@harperfast/harper 5.2.0 → 5.2.2

package/server/http.ts

@@ -28,7 +28,7 @@ import {
 import { Blob } from '../resources/blob.ts';
 import { recordAction, recordActionBinary } from '../resources/analytics/write.ts';
 import { Readable, Writable, pipeline } from 'node:stream';
-import { mkdirSync, writeFileSync, unlinkSync, readdirSync } from 'node:fs';
+import { mkdirSync, writeFileSync, unlinkSync, readdirSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { server, type ServerOptions, type HttpOptions, type UpgradeOptions, UpgradeListener } from './Server.ts';
 import { setPortServerMap, SERVERS, socketOptionDefaults } from './serverRegistry.ts';
@@ -67,7 +67,14 @@ export const uwsServeConfigs: Record<string, any> = {};
 // backends that don't register their own Node http server (Bun, and the uWS HTTP path). Keeping
 // them out of SERVERS is what prevents a competing Node server from binding the same port.
 const fallbackServers: Record<string | number, any> = {};
-const udsCleanupPaths: { socketPath: string; yamlPath: string }[] = [];
+// `ino`/`dev` are set once this worker's own bind is confirmed (see recordUdsBindSuccess) and are
+// what make cleanupUdsFiles/markUdsBindFailed ownership-aware: on an overlapping restart (see
+// restartWorkers()), the replacement worker rebinds this exact path before the outgoing worker
+// exits, so by the time the outgoing worker cleans up, the identity on disk may already belong to
+// the replacement, not to it. Captured as bigint (statSync's `{ bigint: true }` form): a plain
+// Number loses precision above 2^53, which some filesystems (e.g. XFS with inode64) can exceed,
+// letting two genuinely different inodes compare equal.
+const udsCleanupPaths: { socketPath: string; yamlPath: string; identity?: { dev: bigint; ino: bigint } }[] = [];
 // Sockets whose listen() has failed (see threadServer.js's fail-soft UDS handling). A TLS mirror's
 // YAML metadata is written on its own schedule (SNICallback readiness / cert reload), independent of
 // whether the mirror socket ever actually bound, so a failed bind must both cancel any metadata write
@@ -79,24 +86,100 @@ export function registerUdsCleanupPaths(socketPath: string, yamlPath: string) {
 	udsCleanupPaths.push({ socketPath, yamlPath });
 }
 
-/** Mark a Unix domain socket's listen() as failed: suppress its metadata and remove any already written. */
+/**
+ * Record that this worker's own bind at `socketPath` succeeded, capturing the (dev, inode) pair that
+ * proves ownership. Call right after a mirror socket starts listening (see the bind sites in
+ * threadServer.js — the Node/h2/raw-socket mirrors via listenOnDomainSocket's onListening, the Bun
+ * path right after Bun.serve() returns, and the uWS path once createUwsServer() resolves). A no-op
+ * if `socketPath` was never registered.
+ */
+export function recordUdsBindSuccess(socketPath: string) {
+	const entry = udsCleanupPaths.find((candidate) => candidate.socketPath === socketPath);
+	if (!entry) return;
+	try {
+		const stat = statSync(socketPath, { bigint: true });
+		entry.identity = { dev: stat.dev, ino: stat.ino };
+	} catch (error) {
+		// Extremely unlikely (we just bound this path), but silent failure here is expensive: the
+		// entry is permanently treated as unowned, so this worker leaks both files at shutdown with
+		// nothing in the logs to explain why.
+		harperLogger.warn(`Could not stat freshly bound UDS mirror at ${socketPath}`, error);
+	}
+}
+
+/**
+ * 'owned' — the (dev, inode) this worker recorded at bind time still matches what's on disk.
+ * 'foreign' — a socket exists at the path, but with a different identity (or none was ever
+ *   recorded): something else — almost always a replacement worker — currently owns it. Also the
+ *   safe default when statSync fails for any reason other than ENOENT (e.g. EACCES): we can't
+ *   confirm the path is genuinely empty, so treat it as though something we can't verify owns it.
+ * 'absent' — statSync confirmed ENOENT: nothing is on disk at the path. There is no live owner to
+ *   protect.
+ */
+function ownershipOf(entry: {
+	socketPath: string;
+	identity?: { dev: bigint; ino: bigint };
+}): 'owned' | 'foreign' | 'absent' {
+	let current: { dev: bigint; ino: bigint };
+	try {
+		const stat = statSync(entry.socketPath, { bigint: true });
+		current = { dev: stat.dev, ino: stat.ino };
+	} catch (error) {
+		return (error as NodeJS.ErrnoException).code === 'ENOENT' ? 'absent' : 'foreign';
+	}
+	return entry.identity !== undefined && current.dev === entry.identity.dev && current.ino === entry.identity.ino
+		? 'owned'
+		: 'foreign';
+}
+
+/**
+ * Mark a Unix domain socket's listen() as failed: suppress its metadata, and remove any already
+ * written UNLESS a live socket at this path currently belongs to someone else (a replacement worker
+ * that already rebound it). Unlike cleanupUdsFiles, a failed bind never produced a socket of its own,
+ * so 'absent' here just means no bind ever won this path — not evidence of a live replacement — and
+ * is safe to retract stale metadata for (see server/DESIGN.md's UDS ownership note for why this can't
+ * require 'owned': the only real caller, an overlong path, fails before listen() ever runs, so this
+ * worker's own identity is never recorded).
+ */
 export function markUdsBindFailed(socketPath: string) {
 	failedUdsPaths.add(socketPath);
 	const entry = udsCleanupPaths.find((candidate) => candidate.socketPath === socketPath);
-	if (entry) {
-		try {
-			unlinkSync(entry.yamlPath);
-		} catch {}
-	}
+	if (!entry || ownershipOf(entry) === 'foreign') return;
+	try {
+		unlinkSync(entry.yamlPath);
+	} catch {}
 }
 
 export function cleanupUdsFiles() {
-	for (const { socketPath, yamlPath } of udsCleanupPaths) {
+	for (const entry of udsCleanupPaths) {
+		// ownershipOf() and the unlinks below are separate syscalls, so a replacement that unlinks
+		// and rebinds in the gap between them would still lose its files — unavoidable in Node
+		// (no unlink-if-inode-matches primitive), but this narrows that window from the
+		// seconds-wide one this fix closes down to microseconds.
+		const ownership = ownershipOf(entry);
+		// Consume this entry's recorded identity on first use, regardless of outcome. This function
+		// runs twice per worker (threadServer.js's SHUTDOWN handler, while this worker's own
+		// socket is still open, then again from process.on('exit') after closeServers() has
+		// released it) — and a freed inode can be handed to an unrelated later bind before the
+		// second call runs. Leaving the stale value in place would let that second call
+		// coincidentally re-match a path it no longer has any claim to; clearing it here makes a
+		// repeat call a guaranteed no-op instead of a second chance to delete a stranger's files.
+		entry.identity = undefined;
+		// Unlike markUdsBindFailed (where 'absent' is genuinely safe — its only caller runs
+		// synchronously before any bind attempt, with no window for anyone else to be mid-flight),
+		// this function's second call (process.on('exit')) can land seconds after the first, while
+		// a concurrently-booting replacement — on the non-overlapping-restart platforms, started
+		// right after this worker's SHUTDOWN, not after it fully exits — may have already written
+		// its own fresh yaml (SNICallback.ready resolves independently of its bind) without having
+		// bound its socket yet. Treating that window's 'absent' as retractable would delete the
+		// replacement's yaml out from under it. Only 'owned' is safe here; a stale yaml this worker
+		// never bound (or no longer owns) is left for markUdsBindFailed or the startup sweep.
+		if (ownership !== 'owned') continue;
 		try {
-			unlinkSync(socketPath);
+			unlinkSync(entry.socketPath);
 		} catch {}
 		try {
-			unlinkSync(yamlPath);
+			unlinkSync(entry.yamlPath);
 		} catch {}
 	}
 }
@@ -161,9 +244,13 @@ export function writeUdsMetadata(
 	}
 }
 
-/** Clean all files in the sockets directory. Call from main thread on process startup. */
+/**
+ * Clean all files in the sockets directory. Call from main thread on process startup, before any
+ * worker can bind. Unconditional on the current TLS_UNIXDOMAINSOCKETS setting — the directory is
+ * Harper-owned and holds nothing but mirror .sock/.yaml files, so a crash that left stale ones
+ * behind while UDS was enabled must still be swept even if this boot has since disabled it.
+ */
 export function cleanupSocketsDirectory() {
-	if (!env.get(terms.CONFIG_PARAMS.TLS_UNIXDOMAINSOCKETS)) return;
 	const socketsDir = join(env.getHdbBasePath(), 'sockets');
 	try {
 		for (const file of readdirSync(socketsDir)) {

package/server/operationsServer.ts

@@ -137,10 +137,8 @@ export interface ImpersonatePayload {
 
 interface BaseOperationRequestBody {
 	operation: OperationFunctionName;
-	bypassAuth: boolean;
 	hdb_user?: userSchema.User;
 	hdbAuthHeader?: unknown;
-	bypass_auth?: boolean;
 	impersonate?: ImpersonatePayload;
 	password?: string;
 	payload?: string;

package/server/serverHelpers/multipartParser.ts

@@ -11,6 +11,7 @@ interface MultipartBody {
 
 const FIELD_SIZE_LIMIT = 1024 * 1024; // 1 MB per non-file field — generous for JSON params
 const MAX_FIELDS = 64;
+const UNSAFE_FIELD_NAMES = new Set(['__proto__', 'constructor', 'prototype']);
 // Operation handlers stream the file part directly into extraction (gunzip + tar-fs),
 // so there is no separate filesize cap to enforce here. Backpressure flows through busboy
 // → the file Readable → the consumer, bounded by disk space rather than memory.
@@ -73,6 +74,14 @@ export function parseMultipartRequest(
 			logger.warn?.(`Multipart field "${name}" arrived after the file part; ignoring`);
 			return;
 		}
+		if (UNSAFE_FIELD_NAMES.has(name)) {
+			const error = new ClientError(`Multipart field "${name}" is not allowed`, 400);
+			callDone(error);
+			// Stop accepting bytes from a malicious request immediately. The raw-stream error
+			// handler below also tears down busboy, so a later file part cannot remain unread.
+			rawStream.destroy(error);
+			return;
+		}
 		body[name] = decodeFieldValue(value);
 	});
 

package/server/serverHelpers/operationAuthorizationState.ts

@@ -0,0 +1,11 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+const operationAuthorizationState = new AsyncLocalStorage<boolean>();
+
+export function runWithOperationAuthorizationBypass<T>(bypassAuth: boolean, callback: () => T): T {
+	return operationAuthorizationState.run(bypassAuth === true, callback);
+}
+
+export function isOperationAuthorizationBypassed(): boolean {
+	return operationAuthorizationState.getStore() === true;
+}

package/server/serverHelpers/registeredOperations.ts

@@ -27,6 +27,7 @@ import harperLogger from '../../utility/logging/harper_logger.ts';
 import { ServerError } from '../../utility/errors/hdbError.ts';
 import { sendItcEvent } from '../threads/itc.js';
 import { onMessageByType, onThreadExit } from '../threads/manageThreads.js';
+import { runWithOperationAuthorizationBypass } from './operationAuthorizationState.ts';
 
 const operationLog = harperLogger.loggerWithTag('operation');
 
@@ -49,7 +50,7 @@ const EXECUTE_TIMEOUT_MS = env.get(terms.CONFIG_PARAMS.OPERATIONSAPI_NETWORK_TIM
 // survive the dist build). A worker can only receive an execute request after announcing a
 // registration — which goes through serverUtilities — so these are always set on that path.
 let localDispatch: {
-	chooseOperation: (body: any) => Function;
+	chooseOperation: (body: any, bypassAuth?: boolean) => Function;
 	processLocalTransaction: (req: any, operationFunction: Function) => Promise<any>;
 };
 export function setLocalOperationDispatch(dispatch: typeof localDispatch) {
@@ -99,10 +100,13 @@ let rotation = 0;
  * function and metadata that `verifyPerms` needs only exist on the worker, which runs the full
  * `chooseOperation` check with the forwarded `hdb_user`.
  */
-export function getRemoteOperationFunction(name: string): ((body: any) => Promise<any>) | undefined {
+export function getRemoteOperationFunction(
+	name: string,
+	bypassAuth = false
+): ((body: any) => Promise<any>) | undefined {
 	if (!isMainThread) return undefined;
 	if (!registeredByWorker.has(name)) return undefined;
-	return (body: any) => executeRemoteOperation(name, body);
+	return (body: any) => executeRemoteOperation(name, body, bypassAuth);
 }
 
 function attachMainListeners() {
@@ -135,7 +139,7 @@ function attachMainListeners() {
 	});
 }
 
-async function executeRemoteOperation(name: string, body: any): Promise<any> {
+async function executeRemoteOperation(name: string, body: any, bypassAuth: boolean): Promise<any> {
 	attachMainListeners();
 	const workerIds = registeredByWorker.get(name);
 	const forwardBody = { ...body };
@@ -151,7 +155,7 @@ async function executeRemoteOperation(name: string, body: any): Promise<any> {
 		try {
 			sent = threads.sendToThread(targetThreadId, {
 				type: terms.ITC_EVENT_TYPES.OPERATION_EXECUTE_REQUEST,
-				message: { requestId, body: forwardBody, originator: threadId },
+				message: { requestId, body: forwardBody, bypassAuth, originator: threadId },
 			});
 		} catch (error) {
 			// Structured-clone failure (e.g. a function or native handle on the request body) is a
@@ -198,20 +202,20 @@ async function executeRemoteOperation(name: string, body: any): Promise<any> {
  * (permission check + processLocalTransaction) and send the result back to the main thread.
  */
 export async function operationExecuteRequestHandler(event: {
-	message: { requestId: number; body: any; originator: number };
+	message: { requestId: number; body: any; bypassAuth?: boolean; originator: number };
 }) {
-	const { requestId, body, originator } = event.message;
+	const { requestId, body, bypassAuth, originator } = event.message;
 	let response;
 	try {
 		if (!localDispatch) throw new ServerError('This worker thread cannot execute operations', 503);
-		// bypass_auth is trusted as forwarded: the main thread already strips it from external
-		// HTTP requests (handlePostRequest, before any dispatch decision), and an internal caller
-		// legitimately setting it (server.operation(op, context, false)) must see the same
-		// authorize:false behavior whether the operation happens to run locally or via this bridge.
-		// ITC is an internal, same-process trust boundary — a worker able to forge this message
-		// already has direct DB access and gains nothing by spoofing bypass_auth.
-		const operationFunction = localDispatch.chooseOperation(body);
-		const result = await localDispatch.processLocalTransaction({ body }, operationFunction);
+		// Authorization state travels in the trusted same-process ITC envelope, never in the
+		// caller-controlled operation body. This preserves server.operation(..., false) across
+		// worker forwarding without creating a client-spoofable request property.
+		const trustedBypassAuth = bypassAuth === true;
+		const result = await runWithOperationAuthorizationBypass(trustedBypassAuth, () => {
+			const operationFunction = localDispatch.chooseOperation(body, trustedBypassAuth);
+			return localDispatch.processLocalTransaction({ body }, operationFunction);
+		});
 		if (result instanceof Readable || typeof result?.pipe === 'function') {
 			// Streaming results would need MessagePort transfer plumbing — explicitly unsupported
 			// for worker-registered operations for now (#1736), rather than failing opaquely.

package/server/serverHelpers/serverHandlers.js

@@ -4,7 +4,7 @@ const terms = require('../../utility/hdbTerms.ts');
 const hdbUtil = require('../../utility/common_utils.ts');
 const harperLogger = require('../../utility/logging/harper_logger.ts');
 const { realExit } = require('../threads/workerProcessGuard.ts');
-const { handleHDBError, hdbErrors } = require('../../utility/errors/hdbError.ts');
+const { ClientError, handleHDBError, hdbErrors } = require('../../utility/errors/hdbError.ts');
 const { isMainThread } = require('worker_threads');
 const { Readable } = require('stream');
 
@@ -43,6 +43,19 @@ const NO_AUTH_OPERATIONS = [
 	terms.OPERATIONS_ENUM.LOGOUT,
 ];
 
+const UNSAFE_REQUEST_BODY_PROPERTIES = ['__proto__', 'constructor', 'prototype'];
+
+function validateRequestBodyProperties(body) {
+	if (!body || typeof body !== 'object') {
+		throw new ClientError('Invalid request body', 400);
+	}
+	for (const property of UNSAFE_REQUEST_BODY_PROPERTIES) {
+		if (Object.hasOwn(body, property)) {
+			throw new ClientError(`Request body property "${property}" is not allowed`, 400);
+		}
+	}
+}
+
 function handleServerUncaughtException(err) {
 	let message = `Found an uncaught exception with message: ${err.message}. ${os.EOL}Stack: ${err.stack} ${
 		os.EOL
@@ -145,8 +158,12 @@ async function handlePostRequest(req, res, _bypassAuth = false) {
 	let operation_function;
 
 	try {
-		// Just in case someone tries to bypass auth
-		if (req.body.bypass_auth) delete req.body.bypass_auth;
+		validateRequestBodyProperties(req.body);
+		// Authorization bypass is internal dispatch state, never client request data. Dispatch no
+		// longer reads these properties, but remove both true and false values before operation
+		// code sees the body.
+		if (Object.hasOwn(req.body, 'bypass_auth')) delete req.body.bypass_auth;
+		if (Object.hasOwn(req.body, 'bypassAuth')) delete req.body.bypassAuth;
 
 		operation_function = serverUtilities.chooseOperation(req.body);
 

package/server/serverHelpers/serverUtilities.ts

@@ -48,6 +48,7 @@ import {
 	getRemoteOperationFunction,
 	setLocalOperationDispatch,
 } from './registeredOperations.ts';
+import { runWithOperationAuthorizationBypass } from './operationAuthorizationState.ts';
 
 const pSearchSearch = util.promisify(search.search);
 let pEvaluateSql: (sql: string) => Promise<any>;
@@ -203,7 +204,7 @@ server.setMcpQuotaHandler = (handler) => {
 	setMcpQuotaHandler(handler);
 };
 
-export function chooseOperation(json: OperationRequestBody) {
+export function chooseOperation(json: OperationRequestBody, bypassAuth = false) {
 	let getOpResult: OperationFunctionObject;
 	try {
 		getOpResult = getOperationFunction(json);
@@ -214,7 +215,7 @@ export function chooseOperation(json: OperationRequestBody) {
 		// and its metadata actually exist, so no perm check is skipped by returning early
 		// here (#1736). Workers never re-forward, so an unknown op can't loop.
 		if (isMainThread) {
-			const remoteOperationFunction = getRemoteOperationFunction(json.operation);
+			const remoteOperationFunction = getRemoteOperationFunction(json.operation, bypassAuth);
 			if (remoteOperationFunction) return remoteOperationFunction;
 		}
 		operationLog.error(`Error when selecting operation function - ${err}`);
@@ -231,7 +232,7 @@ export function chooseOperation(json: OperationRequestBody) {
 			const sqlStatement = json.operation === 'sql' ? json.sql : json.search_operation.sql;
 			const parsedSqlObject = sql.convertSQLToAST(sqlStatement);
 			json.parsed_sql_object = parsedSqlObject;
-			if (!json.bypass_auth) {
+			if (!bypassAuth) {
 				const astPermCheck = sql.checkASTPermissions(json, parsedSqlObject);
 				if (astPermCheck) {
 					operationLog.error(`${HTTP_STATUS_CODES.FORBIDDEN} from operation ${json.operation}`);
@@ -248,7 +249,7 @@ export function chooseOperation(json: OperationRequestBody) {
 			}
 			//we need to bypass permission checks to allow the createAuthorizationTokens
 		} else if (
-			!json.bypass_auth &&
+			!bypassAuth &&
 			json.operation !== terms.OPERATIONS_ENUM.CREATE_AUTHENTICATION_TOKENS &&
 			json.operation !== terms.OPERATIONS_ENUM.LOGIN &&
 			json.operation !== terms.OPERATIONS_ENUM.LOGOUT
@@ -310,9 +311,11 @@ _assignPackageExport('operation', operation);
  */
 export function operation(operation: OperationRequestBody, context: Context, authorize: boolean) {
 	operation.hdb_user = context?.user;
-	operation.bypass_auth = !authorize;
-	const operation_function = chooseOperation(operation);
-	return processLocalTransaction({ body: operation }, operation_function);
+	const bypassAuth = !authorize;
+	return runWithOperationAuthorizationBypass(bypassAuth, () => {
+		const operation_function = chooseOperation(operation, bypassAuth);
+		return processLocalTransaction({ body: operation }, operation_function);
+	});
 }
 
 interface Transaction {

package/server/static.ts

@@ -1,5 +1,5 @@
 import { realpathSync, existsSync } from 'node:fs';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
 import { Scope } from '../components/Scope';
 import { resolveBaseURLPath } from '../components/resolveBaseURLPath.ts';
 import { convertToMS } from '../utility/common_utils.ts';
@@ -52,7 +52,7 @@ import send from 'send';
  *
  * This plugin dynamically updates its behavior based on the current configuration file. Users can make updates and immediately see the changes reflect in the next request.
  *
- * Updates to the `files` option will clear the in-memory maps and allow them to regenerate based on the new configuration (since the default EntryHandler will regenerate anyways).
+ * Updates to the `files` option incrementally add newly matched paths and remove paths that no longer match while preserving common entries.
  * Updates to `urlPath` request a restart: the HTTP route mount is registered once at load and cannot be re-registered on a live server (#1583).
  */
 /**
@@ -146,7 +146,40 @@ export function handleApplication(scope: Scope) {
 	// in-memory map of static files
 	// keys are the URL paths relative to the mount base, values are the absolute paths to the files
 	const staticFiles = new Map<string, string>();
-	const indexEntries = new Map<string, string>();
+	const indexEntries = new Map<string, string | null>();
+	const staticFileOwners = new Map<string, Map<string, string>>();
+	const indexEntryOwners = new Map<string, Map<string, string | null>>();
+
+	function setOwnedPath<Path>(
+		paths: Map<string, Path>,
+		ownersByURL: Map<string, Map<string, Path>>,
+		urlPath: string,
+		owner: string,
+		path: Path
+	) {
+		let owners = ownersByURL.get(urlPath);
+		if (!owners) ownersByURL.set(urlPath, (owners = new Map()));
+		owners.delete(owner);
+		owners.set(owner, path);
+		paths.set(urlPath, path);
+	}
+
+	function removeOwnedPath<Path>(
+		paths: Map<string, Path>,
+		ownersByURL: Map<string, Map<string, Path>>,
+		urlPath: string,
+		owner: string
+	) {
+		const owners = ownersByURL.get(urlPath);
+		if (!owners?.delete(owner)) return;
+		const replacement = [...owners.values()].at(-1);
+		if (replacement === undefined) {
+			ownersByURL.delete(urlPath);
+			paths.delete(urlPath);
+		} else {
+			paths.set(urlPath, replacement);
+		}
+	}
 
 	// The HTTP route below is registered once, with the urlPath in effect at load time; the mount
 	// cannot be re-registered at runtime. Capture the matching base once so map keys always agree
@@ -156,6 +189,9 @@ export function handleApplication(scope: Scope) {
 	// keep agreeing with the entry URL paths the file map is keyed by — but a redirect Location has
 	// to carry the application's mount too, or it would point outside the mount (#1583).
 	const externalBaseURLPath = scope.externalBasePath(baseURLPath);
+	let urlPathRestartPending = false;
+	let fileSelectionChangePending = false;
+	let entryHandler: ReturnType<Scope['handleEntry']>;
 
 	// A bare `before:` / `after:` key in YAML parses as null — treat it as unset, like before this
 	// option was validated.
@@ -187,14 +223,19 @@ export function handleApplication(scope: Scope) {
 
 	scope.options.on('change', (key) => {
 		if (key[0] === 'files') {
-			// If the files option changes, clear the maps and let the entry handler regenerate them
-			staticFiles.clear();
-			indexEntries.clear();
-			scope.logger.info(`Static files reinitialized due to change in ${key.join('.')}`);
+			fileSelectionChangePending = true;
+			const updateReady = entryHandler?.ready;
+			const clearPending = () => {
+				if (entryHandler?.ready === updateReady) fileSelectionChangePending = false;
+			};
+			updateReady?.then(clearPending, clearPending);
+			// EntryHandler updates are incremental: paths no longer matched emit unlink, newly matched
+			// paths emit add, and common unchanged paths remain valid in these maps.
+			scope.logger.info(`Static file matches updated due to change in ${key.join('.')}`);
 			return;
 		}
 		if (key[0] === 'urlPath') {
-			// The route mount cannot be changed on a live server registration — restart to apply
+			urlPathRestartPending = true;
 			scope.requestRestart();
 			return;
 		}
@@ -211,7 +252,12 @@ export function handleApplication(scope: Scope) {
 	});
 
 	// Handle entry events for the default entry handler based on the `files` and `urlPath` options
-	scope.handleEntry((entry) => {
+	entryHandler = scope.handleEntry((entry) => {
+		if (
+			urlPathRestartPending &&
+			(!fileSelectionChangePending || (entry.eventType !== 'unlink' && entry.eventType !== 'unlinkDir'))
+		)
+			return;
 		// entry.urlPath includes the component's base URL path, but when a `urlPath` is configured
 		// the routing chain strips that mount prefix from req.pathname before this plugin's handler
 		// runs — so key the maps relative to the base (#1583)
@@ -222,34 +268,43 @@ export function handleApplication(scope: Scope) {
 		switch (entry.eventType) {
 			// Directories only matter for the `index` files
 			case 'addDir':
-			case 'unlinkDir':
 				// Handle `index.html` for directories for if/when the user enables the `index` option
 				const indexPath = join(entry.absolutePath, 'index.html');
-				if (existsSync(indexPath)) {
-					indexEntries[entry.eventType === 'addDir' ? 'set' : 'delete'](urlPath, indexPath);
-				}
+				if (existsSync(indexPath)) setOwnedPath(indexEntries, indexEntryOwners, urlPath, entry.absolutePath, indexPath);
+				break;
+			case 'unlinkDir':
+				removeOwnedPath(indexEntries, indexEntryOwners, urlPath, entry.absolutePath);
 				break;
 			// Otherwise, user must specify pattern to match individual files
 			case 'add':
 				// Store the file in memory for serving
-				staticFiles.set(urlPath, entry.absolutePath);
+				setOwnedPath(staticFiles, staticFileOwners, urlPath, entry.absolutePath, entry.absolutePath);
 				// If the file is an index.html, also store it in the index entries
 				if (urlPath.endsWith('index.html')) {
 					// Without trailing slash; null -> 301 redirect to trailing slash
 					let lastSlashIndex = urlPath.lastIndexOf('/');
-					indexEntries.set(urlPath.slice(0, lastSlashIndex), null);
+					setOwnedPath(indexEntries, indexEntryOwners, urlPath.slice(0, lastSlashIndex), entry.absolutePath, null);
 					// With trailing slash; serves the index.html file
-					indexEntries.set(urlPath.slice(0, lastSlashIndex + 1), entry.absolutePath);
+					setOwnedPath(
+						indexEntries,
+						indexEntryOwners,
+						urlPath.slice(0, lastSlashIndex + 1),
+						entry.absolutePath,
+						entry.absolutePath
+					);
 				}
 				break;
 			case 'unlink':
-				// Remove the file from memory when it is deleted
-				staticFiles.delete(urlPath);
+				removeOwnedPath(staticFiles, staticFileOwners, urlPath, entry.absolutePath);
 				// If the file is an index.html, remove it from the index entries as well
 				if (urlPath.endsWith('index.html')) {
 					let lastSlashIndex = urlPath.lastIndexOf('/');
-					indexEntries.delete(urlPath.slice(0, lastSlashIndex));
-					indexEntries.delete(urlPath.slice(0, lastSlashIndex + 1));
+					const directoryURLPath = urlPath.slice(0, lastSlashIndex);
+					const directoryOwner = dirname(entry.absolutePath);
+					removeOwnedPath(indexEntries, indexEntryOwners, directoryURLPath, entry.absolutePath);
+					removeOwnedPath(indexEntries, indexEntryOwners, directoryURLPath, directoryOwner);
+					removeOwnedPath(indexEntries, indexEntryOwners, urlPath.slice(0, lastSlashIndex + 1), entry.absolutePath);
+					removeOwnedPath(indexEntries, indexEntryOwners, urlPath.slice(0, lastSlashIndex + 1), directoryOwner);
 				}
 				break;
 		}