@syncular/server 0.0.6-96 → 0.1.1

package/src/hono/proxy/routes.ts

@@ -0,0 +1,272 @@
+/**
+ * @syncular/server/hono - Proxy Routes
+ *
+ * WebSocket endpoint for database proxy.
+ */
+
+import type {
+  ProxyHandshake,
+  ProxyHandshakeAck,
+  ProxyMessage,
+  ProxyResponse,
+} from '@syncular/core';
+import { createSyncularErrorResponse, logSyncEvent } from '@syncular/core';
+import type {
+  ProxyHandlerCollection,
+  ServerSyncDialect,
+  SyncCoreDb,
+} from '@syncular/server';
+import type { Context } from 'hono';
+import { Hono } from 'hono';
+import type { UpgradeWebSocket, WSContext } from 'hono/ws';
+import type { Kysely } from 'kysely';
+import { isWebSocketOriginAllowed } from '../websocket-origin';
+import { ProxyConnectionManager } from './connection-manager';
+
+/**
+ * WeakMap for storing proxy connection manager per Hono instance.
+ */
+interface ProxyConnectionManagerHandle {
+  canAccept(): boolean;
+  getConnectionCount(): number;
+  register(ws: WSContext, handshake: ProxyHandshake): unknown;
+  handleMessage(ws: WSContext, message: ProxyMessage): Promise<ProxyResponse>;
+  unregister(ws: WSContext): Promise<void>;
+}
+
+const proxyConnectionManagerMap = new WeakMap<
+  Hono,
+  ProxyConnectionManagerHandle
+>();
+
+interface ProxyAuthResult {
+  /** Actor ID for oplog tracking */
+  actorId: string;
+}
+
+interface CreateProxyRoutesConfig<DB extends SyncCoreDb = SyncCoreDb> {
+  /** Database connection */
+  db: Kysely<DB>;
+  /** Server sync dialect */
+  dialect: ServerSyncDialect;
+  /** 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 */
+  upgradeWebSocket: UpgradeWebSocket;
+  /** Maximum concurrent connections (default: 100) */
+  maxConnections?: number;
+  /** Idle connection timeout in ms (default: 30000) */
+  idleTimeoutMs?: number;
+  /**
+   * Maximum inbound websocket message size in bytes.
+   * Default: 1 MiB.
+   */
+  maxMessageBytes?: number;
+  /**
+   * Optional list of allowed websocket origins.
+   * - undefined: allow same-origin browser upgrades and origin-less non-browser clients
+   * - '*': allow all origins
+   * - string[]: exact origin match (scheme + host + port)
+   */
+  allowedOrigins?: string[] | '*';
+}
+
+/**
+ * Create Hono routes for the proxy WebSocket endpoint.
+ *
+ * @example
+ * ```typescript
+ * import { Hono } from 'hono';
+ * import { createBunWebSocket } from 'hono/bun';
+ * import { createProxyRoutes } from '@syncular/server/hono/proxy';
+ *
+ * const { upgradeWebSocket, websocket } = createBunWebSocket();
+ *
+ * const app = new Hono();
+ *
+ * app.route('/proxy', createProxyRoutes({
+ *   db,
+ *   handlers: proxyHandlers,
+ *   authenticate: async (c) => {
+ *     // Verify admin auth
+ *     return { actorId: 'admin:123' };
+ *   },
+ *   upgradeWebSocket,
+ * }));
+ *
+ * export default { fetch: app.fetch, websocket };
+ * ```
+ */
+export function createProxyRoutes<DB extends SyncCoreDb>(
+  config: CreateProxyRoutesConfig<DB>
+): Hono {
+  const app = new Hono();
+  const maxMessageBytes = config.maxMessageBytes ?? 1024 * 1024;
+
+  const manager = new ProxyConnectionManager({
+    db: config.db,
+    dialect: config.dialect,
+    handlers: config.handlers,
+    maxConnections: config.maxConnections,
+    idleTimeoutMs: config.idleTimeoutMs,
+  });
+
+  // Store manager for external access if needed
+  proxyConnectionManagerMap.set(app, manager);
+
+  // WebSocket upgrade endpoint - using regular route since WebSocket doesn't fit OpenAPI well
+  app.get('/', async (c) => {
+    if (!isWebSocketOriginAllowed(c, config.allowedOrigins)) {
+      return c.json(createSyncularErrorResponse('proxy.forbidden_origin'), 403);
+    }
+
+    // Authenticate before upgrade
+    const auth = await config.authenticate(c);
+    if (!auth) {
+      return c.json(createSyncularErrorResponse('proxy.auth_required'), 401);
+    }
+
+    // Check connection limit
+    if (!manager.canAccept()) {
+      logSyncEvent({
+        event: 'proxy.rejected',
+        userId: auth.actorId,
+        reason: 'max_connections',
+      });
+      return c.json(createSyncularErrorResponse('proxy.connection_limit'), 429);
+    }
+
+    logSyncEvent({
+      event: 'proxy.connect',
+      userId: auth.actorId,
+    });
+
+    return config.upgradeWebSocket(c, {
+      onOpen(_evt, _ws) {
+        // Connection opened, wait for handshake message
+      },
+
+      async onMessage(evt, ws) {
+        try {
+          const messageBytes = measureWebSocketMessageBytes(evt.data);
+          if (messageBytes > maxMessageBytes) {
+            ws.send(
+              JSON.stringify({
+                type: 'error',
+                error: `Message exceeds max size (${maxMessageBytes} bytes)`,
+              })
+            );
+            ws.close(1009, 'Message too large');
+            return;
+          }
+
+          const data = decodeWebSocketData(evt.data);
+
+          const message = JSON.parse(data);
+
+          // Handle handshake
+          if (message.type === 'handshake') {
+            const handshake = message as ProxyHandshake;
+
+            // Validate that the handshake actor matches authenticated actor
+            if (handshake.actorId !== auth.actorId) {
+              const ack: ProxyHandshakeAck = {
+                type: 'handshake_ack',
+                ok: false,
+                error: 'Actor ID mismatch',
+              };
+              ws.send(JSON.stringify(ack));
+              ws.close(4001, 'Unauthorized');
+              return;
+            }
+
+            manager.register(ws, handshake);
+
+            const ack: ProxyHandshakeAck = {
+              type: 'handshake_ack',
+              ok: true,
+            };
+            ws.send(JSON.stringify(ack));
+            return;
+          }
+
+          // Handle proxy messages
+          const proxyMessage = message as ProxyMessage;
+          const response = await manager.handleMessage(ws, proxyMessage);
+          ws.send(JSON.stringify(response));
+        } catch (err) {
+          // Send error response if we can parse the message ID
+          try {
+            const parsed = JSON.parse(decodeWebSocketData(evt.data));
+            if (parsed.id) {
+              ws.send(
+                JSON.stringify({
+                  id: parsed.id,
+                  type: 'error',
+                  error: err instanceof Error ? err.message : 'Unknown error',
+                })
+              );
+            }
+          } catch {
+            // Ignore parse errors
+          }
+        }
+      },
+
+      async onClose(_evt, ws) {
+        await manager.unregister(ws);
+        logSyncEvent({
+          event: 'proxy.disconnect',
+          userId: auth.actorId,
+        });
+      },
+
+      async onError(_evt, ws) {
+        await manager.unregister(ws);
+        logSyncEvent({
+          event: 'proxy.error',
+          userId: auth.actorId,
+        });
+      },
+    });
+  });
+
+  return app;
+}
+
+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;
+}
+
+function decodeWebSocketData(data: unknown): string {
+  if (typeof data === 'string') return data;
+  if (data instanceof ArrayBuffer) return new TextDecoder().decode(data);
+  if (ArrayBuffer.isView(data)) {
+    const view = data as Uint8Array;
+    return new TextDecoder().decode(view);
+  }
+  return String(data);
+}
+
+/**
+ * Get the ProxyConnectionManager from a proxy routes instance.
+ */
+export function getProxyConnectionManager(
+  routes: Hono
+): ProxyConnectionManagerHandle | undefined {
+  return proxyConnectionManagerMap.get(routes);
+}

