@harperfast/harper 5.2.9 → 5.3.0-alpha.1

package/components/operationsValidation.js

@@ -13,7 +13,12 @@ const { ENV_ENCRYPTED_PREFIX } = require('../utility/envFile.ts');
 // File and project names can only be alphanumeric, dash and underscores. Both patterns are shared
 // with the CLI (utility/componentNames.ts): `harper deploy setup=true` resolves a project name and a
 // credential host client-side, and has to reject exactly what these schemas would.
-const { PROJECT_NAME_PATTERN: PROJECT_FILE_NAME_REGEX, GIT_HOST_PATTERN } = require('../utility/componentNames.ts');
+const {
+	PROJECT_NAME_PATTERN: PROJECT_FILE_NAME_REGEX,
+	GIT_HOST_PATTERN,
+	isReservedComponentName,
+} = require('../utility/componentNames.ts');
+const { assertBranchedDatabases } = require('./Application.ts');
 
 // dotenv's accepted key character set. Restricting keys to this prevents a crafted key (e.g. one
 // containing `=` or a newline) from injecting extra assignments into a .env file.
@@ -73,6 +78,31 @@ function checkProjectExists(checkExists, project, helpers) {
 	}
 }
 
+// Drop/package/file operations deliberately don't call this: an application deployed under the
+// name before it was reserved has to stay removable.
+function checkReservedProjectName(project, helpers) {
+	if (isReservedComponentName(project)) return helpers.message(HDB_ERROR_MSGS.RESERVED_PROJECT_NAME(project));
+	return project;
+}
+
+/**
+ * The file writers create the project directory as a side effect of writing into it, so they refuse
+ * only the creation — an application that already holds the name stays editable until it is
+ * migrated off it.
+ */
+function checkReservedProjectCreation(project, helpers) {
+	if (!isReservedComponentName(project)) return project;
+	let projectDir;
+	try {
+		const componentsRoot = configUtils.getConfigPath(hdbTerms.CONFIG_PARAMS.COMPONENTSROOT);
+		if (componentsRoot) projectDir = path.join(componentsRoot, project);
+	} catch (err) {
+		hdbLogger.error(err);
+	}
+	if (projectDir && fs.existsSync(projectDir)) return project;
+	return helpers.message(HDB_ERROR_MSGS.RESERVED_PROJECT_NAME(project));
+}
+
 function checkFilePath(path, helpers) {
 	if (path.includes('..')) return helpers.message('Invalid file path');
 	return path;
@@ -154,6 +184,7 @@ function setComponentFileValidator(req) {
 	const setCompSchema = Joi.object({
 		project: Joi.string()
 			.pattern(PROJECT_FILE_NAME_REGEX)
+			.custom(checkReservedProjectCreation)
 			.required()
 			.messages({ 'string.pattern.base': HDB_ERROR_MSGS.BAD_PROJECT_NAME }),
 		file: Joi.string().custom(checkFilePath).required(),
@@ -214,6 +245,7 @@ function setEnvValueValidator(req) {
 	const schema = Joi.object({
 		project: Joi.string()
 			.pattern(PROJECT_FILE_NAME_REGEX)
+			.custom(checkReservedProjectCreation)
 			.required()
 			.messages({ 'string.pattern.base': HDB_ERROR_MSGS.BAD_PROJECT_NAME }),
 		file: Joi.string().custom(checkFilePath).optional(),
@@ -330,6 +362,7 @@ function addComponentValidator(req) {
 	const addFuncSchema = Joi.object({
 		project: Joi.string()
 			.pattern(PROJECT_FILE_NAME_REGEX)
+			.custom(checkReservedProjectName)
 			.custom(checkProjectExists.bind(null, false))
 			.required()
 			.messages({ 'string.pattern.base': HDB_ERROR_MSGS.BAD_PROJECT_NAME }),
@@ -455,6 +488,7 @@ function deployComponentValidator(req) {
 	const deployProjSchema = Joi.object({
 		project: Joi.string()
 			.pattern(PROJECT_FILE_NAME_REGEX)
+			.custom(checkReservedProjectName)
 			.required()
 			.messages({ 'string.pattern.base': HDB_ERROR_MSGS.BAD_PROJECT_NAME }),
 		package: Joi.string().optional(),
@@ -496,6 +530,20 @@ function deployComponentValidator(req) {
 			})
 			.optional()
 			.messages({ 'string.bracketedHost': '{#label} must not be bracketed; use the bare IPv6 literal' }),
+		// Databases this application forks a private copy of (harper#642/#643). Deployment routing
+		// like urlPath/host above, not component config: reusing assertBranchedDatabases here (rather
+		// than re-deriving its rules in Joi) gives a synchronous 400 at deploy time instead of a load
+		// failure discovered much later and disconnected from the request that caused it.
+		branchedDatabases: Joi.custom((value, helpers) => {
+			try {
+				assertBranchedDatabases(req.project, value);
+			} catch (error) {
+				return helpers.error('any.invalid', { reason: error.message });
+			}
+			return value;
+		}, 'branchedDatabases')
+			.optional()
+			.messages({ 'any.invalid': '{{#reason}}' }),
 		// Deploy credentials. The array is kind-heterogeneous: an entry's kind is implied by its
 		// identifying key rather than a separate discriminator field, so a new kind is added as
 		// another item alternative here without reshaping the field. Today: npm registry auth

package/components/status/ComponentStatusRegistry.ts

@@ -5,6 +5,7 @@
  * centralized management of component health status.
  */
 
+import { deployValidationStatusSink } from '../../server/serverHelpers/deployValidationState.ts';
 import { ComponentStatus } from './ComponentStatus.ts';
 import {
 	type ComponentStatusLevel,
@@ -24,6 +25,37 @@ export type ComponentStatusMap = Map<string, ComponentStatus>;
  * Component Status Registry Class
  * Provides a centralized registry for managing component health status
  */
+/**
+ * A status copy handed to a validation must share nothing mutable with the live entry. `Error` is reachable
+ * through the public `statusForComponent(...).get()` path, so candidate code could otherwise edit
+ * `message`, `cause` or a custom field on the serving component's own error object. Own enumerable
+ * properties are carried across; `cause` is flattened to a message, because an error graph of unknown depth
+ * is not worth cloning to hand a throwaway load its own read.
+ */
+function detachError(error: Error | string | undefined): Error | string | undefined {
+	if (!(error instanceof Error)) return error;
+	const detached = new Error(error.message);
+	detached.name = error.name;
+	detached.stack = error.stack;
+	for (const [key, value] of Object.entries(error)) {
+		if (key === 'cause') continue;
+		// Detached too where it can be: copying an object property by reference would leave the candidate a
+		// mutable handle into the live error after all. Anything unclonable (a function, a class instance) is
+		// replaced by its string form rather than shared.
+		let detachedValue: unknown;
+		try {
+			detachedValue = structuredClone(value);
+		} catch {
+			detachedValue = typeof value === 'object' && value !== null ? String(value) : value;
+		}
+		(detached as unknown as Record<string, unknown>)[key] = detachedValue;
+	}
+	if (error.cause !== undefined) {
+		detached.cause = error.cause instanceof Error ? `${error.cause.name}: ${error.cause.message}` : error.cause;
+	}
+	return detached;
+}
+
 export class ComponentStatusRegistry {
 	private statusMap: ComponentStatusMap = new Map();
 
@@ -61,6 +93,16 @@ export class ComponentStatusRegistry {
 			);
 		}
 
+		// A deploy's pre-flight validation loads the CANDIDATE's code under the real component's name, so its
+		// writes would land on the live component. They go to the validation's own throwaway map instead —
+		// which is why this cannot simply be reverted afterwards: the live component keeps serving through
+		// that window, and `statusForComponent()` is a public API its own code may call at any time, so
+		// reverting would silently discard a genuine report from it.
+		const sink = deployValidationStatusSink();
+		if (sink) {
+			sink.set(componentName, new ComponentStatus(status, message, error));
+			return;
+		}
 		this.statusMap.set(componentName, new ComponentStatus(status, message, error));
 	}
 
@@ -68,6 +110,23 @@ export class ComponentStatusRegistry {
 	 * Get the current status of a component
 	 */
 	public getStatus(componentName: string): ComponentStatus | undefined {
+		// Inside a validation the candidate reads its OWN writes, and never the live object: the returned
+		// `ComponentStatus` is mutable, so handing back the live one would let candidate code edit the
+		// serving component's status in place and bypass the diversion entirely. A component the candidate
+		// has not written yet is copied into the sink on first read for the same reason.
+		const sink = deployValidationStatusSink();
+		if (sink) {
+			const diverted = sink.get(componentName);
+			if (diverted) return diverted;
+			const live = this.statusMap.get(componentName);
+			if (!live) return undefined;
+			const copy = new ComponentStatus(live.status, live.message, detachError(live.error));
+			// A new Date, not the live one: `Date` is mutable, so sharing it would let candidate code reach
+			// back into the serving component's status through the copy.
+			copy.lastChecked = new Date(live.lastChecked);
+			sink.set(componentName, copy);
+			return copy;
+		}
 		return this.statusMap.get(componentName);
 	}
 

package/config/RootConfigWatcher.ts

@@ -1,23 +1,49 @@
-import chokidar, { FSWatcher } from 'chokidar';
-import { readFile } from 'node:fs/promises';
+import { FSWatcher } from 'chokidar';
+import { readFileSync } from 'node:fs';
 import { getConfigFilePath } from './configUtils.ts';
 import { EventEmitter, once } from 'node:events';
 import { parse } from 'yaml';
-import { POLLING_FALLBACK_OPTIONS, isWatcherExhaustionError, warnWatcherFallback } from '../utility/watcherFallback.ts';
+import {
+	POLLING_FALLBACK_OPTIONS,
+	PartialReadRetry,
+	claimLostNativeWatchError,
+	guardedWatch,
+	isPartialReadError,
+	isWatcherExhaustionError,
+	warnWatcherFallback,
+	warnWatcherListenerError,
+} from '../utility/watcherFallback.ts';
+import { resolveWatchTarget } from '../utility/watchPath.ts';
+
+let sharedWatcher: RootConfigWatcher | undefined;
+
+/**
+ * The isolate-wide watcher for the root config file. Consumers (logging, models) subscribe to this
+ * one instance instead of each opening their own native watcher — per-worker duplicates double the
+ * inotify/FD footprint and the synchronous read+parse work on every config write.
+ */
+export function getSharedRootConfigWatcher(): RootConfigWatcher {
+	return (sharedWatcher ??= new RootConfigWatcher());
+}
 
 export class RootConfigWatcher extends EventEmitter {
 	#configFilePath: string;
+	#watchPath: string;
 	#watcher!: FSWatcher;
 	#config: any;
 	#usingPolling: boolean;
 	#closed: boolean;
 	#openCount: number = 0;
+	#partialRead: PartialReadRetry;
 	ready: Promise<any[]>;
 
-	constructor() {
+	constructor(configFilePath: string = getConfigFilePath()) {
 		super();
-		this.#configFilePath = getConfigFilePath();
-		this.#usingPolling = false;
+		this.#configFilePath = configFilePath;
+		const watchTarget = resolveWatchTarget(this.#configFilePath);
+		this.#watchPath = watchTarget.path;
+		this.#partialRead = new PartialReadRetry(this.#configFilePath);
+		this.#usingPolling = watchTarget.mustPoll;
 		this.#closed = false;
 		this.ready = once(this, 'ready');
 		this.#openWatcher();
@@ -25,11 +51,10 @@ export class RootConfigWatcher extends EventEmitter {
 
 	#openWatcher() {
 		this.#openCount++;
-		this.#watcher = chokidar
-			.watch(this.#configFilePath, {
-				persistent: false,
-				...(this.#usingPolling ? POLLING_FALLBACK_OPTIONS : {}),
-			})
+		this.#watcher = guardedWatch(this.#watchPath, {
+			persistent: false,
+			...(this.#usingPolling ? POLLING_FALLBACK_OPTIONS : {}),
+		})
 			.on('add', this.handleChange.bind(this))
 			.on('change', this.handleChange.bind(this))
 			.on('error', this.handleError.bind(this));
@@ -53,6 +78,9 @@ export class RootConfigWatcher extends EventEmitter {
 	}
 
 	handleError(error: unknown) {
+		// See EntryHandler.#handleWatcherError: a lost native watch handle is benign
+		// and must not be surfaced to consumers as a config-watch failure.
+		if (claimLostNativeWatchError(error)) return;
 		if (isWatcherExhaustionError(error)) {
 			// Swallow every exhaustion error — chokidar can emit several before the
 			// failed native watcher closes, and we don't want a flurry of ENOSPC to
@@ -60,46 +88,64 @@ export class RootConfigWatcher extends EventEmitter {
 			if (!this.#usingPolling) {
 				warnWatcherFallback(this.#configFilePath);
 				this.#usingPolling = true;
-				// Guard against reopen-after-close: the caller may have invoked
-				// close() while this teardown was in flight. The .catch is required
-				// because `finally` would re-raise a teardown rejection as an
-				// unhandled one.
-				this.#watcher
-					.close()
+				// Start close() from a microtask, not directly here, so a synchronous throw
+				// can't escape this 'error' listener as an uncaught exception.
+				Promise.resolve()
+					.then(() => this.#watcher.close())
 					.catch(() => {
 						// Teardown errors on an already-failed watcher are not actionable.
 					})
-					.finally(() => {
+					.then(() => {
 						if (!this.#closed) this.#openWatcher();
-					});
+					})
+					.catch((error) => console.error(`Could not reopen the ${this.#configFilePath} watch on polling:`, error));
 			}
 			return;
 		}
 		this.emit('error', error);
 	}
 
+	// See the descriptor-lifetime invariant on atomicWriteFile (DESIGN.md).
 	handleChange() {
-		readFile(this.#configFilePath, 'utf-8')
-			.then((data) => {
-				if (!data) return;
-
-				const config = parse(data);
+		let config;
+		// Only the read and parse are guarded: a listener that throws must not be mistaken for a
+		// half-written file and replayed.
+		try {
+			config = parse(readFileSync(this.#configFilePath, 'utf-8'));
+		} catch (error) {
+			// A missing file needs no re-read; anything else may be the file being replaced.
+			if (isPartialReadError(error)) this.#scheduleReread(error);
+			return;
+		}
+		// A snapshot that does not parse to an object is the other shape a half-written file
+		// takes: `''`, `'\n'` and a truncated document all yield null, and adopting that would
+		// hand every consumer a config with nothing in it.
+		if (!config || typeof config !== 'object') {
+			this.#scheduleReread();
+			return;
+		}
+		this.#partialRead.settled();
 
-				if (!this.#config) {
-					this.#config = config;
-					this.emit('ready', this.#config);
-					return;
-				}
+		try {
+			if (!this.#config) {
+				this.#config = config;
+				this.emit('ready', this.#config);
+				return;
+			}
+			this.emit('change', (this.#config = config));
+		} catch (error) {
+			warnWatcherListenerError(this.#configFilePath, error);
+		}
+	}
 
-				this.emit('change', (this.#config = config));
-			})
-			.catch((_error) => {
-				// if yaml parse error ignore?
-			});
+	#scheduleReread(error?: unknown) {
+		if (this.#partialRead.schedule(() => this.handleChange())) return;
+		this.#partialRead.gaveUp(error);
 	}
 
 	close() {
 		this.#closed = true;
+		this.#partialRead.cancel();
 		this.#watcher.close();
 		this.#config = undefined;
 		this.emit('close');