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.

WARNING

This documentation is focused on the HTTP Adapter. Other adapters may remove or change options to keep things simple.

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 automatically enables essential plugins for security reasons.

Plugin	Applies To	Toggle Option
StrictGetMethodPlugin	HTTP Adapter	strictGetMethodPluginEnabled