dotdo 0.0.1 → 0.0.2

package/dist/objects/transport/rpc-server.js

@@ -0,0 +1,1536 @@
+/**
+ * RPC Server for DO - Legacy RPC Protocol Implementation
+ *
+ * @deprecated This module is deprecated in favor of the official capnweb library.
+ * Use the root endpoint (/) for Cap'n Web RPC via `objects/transport/capnweb-target.ts`.
+ *
+ * This module is kept for backward compatibility at the /rpc endpoint and supports:
+ * - JSON-RPC 2.0: Standard JSON-RPC protocol (still useful for many clients)
+ * - Chain RPC: Legacy chain-based format (deprecated, use capnweb)
+ * - Custom Cap'n Web emulation: (deprecated, use real capnweb at /)
+ *
+ * Migration guide:
+ * - For new clients: Use capnweb client connecting to root endpoint (/)
+ * - For JSON-RPC 2.0: Continue using /rpc endpoint
+ * - For Chain RPC: Migrate to capnweb protocol
+ *
+ * @see {@link ./capnweb-target.ts} for the new capnweb integration
+ */
+// Standard JSON-RPC error codes
+const JSON_RPC_ERRORS = {
+    PARSE_ERROR: { code: -32700, message: 'Parse error' },
+    INVALID_REQUEST: { code: -32600, message: 'Invalid Request' },
+    METHOD_NOT_FOUND: { code: -32601, message: 'Method not found' },
+    INVALID_PARAMS: { code: -32602, message: 'Invalid params' },
+    INTERNAL_ERROR: { code: -32603, message: 'Internal error' },
+};
+/**
+ * Chain execution error codes
+ */
+const CHAIN_ERRORS = {
+    INVALID_CHAIN: { code: 'INVALID_CHAIN', message: 'Chain must be a non-empty array' },
+    INVALID_STEP: { code: 'INVALID_STEP', message: 'Invalid step type' },
+    NOT_FOUND: { code: 'NOT_FOUND', message: 'Property not found' },
+    NOT_CALLABLE: { code: 'NOT_CALLABLE', message: 'Value is not a function' },
+    NOT_INDEXABLE: { code: 'NOT_INDEXABLE', message: 'Value is not an array' },
+    INDEX_OUT_OF_BOUNDS: { code: 'INDEX_OUT_OF_BOUNDS', message: 'Array index out of bounds' },
+    EXECUTION_ERROR: { code: 'EXECUTION_ERROR', message: 'Chain execution failed' },
+    BLOCKED_ACCESS: { code: 'BLOCKED_ACCESS', message: 'Access to this property is blocked' },
+};
+// ============================================================================
+// PROMISE STORE - Manages stored promise results for pipelining
+// ============================================================================
+class PromiseStore {
+    promises = new Map();
+    disposed = new Set();
+    depths = new Map();
+    set(id, value, depth = 0) {
+        this.promises.set(id, value);
+        this.depths.set(id, depth);
+    }
+    get(id) {
+        if (this.disposed.has(id)) {
+            throw { code: 'DISPOSED_REFERENCE', message: `Promise ${id} has been disposed` };
+        }
+        return this.promises.get(id);
+    }
+    getDepth(id) {
+        return this.depths.get(id) ?? 0;
+    }
+    has(id) {
+        return this.promises.has(id) && !this.disposed.has(id);
+    }
+    dispose(id) {
+        if (this.promises.has(id)) {
+            this.disposed.add(id);
+            this.promises.delete(id);
+            this.depths.delete(id);
+            return true;
+        }
+        return false;
+    }
+    isDisposed(id) {
+        return this.disposed.has(id);
+    }
+    clear() {
+        this.promises.clear();
+        this.disposed.clear();
+        this.depths.clear();
+    }
+}
+class SubscriptionManager {
+    subscriptions = new Map();
+    eventSubscriptions = new Map();
+    subscribe(event, callback) {
+        const id = `sub_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+        this.subscriptions.set(id, { id, event, callback });
+        if (!this.eventSubscriptions.has(event)) {
+            this.eventSubscriptions.set(event, new Set());
+        }
+        this.eventSubscriptions.get(event).add(id);
+        return id;
+    }
+    unsubscribe(subscriptionId) {
+        const sub = this.subscriptions.get(subscriptionId);
+        if (!sub)
+            return false;
+        this.subscriptions.delete(subscriptionId);
+        this.eventSubscriptions.get(sub.event)?.delete(subscriptionId);
+        return true;
+    }
+    emit(event, data) {
+        const subIds = this.eventSubscriptions.get(event);
+        if (!subIds)
+            return;
+        for (const id of subIds) {
+            const sub = this.subscriptions.get(id);
+            if (sub) {
+                try {
+                    sub.callback(data);
+                }
+                catch (error) {
+                    // Log callback errors so broken subscriptions can be detected
+                    console.error('[rpc] Subscription callback error:', {
+                        subscriptionId: id,
+                        event,
+                        error: error instanceof Error ? error.message : 'unknown',
+                        stack: error instanceof Error ? error.stack : undefined,
+                    });
+                }
+            }
+        }
+    }
+    clear() {
+        this.subscriptions.clear();
+        this.eventSubscriptions.clear();
+    }
+}
+// Default blocked methods - internal DO methods that should never be exposed
+const DEFAULT_BLOCKED_METHODS = new Set([
+    // Lifecycle methods
+    'initialize',
+    'fetch',
+    'handleFetch',
+    'alarm',
+    // Internal state
+    'db',
+    'ctx',
+    'storage',
+    'env',
+    // Private accessors
+    '_users',
+    '_posts',
+    '_things',
+    '_rels',
+    '_actions',
+    '_events',
+    '_search',
+    '_objects',
+    '_dlq',
+    '_typeCache',
+    '_eventHandlers',
+    '_scheduleHandlers',
+    '_scheduleManager',
+    '_currentActor',
+    '_stepCache',
+    // Constructor
+    'constructor',
+]);
+// ============================================================================
+// COLLECTION RPC PATTERN MATCHING
+// ============================================================================
+/**
+ * Valid collection methods
+ */
+const COLLECTION_METHODS = new Set(['create', 'update', 'delete', 'get', 'list', 'find']);
+/**
+ * Pattern for valid PascalCase noun names (no numbers, no special chars)
+ */
+const VALID_NOUN_PATTERN = /^[A-Z][a-zA-Z]*$/;
+/**
+ * Pattern for {Noun}.{method} format (exactly one dot)
+ * Noun must be PascalCase, method can be any valid identifier starting with lowercase
+ */
+const COLLECTION_RPC_PATTERN = /^([A-Z][a-zA-Z]*)\.([a-z][a-zA-Z]*)$/;
+/**
+ * Check if a method name looks like a collection RPC call
+ */
+function isCollectionRpcMethod(method) {
+    return method.includes('.') && !method.startsWith('_');
+}
+/**
+ * Parse a collection RPC method into noun and action
+ * Returns null if invalid format
+ */
+function parseCollectionRpcMethod(method) {
+    // Check for multiple dots (invalid)
+    if ((method.match(/\./g) || []).length !== 1) {
+        return null;
+    }
+    const match = method.match(COLLECTION_RPC_PATTERN);
+    if (!match)
+        return null;
+    const [, noun, action] = match;
+    return { noun, action };
+}
+/**
+ * Validate noun name
+ * @returns error message if invalid, null if valid
+ */
+function validateNounName(noun) {
+    if (!noun || noun.trim() === '') {
+        return 'Noun name cannot be empty';
+    }
+    if (!VALID_NOUN_PATTERN.test(noun)) {
+        return `Invalid noun '${noun}': must be PascalCase letters only`;
+    }
+    return null;
+}
+/**
+ * Validate collection method name
+ * @returns error message if invalid, null if valid
+ */
+function validateCollectionMethod(noun, method) {
+    if (!COLLECTION_METHODS.has(method)) {
+        return `Unknown method '${method}' on ${noun}. Valid methods: ${Array.from(COLLECTION_METHODS).join(', ')}`;
+    }
+    return null;
+}
+/**
+ * RPC Server class that wraps a DO instance
+ */
+export class RPCServer {
+    doInstance;
+    config;
+    exposedMethods;
+    blockedMethods;
+    sessions = new Map();
+    defaultHttpSession;
+    constructor(doInstance, config = {}) {
+        this.doInstance = doInstance;
+        this.config = {
+            maxPipelineDepth: config.maxPipelineDepth ?? 20,
+            ...config,
+        };
+        // Build blocked methods set
+        this.blockedMethods = new Set([
+            ...DEFAULT_BLOCKED_METHODS,
+            ...(config.blockedMethods ?? []),
+        ]);
+        // Build exposed methods set
+        this.exposedMethods = new Set();
+        if (config.exposedMethods && config.exposedMethods.length > 0) {
+            for (const method of config.exposedMethods) {
+                if (!this.blockedMethods.has(method)) {
+                    this.exposedMethods.add(method);
+                }
+            }
+        }
+        else {
+            // Auto-discover methods from the DO instance
+            this.discoverMethods();
+        }
+    }
+    /**
+     * Discover exposed methods from the DO instance
+     */
+    discoverMethods() {
+        // Get own property names from instance and prototype chain
+        const visited = new Set();
+        let obj = this.doInstance;
+        while (obj && obj !== Object.prototype) {
+            for (const key of Object.getOwnPropertyNames(obj)) {
+                if (visited.has(key))
+                    continue;
+                visited.add(key);
+                // Skip blocked methods
+                if (this.blockedMethods.has(key))
+                    continue;
+                // Skip private methods (starting with _)
+                if (key.startsWith('_'))
+                    continue;
+                // Skip getter/setter only properties
+                const descriptor = Object.getOwnPropertyDescriptor(obj, key);
+                if (descriptor && (descriptor.get || descriptor.set) && !descriptor.value) {
+                    continue;
+                }
+                // Check if it's a function
+                const value = this.doInstance[key];
+                if (typeof value === 'function') {
+                    this.exposedMethods.add(key);
+                }
+            }
+            obj = Object.getPrototypeOf(obj);
+        }
+    }
+    /**
+     * Get list of exposed methods
+     */
+    get methods() {
+        return Array.from(this.exposedMethods);
+    }
+    /**
+     * Check if a method is exposed
+     */
+    isRpcExposed(method) {
+        if (this.blockedMethods.has(method))
+            return false;
+        if (method.startsWith('_'))
+            return false;
+        return this.exposedMethods.has(method);
+    }
+    /**
+     * Check if a method requires authentication and return an error if auth is missing
+     */
+    checkMethodAuth(method, request) {
+        // Get the $auth config from the DO instance's constructor
+        const DOClass = this.doInstance.constructor;
+        const authConfig = DOClass.$auth?.[method];
+        if (!authConfig)
+            return null;
+        // If method is public, no auth needed
+        if (authConfig.public)
+            return null;
+        // If method requires auth, check for Authorization header
+        if (authConfig.requireAuth || authConfig.roles) {
+            const authHeader = request.headers.get('Authorization');
+            if (!authHeader || !authHeader.startsWith('Bearer ')) {
+                return {
+                    code: -32001, // Custom auth error code
+                    message: 'Authentication required',
+                };
+            }
+            // Basic token validation (could be extended to actually validate JWT)
+            const token = authHeader.slice(7);
+            if (!token || token.split('.').length !== 3) {
+                return {
+                    code: -32001,
+                    message: 'Invalid authentication token',
+                };
+            }
+        }
+        return null;
+    }
+    /**
+     * Handle collection RPC call pattern: {Noun}.{method}
+     * Routes to the DO's collection() method for typed data access.
+     *
+     * @param method - The method name (e.g., "Task.create")
+     * @param args - The resolved arguments
+     * @returns The result of the collection operation, or throws an error
+     */
+    async handleCollectionRpc(method, args) {
+        // Check if this looks like a collection RPC call
+        if (!isCollectionRpcMethod(method)) {
+            return null; // Not a collection RPC, let normal handling proceed
+        }
+        // Handle multiple dots (invalid pattern)
+        if ((method.match(/\./g) || []).length !== 1) {
+            throw { code: 'INVALID_METHOD', message: `Invalid method pattern: ${method}` };
+        }
+        // Parse the method
+        const parsed = parseCollectionRpcMethod(method);
+        // Check for invalid noun pattern (lowercase, special chars, etc.)
+        if (!parsed) {
+            // Extract noun part for better error message
+            const [nounPart] = method.split('.');
+            // Check if it's a lowercase noun issue
+            if (nounPart && /^[a-z]/.test(nounPart)) {
+                throw { code: 'INVALID_NOUN', message: `Invalid noun '${nounPart}': must start with uppercase letter` };
+            }
+            // Check for numbers or special chars
+            if (nounPart && !/^[A-Za-z]+$/.test(nounPart)) {
+                throw { code: 'INVALID_NOUN', message: `Invalid noun '${nounPart}': must contain only letters` };
+            }
+            // Empty noun
+            if (!nounPart || nounPart === '') {
+                throw { code: 'INVALID_NOUN', message: 'Noun name cannot be empty' };
+            }
+            throw { code: 'INVALID_METHOD', message: `Invalid method pattern: ${method}` };
+        }
+        const { noun, action } = parsed;
+        // Validate noun name
+        const nounError = validateNounName(noun);
+        if (nounError) {
+            throw { code: 'INVALID_NOUN', message: nounError };
+        }
+        // Validate collection method
+        const methodError = validateCollectionMethod(noun, action);
+        if (methodError) {
+            throw { code: 'UNKNOWN_METHOD', message: methodError };
+        }
+        // Get the collection method from the DO instance
+        // The collection method is protected, but we can access it via the instance
+        const collectionFn = this.doInstance['collection'];
+        if (typeof collectionFn !== 'function') {
+            // Fallback: the DO doesn't have a collection method, so we can't handle this
+            throw { code: 'NOT_SUPPORTED', message: 'This DO does not support collection operations' };
+        }
+        // Get the collection for this noun
+        const collection = collectionFn.call(this.doInstance, noun);
+        if (!collection || typeof collection !== 'object') {
+            throw { code: 'COLLECTION_ERROR', message: `Failed to get collection for '${noun}'` };
+        }
+        const actionFn = collection[action];
+        if (typeof actionFn !== 'function') {
+            throw { code: 'UNKNOWN_METHOD', message: `Method '${action}' not found on ${noun} collection` };
+        }
+        // Execute the collection method with the provided arguments
+        let result = await actionFn.apply(collection, args);
+        // For mutations (create, update, delete), ensure $rowid is included
+        if (action === 'create' || action === 'update' || action === 'delete') {
+            result = this.ensureRowidInResult(result, action);
+        }
+        return result;
+    }
+    /**
+     * Ensure $rowid is present in mutation results.
+     * If not present, generate a synthetic one for compatibility.
+     */
+    ensureRowidInResult(result, action) {
+        if (result === null || result === undefined) {
+            return result;
+        }
+        if (typeof result === 'object' && !Array.isArray(result)) {
+            const obj = result;
+            // If $rowid is already present, return as-is
+            if ('$rowid' in obj && typeof obj.$rowid === 'number') {
+                return result;
+            }
+            // For delete, also add 'deleted' flag if not present
+            if (action === 'delete') {
+                return {
+                    ...obj,
+                    deleted: obj.deleted ?? true,
+                    $rowid: obj.$rowid ?? this.generateSyntheticRowid(),
+                };
+            }
+            // For create/update, add $rowid if missing
+            return {
+                ...obj,
+                $rowid: this.generateSyntheticRowid(),
+            };
+        }
+        return result;
+    }
+    /**
+     * Generate a synthetic rowid for collection operations.
+     * This is used when the underlying collection doesn't return a rowid.
+     */
+    syntheticRowidCounter = 1;
+    generateSyntheticRowid() {
+        return this.syntheticRowidCounter++;
+    }
+    /**
+     * Create a new RPC session
+     */
+    createSession() {
+        const sessionId = `session_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+        const promiseStore = new PromiseStore();
+        const subscriptions = new SubscriptionManager();
+        const ctx = {
+            promiseStore,
+            subscriptions,
+            rootObject: this.doInstance,
+            sendNotification: () => { },
+            sessionId,
+            exposedMethods: this.exposedMethods,
+            blockedMethods: this.blockedMethods,
+        };
+        this.sessions.set(sessionId, ctx);
+        return ctx;
+    }
+    /**
+     * Get or create a session
+     */
+    getSession(sessionId) {
+        if (sessionId && this.sessions.has(sessionId)) {
+            return this.sessions.get(sessionId);
+        }
+        return this.createSession();
+    }
+    /**
+     * Get the default HTTP session (persists across HTTP requests to same DO)
+     */
+    getDefaultHttpSession() {
+        if (!this.defaultHttpSession) {
+            this.defaultHttpSession = this.createSession();
+        }
+        return this.defaultHttpSession;
+    }
+    /**
+     * Clean up a session
+     */
+    cleanupSession(sessionId) {
+        const ctx = this.sessions.get(sessionId);
+        if (ctx) {
+            ctx.promiseStore.clear();
+            ctx.subscriptions.clear();
+            this.sessions.delete(sessionId);
+        }
+    }
+    /**
+     * Handle an HTTP RPC request
+     */
+    async handleRpcRequest(request) {
+        // Use persistent session for HTTP requests (state persists across requests to same DO)
+        const ctx = this.getDefaultHttpSession();
+        // Parse request body
+        let body;
+        try {
+            body = await request.json();
+        }
+        catch {
+            return Response.json({
+                id: '',
+                type: 'error',
+                error: { code: 'PARSE_ERROR', message: 'Invalid JSON' },
+            }, { status: 400, headers: { 'Content-Type': 'application/json' } });
+        }
+        // Check if JSON-RPC 2.0
+        if (this.isJSONRPCRequest(body)) {
+            // Check if the method requires auth
+            const authError = this.checkMethodAuth(body.method, request);
+            if (authError) {
+                return Response.json({
+                    jsonrpc: '2.0',
+                    error: authError,
+                    id: body.id ?? null,
+                }, { status: 401, headers: { 'Content-Type': 'application/json' } });
+            }
+            const response = await this.handleJSONRPCRequest(body, ctx);
+            if (!response) {
+                // Notification - no response
+                return new Response(null, { status: 204 });
+            }
+            return Response.json(response, { headers: { 'Content-Type': 'application/json' } });
+        }
+        // Check if JSON-RPC 2.0 batch
+        if (this.isJSONRPCBatch(body)) {
+            const responses = [];
+            for (const req of body) {
+                const response = await this.handleJSONRPCRequest(req, ctx);
+                if (response) {
+                    responses.push(response);
+                }
+            }
+            if (responses.length === 0) {
+                return new Response(null, { status: 204 });
+            }
+            return Response.json(responses, { headers: { 'Content-Type': 'application/json' } });
+        }
+        // Cap'n Web RPC
+        if (this.isCapnWebRequest(body)) {
+            const response = await this.executeCapnWebRequest(body, ctx);
+            return Response.json(response, { headers: { 'Content-Type': 'application/json' } });
+        }
+        // Chain RPC - Check for chain request format
+        if (this.isChainRequest(body)) {
+            // Get the WorkflowContext if available on the DO instance
+            const workflowContext = this.doInstance.$;
+            return this.executeChainRequest(body, workflowContext);
+        }
+        // Check for invalid chain format (has 'chain' property but it's not an array)
+        if (body !== null && typeof body === 'object' && 'chain' in body) {
+            return Response.json({
+                error: { message: 'Chain must be a non-empty array', code: 'INVALID_CHAIN' },
+            }, { status: 400, headers: { 'Content-Type': 'application/json' } });
+        }
+        return Response.json({
+            id: '',
+            type: 'error',
+            error: { code: 'INVALID_REQUEST', message: 'Unknown request format' },
+        }, { status: 400, headers: { 'Content-Type': 'application/json' } });
+    }
+    /**
+     * Handle WebSocket RPC connection
+     */
+    handleWebSocketRpc() {
+        const pair = new WebSocketPair();
+        const [client, server] = Object.values(pair);
+        const ctx = this.createSession();
+        // Set up notification sender
+        ctx.sendNotification = (method, params) => {
+            try {
+                server.send(JSON.stringify({
+                    jsonrpc: '2.0',
+                    method,
+                    params,
+                }));
+            }
+            catch (error) {
+                // Log send errors for debugging WebSocket connection issues
+                console.debug('[rpc] WebSocket notification send failed:', {
+                    method,
+                    readyState: server.readyState,
+                    error: error instanceof Error ? error.message : 'unknown',
+                });
+            }
+        };
+        server.accept();
+        // Send connection acknowledgment
+        server.send(JSON.stringify({
+            type: 'connected',
+            sessionId: ctx.sessionId,
+        }));
+        server.addEventListener('message', async (event) => {
+            const rawData = event.data;
+            // Handle binary data
+            if (rawData instanceof ArrayBuffer) {
+                server.send(JSON.stringify({
+                    type: 'binary_received',
+                    size: rawData.byteLength,
+                }));
+                return;
+            }
+            // Parse message
+            let data;
+            try {
+                data = JSON.parse(rawData);
+            }
+            catch {
+                server.send(JSON.stringify({
+                    jsonrpc: '2.0',
+                    error: JSON_RPC_ERRORS.PARSE_ERROR,
+                    id: null,
+                }));
+                return;
+            }
+            // Handle JSON-RPC 2.0 batch
+            if (this.isJSONRPCBatch(data)) {
+                const responses = [];
+                for (const req of data) {
+                    const response = await this.handleJSONRPCRequest(req, ctx);
+                    if (response) {
+                        responses.push(response);
+                    }
+                }
+                if (responses.length > 0) {
+                    server.send(JSON.stringify(responses));
+                }
+                return;
+            }
+            // Handle single JSON-RPC 2.0 request
+            if (this.isJSONRPCRequest(data)) {
+                const response = await this.handleJSONRPCRequest(data, ctx);
+                if (response) {
+                    server.send(JSON.stringify(response));
+                }
+                return;
+            }
+            // Handle Cap'n Web request
+            if (this.isCapnWebRequest(data)) {
+                const response = await this.executeCapnWebRequest(data, ctx);
+                server.send(JSON.stringify(response));
+                return;
+            }
+            // Invalid request format
+            server.send(JSON.stringify({
+                jsonrpc: '2.0',
+                error: JSON_RPC_ERRORS.INVALID_REQUEST,
+                id: null,
+            }));
+        });
+        server.addEventListener('close', () => {
+            this.cleanupSession(ctx.sessionId);
+        });
+        server.addEventListener('error', () => {
+            this.cleanupSession(ctx.sessionId);
+            server.close();
+        });
+        return new Response(null, {
+            status: 101,
+            webSocket: client,
+        });
+    }
+    // ============================================================================
+    // PROTOCOL DETECTION
+    // ============================================================================
+    isJSONRPCRequest(data) {
+        return (data !== null &&
+            typeof data === 'object' &&
+            'jsonrpc' in data &&
+            data.jsonrpc === '2.0');
+    }
+    isJSONRPCBatch(data) {
+        return (Array.isArray(data) &&
+            data.length > 0 &&
+            data.every((item) => this.isJSONRPCRequest(item)));
+    }
+    isCapnWebRequest(data) {
+        return (data !== null &&
+            typeof data === 'object' &&
+            'type' in data &&
+            typeof data.type === 'string');
+    }
+    /**
+     * Check if request is a Chain RPC request
+     */
+    isChainRequest(data) {
+        return (data !== null &&
+            typeof data === 'object' &&
+            'chain' in data &&
+            Array.isArray(data.chain));
+    }
+    // ============================================================================
+    // CHAIN RPC HANDLER
+    // ============================================================================
+    /**
+     * Execute a chain-based RPC request.
+     *
+     * The chain starts from the root object (the DO instance) and executes
+     * each step in sequence. If a WorkflowContext ($) is available, the chain
+     * can access it via the 'chain' starting from root.
+     *
+     * @param request - The chain RPC request
+     * @param workflowContext - Optional WorkflowContext to use as $ root
+     * @returns Response with data or error
+     */
+    async executeChainRequest(request, workflowContext) {
+        const { chain } = request;
+        // Validate chain
+        if (!Array.isArray(chain) || chain.length === 0) {
+            return Response.json({
+                error: { message: 'Chain must be a non-empty array', code: 'INVALID_CHAIN' },
+            }, { status: 400, headers: { 'Content-Type': 'application/json' } });
+        }
+        try {
+            const result = await this.executeChain(chain, workflowContext);
+            return Response.json({
+                result,
+            }, { headers: { 'Content-Type': 'application/json' } });
+        }
+        catch (error) {
+            const chainError = error;
+            const status = chainError.status ?? 400;
+            return Response.json({
+                error: {
+                    message: chainError.message ?? 'Chain execution failed',
+                    code: chainError.code ?? 'EXECUTION_ERROR',
+                },
+            }, { status, headers: { 'Content-Type': 'application/json' } });
+        }
+    }
+    /**
+     * Execute a chain of steps starting from the DO instance.
+     *
+     * The chain can access:
+     * - DO instance properties and methods directly (e.g., config, getStatus)
+     * - WorkflowContext via the $ property (e.g., $.things, $.on)
+     *
+     * @param chain - Array of chain steps
+     * @param workflowContext - Optional WorkflowContext accessible via $ property
+     * @returns The final result of the chain
+     */
+    async executeChain(chain, workflowContext) {
+        // Always start from the DO instance
+        // WorkflowContext ($) is accessible as a property of the instance
+        let current = this.doInstance;
+        // If the first step is accessing '$', use the WorkflowContext directly
+        if (chain.length > 0 && chain[0].type === 'property' && chain[0].key === '$' && workflowContext) {
+            current = workflowContext;
+            chain = chain.slice(1); // Skip the '$' step
+        }
+        for (let i = 0; i < chain.length; i++) {
+            const step = chain[i];
+            switch (step.type) {
+                case 'property': {
+                    // Validate the step
+                    if (typeof step.key !== 'string') {
+                        throw { code: 'INVALID_STEP', message: 'Property step requires a string key', status: 400 };
+                    }
+                    // Block access to private/internal properties
+                    if (step.key.startsWith('_')) {
+                        throw { code: 'BLOCKED_ACCESS', message: `Access to private property '${step.key}' is blocked`, status: 404 };
+                    }
+                    // Block access to internal DO methods on first step (from root)
+                    if (i === 0 && this.blockedMethods.has(step.key)) {
+                        throw { code: 'BLOCKED_ACCESS', message: `Access to '${step.key}' is blocked`, status: 404 };
+                    }
+                    if (current === null || current === undefined) {
+                        throw { code: 'NOT_FOUND', message: `Cannot access property '${step.key}' of ${current}`, status: 404 };
+                    }
+                    // For objects with a Proxy get trap (like WorkflowContext), accessing the property triggers the proxy
+                    const value = current[step.key];
+                    if (value === undefined && !(step.key in current)) {
+                        throw { code: 'NOT_FOUND', message: `Property '${step.key}' not found`, status: 404 };
+                    }
+                    current = value;
+                    break;
+                }
+                case 'call': {
+                    const args = step.args ?? [];
+                    // SDK Combined Format: { type: 'call', key: 'methodName', args: [...] }
+                    // This combines property access and method call in one step.
+                    // When 'key' is present, first access the property, then call it.
+                    const combinedKey = step.key;
+                    if (combinedKey !== undefined) {
+                        // Combined call step - first access the property, then call it
+                        if (typeof combinedKey !== 'string') {
+                            throw { code: 'INVALID_STEP', message: 'Combined call step requires a string key', status: 400 };
+                        }
+                        // Block access to private methods
+                        if (combinedKey.startsWith('_')) {
+                            throw { code: 'BLOCKED_ACCESS', message: `Access to private method '${combinedKey}' is blocked`, status: 404 };
+                        }
+                        // Block access to internal DO methods on first step (from root)
+                        if (i === 0 && this.blockedMethods.has(combinedKey)) {
+                            throw { code: 'BLOCKED_ACCESS', message: `Access to '${combinedKey}' is blocked`, status: 404 };
+                        }
+                        if (current === null || current === undefined) {
+                            throw { code: 'NOT_FOUND', message: `Cannot access method '${combinedKey}' of ${current}`, status: 404 };
+                        }
+                        // Access the method
+                        const method = current[combinedKey];
+                        if (method === undefined && !(combinedKey in current)) {
+                            throw { code: 'NOT_FOUND', message: `Method '${combinedKey}' not found`, status: 404 };
+                        }
+                        if (typeof method !== 'function') {
+                            throw { code: 'NOT_CALLABLE', message: `'${combinedKey}' is not a function`, status: 400 };
+                        }
+                        // Execute the method with 'current' as 'this' context
+                        const result = method.apply(current, args);
+                        // Await if it's a promise
+                        current = result instanceof Promise ? await result : result;
+                    }
+                    else {
+                        // Traditional call step - 'current' should already be a function
+                        if (typeof current !== 'function') {
+                            throw { code: 'NOT_CALLABLE', message: 'Value is not a function, cannot call', status: 400 };
+                        }
+                        // Find the 'this' context for the call
+                        // Look back for the last property access to get the parent object
+                        let thisContext = this.doInstance;
+                        if (i > 0) {
+                            // Re-execute chain up to the previous step to get the parent context
+                            const prevChain = chain.slice(0, i - 1);
+                            if (prevChain.length > 0) {
+                                thisContext = await this.executeChain(prevChain, workflowContext);
+                            }
+                            else if (i === 1) {
+                                // First call after property access - use root
+                                thisContext = workflowContext ?? this.doInstance;
+                            }
+                        }
+                        // Execute the function
+                        const result = current.apply(thisContext, args);
+                        // Await if it's a promise
+                        current = result instanceof Promise ? await result : result;
+                    }
+                    break;
+                }
+                case 'index': {
+                    if (typeof step.index !== 'number') {
+                        throw { code: 'INVALID_STEP', message: 'Index step requires a numeric index', status: 400 };
+                    }
+                    if (!Array.isArray(current)) {
+                        throw { code: 'NOT_INDEXABLE', message: 'Value is not an array, cannot use index access', status: 400 };
+                    }
+                    if (step.index < 0 || step.index >= current.length) {
+                        throw {
+                            code: 'INDEX_OUT_OF_BOUNDS',
+                            message: `Index ${step.index} is out of bounds (array length: ${current.length})`,
+                            status: 404
+                        };
+                    }
+                    current = current[step.index];
+                    break;
+                }
+                default: {
+                    throw {
+                        code: 'INVALID_STEP',
+                        message: `Invalid step type: ${step.type}`,
+                        status: 400
+                    };
+                }
+            }
+        }
+        return current;
+    }
+    // ============================================================================
+    // JSON-RPC 2.0 HANDLER
+    // ============================================================================
+    async handleJSONRPCRequest(request, ctx) {
+        const { method, params, id } = request;
+        const isNotification = id === undefined;
+        try {
+            // Handle subscription methods
+            if (method === 'subscribe') {
+                const p = params;
+                const subscriptionId = ctx.subscriptions.subscribe(p.event, (data) => {
+                    ctx.sendNotification(p.event, data);
+                });
+                if (isNotification)
+                    return null;
+                return {
+                    jsonrpc: '2.0',
+                    result: { subscriptionId },
+                    id: id ?? null,
+                };
+            }
+            if (method === 'unsubscribe') {
+                const p = params;
+                const success = ctx.subscriptions.unsubscribe(p.subscriptionId);
+                if (isNotification)
+                    return null;
+                return {
+                    jsonrpc: '2.0',
+                    result: { success },
+                    id: id ?? null,
+                };
+            }
+            // Handle triggerEvent (for testing)
+            if (method === 'triggerEvent') {
+                const p = params;
+                ctx.subscriptions.emit(p.event, p.data);
+                if (isNotification)
+                    return null;
+                return {
+                    jsonrpc: '2.0',
+                    result: { triggered: true },
+                    id: id ?? null,
+                };
+            }
+            // Check for collection RPC pattern: {Noun}.{method}
+            if (isCollectionRpcMethod(method)) {
+                // Convert params to args array
+                const args = params === undefined
+                    ? []
+                    : Array.isArray(params)
+                        ? params
+                        : [params];
+                const result = await this.handleCollectionRpc(method, args);
+                if (isNotification)
+                    return null;
+                return {
+                    jsonrpc: '2.0',
+                    result,
+                    id: id ?? null,
+                };
+            }
+            // Check if method exists and is exposed
+            if (!this.isRpcExposed(method)) {
+                if (isNotification)
+                    return null;
+                return {
+                    jsonrpc: '2.0',
+                    error: { ...JSON_RPC_ERRORS.METHOD_NOT_FOUND, message: `Method '${method}' not found` },
+                    id: id ?? null,
+                };
+            }
+            const methodFn = ctx.rootObject[method];
+            if (typeof methodFn !== 'function') {
+                if (isNotification)
+                    return null;
+                return {
+                    jsonrpc: '2.0',
+                    error: { ...JSON_RPC_ERRORS.METHOD_NOT_FOUND, message: `Method '${method}' not found` },
+                    id: id ?? null,
+                };
+            }
+            // Execute method
+            let result;
+            if (params === undefined) {
+                result = await methodFn.call(ctx.rootObject);
+            }
+            else if (Array.isArray(params)) {
+                result = await methodFn.apply(ctx.rootObject, params);
+            }
+            else if (typeof params === 'object' && params !== null) {
+                // Named parameters - try to extract positional args from object
+                const namedParams = params;
+                const paramNames = this.extractParamNames(methodFn);
+                if (paramNames.length > 0 && paramNames.every((name) => name in namedParams)) {
+                    // All parameter names found in the object - convert to positional args
+                    const args = paramNames.map((name) => namedParams[name]);
+                    result = await methodFn.apply(ctx.rootObject, args);
+                }
+                else {
+                    // Fall back to passing the object as a single argument
+                    result = await methodFn.call(ctx.rootObject, params);
+                }
+            }
+            else {
+                result = await methodFn.call(ctx.rootObject, params);
+            }
+            if (isNotification)
+                return null;
+            return {
+                jsonrpc: '2.0',
+                result,
+                id: id ?? null,
+            };
+        }
+        catch (error) {
+            if (isNotification)
+                return null;
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return {
+                jsonrpc: '2.0',
+                error: {
+                    code: JSON_RPC_ERRORS.INTERNAL_ERROR.code,
+                    message: errorMessage,
+                },
+                id: id ?? null,
+            };
+        }
+    }
+    // ============================================================================
+    // CAP'N WEB RPC HANDLER
+    // ============================================================================
+    async executeCapnWebRequest(request, ctx) {
+        switch (request.type) {
+            case 'call':
+            case 'batch':
+                return this.executeBatch(request, ctx);
+            case 'resolve':
+                return this.executeResolve(request, ctx);
+            case 'dispose':
+                return this.executeDispose(request, ctx);
+            default:
+                return {
+                    id: request.id,
+                    type: 'error',
+                    error: { code: 'INVALID_REQUEST', message: 'Unknown request type' },
+                };
+        }
+    }
+    async executeBatch(request, ctx) {
+        if (!request.calls || request.calls.length === 0) {
+            return {
+                id: request.id,
+                type: 'error',
+                error: { code: 'INVALID_REQUEST', message: 'No calls provided' },
+            };
+        }
+        const results = [];
+        for (const call of request.calls) {
+            const result = await this.executeCall(call, ctx);
+            results.push(result);
+        }
+        return {
+            id: request.id,
+            type: 'batch',
+            results,
+        };
+    }
+    async executeResolve(request, ctx) {
+        if (!request.resolve?.promiseId) {
+            return {
+                id: request.id,
+                type: 'error',
+                error: { code: 'INVALID_REQUEST', message: 'No promiseId provided' },
+            };
+        }
+        const promiseId = request.resolve.promiseId;
+        if (ctx.promiseStore.isDisposed(promiseId)) {
+            return {
+                id: request.id,
+                type: 'error',
+                error: { code: 'DISPOSED_REFERENCE', message: `Promise ${promiseId} has been disposed` },
+            };
+        }
+        if (!ctx.promiseStore.has(promiseId)) {
+            return {
+                id: request.id,
+                type: 'error',
+                error: { code: 'INVALID_PROMISE', message: `Promise ${promiseId} not found` },
+            };
+        }
+        const value = ctx.promiseStore.get(promiseId);
+        return {
+            id: request.id,
+            type: 'result',
+            results: [
+                {
+                    promiseId,
+                    type: 'value',
+                    value,
+                },
+            ],
+        };
+    }
+    async executeDispose(request, ctx) {
+        if (!request.dispose?.promiseIds) {
+            return {
+                id: request.id,
+                type: 'error',
+                error: { code: 'INVALID_REQUEST', message: 'No promiseIds provided' },
+            };
+        }
+        for (const promiseId of request.dispose.promiseIds) {
+            ctx.promiseStore.dispose(promiseId);
+        }
+        return {
+            id: request.id,
+            type: 'result',
+            results: [],
+        };
+    }
+    async executeCall(call, ctx) {
+        // Calculate depth for this call (outside try for catch access)
+        let callDepth = 0;
+        try {
+            if (call.target.type === 'promise') {
+                const baseDepth = ctx.promiseStore.getDepth(call.target.promiseId);
+                callDepth = baseDepth + 1;
+                // Check max pipeline depth
+                const maxDepth = this.config.maxPipelineDepth ?? 20;
+                if (callDepth >= maxDepth) {
+                    throw { code: 'MAX_PIPELINE_DEPTH', message: `Pipeline depth ${callDepth} exceeds maximum ${maxDepth}` };
+                }
+            }
+            else if (call.target.type === 'property') {
+                const base = call.target.base;
+                if (base.type === 'promise') {
+                    const baseDepth = ctx.promiseStore.getDepth(base.promiseId);
+                    callDepth = baseDepth + 1;
+                    // Check max pipeline depth
+                    if (callDepth > (this.config.maxPipelineDepth ?? 20)) {
+                        throw { code: 'MAX_PIPELINE_DEPTH', message: `Pipeline depth ${callDepth} exceeds maximum ${this.config.maxPipelineDepth ?? 20}` };
+                    }
+                }
+            }
+            const target = this.resolveTarget(call.target, ctx);
+            const args = call.args.map((arg) => this.resolveArg(arg, ctx));
+            let result;
+            // Handle magic methods
+            if (call.method === '__get__') {
+                // Property getter - target is already the value from property access
+                result = target;
+            }
+            else if (call.method === '__map__' && Array.isArray(target)) {
+                // Magic map operation
+                const mapSpec = args[0];
+                if (mapSpec?.property) {
+                    result = target.map((item) => item[mapSpec.property]);
+                }
+                else {
+                    result = target;
+                }
+            }
+            else if (call.method === '__filter__' && Array.isArray(target)) {
+                // Magic filter operation
+                const filterSpec = args[0];
+                if (filterSpec?.property) {
+                    result = target.filter((item) => item[filterSpec.property] === filterSpec.equals);
+                }
+                else {
+                    result = target;
+                }
+            }
+            else if (target === ctx.rootObject) {
+                // Check for collection RPC pattern first: {Noun}.{method}
+                if (isCollectionRpcMethod(call.method)) {
+                    result = await this.handleCollectionRpc(call.method, args);
+                }
+                else {
+                    // Regular root object method call - MUST check if exposed
+                    if (!this.isRpcExposed(call.method)) {
+                        throw { code: 'METHOD_NOT_FOUND', message: `Method ${call.method} not found` };
+                    }
+                    const method = target[call.method];
+                    if (typeof method !== 'function') {
+                        throw { code: 'METHOD_NOT_FOUND', message: `Method ${call.method} not found` };
+                    }
+                    result = await method.apply(target, args);
+                }
+            }
+            else if (target && typeof target === 'object' && call.method in target) {
+                // Method call on non-root object (from pipelining)
+                const method = target[call.method];
+                if (typeof method === 'function') {
+                    result = await method.apply(target, args);
+                }
+                else {
+                    result = method;
+                }
+            }
+            else if (target && typeof target === 'object') {
+                // Property access on object
+                result = target[call.method];
+                if (result === undefined && !(call.method in target)) {
+                    throw { code: 'METHOD_NOT_FOUND', message: `Method ${call.method} not found` };
+                }
+            }
+            else {
+                throw { code: 'INVALID_TARGET', message: 'Cannot call method on null or primitive' };
+            }
+            // Store result for pipelining (with depth tracking)
+            ctx.promiseStore.set(call.promiseId, result, callDepth);
+            return {
+                promiseId: call.promiseId,
+                type: 'value',
+                value: result,
+            };
+        }
+        catch (error) {
+            const rpcError = error && typeof error === 'object' && 'code' in error
+                ? error
+                : {
+                    code: 'EXECUTION_ERROR',
+                    message: error instanceof Error ? error.message : String(error),
+                };
+            // Store error marker for pipeline propagation (with depth tracking)
+            ctx.promiseStore.set(call.promiseId, { __error__: rpcError }, callDepth);
+            return {
+                promiseId: call.promiseId,
+                type: 'error',
+                error: rpcError,
+            };
+        }
+    }
+    resolveTarget(target, ctx) {
+        switch (target.type) {
+            case 'root':
+                return ctx.rootObject;
+            case 'promise': {
+                if (ctx.promiseStore.isDisposed(target.promiseId)) {
+                    throw { code: 'DISPOSED_REFERENCE', message: `Promise ${target.promiseId} has been disposed` };
+                }
+                const value = ctx.promiseStore.get(target.promiseId);
+                if (value === undefined && !ctx.promiseStore.has(target.promiseId)) {
+                    throw { code: 'INVALID_PROMISE', message: `Promise ${target.promiseId} not found` };
+                }
+                // Check if the value is an error marker (propagate errors through pipeline)
+                if (value && typeof value === 'object' && '__error__' in value) {
+                    throw value.__error__;
+                }
+                // Check for null/undefined target
+                if (value === null || value === undefined) {
+                    throw { code: 'INVALID_TARGET', message: 'Cannot access property of null or undefined' };
+                }
+                return value;
+            }
+            case 'property': {
+                const base = this.resolveNestedTarget(target.base, ctx);
+                if (base === null || typeof base !== 'object') {
+                    throw { code: 'INVALID_TARGET', message: 'Cannot access property of non-object' };
+                }
+                // Handle array index access
+                if (Array.isArray(base) && /^\d+$/.test(target.property)) {
+                    return base[parseInt(target.property, 10)];
+                }
+                return base[target.property];
+            }
+            default:
+                throw { code: 'INVALID_TARGET', message: 'Unknown target type' };
+        }
+    }
+    resolveNestedTarget(target, ctx) {
+        switch (target.type) {
+            case 'root':
+                return ctx.rootObject;
+            case 'promise': {
+                if (ctx.promiseStore.isDisposed(target.promiseId)) {
+                    throw { code: 'DISPOSED_REFERENCE', message: `Promise ${target.promiseId} has been disposed` };
+                }
+                const value = ctx.promiseStore.get(target.promiseId);
+                if (value === undefined && !ctx.promiseStore.has(target.promiseId)) {
+                    throw { code: 'INVALID_PROMISE', message: `Promise ${target.promiseId} not found` };
+                }
+                // Check if the value is an error marker
+                if (value && typeof value === 'object' && '__error__' in value) {
+                    throw value.__error__;
+                }
+                return value;
+            }
+            default:
+                throw { code: 'INVALID_TARGET', message: 'Unknown nested target type' };
+        }
+    }
+    resolveArg(arg, ctx) {
+        switch (arg.type) {
+            case 'value':
+                return arg.value;
+            case 'promise': {
+                if (ctx.promiseStore.isDisposed(arg.promiseId)) {
+                    throw { code: 'DISPOSED_REFERENCE', message: `Promise ${arg.promiseId} has been disposed` };
+                }
+                const value = ctx.promiseStore.get(arg.promiseId);
+                // If the value is an object with an id, extract it for method calls
+                // This handles the case where we pass a user object to getUserPosts
+                if (value && typeof value === 'object' && 'id' in value) {
+                    return value.id;
+                }
+                return value;
+            }
+            case 'callback':
+                throw { code: 'NOT_IMPLEMENTED', message: 'Callbacks not yet supported' };
+            default:
+                throw { code: 'INVALID_ARG', message: 'Unknown argument type' };
+        }
+    }
+    /**
+     * Extract parameter names from a function.
+     * Uses function.toString() parsing to extract parameter names.
+     */
+    extractParamNames(fn) {
+        const fnStr = fn.toString();
+        // Match function parameters - handles various function syntaxes
+        const arrowMatch = fnStr.match(/^\s*\(?([^)=]*)\)?\s*=>/);
+        const funcMatch = fnStr.match(/^(?:async\s+)?(?:function\s*)?\s*\w*\s*\(([^)]*)\)/);
+        const paramsStr = arrowMatch?.[1] || funcMatch?.[1] || '';
+        if (!paramsStr.trim()) {
+            return [];
+        }
+        return paramsStr
+            .split(',')
+            .map((p) => {
+            // Handle destructuring, default values, rest params
+            const cleaned = p.trim()
+                .replace(/\s*=\s*.*$/, '') // Remove default values
+                .replace(/\.\.\.\s*/, '') // Remove rest operator
+                .replace(/[{}[\]]/g, ''); // Remove destructuring braces
+            // Extract the first identifier
+            const match = cleaned.match(/^\s*(\w+)/);
+            return match?.[1] || '';
+        })
+            .filter((p) => p.length > 0);
+    }
+}
+// ============================================================================
+// FACTORY FUNCTIONS
+// ============================================================================
+/**
+ * Create an RPC handler for a DO instance
+ */
+export function createRpcHandler(doInstance, config) {
+    return new RPCServer(doInstance, config);
+}
+/**
+ * Handle an RPC request (HTTP)
+ */
+export async function handleRpcRequest(request, doInstance, config) {
+    const server = createRpcHandler(doInstance, config);
+    return server.handleRpcRequest(request);
+}
+/**
+ * Handle WebSocket RPC upgrade
+ */
+export function handleWebSocketRpc(doInstance, config) {
+    const server = createRpcHandler(doInstance, config);
+    return server.handleWebSocketRpc();
+}
+export function withRpcServer(Base, config) {
+    return class extends Base {
+        _rpcServer;
+        get rpcServer() {
+            if (!this._rpcServer) {
+                this._rpcServer = new RPCServer(this, config);
+            }
+            return this._rpcServer;
+        }
+        isRpcExposed(method) {
+            return this.rpcServer.isRpcExposed(method);
+        }
+        /**
+         * Override fetch to handle /rpc endpoint
+         */
+        async fetch(request) {
+            const url = new URL(request.url);
+            // Handle /rpc endpoint
+            if (url.pathname === '/rpc') {
+                // Check for WebSocket upgrade
+                const upgradeHeader = request.headers.get('upgrade');
+                const connectionHeader = request.headers.get('connection')?.toLowerCase() || '';
+                const hasConnectionUpgrade = connectionHeader.includes('upgrade');
+                if (upgradeHeader?.toLowerCase() === 'websocket' && hasConnectionUpgrade) {
+                    return this.rpcServer.handleWebSocketRpc();
+                }
+                // HTTP RPC request
+                if (request.method === 'POST') {
+                    return this.rpcServer.handleRpcRequest(request);
+                }
+                // GET request - return RPC info
+                return Response.json({
+                    message: 'RPC endpoint - use POST for HTTP batch mode or WebSocket for streaming',
+                    methods: this.rpcServer.methods,
+                }, { headers: { 'Content-Type': 'application/json' } });
+            }
+            // Delegate to parent fetch
+            return super.fetch(request);
+        }
+    };
+}
+/**
+ * Apply RPC integration to an existing DO instance
+ * This is useful when you can't use the mixin pattern
+ */
+export function applyRpcIntegration(doInstance, config) {
+    const rpcServer = new RPCServer(doInstance, config);
+    // Add rpcServer property
+    Object.defineProperty(doInstance, 'rpcServer', {
+        get() {
+            return rpcServer;
+        },
+        enumerable: true,
+        configurable: false,
+    });
+    // Add isRpcExposed method
+    doInstance.isRpcExposed = (method) => rpcServer.isRpcExposed(method);
+    // Wrap the existing fetch method
+    const originalFetch = doInstance.fetch.bind(doInstance);
+    doInstance.fetch = async (request) => {
+        const url = new URL(request.url);
+        // Handle /rpc endpoint
+        if (url.pathname === '/rpc') {
+            // Check for WebSocket upgrade
+            const upgradeHeader = request.headers.get('upgrade');
+            const connectionHeader = request.headers.get('connection')?.toLowerCase() || '';
+            const hasConnectionUpgrade = connectionHeader.includes('upgrade');
+            if (upgradeHeader?.toLowerCase() === 'websocket' && hasConnectionUpgrade) {
+                return rpcServer.handleWebSocketRpc();
+            }
+            // HTTP RPC request
+            if (request.method === 'POST') {
+                return rpcServer.handleRpcRequest(request);
+            }
+            // GET request - return RPC info
+            return Response.json({
+                message: 'RPC endpoint - use POST for HTTP batch mode or WebSocket for streaming',
+                methods: rpcServer.methods,
+            }, { headers: { 'Content-Type': 'application/json' } });
+        }
+        // Delegate to original fetch
+        return originalFetch(request);
+    };
+}
+export default RPCServer;
+import { buildJsonResponse, buildErrorResponse, } from './shared';
+/**
+ * Cache for RPC servers per DO instance
+ */
+const rpcServerCache = new WeakMap();
+/**
+ * RPC Handler implementing TransportHandler interface
+ *
+ * Provides Cap'n Web RPC functionality:
+ * - Promise pipelining
+ * - JSON-RPC 2.0 support
+ * - WebSocket streaming RPC
+ * - Method discovery and invocation
+ *
+ * @example
+ * ```typescript
+ * const rpcHandler = new RpcHandler({
+ *   path: '/rpc',
+ *   maxPipelineDepth: 20,
+ * })
+ *
+ * // Use in handler chain
+ * chain.use(rpcHandler, 40)
+ * ```
+ */
+export class RpcHandler {
+    name = 'rpc';
+    options;
+    server = null;
+    constructor(options = {}) {
+        this.options = {
+            path: '/rpc',
+            maxPipelineDepth: 20,
+            ...options,
+        };
+    }
+    /**
+     * Check if this handler can process the request
+     * RPC handler processes requests to the /rpc endpoint
+     */
+    canHandle(request) {
+        const url = new URL(request.url);
+        const rpcPath = this.options.path || '/rpc';
+        // Check if request is to RPC endpoint
+        if (url.pathname === rpcPath) {
+            // RPC handler has medium-high priority
+            return {
+                canHandle: true,
+                priority: 40,
+            };
+        }
+        return { canHandle: false, reason: 'Path does not match RPC endpoint' };
+    }
+    /**
+     * Handle the RPC request
+     */
+    async handle(request, context) {
+        // Get or create RPC server for this instance
+        const server = this.getOrCreateServer(context.instance);
+        // Check for WebSocket upgrade
+        const upgradeHeader = request.headers.get('upgrade');
+        const connectionHeader = request.headers.get('connection')?.toLowerCase() || '';
+        const hasConnectionUpgrade = connectionHeader.includes('upgrade');
+        if (upgradeHeader?.toLowerCase() === 'websocket' && hasConnectionUpgrade) {
+            return server.handleWebSocketRpc();
+        }
+        // Handle HTTP methods
+        if (request.method === 'POST') {
+            return server.handleRpcRequest(request);
+        }
+        if (request.method === 'GET') {
+            // Return RPC info
+            return buildJsonResponse({
+                message: 'RPC endpoint - use POST for HTTP batch mode or WebSocket for streaming',
+                methods: server.methods,
+            });
+        }
+        return buildErrorResponse({ message: 'Method not allowed', code: 'METHOD_NOT_ALLOWED' }, 405, { headers: { 'Allow': 'GET, POST' } });
+    }
+    /**
+     * Get or create RPC server for an instance
+     */
+    getOrCreateServer(instance) {
+        // Check cache
+        if (rpcServerCache.has(instance)) {
+            return rpcServerCache.get(instance);
+        }
+        // Create new server
+        const server = new RPCServer(instance, {
+            maxPipelineDepth: this.options.maxPipelineDepth,
+            exposedMethods: this.options.exposedMethods,
+            blockedMethods: this.options.blockedMethods,
+        });
+        rpcServerCache.set(instance, server);
+        this.server = server;
+        return server;
+    }
+    /**
+     * Get current RPC server
+     */
+    getServer() {
+        return this.server;
+    }
+    /**
+     * Clear server cache for an instance
+     */
+    static clearCache(instance) {
+        rpcServerCache.delete(instance);
+    }
+    /**
+     * Dispose handler resources
+     */
+    dispose() {
+        this.server = null;
+    }
+}
+//# sourceMappingURL=rpc-server.js.map