@syncular/server-hono 0.0.1-60

package/src/console/schemas.ts

@@ -0,0 +1,299 @@
+/**
+ * @syncular/server-hono - Console API Zod schemas
+ */
+
+import { z } from 'zod';
+
+// ============================================================================
+// Stats Schema
+// ============================================================================
+
+export const SyncStatsSchema = z.object({
+  commitCount: z.number().int(),
+  changeCount: z.number().int(),
+  minCommitSeq: z.number().int(),
+  maxCommitSeq: z.number().int(),
+  clientCount: z.number().int(),
+  activeClientCount: z.number().int(),
+  minActiveClientCursor: z.number().int().nullable(),
+  maxActiveClientCursor: z.number().int().nullable(),
+});
+
+export type SyncStats = z.infer<typeof SyncStatsSchema>;
+
+// ============================================================================
+// Commit Schemas
+// ============================================================================
+
+export const ConsoleCommitListItemSchema = z.object({
+  commitSeq: z.number().int(),
+  actorId: z.string(),
+  clientId: z.string(),
+  clientCommitId: z.string(),
+  createdAt: z.string(),
+  changeCount: z.number().int(),
+  affectedTables: z.array(z.string()),
+});
+
+export type ConsoleCommitListItem = z.infer<typeof ConsoleCommitListItemSchema>;
+
+export const ConsoleChangeSchema = z.object({
+  changeId: z.number().int(),
+  table: z.string(),
+  rowId: z.string(),
+  op: z.enum(['upsert', 'delete']),
+  rowJson: z.unknown().nullable(),
+  rowVersion: z.number().int().nullable(),
+  scopes: z.record(z.string(), z.unknown()),
+});
+
+export type ConsoleChange = z.infer<typeof ConsoleChangeSchema>;
+
+export const ConsoleCommitDetailSchema = ConsoleCommitListItemSchema.extend({
+  changes: z.array(ConsoleChangeSchema),
+});
+
+export type ConsoleCommitDetail = z.infer<typeof ConsoleCommitDetailSchema>;
+
+// ============================================================================
+// Client Schemas
+// ============================================================================
+
+export const ConsoleClientSchema = z.object({
+  clientId: z.string(),
+  actorId: z.string(),
+  cursor: z.number().int(),
+  lagCommitCount: z.number().int().nonnegative(),
+  connectionPath: z.enum(['direct', 'relay']),
+  connectionMode: z.enum(['polling', 'realtime']),
+  realtimeConnectionCount: z.number().int().nonnegative(),
+  isRealtimeConnected: z.boolean(),
+  activityState: z.enum(['active', 'idle', 'stale']),
+  lastRequestAt: z.string().nullable(),
+  lastRequestType: z.enum(['push', 'pull']).nullable(),
+  lastRequestOutcome: z.string().nullable(),
+  effectiveScopes: z.record(z.string(), z.unknown()),
+  updatedAt: z.string(),
+});
+
+export type ConsoleClient = z.infer<typeof ConsoleClientSchema>;
+
+// ============================================================================
+// Handler Schemas
+// ============================================================================
+
+export const ConsoleHandlerSchema = z.object({
+  table: z.string(),
+  dependsOn: z.array(z.string()).optional(),
+  snapshotChunkTtlMs: z.number().int().optional(),
+});
+
+export type ConsoleHandler = z.infer<typeof ConsoleHandlerSchema>;
+
+// ============================================================================
+// Prune & Compact Schemas
+// ============================================================================
+
+export const ConsolePrunePreviewSchema = z.object({
+  watermarkCommitSeq: z.number().int(),
+  commitsToDelete: z.number().int(),
+});
+
+export type ConsolePrunePreview = z.infer<typeof ConsolePrunePreviewSchema>;
+
+export const ConsolePruneResultSchema = z.object({
+  deletedCommits: z.number().int(),
+});
+
+export type ConsolePruneResult = z.infer<typeof ConsolePruneResultSchema>;
+
+export const ConsoleCompactResultSchema = z.object({
+  deletedChanges: z.number().int(),
+});
+
+export type ConsoleCompactResult = z.infer<typeof ConsoleCompactResultSchema>;
+
+// ============================================================================
+// Evict Schema
+// ============================================================================
+
+export const ConsoleEvictResultSchema = z.object({
+  evicted: z.boolean(),
+});
+
+export type ConsoleEvictResult = z.infer<typeof ConsoleEvictResultSchema>;
+
+// ============================================================================
+// Request Event Schemas
+// ============================================================================
+
+export const ConsoleRequestEventSchema = z.object({
+  eventId: z.number().int(),
+  eventType: z.enum(['push', 'pull']),
+  transportPath: z.enum(['direct', 'relay']),
+  actorId: z.string(),
+  clientId: z.string(),
+  statusCode: z.number().int(),
+  outcome: z.string(),
+  durationMs: z.number().int(),
+  commitSeq: z.number().int().nullable(),
+  operationCount: z.number().int().nullable(),
+  rowCount: z.number().int().nullable(),
+  tables: z.array(z.string()),
+  errorMessage: z.string().nullable(),
+  createdAt: z.string(),
+});
+
+export type ConsoleRequestEvent = z.infer<typeof ConsoleRequestEventSchema>;
+
+export const ConsoleClearEventsResultSchema = z.object({
+  deletedCount: z.number().int(),
+});
+
+export type ConsoleClearEventsResult = z.infer<
+  typeof ConsoleClearEventsResultSchema
+>;
+
+export const ConsolePruneEventsResultSchema = z.object({
+  deletedCount: z.number().int(),
+});
+
+export type ConsolePruneEventsResult = z.infer<
+  typeof ConsolePruneEventsResultSchema
+>;
+
+// ============================================================================
+// API Key Schemas
+// ============================================================================
+
+export const ApiKeyTypeSchema = z.enum(['relay', 'proxy', 'admin']);
+export type ApiKeyType = z.infer<typeof ApiKeyTypeSchema>;
+
+export const ConsoleApiKeySchema = z.object({
+  keyId: z.string(),
+  keyPrefix: z.string(),
+  name: z.string(),
+  keyType: ApiKeyTypeSchema,
+  scopeKeys: z.array(z.string()),
+  actorId: z.string().nullable(),
+  createdAt: z.string(),
+  expiresAt: z.string().nullable(),
+  lastUsedAt: z.string().nullable(),
+  revokedAt: z.string().nullable(),
+});
+
+export type ConsoleApiKey = z.infer<typeof ConsoleApiKeySchema>;
+
+export const ConsoleApiKeyCreateRequestSchema = z.object({
+  name: z.string().min(1),
+  keyType: ApiKeyTypeSchema,
+  scopeKeys: z.array(z.string()).optional(),
+  actorId: z.string().optional(),
+  expiresInDays: z.number().int().positive().optional(),
+});
+
+export const ConsoleApiKeyCreateResponseSchema = z.object({
+  key: ConsoleApiKeySchema,
+  secretKey: z.string(),
+});
+
+export type ConsoleApiKeyCreateResponse = z.infer<
+  typeof ConsoleApiKeyCreateResponseSchema
+>;
+
+export const ConsoleApiKeyRevokeResponseSchema = z.object({
+  revoked: z.boolean(),
+});
+
+// ============================================================================
+// Pagination Schemas (Console-specific)
+// ============================================================================
+
+export const ConsolePaginationQuerySchema = z.object({
+  limit: z.coerce.number().int().min(1).max(100).default(50),
+  offset: z.coerce.number().int().min(0).default(0),
+});
+
+export const ConsolePaginatedResponseSchema = <T extends z.ZodTypeAny>(
+  itemSchema: T
+) =>
+  z.object({
+    items: z.array(itemSchema),
+    total: z.number().int(),
+    offset: z.number().int(),
+    limit: z.number().int(),
+  });
+
+export type ConsolePaginatedResponse<T> = {
+  items: T[];
+  total: number;
+  offset: number;
+  limit: number;
+};
+
+// ============================================================================
+// Time-Series Stats Schemas
+// ============================================================================
+
+const TimeseriesIntervalSchema = z.enum(['minute', 'hour', 'day']);
+const TimeseriesRangeSchema = z.enum(['1h', '6h', '24h', '7d', '30d']);
+export const TimeseriesQuerySchema = z.object({
+  interval: TimeseriesIntervalSchema.default('hour'),
+  range: TimeseriesRangeSchema.default('24h'),
+});
+
+export const TimeseriesBucketSchema = z.object({
+  timestamp: z.string(),
+  pushCount: z.number().int(),
+  pullCount: z.number().int(),
+  errorCount: z.number().int(),
+  avgLatencyMs: z.number(),
+});
+
+export type TimeseriesBucket = z.infer<typeof TimeseriesBucketSchema>;
+
+export const TimeseriesStatsResponseSchema = z.object({
+  buckets: z.array(TimeseriesBucketSchema),
+  interval: TimeseriesIntervalSchema,
+  range: TimeseriesRangeSchema,
+});
+
+export type TimeseriesStatsResponse = z.infer<
+  typeof TimeseriesStatsResponseSchema
+>;
+
+// ============================================================================
+// Latency Percentiles Schemas
+// ============================================================================
+
+export const LatencyPercentilesSchema = z.object({
+  p50: z.number(),
+  p90: z.number(),
+  p99: z.number(),
+});
+
+export type LatencyPercentiles = z.infer<typeof LatencyPercentilesSchema>;
+
+export const LatencyStatsResponseSchema = z.object({
+  push: LatencyPercentilesSchema,
+  pull: LatencyPercentilesSchema,
+  range: TimeseriesRangeSchema,
+});
+
+export type LatencyStatsResponse = z.infer<typeof LatencyStatsResponseSchema>;
+
+export const LatencyQuerySchema = z.object({
+  range: TimeseriesRangeSchema.default('24h'),
+});
+
+// ============================================================================
+// Live Events Schemas (for WebSocket)
+// ============================================================================
+
+export const LiveEventSchema = z.object({
+  type: z.enum(['push', 'pull', 'commit', 'client_update']),
+  timestamp: z.string(),
+  data: z.record(z.string(), z.unknown()),
+});
+
+export type LiveEvent = z.infer<typeof LiveEventSchema>;

