@syncular/server-hono 0.0.6-158 → 0.0.6-165

package/src/console/routes.ts

@@ -18,16 +18,18 @@
 import { logSyncEvent } from '@syncular/core';
 import type { SqlFamily, SyncCoreDb, SyncServerAuth } from '@syncular/server';
 import {
+  coerceNumber,
   compactChanges,
   computePruneWatermarkCommitSeq,
   notifyExternalDataChange,
+  parseJsonValue,
   pruneSync,
   readSyncStats,
 } from '@syncular/server';
 import type { Context } from 'hono';
 import { Hono } from 'hono';
 import { cors } from 'hono/cors';
-import { describeRoute, resolver, validator as zValidator } from 'hono-openapi';
+import { resolver, validator as zValidator } from 'hono-openapi';
 import { type Generated, type Kysely, type Selectable, sql } from 'kysely';
 import { z } from 'zod';
 import {
@@ -35,6 +37,8 @@ import {
   parseBearerToken,
   parseWebSocketAuthToken,
 } from './live-auth';
+import { describeConsoleRoute } from './route-descriptor';
+import { isBenignConsoleSchemaError } from './schema-errors';
 import {
   type ApiKeyType,
   ApiKeyTypeSchema,
@@ -171,18 +175,6 @@ export function createConsoleEventEmitter(options?: {
   };
 }
 
-function coerceNumber(value: unknown): number | null {
-  if (value === null || value === undefined) return null;
-  if (typeof value === 'number') return Number.isFinite(value) ? value : null;
-  if (typeof value === 'bigint')
-    return Number.isFinite(Number(value)) ? Number(value) : null;
-  if (typeof value === 'string') {
-    const n = Number(value);
-    return Number.isFinite(n) ? n : null;
-  }
-  return null;
-}
-
 function parseDate(value: string | null | undefined): number | null {
   if (!value) return null;
   const parsed = Date.parse(value);
@@ -198,14 +190,18 @@ function includesSearchTerm(
   return value.toLowerCase().includes(searchTerm);
 }
 
-function parseJsonValue(value: unknown): unknown {
-  if (value === null || value === undefined) return null;
-  if (typeof value !== 'string') return value;
-  try {
-    return JSON.parse(value);
-  } catch {
-    return value;
+function parseJsonRecord(value: unknown): Record<string, unknown> {
+  const parsed = parseJsonValue(value);
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return {};
   }
+  return parsed as Record<string, unknown>;
+}
+
+function parseJsonStringArray(value: unknown): string[] {
+  const parsed = parseJsonValue(value);
+  if (!Array.isArray(parsed)) return [];
+  return parsed.filter((entry): entry is string => typeof entry === 'string');
 }
 
 function parseScopesSummary(
@@ -400,6 +396,7 @@ const DEFAULT_REQUEST_EVENTS_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
 const DEFAULT_REQUEST_EVENTS_MAX_ROWS = 10_000;
 const DEFAULT_OPERATION_EVENTS_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000;
 const DEFAULT_OPERATION_EVENTS_MAX_ROWS = 5_000;
+const DEFAULT_TIMELINE_SCAN_MAX_ROWS = 10_000;
 const DEFAULT_AUTO_EVENTS_PRUNE_INTERVAL_MS = 5 * 60 * 1000;
 
 function readNonNegativeInteger(
@@ -533,6 +530,10 @@ export function createConsoleRoutes<
     options.maintenance?.operationEventsMaxRows,
     DEFAULT_OPERATION_EVENTS_MAX_ROWS
   );
+  const timelineScanMaxRows = readNonNegativeInteger(
+    options.maintenance?.timelineScanMaxRows,
+    DEFAULT_TIMELINE_SCAN_MAX_ROWS
+  );
   const autoEventsPruneIntervalMs = readNonNegativeInteger(
     options.maintenance?.autoPruneIntervalMs,
     DEFAULT_AUTO_EVENTS_PRUNE_INTERVAL_MS
@@ -545,6 +546,9 @@ export function createConsoleRoutes<
     options.dialect.ensureConsoleSchema?.(options.db) ??
     Promise.resolve()
   ).catch((err) => {
+    if (isBenignConsoleSchemaError(err)) {
+      return;
+    }
     console.error('[console] Failed to ensure console schema:', err);
     throw err;
   });
@@ -958,8 +962,7 @@ export function createConsoleRoutes<
 
   routes.get(
     '/stats',
-    describeRoute({
-      tags: ['console'],
+    describeConsoleRoute({
       summary: 'Get sync statistics',
       responses: {
         200: {
@@ -999,8 +1002,7 @@ export function createConsoleRoutes<
 
   routes.get(
     '/stats/timeseries',
-    describeRoute({
-      tags: ['console'],
+    describeConsoleRoute({
       summary: 'Get time-series statistics',
       responses: {
         200: {
@@ -1195,8 +1197,7 @@ export function createConsoleRoutes<
 
   routes.get(
     '/stats/latency',
-    describeRoute({
-      tags: ['console'],
+    describeConsoleRoute({
       summary: 'Get latency percentiles',
       responses: {
         200: {
@@ -1306,8 +1307,7 @@ export function createConsoleRoutes<
 
   routes.get(
     '/timeline',
-    describeRoute({
-      tags: ['console'],
+    describeConsoleRoute({
       summary: 'List timeline items',
       responses: {
         200: {
@@ -1350,6 +1350,9 @@ export function createConsoleRoutes<
       const items: ConsoleTimelineItem[] = [];
       const normalizedSearchTerm = search?.trim().toLowerCase() || null;
       const normalizedTable = table?.trim() || null;
+      const timelineSourceScanLimit =
+        timelineScanMaxRows > 0 ? timelineScanMaxRows : null;
+      let timelineTruncated = false;
 
       if (
         view !== 'events' &&
@@ -1386,8 +1389,29 @@ export function createConsoleRoutes<
           commitsQuery = commitsQuery.where('created_at', '<=', to);
         }
 
-        const commitRows = await commitsQuery.execute();
-        for (const row of commitRows) {
+        let commitsQueryWithOrdering = commitsQuery.orderBy(
+          'created_at',
+          'desc'
+        );
+        if (timelineSourceScanLimit !== null) {
+          commitsQueryWithOrdering = commitsQueryWithOrdering.limit(
+            timelineSourceScanLimit + 1
+          );
+        }
+
+        const commitRows = await commitsQueryWithOrdering.execute();
+        const scannedCommitRows =
+          timelineSourceScanLimit === null
+            ? commitRows
+            : commitRows.slice(0, timelineSourceScanLimit);
+        if (
+          timelineSourceScanLimit !== null &&
+          commitRows.length > timelineSourceScanLimit
+        ) {
+          timelineTruncated = true;
+        }
+
+        for (const row of scannedCommitRows) {
           const commit: ConsoleCommitListItem = {
             commitSeq: coerceNumber(row.commit_seq) ?? 0,
             actorId: row.actor_id ?? '',
@@ -1440,8 +1464,26 @@ export function createConsoleRoutes<
           eventsQuery = eventsQuery.where('created_at', '<=', to);
         }
 
-        const eventRows = await eventsQuery.execute();
-        for (const row of eventRows) {
+        let eventsQueryWithOrdering = eventsQuery.orderBy('created_at', 'desc');
+        if (timelineSourceScanLimit !== null) {
+          eventsQueryWithOrdering = eventsQueryWithOrdering.limit(
+            timelineSourceScanLimit + 1
+          );
+        }
+
+        const eventRows = await eventsQueryWithOrdering.execute();
+        const scannedEventRows =
+          timelineSourceScanLimit === null
+            ? eventRows
+            : eventRows.slice(0, timelineSourceScanLimit);
+        if (
+          timelineSourceScanLimit !== null &&
+          eventRows.length > timelineSourceScanLimit
+        ) {
+          timelineTruncated = true;
+        }
+
+        for (const row of scannedEventRows) {
           const event = mapRequestEvent(row);
 
           items.push({
@@ -1525,6 +1567,12 @@ export function createConsoleRoutes<
       };
 
       c.header('X-Total-Count', String(total));
+      if (timelineTruncated) {
+        c.header('X-Timeline-Truncated', 'true');
+        if (timelineSourceScanLimit !== null) {
+          c.header('X-Timeline-Scan-Limit', String(timelineSourceScanLimit));
+        }
+      }
       return c.json(response, 200);
     }
   );
@@ -1535,8 +1583,7 @@ export function createConsoleRoutes<
 
   routes.get(
     '/commits',
-    describeRoute({
-      tags: ['console'],
+    describeConsoleRoute({
       summary: 'List commits',
       responses: {
         200: {
@@ -1621,8 +1668,7 @@ export function createConsoleRoutes<
 
   routes.get(
     '/commits/:seq',
-    describeRoute({
-      tags: ['console'],
+    describeConsoleRoute({
       summary: 'Get commit details',
       responses: {
         200: {
@@ -1706,21 +1752,9 @@ export function createConsoleRoutes<
         table: row.table ?? '',
         rowId: row.row_id ?? '',
         op: row.op === 'delete' ? 'delete' : 'upsert',
-        rowJson:
-          typeof row.row_json === 'string'
-            ? (() => {
-                try {
-                  return JSON.parse(row.row_json);
-                } catch {
-                  return row.row_json;
-                }
-              })()
-            : row.row_json,
+        rowJson: parseJsonValue(row.row_json),
         rowVersion: coerceNumber(row.row_version),
-        scopes:
-          typeof row.scopes === 'string'
-            ? JSON.parse(row.scopes || '{}')
-            : (row.scopes ?? {}),
+        scopes: parseJsonRecord(row.scopes),
       }));
 
       const commit: ConsoleCommitDetail = {
@@ -1730,11 +1764,7 @@ export function createConsoleRoutes<
         clientCommitId: commitRow.client_commit_id ?? '',
         createdAt: commitRow.created_at ?? '',
         changeCount: coerceNumber(commitRow.change_count) ?? 0,
-        affectedTables: Array.isArray(commitRow.affected_tables)
-          ? commitRow.affected_tables
-          : typeof commitRow.affected_tables === 'string'
-            ? JSON.parse(commitRow.affected_tables || '[]')
-            : [],
+        affectedTables: parseJsonStringArray(commitRow.affected_tables),
         changes,
       };
 
@@ -1748,8 +1778,7 @@ export function createConsoleRoutes<
 
   routes.get(
     '/clients',
-    describeRoute({
-      tags: ['console'],
+    describeConsoleRoute({
       summary: 'List clients',
       responses: {
         200: {
@@ -1918,8 +1947,7 @@ export function createConsoleRoutes<
 
   routes.get(
     '/handlers',
-    describeRoute({
-      tags: ['console'],
+    describeConsoleRoute({
       summary: 'List registered handlers',
       responses: {
         200: {
@@ -1953,8 +1981,7 @@ export function createConsoleRoutes<
 
   routes.get(
     '/operations',
-    describeRoute({
-      tags: ['console'],
+    describeConsoleRoute({
       summary: 'List operation audit events',
       responses: {
         200: {
@@ -2027,8 +2054,7 @@ export function createConsoleRoutes<
 
   routes.post(
     '/prune/preview',
-    describeRoute({
-      tags: ['console'],
+    describeConsoleRoute({
       summary: 'Preview pruning',
       responses: {
         200: {
@@ -2075,8 +2101,7 @@ export function createConsoleRoutes<
 
   routes.post(
     '/prune',
-    describeRoute({
-      tags: ['console'],
+    describeConsoleRoute({
       summary: 'Trigger pruning',
       responses: {
         200: {
@@ -2131,8 +2156,7 @@ export function createConsoleRoutes<
 
   routes.post(
     '/compact',
-    describeRoute({
-      tags: ['console'],
+    describeConsoleRoute({
       summary: 'Trigger compaction',
       responses: {
         200: {
@@ -2194,8 +2218,7 @@ export function createConsoleRoutes<
 
   routes.post(
     '/notify-data-change',
-    describeRoute({
-      tags: ['console'],
+    describeConsoleRoute({
       summary: 'Notify external data change',
       description:
         'Creates a synthetic commit to force re-bootstrap for affected tables. ' +
@@ -2267,8 +2290,7 @@ export function createConsoleRoutes<
 
   routes.delete(
     '/clients/:id',
-    describeRoute({
-      tags: ['console'],
+    describeConsoleRoute({
       summary: 'Evict client',
       responses: {
         200: {
@@ -2335,8 +2357,7 @@ export function createConsoleRoutes<
 
   routes.get(
     '/events',
-    describeRoute({
-      tags: ['console'],
+    describeConsoleRoute({
       summary: 'List request events',
       responses: {
         200: {
@@ -2448,6 +2469,9 @@ export function createConsoleRoutes<
     const emitter = options.eventEmitter;
     const upgradeWebSocket = options.websocket.upgradeWebSocket;
     const heartbeatIntervalMs = options.websocket.heartbeatIntervalMs ?? 30000;
+    const maxMessageBytes = options.websocket.maxMessageBytes ?? 1024 * 1024;
+    const maxMessagesPerWindow = options.websocket.maxMessagesPerWindow ?? 120;
+    const messageRateWindowMs = options.websocket.messageRateWindowMs ?? 10000;
 
     type WebSocketLike = {
       send: (data: string) => void;
@@ -2462,6 +2486,8 @@ export function createConsoleRoutes<
         authTimeout: ReturnType<typeof setTimeout> | null;
         isAuthenticated: boolean;
         startAuthenticatedSession: (() => void) | null;
+        messageRateWindowStart: number;
+        messageRateWindowCount: number;
       }
     >();
 
@@ -2480,179 +2506,212 @@ export function createConsoleRoutes<
       wsState.delete(ws);
     };
 
-    routes.get(
-      '/events/live',
-      upgradeWebSocket(async (c) => {
-        const authHeader = c.req.header('Authorization');
-        const partitionId = c.req.query('partitionId')?.trim() || undefined;
-        const replaySince = c.req.query('since');
-        const replayLimitRaw = c.req.query('replayLimit');
-        const replayLimitNumber = replayLimitRaw
-          ? Number.parseInt(replayLimitRaw, 10)
-          : Number.NaN;
-        const replayLimit = Number.isFinite(replayLimitNumber)
-          ? Math.max(1, Math.min(500, replayLimitNumber))
-          : 100;
-        const mockContext = {
+    const liveEventsWebSocketRoute = upgradeWebSocket(async (c) => {
+      const authHeader = c.req.header('Authorization');
+      const partitionId = c.req.query('partitionId')?.trim() || undefined;
+      const replaySince = c.req.query('since');
+      const replayLimitRaw = c.req.query('replayLimit');
+      const replayLimitNumber = replayLimitRaw
+        ? Number.parseInt(replayLimitRaw, 10)
+        : Number.NaN;
+      const replayLimit = Number.isFinite(replayLimitNumber)
+        ? Math.max(1, Math.min(500, replayLimitNumber))
+        : 100;
+      const mockContext = {
+        req: {
+          header: (name: string) =>
+            name === 'Authorization' ? authHeader : undefined,
+          query: () => undefined,
+        },
+      } as unknown as Context;
+
+      const initialAuth = await options.authenticate(mockContext);
+
+      const authenticateWithBearer = async (token: string) => {
+        const trimmedToken = token.trim();
+        if (!trimmedToken) return null;
+        const authContext = {
           req: {
             header: (name: string) =>
-              name === 'Authorization' ? authHeader : undefined,
+              name === 'Authorization' ? `Bearer ${trimmedToken}` : undefined,
             query: () => undefined,
           },
         } as unknown as Context;
+        return options.authenticate(authContext);
+      };
 
-        const initialAuth = await options.authenticate(mockContext);
-
-        const authenticateWithBearer = async (token: string) => {
-          const trimmedToken = token.trim();
-          if (!trimmedToken) return null;
-          const authContext = {
-            req: {
-              header: (name: string) =>
-                name === 'Authorization' ? `Bearer ${trimmedToken}` : undefined,
-              query: () => undefined,
-            },
-          } as unknown as Context;
-          return options.authenticate(authContext);
-        };
-
-        return {
-          onOpen(_event, ws) {
-            const state: {
-              listener: ConsoleEventListener | null;
-              heartbeatInterval: ReturnType<typeof setInterval> | null;
-              authTimeout: ReturnType<typeof setTimeout> | null;
-              isAuthenticated: boolean;
-              startAuthenticatedSession: (() => void) | null;
-            } = {
-              listener: null,
-              heartbeatInterval: null,
-              authTimeout: null,
-              isAuthenticated: false,
-              startAuthenticatedSession: null,
-            };
-            wsState.set(ws, state);
-
-            const startAuthenticatedSession = () => {
-              if (state.isAuthenticated) return;
-              state.isAuthenticated = true;
-              if (state.authTimeout) {
-                clearTimeout(state.authTimeout);
-                state.authTimeout = null;
-              }
+      return {
+        onOpen(_event, ws) {
+          const state: {
+            listener: ConsoleEventListener | null;
+            heartbeatInterval: ReturnType<typeof setInterval> | null;
+            authTimeout: ReturnType<typeof setTimeout> | null;
+            isAuthenticated: boolean;
+            startAuthenticatedSession: (() => void) | null;
+            messageRateWindowStart: number;
+            messageRateWindowCount: number;
+          } = {
+            listener: null,
+            heartbeatInterval: null,
+            authTimeout: null,
+            isAuthenticated: false,
+            startAuthenticatedSession: null,
+            messageRateWindowStart: Date.now(),
+            messageRateWindowCount: 0,
+          };
+          wsState.set(ws, state);
+
+          const startAuthenticatedSession = () => {
+            if (state.isAuthenticated) return;
+            state.isAuthenticated = true;
+            if (state.authTimeout) {
+              clearTimeout(state.authTimeout);
+              state.authTimeout = null;
+            }
 
-              const listener: ConsoleEventListener = (event) => {
-                if (partitionId) {
-                  const eventPartitionId = event.data.partitionId;
-                  if (
-                    typeof eventPartitionId !== 'string' ||
-                    eventPartitionId !== partitionId
-                  ) {
-                    return;
-                  }
-                }
-                try {
-                  ws.send(JSON.stringify(event));
-                } catch {
-                  // Connection closed
-                }
-              };
-
-              emitter.addListener(listener);
-              state.listener = listener;
-
-              ws.send(
-                JSON.stringify({
-                  type: 'connected',
-                  timestamp: new Date().toISOString(),
-                })
-              );
-
-              const replayEvents = emitter.replay({
-                since: replaySince,
-                limit: replayLimit,
-                partitionId,
-              });
-              for (const replayEvent of replayEvents) {
-                try {
-                  ws.send(JSON.stringify(replayEvent));
-                } catch {
-                  // Connection closed
-                  break;
+            const listener: ConsoleEventListener = (event) => {
+              if (partitionId) {
+                const eventPartitionId = event.data.partitionId;
+                if (
+                  typeof eventPartitionId !== 'string' ||
+                  eventPartitionId !== partitionId
+                ) {
+                  return;
                 }
               }
-
-              const heartbeatInterval = setInterval(() => {
-                try {
-                  ws.send(
-                    JSON.stringify({
-                      type: 'heartbeat',
-                      timestamp: new Date().toISOString(),
-                    })
-                  );
-                } catch {
-                  clearInterval(heartbeatInterval);
-                }
-              }, heartbeatIntervalMs);
-              state.heartbeatInterval = heartbeatInterval;
+              try {
+                ws.send(JSON.stringify(event));
+              } catch {
+                // Connection closed
+              }
             };
-            state.startAuthenticatedSession = startAuthenticatedSession;
 
-            if (initialAuth) {
-              startAuthenticatedSession();
-              return;
-            }
+            emitter.addListener(listener);
+            state.listener = listener;
 
-            state.authTimeout = setTimeout(() => {
-              const current = wsState.get(ws);
-              if (!current || current.isAuthenticated) {
-                return;
+            ws.send(
+              JSON.stringify({
+                type: 'connected',
+                timestamp: new Date().toISOString(),
+              })
+            );
+
+            const replayEvents = emitter.replay({
+              since: replaySince,
+              limit: replayLimit,
+              partitionId,
+            });
+            for (const replayEvent of replayEvents) {
+              try {
+                ws.send(JSON.stringify(replayEvent));
+              } catch {
+                // Connection closed
+                break;
               }
-              closeUnauthenticatedSocket(ws);
-              cleanup(ws);
-            }, 5_000);
-          },
-          async onMessage(event, ws) {
-            const state = wsState.get(ws);
-            if (!state || state.isAuthenticated) {
-              return;
             }
 
-            if (typeof event.data !== 'string') {
-              closeUnauthenticatedSocket(ws);
-              cleanup(ws);
-              return;
-            }
+            const heartbeatInterval = setInterval(() => {
+              try {
+                ws.send(
+                  JSON.stringify({
+                    type: 'heartbeat',
+                    timestamp: new Date().toISOString(),
+                  })
+                );
+              } catch {
+                clearInterval(heartbeatInterval);
+              }
+            }, heartbeatIntervalMs);
+            state.heartbeatInterval = heartbeatInterval;
+          };
+          state.startAuthenticatedSession = startAuthenticatedSession;
 
-            const token = parseWebSocketAuthToken(event.data);
+          if (initialAuth) {
+            startAuthenticatedSession();
+            return;
+          }
 
-            if (!token) {
-              closeUnauthenticatedSocket(ws);
-              cleanup(ws);
+          state.authTimeout = setTimeout(() => {
+            const current = wsState.get(ws);
+            if (!current || current.isAuthenticated) {
               return;
             }
+            closeUnauthenticatedSocket(ws);
+            cleanup(ws);
+          }, 5_000);
+        },
+        async onMessage(event, ws) {
+          const state = wsState.get(ws);
+          if (!state) {
+            return;
+          }
 
-            const auth = await authenticateWithBearer(token);
-            const currentState = wsState.get(ws);
-            if (!currentState || currentState.isAuthenticated) {
-              return;
+          const messageBytes = measureWebSocketMessageBytes(event.data);
+          if (messageBytes > maxMessageBytes) {
+            ws.close(1009, 'message too large');
+            cleanup(ws);
+            return;
+          }
+
+          if (maxMessagesPerWindow > 0 && messageRateWindowMs > 0) {
+            const nowMs = Date.now();
+            if (nowMs - state.messageRateWindowStart >= messageRateWindowMs) {
+              state.messageRateWindowStart = nowMs;
+              state.messageRateWindowCount = 0;
             }
-            if (!auth) {
-              closeUnauthenticatedSocket(ws);
+            state.messageRateWindowCount += 1;
+            if (state.messageRateWindowCount > maxMessagesPerWindow) {
+              ws.close(1008, 'message rate exceeded');
               cleanup(ws);
               return;
             }
-            currentState.startAuthenticatedSession?.();
-          },
-          onClose(_event, ws) {
+          }
+
+          if (state.isAuthenticated) {
+            return;
+          }
+
+          if (typeof event.data !== 'string') {
+            closeUnauthenticatedSocket(ws);
             cleanup(ws);
-          },
-          onError(_event, ws) {
+            return;
+          }
+
+          const token = parseWebSocketAuthToken(event.data);
+
+          if (!token) {
+            closeUnauthenticatedSocket(ws);
             cleanup(ws);
-          },
-        };
-      })
-    );
+            return;
+          }
+
+          const auth = await authenticateWithBearer(token);
+          const currentState = wsState.get(ws);
+          if (!currentState || currentState.isAuthenticated) {
+            return;
+          }
+          if (!auth) {
+            closeUnauthenticatedSocket(ws);
+            cleanup(ws);
+            return;
+          }
+          currentState.startAuthenticatedSession?.();
+        },
+        onClose(_event, ws) {
+          cleanup(ws);
+        },
+        onError(_event, ws) {
+          cleanup(ws);
+        },
+      };
+    });
+
+    routes.get('/events/live', async (c, next) => {
+      if (!isWebSocketOriginAllowed(c, options.websocket?.allowedOrigins)) {
+        return c.json({ error: 'FORBIDDEN_ORIGIN' }, 403);
+      }
+      return liveEventsWebSocketRoute(c, next);
+    });
   }
 
   // -------------------------------------------------------------------------
@@ -2661,8 +2720,7 @@ export function createConsoleRoutes<
 
   routes.get(
     '/events/:id',
-    describeRoute({
-      tags: ['console'],
+    describeConsoleRoute({
       summary: 'Get event details',
       responses: {
         200: {
@@ -2724,8 +2782,7 @@ export function createConsoleRoutes<
 
   routes.get(
     '/events/:id/payload',
-    describeRoute({
-      tags: ['console'],
+    describeConsoleRoute({
       summary: 'Get event payload snapshot',
       responses: {
         200: {
@@ -2823,8 +2880,7 @@ export function createConsoleRoutes<
 
   routes.delete(
     '/events',
-    describeRoute({
-      tags: ['console'],
+    describeConsoleRoute({
       summary: 'Clear all events',
       responses: {
         200: {
@@ -2867,8 +2923,7 @@ export function createConsoleRoutes<
 
   routes.post(
     '/events/prune',
-    describeRoute({
-      tags: ['console'],
+    describeConsoleRoute({
       summary: 'Prune old events',
       responses: {
         200: {
@@ -2911,8 +2966,7 @@ export function createConsoleRoutes<
 
   routes.get(
     '/api-keys',
-    describeRoute({
-      tags: ['console'],
+    describeConsoleRoute({
       summary: 'List API keys',
       responses: {
         200: {
@@ -3040,8 +3094,7 @@ export function createConsoleRoutes<
 
   routes.post(
     '/api-keys',
-    describeRoute({
-      tags: ['console'],
+    describeConsoleRoute({
       summary: 'Create API key',
       responses: {
         201: {
@@ -3140,8 +3193,7 @@ export function createConsoleRoutes<
 
   routes.get(
     '/api-keys/:id',
-    describeRoute({
-      tags: ['console'],
+    describeConsoleRoute({
       summary: 'Get API key',
       responses: {
         200: {
@@ -3212,8 +3264,7 @@ export function createConsoleRoutes<
 
   routes.delete(
     '/api-keys/:id',
-    describeRoute({
-      tags: ['console'],
+    describeConsoleRoute({
       summary: 'Revoke API key',
       responses: {
         200: {
@@ -3263,8 +3314,7 @@ export function createConsoleRoutes<
 
   routes.post(
     '/api-keys/bulk-revoke',
-    describeRoute({
-      tags: ['console'],
+    describeConsoleRoute({
       summary: 'Bulk revoke API keys',
       responses: {
         200: {
@@ -3370,8 +3420,7 @@ export function createConsoleRoutes<
 
   routes.post(
     '/api-keys/:id/rotate/stage',
-    describeRoute({
-      tags: ['console'],
+    describeConsoleRoute({
       summary: 'Stage rotate API key',
       responses: {
         200: {
@@ -3478,8 +3527,7 @@ export function createConsoleRoutes<
 
   routes.post(
     '/api-keys/:id/rotate',
-    describeRoute({
-      tags: ['console'],
+    describeConsoleRoute({
       summary: 'Rotate API key',
       responses: {
         200: {
@@ -3597,8 +3645,7 @@ export function createConsoleRoutes<
 
   routes.get(
     '/storage',
-    describeRoute({
-      tags: ['console'],
+    describeConsoleRoute({
       summary: 'List storage items',
       responses: {
         200: {
@@ -3650,8 +3697,7 @@ export function createConsoleRoutes<
 
   routes.get(
     '/storage/:key{.+}/download',
-    describeRoute({
-      tags: ['console'],
+    describeConsoleRoute({
       summary: 'Download a storage item',
       responses: {
         200: { description: 'Storage item contents' },
@@ -3701,8 +3747,7 @@ export function createConsoleRoutes<
 
   routes.delete(
     '/storage/:key{.+}',
-    describeRoute({
-      tags: ['console'],
+    describeConsoleRoute({
       summary: 'Delete a storage item',
       responses: {
         200: {
@@ -3735,6 +3780,40 @@ export function createConsoleRoutes<
   return routes;
 }
 
+function isWebSocketOriginAllowed(
+  c: Context,
+  allowedOrigins?: string[] | '*'
+): boolean {
+  if (!allowedOrigins) return true;
+  if (allowedOrigins === '*') return true;
+
+  const origin = c.req.header('origin');
+  if (!origin) return false;
+
+  try {
+    const normalizedOrigin = new URL(origin).origin;
+    return allowedOrigins.includes(normalizedOrigin);
+  } catch {
+    return false;
+  }
+}
+
+function measureWebSocketMessageBytes(data: unknown): number {
+  if (typeof data === 'string') {
+    return new TextEncoder().encode(data).byteLength;
+  }
+  if (data instanceof ArrayBuffer) {
+    return data.byteLength;
+  }
+  if (ArrayBuffer.isView(data)) {
+    return data.byteLength;
+  }
+  if (typeof Blob !== 'undefined' && data instanceof Blob) {
+    return data.size;
+  }
+  return new TextEncoder().encode(String(data)).byteLength;
+}
+
 // ===========================================================================
 // API Key Utilities
 // ===========================================================================