Files
moloapp/example/SPEC.md
T
retoor 0595284fe3 feat(doos): add container runtime, audit cases, example demo and tests
- New rootless doos container runtime: sandbox, cgroup, network, images, hardening, davmount, CLI plus molo integration
- 18 CVE audit reproductions with READMEs and Makefiles
- Example DoosDemo routes, IndexCatalog, static assets, spec update
- CLI serve on 0.0.0.0:8000, arg parser, dev server improvements
- Runtime HTTP fixes, supervisor isolation backend
- Tests for doos, example doos routes, CLI serve; suite count 261 to 265
2026-11-06 04:36:00 +01:00

10 KiB

SPEC: living example (plan 10-workflow-example.md, section 6.4)

Status: accepted skeleton, 2026-10-23. Follows plans/10-workflow-example.md rules 1-10 to the extent the framework exists; every gap below names the owning sibling plan and the file that will close it.

Behaviors

  1. GET / renders the coverage matrix from a template with inheritance. Rows are grouped into themed sections by route prefix (IndexCatalog, example/app/IndexCatalog.cpp); a route matching no group lands in "Other" and fails index_test. Groups whose demos need credentials carry a "needs API key" badge. Each row is <td><a href="ROUTE">Name</a></td> (the crawl marker used by matrix_test and tools/verify_deploy.py), with the route repeated in a column that hides below 40rem. A filter box (/static/index.js) hides non-matching rows; without JavaScript the full list shows. Adding a feature stays add_feature(name, route); adding a route under a new prefix means adding the prefix to a group.

  2. Every matrix row resolves to a live route, a test file, and a plan link.

  3. Every test drives the real stack: TestClient -> middleware -> router -> view -> in-memory services, plus one real loopback HTTP round-trip.

  4. Validation failures list ALL field failures with status 422.

  5. Unknown routes answer 404 JSON; wrong methods answer 405 or 404.

  6. Over-cap request bodies answer 413; unnegotiated formats answer 406.

  7. Sessions persist across requests via signed cookies in the test jar.

  8. ORM endpoints self-heal: unknown tables and columns are created inline and the response reports what healed.

  9. The release demo parses Conventional Commits, maps the bump, renders a changelog entry, and gates on checks (dry-run: never writes).

  10. All pages render on a 360px viewport; wide nav collapses to a dropdown.

  11. Browser form posts that fail validation answer 422 with the same form: a summary box (count, one link per failing field) and the message next to each invalid input, entered values kept. Never raw JSON in a page. JSON clients (Accept or Content-Type application/json) keep the validation_error body. One partial (form_page.html) and one helper (app/FormUi.hpp) serve every form.

  12. GET /stats renders Chart.js charts from GET /stats/data: requests, errors, latency avg/p50/p95/p99 and histogram, bytes in/out, status codes, methods, top routes, connections (total, active, peak, timeouts, malformed, cap left), plus service state (stores, cache hit/miss, tasks, workers, ORM, metrics registry). History: 90 ten-second buckets.

  13. Chart.js 4.4.7 and the page script are embedded at build time: example/assets -> build/example/gen/assets.{cpp,hpp} through the MoloApp embedder (src/cli/embed), served at /embedded/{name}.

  14. Every matrix row answers a plain GET with 2xx/3xx (401 for /auth/me by design). tests/example/matrix_test.cpp crawls them all.

  15. Feature groups added: security extras (csrf, cors, rate limit, headers, csp, crypto, roles, secrets, upload, guards, denials, login), platform (i18n, compression, conditional GET and ranges, probes, prometheus, logging, trace context, DI, flash, middleware, expose stats, CLI reference), enterprise (tenancy, audit, governance), resilience (breaker, bulkhead, shedder, deadline, slo, chaos, deploy, coord, debug, supply chain, client retry and session, migrations, transactions, query builder, singleflight, ttl store). Each is a skeleton of the real src/ module; per-module gaps are in the header of its fw/ file.

  16. Voice (src/google, the real framework part, not a skeleton): GET /voice is a hands-free conversation page. The browser detects speech from the microphone level, records one utterance, posts it to POST /voice/turn, plays the spoken answer, and listens again; speaking over the answer interrupts it. The server runs Google speech-to-text, a Gemini reply and Google text-to-speech per turn, with bounded per-conversation history. POST /voice/say and /voice/hear expose the two speech services alone; GET /google/status shows credential state and known services (never the key). No GOOGLE_API_KEY: 503 google_not_configured. Upstream failure: 502 google_error with Google's status. Bad input: 422 or 415 before any network call. Routes and tests use a scripted transport; the key lives only in the x-goog-api-key header.

  17. Agent Platform (src/google/<module>): nine modules, one demo page each at /agent/<module> (models, runtime, sessions, sandbox, registry, armor, optimize, adk, live). GET pages and /status answer 2xx with no credential; every route that calls Google is POST or DELETE and answers 503 google_not_configured without one, 422 on bad input. Destructive routes need an explicit confirmation. No route test scripts a Google reply. All /agent, /voice and /google routes are excluded from locust; check_locust_coverage.py fails if one is referenced.

  18. LLM vendor platforms (src/<vendor>, shared layer src/llm): ten demo pages at /ai/<vendor>[/<part>] for xAI, Anthropic, Meta, DeepSeek, OpenAI and OpenRouter. Same contract as item 17: GET pages and /status answer 2xx with no credential, every calling route is POST or DELETE and answers 503 not_configured without one and 422 on bad input; paid or destructive routes are dry runs unless the body has "confirm":true. No route test scripts a vendor reply. All /ai routes are excluded from locust.

  19. Breadth (plan 18): seven Google packages at /google/<pkg> (discovery, cloudai, enterprise, data, maps, workspace, ops) and ten vendor packages at /ai/<v> (compat, mistral, cohere, perplexity, bedrock, azure, huggingface, audio, media, retrieval). Same contract as items 17 and 18. Every /google and /ai route is excluded from locust.

  20. Sandboxed containers (src/doos, the real framework part): GET /doos renders the container page, GET /doos/status returns containers, images, davmounts and the libdoos version as JSON, POST /doos/create idempotently creates (name plus optional size/memory/net), POST /doos/delete dry-runs unless confirm=yes. Validation failures answer 422 with every failure listed; a missing container answers 404. All four run on a demo store (DOOS_HOME when the harness sets it, else build/doos-demo), never the user's real store; real container starts stay out of the demo (see src/doos/SPEC.md, Framework seams).

