10 KiB
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 BSDmake libsqlite3andlibpq(the CLI links-lsqlite3 -l:libpq.so.5)- Optional: Postgres 18 for the postgres backend (
docker compose up -d postgres)
g++ --version && make --version
Build and test
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 163 integration tests on the real stack (no mocks). Standalone, no other part needed.
make -f example/example.mk example # build
./build/example/living-server 8080 # run
make -f example/example.mk example-test # expect: 163 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:
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.
Open /voice for a live spoken conversation (needs a Google API key with
Text-to-Speech, Speech-to-Text and Generative Language enabled):
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.
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
src/google/<module>/tools/check_discovery.py; MOLO_LIVE_NET=1 make google-test adds read-only live checks against real Google.
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
/voice, /google and /agent routes, are excluded from locust.
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 Routers mounted with a prefix. Apps chain, so mounting three apps
under each other serves /app1/app1/app1/....
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.
./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:
./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.
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, modelmolodetz; override with--base-urland--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).
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.
{
"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
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/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
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 serveparks the loop; full HTTP serving waits on runtime lifecycle wiring (src/cli/dev/dev_server.cpp).molo ai continueresumes 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 (
/healthreportsstub-no-wolfssl). molo expose <upstream> key@server /claimshorthand fromreverse.mdis not wired; use theserveandagentsubcommands with flags.example/fw/is a skeleton, not the real framework; the swap tosrc/namespaces is incremental.- No root
deploytarget, noCHANGELOG.mdorVERSIONyet. - No benchmark numbers are published. Any performance claim without a measurement behind it is not a claim.