@syncular/server-hono 0.0.4-26 → 0.0.6-100

package/src/__tests__/console-routes.test.ts

@@ -1,5 +1,6 @@
 import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
-import { createPgliteDb } from '@syncular/dialect-pglite';
+import { createDatabase } from '@syncular/core';
+import { createPgliteDialect } from '@syncular/dialect-pglite';
 import { ensureSyncSchema, type SyncCoreDb } from '@syncular/server';
 import { createPostgresServerDialect } from '@syncular/server-dialect-postgres';
 import { Hono } from 'hono';
@@ -269,15 +270,35 @@ describe('console timeline route filters', () => {
   }
 
   async function requestEvents(
-    query: Record<string, string | number | undefined> = {}
+    args: {
+      query?: Record<string, string | number | undefined>;
+      targetApp?: Hono;
+    } = {}
   ): Promise<Response> {
     const params = new URLSearchParams({ limit: '50', offset: '0' });
-    for (const [key, value] of Object.entries(query)) {
+    for (const [key, value] of Object.entries(args.query ?? {})) {
       if (value === undefined) continue;
       params.set(key, String(value));
     }
 
-    return app.request(`http://localhost/console/events?${params.toString()}`, {
+    return (args.targetApp ?? app).request(
+      `http://localhost/console/events?${params.toString()}`,
+      {
+        headers: { Authorization: `Bearer ${CONSOLE_TOKEN}` },
+      }
+    );
+  }
+
+  async function requestClearEvents(): Promise<Response> {
+    return app.request('http://localhost/console/events', {
+      method: 'DELETE',
+      headers: { Authorization: `Bearer ${CONSOLE_TOKEN}` },
+    });
+  }
+
+  async function requestPruneEvents(targetApp: Hono = app): Promise<Response> {
+    return targetApp.request('http://localhost/console/events/prune', {
+      method: 'POST',
       headers: { Authorization: `Bearer ${CONSOLE_TOKEN}` },
     });
   }
@@ -425,7 +446,9 @@ describe('console timeline route filters', () => {
   }
 
   function createTestApp(
-    overrides: Pick<CreateConsoleRoutesOptions<TestDb>, 'metrics'> = {}
+    overrides: Partial<
+      Pick<CreateConsoleRoutesOptions<TestDb>, 'metrics' | 'maintenance'>
+    > = {}
   ): Hono {
     const routes = createConsoleRoutes({
       db,
@@ -443,6 +466,18 @@ describe('console timeline route filters', () => {
     return nextApp;
   }
 
+  async function waitForCondition(
+    evaluate: () => Promise<boolean>
+  ): Promise<void> {
+    for (let attempt = 0; attempt < 40; attempt++) {
+      if (await evaluate()) {
+        return;
+      }
+      await new Promise((resolve) => setTimeout(resolve, 25));
+    }
+    throw new Error('Condition was not met within timeout.');
+  }
+
   beforeEach(async () => {
     // Keep fixture events within the current metrics windows (for example 24h).
     baseTimeMs =
@@ -450,7 +485,10 @@ describe('console timeline route filters', () => {
       60 * 60 * 1000;
 
     dialect = createPostgresServerDialect();
-    db = createPgliteDb<TestDb>();
+    db = createDatabase<TestDb>({
+      dialect: createPgliteDialect(),
+      family: 'postgres',
+    });
     await ensureSyncSchema(db, dialect);
     await dialect.ensureConsoleSchema?.(db);
 
@@ -940,7 +978,9 @@ describe('console timeline route filters', () => {
     expect(clientsPayload.total).toBe(1);
     expect(clientsPayload.items[0]?.actorId).toBe('actor-z');
 
-    const eventsResponse = await requestEvents({ partitionId: 'tenant-b' });
+    const eventsResponse = await requestEvents({
+      query: { partitionId: 'tenant-b' },
+    });
     expect(eventsResponse.status).toBe(200);
     const eventsPayload = (await eventsResponse.json()) as {
       items: Array<{ partitionId: string }>;
@@ -1469,4 +1509,118 @@ describe('console timeline route filters', () => {
     expect(payload.requestPayload.clientCommitId).toBe('commit-a');
     expect(payload.responsePayload.status).toBe('applied');
   });
+
+  it('deletes payload snapshots when clearing events', async () => {
+    const response = await requestClearEvents();
+    expect(response.status).toBe(200);
+
+    const eventCountRow = await db
+      .selectFrom('sync_request_events')
+      .select(({ fn }) => fn.countAll().as('total'))
+      .executeTakeFirst();
+    expect(Number(eventCountRow?.total ?? 0)).toBe(0);
+
+    const payloadCountRow = await db
+      .selectFrom('sync_request_payloads')
+      .select(({ fn }) => fn.countAll().as('total'))
+      .executeTakeFirst();
+    expect(Number(payloadCountRow?.total ?? 0)).toBe(0);
+  });
+
+  it('prunes orphaned payload snapshots during event pruning', async () => {
+    await db
+      .insertInto('sync_request_payloads')
+      .values({
+        payload_ref: 'payload-orphan',
+        partition_id: 'default',
+        request_payload: JSON.stringify({ orphan: true }),
+        response_payload: JSON.stringify({ ok: true }),
+        created_at: atIso(33),
+      })
+      .execute();
+
+    const response = await requestPruneEvents();
+    expect(response.status).toBe(200);
+
+    const orphan = await db
+      .selectFrom('sync_request_payloads')
+      .select(['payload_ref'])
+      .where('payload_ref', '=', 'payload-orphan')
+      .executeTakeFirst();
+    expect(orphan).toBeUndefined();
+  });
+
+  it('prunes operation audit events during /events/prune retention', async () => {
+    await db
+      .insertInto('sync_operation_events')
+      .values({
+        operation_type: 'compact',
+        console_user_id: 'console-old',
+        partition_id: null,
+        target_client_id: null,
+        request_payload: JSON.stringify({ fullHistoryHours: 12 }),
+        result_payload: JSON.stringify({ deletedChanges: 22 }),
+        created_at: '2000-01-01T00:00:00.000Z',
+      })
+      .execute();
+
+    const response = await requestPruneEvents();
+    expect(response.status).toBe(200);
+
+    const oldOperation = await db
+      .selectFrom('sync_operation_events')
+      .select(['operation_id'])
+      .where('console_user_id', '=', 'console-old')
+      .executeTakeFirst();
+    expect(oldOperation).toBeUndefined();
+
+    const operationCountRow = await db
+      .selectFrom('sync_operation_events')
+      .select(({ fn }) => fn.countAll().as('total'))
+      .executeTakeFirst();
+    expect(Number(operationCountRow?.total ?? 0)).toBe(2);
+  });
+
+  it('runs automatic event pruning cadence using maintenance config', async () => {
+    const autoPruneApp = createTestApp({
+      maintenance: {
+        autoPruneIntervalMs: 1,
+        requestEventsMaxAgeMs: 0,
+        requestEventsMaxRows: 2,
+        operationEventsMaxAgeMs: 0,
+        operationEventsMaxRows: 1,
+      },
+    });
+
+    const trigger = await requestEvents({ targetApp: autoPruneApp });
+    expect(trigger.status).toBe(200);
+
+    await waitForCondition(async () => {
+      const requestCountRow = await db
+        .selectFrom('sync_request_events')
+        .select(({ fn }) => fn.countAll().as('total'))
+        .executeTakeFirst();
+      const operationCountRow = await db
+        .selectFrom('sync_operation_events')
+        .select(({ fn }) => fn.countAll().as('total'))
+        .executeTakeFirst();
+
+      const requestCount = Number(requestCountRow?.total ?? 0);
+      const operationCount = Number(operationCountRow?.total ?? 0);
+      return requestCount === 2 && operationCount === 1;
+    });
+  });
+
+  it('disables credentialed CORS headers when wildcard origin is configured', async () => {
+    const response = await app.request('http://localhost/console/events', {
+      method: 'OPTIONS',
+      headers: {
+        Origin: 'https://example.com',
+        'Access-Control-Request-Method': 'GET',
+      },
+    });
+
+    expect(response.headers.get('Access-Control-Allow-Origin')).toBe('*');
+    expect(response.headers.get('Access-Control-Allow-Credentials')).toBeNull();
+  });
 });

package/src/__tests__/console-ui.test.ts

@@ -0,0 +1,114 @@
+import { afterEach, describe, expect, it } from 'bun:test';
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import {
+  CONSOLE_BASEPATH_META,
+  CONSOLE_SERVER_URL_META,
+  CONSOLE_TOKEN_META,
+} from '@syncular/console/runtime-config';
+import { Hono } from 'hono';
+import { mountConsoleUi } from '../console/ui';
+
+const tempDirs: string[] = [];
+
+async function createStaticFixture(): Promise<string> {
+  const staticDir = await mkdtemp(path.join(tmpdir(), 'syncular-console-ui-'));
+  tempDirs.push(staticDir);
+
+  await mkdir(path.join(staticDir, 'assets'), { recursive: true });
+  await writeFile(
+    path.join(staticDir, 'index.html'),
+    `<!doctype html>
+<html>
+  <head>
+    <meta name="${CONSOLE_BASEPATH_META}" content="" />
+    <meta name="${CONSOLE_SERVER_URL_META}" content="" />
+    <meta name="${CONSOLE_TOKEN_META}" content="" />
+    <link rel="stylesheet" href="/assets/console.css" />
+  </head>
+  <body>
+    <script type="module" src="/assets/main.js"></script>
+  </body>
+</html>`
+  );
+  await writeFile(
+    path.join(staticDir, 'assets', 'main.js'),
+    'console.log(1);\n'
+  );
+  await writeFile(path.join(staticDir, 'assets', 'console.css'), 'body{}\n');
+
+  return staticDir;
+}
+
+afterEach(async () => {
+  await Promise.all(
+    tempDirs.splice(0).map((dir) => rm(dir, { recursive: true, force: true }))
+  );
+});
+
+describe('mountConsoleUi', () => {
+  it('serves console UI with default prefill derived from mount/api paths', async () => {
+    const staticDir = await createStaticFixture();
+    const app = new Hono();
+
+    mountConsoleUi(app, {
+      mountPath: 'console',
+      apiBasePath: 'api',
+      staticDir,
+    });
+
+    const response = await app.request('http://example.test/console');
+    const html = await response.text();
+
+    expect(response.status).toBe(200);
+    expect(html).toContain(
+      `<meta name="${CONSOLE_BASEPATH_META}" content="/console" />`
+    );
+    expect(html).toContain(
+      `<meta name="${CONSOLE_SERVER_URL_META}" content="http://example.test/api" />`
+    );
+    expect(html).toContain(`<meta name="${CONSOLE_TOKEN_META}" content="" />`);
+    expect(html).toContain('href="/console/assets/console.css"');
+    expect(html).toContain('src="/console/assets/main.js"');
+
+    const asset = await app.request(
+      'http://example.test/console/assets/main.js'
+    );
+    expect(asset.status).toBe(200);
+    expect(await asset.text()).toContain('console.log(1);');
+  });
+
+  it('merges resolvePrefill and allows resolveToken to override token', async () => {
+    const staticDir = await createStaticFixture();
+    const app = new Hono();
+
+    mountConsoleUi(app, {
+      mountPath: '/ops-console',
+      apiBasePath: '/api/internal',
+      staticDir,
+      resolvePrefill: async () => ({
+        basePath: '/prefilled',
+        serverUrl: 'https://prefill.example/api',
+        token: 'prefill-token',
+      }),
+      resolveToken: async () => 'resolver-token',
+    });
+
+    const response = await app.request('http://localhost/ops-console');
+    const html = await response.text();
+
+    expect(response.status).toBe(200);
+    expect(html).toContain(
+      `<meta name="${CONSOLE_BASEPATH_META}" content="/prefilled" />`
+    );
+    expect(html).toContain(
+      `<meta name="${CONSOLE_SERVER_URL_META}" content="https://prefill.example/api" />`
+    );
+    expect(html).toContain(
+      `<meta name="${CONSOLE_TOKEN_META}" content="resolver-token" />`
+    );
+    expect(html).toContain('href="/prefilled/assets/console.css"');
+    expect(html).toContain('src="/prefilled/assets/main.js"');
+  });
+});

package/src/__tests__/create-server.test.ts

@@ -1,5 +1,6 @@
 import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
-import { createPgliteDb } from '@syncular/dialect-pglite';
+import { createDatabase } from '@syncular/core';
+import { createPgliteDialect } from '@syncular/dialect-pglite';
 import {
   createServerHandler,
   ensureSyncSchema,
@@ -8,7 +9,7 @@ import {
 import { createPostgresServerDialect } from '@syncular/server-dialect-postgres';
 import { Hono } from 'hono';
 import { defineWebSocketHelper } from 'hono/ws';
-import type { Kysely } from 'kysely';
+import { type Kysely, sql } from 'kysely';
 import { createSyncServer } from '../create-server';
 import { getSyncWebSocketConnectionManager } from '../routes';
 import type { WebSocketConnection } from '../ws';
@@ -33,7 +34,10 @@ describe('createSyncServer console configuration', () => {
   let previousConsoleToken: string | undefined;
 
   beforeEach(async () => {
-    db = createPgliteDb<ServerDb>();
+    db = createDatabase<ServerDb>({
+      dialect: createPgliteDialect(),
+      family: 'postgres',
+    });
     await ensureSyncSchema(db, createPostgresServerDialect());
     await db.schema
       .createTable('tasks')
@@ -70,8 +74,10 @@ describe('createSyncServer console configuration', () => {
     return {
       db,
       dialect: createPostgresServerDialect(),
-      handlers: [createTestHandler()],
-      authenticate: async () => ({ actorId: 'u1' }),
+      sync: {
+        handlers: [createTestHandler()],
+        authenticate: async () => ({ actorId: 'u1' }),
+      },
     };
   }
 
@@ -94,10 +100,16 @@ describe('createSyncServer console configuration', () => {
     };
   }
 
-  function createPushRequest(): Request {
+  function createPushRequest(args?: {
+    requestId?: string;
+    title?: string;
+  }): Request {
     return new Request('http://localhost/sync', {
       method: 'POST',
-      headers: { 'content-type': 'application/json' },
+      headers: {
+        'content-type': 'application/json',
+        ...(args?.requestId ? { 'x-request-id': args.requestId } : {}),
+      },
       body: JSON.stringify({
         clientId: 'client-1',
         push: {
@@ -111,7 +123,7 @@ describe('createSyncServer console configuration', () => {
               payload: {
                 id: 'task-1',
                 user_id: 'u1',
-                title: 'Task 1',
+                title: args?.title ?? 'Task 1',
                 server_version: 0,
               },
             },
@@ -121,6 +133,62 @@ describe('createSyncServer console configuration', () => {
     });
   }
 
+  function parseSnapshotValue(value: unknown): unknown {
+    if (typeof value !== 'string') {
+      return value;
+    }
+    try {
+      return JSON.parse(value);
+    } catch {
+      return value;
+    }
+  }
+
+  async function waitForRequestEventRow(requestId: string): Promise<{
+    payload_ref: string | null;
+  }> {
+    for (let attempt = 0; attempt < 40; attempt++) {
+      const result = await sql<{ payload_ref: string | null }>`
+        SELECT payload_ref
+        FROM sync_request_events
+        WHERE request_id = ${requestId}
+        ORDER BY event_id DESC
+        LIMIT 1
+      `.execute(db);
+
+      const row = result.rows[0];
+      if (row) {
+        return row;
+      }
+
+      await new Promise((resolve) => setTimeout(resolve, 25));
+    }
+
+    throw new Error(`Timed out waiting for request event: ${requestId}`);
+  }
+
+  async function waitForRequestPayloadSnapshot(
+    payloadRef: string
+  ): Promise<unknown> {
+    for (let attempt = 0; attempt < 40; attempt++) {
+      const result = await sql<{ request_payload: unknown | null }>`
+        SELECT request_payload
+        FROM sync_request_payloads
+        WHERE payload_ref = ${payloadRef}
+        LIMIT 1
+      `.execute(db);
+
+      const row = result.rows[0];
+      if (row && row.request_payload !== null) {
+        return parseSnapshotValue(row.request_payload);
+      }
+
+      await new Promise((resolve) => setTimeout(resolve, 25));
+    }
+
+    throw new Error(`Timed out waiting for payload snapshot: ${payloadRef}`);
+  }
+
   it('keeps console routes disabled when console config is omitted', () => {
     const server = createSyncServer(createOptions());
     expect(server.consoleRoutes).toBeUndefined();
@@ -158,6 +226,80 @@ describe('createSyncServer console configuration', () => {
     expect(server.consoleRoutes).toBeDefined();
   });
 
+  it('returns not implemented when blobBucket is not configured', async () => {
+    const options = createOptions();
+    const server = createSyncServer({
+      ...options,
+      console: {
+        token: 'console-token',
+      },
+    });
+
+    const app = new Hono();
+    app.route('/console', server.consoleRoutes!);
+
+    const response = await app.request('http://localhost/console/storage', {
+      headers: { Authorization: 'Bearer console-token' },
+    });
+
+    expect(response.status).toBe(501);
+    expect(await response.json()).toEqual({
+      error: 'BLOB_STORAGE_NOT_CONFIGURED',
+    });
+  });
+
+  it('enables storage console routes when blobBucket is configured', async () => {
+    const options = createOptions();
+    const server = createSyncServer({
+      ...options,
+      console: {
+        token: 'blob-token',
+        blobBucket: {
+          list: async () => ({
+            objects: [
+              {
+                key: 'hello.txt',
+                size: 12,
+                uploaded: new Date('2025-01-01T00:00:00.000Z'),
+                httpMetadata: { contentType: 'text/plain' },
+              },
+            ],
+            truncated: false,
+            cursor: undefined,
+          }),
+          get: async () => null,
+          delete: async () => {},
+          head: async () => null,
+        },
+      },
+    });
+
+    const app = new Hono();
+    app.route('/console', server.consoleRoutes!);
+
+    const unauthenticated = await app.request(
+      'http://localhost/console/storage'
+    );
+    expect(unauthenticated.status).toBe(401);
+
+    const response = await app.request('http://localhost/console/storage', {
+      headers: { Authorization: 'Bearer blob-token' },
+    });
+    expect(response.status).toBe(200);
+    expect(await response.json()).toEqual({
+      items: [
+        {
+          key: 'hello.txt',
+          size: 12,
+          uploaded: '2025-01-01T00:00:00.000Z',
+          httpMetadata: { contentType: 'text/plain' },
+        },
+      ],
+      truncated: false,
+      cursor: null,
+    });
+  });
+
   it('forwards maxConnectionsPerClient from factory to realtime route', async () => {
     const options = createOptions();
     const upgradeWebSocket = defineWebSocketHelper(async () => {});
@@ -165,7 +307,7 @@ describe('createSyncServer console configuration', () => {
     const server = createSyncServer({
       ...options,
       upgradeWebSocket,
-      sync: {
+      routes: {
         websocket: {
           maxConnectionsPerClient: 1,
         },
@@ -190,6 +332,87 @@ describe('createSyncServer console configuration', () => {
     });
   });
 
+  it('allows disabling request payload snapshots for privacy-sensitive deployments', async () => {
+    process.env.SYNC_CONSOLE_TOKEN = 'env-token';
+    const options = createOptions();
+    const server = createSyncServer({
+      ...options,
+      console: {},
+      routes: {
+        requestPayloadSnapshots: {
+          enabled: false,
+        },
+      },
+    });
+
+    const app = new Hono();
+    app.route('/sync', server.syncRoutes);
+
+    const requestId = 'req-no-payload-snapshot';
+    const response = await app.request(createPushRequest({ requestId }));
+    expect(response.status).toBe(200);
+
+    const eventRow = await waitForRequestEventRow(requestId);
+    expect(eventRow.payload_ref).toBeNull();
+
+    const payloadCountResult = await sql<{ total: number | string }>`
+      SELECT COUNT(*)::int AS total
+      FROM sync_request_payloads
+    `.execute(db);
+    const payloadCount = Number(payloadCountResult.rows[0]?.total ?? 0);
+    expect(payloadCount).toBe(0);
+  });
+
+  it('supports aggressively reducing stored payload snapshot size', async () => {
+    process.env.SYNC_CONSOLE_TOKEN = 'env-token';
+    const options = createOptions();
+    const server = createSyncServer({
+      ...options,
+      console: {},
+      routes: {
+        requestPayloadSnapshots: {
+          maxBytes: 32,
+        },
+      },
+    });
+
+    const app = new Hono();
+    app.route('/sync', server.syncRoutes);
+
+    const requestId = 'req-small-payload-preview';
+    const response = await app.request(
+      createPushRequest({
+        requestId,
+        title: 'x'.repeat(1024),
+      })
+    );
+    expect(response.status).toBe(200);
+
+    const eventRow = await waitForRequestEventRow(requestId);
+    expect(typeof eventRow.payload_ref).toBe('string');
+    if (!eventRow.payload_ref) {
+      throw new Error('Expected payload_ref to be present.');
+    }
+
+    const storedPayload = await waitForRequestPayloadSnapshot(
+      eventRow.payload_ref
+    );
+    expect(typeof storedPayload).toBe('object');
+    expect(Array.isArray(storedPayload)).toBe(false);
+    if (!storedPayload || typeof storedPayload !== 'object') {
+      throw new Error('Expected stored payload snapshot to be an object.');
+    }
+
+    const truncated = Reflect.get(storedPayload, 'truncated');
+    const preview = Reflect.get(storedPayload, 'preview');
+
+    expect(truncated).toBe(true);
+    expect(typeof preview).toBe('string');
+    if (typeof preview === 'string') {
+      expect(preview.length).toBeLessThanOrEqual(32);
+    }
+  });
+
   it('forwards maxConnectionsTotal from factory to realtime route', async () => {
     const options = createOptions();
     const upgradeWebSocket = defineWebSocketHelper(async () => {});
@@ -197,7 +420,7 @@ describe('createSyncServer console configuration', () => {
     const server = createSyncServer({
       ...options,
       upgradeWebSocket,
-      sync: {
+      routes: {
         websocket: {
           maxConnectionsTotal: 1,
         },

package/src/__tests__/pull-chunk-storage.test.ts

@@ -2,6 +2,7 @@ import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
 import { gunzipSync } from 'node:zlib';
 import {
   configureSyncTelemetry,
+  createDatabase,
   decodeSnapshotRows,
   getSyncTelemetry,
   SyncCombinedResponseSchema,
@@ -18,7 +19,7 @@ import {
 } from '@syncular/server';
 import { Hono } from 'hono';
 import type { Kysely } from 'kysely';
-import { createBunSqliteDb } from '../../../dialect-bun-sqlite/src';
+import { createBunSqliteDialect } from '../../../dialect-bun-sqlite/src';
 import { createSqliteServerDialect } from '../../../server-dialect-sqlite/src';
 import { createSyncRoutes } from '../routes';
 
@@ -106,7 +107,10 @@ describe('createSyncRoutes chunkStorage wiring', () => {
   const dialect = createSqliteServerDialect();
 
   beforeEach(async () => {
-    db = createBunSqliteDb<ServerDb>({ path: ':memory:' });
+    db = createDatabase<ServerDb>({
+      dialect: createBunSqliteDialect({ path: ':memory:' }),
+      family: 'sqlite',
+    });
     await ensureSyncSchema(db, dialect);
 
     await db.schema

package/src/__tests__/realtime-bridge.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it, mock } from 'bun:test';
-import { createPgliteDb } from '@syncular/dialect-pglite';
+import { createDatabase } from '@syncular/core';
+import { createPgliteDialect } from '@syncular/dialect-pglite';
 import {
   ensureSyncSchema,
   InMemorySyncRealtimeBroadcaster,
@@ -15,7 +16,10 @@ import {
 
 describe('realtime broadcaster bridge', () => {
   it('notifies local WebSocket connections when another instance publishes a commit', async () => {
-    const db = createPgliteDb<SyncCoreDb>();
+    const db = createDatabase<SyncCoreDb>({
+      dialect: createPgliteDialect(),
+      family: 'postgres',
+    });
     const dialect = createPostgresServerDialect();
     await ensureSyncSchema(db, dialect);