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
596 changes: 594 additions & 2 deletions js/net/src/connection/connect.test.ts

Large diffs are not rendered by default.

182 changes: 147 additions & 35 deletions js/net/src/connection/connect.ts
Original file line number Diff line number Diff line change
@@ -1,13 +1,15 @@
import { Milli, Nano, sleep } from "@moq/clock";
import { Elapsed, Milli, Nano, sleep, timeout } from "@moq/clock";
import Session, { type Version as QmuxVersion } from "@moq/qmux";
import { error, fromClose, ProtocolViolation, sessionCause } from "../error.ts";
import { race } from "@moq/signals";
import { ConnectTimeout, error, fromClose, ProtocolViolation, sessionCause } from "../error.ts";
import * as Ietf from "../ietf/index.ts";
import * as Message from "../ietf/message.ts";
import * as Lite from "../lite/index.ts";
import type { Consumer as OriginConsumer, Producer as OriginProducer } from "../origin.ts";
import { Stream } from "../stream.ts";
import * as Hex from "../util/hex.ts";
import { redact } from "../util/log.ts";
import { after } from "../util/timer.ts";
import { isWebTransportSupported } from "./browser.ts";
import type { Established } from "./established.ts";
import * as Extensions from "./extensions.ts";
Expand All @@ -17,6 +19,21 @@ import { exchangeSetup } from "./handshake.ts";
// Default head start for WebTransport before attempting the WebSocket fallback.
const DEFAULT_WEBSOCKET_DELAY_MS = Milli(500);

// Default bound on one connect, the dial and the MoQ handshake; matches the Rust client.
const DEFAULT_TIMEOUT = Milli(30_000);

// How long the first WebTransport dial may stay unopened before a second one dials alongside
// it. The same moment as the WebSocket's default head start, so a fresh WebTransport flow
// races the fallback rather than losing to it, which would leave the session on WebSocket for
// good. A healthy open is about two round trips, so this spares round trips up to about
// 250 ms, and it is inside the 2 s ceiling RFC 8305 recommends for staggered attempts.
const WEBTRANSPORT_HEDGE = DEFAULT_WEBSOCKET_DELAY_MS;

// How long a WebSocket dial may stay unopened before it is closed and dialed again. Generous,
// since script cannot tell a silent connect from a slow one; Firefox and socket.io give a
// WebSocket 20 s to open.
const WEBSOCKET_REDIAL = Milli(10_000);

