@pylonsync/realtime 0.14.0

package/src/clock.test.ts

@@ -0,0 +1,143 @@
+import { describe, expect, test } from "bun:test";
+
+import { ShardClock } from "./clock";
+
+/** A deterministic jitter source in [0, 1). */
+function rng(seed: number) {
+  let s = seed >>> 0;
+  return () => {
+    s = (s * 1664525 + 1013904223) >>> 0;
+    return s / 2 ** 32;
+  };
+}
+
+/**
+ * Frames for ticks `from..to` at 20 Hz, built at `tick * 50` ms, arriving
+ * after `latency` plus up to `jitter` ms.
+ */
+function feed(
+  clock: ShardClock,
+  from: number,
+  to: number,
+  latency: number,
+  jitter: number,
+  seed = 1,
+) {
+  const r = rng(seed);
+  for (let tick = from; tick <= to; tick++) clock.observe(tick, tick * 50 + latency + r() * jitter);
+}
+
+describe("ShardClock", () => {
+  test("is not ready before a frame", () => {
+    const clock = new ShardClock();
+    expect(clock.ready).toBe(false);
+    expect(clock.serverTick(1000)).toBe(-1);
+  });
+
+  test("anchors on the least-delayed frame, so jitter does not move it", () => {
+    const clock = new ShardClock({ tickRate: 20 });
+    feed(clock, 1, 200, 40, 60);
+    // At time t the newest tick that could have arrived was built at
+    // t - 40 ms (the smallest delay seen is close to 40).
+    const est = clock.serverTick(200 * 50 + 40 + 25);
+    expect(est).toBeGreaterThan(200.3);
+    expect(est).toBeLessThan(200.6);
+  });
+
+  test("measures the tick length when the rate is unknown", () => {
+    const clock = new ShardClock();
+    const r = rng(7);
+    for (let tick = 1; tick <= 128; tick++) clock.observe(tick, tick * 33.3 + 20 + r() * 15);
+    expect(clock.tickMs).toBeGreaterThan(32.8);
+    expect(clock.tickMs).toBeLessThan(33.8);
+  });
+
+  test("never goes backwards when a correction arrives", () => {
+    const clock = new ShardClock({ tickRate: 20 });
+    feed(clock, 1, 64, 100, 0);
+    let t = 64 * 50 + 100;
+    let prev = clock.serverTick(t);
+    // Latency drops by 60 ms: the estimate must move ahead, gradually.
+    for (let tick = 65; tick <= 200; tick++) {
+      clock.observe(tick, tick * 50 + 40);
+      for (let step = 0; step < 3; step++) {
+        t += 50 / 3;
+        const now = clock.serverTick(t);
+        expect(now).toBeGreaterThan(prev);
+        prev = now;
+      }
+    }
+    // It converged on the new, lower latency.
+    expect(clock.serverTick(200 * 50 + 40)).toBeCloseTo(200, 1);
+  });
+
+  test("follows a shard whose ticks resume late after a stall", () => {
+    const clock = new ShardClock({ tickRate: 20 });
+    feed(clock, 1, 40, 50, 0);
+    // The tick loop stalled for 2 s, then kept its tick numbers going.
+    for (let tick = 41; tick <= 43; tick++) clock.observe(tick, tick * 50 + 50 + 2000);
+    expect(clock.serverTick(43 * 50 + 50 + 2000)).toBeCloseTo(43, 1);
+  });
+
+  test("one late frame is jitter", () => {
+    const clock = new ShardClock({ tickRate: 20 });
+    feed(clock, 1, 40, 50, 0);
+    clock.observe(41, 41 * 50 + 50 + 2000);
+    clock.observe(42, 42 * 50 + 50);
+    expect(clock.serverTick(42 * 50 + 50)).toBeCloseTo(42, 1);
+  });
+
+  test("a burst after a network stall catches up to the newest tick", () => {
+    const clock = new ShardClock({ tickRate: 20 });
+    feed(clock, 1, 40, 50, 0);
+    // Ticks 41..80 were built on time but arrive together, 2 s late.
+    const at = 40 * 50 + 50 + 2000;
+    for (let tick = 41; tick <= 80; tick++) clock.observe(tick, at);
+    // Within a tick at once; the rest is spread over the next second.
+    expect(clock.serverTick(at)).toBeGreaterThan(78.9);
+    expect(clock.serverTick(at + 1500)).toBeCloseTo(110, 1);
+  });
+
+  for (const tickRate of [20, undefined]) {
+    test(`a network burst neither moves it back nor throws it off (rate ${tickRate ?? "measured"})`, () => {
+      const clock = new ShardClock({ tickRate });
+      const r = rng(3);
+      let prev = -Infinity;
+      let worst = 0;
+      for (let tick = 1; tick <= 300; tick++) {
+        const built = tick * 50;
+        // Ticks 100..107 are held up by a 400 ms stall and arrive together.
+        const at = tick >= 100 && tick <= 107 ? 107 * 50 + 50 : built + 50 + r() * 10;
+        clock.observe(tick, at);
+        const est = clock.serverTick(at);
+        expect(est).toBeGreaterThanOrEqual(prev);
+        prev = est;
+        // The truth at `at`: the tick being built then, less the least delay.
+        if (tick > 120) worst = Math.max(worst, Math.abs(est - (at - 50) / 50));
+      }
+      expect(worst).toBeLessThan(1);
+      expect(clock.tickMs).toBeGreaterThan(47);
+      expect(clock.tickMs).toBeLessThan(53);
+    });
+  }
+
+  test("after a stall it steps back no further than the newest tick received", () => {
+    const clock = new ShardClock({ tickRate: 20 });
+    feed(clock, 1, 40, 50, 0);
+    const before = clock.serverTick(40 * 50 + 50 + 1999);
+    expect(before).toBeGreaterThan(79);
+    for (let tick = 41; tick <= 43; tick++) {
+      const at = tick * 50 + 50 + 2000;
+      clock.observe(tick, at);
+      expect(clock.serverTick(at)).toBeGreaterThanOrEqual(tick - 1);
+    }
+  });
+
+  test("ticks that go back (a restarted shard) reset it", () => {
+    const clock = new ShardClock({ tickRate: 20 });
+    feed(clock, 1000, 1010, 30, 0);
+    clock.observe(3, 999_999);
+    expect(clock.latestTick).toBe(3);
+    expect(clock.serverTick(999_999)).toBeCloseTo(3);
+  });
+});

