@plitzi/sdk-server 0.37.2 → 0.37.4

package/dist/core/server/fleet/supervisor.js

@@ -0,0 +1,108 @@
+import { serverLog } from "../../../helpers/serverLog.js";
+import { fleetWorkerEnv } from "./role.js";
+import { startHub } from "./link.js";
+import { FLEET_STORES } from "./stores.js";
+import cluster from "node:cluster";
+//#region src/core/server/fleet/supervisor.ts
+var RESTART_WINDOW_MS = 6e4;
+var RESTART_BASE_MS = 500;
+var RESTART_MAX_MS = 3e4;
+/**
+* How long the replacement for a dead worker waits, given how many have died in the last minute. As many deaths as
+* there are workers — each of them crashing once — are replaced at once; past that it doubles from half a second, up
+* to thirty.
+*/
+var restartDelay = (deathsInWindow, count) => deathsInWindow <= count ? 0 : Math.min(RESTART_MAX_MS, RESTART_BASE_MS * 2 ** (deathsInWindow - count - 1));
+/** One fleet per process: a second server in the same primary shares the workers the first one started. */
+var shared;
+var exitOf = (code, signal) => signal ? `signal ${signal}` : `code ${code}`;
+/**
+* Starts `count` workers from this primary, each running the process's own entry point — so each builds and binds
+* its own server on the shared port, and the connections are spread between them.
+*
+* A worker that dies is replaced, crash or kill alike, and the replacement takes over whatever the dead one carried
+* (the jobs). Past one death per worker a minute the replacements wait, longer each time (`restartDelay`), so a
+* request that crashes whichever worker takes it cannot turn the primary into a fork loop.
+*
+* Until the fleet has served at all, a death is not retried: a worker that dies before any has listened would die
+* the same way again — a port in use, a broken build — so the fleet stops and the process exits non-zero for
+* whatever supervises it. Once it has served, a replacement that fails to start is retried like any other death:
+* the workers still serving keep serving through a passing failure (a database that is briefly down).
+*
+* `stop` asks every worker to finish with SIGTERM (what `closeOnSignals` answers) and waits for all of them. A
+* primary that dies without stopping them takes them with it: a worker exits when its channel to the primary closes.
+*/
+var startFleet = (count, label, exit = (code) => process.exit(code)) => {
+	if (shared) {
+		if (shared.count !== count) throw new Error(`[${label}] this process already runs ${shared.count} workers; every server in it must ask for the same number`);
+		shared.servers += 1;
+		const state = shared;
+		return { stop: () => leave(state) };
+	}
+	const workers = /* @__PURE__ */ new Set();
+	const restarts = /* @__PURE__ */ new Set();
+	/** When workers died, over the last minute: what decides how long the next replacement waits. */
+	let deaths = [];
+	let served = false;
+	let stopping = false;
+	const stopAll = () => {
+		restarts.forEach((timer) => clearTimeout(timer));
+		restarts.clear();
+		return Promise.all([...workers].map((worker) => new Promise((resolve) => {
+			if (worker.isDead()) {
+				resolve();
+				return;
+			}
+			worker.once("exit", () => resolve());
+			worker.process.kill("SIGTERM");
+		}))).then(() => void 0);
+	};
+	const fork = (runsJobs) => {
+		const worker = cluster.fork(fleetWorkerEnv(runsJobs));
+		workers.add(worker);
+		worker.once("listening", () => {
+			served = true;
+		});
+		worker.once("exit", (code, signal) => {
+			workers.delete(worker);
+			if (stopping) return;
+			if (!served) {
+				serverLog.error(label, `a worker stopped before it could serve (${exitOf(code, signal)}); stopping the rest`);
+				stopping = true;
+				stopAll().then(() => exit(1));
+				return;
+			}
+			const now = Date.now();
+			deaths = [...deaths.filter((at) => now - at < RESTART_WINDOW_MS), now];
+			const delayMs = restartDelay(deaths.length, count);
+			serverLog.error(label, `worker ${worker.process.pid ?? "?"} stopped (${exitOf(code, signal)}); starting another` + (delayMs > 0 ? ` in ${delayMs}ms — ${deaths.length} have stopped in the last minute` : ""));
+			const timer = setTimeout(() => {
+				restarts.delete(timer);
+				if (!stopping) fork(runsJobs);
+			}, delayMs);
+			restarts.add(timer);
+		});
+	};
+	cluster.setupPrimary({ serialization: "advanced" });
+	startHub(FLEET_STORES);
+	for (let index = 0; index < count; index += 1) fork(index === 0);
+	const state = {
+		count,
+		servers: 1,
+		stop: async () => {
+			stopping = true;
+			await stopAll();
+		}
+	};
+	shared = state;
+	return { stop: () => leave(state) };
+};
+/** The workers stop when the last server of this process that started them closes. */
+var leave = async (state) => {
+	state.servers -= 1;
+	if (state.servers > 0) return;
+	if (shared === state) shared = void 0;
+	await state.stop();
+};
+//#endregion
+export { restartDelay, startFleet };

