Skip to content

Ask a service for a reply over NATS ​

Use @chojs/vendor-nats when a caller needs an answer from a running message service. Each complete CHO topic becomes a NATS subject. If several instances subscribe in the same queue group, NATS selects one to handle each request.

Run a shelf lookup ​

Start a local Core NATS server in a separate terminal. If you use Docker, this command binds the service to loopback. Leave it running while you try the example.

sh
docker run --rm -p 127.0.0.1:4222:4222 nats:2

The adapter and reply headers ship in 3.5.0. To follow the example with Deno, save the example below as examples/library-nats.ts in the CHO checkout. The workspace already declares the Deno transport. Run this command from the repository root.

sh
deno run --allow-net=127.0.0.1:4222 examples/library-nats.ts
ts
import { connect } from "@nats-io/transport-deno";
import {
  ChoMessage,
  type ChoMessageContext,
  ChoMessageReply,
  Controller,
  Module,
  Subscribe,
} from "@chojs/message";
import { ERROR_HEADERS, NatsLinker } from "@chojs/vendor-nats";

class UnknownCopy extends Error {}

@Controller({ topic: "books" })
class Shelves {
  private readonly shelves = new Map([["copy-17", "B2"]]);

  @Subscribe("locate")
  locate(ctx: ChoMessageContext) {
    const copy = ctx.text();
    const shelf = this.shelves.get(copy);
    if (shelf === undefined) throw new UnknownCopy(copy);
    return new ChoMessageReply({ copy, shelf }, {
      headers: { "Content-Type": "application/json" },
    });
  }
}

@Module({ controllers: [Shelves] })
class Library {}

const app = await ChoMessage.create(Library, {
  linker: new NatsLinker({
    connect: () => connect({ servers: "127.0.0.1:4222" }),
    queue: "library",
    errorReply: (error) =>
      error instanceof UnknownCopy
        ? { code: 404, description: "Unknown copy" }
        : undefined,
  }),
});

try {
  await app.start();
  const nc = app.linked.instance;
  for (const copy of ["copy-17", "copy-99"]) {
    const reply = await nc.request("books.locate", copy, { timeout: 2000 });
    const code = reply.headers?.get(ERROR_HEADERS.code);
    if (code) {
      console.log(copy, code, reply.headers?.get(ERROR_HEADERS.description));
    } else {
      const { shelf } = reply.json<{ shelf: string }>();
      console.log(copy, shelf, reply.headers?.get("Content-Type"));
    }
  }
} finally {
  await app.close();
}

The service subscribes to books.locate. Once start() resolves, its subscriptions are ready and the example uses the active connection to ask about two copies. A separate application can make the same request using its own connection. Expect these lines on stdout.

text
copy-17 B2 application/json
copy-99 404 Unknown copy

Read the service-error header before decoding the payload. The missing copy produces a reply with an empty body and a 404 service code. A request that times out or has no responder rejects at the NATS client. When finished, stop the example broker with Ctrl+C.

Choose between a request and an event ​

Subscription outcomeCaller uses nc.requestPublisher uses nc.publish
Returns a valueReceives the encoded payload and any reply headersThe adapter drops the reply
Returns nothingReceives an empty replyProcessing ends
Fails after CHO error handlingReceives a service-error replyThe event is lost. The failure appears in the adapter's debug output when enabled

Core NATS delivers at most once. Use a request when the caller needs to know the outcome. For durable events on the same connection, configure JetStream streams and consumers. For typed requests across services, share a message contract and give linker.sender to ChoMessageClient. The NATS sender uses a default request timeout of 1000 ms.

Map a failure for the caller ​

An @Catch that returns a fallback value produces an ordinary successful reply. If a ReplyError reaches the adapter, its code and description go directly to the requester. For other failures, errorReply(error, message) can supply { code, description, value? }, as the example does for UnknownCopy. Returning undefined selects the default empty service-error reply. Invalid input rejected by CHO validation gets 400 Bad Request and other failures get 500 Internal Error. Enable the adapter's debug output to see the original exception.

Configure a worker ​

SettingWhat it controls
connectRequired callback that opens the connection on start(). Set servers, credentials, TLS and reconnect policy on the transport
queueRequired queue group. Give replicas of one service the same name to divide the work
concurrencyIn-flight handlers per subject. The default of 1 preserves order within a subject. Other subjects can progress independently
onFatalCalled after a permanent connection closure or subscription failure. The default throws. Use this hook for process-level recovery

Use @nats-io/transport-deno on Deno and @nats-io/transport-node on Node.js or Bun. For a WebSocket listener, supply wsconnect from @nats-io/nats-core. The linker owns the supplied connection and drains pending work and replies on app.close().

For incoming messages, ctx.headers contains the first value of each header and ctx.key is undefined. If a handler needs repeated headers or the reply address, read (ctx.native as NatsNative).message, importing the type from @chojs/vendor-nats. Set CHO_DEBUGLOG=cho:nats,cho:message to trace subscriptions and deliveries. On Deno, add --allow-env=CHO_DEBUGLOG to the run command.

Choose who receives a request ​

Run two instances with the same queue when they should share work. Send one request and observe a single response. Use separate subject or queue arrangements for independent subscribers that must each observe an event. For replay after downtime, choose JetStream.

Handle a closed connection or rejected subscription ​

The adapter stops by itself in two cases: the connection closed and the client does not connect again (CHO_NATS_CONNECTION_CLOSED), or a subscription failed, as one the server refuses does (CHO_NATS_SUBSCRIPTION_FAILED). It then finishes the messages in hand, closes what is still open, and calls onFatal with the error (its cause is the error of the client).

nats.js connects again by itself: 10 times by default, 2 seconds apart. Give maxReconnectAttempts: -1 to connect for a client that never gives up.

Without onFatal, the error is thrown: an uncaught exception, which ends the process, so that what runs the application starts it again. Give onFatal to do something else:

ts
new NatsLinker({
  connect,
  queue: "shop",
  onFatal: async (error) => {
    logger.fatal(error);
    await app.close(); // the adapter is stopped already: this ends the rest
    process.exit(1);
  },
});

Read the native NATS message ​

ctx.native is the message of the client library, in a NatsNative:

ts
import type { NatsNative } from "@chojs/vendor-nats";

@Subscribe("created")
created(ctx: ChoMessageContext) {
  const { message } = ctx.native as NatsNative;
  message.subject; // "shop.orders.created"
  message.reply; //   where a reply goes, when one was asked
  message.headers?.values("Trace"); // every value of a header
}

ctx.headers has the first value of each header, and ctx.key is undefined: NATS has no key. Code that reads ctx.native runs on this adapter only.