verani 0.5.4 → 0.6.0

package/dist/actor-runtime-CbquUZdU.d.mts

@@ -0,0 +1,345 @@
+import { n as ConnectionMeta, r as MessageFrame } from "./types-Bs7hBgfQ.mjs";
+import { Actor, ActorConfiguration } from "@cloudflare/actors";
+
+//#region src/actor/types.d.ts
+
+/**
+ * Options for broadcasting messages to connections
+ */
+interface BroadcastOptions {
+  /** Exclude specific WebSocket from receiving the broadcast */
+  except?: WebSocket;
+  /** Only send to specific user IDs */
+  userIds?: string[];
+  /** Only send to specific client IDs */
+  clientIds?: string[];
+}
+/**
+ * RPC-safe version of BroadcastOptions for use over RPC calls.
+ * Excludes the `except` field since WebSocket cannot be serialized over RPC.
+ */
+interface RpcBroadcastOptions {
+  /** Only send to specific user IDs */
+  userIds?: string[];
+  /** Only send to specific client IDs */
+  clientIds?: string[];
+}
+/**
+ * Actor stub interface returned by .get() method.
+ * Provides RPC access to actor methods that can be called remotely.
+ *
+ * Note: RPC methods return Promises even if the underlying method is synchronous.
+ * Methods that return non-serializable types (like WebSocket[] or DurableObjectStorage)
+ * are excluded from this interface.
+ */
+interface ActorStub {
+  /**
+   * Standard fetch method for handling HTTP requests and WebSocket upgrades
+   */
+  fetch(request: Request): Promise<Response>;
+  /**
+   * Socket.IO-like emit API: Emit an event to a specific channel via RPC.
+   * @param channel - Channel name to emit to
+   * @param event - Event name
+   * @param data - Event data
+   * @returns Promise resolving to the number of connections that received the message
+   * @example
+   * ```typescript
+   * await stub.emitToChannel("default", "announcement", { text: "Hello!" });
+   * ```
+   */
+  emitToChannel(channel: string, event: string, data?: any): Promise<number>;
+  /**
+   * Socket.IO-like emit API: Emit an event to a specific user (all their sessions) via RPC.
+   * @param userId - User ID to emit to
+   * @param event - Event name
+   * @param data - Event data
+   * @returns Promise resolving to the number of sessions that received the message
+   * @example
+   * ```typescript
+   * await stub.emitToUser("alice", "notification", { message: "Hello!" });
+   * ```
+   */
+  emitToUser(userId: string, event: string, data?: any): Promise<number>;
+  /**
+   * @deprecated Use `emitToUser()` instead for Socket.IO-like API.
+   * Sends a message to a specific user (all their sessions) via RPC.
+   * @param userId - The user ID to send to
+   * @param channel - The channel to send to
+   * @param data - Message data
+   * @returns Promise resolving to the number of sessions that received the message
+   */
+  sendToUser(userId: string, channel: string, data?: any): Promise<number>;
+  /**
+   * @deprecated Use `emitToChannel()` instead for Socket.IO-like API.
+   * Broadcasts a message to all connections in a channel via RPC.
+   * Note: The `except` option from BroadcastOptions is not available over RPC
+   * since WebSocket cannot be serialized.
+   * @param channel - The channel to broadcast to
+   * @param data - The data to send
+   * @param opts - Broadcast options (filtering by userIds or clientIds)
+   * @returns Promise resolving to the number of connections that received the message
+   */
+  broadcast(channel: string, data: any, opts?: RpcBroadcastOptions): Promise<number>;
+  /**
+   * Gets the total number of active sessions via RPC.
+   * @returns Promise resolving to the number of connected WebSockets
+   */
+  getSessionCount(): Promise<number>;
+  /**
+   * Gets all unique user IDs currently connected via RPC.
+   * @returns Promise resolving to an array of unique user IDs
+   */
+  getConnectedUserIds(): Promise<string[]>;
+  /**
+   * Removes all WebSocket sessions that are not in OPEN state via RPC.
+   * This prevents stale connections from accumulating in memory.
+   * @returns Promise resolving to the number of sessions cleaned up
+   */
+  cleanupStaleSessions(): Promise<number>;
+}
+/**
+ * Extended Actor interface with Verani-specific methods
+ */
+interface VeraniActor<TMeta extends ConnectionMeta = ConnectionMeta, E = unknown> extends Actor<E> {
+  /**
+   * Map of active WebSocket sessions keyed by their WebSocket instance.
+   * Each entry contains the WebSocket and its associated metadata.
+   * See: @src/actor/actor-runtime.ts usage for session management.
+   */
+  sessions: Map<WebSocket, {
+    ws: WebSocket;
+    meta: TMeta;
+  }>;
+  /**
+   * Broadcast a message to all connections in a channel.
+   * Performs channel, userId, clientId, and exclusion filtering.
+   * Returns the number of connections the message was sent to.
+   * @see @src/actor/actor-runtime.ts broadcast()
+   */
+  broadcast(channel: string, data: any, opts?: BroadcastOptions): number;
+  /**
+   * Returns the number of currently connected WebSocket sessions.
+   * @see @src/actor/actor-runtime.ts getSessionCount()
+   */
+  getSessionCount(): number;
+  /**
+   * Get all unique user IDs currently connected to this actor.
+   * @see @src/actor/actor-runtime.ts getConnectedUserIds()
+   */
+  getConnectedUserIds(): string[];
+  /**
+   * Get all WebSocket sessions for a given user ID.
+   * @see @src/actor/actor-runtime.ts getUserSessions()
+   */
+  getUserSessions(userId: string): WebSocket[];
+  /**
+   * Send a message to all sessions belonging to a user ID in a given channel.
+   * Message will only be sent to sessions where the user's channels include the given channel.
+   * Returns the number of sessions the message was sent to.
+   * The message "type" is always "event" (see src/actor/actor-runtime.ts).
+   * @see @src/actor/actor-runtime.ts sendToUser()
+   */
+  sendToUser(userId: string, channel: string, data?: any): number;
+  /**
+   * Validates and removes stale WebSocket sessions.
+   * Called automatically during broadcast/send operations, but can be called manually.
+   * Returns the number of stale sessions removed.
+   * @see @src/actor/actor-runtime.ts cleanupStaleSessions()
+   */
+  cleanupStaleSessions(): number;
+  /**
+   * Access the Durable Object storage API for this actor instance.
+   * @see @src/actor/actor-runtime.ts getStorage()
+   */
+  getStorage(): DurableObjectStorage;
+  /**
+   * Socket.io-like emit API for actor-level broadcasting
+   */
+  emit: ActorEmit<TMeta, E>;
+}
+/**
+ * Event handler function type for socket.io-like event handling
+ */
+type EventHandler<TMeta extends ConnectionMeta = ConnectionMeta, E = unknown> = (ctx: MessageContext<TMeta, E>, data: any) => void | Promise<void>;
+/**
+ * Event emitter interface for room-level event handling
+ */
+interface RoomEventEmitter<TMeta extends ConnectionMeta = ConnectionMeta, E = unknown> {
+  /**
+   * Register an event handler
+   * @param event - Event name (supports wildcard "*")
+   * @param handler - Handler function
+   */
+  on(event: string, handler: EventHandler<TMeta, E>): void;
+  /**
+   * Remove an event handler
+   * @param event - Event name
+   * @param handler - Optional specific handler to remove, or remove all handlers for event
+   */
+  off(event: string, handler?: EventHandler<TMeta, E>): void;
+  /**
+   * Emit an event to registered handlers
+   * @param event - Event name
+   * @param ctx - Message context
+   * @param data - Event data
+   */
+  emit(event: string, ctx: MessageContext<TMeta, E>, data: any): Promise<void>;
+  /**
+   * Rebuild handlers from static storage.
+   * Called after hibernation to restore handlers from the room definition.
+   * This method MUST be implemented by all event emitter implementations.
+   * @param staticHandlers - Map of event names to handler sets from static storage
+   */
+  rebuildHandlers(staticHandlers: Map<string, Set<EventHandler<TMeta, E>>>): void;
+}
+/**
+ * Builder interface for targeting specific scopes when emitting
+ */
+interface EmitBuilder<TMeta extends ConnectionMeta = ConnectionMeta, E = unknown> {
+  /**
+   * Emit to the targeted scope
+   * @param event - Event name
+   * @param data - Event data
+   * @returns Number of connections that received the message
+   */
+  emit(event: string, data?: any): number;
+}
+/**
+ * Socket-level emit API (available on context)
+ * Allows emitting to current socket, user, or channel
+ */
+interface SocketEmit<TMeta extends ConnectionMeta = ConnectionMeta, E = unknown> {
+  /**
+   * Emit to the current socket
+   * @param event - Event name
+   * @param data - Event data
+   */
+  emit(event: string, data?: any): void;
+  /**
+   * Target a specific user or channel for emitting
+   * @param target - User ID or channel name
+   * @returns Builder for emitting to the target
+   */
+  to(target: string): EmitBuilder<TMeta, E>;
+}
+/**
+ * Actor-level emit API (available on actor)
+ * Allows broadcasting to channels
+ */
+interface ActorEmit<TMeta extends ConnectionMeta = ConnectionMeta, E = unknown> {
+  /**
+   * Broadcast to default channel
+   * @param event - Event name
+   * @param data - Event data
+   * @returns Number of connections that received the message
+   */
+  emit(event: string, data?: any): number;
+  /**
+   * Target a specific channel for broadcasting
+   * @param channel - Channel name
+   * @returns Builder for emitting to the channel
+   */
+  to(channel: string): EmitBuilder<TMeta, E>;
+}
+/**
+ * Context provided to room lifecycle hooks
+ */
+interface RoomContext<TMeta extends ConnectionMeta = ConnectionMeta, E = unknown> {
+  /** The actor instance handling this connection */
+  actor: VeraniActor<TMeta, E>;
+  /** The WebSocket connection */
+  ws: WebSocket;
+  /** Connection metadata */
+  meta: TMeta;
+  /** Socket.io-like emit API for this connection */
+  emit: SocketEmit<TMeta, E>;
+}
+/**
+ * Context for onMessage hook with frame included
+ */
+interface MessageContext<TMeta extends ConnectionMeta = ConnectionMeta, E = unknown> extends RoomContext<TMeta, E> {
+  /** The received message frame */
+  frame: MessageFrame;
+}
+/**
+ * Room definition with lifecycle hooks
+ *
+ * **Important:** All lifecycle hooks are properly awaited if they return a Promise.
+ * This ensures async operations complete before the actor proceeds to the next step
+ * or potentially enters hibernation.
+ */
+interface RoomDefinition<TMeta extends ConnectionMeta = ConnectionMeta, E = unknown> {
+  /** Optional room name for debugging */
+  name?: string;
+  /** WebSocket upgrade path (default: "/ws") */
+  websocketPath: string;
+  /**
+   * Extract metadata from the connection request.
+   * This function is awaited if it returns a Promise.
+   */
+  extractMeta?(req: Request): TMeta | Promise<TMeta>;
+  /**
+   * Called when a new WebSocket connection is established.
+   * This hook is awaited if it returns a Promise. The session is only added to the
+   * sessions map after this hook completes successfully. If this hook throws, the
+   * connection is closed and no orphaned session is created.
+   */
+  onConnect?(ctx: RoomContext<TMeta, E>): void | Promise<void>;
+  /**
+   * Called when a WebSocket connection is closed.
+   * This hook is awaited if it returns a Promise. The session is removed from the
+   * sessions map before this hook is called.
+   */
+  onDisconnect?(ctx: RoomContext<TMeta, E>): void | Promise<void>;
+  /**
+   * Called when a message is received from a connection.
+   * This hook is awaited if it returns a Promise. The actor will not process
+   * other messages from this connection until this hook completes.
+   *
+   * **Note:** If event handlers are registered via `eventEmitter`, they take priority.
+   * This hook is used as a fallback when no matching event handler is found.
+   */
+  onMessage?(ctx: MessageContext<TMeta, E>, frame: MessageFrame): void | Promise<void>;
+  /**
+   * Called when an error occurs in a lifecycle hook.
+   * This hook is also awaited if it returns a Promise.
+   */
+  onError?(error: Error, ctx: RoomContext<TMeta, E>): void | Promise<void>;
+  /**
+   * Called after actor wakes from hibernation and sessions are restored.
+   * This hook is awaited if it returns a Promise. It is called even if some
+   * sessions failed to restore, allowing you to handle partial restoration scenarios.
+   */
+  onHibernationRestore?(actor: VeraniActor<TMeta, E>): void | Promise<void>;
+  /**
+   * Event emitter for socket.io-like event handling.
+   * If provided, event handlers registered here will be called for matching message types.
+   * If not provided, a default event emitter will be created.
+   */
+  eventEmitter?: RoomEventEmitter<TMeta, E>;
+  /**
+   * Static handler storage that persists across hibernation.
+   * Handlers registered via room.on() are stored here and rebuilt in onInit.
+   * @internal
+   */
+  _staticHandlers?: Map<string, Set<EventHandler<TMeta, E>>>;
+}
+//#endregion
+//#region src/actor/actor-runtime.d.ts
+/**
+ * Return type for createActorHandler - represents an Actor class constructor
+ */
+type ActorHandlerClass<E = unknown> = {
+  new (state: any, env: E): Actor<E>;
+  get(id: string): ActorStub;
+  configuration(request?: Request): ActorConfiguration;
+};
+/**
+ * Creates an Actor handler from a room definition
+ * @param room - The room definition with lifecycle hooks
+ * @returns Actor class for Cloudflare Workers (extends DurableObject)
+ */
+declare function createActorHandler<TMeta extends ConnectionMeta = ConnectionMeta, E = unknown>(room: RoomDefinition<TMeta, E>): ActorHandlerClass<E>;
+//#endregion
+export { EventHandler as a, RoomDefinition as c, BroadcastOptions as i, RpcBroadcastOptions as l, createActorHandler as n, MessageContext as o, ActorStub as r, RoomContext as s, ActorHandlerClass as t, VeraniActor as u };

