@harperfast/harper 5.2.13 → 5.3.0-beta.1

package/server/serverHelpers/sharedMessageEncoding.ts

@@ -0,0 +1,307 @@
+import { serializeMessage, getMessageSerializer } from './contentTypes.ts';
+import { logger } from '../../utility/logging/logger.ts';
+
+/**
+ * The encoding work that every subscriber of a topic would otherwise redo for the same message.
+ * `payload` is the serialized message body; `frames` holds fully encoded protocol frames that are
+ * byte-identical across subscribers (MQTT QoS 0 PUBLISH packets), keyed by whatever the frame
+ * still varies on. `next` chains the encodings for any further content types the same message was
+ * delivered in — a chain rather than a map because a topic's subscribers realistically negotiate
+ * one or two content types, and this keeps the single-content-type case to one allocation.
+ *
+ * `hits` counts the subscribers after the first, so a caller can skip caching anything derived
+ * from the payload until a fan-out is known to exist. `failed` is a distinct state from an
+ * undefined `payload`, which a serializer can legitimately return (JSON of `undefined`).
+ * `bytes` is everything this entry holds — payload plus frames — and `epoch` records which
+ * generation those bytes are charged to, so work that lands after a rotation (a serialization that
+ * resolves late) is not charged to a budget it does not belong to, and a promotion re-charges the
+ * entry exactly once. That is what makes the budget an actual accounting rather than an estimate.
+ */
+export interface SharedMessageEncoding {
+	serializer: Function;
+	version: number | undefined;
+	payload: Buffer | string | Promise<Buffer | string> | undefined;
+	failed: boolean;
+	hits: number;
+	bytes: number;
+	epoch: number;
+	frames: Map<number, Map<string, Buffer>> | undefined;
+	next: SharedMessageEncoding | undefined;
+}
+
+// A message that carries its own content type is passed through verbatim and never negotiated, so
+// every subscriber shares one entry no matter what it negotiated. This sentinel stands in for the
+// serializer that was deliberately not consulted.
+const PASS_THROUGH = function passThrough() {};
+
+// THE IDENTITY CONTRACT. A fan-out has a single shared origin: the same message object instance is
+// dispatched to every subscription of a key (resources/transactionBroadcast.ts), so identity is
+// what lets the first subscriber to encode do the work for all of them. This is only sound because
+// every internal producer yields a *fresh object per version* — transactionBroadcast hands one
+// auditRecord to every subscription, auditStore's getValue memoizes the decode in its closure, and
+// primaryStore.getEntry is guarded by a version check — so identity implies equal content, and a
+// miss (a primitive message, or a store cache eviction between subscribers) only costs the
+// redundant encode we have today rather than yielding stale bytes.
+//
+// A custom Resource is not bound by that, so identity alone is not trusted: the event's record
+// version is part of the key (see getSharedMessageEncoding), which makes reusing one envelope
+// across publishes correct as long as the version advances, and refuses to share at all when there
+// is no version to tell one publish from the next.
+//
+// Retention is bounded by rotating generations rather than by the message object's lifetime: for
+// record events the message IS the store's cached record, so hanging encodings off it alone would
+// keep serialized copies and whole PUBLISH buffers resident for as long as the record stays cached,
+// while sharing is only ever needed for the duration of one fan-out. Two generations are kept so a
+// fan-out spanning a rotation still hits; dropping a generation releases all of it at once.
+const ROTATE_INTERVAL_MS = 10_000;
+// Time alone bounds how LONG an entry is retained, not how MUCH: at high throughput on
+// single-subscriber topics the interval's worth of payloads would all be live at once, for no
+// benefit. The byte budget puts a ceiling on that, at the cost of a fan-out that spans an early
+// rotation falling back to re-encoding — slower, never wrong. Note this is the ceiling for ONE
+// generation; the previous generation can hold as much again, so steady-state retention is up to
+// twice this per worker thread.
+export const MAX_RETAINED_BYTES = 4_000_000;
+let currentGeneration = new WeakMap<object, SharedMessageEncoding>();
+let previousGeneration = new WeakMap<object, SharedMessageEncoding>();
+// Rotation runs on a timer, not on a delivery counter: the bound has to hold when traffic stops,
+// which is exactly when a delivery-gated check would never fire again. Insert counts only decide
+// when the timer can stop — a WeakMap can not be asked whether it is empty.
+let rotationTimer: ReturnType<typeof setInterval> | undefined;
+let currentInserts = 0;
+let currentBytes = 0;
+// Identifies the generation an entry's bytes are charged to. Work can land after a rotation — a
+// serialization that resolves late, a frame generated by a subscriber that arrived slowly — and
+// charging that to the current budget would bill a generation the bytes do not belong to, then bill
+// them again when a promotion re-charges the entry.
+const UNRETAINED = -1;
+// starts at 1 so UNRETAINED can never collide with `currentEpoch - 1`, which would make charge()
+// treat a never-retained entry as one still live in the previous generation
+let currentEpoch = 1;
+
+/** Retire the older generation. Exported for the rotation timer and for tests. */
+export function rotateSharedEncodings() {
+	previousGeneration = currentGeneration;
+	currentGeneration = new WeakMap();
+	currentEpoch++;
+	const rotatedInserts = currentInserts;
+	currentInserts = 0;
+	currentBytes = 0;
+	if (rotatedInserts === 0 && rotationTimer !== undefined) {
+		// nothing is retained in either generation, so stop ticking until the next insert
+		clearInterval(rotationTimer);
+		rotationTimer = undefined;
+	}
+}
+
+/** Whether the rotation timer is currently armed. Introspection for tests. */
+export function isRotationScheduled(): boolean {
+	return rotationTimer !== undefined;
+}
+
+/** Bytes charged to the live generation. Introspection so tests can pin the accounting exactly. */
+export function getRetainedBytes(): number {
+	return currentBytes;
+}
+
+function retainedSize(payload: SharedMessageEncoding['payload']): number {
+	// a pending promise is accounted for when it resolves
+	if (typeof payload === 'string') return Buffer.byteLength(payload);
+	return (payload as Buffer)?.byteLength ?? 0;
+}
+
+/** Add to an entry's footprint, and to the budget if the entry is live. */
+function charge(encoding: SharedMessageEncoding, bytes: number) {
+	encoding.bytes += bytes;
+	if (encoding.epoch === currentEpoch) currentBytes += bytes;
+	else if (encoding.epoch === currentEpoch - 1) {
+		// Bytes can land after a rotation — a serialization resolving late, or a frame generated by a
+		// subscriber whose await spanned one. The entry is still live in the previous generation, so
+		// fold its whole footprint into the live budget; charging only the new bytes would leave the
+		// rest counted by no generation at all, and charging nothing would under-report the ceiling.
+		encoding.epoch = currentEpoch;
+		currentBytes += encoding.bytes;
+	}
+}
+
+/** Give back everything a chain holds, for an entry that is being discarded rather than refilled. */
+function release(encoding: SharedMessageEncoding) {
+	for (let node = encoding; node !== undefined; node = node.next) {
+		if (node.epoch === currentEpoch) currentBytes -= node.bytes;
+		node.epoch = UNRETAINED;
+	}
+}
+
+function retain(message: object, encoding: SharedMessageEncoding) {
+	if (currentBytes >= MAX_RETAINED_BYTES) rotateSharedEncodings();
+	currentGeneration.set(message, encoding);
+	currentInserts++;
+	// charges the whole chain: on a promotion this re-charges everything the entry holds, since
+	// rotation zeroed the counter but the bytes are still live
+	for (let node = encoding; node !== undefined; node = node.next) {
+		if (node.epoch !== currentEpoch) {
+			node.epoch = currentEpoch;
+			currentBytes += node.bytes;
+		}
+	}
+	if (rotationTimer === undefined) {
+		rotationTimer = setInterval(rotateSharedEncodings, ROTATE_INTERVAL_MS);
+		rotationTimer.unref?.();
+	}
+}
+
+function fill(encoding: SharedMessageEncoding, message: any, request: any) {
+	// whatever this entry was holding is being replaced, so give the bytes back before re-charging
+	if (encoding.epoch === currentEpoch) currentBytes -= encoding.bytes;
+	encoding.bytes = 0;
+	encoding.frames = undefined;
+	// Pessimistic: an entry is only valid once a payload is actually in hand. Set optimistically,
+	// a synchronous throw here would leave an already-retained entry claiming success with no
+	// payload, and every later subscriber would send an empty PUBLISH instead of erroring.
+	encoding.failed = true;
+	encoding.payload = undefined;
+	const payload = serializeMessage(message, request);
+	encoding.payload = payload;
+	encoding.failed = false;
+	// A pass-through payload IS the message's own data, already reachable from the WeakMap key, so
+	// caching it retains nothing extra and must not be billed against the budget.
+	if (encoding.serializer === PASS_THROUGH) return;
+	if (typeof (payload as any)?.then === 'function')
+		// collapse an async serialization in place so later subscribers, and frame sharing, see the
+		// finished buffer rather than re-entering the async path
+		encoding.payload = (payload as Promise<Buffer | string>).then(
+			(resolved) => {
+				charge(encoding, retainedSize(resolved));
+				return (encoding.payload = resolved);
+			},
+			(error) => {
+				// mark for retry rather than memoize the failure: a shared rejected promise would turn
+				// one transient serialization error into a permanent one for every later subscriber
+				encoding.failed = true;
+				encoding.payload = undefined;
+				throw error;
+			}
+		);
+	else charge(encoding, retainedSize(payload));
+}
+
+function encode(message: any, request: any, serializer: Function, version?: number): SharedMessageEncoding {
+	const encoding: SharedMessageEncoding = {
+		serializer,
+		version,
+		payload: undefined,
+		failed: false,
+		hits: 0,
+		bytes: 0,
+		epoch: UNRETAINED,
+		frames: undefined,
+		next: undefined,
+	};
+	fill(encoding, message, request);
+	return encoding;
+}
+
+function reuse(encoding: SharedMessageEncoding, message: any, request: any): SharedMessageEncoding {
+	encoding.hits++;
+	if (encoding.failed) fill(encoding, message, request);
+	return encoding;
+}
+
+/**
+ * Get the encoding shared by every subscriber that negotiated the same content type. Keyed on the
+ * message object's identity, the serializer function (which is what `serializeMessage` output
+ * varies on), and the event's record `version`.
+ *
+ * The version is part of the key, not a permission to share. Identity alone would be unsafe for a
+ * producer that reuses one mutable envelope across publishes — an app Resource wrapping a table
+ * subscription to enrich events can easily do that, and copies the version straight through with a
+ * spread — so a cached entry whose version does not match is treated as a miss and re-encoded.
+ * That leaves only same-object-and-same-version mutation, which is indistinguishable from "the same
+ * message". An event with no version at all is not shared: nothing then distinguishes one publish
+ * from the next.
+ */
+export function getSharedMessageEncoding(message: any, request?: any, version?: number): SharedMessageEncoding {
+	// Negotiation must not run for a pass-through message: an Accept header naming only unsupported
+	// types throws 406, which would kill a delivery that used to succeed by returning message.data.
+	const serializer =
+		message?.contentType != null && message.data != null ? PASS_THROUGH : getMessageSerializer(request);
+	// primitives can not key a WeakMap, and are cheap to encode anyway; these stay per-subscriber
+	if (message === null || typeof message !== 'object' || typeof version !== 'number')
+		return encode(message, request, serializer);
+	let encoding = currentGeneration.get(message);
+	if (encoding === undefined) {
+		encoding = previousGeneration.get(message);
+		// promote a surviving entry so it lives through the next rotation
+		if (encoding !== undefined && encoding.version === version) retain(message, encoding);
+	}
+	if (encoding !== undefined && encoding.version !== version) {
+		// the same object carrying a new version: every content type on the chain is stale, so give
+		// back what the whole chain held and start over rather than serving the earlier message
+		release(encoding);
+		encoding = undefined;
+	}
+	if (encoding === undefined) {
+		retain(message, (encoding = encode(message, request, serializer, version)));
+		return encoding;
+	}
+	let last: SharedMessageEncoding;
+	do {
+		if (encoding.serializer === serializer) return reuse(encoding, message, request);
+		last = encoding;
+		encoding = encoding.next;
+	} while (encoding !== undefined);
+	// a second content type on an already-retained message is retained with it, so it is charged too
+	const chained = encode(message, request, serializer, version);
+	chained.epoch = last.epoch;
+	if (chained.epoch === currentEpoch) currentBytes += chained.bytes;
+	return (last.next = chained);
+}
+
+/**
+ * Resolve a still-pending shared serialization, retrying once through a fresh lookup if it failed.
+ * Every subscriber currently in the fan-out awaits the same promise, so without this one transient
+ * failure would disconnect all of them, where before the encoding was shared each subscriber
+ * serialized — and so retried — on its own.
+ */
+export async function resolveSharedPayload(
+	encoding: SharedMessageEncoding,
+	message: any,
+	request: any,
+	version?: number
+): Promise<Buffer | string> {
+	try {
+		return await (encoding.payload as Promise<Buffer | string>);
+	} catch (error) {
+		// otherwise a failure that the retry recovers from leaves no trace at all
+		logger.debug?.('Shared message serialization failed, retrying for this subscriber', error);
+		// The entry is marked for retry, or a peer in this same wave has already refilled it — either
+		// way, ask again. The first subscriber here re-encodes and the rest share that attempt; if it
+		// fails too, that rejection propagates and the caller handles it as it did before sharing.
+		return await getSharedMessageEncoding(message, request, version).payload;
+	}
+}
+
+/**
+ * Look up a fully encoded frame shared across subscribers, or undefined if it has not been
+ * generated yet. Split from `setSharedFrame` so a cache hit — the whole point on a fan-out —
+ * allocates nothing, not even a generator closure.
+ */
+export function getSharedFrame(encoding: SharedMessageEncoding, version: number, topic: string): Buffer | undefined {
+	return encoding.frames?.get(version)?.get(topic);
+}
+
+/**
+ * Store a generated frame for reuse by the remaining subscribers, and return it. Call only when
+ * `encoding.hits > 0`: a frame stored for a fan-out of one is never read, and would keep a whole
+ * PUBLISH buffer reachable from the message object for the rest of its retention window.
+ */
+export function setSharedFrame(encoding: SharedMessageEncoding, version: number, topic: string, frame: Buffer): Buffer {
+	let frames = encoding.frames;
+	if (frames === undefined) encoding.frames = frames = new Map();
+	let byTopic = frames.get(version);
+	if (byTopic === undefined) frames.set(version, (byTopic = new Map()));
+	// concurrent subscribers can each generate before any of them stores; only the retained buffer
+	// is charged, or the budget would bill every duplicate that is immediately garbage
+	if (!byTopic.has(topic)) charge(encoding, frame.byteLength);
+	byTopic.set(topic, frame);
+	return frame;
+}

