API & data-plane contract

eggrd adds no application endpoints of its own. Your API is whatever you put behind it, forwarded unchanged. What this page documents is the contract the proxy imposes on that traffic: the one namespace it reserves, the headers it adds in each direction, and every status code it can generate instead of your app.

Anything not listed under status codes is your upstream's own response, passed through.

Internal endpoints

/__edgeguard/* is reserved. It is never forwarded upstream, and these routes are exempt from auth, rate limiting, the WAF and IP access control — so that a liveness probe still answers when the gate in front of it is refusing everything. Restrict them at the network layer, or move the ops trio to a private listener with server.admin_port.

Any other /__edgeguard/… path is 404 from eggrd with outcome not_found. It is never a leak through to the app.

Public/private split

With server.admin_port set, the ops trio moves off the public port entirely:

• Admin listener (admin_addr:admin_port, plain HTTP, no auth): health, ready and metrics. No proxy fallback — an unknown path is 404.
• Public listener: the proxy, plus /__edgeguard/csp-report only, because a browser has to be able to reach the sink. The ops trio on the public port becomes 404.

The admin listener carries no authentication by design. Bind it to loopback or a private network; do not publish it.

Headers eggrd adds to the upstream request

Hop-by-hop headers — the RFC 7230 §6.1 set, plus anything named in Connection — and Host are stripped, and Content-Length is recomputed. With websocket_passthrough an upgrade request keeps its Connection: upgrade and Upgrade headers.

Headers eggrd adds or rewrites on the response

Every response — proxied and eggrd-generated errors alike — carries X-Request-Id, and the Access-Control-* decoration when [cors] is on and the request carried an allowed Origin.

Proxied responses additionally get the [headers] hardening:

A tunneled WebSocket connection is not hardened: there is no buffered response to stamp.

Status codes eggrd generates itself

The proxy pipeline in evaluation order. outcome is the label on the JSON access log and on edgeguard_requests_total{outcome=…}; the two line up one to one, so a spike on a dashboard names the exact stage that produced it.

Error bodies are one-line text/plain; charset=utf-8, apart from the DLP JSON above. No HTML error pages and no stack traces.

Where each gate sits, and why it matters

The order in that table is the order of evaluation, and the position of the forward row is the whole point: every refusal above it happens before your upstream is contacted. A request that is denied costs your app nothing, and on the LLM lane it costs the provider nothing, because the call was never placed.

That used to be an assertion in a comment. Since 0.4.0 it is a test: a counting stub stands in for the upstream and each denial path asserts it saw exactly zero requests — unauthenticated, WAF block, IP denied, oversized body, rate limited, limiter outage, over budget, DLP block, off-allow-list model and budget-store outage. A control test asserts an admitted request reaches it exactly once, so a counter that never incremented could not make the rest pass vacuously.

Written by hand from the routers in src/lib.rs and the pipeline in src/proxy.rs, and checked against the shipped binary. The configuration reference is generated from the source instead, because it is far too large to keep honest any other way. Something wrong here is a bug worth reporting.