oRPC Event Iterators
The oRPC socket adapters connect a HyperFetch
Socketto procedures that return an event iterator, over an HTTP event stream or a WebSocket. Every event iterator procedure becomes a typed listener, with the procedure input as the payload.
- Listen to event iterators with the
Socket,ListeneranduseListenerAPI you use for other realtime sources. - Infer types from your router or contract with
OrpcSocketSchemaandcreateSocketSdk. - Share one server subscription between every listener with the same input.
- Resume after reconnecting from the id of the last event, set with
withEventMeta. - Keep rich types such as
Date,BigIntandMapin the input and in every event.
Installation
The socket adapters live in the oRPC package and need @hyper-fetch/sockets.
npm install @hyper-fetch/core @hyper-fetch/sockets @hyper-fetch/orpc @orpc/client
Event stream over HTTP
OrpcStreamAdapter calls the procedure the same way the RPCLink of @orpc/client/fetch does: a
POST {url}/planet/onUpdate with the serialized input, answered with a text/event-stream. It works with the
RPCHandler of @orpc/server/fetch or @orpc/server/node, the same handler that serves your queries.
import { EventPublisher, os, withEventMeta } from "@orpc/server";
import { z } from "zod";
const publisher = new EventPublisher<Record<string, Planet>>();
export const router = {
planet: {
onUpdate: os.input(z.object({ id: z.number() })).handler(async function* ({ input, signal }) {
for await (const planet of publisher.subscribe(`planet/${input.id}`, { signal })) {
yield withEventMeta(planet, { id: String(planet.version) });
}
}),
},
};
import { createSocketSdk, Socket } from "@hyper-fetch/sockets";
import { OrpcStreamAdapter } from "@hyper-fetch/orpc";
import type { OrpcSocketSchema } from "@hyper-fetch/orpc";
import type { router } from "./server";
const socket = new Socket({ url: "http://localhost:3000/rpc", adapter: OrpcStreamAdapter() });
const sdk = createSocketSdk<typeof socket, OrpcSocketSchema<typeof router>>(socket, {
camelCaseToKebabCase: false,
});
const stop = sdk.planet.onUpdate.$listener.setPayload({ id: 1 }).listen(({ data, extra }) => {
console.log(data.name, extra.id);
});
Every subscription is its own request, there is no shared connection. "Connected" means the adapter opens streams:
| Socket call | What happens to the streams |
|---|---|
connect() | Every listener starts its stream. The socket connects on creation, unless autoConnect is false |
disconnect() | Every stream is aborted and the server cancels the generators. Listeners stay registered |
reconnect() | Every running stream is aborted and started again with the id of its last event |
When a stream fails, for example the network drops, the error is reported and the stream starts again after the retry
of the last event, or after the reconnectTime of the socket. After the reconnect attempts of the socket the
subscription ends with an error. A stream whose response does not arrive within the connectionTimeout of the socket (5
seconds by default) is aborted and starts again the same way. Going offline aborts every stream, and coming back online
starts them all again at once with the id of their last event.
const socket = new Socket({
url: "http://localhost:3000/rpc",
adapter: OrpcStreamAdapter(),
adapterOptions: { headers: { authorization: `Bearer ${token}` }, fetchOptions: { credentials: "include" } },
});
WebSocket
OrpcWebsocketAdapter speaks the protocol of the RPCHandler of @orpc/server/ws, the same as the RPCLink of
@orpc/client/websocket. Every subscription is a request on one shared connection.
import { RPCHandler } from "@orpc/server/ws";
import { WebSocketServer } from "ws";
const handler = new RPCHandler(router);
const wss = new WebSocketServer({ port: 3000 });
wss.on("connection", (ws) => handler.upgrade(ws, { context: {} }));
import { OrpcWebsocketAdapter } from "@hyper-fetch/orpc";
const socket = new Socket({ url: "ws://localhost:3000", adapter: OrpcWebsocketAdapter() });
const sdk = createSocketSdk<typeof socket, OrpcSocketSchema<typeof router>>(socket, {
camelCaseToKebabCase: false,
});
The connection follows the regular socket reconnection: a handshake that
takes longer than connectionTimeout is a failed attempt, and a dropped connection comes
back after a jittered backoff between reconnectTime and maxReconnectTime. Every running subscription then starts again
with the id of its last event.
- Use
OrpcStreamAdapterwhen your API already runs on an HTTPRPCHandler, behind proxies and CDNs, or in serverless functions. - Use
OrpcWebsocketAdapterfor many subscriptions per client, since they all share one connection.
Inputs and shared subscriptions
OrpcSocketSchema turns every event iterator procedure into a $listener. The listener response is the yielded value,
the payload is the procedure input and the topic is the procedure path, such as planet/onUpdate. Regular procedures
are left out, call them with OrpcSchema.
sdk.planet.onUpdate.$listener.setPayload({ id: 1 }).listen(({ data }) => {});
// The payload can be passed to listen as well
sdk.planet.onUpdate.$listener.listen(({ data }) => {}, { payload: { id: 2 } });
// Procedures without an input need no payload
sdk.ticks.$listener.listen(({ data }) => {});
Listeners with the same topic and payload share one server subscription, and the last one to unsubscribe cancels it. One
callback function can listen with several payloads, every listen() call is stopped by its own unsubscribe. Payloads
are compared in the oRPC wire format, so { at: new Date(0) } and { at: new Date(1) } are different subscriptions.
Every listener receives only the events of its own payload.
For contract-first APIs, pass the client type of the contract.
import type { ContractRouterClient } from "@orpc/contract";
const sdk = createSocketSdk<typeof socket, OrpcSocketSchema<ContractRouterClient<typeof contract>>>(socket, {
camelCaseToKebabCase: false,
});
Event meta and resuming
The extra of every message holds the meta the server set with withEventMeta.
sdk.planet.onUpdate.$listener.setPayload({ id: 1 }).listen(({ data, extra }) => {
extra.id; // "42" - the id of the event
extra.retry; // the retry delay in milliseconds, when the server set one
});
When a subscription starts again, after a reconnect or a failed stream, the adapter sends the id of its last event as
the last-event-id header. oRPC passes it to the procedure as lastEventId, so the server can send the events the
client missed.
onUpdate: os.input(z.object({ id: z.number() })).handler(async function* ({ input, lastEventId }) {
for (const planet of await history.after(input.id, lastEventId)) {
yield withEventMeta(planet, { id: planet.eventId });
}
// ...then the live events
}),
React
useListener subscribes on mount and unsubscribes on unmount. A new payload starts a new subscription and cancels the
previous one. In StrictMode the extra mount is cancelled right away, so the server keeps one subscription.
status follows the subscription lifecycle: "starting" until the server confirms it,
"listening" while it runs, then "ended", or "failed" with the OrpcSocketError in error.
import { useListener } from "@hyper-fetch/react";
function Planet({ id }: { id: number }) {
const { data, extra, status, error } = useListener(sdk.planet.onUpdate.$listener.setPayload({ id }));
if (status === "failed") {
return <p>{error?.message}</p>;
}
return (
<div>
<h3>{data?.name}</h3>
<p>
Event {extra?.id} ({status})
</p>
</div>
);
}
Errors
Errors of a subscription never throw into your code. They are reported to socket.onError and the socket error events
as an OrpcSocketError, which tells you which subscription failed:
| Property | Description |
|---|---|
topic | Topic of the failed subscription, such as planet/onUpdate |
payload | Input of the failed subscription |
shape | The server error in the shape of ORPCError.toJSON(), null when there was none |
defined, code, status, data | Read from shape. defined is true for errors from the .errors() map |
cause | The original error - the ORPCError, an ErrorEvent, or the network error |
import { OrpcSocketError } from "@hyper-fetch/orpc";
socket.onError(({ error }) => {
if (error instanceof OrpcSocketError && error.defined && error.code === "OVERHEATED") {
console.log(error.topic, error.payload, error.data);
}
});
What ends up in it:
- An
errorevent of the iterator, and a call the server rejected before the iterator started (a failed input validation or middleware), have theORPCErroras thecauseand its JSON as theshape. - An error event that is not an oRPC error has the
ErrorEventof@orpc/clientas thecause, with itsdata. - A procedure that returns a regular output, malformed data, and a failed or timed out stream have
shape: null. - A WebSocket frame that can't be read at all has
topic: null, since it can't be matched to a subscription.
A listener callback that throws is reported with its own error, and the other listeners still receive the event. A
WebSocket connection that closes is reported as a regular Error, the same as in the other socket adapters.
Subscription lifecycle
Both adapters report when the server confirms a subscription and when it ends it. Pass onStart and onEnd to
listen():
sdk.countdown.$listener.setPayload({ from: 3 }).listen(({ data }) => console.log(data), {
// The server answered with the event iterator - also after every restart
onStart: ({ topic }) => console.log(`${topic} is live`),
// The iterator finished (`error` is `null`) or failed
onEnd: ({ topic, error }) => console.log(topic, error ? "failed" : "finished"),
});
| Event | When |
|---|---|
onStart | The response of the stream, or of the WebSocket request, carries the event iterator. A listener that joins a running subscription gets it right away. It comes again when the subscription is confirmed after a reconnect or a failed stream |
onEnd | error: null after the done event, or when the server closes the stream. The OrpcSocketError after an error event, a rejected call, a procedure that is not an event iterator, an input the WebSocket adapter can't encode, or a stream that stopped restarting |
A failure the adapter recovers from, such as a dropped connection that reconnects, does not end the subscription. The
error is still reported to socket.onError.
When a subscription ends, the listeners receive the events that came before the end (also the batch of a delivery
strategy), then they unsubscribe and onEnd runs. The value returned by the generator is not delivered. The adapter
doesn't cancel anything on the server, since the server already finished. A reconnect never starts an ended subscription
again - call listen() for a new one. It starts without the id of the last event of the old one.
Options
Both adapters take customJsonSerializers, the same list as the RPCHandler.
const socket = new Socket({ url, adapter: OrpcStreamAdapter({ customJsonSerializers: [moneySerializer] }) });
| Option | Adapter | Description |
|---|---|---|
autoConnect | both | Connect when the socket is created, true by default |
headers | both | Headers of every subscription request |
fetch | OrpcStreamAdapter | The fetch to use, the global one by default |
fetchOptions | OrpcStreamAdapter | Options passed to fetch, such as credentials |
WebSocket | OrpcWebsocketAdapter | The WebSocket constructor, the global one by default |
protocols | OrpcWebsocketAdapter | Subprotocols of the WebSocket |
Set them with the adapterOptions of the socket, or per connection attempt in socket.onConnect, for example to send a
fresh token. Query params of the socket are appended to the URL. In a runtime without a global fetch or WebSocket,
pass one - otherwise the connection fails with "not available in this environment".
import WebSocket from "ws";
const socket = new Socket({
url: "ws://localhost:3000",
adapter: OrpcWebsocketAdapter(),
adapterOptions: { WebSocket: WebSocket as unknown as typeof globalThis.WebSocket },
});
The socket options connectionTimeout (the limit of one connection attempt or stream response) and reconnectTime (the
minimum delay before the next attempt) apply to both adapters. socket.destroy() closes the connection and removes everything
the adapter subscribed to, such as the online listener of the app manager.
Limitations
- The adapters only subscribe. Emitting throws, use
OrpcAdapterfor regular procedures. - Inputs with files are not supported over WebSocket.
- Event iterators in the input (client streaming) and request batching are not supported.
OrpcStreamAdapterreads event iterators from HTTP event streams,OrpcWebsocketAdapterfrom one WebSocket.OrpcSocketSchematypes every event iterator procedure as a listener, with the input as the payload.- Listeners with the same payload share one server subscription.
- The event id from
withEventMetais inextraand resumes the subscription after a reconnect. onStartandonEnd, and thestatusofuseListener, follow the server side of the subscription.- Errors arrive in
socket.onErroras anOrpcSocketErrorwith the topic, the payload and the server error.

