@evolu/common 8.9.0 → 8.11.0

package/src/local-first/Timestamp.test.ts

@@ -3,34 +3,36 @@ import {
   assertEqual,
   assertErr,
   assertFalse,
+  assertNotSame,
   assertOk,
+  assertThrowsInstanceOf,
   assertTrue,
 } from "../Assert.ts";
 import { increment } from "../Number.ts";
 import { orderNumber } from "../Order.ts";
 import type { Result } from "../Result.ts";
-import { ok } from "../Result.ts";
 import { testCreateDeps } from "../Task.ts";
-import type { Time, TimeDep } from "../Time.ts";
-import { maxMillis, Millis, minMillis, testCreateTime } from "../Time.ts";
+import { maxMillis, Millis, minMillis } from "../Time.ts";
+import { assertType } from "../Type.ts";
 import type {
   Timestamp,
   TimestampBytes,
   TimestampConfigDep,
-  TimestampCounterOverflowError,
   TimestampDriftError,
-  TimestampTimeOutOfRangeError,
 } from "./Timestamp.ts";
 import {
   Counter,
   createInitialTimestamp,
   createTimestamp,
   defaultTimestampMaxDrift,
+  isTimestampBeyondMaxDrift,
   maxCounter,
+  maxNodeId,
   minCounter,
   NodeId,
   nodeIdBytesToNodeId,
   nodeIdToNodeIdBytes,
+  orderTimestamp,
   orderTimestampBytes,
   receiveTimestamp,
   sendTimestamp,
@@ -93,21 +95,90 @@ test("creates an initial Timestamp", () => {
   });
 });
 
+describe("orderTimestamp", () => {
+  it("compares equal timestamps regardless of object identity", () => {
+    const timestamp = createTimestamp({
+      millis: maxMillis,
+      counter: maxCounter,
+      nodeId: maxNodeId,
+    });
+    const copy = { ...timestamp };
+
+    assertNotSame(timestamp, copy);
+    assertEqual(orderTimestamp(timestamp, timestamp), 0);
+    assertEqual(orderTimestamp(timestamp, copy), 0);
+    assertEqual(orderTimestamp(copy, timestamp), 0);
+  });
+
+  it("orders millis, counter, then nodeId consistently with timestamp bytes", () => {
+    const timestamps = [
+      createTimestamp(),
+      createTimestamp({ nodeId: NodeId.orThrow("9999999999999999") }),
+      createTimestamp({ nodeId: NodeId.orThrow("aaaaaaaaaaaaaaaa") }),
+      createTimestamp({ nodeId: maxNodeId }),
+      createTimestamp({ counter: Counter.orThrow(255), nodeId: maxNodeId }),
+      createTimestamp({ counter: Counter.orThrow(256) }),
+      createTimestamp({ counter: maxCounter, nodeId: maxNodeId }),
+      createTimestamp({ millis: Millis.orThrow(1) }),
+      createTimestamp({
+        millis: Millis.orThrow(2 ** 32 - 1),
+        counter: maxCounter,
+        nodeId: maxNodeId,
+      }),
+      createTimestamp({ millis: Millis.orThrow(2 ** 32) }),
+      createTimestamp({
+        millis: maxMillis,
+        counter: maxCounter,
+        nodeId: maxNodeId,
+      }),
+    ];
+    const bytes = timestamps.map(timestampToTimestampBytes);
+
+    for (const [i, a] of timestamps.entries()) {
+      for (const [j, b] of timestamps.entries()) {
+        const order = orderTimestamp(a, b);
+        assertEqual(order, orderNumber(i, j));
+        assertEqual(order, orderTimestampBytes(bytes[i], bytes[j]));
+      }
+    }
+  });
+});
+
 const makeMillis = (millis: number): Millis => Millis.orThrow(millis);
 
