@syncular/server-hono 0.0.3-8 → 0.0.4-26

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/server-hono",
-  "version": "0.0.3-8",
+  "version": "0.0.4-26",
   "description": "Hono adapter for the Syncular server with OpenAPI support",
   "license": "MIT",
   "author": "Benjamin Kniffler",
@@ -48,16 +48,17 @@
     "@hono/standard-validator": "^0.2.2",
     "@standard-community/standard-json": "^0.3.5",
     "@standard-community/standard-openapi": "^0.2.9",
-    "@syncular/core": "0.0.3-8",
-    "@syncular/server": "0.0.3-8",
+    "@syncular/console": "0.0.4-26",
+    "@syncular/core": "0.0.4-26",
+    "@syncular/server": "0.0.4-26",
     "@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.3-8",
-    "@syncular/server-dialect-postgres": "0.0.3-8",
+    "@syncular/dialect-pglite": "0.0.4-26",
+    "@syncular/server-dialect-postgres": "0.0.4-26",
     "kysely": "*",
     "zod": "*"
   },

package/src/console/gateway.ts

@@ -1081,7 +1081,15 @@ export function createConsoleGatewayRoutes(
     cors({
       origin: corsOrigins === '*' ? '*' : corsOrigins,
       allowMethods: ['GET', 'POST', 'DELETE', 'OPTIONS'],
-      allowHeaders: ['Content-Type', 'Authorization'],
+      allowHeaders: [
+        'Content-Type',
+        'Authorization',
+        'X-Syncular-Transport-Path',
+        'Baggage',
+        'Sentry-Trace',
+        'Traceparent',
+        'Tracestate',
+      ],
       credentials: true,
     })
   );

package/src/console/index.ts

@@ -7,3 +7,4 @@
 export * from './gateway';
 export * from './routes';
 export * from './schemas';
+export * from './ui';

package/src/console/routes.ts

@@ -586,7 +586,15 @@ export function createConsoleRoutes<DB extends SyncCoreDb>(
     cors({
       origin: corsOrigins === '*' ? '*' : corsOrigins,
       allowMethods: ['GET', 'POST', 'DELETE', 'OPTIONS'],
-      allowHeaders: ['Content-Type', 'Authorization'],
+      allowHeaders: [
+        'Content-Type',
+        'Authorization',
+        'X-Syncular-Transport-Path',
+        'Baggage',
+        'Sentry-Trace',
+        'Traceparent',
+        'Tracestate',
+      ],
       exposeHeaders: ['X-Total-Count'],
       credentials: true,
     })

package/src/console/ui.ts

@@ -0,0 +1,100 @@
+import {
+  type ConsoleStaticResponder,
+  type ConsoleUiPrefill,
+  type CreateConsoleStaticResponderOptions,
+  createConsoleStaticResponder,
+  type ServeConsoleStaticRequestOptions,
+} from '@syncular/console/server';
+import type { Context, Hono } from 'hono';
+
+type MaybePromise<T> = T | Promise<T>;
+
+export interface MountConsoleUiOptions {
+  /**
+   * Browser mount path for the console UI. Defaults to `/console`.
+   */
+  mountPath?: string;
+  /**
+   * API base path used to prefill the console server URL.
+   * Defaults to `/api`.
+   */
+  apiBasePath?: string;
+  /**
+   * Resolve prefill values per request.
+   * Return `null`/`undefined` to keep defaults.
+   */
+  resolvePrefill?: (
+    c: Context
+  ) => MaybePromise<ConsoleUiPrefill | null | undefined>;
+  /**
+   * Convenience callback for prefilled token.
+   */
+  resolveToken?: (c: Context) => MaybePromise<string | undefined>;
+  /**
+   * Override distributable directory.
+   */
+  staticDir?: string;
+  /**
+   * Cache-Control header for index responses.
+   */
+  indexCacheControl?: string;
+  /**
+   * Cache-Control header for static asset responses.
+   */
+  assetCacheControl?: string;
+}
+
+type StaticResponderConfig = Pick<
+  CreateConsoleStaticResponderOptions,
+  'mountPath' | 'staticDir' | 'indexCacheControl' | 'assetCacheControl'
+>;
+
+function normalizePath(pathname: string | undefined, fallback: string): string {
+  const value = pathname?.trim() ?? '';
+  if (!value) return fallback;
+  if (value === '/') return '/';
+  const withLeadingSlash = value.startsWith('/') ? value : `/${value}`;
+  return withLeadingSlash.replace(/\/+$/g, '') || '/';
+}
+
+export function mountConsoleUi(
+  app: Hono,
+  options: MountConsoleUiOptions = {}
+): void {
+  const mountPath = normalizePath(options.mountPath, '/console');
+  const apiBasePath = normalizePath(options.apiBasePath, '/api');
+
+  const staticResponderConfig: StaticResponderConfig = {
+    mountPath,
+    staticDir: options.staticDir,
+    indexCacheControl: options.indexCacheControl,
+    assetCacheControl: options.assetCacheControl,
+  };
+  const serveConsoleStatic: ConsoleStaticResponder =
+    createConsoleStaticResponder(staticResponderConfig);
+
+  const handler = async (c: Context) => {
+    const prefillFromResolver = await options.resolvePrefill?.(c);
+    const token = await options.resolveToken?.(c);
+    const origin = new URL(c.req.url).origin;
+
+    const prefill: ConsoleUiPrefill = {
+      basePath: mountPath,
+      serverUrl: `${origin}${apiBasePath}`,
+      ...prefillFromResolver,
+    };
+
+    if (token !== undefined) {
+      prefill.token = token;
+    }
+
+    const requestOptions: ServeConsoleStaticRequestOptions = { prefill };
+    const response = await serveConsoleStatic(c.req.raw, requestOptions);
+    if (!response) return c.notFound();
+    return response;
+  };
+
+  const wildcardPath = mountPath === '/' ? '/*' : `${mountPath}/*`;
+  app.get(mountPath, handler);
+  app.get(wildcardPath, handler);
+}

package/src/routes.ts

@@ -420,13 +420,13 @@ function emitConsoleLiveEvent(
       }
     | undefined,
   type: 'push' | 'pull' | 'commit' | 'client_update',
-  data: Record<string, unknown>
+  data: Record<string, unknown> | (() => Record<string, unknown>)
 ): void {
   if (!emitter) return;
   emitter.emit({
     type,
     timestamp: new Date().toISOString(),
-    data,
+    data: typeof data === 'function' ? data() : data,
   });
 }
 
