Skip to content

feat(net)!: @moq/net requests are awaitable, and its last odd names match Rust - #8953

Merged
kixelated merged 8 commits into
mainfrom
quest/m2/js-net-api
Nov 17, 2026
Merged

kixelated merged 8 commits into
mainfrom
quest/m2/js-net-api

Conversation

@kixelated

@kixelated kixelated commented Nov 16, 2026 •

Copy link
Copy Markdown
Collaborator

Finishes quest/m2/js-net-api.md (deleted here).

Problem

Three @moq/net shapes disagreed with Rust and with the package's own rules before the 0.22 cut freezes them:

  • A one-shot origin.request(path) had no await. The hello world (js/net/examples/subscribe.ts) looped on active.changed() and hung forever when the broadcast did not exist, because a refusal settles closed and leaves active undefined.
  • The reconnect backoff was Connection.Props.delay, while Rust, moq-tokio, and moq-ffi say backoff, and delay already means two other things in this package.
  • Connection.Session.closed was a mutable Promise and Auth.Credential.closed a PromiseLike, against js/AGENTS.md's rule that terminal state is a GetPromise<Error | null>.

Approach

  • Origin.Requesting.broadcast() returns a promise that resolves once active holds a broadcast, or rejects with the error closed carries if the request ends first (such as Unroutable). When closed settles null (the handle or its origin closed cleanly), it rejects with a StreamCode.Cancel error, so an await never hangs. The first call fixes the answer, and later calls return the same promise. Requesting is not a thenable: an await or an async return of the handle never takes the broadcast out from under the request that owns it (maintainer decision, below). active, closed, and close() are unchanged. Following stays a plain handle, since it never settles.
  • Connection.Props.delay is backoff. The internal ReloadDelay type is Backoff (matching its Connection.Backoff export), DEFAULT_DELAY is DEFAULT_BACKOFF, and the share refusal reads "backoff cannot be shared". WebSocketProps.delay and Track.Subscription.delay are untouched.
  • Connection.Session.closed is readonly closed: GetPromise<Error | null>. Both session classes settle one Once from the transport's close, after auth has let go of the session, as the old getter did. Auth.Credential.closed, plus the @internal Auth.Issued.closed and Auth.Request.closed, are GetPromise<Error | null> too. IssuedGrant.ended now reads its closed instead of keeping a second flag.
  • The request() wait loops now await request.broadcast(): the example, js/net/bench/refresh.ts, two js/net tests, and the audio-quality, stream-limits, datagram-tracks, max-age, and stream-credit clients. doc/lib/js/net.md documents it.
  • Closing an origin ends every open request, pending or resolved, with its abort or null. Before, Producer.close() cleared the request table without settling a pending request's closed, which the doc promised, so an await on it would have hung (found by review).
  • test/datagram-tracks/client.ts expected an untimed datagram to have no timestamp. Since moq-dev/moq#8638, it carries Timestamp.unscaled(sequence). The nightly-only lane failed on main, and this PR fixes the assertion.

Impact

Public API, breaking for @moq/net. Wire: none. Bindings: none (Rust and moq-ffi already say backoff and await a request).

Migration:

  • new Connection({ delay: { ... } }) → new Connection({ backoff: { ... } }). The fields (initial, multiplier, max, healthy, timeout) are unchanged. A share: true connection given backoff throws "backoff cannot be shared; pass share: false".
  • Replace a wait loop on a request with await request.broadcast(). The await rejects when the request ends without a broadcast, where the loop hung:
    const request = origin.request(path);
    const broadcast = await request.broadcast(); // throws Unroutable if nothing serves the path
    // ...
    request.close(); // the request still owns the broadcast
  • session.closed and credential.closed are now GetPromise<Error | null>. await and .then work as before. Code that typed them as Promise<Error | null> (for example, a mock Session or Credential) builds a Once<Error | null> from @moq/signals instead. session.closed is readonly.
  • Requesting is not awaitable: pass the handle through async functions and promise resolution freely, and call broadcast() when you want the broadcast.

Decisions

