Merge pull request #2172 from rabbitmq/direct-reply-to

Revise Direct Reply-To

Author: michaelklishin

docs/direct-reply-to.md

@@ -23,10 +23,19 @@ limitations under the License.
 ## Overview {#overview}
 
 Direct reply-to is a feature that allows RPC (request/reply) clients with a design
-similar to that demonstrated in [tutorial 6](/tutorials) to avoid
-declaring a response queue per request.
+similar to that demonstrated in [tutorial 6](/tutorials) without requiring the creation
+of a reply queue.
 
-### Motivation {#motivation}
+:::important
+
+Request-reply implementations where clients use explicitly declared queues, both
+long-lived client named and connection-specific exclusive queues, are
+just as valid as Direct Reply-to, and have their benefits, in particular
+for workloads with long-running tasks
+
+:::
+
+## Motivation {#motivation}
 
 RPC (request/reply) is a popular pattern to implement with a messaging broker
 like RabbitMQ. [Tutorial 6](/tutorials) demonstrates its implementation
@@ -38,22 +47,26 @@ header.
 
 Where does the client's queue come from? The client can
 declare a single-use queue for each request-response pair. But
-this is inefficient; even a transient unreplicated queue can be
+this is inefficient; even an unreplicated queue can be
 expensive to create and then delete (compared with the cost of
 sending a message). This is especially true in a cluster as all
 cluster nodes need to agree that the queue has been created,
 agree on its type, replication parameters, and other metadata.
 
