Skip to content

polyengine 0.3.0 (the deltic rename); @polymorph/webrtc-datachannels 0.3.0 #164

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lannbot merged 1 commit into from
Aug 22, 2026
Merged

polyengine 0.3.0 (the deltic rename); @polymorph/webrtc-datachannels 0.3.0 #164

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
10 changes: 5 additions & 5 deletions .github/justfile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,19 +38,19 @@ conformance-build:
@just gha::_step conformance::build
@just gha::_step conformance::_ct-tools

# The loopback targets (wasmtime, composed, deltic-deno, deltic-browser)
# The loopback targets (wasmtime, composed, polyengine-deno, polyengine-browser)
# and the interop directions, aggregated against both committed
# lockfiles, then gated against both committed matrices. In CI the
# artifacts arrive prebuilt from the build job; locally
# `just gha::conformance-build` produces them. deltic-check needs only
# `just gha::conformance-build` produces them. polyengine-check needs only
# Deno + network, so it rides this job too.
conformance-matrix:
@just gha::_step conformance::lock-check
@just gha::_step deltic-check
@just gha::_step polyengine-check
@just gha::_step conformance::run-wasmtime
@just gha::_step conformance::run-composed
@just gha::_step conformance::run-deltic
@just gha::_step conformance::run-deltic-browser
@just gha::_step conformance::run-polyengine
@just gha::_step conformance::run-polyengine-browser
@just gha::_step conformance::run-interop
@just gha::_step conformance::aggregate
@just gha::_step conformance::matrix-check
Expand Down
38 changes: 19 additions & 19 deletions .github/workflows/conformance.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ name: Conformance
# and cached — exactly once per run.
#
# The `matrix` job runs the loopback targets (wasmtime, composed,
# deltic-deno, deltic-browser — the full solo+pair suite each) and the
# polyengine-deno, polyengine-browser — the full solo+pair suite each) and the
# interop directions (every implementation against the libwebrtc
# reference peer in both orders, the reference self-pair, and the direct
# implementation pairs — the pair-only suite), aggregates every stream
Expand Down Expand Up @@ -64,7 +64,7 @@ jobs:
# Owns the rev derivation, the rev-keyed tools cache, the
# install, and the pins gate; conformance::_ct-tools recognizes
# the stamped install and does not repeat it.
uses: polymorph-components/polymorph-test/actions/setup@b4444a25a22106ad4128549bdc9e579552e62210
uses: polymorph-components/polymorph-test/actions/setup@38bfedf2b989522b82ddce5320fc1557a2f61461
with:
tools: component-test-cli

Expand Down Expand Up @@ -105,24 +105,24 @@ jobs:
- name: Checkout code
uses: actions/checkout@v5

# The deltic-browser leg's page driver runs under Node (playwright
# The polyengine-browser leg's page driver runs under Node (playwright
# against the runner image's Chrome; no engine flag anywhere).
- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version: "24"
cache: npm
cache-dependency-path: conformance/driver-ct/deltic/package-lock.json
cache-dependency-path: conformance/driver-ct/polyengine/package-lock.json

# The deltic legs run the suite runtime-linked — deltic-deno under
# stock Deno, deltic-browser inside Chromium — no engine flag (see
# conformance/driver-ct/deltic/README.md).
- name: Set up Deno (the deltic legs; stock, no flags)
# The polyengine legs run the suite runtime-linked — polyengine-deno under
# stock Deno, polyengine-browser inside Chromium — no engine flag (see
# conformance/driver-ct/polyengine/README.md).
- name: Set up Deno (the polyengine legs; stock, no flags)
uses: denoland/setup-deno@v2
with:
deno-version: "2.9.5"

# Runtime dependencies only (the deltic legs' module graphs and npm
# Runtime dependencies only (the polyengine legs' module graphs and npm
# trees are materialized by their own just recipes). The netns lab
# never runs in CI, so its apt packages are skipped.
- name: Install dependencies
Expand All @@ -149,37 +149,37 @@ jobs:
# against the pin.
- name: Publish the conformance matrix
if: always() && hashFiles('conformance/driver-ct/results/*.jsonl') != ''
uses: polymorph-components/polymorph-test/actions/aggregate@b4444a25a22106ad4128549bdc9e579552e62210
uses: polymorph-components/polymorph-test/actions/aggregate@38bfedf2b989522b82ddce5320fc1557a2f61461
with:
lock: conformance/guest-ct/tests.lock
manifest: conformance/driver-ct/targets.toml
results: |
wasmtime=conformance/driver-ct/results/wasmtime.jsonl
composed=conformance/driver-ct/results/composed.jsonl
deltic-deno=conformance/driver-ct/results/deltic-deno.jsonl
deltic-browser=conformance/driver-ct/results/deltic-browser.jsonl
polyengine-deno=conformance/driver-ct/results/polyengine-deno.jsonl
polyengine-browser=conformance/driver-ct/results/polyengine-browser.jsonl
summary-title: Conformance matrix
cli: target/ct-tools/bin/component-test
cargo-lock: Cargo.lock