Maintainer decision (2026-11-16, /quest-run, comment): merge once Requesting stops being a thenable. It gains an explicit broadcast() method with the same resolve and reject behavior, which keeps the request owning the broadcast and keeps an async function or promise resolution from silently awaiting the handle. The example, docs, tests, and API report follow it. The delay to backoff rename and closed as GetPromise<Error | null> are accepted as they were. This supersedes the earlier thenable shape (and the earlier decision 2's "first then read").

The rest were taken while the maintainer was away, and the maintainer accepted them with that comment:

  1. Clean close rejects with StreamCode.Cancel (message "request closed"). The quest recommended one named cancellation error. StreamCode.Cancel already exists, and Rust's Error::Closed maps to it, so no new export is needed. Alternative: a new Error.Cancelled class.
  2. The answer is fixed lazily, at the first broadcast() call, not tracked from construction. Tracking from construction would subscribe on every request, including the ones follow() makes internally, for an answer few callers read. A lazy answer also avoids an unhandled rejection nobody awaits. The cost: a request that resolved and then ended before anyone awaited it rejects with the ending. Alternative: track from construction and resolve with the first broadcast ever held.
  3. The request still owns the broadcast it resolves to. The resolved value is the same handle as active, closed with the request. Rust drops the Requesting on await, but in JS the request drives failover between routes of the same instance, so releasing it on resolve would lose that. The example, the broadcast() doc, and the net docs say to close the request. Alternative: release the request on resolve and return a clone, losing failover.
  4. Auth.Issued.closed and Auth.Request.closed took the same type. The quest recommended this but left it open. Both are @internal and were the only other PromiseLike terminal fields.
  5. Some loops stay. Loops on follow() stay, since a follower never settles. test/smoke/clients/js-native/subscribe.ts and test/interop/compat/client.ts stay because they run against the published @moq/net, which has no broadcast() yet, and both follow. The quest named the smoke client, but that predates checking what it runs against. claims.ts and replace.ts read Following handles, or both shapes.
  6. No js/net/MIGRATE.md edit. The quest's Plan asked for one, but CONTRIBUTING and RELEASE have the release cut write MIGRATE.md from each PR's Impact section.

Overlap with open PRs

  • moq-dev/moq#8929 drops a Related link from this quest file, which this PR deletes; resolve by keeping the deletion. No API overlap.
  • moq-dev/moq#8902 edits pool.ts near the renamed option, and reads credential closed through then, which GetPromise keeps.
  • moq-dev/moq#8942 unlinks a neighbor on the same quest/m2/README.md line.

Validation

  • Real relay: a bun script against https://cdn.moq.dev/anon (WebSocket, moq-lite-06) awaited origin.request() for a random missing path. It rejected after 51 ms with Stream: unroutable (code === StreamCode.Unroutable). The old example loop hangs in that case. Against https://cdn.moq.dev/demo, it awaited a request for the first announced broadcast (bbb.hang), resolved, and read its 829-byte catalog.
  • Real Rust relay with JS clients: just test max-age, just test stream-limits, and just test datagram-tracks pass. All three use await request.broadcast() now, rerun after the maintainer's change. Before the assertion fix, datagram-tracks got past the await and failed on the stale timestamp check, which is a failure on main too.
  • New tests in js/net/src/origin-request.test.ts: awaiting broadcast() for a missing path rejects Unroutable once discovery syncs; it resolves at once when routed and later when a route arrives; closing a pending request, or requesting on a closed origin, rejects Cancel; closing an origin rejects a pending await with its abort (or Cancel when clean) and ends a resolved request, which timed out before the fix; the first call fixes the answer; a Requesting has no then and survives an async return. To check that the tests discriminate, I dropped the memo (??= → =), and "the first call fixes a request's answer" failed (before the broadcast() change). The real-relay script above ran on the thenable shape; the Rust-relay clients were rerun on broadcast().
  • just check passes: biome, every JS build including the API report and the doc site, and the JS tests (rerun after merging main and the broadcast() change). The standalone test/{stream-limits,max-age,datagram-tracks} clients also type-check with tsc.

Caused by

  • moq-dev/moq#8638: gave every datagram a timestamp (unscaled at its sequence when untimed) but left test/datagram-tracks/client.ts asserting undefined (found by check)

  • No single PR: Producer.close() never settled a pending request's closed, though its doc has promised "origin shutdown" since the request handle split from follow() in moq-dev/moq#7476, and the wording predates that (found by reviewer)

Follow-ups

None.

Models

Size: M
Implementer: Claude, claude-opus-5-5, high effort (arm B)
Implementer: Claude Code, claude-sonnet-5-5, unknown effort (iterate, M)

(Written by Claude Opus 5.5 with high effort)

🤖 Generated with Claude Code

Review

Rewritten by quest review after each round.

  • Head: 5280af6

  • Base: origin/main at 8fbbb2a

  • Risk: high, The branch changes public @moq/net APIs that downstream applications depend on, so consumers may require source updates even though the repository changes are reversible.

  • Classified: medium by default

  • Reviewer: Codex, gpt-6.1-sol, high effort

  • Session: 01a1e962-1ddb-7e00-b258-e578c88dd101, round 2

  • Score: 9/10, The incremental merge introduces no actionable findings beyond the previously reviewed change; builds and tests were not run, as requested.

  • Raised the risk to high: The branch changes public @moq/net APIs that downstream applications depend on, so consumers may require source updates even though the repository changes are reversible.

  • Rounds: 4; first round 1 (medium 1); findings 1 (medium 1): fixed 1, refuted 0, open 0

  • Findings: none

kixelated and others added 4 commits November 16, 2026 07:15
Quest-Claim: 2e6aee30d4faba44
…and closed fields are GetPromise

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…inish the quest

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kixelated kixelated changed the title @moq/net requests are awaitable, and its last odd names match Rust feat(net)!: @moq/net requests are awaitable, and its last odd names match Rust Nov 16, 2026
…luded

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kixelated
kixelated marked this pull request as ready for review November 16, 2026 16:19
@coderabbitai

coderabbitai Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 5 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used all 4 included reviews currently available.

Learn how review limits work.

Review configuration:

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 4d8ac8e2-8d09-4de1-905b-68fbdaa37bfe
Commits

Reviewing files that changed from the base of the PR and between ca8b08c and 5280af6.

Files selected for processing: 29

  • doc/lib/js/net.md
  • js/net/api/index.api.md
  • js/net/bench/refresh.ts
  • js/net/examples/subscribe.ts
  • js/net/src/auth.ts
  • js/net/src/auth_session.ts
  • js/net/src/connection/answered.test.ts
  • js/net/src/connection/migrate.test.ts
  • js/net/src/connection/pool.test.ts
  • js/net/src/connection/pool.ts
  • js/net/src/connection/reload.test.ts
  • js/net/src/connection/reload.ts
  • js/net/src/connection/session.ts
  • js/net/src/ietf/connection.ts
  • js/net/src/ietf/publisher.test.ts
  • js/net/src/integration.test.ts
  • js/net/src/lite/compression.test.ts
  • js/net/src/lite/connection.ts
  • js/net/src/lite/refresh.test.ts
  • js/net/src/origin-request.test.ts
  • js/net/src/origin.ts
  • quest/m2/README.md
  • quest/m2/js-net-api.md
  • test/audio-quality/clients/js/src/recorder.ts
  • test/datagram-tracks/client.ts
  • test/interop/clients/js/src/close.ts
  • test/max-age/client.ts
  • test/stream-credit/src/main.ts
  • test/stream-limits/client.ts
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

pullfrog[bot]
pullfrog Bot previously approved these changes Nov 16, 2026

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ No new issues found.

Reviewed changes

I reviewed all 29 files: the @moq/net API reshaping, the origin shutdown fix, and the call sites and tests updated to match.

  • Origin.Requesting is awaitable. A memoized then getter resolves once active holds a broadcast. It rejects with the error closed carries, or with StreamCode.Cancel when the request closes cleanly, so an await never hangs.
  • Producer.close() ends every open request. Handles in both joined and detached slots settle with abort ?? null. A peek() guard protects Once.set, and since both tables are cleared first, drop() can no longer reach these slots and settle them twice.
  • delay → backoff. The rename covers Connection.Props, ReloadDelay/Backoff, DEFAULT_BACKOFF, the share refusal, and every test. The other two meanings of delay are untouched.
  • closed fields are GetPromise<Error | null>. Both session classes settle a Once from a quic.closed reaction registered after auth's leave, so the old ordering holds. IssuedGrant.ended now reads that Once.
  • Wait loops replaced with await. I checked the loops that remain in test/interop/clients/js-native/* and js/crypto: every one is on follow(). @moq/watch never passes a Requesting through promise resolution, so it won't unwrap the handle by accident.
  • datagram-tracks assertion. The test now matches Timestamp.unscaled(sequence), which makes scale undefined and value equal to the sequence.

Pullfrog  | View workflow run | Using claude-opus-5-5 | 𝕏

@kixelated kixelated left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Automated review by review (OpenAI)

Reviewed fc9794630f6fe45b86d73979b9c36c49f26023f0. Awaiting a request is an improvement, but P2: reading request.then alone can produce an unhandled rejection (js/net/src/origin.ts:2113). A common thenable check like typeof request.then === "function" creates the memoized promise without attaching a handler; if the request is closed or later refused, that check alone can kill a Node process in strict mode. Either start the memo when the returned function is invoked, or attach a rejection observer to the memo without changing the result that real awaiters receive. I reproduced the unhandled-rejection pattern in a minimal Node fixture, not the full package.

Also put teardown in finally in js/net/examples/subscribe.ts: a missing broadcast now rejects before the connection and origin close, so the example can still leave a live transport after logging the error. Show a retained request in the class JSDoc too, rather than await origin.request(...), since only the request can release its discovery watch.

@kixelated

Copy link
Copy Markdown
Collaborator Author

Maintainer decision (2026-11-16, /quest-run)

  • Merge, once the change below is in.
  • No thenable: Requesting does not implement then. Instead, add an explicit awaitable method, such as await request.broadcast(). It resolves to the broadcast or rejects (Unroutable, or Cancel on close). It keeps the request owning the broadcast and avoids an async function or promise resolution silently awaiting the handle. Update the example, docs and decisions to match.
  • The rest is accepted: delay becomes backoff, and closed becomes GetPromise<Error | null>.

(Written by Opus 5.5)

pullfrog[bot]
pullfrog Bot previously approved these changes Nov 17, 2026

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ No new issues found.

Reviewed changes

Since the last review at fc97946, Requesting stopped being a thenable and gained an explicit broadcast() method, and the call sites now use it. The rest of this delta comes from merging main.

  • Requesting.broadcast() replaces the then getter. It keeps the same memoized answer(active, closed), and PromiseLike and the biome-ignore are gone. This also removes the earlier risk of an unhandled rejection when code only checked for .then: the memo now starts only when a caller invokes broadcast(), and that caller gets the promise back.
  • Call sites moved to await request.broadcast(). This covers the example, bench/refresh.ts, compression.test.ts, refresh.test.ts, and the audio-quality, datagram-tracks, max-age, stream-credit, and stream-limits clients. I searched for any await request left on a Requesting handle. The only two hits are in request-deadline.test.ts and lite/publisher.test.ts, and both await unrelated promises.
  • Tests track the new shape. A new test checks that the handle has no then and that returning it from an async function gives back the same handle. The first-call memo test and the shutdown tests now call broadcast().
  • The doc, the JSDoc and the API report match broadcast(). They say the handle is not awaitable and that the request still owns the broadcast.

Pullfrog  | View workflow run | Using claude-opus-5-5 | 𝕏

@kixelated kixelated left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Automated review by review (OpenAI)

Reviewed 537de6e5fbc130d7e092c427fa3af1e8281e0fb4. The explicit request.broadcast() method fixes the previous thenable bug: inspecting or returning the handle no longer allocates a promise or assimilates the broadcast. The revised tests cover success, refusal, clean cancellation, and repeated calls, and the JSDoc keeps the owning handle. No new implementation blocker. The earlier example-cleanup point remains: if broadcast() rejects, js/net/examples/subscribe.ts still skips teardown; close the request, connection, and origin in finally. Static inspection only; I didn’t run the JS tests.

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ No new issues found.

Reviewed changes

Since the last review at 537de6e, the only new commit merges main. That merge changes nothing in the PR's code.

  • Resolved a conflict in the quest/m2/README.md merge. The "JS and browser" line now links only signals. The js-net-api.md link is gone, which matches this PR deleting that quest file.

Pullfrog  | View workflow run | Using claude-opus-5-5 | 𝕏

@kixelated
kixelated added this pull request to the merge queue Nov 17, 2026
Merged via the queue into main with commit 50ae64b Nov 17, 2026
6 checks passed
@kixelated
kixelated deleted the quest/m2/js-net-api branch November 17, 2026 13:01
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