{"id":29291094,"url":"https://github.com/networknt/http-sidecar","last_synced_at":"2026-02-03T02:13:18.423Z","repository":{"id":37084447,"uuid":"384810077","full_name":"networknt/http-sidecar","owner":"networknt","description":"HTTP sidecar of light-mesh to provide cross-cutting concerns for Kubernetes service","archived":false,"fork":false,"pushed_at":"2025-08-11T22:02:57.000Z","size":86402,"stargazers_count":3,"open_issues_count":1,"forks_count":1,"subscribers_count":16,"default_branch":"master","last_synced_at":"2025-08-12T00:11:54.498Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/networknt.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-07-10T22:42:36.000Z","updated_at":"2025-06-25T20:35:16.000Z","dependencies_parsed_at":"2024-01-19T20:42:23.213Z","dependency_job_id":"49e627df-7d1d-4a82-9001-d9a796989108","html_url":"https://github.com/networknt/http-sidecar","commit_stats":null,"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"purl":"pkg:github/networknt/http-sidecar","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/networknt%2Fhttp-sidecar","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/networknt%2Fhttp-sidecar/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/networknt%2Fhttp-sidecar/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/networknt%2Fhttp-sidecar/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/networknt","download_url":"https://codeload.github.com/networknt/http-sidecar/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/networknt%2Fhttp-sidecar/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272816171,"owners_count":24997720,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-30T02:00:09.474Z","response_time":77,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":[],"created_at":"2025-07-06T07:34:19.508Z","updated_at":"2026-02-03T02:13:18.374Z","avatar_url":"https://github.com/networknt.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"## http-sidecar:\n\nhttp-sidecar can be deployed as sidecar container run in parallel with the main container in the pod.\n\nThe http-sidecar sidecar service will handle proxy and router the ingress/egress traffic for the service in main container, and can delegate the Cross-Cutting Concerns handlers for the service in main container.\n\n\n  - http-sidecar\n\n    http-sidecar can be deployed as sidecar container/service to handle restful request/response related functionalities which include:\n\n     - Package and deployed as separate module to handle Cross-Cutting Concerns for main container/service in the same pod. In this case, the main service only need care about the http request/response and business logic\n\n     - Ingress traffic: client API request will come to sidecar service first, sidecar service act as a proxy to delegate light client features, which include, openapi schema validation, observability, monitoring, logging, JWT verify, etc. Then forward the request to main service.\n\n     - Egress traffic: main service call sidecar service first for egress traffic; in this case, sidecar service act as a router to delegate light client features, which include service discovery, SSL handshake, JWT token management, etc. Then forward the request to server API.\n\n\n\n\n### Architecture diagram\n\n- Deploy the service with sidecar container:\n\n![Ligh-Mesh Architecture](docs/mesh.png)\n\n- Service normal deployment without sidecar container:\n\n![Ligh-Mesh Architecture](docs/mesh-2.png)\n\n\n### What Is a Sidecar Pattern\n\nSegregating the functionalities of an application into a separate process can be viewed as a Sidecar pattern. The sidecar design pattern allows you to add a number of capabilities to your application without additional configuration code for third-party components.\n\nIn software architecture a sidecar attach to a parent application and extends/enhances its functionalities. A sidecar is loosely coupled with the main application.\n\nIn Kubernetes cluster environment, sidecar can be deployed as Sidecar container run in parallel with the main container in the pod.\n\n\n### Benefits of Using a Sidecar Pattern:\n\n- Reduces the complexity in the microservice code by abstracting the common infrastructure-related functionalities to a different layer.\n- Reduces code duplication in a microservice architecture since you do not need to write configuration code inside each microservice.\n- Provide loose coupling between application code and the underlying platform.\n\n\n\n### Note:\n\nIf you want to use SidecarServiceDictHandler to get the service Id by the path url mapping from serviceDict.yml, add it before token handlers and router handler. The service Id get from serviceDict\nwill be used for next handler chain.\n\n```\n  - com.networknt.router.middleware.SidecarServiceDictHandler@path\n  - com.networknt.router.middleware.SidecarSAMLTokenHandler@saml\n  - com.networknt.router.SidecarRouterHandler@router\n\n```\n\n\n### start http-sidecar locally and verify:\n\n- start http-sidecar service\n\n```\ncd ~/workspace\ngit clone git@github.com:networknt/http-sidecar.git\n\ncd http-sidecar\n\nmvn clean install\n\n\njava -jar -Dlight-4j-config-dir=config/local  target/http-sidecar.jar\n\n\n```\n\nThe http-sidecar service will start on http port 9080 and https port 9445. In the kubernetes multiple containers situation, the http-sidecar service will be deployed as sidecar container with the service API in same pod.\nThe service API could use any technologies, like NodeJs, .nets, php service...; The sidecar container (http-sidecar service) will handle the ingress and egress traffic to the pod and leverage light-4j cross-cutting concerns and client module features.\n\nIn the k8s pod, the egress network traffic will http protocol(from service API container to sidecar container), and the traffic will be forwarded by sidecar container (delegate light-router features) to downsteam API.\n\nIn reverse way, the ingress traffic (from outside of pod to call the service API in the pod) should be https protocol, it will reach the sidecar container first (by http-sidecar service Id), the sidecar container will leverage the light platform cross-cutting concerns features and forward the request to main service container in the pod.\n\n\n\n- Start Nodejs restful API (It is simulate the service in the Pod)\n\nFollow the [steps](nodeapp/start.md) to start Nodejs books store restful API. The Nodejs api will start on local port: 8080\n\nWe can verify the Nodejs restful API directly with curl command:\n\n```\nGet:\n\ncurl --location --request GET 'http://localhost:8080/api/books/' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\"name\":\"mybook\"}'\n\nPost:\n\ncurl --location --request POST 'http://localhost:8080/api/books/' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\"title\":\"Newbook\"}'\n\nPut:\n\ncurl --location --request POST 'http://localhost:8080/api/books/' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\"title\":\"Newbook\"}'\n\nDelete:\n\ncurl --location --request DELETE 'http://localhost:8080/api/books/4' \\\n--header 'Content-Type: application/json' \\\n```\n\n\n- Start a sample light-4j API from light-example-4j (It is simulate the outside service which service in the Pod need to call):\n\n\n```\n cd ~/networknt\n git clone git@github.com:networknt/light-example-4j.git\n cd ~/networknt/light-example-4j/servicemesher/services\n\n mvn clean install -Prelease\n\ncd petstore-service-api\n\njava -jar target/petstore-service-api-3.0.1.jar\n\n```\n\nThe petstore light-api will start on local https 8443 port.\n\n\n- Try the call by using http-sidecar:\n\n\n\n#### Ingress traffic (https protocol, port 9445)\n\nSend request from outside service to the service in the pod through sidecar\n\n```\ncurl --location --request GET 'https://localhost:9445/api/books/' \\\n--header 'Content-Type: application/json' \\\n\n```\n\nLeverage schema validation handler cross-cutting concerns\n\n```\ncurl --location --request POST 'https://localhost:9445/api/books/' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\"author\":\"Steve Jobs\"}'\n```\n\nresponse:\n\n```\n{\n    \"statusCode\": 400,\n    \"code\": \"ERR11004\",\n    \"message\": \"VALIDATOR_SCHEMA\",\n    \"description\": \"Schema Validation Error - requestBody.title: is missing but it is required\",\n    \"severity\": \"ERROR\"\n}\n```\n\n\n#### Egress traffic (http protocol, port 9080)\n\nSend request from service in the pod to light API petstore through sidecar\n\n```\ncurl --location --request GET 'http://localhost:9080/v1/pets' \\\n--header 'Content-Type: application/json' \\\n\n```\n\n#### Build native executable docker image\n\n\nCreate static link native executable (linux only) with native-image tools of Graalvm, it requires docker installed on your develop machine. The executable is static linked with musl (x86_64) static library. The size of generated docker image around 14M.\n\n```\nmvn clean install\n\ndocker build -f docker/Dockerfile.native . -t http-sidecar-native:latest\n\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnetworknt%2Fhttp-sidecar","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnetworknt%2Fhttp-sidecar","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnetworknt%2Fhttp-sidecar/lists"}