@mertushka/webrtc-node 0.1.0-alpha.0

package/docs/architecture.md

@@ -0,0 +1,38 @@
+# Architecture
+
+The package is intentionally split between a thin native layer and a
+browser-compatible JavaScript facade.
+
+## Native Addon
+
+`src/native/addon.cc` owns `libdatachannel` handles and exposes a small
+Node-API surface to JavaScript. It must remain ABI-stable and must not use
+direct V8 or NAN APIs.
+
+Native callbacks never call JavaScript directly from `libdatachannel` callback
+threads. They dispatch back to Node through a thread-safe function.
+
+## JavaScript Facade
+
+`lib/index.js` implements the W3C-facing behavior:
+
+- WebIDL-style conversions
+- DOM-style `EventTarget` behavior
+- promise timing and operations-chain behavior
+- WebRTC state mapping
+- `DOMException`-style errors
+- data-channel message, open, close, and buffered amount semantics
+
+Keep browser-compatible behavior in JavaScript unless native behavior is
+required for correctness.
+
+## Type Declarations
+
+`index.d.ts` describes the public API. Any runtime API change must update the
+declarations and `scripts/check-api-surface.js` as needed.
+
+## Scope Boundary
+
+The public scope is `RTCPeerConnection` plus `RTCDataChannel` for the WebRTC
+data-channel profile. Media tracks, transceivers, RTP sender/receiver APIs,
+stats, DTMF, and capture devices are not implemented.

package/docs/conformance.md

@@ -0,0 +1,53 @@
+# Conformance
+
+The compatibility target is the selected WPT subset in `wpt-manifest.json`.
+This project targets the WebRTC data-channel profile exposed through
+`RTCPeerConnection` and `RTCDataChannel`.
+
+## Selected Scope
+
+Expected-pass coverage currently includes:
+
+- `RTCPeerConnection` construction, descriptions, signaling state, ICE state,
+  ICE candidates, and data-channel negotiation
+- `RTCDataChannel` construction, id assignment, negotiated channels, ready
+  state, open/message/close/error behavior, send variants, binary type, and
+  buffered amount behavior
+- WebRTC-shaped constructors and events such as `RTCSessionDescription`,
+  `RTCIceCandidate`, `RTCDataChannelEvent`, and ICE events
+
+Out-of-scope WPT areas are grouped in the manifest as `notApplicable`,
+`needsShim`, or `expectedFail`. Media and RTP APIs are outside this package's
+public scope.
+
+## Running WPT
+
+```sh
+npm run wpt:ensure
+npm run wpt:selection:check
+npm run wpt:test
+npm run wpt:check:strict
+npm run wpt:report -- --output wpt-report.md
+```
+
+`wpt:test` writes `wpt-results.json`. `wpt:check:strict` requires every selected
+subtest to pass and fails if a worker retry was needed.
+
+## CI Evidence
+
+Each CI matrix job writes:
+
+- `ci-evidence.json`
+- `wpt-results.json`
+- `wpt-report.md`
+- `wpt-manifest.json`
+- `wpt-manifest.txt`
+
+After downloading CI artifacts into `ci-artifacts/`, validate the full matrix:
+
+```sh
+npm run ci:evidence:check -- --artifacts ci-artifacts
+```
+
+The verifier checks Linux, macOS, and Windows artifacts across Node 20, 22, and
+24. It rejects missing jobs, pin mismatches, WPT failures, and WPT retries.

package/docs/development.md

