caddy_nats_bridge package - github.com/CoverWhale/caddy-nats-bridge - Go Packages
README ¶ Caddy-NATS-Bridge NOTE: This package is originally based on https://github.com/codegangsta/caddy-nats , which has greatly inspired me to work on this topic. Because we want to use this package in our core infrastructure very heavily and I had some specific ideas around the API, I created my own package based on the original one. tl;dr: Pick whichever works for you - Open Source rocks :) caddy-nats-bridge is a caddy module that allows the caddy server to interact with a NATS server in meaningful ways.
Main Features : Connect NATS and HTTP in all possible directions (we call this Bridging ) experimental: offload large HTTP bodies to JetStream NEW in 0.7: publish Caddy Log messages to NATS The initial of this project was 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.
This extension supports multiple patterns: publish/subscribe, fan in/out, and request reply. Additionally, this extension supports using NATS as Log output. Caddy-NATS-Bridge Installation Getting Started - NATS as Log Output Getting Started - Bridging HTTP <-> NATS Connecting to NATS Logging to NATS Bridging HTTP <-> NATS NATS -> HTTP via subscribe Placeholders for subscribe Queue Groups FAQ: HTTP URL Parameters HTTP -> NATS via nats_request (interested about response) Placeholders for nats_request Extra headers for nats_request HTTP -> NATS via nats_publish (fire-and-forget) Placeholders for nats_publish Extra headers for nats_publish large HTTP payloads with store_body_to_jetstream Development Installation To use caddy-nats-bridge , simply run the xcaddy build tool to create a caddy-nats-bridge compatible caddy server. # Prerequisites - install go and xcaddy brew install go go install github.com/caddyserver/xcaddy/cmd/xcaddy@latest # now, build your custom Caddy server (NOTE: path to xcaddy might differ on your system). ~/go/bin/xcaddy build --with github.com/sandstorm/caddy-nats-bridge Getting Started - NATS as Log Output (supported since version 0.7.0 of this extension).
Getting up and running with caddy-nats-bridge is pretty simple: First install NATS and make sure the NATS server is running: nats-server 💡 To try this example, cd examples/logs; ./build-run.sh Caddyfile build-run.sh Then create and run your Caddyfile: # run with: ./caddy run --config Caddyfile { nats { url 127.0.0.1:4222 clientName "My Caddy Server" } } http://127.0.0.1:8888 { log { output nats my.log.subject } respond "Hello World" } Then, you can can listen to my.log with the nats CLI, and do a HTTP Request to see it in the Logs: nats subscribe 'my.log.>' # in another console curl http://127.0.0.1:8888 What has happened here?
You sent a HTTP request to Caddy the access log is routed to NATS. Getting Started - Bridging HTTP <-> NATS This is a more advanced scenario, but still getting up and running with caddy-nats-bridge is pretty simple: First install NATS and make sure the NATS server is running: nats-server 💡 To try this example, cd examples/getting-started; ./build-run.sh Caddyfile build-run.sh Then create and run your Caddyfile: # run with: ./caddy run --config Caddyfile { nats { url 127.0.0.1:4222 clientName "My Caddy Server" # listens to "datausa.[drilldowns].[measures]" -> calls internal URL # nats req "datausa.Nation.Population" "" subscribe datausa.> GET http://127.0.0.1:8888/datausa/{nats.request.subject.asUriPath.1}/{nats.request.subject.asUriPath.2} } } http://127.0.0.1:8888 { # internal URL: "/datausa/[drilldowns]/[measures]" handle /datausa/* { # Reference for placeholders: https://caddyserver.com/docs/json/apps/http/#docs rewrite * /api/data?drilldowns={http.request.uri.path.1}&measures={http.request.uri.path.2} reverse_proxy https://datausa.io { header_up Host {upstream_hostport} } } route /weather/* { nats_request cli.weather.{http.request.uri.path.1} } } Then, you can do a request with the nats CLI, and see that it is automatically converted to a HTTP Request: nats req "datausa.Nation.Population" "" What has happened here?
You sent a NATS request to the topic datausa.Nation.Population the Caddy-Nats-Bridge has subscribed to the above topic, and routed the request to the internal URL http://127.0.0.1:8888/datausa/Nation/Population The rest is standard Caddy configuration - triggering the API call https://datausa.io/api/data?drilldowns=Nation&measures=Population The HTTP response is then converted to a NATS reply. As a second example, you can start a fake NATS weather service using: nats reply 'cli.weather.>' --command "curl -s wttr.in/{{2}}?format=3" You can query this service via nats request cli.weather.Dresden "" to retrieve the current weather forecast.
Because of the nats_request rule in the Caddyfile above, you can also request http://127.0.0.1:8888/weather/Dresden in your browser: You sent a HTTP request to Caddy This has been forwarded to the NATS topic cli.weather.Dresden , which is responded by the nats reply tool above. The NATS response is converted to a HTTP response. Connecting to NATS To connect to nats , use the nats global option in your Caddyfile with the URL of the NATS server: { nats [alias] { url nats://127.0.0.1:4222 } } The alias is a server-reference which is relevant if you want to connect to two NATS servers at the same time.
If omitted, the serverAlias default is used. To connect to multiple servers (NATS Cluster), separate them with , in the url parameter. The following connection options are supported for a server: url : URL(s) pointing to a NATS cluster. nats:// , tls:// , ws:// and wss:// URLs are all supportted, if the NATS cluster supports them. multiple comma separated URLs can be specified, but they must be all pointing to the same NATS cluster.
Authentication Options (only one of the ones below may be specified; in descending precedence): userCredentialFile a User Credential file as generated by nsc tool. You need this if you use the Decentralized JWT Authentication/Authorization of NATS. nkeyCredentialFile an NKEY File as generated by nk -gen user -pubout . You need this if you use NKEY Authentication of NATS. (other authentication options are not supported right now, but we can add them if needed) clientName name of the NATS client - this is useful for monitoring. inboxPrefix .
The "inbox" is the response subject for request/reply messaging. Your server operator might tell you that you need to use a different inbox prefix than the default _INBOX for security reasons . Configuration with all configuration options is specified below: { nats [alias] { url nats://127.0.0.1:4222 # either userCredentialFile or nkeyCredentialFile can be specified. If both are specified, userCredentialFile # takes precedence. userCredentialFile /path/to/file.creds nkeyCredentialFile /path/to/file.nk clientName MyClient inboxPrefix _INBOX_custom } } Logging to NATS Simple usage: { nats { url nats://127.0.0.1:4222 } } my-domain.com { # will use the "default" NATS server defined above log nats my.log.subject } You can also specify the NATS server alias to use for logging; in the example below "myNatsServer": { nats { url nats://127.0.0.1:4222 } nats myNatsServer { url nats://127.0.0.1:5444 } } my-domain.com { # will use the "myNatsServer" NATS server defined above log nats myNatsServer my.log.subject } This concept is fully pluggable; you can configure the log output any way you like in Caddy.
Bridging HTTP <-> NATS The module works if you want to bridge HTTP -> NATS , and also NATS -> HTTP - both in unidirectional, and in bidirectional mode. NATS -> HTTP via subscribe caddy-nats-bridge supports subscribing to NATS subjects in a few different flavors, depending on your needs: forward a NATS message to an HTTP endpoint, and replying the HTTP response back to the NATS sender. forward a NATS message to an HTTP endpoint, without interest for the response (f.e. triggering a webhook).
The two cases above are bot
The rest of this page is on the live site.