@@ -453,6 +453,8 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
   const maxPullMaxSnapshotPages = config.maxPullMaxSnapshotPages ?? 10;
   const maxOperationsPerPush = config.maxOperationsPerPush ?? 200;
   const consoleLiveEmitter = options.consoleLiveEmitter;
+  const shouldEmitConsoleLiveEvents = consoleLiveEmitter !== undefined;
+  const shouldRecordRequestEvents = shouldEmitConsoleLiveEvents;
 
   // -------------------------------------------------------------------------
   // Optional WebSocket manager (scope-key based wake-ups)
@@ -611,13 +613,19 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
     `.execute(options.db);
   };
 
-  const recordRequestEventInBackground = (event: RequestEvent): void => {
-    void recordRequestEvent(event).catch((error) => {
+  const recordRequestEventInBackground = (
+    event: RequestEvent | (() => RequestEvent)
+  ): void => {
+    if (!shouldRecordRequestEvents) return;
+
+    const resolvedEvent = typeof event === 'function' ? event() : event;
+
+    void recordRequestEvent(resolvedEvent).catch((error) => {
       logAsyncFailureOnce('sync.request_event_record_failed', {
         event: 'sync.request_event_record_failed',
-        userId: event.actorId,
-        clientId: event.clientId,
-        requestEventType: event.eventType,
+        userId: resolvedEvent.actorId,
+        clientId: resolvedEvent.clientId,
+        requestEventType: resolvedEvent.eventType,
         error: error instanceof Error ? error.message : String(error),
       });
     });
@@ -761,7 +769,8 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
 
       // --- Push phase ---
       if (body.push) {
-        const pushOps = body.push.operations ?? [];
+        const pushBody = body.push;
+        const pushOps = pushBody.operations ?? [];
         if (pushOps.length > maxOperationsPerPush) {
           return c.json(
             {
@@ -782,9 +791,9 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
           partitionId,
           request: {
             clientId,
-            clientCommitId: body.push.clientCommitId,
-            operations: body.push.operations,
-            schemaVersion: body.push.schemaVersion,
+            clientCommitId: pushBody.clientCommitId,
+            operations: pushBody.operations,
+            schemaVersion: pushBody.schemaVersion,
           },
         });
 
@@ -799,7 +808,7 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
           commitSeq: pushed.response.commitSeq,
         });
 
-        recordRequestEventInBackground({
+        recordRequestEventInBackground(() => ({
           partitionId,
           requestId,
           traceId: traceContext.traceId,
@@ -820,14 +829,14 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
           payloadSnapshot: {
             request: {
               clientId,
-              clientCommitId: body.push.clientCommitId,
-              schemaVersion: body.push.schemaVersion,
-              operations: body.push.operations,
+              clientCommitId: pushBody.clientCommitId,
+              schemaVersion: pushBody.schemaVersion,
+              operations: pushBody.operations,
             },
             response: pushed.response,
           },
-        });
-        emitConsoleLiveEvent(consoleLiveEmitter, 'push', {
+        }));
+        emitConsoleLiveEvent(consoleLiveEmitter, 'push', () => ({
           partitionId,
           requestId,
           traceId: traceContext.traceId,
@@ -842,7 +851,7 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
           commitSeq: pushed.response.commitSeq ?? null,
           operationCount: pushOps.length,
           tables: pushed.affectedTables,
-        });
+        }));
 
         // WS notifications
         if (
@@ -895,13 +904,13 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
           pushed.response.status === 'applied' &&
           typeof pushed.response.commitSeq === 'number'
         ) {
-          emitConsoleLiveEvent(consoleLiveEmitter, 'commit', {
+          emitConsoleLiveEvent(consoleLiveEmitter, 'commit', () => ({
             partitionId,
             commitSeq: pushed.response.commitSeq,
             actorId: auth.actorId,
             clientId,
             affectedTables: pushed.affectedTables,
-          });
+          }));
         }
 
         pushResponse = pushed.response;
@@ -947,7 +956,7 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
             maxPullLimitSnapshotRows
           ),
           maxSnapshotPages: clampInt(
-            body.pull.maxSnapshotPages ?? 1,
+            body.pull.maxSnapshotPages ?? 4,
             1,
             maxPullMaxSnapshotPages
           ),
@@ -994,13 +1003,13 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
           effectiveScopes: pullResult.effectiveScopes,
         })
           .then(() => {
-            emitConsoleLiveEvent(consoleLiveEmitter, 'client_update', {
+            emitConsoleLiveEvent(consoleLiveEmitter, 'client_update', () => ({
               action: 'cursor_recorded',
               partitionId,
               actorId: auth.actorId,
               clientId,
               cursor: pullResult.clientCursor,
-            });
+            }));
           })
           .catch((error) => {
             logAsyncFailureOnce('sync.client_cursor_record_failed', {
@@ -1029,56 +1038,73 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
           clientCursor: pullResult.clientCursor,
         });
 
-        recordRequestEventInBackground({
-          partitionId,
-          requestId,
-          traceId: traceContext.traceId,
-          spanId: traceContext.spanId,
-          eventType: 'pull',
-          syncPath: 'http-combined',
-          actorId: auth.actorId,
-          clientId,
-          transportPath: readTransportPath(c),
-          statusCode: 200,
-          outcome: 'applied',
-          responseStatus: normalizeResponseStatus(200, 'applied'),
-          durationMs: pullDurationMs,
-          rowCount: countPullRows(pullResult.response),
-          subscriptionCount: request.subscriptions.length,
-          scopesSummary: summarizeScopeValues(pullResult.effectiveScopes),
-          payloadSnapshot: {
-            request: {
-              clientId,
-              limitCommits: request.limitCommits,
-              limitSnapshotRows: request.limitSnapshotRows,
-              maxSnapshotPages: request.maxSnapshotPages,
-              dedupeRows: request.dedupeRows,
-              subscriptions: request.subscriptions.map((subscription) => ({
-                id: subscription.id,
-                table: subscription.table,
-                scopes: subscription.scopes,
-                cursor: subscription.cursor,
-                bootstrapState: subscription.bootstrapState,
-              })),
-            },
-            response: summarizePullResponse(pullResult.response),
-          },
+        recordRequestEventInBackground(() => {
+          const pullRowCount = shouldRecordRequestEvents
+            ? countPullRows(pullResult.response)
+            : null;
+          const scopesSummary = shouldRecordRequestEvents
+            ? summarizeScopeValues(pullResult.effectiveScopes)
+            : null;
+          const payloadSnapshot = shouldRecordRequestEvents
+            ? {
+                request: {
+                  clientId,
+                  limitCommits: request.limitCommits,
+                  limitSnapshotRows: request.limitSnapshotRows,
+                  maxSnapshotPages: request.maxSnapshotPages,
+                  dedupeRows: request.dedupeRows,
+                  subscriptions: request.subscriptions.map((subscription) => ({
+                    id: subscription.id,
+                    table: subscription.table,
+                    scopes: subscription.scopes,
+                    cursor: subscription.cursor,
+                    bootstrapState: subscription.bootstrapState,
+                  })),
+                },
+                response: summarizePullResponse(pullResult.response),
+              }
+            : null;
+
+          return {
+            partitionId,
+            requestId,
+            traceId: traceContext.traceId,
+            spanId: traceContext.spanId,
+            eventType: 'pull',
+            syncPath: 'http-combined',
+            actorId: auth.actorId,
+            clientId,
+            transportPath: readTransportPath(c),
+            statusCode: 200,
+            outcome: 'applied',
+            responseStatus: normalizeResponseStatus(200, 'applied'),
+            durationMs: pullDurationMs,
+            rowCount: pullRowCount,
+            subscriptionCount: request.subscriptions.length,
+            scopesSummary,
+            payloadSnapshot,
+          };
         });
-        emitConsoleLiveEvent(consoleLiveEmitter, 'pull', {
-          partitionId,
-          requestId,
-          traceId: traceContext.traceId,
-          spanId: traceContext.spanId,
-          actorId: auth.actorId,
-          clientId,
-          transportPath: readTransportPath(c),
-          syncPath: 'http-combined',
-          outcome: 'applied',
-          statusCode: 200,
-          durationMs: pullDurationMs,
-          rowCount: countPullRows(pullResult.response),
-          subscriptionCount: request.subscriptions.length,
-          clientCursor: pullResult.clientCursor,
+        emitConsoleLiveEvent(consoleLiveEmitter, 'pull', () => {
+          const pullRowCount = shouldEmitConsoleLiveEvents
+            ? countPullRows(pullResult.response)
+            : null;
+          return {
+            partitionId,
+            requestId,
+            traceId: traceContext.traceId,
+            spanId: traceContext.spanId,
+            actorId: auth.actorId,
+            clientId,
+            transportPath: readTransportPath(c),
+            syncPath: 'http-combined',
+            outcome: 'applied',
+            statusCode: 200,
+            durationMs: pullDurationMs,
+            rowCount: pullRowCount,
+            subscriptionCount: request.subscriptions.length,
+            clientCursor: pullResult.clientCursor,
+          };
         });
 
         pullResponse = pullResult.response;
@@ -1309,14 +1335,14 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
 
           unregister = wsConnectionManager.register(conn, initialScopeKeys);
           conn.sendHeartbeat();
-          emitConsoleLiveEvent(consoleLiveEmitter, 'client_update', {
+          emitConsoleLiveEvent(consoleLiveEmitter, 'client_update', () => ({
             action: 'realtime_connected',
             actorId: auth.actorId,
             clientId,
             partitionId,
             transportPath: realtimeTransportPath,
             scopeCount: initialScopeKeys.length,
-          });
+          }));
         },
         onClose(_evt, _ws) {
           unregister?.();
@@ -1326,12 +1352,12 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
             event: 'sync.realtime.disconnect',
             userId: auth.actorId,
           });
-          emitConsoleLiveEvent(consoleLiveEmitter, 'client_update', {
+          emitConsoleLiveEvent(consoleLiveEmitter, 'client_update', () => ({
             action: 'realtime_disconnected',
             actorId: auth.actorId,
             clientId,
             partitionId,
-          });
+          }));
         },
         onError(_evt, _ws) {
           unregister?.();
@@ -1341,12 +1367,12 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
             event: 'sync.realtime.disconnect',
             userId: auth.actorId,
           });
-          emitConsoleLiveEvent(consoleLiveEmitter, 'client_update', {
+          emitConsoleLiveEvent(consoleLiveEmitter, 'client_update', () => ({
             action: 'realtime_error',
             actorId: auth.actorId,
             clientId,
             partitionId,
-          });
+          }));
         },
         onMessage(evt, _ws) {
           if (!connRef) return;
@@ -1479,7 +1505,7 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
             { opIndex: 0, status: 'error', error: 'Invalid push payload' },
           ],
         });
-        recordRequestEventInBackground({
+        recordRequestEventInBackground(() => ({
           partitionId,
           requestId,
           traceId: traceContext.traceId,
@@ -1503,8 +1529,8 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
               reason: 'invalid_push_payload',
             },
           },
-        });
-        emitConsoleLiveEvent(consoleLiveEmitter, 'push', {
+        }));
+        emitConsoleLiveEvent(consoleLiveEmitter, 'push', () => ({
           partitionId,
           requestId,
           traceId: traceContext.traceId,
@@ -1517,7 +1543,7 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
           statusCode: 400,
           durationMs: invalidDurationMs,
           errorCode: 'INVALID_PUSH_PAYLOAD',
-        });
+        }));
         return;
       }
 
@@ -1536,7 +1562,7 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
             },
           ],
         });
-        recordRequestEventInBackground({
+        recordRequestEventInBackground(() => ({
           partitionId,
           requestId,
           traceId: traceContext.traceId,
@@ -1566,8 +1592,8 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
               reason: 'max_operations_exceeded',
             },
           },
-        });
-        emitConsoleLiveEvent(consoleLiveEmitter, 'push', {
+        }));
+        emitConsoleLiveEvent(consoleLiveEmitter, 'push', () => ({
           partitionId,
           requestId,
           traceId: traceContext.traceId,
@@ -1581,7 +1607,7 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
           durationMs: rejectedDurationMs,
           operationCount: pushOps.length,
           errorCode: 'MAX_OPERATIONS_EXCEEDED',
-        });
+        }));
         return;
       }
 
@@ -1610,7 +1636,7 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
         commitSeq: pushed.response.commitSeq,
       });
 
-      recordRequestEventInBackground({
+      recordRequestEventInBackground(() => ({
         partitionId,
         requestId,
         traceId: traceContext.traceId,
@@ -1637,8 +1663,8 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
           },
           response: pushed.response,
         },
-      });
-      emitConsoleLiveEvent(consoleLiveEmitter, 'push', {
+      }));
+      emitConsoleLiveEvent(consoleLiveEmitter, 'push', () => ({
         partitionId,
         requestId,
         traceId: traceContext.traceId,
@@ -1653,7 +1679,7 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
         commitSeq: pushed.response.commitSeq ?? null,
         operationCount: pushOps.length,
         tables: pushed.affectedTables,
-      });
+      }));
 
       // WS notifications to other clients
       if (
@@ -1702,13 +1728,13 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
         pushed.response.status === 'applied' &&
         typeof pushed.response.commitSeq === 'number'
       ) {
-        emitConsoleLiveEvent(consoleLiveEmitter, 'commit', {
+        emitConsoleLiveEvent(consoleLiveEmitter, 'commit', () => ({
           partitionId,
           commitSeq: pushed.response.commitSeq,
           actorId,
           clientId,
           affectedTables: pushed.affectedTables,
-        });
+        }));
       }
 
       conn.sendPushResponse({
@@ -1729,7 +1755,7 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
       });
       const message =
         err instanceof Error ? err.message : 'Internal server error';
-      recordRequestEventInBackground({
+      recordRequestEventInBackground(() => ({
         partitionId,
         requestId,
         traceId: traceContext.traceId,
@@ -1754,8 +1780,8 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
             message,
           },
         },
-      });
-      emitConsoleLiveEvent(consoleLiveEmitter, 'push', {
+      }));
+      emitConsoleLiveEvent(consoleLiveEmitter, 'push', () => ({
         partitionId,
         requestId,
         traceId: traceContext.traceId,
@@ -1768,7 +1794,7 @@ export function createSyncRoutes<DB extends SyncCoreDb = SyncCoreDb>(
         statusCode: 500,
         durationMs: failedDurationMs,
         errorCode: 'INTERNAL_SERVER_ERROR',
-      });
+      }));
       conn.sendPushResponse({
         requestId,
         ok: false,