Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
18365ab
chore(quest): claim quest/m1/drop-set.md
kixelated Nov 8, 2026
21446a2
wip(net): bill the track drop set to the cache pool
kixelated Nov 8, 2026
111035b
wip(net): mirror the billed drop set in js/net, incremental cursor folds
kixelated Nov 8, 2026
043d28c
fix(net): bill and bound the track drop set, and fold drops increment…
kixelated Nov 8, 2026
20e0647
fix(net): a local track keeps the drops its declared end relies on
kixelated Nov 8, 2026
ebb880c
quest: drop set keeps only the per-cursor record, still-to-cover item…
kixelated Nov 9, 2026
0dbf96a
fix(net): a kept drop run is reclaimable once its edge passes or its …
kixelated Nov 9, 2026
c8d2067
fix(js/net): a track drop or skip wins over a reader's own refusal
kixelated Nov 9, 2026
36663c6
fix(js/net): only a drop that settles the reader hides its refusal
kixelated Nov 9, 2026
ca0de2b
fix(moq-net): hold the drop-set bench's run and record counts steady
kixelated Nov 9, 2026
66c0b09
Merge remote-tracking branch 'origin/main' into HEAD
kixelated Nov 9, 2026
101be34
fix(moq-net): address review of the drop set's billing and folds
kixelated Nov 9, 2026
96a994f
fix(moq-net): keep a reached end reached when its drops are reclaimed
kixelated Nov 9, 2026
dc0a7e8
fix(net): account a reclaimed drop run in the arrivals, and rejudge f…
kixelated Nov 9, 2026
c9e13cb
style: format the reclaim accounting
kixelated Nov 9, 2026
2bf8648
test(moq-net): satisfy clippy in the forget log test
kixelated Nov 9, 2026
baf9e09
fix(net): a received end's tail decides it in JS too, and drop billin…
kixelated Nov 9, 2026
1f5f69b
Merge remote-tracking branch 'origin/main' into quest/m1/drop-set
kixelated Nov 9, 2026
3d8272e
test(moq-net): finish the fill-refusal test's track through a shared …
kixelated Nov 9, 2026
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
167 changes: 165 additions & 2 deletions js/net/src/cache.test.ts
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
import { expect, test } from "bun:test";
import { Duration, Manual, yieldNow } from "@moq/clock";
import * as cache from "./cache.ts";
import { StreamCode, TooFarBehind } from "./error.ts";
import { hooks } from "./internal.ts";
import { StreamCode, StreamError, TooFarBehind } from "./error.ts";
import { hooks, staleHole } from "./internal.ts";
import { Producer as TrackProducer } from "./track.ts";

// Run `fn` on a manual clock, stepped in milliseconds.
Expand Down Expand Up @@ -274,3 +274,166 @@ test("the debt sheds the front of an open live edge", async () => {
await expect(behind?.readFrame()).rejects.toThrow();
});
});

// Every run a fresh reader of `producer` is told was given up: what the track still holds.
function dropsHeld(producer: TrackProducer): bigint[] {
const reader = producer.subscribe({ delay: { max: null } });
const held: bigint[] = [];
for (let run = hooks.tryDrop(reader); run; run = hooks.tryDrop(reader)) held.push(run.start);
reader.close();
return held;
}

const old = () => ({ error: new StreamError(StreamCode.Old) });

// A drop-only flood of disjoint runs bills the pool and sheds its lowest runs to stay within it,
// with no cached group to evict; a shed run is unknown again, so a reader reports only the runs
// the track still holds. Mirrors Rust `a_drop_flood_stays_within_the_pool`.
test("a drop flood stays within the pool", () => {
const runs = 1000n;
const capacity = 64 * cache.RUN_OVERHEAD;
const pool = new cache.Pool({ capacity });
const producer = pooled(pool);
hooks.receiveTrack(producer);
const reader = producer.subscribe({ delay: { max: null } });
const reported: bigint[] = [];
for (let run = 0n; run < runs; run++) {
hooks.dropTrackGroups(producer, 2n * run, 2n * run + 1n, old());
expect(pool.used).toBeLessThanOrEqual(capacity + 2 * cache.RUN_OVERHEAD);
// Midway, the reader takes in every run held then and reports the lowest; the rest are
// shed before it reports them.
if (run === runs / 2n) {
const first = hooks.tryDrop(reader);
if (!first) throw new Error("a run is owed");
reported.push(first.start);
}
}
const held = dropsHeld(producer);
expect(pool.used).toBe(held.length * cache.RUN_OVERHEAD);
expect(held[0]).toBeGreaterThan(0n);
expect(held.every((start, i) => i === 0 || start === held[i - 1] + 2n)).toBe(true);
expect(held[held.length - 1]).toBe(2n * (runs - 1n));
for (let run = hooks.tryDrop(reader); run; run = hooks.tryDrop(reader)) reported.push(run.start);
expect(reported.slice(1)).toEqual(held);
});

// A run given up longer than the pool's idle window ago is forgotten by the sweep, even on a
// track that caches nothing, and a run given up since stays. Mirrors Rust
// `the_sweep_forgets_runs_past_the_expiry_window`.
test("the sweep forgets runs past the idle window", async () => {
await withClock(async (clock) => {
const pool = new cache.Pool({ expiry: Duration.millis(1_000) });
const producer = pooled(pool);
hooks.receiveTrack(producer);
// A local track keeps what it skipped above its newest group, which its end relies on.
const local = pooled(pool, "local");
local.skipGroups(5n, 10n);
hooks.dropTrackGroups(producer, 0n, 1n, old());
hooks.dropTrackGroups(producer, 2n, 3n, old());
await clock.advance(500);
hooks.dropTrackGroups(producer, 4n, 5n, old());
// Each run and its expiry are billed.
expect(pool.used).toBe(4 * (cache.RUN_OVERHEAD + cache.BORN_OVERHEAD));

// The sweep at 1.5 s forgets the first two, given up at 0 s.
await clock.advance(1_000);
expect(dropsHeld(producer)).toEqual([4n]);
expect(pool.used).toBe(2 * (cache.RUN_OVERHEAD + cache.BORN_OVERHEAD));

await clock.advance(1_000);
expect(dropsHeld(producer)).toEqual([]);
expect(dropsHeld(local)).toEqual([5n]);
expect(pool.used).toBe(cache.RUN_OVERHEAD + cache.BORN_OVERHEAD);
});
});

// A local skip kept above the track's edge is dated once the edge passes it, or once the track
// closes, so an expiry scan past its window forgets it with no other drop to rearm it, and its
// bill leaves the pool. Mirrors Rust `a_kept_local_skip_expires_once_the_edge_passes_it`; Rust
// frees a closed track's drops with its state.
test("a kept local skip expires once the edge passes it or the track closes", async () => {
await withClock(async (clock) => {
const pool = new cache.Pool({ expiry: Duration.millis(1_000) });
const passed = pooled(pool);
const closed = pooled(pool, "closed");
passed.skipGroups(0n, 10n);
closed.skipGroups(0n, 10n);
await clock.advance(3_000);
expect(dropsHeld(passed)).toEqual([0n]);
expect(dropsHeld(closed)).toEqual([0n]);

// The write's own expiry scan finds the skip.
passed.createGroup(10n).finish();
expect(dropsHeld(passed)).toEqual([]);

const used = pool.used;
closed.close();
expect(pool.used).toBe(used - cache.RUN_OVERHEAD - cache.BORN_OVERHEAD);
});
});