package/dist/core/server/fleet/supervisor.test.d.ts

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

package/dist/core/server/pageServer.js

@@ -1,11 +1,16 @@
+import { configureServerLog, defaultLogLevel, isLogged, logLevelOf } from "../../helpers/serverLog.js";
+import { runsFleetJobs } from "./fleet/role.js";
+import { fleetStore } from "./fleet/link.js";
+import { realtimeModuleFor } from "../../modules/realtime/index.js";
 import { actionsModuleFor } from "../../modules/actions/moduleFor.js";
 import { createHttpServer } from "./baseServer.js";
 import { DEFAULT_TTL_MS } from "../../helpers/cache/defaults.js";
 import { buildCacheManager } from "../../helpers/cache/cacheManager.js";
 import { createServerCaches, destroyServerCaches } from "../../helpers/cache/serverCaches.js";
 import normalizePlugins, { normalizePluginSource } from "../../helpers/normalizePlugins.js";
+import { reportReactBuild } from "../../helpers/reportReactBuild.js";
 import { invalidatePluginComponentCache } from "../../modules/ssr/loadPluginComponents.js";
-import { createMemoryDraftStore } from "../../modules/ssr/preview.js";
+import { DRAFT_STORE_METHODS, createMemoryDraftStore } from "../../modules/ssr/preview.js";
 import { compileTemplate } from "../../modules/ssr/template.js";
 import { PluginManager } from "../../plugins/manager.js";
 import { makeHandler } from "../http/dispatcher.js";
@@ -16,7 +21,18 @@ import { buildPagePipeline } from "../services/registry.js";
 *  enables — so this unit never second-guesses a factory's promise. */
 var createPageServer = (config, services, extensions) => {
 	const { cacheTtlMs: htmlTtlMs = DEFAULT_TTL_MS.html } = config;
-	if (config.preview?.enabled && !config.draftStore) config.draftStore = createMemoryDraftStore();
+	const logLevel = config.logLevel ?? defaultLogLevel(config.devMode);
+	const { logger } = config;
+	config.logLevel = logLevel;
+	if (logger) config.logger = (event) => {
+		if (isLogged(logLevel, logLevelOf(event))) logger(event);
+	};
+	configureServerLog({
+		level: logLevel,
+		logger
+	});
+	reportReactBuild(config.devMode);
+	if (config.preview?.enabled && !config.draftStore) config.draftStore = fleetStore("ssr.drafts", DRAFT_STORE_METHODS) ?? createMemoryDraftStore();
 	const caches = createServerCaches(htmlTtlMs, config.rsc?.cacheTtlMs ?? DEFAULT_TTL_MS.rsc);
 	const cache = caches.html ? buildCacheManager(caches.html) : null;
 	const renderFn = config.templateFn ?? compileTemplate();
@@ -32,6 +48,7 @@ var createPageServer = (config, services, extensions) => {
 		}
 	};
 	const actions = actionsModuleFor(config);
