API Gateway
Home › Technical Guides › Extensibility
Extensibility

Extending API Gateways with WebAssembly, Lua, and JavaScript Plugins

Custom gateway plugins solve specialized authentication, header signing, and routing logic when built-in policies fall short—without recompiling the core proxy binary.

Gateway Request Lifecycle Hooks

Gateways process HTTP traffic through deterministic hooks: connection accept, `on_request_headers`, optional `on_request_body`, upstream selection, response headers/body, and post-response logging.

Running custom authentication or HMAC checks inside `on_request_headers` lets plugins reject invalid requests in microseconds before buffering body bytes.

  • Execute rejections in header hooks prior to body buffering
  • Guard body hooks with strict max-byte size limits
  • Run logging hooks asynchronously outside the response path
  • Order plugin execution explicitly (auth before rate-limiting)

Comparing LuaJIT, Embedded JS, and Proxy-Wasm

LuaJIT coroutines offer tiny memory footprints in NGINX-derived gateways, though Lua shares worker memory and unsafe C-FFI calls can crash workers.

Proxy-Wasm compiles Rust, Go, or AssemblyScript into sandboxed `.wasm` modules with isolated linear memory—trapping panics safely without crashing the host proxy—while embedded JS isolates (V8/QuickJS) ease full-stack onboarding.

  • Proxy-Wasm provides strict memory sandboxing and multi-language portability
  • LuaJIT offers ultra-low overhead coroutines in NGINX-family proxies
  • External gRPC filters (`ext_authz`) support any runtime across a loopback hop

Avoiding Blocking I/O and Memory Leaks

Never run blocking sockets, synchronous disk I/O, or sleeps on a proxy event-loop thread; one stalled call blocks hundreds of concurrent connections sharing that worker.

Use strictly async host APIs with tight callout timeouts (50–100 ms), pre-compile regexes at startup, and cap in-plugin caches with LRU eviction.

  • Use non-blocking async host APIs for all external callouts
  • Pre-compile RE2 regex patterns and schemas once on initialization
  • Bound in-memory plugin caches with fixed LRU entry limits

Testing and Rollout Governance

Package `.wasm` and script plugins with semantic versions and SHA-256 checksums, test against golden HTTP fixtures in CI, and roll out to canary routes before global activation.

API Gateway Plugin Runtime Comparison

RuntimeIsolation ModelSupported LanguagesTypical Call OverheadOperational Trade-Off
Proxy-WasmSandboxed linear memoryRust, TinyGo, C++, AssemblyScript0.1–0.6 msStrong fault isolation; requires Wasm build toolchain
LuaJIT (In-Process)Shared worker VMLua0.05–0.3 msUltra-fast coroutines; FFI bugs can crash worker
Embedded JS (V8 / QuickJS)Isolate / context sandboxJavaScript / TypeScript0.2–1.0 msEasy team adoption; watch GC pauses under heavy load
External gRPC Filter (ext_authz)Separate OS process / sidecarAny (Python, Go, Java, Node)1.5–8 ms (IPC/loopback)Full SDK freedom; extra network hop & deployment unit
Native Compiled CoreDirect proxy binaryRust, C++, Go< 0.05 msPeak performance; requires recompiling proxy binary

Overhead figures measure runtime entry/exit and header inspection; external network callouts add network RTT.

Worked Illustration: Building a Custom HMAC Signature Plugin

This worked illustration traces a Proxy-Wasm plugin verifying partner webhook HMAC-SHA256 signatures at the gateway edge.

  1. Step 1 (Startup Init): Load signing secret key IDs into an immutable in-memory map on configuration load.
  2. Step 2 (Header Check): In `on_request_headers`, reject missing or stale `X-Webhook-Timestamp` (>300 s) with HTTP 401 before body buffering.
  3. Step 3 (Bounded Body Verify): If `Content-Length <= 256 KB`, verify `HMAC-SHA256(secret, timestamp + '.' + body)` in constant time.
  4. Step 4 (Result): Valid requests proceed in ~0.4 ms with `X-Webhook-Verified: true`; invalid signatures fail fast with HTTP 403.

Engineering Illustration Summary: Header-first sandboxed verification stops replay attacks and oversized bodies under half a millisecond.

Custom Gateway Plugin Engineering Checklist

  • Verify whether built-in declarative policies solve the requirement before writing custom plugins.
  • Execute auth and rejection logic in header hooks before reading request bodies when possible.
  • Use non-blocking async host APIs with tight timeouts for any external callouts.
  • Pre-compile regular expressions, schemas, and lookup maps once at plugin startup.
  • Enforce bounded LRU memory caps and load-test memory growth before release.
  • Checksum plugin artifacts and roll out to canary routes before global deployment.

Frequently Asked Questions

When should I choose Proxy-Wasm over an external gRPC plugin?

Choose Proxy-Wasm for sub-millisecond header validation and lightweight mutation; choose external gRPC when heavy SDKs or database drivers are required.

Can a Lua or Wasm plugin crash the entire API gateway?

Proxy-Wasm runs in an isolated sandbox so faults terminate only the plugin instance, whereas unsafe C-FFI calls in shared Lua VMs can crash the worker.

Why does plugin execution order matter?

Authentication and IP filtering must run before rate limiting or mutation so unauthorized requests are rejected before consuming quota or CPU.

How do you prevent regex denial-of-service (ReDoS) in custom plugins?

Use linear-time regex engines (such as RE2), pre-compile patterns at startup, and bound input lengths before matching.

Primary Standards & Specifications

  • Proxy-Wasm Application Binary Interface (ABI) Specification
  • WebAssembly Core Specification v2.0 (World Wide Web Consortium, W3C)
  • OWASP Application Security Verification Standard (ASVS)

Related Technical Guides