WebSockets

A WebSocket route is a route: the upgrade request is routed, goes through onRequest, the security, the params, query and header checks, middleware and preHandler like a GET, and only once all of them let it through does it become a socket. A no answers with its status (400, 401, 404, …) and no socket. RFC 6455 is written on node:http's upgrade event, with no dependency.

const Say = t.discriminated("type", {
  say: t.object({ type: t.literal("say"), text: t.string().max(200) }),
  leave: t.object({ type: t.literal("leave") }),
});
const Said = t.object({ type: t.enum(["said", "joined"]), text: t.string(), from: t.string() });

app.ws(
  "/rooms/:room",
  { summary: "A chat room", params: t.object({ room: t.string() }), query: t.object({ name: t.string() }), message: Say, send: Said },
  (socket, ctx) => {
    void socket.send({ type: "joined", text: ctx.params.room, from: ctx.query.name });
    socket.on("message", (m) => {
      if (m.type === "leave") return socket.close(4000, "bye");
      void socket.send({ type: "said", text: m.text, from: ctx.query.name });
    });
  },
);

message and sendCopy Anchor Link

message is what the client sends. With it, every message is JSON checked against it, typed in socket.on("message") and in for await (const m of socket). One that is not JSON, or breaks the contract, closes the socket with 1007 and the reason (the path and the rule, never the value sent); a binary frame where the contract wants JSON closes it with 1003.

send is what the server sends. socket.send(v) writes it as JSON with only what the contract lists, as a route's answer is trimmed. In development a value that breaks it throws (reported, and the socket closes with 1011).

Without message, text arrives as a string and binary as a Buffer, a copy of its own. sendRaw(data) sends text or bytes as they are, past the contract.

The socketCopy Anchor Link

app.ws("/feed", { send: Tick }, async (socket, ctx) => {
  for (let n = 0; !ctx.signal.aborted; n++) {
    await socket.send({ n }); // resolves once the socket takes more
    await sleep(1000);
  }
});

ctx is the upgrade request's context, with its params, query, headers, decorations and state. ctx.signal aborts when the socket closes. Messages that come before the handler listens wait for it. A listener that throws is reported and closes the socket with 1011.

The typed clientCopy Anchor Link

const room = shop.ws("/rooms/:room", { params: { room: "tea" }, query: { name: "ana" } });
room.on("message", (m) => m.type === "said" && show(m.text)); // narrowed by the route's send
await room.ready;                                           // rejects when it closes first (a 401, a 404)
room.send({ type: "say", text: "hello" });                  // typed by the route's message

for await (const m of room) if (m.type === "joined") greet(m.from); // leaving the loop closes it

client.ws(path, { params, query }) opens a WebSocket route with the platform's WebSocket: http becomes ws, https wss. In Node, headers go with the upgrade; a browser sends none. raw is the socket underneath, and { WebSocket } in the client's options puts in another class. OpenAPI lists a WebSocket route as a GET with a 101 and an x-inkan-websocket extension holding both schemas; the docs page shows it as WS.

Who may open it: originsCopy Anchor Link

A browser sends the user's cookies with a WebSocket upgrade from any page, and the same-origin policy does not stop that page from reading the answers. Without a check, a site the user happens to visit can open your socket as the user and talk on it: cross-site WebSocket hijacking. So inkan checks the Origin header browsers send before any hook runs. By default only the app's own origin (the Host header and ctx.protocol) may open the socket, and a request without an Origin, which is not a browser, goes through. Anything else is a 403 origin-not-allowed.

app.ws("/live", { origins: ["https://shop.example"] }, live);            // the own origin, and these
app.ws("/live", { origins: (origin, ctx) => origin?.endsWith(".shop.example") ?? true }, live); // decides alone
app.ws("/public", { origins: "*" }, feed);                               // every page

inkan({ ws: { origins: ["https://admin.shop.example"] } });             // for every route without its own

A function gets the request's Origin and a PreContext: the request before hooks and input checks (method, path, headers, protocol, ip), so it cannot read decorations. The same Origins type serves cors({ origins }). Origins are compared as URL origins: http://X:80 is http://x.

OptionsCopy Anchor Link

The app's ws option sets the defaults for every route that does not set its own:

inkan({ ws: { origins: ["https://admin.shop.example"], maxMessage: 64 * 1024, heartbeat: 15_000, handshakeTimeout: 5_000 } });

Before any hook, too: an upgrade that is not a GET over HTTP/1.1 without a body is a 400, and sec-websocket-key has to be canonical base64. A plain request to a WebSocket path is a 426.

Close codesCopy Anchor Link

Your own codes go from 4000 to 4999, as socket.close(4000, "bye") above.

LimitsCopy Anchor Link

• No permessage-deflate. No extension is negotiated, so every frame goes as it is. No subprotocol is chosen either; a hook may set sec-websocket-protocol.
• Not on app.fetch. Bun, Deno and serverless platforms upgrade their own way. listen listens for upgrades when the app has a WebSocket route; a server of your own takes server.on("upgrade", app.upgradeListener), and @inkanjs/uws runs them on uWebSockets.js.
• A message comes in at most 1024 frames, each after the first counted 64 bytes against maxMessage; text is checked as UTF-8 frame by frame. A peer that floods pings without reading gets only its latest one answered.
• Per process. With workers, each process holds its own sockets. Broadcast with a Set of sockets per process, or through a bus the processes share: the publish/subscribe of a shared Store, Redis pub/sub, say:

import type { Infer, WsSocket } from "@vxnsin/inkan";

const room = new Set<WsSocket<Infer<typeof Say>, Infer<typeof Said>>>();

app.ws("/room", { message: Say, send: Said }, (socket) => {
  room.add(socket);
  socket.on("close", () => room.delete(socket));
  socket.on("message", (m) => {
    if (m.type === "say") room.forEach((s) => void s.send({ type: "said", text: m.text, from: "someone" }));
  });
});