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
Check · Review · Land done · Live — Landed; nothing deploys from this branch, so this is the end of its path.
smith/arm:smith/480-src-hops-ts-ntp-style-clock-offset-and-p → main 1 commit fork 2 threads · 2 unresolved
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)))) { | |
| 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 | } |
new above
offline
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.