Skip to content
Merged
7 changes: 3 additions & 4 deletions js/net/bench/track.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
/** Sweep retained groups and subscribers for one group published through a track and received. */

import { Milli } from "@moq/clock";
import { DEFAULT_EXPIRY } from "../src/cache.ts";
import type { Consumer as GroupConsumer, Producer as GroupProducer } from "../src/group.ts";
import { Timescale, Timestamp } from "../src/time.ts";
import { Producer, type Subscriber } from "../src/track.ts";
Expand All @@ -16,8 +17,6 @@ const holds = [
] as const;
type Hold = (typeof holds)[number];
const groups = 100;
// Matches the private idle window and Rust cache::DEFAULT_EXPIRY.
const CACHE_WINDOW_MS = 30_000;
const reps = 7;
// Publishing a group must not cost more as the retained window grows, or a guard or cache pass
// has gone back to scanning every retained group. The sweep spans 60x, so a scan lands well past
Expand Down Expand Up @@ -61,7 +60,7 @@ async function measure(
let sequence = 0;
// Inserted by sequence, the way the wire hands a subscribed track its groups.
const publish = (close: boolean) => {
clock += held > 0 ? 1 : CACHE_WINDOW_MS / retained;
clock += held > 0 ? 1 : DEFAULT_EXPIRY / retained;
const group = producer.createGroup(BigInt(sequence));
group.writeFrame({ payload, timestamp: Timestamp.fromMillis(sequence++) });
if (close) group.finish();
Expand Down Expand Up @@ -114,7 +113,7 @@ async function measure(
producer.finish();
producer.close();
// Ending the track releases the newest group too; idle cleanup reclaims the cache.
clock += CACHE_WINDOW_MS + CACHE_WINDOW_MS / 8 + 1;
clock += 2 * DEFAULT_EXPIRY;
const idleStart = now();
const replay = producer.subscribe({ delay: { max: window } });
if (replay.tryRecvGroup()) throw new Error("idle cache entries were retained");
Expand Down
7 changes: 3 additions & 4 deletions js/net/src/broadcast.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -513,10 +513,9 @@ test("a stalled consumer does not pin evicted groups", async () => {

producer.writeFrame(textFrame("old"));

// Advance past the cache window, plus the scan slice a prune may lag by, and write
// again to trigger a prune. The old (closed, aged-out) group is dropped from the
// stalled sink, not retained.
clock.jump(Nano.fromMilli(Milli(30_000 + 30_000 / 8)));
// Advance past the cache window and write again, which scans for idle groups. The old
// (closed, aged-out) group is dropped from the stalled sink, not retained.
clock.jump(Nano.fromMilli(Milli(30_000 + 1_000)));
producer.writeFrame(textFrame("fresh"));

// The next group in arrival order is the fresh one (seq 1): the old (seq 0) group
Expand Down
17 changes: 14 additions & 3 deletions js/net/src/broadcast.ts
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@
* @module
*/
import { type GetPromise, Once, Signal } from "@moq/signals";
import * as cache from "./cache.ts";
import * as datagram from "./datagram.ts";
import { NotFound, StreamCode, StreamError, toStreamCode } from "./error.ts";
import type { Consumer as GroupConsumer } from "./group.ts";
Expand Down Expand Up @@ -54,6 +55,16 @@ class BroadcastState {
unheld = false;
// Run synchronously once the broadcast closes, before `closed` notifies its observers.
closers = new Set<() => void>();
// The cache pool every track of the broadcast caches into, defaulting as Rust's
// `broadcast::Info` does: no byte capacity, and the default idle window.
pool = new cache.Pool({ expiry: cache.DEFAULT_EXPIRY });
}

// A new track of the broadcast, caching into its pool.
function createProducer(state: BroadcastState, name: string): track.Producer {
const producer = new track.Producer(name);
hooks.poolTrack(producer, state.pool);
return producer;
}

// Datagram tracks never enter the stream listing or cache.
Expand Down Expand Up @@ -204,7 +215,7 @@ function logical(state: BroadcastState, name: string): { producer: track.Produce
const existing = lookup(state, name);
if (existing) return { producer: existing, requested: false };

const producer = new track.Producer(name);
const producer = createProducer(state, name);
if (!state.served) {
// Answer through the track rather than throwing, so a peer's subscribe is refused with
// the code instead of an unhandled error.
Expand Down Expand Up @@ -398,7 +409,7 @@ export class Producer {
const state = broadcast.#state;
if (state.closed.peek() !== undefined) throw new Error("broadcast is closed");
if (lookup(state, name)) throw new Error("duplicate reserved track");
const producer = new track.Producer(name);
const producer = createProducer(state, name);
const lookups = new Lookups();
state.lookups.set(producer, lookups);
state.requests.set(name, producer);
Expand Down Expand Up @@ -462,7 +473,7 @@ export class Producer {
throw new Error(`duplicate track: ${name}`);
}

const producer = new track.Producer(name).accept(info);
const producer = createProducer(this.#state, name).accept(info);
adopt(this.#state, producer, track.authoredInfo(info));
return producer;
}
Expand Down
276 changes: 276 additions & 0 deletions js/net/src/cache.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,276 @@
import { expect, test } from "bun:test";
import { Manual, Milli, Nano, yieldNow } from "@moq/clock";
import * as cache from "./cache.ts";
import { StreamCode, TooFarBehind } from "./error.ts";
import { hooks } from "./internal.ts";
import { Producer as TrackProducer } from "./track.ts";

// Run `fn` on a manual clock, stepped in milliseconds.
async function withClock(fn: (clock: { advance: (ms: number) => Promise<void> }) => Promise<void> | void) {
const clock = new Manual();
const installed = clock.install();
try {
await fn({ advance: (ms) => clock.advance(Nano.fromMilli(Milli(ms))) });
} finally {
installed.close();
}
}

// A track caching into `pool`, as a broadcast's tracks do.
function pooled(pool: cache.Pool, name = "test"): TrackProducer {
const producer = new TrackProducer(name);
hooks.poolTrack(producer, pool);
return producer.accept({ maxAge: null });
}

function finished(producer: TrackProducer, size: number): bigint {
const group = producer.appendGroup();
group.writeFrame({ payload: new Uint8Array(size) });
group.finish();
return group.sequence;
}

// The sequences a fresh subscriber is handed: what the track still caches. Its mirrors are
// released once its close settles.
async function cached(producer: TrackProducer): Promise<bigint[]> {
const subscriber = producer.subscribe({ delay: { max: null } });
const sequences: bigint[] = [];
for (let group = subscriber.tryRecvGroup(); group; group = subscriber.tryRecvGroup())
sequences.push(group.sequence);
subscriber.close();
await yieldNow();
return sequences;
}

// What one finished group of `size` payload bytes bills: its frame, the frame's own
// bookkeeping (group.ts `FRAME_BYTES`), and the group's.
const billed = (size: number) => size + 256 + cache.ENTRY_OVERHEAD;

// While the pool is over capacity, every append accrues debt and pays it by evicting the
// track's own oldest groups, so the newest content survives. Mirrors Rust `debt_evicts_oldest_group`.
test("debt evicts a track's oldest groups", async () => {
await withClock(async () => {
const pool = new cache.Pool({ capacity: 2 * billed(10_000) });
const producer = pooled(pool);
for (let i = 0; i < 4; i++) finished(producer, 10_000);

const left = await cached(producer);
expect(left).not.toContain(0n);
expect(left).toContain(3n);
// The protected live edge plus the group just demoted, since debt is charged before it.
expect(pool.used).toBeLessThanOrEqual(2 * billed(10_000));
});
});

// Far too small for one group, the pool still keeps the newest group whole. Mirrors Rust
// `latest_group_never_evicted`.
test("the newest group survives any capacity", async () => {
await withClock(async () => {
const pool = new cache.Pool({ capacity: 100 });
const producer = pooled(pool);
for (let i = 0; i < 3; i++) finished(producer, 1_000);
const left = await cached(producer);
expect(left).not.toContain(0n);
expect(left).toContain(2n);
const newest = producer.subscribe({ delay: { max: null }, ranges: [{ start: { absolute: 2n } }] });
expect((await newest.tryRecvGroup()?.readFrame())?.payload.length).toBe(1_000);
});
});

// A reader holding an evicted group's unread frames is told so, rather than hanging or
// reading a truncated clean end. Mirrors Rust `eviction_aborts_readers`.
test("eviction fails a reader's unread group with Evicted", async () => {
await withClock(async () => {
const pool = new cache.Pool({ capacity: billed(10_000) + cache.MIRROR_OVERHEAD });
const producer = pooled(pool);
const subscriber = producer.subscribe({ delay: { max: null } });
finished(producer, 10_000); // seq 0
const held = subscriber.tryRecvGroup();
finished(producer, 10_000); // seq 1: demotes seq 0
finished(producer, 10_000); // seq 2: pays by evicting seq 0
await expect(held?.readFrame()).rejects.toMatchObject({ code: StreamCode.Evicted });
subscriber.close();
});
});

// Debt too small to evict an old group carries over rather than shedding the live group's
// frames, which its reader has not taken yet. Mirrors Rust `carried_debt_keeps_the_live_group`.
test("carried debt keeps the live group", async () => {
await withClock(async () => {
const unit = 100 * cache.ENTRY_OVERHEAD;
const pool = new cache.Pool({ capacity: 22 * unit });
const producer = pooled(pool);
finished(producer, 20 * unit);

const group = producer.appendGroup();
const reader = group.consume();
for (let i = 0; i < 3; i++) group.writeFrame({ payload: new Uint8Array(unit) });
group.finish();
for (let i = 0; i < 3; i++) expect((await reader.readFrame())?.payload.length).toBe(unit);
expect(await reader.readFrame()).toBeUndefined();
});
});

// A read lifts a group's access above the pool's mean, so the eviction walk passes over it
// and evicts a never-read group instead, even one that arrived later. Mirrors Rust
// `fetch_refresh_survives_eviction`.
test("a read group outlives a later unread one", async () => {
await withClock(async (clock) => {
// Each group is mirrored to the reader too.
const pool = new cache.Pool({ capacity: Math.floor(3.5 * (billed(3_000) + cache.MIRROR_OVERHEAD)) });
const producer = pooled(pool);
const reader = producer.subscribe({ delay: { max: null } });

finished(producer, 3_000); // seq 0
await clock.advance(1_000);
finished(producer, 3_000); // seq 1
await clock.advance(1_000);
finished(producer, 3_000); // seq 2
await clock.advance(500);
const first = reader.tryRecvGroup();
expect(first?.sequence).toBe(0n);
expect((await first?.readFrame())?.payload.length).toBe(3_000);
await clock.advance(500);

finished(producer, 3_000); // seq 3
await clock.advance(1_000);
finished(producer, 3_000); // seq 4
reader.close();

const left = await cached(producer);
expect(left).toContain(0n);
expect(left).not.toContain(1n);
});
});

// Taking a group is a cache access: a reader handed one just inside the window can still read
// it almost a window later. Mirrors Rust `delivery_restarts_the_expiry_clock`.
test("delivery restarts a group's idle window", async () => {
await withClock(async (clock) => {
const pool = new cache.Pool({ expiry: Milli(10_000) });
const producer = pooled(pool);
const subscriber = producer.subscribe({ delay: { max: null } });
finished(producer, 1); // seq 0
finished(producer, 1); // seq 1 takes the live edge, so seq 0 can expire

await clock.advance(9_000);
const reading = subscriber.tryRecvGroup();
expect(reading?.sequence).toBe(0n);
// Far beyond the write, inside the delivery. The new group runs the expiry scan.
await clock.advance(9_000);
finished(producer, 1);
expect((await reading?.readFrame())?.payload.length).toBe(1);
subscriber.close();
});
});

// Every track of a broadcast caches into one pool, and the mean access across all of them
// orders eviction: a track writing past the capacity pays with its own groups, but only those
// accessed no later than the mean, so a fresher track's groups survive its own debt while a
// staler track's write evicts its oldest at double rate.
test("a shared capacity spares a fresher track and evicts a staler one's oldest", async () => {
await withClock(async (clock) => {
const pool = new cache.Pool({ capacity: 6 * billed(10_000) });
const open = (producer: TrackProducer) => {
const group = producer.appendGroup();
group.writeFrame({ payload: new Uint8Array(10_000) });
return group;
};
const staler = pooled(pool, "staler");
const old = [open(staler), open(staler), open(staler), open(staler)];

await clock.advance(10_000);
const fresher = pooled(pool, "fresher");
const reader = fresher.subscribe({ delay: { max: null } });
const read = [];
for (let i = 0; i < 4; i++) {
read.push(open(fresher));
expect((await reader.tryRecvGroup()?.readFrame())?.payload.length).toBe(10_000);
}
expect(pool.used).toBeGreaterThan(6 * billed(10_000));
for (const group of read) expect(group.closed.peek()).toBeUndefined();

open(staler);
// One write's worth of debt, doubled: two groups.
expect(old[0].closed.peek()).toMatchObject({ code: StreamCode.Evicted });
expect(old[1].closed.peek()).toMatchObject({ code: StreamCode.Evicted });
expect(old[2].closed.peek()).toBeUndefined();
for (const group of read) expect(group.closed.peek()).toBeUndefined();
reader.close();
});
});

// The pool's sweep reclaims every track's idle groups with no write behind it, the live edges
// excepted, and leaves only what those still bill. Mirrors Rust `pool_sweep_expires_without_a_write`.
test("the sweep expires idle groups across tracks without a write", async () => {
await withClock(async (clock) => {
const pool = new cache.Pool({ expiry: Milli(1_000) });
const tracks = [pooled(pool, "a"), pooled(pool, "b")];
const stalled = tracks.map((track) => {
const group = track.appendGroup(); // left open
group.writeFrame({ payload: new Uint8Array(1) });
finished(track, 1); // the live edge
return group;
});

await clock.advance(1_000);
for (const group of stalled) expect(group.closed.peek()).toBeUndefined();
await clock.advance(1_000 + 500);
for (const group of stalled) expect(group.closed.peek()).toBeInstanceOf(TooFarBehind);
for (const track of tracks) expect(await cached(track)).toEqual([1n]);
expect(pool.used).toBe(2 * billed(1));
});
});

// Every byte a group bills, its subscribers' mirrors included, goes back once it leaves.
test("the pool is billed only for what is cached", async () => {
await withClock(async (clock) => {
const pool = new cache.Pool({ expiry: Milli(1_000) });
const producer = pooled(pool);
const subscriber = producer.subscribe({ delay: { max: null } });
finished(producer, 100);
expect(pool.used).toBe(billed(100) + cache.MIRROR_OVERHEAD);
subscriber.close();
await yieldNow();
expect(pool.used).toBe(billed(100));

producer.finish();
producer.close();
await clock.advance(3_000);
expect(pool.used).toBe(0);
});
});

// The group's own tail limit still sheds its front, and the pool is credited for it.
test("a group's tail limit releases what it sheds from the pool", async () => {
await withClock(() => {
const pool = new cache.Pool();
const producer = pooled(pool);
const group = producer.appendGroup();
const frame = new Uint8Array(1024 * 1024);
for (let i = 0; i < 40; i++) group.writeFrame({ payload: frame });
expect(hooks.groupCacheBytes(group)).toBeLessThanOrEqual(32 * 1024 * 1024);
expect(pool.used).toBe(hooks.groupCacheBytes(group) + cache.ENTRY_OVERHEAD);
});
});

// With nothing evictable, the debt sheds the live edge's front, keeping the newest frame, so
// an open group a track only appends frames to stays near the capacity.
test("the debt sheds the front of an open live edge", async () => {
await withClock(async () => {
const capacity = 1024 * 1024;
const pool = new cache.Pool({ capacity });
const producer = pooled(pool);
const reader = producer.subscribe({ delay: { max: null } });
const group = producer.appendGroup();
const behind = reader.tryRecvGroup();
const frame = new Uint8Array(64 * 1024);
for (let i = 0; i < 64; i++) group.writeFrame({ payload: frame });

expect(group.closed.peek()).toBeUndefined();
// What a frame write may add before it settles, on top of the capacity.
expect(pool.used).toBeLessThanOrEqual(capacity + 512 * 1024);
// A reader that never read lost the shed front.
await expect(behind?.readFrame()).rejects.toThrow();
});
});
Loading
Loading