@baukit/sync-client 0.7.1 → 0.7.3

package/src/error.ts

@@ -0,0 +1,116 @@
+/** Machine-readable failure metadata. Products own any message shown to users. */
+export type SyncFailure =
+  | { readonly kind: 'auth' }
+  | { readonly kind: 'partition_mismatch' }
+  | { readonly kind: 'rate_limited'; readonly retryAt: string }
+  | { readonly kind: 'network' }
+  | { readonly kind: 'server' }
+  | { readonly kind: 'payload_compatibility' }
+  | { readonly kind: 'local_apply' };
+
+/** A sync request failed. `retryable` decides whether a later attempt may win. */
+export class SyncTransportError extends Error {
+  constructor(
+    message: string,
+    readonly retryable: boolean,
+    override readonly cause?: unknown,
+  ) {
+    super(message);
+    this.name = 'SyncTransportError';
+  }
+}
+
+/** Credentials were rejected. Never retryable without re-authentication. */
+export class SyncAuthError extends SyncTransportError {
+  readonly kind = 'auth';
+
+  constructor(message: string, cause?: unknown) {
+    super(message, false, cause);
+    this.name = 'SyncAuthError';
+  }
+}
+
+/** The request did not reach a usable HTTP response. */
+export class SyncNetworkError extends SyncTransportError {
+  readonly kind = 'network';
+
+  constructor(message: string, cause?: unknown) {
+    super(message, true, cause);
+    this.name = 'SyncNetworkError';
+  }
+}
+
+/** The server returned an HTTP failure other than authentication or rate limiting. */
+export class SyncServerError extends SyncTransportError {
+  readonly kind = 'server';
+
+  constructor(message: string, retryable: boolean, cause?: unknown) {
+    super(message, retryable, cause);
+    this.name = 'SyncServerError';
+  }
+}
+
+/** HTTP 429 with its raw `Retry-After` value and resolved retry time. */
+export class SyncRateLimitError extends SyncTransportError {
+  readonly kind = 'rate_limited';
+
+  constructor(
+    message: string,
+    readonly retryAt: string,
+    readonly retryAfter: string | null,
+    cause?: unknown,
+  ) {
+    super(message, true, cause);
+    this.name = 'SyncRateLimitError';
+  }
+}
+
+/**
+ * The server rejected the caller's local-data partition, so the local database
+ * belongs to an erased or replaced owner and must not be reused.
+ */
+export class SyncPartitionMismatchError extends SyncTransportError {
+  readonly kind = 'partition_mismatch';
+
+  constructor(message: string, cause?: unknown) {
+    super(message, false, cause);
+    this.name = 'SyncPartitionMismatchError';
+  }
+}
+
+/** A decoded response violates the sync payload contract. */
+export class SyncPayloadCompatibilityError extends SyncTransportError {
+  readonly kind = 'payload_compatibility';
+
+  constructor(message: string, cause?: unknown) {
+    super(message, false, cause);
+    this.name = 'SyncPayloadCompatibilityError';
+  }
+}
+
+/** Remote data or a cursor could not be committed to local storage. */
+export class SyncLocalApplyError extends Error {
+  readonly kind = 'local_apply';
+
+  constructor(message: string, cause?: unknown) {
+    super(message, { cause });
+    this.name = 'SyncLocalApplyError';
+  }
+}
+
+/** Maps package errors onto store failure metadata. */
+export function syncFailureFromError(error: unknown): SyncFailure {
+  if (error instanceof SyncRateLimitError) {
+    return { kind: 'rate_limited', retryAt: error.retryAt };
+  }
+  if (error instanceof SyncAuthError) return { kind: 'auth' };
+  if (error instanceof SyncPartitionMismatchError) return { kind: 'partition_mismatch' };
+  if (error instanceof SyncNetworkError) return { kind: 'network' };
+  if (error instanceof SyncServerError) return { kind: 'server' };
+  if (error instanceof SyncPayloadCompatibilityError) return { kind: 'payload_compatibility' };
+  if (error instanceof SyncLocalApplyError) return { kind: 'local_apply' };
+  if (error instanceof SyncTransportError) {
+    return error.retryable ? { kind: 'network' } : { kind: 'server' };
+  }
+  return { kind: 'local_apply' };
+}

package/src/expo.test.ts