package/dist/actor-runtime-PyNnwtah.mjs

@@ -0,0 +1 @@
+import{a as decodeFrame$1,n as encodeFrame$1}from"./encode-BEipaz10.mjs";import{Actor}from"@cloudflare/actors";var RoomEventEmitterImpl=class{constructor(){this.handlers=new Map}on(e,w){this.handlers.has(e)||this.handlers.set(e,new Set),this.handlers.get(e).add(w)}off(e,w){let T=this.handlers.get(e);T&&(w?(T.delete(w),T.size===0&&this.handlers.delete(e)):this.handlers.delete(e))}async emit(e,w,T){let E=this.handlers.get(e);if(E&&E.size>0){let e=[];for(let D of E)try{let E=D(w,T);E instanceof Promise&&e.push(E)}catch{}await Promise.all(e)}let D=this.handlers.get(`*`);if(D&&D.size>0){let e=[];for(let E of D)try{let D=E(w,T);D instanceof Promise&&e.push(D)}catch{}await Promise.all(e)}}hasHandlers(e){return this.handlers.has(e)&&this.handlers.get(e).size>0||this.handlers.has(`*`)&&this.handlers.get(`*`).size>0}getEventNames(){return Array.from(this.handlers.keys())}rebuildHandlers(e){this.handlers.clear();for(let[w,T]of e.entries())this.handlers.set(w,new Set(T))}};function createRoomEventEmitter(){return new RoomEventEmitterImpl}function defaultExtractMeta(e){let w=crypto.randomUUID(),T=crypto.randomUUID(),E=new URL(e.url).searchParams.get(`channels`);return{userId:w,clientId:T,channels:E?E.split(`,`).map(e=>e.trim()).filter(Boolean):[`default`]}}function defineRoom(e){let w=e.eventEmitter||createRoomEventEmitter(),T=e._staticHandlers||new Map;return{name:e.name,websocketPath:e.websocketPath,extractMeta:e.extractMeta||(e=>defaultExtractMeta(e)),onConnect:e.onConnect,onDisconnect:e.onDisconnect,onMessage:e.onMessage,onError:e.onError,onHibernationRestore:e.onHibernationRestore,eventEmitter:w,_staticHandlers:T,on(e,E){w.on(e,E),T.has(e)||T.set(e,new Set),T.get(e).add(E)},off(e,E){w.off(e,E);let D=T.get(e);D&&(E?(D.delete(E),D.size===0&&T.delete(e)):T.delete(e))}}}function cleanupStaleSessions(e){let w=0,T=[];for(let[w,E]of e.entries())w.readyState!==WebSocket.OPEN&&T.push(w);for(let E of T)e.delete(E),w++;return w}function decodeFrame(w){return decodeFrame$1(w)??{type:`invalid`}}function encodeFrame(e){return encodeFrame$1(e)}function broadcast(e,w,T,E){let D=0,O=encodeFrame({type:`event`,channel:w,data:T}),k=[];for(let{ws:T,meta:A}of e.values())if(A.channels.includes(w)&&!(E?.except&&T===E.except)&&!(E?.userIds&&!E.userIds.includes(A.userId))&&!(E?.clientIds&&!E.clientIds.includes(A.clientId))){if(T.readyState!==WebSocket.OPEN){k.push(T);continue}try{T.send(O),D++}catch{k.push(T)}}for(let w of k)e.delete(w);return k.length,D}function sendToUser(e,w,T,E){let D=0,O=encodeFrame({type:`event`,channel:T,data:E}),k=[];for(let{ws:E,meta:A}of e.values())if(A.userId===w&&A.channels.includes(T)){if(E.readyState!==WebSocket.OPEN){k.push(E);continue}try{E.send(O),D++}catch{k.push(E)}}for(let w of k)e.delete(w);return k.length,D}function getSessionCount(e){return e.size}function getConnectedUserIds(e){let w=new Set;for(let{meta:T}of e.values())w.add(T.userId);return Array.from(w)}function getUserSessions(e,w){let T=[];for(let{ws:E,meta:D}of e.values())D.userId===w&&T.push(E);return T}function getStorage(e){return e.storage}function sanitizeToClassName(e){return e.replace(/^\/+/,``).split(/[-_\/\s]+/).map(e=>e.replace(/[^a-zA-Z0-9]/g,``)).filter(e=>e.length>0).map(e=>e.charAt(0).toUpperCase()+e.slice(1).toLowerCase()).join(``)||`VeraniActor`}function createConfiguration(e){return function(w){return{locationHint:`me`,sockets:{upgradePath:e.websocketPath}}}}function isValidConnectionMeta(e){return!(!e||typeof e!=`object`||typeof e.userId!=`string`||!e.userId||typeof e.clientId!=`string`||!e.clientId||!Array.isArray(e.channels)||!e.channels.every(e=>typeof e==`string`))}function storeAttachment(e,w){e.serializeAttachment(w)}function restoreSessions(e){let w=0,T=0;for(let E of e.ctx.getWebSockets()){if(E.readyState!==WebSocket.OPEN){T++;continue}let D=E.deserializeAttachment();if(!D){T++;continue}if(!isValidConnectionMeta(D)){T++;continue}e.sessions.set(E,{ws:E,meta:D}),w++}}async function onInit(e,w){if(w.eventEmitter&&w._staticHandlers)try{w.eventEmitter.rebuildHandlers(w._staticHandlers)}catch{}try{restoreSessions(e)}catch{}if(w.onHibernationRestore&&e.sessions.size>0)try{await w.onHibernationRestore(e)}catch{}else w.onHibernationRestore&&e.sessions.size}function createUserEmitBuilder(e,w,T){return{emit(E,D){return sendToUser(w,e,T,{type:E,...D})}}}function createChannelEmitBuilder(e,w,T){return{emit(E,D){return broadcast(w,e,{type:E,...D},T)}}}function createSocketEmit(e){let w=e.meta.channels[0]||`default`;return{emit(T,E){if(e.ws.readyState===WebSocket.OPEN)try{let D={type:`event`,channel:w,data:{type:T,...E}};e.ws.send(encodeFrame(D))}catch{}},to(T){return e.meta.channels.includes(T)?createChannelEmitBuilder(T,e.actor.sessions,{except:e.ws}):createUserEmitBuilder(T,e.actor.sessions,w)}}}function createActorEmit(e){return{emit(w,T){let E={type:w,...T};return broadcast(e.sessions,`default`,E)},to(w){return createChannelEmitBuilder(w,e.sessions)}}}async function onWebSocketConnect(e,w,T,E){let D;try{D=w.extractMeta?await w.extractMeta(E):{userId:`anonymous`,clientId:crypto.randomUUID(),channels:[`default`]},storeAttachment(T,D);let O={actor:e,ws:T,meta:D,frame:{type:`connect`}};if(w.onConnect){let E={actor:e,ws:T,meta:D,emit:createSocketEmit(O)};await w.onConnect(E)}e.sessions.set(T,{ws:T,meta:D})}catch(E){if(w.onError&&D)try{let O={actor:e,ws:T,meta:D,frame:{type:`error`}};await w.onError(E,{actor:e,ws:T,meta:D,emit:createSocketEmit(O)})}catch{}T.close(1011,`Internal server error`)}}async function onWebSocketMessage(e,w,T,E){let D;try{let O=decodeFrame(E);if(O&&O.type===`ping`){if(T.readyState===WebSocket.OPEN)try{T.send(encodeFrame({type:`pong`}))}catch{}return}if(!O||O.type===`invalid`||(D=e.sessions.get(T),!D))return;let k={actor:e,ws:T,meta:D.meta,frame:O,emit:createSocketEmit({actor:e,ws:T,meta:D.meta,frame:O})},A=w.eventEmitter;A&&A.hasHandlers&&A.hasHandlers(O.type)?await A.emit(O.type,k,O.data||{}):w.onMessage&&await w.onMessage(k,O)}catch(E){if(w.onError&&D)try{await w.onError(E,{actor:e,ws:T,meta:D.meta,emit:createSocketEmit({actor:e,ws:T,meta:D.meta,frame:{type:`error`}})})}catch{}}}async function onWebSocketDisconnect(e,w,T){try{let E=e.sessions.get(T);if(e.sessions.delete(T),E&&w.onDisconnect){let D={actor:e,ws:T,meta:E.meta,frame:{type:`disconnect`}},O={actor:e,ws:T,meta:E.meta,emit:createSocketEmit(D)};await w.onDisconnect(O)}}catch{}}function createFetch(e,w){return async function(T){let E=new URL(T.url),D=T.headers.get(`Upgrade`);return E.pathname===e.websocketPath&&D===`websocket`&&await w.shouldUpgradeWebSocket(T)?w.onWebSocketUpgrade(T):w.onRequest(T)}}function createActorHandler(e){let w=sanitizeToClassName(e.name||e.websocketPath||`VeraniActor`);class E extends Actor{constructor(...w){super(...w),this.sessions=new Map,this.emit=createActorEmit(this),this.fetch=createFetch(e,this)}static{this.configuration=createConfiguration(e)}async shouldUpgradeWebSocket(e){return!0}async onInit(){await onInit(this,e)}async onWebSocketConnect(w,T){await onWebSocketConnect(this,e,w,T)}async onWebSocketMessage(w,T){await onWebSocketMessage(this,e,w,T)}async onWebSocketDisconnect(w){await onWebSocketDisconnect(this,e,w)}cleanupStaleSessions(){return cleanupStaleSessions(this.sessions)}broadcast(e,w,T){return broadcast(this.sessions,e,w,T)}getSessionCount(){return getSessionCount(this.sessions)}getConnectedUserIds(){return getConnectedUserIds(this.sessions)}getUserSessions(e){return getUserSessions(this.sessions,e)}sendToUser(e,w,T){return sendToUser(this.sessions,e,w,T)}emitToChannel(e,w,T){let E={type:w,...T};return broadcast(this.sessions,e,E)}emitToUser(e,w,T){let E=encodeFrame({type:`event`,channel:`default`,data:{type:w,...T}}),D=0,O=[];for(let{ws:w,meta:T}of this.sessions.values())if(T.userId===e){if(w.readyState!==WebSocket.OPEN){O.push(w);continue}try{w.send(E),D++}catch{O.push(w)}}for(let e of O)this.sessions.delete(e);return D}getStorage(){return getStorage(this.ctx)}}return Object.defineProperty(E,`name`,{value:w,writable:!1,configurable:!0}),E}export{defineRoom as i,restoreSessions as n,storeAttachment as r,createActorHandler as t};