@fitzzero/quickdraw-core 3.7.0 → 3.8.0

package/README.md

@@ -180,6 +180,111 @@ function TaskList({ projectId }: { projectId: string }) {
 
 Rapid-fire events within 100ms are debounced into a single refetch.
 
+### Channels (High-Frequency Traffic)
+
+Methods are request/response: ack'd, ACL-checked against the database, and
+counted by the global rate limiter. **Channels** are their fire-and-forget
+counterpart for traffic where per-message overhead matters and losing a
+message is fine — game input, cursor positions, typing indicators, telemetry.
+
+Channel messages have no ack and no response. Each message is validated
+(zod schema required), access-checked entirely in memory (zero DB reads on
+the hot path), and governed by a per-socket, per-channel token bucket instead
+of the global limiter. Excess messages are silently dropped; sustained extreme
+flooding disconnects the socket.
+
+**Server** — define channels next to methods; broadcast tick data back with
+`emitToRoomVolatile` (backpressured clients drop frames instead of queueing):
+
+```typescript
+type GameServiceChannels = ServiceChannelMap<{
+  input: { seq: number; dx: number; dy: number; boost: boolean };
+}>;
+
+class GameService extends BaseService<
+  GameWorld,
+  Prisma.GameWorldCreateInput,
+  Prisma.GameWorldUpdateInput,
+  GameServiceMethods,
+  GameServiceChannels // 5th type param
+> {
+  constructor(prisma: PrismaClient) {
+    super({ serviceName: "gameService" });
+    this.setDelegate(prisma.gameWorld);
+
+    this.defineChannel(
+      "input",
+      "Read",
+      (payload, ctx) => this.sim.applyInput(ctx.userId, payload),
+      {
+        schema: gameInputSchema,
+        ratePerSecond: 30, // default 30
+        burst: 60, // default 2x rate
+        requireRoom: () => this.getRoomName(WORLD_ID), // entry-level gate
+      },
+    );
+  }
+
+  // In a 20Hz tick loop:
+  broadcastSnapshot(snapshot: WorldSnapshot): void {
+    this.emitToRoomVolatile(this.getRoomName(WORLD_ID), "game:snapshot", snapshot);
+  }
+}
+```
+
+Exempt channel traffic from the global rate limiter (channels self-limit):
+
+```typescript
+import { CHANNEL_EVENT_PREFIX } from "@fitzzero/quickdraw-core";
+
+const rateLimiter = createRateLimiter({
+  maxRequests: 100,
+  excludePrefixes: [CHANNEL_EVENT_PREFIX],
+});
+```
+
+**Client** — send with `useChannelSend`; receive broadcasts with the existing
+`useRoomEvents` (volatile room emits arrive as ordinary events):
+
+```tsx
+import { useSubscription, useRoomEvents, useChannelSend } from "@fitzzero/quickdraw-core/client";
+
+function GameView({ worldId }: { worldId: string }) {
+  useSubscription("gameService", worldId); // room membership gates the channel
+  const { send, isReady } = useChannelSend<GameInput>("gameService", "input");
+
+  useRoomEvents({
+    "game:snapshot": (snap: WorldSnapshot) => applySnapshot(snap),
+  });
+
+  // e.g. called from a fixed-timestep loop
+  const onTick = (input: GameInput) => send(input);
+}
+```
+
+**Access model** (all synchronous, in-memory):
+
+| Check                    | Behavior                                                                                                                                                       |
+| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Authentication           | Always required — anonymous messages dropped, even at `"Public"` access                                                                                        |
+| `"Public"` / `"Read"`    | Any authenticated user passes the service gate                                                                                                                 |
+| `"Moderate"` / `"Admin"` | Requires that level in the socket's `serviceAccess`                                                                                                            |
+| `requireRoom`            | Socket must already be in the resolved room — membership was ACL-checked at subscribe time, so this inherits entry ACL semantics without a DB read per message |
+
+Channels route as the Socket.io event `channel:<serviceName>:<channelName>`
+(helper: `channelEventName(serviceName, channelName)`), which also makes them
+easy to speak from non-JS clients (game engines, native apps).
+
+When to use which:
+
+|                | Method                    | Channel                  |
+| -------------- | ------------------------- | ------------------------ |
+| Response       | ack with data/error       | none (fire-and-forget)   |
+| Frequency      | occasional (user actions) | tick rate (10-60Hz)      |
+| Loss tolerance | must not lose             | next message supersedes  |
+| ACL            | full async check incl. DB | in-memory only           |
+| Rate limit     | global limiter            | per-channel token bucket |
+
 ## Package Exports
 
 ```typescript

package/dist/client/index.d.ts

@@ -1,6 +1,6 @@
 import * as React from 'react';
-import { a as QuickdrawProviderProps, Q as QuickdrawSocketContextValue, U as UseServiceOptions, b as UseServiceResult, c as UseServiceQueryOptions, d as UseServiceQueryResult, e as UseSubscriptionOptions, f as UseSubscriptionResult, g as UseRoomEventsOptions } from '../types-B1z5aXdR.js';
-export { C as ClientServiceMethodMap, S as SubscriptionDataMap } from '../types-B1z5aXdR.js';
+import { a as QuickdrawProviderProps, Q as QuickdrawSocketContextValue, U as UseServiceOptions, b as UseServiceResult, c as UseServiceQueryOptions, d as UseServiceQueryResult, e as UseSubscriptionOptions, f as UseSubscriptionResult, g as UseRoomEventsOptions, h as UseChannelSendResult } from '../types-DUHPIy_5.js';
+export { C as ClientServiceMethodMap, S as SubscriptionDataMap } from '../types-DUHPIy_5.js';
 import 'socket.io-client';
 import '@tanstack/react-query';
 import '../shared/index.js';
@@ -28,7 +28,7 @@ declare function useQuickdrawSocket(): QuickdrawSocketContextValue;
  * }
  * ```
  */
-declare function QuickdrawProvider({ children, serverUrl, queryClient, authToken, autoConnect, withCredentials, }: QuickdrawProviderProps): React.ReactElement;
+declare function QuickdrawProvider({ children, serverUrl, queryClient, authToken, autoConnect, withCredentials, socketPath, }: QuickdrawProviderProps): React.ReactElement;
 
 /**
  * Hook for invoking service methods via Socket.io with TanStack Query integration.
@@ -207,6 +207,36 @@ declare function useSubscription<TData extends {
  */
 declare function useRoomEvents(handlers: Record<string, (data: never) => void>, options?: UseRoomEventsOptions): void;
 
+/**
+ * Hook for sending fire-and-forget channel messages (the high-frequency
+ * counterpart to useService).
+ *
+ * Channel messages are emitted volatile: if the connection is backpressured,
+ * the message is dropped instead of queued — the right behavior for input
+ * streams where the next message supersedes the last. There is no ack and no
+ * response; the server validates, rate-limits (per-channel token bucket), and
+ * access-checks each message, silently dropping any that fail.
+ *
+ * Receiving server broadcasts needs nothing new: volatile room emits arrive
+ * as ordinary events, so pair this with `useRoomEvents` (and `useSubscription`
+ * for room membership).
+ *
+ * @typeParam TPayload - The channel payload type (from the service's channel map)
+ *
+ * @example
+ * ```tsx
+ * function GameInput({ worldId }: { worldId: string }) {
+ *   // Room membership (ACL-checked server-side) gates the channel
+ *   useSubscription("gameService", worldId);
+ *   const { send, isReady } = useChannelSend<GameInput>("gameService", "input");
+ *
+ *   // e.g. called from a 20Hz game loop
+ *   const onTick = (input: GameInput) => send(input);
+ * }
+ * ```
+ */
+declare function useChannelSend<TPayload = unknown>(serviceName: string, channelName: string): UseChannelSendResult<TPayload>;
+
 type CommitMode = "change" | "blur" | "debounce";
 interface UseSocketInputOptions<TEntry, TAllowedUpdate, TKey extends keyof TAllowedUpdate> {
     /**
@@ -517,4 +547,4 @@ declare function buildBreadcrumbs(pathname: string, navigation: NavItem[]): Brea
  */
 declare function routeRequiresAuth(pathname: string, navigation: NavItem[], userMenuItems?: NavItem[]): boolean;
 
-export { type BreadcrumbItem, type CommitMode, type JWTPayload, type NavItem, QuickdrawProvider, QuickdrawProviderProps, QuickdrawSocketContextValue, SocketCheckbox, type SocketCheckboxProps, SocketSelect, type SocketSelectProps, SocketSlider, type SocketSliderProps, SocketSwitch, type SocketSwitchProps, SocketTextField, type SocketTextFieldProps, UseRoomEventsOptions, UseServiceOptions, UseServiceQueryOptions, UseServiceQueryResult, UseServiceResult, type UseSocketInputOptions, type UseSocketInputResult, UseSubscriptionOptions, UseSubscriptionResult, buildBreadcrumbs, clearAuthToken, findNavItemByHref, findParentNavItem, formatCurrency, formatDate, formatDateTime, formatNumber, formatPercent, getAuthToken, getOAuthUrl, logout, logoutAllDevices, parseJWTPayload, routeRequiresAuth, setAuthToken, truncate, useQuickdrawSocket, useRoomEvents, useService, useServiceMethod, useServiceQuery, useSocketInput, useSubscription };
+export { type BreadcrumbItem, type CommitMode, type JWTPayload, type NavItem, QuickdrawProvider, QuickdrawProviderProps, QuickdrawSocketContextValue, SocketCheckbox, type SocketCheckboxProps, SocketSelect, type SocketSelectProps, SocketSlider, type SocketSliderProps, SocketSwitch, type SocketSwitchProps, SocketTextField, type SocketTextFieldProps, UseChannelSendResult, UseRoomEventsOptions, UseServiceOptions, UseServiceQueryOptions, UseServiceQueryResult, UseServiceResult, type UseSocketInputOptions, type UseSocketInputResult, UseSubscriptionOptions, UseSubscriptionResult, buildBreadcrumbs, clearAuthToken, findNavItemByHref, findParentNavItem, formatCurrency, formatDate, formatDateTime, formatNumber, formatPercent, getAuthToken, getOAuthUrl, logout, logoutAllDevices, parseJWTPayload, routeRequiresAuth, setAuthToken, truncate, useChannelSend, useQuickdrawSocket, useRoomEvents, useService, useServiceMethod, useServiceQuery, useSocketInput, useSubscription };

package/dist/client/index.js

@@ -139,7 +139,8 @@ function QuickdrawProvider({
   queryClient,
   authToken,
   autoConnect = !!authToken,
-  withCredentials = true
+  withCredentials = true,
+  socketPath
 }) {
   const [defaultQueryClient] = React.useState(() => createQueryClient());
   const actualQueryClient = queryClient ?? defaultQueryClient;
@@ -163,7 +164,8 @@ function QuickdrawProvider({
         auth: authToUse ? { token: authToUse } : void 0,
         withCredentials,
         transports: ["websocket", "polling"],
-        autoConnect: true
+        autoConnect: true,
+        ...socketPath ? { path: socketPath } : {}
       });
       newSocket.on("connect", () => {
         setIsConnected(true);
@@ -185,7 +187,7 @@ function QuickdrawProvider({
       socketRef.current = newSocket;
       setSocket(newSocket);
     },
-    [serverUrl, withCredentials]
+    [serverUrl, withCredentials, socketPath]
   );
   const disconnect = React.useCallback(() => {
     if (socketRef.current) {
@@ -664,6 +666,25 @@ function useRoomEvents(handlers, options) {
     };
   }, [socket, isConnected, enabled, stableEventNames]);
 }
+
+// src/shared/types.ts
+function channelEventName(serviceName, channelName) {
+  return `channel:${serviceName}:${channelName}`;
+}
+
+// src/client/useChannelSend.ts
+function useChannelSend(serviceName, channelName) {
+  const { socket, isConnected } = useQuickdrawSocket();
+  const eventName = channelEventName(serviceName, channelName);
+  const send = React.useCallback(
+    (payload) => {
+      if (!socket?.connected) return;
+      socket.volatile.emit(eventName, payload);
+    },
+    [socket, eventName]
+  );
+  return { send, isReady: isConnected && !!socket };
+}
 function useSocketInput(options) {
   const {
     state,
@@ -1194,6 +1215,6 @@ function routeRequiresAuth(pathname, navigation, userMenuItems) {
   return false;
 }
 
-export { QuickdrawProvider, SocketCheckbox, SocketSelect, SocketSlider, SocketSwitch, SocketTextField, buildBreadcrumbs, clearAuthToken, findNavItemByHref, findParentNavItem, formatCurrency, formatDate, formatDateTime, formatNumber, formatPercent, getAuthToken, getOAuthUrl, logout, logoutAllDevices, parseJWTPayload, routeRequiresAuth, setAuthToken, truncate, useQuickdrawSocket, useRoomEvents, useService, useServiceMethod, useServiceQuery, useSocketInput, useSubscription };
+export { QuickdrawProvider, SocketCheckbox, SocketSelect, SocketSlider, SocketSwitch, SocketTextField, buildBreadcrumbs, clearAuthToken, findNavItemByHref, findParentNavItem, formatCurrency, formatDate, formatDateTime, formatNumber, formatPercent, getAuthToken, getOAuthUrl, logout, logoutAllDevices, parseJWTPayload, routeRequiresAuth, setAuthToken, truncate, useChannelSend, useQuickdrawSocket, useRoomEvents, useService, useServiceMethod, useServiceQuery, useSocketInput, useSubscription };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map