Skip to content

SYSTEM Cited by 1 source

ngx_lua

ngx_lua (a.k.a. lua-nginx-module, widely distributed as part of OpenResty) is an nginx module that embeds a Lua runtime into the request lifecycle. Lua scripts can hook into any nginx request phase (access_by_lua, content_by_lua, log_by_lua, etc.), call external services (HTTP, MySQL, Redis, DNS), use shared-memory zones for in-process caching, and return directives to nginx without giving up nginx's event-driven proxy + HTTP stack.

Why it matters in system design

ngx_lua is the canonical substrate for "put a small amount of routing / decision logic inside the edge proxy without rewriting nginx in Lua or swapping it out for a heavier framework." You get:

  • nginx's proxy + connection management for free — no hand-rolled HTTP client, no rewrite of proxy_pass.
  • Scripting that looks like a regular programming language — not nginx config directives.
  • Shared-memory zones — worker-shared LRU dicts for caching external lookups under request traffic.
  • Cosocket API — non-blocking I/O to MySQL / Redis / HTTP from inside an nginx worker.

The architectural move is "keep nginx for what nginx is good at, express the custom decision as Lua, leave everything else alone."

Canonical wiki instance

GitHub Pages' 2015 rewrite uses access_by_lua_file /data/pages-lua/router.lua in access_by_lua_file to:

  1. Query a MySQL read replica for the backend fileserver pair hosting the requested site.
  2. Retry the query against a different read replica on error.
  3. Cache the lookup in an nginx shared-memory zone for 30 seconds to absorb MySQL blips + reduce load.
  4. Set variables ($gh_pages_host, $gh_pages_path) consumed by a subsequent stock proxy_pass line.

The whole production config is described as "not much more complicated than" ~8 nginx-config lines + the Lua file. Measured cost: < 3 ms in Lua at p98 including external network calls, at millions of HTTP requests per hour. (Source: sources/2025-09-02-github-rearchitecting-github-pages)

GitHub's assessment: "ngx_lua's integration with nginx really shines — our production nginx config is not much more complicated than [8 lines]… The ability to embed our own code into nginx's request lifecycle has also meant that we're able to reuse nginx's rock-solid proxy functionality rather than reinventing that particular wheel on our own."

Stub page

Stub anchoring ngx_lua's role as the embedded-scripting substrate behind DB-routed static hosting. Wider ngx_lua / OpenResty coverage (phase semantics, cosocket details, OpenResty bundle distribution, ngx_stream_lua, etc.) out of scope until a second source lands.

Seen in

Last updated · 319 distilled / 1,201 read