Skip to content

feat(abi)!: make absent HTTP header, query, and trailer values explicit (ABI 26) - #3

Merged
fffonion merged 9 commits into
masterfrom
feat/abi26-optional-text-getters
Nov 16, 2026
Merged

fffonion merged 9 commits into
masterfrom
feat/abi26-optional-text-getters

Conversation

@fffonion

@fffonion fffonion commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

Moves pd-edge onto the frozen core revision 2f433eda and replaces the empty-string absence sentinels on the HTTP header/query/trailer getters with Result<Option<string>, string>.

ABI 26 (abi.json regenerated; drift test passes)

  • http::request::get_header, http::request::get_query_arg, http::response::get_header, http::response::get_trailer, http::exchange::get_header, http::exchange::get_trailer all return Result<Option<string>, string>: absent = Ok(None), present-but-empty = Ok(Some("")), undecodable bytes = Err(original text), invalid header name stays a fatal VmError. Fixed fields (method, path, uri, version, status) keep their scalar types.
  • Carriers are the core canonical {tag, payload} Result/Option shapes (vm::result::carrier + vm::option::{some,none}_carrier), not an app envelope.

Core pin and contract alignment

  • pd-vm and pd-host-function pin 2f433edab3f1907e8cb060e901357d7e2af016ce; bridge gains poll_submitted_op/cleanup_op, SourceFlavor follows the new shape, AbiValueType::Null becomes Unit.
  • Edge IO overrides now publish the core contracts: read_all/write/flush/close as Result<...>, read_line as Result<Option<string>, string> with EOF = Ok(None), blank line = Ok(Some("")), one trailing \n stripped and \r kept (CRLF covered by a named test).
  • MQTT MqttEvent emits all eight members on every variant, using Option<T> carriers instead of missing keys.
  • Anthropic samples drop legacy null (() and Unit), and the wrapper stops publishing get_headers() because dynamic-header maps remain deliberately untyped in ABI 26; the typed get_header is the supported path (migration note in stdlib/rss/http/upstream/response.rss).

Known residual: edge io::open still returns a raw virtual handle int; the edge scope cannot mint a core resource, so the descriptor contract is documented and allow-listed (docs/EDGE_HOST_DESCRIPTOR_MIGRATION.md).

Verified on head a0f3aacc1209276e7f158f1061848169abea925c: cargo test --locked (with RUST_TEST_THREADS=1) — 11 suites, 275 passed, 0 failed, 0 ignored; cargo check --locked, cargo clippy --locked --tests -- -D warnings, cargo fmt --all -- --check, and git diff --check all pass. All checked-in RSS examples and embedded test-script Option patterns use bare Some / None as required by the pinned core; Result::Ok / Result::Err remain qualified. Debugger integration-test timeouts were extended for loaded runners after the initial broad run timed out; the three focused debugger tests and the final complete run pass.

Pin the workspace to the frozen descriptor core fc8b0c81 and turn the five
HTTP getters that can be absent into explicit results instead of empty
strings:

  http::request::get_header
  http::request::get_query_arg
  http::response::get_header
  http::response::get_trailer
  http::exchange::get_header

All five publish Result<Option<string>, string>: an absent member is Ok(None),
a present empty value is Ok(Some("")), a member that is not valid text is
Err(text), and an invalid header or trailer name stays a fatal VmError. The
wire tag is result_option_string over the canonical Result/Option carriers, so
absence is never a bare Null and a decode failure is never an empty-string
sentinel. Fields that always exist (method, path, uri, version, status) keep
their string/int returns. ABI_VERSION moves 25 -> 26 and the checked-in
manifest is regenerated from an --all-features build.

Void host functions now publish Unit instead of the legacy Null schema, which
the frozen compiler no longer admits.

Pin surface adaptation: HostAsyncBridge gained poll_submitted_op/cleanup_op
(edge cleanup drops the pending future, which is the cancellation), and
SourceFlavor is now RustScript | Plugin(FrontendId) in the fixture sweep. Two
toolchain lints were suppressed at pre-existing sites so clippy -D warnings
stays green.

Every RSS call site keeps its detection strings and rules unchanged and
collapses the new contract through one local helper, so Ok(None) and Err read
as "" exactly as the previous empty-string default did. The embedded stdlib
wrapper http::upstream::response::get_header propagates the new contract
instead of collapsing it.

Named tests cover absent, present-empty, invalid text, invalid name, the
repeated query key, and the response header/trailer decode paths.
…the frozen core contracts

The ABI 26 pin exposed three contract mismatches the runtime still carried:

