@dotdo/do 0.1.0

package/dist/rpc/server.d.ts

@@ -0,0 +1,380 @@
+/**
+ * CapnWeb RPC Server
+ *
+ * Handles both WebSocket and HTTP transports for RPC communication.
+ * Implements Cloudflare Durable Object WebSocket hibernation for 95% cost savings.
+ *
+ * @module rpc/server
+ *
+ * @example
+ * ```typescript
+ * import { RPCServer } from 'do/rpc/server'
+ * import { MethodRegistry } from 'do/rpc/methods'
+ *
+ * export class MyDurableObject {
+ *   private rpc: RPCServer
+ *
+ *   constructor(state: DurableObjectState, env: Env) {
+ *     const registry = new MethodRegistry()
+ *     // Register your methods...
+ *
+ *     this.rpc = new RPCServer(state, env, registry)
+ *   }
+ *
+ *   async fetch(request: Request): Promise<Response> {
+ *     return this.rpc.handleRequest(request)
+ *   }
+ *
+ *   // Hibernation handlers
+ *   async webSocketMessage(ws: WebSocket, message: string | ArrayBuffer) {
+ *     return this.rpc.handleWebSocketMessage(ws, message)
+ *   }
+ *
+ *   async webSocketClose(ws: WebSocket, code: number, reason: string) {
+ *     return this.rpc.handleWebSocketClose(ws, code, reason)
+ *   }
+ *
+ *   async webSocketError(ws: WebSocket, error: unknown) {
+ *     return this.rpc.handleWebSocketError(ws, error)
+ *   }
+ * }
+ * ```
+ */
+import type { RPCResponse, HibernationOptions } from '../types/rpc';
+import type { MethodContext } from './methods';
+/**
+ * RPC Server configuration options
+ */
+export interface RPCServerOptions {
+    /** Durable Object state */
+    state?: DurableObjectState;
+    /** Environment bindings */
+    env?: Record<string, unknown>;
+    /** Hibernation configuration */
+    hibernation?: HibernationOptions;
+    /** Whether to enable HTTP POST fallback (default: true) */
+    enableHttpFallback?: boolean;
+    /** Whether to enable GET /rpc/* routes (default: true) */
+    enableSchemaRoutes?: boolean;
+    /** CORS configuration */
+    cors?: CORSOptions;
+    /** Maximum batch size (default: 100) */
+    maxBatchSize?: number;
+    /** Request timeout in ms (default: 30000) */
+    requestTimeout?: number;
+    /** Method timeout in ms */
+    methodTimeout?: number;
+    /** Rate limit configuration */
+    rateLimit?: {
+        maxRequests: number;
+        windowMs: number;
+    };
+    /** Maximum payload size in bytes */
+    maxPayloadSize?: number;
+}
+/**
+ * CORS configuration
+ */
+export interface CORSOptions {
+    /** Allowed origins (default: '*') */
+    origins?: string | string[];
+    /** Allowed methods */
+    methods?: string[];
+    /** Allowed headers */
+    headers?: string[];
+    /** Max age for preflight cache */
+    maxAge?: number;
+}
+/**
+ * RPC Server for Durable Objects
+ *
+ * Handles incoming requests via both WebSocket and HTTP transports.
+ * WebSocket connections support hibernation for cost savings.
+ *
+ * @example
+ * ```typescript
+ * const server = new RPCServer(state, env, registry, {
+ *   hibernation: {
+ *     idleTimeout: 10000,
+ *     maxHibernationDuration: 86400000,
+ *   },
+ *   maxBatchSize: 50,
+ * })
+ * ```
+ */
+/**
+ * Method handler type for server-side registration
+ */
+export type RPCMethodHandler<TParams = unknown, TResult = unknown> = (params: TParams, ctx: MethodContext) => Promise<TResult>;
+/**
+ * RPC Handler type alias for compatibility
+ */
+export type RPCHandler = RPCMethodHandler;
+export declare class RPCServer {
+    private state?;
+    private env;
+    private options;
+    private connections;
+    private wsToId;
+    private methods;
+    private rateLimitState;
+    /**
+     * Create a new RPC server
+     *
+     * @param options - Server configuration including state, env, and registry
+     */
+    constructor(options?: RPCServerOptions);
+    /**
+     * Handle an incoming HTTP request
+     *
+     * Routes to appropriate handler based on method and path:
+     * - GET /rpc - Schema discovery
+     * - GET /rpc/* - Method documentation
+     * - POST / or POST /rpc - Execute RPC
+     * - WebSocket upgrade on /rpc
+     *
+     * @param request - Incoming HTTP request
+     * @returns HTTP response
+     *
+     * @example
+     * ```typescript
+     * async fetch(request: Request): Promise<Response> {
+     *   return this.rpc.handleRequest(request)
+     * }
+     * ```
+     */
+    handleRequest(request: Request): Promise<Response>;
+    /**
+     * Handle WebSocket upgrade request
+     *
+     * Creates a WebSocket pair and accepts the connection.
+     * The connection will hibernate after the idle timeout.
+     *
+     * @param request - WebSocket upgrade request
+     * @returns Response with WebSocket
+     */
+    handleWebSocketUpgrade(request: Request): Promise<Response>;
+    /**
+     * Handle HTTP POST RPC request
+     *
+     * @param request - HTTP POST request with JSON body
+     * @returns JSON response with RPC result
+     */
+    handleHttpRpc(request: Request): Promise<Response>;
+    /**
+     * Handle WebSocket message (hibernation callback)
+     *
+     * Called by Cloudflare when a message is received on a hibernated WebSocket.
+     *
+     * @param ws - WebSocket that received the message
+     * @param message - Message content (string or ArrayBuffer)
+     *
+     * @example
+     * ```typescript
+     * async webSocketMessage(ws: WebSocket, message: string | ArrayBuffer) {
+     *   return this.rpc.handleWebSocketMessage(ws, message)
+     * }
+     * ```
+     */
+    handleWebSocketMessage(ws: WebSocket, message: string | ArrayBuffer): Promise<void>;
+    /**
+     * Handle WebSocket close (hibernation callback)
+     *
+     * @param ws - WebSocket that was closed
+     * @param code - Close code
+     * @param reason - Close reason
+     */
+    handleWebSocketClose(ws: WebSocket, code: number, reason: string): Promise<void>;
+    /**
+     * Handle WebSocket error (hibernation callback)
+     *
+     * @param ws - WebSocket that errored
+     * @param error - Error that occurred
+     */
+    handleWebSocketError(ws: WebSocket, error: unknown): Promise<void>;
+    /**
+     * Get all active WebSocket connections
+     *
+     * @returns Array of connection states
+     */
+    getConnections(): Array<{
+        id: string;
+        status: string;
+        connectedAt: number;
+        hibernatedAt?: number;
+        lastMessageAt: number;
+        subscriptions: string[];
+        data?: Record<string, unknown>;
+    }>;
+    /**
+     * Get a specific connection by ID
+     *
+     * @param id - Connection ID
+     * @returns Connection state or undefined
+     */
+    getConnection(id: string): {
+        id: string;
+        status: string;
+        connectedAt: number;
+        hibernatedAt?: number;
+        lastMessageAt: number;
+        subscriptions: string[];
+        data?: Record<string, unknown>;
+    } | undefined;
+    /**
+     * Broadcast a message to all connected clients
+     *
+     * @param message - Message to broadcast
+     * @param filter - Optional filter function
+     */
+    broadcast(message: RPCResponse, filter?: (state: {
+        id: string;
+        status: string;
+        connectedAt: number;
+        lastMessageAt: number;
+        subscriptions: string[];
+        data?: Record<string, unknown>;
+    }) => boolean): Promise<void>;
+    /**
+     * Send a message to a specific connection
+     *
+     * @param connectionId - Target connection ID
+     * @param message - Message to send
+     */
+    send(connectionId: string, message: RPCResponse): Promise<void>;
+    /**
+     * Close a connection
+     *
+     * @param connectionId - Connection to close
+     * @param code - Close code
+     * @param reason - Close reason
+     */
+    closeConnection(connectionId: string, code?: number, reason?: string): Promise<void>;
+    /**
+     * Register a method handler
+     *
+     * @param name - Method name (e.g., 'do.things.list')
+     * @param handler - Handler function
+     */
+    registerMethod(name: string, handler: RPCMethodHandler): void;
+    /**
+     * Unregister a method handler
+     *
+     * @param name - Method name to unregister
+     */
+    unregisterMethod(name: string): void;
+    /**
+     * Get all registered method names
+     *
+     * @returns Array of method names
+     */
+    getMethods(): string[];
+    /**
+     * Subscribe a connection to a channel
+     *
+     * @param connectionId - Connection ID
+     * @param channel - Channel name
+     */
+    subscribe(connectionId: string, channel: string): Promise<void>;
+    /**
+     * Emit an event to all subscribers of a channel
+     *
+     * @param channel - Channel name
+     * @param data - Event data
+     */
+    emit(channel: string, data: unknown): Promise<void>;
+    /**
+     * Register a connection
+     *
+     * @param connectionId - Unique connection ID
+     * @param ws - WebSocket instance
+     */
+    registerConnection(connectionId: string, ws: WebSocket): void;
+    /**
+     * Set custom data for a connection
+     *
+     * @param connectionId - Connection ID
+     * @param data - Custom data to store
+     */
+    setConnectionData(connectionId: string, data: Record<string, unknown>): void;
+    /**
+     * Wake a hibernated connection
+     *
+     * @param ws - WebSocket instance
+     * @returns Connection ID
+     */
+    wakeConnection(ws: WebSocket): Promise<string>;
+    /**
+     * Handle an incoming HTTP request (convenience method)
+     *
+     * Alias for handleRequest for Worker fetch handler compatibility.
+     *
+     * @param request - Incoming HTTP request
+     * @returns HTTP response
+     */
+    fetch(request: Request): Promise<Response>;
+    /**
+     * Build method context from request
+     *
+     * @param request - Optional HTTP request
+     * @param ws - Optional WebSocket
+     * @returns Method context
+     */
+    private buildContext;
+    /**
+     * Handle CORS preflight request
+     *
+     * @returns CORS preflight response
+     */
+    private handleCors;
+    /**
+     * Add CORS headers to response
+     *
+     * @param response - Response to modify
+     * @returns Response with CORS headers
+     */
+    private addCorsHeaders;
+    /**
+     * Check if a request is a batch request
+     */
+    private isBatchRequest;
+    /**
+     * Execute a single RPC request
+     */
+    private executeRequest;
+    /**
+     * Set up idle timer for hibernation
+     */
+    private setupIdleTimer;
+    /**
+     * Reset idle timer on activity
+     */
+    private resetIdleTimer;
+    /**
+     * Hibernate a connection
+     */
+    private hibernateConnection;
+    /**
+     * Check if client is rate limited
+     */
+    private isRateLimited;
+}
+/**
+ * Create an RPC server with default configuration
+ *
+ * @param options - Server options (optional)
+ * @returns Configured RPC server
+ */
+export declare function createRPCServer(options?: RPCServerOptions): RPCServer;
+/**
+ * Create method context from Durable Object state
+ *
+ * Utility for building context outside of server class.
+ *
+ * @param state - Durable Object state
+ * @param env - Environment bindings
+ * @param meta - Optional metadata
+ * @returns Method context
+ */
+export declare function createMethodContext(state: DurableObjectState, env: Record<string, unknown>, meta?: Record<string, string>): MethodContext;
+//# sourceMappingURL=server.d.ts.map

package/dist/rpc/server.d.ts.map

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