2026-10-23 18:20:04 +02:00
|
|
|
# Living example
|
|
|
|
|
|
|
|
|
|
Big living example project proving every MoloApp feature end to end.
|
|
|
|
|
Plan: `plans/10-workflow-example.md`, section 6.4.
|
|
|
|
|
|
|
|
|
|
Run it:
|
|
|
|
|
|
|
|
|
|
```sh
|
|
|
|
|
make -f example/example.mk example
|
|
|
|
|
./build/example/living-server 8080
|
|
|
|
|
```
|
|
|
|
|
|
2026-10-24 02:19:52 +02:00
|
|
|
Open `http://127.0.0.1:8080/` and click through the matrix; `/stats` has the
|
|
|
|
|
charts (Chart.js is embedded in the binary, no CDN). Narrow the
|
2026-10-23 18:20:04 +02:00
|
|
|
window to 360px: the top nav collapses into a dropdown menu.
|
|
|
|
|
|
2026-10-24 02:19:52 +02:00
|
|
|
Run the suite (105 route-level integration tests, real stack, no mocks):
|
2026-10-23 18:20:04 +02:00
|
|
|
|
|
|
|
|
```sh
|
|
|
|
|
make -f example/example.mk example-test
|
|
|
|
|
```
|
|
|
|
|
|
2026-10-24 03:10:28 +02:00
|
|
|
## Load test (Locust, full integration)
|
|
|
|
|
|
|
|
|
|
`example/locustfile.py` hits literally every route: all GETs, all POSTs,
|
|
|
|
|
and the file PUTs, including the `/routing/*` prefix and parameterized
|
|
|
|
|
routes (`/hello/{name}`, `/di/resolve/{name}`, `/tenancy/t/{tenant}/whoami`,
|
|
|
|
|
`/governance/keys/{id}/revoke`, ...). Start the server, then:
|
|
|
|
|
|
|
|
|
|
```sh
|
|
|
|
|
pip install locust
|
|
|
|
|
locust -f example/locustfile.py --host http://127.0.0.1:8080
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Open the Locust web UI at `http://localhost:8089` (linked as `locust` in
|
|
|
|
|
the index matrix on `/`). Or headless:
|
|
|
|
|
|
|
|
|
|
```sh
|
|
|
|
|
make -f example/example.mk example-locust
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
The make target first runs the reproducible coverage gate
|
|
|
|
|
(`example/check_locust_coverage.py`), which enumerates every
|
|
|
|
|
`add_feature` index route plus every router registration, applies
|
|
|
|
|
fill/prefix normalization, and fails on gaps. Expected output:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
routes=112 urls=176 methods=['get', 'options', 'post', 'put']
|
|
|
|
|
OK: 112/112 routes covered, methods ['get', 'options', 'post', 'put']
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
`/ws/chat` is exercised three ways: POST echo, HTTP upgrade-header
|
|
|
|
|
probe, and a true websocket roundtrip via `ChatWebsocketUser`
|
|
|
|
|
(`websocket-client`: open `ws://host/ws/chat`, send/recv, close).
|
|
|
|
|
|
2026-10-23 18:20:04 +02:00
|
|
|
## Framework status
|
|
|
|
|
|
|
|
|
|
The framework is skeletal: `example/fw/` holds a compiling skeleton of the
|
|
|
|
|
public API (request, response hierarchy, router, application, views,
|
|
|
|
|
validation, forms, negotiation, templates, middleware, DI-shaped services,
|
|
|
|
|
errors, cookies, static, TLS stub, KV, cache, pubsub, events, metrics,
|
|
|
|
|
telemetry, sessions, auth, ORM stub, uploads, WebDAV, supervisor, tasks,
|
|
|
|
|
replication, REST client, OpenAPI, AI harness sample, release pipeline,
|
|
|
|
|
test client, loopback server). Gaps are marked in `example/SPEC.md` and in
|
|
|
|
|
each header. As siblings 01 through 09 land, this app re-binds to the real
|
|
|
|
|
namespaces route by route; the URLs, tests, and matrix stay stable.
|
|
|
|
|
|
|
|
|
|
## Coverage matrix
|
|
|
|
|
|
|
|
|
|
Feature -> route -> test file -> plan link. One row per feature; CI fails
|
|
|
|
|
on a missing row.
|
|
|
|
|
|
|
|
|
|
| Feature | Route | Test file | Plan |
|
|
|
|
|
|---|---|---|---|
|
|
|
|
|
| index | `/` | `tests/example/index_test.cpp` | `plans/10-workflow-example.md` 6.4 |
|
|
|
|
|
| health probe | `/health` | `tests/example/health_test.cpp` | `plans/09-cli-ops.md` health |
|
|
|
|
|
| routing | `/routing/hello/{name}` | `tests/example/routing/hello_test.cpp` | `plans/05-request-routing.md` |
|
|
|
|
|
| class views | `/routing/views/greet` | `tests/example/routing/views_test.cpp` | `plans/05-request-routing.md` |
|
|
|
|
|
| routers | `/routing/routers/nested/deep` | `tests/example/routing/routers_test.cpp` | `plans/05-request-routing.md` |
|
|
|
|
|
| app chaining | `/app1/app1/app1/whoami` | `tests/example/chain/deep_test.cpp` | `plans/05-request-routing.md` |
|
|
|
|
|
| orm sqlite | `/orm/users?backend=sqlite` | `tests/example/orm/users_test.cpp` | `plans/04-data.md` |
|
|
|
|
|
| orm postgres | `/orm/users?backend=postgres` | `tests/example/orm/users_test.cpp` | `plans/04-data.md` |
|
|
|
|
|
| basic auth | `/auth/me` | `tests/example/auth/me_test.cpp` | `plans/03-security.md` |
|
|
|
|
|
| login | `/auth/login` | `tests/example/auth/login_test.cpp` | `plans/03-security.md` |
|
|
|
|
|
| sessions | `/sessions/counter` | `tests/example/sessions/counter_test.cpp` | `plans/03-security.md` |
|
|
|
|
|
| uploads | `/uploads/file` | `tests/example/uploads/file_test.cpp` | `plans/03-security.md` |
|
|
|
|
|
| forms | `/forms/contact` | `tests/example/forms/contact_test.cpp` | `plans/05-request-routing.md` |
|
|
|
|
|
| validation | `/validate/user` | `tests/example/validate/user_test.cpp` | `plans/05-request-routing.md` |
|
|
|
|
|
| templates | `/templates/page` | `tests/example/templates/page_test.cpp` | `plans/05-request-routing.md` |
|
|
|
|
|
| formats | `/formats/data` | `tests/example/formats/data_test.cpp` | `plans/05-request-routing.md` |
|
|
|
|
|
| static disk | `/static/{name}` | `tests/example/static/files_test.cpp` | `plans/01-runtime.md` |
|
|
|
|
|
| embedded | `/embedded/{name}` | `tests/example/embedded/assets_test.cpp` | `plans/09-cli-ops.md` |
|
|
|
|
|
| streaming | `/streaming/feed` | `tests/example/streaming/feed_test.cpp` | `plans/06-realtime.md` |
|
|
|
|
|
| passthrough | `/streaming/passthrough` | `tests/example/streaming/passthrough_test.cpp` | `plans/06-realtime.md` |
|
|
|
|
|
| websocket | `/ws/chat` | `tests/example/ws/chat_test.cpp` | `plans/06-realtime.md` |
|
|
|
|
|
| socket.io | `/socketio/rooms` | `tests/example/socketio/rooms_test.cpp` | `plans/06-realtime.md` |
|
|
|
|
|
| sse | `/sse/events` | `tests/example/sse/events_test.cpp` | `plans/06-realtime.md` |
|
|
|
|
|
| webdav | `/webdav/files/` | `tests/example/webdav/files_test.cpp` | `plans/06-realtime.md` |
|
|
|
|
|
| pubsub | `/pubsub/publish` | `tests/example/pubsub/publish_test.cpp` | `plans/04-data.md` |
|
|
|
|
|
| events | `/events/fire` | `tests/example/events/fire_test.cpp` | `plans/02-observability.md` |
|
|
|
|
|
| metrics | `/metrics/counters` | `tests/example/metrics/counters_test.cpp` | `plans/02-observability.md` |
|
|
|
|
|
| telemetry | `/telemetry/trace` | `tests/example/telemetry/trace_test.cpp` | `plans/02-observability.md` |
|
|
|
|
|
| kv store | `/kv/items` | `tests/example/kv/items_test.cpp` | `plans/04-data.md` |
|
|
|
|
|
| cache | `/cache/lookup` | `tests/example/cache/lookup_test.cpp` | `plans/04-data.md` |
|
|
|
|
|
| tasks | `/supervisor/tasks` | `tests/example/supervisor/tasks_test.cpp` | `plans/07-supervisor-replication.md` |
|
|
|
|
|
| workers | `/supervisor/workers` | `tests/example/supervisor/workers_test.cpp` | `plans/07-supervisor-replication.md` |
|
|
|
|
|
| replication | `/replication/state` | `tests/example/replication/state_test.cpp` | `plans/07-supervisor-replication.md` |
|
|
|
|
|
| rest client | `/restclient/self` | `tests/example/restclient/self_test.cpp` | `plans/08-clients-openapi.md` |
|
|
|
|
|
| openapi | `/openapi.json` | `tests/example/openapi/docs_test.cpp` | `plans/08-clients-openapi.md` |
|
|
|
|
|
| docs page | `/docs` | `tests/example/openapi/docs_test.cpp` | `plans/08-clients-openapi.md` |
|
|
|
|
|
| ai harness | `/cli/ai` | `tests/example/cli/ai_test.cpp` | `plans/09-cli-ops.md` |
|
|
|
|
|
| workflow | `/workflow/release` | `tests/example/workflow/release_test.cpp` | `plans/10-workflow-example.md` 6.2 |
|
|
|
|
|
| redirects | `/redirect/here` | `tests/example/redirect/here_test.cpp` | `plans/05-request-routing.md` |
|
|
|
|
|
|
2026-10-24 02:19:52 +02:00
|
|
|
| statistics | `/stats` | `tests/example/stats/page_test.cpp` | `plans/02-observability.md` |
|
|
|
|
|
| statistics data | `/stats/data` | `tests/example/stats/data_test.cpp` | `plans/02-observability.md` |
|
|
|
|
|
|
|
|
|
|
### Extended features
|
|
|
|
|
|
|
|
|
|
Added in the second pass: security, platform, enterprise, resilience and
|
|
|
|
|
data-depth demos. Each row is a plain GET that answers 2xx; actions are
|
|
|
|
|
buttons or forms on the page. Per-module gaps versus `src/` are in the
|
|
|
|
|
header of `example/fw/{SecurityExtra,Platform,Enterprise,Resilience}.hpp`.
|
|
|
|
|
`tests/example/matrix_test.cpp` crawls every row of the index.
|
|
|
|
|
|
|
|
|
|
| Feature | Route | Test file |
|
|
|
|
|
|---|---|---|
|
|
|
|
|
| CSRF token form | `/security/csrf` | `tests/example/security/csrf_test.cpp` |
|
|
|
|
|
| CORS preflight allowlist | `/security/cors` | `tests/example/security/cors_test.cpp` |
|
|
|
|
|
| Rate limiter (429 + Retry-After) | `/security/rate` | `tests/example/security/rate_test.cpp` |
|
|
|
|
|
| Security headers | `/security/headers` | `tests/example/security/headers_test.cpp` |
|
|
|
|
|
| CSP nonce page | `/csp/page` | `tests/example/csp/page_test.cpp` |
|
|
|
|
|
| CSP report endpoint | `/csp/report` | `tests/example/csp/report_test.cpp` |
|
|
|
|
|
| SHA-256 and HMAC | `/crypto/hash` | `tests/example/crypto/hash_test.cpp` |
|
|
|
|
|
| Secure random token | `/crypto/random` | `tests/example/crypto/random_test.cpp` |
|
|
|
|
|
| Password hashing (demo) | `/crypto/password` | `tests/example/crypto/password_test.cpp` |
|
|
|
|
|
| Roles and permissions | `/security/roles` | `tests/example/security/` |
|
|
|
|
|
| Secrets provider (masked) | `/security/secrets` | `tests/example/security/secrets_test.cpp` |
|
|
|
|
|
| Upload validation | `/security/upload` | `tests/example/security/upload_test.cpp` |
|
|
|
|
|
| SQL and path guard | `/security/guard` | `tests/example/security/guard_test.cpp` |
|
|
|
|
|
| Denial sink | `/security/denials` | `tests/example/security/denials_test.cpp` |
|
|
|
|
|
| Login form with session cookie | `/security/login` | `tests/example/security/login_test.cpp` |
|
|
|
|
|
| i18n | `/i18n` | `tests/example/i18n/` |
|
|
|
|
|
| gzip compression | `/compress/demo` | `tests/example/compress/demo_test.cpp` |
|
|
|
|
|
| conditional GET and ranges | `/conditional/doc` | `tests/example/conditional/doc_test.cpp` |
|
|
|
|
|
| liveness probe | `/healthz` | `tests/example/healthz/` |
|
|
|
|
|
| readiness probe | `/readyz` | `tests/example/readyz/` |
|
|
|
|
|
| startup gate | `/startupz` | `tests/example/startupz/` |
|
|
|
|
|
| prometheus metrics | `/metrics` | `tests/example/metrics/` |
|
|
|
|
|
| structured logging | `/logging/records` | `tests/example/logging/records_test.cpp` |
|
|
|
|
|
| trace context | `/context/trace` | `tests/example/context/trace_test.cpp` |
|
|
|
|
|
| DI container | `/di/services` | `tests/example/di/services_test.cpp` |
|
|
|
|
|
| flash messages | `/flash` | `tests/example/flash/` |
|
|
|
|
|
| middleware builtins | `/middleware/demo` | `tests/example/middleware/demo_test.cpp` |
|
|
|
|
|
| expose stats | `/expose/stats` | `tests/example/expose/stats_test.cpp` |
|
|
|
|
|
| CLI commands | `/cli/commands` | `tests/example/cli/commands_test.cpp` |
|
|
|
|
|
| Tenant resolution (header, subdomain, path) | `/tenancy/resolve` | `tests/example/tenancy/resolve_test.cpp` |
|
|
|
|
|
| Tenant path resolution | `/tenancy/t/demo/whoami` | `tests/example/tenancy/` |
|
|
|
|
|
| Tenant data isolation | `/tenancy/data` | `tests/example/tenancy/data_test.cpp` |
|
|
|
|
|
| Tenant quotas | `/tenancy/quota` | `tests/example/tenancy/quota_test.cpp` |
|
|
|
|
|
| Tenant feature flags | `/tenancy/flags` | `tests/example/tenancy/flags_test.cpp` |
|
|
|
|
|
| Tenant config overlay | `/tenancy/config` | `tests/example/tenancy/config_test.cpp` |
|
|
|
|
|
| Per-tenant metrics | `/tenancy/metrics` | `tests/example/tenancy/metrics_test.cpp` |
|
|
|
|
|
| Tenant provisioning form | `/tenancy/provision` | `tests/example/tenancy/provision_test.cpp` |
|
|
|
|
|
| Hash-chained audit log | `/audit/log` | `tests/example/audit/log_test.cpp` |
|
|
|
|
|
| Audit tamper detection | `/audit/verify` | `tests/example/audit/verify_test.cpp` |
|
|
|
|
|
| PII masking and redaction | `/audit/mask` | `tests/example/audit/mask_test.cpp` |
|
|
|
|
|
| Retention and legal hold | `/audit/retention` | `tests/example/audit/retention_test.cpp` |
|
|
|
|
|
| Data subject export and erasure | `/audit/subject` | `tests/example/audit/subject_test.cpp` |
|
|
|
|
|
| API keys with scopes | `/governance/keys` | `tests/example/governance/keys_test.cpp` |
|
|
|
|
|
| Tiers and rate limit headers | `/governance/tiers` | `tests/example/governance/tiers_test.cpp` |
|
|
|
|
|
| API versions (Deprecation, Sunset) | `/v1/items` | `tests/example/v1/items_test.cpp` |
|
|
|
|
|
| API version list | `/governance/versions` | `tests/example/governance/versions_test.cpp` |
|
|
|
|
|
| Route linter | `/governance/lint` | `tests/example/governance/lint_test.cpp` |
|
|
|
|
|
| OpenAPI spec differ | `/governance/diff` | `tests/example/governance/diff_test.cpp` |
|
|
|
|
|
| RFC 7807 problem+json | `/governance/problem` | `tests/example/governance/problem_test.cpp` |
|
|
|
|
|
| Circuit breaker | `/operability/breaker` | `tests/example/operability/breaker_test.cpp` |
|
|
|
|
|
| Bulkhead | `/operability/bulkhead` | `tests/example/operability/bulkhead_test.cpp` |
|
|
|
|
|
| Load shedder | `/operability/shedder` | `tests/example/operability/shedder_test.cpp` |
|
|
|
|
|
| Deadline propagation | `/operability/deadline` | `tests/example/operability/deadline_test.cpp` |
|
|
|
|
|
| SLO error budget | `/operability/slo` | `tests/example/operability/slo_test.cpp` |
|
|
|
|
|
| Chaos experiment | `/operability/chaos` | `tests/example/operability/chaos_test.cpp` |
|
|
|
|
|
| Deploy strategies | `/operability/deploy` | `tests/example/operability/deploy_test.cpp` |
|
|
|
|
|
| Lease, election, fenced lock | `/operability/coord` | `tests/example/operability/coord_test.cpp` |
|
|
|
|
|
| Supply chain gate | `/supplychain` | `tests/example/supplychain/` |
|
|
|
|
|
| Client retry and backoff | `/clients/retry` | `tests/example/clients/retry_test.cpp` |
|
|
|
|
|
| Client session: cookies, pool, proxy, auth | `/clients/session` | `tests/example/clients/session_test.cpp` |
|
|
|
|
|
| Migrations: check then apply | `/data/migrations` | `tests/example/data/migrations_test.cpp` |
|
|
|
|
|
| Transaction rollback | `/data/transaction` | `tests/example/data/transaction_test.cpp` |
|
|
|
|
|
| Query builder and relations | `/data/query` | `tests/example/data/query_test.cpp` |
|
|
|
|
|
| Singleflight | `/data/singleflight` | `tests/example/data/singleflight_test.cpp` |
|
|
|
|
|
| TTL store, LRU, pubsub | `/data/ttl` | `tests/example/data/ttl_test.cpp` |
|
|
|
|
|
| Debug snapshot | `/operability/debug` | `tests/example/operability/debug_test.cpp` |
|
|
|
|
|
|
2026-10-23 18:20:04 +02:00
|
|
|
## Layout
|
|
|
|
|
|
|
|
|
|
```text
|
|
|
|
|
example/
|
|
|
|
|
example.mk # per-part make include (build, test, clean)
|
|
|
|
|
SPEC.md # mini-spec: behaviors, caps, formats, errors, gaps
|
|
|
|
|
README.md # this file
|
|
|
|
|
main.cpp # loopback server entry
|
|
|
|
|
fw/ # skeletal framework public API (namespace molo::example::fw)
|
|
|
|
|
app/ # demo routes (namespace molo::example::app)
|
|
|
|
|
static/ # disk static assets (responsive CSS, tiny JS)
|
2026-10-24 02:19:52 +02:00
|
|
|
assets/ # embedded at build time (Chart.js, stats.js) via src/cli/embed
|
|
|
|
|
tools/ # build helper wrapping the embedder
|
2026-10-23 18:20:04 +02:00
|
|
|
tests/example/ # route-level integration tests mirroring URLs
|
|
|
|
|
```
|