@syncular/server 0.1.2 → 0.2.0

package/src/hono/proxy/routes.ts

@@ -1,272 +0,0 @@
-/**
- * @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

@@ -1,319 +0,0 @@
-/**
- * @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,
-  },
-};