sleepy-serv 0.11.0 → 0.13.0

package/README.md

@@ -12,10 +12,7 @@ A directory-driven web server designed for REST-ful applications
 Here's a minimalist example on how to create a sleepy-serv app:
 
 ```js
-import {
-  middleware,
-  createApp,
-} from 'sleepy-serv'
+import { createApp } from 'sleepy-serv'
 
 const PORT = 3000
 
@@ -29,7 +26,7 @@ The parameter for `import.meta.dirname` can be any directory you prefer, but it'
 `sleepy-serv` was originally built for NodeJS, but it was ported to `bun` recently (before the initial release). The `createApp()` function merely calls `Bun.serve()` under-the-hood, and returns the `app` object that contains these properties:
 - `routes`: Contains a list of all of the routes defined by the file structure. This is useful for debugging.
 - `server`: this is the object that's returned from `Bun.serve()`. The `server` object has an `async` `.stop()` method on it, but prefer `app.close()` (see [Shutting Down](#shutting-down)), which stops the server and releases everything else the app holds.
-- `commands`: WebSocket helpers for pushing messages out to connected clients: `send(clientId, event, body)` and `broadcast(event, body)`.
+- `ws`: WebSocket commands for interacting with connected clients: `query(fn)`, `send(fn, event, body)`, `broadcast(event, body)`, and `drop(fn, code?, reason?)`.
 - `close`: an `async` function that shuts the app down. See [Shutting Down](#shutting-down).
 
 ### Shutting Down
@@ -488,3 +485,64 @@ const app = await createApp(PORT, import.meta.dirname, {
   onClose: () => console.info('closing down...'),
 })
 ```
+
+### `ws`
+
+WebSocket tuning and lifecycle hooks:
+
+```js
+const app = await createApp(PORT, import.meta.dirname, {
+  ws: {
+    heartbeatInterval: 30_000,
+    dropThreshold: 120_000,
+    reclaimTtl: 300_000,
+    ticketTtl: 10_000,
+    onOpen: clientId => console.log('connected:', clientId),
+    onClose: (clientId, reason) => console.log('closed:', clientId, reason),
+  },
+})
+```
+
+- `heartbeatInterval`: how often the client should send heartbeats, in milliseconds. Sent to the client in the welcome message. Defaults to `30_000`.
+- `dropThreshold`: how long the server waits without an inbound message before reaping the connection, in milliseconds. Defaults to `120_000`.
+- `reclaimTtl`: how long an inactive (reaped/dropped) session stays reclaimable, in milliseconds. Defaults to `300_000`.
+- `ticketTtl`: how long a minted upgrade ticket stays valid, in milliseconds. Defaults to `10_000`.
+- `onOpen(clientId)`: fires after a client's welcome message is sent. Wrapped in try/catch so a throwing hook does not break the connection.
+- `onClose(clientId, reason)`: fires when a connection closes. `reason` is a `CloseReason` value: `'ok'`, `'dropped'`, `'reaped'`, or `'superseded'`. Also wrapped in try/catch.
+
+## WebSocket Commands
+
+The `app.ws` object exposes four methods for interacting with connected clients:
+
+- `query(fn)`: return a filtered list of active sessions. The filter function receives `(clientId, data, index)` and returns a boolean. Each entry in the returned array is a `SessionEntry` with `clientId` and `app` (the application context). To list all sessions: `app.ws.query(() => true)`.
+- `send(fn, event, body)`: push a notification to clients matching a filter. The filter function receives `(clientId, data, index)` and returns a boolean. To target one client: `app.ws.send(id => id === targetId, event, body)`.
+- `broadcast(event, body)`: push a notification to all connected clients.
+- `drop(fn, code?, reason?)`: close connections matching a filter. The filter function receives `(clientId, data, index)` and returns a boolean. The default code is `CloseCode.Ok` (1000), which tells the client not to reconnect. Passing a custom code (e.g. 4000) allows the client to reconnect. To drop one client: `app.ws.drop(id => id === targetId)`.
+
+The same commands are available inside endpoint handlers via `req.ws`:
+
+```js
+export default function (req) {
+  const targetId = req.query.targetId
+
+  req.ws.send(id => id === targetId, 'ping', { from: 'handler' })
+
+  return Response.json({ ok: true })
+}
+```
+
+This works from both HTTP and WebSocket transports.
+
+## Exports
+
+`sleepy-serv` exports several runtime constants and types:
+
+- `CloseCode`: WebSocket close codes: `Ok` (1000), `Abnormal` (1006), `Reaped` (4999)
+- `CloseReason`: close reason values: `Ok`, `Dropped`, `Reaped`, `Superseded`
+- `StatusCode`: the full range of HTTP status codes (1xx through 5xx)
+- `HttpMethod`: HTTP verbs: `Head`, `Get`, `Post`, `Put`, `Patch`, `Delete`
+- `SessionEntry`: the shape returned by `query()`: `{ clientId: string, app: unknown }`
+- `FilterFn`: the filter callback type: `(clientId: string, data: unknown, index: number) => boolean`
+- `SocketCommands`: the type for `app.ws` and `req.ws`
+- Error classes for every 4xx and 5xx status (e.g. `NotFoundError`, `UnauthorizedError`, `InternalServerError`)
+- Middleware helpers: `parseJsonBody`, `validateSchemas`, `setValidationFormats`

