@shadow-js/realtime 0.0.0-stage → 1.0.0

package/dist/dev/server/http.js

@@ -0,0 +1,286 @@
+import { RealtimeError } from "../errors.js";
+import { byteLength } from "../protocol.js";
+import { TokenBucket } from "./limits.js";
+//#region src/server/http.ts
+const KEY = "$realtime";
+const MAX_FRAMES_PER_POST = 64;
+const MAX_SUBSCRIPTIONS_IN_QUERY = 64;
+const MAX_BUCKETS = 1e4;
+function refuse(status, code, message) {
+	return new Response(JSON.stringify({ error: {
+		code,
+		message
+	} }), {
+		status,
+		headers: {
+			"content-type": "application/json",
+			"cache-control": "no-store"
+		}
+	});
+}
+/** Whether the request's `Origin` header is acceptable. A missing header is allowed (see `HubRouteOptions.allowedOrigins`). */
+function originAllowed(request, allowed) {
+	const origin = request.headers.get("origin");
+	if (origin === null) return true;
+	if (allowed !== void 0) return allowed.includes(origin);
+	try {
+		return origin === new URL(request.url).origin;
+	} catch {
+		return false;
+	}
+}
+async function identify(options, event) {
+	const result = await options.authenticate?.(event);
+	if (result instanceof Response) return { refusal: result };
+	return { identity: result ?? {} };
+}
+/**
+* The WebSocket route of a hub: `export const WS = hub.websocket({ authenticate })` in a Dusk stream file. The upgrade is decided
+* by `authenticate` (a `Response` refuses it) and Dusk's own checks (origin, caps, size); each text frame goes to the hub.
+* Binary frames close the connection with 1003.
+*
+* @param hub The hub.
+* @param options How to identify the connection.
+* @returns Handlers shaped like Dusk's `WS` export.
+* @example
+* import { createHub } from "@shadow-js/realtime/server";
+*
+* const hub = createHub({ channels: { "chat:{room}": { subscribe: true, publish: true } } });
+* export const WS = hub.websocket();
+* @since 1.0.0
+*/
+function websocketRoute(hub, options = {}) {
+	return {
+		async upgrade(event) {
+			const result = await identify(options, event);
+			return "refusal" in result ? result.refusal : void 0;
+		},
+		async open(ws, event) {
+			const result = await identify(options, event);
+			if ("refusal" in result) {
+				ws.close(1008, "unauthorized");
+				return;
+			}
+			const transport = {
+				send: (frame) => ws.send(frame),
+				close: (code, reason) => ws.close(code, reason)
+			};
+			ws.data[KEY] = hub.connect(transport, result.identity);
+		},
+		message(ws, message) {
+			const connection = ws.data[KEY];
+			if (connection === void 0) return;
+			if (typeof message !== "string") {
+				ws.close(1003, "binary frames are not supported");
+				return;
+			}
+			connection.receive(message);
+		},
+		close(ws) {
+			ws.data[KEY]?.closed();
+		},
+		error(ws, error) {
+			hub.report(error, { where: "websocket" });
+			ws.data[KEY]?.closed();
+		}
+	};
+}
+/**
+* Refuses a stream that has already started (the status 200 is sent before the handler runs): a `bye` with the policy code the
+* client treats as fatal, so it gives up instead of reconnecting for ever, then the end of the stream.
+*/
+async function refuseStream(stream, why) {
+	try {
+		await stream.send({
+			event: "rt",
+			data: JSON.stringify({
+				t: "bye",
+				code: 1008,
+				why
+			})
+		});
+	} catch {}
+	stream.close();
+}
+/** Reads the subscriptions a stream request declares: `?s=[{"c":"chat:lobby","after":12}]`. */
+function declared(url) {
+	const text = url.searchParams.get("s");
+	if (text === null) return [];
+	try {
+		const value = JSON.parse(text);
+		if (!Array.isArray(value) || value.length > MAX_SUBSCRIPTIONS_IN_QUERY) return void 0;
+		return value.map((item) => item !== null && typeof item === "object" ? item : {});
+	} catch {
+		return;
+	}
+}
+/**
+* The server-sent events route of a hub, for hosts that cannot hold a WebSocket: `export const SSE = hub.sse()`. The channels
+* are declared in the request (`?s=[{"c":"chat:lobby","after":12,"echo":false,"presence":{"typing":false}}]`); to change them the
+* client opens a new stream. Frames go out as events named `rt`; everything the client sends goes to {@link postRoute}.
+*
+* @param hub The hub.
+* @param options How to identify the connection and which origins may connect.
+* @returns A handler shaped like Dusk's `SSE` export.
+* @example
+* import { createHub } from "@shadow-js/realtime/server";
+*
+* const hub = createHub({ channels: { "chat:{room}": { subscribe: true, publish: true } } });
+* export const SSE = hub.sse();
+* @since 1.0.0
+*/
+function sseRoute(hub, options = {}) {
+	return async (event, stream) => {
+		if (!originAllowed(event.request, options.allowedOrigins)) {
+			hub.report(new RealtimeError("forbidden", "origin refused"), { where: "sse.origin" });
+			await refuseStream(stream, "origin not allowed");
+			return;
+		}
+		const result = await identify(options, event);
+		if ("refusal" in result) {
+			await refuseStream(stream, "unauthorized");
+			return;
+		}
+		const entries = declared(new URL(event.request.url));
+		if (entries === void 0) {
+			await refuseStream(stream, "bad subscription list");
+			return;
+		}
+		let pendingBytes = 0;
+		const connection = hub.connect({
+			send(frame) {
+				if (stream.closed) return false;
+				pendingBytes += frame.length;
+				stream.send({
+					event: "rt",
+					data: frame
+				}).then(() => {
+					pendingBytes -= frame.length;
+				}, () => {
+					pendingBytes = Number.MAX_SAFE_INTEGER;
+					connection.closed();
+				});
+				return true;
+			},
+			close: () => stream.close(),
+			buffered: () => pendingBytes
+		}, result.identity);
+		entries.forEach((entry, at) => {
+			connection.receive(JSON.stringify({
+				t: "sub",
+				n: at + 1,
+				...entry
+			}));
+		});
+		if (!stream.signal.aborted) await new Promise((resolve) => {
+			stream.signal.addEventListener("abort", () => resolve(), { once: true });
+		});
+		connection.closed();
+		await connection.done;
+	};
+}
+/**
+* The HTTP route that carries what an SSE client sends: `export const POST = hub.post()`. The body is
+* `{"cid": "<connection id>", "frames": [ ... ]}` (at most 64 frames of the types `pub`, `req`, `pres`); the answer is
+* `{"frames": [ ... ]}` with the acks, replies and errors. It keeps nothing between requests, so any server can answer it.
+*
+* The request rate of one caller is limited by `key` (default: the user, else all anonymous callers together) with the hub's
+* publish limits; put Dusk's rate limiting in front of the route for per-address limits.
+*
+* @param hub The hub.
+* @param options Identity, origins and the rate-limit key.
+* @returns A handler for a Dusk API route.
+* @example
+* import { createHub } from "@shadow-js/realtime/server";
+*
+* const hub = createHub({ channels: { "chat:{room}": { subscribe: true, publish: true } } });
+* export const POST = hub.post();
+* @since 1.0.0
+*/
+function postRoute(hub, options = {}) {
+	const buckets = /* @__PURE__ */ new Map();
+	const bucketFor = (key) => {
+		let bucket = buckets.get(key);
+		if (bucket === void 0) {
+			if (buckets.size >= MAX_BUCKETS) {
+				const oldest = buckets.keys().next().value;
+				if (oldest !== void 0) buckets.delete(oldest);
+			}
+			bucket = new TokenBucket(hub.limits.publishesPerSecond, hub.limits.publishBurst, Date.now());
+			buckets.set(key, bucket);
+		}
+		return bucket;
+	};
+	return async (event) => {
+		const { request } = event;
+		if (!originAllowed(request, options.allowedOrigins)) return refuse(403, "forbidden", "origin not allowed");
+		const result = await identify(options, event);
+		if ("refusal" in result) return result.refusal;
+		const text = await request.text();
+		if (byteLength(text) > hub.limits.maxMessageBytes * 8) return refuse(413, "too_large", "the request is too large");
+		let body;
+		try {
+			body = JSON.parse(text);
+		} catch {
+			return refuse(400, "bad_frame", "the body is not JSON");
+		}
+		const frames = body?.frames;
+		const cid = body?.cid;
+		if (!Array.isArray(frames) || frames.length === 0 || frames.length > MAX_FRAMES_PER_POST) return refuse(400, "bad_frame", `frames must hold 1..${MAX_FRAMES_PER_POST} frames`);
+		const key = options.key?.(event, result.identity) ?? result.identity.user ?? "anonymous";
+		const answers = [];
+		const connection = hub.connect({
+			send(frame) {
+				if (!frame.startsWith("{\"t\":\"ready\"")) answers.push(frame);
+				return true;
+			},
+			close: () => void 0
+		}, result.identity, {
+			stateless: true,
+			publishBucket: bucketFor(key),
+			...typeof cid === "string" ? { actingFor: cid } : {}
+		});
+		try {
+			for (const frame of frames) {
+				const type = frame?.t;
+				if (type === "pres") {
+					const item = frame;
+					try {
+						if (typeof item.c !== "string" || typeof cid !== "string") throw new RealtimeError("bad_frame", "pres needs c and the connection id");
+						await hub.setMemberState(result.identity, item.c, cid, item.s ?? null);
+					} catch (error) {
+						const code = error instanceof RealtimeError ? error.code : "unavailable";
+						answers.push(JSON.stringify({
+							t: "err",
+							code
+						}));
+					}
+					continue;
+				}
+				if (type !== "pub" && type !== "req") {
+					answers.push(JSON.stringify({
+						t: "err",
+						code: "bad_frame",
+						msg: "only pub, req and pres"
+					}));
+					continue;
+				}
+				connection.receive(JSON.stringify(frame));
+			}
+			await connection.settled();
+		} finally {
+			connection.closed();
+		}
+		return new Response(`{"frames":[${answers.join(",")}]}`, {
+			status: 200,
+			headers: {
+				"content-type": "application/json",
+				"cache-control": "no-store"
+			}
+		});
+	};
+}
+//#endregion
+export { postRoute, sseRoute, websocketRoute };
+
+//# sourceMappingURL=http.js.map

