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
1 change: 1 addition & 0 deletions bun.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

4 changes: 3 additions & 1 deletion doc/concept/moq-lite.md
Original file line number Diff line number Diff line change
Expand Up @@ -297,7 +297,9 @@ JSON and not for media. Each group's frames become one DEFLATE stream
compresses alone. Only the work-in-progress moq-lite 07 carries the compressed
bytes. A relay forwards them as received and inflates each group once for every
other subscriber, moq-transport included, so readers always see the original
frames. Rust publishes and relays compressed tracks; js/net refuses them for now.
frames. Rust and JavaScript publish compressed tracks by setting `compress: true`
on the track's info. Application writes stay synchronous and readers receive plain
payloads; compression is useful for repetitive data, not already compressed media.

A relay cancels its upstream subscription once nobody subscribes, but keeps its
copy of the track for 30 seconds after the last reader leaves, so a returning
Expand Down
2 changes: 1 addition & 1 deletion js/justfile
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ test-changed list:
coverage package="":
python3 ../sh/js/coverage.py '{{ package }}'

# Run one net benchmark: broadcasts, forward, requests, reader, frames, track, resume, interests, observed, varint, lite-varint, priority, request-ids, or subscribe-drop.
# Run one net benchmark: broadcasts, forward, requests, reader, frames, track, resume, interests, observed, varint, lite-varint, priority, request-ids, subscribe-drop, or compression.
bench name:
bun install --frozen-lockfile
bun net/bench/{{ name }}.ts
Expand Down
70 changes: 70 additions & 0 deletions js/net/bench/compression.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
/** Sweep compressed publishers x plain readers, reporting one shared inflated copy per group. */
import { gzipSync } from "node:zlib";
import type { Producer as Group } from "../src/group.ts";
import { hooks } from "../src/internal.ts";
import { Producer as Track } from "../src/track.ts";

const payload = new TextEncoder().encode('{"value":123,"status":"unchanged"}\n'.repeat(64));
const frames = 32;
const rounds = 10;
console.log("publishers,readers,publish_us,read_us,stored_bytes,inflated_bytes");
for (const publishers of [1, 4, 16]) {
for (const readers of [1, 4, 16]) {
let publish = 0;
let read = 0;
let stored = 0;
let inflated = 0;
for (let round = 0; round < rounds; round++) {
const tracks = Array.from({ length: publishers }, () => new Track("bench").accept({ compress: true }));
const groups: Group[] = tracks.map((track) => track.appendGroup());
const consumers = groups.map((group) => Array.from({ length: readers }, () => group.mirror()));
let started = performance.now();
for (const group of groups) {
for (let index = 0; index < frames; index++) group.writeFrame({ payload });
group.close();
}
publish += performance.now() - started;
stored = groups.reduce((bytes, group) => bytes + hooks.groupCacheBytes(group), 0);
started = performance.now();
for (const subscribers of consumers) {
let shared: Uint8Array | undefined;
for (const consumer of subscribers) {
for (let index = 0; index < frames; index++) {
const frame = consumer.tryReadFrame();
if (!frame || frame.payload.length !== payload.length) throw new Error("missing payload");
if (index === 0) {
if (shared && shared !== frame.payload) throw new Error("fanout duplicated inflation");
shared = frame.payload;
}
}
consumer.close();
}
}
read += performance.now() - started;
inflated = groups.reduce((bytes, group) => bytes + hooks.groupCacheBytes(group), 0) - stored;
if (inflated !== publishers * frames * payload.length) throw new Error("inflated bytes scale with readers");
for (const track of tracks) track.close();
}
console.log(
[
publishers,
readers,
((publish * 1000) / rounds).toFixed(1),
((read * 1000) / rounds).toFixed(1),
stored,
inflated,
].join(","),
);
}
}

