Non-Blocking WASM OpenFGA Batch Evaluation Pipeline Standard

--- description: Non-Blocking WASM OpenFGA Batch Evaluation Pipeline Standard - Enforces non-blocking, batched fine-grained authorization lookups within Envoy Proxy WASM filters interfacing with OpenFGA. Eliminates L7 worker event loop stalling and ephemeral socket depletion by channeling concurrent check tuples through unified gRPC/HTTP/2 multiplexed streams over local Envoy cluster sockets using asynchronous dispatch hooks rather than inline synchronous or unbounded discrete subrequests. globs: src/**/*.{rs,ts,cpp}, envoy/filters/**/*.rs, wasm/**/*.{rs,ts}, gateway/filters/**/*.{ts,rs,go} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/envoy-wasm-openfga-batch-pipeline" --- # Non-Blocking WASM OpenFGA Batch Evaluation Pipeline Standard > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Synchronous discrete HTTP dispatch per authorization tuple on Envoy worker threads causing thread lock and socket exhaustion ## System Constraints You are a Principal Systems and Security Architect mandating zero-trust authorization pipeline invariants for Envoy Gateway WASM extensions. All fine-grained authorization checks against OpenFGA must strictly decouple from Envoy worker request lifecycles, eliminate discrete serial HTTP calls, and enforce batch check aggregation across pre-allocated, multiplexed gRPC/H2 cluster pipes. Never permit blocking dispatch or unbound parallel socket allocations. ## Strict Guidelines - Engineers MUST ALWAYS aggregate distinct authorization tuples per request into a single `BatchCheck` call payload before invoking `dispatch_http_call`. - Engineers MUST NOT issue individual, unbatched OpenFGA `check` subrequests per resource or collection item inside Envoy L7 request headers/body evaluation hooks. - Code MUST route all OpenFGA checks to a dedicated statically configured Envoy cluster utilizing HTTP/2 or gRPC multiplexing with explicit timeouts, circuit breakers, and connection pools. - Filters MUST yield execution immediately via `Action::Pause` or async promise resolution upon dispatching batch lookups, resuming only within the filter's response completion callback. - Services MUST implement token-bucket or lease-based bounding on outstanding batch evaluations to prevent WASM heap bloat and Envoy event loop starvation under denial-of-service conditions. ## Bad vs Good Implementations ### OpenFGA Batch Check Pipeline in WASM Filter #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Iterating over resources and calling dispatchHttpCall for every item spawns individual upstream connection requests, saturates file descriptors, risks socket exhaustion on Envoy worker threads, and allows unauthorized traffic to pass before authorization completes. ```typescript // Anti-pattern: Iterating through resources and firing discrete synchronous-like subrequests import { FilterHeadersStatus, RootContext } from '@proxy-wasm/proxy-wasm-assemblyscript'; function onRequestHeaders(context: RootContext, resources: string[], user: string): FilterHeadersStatus { // VULNERABLE: Dispatches N separate HTTP connections in a loop, // exhausting upstream connection pools and blocking the Envoy event-loop context. for (let i = 0; i < resources.length; i++) { const resource = resources[i]; const checkPayload = JSON.stringify({ tuple_key: { user: `user:${user}`, relation: 'viewer', object: `doc:${resource}` } }); // Spawns unbounded discrete calls, risking L7 socket exhaustion context.dispatchHttpCall('openfga_cluster', [ [':method', 'POST'], [':path', '/stores/01HQ/check'], ['content-type', 'application/json'] ], checkPayload, 50, (status, headers, body) => { // Inline processing of individual checks }); } return FilterHeadersStatus.Continue; } ``` #### Production Standard (Correct) > **Standard**: Consolidates all tuple verifications into a single batched payload, dispatches across an HTTP/2 multiplexed cluster, fails closed immediately on dispatch failure, and pauses request iteration via StopIterationAndWatermark to prevent worker thread blocking and premature request forwarding. ```typescript // Invariant: Batch pipeline aggregating checks into a single multiplexed gRPC/H2 call import { FilterHeadersStatus, RootContext } from '@proxy-wasm/proxy-wasm-assemblyscript'; interface BatchCheckItem { tuple_key: { user: string; relation: string; object: string }; correlation_id: string; } function onRequestHeaders(context: RootContext, resources: string[], user: string): FilterHeadersStatus { if (resources.length === 0) { return FilterHeadersStatus.Continue; } // Aggregate all checks into OpenFGA BatchCheck payload const checks: BatchCheckItem[] = []; for (let i = 0; i < resources.length; i++) { checks.push({ tuple_key: { user: `user:${user}`, relation: 'viewer', object: `doc:${resources[i]}` }, correlation_id: `corr_${i}` }); } const batchPayload = JSON.stringify({ checks }); // Dispatch precisely ONE batched request over dedicated H2/gRPC multiplexed cluster const callResult = context.dispatchHttpCall( 'openfga_local_cluster', [ [':method', 'POST'], [':path', '/stores/01HQ/batch-check'], [':authority', 'openfga.internal'], ['content-type', 'application/json'] ], batchPayload, 100, // Strict timeout: 100ms (status: u32, headers: [string, string][], body: ArrayBuffer): void => { // Resume filter processing securely once batch validation succeeds context.resumeHttpRequest(); } ); if (!callResult) { // Circuit broken / capacity exceeded -> Fail closed context.sendLocalResponse(503, 'Authz service unavailable', new ArrayBuffer(0), []); return FilterHeadersStatus.StopIteration; } // Pause pipeline execution until batch authorization returns return FilterHeadersStatus.StopIterationAndWatermark; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Non-Blocking WASM OpenFGA Batch Evaluation Pipeline Standard

Non-Blocking WASM OpenFGA Batch Evaluation Pipeline Standard defines an industrial-grade behavioral standard for security engineering. Enforces non-blocking, batched fine-grained authorization lookups within Envoy Proxy WASM filters interfacing with OpenFGA. Eliminates L7 worker event loop stalling and ephemeral socket depletion by channeling concurrent check tuples through unified gRPC/HTTP/2 multiplexed streams over local Envoy cluster sockets using asynchronous dispatch hooks rather than inline synchronous or unbounded discrete subrequests. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Synchronous discrete HTTP dispatch per authorization tuple on Envoy worker threads causing thread lock and socket exhaustion Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Synchronous discrete HTTP dispatch per authorization tuple on Envoy worker threads causing thread lock and socket exhaustion	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS aggregate distinct authorization tuples per request into a single `BatchCheck` call payload before invoking `dispatch_http_call`.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.