Skip to content

Latest commit

 

History

History
56 lines (46 loc) · 3.14 KB

index.md

File metadata and controls

56 lines (46 loc) · 3.14 KB

ngx-rustscript documentation

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.

Start here

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

Runnable phases

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.

Facts that apply everywhere

  • Official NGINX 1.31.4 (nginx_version 1031004); 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) and ngx::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 stay map fields 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_root is required even for an in-memory database.
  • log_by_rss_file never waits and never mutates the already-sent response.