@@ -0,0 +1,137 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const runtime = vi.hoisted(() => ({
+  appState: 'active',
+  platform: 'ios',
+  appStateListener: undefined as ((state: string) => void) | undefined,
+  networkListener: undefined as
+    ((state: { isConnected?: boolean; isInternetReachable?: boolean }) => void) | undefined,
+  removeAppState: vi.fn(),
+  removeNetwork: vi.fn(),
+  getNetworkStateAsync: vi.fn(),
+}));
+
+vi.mock('react-native', () => ({
+  AppState: {
+    get currentState() {
+      return runtime.appState;
+    },
+    addEventListener: vi.fn(
+      (_event: string, listener: (state: string) => void): { remove(): void } => {
+        runtime.appStateListener = listener;
+        return { remove: runtime.removeAppState };
+      },
+    ),
+  },
+  Platform: {
+    get OS() {
+      return runtime.platform;
+    },
+  },
+}));
+
+vi.mock('expo-network', () => ({
+  getNetworkStateAsync: runtime.getNetworkStateAsync,
+  addNetworkStateListener: vi.fn(
+    (
+      listener: (state: { isConnected?: boolean; isInternetReachable?: boolean }) => void,
+    ): { remove(): void } => {
+      runtime.networkListener = listener;
+      return { remove: runtime.removeNetwork };
+    },
+  ),
+}));
+
+import { createExpoSyncEnvironment } from './expo.js';
+import { createExpoSyncEnvironment as createFromPackageExport } from '@baukit/sync-client/expo';
+
+describe('createExpoSyncEnvironment', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    runtime.appState = 'active';
+    runtime.platform = 'ios';
+    runtime.appStateListener = undefined;
+    runtime.networkListener = undefined;
+    runtime.getNetworkStateAsync.mockResolvedValue({
+      isConnected: true,
+      isInternetReachable: true,
+    });
+  });
+
+  it('resolves the built Expo package export', () => {
+    expect(createFromPackageExport).toBeTypeOf('function');
+  });
+
+  it('maps AppState changes onto active state and removes the subscription', () => {
+    const listener = vi.fn();
+    const environment = createExpoSyncEnvironment();
+
+    expect(environment.isActive()).toBe(true);
+    const unsubscribe = environment.subscribeActive(listener);
+    runtime.appStateListener?.('background');
+    runtime.appStateListener?.('active');
+
+    expect(listener.mock.calls).toEqual([[false], [true]]);
+    unsubscribe();
+    expect(runtime.removeAppState).toHaveBeenCalledOnce();
+  });
+
+  it('reports a native transition from offline to usable connectivity once', async () => {
+    runtime.getNetworkStateAsync.mockResolvedValue({
+      isConnected: false,
+      isInternetReachable: false,
+    });
+    const listener = vi.fn();
+    const unsubscribe = createExpoSyncEnvironment().subscribeOnline(listener);
+    await Promise.resolve();
+
+    runtime.networkListener?.({ isConnected: true, isInternetReachable: false });
+    runtime.networkListener?.({ isConnected: true });
+    runtime.networkListener?.({ isConnected: true, isInternetReachable: true });
+
+    expect(listener).toHaveBeenCalledOnce();
+    unsubscribe();
+    expect(runtime.removeNetwork).toHaveBeenCalledOnce();
+  });
+
+  it('uses browser online events on Expo web', () => {
+    runtime.platform = 'web';
+    const addEventListener = vi.fn();
+    const removeEventListener = vi.fn();
+    const originalWindow = Object.getOwnPropertyDescriptor(globalThis, 'window');
+    Object.defineProperty(globalThis, 'window', {
+      configurable: true,
+      value: { addEventListener, removeEventListener },
+    });
+    const listener = vi.fn();
+
+    try {
+      const unsubscribe = createExpoSyncEnvironment().subscribeOnline(listener);
+      expect(addEventListener).toHaveBeenCalledWith('online', listener);
+      unsubscribe();
+      expect(removeEventListener).toHaveBeenCalledWith('online', listener);
+    } finally {
+      if (originalWindow) {
+        Object.defineProperty(globalThis, 'window', originalWindow);
+      } else {
+        Reflect.deleteProperty(globalThis, 'window');
+      }
+    }
+  });
+
+  it('uses injected timers', () => {
+    const handle = {};
+    const timers = {
+      setInterval: vi.fn(() => handle),
+      clearInterval: vi.fn(),
+    };
+    const environment = createExpoSyncEnvironment({ timers });
+    const callback = vi.fn();
+
+    expect(environment.setInterval(callback, 1234)).toBe(handle);
+    environment.clearInterval(handle);
+
+    expect(timers.setInterval).toHaveBeenCalledWith(callback, 1234);
+    expect(timers.clearInterval).toHaveBeenCalledWith(handle);
+  });
+});

package/src/expo.ts

