retoorandClaude Sonnet 5.5 6d744a433f feat(clients): google foundation for the agent platform: all-verb client, streaming, typed Gemini content, operations
GoogleClient gets every verb and stream_json (SSE and plain JSON), typed
Content/Part/Tool/GenerateRequest with the LanguageModel seam, CloudContext
resource names, long-running operation polling and pagination, OAuth bearer
tokens via GOOGLE_ACCESS_TOKEN. Example scaffold: one stub per agent module
under example/app/agent, wildcard builds, locust excludes /voice /google
/agent. plans/16-agent-platform.md splits the work into nine modules.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-24 04:12:52 +02:00

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)
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 111 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: 111 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); its route tests script the Google side, MOLO_LIVE_NET=1 make google-test adds the opt-in real-network checks. 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, 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).

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 APIs: generic client, TTS, STT, Gemini, voice pipeline
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.
S
Description
moloapp
Readme
5.2 MiB
Languages
C++ 90%
Python 3.2%
Pawn 3.2%
POV-Ray SDL 1.3%
JavaScript 1.1%
Other 1.1%