Home / Blog / HeliosProxy v0.4 — From Connection Router to Programmable Data-Plane
Release 10 min read

HeliosProxy v0.4 — From Connection Router to Programmable Data-Plane

Superseded. Two bullets below overstate what survives a failover: cursor recreation and PREPARE / CREATE TEMP TABLE session migration are library modules that are not wired to the recovery path. Open cursors, SQL-level prepared statements, session temp tables and advisory locks are not restored across a failover. See HeliosProxy 1.7.0 for what is.

HeliosProxy v0.3.x was a connection router with feature flags. v0.4.0 is something different. The proxy now ships a real WASM plugin runtime, signed plugin distribution via OCI, a time-travel replay engine, a zero-downtime PostgreSQL major-version upgrade orchestrator, and a built-in admin web console — alongside the 24 feature modules already there. 22 new modules at the same granularity bring the platform to 46 total.

Plus: the licence moved from SSPL-1.0 to Apache 2.0. Permissive, OSI-approved, and aligned with HeliosDB Nano — no copyleft, no managed-service ambiguity, friction-free for commercial and proprietary deployments.

The 22 New Modules at a Glance

Category Modules
Top-level Cargo features (2)anomaly-detection, edge-proxy
Plugin platform extensions (6)Host KV bridge, host crypto (env.sha256_hex), Ed25519 signature verification, OCI artefact loader, RouteResult::Block ABI, trust_root config knob
Admin surface (2)Single embedded admin web UI (10 panels), expanded admin REST v2 (8 new endpoints)
First-party plugins (8)cost-governor, ai-classifier, token-budget, llm-guardrail, pgvector-router, column-mask, audit-chain, residency-router
Companion projects (4)helios-plugin CLI, Kubernetes operator, Terraform provider, Pulumi provider

The full module list is on the HeliosProxy page. The rest of this post walks through the highest-leverage themes.

Real WASM Plugin Runtime

v0.3.x had a WASM plugin slot in the architecture diagram. v0.4.0 makes it real. Wasmtime executes plugins inside the proxy with sandboxed memory, fuel-metered execution, and five hook points covering the full request lifecycle:

  • Authenticate — runs during startup auth.
  • Route — can pick a backend, rewrite, or return RouteResult::Block.
  • PreQuery — runs before query forwarding.
  • PostQuery — runs after the backend responds.
  • Validate — runs on extended-protocol parse messages.

Authoring is a Rust crate compiled to wasm32-wasi. Host imports cover what plugins actually need: a KV namespace bridge, env.sha256_hex, request-view accessors. Cached responses can be synthesised as PG wire frames so a plugin can answer a query directly.

# Plugin lifecycle, end to end

# 1. Author
cargo new --lib auth-plugin
cargo build --release --target wasm32-wasi

# 2. Sign with your Ed25519 key
cargo helios-plugin sign \
  --key   ./signing.key \
  --input target/wasm32-wasi/release/auth_plugin.wasm

# 3. Push to any OCI registry
oras push registry.example.com/my-org/auth-plugin:v1 \
  ./auth_plugin.wasm.tar.gz

# 4. Reference in the proxy config
[[plugins]]
name        = "auth"
source      = "oci://registry.example.com/my-org/auth-plugin:v1"
hooks       = ["Authenticate", "PreQuery"]
verify_with = "./trusted-keys.toml"

Signed Plugins, OCI-Distributed

Every plugin in v0.4.0 is signed with Ed25519 and verified at load time. SignatureVerifier is wired into the runtime configuration. Distribution is OCI-native — .tar.gz artefacts pulled from any OCI registry. Sign once, push to your registry, point the proxy at the OCI URL.

Time-Travel Replay

Every transaction the proxy sees is journalled. v0.4.0 adds a replay engine over journal windows, plus admin endpoints and a UI form. Replay any historical window against the current cluster, a standby, or a brand-new candidate. Per-call credential overrides let you replay traffic that ran as user A as user B.

POST /api/replay
{
  "from":      "2026-04-26T10:00:00Z",
  "to":        "2026-04-26T11:00:00Z",
  "target":    "candidate-pg17",
  "as_user":   "audit_replay",
  "shadow":    true,
  "diff_mode": "rows"
}

The shadow-execution comparator runs identical traffic against two backends and diffs the result. The combination — replay + shadow — is the strongest incident-prevention surface in v0.4.

Zero-Downtime PostgreSQL Major-Version Upgrades

The hardest operational task on Postgres is a major-version upgrade. v0.4.0 puts the orchestration inside the proxy. Stages execute on a tick schedule. Each runs real SQL bodies against both the old and new backend. Chaos-mode injects failures during rehearsal. Shadow-execution validates equivalence across a window you specify.

