nats://¶

NATS messaging on top of nats.go. Pub/sub, queue groups, request/reply, and JetStream persistence. Connection pooling, TLS, multiple auth modes (username/password, token, NKey seed, .creds file), and reconnect are all built in.

URI shape¶

nats://<subject>?[options]

<subject> is a NATS subject (e.g. orders.created or metrics.*). Wildcards work for consumers; producers should publish on a concrete subject. The servers URI param overrides the component's default server list.

Parameters¶

Connection¶

Reconnect & liveness¶

Auth (mutually exclusive)¶

TLS¶

Producer¶

Consumer¶

Headers¶

JetStream¶

Body shape¶

Producer¶

• In body — published verbatim (BodyAsBytes()).
• In headers — passed through the include/exclude filter and set as NATS headers (NATS 2.2+ feature).
• InOut exchanges trigger a request/reply (nc.Request); the reply becomes the In body.

Consumer¶

• In body — message payload bytes.
• In headers:

Plus any pass-filtered NATS headers.

When the inbound message carries a reply and replyToDisabled=false, the processor's output body is auto-published back to that subject.

Examples¶

Pub/sub consumer:

- id: events
  from: nats://orders.>?queueName=svc&servers=nats://nats:4222
  steps:
    - to: direct://process-order

Request/reply producer (InOut):

- setBody:
    starlang: '"{\"sku\":\"" ++ headers["sku"] ++ "\"}"'
- to: nats://inventory.lookup?requestTimeout=2s&servers=nats://nats:4222
# After: ex.In() holds the reply body.

Auto-reply server (treat the route as an RPC implementation):

- id: lookup
  from: nats://inventory.lookup
  steps:
    - to: postgres://inventory/findOne
    # the body produced here is auto-published to msg.Reply

JetStream durable pull subscription:

- from: nats://orders.>?jetstreamEnabled=true&jetstreamName=ORDERS&durableName=order-processor&pullSubscription=true&ackPolicy=explicit&maxDeliver=5

TLS + .creds auth:

- to: nats://metrics.app?servers=tls://nats.prod:4222&credentialsFilePath=/etc/nats/svc.creds&secure=true&tlsCAFile=/etc/ssl/nats-ca.pem

Behavior notes¶

• Connection pooling. Endpoints with identical connection parameters share a single *nats.Conn (connection_pool.go).
• noEcho. Set on shared subjects where the publisher and subscriber sit on the same conn — prevents your own publishes from echoing back as messages.
• Auth modes are mutually exclusive. Pick one of credentials file / user+password / token / NKey seed. Mixing them errors at parse time.
• JetStream defaults. pullSubscription=true, ackPolicy=explicit is the standard durable-worker pattern. Explicit ack is the processor returning nil; on processor error the message is nak'd (redelivered per maxDeliver).
• Header filter is symmetric. The include/exclude regexes apply on outbound (Helix → NATS) and inbound (NATS → Helix) directions, so one rule governs both sides.
• Producer flush. flushConnection=true (default) ensures bytes hit the wire before Process returns. Disable for higher throughput at the cost of lost-on-crash semantics.

Source¶

• pkg/component/nats/nats.go — Component, Endpoint.
• pkg/component/nats/{producer,consumer}.go — pub/sub paths.
• pkg/component/nats/{jetstream}.go — JetStream variants.
• pkg/component/nats/{config,security,connection_pool,headers}.go — config parsing, TLS+auth, pooling, header filter.

See also¶

• Other brokers: kafka://, amqp://, rabbitmq://, mqtt://