Repository files navigation

caddy-nats is a caddy module that allows the caddy server to interact with aNATS 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 NATSin a pragmatic and straightforward way. If you've been wanting to use NATS, buthave some use cases that still need to use HTTP, this may be a really goodoption for you.

To usecaddy-nats, simply run thexcaddy build tool to create acaddy-nats compatible caddy server.

xcaddy build --with github.com/codegangsta/caddy-nats

Getting up and running withcaddy-nats is pretty simple:

Firstinstall 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 builtcaddy server with this Caddyfile, you canthen run thenats cli tool to test it out:

nats req hello""

To connect tonats, simply use thenats global option in your Caddyfile:

{nats}

This will connect to the currently selectednats context that thenats CLIuses. If there is nonats context available, it will connect to the defaultnats server URL.

You can view yournats context information via thenats cli:

nats context list

We recommend connecting to a specific context:

{nats <context>}

caddy-nats supports subscribing to NATS subjects in a few different flavors,depending on your needs.

Allsubscribe based directives (subscribe,reply,queue_subscribe,queue_reply) support the followingcaddy placeholders in themethod andurl 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 <subject> <method> <url>

subscribe will subscribe to the specific NATS subject (wildcards aresupported) and forward the NATS payload to the specified URL inside the caddyweb server. This directive does not care about the HTTP response, and isgenerally fire and forget.

Subscribe to an event stream in NATS and call an HTTP endpoint:

{nats {subscribe events.> POST https://localhost/nats_events/{nats.path.1:}  }}

reply <subject> <method> <url>

reply will subscribe to the specific NATS subject and forward the NATSpayload to the specified URL inside the caddy web server. This directive willthen respond back to the nats message with the response body of the HTTPrequest.

Respond to thehello.world NATS subject with the response of the/hello/world endpoint.

{nats {reply hello.world GET https://localhost/hello/world  }}

queue_subscribe <subject> <queue> <method> <url>

queue_subscribe operates the same way assubscribe, but subscribes under a NATSqueue group

Subscribe to a worker queue:

{nats {queue_subscribe jobs.* workers_queue POST https://localhost/{nats.path}  }}

queue_reply <subject> <queue> <method> <url>

queue_reply operates the same way asreply, but subscribes under a NATSqueue group

Subscribe to a worker queue, and respond to the NATS message:

{nats {queue_reply jobs.* workers_queue POST https://localhost/{nats.path}  }}

caddy-nats also supports publishing to NATS subjects when an HTTP call ismatched withincaddy, this makes for some very powerful bidirectionalpatterns.

Allpublish based directives (nats_publish,nats_request) support the followingcaddy placeholders in thesubject 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, sincepublish based directives are caddy http handlers, you also get access to allcaddy http placeholders.

nats_publish [<matcher>] <subject> {timeout <timeout-ms>}

nats_publish publishes the request body to the specified NATS subject. Thishttp handler is not a terminal handler, which means it can be used asmiddleware (Think logging and events for specific http requests).

Publish an event before responding to the http request:

localhost {route /hello {nats_publish events.hellorespond"Hello, world"  }}

nats_request [<matcher>] <subject> {timeout <timeout-ms>}

nats_request publishes the request body to the specified NATS subject, andwrites the response of the NATS reply to the http response body.

Publish an event before responding to the http request:

localhost {route /hello/* {nats_request hello_service.{nats.subject.1}  }}

While this is currently functional and useful as is, here are the things I'd like to add next:

• Add more examples in the /examples directory
• Add Validation for all caddy modules in this package
• Add godoc comments
• Support mapping nats headers and http headers for upstream and downstream
• Customizable error handling
• Jetstream support (for all that persistence babyyyy)
• nats KV for storage