1. The edge io overrides must encode the contracts the guest compiler
   resolves from the core IO module, and they returned bare values:
   - io::read_line is Result<Option<string>, string>. The line reader now
     distinguishes end of stream from a blank line (Ok(None) vs Ok(Some("")),
     one trailing \n stripped) and the downstream line finalizer closes the
     transport on Ok(None) instead of on an empty chunk.
   - io::read_all is Result<string, string>.
   - io::write is Result<int, string>; io::flush and io::close are
     Result<(), string>.
   io::open stays the documented exception: core publishes
   Result<io.file resource, string> and edge scope can only return a raw
   virtual-handle int. The embedded http::upstream::response wrapper now
   propagates next_line/read_line/read_all.

2. mqtt::connection::read_event overlayed its closed record with nullable
   (optional<T>) members, which the frozen compiler rejects on a host output.
   Every variant-specific member is now Option<T> and the runtime emits the
   canonical Option carrier for an absent member, so a publish event carries
   reason=None and a closed/failed event carries topic=None and friends.

3. sample_anthropic_*_program.rss still used the removed `null` type/value.
   It now uses Unit (()) with identical rules and detection strings.

The embedded wrapper drops its get_headers helper: the open header map stays a
deliberate dynamic boundary in ABI 26 and the frozen compiler does not admit a
dynamic host output as a guest value, so no wrapper can publish it.

Every RSS call site keeps its detection strings and rules and collapses the new
contract through one local helper (absent/error still read as ""), except the
stdio wrapper which propagates.

Named coverage: read_next_line blank-line/EOF/delimiter unit tests, MqttEvent
carrier tests for publish and closed, and end-to-end proxy cases for
exchange::get_header present/empty/absent and a present upstream response
trailer.
…iew notes

Sixth optional-text getter: http::exchange::get_trailer published a bare string,
so an absent trailer, an empty trailer, and a trailer that is not valid text all
read as "". It now publishes Result<Option<string>, string> like the other five
(absent=Ok(None), empty=Ok(Some("")), non-text=Err, invalid name stays a fatal
VmError), over the same result_option_string wire tag and the shared
optional_header_text/optional_text_outcome helpers. ABI stays 26 (unreleased);
the checked-in abi.json is regenerated from an --all-features build and moves
only that one entry.

The selection is factored into exchange_trailer_value so the absent / present
empty / invalid text / invalid name semantics are covered by named unit tests
that decode the real guest carrier rather than a coerced string.

Also:
- read_next_line gains a named \r\n boundary test: "a\r\nb" yields Some("a\r"),
  because only the \n delimiter is stripped and a preceding \r is kept, matching
  the core reader.
- The io::read_line doc comment claimed a handle or read failure surfaces as the
  guest Err; the implementation fails closed with a fatal host error, so the
  comment now says so (and records the \r-kept rule).
- docs/EDGE_HOST_DESCRIPTOR_MIGRATION.md still pinned the pre-migration core
  b1d6cffe; it now names the frozen pin fc8b0c81.
Core exposed the VMBC codec outside the runtime feature; pick up that revision
so the ABI crate and its downstream consumers share one pd-vm source.
@fffonion
fffonion force-pushed the feat/abi26-optional-text-getters branch from f4a6836 to 1ab0dec Compare November 15, 2026 12:46
pd-edge-abi asked for pd-vm/runtime only to reach GuestOption and GuestResult,
but the core crate root exports both without any feature. Feature unification
pushed that runtime onto every compiler-only consumer, so IronRust's
`Check compiler-only dependencies` step failed on `pd-vm ... features=runtime`
on both Ubuntu and Windows.

Request no pd-vm features from the ABI manifest and lock the compiler-only ABI
surface down with a cargo-tree guard in the pin tests. The workspace runtime
keeps vm/runtime through its own pin; only the descriptor ABI stops asking.
The runtime pinned pd-vm at fc8b0c81 while the ABI crate pinned pd-host-function
and pd-vm at 8db45832, so the lock carried two copies of each core package and
the single-revision pin tests failed both before and after the ABI-only change.

Move the root vm pin to 8db45832: the descriptor codec is public there without
the runtime feature, the runtime feature set is unchanged, and root, ABI and
lock now resolve every core git package to one revision again, which is the
single CORE_TARGET the migration plan assumes. Cargo.lock drops the duplicate
pd-vm, pd-host-function and pd-host-schema entries; no other package moves.

FROZEN_CORE_REV and the migration note now name 8db45832, and
pd_vm_enabled_features goes back to a plain name lookup: its source filter only
existed to pick the runtime copy out of the temporary two-pin graph. The strict
per-manifest and lock assertions are untouched.
@fffonion
fffonion merged commit 8376919 into master Nov 16, 2026
8 checks 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