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:
@@ -2,8 +2,10 @@
|
||||
|
||||
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`.
|
||||
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
|
||||
@@ -13,8 +15,10 @@ disagree, the spec wins: `plan.md`, `plans/`, `src/*/SPEC.md`, `reverse.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
|
||||
@@ -23,15 +27,18 @@ g++ --version && make --version
|
||||
## Build and test
|
||||
|
||||
```sh
|
||||
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
|
||||
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. `make deploy` is referenced in `AGENTS.md` but
|
||||
is not defined in the Makefile yet.
|
||||
cause, never silence them. Per-part targets (`google`, `google-test`, `ai`,
|
||||
`ai-test`, `data-test`, `cli-test`, ...) also run standalone.
|
||||
|
||||
## 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:
|
||||
|
||||
```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
|
||||
@@ -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
|
||||
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`):
|
||||
`GOOGLE_API_KEY` (Vertex express keys, voice), `GOOGLE_CLOUD_PROJECT`,
|
||||
`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. |
|
||||
| `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). |
|
||||
| `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` | 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. |
|
||||
| `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).
|
||||
@@ -157,34 +189,44 @@ cd shop && ls -A # .env.json AGENTS.md Makefile assets locales src templa
|
||||
|
||||
## The agent: `molo ai`
|
||||
|
||||
OpenAI-compatible vibe-coding harness that knows the framework's features
|
||||
and conventions. Streams by default.
|
||||
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"
|
||||
./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`;
|
||||
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.
|
||||
- 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).
|
||||
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 # 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
|
||||
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
|
||||
```
|
||||
|
||||
Stats are zero-cost on the hot path (atomics), flushed in one transaction to
|
||||
@@ -193,8 +235,8 @@ windowed kB/s, average latency.
|
||||
|
||||
## Configuration
|
||||
|
||||
`.env.json` in the workdir is loaded automatically; environment variables
|
||||
override it.
|
||||
Order, highest first: environment, `.env.json.local` (git-ignored, put
|
||||
secrets here), `.env.json`. `.secrets/` is git-ignored too.
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -208,7 +250,8 @@ override it.
|
||||
| `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 |
|
||||
| `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).
|
||||
@@ -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/operability deploys, drains, locks, breakers, SLO, chaos
|
||||
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
|
||||
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
|
||||
@@ -249,25 +294,30 @@ 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.
|
||||
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.
|
||||
|
||||
## 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/`
|
||||
- `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/`
|
||||
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
|
||||
measurement behind it is not a claim.
|
||||
|
||||
+3
-1
@@ -60,7 +60,9 @@ client, credentials, errors, or caps.
|
||||
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
|
||||
`.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`
|
||||
(HTTP 503, status `NOT_CONFIGURED`) before any network traffic. Loud, not
|
||||
silent.
|
||||
|
||||
Reference in New Issue
Block a user