package/dist/index.d.ts

@@ -1,18 +1,16 @@
-import type { AppOptions, Server } from './utils';
-import type { SocketCommands } from './socket';
+import type { SocketCommands, AppOptions, Server } from './utils';
 export * from './errors';
 export { StatusCode, CloseCode, CloseReason, HttpMethod } from './utils';
 export { parseJsonBody, setValidationFormats, validateSchemas, } from './middleware';
-export type { SocketCommands } from './socket';
-export type { ActiveSessions } from './utils';
+export type { FilterFn, SessionEntry, SocketCommands } from './utils';
 export type { AppOptions, AsyncHandlerResult, BaseRequest, EndpointRequest, FormattedError, Handler, Middleware, MiddlewareChain, NextFn, HandlerResult, Request, Server, SocketConnection, SocketOptions, WebSocketRequest, } from './utils';
 export type { FormatterField, FormatterSchema, ValidationSchemas, } from './middleware';
 type OutputRoutes = Record<string, string[]>;
 type CloseFn = (force?: boolean) => Promise<void>;
 export type App = {
     server: Server;
-    commands: SocketCommands;
     routes: OutputRoutes;
+    ws: SocketCommands;
     close: CloseFn;
 };
 export declare function createApp(port: number, rootPath: string, opts?: AppOptions): Promise<App>;

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AA4BA,OAAO,KAAK,EAOV,UAAU,EACV,MAAM,EACP,MAAM,SAAS,CAAA;AAEhB,OAAO,KAAK,EAGV,cAAc,EACf,MAAM,UAAU,CAAA;AAEjB,cAAc,UAAU,CAAA;AACxB,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAExE,OAAO,EACL,aAAa,EACb,oBAAoB,EACpB,eAAe,GAChB,MAAM,cAAc,CAAA;AAErB,YAAY,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AAC9C,YAAY,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAE7C,YAAY,EACV,UAAU,EACV,kBAAkB,EAClB,WAAW,EACX,eAAe,EACf,cAAc,EACd,OAAO,EACP,UAAU,EACV,eAAe,EACf,MAAM,EACN,aAAa,EACb,OAAO,EACP,MAAM,EACN,gBAAgB,EAChB,aAAa,EACb,gBAAgB,GACjB,MAAM,SAAS,CAAA;AAEhB,YAAY,EACV,cAAc,EACd,eAAe,EACf,iBAAiB,GAClB,MAAM,cAAc,CAAA;AAErB,KAAK,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAA;AA4C5C,KAAK,OAAO,GAAG,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;AAEjD,MAAM,MAAM,GAAG,GAAG;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,cAAc,CAAA;IACxB,MAAM,EAAE,YAAY,CAAA;IACpB,KAAK,EAAE,OAAO,CAAA;CACf,CAAA;AAyaD,wBAAsB,SAAS,CAC7B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE,UAAe,GACpB,OAAO,CAAC,GAAG,CAAC,CAad"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AA4BA,OAAO,KAAK,EAMV,cAAc,EACd,UAAU,EACV,MAAM,EACP,MAAM,SAAS,CAAA;AAOhB,cAAc,UAAU,CAAA;AACxB,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAExE,OAAO,EACL,aAAa,EACb,oBAAoB,EACpB,eAAe,GAChB,MAAM,cAAc,CAAA;AAErB,YAAY,EAAE,QAAQ,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAErE,YAAY,EACV,UAAU,EACV,kBAAkB,EAClB,WAAW,EACX,eAAe,EACf,cAAc,EACd,OAAO,EACP,UAAU,EACV,eAAe,EACf,MAAM,EACN,aAAa,EACb,OAAO,EACP,MAAM,EACN,gBAAgB,EAChB,aAAa,EACb,gBAAgB,GACjB,MAAM,SAAS,CAAA;AAEhB,YAAY,EACV,cAAc,EACd,eAAe,EACf,iBAAiB,GAClB,MAAM,cAAc,CAAA;AAErB,KAAK,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAA;AA4C5C,KAAK,OAAO,GAAG,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;AAEjD,MAAM,MAAM,GAAG,GAAG;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,YAAY,CAAA;IACpB,EAAE,EAAE,cAAc,CAAA;IAClB,KAAK,EAAE,OAAO,CAAA;CACf,CAAA;AA0aD,wBAAsB,SAAS,CAC7B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE,UAAe,GACpB,OAAO,CAAC,GAAG,CAAC,CAad"}