package/src/create-server.ts

@@ -0,0 +1,180 @@
+/**
+ * Simplified server factory for Hono
+ *
+ * Breaking changes from legacy createSyncRoutes:
+ * - handlers: array instead of TableRegistry
+ * - Combined sync + console routes in one call
+ */
+
+import type {
+  ServerSyncDialect,
+  ServerTableHandler,
+  SyncCoreDb,
+} from '@syncular/server';
+import type { Context } from 'hono';
+import type { UpgradeWebSocket } from 'hono/ws';
+import type { Kysely } from 'kysely';
+import {
+  type ConsoleEventEmitter,
+  createConsoleEventEmitter,
+  createConsoleRoutes,
+  createTokenAuthenticator,
+} from './console';
+import {
+  createSyncRoutes,
+  getSyncWebSocketConnectionManager,
+  type SyncAuthResult,
+  type SyncRoutesConfigWithRateLimit,
+} from './routes';
+
+export interface SyncServerOptions<DB extends SyncCoreDb = SyncCoreDb> {
+  /** 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 route configuration */
+  sync?: SyncRoutesConfigWithRateLimit;
+
+  /** WebSocket upgrader for realtime */
+  upgradeWebSocket?: UpgradeWebSocket;
+
+  /**
+   * Console configuration for dashboard/monitoring.
+   * Omit or set to false to disable console routes.
+   */
+  console?:
+    | false
+    | {
+        /** Console bearer token for authentication (required unless SYNC_CONSOLE_TOKEN is set) */
+        token?: string;
+        /** CORS origins (defaults to '*') */
+        corsOrigins?: '*' | string[];
+      };
+}
+
+export interface SyncServerResult {
+  /** Sync routes for Hono */
+  syncRoutes: ReturnType<typeof createSyncRoutes>;
+  /** Console routes for Hono (if enabled) */
+  consoleRoutes?: ReturnType<typeof createConsoleRoutes>;
+  /** Console event emitter (if console enabled) */
+  consoleEventEmitter?: ConsoleEventEmitter;
+}
+
+/**
+ * Create a simplified sync server with sync and optional console routes.
+ *
+ * @example
+ * ```typescript
+ * // With handlers
+ * const { syncRoutes } = createSyncServer({
+ *   db,
+ *   dialect,
+ *   handlers: [tasksHandler, notesHandler],
+ *   authenticate: async (c) => {
+ *     const userId = c.req.header('x-user-id');
+ *     return userId ? { actorId: userId } : null;
+ *   },
+ * });
+ *
+ * // 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;
+ *   },
+ *   console: { token: process.env.CONSOLE_TOKEN },
+ * });
+ * ```
+ */
+export function createSyncServer<DB extends SyncCoreDb = SyncCoreDb>(
+  options: SyncServerOptions<DB>
+): SyncServerResult {
+  const {
+    db,
+    dialect,
+    handlers,
+    authenticate,
+    sync,
+    upgradeWebSocket,
+    console: consoleConfig,
+  } = options;
+
+  if (handlers.length === 0) {
+    throw new Error('At least one handler must be provided');
+  }
+
+  // Create sync routes
+  const syncRoutes = createSyncRoutes({
+    db,
+    dialect,
+    handlers,
+    authenticate,
+    sync: {
+      ...sync,
+      websocket: upgradeWebSocket
+        ? {
+            enabled: true,
+            upgradeWebSocket,
+            ...(sync?.websocket?.heartbeatIntervalMs !== undefined && {
+              heartbeatIntervalMs: sync.websocket.heartbeatIntervalMs,
+            }),
+            ...(sync?.websocket?.maxConnectionsTotal !== undefined && {
+              maxConnectionsTotal: sync.websocket.maxConnectionsTotal,
+            }),
+            ...(sync?.websocket?.maxConnectionsPerClient !== undefined && {
+              maxConnectionsPerClient: sync.websocket.maxConnectionsPerClient,
+            }),
+          }
+        : { enabled: false },
+    },
+  });
+
+  // Console is opt-in; disable unless explicitly configured.
+  if (!consoleConfig) {
+    return { syncRoutes };
+  }
+
+  const consoleToken = consoleConfig.token ?? process.env.SYNC_CONSOLE_TOKEN;
+  if (!consoleToken) {
+    throw new Error(
+      'Console is enabled but no token is configured. Set `console.token` or SYNC_CONSOLE_TOKEN.'
+    );
+  }
+  const consoleEventEmitter = createConsoleEventEmitter();
+
+  const consoleRoutes = createConsoleRoutes({
+    db,
+    dialect,
+    handlers,
+    authenticate: createTokenAuthenticator(consoleToken),
+    corsOrigins: consoleConfig.corsOrigins ?? '*',
+    eventEmitter: consoleEventEmitter,
+    wsConnectionManager: getSyncWebSocketConnectionManager(syncRoutes),
+    ...(upgradeWebSocket && {
+      websocket: {
+        enabled: true,
+        upgradeWebSocket,
+      },
+    }),
+  });
+
+  return {
+    syncRoutes,
+    consoleRoutes,
+    consoleEventEmitter,
+  };
+}