package/src/hono/rate-limit.ts

@@ -0,0 +1,319 @@
+/**
+ * @syncular/server/hono - Rate limiting middleware for sync endpoints
+ *
+ * Provides per-user rate limiting to prevent DoS attacks and excessive
+ * server load from misbehaving clients.
+ */
+
+import { createSyncularErrorResponse, logSyncEvent } from '@syncular/core';
+import type { Context, MiddlewareHandler } from 'hono';
+
+/**
+ * Rate limit configuration
+ */
+export interface RateLimitConfig {
+  /**
+   * Maximum requests per window (default: 60)
+   */
+  maxRequests: number;
+
+  /**
+   * Time window in milliseconds (default: 60000 = 1 minute)
+   */
+  windowMs: number;
+
+  /**
+   * Function to extract the rate limit key from a request.
+   * Typically returns userId, deviceId, or IP address.
+   * Return null to skip rate limiting for this request.
+   */
+  keyGenerator: (c: Context) => string | null | Promise<string | null>;
+
+  /**
+   * Whether to include rate limit headers in responses (default: true)
+   */
+  includeHeaders?: boolean;
+
+  /**
+   * Custom handler for rate-limited requests (optional)
+   * If not provided, returns a 429 JSON response
+   */
+  onRateLimited?: (
+    c: Context,
+    retryAfterMs: number
+  ) => Response | Promise<Response>;
+
+  /**
+   * Whether to skip rate limiting in test environments (default: false)
+   */
+  skipInTest?: boolean;
+}
+
+/**
+ * Default rate limit configuration
+ */
+const DEFAULT_RATE_LIMIT_CONFIG: Omit<RateLimitConfig, 'keyGenerator'> = {
+  maxRequests: 60,
+  windowMs: 60_000,
+  includeHeaders: true,
+  skipInTest: false,
+};
+
+/**
+ * Rate limit entry for tracking request counts
+ */
+interface RateLimitEntry {
+  /** Request count in current window */
+  count: number;
+  /** Window start timestamp */
+  windowStart: number;
+}
+
+/**
+ * In-memory rate limiter store
+ *
+ * Note: This is suitable for single-instance deployments.
+ * For distributed deployments, use Redis or similar.
+ */
+class RateLimitStore {
+  private entries = new Map<string, RateLimitEntry>();
+  private cleanupInterval: ReturnType<typeof setInterval> | null = null;
+
+  constructor(private windowMs: number) {
+    // Clean up expired entries periodically
+    this.cleanupInterval = setInterval(
+      () => this.cleanup(),
+      Math.max(windowMs, 60_000)
+    );
+  }
+
+  /**
+   * Check and increment the rate limit counter for a key.
+   *
+   * @param key - Rate limit key (e.g., userId)
+   * @param maxRequests - Maximum requests allowed
+   * @returns Rate limit check result
+   */
+  check(
+    key: string,
+    maxRequests: number
+  ): {
+    allowed: boolean;
+    current: number;
+    remaining: number;
+    resetAt: number;
+  } {
+    const now = Date.now();
+    let entry = this.entries.get(key);
+
+    // Check if window has expired
+    if (!entry || now - entry.windowStart >= this.windowMs) {
+      entry = { count: 0, windowStart: now };
+      this.entries.set(key, entry);
+    }
+
+    const resetAt = entry.windowStart + this.windowMs;
+    const allowed = entry.count < maxRequests;
+
+    if (allowed) {
+      entry.count++;
+    }
+
+    return {
+      allowed,
+      current: entry.count,
+      remaining: Math.max(0, maxRequests - entry.count),
+      resetAt,
+    };
+  }
+
+  /**
+   * Clean up expired entries
+   */
+  cleanup(): void {
+    const now = Date.now();
+    for (const [key, entry] of this.entries) {
+      if (now - entry.windowStart >= this.windowMs) {
+        this.entries.delete(key);
+      }
+    }
+  }
+
+  /**
+   * Stop the cleanup interval
+   */
+  stop(): void {
+    if (this.cleanupInterval) {
+      clearInterval(this.cleanupInterval);
+      this.cleanupInterval = null;
+    }
+  }
+
+  /**
+   * Clear all entries (for testing)
+   */
+  clear(): void {
+    this.entries.clear();
+  }
+
+  /**
+   * Get current entry count (for monitoring)
+   */
+  get size(): number {
+    return this.entries.size;
+  }
+}
+
+// Track created stores so tests can reset state deterministically.
+const activeStores = new Set<RateLimitStore>();
+
+/**
+ * Reset the global store (for testing)
+ */
+export function resetRateLimitStore(): void {
+  for (const store of activeStores) {
+    store.stop();
+  }
+  activeStores.clear();
+}
+
+/**
+ * Create a rate limiting middleware for Hono.
+ *
+ * @example
+ * ```typescript
+ * import { createRateLimiter } from '@syncular/server/hono';
+ *
+ * const rateLimiter = createRateLimiter({
+ *   maxRequests: 60,
+ *   windowMs: 60_000,
+ *   keyGenerator: async (c) => {
+ *     const auth = await authenticate(c);
+ *     return auth?.userId ?? null;
+ *   },
+ * });
+ *
+ * app.use('/sync/*', rateLimiter);
+ * ```
+ */
+export function createRateLimiter(
+  config: Partial<RateLimitConfig> & Pick<RateLimitConfig, 'keyGenerator'>
+): MiddlewareHandler {
+  const {
+    maxRequests = DEFAULT_RATE_LIMIT_CONFIG.maxRequests,
+    windowMs = DEFAULT_RATE_LIMIT_CONFIG.windowMs,
+    keyGenerator,
+    includeHeaders = DEFAULT_RATE_LIMIT_CONFIG.includeHeaders,
+    onRateLimited,
+    skipInTest = DEFAULT_RATE_LIMIT_CONFIG.skipInTest,
+  } = config;
+
+  const store = new RateLimitStore(windowMs);
+  activeStores.add(store);
+
+  return async (c, next) => {
+    // Skip in test environment if configured
+    if (skipInTest && process.env.NODE_ENV === 'test') {
+      return next();
+    }
+
+    // Get the rate limit key
+    const key = await keyGenerator(c);
+    if (key === null) {
+      // Skip rate limiting for this request
+      return next();
+    }
+
+    const result = store.check(key, maxRequests);
+
+    // Add rate limit headers if configured
+    if (includeHeaders) {
+      c.header('X-RateLimit-Limit', String(maxRequests));
+      c.header('X-RateLimit-Remaining', String(result.remaining));
+      c.header('X-RateLimit-Reset', String(Math.ceil(result.resetAt / 1000)));
+    }
+
+    if (!result.allowed) {
+      const retryAfterMs = result.resetAt - Date.now();
+      const retryAfterSec = Math.ceil(retryAfterMs / 1000);
+
+      // Log rate limit event
+      logSyncEvent({
+        event: 'sync.rate_limit',
+        key,
+        current: result.current,
+        maxRequests,
+        retryAfterMs,
+      });
+
+      // Add Retry-After header
+      c.header('Retry-After', String(retryAfterSec));
+
+      // Use custom handler or default response
+      if (onRateLimited) {
+        return onRateLimited(c, retryAfterMs);
+      }
+
+      return c.json(
+        createSyncularErrorResponse('sync.rate_limited', {
+          message: 'Too many requests. Please try again later.',
+          details: { retryAfterMs, retryAfterSec },
+        }),
+        429
+      );
+    }
+
+    return next();
+  };
+}
+
+/**
+ * Create a rate limiter that uses userId from auth context.
+ *
+ * This is a convenience function for the common case of rate limiting
+ * by authenticated user.
+ *
+ * @example
+ * ```typescript
+ * const syncRoutes = createSyncRoutes({
+ *   db,
+ *   handlers: [tasksHandler],
+ *   authenticate,
+ *   sync: {
+ *     rateLimit: {
+ *       pull: { maxRequests: 120, windowMs: 60_000 },
+ *       push: { maxRequests: 60, windowMs: 60_000 },
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export interface SyncRateLimitConfig {
+  /**
+   * Rate limit config for pull requests.
+   * Set to false to disable rate limiting for pulls.
+   */
+  pull?: Omit<RateLimitConfig, 'keyGenerator'> | false;
+
+  /**
+   * Rate limit config for push requests.
+   * Set to false to disable rate limiting for pushes.
+   */
+  push?: Omit<RateLimitConfig, 'keyGenerator'> | false;
+}
+
+/**
+ * Default sync rate limit configuration
+ */
+export const DEFAULT_SYNC_RATE_LIMITS: SyncRateLimitConfig = {
+  pull: {
+    maxRequests: 120, // 2 requests per second average
+    windowMs: 60_000,
+    includeHeaders: true,
+  },
+  push: {
+    maxRequests: 60, // 1 request per second average
+    windowMs: 60_000,
+    includeHeaders: true,
+  },
+};