package/dist/socket.d.ts

@@ -1,8 +1,7 @@
 import { CloseReason } from './utils';
 import type { WebSocketHandler } from 'bun';
-import type { AsyncHandlerResult, HttpMethod, Request, MiddlewareChain, SocketData, ActiveSession, InactiveSession, AppOptions } from './utils';
+import type { AsyncHandlerResult, HttpMethod, Request, MiddlewareChain, SocketCommands, SocketData, ActiveSession, InactiveSession, AppOptions } from './utils';
 type SocketHandler = (req: Request, res: unknown) => AsyncHandlerResult;
-type FilterFn = (clientId: string, data: unknown) => boolean;
 type SocketEndpoint = {
     method: HttpMethod;
     path: string;
@@ -31,14 +30,8 @@ export type SocketRoute = {
     segments: string[];
     chain: MiddlewareChain;
 };
-export type SocketCommands = {
-    send: (clientId: string, event: string, body: unknown) => void;
-    sendToGroup: (fn: FilterFn, event: string, body: unknown) => void;
-    broadcast: (event: string, body: unknown) => void;
-    drop: (clientId: string, code?: number, reason?: string) => void;
-};
 export declare function buildSocketState(opts?: AppOptions): SocketState;
-export declare function buildSocketServer(routes: SocketRoute[], state: SocketState): WebSocketHandler<SocketData>;
+export declare function buildSocketServer(routes: SocketRoute[], state: SocketState, commands: SocketCommands): WebSocketHandler<SocketData>;
 export declare function buildSocketHandlers(state: SocketState): SocketEndpoint[];
 export declare function buildSocketCommands(state: SocketState): SocketCommands;
 export {};

package/dist/socket.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"socket.d.ts","sourceRoot":"","sources":["../src/socket.ts"],"names":[],"mappings":"AAUA,OAAO,EAGL,WAAW,EAIZ,MAAM,SAAS,CAAA;AAchB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,KAAK,CAAA;AAE3C,OAAO,KAAK,EACV,kBAAkB,EAClB,UAAU,EACV,OAAO,EACP,eAAe,EAEf,UAAU,EAEV,aAAa,EAEb,eAAe,EAEf,UAAU,EACX,MAAM,SAAS,CAAA;AAShB,KAAK,aAAa,GAAG,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,KAAK,kBAAkB,CAAA;AACvE,KAAK,QAAQ,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,KAAK,OAAO,CAAA;AAY5D,KAAK,cAAc,GAAG;IACpB,MAAM,EAAE,UAAU,CAAA;IAClB,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,aAAa,CAAA;CACvB,CAAA;AAqBD,MAAM,MAAM,MAAM,GAAG;IACnB,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,IAAI,EAAE,OAAO,CAAA;CACd,CAAA;AAED,MAAM,MAAM,WAAW,GAAG;IACxB,aAAa,EAAE,MAAM,CAAA;IACrB,iBAAiB,EAAE,MAAM,CAAA;IACzB,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,MAAM,CAAA;IAClB,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC5B,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAA;IAC1C,gBAAgB,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAA;IAC9C,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,IAAI,CAAA;IAC3C,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,KAAK,IAAI,CAAC,GAAG,IAAI,CAAA;CAClE,CAAA;AAED,MAAM,MAAM,WAAW,GAAG;IACxB,MAAM,EAAE,UAAU,CAAA;IAClB,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,EAAE,CAAA;IAClB,KAAK,EAAE,eAAe,CAAA;CACvB,CAAA;AAED,MAAM,MAAM,cAAc,GAAG;IAC3B,IAAI,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,KAAK,IAAI,CAAA;IAC9D,WAAW,EAAE,CAAC,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,KAAK,IAAI,CAAA;IACjE,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,KAAK,IAAI,CAAA;IACjD,IAAI,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;CACjE,CAAA;AAmTD,wBAAgB,gBAAgB,CAAE,IAAI,GAAE,UAAe,GAAG,WAAW,CAapE;AAED,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,WAAW,EAAE,EACrB,KAAK,EAAE,WAAW,GACjB,gBAAgB,CAAC,UAAU,CAAC,CAoJ9B;AAED,wBAAgB,mBAAmB,CAAE,KAAK,EAAE,WAAW,GAAG,cAAc,EAAE,CAyIzE;AAED,wBAAgB,mBAAmB,CAAE,KAAK,EAAE,WAAW,GAAG,cAAc,CA6CvE"}
+{"version":3,"file":"socket.d.ts","sourceRoot":"","sources":["../src/socket.ts"],"names":[],"mappings":"AAUA,OAAO,EAGL,WAAW,EAIZ,MAAM,SAAS,CAAA;AAchB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,KAAK,CAAA;AAE3C,OAAO,KAAK,EACV,kBAAkB,EAClB,UAAU,EACV,OAAO,EACP,eAAe,EACf,cAAc,EAGd,UAAU,EAEV,aAAa,EACb,eAAe,EAEf,UAAU,EACX,MAAM,SAAS,CAAA;AAShB,KAAK,aAAa,GAAG,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,KAAK,kBAAkB,CAAA;AAYvE,KAAK,cAAc,GAAG;IACpB,MAAM,EAAE,UAAU,CAAA;IAClB,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,aAAa,CAAA;CACvB,CAAA;AAqBD,MAAM,MAAM,MAAM,GAAG;IACnB,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,IAAI,EAAE,OAAO,CAAA;CACd,CAAA;AAED,MAAM,MAAM,WAAW,GAAG;IACxB,aAAa,EAAE,MAAM,CAAA;IACrB,iBAAiB,EAAE,MAAM,CAAA;IACzB,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,MAAM,CAAA;IAClB,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC5B,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAA;IAC1C,gBAAgB,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAA;IAC9C,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,IAAI,CAAA;IAC3C,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,KAAK,IAAI,CAAC,GAAG,IAAI,CAAA;CAClE,CAAA;AAED,MAAM,MAAM,WAAW,GAAG;IACxB,MAAM,EAAE,UAAU,CAAA;IAClB,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,EAAE,CAAA;IAClB,KAAK,EAAE,eAAe,CAAA;CACvB,CAAA;AAiTD,wBAAgB,gBAAgB,CAAE,IAAI,GAAE,UAAe,GAAG,WAAW,CAapE;AAED,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,WAAW,EAAE,EACrB,KAAK,EAAE,WAAW,EAClB,QAAQ,EAAE,cAAc,GACvB,gBAAgB,CAAC,UAAU,CAAC,CAoJ9B;AAED,wBAAgB,mBAAmB,CAAE,KAAK,EAAE,WAAW,GAAG,cAAc,EAAE,CAyIzE;AAED,wBAAgB,mBAAmB,CAAE,KAAK,EAAE,WAAW,GAAG,cAAc,CAgEvE"}

package/dist/utils.d.ts

@@ -96,6 +96,17 @@ export type InactiveSession = {
 };
 export type ActiveSessions = ReadonlyMap<string, ActiveSession>;
 export type Session = ActiveSession | InactiveSession;
+export type SessionEntry = {
+    clientId: string;
+    app: unknown;
+};
+export type FilterFn = (clientId: string, data: unknown, index: number) => boolean;
+export type SocketCommands = {
+    query: (fn: FilterFn) => SessionEntry[];
+    send: (fn: FilterFn, event: string, body: unknown) => void;
+    broadcast: (event: string, body: unknown) => void;
+    drop: (fn: FilterFn, code?: number, reason?: string) => void;
+};
 export type BaseRequest = {
     method: HttpMethod;
     route: string;
@@ -103,9 +114,7 @@ export type BaseRequest = {
     params: Record<string, string>;
     query: Record<string, unknown>;
     json: () => Promise<unknown>;
-    ws: {
-        active: ActiveSessions;
-    };
+    ws: SocketCommands;
 };
 export type EndpointRequest = BaseRequest & {
     raw: BunRequest;

package/dist/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -3,7 +3,7 @@
   "description": "A more opinionated web server for building REST-ful applications",
   "author": "Travis J True",
   "license": "MIT",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "type": "module",
   "exports": {
     ".": {

package/src/index.ts

@@ -32,7 +32,7 @@ import type {
   Middleware,
   MiddlewareChain,
   EndpointRequest,
-  ActiveSessions,
+  SocketCommands,
   AppOptions,
   Server,
 } from './utils'
@@ -40,7 +40,6 @@ import type {
 import type {
   SocketRoute,
   SocketState,
-  SocketCommands,
 } from './socket'
 
 export * from './errors'
@@ -52,8 +51,7 @@ export {
   validateSchemas,
 } from './middleware'
 
-export type { SocketCommands } from './socket'
-export type { ActiveSessions } from './utils'
+export type { FilterFn, SessionEntry, SocketCommands } from './utils'
 
 export type {
   AppOptions,
@@ -127,8 +125,8 @@ type CloseFn = (force?: boolean) => Promise<void>
 
 export type App = {
   server: Server
-  commands: SocketCommands
   routes: OutputRoutes
+  ws: SocketCommands
   close: CloseFn
 }
 
@@ -167,7 +165,7 @@ function defaultMethodMap (): Record<string, EndpointHandler> {
 function buildEndpointRequest (
   bunReq: BunRequest,
   server: Server,
-  activeSessions: ActiveSessions,
+  ws: SocketCommands,
 ): EndpointRequest {
   const url = new URL(bunReq.url)
   const qs = url.search.replace('?', '')
@@ -191,9 +189,7 @@ function buildEndpointRequest (
     raw: bunReq,
     server,
     json,
-    ws: {
-      active: activeSessions,
-    },
+    ws,
   }
 }
 
@@ -405,15 +401,11 @@ function buildSocketRoutes (mergedRoutes: ChainRoute[]): SocketRoute[] {
 
 function buildModuleRoutes (
   socketRoutes: SocketRoute[],
-  state: SocketState,
+  ws: SocketCommands,
 ): ModuleRoute[] {
   return socketRoutes.map(route => {
     const handler: EndpointHandler = async (bunReq, server) => {
-      const req = buildEndpointRequest(
-        bunReq,
-        server,
-        state.activeSessions,
-      )
+      const req = buildEndpointRequest(bunReq, server, ws)
 
       return executeMiddlewareChain(req, route.chain)
     }
@@ -451,6 +443,7 @@ function buildOutputRoutes (moduleRoutes: ModuleRoute[]): OutputRoutes {
 async function buildRoutes (
   rootPath: string,
   state: SocketState,
+  ws: SocketCommands,
   opts: AppOptions,
 ): Promise<AppRoutes> {
   const basePath = `${rootPath}/api`
@@ -474,7 +467,7 @@ async function buildRoutes (
   )
 
   const socketRoutes = buildSocketRoutes(mergedRoutes)
-  const moduleRoutes = buildModuleRoutes(socketRoutes, state)
+  const moduleRoutes = buildModuleRoutes(socketRoutes, ws)
   const serverRoutes = buildServerRoutes(moduleRoutes)
   const outputRoutes = buildOutputRoutes(moduleRoutes)
 
@@ -489,10 +482,16 @@ function buildServer (
   port: number,
   routes: AppRoutes,
   state: SocketState,
+  ws: SocketCommands,
   opts: AppOptions,
 ): Server {
   const hostname = opts.hostname || '0.0.0.0'
-  const websocketServer = buildSocketServer(routes.socket, state)
+
+  const websocketServer = buildSocketServer(
+    routes.socket,
+    state,
+    ws,
+  )
 
   return Bun.serve({
     port,
@@ -561,15 +560,15 @@ export async function createApp (
   opts: AppOptions = {},
 ): Promise<App> {
   const state = buildSocketState(opts)
-  const routes = await buildRoutes(rootPath, state, opts)
-  const server = buildServer(port, routes, state, opts)
-  const commands = buildSocketCommands(state)
+  const ws = buildSocketCommands(state)
+  const routes = await buildRoutes(rootPath, state, ws, opts)
+  const server = buildServer(port, routes, state, ws, opts)
   const close = processIO(port, server, opts)
 
   return {
     routes: routes.output,
     server,
-    commands,
+    ws,
     close,
   }
 }

package/src/socket.ts

@@ -36,11 +36,12 @@ import type {
   HttpMethod,
   Request,
   MiddlewareChain,
+  SocketCommands,
+  SessionEntry,
   WebSocketRequest,
   SocketData,
   SocketConnection,
   ActiveSession,
-  ActiveSessions,
   InactiveSession,
   Session,
   AppOptions,
@@ -54,7 +55,6 @@ import type {
 } from './messages'
 
 type SocketHandler = (req: Request, res: unknown) => AsyncHandlerResult
-type FilterFn = (clientId: string, data: unknown) => boolean
 
 type UpgradeData = {
   clientId?: string
@@ -117,13 +117,6 @@ export type SocketRoute = {
   chain: MiddlewareChain
 }
 
-export type SocketCommands = {
-  send: (clientId: string, event: string, body: unknown) => void
-  sendToGroup: (fn: FilterFn, event: string, body: unknown) => void
-  broadcast: (event: string, body: unknown) => void
-  drop: (clientId: string, code?: number, reason?: string) => void
-}
-
 const ajv = new Ajv({
   allErrors: true,
 })
@@ -361,7 +354,7 @@ function buildParams (
 function buildRequest (
   params: Record<string, string>,
   message: RequestMessage,
-  activeSessions: ActiveSessions,
+  ws: SocketCommands,
 ): WebSocketRequest {
   const { id, clientId, method, route } = message
   const headers = new Headers(message.headers ?? {})
@@ -376,10 +369,8 @@ function buildRequest (
     headers,
     params,
     query,
+    ws,
     json,
-    ws: {
-      active: activeSessions,
-    },
   }
 }
 
@@ -447,6 +438,7 @@ export function buildSocketState (opts: AppOptions = {}): SocketState {
 export function buildSocketServer (
   routes: SocketRoute[],
   state: SocketState,
+  commands: SocketCommands,
 ): WebSocketHandler<SocketData> {
   const {
     dropThreshold,
@@ -581,7 +573,7 @@ export function buildSocketServer (
         const { id, clientId } = message
         const route = matchRoute(routes, message)
         const params = buildParams(route, message)
-        const req = buildRequest(params, message, activeSessions)
+        const req = buildRequest(params, message, commands)
         const res = await executeMiddlewareChain(req, route.chain)
         const outgoingMsg = await buildOutgoingMessage(id, clientId, res)
 
@@ -754,16 +746,33 @@ export function buildSocketCommands (state: SocketState): SocketCommands {
   }
 
   return {
-    send (clientId, event, body) {
-      sendToClient(clientId, event, body)
-    },
-    sendToGroup (fn, event, body) {
+    query (fn) {
+      const results: SessionEntry[] = []
+      let index = 0
+
       for (const [clientId, session] of state.activeSessions) {
-        const allow = fn(clientId, session.ws.data)
+        if (fn(clientId, session.ws.data, index)) {
+          results.push({
+            clientId,
+            app: session.ws.data.app,
+          })
+        }
+
+        index += 1
+      }
 
-        if (allow) {
+      return results
+    },
+    send (fn, event, body) {
+      let index = 0
+
+      /* TODO: look into concurrency at some point */
+      for (const [clientId, session] of state.activeSessions) {
+        if (fn(clientId, session.ws.data, index)) {
           sendToClient(clientId, event, body)
         }
+
+        index += 1
       }
     },
     broadcast (event, body) {
@@ -771,14 +780,16 @@ export function buildSocketCommands (state: SocketState): SocketCommands {
         sendToClient(clientId, event, body)
       }
     },
-    drop (clientId, code, reason) {
-      const session = state.activeSessions.get(clientId)
+    drop (fn, code, reason) {
+      let index = 0
 
-      if (!session) {
-        throw new ReferenceError(`No active socket for client: ${clientId}`)
-      }
+      for (const [clientId, session] of state.activeSessions) {
+        if (fn(clientId, session.ws.data, index)) {
+          session.ws.close(code, reason)
+        }
 
-      session.ws.close(code, reason)
+        index += 1
+      }
     },
   }
 }

package/src/utils.ts

@@ -121,6 +121,24 @@ export type InactiveSession = {
 export type ActiveSessions = ReadonlyMap<string, ActiveSession>
 export type Session = ActiveSession | InactiveSession
 
+export type SessionEntry = {
+  clientId: string
+  app: unknown
+}
+
+export type FilterFn = (
+  clientId: string,
+  data: unknown,
+  index: number,
+) => boolean
+
+export type SocketCommands = {
+  query: (fn: FilterFn) => SessionEntry[]
+  send: (fn: FilterFn, event: string, body: unknown) => void
+  broadcast: (event: string, body: unknown) => void
+  drop: (fn: FilterFn, code?: number, reason?: string) => void
+}
+
 export type BaseRequest = {
   method: HttpMethod
   route: string
@@ -128,9 +146,7 @@ export type BaseRequest = {
   params: Record<string, string>
   query: Record<string, unknown>
   json: () => Promise<unknown>
-  ws: {
-    active: ActiveSessions
-  }
+  ws: SocketCommands
 }
 
 export type EndpointRequest = BaseRequest & {