Add runnable HAProxy-style routing policy example

Author: eldryoth

CHANGELOG.md

@@ -18,6 +18,9 @@ behavior when the change improves security or project direction.
   opt-in Wasm release gate.
 - Add the checked-in nginx Lua/OpenResty-style bounded request/response header
   policy and config example, compiled directly by its real listener tests.
+- Add the checked-in HAProxy Lua/SPOE-style symbolic route policy and config
+  example, with live canary, load-balancer, persistence, mirror, and selected
+  route-policy coverage.
 
 ### Security
 

crates/fluxheim-config/src/config_tests_wasm.rs

@@ -55,6 +55,17 @@ fn openresty_header_policy_example_config_validates() {
     assert_eq!(config.validate(), Ok(()));
 }
 
+#[cfg(feature = "wasm")]
+#[test]
+fn haproxy_spoe_routing_policy_example_config_validates() {
+    let config: Config = toml::from_str(include_str!(
+        "../../../examples/wasm/haproxy-spoe-routing-policy.toml"
+    ))
+    .unwrap();
+
+    assert_eq!(config.validate(), Ok(()));
+}
+
 #[cfg(feature = "wasm")]
 fn proxy_preview_wasm_config(plugin_fields: &str) -> Config {
     toml::from_str(&format!(

crates/fluxheim-server/src/native_http1_route_proxy_tests/wasm.rs

@@ -536,7 +536,8 @@ async fn native_wasm_forbidden_header_mutation_fails_closed() {
 
 #[tokio::test]
 async fn native_wasm_route_decision_selects_configured_canary_route() {
-    let fixture = WasmRouteFixture::new(&[("router", WasmPluginBody::RouteDecision)]);
+    let fixture =
+        WasmRouteFixture::new(&[("router", WasmPluginBody::HaProxySpoeRoutingPolicyExample)]);
     let stable = upstream_expect_body("/lb/item", "stable").await;
     let canary = upstream_expect_body("/lb/item", "canary").await;
     let mut config = fixture.config_with_attachments(
@@ -567,7 +568,8 @@ async fn native_wasm_route_decision_selects_configured_canary_route() {
 
 #[tokio::test]
 async fn native_wasm_route_decision_fails_closed_for_unconfigured_branch() {
-    let fixture = WasmRouteFixture::new(&[("router", WasmPluginBody::RouteDecision)]);
+    let fixture =
+        WasmRouteFixture::new(&[("router", WasmPluginBody::HaProxySpoeRoutingPolicyExample)]);
     let stable = upstream_expect_body("/lb/item", "stable").await;
     let mut config = fixture.config_with_attachments(
         stable,
@@ -594,7 +596,8 @@ async fn native_wasm_route_decision_fails_closed_for_unconfigured_branch() {
 
 #[tokio::test]
 async fn native_wasm_route_decision_does_not_run_before_route_acl() {
-    let fixture = WasmRouteFixture::new(&[("router", WasmPluginBody::RouteDecision)]);
+    let fixture =
+        WasmRouteFixture::new(&[("router", WasmPluginBody::HaProxySpoeRoutingPolicyExample)]);
     let upstream = super::upstream_expect_path("/never", "unexpected").await;
     let mut config = fixture.config_with_attachments(
         upstream,
@@ -624,7 +627,8 @@ async fn native_wasm_route_decision_does_not_run_before_route_acl() {
 
 #[tokio::test]
 async fn native_wasm_route_decision_enforces_selected_route_rate_limit() {
-    let fixture = WasmRouteFixture::new(&[("router", WasmPluginBody::RouteDecision)]);
+    let fixture =
+        WasmRouteFixture::new(&[("router", WasmPluginBody::HaProxySpoeRoutingPolicyExample)]);
     let stable = upstream_expect_body("/limit/item", "stable").await;
     let canary = upstream_expect_body("/limit/item", "canary").await;
     let mut config = fixture.config_with_attachments(
@@ -671,7 +675,8 @@ async fn native_wasm_route_decision_enforces_selected_route_rate_limit() {
 #[cfg(feature = "load-balancer")]
 #[tokio::test]
 async fn native_wasm_route_decision_selects_configured_load_balanced_route() {
-    let fixture = WasmRouteFixture::new(&[("router", WasmPluginBody::RouteDecision)]);
+    let fixture =
+        WasmRouteFixture::new(&[("router", WasmPluginBody::HaProxySpoeRoutingPolicyExample)]);
     let stable = upstream_expect_body("/lb/item", "stable").await;
     let canary_a = upstream_expect_body("/lb/item", "canary-a").await;
     let canary_b = upstream_expect_body("/lb/item", "canary-b").await;
@@ -707,7 +712,8 @@ async fn native_wasm_route_decision_selects_configured_load_balanced_route() {
 #[cfg(feature = "load-balancer")]
 #[tokio::test]
 async fn native_wasm_route_decision_selects_configured_persistent_route() {
-    let fixture = WasmRouteFixture::new(&[("router", WasmPluginBody::RouteDecision)]);
+    let fixture =
+        WasmRouteFixture::new(&[("router", WasmPluginBody::HaProxySpoeRoutingPolicyExample)]);
     let stable = upstream_expect_body("/sticky/item", "stable").await;
     let sticky_a = upstream_body_loop("sticky-a", 2).await;
     let sticky_b = upstream_body_loop("sticky-b", 2).await;
@@ -757,7 +763,8 @@ async fn native_wasm_route_decision_selects_configured_persistent_route() {
 #[cfg(all(feature = "traffic-mirror", not(feature = "privacy-mode")))]
 #[tokio::test]
 async fn native_wasm_route_decision_selects_configured_mirror_route() {
-    let fixture = WasmRouteFixture::new(&[("router", WasmPluginBody::RouteDecision)]);
+    let fixture =
+        WasmRouteFixture::new(&[("router", WasmPluginBody::HaProxySpoeRoutingPolicyExample)]);
     let origin = upstream_expect_body("/shadow/item", "origin").await;
     let (mirror, mirror_rx) = mirror_endpoint().await;
     let mut config = fixture.config_with_attachments(
@@ -1169,7 +1176,7 @@ async fn native_wasm_cross_family_chain_runs_in_order_with_cache_hit_metadata()
     let fixture = WasmRouteFixture::new(&[
         ("access", WasmPluginBody::Decision(1)),
         ("headers", WasmPluginBody::OpenRestyHeaderPolicyExample),
-        ("router", WasmPluginBody::RouteDecision),
+        ("router", WasmPluginBody::HaProxySpoeRoutingPolicyExample),
         ("cache_key", WasmPluginBody::CacheLookupDeviceKey),
         ("cache_store", WasmPluginBody::CacheStoreHeader),
     ]);
@@ -1904,7 +1911,7 @@ enum WasmPluginBody {
     IrulesAccessPolicyExample,
     OpenRestyHeaderPolicyExample,
     ForbiddenHeader,
-    RouteDecision,
+    HaProxySpoeRoutingPolicyExample,
     CacheLookup,
     CacheLookupDeviceKey,
     CacheLookupForbiddenKey,
@@ -1960,32 +1967,9 @@ impl WasmPluginBody {
                 "#
                 .to_owned()
             }
-            Self::RouteDecision => {
-                r#"
-                (module
-                  (import "fluxheim_policy_v1" "context" (func $context (param i32 i32) (result i32)))
-                  (func (export "fluxheim_route_decision") (result i32)
-                    i32.const 3
-                    i32.const 0
-                    call $context
-                    i32.const 1
-                    i32.eq
-                    if (result i32)
-                      i32.const 3
-                    else
-                      i32.const 2
-                      i32.const 0
-                      call $context
-                      i32.const 1
-                      i32.eq
-                      if (result i32)
-                        i32.const 1
-                      else
-                        i32.const 0
-                      end
-                    end))
-                "#
-                .to_owned()
+            Self::HaProxySpoeRoutingPolicyExample => {
+                include_str!("../../../../examples/wasm/haproxy-spoe-routing-policy.wat")
+                    .to_owned()
             }
             Self::CacheLookup => {
                 r#"
@@ -2332,7 +2316,9 @@ fn wasm_plugin_phases(body: WasmPluginBody) -> Vec<fluxheim_config::WasmPluginPh
         WasmPluginBody::ForbiddenHeader => {
             vec![fluxheim_config::WasmPluginPhase::RequestHeaders]
         }
-        WasmPluginBody::RouteDecision => vec![fluxheim_config::WasmPluginPhase::RouteDecision],
+        WasmPluginBody::HaProxySpoeRoutingPolicyExample => {
+            vec![fluxheim_config::WasmPluginPhase::RouteDecision]
+        }
         WasmPluginBody::CacheLookup
         | WasmPluginBody::CacheLookupDeviceKey
         | WasmPluginBody::CacheLookupForbiddenKey

docs/wasm-policy-example-parity.md

@@ -132,6 +132,14 @@ The hook can continue, deny, or select a configured matching branch; arbitrary
 pool names, persistence keys, and mirror/shadow target decisions remain staged
 for later `1.7.x` slices.
 
+The `v1.7.9` runnable mapping is checked in as
+`examples/wasm/haproxy-spoe-routing-policy.wat` with a complete config fixture.
+The shared live smoke compiles that source and proves configured canary route
+selection, unavailable-branch fail-closed behavior, selected-route policy
+enforcement, native load-balancer selection, managed-cookie persistence, and
+safe configured mirror routing. Backend addresses, arbitrary persistence keys,
+and mirror URLs remain outside the guest ABI.
+
 ### VCL-Like Cache Policy
 
 Capability target:

examples/wasm/README.md

@@ -31,6 +31,18 @@ cannot create arbitrary names or values. Unknown IDs, duplicate/oversized
 mutations, traps, timeouts, and admission failures follow the configured fail
 mode; security-sensitive examples use `fail-closed`.
 
+`haproxy-spoe-routing-policy.wat` and
+`haproxy-spoe-routing-policy.toml` demonstrate the HAProxy Lua/SPOE-style
+routing mapping. The guest receives only bounded `x-canary: 1` and
+`x-mirror: 1` signals. It may continue normal selection or choose an existing
+matching route named `canary` or `mirror`; it cannot name an arbitrary pool,
+backend, URL, persistence key, or TLS policy.
+
+The selected route still passes its own ACL, rate-limit, concurrency,
+load-balancer, health, persistence, retry, and traffic-mirror controls. If the
+symbolic branch is not configured and still valid for the request, selection
+fails closed instead of falling back to an attacker-chosen destination.
+
 `cache-lookup-policy.wat` and `cache-store-policy.wat` demonstrate the bounded
 1.7.5 cache-policy ABI:
 

examples/wasm/haproxy-spoe-routing-policy.toml

@@ -0,0 +1,55 @@
+# Compile haproxy-spoe-routing-policy.wat to the configured .wasm path and
+# replace the sha256 placeholder with the compiled module digest before use.
+
+[wasm]
+enabled = true
+plugin_roots = ["/etc/fluxheim/plugins"]
+max_total_concurrent_executions = 256
+
+[[wasm.plugins]]
+name = "traffic_branch_policy"
+path = "/etc/fluxheim/plugins/haproxy-spoe-routing-policy.wasm"
+sha256 = "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
+abi = "fluxheim-policy-v1"
+host_call_namespace = "fluxheim-policy-v1"
+phases = ["route-decision"]
+fail_mode = "fail-closed"
+
+[wasm.plugins.limits]
+max_module_bytes = "1MiB"
+max_memory_bytes = "16MiB"
+max_table_elements = 10000
+fuel = 5000000
+timeout_ms = 50
+compile_timeout_ms = 500
+
+[[wasm.attachments]]
+plugin = "traffic_branch_policy"
+vhost = "example"
+priority = 100
+phases = ["route-decision"]
+
+[[vhosts]]
+name = "example"
+hosts = ["example.com"]
+
+[[vhosts.routes]]
+name = "standard"
+path_prefix = "/app/"
+
+[vhosts.routes.proxy]
+upstreams = ["127.0.0.1:3000"]
+
+[[vhosts.routes]]
+name = "canary"
+path_prefix = "/app/"
+
+[vhosts.routes.proxy]
+upstreams = ["127.0.0.1:3001"]
+
+[[vhosts.routes]]
+name = "mirror"
+path_prefix = "/app/"
+
+[vhosts.routes.proxy]
+upstreams = ["127.0.0.1:3000"]

examples/wasm/haproxy-spoe-routing-policy.wat

@@ -0,0 +1,28 @@
+(module
+  (import "fluxheim_policy_v1" "context"
+    (func $context (param i32 i32) (result i32)))
+
+  (func (export "fluxheim_route_decision") (result i32)
+    ;; Context field 3 reports the bounded x-mirror: 1 signal. Decision 3
+    ;; selects only an already configured matching route named "mirror".
+    i32.const 3
+    i32.const 0
+    call $context
+    i32.const 1
+    i32.eq
+    if (result i32)
+      i32.const 3
+    else
+      ;; Context field 2 reports x-canary: 1. Decision 1 selects only an
+      ;; already configured matching route named "canary".
+      i32.const 2
+      i32.const 0
+      call $context
+      i32.const 1
+      i32.eq
+      if (result i32)
+        i32.const 1
+      else
+        i32.const 0
+      end
+    end))

packaging/rpm/fluxheim.spec

@@ -158,6 +158,7 @@ fi
 - Start documented and runnable Wasm migration-example parity work.
 - Add the F5 iRules-style route access example and real listener smoke.
 - Add the nginx Lua/OpenResty-style bounded header-policy example.
+- Add the HAProxy Lua/SPOE-style bounded route and load-balancer example.
 - Harden snapshot opens against pathname races and isolate corruption fixtures
   behind safe store primitives.
 

release-notes/RELEASE_NOTES_1.7.9.md

@@ -19,6 +19,10 @@ products.
   fixture. Live coverage proves the allow-listed origin request mutation,
   client response mutation, upstream-header removal, and fail-closed rejection
   of unknown mutation IDs.
+- Add a checked-in HAProxy Lua/SPOE-style route policy and complete config
+  fixture. Live coverage proves symbolic canary/mirror selection, unavailable
+  branch rejection, selected-route policy enforcement, native load balancing,
+  and managed-cookie persistence without exposing backend addresses.
 
 ## Security
 

scripts/smoke_wasm_policy_examples.sh

@@ -9,5 +9,8 @@ cargo test --locked -p fluxheim-server --features wasm \
     native_wasm_openresty_header_policy_example_uses_bounded_host_calls
 cargo test --locked -p fluxheim-server --features wasm \
     native_wasm_forbidden_header_mutation_fails_closed
+cargo test --locked -p fluxheim-server \
+    --features "wasm,load-balancer,traffic-mirror" \
+    native_wasm_route_decision
 
 echo "wasm policy examples smoke: ok"