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 { matched, response } = await handler.handle(request, {
    prefix: '/rpc',
    context: {} // Provide initial context if required
  })

  if (matched) {
    return 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 handler = new RPCHandler(router, {
  eventIteratorKeepAliveEnabled: true,
  eventIteratorKeepAliveInterval: 5000, // 5 seconds
  eventIteratorKeepAliveComment: '',
})

Default Plugins

RPCHandler is pre-configured with plugins that help enforce best practices and enhance security out of the box. By default, the following plugin is enabled:

• StrictGetMethodPlugin - Disable by setting strictGetMethodPluginEnabled to false.