2026-10-23 18:20:04 +02:00
|
|
|
# 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.
|
2026-10-24 02:19:52 +02:00
|
|
|
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.
|
2026-10-23 18:20:04 +02:00
|
|
|
|
2026-10-24 04:05:41 +02:00
|
|
|
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.
|
|
|
|
|
|
2026-10-23 18:20:04 +02:00
|
|
|
## 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
|
|
|
|
|
|
2026-10-24 04:05:41 +02:00
|
|
|
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:
|
2026-10-23 18:20:04 +02:00
|
|
|
`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.*`.
|
2026-10-24 04:05:41 +02:00
|
|
|
- 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.*`.
|
2026-10-24 02:19:52 +02:00
|
|
|
- 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.*`.
|
2026-10-23 18:20:04 +02:00
|
|
|
- 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.
|