feat(client, contract, openapi): support 3xx response (#304)

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

- **Documentation**
- Introduced a new “Redirect Response” page in the OpenAPI docs with an
updated sidebar for easier navigation.
  
- **New Features**
- Enhanced HTTP redirect handling to offer more precise control over
redirection.
- Improved error response validations for clearer, more reliable
feedback.
  
- **Bug Fixes**
- Updated error handling logic to provide more accurate status code
validations.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: unnoq

apps/content/.vitepress/config.ts

@@ -191,6 +191,7 @@ export default defineConfig({
           text: 'Advanced',
           collapsed: true,
           items: [
+            { text: 'Redirect Response', link: '/docs/openapi/advanced/redirect-response' },
             { text: 'OpenAPI JSON Serializer', link: '/docs/openapi/advanced/openapi-json-serializer' },
           ],
         },

apps/content/docs/openapi/advanced/redirect-response.md

@@ -0,0 +1,33 @@
+---
+title: Redirect Response
+description: Standard HTTP redirect response in oRPC OpenAPI.
+---
+
+# Redirect Response
+
+Easily return a standard HTTP redirect response in oRPC OpenAPI.
+
+## Basic Usage
+
+By combining the `successStatus` and `outputStructure` options, you can return a standard HTTP redirect response.
+
+```ts
+const redirect = os
+  .route({
+    method: 'GET',
+    path: '/redirect',
+    successStatus: 307, // [!code highlight]
+    outputStructure: 'detailed' // [!code highlight]
+  })
+  .handler(async () => {
+    return {
+      headers: {
+        location: 'https://orpc.unnoq.com', // [!code highlight]
+      },
+    }
+  })
+```
+
+## Limitations
+
+When invoking a redirect procedure with [OpenAPILink](/docs/openapi/client/openapi-link), oRPC treats the redirect as a normal response rather than following it. Some environments, such as browsers, may restrict access to the redirect response, **potentially causing errors**. In contrast, server environments like Node.js handle this without issue.

packages/client/src/adapters/fetch/index.ts

@@ -1,3 +1,2 @@
 export * from './link-fetch-client'
 export * from './rpc-link'
-export * from './types'

packages/client/src/adapters/fetch/link-fetch-client.test.ts

@@ -40,7 +40,7 @@ describe('linkFetchClient', () => {
     expect(fetch).toBeCalledTimes(1)
     expect(fetch).toBeCalledWith(
       toFetchRequestSpy.mock.results[0]!.value,
-      {},
+      { redirect: 'manual' },
       options,
       ['example'],
       { body: true },

packages/client/src/adapters/fetch/link-fetch-client.ts

@@ -7,7 +7,7 @@ import { toFetchRequest, toStandardLazyResponse } from '@orpc/standard-server-fe
 export interface LinkFetchClientOptions<T extends ClientContext> extends ToFetchRequestOptions {
   fetch?: (
     request: Request,
-    init: Record<never, never>,
+    init: { redirect?: Request['redirect'] },
     options: ClientOptions<T>,
     path: readonly string[],
     input: unknown
@@ -26,7 +26,7 @@ export class LinkFetchClient<T extends ClientContext> implements StandardLinkCli
   async call(request: StandardRequest, options: ClientOptions<T>, path: readonly string[], input: unknown): Promise<StandardLazyResponse> {
     const fetchRequest = toFetchRequest(request, this.toFetchRequestOptions)
 
-    const fetchResponse = await this.fetch(fetchRequest, {}, options, path, input)
+    const fetchResponse = await this.fetch(fetchRequest, { redirect: 'manual' }, options, path, input)
 
     const lazyResponse = toStandardLazyResponse(fetchResponse)
 

packages/client/src/adapters/fetch/types.ts

@@ -1,9 +1,11 @@
 import * as StandardServer from '@orpc/standard-server'
-import { ORPCError } from '../../error'
+import * as ErrorModule from '../../error'
 import { StandardRPCJsonSerializer } from './rpc-json-serializer'
 import { StandardRPCLinkCodec } from './rpc-link-codec'
 import { StandardRPCSerializer } from './rpc-serializer'
 
+const ORPCError = ErrorModule.ORPCError
+const isORPCErrorStatusSpy = vi.spyOn(ErrorModule, 'isORPCErrorStatus')
 const mergeStandardHeadersSpy = vi.spyOn(StandardServer, 'mergeStandardHeaders')
 
 beforeEach(() => {
@@ -121,6 +123,9 @@ describe('standardRPCLinkCodec', () => {
 
       expect(deserializeSpy).toBeCalledTimes(1)
       expect(deserializeSpy).toBeCalledWith(serialized)
+
+      expect(isORPCErrorStatusSpy).toBeCalledTimes(1)
+      expect(isORPCErrorStatusSpy).toBeCalledWith(200)
     })
 
     it('should decode error', async () => {
@@ -144,6 +149,9 @@ describe('standardRPCLinkCodec', () => {
 
       expect(deserializeSpy).toBeCalledTimes(1)
       expect(deserializeSpy).toBeCalledWith(serialized)
+
+      expect(isORPCErrorStatusSpy).toBeCalledTimes(1)
+      expect(isORPCErrorStatusSpy).toBeCalledWith(499)
     })
 
     it('error: Cannot parse response body', async () => {

packages/client/src/adapters/standard/rpc-link-codec.test.ts

@@ -3,7 +3,7 @@ import type { StandardRPCSerializer } from './rpc-serializer'
 import type { StandardLinkCodec } from './types'
 import { isAsyncIteratorObject, stringifyJSON, value, type Value } from '@orpc/shared'
 import { mergeStandardHeaders, type StandardHeaders, type StandardLazyResponse, type StandardRequest } from '@orpc/standard-server'
-import { ORPCError } from '../../error'
+import { isORPCErrorStatus, ORPCError } from '../../error'
 import { toHttpPath } from './utils'
 
 export interface StandardRPCLinkCodecOptions<T extends ClientContext> {
@@ -117,7 +117,7 @@ export class StandardRPCLinkCodec<T extends ClientContext> implements StandardLi
   }
 
   async decode(response: StandardLazyResponse): Promise<unknown> {
-    const isOk = response.status >= 200 && response.status < 300
+    const isOk = !isORPCErrorStatus(response.status)
 
     const deserialized = await (async () => {
       let isBodyOk = false

packages/client/src/adapters/standard/rpc-link-codec.ts

@@ -1,4 +1,4 @@
-import { fallbackORPCErrorMessage, fallbackORPCErrorStatus, isDefinedError, ORPCError, toORPCError } from './error'
+import { fallbackORPCErrorMessage, fallbackORPCErrorStatus, isDefinedError, isORPCErrorStatus, ORPCError, toORPCError } from './error'
 
 it('fallbackORPCErrorStatus', () => {
   expect(fallbackORPCErrorStatus('BAD_GATEWAY', 500)).toBe(500)
@@ -42,9 +42,9 @@ describe('oRPCError', () => {
 
   it('oRPCError throw when invalid status', () => {
     expect(() => new ORPCError('BAD_GATEWAY', { status: 200 })).toThrowError()
-    expect(() => new ORPCError('BAD_GATEWAY', { status: 299 })).toThrowError()
+    expect(() => new ORPCError('BAD_GATEWAY', { status: 399 })).toThrowError()
 
-    expect(() => new ORPCError('BAD_GATEWAY', { status: 300 })).not.toThrowError()
+    expect(() => new ORPCError('BAD_GATEWAY', { status: 400 })).not.toThrowError()
     expect(() => new ORPCError('BAD_GATEWAY', { status: 199 })).not.toThrowError()
   })
 
@@ -107,3 +107,12 @@ it('toORPCError', () => {
     return true
   })
 })
+
+it('isORPCErrorStatus', () => {
+  expect(isORPCErrorStatus(200)).toBe(false)
+  expect(isORPCErrorStatus(399)).toBe(false)
+
+  expect(isORPCErrorStatus(400)).toBe(true)
+  expect(isORPCErrorStatus(499)).toBe(true)
+  expect(isORPCErrorStatus(199)).toBe(true)
+})

packages/client/src/error.test.ts

@@ -104,8 +104,8 @@ export class ORPCError<TCode extends ORPCErrorCode, TData> extends Error {
   readonly data: TData
 
   constructor(code: TCode, ...[options]: MaybeOptionalOptions<ORPCErrorOptions<TData>>) {
-    if (options?.status && (options.status >= 200 && options.status < 300)) {
-      throw new Error('[ORPCError] The error status code must not be in the 200-299 range.')
+    if (options?.status && !isORPCErrorStatus(options.status)) {
+      throw new Error('[ORPCError] Invalid error status code.')
     }
 
     const message = fallbackORPCErrorMessage(code, options?.message)
@@ -173,3 +173,7 @@ export function toORPCError(error: unknown): ORPCError<any, any> {
       cause: error,
     })
 }
+
+export function isORPCErrorStatus(status: number): boolean {
+  return status < 200 || status >= 400
+}

packages/client/src/error.ts

@@ -1,34 +1,62 @@
+import * as ClientModule from '@orpc/client'
 import { ping, pong } from '../tests/shared'
 import { ContractProcedure, isContractProcedure } from './procedure'
 
+const isORPCErrorStatusSpy = vi.spyOn(ClientModule, 'isORPCErrorStatus')
+
+beforeEach(() => {
+  vi.clearAllMocks()
+})
+
 describe('contractProcedure', () => {
-  it('throws error when route.successStatus is not between 200 and 299', () => {
-    expect(
-      () => new ContractProcedure({ ...ping['~orpc'], route: { successStatus: 100 } }),
-    ).toThrowError()
+  it('throws error when route.successStatus is invalid', () => {
+    isORPCErrorStatusSpy.mockReturnValueOnce(true)
+
     expect(
-      () => new ContractProcedure({ ...ping['~orpc'], route: { successStatus: 300 } }),
+      () => new ContractProcedure({ ...ping['~orpc'], route: { successStatus: 1999 } }),
     ).toThrowError()
+
+    expect(isORPCErrorStatusSpy).toHaveBeenCalledTimes(1)
+    expect(isORPCErrorStatusSpy).toHaveBeenCalledWith(1999)
+
+    isORPCErrorStatusSpy.mockClear()
+    isORPCErrorStatusSpy.mockReturnValueOnce(false)
+
     expect(
-      () => new ContractProcedure({ ...ping['~orpc'], route: { successStatus: 299 } }),
+      () => new ContractProcedure({ ...ping['~orpc'], route: { successStatus: 2000 } }),
     ).not.toThrowError()
+
+    expect(isORPCErrorStatusSpy).toHaveBeenCalledTimes(1)
+    expect(isORPCErrorStatusSpy).toHaveBeenCalledWith(2000)
   })
 
   it('throws error when errorMap has invalid status code', () => {
+    isORPCErrorStatusSpy.mockReturnValueOnce(false)
+
     expect(
       () => new ContractProcedure({
         ...ping['~orpc'],
-        errorMap: { BAD_GATEWAY: { status: 100 } },
+        errorMap: { BAD_GATEWAY: { status: 200 } },
       }),
     ).toThrowError()
+
+    expect(isORPCErrorStatusSpy).toHaveBeenCalledTimes(1)
+    expect(isORPCErrorStatusSpy).toHaveBeenCalledWith(200)
+
+    isORPCErrorStatusSpy.mockClear()
+    isORPCErrorStatusSpy.mockReturnValueOnce(true)
+
     expect(
       () => new ContractProcedure({
         ...ping['~orpc'],
         errorMap: {
-          BAD_GATEWAY: { status: 600 },
+          BAD_GATEWAY: { status: 500 },
         },
       }),
-    ).toThrowError()
+    ).not.toThrowError()
+
+    expect(isORPCErrorStatusSpy).toHaveBeenCalledTimes(1)
+    expect(isORPCErrorStatusSpy).toHaveBeenCalledWith(500)
   })
 })
 

packages/contract/src/procedure.test.ts

@@ -2,6 +2,7 @@ import type { ErrorMap } from './error'
 import type { Meta } from './meta'
 import type { Route } from './route'
 import type { AnySchema } from './schema'
+import { isORPCErrorStatus } from '@orpc/client'
 
 export interface ContractProcedureDef<
   TInputSchema extends AnySchema,
@@ -25,12 +26,12 @@ export class ContractProcedure<
   '~orpc': ContractProcedureDef<TInputSchema, TOutputSchema, TErrorMap, TMeta>
 
   constructor(def: ContractProcedureDef<TInputSchema, TOutputSchema, TErrorMap, TMeta>) {
-    if (def.route?.successStatus && (def.route.successStatus < 200 || def.route?.successStatus > 299)) {
-      throw new Error('[ContractProcedure] The successStatus must be between 200 and 299')
+    if (def.route?.successStatus && isORPCErrorStatus(def.route.successStatus)) {
+      throw new Error('[ContractProcedure] Invalid successStatus.')
     }
 
-    if (Object.values(def.errorMap).some(val => val && val.status && (val.status < 400 || val.status > 599))) {
-      throw new Error('[ContractProcedure] The error status code must be in the 400-599 range.')
+    if (Object.values(def.errorMap).some(val => val && val.status && !isORPCErrorStatus(val.status))) {
+      throw new Error('[ContractProcedure] Invalid error status code.')
     }
 
     this['~orpc'] = def

packages/contract/src/procedure.ts

@@ -1,11 +1,13 @@
-import { ORPCError } from '@orpc/client'
+import * as ClientModule from '@orpc/client'
 import * as StandardServer from '@orpc/standard-server'
 import { oc } from '../../../../contract/src/builder'
 import { StandardBracketNotationSerializer } from './bracket-notation'
 import { StandardOpenAPIJsonSerializer } from './openapi-json-serializer'
 import { StandardOpenapiLinkCodec } from './openapi-link-codec'
 import { StandardOpenAPISerializer } from './openapi-serializer'
 
+const ORPCError = ClientModule.ORPCError
+const isORPCErrorStatusSpy = vi.spyOn(ClientModule, 'isORPCErrorStatus')
 const mergeStandardHeadersSpy = vi.spyOn(StandardServer, 'mergeStandardHeaders')
 
 beforeEach(() => {
@@ -282,6 +284,9 @@ describe('standardOpenapiLinkCodecOptions', () => {
 
       expect(deserialize).toHaveBeenCalledTimes(1)
       expect(deserialize).toHaveBeenCalledWith(form)
+
+      expect(isORPCErrorStatusSpy).toHaveBeenCalledTimes(1)
+      expect(isORPCErrorStatusSpy).toHaveBeenCalledWith(201)
     })
 
     it('outputStructure=detailed', async () => {
@@ -300,6 +305,46 @@ describe('standardOpenapiLinkCodecOptions', () => {
 
       expect(deserialize).toHaveBeenCalledTimes(1)
       expect(deserialize).toHaveBeenCalledWith(form)
+
+      expect(isORPCErrorStatusSpy).toHaveBeenCalledTimes(1)
+      expect(isORPCErrorStatusSpy).toHaveBeenCalledWith(201)
+    })
+
+    it('deserialize error', async () => {
+      const codec = new StandardOpenapiLinkCodec({ ping: oc }, serializer, {
+        url: 'http://localhost:3000',
+      })
+
+      await expect(codec.decode({
+        headers: { 'x-custom': 'value' },
+        body: async () => new ORPCError('BAD_GATEWAY', { status: 501, message: 'message', data: 'data' }).toJSON(),
+        status: 501,
+      }, { context: {}, signal }, ['ping'])).rejects.toSatisfy((error: any) => {
+        expect(error).toBeInstanceOf(ORPCError)
+        expect(error.code).toEqual('BAD_GATEWAY')
+        expect(error.status).toBe(501)
+        expect(error.message).toBe('message')
+        expect(error.data).toBe('data')
+
+        return true
+      })
+
+      await expect(codec.decode({
+        headers: { 'x-custom': 'value' },
+        body: async () => ({ something: 'data' }),
+        status: 409,
+      }, { context: {}, signal }, ['ping'])).rejects.toSatisfy((error: any) => {
+        expect(error).toBeInstanceOf(ORPCError)
+        expect(error.code).toEqual('MALFORMED_ORPC_ERROR_RESPONSE')
+        expect(error.status).toBe(409)
+        expect(error.data).toEqual({ something: 'data' })
+
+        return true
+      })
+
+      expect(isORPCErrorStatusSpy).toHaveBeenCalledTimes(2)
+      expect(isORPCErrorStatusSpy).toHaveBeenCalledWith(501)
+      expect(isORPCErrorStatusSpy).toHaveBeenCalledWith(409)
     })
 
     it('throw if not found a procedure', async () => {
@@ -341,38 +386,5 @@ describe('standardOpenapiLinkCodecOptions', () => {
         status: 201,
       }, { context: {}, signal }, ['ping'])).rejects.toThrow('Invalid OpenAPI response format.')
     })
-
-    it('deserialize error', async () => {
-      const codec = new StandardOpenapiLinkCodec({ ping: oc }, serializer, {
-        url: 'http://localhost:3000',
-      })
-
-      await expect(codec.decode({
-        headers: { 'x-custom': 'value' },
-        body: async () => new ORPCError('BAD_GATEWAY', { status: 501, message: 'message', data: 'data' }).toJSON(),
-        status: 501,
-      }, { context: {}, signal }, ['ping'])).rejects.toSatisfy((error: any) => {
-        expect(error).toBeInstanceOf(ORPCError)
-        expect(error.code).toEqual('BAD_GATEWAY')
-        expect(error.status).toBe(501)
-        expect(error.message).toBe('message')
-        expect(error.data).toBe('data')
-
-        return true
-      })
-
-      await expect(codec.decode({
-        headers: { 'x-custom': 'value' },
-        body: async () => ({ something: 'data' }),
-        status: 409,
-      }, { context: {}, signal }, ['ping'])).rejects.toSatisfy((error: any) => {
-        expect(error).toBeInstanceOf(ORPCError)
-        expect(error.code).toEqual('MALFORMED_ORPC_ERROR_RESPONSE')
-        expect(error.status).toBe(409)
-        expect(error.data).toEqual({ something: 'data' })
-
-        return true
-      })
-    })
   })
 })