@effectstream/sync 0.200.5 → 0.300.0

package/test/ntp-fetcher-case.ts

@@ -0,0 +1,248 @@
+import assert from "node:assert/strict";
+import { createSocket, type RemoteInfo, type Socket } from "node:dgram";
+import { run } from "effection";
+import {
+  ConfigNetworkType,
+  ConfigSyncProtocolType,
+} from "@effectstream/config";
+import { NtpFetcher } from "../src/sync-protocols/ntp/fetcher.ts";
+import { NtpSyncState } from "../src/sync-protocols/ntp/state.ts";
+
+type Responder = (request: Buffer, remote: RemoteInfo, socket: Socket) => void;
+
+async function closeSocket(socket: Socket): Promise<void> {
+  await new Promise<void>((resolve) => {
+    try {
+      socket.close(() => resolve());
+    } catch {
+      resolve();
+    }
+  });
+}
+
+async function startUdp(responder: Responder) {
+  let lastError: unknown;
+  for (let attempt = 0; attempt < 64; attempt++) {
+    const socket = createSocket("udp4");
+    try {
+      await new Promise<void>((resolve, reject) => {
+        socket.once("error", reject);
+        socket.bind(0, "127.0.0.1", () => {
+          socket.removeListener("error", reject);
+          resolve();
+        });
+      });
+      const port = socket.address().port;
+      if (port <= 10_000) {
+        await closeSocket(socket);
+        continue;
+      }
+      let hits = 0;
+      const clientPorts = new Set<number>();
+      socket.on("message", (message, remote) => {
+        hits += 1;
+        clientPorts.add(remote.port);
+        responder(message, remote, socket);
+      });
+      return {
+        port,
+        hits: () => hits,
+        clientPorts: () => [...clientPorts],
+        close: () => closeSocket(socket),
+      };
+    } catch (error) {
+      lastError = error;
+      await closeSocket(socket);
+    }
+  }
+  throw lastError ?? new Error("no OS-selected UDP port above 10000");
+}
+
+async function assertPortReusable(port: number): Promise<void> {
+  const socket = createSocket("udp4");
+  await new Promise<void>((resolve, reject) => {
+    socket.once("error", reject);
+    socket.bind(port, "127.0.0.1", () => {
+      socket.removeListener("error", reject);
+      resolve();
+    });
+  });
+  await closeSocket(socket);
+}
+
+function writeTimestamp(buffer: Buffer, offset: number, unixMs: number): void {
+  const ntpMs = unixMs + 2_208_988_800_000;
+  const seconds = Math.floor(ntpMs / 1_000);
+  const fraction = Math.floor(((ntpMs % 1_000) / 1_000) * 2 ** 32);
+  buffer.writeUInt32BE(seconds >>> 0, offset);
+  buffer.writeUInt32BE(fraction >>> 0, offset + 4);
+}
+
+function responseFor(request: Buffer, clockOffsetMs = 0): Buffer {
+  const response = Buffer.alloc(48);
+  response[0] = (4 << 3) | 4;
+  response[1] = 1;
+  response[2] = 4;
+  response[3] = 0xec;
+  response.write("LOCL", 12, 4, "ascii");
+  const now = Date.now() + clockOffsetMs;
+  writeTimestamp(response, 16, now - 1_000);
+  request.copy(response, 24, 40, 48);
+  writeTimestamp(response, 32, now);
+  writeTimestamp(response, 40, now);
+  return response;
+}
+
+const responder =
+  (clockOffsetMs = 0): Responder =>
+  (request, remote, socket) => {
+    socket.send(
+      responseFor(request, clockOffsetMs),
+      remote.port,
+      remote.address,
+    );
+  };
+
+function config(servers?: string[]) {
+  return {
+    networkType: ConfigNetworkType.NTP,
+    syncProtocolType: ConfigSyncProtocolType.NTP_MAIN,
+    network: {
+      name: "controlled-clock",
+      type: ConfigNetworkType.NTP,
+      blockTimeMS: 1_000,
+      startTime: 0,
+      servers,
+    },
+    syncProtocol: {
+      name: "controlled-clock",
+      type: ConfigSyncProtocolType.NTP_MAIN,
+      startBlockHeight: 42,
+      pollingInterval: 1_000,
+      stepSize: 10,
+    },
+    primitives: [],
+  } as any;
+}
+
+async function withTwoServers(
+  action: (
+    a: Awaited<ReturnType<typeof startUdp>>,
+    b: Awaited<ReturnType<typeof startUdp>>,
+  ) => Promise<void>,
+) {
+  const a = await startUdp(responder());
+  const b = await startUdp(responder(100_000));
+  try {
+    await action(a, b);
+  } finally {
+    const clientPorts = [...a.clientPorts(), ...b.clientPorts()];
+    await a.close();
+    await b.close();
+    await assertPortReusable(a.port);
+    await assertPortReusable(b.port);
+    for (const port of clientPorts) await assertPortReusable(port);
+  }
+}
+
+switch (process.argv[2]) {
+  case "default-owned": {
+    const absentA = new NtpFetcher(config());
+    const absentB = new NtpFetcher(config());
+    const empty = new NtpFetcher(config([]));
+    assert.notEqual(absentA.ntpTimeSync, absentB.ntpTimeSync);
+    assert.notEqual(absentA.ntpTimeSync, empty.ntpTimeSync);
+    assert.notEqual(absentB.ntpTimeSync, empty.ntpTimeSync);
+    break;
+  }
+  case "configured-copy": {
+    const servers = ["127.0.0.1:12345"];
+    const fetcher = new NtpFetcher(config(servers));
+    servers[0] = "127.0.0.1:54321";
+    servers.push("127.0.0.1:11111");
+    const options = (fetcher.ntpTimeSync as any).options;
+    assert.deepEqual(options.servers, [{ host: "127.0.0.1", port: 12345 }]);
+    break;
+  }
+  case "sequential-isolation": {
+    await withTwoServers(async (a, b) => {
+      const fetcherA = new NtpFetcher(config([`127.0.0.1:${a.port}`]));
+      const fetcherB = new NtpFetcher(config([`127.0.0.1:${b.port}`]));
+      assert.notEqual(fetcherA.ntpTimeSync, fetcherB.ntpTimeSync);
+      await fetcherA.ntpTimeSync.getTime();
+      assert.equal(a.hits(), 8);
+      assert.equal(b.hits(), 0);
+      await fetcherB.ntpTimeSync.getTime();
+      assert.equal(a.hits(), 8);
+      assert.equal(b.hits(), 8);
+      await fetcherA.ntpTimeSync.getTime();
+      await fetcherB.ntpTimeSync.getTime();
+      assert.equal(a.hits(), 8);
+      assert.equal(b.hits(), 8);
+    });
+    break;
+  }
+  case "concurrent-isolation": {
+    await withTwoServers(async (a, b) => {
+      const fetcherA = new NtpFetcher(config([`127.0.0.1:${a.port}`]));
+      const fetcherB = new NtpFetcher(config([`127.0.0.1:${b.port}`]));
+      assert.notEqual(fetcherA.ntpTimeSync, fetcherB.ntpTimeSync);
+      const [resultA, resultB] = await Promise.all([
+        fetcherA.ntpTimeSync.getTime(),
+        fetcherB.ntpTimeSync.getTime(),
+      ]);
+      assert(resultA.offset > -1_000 && resultA.offset < 1_000);
+      assert(resultB.offset > 99_000 && resultB.offset < 101_000);
+      assert.equal(a.hits(), 8);
+      assert.equal(b.hits(), 8);
+    });
+    break;
+  }
+  case "numeric-page-one": {
+    const fetcher = {
+      getLatestPage: function* () {
+        return 100;
+      },
+      intervalFromStart: (start: number) => ({ from: start, to: start + 9 }),
+      previousInterval: (start: number) => ({
+        from: start - 10,
+        to: start - 1,
+      }),
+      nextInterval: (end: number) => ({ from: end + 1, to: end + 10 }),
+    } as any;
+    const state = new NtpSyncState(
+      undefined as any,
+      config(),
+      fetcher,
+      undefined as any,
+    );
+    const input = await run(() => state.stateToInput());
+    assert.deepEqual(input, { from: 1, to: 10, isPresync: true });
+    break;
+  }
+  case "offset-warnings": {
+    const fetcher = new NtpFetcher(config());
+    const originalConsoleError = console.error;
+    const warnings: string[] = [];
+    console.error = (...values: unknown[]) => warnings.push(values.join(" "));
+    try {
+      for (const offset of [6_001, -6_001, 5_000, -5_000]) {
+        (fetcher.ntpTimeSync as any).getTime = async () => ({
+          now: new Date(10_000),
+          offset,
+        });
+        await run(() => fetcher.getLatestPage(undefined));
+      }
+    } finally {
+      console.error = originalConsoleError;
+    }
+    assert.equal(warnings.length, 2);
+    assert(warnings[0].includes("6001"));
+    assert(warnings[1].includes("-6001"));
+    break;
+  }
+  default:
+    assert.fail(`unknown NTP fetcher scenario: ${process.argv[2]}`);
+}
+
+console.log(`ok ${process.argv[2]}`);

