Documentation · Directives · API · Execution model · Security · Examples · Compatibility
NGINX dynamic HTTP module that hosts RustScript (pd-vm) at the access,
content, and log phases. Scripts compile once at configuration time.
The crate README is the build and install quick start; this tree is the
directive, API, and runtime reference.
The layout follows the lua-nginx-module information architecture: directives are one index, APIs are another, with syntax/context/phase metadata on each directive. The prose is ngx-rustscript's own.
| Page | Contents |
|---|---|
| README | Requirements, NGINX 1.31.4 ABI, build, release packages, tests |
| Directives | access_by_rss_file, content_by_rss_file, log_by_rss_file, shared dict, I/O/HTTP/SQLite policy |
| API reference | 199 ngx hosts, split by family, plus pd-vm async I/O/HTTP/SQLite |
| Execution model | Worker runtime, VM pool vs request-owned VM, Waiting/eventfd, log phase |
| Security and policy | Denied-by-default grants, one HTTP allow pair, SQLite root, fail-closed log |
| Examples | Rate limiter, HMAC API-key auth, async pipeline |
| Compatibility | OpenResty v0.10.29 mapping, typed results, out of scope |
| Host descriptors | Module descriptors, typed resources, named envelopes, retained Unknown slots |
| Scheduler design | Callback execution contract: blocked thread/on_abort/run_worker_thread families, plus the landed semaphore and timer families and their lifecycle |
| Directive | NGINX phase | Yield |
|---|---|---|
access_by_rss_file |
access | sync or Waiting → NGX_AGAIN |
content_by_rss_file |
content | sync or Waiting → NGX_AGAIN |
log_by_rss_file |
log | sync only; Waiting is fail-closed |
Catalog phase names other than access, content, and log record
OpenResty allowlists for later directives. They are not runnable entry
points yet. See phase sets.
- Official NGINX 1.31.4 (
nginx_version1031004); an existing OpenResty 1.31.4.1 build is supported only as an explicitly selected local test fixture. - Production ngx host count is 199: the 191 callable-family baseline
plus
ngx::semaphore::{new,wait,post,count}(worker-owned state, no script callables) andngx::timer::{at,every,pending_count,running_count}(worker-owned fake requests with one owned callback each). Typed fixed result structs (SharedStoreResult,DecodedArgsResult, …) are the script-facing envelopes; dynamic-key collections staymapfields inside those envelopes. - pd-vm I/O, HTTP, and SQLite start denied. A location may grant one
rss_http_allow <host> <port>pair.rss_sqlite_rootis required even for an in-memory database. log_by_rss_filenever waits and never mutates the already-sent response.