REVERSE PROXY AND WEB SERVER — RUST

Vongola

OVERVIEW

Vongola is Qompass AI's reverse proxy and web server — a clean-room rewrite on Pingora 0.9.0 that hosts qompass.ai, runs on a single small device, and scales across a fleet of small nodes sharing one versioned configuration bundle.

HOW IT WORKS

1One process starts three listeners — HTTPS (Pingora proxy), HTTP, and admin — plus a background service for health checks, NAT, Tor, and discovery.
2A request arrives on HTTP and is 308-redirected to HTTPS, except ACME HTTP-01 challenge answers and the Agent Card, which are served over HTTP.
3On HTTPS, SNI selects the certificate through a `TlsAccept` callback; TLS is pinned to TLS 1.3 with the configured group allowlist.
4`request_filter` runs before any upstream is touched: www→apex 308, route lookup by host + longest path prefix, body-size bound, then route auth (basic, JWT, or OAuth2).
5The route is then served: static files for hosting routes, a chained fetch for chained routes, or round-robin over healthy upstreams for plain proxy routes — all-known-down is a 502.
6`logging` records the access line and metrics through a bounded (1024) redacting log pipeline; `POST /api/reload` on the admin listener re-reads config and atomically swaps config and certificate store, keeping the old state on failure.

How it works, step by step — each step as the project's own documentation states it.

CONCEPTS

Pingora's request-lifecycle phases as Vongola implements them: the request filter routes and authenticates before any upstream is touched, peer selection chooses static, chained, or round-robin service, the response is filtered on the way back, and logging runs last. Phase names and order are the Pingora framework's; the work in each phase is Vongola's own, from its architecture book.

CONFIGURATION

Option	Default	What it does
`profile`	hosting	Deployment profile: `fleet`, `hosting`, or `lean`
`node_name`	not stated in source	This node's name (dashboard, card, logs)
`bundle_version`	not stated in source	Fleet bundle version string; fingerprinted with the config
`state_dir`	./vongola-state	Keys, self-signed certs, onion keys
`worker_threads`	4	Threads per Pingora service, wired into `ServerConf` (lean example: `2`)
`shutdown_grace_secs`	10	SIGTERM drain cap, wired into Pingora's `ServerConf`
`admin_token_env`	VONGOLA_OPERATOR_TOKEN	Env var holding the operator token
`listeners.<admin\	http\	https>.bind`
`listeners.<name>.nat.enabled`	not stated in source	Per-listener NAT traversal opt-in (PCP / NAT-PMP / UPnP IGD)
`listeners.<name>.nat.lease_secs`	not stated in source	NAT mapping lease; lean example sets `3600`
`tls.min_version`	only `"1.3"` allowed	TLS minimum version
`tls.groups`	not stated in source	TLS group allowlist (see the book's TLS chapter)
`tor.enabled`	not stated in source	Enable Tor onion-service publication
`tor.exit_relay`	must be `false`	Vongola is never a Tor exit node; enforced in config validation
`tor.exit_policy`	only `reject :` allowed	Tor exit policy
lets_encrypt.enabled` / `lets_encrypt.email` / `lets_encrypt.staging	not stated in source	ACME / Let's Encrypt issuance; placeholder emails are rejected, even when disabled
`a2a.enabled`	not stated in source	Publish the signed A2A Agent Card
`routes[].host`	not stated in source	Primary hostname; route identity is host + path-prefix set
`routes[].path_prefixes`	not stated in source	Prefixes this route answers; longest match wins
`routes[].static_root`	not stated in source	Directory for static hosting (mutually exclusive with `upstreams`)
`routes[].upstreams[].address`	not stated in source	Upstream `host:port`; round-robin over healthy entries
`routes[].max_body_bytes`	16 MiB	Request body bound; oversized is a 413
`routes[].redirect_www_to_apex`	not stated in source	308 `www.<host>` → apex
`routes[].security_headers`	on	Standard security header set on responses
routes[].cache.enabled` / `max_age_secs` / `max_bytes	not stated in source	Static in-memory cache; qompass example sets `max_age_secs: 3600`
`routes[].chain[]`	not stated in source	Ordered proxy-chain hops: `kind` (`http-connect`, `socks5`, `tor`, `vongola`) + `address` (optional for `tor`); max 8 hops per `docs/src/architecture.md`
`routes[].onion.enabled`	not stated in source	Publish as an onion service (requires `tor.enabled`)
`routes[].self_signed_fallback`	not stated in source	Opt-in: generate/reuse a self-signed cert when no operator cert exists; without a cert and without this flag, the handshake fails

CONTROLS

Action	Control
Build	`cargo build --release`
Validate a config without starting listeners	`./target/release/vongola validate-config --config examples/qompass.yaml`
Serve (default subcommand)	`./target/release/vongola serve --config examples/lean.yaml`
Run the stdio MCP operator server	`vongola mcp`
Print version	`vongola version`
Run the full live smoke suite	`bash scripts/smoke.sh`
Reload config at runtime	`POST /api/reload` on the admin listener (operator token required)
Read operator state	Admin listener: `/healthz`, `/metrics`, `/api/state`, `/dashboard`, `/mcp`
Rotate a self-signed certificate	`POST /api/rotate-self-signed` on the admin listener

NOT COVERED

- No per-field defaults are stated in `docs/src/config.md` for most route, listener, Tor, ACME, or discovery fields; those rows record "not stated in source" rather than guessing. - The full TLS group allowlist is in the book's TLS chapter (`docs/src/tls.md`), which was not read for this pack; only the config reference's summary was sourced. - MCP tool names and A2A Agent Card fields were not enumerated from `crates/vongola/src/mcp.rs` / `a2a.rs` for this pack.

REFERENCES

Pingora — Cloudflare's Rust framework for programmable network servicesThe upstream framework Vongola builds on (Pingora 0.9.0): its proxy phase order — request filter, upstream peer selection, upstream filter, response filter, logging — and its upstream connection pooling are what the diagram shows.
RFC 9110 — HTTP SemanticsThe HTTP semantics Vongola's routes speak: methods, the status codes in the diagram (308, 413, 502), and header fields.