# Web Server Technology 1-2-3 Plan **Last reviewed:** 2026-10-26 **Scope:** `web-server-technology/` and `lib/web-server-technology/` **Purpose:** Record the delivered dynamic, SQL-backed, dual-stack HTTP/1.1 server and its SLeeLa facade, and track the remaining work before public production deployment. **Review type:** Source authoring plus local build and runtime smoke tests on the POSIX backend. No automated CI, stress test, or penetration test has been run in this review. **Overall status:** Core dynamic server, Side-2 envelopment, and the Section-3 in-process hardening (rate limiting, write-auth, trusted-proxy) plus the documented TLS boundary are delivered, built clean, and unit + end-to-end tested. Remaining before untrusted-network exposure: the SQL-engine maturity work (transactions/JOINs/concurrency) and environment-bound validation (CI, stress/fuzz, real IPv6). ## Current status snapshot — 2026-10-26 The server builds with no warnings, links the `lib/sleela-sql` engine, and passes an end-to-end smoke test: dynamic `SELECT` and filtered queries, the fluent SLeeLaSQL dialect over POST, the read-only write-denial policy, encoded path-traversal containment (`403`), and static file serving. Dual-stack binding is reported at startup and in `/__sleela/status`. The SLeeLa facade (`SLWebServer`, `SLSqlEndpoint`, `SLDualStackBinding`) passes `sleela check` and `sleela run` under the source-built 2.1 compiler and asserts policy correspondence with the native server. A pre-existing build-breaking brace error in `lib/sleela-sql/native/src/sleela_sql.c` was fixed and the SHA-256 manifest regenerated. | Area | Current observation | Priority / status | |---|---|---| | Dynamic SQL endpoint | `/db/query` executes SQL via the engine and returns JSON per request, in SQL and SLeeLaSQL dialects. | Delivered; smoke-tested | | World IP reach (dual-stack) | One `AF_INET6` socket with `IPV6_V6ONLY` cleared accepts IPv6 and IPv4-mapped peers, with `AF_INET` fallback. | Delivered; IPv4 verified, IPv6 loopback not testable in this env | | Write policy | `/db` is read-only by default; mutations require `--db-writable`. Single-statement-only, 8 KiB SQL bound, 10,000-row JSON bound. | Delivered; smoke-tested | | Static files | Root-relative resolution, normalization, `..` rejection, canonical-prefix containment. | Delivered; traversal test passes | | Side 2 envelopment | One domain fronts many programs (meme/static/sql) via subjects/warrants for causes; Scientist-gated; selectable in startup flags or config file. Side 1 is untouched when inactive. | Delivered; gate + routing tested | | Rate limiting | Sliding-window per-peer + global admission control; over-limit = 503, not counted; swept. | Delivered; unit + live tested | | Write authorization | Bearer-token gate on mutating `/db`, constant-time compare; 401 on missing/wrong. | Delivered; unit + live tested | | Trusted proxy / client IP | Honours Forwarded/X-Forwarded-For only from allowlisted proxies (anti-spoof); keys rate limit + logs on the real client. | Delivered; unit + live tested | | TLS 1.3 | Not in-process by design; documented reverse-proxy deployment model with the trusted-proxy hook. | Boundary delivered + documented | | CPU keep-warm floor | Closed-loop controller holds each of the 1-16 cores at a ~11-14% band so the server stays warm; on by default, admin-disablable, low-priority so real work preempts. | Delivered; converges ~12.5%, tested | | SQL engine maturity | Local CSV-backed subset: no ACID/JOINs/indexes/concurrent-writer isolation (see `lib/sleela-sql/ROADMAP.md`). | High / outstanding | | Transport hardening | Bounded worker pool and queue, bounded headers/bodies, strict framing, bounded chunked decode, `Host` enforcement, keep-alive/timeouts, graceful shutdown, synchronized logging. | Carried over from Grade 1 | | TLS / authentication | Not terminated in-process; no authenticated peer identity. | Critical / outstanding for public use | | Rate limiting | Only the bounded connection queue provides back-pressure; no per-peer windowed limiter. | High / outstanding | | SQL engine maturity | Local CSV-backed subset: no ACID transactions, JOINs, indexes, or concurrent-writer isolation (see `lib/sleela-sql/ROADMAP.md`). | High / outstanding | | Engine handle reuse | A fresh engine handle is opened per `/db` request; no pooled handle. | Medium / optimization | | Build integration | `web-server-technology/native/Makefile` builds and links the engine; not yet wired into the top-level/`impl` build or CI. | Medium / decision required | **Safe operating posture:** Keep the listener behind a deliberately configured, TLS-terminating, access-controlled boundary (reverse proxy plus per-IP rate limiting) before exposing it to untrusted networks. Leave `/db` read-only unless a trusted operator explicitly needs writes. ## 1. Server core and dynamic SQL — delivered **Goal:** A dynamic HTTP/1.1 server that answers world IP addresses and serves JSON computed per request from live SQL. - [x] IPv6/dual-stack listener (`AF_INET6` + IPv4-mapped) with `AF_INET` fallback. **Delivered.** - [x] `/db/query` endpoint executing SQL through `lib/sleela-sql` and returning `{"columns":[...],"rows":[...],"row_count":N}`. **Delivered.** - [x] Both dialects accepted (classic SQL and fluent SLeeLaSQL). **Delivered.** - [x] Read-only-by-default policy with `--db-writable` gate; single-statement, length- and row-bounded. **Delivered; smoke-tested.** - [x] Static file serving with path-traversal containment. **Delivered; traversal test passes.** - [x] RFC 8259 JSON string escaping on all values. **Delivered.** - [x] Fixed the pre-existing `exec_drop` brace error in the SQL engine and regenerated the SHA-256 manifest. **Delivered.** ## 2. SLeeLa facade and verification — delivered **Goal:** A faithful SLeeLa-side model of the server with the required metadata. - [x] `SLWebServer`, `SLSqlEndpoint`, `SLDualStackBinding`, and `SLPackage` with Descriptive-metadata blocks. **Delivered.** - [x] Executive-tier metadata citing real instruments (RFC 9112, RFC 8259, RFC 4291). **Delivered.** - [x] Runnable `demo-web-server-technology.sleela` passing `check` and `run` on the 2.1 source compiler. **Delivered.** - [x] Demo asserts policy correspondence: `SELECT` read-only-permitted, `INSERT` denied until writable, single-literal bind drops world reach. **Delivered.** ## 2b. Side 2 — envelopment (many programs per domain) — delivered **Goal:** A domain may carry many subjects/warrants for causes, enveloping many disparate programs behind one domain, available to Scientists and selectable in startup settings or the configuration file. Side 1 stays the default. - [x] Self-contained envelopment model (`native/envelopment.{h,cpp}`): `Program` (static/sql/meme), `Warrant` (cause/subject/path/program/enabled), `Envelopment`. **Delivered.** - [x] Line-oriented config grammar + loader shared with CLI overrides; `docs/ENVELOPMENT.md` and `examples/envelopment.conf`. **Delivered.** - [x] Scientist capability gate: `active()` requires enabled + scientist + >=1 warrant; the server refuses to start if enabled without the capability. **Delivered; tested.** - [x] Control surface in both startup flags (`--config`, `--envelopment`, `--scientist`) and config file (`envelopment`, `scientist`, `domain`). **Delivered.** - [x] Longest-matching-path-prefix warrant resolution; selected program runs in its own mount-relative path space reusing the Side-1 static/SQL machinery. **Delivered.** - [x] Side 1 proven untouched when envelopment is inactive. **Delivered; regression passes.** - [x] SLeeLa facade (`SLWebProgram`, `SLWarrant`, `SLEnvelopment`) with metadata; demo asserts the `active()` gate matches the native rule. **Delivered; check + run pass.** ## 3. Hardening before public production **Goal:** Make the server safe to expose directly to untrusted networks. The in-process controls and the TLS boundary are now delivered and tested; the remaining items are the SQL-engine maturity work and environment-bound validation. ### Delivered - [x] Documented TLS 1.3 reverse-proxy deployment model with a native trusted-proxy hook so the server behaves correctly behind a terminator. See `docs/HARDENING.md`. **Delivered.** - [x] Write authorization for mutating `/db` use: `Authorization: Bearer `, constant-time compare, 401 on missing/wrong; composes with `--db-writable`. **Delivered; unit + live tested.** - [x] Global and per-peer sliding-window rate limiter beyond the connection-queue back-pressure; over-limit = 503 (not counted); aged windows swept. **Delivered; unit + live tested.** - [x] Trusted-proxy client-IP resolution (Forwarded / X-Forwarded-For) with anti-spoofing; rate limit and logs key on the real client. **Delivered; unit + live tested.** - [x] Per-request SQL engine open removed from the hot path: the db directory is validated/created once at startup and the engine handle is bound without a per-request `stat()`/`mkdir()`. **Delivered.** - [x] Both control surfaces: all hardening settings work as startup flags and in the configuration file (CLI overrides file). **Delivered; tested.** - [x] Hardening is its own module (`native/hardening.{h,cpp}`) with unit tests (`make check`) plus live and config-file end-to-end tests. **Delivered.** ### Operational warmth (added) - [x] CPU keep-warm idle floor: a closed-loop per-core controller that holds each of the 1-16 CPUs in a ~11-14% band so the server stays warm (avoids deep-idle / cold-path latency on the first request after quiet). On by default; an administrator may disable (`--no-warm`) or retune the band; low-priority (`SCHED_IDLE`) so genuine request handling always preempts it; bounds clamped so it can never become a runaway hot loop. Own module `native/cpu_warmer.{h,cpp}` with a convergence test (`make check`, lands ~12.5% on the build host) and a live status/override test. See `docs/CPU-WARM.md`. **Delivered.** ### Shared implementation (consolidation) - [x] The server no longer carries a parallel copy of the envelopment and hardening logic: `native/envelopment.cpp` (active-gate + longest-prefix resolution) and `native/hardening.cpp` (rate limiter, constant-time compare, bearer-token auth, trusted-proxy client IP) now delegate to the one shared C core, `lib/web-server-technology` (`slweb`), which the server links. The server keeps its transport-facing structs and config loaders; the decision logic lives in a single place. Full test battery re-run with no behavior change. **Delivered.** ### Testing + observability (added) - [x] Local stress + fuzz harness (`native/stress-fuzz-test.sh`): concurrent `/db` soak (mixed read/write), SQL fuzz (gibberish/empty/multi-statement/oversize/binary → clean 4xx, never 5xx), and HTTP framing fuzz on raw sockets (bad method / no version / missing Host / garbage / 70 KiB header → 400/405 or clean close, process survives). **"CI" is deliberately offloaded to a local runnable script -- no external CI vendor / no GitHub Actions.** `docs/TESTING.md` documents the whole local suite. **Delivered; passes.** - [x] `/__sleela/warm` endpoint: per-core keep-warm readings as JSON (band + live per-core percent). **Delivered; tested.** - [x] First transaction step in `lib/sleela-sql`: snapshot-based `ssql_begin`/`commit`/`rollback`/`in_transaction` with documented, honest rollback guarantees and a dedicated test (`tests/test_txn.c`). **Delivered; see the engine ROADMAP for what is and is not yet guaranteed.** ### Still outstanding - [ ] Finish the `lib/sleela-sql` durability/isolation gaps the snapshot transaction does not yet cover: a crash-recovery journal/manifest with automatic replay, and cross-process concurrent-writer isolation. Plus richer predicates/JOINs. (Still a separate engine effort; not claimed.) - [ ] Validate the IPv6/dual-stack path on a host with real IPv6 connectivity (only IPv4 was exercisable in this environment). --- # SLeeLa

SLeeLa — The Now. The Ingredient.