-const deps0: TimeDep & TimestampConfigDep = {
-  time: testCreateTime({ startAt: minMillis }),
-  timestampConfig: { maxDrift: defaultTimestampMaxDrift },
-};
+describe("isTimestampBeyondMaxDrift", () => {
+  it("accepts past timestamps and the exact future limit", () => {
+    const isBeyondMaxDrift = isTimestampBeyondMaxDrift({
+      timestampConfig: { maxDrift: 10 },
+    });
+    const now = makeMillis(100);
+
+    assertFalse(isBeyondMaxDrift(makeMillis(0), now));
+    assertFalse(isBeyondMaxDrift(now, now));
+    assertFalse(isBeyondMaxDrift(makeMillis(109), now));
+    assertFalse(isBeyondMaxDrift(makeMillis(110), now));
+    assertTrue(isBeyondMaxDrift(makeMillis(111), now));
+  });
+
+  it("rejects any future timestamp when the limit is zero", () => {
+    const isBeyondMaxDrift = isTimestampBeyondMaxDrift({
+      timestampConfig: { maxDrift: 0 },
+    });
+    const now = makeMillis(100);
+
+    assertFalse(isBeyondMaxDrift(makeMillis(99), now));
+    assertFalse(isBeyondMaxDrift(now, now));
+    assertTrue(isBeyondMaxDrift(makeMillis(101), now));
+  });
+});
 
