@syncular/server-hono 0.0.6-56 → 0.0.6-66

package/src/console/routes.ts

@@ -16,7 +16,7 @@
  */
 
 import { logSyncEvent } from '@syncular/core';
-import type { SyncCoreDb } from '@syncular/server';
+import type { SyncCoreDb, SyncServerAuth } from '@syncular/server';
 import {
   compactChanges,
   computePruneWatermarkCommitSeq,
@@ -391,9 +391,10 @@ const handlersResponseSchema = z.object({
   items: z.array(ConsoleHandlerSchema),
 });
 
-export function createConsoleRoutes<DB extends SyncCoreDb>(
-  options: CreateConsoleRoutesOptions<DB>
-): Hono {
+export function createConsoleRoutes<
+  DB extends SyncCoreDb,
+  Auth extends SyncServerAuth,
+>(options: CreateConsoleRoutesOptions<DB, Auth>): Hono {
   const routes = new Hono();
 
   routes.onError((error, context) => {
@@ -3337,143 +3338,153 @@ export function createConsoleRoutes<DB extends SyncCoreDb>(
   // -----------------------------------------------------------------------
   // Storage endpoints
   // -----------------------------------------------------------------------
-  if (options.blobBucket) {
-    const bucket = options.blobBucket;
+  const bucket = options.blobBucket;
 
-    routes.get(
-      '/storage',
-      describeRoute({
-        tags: ['console'],
-        summary: 'List storage items',
-        responses: {
-          200: {
-            description: 'Paginated list of storage items',
-            content: {
-              'application/json': {
-                schema: resolver(ConsoleBlobListResponseSchema),
-              },
+  routes.get(
+    '/storage',
+    describeRoute({
+      tags: ['console'],
+      summary: 'List storage items',
+      responses: {
+        200: {
+          description: 'Paginated list of storage items',
+          content: {
+            'application/json': {
+              schema: resolver(ConsoleBlobListResponseSchema),
             },
           },
-          401: {
-            description: 'Unauthenticated',
-            content: {
-              'application/json': { schema: resolver(ErrorResponseSchema) },
-            },
+        },
+        401: {
+          description: 'Unauthenticated',
+          content: {
+            'application/json': { schema: resolver(ErrorResponseSchema) },
           },
         },
-      }),
-      zValidator('query', ConsoleBlobListQuerySchema),
-      async (c) => {
-        const auth = await requireAuth(c);
-        if (!auth) return c.json({ error: 'UNAUTHENTICATED' }, 401);
-
-        const { prefix, cursor, limit } = c.req.valid('query');
-        const listed = await bucket.list({
-          prefix: prefix || undefined,
-          cursor: cursor || undefined,
-          limit,
-        });
+      },
+    }),
+    zValidator('query', ConsoleBlobListQuerySchema),
+    async (c) => {
+      const auth = await requireAuth(c);
+      if (!auth) return c.json({ error: 'UNAUTHENTICATED' }, 401);
 
-        return c.json(
-          {
-            items: listed.objects.map((obj) => ({
-              key: obj.key,
-              size: obj.size,
-              uploaded: obj.uploaded.toISOString(),
-              httpMetadata: obj.httpMetadata?.contentType
-                ? { contentType: obj.httpMetadata.contentType }
-                : undefined,
-            })),
-            truncated: listed.truncated,
-            cursor: listed.cursor ?? null,
-          },
-          200
-        );
+      if (!bucket) {
+        return c.json({ error: 'BLOB_STORAGE_NOT_CONFIGURED' }, 501);
       }
-    );
 
-    routes.get(
-      '/storage/:key{.+}/download',
-      describeRoute({
-        tags: ['console'],
-        summary: 'Download a storage item',
-        responses: {
-          200: { description: 'Storage item contents' },
-          401: {
-            description: 'Unauthenticated',
-            content: {
-              'application/json': { schema: resolver(ErrorResponseSchema) },
-            },
+      const { prefix, cursor, limit } = c.req.valid('query');
+      const listed = await bucket.list({
+        prefix: prefix || undefined,
+        cursor: cursor || undefined,
+        limit,
+      });
+
+      return c.json(
+        {
+          items: listed.objects.map((obj) => ({
+            key: obj.key,
+            size: obj.size,
+            uploaded: obj.uploaded.toISOString(),
+            httpMetadata: obj.httpMetadata?.contentType
+              ? { contentType: obj.httpMetadata.contentType }
+              : undefined,
+          })),
+          truncated: listed.truncated,
+          cursor: listed.cursor ?? null,
+        },
+        200
+      );
+    }
+  );
+
+  routes.get(
+    '/storage/:key{.+}/download',
+    describeRoute({
+      tags: ['console'],
+      summary: 'Download a storage item',
+      responses: {
+        200: { description: 'Storage item contents' },
+        401: {
+          description: 'Unauthenticated',
+          content: {
+            'application/json': { schema: resolver(ErrorResponseSchema) },
           },
-          404: {
-            description: 'Blob not found',
-            content: {
-              'application/json': { schema: resolver(ErrorResponseSchema) },
-            },
+        },
+        404: {
+          description: 'Blob not found',
+          content: {
+            'application/json': { schema: resolver(ErrorResponseSchema) },
           },
         },
-      }),
-      async (c) => {
-        const auth = await requireAuth(c);
-        if (!auth) return c.json({ error: 'UNAUTHENTICATED' }, 401);
-
-        const key = decodeURIComponent(c.req.param('key'));
-        const object = await bucket.get(key);
-        if (!object) {
-          return c.json({ error: 'BLOB_NOT_FOUND' }, 404);
-        }
+      },
+    }),
+    async (c) => {
+      const auth = await requireAuth(c);
+      if (!auth) return c.json({ error: 'UNAUTHENTICATED' }, 401);
 
-        const headers = new Headers();
-        headers.set('Content-Length', String(object.size));
-        headers.set(
-          'Content-Type',
-          object.httpMetadata?.contentType ?? 'application/octet-stream'
-        );
-        const filename = key.split('/').pop() || key;
-        headers.set(
-          'Content-Disposition',
-          `attachment; filename="${filename.replace(/"/g, '\\"')}"`
-        );
+      if (!bucket) {
+        return c.json({ error: 'BLOB_STORAGE_NOT_CONFIGURED' }, 501);
+      }
 
-        return new Response(object.body as ReadableStream, {
-          status: 200,
-          headers,
-        });
+      const key = decodeURIComponent(c.req.param('key'));
+      const object = await bucket.get(key);
+      if (!object) {
+        return c.json({ error: 'BLOB_NOT_FOUND' }, 404);
       }
-    );
 
-    routes.delete(
-      '/storage/:key{.+}',
-      describeRoute({
-        tags: ['console'],
-        summary: 'Delete a storage item',
-        responses: {
-          200: {
-            description: 'Storage item deleted',
-            content: {
-              'application/json': {
-                schema: resolver(ConsoleBlobDeleteResponseSchema),
-              },
+      const headers = new Headers();
+      headers.set('Content-Length', String(object.size));
+      headers.set(
+        'Content-Type',
+        object.httpMetadata?.contentType ?? 'application/octet-stream'
+      );
+      const filename = key.split('/').pop() || key;
+      headers.set(
+        'Content-Disposition',
+        `attachment; filename="${filename.replace(/"/g, '\\"')}"`
+      );
+
+      return new Response(object.body as ReadableStream, {
+        status: 200,
+        headers,
+      });
+    }
+  );
+
+  routes.delete(
+    '/storage/:key{.+}',
+    describeRoute({
+      tags: ['console'],
+      summary: 'Delete a storage item',
+      responses: {
+        200: {
+          description: 'Storage item deleted',
+          content: {
+            'application/json': {
+              schema: resolver(ConsoleBlobDeleteResponseSchema),
             },
           },
-          401: {
-            description: 'Unauthenticated',
-            content: {
-              'application/json': { schema: resolver(ErrorResponseSchema) },
-            },
+        },
+        401: {
+          description: 'Unauthenticated',
+          content: {
+            'application/json': { schema: resolver(ErrorResponseSchema) },
           },
         },
-      }),
-      async (c) => {
-        const auth = await requireAuth(c);
-        if (!auth) return c.json({ error: 'UNAUTHENTICATED' }, 401);
+      },
+    }),
+    async (c) => {
+      const auth = await requireAuth(c);
+      if (!auth) return c.json({ error: 'UNAUTHENTICATED' }, 401);
 
-        const key = decodeURIComponent(c.req.param('key'));
-        await bucket.delete(key);
-        return c.json({ deleted: true }, 200);
+      if (!bucket) {
+        return c.json({ error: 'BLOB_STORAGE_NOT_CONFIGURED' }, 501);
       }
-    );
-  }
+
+      const key = decodeURIComponent(c.req.param('key'));
+      await bucket.delete(key);
+      return c.json({ deleted: true }, 200);
+    }
+  );
 
   return routes;
 }

package/src/console/types.ts

@@ -2,6 +2,7 @@ import type {
   ServerSyncDialect,
   ServerTableHandler,
   SyncCoreDb,
+  SyncServerAuth,
 } from '@syncular/server';
 import type { Context } from 'hono';
 import type { UpgradeWebSocket } from 'hono/ws';
@@ -90,11 +91,13 @@ export interface ConsoleSharedOptions {
   blobBucket?: ConsoleBlobBucket;
 }
 
-export interface CreateConsoleRoutesOptions<DB extends SyncCoreDb = SyncCoreDb>
-  extends ConsoleSharedOptions {
+export interface CreateConsoleRoutesOptions<
+  DB extends SyncCoreDb = SyncCoreDb,
+  Auth extends SyncServerAuth = SyncServerAuth,
+> extends ConsoleSharedOptions {
   db: Kysely<DB>;
   dialect: ServerSyncDialect;
-  handlers: ServerTableHandler<DB>[];
+  handlers: ServerTableHandler<DB, Auth>[];
   /**
    * Authentication function for console requests.
    * Return null to reject the request.

package/src/create-server.ts

@@ -2,17 +2,16 @@
  * Simplified server factory for Hono
  *
  * Breaking changes from legacy createSyncRoutes:
- * - handlers: array instead of TableRegistry
+ * - sync contract instead of top-level handlers/authenticate
  * - Combined sync + console routes in one call
  */
 
 import type {
+  ServerSyncConfig,
   ServerSyncDialect,
-  ServerTableHandler,
   SnapshotChunkStorage,
   SyncCoreDb,
 } from '@syncular/server';
-import type { Context } from 'hono';
 import type { UpgradeWebSocket } from 'hono/ws';
 import type { Kysely } from 'kysely';
 import {
@@ -31,26 +30,24 @@ import {
   type SyncRoutesConfigWithRateLimit,
 } from './routes';
 
-export interface SyncServerOptions<DB extends SyncCoreDb = SyncCoreDb> {
+export interface SyncServerOptions<
+  DB extends SyncCoreDb = SyncCoreDb,
+  Auth extends SyncAuthResult = SyncAuthResult,
+> {
   /** Kysely database instance */
   db: Kysely<DB>;
 
   /** Server sync dialect */
   dialect: ServerSyncDialect;
 
-  /**
-   * Table handlers for sync operations.
-   */
-  handlers: ServerTableHandler<DB>[];
-
-  /** Authentication function - returns actorId or null for unauthenticated */
-  authenticate: (c: Context) => Promise<SyncAuthResult | null>;
+  /** Sync contract with auth + table handlers */
+  sync: ServerSyncConfig<DB, Auth>;
 
   /** Snapshot chunk storage (external body storage, e.g. R2/S3) */
   chunkStorage?: SnapshotChunkStorage;
 
   /** Sync route configuration */
-  sync?: SyncRoutesConfigWithRateLimit;
+  routes?: SyncRoutesConfigWithRateLimit;
 
   /** WebSocket upgrader for realtime */
   upgradeWebSocket?: UpgradeWebSocket;
@@ -81,45 +78,37 @@ export interface SyncServerResult {
  *
  * @example
  * ```typescript
- * // With handlers
+ * // With sync contract
  * const { syncRoutes } = createSyncServer({
  *   db,
  *   dialect,
- *   handlers: [tasksHandler, notesHandler],
- *   authenticate: async (c) => {
- *     const userId = c.req.header('x-user-id');
- *     return userId ? { actorId: userId } : null;
- *   },
+ *   sync,
  * });
  *
  * // With custom handlers
  * const { syncRoutes, consoleRoutes } = createSyncServer({
  *   db,
  *   dialect,
- *   handlers: [tasksHandler, notesHandler],
- *   authenticate: async (c) => {
- *     const userId = c.req.header('x-user-id');
- *     return userId ? { actorId: userId } : null;
- *   },
+ *   sync,
  *   console: { token: process.env.CONSOLE_TOKEN },
  * });
  * ```
  */
-export function createSyncServer<DB extends SyncCoreDb = SyncCoreDb>(
-  options: SyncServerOptions<DB>
-): SyncServerResult {
+export function createSyncServer<
+  DB extends SyncCoreDb = SyncCoreDb,
+  Auth extends SyncAuthResult = SyncAuthResult,
+>(options: SyncServerOptions<DB, Auth>): SyncServerResult {
   const {
     db,
     dialect,
-    handlers,
-    authenticate,
-    chunkStorage,
     sync,
+    chunkStorage,
+    routes,
     upgradeWebSocket,
     console: consoleConfig,
   } = options;
 
-  if (handlers.length === 0) {
+  if (sync.handlers.length === 0) {
     throw new Error('At least one handler must be provided');
   }
 
@@ -146,24 +135,25 @@ export function createSyncServer<DB extends SyncCoreDb = SyncCoreDb>(
   const syncRoutes = createSyncRoutes({
     db,
     dialect,
-    handlers,
-    authenticate,
+    handlers: sync.handlers,
+    authenticate: async (context): Promise<Auth | null> =>
+      sync.authenticate(context.req.raw),
     chunkStorage,
     consoleLiveEmitter: consoleEventEmitter,
     sync: {
-      ...sync,
+      ...routes,
       websocket: upgradeWebSocket
         ? {
             enabled: true,
             upgradeWebSocket,
-            ...(sync?.websocket?.heartbeatIntervalMs !== undefined && {
-              heartbeatIntervalMs: sync.websocket.heartbeatIntervalMs,
+            ...(routes?.websocket?.heartbeatIntervalMs !== undefined && {
+              heartbeatIntervalMs: routes.websocket.heartbeatIntervalMs,
             }),
-            ...(sync?.websocket?.maxConnectionsTotal !== undefined && {
-              maxConnectionsTotal: sync.websocket.maxConnectionsTotal,
+            ...(routes?.websocket?.maxConnectionsTotal !== undefined && {
+              maxConnectionsTotal: routes.websocket.maxConnectionsTotal,
             }),
-            ...(sync?.websocket?.maxConnectionsPerClient !== undefined && {
-              maxConnectionsPerClient: sync.websocket.maxConnectionsPerClient,
+            ...(routes?.websocket?.maxConnectionsPerClient !== undefined && {
+              maxConnectionsPerClient: routes.websocket.maxConnectionsPerClient,
             }),
           }
         : { enabled: false },
@@ -178,7 +168,7 @@ export function createSyncServer<DB extends SyncCoreDb = SyncCoreDb>(
   const consoleRoutes = createConsoleRoutes({
     db,
     dialect,
-    handlers,
+    handlers: sync.handlers,
     authenticate: createTokenAuthenticator(consoleToken),
     corsOrigins: resolvedConsoleConfig.corsOrigins ?? '*',
     eventEmitter: consoleEventEmitter,

package/src/proxy/connection-manager.ts

@@ -11,7 +11,7 @@ import type {
 } from '@syncular/core';
 import type {
   ExecuteProxyQueryResult,
-  ProxyTableRegistry,
+  ProxyHandlerCollection,
   ServerSyncDialect,
   SyncCoreDb,
 } from '@syncular/server';
@@ -26,8 +26,8 @@ export interface ProxyConnectionManagerConfig<
   db: Kysely<DB>;
   /** Server sync dialect */
   dialect: ServerSyncDialect;
-  /** Proxy table registry for oplog generation */
-  handlers: ProxyTableRegistry;
+  /** Proxy table handlers for oplog generation */
+  handlers: ProxyHandlerCollection;
   /** Maximum concurrent connections (default: 100) */
   maxConnections?: number;
   /** Idle connection timeout in ms (default: 30000) */

package/src/proxy/routes.ts

@@ -12,7 +12,7 @@ import type {
 } from '@syncular/core';
 import { logSyncEvent } from '@syncular/core';
 import type {
-  ProxyTableRegistry,
+  ProxyHandlerCollection,
   ServerSyncDialect,
   SyncCoreDb,
 } from '@syncular/server';
@@ -48,8 +48,8 @@ interface CreateProxyRoutesConfig<DB extends SyncCoreDb = SyncCoreDb> {
   db: Kysely<DB>;
   /** Server sync dialect */
   dialect: ServerSyncDialect;
-  /** Proxy table registry for oplog generation */
-  handlers: ProxyTableRegistry;
+  /** Proxy table handlers for oplog generation */
+  handlers: ProxyHandlerCollection;
   /** Authenticate the request and return actor info */
   authenticate: (c: Context) => Promise<ProxyAuthResult | null>;
   /** WebSocket upgrade function from Hono */
@@ -75,7 +75,7 @@ interface CreateProxyRoutesConfig<DB extends SyncCoreDb = SyncCoreDb> {
  *
  * app.route('/proxy', createProxyRoutes({
  *   db,
- *   handlers: proxyTableRegistry,
+ *   handlers: proxyHandlers,
  *   authenticate: async (c) => {
  *     // Verify admin auth
  *     return { actorId: 'admin:123' };

package/src/routes.ts

@@ -23,9 +23,11 @@ import type {
   SyncCoreDb,
   SyncRealtimeBroadcaster,
   SyncRealtimeEvent,
+  SyncServerAuth,
 } from '@syncular/server';
 import {
   type CompactOptions,
+  createServerHandlerCollection,
   InvalidSubscriptionScopeError,
   type PruneOptions,
   type PullResult,
@@ -33,7 +35,6 @@ import {
   pushCommit,
   readSnapshotChunk,
   recordClientCursor,
-  TableRegistry,
 } from '@syncular/server';
 import type { Context, MiddlewareHandler } from 'hono';
 import { Hono } from 'hono';
@@ -64,10 +65,7 @@ import {
 const wsConnectionManagerMap = new WeakMap<Hono, WebSocketConnectionManager>();
 const realtimeUnsubscribeMap = new WeakMap<Hono, () => void>();
 
-export interface SyncAuthResult {
-  actorId: string;
-  partitionId?: string;
-}
+export interface SyncAuthResult extends SyncServerAuth {}
 
 /**
  * WebSocket configuration for realtime sync.
@@ -162,11 +160,14 @@ export interface SyncRoutesConfigWithRateLimit {
   };
 }
 
-export interface CreateSyncRoutesOptions<DB extends SyncCoreDb = SyncCoreDb> {
+export interface CreateSyncRoutesOptions<
+  DB extends SyncCoreDb = SyncCoreDb,
+  Auth extends SyncAuthResult = SyncAuthResult,
+> {
   db: Kysely<DB>;
   dialect: ServerSyncDialect;
-  handlers: ServerTableHandler<DB>[];
-  authenticate: (c: Context) => Promise<SyncAuthResult | null>;
+  handlers: ServerTableHandler<DB, Auth>[];
+  authenticate: (c: Context) => Promise<Auth | null>;
   sync?: SyncRoutesConfigWithRateLimit;
   wsConnectionManager?: WebSocketConnectionManager;
   /**
@@ -430,9 +431,10 @@ function emitConsoleLiveEvent(
   });
 }
 
-export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
-  options: CreateSyncRoutesOptions<DB>
-): Hono {
+export function createSyncRoutes<
+  DB extends SyncCoreDb = SyncCoreDb,
+  Auth extends SyncAuthResult = SyncAuthResult,
+>(options: CreateSyncRoutesOptions<DB, Auth>): Hono {
   const routes = new Hono();
   routes.onError((error, c) => {
     captureSyncException(error, {
@@ -442,10 +444,7 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
     });
     return c.text('Internal Server Error', 500);
   });
-  const handlerRegistry = new TableRegistry<DB>();
-  for (const handler of options.handlers) {
-    handlerRegistry.register(handler);
-  }
+  const handlerRegistry = createServerHandlerCollection(options.handlers);
   const config = options.sync ?? {};
   const maxPullLimitCommits = config.maxPullLimitCommits ?? 100;
   const maxSubscriptionsPerPull = config.maxSubscriptionsPerPull ?? 200;
@@ -631,8 +630,8 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
     });
   };
 
-  const authCache = new WeakMap<Context, Promise<SyncAuthResult | null>>();
-  const getAuth = (c: Context): Promise<SyncAuthResult | null> => {
+  const authCache = new WeakMap<Context, Promise<Auth | null>>();
+  const getAuth = (c: Context): Promise<Auth | null> => {
     const cached = authCache.get(c);
     if (cached) return cached;
     const pending = options.authenticate(c);
@@ -787,8 +786,7 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
           db: options.db,
           dialect: options.dialect,
           handlers: handlerRegistry,
-          actorId: auth.actorId,
-          partitionId,
+          auth,
           request: {
             clientId,
             clientCommitId: pushBody.clientCommitId,
@@ -979,8 +977,7 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
             db: options.db,
             dialect: options.dialect,
             handlers: handlerRegistry,
-            actorId: auth.actorId,
-            partitionId,
+            auth,
             request,
             chunkStorage: options.chunkStorage,
           });
@@ -1383,13 +1380,7 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
             if (!msg || typeof msg !== 'object') return;
 
             if (msg.type === 'push') {
-              void handleWsPush(
-                msg,
-                connRef,
-                auth.actorId,
-                partitionId,
-                clientId
-              );
+              void handleWsPush(msg, connRef, auth, clientId);
               return;
             }
 
@@ -1481,10 +1472,11 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
   async function handleWsPush(
     msg: Record<string, unknown>,
     conn: WebSocketConnection,
-    actorId: string,
-    partitionId: string,
+    auth: Auth,
     clientId: string
   ): Promise<void> {
+    const actorId = auth.actorId;
+    const partitionId = auth.partitionId ?? 'default';
     const requestId = typeof msg.requestId === 'string' ? msg.requestId : '';
     if (!requestId) return;
     const traceContext = readTraceContextFromMessage(msg);
@@ -1615,8 +1607,7 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
         db: options.db,
         dialect: options.dialect,
         handlers: handlerRegistry,
-        actorId,
-        partitionId,
+        auth,
         request: {
           clientId,
           clientCommitId: parsed.data.clientCommitId,