package/dist/dev/server/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","names":[],"sources":["../../../src/server/http.ts"],"sourcesContent":["import { RealtimeError } from \"../errors\";\nimport { byteLength, type Json } from \"../protocol\";\nimport type { HubConnection, HubCore, Transport } from \"./hub\";\nimport { TokenBucket } from \"./limits\";\nimport type { Identity } from \"./rules\";\n\n/** What a hub needs from the framework's request event. @since 1.0.0 */\nexport interface RequestLike {\n  readonly request: Request;\n}\n\n/** How a connection is identified: an identity, or a response that refuses it. @since 1.0.0 */\nexport type AuthenticateResult = Identity | undefined | Response;\n\n/** Options shared by the transport routes. @since 1.0.0 */\nexport interface HubRouteOptions<E extends RequestLike> {\n  /**\n   * Reads the identity from the request (the session cookie, a bearer token). Return a `Response` to refuse (a 401). Return\n   * nothing for an anonymous connection. Default: everyone is anonymous, and channel rules decide.\n   */\n  readonly authenticate?: (event: E) => AuthenticateResult | Promise<AuthenticateResult>;\n  /**\n   * Origins allowed to open a stream or post (full origins such as `https://app.example.com`). Default: the request's own\n   * origin only. A request with no `Origin` header (same-origin GET, a non-browser client) is allowed.\n   */\n  readonly allowedOrigins?: readonly string[];\n}\n\n/** The WebSocket connection the framework hands to handlers (the part this package uses). @since 1.0.0 */\nexport interface WebSocketLike {\n  readonly data: Record<string, unknown>;\n  readonly signal: AbortSignal;\n  send(message: string | Uint8Array): boolean;\n  close(code?: number, reason?: string): void;\n}\n\n/** The handlers of a WebSocket route, shaped like Dusk's `WS` export. @since 1.0.0 */\nexport interface WebSocketRoute<E extends RequestLike> {\n  upgrade(event: E): Promise<Response | undefined>;\n  open(ws: WebSocketLike, event: E): Promise<void>;\n  message(ws: WebSocketLike, message: string | Uint8Array, event: E): void;\n  close(ws: WebSocketLike): void;\n  error(ws: WebSocketLike, error: unknown, event: E): void;\n}\n\n/** The stream a server-sent events route writes to (the part this package uses). @since 1.0.0 */\nexport interface SseLike {\n  send(message: { readonly event: string; readonly data: string }): Promise<void>;\n  close(): void;\n  readonly signal: AbortSignal;\n  readonly closed: boolean;\n}\n\nconst KEY = \"$realtime\";\nconst MAX_FRAMES_PER_POST = 64;\nconst MAX_SUBSCRIPTIONS_IN_QUERY = 64;\nconst MAX_BUCKETS = 10_000;\n\nfunction refuse(status: number, code: RealtimeError[\"code\"], message: string): Response {\n  return new Response(JSON.stringify({ error: { code, message } }), {\n    status,\n    headers: { \"content-type\": \"application/json\", \"cache-control\": \"no-store\" },\n  });\n}\n\n/** Whether the request's `Origin` header is acceptable. A missing header is allowed (see `HubRouteOptions.allowedOrigins`). */\nfunction originAllowed(request: Request, allowed: readonly string[] | undefined): boolean {\n  const origin = request.headers.get(\"origin\");\n  if (origin === null) return true;\n  if (allowed !== undefined) return allowed.includes(origin);\n  try {\n    return origin === new URL(request.url).origin;\n  } catch {\n    return false;\n  }\n}\n\nasync function identify<E extends RequestLike>(\n  options: HubRouteOptions<E>,\n  event: E,\n): Promise<{ readonly identity: Identity } | { readonly refusal: Response }> {\n  const result = await options.authenticate?.(event);\n  if (result instanceof Response) return { refusal: result };\n  return { identity: result ?? {} };\n}\n\n/**\n * The WebSocket route of a hub: `export const WS = hub.websocket({ authenticate })` in a Dusk stream file. The upgrade is decided\n * by `authenticate` (a `Response` refuses it) and Dusk's own checks (origin, caps, size); each text frame goes to the hub.\n * Binary frames close the connection with 1003.\n *\n * @param hub The hub.\n * @param options How to identify the connection.\n * @returns Handlers shaped like Dusk's `WS` export.\n * @example\n * import { createHub } from \"@shadow-js/realtime/server\";\n *\n * const hub = createHub({ channels: { \"chat:{room}\": { subscribe: true, publish: true } } });\n * export const WS = hub.websocket();\n * @since 1.0.0\n */\nexport function websocketRoute<E extends RequestLike>(\n  hub: HubCore,\n  options: Pick<HubRouteOptions<E>, \"authenticate\"> = {},\n): WebSocketRoute<E> {\n  return {\n    async upgrade(event) {\n      const result = await identify(options, event);\n      return \"refusal\" in result ? result.refusal : undefined;\n    },\n    async open(ws, event) {\n      const result = await identify(options, event);\n      if (\"refusal\" in result) {\n        ws.close(1008, \"unauthorized\");\n        return;\n      }\n      const transport: Transport = {\n        send: (frame) => ws.send(frame),\n        close: (code, reason) => ws.close(code, reason),\n      };\n      ws.data[KEY] = hub.connect(transport, result.identity);\n    },\n    message(ws, message) {\n      const connection = ws.data[KEY] as HubConnection | undefined;\n      if (connection === undefined) return;\n      if (typeof message !== \"string\") {\n        ws.close(1003, \"binary frames are not supported\");\n        return;\n      }\n      connection.receive(message);\n    },\n    close(ws) {\n      (ws.data[KEY] as HubConnection | undefined)?.closed();\n    },\n    error(ws, error) {\n      hub.report(error, { where: \"websocket\" });\n      (ws.data[KEY] as HubConnection | undefined)?.closed();\n    },\n  };\n}\n\n/**\n * Refuses a stream that has already started (the status 200 is sent before the handler runs): a `bye` with the policy code the\n * client treats as fatal, so it gives up instead of reconnecting for ever, then the end of the stream.\n */\nasync function refuseStream(stream: SseLike, why: string): Promise<void> {\n  try {\n    await stream.send({ event: \"rt\", data: JSON.stringify({ t: \"bye\", code: 1008, why }) });\n  } catch {\n    // A client that already left needs no answer.\n  }\n  stream.close();\n}\n\n/** Reads the subscriptions a stream request declares: `?s=[{\"c\":\"chat:lobby\",\"after\":12}]`. */\nfunction declared(url: URL): readonly Record<string, unknown>[] | undefined {\n  const text = url.searchParams.get(\"s\");\n  if (text === null) return [];\n  try {\n    const value: unknown = JSON.parse(text);\n    if (!Array.isArray(value) || value.length > MAX_SUBSCRIPTIONS_IN_QUERY) return undefined;\n    return value.map((item) =>\n      item !== null && typeof item === \"object\" ? (item as Record<string, unknown>) : {},\n    );\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * The server-sent events route of a hub, for hosts that cannot hold a WebSocket: `export const SSE = hub.sse()`. The channels\n * are declared in the request (`?s=[{\"c\":\"chat:lobby\",\"after\":12,\"echo\":false,\"presence\":{\"typing\":false}}]`); to change them the\n * client opens a new stream. Frames go out as events named `rt`; everything the client sends goes to {@link postRoute}.\n *\n * @param hub The hub.\n * @param options How to identify the connection and which origins may connect.\n * @returns A handler shaped like Dusk's `SSE` export.\n * @example\n * import { createHub } from \"@shadow-js/realtime/server\";\n *\n * const hub = createHub({ channels: { \"chat:{room}\": { subscribe: true, publish: true } } });\n * export const SSE = hub.sse();\n * @since 1.0.0\n */\nexport function sseRoute<E extends RequestLike>(\n  hub: HubCore,\n  options: HubRouteOptions<E> = {},\n): (event: E, stream: SseLike) => Promise<void> {\n  return async (event, stream) => {\n    if (!originAllowed(event.request, options.allowedOrigins)) {\n      hub.report(new RealtimeError(\"forbidden\", \"origin refused\"), { where: \"sse.origin\" });\n      await refuseStream(stream, \"origin not allowed\");\n      return;\n    }\n    const result = await identify(options, event);\n    if (\"refusal\" in result) {\n      await refuseStream(stream, \"unauthorized\");\n      return;\n    }\n    const entries = declared(new URL(event.request.url));\n    if (entries === undefined) {\n      await refuseStream(stream, \"bad subscription list\");\n      return;\n    }\n    let pendingBytes = 0;\n    const transport: Transport = {\n      send(frame) {\n        if (stream.closed) return false;\n        pendingBytes += frame.length;\n        stream.send({ event: \"rt\", data: frame }).then(\n          () => {\n            pendingBytes -= frame.length;\n          },\n          () => {\n            pendingBytes = Number.MAX_SAFE_INTEGER;\n            connection.closed();\n          },\n        );\n        return true;\n      },\n      close: () => stream.close(),\n      buffered: () => pendingBytes,\n    };\n    const connection = hub.connect(transport, result.identity);\n    entries.forEach((entry, at) => {\n      connection.receive(JSON.stringify({ t: \"sub\", n: at + 1, ...entry }));\n    });\n    if (!stream.signal.aborted)\n      await new Promise<void>((resolve) => {\n        stream.signal.addEventListener(\"abort\", () => resolve(), { once: true });\n      });\n    connection.closed();\n    await connection.done;\n  };\n}\n\n/**\n * The HTTP route that carries what an SSE client sends: `export const POST = hub.post()`. The body is\n * `{\"cid\": \"<connection id>\", \"frames\": [ ... ]}` (at most 64 frames of the types `pub`, `req`, `pres`); the answer is\n * `{\"frames\": [ ... ]}` with the acks, replies and errors. It keeps nothing between requests, so any server can answer it.\n *\n * The request rate of one caller is limited by `key` (default: the user, else all anonymous callers together) with the hub's\n * publish limits; put Dusk's rate limiting in front of the route for per-address limits.\n *\n * @param hub The hub.\n * @param options Identity, origins and the rate-limit key.\n * @returns A handler for a Dusk API route.\n * @example\n * import { createHub } from \"@shadow-js/realtime/server\";\n *\n * const hub = createHub({ channels: { \"chat:{room}\": { subscribe: true, publish: true } } });\n * export const POST = hub.post();\n * @since 1.0.0\n */\nexport function postRoute<E extends RequestLike>(\n  hub: HubCore,\n  options: HubRouteOptions<E> & { readonly key?: (event: E, identity: Identity) => string } = {},\n): (event: E) => Promise<Response> {\n  const buckets = new Map<string, TokenBucket>();\n  const bucketFor = (key: string): TokenBucket => {\n    let bucket = buckets.get(key);\n    if (bucket === undefined) {\n      if (buckets.size >= MAX_BUCKETS) {\n        const oldest = buckets.keys().next().value;\n        if (oldest !== undefined) buckets.delete(oldest);\n      }\n      bucket = new TokenBucket(hub.limits.publishesPerSecond, hub.limits.publishBurst, Date.now());\n      buckets.set(key, bucket);\n    }\n    return bucket;\n  };\n  return async (event) => {\n    const { request } = event;\n    if (!originAllowed(request, options.allowedOrigins))\n      return refuse(403, \"forbidden\", \"origin not allowed\");\n    const result = await identify(options, event);\n    if (\"refusal\" in result) return result.refusal;\n    const text = await request.text();\n    if (byteLength(text) > hub.limits.maxMessageBytes * 8)\n      return refuse(413, \"too_large\", \"the request is too large\");\n    let body: unknown;\n    try {\n      body = JSON.parse(text);\n    } catch {\n      return refuse(400, \"bad_frame\", \"the body is not JSON\");\n    }\n    const frames = (body as { frames?: unknown } | null)?.frames;\n    const cid = (body as { cid?: unknown } | null)?.cid;\n    if (!Array.isArray(frames) || frames.length === 0 || frames.length > MAX_FRAMES_PER_POST)\n      return refuse(400, \"bad_frame\", `frames must hold 1..${MAX_FRAMES_PER_POST} frames`);\n    const key = options.key?.(event, result.identity) ?? result.identity.user ?? \"anonymous\";\n    const answers: string[] = [];\n    const transport: Transport = {\n      send(frame) {\n        if (!frame.startsWith('{\"t\":\"ready\"')) answers.push(frame);\n        return true;\n      },\n      close: () => undefined,\n    };\n    const connection = hub.connect(transport, result.identity, {\n      stateless: true,\n      publishBucket: bucketFor(key),\n      ...(typeof cid === \"string\" ? { actingFor: cid } : {}),\n    });\n    try {\n      for (const frame of frames) {\n        const type = (frame as { t?: unknown } | null)?.t;\n        if (type === \"pres\") {\n          const item = frame as { c?: unknown; s?: unknown };\n          try {\n            if (typeof item.c !== \"string\" || typeof cid !== \"string\")\n              throw new RealtimeError(\"bad_frame\", \"pres needs c and the connection id\");\n            await hub.setMemberState(result.identity, item.c, cid, (item.s ?? null) as Json);\n          } catch (error) {\n            const code = error instanceof RealtimeError ? error.code : \"unavailable\";\n            answers.push(JSON.stringify({ t: \"err\", code }));\n          }\n          continue;\n        }\n        if (type !== \"pub\" && type !== \"req\") {\n          answers.push(\n            JSON.stringify({ t: \"err\", code: \"bad_frame\", msg: \"only pub, req and pres\" }),\n          );\n          continue;\n        }\n        connection.receive(JSON.stringify(frame));\n      }\n      await connection.settled();\n    } finally {\n      connection.closed();\n    }\n    return new Response(`{\"frames\":[${answers.join(\",\")}]}`, {\n      status: 200,\n      headers: { \"content-type\": \"application/json\", \"cache-control\": \"no-store\" },\n    });\n  };\n}\n"],"mappings":"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"}

