@harperfast/harper 5.3.0-alpha.1 → 5.3.0-beta.1

package/server/serverHelpers/contentTypes.ts

@@ -10,6 +10,10 @@ import * as envMgr from '../../utility/environment/environmentManager.ts';
 import { CONFIG_PARAMS } from '../../utility/hdbTerms.ts';
 import * as YAML from 'yaml';
 import { logger } from '../../utility/logging/logger.ts';
+import {
+	errorToString as harperErrorToString,
+	errorForLog as harperErrorForLog,
+} from '../../utility/logging/harper_logger.ts';
 import { Blob } from '../../resources/blob.ts';
 // TODO: Only load this if fastify is loaded
 import fp from 'fastify-plugin';
@@ -17,6 +21,36 @@ import { parseMultipartRequest } from './multipartParser.ts';
 const SERIALIZATION_BIGINT = envMgr.get(CONFIG_PARAMS.SERIALIZATION_BIGINT) !== false;
 const JSONStringify = SERIALIZATION_BIGINT ? stringify : JSON.stringify;
 const JSONParse = SERIALIZATION_BIGINT ? parse : JSON.parse;
+const streamStartup = Symbol('streamStartup');
+const serializedStreamError = Symbol('serializedStreamError');
+
+type StreamStartup = {
+	result: Promise<{ failed?: true; error?: unknown }>;
+	abort: () => void;
+	start: () => void;
+	cancel?: () => void;
+};
+
+function streamErrorRecord(error: any) {
+	let name = 'Error';
+	let message;
+	try {
+		const code = error?.code;
+		if (typeof code === 'string' || typeof code === 'number') name = String(code);
+		else if (typeof error?.constructor?.name === 'string') name = error.constructor.name;
+		else if (typeof error?.name === 'string') name = error.name;
+	} catch {}
+	try {
+		if (typeof error?.message === 'string') message = error.message;
+	} catch {}
+	message ??= harperErrorToString(error);
+	const record: { error: string; message: string; status?: number } = { error: name, message };
+	try {
+		const status = error?.statusCode ?? error?.status;
+		if (typeof status === 'number') record.status = status;
+	} catch {}
+	return record;
+}
 
 const PUBLIC_ENCODE_OPTIONS = {
 	useRecords: false,
@@ -103,9 +137,14 @@ mediaTypes.set('text/yaml', {
 });
 
 const ndjsonHandler = {
-	serializeStream(data: any) {
+	serializeStream(data: any, _response?: Response, request?: any) {
 		if (data?.[Symbol.iterator] || data?.[Symbol.asyncIterator]) {
-			return Readable.from(transformIterable(data, (msg: any) => JSONStringify(msg) + '\n'));
+			return errorFrameStream(
+				data,
+				(msg: any) => JSONStringify(msg) + '\n',
+				(error) => JSONStringify({ $harperStreamError: streamErrorRecord(error) }) + '\n',
+				request?.method === 'GET'
+			);
 		}
 		return JSONStringify(data) + '\n';
 	},
@@ -132,9 +171,14 @@ function serializeSSEData(data: any) {
 
 mediaTypes.set('text/event-stream', {
 	// Server-Sent Events (SSE)
-	serializeStream: function (iterable) {
+	serializeStream: function (iterable, _response?: Response, request?: any) {
 		// create a readable stream that we use to stream out events from our subscription
-		return Readable.from(transformIterable(iterable, this.serialize));
+		return errorFrameStream(
+			iterable,
+			this.serialize,
+			(error) => this.serialize({ event: 'harper-error', data: streamErrorRecord(error) }),
+			request?.method === 'GET'
+		);
 	},
 	serialize: function (message) {
 		if (message.acknowledge) message.acknowledge();
@@ -396,7 +440,12 @@ export function serialize(responseData, request, responseObject) {
 			(responseData[Symbol.iterator] || responseData[Symbol.asyncIterator]) &&
 			serializer.serializer.serializeStream
 		) {
-			if (responseData.mapError) {
+			if (
+				responseData.mapError &&
+				serializer.type !== 'application/x-ndjson' &&
+				serializer.type !== 'application/ndjson' &&
+				serializer.type !== 'text/event-stream'
+			) {
 				// indicate that we want iterator errors to be returned so we can serialize them in a meaningful way, if possible
 				const getColumns = responseData.getColumns;
 				responseData = responseData.mapError((error) => {
@@ -407,9 +456,10 @@ export function serialize(responseData, request, responseObject) {
 				});
 				responseData.getColumns = getColumns;
 			}
-			let stream = serializer.serializer.serializeStream(responseData, responseObject);
+			let stream = serializer.serializer.serializeStream(responseData, responseObject, request);
 			if (canCompress) {
 				responseObject.headers.set('Content-Encoding', 'br');
+				const uncompressedStream = stream;
 				stream = stream.pipe(
 					createBrotliCompress({
 						params: {
@@ -421,6 +471,7 @@ export function serialize(responseData, request, responseObject) {
 						},
 					})
 				);
+				if (uncompressedStream[streamStartup]) stream[streamStartup] = uncompressedStream[streamStartup];
 			}
 			return stream;
 		}
@@ -623,24 +674,146 @@ function deserializerUnknownType(contentType: ContentType): Deserialize {
 	}
 }
 
-function transformIterable(iterable, transform) {
+function errorFrameStream(iterable, transform, serializeError, eager: boolean) {
+	const transformed = transformIterable(iterable, transform, serializeError, eager);
+	const readable = Readable.from(transformed);
+	const startup: StreamStartup = transformed[streamStartup];
+	startup.cancel = () => readable.destroy();
+	readable[streamStartup] = startup;
+	return readable;
+}
+
+export function discardSerializedStream(stream) {
+	stream?.[streamStartup]?.cancel?.();
+	stream?.destroy?.();
+}
+
+export function waitForStreamStartup(stream) {
+	const startup: StreamStartup | undefined = stream?.[streamStartup];
+	if (!startup) return;
+	startup.start();
+	return startup.result.then((result) => {
+		if (result.failed) {
+			startup.abort();
+			discardSerializedStream(stream);
+			throw result.error;
+		}
+	});
+}
+
+function transformIterable(iterable, transform, serializeError, eager) {
+	let iterator;
+	let terminal = false;
+	let first = true;
+	let started = false;
+	let firstStep;
+	let startupSettled = false;
+	const startupResult = Promise.withResolvers<{ failed?: true; error?: unknown }>();
+	const errorDecision = Promise.withResolvers<boolean>();
+	let startupTimer;
+
+	const commit = () => {
+		if (startupTimer) clearImmediate(startupTimer);
+		if (!startupSettled) {
+			startupSettled = true;
+			startupResult.resolve({});
+		}
+		errorDecision.resolve(true);
+	};
+	const abort = () => {
+		if (startupTimer) clearImmediate(startupTimer);
+		errorDecision.resolve(false);
+	};
+	const handleError = async (error) => {
+		terminal = true;
+		try {
+			const returned = iterator.return?.();
+			returned?.catch?.(() => {});
+		} catch {}
+		if (!startupSettled) startupResult.resolve({ failed: true, error });
+		if (!startupSettled && !(await errorDecision.promise)) return { done: true };
+		logger.warn?.('Error serializing in stream', harperErrorForLog(error));
+		return { value: serializeError(error), done: false, [serializedStreamError]: true };
+	};
+	const transformStep = (step) => {
+		if (step?.[serializedStreamError]) return step;
+		if (terminal) return { done: true };
+		if (step.done) return step;
+		try {
+			return { value: transform(step.value), done: false };
+		} catch (error) {
+			return handleError(error);
+		}
+	};
+	const getRawNext = () => {
+		if (terminal) return { done: true };
+		let step;
+		try {
+			step = iterator.next();
+		} catch (error) {
+			return handleError(error);
+		}
+		if (step.then) return step.then(undefined, handleError);
+		return step;
+	};
+	const getNext = () => {
+		if (terminal) return { done: true };
+		let step;
+		try {
+			step = iterator.next();
+		} catch (error) {
+			return handleError(error);
+		}
+		if (step.then) return step.then(transformStep, handleError);
+		return transformStep(step);
+	};
+	const start = () => {
+		if (started) return;
+		started = true;
+		iterator = iterable[Symbol.asyncIterator] ? iterable[Symbol.asyncIterator]() : iterable[Symbol.iterator]();
+		firstStep = getRawNext();
+		Promise.resolve(firstStep).then(
+			() => {
+				if (!terminal) commit();
+			},
+			() => {}
+		);
+		// After this turn, the HTTP status can no longer wait for a first item without delaying long-lived streams.
+		startupTimer = setImmediate(commit);
+	};
+	if (eager) start();
+
 	return {
+		[streamStartup]: {
+			result: startupResult.promise,
+			abort,
+			start,
+		},
 		[Symbol.asyncIterator]() {
-			const iterator = iterable[Symbol.asyncIterator] ? iterable[Symbol.asyncIterator]() : iterable[Symbol.iterator]();
 			return {
 				next() {
-					const step = iterator.next();
-					if (step.then) {
-						// don't transform the terminal sentinel step, whose value is undefined
-						return step.then((result) => (result.done ? result : { value: transform(result.value), done: false }));
+					if (terminal) return { done: true };
+					if (first) {
+						first = false;
+						start();
+						const step = firstStep;
+						firstStep = undefined;
+						if (step.then) return step.then(transformStep);
+						return transformStep(step);
 					}
-					return step.done ? step : { value: transform(step.value), done: false };
+					return getNext();
 				},
 				return(value) {
-					return iterator.return(value);
+					terminal = true;
+					started = true;
+					if (!iterator)
+						iterator = iterable[Symbol.asyncIterator]
+							? iterable[Symbol.asyncIterator]()
+							: iterable[Symbol.iterator]?.();
+					return iterator?.return?.(value) ?? { value, done: true };
 				},
 				throw(error) {
-					return iterator.throw(error);
+					return iterator?.throw?.(error) ?? Promise.reject(error);
 				},
 			};
 		},

package/server/serverHelpers/serverUtilities.ts

@@ -235,6 +235,17 @@ server.setMcpQuotaHandler = (handler) => {
 	setMcpQuotaHandler(handler);
 };
 
+// The nested `search_operation` operations dataLayer/export.ts's getRecords can actually run (its
+// VALID_SEARCH_OPERATIONS). Validated at dispatch so an unsupported or missing nested operation is a
+// request-time 400 rather than an async job failure, and so the nested authorization below always
+// resolves a real handler.
+const EXPORT_SEARCH_OPERATIONS = new Set<string>([
+	terms.OPERATIONS_ENUM.SEARCH_BY_VALUE,
+	terms.OPERATIONS_ENUM.SEARCH_BY_HASH,
+	terms.OPERATIONS_ENUM.SEARCH_BY_CONDITIONS,
+	terms.OPERATIONS_ENUM.SQL,
+]);
+
 export function chooseOperation(json: OperationRequestBody, bypassAuth = false) {
 	let getOpResult: OperationFunctionObject;
 	try {
@@ -255,32 +266,112 @@ export function chooseOperation(json: OperationRequestBody, bypassAuth = false)
 
 	const { operation_function, job_operation_function } = getOpResult;
 
-	// Here there is a SQL statement in either the operation or the searchOperation (from jobs like export_local).  Need to check the perms
-	// on all affected tables/attributes.
+	const isSqlOperation = json.operation === terms.OPERATIONS_ENUM.SQL;
+	// `verifyPerms` derives the tables it checks from the object it is handed, so the caller-supplied
+	// `search_operation` may only stand in as the permission subject for the operations that actually
+	// run it (dataLayer/export.ts is its only consumer). For anything else it would check the nested
+	// tables while the handler runs against the top-level ones.
+	const nestedSearch =
+		json.operation === terms.OPERATIONS_ENUM.EXPORT_LOCAL || json.operation === terms.OPERATIONS_ENUM.EXPORT_TO_S3
+			? json.search_operation
+			: undefined;
+	if (nestedSearch !== undefined) {
+		// It becomes the permission subject below, and a primitive would throw on the principal
+		// assignment — a 400 rather than a wrapped 500.
+		if (nestedSearch === null || typeof nestedSearch !== 'object' || Array.isArray(nestedSearch)) {
+			throw handleHDBError(
+				new Error(),
+				`'search_operation' must be an object`,
+				hdbErrors.HTTP_STATUS_CODES.BAD_REQUEST,
+				undefined,
+				undefined,
+				true
+			);
+		}
+		// The object check alone lets `{}` and unsupported operations through — they would then fail
+		// asynchronously in the export worker (or dereference `search_operation.operation`). Require a
+		// supported operation at request time; the nested authorization below relies on it resolving.
+		if (typeof nestedSearch.operation !== 'string' || !EXPORT_SEARCH_OPERATIONS.has(nestedSearch.operation)) {
+			throw handleHDBError(
+				new Error(),
+				`'search_operation.operation' must be one of: ${[...EXPORT_SEARCH_OPERATIONS].join(', ')}`,
+				hdbErrors.HTTP_STATUS_CODES.BAD_REQUEST,
+				undefined,
+				undefined,
+				true
+			);
+		}
+		// Dispatch state, never client input: the export worker re-reads `parsed_sql_object` off this
+		// same object (evaluateSQL), and it carries `permissions_checked`, so a body-supplied one would
+		// execute an AST no check ever saw. Deleting it rather than replacing it with the authorized
+		// parse is deliberate — the worker then re-parses and re-runs the check itself.
+		delete nestedSearch.parsed_sql_object;
+	}
+	// The AST check below covers only the statement's tables, never the caller's right to invoke the
+	// job operation, so it is additive to verifyPerms rather than an alternative to it.
+	const hasNestedSqlSearch = nestedSearch?.operation === terms.OPERATIONS_ENUM.SQL;
+
 	try {
-		if (json.operation === 'sql' || (json.search_operation && json.search_operation.operation === 'sql')) {
+		if (isSqlOperation || hasNestedSqlSearch) {
 			const sql = require('../../sqlTranslator/index');
-			const sqlStatement = json.operation === 'sql' ? json.sql : json.search_operation.sql;
+			const sqlStatement = isSqlOperation ? json.sql : nestedSearch.sql;
 			// Before this dispatch's own parse is assigned, so a body-supplied object cannot survive it.
 			stripSuppliedParsedSqlObject(json);
 			const parsedSqlObject = sql.convertSQLToAST(sqlStatement);
-			json.parsed_sql_object = parsedSqlObject;
+			if (hasNestedSqlSearch && parsedSqlObject.variant !== terms.VALID_SQL_OPS_ENUM.SELECT) {
+				throw handleHDBError(
+					new Error(),
+					`'search_operation.sql' must be a SELECT statement`,
+					hdbErrors.HTTP_STATUS_CODES.BAD_REQUEST,
+					undefined,
+					undefined,
+					true
+				);
+			}
+			// Only the direct-SQL path consumes `json.parsed_sql_object` (evaluateSQL). A nested export
+			// re-parses off `search_operation` — whose `parsed_sql_object` was deleted above — so setting
+			// it here for a job would be inert.
+			if (isSqlOperation) {
+				json.parsed_sql_object = parsedSqlObject;
+			}
 			if (!bypassAuth) {
-				// The SQL path never reaches verifyPerms, so the role `operations` allowlist must be
-				// enforced here — otherwise an allowlisted role reaches unlisted operations via `sql`.
-				// json.operation is already the API name ('sql', or the outer job op like 'export_local').
-				const allowlistDenial = opAuth.verifyOperationsAllowlist(json, json.operation);
-				if (allowlistDenial) {
-					operationLog.error(`${HTTP_STATUS_CODES.FORBIDDEN} from operation ${json.operation}`);
-					operationLog.warn(`User '${json.hdb_user?.username}' is not permitted to ${json.operation}`);
-					throw handleHDBError(
-						new Error(),
-						allowlistDenial,
-						hdbErrors.HTTP_STATUS_CODES.FORBIDDEN,
-						undefined,
-						undefined,
-						true
-					);
+				if (hasNestedSqlSearch) {
+					// A nested-SQL export's outer op (export_local/export_to_s3) is `requires_su`, which the
+					// AST table check below does not enforce. Authorize invoking it through verifyPerms
+					// exactly as the non-SQL job path does — otherwise SQL is a way around the requires_su
+					// gate that path enforces. The nested table reads are then covered additively by the AST
+					// check. verifyPerms also runs the allowlist (gate 1) and the export token scope.
+					const functionToCheck = job_operation_function === undefined ? operation_function : job_operation_function;
+					const outerDenial = opAuth.verifyPerms(json, functionToCheck, { apiOperation: json.operation });
+					if (outerDenial) {
+						operationLog.error(`${HTTP_STATUS_CODES.FORBIDDEN} from operation ${json.operation}`);
+						operationLog.warn(`User '${json.hdb_user?.username}' is not permitted to ${json.operation}`);
+						throw handleHDBError(
+							new Error(),
+							outerDenial,
+							hdbErrors.HTTP_STATUS_CODES.FORBIDDEN,
+							undefined,
+							false,
+							true
+						);
+					}
+				} else {
+					// Direct SQL: the invoked operation IS `sql`, so the role `operations` allowlist is the
+					// operation-invocation check — otherwise an allowlisted role reaches unlisted operations
+					// via `sql`. json.operation is already the API name.
+					const allowlistDenial = opAuth.verifyOperationsAllowlist(json, json.operation);
+					if (allowlistDenial) {
+						operationLog.error(`${HTTP_STATUS_CODES.FORBIDDEN} from operation ${json.operation}`);
+						operationLog.warn(`User '${json.hdb_user?.username}' is not permitted to ${json.operation}`);
+						throw handleHDBError(
+							new Error(),
+							allowlistDenial,
+							hdbErrors.HTTP_STATUS_CODES.FORBIDDEN,
+							undefined,
+							undefined,
+							true
+						);
+					}
 				}
 				// `json.operation` explicitly — the operation this dispatch already resolved, not a
 				// field read back off the request body.
@@ -309,10 +400,9 @@ export function chooseOperation(json: OperationRequestBody, bypassAuth = false)
 			json.operation !== terms.OPERATIONS_ENUM.EXCHANGE_OIDC_TOKEN
 		) {
 			const functionToCheck = job_operation_function === undefined ? operation_function : job_operation_function;
-			const operation_json = json.search_operation ? json.search_operation : json;
-			if (!operation_json.hdb_user) {
-				operation_json.hdb_user = json.hdb_user;
-			}
+			const operation_json = nestedSearch ?? json;
+			// Authentication is the only source of the principal; a nested one is overwritten, not honored.
+			operation_json.hdb_user = json.hdb_user;
 
 			// Pass the top-level operation for the token-scope check: for an export job, operation_json
 			// is the nested search_operation, so json.operation (export_local/export_to_s3) is the op the
@@ -335,6 +425,35 @@ export function chooseOperation(json: OperationRequestBody, bypassAuth = false)
 					true
 				);
 			}
+
+			// The check above authorizes invoking the operation, but for a non-SQL export it returns
+			// before any table check — a requires_su export is granted the moment its `operations`
+			// allowlist lists it (verifyPerms gate 2) — and the job worker then runs `search_operation`
+			// through searchByValue/Hash/Conditions, none of which check permissions. So the nested read
+			// is only enforceable here: authorize it additively against its real search handler and the
+			// authenticated principal (assigned above via operation_json), so a role that may invoke the
+			// export but lacks read on the table is denied. A nested SQL search is covered by the AST
+			// branch above instead.
+			if (nestedSearch) {
+				const nestedFunction = getOperationFunction(nestedSearch).operation_function;
+				const nestedPermsResult = opAuth.verifyPerms(nestedSearch, nestedFunction, {
+					apiOperation: json.operation,
+				});
+				if (nestedPermsResult) {
+					operationLog.error(`${HTTP_STATUS_CODES.FORBIDDEN} from operation ${json.operation}`);
+					operationLog.warn(
+						`User '${operation_json.hdb_user?.username}' is not permitted to ${nestedSearch.operation} within ${json.operation}`
+					);
+					throw handleHDBError(
+						new Error(),
+						nestedPermsResult,
+						hdbErrors.HTTP_STATUS_CODES.FORBIDDEN,
+						undefined,
+						false,
+						true
+					);
+				}
+			}
 		}
 	} catch (err) {
 		throw handleHDBError(err, `There was an error when trying to choose an operation path`, 500);

package/server/storageReclamation.ts

@@ -1,7 +1,7 @@
 import { readFile, realpath } from 'node:fs/promises';
 import { statfs } from 'node:fs/promises';
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
-import { getWorkerIndex, getWorkerCount } from '../server/threads/manageThreads.js';
+import { ownsStoreMaintenance } from '../server/threads/manageThreads.js';
 import { logger } from '../utility/logging/logger.ts';
 import { CONFIG_PARAMS } from '../utility/hdbTerms.ts';
 import * as envMgr from '../utility/environment/environmentManager.ts';
@@ -106,7 +106,7 @@ export function onStorageReclamation(
 	handler: (priority: number) => Promise<void> | void,
 	skipThreadCheck?: boolean
 ) {
-	if (skipThreadCheck || getWorkerIndex() === getWorkerCount() - 1) {
+	if (skipThreadCheck || ownsStoreMaintenance(path)) {
 		// only run on one thread (last one)
 		if (!path) {
 			throw new Error('Storage reclamation path cannot be empty');

package/server/threads/isolatedApplications.ts

@@ -0,0 +1,157 @@
+/**
+ * Isolated applications: an application whose root-config entry carries `isolated: true` runs in a
+ * worker thread of its own that loads no other application (harper#642, tier 2).
+ *
+ * The invariant every helper here serves: an isolated application is loaded by exactly one thread,
+ * and that thread loads nothing else. The dedicated worker is an ordinary `http` worker by type --
+ * so restarts, overlap rules and shutdown treat it as one -- distinguished only by
+ * `workerData.isolatedApplication`. It binds none of the public ports (the kernel would hand it
+ * connections for every other application) and is reachable only through its own UDS mirror, whose
+ * metadata names the application and its hosts for the fronting proxy to route by.
+ */
+import { isMainThread, workerData } from 'node:worker_threads';
+import { getWorkerIndex } from './manageThreads.js';
+import { getConfigObj, getConfigPath } from '../../config/configUtils.ts';
+import * as env from '../../utility/environment/environmentManager.ts';
+import { CONFIG_PARAMS } from '../../utility/hdbTerms.ts';
+import { isDomainSocketPathTooLong } from '../../utility/domainSocket.ts';
+import { existsSync } from 'node:fs';
+import { basename, join } from 'node:path';
+
+export const DEFAULT_MAX_ISOLATED_APPLICATIONS = 8;
+
+/** The application this thread is dedicated to, if it is a dedicated worker. */
+export function thisThreadsIsolatedApplication(): string | undefined {
+	return (workerData as any)?.isolatedApplication;
+}
+
+export function thisThreadOwnsApplication(
+	appName: string | undefined,
+	owner: string | undefined = thisThreadsIsolatedApplication()
+): boolean {
+	return owner !== undefined && appName === owner;
+}
+
+export function isIsolatedApplication(
+	appName: string,
+	config: Record<string, any> | undefined = getConfigObj()
+): boolean {
+	const entry = config?.[appName];
+	return typeof entry === 'object' && entry !== null && entry.isolated === true;
+}
+
+/** Every application the root config marks isolated, in config order. */
+export function isolatedApplicationNames(config: Record<string, any> | undefined = getConfigObj()): string[] {
+	if (!config) return [];
+	return Object.keys(config).filter((name) => isIsolatedApplication(name, config));
+}
+
+export function presentIsolatedApplicationNames(
+	config: Record<string, any> | undefined = getConfigObj(),
+	componentsRoot: string = getConfigPath(CONFIG_PARAMS.COMPONENTSROOT) as string,
+	installedRoot: string = join(env.get(CONFIG_PARAMS.ROOTPATH), 'components'),
+	runApplicationPath: string | undefined = process.env.RUN_HDB_APP
+): string[] {
+	return isolatedApplicationNames(config).filter(
+		(application) =>
+			existsSync(join(componentsRoot, application)) ||
+			existsSync(join(installedRoot, application)) ||
+			(runApplicationPath && basename(runApplicationPath) === application)
+	);
+}
+
+export function maxIsolatedApplications(): number {
+	const configured = Number(env.get(CONFIG_PARAMS.THREADS_MAXISOLATED));
+	return Number.isInteger(configured) && configured >= 0 ? configured : DEFAULT_MAX_ISOLATED_APPLICATIONS;
+}
+
+/** Why `appName` cannot claim a place in the dedicated-worker budget, if the budget is full. */
+export function isolatedApplicationCapacityRefusal(
+	appName: string,
+	runningApplications: Iterable<string>,
+	max = maxIsolatedApplications()
+): string | undefined {
+	const running = new Set(runningApplications);
+	if (running.has(appName) || running.size < max) return undefined;
+	return `the instance already runs ${max} isolated application(s) (threads.maxIsolated)`;
+}
+
+/**
+ * Whether the calling thread is the one that loads the application `appName` (an application: a
+ * directory under componentsRoot, or a root-config entry with `package`). A dedicated worker loads
+ * only its own application; every other thread -- pool workers and the main thread alike -- loads only
+ * the applications that are not isolated. Decided before any of the application's modules are
+ * imported, so a skipped application has no side effects on the thread that skipped it.
+ */
+export function shouldLoadApplicationHere(
+	appName: string,
+	owner: string | undefined = thisThreadsIsolatedApplication(),
+	config: Record<string, any> | undefined = getConfigObj()
+): boolean {
+	if (owner !== undefined) return appName === owner;
+	return !isIsolatedApplication(appName, config);
+}
+
+/**
+ * Whether this thread starts the uWS listener for one `uwsServeConfigs` entry (see listenOnPorts()).
+ * A dedicated worker starts only its own per-application UDS mirrors -- the entries that carry a
+ * `socketPath` -- and never a global port listener, which the kernel would hand connections for every
+ * other application.
+ */
+export function shouldStartUwsListenerHere(
+	serveConfig: { socketPath?: string },
+	owner: string | undefined = thisThreadsIsolatedApplication()
+): boolean {
+	return owner === undefined || Boolean(serveConfig.socketPath);
+}
+
+/**
+ * Whether a dedicated worker can be reached at all: it binds only UDS mirrors of the secure port, so
+ * without `tls.unixDomainSockets` and a secure port an isolated application would load and answer
+ * nothing, silently. Refused at admission instead. Returns the reason, or undefined when reachable.
+ */
+export function isolatedApplicationsUnreachableReason(platform = process.platform): string | undefined {
+	if (platform === 'win32') return 'Windows does not support per-application UDS mirrors';
+	// the main thread standing in as the only worker (threads.count: 0) has no thread to give
+	if (isMainThread && getWorkerIndex() === 0) return 'threads.count is 0, so there is no worker thread to dedicate';
+	if (!env.get(CONFIG_PARAMS.HTTP_SECUREPORT)) return 'no http.securePort is configured';
+	if (!env.get(CONFIG_PARAMS.TLS_UNIXDOMAINSOCKETS)) return 'tls.unixDomainSockets is not enabled';
+	return undefined;
+}
+
+/** Why `appName` cannot get a dedicated worker on this instance, or undefined when it can. */
+export function isolatedApplicationRefusal(appName: string): string | undefined {
+	const unreachable = isolatedApplicationsUnreachableReason();
+	if (unreachable) return `its worker would be unreachable: ${unreachable}`;
+	const socketPath = join(
+		env.getHdbBasePath(),
+		'sockets',
+		`${applicationSocketName(appName, env.get(CONFIG_PARAMS.HTTP_SECUREPORT))}.sock`
+	);
+	if (isDomainSocketPathTooLong(socketPath)) return `its UDS mirror path ${socketPath} exceeds the platform limit`;
+	return undefined;
+}
+
+/**
+ * The filesystem name of an isolated worker's UDS mirror for `port`: every UTF-8 byte outside
+ * `[A-Za-z0-9._]` becomes a fixed-width `%XX`, which is injective (two application names never share
+ * a socket), and the `app-` prefix keeps it apart from the pool's `<workerIndex>-<port>` names.
+ */
+export function applicationSocketName(appName: string, port: number | string): string {
+	let encoded = '';
+	for (const byte of Buffer.from(appName, 'utf8')) {
+		const c = String.fromCharCode(byte);
+		encoded += byte < 0x80 && /[A-Za-z0-9._]/.test(c) ? c : `%${byte.toString(16).toUpperCase().padStart(2, '0')}`;
+	}
+	return `app-${encoded}-${port}`;
+}
+
+/** What a dedicated worker publishes in its mirror metadata for the proxy to route by. */
+export function isolatedApplicationRoute(
+	appName: string | undefined = thisThreadsIsolatedApplication(),
+	config: Record<string, any> | undefined = getConfigObj()
+): { application: string; hosts: string[] } | undefined {
+	if (!appName) return undefined;
+	const host = config?.[appName]?.host; // a string, as the mount parser requires
+	return { application: appName, hosts: typeof host === 'string' && host ? [host] : [] };
+}