feat(client): Retry After Plugin (#1190)

A plugin auto retry base on `Retry-After` response header.

Fixes #1181

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Introduced a Retry After Plugin for clients enabling automatic retries
with configurable conditions, max attempts, and timeouts.

* **Documentation**
  * Added Retry After Plugin docs with examples.
* Updated rate-limit handler docs to note integration with the Retry
After Plugin.
  * Navigation updated to include the new plugin docs.

* **Tests**
* Added comprehensive tests covering retry behavior, parsing, timeouts,
custom conditions, and abort handling.

* **Bug Fixes**
  * Aligned rate-limit status handling with shared definitions.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: unnoq

apps/content/.vitepress/config.ts

@@ -149,6 +149,7 @@ export default withMermaid(defineConfig({
             { text: 'Dedupe Requests', link: '/docs/plugins/dedupe-requests' },
             { text: 'Batch Requests', link: '/docs/plugins/batch-requests' },
             { text: 'Client Retry', link: '/docs/plugins/client-retry' },
+            { text: 'Retry After', link: '/docs/plugins/retry-after' },
             { text: 'Compression', link: '/docs/plugins/compression' },
             { text: 'Body Limit', link: '/docs/plugins/body-limit' },
             { text: 'Simple CSRF Protection', link: '/docs/plugins/simple-csrf-protection' },

apps/content/docs/helpers/ratelimit.md

@@ -224,6 +224,10 @@ const handler = new RPCHandler(router, {
 })
 ```
 
+::: info
+You can combine this plugin with [Retry After Plugin](/docs/plugins/retry-after) to enable automatic client-side retries based on server rate-limiting headers.
+:::
+
 ::: info
 The `handler` can be any supported oRPC handler, such as [RPCHandler](/docs/rpc-handler), [OpenAPIHandler](/docs/openapi/openapi-handler), or other custom handlers.
 :::

apps/content/docs/plugins/retry-after.md

@@ -0,0 +1,40 @@
+---
+title: Retry After Plugin
+description: A plugin for oRPC that automatically retries requests based on server Retry-After headers.
+---
+
+# Retry After Plugin
+
+The **Retry After Plugin** automatically retries requests based on server `Retry-After` headers. This is particularly useful for handling rate limiting and temporary server unavailability.
+
+## Usage
+
+```ts
+import { RetryAfterPlugin } from '@orpc/client/plugins'
+
+const link = new RPCLink({
+  url: 'http://localhost:3000/rpc',
+  plugins: [
+    new RetryAfterPlugin({
+      condition: (response, options) => {
+        // Override condition to determine if a request should be retried
+        return response.status === 429 || response.status === 503
+      },
+      maxAttempts: 5, // Maximum retry attempts
+      timeout: 5 * 60 * 1000, // Maximum time to spend retrying (ms)
+    }),
+  ],
+})
+```
+
+::: info Options
+
+- **`condition`**: A function to determine whether a request should be retried. Defaults to retrying on `429` (Too Many Requests) and `503` (Service Unavailable) status codes.
+- **`maxAttempts`**: Maximum number of retry attempts allowed. Defaults to `3`.
+- **`timeout`**: Maximum duration in milliseconds to spend on retries. If specified, retries will stop once this time limit is exceeded. Defaults to `5 * 60 * 1000` (5 minutes).
+
+:::
+
+::: info
+The `link` can be any supported oRPC link, such as [RPCLink](/docs/client/rpc-link), [OpenAPILink](/docs/openapi/client/openapi-link), or custom implementations.
+:::

packages/client/src/plugins/index.ts

@@ -1,4 +1,5 @@
 export * from './batch'
 export * from './dedupe-requests'
 export * from './retry'
+export * from './retry-after'
 export * from './simple-csrf-protection'

packages/client/src/plugins/retry-after.test.ts

@@ -0,0 +1,307 @@
+import type { StandardLazyResponse } from '@orpc/standard-server'
+import { StandardLink } from '../adapters/standard'
+import { RetryAfterPlugin } from './retry-after'
+
+describe('retryAfterPlugin', () => {
+  const signal1 = AbortSignal.timeout(10000)
+
+  const encode = vi.fn(async (path, input, { signal }): Promise<any> => ({
+    url: new URL(`http://localhost/${path.join('/')}`),
+    method: 'GET',
+    headers: {},
+    body: input,
+    signal,
+  }))
+
+  const decode = vi.fn(async (response): Promise<unknown> => response.body())
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+    vi.useFakeTimers()
+  })
+
+  afterEach(() => {
+    expect(vi.getTimerCount()).toBe(0)
+    vi.useRealTimers()
+  })
+
+  describe('core behavior', () => {
+    it('should retry on 429/503 with retry-after header and succeed', async () => {
+      let callCount = 0
+      const clientCall = vi.fn(async () => {
+        callCount++
+        if (callCount === 1) {
+          return {
+            status: 429,
+            headers: { 'retry-after': '2' },
+            body: async () => 'rate limited',
+          } satisfies StandardLazyResponse
+        }
+        return {
+          status: 200,
+          headers: {},
+          body: async () => 'success',
+        } satisfies StandardLazyResponse
+      })
+
+      const link = new StandardLink({ encode, decode }, { call: clientCall }, {
+        plugins: [new RetryAfterPlugin()],
+      })
+
+      const promise = link.call(['test'], 'input', { context: {}, signal: signal1 })
+      await vi.runAllTimersAsync()
+
+      expect(await promise).toBe('success')
+      expect(clientCall).toHaveBeenCalledTimes(2)
+    })
+
+    it('should not retry without retry-after header or on non-retryable status', async () => {
+      const testCases = [
+        { status: 200, headers: {}, body: 'success' },
+        { status: 429, headers: {}, body: 'rate limited' },
+        { status: 500, headers: { 'retry-after': '1' }, body: 'internal error' },
+      ]
+
+      for (const { status, headers, body } of testCases) {
+        const clientCall = vi.fn(async () => ({
+          status,
+          headers,
+          body: async () => body,
+        } satisfies StandardLazyResponse))
+
+        const link = new StandardLink({ encode, decode }, { call: clientCall }, {
+          plugins: [new RetryAfterPlugin()],
+        })
+
+        const result = await link.call(['test'], 'input', { context: {}, signal: signal1 })
+
+        expect(result).toBe(body)
+        expect(clientCall).toHaveBeenCalledTimes(1)
+        vi.clearAllMocks()
+      }
+    })
+  })
+
+  describe('retry-after parsing', () => {
+    it('should parse various retry-after formats', async () => {
+      const testCases = [
+        { value: '3', description: 'seconds' },
+        { value: new Date(Date.now() + 5000).toUTCString(), description: 'HTTP date' },
+        { value: '  2  ', description: 'whitespace' },
+      ]
+
+      for (const { value, description } of testCases) {
+        let callCount = 0
+        const clientCall = vi.fn(async () => {
+          callCount++
+          if (callCount === 1) {
+            return {
+              status: 429,
+              headers: { 'retry-after': value },
+              body: async () => 'rate limited',
+            } satisfies StandardLazyResponse
+          }
+          return {
+            status: 200,
+            headers: {},
+            body: async () => 'success',
+          } satisfies StandardLazyResponse
+        })
+
+        const link = new StandardLink({ encode, decode }, { call: clientCall }, {
+          plugins: [new RetryAfterPlugin()],
+        })
+
+        const promise = link.call(['test'], 'input', { context: {}, signal: signal1 })
+        await vi.runAllTimersAsync()
+
+        expect(await promise).toBe('success')
+        expect(clientCall).toHaveBeenCalledTimes(2)
+        vi.clearAllMocks()
+      }
+    })
+
+    it('should not retry on invalid retry-after values', async () => {
+      const invalidValues = ['invalid', '']
+
+      for (const value of invalidValues) {
+        const clientCall = vi.fn(async () => ({
+          status: 429,
+          headers: { 'retry-after': value },
+          body: async () => 'rate limited',
+        } satisfies StandardLazyResponse))
+
+        const link = new StandardLink({ encode, decode }, { call: clientCall }, {
+          plugins: [new RetryAfterPlugin()],
+        })
+
+        const result = await link.call(['test'], 'input', { context: {}, signal: signal1 })
+
+        expect(result).toBe('rate limited')
+        expect(clientCall).toHaveBeenCalledTimes(1)
+        vi.clearAllMocks()
+      }
+    })
+  })
+
+  describe('maxAttempts', () => {
+    it('should respect maxAttempts (static and dynamic)', async () => {
+      const testCases = [
+        { maxAttempts: undefined, expected: 3, description: 'default' },
+        { maxAttempts: 5, expected: 5, description: 'custom' },
+        { maxAttempts: vi.fn(() => 2), expected: 2, description: 'dynamic' },
+      ]
+
+      for (const { maxAttempts, expected, description } of testCases) {
+        const clientCall = vi.fn(async () => ({
+          status: 429,
+          headers: { 'retry-after': '0' },
+          body: async () => 'rate limited',
+        } satisfies StandardLazyResponse))
+
+        const link = new StandardLink({ encode, decode }, { call: clientCall }, {
+          plugins: [new RetryAfterPlugin(maxAttempts !== undefined ? { maxAttempts } : {})],
+        })
+
+        const promise = link.call(['test'], 'input', { context: {}, signal: signal1 })
+        await vi.runAllTimersAsync()
+
+        expect(await promise).toBe('rate limited')
+        expect(clientCall).toHaveBeenCalledTimes(expected)
+
+        if (typeof maxAttempts === 'function') {
+          expect(maxAttempts).toHaveBeenCalledWith(
+            expect.objectContaining({ status: 429 }),
+            expect.objectContaining({ context: {} }),
+          )
+        }
+
+        vi.clearAllMocks()
+      }
+    })
+  })
+
+  describe('timeout and custom condition', () => {
+    it('should stop retrying after timeout', async () => {
+      const clientCall = vi.fn(async () => ({
+        status: 429,
+        headers: { 'retry-after': '3' },
+        body: async () => 'rate limited',
+      } satisfies StandardLazyResponse))
+
+      const link = new StandardLink({ encode, decode }, { call: clientCall }, {
+        plugins: [new RetryAfterPlugin({ timeout: 5000 })],
+      })
+
+      const promise = link.call(['test'], 'input', { context: {}, signal: signal1 })
+      await vi.runAllTimersAsync()
+
+      expect(await promise).toBe('rate limited')
+      expect(clientCall).toHaveBeenCalledTimes(2)
+    })
+
+    it('should support dynamic timeout function', async () => {
+      const clientCall = vi.fn(async () => ({
+        status: 429,
+        headers: { 'retry-after': '2' },
+        body: async () => 'rate limited',
+      } satisfies StandardLazyResponse))
+
+      const timeoutFn = vi.fn(() => 3000)
+
+      const link = new StandardLink({ encode, decode }, { call: clientCall }, {
+        plugins: [new RetryAfterPlugin({ timeout: timeoutFn })],
+      })
+
+      const promise = link.call(['test'], 'input', { context: {}, signal: signal1 })
+      await vi.runAllTimersAsync()
+
+      expect(await promise).toBe('rate limited')
+      expect(clientCall).toHaveBeenCalledTimes(2)
+      expect(timeoutFn).toHaveBeenCalledWith(
+        expect.objectContaining({ status: 429 }),
+        expect.objectContaining({ context: {}, signal: signal1 }),
+      )
+    })
+
+    it('should respect custom condition function', async () => {
+      let callCount = 0
+      const clientCall = vi.fn(async () => {
+        callCount++
+        if (callCount === 1) {
+          return {
+            status: 400,
+            headers: { 'retry-after': '1' },
+            body: async () => 'bad request',
+          } satisfies StandardLazyResponse
+        }
+        return {
+          status: 200,
+          headers: {},
+          body: async () => 'success',
+        } satisfies StandardLazyResponse
+      })
+
+      const condition = vi.fn((response: StandardLazyResponse) => response.status === 400)
+
+      const link = new StandardLink({ encode, decode }, { call: clientCall }, {
+        plugins: [new RetryAfterPlugin({ condition })],
+      })
+
+      const promise = link.call(['test'], 'input', { context: {}, signal: signal1 })
+      await vi.runAllTimersAsync()
+
+      expect(await promise).toBe('success')
+      expect(clientCall).toHaveBeenCalledTimes(2)
+      expect(condition).toHaveBeenCalledWith(
+        expect.objectContaining({ status: 400 }),
+        expect.objectContaining({ context: {}, signal: signal1 }),
+      )
+    })
+  })
+
+  describe('signal handling', () => {
+    it('should stop retrying when signal is aborted during delay', async () => {
+      const clientCall = vi.fn(async () => ({
+        status: 429,
+        headers: { 'retry-after': '5' },
+        body: async () => 'rate limited',
+      } satisfies StandardLazyResponse))
+
+      const controller = new AbortController()
+
+      const link = new StandardLink({ encode, decode }, { call: clientCall }, {
+        plugins: [new RetryAfterPlugin()],
+      })
+
+      const promise = link.call(['test'], 'input', { context: {}, signal: controller.signal })
+
+      await vi.advanceTimersByTimeAsync(2000)
+      controller.abort()
+      await vi.advanceTimersByTimeAsync(3000)
+
+      expect(await promise).toBe('rate limited')
+      expect(clientCall).toHaveBeenCalledTimes(1)
+    })
+
+    it('should not retry if signal is already aborted', async () => {
+      const clientCall = vi.fn(async () => ({
+        status: 429,
+        headers: { 'retry-after': '1' },
+        body: async () => 'rate limited',
+      } satisfies StandardLazyResponse))
+
+      const controller = new AbortController()
+      controller.abort()
+
+      const link = new StandardLink({ encode, decode }, { call: clientCall }, {
+        plugins: [new RetryAfterPlugin()],
+      })
+
+      const result = await link.call(['test'], 'input', { context: {}, signal: controller.signal })
+
+      expect(result).toBe('rate limited')
+      expect(clientCall).toHaveBeenCalledTimes(1)
+    })
+  })
+})