Is it possible to return a response from a procedure?

[marbemac]

Basically for "proxy" style use cases. We're trying out https://electric-sql.com and would love to leverage all the existing middleware, logging setup, tracing, etc we've got with oRPC, in proxy scenarios.

Here's an (imperfect but demonstrative) example for electric:

const sync = base.
  // re-use our existing orpc middlewares, logging, etc
  .use(requireAuth)
  // expose a plain http endpoint for electric
  .route({
    method: 'GET',
    path: '/api/sync/threads',
  })
  // electric's standard search params
  .input(z.object({
    live: z.string().optional(),
    handle: z.string().optional(),
    offset: z.string().optional(),
    cursor: z.string().optional(),
  }))
  // proxy the electric sync requests to electric backend
  .handler(async ({ context, input, errors }) => {
    // .. set input params on the url of course.. skipping in this example
    const electricUrl = new URL('http://localhost:4028/v1/shape');

    electricUrl.searchParams.set('table', 'threads');

    // access orpc context as needed...
    // const xyz = context.db.get(foo)

    // proxy the request
    const response = await fetch(electricUrl, {
      cf: { cacheEverything: true },
    });

    if (!response.ok) {
      throw errors.INTERNAL_SERVER_ERROR({ message: `Sync error: ${response.statusText}` });
    }

    return response;
  });

And then use it like so on the client:

const stream = new ShapeStream({
  url: `http://{server w orpc}/api/threads/sync`,
})

[dosubot]

Yes, you can return a raw Response object (like from fetch) directly from an oRPC handler—this is supported by oRPC’s server adapters. This approach works well for proxy-style use cases and lets you leverage all your existing middleware, logging, and tracing. oRPC will forward the status, headers, and body from your Response to the client, so you can proxy HTTP calls, stream responses, and set custom headers as needed.

For streaming scenarios (like SSE or readable streams), you can also return an async generator or event iterator from your handler, which oRPC will handle as a streaming response. Middleware and plugins (such as for compression or logging) will still run as usual in the request pipeline before the handler’s response is sent to the client. Just be aware that some adapters (like node vs fetch) may have subtle differences in how they handle streaming and raw Response objects, so test your use case if you’re targeting multiple environments.

You can see examples and discussion of these patterns in the oRPC repo, including proxying SSE streams with generator functions and handlers returning HTTP Response objects that plugins can intercept.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[marbemac]

omg why don't I just try these things instead of assuming it's not supported if it's not in the docs 🤦‍♂️ . works! closing...

[marbemac]

Hmm actually, I must be missing something still.

With a handler like the below:

const sync = base.
  .route({
    method: 'GET',
    path: '/api/debug',
  })
  .handler(async () => {
    return new Response(JSON.stringify({ hello: 'world' }), {
      status: 200,
      headers: {
        'content-type': 'application/json',
        'x-my-header': 'my-value',
      },
    });
  });

This is what I receive when I make a request to it:

curl -i "https://localhost:3001/api/debug"

HTTP/2 200
vary: Origin
content-length: 2
content-type: application/json
date: Mon, 01 Sep 2025 15:45:40 GMT

{}

Note the empty response and no x-my-header header. In reality electric returns a chunked response, but simplifying here just to get the basics working.

[dosubot]

The most likely cause is handler selection: for manual API calls (like with curl), you should use oRPC's OpenAPIHandler, not RPCHandler. The RPCHandler is designed for oRPC-generated clients and enforces input validation and protocol, which can result in missing headers or body for direct HTTP calls. Switching to OpenAPIHandler should allow your custom headers and body to be returned as expected (source).

Also, recent changes added adapter interceptors and plugins that can modify responses, including headers and body (source, source). If you have plugins like CompressionPlugin enabled, double-check that they aren't stripping or overwriting your custom headers.

So: confirm you're using OpenAPIHandler for direct HTTP endpoints, and review any plugins/interceptors in your oRPC setup that might affect the response.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[marbemac]

Alrighty a little closer - detailed outputStructure covers the simple json case above.

However, setting the body in the detailed output to the response body from a fetch request doesn't seem to work. End up with empty response.

const res = await fetch(electricUrl, { cf: { cacheEverything: true } });

return {
  status: res.status,
  headers: Object.fromEntries(res.headers.entries()),
  body: res.body,
};

Example curl (closer! status and headers coming through, but not body):

HTTP/2 200
vary: accept-encoding
access-control-allow-methods: GET, HEAD, DELETE, OPTIONS
access-control-allow-origin: *
access-control-expose-headers: electric-cursor,electric-handle,electric-offset,electric-schema,electric-up-to-date,electric-internal-known-error
cache-control: public, max-age=604800, s-maxage=3600, stale-while-revalidate=2629746
content-length: 2
content-type: application/json
date: Mon, 01 Sep 2025 16:19:38 GMT
electric-handle: 14619969-1756740024688195
electric-offset: 0_0
electric-server: ElectricSQL/1.1.7
etag: "14619969-1756740024688195:-1:0_0"
x-request-id: GGE0-llyczzcOaQAAAuj

{}

[dosubot]

The reason you get an empty response body is that oRPC's detailed output structure serializes the body using its built-in serializer, which expects a string, object, array, or Blob—not a ReadableStream like fetch's res.body. When you pass res.body directly, the serializer can't process it, so the response is empty (source).

To proxy the response body, you need to convert it to a supported type before returning. For example, if you want to forward JSON:

const res = await fetch(electricUrl, { cf: { cacheEverything: true } });

return {
  status: res.status,
  headers: Object.fromEntries(res.headers.entries()),
  body: await res.json(), // or await res.text() for plain text
};

If you need to support streaming or chunked responses, use oRPC's support for returning a raw Response object from your handler instead of the detailed output structure. This allows oRPC to forward the stream directly to the client (source).

So: for non-streaming proxy, use await res.json() or await res.text(); for streaming, return the Response object itself.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[marbemac]

for streaming, return the Response object itself.

Doesn't seem to work. Maybe could make this work via a plugin, interceptor, adapterInterceptor, or rootInterceptor, but I'm a bit unsure re where to start.

[dosubot]

The reason returning a Response object from your oRPC handler doesn't stream as expected is likely due to how the OpenAPIHandler and its codec serialize handler output. The detailed output structure serializes the body using a built-in serializer, which only supports string, object, array, or Blob—not ReadableStream or Buffer—so passing a stream results in an empty or malformed response body (source).

For streaming proxy scenarios, you can use an interceptor in your OpenAPIHandler setup to manage streaming and abort signals. This approach lets you wrap the streaming response body in an async iterator and ensures cleanup when the client disconnects. Here’s a minimal example:

const handler = new OpenAPIHandler(router, {
  interceptors: [
    async (options) => {
      if (!options.request.signal || options.request.signal.aborted) {
        return options.next()
      }

      const controller = new AbortController()
      options.request.signal.addEventListener('abort', () => controller.abort())

      const result = await options.next({
        ...options,
        request: { ...options.request, signal: controller.signal },
      })

      if (!result.matched || !isAsyncIteratorObject(result.response.body)) {
        return result
      }

      const body = new AsyncIteratorClass(
        async () => (result.response.body as any).next(),
        async () => {
          controller.abort()
          await (result.response.body as any).return?.()
        },
      )

      return { ...result, response: { ...result.response, body } }
    },
  ],
})

This pattern ensures your streaming proxy endpoint works and cleans up resources properly when the stream is terminated (source). If you need to proxy a fetch stream, you may need to adapt the fetch response body into an async iterator or similar construct that oRPC can handle.

If you’re still seeing issues, double-check for plugins or middleware that might be modifying the response, and confirm your runtime/adapter supports streaming pass-through.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[unnoq]

@dosu you are completely incorrect, oRPC handlers do not support to return Response instance for now.

[dosubot]

You're right—oRPC handlers do not currently support returning a native Response instance directly. Handler outputs must be serializable types (like string, object, array, or Blob), and the serialization logic in the OpenAPI adapter will not handle streams or Response objects, which is why attempts to return them result in empty or malformed responses (see code).

For proxying, you need to extract the body from the fetch response as a supported type (e.g., await res.json(), await res.text(), or a Blob) and return that along with status and headers. Streaming and direct Response passthrough aren't supported out of the box—enabling that would require changes to the core adapters and codecs.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[marbemac]

you are completely incorrect, oRPC handlers do not support to return Response instance for now.

😂

@unnoq if you point me in the right direction maybe I can get this done, assuming it can be done within the current capabilities / api of orpc. e.g. what if I replaced OpenAPIHandler w something like a custom ProxyHandler that also extended FetchHandler? ideally with the same functionality around input handling, but none of the output stuff - expectation is to proxy a response object returned form the handler.

