feat(workflow): example covers security, platform, enterprise and resilience features
105 route tests, matrix crawl, spec and README updated. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,225 @@
|
||||
# MoloApp
|
||||
|
||||
Native C++23 web framework: HTTP/1.1 + HTTP/2 runtime, routing, views,
|
||||
validation, templates, ORM (SQLite + Postgres), sessions, realtime,
|
||||
supervisor, clients, observability, multi-tenancy, audit, governance. One
|
||||
third-party dependency planned for TLS (wolfSSL). One CLI binary: `molo`.
|
||||
|
||||
This README states what works today. Gaps are listed at the bottom and in
|
||||
the spec next to the code that will close them. Where README and a spec
|
||||
disagree, the spec wins: `plan.md`, `plans/`, `src/*/SPEC.md`, `reverse.md`,
|
||||
`example/SPEC.md`.
|
||||
|
||||
## Requirements
|
||||
|
||||
- Linux, `g++` 15+ with `-std=c++23`, GNU or BSD `make`
|
||||
- `libsqlite3` and `libpq` (the CLI links `-lsqlite3 -l:libpq.so.5`)
|
||||
- Optional: Postgres 18 for the postgres backend (`docker compose up -d postgres`)
|
||||
|
||||
```sh
|
||||
g++ --version && make --version
|
||||
```
|
||||
|
||||
## Build and test
|
||||
|
||||
```sh
|
||||
make # everything: libs, tests, build/molo
|
||||
make test # whole suite, every part
|
||||
make lint # warning-free build plus em dash ban
|
||||
make clean # rm -rf build
|
||||
```
|
||||
|
||||
Everything lands under `build/`. Warnings are errors in spirit: fix the
|
||||
cause, never silence them. `make deploy` is referenced in `AGENTS.md` but
|
||||
is not defined in the Makefile yet.
|
||||
|
||||
## The living example
|
||||
|
||||
A route-level demo of every feature, with 105 integration tests on the real
|
||||
stack (no mocks). Standalone, no other part needed.
|
||||
|
||||
```sh
|
||||
make -f example/example.mk example # build
|
||||
./build/example/living-server 8080 # run
|
||||
make -f example/example.mk example-test # expect: 105 passed, 0 failed
|
||||
```
|
||||
|
||||
Open `http://127.0.0.1:8080/` and click through the matrix. Narrow the
|
||||
window to 360px: the nav collapses into a dropdown. Quick probe:
|
||||
|
||||
```sh
|
||||
curl localhost:8080/health # {"status":"ok","tls":"stub-no-wolfssl"}
|
||||
```
|
||||
|
||||
Open `/stats` for live Chart.js charts of requests, latency, bytes and
|
||||
connections (Chart.js is embedded into the binary at build time). The
|
||||
feature -> route -> test -> plan matrix lives in `example/README.md`.
|
||||
Test conventions (one test file per URL, Arrange/Act/Assert, integration
|
||||
only) are in `tests/README.md`.
|
||||
|
||||
### How an app is written
|
||||
|
||||
`example/app/App.cpp` is the reference: an `Application`, middleware slots,
|
||||
and `Router`s mounted with a prefix. Apps chain, so mounting three apps
|
||||
under each other serves `/app1/app1/app1/...`.
|
||||
|
||||
```cpp
|
||||
auto app = std::make_shared<fw::Application>();
|
||||
app->use(fw::MiddlewareSlot::Errors, fw::errors_middleware());
|
||||
|
||||
fw::Router routing;
|
||||
register_routing_demo(routing, services);
|
||||
app->include_router("/routing", routing, "routing.");
|
||||
```
|
||||
|
||||
Note: `example/fw/` is a skeleton of the public API that the real parts
|
||||
under `src/` are being re-bound to, route by route. URLs and tests stay
|
||||
stable while that happens.
|
||||
|
||||
## The CLI: `molo`
|
||||
|
||||
Built by `make` to `build/molo`.
|
||||
|
||||
```sh
|
||||
./build/molo --help
|
||||
./build/molo help <command> # full help for one command
|
||||
```
|
||||
|
||||
Global flags: `--format json|text`, `-v` (repeat up to 3), `-q`, `-h`.
|
||||
Exit codes: `0` ok, `1` runtime, `2` usage, `69` unavailable. Stdout is the
|
||||
primary output only; logs go to stderr. `--format json` is always parseable.
|
||||
|
||||
| Command | What it does |
|
||||
|---|---|
|
||||
| `new <name> [--backend postgres\|sqlite] [--force]` | Scaffold a project (Makefile, AGENTS.md, `.env.json`, assets, templates, locales, `git init`). Refuses a non-empty dir without `--force`. |
|
||||
| `serve [--port N] [--reload] [--config F]` | Dev server. `--reload` watches and rebuilds; refused on prod config without `--allow-prod`. |
|
||||
| `build [--embed dir] [--out dir]` | Build, optionally embedding assets first. |
|
||||
| `embed <dir> --out f.cpp [--hpp f.hpp] [--namespace ns] [--gzip]` | Turn a static dir into constexpr C++ arrays. Output is byte-identical across runs. |
|
||||
| `migrate [--check \| --apply]` | Preview or apply database migrations. |
|
||||
| `health` | Local liveness and readiness summary. |
|
||||
| `supervisor start\|stop\|restart\|status\|logs` | Process supervisor. |
|
||||
| `task enqueue\|retry\|cancel\|inspect` | Background task queue (`--id` for inspect). |
|
||||
| `ai new\|continue` | The AI agent, see below. |
|
||||
| `expose serve\|agent\|list\|stats\|expose-key` | Reverse tunnels, see below. |
|
||||
| `verify`, `supply-check`, `release` | Offline artifact verification, pin and advisory gate, ordered release gate. |
|
||||
| `rollout`, `rollback`, `experiment`, `debug` | Operability: deploys, chaos, debug helpers. |
|
||||
|
||||
Fixed health paths on a running server, no auth: `/healthz`, `/readyz`,
|
||||
`/startupz`, `/metrics` (Prometheus text 0.0.4).
|
||||
|
||||
Start a new app:
|
||||
|
||||
```sh
|
||||
./build/molo new shop --backend sqlite
|
||||
cd shop && ls -A # .env.json AGENTS.md Makefile assets locales src templates
|
||||
```
|
||||
|
||||
## The agent: `molo ai`
|
||||
|
||||
OpenAI-compatible vibe-coding harness that knows the framework's features
|
||||
and conventions. Streams by default.
|
||||
|
||||
```sh
|
||||
export DEVPLACE_API_KEY=... # env only, never a flag or a file
|
||||
./build/molo ai new --prompt "a todo app with sqlite and a json api"
|
||||
./build/molo ai continue --prompt "add login"
|
||||
```
|
||||
|
||||
- Defaults: base `https://devplace.net/openai/v1`, model `molodetz`;
|
||||
override with `--base-url` and `--model`.
|
||||
- Secrets are redacted before the prompt is built. If redaction fails, the
|
||||
run aborts.
|
||||
- Plan then apply: file writes are confirmed by a human.
|
||||
- Caps: 30 s connect, 300 s session, 8 MB transcript, 50 actions.
|
||||
|
||||
## Reverse tunnels: `molo expose`
|
||||
|
||||
Publish a local endpoint through a MoloApp server over one outbound
|
||||
connection. The spec is `reverse.md` (claims, keys, upstream tables,
|
||||
routing precedence, caps).
|
||||
|
||||
```sh
|
||||
molo expose serve --slug /hook1 --upstream http://127.0.0.1:3000 # server side
|
||||
molo expose agent --slug /hook1 --key <key> # exposer side
|
||||
molo expose list
|
||||
molo expose stats # or --format json
|
||||
molo expose expose-key rotate
|
||||
```
|
||||
|
||||
Stats are zero-cost on the hot path (atomics), flushed in one transaction to
|
||||
SQLite by default (`system.db`) or Postgres. Per method: count, kB up/down,
|
||||
windowed kB/s, average latency.
|
||||
|
||||
## Configuration
|
||||
|
||||
`.env.json` in the workdir is loaded automatically; environment variables
|
||||
override it.
|
||||
|
||||
```json
|
||||
{
|
||||
"DATABASE_URL": "sqlite://system.db",
|
||||
"STATS_FLUSH_SECS": "5"
|
||||
}
|
||||
```
|
||||
|
||||
| Key | Default | Meaning |
|
||||
|---|---|---|
|
||||
| `DATABASE_URL` | `sqlite://system.db` | `sqlite://...` or a postgres URL |
|
||||
| `STATS_FLUSH_SECS` | `5` | Stats flush interval |
|
||||
| `DEVPLACE_API_KEY` | none | Env only. Required by `molo ai` |
|
||||
| `MOLO_EXPOSE_KEY` | none | Claim key for the expose agent |
|
||||
|
||||
Postgres for local tests: `docker compose up -d postgres` (user/password
|
||||
`molo`, db `molo_test`, bound to 127.0.0.1:5432).
|
||||
|
||||
## Repo map
|
||||
|
||||
```text
|
||||
src/runtime event loop, HTTP/1.1 + HTTP/2, compression, static
|
||||
src/observability logging, events, metrics, tracing (zero-cost when off)
|
||||
src/security auth, hashing, crypto, sessions, guards, uploads
|
||||
src/data ORM, drivers, KV, cache, pubsub
|
||||
src/app application, routers, views, forms, validation, templates
|
||||
src/realtime WebSocket, SSE, Socket.IO, streaming, WebDAV, expose tunnels
|
||||
src/supervisor process supervisor, tasks, replication
|
||||
src/clients HTTP/REST client, OpenAPI, test double
|
||||
src/cli molo binary: CLI, dev server, embedder, AI, ops, i18n, CSP
|
||||
src/tenancy multi-tenancy
|
||||
src/audit hash-chained audit log, GDPR export/erasure, retention
|
||||
src/governance API keys, versioning, OpenAPI diff gate, surface linter
|
||||
src/operability deploys, drains, locks, breakers, SLO, chaos
|
||||
src/supplychain SBOM, provenance, pin policy, release attestation
|
||||
example/ living example (skeleton fw + demo routes)
|
||||
tests/ integration tests, mirrors URLs
|
||||
plans/ 15 detailed plans, index in plans/README.md
|
||||
```
|
||||
|
||||
Each part ships a `<part>.mk` fragment that the root Makefile includes, and
|
||||
most ship a `SPEC.md`. Every knob has a hard static cap, declared in that
|
||||
part's `caps` header (CLI: `src/cli/caps.hpp`).
|
||||
|
||||
## Working with agents on this repo
|
||||
|
||||
`AGENTS.md` is the entry point for autonomous work. Pipeline order:
|
||||
lint, suite, bump, changelog, commit, tag, deploy, verify. Commits are
|
||||
`<type>[(scope)][!]: <description>` (subject max 100 chars). Versions are
|
||||
derived from commits, never hand-chosen. Never cross alone: `specs/`,
|
||||
`CHANGELOG.md`, `VERSION`, tags, history rewrite, force push.
|
||||
|
||||
## Known gaps
|
||||
|
||||
Measured on this checkout, not aspirational:
|
||||
|
||||
- `molo serve` parks the loop; full HTTP serving waits on runtime lifecycle
|
||||
wiring (`src/cli/dev/dev_server.cpp`).
|
||||
- `molo ai continue` resumes within one process only; no durable session
|
||||
store (`src/cli/cli/cli_app.cpp`). HTTPS transport for the agent is a stub
|
||||
until wolfSSL lands.
|
||||
- TLS is a stub everywhere (`/health` reports `stub-no-wolfssl`).
|
||||
- `molo expose <upstream> key@server /claim` shorthand from `reverse.md` is
|
||||
not wired; use the `serve` and `agent` subcommands with flags.
|
||||
- `example/fw/` is a skeleton, not the real framework; the swap to `src/`
|
||||
namespaces is incremental.
|
||||
- No root `deploy` target, no `CHANGELOG.md` or `VERSION` yet.
|
||||
- No benchmark numbers are published. Any performance claim without a
|
||||
measurement behind it is not a claim.
|
||||
Reference in New Issue
Block a user