// A received stale run the pool forgets is accounted for, as an evicted group is: no reader waits
// on it from the live feed, so a reader that wants it asks a fill. Mirrors Rust
// `a_reader_asks_a_fill_for_a_forgotten_run_it_judged`.
test("a forgotten stale run is asked of a fill", async () => {
await withClock(async (clock) => {
const pool = new cache.Pool({ expiry: Duration.millis(1_000) });
const producer = pooled(pool);
hooks.receiveTrack(producer);
const requests = producer.requests();
producer.createGroup(0n).finish();
hooks.dropTrackGroups(producer, 1n, 3n, staleHole(500));
producer.createGroup(3n).finish();
await clock.advance(2_000);

const reader = producer.subscribe({
ranges: [{ start: { absolute: 1n } }],
delay: { max: Duration.millis(60_000) },
order: "ascending",
});
// The live group first, in arrival order; the next read asks for what it misses.
expect((await reader.recvGroup())?.sequence).toBe(3n);
const next = reader.recvGroup();
const asked: bigint[][] = [];
for (;;) {
const fill = await Promise.race([requests.requestedFill(), yieldNow().then(() => undefined)]);
if (!fill) break;
asked.push([fill.start, fill.end]);
}
expect(asked).toEqual([[1n, 3n]]);

reader.close();
requests.close();
await next.catch(() => undefined);
});
});

// A received copy that reached its end through a skip stays ended once the pool forgets the skip,
// since the forgotten run stays accounted for. Mirrors Rust
// `a_reached_end_outlives_its_expired_drops`.
test("a reached end outlives its forgotten skip", async () => {
await withClock(async (clock) => {
const pool = new cache.Pool({ expiry: Duration.millis(1_000) });
const producer = pooled(pool);
hooks.receiveTrack(producer);
producer.createGroup(0n).finish();
hooks.skipTrackGroups(producer, 1n, 3n);
hooks.endTrack(producer, { group: 3n, frame: 0 });
const done = (reader: ReturnType<TrackProducer["subscribe"]>) => {
for (let recv = hooks.tryRecvGroup(reader, false); ; recv = hooks.tryRecvGroup(reader, false)) {
if (recv.kind !== "group") return recv.kind;
recv.group.close();
}
};
const reader = producer.subscribe({ delay: { max: Duration.millis(60_000) } });
expect(done(reader)).toBe("done");

await clock.advance(3_000);
expect(dropsHeld(producer)).toEqual([]);
expect(done(reader)).toBe("done");
const late = producer.subscribe({ delay: { max: Duration.millis(60_000) } });
expect(done(late)).toBe("done");
reader.close();
late.close();
});
});
44 changes: 40 additions & 4 deletions js/net/src/cache.ts
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,12 @@ export const DEFAULT_EXPIRY = Duration.millis(30_000);
export const ENTRY_OVERHEAD = 3 * 1024;
/** Bookkeeping billed per subscriber mirror a cached group holds. */
export const MIRROR_OVERHEAD = 4 * 1024;
// Bun 1.4's heap grows about 334 bytes per disjoint run of a track's drop set, its change-log
// entry included, and about 53 more per entry of the expiry index a pool with an idle window keeps.
/** Bookkeeping billed per run of a track's drop set. */
export const RUN_OVERHEAD = 336;
/** Bookkeeping billed per entry of a drop set's expiry index. */
export const BORN_OVERHEAD = 64;

// The coarse clock behind access stamps, as Rust's: the expiry window rounds up to it.
const TICK = Duration.millis(100);
Expand Down Expand Up @@ -227,6 +233,12 @@ export interface Owner<E extends Entry> {
shed(entry: E, debt: number, cap: number): number;
/** Something was evicted: settle what the cache's contents decide. */
settle(): void;
/** Forget the lowest runs of the track's drop set toward `debt`, freeing about `cap` at most, and return the bytes freed. */
shedDrops(debt: number, cap: number): number;
/** Forget the runs of the drop set given up longer than the pool's idle window before tick `now`, returning whether any went. */
expireDrops(now: number): boolean;
/** Whether the track holds a drop run a reclaim may forget, which keeps its account in the idle sweep. */
holdsDrops(): boolean;
}