// This entry is an application importing only its track consumer. Synchronous model writes
// share the module, so its bundle includes the encoder as well as the decoder.
const bundle = await Bun.build({
entrypoints: [new URL("./fixtures/compression-consumer.ts", import.meta.url).pathname],
minify: true,
target: "browser",
});
if (!bundle.success) throw new AggregateError(bundle.logs, "consumer bundle failed");
const bytes = new Uint8Array(await bundle.outputs[0].arrayBuffer());
console.log(`consumer_bundle_bytes=${bytes.length},gzip_bytes=${gzipSync(bytes).length}`);
2 changes: 2 additions & 0 deletions js/net/bench/fixtures/compression-consumer.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
/** Consumer-only entry for measuring the static application graph. @module */
export { Consumer } from "../../src/track.ts";
6 changes: 3 additions & 3 deletions js/net/bench/frames.ts
Original file line number Diff line number Diff line change
Expand Up @@ -52,9 +52,9 @@ const lite: Protocol = {
async subscribe() {
const open: Open = (stream) => {
const producer = new Producer(0);
const done = readFrames(new Reader(stream, undefined, LiteVersion.DRAFT_06), producer, 1_000_000).then(() =>
producer.close(),
);
const done = readFrames(new Reader(stream, undefined, LiteVersion.DRAFT_06), producer, {
scale: 1_000_000,
}).then(() => producer.close());
return { group: Promise.resolve(producer.consume()), done };
};
return { open, close: () => {} };
Expand Down
2 changes: 1 addition & 1 deletion js/net/bench/lite-varint.ts
Original file line number Diff line number Diff line change
Expand Up @@ -79,7 +79,7 @@ const subscribe: Sample = {
const datagram: Sample = {
name: "Datagram",
encode: (w, version) => w.write(new Datagram(3n, 1_234, 1_234_567_890, new Uint8Array()).encode(version)),
decode: (r, version) => r.readAll().then((data) => Datagram.decode(data, version, () => true)),
decode: (r, version) => r.readAll().then((data) => Datagram.decode(data, version, () => ({ timed: true }))),
};

const hop = randomHop();
Expand Down
1 change: 1 addition & 0 deletions js/net/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@
"@moq/qmux": "workspace:^",
"@moq/signals": "workspace:*",
"async-mutex": "^0.5.0",
"pako": "^3.0.2",
"uuid": "^14.0.3"
},
"peerDependencies": {
Expand Down
62 changes: 62 additions & 0 deletions js/net/src/flate/codec.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
import { expect, spyOn, test } from "bun:test";
import { deflateRaw, Inflate } from "pako";
import { Decoder } from "./decoder.ts";
import { Encoder } from "./encoder.ts";

const text = new TextEncoder();

test("group slices preserve a shared window across empty and nonempty frames", () => {
const frames = ["the quick brown fox", "", "the quick brown dog", "the lazy fox"];
const encoder = new Encoder();
const decoder = new Decoder();
for (const frame of frames.map((value) => text.encode(value))) {
expect(decoder.frame(encoder.frame(frame), frame.length)).toEqual(frame);
}
});

test("a retained frame owns only its payload, across later pushes", () => {
const encoder = new Encoder();
const decoder = new Decoder();
const first = decoder.frame(encoder.frame(text.encode("first")), 5);
decoder.frame(encoder.frame(new Uint8Array(20_000)), 20_000);
expect(first).toEqual(text.encode("first"));
expect(first.buffer.byteLength).toBe(first.length);
});

test("each declared size is exact, including an empty slice", () => {
const slice = new Encoder().frame(new Uint8Array(1024));
for (const size of [512, 2048]) expect(() => new Decoder().frame(slice, size)).toThrow(/declared size/);
expect(() => new Decoder().frame(new Uint8Array(), 1)).toThrow(/declared size/);
});

test("a bomb stops inflating at the declaration plus one scratch chunk", () => {
const slice = new Encoder().frame(new Uint8Array(1024 * 1024));
const push = Inflate.prototype.push;
let output = 0;
const pushing = spyOn(Inflate.prototype, "push").mockImplementation(function (this: Inflate, ...args) {
const onData = this.onData;
this.onData = (chunk) => {
output += chunk.length;
onData.call(this, chunk);
};
try {
return push.apply(this, args);
} finally {
this.onData = onData;
}
});
try {
expect(() => new Decoder().frame(slice, 1)).toThrow(/exceeds/);
expect(output).toBe(4096);
} finally {
pushing.mockRestore();
}
});

test("final blocks, malformed input, and a decoder already failed are refused", () => {
const frame = text.encode("final");
expect(() => new Decoder().frame(deflateRaw(frame), frame.length)).toThrow(/ended/);
const decoder = new Decoder();
expect(() => decoder.frame(new Uint8Array(64).fill(0xff), 64)).toThrow();
expect(() => decoder.frame(new Uint8Array(), 0)).toThrow(/already failed/);
});
59 changes: 59 additions & 0 deletions js/net/src/flate/decoder.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
// The group-scoped moq-flate decoder; applications always read inflated frames.
import { Inflate, Z_SYNC_FLUSH } from "pako";
import { StreamCode, StreamError } from "../error.ts";

const SYNC_FLUSH_TAIL = new Uint8Array([0x00, 0x00, 0xff, 0xff]);

function malformed(message: string): Error {
return new StreamError(StreamCode.MalformedTrack, { message });
}

/** Decode one group's slices in frame order, enforcing each declared size. @internal */
export class Decoder {
#inflate = new Inflate({ raw: true, chunkSize: 4096 });
#chunks: Uint8Array[] = [];
#total = 0;
#size = 0;
#failed = false;

constructor() {
this.#inflate.onData = (chunk) => {
this.#total += chunk.length;
// Throw inside push, so a bomb stops doing work at its declaration plus one
// scratch chunk rather than merely discarding the rest of its output.
if (this.#total > this.#size) throw malformed("inflated frame exceeds its declared size");
this.#chunks.push(chunk);
};
}

/** Inflate a slice to exactly `size` bytes, without preallocating from that declaration. */
frame(slice: Uint8Array, size: number): Uint8Array {
if (this.#failed) throw malformed("decoder already failed");
if (!Number.isSafeInteger(size) || size < 0) throw malformed("invalid inflated frame size");
this.#chunks = [];
this.#total = 0;
this.#size = size;
try {
if (slice.length > 0) {
this.#inflate.push(slice, false);
if (this.#inflate.ended) throw malformed("compressed group ended its DEFLATE stream");
this.#inflate.push(SYNC_FLUSH_TAIL, Z_SYNC_FLUSH);
if (this.#inflate.err || this.#inflate.ended) throw malformed("malformed DEFLATE slice");
}
if (this.#total !== size) throw malformed("inflated frame differs from its declared size");
// Retained frames must own tight buffers rather than pinning scratch storage.
const out = new Uint8Array(this.#total);
let offset = 0;
for (const chunk of this.#chunks) {
out.set(chunk, offset);
offset += chunk.length;
}
return out;
} catch (error) {
this.#failed = true;
throw error;
} finally {
this.#chunks = [];
}
}
}
73 changes: 73 additions & 0 deletions js/net/src/flate/encoder.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
// Synchronous model writes include the encoder in the static graph.
import { Deflate, type DeflateOptions, Z_SYNC_FLUSH } from "pako";

const DEFAULT_LEVEL = 6;
const SYNC_FLUSH_TAIL = new Uint8Array([0x00, 0x00, 0xff, 0xff]);

/** Options for an {@link Encoder}. */
interface EncoderOptions {
/** DEFLATE level, `0..=9` (higher is smaller and slower). Defaults to {@link DEFAULT_LEVEL}. */
level?: number;
}

/**
* Encodes a stream's frame payloads into one shared DEFLATE window, one self-delimited slice per
* frame. Hold one per stream; create a new one for each independent stream.
*
* @internal
*/
export class Encoder {
#deflate: Deflate;
#chunks: Uint8Array[] = [];
#total = 0;

/** Start a fresh encoder with a cold window. */
constructor(options: EncoderOptions = {}) {
// `raw`: no zlib header/trailer, matching the Rust side and the browser's `deflate-raw`.
// pako types `level` as a literal union; we accept a plain number and narrow here.
const level = (options.level ?? DEFAULT_LEVEL) as DeflateOptions["level"];
this.#deflate = new Deflate({ raw: true, level });
this.#deflate.onData = (chunk) => {
const bytes = chunk as Uint8Array;
this.#chunks.push(bytes);
this.#total += bytes.length;
};
}

/**
* The most bytes {@link frame} can return for a payload of `len` bytes, at any level and whatever
* the window already holds.
*
* zlib's `deflateBound` for its default window and memory level, which both pako and the Rust
* `moq-flate` use: incompressible input falls back to stored blocks, 5 bytes per 16 KiB. The
* constant covers the block headers and the flush, whose fixed 4-byte marker is stripped anyway.
*/
static bound(len: number): number {
// Division rather than shifts, which wrap past 2^31.
return len + Math.floor(len / 4096) + Math.floor(len / 16384) + Math.floor(len / 33554432) + 13;
}

/**
* Compress the next frame's `payload`, returning its slice of the stream: the DEFLATE bytes minus
* the fixed sync-flush marker. Empty in yields empty out. Slices must be produced in frame order.
*/
frame(payload: Uint8Array): Uint8Array {
if (payload.length === 0) return payload;
this.#chunks = [];
this.#total = 0;
this.#deflate.push(payload, Z_SYNC_FLUSH);

// Copy into one tight owned buffer, dropping the trailing sync-flush marker. We can't return
// pako's chunk views: a caller retains the reference and pako backs each chunk with a ~16 KB
// buffer, so a view would pin far more memory than the frame.
const out = new Uint8Array(this.#total - SYNC_FLUSH_TAIL.length);
let offset = 0;
for (const chunk of this.#chunks) {
if (offset >= out.length) break;
const take = Math.min(chunk.length, out.length - offset);
out.set(chunk.subarray(0, take), offset);
offset += take;
}
return out;
}
}
Loading
Loading