package/src/clock.ts

@@ -0,0 +1,206 @@
+/**
+ * An estimate of the shard's current tick, from the ticks in the frames it
+ * sends and when they arrive.
+ *
+ * Each frame carries the tick it was built on. The frame that arrived
+ * soonest after it was built (lowest delay) anchors the estimate, so
+ * network jitter only ever makes a frame look late. The tick length is the
+ * shard's tick rate when the client knows it, or else the median slope of
+ * arrival time against tick.
+ *
+ * The estimate is continuous: when a new frame moves it, the change is
+ * spread over time instead of jumping (from `slew` of real time for small
+ * changes up to all of it). A step forward larger than `snapMs` applies at
+ * once. A step back larger than that applies only as far as the newest
+ * tick received, so it never goes back past a tick a frame carried.
+ *
+ * After three frames in a row arrive more than `snapMs` late and spaced
+ * like ticks (a shard that stalled), the older frames are dropped and the
+ * clock follows the new schedule. Frames that arrive together (a network
+ * burst) do not count.
+ */
+
+export interface ShardClockOptions {
+  /** The shard's tick rate in ticks per second, when the client knows it. */
+  tickRate?: number;
+  /** Frames the estimate uses. Default 64. */
+  window?: number;
+  /** The least fraction of real time the estimate speeds up or slows
+   *  down by to absorb a correction. Default 0.05. */
+  slew?: number;
+  /** A step forward larger than this (ms) applies at once, and a
+   *  correction this large or larger runs at full rate. Default 250. */
+  snapMs?: number;
+}
+
+interface Sample {
+  tick: number;
+  at: number;
+}
+
+const DEFAULT_TICK_MS = 50;
+/** Late frames in a row that mean the schedule moved. */
+const LATE_FRAMES = 3;
+/** Samples the tick length is measured from; fewer keep the last value. */
+const MIN_FIT_SAMPLES = 8;
+
+export class ShardClock {
+  private readonly fixedTickMs: number | null;
+  private readonly window: number;
+  private readonly slew: number;
+  private readonly snapMs: number;
+  private samples: Sample[] = [];
+  private measuredTickMs = DEFAULT_TICK_MS;
+  /** The newest tick seen, and the estimated arrival time of a frame for
+   *  it with the lowest delay seen. */
+  private anchorTick = -1;
+  private anchorAt = 0;
+  /** Ticks the displayed estimate is ahead of the raw one; decays to 0. */
+  private offset = 0;
+  private slewedTo = 0;
+  /** Frames in a row that arrived more than `snapMs` after the anchor
+   *  predicted. */
+  private late = 0;
+
+  constructor(options: ShardClockOptions = {}) {
+    const rate = options.tickRate;
+    this.fixedTickMs = rate !== undefined && rate > 0 && Number.isFinite(rate) ? 1000 / rate : null;
+    this.window = Math.max(2, options.window ?? 64);
+    this.slew = Math.min(0.5, Math.max(0, options.slew ?? 0.05));
+    this.snapMs = options.snapMs ?? 250;
+  }
+
+  /** True once a frame has arrived. */
+  get ready(): boolean {
+    return this.anchorTick >= 0;
+  }
+
+  /** The newest tick a frame carried, or -1. */
+  get latestTick(): number {
+    return this.anchorTick;
+  }
+
+  /** Milliseconds per tick: the configured rate, or the measured one. */
+  get tickMs(): number {
+    return this.fixedTickMs ?? this.measuredTickMs;
+  }
+
+  /** Forget everything (a new shard). */
+  reset(): void {
+    this.samples = [];
+    this.measuredTickMs = DEFAULT_TICK_MS;
+    this.anchorTick = -1;
+    this.anchorAt = 0;
+    this.offset = 0;
+    this.slewedTo = 0;
+    this.late = 0;
+  }
+
+  /** Record a frame for `tick` that arrived at `at` (ms, monotonic). */
+  observe(tick: number, at: number): void {
+    if (tick < this.anchorTick) {
+      // Ticks went back: the shard restarted, or this is another shard.
+      this.reset();
+    }
+    const shown = this.ready ? this.serverTick(at) : null;
+    const newestBefore = this.anchorTick;
+
+    // The shard's schedule moved later (it stalled, or the path got
+    // slower for good) when several frames in a row arrive late by more
+    // than `snapMs`, spaced like ticks. One late frame is jitter, and
+    // frames that arrive together are a network burst: the shard kept its
+    // schedule. After a move, the samples from before it would anchor the
+    // estimate too early, so they go.
+    const prev = this.samples[this.samples.length - 1];
+    if (this.ready && prev && tick > prev.tick) {
+      const expected = this.anchorAt + (tick - this.anchorTick) * this.tickMs;
+      const spaced = at - prev.at >= 0.5 * this.tickMs * (tick - prev.tick);
+      this.late = spaced && at - expected > this.snapMs ? this.late + 1 : 0;
+      if (this.late >= LATE_FRAMES) {
+        this.samples = this.samples.slice(-(LATE_FRAMES - 1));
+        this.late = 0;
+      }
+    }
+
+    const last = this.samples[this.samples.length - 1];
+    if (last && last.tick === tick) {
+      // Another frame for the same tick: keep the earlier arrival.
+      if (at >= last.at) return;
+      last.at = at;
+    } else {
+      this.samples.push({ tick, at });
+      if (this.samples.length > this.window) this.samples.shift();
+    }
+    if (this.fixedTickMs === null) this.fitTickMs();
+
+    const tickMs = this.tickMs;
+    let anchorAt = Infinity;
+    for (const s of this.samples) {
+      anchorAt = Math.min(anchorAt, s.at + (tick - s.tick) * tickMs);
+    }
+    this.anchorTick = tick;
+    this.anchorAt = anchorAt;
+
+    if (shown === null) {
+      this.offset = 0;
+    } else {
+      // Keep what a render loop sees continuous; `serverTick` decays the
+      // difference. A large step forward applies at once. A large step
+      // back applies only down to the newest tick received before this
+      // frame: past it the estimate had run ahead of every frame (a shard
+      // that stalled), so nothing drawn goes back.
+      const raw = this.raw(at);
+      this.offset = shown - raw;
+      if (Math.abs(this.offset) * tickMs > this.snapMs) {
+        this.offset = this.offset > 0 ? Math.max(0, Math.min(shown, newestBefore) - raw) : 0;
+      }
+    }
+    this.slewedTo = Math.max(this.slewedTo, at);
+  }
+
+  /**
+   * The estimated tick the shard is on at `now` (ms, same clock as
+   * `observe`), with a fraction. Before the first frame, -1.
+   */
+  serverTick(now: number): number {
+    if (!this.ready) return -1;
+    const elapsed = now - this.slewedTo;
+    if (elapsed > 0) {
+      // The correction runs faster the larger it is, from `slew` up to
+      // all of real time (the estimate stands still, or runs at double
+      // speed).
+      const offsetMs = Math.abs(this.offset) * this.tickMs;
+      const rate = Math.min(1, Math.max(this.slew, offsetMs / this.snapMs));
+      const step = (elapsed * rate) / this.tickMs;
+      this.offset -= Math.max(-step, Math.min(step, this.offset));
+      this.slewedTo = now;
+    }
+    return this.raw(now) + this.offset;
+  }
+
+  private raw(now: number): number {
+    return this.anchorTick + (now - this.anchorAt) / this.tickMs;
+  }
+
+  /**
+   * The median slope of arrival time against tick over every pair of
+   * samples (Theil-Sen): frames that arrive together in a burst are a
+   * minority of pairs and do not pull it.
+   */
+  private fitTickMs(): void {
+    const n = this.samples.length;
+    if (n < MIN_FIT_SAMPLES) return;
+    if (this.samples[n - 1].tick - this.samples[0].tick < 4) return;
+    const slopes: number[] = [];
+    for (let i = 0; i < n; i++) {
+      for (let j = i + 1; j < n; j++) {
+        const dt = this.samples[j].tick - this.samples[i].tick;
+        if (dt > 0) slopes.push((this.samples[j].at - this.samples[i].at) / dt);
+      }
+    }
+    if (slopes.length === 0) return;
+    slopes.sort((a, b) => a - b);
+    const slope = slopes[slopes.length >> 1];
+    if (Number.isFinite(slope)) this.measuredTickMs = Math.min(2000, Math.max(1, slope));
+  }
+}

