@fitzzero/quickdraw-core 0.1.0 → 1.0.0

package/dist/server/index.d.ts

@@ -1,7 +1,7 @@
-import { a as QuickdrawSocket, P as PrismaDelegate, b as BaseServiceOptions, I as InstallAdminMethodsOptions, S as ServiceRegistryInstance, B as BaseServiceInstance, c as QuickdrawServerOptions, Q as QuickdrawServerResult } from '../types-OhRxDBID.js';
+import { a as QuickdrawSocket, P as PrismaDelegate, b as BaseServiceOptions, I as InstallAdminMethodsOptions, A as AdminListPayload, c as AdminListResponse, d as AdminSetACLPayload, e as AdminSubscribersResponse, S as ServiceRegistryInstance, B as BaseServiceInstance, f as QuickdrawServerOptions, Q as QuickdrawServerResult } from '../types-CDhCEpTU.js';
+import { Server, Socket } from 'socket.io';
 import { z } from 'zod';
 import { ACL, Logger, AccessLevel, ServiceMethodContext, ServiceMethodDefinition } from '../shared/index.js';
-import { Server } from 'socket.io';
 import 'http';
 
 /**
@@ -52,6 +52,7 @@ declare abstract class BaseService<TEntity extends {
     protected readonly logger: Logger;
     protected readonly subscribers: Map<string, Set<QuickdrawSocket>>;
     protected delegate: PrismaDelegate<TEntity, TCreateInput, TUpdateInput> | undefined;
+    protected io: Server | null;
     private readonly publicMethods;
     constructor(options: BaseServiceOptions);
     /**
@@ -59,13 +60,24 @@ declare abstract class BaseService<TEntity extends {
      * Must be called in the constructor of derived classes.
      */
     protected setDelegate(delegate: PrismaDelegate<TEntity, TCreateInput, TUpdateInput>): void;
+    /**
+     * Set the Socket.io server instance for room-based broadcasts.
+     * Called automatically by ServiceRegistry during registration.
+     */
+    setIo(io: Server): void;
     /**
      * Get the delegate, throwing if not set.
      */
     protected getDelegate(): PrismaDelegate<TEntity, TCreateInput, TUpdateInput>;
+    /**
+     * Get the Socket.io room name for an entry.
+     * Used for room-based broadcasting across services.
+     */
+    getRoomName(entryId: string): string;
     /**
      * Subscribe a socket to an entity's updates.
      * Returns the current entity data if access is granted, null otherwise.
+     * Also joins the socket to the entity's Socket.io room for cross-service events.
      */
     subscribe(entryId: string, socket: QuickdrawSocket, requiredLevel?: AccessLevel): Promise<TEntity | null>;
     /**
@@ -76,8 +88,33 @@ declare abstract class BaseService<TEntity extends {
      * Remove a socket from all subscriptions (called on disconnect).
      */
     unsubscribeSocket(socket: QuickdrawSocket): void;
+    /**
+     * Emit a custom event to all subscribers of an entry via Socket.io rooms.
+     * This is useful for cross-service events (e.g., message service notifying chat subscribers).
+     *
+     * @param roomName - The Socket.io room name (use getRoomName for service rooms)
+     * @param eventName - The event name to emit
+     * @param data - The data to emit
+     *
+     * @example
+     * ```typescript
+     * // In MessageService, notify chat subscribers of a new message
+     * this.emitToRoom(
+     *   `chatService:${message.chatId}`,
+     *   'chat:message',
+     *   messageDTO
+     * );
+     * ```
+     */
+    protected emitToRoom(roomName: string, eventName: string, data: unknown): void;
+    /**
+     * Get any active socket for room-based operations.
+     */
+    private getAnySubscriberSocket;
     /**
      * Emit an update to all subscribers of an entity.
+     * Uses tier-based pre-filtering: computes filtered versions once,
+     * then selects the appropriate version per subscriber.
      */
     protected emitUpdate(entryId: string, data: Partial<TEntity>): void;
     /**
@@ -107,6 +144,56 @@ declare abstract class BaseService<TEntity extends {
      * Throws if access is denied.
      */
     ensureAccessForMethod(requiredLevel: AccessLevel, socket: QuickdrawSocket, entryId?: string): Promise<void>;
