Resolver API

When integrating WebSockets with larger projects, it is often needed to dynamically route an incoming event to websocket hooks. crossws provides a very simple mechanism to do this using resolver API.

// https://crossws.h3.dev/adapters
import crossws from "crossws/adapters/<adapter>";

import { defineHooks } from "crossws";

const websocket = crossws({
  async resolve(req) {
    // TODO: Resolve hooks based on req.url, req.headers
    // You can return undefined in case there is no match
    return {
      /* resolved hooks */
    };
  },
});

If you need to change resolve function (for cases like handling HMR):

let resolveWebSocketHooks = (req) => /* ... */

const websocket = crossws({
  async resolve(req) {
    return resolveWebSocketHooks(req)
  },
});

// Update reference to `resolveWebSocketHooks` later.

#Server plugin

When using the crossws/server plugin (srvx integration), resolve is optional. If you omit it, hooks are resolved by calling the server's own fetch handler and reading them back from either the request or the crossws property of the returned Response (the srvx convention for attaching WebSocket hooks):

import { plugin as ws } from "crossws/server";

// No `resolve` needed — hooks come from the app's own fetch handler.
serve(app, { plugins: [ws()] });

Provide resolve only to customize routing, e.g. to resolve hooks without invoking the app:

serve(app, {
  plugins: [ws({ resolve: (req) => resolveWebSocketHooks(req) })],
});

resolve is invoked once per connection — its result is cached against the connection for the lifetime of the peer — so the app's fetch runs on connect, not on every message.

#Making your fetch handler upgrade-aware

With the default resolver, your app's fetch handler is called with the raw WebSocket upgrade request on connect. Keep two things in mind:

• Attach hooks to the request, or via .crossws. Hooks are read from two channels: the Symbol.for("crossws.hooks") property on the request (see Attaching hooks to the request), and the crossws property of the value returned for the upgrade request. An error or redirect response with hooks on neither channel (any status that is not 2xx or 101, e.g. new Response("Unauthorized", { status: 401 }) or a 302) is sent back to the client and the handshake is rejected — handy for auth. The lone exception is a 426 carrying request hooks. A 2xx (or 101) response with hooks on neither channel still completes the handshake but with no hooks attached, so every message is silently dropped. Make sure the upgrade path provides hooks, either on a Response:

  import { defineHooks } from "crossws";
  
  const hooks = defineHooks({
    message(peer, message) {
      peer.send(message.text());
    },
  });
  
  function fetch(req) {
    if (req.headers.get("upgrade") === "websocket") {
      const res = new Response(null);
      res.crossws = hooks; // opt this connection into WebSocket handling
      return res;
    }
    return new Response("Hello!"); // normal HTTP response
  }

  …or, as a shortcut for the upgrade path, a plain object { crossws, headers } (no Response needed). Any headers are sent on the WebSocket handshake response:

  function fetch(req) {
    if (req.headers.get("upgrade") === "websocket") {
      return {
        crossws: hooks,
        headers: { "x-powered-by": "crossws" }, // optional handshake headers
      };
    }
    return new Response("Hello!"); // normal HTTP response — must be a Response
  }

  Note

  The plain-object form is only for upgrade requests. Non-upgrade paths must still return a real Response. An HTTP Response's own headers are not applied to the handshake — use the { crossws, headers } shortcut (or an upgrade hook returning { headers }) to set handshake headers.

• fetch runs per connection, so keep it side-effect-safe. Any auth, logging, metrics, or database work in fetch now executes once for every WebSocket upgrade. If a code path must run only for regular HTTP requests, branch on the upgrade header first.

• Throwing/rejecting fails the handshake. If fetch throws (or rejects) on the upgrade request, the WebSocket handshake is rejected rather than left hanging. Throw a Response to control the rejection; otherwise the client sees a 500. To reject an upgrade gracefully, prefer returning a non-2xx Response (which is rendered to the client) over throwing.

#Attaching hooks to the request

Hooks attached to a Response are lost whenever some layer rebuilds it — merging a staged header (a route rule, CORS middleware), wrapping a streamed body, or any plain new Response(res.body, res) in a middleware. A rebuilt response carries none of the original's own properties, so .crossws silently disappears and the handshake is rejected with an opaque 426.

Nothing in that chain replaces the request, so it is the durable channel. Attach hooks to it with setWebSocketHooks():

import { setWebSocketHooks } from "crossws";

function fetch(req) {
  if (req.headers.get("upgrade") === "websocket") {
    setWebSocketHooks(req, hooks);
    return new Response("WebSocket upgrade is required.", { status: 426 });
  }
  return new Response("Hello!");
}

The symbol is the wire format, not the helper — Symbol.for("crossws.hooks") is public API. A framework that depends on crossws for types only can write it with no import at all, and because it lives in the global symbol registry it also crosses duplicate module instances and realms:

req[Symbol.for("crossws.hooks")] = hooks;

Both channels are supported, and they compose predictably:

• Hooks on the result (.crossws) always win.
• Hooks on the request are a recovery channel: they never reinterpret a response. An error/redirect result still rejects the handshake, so auth middleware that rejects after the WebSocket handler ran keeps working. The one exception is 426 Upgrade Required — the status a framework returns because it routed to a WebSocket handler — which is treated as an upgrade when the request carries hooks. A 426 with hooks on neither channel is still rejected, and logs a one-time warning naming the likely cause (its only other symptom is an opaque Unexpected server response: 426 on the client).
• The { crossws, headers } shortcut still applies its handshake headers when the hooks came from the request.