Skip to content

feat(host)!: migrate the ngx catalog and RSS surface to Unit/Option/Result - #3

Merged
fffonion merged 15 commits into
masterfrom
feat/unit-option-result-contract
Nov 15, 2026
Merged

fffonion merged 15 commits into
masterfrom
feat/unit-option-result-contract

Conversation

@fffonion

Copy link
Copy Markdown
Contributor

Moves ngx-rustscript onto core fc8b0c81 and removes the legacy Null/Optional/Unknown host exits the compiler now rejects.

Core pin

  • pd-host-function, vm, and the metadata rustscript-rev point at fc8b0c81; the lock moves only the three core packages.
  • Compile surface was already green at the pin; the work is the runtime contract.

Catalog

  • 46 void hosts return Unit instead of Null; a guard test asserts no host output carries Unknown, Null, or Optional recursively.
  • var::get, req::get_body_data, req::get_body_file, req::http_version, decode_base64, decode_base64mime, parse_http_time, ctx::get, ctx::delete, and header::get return guest Option<T> built from vm::option::{some_carrier, none_carrier}.
  • Header, arg, and decoded-arg results are {name, value} entry arrays (ArgEntry.value is Option<string>: a bare key is None, a= is Some("")); repeats survive.
  • Shared dict uses a tagged SharedValue record (kind + one Option payload), error: Option<string>, and delete -> bool; a ttl miss yields value: None.
  • ctx is string-valued; timers register with a Unit result and invoke fn(bool) -> ().
  • compile_host_catalog() merges pd-vm's standard catalog (I/O, HTTP, SQLite) and the production registry installs those modules from the same snapshot, so resource handles bind exactly. Quiescent buffered HTTP is admitted to VM reuse.

RSS surface and docs

  • Every null literal and T? annotation in tests, fixtures, examples, and docs becomes (), Option::Some/Option::None, or Result with ?.
  • HTTP examples use the resource builder (http::request::new, set_header(&mut …), http::response::*); SQLite uses SqliteOpenOptions/SqliteValue.
  • standard-async, ctx, shared-dict, request, response, codec, timer, host-descriptors, compatibility, security, examples, and README follow the new contract.

Verification (real nginx 1.31.4, default test threads)

  • cargo check --locked: 0
  • cargo test --locked: 1609 passed / 0 failed / 0 ignored, exit 0
  • cargo fmt --all -- --check: 0
  • cargo clippy --locked --all-targets -- -D warnings: 0

Test-fixture changes only serialize fixtures that contend for worker slots and move measurement start points past VM/driver setup; no assertion was weakened and no business code was touched for them.

Advance the RustScript core pin from 87d8c5d5 to fc8b0c8179
(CORE_TARGET) and refresh Cargo.lock, which relocks exactly
pd-host-function, pd-host-schema, and pd-vm.

fc8b0c81 extends HostTypeSchema with Unit/Option/Result. The library
and every test target still compile: the only source break was a
non-exhaustive match in ngx_scheduler_contract's callable walker, now
recursing into Option/Result and treating Unit as a leaf.

Host-contract adaptation is NOT included: the new core rejects host
functions whose declared return schema is Unknown, Null, or Optional
(host_output_forbidden), and rejects RSS `null` literals. 76 of the
199 catalogued ngx hosts still declare a rejected return schema, so
the runtime suite is red until that migration lands.
The pinned pd-host-function/pd-vm (fc8b0c81) compiler rejects any host
function whose declared return schema is Null, Optional, or Unknown with
"returns a dynamic or legacy-null schema, which RustScript does not admit".
Every void ngx host therefore failed at configuration time, which is most
of the runtime rejection surface.

- 46 void host returns move from `HostTypeSchema::Null` to `::Unit`;
  `ngx::core::null_value` keeps `Null` because it deliberately hands guest
  code a null value and is the null-literal probe.
- Unit's physical carrier is the internal Null value, so the host
  implementations already emit it through `ret(())`; no implementation
  path had to change.
- Bump NGX_HOST_CATALOG_SCHEMA_VERSION to 4 and refresh the fingerprint
  golden, which the schema tags feed.
- Sync every catalog return-type assertion in the integration tests and add
  a guard test that keeps legacy Null host returns out of the catalog.
Pin pd-vm at fc8b0c81 and move every host output onto the RustScript guest
contract. RustScript now rejects `unknown`, `null`, and the legacy
`optional<T>` schema anywhere in a host output, so the catalog, the host
implementations, and every RSS consumer move together.

Catalog (schema version 5, fingerprint retargeted):

* Logical absence is guest `Option<T>` (`{tag, payload}` carriers built from
  `vm::option::{some_carrier,none_carrier}`): `var::get`,
  `req::get_body_data`, `req::get_body_file`, `req::http_version`,
  `decode_base64`, `decode_base64mime`, `parse_http_time`, `ctx::get`,
  `ctx::delete`, `header::get`, and every option-typed named field.
* Void results are Unit: `ngx::core::null_value` (was `Null`), timer
  registration (was `Bool`), and every `error`/`value` absence carrier.
* Header and argument bags are typed entry arrays instead of dynamic maps:
  `HeaderEntry { name, value }`, `ArgEntry { name, value: Option<string> }`.
  Repeated names repeat the entry, so duplicate headers and repeated query
  arguments survive; a bare query key is `Option::None`, `a=` is
  `Some("")`.
* Shared dictionary values are the tagged `SharedValue` record (`kind` plus
  one `Option` payload) and `ngx::shared::delete` returns `bool`.
* `ngx::ctx` values are `string`: get/delete return `Option<string>` and a
  non-string value is rejected.
* `ngx::header::get` returns the first value as `Option<string>`.
* timer callback schema is `fn(bool) -> ()` and the registration returns
  `()`.

Compile/runtime contract:

* `compile_host_catalog()` now merges pd-vm's standard host catalog
  (I/O, HTTP, SQLite) with the ngx surface and the production registry
  installs those modules from the same snapshot. Without that, a standard
  handle resolved through the legacy builtin table carried an `int` that
  the resource-typed sibling hosts reject.
* Quiescent buffered HTTP (`http::*` request/response/header resources) is
  admitted to statically reused request VMs; SQLite/I/O/SSE stay excluded.
* Standard-family use is detected from catalog imports as well as legacy
  builtins, so request-owned execution selection is unchanged for both
  paths.

RSS consumers: tests, fixtures, examples, and documentation use the guest
types (`Option::Some`/`Option::None`, `Result::Ok`/`Result::Err` with `?`,
`()`), the resource-based HTTP builder (`http::request::new`,
`set_header(&mut ..)`, `http::response::*`), the `SqliteOpenOptions`/
`SqliteValue` records, and typed entry arrays. Stub- and zone-backed test
binaries serialize on a per-binary lock so process-global stub counters and
in-process zones no longer race under the default test threading.
…t polls

parse_http_time now returns a guest Option, so the fixed-date test asserts
Some(1290079655) and None instead of a bare int and a physical Null.
The live-socket poll-order tests take the existing socket test lock: a
loaded machine can flip a Pending poll to Ready when they overlap.
Driver::new() pays the worker runtime start (~2.7s on a loaded host), which
the 1.5s bound was counting as connect latency. Build the driver first and
start the clock at pump_until, so the assertion still proves the oversized
host is rejected before any lookup.
@fffonion
fffonion force-pushed the feat/unit-option-result-contract branch from b0bbd20 to 0f41f58 Compare November 15, 2026 08:59
@fffonion
fffonion merged commit c9a0a26 into master Nov 15, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant