test(server): plugins (#220)

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

## Summary by CodeRabbit

- **Refactor**
- Streamlined server configuration options for improved consistency and
reliability.
- Enhanced CORS settings to enforce stricter, immutable configurations
ensuring proper header behavior.
  
- **Tests**
- Added comprehensive test coverage to validate plugin integrations,
including composite handling, CORS responses, and custom header
modifications.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: dinwwwh

packages/server/src/adapters/standard/handler.ts

@@ -15,11 +15,11 @@ export type StandardHandleOptions<T extends Context> =
   & { prefix?: HTTPPath }
   & (Record<never, never> extends T ? { context?: T } : { context: T })
 
-export type WellStandardHandleOptions<T extends Context> = StandardHandleOptions<T> & { context: T }
-
 export type StandardHandleResult = { matched: true, response: StandardResponse } | { matched: false, response: undefined }
 
-export type StandardHandlerInterceptorOptions<TContext extends Context> = WellStandardHandleOptions<TContext> & { request: StandardLazyRequest }
+export type StandardHandlerInterceptorOptions<T extends Context> =
+  & StandardHandleOptions<T>
+  & { context: T, request: StandardLazyRequest }
 
 export interface StandardHandlerOptions<TContext extends Context> {
   plugins?: HandlerPlugin<TContext>[]

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

@@ -0,0 +1,16 @@
+import { CompositePlugin } from './base'
+
+it('compositePlugin', () => {
+  const plugin1 = { init: vi.fn() }
+  const plugin2 = {}
+  const plugin3 = { init: vi.fn() }
+
+  const composite = new CompositePlugin([plugin1, plugin2, plugin3])
+
+  composite.init('__OPTIONS__' as any)
+
+  expect(plugin1.init).toHaveBeenCalledTimes(1)
+  expect(plugin1.init).toHaveBeenCalledWith('__OPTIONS__')
+  expect(plugin3.init).toHaveBeenCalledTimes(1)
+  expect(plugin3.init).toHaveBeenCalledWith('__OPTIONS__')
+})

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

@@ -0,0 +1,188 @@
+import { OpenAPIHandler } from '../../../openapi/src/adapters/fetch/openapi-handler'
+import { os } from '../builder'
+import { CORSPlugin } from './cors'
+
+function assertResponse(response: Response | undefined): asserts response is Response {
+  if (!response) {
+    throw new Error('response is undefined')
+  }
+}
+
+beforeEach(() => {
+  vi.clearAllMocks()
+})
+
+describe('corsPlugin', () => {
+  const handlerFn = vi.fn(() => 'pong')
+  const router = os
+    .route({
+      method: 'GET',
+      path: '/ping',
+    })
+    .handler(handlerFn)
+
+  it('handles OPTIONS request with default options', async () => {
+    const handler = new OpenAPIHandler(router, {
+      plugins: [new CORSPlugin()],
+    })
+
+    const { response } = await handler.handle(new Request('https://example.com', {
+      method: 'OPTIONS',
+      headers: {
+        origin: 'https://example.com',
+      },
+    }))
+
+    assertResponse(response)
+    expect(handlerFn).toHaveBeenCalledTimes(0)
+    expect(response.status).toBe(204)
+    expect(response.headers.get('access-control-allow-origin')).toBe('https://example.com')
+    expect(response.headers.get('vary')).toBe('origin')
+    expect(response.headers.get('access-control-allow-methods')).toBe('GET,HEAD,PUT,POST,DELETE,PATCH')
+    expect(response.headers.get('access-control-max-age')).toBeNull()
+  })
+
+  it('handles GET request and sets CORS headers with default origin function', async () => {
+    const handler = new OpenAPIHandler(router, {
+      plugins: [new CORSPlugin()],
+    })
+
+    const { response } = await handler.handle(new Request('https://example.com/ping', {
+      headers: {
+        origin: 'https://example.com',
+      },
+    }))
+
+    assertResponse(response)
+    expect(handlerFn).toHaveBeenCalledTimes(1)
+    expect(response.headers.get('access-control-allow-origin')).toBe('https://example.com')
+    expect(response.headers.get('vary')).toBe('origin')
+  })
+
+  it('applies maxAge and allowHeaders on OPTIONS requests when specified', async () => {
+    const plugin = new CORSPlugin({
+      maxAge: 600,
+      allowHeaders: ['Content-Type', 'Authorization'],
+    })
+
+    const handler = new OpenAPIHandler(router, {
+      plugins: [plugin],
+    })
+
+    const { response } = await handler.handle(new Request('https://example.com/test', {
+      method: 'OPTIONS',
+      headers: {
+        origin: 'https://example.com',
+      },
+    }))
+
+    assertResponse(response)
+    expect(response.headers.get('access-control-max-age')).toBe('600')
+    expect(response.headers.get('access-control-allow-methods')).toBe('GET,HEAD,PUT,POST,DELETE,PATCH')
+    expect(response.headers.get('access-control-allow-headers')).toBe('Content-Type,Authorization')
+  })
+
+  it('sets allowed origin only when custom origin function approves', async () => {
+    // Custom origin function: only allow 'https://allowed.com'
+    const customOrigin = (origin: string) => origin === 'https://allowed.com' ? origin : ''
+    const router = os
+      .route({
+        method: 'GET',
+        path: '/custom',
+      })
+      .handler(() => 'ok')
+
+    const plugin = new CORSPlugin({ origin: customOrigin })
+    const handler = new OpenAPIHandler(router, {
+      plugins: [plugin],
+    })
+
+    // Request from allowed origin
+    const { response } = await handler.handle(new Request('https://example.com/custom', {
+      headers: {
+        origin: 'https://allowed.com',
+      },
+    }))
+    assertResponse(response)
+    expect(response.headers.get('access-control-allow-origin')).toBe('https://allowed.com')
+
+    // Request from a disallowed origin should not get the header set
+    const { response: response2 } = await handler.handle(new Request('https://example.com/custom', {
+      headers: {
+        origin: 'https://disallowed.com',
+      },
+    }))
+    assertResponse(response2)
+    expect(response2.headers.get('access-control-allow-origin')).toBeNull()
+  })
+
+  it('handles timingOrigin option correctly', async () => {
+    // Custom timingOrigin: only allow 'https://timing.com'
+    const customTimingOrigin = (origin: string) => origin === 'https://timing.com' ? origin : ''
+    const router = os
+      .route({
+        method: 'GET',
+        path: '/timing',
+      })
+      .handler(() => 'ok')
+
+    const plugin = new CORSPlugin({ timingOrigin: customTimingOrigin })
+    const handler = new OpenAPIHandler(router, {
+      plugins: [plugin],
+    })
+
+    // Request with allowed timing origin
+    const { response } = await handler.handle(new Request('https://example.com/timing', {
+      headers: {
+        origin: 'https://timing.com',
+      },
+    }))
+    assertResponse(response)
+    expect(response.headers.get('timing-allow-origin')).toBe('https://timing.com')
+
+    // Request with not allowed timing origin should not have the header
+    const { response: response2 } = await handler.handle(new Request('https://example.com/timing', {
+      headers: {
+        origin: 'https://not-timing.com',
+      },
+    }))
+    assertResponse(response2)
+    expect(response2.headers.get('timing-allow-origin')).toBeNull()
+  })
+
+  it('sets credentials and exposeHeaders when specified in options', async () => {
+    const plugin = new CORSPlugin({
+      credentials: true,
+      exposeHeaders: ['X-Custom-Header', 'X-Another-Header'],
+    })
+
+    const handler = new OpenAPIHandler(router, {
+      plugins: [plugin],
+    })
+
+    const { response } = await handler.handle(new Request('https://example.com/ping', {
+      headers: {
+        origin: 'https://example.com',
+      },
+    }))
+    assertResponse(response)
+    expect(response.headers.get('access-control-allow-credentials')).toBe('true')
+    expect(response.headers.get('access-control-expose-headers')).toBe('X-Custom-Header,X-Another-Header')
+  })
+
+  it('returns "*" for access-control-allow-origin when origin function returns "*"', async () => {
+    const plugin = new CORSPlugin({ origin: () => '*' })
+    const handler = new OpenAPIHandler(router, {
+      plugins: [plugin],
+    })
+
+    const { response } = await handler.handle(new Request('https://example.com/ping', {
+      headers: {
+        origin: 'https://any-origin.com',
+      },
+    }))
+    assertResponse(response)
+    expect(response.headers.get('access-control-allow-origin')).toBe('*')
+    expect(response.headers.get('vary')).toBeNull()
+  })
+})

packages/server/src/plugins/cors.ts

@@ -5,19 +5,19 @@ import type { HandlerPlugin } from './base'
 import { value, type Value } from '@orpc/shared'
 
 export interface CORSOptions<TContext extends Context> {
-  origin?: Value<string | string[] | null | undefined, [origin: string, options: StandardHandlerInterceptorOptions<TContext>]>
-  timingOrigin?: Value<string | string[] | null | undefined, [origin: string, options: StandardHandlerInterceptorOptions<TContext>]>
-  allowMethods?: string[]
-  allowHeaders?: string[]
+  origin?: Value<string | readonly string[] | null | undefined, [origin: string, options: StandardHandlerInterceptorOptions<TContext>]>
+  timingOrigin?: Value<string | readonly string[] | null | undefined, [origin: string, options: StandardHandlerInterceptorOptions<TContext>]>
+  allowMethods?: readonly string[]
+  allowHeaders?: readonly string[]
   maxAge?: number
   credentials?: boolean
-  exposeHeaders?: string[]
+  exposeHeaders?: readonly string[]
 }
 
 export class CORSPlugin<TContext extends Context> implements HandlerPlugin<TContext> {
   private readonly options: CORSOptions<TContext>
 
-  constructor(options?: Partial<CORSOptions<TContext>>) {
+  constructor(options: CORSOptions<TContext> = {}) {
     const defaults: CORSOptions<TContext> = {
       origin: origin => origin,
       allowMethods: ['GET', 'HEAD', 'PUT', 'POST', 'DELETE', 'PATCH'],

packages/server/src/plugins/response-headers.test.ts

@@ -0,0 +1,50 @@
+import type { ResponseHeadersPluginContext } from './response-headers'
+import { OpenAPIHandler } from '../../../openapi/src/adapters/fetch/openapi-handler'
+import { os } from '../builder'
+import { ResponseHeadersPlugin } from './response-headers'
+
+it('responseHeadersPlugin', async () => {
+  const router = os
+    .$context<ResponseHeadersPluginContext>()
+    .use(({ context, next }) => {
+      context.resHeaders?.set('x-custom-1', 'mid')
+      context.resHeaders?.set('x-custom-2', 'mid')
+      context.resHeaders?.set('x-custom-3', 'mid')
+      context.resHeaders?.set('x-custom-4', 'mid')
+
+      return next()
+    })
+    .route({
+      method: 'GET',
+      path: '/ping',
+      outputStructure: 'detailed',
+    })
+    .handler(() => {
+      return {
+        headers: {
+          'x-custom-1': 'value',
+          'x-custom-2': ['1', '2'],
+          'x-custom-3': undefined,
+        },
+      }
+    })
+
+  const handler = new OpenAPIHandler(router, {
+    plugins: [
+      new ResponseHeadersPlugin(),
+    ],
+  })
+
+  const { response } = await handler.handle(new Request('https://example.com/ping'))
+
+  if (!response) {
+    throw new Error('response is undefined')
+  }
+
+  expect(response.headers.get('x-custom-1')).toBe('value, mid')
+  expect(response.headers.get('x-custom-2')).toBe('1, 2, mid')
+  expect(response.headers.get('x-custom-3')).toBe('mid')
+  expect(response.headers.get('x-custom-4')).toBe('mid')
+
+  await handler.handle(new Request('https://example.com/not_found'))
+})