= >(path: P, ...input: Args>) => LiveEvents>>>;
+type Ws = >(
+ path: P,
+ ...input: Args>
+) => LiveSocket, "message">, Part, "send">>;
+
+/**
+ * How a live source stands. `idle` only for a hook that is not `enabled`; `connecting` until
+ * the first event (or message) arrives, and again while waiting to retry; `closed` once it
+ * ended; `error` once it failed for good.
+ */
+export type LiveStatus = "idle" | "connecting" | "open" | "closed" | "error";
+
+/** The data of each event, by its name. */
+export type EventData = { [K in E["event"]]: Extract["data"] };
+
+export type EventsState = {
+ /** The last event, narrowed by `last.event`. */
+ last: E | undefined;
+ /** The latest data of every event that came, by name: `byName.progress`. */
+ byName: Partial>;
+ status: LiveStatus;
+ /**
+ * Why it failed (or, while retrying, failed last). A stream that did not open is a
+ * ProblemError with the problem the server sent: `isProblem(error, "not-found")`.
+ */
+ error: ProblemError | Error | undefined;
+};
+
+export type FollowOptions = {
+ /** Called with every event as it comes, after the state took it: a place for `setQueryData`. */
+ onEvent?: (event: E) => void;
+ /**
+ * Whether to open the stream again after it failed to open or broke off. Default never
+ * (a job's stream ends by itself; an ended stream is never opened again). `true` always,
+ * a number that many times in a row, or a function like TanStack's `retry`, so the
+ * package's `retry(3)` fits: no retry for a 404, one for a 503 or a dropped connection.
+ */
+ retry?: boolean | number | ((failures: number, error: ProblemError | Error) => boolean);
+ /** Milliseconds before opening it again. Default 1 s, doubling, at most 30 s. */
+ retryDelay?: number | ((failures: number, error: ProblemError | Error) => number);
+};
+
+/**
+ * Follows an event stream until it ends, fails or `signal` aborts, telling `onChange` how it
+ * stands. Returns the function that stops it. The framework-free part of `useEvents`.
+ */
+export function follow(
+ source: LiveEvents,
+ options?: FollowOptions & { signal?: AbortSignal; onChange?: (state: EventsState) => void },
+): () => void;
+
+export type SocketState = {
+ /** The last message the server sent, after a trip through JSON. */
+ last: Jsonify | undefined;
+ status: LiveStatus;
+ error: Error | undefined;
+ /** The typed socket underneath: `on`, `ready`, `raw`. */
+ socket: TypedSocket | undefined;
+};
+
+export type Connection = {
+ socket: TypedSocket;
+ /** Sends a message as JSON; one sent while the socket is still opening goes once it is open. */
+ send(value: In): void;
+ /** Closes the socket; `onChange` hears nothing after. */
+ close(): void;
+};
+
+/**
+ * Opens a WebSocket and tells `onChange` how it stands and `onMessage` every message. The
+ * framework-free part of `useSocket`.
+ */
+export function connect(
+ source: LiveSocket,
+ options?: { onMessage?: (message: Jsonify) => void; onChange?: (state: SocketState) => void },
+): Connection;
diff --git a/packages/query/index.js b/packages/query/index.js
index 2b59b97..efb894b 100644
--- a/packages/query/index.js
+++ b/packages/query/index.js
@@ -7,6 +7,9 @@
// useQuery(q.get("/teas/:id", { params: { id } }));
// useMutation(q.post("/teas"));
// queryClient.invalidateQueries({ queryKey: q.key("/teas/:id") });
+//
+// Live data, server-sent events and WebSockets, is no query: follow() and connect() keep its
+// state without any framework, and @inkanjs/query/react makes hooks of them.
/** A failed answer: the RFC 9457 problem document the server sent, and its status. */
export class ProblemError extends Error {
@@ -49,10 +52,112 @@ export function mutation(call) {
return { mutationFn: async (variables) => unwrap(await call(variables)) };
}
+/** What a stream that did not open threw (the client's StreamError) as a ProblemError. */
+function asError(err) {
+ if (err instanceof ProblemError) return err;
+ if (err instanceof Error && typeof err.status === "number" && err.problem) return new ProblemError(err);
+ return err instanceof Error ? err : new Error(String(err));
+}
+
+const backoff = (failures) => Math.min(1000 * 2 ** (failures - 1), 30_000);
+
+/**
+ * Follows an event stream (`q.events(path, input)`) until it ends, fails or `signal` aborts,
+ * and tells `onChange` how it stands, first as it starts and then after every event. A
+ * stream that fails to open or breaks off is opened again only as `retry` says: by default
+ * never, since a job's stream ends, and an ended stream stays closed either way. Returns
+ * the function that stops it.
+ */
+export function follow(source, options = {}) {
+ const stop = new AbortController();
+ const outer = options.signal;
+ if (outer?.aborted) stop.abort();
+ else outer?.addEventListener("abort", () => stop.abort(), { once: true });
+ let state = { last: undefined, byName: {}, status: "connecting", error: undefined };
+ const set = (next) => {
+ if (stop.signal.aborted) return;
+ state = { ...state, ...next };
+ options.onChange?.(state);
+ };
+ options.onChange?.(state);
+ (async () => {
+ for (let failures = 0; !stop.signal.aborted; ) {
+ try {
+ for await (const e of source.open(stop.signal)) {
+ if (stop.signal.aborted) return;
+ failures = 0;
+ const event = e.id === undefined ? { event: e.event, data: e.data } : { event: e.event, data: e.data, id: e.id };
+ set({ status: "open", error: undefined, last: event, byName: { ...state.byName, [e.event]: e.data } });
+ if (!stop.signal.aborted) options.onEvent?.(event);
+ }
+ return set({ status: "closed" });
+ } catch (err) {
+ if (stop.signal.aborted) return;
+ const error = asError(err);
+ const again = options.retry;
+ const go = typeof again === "function" ? again(failures, error) : typeof again === "number" ? failures < again : again === true;
+ if (!go) return set({ status: "error", error });
+ failures++;
+ set({ status: "connecting", error });
+ const wait = options.retryDelay ?? backoff;
+ await new Promise((resolve) => {
+ const timer = setTimeout(resolve, typeof wait === "function" ? wait(failures, error) : wait);
+ stop.signal.addEventListener("abort", () => (clearTimeout(timer), resolve()), { once: true });
+ });
+ }
+ }
+ })();
+ return () => stop.abort();
+}
+
+/**
+ * Opens a WebSocket (`q.ws(path, input)`) and tells `onChange` how it stands: its status and
+ * the last message. `send` waits for the socket to open; `close` closes it, and after that
+ * nothing is told any more.
+ */
+export function connect(source, options = {}) {
+ const socket = source.open();
+ let closed = false;
+ let state = { last: undefined, status: "connecting", error: undefined, socket };
+ const set = (next) => {
+ if (closed) return;
+ state = { ...state, ...next };
+ options.onChange?.(state);
+ };
+ options.onChange?.(state);
+ socket.ready.then(() => state.status === "connecting" && set({ status: "open" }), () => {});
+ socket.on("message", (message) => {
+ if (closed) return;
+ set({ last: message });
+ options.onMessage?.(message);
+ });
+ socket.on("close", (code) => {
+ if (state.status === "connecting") set({ status: "error", error: new Error(`The WebSocket closed before it opened (${code})`) });
+ else set({ status: "closed" });
+ });
+ // some WebSocket clients (Node 22's) tell a refused handshake only by an error, never a close
+ socket.raw.addEventListener?.("error", () => {
+ if (state.status === "connecting") set({ status: "error", error: new Error("The WebSocket could not open") });
+ });
+ return {
+ socket,
+ send(value) {
+ if (socket.raw.readyState === 1) socket.send(value);
+ else if (socket.raw.readyState === 0) socket.ready.then(() => socket.send(value), () => {});
+ },
+ close() {
+ closed = true;
+ if (socket.raw.readyState < 2) socket.close();
+ },
+ };
+}
+
/**
* Query and mutation options straight from the typed client, keyed by path and input:
* `q.get(path, input)` is a query, `q.post(path)` and the others a mutation that takes the
* input as its variables, and `q.key(path)` the key of every query of that path.
+ * `q.events(path, input)` and `q.ws(path, input)` are live sources for follow() and
+ * connect(), or useEvents and useSocket: a key, and how to open them.
*/
export function queries(client) {
const key = (path, input) => (input === undefined ? [path] : [path, input]);
@@ -64,5 +169,7 @@ export function queries(client) {
put: write("put"),
patch: write("patch"),
delete: write("delete"),
+ events: (path, input) => ({ key: key(path, input), open: (signal) => client.events(path, { ...input, signal }) }),
+ ws: (path, input) => ({ key: key(path, input), open: () => client.ws(path, input) }),
};
}
diff --git a/packages/query/package.json b/packages/query/package.json
index 2dd564f..a0bf364 100644
--- a/packages/query/package.json
+++ b/packages/query/package.json
@@ -1,7 +1,7 @@
{
"name": "@inkanjs/query",
- "version": "0.2.0",
- "description": "The typed inkan client for TanStack Query: data typed from the contract, problems as errors. React, Vue, Svelte, Solid.",
+ "version": "0.3.0",
+ "description": "The typed inkan client for TanStack Query: data typed from the contract, problems as errors, live events and WebSockets. React, Vue, Svelte, Solid.",
"type": "module",
"license": "MIT",
"author": "Vensin (https://github.com/vxnsin)",
@@ -17,17 +17,25 @@
"vue-query",
"svelte-query",
"solid-query",
- "typed-client"
+ "typed-client",
+ "server-sent-events",
+ "websocket"
],
"exports": {
".": {
"types": "./index.d.ts",
"default": "./index.js"
+ },
+ "./react": {
+ "types": "./react.d.ts",
+ "default": "./react.js"
}
},
"files": [
"index.js",
"index.d.ts",
+ "react.js",
+ "react.d.ts",
"README.md",
"CHANGELOG.md"
],
@@ -35,11 +43,18 @@
"node": ">=22.18"
},
"peerDependencies": {
- "@vxnsin/inkan": ">=0.4.0"
+ "@vxnsin/inkan": ">=0.7.0",
+ "react": ">=18"
+ },
+ "peerDependenciesMeta": {
+ "react": {
+ "optional": true
+ }
},
"devDependencies": {
"@tanstack/query-core": "^5.104.1",
- "@vxnsin/inkan": "^0.4.0"
+ "@vxnsin/inkan": "^0.8.0",
+ "react": "^19.3.0"
},
"scripts": {
"test": "node --test test.ts"
diff --git a/packages/query/react.d.ts b/packages/query/react.d.ts
new file mode 100644
index 0000000..2bd8555
--- /dev/null
+++ b/packages/query/react.d.ts
@@ -0,0 +1,34 @@
+import type { Jsonify } from "@vxnsin/inkan/client";
+import type { AnyEvent, EventsState, FollowOptions, LiveEvents, LiveSocket, SocketState } from "./index.js";
+
+export type UseEventsOptions = FollowOptions & {
+ /** Whether to follow the stream at all; while false the status is `idle`. Default true. */
+ enabled?: boolean;
+};
+
+/**
+ * Follows an event stream (`q.events(path, input)`) while the component is mounted: opened
+ * again when the key (path and input) changes, closed on unmount. Every event is typed by
+ * its name: `last.event === "progress"` narrows `last.data`, `byName.progress` is the latest.
+ */
+export function useEvents(source: LiveEvents, options?: UseEventsOptions): EventsState;
+
+export type UseSocketOptions = {
+ /** Called with every message the server sends. */
+ onMessage?: (message: Jsonify) => void;
+ /** Whether to open the socket at all; while false the status is `idle`. Default true. */
+ enabled?: boolean;
+};
+
+/**
+ * Opens a WebSocket (`q.ws(path, input)`) while the component is mounted: opened again when
+ * the key changes, closed on unmount. `send` takes what the route's `message` asks for, and
+ * `last` is the last of what its `send` promises.
+ */
+export function useSocket(
+ source: LiveSocket,
+ options?: UseSocketOptions,
+): SocketState & {
+ /** Sends a message as JSON; one sent while the socket is still opening goes once it is open. */
+ send(value: In): void;
+};
diff --git a/packages/query/react.js b/packages/query/react.js
new file mode 100644
index 0000000..6c19bea
--- /dev/null
+++ b/packages/query/react.js
@@ -0,0 +1,57 @@
+// Live data for React: follow() and connect() as hooks. The source is opened again when its
+// key (path and input) changes, and closed when the component unmounts.
+//
+// const job = useEvents(q.events("/exports/:id/events", { params: { id } }));
+// job.byName.progress; // typed from the route's events
+//
+// const room = useSocket(q.ws("/rooms/:room", { params: { room } }));
+// room.send({ type: "say", text: "hello" });
+import { useCallback, useEffect, useRef, useState } from "react";
+import { connect, follow } from "./index.js";
+
+const idleEvents = { last: undefined, byName: {}, status: "idle", error: undefined };
+const idleSocket = { last: undefined, status: "idle", error: undefined, socket: undefined };
+
+/** The latest options, for callbacks that should not open the source again when they change. */
+function useLatest(value) {
+ const ref = useRef(value);
+ useEffect(() => {
+ ref.current = value;
+ });
+ return ref;
+}
+
+/** Follows an event stream while mounted and `enabled`: the last event, the latest of each, the status. */
+export function useEvents(source, options = {}) {
+ const enabled = options.enabled ?? true;
+ const latest = useLatest(options);
+ const [state, setState] = useState(enabled ? { ...idleEvents, status: "connecting" } : idleEvents);
+ const id = JSON.stringify(source.key);
+ useEffect(() => {
+ if (!enabled) return setState(idleEvents);
+ const { retry, retryDelay } = latest.current;
+ return follow(source, { retry, retryDelay, onEvent: (event) => latest.current.onEvent?.(event), onChange: setState });
+ // the key is what tells one source from another; a new object for the same one opens nothing
+ }, [id, enabled]); // eslint-disable-line react-hooks/exhaustive-deps
+ return state;
+}
+
+/** Opens a WebSocket while mounted and `enabled`: `send`, the last message, the status, the socket. */
+export function useSocket(source, options = {}) {
+ const enabled = options.enabled ?? true;
+ const latest = useLatest(options);
+ const [state, setState] = useState(enabled ? { ...idleSocket, status: "connecting" } : idleSocket);
+ const connection = useRef(undefined);
+ const id = JSON.stringify(source.key);
+ useEffect(() => {
+ if (!enabled) return setState(idleSocket);
+ const open = connect(source, { onMessage: (message) => latest.current.onMessage?.(message), onChange: setState });
+ connection.current = open;
+ return () => {
+ open.close();
+ if (connection.current === open) connection.current = undefined;
+ };
+ }, [id, enabled]); // eslint-disable-line react-hooks/exhaustive-deps
+ const send = useCallback((value) => connection.current?.send(value), []);
+ return { ...state, send };
+}
diff --git a/packages/query/test.ts b/packages/query/test.ts
index 5dc7a48..27f778e 100644
--- a/packages/query/test.ts
+++ b/packages/query/test.ts
@@ -1,9 +1,13 @@
import { test } from "node:test";
import assert from "node:assert/strict";
import { QueryClient, MutationObserver } from "@tanstack/query-core";
-import { inkan, problem, t } from "@vxnsin/inkan";
+import { inkan, problem, sse, t } from "@vxnsin/inkan";
import { client } from "@vxnsin/inkan/client";
-import { isProblem, mutation, ProblemError, queries, query, retry } from "./index.js";
+import { connect, follow, isProblem, mutation, ProblemError, queries, query, retry } from "./index.js";
+import type { Connection, EventsState, LiveEvents, SocketState } from "./index.js";
+import { useEvents, useSocket } from "./react.js";
+
+type EventOf = S extends LiveEvents ? E : never;
const Tea = t.object({ id: t.int(), name: t.string(), brewed: t.date() });
const teas = [{ id: 1, name: "Sencha", brewed: new Date("2026-01-02T03:04:05.000Z") }];
@@ -86,3 +90,199 @@ test("isProblem and retry tell problems that pass from those that stay", async (
assert.equal(again(0, new ProblemError({ status: 429, problem: {} })), true);
assert.equal(again(2, down), false, "and only so often");
});
+
+// ---- live data
+
+const Progress = t.object({ done: t.int(), total: t.int() });
+let release: () => void = () => {};
+const live = inkan({ log: false })
+ .job("/exports", { body: t.object({ rows: t.int() }), progress: Progress, result: t.object({ url: t.string() }) }, async (job) => {
+ await new Promise((resolve) => (release = resolve)); // waits until someone follows it
+ for (let done = 1; done <= job.input.rows; done++) job.progress({ done, total: job.input.rows });
+ return { url: `/files/${job.id}.csv` };
+ })
+ .get("/ticks", { response: { 200: t.events({ tick: t.object({ n: t.int() }) }) } }, () =>
+ sse(async function* (signal) {
+ for (let n = 0; !signal.aborted; n++) {
+ yield { event: "tick", data: { n } };
+ await new Promise((r) => setTimeout(r, 5));
+ }
+ }),
+ )
+ .ws(
+ "/rooms/:room",
+ {
+ params: t.object({ room: t.string().min(3) }),
+ message: t.object({ type: t.literal("say"), text: t.string() }),
+ send: t.object({ type: t.literal("said"), room: t.string(), text: t.string() }),
+ },
+ (socket, ctx) => socket.on("message", (m) => void socket.send({ type: "said", room: ctx.params.room, text: m.text })),
+ );
+const api = client("http://live.test", { fetch: (url, init) => live.fetch(new Request(url, init)) });
+
+/** Resolves with the first state `check` accepts. */
+function until(start: (onChange: (s: S) => void) => unknown, check: (s: S) => boolean, ms = 5_000): Promise {
+ return new Promise((resolve, reject) => {
+ const seen: S[] = [];
+ // fail with what was seen instead of hanging the run
+ const timer = setTimeout(() => reject(new Error(`no state passed the check in ${ms} ms; seen: ${JSON.stringify(seen.map((x) => ({ ...(x as object), socket: undefined, error: (x as { error?: Error }).error?.message })))}`)), ms);
+ start((s) => {
+ seen.push(s);
+ if (check(s)) {
+ clearTimeout(timer);
+ resolve(s);
+ }
+ });
+ });
+}
+
+test("follow() follows a job: typed events, the latest of each, then closed", async () => {
+ const qc = new QueryClient();
+ const q = queries(api);
+ const started = await new MutationObserver(qc, q.post("/exports")).mutate({ body: { rows: 3 } });
+ const source = q.events("/exports/:id/events", { params: { id: started.id } });
+ assert.deepEqual(source.key, ["/exports/:id/events", { params: { id: started.id } }]);
+
+ const progress: number[] = [];
+ const statuses: string[] = [];
+ const end = await until>>(
+ (onChange) =>
+ follow(source, {
+ onChange: (s) => (statuses.push(s.status), onChange(s)),
+ onEvent: (e) => {
+ if (e.event === "status") release(); // following now: let the job run
+ if (e.event === "progress") progress.push(e.data.done); // narrowed by the name
+ // @ts-expect-error a job's stream has no such event
+ void (e.event === "tick");
+ },
+ }),
+ (s) => s.status === "closed",
+ );
+ assert.equal(statuses[0], "connecting");
+ assert.ok(statuses.includes("open"));
+ assert.equal(end.byName.end?.state, "done");
+ assert.deepEqual(end.byName.progress, { done: 3, total: 3 });
+ assert.equal(end.last?.event, "end");
+ assert.equal(progress.at(-1), 3);
+ const total: number | undefined = end.byName.progress?.total;
+ assert.equal(total, 3);
+ // @ts-expect-error progress has no percent
+ void end.byName.progress?.percent;
+
+ const result = await qc.fetchQuery(q.get("/exports/:id/result", { params: { id: started.id } }));
+ assert.equal(result.url, `/files/${started.id}.csv`);
+});
+
+test("follow() tells a stream that does not open as a ProblemError, and retries only as asked", async () => {
+ const q = queries(api);
+ const missing = q.events("/exports/:id/events", { params: { id: "nope" } });
+ let opened = 0;
+ const counted = { key: missing.key, open: (signal?: AbortSignal) => (opened++, missing.open(signal)) };
+ const failed = await until>>(
+ (onChange) => follow(counted, { onChange, retry: retry(3), retryDelay: 0 }),
+ (s) => s.status === "error",
+ );
+ assert.ok(isProblem(failed.error) && failed.error.status === 404);
+ assert.equal(opened, 1, "a 404 is not tried again");
+
+ let tries = 0;
+ const broken = {
+ key: ["broken"],
+ open: (): AsyncIterable<{ event: "x"; data: number }> => ({
+ [Symbol.asyncIterator]: () => ({ next: () => (tries++, Promise.reject(new TypeError("fetch failed"))) }),
+ }),
+ };
+ const statuses: string[] = [];
+ const gave = await until>(
+ (onChange) => follow(broken, { onChange: (s) => (statuses.push(s.status), onChange(s)), retry: 2, retryDelay: 0 }),
+ (s) => s.status === "error",
+ );
+ assert.equal(tries, 3, "once, and twice again");
+ assert.equal(gave.error?.message, "fetch failed");
+ assert.deepEqual(statuses, ["connecting", "connecting", "connecting", "error"]);
+});
+
+test("follow() stops when told to, and tells nothing after", async () => {
+ const q = queries(api);
+ const changes: string[] = [];
+ let stop = () => {};
+ await until>(
+ (onChange) => (stop = follow(q.events("/ticks"), { onChange: (s) => (changes.push(s.status), onChange(s)) })),
+ (s) => (s.byName.tick?.n ?? 0) >= 2,
+ );
+ stop();
+ const count = changes.length;
+ await new Promise((r) => setTimeout(r, 40));
+ assert.equal(changes.length, count);
+});
+
+type Say = { type: "say"; text: string };
+type Said = { type: "said"; room: string; text: string };
+
+test("connect() opens a typed WebSocket, sends before it is open, closes", { timeout: 15_000 }, async () => {
+ const server = await live.listen(0, "127.0.0.1");
+ // what the server heard, for the message when a state never comes
+ const heard: string[] = [];
+ server.on("upgrade", (req) => heard.push(`upgrade ${req.method} ${req.url} origin=${req.headers.origin ?? "-"} key=${req.headers["sec-websocket-key"] ? "yes" : "no"} v=${req.httpVersion}`));
+ server.on("request", (req) => heard.push(`request ${req.method} ${req.url} upgrade=${req.headers.upgrade ?? "-"}`));
+ try {
+ const { port } = server.address() as { port: number };
+ const q = queries(client(`http://127.0.0.1:${port}`));
+ const statuses: string[] = [];
+ let conn!: Connection;
+ const said = await until>(
+ (onChange) => {
+ conn = connect(q.ws("/rooms/:room", { params: { room: "tea" } }), { onChange: (s) => (statuses.push(s.status), onChange(s)) });
+ conn.send({ type: "say", text: "hello" }); // still opening: goes once it is open
+ // @ts-expect-error the route takes a say
+ void (() => conn.send({ type: "shout", text: "x" }));
+ },
+ (s) => s.last !== undefined,
+ ).catch((err: Error) => {
+ throw new Error(`${err.message}; server heard: ${JSON.stringify(heard)}; socket readyState=${conn?.socket.raw.readyState}; listeners=${server.listenerCount("upgrade")}`);
+ });
+ assert.deepEqual(said.last, { type: "said", room: "tea", text: "hello" });
+ assert.deepEqual(statuses.slice(0, 2), ["connecting", "open"]);
+ conn.close();
+
+ const refused = await until>(
+ (onChange) => connect(q.ws("/rooms/:room", { params: { room: "x" } }), { onChange }),
+ (s) => s.status !== "connecting",
+ );
+ assert.equal(refused.status, "error", "a room name too short is a 400, and no socket");
+ } finally {
+ // an upgraded socket is no longer the http server's: close it through the app first, or
+ // server.close() waits for it (forever, on Node 22)
+ await live.stopped();
+ server.closeAllConnections();
+ await new Promise((r) => server.close(r));
+ }
+});
+
+test("the React hooks are typed from the route", () => {
+ // types only: running them takes a renderer; follow() and connect() above are what they run
+ const q = queries(api);
+ const component = () => {
+ const job = useEvents(q.events("/exports/:id/events", { params: { id: "1" } }), { retry: retry(2), onEvent: (e) => void e.event });
+ const done: number | undefined = job.byName.progress?.done;
+ const state: string | undefined = job.byName.end?.state;
+ if (job.last?.event === "progress") void (job.last.data.total satisfies number);
+ const status: "idle" | "connecting" | "open" | "closed" | "error" = job.status;
+ // @ts-expect-error the events route needs its id
+ void (() => useEvents(q.events("/exports/:id/events")));
+ // @ts-expect-error a GET that is not a stream
+ void (() => q.events("/exports/:id", { params: { id: "1" } }));
+
+ const room = useSocket(q.ws("/rooms/:room", { params: { room: "tea" } }), { enabled: true, onMessage: (m) => void m.text });
+ room.send({ type: "say", text: "hi" });
+ // @ts-expect-error the route takes a text
+ room.send({ type: "say" });
+ const text: string | undefined = room.last?.text;
+ // @ts-expect-error there is no such WebSocket route
+ void (() => q.ws("/lobby"));
+ return [done, state, status, text, room.socket?.raw];
+ };
+ assert.equal(typeof component, "function");
+ assert.equal(typeof useEvents, "function");
+ assert.equal(typeof useSocket, "function");
+});
diff --git a/packages/uws/CHANGELOG.md b/packages/uws/CHANGELOG.md
index c73017c..3559c37 100644
--- a/packages/uws/CHANGELOG.md
+++ b/packages/uws/CHANGELOG.md
@@ -1,5 +1,15 @@
# Changelog
+## 0.4.0
+
+- WebSocket routes (`app.ws()`) run on uWebSockets.js's websockets. The app decides each
+ upgrade through `app.upgradeListener` (route, origin, maxConnections, hooks, security,
+ input, handshake timeout) and runs the socket; uWS carries the frames. Same handler, same
+ socket, same close codes as `app.listen()`, within the limits the README lists: a message
+ past the largest route's `maxMessage` is cut off by uWS (1006, not 1009).
+- `close()` closes the WebSockets with 1001 before the onClose hooks.
+- Needs inkan 0.8 (peer `>=0.8.0 <1.0.0`).
+
## 0.3.0
- A route's own `bodyLimit` holds, through `app.bodyFor()` (inkan 0.5 and later): 413 past
diff --git a/packages/uws/README.md b/packages/uws/README.md
index 1974f38..0238cf2 100644
--- a/packages/uws/README.md
+++ b/packages/uws/README.md
@@ -3,8 +3,9 @@
Runs an [inkan](https://github.com/inkanjs/inkan) app on
[uWebSockets.js](https://github.com/uNetworking/uWebSockets.js) instead of `node:http`.
The app does not change: contracts, hooks, plugins, problems, streams and the inspector
-all work as they do with `app.listen()`. This package only moves bytes between the socket
-and `app.exchange()`, the one door inkan has for any server.
+all work as they do with `app.listen()`, and so do WebSocket routes (`app.ws()`, inkan 0.8).
+This package only moves bytes between the socket and `app.exchange()`, the one door inkan
+has for any server, and `app.upgradeListener` for WebSockets.
## Install
@@ -44,18 +45,54 @@ falls behind, the socket is paused until it catches up. Both need inkan 0.5 or l
an older one every route has the app's limit. Cookies a handler sets (inkan 0.6 and later)
go out as one `Set-Cookie` header each.
+## WebSockets
+
+An app with `app.ws()` routes gets them on uWebSockets.js's own websockets, nothing to set:
+
+```ts
+const app = inkan().ws("/rooms/:room", { message: Say, send: Said }, (socket, ctx) => {
+ socket.on("message", (m) => void socket.send({ type: "said", text: m.text }));
+});
+await serve(app, { port: 3000 });
+```
+
+The app decides every upgrade, as under `app.listen()`: the route (an unknown path is a 404),
+the origin check first (403 `origin-not-allowed`, before any hook), `maxConnections` (503),
+then the hooks, the security and the params, query and headers checks (401, 400, …), all
+within `handshakeTimeout`. A refusal goes out as the app wrote it; otherwise uWS writes the
+101, with the answer's own headers (request id, cookies). The handler and the socket it gets
+are the same: messages checked against `message` (not JSON or breaking it: 1007; binary on
+such a route: 1003), `send` trimmed to its contract (and checked in development), `send()`
+resolving once the socket can take more, `ctx.signal` aborted on close, 1011 when the handler
+throws. `close()` ends every open socket with 1001 before the onClose hooks.
+
+uWS does the wire: the handshake, frames, UTF-8, fragments, pongs. The app's frames go out as
+uWS sends, pings and ends; what the client sends reaches the app as one frame per message.
+
+Limits, and where they differ from `app.listen()`:
+
+| | |
+| --- | --- |
+| `maxMessage` | each route's own: past it the socket closes with 1009 and says why. uWS's `maxPayloadLength` is the largest `maxMessage` among the app's routes; a message past that is cut off by uWS before the app sees it, **without a close frame**: the client sees 1006, and so does the handler's close listener (uWebSockets.js 20.71 sends no 1009). uWS puts fragments together, so the 1024-fragment rule is left to its cap on the size |
+| `heartbeat` | the route's own, as with `app.listen()`: the app pings through uWS and cuts off a peer that has not answered by the next ping. uWS's `idleTimeout` and automatic pings are off |
+| writing | past 64 KiB waiting in uWS, the next frame waits for uWS's drain; past four times `maxMessage` (1 MiB at least) waiting in all, the socket is cut off with 1008, as with `app.listen()`. uWS never drops a message |
+| reading | uWS cannot pause one socket: messages a handler has not taken yet wait in memory, the client is not slowed down |
+| pings | uWS answers the client's pings itself |
+| `ctx.req` | a stand-in for Node's request (method, url, headers, the socket's address), not an `IncomingMessage` |
+
## Closing
`await server.close()` closes as `app.listen()` does on a ctrl+c: it stops taking requests,
lets the open ones finish, ends the event streams (an endless one would otherwise keep it
-waiting for as long as its client stays), and then runs the app's onClose hooks. After
-`drain` milliseconds whatever is left is closed anyway.
+waiting for as long as its client stays), closes the WebSockets with 1001, and then runs the
+app's onClose hooks. After `drain` milliseconds whatever is left is closed anyway.
## What is the same, what is not
The same set of requests runs against `app.listen()`, `app.fetch()` and this adapter in
CI: routes, bodies and the body limit, problems, HEAD, query and headers, endless event
-streams that stop when the client leaves, onListen and onClose. `workers` (the cluster
+streams that stop when the client leaves, onListen and onClose. The WebSocket routes run
+against the cases inkan tests them with on node:http (websockets.ts). `workers` (the cluster
mode) is for `app.listen()`; run one process per core yourself if you need it here.
Measure before you switch: the bench in the inkan repository has an `inkan-uws` entry
diff --git a/packages/uws/index.d.ts b/packages/uws/index.d.ts
index fa573b6..d4ccaed 100644
--- a/packages/uws/index.d.ts
+++ b/packages/uws/index.d.ts
@@ -5,7 +5,7 @@ export type Served = {
readonly port: number;
/** Where it listens, as a URL: `http://localhost:3000`, or https with `tls`. */
readonly url: string;
- /** Stops taking requests, lets the open ones finish (ends the event streams), then runs the app's onClose hooks. */
+ /** Stops taking requests, lets the open ones finish (ends the event streams, closes the WebSockets with 1001), then runs the app's onClose hooks. */
close(): Promise;
};
@@ -25,6 +25,7 @@ export type ServeOptions = {
/**
* Serves an inkan app on uWebSockets.js. Resolves once it listens, after the app's plugins and onListen hooks.
* Bodies are held to each route's limit; a `t.stream()` route gets its body unread; every cookie
- * the answer carries goes out as a Set-Cookie header of its own.
+ * the answer carries goes out as a Set-Cookie header of its own. WebSocket routes (`app.ws()`)
+ * run on uWS's websockets; `close()` ends them with 1001.
*/
export function serve(app: App, options?: ServeOptions): Promise;
diff --git a/packages/uws/index.js b/packages/uws/index.js
index 5519ab0..3f6c157 100644
--- a/packages/uws/index.js
+++ b/packages/uws/index.js
@@ -1,6 +1,8 @@
// An inkan app on uWebSockets.js instead of node:http. Everything goes through
// app.exchange(), the one door inkan has for any server: the contracts, hooks, problems
// and streams are the app's, this file only moves bytes between the socket and the app.
+// WebSockets go through the other door, app.upgradeListener: the app decides the upgrade
+// and runs the socket, uWS's own websockets carry it (see Pipe below).
//
// import { serve } from "@inkanjs/uws";
// const server = await serve(app, { port: 3000 });
@@ -8,6 +10,7 @@
import { STATUS_CODES } from "node:http";
import { createRequire } from "node:module";
+import { Duplex } from "node:stream";
// uWebSockets.js 20.71 ships an ESM wrapper that imports a file it does not have; its CommonJS entry works
const uWS = createRequire(import.meta.url)("uWebSockets.js");
@@ -37,6 +40,9 @@ export async function serve(app, options = {}) {
};
const server = tls ? uWS.SSLApp({ key_file_name: tls.key, cert_file_name: tls.cert, passphrase: tls.passphrase }) : uWS.App();
+ // the open WebSockets and the handshakes on their way: close() ends them with 1001
+ const pipes = new Set();
+ const sockets = websockets(app, server, pipes, Boolean(tls));
server.any("/*", (res, req) => {
// the request is only readable now, before the first await
const method = req.getCaseSensitiveMethod().toUpperCase();
@@ -45,6 +51,9 @@ export async function serve(app, options = {}) {
const headers = {};
req.forEach((name, value) => (headers[name] = name in headers ? `${headers[name]}, ${value}` : value));
const remote = text(res.getRemoteAddressAsText());
+ // an upgrade uWS did not take (not a GET, a key that is not 24 characters) is still the
+ // app's to refuse, as with app.listen()
+ if (sockets && headers.upgrade !== undefined && /\bupgrade\b/i.test(headers.connection ?? "")) return sockets.refuse(res, method, url, headers, remote);
open++;
let gone = false;
@@ -202,12 +211,10 @@ export async function serve(app, options = {}) {
(closing ??= (async () => {
uWS.us_listen_socket_close(token);
for (const stop of streams) stop();
- if (open > 0) {
- await new Promise((resolve) => {
- idle = resolve;
- setTimeout(resolve, drain).unref();
- });
- }
+ // the WebSockets close with 1001, as with app.listen(); on uWS they are gone at once
+ const waits = [...pipes].map((p) => p.shutdown());
+ if (open > 0) waits.push(new Promise((resolve) => (idle = resolve)));
+ if (waits.length) await Promise.race([Promise.all(waits), new Promise((resolve) => setTimeout(resolve, drain).unref())]);
server.close?.(); // whatever is left after the wait, idle keep-alive sockets too
process.off("SIGINT", onSignal);
process.off("SIGTERM", onSignal);
@@ -239,6 +246,293 @@ export async function serve(app, options = {}) {
};
}
+// ---------- WebSockets ----------
+
+const TEXT = 0x1;
+const BINARY = 0x2;
+const CLOSE = 0x8;
+const PING = 0x9;
+const PONG = 0xa;
+/** Bytes uWS may hold for a socket before the app's next frame waits for its drain. */
+const HIGH = 64 * 1024;
+const SHUTDOWN = "the server is shutting down";
+const SWITCHING = Buffer.from("HTTP/1.1 101 ");
+/** The close codes a close frame may carry (RFC 6455 7.4); what else uWS reports (1006) is a connection that just went. */
+const validCode = (c) => (c >= 1000 && c <= 1014 && c !== 1004 && c !== 1005 && c !== 1006) || (c >= 3000 && c <= 4999);
+
+/**
+ * The app's WebSocket routes on uWS's websockets, when it has any. The app decides every
+ * upgrade itself, through app.upgradeListener: the route, the origin, maxConnections, the
+ * hooks, the security and the input checks, the handshake timeout. uWS does the wire: the
+ * handshake, framing, masking, UTF-8, fragments, pongs, and the cap on a message's size.
+ */
+function websockets(app, server, pipes, secure) {
+ const routes = app.routes().filter((r) => r.method === "WS");
+ if (!routes.length) return; // as app.listen(): an app without WebSocket routes answers upgrades as plain requests
+ const listener = app.upgradeListener;
+ const largest = Math.max(...routes.map((r) => r.spec.maxMessage ?? 1024 * 1024));
+
+ function start(res, method, url, headers, remote, context) {
+ const pipe = new Pipe(res, headers, context, () => pipes.delete(pipe));
+ pipes.add(pipe);
+ res.onAborted(() => pipe.aborted());
+ // what the app reads of a Node request; ctx.req is this
+ const req = { method, url, headers, httpVersion: "1.1", httpVersionMajor: 1, httpVersionMinor: 1, socket: { remoteAddress: remote, encrypted: secure } };
+ listener(req, pipe, Buffer.alloc(0));
+ }
+
+ server.ws("/*", {
+ // each route holds its own maxMessage in the app; uWS cuts off, with 1009, what no route would take
+ maxPayloadLength: largest,
+ // the app's heartbeat (per route) pings; uWS neither pings nor times out on its own
+ idleTimeout: 0,
+ sendPingsAutomatically: false,
+ // nothing is dropped: past HIGH the app's next frame waits for the drain
+ maxBackpressure: HIGH + largest + 1024 * 1024,
+ closeOnBackpressureLimit: false,
+ upgrade(res, req, context) {
+ const query = req.getQuery();
+ const url = req.getUrl() + (query ? `?${query}` : "");
+ const headers = {};
+ req.forEach((name, value) => (headers[name] = name in headers ? `${headers[name]}, ${value}` : value));
+ start(res, "GET", url, headers, text(res.getRemoteAddressAsText()), context);
+ },
+ open: (ws) => ws.getUserData().pipe.opened(ws),
+ message: (ws, data, binary) => ws.getUserData().pipe.in(binary ? BINARY : TEXT, data),
+ pong: (ws, data) => ws.getUserData().pipe.in(PONG, data),
+ drain: (ws) => ws.getUserData().pipe.drained(),
+ close: (ws, code, message) => ws.getUserData().pipe.ended(code, text(message)),
+ });
+
+ return {
+ /** An upgrade uWS passed on to the HTTP routes (its key is not 24 characters): the app answers it, never with a 101. */
+ refuse: (res, method, url, headers, remote) => start(res, method, url, headers, remote, undefined),
+ };
+}
+
+/**
+ * The socket the app gets for an upgrade, in place of the TCP socket Node would hand over.
+ * What the app writes is read back: an HTTP answer (a refusal, written as it is), or the
+ * 101, after which every frame goes out as a uWS send, ping or end. What the client sends
+ * comes in as frames again, whole and checked by uWS already, so the app reads them as it
+ * reads any socket: the message contract, 1007, 1003, the listeners, ctx.signal.
+ */
+class Pipe extends Duplex {
+ /** handshake: the answer is being written; upgrading: the 101 went, uWS has not opened yet; open; gone */
+ state = "handshake";
+ out = Buffer.alloc(0);
+ /** The app's write that waits for uWS to drain. */
+ waiting;
+ /** Whether the app sent its close frame. */
+ sentClose = false;
+
+ constructor(res, headers, context, forget) {
+ super();
+ this.res = res;
+ this.headers = headers;
+ this.context = context;
+ this.once("close", forget);
+ }
+
+ _read() {}
+
+ _write(chunk, _enc, cb) {
+ this.take(chunk, cb);
+ }
+
+ _writev(chunks, cb) {
+ this.take(chunks.length === 1 ? chunks[0].chunk : Buffer.concat(chunks.map((c) => c.chunk)), cb);
+ }
+
+ take(chunk, cb) {
+ if (this.state === "gone") return cb();
+ this.out = this.out.length ? Buffer.concat([this.out, chunk]) : chunk;
+ if (this.state === "handshake") {
+ // the 101 comes as one write; any other answer comes whole with the end of the socket (_final)
+ const end = this.out.indexOf("\r\n\r\n");
+ if (end < 0 || !this.out.subarray(0, SWITCHING.length).equals(SWITCHING)) return cb();
+ const head = this.out.subarray(0, end).toString("latin1");
+ this.out = this.out.subarray(end + 4);
+ this.switch(head);
+ }
+ if (this.state !== "open") return cb(); // frames before uWS opened wait in `out`
+ this.frames();
+ if (this.ws && this.ws.getBufferedAmount() > HIGH) this.waiting = cb;
+ else cb();
+ }
+
+ _final(cb) {
+ if (this.state === "handshake") {
+ this.answer();
+ setImmediate(() => this.destroy()); // the app is done with it: there is nothing more to read
+ }
+ cb();
+ }
+
+ _destroy(err, cb) {
+ const was = this.state;
+ const { res, ws } = this;
+ this.state = "gone";
+ this.res = undefined;
+ this.ws = undefined;
+ if (was === "handshake") res?.close(); // the handshake timed out: cut the connection
+ else ws?.close(); // no close frame: the app cut it off (no pong in time, too much waiting)
+ const waiting = this.waiting;
+ this.waiting = undefined;
+ waiting?.();
+ cb(err);
+ }
+
+ /** The client went away before the handshake was answered. */
+ aborted() {
+ if (this.state !== "handshake") return;
+ this.res = undefined;
+ this.destroy();
+ }
+
+ /** An answer that is not a 101: written as the app wrote it, then the connection ends. */
+ answer() {
+ const res = this.res;
+ this.res = undefined;
+ this.state = "gone";
+ if (!res) return;
+ const end = this.out.indexOf("\r\n\r\n");
+ const lines = this.out.subarray(0, end < 0 ? this.out.length : end).toString("latin1").split("\r\n");
+ const body = end < 0 ? "" : this.out.subarray(end + 4);
+ const status = lines.shift().slice("HTTP/1.1 ".length);
+ res.cork(() => {
+ res.writeStatus(status);
+ for (const line of lines) {
+ const at = line.indexOf(":");
+ const name = line.slice(0, at).toLowerCase();
+ if (name === "content-length" || name === "connection") continue; // uWS writes those
+ res.writeHeader(name, line.slice(at + 1).trim());
+ }
+ res.end(body, true);
+ });
+ }
+
+ /** The 101: uWS writes it, with its own accept key and the answer's own headers (request id, cookies). */
+ switch(head) {
+ const res = this.res;
+ this.res = undefined;
+ if (!res || !this.context) return void this.destroy(); // nothing to upgrade with: the app never says 101 to those
+ this.state = "upgrading";
+ res.cork(() => {
+ res.writeStatus("101 Switching Protocols");
+ for (const line of head.split("\r\n").slice(1)) {
+ const at = line.indexOf(":");
+ const name = line.slice(0, at).toLowerCase();
+ if (name === "upgrade" || name === "connection" || name === "sec-websocket-accept") continue;
+ res.writeHeader(name, line.slice(at + 1).trim());
+ }
+ // no subprotocol and no extension, as with app.listen(): the frames go as they are
+ res.upgrade({ pipe: this }, this.headers["sec-websocket-key"], "", "", this.context);
+ });
+ }
+
+ opened(ws) {
+ if (this.state !== "upgrading") return void ws.close(); // destroyed between the 101 and now
+ this.ws = ws;
+ this.state = "open";
+ this.frames(); // what the handler sent before uWS opened
+ }
+
+ /** The app's frames out, as uWS sends. They are never fragmented and never masked. */
+ frames() {
+ // corked: a send from outside a uWS callback (a handler's await) is otherwise not flushed
+ if (this.state === "open" && this.out.length >= 2) this.ws.cork(() => this.unframe());
+ }
+
+ unframe() {
+ let b = this.out;
+ while (b.length >= 2 && this.state === "open") {
+ const len7 = b[1] & 0x7f;
+ const at = len7 < 126 ? 2 : len7 === 126 ? 4 : 10;
+ if (b.length < at) break;
+ const len = len7 < 126 ? len7 : len7 === 126 ? b.readUInt16BE(2) : b.readUInt32BE(2) * 2 ** 32 + b.readUInt32BE(6);
+ if (b.length < at + len) break;
+ this.frame(b[0] & 0x0f, b.subarray(at, at + len));
+ b = b.subarray(at + len);
+ }
+ this.out = this.state === "open" ? b : Buffer.alloc(0);
+ }
+
+ frame(op, payload) {
+ const ws = this.ws;
+ if (op === TEXT || op === BINARY) ws.send(payload, op === BINARY);
+ else if (op === PING) ws.ping(payload);
+ else if (op === CLOSE) {
+ // the app closes: uWS sends the frame and reports the close at once (ended)
+ this.sentClose = true;
+ if (payload.length >= 2) ws.end(payload.readUInt16BE(0), payload.subarray(2));
+ else ws.end();
+ }
+ // a pong: uWS answers pings itself, so the app is never handed one to answer
+ }
+
+ /** A message or a pong from the client: a frame for the app, masked as a client's are (with zeros). */
+ in(op, data) {
+ if (this.state !== "open") return;
+ this.push(clientFrame(op, new Uint8Array(data))); // a copy: uWS takes the memory back after this call
+ }
+
+ drained() {
+ if (!this.waiting || !this.ws || this.ws.getBufferedAmount() > HIGH) return;
+ const cb = this.waiting;
+ this.waiting = undefined;
+ // not from inside the drain handler: what uWS (20.71) is handed there can stay buffered for good
+ setImmediate(cb);
+ }
+
+ /** Closed on uWS: by the client, by uWS (a message too large), or after an end() of the app's or of close(). */
+ ended(code, reason) {
+ if (this.state === "gone") return;
+ this.state = "gone";
+ this.ws = undefined;
+ if (!this.sentClose) {
+ // the app learns it as from a close frame; a connection that just went (1006) has none
+ if (validCode(code)) {
+ const r = Buffer.from(reason);
+ const payload = Buffer.allocUnsafe(2 + r.length);
+ payload.writeUInt16BE(code, 0);
+ r.copy(payload, 2);
+ this.push(clientFrame(CLOSE, payload));
+ } else if (code === 1005) this.push(clientFrame(CLOSE, new Uint8Array(0)));
+ }
+ this.push(null);
+ setImmediate(() => this.destroy());
+ }
+
+ /** For close(): an open socket ends with 1001, a handshake on its way is cut. Resolves once it is gone. */
+ shutdown() {
+ const gone = this.destroyed ? Promise.resolve() : new Promise((resolve) => this.once("close", resolve));
+ if (this.state === "open") this.ws.end(1001, SHUTDOWN);
+ else this.destroy();
+ return gone;
+ }
+}
+
+/** A frame as a client sends it: one, final, masked with zeros so the bytes stay as they are. */
+function clientFrame(op, data) {
+ const len = data.byteLength;
+ const ext = len < 126 ? 0 : len < 65536 ? 2 : 8;
+ const f = Buffer.allocUnsafe(6 + ext + len);
+ f[0] = 0x80 | op;
+ if (len < 126) f[1] = 0x80 | len;
+ else if (len < 65536) {
+ f[1] = 0x80 | 126;
+ f.writeUInt16BE(len, 2);
+ } else {
+ f[1] = 0x80 | 127;
+ f.writeUInt32BE(Math.floor(len / 2 ** 32), 2);
+ f.writeUInt32BE(len >>> 0, 6);
+ }
+ f.fill(0, 2 + ext, 6 + ext);
+ f.set(data, 6 + ext);
+ return f;
+}
+
/** One line in the app's log, in its format: what app.listen() would say, said here. */
function say(app, msg, url) {
const { log, logger } = app.options;
diff --git a/packages/uws/package.json b/packages/uws/package.json
index 59a0d29..5ff32d0 100644
--- a/packages/uws/package.json
+++ b/packages/uws/package.json
@@ -1,6 +1,6 @@
{
"name": "@inkanjs/uws",
- "version": "0.3.0",
+ "version": "0.4.0",
"description": "Runs an inkan app on uWebSockets.js instead of node:http.",
"type": "module",
"license": "MIT",
@@ -26,7 +26,7 @@
"node": ">=22.18"
},
"peerDependencies": {
- "@vxnsin/inkan": ">=0.4.0",
+ "@vxnsin/inkan": ">=0.8.0 <1.0.0",
"uWebSockets.js": ">=20.71.0"
},
"scripts": {
@@ -38,7 +38,7 @@
}
},
"devDependencies": {
- "@vxnsin/inkan": "^0.6.0"
+ "@vxnsin/inkan": "^0.8.0"
},
"keywords": [
"inkan",
diff --git a/packages/uws/test.ts b/packages/uws/test.ts
index 0bb279b..62e3931 100644
--- a/packages/uws/test.ts
+++ b/packages/uws/test.ts
@@ -1,5 +1,5 @@
// The same requests every way of serving inkan has to answer alike, on uWebSockets.js, and
-// what only this adapter does: closing gently, and HTTPS. uWebSockets.js is installed on
+// what only this adapter does: closing gently, HTTPS, WebSockets (websockets.ts). uWebSockets.js is installed on
// purpose, from GitHub (see README); without it this test is skipped, unless REQUIRE_UWS
// says it has to run, as it does in CI.
import { test } from "node:test";
@@ -12,6 +12,7 @@ import { tmpdir } from "node:os";
import { join } from "node:path";
import { inkan, sse, t } from "@vxnsin/inkan";
import { conformance } from "./conformance.ts";
+import { websockets } from "./websockets.ts";
/** A request body sent in pieces, chunked, with no length declared. */
function streamOf(pieces: Iterable | AsyncIterable): ReadableStream {
@@ -41,6 +42,7 @@ if (installed) {
const server = await serve(app, { port: 0, host: "127.0.0.1" });
return { url: server.url, close: () => server.close() };
});
+ websockets(serve);
test("close() lets an open request finish, ends the streams, then runs onClose", { timeout: 20_000 }, async () => {
const events: string[] = [];
diff --git a/packages/uws/websockets.ts b/packages/uws/websockets.ts
new file mode 100644
index 0000000..248bad2
--- /dev/null
+++ b/packages/uws/websockets.ts
@@ -0,0 +1,434 @@
+// WebSocket routes (app.ws) on uWebSockets.js: the same handshake, refusals, message contract,
+// limits and close codes as app.listen(), with Node's own WebSocket as the client, and a
+// client that writes frames by hand where the platform one cannot say what is needed.
+// test.ts runs them when uWebSockets.js is installed.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { connect, type Socket } from "node:net";
+import { randomBytes } from "node:crypto";
+import { inkan, t, type App } from "@vxnsin/inkan";
+import type { serve as Serve } from "./index.js";
+
+const quiet = { log: false, gracefulShutdown: false } as const;
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+const Say = t.discriminated("type", {
+ say: t.object({ type: t.literal("say"), text: t.string().max(20) }),
+ leave: t.object({ type: t.literal("leave") }),
+});
+const Said = t.object({ type: t.enum(["said", "joined"]), text: t.string(), from: t.string() });
+
+const chat = () =>
+ inkan(quiet).ws(
+ "/rooms/: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, secret: "kept back" } as never);
+ 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 });
+ });
+ },
+ );
+
+const parsed = (s: string) => {
+ try {
+ return JSON.parse(s);
+ } catch {
+ return s;
+ }
+};
+/** The next messages of a platform WebSocket, parsed when they are JSON. */
+function inbox(ws: WebSocket) {
+ const got: unknown[] = [];
+ const waiting: ((v: unknown) => void)[] = [];
+ ws.addEventListener("message", (e) => {
+ const v = typeof e.data === "string" ? parsed(e.data) : e.data;
+ const w = waiting.shift();
+ w ? w(v) : got.push(v);
+ });
+ return () => (got.length ? Promise.resolve(got.shift()) : new Promise((r) => waiting.push(r)));
+}
+const opened = (ws: WebSocket) =>
+ new Promise((resolve, reject) => {
+ ws.addEventListener("open", () => resolve(), { once: true });
+ ws.addEventListener("error", () => reject(new Error("did not open")), { once: true });
+ });
+const closed = (ws: WebSocket) => new Promise<{ code: number; reason: string }>((r) => ws.addEventListener("close", (e) => r({ code: e.code, reason: e.reason }), { once: true }));
+
+type Frame = { op: number; payload: Buffer };
+type Raw = { status: number; head: string; text: string; sock: Socket; next: (ms?: number) => Promise };
+
+/** An upgrade written by hand: the answer's head (and body, for a refusal), then the frames that come. */
+function raw(port: number, path: string, extra = "", key = randomBytes(16).toString("base64")): Promise {
+ return new Promise((resolve, reject) => {
+ const sock = connect(port, "127.0.0.1");
+ sock.write(`GET ${path} HTTP/1.1\r\nHost: x\r\nUpgrade: websocket\r\nConnection: Upgrade\r\nSec-WebSocket-Version: 13\r\nSec-WebSocket-Key: ${key}\r\n${extra}\r\n`);
+ let buf = Buffer.alloc(0);
+ let head: string | undefined;
+ let text = "";
+ const frames: (Frame | null)[] = [];
+ const waiting: ((f: Frame | null) => void)[] = [];
+ const push = (f: Frame | null) => {
+ const w = waiting.shift();
+ w ? w(f) : frames.push(f);
+ };
+ sock.on("error", reject);
+ sock.on("close", () => {
+ if (head === undefined) resolve({ status: Number(text.split(" ")[1]) || 0, head: text, text, sock, next });
+ push(null);
+ });
+ sock.on("data", (b: Buffer) => {
+ text += b.toString();
+ buf = Buffer.concat([buf, b]);
+ if (head === undefined) {
+ const end = buf.indexOf("\r\n\r\n");
+ if (end < 0) return;
+ const status = Number(buf.subarray(0, end).toString().split(" ")[1]);
+ if (status !== 101) return; // a refusal: the whole answer, once the server hangs up
+ head = buf.subarray(0, end).toString();
+ buf = buf.subarray(end + 4);
+ resolve({ status, head, text, sock, next });
+ }
+ for (;;) {
+ if (buf.length < 2) return;
+ let len = buf[1]! & 0x7f;
+ let at = 2;
+ if (len === 126) (len = buf.readUInt16BE(2)), (at = 4);
+ else if (len === 127) (len = Number(buf.readBigUInt64BE(2))), (at = 10);
+ if (buf.length < at + len) return;
+ push({ op: buf[0]! & 0x0f, payload: Buffer.from(buf.subarray(at, at + len)) });
+ buf = buf.subarray(at + len);
+ }
+ });
+ function next(ms = 2000): Promise {
+ if (frames.length) return Promise.resolve(frames.shift()!);
+ return new Promise((resolve, reject) => {
+ const timer = setTimeout(() => reject(new Error("no frame came")), ms);
+ waiting.push((f) => (clearTimeout(timer), resolve(f)));
+ });
+ }
+ });
+}
+
+export function websockets(serve: typeof Serve) {
+ async function served(app: App) {
+ const server = await serve(app, { port: 0, host: "127.0.0.1" });
+ return { port: server.port, url: server.url.replace(/^http/, "ws"), http: server.url, close: () => server.close() };
+ }
+
+ test("uws ws: handshake and echo, typed both ways, trimmed to `send`; the server's close code reaches the client", async () => {
+ const s = await served(chat());
+ try {
+ const ws = new WebSocket(`${s.url}/rooms/tea?name=ana`);
+ const next = inbox(ws);
+ await opened(ws);
+ assert.deepEqual(await next(), { type: "joined", text: "tea", from: "ana" });
+ ws.send(JSON.stringify({ type: "say", text: "hello" }));
+ assert.deepEqual(await next(), { type: "said", text: "hello", from: "ana" });
+ const end = closed(ws);
+ ws.send(JSON.stringify({ type: "leave" }));
+ assert.deepEqual(await end, { code: 4000, reason: "bye" });
+ } finally {
+ await s.close();
+ }
+ });
+
+ test("uws ws: the 101 carries the accept key and the answer's own headers", async () => {
+ const s = await served(chat());
+ try {
+ const r = await raw(s.port, "/rooms/a?name=x", "x-request-id: abc-123\r\n");
+ assert.equal(r.status, 101);
+ assert.match(r.head, /sec-websocket-accept: [A-Za-z0-9+/=]{28}/i);
+ assert.match(r.head, /x-request-id: abc-123/i);
+ r.sock.destroy();
+ } finally {
+ await s.close();
+ }
+ });
+
+ test("uws ws: a message that breaks the contract or is not JSON closes with 1007; binary on a contract route with 1003", async () => {
+ const s = await served(chat());
+ try {
+ const a = new WebSocket(`${s.url}/rooms/a?name=x`);
+ await opened(a);
+ const endA = closed(a);
+ a.send(JSON.stringify({ type: "say", text: "x".repeat(30) }));
+ const ca = await endA;
+ assert.equal(ca.code, 1007);
+ assert.match(ca.reason, /text/);
+ assert.doesNotMatch(ca.reason, /xxxx/, "the reason echoes no input");
+
+ const b = new WebSocket(`${s.url}/rooms/a?name=x`);
+ await opened(b);
+ const endB = closed(b);
+ b.send("not json");
+ assert.deepEqual(await endB, { code: 1007, reason: "the message is not JSON" });
+
+ const c = new WebSocket(`${s.url}/rooms/a?name=x`);
+ await opened(c);
+ const endC = closed(c);
+ c.send(new Uint8Array([1, 2, 3]));
+ assert.deepEqual(await endC, { code: 1003, reason: "messages are JSON text, not binary" });
+ } finally {
+ await s.close();
+ }
+ });
+
+ test("uws ws: origin, security, input and path answer the upgrade with their status before any socket", async () => {
+ let hooks = 0;
+ const app = inkan(quiet)
+ .ws("/secure", { security: "bearer" }, (socket) => void socket.sendRaw("in"))
+ .ws("/q", { query: t.object({ n: t.int() }) }, () => {})
+ .ws("/listed", { origins: ["https://good.example"] }, () => {})
+ .ws("/one", { maxConnections: 1 }, () => {})
+ .get("/plain", () => ({ ok: true }));
+ app.onRequest(() => void hooks++);
+ const s = await served(app);
+ try {
+ const evil = await raw(s.port, "/q?n=1", "Origin: http://evil.example\r\nCookie: sid=abc\r\n");
+ assert.equal(evil.status, 403);
+ assert.match(evil.text, /"type":"origin-not-allowed"/);
+ assert.equal(hooks, 0, "no hook ran");
+ const own = await raw(s.port, "/q?n=1", "Origin: http://x\r\n");
+ assert.equal(own.status, 101, "the own origin, by the Host header");
+ own.sock.destroy();
+ const listed = await raw(s.port, "/listed", "Origin: https://good.example\r\n");
+ assert.equal(listed.status, 101);
+ listed.sock.destroy();
+
+ const no = await raw(s.port, "/secure");
+ assert.equal(no.status, 401);
+ assert.match(no.text, /"type":"unauthorized"/);
+ assert.match(no.text, /www-authenticate: Bearer/i);
+ assert.equal((await raw(s.port, "/q?n=abc")).status, 400);
+ assert.equal((await raw(s.port, "/nowhere")).status, 404);
+ assert.equal((await raw(s.port, "/plain")).status, 404, "an HTTP route is no WebSocket");
+ assert.equal((await raw(s.port, "/q?n=1", "", "short")).status, 400, "a key uWS does not take is the app's to refuse");
+ assert.equal((await raw(s.port, "/q?n=1", "", "AAAAAAAAAAAAAAAAAAAAAB==")).status, 400, "not canonical base64");
+ assert.equal((await fetch(`${s.http}/q?n=1`)).status, 426, "a plain request to a WebSocket path");
+ assert.equal((await fetch(`${s.http}/plain`)).status, 200, "and the HTTP routes beside them are untouched");
+
+ const first = await raw(s.port, "/one");
+ assert.equal(first.status, 101);
+ const second = await raw(s.port, "/one");
+ assert.equal(second.status, 503);
+ first.sock.destroy();
+ await sleep(50);
+ const third = await raw(s.port, "/one");
+ assert.equal(third.status, 101, "the slot is free again");
+ third.sock.destroy();
+
+ // Node's WebSocket takes headers: the bearer token goes with the upgrade
+ const ws = new WebSocket(`${s.url}/secure`, { headers: { authorization: "Bearer t" } } as never);
+ const next = inbox(ws);
+ await opened(ws);
+ assert.equal(await next(), "in");
+ ws.close();
+ } finally {
+ await s.close();
+ }
+ });
+
+ test("uws ws: a handshake that never gets its answer is cut off", async () => {
+ const app = inkan(quiet).ws("/slow", { handshakeTimeout: 100 }, () => {});
+ app.onRequest(() => new Promise(() => {}));
+ const s = await served(app);
+ try {
+ const started = Date.now();
+ const r = await raw(s.port, "/slow");
+ assert.equal(r.status, 0, "no answer, the connection just ends");
+ assert.ok(Date.now() - started < 2000);
+ } finally {
+ await s.close();
+ }
+ });
+
+ test("uws ws: maxMessage closes with 1009 per route; past the largest route's, uWS cuts the connection (1006)", async () => {
+ const echo = (socket: { on: (e: "message", fn: (m: string | Buffer) => void) => unknown; sendRaw: (m: string | Buffer) => Promise }) =>
+ void socket.on("message", (m) => void socket.sendRaw(m));
+ const app = inkan(quiet)
+ .ws("/small", { maxMessage: 16 }, echo)
+ .ws("/roomy", { maxMessage: 1000 }, echo);
+ const s = await served(app);
+ try {
+ const a = new WebSocket(`${s.url}/small`);
+ const next = inbox(a);
+ await opened(a);
+ a.send("x".repeat(16));
+ assert.equal(await next(), "x".repeat(16), "the limit itself is fine");
+ const endA = closed(a);
+ a.send("x".repeat(17));
+ assert.deepEqual(await endA, { code: 1009, reason: "messages may have at most 16 bytes" });
+
+ const b = new WebSocket(`${s.url}/small`);
+ await opened(b);
+ const endB = closed(b);
+ b.send("x".repeat(5000));
+ assert.equal((await endB).code, 1006, "uWS closes without a close frame");
+ } finally {
+ await s.close();
+ }
+ });
+
+ test("uws ws: without a contract text is a string and binary a Buffer; large messages both ways", async () => {
+ const got: unknown[] = [];
+ const app = inkan(quiet).ws("/raw", {}, (socket) =>
+ socket.on("message", (m) => {
+ got.push(Buffer.isBuffer(m) ? ["buffer", m.length] : ["string", (m as string).length]);
+ void socket.sendRaw(m);
+ }),
+ );
+ const s = await served(app);
+ try {
+ const ws = new WebSocket(`${s.url}/raw`);
+ ws.binaryType = "arraybuffer";
+ const next = inbox(ws);
+ await opened(ws);
+ ws.send("hi");
+ assert.equal(await next(), "hi");
+ const big = randomBytes(200_000);
+ ws.send(big);
+ const back = (await next()) as ArrayBuffer;
+ assert.ok(Buffer.from(back).equals(big));
+ ws.send("é".repeat(100_000));
+ assert.equal(await next(), "é".repeat(100_000));
+ assert.deepEqual(got, [["string", 2], ["buffer", 200_000], ["string", 100_000]]);
+ ws.close();
+ } finally {
+ await s.close();
+ }
+ });
+
+ test("uws ws: send resolves once the socket can take more, and bufferedAmount says how much waits", async () => {
+ let done = false;
+ let buffered = -1;
+ const app = inkan(quiet).ws("/flood", {}, async (socket) => {
+ const chunk = "z".repeat(64 * 1024);
+ for (let i = 0; i < 64; i++) await socket.sendRaw(chunk);
+ buffered = socket.bufferedAmount;
+ done = true;
+ });
+ const s = await served(app);
+ try {
+ const ws = new WebSocket(`${s.url}/flood`);
+ let count = 0;
+ ws.addEventListener("message", () => count++);
+ await opened(ws);
+ while (count < 64) await sleep(10);
+ for (let i = 0; i < 50 && !done; i++) await sleep(10);
+ assert.equal(done, true);
+ assert.equal(typeof buffered, "number");
+ ws.close();
+ } finally {
+ await s.close();
+ }
+ });
+
+ test("uws ws: a handler that writes past the buffer limit without waiting is cut off with 1008", async () => {
+ let code: number | undefined;
+ const app = inkan(quiet).ws("/flood", { heartbeat: false }, (socket) => {
+ socket.on("close", (c) => (code = c));
+ const chunk = Buffer.alloc(64 * 1024);
+ for (let i = 0; i < 400; i++) void socket.sendRaw(chunk);
+ });
+ const s = await served(app);
+ try {
+ const r = await raw(s.port, "/flood");
+ r.sock.pause();
+ for (let i = 0; i < 100 && code === undefined; i++) await sleep(20);
+ assert.equal(code, 1008);
+ r.sock.destroy();
+ } finally {
+ await s.close();
+ }
+ });
+
+ test("uws ws: the client's close code reaches the handler; ctx.signal aborts; late listeners and the iterator get every message", async () => {
+ let got: [number, string] | undefined;
+ let aborted = false;
+ const app = inkan(quiet)
+ .ws("/hear", {}, (socket) => socket.on("close", (code, reason) => (got = [code, reason])))
+ .ws("/late", { message: t.object({ n: t.int() }), send: t.object({ sum: t.int() }) }, async (socket, ctx) => {
+ ctx.signal.addEventListener("abort", () => (aborted = true));
+ await sleep(50); // the client sends before anybody listens
+ let sum = 0;
+ for await (const m of socket) {
+ sum += m.n;
+ if (sum >= 6) await socket.send({ sum });
+ }
+ });
+ const s = await served(app);
+ try {
+ const a = new WebSocket(`${s.url}/hear`);
+ await opened(a);
+ a.close(4002, "bye");
+ await closed(a);
+ for (let i = 0; i < 50 && !got; i++) await sleep(10);
+ assert.deepEqual(got, [4002, "bye"]);
+
+ const b = new WebSocket(`${s.url}/late`);
+ const next = inbox(b);
+ await opened(b);
+ for (const n of [1, 2, 3]) b.send(JSON.stringify({ n }));
+ assert.deepEqual(await next(), { sum: 6 });
+ b.close(1000);
+ await closed(b);
+ for (let i = 0; i < 50 && !aborted; i++) await sleep(10);
+ assert.equal(aborted, true);
+ } finally {
+ await s.close();
+ }
+ });
+
+ test("uws ws: in development a message that breaks `send` throws: reported, and the socket closes with 1011", async () => {
+ const errors: unknown[] = [];
+ const app = inkan({ ...quiet, onError: (e) => void errors.push(e) }).ws("/bad", { send: t.object({ n: t.int() }) }, (socket) => {
+ void socket.send({ n: "one" } as never);
+ });
+ const s = await served(app);
+ try {
+ const ws = new WebSocket(`${s.url}/bad`);
+ assert.equal((await closed(ws)).code, 1011);
+ assert.match(String(errors[0]), /WS \/bad sent a message that breaks its contract: n/);
+ } finally {
+ await s.close();
+ }
+ });
+
+ test("uws ws: heartbeat: a peer that answers pings stays, one that does not is cut off", { timeout: 15_000 }, async () => {
+ const app = inkan(quiet).ws("/hb", { heartbeat: 250 }, (socket) => socket.on("message", (m) => void socket.sendRaw(m)));
+ const s = await served(app);
+ try {
+ const ws = new WebSocket(`${s.url}/hb`); // answers pings by itself
+ const next = inbox(ws);
+ await opened(ws);
+ await sleep(800);
+ ws.send('"still here"');
+ assert.equal(await next(), "still here");
+ ws.close();
+
+ const r = await raw(s.port, "/hb"); // never answers
+ assert.equal((await r.next())?.op, 0x9, "the server pings");
+ assert.equal(await r.next(), null, "and hangs up without a pong");
+ } finally {
+ await s.close();
+ }
+ });
+
+ test("uws ws: close() ends every open socket with 1001, then runs onClose", async () => {
+ const events: string[] = [];
+ const app = inkan(quiet)
+ .ws("/stay", {}, (socket) => socket.on("close", (code) => void events.push(`socket ${code}`)))
+ .onClose(() => void events.push("onClose"));
+ const s = await served(app);
+ const ws = new WebSocket(`${s.url}/stay`);
+ await opened(ws);
+ const end = closed(ws);
+ const started = Date.now();
+ await s.close();
+ assert.ok(Date.now() - started < 2000, "it does not wait for the drain");
+ assert.deepEqual(await end, { code: 1001, reason: "the server is shutting down" });
+ assert.deepEqual(events, ["socket 1001", "onClose"]);
+ });
+}