@doync/client 0.1.0

package/src/replica/track.ts

@@ -0,0 +1,190 @@
+import type { LocalDb, LocalRow } from '../port'
+
+/**
+ * Replica engine track + LocalDb twin of server `runEngineTrack` (ADR-0024 /
+ * #159). Drizzle migrations under `./db/` via `*.sql?raw` (#156); journal by
+ * idx; split on statement-breakpoint. Ledger `__doync_engine` survives wipe
+ * with pending + clientId.
+ */
+import migration0000 from './db/0000_replica_engine_v0.sql?raw'
+import migration0001 from './db/0001_release_stamps.sql?raw'
+import journal from './db/meta/_journal.json'
+import { readMeta, writeMeta } from './meta'
+
+/** One ordered engine-track step: the statements of one migration file. */
+export type EngineTrackStep = readonly string[]
+
+/**
+ * Drizzle-kit journal shape (min fields we consume). Kept local so the client
+ * does not depend on drizzle-kit at runtime.
+ */
+type Journal = {
+  readonly entries: readonly {
+    readonly idx: number
+    readonly tag: string
+  }[]
+}
+
+/** Migration tag → raw SQL text, filled by the raw imports above. */
+const MIGRATION_SQL: Readonly<Record<string, string>> = {
+  '0000_replica_engine_v0': migration0000,
+  '0001_release_stamps': migration0001,
+}
+
+/**
+ * Assembled track: journal order, each migration split on drizzle's breakpoint
+ * marker. Empty statements (trailing markers) drop out.
+ */
+export const REPLICA_ENGINE_TRACK: readonly EngineTrackStep[] = (
+  journal as Journal
+).entries
+  .slice()
+  .sort((a, b) => a.idx - b.idx)
+  .map((entry) => {
+    const sql = MIGRATION_SQL[entry.tag]
+    if (sql === undefined) {
+      throw new Error(
+        `doync: replica engine track missing sql for journal tag ${JSON.stringify(entry.tag)}`,
+      )
+    }
+    return sql
+      .split(/-->\s*statement-breakpoint/)
+      .map((s) => s.trim())
+      .filter((s) => s.length > 0)
+  })
+
+/** Outcome of applying (or rebuilding) the replica engine track. */
+export type EngineTrackResult = {
+  /**
+   * True when ledger was above bundled length: engine tables wiped/rebuilt,
+   * survivors restored best-effort. Caller should finish consumer
+   * wipe-and-resync.
+   */
+  readonly rolledBack: boolean
+}
+
+/** Unversioned ledger bootstrap — created before any track step. */
+function ensureEngineLedger(db: LocalDb): void {
+  db.exec(
+    `CREATE TABLE IF NOT EXISTS __doync_engine (
+       k TEXT PRIMARY KEY,
+       v
+     ) WITHOUT ROWID`,
+  )
+}
+
+/**
+ * Apply every track step from `fromVersion` (0-based exclusive start of the
+ * next step) up to the track length, recording `track_version` after each.
+ */
+function applyTrackFrom(db: LocalDb, fromVersion: number): void {
+  let version = fromVersion
+  while (version < REPLICA_ENGINE_TRACK.length) {
+    const step = REPLICA_ENGINE_TRACK[version]
+    if (step === undefined) break
+    const next = version + 1
+    for (const statement of step) {
+      db.exec(statement)
+    }
+    db.exec(
+      `INSERT INTO __doync_engine (k, v) VALUES ('track_version', ?)
+         ON CONFLICT (k) DO UPDATE SET v = excluded.v`,
+      next,
+    )
+    version = next
+  }
+}
+
+/**
+ * LocalDb twin of the server's `runEngineTrack` (packages/server/src/boot.ts):
+ *
+ * 1. Create `__doync_engine (k, v)` unversioned (`CREATE TABLE IF NOT EXISTS`).
+ * 2. Read `track_version` (absent → 0).
+ * 3. Rollback tripwire: version above bundled length → `console.warn`, rebuild
+ *    engine tables from scratch (preserve pending + clientId best-effort),
+ *    return `{ rolledBack: true }`. NOT a throw (Origin-only).
+ * 4. Else apply every step above the ledger in order, record the new version after
+ *    each step.
+ */
+export function runReplicaEngineTrack(db: LocalDb): EngineTrackResult {
+  ensureEngineLedger(db)
+  const recorded = db.exec<{ v: string | number | null }>(
+    `SELECT v FROM __doync_engine WHERE k = 'track_version'`,
+  )
+  let version = recorded.length === 0 ? 0 : Number(recorded[0]?.v)
+  if (!Number.isFinite(version) || version < 0) version = 0
+
+  if (version > REPLICA_ENGINE_TRACK.length) {
+    console.warn(
+      `doync: replica engine track_version ${version} is above bundled track ` +
+        `length ${REPLICA_ENGINE_TRACK.length} — wiping engine tables and ` +
+        `rebuilding (code rollback against a newer database). Consumer state ` +
+        `will resync through wipe-and-resync.`,
+    )
+    rebuildEngineTables(db)
+    return { rolledBack: true }
+  }
+  try {
+    applyTrackFrom(db, version)
+  } catch (error) {
+    console.warn(
+      `doync: replica engine track failed at version ${version} — wiping ` +
+        `engine tables and rebuilding (code rollback against a newer database). ` +
+        `Consumer state will resync through wipe-and-resync.`,
+      error,
+    )
+    rebuildEngineTables(db)
+    return { rolledBack: true }
+  }
+  return { rolledBack: false }
+}
+
+/**
+ * Wipe and re-apply engine track (tripwire). Best-effort capture of survivors
+ * before DROP (wipe-and-resync-shaped, not forget).
+ */
+function rebuildEngineTables(db: LocalDb): void {
+  type PendingRow = LocalRow & {
+    mutation_id: number
+    name: string
+    args: string
+    idem_key: string | null
+  }
+  let clientId: string | null = null
+  let nextMutationId: string | null = null
+  let logoutBehavior: string | null = null
+  let pending: PendingRow[] = []
+  try {
+    clientId = readMeta(db, 'client_id')
+    nextMutationId = readMeta(db, 'next_mutation_id')
+    logoutBehavior = readMeta(db, 'logout_behavior')
+    pending = db.exec<PendingRow>(
+      `SELECT mutation_id, name, args, idem_key FROM __doync_pending`,
+    )
+  } catch {
+    // Unknown table shape under true rollback — survivors gone.
+  }
+
+  db.exec(`DROP TABLE IF EXISTS __doync_release_stamp`)
+  db.exec(`DROP TABLE IF EXISTS __doync_membership`)
+  db.exec(`DROP TABLE IF EXISTS __doync_meta`)
+  db.exec(`DROP TABLE IF EXISTS __doync_pending`)
+  db.exec(`DROP TABLE IF EXISTS __doync_engine`)
+
+  ensureEngineLedger(db)
+  applyTrackFrom(db, 0)
+
+  if (clientId !== null) writeMeta(db, 'client_id', clientId)
+  if (nextMutationId !== null) writeMeta(db, 'next_mutation_id', nextMutationId)
+  if (logoutBehavior !== null) writeMeta(db, 'logout_behavior', logoutBehavior)
+  for (const row of pending) {
+    db.exec(
+      `INSERT INTO __doync_pending (mutation_id, name, args, idem_key)
+         VALUES (?, ?, ?, ?)`,
+      row.mutation_id,
+      row.name,
+      row.args,
+      row.idem_key,
+    )
+  }
+}