@@ -0,0 +1,101 @@
+import * as Network from 'expo-network';
+import { AppState, Platform } from 'react-native';
+
+import type { SyncSchedulerEnvironment, SyncSchedulerTimer } from './scheduler.js';
+
+export interface ExpoSyncTimers {
+  setInterval(callback: () => void, milliseconds: number): SyncSchedulerTimer;
+  clearInterval(handle: SyncSchedulerTimer): void;
+}
+
+export interface ExpoSyncEnvironmentOptions {
+  /** Overrides global timers, primarily for deterministic scheduler tests. */
+  timers?: ExpoSyncTimers;
+}
+
+interface ExpoNetworkModule {
+  getNetworkStateAsync(): Promise<Network.NetworkState>;
+  addNetworkStateListener?: (listener: (state: Network.NetworkState) => void) => { remove(): void };
+}
+
+const defaultTimers: ExpoSyncTimers = {
+  setInterval: (callback, milliseconds) =>
+    globalThis.setInterval(callback, milliseconds) as unknown as SyncSchedulerTimer,
+  clearInterval: (handle) => {
+    globalThis.clearInterval(handle as unknown as ReturnType<typeof globalThis.setInterval>);
+  },
+};
+
+function isUsableNetwork(state: Network.NetworkState): boolean {
+  return state.isConnected === true && state.isInternetReachable !== false;
+}
+
+function subscribeBrowserOnline(listener: () => void): () => void {
+  if (typeof window === 'undefined') {
+    return () => undefined;
+  }
+  window.addEventListener('online', listener);
+  return () => {
+    window.removeEventListener('online', listener);
+  };
+}
+
+function subscribeNativeOnline(listener: () => void): () => void {
+  const network = Network as ExpoNetworkModule;
+  let subscribed = true;
+  let receivedEvent = false;
+  let wasUsable: boolean | null = null;
+
+  void network
+    .getNetworkStateAsync()
+    .then((state) => {
+      if (subscribed && !receivedEvent) {
+        wasUsable = isUsableNetwork(state);
+      }
+    })
+    .catch(() => undefined);
+
+  const subscription = network.addNetworkStateListener?.((state) => {
+    if (!subscribed) return;
+    receivedEvent = true;
+    const usable = isUsableNetwork(state);
+    if (wasUsable === false && usable) {
+      listener();
+    }
+    wasUsable = usable;
+  });
+
+  return () => {
+    subscribed = false;
+    subscription?.remove();
+  };
+}
+
+/** Creates the Expo runtime environment consumed by {@link SyncScheduler}. */
+export function createExpoSyncEnvironment(
+  options: ExpoSyncEnvironmentOptions = {},
+): SyncSchedulerEnvironment {
+  const timers = options.timers ?? defaultTimers;
+  return {
+    isActive: () => AppState.currentState === 'active',
+    subscribeActive(listener) {
+      const subscription = AppState.addEventListener('change', (state) => {
+        listener(state === 'active');
+      });
+      return () => {
+        subscription.remove();
+      };
+    },
+    subscribeOnline(listener) {
+      return Platform.OS === 'web'
+        ? subscribeBrowserOnline(listener)
+        : subscribeNativeOnline(listener);
+    },
+    setInterval(callback, milliseconds) {
+      return timers.setInterval(callback, milliseconds);
+    },
+    clearInterval(handle) {
+      timers.clearInterval(handle);
+    },
+  };
+}

package/src/hlc.test.ts