package/src/connection.test.ts

@@ -0,0 +1,80 @@
+import { afterAll, beforeAll, expect, test } from "bun:test";
+
+import { connectShard } from "./connection";
+
+const sockets: FakeWebSocket[] = [];
+class FakeWebSocket {
+  static OPEN = 1;
+  readyState = 0;
+  binaryType = "blob";
+  onopen: (() => void) | null = null;
+  onmessage: ((e: { data: ArrayBuffer }) => void) | null = null;
+  onerror: (() => void) | null = null;
+  onclose: (() => void) | null = null;
+  constructor(
+    readonly url: string,
+    readonly protocols?: string[],
+  ) {
+    sockets.push(this);
+  }
+  close() {
+    this.readyState = 3;
+    this.onclose?.();
+  }
+  send() {}
+}
+
+const realWebSocket = globalThis.WebSocket;
+const realSetTimeout = globalThis.setTimeout;
+const delays: number[] = [];
+beforeAll(() => {
+  globalThis.WebSocket = FakeWebSocket as unknown as typeof WebSocket;
+  globalThis.setTimeout = ((fn: () => void, ms: number) => {
+    delays.push(ms);
+    queueMicrotask(fn);
+    return 0;
+  }) as unknown as typeof setTimeout;
+});
+afterAll(() => {
+  globalThis.WebSocket = realWebSocket;
+  globalThis.setTimeout = realSetTimeout;
+});
+
+const settle = () => new Promise((r) => realSetTimeout(r, 0));
+
+test("a ticket function gives each connection attempt a new ticket", async () => {
+  let n = 0;
+  const errors: string[] = [];
+  const client = connectShard("zone", {
+    subscriberId: "p1",
+    baseUrl: "h",
+    ticket: async () => {
+      n += 1;
+      if (n === 2) throw new Error("ticket service down");
+      return `t${n}`;
+    },
+  });
+  client.onError((e) => errors.push(e.message));
+  await settle();
+  expect(sockets[0].protocols).toEqual(["ticket.t1"]);
+
+  // The socket drops; the next ticket fails, so it retries with backoff.
+  sockets[0].close();
+  await settle();
+  await settle();
+  expect(errors).toContain("ticket service down");
+  expect(sockets.length).toBe(2);
+  expect(sockets[1].protocols).toEqual(["ticket.t3"]);
+  expect(delays).toEqual([500, 1000]);
+  client.close();
+});
+
+test("send returns 0 and sends nothing while the socket is not open", () => {
+  const errors: string[] = [];
+  const client = connectShard("zone", { subscriberId: "p1", baseUrl: "h", ticket: "fixed" });
+  client.onError((e) => errors.push(e.message));
+  expect(sockets[sockets.length - 1].protocols).toEqual(["ticket.fixed"]);
+  expect(client.send({ a: 1 })).toBe(0);
+  expect(errors[0]).toContain("not open");
+  client.close();
+});