Skip to main content

Introduction to Lumenize RPC

Lumenize RPC provides remote procedure calls to Cloudflare Durable Objects over HTTP or WebSocket transports.

Lumenize RPC supports two main use cases:

  1. In-process integration testing (documented in @lumenize/testing Usage)
  2. In-production RPC (documented in this section)

In-production RPC​

  1. Purpose: Interact with your Durable Objects from a browser client as if running inside the DO.

  2. Supports:

    • Any StructuredCloneable type (e.g., Set, Map, Date, circular objects)
    • Automatic propagation of errors thrown by your DO back to the client
    • Both HTTP and WebSocket transports

  3. Secure:

    • Security hooks and best-practice examples included

  4. Example Usage:

    // Store a value in the DO's storage
    await client.ctx.storage.put('count', '10');
    // Call an RPC method defined in your DO
    const currentCount = await client.increment(); // returns 11

WebSocket vs HTTP​

Both transports offer identical RPC functionality but have different performance characteristics.

WebSocket (default)​

  • Persistent connection for multiple RPC calls
  • Higher initial connection overhead
  • Lower latency for subsequent calls
  • Automatic connection management
  • Automatically re-establishes connection on demand
  • Utilizes Cloudflare DurableObject's hibernating WebSockets

HTTP​

  • One HTTP request per RPC call
  • Simpler
  • Slightly higher per-call latency

Choose based on your requirements:

  • When in doubt: WebSocket is generally more efficient and low-latency
  • Production scenarios with restrictive intermediaries: HTTP may be more robust
  • Future-proofing: LumenizeBase builds on WebSockets for real-time state sync — your client code will remain the same