feat(server): add timeout handler plugin (#1858)

Adds `TimeoutHandlerPlugin` to `@orpc/server/plugins`, the server-side
counterpart of `TimeoutLinkPlugin`. When handling exceeds the configured
timeout, the plugin aborts the request signal with an `AbortError`. It
never preempts the procedure: abort-aware procedures stop early and
logging records the timeout as a cancellation, while a procedure that
ignores the signal still delivers its real result or error, so nothing
is masked.

## Features

- `timeout` limits producing the response; the separate
`streamingTimeout` (usually higher) limits the full duration of
streaming bodies, both async iterator objects and readable streams.
- Both options accept a static number or a per-request function of the
interceptor options; returning `null`/`undefined` disables the timeout
for that request.
- No timer leaks: timers are cleared when the response is produced and
when a streaming body finishes or is cancelled; requests with both
timeouts disabled bypass the plugin entirely.

## Testing

- 15 handler tests under fake timers, each asserting zero leftover
timers: abort + response via signal-honoring procedures, no preemption,
unmasked late errors, dynamic values, per-request disabling, and
streaming termination and cleanup for both body kinds.
- Registered in the all-plugins compatibility suite; `pnpm type:check`,
eslint, and `pnpm docs:validate` pass.

## Docs

- `/docs/plugins/timeout` now covers both the link and handler plugins,
streaming timeouts, and dynamic per-request values.

Author: dinwwwh

apps/content/docs/plugins/timeout.mdx

@@ -1,11 +1,13 @@
 ---
 title: "Timeout Plugin"
-description: "Automatically abort requests that exceed a timeout with an AbortError, using a static value or a per-request dynamic timeout."
+description: "Abort requests that exceed a timeout on the client or the server, using a static value or a per-request dynamic timeout."
 sidebar:
   label: "Timeout"
 ---
 
-## Usage
+## Client
+
+Use `TimeoutLinkPlugin` to abort requests that exceed the timeout with an `AbortError`:
 
 ```ts
 import { TimeoutLinkPlugin } from '@orpc/client/plugins'
@@ -23,11 +25,52 @@ const link = new RPCLink({
 The `link` can be any supported oRPC link, such as [RPCLink](/docs/rpc/link), [OpenAPILink](/docs/openapi/link), or a custom one.
 :::
 
+## Server
+
+Use `TimeoutHandlerPlugin` to abort the request signal with an `AbortError` when handling exceeds the timeout:
+
+```ts handler
+import { TimeoutHandlerPlugin } from '@orpc/server/plugins'
+
+const handler = new RPCHandler(router, {
+  plugins: [
+    new TimeoutHandlerPlugin({
+      timeout: 10_000, // 10 seconds
+    }),
+  ],
+})
+```
+
+:::warning
+The plugin only aborts the request signal, it does not respond right after the timeout exceeds. The procedure must honor the signal to stop early and produce the response.
+:::
+
+### Streaming Responses
+
+The `timeout` option only covers producing the response, so streaming responses can outlive it. Use `streamingTimeout`, usually higher, to limit the full duration of streaming response bodies ([async iterator objects](/docs/async-iterator-object) and readable streams):
+
+```ts handler
+const handler = new RPCHandler(router, {
+  plugins: [
+    new TimeoutHandlerPlugin({
+      timeout: 10_000, // 10 seconds to produce the response
+      streamingTimeout: 300_000, // 5 minutes for the full stream
+    }),
+  ],
+})
+```
+
+:::info
+The `handler` can be any supported oRPC handler, such as [RPCHandler](/docs/rpc/handler), [OpenAPIHandler](/docs/openapi/handler), or a custom one.
+:::
+
 ## Dynamic Timeout
 
-The `timeout` option also accepts a function, so you can resolve the timeout per request from the interceptor options, such as the procedure `path` or the [client context](/docs/client/client-side#client-context):
+The `timeout` and `streamingTimeout` options also accept a function, so you can resolve the timeout per request from the interceptor options. On the client these include the procedure `path` and the [client context](/docs/client/client-side#client-context), on the server the matched `procedure` and the [handler context](/docs/context):
 
-```ts
+<CodeGroup>
+
+```ts link
 const link = new RPCLink({
   plugins: [
     new TimeoutLinkPlugin({
@@ -37,10 +80,22 @@ const link = new RPCLink({
 })
 ```
 
+```ts handler
+const handler = new RPCHandler(router, {
+  plugins: [
+    new TimeoutHandlerPlugin({
+      timeout: ({ path }) => path[0] === 'reports' ? 60_000 : 10_000,
+    }),
+  ],
+})
+```
+
+</CodeGroup>
+
 :::info
 Return `null` or `undefined` to disable the timeout, which is useful for excluding long-lived requests. Any number always enables the timeout.
 :::
 
 ## Learn More
 
-For implementation details, see the [source code](https://github.com/middleapi/orpc/blob/main/packages/client/src/plugins/timeout.ts).
+For implementation details, see the [TimeoutLinkPlugin source code](https://github.com/middleapi/orpc/blob/main/packages/client/src/plugins/timeout.ts) or the [TimeoutHandlerPlugin source code](https://github.com/middleapi/orpc/blob/main/packages/server/src/plugins/timeout.ts).

packages/cloudflare/worker-configuration.d.ts

@@ -1,6 +1,6 @@
 /* eslint-disable */
 // Generated by Wrangler by running `wrangler types` (hash: e624d76b8500cfee2091bb6c84ee404f)
-// Runtime types generated with workerd@1.20260730.1 2026-07-01 
+// Runtime types generated with workerd@1.20260804.1 2026-07-01 
 interface __BaseEnv_Env {
 	RATELIMIT_3_10S: RateLimit;
 	PUBLISHER_DON: DurableObjectNamespace /* PublisherDO */;

packages/server/src/plugins/index.ts

@@ -38,3 +38,4 @@ export type {
   ResponseHeadersHandlerPluginContext as ResponseHeadersPluginContext,
 } from './response-headers'
 export * from './rethrow'
+export * from './timeout'

packages/server/src/plugins/timeout.test.ts

@@ -0,0 +1,268 @@
+import type { TimeoutHandlerPluginOptions } from './timeout'
+import { COMMON_ERROR_STATUS_MAP, ORPCError } from '@orpc/client'
+import { AbortError } from '@orpc/shared'
+import { RPCHandler } from '../adapters/fetch'
+import { os } from '../builder'
+import { TimeoutHandlerPlugin } from './timeout'
+
+beforeEach(() => {
+  vi.clearAllMocks()
+  vi.useFakeTimers()
+})
+
+afterEach(() => {
+  expect(vi.getTimerCount()).toBe(0)
+  vi.useRealTimers()
+})
+
+describe('timeoutHandlerPlugin', () => {
+  const procedure_handler = vi.fn()
+  const procedure = os.handler(procedure_handler)
+
+  function makeHandler(options: TimeoutHandlerPluginOptions<any>, router: any = procedure) {
+    return new RPCHandler(router, {
+      allowMethods: ['GET'], // tests below send GET requests
+      plugins: [new TimeoutHandlerPlugin(options)],
+    })
+  }
+
+  /** A sleep that honors the signal by rejecting with the abort reason, or ignores it when no signal is given. */
+  function sleepWithSignal(ms: number, signal?: AbortSignal): Promise<void> {
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(resolve, ms)
+      signal?.addEventListener('abort', () => {
+        clearTimeout(timer)
+        reject(signal.reason)
+      }, { once: true })
+    })
+  }
+
+  it('should respond and clear the timeout when the procedure finishes in time', async () => {
+    procedure_handler.mockResolvedValueOnce('success')
+    const handler = makeHandler({ timeout: 5000 })
+
+    const { response } = await handler.handle(new Request('http://localhost'))
+    expect(response?.status).toBe(200)
+
+    const { signal } = procedure_handler.mock.calls[0]![0]
+    expect(signal).toBeInstanceOf(AbortSignal)
+    expect(signal.aborted).toBe(false)
+  })
+
+  it('should abort the signal with an AbortError and respond once the procedure honors it', async () => {
+    procedure_handler.mockImplementationOnce(({ signal }) => sleepWithSignal(100_000, signal))
+    const handler = makeHandler({ timeout: 1000 })
+
+    const promise = handler.handle(new Request('http://localhost'))
+    await vi.advanceTimersByTimeAsync(1000)
+
+    const { response } = await promise
+    expect(response?.status).toBe(COMMON_ERROR_STATUS_MAP.INTERNAL_SERVER_ERROR)
+
+    const { signal } = procedure_handler.mock.calls[0]![0]
+    expect(signal.aborted).toBe(true)
+    expect(signal.reason).toBeInstanceOf(AbortError)
+    expect(signal.reason.message).toBe('Request timed out after 1000ms')
+  })
+
+  it('should not preempt a procedure that ignores the abort signal', async () => {
+    procedure_handler.mockImplementationOnce(async () => {
+      await sleepWithSignal(100_000)
+      return 'late success'
+    })
+    const handler = makeHandler({ timeout: 1000 })
+
+    const promise = handler.handle(new Request('http://localhost'))
+
+    await vi.advanceTimersByTimeAsync(1000)
+    expect(procedure_handler.mock.calls[0]![0].signal.aborted).toBe(true)
+
+    await vi.advanceTimersByTimeAsync(99_000)
+    const { response } = await promise
+    expect(response?.status).toBe(200) // the late result is still delivered
+  })
+
+  it('should not mask procedure errors thrown after the timeout', async () => {
+    procedure_handler.mockImplementationOnce(async () => {
+      await sleepWithSignal(100_000)
+      throw new ORPCError('NOT_ACCEPTABLE')
+    })
+    const handler = makeHandler({ timeout: 1000 })
+
+    const promise = handler.handle(new Request('http://localhost'))
+    await vi.advanceTimersByTimeAsync(100_000)
+
+    const { response } = await promise
+    expect(response?.status).toBe(COMMON_ERROR_STATUS_MAP.NOT_ACCEPTABLE)
+  })
+
+  it('should support dynamic timeout based on interceptor options', async () => {
+    procedure_handler.mockImplementationOnce(({ signal }) => sleepWithSignal(100_000, signal))
+
+    const timeout = vi.fn(({ context }: any) => context.timeout)
+    const handler = makeHandler({ timeout })
+
+    const promise = handler.handle(new Request('http://localhost'), { context: { timeout: 1000 } })
+    await vi.advanceTimersByTimeAsync(1000)
+
+    const { response } = await promise
+    expect(response?.status).toBe(COMMON_ERROR_STATUS_MAP.INTERNAL_SERVER_ERROR)
+
+    expect(timeout).toHaveBeenCalledTimes(1)
+    expect(timeout).toHaveBeenCalledWith(expect.objectContaining({
+      path: [],
+      procedure,
+      context: { timeout: 1000 },
+    }))
+  })
+
+  it.each([null, undefined])('should dynamically disable timeout when value is %s', async (timeout) => {
+    procedure_handler.mockImplementationOnce(() => sleepWithSignal(100_000).then(() => 'success'))
+    const handler = makeHandler({ timeout: () => timeout })
+
+    const promise = handler.handle(new Request('http://localhost'))
+    await vi.advanceTimersByTimeAsync(100_000)
+
+    const { response } = await promise
+    expect(response?.status).toBe(200)
+  })
+
+  it.each([
+    ['not provided', {}],
+    ['null', { streamingTimeout: () => null }],
+    ['undefined', { streamingTimeout: () => undefined }],
+  ])('should let streaming responses outlive the timeout when streamingTimeout is %s', async (_, options) => {
+    const handler = makeHandler({ timeout: 1000, ...options }, os.handler(async function* () {
+      yield 'first'
+      await sleepWithSignal(100_000)
+      yield 'second'
+    }))
+
+    const { response } = await handler.handle(new Request('http://localhost'))
+    expect(response?.status).toBe(200)
+
+    const textPromise = response!.text()
+    await vi.advanceTimersByTimeAsync(100_000)
+
+    const text = await textPromise
+    expect(text).toContain('first')
+    expect(text).toContain('second')
+    expect(text).not.toContain('event: error')
+  })
+
+  it('should end event iterator bodies with an error event when streamingTimeout is exceeded', async () => {
+    let cleaned = false
+    const handler = makeHandler({ timeout: 1000, streamingTimeout: 2000 }, os.handler(async function* ({ signal }) {
+      try {
+        yield 'first'
+        await sleepWithSignal(100_000, signal)
+        yield 'second'
+      }
+      finally {
+        cleaned = true
+      }
+    }))
+
+    const { response } = await handler.handle(new Request('http://localhost'))
+    expect(response?.status).toBe(200)
+
+    const textPromise = response!.text()
+    await vi.advanceTimersByTimeAsync(2000)
+
+    const text = await textPromise
+    expect(text).toContain('first')
+    expect(text).not.toContain('second')
+    expect(text).toContain('event: error')
+    expect(cleaned).toBe(true)
+  })
+
+  it('should end readable stream bodies once the producer honors the signal when streamingTimeout is exceeded', async () => {
+    const handler = new RPCHandler(procedure, {
+      allowMethods: ['GET'],
+      interceptors: [async ({ request }) => ({
+        status: 200,
+        headers: {},
+        body: new ReadableStream<Uint8Array>({
+          start(controller) {
+            controller.enqueue(new TextEncoder().encode('first'))
+            request.signal!.addEventListener('abort', () => {
+              controller.error(request.signal!.reason)
+            }, { once: true })
+          },
+        }),
+      })],
+      plugins: [new TimeoutHandlerPlugin({ timeout: 1000, streamingTimeout: 2000 })],
+    })
+
+    const { response } = await handler.handle(new Request('http://localhost'))
+    expect(response?.status).toBe(200)
+
+    const reader = response!.body!.getReader()
+    await expect(reader.read()).resolves.toEqual({ done: false, value: new TextEncoder().encode('first') })
+
+    const nextRead = reader.read()
+    nextRead.catch(() => {})
+    await vi.advanceTimersByTimeAsync(2000)
+
+    await expect(nextRead).rejects.toSatisfy(error =>
+      error instanceof AbortError && error.message === 'Request timed out after 2000ms',
+    )
+  })
+
+  it('should let streaming responses finish in time and clear the streaming timeout', async () => {
+    const handler = makeHandler({ timeout: 1000, streamingTimeout: 5000 }, os.handler(async function* () {
+      yield 'first'
+      await sleepWithSignal(1000)
+      yield 'second'
+    }))
+
+    const { response } = await handler.handle(new Request('http://localhost'))
+    const textPromise = response!.text()
+    await vi.advanceTimersByTimeAsync(1000)
+
+    const text = await textPromise
+    expect(text).toContain('first')
+    expect(text).toContain('second')
+    expect(text).not.toContain('event: error')
+  })
+
+  it('should support dynamic streamingTimeout based on interceptor options', async () => {
+    const streamingTimeout = vi.fn(({ context }: any) => context.streamingTimeout)
+    const handler = makeHandler({ timeout: 1000, streamingTimeout }, os.handler(async function* ({ signal }) {
+      yield 'first'
+      await sleepWithSignal(100_000, signal)
+      yield 'second'
+    }))
+
+    const { response } = await handler.handle(new Request('http://localhost'), {
+      context: { streamingTimeout: 2000 },
+    })
+
+    const textPromise = response!.text()
+    await vi.advanceTimersByTimeAsync(2000)
+
+    const text = await textPromise
+    expect(text).toContain('first')
+    expect(text).not.toContain('second')
+    expect(text).toContain('event: error')
+
+    expect(streamingTimeout).toHaveBeenCalledTimes(1)
+    expect(streamingTimeout).toHaveBeenCalledWith(expect.objectContaining({
+      context: { streamingTimeout: 2000 },
+    }))
+  })
+
+  it('should forward abort from the request signal while the timeout is still active', async () => {
+    procedure_handler.mockImplementationOnce(({ signal }) => sleepWithSignal(100_000, signal))
+    const handler = makeHandler({ timeout: 5000 })
+
+    const controller = new AbortController()
+    const promise = handler.handle(new Request('http://localhost', { signal: controller.signal }))
+
+    await vi.advanceTimersByTimeAsync(500)
+    controller.abort(new Error('user cancelled'))
+
+    const { response } = await promise
+    expect(response?.status).toBe(500) // not a timeout response
+  })
+})