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) withAF_INETfallback. Delivered. - [x]
/db/queryendpoint executing SQL throughlib/sleela-sqland 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-writablegate; 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_dropbrace 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, andSLPackagewith Descriptive-metadata blocks. Delivered. - [x] Executive-tier metadata citing real instruments (RFC 9112, RFC 8259, RFC 4291). Delivered.
- [x] Runnable
demo-web-server-technology.sleelapassingcheckandrunon the 2.1 source compiler. Delivered. - [x] Demo asserts policy correspondence:
SELECTread-only-permitted,INSERTdenied 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.mdandexamples/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 theactive()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
/dbuse:Authorization: Bearer <token>, 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 modulenative/cpu_warmer.{h,cpp}with a convergence test (make check, lands ~12.5% on the build host) and a live status/override test. Seedocs/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) andnative/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/dbsoak (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.mddocuments the whole local suite. Delivered; passes. - [x]
/__sleela/warmendpoint: per-core keep-warm readings as JSON (band + live per-core percent). Delivered; tested. - [x] First transaction step in
lib/sleela-sql: snapshot-basedssql_begin/commit/rollback/in_transactionwith 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-sqldurability/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
<p align="center"><img src="https://github.com/mearvk/SLeeLa/blob/master/images/sleela/sleela-wordmark.svg" alt="SLeeLa — The Now. The Ingredient." width="560"></p>