@syncular/client 0.0.1-100

package/src/blobs/migrate.ts

@@ -0,0 +1,67 @@
+/**
+ * @syncular/client - Blob storage migrations
+ */
+
+import type { Kysely } from 'kysely';
+
+/**
+ * Ensures the client blob schema exists in the database.
+ * Safe to call multiple times (idempotent).
+ */
+export async function ensureClientBlobSchema<DB>(
+  db: Kysely<DB>
+): Promise<void> {
+  // Blob cache table
+  await db.schema
+    .createTable('sync_blob_cache')
+    .ifNotExists()
+    .addColumn('hash', 'text', (col) => col.primaryKey())
+    .addColumn('size', 'integer', (col) => col.notNull())
+    .addColumn('mime_type', 'text', (col) => col.notNull())
+    .addColumn('body', 'blob', (col) => col.notNull())
+    .addColumn('encrypted', 'integer', (col) => col.notNull().defaultTo(0))
+    .addColumn('key_id', 'text')
+    .addColumn('cached_at', 'bigint', (col) => col.notNull())
+    .addColumn('last_accessed_at', 'bigint', (col) => col.notNull())
+    .execute();
+
+  await db.schema
+    .createIndex('idx_sync_blob_cache_last_accessed')
+    .ifNotExists()
+    .on('sync_blob_cache')
+    .columns(['last_accessed_at'])
+    .execute();
+
+  // Blob upload outbox table
+  await db.schema
+    .createTable('sync_blob_outbox')
+    .ifNotExists()
+    .addColumn('id', 'integer', (col) => col.primaryKey().autoIncrement())
+    .addColumn('hash', 'text', (col) => col.notNull().unique())
+    .addColumn('size', 'integer', (col) => col.notNull())
+    .addColumn('mime_type', 'text', (col) => col.notNull())
+    .addColumn('body', 'blob', (col) => col.notNull())
+    .addColumn('encrypted', 'integer', (col) => col.notNull().defaultTo(0))
+    .addColumn('key_id', 'text')
+    .addColumn('status', 'text', (col) => col.notNull())
+    .addColumn('attempt_count', 'integer', (col) => col.notNull().defaultTo(0))
+    .addColumn('error', 'text')
+    .addColumn('created_at', 'bigint', (col) => col.notNull())
+    .addColumn('updated_at', 'bigint', (col) => col.notNull())
+    .execute();
+
+  await db.schema
+    .createIndex('idx_sync_blob_outbox_status')
+    .ifNotExists()
+    .on('sync_blob_outbox')
+    .columns(['status', 'created_at'])
+    .execute();
+}
+
+/**
+ * Drops the client blob schema from the database.
+ */
+export async function dropClientBlobSchema<DB>(db: Kysely<DB>): Promise<void> {
+  await db.schema.dropTable('sync_blob_outbox').ifExists().execute();
+  await db.schema.dropTable('sync_blob_cache').ifExists().execute();
+}

package/src/blobs/types.ts

@@ -0,0 +1,84 @@
+/**
+ * @syncular/client - Blob storage types
+ */
+
+import type { Generated } from 'kysely';
+
+// ============================================================================
+// Blob Cache Table
+// ============================================================================
+
+/**
+ * Local blob cache table.
+ * Stores downloaded blobs for offline access.
+ */
+export interface SyncBlobCacheTable {
+  /** SHA-256 hash with prefix: "sha256:<hex>" */
+  hash: string;
+  /** Size in bytes */
+  size: number;
+  /** MIME type */
+  mime_type: string;
+  /** Blob content */
+  body: Uint8Array;
+  /** Whether the blob is encrypted */
+  encrypted: number; // SQLite boolean
+  /** Encryption key ID (if encrypted) */
+  key_id: string | null;
+  /** When the blob was cached */
+  cached_at: number;
+  /** Last accessed timestamp (for LRU eviction) */
+  last_accessed_at: number;
+}
+
+// ============================================================================
+// Blob Upload Outbox Table
+// ============================================================================
+
+export type BlobUploadStatus =
+  | 'pending'
+  | 'uploading'
+  | 'uploaded'
+  | 'confirming'
+  | 'complete'
+  | 'failed';
+
+/**
+ * Blob upload outbox table.
+ * Tracks pending blob uploads for offline support.
+ */
+export interface SyncBlobOutboxTable {
+  /** Local row id */
+  id: Generated<number>;
+  /** SHA-256 hash with prefix: "sha256:<hex>" */
+  hash: string;
+  /** Size in bytes */
+  size: number;
+  /** MIME type */
+  mime_type: string;
+  /** Blob content (stored locally until upload completes) */
+  body: Uint8Array;
+  /** Whether the blob is encrypted */
+  encrypted: number; // SQLite boolean
+  /** Encryption key ID (if encrypted) */
+  key_id: string | null;
+  /** Upload status */
+  status: BlobUploadStatus;
+  /** Upload attempt count */
+  attempt_count: number;
+  /** Last error message */
+  error: string | null;
+  /** When the upload was queued */
+  created_at: number;
+  /** When the upload was last updated */
+  updated_at: number;
+}
+
+// ============================================================================
+// Database Interface
+// ============================================================================
+
+export interface SyncBlobClientDb {
+  sync_blob_cache: SyncBlobCacheTable;
+  sync_blob_outbox: SyncBlobOutboxTable;
+}

package/src/client.test.ts

@@ -0,0 +1,369 @@
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
+import type { SyncTransport } from '@syncular/core';
+import type { Kysely } from 'kysely';
+import { sql } from 'kysely';
+import { createBunSqliteDb } from '../../dialect-bun-sqlite/src';
+import { ensureClientBlobSchema } from './blobs/migrate';
+import { Client, type ClientBlobStorage } from './client';
+import { SyncEngine } from './engine/SyncEngine';
+import { ClientTableRegistry } from './handlers/registry';
+import { ensureClientSyncSchema } from './migrate';
+import type { SyncClientDb } from './schema';
+
+interface TasksTable {
+  id: string;
+  title: string;
+  server_version: number;
+}
+
+interface TestDb extends SyncClientDb {
+  tasks: TasksTable;
+}
+
+const noopTransport: SyncTransport = {
+  async sync() {
+    return {};
+  },
+  async fetchSnapshotChunk() {
+    return new Uint8Array();
+  },
+};
+
+function createMemoryBlobStorage(): ClientBlobStorage {
+  const memory = new Map<string, Uint8Array>();
+  return {
+    async write(hash, data) {
+      if (data instanceof ReadableStream) {
+        const reader = data.getReader();
+        const chunks: Uint8Array[] = [];
+        let total = 0;
+        while (true) {
+          const chunk = await reader.read();
+          if (chunk.done) break;
+          chunks.push(chunk.value);
+          total += chunk.value.length;
+        }
+        const combined = new Uint8Array(total);
+        let offset = 0;
+        for (const chunk of chunks) {
+          combined.set(chunk, offset);
+          offset += chunk.length;
+        }
+        memory.set(hash, combined);
+        return;
+      }
+      memory.set(hash, new Uint8Array(data));
+    },
+    async read(hash) {
+      const data = memory.get(hash);
+      return data ? new Uint8Array(data) : null;
+    },
+    async delete(hash) {
+      memory.delete(hash);
+    },
+    async exists(hash) {
+      return memory.has(hash);
+    },
+  };
+}
+
+describe('Client conflict events', () => {
+  let db: Kysely<TestDb>;
+  let client: Client<TestDb>;
+  let engine: SyncEngine<TestDb>;
+
+  async function seedConflict(id: string): Promise<void> {
+    const now = Date.now();
+    await sql`
+      insert into ${sql.table('sync_outbox_commits')} (
+        ${sql.ref('id')},
+        ${sql.ref('client_commit_id')},
+        ${sql.ref('status')},
+        ${sql.ref('operations_json')},
+        ${sql.ref('last_response_json')},
+        ${sql.ref('error')},
+        ${sql.ref('created_at')},
+        ${sql.ref('updated_at')},
+        ${sql.ref('attempt_count')},
+        ${sql.ref('acked_commit_seq')},
+        ${sql.ref('schema_version')}
+      ) values (
+        ${'outbox-1'},
+        ${'commit-1'},
+        ${'failed'},
+        ${JSON.stringify([
+          {
+            table: 'tasks',
+            row_id: 't1',
+            op: 'upsert',
+            payload: { id: 't1', title: 'local', server_version: 1 },
+          },
+        ])},
+        ${null},
+        ${'conflict'},
+        ${now},
+        ${now},
+        ${1},
+        ${null},
+        ${1}
+      )
+    `.execute(db);
+
+    await sql`
+      insert into ${sql.table('sync_conflicts')} (
+        ${sql.ref('id')},
+        ${sql.ref('outbox_commit_id')},
+        ${sql.ref('client_commit_id')},
+        ${sql.ref('op_index')},
+        ${sql.ref('result_status')},
+        ${sql.ref('message')},
+        ${sql.ref('code')},
+        ${sql.ref('server_version')},
+        ${sql.ref('server_row_json')},
+        ${sql.ref('created_at')},
+        ${sql.ref('resolved_at')},
+        ${sql.ref('resolution')}
+      ) values (
+        ${id},
+        ${'outbox-1'},
+        ${'commit-1'},
+        ${0},
+        ${'conflict'},
+        ${'server conflict'},
+        ${'CONFLICT'},
+        ${2},
+        ${JSON.stringify({ id: 't1', title: 'server', server_version: 2 })},
+        ${now},
+        ${null},
+        ${null}
+      )
+    `.execute(db);
+  }
+
+  async function runConflictCheck(
+    clientInstance: Client<TestDb>
+  ): Promise<void> {
+    const checker = Reflect.get(clientInstance, 'checkForNewConflicts');
+    if (typeof checker !== 'function') {
+      throw new Error('Expected checkForNewConflicts to be callable');
+    }
+    await checker.call(clientInstance);
+  }
+
+  beforeEach(async () => {
+    db = createBunSqliteDb<TestDb>({ path: ':memory:' });
+    await ensureClientSyncSchema(db);
+    await db.schema
+      .createTable('tasks')
+      .addColumn('id', 'text', (col) => col.primaryKey())
+      .addColumn('title', 'text', (col) => col.notNull())
+      .addColumn('server_version', 'integer', (col) =>
+        col.notNull().defaultTo(0)
+      )
+      .execute();
+
+    const handlers = new ClientTableRegistry<TestDb>();
+    client = new Client<TestDb>({
+      db,
+      transport: noopTransport,
+      tableHandlers: handlers,
+      clientId: 'client-1',
+      actorId: 'u1',
+      subscriptions: [],
+    });
+
+    engine = new SyncEngine<TestDb>({
+      db,
+      transport: noopTransport,
+      shapes: handlers,
+      actorId: 'u1',
+      clientId: 'client-1',
+      subscriptions: [],
+    });
+    Reflect.set(client, 'engine', engine);
+  });
+
+  afterEach(async () => {
+    client.destroy();
+    await db.destroy();
+  });
+
+  it('emits conflict:resolved with the resolved conflict payload', async () => {
+    await seedConflict('conflict-1');
+
+    const resolvedEvents: Array<{ id: string }> = [];
+    client.on('conflict:resolved', (conflict) => {
+      resolvedEvents.push({ id: conflict.id });
+    });
+
+    await client.resolveConflict('conflict-1', { strategy: 'keep-local' });
+
+    expect(resolvedEvents).toEqual([{ id: 'conflict-1' }]);
+
+    const resolvedRow = await sql<{ resolved_at: number | null }>`
+      select ${sql.ref('resolved_at')}
+      from ${sql.table('sync_conflicts')}
+      where ${sql.ref('id')} = ${'conflict-1'}
+      limit 1
+    `.execute(db);
+    expect(resolvedRow.rows[0]?.resolved_at).not.toBeNull();
+  });
+
+  it('emits conflict:new only once per unresolved conflict id', async () => {
+    await seedConflict('conflict-1');
+
+    const newEvents: string[] = [];
+    client.on('conflict:new', (conflict) => {
+      newEvents.push(conflict.id);
+    });
+
+    await runConflictCheck(client);
+    await runConflictCheck(client);
+
+    expect(newEvents).toEqual(['conflict-1']);
+  });
+});
+
+describe('Client blob upload queue recovery', () => {
+  let db: Kysely<TestDb>;
+  let client: Client<TestDb>;
+  let initiateCalls = 0;
+
+  async function insertBlobOutboxRow(input: {
+    hash: string;
+    status: string;
+    attemptCount: number;
+    updatedAt: number;
+  }): Promise<void> {
+    const now = Date.now();
+    await sql`
+      insert into ${sql.table('sync_blob_outbox')} (
+        ${sql.join([
+          sql.ref('hash'),
+          sql.ref('size'),
+          sql.ref('mime_type'),
+          sql.ref('body'),
+          sql.ref('encrypted'),
+          sql.ref('key_id'),
+          sql.ref('status'),
+          sql.ref('attempt_count'),
+          sql.ref('error'),
+          sql.ref('created_at'),
+          sql.ref('updated_at'),
+        ])}
+      ) values (
+        ${sql.join([
+          sql.val(input.hash),
+          sql.val(3),
+          sql.val('application/octet-stream'),
+          sql.val(new Uint8Array([1, 2, 3])),
+          sql.val(0),
+          sql.val(null),
+          sql.val(input.status),
+          sql.val(input.attemptCount),
+          sql.val(null),
+          sql.val(now),
+          sql.val(input.updatedAt),
+        ])}
+      )
+    `.execute(db);
+  }
+
+  beforeEach(async () => {
+    db = createBunSqliteDb<TestDb>({ path: ':memory:' });
+    await ensureClientSyncSchema(db);
+    await ensureClientBlobSchema(db);
+    initiateCalls = 0;
+
+    const handlers = new ClientTableRegistry<TestDb>();
+    const transport: SyncTransport = {
+      ...noopTransport,
+      blobs: {
+        async initiateUpload() {
+          initiateCalls++;
+          return { exists: true };
+        },
+        async completeUpload() {
+          return { ok: true };
+        },
+        async getDownloadUrl() {
+          return {
+            url: 'https://example.invalid/blob',
+            expiresAt: new Date(0).toISOString(),
+          };
+        },
+      },
+    };
+
+    client = new Client<TestDb>({
+      db,
+      transport,
+      tableHandlers: handlers,
+      blobStorage: createMemoryBlobStorage(),
+      clientId: 'client-1',
+      actorId: 'u1',
+      subscriptions: [],
+    });
+  });
+
+  afterEach(async () => {
+    client.destroy();
+    await db.destroy();
+  });
+
+  it('requeues stale uploading rows and uploads them on the next queue run', async () => {
+    await insertBlobOutboxRow({
+      hash: 'sha256:stale-upload',
+      status: 'uploading',
+      attemptCount: 0,
+      updatedAt: Date.now() - 31_000,
+    });
+
+    const result = await client.blobs!.processUploadQueue();
+
+    expect(result.uploaded).toBe(1);
+    expect(result.failed).toBe(0);
+    expect(initiateCalls).toBe(1);
+
+    const remaining = await sql<{ count: number | bigint }>`
+      select count(${sql.ref('hash')}) as count
+      from ${sql.table('sync_blob_outbox')}
+      where ${sql.ref('hash')} = ${'sha256:stale-upload'}
+    `.execute(db);
+    expect(Number(remaining.rows[0]?.count ?? 0)).toBe(0);
+  });
+
+  it('marks stale uploading rows as failed after max retries', async () => {
+    await insertBlobOutboxRow({
+      hash: 'sha256:stale-failed',
+      status: 'uploading',
+      attemptCount: 2,
+      updatedAt: Date.now() - 31_000,
+    });
+
+    await client.blobs!.processUploadQueue();
+
+    expect(initiateCalls).toBe(0);
+
+    const rowResult = await sql<{
+      status: string;
+      attempt_count: number;
+      error: string | null;
+    }>`
+      select
+        ${sql.ref('status')} as status,
+        ${sql.ref('attempt_count')} as attempt_count,
+        ${sql.ref('error')} as error
+      from ${sql.table('sync_blob_outbox')}
+      where ${sql.ref('hash')} = ${'sha256:stale-failed'}
+      limit 1
+    `.execute(db);
+    const row = rowResult.rows[0];
+    if (!row) {
+      throw new Error('Expected stale failed row to remain in outbox');
+    }
+    expect(row.status).toBe('failed');
+    expect(row.attempt_count).toBe(3);
+    expect(row.error).toContain('Upload timed out while in uploading state');
+  });
+});