Documentation · Directives · API · Execution model · Security · Examples · Compatibility
All request-read hosts copy ngx_str / list / buffer bytes into
owned VM values on the worker main thread and never retain request, pool,
or list pointers. They require a live request scope. ngx::req::read_body
is async (Waiting); the rest of this family is sync.
struct RequestHeadersResult {
headers: map,
truncated: bool
}
struct RequestArgsResult {
args: map,
truncated: bool
}| OpenResty API | RustScript callable | Status | Phases | Limits | Semantic differences | Acceptance |
|---|---|---|---|---|---|---|
ngx.req.get_method |
ngx::req::get_method() -> string |
supported | PHASE_REQ_GET_METHOD |
256-byte method token | Custom methods keep the textual token. | tests/ngx_request_read.rs |
ngx.req.http_version |
ngx::req::http_version() -> Option<float> |
adapted | PHASE_REQ_HTTP_VERSION |
none | 0.9/1.0/1.1/2.0/3.0, or None if unrecognized. |
tests/ngx_request_read.rs |
ngx.req.raw_header |
ngx::req::raw_header(no_request_line: unknown) -> string |
adapted | PHASE_REQ_HTTP_VERSION |
65536-byte reconstruction | Reconstructs from the main request connection header buffer and busy chain (OpenResty v0.10.29). Validates every pointer/range and rejects HTTP/2 (r->main->stream) and HTTP/3 (http_version 3.0 or non-null v3_parse) using main-request protocol truth. Parser NULs restore to : and CR/LF. Preread body after CRLFCRLF is stripped. no_request_line is ()/false/true. Malformed ranges, null buffers, cycles, and over-cap copies are host errors. |
tests/ngx_request_read.rs (raw_header_*) |
ngx.req.get_headers |
ngx::req::get_headers(max_headers: unknown, raw: unknown) -> RequestHeadersResult |
adapted | PHASE_REQ_GET_HEADERS |
default 100; hard 1024; 8192-byte field; 65536-byte total | Fixed fields headers: array<HeaderEntry> and truncated: bool, where HeaderEntry { name: string, value: string }. raw true keeps original names; otherwise lowercase. Duplicate names repeat the entry. Empty values kept. hash==0 skipped. Count/byte caps set truncated=true before further copy. Null elts with nelts>0, cycles, and impossible metadata are host errors, not silent truncation. |
tests/ngx_request_read.rs |
ngx.req.get_uri_args |
ngx::req::get_uri_args(max_args: unknown) -> RequestArgsResult |
adapted | PHASE_REQ_GET_URI_ARGS |
default 100; hard 1024; 65536-byte query | Fixed fields args: array<ArgEntry> and truncated: bool; ArgEntry { name: string, value: Option<string> }. Uses the crate-private decode_query_args helper shared with ngx::decode_args. Trailing empty & at max_args is not truncated. 0 clamps to 1024. |
tests/ngx_request_read.rs, tests/ngx_codec.rs |
ngx.req.get_post_args |
ngx::req::get_post_args(max_args: unknown) -> RequestArgsResult |
adapted | PHASE_REQ_GET_POST_ARGS |
same arg caps; 65536-byte body | Sync parse after read_body completion from memory or a bounded temp file. Fixed fields args: array<ArgEntry> and truncated: bool, where ArgEntry { name: string, value: Option<string> }. Duplicate keys repeat the entry. Unread, still-reading, discarded, incomplete, or corrupt bodies are structured host errors. Does not delete NGINX temp files. Never initiates body read or yield. |
tests/ngx_request_body.rs |
ngx.req.read_body |
ngx::req::read_body() -> () |
adapted | PHASE_REQ_READ_BODY |
async; rewrite/access/content | Calls ngx_http_read_client_request_body through a C shim. Undoes that API's r->main->count++ for NGX_OK/NGX_AGAIN so the phase driver (content NGX_DONE / access NGX_AGAIN) owns count. Premature client close (c->error / confirmed EOF) is 499; timeout stays 408; protocol/413 statuses are preserved. A C read-event wrapper peeks EOF then finalizes 499 once, otherwise invokes NGINX's original body handler. Generation-safe nginx_op cell: callback completes once; cleanup cancels once; stale callbacks no-op. Futures hold no request/VM/module pointers. Idempotent after completion. Forbidden in Log. |
tests/ngx_request_body.rs, tests/lifecycle.rs |
ngx.req.discard_body |
ngx::req::discard_body() -> () |
adapted | PHASE_REQ_READ_BODY |
sync; rewrite/access/content | Calls ngx_http_discard_request_body. Never waits. Idempotent (NGX_OK/NGX_AGAIN). Discard-after-read is a no-op; read-after-discard completes immediately. Forbidden in Log. |
tests/ngx_request_body.rs |
ngx.req.get_body_data |
ngx::req::get_body_data() -> Option<string> |
adapted | PHASE_REQ_GET_BODY_DATA |
65536-byte copy | Nullary like OpenResty. Owned copy of in-memory buffers. File-backed returns None. Empty memory buffers are skipped; inverted ranges and cycles are host errors. Allowed in Log (completed-body getter). |
tests/ngx_request_body.rs |
ngx.req.get_body_file |
ngx::req::get_body_file() -> Option<string> |
adapted | PHASE_REQ_GET_BODY_FILE |
4096-byte path | Owned copy of NGINX temp-file path. Memory-backed returns None. Does not delete the file. Forbidden in Log. |
tests/ngx_request_body.rs |
ngx.req.set_body_data |
ngx::req::set_body_data(data: string) -> () |
adapted | PHASE_REQ_SET_BODY |
65536-byte memory body | Transactionally allocates a complete ngx_http_request_body_t / chain / buf plus bytes from the request pool, then swaps r->request_body only after Content-Length (real header hash, linked duplicates updated, dedicated pointer coherent) and chunked/Transfer-Encoding hide-hash sync succeed. Empty body installs a zero-length memory buf. Prior body remains on allocation failure. Rejected in Log, without RequestWrite/live request, while reading_body/discard_body/header_sent, while a read-body wait is armed, and on subrequests (r != r->main). |
tests/ngx_request_body_mutation.rs |
ngx.req.set_body_file |
ngx::req::set_body_file(path: string, auto_clean: unknown) -> () |
adapted | PHASE_REQ_SET_BODY |
4096-byte path; 65536-byte file | lstat then O_NOFOLLOW|O_CLOEXEC|O_NONBLOCK open; post-open fstat must stay a regular file with the same st_dev/st_ino as lstat. Regular files only (symlink/dir/FIFO rejected before open). auto_clean ()/false leaves the source path; true copies into a private temp. A C ngx_pool_cleanup_add handler (ngx_pool_delete_file vs ngx_pool_cleanup_file) owns the fd: unlink the copy exactly once when auto_clean, close once, never unlink the caller source. Errors before cleanup registration leave fd with the caller; after registration a failed header commit nulls the handler. File buf matches OpenResty: rb->buf=NULL, in_file/last_buf/last_in_chain, no temp_file bit. Content-Length uses the real header hash so proxy hide-hash emits exactly one CL; Transfer-Encoding chain entries keep the hide-hash and are emptied. |
tests/ngx_request_body_mutation.rs |
ngx.req.init_body |
ngx::req::init_body(buffer_size: unknown) -> () |
adapted | PHASE_REQ_SET_BODY |
default/hard cap 65536 | Request-owned builder in RequestPhaseCtx (test fallback only without module ctx). () uses the default cap; integer must be 0..=65536. Repeated init resets the builder. Does not mutate NGINX body until finish_body. |
tests/ngx_request_body_mutation.rs |
ngx.req.append_body |
ngx::req::append_body(data: string) -> () |
adapted | PHASE_REQ_SET_BODY |
cumulative builder cap | Copies bytes into the builder. Fails without init_body or when the cap would be exceeded; the builder is unchanged on oversize. |
tests/ngx_request_body_mutation.rs |
ngx.req.finish_body |
ngx::req::finish_body() -> () |
adapted | PHASE_REQ_SET_BODY |
same as set_body_data |
Atomically installs one coherent in-memory body. Repeated finish / finish without init fail. Allocation failure restores the builder. Dropped on request cleanup/error/disconnect/shutdown. | tests/ngx_request_body_mutation.rs |
ngx.req.is_internal |
ngx::req::is_internal() -> bool |
adapted | PHASE_REQ_FLAGS |
none | Live C r->internal via a headers-compiled shim (ngx_rustscript_request_is_internal). nginx-sys bindgen bitfield getters are the wrong ABI; neighboring C flags such as filter_finalize must not read as internal (REQ_INTERNAL_REDIR=true). |
tests/ngx_request_read.rs, tests/ngx_request_abi.rs |
ngx.req.start_time |
ngx::req::start_time() -> float |
supported | PHASE_REQ_FLAGS |
none | start_sec + start_msec/1000. |
tests/ngx_request_read.rs |
ngx.is_subrequest |
ngx::is_subrequest() -> bool |
supported | PHASE_REQ_FLAGS |
none | r != r->main. Live false-path on main requests (REQ_SUB=false). ngx_http_core_access_phase skips all access handlers when r != r->main, so SSI/mirror/auth_request subrequests cannot run access_by_rss_file. True is stub-covered; SSI include still returns sub-ok as evidence the subrequest ran. |
tests/ngx_request_read.rs |
ngx.headers_sent |
ngx::headers_sent() -> bool |
supported | PHASE_HEADERS_SENT |
none | Live C r->header_sent via ngx_rustscript_request_headers_sent. Access-phase scripts observe false. |
tests/ngx_request_read.rs, tests/ngx_request_abi.rs |
ngx.var.VARIABLE |
ngx::var::get(name: string) -> Option<string> |
adapted | PHASE_VAR_GET |
1024-byte name; 65536-byte value | Indexed lookup with ngx_hash_strlow. Missing is None; present empty is Some(""). Rejects empty/NUL names. |
tests/ngx_request_read.rs (var_get_*) |
ngx.req.set_method |
ngx::req::set_method(method_id: int) -> () |
adapted | PHASE_REQ_SET_METHOD |
OpenResty method IDs only | Pool-owned canonical method_name is allocated successfully before numeric/text fields change. Allocation failure leaves method untouched. Unsupported IDs fail before mutation. |
tests/ngx_request_mutation.rs, tests/ngx_task7_hardening.rs |
ngx.req.set_uri |
ngx::req::set_uri(uri: string, jump: unknown) -> () |
adapted | PHASE_REQ_SET_URI |
65536-byte URI | jump ()/false rewrites r->uri, sets internal, clears valid_unparsed_uri/valid_location/uri_changed, and calls ngx_http_set_exten via the C shim. jump=true is rejected before mutation. Empty/unsafe bytes (0x00-0x08, 0x0A-0x1F, 0x7F) fail first. |
tests/ngx_request_mutation.rs |
ngx.req.set_uri_args |
ngx::req::set_uri_args(args: unknown) -> () |
adapted | PHASE_REQ_SET_URI |
65536-byte encoded args | String: escape 0x00-0x20 and 0x7F as %XX. Map: reuse encode_args. Pool-owned r->args; valid_unparsed_uri=0. |
tests/ngx_request_mutation.rs |
ngx.req.set_header |
ngx::req::set_header(name: string, value: unknown) -> () |
adapted | PHASE_REQ_SET_HEADER |
256-byte token name; 8192-byte value | () clears. String/array values. Token + no CRLF/NUL. Validates the list, then Host (ngx_http_lua_validate_host port-aware, updates headers_in.server, invalidates cached $host), Content-Length (ngx_atoof before mutation; every value must be a decimal; dedicated n uses the first), User-Agent browser flags, and Connection (close substring first, then keep-alive). Hash-zero then push. Dedicated Host/Content-Length/Content-Type/User-Agent/Connection/Cookie/Referer stay consistent. Allocation/list-push failure rolls back added entries. |
tests/ngx_request_mutation.rs, tests/ngx_task7_hardening.rs |
ngx.req.clear_header |
ngx::req::clear_header(name: string) -> () |
adapted | PHASE_REQ_SET_HEADER |
same name policy | Hash-zero matching list entries and reset dedicated fields (content_length_n=-1, connection_type=0). |
tests/ngx_request_mutation.rs |
ngx.var.VARIABLE write |
ngx::var::set(name: string, value: unknown) -> () |
adapted | PHASE_VAR_GET |
1024-byte name; 65536-byte value | Indexed/set_handler write via C shim. Honors CHANGEABLE. () → not_found. Empty string is present empty. Read-only and unknown names fail. |
tests/ngx_request_mutation.rs |
See also: API index · Phase sets · Cross-cutting adaptations · Hard caps