@geekmidas/constructs 10.0.0-alpha.126 → 10.0.0-alpha.127

package/dist/websocket-api.cjs

@@ -0,0 +1,769 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_shutdown = require("./shutdown-BMJmAhSt.cjs");
+const require_construct_interface = require("./construct-interface.cjs");
+const require_surfaceEnv = require("./surfaceEnv-CNimK76p.cjs");
+let _geekmidas_manifest = require("@geekmidas/manifest");
+let _geekmidas_logger_console = require("@geekmidas/logger/console");
+let node_crypto = require("node:crypto");
+let _geekmidas_services = require("@geekmidas/services");
+let _geekmidas_errors = require("@geekmidas/errors");
+/** A connection string names no transport this package knows. */
+var UnsupportedWebSocketTransport = class extends Error {
+	connectionString;
+	constructor(connectionString) {
+		super(`'${redact(connectionString)}' is not a WebSocket publisher connection string. Use redis://, rediss:// or memory:// — gkm composes it as <ID>_PUBLISHER_CONNECTION_STRING.`);
+		this.connectionString = connectionString;
+		this.name = "UnsupportedWebSocketTransport";
+	}
+};
+/** The scheme alone, so an error never prints a password. */
+function redact(connectionString) {
+	const scheme = connectionString.split("://")[0];
+	return scheme && scheme !== connectionString ? `${scheme}://…` : connectionString.slice(0, 12);
+}
+const key = Symbol.for("@geekmidas/constructs/websocket/memory");
+const registry = globalThis;
+registry[key] ??= /* @__PURE__ */ new Map();
+const channels = registry[key];
+/**
+* In one process: the server and whoever sends meet in a map, keyed by the
+* channel the connection string names.
+*/
+var MemoryTransport = class {
+	channel;
+	subscribed = /* @__PURE__ */ new Set();
+	constructor(channel) {
+		this.channel = channel;
+	}
+	async publish(instance, delivery) {
+		const instances = channels.get(this.channel);
+		if (!instances) return;
+		if (instance === "*") {
+			for (const receive of instances.values()) receive(delivery);
+			return;
+		}
+		instances.get(instance)?.(delivery);
+	}
+	async subscribe(instance, receive) {
+		let instances = channels.get(this.channel);
+		if (!instances) {
+			instances = /* @__PURE__ */ new Map();
+			channels.set(this.channel, instances);
+		}
+		instances.set(instance, receive);
+		this.subscribed.add(instance);
+	}
+	async close() {
+		const instances = channels.get(this.channel);
+		for (const instance of this.subscribed) instances?.delete(instance);
+		this.subscribed.clear();
+	}
+};
+/**
+* Over Redis pub/sub: one channel per instance and one for broadcasts, under
+* a prefix that keeps two surfaces — or two projects on one Redis — apart.
+* Channels are not scoped by database index, so the prefix is what does it.
+*
+* Publishing and subscribing take separate connections, because a connection
+* that has subscribed can do nothing else.
+*/
+var RedisTransport = class {
+	client;
+	prefix;
+	subscriber;
+	closed;
+	constructor(client, prefix) {
+		this.client = client;
+		this.prefix = prefix;
+	}
+	channel(instance) {
+		return `${this.prefix}:${instance}`;
+	}
+	async publish(instance, delivery) {
+		await this.client.publish(this.channel(instance), JSON.stringify(delivery));
+	}
+	async subscribe(instance, receive) {
+		const subscriber = this.client.duplicate();
+		this.subscriber = subscriber;
+		const own = this.channel(instance);
+		const every = this.channel("*");
+		subscriber.on("message", (channel, message) => {
+			if (channel !== own && channel !== every) return;
+			receive(JSON.parse(message));
+		});
+		await subscriber.subscribe(own, every);
+	}
+	/** Idempotent: the server and a shutdown hook may both close it. */
+	close() {
+		this.closed ??= Promise.all([this.subscriber?.quit(), this.client.quit()]).then(() => void 0);
+		return this.closed;
+	}
+};
+/**
+* The transport a connection string names.
+*
+* `redis://` and `rediss://` take an optional `channel` query parameter, the
+* prefix every channel is named under; `memory://<channel>` is in-process.
+* Absent, the channel is `fallback` — the surface's own.
+*/
+async function transportFromConnectionString(connectionString, fallback) {
+	if (connectionString.startsWith("memory://")) return new MemoryTransport(connectionString.slice(9) || fallback);
+	const url = URL.canParse(connectionString) ? new URL(connectionString) : void 0;
+	if (!url) throw new UnsupportedWebSocketTransport(connectionString);
+	if (url.protocol === "redis:" || url.protocol === "rediss:") {
+		const channel = url.searchParams.get("channel") || fallback;
+		url.searchParams.delete("channel");
+		const { Redis } = await import("ioredis");
+		return new RedisTransport(new Redis(url.toString(), {
+			maxRetriesPerRequest: null,
+			lazyConnect: false
+		}), channel);
+	}
+	throw new UnsupportedWebSocketTransport(connectionString);
+}
+//#endregion
+//#region src/websocket/publisher.ts
+/** The instance a connection id was issued by: everything before its dot. */
+function instanceOf(connectionId) {
+	const dot = connectionId.indexOf(".");
+	return dot > 0 ? connectionId.slice(0, dot) : void 0;
+}
+/** A message sent on an action the surface does not declare. */
+var UnknownWebSocketMessage = class extends Error {
+	surface;
+	action;
+	declared;
+	constructor(surface, action, declared) {
+		super(`${surface} sends no '${action}' message. It declares ${declared.map((a) => `'${a}'`).join(", ")} — send one of them, or add '${action}' to its messages.`);
+		this.surface = surface;
+		this.action = action;
+		this.declared = declared;
+		this.name = "UnknownWebSocketMessage";
+	}
+};
+/** A message whose data its action's schema refused. */
+var InvalidWebSocketMessage = class extends Error {
+	surface;
+	action;
+	issues;
+	constructor(surface, action, issues) {
+		super(`${surface}'s '${action}' message was refused by its schema: ${issues.map((issue) => issue.message).join("; ")}. Nothing was sent.`);
+		this.surface = surface;
+		this.action = action;
+		this.issues = issues;
+		this.name = "InvalidWebSocketMessage";
+	}
+};
+/**
+* How anything reaches a socket — `services.realtime` in an endpoint, and
+* `sockets` in a route of the surface itself.
+*
+* A message is `{ action, data }`, the shape a client's frames arrive in.
+* Where the surface declares its messages, `action` is one of them and
+* `data` is typed and checked by its schema before anything is sent; where it
+* declares none, any action and any JSON value go. A message is serialised
+* once, whatever the number of sockets it goes to. An id whose process has
+* gone is dropped silently, as API Gateway's `postToConnection` to a closed
+* connection is a no-op the sender rarely wants to handle.
+*/
+var WebSocketPublisher = class {
+	transport;
+	local;
+	declared;
+	constructor(transport, local, declared) {
+		this.transport = transport;
+		this.local = local;
+		this.declared = declared;
+	}
+	/** Send `action`'s message to each connection. */
+	async send(ids, action, data) {
+		const payload = await this.payload(action, data);
+		await this.each(ids, (group) => ({
+			kind: "send",
+			ids: group,
+			payload
+		}));
+	}
+	/** Send `action`'s message to every open connection, on every process. */
+	async broadcast(action, data, options = {}) {
+		const payload = await this.payload(action, data);
+		await this.transport.publish("*", {
+			kind: "broadcast",
+			payload,
+			...options.except?.length ? { except: options.except } : {}
+		});
+	}
+	/** Close each connection, with a close code and reason its client sees. */
+	async close(ids, code = 1e3, reason = "") {
+		await this.each(ids, (group) => ({
+			kind: "close",
+			ids: group,
+			code,
+			reason
+		}));
+	}
+	/**
+	* The frame, checked by the action's schema where the surface declares
+	* its messages.
+	*
+	* @throws {UnknownWebSocketMessage}, {InvalidWebSocketMessage}
+	*/
+	async payload(action, data) {
+		if (!this.declared) return JSON.stringify({
+			action,
+			data
+		});
+		const { surface, messages } = this.declared;
+		const schema = messages[action];
+		if (!schema) throw new UnknownWebSocketMessage(surface, action, Object.keys(messages));
+		const result = await schema["~standard"].validate(data);
+		if (result.issues) throw new InvalidWebSocketMessage(surface, action, result.issues);
+		return JSON.stringify({
+			action,
+			data: result.value
+		});
+	}
+	/** One delivery per process that holds any of `ids`. */
+	async each(ids, delivery) {
+		const byInstance = /* @__PURE__ */ new Map();
+		for (const id of typeof ids === "string" ? [ids] : ids) {
+			const instance = instanceOf(id);
+			if (!instance) continue;
+			const group = byInstance.get(instance) ?? [];
+			group.push(id);
+			byInstance.set(instance, group);
+		}
+		await Promise.all([...byInstance].map(([instance, group]) => this.local?.instance === instance ? this.local.deliver(delivery(group)) : this.transport.publish(instance, delivery(group))));
+	}
+};
+//#endregion
+//#region src/websocket/route.ts
+/**
+* A handler bound to a WebSocket surface — what `realtime.route('chat.send')
+* …handle()` returns, and what a file exports.
+*
+* Carries `surface` and `constructs` the way an endpoint does, so discovery
+* records what its process reaches without knowing what a route is.
+*/
+var WebSocketRoute = class {
+	kind;
+	action;
+	surface;
+	services;
+	constructs;
+	handler;
+	schema;
+	__IS_WEBSOCKET_ROUTE__ = true;
+	static isRoute(value) {
+		return Boolean(value && value.__IS_WEBSOCKET_ROUTE__ === true);
+	}
+	constructor(kind, action, surface, services, constructs, handler, schema) {
+		this.kind = kind;
+		this.action = action;
+		this.surface = surface;
+		this.services = services;
+		this.constructs = constructs;
+		this.handler = handler;
+		this.schema = schema;
+	}
+};
+/** The builder `connect()`, `disconnect()` and `route()` start. */
+var WebSocketRouteBuilder = class WebSocketRouteBuilder {
+	kind;
+	action;
+	surface;
+	_services;
+	_constructs;
+	schema;
+	constructor(kind, action, surface, _services = [], _constructs = [], schema) {
+		this.kind = kind;
+		this.action = action;
+		this.surface = surface;
+		this._services = _services;
+		this._constructs = _constructs;
+		this.schema = schema;
+	}
+	/** The schema a frame's `data` must satisfy before the handler runs. */
+	body(schema) {
+		return new WebSocketRouteBuilder(this.kind, this.action, this.surface, this._services, this._constructs, schema);
+	}
+	/** What the handler reaches, as `services.<id>` — per route, as an endpoint's. */
+	dependsOn(constructs) {
+		return new WebSocketRouteBuilder(this.kind, this.action, this.surface, [...this._services, ...require_construct_interface.servicesOf(constructs)], require_construct_interface.idsOf(constructs, this._constructs), this.schema);
+	}
+	/**
+	* The handler. A message handler's return value, when there is one, is
+	* sent back to the connection as the reply to that frame; a connect
+	* handler's is kept as the connection's `data`.
+	*/
+	handle(handler) {
+		return new WebSocketRoute(this.kind, this.action, this.surface, this._services, this._constructs, handler, this.schema);
+	}
+};
+//#endregion
+//#region src/websocket/server.ts
+/**
+* The process that holds a WebSocket surface's sockets.
+*
+* Node's own `http` server and `ws`, nothing between them: a frame is parsed,
+* validated and handed to its route, and that is the whole hot path. The HTTP
+* server is whatever the entry started — the generated one serves `/health`
+* on the same port — and this attaches to its `upgrade` event.
+*/
+/** Close codes a client sees. */
+const CLOSE = {
+	normal: 1e3,
+	/** The process is stopping; reconnect and land on another. */
+	serviceRestart: 1012,
+	/** It stopped reading, and what was queued for it passed the limit. */
+	tooSlow: 1013
+};
+/** Two routes answer one action. */
+var DuplicateWebSocketRoute = class extends Error {
+	surface;
+	action;
+	constructor(surface, action) {
+		super(`Two routes on ${surface} answer '${action}'. Each action has one handler — rename one of them.`);
+		this.surface = surface;
+		this.action = action;
+		this.name = "DuplicateWebSocketRoute";
+	}
+};
+var WebSocketSurfaceServer = class WebSocketSurfaceServer {
+	wss;
+	options;
+	/** This process, as connection ids name it. */
+	instance = (0, node_crypto.randomBytes)(6).toString("hex");
+	/** `sockets` in a route: local sends skip the transport. */
+	publisher;
+	held = /* @__PURE__ */ new Map();
+	routes = /* @__PURE__ */ new Map();
+	lifecycle = {};
+	heartbeat;
+	next = 0;
+	closing = false;
+	constructor(wss, options) {
+		this.wss = wss;
+		this.options = options;
+		for (const route of options.routes) {
+			if (route.surface.id !== options.surface) continue;
+			if (route.kind === "message") {
+				if (this.routes.has(route.action)) throw new DuplicateWebSocketRoute(options.surface, route.action);
+				this.routes.set(route.action, route);
+			} else {
+				if (this.lifecycle[route.kind]) throw new DuplicateWebSocketRoute(options.surface, route.action);
+				this.lifecycle[route.kind] = route;
+			}
+		}
+		this.publisher = new WebSocketPublisher(options.transport, {
+			instance: this.instance,
+			deliver: (delivery) => this.deliver(delivery)
+		}, options.messages ? {
+			surface: options.surface,
+			messages: options.messages
+		} : void 0);
+		this.heartbeat = setInterval(() => this.beat(), options.heartbeatMs ?? 3e4);
+		this.heartbeat.unref();
+	}
+	static async start(options) {
+		const { WebSocketServer } = await import("ws");
+		const wss = new WebSocketServer({
+			noServer: true,
+			maxPayload: options.maxPayload ?? 1048576,
+			perMessageDeflate: false,
+			clientTracking: false
+		});
+		const server = new WebSocketSurfaceServer(wss, options);
+		await options.transport.subscribe(server.instance, (delivery) => server.deliver(delivery));
+		return server;
+	}
+	/** How many sockets this process holds. */
+	get size() {
+		return this.held.size;
+	}
+	/** Take over `server`'s upgrades. */
+	attach(server) {
+		server.on("upgrade", (request, socket, head) => {
+			this.upgrade(request, socket, head);
+		});
+	}
+	/** Upgrade one request, or refuse it with a status line. */
+	async upgrade(request, socket, head) {
+		if (this.closing) return refuse(socket, 503, "Service Unavailable");
+		const origin = request.headers.origin;
+		if (origin && !this.options.trustedOrigins.includes(origin)) return refuse(socket, 403, "Forbidden");
+		const connectionId = `${this.instance}.${(this.next++).toString(36)}`;
+		const headers = headersOf(request);
+		let data = {};
+		const connect = this.lifecycle.connect;
+		if (connect) try {
+			const session = this.options.authenticator ? await this.options.authenticator.verify(headers, this.options.envParser) : null;
+			const returned = await this.run(connect, connectionId, (base) => ({
+				...base,
+				connectionId,
+				headers,
+				query: new URL(request.url ?? "/", "http://localhost").searchParams,
+				session
+			}));
+			if (returned && typeof returned === "object") data = returned;
+		} catch (error) {
+			if (error instanceof _geekmidas_errors.HttpError) return refuse(socket, error.statusCode, error.statusMessage);
+			this.options.logger.error({
+				err: error,
+				connectionId
+			}, "WebSocket connect handler failed");
+			return refuse(socket, 500, "Internal Server Error");
+		}
+		if (socket.destroyed) return;
+		this.wss.handleUpgrade(request, socket, head, (ws) => this.open(ws, {
+			id: connectionId,
+			data
+		}));
+	}
+	open(socket, connection) {
+		const held = {
+			socket,
+			connection,
+			alive: true
+		};
+		this.held.set(connection.id, held);
+		socket.on("pong", () => {
+			held.alive = true;
+		});
+		socket.on("message", (raw, isBinary) => {
+			held.alive = true;
+			if (isBinary) return this.error(held, void 0, "Frames are JSON text.");
+			this.dispatch(held, raw.toString());
+		});
+		socket.on("error", () => socket.terminate());
+		socket.on("close", (code, reason) => {
+			this.held.delete(connection.id);
+			const disconnect = this.lifecycle.disconnect;
+			if (!disconnect) return;
+			this.run(disconnect, connection.id, (base) => ({
+				...base,
+				connection,
+				code,
+				reason: reason.toString()
+			})).catch((error) => this.options.logger.error({
+				err: error,
+				connectionId: connection.id
+			}, "WebSocket disconnect handler failed"));
+		});
+	}
+	/** Parse, validate and run one frame. Errors go back as frames, not closes. */
+	async dispatch(held, text) {
+		let frame;
+		try {
+			frame = JSON.parse(text);
+		} catch {
+			return this.error(held, void 0, "Frames are JSON.");
+		}
+		if (!frame || typeof frame.action !== "string") return this.error(held, frame?.id, "A frame names its `action`.");
+		const route = this.routes.get(frame.action) ?? this.routes.get("$default");
+		if (!route) return this.error(held, frame.id, `No route answers '${frame.action}'.`);
+		let body = frame.data;
+		if (route.schema) {
+			const result = await route.schema["~standard"].validate(frame.data);
+			if (result.issues) return this.error(held, frame.id, "The frame was invalid.", result.issues);
+			body = result.value;
+		}
+		try {
+			const returned = await this.run(route, held.connection.id, (base) => ({
+				...base,
+				connection: held.connection,
+				body,
+				reply: (message) => this.write(held, JSON.stringify(message))
+			}));
+			if (returned !== void 0) this.write(held, JSON.stringify({
+				action: frame.action,
+				...frame.id !== void 0 ? { id: frame.id } : {},
+				data: returned
+			}));
+		} catch (error) {
+			if (error instanceof _geekmidas_errors.HttpError) return this.error(held, frame.id, error.message);
+			this.options.logger.error({
+				err: error,
+				connectionId: held.connection.id,
+				action: frame.action
+			}, "WebSocket route failed");
+			this.error(held, frame.id, "The route failed.");
+		}
+	}
+	/** Run a handler with its services, inside a request context of its own. */
+	async run(route, connectionId, context) {
+		const logger = this.options.logger.child({
+			connectionId,
+			action: route.action
+		});
+		return (0, _geekmidas_services.runWithRequestContext)({
+			logger,
+			requestId: connectionId,
+			startTime: Date.now(),
+			operation: `ws ${route.action}`
+		}, async () => {
+			const services = route.services.length ? await _geekmidas_services.ServiceDiscovery.getInstance(this.options.envParser).register([...route.services]) : {};
+			return route.handler(context({
+				services,
+				logger,
+				sockets: this.publisher
+			}));
+		});
+	}
+	error(held, id, message, issues) {
+		this.write(held, JSON.stringify({
+			action: "$error",
+			...id !== void 0 ? { id } : {},
+			data: {
+				message,
+				...issues ? { issues } : {}
+			}
+		}));
+	}
+	/** Write, unless the socket has stopped reading and its queue is full. */
+	write(held, payload) {
+		const { socket } = held;
+		if (socket.readyState !== socket.OPEN) return;
+		if (socket.bufferedAmount > (this.options.maxBufferedBytes ?? 4194304)) {
+			socket.close(CLOSE.tooSlow, "Too slow");
+			return;
+		}
+		socket.send(payload);
+	}
+	/** What the transport, or a local publisher, asked of this process. */
+	deliver(delivery) {
+		switch (delivery.kind) {
+			case "send":
+				for (const id of delivery.ids) {
+					const held = this.held.get(id);
+					if (held) this.write(held, delivery.payload);
+				}
+				return;
+			case "broadcast": {
+				const except = delivery.except ? new Set(delivery.except) : void 0;
+				for (const [id, held] of this.held) if (!except?.has(id)) this.write(held, delivery.payload);
+				return;
+			}
+			case "close":
+				for (const id of delivery.ids) this.held.get(id)?.socket.close(delivery.code, delivery.reason);
+				return;
+		}
+	}
+	/** Drop every socket that missed the last ping, and ping the rest. */
+	beat() {
+		for (const [id, held] of this.held) {
+			if (!held.alive) {
+				held.socket.terminate();
+				this.held.delete(id);
+				continue;
+			}
+			held.alive = false;
+			held.socket.ping();
+		}
+	}
+	/**
+	* Stop: refuse new upgrades, close every socket with `code` — 1012 tells
+	* a client to reconnect, and it lands on a process that is still up — and
+	* leave the transport.
+	*/
+	async close(code = CLOSE.serviceRestart, reason = "Restarting") {
+		if (this.closing) return;
+		this.closing = true;
+		clearInterval(this.heartbeat);
+		const closed = [...this.held.values()].map(({ socket }) => new Promise((resolve) => {
+			if (socket.readyState === socket.CLOSED) return resolve();
+			socket.once("close", () => resolve());
+			socket.close(code, reason);
+			setTimeout(() => {
+				socket.terminate();
+				resolve();
+			}, 2e3).unref();
+		}));
+		await Promise.all(closed);
+		await this.options.transport.close();
+		this.wss.close();
+	}
+};
+function headersOf(request) {
+	const headers = new Headers();
+	for (const [name, value] of Object.entries(request.headers)) {
+		if (value === void 0) continue;
+		for (const one of Array.isArray(value) ? value : [value]) headers.append(name, one);
+	}
+	return headers;
+}
+function refuse(socket, status, message) {
+	if (!socket.destroyed) socket.end(`HTTP/1.1 ${status} ${message}\r\nConnection: close\r\nContent-Length: 0\r\n\r\n`);
+}
+//#endregion
+//#region src/websocket-api.ts
+/** A replica count that is not a whole number of at least one. */
+var InvalidReplicaCount = class extends Error {
+	id;
+	replicas;
+	constructor(id, replicas) {
+		super(`${id} asks for ${replicas} replicas. A surface runs on at least one process — give a whole number of 1 or more.`);
+		this.id = id;
+		this.replicas = replicas;
+		this.name = "InvalidReplicaCount";
+	}
+};
+var WebSocketApi = class WebSocketApi {
+	config;
+	dependencies;
+	authenticator;
+	id;
+	keys;
+	logger;
+	envParser;
+	telemetry;
+	/**
+	* The surface as a dependency: `services.<id>` is its publisher, so an
+	* endpoint sends to a socket the way a route beside it does.
+	*/
+	service;
+	constructor(id, config, dependencies = [], authenticator) {
+		this.config = config;
+		this.dependencies = dependencies;
+		this.authenticator = authenticator;
+		const canonical = (0, _geekmidas_manifest.canonicalId)(id);
+		this.id = canonical;
+		const replicas = config.replicas ?? 1;
+		if (!Number.isInteger(replicas) || replicas < 1) throw new InvalidReplicaCount(canonical, replicas);
+		this.keys = {
+			url: (0, _geekmidas_manifest.provideKey)(canonical, "url"),
+			trustedOrigins: (0, _geekmidas_manifest.provideKey)(canonical, "trustedOrigins"),
+			publisherConnectionString: (0, _geekmidas_manifest.provideKey)(canonical, "publisherConnectionString")
+		};
+		this.logger = config.logger ?? _geekmidas_logger_console.DEFAULT_LOGGER;
+		this.telemetry = config.telemetry;
+		this.envParser = require_surfaceEnv.envParserFor(config.envParser ? {
+			id: canonical,
+			envParser: config.envParser
+		} : void 0);
+		const envVar = this.keys.publisherConnectionString;
+		const channel = channelOf(canonical);
+		const declared = this.declared;
+		this.service = {
+			serviceName: (0, _geekmidas_manifest.serviceKey)(canonical),
+			async register({ envParser }) {
+				const { connectionString } = envParser.create((get) => ({ connectionString: get(envVar).string() })).parse();
+				const transport = await transportFromConnectionString(connectionString, channel);
+				require_shutdown.onShutdown(() => transport.close());
+				return new WebSocketPublisher(transport, void 0, declared);
+			}
+		};
+	}
+	/** The handler a connection's upgrade runs: refuse it, or say who it is. */
+	connect() {
+		return new WebSocketRouteBuilder("connect", "$connect", { id: this.id });
+	}
+	/** The handler a closed connection runs. */
+	disconnect() {
+		return new WebSocketRouteBuilder("disconnect", "$disconnect", { id: this.id });
+	}
+	/**
+	* The handler for frames whose `action` is `action`. `$default` answers
+	* any action nothing else does.
+	*/
+	route(action) {
+		return new WebSocketRouteBuilder("message", action, { id: this.id });
+	}
+	/** What authenticates a connection — its session reaches `connect()`. */
+	auth(construct) {
+		return new WebSocketApi(this.id, this.config, [...this.dependencies, require_construct_interface.edgeTo(construct)], construct);
+	}
+	/** Other surfaces this one calls. See `RestApi.calls`. */
+	calls(constructs) {
+		return new WebSocketApi(this.id, this.config, [...this.dependencies, ...constructs.map(require_construct_interface.edgeTo)], this.authenticator);
+	}
+	/**
+	* Serve it: the routes exported by `modules` that were built from this
+	* surface, on whatever HTTP server `attach` is handed.
+	*
+	* `app` answers plain HTTP — the generated entry puts `/health` in front
+	* of it — and `attach` takes over the server's upgrades. The sockets are
+	* closed with 1012 when the server shuts down.
+	*/
+	async server(options) {
+		const { Hono } = await import("hono");
+		const routes = (options.modules ?? []).flatMap((module) => Object.values(module).filter(WebSocketRoute.isRoute));
+		const { connectionString, origins } = options.envParser.create((get) => ({
+			connectionString: get(this.keys.publisherConnectionString).string().default(`memory://${channelOf(this.id)}`),
+			origins: get(this.keys.trustedOrigins).string().default("").transform((value) => value.split(",").map((origin) => origin.trim()).filter(Boolean))
+		})).parse();
+		const server = await WebSocketSurfaceServer.start({
+			surface: this.id,
+			routes,
+			transport: await transportFromConnectionString(connectionString, channelOf(this.id)),
+			envParser: options.envParser,
+			logger: this.logger,
+			trustedOrigins: origins,
+			...this.declared ? { messages: this.declared.messages } : {},
+			...this.authenticator ? { authenticator: this.authenticator } : {},
+			...this.config.heartbeat ? { heartbeatMs: this.config.heartbeat * 1e3 } : {},
+			...this.config.maxPayload ? { maxPayload: this.config.maxPayload } : {}
+		});
+		require_shutdown.onShutdown(() => server.close());
+		const app = new Hono();
+		app.get("/health", (c) => c.json({
+			status: "ok",
+			connections: server.size
+		}));
+		app.get("/", (c) => c.json({
+			surface: this.id,
+			connections: server.size
+		}, 426, { Upgrade: "websocket" }));
+		return {
+			app,
+			attach: (http) => server.attach(http),
+			release: () => server.close(),
+			server
+		};
+	}
+	/** The declared messages, with the surface they are checked for. */
+	get declared() {
+		return this.config.messages ? {
+			surface: this.id,
+			messages: this.config.messages
+		} : void 0;
+	}
+	declare() {
+		return [{
+			kind: "websocket-api",
+			id: this.id,
+			path: this.config.path,
+			...this.config.subdomain ? { subdomain: this.config.subdomain } : {},
+			...this.authenticator ? { auth: this.authenticator.id } : {},
+			...this.dependencies.length ? { calls: this.dependencies } : {},
+			...this.config.telemetry ? { telemetry: this.config.telemetry.id } : {},
+			...this.config.replicas && this.config.replicas > 1 ? { replicas: this.config.replicas } : {},
+			provides: [
+				this.keys.url,
+				this.keys.trustedOrigins,
+				this.keys.publisherConnectionString
+			]
+		}];
+	}
+};
+/** The prefix a surface's channels are named under. */
+function channelOf(id) {
+	return `gkm:ws:${id}`;
+}
+//#endregion
+exports.CLOSE = CLOSE;
+exports.DuplicateWebSocketRoute = DuplicateWebSocketRoute;
+exports.InvalidReplicaCount = InvalidReplicaCount;
+exports.InvalidWebSocketMessage = InvalidWebSocketMessage;
+exports.MemoryTransport = MemoryTransport;
+exports.RedisTransport = RedisTransport;
+exports.UnknownWebSocketMessage = UnknownWebSocketMessage;
+exports.UnsupportedWebSocketTransport = UnsupportedWebSocketTransport;
+exports.WebSocketApi = WebSocketApi;
+exports.WebSocketPublisher = WebSocketPublisher;
+exports.WebSocketRoute = WebSocketRoute;
+exports.WebSocketRouteBuilder = WebSocketRouteBuilder;
+exports.WebSocketSurfaceServer = WebSocketSurfaceServer;
+exports.transportFromConnectionString = transportFromConnectionString;
+
+//# sourceMappingURL=websocket-api.cjs.map