---
title: "HeliosProxy v0.4 — From Connection Router to Programmable Data-Plane"
description: "Real WASM plugin runtime, signed-plugin distribution via OCI, time-travel replay, zero-downtime PG major-version upgrade orchestrator, built-in admin console. Largest release in the project's history."
date: 2026-04-25
updated: 2026-04-25
tag: "Release"
canonical: https://www.heliosdb.com/blog/heliosproxy-0-4-programmable-data-plane.html
---

# 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](https://www.heliosdb.com/blog/heliosproxy-1-7-0-verified-transaction-replay.html) 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](https://www.heliosdb.com/heliosproxy.html). 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](https://www.heliosdb.com/blog/zero-downtime-postgresql-major-upgrades.html) 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`](https://github.com/dimensigon/HDB-HeliosDB-Proxy-Plugins) — the eight first-party plugins + `helios-plugin` CLI for packing, inspecting, and verifying `.tar.gz` artefacts.
- [`HDB-HeliosDB-Proxy-Operator`](https://github.com/dimensigon/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`](https://github.com/dimensigon/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`](https://github.com/dimensigon/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](https://www.heliosdb.com/blog/zero-downtime-postgresql-major-upgrades.html) 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](https://github.com/dimensigon/HDB-HeliosDB-Proxy).