@plitzi/sdk-server 0.37.1 → 0.37.3

package/dist/modules/realtime/hub.js

@@ -0,0 +1,141 @@
+import { JOIN_TYPE, LEAVE_TYPE, REVOKED_TYPE } from "@plitzi/sdk-shared/realtime";
+//#region src/modules/realtime/hub.ts
+/** A space's topic, as the adapter knows it: namespaced, so two spaces never hear each other. */
+var adapterTopic = ({ spaceId, environment }, topic) => `${spaceId}/${environment}/${topic}`;
+/**
+* Said between the servers, never to a page: every connection opened with the grant it names — or, naming none, with
+* any grant for the topic — is let go of it. On the topic's own adapter channel, so it reaches every replica holding
+* the topic, and only them. A page cannot send it: the types a page or a flow may use have no `$` but `$presence`.
+*/
+var REVOKE_TYPE = "$revoke";
+var revokedGrant = (data) => typeof data === "object" && data !== null && "grant" in data && typeof data.grant === "string" ? data.grant : void 0;
+/** A message as the adapter carried it — written by this module, but read from a transport that is not. */
+var isMessage = (value) => typeof value === "object" && value !== null && "topic" in value && typeof value.topic === "string" && "type" in value && typeof value.type === "string" && "from" in value && typeof value.from === "string" && "at" in value && typeof value.at === "number";
+var parse = (raw) => {
+	try {
+		const value = JSON.parse(raw);
+		return isMessage(value) ? value : void 0;
+	} catch {
+		return;
+	}
+};
+/**
+* This process's connections, and the ONE adapter subscription per topic they share.
+*
+* A hundred pages on one board are a hundred connections here and a single subscription to the adapter: a message
+* arrives once and is written to each of them. The last one to leave a topic unsubscribes it.
+*/
+var createRealtimeHub = (pubsub) => {
+	const byToken = /* @__PURE__ */ new Map();
+	const local = /* @__PURE__ */ new Map();
+	const publish = (space, message) => pubsub.publish(adapterTopic(space, message.topic), JSON.stringify(message));
+	const join = async (connection, topic) => {
+		const key = adapterTopic(connection.space, topic);
+		let entry = local.get(key);
+		if (!entry) {
+			const connections = /* @__PURE__ */ new Set();
+			entry = {
+				connections,
+				release: pubsub.subscribe(key, (raw) => {
+					const message = parse(raw);
+					if (message?.type === REVOKE_TYPE) {
+						const grant = revokedGrant(message.data);
+						[...connections].filter((member) => {
+							const opened = member.grants.get(message.topic);
+							return opened !== void 0 && (grant === void 0 || opened === grant);
+						}).forEach((member) => void releaseTopic(member, message.topic));
+					} else if (message) connections.forEach((member) => member.send("message", message));
+				})
+			};
+			local.set(key, entry);
+		}
+		entry.connections.add(connection);
+		await entry.release;
+	};
+	const leave = async (connection, topic) => {
+		const key = adapterTopic(connection.space, topic);
+		const entry = local.get(key);
+		if (!entry) return;
+		entry.connections.delete(connection);
+		if (entry.connections.size === 0) {
+			local.delete(key);
+			await (await entry.release)();
+		}
+	};
+	/** A stamped message from this connection: `from` and `user` are the server's, whatever was sent. */
+	const from = (connection, topic, type, data) => ({
+		topic,
+		type,
+		data,
+		from: connection.id,
+		...connection.user ? { user: connection.user } : {},
+		at: Date.now()
+	});
+	/**
+	* Lets `connection` go of `topic`: it is told, the others on a presence channel hear it leave, and it no longer
+	* hears the topic or may send on it.
+	*/
+	const releaseTopic = async (connection, topic) => {
+		connection.send("message", {
+			topic,
+			type: REVOKED_TYPE,
+			data: null,
+			from: "server",
+			at: Date.now()
+		});
+		connection.topics.delete(topic);
+		connection.grants.delete(topic);
+		await leave(connection, topic);
+		if (connection.announced.delete(topic)) await publish(connection.space, from(connection, topic, LEAVE_TYPE, null));
+	};
+	return {
+		publish,
+		from,
+		find: (token) => byToken.get(token),
+		/**
+		* Lets go of `topic` every connection, on every replica, that opened it with `grant` — or with any grant, naming
+		* none. What stops a grant that is already in use; `grants.revoke` is what stops it being used again.
+		*/
+		revoke: (space, topic, grant) => publish(space, {
+			topic,
+			type: REVOKE_TYPE,
+			data: grant === void 0 ? null : { grant },
+			from: "server",
+			at: Date.now()
+		}),
+		/** Subscribes a new connection to its topics, and tells the members of each presence channel it arrived. */
+		connect: async (connection) => {
+			byToken.set(connection.token, connection);
+			for (const [topic, declaration] of connection.topics) {
+				await join(connection, topic);
+				if (declaration.presence) await publish(connection.space, from(connection, topic, JOIN_TYPE, null));
+			}
+		},
+		/** Unsubscribes a connection that went away, and tells the channels it announced itself on. */
+		disconnect: async (connection) => {
+			byToken.delete(connection.token);
+			for (const topic of connection.topics.keys()) {
+				if (connection.announced.has(topic)) await publish(connection.space, from(connection, topic, LEAVE_TYPE, null));
+				await leave(connection, topic);
+			}
+		},
+		/**
+		* Every connection closed from here: the server is shutting down. An open socket or event stream is a request that
+		* never ends, so a server waiting for them to finish waited for ever — each is told to go, and goes the way it
+		* goes when its page leaves.
+		*/
+		closeAll: () => {
+			[...byToken.values()].forEach((connection) => connection.end());
+		},
+		/** How many connections this process holds — for tests and for a health endpoint. */
+		get connectionCount() {
+			return byToken.size;
+		},
+		/** How many topics this process holds a subscription for — for tests and for a health endpoint. */
+		get topicCount() {
+			return local.size;
+		}
+	};
+};
+//#endregion
+export { adapterTopic, createRealtimeHub };

package/dist/modules/realtime/index.d.ts

@@ -0,0 +1,51 @@
+import { ChannelResolver } from './declarations';
+import { RealtimeGrants } from './grants';
+import { RealtimeHub } from './hub';
+import { RealtimeTransport, SSRServerConfig } from '@plitzi/sdk-shared';
+export { createMemoryPubSub } from './memoryPubSub';
+export { handleRealtimePublish, handleRealtimeSubscribe } from './handlers';
+export { handleRealtimeSocket } from './socket';
+export type RealtimeModule = {
+    hub: RealtimeHub;
+    path: string;
+    /** What pages are told to connect with. Both are served whatever this says. */
+    transport: RealtimeTransport;
+    /** Origins besides the server's own whose pages may open a socket. */
+    allowedOrigins: readonly string[];
+    resolveChannels: ChannelResolver;
+    /** The grants issued for topics of channels declared `grant: true`, and the check a subscription makes. */
+    grants: RealtimeGrants;
+    /** Closes every connection this process holds: the server is shutting down (`HttpServerParts.onClosing`). */
+    close: () => void;
+    /**
+     * Publishes from the server — what a flow's `realtime.publish` does. Checked against the space's channels like a
+     * page's publish, and sent `from: 'server'`: the one sender a page cannot be.
+     */
+    publish: (space: {
+        spaceId: number;
+        environment: string;
+    }, topic: string, type: string, data: unknown) => Promise<void>;
+    /**
+     * A grant for one topic of a channel declared `grant: true` — what a flow's `realtime.grant` hands a page, once it
+     * has decided the visitor may be there. Refused for a topic of any other channel: a grant it would never ask for
+     * is a mistake in the flow, not a key to hand out.
+     */
+    grant: (space: {
+        spaceId: number;
+        environment: string;
+    }, topic: string, ttlSeconds?: number) => Promise<string>;
+    /**
+     * `grant` no longer opens `topic` — or, naming none, no grant issued for it until now does: nobody who holds one gets
+     * in again, and whoever is on the topic with one, on any replica, is let go of it (`$revoked`). A page kept out asks
+     * the action that lets it in for a new grant, if it still may.
+     */
+    revoke: (space: {
+        spaceId: number;
+        environment: string;
+    }, topic: string, grant?: string) => Promise<void>;
+};
+/**
+ * The server's realtime channels, built once per config — or `undefined` when they are off or cannot be: without the
+ * space's documents (`getOfflineData`) there is nothing to say which channels a space declares, so none is opened.
+ */
+export declare const realtimeModuleFor: (config: SSRServerConfig) => RealtimeModule | undefined;

package/dist/modules/realtime/index.js

@@ -0,0 +1,62 @@
+import { fleetStore } from "../../core/server/fleet/link.js";
+import { KV_METHODS, createMemoryKv } from "../actions/runtime/memoryKv.js";
+import { createRealtimeGrants } from "./grants.js";
+import { createChannelResolver } from "./declarations.js";
+import { createRealtimeHub } from "./hub.js";
+import { createMemoryPubSub } from "./memoryPubSub.js";
+import { handleRealtimePublish, handleRealtimeSubscribe } from "./handlers.js";
+import { handleRealtimeSocket } from "./socket.js";
+import { matchChannel } from "@plitzi/sdk-shared/realtime";
+//#region src/modules/realtime/index.ts
+/** A type a flow publishes: its own vocabulary — the `$` types are the channel's. */
+var SERVER_TYPE = /^[A-Za-z0-9_.:-]{1,64}$/;
+var modules = /* @__PURE__ */ new WeakMap();
+/**
+* The server's realtime channels, built once per config — or `undefined` when they are off or cannot be: without the
+* space's documents (`getOfflineData`) there is nothing to say which channels a space declares, so none is opened.
+*/
+var realtimeModuleFor = (config) => {
+	const getOfflineData = config.adapters.getOfflineData;
+	if (config.realtime === false || !getOfflineData) return;
+	const existing = modules.get(config);
+	if (existing) return existing;
+	const hub = createRealtimeHub(config.realtime?.pubsub ?? createMemoryPubSub());
+	const resolveChannels = createChannelResolver(getOfflineData);
+	const grants = createRealtimeGrants(config.action?.kv ?? fleetStore("realtime.grants", KV_METHODS) ?? createMemoryKv());
+	const module = {
+		hub,
+		path: config.realtime?.path ?? "/_realtime",
+		transport: config.realtime?.transport ?? "sse",
+		allowedOrigins: config.realtime?.allowedOrigins ?? [],
+		resolveChannels,
+		grants,
+		close: () => hub.closeAll(),
+		publish: async (space, topic, type, data) => {
+			const channels = await resolveChannels(space.spaceId, space.environment);
+			if (!matchChannel(topic, channels)) throw new Error(`No channel of this space matches "${topic}": declare it in the space's \`channels\``);
+			if (!SERVER_TYPE.test(type)) throw new Error("A message type is 1-64 of A-Z a-z 0-9 _ . : -");
+			await hub.publish(space, {
+				topic,
+				type,
+				data,
+				from: "server",
+				at: Date.now()
+			});
+		},
+		grant: async (space, topic, ttlSeconds) => {
+			const match = matchChannel(topic, await resolveChannels(space.spaceId, space.environment));
+			if (!match) throw new Error(`No channel of this space matches "${topic}": declare it in the space's \`channels\``);
+			if (match.declaration.grant !== true) throw new Error(`"${match.pattern}" is open to anyone its access lets in, so it takes no grant: declare it \`grant: true\` to make its topics private`);
+			return grants.issue(space, topic, ttlSeconds);
+		},
+		revoke: async (space, topic, grant) => {
+			if (matchChannel(topic, await resolveChannels(space.spaceId, space.environment))?.declaration.grant !== true) throw new Error(`"${topic}" is not a topic of a private (\`grant: true\`) channel of this space: it has no grants to revoke`);
+			await grants.revoke(space, topic, grant);
+			await hub.revoke(space, topic, grant);
+		}
+	};
+	modules.set(config, module);
+	return module;
+};
+//#endregion
+export { handleRealtimePublish, handleRealtimeSocket, handleRealtimeSubscribe, realtimeModuleFor };

package/dist/modules/realtime/memoryPubSub.d.ts

@@ -0,0 +1,10 @@
+import { PubSubAdapter } from '@plitzi/sdk-shared';
+/**
+ * The default pub/sub: in this process, and across its workers.
+ *
+ * A page connected to one worker must hear what another worker published, so a publish is delivered here AND sent to
+ * the rest of the fleet as a broadcast, which each process delivers to its own listeners. Without workers the
+ * broadcast goes nowhere and this is a Map of listeners. A second REPLICA shares nothing with this one: a deployment
+ * that runs several hands the server an adapter over something shared (Redis, NATS…).
+ */
+export declare const createMemoryPubSub: () => PubSubAdapter;

package/dist/modules/realtime/memoryPubSub.js

@@ -0,0 +1,43 @@
+import { broadcast, channelName, onBroadcast } from "../../core/server/fleet/link.js";
+//#region src/modules/realtime/memoryPubSub.ts
+var isRelayed = (value) => typeof value === "object" && value !== null && "topic" in value && typeof value.topic === "string" && "message" in value && typeof value.message === "string";
+/**
+* The default pub/sub: in this process, and across its workers.
+*
+* A page connected to one worker must hear what another worker published, so a publish is delivered here AND sent to
+* the rest of the fleet as a broadcast, which each process delivers to its own listeners. Without workers the
+* broadcast goes nowhere and this is a Map of listeners. A second REPLICA shares nothing with this one: a deployment
+* that runs several hands the server an adapter over something shared (Redis, NATS…).
+*/
+var createMemoryPubSub = () => {
+	const topics = /* @__PURE__ */ new Map();
+	const fleet = channelName("realtime.pubsub");
+	const deliver = (topic, message) => {
+		for (const listener of topics.get(topic) ?? []) listener(message);
+	};
+	onBroadcast(fleet, (payload) => {
+		if (isRelayed(payload)) deliver(payload.topic, payload.message);
+	});
+	return {
+		publish: (topic, message) => {
+			deliver(topic, message);
+			broadcast(fleet, {
+				topic,
+				message
+			});
+			return Promise.resolve();
+		},
+		subscribe: (topic, listener) => {
+			const listeners = topics.get(topic) ?? /* @__PURE__ */ new Set();
+			listeners.add(listener);
+			topics.set(topic, listeners);
+			return Promise.resolve(() => {
+				listeners.delete(listener);
+				if (listeners.size === 0) topics.delete(topic);
+				return Promise.resolve();
+			});
+		}
+	};
+};
+//#endregion
+export { createMemoryPubSub };

package/dist/modules/realtime/realtime.test.d.ts

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

package/dist/modules/realtime/redisPubSub.d.ts

@@ -0,0 +1,24 @@
+import { PubSubAdapter } from '@plitzi/sdk-shared';
+/**
+ * The two Redis connections pub/sub needs, by shape — `ioredis` fits as it is, and so does anything answering the same
+ * calls. A connection in subscriber mode can do nothing else, which is why it is a second one.
+ */
+export type RedisPubSubClients = {
+    publisher: {
+        publish: (channel: string, message: string) => Promise<unknown>;
+    };
+    subscriber: {
+        subscribe: (channel: string) => Promise<unknown>;
+        unsubscribe: (channel: string) => Promise<unknown>;
+        on: (event: 'message', listener: (channel: string, message: string) => void) => unknown;
+    };
+    /** Prefixed onto every channel, so the realtime topics cannot collide with anything else on the server. */
+    prefix?: string;
+};
+/**
+ * Pub/sub over Redis: what a deployment of several replicas hands `createServer({ realtime: { pubsub } })`.
+ *
+ * One Redis subscription per topic per process, however many pages of that process listen to it: the listeners are
+ * kept here, and the channel is subscribed on the first and unsubscribed with the last.
+ */
+export declare const createRedisPubSub: ({ publisher, subscriber, prefix }: RedisPubSubClients) => PubSubAdapter;

package/dist/modules/realtime/redisPubSub.js

@@ -0,0 +1,36 @@
+//#region src/modules/realtime/redisPubSub.ts
+/**
+* Pub/sub over Redis: what a deployment of several replicas hands `createServer({ realtime: { pubsub } })`.
+*
+* One Redis subscription per topic per process, however many pages of that process listen to it: the listeners are
+* kept here, and the channel is subscribed on the first and unsubscribed with the last.
+*/
+var createRedisPubSub = ({ publisher, subscriber, prefix = "plitzi:rt:" }) => {
+	const listeners = /* @__PURE__ */ new Map();
+	subscriber.on("message", (channel, message) => {
+		if (!channel.startsWith(prefix)) return;
+		listeners.get(channel.slice(prefix.length))?.forEach((listener) => listener(message));
+	});
+	return {
+		publish: async (topic, message) => {
+			await publisher.publish(`${prefix}${topic}`, message);
+		},
+		subscribe: async (topic, listener) => {
+			const set = listeners.get(topic) ?? /* @__PURE__ */ new Set();
+			if (!set.size) {
+				listeners.set(topic, set);
+				await subscriber.subscribe(`${prefix}${topic}`);
+			}
+			set.add(listener);
+			return async () => {
+				set.delete(listener);
+				if (!set.size) {
+					listeners.delete(topic);
+					await subscriber.unsubscribe(`${prefix}${topic}`);
+				}
+			};
+		}
+	};
+};
+//#endregion
+export { createRedisPubSub };

package/dist/modules/realtime/redisPubSub.test.d.ts

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

package/dist/modules/realtime/socket.d.ts

@@ -0,0 +1,25 @@
+import { ChannelResolver } from './declarations';
+import { RealtimeGrants } from './grants';
+import { RealtimeHub } from './hub';
+import { UpgradeRequest } from '../../core/http/socketResponse';
+import { SSRRequest, SSRResponseHelpers } from '@plitzi/sdk-shared';
+import { IncomingMessage } from 'node:http';
+export type SocketDeps = {
+    req: SSRRequest;
+    res: SSRResponseHelpers;
+    raw: IncomingMessage;
+    upgrade: UpgradeRequest;
+    hub: RealtimeHub;
+    resolveChannels: ChannelResolver;
+    grants: RealtimeGrants;
+    allowedOrigins: readonly string[];
+};
+/**
+ * A page's realtime connection as a WebSocket: the same topics, rules and messages as the Server-Sent Events one, in
+ * both directions over one socket. A publish is a frame, not a request — no headers, no second connection, no token
+ * to present: the socket is the credential. Its answer arrives as an `ack` carrying the publish's `id`.
+ *
+ * Refused the way the stream is — a `403` or a `422`, in HTTP, before anything switches — so a page falls back or
+ * reports it exactly as it would there.
+ */
+export declare const handleRealtimeSocket: ({ req, res, raw, upgrade, hub, resolveChannels, grants, allowedOrigins }: SocketDeps) => Promise<void>;

package/dist/modules/realtime/socket.js

@@ -0,0 +1,122 @@
+import { admit, answer, connectionFor, publishFrom } from "./handlers.js";
+import { requestOrigin } from "../../core/requestParser.js";
+import { frameText } from "../../helpers/wsFrame.js";
+//#region src/modules/realtime/socket.ts
+/** The largest frame a page may send: well above the largest message a channel may declare, and bounded. */
+var MAX_FRAME_BYTES = 262144;
+/**
+* What may wait in a socket's buffer for a page that stopped reading. Past it the page is gone in all but name, and
+* holding everything it has not read is how one stalled tab grows a process.
+*/
+var MAX_BUFFERED_BYTES = 1048576;
+/** How often the server asks a socket whether the page behind it is still there — and gives up on one that did not answer the last time. */
+var PING_MS = 25e3;
+var server;
+/**
+* Loaded the first time a page asks for a socket: a server whose pages never do — or that runs behind HTTP/2, where
+* none can — never pays for the module.
+*/
+var socketServer = () => server ??= import("ws").then(({ WebSocketServer: Server }) => new Server({
+	noServer: true,
+	maxPayload: MAX_FRAME_BYTES
+}));
+/**
+* A browser opens a WebSocket to any address, carrying that address's cookies, from any page — CORS does not apply to
+* it. So a socket is refused unless the page that opened it is on this origin, or on one the deployment lists: without
+* this, another site could open a channel restricted to signed-in visitors with a visitor's session and read it.
+* A client that is not a browser sends no `Origin`, and has no visitor's cookies to borrow.
+*/
+var originAllowed = (raw, req, allowed) => {
+	const origin = raw.headers.origin;
+	return origin === void 0 || origin === requestOrigin(req) || allowed.includes(origin);
+};
+/** A frame's text, whichever of the shapes `ws` hands a frame over in. */
+var parse = (frame) => {
+	try {
+		const value = JSON.parse(frameText(frame));
+		return typeof value === "object" && value !== null ? value : void 0;
+	} catch {
+		return;
+	}
+};
+/** A publish's id, echoed on its `ack`: what the page matches the answer to. Short, and never anything else. */
+var ackId = (id) => typeof id === "number" && Number.isInteger(id) || typeof id === "string" && id.length <= 64 ? id : void 0;
+/**
+* A page's realtime connection as a WebSocket: the same topics, rules and messages as the Server-Sent Events one, in
+* both directions over one socket. A publish is a frame, not a request — no headers, no second connection, no token
+* to present: the socket is the credential. Its answer arrives as an `ack` carrying the publish's `id`.
+*
+* Refused the way the stream is — a `403` or a `422`, in HTTP, before anything switches — so a page falls back or
+* reports it exactly as it would there.
+*/
+var handleRealtimeSocket = async ({ req, res, raw, upgrade, hub, resolveChannels, grants, allowedOrigins }) => {
+	if (!originAllowed(raw, req, allowedOrigins)) {
+		answer(res, {
+			status: 403,
+			error: "A page on another site may not open this",
+			reason: "foreign"
+		});
+		return;
+	}
+	const admission = await admit(req, resolveChannels, grants);
+	if (!admission.ok) {
+		answer(res, admission.answer);
+		return;
+	}
+	const sockets = await socketServer();
+	upgrade.taken = true;
+	res.setStatus(101);
+	sockets.handleUpgrade(raw, upgrade.socket, upgrade.head, (socket) => {
+		const send = (event, data) => {
+			if (socket.readyState !== socket.OPEN) return;
+			if (socket.bufferedAmount > MAX_BUFFERED_BYTES) {
+				socket.terminate();
+				return;
+			}
+			socket.send(JSON.stringify({
+				event,
+				data
+			}));
+		};
+		const connection = connectionFor(admission, send, () => socket.close(1001, "The server is going away"));
+		let alive = true;
+		const heartbeat = setInterval(() => {
+			if (!alive) {
+				socket.terminate();
+				return;
+			}
+			alive = false;
+			socket.ping();
+		}, PING_MS);
+		socket.on("pong", () => {
+			alive = true;
+		});
+		socket.on("message", (frame, binary) => {
+			alive = true;
+			const message = binary ? void 0 : parse(frame);
+			if (!message) return;
+			const id = ackId(message.id);
+			publishFrom(hub, connection, message).then((result) => {
+				if (id !== void 0) send("ack", {
+					id,
+					ok: result.status === 204,
+					status: result.status,
+					...result.reason ? { reason: result.reason } : {}
+				});
+			});
+		});
+		socket.on("close", () => {
+			clearInterval(heartbeat);
+			hub.disconnect(connection);
+		});
+		socket.on("error", () => socket.terminate());
+		send("ready", {
+			connection: connection.id,
+			topics: [...admission.accepted.keys()],
+			refused: admission.refused
+		});
+		hub.connect(connection);
+	});
+};
+//#endregion
+export { handleRealtimeSocket };

package/dist/modules/realtime/socket.test.d.ts

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

package/dist/modules/rsc/handler.d.ts

@@ -1,6 +1,22 @@
 import { TtlCache } from '../../helpers/cache';
 import { PluginManager } from '../../plugins/manager';
 import { SSRPageServerConfig, SSRRequest, SSRResponseHelpers } from '@plitzi/sdk-shared';
+/**
+ * Rewrites the request to the page the browser is actually on.
+ *
+ * A refresh is issued against `/_rsc`, not against `/blog/my-post`, so resolving straight from `req.path` matches
+ * nothing in `schema.pages` and every client-side refresh silently returns no data. The SDK sends the visitor's
+ * location as `?location=`, and route params plus the page parameter are read from that instead.
+ *
+ * What a refresh asks for besides — the next page of a "load more", a search a provider was reloaded with — rides on
+ * the query string beside `location`, and is read over the location's own query. It used to be dropped with the rest
+ * of the endpoint's query, so a provider paged in place was answered its first page every time.
+ *
+ * Reflecting both is safe by construction: the location is matched against this space's own page list, and the rest
+ * is what the same visitor could have put in the page's own address; the cache key is the whole request, so no answer
+ * is served for a query it was not made for.
+ */
+export declare const withPageLocation: (req: SSRRequest) => SSRRequest;
 /**
  * Handles GET /_rsc requests.
  *

package/dist/modules/rsc/handler.js

@@ -1,3 +1,4 @@
+import { serverLog } from "../../helpers/serverLog.js";
 import { resolveDebugAuthorization } from "../../helpers/debugAuthorization.js";
 import { DEFAULT_TTL_MS } from "../../helpers/cache/defaults.js";
 import { buildRscCacheKey } from "../../helpers/cache/keys.js";
@@ -19,6 +20,8 @@ var meterRsc = async (req, config, spaceId, environment, revision, cached) => {
 		});
 	} catch {}
 };
+/** The endpoint's own parameters: what it is asked about, never input to what it resolves. */
+var ENDPOINT_PARAMS = /* @__PURE__ */ new Set(["location", "ids"]);
 /**
 * Rewrites the request to the page the browser is actually on.
 *
@@ -26,22 +29,26 @@ var meterRsc = async (req, config, spaceId, environment, revision, cached) => {
 * nothing in `schema.pages` and every client-side refresh silently returns no data. The SDK sends the visitor's
 * location as `?location=`, and route params plus the page parameter are read from that instead.
 *
-* Reflecting it is safe by construction: it is matched against this space's own page list, so the worst a forged
-* value can do is resolve a page the same visitor could have loaded directly.
+* What a refresh asks for besides — the next page of a "load more", a search a provider was reloaded with — rides on
+* the query string beside `location`, and is read over the location's own query. It used to be dropped with the rest
+* of the endpoint's query, so a provider paged in place was answered its first page every time.
+*
+* Reflecting both is safe by construction: the location is matched against this space's own page list, and the rest
+* is what the same visitor could have put in the page's own address; the cache key is the whole request, so no answer
+* is served for a query it was not made for.
 */
 var withPageLocation = (req) => {
 	const location = req.query.location;
 	if (!location || !location.startsWith("/") || location.length > MAX_PAGE_LOCATION) return req;
 	const url = new URL(location, `${req.protocol}://${req.hostname}`);
-	const query = [...url.searchParams.entries()].reduce((acum, [key, value]) => {
-		acum[key] = value;
-		return acum;
-	}, {});
+	const asked = Object.entries(req.query).filter(([key]) => !ENDPOINT_PARAMS.has(key));
+	const query = Object.fromEntries([...url.searchParams.entries(), ...asked]);
+	const search = new URLSearchParams(query).toString();
 	return {
 		...req,
 		path: url.pathname,
-		search: url.search,
-		url: `${url.pathname}${url.search}`,
+		search: search ? `?${search}` : "",
+		url: `${url.pathname}${search ? `?${search}` : ""}`,
 		query
 	};
 };
@@ -112,7 +119,7 @@ var handleRsc = async (req, res, config, _pluginManager, cache) => {
 			loadOfflineData
 		});
 	} catch (err) {
-		console.error("[RSC] getRscData error:", err);
+		serverLog.error("RSC", "getRscData error", err);
 		res.setStatus(500);
 		res.send(JSON.stringify({ error: "RSC data fetch failed" }));
 		return;
@@ -135,4 +142,4 @@ var handleRsc = async (req, res, config, _pluginManager, cache) => {
 	res.send(payloadStr);
 };
 //#endregion
-export { handleRsc };
+export { handleRsc, withPageLocation };

package/dist/modules/rsc/handler.test.d.ts

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

package/dist/modules/rsc/resolveRscData.js

@@ -1,3 +1,4 @@
+import { serverLog } from "../../helpers/serverLog.js";
 import { matchRscPage } from "./matchRscPage.js";
 import { collectServerElements } from "@plitzi/sdk-shared/schema/serverElements";
 //#region src/modules/rsc/resolveRscData.ts
@@ -52,7 +53,7 @@ var resolveRscData = async ({ schema, req, spaceId, environment, user, ids, reso
 		}), timeoutMs, `element ${element.id}`)
 	})))).reduce((acum, result, index) => {
 		if (result.status === "rejected") {
-			console.error(`[RSC] element ${targets[index].id} failed to resolve:`, result.reason);
+			serverLog.error("RSC", `element ${targets[index].id} failed to resolve`, result.reason);
 			return acum;
 		}
 		if (result.value.data !== void 0) acum[result.value.id] = result.value.data;

package/dist/modules/runtime/bundle.d.ts

@@ -0,0 +1,24 @@
+import { SpaceRuntime } from './contract';
+/** A packed runtime at most this big: its code and every dependency, not its data. */
+export declare const MAX_RUNTIME_BUNDLE_BYTES: number;
+/** A bundle's id: what its bytes are, so the same code packed twice is one bundle. */
+export declare const runtimeBundleId: (bytes: Uint8Array) => string;
+/**
+ * A runtime's module packed to travel: bundled for Node with every dependency it imports — but the platform's packages
+ * and React, which the host provides, so there is one copy of each — and gzipped. `entry` is the module whose default
+ * export is `defineRuntime(…)`.
+ */
+export declare const packRuntime: (entry: string) => Promise<Uint8Array>;
+/**
+ * What a packed runtime holds, read without running any of it — what a platform checks a bundle with before keeping it.
+ * Throws, saying why, for bytes that are not one.
+ */
+export declare const inspectRuntime: (bytes: Uint8Array) => {
+    entry: string;
+    files: string[];
+};
+/**
+ * A packed runtime written into `dir` and imported: its module's default export. `dir` must be inside the host's own
+ * project, so the packages the bundle leaves to the host resolve to the host's — one copy of each.
+ */
+export declare const loadRuntime: (bytes: Uint8Array, dir: string) => Promise<SpaceRuntime>;