@@ -0,0 +1,161 @@
+# Development
+
+This project builds a Node-API addon and a W3C-style JavaScript facade. Use the
+lockfile and keep generated artifacts out of commits.
+
+## Setup
+
+```sh
+npm ci
+npm run native:check
+npm run build
+```
+
+`native:check` verifies the pinned `libdatachannel` commit, Node-API usage, and
+thread-safe callback dispatch. The build uses `cmake-js` and links
+`LibDataChannel::LibDataChannelStatic`.
+
+If a local `libdatachannel/` checkout exists, CMake verifies it against the
+pinned commit. Otherwise it fetches the pinned upstream commit with
+`FetchContent`.
+
+## Local Checks
+
+```sh
+npm run check
+npm test
+npm run api:check
+npm run types:check
+npm run pack:check
+npm run wpt:selection:check
+npm run wpt:smoke
+npm run wpt:smoke:check
+```
+
+Run the full selected WPT suite before claiming conformance changes:
+
+```sh
+npm run wpt:ensure
+npm run wpt:test
+npm run wpt:check:strict
+npm run wpt:report -- --output wpt-report.md
+```
+
+The default `CI` workflow keeps pull requests fast by running the native
+OS/Node matrix with unit tests plus a small WPT smoke subset on Ubuntu Node 24.
+The full selected WPT matrix is in the `Conformance` workflow, which runs on
+manual dispatch, weekly schedule, and version tags.
+
+Only source-relevant changes run the native matrix, package-artifact source
+build, and WPT smoke job. Source-relevant paths include `lib/`, `src/`,
+`scripts/`, `test/`, `examples/`, `build-containers/`, `CMakeLists.txt`,
+package files, TypeScript/API config, Biome config, and `wpt-manifest.json`.
+Documentation, agent notes, and workflow-only maintenance changes run the
+lightweight quality gate only.
+
+By default, WPT is fetched into the ignored `wpt/` cache. Set `WPT_DIR` to use a
+different pinned checkout.
+
+For focused debugging:
+
+```sh
+npm run wpt:test -- webrtc/RTCDataChannel-close.html
+npm run wpt:test -- "webrtc/RTCDataChannel-send.html#Sending in ondatachannel should work"
+```
+
+Bare file targets use manifest include/exclude rules. A `file#subtest` selector
+runs one exact WPT subtest.
+
+## Formatting and Linting
+
+Biome is used for JavaScript, TypeScript, and JSON formatting/linting:
+
+```sh
+npm run check
+npm run lint
+npm run format:check
+npm run format
+```
+
+`npm run check` is the Biome gate used by GitHub Actions. The full Quality job
+also runs `npm run types:check` and `npm run pack:check`. WPT selection checks
+run after the native addon is built because the WPT harness loads the public
+WebRTC facade. `pack:check` validates the npm source artifact contents. Use
+`npm run format` before sending a pull request.
+
+## Package Artifact
+
+CI has a Linux `Package artifact` job that packs the npm source package,
+extracts it in a clean directory, installs dependencies, builds the native
+addon, and requires the package. This guards against missing files in
+`package.json#files` before npm publication.
+
+## Prebuilt Releases
+
+The release workflow keeps `cmake-js` as the native build backend. Platform jobs
+build `build/Release/webrtc_node.node`, then `npm run prebuild:package` creates
+`prebuild-artifacts/webrtc-node-v<version>-napi-v8-<target>.tar.gz`. The npm
+publish job downloads those artifacts, verifies the expected prebuild set,
+uploads them to the GitHub Release, runs `pack:check`, and publishes the source
+package. Prebuilds are not bundled inside the npm tarball.
+
+Publishing uses npm trusted publishing with GitHub Actions OIDC, not an
+`NPM_TOKEN` secret. Configure the npm package trusted publisher for repository
+`mertushka/webrtc-node`, workflow filename `release.yml`, and environment `npm`
+if the GitHub release environment is kept.
+
+Manual `workflow_dispatch` releases expect a GitHub Release named
+`v<package.json version>` to already exist, because prebuilt archives are
+uploaded as release assets before `npm publish` runs.
+
+Supported release targets are:
+
+- `linux-x64-glibc`
+- `linux-x64-musl`
+- `darwin-x64`
+- `darwin-arm64`
+- `win32-x64`
+
+Use `WEBRTC_NODE_NATIVE_PATH=/absolute/path/to/webrtc_node.node` to test a
+specific local native binary. Use `npm install --build-from-source` to force the
+install script to compile with `cmake-js`.
+
+## Docker Linux Slice
+
+GitHub Actions is the authoritative conformance gate. The Docker helpers are
+optional local reproducers for Linux CI behavior when a contributor has Docker
+available.
+
+On Linux or macOS:
+
+```sh
+bash scripts/run-docker-linux-ci.sh --node-image node:20-bookworm --artifacts-dir ci-artifacts/docker-linux-node20
+bash scripts/run-docker-linux-ci.sh --node-image node:22-bookworm --artifacts-dir ci-artifacts/docker-linux-node22
+bash scripts/run-docker-linux-ci.sh --node-image node:24-bookworm --artifacts-dir ci-artifacts/docker-linux-node24
+```
+
+On Windows with Docker Desktop:
+
+```powershell
+./scripts/run-docker-linux-ci.ps1 -NodeImage node:20-bookworm -ArtifactsDir ci-artifacts/docker-linux-node20
+./scripts/run-docker-linux-ci.ps1 -NodeImage node:22-bookworm -ArtifactsDir ci-artifacts/docker-linux-node22
+./scripts/run-docker-linux-ci.ps1 -NodeImage node:24-bookworm -ArtifactsDir ci-artifacts/docker-linux-node24
+```
+
+Target a single WPT case:
+
+```sh
+bash scripts/run-docker-linux-ci.sh \
+  --node-image node:24-bookworm \
+  --artifacts-dir ci-artifacts/docker-linux-node24-close \
+  --wpt-selector "webrtc/RTCDataChannel-close.html#Repeated open/send/echo/close datachannel works"
+```
+
+```powershell
+./scripts/run-docker-linux-ci.ps1 -NodeImage node:24-bookworm `
+  -ArtifactsDir ci-artifacts/docker-linux-node24-close `
+  -WptSelector "webrtc/RTCDataChannel-close.html#Repeated open/send/echo/close datachannel works"
+```
+
+The helper writes logs and WPT artifacts under the selected `ci-artifacts/`
+directory.

