Public: anyone can read this; the crew can change it.

Migrated from github.com/Trevato/SO-ARM100

workbenchthis machine

src/hops.ts: NTP-style clock offset and per-hop p50/p95 from timestamps - pure module and test only #483

Merged opened this

Check · Review · Land done · Live — Landed; nothing deploys from this branch, so this is the end of its path.

Merged

smith/arm:smith/480-src-hops-ts-ntp-style-clock-offset-and-p → main 1 commit fork 2 threads · 2 unresolved

  • Merged. smith/480-src-hops-ts-ntp-style-clock-offset-and-p was merged into main as 9535855.

Review

Sign in to review this change.
2 files changed +132 −0
Software/so101/src/hops.test.ts added +68
@@ -0,0 +1,68 @@
1 import { describe, expect, test } from "bun:test";
2 import { bestSync, exchangeSync, Hop, type Exchange } from "./hops.ts";
3
4 /** An exchange where the server clock runs `skew` ahead, with the given legs and server hold time. */
5 const ex = (t0: number, skew: number, out: number, back: number, hold = 1): Exchange => {
6 const t1 = t0 + out + skew;
7 const t2 = t1 + hold;
8 return { t0, t1, t2, t3: t2 - skew + back };
9 };
10
11 describe("exchangeSync", () => {
12 test("symmetric legs recover the skew exactly and exclude the hold time from delay", () => {
13 expect(exchangeSync(ex(1000, 250, 10, 10, 3))).toEqual({ offsetMs: 250, delayMs: 20 });
14 });
15
16 test("asymmetric legs bias the offset by half the difference", () => {
17 const s = exchangeSync(ex(1000, 250, 30, 10))!;
18 expect(s.delayMs).toBe(40);
19 expect(s.offsetMs).toBe(260);
20 });
21
22 test("malformed exchanges give null", () => {
23 expect(exchangeSync({ t0: NaN, t1: 1, t2: 2, t3: 3 })).toBeNull();
24 expect(exchangeSync({ t0: 0, t1: 0, t2: 10, t3: 5 })).toBeNull();
25 });
26 });
27
28 describe("bestSync", () => {
29 test("takes the offset of the lowest-delay exchange", () => {
30 const xs = [ex(0, 100, 40, 5), ex(100, 100, 6, 6), ex(200, 100, 5, 50)];
31 expect(bestSync(xs)).toEqual({ offsetMs: 100, delayMs: 12 });
32 });
33
34 test("only the last n count", () => {
35 const xs = [ex(0, 100, 5, 5), ex(100, 100, 20, 20), ex(200, 100, 30, 30)];
36 expect(bestSync(xs, 2)!.delayMs).toBe(40);
37 });
38
39 test("skips malformed exchanges and gives null when none are usable", () => {
40 expect(bestSync([])).toBeNull();
41 expect(bestSync([{ t0: 0, t1: NaN, t2: 0, t3: 0 }])).toBeNull();
42 expect(bestSync([{ t0: 0, t1: NaN, t2: 0, t3: 0 }, ex(0, 5, 4, 4)])!.offsetMs).toBe(5);
43 });
44 });
45
46 describe("Hop", () => {
47 test("p50 and p95 by nearest rank", () => {
48 const h = new Hop();
49 for (let i = 100; i >= 1; i--) h.add(i);
50 expect(h.stats()).toEqual({ count: 100, refused: 0, p50: 50, p95: 95 });
51 });
52
53 test("an empty hop has no percentiles", () => {
54 expect(new Hop().stats()).toEqual({ count: 0, refused: 0, p50: null, p95: null });
55 });
56
57 test("the window drops the oldest samples", () => {
58 const h = new Hop(3);
59 for (const v of [1000, 1, 2, 3]) h.add(v);
60 expect(h.stats()).toMatchObject({ count: 3, p50: 2, p95: 3 });
61 });
62
63 test("negative and non-finite samples are refused and counted", () => {
64 const h = new Hop();
65 expect([h.add(-1), h.add(NaN), h.add(Infinity), h.add(5)]).toEqual([false, false, false, true]);
66 expect(h.stats()).toEqual({ count: 1, refused: 3, p50: 5, p95: 5 });
67 });
68 });
Software/so101/src/hops.ts added +64
@@ -0,0 +1,64 @@
1 /**
2 * NTP-style clock offset and per-hop latency percentiles from timestamps.
3 * Pure: plain data in, plain data out; the caller owns the clock and the transport.
4 */
5
6 /** One request/response: t0 client send, t1 server receive, t2 server send, t3 client receive (ms). */
7 export type Exchange = { t0: number; t1: number; t2: number; t3: number };
8
9 export type Sync = { offsetMs: number; delayMs: number };
10
11 export const SYNC_WINDOW = 8;
12 export const HOP_WINDOW = 256;
13
14 const finite = (...v: number[]) => v.every(Number.isFinite);
15
16 /** Offset of the server clock from the client's (server - client) and the round-trip delay, or null for a malformed exchange. */
17 export function exchangeSync(x: Exchange): Sync | null {
18 if (!finite(x.t0, x.t1, x.t2, x.t3)) return null;
19 const delayMs = x.t3 - x.t0 - (x.t2 - x.t1);
20 if (delayMs < 0) return null;
21 return { offsetMs: (x.t1 - x.t0 + (x.t2 - x.t3)) / 2, delayMs };
22 }
23
24 /** The offset from the lowest-delay exchange of the last `n`: the least queued one is the least skewed by asymmetry. */
25 export function bestSync(exchanges: readonly Exchange[], n = SYNC_WINDOW): Sync | null {
26 let best: Sync | null = null;
27 for (const x of exchanges.slice(-Math.max(1, Math.floor(n)))) {

Math.max(1, Math.floor(NaN)) is NaN and slice(-NaN) returns everything. Fall back to SYNC_WINDOW when n is not finite, and add a test.

28 const s = exchangeSync(x);
29 if (s && (!best || s.delayMs < best.delayMs)) best = s;
30 }
31 return best;
32 }
33
34 export type HopStats = { count: number; refused: number; p50: number | null; p95: number | null };
35
36 /** A rolling window of one hop's durations (ms). */
37 export class Hop {
38 private samples: number[] = [];
39 private refused = 0;
40
41 constructor(private readonly size = HOP_WINDOW) {}
42
43 /** Returns false, and counts it, for a negative or non-finite duration. */
44 add(ms: number): boolean {

The typeof check is redundant: ms is typed number and Number.isFinite already returns false for non-numbers. Drop it unless input here can arrive untyped.

45 if (typeof ms !== "number" || !Number.isFinite(ms) || ms < 0) {
46 this.refused++;
47 return false;
48 }
49 this.samples.push(ms);
50 if (this.samples.length > this.size) this.samples.shift();
51 return true;
52 }
53
54 stats(): HopStats {
55 const sorted = [...this.samples].sort((a, b) => a - b);
56 return { count: sorted.length, refused: this.refused, p50: percentile(sorted, 0.5), p95: percentile(sorted, 0.95) };
57 }
58 }
59
60 /** Nearest-rank percentile of an ascending list. */
61 function percentile(sorted: readonly number[], p: number): number | null {
62 if (sorted.length === 0) return null;
63 return sorted[Math.max(0, Math.ceil(p * sorted.length) - 1)]!;
64 }

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs