HeliosProxy platform-tier demos — 22 hands-on showcases

One self-contained demo per platform-tier feature: the WASM plugin runtime and its host APIs, the first-party plugins, the edge proxy, anomaly detection, the admin console and REST API, and the companion operator and infrastructure providers. This is a historical set, written for the release that introduced the platform tier: the demos still run, but they are not a tour of the current release. For what has changed since, see the Release History and the repo CHANGELOG.

Each demo:

has a README.md with what the demo does, use cases, and a step-by-step walkthrough,
includes a docker-compose.yml with a PostgreSQL 17 backend,
and a demo.sh entry point with up / run / down subcommands.

cd <demo-dir>
./demo.sh           # interactive walkthrough
./demo.sh up        # just bring up services + leave them running
./demo.sh down      # tear everything down + remove volumes

Prerequisites

Docker + Docker Compose v2
psql (PostgreSQL 14+ client)
curl and jq
For plugin demos: a Rust toolchain with wasm32-unknown-unknown target, OR pre-built .wasm artefacts dropped into the per-demo plugins/ directory.

Demo index

#	Demo	Module	Runnable	What it proves
1	Anomaly Detection	`anomaly-detection`	yes	SQLi + auth burst + novel query — three families fire concurrently against a single backend
2	Edge / Geo Proxy	`edge-proxy`	yes	Two proxies (home + edge), invalidation broadcast on write, ~40× cache speedup
3	Plugin host KV bridge	`wasm-plugins`	yes (via Demo 11)	Per-plugin namespaced state survives across hook invocations
4	Plugin host crypto	`wasm-plugins`	walkthrough	RFC 6234 SHA-256 vector check + audit-chain producing real digests
5	Plugin Ed25519 signatures	`wasm-plugins`	yes	openssl-signed `.wasm` loads; tampered or unsigned refuses
6	Plugin OCI artefact loader	`wasm-plugins`	yes	`helios-plugin pack` → drop tarball → proxy loads + validates SHA-256
7	`RouteResult::Block`	`wasm-plugins`	yes (via Demo 18)	Route hook produces clean PG `ErrorResponse` on rejection
8	`trust_root` config knob	`wasm-plugins`	walkthrough	Same proxy binary, different TOML → permissive vs enforced
9	Admin Web UI	(always-on)	yes	10-panel dashboard at `http://localhost:9090/`, auto-refresh
10	Admin REST API tour	(always-on)	yes	`curl` tour of all 8 new endpoints
11	Plugin: cost-governor	companion plugin	yes	Per-tenant budget exhaustion → block; recovery after window resets
12	Plugin: ai-classifier	companion plugin	yes	LLM detection from `application_name` keywords + generated-by markers
13	Plugin: token-budget	companion plugin	yes	Per-`(agent, model)` cost gate for AI traffic
14	Plugin: llm-guardrail	companion plugin	yes	DROP, missing WHERE, missing tenant_id all refused for AI traffic
15	Plugin: pgvector-router	companion plugin	yes	Vector top-K → pg-vector replica; non-vector → pg-primary
16	Plugin: column-mask	companion plugin	yes	Same query, different roles, masked vs raw PII
17	Plugin: audit-chain	companion plugin	yes	Hash-chained tamper-evident log; verify_chain catches mutation
18	Plugin: residency-router	companion plugin	yes	EU users → EU replica; US users → US replica; unknown region → block
19	`helios-plugin` CLI	(build tool)	walkthrough	Pack/inspect/verify with openssl-generated key
20	Kubernetes operator	companion operator	yes (kind cluster)	One CR brings up ConfigMap + Deployment + Service; status flips Pending → Ready
21	Terraform provider	companion Terraform provider	walkthrough (needs Demo 20)	Five resources via `main.tf`; Terraform-tracked state
22	Pulumi provider	companion Pulumi provider	walkthrough (needs Demo 20)	Same five resources via TypeScript

Shared assets

The _shared/ directory next to the demos contains files multiple demos depend on:

proxy.base.toml — minimal proxy config
init.sql — sample schema (users + orders + events) with mask functions and roles
wait-for.sh — TCP-port poller used by every demo.sh
plugin-demo.sh — shared bring-up logic sourced by per-plugin demos

Backend

Every demo uses postgres:17-alpine as the default backend so docker compose up works on any laptop.

Container image

The demo compose files in the repo pin the older proxy image tag they were last fixed against (that fix also replaced a local build: context that no longer exists). To run them against the current release, swap the image: line for ghcr.io/heliosdatabase/hdb-heliosdb-proxy:latest or a current release tag; the admin API now binds loopback by default, so a demo that reaches the admin port across the compose network needs admin_address (and admin_token) set explicitly.

The image is published by the docker workflow on each release tag (the release version, its major.minor line, and latest); if you’re running against an unreleased build, swap the image: line for build: pointing at your local proxy repo.

Where to file improvements

github.com/HeliosDatabase/HeliosDB-Proxy/issues — one issue per demo, please. Pull requests welcome; new demos follow the layout described at the top of this file.