2026-10-24 02:19:52 +02:00
# MoloApp
Native C++23 web framework: HTTP/1.1 + HTTP/2 runtime, routing, views,
validation, templates, ORM (SQLite + Postgres), sessions, realtime,
2026-10-25 07:27:24 +01:00
supervisor, clients, observability, multi-tenancy, audit, governance, plus
clients for Google Cloud and the main LLM vendors. One third-party dependency
for TLS (wolfSSL). One CLI binary: `molo` . Current version: see `VERSION`
(0.1.0), history in `CHANGELOG.md` .
2026-10-24 02:19:52 +02:00
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`
2026-10-25 07:27:24 +01:00
- `libwolfssl` (TLS; the example and the Google/vendor libs link `-lwolfssl` )
2026-10-24 02:19:52 +02:00
- `libsqlite3` and `libpq` (the CLI links `-lsqlite3 -l:libpq.so.5` )
- Optional: Postgres 18 for the postgres backend (`docker compose up -d postgres` )
2026-10-25 07:27:24 +01:00
- Optional: `python3` for `make verify` , `pip install locust` for load tests
2026-10-24 02:19:52 +02:00
```sh
g++ --version && make --version
```
## Build and test
```sh
2026-10-25 07:27:24 +01:00
make # everything: libs, tests, build/molo, living server
make test # whole suite, every part
make lint # warning-free build plus em dash ban
make cve-audit # vulnerability-class regression checks, see audit/README.md
make deploy # restart the living server from build/ on :8080, pid file, health wait
make verify # live check of the deployed server (health, metrics, 360px markup, top 10 routes)
make clean # rm -rf build
2026-10-24 02:19:52 +02:00
```
Everything lands under `build/` . Warnings are errors in spirit: fix the
2026-10-25 07:27:24 +01:00
cause, never silence them. Per-part targets (`google` , `google-test` , `ai` ,
`ai-test` , `data-test` , `cli-test` , ...) also run standalone.
2026-10-24 02:19:52 +02:00
## The living example
2026-10-24 08:21:14 +02:00
A route-level demo of every feature, with 205 integration tests on the real
2026-10-24 02:19:52 +02:00
stack (no mocks). Standalone, no other part needed.
```sh
make -f example/example.mk example # build
./build/example/living-server 8080 # run
2026-10-24 08:21:14 +02:00
make -f example/example.mk example-test # expect: 205 passed, 0 failed
2026-10-24 02:19:52 +02:00
```
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
2026-10-25 07:27:24 +01:00
curl localhost:8080/health # {"status":"ok", ...}
```
Load test every route with Locust (`pip install locust` , see
`example/README.md` ):
```sh
make -f example/example.mk example-locust # coverage gate first, then headless run
2026-10-24 02:19:52 +02:00
```
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` .
2026-10-24 04:05:41 +02:00
Open `/voice` for a live spoken conversation (needs a Google API key with
Text-to-Speech, Speech-to-Text and Generative Language enabled):
```sh
GOOGLE_API_KEY = ... ./build/example/living-server 8080 # then open /voice
```
Click Start, talk, pause: the answer is spoken back, and speaking over it
interrupts it. Optional env: `GOOGLE_VOICE_LANG` (default `nl-NL` ),
`GOOGLE_VOICE_NAME` , `GOOGLE_GENAI_MODEL` (default `gemini-3.5-flash` ), `GOOGLE_STT_MODEL` , `GOOGLE_TTS_MODEL` (default `gemini-2.5-flash-tts` ), `GOOGLE_API_BACKEND` .
2026-10-24 04:51:20 +02:00
The Google layer is `src/google` (spec: `src/google/SPEC.md` , plan
`plans/16-agent-platform.md` ). No test scripts a Google reply: each module
is derived from Google's Discovery documents and re-checked by
2026-10-24 08:32:55 +02:00
`src/google/<module>/tools/check_discovery.py` ; `make google-live`
runs read-only live checks against real Google (a service-account token is
minted for the OAuth-only APIs).
2026-10-24 04:51:20 +02:00
2026-10-25 07:27:24 +01:00
### Live checks
Hermetic tests never touch the network and ignore `.env.json.local`
(`MOLO_ENV_FILES=off` ). Live checks are opt-in:
- `make google-live` : builds `build/google/sa-token` , mints a service-account
access token into `GOOGLE_ACCESS_TOKEN` , then runs the whole Google suite
(hermetic tests plus live tests) with `MOLO_LIVE_NET=1` . Needs
`GOOGLE_APPLICATION_CREDENTIALS` and `GOOGLE_CLOUD_PROJECT` . Live tests are
read-only or a few tokens; none creates, updates or deletes a resource. An
API that is disabled on the project prints a loud `API NOT ENABLED` instead
of failing quietly.
- `MOLO_LIVE_NET=1 make ai-test` : same for the vendor packages, using
`XAI_API_KEY` , `ANTHROPIC_API_KEY` , `META_API_KEY` , `DEEPSEEK_API_KEY` ,
`OPENAI_API_KEY` , `OPENROUTER_API_KEY` and the admin / management keys.
Missing keys give a loud SKIP. Calls that cost real money also need
`MOLO_LIVE_PAID=1` .
2026-10-24 04:51:20 +02:00
Credentials (environment, then `.env.json.local` , then `.env.json` ):
`GOOGLE_API_KEY` (Vertex express keys, voice), `GOOGLE_CLOUD_PROJECT` ,
`GOOGLE_CLOUD_LOCATION` , and for OAuth-only APIs either
`GOOGLE_ACCESS_TOKEN` or a service account key file in
`GOOGLE_APPLICATION_CREDENTIALS` (git-ignored `.secrets/` ). `make
google-token && ./build/google/sa-token` prints an access token.
The Agent Platform demo pages are under `/agent/<module>` and, like all
2026-10-24 08:21:14 +02:00
`/voice` , `/google` , `/agent` and `/ai` routes, are excluded from locust.
Other vendors (plan `plans/17-llm-vendor-platforms.md` , shared layer
`src/llm/SPEC.md` ): pages `/ai/xai` , `/ai/xai/platform` , `/ai/anthropic` ,
`/ai/anthropic/admin` , `/ai/meta` , `/ai/deepseek` , `/ai/openai` ,
`/ai/openai/platform` , `/ai/openai/admin` , `/ai/openrouter` . Keys go in
`.env.json.local` or the environment: `XAI_API_KEY` , `XAI_MANAGEMENT_KEY` ,
`ANTHROPIC_API_KEY` , `ANTHROPIC_ADMIN_KEY` , `META_API_KEY` (or
`MODEL_API_KEY` ), `DEEPSEEK_API_KEY` , `OPENAI_API_KEY` , `OPENAI_ADMIN_KEY` ,
`OPENROUTER_API_KEY` , `OPENROUTER_MANAGEMENT_KEY` . Without a key a page and
its status route still load and every calling route answers 503
`not_configured` ; paid or destructive routes are dry runs unless the body has
`"confirm":true` . `MOLO_LIVE_NET=1 make ai-test` adds opt-in live checks;
anything that costs money also needs `MOLO_LIVE_PAID=1` . No vendor key
exists in this repo's environment yet, so every vendor package is verified
against its published spec and unauthenticated probes only.
2026-10-24 02:19:52 +02:00
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. |
2026-10-25 07:27:24 +01:00
| `supervisor start\|stop\|restart\|status\|logs` | Process supervisor. Exits 69 until the supervisor is wired in. |
| `task enqueue\|retry\|cancel\|inspect` | Background task queue (`--id` for inspect). Same wiring caveat. |
2026-10-24 02:19:52 +02:00
| `ai new\|continue` | The AI agent, see below. |
2026-10-25 07:27:24 +01:00
| `expose serve\|agent\|list\|stats\|expose-key rotate` | Reverse tunnels, see below. |
| `verify [dir]` , `supply-check [dir]` , `release --commit SHA --suite-stamp F` | Offline artifact verification, pin and advisory gate, ordered release gate. |
| `rollout start\|abort` , `rollback` , `experiment start\|abort` , `debug snapshot` | Operability: rolling or blue-green rollout (`--strategy --instances --batch --max-unavailable` ), chaos experiment (`--blast --duration --max-burn` ), debug snapshot. These are one-shot: `abort` and `rollback` report that nothing runs in the process. |
2026-10-24 02:19:52 +02:00
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`
2026-10-25 07:27:24 +01:00
OpenAI-compatible vibe-coding harness with a framework-aware system prompt.
Streams by default. The prompt comes from `--prompt` , the first argument, or
piped stdin.
2026-10-24 02:19:52 +02:00
```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"
2026-10-25 07:27:24 +01:00
echo "add login" | ./build/molo ai continue
./build/molo ai new --prompt "..." --format json # {"ok":true,"text":"..."}
2026-10-24 02:19:52 +02:00
```
- Defaults: base `https://devplace.net/openai/v1` , model `molodetz` ;
override with `--base-url` and `--model` .
2026-10-25 07:27:24 +01:00
- Today it prints the model's answer. It does not write files yet, so the
plan-then-apply flow in `src/cli/spec.md` is not implemented.
- `continue [name]` resumes by name within one process only; there is no
durable session store.
2026-10-24 02:19:52 +02:00
- Caps: 30 s connect, 300 s session, 8 MB transcript, 50 actions.
2026-10-25 07:27:24 +01:00
Calling vendors from your own code is a separate layer: `src/llm` plus
`src/openai` , `src/anthropic` , `src/xai` , `src/meta` , `src/deepseek` ,
`src/openrouter` and `src/google` , demoed under `/ai/*` , `/agent/*` ,
`/google` and `/voice` in the living example (see above).
2026-10-24 02:19:52 +02:00
## 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,
2026-10-25 07:27:24 +01:00
routing precedence, caps). The protocol pieces (claims, upstream table,
tunnel, proxy) live in `src/realtime/expose/` . The CLI is a thin front end
and does not run a live tunnel yet:
2026-10-24 02:19:52 +02:00
```sh
2026-10-25 07:27:24 +01:00
molo expose serve --slug /hook1 --upstream http://127.0.0.1:3000 # validates, registers the claim in-process, starts stats
molo expose agent --slug /hook1 --key <key> [ --server URL] # validates args, prints the target, exits
molo expose list # tunnels registered in this process
molo expose stats [ --format json] # reads the stats store
molo expose expose-key rotate --slug /hook1
2026-10-24 02:19:52 +02:00
```
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
2026-10-25 07:27:24 +01:00
Order, highest first: environment, `.env.json.local` (git-ignored, put
secrets here), `.env.json` . `.secrets/` is git-ignored too.
2026-10-24 02:19:52 +02:00
```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` |
2026-10-25 07:27:24 +01:00
| `MOLO_EXPOSE_KEY` | none | Claim key for the expose agent (specified in `reverse.md` ; the CLI reads `--key` ) |
| `GOOGLE_API_KEY` , `XAI_API_KEY` , `ANTHROPIC_API_KEY` , `OPENAI_API_KEY` , ... | none | Vendor keys for the demo pages, full list in the living example section |
2026-10-24 02:19:52 +02:00
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
2026-10-24 08:21:14 +02:00
src/llm shared layer for the vendor platforms below (client, SSE, errors, ChatModel)
src/xai src/anthropic src/meta src/deepseek src/openai src/openrouter
whole public API platforms of Grok, Claude, Meta Model API (Muse Spark),
DeepSeek, OpenAI and OpenRouter, one dir per work package
2026-10-24 04:51:20 +02:00
src/google Google Cloud: generic client, OAuth + service accounts, voice, and the
Gemini Enterprise Agent Platform (models, runtime, sessions, sandbox,
registry, armor, optimize, adk, live), one dir per module
2026-10-24 02:19:52 +02:00
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
2026-10-25 07:27:24 +01:00
audit/ vulnerability-class regression checks (make cve-audit)
tools/ deploy verification, release and token helpers
example/ living example (skeleton fw + demo routes, Locust file)
2026-10-24 02:19:52 +02:00
tests/ integration tests, mirrors URLs
2026-10-25 07:27:24 +01:00
plans/ 17 detailed plans, index in plans/README.md
2026-10-24 02:19:52 +02:00
```
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:
2026-10-25 07:27:24 +01:00
lint, suite, bump, changelog, commit, tag, deploy (`make deploy` ), verify
(`make verify` ). Commits are `<type>[(scope)][!]: <description>` (subject
max 100 chars). Versions are derived from commits, never hand-chosen:
`VERSION` and `CHANGELOG.md` are written by the release tool. Never cross
alone: `specs/` , `CHANGELOG.md` , `VERSION` , tags, history rewrite, force push.
2026-10-24 02:19:52 +02:00
## Known gaps
Measured on this checkout, not aspirational:
2026-10-25 07:27:24 +01:00
- `molo serve` without `--reload` only waits for a signal; it does not serve
HTTP (`src/cli/dev/dev_server.cpp` , `run_once` ). With `--reload` it
rebuilds and restarts `./build/molo-app` on change.
- `molo ai` prints answers only: no file writes, no durable sessions
(`src/cli/cli/cli_app.cpp` , `cmd_ai` ).
- `molo expose serve|agent` do not carry traffic; the shorthand
`molo expose <upstream> key@server /claim` from `reverse.md` is not wired
(`src/cli/cli/expose_cli.cpp` ).
- `molo supervisor` , `task` and `migrate` exit 69 with the null controllers
the binary is built with (`src/cli/cli/cli_app.cpp` ).
- `example/fw/` is a skeleton, not the real framework (its TLS context is
still `tls-stub-no-wolfssl` , `example/fw/Tls.cpp` ); the swap to `src/`
2026-10-24 02:19:52 +02:00
namespaces is incremental.
2026-10-25 07:27:24 +01:00
- Vendor and Google modules are verified against published specs and
unauthenticated probes; no vendor key exists in this repo's environment.
2026-10-24 02:19:52 +02:00
- No benchmark numbers are published. Any performance claim without a
measurement behind it is not a claim.