http-sidecar:

http-sidecar can be deployed as sidecar container run in parallel with the main container in the pod.

The 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.

• http-sidecar

  http-sidecar can be deployed as sidecar container/service to handle restful request/response related functionalities which include:

  • 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

  • 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.

  • 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.

Architecture diagram

• Deploy the service with sidecar container:

• Service normal deployment without sidecar container:

What Is a Sidecar Pattern

Segregating 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.

In software architecture a sidecar attach to a parent application and extends/enhances its functionalities. A sidecar is loosely coupled with the main application.

In Kubernetes cluster environment, sidecar can be deployed as Sidecar container run in parallel with the main container in the pod.

Benefits of Using a Sidecar Pattern:

• Reduces the complexity in the microservice code by abstracting the common infrastructure-related functionalities to a different layer.
• Reduces code duplication in a microservice architecture since you do not need to write configuration code inside each microservice.
• Provide loose coupling between application code and the underlying platform.

Note:

If 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 will be used for next handler chain.

  - com.networknt.router.middleware.SidecarServiceDictHandler@path
  - com.networknt.router.middleware.SidecarSAMLTokenHandler@saml
  - com.networknt.router.SidecarRouterHandler@router

start http-sidecar locally and verify:

• start http-sidecar service

cd ~/workspace
git clone git@github.com:networknt/http-sidecar.git

cd http-sidecar

mvn clean install


java -jar -Dlight-4j-config-dir=config/local  target/http-sidecar.jar

The 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. The service API could use any technology. 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.

In 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.

In 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.

• Start or configure a backend service

The local configuration profile proxies ingress traffic to http://localhost:8080. Run your backend service on that port, or update proxy.hosts in config/local/values.yml to point to the service you want to place behind the sidecar.

• Start a sample light-4j API from light-example-4j (It is simulate the outside service which service in the Pod need to call):

 cd ~/networknt
 git clone git@github.com:networknt/light-example-4j.git
 cd ~/networknt/light-example-4j/servicemesher/services

 mvn clean install -Prelease

cd petstore-service-api

java -jar target/petstore-service-api-3.0.1.jar

The petstore light-api will start on local https 8443 port.

• Try the call by using http-sidecar:

Ingress traffic (https protocol, port 9445)

Send request from outside service to the service in the pod through sidecar

curl --location --request GET 'https://localhost:9445/api/books/' \
--header 'Content-Type: application/json' \

Leverage schema validation handler cross-cutting concerns

curl --location --request POST 'https://localhost:9445/api/books/' \
--header 'Content-Type: application/json' \
--data-raw '{"author":"Steve Jobs"}'

response:

{
    "statusCode": 400,
    "code": "ERR11004",
    "message": "VALIDATOR_SCHEMA",
    "description": "Schema Validation Error - requestBody.title: is missing but it is required",
    "severity": "ERROR"
}

Egress traffic (http protocol, port 9080)

Send request from service in the pod to light API petstore through sidecar

curl --location --request GET 'http://localhost:9080/v1/pets' \
--header 'Content-Type: application/json' \

Build native executable docker image

Create 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.

mvn clean install

docker build -f docker/Dockerfile.native . -t http-sidecar-native:latest

Jackson 3 source line

This line requires the Jackson 3 framework snapshots, Jackson 3.2.3, json-schema-validator 3.0.8 and yaml-rule 4.0.0-SNAPSHOT. Build the migrated prerequisites from source before this application; old snapshot binaries can have incompatible Config mapper descriptors. Jackson annotations retain their com.fasterxml.jackson.annotation package. Framework mapper defaults are preserved; classic SnakeYAML cleanup is deferred.

Build the pinned, merged chaos-monkey sources and verify the strict distribution profile before qualifying the final distribution. Local tests and mapper parity do not imply deployed integration or remote CI qualification.

Reproducible Jackson 3 source build

.github/workflows/jackson3-source-build.yml builds the prerequisite source stack in an isolated Maven repository, reuses independently qualified full-core test evidence, and runs the prerequisite and full consumer suites. It pins reviewed policy f0d2100f972eec765b2b276e7ace38922394f0a6 and candidate bc3e4b5e2719d705d58a2edeabeb9bb5009c7401; yaml-rule/http-client are selected from that verified evidence. The complete prerequisite closure is pinned in ci/jackson3-source-refs.json, initialized from the successful source-build manifest, with reviewed updates expressed as full SHAs; no default-branch or migration-branch lookup is used. Explicit source_refs replay overrides are merged into that map and remain subject to core qualification. The workflow uploads source-refs.json, source-commits.txt, core-qualification.json and Surefire reports. Core registration and workflow-token acceptance are merged in light-4j #2825 and #2826.

The optional source_refs workflow-dispatch input replays recorded full SHAs. GitHub enables dispatch only after the workflow exists on the default branch; before merge, reproduce from the recorded source checkouts locally. A green local suite is separate from a successful remote source-build run.

Logstash Encoder is now 9.0 (Jackson 3). The source manifest pins the merged light-chaos-monkey #49 cleanup at 89b12694ea98c10281106918707e20c64635e1f3, which removes the unused Jackson 2 runtime declarations. Fresh source-build and strict distribution results on this consumer head determine distribution qualification; this PR remains a draft pending review. ChaosMonkeyBinaryGuardTest inspects class-file member references in every chaos-monkey class on the application classpath, including latency-assault, and rejects Jackson 2 Config/mapper ABI references. It records the Jackson 2 databind origin separately. The jackson3-distribution Maven profile rejects any remaining Jackson 2 databind; this strict gate must pass on the current consumer head before distribution qualification. Its independently frozen Maven Central 2.4.1 class is a negative control. A freshly rebuilt source dependency passing this test does not qualify an older published jar. Do not deploy the Jackson 2 chaos-monkey binaries with Jackson 3 Config.

The source workflow now runs that profile after its normal suite and publishes an independent distribution-readiness check. That check stays red while Jackson 2 databind remains, even when the normal test check is green. Its command, exit code and isolated Surefire reports are retained in jackson3-distribution-readiness; a failed or missing result cannot pass readiness.

Exact-source CI qualification

Consumer CI requires retained successful full-reactor evidence for the actual checked-out light-4j SHA and the same yaml-rule/http-client source commits. Core PR CI explicitly checks out the PR head, not its merge ref. Replay dispatches cannot qualify consumers. The attempt-specific evidence artifact records the actual checkout, prerequisite SHAs and test totals. A later pending, failed or cancelled run does not invalidate earlier valid evidence. All API pages and retained attempts are considered; missing or expired evidence blocks reuse. core-qualification.json records the accepted run and artifact.

The full dependency ledger is audited across all groups. Every NetworkNT release and snapshot must be source-installed, apart from the explicitly SHA-256-pinned Jackson 3 validator release. Known Jackson 2 yaml-rule and chaos-monkey releases are rejected even with a local-install marker. Jackson 2 dependencies in other groups are reported; ready migrations reject them except shared annotations.