@fitzzero/quickdraw-core 3.7.0 → 3.8.0

package/dist/server/index.d.ts

@@ -1,7 +1,7 @@
-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-DniMxkQs.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-ClgSr90l.js';
 import { Server, Socket } from 'socket.io';
 import { z } from 'zod';
-import { ACL, Logger, AccessLevel, ServiceMethodContext, ServiceMethodDefinition, AdminServiceMeta, AdminFieldConfig } from '../shared/index.js';
+import { ACL, Logger, AccessLevel, ServiceMethodContext, ServiceMethodDefinition, ServiceChannelContext, ServiceChannelDefinition, AdminServiceMeta, AdminFieldConfig } from '../shared/index.js';
 import { Router } from 'express';
 import 'http';
 
@@ -19,6 +19,7 @@ import 'http';
  * @typeParam TCreateInput - The create input type
  * @typeParam TUpdateInput - The update input type
  * @typeParam TServiceMethods - Service method definitions map
+ * @typeParam TChannels - Service channel payload map (high-frequency fire-and-forget events)
  *
  * @example
  * ```typescript
@@ -48,7 +49,9 @@ declare abstract class BaseService<TEntity extends {
 } = Record<string, {
     payload: unknown;
     response: unknown;
-}>> {
+}>, TChannels extends {
+    [K in keyof TChannels]: unknown;
+} = Record<string, unknown>> {
     readonly serviceName: string;
     protected readonly hasEntryACL: boolean;
     protected readonly defaultACL: ACL;
@@ -57,6 +60,7 @@ declare abstract class BaseService<TEntity extends {
     protected delegate: PrismaDelegate<TEntity, TCreateInput, TUpdateInput> | undefined;
     protected io: Server | null;
     private readonly publicMethods;
+    private readonly publicChannels;
     private adminMeta;
     constructor(options: BaseServiceOptions);
     /**
@@ -138,6 +142,28 @@ declare abstract class BaseService<TEntity extends {
      * ```
      */
     emitToRoom(roomName: string, eventName: string, data: unknown): void;
+    /**
+     * Emit a custom event to a room using Socket.io's volatile flag.
+     *
+     * Volatile events are dropped for clients whose connection is backpressured
+     * instead of being buffered — exactly what you want for high-frequency state
+     * that is superseded by the next emit (game snapshots, cursor positions).
+     * Never use this for events a client must not miss.
+     *
+     * Intentionally does no per-call logging: this is a hot path, typically
+     * called at tick rate (10–60Hz).
+     *
+     * @example
+     * ```typescript
+     * // In a 20Hz game loop
+     * this.emitToRoomVolatile(
+     *   this.getRoomName(worldId),
+     *   'game:snapshot',
+     *   snapshot
+     * );
+     * ```
+     */
+    emitToRoomVolatile(roomName: string, eventName: string, data: unknown): void;
     /**
      * Emit a custom event to a specific user's room.
      * Users join `user:{userId}` on connection (set up in auth middleware).
@@ -274,6 +300,58 @@ declare abstract class BaseService<TEntity extends {
      * Get all public methods for registry discovery.
      */
     getPublicMethods(): ServiceMethodDefinition<unknown, unknown>[];
+    /**
+     * Define a channel: a fire-and-forget event for high-frequency traffic
+     * (game input, cursor positions, typing indicators).
+     *
+     * Channels differ from methods:
+     * - No ack, no response — the handler returns void and errors are logged,
+     *   never sent to the client.
+     * - Exempt from the global rate limiter; each channel enforces its own
+     *   per-socket token bucket (`ratePerSecond`/`burst`). Excess messages are
+     *   silently dropped; sustained extreme abuse disconnects the socket.
+     * - Access checks are fully synchronous and in-memory: authentication is
+     *   always required; "Moderate"/"Admin" check the socket's serviceAccess;
+     *   entry-level access is expressed via `requireRoom` (the socket must
+     *   already be in that room, which was ACL-gated at subscribe time).
+     * - `schema` is required — channel payloads are untrusted input arriving
+     *   at tick rate.
+     *
+     * Routes as the Socket.io event `channel:<serviceName>:<name>`.
+     *
+     * @example
+     * ```typescript
+     * this.defineChannel(
+     *   "input",
+     *   "Read",
+     *   (payload, ctx) => this.sim.applyInput(ctx.userId, payload),
+     *   {
+     *     schema: gameInputSchema,
+     *     ratePerSecond: 30,
+     *     requireRoom: () => this.getRoomName(GLOBAL_WORLD_ID),
+     *   },
+     * );
+     * ```
+     */
+    defineChannel<K extends keyof TChannels & string>(name: K, access: AccessLevel, handler: (payload: TChannels[K], context: ServiceChannelContext) => void, options: {
+        schema: z.ZodType<TChannels[K]>;
+        /** Sustained messages/second per socket. Default: 30 */
+        ratePerSecond?: number;
+        /** Bucket capacity for bursts. Default: 2 × ratePerSecond */
+        burst?: number;
+        /** Room the socket must already be in (null result skips the check). */
+        requireRoom?: (payload: TChannels[K]) => string | null;
+    }): ServiceChannelDefinition<TChannels[K]>;
+    /**
+     * Get all channels for registry discovery.
+     */
+    getPublicChannels(): ServiceChannelDefinition<unknown>[];
+    /**
+     * Synchronous, in-memory access check for a channel message.
+     * Called by the registry on the hot path — must not touch the database.
+     * Returns false to silently drop the message.
+     */
+    checkChannelAccess(channel: ServiceChannelDefinition<unknown>, socket: QuickdrawSocket, payload: unknown): boolean;
     /**
      * Verify that all expected service methods have been defined via defineMethod().
      * Call at the end of initMethods() to catch missing implementations at boot time.
@@ -416,6 +494,7 @@ declare class ServiceRegistry implements ServiceRegistryInstance {
     private readonly logResponses;
     private connectionHandlerInstalled;
     private readonly methodRegistry;
+    private readonly channelRegistry;
     constructor(io: Server, options?: ServiceRegistryOptions);
     /**
      * Install the single connection handler that wires all registered services.
@@ -434,6 +513,20 @@ declare class ServiceRegistry implements ServiceRegistryInstance {
      * Discover and store all public methods from a service.
      */
     private discoverServiceMethods;