package/docs/divergences.md

@@ -0,0 +1,230 @@
+# Intentional W3C Divergences
+
+This package targets W3C-style `RTCPeerConnection` and `RTCDataChannel`
+behavior for Node.js. It intentionally does not expose browser media APIs. The
+current implementation diverges from W3C WebRTC in the following places.
+
+## Local SDP application
+
+`libdatachannel` generates local SDP inside `setLocalDescription()`. It does not
+provide a public API that applies arbitrary caller-supplied local SDP. The JS
+facade accepts `setLocalDescription(description)` for browser compatibility, but
+currently uses the description type and lets libdatachannel generate the actual
+local SDP.
+
+Impact: WPT cases that mutate local SDP between `createOffer()` and
+`setLocalDescription()` are expected to fail until the binding grows a validated
+SDP-munging strategy or native support.
+
+## Media APIs
+
+This package intentionally excludes media tracks, transceivers, RTP
+senders/receivers, stats, DTMF, capture devices, and `ontrack`. libdatachannel
+has RTP/SRTP track primitives, but they do not map directly to the exposed
+`RTCPeerConnection` plus `RTCDataChannel` scope.
+
+Impact: media-oriented WPT files are marked not applicable in
+`wpt-manifest.json`.
+
+The selected `historical.html` subset excludes only the legacy
+`RTCRtpTransceiver` member check because `RTCRtpTransceiver` is not exposed.
+
+## RTCConfiguration
+
+The JS facade validates and stores W3C-shaped `RTCConfiguration` dictionaries,
+including `iceServers`, `iceTransportPolicy`, `bundlePolicy`, `rtcpMuxPolicy`,
+`iceCandidatePoolSize`, and `certificates`. `getConfiguration()` returns a
+clone of that JS-visible configuration and `setConfiguration()` applies W3C
+validation and immutable-field checks.
+
+libdatachannel consumes ICE servers and transport policy at peer-connection
+construction time. The current binding does not reconfigure the native ICE
+transport after construction, so `setConfiguration()` is a W3C-compatible facade
+operation for validation and JS-visible state rather than a native ICE restart
+or transport reconfiguration mechanism.
+
+Impact: the selected WPT suite covers constructor, `getConfiguration()`, and
+`setConfiguration()` validation for ICE servers, ICE candidate pool size,
+certificates, bundle policy, RTCP mux policy, and ICE transport policy. Media
+candidate-gathering and media SDP RTCP-mux validation cases remain outside the
+expected-pass set.
+
+## Certificates
+
+`RTCPeerConnection.generateCertificate()` and `RTCCertificate` are implemented
+as native-backed WebRTC objects with generated PEM/key material, expiration,
+and fingerprint accessors. `RTCPeerConnection` validates expired certificates,
+rejects `setConfiguration()` calls that change the certificate set, and passes
+the first configured certificate into libdatachannel's `rtc::Configuration` so
+the generated DTLS fingerprint appears in local SDP.
+
+libdatachannel accepts one certificate/key pair for a peer connection. The W3C
+configuration dictionary allows a sequence of certificates, and WPT has a case
+that expects all configured certificate fingerprints to appear in SDP. The
+current binding preserves the JS-visible certificate set for W3C
+`getConfiguration()`/`setConfiguration()` behavior but uses only the first
+certificate for native DTLS identity.
+
+Impact: the selected WPT suite covers certificate generation, unsupported
+algorithm rejection, expiration validation, fingerprint object shape, and
+certificate immutability in `setConfiguration()`, plus single-certificate SDP
+fingerprint generation. The multi-certificate SDP fingerprint case remains
+outside expected-pass until the binding has a defensible multi-certificate
+strategy.
+
+## Transport object surface
+
+`RTCPeerConnection.sctp` is implemented as a data-channel-backed
+`RTCSctpTransport` facade, with a minimal `RTCDtlsTransport` object available at
+`sctp.transport`. The facade is created only when SDP contains an
+`m=application` data section. It tracks `connecting`, `connected`, and `closed`
+from peer/data-channel state, exposes same-process remote certificates through
+`getRemoteCertificates()` after connection, and exposes negotiated
+`maxMessageSize` and post-connect `maxChannels` where the current native
+binding can support them.
+As in browsers, these transport facade objects are exposed from
+`RTCPeerConnection.sctp` and related attributes rather than being publicly
+constructible. The data-channel DTLS facade reports `"new"` until both local and
+remote descriptions are present, then `"connecting"` until the data transport is
+connected.
+
+Impact: the selected WPT suite covers SCTP transport creation, state events,
+`maxChannels`, and `maxMessageSize`. A minimal `RTCIceTransport` facade is
+available at `sctp.transport.iceTransport`; it exposes ICE role, component,
+state, gathering state, candidate accessors, selected candidate pair, and ICE
+parameters from the data-channel peer-connection state.
+`getSelectedCandidatePair()` returns a WebIDL-shaped `RTCIceCandidatePair`
+object, not a plain object, when libdatachannel exposes a connected local/remote
+candidate pair.
+
+Impact: the selected WPT suite covers connected data-channel selected candidate
+pairs, unconnected SCTP ICE transport behavior, data-channel disconnected
+transport behavior after peer close, ICE restart transport-object identity for
+data channels, and data-channel SCTP ICE transport gathering-state and
+connected-state consistency. The pinned `RTCIceTransport.html?rest`
+candidate-pair test has a runner shim for its `"completed"`/`"complete"`
+gathering-state typo; the runtime keeps the WebRTC enum value `"complete"`.
+Disconnected timing and media transport graph cases remain outside the current
+expected-pass set.
+
+## Data channel closing
+
+libdatachannel does not expose a native `closing` ready state. The JS facade
+synthesizes `readyState === "closing"` and a `closing` event when
+`RTCDataChannel.close()` is called. If application data was queued in the same
+task, the facade marks the channel as closing immediately but briefly delays the
+native SCTP close so the just-queued message can be delivered before reset.
+
+Impact: local close behavior is browser-shaped in the JS layer. The current WPT
+runner passes `RTCDataChannel-close.html`, including remote `closing`, repeated
+open/send/close, and peer-close `RTCErrorEvent` cases.
+
+For same-process peers that have exchanged SDP through this facade, the JS layer
+also pairs peer connections and data channels by SDP/stream id. That pairing is
+used only to synthesize remote data-channel close/error events when native close
+callbacks are late or uneven under stress; send-drain closes still wait for
+native delivery so queued messages are not truncated.
+
+## Incoming data channel event timing
+
+libdatachannel can report an incoming data channel and its first channel events
+from native callbacks before browser-style JS event handlers have been attached.
+The JS facade queues incoming `datachannel` announcements and holds early
+`open`/`message`/`close` events for that channel until after the
+`datachannel` event has been dispatched.
+
+Impact: this is the EventTarget timing layer required for WPT-compatible
+ordering. The current runner passes full `RTCPeerConnection-ondatachannel.html`,
+including the cases that close or send from inside the `datachannel` handler.
+
+## Worker-transferable data channels
+
+Browser WebRTC exposes worker transfer behavior for `RTCDataChannel` through the
+structured clone/transfer machinery. The current Node facade does not implement
+transferable `RTCDataChannel` objects or a Worker-backed channel owner model.
+
+Impact: worker and transferable data-channel WPT files remain outside
+expected-pass, including `RTCDataChannel-worker*.js`,
+`RTCDataChannel-worker-GC.html`, and `transfer-datachannel.html`.
+
+## bufferedAmount
+
+libdatachannel reports bytes buffered in its SCTP transport queue. W3C
+`bufferedAmount` increases synchronously for every `send()` call and decreases
+later. The JS facade maintains its own W3C-style counter and does not surface
+native buffered-amount-low callbacks directly because they are based on
+libdatachannel's transport queue and can race the JS-visible counter.
+
+Impact: this is intentionally shimmed in JS. The current WPT runner passes
+`RTCDataChannel-bufferedAmount.html`.
+
+## End-of-candidates
+
+libdatachannel candidate callbacks do not directly match browser
+`icecandidate` event end-of-candidates semantics. The JS facade synthesizes a
+final `icecandidate` event with `candidate === null` when gathering reaches
+`complete`.
+
+Impact: the selected WPT suite now covers candidate target validation, SDP
+candidate insertion, and end-of-candidates mutation in
+`RTCPeerConnection-addIceCandidate.html`. Operations-chain timing and
+media-transceiver connection setup remain outside the selected scope.
+
+## ICE candidate errors
+
+`RTCPeerConnectionIceErrorEvent` and the `onicecandidateerror` handler
+attribute are exposed for WebRTC API shape compatibility. The current
+libdatachannel binding does not surface STUN/TURN candidate-gathering failures
+as browser `icecandidateerror` events.
+
+Impact: constructor and handler-attribute behavior are covered locally, while
+`RTCPeerConnection-onicecandidateerror.https.html` remains outside the selected
+expected-pass WPT set until native ICE-server error events are available.
+
+## ICE restart
+
+The default libdatachannel/libjuice path only accepts custom local ICE
+credentials before candidate gathering starts. After gathering has started, the
+facade treats `restartIce()` as a W3C-shaped renegotiation request and preserves
+existing data channels through the offer/answer exchange, but it does not claim
+fresh native ICE ufrag/password credentials.
+
+Impact: the selected suite covers data-channel liveness with
+`RTCDataChannel-iceRestart.html`, closed-state no-op behavior from
+`RTCPeerConnection-restartIce.https.html`, and data-channel explicit rollback
+gathering timing from
+`RTCPeerConnection-explicit-rollback-iceGatheringState.html`. When native
+gathering is already complete, the JS facade replays browser-shaped
+`gathering`/`complete` events for the restart offer so WPT-visible task timing
+matches the WebRTC API, but this does not imply fresh native ICE credentials.
+WPT cases that assert fresh ICE credentials, media behavior, or detailed
+restart signaling remain outside the current expected-pass set.
+
+## SCTP stream limit
+
+The audited libdatachannel commit negotiates up to 1024 SCTP streams internally.
+The JS facade exposes that connected-state `RTCSctpTransport.maxChannels` limit
+even if the native limit read arrives slightly after the SCTP connected event.
+Browser WebRTC/WPT includes cases around stream ids up to 65534.
+For WebIDL construction compatibility, negotiated channels with ids above the
+native limit can be constructed and keep their requested `id` while remaining in
+the `"connecting"` state. They are not backed by a native SCTP stream and are
+not expected to become usable until libdatachannel can negotiate that stream
+range.
+
+Impact: the selected WPT suite covers the construction-time negotiated id
+`65534` case. Functional high-id transport cases remain outside expected-pass
+unless libdatachannel is configured or changed to support the larger range.
+Full `RTCDataChannel-id.html` coverage now passes; the JS facade assigns
+browser-visible IDs when a remote answer determines the DTLS role before
+libdatachannel exposes a native stream id.
+
+## Event and promise timing
+
+Native libdatachannel callbacks run on internal worker threads. The addon uses a
+Node-API thread-safe function and the JS facade dispatches DOM-style events on
+the Node thread. Some exact browser task-source ordering is still being aligned
+with WPT.
+
+Impact: high-level negotiation and data-channel messaging work; precise timing
+tests remain gated by the WPT harness.

