Skip to content
Tutorials Center
My learning

Topics

Lesson 28 of 42 ยท Beyond HTTP

Microservices and Transports

Learn NestJS microservices: transports (TCP, Redis, NATS, RabbitMQ, Kafka, gRPC), message vs event patterns, ClientProxy, hybrid apps, with a loopback TCP stand-in.

So far every request to your Nest app has arrived over HTTP. HTTP is a fine default for browsers and public APIs, but between your own services other options are often better: a lightweight binary protocol, a message broker that buffers work while a service is down, or a streaming platform that keeps a history of events. Nest calls the way a message travels a transport, and its microservices package lets you switch the transport while keeping the same controllers, providers, guards, pipes and interceptors.

The big idea is that a Nest microservice is a normal Nest app whose "controllers" respond to patterns (labels attached to messages) instead of URL routes. You change NestFactory.create to NestFactory.createMicroservice, choose a transport, and write handlers with @MessagePattern and @EventPattern.

The real packages need Node, npm and usually a broker, so the Nest snippets are read-only. The runnable part is a stand-in that builds the core of a request-response transport with plain Node on a loopback TCP socket.

A transport is a delivery route

TCP Direct and simple.
Brokers Redis, NATS, RabbitMQ.
Kafka A durable log of events.
gRPC Typed contracts over HTTP/2.

Same Nest code, different wire.

1 / 2

A microservice in Nest

Install @nestjs/microservices. A TCP microservice is created like this:

TypeScript
import { NestFactory } from '@nestjs/core';
import { Transport, MicroserviceOptions } from '@nestjs/microservices';

async function bootstrap() {
  const app = await NestFactory.createMicroservice<MicroserviceOptions>(AppModule, {
    transport: Transport.TCP,
    options: { host: '127.0.0.1', port: 4001 },
  });
  await app.listen();
}
bootstrap();

There is no HTTP server here, so no routes and no @Get(). Handlers are bound to patterns:

TypeScript
@Controller()
export class MathController {
  @MessagePattern({ cmd: 'sum' })
  sum(data: number[]): number {
    return data.reduce((a, b) => a + b, 0);
  }

  @EventPattern('user.created')
  handleUserCreated(data: { id: number; email: string }) {
    // do work, send nothing back
  }
}

A pattern is usually a string ('user.created') or a small object ({ cmd: 'sum' }). Pipes, guards, interceptors and exception filters all work on these handlers, though some details differ (for example, microservice filters throw RpcException instead of HttpException, and you read data with @Payload() and @Ctx() instead of @Body()).

Message patterns vs event patterns

This distinction is the most important one in the lesson.

  • @MessagePattern is request-response. The sender expects a reply, the handler's return value is that reply, and the sender normally waits (with a timeout) for it. Use it when you need the answer: "what is the price of product 5?".
  • @EventPattern is fire-and-forget. The sender announces that something happened and does not wait. Several services can react to the same event, and the emitter does not know or care who. Use it for notifications: "order 17 was paid".

From the calling side you use a client. Register one in a module and inject it:

TypeScript
@Module({
  imports: [
    ClientsModule.register([
      { name: 'MATH_SERVICE', transport: Transport.TCP, options: { host: '127.0.0.1', port: 4001 } },
    ]),
  ],
})
export class AppModule {}

@Injectable()
export class CalcService {
  constructor(@Inject('MATH_SERVICE') private readonly client: ClientProxy) {}

  async total(numbers: number[]) {
    return firstValueFrom(this.client.send({ cmd: 'sum' }, numbers)); // request-response
  }

  announce(user: { id: number; email: string }) {
    this.client.emit('user.created', user); // event
  }
}

send returns an RxJS Observable that emits the reply, which is why firstValueFrom appears: it turns the observable into a promise. emit also returns an observable, and like all cold observables it starts work when subscribed, so in practice you either subscribe or call await firstValueFrom(...) or .subscribe() to make sure the event goes out.

The transports

Transport What it is Typical use
TCP Direct socket between two services Simple internal calls, local development
Redis Redis pub/sub Light messaging when you already run Redis; messages are not stored, so a service that is offline misses them
NATS A fast, lightweight messaging system Low-latency request-response and events between many services
RabbitMQ A broker with queues and acknowledgements Reliable work queues: messages wait until a consumer acknowledges them
Kafka A distributed, durable log with consumer groups High-volume event streams, replaying history, many independent consumers
gRPC Typed remote calls defined in .proto files, over HTTP/2 Strict contracts between services, often in different languages
MQTT A small publish/subscribe protocol IoT devices

Each transport has its own options object (a RabbitMQ URL and queue name, Kafka brokers and a group id, a gRPC proto path and package). The names and exact options differ by version, so check the documentation for the one you use. What stays the same is how you write handlers and clients.

