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
11 changes: 6 additions & 5 deletions Cargo.lock

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

4 changes: 2 additions & 2 deletions Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ name = "edge"
# Keep HTTP/3 opt-in in normal builds; release.yml enables it explicitly with --all-features.
# Do not enable `vm/edge-abi`: frozen pd-vm's optional edge-abi depends on
# crates.io pd-edge-abi 0.1.1 (ABI24). HTTP compiles and runs against the
# in-tree ABI25 catalog, exact compiler overlay, and runtime descriptors.
# in-tree ABI26 catalog, exact compiler overlay, and runtime descriptors.
default = ["console", "http", "tls", "websocket"]
console = ["http", "tls", "websocket", "edge_abi/console"]
native-jit = ["vm/cranelift-jit"]
Expand Down Expand Up @@ -73,7 +73,7 @@ h3-quinn = { version = "0.0.10", optional = true }
futures-util = "0.3"
pd-edge-host-function = { path = "./pd-edge-host-function", version = "0.1.0" }
linkme = "0.3"
vm = { package = "pd-vm", git = "https://github.com/rustscript-lang/rustscript.git", rev = "b1d6cffede77f49410bf63525f30b9a46b02dc01", version = "0.1.0", default-features = false, features = ["runtime"] }
vm = { package = "pd-vm", git = "https://github.com/rustscript-lang/rustscript.git", rev = "2f433edab3f1907e8cb060e901357d7e2af016ce", version = "0.1.0", default-features = false, features = ["runtime"] }
edge_abi = { package = "pd-edge-abi", path = "./pd-edge-abi", version = "0.1.0", default-features = false }
serde = { version = "1", features = ["derive"] }
serde_json = "1"
Expand Down
56 changes: 52 additions & 4 deletions docs/EDGE_HOST_DESCRIPTOR_MIGRATION.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Edge host descriptor and effect migration

This repository is pinned to the frozen RustScript descriptor core
`b1d6cffede77f49410bf63525f30b9a46b02dc01` (a git dependency for `pd-vm` and
`2f433edab3f1907e8cb060e901357d7e2af016ce` (a git dependency for `pd-vm` and
`pd-host-function`). This note records how the edge host surface is derived
after the migration, and which boundaries are intentionally *not* typed.

Expand Down Expand Up @@ -55,26 +55,74 @@ Their descriptor schema is the observed parameter list with an untyped return
exactly how the guest compiler represents such calls. They must not be moved
into the published ABI without a versioned ABI change.

## Named closed records (ABI version 25)
## Named closed records (ABI version 26)

Closed fixed-shape returns are overlayed as `HostTypeSchema::Named` on the
compiler catalog. Runtime values remain maps. The overlay changes the catalog
fingerprint tag, so it is an explicit ABI-versioned change.

| Function | Named schema | Runtime representation |
|---|---|---|
| `mqtt::connection::read_event` | `MqttEvent` (`kind` plus optional publish/close/fail fields) | map |
| `mqtt::connection::read_event` | `MqttEvent`: always-present `kind` plus `Option<T>` for every variant-specific member | map with canonical `Option` carriers |

Compile options install this catalog so the guest compiler sees the named
contract. The coarse `pd-edge-abi` wire type for `read_event` remains `map`.
A member the active variant does not carry is an explicit `None`
carrier, never a missing map entry and never a nullable (`optional<T>`) field:
the frozen compiler rejects a nullable field on a host output and requires the
canonical `Option` carrier for an absent member.

Published ABI namespaces (`runtime`, `tcp`, `http`, …) are exact catalog
modules. A guest file of the same name is not a host-namespace fallback;
local modules still compile when their namespace is not in the catalog.

## Fallible optional-text getters (ABI version 26)

A getter for a member that may be absent publishes
`Result<Option<string>, string>` instead of returning an empty string:

| Function | Guest contract |
|---|---|
| `http::request::get_header` | `Ok(None)` absent, `Ok(Some(""))` present-but-empty, `Err` value is not text |
| `http::request::get_query_arg` | same; a repeated key keeps the first value |
| `http::response::get_header` | same |
| `http::response::get_trailer` | same |
| `http::exchange::get_header` | same |

The wire tag is `result_option_string`; the carrier is the canonical
`Result`/`Option` map pair, so absence is never a bare Null and an undecodable
value is never an empty-string sentinel. An invalid header or trailer name
stays a fatal host error. Fields that always exist (`method`, `path`, `uri`,
`version`, `status`, ...) keep returning `string`/`int`.

## Core IO readers overridden by the edge runtime (ABI version 26)

`io::read_all` and `io::read_line` are edge overrides of core builtins: the
runtime keeps its own handles, but the guest contract is the one the frozen
compiler resolves from the core IO module. Both are published as explicit
results:

| Function | Guest contract |
|---|---|
| `io::read_all` | `Result<string, string>`: the remaining text, or the guest error |
| `io::read_line` | `Result<Option<string>, string>`: `Ok(None)` at end of stream, `Ok(Some(""))` for a blank line, one trailing `\n` stripped |
| `io::write` | `Result<int, string>`: bytes written |
| `io::flush` | `Result<(), string>` |
| `io::close` | `Result<(), string>` |

A handle or transport failure stays a fatal host error. The embedded
`http::upstream::response` wrapper propagates both text contracts (`next_line`,
`read_line`, `read_all`) instead of collapsing them.

`io::open` stays the one edge override whose value cannot match its core
contract: core publishes `Result<io.file resource, string>`, while the edge
runtime returns a raw virtual-handle `int` (see the raw-handle metadata
family). Minting a core `io.file` resource is not possible from edge scope, so
the open result keeps the raw token and no guest is currently typed against it.

## Intentional dynamic boundaries

The edge ABI is a published wire contract (ABI version 25, shared with the
The edge ABI is a published wire contract (ABI version 26, shared with the
`pd-edge-abi` crate the VM compiler links). The following stay dynamic and are
pinned by an allowlist test. WebRTC has no map/any wire types.

Expand Down
16 changes: 15 additions & 1 deletion examples/console/sample_console_http3_client.rss
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,7 @@ if argc == 0 {
console::stdout::write("http-version=" + http::exchange::get_http_version(exchange) + "\n");
console::stdout::write("alpn=" + tls::session::get_alpn(session) + "\n");

let content_type = http::exchange::get_header(exchange, "content-type");
let content_type = exchange_header_text(exchange, "content-type");
if content_type != "" {
console::stdout::write("content-type=" + content_type + "\n");
}
Expand All @@ -78,3 +78,17 @@ if argc == 0 {
console::stdout::write("\n");
console::stdout::flush();
}

// `http::exchange::get_header` reports an absent header or an undecodable
// value instead of returning an empty string. This sample only needs the value,
// so absence and a malformed value keep the previous empty-string default.
fn exchange_header_text(exchange: int, name: string) -> string {
let value: Result<Option<string>, string> = http::exchange::get_header(exchange, name);
match value {
Result::Ok(present) => match present {
Some(text) => text,
None => "",
},
Result::Err(error) => "",
}
}
Loading
Loading