Skip to main content

Request-Reply

Request-Reply is a communication pattern that brings synchronous communication to NATS's asynchronous messaging system. It allows a client to send a request and wait for a response, building RPC-style interactions on top of the core publish-subscribe mechanism.

For a runnable, step-by-step treatment, see the request-reply chapter in the Core NATS deep dive.

How Request-Reply Works​

Under the hood, request-reply uses NATS's publish-subscribe with these steps:

  1. Client creates a unique reply subject (inbox)
  2. Client subscribes to the reply subject
  3. Client publishes the request with the reply subject
  4. Service receives the request and sees the reply subject
  5. Service publishes the response to the reply subject
  6. Client receives the response

This pattern is so common that NATS clients provide a simplified request() method that handles all these steps automatically.

In the animation above:

  • The orange arrow shows the request flowing from client to service
  • The green dashed arrow shows the reply flowing back
  • This demonstrates the bidirectional, synchronous nature of request-reply

Basic Request-Reply​

# Terminal 1: Set up a service that responds to time requests
nats reply time --command "date"

# Terminal 2: Make a request
nats request time ""

# Output: Wed Nov 15 10:23:45 PST 2023

Handling Timeouts​

Timeouts are crucial in request-reply to prevent indefinite waiting. All NATS clients support configurable timeouts:

# Request with 2 second timeout
nats request service "" --timeout 2s

# If no response within 2 seconds, returns error

Multiple Responders​

When multiple services subscribe to the same request subject, NATS supports two distinct patterns depending on whether queue groups are used:

Pattern 1: All Services Respond (Scatter-Gather)​

If each app creates a "service" subscription, all of them will receive the request and all can respond. The client can collect multiple responses:

In this pattern, one request is broadcast to all three services (A, B, C), and all three send responses back. This is useful for:

  • Gathering data from multiple sources
  • Aggregating results from distributed services
  • Querying multiple replicas for consensus

Pattern 2: One Service Responds (Load Balancing)​

With queue groups, only one service receives the request and responds, providing automatic load balancing for scalability:

In this pattern, NATS selects one service from the queue group (Service B in this example) to handle the request. This provides:

  • Automatic load distribution across service instances
  • Horizontal scalability
  • Built-in failover (if one service is down, another handles it)

By default, the request() method returns the first response and drops the rest. The example below starts multiple responders and shows the client receiving a single reply. To gather every response, subscribe to a reply inbox directly and read messages until a timeout instead of calling request().

# Terminal 1: First service
nats reply service "Response from service 1"

# Terminal 2: Second service
nats reply service "Response from service 2"

# Terminal 3: Make request (nats reply puts both in a shared queue group,
# so one instance answers and the client gets a single reply)
nats request service ""

No Responders Detection​

NATS will detect when no services are available to handle a request. When there are no subscribers for the request subject, NATS server will return a "no responders" error immediately:

#!/bin/bash

# Request to a subject with no subscribers
nats request no.such.service "test"

# Error: no responders available for request

Request with Headers​

NATS supports headers in request-reply, enabling metadata exchange:

#!/bin/bash

# Send request with headers
nats request service "data" -H "X-Request-ID:123" -H "X-Priority:high"

Best Practices​

Timeout Strategy​

  • Set appropriate timeouts: Too short may miss valid responses, too long blocks unnecessarily
  • Consider network latency: Add buffer for network round-trip time
  • Implement retry logic: For transient failures

Error Handling​

  • Always handle timeouts: Don't assume responses will arrive
  • Check for no responders: React appropriately when services are unavailable
  • Validate responses: Ensure response data is valid before processing

Service Design​

  • Idempotent operations: Requests might be retried
  • Lightweight processing: Long operations should be async
  • Health checks: Implement service health endpoints
  • Graceful shutdown: Drain pending requests before shutting down

Performance​

  • Connection pooling: Reuse connections for multiple requests
  • Inbox reuse: Modern clients reuse inbox subjects for efficiency
  • Batch operations: Group related requests when possible

Request-Reply vs Publish-Subscribe​

Choose request-reply when you need:

  • Synchronous communication: Wait for a response before continuing
  • Service discovery: Automatic "no responders" detection
  • Load balancing: Combined with queue groups
  • RPC-style APIs: Traditional request-response patterns

Use publish-subscribe when you need:

  • Fire-and-forget: No response needed
  • Multiple consumers: All subscribers should receive the message
  • Event streaming: Continuous flow of events
  • Decoupled systems: Publishers shouldn't know about subscribers

Try It Yourself​

Create a simple calculator service:

#!/bin/bash

# Terminal 1: Calculator service (adds the two numbers in the request body)
nats reply calc.add --command "sh -c \"echo \$NATS_REQUEST_BODY | awk '{print \$1 + \$2}'\""

# Terminal 2: Make calculations
nats request calc.add "5 3"
# Output: 8
nats request calc.add "10 7"
# Output: 17

Next steps​