Files
moloapp/example/SPEC.md
T

154 lines
8.7 KiB
Markdown
Raw Normal View History

# 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.
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.
## 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.