package/test/ntp-fetcher.test.ts

@@ -0,0 +1,69 @@
+import { expect, test } from "bun:test";
+
+async function runCase(name: string): Promise<void> {
+  const child = Bun.spawn(
+    [process.execPath, "packages/node-sdk/sync/test/ntp-fetcher-case.ts", name],
+    { cwd: process.cwd(), stdout: "pipe", stderr: "pipe", env: process.env },
+  );
+  let timedOut = false;
+  const timeout = setTimeout(() => {
+    timedOut = true;
+    child.kill();
+  }, 30_000);
+  const [exitCode, stdout, stderr] = await Promise.all([
+    child.exited,
+    new Response(child.stdout).text(),
+    new Response(child.stderr).text(),
+  ]);
+  clearTimeout(timeout);
+  expect(timedOut, `${name} timed out`).toBe(false);
+  expect(exitCode, `${name}\n${stdout}\n${stderr}`).toBe(0);
+  expect(stdout).toContain(`ok ${name}`);
+}
+
+test(
+  "absent and empty fetchers each own a clock instance",
+  () => runCase("default-owned"),
+  35_000,
+);
+test(
+  "configured server arrays are defensively copied",
+  () => runCase("configured-copy"),
+  35_000,
+);
+test(
+  "sequential configured fetchers isolate traffic and cache",
+  () => runCase("sequential-isolation"),
+  35_000,
+);
+test(
+  "concurrent configured fetchers isolate traffic and signed offsets",
+  () => runCase("concurrent-isolation"),
+  35_000,
+);
+test(
+  "explicit numeric NTP state preserves historical page-1 presync",
+  () => runCase("numeric-page-one"),
+  35_000,
+);
+test(
+  "offset warnings use magnitude in both clock directions",
+  () => runCase("offset-warnings"),
+  35_000,
+);
+
+test("NTP dependencies and lock integrity are exact", async () => {
+  const manifest = await Bun.file("packages/node-sdk/sync/package.json").json();
+  const lock = await Bun.file("bun.lock").text();
+  expect(manifest.dependencies["ntp-time-sync"]).toBe("0.6.0");
+  // ntp-packet-parser is ntp-time-sync's own dependency, not a direct one.
+  expect(manifest.dependencies["ntp-packet-parser"]).toBeUndefined();
+  expect(lock).toContain('"ntp-time-sync": ["ntp-time-sync@0.6.0"');
+  expect(lock).toContain(
+    "sha512-7hKnLUZN04goatNThks+raCAI4xRkF0UTdvoj7zpGsp1LDtyAJp4yguIIFYsLng6BKlheYfIOOyqY+eqvPsaCA==",
+  );
+  expect(lock).toContain('"ntp-packet-parser": ["ntp-packet-parser@0.6.1"');
+  expect(lock).toContain(
+    "sha512-nIDaxXcaxDsSj0Fh+Daa1nsmBwc2ENxeWOHmyEnbj7Cl3Jgzl03gCqV+jWOAvB46ooibbAaTAjMhy0lzlHUPSg==",
+  );
+});