-So alternatively the client can create a long-lived queue for
-its replies. But this can be fiddly to manage, especially if the
-client itself is not long-lived.
+Therefore, the client should create a single reply queue for multiple RPC requests.
+
+The [properties](queues#properties) of this reply queue depend on the use case:
 
-The direct reply-to feature allows RPC clients to receive
-replies directly from their RPC server, without going through a
-reply queue. "Directly" here still means going through the same connection
-and a RabbitMQ node; there is no direct network connection
-between RPC client and RPC server processes.
+* **[Exclusive](queues#exclusive-queues) queues** are commonly used when replies are consumed by a single client and deleted upon disconnection
+* **Non-exclusive long-lived queues** are better suited for long-running tasks, ensuring replies persist even if the client disconnects temporarily
 
+Direct reply-to eliminates the need for a reply queue. This benefits the request-reply
+implementations with short-lived queues and transient responses at the cost
+of giving up all control over how the responses are stored.
+
+With Direct Reply-to, RPC clients will receive replies directly from their RPC server,
+without going through a reply queue. "Directly" here still means going through the same channel
+and a RabbitMQ node; there is no direct network connection between RPC client and RPC server processes.
 
 ## How to Use Direct Reply-to {#usage}
 
@@ -123,3 +136,16 @@ or fail.
     was set.
   </li>
 </ul>
+
+## When to Use Direct Reply-to
+
+While clients should use long lived connections, direct reply-to is ideal for workloads with
+[high connection churn](connections#high-connection-churn), where clients establish a connection
+for a single RPC and disconnect immediately after.
+By avoiding the creation of queue metadata in the [metadata store](metadata-store), direct
+reply-to can reduce overhead and latency.
+
+For workloads with long-lived connections where clients perform multiple RPCs, the performance
+benefits of direct reply-to are not significant compared to [classic queues](classic-queues).
+Modern RabbitMQ versions have optimized classic queues for low latency and minimal resource usage,
+making them similarly efficient in such scenarios.

tutorials/tutorial-six-dotnet.md

@@ -103,9 +103,8 @@ https://github.com/rabbitmq/rabbitmq-tutorials/blob/main/dotnet/RPCClient/RPCCli
 
 ### Correlation Id
 
-In the method presented above we suggest creating a callback queue for
-every RPC request. That's pretty inefficient, but fortunately there is
-a better way - let's create a single callback queue per client.
+Creating a callback queue for every RPC request is inefficient.
+A better way is creating a single callback queue per client.
 
 That raises a new issue, having received a response in that queue it's
 not clear to which request the response belongs. That's when the
@@ -131,7 +130,7 @@ gracefully, and the RPC should ideally be idempotent.
 
 Our RPC will work like this:
 
-  * When the Client starts up, it creates an anonymous exclusive
+  * When the Client starts up, it creates an exclusive
     callback queue.
   * For an RPC request, the Client sends a message with two properties:
     `ReplyTo`, which is set to the callback queue and `CorrelationId`,

tutorials/tutorial-six-elixir.md

@@ -113,9 +113,8 @@ AMQP.Basic.publish(channel,
 
 ### Correlation id
 
-In the method presented above we suggest creating a callback queue for
-every RPC request. That's pretty inefficient, but fortunately there is
-a better way - let's create a single callback queue per client.
+Creating a callback queue for every RPC request is inefficient.
+A better way is creating a single callback queue per client.
 
 That raises a new issue, having received a response in that queue it's
 not clear to which request the response belongs. That's when the
@@ -141,7 +140,7 @@ gracefully, and the RPC should ideally be idempotent.
 
 Our RPC will work like this:
 
-  * When the Client starts up, it creates an anonymous exclusive
+  * When the Client starts up, it creates an exclusive
     callback queue.
   * For an RPC request, the Client sends a message with two properties:
     `reply_to`, which is set to the callback queue and `correlation_id`,

tutorials/tutorial-six-go.md

@@ -114,9 +114,8 @@ err = ch.PublishWithContext(ctx,
 
 ### Correlation Id
 
-In the method presented above we suggest creating a callback queue for
-every RPC request. That's pretty inefficient, but fortunately there is
-a better way - let's create a single callback queue per client.
+Creating a callback queue for every RPC request is inefficient.
+A better way is creating a single callback queue per client.
 
 That raises a new issue, having received a response in that queue it's
 not clear to which request the response belongs. That's when the
@@ -142,7 +141,7 @@ gracefully, and the RPC should ideally be idempotent.
 
 Our RPC will work like this:
 
-  * When the Client starts up, it creates an anonymous exclusive
+  * When the Client starts up, it creates an exclusive
     callback queue.
   * For an RPC request, the Client sends a message with two properties:
     `reply_to`, which is set to the callback queue and `correlation_id`,

tutorials/tutorial-six-java.md

@@ -119,9 +119,8 @@ import com.rabbitmq.client.AMQP.BasicProperties;
 
 ### Correlation Id
 
-In the method presented above we suggest creating a callback queue for
-every RPC request. That's pretty inefficient, but fortunately there is
-a better way - let's create a single callback queue per client.
+Creating a callback queue for every RPC request is inefficient.
+A better way is creating a single callback queue per client.
 
 That raises a new issue, having received a response in that queue it's
 not clear to which request the response belongs. That's when the
@@ -147,9 +146,10 @@ gracefully, and the RPC should ideally be idempotent.
 
 Our RPC will work like this:
 
+  * When the Client starts up, it creates an exclusive
+    callback queue.
   * For an RPC request, the Client sends a message with two properties:
-    `replyTo`, which is set to an anonymous exclusive queue created
-    just for the request, and `correlationId`,
+    `reply_to`, which is set to the callback queue and `correlation_id`,
     which is set to a unique value for every request.
   * The request is sent to an `rpc_queue` queue.
   * The RPC worker (aka: server) is waiting for requests on that queue.

tutorials/tutorial-six-javascript.md

@@ -67,7 +67,7 @@ service that returns Fibonacci numbers.
 In general doing RPC over RabbitMQ is easy. A client sends a request
 message and a server replies with a response message. In order to
 receive a response we need to send a 'callback' queue address with the
-request. We can use the default exchange.
+request.
 Let's try it:
 
 ```javascript
@@ -99,9 +99,8 @@ channel.sendToQueue('rpc_queue', Buffer.from('10'), {
 
 ### Correlation Id
 
-In the method presented above we suggest creating a callback queue for
-every RPC request. That's pretty inefficient, but fortunately there is
-a better way - let's create a single callback queue per client.
+Creating a callback queue for every RPC request is inefficient.
+A better way is creating a single callback queue per client.
 
 That raises a new issue, having received a response in that queue it's
 not clear to which request the response belongs. That's when the
@@ -127,7 +126,7 @@ gracefully, and the RPC should ideally be idempotent.
 
 Our RPC will work like this:
 
-  * When the Client starts up, it creates an anonymous exclusive
+  * When the Client starts up, it creates an exclusive
     callback queue.
   * For an RPC request, the Client sends a message with two properties:
     `reply_to`, which is set to the callback queue and `correlation_id`,

tutorials/tutorial-six-php.md

@@ -112,9 +112,8 @@ $channel->basic_publish($msg, '', 'rpc_queue');
 
 ### Correlation Id
 
-In the method presented above we suggest creating a callback queue for
-every RPC request. That's pretty inefficient, but fortunately there is
-a better way - let's create a single callback queue per client.
+Creating a callback queue for every RPC request is inefficient.
+A better way is creating a single callback queue per client.
 
 That raises a new issue, having received a response in that queue it's
 not clear to which request the response belongs. That's when the
@@ -140,7 +139,7 @@ gracefully, and the RPC should ideally be idempotent.
 
 Our RPC will work like this:
 
-  * When the Client starts up, it creates an anonymous exclusive
+  * When the Client starts up, it creates an exclusive
     callback queue.
   * For an RPC request, the Client sends a message with two properties:
     `reply_to`, which is set to the callback queue and `correlation_id`,

tutorials/tutorial-six-python.md

@@ -120,9 +120,8 @@ channel.basic_publish(exchange='',
 
 ### Correlation id
 
-In the method presented above we suggest creating a callback queue for
-every RPC request. That's pretty inefficient, but fortunately there is
-a better way - let's create a single callback queue per client.
+Creating a callback queue for every RPC request is inefficient.
+A better way is creating a single callback queue per client.
 
 That raises a new issue, having received a response in that queue it's
 not clear to which request the response belongs. That's when the
@@ -148,7 +147,7 @@ gracefully, and the RPC should ideally be idempotent.
 
 Our RPC will work like this:
 
-  * When the Client starts up, it creates an anonymous exclusive
+  * When the Client starts up, it creates an exclusive
     callback queue.
   * For an RPC request, the Client sends a message with two properties:
     `reply_to`, which is set to the callback queue and `correlation_id`,

tutorials/tutorial-six-ruby.md

@@ -112,9 +112,8 @@ exchange.publish(message, routing_key: 'rpc_queue', reply_to: queue.name)
 
 ### Correlation Id
 
-In the method presented above we suggest creating a callback queue for
-every RPC request. That's pretty inefficient, but fortunately there is
-a better way - let's create a single callback queue per client.
+Creating a callback queue for every RPC request is inefficient.
+A better way is creating a single callback queue per client.
 
 That raises a new issue, having received a response in that queue it's
 not clear to which request the response belongs. That's when the
@@ -140,7 +139,7 @@ gracefully, and the RPC should ideally be idempotent.
 
 Our RPC will work like this:
 
-  * When the Client starts up, it creates an anonymous exclusive
+  * When the Client starts up, it creates an exclusive
     callback queue.
   * For an RPC request, the Client sends a message with two properties:
     `:reply_to`, which is set to the callback queue and `:correlation_id`,

tutorials/tutorial-six-spring-amqp.md

@@ -107,7 +107,7 @@ Spring AMQP allows you to focus on the message style you're working
 with and hide the details of message plumbing required to support
 this style. For example, typically the native client would
 create a callback queue for every RPC request. That's pretty
-inefficient so an alternative is to create a single callback
+inefficient, so an alternative is to create a single callback
 queue per client.
 
 That raises a new issue, having received a response in that queue it's