package/dist/dev/server/hub.d.ts

@@ -0,0 +1,114 @@
+import { Json } from "../protocol.js";
+import { Adapter, PublishResult } from "../adapter.js";
+import { ChannelRule, Identity, RuleContext } from "./rules.js";
+import { HubLimits, TokenBucket } from "./limits.js";
+//#region src/server/hub.d.ts
+/**
+ * What a hub needs from a connection's transport. A WebSocket, an SSE stream and an in-memory test client all fit.
+ * @since 1.0.0
+ */
+export interface Transport {
+  /** Sends one frame (text). False when the transport is closed. */
+  send(frame: string): boolean;
+  /** Closes the transport with a WebSocket close code and a reason of at most 123 bytes. */
+  close(code: number, reason: string): void;
+  /** Bytes accepted by `send` that the peer has not yet taken. When present, a connection over the limit is closed. */
+  buffered?(): number;
+}
+/** Where an error reported to `onError` came from. @since 1.0.0 */
+export interface ErrorContext {
+  readonly where: string;
+  readonly channel?: string;
+  readonly connection?: string;
+}
+/** Options of {@link createHub}. @since 1.0.0 */
+export interface HubOptions {
+  /** Storage and fan-out. Default: a fresh `memoryAdapter()`, closed with the hub. */
+  readonly adapter?: Adapter;
+  /** Channel rules by pattern, in order. The first matching pattern wins. */
+  readonly channels?: Readonly<Record<string, ChannelRule>>;
+  /** Limits (see {@link HubLimits}). */
+  readonly limits?: Partial<HubLimits>;
+  /** Receives failures the hub handled (an adapter outage, a rule predicate that threw). Default: `console.error`. */
+  readonly onError?: (error: unknown, context: ErrorContext) => void;
+  /** The clock, in epoch milliseconds. Default `Date.now`. */
+  readonly now?: () => number;
+}
+/** Counters of a running hub. @since 1.0.0 */
+export interface HubStats {
+  readonly connections: number;
+  readonly channels: number;
+  readonly subscriptions: number;
+  readonly published: number;
+  readonly delivered: number;
+  readonly refused: number;
+  readonly slowConsumers: number;
+}
+/** One connection, as the transport glue drives it. @since 1.0.0 */
+export interface HubConnection {
+  readonly id: string;
+  readonly identity: Identity;
+  /** Hands the hub one text frame from the peer. Frames are handled in order. */
+  receive(text: string): void;
+  /** Tells the hub the transport closed. Safe to call twice. */
+  closed(): void;
+  /** Resolves once every frame received so far was handled and every request answered. */
+  settled(): Promise<void>;
+  /** Resolves when the hub finished releasing what the connection held. */
+  readonly done: Promise<void>;
+}
+/** How a connection differs from a long-lived one. @since 1.0.0 */
+export interface ConnectOptions {
+  /**
+   * A connection that exists for one HTTP request: a request is answered for any identity the channel's `subscribe` rule
+   * accepts (there is no subscription to look up), and nothing is kept after it closes.
+   */
+  readonly stateless?: boolean;
+  /** Replaces the connection's own publish bucket, so a caller can share one across requests. */
+  readonly publishBucket?: TokenBucket;
+  /**
+   * The id of a long-lived connection of the same user this request acts for (SSE clients post under their stream's id, so
+   * `echo:false` and `publisher` work). Honored only when that connection is open on this server and has the same user.
+   */
+  readonly actingFor?: string;
+}
+/** Who to remove subscriptions of. At least one field. @since 1.0.0 */
+export interface RevokeTarget {
+  readonly user?: string;
+  readonly connection?: string;
+  readonly channel?: string;
+}
+/** The server object. @since 1.0.0 */
+export interface HubCore {
+  /** Adds a channel rule after the ones already registered. */
+  channel(pattern: string, rule: ChannelRule): HubCore;
+  /** Starts handling a connection. Sends `ready`. */
+  connect(transport: Transport, identity?: Identity, options?: ConnectOptions): HubConnection;
+  /** Publishes from the server (no rule applies). */
+  publish(channel: string, event: string, data: unknown, options?: {
+    readonly key?: string;
+  }): Promise<PublishResult>;
+  /** Removes matching subscriptions; each subscriber gets `unsubbed why:"revoked"`. Returns how many were removed. */
+  revoke(target: RevokeTarget): number;
+  /** Counters. */
+  stats(): HubStats;
+  /** Closes every connection with 1001, stops timers, removes presence, settles requests. */
+  close(): Promise<void>;
+  /** @internal Changes the state of a presence member from outside its connection (SSE clients). */
+  setMemberState(identity: Identity, channel: string, connectionId: string, state: Json): Promise<void>;
+  /** @internal The resolved limits. */
+  readonly limits: HubLimits;
+  /** @internal The adapter. */
+  readonly adapter: Adapter;
+  /** @internal Reports an error. */
+  report(error: unknown, context: ErrorContext): void;
+  /** @internal Matches a channel against the rules. */
+  match(channel: string): {
+    readonly rule: ChannelRule;
+    readonly params: Record<string, string>;
+  } | undefined;
+  /** @internal Evaluates a rule permission for an identity. */
+  allowed(rule: ChannelRule, op: RuleContext["op"], channel: string, params: Record<string, string>, identity: Identity): Promise<boolean>;
+}
+//#endregion
+//# sourceMappingURL=hub.d.ts.map