Skip to content
Merged
1 change: 1 addition & 0 deletions js/net/src/ietf/publisher.ts
Original file line number Diff line number Diff line change
Expand Up @@ -1307,6 +1307,7 @@ export class Publisher {
version: this.#session.version,
sendOrder: place.rank,
cancel: race([unsubscribed, abandoned, excluded.promise]),
group: true,
});
} finally {
opened.resolve();
Expand Down
1 change: 1 addition & 0 deletions js/net/src/lite/publisher.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2229,6 +2229,7 @@ export class Publisher {
version: this.version,
sendOrder: place.rank,
cancel: race([unsubscribed, abandoned]),
group: true,
});
} finally {
opened.resolve();
Expand Down
83 changes: 83 additions & 0 deletions js/net/src/open.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,83 @@
import { expect, test } from "bun:test";
import Qmux from "@moq/qmux";
import { Version } from "./lite/version.ts";
import { createMockTransportPair } from "./mock.ts";
import { lines } from "./open.ts";
import { Writer } from "./stream.ts";

const version = Version.DRAFT_07;
const never = new Promise<void>(() => {});

// A qmux session pair over an in-memory socket.
function qmuxPair(): { client: WebTransport; server: WebTransport } {
const socket = (readable: ReadableStream<Uint8Array>, writable: WritableStream<Uint8Array>) => {
const closed = Promise.withResolvers<{ closeCode: number; reason: string }>();
return {
url: "",
opened: Promise.resolve({ readable, writable, extensions: "", protocol: "qmux-01" }),
closed: closed.promise,
close: () => closed.resolve({ closeCode: 1000, reason: "" }),
};
};
// Copied, since a sender may reuse its buffer once a write resolves.
const pipe = () =>
new TransformStream<Uint8Array, Uint8Array>({ transform: (chunk, c) => c.enqueue(chunk.slice()) });
const up = pipe();
const down = pipe();
const config = { idleTimeout: null };
const client = new Qmux(socket(down.readable, up.writable), { config });
const server = Qmux.accept(socket(up.readable, down.writable), { config });
return { client, server };
}

function openGroup(quic: WebTransport, sendOrder: number): Promise<Writer> {
return Writer.tryOpen(quic, { version, sendOrder, cancel: never, group: true }) as Promise<Writer>;
}

function orders(quic: WebTransport): number[] {
return lines(quic)
.streams.list()
.map((stream) => stream.sendOrder);
}

test("group streams are listed lowest send order first until they close or reset", async () => {
const { client, server } = createMockTransportPair();
const first = await openGroup(client, 1);
const second = await openGroup(client, 3);
const control = await Writer.open(client, { version });
const third = await openGroup(client, 2);
expect(orders(client)).toEqual([1, 2, 3]);

second.setPriority(0);
expect(orders(client)).toEqual([0, 1, 2]);

first.close();
second.reset(new Error("cancel"));
expect(orders(client)).toEqual([2]);
third.close();
expect(orders(client)).toEqual([]);

expect(lines(client).streams.acknowledges).toBe(false);
expect(await control.acknowledged()).toBeUndefined();
client.close();
server.close();
});

test("a qmux group stream reports what the peer has acknowledged", async () => {
const { client, server } = qmuxPair();
expect(lines(client).streams.acknowledges).toBe(true);
const stream = await openGroup(client, 0);
const [listed] = lines(client).streams.list();
expect(listed).toBe(stream);
expect(await listed.acknowledged()).toBe(true);

const write = stream.write(new Uint8Array(1024));
expect(await listed.acknowledged()).toBe(false);
await write;
expect(await listed.acknowledged()).toBe(true);

stream.reset(new Error("cancel"));
expect(await stream.acknowledged()).toBe(false);
client.close();
server.close();
});
49 changes: 47 additions & 2 deletions js/net/src/open.ts
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
import { race } from "@moq/signals";
import { transportOf } from "./connection/transport.ts";

/**
* The one entry point every stream a session opens goes through.
Expand All @@ -15,6 +16,10 @@ import { race } from "@moq/signals";
*
* Chrome ignores a `sendOrder` set after a create, so there a stream handed to another open
* keeps the send order it was created at.
*
* The session also lists the group streams it has open, each with its send order and whether
* the peer has acknowledged everything written to it, so an open waiting for credit can choose
* a lower one to make room with.
*/

const live = Symbol("live");
Expand Down Expand Up @@ -156,15 +161,54 @@ function aborted(signal: AbortSignal): { promise: Promise<void>; done: () => voi

type SendStream = WritableStream<Uint8Array> & { sendOrder?: number };

/** The lines of one session's opens. */
/** One of a session's open group streams. */
export interface OpenStream {
/** The send order the stream has now, where HIGHER values are sent first. */
readonly sendOrder: number;
/**
* Whether the peer has acknowledged every byte written to it so far, or undefined when the
* transport cannot tell.
*/
acknowledged(): Promise<boolean | undefined>;
}

/** The group streams a session has open, from when each opens until it is closed or reset. */
export class OpenStreams {
/**
* Whether the transport reports acknowledgements, known when the session starts:
* `@moq/qmux` does, a browser's WebTransport cannot.
*/
readonly acknowledges: boolean;
readonly #open = new Set<OpenStream>();

constructor(acknowledges: boolean) {
this.acknowledges = acknowledges;
}

add(stream: OpenStream) {
this.#open.add(stream);
}

delete(stream: OpenStream) {
this.#open.delete(stream);
}

/** The open group streams, the lowest send order first, and the earliest opened among equals. */
list(): OpenStream[] {
return [...this.#open].sort((a, b) => a.sendOrder - b.sendOrder);
}
}

/** The lines of one session's opens, and the group streams it has open. */
interface Lines {
uni: Line<SendStream>;
bi: Line<WebTransportBidirectionalStream>;
streams: OpenStreams;
}

const sessions = new WeakMap<WebTransport, Lines>();

/** The lines `quic`'s opens wait in, shared by everything opening on it. */
/** The lines `quic`'s opens wait in, and its open group streams, shared by everything opening on it. */
export function lines(quic: WebTransport): Lines {
let lines = sessions.get(quic);
if (lines) return lines;
Expand All @@ -185,6 +229,7 @@ export function lines(quic: WebTransport): Lines {
(stream.writable as SendStream).sendOrder = sendOrder;
},
),
streams: new OpenStreams(transportOf(quic) === "websocket"),
};
sessions.set(quic, lines);
return lines;
Expand Down
82 changes: 76 additions & 6 deletions js/net/src/stream.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ import { fromTransport, StreamCode, toStreamCode, toTransport } from "./error.ts
import { sharedStreamCode } from "./ietf/error.ts";
import type { IetfVersion } from "./ietf/version.ts";
import { Version as Lite, type Version as LiteVersion } from "./lite/version.ts";
import { lines, type Rank } from "./open.ts";
import { lines, type OpenStream, type OpenStreams, type Rank } from "./open.ts";
import { decodeError } from "./util/decode_error.ts";
import { POW32, toBigInt, toNumber, U64 } from "./util/u64.ts";
import { decodeUtf8 } from "./util/utf8.ts";
Expand Down Expand Up @@ -151,8 +151,14 @@ export interface TryOpenOptions extends Omit<OpenOptions, "sendOrder"> {

/** Give up once this resolves. */
cancel: Promise<void>;

/** List the stream among the session's open group streams until it is closed or reset. */
group?: boolean;
}

/** A send stream that reports what it sent, as W3C WebTransport's `WebTransportSendStream.getStats()` does. */
type Stats = WritableStream<Uint8Array> & { getStats(): Promise<{ bytesAcknowledged: number }> };

export class Stream {
reader: Reader;
writer: Writer;
Expand Down Expand Up @@ -690,11 +696,21 @@ const U62 = (c: Cursor) => c.u62();
const VARINT = (c: Cursor) => c.varint();

// Writer wraps a stream and writes chunks of data
export class Writer {
export class Writer implements OpenStream {
#writer: WritableStreamDefaultWriter<Uint8Array>;
#stream: WritableStream<Uint8Array>;
#closed?: Promise<void>;

/** The bytes handed to the stream so far. */
#written = 0;
#sendOrder = 0;
/** Whether the transport reports acknowledgements, as the session's open streams say. */
#acknowledges = false;
/** Reset by this side, or failed or stopped by the peer, so never acknowledged. */
#aborted = false;
/** The session's open group streams, while this one is among them. */
#listed?: OpenStreams;

// Scratch buffer for each primitive write, sized for the longest (a 9-byte leading-ones varint).
#scratch: ArrayBuffer;

Expand All @@ -705,6 +721,19 @@ export class Writer {
this.#scratch = new ArrayBuffer(9);
this.#writer = this.#stream.getWriter();
this.version = version;
// The stream ends once it is finished, or with a failure: a reset, a stop, or the session closing.
this.#writer.closed.then(
() => this.#unlist(),
() => {
this.#aborted = true;
this.#unlist();
},
);
}

/** The send order the stream has now, where HIGHER values are sent first. */
get sendOrder(): number {
return this.#sendOrder;
}

/**
Expand All @@ -718,9 +747,22 @@ export class Writer {
* ignored property, the same way an ignored `sendOrder` option does at {@link open}.
*/
setPriority(sendOrder: number) {
this.#sendOrder = sendOrder;
(this.#stream as SendStream).sendOrder = sendOrder;
}

/**
* Whether the peer has acknowledged every byte written so far, or undefined when the
* transport cannot tell, as a browser's WebTransport cannot.
*/
async acknowledged(): Promise<boolean | undefined> {
if (!this.#acknowledges) return undefined;
if (this.#aborted) return false;
const written = this.#written;
const stats = await (this.#stream as Stats).getStats();
return !this.#aborted && stats.bytesAcknowledged >= written;
}

async bool(v: boolean) {
await this.write(setUint8(this.#scratch, v ? 1 : 0));
}
Expand Down Expand Up @@ -767,6 +809,7 @@ export class Writer {
}

async write(v: Uint8Array) {
this.#written += v.byteLength;
// Mirrors Reader.#fill: every write funnels through here, so a STOP_SENDING from the
// peer surfaces as a typed code rather than the transport's own error shape.
await this.#writer.write(v).catch((err: unknown) => {
Expand All @@ -783,6 +826,7 @@ export class Writer {
}

close() {
this.#unlist();
this.#writer.close().catch(() => void 0);
}

Expand All @@ -796,9 +840,16 @@ export class Writer {
}

reset(reason: unknown) {
this.#aborted = true;
this.#unlist();
this.#writer.abort(withCode(reason, this.version)).catch(() => void 0);
}

#unlist() {
this.#listed?.delete(this);
this.#listed = undefined;
}

/** Run `f` against a Writer that buffers in memory, returning everything it wrote as one chunk. */
static async collect(version: StreamVersion, f: (w: Writer) => Promise<void>): Promise<Uint8Array> {
const chunks: Uint8Array[] = [];
Expand All @@ -824,8 +875,9 @@ export class Writer {
*/
/** Open a send-only stream, waiting its turn for the peer's stream credit. */
static async open(quic: WebTransport, options: OpenOptions): Promise<Writer> {
const writable = await lines(quic).uni.open(options.sendOrder ?? 0);
return new Writer(writable, options.version);
const session = lines(quic);
const writable = await session.uni.open(options.sendOrder ?? 0);
return Writer.#opened(writable, options.version, options.sendOrder ?? 0, session.streams);
}

/**
Expand All @@ -834,8 +886,26 @@ export class Writer {
* to the next open in line. A transport failure, or a rejected `cancel`, still throws.
*/
static async tryOpen(quic: WebTransport, options: TryOpenOptions): Promise<Writer | undefined> {
const writable = await lines(quic).uni.open(options.sendOrder ?? 0, options.cancel);
return writable && new Writer(writable, options.version);
const session = lines(quic);
const rank = options.sendOrder ?? 0;
// The line ranks the stream it hands out by its last read, which can differ from a read now.
let sendOrder = typeof rank === "number" ? rank : 0;
const read = typeof rank === "number" ? rank : () => (sendOrder = rank());
const writable = await session.uni.open(read, options.cancel);
if (!writable) return undefined;
const writer = Writer.#opened(writable, options.version, sendOrder, session.streams);
if (options.group) {
writer.#listed = session.streams;
session.streams.add(writer);
}
return writer;
}

static #opened(writable: SendStream, version: StreamVersion, sendOrder: number, streams: OpenStreams): Writer {
const writer = new Writer(writable, version);
writer.#sendOrder = sendOrder;
writer.#acknowledges = streams.acknowledges;
return writer;
}
}

Expand Down
21 changes: 18 additions & 3 deletions js/qmux/api/index.api.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,10 @@ export interface AcceptOptions extends Pick<SessionOptions, "config" | "sendBuff
protocol?: string;
}

export interface BidirectionalStream extends WebTransportBidirectionalStream {
readonly writable: SendStream;
}

export interface Config {
idleTimeout?: number | null;
maxDatagramFrameSize?: bigint | null;
Expand All @@ -20,10 +24,21 @@ export interface InstallOptions {
versions?: Record<string, Version | Version[] | null>;
}

export interface SendStream extends WritableStream<Uint8Array> {
getStats(): Promise<SendStreamStats>;
sendOrder: number;
}

export type SendStreamOptions = WebTransportSendStreamOptions & {
waitUntilAvailable?: boolean;
};

export interface SendStreamStats {
bytesAcknowledged: number;
bytesSent: number;
bytesWritten: number;
}

export class SessionError extends Error implements Pick<WebTransportError, "source" | "streamErrorCode"> {
constructor(message: string, options?: {
cause?: unknown;
Expand Down Expand Up @@ -109,13 +124,13 @@ export default class implements WebTransport {
}): void;
readonly closed: Promise<WebTransportCloseInfo>;
get congestionControl(): WebTransportCongestionControl;
createBidirectionalStream(options?: SendStreamOptions): Promise<WebTransportBidirectionalStream>;
createUnidirectionalStream(options?: SendStreamOptions): Promise<WritableStream<Uint8Array>>;
createBidirectionalStream(options?: SendStreamOptions): Promise<BidirectionalStream>;
createUnidirectionalStream(options?: SendStreamOptions): Promise<SendStream>;
get datagrams(): WebTransportDatagramDuplexStream;
getStats(): Promise<{
datagrams: {};
}>;
readonly incomingBidirectionalStreams: ReadableStream<WebTransportBidirectionalStream>;
readonly incomingBidirectionalStreams: ReadableStream<BidirectionalStream>;
readonly incomingUnidirectionalStreams: ReadableStream<ReadableStream<Uint8Array>>;
get protocol(): string;
readonly ready: Promise<void>;
Expand Down
Loading
Loading