Koder Jet — `infra/net/jet`
- Area: Network Infrastructure (
infra/net/) - Path:
infra/net/jet - Kind: Unified web server + reverse proxy + TLS terminator
- Stack: Go (production binary). A Koder Koda port spec lives at
docs/koda-port-spec/as a design exercise (jet#126 Path C); promotion gated on Koder Koda maturity milestones. - Version: v1.39.0 (2026-05-05). Tag pattern
infra/net/jet/v*. - Production deployment: s.forge (LXC 129 on s.r1,
177.136.231.237:443). Currently fronts 204 vhosts on*.koder.dev,flow.koder.dev,*.vivver.com.br,ticsign.com, etc. - Self-hosted-first status: official, 9 gates passed (
feature_parity,performance,stability,tls,reverse_proxy,hot_reload,static_serving,http3,production_proven), 0 pending. Replaces nginx, caddy, apache, traefik. Single permitted exception:poc.vivver.comruns Caddy.
Role in the stack
Jet is the edge layer in front of every Koder HTTP service. Written in Go today, it is a "batteries-included" web server that combines the most-used features of nginx, Caddy, Traefik, plus a pile of operational hooks Koder needs (auth-gate, observe RUM injection, paradox slot routing) into a single unified binary.
"Like a jet — fast, direct, no unnecessary stops."
Features
| Feature | Description |
|---|---|
| Auto HTTPS | ACME (Let's Encrypt v2 prod), wildcard via DNS-01, OCSP stapling. Per-vhost cert files supported in addition to autocert. |
| HTTP/1, 2, 3 | TCP HTTP1.1+2 plus QUIC HTTP3 over UDP443 ([http3] enabled = true). HTTP3 capability is a passed self-hosted gate as of v1.32.0. |
| ECH + Post-Quantum TLS | Encrypted ClientHello with HPKE key rotation; hybrid x25519mlkem768 KEX enabled by default. |
| DNS-01 wildcards | ClouDNS, Porkbun providers wired for wildcard cert issuance + ECH key plumbing. |
| FastCGI | Real responder-side client (v1.31.0+ — replaces the placeholder that always returned 502). |
| Reverse proxy | Per-vhost proxy = "http://...", per-route [sites.routes], paradox slot routing for canary / blue-green. |
| Auth gate | Email-approval access gate for devstaging vhosts (jet#106). HeaderGeo wires CDN country headers to the geofence (jet#124). A bare GET shows a static "Request access" button and emails nobody — the approval notifier fires only on the explicit button POST (__koder_gate=request), then a 303 POSTredirectGET (jet#196, the UA-independent fix for the crawler email storm; backstops the jet#190 UA heuristic). The approval email is multipart with a one-click "Authorize access" button → `confirm.koder.devreq/token?do=approve`, which one-shots the approval after Koder ID sign-in (jet#197). |
| Cache-purge HTML injection | Centralised cacheSW invalidation snippet, scoped by domain glob + IP allowlist (jet#121); the inline <script> carries the per-request CSP nonce so it survives enforce-mode nonce-CSP (jet#195). Smart since jet#204: version-gated (purge once per build_id transition via localStorage, not every render), mode="soft" default (registration.update() + postMessage, keeps the SWPWA alive — mode="hard" is the emergency unregister()), synchronous head-check + single guarded reload to fix the first post-deploy render, selective cache deletion + SW-scope scoping, header_mode (Clear-Site-Data) and report_only dry-run. Content value injected-by-jet-204. |
| Cache-control posture | [cache_control] (jet#202): text/html → no-cache (revalidate, so a redeploy is seen at once), fingerprinted asset requests (?v=<hash> / path glob) → public, max-age=1y, immutable. Set only when the response carries no Cache-Control (unless override), so it never clobbers the nonce'd-HTML no-store (#195) or the static handler's directive. OFF by default — enabling is an owner-level Stack-wide flip (per-env via environments.kmd). |
| Streaming / SSE passthrough | All response-writer wrappers (cache, cache-purge, observe-inject, subfilter, wasm, response-rewrite, compress, headers) implement Flush()+Unwrap() and skip buffering for streaming Content-Types (text/event-stream et al.), so httputil.ReverseProxy streams SSE through the full middleware chain instead of buffering it dead (jet#203; unblocks Koder ID GET /v1/me/auth-gate/stream foreground push). |
| kjet bench | Built-in HTTP benchmark with reservoir-sampled p50p95p99 (v1.29.0+). |
| kjet seccomp | Operator CLI for inspecting and testing seccomp profiles. |
| kjet whitelist | Auth-gate IP whitelist administration (list/add/revoke/clear/pending). |
| kjet doctor | 11-probe operator health diagnostic (config, data_dir, auth-gate-smtp, auth-gate-id, acme, backends, listeners, tls, observe-sink, geoip, upgradable). JSON output for CI gates. |
| Zero-downtime upgrade | cloudflare/tableflip integration + koder-jet-upgrade.service helper unit. systemctl start koder-jet-upgrade does a SIGUSR2 binary swap with zero connection drops (v1.39.0+, jet#133). |
| Compression | zstd, gzip, brotli; small-body-drop fix (jet#010 regression test). |
| Observe RUM | HTML rewriter injects /_koder/rum.js into text/html responses; per-site override via [sites.observe] rum_inject = false. |
| CSP per-request nonce | An outermost global EnsureNonce middleware installs one per-request nonce holder in the root context (jet#195, csp.kmd R1.1) so every consumer agrees: the ${csp_nonce} header-template variable (jet#162), the [sites.response_rewrite] body substitution (jet#163), and the global cache-purge injected <script> all stamp the same nonce. Headers reuses the holder idempotently (R1.4). Response-rewrite also sets Cache-Control: no-store on nonce'd HTML (per-request-nonce bodies are uncacheable — jet#195). [sites.csp_report] accepts violation reports at /csp-report (jet#164). KDS (stg.kdskds.koder.devkoder.design) runs ENFORCE since jet#201 (2026-06-03) — flipped after a ≥24h CLEAN/STALE-CLIENT window + an exhaustive headless route crawl with zero script-src violations. The header allowlist is reconciled with the design-gen <meta> CSP (header∩meta is the effective policy): img hub.koder.dev, media-src, connect reporter+analytics, worker-src, plus nonce-based script-src + wasm-unsafe-eval (KVG). The earlier 2026-05-31 premature flip broke cached reloads (stale-nonce); resolved by jet#195 (no-store on nonce'd HTML) + jet#204 (version-gated soft-SW). |
| Worker seccomp | Linux launcher supports off, audit, enforce modes; fixes the cgroup attach race via SIGSTOP/SIGCONT handoff (jet#102). |
| Admin API | OpenAPI-documented at /openapi.json; bearer-token enforced for mutating routes; deploy cache purge; token-required on public binds. /api/v1/status exposes tableflip_ready for upgrade decisioning. |
| AI-sites store | POST /api/v1/ai-sites publishes AI-app vhosts under *.kapps.koder.dev. Persistence is opt-in to a multi-tenant kdb (Postgrespgx) ai_sites table (`internalaistore, jet#150) keyed by koderuserid with RLS via the app.currenttenantid GUC (cross-tenant read → 404, not 403). Disabled by default (no [ai_sites] DSN → legacy sites.toml dump), and best-effort even when enabled — a store failure never blocks boot; jet stays file-backed (always-on §5). Human-curated vhosts stay in sites.toml`; AI ephemera lives in the store. |
Operations
The runbook lives at docs/operations.kmd (v1.39.0+). Decision tree:
| Trigger | Mechanism | Drops connections? | When |
|---|---|---|---|
systemctl reload koder-jet |
SIGHUP | no | Sites or reload-applicable global block changed |
systemctl start koder-jet-upgrade |
SIGUSR2 + tableflip | no | New koder-jet binary deployed |
systemctl restart koder-jet |
SIGTERM + spawn | yes (briefly) | Restart-required global block changed (tls, http3, dns, admin, dashboard, supervisor) |
The reload diff (internal/config/diff.go, jet#132 V1) detects changes in 22 top-level blocks and classifies each as restart-required vs reload-applicable. The journal logs an explicit remediation per block — operators no longer get the silent "config unchanged, nothing to reload" lie.
The auth-gate runbook lives at docs/auth-gate.kmd. It covers the full request-flow diagram, env-var matrix (SMTP + Koder ID introspection), confirm-callback mount conventions, smoke-test procedure for koder-jet reload, and kjet whitelist administration.
Interfaces
The Go production runtime exposes the Admin API schema at /openapi.json and a self-contained browser view at /docs. Covers: healthstatus, site CRUD, cache purge, Paradox slot management, stats, certificate status, and auto-update status. The tableflip_ready field on `apiv1status (jet#133) lets operators and kjet doctor --probe upgradable` choose between SIGUSR2 and SIGTERM-restart paths.
The Koder Koda spec under docs/koda-port-spec/ (relocated from src/ in jet#126) shows the Koda-shape API for the same surface — design exercise, not implemented. Promotion to a real port is gated on Koder Koda hitting the milestones in engines/lang/koda/CAMPAIGN-full-self-hosted.kmd.
Primary couplings
| Consumer | Relationship |
|---|---|
products/dev/flow |
Fronted by Jet on flow.koder.dev (git, CI, releases, Hub backend) |
products/dev/hub |
Fronted by Jet on hub.koder.dev |
| `products/horizontal |