A dedicated post tomorrow covers the orchestrator in detail.

Real Backend, Real Failover

v0.3.x simulated a lot of the backend interaction. v0.4.0 replaces every simulation with a real implementation:

  • Real backend connections in ConnectionPool.
  • Real pg_is_in_recovery() polling for primary tracking.
  • Real PG-backed health checks.
  • Real pg_promote + WAL probe sync-wait for failover.
  • Real statement replay + WAL sync.
  • Real DECLARE / MOVE cursor recreation.
  • Real SET / PREPARE / CREATE TEMP TABLE session migration.

The Oracle-grade TAF / TAC story now has a real backend behind it.

Eight First-Party Plugins

v0.4 ships eight signed first-party plugins as concrete demonstrations of the platform — and as production-ready building blocks:

  • cost-governor — Per-tenant query cost budgets (minute / hour / day windows), sliding window in KV, thresholds via the operator's TenantQuota CRD.
  • ai-classifier — Detects LLM-generated SQL (application_name keywords, generated-by markers, opt-in attributes), best-effort agent_id + model_id extraction.
  • token-budget — Per-(agent, model) cost gating for AI traffic. Sliding-window minute + day in KV. Cost model assumes ~4 bytes per token.
  • llm-guardrail — Refuses dangerous SQL from AI traffic: DROP/TRUNCATE, DELETE/UPDATE without WHERE, missing tenant_id filter. Self-contained — useful even without ai-classifier.
  • pgvector-router — Routes pgvector top-K queries to a topology-tagged vector replica. Falls back to default routing when no tagged node exists.
  • column-mask — Per-role column masking via SQL rewriting. SELECT ssn → SELECT mask_ssn(ssn) when the user lacks the unmask role.
  • audit-chain — Hash-chained tamper-evident audit log with real SHA-256 (was a placeholder in v0.3.x).
  • residency-router — Per-user data-residency routing. Reads helios.region; routes to in-region replica or returns RouteResult::Block.

Anomaly Detection & Edge Mode

Two new top-level Cargo features extend the proxy's role beyond connection routing:

  • Anomaly Detection — In-process detector for rate spikes (z-score against rolling EWMA), credential-stuffing bursts, six classes of SQL-injection patterns, and novel query shapes. Fires before the WASM plugin pre-query hook so detections land in the audit trail even when a plugin later blocks the query.
  • Edge Mode — Cache-first proxy for geo-distributed deployments. Local LRU+TTL+version cache on every edge; home broadcasts table-scoped invalidations on writes via EdgeRegistry::broadcast. Last-write-wins, no consensus, no vector clocks — the simplest model that actually works for "eventual consistency with bounded staleness".

Built-in Admin Console

A static admin web UI ships at / and /ui. Ten panels: Nodes, Topology, Plugins, Anomalies, Edge Mode, Chaos Mode, Shadow Execution, Time-Travel Replay, SQL, Traffic. Auto-refreshes every 5 s. Each panel is feature-gated — a 503 from the underlying endpoint shows a friendly "X not attached" message rather than spinning. The UI is static HTML/JS served from the same binary via include_str! — no Node.js, no build step, no second container.

Companion Projects

Four sibling repositories ship at v0.4:

  • HDB-HeliosDB-Proxy-Plugins — the eight first-party plugins + helios-plugin CLI for packing, inspecting, and verifying .tar.gz artefacts.
  • HDB-HeliosDB-Proxy-Operator — Kubernetes operator with five CRDs (HeliosProxy, PoolProfile, RoutingRule, AuditPolicy, TenantQuota). Renders ConfigMap + Deployment + Service per CR; polls /topology for status.
  • terraform-provider-HDB-HeliosDB-Proxy — five resources mirror the operator CRDs, schema imported from the operator's Go types so they don't drift.
  • pulumi-HDB-HeliosDB-Proxy — built on top of the Terraform provider via pulumi-terraform-bridge; ships TypeScript / Python / Go / .NET SDKs.

Container image: ghcr.io/dimensigon/hdb-heliosdb-proxy:0.4.0 (lowercase due to GHCR convention; the GitHub repo keeps the mixed-case form).

Migration from v0.3.x

Drop-in. No config changes required. Plugin loading, the upgrade orchestrator, the admin UI, and the replay engine are opt-in. The license switch is the only operational change — Apache 2.0 is permissive and removes the SSPL-1.0 managed-service ambiguity; consult counsel if you have specific compliance questions.

What's Next

Tomorrow's post covers the upgrade orchestrator in detail — the wedge into the PG-12-EOL migration market.

HeliosProxy is open source under Apache 2.0. Repository: github.com/dimensigon/HDB-HeliosDB-Proxy.

← Back to Blog