package/examples/datachannel.js

@@ -0,0 +1,57 @@
+"use strict";
+
+const { RTCPeerConnection } = require("..");
+
+async function main() {
+  const pc1 = new RTCPeerConnection();
+  const pc2 = new RTCPeerConnection();
+  let timeout;
+
+  const cleanup = () => {
+    if (timeout) clearTimeout(timeout);
+    pc1.close();
+    pc2.close();
+  };
+
+  pc1.addEventListener("icecandidate", ({ candidate }) => {
+    if (candidate) pc2.addIceCandidate(candidate).catch(console.error);
+  });
+  pc2.addEventListener("icecandidate", ({ candidate }) => {
+    if (candidate) pc1.addIceCandidate(candidate).catch(console.error);
+  });
+
+  pc2.addEventListener("datachannel", ({ channel }) => {
+    channel.addEventListener("message", ({ data }) => {
+      console.log(`pc2 received: ${data}`);
+      channel.send(`echo: ${data}`);
+    });
+  });
+
+  const channel = pc1.createDataChannel("chat");
+  channel.addEventListener("open", () => {
+    channel.send("hello from Node");
+  });
+  channel.addEventListener("message", ({ data }) => {
+    console.log(`pc1 received: ${data}`);
+    cleanup();
+  });
+
+  const offer = await pc1.createOffer();
+  await pc1.setLocalDescription(offer);
+  await pc2.setRemoteDescription(pc1.localDescription);
+
+  const answer = await pc2.createAnswer();
+  await pc2.setLocalDescription(answer);
+  await pc1.setRemoteDescription(pc2.localDescription);
+
+  timeout = setTimeout(() => {
+    cleanup();
+    process.exitCode = 1;
+    console.error("Timed out waiting for data-channel echo");
+  }, 10000).unref();
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exitCode = 1;
+});