package/src/socket-reconnect.ts

@@ -0,0 +1,242 @@
+// ADR-0016; closeio/doync#90/#185 — shared reconnect policy for web and mobile.
+// Buffers sends, exponential backoff on unexpected close, keepalive ping,
+// drops stale outbox on reconnect (re-handshake resends pending).
+
+import { PING_FRAME } from '@doync/core/internal'
+
+/**
+ * Minimal socket surface the reconnect coordinator drives — a structural subset
+ * of browser `WebSocket` so fakes work under test.
+ */
+export interface ReconnectSocket {
+  readonly readyState: 'connecting' | 'open' | 'closed'
+  send(frame: string): void
+  close(): void
+  onopen: (() => void) | null
+  onmessage: ((data: string) => void) | null
+  /**
+   * Socket closed. `code` is the WebSocket close code when available (1008 =
+   * auth-close).
+   */
+  onclose: ((code?: number) => void) | null
+  /** Transport-level error; browsers fire it before `onclose`. */
+  onerror: (() => void) | null
+}
+
+/**
+ * How an unexpected drop looked: optional WebSocket close `code`, and whether a
+ * transport error preceded the close. Feeds disconnected / error / needs-auth
+ * status decisions.
+ */
+export interface SocketCloseInfo {
+  readonly code?: number
+  readonly wasError?: boolean
+}
+
+/** Environment the reconnect coordinator needs (all injectable for tests). */
+export interface ReconnectingSocketConfig {
+  /** Open a fresh server socket. Called on `open()` and each reconnect. */
+  connect(): ReconnectSocket
+  /**
+   * Fired on every (re)open — host should re-handshake and re-send pending
+   * pushes.
+   */
+  onReconnect(): void
+  /** A (re)connect attempt started (initial open and every backoff retry). */
+  onConnecting?(): void
+  /** Unexpected drop (not an explicit `close()`). Drives connection status. */
+  onDisconnected?(info: SocketCloseInfo): void
+  /** Server→client frame (JSON text). */
+  onMessage?(data: string): void
+  /** Schedule a reconnect after `delayMs` (defaults to `setTimeout`). */
+  schedule?(callback: () => void, delayMs: number): void
+  /**
+   * Register a repeating keepalive tick; return a canceller (defaults to
+   * `setInterval` / `clearInterval`).
+   */
+  scheduleInterval?(callback: () => void, ms: number): () => void
+  /** Backoff base in ms (first retry). Default 250. */
+  backoffBaseMs?: number
+  /** Backoff cap in ms. Default 10_000. */
+  backoffMaxMs?: number
+  /** Keepalive ping period in ms while open. Default 30_000. */
+  pingIntervalMs?: number
+}
+
+/** Lifecycle handle for one reconnecting server socket. */
+export interface ReconnectingSocket {
+  /** Whether the socket is currently open. */
+  readonly isConnected: boolean
+  /** Open (idempotent while already open/connecting). */
+  open(): void
+  /** Intentional close — does not reconnect. */
+  close(): void
+  /** Drop and re-establish under backoff (engine-requested). */
+  reconnect(): void
+  /**
+   * Skip pending backoff and dial immediately if not open. No-op while open or
+   * dial already in flight. Use for mobile foreground / web `online`.
+   */
+  reconnectNow(): void
+  /** Enqueue a client→server frame; flushed once open. */
+  send(frame: string): void
+}
+
+const DEFAULT_BACKOFF_BASE_MS = 250
+const DEFAULT_BACKOFF_MAX_MS = 10_000
+const DEFAULT_PING_INTERVAL_MS = 30_000
+
+/**
+ * Create a reconnecting socket coordinator: buffers sends, exponential backoff
+ * on unexpected close, keepalive ping while open, drops the stale outbox on
+ * reconnect (the re-handshake resends pending pushes).
+ */
+export function createReconnectingSocket(
+  config: ReconnectingSocketConfig,
+): ReconnectingSocket {
+  const schedule =
+    config.schedule ??
+    ((cb, delay) => {
+      setTimeout(cb, delay)
+    })
+  const scheduleInterval =
+    config.scheduleInterval ??
+    ((cb, ms) => {
+      const handle = setInterval(cb, ms)
+      return () => clearInterval(handle)
+    })
+  const backoffBaseMs = config.backoffBaseMs ?? DEFAULT_BACKOFF_BASE_MS
+  const backoffMaxMs = config.backoffMaxMs ?? DEFAULT_BACKOFF_MAX_MS
+  const pingIntervalMs = config.pingIntervalMs ?? DEFAULT_PING_INTERVAL_MS
+
+  let socket: ReconnectSocket | null = null
+  const outbox: string[] = []
+  /** Set by `close()` so intentional teardown does not reconnect. */
+  let closedByUs = false
+  /** Failed/closed attempts since last successful open. */
+  let attempt = 0
+  /**
+   * Next open is a reconnect (socket opened at least once). First open keeps
+   * outbox; reconnect drops it (re-handshake resends pending).
+   */
+  let reopening = false
+  /** Cancel keepalive interval; null when not open. */
+  let cancelPing: (() => void) | null = null
+  /**
+   * Bumped to invalidate pending backoff (#185). Injectable `schedule` has no
+   * canceller — generation token lets `reconnectNow()` skip a dial.
+   */
+  let reconnectGeneration = 0
+
+  function stopPing(): void {
+    cancelPing?.()
+    cancelPing = null
+  }
+
+  function startPing(): void {
+    stopPing()
+    cancelPing = scheduleInterval(() => {
+      // Exact DO keepalive bytes (ADR-0016); skip if socket closed between ticks.
+      if (socket?.readyState === 'open') socket.send(PING_FRAME)
+    }, pingIntervalMs)
+  }
+
+  function flushOutbox(): void {
+    if (!socket || socket.readyState !== 'open') return
+    while (outbox.length > 0) {
+      const frame = outbox.shift()
+      if (frame !== undefined) socket.send(frame)
+    }
+  }
+
+  function scheduleReconnect(): void {
+    const delay = Math.min(backoffBaseMs * 2 ** attempt, backoffMaxMs)
+    attempt++
+    const gen = reconnectGeneration
+    schedule(() => {
+      if (closedByUs) return
+      // reconnectNow/later schedule stole this slot — no double-dial.
+      if (gen !== reconnectGeneration) return
+      connect()
+    }, delay)
+  }
+
+  function connect(): void {
+    if (socket && socket.readyState !== 'closed') return
+    // Surface connecting through the whole backoff, not just first open (#102).
+    config.onConnecting?.()
+    const next = config.connect()
+    socket = next
+    // Transport error on THIS socket before close => error status vs disconnected.
+    let errored = false
+    next.onopen = () => {
+      // A superseded socket (close then open before the prior onclose) must not
+      // drive handshake / ping of the abandoned dial (closeio/doync#319).
+      if (socket !== next) return
+      attempt = 0
+      // Reconnect drops stale outbox (re-handshake resends); first open keeps it.
+      if (reopening) outbox.length = 0
+      reopening = true
+      config.onReconnect()
+      flushOutbox()
+      startPing()
+    }
+    next.onmessage = (data: string) => {
+      if (socket !== next) return
+      config.onMessage?.(data)
+    }
+    next.onerror = () => {
+      if (socket !== next) return
+      errored = true
+    }
+    next.onclose = (code?: number) => {
+      // Browser WebSocket.close() delivers onclose asynchronously. Last-out
+      // teardown (ADR-0034 / #280) closes, then a new tab may open() before that
+      // onclose lands. The late event must not null the NEW socket or schedule a
+      // reconnect that races the intentional redial — otherwise the tab wedges
+      // `disconnected` with no usable dial (closeio/doync#319).
+      if (socket !== next) return
+      socket = null
+      stopPing()
+      // Report drop unless we closed; 1008 included (#102). Auth stays sticky on hub.
+      if (!closedByUs) config.onDisconnected?.({ code, wasError: errored })
+      // Unexpected close reconnects; close() stays down.
+      if (!closedByUs) scheduleReconnect()
+    }
+  }
+
+  return {
+    get isConnected(): boolean {
+      return socket?.readyState === 'open'
+    },
+    open(): void {
+      closedByUs = false
+      connect()
+    },
+    close(): void {
+      closedByUs = true
+      stopPing()
+      // Invalidate pending backoff so close after drop stays silent.
+      reconnectGeneration++
+      socket?.close()
+      socket = null
+    },
+    reconnect(): void {
+      // Engine drop-and-reopen (client-ahead skew, ADR-0020): onclose schedules
+      // one backoff (closedByUs false). No-op if no socket.
+      socket?.close()
+    },
+    reconnectNow(): void {
+      // Foreground/online nudge (#185): if not open and no dial in flight, skip
+      // backoff and dial now. Open/connecting is no-op.
+      if (socket && socket.readyState !== 'closed') return
+      closedByUs = false
+      reconnectGeneration++
+      connect()
+    },
+    send(frame: string): void {
+      outbox.push(frame)
+      flushOutbox()
+    },
+  }
+}