I just ran into another issue (using the detailed response approach), electric returns a 409 status code that needs to be passed through to consumer, but the openapi handler seems to turn any non successful status code into a 500 (maybe can override via one of the hooks, but haven't figured out how yet).

[marbemac]

Hey! Quick update on the proxy handler implementation. Tried a few different approaches and wanted to share what worked/didn't work in case it helps others.

Attempt 1: Custom Codec

First tried creating a custom codec that would detect Response objects and pass them through untouched. The problem was that StandardBody doesn't support ReadableStream - it expects things like Blob, FormData, etc. So even when I tried to pass response.body (the stream) through, it would get lost in the serialization process and I'd end up with empty {} responses.

Attempt 2: Adapter Interceptors

Next tried using adapterInterceptors in FetchHandler to intercept after the standard handler ran and re-execute procedures that returned Response objects. This actually worked! But... it meant every request ran the procedure twice. For a proxy use case hitting external services, that's obviously not great - double network requests, potential inconsistency between calls, etc.

Attempt 3: Root Interceptors

Tried using rootInterceptors at the StandardHandler level to intercept before the main processing. Similar issue though - to avoid double execution I tried converting Response → Blob which worked but killed streaming. No good for SSE or large responses.

Final Solution: Extend OpenAPIHandler

What ended up working was extending OpenAPIHandler and overriding the handle method entirely. We skip calling super.handle() and instead access the inherited standardHandler.matcher and standardHandler.codec directly. This lets us:

It's definitely not perfect, and I had to use some private methods, but it's working pretty well atm for the proxy use case.

Just a tiny 3 lines of code that makes the response bit possible.. the rest is basically copied from existing orpc standard fetch handler.

// right before encoding the response and returning, checking this and returning as is if it's a Response
if (output instanceof Response) {
  return { matched: true, response: output };
}

Full:

import { ORPCError, toORPCError } from '@orpc/client';
import { OpenAPIHandler, type OpenAPIHandlerOptions } from '@orpc/openapi/fetch';
import type { Context, HTTPPath, Router } from '@orpc/server';
import { createProcedureClient } from '@orpc/server';
import type { FetchHandleResult } from '@orpc/server/fetch';
import { type FriendlyStandardHandleOptions, resolveFriendlyStandardHandleOptions } from '@orpc/server/standard';
import { intercept, type MaybeOptionalOptions, resolveMaybeOptionalOptions } from '@orpc/shared';
import { toFetchResponse, toStandardLazyRequest } from '@orpc/standard-server-fetch';

// More background on this custom handler here: https://github.com/unnoq/orpc/issues/954

export interface ProxyHandlerOptions<T extends Context> extends OpenAPIHandlerOptions<T> {}

/**
 * A handler that extends OpenAPIHandler but allows procedures to return Response objects directly.
 * When a procedure returns a Response, it passes through untouched (preserving streams, headers, etc).
 * Falls back to standard ORPC encoding for non-Response outputs. Useful for proxy scenarios.
 *
 * Doesn't support everything.. unsupported vs normal orpc openapi handler:
 * - no tracing
 * - no adapter interceptors
 * - no async iterator input support
 * - no standard orpc SSE support (proxied response can SSE of course)
 *
 * BUT it does support proxying responses & most of the orpc input functionality, as well as most interceptors
 */
export class ProxyHandler<T extends Context> extends OpenAPIHandler<T> {
  constructor(router: Router<any, T>, options: NoInfer<ProxyHandlerOptions<T>> = {}) {
    super(router, options);
  }

  override async handle(
    baseRequest: Request,
    ...rest: MaybeOptionalOptions<FriendlyStandardHandleOptions<T>>
  ): Promise<FetchHandleResult> {
    // Access the inherited (but private) StandardHandler's matcher and codec
    const standardHandler = (this as any).standardHandler;
    const interceptors = standardHandler.interceptors;
    const clientInterceptors = standardHandler.clientInterceptors;
    const rootInterceptors = standardHandler.rootInterceptors;

    // Ditto for this private property
    const toFetchResponseOptions = (this as any).toFetchResponseOptions;

    // https://github.com/unnoq/orpc/blob/f437dcbab2c204df0a8af38e39c07c63e388e08e/packages/server/src/adapters/fetch/handler.ts#L48
    const options = resolveFriendlyStandardHandleOptions(resolveMaybeOptionalOptions(rest));

    // https://github.com/unnoq/orpc/blob/f437dcbab2c204df0a8af38e39c07c63e388e08e/packages/server/src/adapters/fetch/handler.ts#L53
    const request = toStandardLazyRequest(baseRequest);

    // Check prefix matching
    // https://github.com/unnoq/orpc/blob/f437dcbab2c204df0a8af38e39c07c63e388e08e/packages/server/src/adapters/standard/handler.ts#L75
    const prefix = (options.prefix?.replace(/\/$/, '') || undefined) as HTTPPath | undefined;
    if (prefix && !request.url.pathname.startsWith(`${prefix}/`) && request.url.pathname !== prefix) {
      return { matched: false, response: undefined };
    }

    return intercept(rootInterceptors, { ...options, request, prefix }, async interceptorOptions => {
      try {
        return await intercept(interceptors, interceptorOptions, async ({ request, context, prefix }) => {
          const method = request.method;
          const url = request.url;

          // https://github.com/unnoq/orpc/blob/f437dcbab2c204df0a8af38e39c07c63e388e08e/packages/server/src/adapters/standard/handler.ts#L96-L98
          const pathname = prefix ? url.pathname.replace(prefix, '') : url.pathname;

          // https://github.com/unnoq/orpc/blob/f437dcbab2c204df0a8af38e39c07c63e388e08e/packages/server/src/adapters/standard/handler.ts#L100-L107
          const match = await standardHandler.matcher.match(method, `/${pathname.replace(/^\/|\/$/g, '')}`);
          if (!match) {
            return { matched: false as const, response: undefined };
          }

          let input;
          try {
            // https://github.com/unnoq/orpc/blob/f437dcbab2c204df0a8af38e39c07c63e388e08e/packages/server/src/adapters/standard/handler.ts#L119
            input = await standardHandler.codec.decode(request, match.params, match.procedure);
          } catch (e) {
            // Handle decode errors like the original implementation
            // https://github.com/unnoq/orpc/blob/f437dcbab2c204df0a8af38e39c07c63e388e08e/packages/server/src/adapters/standard/handler.ts#L164
            const error = !(e instanceof ORPCError)
              ? new ORPCError('BAD_REQUEST', {
                  message: `Malformed request. Ensure the request body is properly formatted and the 'Content-Type' header is set correctly.`,
                  cause: e,
                })
              : toORPCError(e);

            throw error;
          }

          // not handling async iterator input intentionally for proxy use case atm
          // https://github.com/unnoq/orpc/blob/f437dcbab2c204df0a8af38e39c07c63e388e08e/packages/server/src/adapters/standard/handler.ts#L123

          // https://github.com/unnoq/orpc/blob/f437dcbab2c204df0a8af38e39c07c63e388e08e/packages/server/src/adapters/standard/handler.ts#L130-L134
          const client = createProcedureClient(match.procedure, {
            context,
            path: match.path,
            interceptors: clientInterceptors || [],
          });

          // https://github.com/unnoq/orpc/blob/f437dcbab2c204df0a8af38e39c07c63e388e08e/packages/server/src/adapters/standard/handler.ts#L130
          const output = await client(input, {
            signal: request.signal,
            // not supporting for proxy atm
            // lastEventId
          });

          // The big change... if output is a Response, return it directly!
          if (output instanceof Response) {
            return { matched: true, response: output };
          }

          // https://github.com/unnoq/orpc/blob/f437dcbab2c204df0a8af38e39c07c63e388e08e/packages/server/src/adapters/standard/handler.ts#L146
          const response = standardHandler.codec.encode(output, match.procedure);

          // https://github.com/unnoq/orpc/blob/f437dcbab2c204df0a8af38e39c07c63e388e08e/packages/server/src/adapters/fetch/handler.ts#L63
          return {
            matched: true,
            response: toFetchResponse(response, toFetchResponseOptions),
          };
        });
      } catch (e) {
        const error = !(e instanceof ORPCError) ? toORPCError(e) : e;

        // https://github.com/unnoq/orpc/blob/f437dcbab2c204df0a8af38e39c07c63e388e08e/packages/server/src/adapters/standard/handler.ts#L171
        const response = standardHandler.codec.encodeError(error);

        return {
          matched: true,
          response: toFetchResponse(response, toFetchResponseOptions),
        };
      }
    });
  }
}