package/test/ntp-tip.test.ts

@@ -0,0 +1,228 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { createSocket, type RemoteInfo, type Socket } from "node:dgram";
+import { getNtpTip, NtpTipError } from "../src/sync-protocols/ntp/tip.ts";
+
+const NTP_EPOCH_OFFSET_MS = 2_208_988_800_000;
+const BLOCK_TIME_MS = 600_000;
+
+type Responder = (request: Buffer, remote: RemoteInfo, socket: Socket) => void;
+
+type Fixture = {
+  server: string;
+  hits: () => number;
+  close: () => Promise<void>;
+};
+
+const fixtures: Fixture[] = [];
+
+afterEach(async () => {
+  await Promise.all(fixtures.splice(0).map((fixture) => fixture.close()));
+});
+
+function writeTimestamp(buffer: Buffer, offset: number, unixMs: number): void {
+  const ntpMs = unixMs + NTP_EPOCH_OFFSET_MS;
+  buffer.writeUInt32BE(Math.floor(ntpMs / 1000) >>> 0, offset);
+  buffer.writeUInt32BE(Math.floor(((ntpMs % 1000) / 1000) * 2 ** 32) >>> 0, offset + 4);
+}
+
+/** A valid NTPv4 server response whose clock reads `serverTimeMs`. */
+function responseFor(request: Buffer, serverTimeMs: number): Buffer {
+  const response = Buffer.alloc(48);
+  response[0] = (4 << 3) | 4; // leap 0, version 4, mode server
+  response[1] = 1; // stratum
+  response[3] = 0xec; // precision, 2^-20s
+  response.write("LOCL", 12, 4, "ascii");
+  writeTimestamp(response, 16, serverTimeMs - 1_000);
+  request.copy(response, 24, 40, 48); // echo the client transmit as origin
+  writeTimestamp(response, 32, serverTimeMs);
+  writeTimestamp(response, 40, serverTimeMs);
+  return response;
+}
+
+const serveTime =
+  (serverTimeMs: () => number): Responder =>
+  (request, remote, socket) =>
+    socket.send(responseFor(request, serverTimeMs()), remote.port, remote.address);
+
+const silent: Responder = () => {};
+
+const serveGarbage: Responder = (_request, remote, socket) =>
+  socket.send(Buffer.alloc(4), remote.port, remote.address);
+
+async function startFixture(responder: Responder): Promise<Fixture> {
+  const socket = createSocket("udp4");
+  await new Promise<void>((resolve, reject) => {
+    socket.once("error", reject);
+    socket.bind(0, "127.0.0.1", () => {
+      socket.removeListener("error", reject);
+      resolve();
+    });
+  });
+  let hits = 0;
+  socket.on("message", (request, remote) => {
+    hits += 1;
+    responder(request, remote, socket);
+  });
+  const fixture: Fixture = {
+    server: `127.0.0.1:${socket.address().port}`,
+    hits: () => hits,
+    close: () =>
+      new Promise<void>((resolve) => {
+        try {
+          socket.close(() => resolve());
+        } catch {
+          resolve();
+        }
+      }),
+  };
+  fixtures.push(fixture);
+  return fixture;
+}
+
+async function expectTipError(
+  promise: Promise<unknown>,
+  code: NtpTipError["code"],
+): Promise<NtpTipError> {
+  try {
+    await promise;
+  } catch (error) {
+    expect(error).toBeInstanceOf(NtpTipError);
+    expect((error as NtpTipError).code).toBe(code);
+    return error as NtpTipError;
+  }
+  throw new Error(`Expected NtpTipError(${code})`);
+}
+
+describe("getNtpTip validation", () => {
+  test.each([
+    ["missing options", undefined],
+    ["non-object options", 42],
+    ["fractional startTime", { startTime: 0.5, blockTimeMS: 1000 }],
+    ["unsafe startTime", { startTime: 2 ** 53, blockTimeMS: 1000 }],
+    ["zero blockTimeMS", { startTime: 0, blockTimeMS: 0 }],
+    ["negative blockTimeMS", { startTime: 0, blockTimeMS: -1 }],
+    ["fractional blockTimeMS", { startTime: 0, blockTimeMS: 0.5 }],
+    ["zero timeout", { startTime: 0, blockTimeMS: 1000, requestTimeoutMs: 0 }],
+    [
+      "timeout past the timer clamp",
+      { startTime: 0, blockTimeMS: 1000, requestTimeoutMs: 2 ** 31 },
+    ],
+    ["non-array servers", { startTime: 0, blockTimeMS: 1000, servers: "x" }],
+    ["empty server", { startTime: 0, blockTimeMS: 1000, servers: [""] }],
+    [
+      "padded server",
+      { startTime: 0, blockTimeMS: 1000, servers: [" host "] },
+    ],
+    ["non-signal", { startTime: 0, blockTimeMS: 1000, signal: 7 }],
+  ])("rejects %s", async (_name, options) => {
+    await expectTipError(
+      getNtpTip(options as never),
+      "INVALID_OPTIONS",
+    );
+  });
+});
+
+describe("getNtpTip network behavior", () => {
+  test("returns the inclusive page for the sampled NTP time", async () => {
+    const startTime = Date.now();
+    const fixture = await startFixture(
+      serveTime(() => startTime + 3 * BLOCK_TIME_MS + BLOCK_TIME_MS / 2),
+    );
+    await expect(
+      getNtpTip({ startTime, blockTimeMS: BLOCK_TIME_MS, servers: [fixture.server] }),
+    ).resolves.toEqual({ height: 3 });
+    expect(fixture.hits()).toBe(1);
+  });
+
+  test("concurrent calls own their server configuration", async () => {
+    const startTime = Date.now();
+    const fixtureA = await startFixture(
+      serveTime(() => startTime + 3 * BLOCK_TIME_MS + BLOCK_TIME_MS / 2),
+    );
+    const fixtureB = await startFixture(
+      serveTime(() => startTime + 7 * BLOCK_TIME_MS + BLOCK_TIME_MS / 2),
+    );
+    const [a, b] = await Promise.all([
+      getNtpTip({ startTime, blockTimeMS: BLOCK_TIME_MS, servers: [fixtureA.server] }),
+      getNtpTip({ startTime, blockTimeMS: BLOCK_TIME_MS, servers: [fixtureB.server] }),
+    ]);
+    expect(a).toEqual({ height: 3 });
+    expect(b).toEqual({ height: 7 });
+    expect(fixtureA.hits()).toBe(1);
+    expect(fixtureB.hits()).toBe(1);
+  });
+
+  test("a sampled time before startTime is INVALID_TIME", async () => {
+    const startTime = Date.now();
+    const fixture = await startFixture(
+      serveTime(() => startTime - 10 * BLOCK_TIME_MS),
+    );
+    await expectTipError(
+      getNtpTip({ startTime, blockTimeMS: BLOCK_TIME_MS, servers: [fixture.server] }),
+      "INVALID_TIME",
+    );
+  });
+
+  test("a silent server is bounded by the deadline", async () => {
+    const fixture = await startFixture(silent);
+    const error = await expectTipError(
+      getNtpTip({
+        startTime: 0,
+        blockTimeMS: BLOCK_TIME_MS,
+        servers: [fixture.server],
+        requestTimeoutMs: 300,
+      }),
+      "TIMEOUT",
+    );
+    expect(error.timeoutMs).toBe(300);
+    expect(fixture.hits()).toBe(1);
+  });
+
+  test("malformed responses fail as NETWORK with a cause", async () => {
+    const fixture = await startFixture(serveGarbage);
+    const error = await expectTipError(
+      getNtpTip({
+        startTime: 0,
+        blockTimeMS: BLOCK_TIME_MS,
+        servers: [fixture.server],
+        requestTimeoutMs: 5_000,
+      }),
+      "NETWORK",
+    );
+    expect(error.cause).toBeDefined();
+  });
+
+  test("an already-aborted signal sends no packets", async () => {
+    const fixture = await startFixture(serveTime(() => Date.now()));
+    const controller = new AbortController();
+    const reason = new Error("stop before start");
+    controller.abort(reason);
+    const error = await expectTipError(
+      getNtpTip({
+        startTime: 0,
+        blockTimeMS: BLOCK_TIME_MS,
+        servers: [fixture.server],
+        signal: controller.signal,
+      }),
+      "ABORTED",
+    );
+    expect(error.cause).toBe(reason);
+    expect(fixture.hits()).toBe(0);
+  });
+
+  test("an in-flight abort keeps its cause and removes its listener", async () => {
+    const fixture = await startFixture(silent);
+    const controller = new AbortController();
+    const reason = new Error("stop mid-flight");
+    const pending = getNtpTip({
+      startTime: 0,
+      blockTimeMS: BLOCK_TIME_MS,
+      servers: [fixture.server],
+      requestTimeoutMs: 1_000,
+      signal: controller.signal,
+    });
+    setTimeout(() => controller.abort(reason), 50);
+    const error = await expectTipError(pending, "ABORTED");
+    expect(error.cause).toBe(reason);
+  });
+});