feat: implement MoloApp plans 01-15 with integration

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.
This commit is contained in:
2026-10-23 18:20:04 +02:00
parent 54068f1953
commit 3c4334cec9
1068 changed files with 100899 additions and 2 deletions
+3
View File
@@ -0,0 +1,3 @@
build/
*.o
*.a
+91
View File
@@ -0,0 +1,91 @@
# AGENTS.md (DRAFT, owned by plan 10-workflow-example.md)
Normative agent workflow for MoloApp. Human quickstart lives in README.md;
this file is the single entry point for autonomous work. Status: draft until
the root Makefile and CLI land (09-cli-ops.md); per-part commands below are
live today via `example/example.mk`.
## Setup commands
```sh
g++ --version # expect g++ 15.2 with -std=c++23
make --version # GNU or BSD make
```
Expected: both print versions. Failure action: stop, page a human.
## Build
```sh
make # whole repo (root Makefile includes per-part .mk files)
make -f example/example.mk example # this part only, standalone
```
Expected: warning-free build, outputs only under `build/`. Failure action:
fix at root cause, never silence warnings.
## Test
```sh
make test # whole repo
make -f example/example.mk example-test # this part only, standalone
```
Expected: `example suite: 37 passed, 0 failed`. Failure action: reproduce
through the real stack first (failing route-level test), then fix; the
reproduction stays in the suite. Conventions: `tests/README.md`.
## Lint
```sh
make lint # configured gate (falls back to -Wall -Wextra clean build)
```
Expected: zero findings. Failure action: fix, never skip the gate.
## Docs update
After behavior changes, in the same session: spec delta first, then code,
then example route, then tests, then changelog entry. Docs state what the
system does today; gaps list the owning file next to the code.
## Version bump
Never hand-chosen. From commits since the last tag: any `!` or
`BREAKING CHANGE` -> MAJOR; else any `feat` -> MINOR; else any `fix` ->
PATCH; else no release. `VERSION` plus annotated tag `vMAJOR.MINOR.PATCH`
update atomically with the changelog entry. Demo: `POST /workflow/release`.
## Commit
Format: `<type>[(scope)][!]: <description>`, subject max 100 chars.
Allowed types: feat, fix, docs, style, refactor, perf, test, build, ci,
chore. Scope is the area slug: runtime, security, data, routing,
realtime, supervisor, clients, cli, workflow. Malformed commits are
rejected before version analysis.
## Tag
Tagging requires a green suite plus live verification after deploy, same
session. Failed verification blocks the tag. Max 1 release per green run.
## Deploy
```sh
make deploy # defined by 09-cli-ops.md; loopback single binary for v1
```
## Verify live
After deploy: health probe, metrics scrape, example index load on a 360px
viewport, click the matrix top 10 routes. Any red step halts the pipeline;
report, never force-push past red.
## Floors and escalation
Never cross alone: `specs/`, `CHANGELOG.md`, `VERSION`, tags, retention
windows, destructive file deletes, history rewrite, force push, hard
reset. On a floor hit: dry-run, stop, page a human. Pipeline order is
lint -> suite -> bump -> changelog -> commit -> tag -> deploy -> verify;
timeout 30 min, then escalate. On code-vs-spec conflict the spec wins
until formally amended in the same change.
+138
View File
@@ -0,0 +1,138 @@
# MoloApp root Makefile. Aggregates the per-part subdir fragments:
# each part ships src/<part>/<part>.mk (plus example/example.mk).
# Targets: all, test, clean, interop, lint.
#
# Composition rules used here:
# - Double-colon all::/test::/clean:: so supervisor.mk and example.mk can
# append their own branches without editing this file.
# - Fragments are included byte-exact from the parts; integration-only
# wiring (missing rules, missing pattern edges) lives below the includes
# and is marked INTEGRATION.
CXX ?= g++
CXXFLAGS ?= -std=c++23 -O2 -Wall -Wextra -pthread
AR ?= ar
# Consumed by src/runtime/runtime.mk (verified runtime flags).
MOLO_CXXFLAGS ?= -std=c++23 -O1 -g -Wall -Wextra -Werror -Isrc
MOLO_ALL =
MOLO_TEST_BINS =
MOLO_INTEROP =
# Default goal is `all`: these are the first ordinary targets in this file.
all::
test::
clean::
rm -rf build
# Operability first: supervisor.mk and cli.mk reference OPERABILITY_LIB.
-include src/operability.mk
-include src/runtime/runtime.mk
-include src/observability/observability.mk
-include src/security/security.mk
-include src/data/data.mk
-include src/app/app.mk
-include src/realtime/realtime.mk
-include src/supervisor/supervisor.mk
-include src/clients/clients.mk
# NOTE: supplychain.mk and operability.mk precede cli.mk and supervisor.mk
# so SUPPLY_LIB / OPERABILITY_LIB are defined when those add link edges
# (supply PATCHES section 2, operability PATCHES sections 5-6 and 10).
-include src/supplychain.mk
-include src/cli/cli.mk
-include src/tenancy.mk
-include src/audit.mk
-include src/governance.mk
-include example/example.mk
# --- all wiring (INTEGRATION; supervisor/example self-append via all::) ---
all:: $(MOLO_ALL)
all:: $(OBS_LIB)
all:: security-all
all:: data-all
all:: app-build
all:: $(REALTIME_LIB)
all:: clients
all:: $(MOLO_BIN)
all:: tenancy-tests
all:: audit-tests
all:: operability-tests
all:: govern-build
all:: supply-all
# --- test wiring (INTEGRATION; supervisor/example self-append via test::) --
test:: $(MOLO_TEST_BINS)
set -e; for t in $(MOLO_TEST_BINS); do ./$$t; done
test:: obs-test
test:: security-test
test:: data-test
test:: app-test
test:: realtime-test
test:: clients-test
test:: cli-test
test:: tenancy-check
test:: audit-check
test:: operability-check
test:: govern-test
test:: supply-test
# --- data rules (INTEGRATION: data.mk ships variables only, no rules) ------
# Mirrors the verified standalone flags (src/data/Makefile): header-only
# lib, one binary per suite, -Isrc/data -Itests/src/data.
DATA_BINS = $(addprefix build/data/test_,$(DATA_TESTS))
data-all: $(DATA_BINS)
build/data/test_%: tests/src/data/test_%.cpp $(DATA_HEADERS) tests/src/data/mini.hpp
@mkdir -p build/data
$(CXX) $(CXXFLAGS) -Isrc/data -Itests/src/data $< -o $@
data-test: data-all
@for t in $(DATA_BINS); do echo "== $$t"; ./$$t || exit 1; done
@echo "data: all suites green"
data-clean:
rm -rf build/data
# --- realtime test runner (INTEGRATION: realtime.mk ships bins, no runner) --
realtime-test: $(REALTIME_TESTS)
@pass=0; fail=0; \
for t in $(REALTIME_TESTS); do \
if ./$$t; then pass=$$((pass+1)); else fail=$$((fail+1)); \
echo "FAIL: $$t"; fi; \
done; \
echo "realtime tests passed=$$pass failed=$$fail"; \
test $$fail -eq 0
# --- cli main object (INTEGRATION: cli.mk's build/obj/%.o pattern cannot ----
# derive build/obj/src/cli/main.cpp.o from src/cli/main.cpp, since the stem
# would require a nonexistent src/cli/main.cpp.cpp. Explicit edge fixes it;
# `make -f src/cli/cli.mk -n build/obj/src/cli/main.cpp.o` fails without it.
$(CLI_MAIN_OBJ): src/cli/main.cpp
@mkdir -p $(dir $@)
$(CXX) $(CXXFLAGS) $(CLI_INC) -c $< -o $@
# --- interop (runtime loopback servers; kept out of `test` per the ---------
# runtime author's own split between `test` and `interop`) ------------------
interop: $(MOLO_ALL)
set -e; for t in $(MOLO_INTEROP); do $(MAKE) $$t; done
# --- lint (referenced by AGENTS.md; falls back to the warning-free build) --
lint: all
@if grep -rl --exclude-dir=build "$$(printf '\342\200\224')" src tests example Makefile 2>/dev/null; then \
echo "lint: em dash found"; exit 1; \
else echo "lint: no em dash, build warning-free"; fi
# --- audit test runner (INTEGRATION: audit.mk builds bins, no runner) ---------
audit-check: audit-tests
@for t in $(AUDIT_TEST_BINS); do echo "== $$t"; ./$$t || exit 1; done
@echo "audit: all suites green"
# --- operability production link (INTEGRATION: with the base tree present ---
# the real supervisor/common Clock/KvStore/Observer satisfy the includes, so
# their TU definitions ride along on the test link lines).
OPERABILITY_TEST_SRCS += src/supervisor/common/clock.cpp
OPERABILITY_TEST_SRCS += src/supervisor/common/kv_store.cpp
OPERABILITY_TEST_SRCS += src/supervisor/common/observer.cpp
.PHONY: all test clean interop lint data-all data-test data-clean realtime-test cli-test audit-check
+21
View File
@@ -0,0 +1,21 @@
name: moloapp
services:
postgres:
image: postgres:18
container_name: moloapp-postgres
restart: unless-stopped
environment:
POSTGRES_USER: molo
POSTGRES_PASSWORD: molo
POSTGRES_DB: molo_test
ports:
- "127.0.0.1:5432:5432"
volumes:
- moloapp-pgdata:/var/lib/postgresql
healthcheck:
test: ["CMD-SHELL", "pg_isready -U molo -d molo_test"]
interval: 5s
timeout: 3s
retries: 12
volumes:
moloapp-pgdata:
+93
View File
@@ -0,0 +1,93 @@
# 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
```
Open `http://127.0.0.1:8080/` and click through the matrix. Narrow the
window to 360px: the top nav collapses into a dropdown menu.
Run the suite (37 route-level integration tests, real stack, no mocks):
```sh
make -f example/example.mk example-test
```
## 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` |
## 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)
tests/example/ # route-level integration tests mirroring URLs
```
+85
View File
@@ -0,0 +1,85 @@
# 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.
+53
View File
@@ -0,0 +1,53 @@
#include "App.hpp"
namespace molo::example::app {
std::shared_ptr<fw::Application> build_application(Services& services) {
seed_services(services);
load_templates(services);
load_embedded(services);
auto app = std::make_shared<fw::Application>();
app->use(fw::MiddlewareSlot::Errors, fw::errors_middleware());
app->use(fw::MiddlewareSlot::Observability, fw::request_id_middleware());
app->use(fw::MiddlewareSlot::SessionAuth,
[](fw::Request req, fw::Next next) -> fw::Response {
fw::Response res = next(std::move(req));
res.headers.set("X-Frame-Options", "DENY");
res.headers.set("X-Content-Type-Options", "nosniff");
return res;
});
fw::Router index;
register_index(index, services);
app->include_router("", index);
fw::Router routing;
register_routing_demo(routing, services);
app->include_router("/routing", routing, "routing.");
fw::Router data;
register_data_demo(data, services);
app->include_router("", data);
fw::Router security;
register_security_demo(security, services);
app->include_router("", security);
fw::Router formats;
register_formats_demo(formats, services);
app->include_router("", formats);
fw::Router realtime;
register_realtime_demo(realtime, services);
app->include_router("", realtime);
fw::Router ops;
register_ops_demo(ops, services);
app->include_router("", ops);
register_chain_demo(app, services);
return app;
}
} // namespace molo::example::app
+69
View File
@@ -0,0 +1,69 @@
#pragma once
// Demo application assembly: shared Services (the DI skeleton), the root
// Application with middleware, routers, and mounted sub-applications.
// Gap: real molo::di::Container and plugin registry in 05-request-routing.md.
#include <map>
#include <memory>
#include <string>
#include "../fw/App.hpp"
#include "../fw/Data.hpp"
#include "../fw/Jobs.hpp"
#include "../fw/Kv.hpp"
#include "../fw/Net.hpp"
#include "../fw/Observ.hpp"
#include "../fw/Templates.hpp"
namespace molo::example::app {
struct Services {
std::shared_ptr<fw::KvStore> kv = std::make_shared<fw::KvStore>();
std::shared_ptr<fw::Cache> cache = std::make_shared<fw::Cache>();
std::shared_ptr<fw::Pubsub> pubsub = std::make_shared<fw::Pubsub>();
std::shared_ptr<fw::EventBus> events = std::make_shared<fw::EventBus>();
std::shared_ptr<fw::Metrics> metrics = std::make_shared<fw::Metrics>();
std::shared_ptr<fw::Telemetry> telemetry =
std::make_shared<fw::Telemetry>();
std::shared_ptr<fw::SessionStore> sessions =
std::make_shared<fw::SessionStore>();
std::shared_ptr<fw::Auth> auth = std::make_shared<fw::Auth>();
std::shared_ptr<fw::OrmDb> sqlite =
std::make_shared<fw::OrmDb>(fw::OrmBackend::Sqlite);
std::shared_ptr<fw::OrmDb> postgres =
std::make_shared<fw::OrmDb>(fw::OrmBackend::Postgres);
std::shared_ptr<fw::UploadStore> uploads =
std::make_shared<fw::UploadStore>();
std::shared_ptr<fw::WebdavStore> webdav =
std::make_shared<fw::WebdavStore>();
std::shared_ptr<fw::Supervisor> supervisor =
std::make_shared<fw::Supervisor>();
std::shared_ptr<fw::TaskQueue> tasks = std::make_shared<fw::TaskQueue>();
std::shared_ptr<fw::ReplicationLog> repl =
std::make_shared<fw::ReplicationLog>();
std::shared_ptr<fw::OpenApi> openapi = std::make_shared<fw::OpenApi>();
std::shared_ptr<fw::Environment> templates =
std::make_shared<fw::Environment>();
std::map<std::string, std::string> embedded;
std::string static_root = "example/static";
std::string cookie_secret = "living-example-secret";
};
std::shared_ptr<fw::Application> build_application(Services& services);
void register_index(fw::Router& router, Services& services);
void register_routing_demo(fw::Router& router, Services& services);
void register_chain_demo(std::shared_ptr<fw::Application> app,
Services& services);
void register_data_demo(fw::Router& router, Services& services);
void register_security_demo(fw::Router& router, Services& services);
void register_formats_demo(fw::Router& router, Services& services);
void register_realtime_demo(fw::Router& router, Services& services);
void register_ops_demo(fw::Router& router, Services& services);
void load_templates(Services& services);
void load_embedded(Services& services);
void seed_services(Services& services);
} // namespace molo::example::app
+141
View File
@@ -0,0 +1,141 @@
#include "App.hpp"
#include "../fw/Http.hpp"
#include "../fw/Router.hpp"
#include "../fw/Validate.hpp"
namespace molo::example::app {
namespace {
fw::OrmDb* pick_db(Services& services, const fw::Request& req) {
if (fw::parse_backend(req.query_or("backend", "sqlite")) ==
fw::OrmBackend::Postgres)
return services.postgres.get();
return services.sqlite.get();
}
std::string rows_json(const std::vector<fw::OrmRow>& rows) {
std::string out = "[";
bool first = true;
for (const auto& r : rows) {
if (!first) out += ",";
first = false;
out += "{";
bool fc = true;
for (const auto& [k, v] : r.columns) {
if (!fc) out += ",";
fc = false;
out += "\"" + fw::json_escape(k) + "\":\"" + fw::json_escape(v) + "\"";
}
out += "}";
}
return out + "]";
}
} // namespace
void register_data_demo(fw::Router& router, Services& services) {
fw::OrmDb* sqlite = services.sqlite.get();
fw::OrmDb* postgres = services.postgres.get();
fw::KvStore* kv = services.kv.get();
fw::Cache* cache = services.cache.get();
fw::Pubsub* pubsub = services.pubsub.get();
router.get("/orm/users", "orm-users", [sqlite, postgres](fw::Request req) {
fw::OrmDb* db = req.query_or("backend", "sqlite") == "postgres" ? postgres
: sqlite;
fw::OrmResult res = db->select_all("users");
std::string body = "{\"backend\":\"" + fw::backend_name(db->backend()) +
"\",\"healed\":" + (res.healed ? "true" : "false") +
",\"note\":\"" + fw::json_escape(res.healed_note) +
"\",\"rows\":" + rows_json(res.rows) + "}";
return fw::JsonResponse(body, 200);
});
router.post("/orm/users", "orm-users-post",
[sqlite, postgres](fw::Request req) {
fw::OrmDb* db = req.query_or("backend", "sqlite") == "postgres"
? postgres
: sqlite;
auto input = fw::parse_json_object_flat(req.body);
if (input.empty()) input = fw::parse_form(req.body);
fw::OrmResult res = db->insert("users", input);
if (!res.ok)
return fw::JsonResponse("{\"error\":\"store full\"}", 500);
std::string body =
"{\"backend\":\"" + fw::backend_name(db->backend()) +
"\",\"healed\":" + (res.healed ? "true" : "false") +
",\"note\":\"" + fw::json_escape(res.healed_note) +
"\",\"rows\":" + rows_json(res.rows) + "}";
return fw::JsonResponse(body, 201);
});
router.get("/kv/items", "kv-get", [kv](fw::Request req) {
std::string key = req.query_or("key", "");
if (key.empty()) return fw::JsonResponse("{\"error\":\"key required\"}", 400);
std::string value;
if (!kv->get(key, value))
return fw::JsonResponse("{\"error\":\"not found\"}", 404);
return fw::JsonResponse("{\"key\":\"" + fw::json_escape(key) +
"\",\"value\":\"" + fw::json_escape(value) +
"\"}",
200);
});
router.post("/kv/items", "kv-set", [kv](fw::Request req) {
auto input = fw::parse_json_object_flat(req.body);
if (input.empty()) input = fw::parse_form(req.body);
if (!input.count("key") || !input.count("value"))
return fw::JsonResponse("{\"error\":\"key and value required\"}", 400);
if (!kv->set(input["key"], input["value"]))
return fw::JsonResponse("{\"error\":\"store full\"}", 500);
return fw::JsonResponse("{\"stored\":\"" + fw::json_escape(input["key"]) +
"\"}",
201);
});
router.get("/cache/lookup", "cache", [cache](fw::Request req) {
std::string key = req.query_or("key", "demo");
std::string value;
bool hit = cache->lookup(key, value, 1000);
if (!hit) {
value = "computed-for-" + key;
cache->put(key, value, 60, 1000);
return fw::JsonResponse(
"{\"key\":\"" + fw::json_escape(key) + "\",\"hit\":false,\"value\":\"" +
fw::json_escape(value) + "\"}",
200);
}
return fw::JsonResponse(
"{\"key\":\"" + fw::json_escape(key) + "\",\"hit\":true,\"value\":\"" +
fw::json_escape(value) + "\"}",
200);
});
router.post("/pubsub/publish", "pubsub", [pubsub](fw::Request req) {
auto input = fw::parse_json_object_flat(req.body);
if (input.empty()) input = fw::parse_form(req.body);
std::string topic = input.count("topic") ? input["topic"] : "news";
std::string message = input.count("message") ? input["message"] : "hello";
std::size_t delivered = pubsub->publish(topic, message);
return fw::JsonResponse("{\"topic\":\"" + fw::json_escape(topic) +
"\",\"delivered\":" +
std::to_string(delivered) + "}",
200);
});
router.get("/pubsub/publish", "pubsub-history", [pubsub](fw::Request req) {
std::string topic = req.query_or("topic", "news");
auto hist = pubsub->history(topic);
std::string body = "{\"topic\":\"" + fw::json_escape(topic) +
"\",\"history\":[";
bool first = true;
for (const auto& m : hist) {
if (!first) body += ",";
first = false;
body += "\"" + fw::json_escape(m) + "\"";
}
return fw::JsonResponse(body + "]}", 200);
});
(void)pick_db;
}
} // namespace molo::example::app
+19
View File
@@ -0,0 +1,19 @@
#include "App.hpp"
namespace molo::example::app {
namespace {
// Byte-identical reproducible bundle. Production bundles are generated by
// the asset embedder CLI (09-cli-ops.md); this hand-written copy proves the
// serving path with sorted names and no timestamps.
} // namespace
void load_embedded(Services& services) {
services.embedded["/app.css"] =
"/* embedded bundle */\nbody{font-family:sans-serif}\n";
services.embedded["/hello.txt"] = "hello from embedded assets\n";
}
} // namespace molo::example::app
+131
View File
@@ -0,0 +1,131 @@
#include "App.hpp"
#include "../fw/Negotiate.hpp"
#include "../fw/Router.hpp"
#include "../fw/StaticFiles.hpp"
#include "../fw/Templates.hpp"
#include "../fw/Validate.hpp"
namespace molo::example::app {
namespace {
fw::Model contact_model() {
return fw::Model(
{{"name", fw::FieldType::String, true, 1, 80, 0, 0, false, ""},
{"email", fw::FieldType::Email, true, 3, 120, 0, 0, false, ""},
{"message", fw::FieldType::String, true, 1, 2000, 0, 0, false, ""}});
}
fw::Model user_model() {
fw::Field age{"age", fw::FieldType::Integer, true, 0, 0, 0, 150, true, ""};
return fw::Model(
{{"username", fw::FieldType::String, true, 3, 40, 0, 0, false, ""},
{"email", fw::FieldType::Email, true, 3, 120, 0, 0, false, ""},
age});
}
} // namespace
void register_formats_demo(fw::Router& router, Services& services) {
fw::Environment* env = services.templates.get();
std::map<std::string, std::string> embedded = services.embedded;
std::string static_root = services.static_root;
router.get("/templates/page", "template-page", [env](fw::Request req) {
(void)req;
fw::TemplateCtx ctx;
ctx["title"] = std::string("Templates");
ctx["heading"] = std::string("Template demo");
ctx["author"] = std::string("ada");
ctx["snippet"] = std::string("<b>bold</b>");
fw::TemplateList items;
items.push_back({{"name", "extends"}, {"kind", "inheritance"}});
items.push_back({{"name", "include"}, {"kind", "partial"}});
items.push_back({{"name", "for"}, {"kind", "loop"}});
ctx["items"] = items;
return fw::Response(200, env->render("page.html", ctx),
"text/html; charset=utf-8");
});
router.get("/formats/data", "formats", [](fw::Request req) {
std::vector<std::string> offers = {"application/json", "application/xml",
"text/html", "text/plain"};
std::string pick =
fw::negotiate(req.headers.get("Accept"), offers);
if (pick == "application/json")
return fw::Response(
200, "{\"format\":\"json\",\"value\":42}", "application/json");
if (pick == "application/xml")
return fw::Response(200, "<data><value>42</value></data>",
"application/xml");
if (pick == "text/html")
return fw::Response(200, "<p>value: 42</p>",
"text/html; charset=utf-8");
return fw::Response(200, "value: 42", "text/plain; charset=utf-8");
});
router.get("/forms/contact", "contact-get", [env](fw::Request req) {
(void)req;
fw::TemplateCtx ctx;
ctx["title"] = std::string("Contact");
ctx["posted"] = std::string("");
ctx["name"] = std::string("");
ctx["email"] = std::string("");
ctx["message"] = std::string("");
return fw::Response(200, env->render("contact.html", ctx),
"text/html; charset=utf-8");
});
router.post("/forms/contact", "contact-post", [env](fw::Request req) {
fw::Form form(contact_model());
fw::TemplateCtx ctx;
ctx["title"] = std::string("Contact");
try {
auto clean = form.bind(req);
ctx["posted"] = std::string("true");
ctx["name"] = clean["name"];
ctx["email"] = clean["email"];
ctx["message"] = clean["message"];
} catch (const fw::ValidationError& e) {
ctx["posted"] = std::string("");
auto input = fw::parse_form(req.body);
ctx["name"] = input.count("name") ? input["name"] : "";
ctx["email"] = input.count("email") ? input["email"] : "";
ctx["message"] = input.count("message") ? input["message"] : "";
ctx["error"] = e.to_json();
return fw::Response(422, env->render("contact.html", ctx),
"text/html; charset=utf-8");
}
return fw::Response(200, env->render("contact.html", ctx),
"text/html; charset=utf-8");
});
router.post("/validate/user", "validate-user", [](fw::Request req) {
fw::Model model = user_model();
auto input = fw::parse_json_object_flat(req.body);
if (input.empty()) input = fw::parse_form(req.body);
try {
auto clean = model.validate(input);
return fw::JsonResponse(
"{\"ok\":true,\"username\":\"" +
fw::json_escape(clean["username"]) + "\"}",
200);
} catch (const fw::ValidationError& e) {
return fw::JsonResponse(e.to_json(), 422);
}
});
router.get("/static/{name}", "static", [static_root](fw::Request req) {
return fw::serve_disk_file(static_root, req.param_or("name", ""));
});
router.get("/embedded/{name}", "embedded", [embedded](fw::Request req) {
return fw::serve_embedded(embedded, req.param_or("name", ""));
});
router.get("/redirect/here", "redirect", [](fw::Request req) {
bool permanent = req.query_or("mode", "temp") == "perm";
return fw::Response(fw::RedirectResponse("/health", permanent));
});
}
} // namespace molo::example::app
+75
View File
@@ -0,0 +1,75 @@
#include "App.hpp"
#include "../fw/Http.hpp"
#include "../fw/Router.hpp"
#include "../fw/Templates.hpp"
namespace molo::example::app {
namespace {
const char* kFeatures[][2] = {
{"routing", "/routing/hello/world"},
{"views", "/views/greet"},
{"routers", "/routers/nested/deep"},
{"chaining", "/app1/app1/app1/whoami"},
{"orm-sqlite", "/orm/users?backend=sqlite"},
{"orm-postgres", "/orm/users?backend=postgres"},
{"auth", "/auth/me"},
{"sessions", "/sessions/counter"},
{"forms", "/forms/contact"},
{"validation", "/validate/user"},
{"templates", "/templates/page"},
{"formats", "/formats/data"},
{"static", "/static/app.css"},
{"embedded", "/embedded/hello.txt"},
{"streaming", "/streaming/feed"},
{"passthrough", "/streaming/passthrough"},
{"websocket", "/ws/chat"},
{"socketio", "/socketio/rooms"},
{"sse", "/sse/events"},
{"pubsub", "/pubsub/publish"},
{"events", "/events/fire"},
{"metrics", "/metrics/counters"},
{"telemetry", "/telemetry/trace"},
{"kv", "/kv/items"},
{"cache", "/cache/lookup"},
{"uploads", "/uploads/file"},
{"webdav", "/webdav/files/"},
{"replication", "/replication/state"},
{"tasks", "/supervisor/tasks"},
{"workers", "/supervisor/workers"},
{"restclient", "/restclient/self"},
{"openapi", "/openapi.json"},
{"docs", "/docs"},
{"ai", "/cli/ai"},
{"workflow", "/workflow/release"},
{"redirect", "/redirect/here"},
{"health", "/health"},
};
} // namespace
void register_index(fw::Router& router, Services& services) {
fw::Environment* env = services.templates.get();
router.get("/", "index", [env](fw::Request req) {
fw::TemplateCtx ctx;
ctx["title"] = std::string("MoloApp living example");
ctx["show_matrix"] = std::string("true");
fw::TemplateList rows;
for (const auto& [feature, route] : kFeatures) {
rows.push_back({{"feature", feature}, {"route", route}});
}
ctx["matrix"] = rows;
(void)req;
return fw::Response(200, env->render("index.html", ctx),
"text/html; charset=utf-8");
});
router.get("/health", "health", [](fw::Request req) {
(void)req;
return fw::JsonResponse(
"{\"status\":\"ok\",\"tls\":\"stub-no-wolfssl\"}", 200);
});
}
} // namespace molo::example::app
+224
View File
@@ -0,0 +1,224 @@
#include "App.hpp"
#include "../fw/Jobs.hpp"
#include "../fw/Net.hpp"
#include "../fw/Observ.hpp"
#include "../fw/Router.hpp"
#include "../fw/Templates.hpp"
#include "../fw/Validate.hpp"
#include "../fw/Workflow.hpp"
namespace molo::example::app {
void register_ops_demo(fw::Router& router, Services& services) {
fw::EventBus* events = services.events.get();
fw::Metrics* metrics = services.metrics.get();
fw::Telemetry* telemetry = services.telemetry.get();
fw::Supervisor* supervisor = services.supervisor.get();
fw::TaskQueue* tasks = services.tasks.get();
fw::ReplicationLog* repl = services.repl.get();
fw::OpenApi* openapi = services.openapi.get();
fw::Environment* env = services.templates.get();
router.post("/events/fire", "events-fire", [events](fw::Request req) {
auto input = fw::parse_json_object_flat(req.body);
if (input.empty()) input = fw::parse_form(req.body);
std::string type = input.count("type") ? input["type"] : "demo.ping";
std::string payload =
input.count("payload") ? input["payload"] : "ping";
events->emit({type, payload, req.correlation_id});
return fw::JsonResponse(
"{\"fired\":\"" + fw::json_escape(type) + "\"}", 200);
});
router.get("/events/fire", "events-list", [events](fw::Request req) {
(void)req;
auto delivered = events->delivered();
std::string body = "{\"delivered\":[";
bool first = true;
for (const auto& e : delivered) {
if (!first) body += ",";
first = false;
body += "{\"type\":\"" + fw::json_escape(e.type) + "\",\"payload\":\"" +
fw::json_escape(e.payload) + "\"}";
}
return fw::JsonResponse(body + "]}", 200);
});
router.get("/metrics/counters", "metrics",
[metrics](fw::Request req) {
(void)req;
metrics->inc("example.page.views");
fw::Response res(200, metrics->render_prometheus(),
"text/plain; version=0.0.4");
return res;
});
router.get("/telemetry/trace", "telemetry",
[telemetry](fw::Request req) {
fw::Span span =
telemetry->start_span("demo", req.correlation_id);
telemetry->finish_span(span);
return fw::JsonResponse(
"{\"trace\":\"" + fw::json_escape(span.trace_id) +
"\",\"span\":\"" + fw::json_escape(span.span_id) +
"\",\"correlation\":\"" +
fw::json_escape(req.correlation_id) + "\"}",
200);
});
router.get("/replication/state", "repl", [repl](fw::Request req) {
unsigned long since = 0;
try {
since = (unsigned long)std::stoul(req.query_or("since", "0"));
} catch (...) {
since = 0;
}
auto entries = repl->since(since);
std::string body = "{\"latest\":" + std::to_string(repl->latest()) +
",\"entries\":[";
bool first = true;
for (const auto& e : entries) {
if (!first) body += ",";
first = false;
body += "{\"seq\":" + std::to_string(e.seq) + ",\"object\":\"" +
fw::json_escape(e.object) + "\",\"resolution\":\"" +
fw::json_escape(e.resolution) + "\"}";
}
return fw::JsonResponse(body + "]}", 200);
});
router.post("/replication/state", "repl-append", [repl](fw::Request req) {
auto input = fw::parse_json_object_flat(req.body);
if (input.empty()) input = fw::parse_form(req.body);
std::string object = input.count("object") ? input["object"] : "doc-1";
std::string data = input.count("data") ? input["data"] : "{}";
fw::ReplEntry e = repl->append(object, data);
return fw::JsonResponse("{\"seq\":" + std::to_string(e.seq) +
",\"resolution\":\"" +
fw::json_escape(e.resolution) + "\"}",
201);
});
router.get("/supervisor/tasks", "tasks-list", [tasks](fw::Request req) {
(void)req;
std::string body = "{\"tasks\":[";
bool first = true;
for (const auto& t : tasks->list()) {
if (!first) body += ",";
first = false;
body += "{\"id\":\"" + fw::json_escape(t.id) + "\",\"state\":\"" +
fw::json_escape(t.state) + "\"}";
}
return fw::JsonResponse(body + "]}", 200);
});
router.post("/supervisor/tasks", "tasks-enqueue", [tasks](fw::Request req) {
auto input = fw::parse_json_object_flat(req.body);
if (input.empty()) input = fw::parse_form(req.body);
std::string kind = input.count("kind") ? input["kind"] : "email";
std::string payload =
input.count("payload") ? input["payload"] : "{}";
std::string id = tasks->enqueue(kind, payload, 0);
if (id.empty()) return fw::JsonResponse("{\"error\":\"queue full\"}", 500);
return fw::JsonResponse("{\"id\":\"" + fw::json_escape(id) + "\"}", 201);
});
router.get("/supervisor/workers", "workers",
[supervisor](fw::Request req) {
(void)req;
std::string body = "{\"workers\":[";
bool first = true;
for (const auto& w : supervisor->status()) {
if (!first) body += ",";
first = false;
body += "{\"name\":\"" + fw::json_escape(w.name) +
"\",\"running\":" +
(w.running ? "true" : "false") + ",\"restarts\":" +
std::to_string(w.restarts) + "}";
}
return fw::JsonResponse(body + "]}", 200);
});
router.get("/restclient/self", "restclient", [](fw::Request req) {
(void)req;
fw::RestClient client([](fw::Request r) {
(void)r;
return fw::JsonResponse("{\"status\":\"ok\"}", 200);
});
fw::Response upstream = client.get("/health");
return fw::JsonResponse(
"{\"self_call\":" + std::to_string(upstream.status) + "}", 200);
});
openapi->add("/health", "get", "health probe");
openapi->add("/orm/users", "get", "list users");
openapi->add("/validate/user", "post", "validate user model");
router.get("/openapi.json", "openapi", [openapi](fw::Request req) {
(void)req;
return fw::Response(200, openapi->to_json(), "application/json");
});
router.get("/docs", "docs", [env, openapi](fw::Request req) {
(void)req;
(void)openapi;
fw::TemplateCtx ctx;
ctx["title"] = std::string("API docs");
fw::TemplateList rows;
rows.push_back({{"method", "GET"},
{"path", "/health"},
{"summary", "health probe"}});
rows.push_back({{"method", "GET"},
{"path", "/orm/users"},
{"summary", "list users"}});
rows.push_back({{"method", "POST"},
{"path", "/validate/user"},
{"summary", "validate user model"}});
ctx["routes"] = rows;
return fw::Response(200, env->render("docs.html", ctx),
"text/html; charset=utf-8");
});
router.get("/cli/ai", "ai", [](fw::Request req) {
std::string prompt = req.query_or("prompt", "add a route");
fw::AiSample sample = fw::ai_harness_sample(prompt);
std::string body = "{\"base_url\":\"" + sample.base_url +
"\",\"model\":\"" + sample.model +
"\",\"prompt\":\"" +
fw::json_escape(sample.redacted_prompt) +
"\",\"stream_events\":" +
std::to_string(sample.stream_chunks.size()) + "}";
return fw::JsonResponse(body, 200);
});
router.post("/workflow/release", "workflow", [](fw::Request req) {
auto input = fw::parse_json_object_flat(req.body);
if (input.empty()) input = fw::parse_form(req.body);
std::string subjects = input.count("commits") ? input["commits"] : "";
std::vector<fw::CommitInfo> commits;
std::size_t start = 0;
while (start < subjects.size()) {
std::size_t bar = subjects.find('|', start);
std::string one =
subjects.substr(start, bar == std::string::npos ? bar : bar - start);
fw::CommitInfo info;
std::string error;
if (!fw::parse_commit(one, "", info, error))
return fw::JsonResponse(
"{\"error\":\"bad commit: " + fw::json_escape(error) + "\"}",
400);
commits.push_back(info);
if (bar == std::string::npos) break;
start = bar + 1;
}
fw::ReleasePlanner planner;
fw::ChangelogWriter writer;
fw::ReleaseVerifier verifier;
verifier.add_check("suite", true, "example suite green");
verifier.add_check("live", true, "health probe ok");
std::string version = planner.next_version("0.1.0", commits);
std::string body =
"{\"bump\":\"" + fw::bump_name(planner.decide(commits)) +
"\",\"version\":\"" + version + "\",\"green\":" +
(verifier.green() ? "true" : "false") + ",\"changelog\":\"" +
fw::json_escape(writer.entry(version, "2026-10-23", commits)) + "\"}";
return fw::JsonResponse(body, 200);
});
}
} // namespace molo::example::app
+93
View File
@@ -0,0 +1,93 @@
#include "App.hpp"
#include "../fw/Data.hpp"
#include "../fw/Router.hpp"
#include "../fw/Validate.hpp"
namespace molo::example::app {
// Realtime demos answer over plain HTTP in the skeleton: the WebSocket and
// Socket.IO endpoints describe the upgrade contract and echo posted frames,
// SSE streams real event text. Gap: real framing, namespaces, rooms, and
// long-polling fallback in 06-realtime.md plus matching clients.
void register_realtime_demo(fw::Router& router, Services& services) {
fw::WebdavStore* webdav = services.webdav.get();
router.get("/streaming/feed", "stream", [](fw::Request req) {
(void)req;
return fw::Response(
fw::StreamingResponse({"chunk-1\n", "chunk-2\n", "chunk-3\n"}));
});
router.get("/streaming/passthrough", "passthrough", [](fw::Request req) {
std::string target = req.query_or("target", "/health");
return fw::Response(fw::StreamingResponse(
{"passthrough from " + target + "\n", "{\"status\":\"ok\"}\n"}));
});
router.get("/ws/chat", "ws", [](fw::Request req) {
std::string upgrade = req.headers.get("Upgrade");
if (upgrade == "websocket")
return fw::JsonResponse(
"{\"upgraded\":false,\"note\":\"skeleton: echo over POST\"}", 200);
return fw::JsonResponse(
"{\"protocol\":\"websocket\",\"path\":\"/ws/chat\",\"upgrade\":"
"\"send Upgrade: websocket\"}",
200);
});
router.post("/ws/chat", "ws-echo", [](fw::Request req) {
return fw::JsonResponse(
"{\"echo\":\"" + fw::json_escape(req.body) + "\"}", 200);
});
router.get("/socketio/rooms", "socketio", [](fw::Request req) {
(void)req;
return fw::JsonResponse(
"{\"protocol\":\"socket.io\",\"namespaces\":[\"/\"],\"rooms\":["
"\"lobby\"],\"fallback\":\"long-polling\"}",
200);
});
router.post("/socketio/rooms", "socketio-emit", [](fw::Request req) {
auto input = fw::parse_json_object_flat(req.body);
if (input.empty()) input = fw::parse_form(req.body);
std::string room = input.count("room") ? input["room"] : "lobby";
std::string event = input.count("event") ? input["event"] : "message";
return fw::JsonResponse("{\"emitted\":\"" + fw::json_escape(event) +
"\",\"room\":\"" + fw::json_escape(room) +
"\",\"ack\":true}",
200);
});
router.get("/sse/events", "sse", [](fw::Request req) {
(void)req;
return fw::Response(
fw::SseResponse({"hello", "tick", "goodbye"}));
});
router.any({fw::Method::Propfind}, "/webdav/files/", "webdav-propfind",
[webdav](fw::Request req) {
(void)req;
return fw::Response(207, webdav->propfind_xml("/files/"),
"application/xml");
});
router.any({fw::Method::Get}, "/webdav/files/{name}", "webdav-get",
[webdav](fw::Request req) -> fw::Response {
std::string content;
if (!webdav->get("/files/" + req.param_or("name", ""), content))
return fw::JsonResponse("{\"error\":\"not found\"}", 404);
return fw::TextResponse(content, 200);
});
router.any({fw::Method::Put}, "/webdav/files/{name}", "webdav-put",
[webdav](fw::Request req) {
webdav->put("/files/" + req.param_or("name", ""), req.body);
return fw::JsonResponse("{\"stored\":true}", 201);
});
router.any({fw::Method::Delete}, "/webdav/files/{name}", "webdav-delete",
[webdav](fw::Request req) {
if (!webdav->remove("/files/" + req.param_or("name", "")))
return fw::JsonResponse("{\"error\":\"not found\"}", 404);
return fw::JsonResponse("{\"deleted\":true}", 200);
});
}
} // namespace molo::example::app
+80
View File
@@ -0,0 +1,80 @@
#include "App.hpp"
#include "../fw/Router.hpp"
#include "../fw/View.hpp"
namespace molo::example::app {
namespace {
class GreetView : public fw::View {
public:
using fw::View::View;
fw::Response get() override {
return fw::JsonResponse(
"{\"view\":\"GreetView\",\"method\":\"GET\",\"name\":\"" +
fw::json_escape(req_.query_or("name", "stranger")) + "\"}",
200);
}
fw::Response post() override {
auto form = fw::parse_form(req_.body);
auto it = form.find("name");
std::string name = it == form.end() ? "stranger" : it->second;
return fw::JsonResponse(
"{\"view\":\"GreetView\",\"method\":\"POST\",\"name\":\"" +
fw::json_escape(name) + "\"}",
200);
}
};
} // namespace
void register_routing_demo(fw::Router& router, Services& services) {
(void)services;
router.get("/hello/{name}", "hello", [](fw::Request req) {
return fw::JsonResponse(
"{\"hello\":\"" + fw::json_escape(req.param_or("name", "")) + "\"}",
200);
});
fw::Router views;
views.get("/greet", "greet", [](fw::Request req) {
GreetView view(std::move(req));
return view.dispatch();
});
views.post("/greet", "greet-post", [](fw::Request req) {
GreetView view(std::move(req));
return view.dispatch();
});
router.include_router("/views", views, "views.");
fw::Router nested;
nested.get("/deep", "deep", [](fw::Request req) {
(void)req;
return fw::JsonResponse("{\"nested\":true}", 200);
});
fw::Router middle;
middle.include_router("/nested", nested, "nested.");
router.include_router("/routers", middle, "routers.");
}
void register_chain_demo(std::shared_ptr<fw::Application> app,
Services& services) {
(void)services;
auto leaf = std::make_shared<fw::Application>();
fw::Router r;
r.get("/whoami", "whoami", [](fw::Request req) {
(void)req;
return fw::JsonResponse("{\"depth\":3,\"path\":\"/app1/app1/app1\"}", 200);
});
leaf->include_router("", r);
auto mid = std::make_shared<fw::Application>();
mid->mount("/app1", leaf);
auto top = std::make_shared<fw::Application>();
top->mount("/app1", mid);
app->mount("/app1", top);
}
} // namespace molo::example::app
+93
View File
@@ -0,0 +1,93 @@
#include "App.hpp"
#include "../fw/Cookies.hpp"
#include "../fw/Data.hpp"
#include "../fw/Router.hpp"
#include "../fw/Validate.hpp"
namespace molo::example::app {
void register_security_demo(fw::Router& router, Services& services) {
fw::Auth* auth = services.auth.get();
fw::SessionStore* sessions = services.sessions.get();
fw::UploadStore* uploads = services.uploads.get();
std::string secret = services.cookie_secret;
router.get("/auth/me", "auth-me", [auth](fw::Request req) {
std::string user, password;
if (!fw::parse_basic_auth(req.headers.get("Authorization"), user,
password))
return fw::JsonResponse("{\"error\":\"basic auth required\"}", 401);
if (!auth->check(user, password))
return fw::JsonResponse("{\"error\":\"bad credentials\"}", 403);
return fw::JsonResponse(
"{\"user\":\"" + fw::json_escape(user) + "\"}", 200);
});
router.post("/auth/login", "auth-login", [auth](fw::Request req) {
auto input = fw::parse_json_object_flat(req.body);
if (input.empty()) input = fw::parse_form(req.body);
if (!input.count("username") || !input.count("password"))
return fw::JsonResponse("{\"error\":\"username and password required\"}",
400);
if (!auth->check(input["username"], input["password"]))
return fw::JsonResponse("{\"error\":\"bad credentials\"}", 403);
return fw::JsonResponse(
"{\"user\":\"" + fw::json_escape(input["username"]) + "\"}", 200);
});
router.get("/sessions/counter", "session-counter",
[sessions, secret](fw::Request req) {
std::string raw = req.cookie_or("session", "");
std::string id;
std::map<std::string, std::string> data;
bool fresh = false;
if (raw.empty() || !fw::cookie_verify(raw, secret, id) ||
!sessions->get(id, data)) {
id = sessions->create();
fresh = true;
data.clear();
}
long count = 0;
if (data.count("count")) {
try {
count = std::stol(data["count"]);
} catch (...) {
count = 0;
}
}
++count;
sessions->put(id, "count", std::to_string(count));
fw::Response res(200,
"{\"count\":" + std::to_string(count) +
",\"fresh\":" +
(fresh ? "true" : "false") + "}",
"application/json");
res.headers.set(
"Set-Cookie",
fw::make_set_cookie("session", fw::cookie_sign(id, secret),
"/", true, false, "Lax", 3600));
return res;
});
router.post("/uploads/file", "upload", [uploads](fw::Request req) {
std::string filename = req.query_or("filename", "upload.txt");
std::string content_type =
req.headers.get("Content-Type");
if (content_type.empty()) content_type = "text/plain";
fw::UploadInfo info;
std::string error;
if (!uploads->store(filename, content_type, req.body, info, error)) {
if (error == "file too large")
return fw::JsonResponse("{\"error\":\"" + error + "\"}", 413);
if (error == "content type not allowed")
return fw::JsonResponse("{\"error\":\"" + error + "\"}", 415);
return fw::JsonResponse("{\"error\":\"" + error + "\"}", 400);
}
return fw::JsonResponse("{\"file\":\"" + fw::json_escape(info.filename) +
"\",\"size\":" + std::to_string(info.size) +
"}",
201);
});
}
} // namespace molo::example::app
+14
View File
@@ -0,0 +1,14 @@
#include "App.hpp"
namespace molo::example::app {
void seed_services(Services& services) {
services.auth->add_user("ada", "correct-horse");
services.auth->add_user("grace", "compiler-rocks");
services.supervisor->add_worker("mailer");
services.supervisor->add_worker("indexer");
services.supervisor->start("mailer");
services.webdav->put("/files/welcome.txt", "hello from webdav\n");
}
} // namespace molo::example::app
+136
View File
@@ -0,0 +1,136 @@
#include "App.hpp"
#include "../fw/Templates.hpp"
namespace molo::example::app {
namespace {
const char kBase[] = R"BASE(<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>{{ title }}</title>
<link rel="stylesheet" href="/static/app.css">
</head>
<body>
<header class="topbar">
<a class="brand" href="/">{{ site }}</a>
<nav class="nav-wide">
<a href="/">Index</a>
<a href="/templates/page">Templates</a>
<a href="/forms/contact">Forms</a>
<a href="/docs">Docs</a>
<a href="/health">Health</a>
</nav>
<details class="nav-narrow">
<summary>Menu</summary>
<nav>
<a href="/">Index</a>
<a href="/templates/page">Templates</a>
<a href="/forms/contact">Forms</a>
<a href="/docs">Docs</a>
<a href="/health">Health</a>
</nav>
</details>
</header>
<main>
{% block content %}{% endblock %}
</main>
<footer><p>{{ site }}: living example, {{ backend }}</p></footer>
</body>
</html>
)BASE";
const char kIndex[] = R"INDEX({% extends "base.html" %}
{% block content %}
<h1>Living example</h1>
<p>Every framework feature, one click away. Mobile-first: narrow the window
and the top nav collapses into a dropdown menu.</p>
{% if show_matrix %}
<table>
<thead><tr><th>Feature</th><th>Route</th></tr></thead>
<tbody>
{% for row in matrix %}
<tr><td>{{ row.feature }}</td><td><a href="{{ row.route }}">{{ row.route }}</a></td></tr>
{% endfor %}
</tbody>
</table>
{% else %}
<p>Matrix hidden.</p>
{% endif %}
{% include "nav_hint.html" %}
{% endblock %}
)INDEX";
const char kPage[] = R"PAGE({% extends "base.html" %}
{% block content %}
<h1>{{ heading }}</h1>
<p>Author: {{ author|upper }}</p>
<p>Raw (escaped): {{ snippet }}</p>
<p>Trusted (safe): {{ snippet|safe }}</p>
<ul>
{% for item in items %}
<li>{{ item.name }} ({{ item.kind }})</li>
{% endfor %}
</ul>
{% endblock %}
)PAGE";
const char kContact[] = R"CONTACT({% extends "base.html" %}
{% block content %}
<h1>Contact</h1>
{% if posted %}
<p class="ok">Thanks {{ name }}, message received.</p>
{% else %}
<form method="post" action="/forms/contact">
<label>Name <input name="name" value="{{ name }}"></label>
<label>Email <input name="email" value="{{ email }}"></label>
<label>Message <textarea name="message">{{ message }}</textarea></label>
<button type="submit">Send</button>
</form>
{% endif %}
{% if error %}
<p class="error">{{ error }}</p>
{% endif %}
{% endblock %}
)CONTACT";
const char kDocs[] = R"DOCS({% extends "base.html" %}
{% block content %}
<h1>API docs</h1>
<p>OpenAPI JSON: <a href="/openapi.json">/openapi.json</a></p>
<ul>
{% for row in routes %}
<li><code>{{ row.method }} {{ row.path }}</code> : {{ row.summary }}</li>
{% endfor %}
</ul>
{% endblock %}
)DOCS";
const char kError[] = R"ERROR({% extends "base.html" %}
{% block content %}
<h1>Error {{ status }}</h1>
<p>{{ message }}</p>
{% endblock %}
)ERROR";
const char kNavHint[] =
"<p class=\"hint\">Tip: this page works on a 360px phone.</p>\n";
} // namespace
void load_templates(Services& services) {
services.templates->add_template("base.html", kBase);
services.templates->add_template("index.html", kIndex);
services.templates->add_template("page.html", kPage);
services.templates->add_template("contact.html", kContact);
services.templates->add_template("docs.html", kDocs);
services.templates->add_template("error.html", kError);
services.templates->add_template("nav_hint.html", kNavHint);
services.templates->add_global("site", "MoloApp living example");
services.templates->add_global("backend", "skeleton");
}
} // namespace molo::example::app
+117
View File
@@ -0,0 +1,117 @@
# example/example.mk: living example part (plan 10-workflow-example.md).
# Included by the root Makefile through per-part subdir .mk includes, or run
# standalone from the repo root:
# make -f example/example.mk example # build lib + server
# make -f example/example.mk example-test # build + run example suite
# make -f example/example.mk example-clean # remove build/example
# Portable make: variables plus sh loops only, no GNU-only functions.
CXX ?= g++
EXAMPLE_CXXFLAGS ?= -std=c++23 -Wall -Wextra -O1
EXAMPLE_DIR ?= example
EXAMPLE_BUILD ?= build/example
EXAMPLE_TESTDIR ?= tests/example
EXAMPLE_SRCS = \
$(EXAMPLE_DIR)/fw/Http.cpp \
$(EXAMPLE_DIR)/fw/Router.cpp \
$(EXAMPLE_DIR)/fw/App.cpp \
$(EXAMPLE_DIR)/fw/View.cpp \
$(EXAMPLE_DIR)/fw/Validate.cpp \
$(EXAMPLE_DIR)/fw/Templates.cpp \
$(EXAMPLE_DIR)/fw/Negotiate.cpp \
$(EXAMPLE_DIR)/fw/Cookies.cpp \
$(EXAMPLE_DIR)/fw/StaticFiles.cpp \
$(EXAMPLE_DIR)/fw/Tls.cpp \
$(EXAMPLE_DIR)/fw/Kv.cpp \
$(EXAMPLE_DIR)/fw/Observ.cpp \
$(EXAMPLE_DIR)/fw/Data.cpp \
$(EXAMPLE_DIR)/fw/Jobs.cpp \
$(EXAMPLE_DIR)/fw/Net.cpp \
$(EXAMPLE_DIR)/fw/Workflow.cpp \
$(EXAMPLE_DIR)/fw/TestClient.cpp \
$(EXAMPLE_DIR)/fw/Server.cpp \
$(EXAMPLE_DIR)/app/App.cpp \
$(EXAMPLE_DIR)/app/Seed.cpp \
$(EXAMPLE_DIR)/app/Templates.cpp \
$(EXAMPLE_DIR)/app/Embedded.cpp \
$(EXAMPLE_DIR)/app/Index.cpp \
$(EXAMPLE_DIR)/app/RoutingDemo.cpp \
$(EXAMPLE_DIR)/app/DataDemo.cpp \
$(EXAMPLE_DIR)/app/SecurityDemo.cpp \
$(EXAMPLE_DIR)/app/FormatsDemo.cpp \
$(EXAMPLE_DIR)/app/RealtimeDemo.cpp \
$(EXAMPLE_DIR)/app/OpsDemo.cpp
EXAMPLE_TESTS = \
$(EXAMPLE_TESTDIR)/index_test.cpp \
$(EXAMPLE_TESTDIR)/health_test.cpp \
$(EXAMPLE_TESTDIR)/routing/hello_test.cpp \
$(EXAMPLE_TESTDIR)/routing/views_test.cpp \
$(EXAMPLE_TESTDIR)/routing/routers_test.cpp \
$(EXAMPLE_TESTDIR)/chain/deep_test.cpp \
$(EXAMPLE_TESTDIR)/orm/users_test.cpp \
$(EXAMPLE_TESTDIR)/kv/items_test.cpp \
$(EXAMPLE_TESTDIR)/cache/lookup_test.cpp \
$(EXAMPLE_TESTDIR)/pubsub/publish_test.cpp \
$(EXAMPLE_TESTDIR)/auth/login_test.cpp \
$(EXAMPLE_TESTDIR)/auth/me_test.cpp \
$(EXAMPLE_TESTDIR)/sessions/counter_test.cpp \
$(EXAMPLE_TESTDIR)/uploads/file_test.cpp \
$(EXAMPLE_TESTDIR)/forms/contact_test.cpp \
$(EXAMPLE_TESTDIR)/validate/user_test.cpp \
$(EXAMPLE_TESTDIR)/templates/page_test.cpp \
$(EXAMPLE_TESTDIR)/formats/data_test.cpp \
$(EXAMPLE_TESTDIR)/static/files_test.cpp \
$(EXAMPLE_TESTDIR)/embedded/assets_test.cpp \
$(EXAMPLE_TESTDIR)/streaming/feed_test.cpp \
$(EXAMPLE_TESTDIR)/streaming/passthrough_test.cpp \
$(EXAMPLE_TESTDIR)/ws/chat_test.cpp \
$(EXAMPLE_TESTDIR)/socketio/rooms_test.cpp \
$(EXAMPLE_TESTDIR)/sse/events_test.cpp \
$(EXAMPLE_TESTDIR)/webdav/files_test.cpp \
$(EXAMPLE_TESTDIR)/events/fire_test.cpp \
$(EXAMPLE_TESTDIR)/metrics/counters_test.cpp \
$(EXAMPLE_TESTDIR)/telemetry/trace_test.cpp \
$(EXAMPLE_TESTDIR)/supervisor/tasks_test.cpp \
$(EXAMPLE_TESTDIR)/supervisor/workers_test.cpp \
$(EXAMPLE_TESTDIR)/replication/state_test.cpp \
$(EXAMPLE_TESTDIR)/restclient/self_test.cpp \
$(EXAMPLE_TESTDIR)/openapi/docs_test.cpp \
$(EXAMPLE_TESTDIR)/cli/ai_test.cpp \
$(EXAMPLE_TESTDIR)/workflow/release_test.cpp \
$(EXAMPLE_TESTDIR)/redirect/here_test.cpp
.PHONY: example example-test example-clean
example:
mkdir -p $(EXAMPLE_BUILD)/obj
for s in $(EXAMPLE_SRCS); do \
o=$(EXAMPLE_BUILD)/obj/`echo $$s | tr '/' '_'`.o; \
$(CXX) $(EXAMPLE_CXXFLAGS) -I$(EXAMPLE_DIR) -c $$s -o $$o || exit 1; \
done
ar rcs $(EXAMPLE_BUILD)/libexample.a $(EXAMPLE_BUILD)/obj/*.o
$(CXX) $(EXAMPLE_CXXFLAGS) -I$(EXAMPLE_DIR) $(EXAMPLE_DIR)/main.cpp \
$(EXAMPLE_BUILD)/libexample.a -o $(EXAMPLE_BUILD)/living-server
example-test: example
mkdir -p $(EXAMPLE_BUILD)/tests
pass=0; fail=0; \
for t in $(EXAMPLE_TESTS); do \
n=`echo $$t | sed 's|$(EXAMPLE_TESTDIR)/||; s|/|_|g; s|\.cpp$$||'`; \
$(CXX) $(EXAMPLE_CXXFLAGS) -I$(EXAMPLE_DIR) -I$(EXAMPLE_TESTDIR) \
$$t $(EXAMPLE_BUILD)/libexample.a \
-o $(EXAMPLE_BUILD)/tests/$$n || exit 1; \
if $(EXAMPLE_BUILD)/tests/$$n; then pass=$$((pass+1)); \
else fail=$$((fail+1)); echo "FAIL: $$t"; fi; \
done; \
echo "example suite: $$pass passed, $$fail failed"; \
test $$fail -eq 0
example-clean:
rm -rf $(EXAMPLE_BUILD)
# Root Makefile aggregation points (double-colon: safe with other parts).
all:: example
test:: example-test
clean:: example-clean
+123
View File
@@ -0,0 +1,123 @@
#include "App.hpp"
#include <stdexcept>
#include "Caps.hpp"
namespace molo::example::fw {
HttpError::HttpError(int status, std::string code, std::string message)
: status_(status), code_(std::move(code)), message_(std::move(message)) {}
int HttpError::status() const { return status_; }
const std::string& HttpError::code() const { return code_; }
const std::string& HttpError::message() const { return message_; }
void Application::use(MiddlewareSlot slot, Middleware middleware) {
if (has_middleware_ && slot < last_slot_)
throw std::runtime_error("middleware category order violated");
last_slot_ = slot;
has_middleware_ = true;
middlewares_.emplace_back(slot, std::move(middleware));
}
void Application::include_router(const std::string& prefix,
const Router& router,
const std::string& name_prefix) {
router_.include_router(prefix, router, name_prefix);
}
void Application::mount(const std::string& path,
std::shared_ptr<Application> sub) {
mounts_.emplace_back(path, std::move(sub));
}
Response Application::dispatch(Request req) {
if (req.body.size() > caps::kMaxRequestBody)
return TextResponse("body too large", 413);
try {
return run_chain(std::move(req), 0);
} catch (const HttpError& e) {
std::string body = "{\"error\":\"" + json_escape(e.code()) +
"\",\"message\":\"" + json_escape(e.message()) + "\"}";
return JsonResponse(body, e.status());
} catch (const std::exception& e) {
return JsonResponse("{\"error\":\"internal\",\"message\":\"" +
json_escape(e.what()) + "\"}",
500);
}
}
Response Application::run_chain(Request req, int depth) {
Next next = [this, depth](Request r) { return dispatch_inner(r, depth); };
for (std::size_t i = middlewares_.size(); i > 0; --i) {
Middleware mw = middlewares_[i - 1].second;
Next inner = next;
next = [mw, inner](Request r) { return mw(std::move(r), inner); };
}
return next(std::move(req));
}
Response Application::dispatch_inner(Request req, int depth) {
if (depth > caps::kMaxMountDepth)
throw HttpError(500, "mount_depth", "sub-application nesting too deep");
std::string best;
std::shared_ptr<Application> target;
for (auto& [prefix, sub] : mounts_) {
if (req.path.size() >= prefix.size() &&
req.path.compare(0, prefix.size(), prefix) == 0 &&
prefix.size() > best.size()) {
best = prefix;
target = sub;
}
}
if (target) {
req.path = req.path.substr(best.size());
if (req.path.empty() || req.path.front() != '/') req.path = "/" + req.path;
return target->run_chain(std::move(req), depth + 1);
}
Handler handler;
if (router_.match(req, handler)) return handler(std::move(req));
bool path_exists = false;
for (const auto& r : router_.routes()) {
std::map<std::string, std::string> params;
if (match_pattern(r.pattern, req.path, params)) {
path_exists = true;
break;
}
}
if (path_exists)
throw HttpError(405, "method_not_allowed", "method not allowed");
throw HttpError(404, "not_found", "no route for " + req.path);
}
const std::vector<Route>& Application::routes() const {
return router_.routes();
}
Middleware errors_middleware() {
return [](Request req, Next next) -> Response {
try {
return next(std::move(req));
} catch (const HttpError& e) {
std::string body = "{\"error\":\"" + json_escape(e.code()) +
"\",\"message\":\"" + json_escape(e.message()) +
"\"}";
return JsonResponse(body, e.status());
}
};
}
Middleware request_id_middleware() {
return [](Request req, Next next) -> Response {
if (req.correlation_id.empty()) {
static unsigned long counter = 1;
req.correlation_id = "req-" + std::to_string(counter++);
}
Response res = next(req);
res.headers.set("X-Request-ID", req.correlation_id);
return res;
};
}
} // namespace molo::example::fw
+67
View File
@@ -0,0 +1,67 @@
#pragma once
// Application: composition root. Owns routers, middleware chain, sub-app
// mounts, and the typed error mapping. Gap: real molo::app::Application in
// 05-request-routing.md owns lifespan hooks, plugin registry, and the full DI
// container; this skeleton passes a Services struct to route factories.
#include <functional>
#include <memory>
#include <string>
#include <vector>
#include "Http.hpp"
#include "Router.hpp"
namespace molo::example::fw {
enum class MiddlewareSlot {
Errors = 0,
Observability = 1,
Security = 2,
SessionAuth = 3,
User = 4,
};
using Next = std::function<Response(Request)>;
using Middleware = std::function<Response(Request, Next)>;
class HttpError {
public:
HttpError(int status, std::string code, std::string message);
int status() const;
const std::string& code() const;
const std::string& message() const;
private:
int status_;
std::string code_;
std::string message_;
};
class Application : public std::enable_shared_from_this<Application> {
public:
void use(MiddlewareSlot slot, Middleware middleware);
void include_router(const std::string& prefix, const Router& router,
const std::string& name_prefix = "");
void mount(const std::string& path, std::shared_ptr<Application> sub);
Response dispatch(Request req);
const std::vector<Route>& routes() const;
private:
Response dispatch_inner(Request req, int depth);
Response run_chain(Request req, int depth);
Router router_;
std::vector<std::pair<MiddlewareSlot, Middleware>> middlewares_;
std::vector<std::pair<std::string, std::shared_ptr<Application>>> mounts_;
MiddlewareSlot last_slot_ = MiddlewareSlot::Errors;
bool has_middleware_ = false;
};
Middleware errors_middleware();
Middleware request_id_middleware();
} // namespace molo::example::fw
+48
View File
@@ -0,0 +1,48 @@
#pragma once
// Static ceilings for the living example. Every knob has a cap; no autotuning.
// Gap: real framework caps live in 01-runtime.md through 09-cli-ops.md specs;
// these example caps mirror them until the framework lands.
#include <cstddef>
namespace molo::example::fw::caps {
inline constexpr std::size_t kMaxRequestBody = 1 << 20; // 1 MiB
inline constexpr std::size_t kMaxHeaderCount = 100;
inline constexpr std::size_t kMaxHeaderBytes = 65536;
inline constexpr std::size_t kMaxFormFields = 200;
inline constexpr int kMaxJsonDepth = 32;
inline constexpr std::size_t kMaxUploadBytes = 8 << 20; // 8 MiB
inline constexpr std::size_t kMaxTemplateBytes = 256 << 10;
inline constexpr int kMaxTemplateDepth = 16;
inline constexpr std::size_t kMaxRouteCount = 4096;
inline constexpr int kMaxMountDepth = 8;
inline constexpr std::size_t kMaxKvEntries = 100000;
inline constexpr std::size_t kMaxCacheEntries = 10000;
inline constexpr std::size_t kMaxPubsubTopics = 1000;
inline constexpr std::size_t kMaxPubsubHistory = 100;
inline constexpr std::size_t kMaxMetrics = 1000;
inline constexpr std::size_t kMaxSpans = 10000;
inline constexpr std::size_t kMaxSessions = 100000;
inline constexpr std::size_t kMaxOrmRows = 100000;
inline constexpr std::size_t kMaxOrmTables = 500;
inline constexpr std::size_t kMaxTasks = 10000;
inline constexpr std::size_t kMaxWorkers = 64;
inline constexpr std::size_t kMaxReplEntries = 10000;
inline constexpr std::size_t kMaxStreamChunks = 1000;
inline constexpr std::size_t kMaxChunkBytes = 65536;
inline constexpr int kServerBacklog = 64;
inline constexpr int kServerTimeoutSec = 30;
inline constexpr int kMaxConnections = 512;
inline constexpr std::size_t kMaxTestBody = 4 << 20;
inline constexpr int kSuiteTimeoutSec = 600;
inline constexpr int kSingleTestTimeoutSec = 30;
inline constexpr int kMaxReleasePerRun = 1;
inline constexpr int kMaxChangelogLines = 20;
inline constexpr int kMaxCommitSubject = 100;
inline constexpr int kPipelineTimeoutMin = 30;
inline constexpr std::size_t kMaxOpenApiRoutes = 4096;
inline constexpr std::size_t kMaxWebdavEntries = 10000;
} // namespace molo::example::fw::caps
+49
View File
@@ -0,0 +1,49 @@
#include "Cookies.hpp"
#include <cstdio>
namespace molo::example::fw {
namespace {
unsigned long long fnv1a(const std::string& s) {
unsigned long long h = 1469598103934665603ULL;
for (unsigned char c : s) {
h ^= c;
h *= 1099511628211ULL;
}
return h;
}
} // namespace
std::string cookie_sign(const std::string& value, const std::string& secret) {
char buf[32];
std::snprintf(buf, sizeof(buf), "%016llx",
(unsigned long long)fnv1a(secret + "|" + value));
return value + "." + buf;
}
bool cookie_verify(const std::string& signed_value, const std::string& secret,
std::string& out_value) {
std::size_t dot = signed_value.rfind('.');
if (dot == std::string::npos) return false;
std::string value = signed_value.substr(0, dot);
return cookie_sign(value, secret) == signed_value
? (out_value = value, true)
: false;
}
std::string make_set_cookie(const std::string& name, const std::string& value,
const std::string& path, bool http_only,
bool secure, const std::string& same_site,
long max_age) {
std::string out = name + "=" + value + "; Path=" + path;
if (max_age >= 0) out += "; Max-Age=" + std::to_string(max_age);
if (http_only) out += "; HttpOnly";
if (secure) out += "; Secure";
out += "; SameSite=" + same_site;
return out;
}
} // namespace molo::example::fw
+21
View File
@@ -0,0 +1,21 @@
#pragma once
// First-class cookies: sign and verify values for session cookies.
// Signing here is a keyed FNV-1a demonstration, NOT production crypto.
// Gap: real signing and encryption live in 03-security.md (AES-GCM or
// ChaCha20-Poly1305); this stub exists so the example compiles and runs.
#include <string>
namespace molo::example::fw {
std::string cookie_sign(const std::string& value, const std::string& secret);
bool cookie_verify(const std::string& signed_value, const std::string& secret,
std::string& out_value);
std::string make_set_cookie(const std::string& name, const std::string& value,
const std::string& path, bool http_only,
bool secure, const std::string& same_site,
long max_age);
} // namespace molo::example::fw
+272
View File
@@ -0,0 +1,272 @@
#include "Data.hpp"
#include <cstdio>
#include "Caps.hpp"
namespace molo::example::fw {
std::string SessionStore::create() {
std::lock_guard<std::mutex> lock(mu_);
std::string id = "sess-" + std::to_string(next_id_++);
sessions_[id] = {};
return id;
}
bool SessionStore::get(const std::string& id,
std::map<std::string, std::string>& out) {
std::lock_guard<std::mutex> lock(mu_);
auto it = sessions_.find(id);
if (it == sessions_.end()) return false;
out = it->second;
return true;
}
void SessionStore::put(const std::string& id, const std::string& key,
const std::string& value) {
std::lock_guard<std::mutex> lock(mu_);
if (!sessions_.count(id) && sessions_.size() >= caps::kMaxSessions) return;
sessions_[id][key] = value;
}
void SessionStore::rotate(const std::string& old_id, std::string& new_id) {
std::lock_guard<std::mutex> lock(mu_);
new_id = "sess-" + std::to_string(next_id_++);
auto it = sessions_.find(old_id);
if (it != sessions_.end()) {
sessions_[new_id] = it->second;
sessions_.erase(it);
} else {
sessions_[new_id] = {};
}
}
std::string demo_hash_password(const std::string& password) {
unsigned long long h = 1469598103934665603ULL;
std::string salted = "demo-salt|" + password;
for (unsigned char c : salted) {
h ^= c;
h *= 1099511628211ULL;
}
char buf[32];
std::snprintf(buf, sizeof(buf), "demo$%016llx", (unsigned long long)h);
return buf;
}
namespace {
int b64val(char c) {
if (c >= 'A' && c <= 'Z') return c - 'A';
if (c >= 'a' && c <= 'z') return c - 'a' + 26;
if (c >= '0' && c <= '9') return c - '0' + 52;
if (c == '+') return 62;
if (c == '/') return 63;
return -1;
}
std::string b64decode(const std::string& in) {
std::string out;
int acc = 0, bits = 0;
for (char c : in) {
if (c == '=') break;
int v = b64val(c);
if (v < 0) continue;
acc = (acc << 6) | v;
bits += 6;
if (bits >= 8) {
bits -= 8;
out.push_back((char)((acc >> bits) & 0xFF));
}
}
return out;
}
} // namespace
bool parse_basic_auth(const std::string& header, std::string& user,
std::string& password) {
const std::string prefix = "Basic ";
if (header.compare(0, prefix.size(), prefix) != 0) return false;
std::string decoded = b64decode(header.substr(prefix.size()));
std::size_t colon = decoded.find(':');
if (colon == std::string::npos) return false;
user = decoded.substr(0, colon);
password = decoded.substr(colon + 1);
return true;
}
void Auth::add_user(const std::string& username, const std::string& password) {
std::lock_guard<std::mutex> lock(mu_);
users_[username] = demo_hash_password(password);
}
bool Auth::check(const std::string& username,
const std::string& password) const {
std::lock_guard<std::mutex> lock(mu_);
auto it = users_.find(username);
if (it == users_.end()) return false;
return it->second == demo_hash_password(password);
}
std::string backend_name(OrmBackend backend) {
return backend == OrmBackend::Sqlite ? "sqlite" : "postgres";
}
OrmBackend parse_backend(const std::string& name) {
return name == "postgres" ? OrmBackend::Postgres : OrmBackend::Sqlite;
}
OrmDb::OrmDb(OrmBackend backend) : backend_(backend) {}
OrmBackend OrmDb::backend() const { return backend_; }
OrmResult OrmDb::insert(const std::string& table,
const std::map<std::string, std::string>& values) {
std::lock_guard<std::mutex> lock(mu_);
OrmResult res;
auto& cols = schema_[table];
if (cols.empty()) {
if (schema_.size() > caps::kMaxOrmTables) {
res.ok = false;
return res;
}
for (const auto& [k, v] : values) cols.push_back(k);
res.healed = true;
res.healed_note = "auto-created table " + table;
} else {
for (const auto& [k, v] : values) {
bool known = false;
for (const auto& c : cols) {
if (c == k) {
known = true;
break;
}
}
if (!known) {
cols.push_back(k);
res.healed = true;
res.healed_note = "auto-added column " + k + " to " + table;
}
}
}
auto& vec = rows_[table];
if (vec.size() >= caps::kMaxOrmRows) {
res.ok = false;
return res;
}
OrmRow row;
row.columns = values;
vec.push_back(row);
res.rows = {row};
return res;
}
OrmResult OrmDb::select_all(const std::string& table) {
std::lock_guard<std::mutex> lock(mu_);
OrmResult res;
auto it = rows_.find(table);
if (it == rows_.end()) {
if (!schema_.count(table)) {
schema_[table] = {"id"};
res.healed = true;
res.healed_note = "auto-created table " + table;
}
return res;
}
res.rows = it->second;
return res;
}
OrmResult OrmDb::ensure_column(const std::string& table,
const std::string& column) {
std::lock_guard<std::mutex> lock(mu_);
OrmResult res;
auto& cols = schema_[table];
for (const auto& c : cols) {
if (c == column) return res;
}
cols.push_back(column);
res.healed = true;
res.healed_note = "auto-added column " + column + " to " + table;
return res;
}
std::vector<std::string> OrmDb::tables() const {
std::lock_guard<std::mutex> lock(mu_);
std::vector<std::string> out;
for (const auto& [k, v] : schema_) out.push_back(k);
return out;
}
std::vector<std::string> OrmDb::columns(const std::string& table) const {
std::lock_guard<std::mutex> lock(mu_);
auto it = schema_.find(table);
if (it == schema_.end()) return {};
return it->second;
}
bool UploadStore::store(const std::string& filename,
const std::string& content_type,
const std::string& data, UploadInfo& out,
std::string& error) {
if (data.size() > caps::kMaxUploadBytes) {
error = "file too large";
return false;
}
bool allowed = content_type == "text/plain" || content_type == "image/png" ||
content_type == "application/json";
if (!allowed) {
error = "content type not allowed";
return false;
}
if (filename.find("..") != std::string::npos ||
filename.find('/') != std::string::npos) {
error = "unsafe filename";
return false;
}
std::lock_guard<std::mutex> lock(mu_);
out = UploadInfo{filename, content_type, data.size()};
uploads_.push_back(out);
return true;
}
std::vector<UploadInfo> UploadStore::list() const {
std::lock_guard<std::mutex> lock(mu_);
return uploads_;
}
void WebdavStore::put(const std::string& path, const std::string& content) {
std::lock_guard<std::mutex> lock(mu_);
if (!files_.count(path) && files_.size() >= caps::kMaxWebdavEntries) return;
files_[path] = content;
}
bool WebdavStore::get(const std::string& path, std::string& out) const {
std::lock_guard<std::mutex> lock(mu_);
auto it = files_.find(path);
if (it == files_.end()) return false;
out = it->second;
return true;
}
bool WebdavStore::remove(const std::string& path) {
std::lock_guard<std::mutex> lock(mu_);
return files_.erase(path) > 0;
}
std::string WebdavStore::propfind_xml(const std::string& root) const {
std::lock_guard<std::mutex> lock(mu_);
std::string out =
"<?xml version=\"1.0\"?><D:multistatus xmlns:D=\"DAV:\">";
for (const auto& [k, v] : files_) {
if (k.compare(0, root.size(), root) != 0) continue;
out += "<D:response><D:href>" + k +
"</D:href><D:propstat><D:prop><D:getcontentlength>" +
std::to_string(v.size()) +
"</D:getcontentlength></D:prop><D:status>HTTP/1.1 200 OK"
"</D:status></D:propstat></D:response>";
}
return out + "</D:multistatus>";
}
} // namespace molo::example::fw
+113
View File
@@ -0,0 +1,113 @@
#pragma once
// Data layer skeletons: sessions, basic auth, dual-backend ORM stub with
// self-healing demo, upload store, and WebDAV store.
// Gap: real 04-data.md owns the Postgres wire client, SQLite handling,
// pooling, transactions, and production self-healing; real password hashing
// (Argon2id) and encryption live in 03-security.md.
#include <map>
#include <mutex>
#include <string>
#include <vector>
namespace molo::example::fw {
class SessionStore {
public:
std::string create();
bool get(const std::string& id, std::map<std::string, std::string>& out);
void put(const std::string& id, const std::string& key,
const std::string& value);
void rotate(const std::string& old_id, std::string& new_id);
private:
mutable std::mutex mu_;
std::map<std::string, std::map<std::string, std::string>> sessions_;
unsigned long next_id_ = 1;
};
struct BasicUser {
std::string username;
std::string password_hash;
};
std::string demo_hash_password(const std::string& password);
bool parse_basic_auth(const std::string& header, std::string& user,
std::string& password);
class Auth {
public:
void add_user(const std::string& username, const std::string& password);
bool check(const std::string& username, const std::string& password) const;
private:
mutable std::mutex mu_;
std::map<std::string, std::string> users_;
};
enum class OrmBackend { Sqlite, Postgres };
std::string backend_name(OrmBackend backend);
OrmBackend parse_backend(const std::string& name);
struct OrmRow {
std::map<std::string, std::string> columns;
};
struct OrmResult {
bool ok = true;
bool healed = false;
std::string healed_note;
std::vector<OrmRow> rows;
};
class OrmDb {
public:
explicit OrmDb(OrmBackend backend);
OrmBackend backend() const;
OrmResult insert(const std::string& table,
const std::map<std::string, std::string>& values);
OrmResult select_all(const std::string& table);
OrmResult ensure_column(const std::string& table, const std::string& column);
std::vector<std::string> tables() const;
std::vector<std::string> columns(const std::string& table) const;
private:
OrmBackend backend_;
mutable std::mutex mu_;
std::map<std::string, std::vector<std::string>> schema_;
std::map<std::string, std::vector<OrmRow>> rows_;
};
struct UploadInfo {
std::string filename;
std::string content_type;
std::size_t size = 0;
};
class UploadStore {
public:
bool store(const std::string& filename, const std::string& content_type,
const std::string& data, UploadInfo& out, std::string& error);
std::vector<UploadInfo> list() const;
private:
mutable std::mutex mu_;
std::vector<UploadInfo> uploads_;
};
class WebdavStore {
public:
void put(const std::string& path, const std::string& content);
bool get(const std::string& path, std::string& out) const;
bool remove(const std::string& path);
std::string propfind_xml(const std::string& root) const;
private:
mutable std::mutex mu_;
std::map<std::string, std::string> files_;
};
} // namespace molo::example::fw
+266
View File
@@ -0,0 +1,266 @@
#include "Http.hpp"
#include <cctype>
#include "Caps.hpp"
namespace molo::example::fw {
Method parse_method(std::string_view name) {
if (name == "GET") return Method::Get;
if (name == "POST") return Method::Post;
if (name == "PUT") return Method::Put;
if (name == "PATCH") return Method::Patch;
if (name == "DELETE") return Method::Delete;
if (name == "HEAD") return Method::Head;
if (name == "OPTIONS") return Method::Options;
if (name == "PROPFIND") return Method::Propfind;
if (name == "PROPPATCH") return Method::Proppatch;
if (name == "MKCOL") return Method::Mkcol;
if (name == "COPY") return Method::Copy;
if (name == "MOVE") return Method::Move;
if (name == "LOCK") return Method::Lock;
if (name == "UNLOCK") return Method::Unlock;
return Method::Unknown;
}
std::string method_name(Method method) {
switch (method) {
case Method::Get: return "GET";
case Method::Post: return "POST";
case Method::Put: return "PUT";
case Method::Patch: return "PATCH";
case Method::Delete: return "DELETE";
case Method::Head: return "HEAD";
case Method::Options: return "OPTIONS";
case Method::Propfind: return "PROPFIND";
case Method::Proppatch: return "PROPPATCH";
case Method::Mkcol: return "MKCOL";
case Method::Copy: return "COPY";
case Method::Move: return "MOVE";
case Method::Lock: return "LOCK";
case Method::Unlock: return "UNLOCK";
case Method::Unknown: return "UNKNOWN";
}
return "UNKNOWN";
}
namespace {
bool name_eq(std::string_view a, std::string_view b) {
if (a.size() != b.size()) return false;
for (std::size_t i = 0; i < a.size(); ++i) {
if (std::tolower((unsigned char)a[i]) != std::tolower((unsigned char)b[i]))
return false;
}
return true;
}
} // namespace
void Headers::set(std::string name, std::string value) {
for (auto& e : entries_) {
if (name_eq(e.first, name)) {
e.second = value;
return;
}
}
entries_.emplace_back(std::move(name), std::move(value));
}
std::string Headers::get(std::string_view name) const {
for (const auto& e : entries_) {
if (name_eq(e.first, name)) return e.second;
}
return "";
}
bool Headers::has(std::string_view name) const {
for (const auto& e : entries_) {
if (name_eq(e.first, name)) return true;
}
return false;
}
const std::vector<std::pair<std::string, std::string>>& Headers::entries()
const {
return entries_;
}
std::string Request::query_or(std::string_view key,
std::string_view fallback) const {
auto it = query.find(std::string(key));
if (it == query.end()) return std::string(fallback);
return it->second;
}
std::string Request::param_or(std::string_view key,
std::string_view fallback) const {
auto it = path_params.find(std::string(key));
if (it == path_params.end()) return std::string(fallback);
return it->second;
}
std::string Request::cookie_or(std::string_view key,
std::string_view fallback) const {
auto it = cookies.find(std::string(key));
if (it == cookies.end()) return std::string(fallback);
return it->second;
}
Response::Response(int status, std::string body, std::string content_type)
: status(status), body(std::move(body)) {
headers.set("Content-Type", std::move(content_type));
}
std::string Response::content_type() const {
return headers.get("Content-Type");
}
TextResponse::TextResponse(std::string body, int status)
: Response(status, std::move(body), "text/plain; charset=utf-8") {}
HtmlResponse::HtmlResponse(std::string body, int status)
: Response(status, std::move(body), "text/html; charset=utf-8") {}
JsonResponse::JsonResponse(std::string body, int status)
: Response(status, std::move(body), "application/json") {}
XmlResponse::XmlResponse(std::string body, int status)
: Response(status, std::move(body), "application/xml") {}
RedirectResponse::RedirectResponse(std::string location, bool permanent)
: Response(permanent ? 301 : 302, "", "text/plain; charset=utf-8") {
headers.set("Location", std::move(location));
}
FileResponse::FileResponse(std::string body, std::string content_type,
std::string filename)
: Response(200, std::move(body), std::move(content_type)) {
headers.set("Content-Disposition",
"attachment; filename=\"" + filename + "\"");
}
StreamingResponse::StreamingResponse(std::vector<std::string> chunks)
: Response(200, "", "text/plain; charset=utf-8"), chunks(std::move(chunks)) {
for (const auto& c : this->chunks) body += c;
headers.set("Transfer-Encoding", "chunked");
if (this->chunks.size() > caps::kMaxStreamChunks) {
status = 500;
body = "chunk cap exceeded";
}
}
SseResponse::SseResponse(std::vector<std::string> events)
: Response(200, "", "text/event-stream"), events(std::move(events)) {
for (const auto& e : this->events) body += "data: " + e + "\n\n";
}
std::string url_decode(std::string_view in) {
std::string out;
out.reserve(in.size());
for (std::size_t i = 0; i < in.size(); ++i) {
if (in[i] == '%' && i + 2 < in.size() &&
std::isxdigit((unsigned char)in[i + 1]) &&
std::isxdigit((unsigned char)in[i + 2])) {
int hi = std::isdigit((unsigned char)in[i + 1])
? in[i + 1] - '0'
: std::tolower((unsigned char)in[i + 1]) - 'a' + 10;
int lo = std::isdigit((unsigned char)in[i + 2])
? in[i + 2] - '0'
: std::tolower((unsigned char)in[i + 2]) - 'a' + 10;
out.push_back((char)(hi * 16 + lo));
i += 2;
} else if (in[i] == '+') {
out.push_back(' ');
} else {
out.push_back(in[i]);
}
}
return out;
}
std::map<std::string, std::string> parse_query(std::string_view qs) {
std::map<std::string, std::string> out;
std::size_t start = 0;
std::size_t fields = 0;
while (start <= qs.size() && fields < caps::kMaxFormFields) {
std::size_t amp = qs.find('&', start);
if (amp == std::string_view::npos) amp = qs.size();
std::string_view pair = qs.substr(start, amp - start);
std::size_t eq = pair.find('=');
if (eq == std::string_view::npos) {
if (!pair.empty()) out[url_decode(pair)] = "";
} else {
out[url_decode(pair.substr(0, eq))] = url_decode(pair.substr(eq + 1));
}
++fields;
start = amp + 1;
}
return out;
}
std::map<std::string, std::string> parse_cookies(std::string_view header) {
std::map<std::string, std::string> out;
std::size_t start = 0;
while (start < header.size()) {
std::size_t semi = header.find(';', start);
if (semi == std::string_view::npos) semi = header.size();
std::string_view pair = header.substr(start, semi - start);
std::size_t eq = pair.find('=');
if (eq != std::string_view::npos) {
std::string k(pair.substr(0, eq));
std::string v(pair.substr(eq + 1));
while (!k.empty() && k.front() == ' ') k.erase(k.begin());
while (!v.empty() && v.front() == ' ') v.erase(v.begin());
if (!k.empty()) out[k] = v;
}
start = semi + 1;
}
return out;
}
std::map<std::string, std::string> parse_form(std::string_view body) {
return parse_query(body);
}
std::string status_text(int status) {
switch (status) {
case 200: return "OK";
case 201: return "Created";
case 207: return "Multi-Status";
case 301: return "Moved Permanently";
case 302: return "Found";
case 400: return "Bad Request";
case 401: return "Unauthorized";
case 403: return "Forbidden";
case 404: return "Not Found";
case 405: return "Method Not Allowed";
case 406: return "Not Acceptable";
case 409: return "Conflict";
case 413: return "Content Too Large";
case 422: return "Unprocessable Entity";
case 429: return "Too Many Requests";
case 500: return "Internal Server Error";
case 501: return "Not Implemented";
default: return "Unknown";
}
}
std::string json_escape(std::string_view in) {
std::string out;
out.reserve(in.size() + 2);
for (char c : in) {
switch (c) {
case '"': out += "\\\""; break;
case '\\': out += "\\\\"; break;
case '\n': out += "\\n"; break;
case '\r': out += "\\r"; break;
case '\t': out += "\\t"; break;
default: out.push_back(c); break;
}
}
return out;
}
} // namespace molo::example::fw
+114
View File
@@ -0,0 +1,114 @@
#pragma once
// HTTP message types: one Request, one Response hierarchy with a subclass per
// format. Subclasses are constructor conveniences over the base value type so
// handlers can return by value without slicing loss. Gap: real molo::http_msg
// in 05-request-routing.md owns the final API; this skeleton mirrors it.
#include <map>
#include <string>
#include <string_view>
#include <vector>
namespace molo::example::fw {
enum class Method {
Get,
Post,
Put,
Patch,
Delete,
Head,
Options,
Propfind,
Proppatch,
Mkcol,
Copy,
Move,
Lock,
Unlock,
Unknown,
};
Method parse_method(std::string_view name);
std::string method_name(Method method);
class Headers {
public:
void set(std::string name, std::string value);
std::string get(std::string_view name) const;
bool has(std::string_view name) const;
const std::vector<std::pair<std::string, std::string>>& entries() const;
private:
std::vector<std::pair<std::string, std::string>> entries_;
};
struct Request {
Method method = Method::Get;
std::string path = "/";
std::map<std::string, std::string> query;
Headers headers;
std::map<std::string, std::string> cookies;
std::map<std::string, std::string> path_params;
std::string body;
std::string correlation_id;
std::string query_or(std::string_view key, std::string_view fallback) const;
std::string param_or(std::string_view key, std::string_view fallback) const;
std::string cookie_or(std::string_view key, std::string_view fallback) const;
};
struct Response {
int status = 200;
Headers headers;
std::string body;
Response() = default;
Response(int status, std::string body, std::string content_type);
std::string content_type() const;
};
struct TextResponse : Response {
explicit TextResponse(std::string body, int status = 200);
};
struct HtmlResponse : Response {
explicit HtmlResponse(std::string body, int status = 200);
};
struct JsonResponse : Response {
explicit JsonResponse(std::string body, int status = 200);
};
struct XmlResponse : Response {
explicit XmlResponse(std::string body, int status = 200);
};
struct RedirectResponse : Response {
RedirectResponse(std::string location, bool permanent);
};
struct FileResponse : Response {
FileResponse(std::string body, std::string content_type, std::string filename);
};
struct StreamingResponse : Response {
explicit StreamingResponse(std::vector<std::string> chunks);
std::vector<std::string> chunks;
};
struct SseResponse : Response {
explicit SseResponse(std::vector<std::string> events);
std::vector<std::string> events;
};
std::string url_decode(std::string_view in);
std::map<std::string, std::string> parse_query(std::string_view qs);
std::map<std::string, std::string> parse_cookies(std::string_view header);
std::map<std::string, std::string> parse_form(std::string_view body);
std::string status_text(int status);
std::string json_escape(std::string_view in);
} // namespace molo::example::fw
+113
View File
@@ -0,0 +1,113 @@
#include "Jobs.hpp"
#include "Caps.hpp"
namespace molo::example::fw {
void Supervisor::add_worker(const std::string& name) {
std::lock_guard<std::mutex> lock(mu_);
if (!workers_.count(name) && workers_.size() >= caps::kMaxWorkers) return;
workers_[name] = WorkerInfo{name, false, 0};
}
bool Supervisor::start(const std::string& name) {
std::lock_guard<std::mutex> lock(mu_);
auto it = workers_.find(name);
if (it == workers_.end()) return false;
it->second.running = true;
return true;
}
bool Supervisor::stop(const std::string& name) {
std::lock_guard<std::mutex> lock(mu_);
auto it = workers_.find(name);
if (it == workers_.end()) return false;
it->second.running = false;
return true;
}
bool Supervisor::restart(const std::string& name) {
std::lock_guard<std::mutex> lock(mu_);
auto it = workers_.find(name);
if (it == workers_.end()) return false;
it->second.running = true;
++it->second.restarts;
return true;
}
std::vector<WorkerInfo> Supervisor::status() const {
std::lock_guard<std::mutex> lock(mu_);
std::vector<WorkerInfo> out;
for (const auto& [k, v] : workers_) out.push_back(v);
return out;
}
std::string TaskQueue::enqueue(const std::string& kind,
const std::string& payload, long delay_sec) {
std::lock_guard<std::mutex> lock(mu_);
if (tasks_.size() >= caps::kMaxTasks) return "";
std::string id = "task-" + std::to_string(next_id_++);
TaskInfo t{id, kind, payload,
delay_sec > 0 ? "delayed" : "queued", 0};
tasks_[id] = t;
return id;
}
bool TaskQueue::cancel(const std::string& id) {
std::lock_guard<std::mutex> lock(mu_);
auto it = tasks_.find(id);
if (it == tasks_.end()) return false;
it->second.state = "cancelled";
return true;
}
bool TaskQueue::retry(const std::string& id) {
std::lock_guard<std::mutex> lock(mu_);
auto it = tasks_.find(id);
if (it == tasks_.end()) return false;
++it->second.attempts;
it->second.state = "queued";
return true;
}
void TaskQueue::run_inline(TaskInfo& task) {
task.state = "done";
std::lock_guard<std::mutex> lock(mu_);
auto it = tasks_.find(task.id);
if (it != tasks_.end()) it->second.state = "done";
}
std::vector<TaskInfo> TaskQueue::list() const {
std::lock_guard<std::mutex> lock(mu_);
std::vector<TaskInfo> out;
for (const auto& [k, v] : tasks_) out.push_back(v);
return out;
}
ReplEntry ReplicationLog::append(const std::string& object,
const std::string& data) {
std::lock_guard<std::mutex> lock(mu_);
ReplEntry e;
e.seq = entries_.size() + 1;
e.object = object;
e.data = data;
e.resolution = "last-writer-wins";
if (entries_.size() < caps::kMaxReplEntries) entries_.push_back(e);
return e;
}
std::vector<ReplEntry> ReplicationLog::since(unsigned long seq) const {
std::lock_guard<std::mutex> lock(mu_);
std::vector<ReplEntry> out;
for (const auto& e : entries_) {
if (e.seq > seq) out.push_back(e);
}
return out;
}
unsigned long ReplicationLog::latest() const {
std::lock_guard<std::mutex> lock(mu_);
return entries_.size();
}
} // namespace molo::example::fw
+75
View File
@@ -0,0 +1,75 @@
#pragma once
// Supervisor plus background tasks plus replication log skeletons.
// Gap: real 07-supervisor-replication.md owns worker processes, restarts,
// durable streams, conflict handling, and multi-instance deployment.
#include <functional>
#include <map>
#include <mutex>
#include <string>
#include <vector>
namespace molo::example::fw {
struct WorkerInfo {
std::string name;
bool running = false;
int restarts = 0;
};
class Supervisor {
public:
void add_worker(const std::string& name);
bool start(const std::string& name);
bool stop(const std::string& name);
bool restart(const std::string& name);
std::vector<WorkerInfo> status() const;
private:
mutable std::mutex mu_;
std::map<std::string, WorkerInfo> workers_;
};
struct TaskInfo {
std::string id;
std::string kind;
std::string payload;
std::string state;
int attempts = 0;
};
class TaskQueue {
public:
std::string enqueue(const std::string& kind, const std::string& payload,
long delay_sec = 0);
bool cancel(const std::string& id);
bool retry(const std::string& id);
void run_inline(TaskInfo& task);
std::vector<TaskInfo> list() const;
private:
mutable std::mutex mu_;
std::map<std::string, TaskInfo> tasks_;
unsigned long next_id_ = 1;
};
struct ReplEntry {
unsigned long seq = 0;
std::string object;
std::string data;
std::string resolution;
};
class ReplicationLog {
public:
ReplEntry append(const std::string& object, const std::string& data);
std::vector<ReplEntry> since(unsigned long seq) const;
unsigned long latest() const;
private:
mutable std::mutex mu_;
std::vector<ReplEntry> entries_;
};
} // namespace molo::example::fw
+95
View File
@@ -0,0 +1,95 @@
#include "Kv.hpp"
#include "Caps.hpp"
namespace molo::example::fw {
bool KvStore::set(const std::string& key, const std::string& value) {
std::lock_guard<std::mutex> lock(mu_);
if (!data_.count(key) && data_.size() >= caps::kMaxKvEntries) return false;
data_[key] = value;
return true;
}
bool KvStore::get(const std::string& key, std::string& out) const {
std::lock_guard<std::mutex> lock(mu_);
auto it = data_.find(key);
if (it == data_.end()) return false;
out = it->second;
return true;
}
bool KvStore::del(const std::string& key) {
std::lock_guard<std::mutex> lock(mu_);
return data_.erase(key) > 0;
}
std::size_t KvStore::size() const {
std::lock_guard<std::mutex> lock(mu_);
return data_.size();
}
void Cache::put(const std::string& key, const std::string& value, long ttl_sec,
long now) {
std::lock_guard<std::mutex> lock(mu_);
if (!data_.count(key) && data_.size() >= caps::kMaxCacheEntries) return;
data_[key] = CacheEntry{value, now + ttl_sec};
}
bool Cache::lookup(const std::string& key, std::string& out, long now) {
std::lock_guard<std::mutex> lock(mu_);
auto it = data_.find(key);
if (it == data_.end()) return false;
if (it->second.expires_at <= now) {
data_.erase(it);
return false;
}
out = it->second.value;
return true;
}
void Cache::invalidate(const std::string& key) {
std::lock_guard<std::mutex> lock(mu_);
data_.erase(key);
}
std::size_t Cache::size() const {
std::lock_guard<std::mutex> lock(mu_);
return data_.size();
}
bool Pubsub::subscribe(const std::string& topic, PubsubHandler handler) {
std::lock_guard<std::mutex> lock(mu_);
if (!subs_.count(topic) && subs_.size() >= caps::kMaxPubsubTopics)
return false;
subs_[topic].push_back(std::move(handler));
return true;
}
std::size_t Pubsub::publish(const std::string& topic,
const std::string& message) {
std::lock_guard<std::mutex> lock(mu_);
auto& hist = history_[topic];
hist.push_back(message);
if (hist.size() > caps::kMaxPubsubHistory) hist.erase(hist.begin());
auto it = subs_.find(topic);
if (it == subs_.end()) return 0;
for (auto& h : it->second) h(message);
return it->second.size();
}
std::vector<std::string> Pubsub::history(const std::string& topic) const {
std::lock_guard<std::mutex> lock(mu_);
auto it = history_.find(topic);
if (it == history_.end()) return {};
return it->second;
}
std::vector<std::string> Pubsub::topics() const {
std::lock_guard<std::mutex> lock(mu_);
std::vector<std::string> out;
for (const auto& [k, v] : subs_) out.push_back(k);
return out;
}
} // namespace molo::example::fw
+61
View File
@@ -0,0 +1,61 @@
#pragma once
// In-memory key-value store, TTL cache, and pubsub broker skeletons.
// Gap: real implementations in 04-data.md own persistence, replication,
// durability guarantees, and multi-instance sharing.
#include <cstdint>
#include <functional>
#include <map>
#include <mutex>
#include <string>
#include <vector>
namespace molo::example::fw {
class KvStore {
public:
bool set(const std::string& key, const std::string& value);
bool get(const std::string& key, std::string& out) const;
bool del(const std::string& key);
std::size_t size() const;
private:
mutable std::mutex mu_;
std::map<std::string, std::string> data_;
};
struct CacheEntry {
std::string value;
long expires_at = 0;
};
class Cache {
public:
void put(const std::string& key, const std::string& value, long ttl_sec,
long now);
bool lookup(const std::string& key, std::string& out, long now);
void invalidate(const std::string& key);
std::size_t size() const;
private:
mutable std::mutex mu_;
std::map<std::string, CacheEntry> data_;
};
using PubsubHandler = std::function<void(const std::string& message)>;
class Pubsub {
public:
bool subscribe(const std::string& topic, PubsubHandler handler);
std::size_t publish(const std::string& topic, const std::string& message);
std::vector<std::string> history(const std::string& topic) const;
std::vector<std::string> topics() const;
private:
mutable std::mutex mu_;
std::map<std::string, std::vector<PubsubHandler>> subs_;
std::map<std::string, std::vector<std::string>> history_;
};
} // namespace molo::example::fw
+70
View File
@@ -0,0 +1,70 @@
#include "Negotiate.hpp"
#include <cctype>
namespace molo::example::fw {
namespace {
std::string trim(std::string s) {
while (!s.empty() && (s.front() == ' ' || s.front() == '\t')) s.erase(s.begin());
while (!s.empty() && (s.back() == ' ' || s.back() == '\t')) s.pop_back();
return s;
}
} // namespace
std::string negotiate(const std::string& accept,
const std::vector<std::string>& available) {
if (available.empty()) throw HttpError(500, "no_offers", "no offers");
if (accept.empty()) return available.front();
struct Range {
std::string type;
double q = 1.0;
};
std::vector<Range> ranges;
std::size_t start = 0;
while (start < accept.size()) {
std::size_t comma = accept.find(',', start);
if (comma == std::string::npos) comma = accept.size();
std::string part = trim(accept.substr(start, comma - start));
std::size_t semi = part.find(';');
Range r{trim(part.substr(0, semi)), 1.0};
if (semi != std::string::npos) {
std::string params = part.substr(semi + 1);
std::size_t q = params.find("q=");
if (q != std::string::npos) {
try {
r.q = std::stod(params.substr(q + 2));
} catch (...) {
r.q = 1.0;
}
}
}
ranges.push_back(r);
start = comma + 1;
}
std::string best;
double best_q = -1.0;
for (const auto& a : available) {
for (const auto& r : ranges) {
bool hit = r.type == "*/*" || r.type == a;
if (!hit) {
std::size_t slash = a.find('/');
std::string wild = slash == std::string::npos
? "*/*"
: a.substr(0, slash) + "/*";
hit = r.type == wild;
}
if (hit && r.q > best_q) {
best_q = r.q;
best = a;
}
}
}
if (best.empty() || best_q <= 0.0)
throw HttpError(406, "not_acceptable", "no acceptable format");
return best;
}
} // namespace molo::example::fw
+22
View File
@@ -0,0 +1,22 @@
#pragma once
// Server-driven content negotiation: parses Accept with q weights, picks one
// handler-declared format, answers 406 when nothing matches.
// Gap: real molo::negotiate in 05-request-routing.md owns suffix and
// format-override rules.
#include <string>
#include <vector>
#include "App.hpp"
namespace molo::example::fw {
struct Offer {
std::string media_type;
};
std::string negotiate(const std::string& accept,
const std::vector<std::string>& available);
} // namespace molo::example::fw
+82
View File
@@ -0,0 +1,82 @@
#include "Net.hpp"
#include "Caps.hpp"
namespace molo::example::fw {
RestClient::RestClient(RestTransport transport)
: transport_(std::move(transport)) {}
Response RestClient::get(const std::string& path) {
Request req;
req.method = Method::Get;
req.path = path;
return transport_(std::move(req));
}
Response RestClient::post_json(const std::string& path,
const std::string& json) {
Request req;
req.method = Method::Post;
req.path = path;
req.body = json;
req.headers.set("Content-Type", "application/json");
return transport_(std::move(req));
}
void OpenApi::add(const std::string& path, const std::string& method,
const std::string& summary) {
if (routes_.size() >= caps::kMaxOpenApiRoutes) return;
routes_.push_back({path, method, summary});
}
std::string OpenApi::to_json() const {
std::string out =
"{\"openapi\":\"3.0.0\",\"info\":{\"title\":\"living-example\","
"\"version\":\"0.1.0\"},\"paths\":{";
bool first = true;
for (const auto& r : routes_) {
if (!first) out += ",";
first = false;
out += "\"" + json_escape(r.path) + "\":{\"" + json_escape(r.method) +
"\":{\"summary\":\"" + json_escape(r.summary) + "\"}}";
}
return out + "}}";
}
std::size_t OpenApi::size() const { return routes_.size(); }
std::string redact_secrets(const std::string& text) {
std::string out = text;
const char* keys[] = {"DEVPLACE_API_KEY", "API_KEY", "SECRET", "TOKEN",
"PASSWORD"};
for (const char* k : keys) {
std::string key(k);
std::size_t pos = 0;
while ((pos = out.find(key, pos)) != std::string::npos) {
std::size_t eol = out.find('\n', pos);
if (eol == std::string::npos) eol = out.size();
std::size_t eq = out.find('=', pos);
if (eq != std::string::npos && eq < eol) {
out.replace(eq + 1, eol - eq - 1, "[REDACTED]");
pos = eq + 1;
} else {
pos += key.size();
}
}
}
return out;
}
AiSample ai_harness_sample(const std::string& prompt) {
AiSample s;
s.base_url = "https://devplace.net/openai/v1";
s.model = "molodetz";
s.redacted_prompt = redact_secrets(prompt);
s.stream_chunks = {"data: {\"delta\":\"plan: add route\"}\n\n",
"data: {\"delta\":\"apply: 1 file\"}\n\n",
"data: [DONE]\n\n"};
return s;
}
} // namespace molo::example::fw
+57
View File
@@ -0,0 +1,57 @@
#pragma once
// Client parity skeletons: REST client (self-call transport), realtime
// client notes, OpenAPI registry, and the AI harness sample.
// Gap: real HTTP/1.1 plus HTTP/2 client in 08-clients-openapi.md, realtime
// clients in 06-realtime.md, and the AI harness CLI in 09-cli-ops.md.
#include <functional>
#include <map>
#include <string>
#include <vector>
#include "Http.hpp"
namespace molo::example::fw {
using RestTransport = std::function<Response(Request)>;
class RestClient {
public:
explicit RestClient(RestTransport transport);
Response get(const std::string& path);
Response post_json(const std::string& path, const std::string& json);
private:
RestTransport transport_;
};
struct OpenApiRoute {
std::string path;
std::string method;
std::string summary;
};
class OpenApi {
public:
void add(const std::string& path, const std::string& method,
const std::string& summary);
std::string to_json() const;
std::size_t size() const;
private:
std::vector<OpenApiRoute> routes_;
};
struct AiSample {
std::string base_url;
std::string model;
std::string redacted_prompt;
std::vector<std::string> stream_chunks;
};
std::string redact_secrets(const std::string& text);
AiSample ai_harness_sample(const std::string& prompt);
} // namespace molo::example::fw
+86
View File
@@ -0,0 +1,86 @@
#include "Observ.hpp"
#include <cstdio>
#include "Caps.hpp"
namespace molo::example::fw {
void EventBus::on(const std::string& type,
std::function<void(const Event&)> listener) {
std::lock_guard<std::mutex> lock(mu_);
if (!kEnabled) return;
listeners_[type].push_back(std::move(listener));
}
void EventBus::emit(const Event& event) {
std::lock_guard<std::mutex> lock(mu_);
if (!kEnabled) return;
delivered_.push_back(event);
auto it = listeners_.find(event.type);
if (it == listeners_.end()) return;
for (auto& l : it->second) l(event);
}
std::vector<Event> EventBus::delivered() const {
std::lock_guard<std::mutex> lock(mu_);
return delivered_;
}
void Metrics::inc(const std::string& name, double value) {
std::lock_guard<std::mutex> lock(mu_);
if (!kEnabled) return;
if (!values_.count(name) && values_.size() >= caps::kMaxMetrics) return;
values_[name] += value;
}
void Metrics::gauge(const std::string& name, double value) {
std::lock_guard<std::mutex> lock(mu_);
if (!kEnabled) return;
if (!values_.count(name) && values_.size() >= caps::kMaxMetrics) return;
values_[name] = value;
}
double Metrics::get(const std::string& name) const {
std::lock_guard<std::mutex> lock(mu_);
auto it = values_.find(name);
return it == values_.end() ? 0.0 : it->second;
}
std::string Metrics::render_prometheus() const {
std::lock_guard<std::mutex> lock(mu_);
std::string out;
for (const auto& [k, v] : values_) {
char buf[64];
std::snprintf(buf, sizeof(buf), "%g", v);
out += k + " " + buf + "\n";
}
return out;
}
Span Telemetry::start_span(const std::string& name,
const std::string& correlation_id) {
std::lock_guard<std::mutex> lock(mu_);
Span s;
if (!kEnabled) return s;
s.trace_id = "trace-" + std::to_string(next_id_);
s.span_id = "span-" + std::to_string(next_id_);
++next_id_;
s.name = name;
s.correlation_id = correlation_id;
return s;
}
void Telemetry::finish_span(const Span& span) {
std::lock_guard<std::mutex> lock(mu_);
if (!kEnabled) return;
if (spans_.size() >= caps::kMaxSpans) return;
spans_.push_back(span);
}
std::vector<Span> Telemetry::spans() const {
std::lock_guard<std::mutex> lock(mu_);
return spans_;
}
} // namespace molo::example::fw
+72
View File
@@ -0,0 +1,72 @@
#pragma once
// Observability skeletons: typed event bus, metrics registry, and tracer.
// All three compile to near-zero overhead when kEnabled is false.
// Gap: real 02-observability.md owns the log format, Prometheus and OTel
// export, and the zero-cost macro layer.
#include <functional>
#include <map>
#include <mutex>
#include <string>
#include <vector>
namespace molo::example::fw {
struct Event {
std::string type;
std::string payload;
std::string correlation_id;
};
class EventBus {
public:
static constexpr bool kEnabled = true;
void on(const std::string& type, std::function<void(const Event&)> listener);
void emit(const Event& event);
std::vector<Event> delivered() const;
private:
mutable std::mutex mu_;
std::map<std::string, std::vector<std::function<void(const Event&)>>>
listeners_;
std::vector<Event> delivered_;
};
class Metrics {
public:
static constexpr bool kEnabled = true;
void inc(const std::string& name, double value = 1.0);
void gauge(const std::string& name, double value);
double get(const std::string& name) const;
std::string render_prometheus() const;
private:
mutable std::mutex mu_;
std::map<std::string, double> values_;
};
struct Span {
std::string trace_id;
std::string span_id;
std::string name;
std::string correlation_id;
};
class Telemetry {
public:
static constexpr bool kEnabled = true;
Span start_span(const std::string& name, const std::string& correlation_id);
void finish_span(const Span& span);
std::vector<Span> spans() const;
private:
mutable std::mutex mu_;
std::vector<Span> spans_;
unsigned long next_id_ = 1;
};
} // namespace molo::example::fw
+129
View File
@@ -0,0 +1,129 @@
#include "Router.hpp"
#include <stdexcept>
#include "Caps.hpp"
namespace molo::example::fw {
namespace {
std::vector<std::string> split_path(std::string_view path) {
std::vector<std::string> segs;
std::string cur;
for (char c : path) {
if (c == '/') {
if (!cur.empty()) {
segs.push_back(cur);
cur.clear();
}
} else {
cur.push_back(c);
}
}
if (!cur.empty()) segs.push_back(cur);
return segs;
}
} // namespace
bool match_pattern(std::string_view pattern, std::string_view path,
std::map<std::string, std::string>& params) {
auto want = split_path(pattern);
auto got = split_path(path);
if (want.size() != got.size()) return false;
for (std::size_t i = 0; i < want.size(); ++i) {
const std::string& w = want[i];
if (w.size() >= 2 && w.front() == '{' && w.back() == '}') {
params[w.substr(1, w.size() - 2)] = url_decode(got[i]);
} else if (w != got[i]) {
return false;
}
}
return true;
}
void Router::add(std::vector<Method> methods, std::string pattern,
std::string name, Handler handler) {
if (routes_.size() >= caps::kMaxRouteCount)
throw std::length_error("route cap exceeded");
for (const auto& r : routes_) {
if (r.name == name)
throw std::runtime_error("duplicate route name: " + name);
}
routes_.push_back(
Route{std::move(methods), std::move(pattern), std::move(name),
std::move(handler)});
}
void Router::get(std::string pattern, std::string name, Handler handler) {
add({Method::Get}, std::move(pattern), std::move(name), std::move(handler));
}
void Router::post(std::string pattern, std::string name, Handler handler) {
add({Method::Post}, std::move(pattern), std::move(name), std::move(handler));
}
void Router::put(std::string pattern, std::string name, Handler handler) {
add({Method::Put}, std::move(pattern), std::move(name), std::move(handler));
}
void Router::patch(std::string pattern, std::string name, Handler handler) {
add({Method::Patch}, std::move(pattern), std::move(name), std::move(handler));
}
void Router::del(std::string pattern, std::string name, Handler handler) {
add({Method::Delete}, std::move(pattern), std::move(name),
std::move(handler));
}
void Router::options(std::string pattern, std::string name, Handler handler) {
add({Method::Options}, std::move(pattern), std::move(name),
std::move(handler));
}
void Router::any(std::vector<Method> methods, std::string pattern,
std::string name, Handler handler) {
add(std::move(methods), std::move(pattern), std::move(name),
std::move(handler));
}
void Router::include_router(const std::string& prefix, const Router& other,
const std::string& name_prefix) {
for (const auto& r : other.routes_) {
std::string pattern = prefix;
if (!r.pattern.empty() && r.pattern != "/") {
if (pattern.empty() || pattern.back() != '/') pattern += "/";
std::string sub = r.pattern;
if (!sub.empty() && sub.front() == '/') sub.erase(sub.begin());
pattern += sub;
}
if (pattern.empty()) pattern = "/";
std::string name = name_prefix.empty() ? r.name : name_prefix + r.name;
add(r.methods, pattern, name, r.handler);
}
}
bool Router::match(Request& req, Handler& out) const {
for (const auto& r : routes_) {
bool method_ok = false;
for (Method m : r.methods) {
if (m == req.method) {
method_ok = true;
break;
}
}
if (!method_ok) continue;
std::map<std::string, std::string> params;
if (match_pattern(r.pattern, req.path, params)) {
for (auto& [k, v] : params) req.path_params[k] = v;
out = r.handler;
return true;
}
}
return false;
}
const std::vector<Route>& Router::routes() const { return routes_; }
} // namespace molo::example::fw
+52
View File
@@ -0,0 +1,52 @@
#pragma once
// Router: FastAPI-style route groups mounted on the app with a shared prefix.
// Gap: real molo::routing in 05-request-routing.md owns path compilation,
// url_for and converters; this skeleton supports {param} segments only.
#include <functional>
#include <string>
#include <vector>
#include "Http.hpp"
namespace molo::example::fw {
using Handler = std::function<Response(Request)>;
struct Route {
std::vector<Method> methods;
std::string pattern;
std::string name;
Handler handler;
};
class Router {
public:
void add(std::vector<Method> methods, std::string pattern, std::string name,
Handler handler);
void get(std::string pattern, std::string name, Handler handler);
void post(std::string pattern, std::string name, Handler handler);
void put(std::string pattern, std::string name, Handler handler);
void patch(std::string pattern, std::string name, Handler handler);
void del(std::string pattern, std::string name, Handler handler);
void options(std::string pattern, std::string name, Handler handler);
void any(std::vector<Method> methods, std::string pattern, std::string name,
Handler handler);
void include_router(const std::string& prefix, const Router& other,
const std::string& name_prefix = "");
bool match(Request& req, Handler& out) const;
const std::vector<Route>& routes() const;
private:
std::vector<Route> routes_;
};
bool match_pattern(std::string_view pattern, std::string_view path,
std::map<std::string, std::string>& params);
} // namespace molo::example::fw
+205
View File
@@ -0,0 +1,205 @@
#include "Server.hpp"
#include <arpa/inet.h>
#include <netinet/in.h>
#include <sys/socket.h>
#include <unistd.h>
#include <cstring>
#include <sstream>
#include "Caps.hpp"
namespace molo::example::fw {
Server::Server(std::shared_ptr<Application> app) : app_(std::move(app)) {
stop();
}
Server::~Server() { stop(); }
bool Server::start(const std::string& host, int port) {
if (running_) return false;
listen_fd_ = ::socket(AF_INET, SOCK_STREAM, 0);
if (listen_fd_ < 0) return false;
int one = 1;
::setsockopt(listen_fd_, SOL_SOCKET, SO_REUSEADDR, &one, sizeof(one));
sockaddr_in addr{};
addr.sin_family = AF_INET;
addr.sin_port = htons((uint16_t)port);
if (::inet_pton(AF_INET, host.c_str(), &addr.sin_addr) != 1) {
::close(listen_fd_);
listen_fd_ = -1;
return false;
}
if (::bind(listen_fd_, (sockaddr*)&addr, sizeof(addr)) != 0) {
::close(listen_fd_);
listen_fd_ = -1;
return false;
}
if (port == 0) {
sockaddr_in bound{};
socklen_t len = sizeof(bound);
if (::getsockname(listen_fd_, (sockaddr*)&bound, &len) == 0)
port_ = ntohs(bound.sin_port);
} else {
port_ = port;
}
if (::listen(listen_fd_, caps::kServerBacklog) != 0) {
::close(listen_fd_);
listen_fd_ = -1;
return false;
}
running_ = true;
worker_ = std::thread([this]() { loop(); });
return true;
}
void Server::stop() {
bool was = running_.exchange(false);
if (listen_fd_ >= 0) {
::shutdown(listen_fd_, SHUT_RDWR);
::close(listen_fd_);
listen_fd_ = -1;
}
if (was && worker_.joinable() &&
worker_.get_id() != std::this_thread::get_id())
worker_.join();
else if (worker_.joinable() &&
worker_.get_id() == std::this_thread::get_id())
worker_.detach();
}
int Server::port() const { return port_; }
bool Server::running() const { return running_; }
void Server::loop() {
int served = 0;
while (running_ && served < caps::kMaxConnections) {
sockaddr_in peer{};
socklen_t len = sizeof(peer);
int fd = ::accept(listen_fd_, (sockaddr*)&peer, &len);
if (fd < 0) {
if (!running_) break;
continue;
}
struct timeval tv{};
tv.tv_sec = caps::kServerTimeoutSec;
::setsockopt(fd, SOL_SOCKET, SO_RCVTIMEO, &tv, sizeof(tv));
handle_one(fd);
::close(fd);
++served;
}
}
void Server::handle_one(int fd) {
std::string raw;
char buf[4096];
while (raw.size() < caps::kMaxHeaderBytes) {
ssize_t n = ::recv(fd, buf, sizeof(buf), 0);
if (n <= 0) break;
raw.append(buf, (std::size_t)n);
if (raw.find("\r\n\r\n") != std::string::npos) break;
}
std::size_t hdr_end = raw.find("\r\n\r\n");
if (hdr_end == std::string::npos) return;
std::string head = raw.substr(0, hdr_end);
std::string rest = raw.substr(hdr_end + 4);
std::istringstream lines(head);
std::string line;
if (!std::getline(lines, line)) return;
if (!line.empty() && line.back() == '\r') line.pop_back();
std::istringstream rl(line);
std::string method_s, target, version;
rl >> method_s >> target >> version;
Request req;
req.method = parse_method(method_s);
std::size_t q = target.find('?');
if (q == std::string::npos) {
req.path = target.empty() ? "/" : target;
} else {
req.path = target.substr(0, q);
req.query = parse_query(target.substr(q + 1));
}
std::size_t header_count = 0;
std::size_t content_length = 0;
while (std::getline(lines, line)) {
if (!line.empty() && line.back() == '\r') line.pop_back();
if (line.empty()) continue;
if (++header_count > caps::kMaxHeaderCount) break;
std::size_t colon = line.find(':');
if (colon == std::string::npos) continue;
std::string name = line.substr(0, colon);
std::string value = line.substr(colon + 1);
while (!value.empty() && value.front() == ' ') value.erase(value.begin());
req.headers.set(name, value);
if (name == "Content-Length" || name == "content-length") {
try {
content_length = (std::size_t)std::stoul(value);
} catch (...) {
content_length = 0;
}
}
}
std::string cookie_h = req.headers.get("Cookie");
if (!cookie_h.empty()) req.cookies = parse_cookies(cookie_h);
req.body = rest;
while (req.body.size() < content_length &&
req.body.size() < caps::kMaxRequestBody) {
ssize_t n = ::recv(fd, buf, sizeof(buf), 0);
if (n <= 0) break;
req.body.append(buf, (std::size_t)n);
}
Response res = app_->dispatch(std::move(req));
if (res.body.size() > caps::kMaxTestBody) {
res.status = 500;
res.body = "response over cap";
}
std::ostringstream out;
out << "HTTP/1.1 " << res.status << " " << status_text(res.status) << "\r\n";
out << "Content-Length: " << res.body.size() << "\r\n";
out << "Connection: close\r\n";
for (const auto& [k, v] : res.headers.entries()) {
if (k == "Content-Length" || k == "content-length") continue;
if (k == "Transfer-Encoding" || k == "transfer-encoding") continue;
out << k << ": " << v << "\r\n";
}
out << "\r\n" << res.body;
std::string wire = out.str();
std::size_t sent = 0;
while (sent < wire.size()) {
ssize_t n = ::send(fd, wire.data() + sent, wire.size() - sent, 0);
if (n <= 0) break;
sent += (std::size_t)n;
}
}
std::string http_roundtrip(const std::string& host, int port,
const std::string& raw_request) {
int fd = ::socket(AF_INET, SOCK_STREAM, 0);
if (fd < 0) return "";
sockaddr_in addr{};
addr.sin_family = AF_INET;
addr.sin_port = htons((uint16_t)port);
if (::inet_pton(AF_INET, host.c_str(), &addr.sin_addr) != 1) {
::close(fd);
return "";
}
if (::connect(fd, (sockaddr*)&addr, sizeof(addr)) != 0) {
::close(fd);
return "";
}
::send(fd, raw_request.data(), raw_request.size(), 0);
std::string out;
char buf[4096];
while (out.size() < caps::kMaxTestBody) {
ssize_t n = ::recv(fd, buf, sizeof(buf), 0);
if (n <= 0) break;
out.append(buf, (std::size_t)n);
}
::close(fd);
return out;
}
} // namespace molo::example::fw
+44
View File
@@ -0,0 +1,44 @@
#pragma once
// Minimal loopback HTTP/1.1 server for manual verification and the real-HTTP
// round-trip test. Sequential accept loop, static caps, no TLS, no HTTP/2.
// Gap: real event loop, timeouts, keep-alive, H2, and compression live in
// 01-runtime.md; this server exists only to prove the stack end to end.
#include <atomic>
#include <memory>
#include <string>
#include <thread>
#include "App.hpp"
namespace molo::example::fw {
class Server {
public:
explicit Server(std::shared_ptr<Application> app);
~Server();
Server(const Server&) = delete;
Server& operator=(const Server&) = delete;
bool start(const std::string& host, int port);
void stop();
int port() const;
bool running() const;
private:
void loop();
void handle_one(int fd);
std::shared_ptr<Application> app_;
int listen_fd_ = -1;
int port_ = 0;
std::atomic<bool> running_{false};
std::thread worker_;
};
std::string http_roundtrip(const std::string& host, int port,
const std::string& raw_request);
} // namespace molo::example::fw
+74
View File
@@ -0,0 +1,74 @@
#include "StaticFiles.hpp"
#include <cstdio>
#include <fstream>
#include <sstream>
namespace molo::example::fw {
bool path_is_safe(const std::string& request_path) {
if (request_path.find("..") != std::string::npos) return false;
if (request_path.find('\\') != std::string::npos) return false;
if (request_path.empty() || request_path.front() != '/') return false;
return true;
}
namespace {
std::string content_type_for(const std::string& name) {
auto ends = [&](const char* ext) {
std::string e(ext);
return name.size() >= e.size() &&
name.compare(name.size() - e.size(), e.size(), e) == 0;
};
if (ends(".html")) return "text/html; charset=utf-8";
if (ends(".css")) return "text/css; charset=utf-8";
if (ends(".js")) return "text/javascript; charset=utf-8";
if (ends(".json")) return "application/json";
if (ends(".svg")) return "image/svg+xml";
if (ends(".png")) return "image/png";
return "application/octet-stream";
}
} // namespace
std::string etag_for(const std::string& body) {
unsigned long long h = 1469598103934665603ULL;
for (unsigned char c : body) {
h ^= c;
h *= 1099511628211ULL;
}
char buf[32];
std::snprintf(buf, sizeof(buf), "\"%llx-%zu\"",
(unsigned long long)h, body.size());
return buf;
}
Response serve_disk_file(const std::string& root,
const std::string& subpath) {
std::string full = "/" + subpath;
if (!path_is_safe(full)) return TextResponse("unsafe path", 403);
std::ifstream in(root + full, std::ios::binary);
if (!in) return TextResponse("not found", 404);
std::ostringstream ss;
ss << in.rdbuf();
Response res(200, ss.str(), content_type_for(full));
res.headers.set("ETag", etag_for(res.body));
res.headers.set("Cache-Control", "public, max-age=3600");
return res;
}
Response serve_embedded(const std::map<std::string, std::string>& assets,
const std::string& subpath) {
std::string full = "/" + subpath;
if (!path_is_safe(full)) return TextResponse("unsafe path", 403);
auto it = assets.find(full);
if (it == assets.end()) return TextResponse("not found", 404);
Response res(200, it->second, content_type_for(full));
res.headers.set("ETag", etag_for(res.body));
res.headers.set("Cache-Control", "public, max-age=3600");
res.headers.set("X-Asset-Source", "embedded");
return res;
}
} // namespace molo::example::fw
+24
View File
@@ -0,0 +1,24 @@
#pragma once
// Static file serving from disk or from embedded C++ assets, with path
// traversal protection, ETags, and cache-control headers.
// Gap: real static serving in 01-runtime.md owns ranges, conditional
// requests, and directory indexing; the embedder CLI lives in 09-cli-ops.md.
#include <map>
#include <string>
#include "Http.hpp"
namespace molo::example::fw {
bool path_is_safe(const std::string& request_path);
Response serve_disk_file(const std::string& root, const std::string& subpath);
Response serve_embedded(const std::map<std::string, std::string>& assets,
const std::string& subpath);
std::string etag_for(const std::string& body);
} // namespace molo::example::fw
+246
View File
@@ -0,0 +1,246 @@
#include "Templates.hpp"
#include <stdexcept>
#include "Caps.hpp"
namespace molo::example::fw {
std::string html_escape(std::string_view in) {
std::string out;
out.reserve(in.size());
for (char c : in) {
switch (c) {
case '&': out += "&amp;"; break;
case '<': out += "&lt;"; break;
case '>': out += "&gt;"; break;
case '"': out += "&quot;"; break;
default: out.push_back(c); break;
}
}
return out;
}
namespace {
std::string trim(std::string s) {
while (!s.empty() && (s.front() == ' ' || s.front() == '\t' ||
s.front() == '\n' || s.front() == '\r'))
s.erase(s.begin());
while (!s.empty() && (s.back() == ' ' || s.back() == '\t' ||
s.back() == '\n' || s.back() == '\r'))
s.pop_back();
return s;
}
std::string apply_filter(std::string value, const std::string& filter) {
if (filter == "upper") {
for (char& c : value) c = (char)std::toupper((unsigned char)c);
} else if (filter == "lower") {
for (char& c : value) c = (char)std::tolower((unsigned char)c);
} else if (filter == "escape") {
value = html_escape(value);
}
return value;
}
std::string ctx_string(const TemplateCtx& ctx, const std::string& key) {
auto it = ctx.find(key);
if (it == ctx.end()) return "";
if (auto* s = std::get_if<std::string>(&it->second)) return *s;
return "";
}
bool ctx_truthy(const TemplateCtx& ctx, const std::string& key) {
auto it = ctx.find(key);
if (it == ctx.end()) return false;
if (auto* s = std::get_if<std::string>(&it->second))
return !s->empty() && *s != "false" && *s != "0";
if (auto* l = std::get_if<TemplateList>(&it->second)) return !l->empty();
return false;
}
} // namespace
void Environment::add_template(std::string name, std::string source) {
templates_[std::move(name)] = std::move(source);
}
void Environment::add_global(std::string key, std::string value) {
globals_[std::move(key)] = std::move(value);
}
bool Environment::has_template(const std::string& name) const {
return templates_.count(name) > 0;
}
std::string Environment::render(const std::string& name, TemplateCtx ctx) const {
auto it = templates_.find(name);
if (it == templates_.end()) throw std::runtime_error("template not found");
for (const auto& [k, v] : globals_) {
if (!ctx.count(k)) ctx[k] = v;
}
return render_source(name, it->second, ctx, 0);
}
std::string Environment::render_source(const std::string& name,
const std::string& src, TemplateCtx& ctx,
int depth) const {
(void)name;
if (depth > caps::kMaxTemplateDepth)
throw std::runtime_error("template depth exceeded");
std::string extends;
std::size_t pos = src.find("{% extends");
if (pos != std::string::npos) {
std::size_t q1 = src.find('"', pos);
std::size_t q2 = q1 == std::string::npos
? std::string::npos
: src.find('"', q1 + 1);
if (q1 != std::string::npos && q2 != std::string::npos)
extends = src.substr(q1 + 1, q2 - q1 - 1);
}
if (!extends.empty()) {
auto it = templates_.find(extends);
if (it == templates_.end()) throw std::runtime_error("base not found");
std::map<std::string, std::string> blocks;
std::size_t b = 0;
while (true) {
std::size_t bs = src.find("{% block", b);
if (bs == std::string::npos) break;
std::size_t be = src.find("%}", bs);
std::size_t cs = src.find("{% endblock %}", be);
if (be == std::string::npos || cs == std::string::npos) break;
std::string head = trim(src.substr(bs + 9, be - bs - 9));
blocks[head] = src.substr(be + 2, cs - be - 2);
b = cs + 14;
}
std::string base = it->second;
for (const auto& [k, v] : blocks) {
std::string open = "{% block " + k + " %}";
std::size_t s = base.find(open);
std::size_t e = s == std::string::npos
? std::string::npos
: base.find("{% endblock %}", s);
if (s != std::string::npos && e != std::string::npos)
base = base.substr(0, s) + v + base.substr(e + 14);
}
return render_blocks(base, ctx, depth);
}
return render_blocks(src, ctx, depth);
}
std::string Environment::render_blocks(const std::string& src, TemplateCtx& ctx,
int depth) const {
std::string out;
std::size_t i = 0;
while (i < src.size()) {
std::size_t v = src.find("{{", i);
std::size_t t = src.find("{%", i);
if (v == std::string::npos && t == std::string::npos) {
out += src.substr(i);
break;
}
if (v != std::string::npos && (t == std::string::npos || v < t)) {
out += src.substr(i, v - i);
std::size_t e = src.find("}}", v);
if (e == std::string::npos) break;
std::string expr = trim(src.substr(v + 2, e - v - 2));
bool safe = false;
std::string var = expr;
std::vector<std::string> filters;
std::size_t p = expr.find('|');
if (p != std::string::npos) {
var = trim(expr.substr(0, p));
std::string rest = expr.substr(p + 1);
std::size_t s = 0;
while (s < rest.size()) {
std::size_t q = rest.find('|', s);
std::string f = trim(rest.substr(s, q == std::string::npos
? q
: q - s));
if (f == "safe") {
safe = true;
} else if (!f.empty()) {
filters.push_back(f);
}
if (q == std::string::npos) break;
s = q + 1;
}
}
std::string value;
std::size_t dot = var.find('.');
if (dot != std::string::npos) {
value = ctx_string(ctx, var);
} else {
value = ctx_string(ctx, var);
}
for (const auto& f : filters) value = apply_filter(value, f);
if (!safe) value = html_escape(value);
out += value;
i = e + 2;
} else {
out += src.substr(i, t - i);
std::size_t e = src.find("%}", t);
if (e == std::string::npos) break;
std::string tag = trim(src.substr(t + 2, e - t - 2));
if (tag.rfind("if ", 0) == 0) {
std::string cond = trim(tag.substr(3));
std::size_t end = src.find("{% endif %}", e);
if (end == std::string::npos) break;
std::string inner = src.substr(e + 2, end - e - 2);
std::size_t els = inner.find("{% else %}");
std::string yes = els == std::string::npos ? inner
: inner.substr(0, els);
std::string no =
els == std::string::npos ? "" : inner.substr(els + 10);
out += render_blocks(ctx_truthy(ctx, cond) ? yes : no, ctx, depth + 1);
i = end + 11;
} else if (tag.rfind("for ", 0) == 0) {
std::string rest = trim(tag.substr(4));
std::size_t in = rest.find(" in ");
std::string item = in == std::string::npos
? ""
: trim(rest.substr(0, in));
std::string list = in == std::string::npos
? ""
: trim(rest.substr(in + 4));
std::size_t end = src.find("{% endfor %}", e);
if (end == std::string::npos) break;
std::string inner = src.substr(e + 2, end - e - 2);
auto it = ctx.find(list);
if (it != ctx.end()) {
if (auto* l = std::get_if<TemplateList>(&it->second)) {
for (const auto& row : *l) {
TemplateCtx sub = ctx;
for (const auto& [k, val] : row) {
sub[item + "." + k] = val;
sub[k] = val;
}
out += render_blocks(inner, sub, depth + 1);
}
}
}
i = end + 12;
} else if (tag.rfind("include ", 0) == 0) {
std::string rest = trim(tag.substr(8));
if (rest.size() >= 2 && rest.front() == '"') {
std::string inc = rest.substr(1, rest.size() - 2);
auto it = templates_.find(inc);
if (it != templates_.end())
out += render_blocks(it->second, ctx, depth + 1);
}
i = e + 2;
} else if (tag.rfind("block ", 0) == 0) {
std::size_t end = src.find("{% endblock %}", e);
if (end == std::string::npos) break;
out += render_blocks(src.substr(e + 2, end - e - 2), ctx, depth + 1);
i = end + 14;
} else {
i = e + 2;
}
}
}
return out;
}
} // namespace molo::example::fw
+39
View File
@@ -0,0 +1,39 @@
#pragma once
// Jinja-like template environment: extends plus blocks, includes, if, for,
// filters, autoescape for .html/.htm/.xml with explicit safe opt-out.
// Gap: real molo::templates in 05-request-routing.md owns the full lexer,
// parser, sandbox, and streamed rendering.
#include <map>
#include <string>
#include <variant>
#include <vector>
namespace molo::example::fw {
using TemplateList = std::vector<std::map<std::string, std::string>>;
using TemplateValue = std::variant<std::string, TemplateList>;
using TemplateCtx = std::map<std::string, TemplateValue>;
class Environment {
public:
void add_template(std::string name, std::string source);
void add_global(std::string key, std::string value);
bool has_template(const std::string& name) const;
std::string render(const std::string& name, TemplateCtx ctx) const;
private:
std::string render_source(const std::string& name, const std::string& src,
TemplateCtx& ctx, int depth) const;
std::string render_blocks(const std::string& src, TemplateCtx& ctx,
int depth) const;
std::map<std::string, std::string> templates_;
std::map<std::string, std::string> globals_;
};
std::string html_escape(std::string_view in);
} // namespace molo::example::fw
+65
View File
@@ -0,0 +1,65 @@
#include "TestClient.hpp"
#include "Caps.hpp"
#include "Http.hpp"
namespace molo::example::fw {
TestClient::TestClient(std::shared_ptr<Application> app)
: app_(std::move(app)) {}
Response TestClient::get(const std::string& path) {
return request(Method::Get, path);
}
Response TestClient::post(const std::string& path, const std::string& body,
const std::string& content_type) {
return request(Method::Post, path, body, {{"Content-Type", content_type}});
}
Response TestClient::request(
Method method, const std::string& path, const std::string& body,
const std::map<std::string, std::string>& headers) {
if (body.size() > caps::kMaxTestBody)
return TextResponse("test body over cap", 413);
Request req;
req.method = method;
std::size_t q = path.find('?');
if (q == std::string::npos) {
req.path = path;
} else {
req.path = path.substr(0, q);
req.query = parse_query(path.substr(q + 1));
}
req.headers.set("User-Agent", "living-example-test/1.0");
for (const auto& [k, v] : headers) req.headers.set(k, v);
if (!jar_.empty()) {
std::string cookie;
for (const auto& [k, v] : jar_) {
if (!cookie.empty()) cookie += "; ";
cookie += k + "=" + v;
}
req.cookies = jar_;
req.headers.set("Cookie", cookie);
}
if (!frozen_time_.empty()) req.headers.set("X-Test-Time", frozen_time_);
req.body = body;
Response res = app_->dispatch(std::move(req));
std::string set_cookie = res.headers.get("Set-Cookie");
if (!set_cookie.empty()) {
std::size_t semi = set_cookie.find(';');
std::string pair = set_cookie.substr(0, semi);
std::size_t eq = pair.find('=');
if (eq != std::string::npos)
jar_[pair.substr(0, eq)] = pair.substr(eq + 1);
}
return res;
}
void TestClient::freeze_time(const std::string& iso) { frozen_time_ = iso; }
const std::string& TestClient::frozen_time() const { return frozen_time_; }
void TestClient::clear_cookies() { jar_.clear(); }
} // namespace molo::example::fw
+38
View File
@@ -0,0 +1,38 @@
#pragma once
// Test client: drives the real Application (routing, middleware, views, DI,
// error mapping, in-memory DB) without sockets, plus a cookie jar and frozen
// time hook. Gap: real test client in 08-clients-openapi.md owns fixtures,
// DB resets, and time freezing.
#include <map>
#include <memory>
#include <string>
#include "App.hpp"
namespace molo::example::fw {
class TestClient {
public:
explicit TestClient(std::shared_ptr<Application> app);
Response get(const std::string& path);
Response post(const std::string& path, const std::string& body = "",
const std::string& content_type = "text/plain");
Response request(Method method, const std::string& path,
const std::string& body = "",
const std::map<std::string, std::string>& headers =
{});
void freeze_time(const std::string& iso);
const std::string& frozen_time() const;
void clear_cookies();
private:
std::shared_ptr<Application> app_;
std::map<std::string, std::string> jar_;
std::string frozen_time_;
};
} // namespace molo::example::fw
+9
View File
@@ -0,0 +1,9 @@
#include "Tls.hpp"
namespace molo::example::fw {
std::string StubTlsContext::name() const { return "tls-stub-no-wolfssl"; }
bool StubTlsContext::available() const { return false; }
} // namespace molo::example::fw
+25
View File
@@ -0,0 +1,25 @@
#pragma once
// TLS posture: framework code depends only on ITlsContext. wolfSSL is NOT
// installed in this environment, so only StubTlsContext exists. It refuses
// handshakes loudly instead of silently serving plaintext as TLS.
// Gap: real wolfSSL-backed context from 03-security.md (TLS 1.3).
#include <string>
namespace molo::example::fw {
class ITlsContext {
public:
virtual ~ITlsContext() = default;
virtual std::string name() const = 0;
virtual bool available() const = 0;
};
class StubTlsContext : public ITlsContext {
public:
std::string name() const override;
bool available() const override;
};
} // namespace molo::example::fw
+189
View File
@@ -0,0 +1,189 @@
#include "Validate.hpp"
#include <cctype>
#include "Caps.hpp"
#include "Http.hpp"
namespace molo::example::fw {
ValidationError::ValidationError(std::vector<FieldError> failures)
: HttpError(422, "validation_error", "validation failed"),
failures_(std::move(failures)) {}
const std::vector<FieldError>& ValidationError::failures() const {
return failures_;
}
std::string ValidationError::to_json() const {
std::string out = "{\"error\":\"validation_error\",\"failures\":[";
bool first = true;
for (const auto& f : failures_) {
if (!first) out += ",";
first = false;
out += "{\"field\":\"" + json_escape(f.field) + "\",\"message\":\"" +
json_escape(f.message) + "\"}";
}
return out + "]}";
}
Model::Model(std::vector<Field> fields) : fields_(std::move(fields)) {}
namespace {
bool looks_like_email(const std::string& v) {
auto at = v.find('@');
if (at == std::string::npos || at == 0) return false;
return v.find('.', at) != std::string::npos;
}
bool parse_long(const std::string& v, long& out) {
if (v.empty()) return false;
std::size_t i = 0;
bool neg = false;
if (v[0] == '-' || v[0] == '+') {
neg = v[0] == '-';
i = 1;
}
if (i >= v.size()) return false;
long acc = 0;
for (; i < v.size(); ++i) {
if (!std::isdigit((unsigned char)v[i])) return false;
acc = acc * 10 + (v[i] - '0');
}
out = neg ? -acc : acc;
return true;
}
} // namespace
std::map<std::string, std::string> Model::validate(
const std::map<std::string, std::string>& input) const {
std::vector<FieldError> failures;
std::map<std::string, std::string> clean;
for (const auto& f : fields_) {
auto it = input.find(f.name);
std::string value = it == input.end() ? "" : it->second;
bool missing = it == input.end() || value.empty();
if (missing) {
if (!f.required) {
if (!f.default_value.empty()) clean[f.name] = f.default_value;
continue;
}
failures.push_back({f.name, "field is required"});
continue;
}
if (f.type != FieldType::Integer && value.size() < f.min_len)
failures.push_back({f.name, "too short"});
else if (f.type != FieldType::Integer && value.size() > f.max_len)
failures.push_back({f.name, "too long"});
else if (f.type == FieldType::Integer) {
long n = 0;
if (!parse_long(value, n)) {
failures.push_back({f.name, "not an integer"});
} else if (f.has_range && (n < f.min_value || n > f.max_value)) {
failures.push_back({f.name, "out of range"});
} else {
clean[f.name] = value;
}
continue;
} else if (f.type == FieldType::Email && !looks_like_email(value)) {
failures.push_back({f.name, "not an email address"});
continue;
} else if (f.type == FieldType::Boolean &&
value != "true" && value != "false" && value != "1" &&
value != "0") {
failures.push_back({f.name, "not a boolean"});
continue;
} else {
clean[f.name] = value;
}
}
if (!failures.empty()) throw ValidationError(std::move(failures));
return clean;
}
const std::vector<Field>& Model::fields() const { return fields_; }
std::map<std::string, std::string> parse_json_object_flat(
const std::string& body) {
std::map<std::string, std::string> out;
std::size_t i = 0;
int depth = 0;
auto skip_ws = [&]() {
while (i < body.size() &&
std::isspace((unsigned char)body[i]))
++i;
};
skip_ws();
if (i >= body.size() || body[i] != '{') return out;
++i;
++depth;
std::size_t fields = 0;
while (i < body.size() && fields < caps::kMaxFormFields) {
skip_ws();
if (i < body.size() && body[i] == '}') break;
if (i >= body.size() || body[i] != '"') break;
++i;
std::string key;
while (i < body.size() && body[i] != '"') {
if (body[i] == '\\' && i + 1 < body.size()) {
key.push_back(body[i + 1]);
i += 2;
} else {
key.push_back(body[i++]);
}
}
if (i < body.size()) ++i;
skip_ws();
if (i >= body.size() || body[i] != ':') break;
++i;
skip_ws();
std::string value;
if (i < body.size() && body[i] == '"') {
++i;
while (i < body.size() && body[i] != '"') {
if (body[i] == '\\' && i + 1 < body.size()) {
value.push_back(body[i + 1]);
i += 2;
} else {
value.push_back(body[i++]);
}
}
if (i < body.size()) ++i;
} else {
while (i < body.size() && body[i] != ',' && body[i] != '}') {
if (body[i] == '{' || body[i] == '[') {
if (++depth > caps::kMaxJsonDepth) return out;
}
value.push_back(body[i++]);
}
while (!value.empty() &&
std::isspace((unsigned char)value.back()))
value.pop_back();
}
out[key] = value;
++fields;
skip_ws();
if (i < body.size() && body[i] == ',') ++i;
}
return out;
}
Form::Form(Model model) : model_(std::move(model)) {}
std::map<std::string, std::string> Form::bind(const Request& req) const {
std::string ct = req.headers.get("Content-Type");
std::map<std::string, std::string> input;
if (ct.find("application/json") != std::string::npos) {
input = parse_json_object_flat(req.body);
} else {
input = parse_form(req.body);
for (const auto& [k, v] : req.query) {
if (!input.count(k)) input[k] = v;
}
}
return model_.validate(input);
}
} // namespace molo::example::fw
+72
View File
@@ -0,0 +1,72 @@
#pragma once
// Single validation framework: field descriptors plus whole-model validation
// that reports ALL failures in one error. Forms bind JSON and urlencoded
// bodies into the same models. Gap: real molo::validate and molo::forms in
// 05-request-routing.md own coercions, nested models, and OpenAPI schemas.
#include <map>
#include <optional>
#include <string>
#include <vector>
#include "App.hpp"
namespace molo::example::fw {
enum class FieldType { String, Integer, Boolean, Email };
struct Field {
std::string name;
FieldType type = FieldType::String;
bool required = true;
std::size_t min_len = 0;
std::size_t max_len = 1024;
long min_value = 0;
long max_value = 0;
bool has_range = false;
std::string default_value;
};
struct FieldError {
std::string field;
std::string message;
};
class ValidationError : public HttpError {
public:
explicit ValidationError(std::vector<FieldError> failures);
const std::vector<FieldError>& failures() const;
std::string to_json() const;
private:
std::vector<FieldError> failures_;
};
class Model {
public:
explicit Model(std::vector<Field> fields);
std::map<std::string, std::string> validate(
const std::map<std::string, std::string>& input) const;
const std::vector<Field>& fields() const;
private:
std::vector<Field> fields_;
};
std::map<std::string, std::string> parse_json_object_flat(
const std::string& body);
class Form {
public:
explicit Form(Model model);
std::map<std::string, std::string> bind(const Request& req) const;
private:
Model model_;
};
} // namespace molo::example::fw
+26
View File
@@ -0,0 +1,26 @@
#include "View.hpp"
namespace molo::example::fw {
View::View(Request req) : req_(std::move(req)) {}
Response View::dispatch() {
switch (req_.method) {
case Method::Get: return get();
case Method::Post: return post();
case Method::Put: return put();
case Method::Patch: return patch();
case Method::Delete: return del();
case Method::Options: return options();
default: return TextResponse("method not allowed", 405);
}
}
Response View::get() { return TextResponse("method not allowed", 405); }
Response View::post() { return TextResponse("method not allowed", 405); }
Response View::put() { return TextResponse("method not allowed", 405); }
Response View::patch() { return TextResponse("method not allowed", 405); }
Response View::del() { return TextResponse("method not allowed", 405); }
Response View::options() { return TextResponse("method not allowed", 405); }
} // namespace molo::example::fw
+29
View File
@@ -0,0 +1,29 @@
#pragma once
// Class-based views, aiohttp style: constructed with the Request, one virtual
// coroutine-equivalent per HTTP method, dispatch selects by method.
// Gap: real molo::views::View in 05-request-routing.md is coroutine based.
#include "Http.hpp"
namespace molo::example::fw {
class View {
public:
explicit View(Request req);
virtual ~View() = default;
Response dispatch();
virtual Response get();
virtual Response post();
virtual Response put();
virtual Response patch();
virtual Response del();
virtual Response options();
protected:
Request req_;
};
} // namespace molo::example::fw
+143
View File
@@ -0,0 +1,143 @@
#include "Workflow.hpp"
#include <cstdio>
#include "Caps.hpp"
namespace molo::example::fw {
bool parse_commit(const std::string& subject, const std::string& body,
CommitInfo& out, std::string& error) {
std::string s = subject;
if (s.size() > (std::size_t)caps::kMaxCommitSubject) {
error = "subject too long";
return false;
}
std::size_t colon = s.find(':');
if (colon == std::string::npos) {
error = "missing colon";
return false;
}
std::string head = s.substr(0, colon);
out.description = s.substr(colon + 1);
while (!out.description.empty() && out.description.front() == ' ')
out.description.erase(out.description.begin());
if (!head.empty() && head.back() == '!') {
out.breaking = true;
head.pop_back();
}
std::size_t paren = head.find('(');
if (paren == std::string::npos) {
out.type = head;
} else {
out.type = head.substr(0, paren);
std::size_t close = head.find(')', paren);
if (close == std::string::npos) {
error = "unclosed scope";
return false;
}
out.scope = head.substr(paren + 1, close - paren - 1);
}
const char* allowed[] = {"feat", "fix", "docs", "style", "refactor",
"perf", "test", "build", "ci", "chore"};
bool ok = false;
for (const char* t : allowed) {
if (out.type == t) {
ok = true;
break;
}
}
if (!ok) {
error = "unknown type: " + out.type;
return false;
}
if (body.find("BREAKING CHANGE") != std::string::npos) out.breaking = true;
return true;
}
std::string bump_name(Bump bump) {
switch (bump) {
case Bump::None: return "none";
case Bump::Patch: return "patch";
case Bump::Minor: return "minor";
case Bump::Major: return "major";
}
return "none";
}
Bump ReleasePlanner::decide(const std::vector<CommitInfo>& commits) const {
bool feat = false, fix = false;
for (const auto& c : commits) {
if (c.breaking) return Bump::Major;
if (c.type == "feat") feat = true;
if (c.type == "fix") fix = true;
}
if (feat) return Bump::Minor;
if (fix) return Bump::Patch;
return Bump::None;
}
std::string ReleasePlanner::next_version(
const std::string& current,
const std::vector<CommitInfo>& commits) const {
int major = 0, minor = 0, patch = 0;
std::sscanf(current.c_str(), "%d.%d.%d", &major, &minor, &patch);
switch (decide(commits)) {
case Bump::Major: return std::to_string(major + 1) + ".0.0";
case Bump::Minor:
return std::to_string(major) + "." + std::to_string(minor + 1) + ".0";
case Bump::Patch:
return std::to_string(major) + "." + std::to_string(minor) + "." +
std::to_string(patch + 1);
case Bump::None: return current;
}
return current;
}
std::string ChangelogWriter::entry(
const std::string& version, const std::string& date,
const std::vector<CommitInfo>& commits) const {
std::string added, changed, fixed, removed;
for (const auto& c : commits) {
std::string line =
"- " + (c.scope.empty() ? "" : "(" + c.scope + ") ") + c.description +
"\n";
if (c.breaking)
changed += line;
else if (c.type == "feat")
added += line;
else if (c.type == "fix")
fixed += line;
else
changed += line;
}
std::string out = "## [" + version + "] - " + date + "\n";
if (!added.empty()) out += "### Added\n" + added;
if (!changed.empty()) out += "### Changed\n" + changed;
if (!fixed.empty()) out += "### Fixed\n" + fixed;
if (!removed.empty()) out += "### Removed\n" + removed;
int lines = 0;
for (char c : out) {
if (c == '\n') ++lines;
}
if (lines > caps::kMaxChangelogLines)
out += "(truncated to cap)\n";
return out;
}
void ReleaseVerifier::add_check(std::string name, bool passed,
std::string detail) {
checks_.push_back({std::move(name), passed, std::move(detail)});
}
bool ReleaseVerifier::green() const {
if (checks_.empty()) return false;
for (const auto& c : checks_) {
if (!c.passed) return false;
}
return true;
}
std::vector<VerifyCheck> ReleaseVerifier::checks() const { return checks_; }
} // namespace molo::example::fw
+57
View File
@@ -0,0 +1,57 @@
#pragma once
// Autonomous release pipeline: commits since tag to bump decision, changelog
// writing, and pre-tag verification. Dry-run mode never writes.
// Final home is tools/release/ under namespace molo::workflow; this example
// copy proves the rules and is marked as a demo, not the pipeline itself.
// Gap: real molo::workflow in tools/release/ plus CLI surface in 09-cli-ops.md.
#include <string>
#include <vector>
namespace molo::example::fw {
struct CommitInfo {
std::string type;
std::string scope;
std::string description;
bool breaking = false;
};
bool parse_commit(const std::string& subject, const std::string& body,
CommitInfo& out, std::string& error);
enum class Bump { None, Patch, Minor, Major };
std::string bump_name(Bump bump);
class ReleasePlanner {
public:
Bump decide(const std::vector<CommitInfo>& commits) const;
std::string next_version(const std::string& current,
const std::vector<CommitInfo>& commits) const;
};
class ChangelogWriter {
public:
std::string entry(const std::string& version, const std::string& date,
const std::vector<CommitInfo>& commits) const;
};
struct VerifyCheck {
std::string name;
bool passed = false;
std::string detail;
};
class ReleaseVerifier {
public:
void add_check(std::string name, bool passed, std::string detail = "");
bool green() const;
std::vector<VerifyCheck> checks() const;
private:
std::vector<VerifyCheck> checks_;
};
} // namespace molo::example::fw
+35
View File
@@ -0,0 +1,35 @@
// Living example server entry: serves the demo app on loopback.
// Usage: living-server [port] (default 8080)
#include <chrono>
#include <iostream>
#include <string>
#include <thread>
#include "app/App.hpp"
#include "fw/Server.hpp"
int main(int argc, char** argv) {
int port = 8080;
if (argc > 1) {
try {
port = std::stoi(argv[1]);
} catch (...) {
std::cerr << "bad port\n";
return 1;
}
}
molo::example::app::Services services;
auto app = molo::example::app::build_application(services);
molo::example::fw::Server server(app);
if (!server.start("127.0.0.1", port)) {
std::cerr << "bind failed\n";
return 1;
}
std::cout << "living example on http://127.0.0.1:" << server.port() << "\n";
std::cout << "press Ctrl-C to stop\n";
while (server.running()) {
std::this_thread::sleep_for(std::chrono::milliseconds(200));
}
return 0;
}
+25
View File
@@ -0,0 +1,25 @@
/* Living example stylesheet: mobile-first, responsive by default. */
* { box-sizing: border-box; }
body { margin: 0; font-family: system-ui, sans-serif; line-height: 1.5; }
.topbar { display: flex; align-items: center; gap: 1rem; padding: 0.5rem 1rem;
background: #102030; color: #fff; }
.brand { color: #fff; font-weight: bold; text-decoration: none; }
.nav-wide { display: none; gap: 0.75rem; }
.nav-wide a { color: #cde; text-decoration: none; }
.nav-narrow { margin-left: auto; }
.nav-narrow nav { display: flex; flex-direction: column; gap: 0.25rem;
background: #fff; padding: 0.5rem; border: 1px solid #ccc; }
main { padding: 1rem; max-width: 60rem; margin: 0 auto; }
table { border-collapse: collapse; width: 100%; }
th, td { border: 1px solid #ccc; padding: 0.25rem 0.5rem; text-align: left; }
form { display: flex; flex-direction: column; gap: 0.5rem; max-width: 28rem; }
input, textarea, button { font-size: 1rem; padding: 0.4rem; }
.ok { color: #0a0; }
.error { color: #a00; }
.hint { color: #555; }
/* Big button group becomes a dropdown on small phones: the details element
above is the dropdown; on wide screens show the plain link row. */
@media (min-width: 48rem) {
.nav-wide { display: flex; }
.nav-narrow { display: none; }
}
+6
View File
@@ -0,0 +1,6 @@
// Living example script: tiny health badge, no framework needed.
fetch("/health").then(function (r) { return r.json(); }).then(function (j) {
var el = document.createElement("p");
el.textContent = "health: " + j.status + " tls: " + j.tls;
document.body.appendChild(el);
});
+9
View File
@@ -53,6 +53,11 @@ feature. C++26 stays excluded until published and stably supported.
- Response formats: HTML, JSON, XML, plain text and others, with content negotiation
- Streaming responses and passthrough streaming (proxy or generate bodies without full buffering)
- Modern async HTTP/API/REST client with HTTP/1.1 and HTTP/2 support (pooling, retries, timeouts, JSON/XML/form handling, file upload, streaming, test double)
- Multi-tenancy: first-class tenants with silo/bridge/pool isolation, per-tenant config, quotas, rate limits, feature flags and metrics
- Audit and compliance: immutable hash-chained audit log, GDPR export/erasure cascade, retention with legal hold, PII marking, log redaction, non-prod masking
- Operability at scale: rolling/blue-green deploys, drains, distributed locks/election, breakers, bulkheads, load shedding, deadlines, SLO budgets, chaos hooks, debug endpoints
- API governance: API keys with scopes/quotas/expiry, router versioning with deprecation policy, OpenAPI breaking-change gate, rate-limit tiers, surface linter
- Supply chain and trust: SBOM (SPDX + CycloneDX), signed SLSA provenance, wolfSSL pin policy, vuln-scan gate, Sigstore-signed release artifacts
### 3. Core runtime and HTTP fundamentals
@@ -80,6 +85,7 @@ folk knowledge:
- Secrets management: loading and rotation story for passwords, API keys, encryption keys
- XSS-safe templating defaults (auto-escaping), path traversal protection
- TLS via wolfSSL (sole dependency exception, commercial license for closed-source use), natively compiled, TLS 1.3
- Immutable audit log: append-only hash-chained record of security-relevant events (auth, grants, key use, config change, export/erasure), auditor-role reads, verification command
### 5. Data layer and ORM
@@ -152,3 +158,6 @@ An AI agent keeps the tree consistent following `AGENTS.md`.
5. OpenAPI generation, test client, modern HTTP/API/REST client, dev server / CLI experience.
6. Replication/sync semantics and conflict handling.
7. Autonomous git/versioning/changelog pipeline + `AGENTS.md` + docs templates + big living example project updated with every feature.
8. Multi-tenancy jointly with the data layer: tenant context in place before ORM/pooling harden, then quotas, flags and per-tenant metrics.
9. Audit/compliance (PII marks, redaction, audit chain, retention/holds, rights engine, masking) plus operability at scale (coordination, drains, resilience, deploys, SLO, chaos, debug).
10. API governance (keys, versioning, diff gate, tiers, linter) plus supply chain and trust (SBOM, provenance, signing, vuln gate) wired into the release pipeline.
+187
View File
@@ -0,0 +1,187 @@
# 11 - Multi-Tenancy
Title: Multi-Tenancy
Scope: plan.md sections 2, 5, 7 partial. First-class tenants: isolated data paths, per-tenant config, quotas, rate limits, feature flags, per-tenant metrics; tenant-aware ORM, auth, routing, replication. Must land before the data layer hardens.
## 1. Purpose and philosophy
Every request, query, log record, metric, task, and replication entry belongs to exactly one tenant or carries an explicit system exemption. Tenancy is resolved once at the edge, attached to the request and data contexts, and enforced at the lowest layer that can do it (the database), never trusted to caller discipline.
One API over a strategy spectrum: Silo (dedicated database instance or cluster per tenant), Bridge (database-per-tenant on a shared Postgres cluster, file-per-tenant on SQLite), Pool (shared tables with tenant_id plus Row-Level Security on Postgres). Strategy is chosen per tenant at provisioning time, because switching models later is costly (see Best practices).
This file must land before 04-data.md hardens: the data Context shape, pool ownership, sync and healer behavior, and the migration journal all branch on isolation strategy. Retrofitting tenancy after those freeze would fork the ORM.
## 2. Best practices (from research)
1. Three partitioning models: "In the silo model, each tenant has their own unique physical resource. The bridge model logically separates tenants on a physical resource, for example, a database-per-tenant on a shared physical database. In the pool model, all tenants share a single logical construct on a physical resource, for example, a single schema shared by all tenants." (Source 1)
2. Silo gives the strongest isolation ("separate database instance and separate compute instance per tenant"), motivated by noisy-neighbour, compliance, or encryption requirements; bridge exists to cut cost by sharing the instance between tenants. (Source 1)
3. On Postgres bridge, AWS recommends database-per-tenant over schema-per-tenant: schemas are logical constructs that do not separate data on disk and share one directory, which risks system limits with many tenants. (Source 1, paraphrased)
4. A Postgres client connection "can only access data in a single database, the one specified in the connection request" (Source 4), so bridge needs one pool per tenant database while pool strategy keeps a single shared pool.
5. Pool enforcement belongs in the database: "When row security is enabled on a table ... all normal access to the table for selecting rows or modifying rows must be allowed by a row security policy", and "If no policy exists for the table, a default-deny policy is used" (Source 2). Policies can target ALL commands or SELECT, INSERT, UPDATE, DELETE, specific roles, or both.
6. The tenancy model "determines how each tenant's data is mapped to storage" and "Switching to a different model later is sometimes costly" (Source 3). Single-tenancy stores one tenant per database; multi-tenancy stores several tenants per database "with mechanisms to protect data privacy" (Source 3). Hence strategy-per-tenant at provisioning plus explicit migration procedures.
7. SQLite file-per-tenant rests on ATTACH: "The ATTACH DATABASE statement adds another database file to the current database connection" (Source 5), with a static limit on attached databases per connection. Under WAL, multi-file transactions stay atomic per file but a crash mid-COMMIT can split them across files (Source 5), so bridge on SQLite uses one connection per tenant file and never spans a transaction across files.
8. Tenant isolation "is fundamental to the design and development of software as a service (SaaS) systems" and crossing a tenant boundary "would represent a significant and potentially un-recoverable event for a SaaS business" (Source 6). Hence default-deny everywhere in this file.
9. Triangulation: AWS and Microsoft agree on the silo to pool spectrum with cost versus isolation tradeoffs (Sources 1, 3). AWS and the Postgres docs agree that bridge means database-per-tenant guarded by native access controls (Sources 1, 4). Pool safety is agreed from two sides: RLS default-deny at the engine (Source 2) plus app-level tenant scoping as defense in depth (this file, Rules R1 and R2).
## 3. Structure
Root: `src/molo/tenancy/`, namespace `molo::tenancy`. One class or concern per file pair.
- `tenant_id.h`: `TenantId` strong type (uuid7 plus validated slug).
- `tenant.h/.cpp`: `Tenant` record (id, slug, strategy, status, timestamps).
- `strategy.h`: `IsolationStrategy { Silo, Bridge, Pool }`, `strategy_from_string`.
- `catalog.h/.cpp`: `TenantCatalog` (create, lookup, suspend, tombstone, purge); `store/catalog_store.h` interface plus `store/memory_catalog.h`, `store/db_catalog.h`.
- `resolver.h/.cpp`: `TenantResolver` (ordered chain: subdomain, header, path prefix, auth claim).
- `context.h`: `TenantContext` (id, strategy, connection selector), embedded in the 04-data.md data Context and the request scope.
- `middleware.h/.cpp`: `TenantMiddleware` (resolve, attach, reject unknown or suspended).
- `provisioner.h/.cpp`: `TenantProvisioner` (provision, strategy migration, suspend, delete with floor).
- `config_overlay.h/.cpp`: `TenantConfig` (layered typed overlay over global config, cache, invalidation).
- `quota.h/.cpp`: `QuotaManager` (usage counters, pre-allocation checks).
- `tenant_buckets.h/.cpp`: per-tenant rate-limit buckets built on the 03-security.md limiter core.
- `feature_flags.h/.cpp`: `FeatureFlags` (per-tenant typed flags, cache, change events).
- `metrics.h/.cpp`: `TenantMetrics` (tenant-labeled recording with allowlist cap).
- `orm_scope.h/.cpp`: `TenantScope` (automatic query filter injection, privileged escape hatch).
## 4. Rules (hard, numbered)
- R1. Every ORM query in pool mode carries tenant scope. Unscoped data access fails closed unless it uses the explicit privileged API, which logs tenant pair plus reason.
- R2. Pool on Postgres always enables Row-Level Security with default-deny policies on every tenant table. The app-level filter is defense in depth, never the only enforcement.
- R3. Tenant database state is set per transaction or per checkout (SET LOCAL semantics) and reset on release. Shared pooled connections never retain a tenant between checkouts.
- R4. Bridge means database-per-tenant on Postgres and file-per-tenant on SQLite. Schema-per-tenant is not offered.
- R5. Cross-tenant reads and writes are forbidden except through explicit system APIs that record both tenant ids and the reason in logs and audit.
- R6. Tenant resolution runs before auth in the middleware chain. Unknown tenant yields 404 `tenant_unknown`; suspended tenant yields 403 `tenant_suspended`.
- R7. Quotas are checked before allocation. Over-quota fails closed: 429 with Retry-After for rate quotas, 507 for storage quotas.
- R8. The `tenant` metric label is allowed only for tenants on the metrics allowlist (static cap); all others record as `tenant="other"` and count an overflow metric.
- R9. Tenant deletion is a two-phase tombstone plus purge with a retention window. Purge (data destruction) requires explicit human confirmation and is never autonomous.
- R10. Every task envelope, oplog entry, cache key namespace, pubsub channel, log record, and trace span attribute set carries the tenant id. Replay and sync filter by tenant.
- R11. Per-tenant config overlays validate against the same typed schema as global config. An invalid overlay fails the update atomically; partial application is forbidden.
- R12. Isolation strategy is fixed per tenant at provisioning. Strategy migration is an explicit procedure with pre-checks, backfill, and post-verification, never silent.
## 5. Development guidelines
- Build in section 7 order: resolver plus context plus catalog first, then pool scoping, then bridge pools, then quotas, flags, and metrics. Each step ends green through the real stack.
- Keep the strategy matrix in exactly one place (`TenantProvisioner` plus the pool factory). Callers take a `TenantContext` and never branch on backend or strategy.
- Fixtures always provision at least two tenants plus system scope. Every tenant-visible route test asserts the neighbor tenant sees nothing (404 or empty, never a leak).
- RLS policies are generated from the model registry, reviewed as SQL text, and applied by the same migrator as schema DDL. No hand-written policy drift.
- Quota checks sit at admission points (middleware, pool checkout, upload start, task enqueue), not sprinkled in business logic.
- Feature flags default from global config; a tenant overlay only overrides named flags. Unknown flag names fail closed at update time.
- Deletion and purge paths are dry-run first with an itemized report (databases, files, keys, streams), then confirmed execution.
## 6. Specifications
### 6.1 Identity and resolution
- `TenantId`: internal uuid7 plus public slug matching `[a-z0-9-]{3,63}`, starting and ending alphanumeric. Slug is unique per deployment; uuid is the stored key.
- Resolvers, in default order (configurable): subdomain (`<slug>.example.com`), header `X-Tenant-ID` (slug or uuid), path prefix `/t/<slug>/` (stripped before routing), auth claim `tid` (verified token only).
- First match wins; conflicting signals (header says A, path says B) yield 400 `tenant_conflict`. No signal yields the configured default tenant in single-tenant dev mode, else 404 `tenant_unknown`.
- Statuses: `provisioning`, `active`, `suspended`, `tombstoned`. Only `active` serves traffic; `suspended` serves 403 with a fixed body; `tombstoned` behaves as unknown.
### 6.2 Catalog record (JSON, also the on-disk shape)
`{"id":"uuid7","slug":"acme","strategy":"pool","status":"active","pg_database":"molo_t_acme","sqlite_file":"tenants/acme.db","quotas":{...},"flags":{...},"created_at":"iso8601","updated_at":"iso8601"}`. Slug to id cached in memory (cap 65536 entries, LRU); catalog reads bypass tenant scope via the privileged API and are audit-logged.
### 6.3 Pool mode (shared tables)
- Every tenant model gains `tenant_id UUID NOT NULL`; composite indexes lead with `tenant_id`. The ORM injects `tenant_id = current` into every generated query; raw fragments must bind it explicitly.
- Postgres: `ALTER TABLE <t> ENABLE ROW LEVEL SECURITY` plus generated policy `CREATE POLICY tenant_isolation ON <t> USING (tenant_id = current_setting('app.current_tenant')::uuid) WITH CHECK (...)` for ALL commands on the app role. The tenant GUC is set with `SET LOCAL` inside each transaction; pooled checkouts assert the GUC is empty before use.
- SQLite pool: shared file with `tenant_id` column plus app filter; RLS does not exist, so integration tests additionally run a hostile-shape suite where hand-written SQL without scope must fail at the driver guard.
- Max tenants per pool deployment: 100000 (soft, operations warning at 80 percent). Beyond that, split pools or move tenants to bridge.
### 6.4 Bridge mode
- Postgres: one database per tenant on the shared cluster, name `molo_t_<slug>` (truncated to 63 chars with uuid suffix on collision). Per-tenant pool: min 0, max 8, acquire timeout 5 s. Connection strings derive from the catalog, never from request input.
- SQLite: one file per tenant at `tenants/<slug>.db`, same pragmas as 04-data.md (WAL, foreign keys on, busy timeout 5000). One writer gate per file; no transaction ever spans two tenant files (see Best practices 7).
- Bridge caps: max 1024 tenant databases per Postgres cluster, max 4096 tenant files per deployment (soft; shard beyond).
### 6.5 Silo mode
- Dedicated Postgres cluster (or instance) per tenant, or dedicated file root per tenant on SQLite. The catalog stores a connection profile name; credentials come from 03-security.md secrets per profile. All pool defaults from 04-data.md apply unchanged inside the silo. Silo tenants skip RLS (single tenant per database) but keep `tenant_id` columns for portability.
### 6.6 Sync, healer, migrations per tenant
- Sync and self-heal run per tenant target: pool runs once on shared tables (policies included); bridge and silo run once per tenant database or file. Heal DDL in pool mode never touches `tenant_id` columns except widening the type.
- The migration journal is per target (shared journal for pool, per-database or per-file journal otherwise). `molo migrate` (09-cli-ops.md) iterates tenant targets with a per-tenant report and continues past single-tenant failure, exiting nonzero with a summary.
### 6.7 Quotas and rate limits
- Defaults per tenant (all overridable via overlay): requests 600/min with burst 2x for 10 s; concurrent connections 256; realtime connections 1024; storage 10 GB; uploads 1 GB/day; queued tasks 10000; export rows per request 100000.
- Rate overage: 429 with `Retry-After` and `X-Tenant-ID` echo. Storage overage: 507 with a problem body naming the quota. Usage counters live in memory plus periodic catalog persist (every 60 s or 1000 deltas); restart rebuilds from stores, never trusts memory alone.
- Noisy-neighbour guard: a tenant exceeding 50 percent of shared pool checkouts over a 60 s window is throttled to its fair share and emits a warning event; sustained abuse triggers an automatic suspension proposal that a human confirms.
### 6.8 Per-tenant config and feature flags
- Overlay keys mirror global config paths (`http.body_max`, `auth.session_idle`, ...); unknown paths rejected. Overlay cache TTL 30 s, tag-invalidated on update; every read path takes the merged view, never global alone when a tenant is active.
- Flags: typed map (bool, int64, string; max 256 flags per tenant, name `[a-z0-9_.]{1,128}`, string value max 4 KB). Reads are synchronous from cache; updates emit a `tenant.flags_changed` event that cache invalidation and long-lived connections honor within 30 s.
### 6.9 Per-tenant metrics, logs, traces
- Metrics: shared registry with `tenant` label gated by the metrics allowlist (default cap 512 tenants, LRU admission, overflow to `tenant="other"` plus `molo_tenant_label_overflows_total`). Framework per-tenant series: requests total, request duration, db queries total, quota denials total, realtime connections gauge.
- Logs: every record in tenant scope carries `tenant_id`; the redaction rules of 02-observability.md apply unchanged. Traces: `tenant.id` span attribute on server spans; sampling stays head-based and tenant-blind.
- Cardinality audit: CI fails if any new metric uses an unbounded tenant-derived label outside this section.
### 6.10 Tenant-aware auth, routing, realtime, replication
- Auth (with 03-security.md): users belong to one or more tenants; sessions bind to exactly one tenant at login; switching tenant requires re-resolution plus a membership check and rotates the session id. The login URL carries the tenant signal; token `tid` must equal the resolved tenant.
- Routing (with 05-request-routing.md): `TenantMiddleware` runs immediately after error mapping and observability, before security guards that need tenant quotas. Route helpers accept a tenant parameter for URL building in path-prefix mode.
- Realtime (with 06-realtime.md): rooms and channels are namespaced `tenant:<id>:<room>`; cross-tenant join is rejected; connection caps enforced per tenant at upgrade; broadcasts fan out only within the tenant unless a system channel explicitly allows wider.
- Replication (with 07-supervisor-replication.md): oplog entries gain `"tenant"`; sync sessions declare a tenant filter (single tenant, tenant list cap 128, or privileged all); conflict policies apply per tenant key; tenant provision, suspend, and purge replicate as control entries with human-confirm gates at apply time on peers.
### 6.11 Provisioning and deletion
- Provision: validate slug and strategy, allocate target (database, file, or pool row), run sync plus RLS policies, seed flags and quotas, warm caches, emit `tenant.provisioned`. Provision timeout 120 s; partial state rolls back with an itemized cleanup log.
- Suspend: flip status, drain tenant connections within 30 s, reject new work with 403, keep data. Unsuspend reverses with a health pre-check.
- Delete: mark `tombstoned`, revoke access, retain data for the retention window (default 30 days), then require human-confirmed purge. Purge emits an itemized destruction report and is blocked while replicas lag on that tenant.
## 7. Execution steps (in build order)
- E11-1: `TenantId`, `Tenant`, `IsolationStrategy`, in-memory catalog, `TenantContext` type shared with 04-data.md. Joint milestone: data Context carries tenant before drivers harden.
- E11-2: `TenantResolver` (all four signals, conflict rule) plus `TenantMiddleware` ordering test with 05-request-routing.md.
- E11-3: Pool scoping: `TenantScope` filter injection, `tenant_id` column convention, Postgres RLS policy generator, SET LOCAL checkout discipline.
- E11-4: Bridge pools: per-tenant Postgres databases plus pools, per-tenant SQLite files plus writer gates, catalog-driven connection factory.
- E11-5: `TenantProvisioner`: provision, sync integration, suspend and unsuspend, tombstone plus human-gated purge.
- E11-6: Quotas plus per-tenant rate buckets at admission points; usage persistence; 429 and 507 paths.
- E11-7: Config overlay plus feature flags with cache, validation, and change events.
- E11-8: `TenantMetrics` allowlist plus per-tenant series; log and trace tenant fields; replication tenant filter and control entries; living-example tenant demo.
## 8. Validation (how to verify each step)
- E11-1: context propagation test: tenant set at edge reaches ORM, log record, and task envelope unchanged; missing tenant fails closed in pool mode.
- E11-2: resolution matrix: subdomain, header, path, claim, conflict (400), unknown (404), suspended (403), dev default; order reconfiguration honored.
- E11-3: two-tenant CRUD suite on both backends: each tenant sees only its rows; direct SQL without scope returns zero rows on Postgres (RLS proof) and is rejected by the driver guard on SQLite; pooled checkout leak test (100k checkouts, GUC never bleeds).
- E11-4: bridge suite: per-tenant databases and files created, isolated pools saturate independently, cross-file transaction attempt refused, connection factory rejects request-derived names.
- E11-5: provision plus suspend plus purge drill: partial-provision rollback leaves no residue; tombstone retains data; purge without human confirmation refuses; purge with lagging replica blocks.
- E11-6: quota matrix: each quota trips at its limit with the documented status; burst and fair-share throttle behave within 20 percent; restart preserves usage within one persist window.
- E11-7: overlay validation: unknown path rejected atomically; flag change propagates to cached readers within 30 s; event observed on the bus.
- E11-8: metrics allowlist: 513th tenant records as "other" with overflow counter; per-tenant series render in `/metrics`; replication filter syncs one tenant without touching others; full suite green with the living-example tenant demo.
## 9. References
- Depends on 01-runtime.md: connection lifecycle, checkout discipline, static caps pattern.
- Depends on 02-observability.md: log schema, metric registry and label caps, trace attributes, redaction.
- Depends on 03-security.md: auth and session binding, rate limiter core, secrets for silo profiles, upload quotas.
- Depends on 04-data.md: ORM query builder, pooling, transactions, sync and healer, migration journal, KV and cache namespaces, pubsub channels. Joint hardening milestone before either file freezes.
- Depends on 05-request-routing.md: middleware ordering, Request scope, DI providers, error shapes.
- Depends on 06-realtime.md: room and channel namespacing, upgrade-time caps, broadcast fan-out.
- Depends on 07-supervisor-replication.md: task envelope tenant field, scheduler fairness, oplog shape, sync filters, multi-instance shared stores.
- Depends on 08-clients-openapi.md: test client tenant fixtures, per-tenant OpenAPI examples.
- Depends on 09-cli-ops.md: `molo tenant` commands, `/metrics` exposition, health aggregation per tenant.
- Follows 10-workflow-example.md: spec template, integration-only tests, living example coverage.
- Feeds 12-audit-compliance.md: tenant id on every auditable record, purge reports, suspension trail.
- Feeds 14-api-governance.md: per-tenant quota and versioning surface.
## 10. Open questions
1. RLS plus prepared plans under transaction pooling: which pool mode stays default for pool tenants, and does SET LOCAL survive the pooler path? Needs a joint test with 04-data.md.
2. Schema-per-tenant is excluded per AWS guidance; if a reviewer demands it, which cap (max schemas) makes it safe?
3. Should tenant slug renames be supported (pointer plus async rewrite) or forbidden (new tenant plus migration)? Leaning forbidden for v1.
4. Fair-share throttle constants (50 percent, 60 s window) are placeholders pending load measurements.
5. Cross-tenant analytics for operators: privileged read API only, or a dedicated export pipeline with its own audit? Proposal: export pipeline with audit owned alongside 12-audit-compliance.md.
## 11. Sources
1. AWS Database Blog, Choose the right PostgreSQL data access pattern for your SaaS application (silo, bridge, pool; database-per-tenant recommendation; noisy neighbours): https://aws.amazon.com/blogs/database/choose-the-right-postgresql-data-access-pattern-for-your-saas-application/ (retrieved 2026-10-23).
2. PostgreSQL 18 documentation, 5.9 Row Security Policies (ENABLE ROW LEVEL SECURITY, per-command and per-role policies, default-deny): https://www.postgresql.org/docs/current/ddl-rowsecurity.html (retrieved 2026-10-23).
3. Microsoft Learn, Multitenant SaaS Patterns, Azure SQL Database (tenancy model definitions, switching cost): https://learn.microsoft.com/en-us/azure/azure-sql/database/saas-tenancy-app-design-patterns?view=azuresql (retrieved 2026-10-23).
4. PostgreSQL 18 documentation, 5.10 Schemas (single-database connections, CREATE SCHEMA, search path): https://www.postgresql.org/docs/current/ddl-schemas.html (retrieved 2026-10-23).
5. SQLite documentation, ATTACH DATABASE (multi-file connections, per-file atomicity under WAL, attach limit): https://www.sqlite.org/lang_attach.html (retrieved 2026-10-23).
6. AWS whitepaper, SaaS Tenant Isolation Strategies (isolation as foundational SaaS concern): https://docs.aws.amazon.com/whitepapers/latest/saas-tenant-isolation-strategies/saas-tenant-isolation-strategies.html (retrieved 2026-10-23).
+159
View File
@@ -0,0 +1,159 @@
# 12 - Audit and Compliance
File: plans/12-audit-compliance.md
Title: Audit and Compliance
Scope: Immutable audit log (who/what/when/where, before/after), GDPR export and erasure cascade, retention policies with legal hold, field-level PII marking, log redaction, non-prod data masking.
## 1. Purpose and philosophy
This file owns proof: what happened, who did it, when, where, and what changed. It gives every MoloApp deployment an append-only audit log with tamper-evident chaining, a GDPR rights engine (export and erasure with cascade), retention policies with legal hold override, field-level PII marking on ORM models, centralized log redaction, and deterministic masking for non-prod data.
Philosophy:
- Accountability is a feature, not paperwork. GDPR Art. 5(2) makes the controller responsible for demonstrating compliance, so the framework generates the evidence by default.
- Append-only with teeth. Audit records are hash-chained and sealed; verification is a command, not a hope. Detection of gaps follows the signed-syslog model (sequencing plus missing-message detection).
- Redact before persistence. Sensitive values never reach a log, audit record, export, or non-prod copy. Scrubbing copies later is not a strategy.
- Erasure is a cascade with named exceptions. Art. 17 grounds drive deletion across ORM, KV, cache, audit metadata, and backups policy; Art. 17(3) exceptions (legal claims, legal obligation) plus legal holds are the only brakes, and each brake is itself audited.
- Minimize by mark. Every ORM field declares a PII class once; redaction, export, erasure, retention, and masking all read that mark. No second inventory anywhere.
## 2. Best practices (from research)
1. Audit records capture when, where, who and what for each event: timestamps plus interaction identifier (when), app identity plus entry point plus code location (where), source address plus user identity (who), event type plus severity plus action/object/result/reason (what). (Source: https://cheatsheetseries.owasp.org/cheatsheets/Logging_Cheat_Sheet.html, retrieved 2026-10-23)
2. Log security events always: auth success and failure, authorization failure, session failures, admin actions, sensitive-data access, key use and rotation, data import and export, config change, legal opt-ins such as consent. Data changes and config modifications are at minimum considered. (Source: https://cheatsheetseries.owasp.org/cheatsheets/Logging_Cheat_Sheet.html, retrieved 2026-10-23)
3. Never record directly, instead remove, mask, sanitize, hash, or encrypt: session IDs, access tokens, passwords, DB connection strings, encryption keys, bank or card data, sensitive PII (health, government identifiers, vulnerable people), data above the logging system's classification, opted-out data. Non-sensitive PII (names, phones, emails) gets special treatment; prefer de-identification (deletion, scrambling, pseudonymization). (Source: https://cheatsheetseries.owasp.org/cheatsheets/Logging_Cheat_Sheet.html, retrieved 2026-10-23)
4. GDPR principles: lawfulness/fairness/transparency, purpose limitation, data minimisation, accuracy, storage limitation (identifiable form no longer than necessary), integrity and confidentiality, plus accountability (the controller must demonstrate compliance). (Source: https://gdpr-info.eu/art-5-gdpr/, retrieved 2026-10-23)
5. Erasure without undue delay when a ground applies: data no longer necessary, consent withdrawn with no other ground, successful objection, unlawful processing, legal-obligation erasure, child consent services data. Public-data controllers take reasonable steps to inform downstream processors. Exceptions: expression, legal obligation or public task, public health, archiving/research/statistics, legal claims. (Source: https://gdpr-info.eu/art-17-gdpr/, retrieved 2026-10-23)
6. Portability: the subject receives provided data in a structured, commonly used and machine-readable format and may transmit it to another controller; direct controller-to-controller transfer applies where technically feasible; the right must not adversely affect others' rights. It is without prejudice to erasure. (Source: https://gdpr-info.eu/art-20-gdpr/, retrieved 2026-10-23)
7. Rights requests: information on action taken without undue delay and within one month of receipt, extendable by two months for complex or numerous requests with reasons given inside the first month; electronic requests get electronic answers where possible; identity may be re-confirmed on reasonable doubt; manifestly unfounded or excessive requests may be charged or refused with the burden of proof on the controller. (Source: https://gdpr-info.eu/art-12-gdpr/, retrieved 2026-10-23)
8. Tamper evidence for logs: signed syslog adds origin authentication, message integrity, replay resistance, message sequencing, and detection of missing messages on top of RFC 5424. (Source: https://www.rfc-editor.org/rfc/rfc5848.txt, retrieved 2026-10-23)
9. Triangulated decisions: (a) OWASP when/where/who/what plus Art. 5 accountability define the audit record schema in section 6.1, nothing else may define it. (b) Art. 17 grounds plus Art. 17(3) exceptions plus OWASP consent logging define the erasure cascade with legal-hold brake. (c) Art. 20 machine-readable plus Art. 12 electronic-means define the JSON export format and delivery rule. (d) OWASP remove/mask/hash plus Art. 5 minimisation define redact-before-persist and PII marking. (e) RFC 5848 sequencing plus integrity define the hash chain and gap detection.
## 3. Structure
Root: `src/molo/audit/`, headers mirror under `include/molo/audit/`. One class or concern per file. Namespace root `molo::audit`, sub-namespaces `log`, `rights`, `retention`, `pii`, `redact`, `mask`.
- `log/Record.h`: `struct Record` (schema in 6.1, fixed JSON keys, no free text PII).
- `log/Appender.h`: `class Appender` (append-only write, monotonic seq, prev-hash link).
- `log/Chain.h`: `class Chain` (hash computation, seal block, verify range, gap report).
- `log/Store.h`: `class Store` interface (append, read range, seal); `log/SqlStore.h` (dual-backend impl over 04-data.md drivers).
- `log/Query.h`: `class Query` (filter by subject, actor, object, time range, paged).
- `rights/Subject.h`: `struct SubjectRef` (subject id type, tenant id from 11-tenancy.md).
- `rights/Exporter.h`: `class Exporter` (collect marked fields, emit JSON bundle).
- `rights/Eraser.h`: `class Eraser` (plan cascade, apply, report per-store outcome).
- `rights/Request.h`: `class RightsRequest` (id, type export/erase, state machine, due date).
- `retention/Policy.h`: `struct Policy` (per-model TTL, legal basis tag, action erase or anonymize).
- `retention/Enforcer.h`: `class Enforcer` (periodic scan driver, executed via 07-supervisor-replication.md scheduler).
- `retention/Hold.h`: `class LegalHold` (hold id, scope, reason, placed-by, release rule).
- `pii/Mark.h`: `enum class PiiClass`, `struct FieldMark` (see 6.4).
- `pii/Registry.h`: `class Registry` (model to field-mark map, built from ORM descriptors).
- `redact/Redactor.h`: `class Redactor` (single entry `redact(record, context)`).
- `redact/Pattern.h`: `struct Pattern` (named matchers for tokens, keys, card data).
- `mask/Masker.h`: `class Masker` (deterministic per-class masking, seeded).
- `mask/Fixture.h`: `class FixtureScrubber` (DB dump and fixture rewrite for non-prod).
## 4. Rules (hard, numbered)
1. Audit writes are append-only. No update or delete API exists on the store; correction is a new compensating record linking the original seq.
2. Every audit record carries seq, prev-hash, timestamp, actor, subject, action, object, result, before/after digests or redacted diffs, and request/trace IDs. Missing fields fail the write loudly.
3. Before/after values pass through the Redactor before persistence. Raw PII, secrets, tokens, or passwords in an audit record are a build-breaking defect.
4. All data-subject rights flow through `RightsRequest` with identity confirmation and due-date tracking. Ad-hoc export or delete code paths are forbidden.
5. Erasure cascades to every store holding the subject: ORM rows, KV keys, cache entries and tags, sessions, uploads metadata, task payloads, audit subject index (pseudonymized, never content-deleted). Each store reports done, held, or exempted.
6. Legal hold and Art. 17(3) exemptions block erasure and retention deletion for held records only, with reason recorded. Holds never silently expand scope.
7. Retention deletion never touches held records and never runs without a dry-run report first. Enforcer applies only the policy version that was dry-run.
8. Every ORM field is marked with exactly one PII class at model declaration. Unmarked fields fail model registration at startup.
9. Non-prod environments never hold prod PII. Seed, fixture, dump-restore, and staging-sync paths run the Masker; unmasked prod copies outside prod are forbidden.
10. Redaction is centralized in `molo::audit::redact`. Sibling log, error, and export code calls it; local regex scrubbers are forbidden.
11. Audit log reads require an explicit auditor role and are themselves audited (who queried what range, when). Export bundles are signed and expire.
12. All caps in section 6 are static constants. No autotuning of retention, chain sealing, export size, or masking throughput.
## 5. Development guidelines
- Build order follows section 7: PII marks first (everything reads them), then redaction, then the audit chain, then retention and holds, then rights, then masking.
- Extremely object-oriented: one small class per file, deep namespaces, shared behavior in exactly one base. No cross-layer imports outside declared interfaces.
- Every audit emission is a one-line call at the mutation site: `AUDIT(model, action, before, after)`; the macro fills actor, subject, IDs, and chain link. Reviews reject manual record assembly.
- Structured over stringly: fixed JSON schemas for records, export bundles, erasure reports, and retention reports. Free-text reason fields are capped and redacted.
- Blocking work (chain sealing, export assembly, erasure cascade, retention scan, masking) runs off the event loop via 01-runtime.md blocking-work path or as 07-supervisor-replication.md tasks.
- Denials and holds emit structured logs plus metrics per 02-observability.md with reason codes, never the held content.
- Mobile-first and simplicity rules from plan.md apply to the auditor UI and rights self-service pages: responsive, plain language, one action per screen.
## 6. Specifications (concrete behaviors, caps, formats)
### 6.1 Audit record schema (JSON, fixed keys)
`{"seq":n,"prev":"hex","hash":"hex","ts":"RFC3339-UTC","tenant":"id","actor":"user:42|system:scheduler|api:key-id","subject":"subject:uuid|none","action":"create|update|delete|read-sensitive|export|erase|login|grant|hold.place|hold.release|retention.run|config.change","object":"model:table:pk","result":"success|fail|defer","reason":"code","request_id":"...","trace_id":"...","before":"redacted-json|null","after":"redacted-json|null","policy":"retention-policy-version|null"}`
Chain: `hash = SHA256(prev || canonical-json-without-hash)` using in-house hash per 03-security.md; genesis `prev` is 64 zeros. Seal block every 1000 records or 60 s: `{"seal_seq":n,"root":"hex-chain-tip","ts":"..."}` signed with the audit key epoch. Verify command replays hashes and reports first gap.
### 6.2 Retention and legal hold
Policy per model: `{"model":"...","ttl_days":n,"basis":"contract|consent|legal-obligation|legitimate-interest","on_expiry":"erase|anonymize","grace_days":30}`. Defaults: sessions 1 day, logs with PII 90 days, audit records 7 years (legal basis tag, jurisdiction-configurable), user content per-app config. Enforcer runs daily via 07-supervisor-replication.md scheduler, dry-run report first, then apply; report lists scanned, expired, held, deleted, anonymized counts. Hold: `{"hold_id":"...","scope":"subject:uuid|model:table:pk|query-hash","reason":"...","by":"...","ts":"...","release":"manual|date"}`; held records are skipped with counter `audit_retention_held_total`. Holds survive retention runs and erasure requests until released; release is audited.
### 6.3 Rights engine (export, erasure)
Request states: received, identity-pending, queued, running, done, refused, expired. Due date: received plus 30 days; one extension of 60 days with reason notice. Export bundle JSON: `{"subject":"...","exported_at":"...","sources":[{"store":"orm:users","rows":n}],"data":{...marked fields only...},"checksum":"sha256"}`; max bundle 256 MB, beyond that split into numbered parts; delivered electronically with signed URL expiry 7 days. Erasure cascade order: sessions, cache, KV, ORM rows (or anonymize where FK and audit law requires), uploads metadata, task payloads, audit subject index pseudonymized to `erased:<request-id>`. Report per store: done, held (hold id), exempted (Art. 17(3) limb). Refusals cite the limb and log the reason code.
### 6.4 PII marking
`enum class PiiClass { None, Identifier, Contact, CredentialRef, Financial, Health, Location, Biometric, Child, Legal }`. `FieldMark { PiiClass cls; bool exportable; bool erasure; const char* basis; }`. Defaults: Identifier and Contact are exportable and erasure-bound; CredentialRef never exported in raw form (presence boolean only); Financial, Health, Biometric, Child default to non-exportable raw, exportable only as category-present flags unless policy opts in. Registry is built at ORM model registration; unknown model or unmarked field aborts boot with named error.
### 6.5 Redaction and masking
Redactor runs on: audit before/after, log records via 02-observability.md sink hook, error bodies via 05-request-routing.md error renderer, export bundles for non-exportable classes. Patterns: session/token/key headers, `*_KEY/*_SECRET/*_TOKEN`, card-shaped digit runs, DB connection strings; replacement is `[redacted:<class>]`, stable per class for grepability. Masker per class: Identifier to `user-<n>`, Contact to `user<n>@example.invalid` and `+00-000-000<n>`, Financial to zeros preserving length, others to class token; deterministic under seed so FK joins survive masking. FixtureScrubber rewrites dumps and seeds; max dump 2 GB, streams in 1 MB chunks, verifies zero unmasked marked values by rescan.
### 6.6 Caps (static)
Audit record max 64 KB (before/after each max 16 KB, overflow truncated with flag); chain seal every 1000 records or 60 s; log store retention of sealed tips forever, record bodies per policy; query page max 1000 rows; export bundle max 256 MB and max 1M rows per request; erasure cascade max 100k objects per run then continue-as-new-task; retention scan max 1M rows per run; redactor input max 1 MB per call; masker throughput floor 50 MB/s on reference host; holds max 100k active; rights requests max 10k open per tenant.
## 7. Execution steps (in build order)
1. PII marks: `PiiClass`, `FieldMark`, `Registry` wired into 04-data.md model registration with boot-time unmarked-field failure.
2. Redactor: patterns, class replacements, single `redact()` entry, hooks into 02-observability.md sinks and 05-request-routing.md errors.
3. Audit chain: `Record`, `Appender`, `Chain`, `SqlStore` on both backends, seal blocks, `AUDIT()` macro at ORM write hooks.
4. Audit query plus verify: `Query` with auditor-role guard, verify command with gap report, metrics per 02-observability.md.
5. Retention: `Policy` config, dry-run report, `Enforcer` as scheduled task via 07-supervisor-replication.md, per-model TTLs.
6. Legal hold: `LegalHold` CRUD with audit trail, hold check inside Enforcer and Eraser, release flow.
7. Rights requests: `RightsRequest` state machine with due dates, identity gate, export bundle builder with checksums.
8. Erasure cascade: per-store deleters (ORM, KV, cache, sessions, uploads, tasks), pseudonymization of audit subject index, report format.
9. Masking: `Masker` per class plus `FixtureScrubber` for dumps, seeds, and staging sync; rescan verifier.
10. Hardening: caps audit, auditor UI routes, CLI surface via 09-cli-ops.md, docs and living-example coverage.
## 8. Validation (how to verify each step)
- Step 1: model with an unmarked field refuses to boot naming the field; registry dump lists every model with its marks; integration test through a create URL.
- Step 2: planted secrets, tokens, card-shaped strings, and marked PII in logs, errors, and audit diffs all render as `[redacted:<class>]`; no raw value in any sink under failure injection.
- Step 3: 10k writes produce an unbroken chain on both backends; tamper-one-byte fixture fails verify naming the exact seq; seal blocks present at the configured interval.
- Step 4: non-auditor query returns 403 and is audited; auditor paged query returns exact ranges; verify on a pruned-gap fixture reports the gap range.
- Step 5: dry-run report counts match a manual query; apply deletes only expired unheld rows; TTL boundary test (day 89 kept, day 91 plus grace handled).
- Step 6: held subject survives retention and erasure with reason cited; release then re-run completes; hold place and release each emit audit records.
- Step 7: export bundle validates against schema, contains only marked exportable fields, checksum matches, second generation for identical data is byte-identical except timestamps.
- Step 8: erased subject has zero rows, keys, cache entries, sessions, or task payloads on rescan; audit records keep chain validity with pseudonymized subject; exempted-limb fixture refuses with cited reason.
- Step 9: masked dump restores and passes app boot; rescan finds zero raw marked values; FK joins still resolve; determinism check (same seed gives same output).
- Step 10: full integration suite green in the same session; caps review signed; living example demonstrates audit view, export, erasure, hold, and masked staging per 10-workflow-example.md rule 1.
## 9. References
- Depends on 02-observability.md: log record format, sink hook for redaction, audit metrics and trace linkage.
- Depends on 03-security.md: hash and signing primitives, key epochs, auditor auth guards, secret handling.
- Depends on 04-data.md: ORM descriptors for PII marks, dual-backend stores, KV/cache invalidation, migration journal for audit tables.
- Depends on 05-request-routing.md: error renderer hook for redaction, auditor and self-service routes, validation for rights forms.
- Depends on 07-supervisor-replication.md: scheduler for retention runs, task queue for export/erasure cascades, durable streams for audit replication.
- Depends on 11-tenancy.md: tenant selector on every record, per-tenant retention and holds isolation.
- Feeds 09-cli-ops.md: verify, export, erase, hold, retention dry-run commands and health inputs.
- Feeds 10-workflow-example.md: compliance demo routes and integration test templates.
- Defers to 13-operability.md for cross-system audit exchange formats; defers API policy surface to 14-api-governance.md; defers SBOM and provenance attestation to 15-supply-chain.md.
## 10. Open questions
1. Audit store engine: reuse 04-data.md SQLite WAL path for the chain, or a dedicated append-only segment file shared with 07-supervisor-replication.md streams?
2. Backup erasure: crypto-shredding via per-subject keys, or documented backup-expiry window (restores re-run erasure)? Leaning to crypto-shredding for flagged classes.
3. Default audit retention is 7 years; should the default vary per deployment region template, or stay single-default with explicit override?
4. Should audit reads require quorum (two auditor roles) for bulk export, or is single auditor plus audit-of-access enough for v1?
## 11. Sources
- OWASP Logging Cheat Sheet (event attributes when/where/who/what, events to log, data to exclude, de-identification): https://cheatsheetseries.owasp.org/cheatsheets/Logging_Cheat_Sheet.html (retrieved 2026-10-23)
- GDPR Art. 5, Principles relating to processing of personal data: https://gdpr-info.eu/art-5-gdpr/ (retrieved 2026-10-23)
- GDPR Art. 12, rights modalities and one-month deadline: https://gdpr-info.eu/art-12-gdpr/ (retrieved 2026-10-23)
- GDPR Art. 17, Right to erasure: https://gdpr-info.eu/art-17-gdpr/ (retrieved 2026-10-23)
- GDPR Art. 20, Right to data portability: https://gdpr-info.eu/art-20-gdpr/ (retrieved 2026-10-23)
- RFC 5848, Signed Syslog Messages (origin authentication, integrity, sequencing, missing-message detection): https://www.rfc-editor.org/rfc/rfc5848.txt (retrieved 2026-10-23)
+175
View File
@@ -0,0 +1,175 @@
# 13 - Operability at Scale
Title: Operability at Scale
Scope: Rolling and blue-green deploys, startup/shutdown drains, distributed locks, leader election, circuit breakers, bulkheads, load shedding, client deadlines, chaos hooks, SLO and error-budget metrics, debug endpoints.
## 1. Purpose and philosophy
This file owns what keeps MoloApp alive under real production pressure: safe deploys, clean startup and shutdown, single-owner coordination across instances, fast failure under overload, propagated deadlines, deliberate fault injection, SLO accounting, and debug introspection. It does not own the primitives it builds on: probes live in 09-cli-ops.md, metric and trace primitives live in 02-observability.md, retry and timeout phases live in 08-clients-openapi.md, scheduler leadership and replication live in 07-supervisor-replication.md, connection draining mechanics live in 01-runtime.md.
Philosophy:
- Fail fast, shed early, degrade loudly. It is nearly always better to fail quickly and apply back pressure downstream as soon as possible (Envoy circuit breaking docs). Overload is handled by policy, never by unbounded queues.
- Deploys are boring by construction. Health-gated, reversible, and version-tolerant: two versions serve side by side during every rollout, and shared state never assumes a single version.
- Coordination needs a lease and a fence. Every lock and leadership claim expires on its own and carries a fencing token, so a slow holder can never corrupt state after losing ownership.
- Deadlines flow downhill. Every inbound request carries a deadline, and every outbound call inherits what remains, converted to a remaining-time budget so clock skew cannot stretch it.
- Chaos is a first-class test input. Fault hooks are compiled in, disabled by default, authenticated always, and every experiment states its steady-state hypothesis up front.
## 2. Best practices (from research)
1. Error budgets make reliability negotiable. An error budget is 1 minus the SLO of the service: a 99.9% SLO service has a 0.1% error budget, so 1,000,000 requests in four weeks allow 1,000 errors (Source: https://sre.google/sre-book/embracing-risk, retrieved 2026-10-23). SLOs are the target, the budget is the spendable allowance for deploys and experiments.
2. Rolling updates gate on readiness. Kubernetes RollingUpdate strategy exposes maxUnavailable (pods allowed down) and maxSurge (extra pods allowed above desired), both defaulting to 25%, and with maxUnavailable 0 a new pod must pass its readiness probe before an old one is terminated (Source: https://kubernetes.io/docs/concepts/workloads/controllers/deployment/, retrieved 2026-10-23; parameter table at https://kubernetes.io/docs/tasks/run-application/update-deployment-rolling/, retrieved 2026-10-23). MoloApp deploys mirror this: readiness gates traffic, startup gates protect slow boots.
3. Circuit breaking is distributed and fail-fast. Envoy enforces circuit breaking limits at the network level with fully distributed (not coordinated) breakers: cluster maximum connections, pending requests, active requests, and retries, each with overflow counters (Source: https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/circuit_breaking, retrieved 2026-10-23). Triangulates with the SRE overload chapter: gracefully handling overload is fundamental to a reliable serving system, via degraded responses and client-side throttling (Source: https://sre.google/sre-book/handling-overload/, retrieved 2026-10-23).
4. Deadlines are absolute, propagation is relative. A deadline is a point in time past which a client is unwilling to wait; because clocks differ, gRPC converts the deadline to a remaining timeout with elapsed time already deducted before propagating it downstream, and expiry surfaces as DEADLINE_EXCEEDED (Source: https://grpc.io/docs/guides/deadlines/, retrieved 2026-10-23). MoloApp copies this: absolute on the wire, remaining-budget on forward.
5. Locks and elections ride on lease-bound sessions. etcd concurrency builds Mutex and Election on Sessions: multiple sessions may contend for one election prefix but only one can be leader at a time, and session loss releases everything it held (Source: https://pkg.go.dev/go.etcd.io/etcd/client/v3/concurrency, retrieved 2026-10-23). MoloApp implements the same shape over the shared KV from 04-data.md, which answers open question O7-4 in 07-supervisor-replication.md by adding fencing tokens in v1.
6. Chaos experiments follow four steps: define steady state as measurable output, hypothesize it holds for control and experimental groups, inject real-world variables (crashes, severed links, failing disks), and try to disprove the hypothesis by comparing the groups (Source: https://principlesofchaos.org/, retrieved 2026-10-23). MoloApp chaos hooks encode exactly this loop: steady-state metric, hypothesis record, fault action, comparison verdict.
7. Debug endpoints are separate, conventional, and cheap. Go exposes pprof under /debug/pprof/ with heap, CPU profile, trace, goroutine, block, and mutex views (Source: https://pkg.go.dev/net/http/pprof, retrieved 2026-10-23). MoloApp mirrors the convention under /debug/ with its own auth, caps, and opt-in compile flag, never on the public listener by default.
## 3. Structure
Root: `src/ops/` continues in 09-cli-ops.md; this file owns `src/resilience/` plus deploy and debug surface. One class or concern per file, deep over flat.
```
src/deploy/
strategy.h molo::deploy::Strategy (rolling, blue_green)
rolling.h/.cpp molo::deploy::RollingUpdater (surge, unavailable, gates)
blue_green.h/.cpp molo::deploy::BlueGreenSwitcher (standby, cutover, rollback)
lifecycle.h/.cpp molo::deploy::Lifecycle (startup gate, drain phases, hooks)
src/coord/
lease.h/.cpp molo::coord::Lease (TTL, renewal, expiry callback)
dist_lock.h/.cpp molo::coord::DistributedLock (acquire, fencing token)
election.h/.cpp molo::coord::LeaderElection (campaign, observe, resign)
fence.h molo::coord::FencingToken (monotonic, compare)
src/resilience/
breaker.h/.cpp molo::resilience::CircuitBreaker (closed, open, half_open)
bulkhead.h/.cpp molo::resilience::Bulkhead (partition, semaphore, queue)
shedder.h/.cpp molo::resilience::LoadShedder (priority, overload policy)
deadline.h/.cpp molo::resilience::Deadline (absolute, remaining, propagate)
slo.h/.cpp molo::resilience::SloTracker (SLI windows, burn rate, budget)
src/chaos/
hook.h molo::chaos::FaultHook (interface: fault points)
injector.h/.cpp molo::chaos::Injector (latency, error, kill, partition)
experiment.h/.cpp molo::chaos::Experiment (hypothesis, steady state, verdict)
src/debug/
endpoint.h/.cpp molo::debug::DebugEndpoint (route table, auth gate)
snapshot.h/.cpp molo::debug::StateSnapshot (loops, pools, breakers, locks)
```
Namespaces: `molo::deploy`, `molo::coord`, `molo::resilience`, `molo::chaos`, `molo::debug`. No sibling namespace may implement its own breaker, lock, or deadline; they consume these.
## 4. Rules (hard, numbered)
1. Every deploy keeps the old version serving until the new version passes readiness; traffic never moves to an unreadied instance.
2. Mixed versions must interoperate: shared state formats (oplog, envelopes, sessions) stay backward compatible across one minor version, old readers ignore unknown fields.
3. Shutdown always drains: stop accepting, finish in-flight work within the deadline, then exit; dropped work lands in the dead-letter queue with a reason, never vanishes silently (mechanics in 01-runtime.md and 07-supervisor-replication.md, orchestration here).
4. Every lock acquisition and leadership claim has a TTL and returns a fencing token; writes without a current token are rejected by shared stores.
5. Only one leader per election name at a time; leadership loss is delivered as an event within one renewal interval, and the loser stops acting immediately.
6. Circuit breakers fail fast when open: no queuing behind an open breaker, no retries into it, every rejection counted and logged at debug.
7. Bulkheads partition by downstream dependency and by priority class; one saturated partition never starves another.
8. Load shedding drops lowest priority first by declared policy; shed requests return 503 with Retry-After, never hang.
9. Every request has an effective deadline; outbound calls inherit the remaining budget minus a safety margin, and expiry returns 504 (or DEADLINE_EXCEEDED equivalent on realtime paths).
10. Chaos hooks are disabled by default, require explicit enable plus auth, and every experiment records hypothesis, blast radius, and verdict.
11. Debug endpoints bind to the admin listener only, require auth, and are compiled out unless MOLO_ENABLE_DEBUG is set.
12. SLO burn-rate alerts fire on budget consumption rate, not on raw error counts; paging alerts require both fast-burn and slow-burn windows to agree.
## 5. Development guidelines
- Build coordination first (lease, lock, election over the 04-data.md shared KV), then drains, then breakers and bulkheads, then deadlines, then deploy strategies, then SLO tracking, then chaos and debug last.
- State machines everywhere: breaker (closed, open, half_open), election (candidate, leader, follower), lifecycle (booting, serving, draining, stopped). Explicit transitions, logged, with metrics per transition.
- Time comes from an injectable clock (see 08-clients-openapi.md frozen clock) so TTLs, backoffs, and burn windows are deterministic in tests.
- Fencing tokens are monotonic per resource (uint64 from the shared store); compare with greater-than, never equality, and persist the highest seen token alongside the data.
- Prefer middleware composition for resilience: breaker, bulkhead, shedder, and deadline middlewares wrap handlers in a fixed order (deadline outermost, then shedder, bulkhead, breaker innermost near the call).
- Chaos faults implement one interface with dry-run support: every fault can report what it would do without doing it, and dry-run is the default first step of every experiment.
- Debug output is snapshots, not live references: serialize state under a short lock, then render; a slow debugger must never stall the loop.
## 6. Specifications (concrete behaviors, caps, formats)
Deploy:
- Rolling: max_unavailable default 0, max_surge default 1; per-instance steps are wait_ready (cap 120 s) then terminate_old; revision history kept for last 5 deploys; automatic rollback when new-version error rate exceeds 5x baseline over 2 minutes.
- Blue-green: standby pool warms to ready, cutover flips router weight in 10% steps every 30 s, instant rollback flips back in one step; both pools share the same shared-KV and durable bus (no split brain).
- Startup gate: /startupz (09-cli-ops.md) returns 503 until lifecycle reaches serving; slow boot budget 60 s, then process exits nonzero so the orchestrator retries.
- Drain phases on SIGTERM: phase 1 stop accept plus fail /readyz (immediate); phase 2 finish in-flight requests (cap 30 s); phase 3 close realtime connections with code 1001 (cap 10 s); phase 4 flush tasks and spans (cap 10 s); total cap 60 s, then hard exit with exit code 0 and a loud log of anything dropped.
Coordination:
- Lease: TTL default 10 s, renewal every 3 s, expiry callback fires within 1 renewal interval; max 1024 live leases per process.
- DistributedLock: acquire timeout default 5 s, hold TTL 10 s with auto-renew while held; returns FencingToken uint64 strictly increasing per lock name; unlock with stale token is a no-op counted in metrics.
- LeaderElection: one name, one leader; campaign blocks until elected or cancelled; heartbeat 3 s; followers get leader-change events; resign hands over within 1 s. Scheduler leadership in 07-supervisor-replication.md is the first consumer.
- Fencing enforcement: shared KV compare-and-set on (key, token) rejects writes with token older than stored; rejection error carries winner token.
Resilience:
- CircuitBreaker per downstream: opens after 20 failures or 50% failure rate over a 10 s sliding window (min 10 calls); open duration 30 s; half_open allows 3 probe calls, closes on 3 successes, reopens on 1 failure. States exported as gauge plus transition counter.
- Bulkhead: max 32 partitions per process; each partition has max_concurrent (default 64) plus max_queue (default 128); overflow sheds with 503; partitions named per downstream host or priority class.
- LoadShedder: priority classes critical, normal, best_effort; when CPU queue depth or memory pressure crosses thresholds, shed best_effort first; shed decision under 1 ms; every shed emits metric with class and reason.
- Deadline: header `X-Deadline-Ms` (absolute Unix millis) on inbound; outbound propagation sends remaining minus 50 ms floor-margin; default request budget 30 s, max 300 s; realtime paths carry deadline in the connection context from 06-realtime.md.
SLO and error budget:
- SLI windows: 30-day rolling for budget accounting, plus 1 h and 6 h burn-rate windows for alerting; availability SLI = good_events / total_events per route template (never raw path).
- Budget: budget = 1 - SLO; default SLO 99.9% per service; burn_rate = observed_error_ratio / budget_ratio; fast-burn page at 14x over 1 h, slow-burn ticket at 6x over 6 h; both must fire for a page.
- Metrics: `molo_slo_budget_remaining_ratio`, `molo_slo_burn_rate{window}`, `molo_slo_bad_events_total{route,reason}`; cardinality capped per 02-observability.md rules.
Chaos and debug:
- Fault hooks: latency_add_ms (cap 10000), error_rate (cap 1.0), conn_kill, partition_downstream, clock_skew_ms (cap 60000, test only); each hook scoped to route template or downstream name, max 64 active hooks.
- Experiment record: {id, hypothesis, steady_state_metric, threshold, duration_cap 30 min, blast_radius, verdict}; auto-abort when steady state breaches threshold; all actions audit-logged (feeds 12-audit-compliance.md).
- Debug endpoints (admin listener, auth required): GET /debug/snapshot (loops, pools, breakers, locks, elections), GET /debug/breakers, GET /debug/elections, GET /debug/slo; response cap 1 MB; pprof-style CPU and heap views where the platform allows, same path convention /debug/pprof/.
## 7. Execution steps (in build order)
1. Coordination core: Lease, DistributedLock with fencing tokens, LeaderElection over shared KV; migrate the 07-supervisor-replication.md scheduler lease onto it.
2. Lifecycle orchestration: startup gate, four-phase drain, signal wiring with 01-runtime.md, drop accounting into dead-letter queue.
3. Breaker plus bulkhead: per-downstream breaker state machines, partitions, middleware wrappers, overflow metrics.
4. Shedder plus deadlines: priority shedder, X-Deadline-Ms parse and propagate through 08-clients-openapi.md client and 06-realtime.md contexts.
5. Deploy strategies: rolling updater with readiness gates and auto-rollback, blue-green switcher with weighted cutover, revision history.
6. SLO tracking: SLI windows, budget math, burn-rate alerts, Prometheus series for budget and burn.
7. Chaos hooks: fault interface, injector actions, experiment runner with auto-abort and audit records.
8. Debug endpoints: admin-listener routes, snapshot serializers, auth gate, compile-flag removal check.
## 8. Validation (how to verify each step)
- Step 1: two processes campaign for one election, kill the leader, follower takes over within 5 s; stale-token write rejected with winner token; lease expiry releases lock within 4 s of holder death (frozen-clock plus real-clock runs).
- Step 2: SIGTERM during 1000 in-flight requests drains with zero silent drops; /readyz flips to 503 within 100 ms; realtime peers receive close 1001; hard cap enforced at 60 s with loud log.
- Step 3: failing downstream opens breaker within window, calls fail fast under 1 ms with rejection counter; bulkhead saturation on one host leaves other hosts at full speed; half-open probes close the breaker after recovery.
- Step 4: low-priority flood sheds best_effort first while critical stays green; propagated deadline expires downstream first and returns 504 upstream with matching request IDs; margin floor never sends negative budgets.
- Step 5: rolling deploy with max_unavailable 0 shows zero failed requests across cutover; injected 10% new-version errors trigger auto-rollback within 3 minutes; blue-green cutover and instant rollback both verified through the real router.
- Step 6: recorded error rates reproduce budget math within rounding; 14x fast-burn plus 6x slow-burn fixtures page, single-window fixtures do not; series cardinality stays under caps at 10k routes.
- Step 7: experiment with latency fault shows steady-state breach, auto-abort, and verdict record; dry-run changes nothing; unauthenticated chaos call rejected; disabled-by-default build contains no reachable fault path.
- Step 8: debug routes 404 on the public listener and 200 on admin with auth; snapshot under 1 MB renders in under 100 ms; MOLO_ENABLE_DEBUG=0 build has zero debug symbols in the binary.
## 9. References (sibling files this depends on or feeds)
- Depends on 01-runtime.md: signal handling, connection drain mechanics, H2 GOAWAY, loop introspection for snapshots.
- Depends on 02-observability.md: metric, event, and span primitives; label cardinality rules; zero-cost gating for all resilience hooks.
- Depends on 04-data.md: shared KV for leases, locks, elections, and fencing compare-and-set.
- Depends on 05-request-routing.md: middleware ordering slot for deadline, shedder, bulkhead, breaker layers.
- Depends on 06-realtime.md: connection context for deadlines, close codes for drain, broadcast behavior during deploys.
- Depends on 07-supervisor-replication.md: drain deadlines, dead-letter queue, scheduler leadership migration, multi-instance topology.
- Depends on 08-clients-openapi.md: timeout phases, retry policy interplay with breakers, frozen clock, deadline propagation in the HTTP client.
- Depends on 09-cli-ops.md: /healthz, /readyz, /startupz, /metrics endpoints consumed as deploy gates; admin listener shape.
- Feeds 09-cli-ops.md: deploy and chaos CLI surface (rollout status, rollback, experiment run/abort), debug endpoint hosting.
- Feeds 10-workflow-example.md: living example must demo rolling deploy, breaker trip, deadline expiry, and one chaos experiment.
- Feeds 12-audit-compliance.md: chaos action and debug access audit records (no duplication of audit formats).
- Boundary with 03-security.md: auth for debug and chaos endpoints is owned there; this file only names the gate.
## 10. Open questions
1. Should blue-green weight steps be time-based (10% per 30 s) or metric-gated per step (advance only when error rate holds)? Proposal: metric-gated with time cap.
2. Fencing token scope: per lock name or global per store? Proposal: per lock name for v1, global optional later.
3. Default SLO: single 99.9% for the whole service, or per-route SLOs from day one? Proposal: service default plus opt-in per-route overrides.
4. Chaos in production: allow guarded production experiments in v1, or restrict to staging by config? Proposal: staging-only until the audit trail in 12-audit-compliance.md lands.
5. Debug CPU and heap profiling: in-house sampler or platform hooks only? Proposal: platform hooks where available, documented gap elsewhere.
## 11. Sources (exact URLs with retrieval dates)
- Google SRE Book, Chapter 3 Embracing Risk (error budget equals 1 minus SLO): https://sre.google/sre-book/embracing-risk (retrieved 2026-10-23).
- Google SRE Book, Chapter 21 Handling Overload (graceful overload, degraded responses, client-side throttling): https://sre.google/sre-book/handling-overload/ (retrieved 2026-10-23).
- Kubernetes Deployments (RollingUpdate strategy, readiness gating): https://kubernetes.io/docs/concepts/workloads/controllers/deployment/ (retrieved 2026-10-23).
- Kubernetes rolling update parameters (maxUnavailable, maxSurge defaults): https://kubernetes.io/docs/tasks/run-application/update-deployment-rolling/ (retrieved 2026-10-23).
- Envoy Circuit Breaking (fail fast, distributed breakers, overflow counters): https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/circuit_breaking (retrieved 2026-10-23).
- gRPC Deadlines (absolute deadline, remaining-timeout propagation, DEADLINE_EXCEEDED): https://grpc.io/docs/guides/deadlines/ (retrieved 2026-10-23).
- etcd clientv3 concurrency (Session, Mutex, Election, single leader): https://pkg.go.dev/go.etcd.io/etcd/client/v3/concurrency (retrieved 2026-10-23).
- Principles of Chaos Engineering (four-step experiment loop): https://principlesofchaos.org/ (retrieved 2026-10-23).
- Go net/http/pprof (debug endpoint convention): https://pkg.go.dev/net/http/pprof (retrieved 2026-10-23).
+162
View File
@@ -0,0 +1,162 @@
# 14 - API Governance
Title: API Governance
Scope: plan.md sections 2, 6 partial. Topics: API keys with scopes/quotas/expiry, router versioning and deprecation policy, breaking-change detection from OpenAPI diff, rate-limit tiers, developer-facing API surface rules.
## 1. Purpose and philosophy
This file owns the contract between MoloApp applications and their API consumers: who may call (keys, scopes), how much they may call (quotas, tiers), which contract version they bind to (router versioning), how that contract retires (deprecation policy), how breakage is caught before release (OpenAPI diff gate), and what a conforming endpoint looks like (surface rules).
Philosophy:
- Explicit contracts, explicit versions. Every public route belongs to exactly one major API version. No unversioned public surface.
- Additive evolution inside a version, new version for breakage. Compatible changes ship in place; incompatible changes ship a new `/v{n}` prefix and retire the old one on a schedule.
- Machine-checkable governance. Keys, scopes, tiers, versions, deprecations and surface rules are declared data validated at startup and in CI, never tribal knowledge.
- Standards wire format, in-house enforcement. Deprecation/Sunset headers, OpenAPI flags and rate-limit headers follow their specs byte for byte; the checker, linter and gate are dependency-free C++23.
- This file declares policy and detection. Mechanism lives in siblings: crypto and base throttling in 03-security.md, routers and views in 05-request-routing.md, OpenAPI emission in 08-clients-openapi.md, audit trail in 12-audit-compliance.md.
## 2. Best practices (from research)
1. Explicit versioning is mandatory and Major.Minor shaped. Microsoft requires: "All APIs compliant with the Microsoft REST API Guidelines MUST support explicit versioning", versioned "using a Major.Minor versioning scheme", with version in path or `?api-version=` query; services that cannot keep URL paths stable across versions MUST embed the version in the URL path (Source: https://github.com/Microsoft/api-guidelines/blob/master/Guidelines.md, retrieved 2026-10-23). Triangulated with 08-clients-openapi.md (`/v{n}` path prefix rule) and OpenAPI `info.version` below: MoloApp uses path prefix `/v{n}` (major only) as the single mechanism.
2. OpenAPI separates spec version from API version and flags retirement per item. The `openapi` field "MUST be the version number of the OpenAPI Specification" and "is not related to the API `info.version` string"; Operation and Parameter objects carry `deprecated: boolean` where consumers "SHOULD refrain from usage" (Source: https://spec.openapis.org/oas/v3.1.0, retrieved 2026-10-23). MoloApp therefore versions the API in `info.version` plus the `/v{n}` prefix, and marks deprecation with `deprecated: true` derived from router declarations in 08-clients-openapi.md.
3. Runtime deprecation uses two headers plus a link. RFC 8594 "defines the Sunset HTTP response header field, which indicates that a URI is likely to become unresponsive at a specified point in the future" plus "a sunset link relation type" (Source: https://www.rfc-editor.org/rfc/rfc8594, retrieved 2026-10-23). RFC 9745 adds: "The Deprecation HTTP response header field is used to signal to consumers of a resource (identified by a URI) that the resource will be or has been deprecated", with a `deprecation` link relation; "The act of deprecation does not change any behavior of the resource"; `Deprecation` value MUST be a Structured Field Date; "The timestamp given in the `Sunset` HTTP header field MUST NOT be earlier than the one given in the `Deprecation` header field" (Source: https://www.rfc-editor.org/rfc/rfc9745, retrieved 2026-10-23). Triangulated with item 2: static flag in OpenAPI, runtime headers on responses, both from one router declaration.
4. Scopes are space-delimited least-privilege grants. RFC 6749 section 3.3: "The value of the scope parameter is expressed as a list of space-delimited, case-sensitive strings", issued scope may differ from requested scope per resource-owner policy, and violations use `invalid_scope` errors (Source: https://www.rfc-editor.org/rfc/rfc6749, retrieved 2026-10-23). MoloApp API keys carry the same grammar (`resource.action`, space-delimited sets) enforced per route; under-scoped calls fail 403 with a problem-details body.
5. Rate-limit signalling is converging on two fields plus 429/Retry-After. Draft revision 11 "defines the RateLimit-Policy and RateLimit HTTP header fields for servers to advertise their quota policies" with quota parameters, available-quota parameters, and problem types including "quota-exceeded" (Source: https://datatracker.ietf.org/doc/draft-ietf-httpapi-ratelimit-headers/, retrieved 2026-10-23). Until the draft becomes an RFC, MoloApp emits both the draft fields (revision pinned in config) and the de-facto `X-RateLimit-*` trio, always with `Retry-After` on 429.
6. Breaking-change detection is a three-mode OpenAPI diff with a rule engine. oasdiff "compare[s] and detect[s] breaking changes in OpenAPI specs": `breaking` shows "only the changes that break existing API clients", `changelog` the human-readable consumer-affecting list, `diff` the full machine-readable definition diff, backed by a customizable checks list (Source: https://github.com/oasdiff/oasdiff, retrieved 2026-10-23). Triangulated with Microsoft section 12.3 (breaking-change definition) and 10-workflow-example.md release gates: MoloApp ships an in-house checker with the same three outputs and fails CI on `breaking` unless the major version bumped.
7. Surface rules stay boring: plural noun collections, verbs in methods, standard codes, problem details, pagination in query. Microsoft guidelines plus 05-request-routing.md/08-clients-openapi.md agree on this shape; this file turns that agreement into a startup linter with numbered checks rather than prose advice.
## 3. Structure
Root: `src/molo/govern/`, headers mirrored under `include/molo/govern/`. One class or concern per file pair. Namespace root `molo::govern`.
- `keys/ApiKey.h`: `struct ApiKey` (id, prefix, hash ref, owner, scopes, tier, quota overrides, issued_at, expires_at, revoked flag, last_used).
- `keys/Scope.h`: `class Scope` grammar (`resource.action`, `*` segment rules), parse, `allows(route_scope)` check.
- `keys/KeyStore.h`: `class IKeyStore` interface (lookup by prefix, record use); `keys/MemoryKeyStore.h`, `keys/DbKeyStore.h` (ORM-backed, see 04-data.md).
- `keys/KeyIssuer.h`: mint, rotate, revoke; `keys/KeyAuth.h`: middleware hook extracting `Authorization: Bearer` or `X-Api-Key`, constant-time verify via 03-security.md.
- `versions/ApiVersion.h`: `struct ApiVersion` (major, status: current/deprecated/sunset, deprecation_date, sunset_date, successor link).
- `versions/VersionedRouter.h`: binds a `Router` (05-request-routing.md) to `/v{n}`, declares status and dates, validates uniqueness.
- `versions/DeprecationMiddleware.h`: injects `Deprecation`, `Sunset`, `Link: rel="deprecation"` and `rel="successor-version"` per policy.
- `diff/SpecSnapshot.h`: stored canonical OpenAPI JSON per version (`specs/api/v{n}.json`).
- `diff/SpecDiffer.h`: path/method/schema diff engine over 08-clients-openapi.md documents.
- `diff/BreakingRules.h`: numbered check list (see 6.3), severity ERR/WARN/INFO.
- `diff/GovernGate.h`: CI verdict (pass/fail with reason codes), major-bump detector.
- `tiers/TierTable.h`: `struct Tier` (name, req/min, req/day, burst, concurrency, quota units); `tiers/TierPolicy.h`: key-to-tier resolution plus per-route overrides.
- `tiers/QuotaLedger.h`: usage counters interface over 04-data.md KV; `tiers/TierHeaders.h`: RateLimit-Policy/RateLimit plus X-RateLimit-* plus Retry-After emission.
- `surface/SurfaceRules.h`: numbered lint checks (see 6.5); `surface/RouteLinter.h`: runs checks over routers at startup and in CI.
## 4. Rules (hard, numbered)
1. Every public API route belongs to exactly one major version mounted at `/v{n}`. Unversioned public routes fail startup.
2. At most 3 live majors per app; a 4th requires retiring the oldest first. Deprecated majors keep serving until their Sunset date.
3. Breaking changes (section 6.3 ERR list) inside one major without a new `/v{n}` fail the CI gate. No override flag; ship a new major instead.
4. Every deprecated route/version emits `Deprecation` plus `Sunset` plus `Link rel="deprecation"` on every response; Sunset date MUST NOT precede Deprecation date. After Sunset, the route returns 410 Gone, never silent 404.
5. OpenAPI `deprecated: true` and runtime headers derive from the same router declaration. Hand-editing one without the other is a defect caught by the diff gate.
6. API keys authenticate the calling application only, never a user. User context comes from 03-security.md sessions or bearer user tokens; mixing the two in one credential is rejected at issue time.
7. Every key has scopes (space-delimited `resource.action`), an expiry, and a tier. Keys without expiry are rejected at issue. Expired or revoked keys fail 401; valid keys lacking scope fail 403.
8. Key secrets are shown once at mint, stored as Argon2id hashes (03-security.md), looked up by public prefix. Plaintext secrets never appear in logs, errors, metrics or audit bodies (see 12-audit-compliance.md).
9. Rate-limit tiers bind to the 03-security.md limiter; this file defines the tier table and headers, never a second counting algorithm. Every 429 carries `Retry-After` and the tier headers.
10. Surface rules in section 6.5 are startup errors for new routes and CI warnings for deprecated ones. New violations never merge.
11. All caps in section 6 are static constants with documented defaults. No autotuning of quotas, windows, versions or diff thresholds.
12. Governance data (keys metadata, tiers, versions, snapshots) is tenant-scoped where 11-tenancy.md applies; cross-tenant key reuse is impossible by construction.
## 5. Development guidelines
- Declare first: version, scopes, tier and deprecation dates live on the router/handler declaration; middleware, headers, OpenAPI flags and docs all render from that one declaration.
- Build in section 7 order; each step ends green through the real stack per 10-workflow-example.md (no unit-only key checks, real HTTP with real headers).
- Reuse sibling machinery: hashing and constant-time compare from 03-security.md, routers and error shapes from 05-request-routing.md, OpenAPI builder from 08-clients-openapi.md, KV counters from 04-data.md, metrics/log macros from 02-observability.md.
- Keep the diff deterministic: canonical JSON (sorted keys, fixed floats) before compare, so identical apps produce byte-identical snapshots.
- Errors are RFC 9457 problem details (`application/problem+json`) with `type` URIs per reason (expired_key, insufficient_scope, quota_exceeded, version_gone, version_deprecated is a warning header, not an error).
- Document every new check (diff or surface) with id, severity, example violation and fix, in the same change that adds it.
## 6. Specifications (concrete behaviors, caps, formats)
### 6.1 API keys, scopes, quotas, expiry
- Key format: `molo_<base32id>_<base64urlsecret>`; id 16 chars public prefix used for lookup and logs; secret 32 bytes from 03-security.md CSPRNG. Storage: `{id, prefix, argon2id_hash, owner, scopes[], tier, quota_override?, issued_at, expires_at, revoked_at?, last_used_at, last_used_ip?}`.
- Scope grammar: `resource.action` segments `[a-z0-9_]+`, `*` allowed as full segment only (`billing.*`, `*.read`); max 64 scopes per key, max 64 chars per scope. Route declares `required_scopes[]`; request passes when key scopes cover all required (AND) with `*` expansion. Empty route list means key-only auth, no scope check.
- Expiry: default 90 days, max 366 days, min 1 hour; rotation issues a successor with 24 h overlap (`supersedes` link), old key keeps serving 24 h then 401. Revocation is immediate and replicated per 07-supervisor-replication.md within 5 s p99.
- Quota binding: key resolves tier from TierTable; per-key `quota_override` may only lower limits, never raise above tier. Usage ledger keys `gov:quota:{key_id}:{window}` in 04-data.md KV, TTL = window length.
- Caps: 100k keys per tenant, 10k lookups/s per process (in-memory prefix index, overflow spills to DB store with metric), secret verify budget under 1 s via off-loop Argon2id path.
### 6.2 Router versioning and deprecation policy
- Mount: `VersionedRouter(version=2, status=current)` mounts all routes under `/v2/...`; `url_for` includes the version. Major-only integers 1..99. Minor evolution is additive inside the major and tracked in `info.version` (`2.3.0`) without URL change.
- Lifecycle: current -> deprecated (announce: headers on, OpenAPI flag on, changelog entry) -> sunset (date reached: 410 Gone with problem body + `Link rel="successor-version"`) -> removed (route gone, major slot freed). Minimum deprecation window 90 days; minimum announce-to-sunset 30 days even for pre-1.0 majors.
- Headers: `Deprecation: @<unix-seconds>` (Structured Field Date per RFC 9745), `Sunset: <IMF-fixdate>` (RFC 8594), `Link: <{guide}>; rel="deprecation"`, `Link: <{successor}>; rel="successor-version"`. Startup validation rejects Sunset earlier than Deprecation.
- Version negotiation: path prefix only; no header or query negotiation in v1 (explicit non-goal, avoids the matrix Microsoft documents as optional). Wrong-major requests get 404 plus `Link rel="successor-version"` to the current major, not a silent redirect.
- Snapshots: one canonical `specs/api/v{n}.json` per live major, committed in-repo, regenerated by 08-clients-openapi.md builder, diffed by 6.3 gate.
### 6.3 Breaking-change detection (OpenAPI diff)
- Modes mirror oasdiff: `molo apidiff breaking <old> <new>` (ERR only, exit 1 on any), `changelog` (ERR+WARN human list), `diff` (full JSON incl. INFO/doc-only). Same taxonomy: ERR breaks clients, WARN may break, INFO is safe.
- ERR (breaking): remove path/method; add required request param/property/header; Narrow type/format/enum (remove enum value, int32 to int, string to number, widen is WARN); raise required-ness; remove response status previously documented; change response property from optional to required; change auth scheme or add required security; reduce rate-limit tier defaults. WARN: add optional field, add enum value, add response status, widen type, deprecate flag flip, description-only edits are INFO.
- Gate: CI regenerates the live-major snapshot, runs `breaking` against the committed one. Any ERR fails unless the change also adds a new `/v{n+1}` snapshot carrying the change (major-bump path). Deprecated majors accept INFO/WARN only; any ERR fails unconditionally.
- Caps: diff input max 10 MB per document (matches 08-clients-openapi.md cap), max 5000 paths, rule run under 30 s on reference hardware, output max 1 MB (truncated with counter beyond).
### 6.4 Rate-limit tiers
- Default table: `free` 60 req/min, 10k req/day, burst 2x/10 s, concurrency 4; `pro` 600 req/min, 1M req/day, burst 2x/60 s, concurrency 32; `enterprise` 6000 req/min, 50M req/day, burst 1.5x/60 s, concurrency 256. All per key, all overridable per route downward only.
- Headers on every keyed response: `RateLimit-Policy: "tier";q=<quota>;w=<window-s>` and `RateLimit: "tier";r=<remaining>;t=<reset-s>` (draft-ietf-httpapi-ratelimit-headers rev 11 shape) plus `X-RateLimit-Limit/Remaining/Reset` for legacy clients. 429 adds `Retry-After: <s>` (min(reset, cap 300)) and `application/problem+json` body with type `quota-exceeded`.
- Counting owned by 03-security.md limiter buckets keyed `(tier, key_id, route)`; this file supplies limits and emits headers. Cross-instance counts converge via 07-supervisor-replication.md shared counters; documented skew bound 2x window edge under partition.
- Quota day is UTC midnight to midnight; minute windows are fixed 60 s; burst bucket refills linearly. Exceeding any one dimension returns 429 for that dimension (reason named in body).
### 6.5 Developer-facing API surface rules (linter)
- S1 nouns not verbs: collection paths are plural nouns (`/v1/users/{id}`), no verbs (`/getUsers`, `/users/create` fail). S2 method semantics: GET read, POST create, PUT full replace, PATCH partial, DELETE remove. S3 status codes from the fixed set 200/201/204/400/401/403/404/405/406/409/410/415/422/429/500/503 with 410 reserved for sunset routes.
- S4 errors are RFC 9457 bodies with stable `type` URIs; S5 pagination is `?page=&per_page=` (default 20, max 100) or cursor, envelope `{data, meta, links}` per 08-clients-openapi.md; S6 filtering/sorting in query only; S7 new error `code` values require a minor version note, new nested detail never breaks (Microsoft innererror pattern).
- S8 auth declared: every route declares `auth: none|key|key+scopes|session` plus scopes when applicable; undeclared auth fails startup. S9 idempotency: POST create endpoints accept `Idempotency-Key` (24 h result store per 08-clients-openapi.md). S10 docs: every route has summary + one example; missing items render `description: TBD` and fail the strict lint profile.
## 7. Execution steps (in build order)
1. Scopes + key model: Scope grammar, ApiKey struct, IKeyStore + memory backend, KeyIssuer mint/rotate/revoke with 03-security.md hashing.
2. Key auth path: KeyAuth middleware (Bearer + X-Api-Key), constant-time verify, 401/403 problem bodies, scope AND-check, per-request key context for tiers and audit.
3. Versioned routers: ApiVersion + VersionedRouter mounting `/v{n}`, uniqueness and max-3-majors validation, `url_for` with version, 410 Gone handler.
4. Deprecation runtime: DeprecationMiddleware headers (Deprecation/Sunset/Link), date validation (Sunset >= Deprecation), OpenAPI `deprecated: true` derivation via 08-clients-openapi.md builder hook.
5. Tier table + headers: TierTable defaults, key/tier resolution, QuotaLedger over 04-data.md KV, TierHeaders emission (draft + legacy + Retry-After), 429 mapping into 03-security.md limiter.
6. Spec snapshots + differ: canonical JSON writer, SpecSnapshot store per major, SpecDiffer path/method/schema engine, INFO/WARN/ERR taxonomy.
7. Breaking gate + CLI: BreakingRules full list, GovernGate verdict, `molo apidiff breaking|changelog|diff` commands (CLI surface follows 09-cli-ops.md conventions), CI wiring per 10-workflow-example.md.
8. Surface linter + docs: RouteLinter S1-S10, startup fail on new-route violations, strict CI profile, developer guide page in living example.
## 8. Validation (how to verify each step)
- Step 1: mint 1k keys, assert prefix lookup, hash-only storage (dump contains no secret), expiry/rotation windows (old serves 24 h then 401), revoke immediacy, scope parse/expand matrix incl. `*` edges and 65-scope rejection.
- Step 2: real-HTTP matrix: no key 401, expired 401, revoked 401, wrong scope 403 with `insufficient_scope`, correct 200; key context visible to audit probe; verify latency within 03-security.md budget.
- Step 3: mount v1+v2, assert prefix routing, triple-mount path merge still works under `/v{n}`, 4th major fails startup, sunset date reached returns 410 with successor link, `url_for` round-trips.
- Step 4: deprecated route returns all four headers with Sunset >= Deprecation; generated OpenAPI shows `deprecated: true` for the same routes; misconfigured dates refuse boot with named error.
- Step 5: tier matrix per key (free/pro/enterprise + override-down) enforced through real burst traffic; every response carries both header families; 429 carries Retry-After and `quota-exceeded` body; counters converge across two instances within the documented skew bound.
- Step 6: golden vector diffs (remove path, add required field, widen type, doc-only edit) classify ERR/WARN/INFO exactly; determinism check (snapshot twice, diff empty); 10 MB + 5000-path caps enforced with clear errors.
- Step 7: fixture PRs: breaking change without new major fails CI with reason codes; same change with new `/v{n+1}` snapshot passes; deprecated-major ERR always fails; CLI exit codes match 09-cli-ops.md mapping.
- Step 8: lint fixtures per S1-S10 pass/fail exactly; new-route violation blocks startup; full integration suite green same session; living example exposes versioned, keyed, tiered routes with deprecation demo page.
## 9. References (sibling files this depends on or feeds)
- Depends on 01-runtime.md: header emission path, 429/410 status plumbing, request lifecycle hooks.
- Depends on 02-observability.md: key-use metrics, version/deprecation counters, quota gauges, trace linkage.
- Depends on 03-security.md: Argon2id hashing, CSPRNG, constant-time compare, base rate-limiter buckets, session/user auth boundary.
- Depends on 04-data.md: ORM/DB key store backend, KV quota ledger, invalidation hooks.
- Depends on 05-request-routing.md: Router, Route, middleware chain, error-to-status mapping, problem-details rendering.
- Depends on 08-clients-openapi.md: OpenAPI builder input (routers + models), canonical document, `info.version`, security schemes.
- Depends on 10-workflow-example.md: CI gate placement, spec/test templates, living-example coverage rule.
- Depends on 11-tenancy.md: tenant scope for keys/tiers/versions; feeds it the per-tenant governance shapes.
- Feeds 09-cli-ops.md: `molo apidiff` command implementation target (UX owned there).
- Feeds 12-audit-compliance.md: key lifecycle events (mint/rotate/revoke/use), gate verdicts, deprecation audit records.
- Feeds 13-operability.md: tier/quota export formats shared with external gateways.
- Parallel with 07-supervisor-replication.md (key/quota replication transport) and 15-supply-chain.md (snapshot provenance signing, if adopted).
## 10. Open questions
1. Should v1 ship OAuth2 scopes beyond API-key scopes (user-delegated flows), or stay key-only with sessions covering users? Proposal: key scopes only, RFC 6749 flows deferred.
2. Draft header shape is pinned to rev 11; when the IETF publishes the RFC, do we dual-emit old and final shapes during a window? Proposal: yes, one minor version of dual emission.
3. Cross-instance quota exactness: is 2x edge skew acceptable for paid tiers, or do enterprise tiers need synchronous counting? Needs a joint decision with 07-supervisor-replication.md.
4. Should the surface linter auto-fix (rename suggestions) or only report? Proposal: report with fix hints, no auto-rename in v1.
5. Sunset 410 body: include machine-readable `successor` operation mapping (old path to new path table), or just the version link? Proposal: version link in v1, path map later.
## 11. Sources (exact URLs with retrieval dates)
- RFC 8594, The Sunset HTTP Header Field (E. Wilde, May 2019, Informational): https://www.rfc-editor.org/rfc/rfc8594 (retrieved 2026-10-23).
- RFC 9745, The Deprecation HTTP Response Header Field (S. Dalal, E. Wilde, Proposed Standard): https://www.rfc-editor.org/rfc/rfc9745 (retrieved 2026-10-23).
- OpenAPI Specification v3.1.0 (2021-02-15): https://spec.openapis.org/oas/v3.1.0 (retrieved 2026-10-23).
- IETF draft-ietf-httpapi-ratelimit-headers-11, RateLimit header fields for HTTP (May 2026, Internet-Draft): https://datatracker.ietf.org/doc/draft-ietf-httpapi-ratelimit-headers/ (retrieved 2026-10-23).
- oasdiff repository, OpenAPI Diff and Breaking Changes (breaking/changelog/diff, checker rules): https://github.com/oasdiff/oasdiff (retrieved 2026-10-23).
- Microsoft REST API Guidelines (explicit versioning, Major.Minor, breaking-change definition): https://github.com/Microsoft/api-guidelines/blob/master/Guidelines.md (retrieved 2026-10-23).
- RFC 6749, The OAuth 2.0 Authorization Framework, section 3.3 Access Token Scope (Oct 2012, Standards Track): https://www.rfc-editor.org/rfc/rfc6749 (retrieved 2026-10-23).
+150
View File
@@ -0,0 +1,150 @@
# 15 - Supply Chain and Trust
File: plans/15-supply-chain.md
Scope: plan.md sections 4 (wolfSSL exception), 9 (autonomous releases). Topics: SBOM generation, signed release artifacts, dependency policy and wolfSSL exception handling, vulnerability-scan pipeline hook, provenance and release attestation.
## 1. Purpose and philosophy
MoloApp ships almost no supply chain: stdlib plus OS syscalls plus wolfSSL as the sole third-party dependency. This file makes that claim verifiable. Every release carries a machine-readable SBOM, a signed provenance statement describing where, when and how it was built, and detached signatures over all artifacts, so a consumer can answer "what is inside this binary and who built it" without trusting the download server.
Philosophy:
- Minimal surface, maximal proof. One allowed exception (wolfSSL) is pinned, hashed and attested; everything else in-house is versioned by git commit.
- Proof over promise. SBOM, provenance and signatures are generated by the release pipeline in 10-workflow-example.md, never hand-edited.
- Standards first. SPDX and CycloneDX for SBOM, in-toto plus SLSA for provenance, Sigstore/cosign for signing, NIST SSDF for practice grouping.
- Closed by default. A new dependency, an unsigned artifact, or a failing vuln gate blocks the release. Overrides are explicit, logged and expire.
## 2. Best practices (from research)
1. SLSA provenance is verifiable information about where, when and how an artifact was produced, defined as an in-toto attestation predicate with predicateType `https://slsa.dev/provenance/v1`, where the build platform attests it produced artifacts by executing a buildDefinition (Source: https://slsa.dev/spec/v1.0/provenance, retrieved 2026-10-23; triangulated by https://slsa.dev/spec/v1.0/about, retrieved 2026-10-23).
2. The in-toto attestation framework is the envelope: a Statement binds subjects (artifact digests) to a predicateType plus predicate, and SLSA provenance is one predicate type inside it (Source: https://github.com/in-toto/attestation, retrieved 2026-10-23; triangulated by SLSA provenance spec above).
3. SPDX (Linux Foundation, ISO/IEC 5962:2021 for SPDX 2.2.1) and CycloneDX (OWASP, ECMA-424) are the two interoperable machine-readable SBOM formats satisfying the NTIA minimum elements: supplier name, component name, version, other unique identifiers, dependency relationship, SBOM author, timestamp (Source: https://spdx.dev/learn/overview/, retrieved 2026-10-23; Source: https://cyclonedx.org/specification/overview/, retrieved 2026-10-23; NTIA element list triangulated by https://github.com/spdx/ntia-conformance-checker, retrieved 2026-10-23). MoloApp emits SPDX JSON as canonical and CycloneDX JSON as secondary.
4. Sigstore cosign keyless blob signing (`cosign sign-blob` without `--key`) obtains a short-lived certificate from Fulcio via OIDC identity and records the signature in the Rekor transparency log, producing a `.sigstore.json` bundle verified against the expected signer identity (`--certificate-identity`) and OIDC issuer (Source: https://docs.sigstore.dev/cosign/signing/signing_with_blobs/, retrieved 2026-10-23; triangulated by https://docs.sigstore.dev/about/overview/, retrieved 2026-10-23).
5. NIST SP 800-218 v1.1 (SSDF, Feb 2022) defines outcome-based secure development practices in four groups: Prepare the Organization (PO), Protect the Software (PS), Produce Well-Secured Software (PW), Respond to Vulnerabilities (RV); it mandates outcomes, not tools (Source: https://csrc.nist.gov/pubs/sp/800/218/final, retrieved 2026-10-23).
6. Triangulated release rule from (1)+(4)+(5): a trustworthy release needs all three of SBOM (PW.4.1 lineage), signed provenance from the build platform (PS.3, SLSA Build L2+), and a vulnerability response hook (RV) that blocks or discloses known CVEs before ship. Missing any one fails the gate.
## 3. Structure
Directories (one class or concern per file, deep over flat):
```
tools/supply/ release-time only, never linked into the framework
SbomGenerator.hpp/.cpp molo::supply::sbom::Generator (inventory assembly)
SpdxEmitter.hpp/.cpp molo::supply::sbom::SpdxEmitter (SPDX 2.3 JSON)
CycloneDxEmitter.hpp/.cpp molo::supply::sbom::CycloneDxEmitter (CycloneDX 1.6 JSON)
SbomCheck.hpp/.cpp molo::supply::sbom::ConformanceCheck (NTIA elements)
include/molo/supply/
src/supply/
policy/DependencyPolicy.hpp molo::supply::policy::DependencyPolicy (allow-list)
policy/WolfPin.hpp/.cpp molo::supply::policy::WolfPin (version, digest, license receipt)
attest/ProvenanceBuilder.hpp molo::supply::attest::ProvenanceBuilder (SLSA v1 predicate)
attest/Attestor.hpp/.cpp molo::supply::attest::Attestor (in-toto Statement envelope)
attest/Signer.hpp/.cpp molo::supply::attest::Signer (cosign wrapper, keyless first)
attest/Verify.hpp/.cpp molo::supply::attest::Verifier (bundle + digest verify)
scan/VulnHook.hpp/.cpp molo::supply::scan::VulnHook (SBOM in, verdict out)
scan/OsdvClient.hpp/.cpp molo::supply::scan::OsvClient (OSV API query, capped)
sbom/ generated per release, committed as tag asset only
specs/supply.md normative spec mirror (owned by 10-workflow-example.md template)
```
Namespaces: `molo::supply::sbom`, `::policy`, `::attest`, `::scan`. No other namespace signs, attests or scans. Signing keys never enter `src/`; only digests and bundle paths cross into `tools/release/` from 10-workflow-example.md.
## 4. Rules (hard, numbered)
R15-1: wolfSSL is the sole third-party dependency. Any second dependency blocks the build until this spec is amended and the SBOM schema covers it.
R15-2: Every tagged release ships four artifacts minimum: binary or tarball, `sbom.spdx.json`, `sbom.cdx.json`, `provenance.intoto.jsonl` plus one `.sigstore.json` bundle per signed file. Missing file blocks the tag.
R15-3: SPDX JSON is canonical and must pass NTIA minimum-element conformance; CycloneDX JSON must describe the same component set (same name/version/digest triples).
R15-4: Provenance predicateType is exactly `https://slsa.dev/provenance/v1` inside an in-toto Statement; subject digests are SHA-256 over released bytes.
R15-5: Signing is Sigstore keyless first (OIDC identity of the release workflow); long-lived keys are forbidden unless a human-approved exception with expiry exists.
R15-6: The vuln-scan hook runs on the final SBOM before signing; a CRITICAL with a fix available blocks release, others attach as disclosed advisories.
R15-7: wolfSSL is pinned by exact version plus SHA-256 of the vendored tarball plus license receipt path; any mismatch fails the build loudly.
R15-8: Reproducibility: same git commit plus same toolchain record plus same wolfSSL tarball yields byte-identical SBOM component section (timestamps only in metadata, never in digests).
R15-9: No network fetch during normal build. The only network allowed is the release pipeline calling OSV, Fulcio and Rekor, each behind timeout, retry cap and offline fail-closed behavior.
R15-10: Verification is public and offline-capable: `molo verify` checks digests, bundle chain and provenance subject match using only release assets plus Sigstore roots.
R15-11: All caps in section 6 are static constants. No silent growth of SBOM size, scan window or signature count.
R15-12: This file never duplicates sibling scope: no TLS config (03-security.md), no git/tag mechanics (10-workflow-example.md), no CLI UX (09-cli-ops.md), no audit log schema (12-audit-compliance.md). It provides SBOM, policy verdicts, provenance and bundles those siblings consume.
## 5. Development guidelines
- Build order follows section 7: policy pin first, then SBOM, then scan hook, then provenance, then signing, then verify. Each step lands with its spec delta and template output checked in as golden files.
- Generators are pure functions over (git commit, toolchain file, wolfSSL pin, file manifest). No timestamps inside hashed content; timestamps live only in SBOM metadata and provenance `buildMetadata.finishedOn`.
- Treat the SBOM as code: diff it in review, fail CI on unexpected component delta, keep golden SBOMs for the last three releases in `sbom/golden/`.
- Wrap external CLIs (cosign) behind `Signer` with a fake for tests; never shell out from framework code, only from `tools/supply/`.
- Log every policy decision with reason code (allow, pin-mismatch, vuln-block, exception-expired) through 02-observability.md; denials are loud, never silent skips.
- License hygiene: wolfSSL commercial license receipt path is recorded in the SBOM supplier field and provenance materials; receipt missing blocks release.
## 6. Specifications (concrete behaviors, caps, formats)
Dependency policy:
- Allow-list file `supply.allow.json`: exactly one entry `{name: wolfssl, version: X.Y.Z, sha256: hex, source: vendored-tarball-url-or-path, license: commercial, receipt: path}`. Unknown entry or version drift fails `make supply-check`.
- Toolchain record `supply.toolchain.json`: compiler id plus version, linker, CMake or Make version, build flags hash. Max 100 entries, max 64 KB file.
SBOM:
- Formats: SPDX 2.3 JSON (`sbom.spdx.json`) canonical, CycloneDX 1.6 JSON (`sbom.cdx.json`) secondary. Both UTF-8, LF, sorted keys, 2-space indent.
- Components: `moloapp` (supplier MoloApp, version from VERSION, id git commit), `wolfssl` (supplier wolfSSL Inc, pinned version, externalRefs: url plus purl `pkg:generic/wolfssl@X.Y.Z`), `toolchain` (supplier recorded, version string). Each carries SHA-256 checksum, license declared plus concluded, downloadLocation or NOASSERTION with justification.
- NTIA fields mandatory on every component: supplier, name, version, unique id (SPDXID plus purl/CPE where known), relationship (DEPENDS_ON from moloapp), author (`MoloApp release pipeline`), timestamp (RFC 3339 UTC).
- Caps: max 64 components, max 256 relationships, SBOM JSON max 1 MB per format, component name max 256 chars, version max 64 chars.
Vuln-scan hook:
- Input: canonical SPDX JSON. Query OSV API `https://api.osv.dev/v1/query` per component (purl plus version), timeout 10 s per request, max 64 queries per release, 1 retry, offline yields `unknown` verdict which blocks signing until a human override with 7-day expiry.
- Verdicts: `clean`, `disclosed` (non-critical or no fix, attached as `advisories.json`), `blocked` (critical CVSS >= 9.0 with fix, or wolfSSL CVE with fix regardless of score). Blocked stops the pipeline before provenance generation.
Provenance and signing:
- Provenance: in-toto Statement v1, `predicateType: https://slsa.dev/provenance/v1`, subjects are `{name, digest: {sha256: hex}}` per released file, `buildDefinition.buildType` is `https://moloapp.dev/build/v1`, `externalParameters` holds git commit, toolchain hash, wolfSSL pin digest; `runDetails.builder.id` is the release workflow identity URI; `runDetails.metadata.invocationId` is the pipeline run id.
- Signing: `cosign sign-blob --yes --bundle <file>.sigstore.json <file>` per artifact; verify with `cosign verify-blob --bundle --certificate-identity <workflow-id> --certificate-oidc-issuer https://token.actions.githubusercontent.com <file>`. SHA-256SUMS file signed as one blob additionally.
- Layout per tag `vX.Y.Z`: `molo-X.Y.Z.tar.gz`, `SHA256SUMS`, `sbom.spdx.json`, `sbom.cdx.json`, `advisories.json`, `provenance.intoto.jsonl`, plus `.sigstore.json` per file. Max 32 signed files per release.
- `molo verify <dir>`: recompute SHA-256, check bundle chain, check provenance subjects match digests, check SBOM component digests match wolfSSL pin; exit 0 verified, 1 mismatch (first mismatch quoted), 2 usage error. No network required.
## 7. Execution steps (in build order)
E15-1: DependencyPolicy plus WolfPin: allow-list schema, pin check in `make supply-check`, golden fixtures (good pin, drifted version, bad digest).
E15-2: SbomGenerator plus SpdxEmitter: inventory assembly, canonical JSON, sorted output, NTIA conformance self-check.
E15-3: CycloneDxEmitter plus equivalence test: same triples as SPDX, golden pair diff in CI.
E15-4: VulnHook plus OsvClient: query, verdict mapping, advisories.json writer, offline fail-closed path.
E15-5: ProvenanceBuilder plus Attestor: SLSA v1 predicate, in-toto Statement envelope, subject digest binding.
E15-6: Signer plus Verifier: cosign keyless wrapper, bundle layout, offline `molo verify` command core.
E15-7: Pipeline wiring into 10-workflow-example.md release order (suite green, SBOM, scan, provenance, sign, tag) and 09-cli-ops.md `molo release` surface.
E15-8: Hardening: golden SBOMs for three releases, tamper drills (bit-flip, pin drift, expired exception), docs and living-example supply page.
## 8. Validation (how to verify each step)
V15-1: Pin fixtures: correct tarball passes, one-byte change fails with digest quoted, version bump without allow-list edit fails, missing license receipt fails.
V15-2: SPDX golden test: regenerate twice, byte-identical except timestamp; NTIA checker passes; component count is exactly 3 (moloapp, wolfssl, toolchain) on a clean tree.
V15-3: Equivalence test: extract (name, version, sha256) triples from both SBOMs, sets equal; CycloneDX validates against its JSON schema.
V15-4: Scan matrix: clean SBOM yields clean; fixture with known-fixed critical yields blocked; fixture with no-fix advisory yields disclosed plus advisories.json entry; network cut yields unknown and signing refused.
V15-5: Provenance test: subjects match `sha256sum` of release files; predicateType exact; builder id equals workflow identity; tampered artifact fails subject match.
V15-6: Sign and verify round-trip against local Sigstore stub plus one manual live run: valid bundle verifies, wrong identity fails, bit-flipped file fails, offline verify works with cached roots.
V15-7: End-to-end dry run on fixture repo: full order executes, a blocked verdict stops before signing, a green run produces all files in the layout with caps respected.
V15-8: Drill suite: expired exception blocks, oversized SBOM (>1 MB) rejected, 33rd signed file rejected, living-example supply page shows SBOM plus verify instructions on a small-phone viewport.
## 9. References (sibling files this depends on or feeds)
- Depends on 03-security.md: wolfSSL version and TLS posture, hash and RNG primitives for digests, secret redaction in SBOM and provenance.
- Depends on 09-cli-ops.md: `molo release`, `molo verify`, `molo version` UX, embedder manifest hash reuse, exit-code mapping.
- Depends on 10-workflow-example.md: release pipeline order, tag gating, VERSION and CHANGELOG linkage, spec and test templates.
- Depends on 02-observability.md: structured logs and metrics for policy verdicts and scan outcomes.
- Feeds 12-audit-compliance.md: SBOM, provenance, bundles and advisories as audit evidence; retention pointers.
- Feeds 14-api-governance.md: SBOM and provenance as governed release contracts (formats versioned, breaking changes major).
- Feeds 11-tenancy.md and 13-operability.md: per-tenant build identity inputs and SBOM exchange notes (formats defined here, transport there).
- Never duplicates: 10-workflow-example.md owns git mechanics, 09-cli-ops.md owns CLI flags, 12-audit-compliance.md owns audit retention.
## 10. Open questions
Q1: SLSA Build L3 (hardened builder, non-falsifiable provenance) in v1 or L2 first with a documented L3 path? Proposal: L2 now, L3 tracked as gap.
Q2: OSV only, or OSV plus a second feed (wolfSSL security list, CISA KEV) for the vuln hook? Proposal: OSV plus wolfSSL advisory check, KEV later.
Q3: Rekor transparency proof required at verify time, or bundle signature plus identity sufficient for v1? Proposal: bundle sufficient, checkpoint proof optional flag.
Q4: SPDX 3.0 migration timeline? Proposal: stay on SPDX 2.3 JSON until tooling converges, track 3.0 as gap.
## 11. Sources (exact URLs with retrieval dates)
- SLSA Provenance specification v1.0 (predicateType, model, purpose): https://slsa.dev/spec/v1.0/provenance (retrieved 2026-10-23)
- SLSA About page (SSDF link, supply-chain rationale): https://slsa.dev/spec/v1.0/about (retrieved 2026-10-23)
- in-toto Attestation Framework repository (Statement, predicate model): https://github.com/in-toto/attestation (retrieved 2026-10-23)
- SPDX Project overview (formats, ISO standard): https://spdx.dev/learn/overview/ (retrieved 2026-10-23)
- CycloneDX Specification Overview (object model, ECMA-424): https://cyclonedx.org/specification/overview/ (retrieved 2026-10-23)
- Sigstore cosign Signing Blobs (keyless sign-blob, bundles): https://docs.sigstore.dev/cosign/signing/signing_with_blobs/ (retrieved 2026-10-23)
- NIST SP 800-218 SSDF v1.1 project page (PO, PS, PW, RV practice groups): https://csrc.nist.gov/pubs/sp/800/218/final (retrieved 2026-10-23)
+15 -2
View File
@@ -1,6 +1,6 @@
# MoloApp Detailed Plans
Index for the ten detailed plan files. Each file is self-contained with purpose, best practices, structure, rules, guidelines, specifications, execution steps, validation, references, open questions, and sources.
Index for the fifteen detailed plan files. Each file is self-contained with purpose, best practices, structure, rules, guidelines, specifications, execution steps, validation, references, open questions, and sources.
## Index
@@ -16,10 +16,15 @@ Index for the ten detailed plan files. Each file is self-contained with purpose,
| 8 | 08-clients-openapi.md | Clients, OpenAPI, Test Client | HTTP/REST client, REST standards, OpenAPI generation, test client. |
| 9 | 09-cli-ops.md | CLI Tooling, Dev Server, Operations | CLI, dev server, embedder, AI harness, health/metrics, i18n/CSP. |
| 10 | 10-workflow-example.md | Workflow, Testing Discipline, Living Example | Specs, AGENTS.md, autonomous git, integration testing, living example. |
| 11 | 11-tenancy.md | Multi-Tenancy | First-class tenants: isolation strategies, quotas, flags, per-tenant metrics. |
| 12 | 12-audit-compliance.md | Audit and Compliance | Immutable audit log, GDPR export/erasure, retention, PII marking, masking. |
| 13 | 13-operability.md | Operability at Scale | Safe deploys, drains, locks/election, breakers, deadlines, SLO, chaos, debug. |
| 14 | 14-api-governance.md | API Governance | API keys, versioning/deprecation, OpenAPI diff gate, rate tiers, surface rules. |
| 15 | 15-supply-chain.md | Supply Chain and Trust | SBOM, signed provenance, dependency policy, vuln-scan hook, release attestation. |
## How files reference each other
- References always use exact sibling filenames (`01-runtime.md` through `10-workflow-example.md`).
- References always use exact sibling filenames (`01-runtime.md` through `15-supply-chain.md`).
- Each file has a References section naming Depends on (interfaces it consumes) and Feeds (interfaces it provides).
- Dependency direction (consumes, upstream first):
- `01-runtime.md` depends on `02-observability.md` (hooks) and `03-security.md` (TLS handle); feeds `05-request-routing.md`, `06-realtime.md`, `08-clients-openapi.md`, `09-cli-ops.md`.
@@ -32,6 +37,11 @@ Index for the ten detailed plan files. Each file is self-contained with purpose,
- `08-clients-openapi.md` depends on `01-runtime.md`, `02-observability.md`, `03-security.md`, `04-data.md`, `05-request-routing.md`; defers realtime clients to `06-realtime.md`; feeds `09-cli-ops.md`, `10-workflow-example.md`.
- `09-cli-ops.md` depends on `01-runtime.md` through `08-clients-openapi.md`; feeds `10-workflow-example.md`.
- `10-workflow-example.md` depends on `02-observability.md`, `08-clients-openapi.md`, `09-cli-ops.md`; feeds `01-runtime.md` through `09-cli-ops.md` (spec template, test discipline, release gates).
- `11-tenancy.md` depends on `01-runtime.md` through `09-cli-ops.md` (joint hardening milestone with `04-data.md` before either file freezes); follows `10-workflow-example.md`; feeds `12-audit-compliance.md`, `14-api-governance.md`.
- `12-audit-compliance.md` depends on `02-observability.md`, `03-security.md`, `04-data.md`, `05-request-routing.md`, `07-supervisor-replication.md`, `11-tenancy.md`; feeds `09-cli-ops.md`, `10-workflow-example.md`; defers exchange formats to `13-operability.md`, API policy to `14-api-governance.md`, attestation to `15-supply-chain.md`.
- `13-operability.md` depends on `01-runtime.md`, `02-observability.md`, `04-data.md`, `05-request-routing.md`, `06-realtime.md`, `07-supervisor-replication.md`, `08-clients-openapi.md`, `09-cli-ops.md`; feeds `09-cli-ops.md`, `10-workflow-example.md`, `12-audit-compliance.md`.
- `14-api-governance.md` depends on `01-runtime.md`, `02-observability.md`, `03-security.md`, `04-data.md`, `05-request-routing.md`, `08-clients-openapi.md`, `10-workflow-example.md`, `11-tenancy.md`; feeds `09-cli-ops.md`, `12-audit-compliance.md`, `13-operability.md`; parallel with `07-supervisor-replication.md`, `15-supply-chain.md`.
- `15-supply-chain.md` depends on `02-observability.md`, `03-security.md`, `09-cli-ops.md`, `10-workflow-example.md`; feeds `11-tenancy.md`, `12-audit-compliance.md`, `13-operability.md`, `14-api-governance.md`.
## Overall execution order
@@ -44,5 +54,8 @@ Build order follows plan.md section 10, with the file sequence matching dependen
5. `05-request-routing.md` steps E1-E12 plus `08-clients-openapi.md` steps 1-8 plus `09-cli-ops.md` steps 1-10 (plan step 5: app layer, clients, OpenAPI, CLI/ops).
6. `07-supervisor-replication.md` steps E7-5 through E7-8 (plan step 6: durable streams, replication, multi-instance).
7. `10-workflow-example.md` steps 1-8 throughout and finally (plan step 7: specs, AGENTS.md, pipeline, living example, autonomous end-to-end run).
8. `11-tenancy.md` steps E11-1 through E11-4 jointly with `04-data.md` (tenant context in the data Context before the data layer hardens), then E11-5 through E11-8 with the app layer (plan step 8: multi-tenancy).
9. `12-audit-compliance.md` steps 1-10 plus `13-operability.md` steps 1-8 (plan step 9: audit/compliance plus operability at scale).
10. `14-api-governance.md` steps 1-8 plus `15-supply-chain.md` steps E15-1 through E15-8 (plan step 10: API governance plus supply chain and trust).
Rule: no file is done until its validation section passes through the real stack and `10-workflow-example.md` rule 1 holds (spec updated, docs updated, living example demonstrates it, full suite green, same session).
+12
View File
@@ -0,0 +1,12 @@
# Standalone entry for the request/routing part. Root Makefile includes
# app.mk instead; this wrapper only fixes ROOT for isolated builds.
ROOT := $(abspath ../..)
include app.mk
.PHONY: all test clean
all: app-build
test: app-test
clean: app-clean
+96
View File
@@ -0,0 +1,96 @@
# Spec: request/routing part (plan 05)
Implementation of `plans/05-request-routing.md`, execution steps E1 through
E12, rules R1 through R12. All code lives under `src/app/` in namespaces
`molo::app::*` (namespaces mirror directories). Tests live under
`tests/src/app/` mirroring URL paths. Build outputs go under `build/` only.
C++23, standard library plus OS syscalls only. No TLS code in this part, so
no wolfSSL use and no stub needed here.
## Module map
| Directory | Contents |
|---|---|
| `async/` | `Task<T>`: minimal eager coroutine task (handler return type) |
| `seams/` | Sibling-owned seams: request IDs, session store (in-memory default) |
| `http_msg/` | Method, Headers, Query, Cookies, Request, Response hierarchy, HTML/XML escape |
| `routing/` | Path compiler, Route, Router, match, url_for |
| `app/` | Application, Mount, PluginRegistry, PluginContext |
| `validate/` | Value, JSON codec, Field, Model, ValidationError |
| `forms/` | Form binding: JSON, urlencoded, multipart |
| `errors/` | HttpError hierarchy, ErrorHandler with JSON/HTML renderers |
| `negotiate/` | Accept parser, Negotiator, variant rendering |
| `views/` | View base, handler adapters, Flash helpers |
| `middleware/` | Middleware base, Next guard, Chain, built-ins |
| `di/` | Container with app and request scopes, cycle detection |
| `templates/` | Lexer, Parser, AST, Renderer, Environment, Loaders, Cache, Filters, Tests, TemplateResponse |
Caps: `caps.h` holds every static ceiling (R11). No autotuning anywhere.
## Key behaviors (plan section 6)
- Matching order: static segments first, converters in registration order,
path catch-alls last. Precedence: full match, 405 with `Allow`, 422 on
converter failure with `loc: ["path", name]`, else 404.
- Trailing slash is strict; `slash_insensitive` registers the declared form
plus a companion 308 redirect route (query string preserved).
- Mounts merge paths (`/app1/app1/app1` for triple nesting) and prefix
route names with the mount alias (`app1:app1:deep`) so R10 uniqueness
holds after merge. Mounted apps keep their own DI container and run
their own middleware chain inside the parent chain.
- One 422 aggregates failures across query, headers, cookies and body
(R3). Shape: `{"detail":[{"loc":[...],"msg":"...","type":"..."}]}`
(lowercase `detail`).
- 406 shape: `{"Detail":{"available":[...]}}` (capital `D`, per plan).
- Other errors: `{"error":{"code":...,"message":...,"request_id":"..."}}`,
plus a responsive HTML page when the client prefers HTML.
- `?format=` override applies only when the route sets
`allow_format_override` (default off, Q2).
- Redirects are 307 temporary / 308 permanent (method-preserving).
- Flash messages ride the session store and render exactly once.
- Middleware categories are enforced at registration; `Next` twice is a
loud error. ExceptionMapping is outermost by construction;
Negotiation wraps the terminal dispatch so it stays innermost.
- DI has app and request scopes; request scope is created per `handle()`
call and cleared before returning. Declared dependency cycles fail
startup with the cycle quoted; resolution carries a dynamic guard too.
- Templates: `{{ }}`, `{% %}`, `{# #}` with extends/blocks, include,
if/elif/else, for/else with `loop`, set, macros with defaults and
kwargs, filters, tests, autoescape blocks. Autoescape is on for
`.html`/`.htm`/`.xml` with no global disable (R5). Undefined policy
defaults to Strict and Chain renders empty plus a stats counter (Q3).
Documented Jinja gaps: no ternary, no `**`, no string `%` formatting,
no `super()`, no block-level set, macro defaults are literal-only,
case conversion is ASCII-only, Accept range params are ignored.
## Sibling seams (R12)
Consumed through seams with standalone defaults, owned elsewhere:
- 01-runtime: byte caps, transport, production task executor. Local
`async::Task` is the eager stand-in with the same `co_await` shape.
- 02-observability: correlation IDs (`seams::request_id`), log sink hook
on `ErrorHandler`, per-route metrics (not wired here).
- 03-security: session store (`Application::set_session_store`), upload
quotas and scanning, auth guards consumed via DI and middleware.
- 04-data: ORM/KV/cache handles provided through DI by the host app.
Provided to siblings: `Request`/`Response` shells, router mounting,
middleware and DI participation points, validation models for OpenAPI,
template loaders (embedded assets plug into `EmbeddedLoader`), request
scope teardown at end of `handle()` for background handoff.
## Static assertions and diagnostics
- R4 is enforced by explicit constructors plus `static_assert` in
`tests/src/app/00_compile_all_test.cpp`.
- Route names unique after merge (quoted paths), unknown converters name
the route, DI cycles quote the cycle, middleware reorder names layers,
plugin capability denial names plugin and capability.
## ID counters note (R8)
`generate_request_id` and `generate_session_id` use process-wide atomic
counters. This is ID uniqueness, not service state: no service singleton
or mutable file-static state is reachable from handlers. All services
flow through `Application` and request extensions.
+29
View File
@@ -0,0 +1,29 @@
# Per-part makefile for the request/routing part (plan 05). Includable by
# the root Makefile: set ROOT to the repo root, then `include src/app/app.mk`.
# Provides: app-build, app-test, app-clean. All outputs go under build/.
ROOT ?= .
APP_CXX ?= g++
APP_CXXFLAGS ?= -std=c++23 -Wall -Wextra -Isrc
APP_BUILD ?= $(ROOT)/build/app
APP_TEST_SRCS := $(shell find $(ROOT)/tests/src/app -name '*_test.cpp' | sort)
APP_HEADERS := $(shell find $(ROOT)/src/app -name '*.h' | sort)
APP_TEST_BINS := $(patsubst $(ROOT)/tests/src/app/%.cpp,$(APP_BUILD)/%,$(APP_TEST_SRCS))
$(APP_BUILD)/%: $(ROOT)/tests/src/app/%.cpp $(APP_HEADERS)
@mkdir -p $(dir $@)
$(APP_CXX) $(APP_CXXFLAGS) -I$(ROOT)/src -I$(ROOT)/tests/src/app $< -o $@
.PHONY: app-build app-test app-clean
app-build: $(APP_TEST_BINS)
app-test: $(APP_TEST_BINS)
@pass=0; fail=0; \
for t in $(APP_TEST_BINS); do \
if (cd $(ROOT) && "$$t"); then pass=$$((pass+1)); else fail=$$((fail+1)); fi; \
done; \
echo "app tests: $$pass passed, $$fail failed"; \
test $$fail -eq 0
app-clean:
rm -rf $(APP_BUILD) $(ROOT)/build/tmp_templates
+528
View File
@@ -0,0 +1,528 @@
#pragma once
// Spec: molo::app::app::Application. Composition root (plan 05, E3): owns
// the router, middleware chain, DI container, template environment, error
// handler, session store seam and plugin registry. include_router merges a
// router under a prefix; mount nests a sub-application with automatic path
// merge (triple nesting yields /app1/app1/app1). startup() validates names
// (unique after merge; mounted names gain the mount alias prefix),
// converters (fail fast at add), DI cycles and caps, then runs lifespan
// hooks and plugin hooks. handle() matches the route before the chain runs
// so all middleware sees route info, forks a request DI scope, runs parent
// chain outer plus mount chains inner, validates bindings, and invokes the
// handler. 404/405/422 precedence follows Router::match.
#include <ctime>
#include <functional>
#include <map>
#include <memory>
#include <set>
#include <stdexcept>
#include <string>
#include <utility>
#include <vector>
#include "../../governance/problem.h"
#include "../../governance/versions/ApiVersion.h"
#include "../async/task.h"
#include "../caps.h"
#include "../di/container.h"
#include "../errors/handler.h"
#include "../errors/http_error.h"
#include "../forms/form.h"
#include "../http_msg/request.h"
#include "../http_msg/response.h"
#include "../middleware/builtins.h"
#include "../middleware/chain.h"
#include "../routing/router.h"
#include "../seams/request_id.h"
#include "../seams/session.h"
#include "../templates/environment.h"
#include "../validate/errors.h"
#include "../validate/model.h"
#include "../validate/value.h"
#include "../views/flash.h"
#include "plugin.h"
namespace molo::app::app {
class StartupError : public std::runtime_error {
public:
explicit StartupError(const std::string& msg) : std::runtime_error(msg) {}
};
class Application;
struct Mount {
std::string prefix;
std::string name_prefix;
std::shared_ptr<Application> sub;
};
struct Resolved {
Application* owner = nullptr;
const routing::Route* route = nullptr;
std::map<std::string, std::string> params;
std::vector<std::string> allow;
std::vector<validate::FieldFailure> path_errors;
std::vector<const Mount*> levels;
};
class Application {
public:
Application()
: error_handler_(std::make_shared<errors::ErrorHandler>()),
sessions_(seams::default_session_store()) {
// ExceptionMapping is outermost by construction. Negotiation runs around
// the terminal dispatch (see run_mount_levels), not in the chain, so it
// stays innermost no matter when user layers register.
chain_.use(std::make_shared<middleware::ExceptionMappingMiddleware>(error_handler_));
error_handler_->set_render_hook([this](int status, const std::string& code) {
last_error_code_ = code;
plugins_.fire_error_render(this, status, code);
});
}
routing::Router& router() { return router_; }
middleware::Chain& chain() { return chain_; }
di::Container& di() { return di_; }
templates::Environment& templates_env() { return templates_; }
errors::ErrorHandler& error_handler() { return *error_handler_; }
PluginRegistry& plugins() { return plugins_; }
std::shared_ptr<seams::SessionStore> sessions() { return sessions_; }
void set_session_store(std::shared_ptr<seams::SessionStore> store) {
sessions_ = std::move(store);
}
const std::string& last_error_code() const { return last_error_code_; }
void include_router(const std::string& prefix, const routing::Router& router,
const std::vector<std::string>& tags = {}) {
if (started_) throw StartupError("cannot include_router after startup");
router_.include_router(prefix, router, tags);
}
void mount(std::string prefix, std::shared_ptr<Application> sub, std::string alias = "") {
if (started_) throw StartupError("cannot mount after startup");
if (prefix.empty() || prefix[0] != '/') {
throw StartupError("mount prefix must start with /");
}
while (prefix.size() > 1 && prefix.back() == '/') prefix.pop_back();
if (sub->depth() + 1 > caps::kMaxSubAppNestingDepth) {
throw StartupError("sub-app nesting exceeds depth cap at '" + prefix + "'");
}
Mount m;
m.prefix = prefix;
if (!alias.empty()) {
m.name_prefix = alias;
} else if (prefix == "/") {
m.name_prefix = "root";
} else {
m.name_prefix = prefix.substr(1);
for (char& c : m.name_prefix) {
if (c == '/') c = '_';
}
}
m.sub = std::move(sub);
mounts_.push_back(std::move(m));
}
void on_startup(std::function<void(Application&)> hook) {
startup_hooks_.push_back(std::move(hook));
}
void on_shutdown(std::function<void(Application&)> hook) {
shutdown_hooks_.push_back(std::move(hook));
}
void startup() {
if (started_) return;
for (const Mount& m : mounts_) m.sub->startup();
if (total_routes() > caps::kMaxRoutesPerApp) {
throw StartupError("too many routes in application");
}
std::vector<std::pair<std::string, std::string>> names;
collect_names("", names);
std::map<std::string, std::vector<std::string>> by_name;
for (const auto& kv : names) by_name[kv.first].push_back(kv.second);
for (const auto& kv : by_name) {
if (kv.second.size() > 1) {
std::string msg = "duplicate route name '" + kv.first + "' at paths:";
for (const auto& p : kv.second) msg += " '" + p + "'";
throw StartupError(msg);
}
}
di_.validate_no_cycles();
try {
router_.validate_governance();
} catch (const std::runtime_error& e) {
throw StartupError(e.what());
}
gov_sunsets_ = CollectGovSunsets(router_);
for (const routing::Route& route : router_.routes()) {
if (!route.is_slash_redirect() && !route.options().name.empty()) {
plugins_.fire_route_added(this, route);
}
}
for (auto& hook : startup_hooks_) hook(*this);
plugins_.fire_app_started(this);
router_.freeze();
started_ = true;
}
void shutdown() {
if (!started_) return;
for (auto& hook : shutdown_hooks_) hook(*this);
for (const Mount& m : mounts_) m.sub->shutdown();
started_ = false;
}
bool started() const { return started_; }
async::Task<http_msg::Response> handle(http_msg::Request& req) {
if (!started_) startup();
// Governance: a sunset-version match answers 410 instead of 404.
if (IsSunsetVersion(req.path())) {
const auto problem = ::molo::govern::Problem::VersionGone();
http_msg::Response res(410);
res.set_content_type(std::string(::molo::govern::Problem::kContentType));
res.set_body(problem.to_json_string());
co_return res;
}
if (req.request_id().empty()) {
std::string rid = req.headers().get(seams::kRequestIdHeader);
req.set_request_id(rid.empty() ? seams::generate_request_id() : rid);
}
// Resolve runs before the chain so every middleware sees route info.
// Resolve-time failures (414 on overlong paths) render here so they
// still get the exact error shape, request ID echo and plugin hooks.
Resolved rr;
try {
rr = resolve_with_method(req.method(), req.path());
} catch (const errors::HttpError& e) {
req.set_app(this);
http_msg::Response early = error_handler_->render(e, req, req.request_id());
early.headers().set(seams::kRequestIdHeader, req.request_id());
co_return early;
} catch (const std::exception& e) {
req.set_app(this);
http_msg::Response early = error_handler_->render_unknown(req, req.request_id(), e.what());
early.headers().set(seams::kRequestIdHeader, req.request_id());
co_return early;
}
if (rr.route != nullptr) {
req.set_route(rr.route);
for (const auto& kv : rr.params) req.set_path_param(kv.first, kv.second);
req.set_app(rr.owner);
} else {
req.set_app(this);
}
// Request DI scope: lives for this call, cleared before returning so
// the scope ends at response completion (R8). Background handoff must
// copy values out; the scope pointer is not valid after handle().
auto scope = std::make_shared<di::RequestScope>(
rr.owner != nullptr ? &rr.owner->di_ : &di_);
req.set_ext("di", scope);
std::function<async::Task<http_msg::Response>(http_msg::Request&)> terminal =
[this, rr](http_msg::Request& r) -> async::Task<http_msg::Response> {
co_return co_await run_mount_levels(r, rr, 0);
};
http_msg::Response res = co_await chain_.run(req, terminal);
req.clear_ext("di");
co_return res;
}
std::string url_for(const std::string& name,
const std::map<std::string, std::string>& params = {},
const std::string& query = "") const {
if (router_.has_route_name(name)) return router_.url_for(name, params, query);
for (const Mount& m : mounts_) {
std::string head = m.name_prefix + ":";
if (name.size() > head.size() && name.substr(0, head.size()) == head) {
std::string rest = name.substr(head.size());
std::string sub_url = m.sub->url_for(rest, params, query);
if (m.prefix == "/") return sub_url;
return m.prefix + sub_url;
}
}
throw errors::NotFound("url_for: unknown route '" + name + "'");
}
std::size_t depth() const {
std::size_t deep = 0;
for (const Mount& m : mounts_) {
std::size_t d = m.sub->depth();
if (d > deep) deep = d;
}
return 1 + deep;
}
std::size_t total_routes() const {
std::size_t n = router_.size();
for (const Mount& m : mounts_) n += m.sub->total_routes();
return n;
}
void collect_names(const std::string& prefix,
std::vector<std::pair<std::string, std::string>>& out) const {
for (const routing::Route& route : router_.routes()) {
if (route.is_slash_redirect() || route.options().name.empty()) continue;
out.emplace_back(prefix + route.options().name, route.pattern());
}
for (const Mount& m : mounts_) {
std::vector<std::pair<std::string, std::string>> sub;
m.sub->collect_names(m.name_prefix + ":", sub);
for (const auto& kv : sub) out.emplace_back(prefix + kv.first, m.prefix + kv.second);
}
}
static di::RequestScope* di_scope(http_msg::Request& req) {
auto* holder = req.get_ext<std::shared_ptr<di::RequestScope>>("di");
if (holder == nullptr || holder->get() == nullptr) {
throw errors::InternalError("no DI scope bound to request");
}
return holder->get();
}
// Method-aware resolve used by handle(). Public for tests.
Resolved resolve_with_method(http_msg::Method method, const std::string& path) const {
Resolved out;
routing::MatchResult own = router_.match(method, path);
if (own.route != nullptr) {
out.owner = const_cast<Application*>(this);
out.route = own.route;
out.params = std::move(own.params);
return out;
}
bool have_mount_405 = false;
bool have_mount_422 = false;
Resolved mount_best;
for (const Mount& m : mounts_) {
bool hit = (path == m.prefix) || (m.prefix == "/" && !path.empty()) ||
(m.prefix != "/" && path.size() > m.prefix.size() &&
path.substr(0, m.prefix.size()) == m.prefix && path[m.prefix.size()] == '/');
if (!hit) continue;
std::string sub_path =
(m.prefix == "/") ? path : path.substr(m.prefix.size());
if (sub_path.empty()) sub_path = "/";
Resolved sub = m.sub->resolve_with_method(method, sub_path);
if (sub.route != nullptr) {
sub.levels.insert(sub.levels.begin(), &m);
return sub;
}
if (!have_mount_405 && !sub.allow.empty()) {
mount_best = sub;
have_mount_405 = true;
} else if (!have_mount_405 && !have_mount_422 && !sub.path_errors.empty()) {
mount_best = sub;
have_mount_422 = true;
}
}
if (!own.allow.empty()) {
out.allow = std::move(own.allow);
return out;
}
if (!own.path_errors.empty()) {
out.path_errors = std::move(own.path_errors);
return out;
}
return mount_best;
}
private:
// Governance: earliest sunset per /v{n} major, collected at startup so
// handle() answers sunset versions in O(1).
static std::map<int, long> CollectGovSunsets(const routing::Router& router) {
std::map<int, long> out;
for (const routing::Route& r : router.routes()) {
if (r.is_slash_redirect()) continue;
const routing::RouteOptions& o = r.options();
if (o.gov_sunset_httpdate.empty()) continue;
const int major =
::molo::govern::versions::ApiVersion::ParseMajor(r.pattern());
if (major == 0) continue;
const long sunset =
routing::detail::ParseImfFixdate(o.gov_sunset_httpdate);
if (sunset < 0) continue;
auto it = out.find(major);
if (it == out.end() || sunset < it->second) out[major] = sunset;
}
return out;
}
bool IsSunsetVersion(const std::string& path) const {
if (gov_sunsets_.empty()) return false;
const int major = ::molo::govern::versions::ApiVersion::ParseMajor(path);
if (major == 0) return false;
auto it = gov_sunsets_.find(major);
if (it == gov_sunsets_.end()) return false;
return std::time(nullptr) >= it->second;
}
// Two-step resolve keeps handle() readable; this section holds dispatch.
async::Task<http_msg::Response> run_mount_levels(http_msg::Request& req, Resolved rr,
std::size_t level) const {
if (level >= rr.levels.size()) {
middleware::NegotiationMiddleware negotiation;
middleware::Next guard(
[this, rr](http_msg::Request& r) -> async::Task<http_msg::Response> {
co_return co_await dispatch_final(r, rr);
});
co_return co_await negotiation.handle(req, guard);
}
const Mount* m = rr.levels[level];
std::function<async::Task<http_msg::Response>(http_msg::Request&)> inner =
[this, rr, level](http_msg::Request& r) -> async::Task<http_msg::Response> {
co_return co_await run_mount_levels(r, rr, level + 1);
};
co_return co_await m->sub->chain_.run(req, inner);
}
async::Task<http_msg::Response> dispatch_final(http_msg::Request& req,
const Resolved& rr) const {
if (rr.route == nullptr) {
if (!rr.allow.empty()) throw errors::MethodNotAllowed(rr.allow);
if (!rr.path_errors.empty()) {
throw errors::ValidationFailed(validate::ValidationError(rr.path_errors));
}
throw errors::NotFound("no route for " + req.path());
}
const routing::Route& route = *rr.route;
const routing::RouteOptions& opts = route.options();
validate::Object path_obj;
for (const auto& kv : rr.params) path_obj[kv.first] = validate::Value(kv.second);
req.set_validated("path", std::move(path_obj));
// R3: one 422 aggregates failures across every bound source.
std::vector<validate::FieldFailure> all_failures;
auto run_model = [&](const std::shared_ptr<validate::Model>& model,
const validate::Object& input, const std::string& source,
const std::string& slot) {
try {
req.set_validated(slot, model->validate(input, source));
} catch (const validate::ValidationError& e) {
for (const auto& item : e.failures()) all_failures.push_back(item);
}
};
if (opts.query_model) run_model(opts.query_model, query_object(req), "query", "query");
if (opts.header_model) {
validate::Object input;
for (const auto& kv : req.headers().items()) {
if (!input.count(kv.first)) input[kv.first] = validate::Value(kv.second);
}
run_model(opts.header_model, input, "header", "headers");
}
if (opts.cookie_model) {
validate::Object input;
for (const auto& kv : req.cookies().items()) input[kv.first] = validate::Value(kv.second);
run_model(opts.cookie_model, input, "cookie", "cookies");
}
if (opts.body_model) {
validate::Object fields;
if (req.body().empty() && req.content_type().empty()) {
fields = validate::Object{};
} else {
if (opts.max_body == 0 && !req.body().empty()) {
throw errors::PayloadTooLarge("route rejects bodies");
}
forms::FormData data = forms::Form::parse_body(req, opts.max_body);
fields = std::move(data.fields);
req.set_ext("form_files", data.files);
}
run_model(opts.body_model, fields, "body", "body");
}
if (!all_failures.empty()) {
throw errors::ValidationFailed(validate::ValidationError(std::move(all_failures)));
}
co_return co_await route.handler()(req);
}
static validate::Object query_object(const http_msg::Request& req) {
validate::Object out;
std::map<std::string, std::vector<std::string>> grouped;
for (const auto& kv : req.query().items()) grouped[kv.first].push_back(kv.second);
for (const auto& kv : grouped) {
if (kv.second.size() == 1) {
out[kv.first] = validate::Value(kv.second[0]);
} else {
validate::Array arr;
for (const auto& v : kv.second) arr.emplace_back(v);
out[kv.first] = validate::Value(std::move(arr));
}
}
return out;
}
routing::Router router_;
middleware::Chain chain_;
di::Container di_;
templates::Environment templates_;
std::shared_ptr<errors::ErrorHandler> error_handler_;
std::shared_ptr<seams::SessionStore> sessions_;
PluginRegistry plugins_;
std::vector<Mount> mounts_;
std::vector<std::function<void(Application&)>> startup_hooks_;
std::vector<std::function<void(Application&)>> shutdown_hooks_;
std::string last_error_code_;
bool started_ = false;
std::map<int, long> gov_sunsets_;
};
// PluginContext definitions (need the complete Application type).
inline PluginContext::PluginContext(Application* app, const std::set<std::string>& capabilities,
std::string plugin_name)
: app_(app), capabilities_(capabilities), plugin_name_(std::move(plugin_name)) {}
inline bool PluginContext::has(const std::string& capability) const {
return capabilities_.count(capability) > 0;
}
inline void PluginContext::require(const std::string& capability) const {
if (!has(capability)) {
throw PluginAccessError("plugin '" + plugin_name_ + "' lacks capability '" + capability +
"'");
}
}
inline std::size_t PluginContext::route_count() const {
require("routes");
return app_->total_routes();
}
inline bool PluginContext::di_has(const std::string& provider) const {
require("di");
return app_->di().has(provider);
}
inline std::string PluginContext::last_error_code() const {
require("errors");
return app_->last_error_code();
}
} // namespace molo::app::app
namespace molo::app::views {
// Flash definitions (need the complete Application type).
inline void Flash::flash(http_msg::Request& req, http_msg::Response& res, std::string level,
std::string text) {
app::Application* app = req.app();
if (app == nullptr) throw errors::InternalError("flash needs a bound application");
std::string sid = req.cookie(kSessionCookie);
if (sid.empty()) {
sid = generate_session_id();
http_msg::SetCookie cookie;
cookie.name = kSessionCookie;
cookie.value = sid;
res.headers().add("set-cookie", cookie.render());
}
app->sessions()->add_flash(sid, seams::FlashMessage{std::move(level), std::move(text)});
}
inline std::vector<seams::FlashMessage> Flash::take(http_msg::Request& req) {
app::Application* app = req.app();
if (app == nullptr) throw errors::InternalError("flash needs a bound application");
std::string sid = req.cookie(kSessionCookie);
if (sid.empty()) return {};
return app->sessions()->take_flashes(sid);
}
} // namespace molo::app::views
+109
View File
@@ -0,0 +1,109 @@
#pragma once
// Spec: molo::app::app plugin registry (plan 05, E12). Named hooks:
// route_added, app_started, error_render. Plugins declare capabilities
// ("routes", "di", "errors"); PluginContext getters throw PluginAccessError
// unless the plugin declared the matching capability, so plugins cannot
// reach undeclared internals. Hook order per event is registration order.
#include <functional>
#include <map>
#include <set>
#include <stdexcept>
#include <string>
#include <utility>
#include <vector>
namespace molo::app::routing {
class Route;
}
namespace molo::app::app {
class Application;
class PluginAccessError : public std::runtime_error {
public:
explicit PluginAccessError(const std::string& msg) : std::runtime_error(msg) {}
};
class PluginContext {
public:
PluginContext(Application* app, const std::set<std::string>& capabilities,
std::string plugin_name);
const std::string& plugin_name() const { return plugin_name_; }
bool has(const std::string& capability) const;
// Capability "routes".
std::size_t route_count() const;
// Capability "di".
bool di_has(const std::string& provider) const;
// Capability "errors".
std::string last_error_code() const;
private:
void require(const std::string& capability) const;
Application* app_;
std::set<std::string> capabilities_;
std::string plugin_name_;
};
struct PluginHooks {
std::function<void(PluginContext&, const routing::Route&)> route_added;
std::function<void(PluginContext&)> app_started;
std::function<void(PluginContext&, int, const std::string&)> error_render;
};
struct Plugin {
std::string name;
std::set<std::string> capabilities;
PluginHooks hooks;
};
class PluginRegistry {
public:
void register_plugin(Plugin plugin) {
for (const auto& cap : plugin.capabilities) {
if (cap != "routes" && cap != "di" && cap != "errors") {
throw PluginAccessError("plugin '" + plugin.name + "' declares unknown capability '" +
cap + "'");
}
}
plugins_.push_back(std::move(plugin));
}
const std::vector<Plugin>& plugins() const { return plugins_; }
void fire_route_added(Application* app, const routing::Route& route) const {
for (const Plugin& p : plugins_) {
if (p.hooks.route_added) {
PluginContext ctx(app, p.capabilities, p.name);
p.hooks.route_added(ctx, route);
}
}
}
void fire_app_started(Application* app) const {
for (const Plugin& p : plugins_) {
if (p.hooks.app_started) {
PluginContext ctx(app, p.capabilities, p.name);
p.hooks.app_started(ctx);
}
}
}
void fire_error_render(Application* app, int status, const std::string& code) const {
for (const Plugin& p : plugins_) {
if (p.hooks.error_render) {
PluginContext ctx(app, p.capabilities, p.name);
p.hooks.error_render(ctx, status, code);
}
}
}
private:
std::vector<Plugin> plugins_;
};
} // namespace molo::app::app
+123
View File
@@ -0,0 +1,123 @@
#pragma once
// Spec: molo::app::async::Task. Minimal eager coroutine task used as the
// handler return type (plan 05, R1 and section 6 Middleware). Seam note: the
// production executor is owned by 01-runtime; this local type keeps the app
// layer compilable standalone and has the same co_await shape for ready
// values. It runs eagerly and synchronously: every co_await inside app code
// awaits an already complete Task. Integration swaps this header for the
// runtime task without touching call sites.
#include <coroutine>
#include <exception>
#include <optional>
#include <utility>
namespace molo::app::async {
template <typename T>
class Task {
public:
struct promise_type {
std::optional<T> value;
std::exception_ptr error;
Task get_return_object() {
return Task{std::coroutine_handle<promise_type>::from_promise(*this)};
}
std::suspend_never initial_suspend() noexcept { return {}; }
std::suspend_always final_suspend() noexcept { return {}; }
void return_value(T v) { value.emplace(std::move(v)); }
void unhandled_exception() { error = std::current_exception(); }
};
using Handle = std::coroutine_handle<promise_type>;
Task() = default;
explicit Task(Handle h) : handle_(h) {}
Task(Task&& other) noexcept : handle_(other.handle_) { other.handle_ = nullptr; }
Task& operator=(Task&& other) noexcept {
if (this != &other) {
destroy();
handle_ = other.handle_;
other.handle_ = nullptr;
}
return *this;
}
Task(const Task&) = delete;
Task& operator=(const Task&) = delete;
~Task() { destroy(); }
bool await_ready() const noexcept { return true; }
void await_suspend(std::coroutine_handle<>) const noexcept {}
T await_resume() { return value(); }
T value() && {
if (!handle_) throw std::logic_error("molo::app::async::Task: empty task");
if (handle_.promise().error) std::rethrow_exception(handle_.promise().error);
return std::move(*handle_.promise().value);
}
T value() & {
if (!handle_) throw std::logic_error("molo::app::async::Task: empty task");
if (handle_.promise().error) std::rethrow_exception(handle_.promise().error);
T out = *handle_.promise().value;
return out;
}
private:
void destroy() {
if (handle_) handle_.destroy();
handle_ = nullptr;
}
Handle handle_{nullptr};
};
template <>
class Task<void> {
public:
struct promise_type {
std::exception_ptr error;
Task get_return_object() {
return Task{std::coroutine_handle<promise_type>::from_promise(*this)};
}
std::suspend_never initial_suspend() noexcept { return {}; }
std::suspend_always final_suspend() noexcept { return {}; }
void return_void() {}
void unhandled_exception() { error = std::current_exception(); }
};
using Handle = std::coroutine_handle<promise_type>;
Task() = default;
explicit Task(Handle h) : handle_(h) {}
Task(Task&& other) noexcept : handle_(other.handle_) { other.handle_ = nullptr; }
Task& operator=(Task&&) = delete;
Task(const Task&) = delete;
Task& operator=(const Task&) = delete;
~Task() {
if (handle_) handle_.destroy();
}
bool await_ready() const noexcept { return true; }
void await_suspend(std::coroutine_handle<>) const noexcept {}
void await_resume() { value(); }
void value() {
if (!handle_) throw std::logic_error("molo::app::async::Task: empty task");
if (handle_.promise().error) std::rethrow_exception(handle_.promise().error);
}
private:
Handle handle_{nullptr};
};
// Block on an eager task. Valid only because every awaited task completes
// synchronously; the runtime executor replaces this on integration.
template <typename T>
T run(Task<T>&& task) {
return std::move(task).value();
}
inline void run(Task<void>&& task) { task.value(); }
} // namespace molo::app::async
+52
View File
@@ -0,0 +1,52 @@
#pragma once
// Spec: molo::app::caps. Single home of every static ceiling owned by this
// part (plan 05, section 6 plus R11). All values are compile-time constants.
// No autotuning, no silent growth. Sibling-owned byte caps (body, headers)
// are enforced by 01-runtime before this layer; the values below bind the
// app-layer structures only.
#include <cstddef>
namespace molo::app::caps {
// Routing and application (section 6, Global caps).
inline constexpr std::size_t kMaxRoutesPerApp = 100000;
inline constexpr std::size_t kMaxPathLength = 2048;
inline constexpr std::size_t kMaxPathParamsPerRoute = 32;
inline constexpr std::size_t kMaxMiddlewareLayers = 64;
inline constexpr std::size_t kMaxSubAppNestingDepth = 8;
inline constexpr std::size_t kMaxDiProviders = 4096;
// HTTP message views (standalone parsing; runtime owns wire caps).
inline constexpr std::size_t kMaxHeaders = 100;
inline constexpr std::size_t kMaxHeaderName = 256;
inline constexpr std::size_t kMaxHeaderValue = 8192;
inline constexpr std::size_t kMaxQueryParams = 1000;
inline constexpr std::size_t kMaxCookies = 200;
// Validation and forms (section 6, Validation and forms).
inline constexpr std::size_t kMaxFormFields = 1000;
inline constexpr std::size_t kMaxFieldName = 256;
inline constexpr std::size_t kMaxNonFileValue = 1048576; // 1 MiB
inline constexpr std::size_t kMaxJsonDepth = 32;
inline constexpr std::size_t kMaxJsonDocument = 10485760; // 10 MiB
inline constexpr std::size_t kMaxMultipartFiles = 100;
inline constexpr std::size_t kMaxFileBytes = 16777216; // 16 MiB default; 03-security owns policy
inline constexpr std::size_t kMaxMultipartTotal = 67108864; // 64 MiB
// Templates (section 6, Templates).
inline constexpr std::size_t kMaxTemplateSize = 1048576; // 1 MiB
inline constexpr std::size_t kMaxIncludeDepth = 16;
inline constexpr std::size_t kMaxExtendsChain = 8;
inline constexpr std::size_t kMaxLoopIterations = 100000;
inline constexpr std::size_t kMaxRenderOutput = 33554432; // 32 MiB
inline constexpr std::size_t kMaxCompiledTemplates = 512;
inline constexpr std::size_t kMaxMacroArgs = 32;
inline constexpr std::size_t kMaxExprDepth = 128;
// Errors and misc.
inline constexpr std::size_t kMaxErrorDetails = 64;
inline constexpr std::size_t kMaxRouteName = 256;
inline constexpr std::size_t kMaxFlashMessages = 100;
} // namespace molo::app::caps
+208
View File
@@ -0,0 +1,208 @@
#pragma once
// Spec: molo::app::di::Container (plan 05, R8, E9). Dependency injection
// without globals: named providers with app scope (one per Application) or
// request scope (one per request, destroyed after the response). Providers
// are factories or values. Declared dependencies feed startup cycle
// detection (cycle quoted on failure); resolution carries a dynamic guard
// with the same quoting. No service singletons, no file-static mutable
// state reachable from handlers.
#include <any>
#include <functional>
#include <map>
#include <set>
#include <stdexcept>
#include <string>
#include <utility>
#include <vector>
#include "../caps.h"
namespace molo::app::di {
enum class Scope { App, Request };
class DiError : public std::runtime_error {
public:
explicit DiError(const std::string& msg) : std::runtime_error(msg) {}
};
class CycleError : public DiError {
public:
explicit CycleError(const std::string& msg) : DiError(msg) {}
};
class Container;
class RequestScope;
class Resolver {
public:
std::any get(const std::string& name);
template <typename T>
T get_as(const std::string& name) {
return std::any_cast<T>(get(name));
}
private:
friend class Container;
friend class RequestScope;
Resolver(Container* owner, std::map<std::string, std::any>* request_cache,
std::vector<std::string>* stack)
: owner_(owner), request_cache_(request_cache), stack_(stack) {}
Container* owner_;
std::map<std::string, std::any>* request_cache_;
std::vector<std::string>* stack_;
};
struct Provider {
std::function<std::any(Resolver&)> factory;
Scope scope = Scope::App;
std::vector<std::string> deps;
std::any cached;
bool resolved = false;
};
class Container {
public:
void provide(std::string name, std::function<std::any(Resolver&)> factory,
Scope scope = Scope::App, std::vector<std::string> deps = {}) {
if (providers_.count(name)) throw DiError("duplicate DI provider '" + name + "'");
if (providers_.size() >= caps::kMaxDiProviders) {
throw DiError("too many DI providers");
}
Provider p;
p.factory = std::move(factory);
p.scope = scope;
p.deps = std::move(deps);
providers_[std::move(name)] = std::move(p);
}
template <typename T>
void provide_typed(std::string name, std::function<T(Resolver&)> factory,
Scope scope = Scope::App, std::vector<std::string> deps = {}) {
provide(std::move(name),
[factory = std::move(factory)](Resolver& r) -> std::any {
return std::any(factory(r));
},
scope, std::move(deps));
}
template <typename T>
void provide_value(std::string name, T value) {
provide(std::move(name),
[v = std::move(value)](Resolver&) -> std::any { return std::any(v); },
Scope::App, {});
}
bool has(const std::string& name) const { return providers_.count(name) > 0; }
std::size_t size() const { return providers_.size(); }
void validate_no_cycles() const {
std::set<std::string> done;
for (const auto& kv : providers_) {
std::vector<std::string> path;
visit(kv.first, path, done);
}
}
RequestScope fork_request();
private:
friend class Resolver;
friend class RequestScope;
std::any resolve_into(const std::string& name, std::map<std::string, std::any>* request_cache,
std::vector<std::string>* stack) {
auto it = providers_.find(name);
if (it == providers_.end()) throw DiError("unknown DI provider '" + name + "'");
for (const auto& frame : *stack) {
if (frame == name) {
std::string cycle;
bool started = false;
for (const auto& f : *stack) {
if (f == name) started = true;
if (started) {
if (!cycle.empty()) cycle += " -> ";
cycle += "'" + f + "'";
}
}
cycle += " -> '" + name + "'";
throw CycleError("dependency cycle: " + cycle);
}
}
Provider& p = it->second;
if (p.scope == Scope::App && p.resolved) return p.cached;
if (p.scope == Scope::Request && request_cache != nullptr) {
auto hit = request_cache->find(name);
if (hit != request_cache->end()) return hit->second;
}
stack->push_back(name);
Resolver resolver(this, request_cache, stack);
std::any value = p.factory(resolver);
stack->pop_back();
if (p.scope == Scope::App) {
p.cached = value;
p.resolved = true;
} else if (request_cache != nullptr) {
(*request_cache)[name] = value;
}
return value;
}
void visit(const std::string& name, std::vector<std::string>& path,
std::set<std::string>& done) const {
if (done.count(name)) return;
for (const auto& frame : path) {
if (frame == name) {
std::string cycle;
bool started = false;
for (const auto& f : path) {
if (f == name) started = true;
if (started) {
if (!cycle.empty()) cycle += " -> ";
cycle += "'" + f + "'";
}
}
cycle += " -> '" + name + "'";
throw CycleError("dependency cycle: " + cycle);
}
}
auto it = providers_.find(name);
if (it == providers_.end()) return;
path.push_back(name);
for (const auto& dep : it->second.deps) visit(dep, path, done);
path.pop_back();
done.insert(name);
}
std::map<std::string, Provider> providers_;
};
class RequestScope {
public:
explicit RequestScope(Container* owner) : owner_(owner) {}
std::any get(const std::string& name) {
return owner_->resolve_into(name, &cache_, &stack_);
}
template <typename T>
T get_as(const std::string& name) {
return std::any_cast<T>(get(name));
}
Resolver resolver() { return Resolver(owner_, &cache_, &stack_); }
private:
Container* owner_;
std::map<std::string, std::any> cache_;
std::vector<std::string> stack_;
};
inline std::any Resolver::get(const std::string& name) {
return owner_->resolve_into(name, request_cache_, stack_);
}
inline RequestScope Container::fork_request() { return RequestScope(this); }
} // namespace molo::app::di
+209
View File
@@ -0,0 +1,209 @@
#pragma once
// Spec: molo::app::errors::ErrorHandler (plan 05, R9, E5). Maps exceptions
// to status plus negotiated body. JSON shape:
// {"error":{"code":"...","message":"...","request_id":"..."}}.
// HTML shape: responsive error page with the same fields, no internals.
// ValidationFailed renders the 422 detail shape instead:
// {"detail":[{"loc":[...],"msg":"...","type":"..."}]}.
// Unknown exceptions become 500; client-visible text is fixed, internals go
// to the log sink hook (owned by 02-observability on integration).
#include <exception>
#include <functional>
#include <string>
#include <string_view>
#include "../../audit/redact/redactor.h"
#include "../http_msg/html.h"
#include "../http_msg/request.h"
#include "../http_msg/response.h"
#include "../seams/request_id.h"
#include "../validate/json.h"
#include "../validate/value.h"
#include "http_error.h"
namespace molo::app::errors {
inline bool wants_html(const http_msg::Request& req) {
std::string accept = req.headers().get("accept");
std::string low;
for (char c : accept) low += (char)std::tolower((unsigned char)c);
bool html = low.find("text/html") != std::string::npos;
bool json = low.find("application/json") != std::string::npos;
if (html && !json) return true;
if (html && json) return low.find("text/html") < low.find("application/json");
return false;
}
inline std::string error_page_html(int status, const std::string& code, const std::string& message,
const std::string& request_id) {
std::string html =
"<!DOCTYPE html><html lang=\"en\"><head><meta charset=\"utf-8\">"
"<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">"
"<title>" +
std::to_string(status) + " " + http_msg::escape_html(code) +
"</title><style>"
"body{font-family:system-ui,sans-serif;margin:0;background:#f6f6f6;color:#222}"
".card{max-width:34rem;margin:4rem auto;padding:1.5rem;background:#fff;"
"border-radius:.5rem;box-shadow:0 1px 4px rgba(0,0,0,.12)}"
"h1{font-size:1.4rem;margin:0 0 .5rem}code{color:#666;font-size:.85rem}"
"@media (max-width:40rem){.card{margin:1rem;padding:1rem}}"
"</style></head><body><div class=\"card\"><h1>" +
std::to_string(status) + " " + http_msg::escape_html(message) + "</h1><p><code>" +
http_msg::escape_html(code) + " request " + http_msg::escape_html(request_id) +
"</code></p></div></body></html>";
return html;
}
inline std::string validation_page_html(const validate::ValidationError& cause,
const std::string& request_id) {
std::string rows;
for (const auto& f : cause.failures()) {
std::string loc;
for (std::size_t i = 0; i < f.loc.size(); ++i) {
if (i) loc += ".";
loc += f.loc[i];
}
rows += "<li><strong>" + http_msg::escape_html(loc) + "</strong> " +
http_msg::escape_html(f.msg) + " <code>" + http_msg::escape_html(f.type) +
"</code></li>";
}
std::string html =
"<!DOCTYPE html><html lang=\"en\"><head><meta charset=\"utf-8\">"
"<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">"
"<title>422 validation failed</title><style>"
"body{font-family:system-ui,sans-serif;margin:0;background:#f6f6f6;color:#222}"
".card{max-width:34rem;margin:4rem auto;padding:1.5rem;background:#fff;"
"border-radius:.5rem;box-shadow:0 1px 4px rgba(0,0,0,.12)}"
"@media (max-width:40rem){.card{margin:1rem;padding:1rem}}"
"</style></head><body><div class=\"card\"><h1>422 validation failed</h1>"
"<ul>" +
rows + "</ul><p><code>request " + http_msg::escape_html(request_id) +
"</code></p></div></body></html>";
return html;
}
class ErrorHandler {
public:
using LogSink = std::function<void(int status, const std::string& code,
const std::string& request_id,
const std::string& internal)>;
void set_log_sink(LogSink sink) { sink_ = std::move(sink); }
void set_render_hook(std::function<void(int, const std::string&)> hook) {
render_hook_ = std::move(hook);
}
http_msg::Response render(const HttpError& err, const http_msg::Request& req,
std::string request_id) const {
// Audit patch: user-visible detail and diagnostics pass through the
// redactor before they reach the response body and the log sink.
const std::string safe_detail =
::molo::audit::redact::Redactor::RedactDetail(err.detail_message());
log(err.status(), err.code(), request_id, safe_detail);
if (render_hook_) render_hook_(err.status(), err.code());
if (const auto* vf = dynamic_cast<const ValidationFailed*>(&err)) {
if (wants_html(req)) {
return http_msg::HtmlResponse(validation_page_html(vf->cause(), request_id), 422);
}
return http_msg::JsonResponse(vf->cause().to_value(), 422);
}
if (const auto* na = dynamic_cast<const NotAcceptable*>(&err)) {
// Spec 406 shape: {"Detail":{"available":[...]}} (capital D).
validate::Array avail;
for (const auto& a : na->available()) avail.emplace_back(a);
validate::Object inner;
inner["available"] = validate::Value(std::move(avail));
validate::Object root;
root["Detail"] = validate::Value(std::move(inner));
if (wants_html(req)) {
std::string items;
for (const auto& a : na->available()) {
items += "<li><code>" + http_msg::escape_html(a) + "</code></li>";
}
std::string page =
"<!DOCTYPE html><html lang=\"en\"><head><meta charset=\"utf-8\">"
"<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">"
"<title>406 not acceptable</title><style>"
"body{font-family:system-ui,sans-serif;margin:0;background:#f6f6f6;color:#222}"
".card{max-width:34rem;margin:4rem auto;padding:1.5rem;background:#fff;"
"border-radius:.5rem;box-shadow:0 1px 4px rgba(0,0,0,.12)}"
"@media (max-width:40rem){.card{margin:1rem;padding:1rem}}"
"</style></head><body><div class=\"card\">"
"<h1>406 not acceptable</h1><p>Available types:</p><ul>" +
items + "</ul><p><code>request " + http_msg::escape_html(request_id) +
"</code></p></div></body></html>";
return http_msg::HtmlResponse(page, 406);
}
return http_msg::JsonResponse(validate::Value(std::move(root)), 406);
}
http_msg::Response res =
wants_html(req)
? http_msg::Response(http_msg::HtmlResponse(
error_page_html(err.status(), err.code(), safe_detail, request_id),
err.status()))
: http_msg::Response(http_msg::JsonResponse(
validate::Value([&] {
validate::Object inner;
inner["code"] = validate::Value(err.code());
inner["message"] = validate::Value(safe_detail);
inner["request_id"] = validate::Value(request_id);
validate::Object root;
root["error"] = validate::Value(std::move(inner));
return root;
}()),
err.status()));
if (const auto* mna = dynamic_cast<const MethodNotAllowed*>(&err)) {
res.headers().set("allow", mna->allow_header());
}
return res;
}
// Governance: RFC 9457 renderer for problem bodies. Copies Retry-After
// and Link headers from the source headers map when present.
http_msg::Response render_problem(int status, std::string_view type, std::string_view title,
std::string_view detail,
const http_msg::Headers& extra) const {
validate::Object root;
root["type"] = validate::Value(std::string(type));
root["title"] = validate::Value(std::string(title));
root["status"] = validate::Value(static_cast<long long>(status));
if (!detail.empty()) root["detail"] = validate::Value(std::string(detail));
http_msg::Response res = http_msg::JsonResponse(validate::Value(std::move(root)), status);
res.set_content_type("application/problem+json");
for (const char* name : {"retry-after", "link"}) {
std::string v = extra.get(name);
if (!v.empty()) res.headers().set(name, v);
}
return res;
}
http_msg::Response render_unknown(const http_msg::Request& req, std::string request_id,
const std::string& internal) const {
const std::string safe_internal =
::molo::audit::redact::Redactor::RedactDetail(internal);
log(500, "internal_error", request_id, safe_internal);
InternalError err;
if (wants_html(req)) {
return http_msg::HtmlResponse(
error_page_html(500, err.code(), err.detail_message(), request_id), 500);
}
validate::Object inner;
inner["code"] = validate::Value(err.code());
inner["message"] = validate::Value(err.detail_message());
inner["request_id"] = validate::Value(request_id);
validate::Object root;
root["error"] = validate::Value(std::move(inner));
return http_msg::JsonResponse(validate::Value(std::move(root)), 500);
}
private:
void log(int status, const std::string& code, const std::string& request_id,
const std::string& internal) const {
if (sink_) sink_(status, code, request_id, internal);
}
LogSink sink_;
std::function<void(int, const std::string&)> render_hook_;
};
} // namespace molo::app::errors
+178
View File
@@ -0,0 +1,178 @@
#pragma once
// Spec: molo::app::errors HttpError hierarchy (plan 05, R9, section 6
// Errors). Every framework exception maps to exactly one HTTP status via
// this table. Unmapped exceptions become 500 in ErrorHandler.
#include <stdexcept>
#include <string>
#include <utility>
#include <vector>
#include "../validate/errors.h"
namespace molo::app::errors {
class HttpError : public std::exception {
public:
HttpError(int status, std::string code, std::string message)
: status_(status), code_(std::move(code)), message_(std::move(message)) {}
const char* what() const noexcept override { return message_.c_str(); }
int status() const { return status_; }
const std::string& code() const { return code_; }
const std::string& detail_message() const { return message_; }
const std::string& request_id() const { return request_id_; }
void set_request_id(std::string id) { request_id_ = std::move(id); }
private:
int status_;
std::string code_;
std::string message_;
std::string request_id_;
};
class BadRequest : public HttpError {
public:
explicit BadRequest(std::string message = "bad request")
: HttpError(400, "bad_request", std::move(message)) {}
};
class Unauthorized : public HttpError {
public:
explicit Unauthorized(std::string message = "unauthorized")
: HttpError(401, "unauthorized", std::move(message)) {}
};
class Forbidden : public HttpError {
public:
explicit Forbidden(std::string message = "forbidden")
: HttpError(403, "forbidden", std::move(message)) {}
};
class NotFound : public HttpError {
public:
explicit NotFound(std::string message = "not found")
: HttpError(404, "not_found", std::move(message)) {}
};
class MethodNotAllowed : public HttpError {
public:
explicit MethodNotAllowed(std::vector<std::string> allow,
std::string message = "method not allowed")
: HttpError(405, "method_not_allowed", std::move(message)), allow_(std::move(allow)) {}
const std::vector<std::string>& allow() const { return allow_; }
std::string allow_header() const {
std::string out;
for (std::size_t i = 0; i < allow_.size(); ++i) {
if (i) out += ", ";
out += allow_[i];
}
return out;
}
private:
std::vector<std::string> allow_;
};
class NotAcceptable : public HttpError {
public:
explicit NotAcceptable(std::vector<std::string> available = {},
std::string message = "not acceptable")
: HttpError(406, "not_acceptable", std::move(message)), available_(std::move(available)) {}
const std::vector<std::string>& available() const { return available_; }
private:
std::vector<std::string> available_;
};
class RequestTimeout : public HttpError {
public:
explicit RequestTimeout(std::string message = "request timeout")
: HttpError(408, "request_timeout", std::move(message)) {}
};
class PayloadTooLarge : public HttpError {
public:
explicit PayloadTooLarge(std::string message = "payload too large")
: HttpError(413, "payload_too_large", std::move(message)) {}
};
class UriTooLong : public HttpError {
public:
explicit UriTooLong(std::string message = "uri too long")
: HttpError(414, "uri_too_long", std::move(message)) {}
};
class HeaderFieldsTooLarge : public HttpError {
public:
explicit HeaderFieldsTooLarge(std::string message = "header fields too large")
: HttpError(431, "header_fields_too_large", std::move(message)) {}
};
class UnsupportedMediaType : public HttpError {
public:
explicit UnsupportedMediaType(std::string message = "unsupported media type")
: HttpError(415, "unsupported_media_type", std::move(message)) {}
};
class ValidationFailed : public HttpError {
public:
explicit ValidationFailed(validate::ValidationError cause)
: HttpError(422, "validation_failed", "validation failed"), cause_(std::move(cause)) {}
const validate::ValidationError& cause() const { return cause_; }
private:
validate::ValidationError cause_;
};
class TooManyRequests : public HttpError {
public:
explicit TooManyRequests(std::string message = "too many requests")
: HttpError(429, "too_many_requests", std::move(message)) {}
};
class Gone : public HttpError {
public:
explicit Gone(std::string message = "gone")
: HttpError(410, "gone", std::move(message)) {}
};
// Tenant errors (PATCHES 11.13), real subclass style.
class TenantUnknown : public HttpError {
public:
explicit TenantUnknown(std::string message = "tenant unknown")
: HttpError(404, "tenant_unknown", std::move(message)) {}
};
class TenantSuspended : public HttpError {
public:
explicit TenantSuspended(std::string message = "tenant suspended")
: HttpError(403, "tenant_suspended", std::move(message)) {}
};
class TenantConflict : public HttpError {
public:
explicit TenantConflict(std::string message = "tenant conflict")
: HttpError(400, "tenant_conflict", std::move(message)) {}
};
class InsufficientStorage : public HttpError {
public:
explicit InsufficientStorage(std::string message = "insufficient storage")
: HttpError(507, "insufficient_storage", std::move(message)) {}
};
class InternalError : public HttpError {
public:
explicit InternalError(std::string message = "internal server error")
: HttpError(500, "internal_error", std::move(message)) {}
};
class Unavailable : public HttpError {
public:
explicit Unavailable(std::string message = "service unavailable")
: HttpError(503, "unavailable", std::move(message)) {}
};
} // namespace molo::app::errors
+99
View File
@@ -0,0 +1,99 @@
#pragma once
// Spec: molo::app::forms::Form. Binds application/json,
// application/x-www-form-urlencoded and multipart/form-data into a
// validate::Model (plan 05, R2, E10). One entry point, content-type
// dispatch inside. Status policy: malformed shape, bad JSON and depth
// overrun yield 400; size and count overruns (document, value, file,
// total, field count) yield 413.
#include <cstddef>
#include <string>
#include "../errors/http_error.h"
#include "../http_msg/request.h"
#include "../validate/errors.h"
#include "../validate/json.h"
#include "../validate/model.h"
#include "../validate/value.h"
#include "multipart.h"
#include "urlencoded.h"
namespace molo::app::forms {
struct FormData {
validate::Object fields;
std::vector<FileUpload> files;
};
class Form {
public:
static FormData parse_body(const http_msg::Request& req,
std::size_t max_json_document = caps::kMaxJsonDocument) {
std::string ctype = req.content_type();
if (ctype == "application/json") return parse_json_body(req.body(), max_json_document);
if (ctype == "application/x-www-form-urlencoded") {
FormData out;
try {
out.fields = parse_urlencoded(req.body());
} catch (const std::length_error& e) {
throw errors::PayloadTooLarge(e.what());
} catch (const std::exception& e) {
throw errors::BadRequest(e.what());
}
return out;
}
if (ctype == "multipart/form-data") {
FormData out;
try {
MultipartBody body =
parse_multipart(req.headers().get("content-type"), req.body());
out.fields = std::move(body.fields);
out.files = std::move(body.files);
} catch (const std::length_error& e) {
throw errors::PayloadTooLarge(e.what());
} catch (const errors::HttpError&) {
throw;
} catch (const std::exception& e) {
throw errors::BadRequest(e.what());
}
return out;
}
throw errors::UnsupportedMediaType("unsupported form content type: " + ctype);
}
// Parse then validate into a clean object. Throws ValidationFailed (422)
// carrying every field failure (R3).
static validate::Object bind(const http_msg::Request& req, const validate::Model& model,
const std::string& source = "body",
std::size_t max_json_document = caps::kMaxJsonDocument) {
FormData data = parse_body(req, max_json_document);
try {
return model.validate(data.fields, source);
} catch (const validate::ValidationError& e) {
throw errors::ValidationFailed(e);
}
}
private:
static FormData parse_json_body(const std::string& body, std::size_t max_doc) {
if (max_doc == 0 && !body.empty()) {
throw errors::PayloadTooLarge("route rejects bodies");
}
if (body.size() > max_doc) throw errors::PayloadTooLarge("JSON document too large");
FormData out;
validate::Value v;
try {
v = validate::parse_json(body);
} catch (const validate::JsonError& e) {
throw errors::BadRequest(e.what());
}
if (!v.is_object()) throw errors::BadRequest("JSON body must be an object");
out.fields = *std::get_if<validate::Object>(&v.storage());
if (out.fields.size() > caps::kMaxFormFields) {
throw errors::BadRequest("too many JSON fields");
}
return out;
}
};
} // namespace molo::app::forms
+127
View File
@@ -0,0 +1,127 @@
#pragma once
// Spec: molo::app::forms multipart binding. Parses multipart/form-data field
// parts into an Object; file parts become FileUpload records (bytes held in
// memory under the standalone caps; quota policy and scanning belong to
// 03-security, wired through Application on integration).
#include <cctype>
#include <stdexcept>
#include <string>
#include <string_view>
#include <vector>
#include "../caps.h"
#include "../validate/value.h"
namespace molo::app::forms {
struct FileUpload {
std::string field;
std::string filename;
std::string content_type = "application/octet-stream";
std::string data;
};
struct MultipartBody {
validate::Object fields;
std::vector<FileUpload> files;
};
inline std::string multipart_boundary(std::string_view content_type_header) {
std::string lower(content_type_header);
for (char& c : lower) c = (char)std::tolower((unsigned char)c);
std::string::size_type pos = lower.find("boundary=");
if (pos == std::string::npos) return "";
std::string b(content_type_header.substr(pos + 9));
while (!b.empty() && (b.back() == ' ' || b.back() == '\t' || b.back() == '"')) b.pop_back();
while (!b.empty() && (b.front() == ' ' || b.front() == '\t' || b.front() == '"'))
b.erase(b.begin());
return b;
}
inline std::string part_header_attr(std::string_view headers, std::string_view attr) {
std::string lower(headers);
for (char& c : lower) c = (char)std::tolower((unsigned char)c);
std::string key(attr);
for (char& c : key) c = (char)std::tolower((unsigned char)c);
key += "=\"";
std::string::size_type pos = lower.find(key);
if (pos == std::string::npos) {
key = std::string(attr) + "=";
for (char& c : key) c = (char)std::tolower((unsigned char)c);
pos = lower.find(key);
if (pos == std::string::npos) return "";
std::string::size_type start = pos + key.size();
std::string::size_type end = lower.find_first_of("; \t\r\n", start);
return std::string(headers.substr(start, end - start));
}
std::string::size_type start = pos + key.size();
std::string::size_type end = headers.find('"', start);
if (end == std::string_view::npos) return "";
return std::string(headers.substr(start, end - start));
}
inline MultipartBody parse_multipart(std::string_view content_type_header, std::string_view body) {
std::string boundary = multipart_boundary(content_type_header);
if (boundary.empty()) throw std::runtime_error("multipart body without boundary");
if (body.size() > caps::kMaxMultipartTotal) throw std::length_error("multipart body too large");
MultipartBody out;
std::string delim = "--" + boundary;
std::string end_delim = delim + "--";
std::size_t pos = 0;
std::size_t field_count = 0;
while (true) {
std::size_t start = body.find(delim, pos);
if (start == std::string_view::npos) break;
start += delim.size();
if (body.substr(start, 2) == "--") break;
if (body.substr(start, 2) == "\r\n") start += 2;
std::size_t head_end = body.find("\r\n\r\n", start);
if (head_end == std::string_view::npos) break;
std::string_view headers = body.substr(start, head_end - start);
std::size_t data_start = head_end + 4;
std::size_t next = body.find(delim, data_start);
if (next == std::string_view::npos) break;
std::size_t data_end = next;
if (data_end >= 2 && body.substr(data_end - 2, 2) == "\r\n") data_end -= 2;
std::string data(body.substr(data_start, data_end - data_start));
std::string name = part_header_attr(headers, "name");
std::string filename = part_header_attr(headers, "filename");
if (name.size() > caps::kMaxFieldName) throw std::length_error("form field name too long");
if (filename.empty()) {
if (field_count >= caps::kMaxFormFields) throw std::length_error("too many form fields");
if (data.size() > caps::kMaxNonFileValue) throw std::length_error("form value too large");
out.fields[std::move(name)] = validate::Value(std::move(data));
++field_count;
} else {
if (out.files.size() >= caps::kMaxMultipartFiles) {
throw std::length_error("too many uploaded files");
}
if (data.size() > caps::kMaxFileBytes) throw std::length_error("uploaded file too large");
FileUpload upload;
upload.field = std::move(name);
upload.filename = std::move(filename);
std::string ctype = part_header_attr(headers, "content-type");
// Content-Type of a part is a full header line, not an attr; parse it.
std::string lower(headers);
for (char& c : lower) c = (char)std::tolower((unsigned char)c);
std::string::size_type cpos = lower.find("content-type:");
if (cpos != std::string::npos) {
std::string::size_type vstart = cpos + 13;
while (vstart < headers.size() && (headers[vstart] == ' ' || headers[vstart] == '\t'))
++vstart;
std::string::size_type vend = headers.find("\r", vstart);
ctype = std::string(headers.substr(vstart, vend - vstart));
std::string::size_type semi = ctype.find(';');
if (semi != std::string::npos) ctype = ctype.substr(0, semi);
}
if (!ctype.empty()) upload.content_type = ctype;
upload.data = std::move(data);
out.files.push_back(std::move(upload));
}
pos = next;
}
return out;
}
} // namespace molo::app::forms
+65
View File
@@ -0,0 +1,65 @@
#pragma once
// Spec: molo::app::forms urlencoded binding. Parses
// application/x-www-form-urlencoded into an Object (last value wins per key,
// full multimap available). Caps from caps.h.
#include <stdexcept>
#include <string>
#include <string_view>
#include <utility>
#include <vector>
#include "../caps.h"
#include "../http_msg/query.h"
#include "../validate/value.h"
namespace molo::app::forms {
inline validate::Object parse_urlencoded(std::string_view body) {
validate::Object out;
std::size_t count = 0;
std::size_t i = 0;
while (i <= body.size()) {
std::size_t amp = body.find('&', i);
if (amp == std::string_view::npos) amp = body.size();
std::string_view pair = body.substr(i, amp - i);
if (!pair.empty()) {
if (count >= caps::kMaxFormFields) throw std::length_error("too many form fields");
std::size_t eq = pair.find('=');
std::string_view k = (eq == std::string_view::npos) ? pair : pair.substr(0, eq);
std::string_view v = (eq == std::string_view::npos) ? "" : pair.substr(eq + 1);
std::string key = http_msg::percent_decode(k, true);
std::string val = http_msg::percent_decode(v, true);
if (key.size() > caps::kMaxFieldName) throw std::length_error("form field name too long");
if (val.size() > caps::kMaxNonFileValue) throw std::length_error("form value too large");
out[std::move(key)] = validate::Value(std::move(val));
++count;
}
if (amp == body.size()) break;
i = amp + 1;
}
return out;
}
inline std::vector<std::pair<std::string, std::string>> parse_urlencoded_multi(
std::string_view body) {
std::vector<std::pair<std::string, std::string>> out;
std::size_t i = 0;
while (i <= body.size()) {
std::size_t amp = body.find('&', i);
if (amp == std::string_view::npos) amp = body.size();
std::string_view pair = body.substr(i, amp - i);
if (!pair.empty()) {
if (out.size() >= caps::kMaxFormFields) throw std::length_error("too many form fields");
std::size_t eq = pair.find('=');
std::string_view k = (eq == std::string_view::npos) ? pair : pair.substr(0, eq);
std::string_view v = (eq == std::string_view::npos) ? "" : pair.substr(eq + 1);
out.emplace_back(http_msg::percent_decode(k, true), http_msg::percent_decode(v, true));
}
if (amp == body.size()) break;
i = amp + 1;
}
return out;
}
} // namespace molo::app::forms
+82
View File
@@ -0,0 +1,82 @@
#pragma once
// Spec: molo::app::http_msg::Cookies. Read-only cookie view parsed from the
// Cookie header. Signing and encryption live in 03-security; this is the
// plain view plus a Set-Cookie builder for simple values.
#include <string>
#include <string_view>
#include <utility>
#include <vector>
#include "../caps.h"
#include "query.h"
namespace molo::app::http_msg {
class Cookies {
public:
static Cookies parse(std::string_view header) {
Cookies c;
std::size_t i = 0;
while (i < header.size()) {
while (i < header.size() && (header[i] == ' ' || header[i] == ';')) ++i;
if (i >= header.size()) break;
std::size_t semi = header.find(';', i);
if (semi == std::string_view::npos) semi = header.size();
std::string_view pair = header.substr(i, semi - i);
std::size_t eq = pair.find('=');
std::string name = eq == std::string_view::npos
? std::string(pair)
: std::string(pair.substr(0, eq));
std::string value =
eq == std::string_view::npos ? "" : percent_decode(pair.substr(eq + 1), false);
while (!name.empty() && name.back() == ' ') name.pop_back();
if (!name.empty()) {
if (c.items_.size() >= caps::kMaxCookies) break;
c.items_.emplace_back(name, value);
}
i = semi + 1;
}
return c;
}
std::string get(std::string_view name) const {
for (const auto& kv : items_) {
if (kv.first == name) return kv.second;
}
return "";
}
bool has(std::string_view name) const {
for (const auto& kv : items_) {
if (kv.first == name) return true;
}
return false;
}
const std::vector<std::pair<std::string, std::string>>& items() const { return items_; }
private:
std::vector<std::pair<std::string, std::string>> items_;
};
struct SetCookie {
std::string name;
std::string value;
std::string path = "/";
std::string same_site = "Lax";
bool http_only = true;
bool secure = false;
long max_age = -1;
std::string render() const {
std::string out = name + "=" + percent_encode(value) + "; Path=" + path;
if (max_age >= 0) out += "; Max-Age=" + std::to_string(max_age);
if (http_only) out += "; HttpOnly";
if (secure) out += "; Secure";
out += "; SameSite=" + same_site;
return out;
}
};
} // namespace molo::app::http_msg
+95
View File
@@ -0,0 +1,95 @@
#pragma once
// Spec: molo::app::http_msg::Headers. Case-insensitive header multimap.
// Lookup lowercases the name. Count and size caps from caps.h guard
// standalone parsing; the runtime enforces wire caps first.
#include <cctype>
#include <stdexcept>
#include <string>
#include <string_view>
#include <utility>
#include <vector>
#include "../caps.h"
namespace molo::app::http_msg {
inline std::string lower_header_name(std::string_view name) {
std::string out(name);
for (char& c : out) c = (char)std::tolower((unsigned char)c);
return out;
}
class Headers {
public:
void set(std::string name, std::string value) {
if (name.size() > caps::kMaxHeaderName) throw std::length_error("header name too long");
if (value.size() > caps::kMaxHeaderValue) throw std::length_error("header value too long");
std::string key = lower_header_name(name);
for (auto& kv : items_) {
if (kv.first == key) {
kv.second = value;
return;
}
}
if (items_.size() >= caps::kMaxHeaders) throw std::length_error("too many headers");
items_.emplace_back(key, value);
}
void add(std::string name, std::string value) {
if (name.size() > caps::kMaxHeaderName) throw std::length_error("header name too long");
if (value.size() > caps::kMaxHeaderValue) throw std::length_error("header value too long");
if (items_.size() >= caps::kMaxHeaders) throw std::length_error("too many headers");
items_.emplace_back(lower_header_name(name), value);
}
std::string get(std::string_view name) const {
std::string key = lower_header_name(name);
for (const auto& kv : items_) {
if (kv.first == key) return kv.second;
}
return "";
}
std::string get_or(std::string_view name, std::string fallback) const {
std::string key = lower_header_name(name);
for (const auto& kv : items_) {
if (kv.first == key) return kv.second;
}
return fallback;
}
bool contains(std::string_view name) const {
std::string key = lower_header_name(name);
for (const auto& kv : items_) {
if (kv.first == key) return true;
}
return false;
}
std::vector<std::string> get_all(std::string_view name) const {
std::string key = lower_header_name(name);
std::vector<std::string> out;
for (const auto& kv : items_) {
if (kv.first == key) out.push_back(kv.second);
}
return out;
}
void remove(std::string_view name) {
std::string key = lower_header_name(name);
std::vector<std::pair<std::string, std::string>> kept;
for (const auto& kv : items_) {
if (kv.first != key) kept.push_back(kv);
}
items_.swap(kept);
}
const std::vector<std::pair<std::string, std::string>>& items() const { return items_; }
std::size_t size() const { return items_.size(); }
private:
std::vector<std::pair<std::string, std::string>> items_;
};
} // namespace molo::app::http_msg
+42
View File
@@ -0,0 +1,42 @@
#pragma once
// Spec: molo::app::http_msg::escape_html. Shared HTML escaper for error
// pages and template filters (one implementation, plan 05 section 9).
#include <string>
#include <string_view>
namespace molo::app::http_msg {
inline std::string escape_html(std::string_view s) {
std::string out;
out.reserve(s.size());
for (char c : s) {
switch (c) {
case '&': out += "&amp;"; break;
case '<': out += "&lt;"; break;
case '>': out += "&gt;"; break;
case '"': out += "&quot;"; break;
case '\'': out += "&#x27;"; break;
default: out += c;
}
}
return out;
}
inline std::string escape_xml(std::string_view s) {
std::string out;
out.reserve(s.size());
for (char c : s) {
switch (c) {
case '&': out += "&amp;"; break;
case '<': out += "&lt;"; break;
case '>': out += "&gt;"; break;
case '"': out += "&quot;"; break;
case '\'': out += "&apos;"; break;
default: out += c;
}
}
return out;
}
} // namespace molo::app::http_msg
+37
View File
@@ -0,0 +1,37 @@
#pragma once
// Spec: molo::app::http_msg::Method. HTTP methods supported on routes.
// Covers server methods; WebDAV extras arrive with 06-realtime.
#include <optional>
#include <string>
#include <string_view>
namespace molo::app::http_msg {
enum class Method { GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS };
inline std::string to_string(Method m) {
switch (m) {
case Method::GET: return "GET";
case Method::POST: return "POST";
case Method::PUT: return "PUT";
case Method::PATCH: return "PATCH";
case Method::DELETE: return "DELETE";
case Method::HEAD: return "HEAD";
case Method::OPTIONS: return "OPTIONS";
}
return "GET";
}
inline std::optional<Method> parse_method(std::string_view s) {
if (s == "GET") return Method::GET;
if (s == "POST") return Method::POST;
if (s == "PUT") return Method::PUT;
if (s == "PATCH") return Method::PATCH;
if (s == "DELETE") return Method::DELETE;
if (s == "HEAD") return Method::HEAD;
if (s == "OPTIONS") return Method::OPTIONS;
return std::nullopt;
}
} // namespace molo::app::http_msg
+122
View File
@@ -0,0 +1,122 @@
#pragma once
// Spec: molo::app::http_msg percent-decoding and Query multimap.
// Query holds repeated keys in arrival order. Parsing caps come from caps.h.
#include <cctype>
#include <stdexcept>
#include <string>
#include <string_view>
#include <utility>
#include <vector>
#include "../caps.h"
namespace molo::app::http_msg {
inline int hex_val(char c) {
if (c >= '0' && c <= '9') return c - '0';
if (c >= 'a' && c <= 'f') return c - 'a' + 10;
if (c >= 'A' && c <= 'F') return c - 'A' + 10;
return -1;
}
inline std::string percent_decode(std::string_view s, bool plus_is_space) {
std::string out;
out.reserve(s.size());
for (std::size_t i = 0; i < s.size(); ++i) {
char c = s[i];
if (c == '+' && plus_is_space) {
out += ' ';
} else if (c == '%' && i + 2 < s.size()) {
int hi = hex_val(s[i + 1]);
int lo = hex_val(s[i + 2]);
if (hi >= 0 && lo >= 0) {
out += (char)((hi << 4) | lo);
i += 2;
} else {
out += c;
}
} else {
out += c;
}
}
return out;
}
inline std::string percent_encode(std::string_view s) {
static const char* kHex = "0123456789ABCDEF";
std::string out;
for (unsigned char c : s) {
bool plain = (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') || (c >= '0' && c <= '9') ||
c == '-' || c == '_' || c == '.' || c == '~';
if (plain) {
out += (char)c;
} else {
out += '%';
out += kHex[c >> 4];
out += kHex[c & 15];
}
}
return out;
}
class Query {
public:
static Query parse(std::string_view raw) {
Query q;
std::size_t i = 0;
if (!raw.empty() && raw[0] == '?') i = 1;
while (i <= raw.size()) {
std::size_t amp = raw.find('&', i);
if (amp == std::string_view::npos) amp = raw.size();
std::string_view pair = raw.substr(i, amp - i);
if (!pair.empty()) {
if (q.params_.size() >= caps::kMaxQueryParams) {
throw std::length_error("too many query params");
}
std::size_t eq = pair.find('=');
std::string_view k = (eq == std::string_view::npos) ? pair : pair.substr(0, eq);
std::string_view v = (eq == std::string_view::npos) ? "" : pair.substr(eq + 1);
q.params_.emplace_back(percent_decode(k, true), percent_decode(v, true));
}
if (amp == raw.size()) break;
i = amp + 1;
}
return q;
}
void add(std::string key, std::string value) {
if (params_.size() >= caps::kMaxQueryParams) throw std::length_error("too many query params");
params_.emplace_back(std::move(key), std::move(value));
}
std::string get_first(std::string_view key) const {
for (const auto& kv : params_) {
if (kv.first == key) return kv.second;
}
return "";
}
bool has(std::string_view key) const {
for (const auto& kv : params_) {
if (kv.first == key) return true;
}
return false;
}
std::vector<std::string> get_all(std::string_view key) const {
std::vector<std::string> out;
for (const auto& kv : params_) {
if (kv.first == key) out.push_back(kv.second);
}
return out;
}
const std::vector<std::pair<std::string, std::string>>& items() const { return params_; }
std::size_t size() const { return params_.size(); }
private:
std::vector<std::pair<std::string, std::string>> params_;
};
} // namespace molo::app::http_msg
+138
View File
@@ -0,0 +1,138 @@
#pragma once
// Spec: molo::app::http_msg::Request. One request object per handler call
// (plan 05, R1). Carries method, path, parsed query, headers, cookie view,
// body, matched route plus path params, owning app pointer, request ID, and
// a typed extension map for middleware, DI and validation results.
// Body and header byte caps are enforced by 01-runtime before this layer.
#include <any>
#include <map>
#include <string>
#include <string_view>
#include "../validate/value.h"
#include "cookies.h"
#include "headers.h"
#include "method.h"
#include "query.h"
namespace molo::app::routing {
class Route;
}
namespace molo::app::app {
class Application;
}
namespace molo::app::http_msg {
class Request {
public:
Request() = default;
Request(Method method, std::string path, Query query = Query(),
Headers headers = Headers(), std::string body = "")
: method_(method),
path_(std::move(path)),
query_(std::move(query)),
headers_(std::move(headers)),
body_(std::move(body)),
cookies_(Cookies::parse(headers_.get("cookie"))) {}
Method method() const { return method_; }
std::string method_string() const { return to_string(method_); }
const std::string& path() const { return path_; }
void set_path(std::string p) { path_ = std::move(p); }
const Query& query() const { return query_; }
Query& query() { return query_; }
const std::string& query_raw() const { return query_raw_; }
void set_query_raw(std::string q) { query_raw_ = std::move(q); }
const Headers& headers() const { return headers_; }
Headers& headers() { return headers_; }
const Cookies& cookies() const { return cookies_; }
const std::string& body() const { return body_; }
void set_body(std::string b) { body_ = std::move(b); }
// Query shortcut: first value or fallback.
std::string get(std::string_view key, std::string fallback = "") const {
if (query_.has(key)) return query_.get_first(key);
return fallback;
}
std::string header(std::string_view name) const { return headers_.get(name); }
std::string cookie(std::string_view name) const { return cookies_.get(name); }
// Content-Type without parameters, lowercased.
std::string content_type() const {
std::string ct = headers_.get("content-type");
std::size_t semi = ct.find(';');
if (semi != std::string::npos) ct = ct.substr(0, semi);
while (!ct.empty() && (ct.back() == ' ' || ct.back() == '\t')) ct.pop_back();
std::size_t start = 0;
while (start < ct.size() && (ct[start] == ' ' || ct[start] == '\t')) ++start;
std::string out = ct.substr(start);
for (char& c : out) c = (char)std::tolower((unsigned char)c);
return out;
}
const std::map<std::string, std::string>& path_params() const { return path_params_; }
std::string path_param(std::string_view name) const {
auto it = path_params_.find(std::string(name));
return it == path_params_.end() ? "" : it->second;
}
void set_path_param(std::string name, std::string value) {
path_params_[std::move(name)] = std::move(value);
}
const routing::Route* route() const { return route_; }
void set_route(const routing::Route* r) { route_ = r; }
app::Application* app() const { return app_; }
void set_app(app::Application* a) { app_ = a; }
const std::string& request_id() const { return request_id_; }
void set_request_id(std::string id) { request_id_ = std::move(id); }
// Validated binding results, keyed by source ("query", "body", ...).
void set_validated(std::string source, validate::Object obj) {
validated_[std::move(source)] = std::move(obj);
}
const validate::Object* validated(std::string_view source) const {
auto it = validated_.find(std::string(source));
return it == validated_.end() ? nullptr : &it->second;
}
// Typed extension slot for middleware and DI.
template <typename T>
void set_ext(std::string key, T value) {
ext_[std::move(key)] = std::any(std::move(value));
}
template <typename T>
T* get_ext(const std::string& key) {
auto it = ext_.find(key);
if (it == ext_.end()) return nullptr;
return std::any_cast<T>(&it->second);
}
template <typename T>
const T* get_ext(const std::string& key) const {
auto it = ext_.find(key);
if (it == ext_.end()) return nullptr;
return std::any_cast<T>(&it->second);
}
void clear_ext(const std::string& key) { ext_.erase(key); }
private:
Method method_ = Method::GET;
std::string path_ = "/";
std::string query_raw_;
Query query_;
Headers headers_;
std::string body_;
Cookies cookies_;
std::map<std::string, std::string> path_params_;
const routing::Route* route_ = nullptr;
app::Application* app_ = nullptr;
std::string request_id_;
std::map<std::string, validate::Object> validated_;
std::map<std::string, std::any> ext_;
};
} // namespace molo::app::http_msg
+155
View File
@@ -0,0 +1,155 @@
#pragma once
// Spec: molo::app::http_msg::Response hierarchy (plan 05, R1, R4, E1).
// Response is a value type: status, headers, body, plus an extension payload
// for streaming and negotiated variants, so returning by value never slices.
// Subclasses only preset fields. All string-taking constructors are explicit
// (R4: no implicit conversion of a raw string to a 200 text response).
#include <any>
#include <functional>
#include <optional>
#include <string>
#include <utility>
#include <vector>
#include "../validate/json.h"
#include "../validate/value.h"
#include "headers.h"
namespace molo::app::http_msg {
class Response {
public:
explicit Response(int status = 200, std::string body = "",
std::string content_type = "text/plain; charset=utf-8")
: status_(status), body_(std::move(body)) {
headers_.set("content-type", std::move(content_type));
}
int status() const { return status_; }
void set_status(int s) { status_ = s; }
const std::string& body() const { return body_; }
void set_body(std::string b) { body_ = std::move(b); }
const Headers& headers() const { return headers_; }
Headers& headers() { return headers_; }
std::string content_type() const { return headers_.get("content-type"); }
void set_content_type(std::string ct) { headers_.set("content-type", std::move(ct)); }
template <typename T>
void set_payload(T value) {
payload_ = std::any(std::move(value));
}
template <typename T>
T* get_payload() {
return std::any_cast<T>(&payload_);
}
template <typename T>
const T* get_payload() const {
return std::any_cast<T>(&payload_);
}
bool has_payload() const { return payload_.has_value(); }
protected:
int status_ = 200;
Headers headers_;
std::string body_;
std::any payload_;
};
class TextResponse : public Response {
public:
explicit TextResponse(std::string body, int status = 200)
: Response(status, std::move(body), "text/plain; charset=utf-8") {}
};
class HtmlResponse : public Response {
public:
explicit HtmlResponse(std::string body, int status = 200)
: Response(status, std::move(body), "text/html; charset=utf-8") {}
};
class XmlResponse : public Response {
public:
explicit XmlResponse(std::string body, int status = 200)
: Response(status, std::move(body), "application/xml; charset=utf-8") {}
};
class JsonResponse : public Response {
public:
explicit JsonResponse(validate::Value value, int status = 200)
: Response(status, validate::to_json(value), "application/json") {}
explicit JsonResponse(std::string raw_json, int status = 200)
: Response(status, std::move(raw_json), "application/json") {}
};
class RedirectResponse : public Response {
public:
// Method-preserving redirects: 308 permanent, 307 temporary.
explicit RedirectResponse(std::string url, bool permanent = false)
: Response(permanent ? 308 : 307, "") {
headers_.set("location", std::move(url));
}
static RedirectResponse temporary(std::string url) { return RedirectResponse(std::move(url), false); }
static RedirectResponse permanent(std::string url) { return RedirectResponse(std::move(url), true); }
};
class FileResponse : public Response {
public:
explicit FileResponse(std::string content, std::string content_type,
std::string filename = "", int status = 200)
: Response(status, std::move(content), std::move(content_type)) {
if (!filename.empty()) {
headers_.set("content-disposition", "attachment; filename=\"" + filename + "\"");
}
headers_.set("accept-ranges", "bytes");
}
};
// Streaming shell: chunk mechanics live in 06-realtime; the class shell
// lives here (plan 05, section 3). The producer returns the next chunk or
// nullopt when done. collect() materializes with a byte cap.
struct StreamPayload {
std::function<std::optional<std::string>()> producer;
};
class StreamingResponse : public Response {
public:
explicit StreamingResponse(std::function<std::optional<std::string>()> producer,
std::string content_type = "text/plain; charset=utf-8",
int status = 200)
: Response(status, "", std::move(content_type)) {
set_payload(StreamPayload{std::move(producer)});
}
std::string collect(std::size_t max_bytes) {
auto* p = get_payload<StreamPayload>();
if (p == nullptr) return body_;
std::string out;
while (true) {
std::optional<std::string> chunk = p->producer();
if (!chunk.has_value()) break;
if (out.size() + chunk->size() > max_bytes) break;
out += *chunk;
}
return out;
}
};
// Negotiated variant: holds one data value plus the media types the route
// can render it as. NegotiationMiddleware (molo::app::middleware) replaces
// the body and content type with the negotiated representation, or answers
// 406 when nothing matches. Concrete responses pass through untouched.
struct VariantPayload {
validate::Value data;
std::vector<std::string> available;
};
class VariantResponse : public Response {
public:
explicit VariantResponse(validate::Value data, std::vector<std::string> available)
: Response(200, "") {
set_payload(VariantPayload{std::move(data), std::move(available)});
}
};
} // namespace molo::app::http_msg
+92
View File
@@ -0,0 +1,92 @@
#pragma once
// Spec: molo::app::middleware built-ins (plan 05, section 6 Middleware).
// ExceptionMappingMiddleware (outermost, category Errors) converts thrown
// errors to rendered responses. NegotiationMiddleware (RouterAdjacent)
// enforces consumes (415) and renders VariantResponse in the negotiated
// format (406 when nothing matches). CORS policy belongs to 03-security;
// these layers only preserve headers they do not own.
#include <memory>
#include <string>
#include <utility>
#include <vector>
#include "../async/task.h"
#include "../errors/handler.h"
#include "../errors/http_error.h"
#include "../http_msg/request.h"
#include "../http_msg/response.h"
#include "../negotiate/negotiator.h"
#include "../routing/route.h"
#include "../seams/request_id.h"
#include "middleware.h"
namespace molo::app::middleware {
class ExceptionMappingMiddleware : public Middleware {
public:
explicit ExceptionMappingMiddleware(
std::shared_ptr<errors::ErrorHandler> handler = std::make_shared<errors::ErrorHandler>())
: handler_(std::move(handler)) {}
Category category() const override { return Category::Errors; }
std::string name() const override { return "exception_mapping"; }
async::Task<http_msg::Response> handle(http_msg::Request& req, Next next) override {
std::string rid = req.request_id().empty() ? seams::generate_request_id() : req.request_id();
try {
http_msg::Response res = co_await next(req);
res.headers().set(seams::kRequestIdHeader, rid);
co_return res;
} catch (const errors::HttpError& e) {
http_msg::Response res = handler_->render(e, req, rid);
res.headers().set(seams::kRequestIdHeader, rid);
co_return res;
} catch (const validate::ValidationError& e) {
errors::ValidationFailed wrapped(e);
http_msg::Response res = handler_->render(wrapped, req, rid);
res.headers().set(seams::kRequestIdHeader, rid);
co_return res;
} catch (const std::exception& e) {
http_msg::Response res = handler_->render_unknown(req, rid, e.what());
res.headers().set(seams::kRequestIdHeader, rid);
co_return res;
} catch (...) {
http_msg::Response res = handler_->render_unknown(req, rid, "non-standard exception");
res.headers().set(seams::kRequestIdHeader, rid);
co_return res;
}
}
private:
std::shared_ptr<errors::ErrorHandler> handler_;
};
class NegotiationMiddleware : public Middleware {
public:
Category category() const override { return Category::RouterAdjacent; }
std::string name() const override { return "negotiation"; }
async::Task<http_msg::Response> handle(http_msg::Request& req, Next next) override {
const routing::Route* route = req.route();
if (route == nullptr) {
co_return co_await next(req);
}
negotiate::Negotiator::check_consumes(req.content_type(), route->options().consumes);
http_msg::Response res = co_await next(req);
auto* variant = res.get_payload<http_msg::VariantPayload>();
if (variant == nullptr) co_return res;
std::vector<std::string> produces = route->options().produces;
if (produces.empty()) produces = variant->available;
if (produces.empty()) produces = {"application/json"};
std::string chosen = negotiate::Negotiator::select(
req.headers().get("accept"), produces, route->options().allow_format_override,
req.query().get_first("format"));
auto rendered = negotiate::render_variant(variant->data, chosen);
res.set_body(std::move(rendered.first));
res.set_content_type(std::move(rendered.second));
co_return res;
}
};
} // namespace molo::app::middleware
+63
View File
@@ -0,0 +1,63 @@
#pragma once
// Spec: molo::app::middleware::Chain. Composes middleware in registration
// order around a terminal handler. Category order is enforced at use():
// adding a layer with a lower category than the previous one throws
// ChainOrderError (startup error, R7). Layer count capped at 64.
#include <functional>
#include <memory>
#include <stdexcept>
#include <string>
#include <vector>
#include "../async/task.h"
#include "../caps.h"
#include "../http_msg/request.h"
#include "../http_msg/response.h"
#include "middleware.h"
namespace molo::app::middleware {
class ChainOrderError : public std::runtime_error {
public:
explicit ChainOrderError(const std::string& msg) : std::runtime_error(msg) {}
};
class Chain {
public:
void use(std::shared_ptr<Middleware> layer) {
if (layers_.size() >= caps::kMaxMiddlewareLayers) {
throw ChainOrderError("too many middleware layers");
}
if (!layers_.empty() && layer->category() < layers_.back()->category()) {
throw ChainOrderError(
"middleware order violation: '" + layer->name() + "' (" +
category_name(layer->category()) + ") registered after '" +
layers_.back()->name() + "' (" + category_name(layers_.back()->category()) + ")");
}
layers_.push_back(std::move(layer));
}
async::Task<http_msg::Response> run(
http_msg::Request& req,
std::function<async::Task<http_msg::Response>(http_msg::Request&)> terminal) {
std::function<async::Task<http_msg::Response>(http_msg::Request&)> next = terminal;
for (std::size_t i = layers_.size(); i-- > 0;) {
std::shared_ptr<Middleware> layer = layers_[i];
auto inner = next;
next = [layer, inner](http_msg::Request& r) -> async::Task<http_msg::Response> {
Next guard(inner);
co_return co_await layer->handle(r, guard);
};
}
co_return co_await next(req);
}
const std::vector<std::shared_ptr<Middleware>>& layers() const { return layers_; }
std::size_t size() const { return layers_.size(); }
private:
std::vector<std::shared_ptr<Middleware>> layers_;
};
} // namespace molo::app::middleware
+69
View File
@@ -0,0 +1,69 @@
#pragma once
// Spec: molo::app::middleware base (plan 05, R7, E8). Signature:
// Task<Response> handle(Request, Next). Next invokes the remainder exactly
// once; calling twice throws MiddlewareError. Category order is fixed:
// Errors, Observability, Security, SessionAuth, User, RouterAdjacent.
// Middleware must preserve the correlation/request ID.
#include <functional>
#include <memory>
#include <stdexcept>
#include <string>
#include "../async/task.h"
#include "../http_msg/request.h"
#include "../http_msg/response.h"
namespace molo::app::middleware {
enum class Category {
Errors = 0,
Observability = 1,
Security = 2,
SessionAuth = 3,
User = 4,
RouterAdjacent = 5
};
inline std::string category_name(Category c) {
switch (c) {
case Category::Errors: return "errors";
case Category::Observability: return "observability";
case Category::Security: return "security";
case Category::SessionAuth: return "session_auth";
case Category::User: return "user";
case Category::RouterAdjacent: return "router_adjacent";
}
return "user";
}
class MiddlewareError : public std::runtime_error {
public:
explicit MiddlewareError(const std::string& msg) : std::runtime_error(msg) {}
};
class Next {
public:
explicit Next(std::function<async::Task<http_msg::Response>(http_msg::Request&)> fn)
: fn_(std::move(fn)), called_(std::make_shared<bool>(false)) {}
async::Task<http_msg::Response> operator()(http_msg::Request& req) const {
if (*called_) throw MiddlewareError("Next invoked twice in one middleware");
*called_ = true;
co_return co_await fn_(req);
}
private:
std::function<async::Task<http_msg::Response>(http_msg::Request&)> fn_;
std::shared_ptr<bool> called_;
};
class Middleware {
public:
virtual ~Middleware() = default;
virtual Category category() const = 0;
virtual std::string name() const = 0;
virtual async::Task<http_msg::Response> handle(http_msg::Request& req, Next next) = 0;
};
} // namespace molo::app::middleware
+98
View File
@@ -0,0 +1,98 @@
#pragma once
// Spec: molo::app::negotiate Accept parser. Parses an Accept header into
// media ranges (type, subtype, q, params). Missing or empty header means
// */*. Invalid q values are treated as weight 0 (entry ignored), documented
// leniency choice. Range params other than q are parsed and ignored for
// matching (documented gap vs RFC 9110 section 12).
#include <cctype>
#include <string>
#include <string_view>
#include <utility>
#include <vector>
namespace molo::app::negotiate {
struct MediaRange {
std::string type;
std::string subtype;
double q = 1.0;
std::vector<std::pair<std::string, std::string>> params;
std::size_t order = 0;
};
inline std::string trim_ws(std::string_view s) {
std::size_t a = 0;
while (a < s.size() && (s[a] == ' ' || s[a] == '\t')) ++a;
std::size_t b = s.size();
while (b > a && (s[b - 1] == ' ' || s[b - 1] == '\t')) --b;
std::string out(s.substr(a, b - a));
for (char& c : out) c = (char)std::tolower((unsigned char)c);
return out;
}
inline double parse_q(std::string_view s) {
if (s.empty() || s.size() > 5) return 0.0;
try {
std::size_t used = 0;
double v = std::stod(std::string(s), &used);
if (used != s.size() || v < 0.0 || v > 1.0) return 0.0;
return v;
} catch (...) {
return 0.0;
}
}
inline std::vector<MediaRange> parse_accept(std::string_view header) {
std::vector<MediaRange> out;
if (trim_ws(header).empty()) {
out.push_back(MediaRange{"*", "*", 1.0, {}, 0});
return out;
}
std::size_t i = 0;
std::size_t order = 0;
while (i <= header.size()) {
std::size_t comma = header.find(',', i);
if (comma == std::string_view::npos) comma = header.size();
std::string_view entry = header.substr(i, comma - i);
std::size_t semi = entry.find(';');
std::string_view full = (semi == std::string_view::npos) ? entry : entry.substr(0, semi);
std::size_t slash = full.find('/');
if (slash != std::string_view::npos) {
MediaRange range;
range.type = trim_ws(full.substr(0, slash));
range.subtype = trim_ws(full.substr(slash + 1));
range.order = order++;
if (!range.type.empty() && !range.subtype.empty()) {
if (semi != std::string_view::npos) {
std::string_view rest = entry.substr(semi + 1);
std::size_t j = 0;
while (j <= rest.size()) {
std::size_t s2 = rest.find(';', j);
if (s2 == std::string_view::npos) s2 = rest.size();
std::string_view kv = rest.substr(j, s2 - j);
std::size_t eq = kv.find('=');
if (eq != std::string_view::npos) {
std::string k = trim_ws(kv.substr(0, eq));
std::string v = trim_ws(kv.substr(eq + 1));
if (k == "q") {
range.q = parse_q(v);
} else {
range.params.emplace_back(k, v);
}
}
if (s2 == rest.size()) break;
j = s2 + 1;
}
}
out.push_back(std::move(range));
}
}
if (comma == header.size()) break;
i = comma + 1;
}
if (out.empty()) out.push_back(MediaRange{"*", "*", 1.0, {}, 0});
return out;
}
} // namespace molo::app::negotiate
+137
View File
@@ -0,0 +1,137 @@
#pragma once
// Spec: molo::app::negotiate::Negotiator (plan 05, R6, E6). Server-driven
// content negotiation: sorts Accept ranges by q desc, then specificity
// (exact beats type star beats star star), then Accept order; matches
// against handler-declared produces in declaration order. Explicit ?format=
// or suffix override applies only when the route sets allow_format_override
// (Q2 answer: off by default). No match throws NotAcceptable carrying the
// available list. Consumes check throws UnsupportedMediaType (415).
#include <algorithm>
#include <string>
#include <string_view>
#include <utility>
#include <vector>
#include "../errors/http_error.h"
#include "../http_msg/html.h"
#include "../validate/json.h"
#include "../validate/value.h"
#include "accept.h"
namespace molo::app::negotiate {
inline int range_specificity(const MediaRange& r) {
if (r.type == "*" && r.subtype == "*") return 0;
if (r.subtype == "*") return 1;
return 2;
}
inline bool range_matches(const MediaRange& r, std::string_view candidate) {
std::size_t slash = candidate.find('/');
if (slash == std::string_view::npos) return false;
std::string_view ct = candidate.substr(0, slash);
std::string_view cs = candidate.substr(slash + 1);
if (r.type != "*" && r.type != ct) return false;
if (r.subtype != "*" && r.subtype != cs) return false;
return true;
}
inline std::string format_name_to_media(std::string_view name) {
std::string low(name);
for (char& c : low) c = (char)std::tolower((unsigned char)c);
if (low == "json") return "application/json";
if (low == "html") return "text/html";
if (low == "xml") return "application/xml";
if (low == "text" || low == "txt") return "text/plain";
return "";
}
class Negotiator {
public:
static std::string select(std::string_view accept_header,
const std::vector<std::string>& produces,
bool allow_format_override = false,
std::string_view format_param = "") {
if (produces.empty()) return "";
if (allow_format_override && !format_param.empty()) {
std::string mapped = format_name_to_media(format_param);
for (const auto& p : produces) {
if (p == mapped) return p;
}
throw errors::NotAcceptable(produces);
}
std::vector<MediaRange> ranges = parse_accept(accept_header);
std::sort(ranges.begin(), ranges.end(), [](const MediaRange& a, const MediaRange& b) {
if (a.q != b.q) return a.q > b.q;
int sa = range_specificity(a);
int sb = range_specificity(b);
if (sa != sb) return sa > sb;
return a.order < b.order;
});
for (const MediaRange& r : ranges) {
if (r.q <= 0.0) continue;
for (const auto& p : produces) {
if (range_matches(r, p)) return p;
}
}
throw errors::NotAcceptable(produces);
}
static void check_consumes(std::string_view content_type,
const std::vector<std::string>& consumes) {
if (consumes.empty()) return;
for (const auto& c : consumes) {
if (c == content_type) return;
}
throw errors::UnsupportedMediaType("content type not consumed by this route");
}
};
// Render one data value into a concrete (body, content type) pair for the
// negotiated media type. Used by NegotiationMiddleware for VariantResponse.
inline std::pair<std::string, std::string> render_variant(const validate::Value& data,
std::string_view media) {
if (media == "application/json") {
return {validate::to_json(data), "application/json"};
}
if (media == "application/xml") {
std::string body = "<?xml version=\"1.0\" encoding=\"utf-8\"?><value>";
if (const auto* o = std::get_if<validate::Object>(&data.storage())) {
for (const auto& kv : *o) {
body += "<" + kv.first + ">" + http_msg::escape_xml(validate::to_json(kv.second)) +
"</" + kv.first + ">";
}
} else {
body += http_msg::escape_xml(validate::to_json(data));
}
body += "</value>";
return {body, "application/xml; charset=utf-8"};
}
if (media == "text/html") {
std::string rows;
if (const auto* o = std::get_if<validate::Object>(&data.storage())) {
for (const auto& kv : *o) {
rows += "<tr><th>" + http_msg::escape_html(kv.first) + "</th><td>" +
http_msg::escape_html(validate::to_json(kv.second)) + "</td></tr>";
}
} else {
rows = "<tr><td>" + http_msg::escape_html(validate::to_json(data)) + "</td></tr>";
}
std::string body =
"<!DOCTYPE html><html lang=\"en\"><head><meta charset=\"utf-8\">"
"<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">"
"<title>response</title><style>"
"body{font-family:system-ui,sans-serif;margin:1rem}"
"table{border-collapse:collapse;max-width:100%}"
"th,td{border:1px solid #ccc;padding:.4rem .6rem;text-align:left}"
"@media (max-width:40rem){table{width:100%}}</style>"
"</head><body><table>" +
rows + "</table></body></html>";
return {body, "text/html; charset=utf-8"};
}
std::string text = data.is_string() ? data.as_text() : validate::to_json(data);
return {text, "text/plain; charset=utf-8"};
}
} // namespace molo::app::negotiate
+227
View File
@@ -0,0 +1,227 @@
#pragma once
// Spec: molo::app::routing path compiler (plan 05, section 6 Route matching).
// Path syntax: /users/{id:int} with converters int, float, str (single
// segment), path (remainder, must be last). Unknown converter is a startup
// error naming the route. Trailing slash is strict.
#include <cctype>
#include <map>
#include <optional>
#include <stdexcept>
#include <string>
#include <string_view>
#include <utility>
#include <vector>
#include "../caps.h"
#include "../errors/http_error.h"
#include "../validate/errors.h"
namespace molo::app::routing {
class PathCompileError : public std::runtime_error {
public:
explicit PathCompileError(const std::string& msg) : std::runtime_error(msg) {}
};
enum class Converter { Int, Float, Str, Path };
struct Segment {
bool is_param = false;
std::string literal;
std::string name;
Converter converter = Converter::Str;
};
struct CompiledPath {
std::vector<Segment> segments;
bool has_catchall = false;
std::size_t static_count = 0;
};
inline std::vector<std::string> split_path(std::string_view path) {
std::vector<std::string> out;
std::size_t i = 0;
if (!path.empty() && path[0] == '/') i = 1;
while (true) {
std::size_t slash = path.find('/', i);
if (slash == std::string_view::npos) {
out.emplace_back(path.substr(i));
break;
}
out.emplace_back(path.substr(i, slash - i));
i = slash + 1;
}
return out;
}
inline CompiledPath compile_path(std::string_view pattern, std::string_view route_label) {
if (pattern.empty() || pattern[0] != '/') {
throw PathCompileError("route '" + std::string(route_label) + "': pattern must start with /");
}
CompiledPath out;
std::vector<std::string> parts = split_path(pattern);
std::size_t param_count = 0;
for (std::size_t idx = 0; idx < parts.size(); ++idx) {
const std::string& part = parts[idx];
if (part.size() >= 2 && part.front() == '{' && part.back() == '}') {
std::string inner = part.substr(1, part.size() - 2);
std::string name = inner;
std::string conv = "str";
std::size_t colon = inner.find(':');
if (colon != std::string::npos) {
name = inner.substr(0, colon);
conv = inner.substr(colon + 1);
}
if (name.empty()) {
throw PathCompileError("route '" + std::string(route_label) + "': empty param name");
}
Segment seg;
seg.is_param = true;
seg.name = name;
if (conv == "int") {
seg.converter = Converter::Int;
} else if (conv == "float") {
seg.converter = Converter::Float;
} else if (conv == "str") {
seg.converter = Converter::Str;
} else if (conv == "path") {
seg.converter = Converter::Path;
if (idx != parts.size() - 1) {
throw PathCompileError("route '" + std::string(route_label) +
"': path converter must be last");
}
out.has_catchall = true;
} else {
throw PathCompileError("route '" + std::string(route_label) + "': unknown converter '" +
conv + "'");
}
++param_count;
if (param_count > caps::kMaxPathParamsPerRoute) {
throw PathCompileError("route '" + std::string(route_label) + "': too many path params");
}
out.segments.push_back(std::move(seg));
} else {
Segment seg;
seg.literal = part;
out.segments.push_back(std::move(seg));
++out.static_count;
}
}
return out;
}
inline bool strict_int(std::string_view s) {
if (s.empty()) return false;
std::size_t i = 0;
if (s[0] == '+' || s[0] == '-') i = 1;
if (i == s.size()) return false;
for (std::size_t j = i; j < s.size(); ++j) {
if (!std::isdigit((unsigned char)s[j])) return false;
}
return true;
}
inline bool strict_float(std::string_view s) {
if (s.empty()) return false;
try {
std::size_t used = 0;
std::stod(std::string(s), &used);
return used == s.size();
} catch (...) {
return false;
}
}
struct PathMatch {
bool full = false;
bool skeleton = false;
std::map<std::string, std::string> params;
std::vector<validate::FieldFailure> errors;
};
inline PathMatch match_compiled(const CompiledPath& cp, std::string_view path) {
PathMatch m;
if (path.empty() || path[0] != '/') return m;
std::vector<std::string> parts = split_path(path);
std::size_t need = cp.segments.size();
bool count_ok = cp.has_catchall ? (parts.size() >= need - 1) : (parts.size() == need);
// Skeleton pass: converters match any single segment, catch-all the rest.
bool skeleton = count_ok;
if (skeleton) {
for (std::size_t i = 0; i < cp.segments.size() && skeleton; ++i) {
const Segment& seg = cp.segments[i];
if (seg.is_param) {
if (seg.converter == Converter::Path) break;
continue;
}
if (i >= parts.size() || parts[i] != seg.literal) skeleton = false;
}
}
m.skeleton = skeleton;
if (!skeleton) return m;
// Full pass with converter checks.
for (std::size_t i = 0; i < cp.segments.size(); ++i) {
const Segment& seg = cp.segments[i];
if (!seg.is_param) continue;
if (seg.converter == Converter::Path) {
std::string rest;
for (std::size_t j = i; j < parts.size(); ++j) {
if (j > i) rest += '/';
rest += parts[j];
}
m.params[seg.name] = rest;
break;
}
const std::string& raw = parts[i];
if (seg.converter == Converter::Str) {
if (raw.empty()) {
m.errors.push_back({{"path", seg.name}, "empty path segment", "string_type"});
return m;
}
m.params[seg.name] = raw;
} else if (seg.converter == Converter::Int) {
if (!strict_int(raw)) {
m.errors.push_back({{"path", seg.name}, "invalid integer", "int_parsing"});
return m;
}
m.params[seg.name] = raw;
} else if (seg.converter == Converter::Float) {
if (!strict_float(raw)) {
m.errors.push_back({{"path", seg.name}, "invalid number", "float_parsing"});
return m;
}
m.params[seg.name] = raw;
}
}
m.full = true;
return m;
}
inline std::string render_compiled(const CompiledPath& cp,
const std::map<std::string, std::string>& params,
std::string_view route_name) {
std::string out;
for (const Segment& seg : cp.segments) {
out += '/';
if (!seg.is_param) {
out += seg.literal;
} else {
auto it = params.find(seg.name);
if (it == params.end()) {
throw errors::NotFound("url_for: route '" + std::string(route_name) +
"' missing param '" + seg.name + "'");
}
out += it->second;
}
}
if (out.empty()) out = "/";
// Collapse the "/"+"" root case back to "/".
if (out.size() > 1 && out.back() == '/' && cp.segments.size() == 1 &&
!cp.segments[0].is_param && cp.segments[0].literal.empty()) {
out = "/";
}
return out;
}
} // namespace molo::app::routing
+113
View File
@@ -0,0 +1,113 @@
#pragma once
// Spec: molo::app::routing::Route. One route record: methods, compiled path,
// handler, name, tags, validation models, negotiation declarations,
// slash policy (plan 05, section 3). Handler takes Request and returns
// Task<Response> (R1). slash_insensitive registers the declared route plus a
// companion 308 redirect route for the alternate trailing-slash form.
#include <functional>
#include <memory>
#include <set>
#include <string>
#include <utility>
#include <vector>
#include "../async/task.h"
#include "../caps.h"
#include "../http_msg/method.h"
#include "../http_msg/request.h"
#include "../http_msg/response.h"
#include "../validate/model.h"
#include "path_compiler.h"
namespace molo::app::routing {
using Handler = std::function<async::Task<http_msg::Response>(http_msg::Request&)>;
struct RouteOptions {
std::string name;
std::vector<std::string> tags;
std::vector<std::string> produces;
std::vector<std::string> consumes;
bool allow_format_override = false;
bool slash_insensitive = false;
std::size_t max_body = caps::kMaxJsonDocument;
// Governance (molo::govern): auth and lifecycle for this route.
enum class GovAuth { kNone, kKey, kKeyScopes, kSession };
GovAuth gov_auth = GovAuth::kNone;
std::vector<std::string> gov_required_scopes;
int gov_api_version = 0; // 0 = derived from the /v{n} prefix
long gov_deprecation_unix = 0;
std::string gov_sunset_httpdate;
std::string gov_tier_override; // "", "free", "pro", "enterprise"
bool gov_has_summary = false;
bool gov_has_example = false;
std::shared_ptr<validate::Model> query_model;
std::shared_ptr<validate::Model> body_model;
std::shared_ptr<validate::Model> header_model;
std::shared_ptr<validate::Model> cookie_model;
// Internal: non-empty on slash-redirect companions (target declared path).
std::string redirect_target;
};
class Route {
public:
Route(std::set<http_msg::Method> methods, std::string pattern, Handler handler,
RouteOptions options = {}, std::size_t index = 0)
: methods_(std::move(methods)),
pattern_(std::move(pattern)),
handler_(std::move(handler)),
options_(std::move(options)),
index_(index) {
if (options_.name.size() > caps::kMaxRouteName) {
throw PathCompileError("route name too long: " + options_.name);
}
compiled_ = compile_path(pattern_, options_.name.empty() ? pattern_ : options_.name);
}
const std::set<http_msg::Method>& methods() const { return methods_; }
const std::string& pattern() const { return pattern_; }
const CompiledPath& compiled() const { return compiled_; }
const Handler& handler() const { return handler_; }
const RouteOptions& options() const { return options_; }
std::size_t index() const { return index_; }
bool is_slash_redirect() const { return !options_.redirect_target.empty(); }
bool allows(http_msg::Method m) const { return methods_.count(m) > 0; }
std::vector<std::string> allow_list() const {
std::vector<std::string> out;
for (auto m : methods_) out.push_back(http_msg::to_string(m));
return out;
}
Route with_prefix(const std::string& prefix,
const std::vector<std::string>& extra_tags) const {
std::string clean = prefix;
if (clean == "/") clean = "";
RouteOptions opts = options_;
for (const auto& t : extra_tags) opts.tags.push_back(t);
std::string new_pattern = clean + pattern_;
Handler h = handler_;
if (!opts.redirect_target.empty()) {
opts.redirect_target = clean + opts.redirect_target;
std::string target = opts.redirect_target;
h = [target](http_msg::Request& req) -> async::Task<http_msg::Response> {
std::string url = target;
if (!req.query_raw().empty()) url += "?" + req.query_raw();
co_return http_msg::RedirectResponse::permanent(url);
};
}
return Route(methods_, new_pattern, h, opts, index_);
}
private:
std::set<http_msg::Method> methods_;
std::string pattern_;
Handler handler_;
RouteOptions options_;
CompiledPath compiled_;
std::size_t index_ = 0;
};
} // namespace molo::app::routing
+319
View File
@@ -0,0 +1,319 @@
#pragma once
// Spec: molo::app::routing::Router (plan 05, E2). FastAPI-style router:
// get/post/put/patch/delete/head/options, nested include_router with prefix
// and tags, match with 404/405/422 precedence, url_for reversal.
// Match order: static segments first (more static wins), then converters in
// registration order, then path catch-alls. Precedence: full match, then
// 405 (skeleton path exists, method missing), then 422 (path converter
// failure), then 404. Method mismatch sets the Allow header.
#include <algorithm>
#include <map>
#include <set>
#include <string>
#include <utility>
#include <vector>
#include "../../governance/caps.h"
#include "../../governance/versions/ApiVersion.h"
#include "../../tenancy/resolver.h"
#include "../caps.h"
#include "../errors/http_error.h"
#include "../http_msg/method.h"
#include "../http_msg/response.h"
#include "../validate/errors.h"
#include "path_compiler.h"
#include "route.h"
namespace molo::app::routing {
namespace detail {
// Strict IMF-fixdate ("Wed, 21 Oct 2015 07:28:00 GMT") to unix seconds.
// Returns -1 when unparseable. Self-contained so router.h gains no deps.
inline long ParseImfFixdate(const std::string& text) {
if (text.size() != 29) return -1;
if (text[3] != ',' || text[4] != ' ' || text[7] != ' ' || text[11] != ' ' ||
text[16] != ' ' || text[19] != ':' || text[22] != ':' || text[25] != ' ') {
return -1;
}
if (text.compare(26, 3, "GMT") != 0) return -1;
auto digits = [&](std::size_t pos, std::size_t len, int& out) {
int v = 0;
for (std::size_t i = 0; i < len; ++i) {
char c = text[pos + i];
if (c < '0' || c > '9') return false;
v = v * 10 + (c - '0');
}
out = v;
return true;
};
int day, year, hh, mm, ss;
if (!digits(5, 2, day) || !digits(12, 4, year) || !digits(17, 2, hh) ||
!digits(20, 2, mm) || !digits(23, 2, ss)) {
return -1;
}
static const char* kMonths[] = {"Jan", "Feb", "Mar", "Apr", "May", "Jun",
"Jul", "Aug", "Sep", "Oct", "Nov", "Dec"};
int mon = 0;
for (int i = 0; i < 12; ++i) {
if (text.compare(8, 3, kMonths[i]) == 0) {
mon = i + 1;
break;
}
}
if (mon == 0 || day < 1 || day > 31 || hh > 23 || mm > 59 || ss > 60) return -1;
// Days from civil (Howard Hinnant), 1970-01-01 based.
int y = year;
unsigned m = static_cast<unsigned>(mon);
unsigned d = static_cast<unsigned>(day);
y -= (m <= 2);
const int era = (y >= 0 ? y : y - 399) / 400;
const unsigned yoe = static_cast<unsigned>(y - era * 400);
const unsigned doy = (153 * (m + (m > 2 ? -3 : 9)) + 2) / 5 + d - 1;
const unsigned doe = yoe * 365 + yoe / 4 - yoe / 100 + doy;
const long days = static_cast<long>(era) * 146097 + static_cast<long>(doe) - 719468;
return days * 86400L + hh * 3600L + mm * 60L + ss;
}
} // namespace detail
struct MatchResult {
const Route* route = nullptr;
std::map<std::string, std::string> params;
std::vector<std::string> allow;
std::vector<validate::FieldFailure> path_errors;
bool skeleton_matched = false;
};
class Router {
public:
const Route& add(std::set<http_msg::Method> methods, std::string pattern, Handler handler,
RouteOptions options = {}) {
if (frozen_) throw PathCompileError("router frozen: cannot add routes after startup");
if (routes_.size() + 1 > caps::kMaxRoutesPerApp) {
throw PathCompileError("too many routes in router");
}
std::size_t index = next_index_++;
std::size_t at = routes_.size();
routes_.emplace_back(std::move(methods), pattern, std::move(handler), options, index);
const Route& added = routes_.at(at);
if (options.slash_insensitive) {
std::string alt;
if (pattern.size() > 1 && pattern.back() == '/') {
alt = pattern.substr(0, pattern.size() - 1);
} else if (pattern == "/") {
alt = "";
} else {
alt = pattern + "/";
}
if (!alt.empty()) {
if (routes_.size() + 1 > caps::kMaxRoutesPerApp) {
throw PathCompileError("too many routes in router");
}
RouteOptions redirect_opts;
redirect_opts.redirect_target = pattern;
std::string target = pattern;
Handler redirect = [target](http_msg::Request& req)
-> async::Task<http_msg::Response> {
std::string url = target;
if (!req.query_raw().empty()) url += "?" + req.query_raw();
co_return http_msg::RedirectResponse::permanent(url);
};
routes_.emplace_back(added.methods(), alt, std::move(redirect), redirect_opts,
next_index_++);
}
}
rebuild_order();
return routes_.at(at);
}
const Route& get(std::string pattern, Handler handler, RouteOptions options = {}) {
return add({http_msg::Method::GET}, std::move(pattern), std::move(handler),
std::move(options));
}
const Route& post(std::string pattern, Handler handler, RouteOptions options = {}) {
return add({http_msg::Method::POST}, std::move(pattern), std::move(handler),
std::move(options));
}
const Route& put(std::string pattern, Handler handler, RouteOptions options = {}) {
return add({http_msg::Method::PUT}, std::move(pattern), std::move(handler),
std::move(options));
}
const Route& patch(std::string pattern, Handler handler, RouteOptions options = {}) {
return add({http_msg::Method::PATCH}, std::move(pattern), std::move(handler),
std::move(options));
}
const Route& del(std::string pattern, Handler handler, RouteOptions options = {}) {
return add({http_msg::Method::DELETE}, std::move(pattern), std::move(handler),
std::move(options));
}
const Route& head(std::string pattern, Handler handler, RouteOptions options = {}) {
return add({http_msg::Method::HEAD}, std::move(pattern), std::move(handler),
std::move(options));
}
const Route& options(std::string pattern, Handler handler, RouteOptions opts = {}) {
return add({http_msg::Method::OPTIONS}, std::move(pattern), std::move(handler),
std::move(opts));
}
void include_router(std::string prefix, const Router& other,
std::vector<std::string> extra_tags = {}) {
if (frozen_) throw PathCompileError("router frozen: cannot include after startup");
if (prefix.empty() || prefix[0] != '/') {
throw PathCompileError("include_router prefix must start with /");
}
for (const Route& r : other.routes_) {
if (routes_.size() + 1 > caps::kMaxRoutesPerApp) {
throw PathCompileError("too many routes in router");
}
Route merged = r.with_prefix(prefix, extra_tags);
routes_.emplace_back(merged.methods(), merged.pattern(), merged.handler(),
merged.options(), next_index_++);
}
rebuild_order();
}
MatchResult match(http_msg::Method method, std::string_view path) const {
if (path.size() > caps::kMaxPathLength) {
throw errors::UriTooLong("path exceeds length cap");
}
MatchResult out;
std::set<std::string> allow_set;
for (const Route* route : order_) {
PathMatch pm = match_compiled(route->compiled(), path);
if (pm.full) {
if (route->allows(method)) {
out.route = route;
out.params = std::move(pm.params);
return out;
}
out.skeleton_matched = true;
for (const auto& a : route->allow_list()) allow_set.insert(a);
continue;
}
if (pm.skeleton) {
out.skeleton_matched = true;
if (!route->allows(method)) {
for (const auto& a : route->allow_list()) allow_set.insert(a);
} else if (out.path_errors.empty() && !pm.errors.empty()) {
out.path_errors = std::move(pm.errors);
}
}
}
out.allow.assign(allow_set.begin(), allow_set.end());
return out;
}
std::string url_for(std::string_view name,
const std::map<std::string, std::string>& params = {},
std::string_view query = "") const {
for (const Route& r : routes_) {
if (r.options().name == name && !r.is_slash_redirect()) {
std::string url = render_compiled(r.compiled(), params, name);
if (!query.empty()) {
url += '?';
url += query;
}
return url;
}
}
throw errors::NotFound("url_for: unknown route '" + std::string(name) + "'");
}
bool has_route_name(std::string_view name) const {
for (const Route& r : routes_) {
if (!r.is_slash_redirect() && r.options().name == name) return true;
}
return false;
}
// Tenant-aware helpers (PATCHES 11.14): strip the /t/<slug> prefix and
// build URLs that carry the tenant.
static std::pair<std::string, std::string> strip_tenant_prefix(
const std::string& path) {
return ::molo::tenancy::Resolver::StripTenantPrefix(path);
}
std::string url_for_tenant(const std::string& tenant, std::string_view name,
const std::map<std::string, std::string>& params = {},
std::string_view query = "") const {
return "/t/" + tenant + url_for(name, params, query);
}
const std::vector<Route>& routes() const { return routes_; }
std::size_t size() const { return routes_.size(); }
// Application::startup freezes the router so match pointers stay stable.
void freeze() { frozen_ = true; }
bool frozen() const { return frozen_; }
// Governance hook: validates /v{n} prefixes, at most 3 live majors,
// Sunset >= Deprecation, and declared scopes on scoped routes. Routes
// without governance fields set are skipped. Throws std::runtime_error
// (Application::startup rethrows as StartupError).
void validate_governance() const {
std::set<int> live_majors;
for (const Route& r : routes_) {
if (r.is_slash_redirect()) continue;
const RouteOptions& o = r.options();
const bool managed = o.gov_auth != RouteOptions::GovAuth::kNone ||
o.gov_api_version != 0 || o.gov_deprecation_unix != 0 ||
!o.gov_sunset_httpdate.empty() || !o.gov_tier_override.empty();
if (!managed) continue;
const int major =
::molo::govern::versions::ApiVersion::ParseMajor(r.pattern());
if (major == 0) {
throw std::runtime_error("governance: route '" + r.pattern() +
"' is gov-managed but has no /v{n} prefix");
}
if (o.gov_api_version != 0 && o.gov_api_version != major) {
throw std::runtime_error("governance: route '" + r.pattern() +
"' gov_api_version does not match its /v{n} prefix");
}
live_majors.insert(major);
if (o.gov_auth == RouteOptions::GovAuth::kKeyScopes &&
o.gov_required_scopes.empty()) {
throw std::runtime_error("governance: route '" + r.pattern() +
"' requires scopes but declares none");
}
if (!o.gov_sunset_httpdate.empty()) {
const long sunset = detail::ParseImfFixdate(o.gov_sunset_httpdate);
if (sunset < 0) {
throw std::runtime_error("governance: route '" + r.pattern() +
"' has an unparseable gov_sunset_httpdate");
}
if (o.gov_deprecation_unix != 0 && sunset < o.gov_deprecation_unix) {
throw std::runtime_error("governance: route '" + r.pattern() +
"' sunset predates deprecation");
}
}
}
if (static_cast<int>(live_majors.size()) >
::molo::govern::Caps::kMaxLiveMajors) {
throw std::runtime_error("governance: more than 3 live API majors");
}
}
private:
void rebuild_order() {
order_.clear();
for (const Route& r : routes_) order_.push_back(&r);
std::stable_sort(order_.begin(), order_.end(), [](const Route* a, const Route* b) {
int ca = a->compiled().has_catchall ? 1 : 0;
int cb = b->compiled().has_catchall ? 1 : 0;
if (ca != cb) return ca < cb;
if (a->compiled().static_count != b->compiled().static_count) {
return a->compiled().static_count > b->compiled().static_count;
}
return a->index() < b->index();
});
}
std::vector<Route> routes_;
std::vector<const Route*> order_;
std::size_t next_index_ = 0;
bool frozen_ = false;
};
} // namespace molo::app::routing
+23
View File
@@ -0,0 +1,23 @@
#pragma once
// Spec: molo::app::seams::request_id. Correlation ID seam owned by
// 02-observability. Request ID is read from X-Request-ID when present, else
// generated. Middleware must preserve it (plan 05, section 6 Middleware).
#include <atomic>
#include <cstdint>
#include <cstdio>
#include <string>
namespace molo::app::seams {
inline std::string generate_request_id() {
static std::atomic<std::uint64_t> counter{1};
std::uint64_t n = counter.fetch_add(1, std::memory_order_relaxed);
char buf[32];
std::snprintf(buf, sizeof(buf), "req-%016llx", (unsigned long long)n);
return std::string(buf);
}
inline constexpr const char* kRequestIdHeader = "X-Request-ID";
} // namespace molo::app::seams
+62
View File
@@ -0,0 +1,62 @@
#pragma once
// Spec: molo::app::seams::session. Session storage seam owned by
// 03-security. The app layer (flash messages, views) programs against
// SessionStore only. InMemorySessionStore is the standalone default so this
// part compiles and tests without siblings; production wires the security
// store through Application::set_session_store.
#include <map>
#include <memory>
#include <mutex>
#include <string>
#include <vector>
#include "../caps.h"
namespace molo::app::seams {
struct FlashMessage {
std::string level;
std::string text;
};
class SessionStore {
public:
virtual ~SessionStore() = default;
virtual void add_flash(const std::string& session_id, FlashMessage msg) = 0;
virtual std::vector<FlashMessage> take_flashes(const std::string& session_id) = 0;
virtual void clear(const std::string& session_id) = 0;
};
class InMemorySessionStore : public SessionStore {
public:
void add_flash(const std::string& session_id, FlashMessage msg) override {
std::lock_guard<std::mutex> lock(mutex_);
auto& vec = flashes_[session_id];
if (vec.size() < caps::kMaxFlashMessages) vec.push_back(std::move(msg));
}
std::vector<FlashMessage> take_flashes(const std::string& session_id) override {
std::lock_guard<std::mutex> lock(mutex_);
auto it = flashes_.find(session_id);
if (it == flashes_.end()) return {};
std::vector<FlashMessage> out = std::move(it->second);
flashes_.erase(it);
return out;
}
void clear(const std::string& session_id) override {
std::lock_guard<std::mutex> lock(mutex_);
flashes_.erase(session_id);
}
private:
std::mutex mutex_;
std::map<std::string, std::vector<FlashMessage>> flashes_;
};
inline std::shared_ptr<SessionStore> default_session_store() {
return std::make_shared<InMemorySessionStore>();
}
} // namespace molo::app::seams
+116
View File
@@ -0,0 +1,116 @@
#pragma once
// Spec: molo::app::templates AST. Plain data nodes built by the parser,
// executed by the renderer. Expressions cover literals, names, attribute
// and index access, calls, arithmetic, comparisons, logic, membership,
// filters and tests. Gaps vs Jinja (documented): no ternary, no ** power,
// no string % formatting, no super(), no block-level set.
#include <cstdint>
#include <memory>
#include <optional>
#include <string>
#include <utility>
#include <vector>
#include "../validate/value.h"
namespace molo::app::templates {
struct Expr;
using ExprPtr = std::shared_ptr<Expr>;
struct Expr {
enum class Kind {
Literal,
Name,
Attr,
Index,
Call,
Unary,
Binary,
Compare,
BoolOp,
Not,
In,
Filter,
Test,
List,
Dict
};
Kind kind = Kind::Literal;
validate::Value literal;
std::string name; // Name, Attr attribute, Call callee, Filter/Test name
ExprPtr left;
ExprPtr right;
ExprPtr operand;
ExprPtr seq; // In: left in seq
std::string op;
bool negated = false; // In (not in), Test (is not)
std::vector<ExprPtr> args;
std::vector<std::pair<std::string, ExprPtr>> kwargs;
std::vector<std::pair<ExprPtr, ExprPtr>> pairs; // Dict
};
struct Node;
using NodePtr = std::shared_ptr<Node>;
struct IfBranch {
ExprPtr cond; // null cond means else
std::vector<NodePtr> body;
};
struct Node {
enum class Kind {
Text,
Output,
If,
For,
Block,
Extends,
Include,
Set,
Macro,
Autoescape
};
Kind kind = Kind::Text;
std::string text; // Text content, Block/Macro/Set name
ExprPtr expr; // Output, Extends, Include, Set value
std::vector<IfBranch> branches; // If
std::vector<std::string> targets; // For
ExprPtr seq; // For
std::vector<NodePtr> body; // For, Block, Macro, Autoescape
std::vector<NodePtr> else_body; // For
std::vector<std::string> params; // Macro
std::vector<std::optional<validate::Value>> defaults; // Macro
bool flag = false; // Autoescape enabled
};
struct MacroDef {
std::string name;
std::vector<std::string> params;
std::vector<std::optional<validate::Value>> defaults;
std::vector<NodePtr> body;
};
inline ExprPtr lit(validate::Value v) {
ExprPtr e = std::make_shared<Expr>();
e->kind = Expr::Kind::Literal;
e->literal = std::move(v);
return e;
}
inline ExprPtr name_expr(std::string n) {
ExprPtr e = std::make_shared<Expr>();
e->kind = Expr::Kind::Name;
e->name = std::move(n);
return e;
}
inline NodePtr text_node(std::string t) {
NodePtr n = std::make_shared<Node>();
n->kind = Node::Kind::Text;
n->text = std::move(t);
return n;
}
} // namespace molo::app::templates
+62
View File
@@ -0,0 +1,62 @@
#pragma once
// Spec: molo::app::templates compiled-template cache. LRU with max 512
// entries (caps.h). Keyed by template name.
#include <list>
#include <map>
#include <memory>
#include <string>
#include <utility>
#include <vector>
#include "../caps.h"
#include "ast.h"
namespace molo::app::templates {
struct CompiledTemplate {
std::string name;
std::vector<NodePtr> nodes;
bool autoescape = false;
};
class TemplateCache {
public:
std::shared_ptr<CompiledTemplate> get(const std::string& name) {
auto it = entries_.find(name);
if (it == entries_.end()) return nullptr;
order_.erase(it->second.second);
order_.push_front(name);
it->second.second = order_.begin();
return it->second.first;
}
void put(std::string name, std::shared_ptr<CompiledTemplate> compiled) {
auto it = entries_.find(name);
if (it != entries_.end()) {
order_.erase(it->second.second);
entries_.erase(it);
}
order_.push_front(name);
entries_[name] = {std::move(compiled), order_.begin()};
while (entries_.size() > caps::kMaxCompiledTemplates) {
entries_.erase(order_.back());
order_.pop_back();
}
}
void clear() {
entries_.clear();
order_.clear();
}
std::size_t size() const { return entries_.size(); }
private:
std::map<std::string, std::pair<std::shared_ptr<CompiledTemplate>,
std::list<std::string>::iterator>>
entries_;
std::list<std::string> order_;
};
} // namespace molo::app::templates
+66
View File
@@ -0,0 +1,66 @@
#pragma once
// Spec: molo::app::templates::Context. Lexical scopes for rendering: a stack
// of variable scopes plus macro definitions. set writes the innermost
// scope; loops, includes and macro calls push and pop.
#include <map>
#include <memory>
#include <string>
#include <vector>
#include "../validate/value.h"
#include "ast.h"
namespace molo::app::templates {
struct Scope {
validate::Object vars;
std::map<std::string, std::shared_ptr<MacroDef>> macros;
};
class Context {
public:
Context() { scopes_.emplace_back(); }
explicit Context(validate::Object globals) {
Scope root;
root.vars = std::move(globals);
scopes_.push_back(std::move(root));
}
void push() { scopes_.emplace_back(); }
void pop() {
if (scopes_.size() > 1) scopes_.pop_back();
}
void set(const std::string& name, validate::Value value) {
scopes_.back().vars[name] = std::move(value);
}
void define_macro(std::shared_ptr<MacroDef> macro) {
scopes_.back().macros[macro->name] = std::move(macro);
}
validate::Value lookup(const std::string& name) const {
for (std::size_t i = scopes_.size(); i-- > 0;) {
auto it = scopes_[i].vars.find(name);
if (it != scopes_[i].vars.end()) return it->second;
}
return validate::Value::undefined();
}
std::shared_ptr<MacroDef> lookup_macro(const std::string& name) const {
for (std::size_t i = scopes_.size(); i-- > 0;) {
auto it = scopes_[i].macros.find(name);
if (it != scopes_[i].macros.end()) return it->second;
}
return nullptr;
}
const std::vector<Scope>& scopes() const { return scopes_; }
private:
std::vector<Scope> scopes_;
};
} // namespace molo::app::templates
+129
View File
@@ -0,0 +1,129 @@
#pragma once
// Spec: molo::app::templates::Environment. Reusable template environment
// holding loaders, filters, tests and globals (plan 05, E11). Autoescape is
// ON for .html, .htm, .xml; there is deliberately no global disable flag
// (R5). Undefined policy defaults to Strict (dev default per spec); Chain
// renders empty plus a stats counter. dev_reload bypasses the compiled
// cache so disk edits show on the next render.
#include <cctype>
#include <map>
#include <memory>
#include <string>
#include <utility>
#include <vector>
#include "../caps.h"
#include "../validate/value.h"
#include "cache.h"
#include "filters.h"
#include "lexer.h"
#include "loaders.h"
#include "parser.h"
#include "predicates.h"
namespace molo::app::templates {
class Renderer;
enum class UndefinedPolicy { Chain, Strict };
struct TemplateStats {
std::size_t renders = 0;
std::size_t cache_hits = 0;
std::size_t undefined_hits = 0;
std::size_t errors = 0;
};
class Environment {
public:
Environment() : filters_(builtin_filters()), tests_(builtin_tests()) {}
void add_loader(std::shared_ptr<Loader> loader) { loaders_.push_back(std::move(loader)); }
void set_global(const std::string& name, validate::Value value) {
globals_[name] = std::move(value);
}
void add_filter(const std::string& name, FilterFn fn) { filters_[name] = std::move(fn); }
void add_test(const std::string& name, TestFn fn) { tests_[name] = std::move(fn); }
void set_undefined_policy(UndefinedPolicy p) { undefined_policy_ = p; }
UndefinedPolicy undefined_policy() const { return undefined_policy_; }
void set_dev_reload(bool on) { dev_reload_ = on; }
bool dev_reload() const { return dev_reload_; }
const validate::Object& globals() const { return globals_; }
const std::map<std::string, FilterFn>& filters() const { return filters_; }
const std::map<std::string, TestFn>& tests() const { return tests_; }
TemplateStats& stats() { return stats_; }
const TemplateStats& stats() const { return stats_; }
TemplateCache& cache() { return cache_; }
bool autoescape_for(const std::string& name) const {
std::size_t dot = name.rfind('.');
if (dot == std::string::npos) return false;
std::string ext = name.substr(dot + 1);
for (char& c : ext) c = (char)std::tolower((unsigned char)c);
return ext == "html" || ext == "htm" || ext == "xml";
}
std::string load_source(const std::string& name) const {
for (const auto& loader : loaders_) {
std::optional<std::string> hit = loader->load(name);
if (hit.has_value()) {
if (hit->size() > caps::kMaxTemplateSize) {
throw TemplateError("template too large: " + name);
}
return *hit;
}
}
throw TemplateError("template not found: " + name);
}
std::shared_ptr<CompiledTemplate> compile_source(const std::string& source,
const std::string& name) const {
if (source.size() > caps::kMaxTemplateSize) {
throw TemplateError("template too large: " + name);
}
std::vector<Token> toks = lex_template(source, name);
std::vector<NodePtr> nodes = parse_template(toks, name);
auto compiled = std::make_shared<CompiledTemplate>();
compiled->name = name;
compiled->nodes = std::move(nodes);
compiled->autoescape = autoescape_for(name);
return compiled;
}
std::shared_ptr<CompiledTemplate> get_compiled(const std::string& name) {
if (!dev_reload_) {
std::shared_ptr<CompiledTemplate> hit = cache_.get(name);
if (hit) {
++stats_.cache_hits;
return hit;
}
}
std::string source = load_source(name);
std::shared_ptr<CompiledTemplate> compiled = compile_source(source, name);
if (!dev_reload_) cache_.put(name, compiled);
return compiled;
}
// Defined in renderer.h (needs the full Renderer).
std::string render(const std::string& name, validate::Object context = {});
std::string render_source(const std::string& source, const std::string& name,
validate::Object context = {});
private:
std::vector<std::shared_ptr<Loader>> loaders_;
validate::Object globals_;
std::map<std::string, FilterFn> filters_;
std::map<std::string, TestFn> tests_;
TemplateCache cache_;
UndefinedPolicy undefined_policy_ = UndefinedPolicy::Strict;
bool dev_reload_ = false;
TemplateStats stats_;
};
} // namespace molo::app::templates
#include "renderer.h"

Some files were not shown because too many files have changed in this diff Show More