RPC Handler

Use RPCHandler to serve procedures over the RPC protocol, with HTTP method control, interceptors, plugins, custom serializers, and error responses.

Overview

RPCHandler serves RPC Link clients, or any client that implements the RPC protocol:

const handler = new RPCHandler(router, {
  interceptors: [
    async ({ next, path }) => {
      console.time(path.join('.'))

      try {
        return await next()
      } catch (err) {
        console.error(`${path.join('.')}:`, err)
        throw err
      } finally {
        console.timeEnd(path.join('.'))
      }
    },
  ],
  plugins: [new CORSHandlerPlugin()],
})

Supported HTTP Methods

By default, RPCHandler only responds to POST, PUT, PATCH, and DELETE requests. Any other method, such as GET or HEAD, is treated as unmatched, as if no procedure exists at that path.

This is a security default: cross-site, browsers can only send these methods via a CORS preflight or an HTML form, never from a plain link. Safe methods like GET or HEAD are excluded because invoking a procedure can modify data.

Use allowMethods to replace the allowlist: tighten it to POST only, or also accept QUERY, which reads input from the request body and stays preflight-protected:

const handler = new RPCHandler(router, {
  allowMethods: ['POST', 'PUT', 'PATCH', 'DELETE', 'QUERY'],
})

Enabling the GET Method

Add GET to allowMethods to enable it for every procedure:

import { GetMethodCsrfProtectionHandlerPlugin } from '@orpc/server/plugins'
import { RPC_DEFAULT_ALLOW_METHODS } from '@orpc/server/standard'

const handler = new RPCHandler(router, {
  allowMethods: ['GET', ...RPC_DEFAULT_ALLOW_METHODS],
  plugins: [
    new GetMethodCsrfProtectionHandlerPlugin(), // reject GET navigations that may carry SameSite=Lax cookies
  ],
})

The plugin rejects the navigations another site can use to send SameSite=Lax cookies, such as link clicks and redirects, while cookie-less requests such as fetch keep working. See the GET Method CSRF Protection Plugin page for its cookie requirements.

Or pass a function to decide per request. For example, only allow GET for procedures that declare it via OpenAPI metadata:

import { getOpenAPIMeta, openapi } from '@orpc/openapi'
import { RPC_DEFAULT_ALLOW_METHODS } from '@orpc/server/standard'

const listPlanets = os
  .meta(openapi({ method: 'GET', path: '/planets' }))
  .handler(() => ['Earth', 'Mars'])

const handler = new RPCHandler(
  { listPlanets },
  {
    allowMethods: (method, procedure, path) => {
      if (method === 'GET' && getOpenAPIMeta(procedure)?.method === 'GET') {
        return true
      }

      return RPC_DEFAULT_ALLOW_METHODS.includes(method)
    },
  },
)

Interceptors

Interceptors let you observe or change different stages of an RPC request. Common use cases include logging, error handling, and metrics.

Routing Interceptors

Routing interceptors run on every request before routing. Use them when you need to handle all requests, including requests that do not match a procedure.

const handler = new RPCHandler(router, {
  routingInterceptors: [
    async ({ next, request, context }) => {
      if (condition) {
        return { matched: false }
      }

      const { matched, response } = await next()
      return { matched, response }
    },
  ],
})

Interceptors

These interceptors run only for matched requests, after routing and before error handling (but can’t use ORPCError for typesafe errors). Use them when you need access to the matched procedure.

const handler = new RPCHandler(router, {
  interceptors: [
    async ({ next, request, procedure, context }) => {
      try {
        const response = await next()
        return response
      } catch (err) {
        if (err instanceof CustomError) {
          throw new ORPCError('CUSTOM_ERROR', { message: err.message, cause: err })
        }

        throw err
      }
    },
    async ({ next, path }) => {
      console.time(path.join('.'))

      try {
        const response = await next()
        return response
      } catch (err) {
        console.error(`${path.join('.')}:`, err)
        throw err
      } finally {
        console.timeEnd(path.join('.'))
      }
    },
  ],
})

Client Interceptors

Client interceptors run only for matched requests, after input decoding, before output encoding and can use ORPCError for typesafe errors. Use them when you need access to the procedure, input, and output.

const handler = new RPCHandler(router, {
  clientInterceptors: [
    async ({ next, input, context, procedure }) => {
      const output = await next()
      return output
    },
  ],
})

Plugins

Plugins package reusable interceptors. For example, CORS Plugin adds a routing interceptor to handle preflight requests and adds CORS headers to every response.

const handler = new RPCHandler(router, {
  plugins: [new CORSHandlerPlugin()],
})

Custom Serializer

RPCHandler uses a built-in serializer that supports many native types. Provide a custom serializer when you need extra types or different encoding behavior. For more details, see RPC Serializer.

const handler = new RPCHandler(router, {
  serializer: new RPCSerializer({
    handlers: {
      // ...custom handlers
    },
  }),
})

Filtering Procedures

Use the filter option to exclude procedures from matching:

const handler = new RPCHandler(router, {
  filter: (contract, path) => getIsInternalMeta(contract) !== true,
})

Custom Error Response

By default, RPCHandler uses COMMON_ERROR_STATUS_MAP to determine response status codes, and codes missing from the map fall back to 400. Use errorStatusMap to customize them:

import { COMMON_ERROR_STATUS_MAP } from '@orpc/server'

const handler = new RPCHandler(router, {
  /**
   * The status code should be in the `4xx` or `5xx` range (must be greater than or equal to `400`).
   */
  errorStatusMap: {
    ...COMMON_ERROR_STATUS_MAP,
    CUSTOM_ERROR: 599,
  },
})

Event Stream Options

Configure how an AsyncIteratorObject is streamed to the client. Available options depend on the adapter. For example, the fetch adapter supports:

const handler = new RPCHandler(router, {
  toFetchResponse: {
    eventStream: {
      /**
       * Initial comment sent immediately upon stream start to flush headers. This allows the
       * receiving side to establish the connection without waiting for the first event.
       *
       * `false` disables it, an object customizes it.
       *
       * @default true
       */
      initialComment: {
        /**
         * The content of the initial comment sent upon stream start. Must not include newline characters.
         *
         * @default ''
         */
        comment: '',
      },
      /**
       * Ping comment sent periodically to keep the connection alive.
       *
       * `false` disables it, an object customizes it.
       *
       * @default true
       */
      keepAlive: {
        /**
         * Interval (in milliseconds) between ping comments sent after the last event.
         *
         * @default 15000
         */
        interval: 15000,
        /**
         * The content of the ping comment. Must not include newline characters.
         *
         * @default ''
         */
        comment: '',
      },
    },
  },
})

Lifecycle

The diagram below shows how a request flows through RPCHandler and where each interceptor type runs: