@afora/ws 0.0.0-stage → 0.0.8

package/README.md

@@ -1,3 +1,169 @@
-# Temporary Holding Version
+# @afora/ws
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A WebSocket sink for [`@afora/core`](../../README.md) outputs. It serves the operations of an output over JSON messages, with the same validation, masked responses and RFC 9457 problems as the HTTP sink, and lets a connection subscribe to topics that [`publishEvents`](../../docs/commands.md#event-policies) fills with domain events. It depends on no runtime: the sink builds an endpoint, and a few lines of Bun, Hono or Workers feed it the messages of a socket.
+
+```bash
+bun add @afora/core @afora/ws typebox
+```
+
+`@afora/core` and TypeBox (`^1`) are peer dependencies. The package uses only web APIs, so it runs on Bun, Node >= 22 and Workers.
+
+## Example
+
+```ts
+// realtime.ts
+import { wsHub } from "@afora/ws";
+export const hub = wsHub();
+
+// app.ts
+import { applicationOf, commandOf, outputOf, publishEvents } from "@afora/core";
+import { websocket } from "@afora/ws";
+import { hub } from "./realtime";
+
+const Posts = commandOf({
+	name: "Posts",
+	useCases: { create: CreatePost, list: ListPosts },
+	events: publishEvents({ publisher: "realtime", topic: "posts" }),
+});
+
+const Live = outputOf({
+	name: "Live",
+	commands: [Posts],
+	pipe: [
+		websocket({
+			context: { userId: "x-user" },
+			subscriptions: { topics: ["posts", "posts/*"] },
+		}),
+	],
+});
+
+export const App = applicationOf({
+	name: "Blog",
+	commands: { Posts },
+	outputs: { Live },
+	publishers: { realtime: hub },
+	// ...entities, repositories, use cases
+});
+```
+
+```
+→ { "id": 1, "subscribe": "posts" }
+← { "id": 1, "subscribed": "posts" }
+
+→ { "id": 2, "op": "Posts.create", "input": { "title": "Hello" } }
+← { "id": 2, "value": { "post": { "id": "...", "title": "Hello", ... } } }
+← { "topic": "posts", "event": { "name": "postCreated", "command": "Posts", "operation": "create", "entity": { ... } } }
+
+→ { "id": 3, "op": "Posts.create", "input": {} }
+← { "id": 3, "problem": { "type": "urn:afora:exception:InvalidUseCaseInput", "status": 400, "issues": [...], ... } }
+```
+
+The push goes to every socket subscribed to the topic, including the one that made the call, after the call succeeded and committed.
+
+## Adapters
+
+Build the endpoint once (`App.outputs.Live.build()`), then give each socket a session. The session reads each message and sends the reply through `socket.send`; `close()` leaves its topics.
+
+**Bun**
+
+```ts
+const endpoint = App.outputs.Live.build();
+
+Bun.serve<{ values: Record<string, string | undefined>; session?: WsSession }>({
+	fetch(request, server) {
+		const values = { "x-user": request.headers.get("x-user") ?? undefined };
+		if (server.upgrade(request, { data: { values } })) return undefined;
+		return new Response("Upgrade required", { status: 426 });
+	},
+	websocket: {
+		open(ws) {
+			ws.data.session = endpoint.session(ws, { hub, values: ws.data.values });
+		},
+		message(ws, message) {
+			void ws.data.session?.message(message);
+		},
+		close(ws) {
+			ws.data.session?.close();
+		},
+	},
+});
+```
+
+**Hono** (`upgradeWebSocket` from `hono/bun` or `hono/cloudflare-workers`; on Node, `@hono/node-ws`)
+
+```ts
+app.get(
+	"/ws",
+	upgradeWebSocket((c) => {
+		let session: WsSession;
+		return {
+			onOpen: (_event, ws) => {
+				session = endpoint.session(ws, {
+					hub,
+					values: { "x-user": c.req.header("x-user") },
+				});
+			},
+			onMessage: (event) => session.message(event.data as string),
+			onClose: () => session.close(),
+		};
+	}),
+);
+```
+
+**Workers**
+
+```ts
+const [client, server] = Object.values(new WebSocketPair());
+server.accept();
+const session = endpoint.session(server, { hub, values });
+server.addEventListener("message", (event) => session.message(event.data));
+server.addEventListener("close", () => session.close());
+return new Response(null, { status: 101, webSocket: client });
+```
+
+`wsHub()` keeps its subscribers in memory, so it reaches the sockets of one process or isolate. To reach every instance, implement `WsHub` (`subscribe`, `unsubscribe`, `size`, `publish`) over a broker: Bun's `ws.subscribe` and `server.publish`, Redis, or a Durable Object that holds the sockets.
+
+## Options
+
+All options are JSON, so the stage can live in an `afora.json` (`{ "sink": "websocket", "options": { ... } }`).
+
+| Option            | Meaning                                                                                                                                               |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `include`         | Operation ids to serve (`"Posts.create"`); every operation when omitted. An id that is not an operation throws `InvalidOutputStage` on build.         |
+| `context`         | `{ [contextKey]: valueName }`: the context of an operation from the `values` of the session (headers of the upgrade, a token).                        |
+| `subscriptions`   | `{ topics: ["posts", "posts/*"] }`: the topics a session may subscribe to; `*` is one segment between `/`. Without it, every subscription is refused. |
+| `maxMessageBytes` | The largest message read, in bytes. 1 MiB by default.                                                                                                 |
+| `debug`           | `true` adds the `trace` to problems and the real `detail` to 5xx ones. Off by default.                                                                |
+
+Invalid options throw `InvalidOutputStage` when the stage is made.
+
+## Protocol
+
+| Client sends                    | Server answers                                                              |
+| ------------------------------- | --------------------------------------------------------------------------- |
+| `{ id?, op, input? }`           | `{ id, value }` or `{ id, problem }`                                        |
+| `{ id?, subscribe: topic }`     | `{ id, subscribed: topic }` or `{ id, problem }`                            |
+| `{ id?, unsubscribe: topic }`   | `{ id, unsubscribed: topic }`                                               |
+| (an event published to a topic) | `{ topic, event: { name, command, operation, entity } }` to its subscribers |
+
+- **Calls.** `op` is an operation id. The input is validated by the operation (a 400 problem with `issues`), the response goes through `outputValueOf` (sensitive values masked), and an error is `problemOf` with the status of `statusOf` and the output `statuses`. An unknown `op` is a 404 `NotFound` problem.
+- **`id`** is a non-empty string or a number, echoed in the reply; `null` when the request had none.
+- **Invalid messages.** Text that is not UTF-8 or JSON, a frame that is not an object, an unknown key, not exactly one of `op`, `subscribe` and `unsubscribe`, `input` without `op`, or a message over `maxMessageBytes`: a 400 problem `InvalidWsMessage`, whose `detail` says why.
+- **Subscriptions.** A topic must match `subscriptions.topics`, then `authorize(topic, values)` of the session, if given (ownership, roles): otherwise a 403 `WsTopicForbidden`. A session without a hub, or `handle`, answers a 501 `WsSubscriptionsUnavailable`. The output `statuses` can change these three statuses.
+- **Never throws.** `session.message` catches everything and answers a problem; a socket whose `send` throws is dropped by the hub.
+
+`endpoint.handle(message, { values })` answers one message with no connection (calls only), for tests or a transport that is not a socket. `endpoint.operations` lists the operations served with their input JSON Schema.
+
+## Security
+
+- Authenticate on the upgrade, then pass what you trust as `values`; the client never chooses its context.
+- Topics are private by default. Published entities are masked by `toJSON`, but the other fields reach every subscriber of a topic: scope topics (`posts/{id}`, `users/{userId}`) and check them in `authorize`.
+
+## Catalog
+
+`WsStages` is `stageCatalogOf(websocket)`, and `stages` are the entries codegen reads to resolve `{ "sink": "websocket" }` in an `afora.json` (`--stages @afora/ws`):
+
+```ts
+import { stages } from "@afora/ws";
+// [{ name: "websocket", module: "@afora/ws", export: "websocket", kind: "sink" }]
+```

package/dist/exceptions.d.ts

@@ -0,0 +1,10 @@
+/** A message that is not a frame of the protocol (400); `details.reason` says why. */
+export declare const InvalidWsMessage: import("@afora/core").DeclaredExceptionClass<{
+    readonly reason: string;
+}>;
+/** A subscription the topics of the options or `authorize` refuse (403). */
+export declare const WsTopicForbidden: import("@afora/core").DeclaredExceptionClass<{
+    readonly topic: string;
+}>;
+/** A subscription sent where there is no hub: `handle`, or a session without one (501). */
+export declare const WsSubscriptionsUnavailable: import("@afora/core").DeclaredExceptionClass<undefined>;

package/dist/hub.d.ts

@@ -0,0 +1,24 @@
+import type { IEventPublisher } from "@afora/core";
+/** What the sink sends messages through: a WebSocket of any runtime has `send`. */
+export interface WsSocket {
+    send(text: string): void;
+}
+/**
+ * Who is subscribed to which topic, and an `IEventPublisher`: declared under
+ * a key in `applicationOf({ publishers })`, the events `publishEvents` gives
+ * it reach the sockets subscribed to their topic.
+ */
+export interface WsHub extends IEventPublisher {
+    subscribe(topic: string, socket: WsSocket): void;
+    unsubscribe(topic: string, socket: WsSocket): void;
+    /** How many sockets are subscribed to `topic`. */
+    size(topic: string): number;
+}
+/**
+ * A hub in memory: it reaches the sockets of this process (or Workers
+ * isolate) only. `publish` sends `{ topic, event }` as JSON to each socket
+ * subscribed to the topic, and drops a socket whose `send` throws; it never
+ * throws itself. To reach the sockets of other instances, implement `WsHub`
+ * over a broker (Redis, a Durable Object, Bun's `server.publish`).
+ */
+export declare function wsHub(): WsHub;

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { InvalidWsMessage, WsSubscriptionsUnavailable, WsTopicForbidden, } from "./exceptions.js";
+export { type WsHub, type WsSocket, wsHub } from "./hub.js";
+export type { WsPush, WsReply, WsRequest, WsRequestId, } from "./protocol.js";
+export { stages, type WebSocketEndpoint, type WebSocketOptions, type WsOperation, type WsSession, type WsSessionOptions, WsStages, type WsValues, websocket, } from "./sink.js";

package/dist/index.js

@@ -0,0 +1,361 @@
+// src/exceptions.ts
+import { ExceptionLayers, exceptionOf } from "@afora/core";
+var InvalidWsMessage = exceptionOf({
+  layer: ExceptionLayers.Output,
+  name: "InvalidWsMessage",
+  message: ({ reason }) => reason
+});
+var WsTopicForbidden = exceptionOf({
+  layer: ExceptionLayers.Output,
+  name: "WsTopicForbidden",
+  message: ({ topic }) => `Subscribing to "${topic}" is not allowed.`
+});
+var WsSubscriptionsUnavailable = exceptionOf({
+  layer: ExceptionLayers.Output,
+  name: "WsSubscriptionsUnavailable",
+  message: "Subscriptions need a session with a hub."
+});
+// src/hub.ts
+function wsHub() {
+  const topics = new Map;
+  const drop = (socket) => {
+    for (const [topic, sockets] of topics) {
+      sockets.delete(socket);
+      if (sockets.size === 0)
+        topics.delete(topic);
+    }
+  };
+  return Object.freeze({
+    subscribe(topic, socket) {
+      let sockets = topics.get(topic);
+      if (!sockets) {
+        sockets = new Set;
+        topics.set(topic, sockets);
+      }
+      sockets.add(socket);
+    },
+    unsubscribe(topic, socket) {
+      const sockets = topics.get(topic);
+      if (!sockets)
+        return;
+      sockets.delete(socket);
+      if (sockets.size === 0)
+        topics.delete(topic);
+    },
+    size(topic) {
+      return topics.get(topic)?.size ?? 0;
+    },
+    publish(topic, event) {
+      const sockets = topics.get(topic);
+      if (!sockets)
+        return;
+      const text = JSON.stringify({ topic, event });
+      for (const socket of [...sockets]) {
+        try {
+          socket.send(text);
+        } catch {
+          drop(socket);
+        }
+      }
+    }
+  });
+}
+// src/sink.ts
+import {
+  coerceTextValues,
+  InvalidOutputStage,
+  outputValueOf,
+  problemOf,
+  sinkOf,
+  stageCatalogOf,
+  statusOf,
+  toOpenAPI
+} from "@afora/core";
+
+// src/protocol.ts
+var KEYS = ["id", "op", "input", "subscribe", "unsubscribe"];
+var VERBS = ["op", "subscribe", "unsubscribe"];
+var decoder = new TextDecoder("utf-8", { fatal: true });
+var encoder = new TextEncoder;
+function isId(value) {
+  return typeof value === "string" && value !== "" || typeof value === "number" && Number.isFinite(value);
+}
+function parseWsMessage(data, maxBytes) {
+  const fail = (reason, id = null) => ({
+    failure: { reason, id }
+  });
+  let frame = data;
+  if (typeof data === "string" || data instanceof ArrayBuffer || data instanceof Uint8Array) {
+    const size = typeof data === "string" ? encoder.encode(data).byteLength : data.byteLength;
+    if (size > maxBytes) {
+      return fail(`The message is larger than ${maxBytes} bytes.`);
+    }
+    let text;
+    try {
+      text = typeof data === "string" ? data : decoder.decode(data);
+    } catch {
+      return fail("The message is not valid UTF-8.");
+    }
+    try {
+      frame = JSON.parse(text);
+    } catch {
+      return fail("The message is not valid JSON.");
+    }
+  }
+  if (typeof frame !== "object" || frame === null || Array.isArray(frame)) {
+    return fail("The message must be a JSON object.");
+  }
+  const given = frame;
+  const id = isId(given.id) ? given.id : null;
+  if (given.id !== undefined && id === null) {
+    return fail('"id" must be a non-empty string or a number.');
+  }
+  const unknown = Object.keys(given).find((key) => !KEYS.includes(key));
+  if (unknown !== undefined) {
+    return fail(`The message has no key "${unknown}".`, id);
+  }
+  const verbs = VERBS.filter((verb) => Object.hasOwn(given, verb));
+  if (verbs.length !== 1) {
+    return fail('The message must have exactly one of "op", "subscribe" and "unsubscribe".', id);
+  }
+  const [verb] = verbs;
+  if (typeof given[verb] !== "string" || given[verb] === "") {
+    return fail(`"${verb}" must be a non-empty string.`, id);
+  }
+  if (verb !== "op" && given.input !== undefined) {
+    return fail(`"input" only goes with "op".`, id);
+  }
+  return { request: given };
+}
+
+// src/sink.ts
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function validate(options) {
+  const given = options;
+  for (const key of Object.keys(given)) {
+    if (![
+      "include",
+      "context",
+      "subscriptions",
+      "maxMessageBytes",
+      "debug"
+    ].includes(key)) {
+      return `websocket has no option "${key}".`;
+    }
+  }
+  const { include, context, subscriptions, maxMessageBytes, debug } = given;
+  if (include !== undefined && (!Array.isArray(include) || include.some((id) => typeof id !== "string" || id === ""))) {
+    return "Expected websocket.include to be a list of operation ids.";
+  }
+  if (context !== undefined) {
+    if (!isObject(context))
+      return "Expected websocket.context to be an object.";
+    for (const [key, name] of Object.entries(context)) {
+      if (typeof name !== "string" || name === "") {
+        return `Expected websocket.context["${key}"] to be a value name.`;
+      }
+    }
+  }
+  if (subscriptions !== undefined) {
+    if (!isObject(subscriptions) || Object.keys(subscriptions).some((key) => key !== "topics") || !Array.isArray(subscriptions.topics) || subscriptions.topics.some((topic) => typeof topic !== "string" || topic === "" || topic.split("/").some((segment) => segment === ""))) {
+      return 'Expected websocket.subscriptions to be { "topics": ["posts/*", ...] }, with no empty segment.';
+    }
+  }
+  if (maxMessageBytes !== undefined && (!Number.isInteger(maxMessageBytes) || maxMessageBytes < 1)) {
+    return "Expected websocket.maxMessageBytes to be a whole number of bytes, 1 or more.";
+  }
+  if (debug !== undefined && typeof debug !== "boolean") {
+    return "Expected websocket.debug to be a boolean.";
+  }
+  return;
+}
+function matches(pattern, topic) {
+  const wanted = pattern.split("/");
+  const given = topic.split("/");
+  return wanted.length === given.length && wanted.every((segment, index) => segment === given[index] || segment === "*" && given[index] !== "");
+}
+var websocket = sinkOf({
+  name: "websocket",
+  validate,
+  build: (operations, options, { output }) => {
+    const mapping = options.context ?? {};
+    const include = options.include;
+    const patterns = options.subscriptions?.topics ?? [];
+    const maxBytes = options.maxMessageBytes ?? 1048576;
+    const debug = options.debug === true;
+    if (include) {
+      const known = new Set(operations.map((operation) => operation.id));
+      const unknown = include.find((id) => !known.has(id));
+      if (unknown !== undefined) {
+        throw new InvalidOutputStage({
+          source: "websocket",
+          details: {
+            reason: `websocket.include names "${unknown}", which is not an operation.`
+          }
+        });
+      }
+    }
+    const served = new Map;
+    for (const operation of operations) {
+      if (!include || include.includes(operation.id)) {
+        served.set(operation.id, operation);
+      }
+    }
+    const problem = (error, fallback) => {
+      const status = Object.hasOwn(output.statuses, error.name) ? output.statuses[error.name] : fallback;
+      return problemOf(error, { status, debug });
+    };
+    const call = async (request, id, values) => {
+      const operation = served.get(request.op);
+      if (!operation) {
+        return {
+          id,
+          problem: {
+            type: "urn:afora:exception:NotFound",
+            title: "NotFound",
+            status: 404,
+            detail: `Unknown operation "${request.op}".`
+          }
+        };
+      }
+      const options_ = {};
+      if (operation.context) {
+        const raw = {};
+        for (const key of Object.keys(operation.context.properties)) {
+          const source = mapping[key];
+          raw[key] = source === undefined ? undefined : values[source];
+        }
+        options_.context = coerceTextValues(operation.context, raw);
+      }
+      try {
+        const response = await operation.invoke(request.input ?? {}, options_);
+        return { id, value: outputValueOf(response) ?? null };
+      } catch (error) {
+        const status = statusOf(error, operation, output.statuses);
+        return { id, problem: problemOf(error, { status, debug }) };
+      }
+    };
+    const read = (data) => {
+      const parsed = parseWsMessage(data, maxBytes);
+      if ("failure" in parsed) {
+        const { reason, id } = parsed.failure;
+        return {
+          reply: {
+            id,
+            problem: problem(new InvalidWsMessage({
+              source: "websocket",
+              details: { reason }
+            }), 400)
+          }
+        };
+      }
+      return { request: parsed.request, id: parsed.request.id ?? null };
+    };
+    const unavailable = (id) => ({
+      id,
+      problem: problem(new WsSubscriptionsUnavailable({ source: "websocket" }), 501)
+    });
+    const handle = async (message, extra) => {
+      try {
+        const read_ = read(message);
+        if ("reply" in read_)
+          return read_.reply;
+        const { request, id } = read_;
+        if ("op" in request)
+          return await call(request, id, extra?.values ?? {});
+        return unavailable(id);
+      } catch (error) {
+        return { id: null, problem: problemOf(error, { status: 500, debug }) };
+      }
+    };
+    const session = (socket, sessionOptions = {}) => {
+      const { hub, authorize } = sessionOptions;
+      const values = sessionOptions.values ?? {};
+      const topics = new Set;
+      let closed = false;
+      const send = (reply) => {
+        try {
+          socket.send(JSON.stringify(reply));
+        } catch {}
+      };
+      const subscribe = async (topic, id) => {
+        if (!hub)
+          return unavailable(id);
+        const allowed = patterns.some((pattern) => matches(pattern, topic)) && (authorize ? await authorize(topic, values) : true);
+        if (!allowed) {
+          return {
+            id,
+            problem: problem(new WsTopicForbidden({ source: "websocket", details: { topic } }), 403)
+          };
+        }
+        if (closed)
+          return { id, subscribed: topic };
+        hub.subscribe(topic, socket);
+        topics.add(topic);
+        return { id, subscribed: topic };
+      };
+      return {
+        async message(data) {
+          if (closed)
+            return;
+          try {
+            const read_ = read(data);
+            if ("reply" in read_)
+              return send(read_.reply);
+            const { request, id } = read_;
+            if ("op" in request)
+              return send(await call(request, id, values));
+            if ("subscribe" in request) {
+              return send(await subscribe(request.subscribe, id));
+            }
+            if (!hub)
+              return send(unavailable(id));
+            hub.unsubscribe(request.unsubscribe, socket);
+            topics.delete(request.unsubscribe);
+            return send({ id, unsubscribed: request.unsubscribe });
+          } catch (error) {
+            send({
+              id: null,
+              problem: problemOf(error, { status: 500, debug })
+            });
+          }
+        },
+        close() {
+          if (closed)
+            return;
+          closed = true;
+          for (const topic of topics)
+            hub?.unsubscribe(topic, socket);
+          topics.clear();
+        },
+        get topics() {
+          return [...topics];
+        }
+      };
+    };
+    return {
+      operations: [...served.values()].map((operation) => Object.freeze({
+        id: operation.id,
+        ...operation.description ? { description: operation.description } : {},
+        inputSchema: toOpenAPI(operation.input)
+      })),
+      handle,
+      session
+    };
+  }
+});
+var WsStages = stageCatalogOf(websocket);
+var stages = [
+  { name: "websocket", module: "@afora/ws", export: "websocket", kind: "sink" }
+];
+export {
+  InvalidWsMessage,
+  WsStages,
+  WsSubscriptionsUnavailable,
+  WsTopicForbidden,
+  stages,
+  websocket,
+  wsHub
+};

package/dist/protocol.d.ts

@@ -0,0 +1,50 @@
+import type { Problem, PublishedEvent } from "@afora/core";
+/** The id a client gives a request, echoed in the reply. */
+export type WsRequestId = string | number;
+/** What a client sends: a call of an operation, or a (un)subscription to a topic. */
+export type WsRequest = {
+    readonly id?: WsRequestId;
+    /** The operation id: `"Posts.create"`. */
+    readonly op: string;
+    readonly input?: unknown;
+} | {
+    readonly id?: WsRequestId;
+    readonly subscribe: string;
+} | {
+    readonly id?: WsRequestId;
+    readonly unsubscribe: string;
+};
+/** What the server answers to one request; `id` is the request's, or `null` without one. */
+export type WsReply = {
+    readonly id: WsRequestId | null;
+    readonly value: unknown;
+} | {
+    readonly id: WsRequestId | null;
+    readonly problem: Problem;
+} | {
+    readonly id: WsRequestId | null;
+    readonly subscribed: string;
+} | {
+    readonly id: WsRequestId | null;
+    readonly unsubscribed: string;
+};
+/** What the server sends to the subscribers of a topic when an event is published. */
+export interface WsPush {
+    readonly topic: string;
+    readonly event: PublishedEvent;
+}
+/** A frame that cannot be read: why, and the id when the frame had a readable one. */
+export interface WsMessageFailure {
+    readonly reason: string;
+    readonly id: WsRequestId | null;
+}
+/**
+ * `data` read as a request: text (or UTF-8 bytes) of a JSON object with an
+ * optional `id` and exactly one of `op`, `subscribe` and `unsubscribe`, or
+ * already such an object. Never throws.
+ */
+export declare function parseWsMessage(data: string | ArrayBuffer | Uint8Array | object, maxBytes: number): {
+    readonly request: WsRequest;
+} | {
+    readonly failure: WsMessageFailure;
+};

package/dist/sink.d.ts

@@ -0,0 +1,100 @@
+import type { WsHub, WsSocket } from "./hub.js";
+import { type WsReply } from "./protocol.js";
+/** The options of the `websocket` sink. JSON, so the stage can live in an `afora.json`. */
+export interface WebSocketOptions {
+    /** Operation ids to serve (`"Posts.create"`); every operation when omitted. */
+    readonly include?: readonly string[];
+    /**
+     * The context of an operation, by key: `{ token: "authorization" }` fills
+     * `context.token` from the value named `authorization` of the session (or
+     * of `handle`). A missing value leaves the key out.
+     */
+    readonly context?: {
+        readonly [contextKey: string]: string;
+    };
+    /**
+     * The topics a session may subscribe to: names or patterns where `*` is
+     * one segment between `/` (`"posts/*"`). Without it, every subscription
+     * is refused.
+     */
+    readonly subscriptions?: {
+        readonly topics: readonly string[];
+    };
+    /** The largest message read, in bytes. 1 MiB by default. */
+    readonly maxMessageBytes?: number;
+    /** Adds the `trace` to problems and the real `detail` to 5xx ones. Off by default. */
+    readonly debug?: boolean;
+}
+/** Text values the context is read from: headers of the upgrade, a token, a user id. */
+export type WsValues = Readonly<Record<string, string | undefined>>;
+/** What a session is opened with. */
+export interface WsSessionOptions {
+    /** The values the `context` option reads, e.g. from the headers of the upgrade request. */
+    readonly values?: WsValues;
+    /** Where subscriptions go; without it, a subscription is a 501 problem. */
+    readonly hub?: WsHub;
+    /**
+     * A check after the topics of the options, such as ownership: a topic it
+     * refuses is a 403 problem. All topics the options allow by default.
+     */
+    readonly authorize?: (topic: string, values: WsValues) => boolean | Promise<boolean>;
+}
+/** One connection: what to do with each message, and when it closes. */
+export interface WsSession {
+    /** Reads a message and sends the reply to the socket; never throws. */
+    message(data: string | ArrayBuffer | Uint8Array): Promise<void>;
+    /** Leaves every topic; later messages are ignored. */
+    close(): void;
+    /** The topics the session is subscribed to. */
+    readonly topics: readonly string[];
+}
+/** One operation the endpoint serves. */
+export interface WsOperation {
+    /** The operation id, what `op` names. */
+    readonly id: string;
+    readonly description?: string;
+    /** JSON Schema of the input. */
+    readonly inputSchema: Readonly<Record<string, unknown>>;
+}
+/** What the `websocket` sink builds. */
+export interface WebSocketEndpoint {
+    readonly operations: readonly WsOperation[];
+    /**
+     * The reply to one message, with no connection: a call of an operation.
+     * A subscription is a 501 problem here. Never throws.
+     */
+    handle(message: string | ArrayBuffer | Uint8Array | object, extra?: {
+        readonly values?: WsValues;
+    }): Promise<WsReply>;
+    /** A session for one socket, with subscriptions when given a hub. */
+    session(socket: WsSocket, options?: WsSessionOptions): WsSession;
+}
+/**
+ * Serves the operations over WebSocket messages, on any runtime: the sink
+ * builds an endpoint, and a few lines of the runtime's WebSocket feed it
+ * (see the README for Bun, Hono and Workers).
+ *
+ * - A request is `{ id?, op, input? }`, with `op` an operation id. The reply
+ *   is `{ id, value }` (`outputValueOf`: sensitive values masked) or
+ *   `{ id, problem }`, the `problemOf` of the error with the status of
+ *   `statusOf` (the output `statuses` first); invalid input is a 400 with
+ *   `issues`, an unknown `op` a 404, a message that is not a frame a 400
+ *   `InvalidWsMessage`. `id` is the request's, or `null`.
+ * - The context comes from the values of the session through the `context`
+ *   option; richer rules, such as authentication, are a `transform` stage.
+ * - In a session with a hub, `{ id?, subscribe: topic }` subscribes the
+ *   socket (`{ id, subscribed }`) when `subscriptions.topics` and
+ *   `authorize` allow it (a 403 `WsTopicForbidden` otherwise), and
+ *   `{ id?, unsubscribe }` leaves the topic. The hub then sends
+ *   `{ topic, event }` for each event published to the topic.
+ */
+export declare const websocket: import("@afora/core").SinkFactory<WebSocketEndpoint, WebSocketOptions>;
+/** The runtime catalog of this package: the stage name `websocket` resolves to the sink. */
+export declare const WsStages: import("@afora/core").IStageCatalog<Readonly<Record<string, import("@afora/core").StageFactory>>>;
+/** The catalog entries codegen reads (`--stages @afora/ws`): `{ name, module, export, kind }`. */
+export declare const stages: readonly [{
+    readonly name: "websocket";
+    readonly module: "@afora/ws";
+    readonly export: "websocket";
+    readonly kind: "sink";
+}];

package/package.json

@@ -1,6 +1,56 @@
 {
-  "name": "@afora/ws",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@afora/ws",
+	"version": "0.0.8",
+	"description": "A WebSocket sink for afora outputs: operations over a JSON protocol, problem+json errors, masked values and topic subscriptions fed by domain events.",
+	"keywords": [
+		"afora",
+		"websocket",
+		"realtime",
+		"events",
+		"pubsub"
+	],
+	"author": "Alan Reis <alanreisanjo@gmail.com> (https://github.com/Hoyasumii)",
+	"license": "MIT",
+	"homepage": "https://github.com/afora-framework/core/tree/main/packages/ws#readme",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/afora-framework/core.git",
+		"directory": "packages/ws"
+	},
+	"type": "module",
+	"main": "./dist/index.js",
+	"module": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"default": "./dist/index.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"files": [
+		"dist"
+	],
+	"engines": {
+		"bun": ">=1.4.4",
+		"node": ">=22"
+	},
+	"publishConfig": {
+		"access": "public",
+		"provenance": true
+	},
+	"scripts": {
+		"typecheck": "bun check",
+		"build": "rm -rf dist && bun build ./src/index.ts --outdir ./dist --target node --format esm --packages external --tsconfig-override tsconfig.build.json && tsc -p tsconfig.build.json && bun ../../scripts/add-dts-extensions.ts dist",
+		"test": "bun test"
+	},
+	"devDependencies": {
+		"@types/bun": "^1.4.4",
+		"typebox": "^1.4.3"
+	},
+	"peerDependencies": {
+		"@afora/core": ">=0.0.8",
+		"typebox": "^1"
+	}
+}