+    /**
+     * Discover and store all channels from a service.
+     */
+    private discoverServiceChannels;
+    /**
+     * Register a channel as a socket event listener.
+     *
+     * This is the hot path for high-frequency traffic: no ack, no async access
+     * checks, no per-message logging. Order of operations per message:
+     * token bucket → schema validation → in-memory access check → handler.
+     * Any failure silently drops the message; sustained extreme flooding
+     * disconnects the socket.
+     */
+    private registerChannelListener;
     /**
      * Register a method as a socket event listener.
      */
@@ -624,6 +717,12 @@ interface RateLimitOptions {
      * Events to exclude from rate limiting (e.g., ['ping', 'pong'])
      */
     excludeEvents?: string[];
+    /**
+     * Event-name prefixes to exclude from rate limiting.
+     * Pass `[CHANNEL_EVENT_PREFIX]` ("channel:") so channel traffic bypasses
+     * the global limiter — channels enforce their own per-socket token buckets.
+     */
+    excludePrefixes?: string[];
     /**
      * Custom key generator for grouping requests.
      * Default uses socket.id.
@@ -662,7 +761,7 @@ interface RateLimiter {
     /**
      * Configuration options.
      */
-    options: Required<Pick<RateLimitOptions, "windowMs" | "maxRequests" | "excludeEvents">>;
+    options: Required<Pick<RateLimitOptions, "windowMs" | "maxRequests" | "excludeEvents" | "excludePrefixes">>;
 }
 /**
  * Create a rate limiter instance.

package/dist/server/index.js

@@ -8,6 +8,9 @@ import * as fs from 'fs';
 import * as path from 'path';
 
 // src/shared/types.ts
+function channelEventName(serviceName, channelName) {
+  return `channel:${serviceName}:${channelName}`;
+}
 var consoleLogger = {
   info: (message, meta) => console.log(`[INFO] ${message}`, meta ?? ""),
   warn: (message, meta) => console.warn(`[WARN] ${message}`, meta ?? ""),
@@ -176,6 +179,8 @@ var BaseService = class {
   io = null;
   // Collection of public methods for registry discovery
   publicMethods = /* @__PURE__ */ new Map();