A few practical points on choosing:

  • Reliability. With a plain pub/sub system such as Redis pub/sub, a message sent while nobody listens is lost. Queue-based brokers (RabbitMQ) and log-based ones (Kafka) keep messages until consumed.
  • Ordering and replay. Kafka keeps order per partition and lets a new consumer replay old events. Queues usually do not.
  • Contracts. gRPC gives you generated types and a schema; message patterns over a broker rely on convention, so agree on payload shapes (and version them).
  • Complexity. A broker is one more thing to run, monitor and secure. If one service calls another and you do not need buffering, plain HTTP is often enough.

Hybrid applications

One process can serve HTTP and listen on a microservice transport at the same time:

TypeScript
const app = await NestFactory.create(AppModule);

app.connectMicroservice<MicroserviceOptions>({
  transport: Transport.RMQ,
  options: { urls: ['amqp://localhost:5672'], queue: 'orders' },
});

await app.startAllMicroservices();
await app.listen(3000);

A hybrid app is handy for a service with a public REST API that also consumes events from a queue. One thing to know: global pipes, guards and interceptors registered with app.useGlobal... do not automatically apply to connected microservices unless you pass the right option (inheritAppConfig), so check how your cross-cutting code applies to each side.

Errors and timeouts

A request-response call can fail in three ways: the handler throws, the remote service is unreachable, or no answer arrives. In a microservice handler throw RpcException (or a subclass) so the error travels back in a structured form. On the client, protect every send with a timeout, for example the RxJS timeout operator, so a hung service cannot hang its callers. Retries are risky for non-idempotent work (see Queues and Events): retrying "charge the card" twice is a bug unless the handler is idempotent.

Stand-in: request-response over loopback TCP

Nest's TCP transport sends each message as JSON with a length prefix, so the receiver knows where one message ends in the byte stream. Each request carries an id so a reply can be matched with the request that caused it. This stand-in follows that shape with Node's built-in net module. It is not Nest's implementation (the real one has more fields and features), but the mechanics are the same: a server with a pattern table, a client with send and emit.

The server listens on port 0, so the operating system picks a free port, and everything stays on 127.0.0.1.

Node.js A message-pattern server and client over TCP

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Pay attention to three things in the output. The error reply carries the handler's message back to the caller, which is what RpcException does in Nest. The parallel calls come back in the right order because each reply is matched by id, not by arrival order. And the event produced no response: the sender just continued. The extra send after emit is only there so the demo waits long enough on the same connection (TCP delivers bytes in order) for the server to have processed the event.

Stand-in: why framing exists

TCP is a stream of bytes, not a stream of messages. Two writes can arrive glued together, and one write can arrive in pieces. That is why the length prefix exists. This second stand-in feeds the decoder deliberately awkward chunks without any network at all:

Node.js Length-prefixed framing under awkward chunks

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The decoder returns early whenever it does not have a full message yet and keeps the partial bytes for the next chunk. Note that the length is counted in bytes, not characters: the accented letter in hรฉllo takes two bytes. A frame protocol that counts characters breaks the first time a user sends non-ASCII text.

Choosing, in short

Start with the question "does the caller need the answer now?". If yes, you want request-response (HTTP, gRPC, or a message pattern). If no, you want an event, and a broker with buffering so slow or crashed consumers do not lose messages. Add the technology only when a real requirement (decoupling, load leveling, replay, language independence) calls for it, because every network hop adds latency, failure modes and operations work.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What is the difference between @MessagePattern and @EventPattern?

    A message pattern's return value is sent back to the caller. An event pattern handles a notification and sends nothing back.
  2. 2. A service is offline for one minute. Which transport style loses messages sent during that time?

    Redis pub/sub does not store messages for absent subscribers. Queues and logs keep them until consumed.
  3. 3. Why does a TCP message protocol need framing such as a length prefix?

    TCP does not preserve message boundaries. A length prefix lets the receiver reassemble complete messages.
  4. 4. What does client.send(pattern, data) return in Nest, and how do you usually await it?

    send returns a cold Observable that emits the reply when subscribed. firstValueFrom turns it into a promise.
  5. 5. What is a hybrid application?

    connectMicroservice plus startAllMicroservices lets one app handle both HTTP routes and message patterns.

Summary

  • A Nest microservice is a normal Nest app whose handlers respond to patterns; create it with NestFactory.createMicroservice and pick a transport.
  • @MessagePattern is request-response, @EventPattern is fire-and-forget; callers use ClientProxy.send and emit.
  • Transports: TCP for simple direct calls, Redis and NATS for light messaging, RabbitMQ for reliable queues, Kafka for durable event streams, gRPC for typed contracts.
  • Hybrid apps combine HTTP with microservice listeners in one process.
  • Use RpcException for errors, put timeouts on every send, and be careful with retries on non-idempotent work.
  • A transport's wire format must frame messages and match replies to requests, as the TCP stand-in shows.

Continue with Queues and Events to see how events and background jobs are handled inside and across services.