@harperfast/harper 5.3.0-beta.4 → 5.3.0

package/dataLayer/rocksdbBackup.ts

@@ -1,7 +1,8 @@
 'use strict';
 
+import { randomUUID } from 'node:crypto';
 import { createReadStream, existsSync, readdirSync } from 'node:fs';
-import { open, readdir, writeFile } from 'node:fs/promises';
+import { open, writeFile } from 'node:fs/promises';
 import { join, relative, resolve, sep } from 'node:path';
 import { PassThrough, Writable } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
@@ -27,12 +28,14 @@ import { SchemaEventMsg } from '../server/threads/itc.js';
 import { beginRestore, completeRestore, abandonRestore, checkRestoreState, type RestoreLock } from './restoreMarker.ts';
 import {
 	assertBlobSnapshotRestorable,
+	assertEngineOnlyRestoreAllowed,
 	blobSnapshotDir,
 	blobsReadmeContent,
 	deleteBlobSnapshot,
 	purgeBlobSnapshots,
 	restoreBlobSnapshot,
 	snapshotBlobs,
+	walkBlobFiles,
 } from './blobBackup.ts';
 import {
 	deleteBackupManifest,
@@ -165,7 +168,7 @@ function requireBackupId(backupId: any): number {
 	return backupId;
 }
 
-function requireBooleanOption(value: any, name: string): boolean {
+export function requireBooleanOption(value: any, name: string): boolean {
 	if (value !== undefined && typeof value !== 'boolean') {
 		throw new ClientError(`'${name}' must be a boolean`);
 	}
@@ -439,6 +442,13 @@ the backup (blobs are restored automatically). Restore the latest backup in plac
 
     harper restore_backup database=${databaseName} backup_id=<id>
 
+A backup created with \`exclude_blobs\` carries no blobs, so restoring one is refused unless you pass
+\`allow_engine_only=true\`. The restored records address whichever blobs are on disk now: if the
+database still has blob files a record can resolve to one that no longer belongs to it, and if it has
+none the blob ids start over at 1 and the next blob written lands on a path a restored record already
+references. Restoring into a new database is **not** a way around this — its blob roots are empty for
+the same reason. Restore a backup that includes blobs, or accept the mixed result explicitly.
+
 A database held open by a loaded component — and always the \`system\` database — cannot be restored
 while Harper is running; stop the server and run the same command offline. Offline you can also
 restore into a *copy*, leaving the original untouched:
@@ -491,6 +501,7 @@ export async function verifyBackup(request: any) {
 
 export async function validateRestoreBackup(request: any) {
 	requireSuperUser(request, OPERATIONS_ENUM.RESTORE_BACKUP);
+	requireBooleanOption(request.allow_engine_only, 'allow_engine_only');
 	const databaseName = getDatabaseName(request);
 	if (databaseName === 'system') {
 		throw new ClientError(
@@ -558,13 +569,25 @@ export async function restoreBackup(request: any) {
 			: resolveDatabasePath(databaseName);
 	// reject a backup with more blob roots than the current config *before* anything destructive —
 	// restoring it would mis-address blobs (records persist their root index)
-	await assertBlobSnapshotRestorable(backupDir, backupId, getBlobPathsForDatabaseName(databaseName));
+	const blobRoots = getBlobPathsForDatabaseName(databaseName);
+	await assertBlobSnapshotRestorable(backupDir, backupId, blobRoots);
+	const allowEngineOnly = requireBooleanOption(request.allow_engine_only, 'allow_engine_only');
+	// Once is enough: the decision reads the manifest and the opt-in, never the destination, so no
+	// concurrent writer can change the answer between here and the purge.
+	assertEngineOnlyRestoreAllowed(databaseName, { backupHasBlobs: manifest.blobs, allowEngineOnly });
 	const lock = beginRestoreForDatabase(databaseDir, databaseName);
+	const restoreToken = randomUUID();
 	let destructionStarted = false;
 	try {
-		// close the database across all worker threads (each thread also rescans, and the
-		// restoring marker keeps the scan from reloading it mid-restore)
-		await signalling.signalSchemaChange(new SchemaEventMsg(process.pid, OPERATIONS_ENUM.RESTORE_BACKUP, databaseName));
+		// Block new blob saves, drain in-flight saves, and close the database across all worker threads.
+		// Each thread also rescans, and the restoring marker keeps it from reloading mid-restore.
+		try {
+			await signalling.signalSchemaChange(restoreSchemaEvent(databaseName, 'close', restoreToken));
+		} catch {
+			throw new BackupInProgressError(
+				`Cannot restore database '${databaseName}': not every worker completed the blob-save barrier before the acknowledgement deadline. Retry the restore after the stalled work has cleared.`
+			);
+		}
 		// A live component (or the system database) can hold its own handle on the database that
 		// Harper does not track and cannot close, so verify actual process-wide closure before
 		// purging — restoring under an open instance would corrupt it. If handles remain, fail
@@ -587,6 +610,19 @@ export async function restoreBackup(request: any) {
 		// before any destruction is safe to clear.
 		if (destructionStarted || lock.preexisting) {
 			abandonRestore(lock);
+			// The restore is over even though it failed, so release the workers' blob fence. Without this
+			// the fence outlives the attempt: the marker keeps the database from loading, but an operator
+			// who gives up and drops/recreates the name instead of rerunning gets a database whose writes
+			// are refused by a fence no restore owns any more. Treated as a replaced generation because
+			// destruction may have begun -- forgoing a deletion only leaks a file for the orphan sweep,
+			// while performing a stale one destroys restored bytes.
+			try {
+				await signalling.signalSchemaChange(restoreSchemaEvent(databaseName, 'reload', restoreToken, true));
+			} catch (releaseError) {
+				// Never mask the restore failure with a broadcast failure; the fence is worker-local state
+				// and a process restart clears it regardless.
+				logger.error(`Could not release the blob fence after a failed restore of '${databaseName}'`, releaseError);
+			}
 			// wrap rather than mutate error.message: a frozen/library error can have a non-writable
 			// message (assigning it throws TypeError under 'use strict')
 			throw new Error(
@@ -597,13 +633,33 @@ export async function restoreBackup(request: any) {
 		// nothing destructive happened and the marker was fresh — clear it and let every thread reload
 		// the intact database
 		completeRestore(lock);
-		await signalling.signalSchemaChange(new SchemaEventMsg(process.pid, OPERATIONS_ENUM.RESTORE_BACKUP, databaseName));
+		await signalling.signalSchemaChange(restoreSchemaEvent(databaseName, 'reload', restoreToken, false));
 		throw error;
 	}
 	completeRestore(lock);
 	// signal again: with the marker gone, every thread's rescan reloads the restored database
-	await signalling.signalSchemaChange(new SchemaEventMsg(process.pid, OPERATIONS_ENUM.RESTORE_BACKUP, databaseName));
-	return { database: databaseName, backup_id: backupId };
+	await signalling.signalSchemaChange(restoreSchemaEvent(databaseName, 'reload', restoreToken));
+	return { database: databaseName, backup_id: backupId, ...(allowEngineOnly ? { allow_engine_only: true } : {}) };
+}
+
+/**
+ * `restoreToken` identifies the restore that owns the blob fence. Two restores of the same database
+ * can overlap, so a worker releases the fence only for the token that established it -- see
+ * `resumeBlobSavesAfterRestore`.
+ */
+function restoreSchemaEvent(
+	databaseName: string,
+	restorePhase: 'close' | 'reload',
+	restoreToken: string,
+	generationReplaced = true
+) {
+	const message: any = new SchemaEventMsg(process.pid, OPERATIONS_ENUM.RESTORE_BACKUP, databaseName);
+	message.restorePhase = restorePhase;
+	message.restoreToken = restoreToken;
+	// Tells a worker whether the blob roots it fenced were actually replaced. A restore that failed its
+	// admission checks destroyed nothing, so that worker's queued reclamations are still valid.
+	message.generationReplaced = generationReplaced;
+	return message;
 }
 
 // After the close broadcast is acknowledged, every worker thread has released its Harper-managed
@@ -820,28 +876,11 @@ function writeWithBackpressure(dest: PassThrough, chunk: Buffer): Promise<void>
 async function appendBlobEntries(pack: Pack, blobRoots: string[]): Promise<void> {
 	for (let index = 0; index < blobRoots.length; index++) {
 		const root = blobRoots[index];
-		if (!existsSync(root)) continue;
-		const stack: string[] = [root];
-		while (stack.length > 0) {
-			const dir = stack.pop() as string;
-			let entries;
-			try {
-				entries = await readdir(dir, { withFileTypes: true });
-			} catch (error: any) {
-				if (error.code === 'ENOENT') continue;
-				throw error;
-			}
-			for (const entry of entries) {
-				const filePath = join(dir, entry.name);
-				if (entry.isDirectory()) {
-					stack.push(filePath);
-				} else if (entry.isFile()) {
-					// tar entry names are always POSIX-separated; relative() yields `\` on Windows, which
-					// would otherwise become literal filename characters when extracted on POSIX
-					const relativePath = relative(root, filePath).split(sep).join('/');
-					await appendBlobEntry(pack, filePath, `blobs/${index}/${relativePath}`);
-				}
-			}
+		for await (const filePath of walkBlobFiles(root)) {
+			// tar entry names are always POSIX-separated; relative() yields `\` on Windows, which
+			// would otherwise become literal filename characters when extracted on POSIX
+			const relativePath = relative(root, filePath).split(sep).join('/');
+			await appendBlobEntry(pack, filePath, `blobs/${index}/${relativePath}`);
 		}
 	}
 }
@@ -996,7 +1035,15 @@ export async function createBackupOffline(databaseName: string, excludeBlobs = f
  * server start. `targetDatabase` restores into a different database directory (non-destructive
  * for the source database); the server picks it up on next start via normal engine detection.
  */
-export async function restoreBackupOffline(databaseName: string, backupId?: number, targetDatabase?: string) {
+export async function restoreBackupOffline(
+	databaseName: string,
+	backupId?: number,
+	targetDatabase?: string,
+	allowEngineOnlyOption?: boolean
+) {
+	// Validated the same way the online path validates it, so a malformed opt-in is refused rather than
+	// silently read as "no". The CLI JSON-parses `key=value`, so a typo arrives here as a string.
+	const allowEngineOnly = requireBooleanOption(allowEngineOnlyOption, 'allow_engine_only');
 	validateDatabaseName(databaseName);
 	const backupDir = backupDirForDatabase(databaseName);
 	// resolve to the latest complete backup (or the requested id, rejected if incomplete)
@@ -1014,7 +1061,9 @@ export async function restoreBackupOffline(databaseName: string, backupId?: numb
 	}
 	// reject a backup with more blob roots than the target's current config before anything
 	// destructive (records persist their root index, so collapsing would mis-address blobs)
-	await assertBlobSnapshotRestorable(backupDir, backupId, getBlobPathsForDatabaseName(targetDatabase ?? databaseName));
+	const blobRoots = getBlobPathsForDatabaseName(targetDatabase ?? databaseName);
+	await assertBlobSnapshotRestorable(backupDir, backupId, blobRoots);
+	assertEngineOnlyRestoreAllowed(targetDatabase ?? databaseName, { backupHasBlobs: manifest.blobs, allowEngineOnly });
 	// Take the restore lock + marker BEFORE probing so a server that starts after this point sees the
 	// marker and refuses to load the database (closing the window between the probe and the purge).
 	const lock = beginRestoreForDatabase(databaseDir, targetDatabase ?? databaseName);
@@ -1069,7 +1118,12 @@ export async function restoreBackupOffline(databaseName: string, backupId?: numb
 		throw error;
 	}
 	completeRestore(lock);
-	return { database: databaseName, backup_id: backupId, restored_to: databaseDir };
+	return {
+		database: databaseName,
+		backup_id: backupId,
+		restored_to: databaseDir,
+		...(allowEngineOnly ? { allow_engine_only: true } : {}),
+	};
 }
 
 function isMissingOrEmptyDir(path: string): boolean {

package/dataLayer/schemaDescribe.ts

@@ -181,11 +181,15 @@ async function descTable(describeTableObject: any, attrPerms?: any) {
 	}
 
 	let attributes = [];
-	if (tableAttrPerms) {
+	let readableAttributes: Set<string> | undefined;
+	if (tableAttrPerms?.length) {
 		let permittedAttr = {};
+		let readableAttr = {};
 		tableAttrPerms.forEach((a) => {
 			if (a.describe) permittedAttr[a.attribute_name] = true;
+			if (a.read) readableAttr[a.attribute_name] = true;
 		});
+		readableAttributes = new Set(Object.keys(readableAttr));
 
 		tableObj.attributes.forEach((a) => {
 			if (permittedAttr[a.name]) pushAtt(a);
@@ -220,6 +224,46 @@ async function descTable(describeTableObject: any, attrPerms?: any) {
 		tableResult.sources = (tableObj as any).sources
 			.map((source: any) => source.name)
 			.filter((source: any) => source && source !== 'Replicator');
+	if (tableObj.fullTextIndexes?.length > 0) {
+		const { fullTextDerivedIndexReadiness } = await import('../resources/derivedIndexes.ts');
+		tableResult.full_text_indexes = tableObj.fullTextIndexes
+			.map((definition: any) => {
+				const fields = definition.fields.filter(
+					(field: any) => !readableAttributes || readableAttributes.has(field.name)
+				);
+				if (fields.length === 0) return;
+				const readiness = fullTextDerivedIndexReadiness(tableObj, definition.name);
+				return {
+					name: definition.name,
+					fields: fields.map(({ name, weight, mediaType, highlight }: any) => ({
+						name,
+						weight,
+						...(mediaType ? { media_type: mediaType } : null),
+						...(highlight ? { highlight: true } : null),
+					})),
+					analyzer: definition.analyzer,
+					stop_words: definition.stopWords,
+					positions: definition.positions,
+					surface_terms: definition.surfaceTerms,
+					synonyms: definition.synonyms,
+					highlighting: definition.highlighting ?? false,
+					query_modes: [
+						'any',
+						'all',
+						'fuzzy',
+						...(definition.positions ? ['phrase'] : []),
+						...(definition.surfaceTerms ? ['prefix', 'fuzzy-prefix'] : []),
+					],
+					readiness: {
+						state: readiness.state,
+						...(readiness.reason ? { reason: readiness.reason } : null),
+						owner_epoch: readiness.ownerEpoch.toString(),
+						rebuild_attempts: readiness.rebuildAttempts,
+					},
+				};
+			})
+			.filter(Boolean);
+	}
 
 	try {
 		// `getRecordCount` scans the table's primary store, which dominates describe latency on large

package/dist/bin/backup.js

@@ -99,7 +99,7 @@ async function runBackupCommand(command) {
             result = await (0, rocksdbBackup_ts_1.purgeBackupsOffline)(databaseName, request.keep_count);
             break;
         case OPERATIONS_ENUM.RESTORE_BACKUP:
-            result = await (0, rocksdbBackup_ts_1.restoreBackupOffline)(databaseName, request.backup_id, request.target_database);
+            result = await (0, rocksdbBackup_ts_1.restoreBackupOffline)(databaseName, request.backup_id, request.target_database, request.allow_engine_only);
             break;
         default:
             throw new Error(`Unknown backup command '${command}'`);

package/dist/bin/backup.js.map

@@ -1 +1 @@
-{"version":3,"file":"backup.js","sourceRoot":"","sources":["../../bin/backup.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"backup.js","sourceRoot":"","sources":["../../bin/backup.ts"],"names":[],"mappings":"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"}

package/dist/components/Application.d.ts

@@ -137,13 +137,13 @@ type DormantBuild = {
  * cannot hold or miss a slot. Never throws: a failure must neither fail a component closed nor replace a
  * deploy's own error.
  *
- * `pinnedDeploymentId` is never evicted. A delayed activation runs this preamble under the same lock it is
- * about to activate under, so without the pin retention would delete the artifact the request named —
- * immediately, when the knob is `0`. The pin is applied after the kept set is chosen, so a pinned build in
- * the eviction tail leaves `maxCount + 1` on disk for the life of the request; the next preamble that does
- * not pin it brings the count back down.
+ * A `pinned` id is never evicted. A delayed activation runs this preamble under the same lock it is about to
+ * activate under, so without the pin retention would delete the artifact the request named — immediately, when the
+ * knob is `0` — and a settlement's pins keep the releases it just put back. Pins are applied after the kept set is
+ * chosen, so each pinned build in the eviction tail leaves one more than `maxCount` on disk until a pass that does
+ * not pin it.
  */
-export declare function pruneDormantBuilds(componentName: string, builds: DormantBuild[], maxCount: number, pinnedDeploymentId?: string): Promise<void>;
+export declare function pruneDormantBuilds(componentName: string, builds: DormantBuild[], maxCount: number, pinned?: string | readonly string[]): Promise<void>;
 export type ArtifactDescriptor = {
     v: number;
     component: string;
@@ -159,21 +159,10 @@ export declare function makeRollbackPlaceholderMovable(applicationDirPath: strin
     ino: bigint;
 } | undefined): Promise<void>;
 /**
- * Name the component that owns a deployment directory THIS CALL created, and take the directory back if that
- * cannot be recorded.
- *
- * Ownership is published as part of the claim rather than at certification, because resolving and packing can
- * take minutes and until a tree exists to infer an owner from, a directory answering to nobody is one another
- * component will take for abandoned. Unattributed is a permanent refusal, though, so a failure here — a full
- * disk, an EIO on the temp write or its sync — would burn this deployment id for good, every retry refused by
- * its own wreckage. The removal is scoped to the directory this invocation made, and deliberately not
- * broadened to one found by EEXIST: that directory may be another claimant's, and removing it is the race the
- * refusal exists to prevent. Best-effort, because the claim failure is what the caller needs to see.
- *
- * `write` is a parameter so the failure is testable without a filesystem that can be made to fail on exactly
- * this write and nothing else.
+ * The claim names no id yet, so a failure burns nothing. `write` is a parameter so the failure is testable without a
+ * filesystem that can be made to fail on exactly this write.
  */
-export declare function publishClaimOwnership(deploymentDirPath: string, componentName: string, write?: (filePath: string, contents: string) => Promise<void>): Promise<void>;
+export declare function publishClaimOwnership(claimDirPath: string, componentName: string, write?: (filePath: string, contents: string) => Promise<void>): Promise<void>;
 /**
  * The components a deployment's evidence implicates, when its journal and its ownership sidecar disagree
  * about whose it is — or `undefined` when there is no disagreement to act on.
@@ -218,7 +207,7 @@ export declare function recoverInterruptedActivations(componentsRootDirPath: str
  * dormant. The lock is taken only when there is something to do; a lock a live deploy holds is the same
  * deferral the residue branch records.
  */
-export declare function reconcileDormantBuilds(componentsRootDirPath: string, owner: string, builds: DormantBuild[], maxCount: number): Promise<Map<string, Error>>;
+export declare function reconcileDormantBuilds(componentsRootDirPath: string, owner: string, builds: DormantBuild[], maxCount: number, pinned?: readonly string[]): Promise<Map<string, Error>>;
 export declare function markCandidateComplete(componentDirPath: string, deploymentId: string, componentName: string): Promise<void>;
 /**
  * Make a built and validated candidate live, as one transaction over three effects: the live tree moves
@@ -322,6 +311,7 @@ export declare class Application {
     isNewComponent: boolean;
     packageMetadataChanged: boolean;
     installationIsOpaque: boolean;
+    alreadyActive: boolean;
     constructor({ name, payload, packageIdentifier, install, onInstallLine, credentials }: ApplicationOptions);
     writeTransientNpmrc(): Promise<void>;
     get gitCredentialEnv(): Record<string, string> | undefined;