Text of pkg.go.dev › codeberg.org › hsctech › caddy-nats as Styx crawled it on Nov 20, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

caddynats package - codeberg.org/hsctech/caddy-nats - Go Packages

README ¶ Caddy-NATS caddy-nats is a caddy module that allows the caddy server to interact with a NATS server. This extension supports multiple patterns: publish/subscribe, fan in/out, and request reply. The purpose of this project is to better bridge HTTP based services with NATS in a pragmatic and straightforward way. If you've been wanting to use NATS, but have some use cases that still need to use HTTP, this may be a really good option for you.

Installation To use caddy-nats , simply run the xcaddy build tool to create a caddy-nats compatible caddy server. xcaddy build --with codeberg.org/hsctech/caddy-nats Alternatively, download a prebuilt caddy binary with caddy-nats compiled in from the releases page . Each release is built against the caddy release of the same version (e.g. release v2.11.4 is built against caddy v2.11.4 ). Getting Started Getting up and running with caddy-nats is pretty simple: First install NATS and make sure the NATS server is running: nats-server Then create your Caddyfile: { nats { reply hello GET https://localhost/hello } } localhost { route /hello { respond "Hello, world" } } After running your custom built caddy server with this Caddyfile, you can then run the nats cli tool to test it out: nats req hello "" Connecting to NATS To connect to nats , simply use the nats global option in your Caddyfile: { nats } This will connect to the currently selected nats context that the nats CLI uses.

If there is no nats context available, it will connect to the default nats server URL. You can view your nats context information via the nats cli: nats context list We recommend connecting to a specific context: { nats <context> } Subscribing to a NATS subject caddy-nats supports subscribing to NATS subjects in a few different flavors, depending on your needs. Subscribe Placeholders All subscribe based directives ( subscribe , reply , queue_subscribe , queue_reply , stream_subscribe ) support the following caddy placeholders in the method and url arguments: {nats.path} : The subject of this message, with dots "." replaced with a slash "/" to make it easy to map to a URL. {nats.path.*} : You can also select a segment of a path ex: {nats.path.0} or a subslice of a path: {nats.path.2:} or {nats.path.2:7} to have ultimate flexibility in what to forward onto the URL path. subscribe Syntax subscribe <subject> <method> <url> subscribe will subscribe to the specific NATS subject (wildcards are supported) and forward the NATS payload to the specified URL inside the caddy web server.

This directive does not care about the HTTP response, and is generally fire and forget. Example Subscribe to an event stream in NATS and call an HTTP endpoint: { nats { subscribe events.> POST https://localhost/nats_events/{nats.path.1:} } } reply Syntax reply <subject> <method> <url> reply will subscribe to the specific NATS subject and forward the NATS payload to the specified URL inside the caddy web server. This directive will then respond back to the nats message with the response body of the HTTP request.

Example Respond to the hello.world NATS subject with the response of the /hello/world endpoint. { nats { reply hello.world GET https://localhost/hello/world } } queue_subscribe Syntax queue_subscribe <subject> <queue> <method> <url> queue_subscribe operates the same way as subscribe , but subscribes under a NATS queue group Example Subscribe to a worker queue: { nats { queue_subscribe jobs.* workers_queue POST https://localhost/{nats.path} } } queue_reply Syntax queue_reply <subject> <queue> <method> <url> queue_reply operates the same way as reply , but subscribes under a NATS queue group Example Subscribe to a worker queue, and respond to the NATS message: { nats { queue_reply jobs.* workers_queue POST https://localhost/{nats.path} } } stream_subscribe Syntax stream_subscribe <stream> <durable> <subject-filter> <method> <url> { on_error ack|nak|term } stream_subscribe attaches to a pre-existing JetStream stream and durable pull consumer — caddy-nats never creates or mutates streams or consumers; they are managed externally ( nats CLI, IaC) and caddy refuses to start when they are missing.

Each message is forwarded to the specified URL exactly like subscribe , but a 2xx upstream response acks the message and any failure — an unroutable URL, no matching server, or a non-2xx response — applies the on_error policy instead of silently dropping the message. Messages published while caddy is down are delivered when it comes back, and multiple caddy instances sharing the durable name load-balance. Redelivery timing and retry caps ( AckWait , MaxDeliver , Backoff ) live in the externally-managed consumer config, not the Caddyfile.

The optional on_error policy settles messages whose handling fails, whether before dispatch or in the upstream response: nak (default): redeliver per the consumer config ( AckWait , MaxDeliver , Backoff ). term : never redeliver — poison messages stop after the first failure. ack : accept the loss — explicit at-most-once delivery (e.g. best-effort audit). Example Consume order events durably and call an HTTP endpoint: { nats { stream_subscribe EVENTS caddy events.> POST https://localhost/hooks/{nats.path.1:} } } With the matching external infrastructure created once via the nats CLI: nats stream add EVENTS --subjects 'events.>' --defaults nats consumer add EVENTS caddy --filter 'events.>' --ack explicit --max-deliver 5 --defaults See examples/stream-subscribe for a worked example.

Publishing to a NATS subject caddy-nats also supports publishing to NATS subjects when an HTTP call is matched within caddy , this makes for some very powerful bidirectional patterns. Publish Placeholders All publish based directives ( nats_publish , nats_request ) support the following caddy placeholders in the subject argument: {nats.subject} : The path of the http request, with slashes "/" replaced with dots "." to make it easy to map to a NATS subject. {nats.subject.*} : You can also select a segment of a subject ex: {nats.subject.0} or a subslice of the subject: {nats.subject.2:} or {nats.subject.2:7} to have ultimate flexibility in what to forward onto the URL path.

Additionally, since publish based directives are caddy http handlers, you also get access to all caddy http placeholders . nats_publish Syntax nats_publish [<matcher>] <subject> { timeout <timeout-ms> persistent } nats_publish publishes the request body to the specified NATS subject. This http handler is not a terminal handler, which means it can be used as middleware (Think logging and events for specific http requests).

With persistent , the publish goes through JetStream: the handler waits for the server's pub-ack (bounded by timeout , default 10000 ms) before the chain continues, so the event is confirmed stored in a stream. A publish no stream captures fails the request with an error. Streams are managed externally ( nats CLI, IaC) — the module never provisions them. See examples/persistent-publish . persistent is not available on nats_request ; request-reply stays on core NATS.

Example Publish an event before responding to the http request: localhost { route /hello { nats_publish events.hello respond "Hello, world" } } nats_request Syntax nats_request [<matcher>] <subject> { timeout <timeout-ms> } nats_request publishes the request body to the specified NATS subject, and writes the response of the NATS reply to the http response body. Example Publish an event before responding to the http request: localhost { route /hello/* { nats_request hello_service.{nats.subject.1} } } Mapping headers between HTTP and NATS caddy-nats bridges headers across the HTTP/NATS boundary in all four directions: NATS message headers are copied onto the synthesized HTTP request ( subscribe , reply , queue_subscribe , queue_reply , stream_subscribe ) HTTP response headers are copied onto the NATS reply ( reply , queue_reply ) HTTP request headers are copied onto the NATS message ( nats_publish , nat

The rest of this page is on the live site.