Charon API Rate Limiter

CHARON 1.0.0 QUICKSTART

Charon runs in front of your API on port 8080 and forwards allowed requests to your backend.

REQUIREMENTS

• Docker, Amazon ECS, Amazon EKS, or AWS Fargate
• A reachable HTTP backend
• Linux AMD64
• Ports 8080 and 9110

IMAGE

IMAGE="709825985650.dkr.ecr.us-east-1.amazonaws.com/vgov/charon:1.0.0"

RUN WITH DOCKER

Create a network for Charon and your application:

docker network create charon-network

Start your application on the network. Replace YOUR_APPLICATION_IMAGE with your image:

docker run -d
--name app
--network charon-network
YOUR_APPLICATION_IMAGE

Start Charon and point it to the application:

docker run -d
--name charon
--network charon-network
-p 8080:8080
-p 9110:9110
-e CHARON_UPSTREAM=http://app:3000 
"$IMAGE"

For an Amazon ECS or AWS Fargate sidecar where both containers are in the same task, use:

CHARON_UPSTREAM=http://127.0.0.1:3000 

CHECK HEALTH

Check the Docker health status:

docker inspect
--format='{{.State.Health.Status}}'
charon

The expected result is:

healthy

Check the health endpoint:

curl http://localhost:9110/healthz 

The expected response is:

ok

SEND REQUESTS

Send traffic to Charon instead of connecting directly to your backend:

curl -i http://localhost:8080/ 

Allowed requests return your backend response. Requests that exceed the configured limit return:

HTTP/1.1 429 Too Many Requests

The response may include a Retry-After header.

VIEW METRICS

Prometheus metrics are available at:

curl http://localhost:9110/metrics 

Metrics include allowed requests, denied requests, abuse activity, upstream errors, active caller keys, and proxy latency.

Keep port 9110 private and accessible only to trusted monitoring and health-check systems.

VIEW LOGS

docker logs charon

Logs use JSON by default. For readable text logs, add this option when starting Charon:

-e CHARON_LOG_FORMAT=text

CUSTOM CONFIGURATION

Create charon.yaml:

listen: ":8080" admin: ":9110" upstream: "http://app:3000 " upstream_timeout: "30s" log_format: "json"

key: from: ip trusted_proxy: false

limits: algorithm: token_bucket rate: 100 window: "1s" burst: 200 overrides: - path_prefix: "/auth/" rate: 10 window: "1s" burst: 10

abuse: burst: enabled: true threshold: 50 window: "1s" action: block

response: status: 429 retry_after: true body: "rate limited\n"

Validate the configuration:

docker run --rm
--entrypoint /usr/local/bin/charon
-v "$PWD/charon.yaml:/etc/charon/charon.yaml:ro"
"$IMAGE" check /etc/charon/charon.yaml

Run with the configuration:

docker run -d
--name charon
--network charon-network
-p 8080:8080
-p 9110:9110
-v "$PWD/charon.yaml:/etc/charon/charon.yaml:ro"
"$IMAGE"

RELOAD CONFIGURATION

After changing limits, abuse rules, path overrides, or denial responses, reload without restarting:

docker kill --signal HUP charon

Invalid changes are rejected, and the last valid configuration remains active. Changes to the upstream or listening addresses require a restart.

PRODUCTION NOTES

• Set trusted_proxy to true only behind a trusted load balancer or proxy.
• Charon does not terminate TLS. Terminate HTTPS at your load balancer, ingress controller, or service mesh.
• Rate-limit counters are stored separately in each Charon instance.
• Keep your backend private so clients cannot bypass Charon.
• Send application traffic to port 8080.
• Restrict port 9110 to internal monitoring.