Add runnable iRules-style Wasm policy example

Author: eldryoth

CHANGELOG.md

@@ -9,6 +9,14 @@ behavior when the change improves security or project direction.
 
 ## 1.7.9 - Unreleased
 
+### Added
+
+- Add the checked-in F5 iRules-style route access policy and configuration
+  example, with real listener coverage for normal origin traffic, pre-origin
+  denial, and fail-closed plugin traps.
+- Add a dedicated Wasm policy-example smoke to the human test starter and the
+  opt-in Wasm release gate.
+
 ### Security
 
 - Open snapshot files with no-follow semantics before validating the opened

crates/fluxheim-config/src/config_tests_wasm.rs

@@ -33,6 +33,17 @@ fn base_wasm_config(extra: &str) -> Config {
     .unwrap()
 }
 
+#[cfg(feature = "wasm")]
+#[test]
+fn irules_access_policy_example_config_validates() {
+    let config: Config = toml::from_str(include_str!(
+        "../../../examples/wasm/irules-access-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

@@ -33,6 +33,30 @@ async fn native_wasm_access_decision_denies_before_upstream() {
     assert!(response.ends_with("wasm access denied\n"));
 }
 
+#[tokio::test]
+async fn native_wasm_irules_policy_example_allows_public_and_denies_admin() {
+    let fixture =
+        WasmRouteFixture::new(&[("irules_policy", WasmPluginBody::IrulesAccessPolicyExample)]);
+    let upstream = super::upstream_expect_path("/public", "public origin").await;
+    let mut config = fixture.config_with_attachments(
+        upstream,
+        vec![wasm_attachment("irules_policy", "admin", 100)],
+    );
+    config.vhosts[0].routes[0].name = "admin".to_owned();
+    config.vhosts[0].routes[0].path_exact = Some("/admin".to_owned());
+    let router =
+        NativeHttp1HostRouter::from_config(&config, DownstreamHttp1Policy::default(), 0).unwrap();
+    let proxy = router_listener(router).await;
+
+    let allowed = downstream_get(proxy, "/public").await;
+    assert!(allowed.starts_with("HTTP/1.1 200 OK\r\n"));
+    assert!(allowed.ends_with("public origin"));
+
+    let denied = downstream_get(proxy, "/admin").await;
+    assert!(denied.starts_with("HTTP/1.1 403 Forbidden\r\n"));
+    assert!(denied.ends_with("wasm access denied\n"));
+}
+
 #[tokio::test]
 async fn native_wasm_access_decision_uses_first_deny_in_priority_order() {
     let fixture = WasmRouteFixture::new(&[
@@ -1875,6 +1899,7 @@ impl WasmRouteFixture {
 #[derive(Clone, Copy)]
 enum WasmPluginBody {
     Decision(i32),
+    IrulesAccessPolicyExample,
     HeaderPolicy,
     ForbiddenHeader,
     RouteDecision,
@@ -1897,8 +1922,11 @@ enum WasmPluginBody {
     Trap,
     #[cfg(feature = "wasm-proxy-abi")]
     ProxyPreviewLogCall,
+    #[cfg(feature = "wasm-wasi")]
     WasiRandomGranted,
+    #[cfg(feature = "wasm-wasi")]
     WasiRandomDenied,
+    #[cfg(feature = "wasm-wasi")]
     WasiForbiddenFdWrite,
     BusyLoop,
 }
@@ -1911,6 +1939,9 @@ impl WasmPluginBody {
                     r#"(module (func (export "fluxheim_access_decision") (result i32) i32.const {decision}))"#
                 )
             }
+            Self::IrulesAccessPolicyExample => {
+                include_str!("../../../../examples/wasm/irules-access-policy.wat").to_owned()
+            }
             Self::HeaderPolicy => {
                 r#"
                 (module
@@ -2203,6 +2234,7 @@ impl WasmPluginBody {
                 "#
                 .to_owned()
             }
+            #[cfg(feature = "wasm-wasi")]
             Self::WasiRandomGranted | Self::WasiRandomDenied => {
                 r#"
                 (module
@@ -2216,6 +2248,7 @@ impl WasmPluginBody {
                 "#
                 .to_owned()
             }
+            #[cfg(feature = "wasm-wasi")]
             Self::WasiForbiddenFdWrite => {
                 r#"
                 (module
@@ -2264,12 +2297,15 @@ fn wasm_plugin(root: &Path, name: &str, body: WasmPluginBody) -> fluxheim_config
     let proxy_preview = matches!(body, WasmPluginBody::ProxyPreviewLogCall);
     #[cfg(not(feature = "wasm-proxy-abi"))]
     let proxy_preview = false;
+    #[cfg(feature = "wasm-wasi")]
     let wasi_preview = matches!(
         body,
         WasmPluginBody::WasiRandomGranted
             | WasmPluginBody::WasiRandomDenied
             | WasmPluginBody::WasiForbiddenFdWrite
     );
+    #[cfg(not(feature = "wasm-wasi"))]
+    let wasi_preview = false;
     fluxheim_config::WasmPluginConfig {
         name: name.to_owned(),
         path,
@@ -2289,11 +2325,29 @@ fn wasm_plugin(root: &Path, name: &str, body: WasmPluginBody) -> fluxheim_config
             fluxheim_config::WasmHostCallNamespace::FluxheimPolicyV1
         },
         wasi: fluxheim_config::WasmWasiCapabilitiesConfig {
-            clocks: matches!(body, WasmPluginBody::WasiForbiddenFdWrite),
-            randomness: matches!(
-                body,
-                WasmPluginBody::WasiRandomGranted | WasmPluginBody::WasiForbiddenFdWrite
-            ),
+            clocks: {
+                #[cfg(feature = "wasm-wasi")]
+                {
+                    matches!(body, WasmPluginBody::WasiForbiddenFdWrite)
+                }
+                #[cfg(not(feature = "wasm-wasi"))]
+                {
+                    false
+                }
+            },
+            randomness: {
+                #[cfg(feature = "wasm-wasi")]
+                {
+                    matches!(
+                        body,
+                        WasmPluginBody::WasiRandomGranted | WasmPluginBody::WasiForbiddenFdWrite
+                    )
+                }
+                #[cfg(not(feature = "wasm-wasi"))]
+                {
+                    false
+                }
+            },
         },
         phases: wasm_plugin_phases(body),
         fail_mode: fluxheim_config::WasmPluginFailMode::FailClosed,
@@ -2337,11 +2391,15 @@ fn wasm_plugin_phases(body: WasmPluginBody) -> Vec<fluxheim_config::WasmPluginPh
             vec![fluxheim_config::WasmPluginPhase::CacheStore]
         }
         WasmPluginBody::Decision(_)
+        | WasmPluginBody::IrulesAccessPolicyExample
         | WasmPluginBody::Trap
-        | WasmPluginBody::WasiRandomGranted
-        | WasmPluginBody::WasiRandomDenied
-        | WasmPluginBody::WasiForbiddenFdWrite
         | WasmPluginBody::BusyLoop => vec![fluxheim_config::WasmPluginPhase::AccessDecision],
+        #[cfg(feature = "wasm-wasi")]
+        WasmPluginBody::WasiRandomGranted
+        | WasmPluginBody::WasiRandomDenied
+        | WasmPluginBody::WasiForbiddenFdWrite => {
+            vec![fluxheim_config::WasmPluginPhase::AccessDecision]
+        }
         #[cfg(feature = "wasm-proxy-abi")]
         WasmPluginBody::ProxyPreviewLogCall => {
             vec![fluxheim_config::WasmPluginPhase::AccessDecision]

docs/wasm-policy-example-parity.md

@@ -48,6 +48,15 @@ Required live test:
 
 Target release: `v1.7.1`.
 
+Status: the checked-in `examples/wasm/irules-access-policy.wat` and
+`examples/wasm/irules-access-policy.toml` pair packages the bounded
+access-decision subset as a runnable `v1.7.9` migration example. Fluxheim owns
+host/path/method/trusted-client/TLS classification; the route-scoped plugin can
+continue, allow, or deny and cannot inspect arbitrary request state. The live
+listener smoke proves an unattached public request reaches origin, the attached
+admin request receives the plugin's 403 before origin dispatch, and a trapping
+plugin fails closed.
+
 ### nginx Lua/OpenResty-Style Header Policy
 
 Capability target:

examples/wasm/README.md

@@ -5,6 +5,20 @@ These examples are source-level policy examples. Build the `.wat` files to
 `wasm.plugin_roots`, and pin the module SHA-256 in config before enabling it in
 production.
 
+`irules-access-policy.wat` and `irules-access-policy.toml` demonstrate the
+F5 iRules-style access-policy mapping. Fluxheim first classifies the request
+through configured vhosts, routes, methods, trusted-client ACLs, and TLS
+policy. The example plugin is attached only to the bounded `admin` route and
+returns the typed deny decision, producing a small fixed 403 response before
+origin dispatch. Requests outside that attachment continue normally. A trap,
+timeout, invalid result, or admission failure follows `fail_mode =
+"fail-closed"` and cannot silently bypass the policy.
+
+This is capability parity, not Tcl syntax compatibility. The access-decision
+module receives no raw headers, body, filesystem, network, admin-token, or TLS
+secret capability. Use native route and access configuration for classification
+instead of attempting arbitrary parsing inside the plugin.
+
 `cache-lookup-policy.wat` and `cache-store-policy.wat` demonstrate the bounded
 1.7.5 cache-policy ABI:
 

examples/wasm/irules-access-policy.toml

@@ -0,0 +1,45 @@
+# Compile irules-access-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 = "admin_route_policy"
+path = "/etc/fluxheim/plugins/irules-access-policy.wasm"
+sha256 = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+abi = "fluxheim-policy-v1"
+host_call_namespace = "fluxheim-policy-v1"
+phases = ["access-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 = "admin_route_policy"
+vhost = "example"
+route = "admin"
+priority = 100
+phases = ["access-decision"]
+
+[[vhosts]]
+name = "example"
+hosts = ["example.com"]
+
+[vhosts.proxy]
+upstreams = ["127.0.0.1:3000"]
+
+[[vhosts.routes]]
+name = "admin"
+path_prefix = "/admin/"
+
+[vhosts.routes.proxy]
+upstreams = ["127.0.0.1:3000"]

examples/wasm/irules-access-policy.wat

@@ -0,0 +1,5 @@
+(module
+  ;; This policy is attached only to the configured admin route. Fluxheim
+  ;; performs path and client classification before invoking the module.
+  (func (export "fluxheim_access_decision") (result i32)
+    i32.const 2))

packaging/rpm/fluxheim.spec

@@ -156,6 +156,7 @@ fi
 %changelog
 * Sun Jul 12 2026 Fluxheim Maintainers <1921261+eldryoth@users.noreply.github.com> - 1.7.9-1
 - Start documented and runnable Wasm migration-example parity work.
+- Add the F5 iRules-style route access example and real listener smoke.
 - Harden snapshot opens against pathname races and isolate corruption fixtures
   behind safe store primitives.
 

release-notes/RELEASE_NOTES_1.7.9.md

@@ -6,6 +6,16 @@ and VCL-style policy jobs into Fluxheim's typed WebAssembly policy ABI. It
 provides capability mappings, not syntax or runtime compatibility with those
 products.
 
+## Added
+
+- Add a checked-in F5 iRules-style route access policy and complete config
+  fixture using Fluxheim's typed access-decision ABI.
+- Add real listener coverage proving public requests reach origin, attached
+  admin requests are denied before origin dispatch, and plugin traps fail
+  closed.
+- Add `scripts/smoke_wasm_policy_examples.sh` to `scripts/test_starter.py` and
+  the opt-in Wasm release gate.
+
 ## Security
 
 - Open private snapshot files with platform no-follow semantics before

scripts/smoke_wasm_policy_examples.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env sh
+set -eu
+
+cargo test --locked -p fluxheim-server --features wasm \
+    native_wasm_irules_policy_example_allows_public_and_denies_admin
+cargo test --locked -p fluxheim-server --features wasm \
+    native_wasm_access_decision_fails_closed_on_trap
+
+echo "wasm policy examples smoke: ok"