From 694ce041e274a526d8044aace0a91a18b62df4cf Mon Sep 17 00:00:00 2001 From: Vensin Date: Mon, 19 Oct 2026 13:08:40 +0200 Subject: [PATCH 1/7] feat(query): live events and WebSockets, React hooks (0.3.0) --- package-lock.json | 36 ++++++- packages/query/CHANGELOG.md | 16 +++ packages/query/README.md | 85 ++++++++++++++++ packages/query/index.d.ts | 106 +++++++++++++++++++- packages/query/index.js | 103 ++++++++++++++++++++ packages/query/package.json | 25 ++++- packages/query/react.d.ts | 34 +++++++ packages/query/react.js | 57 +++++++++++ packages/query/test.ts | 188 +++++++++++++++++++++++++++++++++++- 9 files changed, 639 insertions(+), 11 deletions(-) create mode 100644 packages/query/react.d.ts create mode 100644 packages/query/react.js diff --git a/package-lock.json b/package-lock.json index 80484d6..1c1a92a 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1278,17 +1278,47 @@ }, "packages/query": { "name": "@inkanjs/query", - "version": "0.2.0", + "version": "0.3.0", "license": "MIT", "devDependencies": { "@tanstack/query-core": "^5.104.1", - "@vxnsin/inkan": "^0.4.0" + "@vxnsin/inkan": "^0.7.0", + "react": "^19.3.0" }, "engines": { "node": ">=22.18" }, "peerDependencies": { - "@vxnsin/inkan": ">=0.4.0" + "@vxnsin/inkan": ">=0.7.0", + "react": ">=18" + }, + "peerDependenciesMeta": { + "react": { + "optional": true + } + } + }, + "packages/query/node_modules/@vxnsin/inkan": { + "version": "0.7.0", + "resolved": "https://registry.npmjs.org/@vxnsin/inkan/-/inkan-0.7.0.tgz", + "integrity": "sha512-d9RavATzolWCk/WHy4ktZVHNT/obYwfllRHHuwUgmEAqYI6f/JoWl6TVPGQ9T8iHwc48pOB1+5opELAzIWzaSw==", + "dev": true, + "license": "MIT", + "bin": { + "inkan": "dist/cli.js" + }, + "engines": { + "node": ">=22" + } + }, + "packages/query/node_modules/react": { + "version": "19.3.0", + "resolved": "https://registry.npmjs.org/react/-/react-19.3.0.tgz", + "integrity": "sha512-E8LUcbtBWt20bbl2YoHfx4ZDBdxVTfOKtCZn9cDSJ4l6/nuoApcpIBcj47t2wZoVX8g2ZHuMHbiShgCR1T5Sog==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=0.10.0" } }, "packages/uws": { diff --git a/packages/query/CHANGELOG.md b/packages/query/CHANGELOG.md index 7b5fb8d..7c59f87 100644 --- a/packages/query/CHANGELOG.md +++ b/packages/query/CHANGELOG.md @@ -1,5 +1,21 @@ # Changelog +## 0.3.0 (unreleased) + +- `q.events(path, input)` and `q.ws(path, input)`: live sources for a route that answers + with `t.events(...)` and for an `app.ws` route, typed from it. A path that is no stream + or no WebSocket is a type error. +- `@inkanjs/query/react`: `useEvents(source, { enabled, onEvent, retry, retryDelay })` gives + `{ last, byName, status, error }`, every event typed by its name; `useSocket(source, + { enabled, onMessage })` gives `{ send, last, status, error, socket }`. Both close on + unmount and open again when the path or input changes. `react` is an optional peer. +- `follow(source, options)` and `connect(source, options)`: what the hooks run, without + React, for Vue, Svelte, Solid or a store of your own. +- A stream that does not open is a `ProblemError`, so `isProblem` and `retry()` work on it. + No reconnect unless `retry` asks for one. Events are not written to the query cache; + `onEvent` with `setQueryData` does it in a line (see the README). +- Needs `@vxnsin/inkan` 0.7 or later, for `client.events` and `client.ws`. + ## 0.2.0 - `queries(client)`: query and mutation options straight from the typed client. diff --git a/packages/query/README.md b/packages/query/README.md index 578a0d6..1fedb0e 100644 --- a/packages/query/README.md +++ b/packages/query/README.md @@ -63,3 +63,88 @@ useMutation(mutation((tea: { name: string }) => shop.post("/teas", { body: tea } `unwrap(answer)` does the same for one answer anywhere else: its data, or a `ProblemError`. This package needs no TanStack package itself; bring the adapter for your framework. + +## Live data: events and WebSockets + +A stream of server-sent events and a WebSocket are no queries: they do not answer once, and +there is nothing to refetch. `q.events` and `q.ws` make live sources of them, typed from the +route like everything else, and `@inkanjs/query/react` follows them in a component: + +```tsx +import { useEvents, useSocket } from "@inkanjs/query/react"; + +// a GET that answers with t.events({ ... }) +const feed = useEvents(q.events("/teas/:id/events", { params: { id } })); +feed.status; // "connecting" | "open" | "closed" | "error" ("idle" while not enabled) +feed.last; // the last event: feed.last?.event === "brewed" narrows feed.last.data +feed.byName.brewed; // the latest data of each event, by name +feed.error; // a stream that did not open: a ProblemError, isProblem(feed.error, "tea-not-found") + +// an app.ws route: send takes its `message`, last is the last of its `send` +const room = useSocket(q.ws("/rooms/:room", { params: { room } }), { onMessage: (m) => log(m) }); +room.send({ type: "say", text: "hello" }); // sent while opening, it goes once the socket is open +room.status; room.last; room.socket; // the TypedSocket underneath: on, ready, raw +``` + +Both open when the component mounts, open again when the path or input changes, and close +when it unmounts. `enabled: false` keeps them closed. A stream that ends stays closed, and +one that fails is not opened again unless `retry` says so: `true`, a number of times, or a +function as for TanStack, so `retry: retry(3)` tries again after a dropped connection or a +503, not after a 404. `retryDelay` is 1 s, doubling, at most 30 s. + +The hooks need `react` (18 or later); nothing else here does. For Vue, Svelte or Solid, +`follow(source, { onChange, onEvent, retry, signal })` and +`connect(source, { onChange, onMessage })` are what the hooks run: the same state, handed to +`onChange` after every change, for a ref or a store of your own. + +### Events are not written to the cache + +The hooks keep their state themselves and write nothing to the QueryClient: which query an +event belongs to is the app's to say, and `onEvent` says it in a line. A job's `status` and +`end` events carry the job as `GET /exports/:id` answers with it, so they can keep that +query fresh: + +```ts +const queryClient = useQueryClient(); +const job = q.get("/exports/:id", { params: { id } }); +useEvents(q.events("/exports/:id/events", { params: { id } }), { + onEvent: (e) => e.event !== "progress" && queryClient.setQueryData(job.queryKey, e.data), +}); +``` + +## Recipe: following a job + +An `app.job("/exports", ...)` on the server gives `POST /exports` to start one, +`GET /exports/:id/events` to follow it (`status`, then `progress`, then `end`) and +`GET /exports/:id/result` for what it made. Start it with a mutation, follow it while it +runs, and fetch the result once it is done: + +```tsx +import { useMutation, useQuery } from "@tanstack/react-query"; +import { queries } from "@inkanjs/query"; +import { useEvents } from "@inkanjs/query/react"; + +const q = queries(api); + +function Export() { + const start = useMutation(q.post("/exports")); + const id = start.data?.id; // the job, as the 202 answered with it + + const job = useEvents(q.events("/exports/:id/events", { params: { id: id! } }), { enabled: !!id }); + const state = job.byName.end?.state ?? job.byName.status?.state; + + const result = useQuery({ + ...q.get("/exports/:id/result", { params: { id: id! } }), + enabled: state === "done", + }); + + if (!id) return ; + if (job.error) return

{job.error.message}

; + if (state === "failed") return

{job.byName.end?.error?.detail}

; + if (result.data) return Download; + const p = job.byName.progress; // typed from the job's `progress` schema + return ; +} +``` + +The stream ends with `end`, so `job.status` turns `closed` by itself; nothing reconnects. diff --git a/packages/query/index.d.ts b/packages/query/index.d.ts index 9b2bb6a..f5417aa 100644 --- a/packages/query/index.d.ts +++ b/packages/query/index.d.ts @@ -1,5 +1,5 @@ import type { ProblemBody, Responses, Routes } from "@vxnsin/inkan"; -import type { Answer, Client, Input } from "@vxnsin/inkan/client"; +import type { Answer, Client, EventOf, Input, Jsonify, TypedSocket } from "@vxnsin/inkan/client"; /** What the typed client answers: success or failure, told apart by `ok`. */ type AnyAnswer = { ok: true; data: unknown } | { ok: false; status: number; problem: unknown }; @@ -65,7 +65,111 @@ export type Queries = { put: Write, "PUT">; patch: Write, "PATCH">; delete: Write, "DELETE">; + /** A live source for useEvents / follow: a GET that answers with `t.events(...)`. */ + events: Live>; + /** A live source for useSocket / connect: a WebSocket route. */ + ws: Ws>; }; /** Query and mutation options straight from the typed client, keyed by path and input. */ export function queries(client: Client): Queries; + +// ---- live data: server-sent events and WebSockets + +/** One event of a stream: its name, its data typed by the name, and its id when it had one. */ +export type AnyEvent = { event: string; data: unknown; id?: string }; +type Args = {} extends Input ? [input?: Input] : [input: Input]; +type EventPaths = { + [K in keyof D & string]: K extends `GET ${infer P}` ? ([EventOf>] extends [never] ? never : P) : never; +}[keyof D & string]; +type Part = R extends { [P in K]: infer V } ? V : unknown; + +/** An event stream to follow: its key (path and input), and how to open it. */ +export type LiveEvents = { + readonly key: readonly unknown[]; + open(signal?: AbortSignal): AsyncIterable; +}; + +/** A WebSocket to open: its key (path and input), and how to open it. */ +export type LiveSocket = { + readonly key: readonly unknown[]; + open(): TypedSocket; +}; + +type Live =

>(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..7801d86 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,108 @@ 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" }); + }); + 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 +165,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..7f803af 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.7.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..53aeb4a 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,183 @@ 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): Promise { + return new Promise((resolve) => { + start((s) => { + if (check(s)) 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", async () => { + const server = await live.listen(0, "127.0.0.1"); + 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, + ); + 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 { + 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"); +}); From 8072a691fcb3dcae0bdf1313473b0c228099379c Mon Sep 17 00:00:00 2001 From: Vensin Date: Mon, 19 Oct 2026 14:12:11 +0200 Subject: [PATCH 2/7] feat(uws): WebSocket routes on uWS websockets (0.4.0) --- package-lock.json | 35 +-- packages/uws/CHANGELOG.md | 10 + packages/uws/README.md | 47 +++- packages/uws/index.d.ts | 5 +- packages/uws/index.js | 306 +++++++++++++++++++++++++- packages/uws/package.json | 6 +- packages/uws/test.ts | 4 +- packages/uws/websockets.ts | 434 +++++++++++++++++++++++++++++++++++++ 8 files changed, 816 insertions(+), 31 deletions(-) create mode 100644 packages/uws/websockets.ts diff --git a/package-lock.json b/package-lock.json index 1c1a92a..bbfb88c 100644 --- a/package-lock.json +++ b/package-lock.json @@ -17,6 +17,22 @@ "node": ">=22.18" } }, + "../inkan-release-0.8": { + "name": "@vxnsin/inkan", + "version": "0.8.0", + "dev": true, + "license": "MIT", + "bin": { + "inkan": "dist/cli.js" + }, + "devDependencies": { + "@types/node": "^26.6.4", + "typescript": "^7.0.2" + }, + "engines": { + "node": ">=22" + } + }, "node_modules/@inkanjs/next": { "resolved": "packages/next", "link": true @@ -1323,16 +1339,16 @@ }, "packages/uws": { "name": "@inkanjs/uws", - "version": "0.3.0", + "version": "0.4.0", "license": "MIT", "devDependencies": { - "@vxnsin/inkan": "^0.6.0" + "@vxnsin/inkan": "file:../../../inkan-release-0.8" }, "engines": { "node": ">=22.18" }, "peerDependencies": { - "@vxnsin/inkan": ">=0.4.0", + "@vxnsin/inkan": ">=0.8.0 <1.0.0", "uWebSockets.js": ">=20.71.0" }, "peerDependenciesMeta": { @@ -1342,17 +1358,8 @@ } }, "packages/uws/node_modules/@vxnsin/inkan": { - "version": "0.6.0", - "resolved": "https://registry.npmjs.org/@vxnsin/inkan/-/inkan-0.6.0.tgz", - "integrity": "sha512-FkZ/K8Faw0eDpLctF0Jbih183ZmHHGBjb8M4/BPsi3lfiMYlyTXxK5Sp3v1LHp6/drbHePYJOHBf0W5wMdGMGg==", - "dev": true, - "license": "MIT", - "bin": { - "inkan": "dist/cli.js" - }, - "engines": { - "node": ">=22" - } + "resolved": "../inkan-release-0.8", + "link": true }, "packages/vite": { "name": "@inkanjs/vite", diff --git a/packages/uws/CHANGELOG.md b/packages/uws/CHANGELOG.md index c73017c..71d9b86 100644 --- a/packages/uws/CHANGELOG.md +++ b/packages/uws/CHANGELOG.md @@ -1,5 +1,15 @@ # Changelog +## 0.4.0 (unreleased) + +- 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..072a77d 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": "file:../../../inkan-release-0.8" }, "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"]); + }); +} From c9afc8285a980cb5221f1990a091ea082b40da76 Mon Sep 17 00:00:00 2001 From: Vensin Date: Tue, 20 Oct 2026 08:59:15 +0200 Subject: [PATCH 3/7] chore: query 0.3.0 and uws 0.4.0 on inkan 0.8.0 --- package-lock.json | 31 ++++++++++++------------------- packages/query/CHANGELOG.md | 2 +- packages/uws/CHANGELOG.md | 2 +- packages/uws/package.json | 2 +- 4 files changed, 15 insertions(+), 22 deletions(-) diff --git a/package-lock.json b/package-lock.json index bbfb88c..5b961bb 100644 --- a/package-lock.json +++ b/package-lock.json @@ -17,22 +17,6 @@ "node": ">=22.18" } }, - "../inkan-release-0.8": { - "name": "@vxnsin/inkan", - "version": "0.8.0", - "dev": true, - "license": "MIT", - "bin": { - "inkan": "dist/cli.js" - }, - "devDependencies": { - "@types/node": "^26.6.4", - "typescript": "^7.0.2" - }, - "engines": { - "node": ">=22" - } - }, "node_modules/@inkanjs/next": { "resolved": "packages/next", "link": true @@ -1342,7 +1326,7 @@ "version": "0.4.0", "license": "MIT", "devDependencies": { - "@vxnsin/inkan": "file:../../../inkan-release-0.8" + "@vxnsin/inkan": "^0.8.0" }, "engines": { "node": ">=22.18" @@ -1358,8 +1342,17 @@ } }, "packages/uws/node_modules/@vxnsin/inkan": { - "resolved": "../inkan-release-0.8", - "link": true + "version": "0.8.0", + "resolved": "https://registry.npmjs.org/@vxnsin/inkan/-/inkan-0.8.0.tgz", + "integrity": "sha512-hwCyNL0VQcvTvWxjIVCT8QFaQ92fR0dXB7aca0AGXqdBzd7HpeirLg/o2QI16MIkHroxSGuPaerM/f3lO78zBA==", + "dev": true, + "license": "MIT", + "bin": { + "inkan": "dist/cli.js" + }, + "engines": { + "node": ">=22" + } }, "packages/vite": { "name": "@inkanjs/vite", diff --git a/packages/query/CHANGELOG.md b/packages/query/CHANGELOG.md index 7c59f87..ae56f12 100644 --- a/packages/query/CHANGELOG.md +++ b/packages/query/CHANGELOG.md @@ -1,6 +1,6 @@ # Changelog -## 0.3.0 (unreleased) +## 0.3.0 - `q.events(path, input)` and `q.ws(path, input)`: live sources for a route that answers with `t.events(...)` and for an `app.ws` route, typed from it. A path that is no stream diff --git a/packages/uws/CHANGELOG.md b/packages/uws/CHANGELOG.md index 71d9b86..3559c37 100644 --- a/packages/uws/CHANGELOG.md +++ b/packages/uws/CHANGELOG.md @@ -1,6 +1,6 @@ # Changelog -## 0.4.0 (unreleased) +## 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, diff --git a/packages/uws/package.json b/packages/uws/package.json index 072a77d..5ff32d0 100644 --- a/packages/uws/package.json +++ b/packages/uws/package.json @@ -38,7 +38,7 @@ } }, "devDependencies": { - "@vxnsin/inkan": "file:../../../inkan-release-0.8" + "@vxnsin/inkan": "^0.8.0" }, "keywords": [ "inkan", From c5a8876ded28f668647e31f0f54fc85fd194fa41 Mon Sep 17 00:00:00 2001 From: Vensin Date: Tue, 20 Oct 2026 09:18:52 +0200 Subject: [PATCH 4/7] test(query): close the socket through the app; a time limit instead of a hang --- packages/query/test.ts | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/packages/query/test.ts b/packages/query/test.ts index 53aeb4a..8224659 100644 --- a/packages/query/test.ts +++ b/packages/query/test.ts @@ -212,7 +212,7 @@ test("follow() stops when told to, and tells nothing after", async () => { 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", async () => { +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"); try { const { port } = server.address() as { port: number }; @@ -238,6 +238,9 @@ test("connect() opens a typed WebSocket, sends before it is open, closes", async ); 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)); } From 0eeb94ede3d4cdc3c03d26f130de99ad959e296f Mon Sep 17 00:00:00 2001 From: Vensin Date: Tue, 20 Oct 2026 09:36:41 +0200 Subject: [PATCH 5/7] test(query): run on inkan 0.8; say what was seen when a state never comes --- package-lock.json | 8 ++++---- packages/query/package.json | 2 +- packages/query/test.ts | 13 ++++++++++--- 3 files changed, 15 insertions(+), 8 deletions(-) diff --git a/package-lock.json b/package-lock.json index 5b961bb..9025d40 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1282,7 +1282,7 @@ "license": "MIT", "devDependencies": { "@tanstack/query-core": "^5.104.1", - "@vxnsin/inkan": "^0.7.0", + "@vxnsin/inkan": "^0.8.0", "react": "^19.3.0" }, "engines": { @@ -1299,9 +1299,9 @@ } }, "packages/query/node_modules/@vxnsin/inkan": { - "version": "0.7.0", - "resolved": "https://registry.npmjs.org/@vxnsin/inkan/-/inkan-0.7.0.tgz", - "integrity": "sha512-d9RavATzolWCk/WHy4ktZVHNT/obYwfllRHHuwUgmEAqYI6f/JoWl6TVPGQ9T8iHwc48pOB1+5opELAzIWzaSw==", + "version": "0.8.0", + "resolved": "https://registry.npmjs.org/@vxnsin/inkan/-/inkan-0.8.0.tgz", + "integrity": "sha512-hwCyNL0VQcvTvWxjIVCT8QFaQ92fR0dXB7aca0AGXqdBzd7HpeirLg/o2QI16MIkHroxSGuPaerM/f3lO78zBA==", "dev": true, "license": "MIT", "bin": { diff --git a/packages/query/package.json b/packages/query/package.json index 7f803af..a0bf364 100644 --- a/packages/query/package.json +++ b/packages/query/package.json @@ -53,7 +53,7 @@ }, "devDependencies": { "@tanstack/query-core": "^5.104.1", - "@vxnsin/inkan": "^0.7.0", + "@vxnsin/inkan": "^0.8.0", "react": "^19.3.0" }, "scripts": { diff --git a/packages/query/test.ts b/packages/query/test.ts index 8224659..93408c9 100644 --- a/packages/query/test.ts +++ b/packages/query/test.ts @@ -121,10 +121,17 @@ const live = inkan({ log: false }) 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): Promise { - return new Promise((resolve) => { +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) => { - if (check(s)) resolve(s); + seen.push(s); + if (check(s)) { + clearTimeout(timer); + resolve(s); + } }); }); } From c39ee5ce97063ebea10b16700bdb953500f1155a Mon Sep 17 00:00:00 2001 From: Vensin Date: Tue, 20 Oct 2026 09:38:40 +0200 Subject: [PATCH 6/7] test(query): tell what the server heard when the socket never opens --- packages/query/test.ts | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/packages/query/test.ts b/packages/query/test.ts index 93408c9..27f778e 100644 --- a/packages/query/test.ts +++ b/packages/query/test.ts @@ -221,6 +221,10 @@ 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}`)); @@ -234,7 +238,9 @@ test("connect() opens a typed WebSocket, sends before it is open, closes", { tim 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(); From c743647d9bf97cb02b89efabbe52ac405ff407f8 Mon Sep 17 00:00:00 2001 From: Vensin Date: Tue, 20 Oct 2026 09:40:32 +0200 Subject: [PATCH 7/7] fix(query): a socket that fails to open is an error even without a close event --- packages/query/index.js | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/packages/query/index.js b/packages/query/index.js index 7801d86..efb894b 100644 --- a/packages/query/index.js +++ b/packages/query/index.js @@ -135,6 +135,10 @@ export function connect(source, options = {}) { 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) {