@@ -0,0 +1,249 @@
+import { readFileSync } from 'node:fs';
+
+import { describe, expect, it } from 'vitest';
+
+import {
+  compareHybridLogicalTimestamps,
+  decodeHybridLogicalTimestamp,
+  encodeHybridLogicalTimestamp,
+  HybridLogicalClock,
+  HybridLogicalClockError,
+  MAX_HLC_TIMESTAMP,
+  type HlcStorage,
+  type HybridLogicalClockState,
+} from './hlc.js';
+
+interface EncodeVector {
+  readonly wallTimeMs: number;
+  readonly counter: number;
+  readonly timestamp: number;
+}
+
+interface CompareVector {
+  readonly left: number;
+  readonly right: number;
+  readonly ordering: -1 | 0 | 1;
+}
+
+interface MergeVector {
+  readonly deviceId: string;
+  readonly initial: HybridLogicalClockState;
+  readonly physicalTimeMs: number;
+  readonly remoteTimestamp: number;
+  readonly expectedTimestamp: number;
+  readonly expectedState: HybridLogicalClockState;
+}
+
+interface HlcVectors {
+  readonly encode: readonly EncodeVector[];
+  readonly compare: readonly CompareVector[];
+  readonly merge: readonly MergeVector[];
+}
+
+class MemoryStorage implements HlcStorage {
+  readonly values = new Map<string, unknown>();
+
+  public get(key: string): Promise<unknown> {
+    return Promise.resolve(this.values.get(key));
+  }
+
+  public set(key: string, value: HybridLogicalClockState): Promise<void> {
+    this.values.set(key, structuredClone(value));
+    return Promise.resolve();
+  }
+}
+
+class BlockingStorage extends MemoryStorage {
+  readonly writes: HybridLogicalClockState[] = [];
+  readonly firstWriteStarted: Promise<void>;
+  #reportFirstWrite: () => void = () => undefined;
+  #releaseFirstWrite: () => void = () => undefined;
+  readonly #firstWriteGate: Promise<void>;
+
+  public constructor() {
+    super();
+    this.firstWriteStarted = new Promise((resolve) => {
+      this.#reportFirstWrite = resolve;
+    });
+    this.#firstWriteGate = new Promise((resolve) => {
+      this.#releaseFirstWrite = resolve;
+    });
+  }
+
+  public override async set(key: string, value: HybridLogicalClockState): Promise<void> {
+    this.writes.push(structuredClone(value));
+    if (this.writes.length === 1) {
+      this.#reportFirstWrite();
+      await this.#firstWriteGate;
+    }
+    await super.set(key, value);
+  }
+
+  public releaseFirstWrite(): void {
+    this.#releaseFirstWrite();
+  }
+}
+
+class FailingOnceStorage extends MemoryStorage {
+  #failed = false;
+
+  public override set(key: string, value: HybridLogicalClockState): Promise<void> {
+    if (!this.#failed) {
+      this.#failed = true;
+      return Promise.reject(new Error('write failed'));
+    }
+    return super.set(key, value);
+  }
+}
+
+const fixtureUrl = new URL('../../../../fixtures/hlc/vectors-v1.json', import.meta.url);
+const readUtf8File = readFileSync as unknown as (path: URL, encoding: 'utf8') => string;
+const vectors = JSON.parse(readUtf8File(fixtureUrl, 'utf8')) as HlcVectors;
+
+describe('HybridLogicalClock', () => {
+  it('advances while physical time stalls and moves backward', async () => {
+    let physical = 1_000;
+    const clock = await HybridLogicalClock.open('device-a', undefined, () => physical);
+
+    const first = await clock.now();
+    const stalled = await clock.now();
+    physical = 900;
+    const backward = await clock.now();
+
+    expect(first).toBeLessThan(stalled);
+    expect(stalled).toBeLessThan(backward);
+    expect(decodeHybridLogicalTimestamp(backward)).toEqual({ wallTimeMs: 1_000, counter: 2 });
+  });
+
+  it('rolls the logical counter into the next millisecond', async () => {
+    const storage = new MemoryStorage();
+    storage.values.set('hlc-state', { wallTimeMs: 1_000, counter: 999, deviceId: 'device-a' });
+    const clock = await HybridLogicalClock.open('device-a', storage, () => 1_000);
+
+    await expect(clock.now()).resolves.toBe(1_001_001);
+    expect(clock.snapshot()).toEqual({ wallTimeMs: 1_001, counter: 0, deviceId: 'device-a' });
+  });
+
+  it('restores matching state', async () => {
+    const storage = new MemoryStorage();
+    storage.values.set('hlc-state', { wallTimeMs: 2_000, counter: 7, deviceId: 'device-a' });
+    const clock = await HybridLogicalClock.open('device-a', storage, () => 1_000);
+
+    await expect(clock.now()).resolves.toBe(2_000_009);
+    expect(clock.snapshot()).toEqual({ wallTimeMs: 2_000, counter: 8, deviceId: 'device-a' });
+  });
+
+  it.each([
+    null,
+    { wallTimeMs: -1, counter: 0, deviceId: 'device-a' },
+    { wallTimeMs: 1_000, counter: 1_000, deviceId: 'device-a' },
+    { wallTimeMs: Number.MAX_SAFE_INTEGER, counter: 0, deviceId: 'device-a' },
+    { wallTimeMs: 1_000, counter: 2, deviceId: 'device-b' },
+  ])('resets corrupt or foreign stored state %#', async (stored) => {
+    const storage = new MemoryStorage();
+    storage.values.set('hlc-state', stored);
+    const clock = await HybridLogicalClock.open('device-a', storage, () => 10);
+
+    await expect(clock.now()).resolves.toBe(10_001);
+  });
+
+  it('observes remote time and leaves state unchanged for invalid input', async () => {
+    const clock = await HybridLogicalClock.open('device-a', undefined, () => 900);
+
+    await expect(clock.observe(1_000_006)).resolves.toBe(1_000_007);
+    const snapshot = clock.snapshot();
+    await expect(clock.observe(0)).rejects.toMatchObject({ code: 'invalid_timestamp' });
+    expect(clock.snapshot()).toEqual(snapshot);
+    expect(compareHybridLogicalTimestamps(0, 1)).toBeNull();
+  });
+
+  it('serializes concurrent persisted calls', async () => {
+    const storage = new BlockingStorage();
+    const clock = await HybridLogicalClock.open('device-a', storage, () => 1_000);
+
+    const first = clock.now();
+    const second = clock.now();
+    const observed = clock.observe(1_000_010);
+    await storage.firstWriteStarted;
+    expect(storage.writes).toHaveLength(1);
+    storage.releaseFirstWrite();
+
+    await expect(Promise.all([first, second, observed])).resolves.toEqual([
+      1_000_001, 1_000_002, 1_000_011,
+    ]);
+    expect(storage.writes).toHaveLength(3);
+    expect(clock.snapshot()).toEqual({ wallTimeMs: 1_000, counter: 10, deviceId: 'device-a' });
+  });
+
+  it('continues the persistence queue after a failed write', async () => {
+    const storage = new FailingOnceStorage();
+    const clock = await HybridLogicalClock.open('device-a', storage, () => 1_000);
+
+    await expect(clock.now()).rejects.toThrow('write failed');
+    expect(clock.snapshot()).toEqual({ wallTimeMs: 0, counter: 0, deviceId: 'device-a' });
+    await expect(clock.now()).resolves.toBe(1_000_001);
+  });
+
+  it('supports the maximum encoded value and reports exhaustion', async () => {
+    expect(encodeHybridLogicalTimestamp(9_007_199_254_740, 990)).toBe(MAX_HLC_TIMESTAMP);
+    expect(decodeHybridLogicalTimestamp(MAX_HLC_TIMESTAMP)).toEqual({
+      wallTimeMs: 9_007_199_254_740,
+      counter: 990,
+    });
+    expect(() => encodeHybridLogicalTimestamp(9_007_199_254_740, 991)).toThrow(
+      HybridLogicalClockError,
+    );
+
+    const storage = new MemoryStorage();
+    storage.values.set('hlc-state', {
+      wallTimeMs: 9_007_199_254_740,
+      counter: 990,
+      deviceId: 'device-a',
+    });
+    const clock = await HybridLogicalClock.open('device-a', storage, () => 0);
+    await expect(clock.now()).rejects.toMatchObject({ code: 'exceeds_safe_integer' });
+    expect(clock.snapshot()).toEqual({
+      wallTimeMs: 9_007_199_254_740,
+      counter: 990,
+      deviceId: 'device-a',
+    });
+  });
+
+  it('rejects a blank device id and invalid physical time with typed errors', async () => {
+    await expect(HybridLogicalClock.open('   ')).rejects.toMatchObject({
+      code: 'empty_device_id',
+    });
+    const clock = await HybridLogicalClock.open('device-a', undefined, () => -1);
+    await expect(clock.now()).rejects.toMatchObject({ code: 'invalid_physical_clock' });
+  });
+});
+
+describe('cross-runtime HLC vectors', () => {
+  it('matches the Rust encoding, comparison, observation, and state corpus', async () => {
+    for (const vector of vectors.encode) {
+      expect(encodeHybridLogicalTimestamp(vector.wallTimeMs, vector.counter)).toBe(
+        vector.timestamp,
+      );
+      expect(decodeHybridLogicalTimestamp(vector.timestamp)).toEqual({
+        wallTimeMs: vector.wallTimeMs,
+        counter: vector.counter,
+      });
+    }
+
+    for (const vector of vectors.compare) {
+      expect(compareHybridLogicalTimestamps(vector.left, vector.right)).toBe(vector.ordering);
+    }
+
+    for (const vector of vectors.merge) {
+      const storage = new MemoryStorage();
+      storage.values.set('hlc-state', vector.initial);
+      const clock = await HybridLogicalClock.open(
+        vector.deviceId,
+        storage,
+        () => vector.physicalTimeMs,
+      );
+      await expect(clock.observe(vector.remoteTimestamp)).resolves.toBe(vector.expectedTimestamp);
+      expect(clock.snapshot()).toEqual(vector.expectedState);
+    }
+  });
+});