Chapter 2
WAGI Architecture and Control Flow
What actually happens when a request hits a WAGI-powered gateway? This chapter peels back the layers of the WAGI stack, charting every architectural element and decision point that transforms raw HTTP traffic into sandboxed WebAssembly execution. Through an exploration of request processing lifecycles, context propagation, and module isolation, you'll gain an insider's perspective on how WAGI delivers powerful modularity and security with precision control over every stage of execution.
2.1 The WAGI Request Lifecycle
The WAGI (WebAssembly Gateway Interface) request lifecycle orchestrates the handling of HTTP requests by mapping them onto the execution of WebAssembly (WASM) modules. This lifecycle is a sequence of well-defined stages starting at the network interface and culminating in the delivery of a coherent HTTP response. Understanding this lifecycle in granular detail elucidates how WAGI balances efficiency, observability, and reliability when bridging high-performance native networking with secure, sandboxed WASM execution.
Upon arrival at the network interface, incoming HTTP requests first undergo transport layer processing, where sockets are accepted and HTTP framing is parsed. At this stage, WAGI leverages asynchronous I/O to support concurrent connections while minimizing blocking operations. The HTTP parser extracts request metadata including the method, URI, headers, and, if applicable, body content. Early validation occurs here to reject malformed requests without allocating unnecessary downstream resources.
Next, the router component matches the request URI against a predefined manifest of WASM modules configured to handle specific path patterns. This routing decision is critical, as it dictates which module will be invoked and how the environment is set up. Route matching is implemented using efficient trie or prefix-tree structures to achieve sublinear lookup times even under heavy manifest sizes. Failure to resolve a route results in a standardized error response to the client.
Following successful routing, environment preparation forms a crucial phase. WAGI initializes the module execution context by creating a fresh WASM runtime instance and populating its environment variables. Environmental variable bindings encapsulate HTTP metadata (such as REQUEST_METHOD, QUERY_STRING, and headers prefixed with HTTP_) and provide modules with consistent input semantics analogous to traditional CGI standards. Additionally, the runtime is configured with limits on memory and CPU usage to ensure isolation and prevent denial-of-service vectors.
Input marshaling from the HTTP request into the WASM memory space is handled next. For GET and HEAD requests, this typically involves encoding URL parameters and headers into environment variables. For POST and PUT methods, WAGI streams the request body, chunking it into manageable buffers to avoid excessive memory consumption. This streaming interface is vital for supporting large payloads and maintaining low latency. The marshaling logic ensures encoding correctness, converting network byte streams into UTF-8 conformant formats accessible by WASM modules.
The WASM module instantiation is tightly coupled with the execution phase. Upon completing environment setup and input marshaling, WAGI invokes the module's entry point, conforming to the WebAssembly System Interface (WASI) or the WAGI-specific ABI contract. The module can synchronously or asynchronously process inputs, access filesystem-like abstractions if permitted, and generate output streams. Execution monitoring hooks allow WAGI to track module resource consumption and execution duration, which are essential signals for observability and safeguarding runtime health.
During execution, the module writes response metadata and payload through prescribed WASI-compliant interfaces. The WAGI runtime collects standard output from the module, parsing the first contiguous block of output as HTTP headers (terminated by a double CRLF sequence), and the remainder as the response body. This adjudication permits modules to control status lines, headers, and content with precision. Streaming of the response body back to the client is done incrementally, enabling reduced latency and efficient use of network buffers.
Completion of the WASM execution triggers the finalization phase, where WAGI consolidates the response. It handles setting TCP socket flags for persistent or closed connections based on HTTP version and headers like Connection. Logging subsystems capture comprehensive telemetry, including time-to-first-byte and total execution time, in addition to error codes or panics within the WASM module. Such observability data supports rapid diagnosis of performance bottlenecks and failure modes.
Error handling is interwoven throughout the lifecycle. At any stage, from initial parsing to module execution, failures are normalized into HTTP error responses, with 4xx status codes for client-originated problems and 5xx for internal faults. WAGI isolates these errors to prevent cascading failures, ensuring stable and responsive service behavior. Retries or circuit breaking mechanisms can be implemented based on runtime policies informed by instrumentation data.
In essence, the WAGI request lifecycle embodies a delicate choreography of network handling, request transformation, sandboxed execution, and response synthesis. Each phase is optimized for minimal resource overhead, strict security boundaries, and seamless observability, enabling WebAssembly modules to operate as efficient, reliable web service endpoints within a lightweight gateway architecture.
2.2 Environment Variables and Context Propagation
Runtime context propagation within WebAssembly Gateway Interface (WAGI) exemplifies a sophisticated mechanism for securely and efficiently injecting environment variables into executing WASM modules. This mechanism leverages the intrinsic capabilities of WebAssembly combined with host environment controls to map HTTP request metadata, configuration details, and secret material into the module's execution context without compromising isolation or security.
Environment variables in WAGI serve as the primary conduit for contextual data derived from HTTP requests. The gateway intercepts HTTP metadata such as headers, query parameters, and method information and transposes these into environment variables accessible by the WASM module. This translation adheres to the CGI-like convention, where HTTP headers are uppercased, prefixed by HTTP_, and hyphens are replaced by underscores. For example, a header X-Custom-Token becomes HTTP_X_CUSTOM_TOKEN within the environment variable space.
This mapping is performed securely and atomically during the instantiation phase of the WASM module execution to prevent tampering or race conditions. The environment variable set is constructed in the host runtime prior to passing to the module's linear memory or importing environment. This preloading ensures that modules perceive the environment as a read-only snapshot corresponding precisely to the encapsulating HTTP request.
Configuration parameters and secrets, representing another critical class of contextual inputs, are injected via environment variables but handled with additional safeguards. Sensitive information such as API keys, database credentials, or tokens are stored in encrypted or ephemeral caches accessible only to the WAGI runtime. When a module is instantiated, only the subset of secrets relevant to its execution scope is decrypted transiently and injected as environment variables. This selective exposure minimizes the attack surface, ensuring secrets never persist longer than necessary in memory and are isolated per execution context.
Patterns for context isolation are fundamental in concurrent, multi-tenant WAGI deployments. Each execution context is provisioned with an independent environment variable set ensuring no interleaving or leakage occurs. The runtime employs a virtualized environment namespace per WASM instance, effectively sandboxing environment variables alongside memory and I/O. This isolation supports concurrent executions of the same WASM module with distinct environment states, enabling safe processing of parallel HTTP requests with varied context.
Advanced context propagation techniques extend beyond static environment variables by supporting dynamic context chaining and augmentation. For example, intermediate middleware layers can inject or modify environment variables before the WASM module executes, effectively enabling a contextual pipeline. This model allows customization such as appending user session data, introducing request-specific flags, or embedding debug tokens without altering the module binary itself.
Troubleshooting environment propagation in WAGI centers on the visibility and integrity of the injected variables. Diagnostic methods include runtime logs capturing the environment snapshot before handoff to the module and introspective APIs exposing environment content securely for administrative inspection. Misconfiguration in header-to-variable mappings or secret provisioning can be pinpointed by correlating HTTP request attributes with the environment...
