@syncular/server-hono 0.0.1-60

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@syncular/server-hono",
+  "version": "0.0.1-60",
+  "description": "Hono adapter for the Syncular server with OpenAPI support",
+  "license": "MIT",
+  "author": "Benjamin Kniffler",
+  "homepage": "https://syncular.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/syncular/syncular.git",
+    "directory": "packages/server-hono"
+  },
+  "bugs": {
+    "url": "https://github.com/syncular/syncular/issues"
+  },
+  "keywords": [
+    "sync",
+    "offline-first",
+    "realtime",
+    "database",
+    "typescript",
+    "hono",
+    "openapi"
+  ],
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "scripts": {
+    "test": "bun test src/__tests__",
+    "tsgo": "tsgo --noEmit",
+    "generate": "bun generate:openapi",
+    "generate:openapi": "bun scripts/generate-openapi.ts",
+    "build": "rm -rf dist && tsgo",
+    "release": "bun pm pack --destination . && npm publish ./*.tgz --tag latest && rm -f ./*.tgz"
+  },
+  "dependencies": {
+    "@hono/standard-validator": "^0.2.2",
+    "@standard-community/standard-json": "^0.3.5",
+    "@standard-community/standard-openapi": "^0.2.9",
+    "@syncular/core": "0.0.1",
+    "@syncular/server": "0.0.1",
+    "@types/json-schema": "^7.0.15",
+    "hono-openapi": "^1.2.0",
+    "openapi-types": "^12.1.3"
+  },
+  "devDependencies": {
+    "@syncular/config": "0.0.0",
+    "@syncular/dialect-pglite": "0.0.1",
+    "@syncular/server-dialect-postgres": "0.0.1",
+    "kysely": "*",
+    "zod": "*"
+  },
+  "peerDependencies": {
+    "hono": "^4.0.0",
+    "kysely": "^0.28.0",
+    "zod": "^4.0.0"
+  },
+  "files": [
+    "dist",
+    "src"
+  ]
+}

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