package/server/serverHelpers/uwsServer.ts

@@ -225,8 +225,23 @@ export async function createUwsServer(options: UwsServerOptions): Promise<{ app:
 	app.any('/*', withBody);
 
 	await new Promise<void>((resolve, reject) => {
-		const onListen = (listenSocket: unknown) =>
-			listenSocket ? resolve() : reject(new Error(`uWS failed to bind ${host ?? ''}:${port ?? socketPath}`));
+		let settled = false;
+		// Backstop against the native listen callback never firing at all — without it, a stuck
+		// bind is indistinguishable from a slow one, and nothing here ever rejects.
+		const bindTimeout = setTimeout(() => {
+			if (settled) return;
+			settled = true;
+			reject(
+				new Error(`uWS timed out waiting to bind ${host ?? ''}:${port ?? socketPath} (listen callback never fired)`)
+			);
+		}, 30_000);
+		const onListen = (listenSocket: unknown) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(bindTimeout);
+			if (listenSocket) resolve();
+			else reject(new Error(`uWS failed to bind ${host ?? ''}:${port ?? socketPath}`));
+		};
 		// uWS shares the port across workers (SO_REUSEPORT) by default, matching the Node reusePort path.
 		if (port != null) {
 			if (host) app.listen(host, port, onListen);

package/server/static.ts

@@ -5,6 +5,7 @@ import { resolveBaseURLPath } from '../components/resolveBaseURLPath.ts';
 import { convertToMS } from '../utility/common_utils.ts';
 import { isMatch } from 'micromatch';
 import send from 'send';
+import { settleDeferredCredentialRejection } from '../security/deferredAuthentication.ts';
 
 /**
  * The static plugin handles serving static files from the respective application directory.
@@ -337,40 +338,30 @@ export function handleApplication(scope: Scope) {
 					// Retrieve index entry
 					staticFile = indexEntries.get(req.pathname);
 
-					// The router strips both '/assets' and '/assets/' down to '/', so the mount root
-					// must be disambiguated via the unstripped pathname (exposed by stripPrefix):
-					// redirect the no-slash form so relative links on the index page resolve under
-					// the mount (#1583). Query string is preserved across both redirects; compute it
-					// lazily inside each branch so the common (non-redirect) index serve stays allocation-free.
-					// Gated on the EXTERNAL base path, not the plugin-local one: a root-level static
-					// plugin (baseURLPath === '/') still needs this redirect when the application
-					// itself carries a host/urlPath mount, since the client-visible mount root is then
-					// externalBaseURLPath, not '/' (review finding).
-					if (staticFile && req.pathname === '/' && externalBaseURLPath !== '/') {
-						const originalPathname: string | undefined = (req as any).originalPathname;
-						if (originalPathname && !originalPathname.endsWith('/')) {
-							const queryIndex = (req.url as string).indexOf('?');
-							const query = queryIndex === -1 ? '' : (req.url as string).slice(queryIndex);
-							return {
-								status: 301,
-								headers: {
-									Location: externalBaseURLPath + query,
-								},
-							};
-						}
-					}
+					// Prefix stripping makes `originalPathname` necessary to distinguish mounted roots (#1583).
+					const originalPathname: string | undefined = (req as any).originalPathname;
+					const redirectsMountRoot = !!(
+						staticFile &&
+						req.pathname === '/' &&
+						externalBaseURLPath !== '/' &&
+						originalPathname &&
+						!originalPathname.endsWith('/')
+					);
 
-					// If `null`, redirect to trailing slash. req.pathname arrives with the mount
-					// prefix stripped, so rebuild the external path for the Location header (#1583)
-					if (staticFile === null) {
-						const externalPath =
-							externalBaseURLPath === '/' ? req.pathname : externalBaseURLPath.slice(0, -1) + req.pathname;
+					if (redirectsMountRoot || staticFile === null) {
+						const settledCredentialRejection = settleDeferredCredentialRejection(req);
+						if (settledCredentialRejection) return settledCredentialRejection;
 						const queryIndex = (req.url as string).indexOf('?');
 						const query = queryIndex === -1 ? '' : (req.url as string).slice(queryIndex);
+						const location = redirectsMountRoot
+							? externalBaseURLPath + query
+							: (externalBaseURLPath === '/' ? req.pathname : externalBaseURLPath.slice(0, -1) + req.pathname) +
+								'/' +
+								query;
 						return {
 							status: 301,
 							headers: {
-								Location: externalPath + '/' + query,
+								Location: location,
 							},
 						};
 					}
@@ -393,6 +384,8 @@ export function handleApplication(scope: Scope) {
 
 			// If an entry matched, serve it
 			if (staticFile) {
+				const settledCredentialRejection = settleDeferredCredentialRejection(req);
+				if (settledCredentialRejection) return settledCredentialRejection;
 				// The benefit to using `send` is that it handles a lot of edge cases and headers for us.
 				return {
 					handlesHeaders: true,
@@ -405,7 +398,8 @@ export function handleApplication(scope: Scope) {
 				return next(req);
 			}
 
-			// Otherwise, handle not found
+			const settledCredentialRejection = settleDeferredCredentialRejection(req);
+			if (settledCredentialRejection) return settledCredentialRejection;
 
 			const notFound = scope.options.get(['notFound']);
 

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');
@@ -128,6 +128,19 @@ export function onStorageReclamation(
 export function removeStorageReclamation(path: string): boolean {
 	return reclamationHandlers.delete(path);
 }
+
+/**
+ * Drop one handler; a RocksDB column family shares its path with every other family in the database.
+ * The list is replaced rather than spliced so a run iterating it across awaits skips nothing.
+ */
+export function removeStorageReclamationHandler(path: string, handler: (priority: number) => unknown): boolean {
+	const handlers = reclamationHandlers.get(path);
+	const remaining = handlers?.filter((entry) => entry.handler !== handler);
+	if (!remaining || remaining.length === handlers.length) return false;
+	if (remaining.length === 0) reclamationHandlers.delete(path);
+	else reclamationHandlers.set(path, remaining);
+	return true;
+}
 let reclamationTimer: NodeJS.Timeout;
 
 export type StorageSpaceStats = {

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] : [] };
+}

package/server/threads/itc.js

@@ -72,14 +72,24 @@ function validateEvent(event) {
  * @param schema
  * @param table
  * @param attribute
+ * @param branchPath the branch directory when the change is to a scope-private branch of `schema`
+ *   rather than to the database itself (resources/databases.ts `reloadBranchAt`)
  * @constructor
  */
-function SchemaEventMsg(originator, operation, schema, table = undefined, attribute = undefined) {
+function SchemaEventMsg(
+	originator,
+	operation,
+	schema,
+	table = undefined,
+	attribute = undefined,
+	branchPath = undefined
+) {
 	this.originator = originator;
 	this.operation = operation;
 	this.schema = schema;
 	this.table = table;
 	this.attribute = attribute;
+	if (branchPath) this.branchPath = branchPath;
 }
 
 /**