+	const realtime = realtimeModuleFor(config);
 	const stages = buildPagePipeline(services, extensions);
 	const makeHandlerForPort = (port) => {
 		const buildContext = (raw, rawRes, req, res) => ({
@@ -44,15 +61,27 @@ var createPageServer = (config, services, extensions) => {
 			renderFn,
 			caches,
 			pluginManager,
-			actions
+			actions,
+			realtime
+		});
+		return makeHandler("SSR", buildContext, stages, {
+			compression: config.compression,
+			...realtime ? { upgrades: (path) => path === realtime.path } : {}
 		});
-		return makeHandler("SSR", buildContext, stages, config.compression);
 	};
 	return createHttpServer(config, makeHandlerForPort, {
 		label: "SSR",
 		cache,
 		plugins,
-		onListen: () => actions?.jobs?.start(),
+		onListen: () => {
+			if (runsFleetJobs()) actions?.jobs?.start();
+		},
+		beforeFork: () => pluginManager.prepareAll(),
+		forgetPlugins: (name, version) => {
+			pluginManager.forget(name, version);
+			invalidatePluginComponentCache();
+		},
+		onClosing: () => realtime?.close(),
 		onDestroy: async () => {
 			await actions?.jobs?.stop();
 			destroyServerCaches(caches);

package/dist/core/services/action.js

@@ -47,9 +47,17 @@ var actionStage = async (ctx) => {
 			ctx.res.send("");
 			return true;
 		}
-		handleActionCatalog({
+		const { spaceId, environment = "main", revision = 0 } = req.ctx.spaceDeployment ?? {};
+		await handleActionCatalog({
 			res: ctx.res,
-			module: actions
+			module: actions,
+			...typeof spaceId === "number" ? {
+				spaceId,
+				at: {
+					environment,
+					revision
+				}
+			} : {}
 		});
 		return true;
 	}

package/dist/core/services/functionRoutes.d.ts

@@ -0,0 +1,9 @@
+import { SSRContext, Stage } from '../http/types';
+/**
+ * The space's functions answering HTTP under `/api/`: a request there that a declared route answers is run
+ * by it — the deployment's own routes first, then the space's, in the sandbox — and anything else goes on to the page
+ * server, which answers as it would have. `/api` is never a page: its slug is refused, so the path is the functions'.
+ *
+ * After the auth chain, so `ctx.user` is who the session says; the session itself never reaches the code.
+ */
+export declare const functionRoutesStage: Stage<SSRContext>;

package/dist/core/services/functionRoutes.js

@@ -0,0 +1,47 @@
+import { clientIp, readRawBytes, requestOrigin } from "../requestParser.js";
+import { FUNCTION_ROUTES_PREFIX } from "@plitzi/sdk-shared/actions";
+//#region src/core/services/functionRoutes.ts
+/**
+* The space's functions answering HTTP under `/api/`: a request there that a declared route answers is run
+* by it — the deployment's own routes first, then the space's, in the sandbox — and anything else goes on to the page
+* server, which answers as it would have. `/api` is never a page: its slug is refused, so the path is the functions'.
+*
+* After the auth chain, so `ctx.user` is who the session says; the session itself never reaches the code.
+*/
+var functionRoutesStage = async (ctx) => {
+	const { req, actions } = ctx;
+	const { spaceId, environment = "main", revision = 0 } = req.ctx.spaceDeployment ?? {};
+	if (!actions || typeof spaceId !== "number" || !req.path.startsWith(`${FUNCTION_ROUTES_PREFIX}/`)) return false;
+	const route = await actions.routeFor({
+		spaceId,
+		environment,
+		at: {
+			environment,
+			revision
+		},
+		...req.ctx.user ? { user: req.ctx.user } : {},
+		callerId: req.ctx.user ? `user:${String(req.ctx.user.id)}` : `ip:${clientIp(ctx.raw, req)}`,
+		signal: ctx.signal
+	}, req.method, req.path.slice(FUNCTION_ROUTES_PREFIX.length));
+	if (!route) return false;
+	ctx.operation = "function:route";
+	const headers = new Headers();
+	Object.entries(req.headers).forEach(([name, value]) => {
+		if (!name.startsWith(":") && value !== void 0) headers.set(name, Array.isArray(value) ? value.join(", ") : value);
+	});
+	const hasBody = req.method !== "GET" && req.method !== "HEAD";
+	const response = await route.handle(new Request(`${requestOrigin(req) || `${req.protocol}://${req.hostname}`}${req.url}`, {
+		method: req.method,
+		headers,
+		...hasBody ? { body: new Uint8Array(await readRawBytes(ctx.raw)) } : {}
+	}));
+	ctx.res.setStatus(response.status);
+	response.headers.forEach((value, name) => {
+		ctx.res.setHeader(name, value);
+	});
+	if (!response.headers.has("cache-control")) ctx.res.setHeader("Cache-Control", "no-store");
+	ctx.res.send(Buffer.from(await response.arrayBuffer()));
+	return true;
+};
+//#endregion
+export { functionRoutesStage };

package/dist/core/services/realtime.d.ts

@@ -0,0 +1,8 @@
+import { SSRContext, Stage } from '../http/types';
+/**
+ * `/_realtime`: a page subscribing (GET, a stream that stays open) and publishing (POST) — or asking to switch the
+ * same GET to a WebSocket, which does both.
+ *
+ * After the auth middleware, like the action endpoint: who may open a channel depends on who is asking.
+ */
+export declare const realtimeStage: Stage<SSRContext>;

package/dist/core/services/realtime.js

@@ -0,0 +1,57 @@
+import { handleRealtimePublish, handleRealtimeSubscribe } from "../../modules/realtime/handlers.js";
+import { readRawBody } from "../requestParser.js";
+import { handleRealtimeSocket } from "../../modules/realtime/socket.js";
+//#region src/core/services/realtime.ts
+/**
+* `/_realtime`: a page subscribing (GET, a stream that stays open) and publishing (POST) — or asking to switch the
+* same GET to a WebSocket, which does both.
+*
+* After the auth middleware, like the action endpoint: who may open a channel depends on who is asking.
+*/
+var realtimeStage = async (ctx) => {
+	const { realtime, req } = ctx;
+	if (!realtime || req.path !== realtime.path) return false;
+	if (ctx.upgrade) {
+		ctx.operation = "realtime:socket";
+		await handleRealtimeSocket({
+			req,
+			res: ctx.res,
+			raw: ctx.raw,
+			upgrade: ctx.upgrade,
+			hub: realtime.hub,
+			resolveChannels: realtime.resolveChannels,
+			grants: realtime.grants,
+			allowedOrigins: realtime.allowedOrigins
+		});
+		return true;
+	}
+	if (req.method === "GET") {
+		ctx.operation = "realtime:subscribe";
+		await handleRealtimeSubscribe({
+			req,
+			res: ctx.res,
+			raw: ctx.rawRes,
+			signal: ctx.signal,
+			hub: realtime.hub,
+			resolveChannels: realtime.resolveChannels,
+			grants: realtime.grants
+		});
+		return true;
+	}
+	if (req.method === "POST") {
+		ctx.operation = "realtime:publish";
+		req.body = await readRawBody(ctx.raw);
+		await handleRealtimePublish({
+			req,
+			res: ctx.res,
+			hub: realtime.hub
+		});
+		return true;
+	}
+	ctx.res.setStatus(405);
+	ctx.res.setHeader("Allow", "GET, POST");
+	ctx.res.send("");
+	return true;
+};
+//#endregion
+export { realtimeStage };

package/dist/core/services/registry.js

@@ -1,10 +1,12 @@
 import { actionStage } from "./action.js";
+import { functionRoutesStage } from "./functionRoutes.js";
+import { realtimeStage } from "./realtime.js";
 import { rscStage } from "./rsc.js";
 import { notFoundStage, ssrStage } from "./ssr.js";
 import { authRoutesStages } from "../http/stages/authRoutes.js";
 import { fontAssetsStage } from "../http/stages/fontAssets.js";
 import { healthStage } from "../http/stages/health.js";
-import { middlewaresStage } from "../http/stages/middlewares.js";
+import { createMiddlewaresStage } from "../http/stages/middlewares.js";
 import { pluginAssetsStage } from "../http/stages/pluginAssets.js";
 import { configStaticStage, publicDirStage, sdkAssetsStage, wellKnownStage } from "../http/stages/static.js";
 //#region src/core/services/registry.ts
@@ -20,10 +22,12 @@ var buildPagePipeline = (services, extensions = {}) => {
 		sdkAssetsStage
 	];
 	stages.push(...extensions.preAuth ?? []);
-	stages.push(middlewaresStage);
+	stages.push(createMiddlewaresStage());
 	if (services.rsc) stages.push(rscStage);
 	stages.push(actionStage);
+	stages.push(realtimeStage);
 	stages.push(...extensions.data ?? []);
+	stages.push(functionRoutesStage);
 	stages.push(services.ssr ? ssrStage : notFoundStage);
 	return stages;
 };

package/dist/core/staticFiles.js

@@ -1,7 +1,10 @@
 import { getCacheControl, getMimeType } from "./mimeTypes.js";
-import fs from "node:fs";
+import { CompressedFileCache } from "../helpers/cache/CompressedFileCache.js";
 import path from "node:path";
+import fs from "node:fs";
 //#region src/core/staticFiles.ts
+var compressedFiles = new CompressedFileCache(16777216);
+var isText = (mimeType) => /^text\/|javascript|json|xml|svg/.test(mimeType);
 var buildEtag = (stat) => `"${stat.mtimeMs.toString(36)}-${stat.size.toString(36)}"`;
 var serveFile = (req, res, filePath, stat) => {
 	const etag = buildEtag(stat);
@@ -14,9 +17,14 @@ var serveFile = (req, res, filePath, stat) => {
 		res.end();
 		return true;
 	}
-	const content = fs.readFileSync(filePath);
-	res.setHeader("Content-Type", getMimeType(filePath));
-	res.send(content);
+	const mimeType = getMimeType(filePath);
+	res.setHeader("Content-Type", mimeType);
+	if (isText(mimeType)) {
+		res.send(() => fs.readFileSync(filePath, "utf-8"), { compressed: compressedFiles.storeFor(filePath, etag) });
+		compressedFiles.trim();
+		return true;
+	}
+	res.send(fs.readFileSync(filePath));
 	return true;
 };
 var serveStatic = (req, res, rootDir) => {

package/dist/core/staticFiles.test.d.ts

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

package/dist/core/transports.d.ts

@@ -1,6 +1,9 @@
+import { default as http, IncomingMessage } from 'node:http';
+import { default as http2 } from 'node:http2';
+import { default as https } from 'node:https';
 import { RawResponse } from '../helpers/buildResponseHelpers';
 import { SSRServerConfig } from '@plitzi/sdk-shared';
-import { IncomingMessage } from 'node:http';
+import { Duplex } from 'node:stream';
 export type CloseableServer = {
     close: (cb?: (err?: Error) => void) => unknown;
     listen: (port: number, host: string, cb: () => void) => unknown;
@@ -8,7 +11,14 @@ export type CloseableServer = {
      *  is how a taken port used to read as a crash in `node:net` rather than as this server not starting. */
     on: (event: 'error', listener: (error: NodeJS.ErrnoException) => void) => unknown;
 };
-export type Handler = (req: IncomingMessage, res: RawResponse) => void;
+/** The server a port is served by: Node's own, whichever protocol — what a shutdown drains (`server/drain.ts`). */
+export type PrimaryServer = http.Server | https.Server | http2.Http2SecureServer;
+/** A request asking to switch protocols: node hands over the socket, and the bytes it read past the headers. */
+export type UpgradeHandler = (req: IncomingMessage, socket: Duplex, head: Buffer) => void;
+/** What a server answers requests with — and, when it takes any, upgrades (`upgrade`). */
+export type Handler = ((req: IncomingMessage, res: RawResponse) => void) & {
+    upgrade?: UpgradeHandler;
+};
 export declare const tlsOptions: (config: SSRServerConfig, label?: string) => {
     key: string | Buffer<ArrayBufferLike>;
     cert: string | Buffer<ArrayBufferLike>;
@@ -16,6 +26,6 @@ export declare const tlsOptions: (config: SSRServerConfig, label?: string) => {
 };
 export declare const protoLabel: (version: number, hasTls: boolean) => string;
 export declare const buildTransport: (config: SSRServerConfig, handler: Handler, port: number, label?: string) => {
-    primary: CloseableServer;
+    primary: PrimaryServer;
     h3?: CloseableServer;
 };

package/dist/core/transports.js

@@ -1,3 +1,4 @@
+import { serverLog } from "../helpers/serverLog.js";
 import http from "node:http";
 import http2 from "node:http2";
 import https from "node:https";
@@ -16,6 +17,14 @@ var protoLabel = (version, hasTls) => {
 	if (version >= 2) return hasTls ? "HTTP/2 (TLS)" : "HTTP/1.1 - TLS Missing";
 	return hasTls ? "HTTPS/1.1" : "HTTP/1.1";
 };
+/**
+* Upgrades reach HTTP/1.1 servers only. Over HTTP/2 a browser has no way to ask for one — node does not speak the
+* extended CONNECT that WebSockets over h2 need — so a client there stays on what plain requests can do.
+*/
+var withUpgrades = (server, handler) => {
+	if (handler.upgrade) server.on("upgrade", handler.upgrade);
+	return server;
+};
 var buildTransport = (config, handler, port, label = "Server") => {
 	const version = config.httpVersion ?? 2;
 	let primary;
@@ -29,10 +38,10 @@ var buildTransport = (config, handler, port, label = "Server") => {
 			try {
 				h3 = (await import("node:http3")).createServer(tlsOptions(config, label), handler);
 				h3.listen(port, "0.0.0.0", () => {
-					console.log(`[${label}] HTTP/3 (QUIC) listening on port ${port}`);
+					serverLog.info(label, `HTTP/3 (QUIC) listening on port ${port}`);
 				});
 			} catch {
-				console.warn(`[${label}] HTTP/3 unavailable — start Node.js with --experimental-quic (requires Node ≥ 23). Falling back to HTTP/2.`);
+				serverLog.warn(label, "HTTP/3 unavailable — start Node.js with --experimental-quic (requires Node ≥ 23). Falling back to HTTP/2.");
 			}
 		})();
 	} else if (version >= 2) {
@@ -40,9 +49,9 @@ var buildTransport = (config, handler, port, label = "Server") => {
 			...tlsOptions(config, label),
 			allowHTTP1: true
 		}, handler);
-		else primary = http.createServer(handler);
-	} else if (config.tls) primary = https.createServer(tlsOptions(config, label), handler);
-	else primary = http.createServer(handler);
+		else primary = withUpgrades(http.createServer(handler), handler);
+	} else if (config.tls) primary = withUpgrades(https.createServer(tlsOptions(config, label), handler), handler);
+	else primary = withUpgrades(http.createServer(handler), handler);
 	return {
 		primary,
 		h3