@@ -0,0 +1,187 @@
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
+import { createPgliteDb } from '@syncular/dialect-pglite';
+import {
+  createServerHandler,
+  ensureSyncSchema,
+  type SyncCoreDb,
+} from '@syncular/server';
+import { createPostgresServerDialect } from '@syncular/server-dialect-postgres';
+import { Hono } from 'hono';
+import { defineWebSocketHelper } from 'hono/ws';
+import type { Kysely } from 'kysely';
+import { createSyncServer } from '../create-server';
+import { getSyncWebSocketConnectionManager } from '../routes';
+import type { WebSocketConnection } from '../ws';
+
+interface TasksTable {
+  id: string;
+  user_id: string;
+  title: string;
+  server_version: number;
+}
+
+interface ServerDb extends SyncCoreDb {
+  tasks: TasksTable;
+}
+
+interface ClientDb {
+  tasks: TasksTable;
+}
+
+describe('createSyncServer console configuration', () => {
+  let db: Kysely<ServerDb>;
+  let previousConsoleToken: string | undefined;
+
+  beforeEach(async () => {
+    db = createPgliteDb<ServerDb>();
+    await ensureSyncSchema(db, createPostgresServerDialect());
+    previousConsoleToken = process.env.SYNC_CONSOLE_TOKEN;
+    delete process.env.SYNC_CONSOLE_TOKEN;
+  });
+
+  afterEach(async () => {
+    if (previousConsoleToken === undefined) {
+      delete process.env.SYNC_CONSOLE_TOKEN;
+    } else {
+      process.env.SYNC_CONSOLE_TOKEN = previousConsoleToken;
+    }
+    await db.destroy();
+  });
+
+  function createTestHandler() {
+    return createServerHandler<ServerDb, ClientDb, 'tasks'>({
+      table: 'tasks',
+      scopes: ['user:{user_id}'],
+      resolveScopes: async (ctx) => ({ user_id: [ctx.actorId] }),
+    });
+  }
+
+  function createOptions() {
+    return {
+      db,
+      dialect: createPostgresServerDialect(),
+      handlers: [createTestHandler()],
+      authenticate: async () => ({ actorId: 'u1' }),
+    };
+  }
+
+  function createConn(args: {
+    actorId: string;
+    clientId: string;
+  }): WebSocketConnection {
+    return {
+      actorId: args.actorId,
+      clientId: args.clientId,
+      transportPath: 'direct',
+      get isOpen() {
+        return true;
+      },
+      sendSync() {},
+      sendHeartbeat() {},
+      sendPresence() {},
+      sendError() {},
+      close() {},
+    };
+  }
+
+  it('keeps console routes disabled when console config is omitted', () => {
+    const server = createSyncServer(createOptions());
+    expect(server.consoleRoutes).toBeUndefined();
+  });
+
+  it('throws when console is enabled without a token', () => {
+    const options = createOptions();
+    expect(() =>
+      createSyncServer({
+        ...options,
+        console: {},
+      })
+    ).toThrow(
+      'Console is enabled but no token is configured. Set `console.token` or SYNC_CONSOLE_TOKEN.'
+    );
+  });
+
+  it('accepts SYNC_CONSOLE_TOKEN when console token is omitted', () => {
+    process.env.SYNC_CONSOLE_TOKEN = 'env-token';
+    const options = createOptions();
+    const server = createSyncServer({
+      ...options,
+      console: {},
+    });
+    expect(server.consoleRoutes).toBeDefined();
+  });
+
+  it('accepts an explicit console token', () => {
+    process.env.SYNC_CONSOLE_TOKEN = 'env-token';
+    const options = createOptions();
+    const server = createSyncServer({
+      ...options,
+      console: { token: 'explicit-token' },
+    });
+    expect(server.consoleRoutes).toBeDefined();
+  });
+
+  it('forwards maxConnectionsPerClient from factory to realtime route', async () => {
+    const options = createOptions();
+    const upgradeWebSocket = defineWebSocketHelper(async () => {});
+
+    const server = createSyncServer({
+      ...options,
+      upgradeWebSocket,
+      sync: {
+        websocket: {
+          maxConnectionsPerClient: 1,
+        },
+      },
+    });
+
+    const manager = getSyncWebSocketConnectionManager(server.syncRoutes);
+    if (!manager) {
+      throw new Error('Expected websocket manager to be enabled.');
+    }
+    manager.register(createConn({ actorId: 'u1', clientId: 'client-1' }), []);
+
+    const app = new Hono();
+    app.route('/sync', server.syncRoutes);
+
+    const response = await app.request(
+      'http://localhost/sync/realtime?clientId=client-1'
+    );
+    expect(response.status).toBe(429);
+    expect(await response.json()).toEqual({
+      error: 'WEBSOCKET_CONNECTION_LIMIT_CLIENT',
+    });
+  });
+
+  it('forwards maxConnectionsTotal from factory to realtime route', async () => {
+    const options = createOptions();
+    const upgradeWebSocket = defineWebSocketHelper(async () => {});
+
+    const server = createSyncServer({
+      ...options,
+      upgradeWebSocket,
+      sync: {
+        websocket: {
+          maxConnectionsTotal: 1,
+        },
+      },
+    });
+
+    const manager = getSyncWebSocketConnectionManager(server.syncRoutes);
+    if (!manager) {
+      throw new Error('Expected websocket manager to be enabled.');
+    }
+    manager.register(createConn({ actorId: 'u1', clientId: 'client-1' }), []);
+
+    const app = new Hono();
+    app.route('/sync', server.syncRoutes);
+
+    const response = await app.request(
+      'http://localhost/sync/realtime?clientId=client-2'
+    );
+    expect(response.status).toBe(429);
+    expect(await response.json()).toEqual({
+      error: 'WEBSOCKET_CONNECTION_LIMIT_TOTAL',
+    });
+  });
+});

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

