{"id":37049223,"url":"https://github.com/wshaddix/http-nats-proxy","last_synced_at":"2026-01-14T05:43:27.017Z","repository":{"id":29194489,"uuid":"116494145","full_name":"wshaddix/http-nats-proxy","owner":"wshaddix","description":"A proxy service that translates http requests to nats messages","archived":false,"fork":false,"pushed_at":"2024-11-21T20:57:24.000Z","size":126,"stargazers_count":20,"open_issues_count":3,"forks_count":7,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-10-22T16:54:18.825Z","etag":null,"topics":["docker","http-nats-proxy","microservice","nats","nats-messaging","nats-server","natsio","proxy-service","reverse-proxy"],"latest_commit_sha":null,"homepage":null,"language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wshaddix.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-01-06T15:34:57.000Z","updated_at":"2025-10-08T22:21:13.000Z","dependencies_parsed_at":"2023-01-14T14:20:26.867Z","dependency_job_id":null,"html_url":"https://github.com/wshaddix/http-nats-proxy","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/wshaddix/http-nats-proxy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wshaddix%2Fhttp-nats-proxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wshaddix%2Fhttp-nats-proxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wshaddix%2Fhttp-nats-proxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wshaddix%2Fhttp-nats-proxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wshaddix","download_url":"https://codeload.github.com/wshaddix/http-nats-proxy/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wshaddix%2Fhttp-nats-proxy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28411205,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T05:26:33.345Z","status":"ssl_error","status_checked_at":"2026-01-14T05:21:57.251Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","http-nats-proxy","microservice","nats","nats-messaging","nats-server","natsio","proxy-service","reverse-proxy"],"created_at":"2026-01-14T05:43:26.491Z","updated_at":"2026-01-14T05:43:27.011Z","avatar_url":"https://github.com/wshaddix.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# http-nats-proxy\r\n\r\nA proxy service that converts http requests to [NATS](https://nats.io) messages.\r\n\r\n## Purpose\r\n\r\nThis proxy service is designed to be ran in a docker container and will translate all of your http based api calls (REST\r\nendpoints). It will translate the http route to a [NATS](https://nats.io) message and will send the message as a request\r\ninto the NATS messaging system. Once a reply has been returned it is written back to the http response. The primary use\r\ncase for this service is when you have an ecosystem of microservices that communicate via NATS but you want http REST\r\napi clients to be able to communicate to those services as a typical http REST api client.\r\n\r\n## Features\r\n\r\n### Routing\r\n\r\nWhen an http request is received the http-nats-proxy will take the request path and replace every forward slash ('/')\r\nwith a period ('.'). It will then prefix that with the http verb that was used (get, put, post, delete, head, etc.).\r\nFinally it will convert the entire string to lowercase. This becomes your NATS subject where the message will be sent.\r\nFor example, the http request of `GET http://localhost:5000/test/v1/customer?id=1234\u0026show-history=true` will result in a\r\nNATS message subject of `get.test.v1.customer`\r\n\r\n### HTTP Request Format Translation\r\n\r\nWhen an http request is received, the http-nats-proxy will extract the headers, cookies, query string parameters and the\r\nbody of the request and create a NATS message. The NATS message that goes into the messaging system will be a json\r\nserialized object that has the following structure:\r\n\r\n```\r\n{\r\n    \"cookies\": {\r\n        \"key1\": \"value1\",\r\n        \"key2\": \"value2\"\r\n    },\r\n    \"errorMessage\", \"\",                     \u003c--- can be set by microservices and pipeline steps\r\n    \"extendedProperties\": {                 \u003c--- can be set by microservices and pipeline steps\r\n        \"key1\": \"value1\",\r\n        \"key2\": \"value2\"\r\n    },\r\n    \"queryParams\": {\r\n        \"key1\": \"value1\",\r\n        \"key2\": \"value2\"\r\n    },\r\n    \"requestBody\": \"\",\r\n    \"requestHeaders\": {\r\n        \"key1\": \"value1\",\r\n        \"key2\": \"value2\"\r\n    },\r\n    \"responseBody\": \"\",                     \u003c--- can be set by microservices and pipeline steps\r\n    \"responseHeaders\": {                    \u003c--- can be set by microservices and pipeline steps\r\n        \"key1\": \"value1\",\r\n        \"key2\": \"value2\"\r\n    },\r\n    \"responseStatusCode\": -1,               \u003c--- can be set by microservices and pipeline steps\r\n    \"shouldTerminateRequest\": true|false    \u003c--- can be set by microservices and pipeline steps\r\n}\r\n```\r\n\r\n### Pipelines\r\n\r\nEvery http(s) request that comes into the http-nats-proxy can go through a series of steps before being delivered to the\r\nfinal destination (your microservice). Those steps are defined in a yaml based configuration file and the location of\r\nthe file is passed to the https-nats-proxy via the `HTTP_NATS_PROXY_REQUEST_PIPELINE_CONFIG_FILE` environment variable.\r\nEach step defined in the pipeline configuration file contains the following properties:\r\n\r\n**subject:** The NATS subject name where the request will be delivered for this particular step in the pipeline. In\r\norder to notify the http-nats-proxy to send the message to your microservice use `*` for the subject name.\r\n\r\n**pattern:** Either `publish` or `request`, this tells the http-nats-proxy whether it should do a fire and forget\r\nmessage exchange pattern or if it should use the request/reply pattern. If you are not going to change or cancel the\r\nhttp request then you should use `publish`. If your pipeline step will potentially modify the request or cancel the\r\nrequest you should use `request`\r\n\r\n**direction:** Either `incoming, outgoing` or `both`. This tells the http-nats-proxy when to call your pipeline step.\r\n`incoming` is when the message is inbound, `outgoing` is after the message has reached the end of the pipeline and the\r\nresponse is being returned. `both` will call you pipeline step twice, once when the request is inbound and a second time\r\nwhen the response is outbound.\r\n\r\n**order:** A numeric value that is the order that your step should be called in relation to other steps in the pipeline\r\n\r\n### Observers\r\n\r\nThere are times when you want to get a copy of the request/response message after it has completed running through all\r\nof the pipeline steps. Examples of this would be when you wanted to log the request/response or capture metrics about\r\nhow long each request took to process, etc. In these cases, the metadata about the request is not available during the\r\nexecution of the pipeline steps. For these scenarios you can use Observers. Observers are notified via a NATS publish\r\nmessage after all of the pipeline steps have executed and metadata has been stored for the request/response pair. It is\r\na \"copy\" of the final state of the http request.\r\n\r\n#### Example pipeline-config.yaml file\r\n\r\n```\r\nsteps:\r\n  - subject: trace.header\r\n    pattern: request\r\n    direction: incoming\r\n    order: 1\r\n\r\n  - subject: authentication\r\n    pattern: request\r\n    direction: incoming\r\n    order: 2\r\n\r\n  - subject: '*'\r\n    pattern: request\r\n    direction: incoming\r\n    order: 3\r\nobservers:\r\n  - subject: 'pipeline.logging'\r\n  - subject: 'pipeline.metrics'\r\n```\r\n\r\n## Configuration\r\n\r\nAll configuration of the http-nats-proxy is done via environment variables.\r\n\r\n| Environment Variable                         | Default Value                   | Description                                                  |\r\n| -------------------------------------------- | ------------------------------- | ------------------------------------------------------------ |\r\n| HTTP_NATS_PROXY_HOST_PORT                    | 5000                            | The port that the http-nats-proxy will listen for incoming http requests on |\r\n| HTTP_NATS_PROXY_NAT_URL                      | nats://localhost:4222           | The NATS url where the http-nats-proxy will send the NATS message to |\r\n| HTTP_NATS_PROXY_WAIT_TIMEOUT_SECONDS         | 10                              | The number of seconds that the http-nats-proxy will wait for a response from the microservice backend before it returns a Timeout Error to the http client |\r\n| HTTP_NATS_PROXY_HEAD_STATUS_CODE             | 200                             | The http status code that will be used for a successful HEAD request |\r\n| HTTP_NATS_PROXY_PUT_STATUS_CODE              | 201                             | The http status code that will be used for a successful PUT request |\r\n| HTTP_NATS_PROXY_GET_STATUS_CODE              | 200                             | The http status code that will be used for a successful GET request |\r\n| HTTP_NATS_PROXY_PATCH_STATUS_CODE            | 201                             | The http status code that will be used for a successful PATCH request |\r\n| HTTP_NATS_PROXY_POST_STATUS_CODE             | 201                             | The http status code that will be used for a successful POST request |\r\n| HTTP_NATS_PROXY_DELETE_STATUS_CODE           | 204                             | The http status code that will be used for a successful DELETE request |\r\n| HTTP_NATS_PROXY_CONTENT_TYPE                 | application/json; charset=utf-8 | The http response Content-Type header value. This should be set to whatever messaging format your microservice api supports (xml, json, etc) |\r\n| HTTP_NATS_PROXY_REQUEST_PIPELINE_CONFIG_FILE |                                 | The full file path and name of the configuration file that specifies your request pipeline |\r\n| LOGGING_LEVEL                                | Verbose                         | Verbose\u003cbr /\u003eDebug\u003cbr /\u003eInformation\u003cbr /\u003eWarning\u003cbr /\u003eError\u003cbr /\u003eFatal |\r\n| LOGGING_PROPERTIES                           |                                 | A comma separated list of name/value pairs that will be set as properties on the Serilog log messages |\r\n\r\n## Running the Demo\r\n\r\nIn order to see the http-nats-proxy in action along with a test microservice, logging and metrics you can run the docker\r\ncompose file in your environment.\r\n\r\n```\r\ncd src\r\ndocker-compose up\r\n```\r\n\r\nThis will run the NATS server in a container.\r\n\r\nNext start the project from Visual Studio and make sure that each project in the solution is set to run on startup (\r\nmulti-project start-up configuration). The http-nats-proxy will listen for http requests on port 5000 of your host\r\nmachine. You can then send http requests to the proxy and have them processed by the test microservice. The test\r\nmicroservice that comes with this repo will respond to the following http routes:\r\n\r\n```\r\nGET http://localhost:5000/healthcheck\r\nGET http://localhost:5000/customers?id=\u003cany integer\u003e\r\n```\r\n\r\nAdditionally, if configured for metrics, logging and tracing you will see the output of those microservices as well in\r\nyour terminal. This is for demo purposes only. There is a 1/2 second delay in the logging and metrics microservices just\r\nto simulate work.\r\n\r\n## Creating your own docker image\r\n\r\nThe http-nats-proxy has a `Dockerfile` where you can build your own docker images by running:\r\n\r\n```\r\ncd src\r\ndocker build -t http-nats-proxy .\r\n\r\n```\r\n\r\n## Responsibilities of your microservices\r\n\r\nIn order to control what gets returned from the http-nats-proxy, your microservice has to set the `response` property of\r\nthe NATS message that you receive when you subscribe to a NATS subject. You should return the *entire* NATS message. You\r\nmay optionally set the `responseStatusCode` and the `errorMessage` properties if an error occurs while you are\r\nprocessing the message. The nats-http-proxy will honor the `responseStatusCode` if it is set and will also format and\r\nreturn an error response if the `errorMessage` property has been set.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwshaddix%2Fhttp-nats-proxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwshaddix%2Fhttp-nats-proxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwshaddix%2Fhttp-nats-proxy/lists"}