feat(rpc,openapi): add end-to-end HTTP QUERY support (#1844)

Fixes #1841

This PR adds end-to-end support for the HTTP `QUERY` method across oRPC
RPC links, OpenAPI routes, request deduplication, batching, CORS, and
tests.

[`QUERY` is defined by RFC
10008](https://www.rfc-editor.org/rfc/rfc10008.html) as a safe and
idempotent method that carries query input in the request body. It fills
the gap between `GET`, which is safe but puts input in the URL, and
`POST`, which supports a body but does not communicate safe or
idempotent semantics.

---------

Co-authored-by: Dinh Le <dinwwwh@gmail.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Author: 3 people

apps/content/docs/openapi/specification.mdx

@@ -131,7 +131,7 @@ In this example, the final `tags` is `undefined`, so no tags are applied to `exa
 
 ## OpenAPI Generator
 
-`OpenAPIGenerator` accepts either a [contract](/docs/contract/router) or a [router](/docs/router) and generates an OpenAPI 3.1 document.
+`OpenAPIGenerator` accepts either a [contract](/docs/contract/router) or a [router](/docs/router) and generates an OpenAPI 3.1 document by default. OpenAPI 3.2 is partially supported.
 
 ```ts
 import { OpenAPIGenerator } from '@orpc/openapi'
@@ -153,6 +153,18 @@ const spec = await generator.generate(router, {
 })
 ```
 
+### QUERY method
+
+If your router contains a procedure that uses the `QUERY` method, explicitly set the OpenAPI version to `3.2.0`, because OpenAPI 3.1 does not support `QUERY`.
+
+```ts
+const spec = await generator.generate(router, {
+  base: {
+    openapi: '3.2.0',
+  },
+})
+```
+
 ### Json Schema Converters
 
 `OpenAPIGenerator` relies on JSON Schema converters to translate your input, output, and error schemas into JSON Schemas. oRPC provides dedicated converters through the [Zod](/docs/integrations/zod), [Valibot](/docs/integrations/valibot), and [ArkType](/docs/integrations/arktype) integrations:

apps/content/docs/plugins/cors.mdx

@@ -17,7 +17,7 @@ const handler = new RPCHandler(router, {
   plugins: [
     new CORSHandlerPlugin({
       origin: (origin, options) => origin,
-      allowMethods: ['GET', 'HEAD', 'PUT', 'POST', 'DELETE', 'PATCH'],
+      allowMethods: ['GET', 'HEAD', 'PUT', 'POST', 'DELETE', 'PATCH', 'QUERY'],
       // ...
     }),
   ],

apps/content/docs/plugins/dedupe.mdx

@@ -30,7 +30,7 @@ The `link` can be any supported oRPC link, such as [RPCLink](/docs/rpc/link), [O
 
 ## Filter
 
-By default, the plugin deduplicates only `GET` requests. You can customize this behavior by providing a `filter` function.
+By default, the plugin deduplicates `GET` and `QUERY` requests. You can customize this behavior by providing a `filter` function.
 
 ```ts
 const link = new RPCLink({

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

@@ -0,0 +1,15 @@
+import { RPCLink } from './rpc-link'
+
+describe('RPCLink', () => {
+  it('accepts QUERY only for body-bearing request methods', () => {
+    void new RPCLink({ method: 'QUERY' })
+    void new RPCLink({ method: 'GET', fallbackMethod: 'QUERY' })
+
+    // @ts-expect-error - HEAD is not a supported direct RPC request method
+    void new RPCLink({ method: 'HEAD' })
+    // @ts-expect-error - OPTIONS is not a supported direct RPC request method
+    void new RPCLink({ method: 'OPTIONS' })
+    // @ts-expect-error - GET cannot be used as a body-bearing fallback
+    void new RPCLink({ fallbackMethod: 'GET' })
+  })
+})

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

@@ -56,6 +56,35 @@ describe('rpcLink', () => {
     )
   })
 
+  it('sends QUERY requests with body-encoded input', async () => {
+    const fetch = vi.fn(async () => {
+      return new Response(JSON.stringify({ json: 'pong' }), {
+        status: 200,
+        headers: {
+          'content-type': 'application/json',
+        },
+      })
+    })
+
+    const orpc = createORPCClient(new RPCLink({
+      fetch,
+      method: 'QUERY',
+      origin: 'http://api.example.com',
+    })) as any
+
+    await expect(orpc.ping('input')).resolves.toEqual('pong')
+
+    expect(fetch).toHaveBeenCalledWith(
+      'http://api.example.com/ping',
+      expect.objectContaining({
+        body: JSON.stringify({ json: 'input' }),
+        method: 'QUERY',
+      }),
+      expect.objectContaining({ context: {} }),
+      ['ping'],
+    )
+  })
+
   it('supports custom headers and query parameters in origin', async () => {
     const fetch = vi.fn(async () => {
       return new Response(JSON.stringify({ json: 'pong' }), {

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

@@ -88,6 +88,37 @@ describe('rpcLinkCodec', () => {
       expect(request.url).toBe('/api/ping')
     })
 
+    it('falls back to QUERY with a body when GET url exceeds maxUrlLength', async () => {
+      const codec = new RPCLinkCodec({
+        url: '/api',
+        method: 'GET',
+        maxUrlLength: 10,
+        fallbackMethod: 'QUERY',
+        serializer,
+      })
+
+      const request = await codec.encodeInput('input', ['ping'], { context: {} })
+
+      expect(request.method).toBe('QUERY')
+      expect(request.body).toBe(serializeSpy.mock.results[0]!.value)
+      expect(request.url).toBe('/api/ping')
+    })
+
+    it('falls back to POST by default when GET url exceeds maxUrlLength', async () => {
+      const codec = new RPCLinkCodec({
+        url: '/api',
+        method: 'GET',
+        maxUrlLength: 10,
+        serializer,
+      })
+
+      const request = await codec.encodeInput('input', ['ping'], { context: {} })
+
+      expect(request.method).toBe('POST')
+      expect(request.body).toBe(serializeSpy.mock.results[0]!.value)
+      expect(request.url).toBe('/api/ping')
+    })
+
     it.each([
       ['FormData', () => {
         const f = new FormData()

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

@@ -32,15 +32,15 @@ export interface RPCLinkCodecOptions<T extends ClientContext> {
    *
    * @default 'POST'
    */
-  method?: Value<Promisable<'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'>, [options: ClientOptions<T>, path: string[], input: unknown]>
+  method?: Value<Promisable<'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'QUERY'>, [options: ClientOptions<T>, path: string[], input: unknown]>
 
   /**
    * The method to use when the payload cannot safely pass to the server with method return from method function.
    * GET is not allowed, it's very dangerous.
    *
    * @default 'POST'
    */
-  fallbackMethod?: 'POST' | 'PUT' | 'PATCH' | 'DELETE'
+  fallbackMethod?: 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'QUERY'
 
   /**
    * Inject headers to the request.

packages/client/src/plugins/batch.test.ts

@@ -451,14 +451,14 @@ describe('batchLinkPlugin', () => {
       expect(subResponse1.headers['x-from-batch-response']).toBeUndefined()
     })
 
-    it('separates GET and POST requests into distinct batches', async () => {
+    it('separates GET, QUERY, and unsafe requests into distinct batches', async () => {
       const codec = makeCodec()
       const transport = makeTransport()
 
       let callIndex = 0
       vi.mocked(codec.encodeInput).mockImplementation(async () => {
         callIndex++
-        const method = callIndex <= 2 ? 'GET' : 'POST'
+        const method = callIndex <= 2 ? 'GET' : callIndex <= 4 ? 'QUERY' : 'PUT'
         return {
           method,
           url: `/test-${callIndex}` as `/${string}`,
@@ -484,19 +484,23 @@ describe('batchLinkPlugin', () => {
       await Promise.all([
         link.call(['get1'], {}, { context: {} }),
         link.call(['get2'], {}, { context: {} }),
-        link.call(['post1'], {}, { context: {} }),
-        link.call(['post2'], {}, { context: {} }),
+        link.call(['query1'], {}, { context: {} }),
+        link.call(['query2'], {}, { context: {} }),
+        link.call(['put1'], {}, { context: {} }),
+        link.call(['put2'], {}, { context: {} }),
       ])
 
-      // Should have at least 2 batch calls: one for GET, one for POST
-      expect(transport.send).toHaveBeenCalledTimes(2)
+      expect(transport.send).toHaveBeenCalledTimes(3)
 
       const sentGetRequest = vi.mocked(transport.send).mock.calls.find(([request]) => request.method === 'GET')![0]
-      expect(sentGetRequest).toBeDefined()
+      expect(extractBatchMessagesFromRequest(sentGetRequest).map(message => message.json.method)).toEqual(['GET', 'GET'])
       expect(sentGetRequest.headers['orpc-batch']).toBe('buffered')
 
+      const sentQueryRequest = vi.mocked(transport.send).mock.calls.find(([request]) => request.method === 'QUERY')![0]
+      expect(extractBatchMessagesFromRequest(sentQueryRequest).map(message => message.json.method)).toEqual(['QUERY', 'QUERY'])
+
       const sentPostRequest = vi.mocked(transport.send).mock.calls.find(([request]) => request.method === 'POST')![0]
-      expect(sentPostRequest).toBeDefined()
+      expect(extractBatchMessagesFromRequest(sentPostRequest).map(message => message.json.method)).toEqual(['PUT', 'PUT'])
       expect(sentPostRequest.headers['orpc-batch']).toBe('buffered')
     })
 

packages/client/src/plugins/batch.ts

@@ -217,15 +217,17 @@ export class BatchLinkPlugin<T extends ClientContext> implements StandardLinkPlu
 
     for (const [group, items] of pending) {
       const getItems = items.filter(([options]) => options.request.method === 'GET')
-      const restItems = items.filter(([options]) => options.request.method !== 'GET')
+      const queryItems = items.filter(([options]) => options.request.method === 'QUERY')
+      const unsafeItems = items.filter(([options]) => options.request.method !== 'GET' && options.request.method !== 'QUERY')
 
       this.executeBatch('GET', group, getItems)
-      this.executeBatch('POST', group, restItems)
+      this.executeBatch('QUERY', group, queryItems)
+      this.executeBatch('POST', group, unsafeItems)
     }
   }
 
   private async executeBatch(
-    method: 'GET' | 'POST',
+    method: 'GET' | 'QUERY' | 'POST',
     group: BatchLinkPluginGroup<T>,
     groupItems: typeof this.queue extends Map<any, infer U> ? U : never,
   ): Promise<void> {

packages/client/src/plugins/dedupe.test.ts

@@ -108,6 +108,63 @@ describe('dedupeLinkPlugin', () => {
     }))
   })
 
+  it('dedupes identical QUERY requests by default', async () => {
+    const codec = makeCodec()
+    const transport = makeTransport()
+
+    const link = new StandardLink(codec, transport, {
+      plugins: [new DedupeLinkPlugin({
+        groups: [{ condition: () => true, context: { group: true } }],
+      })],
+    })
+
+    const [output1, output2] = await Promise.all([
+      link.call(['QUERY', 'planet'], { value: 1 }, { context: {} }),
+      link.call(['QUERY', 'planet'], { value: 1 }, { context: {} }),
+    ])
+
+    expect(output1).toBe(output2)
+    expect(transport.send).toHaveBeenCalledTimes(1)
+  })
+
+  it('does not dedupe QUERY requests with different bodies', async () => {
+    const codec = makeCodec()
+    const transport = makeTransport()
+
+    const link = new StandardLink(codec, transport, {
+      plugins: [new DedupeLinkPlugin({
+        groups: [{ condition: () => true, context: { group: true } }],
+      })],
+    })
+
+    const [output1, output2] = await Promise.all([
+      link.call(['QUERY', 'planet'], { value: 1 }, { context: {} }),
+      link.call(['QUERY', 'planet'], { value: 2 }, { context: {} }),
+    ])
+
+    expect(output1).not.toBe(output2)
+    expect(transport.send).toHaveBeenCalledTimes(2)
+  })
+
+  it('does not dedupe unsafe methods by default', async () => {
+    const codec = makeCodec()
+    const transport = makeTransport()
+
+    const link = new StandardLink(codec, transport, {
+      plugins: [new DedupeLinkPlugin({
+        groups: [{ condition: () => true, context: { group: true } }],
+      })],
+    })
+
+    const [output1, output2] = await Promise.all([
+      link.call(['POST', 'planet'], { value: 1 }, { context: {} }),
+      link.call(['POST', 'planet'], { value: 1 }, { context: {} }),
+    ])
+
+    expect(output1).not.toBe(output2)
+    expect(transport.send).toHaveBeenCalledTimes(2)
+  })
+
   it('computes group context from all deduped matching options', async () => {
     const codec = makeCodec()
     const transport = makeTransport()