package/src/index.ts

@@ -0,0 +1,42 @@
+/**
+ * @syncular/server-hono - Hono adapter for sync infrastructure
+ *
+ * This package provides Hono-specific routes for @syncular/server.
+ * Keeps @syncular/server framework-agnostic.
+ */
+
+// API Key Auth
+export * from './api-key-auth';
+
+// Blob routes
+export { type CreateBlobRoutesOptions, createBlobRoutes } from './blobs';
+
+// Console
+export * from './console';
+
+// Simplified server factory
+export {
+  createSyncServer,
+  type SyncServerOptions,
+  type SyncServerResult,
+} from './create-server';
+
+// OpenAPI utilities
+export * from './openapi';
+
+// Proxy
+export * from './proxy';
+
+// Rate limiting
+export * from './rate-limit';
+
+// Route types and factory
+export {
+  type CreateSyncRoutesOptions,
+  createSyncRoutes,
+  getSyncRealtimeUnsubscribe,
+  getSyncWebSocketConnectionManager,
+} from './routes';
+
+// WebSocket helpers for realtime sync
+export * from './ws';

package/src/openapi.ts

@@ -0,0 +1,74 @@
+/**
+ * @syncular/server-hono - OpenAPI Spec Export
+ *
+ * Provides utilities for generating and serving OpenAPI specifications.
+ */
+
+import type { Hono } from 'hono';
+import { generateSpecs, openAPIRouteHandler } from 'hono-openapi';
+
+interface OpenAPIConfig {
+  title?: string;
+  version?: string;
+  description?: string;
+  servers?: Array<{ url: string; description?: string }>;
+}
+
+/**
+ * Create an OpenAPI spec handler that can be used with Hono routes.
+ *
+ * @example
+ * ```typescript
+ * import { Hono } from 'hono';
+ * import { createSyncRoutes, createConsoleRoutes, createOpenAPIHandler } from '@syncular/server-hono';
+ *
+ * const app = new Hono();
+ * const syncRoutes = createSyncRoutes({ ... });
+ * const consoleRoutes = createConsoleRoutes({ ... });
+ *
+ * app.route('/sync', syncRoutes);
+ * app.route('/console', consoleRoutes);
+ *
+ * // Add OpenAPI spec endpoint
+ * app.get('/openapi.json', createOpenAPIHandler(app, {
+ *   title: 'Syncular API',
+ *   version: '1.0.0',
+ * }));
+ * ```
+ */
+export function createOpenAPIHandler(app: Hono, config: OpenAPIConfig = {}) {
+  return openAPIRouteHandler(app, {
+    documentation: {
+      info: {
+        title: config.title ?? 'Syncular API',
+        version: config.version ?? '1.0.0',
+        description:
+          config.description ??
+          'Sync infrastructure API for real-time data synchronization',
+      },
+      servers: config.servers,
+    },
+  });
+}
+
+/**
+ * Generate OpenAPI document from a Hono app instance.
+ * This is useful for build-time spec generation.
+ */
+export async function generateOpenAPIDocument(
+  app: Hono,
+  config: OpenAPIConfig = {}
+): Promise<unknown> {
+  return generateSpecs(app, {
+    documentation: {
+      info: {
+        title: config.title ?? 'Syncular API',
+        version: config.version ?? '1.0.0',
+        description:
+          config.description ??
+          'Sync infrastructure API for real-time data synchronization',
+      },
+      servers: config.servers,
+    },
+  });
+}