+    /**
+     * Get the list of fields that should be stripped for non-elevated subscribers.
+     * Override in derived classes to customize which fields are protected.
+     *
+     * @example
+     * ```typescript
+     * protected override getProtectedFields(): (keyof User)[] {
+     *   return ['email', 'serviceAccess', 'discordId'];
+     * }
+     * ```
+     */
+    protected getProtectedFields(): (keyof TEntity)[];
+    /**
+     * Check if a socket has elevated access to an entity (receives full data).
+     * Default: owner (socket.userId === entryId) or service-level Admin.
+     * Override in derived classes for custom logic.
+     *
+     * @example
+     * ```typescript
+     * protected override hasElevatedAccess(socket: QuickdrawSocket, entryId: string): boolean {
+     *   // Friends can see more data
+     *   return super.hasElevatedAccess(socket, entryId) ||
+     *          this.isFriend(socket.userId, entryId);
+     * }
+     * ```
+     */
+    protected hasElevatedAccess(socket: QuickdrawSocket, entryId: string): boolean;
+    /**
+     * Strip protected fields from an entity.
+     * Used internally by filterEntityForSubscriber.
+     */
+    protected stripProtectedFields<T extends Partial<TEntity>>(entity: T): T;
+    /**
+     * Filter entity data based on subscriber's access level.
+     * Override for complex filtering logic (e.g., multiple tiers).
+     *
+     * @example
+     * ```typescript
+     * protected override filterEntityForSubscriber(
+     *   entity: Partial<TEntity>,
+     *   socket: QuickdrawSocket,
+     *   entryId: string
+     * ): Partial<TEntity> {
+     *   if (this.hasElevatedAccess(socket, entryId)) return entity;
+     *   if (this.isFriend(socket.userId, entryId)) return this.stripForFriends(entity);
+     *   return this.stripProtectedFields(entity);
+     * }
+     * ```
+     */
+    protected filterEntityForSubscriber(entity: Partial<TEntity>, socket: QuickdrawSocket, entryId: string): Partial<TEntity>;
     /**
      * Find an entity by ID.
      */
