@harperfast/harper 5.2.0 → 5.2.2

package/utility/environment/environmentManager.ts

@@ -9,6 +9,7 @@ import * as commonUtils from '../common_utils.ts';
 import * as hdbTerms from '../hdbTerms.ts';
 import * as configUtils from '../../config/configUtils.ts';
 import { mkdirSync } from 'node:fs';
+import { workerData } from 'node:worker_threads';
 
 const INIT_ERR = 'Error initializing environment manager';
 const BOOT_PROPS_FILE_PATH = 'BOOT_PROPS_FILE_PATH';
@@ -24,6 +25,19 @@ const installPropsToSave = {
 let installProps: any = {};
 export { BOOT_PROPS_FILE_PATH };
 
+// Every param passed to setProperty() on this thread, keyed by its canonical config param so
+// aliases collapse to one last-write-wins entry. Workers inherit this map (getConfigOverrides() and
+// the workerDataProvider registration in server/threads/manageThreads.js) and it is replayed after
+// a forced config reload; `base` is the configured value the override displaced, which is how
+// reapplyAllOverrides() tells a reload that left the param alone from one that is itself the change.
+//
+// setProperty() therefore means operator/harness *intent* only. Code caching a value it derived
+// from config it just read (initializePaths.js, utility/lmdb/environmentUtility.ts) must call
+// configUtils.updateConfigObject() directly, or the derived value outlives what it was derived from
+// and ships to every worker as an override.
+const appliedOverrides = new Map<string, { value: any; base: any }>();
+let inheritedOverridesApplied = false;
+
 /**
  * The base path of the HDB install is often referenced, but is referenced as a const variable at the top of many
  * modules.  This is a problem during install, as the path may not yet be defined.  We offer a function to get the
@@ -62,11 +76,42 @@ export function get(propName: string): any {
  * Note - this function will NOT update the config file. If you want to update the file
  * use the updateConfigValue method in configUtils.
  *
+ * The override is also recorded so it propagates to every worker thread spawned from here and
+ * survives a forced config reload — except a reload that changes this param on disk, which wins
+ * and retires the override (see reapplyAllOverrides()). `value` must be structured-cloneable.
+ *
  * This function should only be used by the installer and unit tests.
  * @param propName
  * @param value
  */
 export function setProperty(propName: string, value: any) {
+	// Snapshot rather than keep the caller's reference: initializePaths.js and environmentUtility.ts
+	// cache derived per-database paths by mutating the live `databases` value in place, which is
+	// often the very object handed to setProperty. Cloning here also settles cloneability at the
+	// caller that can still fix it — manageThreads.js's provider only logs a clone failure and
+	// spawns the worker on the on-disk config anyway.
+	let snapshot;
+	try {
+		snapshot = structuredClone(value);
+	} catch (err) {
+		throw new Error(`Config property '${propName}' cannot be set to a value that is not structured-cloneable`, {
+			cause: err,
+		});
+	}
+
+	// Key by the canonical param name, not the raw alias passed in: CONFIG_PARAM_MAP is many-to-one
+	// (e.g. SERVER_PORT_KEY and OPERATIONSAPI_NETWORK_PORT both canonicalize to
+	// 'operationsApi_network_port'), and replay of a stale alias after the canonical one would
+	// reintroduce the parent/worker skew this map exists to prevent.
+	const canonicalName = (hdbTerms.CONFIG_PARAM_MAP as any)[propName.toLowerCase()] ?? propName;
+	const existing = appliedOverrides.get(canonicalName);
+	appliedOverrides.set(canonicalName, {
+		value: snapshot,
+		// Keep the first override's base: everything after it displaced an override, not a
+		// configured value, so it says nothing about what the config file held.
+		base: existing ? existing.base : snapshotConfigValue(configUtils.getConfigValue(propName)),
+	});
+
 	if (installPropsToSave[propName]) {
 		installProps[propName] = value;
 	}
@@ -74,6 +119,98 @@ export function setProperty(propName: string, value: any) {
 	configUtils.updateConfigObject(propName, value);
 }
 
+/**
+ * Every config override applied on this thread via setProperty(), for propagation to worker
+ * threads spawned from here (see server/threads/manageThreads.js's 'configOverrides'
+ * workerData provider). Returns undefined when nothing has been overridden, so a normal
+ * production boot contributes no extra workerData.
+ */
+export function getConfigOverrides(): Record<string, any> | undefined {
+	if (!appliedOverrides.size) return undefined;
+	const overrides = {};
+	for (const [propName, { value }] of appliedOverrides) {
+		overrides[propName] = value;
+	}
+	return overrides;
+}
+
+/**
+ * Replays the parent thread's config overrides (received via workerData) on THIS thread, so a
+ * worker's effective config matches its parent's rather than silently falling back to whatever
+ * is installed on disk. Applied once per thread, right after the on-disk config is first read —
+ * see initSync(). A later forced re-init is handled separately by reapplyAllOverrides(), since by
+ * then these inherited values are already folded into appliedOverrides.
+ */
+function applyInheritedConfigOverrides() {
+	const inherited = (workerData as any)?.configOverrides;
+	if (!inherited) return;
+	for (const propName of Object.keys(inherited)) {
+		setProperty(propName, inherited[propName]);
+	}
+}
+
+/** Detached copy of a config value; falls back to the value itself for the (unreached) non-cloneable case. */
+function snapshotConfigValue(value: any) {
+	try {
+		return structuredClone(value);
+	} catch {
+		return value;
+	}
+}
+
+/** Key-ordering is a YAML formatting choice, not a config change, so it must not affect equality. */
+function stableStringify(value: any) {
+	if (value === null || typeof value !== 'object') return JSON.stringify(value);
+	if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]`;
+	return `{${Object.keys(value)
+		.sort()
+		.map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`)
+		.join(',')}}`;
+}
+
+/**
+ * A reload rebuilds config values into fresh objects, so identity says nothing about whether the
+ * file changed. Anything this cannot serialize (a cyclic value, which structuredClone accepts)
+ * counts as changed rather than throwing out of the reload path — initSync()'s catch exits the
+ * process.
+ */
+function sameConfigValue(a: any, b: any) {
+	if (Object.is(a, b)) return true;
+	if (a === null || b === null || typeof a !== 'object' || typeof b !== 'object') return false;
+	try {
+		return stableStringify(a) === stableStringify(b);
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Replays this thread's overrides on top of a config that was just re-read from disk. A forced
+ * initSync() rebuilds the whole config, which would otherwise revert the thread to the on-disk
+ * config regardless of any overrides — the same defect applyInheritedConfigOverrides() closes for a
+ * worker's first boot, but for a reload on any thread, main included.
+ *
+ * An override does NOT survive a reload that changed its own param on disk. A forced reload is how
+ * an operator's config edit takes effect (the RESTART handlers in security/keys.ts and
+ * processManagement.js), so replaying unconditionally would make editing an overridden param a
+ * silent no-op for the life of the process. The edit is the newer intent, so the override retires
+ * entirely — dropped from the map, so it stops reaching newly spawned workers as well.
+ *
+ * Call only after configUtils.initConfig(force) has repopulated the config from disk.
+ */
+function reapplyAllOverrides() {
+	if (appliedOverrides.size === 0) return;
+	// Iterate a snapshot: setProperty() re-inserts into appliedOverrides as we go.
+	for (const [propName, { value, base }] of [...appliedOverrides]) {
+		if (!sameConfigValue(configUtils.getConfigValue(propName), base)) {
+			appliedOverrides.delete(propName);
+			log.notify(`Config reload changed '${propName}'; dropping this thread's in-process override of it`);
+			continue;
+		}
+		setProperty(propName, value);
+	}
+}
+
 /**
  * Checks to see if the Harper boot props file exists.
  * If it does, it grabs the install user and settings path for future reference.
@@ -108,6 +245,21 @@ export function initSync(force: boolean = false) {
 	try {
 		if (propFileExists || doesPropFileExist() || commonUtils.noBootFile() || force) {
 			configUtils.initConfig(force);
+			if (!inheritedOverridesApplied) {
+				inheritedOverridesApplied = true;
+				applyInheritedConfigOverrides();
+			}
+			// force implies the on-disk config was just re-read from scratch, which would otherwise
+			// silently drop every override applied on this thread so far (inherited or local) —
+			// except the ones the re-read itself changed, which the config file wins.
+			if (force) reapplyAllOverrides();
+
+			// Sync installProps' HDB_ROOT from the config's rootPath *after* any override replay
+			// above (not before): setProperty() records a rootPath override under its canonical
+			// CONFIG_PARAM_MAP name, not under HDB_ROOT_KEY, so replaying it doesn't retrigger this
+			// same side effect below in setProperty() — this sync is what makes getHdbBasePath()
+			// track an isolated rootPath override instead of staying pinned to whatever the pre-replay
+			// disk read produced.
 			const configHdbRoot = configUtils.getConfigValue(hdbTerms.HDB_SETTINGS_NAMES.HDB_ROOT_KEY);
 			// Only overwrite if we actually got a value from config
 			if (configHdbRoot !== undefined) {

package/utility/errors/commonErrors.ts

@@ -200,6 +200,8 @@ const USER_ERROR_MSGS = {
 	ALTER_USER_ROLE_NOT_FOUND: (role) => `Update failed.  Requested '${role}' role not found.`,
 	DUP_ROLES_FOUND: (role) =>
 		`Multiple ${role} roles found.  Roles must have unique 'role' value. Please update and try again.`,
+	LAST_SUPER_USER:
+		'Rejected: this change would leave the instance with no active super_user. Grant super_user to another active user first.',
 	ROLE_NAME_NOT_FOUND: (role) => `${role} role not found`,
 	USER_ALREADY_EXISTS: (user) => `User ${user} already exists`,
 	USER_NOT_EXIST: (user) => `User ${user} does not exist`,

package/utility/hdbTerms.ts

@@ -553,6 +553,7 @@ export const CONFIG_PARAMS = {
 	LICENSE_MODE: 'license_mode',
 	LICENSE_REGION: 'license_region',
 	LOCALSTUDIO_ENABLED: 'localStudio_enabled',
+	MODELSGATEWAY_ENABLED: 'modelsGateway_enabled',
 	LOGGING_COLORS: 'logging_colors',
 	LOGGING_CONSOLE: 'logging_console',
 	LOGGING_FILE: 'logging_file',
@@ -693,6 +694,7 @@ export const CONFIG_PARAMS = {
 	STORAGE_TRANSACTIONLOG_COOLINGINTERVAL: 'storage_transactionLog_coolingInterval',
 	STORAGE_ENGINE: 'storage_engine',
 	STORAGE_READONLY: 'storage_readOnly',
+	STORAGE_ROCKS_COMPRESSION: 'storage_rocks_compression',
 	STORAGE_ROCKS_BLOCKCACHESIZE: 'storage_rocks_blockCacheSize',
 	STORAGE_ROCKS_WRITEBUFFERMANAGERSIZE: 'storage_rocks_writeBufferManagerSize',
 	STORAGE_ROCKS_WRITEBUFFERMANAGERCOSTTOCACHE: 'storage_rocks_writeBufferManagerCostToCache',

package/utility/install/installer.ts

@@ -19,6 +19,7 @@ import * as hdbTerms from '../hdbTerms.ts';
 const { CONFIG_PARAMS } = hdbTerms;
 import installValidator from '../../validation/installValidator.ts';
 import mountHdb from '../mount_hdb.ts';
+import { composeConfigFromEnv } from '../../config/harperConfigEnvVars.ts';
 import * as configUtils from '../../config/configUtils.ts';
 import * as userOps from '../../security/user.ts';
 import * as roleOps from '../../security/role.ts';
@@ -197,6 +198,7 @@ async function install() {
 	}
 	envManager.setHdbBasePath(hdbRoot);
 	envManager.setProperty(hdbTerms.CONFIG_PARAMS.STORAGE_ENGINE, installParams.STORAGE_ENGINE);
+	stageRocksCompression();
 
 	// Creates the Harper project folder structure and the LMDB environments/dbis.
 	await mountHdb(hdbRoot);
@@ -575,6 +577,41 @@ export function applyInstallModeDefaults(args, defaultsMode) {
  * @param installParams
  * @returns {Promise<void>}
  */
+/**
+ * Make the deployment codec readable before `mountHdb()` creates the system column families.
+ *
+ * The config file is not written until `createConfigFile()`, several steps after `mountHdb()`, but
+ * RocksDB fixes a column family's codec when the family is created and refuses a later reopen that
+ * asks for a different one — and worker threads share one process-wide family registry. Left
+ * unstaged, the main thread creates `__dbis__` at the build default while every worker resolves the
+ * configured codec, and Harper dies with "The system database failed to load". Staging it in the
+ * in-memory config here is the same trick the STORAGE_ENGINE line above uses.
+ *
+ * Checked in the same precedence `createConfigFile()` itself later resolves the value with, so
+ * `storage.compression` also participates when no explicit RocksDB codec is set: its default is
+ * true, which resolves to lz4. Stage both values from every source `createConfigFile()` honors so
+ * the first open cannot create `__dbis__` with `none` and later workers reopen it with lz4.
+ */
+function stageRocksCompression() {
+	const rocksCompression = hdbTerms.CONFIG_PARAMS.STORAGE_ROCKS_COMPRESSION;
+	const compression = hdbTerms.CONFIG_PARAMS.STORAGE_COMPRESSION;
+	const envConfig = composeConfigFromEnv();
+	const commandLineConfig = assignCMDENVVariables([rocksCompression, compression], true);
+	const fileConfig = cfgEnv[hdbTerms.INSTALL_PROMPTS.HDB_CONFIG] ? getConfigFromFile() : {};
+	const configuredRocksCompression =
+		envConfig?.storage?.rocks?.compression ?? commandLineConfig[rocksCompression] ?? fileConfig[rocksCompression];
+	const configuredCompression =
+		envConfig?.storage?.compression ?? commandLineConfig[compression] ?? fileConfig[compression] ?? true;
+	if (
+		configuredRocksCompression !== undefined &&
+		configuredRocksCompression !== null &&
+		configuredRocksCompression !== ''
+	) {
+		envManager.setProperty(rocksCompression, configuredRocksCompression);
+	}
+	envManager.setProperty(compression, configuredCompression);
+}
+
 async function createConfigFile(installParams) {
 	hdbLogger.trace('Creating Harper config file');
 	const args = assignCMDENVVariables(Object.keys(hdbTerms.CONFIG_PARAM_MAP), true);

package/utility/lmdb/environmentUtility.ts

@@ -13,6 +13,7 @@ import * as lmdbTerms from './terms.ts';
 import * as hdbTerms from '../hdbTerms.ts';
 import { resetDatabases } from '../../resources/databases.ts';
 import * as envMngr from '../environment/environmentManager.ts';
+import { updateConfigObject } from '../../config/configUtils.ts';
 
 const INTERNAL_DBIS_NAME = lmdbTerms.INTERNAL_DBIS_NAME;
 const DBI_DEFINITION_NAME = lmdbTerms.DBI_DEFINITION_NAME;
@@ -109,7 +110,7 @@ export async function createEnvironment(
 
 	envName = envName.toString();
 	let schemasConfig = envMngr.get(hdbTerms.CONFIG_PARAMS.DATABASES);
-	if (!schemasConfig) envMngr.setProperty(hdbTerms.CONFIG_PARAMS.DATABASES, (schemasConfig = {}));
+	if (!schemasConfig) updateConfigObject(hdbTerms.CONFIG_PARAMS.DATABASES, (schemasConfig = {}));
 	if (!schemasConfig[dbName]) schemasConfig[dbName] = {};
 	schemasConfig[dbName].path = basePath;
 	try {

package/utility/logging/harper_logger.ts

@@ -381,14 +381,34 @@ module.exports = {
 	inspectForLog,
 	isErrorLike,
 	disableStdio,
+	isStdioBrokenError,
 	externalLogger,
 };
 
+// A bare no-op would read as permanent backpressure to a pipe()'d source; this drains and
+// discards instead.
+function noopWrite(_chunk?: any, encoding?: any, callback?: any) {
+	if (typeof encoding === 'function') callback = encoding;
+	if (typeof callback === 'function') callback();
+	return true;
+}
+
 /**
  * We call this if stdio is not functional
  */
 export function disableStdio(_unused?: any) {
-	nativeStdWrite = function () {}; // make this a noop
+	nativeStdWrite = noopWrite;
+}
+
+const STDIO_BROKEN_ERROR_CODES = new Set(['EPIPE', 'EIO', 'ERR_STREAM_DESTROYED']);
+
+/**
+ * True when this error means a stdio stream (stdout/stderr) is permanently unwritable - the
+ * pipe's reader died (EPIPE), the terminal closed (EIO), or the stream was already destroyed.
+ * Callers should disableStdio() on this rather than logging through the same sink that threw it.
+ */
+export function isStdioBrokenError(error: any): boolean {
+	return STDIO_BROKEN_ERROR_CODES.has(error?.code);
 }
 
 /**
@@ -509,32 +529,42 @@ export function initLogSettings(forceInit = false) {
 	stdioLogging();
 }
 let loggingEnabled = true;
+
+// A POSIX pipe reports a broken pipe asynchronously - write() returns normally and the EPIPE
+// arrives later as an 'error' event, past the try/catch below. An unhandled 'error' event on any
+// EventEmitter becomes an uncaughtException, so the listener is what actually catches that case.
+function installStdioGuard(stream) {
+	if (stream.harperStdioErrorHandler) stream.removeListener('error', stream.harperStdioErrorHandler);
+	stream.harperStdioErrorHandler = (error) => {
+		if (!isStdioBrokenError(error)) throw error;
+		disableStdio();
+	};
+	stream.on('error', stream.harperStdioErrorHandler);
+
+	stream.write = function (data) {
+		if (
+			log_to_file &&
+			typeof data === 'string' && // this is how we identify console output vs redirected output from a worker
+			loggingEnabled &&
+			logConsole
+		) {
+			data = data.toString();
+			if (data[data.length - 1] === '\n') data = data.slice(0, -1);
+			writeToLogFile(data);
+		}
+		try {
+			return nativeStdWrite.apply(stream, arguments);
+		} catch (error) {
+			if (!isStdioBrokenError(error)) throw error;
+			disableStdio();
+			return noopWrite.apply(stream, arguments);
+		}
+	};
+}
+
 function stdioLogging() {
-	if (log_to_file) {
-		process.stdout.write = function (data) {
-			if (
-				typeof data === 'string' && // this is how we identify console output vs redirected output from a worker
-				loggingEnabled &&
-				logConsole
-			) {
-				data = data.toString();
-				if (data[data.length - 1] === '\n') data = data.slice(0, -1);
-				writeToLogFile(data);
-			}
-			return nativeStdWrite.apply(process.stdout, arguments);
-		};
-		process.stderr.write = function (data) {
-			if (
-				typeof data === 'string' && // this is how we identify console output vs redirected output from a worker
-				loggingEnabled &&
-				logConsole
-			) {
-				if (data[data.length - 1] === '\n') data = data.slice(0, -1);
-				writeToLogFile(data);
-			}
-			return nativeStdWrite.apply(process.stderr, arguments);
-		};
-	}
+	installStdioGuard(process.stdout);
+	installStdioGuard(process.stderr);
 }
 
 export function loggerWithTag(tag: string, conditional?: boolean, logger: any = mainLogger) {
@@ -1809,6 +1839,7 @@ export default {
 	setLogLevel,
 	OUTPUTS,
 	disableStdio,
+	isStdioBrokenError,
 	externalLogger,
 	AuthAuditLog,
 	errorToString,