Caps

All ceilings live as literals in example/fw/Caps.hpp: 1 MiB request body, 100 headers, 200 form fields, 32 JSON depth, 8 MiB upload, 4096 routes, 8 mount depth, 100k KV entries, 10k cache entries, 1000 pubsub topics, 1000 metrics, 10k spans, 100k sessions, 100k ORM rows, 10k tasks, 64 workers, 1000 stream chunks, 64 listen backlog, 30 s socket timeout, 512 connections, 600 s suite cap, 30 s single-test cap, 1 release per green run, 20 changelog lines, 100-char commit subjects, 30 min pipeline timeout.

Formats

  • JSON errors: {"error":"<code>","message":"<text>"}.
  • Validation errors: {"error":"validation_error","failures":[{"field", "message"}]}.
  • Prometheus: one <name> <value> line per metric.
  • SSE: data: <event> frames separated by blank lines.
  • WebDAV PROPFIND: 207 with D:multistatus XML.
  • OpenAPI: {"openapi":"3.0.0","info":{...},"paths":{...}}.

Errors

HttpError(status, code, message) maps to the status with a JSON body. ValidationError maps to 422. Unmapped exceptions become 500 JSON without stack details. Route table: 301/302 redirects, 400 bad input, 401 missing auth, 403 bad credentials, 404 unknown, 405 wrong method, 406 no format, 413 over cap, 415 blocked upload type, 422 validation, 500 internal.

Isolation

May depend on: C++23 stdlib, POSIX sockets, example/fw/, and the real framework parts it links on purpose: src/google over src/clients (HTTPS via wolfSSL) and src/operability. Build-time only: the embedder sources in src/cli/embed (asset embedding). May NOT depend on: other src/ trees, real Postgres/SQLite (in-memory doubles), real network except Google through src/google (tests script that transport; only the opt-in MOLO_LIVE_NET=1 tests touch the network). Namespaces mirror directories: molo::example::fw and molo::example::app.

Gaps

  • Real namespaces (molo::app, molo::routing, ...) replace fw/ skeletons as siblings 01-09 land. Owner: each sibling plan.
  • Coroutine handlers, event loop, HTTP/2, compression, keep-alive: owner 01-runtime.md, file example/fw/Server.*.
  • Real log format, OTel/Prometheus export: owner 02-observability.md, file example/fw/Observ.*.
  • wolfSSL TLS, Argon2id, AES-GCM, CSRF, CORS, rate limits: owner 03-security.md, files example/fw/Tls.*, example/fw/Cookies.*.
  • Postgres wire client, SQLite handling, pooling, transactions: owner 04-data.md, file example/fw/Data.*.
  • Full validation coercions, template sandbox, DI container, flash messages: owner 05-request-routing.md, files example/fw/Validate.*, example/fw/Templates.*, example/app/App.*.
  • Voice turns are request/response over REST (about 2 to 4 s per turn). The loopback server accepts sequentially, so one in-flight turn blocks other requests meanwhile. Streaming recognition and the Gemini Live API: owner src/google/SPEC.md, gaps section. Owner of concurrent accept: 01-runtime.md, example/fw/Server.*.
  • Server accepts sequentially and stops after 512 connections (cap above); the stats page shows connections left. Owner: 01-runtime.md, example/fw/Server.*.
  • Template engine has no elif, not, or macros. Owner: 05-request-routing.md, example/fw/Templates.*.
  • Real WS/Socket.IO/SSE framing, rooms, namespaces, realtime clients: owner 06-realtime.md, file example/app/RealtimeDemo.*.
  • Worker processes, durable streams, conflict hooks, multi-instance: owner 07-supervisor-replication.md, file example/fw/Jobs.*.
  • Real HTTP client, test fixtures, time freezing: owner 08-clients-openapi.md, files example/fw/Net.*, example/fw/TestClient.*.
  • Root Makefile, CLI, dev server, embedder codegen, AI CLI loop: owner 09-cli-ops.md, files example/example.mk, example/app/Embedded.*.
  • specs/, root AGENTS.md final, CHANGELOG.md, VERSION, tags: shared floors, see /AGENTS.md draft; this part must not write them alone except the drafts it owns.