Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

6 changes: 3 additions & 3 deletions Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ ngx-rust-rev = "cda9d8372ccd2e139ef2b03e5806e019e7796187"
nginx-core-version = "1.31.4"
nginx-core-tarball-sha256 = "e6f20b644a17a643f059ae6467a1971fe2811587d025e071068753a1f1e3b3c3"
rustscript-git = "https://github.com/rustscript-lang/rustscript"
rustscript-rev = "87d8c5d5cb42b3381aecadb383c0b7bf34ff204f"
rustscript-rev = "fc8b0c8179640a8ffe460a64b3690e35c2f7eb73"

[lib]
crate-type = ["cdylib", "rlib"]
Expand All @@ -27,7 +27,7 @@ sha1 = { version = "0.10", default-features = false }
sha2 = { version = "0.10", default-features = false }
nginx-sys = { git = "https://github.com/nginx/ngx-rust", rev = "cda9d8372ccd2e139ef2b03e5806e019e7796187" }
ngx = { git = "https://github.com/nginx/ngx-rust", rev = "cda9d8372ccd2e139ef2b03e5806e019e7796187", default-features = false, features = ["std"] }
pd-host-function = { git = "https://github.com/rustscript-lang/rustscript", rev = "87d8c5d5cb42b3381aecadb383c0b7bf34ff204f" }
pd-host-function = { git = "https://github.com/rustscript-lang/rustscript", rev = "fc8b0c8179640a8ffe460a64b3690e35c2f7eb73" }
tokio = { version = "1", default-features = false, features = ["rt", "rt-multi-thread", "time", "net", "sync", "io-util"] }
rustls = { version = "0.23", default-features = false, features = ["std", "tls12", "ring"] }
tokio-rustls = { version = "0.26", default-features = false, features = ["ring"] }
Expand All @@ -36,7 +36,7 @@ rustls-pemfile = { version = "2", default-features = false, features = ["std"] }
rustls-native-certs = "0.8"
webpki-roots = "0.26"
zeroize = { version = "1", default-features = false, features = ["alloc"] }
vm = { package = "pd-vm", git = "https://github.com/rustscript-lang/rustscript", rev = "87d8c5d5cb42b3381aecadb383c0b7bf34ff204f", default-features = false, features = ["runtime", "async", "http-client", "sqlite"] }
vm = { package = "pd-vm", git = "https://github.com/rustscript-lang/rustscript", rev = "fc8b0c8179640a8ffe460a64b3690e35c2f7eb73", default-features = false, features = ["runtime", "async", "http-client", "sqlite"] }

