Internals

Code layout#

The gateway is a modular monolith: one deployable, split into domains with explicit boundaries. bun run architecture checks the boundaries in the test suite and CI.

Domains#

Import rules#

scripts/gates/architecture.ts enforces these in the test suite and CI:

1. Import a domain only through its index.ts.
2. Use only the dependencies the domain matrix allows.
3. A domain's core (outside adapters/) imports no framework, Bun API, application, platform, runtime or adapter; dependencies arrive through ports.
4. A domain's index.ts exports no adapter.
5. The application uses domain entry points and observation interfaces, never an adapter.
6. The platform implements ports, makes no policy decision, and imports neither application nor runtime.
7. The observation layer imports nothing from the project.
8. The runtime is the composition root and may assemble everything.
9. No catch-all directories (utils, services, repositories, common, …) and no import cycles, type-only imports included.
10. Only the application uses Hono; only the platform uses runtime APIs.
11. The source imports nothing from services/: neither the Access reference implementation nor the test fixtures belong to the gateway, and a source file that imported one would put the test accounts in the image.

Environment variable names never leave src/runtime/env/; the rest of the gateway receives the settings it needs, not the environment. scripts/gates/environment.ts checks that .env.example and Configuration match the variables declared there.

bun run dead runs knip --use-tsconfig-files and fails on any unused file, export, type or dependency. A domain's index.ts is not an entry point, so an export no consumer imports is reported, as is an export used only inside its own module. Workers started with Bun.spawn and the bun --watch runner are declared as entries in the knip section of package.json.

The gateway adds one rule to the platform working rules: a request is an exchange, not a chain of middlewares.

Resource ownership#

The runtime constructs and closes the shared clients, watchers and process timers. The configuration owns the last-good immutable generation; each request captures one generation for all its policy and forwarding decisions. An HTTP exchange owns its streams, phase timers and cancellation. A WebSocket pair owns both legs, its buffers, its keepalive timers and its slot.

A single owner finalizes each exchange and each connection exactly once. A middleware completing is not an exchange completing.

Request flow#

Bun.serve (platform/bun/listener.ts)
  └─ app.fetch (app/app.ts)
       └─ middleware: request id, cookies
            ├─ gateway endpoints (app/endpoints.ts)
            └─ dispatcher (app/dispatcher.ts)
                 ├─ routing: matchRoute
                 ├─ rate-limiting: the four scopes
                 ├─ authentication: selectCredential, authenticate
                 ├─ forwarding: checkCrossSite, buildUpstreamHeaders
                 ├─ workspace-access: decide
                 ├─ proxying: execute  →  platform/bun/http-transport.ts
                 └─ websockets: handle   →  platform/bun/upstream-websocket.ts

The dispatcher is the only place domains are combined; each decides only for itself.

Source map#

Each rule lives in one domain, with its tests beside it.

services/access-service.ts answers the spec §6.1 protocol from a policy file. It is not a fixture; test/support/access-conformance.ts runs against it, so protocol and reference cannot drift.

Shared-state layout#

Postgres objects, in the gateway schema:

The Redis ACL in deploy/redis/gateway.acl gives gateway read/write on session, limit and decision keys, write-only on its heartbeat (%W~gateway:cfg:hb:*), and read-only on gateway:cfg:active, gateway:cfg:rev:* and gateway:cfg:revs. Revisions are hashes and history a list, and gateway can neither write a hash nor push to a list. gateway-control may read and write ~gateway:*.

Verification#

CI (.github/workflows/ci.yml) also builds the image, checks it starts with a deployment configuration, refuses to start without a session secret, Access, identity provider or rate limit, and contains no fixtures.

Last full run: 793 passed, 0 failed across 79 files on Bun 1.4.3, with real Redis 7.0.15 (GATEWAY_TEST_REDIS_URL=redis://127.0.0.1:6399/0), real Postgres 18.6 (GATEWAY_TEST_POSTGRES_URL=postgres://postgres@127.0.0.1:5432/gateway), 3 Chromium tests and 2 soak tests. Only the four real-provider interop tests were skipped (CI runs them against dex). Coverage of src/: 93.8 % lines, 93.0 % functions (mean over files); whole tree: 91.7 % lines, 91.8 % functions. Without Redis, its 38 tests are skipped; without a named Postgres server, Postgres tests use the in-process engine.

Capacity#

Measured with scripts/ops/load.ts, which also reports resident memory (size pods with it) and can target a running gateway:

bun run load -- --requests 20000 --concurrency 100
bun run load -- --websockets 1000
bun run load -- --url http://localhost:8080 --host api.example.com

Reference machine: AMD Ryzen 7 5800X (8 cores, 16 threads), 31 GiB, Linux 7.2, Bun 1.4.3. Gateway and upstream in one process, plain http over loopback, idle machine. Numbers are a lower bound on cost: no ingress, TLS or network.

• About 7600 req/s; latency grows with requests in flight because the runtime queue is the bottleneck.
• A WebSocket handshake costs about 2 ms; 1000 connections cost about 40 MiB.
• On the same machine under other load: about 4400 req/s (p50 23 ms) at 100 in flight. Measure on your own machines.
• Soak (bun test test/load, 5 rounds of 50 requests, a WebSocket and a reload): settled in 1.1 s, heap growth below 64 MiB. It is a release gate: memory, descriptors, connections and timers must settle.

Shared-state backends#

scripts/ops/benchmark.ts runs each scenario against both backends:

bun run benchmark -- --redis redis://127.0.0.1:6399/0 --postgres postgres://127.0.0.1:5432/gateway

Scenarios: no-state (baseline), limits (three limiter checks), session (plus the session read), full (plus the cached decision). Last run: 20 000 requests at 50 in flight, two rounds, all servers on the reference machine over loopback; an earlier run differed by a few percent.

• Redis costs about a tenth of baseline on limits and a third on full; Postgres about half, with twice Redis's p50. The gap grows with round trips.
• Not the disk: with synchronous commit off, a limiter transaction takes about 0.2 ms instead of 1.8 ms. With it on, Postgres limits drops to about 420 req/s (p50 120 ms), because the deployment scope serializes every request.
• Forty pool connections measured slower than ten (about 3 600 vs 4 100 req/s on limits): serialization, not pool size, is the bottleneck.
• Not measured: an ingress, TLS (the ingress's cost), state on another host, managed servers, several replicas (counters are proved exact; capacity is the sum of replicas).

Runtime#

The gateway is written against Bun directly, so each boundary behind spec §4.2, §10 and §11 is proved by a test/network/ test against a real socket. Before reading its environment, src/runtime/version.ts stops the gateway on a runtime older than Bun 1.4.3 (decision 36); src/runtime/version.test.ts tests it.

Release#

The release process is platform-wide: see platform release. Gateway binaries embed the runtime and are built for seven targets: bun-linux-x64 (glibc), bun-linux-x64-musl (Alpine), bun-linux-arm64, bun-darwin-x64, bun-darwin-arm64, bun-windows-x64, bun-windows-arm64. Archives are named like gateway-1.0.0-linux-x64-musl. The image is built twice, once into the local store for deployment checks and once for the registry; only the second carries provenance and SBOM attestations, because the local docker exporter cannot carry an attestation manifest list.

Known gaps#

Outside the gateway's scope, closed by the deployment:

Thin evidence: