@plitzi/sdk-server 0.37.2 → 0.37.4

package/dist/core/oauth/register.js

@@ -1,21 +1,38 @@
-import { randomId } from "./pkce.js";
 import { getClientByFingerprint, putClient, putClientFingerprint } from "./records.js";
+import { randomId } from "./pkce.js";
 import { sendErrorJson, sendJson } from "./respond.js";
 import { createHash } from "node:crypto";
 //#region src/core/oauth/register.ts
-var isUsableRedirectUri = (value) => {
-	let url;
+var parseUri = (value) => {
 	try {
-		url = new URL(value);
+		return new URL(value);
 	} catch {
-		return false;
+		return;
 	}
-	if (url.protocol === "https:") return true;
-	return url.protocol === "http:" && (url.hostname === "localhost" || url.hostname === "127.0.0.1");
 };
+/** Plain http on the loopback interface — the exception RFC 8252 carves out for a native app listening on a port. */
+var isLoopbackRedirectUri = (value) => {
+	const url = parseUri(value);
+	return url?.protocol === "http:" && (url.hostname === "localhost" || url.hostname === "127.0.0.1");
+};
+/**
+* A redirect target must be one the user's browser can be sent to safely: https anywhere, or loopback. A deployment
+* whose clients are all native apps narrows that to loopback alone (see `OAuthConfig.loopbackRedirectsOnly`).
+*/
+var isUsableRedirectUri = (value, loopbackOnly) => isLoopbackRedirectUri(value) || !loopbackOnly && parseUri(value)?.protocol === "https:";
 var stringList = (value) => Array.isArray(value) ? value.filter((entry) => typeof entry === "string") : [];
 var nowSeconds = () => Math.floor(Date.now() / 1e3);
 var fingerprintOf = (clientName, redirectUris) => createHash("sha256").update(JSON.stringify([clientName, [...redirectUris].sort()])).digest("base64url");
+/**
+* What a client calls itself is shown to the person it acts for — on the grant screen and in their list of devices — so
+* it is bounded: a name is a line of text, not a document a client can fill the screen with.
+*/
+var CLIENT_NAME_MAX = 120;
+var SOFTWARE_ID_MAX = 64;
+var textField = (value, max) => {
+	if (typeof value !== "string") return;
+	return value.trim().slice(0, max) || void 0;
+};
 /** RFC 7591 dynamic client registration. A remote host has no way to be configured into this server ahead of
 *  time, so it registers itself on first connect; the record it gets back is only ever used to pin the redirect
 *  target, since a public client authenticates with PKCE rather than with credentials. */
@@ -25,17 +42,20 @@ var handleRegister = async (config, res, body) => {
 		return;
 	}
 	const metadata = body;
-	const redirectUris = stringList(metadata["redirect_uris"]).filter(isUsableRedirectUri);
+	const loopbackOnly = config.loopbackRedirectsOnly === true;
+	const redirectUris = stringList(metadata["redirect_uris"]).filter((uri) => isUsableRedirectUri(uri, loopbackOnly));
 	if (redirectUris.length === 0) {
-		sendErrorJson(res, 400, "invalid_request", "redirect_uris must list at least one https (or loopback) URI.");
+		sendErrorJson(res, 400, "invalid_request", loopbackOnly ? "redirect_uris must list at least one loopback URI (http://127.0.0.1:<port>/…)." : "redirect_uris must list at least one https (or loopback) URI.");
 		return;
 	}
-	const clientName = typeof metadata["client_name"] === "string" ? metadata["client_name"] : "MCP client";
+	const clientName = textField(metadata["client_name"], CLIENT_NAME_MAX) ?? "MCP client";
+	const softwareId = textField(metadata["software_id"], SOFTWARE_ID_MAX);
 	const { store } = config.adapters;
 	const fingerprint = fingerprintOf(clientName, redirectUris);
 	const client = await getClientByFingerprint(store, fingerprint) ?? {
 		clientId: randomId(),
 		clientName,
+		...softwareId ? { softwareId } : {},
 		redirectUris,
 		issuedAt: nowSeconds()
 	};
@@ -45,6 +65,7 @@ var handleRegister = async (config, res, body) => {
 		client_id: client.clientId,
 		client_id_issued_at: client.issuedAt,
 		client_name: clientName,
+		...client.softwareId ? { software_id: client.softwareId } : {},
 		redirect_uris: redirectUris,
 		grant_types: config.refreshTtlSeconds === 0 ? ["authorization_code"] : ["authorization_code", "refresh_token"],
 		response_types: ["code"],
@@ -52,4 +73,4 @@ var handleRegister = async (config, res, body) => {
 	});
 };
 //#endregion
-export { handleRegister };
+export { handleRegister, isLoopbackRedirectUri };

package/dist/core/oauth/register.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/oauth/token.js

@@ -1,7 +1,8 @@
+import { dropAccess, dropCode, dropRefresh, getAccess, getCode, getRefresh, putAccess, putRefresh } from "./records.js";
+import { issueContextFor } from "./issueContext.js";
 import { scopesOf } from "./metadata.js";
 import { field, optionalField } from "./params.js";
 import { randomId, verifyChallenge } from "./pkce.js";
-import { dropAccess, dropCode, dropRefresh, getCode, getRefresh, putAccess, putRefresh } from "./records.js";
 import { sendErrorJson, sendJson } from "./respond.js";
 //#region src/core/oauth/token.ts
 var DEFAULT_REFRESH_TTL_SECONDS = 2592e3;
@@ -35,12 +36,21 @@ var sendTokens = async (config, res, credential, expiresInSeconds, grant) => {
 	const body = {
 		access_token: bearer,
 		token_type: "Bearer",
-		scope: scopeOf(config, grant.scope)
+		scope: scopeOf(config, grant.scope),
+		/**
+		* What the person chose on the grant screen — a space, the account. RFC 6749 §5.1 lets a token response carry
+		* parameters of its own, and this one is what a client that asked to CHOOSE needs back: without it, a native
+		* client granted "work in this space" would hold a credential and not know which space it was for.
+		*/
+		target: grant.target.value
 	};
 	if (expiresInSeconds !== void 0) body["expires_in"] = expiresInSeconds;
 	if (ttl > 0) {
 		const refreshToken = randomId();
-		await putRefresh(config.adapters.store, refreshToken, grant, ttl);
+		await putRefresh(config.adapters.store, refreshToken, {
+			...grant,
+			credential
+		}, ttl);
 		body["refresh_token"] = refreshToken;
 	}
 	sendJson(res, 200, body);
@@ -89,7 +99,7 @@ var exchangeRefresh = async (config, res, params) => {
 		sendErrorJson(res, 400, "invalid_grant", "The refresh token was issued to another client.");
 		return;
 	}
-	const issued = await config.adapters.issueToken(record.user, record.target);
+	const issued = await config.adapters.issueToken(record.user, record.target, await issueContextFor(config, record.clientId, { replaces: record.credential }));
 	if (!issued) {
 		sendErrorJson(res, 400, "invalid_grant", "The account no longer has access to this resource.");
 		return;
@@ -107,8 +117,13 @@ var exchangeRefresh = async (config, res, params) => {
 var handleRevoke = async (config, res, params) => {
 	const token = optionalField(params, "token");
 	if (token) {
-		await dropRefresh(config.adapters.store, token);
-		await dropAccess(config.adapters.store, token);
+		const { store, revokeToken } = config.adapters;
+		const refresh = await getRefresh(store, token);
+		const access = await getAccess(store, token);
+		await dropRefresh(store, token);
+		await dropAccess(store, token);
+		const credential = refresh?.credential ?? (access ? access.credential ?? token : void 0);
+		if (credential && revokeToken) await revokeToken(credential);
 	}
 	res.setStatus(200);
 	res.end();

package/dist/core/oauth/token.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/requestParser.d.ts

@@ -9,4 +9,8 @@ export declare const requestOrigin: (req: SSRRequest) => string;
  *  the original client first. All three are plain headers a direct client can forge, so this is log/diagnostic
  *  material — never an authorisation input. Falls back to the socket peer, which no client controls. */
 export declare const clientIp: (raw: IncomingMessage, req: SSRRequest) => string;
+/** The proxies' account of the client address, without the socket — for a caller that has headers and nothing else. */
+export declare const forwardedIp: (headers: Record<string, string | string[] | undefined>) => string;
+/** A request's body as it arrived, byte for byte — what a binary upload to a function's route needs. */
+export declare const readRawBytes: (raw: IncomingMessage) => Promise<Buffer>;
 export declare const readRawBody: (raw: IncomingMessage) => Promise<string>;

package/dist/core/requestParser.js

@@ -18,8 +18,10 @@ var parseRequest = (raw) => {
 		const sp = new URLSearchParams(search.slice(1));
 		for (const [k, v] of sp.entries()) query[k] = v;
 	}
+	const method = (headers[":method"] ?? raw.method ?? "GET").toUpperCase();
+	const ip = forwardedIp(headers) || unmapIpv4(raw.socket.remoteAddress ?? "");
 	return {
-		method: (headers[":method"] ?? raw.method ?? "GET").toUpperCase(),
+		method,
 		path,
 		search,
 		url: rawUrl,
@@ -27,6 +29,7 @@ var parseRequest = (raw) => {
 		protocol,
 		headers,
 		query,
+		...ip ? { ip } : {},
 		ctx: {}
 	};
 };
@@ -43,12 +46,15 @@ var unmapIpv4 = (address) => address.startsWith("::ffff:") && address.includes("
 *  peer it accepted in `cf-connecting-ip`, the ingress in `x-real-ip`, and `x-forwarded-for` lists the chain with
 *  the original client first. All three are plain headers a direct client can forge, so this is log/diagnostic
 *  material — never an authorisation input. Falls back to the socket peer, which no client controls. */
-var clientIp = (raw, req) => {
-	const forwardedFor = headerValue(req.headers["x-forwarded-for"]).split(",")[0] ?? "";
-	return unmapIpv4(headerValue(req.headers["cf-connecting-ip"]) || headerValue(req.headers["x-real-ip"]) || forwardedFor.trim() || raw.socket.remoteAddress || "");
+var clientIp = (raw, req) => forwardedIp(req.headers) || unmapIpv4(raw.socket.remoteAddress ?? "");
+/** The proxies' account of the client address, without the socket — for a caller that has headers and nothing else. */
+var forwardedIp = (headers) => {
+	const forwardedFor = headerValue(headers["x-forwarded-for"]).split(",")[0] ?? "";
+	return unmapIpv4(headerValue(headers["cf-connecting-ip"]) || headerValue(headers["x-real-ip"]) || forwardedFor.trim());
 };
 var MAX_BODY_BYTES = 1048576;
-var readRawBody = (raw) => new Promise((resolve, reject) => {
+/** A request's body as it arrived, byte for byte — what a binary upload to a function's route needs. */
+var readRawBytes = (raw) => new Promise((resolve, reject) => {
 	const chunks = [];
 	let size = 0;
 	raw.on("data", (chunk) => {
@@ -59,8 +65,9 @@ var readRawBody = (raw) => new Promise((resolve, reject) => {
 		}
 		chunks.push(chunk);
 	});
-	raw.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+	raw.on("end", () => resolve(Buffer.concat(chunks)));
 	raw.on("error", reject);
 });
+var readRawBody = async (raw) => (await readRawBytes(raw)).toString("utf8");
 //#endregion
-export { clientIp, parseRequest, readRawBody, requestOrigin };
+export { clientIp, forwardedIp, parseRequest, readRawBody, readRawBytes, requestOrigin };

package/dist/core/sdkAssets.js

@@ -1,6 +1,6 @@
 import { createRequire } from "node:module";
-import { statSync } from "node:fs";
 import path from "node:path";
+import { statSync } from "node:fs";
 //#region src/core/sdkAssets.ts
 /** Where the rendered page is told to fetch the SDK bundle from. Emitted by the render, so it is also served. */
 var SDK_ASSETS_PREFIX = "/sdk-assets";

package/dist/core/server/baseServer.d.ts

@@ -6,7 +6,17 @@ export interface HttpServerParts {
     plugins: PluginRegistry;
     /** Started once the transport is bound: background work that should not run in a server nobody listened on. */
     onListen?: () => void;
+    /**
+     * The server has stopped taking connections and is shutting down: what holds connections open for good — realtime
+     * sockets and streams — lets them go now, rather than being cut when the grace runs out.
+     */
+    onClosing?: () => void;
     /** Awaited, so a server that holds work in flight — jobs, drains — can finish it before the sockets close. */
     onDestroy?: () => void | Promise<void>;
+    /** What a plugin invalidated in another process of the fleet leaves to do here: forget it, in memory only. */
+    forgetPlugins?: (name?: string, version?: string) => void;
+    /** What the primary does once, before it starts the workers — work each of them would otherwise repeat, or race
+     *  the others to do. */
+    beforeFork?: () => Promise<void>;
 }
 export declare const createHttpServer: (config: SSRServerConfig, makeHandlerForPort: (port: number) => Handler, parts: HttpServerParts) => SSRServer;

package/dist/core/server/baseServer.js

@@ -1,4 +1,9 @@
+import { serverLog } from "../../helpers/serverLog.js";
+import { fleetRole, resolveWorkers } from "./fleet/role.js";
+import { channelName } from "./fleet/link.js";
 import { buildTransport, protoLabel } from "../transports.js";
+import { watchConnections } from "./drain.js";
+import { relayCache, relayPlugins } from "./fleet/relay.js";
 //#region src/core/server/baseServer.ts
 /**
 * What went wrong taking the port, and what to do about it.
@@ -19,13 +24,33 @@ var createHttpServer = (config, makeHandlerForPort, parts) => {
 	const version = config.httpVersion ?? (config.tls ? 2 : 1);
 	if (version >= 3 && !config.tls) throw new Error(`[${label}] httpVersion: ${version} requires a tls config with key and cert`);
 	let primary;
+	let connections;
 	let h3;
+	let fleet;
+	let closed = false;
+	const plan = resolveWorkers(config.workers);
+	const role = fleetRole(plan);
+	const channel = role === "single" ? void 0 : channelName(label);
 	return {
-		cache: parts.cache,
-		plugins: parts.plugins,
+		cache: channel && parts.cache ? relayCache(parts.cache, `${channel}.cache`) : parts.cache,
+		plugins: channel && parts.forgetPlugins ? relayPlugins(parts.plugins, parts.forgetPlugins, `${channel}.plugins`, label) : parts.plugins,
 		listen(port, host = "0.0.0.0") {
+			if (plan.requested !== void 0 && role !== "worker") serverLog.warn(label, `${plan.requested} workers asked for, ${plan.count} cores to run them on: starting ${plan.count}`);
+			if (role === "primary") {
+				(parts.beforeFork?.() ?? Promise.resolve()).catch((error) => serverLog.error(label, "preparing for the workers failed", error)).then(async () => {
+					const { startFleet } = await import("./fleet/supervisor.js");
+					if (closed) return;
+					fleet = startFleet(plan.count, label);
+					serverLog.info(label, `${plan.count} workers on ${host}:${port}`);
+				}).catch((error) => {
+					serverLog.error(label, "the workers could not start", error);
+					process.exitCode = 1;
+				});
+				return;
+			}
 			const handler = makeHandlerForPort(port);
 			({primary, h3} = buildTransport(config, handler, port, label));
+			connections = watchConnections(primary);
 			primary.on("error", (error) => {
 				if (config.onListenError) {
 					config.onListenError(error, {
@@ -35,29 +60,35 @@ var createHttpServer = (config, makeHandlerForPort, parts) => {
 					});
 					return;
 				}
-				console.error(bindFailure(error, port, label));
+				serverLog.error(label, bindFailure(error, port, label));
 				process.exitCode = 1;
 				process.exit(1);
 			});
 			primary.listen(port, host, () => {
-				console.log(`[${label}] ${protoLabel(version, !!config.tls)} - listening on ${host}:${port}`);
+				serverLog.info(label, `${protoLabel(version, !!config.tls)} - listening on ${host}:${port}`);
 				parts.onListen?.();
 			});
 		},
 		async close() {
-			await parts.onDestroy?.();
-			const open = [primary, h3].filter((srv) => srv !== void 0);
+			closed = true;
+			await fleet?.stop();
+			fleet = void 0;
+			const draining = connections?.drain(label);
+			const quic = h3;
 			primary = void 0;
+			connections = void 0;
 			h3 = void 0;
-			await Promise.all(open.map((srv) => new Promise((resolve, reject) => {
-				srv.close((err) => {
-					if (err && err.code !== "ERR_SERVER_NOT_RUNNING") {
-						reject(err);
+			parts.onClosing?.();
+			await parts.onDestroy?.();
+			await Promise.all([draining, quic && new Promise((resolve, reject) => {
+				quic.close((error) => {
+					if (error && !("code" in error && error.code === "ERR_SERVER_NOT_RUNNING")) {
+						reject(error);
 						return;
 					}
 					resolve();
 				});
-			})));
+			})]);
 		}
 	};
 };

package/dist/core/server/closeOnSignals.js

@@ -1,3 +1,4 @@
+import { serverLog } from "../../helpers/serverLog.js";
 //#region src/core/server/closeOnSignals.ts
 /**
 * Closes the server when the process is told to stop, and only then lets the process exit.
@@ -20,19 +21,19 @@ var closeOnSignals = (server, { signals = ["SIGTERM", "SIGINT"], afterClose } =
 	let closing = false;
 	const onSignal = (signal) => {
 		if (closing) {
-			console.warn(`[server] ${signal} again: exiting without waiting`);
+			serverLog.warn("server", `${signal} again: exiting without waiting`);
 			process.exit(1);
 			return;
 		}
 		closing = true;
-		console.info(`[server] ${signal}: finishing what is running, then exiting`);
+		serverLog.info("server", `${signal}: finishing what is running, then exiting`);
 		(async () => {
 			try {
 				await server.close();
 				await afterClose?.();
 				process.exit(0);
 			} catch (error) {
-				console.error("[server] could not close cleanly:", error);
+				serverLog.error("server", "could not close cleanly", error);
 				process.exit(1);
 			}
 		})();

package/dist/core/server/drain.d.ts

@@ -0,0 +1,18 @@
+import { PrimaryServer } from '../transports';
+/**
+ * How long a server shutting down lets what it is answering finish before it cuts it: a render, an upload, an action
+ * called a moment ago. Well under the 30 seconds a cluster gives a pod between SIGTERM and SIGKILL.
+ */
+export declare const SHUTDOWN_GRACE_MS = 10000;
+/**
+ * The connections a server holds, watched from the moment it is built, so it can be shut down.
+ *
+ * Node's `server.close()` stops taking connections and then waits for every open one to end. A request ends; a
+ * WebSocket or an event stream does not — a board open in a tab, an agent's app listening — so a server with one open
+ * waited for ever, and a Ctrl+C or a SIGTERM hung until something killed it. `drain` stops taking connections, closes
+ * the idle ones, ends every event stream at once (a stream has nothing left to finish), gives what is still being
+ * answered `graceMs`, and then cuts what remains.
+ */
+export declare const watchConnections: (server: PrimaryServer) => {
+    drain: (label: string, graceMs?: number) => Promise<void>;
+};

package/dist/core/server/drain.js

@@ -0,0 +1,62 @@
+import { serverLog } from "../../helpers/serverLog.js";
+//#region src/core/server/drain.ts
+/**
+* How long a server shutting down lets what it is answering finish before it cuts it: a render, an upload, an action
+* called a moment ago. Well under the 30 seconds a cluster gives a pod between SIGTERM and SIGKILL.
+*/
+var SHUTDOWN_GRACE_MS = 1e4;
+/**
+* Whether a response is an event stream: said by its content type — or, since headers written with `writeHead(status,
+* headers)` are not kept where `getHeader` looks, by what it answers: a GET that asked for one, as an EventSource and
+* an MCP client's listening stream do.
+*/
+var isEventStream = (asking, answering) => {
+	const type = answering.getHeader("content-type");
+	const accept = asking.headers.accept;
+	return typeof type === "string" && type.startsWith("text/event-stream") || asking.method === "GET" && [accept].flat().some((value) => value?.includes("text/event-stream"));
+};
+/**
+* The connections a server holds, watched from the moment it is built, so it can be shut down.
+*
+* Node's `server.close()` stops taking connections and then waits for every open one to end. A request ends; a
+* WebSocket or an event stream does not — a board open in a tab, an agent's app listening — so a server with one open
+* waited for ever, and a Ctrl+C or a SIGTERM hung until something killed it. `drain` stops taking connections, closes
+* the idle ones, ends every event stream at once (a stream has nothing left to finish), gives what is still being
+* answered `graceMs`, and then cuts what remains.
+*/
+var watchConnections = (server) => {
+	const sockets = /* @__PURE__ */ new Set();
+	const answering = /* @__PURE__ */ new Map();
+	server.on("connection", (socket) => {
+		sockets.add(socket);
+		socket.once("close", () => sockets.delete(socket));
+	});
+	server.on("request", (request, response) => {
+		answering.set(response, request);
+		response.once("close", () => answering.delete(response));
+	});
+	return { drain: (label, graceMs = SHUTDOWN_GRACE_MS) => new Promise((resolve, reject) => {
+		const cut = setTimeout(() => {
+			if (sockets.size) serverLog.warn(label, `${sockets.size} connection(s) still open after ${graceMs} ms: closing them`);
+			sockets.forEach((socket) => socket.destroy());
+		}, graceMs);
+		cut.unref();
+		server.close((error) => {
+			clearTimeout(cut);
+			if (error && !("code" in error && error.code === "ERR_SERVER_NOT_RUNNING")) {
+				reject(error);
+				return;
+			}
+			resolve();
+		});
+		const closeIdle = () => {
+			if ("closeIdleConnections" in server) server.closeIdleConnections();
+		};
+		closeIdle();
+		answering.forEach((request, response) => {
+			if (isEventStream(request, response)) response.end(closeIdle);
+		});
+	}) };
+};
+//#endregion
+export { SHUTDOWN_GRACE_MS, watchConnections };

package/dist/core/server/drain.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/server/fleet/channel.d.ts

@@ -0,0 +1,103 @@
+/**
+ * What the workers of one server say to their primary, and it to them — with nothing here that knows about
+ * `node:cluster`, so the rules can be held by tests in one process.
+ *
+ * Two things cross it:
+ *
+ * - **Calls to a store the primary holds.** A default kept in memory — an action's `kv`, the job queue, the drafts a
+ *   preview reads, the sign-in rate limit — is right for one process and wrong for several: a counter that counts
+ *   one worker's requests, a schedule every worker fires. With workers, the primary keeps the one copy and each
+ *   worker calls it. One process answering them in turn is what makes `increment` atomic across the fleet.
+ * - **Broadcasts.** What one process is told — invalidate this page, forget that plugin — reaches every other.
+ *   Nothing answers a broadcast, so what is sent must be safe to apply twice.
+ */
+export type FleetCall = {
+    sdkFleet: 'call';
+    id: number;
+    store: string;
+    method: string;
+    args: unknown[];
+};
+export type FleetReply = {
+    sdkFleet: 'reply';
+    id: number;
+    ok: true;
+    value: unknown;
+} | {
+    sdkFleet: 'reply';
+    id: number;
+    ok: false;
+    error: string;
+};
+export type FleetBroadcast = {
+    sdkFleet: 'broadcast';
+    channel: string;
+    payload: unknown;
+};
+export type FleetMessage = FleetCall | FleetReply | FleetBroadcast;
+/** The channel is shared with `node:cluster` and anything else the deployment sends: only these are ours. */
+export declare const isFleetMessage: (value: unknown) => value is FleetMessage;
+/** A store as a worker sees it: every method answers later, since the answer comes from another process. */
+export type Remote<T> = {
+    [K in keyof T]: T[K] extends (...args: infer A) => infer R ? (...args: A) => Promise<Awaited<R>> : never;
+};
+/** Every method of a store, named: the key set is checked, so a method added to the store is not left unreachable. */
+export type StoreMethods<T> = {
+    [K in keyof T]-?: true;
+};
+/** How the primary makes a store the first time a worker asks for it, and the methods a worker may call on it. */
+export type HostedStore = {
+    create: () => object;
+    methods: ReadonlySet<string>;
+};
+export declare const hostable: <T extends object>(create: () => T, methods: StoreMethods<T>) => HostedStore;
+/**
+ * The primary's side: the stores it keeps for its workers, answering their calls.
+ *
+ * A worker names a store `<kind>#<n>` — the n-th of that kind its code built, the same in every worker since they
+ * all run the same code — and the primary makes it from the catalogue the first time it is asked. Nothing is made
+ * that no worker uses. A call names a method the kind was registered with and nothing else: the channel is not a way
+ * to reach whatever the object happens to carry.
+ */
+export declare const createStoreHost: (catalogue: Readonly<Record<string, HostedStore>>) => {
+    answer: (call: FleetCall) => Promise<FleetReply>;
+};
+export type StoreHost = ReturnType<typeof createStoreHost>;
+/** Who in this process hears a broadcast, by channel. A listener that throws is the caller's to report. */
+export declare const createListeners: (onError: (channel: string, error: unknown) => void) => {
+    listen: (channel: string, listener: (payload: unknown) => void) => (() => void);
+    deliver: (channel: string, payload: unknown) => void;
+};
+/**
+ * A worker's side: calls to the primary's stores, and broadcasts both ways.
+ *
+ * `send` may throw — a value that cannot cross the channel, a primary already gone — and the call then fails
+ * rather than waiting for an answer that will not come. The same when the channel closes with calls in flight.
+ */
+export declare const createFleetClient: (send: (message: FleetMessage) => void, deliver: (channel: string, payload: unknown) => void) => {
+    call: (store: string, method: string, args: unknown[]) => Promise<unknown>;
+    remote: <T extends object>(store: string, methods: StoreMethods<T>) => Remote<T>;
+    broadcast: (channel: string, payload: unknown) => void;
+    receive: (message: FleetMessage) => void;
+    close: () => void;
+};
+export type FleetClient = ReturnType<typeof createFleetClient>;
+export type FleetPeer = {
+    id: number;
+    send: (message: FleetMessage) => void;
+};
+/**
+ * The primary's side of the channel: it answers its workers' calls from the stores it holds, and passes each
+ * broadcast on to every process that did not send it — itself included, so a server in the primary hears it too.
+ *
+ * A peer that went away between a call and its answer is simply not answered: it is not waiting any more.
+ */
+export declare const createFleetHub: ({ host, deliver, peers }: {
+    host: StoreHost;
+    deliver: (channel: string, payload: unknown) => void;
+    peers: () => FleetPeer[];
+}) => {
+    receive: (from: number, message: FleetMessage) => Promise<void>;
+    broadcast: (channel: string, payload: unknown, except?: number) => void;
+};
+export type FleetHub = ReturnType<typeof createFleetHub>;