RPC Handler

The RPCHandler enables communication with clients over oRPC's proprietary RPC protocol, built on top of HTTP. While it efficiently transfers native types, the protocol is neither human-readable nor OpenAPI-compatible. For OpenAPI support, use the OpenAPIHandler.

WARNING

RPCHandler is designed exclusively for RPCLink and does not support OpenAPI. Avoid sending requests to it manually.

Supported Data Types

RPCHandler natively serializes and deserializes the following JavaScript types:

• string
• number (including NaN)
• boolean
• null
• undefined
• Date (including Invalid Date)
• BigInt
• RegExp
• URL
• Record (object)
• Array
• Set
• Map
• Blob (unsupported in AsyncIteratorObject)
• File (unsupported in AsyncIteratorObject)
• AsyncIteratorObject (only at the root level; powers the Event Iterator)

TIP

You can extend the list of supported types by creating a custom serializer.

Setup and Integration

import { RPCHandler } from '@orpc/server/fetch' // or '@orpc/server/node'
import { CORSPlugin } from '@orpc/server/plugins'
import { onError } from '@orpc/server'

const handler = new RPCHandler(router, {
  plugins: [
    new CORSPlugin()
  ],
  interceptors: [
    onError((error) => {
      console.error(error)
    })
  ],
})

export default async function fetch(request: Request) {
  const url = new URL(request.url)

  if (url.pathname.startWith('/rpc')) {
    const result = await handler.handle(request, {
      prefix: '/rpc',
      context: {} // Provide initial context if required
    })

    if (result.matched) {
      return result.response
    }
  }

  return new Response('Not Found', { status: 404 })
}

Event-Iterator Keep Alive

To keep Event Iterator connections alive, RPCHandler periodically sends a ping comment to the client. You can configure this behavior using the following options:

• eventIteratorKeepAliveEnabled (default: true) – Enables or disables pings.
• eventIteratorKeepAliveInterval (default: 5000) – Time between pings (in milliseconds).
• eventIteratorKeepAliveComment (default: '') – Custom content for ping comments.

const result = await handler.handle(request, {
  eventIteratorKeepAliveEnabled: true,
  eventIteratorKeepAliveInterval: 5000, // 5 seconds
  eventIteratorKeepAliveComment: '',
})