// RESET_STREAM and CONNECTION_CLOSE are separate transport notifications. Give the latter
// time to surface its authoritative code without letting a reset-only peer stall SETUP forever.
const SETUP_CLOSE_GRACE = Nano.fromMilli(Milli(100));
Expand Down Expand Up @@ -171,8 +188,9 @@ export interface ConnectProps {
* Use a pre-existing WebTransport session instead of connecting; skips the
* WebTransport/WebSocket race. The publisher acquires the session's datagram
* writer lock (`datagrams.writable.getWriter()`) for the session's lifetime,
* so the caller must not hold it. Aborting via {@link ConnectProps.signal}
* closes this session, so don't share one you intend to reuse afterwards.
* so the caller must not hold it. Aborting via {@link ConnectProps.signal}, or
* {@link ConnectProps.timeout} passing, closes this session, so don't share one
* you intend to reuse afterwards.
*/
transport?: WebTransport;

Expand Down Expand Up @@ -203,10 +221,17 @@ export interface ConnectProps {
/** The moq-transport extensions to offer, each on unless set to `false`. */
extensions?: Extensions.Extensions;

/**
* Maximum time for one connect, covering the dial and the MoQ handshake, which has no
* deadline of its own (default: 30000ms). `0` waits forever. Past it, the connect rejects
* with {@link ConnectTimeout} and closes whatever it had opened.
*/
timeout?: Milli;

/**
* Aborts the connection attempt with the signal's reason. An already-aborted
* signal rejects before anything opens, and aborting after the connection is
* established has no effect. Use `AbortSignal.timeout(ms)` for a deadline.
* established has no effect. Set {@link ConnectProps.timeout} for a deadline.
*/
signal?: AbortSignal;
}
Expand Down Expand Up @@ -239,26 +264,40 @@ export async function connect({ url, ...props }: ConnectProps): Promise<Establis
if (props.transport && props.versions) throw new TypeError("versions cannot reconfigure a supplied transport");
const signal = props.signal ?? NEVER_ABORTED;
signal.throwIfAborted();
const limit = props.timeout ?? DEFAULT_TIMEOUT;
// Checked before anything is armed, so an invalid value throws here, in the caller's unit.
const deadline = Nano.fromMilli(Milli(limit));

// Resolves on abort so every in-flight transport tears itself down.
// Resolves on abort or timeout so every in-flight transport tears itself down.
const { promise: abort, resolve } = Promise.withResolvers<void>();
const onAbort = () => resolve();
signal.addEventListener("abort", onAbort, { once: true });

let expired: ConnectTimeout | undefined;
const disarm =
limit > 0
? after(deadline, () => {
expired = new ConnectTimeout(limit);
resolve();
})
: () => {};

const pending = connectInner(url, props, abort);
try {
// A `pending` rejection propagates unless the abort beat it to the finish line.
// A `pending` rejection propagates unless the abort or timeout beat it to the finish line.
const connection = await Promise.race([pending, abort.then(() => undefined)]);
if (connection && !signal.aborted) {
if (connection && !signal.aborted && !expired) {
if (props.consume) forwardAnnounced(connection, props.consume);
return connection;
}

// Close a connection that settles after the abort.
// Close a connection that settles after the abort or timeout.
pending.then((conn) => conn.abort()).catch(() => {});
throw signal.reason;
// The caller's abort is teardown and wins over the timeout.
throw signal.aborted ? signal.reason : expired;
} finally {
signal.removeEventListener("abort", onAbort);
disarm();
}
}

Expand Down Expand Up @@ -294,7 +333,7 @@ async function connectInner(raw: URL, props: Omit<ConnectProps, "url">, abort: P
const cancel = Promise.race([raced, abort]);

const webtransport = isWebTransportSupported()
? connectWebTransport(url, cancel, offered.alpns, props.webtransport)
? hedgeWebTransport(url, cancel, offered.alpns, props.webtransport)
: undefined;

// Give QUIC a head start to connect before trying WebSocket, unless WebSocket has won in the past.
Expand All @@ -313,19 +352,19 @@ async function connectInner(raw: URL, props: Omit<ConnectProps, "url">, abort: P
// Race the available transports, using `.any` to ignore if one participant has an error.
// `webtransport`/`websocket` are `Promise | undefined`, so test existence explicitly: a
// promise is always truthy, so bare truthiness here would be a misused-promise.
const session = await Promise.any(
webtransport !== undefined
? websocket !== undefined
? [websocket, webtransport]
: [webtransport]
: [websocket],
).catch((err: unknown) => {
const contenders: Promise<WebTransport | Session | undefined>[] = [];
if (websocket !== undefined) contenders.push(websocket);
if (webtransport !== undefined) contenders.push(webtransport);
const session = await Promise.any(contenders).catch((err: unknown) => {
// Promise.any rejects with an empty message; name each transport's failure instead.
if (!(err instanceof AggregateError)) throw err;
const reasons = err.errors.map((e: unknown) => (e instanceof Error ? e.message : String(e)));
throw new Error(`no transport connected: ${reasons.join("; ")}`, { cause: err });
});
done();
// A contender that opened in the same turn as the winner has already returned its
// transport, so cancelling cannot close it; the rest close themselves on cancel.
closeLosers(contenders, session);

if (!session) throw new Error("no transport available");

Expand Down Expand Up @@ -578,6 +617,58 @@ async function resolveCertificateHashes(options?: WebTransportProps): Promise<We
return hashes.length > 0 ? hashes : undefined;
}

// Close every transport the race opened other than `winner`.
function closeLosers(contenders: Promise<WebTransport | Session | undefined>[], winner: unknown): void {
for (const contender of contenders) {
void contender.then(
(transport) => {
if (transport && transport !== winner) transport.close();
},
() => {},
);
}
}

/**
* Dial WebTransport, and dial it again alongside if the first has not opened within
* {@link WEBTRANSPORT_HEDGE}. The first to open wins and the other is closed.
*
* A load balancer that still places some new flows on a target that just died sends every
* packet of such a flow there, and the browser waits seconds before failing the dial. A
* second dial is a new flow that the balancer places afresh. Neither dial is cut on a timer of
* its own, only by the attempt's {@link ConnectProps.timeout}: the browser's handshake timer
* tells a silent dial from a slow one, which script cannot, and every dial the browser fails
* or abandons counts against its WebTransport throttle. A first dial that fails outright is
* not hedged; that is left to the caller's retry.
*/
async function hedgeWebTransport(
url: URL,
cancel: Promise<void>,
alpns: string[],
options?: WebTransportProps,
): Promise<WebTransport | undefined> {
const first = connectWebTransport(url, cancel, alpns, options);

// The first dial opening, failing, or being cancelled settles this before the delay does.
const hedge = await timeout(Nano.fromMilli(WEBTRANSPORT_HEDGE), first).then(
() => false,
(err: unknown) => err instanceof Elapsed,
);
if (!hedge) return first;
console.debug(redact(url), `WebTransport not open after ${WEBTRANSPORT_HEDGE}ms; dialing a second`);

const dials = [first, connectWebTransport(url, cancel, alpns, options)];
try {
const winner = await Promise.any(dials);
closeLosers(dials, winner);
return winner;
} catch (err) {
// Both failed. Report the first dial's reason, as when there is no hedge, so `no transport
// connected` keeps one reason per transport; a browser words every handshake failure alike.
throw (err as AggregateError).errors[0];
}
}

async function connectWebTransport(
url: URL,
cancel: Promise<void>,
Expand Down Expand Up @@ -648,6 +739,17 @@ async function connectWebTransport(
}

// TODO accept arguments to control the port/path used.
/**
* Dial the WebSocket fallback after `delay`, and if a dial has not opened within
* {@link WEBSOCKET_REDIAL}, close it and dial again, doubling the wait each time.
*
* A browser lets one WebSocket to an address be connecting at a time (RFC 6455 section 4.1),
* so a second dial alongside a silent one only queues behind it, and a TCP connect whose SYNs
* go unanswered waits for the OS's connect timeout. Closing the silent dial lets the next one
* start, on a new connection that a load balancer places afresh. The doubling lets a
* slow but working path through, and {@link ConnectProps.timeout} bounds the whole attempt. A
* dial that fails outright is not redialed.
*/
async function connectWebSocket(
url: URL,
delay: number,
Expand All @@ -659,23 +761,33 @@ async function connectWebSocket(
const active = await Promise.race([cancel, timer.then(() => true)]);
if (!active) return undefined;

// The default (`requireProtocol: false`) also advertises bare `qmux-01`,
// `qmux-00`, and `webtransport` so we still interop with relays that only
// know a wire-format version (today's moq-relay only accepts bare
// `webtransport`).
const quic = new Session(url, {
protocols: alpns,
versions: Object.fromEntries(alpns.map((alpn) => [alpn, QMUX[alpn] ?? null])),
});
for (let wait = WEBSOCKET_REDIAL; ; wait = Milli(wait * 2)) {
// The default (`requireProtocol: false`) also advertises the bare `qmux-02`,
// `qmux-01`, and `qmux-00`, so we still interop with relays that only know a
// wire-format version.
const quic = new Session(url, {
protocols: alpns,
versions: Object.fromEntries(alpns.map((alpn) => [alpn, QMUX[alpn] ?? null])),
});

// Wait for the WebSocket to connect, or for the cancel promise to resolve.
// `ready` rejects on a refused/failed connection, so a throw here is the caller's
// cue to retry; a lost cancel race instead resolves and we close the loser.
const loaded = await Promise.race([quic.ready.then(() => true), cancel]);
if (!loaded) {
quic.close();
return undefined;
// Wait for the WebSocket to connect, for the cancel promise to resolve, or for the
// redial. `ready` rejects on a refused/failed connection, so a throw here is the
// caller's cue to retry; a lost cancel race instead resolves and we close the loser.
const disarm = new AbortController();
try {
// `race` rather than `Promise.race`, and `cancel` itself rather than something derived
// from it: `cancel` outlives every dial, and `race` releases what it attached.
const outcome = await race([
quic.ready.then(() => "open" as const),
cancel,
sleep(Nano.fromMilli(wait), { signal: disarm.signal }).then(() => "redial" as const),
]);
if (outcome === "open") return quic;
quic.close();
if (outcome !== "redial") return undefined;
console.debug(redact(url), `WebSocket not open after ${wait}ms; dialing again`);
} finally {
disarm.abort();
}
}

return quic;
}
35 changes: 35 additions & 0 deletions js/net/src/connection/pool.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -301,6 +301,7 @@ test("connection-specific options infer a private loop and origin", async () =>
{ webtransport: { congestionControl: "throughput" as const } },
{ websocket: { enabled: false } },
{ delay: { timeout: Milli(0) } },
{ timeout: Milli(10_000) },
{ publish: origin.consume() },
{ consume: origin },
];
Expand Down Expand Up @@ -335,6 +336,7 @@ test("explicit share: true refuses connection-specific options", () => {
);
expect(() => new Connection({ share: true, websocket: { enabled: false } })).toThrow(/share: false/);
expect(() => new Connection({ share: true, delay: { timeout: Milli(0) } })).toThrow(/share: false/);
expect(() => new Connection({ share: true, timeout: Milli(10_000) })).toThrow(/share: false/);
} finally {
origin.close();
}
Expand Down Expand Up @@ -775,3 +777,36 @@ test("GOAWAY keeps version pools distinct at the redirected URL", async () => {
defaults?.close();
}
});

test("a private handle's timeout bounds each attempt", async () => {
let attempts = 0;
class Hung {
ready = new Promise<void>(() => {});
closed = new Promise<void>(() => {});
close() {}
}
globalThis.WebTransport = function StubWebTransport() {
attempts++;
return new Hung();
} as unknown as typeof WebTransport;

const handle = new Connection({
url,
share: false,
websocket: { enabled: false },
timeout: Milli(50),
delay: { initial: Milli(10), multiplier: 1, max: Milli(10) },
});
try {
// Each hung dial is cut at 50 ms and redialed after the backoff; the default 30 s
// timeout would still be holding the first.
await advance(1_000);
expect(attempts).toBeGreaterThanOrEqual(3);
} finally {
handle.close();
}
});

test("an invalid timeout is refused when a private handle is built", () => {
expect(() => new Connection({ url, share: false, timeout: Number.NaN as Milli })).toThrow(RangeError);
});
16 changes: 15 additions & 1 deletion js/net/src/connection/pool.ts
Original file line number Diff line number Diff line change
Expand Up @@ -79,6 +79,13 @@ export interface ConnectionProps {
/** Backoff settings for the reconnect loop; an unset field uses its default. */
delay?: ReloadDelay;

/**
* Maximum time for each connection attempt, the dial and the MoQ handshake (default:
* 30000ms; `0` waits forever). An attempt that outlives it is retried like any other
* failure. The same bound as the `timeout` option of {@link Connection.connect}.
*/
timeout?: Milli;

/**
* How to react to the relay's GOAWAY; an unset field uses its default. Every connection
* migrates on GOAWAY, dialing the replacement while the old session finishes its groups.
Expand Down Expand Up @@ -114,7 +121,7 @@ export interface ConnectionProps {
* session finishes its groups, and the handle and its origin carry across. A redirect the
* {@link ConnectionProps.goaway} policy refuses stops the loop like an auth rejection does.
*
* Options the pool cannot honor (transport options, delay, goaway, a pinned
* Options the pool cannot honor (transport options, delay, timeout, goaway, a pinned
* certificate, caller-owned origins) use a private loop. An explicit `share: true`
* refuses them. A supplied transport cannot reconnect at all; pass it to {@link Connection.connect}
* instead.
Expand Down Expand Up @@ -217,6 +224,8 @@ export class Connection {
// A plain list is checked and copied now, so a bad name throws here and mutating the array
// later changes nothing. A live list is checked as it changes, failing on `error`.
const fixed = normalizeVersions({ ...props, versions: Array.isArray(given) ? given : undefined });
// Likewise a bad timeout, before anything below exists to leak.
if (props?.timeout !== undefined) Milli(props.timeout);
refuse(props);
this.#signals = new Effect();

Expand Down Expand Up @@ -296,6 +305,7 @@ export class Connection {
webtransport: props.webtransport,
websocket: props.websocket,
delay: props.delay,
timeout: props.timeout,
goaway: props.goaway,
});
signals.cleanup(() => loop.close());
Expand Down Expand Up @@ -434,6 +444,9 @@ function refuse(props?: ConnectionProps): void {
if (props.delay !== undefined) {
throw new Error("delay cannot be shared; pass share: false");
}
if (props.timeout !== undefined) {
throw new Error("timeout cannot be shared; pass share: false");
}
if (props.goaway !== undefined) {
throw new Error("goaway cannot be shared; pass share: false");
}
Expand All @@ -445,6 +458,7 @@ function requiresPrivate(props: ConnectionProps): boolean {
props.webtransport !== undefined ||
props.websocket !== undefined ||
props.delay !== undefined ||
props.timeout !== undefined ||
props.goaway !== undefined ||
props.publish !== undefined ||
props.consume !== undefined
Expand Down
Loading
Loading