+  // Collection of channels for registry discovery
+  publicChannels = /* @__PURE__ */ new Map();
   // Admin metadata configuration (set by installAdminMethods)
   adminMeta = null;
   constructor(options) {
@@ -384,6 +389,36 @@ var BaseService = class {
     anySocket.to(roomName).emit(eventName, data);
     this.logger.debug(`Emitted ${eventName} to room ${roomName} (via socket fallback)`);
   }
+  /**
+   * Emit a custom event to a room using Socket.io's volatile flag.
+   *
+   * Volatile events are dropped for clients whose connection is backpressured
+   * instead of being buffered — exactly what you want for high-frequency state
+   * that is superseded by the next emit (game snapshots, cursor positions).
+   * Never use this for events a client must not miss.
+   *
+   * Intentionally does no per-call logging: this is a hot path, typically
+   * called at tick rate (10–60Hz).
+   *
+   * @example
+   * ```typescript
+   * // In a 20Hz game loop
+   * this.emitToRoomVolatile(
+   *   this.getRoomName(worldId),
+   *   'game:snapshot',
+   *   snapshot
+   * );
+   * ```
+   */
+  emitToRoomVolatile(roomName, eventName, data) {
+    if (this.io) {
+      this.io.to(roomName).volatile.emit(eventName, data);
+      return;
+    }
+    const anySocket = this.getAnySubscriberSocket();
+    if (!anySocket) return;
+    anySocket.to(roomName).volatile.emit(eventName, data);
+  }
   /**
    * Emit a custom event to a specific user's room.
    * Users join `user:{userId}` on connection (set up in auth middleware).
@@ -668,6 +703,78 @@ var BaseService = class {
   getPublicMethods() {
     return Array.from(this.publicMethods.values());
   }
+  // ===========================================================================
+  // Channel Definition (high-frequency, fire-and-forget events)
+  // ===========================================================================
+  /**
+   * Define a channel: a fire-and-forget event for high-frequency traffic
+   * (game input, cursor positions, typing indicators).
+   *
+   * Channels differ from methods:
+   * - No ack, no response — the handler returns void and errors are logged,
+   *   never sent to the client.
+   * - Exempt from the global rate limiter; each channel enforces its own
+   *   per-socket token bucket (`ratePerSecond`/`burst`). Excess messages are
+   *   silently dropped; sustained extreme abuse disconnects the socket.
+   * - Access checks are fully synchronous and in-memory: authentication is
+   *   always required; "Moderate"/"Admin" check the socket's serviceAccess;
+   *   entry-level access is expressed via `requireRoom` (the socket must
+   *   already be in that room, which was ACL-gated at subscribe time).
+   * - `schema` is required — channel payloads are untrusted input arriving
+   *   at tick rate.
+   *
+   * Routes as the Socket.io event `channel:<serviceName>:<name>`.
+   *
+   * @example
+   * ```typescript
+   * this.defineChannel(
+   *   "input",
+   *   "Read",
+   *   (payload, ctx) => this.sim.applyInput(ctx.userId, payload),
+   *   {
+   *     schema: gameInputSchema,
+   *     ratePerSecond: 30,
+   *     requireRoom: () => this.getRoomName(GLOBAL_WORLD_ID),
+   *   },
+   * );
+   * ```
+   */
+  defineChannel(name, access, handler, options) {
+    const ratePerSecond = options.ratePerSecond ?? 30;
+    const definition = {
+      name,
+      access,
+      handler,
+      schema: options.schema,
+      ratePerSecond,
+      burst: options.burst ?? ratePerSecond * 2,
+      requireRoom: options.requireRoom
+    };
+    this.publicChannels.set(name, definition);
+    return definition;
+  }
+  /**
+   * Get all channels for registry discovery.
+   */
+  getPublicChannels() {
+    return Array.from(this.publicChannels.values());
+  }
+  /**
+   * Synchronous, in-memory access check for a channel message.
+   * Called by the registry on the hot path — must not touch the database.
+   * Returns false to silently drop the message.
+   */
+  checkChannelAccess(channel, socket, payload) {
+    if (!socket.userId) return false;
+    if (channel.access !== "Public" && channel.access !== "Read" && !this.hasServiceAccess(socket, channel.access)) {
+      return false;
+    }
+    if (channel.requireRoom) {
+      const roomName = channel.requireRoom(payload);
+      if (roomName && !socket.rooms.has(roomName)) return false;
+    }
+    return true;
+  }
   /**
    * Verify that all expected service methods have been defined via defineMethod().
    * Call at the end of initMethods() to catch missing implementations at boot time.
@@ -994,6 +1101,8 @@ var BaseService = class {
 };
 
 // src/server/ServiceRegistry.ts
+var CHANNEL_ABUSE_WINDOW_MS = 1e4;
+var CHANNEL_ABUSE_MULTIPLIER = 100;
 var ServiceRegistry = class {
   io;
   services = /* @__PURE__ */ new Map();
@@ -1004,6 +1113,8 @@ var ServiceRegistry = class {
   connectionHandlerInstalled = false;
   // Store method metadata for deferred registration
   methodRegistry = /* @__PURE__ */ new Map();
+  // Store channel metadata for deferred registration
+  channelRegistry = /* @__PURE__ */ new Map();
   constructor(io, options) {
     this.io = io;
     this.logger = options?.logger?.child({ service: "ServiceRegistry" }) ?? consoleLogger.child({ service: "ServiceRegistry" });
@@ -1037,6 +1148,9 @@ var ServiceRegistry = class {
     for (const [eventName, { method, service }] of this.methodRegistry) {
       this.registerMethodListener(socket, eventName, method, service);
     }
+    for (const [eventName, { channel, service }] of this.channelRegistry) {
+      this.registerChannelListener(socket, eventName, channel, service);
+    }
     for (const [serviceName, service] of this.services) {
       this.registerSubscriptionListener(socket, `${serviceName}:subscribe`, service);
       this.registerBatchSubscriptionListener(socket, `${serviceName}:batchSubscribe`, service);
@@ -1053,6 +1167,7 @@ var ServiceRegistry = class {
     }
     this.logger.info(`Registered service: ${serviceName}`);
     this.discoverServiceMethods(serviceName, service);
+    this.discoverServiceChannels(serviceName, service);
     this.installConnectionHandler();
   }
   /**
@@ -1070,6 +1185,77 @@ var ServiceRegistry = class {
       });
     }
   }
+  /**
+   * Discover and store all channels from a service.
+   */
+  discoverServiceChannels(serviceName, service) {
+    const channels = service.getPublicChannels?.() ?? [];
+    for (const channel of channels) {
+      const eventName = channelEventName(serviceName, channel.name);
+      this.logger.info(
+        `Registering channel event: ${eventName} (${channel.ratePerSecond}/s, burst ${channel.burst})`
+      );
+      this.channelRegistry.set(eventName, {
+        serviceName,
+        channel,
+        service
+      });
+    }
+  }
+  /**
+   * Register a channel as a socket event listener.
+   *
+   * This is the hot path for high-frequency traffic: no ack, no async access
+   * checks, no per-message logging. Order of operations per message:
+   * token bucket → schema validation → in-memory access check → handler.
+   * Any failure silently drops the message; sustained extreme flooding
+   * disconnects the socket.
+   */
+  registerChannelListener(socket, eventName, channel, service) {
+    let tokens = channel.burst;
+    let lastRefillAt = Date.now();
+    let abuseWindowStart = lastRefillAt;
+    let droppedInWindow = 0;
+    socket.on(eventName, (payload) => {
+      const now = Date.now();
+      tokens = Math.min(
+        channel.burst,
+        tokens + (now - lastRefillAt) / 1e3 * channel.ratePerSecond
+      );
+      lastRefillAt = now;
+      if (tokens < 1) {
+        if (now - abuseWindowStart > CHANNEL_ABUSE_WINDOW_MS) {
+          abuseWindowStart = now;
+          droppedInWindow = 0;
+        }
+        droppedInWindow++;
+        if (droppedInWindow > channel.ratePerSecond * CHANNEL_ABUSE_MULTIPLIER) {
+          this.logger.warn(
+            `Disconnecting socket ${socket.id} for sustained channel flooding on ${eventName}`,
+            { userId: socket.userId, droppedInWindow }
+          );
+          socket.disconnect(true);
+        }
+        return;
+      }
+      tokens -= 1;
+      const parsed = channel.schema.safeParse(payload);
+      if (!parsed.success) return;
+      if (!service.checkChannelAccess?.(channel, socket, parsed.data)) return;
+      try {
+        channel.handler(parsed.data, {
+          userId: socket.userId,
+          socketId: socket.id,
+          serviceAccess: socket.serviceAccess ?? {}
+        });
+      } catch (error) {
+        this.logger.error(`Channel handler error for ${eventName}`, {
+          userId: socket.userId,
+          error: error instanceof Error ? error.message : "Unknown error"
+        });
+      }
+    });
+  }
   /**
    * Register a method as a socket event listener.
    */
@@ -1464,7 +1650,7 @@ async function isRedisAdapterAvailable() {
 
 // src/server/rateLimit.ts
 function createRateLimiter(options = {}) {
-  const { windowMs = 6e4, maxRequests = 100, excludeEvents = [] } = options;
+  const { windowMs = 6e4, maxRequests = 100, excludeEvents = [], excludePrefixes = [] } = options;
   const entries = /* @__PURE__ */ new Map();
   const cleanupInterval = setInterval(() => {
     const now = Date.now();
@@ -1516,7 +1702,8 @@ function createRateLimiter(options = {}) {
     options: {
       windowMs,
       maxRequests,
-      excludeEvents
+      excludeEvents,
+      excludePrefixes
     }
   };
 }
@@ -1530,13 +1717,17 @@ function applyRateLimitMiddleware(io, rateLimiter, options = {}) {
       retryAfter: rateLimiter.getResetTime(keyGenerator(socket, eventName))
     });
   });
-  const { excludeEvents } = rateLimiter.options;
+  const { excludeEvents, excludePrefixes } = rateLimiter.options;
   io.on("connection", (socket) => {
     socket.use(([eventName, ...args], next) => {
       if (excludeEvents.includes(eventName)) {
         next();
         return;
       }
+      if (excludePrefixes.some((prefix) => eventName.startsWith(prefix))) {
+        next();
+        return;
+      }
       if (eventName.startsWith("$")) {
         next();
         return;