# 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, 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`. 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` - `libwolfssl` (TLS; the example and the Google/vendor libs link `-lwolfssl`) - `libsqlite3` and `libpq` (the CLI links `-lsqlite3 -l:libpq.so.5`) - Optional: Postgres 18 for the postgres backend (`docker compose up -d postgres`) - Optional: `python3` for `make verify`, `pip install locust` for load tests ```sh g++ --version && make --version ``` ## Build and test ```sh 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 ``` Everything lands under `build/`. Warnings are errors in spirit: fix the cause, never silence them. Per-part targets (`google`, `google-test`, `ai`, `ai-test`, `data-test`, `cli-test`, ...) also run standalone. ## The living example A route-level demo of every feature, with 261 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: 261 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", ...} ``` 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 ``` 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): ```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`. 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//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). ### Live checks Which Google APIs to enable (with console links) is in `src/google/APIS.md`; where to create each vendor key is in `src/llm/SPEC.md` section 5. 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`. 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/` and, like all `/voice`, `/google`, `/agent` and `/ai` routes, are excluded from locust. More Google Cloud (plan `plans/18-breadth.md`): `/google/discovery` calls any method of any of Google's 316 Discovery APIs by id; typed packages are `/google/cloudai` (Translation, Vision, Language, Video Intelligence, Document AI, Speech v2), `/google/enterprise` (Discovery Engine, Dialogflow, Retail, Contact Center Insights, CES), `/google/data` (BigQuery, Storage, Pub/Sub, Firestore, Spanner, Bigtable, Secret Manager, Dataplex, DLP, KMS), `/google/maps`, `/google/workspace` (needs domain-wide delegation) and `/google/ops` (Compute, Run, GKE, IAM, Service Usage, Logging, Monitoring). Every API with its enable link is in `src/google/APIS.md`. More vendors (plan 18, `src/vendors/`): `/ai/compat` (39 OpenAI-compatible providers, one table row each), `/ai/mistral`, `/ai/cohere`, `/ai/perplexity`, `/ai/bedrock`, `/ai/azure`, `/ai/huggingface`, `/ai/audio`, `/ai/media`, `/ai/retrieval`. Env keys are listed in `src/llm/SPEC.md` section 5. 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. 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(); 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 # 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 [--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 --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. Exits 69 until the supervisor is wired in. | | `task enqueue\|retry\|cancel\|inspect` | Background task queue (`--id` for inspect). Same wiring caveat. | | `ai new\|continue` | The AI agent, see below. | | `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. | 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 with a framework-aware system prompt. Streams by default. The prompt comes from `--prompt`, the first argument, or piped stdin. ```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" echo "add login" | ./build/molo ai continue ./build/molo ai new --prompt "..." --format json # {"ok":true,"text":"..."} ``` - Defaults: base `https://devplace.net/openai/v1`, model `molodetz`; override with `--base-url` and `--model`. - 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. - Caps: 30 s connect, 300 s session, 8 MB transcript, 50 actions. 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). ## 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). 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: ```sh 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 [--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 ``` 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 Order, highest first: environment, `.env.json.local` (git-ignored, put secrets here), `.env.json`. `.secrets/` is git-ignored too. ```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 (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 | 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/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 src/vendors plan 18 vendors, one dir each: compat (39 OpenAI-compatible providers), mistral, cohere, perplexity, bedrock (SigV4), azure, huggingface, audio (ElevenLabs, Deepgram, ...), media (image/video), retrieval src/google Google Cloud: generic client, OAuth + service accounts, voice, the Gemini Enterprise Agent Platform (models, runtime, sessions, sandbox, registry, armor, optimize, adk, live) and plan 18 packages (discovery: all 316 Discovery APIs, cloudai, enterprise, data, maps, workspace, ops) 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 audit/ vulnerability-class regression checks (make cve-audit) tools/ deploy verification, release and token helpers example/ living example (skeleton fw + demo routes, Locust file) tests/ integration tests, mirrors URLs plans/ 17 detailed plans, index in plans/README.md ``` Each part ships a `.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 (`make deploy`), verify (`make verify`). Commits are `[(scope)][!]: ` (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. ## Known gaps Measured on this checkout, not aspirational: - `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 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/` namespaces is incremental. - Vendor and Google modules are verified against published specs and unauthenticated probes; no vendor key exists in this repo's environment. - No benchmark numbers are published. Any performance claim without a measurement behind it is not a claim.