@@ -0,0 +1,189 @@
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
+import { gunzipSync } from 'node:zlib';
+import {
+  SyncCombinedResponseSchema,
+  type SyncPullResponse,
+  type SyncSnapshotChunkRef,
+} from '@syncular/core';
+import {
+  createServerHandler,
+  ensureSyncSchema,
+  type SnapshotChunkStorage,
+  type SyncCoreDb,
+} from '@syncular/server';
+import { Hono } from 'hono';
+import type { Kysely } from 'kysely';
+import { createBunSqliteDb } from '../../../dialect-bun-sqlite/src';
+import { createSqliteServerDialect } from '../../../server-dialect-sqlite/src';
+import { createSyncRoutes } from '../routes';
+
+interface TasksTable {
+  id: string;
+  user_id: string;
+  title: string;
+  server_version: number;
+}
+
+interface ServerDb extends SyncCoreDb {
+  tasks: TasksTable;
+}
+
+interface ClientDb {
+  tasks: TasksTable;
+}
+
+function mustGetFirstChunkId(payload: SyncPullResponse): string {
+  const chunkId = payload.subscriptions[0]?.snapshots?.[0]?.chunks?.[0]?.id;
+  if (!chunkId) {
+    throw new Error('Expected pull bootstrap response to include a chunk id.');
+  }
+  return chunkId;
+}
+
+describe('createSyncRoutes chunkStorage wiring', () => {
+  let db: Kysely<ServerDb>;
+  const dialect = createSqliteServerDialect();
+
+  beforeEach(async () => {
+    db = createBunSqliteDb<ServerDb>({ path: ':memory:' });
+    await ensureSyncSchema(db, dialect);
+
+    await db.schema
+      .createTable('tasks')
+      .addColumn('id', 'text', (col) => col.primaryKey())
+      .addColumn('user_id', 'text', (col) => col.notNull())
+      .addColumn('title', 'text', (col) => col.notNull())
+      .addColumn('server_version', 'integer', (col) =>
+        col.notNull().defaultTo(0)
+      )
+      .execute();
+  });
+
+  afterEach(async () => {
+    await db.destroy();
+  });
+
+  it('uses external chunk storage in /pull and serves chunks from it', async () => {
+    await db
+      .insertInto('tasks')
+      .values({
+        id: 't1',
+        user_id: 'u1',
+        title: 'Task 1',
+        server_version: 1,
+      })
+      .execute();
+
+    const tasksHandler = createServerHandler<ServerDb, ClientDb, 'tasks'>({
+      table: 'tasks',
+      scopes: ['user:{user_id}'],
+      resolveScopes: async (ctx) => ({ user_id: [ctx.actorId] }),
+    });
+
+    const externalChunkBodies = new Map<string, Uint8Array>();
+    let storeChunkCalls = 0;
+    const chunkStorage: SnapshotChunkStorage = {
+      name: 'test-external',
+      async storeChunk(metadata) {
+        storeChunkCalls += 1;
+        const ref: SyncSnapshotChunkRef = {
+          id: `chunk-${storeChunkCalls}`,
+          sha256: metadata.sha256,
+          byteLength: metadata.body.length,
+          encoding: metadata.encoding,
+          compression: metadata.compression,
+        };
+        externalChunkBodies.set(ref.id, new Uint8Array(metadata.body));
+        return ref;
+      },
+      async readChunk(chunkId: string) {
+        const body = externalChunkBodies.get(chunkId);
+        return body ? new Uint8Array(body) : null;
+      },
+      async findChunk() {
+        return null;
+      },
+      async cleanupExpired() {
+        return 0;
+      },
+    };
+
+    const routes = createSyncRoutes({
+      db,
+      dialect,
+      handlers: [tasksHandler],
+      authenticate: async (c) => {
+        const actorId = c.req.header('x-user-id');
+        return actorId ? { actorId } : null;
+      },
+      chunkStorage,
+    });
+
+    const app = new Hono();
+    app.route('/sync', routes);
+
+    const pullResponse = await app.request(
+      new Request('http://localhost/sync', {
+        method: 'POST',
+        headers: {
+          'content-type': 'application/json',
+          'x-user-id': 'u1',
+        },
+        body: JSON.stringify({
+          clientId: 'client-1',
+          pull: {
+            limitCommits: 10,
+            limitSnapshotRows: 100,
+            maxSnapshotPages: 1,
+            subscriptions: [
+              {
+                id: 'sub-1',
+                shape: 'tasks',
+                scopes: { user_id: 'u1' },
+                cursor: -1,
+              },
+            ],
+          },
+        }),
+      })
+    );
+
+    expect(pullResponse.status).toBe(200);
+    const combined = SyncCombinedResponseSchema.parse(
+      await pullResponse.json()
+    );
+    const parsed = combined.pull!;
+    const chunkId = mustGetFirstChunkId(parsed);
+    expect(storeChunkCalls).toBe(1);
+    expect(externalChunkBodies.has(chunkId)).toBe(true);
+
+    const storedExternal = externalChunkBodies.get(chunkId);
+    if (!storedExternal) {
+      throw new Error('Expected external chunk body to be stored.');
+    }
+
+    const decoded = new TextDecoder().decode(gunzipSync(storedExternal));
+    const rows = decoded
+      .split('\n')
+      .filter((line) => line.length > 0)
+      .map(
+        (line) =>
+          JSON.parse(line) as {
+            id: string;
+            user_id: string;
+            title: string;
+            server_version: number;
+          }
+      );
+
+    const snapshotChunkCountRow = await db
+      .selectFrom('sync_snapshot_chunks')
+      .select(({ fn }) => fn.countAll().as('count'))
+      .executeTakeFirstOrThrow();
+
+    expect(Number(snapshotChunkCountRow.count)).toBe(0);
+    expect(rows).toEqual([
+      { id: 't1', user_id: 'u1', title: 'Task 1', server_version: 1 },
+    ]);
+  }, 10_000);
+});

