Documentation · Directives · API · Execution model · Security · Examples · Compatibility
This is an OpenResty-oriented RustScript API. It does not run Lua and documents only the hosts in the API reference (199 ngx names, plus pd-vm I/O/HTTP/SQLite). Host-by-host tables, phase sets, and hard caps live there; this page is the compatibility mapping.
Built and tested against official NGINX 1.31.4
(nginx_version 1031004), ngx-rust cda9d8372ccd2e139ef2b03e5806e019e7796187, and the
pinned pd-vm revision in the crate README. Executable directives are
access_by_rss_file, content_by_rss_file, and log_by_rss_file.
Release A phase lists and API names follow lua-nginx-module v0.10.29:
- Tagged README: lua-nginx-module v0.10.29 Nginx API for Lua
- Exact snapshot used when the host manifest was authored: lua-nginx-module at 8374a7beb642af43715a05a33b2cc277fba29c4d
The same README is also the Directives
index (**syntax:** / **context:** / **phase:** on each directive).
A split browseable copy is
OpenResty Reference
(Directives,
Lua Ngx API).
Do not treat later OpenResty APIs, stream-lua, or undocumented Lua helpers as part of this module.
| Status | Meaning |
|---|---|
supported |
Same call shape and result kind as lua-nginx-module v0.10.29 |
adapted |
Intentional RustScript mapping (namespacing, fixed structs, () optional arguments, bytes vs string) |
The pinned compiler matches host arity exactly. OpenResty optional
trailing arguments are explicit arguments: pass () where OpenResty
allows nil.
Multi-return OpenResty values use fixed result structs at the RustScript
boundary, and every return slot is fully typed: Option<T> for logical
absence, named structs for fixed shapes, and entry arrays for open-keyed
bags. Field access uses .value / .flags / .stale / .ok / .error /
.forcible; an absent logical value is None, never null. The
VM's internal carrier is not part of the script-facing type.
Open-keyed collections are typed entry arrays instead of dynamic maps:
struct DecodedArgsResult {
args: [ArgEntry], // ArgEntry { name: string, value: Option<string> }
truncated: bool
}
struct RequestHeadersResult {
headers: [HeaderEntry], // HeaderEntry { name: string, value: string }
truncated: bool
}Repeated keys repeat the entry, so duplicate headers and repeated query
arguments survive without an unknown value. A bare query key carries
None; a present empty value carries Some("").
Heterogeneous stored values use a tagged record. Shared-dictionary values
are SharedValue { kind, bool_value, int_value, float_value, text_value, bytes_value }, where kind selects the active payload.
Lua fields and constants become zero-argument functions:
ngx.OK → ngx::core::ok(), ngx.HTTP_GET → ngx::http::get(),
ngx.config.prefix → ngx::config::prefix(),
ngx.worker.pid → ngx::worker::pid(). There are no host constants
or dynamic table fields. ngx.null is ngx::core::null_value() -> ()
because null is a reserved token.
See Constants and cross-cutting adaptations.
| lua-nginx-module | ngx-rustscript |
|---|---|
*_by_lua_block / *_by_lua_file across many phases |
access_by_rss_file, content_by_rss_file, log_by_rss_file only |
lua_shared_dict |
rss_shared_dict |
| Lua package path / code cache directives | not present; scripts compile at nginx -t / reload |
lua_need_request_body |
ngx::req::read_body() from rewrite/access/content |
Catalog phase names other than access, content, and log document
OpenResty allowlists for later directives. They are not runnable entry
points in this matrix.
The module enables the pinned pd-vm async, http-client, and
sqlite features. Access and content may import those hosts; log
rejects them. External access is denied until location grants:
rss_io_root/rss_io_writerss_http_scheme, onerss_http_allow <host> <port>pair per location,rss_http_allow_privaterss_sqlite_rooteven for an in-memory database
A second HTTP pair is rejected during configuration. Process I/O and unsafe SQL remain disabled. Details: Security, Directives, standard async hosts.
Not production hosts in this matrix (do not import them):
ngx.exec/ internal redirect (set_uri jump=true)- Light threads and abort callbacks:
ngx::thread::{spawn,wait,kill},ngx::on_abort,ngx::run_worker_thread. Configuration compile rejects those names in access, content, and log (UnsupportedImport). The execution contract and upstreampd-vmgap are in docs/design/ngx-scheduler.md. ngx::semaphore::{new,wait,post,count}are production hosts: a worker-owned counting semaphore reached through a VM-localresource<ngx.semaphore>handle, waiting on the genericHostFuturebridge without any script callable. The barengx::semaphorenamespace marker is not a callable and is rejected. Access and content only; Log fails configuration compile. Registered count 199. See semaphore and docs/design/ngx-scheduler.md.ngx.timer.{at,every,pending_count,running_count}are adapted asngx::timer::{at,every,pending_count,running_count}. The registration hosts consume their callback throughHostParamPassing::TakeOwnedand run it later on a timer-owned VM that outlives the creating request. The family is bound through the timer-host registry (owned dispatch has no name-binding API) and is therefore not part of the 195-name per-name bind list. Each registration owns one ordinaryRequestIdentitywhose fake request id is tagged out of the request-id space, and everyeveryround re-arms under a fresh generation so stale wakes cannot start a round early. Access and content only; Log fails configuration compile. Registered count 199 (191 + 4 semaphore + 4 timer). See timer and docs/design/ngx-scheduler.md.- Stream subsystem,
ndk.set_var.*, Luacoroutine.* tcpsock:getsslpointer/tcpsock:getsslctx(no NGINX SSL FFI)print,runtime::sleep, and test hostsngx::probe/ngx::ready/ngx::fail
A timer callback round runs under NgxPhase::Timer with a log-only
AllowedOps allowlist: log, ngx::sleep/sleep_ms, cosocket I/O, the shared
dictionary, the semaphore family, and the timer family work, while request,
response, ctx, and control hosts fail closed and are reported through the
worker log. The standard I/O, HTTP, and SQLite policies are per-VM; a callback
VM does not inherit the registering location's policy.
log_by_rss_file is the executable Log-phase directive: synchronous
and fail-closed. Config uses a closed positive allowlist (family +
capability + name). Codec is included because OpenResty documents those
APIs for log_by_lua*. Response getters are included from the same
OpenResty context tables; setters stay rejected. The handler runs when
NGINX invokes the log phase for the current request (r->loc_conf
after rewrite / error_page). Subrequests require core
log_subrequest on on the subrequest location
(ngx_http_finalize_request in NGINX 1.31.4). Waiting logs
log handler cannot wait, drops the VM, and never arms eventfd, a
timer, or r->main->count.
Update the relevant API family page whenever a
production manifest API, catalog signature, allowed phase, limit, yield
behavior (sync vs Waiting), or semantic adaptation changes. Keep the
inventory on the API index in lockstep. Cross-check
ngx_host_manifest(), ngx_host_catalog(), and
production_runtime_host_names() so no production host is omitted and
no extra name is documented.