@@ -139,8 +226,72 @@ declare abstract class BaseService<TEntity extends {
     /**
      * Install standard admin CRUD methods.
      * Call this in derived class constructor to expose admin endpoints.
+     *
+     * @example
+     * ```typescript
+     * this.installAdminMethods({
+     *   expose: { list: true, get: true, create: true, update: true, delete: true },
+     *   access: {
+     *     list: "Admin",
+     *     get: "Admin",
+     *     create: "Admin",
+     *     update: "Admin",
+     *     delete: "Admin",
+     *     setEntryACL: "Admin",
+     *     getSubscribers: "Admin",
+     *     reemit: "Admin",
+     *     unsubscribeAll: "Admin",
+     *   },
+     * });
+     * ```
+     */
+    protected installAdminMethods(options: InstallAdminMethodsOptions): void;
+    /**
+     * Admin method: List entities with pagination and filters.
+     */
+    protected adminList(payload: AdminListPayload): Promise<AdminListResponse<TEntity>>;
+    /**
+     * Admin method: Get a single entity by ID.
+     */
+    protected adminGet(id: string): Promise<TEntity | null>;
+    /**
+     * Admin method: Create an entity.
+     */
+    protected adminCreate(data: TCreateInput): Promise<TEntity>;
+    /**
+     * Admin method: Update an entity.
+     */
+    protected adminUpdate(id: string, data: TUpdateInput): Promise<TEntity | null>;
+    /**
+     * Admin method: Delete an entity.
+     */
+    protected adminDelete(id: string): Promise<{
+        success: boolean;
+        id: string;
+    }>;
+    /**
+     * Admin method: Set entry-level ACL.
+     */
+    protected adminSetEntryACL(payload: AdminSetACLPayload): Promise<TEntity | null>;
+    /**
+     * Admin method: Get active subscribers for an entity.
+     */
+    protected adminGetSubscribers(entryId: string): AdminSubscribersResponse;
+    /**
+     * Admin method: Re-emit current entity state to all subscribers.
+     * Useful when you've made direct DB changes or need to force-refresh clients.
+     */
+    protected adminReemit(entryId: string): Promise<{
+        success: boolean;
+        subscriberCount: number;
+    }>;
+    /**
+     * Admin method: Unsubscribe all sockets from an entity.
      */
-    protected installAdminMethods(_options: InstallAdminMethodsOptions): void;
+    protected adminUnsubscribeAll(entryId: string): {
+        success: boolean;
+        unsubscribedCount: number;
+    };
     /**
      * Fields that should never be exposed or editable via admin methods.
      */
@@ -155,6 +306,7 @@ declare abstract class BaseService<TEntity extends {
  * - Wires methods to Socket.io events with standardized naming
  * - Handles subscription lifecycle
  * - Provides consistent error handling and logging
+ * - Uses a single connection handler for all services (memory efficient)
  *
  * @example
  * ```typescript
@@ -167,15 +319,26 @@ declare class ServiceRegistry implements ServiceRegistryInstance {
     private readonly io;
     private readonly services;
     private readonly logger;
+    private connectionHandlerInstalled;
+    private readonly methodRegistry;
     constructor(io: Server, options?: {
         logger?: Logger;
     });
+    /**
+     * Install the single connection handler that wires all registered services.
+     * This is called lazily on first service registration.
+     */
+    private installConnectionHandler;
+    /**
+     * Set up all event listeners for a newly connected socket.
+     */
+    private setupSocketListeners;
     /**
      * Register a service and auto-discover its public methods.
      */
     registerService(serviceName: string, service: BaseServiceInstance): void;
     /**
-     * Discover and register all public methods from a service.
+     * Discover and store all public methods from a service.
      */
     private discoverServiceMethods;
     /**
@@ -227,6 +390,255 @@ declare class ServiceRegistry implements ServiceRegistryInstance {
  */
 declare function createQuickdrawServer(options: QuickdrawServerOptions): QuickdrawServerResult;
 
+/**
+ * Redis adapter utilities for horizontal scaling.
+ *
+ * This module provides optional Redis integration for Socket.io
+ * to enable running multiple server instances.
+ *
+ * @example
+ * ```typescript
+ * import { createQuickdrawServer } from '@fitzzero/quickdraw-core/server';
+ * import { setupRedisAdapter } from '@fitzzero/quickdraw-core/server';
+ *
+ * const { io } = createQuickdrawServer({ ... });
+ *
+ * // Enable Redis for horizontal scaling
+ * await setupRedisAdapter(io, {
+ *   host: process.env.REDIS_HOST ?? 'localhost',
+ *   port: parseInt(process.env.REDIS_PORT ?? '6379'),
+ * });
+ * ```
+ */
+
+/**
+ * Redis adapter configuration options.
+ */
+interface RedisAdapterOptions {
+    /**
+     * Redis host (default: 'localhost')
+     */
+    host?: string;
+    /**
+     * Redis port (default: 6379)
+     */
+    port?: number;
+    /**
+     * Redis password (optional)
+     */
+    password?: string;
+    /**
+     * Redis database number (default: 0)
+     */
+    db?: number;
+    /**
+     * Key prefix for Socket.io adapter (default: 'socket.io')
+     */
+    keyPrefix?: string;
+    /**
+     * Logger instance
+     */
+    logger?: Logger;
+}
+/**
+ * Result of Redis adapter setup.
+ */
+interface RedisAdapterResult {
+    /**
+     * Whether the adapter was successfully set up.
+     */
+    success: boolean;
+    /**
+     * Cleanup function to disconnect from Redis.
+     */
+    cleanup: () => Promise<void>;
+}
+/**
+ * Set up Redis adapter for Socket.io horizontal scaling.
+ *
+ * This function dynamically imports the @socket.io/redis-adapter package
+ * to avoid requiring it as a hard dependency.
+ *
+ * @param io - Socket.io server instance
+ * @param options - Redis configuration options
+ * @returns Promise resolving to setup result
+ *
+ * @example
+ * ```typescript
+ * const { io } = createQuickdrawServer({ ... });
+ *
+ * const { success, cleanup } = await setupRedisAdapter(io, {
+ *   host: 'redis.example.com',
+ *   port: 6379,
+ *   password: process.env.REDIS_PASSWORD,
+ * });
+ *
+ * if (success) {
+ *   console.log('Redis adapter enabled - horizontal scaling ready');
+ * }
+ *
+ * // On shutdown:
+ * await cleanup();
+ * ```
+ */
+declare function setupRedisAdapter(io: Server, options?: RedisAdapterOptions): Promise<RedisAdapterResult>;
+/**
+ * Check if Redis adapter packages are available.
+ *
+ * @returns Promise resolving to true if packages are installed
+ */
+declare function isRedisAdapterAvailable(): Promise<boolean>;
+
+/**
+ * Rate limiting middleware for Socket.io events.
+ *
+ * Provides per-socket rate limiting to prevent abuse and ensure
+ * fair resource usage across clients.
+ *
+ * @example
+ * ```typescript
+ * import { createRateLimiter, applyRateLimitMiddleware } from '@fitzzero/quickdraw-core/server';
+ *
+ * // Create a rate limiter
+ * const rateLimiter = createRateLimiter({
+ *   windowMs: 60000, // 1 minute window
+ *   maxRequests: 100, // 100 requests per window
+ * });
+ *
+ * // Apply to Socket.io server
+ * applyRateLimitMiddleware(io, rateLimiter);
+ * ```
+ */
+
+/**
+ * Rate limiter configuration options.
+ */
+interface RateLimitOptions {
+    /**
+     * Time window in milliseconds (default: 60000 = 1 minute)
+     */
+    windowMs?: number;
+    /**
+     * Maximum number of requests per window (default: 100)
+     */
+    maxRequests?: number;
+    /**
+     * Events to exclude from rate limiting (e.g., ['ping', 'pong'])
+     */
+    excludeEvents?: string[];
+    /**
+     * Custom key generator for grouping requests.
+     * Default uses socket.id.
+     */
+    keyGenerator?: (socket: Socket, eventName: string) => string;
+    /**
+     * Callback when rate limit is exceeded.
+     */
+    onRateLimitExceeded?: (socket: Socket, eventName: string) => void;
+    /**
+     * Logger instance
+     */
+    logger?: Logger;
+}
+/**
+ * Rate limiter instance.
+ */
+interface RateLimiter {
+    /**
+     * Check if a request should be allowed.
+     * Returns true if allowed, false if rate limited.
+     */
+    check: (key: string) => boolean;
+    /**
+     * Get remaining requests for a key.
+     */
+    getRemaining: (key: string) => number;
+    /**
+     * Get time until rate limit resets for a key.
+     */
+    getResetTime: (key: string) => number;
+    /**
+     * Clear all rate limit entries (useful for testing).
+     */
+    clear: () => void;
+    /**
+     * Configuration options.
+     */
+    options: Required<Pick<RateLimitOptions, "windowMs" | "maxRequests" | "excludeEvents">>;
+}
+/**
+ * Create a rate limiter instance.
+ *
+ * @param options - Rate limiter configuration
+ * @returns Rate limiter instance
+ *
+ * @example
+ * ```typescript
+ * const limiter = createRateLimiter({
+ *   windowMs: 60000,
+ *   maxRequests: 100,
+ * });
+ *
+ * if (limiter.check('user-123')) {
+ *   // Request allowed
+ * } else {
+ *   // Rate limited
+ * }
+ * ```
+ */
+declare function createRateLimiter(options?: RateLimitOptions): RateLimiter;
+/**
+ * Apply rate limiting middleware to a Socket.io server.
+ *
+ * This intercepts all incoming events and checks them against
+ * the rate limiter before allowing them to proceed.
+ *
+ * @param io - Socket.io server instance
+ * @param rateLimiter - Rate limiter instance
+ * @param options - Additional options
+ *
+ * @example
+ * ```typescript
+ * const rateLimiter = createRateLimiter({ maxRequests: 100 });
+ *
+ * applyRateLimitMiddleware(io, rateLimiter, {
+ *   keyGenerator: (socket) => socket.userId ?? socket.id,
+ *   onRateLimitExceeded: (socket, event) => {
+ *     socket.emit('error', { code: 'RATE_LIMITED', event });
+ *   },
+ * });
+ * ```
+ */
+declare function applyRateLimitMiddleware(io: Server, rateLimiter: RateLimiter, options?: Pick<RateLimitOptions, "keyGenerator" | "onRateLimitExceeded" | "logger">): void;
+/**
+ * Create a tiered rate limiter with different limits for different event types.
+ *
+ * @param tiers - Map of event patterns to rate limit options
+ * @param defaultOptions - Default options for events not matching any tier
+ * @returns Rate limiter that applies different limits based on event name
+ *
+ * @example
+ * ```typescript
+ * const tieredLimiter = createTieredRateLimiter(
+ *   {
+ *     // Strict limits for write operations
+ *     'create*': { maxRequests: 10, windowMs: 60000 },
+ *     'update*': { maxRequests: 20, windowMs: 60000 },
+ *     'delete*': { maxRequests: 5, windowMs: 60000 },
+ *     // Generous limits for reads
+ *     'list*': { maxRequests: 200, windowMs: 60000 },
+ *     'get*': { maxRequests: 200, windowMs: 60000 },
+ *   },
+ *   { maxRequests: 100, windowMs: 60000 } // Default
+ * );
+ * ```
+ */
+declare function createTieredRateLimiter(tiers: Record<string, RateLimitOptions>, defaultOptions?: RateLimitOptions): {
+    check: (key: string, eventName: string) => boolean;
+    getRemaining: (key: string, eventName: string) => number;
+    clear: () => void;
+};
+
 interface JWTPayload {
     userId: string;
     email?: string;
@@ -333,4 +745,4 @@ interface GoogleUser {
  */
 declare const googleProvider: OAuthProvider<GoogleUser>;
 
-export { BaseService, BaseServiceInstance, BaseServiceOptions, type DiscordUser, type GoogleUser, InstallAdminMethodsOptions, type JWTPayload, type OAuthConfig, type OAuthProvider, type OAuthTokenResponse, PrismaDelegate, QuickdrawServerOptions, QuickdrawServerResult, QuickdrawSocket, ServiceRegistry, ServiceRegistryInstance, createJWT, createOAuthURL, createQuickdrawServer, discordProvider, exchangeOAuthCode, googleProvider, verifyJWT };
+export { AdminListPayload, AdminListResponse, AdminSetACLPayload, AdminSubscribersResponse, BaseService, BaseServiceInstance, BaseServiceOptions, type DiscordUser, type GoogleUser, InstallAdminMethodsOptions, type JWTPayload, type OAuthConfig, type OAuthProvider, type OAuthTokenResponse, PrismaDelegate, QuickdrawServerOptions, QuickdrawServerResult, QuickdrawSocket, type RateLimitOptions, type RateLimiter, type RedisAdapterOptions, type RedisAdapterResult, ServiceRegistry, ServiceRegistryInstance, applyRateLimitMiddleware, createJWT, createOAuthURL, createQuickdrawServer, createRateLimiter, createTieredRateLimiter, discordProvider, exchangeOAuthCode, googleProvider, isRedisAdapterAvailable, setupRedisAdapter, verifyJWT };