package/src/__tests__/rate-limit.test.ts

@@ -0,0 +1,78 @@
+import { afterEach, describe, expect, it } from 'bun:test';
+import { Hono } from 'hono';
+import { createRateLimiter, resetRateLimitStore } from '../rate-limit';
+
+afterEach(() => {
+  resetRateLimitStore();
+});
+
+describe('rate limiter store isolation', () => {
+  it('does not share counters across independently configured routes', async () => {
+    const app = new Hono();
+
+    app.use(
+      '/pull',
+      createRateLimiter({
+        maxRequests: 1,
+        windowMs: 60_000,
+        keyGenerator: () => 'actor-1',
+      })
+    );
+    app.use(
+      '/push',
+      createRateLimiter({
+        maxRequests: 1,
+        windowMs: 60_000,
+        keyGenerator: () => 'actor-1',
+      })
+    );
+
+    app.get('/pull', (c) => c.text('ok'));
+    app.get('/push', (c) => c.text('ok'));
+
+    const pullFirst = await app.request('http://localhost/pull');
+    const pushFirst = await app.request('http://localhost/push');
+    const pushSecond = await app.request('http://localhost/push');
+
+    expect(pullFirst.status).toBe(200);
+    expect(pushFirst.status).toBe(200);
+    expect(pushSecond.status).toBe(429);
+  });
+
+  it('keeps window durations isolated per limiter', async () => {
+    const app = new Hono();
+
+    app.use(
+      '/short',
+      createRateLimiter({
+        maxRequests: 1,
+        windowMs: 10,
+        keyGenerator: () => 'actor-1',
+      })
+    );
+    app.use(
+      '/long',
+      createRateLimiter({
+        maxRequests: 1,
+        windowMs: 1_000,
+        keyGenerator: () => 'actor-1',
+      })
+    );
+
+    app.get('/short', (c) => c.text('ok'));
+    app.get('/long', (c) => c.text('ok'));
+
+    // Initialize the short-window limiter first.
+    expect((await app.request('http://localhost/short')).status).toBe(200);
+
+    // Exhaust long-window limiter.
+    expect((await app.request('http://localhost/long')).status).toBe(200);
+    expect((await app.request('http://localhost/long')).status).toBe(429);
+
+    // Wait longer than short window but shorter than long window.
+    await Bun.sleep(30);
+
+    // Long limiter must still be limited.
+    expect((await app.request('http://localhost/long')).status).toBe(429);
+  });
+});

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

