Physical Clocks - NTP/PTP, Drift & Skew, Wall vs Monotonic Time & Leap Seconds

# How NTP estimates clock offset from four timestamps, why the error bound is delay/2,
# how much an unsynced crystal drifts, and what a 24h linear leap smear looks like.
# Timestamps are EXAMPLE values in milliseconds.

def offset_delay(t1, t2, t3, t4):
    """t1 client send, t2 server receive, t3 server send, t4 client receive."""
    offset = ((t2 - t1) + (t3 - t4)) / 2   # how far the server is ahead of the client
    delay = (t4 - t1) - (t3 - t2)          # round trip minus server processing time
    return offset, delay

# Several samples against the same server; the true offset is +25 ms.
# Sample 3 hit a congested return path (asymmetric delay), which skews its estimate.
samples = [
    (0,    35,   36,   22),
    (1000, 1037, 1038, 1026),
    (2000, 2036, 2037, 2068),   # slow way back
    (3000, 3034, 3035, 3020),
]
print("sample  offset_ms  delay_ms  error_bound(+/-delay/2)")
results = []
for i, s in enumerate(samples, 1):
    off, d = offset_delay(*s)
    results.append((d, off))
    print(f"{i:>6}  {off:>9.1f}  {d:>8.1f}  {d/2:>8.1f}")

# NTP's clock filter prefers the lowest-delay sample: least room for asymmetry error.
best_delay, best_off = min(results)
print(f"chosen (min delay) offset = {best_off:+.1f} ms  (true +25.0)\n")

# Drift: a quartz oscillator off by N parts per million gains/loses N microseconds per second.
for ppm in (10, 50, 200):
    per_day_ms = ppm * 86_400 / 1_000
    print(f"drift {ppm:>3} ppm -> {per_day_ms:>7.1f} ms/day unsynced, {ppm*60/1000:>5.2f} ms after a 60 s sync gap")

# Leap smear: instead of inserting 23:59:60, spread the extra second over 24 hours
# (noon to noon UTC, the published Google approach). Clocks run ~11.6 ppm slow meanwhile.
print("\nhours into 24h smear -> smeared clock lags UTC-without-leap by (ms)")
for h in (0, 6, 12, 18, 24):
    print(f"   {h:>2}h -> {1000 * h / 24:6.1f}")
print("smear rate =", round(1e6 / 86_400, 2), "ppm")

sample  offset_ms  delay_ms  error_bound(+/-delay/2)
     1       24.5      21.0      10.5
     2       24.5      25.0      12.5
     3        2.5      67.0      33.5
     4       24.5      19.0       9.5
chosen (min delay) offset = +24.5 ms  (true +25.0)

drift  10 ppm ->   864.0 ms/day unsynced,  0.60 ms after a 60 s sync gap
drift  50 ppm ->  4320.0 ms/day unsynced,  3.00 ms after a 60 s sync gap
drift 200 ppm -> 17280.0 ms/day unsynced, 12.00 ms after a 60 s sync gap

hours into 24h smear -> smeared clock lags UTC-without-leap by (ms)
    0h ->    0.0
    6h ->  250.0
   12h ->  500.0
   18h ->  750.0
   24h -> 1000.0
smear rate = 11.57 ppm

// Wall clock vs monotonic clock for measuring elapsed time, under an NTP step.
// We simulate both clocks so the run is deterministic; real code would use
// Date.now() (wall) vs performance.now() (monotonic).

class SimClocks {
  private trueMs = 0;     // real elapsed time since start
  private wallOffset = 0; // adjustments applied by NTP/admins to the wall clock only
  advance(ms: number): void { this.trueMs += ms; }
  stepWall(deltaMs: number): void { this.wallOffset += deltaMs; } // NTP step / manual change
  wall(): number { return 1_700_000_000_000 + this.trueMs + this.wallOffset; }
  monotonic(): number { return this.trueMs; } // only ever moves forward at a steady rate
}

const LEASE_MS = 10_000; // example lease: 10 s

function scenario(label: string, stepMs: number): void {
  const c = new SimClocks();
  const wallStart = c.wall();
  const monoStart = c.monotonic();
  c.advance(6_000);   // 6 s pass
  c.stepWall(stepMs); // NTP steps the wall clock
  c.advance(6_000);   // 6 more seconds pass: 12 s truly elapsed, lease SHOULD be expired
  const wallElapsed = c.wall() - wallStart;
  const monoElapsed = c.monotonic() - monoStart;
  console.log(label);
  console.log(`  true elapsed      12000 ms`);
  console.log(`  wall elapsed  ${String(wallElapsed).padStart(9)} ms -> lease ${wallElapsed < LEASE_MS ? "STILL HELD (bug)" : "expired"}`);
  console.log(`  mono elapsed  ${String(monoElapsed).padStart(9)} ms -> lease ${monoElapsed < LEASE_MS ? "still held" : "expired (correct)"}`);
}

scenario("A) wall clock stepped BACK 3 s mid-lease:", -3_000);
scenario("B) wall clock stepped FORWARD 5 s mid-lease:", 5_000);

// A negative duration is how Cloudflare's 2017 leap-second bug started: code computed
// a duration from wall-clock reads that went backwards, then passed it to a function
// that requires a positive value (Go's rand.Int63n), which panicked.
const before = 1_483_228_800_000;  // 2017-01-01T00:00:00Z
const after = before - 1_000;      // wall clock repeats a second around the leap
console.log(`\nwall-clock 'duration' across a repeated second: ${after - before} ms (negative!)`);

A) wall clock stepped BACK 3 s mid-lease:
  true elapsed      12000 ms
  wall elapsed       9000 ms -> lease STILL HELD (bug)
  mono elapsed      12000 ms -> lease expired (correct)
B) wall clock stepped FORWARD 5 s mid-lease:
  true elapsed      12000 ms
  wall elapsed      17000 ms -> lease expired
  mono elapsed      12000 ms -> lease expired (correct)

wall-clock 'duration' across a repeated second: -1000 ms (negative!)