Skip to main content

Introduction to Lumenize RPC

Deprecated

@lumenize/rpc is deprecated for production use. Use @lumenize/mesh instead, which provides secure mesh networking with built-in authentication, access control, and browser clients as full mesh peers.

@lumenize/rpc remains available as the foundation for @lumenize/testing — you don't need to change anything if you're using it for testing.

Lumenize RPC provides de✨light✨ful 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: @lumenize/mesh builds on WebSockets for real-time state sync — your client code will remain the same