[features]
default = ["export-modules"]
Expand Down
9 changes: 5 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,9 +13,10 @@ request-state programs, including buffered `http::client::request`, key-auth
control flows, and `ngx.ctx`, may reuse a VM after successful `Halted` cleanup.
Their pool key contains the exact compiled `Arc<Program>` identity, phase,
complete standard-host policy, ngx catalog fingerprint, and standard catalog
fingerprint. SQLite, standard I/O, SSE, timers, sleep, cosockets, resource or
unknown host schemas, failures, cancellation, timeouts, pending cleanup, and
over-capacity returns are excluded. The worker retains at most four reusable
fingerprint. SQLite, standard I/O, SSE, timers, sleep, cosockets, dynamic host
schemas, failures, cancellation, timeouts, pending cleanup, and over-capacity
returns are excluded. Buffered HTTP is admitted: its resource handles are
quiescent within one synchronous call chain. The worker retains at most four reusable
request VMs, installs a fresh `NgxAsyncBridge` and runtime policy on checkout,
and clears request `ngx.ctx`, bridge, print sink, futures, resources, and reset
state before return. Client disconnect during a wait finalizes the request as
Expand All @@ -38,7 +39,7 @@ phase stays synchronous and fail-closed.
| --- | --- |
| [ngx-rust](https://github.com/nginx/ngx-rust) | `cda9d8372ccd2e139ef2b03e5806e019e7796187` (`ngx` / `nginx-sys` 0.5.0) |
| NGINX | Official NGINX 1.31.4 (`nginx_version` 1031004), tarball SHA-256 `e6f20b644a17a643f059ae6467a1971fe2811587d025e071068753a1f1e3b3c3` |
| RustScript / `pd-vm` | [`https://github.com/rustscript-lang/rustscript`](https://github.com/rustscript-lang/rustscript) at `87d8c5d5cb42b3381aecadb383c0b7bf34ff204f` (Cargo git dependency `package = "pd-vm"` on that immutable rev; no sibling path) |
| RustScript / `pd-vm` | [`https://github.com/rustscript-lang/rustscript`](https://github.com/rustscript-lang/rustscript) at `fc8b0c8179640a8ffe460a64b3690e35c2f7eb73` (Cargo git dependency `package = "pd-vm"` on that immutable rev; no sibling path) |
| Rust toolchain | 1.85.0 or later (ngx-rust MSRV). Verified with rustc 1.94.1 |

Required build tools on Linux:
Expand Down
12 changes: 6 additions & 6 deletions docs/api/codec.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,13 +22,13 @@ struct DecodedArgsResult {

| OpenResty API | RustScript callable | Status | Phases | Limits | Semantic differences | Acceptance |
| --- | --- | --- | --- | --- | --- | --- |
| `ngx.escape_uri` | `ngx::escape_uri(uri: string, escape_type: unknown) -> string` | adapted | `PHASE_ESCAPE_URI` | input/output caps; type `0..=8` | Second arg is `null` (default type 2, URI component) or int `0..=8`. Types match lua-nginx-module bitmaps (0 URI, 1 args, 2 component, 3 HTML, 4 refresh, 5/6 memcached, 7 header name, 8 header value). | `tests/ngx_codec.rs` (`escape_uri_*`), `tests/host_catalog.rs` |
| `ngx.escape_uri` | `ngx::escape_uri(uri: string, escape_type: unknown) -> string` | adapted | `PHASE_ESCAPE_URI` | input/output caps; type `0..=8` | Second arg is `()` (default type 2, URI component) or int `0..=8`. Types match lua-nginx-module bitmaps (0 URI, 1 args, 2 component, 3 HTML, 4 refresh, 5/6 memcached, 7 header name, 8 header value). | `tests/ngx_codec.rs` (`escape_uri_*`), `tests/host_catalog.rs` |
| `ngx.unescape_uri` | `ngx::unescape_uri(uri: string) -> string` | adapted | `PHASE_UNESCAPE_URI` | input cap | `+` becomes space; invalid `%` left as-is; non-UTF-8 bytes kept as `char::from` string. Not allowed in `ssl_session_fetch` / `ssl_session_store`. | `tests/ngx_codec.rs` (`unescape_uri_*`) |
| `ngx.encode_args` | `ngx::encode_args(args: unknown) -> string` | adapted | `PHASE_ENCODE_ARGS` | 1024 pairs; input/output caps | Catalog type is `unknown` because object literals are not `map<unknown>`; runtime requires a map. Array values emit repeated keys. `true` is a bare key; `false`/`null` omitted. Nested maps/arrays-as-single-value rejected. Duplicate map keys overwrite; use arrays for multi-value keys. Not allowed in `init` / `init_worker`. | `tests/ngx_codec.rs` (`encode_args_*`) |
| `ngx.decode_args` | `ngx::decode_args(query: string, max_args: unknown) -> DecodedArgsResult` | adapted | `PHASE_DECODE_ARGS` | default 100; hard max 1024 | Returns fields `args: map` and `truncated: bool`; only `args` is a dynamic-key map. See cross-cutting item 4. `max_args` is `null` or int. | `tests/ngx_codec.rs` (`decode_args_*`) |
| `ngx.encode_base64` | `ngx::encode_base64(input: unknown, no_padding: unknown) -> string` | adapted | `PHASE_CODEC_MISC_SSL_CLIENT_HELLO` | input/output caps | `input` is string or bytes. `no_padding` is `null`/`false` or `true`. | `tests/ngx_codec.rs` (`encode_base64_padding_and_decode_variants`) |
| `ngx.decode_base64` | `ngx::decode_base64(text: string) -> optional<bytes>` | adapted | `PHASE_CODEC_MISC_SSL_CLIENT_HELLO` | input cap | Invalid input is `null`, not an error. Padding may be omitted. | `tests/ngx_codec.rs` (`encode_base64_padding_and_decode_variants`) |
| `ngx.decode_base64mime` | `ngx::decode_base64mime(text: string) -> optional<bytes>` | adapted | `PHASE_CODEC_MISC` | input cap | Skips non-alphabet bytes; stops at first `=`. `data_len % 4 == 1` is `null`. **Not** allowed in `ssl_client_hello` (OpenResty v0.10.29 exception). | `tests/ngx_codec.rs` (`decode_base64mime_*`), `tests/host_catalog.rs` |
| `ngx.encode_args` | `ngx::encode_args(args: unknown) -> string` | adapted | `PHASE_ENCODE_ARGS` | 1024 pairs; input/output caps | Catalog type is `unknown` because object literals are not an exact map schema; runtime requires a map. Array values emit repeated keys. `true` is a bare key; `false`/`()` omitted. Nested maps/arrays-as-single-value rejected. Duplicate map keys overwrite; use arrays for multi-value keys. Not allowed in `init` / `init_worker`. | `tests/ngx_codec.rs` (`encode_args_*`) |
| `ngx.decode_args` | `ngx::decode_args(query: string, max_args: unknown) -> DecodedArgsResult` | adapted | `PHASE_DECODE_ARGS` | default 100; hard max 1024 | Returns fields `args: array<ArgEntry>` and `truncated: bool`. See cross-cutting item 4. `max_args` is `()` or int. | `tests/ngx_codec.rs` (`decode_args_*`) |
| `ngx.encode_base64` | `ngx::encode_base64(input: unknown, no_padding: unknown) -> string` | adapted | `PHASE_CODEC_MISC_SSL_CLIENT_HELLO` | input/output caps | `input` is string or bytes. `no_padding` is `()`/`false` or `true`. | `tests/ngx_codec.rs` (`encode_base64_padding_and_decode_variants`) |
| `ngx.decode_base64` | `ngx::decode_base64(text: string) -> Option<bytes>` | adapted | `PHASE_CODEC_MISC_SSL_CLIENT_HELLO` | input cap | Invalid input is `Option::None`, not an error. Padding may be omitted. | `tests/ngx_codec.rs` (`encode_base64_padding_and_decode_variants`) |
| `ngx.decode_base64mime` | `ngx::decode_base64mime(text: string) -> Option<bytes>` | adapted | `PHASE_CODEC_MISC` | input cap | Skips non-alphabet bytes; stops at first `=`. `data_len % 4 == 1` is `Option::None`. **Not** allowed in `ssl_client_hello` (OpenResty v0.10.29 exception). | `tests/ngx_codec.rs` (`decode_base64mime_*`), `tests/host_catalog.rs` |
| `ngx.crc32_short` | `ngx::crc32_short(data: string) -> int` | supported | `PHASE_CODEC_MISC_SSL_CLIENT_HELLO` | input cap | IEEE CRC-32. Currently matches `crc32_long`. | `tests/ngx_codec.rs` (`hash_and_hmac_use_fixed_vectors`) |
| `ngx.crc32_long` | `ngx::crc32_long(data: string) -> int` | supported | `PHASE_CODEC_MISC_SSL_CLIENT_HELLO` | input cap | Same result as `crc32_short` in this release. | `tests/ngx_codec.rs` (`hash_and_hmac_use_fixed_vectors`) |
| `ngx.hmac_sha1` | `ngx::hmac_sha1(secret: string, data: string) -> bytes` | adapted | `PHASE_CODEC_MISC_SSL_CLIENT_HELLO` | input cap on each arg | Raw digest **bytes**, not hex. | `tests/ngx_codec.rs` (`hash_and_hmac_use_fixed_vectors`) |
Expand Down
2 changes: 1 addition & 1 deletion docs/api/constants.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ Acceptance: `tests/ngx_meta.rs`
| `ngx.AGAIN` | `ngx::core::again() -> int` | `-2` |
| `ngx.DONE` | `ngx::core::done() -> int` | `-4` |
| `ngx.DECLINED` | `ngx::core::declined() -> int` | `-5` |
| `ngx.null` | `ngx::core::null_value() -> null` | `null` |
| `ngx.null` | `ngx::core::null_value() -> ()` | `()` |

### HTTP methods (`PHASE_CORE_CONST`)

Expand Down
4 changes: 2 additions & 2 deletions docs/api/control.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,8 @@ Hosts set request-owned `RequestDisposition` then stop the VM. AccessExec consum

| OpenResty API | RustScript callable | Status | Phases | Limits | Semantic differences | Acceptance |
| --- | --- | --- | --- | --- | --- | --- |
| `ngx.exit` | `ngx::exit(status: int) -> null` | adapted | `PHASE_EXIT` | 0, -1, -5, 100-599 | Stops VM immediately. `0` continues the access phase (`NGX_OK`). `-5` is `NGX_DECLINED`. HTTP 201/204 and `>=300` finalize via the access return. HTTP 200-299 except 201/204 send an empty response then return (NGINX does not special-case 200). `NGX_AGAIN`/`NGX_DONE` rejected. | `tests/ngx_control_flow.rs` |
| `ngx.redirect` | `ngx::redirect(uri: string, status: unknown) -> null` | adapted | `PHASE_REDIRECT` | 65536-byte URI; 301/302/303/307/308 | `status` `null` defaults to 302. Validates scope, Continue disposition, headers-not-sent, URI, and status before mutating Location/status/disposition together. First wins. | `tests/ngx_control_flow.rs`, `tests/ngx_task7_hardening.rs` |
| `ngx.exit` | `ngx::exit(status: int) -> ()` | adapted | `PHASE_EXIT` | 0, -1, -5, 100-599 | Stops VM immediately. `0` continues the access phase (`NGX_OK`). `-5` is `NGX_DECLINED`. HTTP 201/204 and `>=300` finalize via the access return. HTTP 200-299 except 201/204 send an empty response then return (NGINX does not special-case 200). `NGX_AGAIN`/`NGX_DONE` rejected. | `tests/ngx_control_flow.rs` |
| `ngx.redirect` | `ngx::redirect(uri: string, status: unknown) -> ()` | adapted | `PHASE_REDIRECT` | 65536-byte URI; 301/302/303/307/308 | `status` `()` defaults to 302. Validates scope, Continue disposition, headers-not-sent, URI, and status before mutating Location/status/disposition together. First wins. | `tests/ngx_control_flow.rs`, `tests/ngx_task7_hardening.rs` |

`ngx.exec` is **not** a production host. Import is rejected at config time. `set_uri(jump=true)` is a runtime rejection before mutation.

Expand Down
20 changes: 10 additions & 10 deletions docs/api/ctx.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,19 +3,19 @@
[Documentation](../index.md) · [Directives](../directives.md) · [API](index.md) · [Execution model](../execution-model.md) · [Security](../security.md) · [Examples](../examples/index.md) · [Compatibility](../ngx-api-compatibility.md)

`ngx.ctx` is adapted as four explicit hosts rather than a Lua table. The map
is owned by `AccessExec` (request lifetime). Hosts clone deep-owned VM values
out; callables and other non-owning runtime values are rejected. Empty and
embedded-NUL keys are rejected. `delete` returns the removed value, or `null`
if missing (OpenResty uses `ngx.ctx.key = nil`). Configuration phases cannot
import these hosts. Capability is `RequestCtx` only — ctx hosts do not read
the request pointer.
is owned by `AccessExec` (request lifetime). Values are `string`; a callable
or any non-string value is rejected. Empty and embedded-NUL keys are
rejected. `delete` returns `Option<string>`: `Option::Some(removed)` or
`Option::None` when the key is missing (OpenResty uses `ngx.ctx.key = nil`).
Configuration phases cannot import these hosts. Capability is `RequestCtx`
only — ctx hosts do not read the request pointer.

| OpenResty API | RustScript callable | Status | Phases | Limits | Semantic differences | Acceptance |
| --- | --- | --- | --- | --- | --- | --- |
| `ngx.ctx` | `ngx::ctx::get(key: string) -> unknown` | adapted | `PHASE_CTX` | missing → `null` | Explicit get; missing is `null`. | `tests/ngx_request_ctx.rs` |
| `ngx.ctx` | `ngx::ctx::set(key: string, value: unknown) -> null` | adapted | `PHASE_CTX` | 256 keys; 256-byte key; depth 16; 65536 total bytes; 1024 elems/container; 8192-byte scalar | Failed set leaves the previous value intact. Shared aliases are deep-cloned and counted per occurrence. | `tests/ngx_request_ctx.rs` |
| `ngx.ctx` | `ngx::ctx::delete(key: string) -> unknown` | adapted | `PHASE_CTX` | same key policy | Returns the removed value, or `null` if missing. | `tests/ngx_request_ctx.rs` |
| `ngx.ctx` | `ngx::ctx::clear() -> null` | adapted | `PHASE_CTX` | — | Drops every entry. OpenResty would assign a new table. | `tests/ngx_request_ctx.rs` |
| `ngx.ctx` | `ngx::ctx::get(key: string) -> Option<string>` | adapted | `PHASE_CTX` | missing → `Option::None` | Explicit get; missing is `Option::None`, a stored empty string is `Option::Some("")`. | `tests/ngx_request_ctx.rs` |
| `ngx.ctx` | `ngx::ctx::set(key: string, value: string) -> ()` | adapted | `PHASE_CTX` | 256 keys; 256-byte key; 8192-byte value | Failed set leaves the previous value intact. | `tests/ngx_request_ctx.rs` |
| `ngx.ctx` | `ngx::ctx::delete(key: string) -> Option<string>` | adapted | `PHASE_CTX` | same key policy | Returns `Option::Some(removed)` or `Option::None` if missing. | `tests/ngx_request_ctx.rs` |
| `ngx.ctx` | `ngx::ctx::clear() -> ()` | adapted | `PHASE_CTX` | — | Drops every entry. OpenResty would assign a new table. | `tests/ngx_request_ctx.rs` |

`PHASE_CTX` (OpenResty v0.10.29 `ngx.ctx` contexts): `set`, `rewrite`,
`access`, `content`, `header_filter`, `body_filter`, `log`, `timer`,
Expand Down
Loading
Loading