Documentation · Directives · API · Execution model · Security · Examples · Compatibility
This matrix is the authoritative current ngx host surface for
ngx-rustscript. It is derived from the production manifest
(src/host/catalog.rs ngx_host_manifest()), the compiler catalog
(ngx_host_catalog()), and the runtime bind list
(src/host/mod.rs production_runtime_host_names() / bind_ngx_hosts).
The manifest and the compiler catalog contain the same 199 names in the
same order; the per-name runtime bind list has 195 ordered non-timer
entries.
The owned ngx::timer::{at,every} registrations have no name-binding API, so
the four timer names resolve through the timer-host registry
(ngx_host_registry) instead of the per-name bind list; the manifest/catalog
add them on top of the 191 callable baseline and the four semaphore entries
(191 + 4 semaphore = 195 per-name, + 4 timer = 199 total). See
timer.
ngx-rustscript provides an OpenResty-oriented RustScript API. It does does not run Lua and documents only the hosts in this matrix (including UDP and TCP cosocket).
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.
The host-by-host tables are split by family below. Phase allowlists, cross-cutting adaptations, and hard caps stay on this page so each family page can cite them without repeating the shared rules.
- Sleep
- Codec and hash
- Time
- Metadata, worker, config, and phase
- Logging
- Constants
- Request and variables
- Request-local context
- Response metadata
- Response output
- Control flow
- Shared dictionary
- UDP cosocket
- TCP cosocket
- Semaphore
- pd-vm standard async hosts
pd-vm I/O, HTTP, and SQLite hosts are not part of the 199 ngx names; see pd-vm standard async hosts.
| Field | Meaning |
|---|---|
| OpenResty API | lua-nginx-module v0.10.29 name |
| RustScript callable | Production host import name and catalog signature |
| Status | supported (same call shape and result kind) or adapted (intentional RustScript mapping) |
| Phases | Catalog allowlist. Names are the NgxPhase display strings below. Runnable directives are access_by_rss_file (access), content_by_rss_file (content), and log_by_rss_file (log). Config-time import checks use the directive's phase. |
| Yield | sync (returns immediately) or Waiting (VmStatus::Waiting, NGX_AGAIN) |
| Limits | Hard caps enforced by the host |
| Semantic differences | Intentional adaptations versus OpenResty Lua |
| Acceptance | Tests that exercise the host or family |
Catalog type labels: number (int or float), int, string, bytes,
bool, (), array<T>, Option<T> (Some(T) or None),
Result<T, E>, named records, and resource (typed VM handle). A host
output never carries unknown, null, or the legacy optional<T> schema.
The pinned compiler matches host arity exactly. OpenResty optional
trailing arguments are explicit arguments: pass () where the default is
wanted. Absence in a result is None, never null.
| Family | Hosts | Yield |
|---|---|---|
| Timer (sleep) | 2 | Waiting |
| Codec / hash | 14 | sync |
| Time | 9 | sync |
| Metadata / worker / config / phase | 12 | sync |
| Logging | 1 | sync |
| Request-read / var | 26 | mixed |
| Request-local ctx | 4 | sync |
| Response metadata | 6 | sync |
| Response output | 5 | print/say/send_headers/eof sync; flush async |
| Control | 2 | sync |
| Shared dict | 22 | sync |
| Cosocket (UDP) | 7 | mixed |
| Cosocket (TCP) | 16 | mixed |
| Semaphore | 4 | wait Waiting; new/post/count sync |
| Timer | 4 | at/every register and return; callbacks run on a timer-owned VM |
| Constants | 65 | sync |
| of which HTTP status | 35 | sync |
| Production total | 199 |
Test-only hosts ngx::probe, ngx::ready, and ngx::fail are not in
the production manifest, catalog, or bind_ngx_hosts.
Every production host except the five content-phase output hosts
(ngx::send_headers, ngx::print, ngx::say, ngx::flush, ngx::eof)
is allowed in access. Output hosts are content-only and rejected at
config time in access/init/set/rewrite. Unknown imports, phase-
forbidden imports, arity errors, and type errors are distinct
configuration failures. Bare print is not a host; use ngx::print
or ngx::log. runtime::sleep is rejected.
Catalog phase names (exact): init, init_worker, set, rewrite,
access, content, header_filter, body_filter, log, timer,
balancer, ssl_certificate, ssl_session_fetch, ssl_session_store,
ssl_client_hello, exit_worker.
ngx::get_phase() returns those strings except ssl_certificate, which
is reported as OpenResty ssl_cert.
Shared sets used by the tables:
| Set | Phases |
|---|---|
SLEEP_PHASES |
rewrite, access, content, timer, ssl_certificate, ssl_session_fetch |
PHASE_SEMAPHORE |
access, content (fail-closed everywhere else, including log) |
PHASE_ALL |
init, init_worker, set, rewrite, access, content, header_filter, body_filter, log, timer, balancer, ssl_certificate, ssl_session_fetch, ssl_session_store, exit_worker, ssl_client_hello |
PHASE_ESCAPE_URI |
same as PHASE_ALL |
PHASE_UNESCAPE_URI |
PHASE_ALL minus ssl_session_fetch and ssl_session_store |
PHASE_ENCODE_ARGS |
set, rewrite, access, content, header_filter, body_filter, log, timer, balancer, ssl_certificate, ssl_client_hello |
PHASE_DECODE_ARGS |
set, rewrite, access, content, header_filter, body_filter, log, timer, balancer, ssl_certificate, ssl_session_fetch, ssl_session_store, ssl_client_hello |
PHASE_CODEC_MISC |
set, rewrite, access, content, header_filter, body_filter, log, timer, balancer, ssl_certificate, ssl_session_fetch, ssl_session_store |
PHASE_CODEC_MISC_SSL_CLIENT_HELLO |
PHASE_CODEC_MISC plus ssl_client_hello |
PHASE_TIME |
init_worker, set, rewrite, access, content, header_filter, body_filter, log, timer, balancer, ssl_certificate, ssl_session_fetch, ssl_session_store, exit_worker, ssl_client_hello |
PHASE_CORE_CONST |
init, set, rewrite, access, content, header_filter, body_filter, log, timer, balancer, ssl_certificate, ssl_session_fetch, ssl_session_store, ssl_client_hello |
PHASE_CONFIG_RUNTIME |
init, init_worker, set, rewrite, access, content, header_filter, body_filter, log, timer, exit_worker |
PHASE_CONFIG_BUILD |
init, set, rewrite, access, content, header_filter, body_filter, log, timer |
PHASE_WORKER_PIDS |
set, rewrite, access, content, header_filter, body_filter, log, timer, exit_worker |
PHASE_WORKER_ID |
init_worker, set, rewrite, access, content, header_filter, body_filter, log, timer, exit_worker |
PHASE_REQ_GET_METHOD |
set, rewrite, access, content, header_filter, body_filter, balancer, log |
PHASE_REQ_HTTP_VERSION |
set, rewrite, access, content, header_filter |
PHASE_REQ_GET_URI_ARGS |
set, rewrite, access, content, header_filter, body_filter, log, balancer |
PHASE_REQ_GET_POST_ARGS |
rewrite, access, content, header_filter, body_filter, log |
PHASE_REQ_GET_HEADERS |
set, rewrite, access, content, header_filter, body_filter, log |
PHASE_REQ_FLAGS |
set, rewrite, access, content, header_filter, body_filter, log |
PHASE_HEADERS_SENT |
set, rewrite, access, content |
PHASE_VAR_GET |
set, rewrite, access, content, header_filter, body_filter, log, balancer |
PHASE_REQ_SET_METHOD |
set, rewrite, access, content, header_filter |
PHASE_REQ_SET_URI |
set, rewrite, access, content, header_filter, body_filter |
PHASE_REQ_SET_HEADER |
set, rewrite, access, content, header_filter, body_filter, log, balancer |
PHASE_REQ_READ_BODY |
rewrite, access, content |
PHASE_REQ_GET_BODY_DATA |
rewrite, access, content, log |
PHASE_REQ_GET_BODY_FILE |
rewrite, access, content |
PHASE_REQ_SET_BODY |
rewrite, access, content |
PHASE_RESPONSE_META |
set, rewrite, access, content, header_filter, body_filter, log, balancer |
PHASE_OUTPUT |
content |
PHASE_EXIT |
rewrite, access, content, header_filter, timer, balancer, ssl_certificate, ssl_session_fetch, ssl_session_store |
PHASE_REDIRECT |
rewrite, access, content |
PHASE_CTX |
set, rewrite, access, content, header_filter, body_filter, log, timer, balancer, ssl_certificate, ssl_session_fetch, ssl_session_store, ssl_client_hello |
PHASE_DICT_LOOKUP |
same as PHASE_ALL |
PHASE_DICT_GET |
same as PHASE_CTX |
PHASE_DICT_WRITE |
init, set, rewrite, access, content, header_filter, body_filter, log, timer, balancer, ssl_certificate, ssl_session_fetch, ssl_session_store, ssl_client_hello |
PHASE_SOCKET_UDP |
same as SLEEP_PHASES |
These apply across families. Per-host rows do not repeat them unless a host adds a further difference.
- Namespaced zero-arg functions for Lua fields and constants. Lua
ngx.OK,ngx.HTTP_GET,ngx.config.prefix,ngx.worker.pidbecome callables such asngx::core::ok(),ngx::http::get(),ngx::config::prefix(),ngx::worker::pid(). There are no host constants or dynamic table fields. ngx.nullisngx::core::null_value() -> ().ngx::core::nullis not catalogued:nullis a reserved token, and the host returns the logical Unit so the RustScript compiler admits it.ngx.sleepis seconds.ngx::sleep(seconds: number) -> ()accepts int or float seconds and rejects negative values, NaN, infinity, and duration overflow. Legacyngx::sleep_ms(ms: int) -> ()keeps integer milliseconds for existing scripts. Both are async.ngx.decode_argsresult shape. ReturnsDecodedArgsResult { args: array<ArgEntry>, truncated: bool }rather than Lua's multi-return(table, truncated?), whereArgEntry { name: string, value: Option<string> }.max_argsof()defaults to 100;0is clamped to the hard max 1024 (not unbounded); values above 1024 are rejected. A key without=carriesNone; a present empty value isSome(""). Repeated keys repeat the entry. Empty keys are skipped. Invalid%sequences are left as-is.- Byte versus string results. Hex
ngx::md5returnsstring.ngx::md5_bin,ngx::sha1_bin, andngx::hmac_sha1returnbytes.ngx::decode_base64/ngx::decode_base64mimereturnOption<bytes>(Noneon invalid input).ngx::unescape_urireturns a string even when decoded bytes are not UTF-8 (each byte becomeschar::from). - Time cache / update boundary. Time hosts use a process-local
cached clock, not nginx
ngx_time/ngx_timeofday. Reads reuse the snapshot while the event generation is unchanged and the snapshot is younger than 1s. Access-phase request execution and later eventfd resume/poll turns callnotify_cached_clock_event_boundaryso the cache may refresh like nginxngx_time_updateon the event loop.ngx::update_time()always samples the OS (or a test override) and replaces the snapshot. - No global
print.printis not a production host. Log withngx::log. Config rejectsprintandruntime::sleep. ngx.logrequest versus cycle.ngx::log(level, message)writes the live request log when the worker-thread request scope is active and allowsLOG; otherwise it uses the cycle log. Missing both sinks is a host error. Levels outsideNGX_LOG_STDERR..=NGX_LOG_DEBUGand messages containing NUL are host errors. The line is prefixedngx-rustscript:. OpenResty varargs are a single string.- Phase and config import enforcement.
compile_rss_sourcecompiles access scripts againstcompile_host_catalog()— the 199-namengx_host_catalog()merged with pd-vm's standard host catalog (I/O, HTTP, SQLite) — and thenvalidate_program_imports_for_phase(..., Access);compile_rss_source_for_phaseperforms the corresponding Content or Log validation forcontent_by_rss_fileandlog_by_rss_file. The standard families are catalogued so their resource handles type-check against the exact schemas the runtime composition registers, and the same snapshot installs the adapters in the production registry. Unknown names, phase-forbidden names, arity, and type mismatches fail distinctly atnginx -t/ reload. Catalog phase metadata is the allowlist for all three executable directives and for documented future phases. ngx.worker.pidssemantics. The array always includes livengx_pidwhenpid > 0. Otherngx_processesslots are included only whenpid > 0andchannel[0] > 0(excludes master, helpers, and stale entries). Invalidngx_process_slotis ignored. Duplicate pids are collapsed. Values come from NGINX public globals, never/proc.- Optional OpenResty arguments. Trailing options such as escape
type,
max_args, andno_paddingmust be passed explicitly; use()when the default is wanted.
| Cap | Value | Applies to |
|---|---|---|
| Codec input | 65536 bytes | URI/args/base64/hash/quote inputs |
| Codec output | 196608 bytes | escape/encode/quote outputs |
decode_args default max_args |
100 | () second argument |
decode_args hard max_args |
1024 | explicit cap; 0 clamps to this |
encode_args pairs |
1024 | including array expansion |
parse_http_time input |
128 bytes | over-limit is a host error |
| Async in-flight waits | 1024 (DEFAULT_MAX_IN_FLIGHT) |
ngx::sleep / ngx::sleep_ms / UDP ops |
| UDP datagram | 65535 bytes | send payload and receive size |
| UDP DNS host | 255 bytes | setpeername host before lookup |
| Idle VM pool | 4 | import-free programs |
| Cached clock stale limit | 1 second | time hosts without update_time |
| Request copy / body / raw header | 65536 bytes | ngx::req::raw_header, get_headers total, get_uri_args / get_post_args source |
| Header field | 8192 bytes | single get_headers name or value |
| Header / args default cap | 100 | () max_headers / max_args |
| Header / args hard cap | 1024 | explicit cap; 0 clamps to this |