Home /Modules/web-server-technology/ARCHITECTURE.md

ARCHITECTURE.md

web-server-technology/ARCHITECTURE.md · 115 line(s) · markdown

SLeeLa Web Server Technology — Architecture

This note explains how the dynamic SQL-backed server processes a request, how it reaches world IP addresses, and where the SQL endpoint boundary sits.

1. Connection lifecycle

accept() ──> bounded queue ──> worker thread ──> serve(fd)
                 (QMAX=128)        (16 default)

2. Request parsing (hardened)

The parser is the Grade-1 parser, carried over unchanged in behaviour:

3. Dispatch

/__sleela/health           -> liveness text
/__sleela/status           -> server status JSON
/db, /db/...               -> dynamic SQL endpoint (section 5)
everything else            -> static file from document root (section 4)

4. Static files

The request path is treated as root-relative: leading slashes are stripped so /index.html maps to <root>/index.html, never to the filesystem root. The decoded path is normalized and rejected if it is absolute or contains any .. segment, and a canonical-prefix check confirms the resolved file still lives under the document root. This contains path traversal (verified by trav-test.sh: ..%2f..%2fetc%2fpasswd is 403 Forbidden).

5. The dynamic /db endpoint

GET  /db/health                 engine status JSON
GET  /db/query?sql=<encoded>    read-only statement -> JSON rows
POST /db/query   (body = SQL)   statement -> JSON rows (writes gated)

Flow:

  1. Extract SQL from the sql= query parameter (GET) or the request body (POST).
  2. Enforce policy: trim; reject empty; reject SQL longer than 8 KiB; reject a multi-statement list; classify the leading verb. If the verb is not a read verb (SELECT/SHOW/from(/tables() and the server was not started with --db-writable, respond 403.
  3. ssql_open the table directory, then ssql_exec the statement. Engine CSV output is captured via open_memstream and converted to a JSON object of the form {"columns":[...],"rows":[{...}],"row_count":N}. JSON strings are escaped per RFC 8259. A successful mutation returns {"ok":true,"mutated":true}.
  4. Engine errors map to 422 Unprocessable Entity with {"error":"<ssql_strerror>"}.

The endpoint opens a fresh engine handle per request; the engine itself is a file-per-table CSV store, so there is no long-lived shared connection to pool yet. (A pooled handle is a natural future optimisation.)

6. Dual-stack / world IP reach

listen_dual_stack():

  1. Create an AF_INET6 socket and clear IPV6_V6ONLY. Bound to in6addr_any, it accepts native IPv6 peers and IPv4-mapped (::ffff:a.b.c.d) peers on the same socket — i.e. the full range of world IP addresses.
  2. If IPv6 is unavailable, or the operator passed an explicit IPv4 bind address, fall back to a plain AF_INET socket.

The server reports which mode it is in at startup (dual_stack=yes|no) and in /__sleela/status ("dual_stack":true).

7. Observability

One synchronized log line per request:

request method=GET path=/db/query version=HTTP/1.1 status=200 bytes=191 \
        duration_us=95 note=db-query ok readonly=1

Query strings and request bodies are deliberately not logged.

8. Relationship to the SLeeLa model

lib/web-server-technology/ carries the SLeeLa-side facade of this server:

SLeeLa classModels
SLWebServerthe server configuration + lifecycle
SLSqlEndpointthe /db route policy (read-only / writable, bounds, verb classification)
SLDualStackBindingthe world-IP-reach binding descriptor

The facade's policy decisions (e.g. which verbs are read-only) are kept faithful to the native statement_is_readonly / db_endpoint logic, and the runnable demo-web-server-technology.sleela asserts that correspondence.