Server

ServerConfig — every field

TLS configuration

The TLSConfig struct is shared by server.tls, tracing.tls, and the database connector tls blocks (redis, postgresql, dynamodb). All fields are the same regardless of where it appears.

tls:
  enabled: true
  certFile: /etc/erpc/tls.crt          # PEM-encoded certificate (or chain)
  keyFile: /etc/erpc/tls.key            # PEM-encoded private key
  caFile: /etc/erpc/ca.crt              # optional; trusted root for client-cert verification
  insecureSkipVerify: false              # disable cert validation entirely

AliasingConfig — domain-based project routing

server.aliasing.rules[] lets you serve different projects/architectures/chains based on the Host header. Useful when you want eth.example.com to mean /main/evm/1 without callers writing out the path.

server:
  aliasing:
    rules:
      - matchDomain: eth.example.com
        serveProject: main
        serveArchitecture: evm
        serveChain: 1
      - matchDomain: arbi.example.com
        serveProject: main
        serveArchitecture: evm
        serveChain: 42161

When a request's Host matches a rule, the URL path can be just the JSON-RPC body — the project/architecture/chain are filled in from the rule. See URL & aliasing for the request flow.

Shutdown semantics

Shutdown is a two-phase process designed to play well with load balancers:

1. Phase 1 (waitBeforeShutdown) — eRPC has received SIGTERM. The /healthcheck endpoint starts returning 503. New connections are still accepted; in-flight requests continue. The LB / k8s ingress sees the failing healthcheck and stops sending new traffic.
2. Phase 2 — drain — eRPC stops accepting new connections. Existing in-flight requests get to finish (bounded by maxTimeout).
3. Phase 3 (waitAfterShutdown) — after the listener is closed, eRPC pauses to flush telemetry (Prometheus, OpenTelemetry exporters) before the process exits.

A typical production tuning: waitBeforeShutdown: 20s (matches your k8s readiness probe interval × 2) and waitAfterShutdown: 5s (lets the metrics scraper pick up the final values).

Custom response headers

server:
  responseHeaders:
    X-eRPC-Instance: \${HOSTNAME}
    Strict-Transport-Security: "max-age=31536000; includeSubDomains"
    X-Content-Type-Options: nosniff

${VAR} env-var expansion happens at config load. Headers with empty values (after expansion) are skipped.

Gzip semantics

Per-upstream outbound gzip (eRPC → upstream) is a separate toggle on jsonRpc.enableGzip (see Upstreams).

Trusted-proxy IP — full walk-through

Suppose the request hits eRPC after passing through:

client (203.0.113.5)
   → CDN edge (cloudflare, 198.51.100.1)
   → cluster ingress (10.0.1.5, in 10.0.0.0/8)
   → eRPC pod

The ingress sets:

X-Forwarded-For: 203.0.113.5, 198.51.100.1

(Most CDNs append to X-Forwarded-For; some also set CF-Connecting-IP: 203.0.113.5.)

Configured:

server:
  trustedIPForwarders:
    - 10.0.0.0/8                       # cluster ingress
    - 198.51.100.0/24                  # cloudflare range (illustrative)
  trustedIPHeaders:
    - X-Forwarded-For
    - CF-Connecting-IP

eRPC walks X-Forwarded-For left-to-right looking for the first non-trusted IP:

• 203.0.113.5 — not in trustedIPForwarders → use this as the client IP

If you forgot to include 198.51.100.0/24 in trustedIPForwarders, eRPC would stop at 198.51.100.1 and falsely treat the CDN as the client.

Common pitfalls

• maxTimeout shorter than your slowest network failsafe timeout — clients will see timeouts even when a retry would have succeeded. Size maxTimeout to be the umbrella; per-network timeouts handle internal bounds.
• grpcEnabled without an LB that supports h2c / HTTP/2 — most TCP load balancers work; some HTTP-aware proxies (older Nginx) need explicit HTTP/2 support. Verify before deploying behind one.
• waitBeforeShutdown: 0s with k8s — kubelet sends SIGTERM the moment a pod is marked for deletion. With waitBeforeShutdown: 0, eRPC stops accepting connections instantly; in-flight requests to LB-balanced replicas may be racy. Set ≥ 2× your readiness probe interval.
• includeErrorDetails: true on a public endpoint — leaks internal error type names that may reveal implementation details. Keep false and rely on logs.
• responseHeaders colliding with eRPC's own headers — eRPC sets Content-Type, Content-Encoding, X-eRPC-Request-Id, etc. Don't override those.
• trustedIPHeaders without trustedIPForwarders — eRPC reads the header from any source. Always pair them.