- name: Publish the interop conformance matrix
if: always() && hashFiles('conformance/driver-ct/results/*.jsonl') != ''
uses: polymorph-components/polymorph-test/actions/aggregate@b4444a25a22106ad4128549bdc9e579552e62210
uses: polymorph-components/polymorph-test/actions/aggregate@38bfedf2b989522b82ddce5320fc1557a2f61461
with:
lock: conformance/guest-pair-ct/tests.lock
manifest: conformance/driver-ct/targets-interop.toml
results: |
reference=conformance/driver-ct/results/reference.jsonl
wasmtime-x-reference=conformance/driver-ct/results/wasmtime-x-reference.jsonl
reference-x-wasmtime=conformance/driver-ct/results/reference-x-wasmtime.jsonl
deltic-deno-x-reference=conformance/driver-ct/results/deltic-deno-x-reference.jsonl
reference-x-deltic-deno=conformance/driver-ct/results/reference-x-deltic-deno.jsonl
deltic-browser-x-reference=conformance/driver-ct/results/deltic-browser-x-reference.jsonl
reference-x-deltic-browser=conformance/driver-ct/results/reference-x-deltic-browser.jsonl
polyengine-deno-x-reference=conformance/driver-ct/results/polyengine-deno-x-reference.jsonl
reference-x-polyengine-deno=conformance/driver-ct/results/reference-x-polyengine-deno.jsonl
polyengine-browser-x-reference=conformance/driver-ct/results/polyengine-browser-x-reference.jsonl
reference-x-polyengine-browser=conformance/driver-ct/results/reference-x-polyengine-browser.jsonl
wasip3-guest-x-reference=conformance/driver-ct/results/wasip3-guest-x-reference.jsonl
reference-x-wasip3-guest=conformance/driver-ct/results/reference-x-wasip3-guest.jsonl
wasmtime-x-deltic-deno=conformance/driver-ct/results/wasmtime-x-deltic-deno.jsonl
deltic-deno-x-wasmtime=conformance/driver-ct/results/deltic-deno-x-wasmtime.jsonl
wasmtime-x-polyengine-deno=conformance/driver-ct/results/wasmtime-x-polyengine-deno.jsonl
polyengine-deno-x-wasmtime=conformance/driver-ct/results/polyengine-deno-x-wasmtime.jsonl
wasmtime-x-wasip3-guest=conformance/driver-ct/results/wasmtime-x-wasip3-guest.jsonl
wasip3-guest-x-wasmtime=conformance/driver-ct/results/wasip3-guest-x-wasmtime.jsonl
summary-title: Interop conformance matrix
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/copilot-setup-steps.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ jobs:
- name: Set up Node.js
uses: actions/setup-node@v4
with:
# Node 24+ for the deltic browser page drivers (plain node, no
# Node 24+ for the polyengine browser page drivers (plain node, no
# engine flag).
node-version: "24"

Expand Down
4 changes: 2 additions & 2 deletions .github/workflows/jsr-publish.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Publish @polymorph/webrtc-datachannels (deltic-impl) to JSR.
# Publish @polymorph/webrtc-datachannels (polyengine-impl) to JSR.
#
# Auth is GitHub Actions OIDC: the package's GitHub-repository link on
# jsr.io authorizes runs from this repository — no tokens. Dispatch
Expand All @@ -20,4 +20,4 @@ jobs:
with:
deno-version: "2.9.5"
- run: deno publish
working-directory: deltic-impl
working-directory: polyengine-impl
42 changes: 21 additions & 21 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ Guidance for automated agents (and humans) working in this repository.