-const deps1: TimeDep & TimestampConfigDep = {
-  time: testCreateTime({ startAt: (minMillis + 1) as Millis }),
+const config: TimestampConfigDep = {
   timestampConfig: { maxDrift: defaultTimestampMaxDrift },
 };
 
 describe("sendTimestamp", () => {
   it("sends monotonically with a monotonic clock", () => {
-    assertOk(sendTimestamp(deps1)(createTimestamp()), {
+    assertOk(sendTimestamp(config)(createTimestamp(), makeMillis(1)), {
       counter: 0,
       millis: 1,
       nodeId: "0000000000000000",
@@ -115,7 +186,7 @@ describe("sendTimestamp", () => {
   });
 
   it("sends monotonically with a stuttering clock", () => {
-    assertOk(sendTimestamp(deps0)(createTimestamp()), {
+    assertOk(sendTimestamp(config)(createTimestamp(), minMillis), {
       counter: 1,
       millis: 0,
       nodeId: "0000000000000000",
@@ -124,8 +195,9 @@ describe("sendTimestamp", () => {
 
   it("sends monotonically with a regressing clock", () => {
     assertOk(
-      sendTimestamp(deps0)(
+      sendTimestamp(config)(
         createTimestamp({ millis: makeMillis(minMillis + 1) }),
+        minMillis,
       ),
       {
         counter: 1,
@@ -135,52 +207,64 @@ describe("sendTimestamp", () => {
     );
   });
 
-  it("returns TimestampCounterOverflowError for counter overflow", () => {
-    let timestamp: Result<
-      Timestamp,
-      | TimestampDriftError
-      | TimestampCounterOverflowError
-      | TimestampTimeOutOfRangeError
-    > = ok(createTimestamp());
-
-    // Note +1 in 65536.
-    for (let i = 0; i < 65536; i++) {
-      if (timestamp.ok) timestamp = sendTimestamp(deps0)(timestamp.value);
+  it("continues past a full counter with fixed wall time", () => {
+    let timestamp = createTimestamp();
+    for (let i = 0; i <= maxCounter; i++) {
+      const next = sendTimestamp(config)(timestamp, minMillis);
+      assertOk(next);
+      timestamp = next.value;
     }
+    assertEqual(timestamp, createTimestamp({ millis: makeMillis(1) }));
+    assertOk(
+      sendTimestamp(config)(timestamp, minMillis),
+      createTimestamp({ millis: makeMillis(1), counter: Counter.orThrow(1) }),
+    );
+  });
 
-    assertErr(timestamp, { type: "TimestampCounterOverflowError" });
+  it("continues past a full counter while the clock is ahead of advancing wall time", () => {
+    // Wall time advances by one millisecond per send, while the clock stays two
+    // minutes ahead, as after receiving a timestamp from a fast peer. Every
+    // send keeps the pinned millis, so the counter alone must carry ordering.
+    const pinnedMillis = makeMillis(2 * 60 * 1000);
+    let timestamp = createTimestamp({ millis: pinnedMillis });
+    for (let i = 0; i <= maxCounter; i++) {
+      const next = sendTimestamp(config)(timestamp, makeMillis(i));
+      assertOk(next);
+      assertEqual(
+        orderTimestampBytes(
+          timestampToTimestampBytes(timestamp),
+          timestampToTimestampBytes(next.value),
+        ),
+        -1,
+      );
+      if (i < maxCounter) assertEqual(next.value.millis, pinnedMillis);
+      timestamp = next.value;
+    }
+    assertEqual(
+      timestamp,
+      createTimestamp({ millis: makeMillis(pinnedMillis + 1) }),
+    );
   });
 
-  it("returns TimestampDriftError for excessive clock drift", () => {
+  it("returns TimestampDriftError for an ahead local clock", () => {
     assertErr(
-      sendTimestamp(deps0)(
+      sendTimestamp(config)(
         createTimestamp({
           millis: makeMillis(minMillis + defaultTimestampMaxDrift + 1),
         }),
+        minMillis,
       ),
       {
-        next: 300001,
-        now: 0,
         type: "TimestampDriftError",
+        now: minMillis,
+        timestamp: createTimestamp({
+          millis: makeMillis(300001),
+          counter: Counter.orThrow(1),
+        }),
+        cause: "local",
       },
     );
   });
-
-  it("returns TimestampTimeOutOfRangeError for an invalid clock", () => {
-    const time = testCreateTime();
-    const invalidTime: Time = {
-      ...time,
-      now: (() => -1) as Time["now"],
-    };
-
-    assertErr(
-      sendTimestamp({
-        time: invalidTime,
-        timestampConfig: { maxDrift: defaultTimestampMaxDrift },
-      })(createTimestamp()),
-      { type: "TimestampTimeOutOfRangeError" },
-    );
-  });
 });
 
 describe("receiveTimestamp", () => {
@@ -200,7 +284,11 @@ describe("receiveTimestamp", () => {
 
   it("uses a wall clock later than both timestamps", () => {
     assertOk(
-      receiveTimestamp(deps1)(makeNode1Timestamp(), makeNode2Timestamp()),
+      receiveTimestamp(config)(
+        makeNode1Timestamp(),
+        makeNode2Timestamp(),
+        makeMillis(1),
+      ),
       {
         counter: 0,
         millis: 1,
@@ -212,9 +300,10 @@ describe("receiveTimestamp", () => {
   describe("wall clock is behind", () => {
     it("increments the maximum counter when millis are equal", () => {
       assertOk(
-        receiveTimestamp(deps1)(
+        receiveTimestamp(config)(
           makeNode1Timestamp(1, 0),
           makeNode2Timestamp(1, 1),
+          makeMillis(1),
         ),
         {
           counter: 2,
@@ -224,9 +313,10 @@ describe("receiveTimestamp", () => {
       );
 
       assertOk(
-        receiveTimestamp(deps0)(
+        receiveTimestamp(config)(
           makeNode1Timestamp(1, 1),
           makeNode2Timestamp(1, 0),
+          minMillis,
         ),
         {
           counter: 2,
@@ -238,7 +328,11 @@ describe("receiveTimestamp", () => {
 
     it("increments the counter when local millis is later", () => {
       assertOk(
-        receiveTimestamp(deps0)(makeNode1Timestamp(2), makeNode2Timestamp(1)),
+        receiveTimestamp(config)(
+          makeNode1Timestamp(2),
+          makeNode2Timestamp(1),
+          minMillis,
+        ),
         {
           counter: 1,
           millis: 2,
@@ -249,7 +343,11 @@ describe("receiveTimestamp", () => {
 
     it("increments the counter when remote millis is later", () => {
       assertOk(
-        receiveTimestamp(deps0)(makeNode1Timestamp(1), makeNode2Timestamp(2)),
+        receiveTimestamp(config)(
+          makeNode1Timestamp(1),
+          makeNode2Timestamp(2),
+          minMillis,
+        ),
         {
           counter: 1,
           millis: 2,
@@ -258,43 +356,219 @@ describe("receiveTimestamp", () => {
       );
     });
 
-    it("returns TimestampDriftError for excessive clock drift", () => {
-      const expected = {
-        next: 300001,
-        now: 0,
-        type: "TimestampDriftError",
-      } as const;
-
+    it("returns local drift when an accepted remote timestamp leaves the clock ahead", () => {
       assertErr(
-        receiveTimestamp(deps0)(
+        receiveTimestamp(config)(
           createTimestamp({
             millis: makeMillis(minMillis + defaultTimestampMaxDrift + 1),
           }),
           makeNode2Timestamp(),
+          minMillis,
+        ),
+        {
+          type: "TimestampDriftError",
+          now: minMillis,
+          timestamp: createTimestamp({
+            millis: makeMillis(300001),
+            counter: Counter.orThrow(1),
+          }),
+          cause: "local",
+        },
+      );
+    });
+
+    it("rejects remote drift without a separate caller check", () => {
+      const remote = createTimestamp({
+        millis: makeMillis(minMillis + defaultTimestampMaxDrift + 1),
+      });
+      const local = makeNode2Timestamp();
+      const before = { ...local };
+      assertErr(receiveTimestamp(config)(local, remote, minMillis), {
+        type: "TimestampDriftError",
+        timestamp: remote,
+        cause: "remote",
+        now: minMillis,
+      });
+      assertEqual(local, before);
+    });
+
+    it("rejects remote drift before arithmetic at the range ceiling", () => {
+      const remote = createTimestamp({
+        millis: maxMillis,
+        counter: maxCounter,
+      });
+      assertErr(
+        receiveTimestamp(config)(createTimestamp(), remote, minMillis),
+        {
+          type: "TimestampDriftError",
+          timestamp: remote,
+          cause: "remote",
+          now: minMillis,
+        },
+      );
+    });
+
+    it("uses the configured drift boundary, including a zero limit", () => {
+      for (const maxDrift of [0, 10]) {
+        const deps = { timestampConfig: { maxDrift } };
+        const now = makeMillis(100);
+        const local = makeNode1Timestamp();
+        const accepted = makeNode2Timestamp(100 + maxDrift);
+        assertOk(
+          receiveTimestamp(deps)(local, accepted, now),
+          makeNode1Timestamp(100 + maxDrift, 1),
+        );
+        const rejected = makeNode2Timestamp(101 + maxDrift);
+        assertErr(receiveTimestamp(deps)(local, rejected, now), {
+          type: "TimestampDriftError",
+          timestamp: rejected,
+          cause: "remote",
+          now: makeMillis(100),
+        });
+      }
+    });
+
+    for (const [
+      label,
+      localMillis,
+      remoteMillis,
+      localCounter,
+      remoteCounter,
+    ] of [
+      ["equal millis with the local counter exhausted", 1, 1, maxCounter, 0],
+      ["equal millis with the remote counter exhausted", 1, 1, 0, maxCounter],
+      [
+        "equal millis with both counters exhausted",
+        1,
+        1,
+        maxCounter,
+        maxCounter,
+      ],
+      ["later local millis", 1, 0, maxCounter, 0],
+      ["later remote millis", 0, 1, 0, maxCounter],
+    ] as const) {
+      it(`rolls over for ${label}`, () => {
+        const local = makeNode1Timestamp(localMillis, localCounter);
+        const remote = makeNode2Timestamp(remoteMillis, remoteCounter);
+        const result = receiveTimestamp(config)(local, remote, minMillis);
+        assertOk(result, makeNode1Timestamp(2, 0));
+        const bytes = timestampToTimestampBytes(result.value);
+        assertEqual(
+          orderTimestampBytes(timestampToTimestampBytes(local), bytes),
+          -1,
+        );
+        assertEqual(
+          orderTimestampBytes(timestampToTimestampBytes(remote), bytes),
+          -1,
+        );
+      });
+    }
+    it("resets exhausted counters when wall time is newer", () => {
+      assertOk(
+        receiveTimestamp(config)(
+          makeNode1Timestamp(1, maxCounter),
+          makeNode2Timestamp(1, maxCounter),
+          makeMillis(2),
         ),
-        expected,
+        makeNode1Timestamp(2, 0),
       );
+    });
+  });
+});
 
+describe("timestamp rollover boundaries", () => {
+  for (const operation of ["send", "receive"] as const) {
+    const nextTimestamp = (timestamp: Timestamp, now = minMillis) =>
+      operation === "send"
+        ? sendTimestamp(config)(timestamp, now)
+        : receiveTimestamp(config)(timestamp, timestamp, now);
+
+    it(`${operation} uses the last counter before rolling over`, () => {
+      const lastCounter = createTimestamp({ counter: maxCounter });
+      assertOk(
+        nextTimestamp(
+          createTimestamp({ counter: Counter.orThrow(maxCounter - 1) }),
+        ),
+        lastCounter,
+      );
+      const result = nextTimestamp(lastCounter);
+      assertOk(result, createTimestamp({ millis: makeMillis(1) }));
+      assertEqual(
+        timestampBytesToTimestamp(timestampToTimestampBytes(result.value)),
+        result.value,
+      );
+    });
+
+    it(`${operation} permits rollover at the drift limit and rejects the next millisecond`, () => {
+      assertOk(
+        nextTimestamp(
+          createTimestamp({
+            millis: makeMillis(defaultTimestampMaxDrift - 1),
+            counter: maxCounter,
+          }),
+        ),
+        createTimestamp({ millis: makeMillis(defaultTimestampMaxDrift) }),
+      );
       assertErr(
-        receiveTimestamp(deps0)(
-          makeNode2Timestamp(),
+        nextTimestamp(
           createTimestamp({
-            millis: makeMillis(minMillis + defaultTimestampMaxDrift + 1),
+            millis: makeMillis(defaultTimestampMaxDrift),
+            counter: maxCounter,
           }),
         ),
-        expected,
+        {
+          type: "TimestampDriftError",
+          now: minMillis,
+          timestamp: createTimestamp({
+            millis: makeMillis(defaultTimestampMaxDrift + 1),
+          }),
+          cause: "local",
+        },
       );
     });
 
-    it("returns TimestampCounterOverflowError for counter overflow", () => {
-      assertErr(
-        receiveTimestamp(deps0)(
-          makeNode1Timestamp(0, maxCounter),
-          makeNode2Timestamp(0, maxCounter),
+    it(`${operation} permits the maximum millis and throws on rollover beyond it`, () => {
+      const now = makeMillis(maxMillis - 1);
+      assertOk(
+        nextTimestamp(
+          createTimestamp({
+            millis: makeMillis(maxMillis - 1),
+            counter: maxCounter,
+          }),
+          now,
         ),
-        { type: "TimestampCounterOverflowError" },
+        createTimestamp({ millis: maxMillis }),
       );
+      assertThrowsInstanceOf(() => {
+        nextTimestamp(
+          createTimestamp({ millis: maxMillis, counter: maxCounter }),
+          now,
+        );
+      }, Error);
     });
+  }
+
+  it("exposes the failures of each operation", () => {
+    assertType<
+      ReturnType<ReturnType<typeof sendTimestamp>>,
+      Result<Timestamp, TimestampDriftError>
+    >();
+    assertType<
+      ReturnType<ReturnType<typeof receiveTimestamp>>,
+      Result<Timestamp, TimestampDriftError>
+    >();
+    assertType<Parameters<typeof sendTimestamp>, [TimestampConfigDep]>();
+    assertType<
+      Parameters<ReturnType<typeof sendTimestamp>>,
+      [Timestamp, Millis]
+    >();
+    assertType<Parameters<typeof receiveTimestamp>, [TimestampConfigDep]>();
+    assertType<
+      Parameters<ReturnType<typeof receiveTimestamp>>,
+      [Timestamp, Timestamp, Millis]
+    >();
+    // @ts-expect-error TimestampCounterOverflowError is no longer exported; counters roll over.
+    type _RemovedError = import("../index.ts").TimestampCounterOverflowError;
   });
 });