retoor
3c4334cec9
Full C++23 framework tree: runtime, observability, security, data, app, realtime, supervisor, clients, CLI, example plus enterprise tenancy, audit, operability, governance, supplychain. Postgres via docker compose for tests.
86 lines
4.2 KiB
Markdown
86 lines
4.2 KiB
Markdown
# 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.
|
|
|
|
## 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/` only. May NOT
|
|
depend on: any `src/` tree (does not exist yet in this worktree), wolfSSL
|
|
(stub behind `ITlsContext`), real Postgres/SQLite (in-memory doubles),
|
|
real network except loopback. 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.*`.
|
|
- 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.
|