Jet

Koder Jet — infra/net/jet

  • *rea:*Network Infrastructure (infra/net/)
  • *ath:*infra/net/jet
  • *ind:*Unified web server + reverse proxy + TLS terminator
  • *tack:*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.
  • *ersion:*v1.39.0 (20260505). Tag pattern infra/net/jet/v*.
  • *roduction 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.
  • *elfhostedfirst status:**fficial* 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.com runs Caddy.

Role in the stack

Jet is the edge layer in front of every Koder HTTP service. Written in *o*today, it is a "batteriesincluded" web server that combines the mostused 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
*uto HTTPS* ACME (Let's Encrypt v2 prod), wildcard via DNS01, OCSP stapling. Pervhost cert files supported in addition to autocert.
*TTP/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.
*CH + Post-Quantum TLS* Encrypted ClientHello with HPKE key rotation; hybrid x25519mlkem768 KEX enabled by default.
*NS-01 wildcards* ClouDNS, Porkbun providers wired for wildcard cert issuance + ECH key plumbing.
*astCGI* Real responder-side client (v1.31.0+ — replaces the placeholder that always returned 502).
*everse proxy* Pervhost proxy = "http://...", perroute [sites.routes], paradox slot routing for canary / blue-green.
*uth gate* Email-approval access gate for dev/staging vhosts (jet#106). HeaderGeo wires CDN country headers to the geofence (jet#124).
*ache-purge HTML injection* Centralised service-worker unregister + caches.delete() snippet, scoped by domain glob + IP allowlist (jet#121).
*jet bench* Builtin HTTP benchmark with reservoirsampled p50p95p99 (v1.29.0+).
*jet seccomp* Operator CLI for inspecting and testing seccomp profiles.
*jet whitelist* Auth-gate IP whitelist administration (list/add/revoke/clear/pending).
*jet doctor* 11probe operator health diagnostic (config, data_dir, authgatesmtp, authgateid, acme, backends, listeners, tls, observesink, geoip, upgradable). JSON output for CI gates.
*ero-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).
*ompression* zstd, gzip, brotli; smallbodydrop fix (jet#010 regression test).
*bserve RUM* HTML rewriter injects /_koder/rum.js into text/html responses; per-site override via [sites.observe] rum_inject = false.
*orker seccomp* Linux launcher supports off, audit, enforce modes; fixes the cgroup attach race via SIGSTOP/SIGCONT handoff (jet#102).
*dmin API* OpenAPIdocumented at /openapi.json; bearertoken enforced for mutating routes; deploy cache purge; token-required on public binds. /api/v1/status exposes tableflip_ready for upgrade decisioning.

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 *2 toplevel blocks*and classifies each as restartrequired vs reload-applicable. The journal logs an explicit remediation per block — operators no longer get the silent "config unchanged, nothing to reload" lie.

The authgate runbook lives at [`docs/authgate.kmd](../../../../infra/net/jet/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 selfcontained browser view at /docs. Covers: health/status, site CRUD, cache purge, Paradox slot management, stats, certificate status, and autoupdate status. The tableflip_ready field on /api/v1/status (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 Kodashape API for the same surface — design exercise, not implemented. Promotion to a real port is gated on Koder Koda hitting the milestones in `engineslangkoda/CAMPAIGNfullselfhosted.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

Source: ../home/koder/dev/koder/meta/docs/stack/modules/jet.md