/**
Expand Down Expand Up @@ -269,6 +281,18 @@ export class Track<E extends Entry> {
this.#written += n;
}

/** Bill `n` bytes the track keeps beside its groups, such as its drop set, which the idle sweep then visits. */
bill(n: number): void {
this.pool.add(n);
this.wrote(n);
if (this.#owner.holdsDrops()) this.pool.register(this as Track<Entry>);
}

/** Release `n` bytes {@link bill} billed. */
unbill(n: number): void {
this.pool.sub(n);
}

/** Whether the account caches any group. */
get empty(): boolean {
return this.#live.size === 0;
Expand Down Expand Up @@ -299,8 +323,10 @@ export class Track<E extends Entry> {
if (this.#live.size === 0) {
this.#order = [];
this.#head = 0;
this.#debt = 0;
this.pool.unregister(this as Track<Entry>);
if (!this.#owner.holdsDrops()) {
this.#debt = 0;
this.pool.unregister(this as Track<Entry>);
}
}
}

Expand Down Expand Up @@ -375,6 +401,13 @@ export class Track<E extends Entry> {
evicted = true;
this.#owner.evict(entry, "evicted");
}
// Then the drop set, oldest sequences first: losing a run costs a reader a judgment or a
// fill, never content being read.
if (this.#debt > 0 && paid < cap) {
const freed = this.#owner.shedDrops(this.#debt, cap - paid);
this.#debt -= Math.min(freed, this.#debt);
paid += freed;
}
const edge = this.#owner.edge();
if (edge) fresh.push(edge);
for (const entry of fresh) {
Expand All @@ -397,8 +430,10 @@ export class Track<E extends Entry> {
const order = this.#order;
const head = this.#head;
const len = order.length - head;
if (expiry === undefined || len === 0) return false;
if (expiry === undefined) return false;
const now = this.pool.now();
const forgot = this.#owner.expireDrops(now);
if (len === 0) return forgot;
const start = full ? 0 : this.#cursor % len;
const width = full ? len : Math.min(len, EVICT_SCAN);
if (!full) this.#cursor = start + width;
Expand All @@ -410,7 +445,7 @@ export class Track<E extends Entry> {
}
for (const entry of expired) this.#owner.evict(entry, "expired");
this.#compact();
return expired.length > 0;
return expired.length > 0 || forgot;
}

// Skip the empty slots at the front of the order, and rebuild it once the slots before the
Expand Down Expand Up @@ -441,6 +476,7 @@ export class Track<E extends Entry> {
sweep(): void {
if (this.evictExpired(true)) this.#owner.settle();
// A live edge alone never expires, so it needs no sweep to keep its track alive for.
if (this.#owner.holdsDrops()) return;
for (const entry of this.#live.keys()) if (!this.#owner.protects(entry)) return;
this.pool.unregister(this as Track<Entry>);
}
Expand Down
35 changes: 35 additions & 0 deletions js/net/src/drops.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
import { expect, test } from "bun:test";
import { Runs } from "./drops.ts";
import type { Run } from "./internal.ts";

type Tagged = Run & { tag: number };

function filled(): Runs<Tagged> {
const runs = new Runs<Tagged>((a, b) => a.tag === b.tag);
for (let i = 0n; i < 8n; i++) runs.set(i * 10n, i * 10n + 5n, { start: 0n, end: 0n, tag: Number(i % 2n) });
return runs;
}

test("drops: clearing ranges in one pass matches clearing each", () => {
// Whole runs, a run split in two, a prefix, a suffix, and a range spanning runs and gaps.
const ranges: Run[] = [
{ start: 0n, end: 5n },
{ start: 11n, end: 13n },
{ start: 20n, end: 22n },
{ start: 24n, end: 31n },
{ start: 42n, end: 65n },
];
const each = filled();
for (const { start, end } of ranges) each.set(start, end);
const bulk = filled();
const { removed, added } = bulk.clear(ranges);
expect(bulk.all).toEqual(each.all);
expect(removed.map((run) => run.start)).toEqual([0n, 10n, 20n, 30n, 40n, 50n, 60n]);
expect(added.map((run) => [run.start, run.end])).toEqual([
[10n, 11n],
[13n, 15n],
[22n, 24n],
[31n, 35n],
[40n, 42n],
]);
});
Loading
Loading