`polymorph:webrtc-datachannels`: a WIT interface plus multiple implementations that
run the *same* guest component over a real WebRTC data channel: two hosts
(Wasmtime and deltic) and one in-guest component (`wasip3-impl`). It is
(Wasmtime and polyengine) and one in-guest component (`wasip3-impl`). It is
intentionally small — prefer clarity and correctness over features, and keep the
implementations behaviourally in sync (asserted by the conformance suite under
[`conformance/`](conformance)). See [`README.md`](README.md) for the findings
Expand Down Expand Up @@ -47,12 +47,12 @@ wasmtime-impl/ # Wasmtime host crate (webrtc-rs),
# modeled after wasmtime_wasi_http::p3;
# add_to_linker + WebrtcView (types + connections.data-channel-options/data-channel);
# crate name: wasmtime-webrtc-datachannels
deltic-impl/ # deltic-native host module (stock Deno,
polyengine-impl/ # polyengine-native host module (stock Deno,
# runtime-linked; node-datachannel-backed):
# deltic's ports/webrtc reference-host port,
# upstreamed per lann/deltic#14; pinned to a
# deltic prerelease via JSR import maps (see
# deltic-impl/README.md)
# polyengine's ports/webrtc reference-host port,
# upstreamed per polymorph-components/polyengine#14; pinned to a
# polyengine prerelease via JSR import maps (see
# polyengine-impl/README.md)
wasip3-impl/ # wasm COMPONENT on `rtc` 0.21: runs the
# sans-I/O stack in-guest (SansIoPeer core
# + a wasi:sockets/clocks runtime driver)
Expand Down Expand Up @@ -87,8 +87,8 @@ conformance/ # cross-implementation conformance suite,
driver-ct/ # rtc-ct-driver (child exec mode + loopback/
# interop/shadow/netns orchestrators, the
# pair fold, the ported netns topology and
# Shadow syscall shim), the deltic
# children (deltic/),
# Shadow syscall shim), the polyengine
# children (polyengine/),
# targets*.toml manifests, and the
# committed matrix.md + matrix-interop.md
reference/ # the non-wasm reference peer (libwebrtc via
Expand Down Expand Up @@ -146,15 +146,15 @@ updating the consumers that name them as strings:
`deps/polymorph-webrtc-datachannels` symlink),
- the Wasmtime host bindings in `examples/wasmtime-demo/src/main.rs`,
- the conformance suite bodies and driver under `conformance/`, and
- the deltic import-record assembly in `deltic-impl/src/webrtc.ts` (the
- the polyengine import-record assembly in `polyengine-impl/src/webrtc.ts` (the
interface keys and error-class wiring the conformance children and any
embedder use).

## Build & run

Prerequisites: Rust with the `wasm32-unknown-unknown` target, `wasm-tools`,
Deno 2.x for the deltic paths (`deltic-impl/` and the deltic conformance
legs; stock Deno, no flags), and Node 24+ for the deltic browser page
Deno 2.x for the polyengine paths (`polyengine-impl/` and the polyengine conformance
legs; stock Deno, no flags), and Node 24+ for the polyengine browser page
drivers (plain `node`, no engine flag).

### One-shot dependency setup: `scripts/setup.sh`
Expand All @@ -174,7 +174,7 @@ It adds the `wasm32-unknown-unknown` and `wasm32-wasip2` Rust targets; installs
`wasm-tools`, `just`, `cargo-nextest`, `wac`, and `wasmtime` (each skipped if
already on `PATH`; versions pinned via `*_VERSION` variables); installs the
netns-lab tools (iproute2, nftables, coturn; skip with `SKIP_NETNS_LAB=1`).
The deltic legs' runtime dependencies are not installed here: their just
The polyengine legs' runtime dependencies are not installed here: their just
recipes materialize the pinned module graph and npm trees on first run. It does
**not** install the Shadow network simulator (see below). CI is kept in sync by
calling this same script rather than duplicating the install steps.
Expand All @@ -193,11 +193,11 @@ missing when the lab runs.
# Guest component (produces examples/echo-demo/build/echo-demo.component.wasm):
just examples::build-component

# deltic (runtime-linked JS) host — the conformance legs are the maintained
# polyengine (runtime-linked JS) host — the conformance legs are the maintained
# entry points (stock Deno; headless Chromium for the browser leg, which is
# also the CI check for the browser path; set CHROME_PATH to override):
just conformance::run-deltic
just conformance::run-deltic-browser
just conformance::run-polyengine
just conformance::run-polyengine-browser

# Wasmtime (native) host (defaults: 1000 messages of 4096 bytes):
just examples::demo-wasmtime # or: just examples::demo-wasmtime 1000 4096
Expand All @@ -215,7 +215,7 @@ just test

# Cross-implementation conformance suite: builds the two suite
# components, runs every loopback target (wasmtime, composed,
# deltic-deno, deltic-browser) and every interop direction (every
# polyengine-deno, polyengine-browser) and every interop direction (every
# implementation against the non-wasm reference peer in both orders, the
# reference self-pair, and the direct implementation pairs), aggregates
# against the committed lockfiles + manifests, and diffs the committed
Expand Down Expand Up @@ -268,7 +268,7 @@ in doubt about whether a recipe's scope is touched, run it.
| `just examples::build-component` | the `echo-demo` guest or its WIT. |
| `just examples::test-webrtc-composed` | the `wasip3-impl` provider component, the `webrtc-consumer`, or the `connections` WIT (composes them with `wac plug` and runs the round trip under `wasmtime`). |
| `just examples::test-echo-remote-composed` | the `echo-remote` guest, `rendezvous-http`, the `wasip3-impl` provider, or the `rendezvous`/`remote` WIT (composes the fully in-guest peer and connects two `wasmtime run` processes over a signaling server). |
| `just deltic-check` | the deltic host module (`deltic-impl/`) or the deltic conformance leg's TS (`conformance/driver-ct/deltic/`): type-checks both and runs the `deltic-impl` unit tests. Behavior changes also need `just conformance` (the `deltic-deno` target). |
| `just polyengine-check` | the polyengine host module (`polyengine-impl/`) or the polyengine conformance leg's TS (`conformance/driver-ct/polyengine/`): type-checks both and runs the `polyengine-impl` unit tests. Behavior changes also need `just conformance` (the `polyengine-deno` target). |
| `just conformance` | any host/guest behavior the suite asserts — the WIT surface, a host implementation, the suite bodies, the driver, or the manifests (CI runs it in `.github/workflows/conformance.yml`). Intentional case changes also need `just conformance::lock-update`; intentional behavior changes, `just conformance::matrix-update` — commit the diffs. |
| `just check` | broad Rust/WIT changes — the quick gate for most commits. |
| `just ci` | anything broad — reproduces CI locally: the rust checks and the full conformance suite; the Shadow lab runs separately (`just gha::shadow-lab`, needs the shadow binary). |
Expand Down Expand Up @@ -334,7 +334,7 @@ documented at its use site):
| Variable | Read by | Effect |
| --- | --- | --- |
| `WEBRTC_UDP_BIND_ADDR` | `wasip3-impl` provider | IP address the in-guest `peer-connection` binds its UDP socket to (and derives its host candidate from); default IPv4 loopback. An unparsable value constructs dead connections (methods fail `closed`; the cause is printed to stderr). |
| `WEBRTC_MAX_INBOUND_BUFFER_BYTES` | all three implementations, but only the `wasip3-impl` guest reads it directly (the env var is its only channel); the host libraries read no ambient state — the Wasmtime hosts (demo binaries, conformance adapter) wire the variable through `WebrtcCtx`, and the deltic children wire it through `deltic-impl`'s exported `setMaxInboundBufferBytes` hook (embedders call the hook directly; there is no `globalThis` channel) | Overrides the 8 MiB inbound buffer bound; primarily a test knob (the conformance overflow probe shrinks it). Set-but-invalid values fail loud. |
| `WEBRTC_MAX_INBOUND_BUFFER_BYTES` | all three implementations, but only the `wasip3-impl` guest reads it directly (the env var is its only channel); the host libraries read no ambient state — the Wasmtime hosts (demo binaries, conformance adapter) wire the variable through `WebrtcCtx`, and the polyengine children wire it through `polyengine-impl`'s exported `setMaxInboundBufferBytes` hook (embedders call the hook directly; there is no `globalThis` channel) | Overrides the 8 MiB inbound buffer bound; primarily a test knob (the conformance overflow probe shrinks it). Set-but-invalid values fail loud. |
| `WEBRTC_INCLUDE_LOOPBACK` | the `wasmtime-demo` binaries | Enables loopback ICE candidates so same-host peers can pair. |
| `CONFORMANCE_SHADOW_SYSCALL_SHIM` | `rtc-ct-driver` | Arms the Shadow syscall shim; set only by the Shadow executor on simulated wasmtime-kind peers. |
| `RTC_CT_ROLE`, `RTC_CT_SIGNALING_URL`, `RTC_CT_RUN_ID` | the conformance suites (via the store environment) | The pair-instance channel: which half this instance drives, the mailbox base URL, and the room-derivation seed. Set by `rtc-ct-driver` on the children it spawns; never set by hand. |
Expand All @@ -344,7 +344,7 @@ documented at its use site):
Every env var is an undeclared API each deployer must discover, and this
table is its only registry — so add no new implementation-level env var
without first considering the proper channel: `WebrtcCtx` on the Wasmtime
host, an exported configure hook for the deltic host module (a module-level
host, an exported configure hook for the polyengine host module (a module-level
knob captured at channel creation), or the WIT surface itself (as
`peer-connection-config` demonstrates for in-guest configuration).
`WEBRTC_UDP_BIND_ADDR` is environment-shaped on purpose: the bind address is
Expand All @@ -364,8 +364,8 @@ exist:

- the Wasmtime demo host implements it natively (the `echo-remote` binary in
`examples/wasmtime-demo`; `just examples::demo-remote`),
- the conformance deltic children implement the same mailbox protocol over
`fetch` (`conformance/driver-ct/deltic/signaling.ts`), and
- the conformance polyengine children implement the same mailbox protocol over
`fetch` (`conformance/driver-ct/polyengine/signaling.ts`), and
- [`examples/rendezvous-http`](examples/rendezvous-http) is a **component**
implementing it over in-guest `wasi:http@0.3`, composable under the guest so
a plain `wasmtime run -S http` provisions it (the fully in-guest path below).
Expand Down
Loading
Loading