feat(server): describe batch binary responses with a dedicated content type (#1761)

dinwwwh · web-flow · commit f53bafa152d4 · 2026-08-02T09:02:28.000+07:00
Batch responses that use the length-prefixed binary framing — streaming
mode, and buffered mode when a sub-response carries binary — now
advertise `application/vnd.orpc.batch` instead of falling back to
`application/octet-stream`. Batch traffic is now distinguishable from
ordinary file transfers in proxy logs, CDN rules, and dev tools, where
before it was indistinguishable from any other opaque byte stream.

`application/octet-stream` means "unknown bytes" and was never chosen
for batch — it is what the adapter fills in for any `ReadableStream`
body with no content type set. The framing is a format oRPC defines, so
it gets a name.

## Compatibility

Nothing changes on the wire. Clients resolve the batch body from the
`standard-server` hint (`octet-stream` / `file`), not from
`content-type`, so old clients read new servers and new clients read old
servers. Compression behavior is also unchanged: the new type sits
outside the compressible allow-list, exactly like the old one, so batch
bodies are still passed through untouched.

A `+json` suffix was considered and rejected — it would assert the whole
body is JSON (it is binary length prefixes wrapping JSON, sometimes with
raw binary appended), and it would pull streaming batches into
`CompressionStream`, which does not sync-flush per chunk and would hold
frames back instead of delivering them as each sub-request completes.

The all-JSON buffered path is untouched and still serializes as
`application/json`. In streaming mode the plugin's content type wins
over the `headers` option, matching buffered mode, which already
hardcodes the type on the `Blob`.

## Testing

Both framing paths assert the new header. Full root suite passes (2772
passed, 41 skipped), along with `pnpm type:check` across all packages
and `pnpm lint`.
diff --git a/packages/server/src/plugins/batch.test.ts b/packages/server/src/plugins/batch.test.ts
@@ -118,6 +118,7 @@ describe('batchHandlerPlugin', () => {
 
       expect(response!.status).toBe(207)
       expect(response!.headers.get('standard-server')).toEqual('file')
+      expect(response!.headers.get('content-type')).toEqual('application/vnd.orpc.batch')
 
       const buffer = new Uint8Array(await response!.arrayBuffer())
       expect(buffer.length).toBeGreaterThan(4)
@@ -212,6 +213,7 @@ describe('batchHandlerPlugin', () => {
       expect(matched).toBe(true)
       expect(response!.status).toBe(207)
       expect(response!.headers.get('standard-server')).toEqual('octet-stream')
+      expect(response!.headers.get('content-type')).toEqual('application/vnd.orpc.batch')
 
       expect(handlerFn).toHaveBeenCalledTimes(0)
 
diff --git a/packages/server/src/plugins/batch.ts b/packages/server/src/plugins/batch.ts
@@ -8,6 +8,15 @@ import { toArray, value } from '@orpc/shared'
 import { flattenStandardHeader, parseStandardUrl } from '@standardserver/core'
 import { encodePeerMessage, isClientPeerSendMessage, ServerPeer } from '@standardserver/peer'
 
+/**
+ * Content type for batch responses that use the length-prefixed binary framing
+ * (streaming mode, and buffered mode when any sub-response contains binary).
+ *
+ * Decoding is driven by the `standard-server` body hint, not this header,
+ * so it only serves to describe the payload to logs, proxies, and dev tools.
+ */
+export const BATCH_CONTENT_TYPE = 'application/vnd.orpc.batch'
+
 export interface BatchHandlerPluginOptions<T extends Context> {
   /**
    * The max size of the batch allowed.
@@ -216,7 +225,7 @@ export class BatchHandlerPlugin<T extends Context> implements StandardHandlerPlu
             response: {
               status,
               headers,
-              body: new Blob(chunks, { type: 'application/octet-stream' }),
+              body: new Blob(chunks, { type: BATCH_CONTENT_TYPE }),
             },
           }
         }
@@ -294,7 +303,11 @@ export class BatchHandlerPlugin<T extends Context> implements StandardHandlerPlu
 
       return {
         matched: true,
-        response: { status, headers, body: stream },
+        response: {
+          status,
+          headers: { ...headers, 'content-type': BATCH_CONTENT_TYPE },
+          body: stream,
+        },
       }
     }
 