@@ -0,0 +1,131 @@
+import { describe, expect, it, mock } from 'bun:test';
+import { createPgliteDb } from '@syncular/dialect-pglite';
+import {
+  ensureSyncSchema,
+  InMemorySyncRealtimeBroadcaster,
+  type SyncCoreDb,
+} from '@syncular/server';
+import { createPostgresServerDialect } from '@syncular/server-dialect-postgres';
+import { defineWebSocketHelper } from 'hono/ws';
+import {
+  createSyncRoutes,
+  getSyncRealtimeUnsubscribe,
+  getSyncWebSocketConnectionManager,
+} from '../routes';
+
+describe('realtime broadcaster bridge', () => {
+  it('notifies local WebSocket connections when another instance publishes a commit', async () => {
+    const db = createPgliteDb<SyncCoreDb>();
+    const dialect = createPostgresServerDialect();
+    await ensureSyncSchema(db, dialect);
+
+    const commit = await db
+      .insertInto('sync_commits')
+      .values({
+        partition_id: 'default',
+        actor_id: 'u1',
+        client_id: 'client-1',
+        client_commit_id: 'c1',
+        meta: null,
+        result_json: null,
+      })
+      .returning(['commit_seq'])
+      .executeTakeFirstOrThrow();
+
+    const commitSeq = Number(commit.commit_seq);
+
+    await db
+      .insertInto('sync_changes')
+      .values({
+        commit_seq: commitSeq,
+        partition_id: 'default',
+        table: 'tasks',
+        row_id: 't1',
+        op: 'upsert',
+        row_json: { id: 't1' },
+        row_version: 1,
+        scopes: { user_id: 'u1' },
+      })
+      .execute();
+
+    const broadcaster = new InMemorySyncRealtimeBroadcaster();
+    const upgradeWebSocket = defineWebSocketHelper(async () => {});
+
+    const routes1 = createSyncRoutes({
+      db,
+      dialect,
+      handlers: [],
+      authenticate: async () => ({ actorId: 'u1' }),
+      sync: {
+        websocket: {
+          enabled: true,
+          upgradeWebSocket,
+          heartbeatIntervalMs: 0,
+        },
+        realtime: { broadcaster, instanceId: 'i1' },
+      },
+    });
+
+    const routes2 = createSyncRoutes({
+      db,
+      dialect,
+      handlers: [],
+      authenticate: async () => ({ actorId: 'u1' }),
+      sync: {
+        websocket: {
+          enabled: true,
+          upgradeWebSocket,
+          heartbeatIntervalMs: 0,
+        },
+        realtime: { broadcaster, instanceId: 'i2' },
+      },
+    });
+
+    const mgr2 = getSyncWebSocketConnectionManager(routes2);
+    expect(mgr2).toBeTruthy();
+
+    const onSync = mock((_cursor: number) => {});
+
+    mgr2!.register(
+      {
+        actorId: 'u1',
+        clientId: 'client-2',
+        get isOpen() {
+          return true;
+        },
+        sendSync: onSync,
+        sendHeartbeat: mock(() => {}),
+        sendPresence: mock(() => {}),
+        sendError: mock(() => {}),
+        close: mock(() => {}),
+      },
+      ['default::user:u1']
+    );
+
+    // Publish without scopeKeys to exercise DB lookup on the receiving instance.
+    await broadcaster.publish({
+      type: 'commit',
+      commitSeq,
+      sourceInstanceId: 'i1',
+    });
+    await new Promise((r) => setTimeout(r, 0));
+
+    expect(onSync).toHaveBeenCalledWith(commitSeq);
+
+    // Echo suppression: instance2 ignores events it originated.
+    onSync.mockClear();
+    await broadcaster.publish({
+      type: 'commit',
+      commitSeq,
+      sourceInstanceId: 'i2',
+    });
+    await new Promise((r) => setTimeout(r, 0));
+
+    expect(onSync).not.toHaveBeenCalled();
+
+    getSyncRealtimeUnsubscribe(routes1)?.();
+    getSyncRealtimeUnsubscribe(routes2)?.();
+    await broadcaster.close();
+    await db.destroy();
+  });
+});