docs(clients): document make google-live and the opt-in live checks

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-25 07:27:24 +01:00
co-authored by Claude Sonnet 5.5
parent 248bdc221a
commit 865ce89784
2 changed files with 98 additions and 46 deletions
+95 -45
View File
@@ -2,8 +2,10 @@
Native C++23 web framework: HTTP/1.1 + HTTP/2 runtime, routing, views, Native C++23 web framework: HTTP/1.1 + HTTP/2 runtime, routing, views,
validation, templates, ORM (SQLite + Postgres), sessions, realtime, validation, templates, ORM (SQLite + Postgres), sessions, realtime,
supervisor, clients, observability, multi-tenancy, audit, governance. One supervisor, clients, observability, multi-tenancy, audit, governance, plus
third-party dependency planned for TLS (wolfSSL). One CLI binary: `molo`. 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 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 the spec next to the code that will close them. Where README and a spec
@@ -13,8 +15,10 @@ disagree, the spec wins: `plan.md`, `plans/`, `src/*/SPEC.md`, `reverse.md`,
## Requirements ## Requirements
- Linux, `g++` 15+ with `-std=c++23`, GNU or BSD `make` - 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`) - `libsqlite3` and `libpq` (the CLI links `-lsqlite3 -l:libpq.so.5`)
- Optional: Postgres 18 for the postgres backend (`docker compose up -d postgres`) - Optional: Postgres 18 for the postgres backend (`docker compose up -d postgres`)
- Optional: `python3` for `make verify`, `pip install locust` for load tests
```sh ```sh
g++ --version && make --version g++ --version && make --version
@@ -23,15 +27,18 @@ g++ --version && make --version
## Build and test ## Build and test
```sh ```sh
make # everything: libs, tests, build/molo make # everything: libs, tests, build/molo, living server
make test # whole suite, every part make test # whole suite, every part
make lint # warning-free build plus em dash ban make lint # warning-free build plus em dash ban
make clean # rm -rf build 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 Everything lands under `build/`. Warnings are errors in spirit: fix the
cause, never silence them. `make deploy` is referenced in `AGENTS.md` but cause, never silence them. Per-part targets (`google`, `google-test`, `ai`,
is not defined in the Makefile yet. `ai-test`, `data-test`, `cli-test`, ...) also run standalone.
## The living example ## The living example
@@ -48,7 +55,14 @@ 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: window to 360px: the nav collapses into a dropdown. Quick probe:
```sh ```sh
curl localhost:8080/health # {"status":"ok","tls":"stub-no-wolfssl"} 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 Open `/stats` for live Chart.js charts of requests, latency, bytes and
@@ -72,6 +86,24 @@ is derived from Google's Discovery documents and re-checked by
runs read-only live checks against real Google (a service-account token is runs read-only live checks against real Google (a service-account token is
minted for the OAuth-only APIs). minted for the OAuth-only APIs).
### 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`.
Credentials (environment, then `.env.json.local`, then `.env.json`): Credentials (environment, then `.env.json.local`, then `.env.json`):
`GOOGLE_API_KEY` (Vertex express keys, voice), `GOOGLE_CLOUD_PROJECT`, `GOOGLE_API_KEY` (Vertex express keys, voice), `GOOGLE_CLOUD_PROJECT`,
`GOOGLE_CLOUD_LOCATION`, and for OAuth-only APIs either `GOOGLE_CLOUD_LOCATION`, and for OAuth-only APIs either
@@ -138,12 +170,12 @@ primary output only; logs go to stderr. `--format json` is always parseable.
| `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. | | `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. | | `migrate [--check \| --apply]` | Preview or apply database migrations. |
| `health` | Local liveness and readiness summary. | | `health` | Local liveness and readiness summary. |
| `supervisor start\|stop\|restart\|status\|logs` | Process supervisor. | | `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). | | `task enqueue\|retry\|cancel\|inspect` | Background task queue (`--id` for inspect). Same wiring caveat. |
| `ai new\|continue` | The AI agent, see below. | | `ai new\|continue` | The AI agent, see below. |
| `expose serve\|agent\|list\|stats\|expose-key` | Reverse tunnels, see below. | | `expose serve\|agent\|list\|stats\|expose-key rotate` | Reverse tunnels, see below. |
| `verify`, `supply-check`, `release` | Offline artifact verification, pin and advisory gate, ordered release gate. | | `verify [dir]`, `supply-check [dir]`, `release --commit SHA --suite-stamp F` | Offline artifact verification, pin and advisory gate, ordered release gate. |
| `rollout`, `rollback`, `experiment`, `debug` | Operability: deploys, chaos, debug helpers. | | `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`, Fixed health paths on a running server, no auth: `/healthz`, `/readyz`,
`/startupz`, `/metrics` (Prometheus text 0.0.4). `/startupz`, `/metrics` (Prometheus text 0.0.4).
@@ -157,34 +189,44 @@ cd shop && ls -A # .env.json AGENTS.md Makefile assets locales src templa
## The agent: `molo ai` ## The agent: `molo ai`
OpenAI-compatible vibe-coding harness that knows the framework's features OpenAI-compatible vibe-coding harness with a framework-aware system prompt.
and conventions. Streams by default. Streams by default. The prompt comes from `--prompt`, the first argument, or
piped stdin.
```sh ```sh
export DEVPLACE_API_KEY=... # env only, never a flag or a file 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 new --prompt "a todo app with sqlite and a json api"
./build/molo ai continue --prompt "add login" 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`; - Defaults: base `https://devplace.net/openai/v1`, model `molodetz`;
override with `--base-url` and `--model`. override with `--base-url` and `--model`.
- Secrets are redacted before the prompt is built. If redaction fails, the - Today it prints the model's answer. It does not write files yet, so the
run aborts. plan-then-apply flow in `src/cli/spec.md` is not implemented.
- Plan then apply: file writes are confirmed by a human. - `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. - 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` ## Reverse tunnels: `molo expose`
Publish a local endpoint through a MoloApp server over one outbound Publish a local endpoint through a MoloApp server over one outbound
connection. The spec is `reverse.md` (claims, keys, upstream tables, connection. The spec is `reverse.md` (claims, keys, upstream tables,
routing precedence, caps). 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 ```sh
molo expose serve --slug /hook1 --upstream http://127.0.0.1:3000 # server side 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> # exposer side molo expose agent --slug /hook1 --key <key> [--server URL] # validates args, prints the target, exits
molo expose list molo expose list # tunnels registered in this process
molo expose stats # or --format json molo expose stats [--format json] # reads the stats store
molo expose expose-key rotate molo expose expose-key rotate --slug /hook1
``` ```
Stats are zero-cost on the hot path (atomics), flushed in one transaction to Stats are zero-cost on the hot path (atomics), flushed in one transaction to
@@ -193,8 +235,8 @@ windowed kB/s, average latency.
## Configuration ## Configuration
`.env.json` in the workdir is loaded automatically; environment variables Order, highest first: environment, `.env.json.local` (git-ignored, put
override it. secrets here), `.env.json`. `.secrets/` is git-ignored too.
```json ```json
{ {
@@ -208,7 +250,8 @@ override it.
| `DATABASE_URL` | `sqlite://system.db` | `sqlite://...` or a postgres URL | | `DATABASE_URL` | `sqlite://system.db` | `sqlite://...` or a postgres URL |
| `STATS_FLUSH_SECS` | `5` | Stats flush interval | | `STATS_FLUSH_SECS` | `5` | Stats flush interval |
| `DEVPLACE_API_KEY` | none | Env only. Required by `molo ai` | | `DEVPLACE_API_KEY` | none | Env only. Required by `molo ai` |
| `MOLO_EXPOSE_KEY` | none | Claim key for the expose agent | | `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 Postgres for local tests: `docker compose up -d postgres` (user/password
`molo`, db `molo_test`, bound to 127.0.0.1:5432). `molo`, db `molo_test`, bound to 127.0.0.1:5432).
@@ -237,9 +280,11 @@ src/audit hash-chained audit log, GDPR export/erasure, retention
src/governance API keys, versioning, OpenAPI diff gate, surface linter src/governance API keys, versioning, OpenAPI diff gate, surface linter
src/operability deploys, drains, locks, breakers, SLO, chaos src/operability deploys, drains, locks, breakers, SLO, chaos
src/supplychain SBOM, provenance, pin policy, release attestation src/supplychain SBOM, provenance, pin policy, release attestation
example/ living example (skeleton fw + demo routes) 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 tests/ integration tests, mirrors URLs
plans/ 15 detailed plans, index in plans/README.md plans/ 17 detailed plans, index in plans/README.md
``` ```
Each part ships a `<part>.mk` fragment that the root Makefile includes, and Each part ships a `<part>.mk` fragment that the root Makefile includes, and
@@ -249,25 +294,30 @@ part's `caps` header (CLI: `src/cli/caps.hpp`).
## Working with agents on this repo ## Working with agents on this repo
`AGENTS.md` is the entry point for autonomous work. Pipeline order: `AGENTS.md` is the entry point for autonomous work. Pipeline order:
lint, suite, bump, changelog, commit, tag, deploy, verify. Commits are lint, suite, bump, changelog, commit, tag, deploy (`make deploy`), verify
`<type>[(scope)][!]: <description>` (subject max 100 chars). Versions are (`make verify`). Commits are `<type>[(scope)][!]: <description>` (subject
derived from commits, never hand-chosen. Never cross alone: `specs/`, max 100 chars). Versions are derived from commits, never hand-chosen:
`CHANGELOG.md`, `VERSION`, tags, history rewrite, force push. `VERSION` and `CHANGELOG.md` are written by the release tool. Never cross
alone: `specs/`, `CHANGELOG.md`, `VERSION`, tags, history rewrite, force push.
## Known gaps ## Known gaps
Measured on this checkout, not aspirational: Measured on this checkout, not aspirational:
- `molo serve` parks the loop; full HTTP serving waits on runtime lifecycle - `molo serve` without `--reload` only waits for a signal; it does not serve
wiring (`src/cli/dev/dev_server.cpp`). HTTP (`src/cli/dev/dev_server.cpp`, `run_once`). With `--reload` it
- `molo ai continue` resumes within one process only; no durable session rebuilds and restarts `./build/molo-app` on change.
store (`src/cli/cli/cli_app.cpp`). HTTPS transport for the agent is a stub - `molo ai` prints answers only: no file writes, no durable sessions
until wolfSSL lands. (`src/cli/cli/cli_app.cpp`, `cmd_ai`).
- TLS is a stub everywhere (`/health` reports `stub-no-wolfssl`). - `molo expose serve|agent` do not carry traffic; the shorthand
- `molo expose <upstream> key@server /claim` shorthand from `reverse.md` is `molo expose <upstream> key@server /claim` from `reverse.md` is not wired
not wired; use the `serve` and `agent` subcommands with flags. (`src/cli/cli/expose_cli.cpp`).
- `example/fw/` is a skeleton, not the real framework; the swap to `src/` - `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. namespaces is incremental.
- No root `deploy` target, no `CHANGELOG.md` or `VERSION` yet. - 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 - No benchmark numbers are published. Any performance claim without a
measurement behind it is not a claim. measurement behind it is not a claim.
+3 -1
View File
@@ -60,7 +60,9 @@ client, credentials, errors, or caps.
Tokens expire after about an hour; refresh is the caller's job (gap). Tokens expire after about an hour; refresh is the caller's job (gap).
- Test runs set `MOLO_ENV_FILES=off`: config files are ignored so a developer's - Test runs set `MOLO_ENV_FILES=off`: config files are ignored so a developer's
`.env.json.local` cannot change test outcomes. `MOLO_LIVE_NET=1` re-enables `.env.json.local` cannot change test outcomes. `MOLO_LIVE_NET=1` re-enables
them for the opt-in live checks. them for the opt-in live checks. `make google-live` is the entry point: it
mints a service-account token (`build/google/sa-token`), exports it as
`GOOGLE_ACCESS_TOKEN`, and runs the full suite with `MOLO_LIVE_NET=1`.
- No key: `configured()` is false and every call throws `NotConfiguredError` - No key: `configured()` is false and every call throws `NotConfiguredError`
(HTTP 503, status `NOT_CONFIGURED`) before any network traffic. Loud, not (HTTP 503, status `NOT_CONFIGURED`) before any network traffic. Loud, not
silent. silent.