package/src/socket.ts

@@ -0,0 +1,44 @@
+import type { ClientMessage, ServerMessage } from '@doync/core/internal'
+
+// ADR-0016/0019 (transport-agnostic Mirror socket seam).
+/**
+ * Minimal transport the client engine uses to talk to its Mirror. Platform
+ * adapters supply WebSocket / reconnect policy behind this shape.
+ */
+export interface SyncSocket {
+  /** Send one client→server frame (`connect` / `subscribe` / `push`). */
+  send(message: ClientMessage): void
+  /**
+   * Register frame and lifecycle handlers (once at construction). `open` fires
+   * on every (re)connect so the engine can re-handshake; `close` pauses
+   * outbound traffic until the next `open`.
+   */
+  setHandlers(handlers: SyncSocketHandlers): void
+  /**
+   * Drop and re-establish under the adapter's backoff. Used after a
+   * client-ahead schema skew; the next successful open triggers re-handshake.
+   */
+  reconnect(): void
+}
+
+/**
+ * Transient transport states a reconnecting adapter may report: `connecting`
+ * (dial/backoff) and `error` (abnormal drop). Connected / disconnected ride
+ * `open`/`close`; auth failure is inferred from frames.
+ */
+export type SeamStatus = 'connecting' | 'error'
+
+/** Handlers the engine registers on a {@link SyncSocket}. */
+export interface SyncSocketHandlers {
+  /** A server→client frame arrived. */
+  message(message: ServerMessage): void
+  /** Socket (re)connected — engine handshakes and re-sends pending. */
+  open(): void
+  /** Socket disconnected — engine queues writes until the next open. */
+  close(): void
+  /**
+   * Optional transient status (`connecting` / `error`). Adapters without
+   * reconnect simply never call this.
+   */
+  status?(status: SeamStatus): void
+}

package/src/sql-raw.d.ts

@@ -0,0 +1,4 @@
+declare module '*.sql?raw' {
+  const content: string
+  export default content
+}