@harperfast/harper 5.2.0-beta.4 → 5.2.0

package/bin/backup.ts

@@ -0,0 +1,169 @@
+'use strict';
+
+import { createWriteStream } from 'node:fs';
+import { rename, unlink } from 'node:fs/promises';
+import { basename } from 'node:path';
+import { pipeline } from 'node:stream/promises';
+import * as YAML from 'yaml';
+import * as envMgr from '../utility/environment/environmentManager.ts';
+envMgr.initSync();
+import * as terms from '../utility/hdbTerms.ts';
+import { buildRequest, cliOperations, resolveRequestOptions } from './cliOperations.ts';
+import { loadCredentials } from './cliCredentials.ts';
+import { httpRequest } from '../utility/common_utils.ts';
+import { initConfig } from '../config/configUtils.ts';
+import { getHdbPid } from '../utility/processManagement/processManagement.js';
+import {
+	createBackupOffline,
+	deleteBackupOffline,
+	listBackupsOffline,
+	purgeBackupsOffline,
+	restoreBackupOffline,
+	verifyBackupOffline,
+} from '../dataLayer/rocksdbBackup.ts';
+
+const { OPERATIONS_ENUM } = terms;
+
+/**
+ * Runs a backup operation from the CLI. `command` is the operation name (e.g. `create_backup`);
+ * there is no hyphenated alias. Each works whether or not Harper is running: RocksDB is
+ * single-writer, so when a server is reachable the running process must own the database handle
+ * and the operation is forwarded to it (also handling remote `target=` and auth); only when the
+ * *local* server is stopped do we open the database/backup files directly. `get_backup` is the
+ * exception — it streams a live snapshot from a running server and has no offline form.
+ */
+export async function runBackupCommand(command: string): Promise<void> {
+	// Load .env before anything reads process.env — useOperationApi and resolveRequestOptions key
+	// the local-vs-remote routing off HARPER_CLI_TARGET/CLI_TARGET, and without this a `.env`-
+	// configured remote target would be invisible, silently running a destructive op locally
+	// (cliOperations does the same on its first line).
+	require('dotenv').config();
+	const request = buildRequest();
+	const databaseName = request.database || 'data';
+
+	// We print results here (not by returning a string) so the CLI's top-level handler doesn't
+	// re-emit them through logger.notify — this keeps output identical to forwarding the operation
+	// to a running server, which the online branch below simply delegates to.
+	if (command === OPERATIONS_ENUM.GET_BACKUP) {
+		console.log(await downloadBackup(request, databaseName));
+		return;
+	}
+
+	// Fall back to direct file access only when there is no server to talk to (no target and the
+	// local instance is stopped). We never fall back on a *reachable* server's error response —
+	// e.g. restore_backup rejecting the system/component-held database (whose offline path is to
+	// stop the server and rerun this same command, which then takes the branch below).
+	if (useOperationApi(request)) {
+		request.operation = command;
+		await cliOperations(request); // prints its own result, exactly like any forwarded operation
+		return;
+	}
+
+	let result: any;
+	switch (command) {
+		case OPERATIONS_ENUM.CREATE_BACKUP:
+			result = await createBackupOffline(databaseName, request.exclude_blobs === true);
+			break;
+		case OPERATIONS_ENUM.LIST_BACKUPS:
+			result = await listBackupsOffline(databaseName);
+			break;
+		case OPERATIONS_ENUM.VERIFY_BACKUP:
+			result = await verifyBackupOffline(databaseName, request.backup_id, request.verify_checksum);
+			break;
+		case OPERATIONS_ENUM.DELETE_BACKUP:
+			result = await deleteBackupOffline(databaseName, request.backup_id);
+			break;
+		case OPERATIONS_ENUM.PURGE_BACKUPS:
+			result = await purgeBackupsOffline(databaseName, request.keep_count);
+			break;
+		case OPERATIONS_ENUM.RESTORE_BACKUP:
+			result = await restoreBackupOffline(databaseName, request.backup_id, request.target_database);
+			break;
+		default:
+			throw new Error(`Unknown backup command '${command}'`);
+	}
+	console.log(YAML.stringify(result).trim());
+}
+
+/**
+ * Whether the target of a saved `last_target` is the local instance (localhost / loopback). A
+ * `harper login` against a local server saves `http://localhost:9925/`, which must NOT be treated as
+ * a remote target — otherwise the offline backup commands would try to reach a stopped local server
+ * instead of falling back to direct file access.
+ */
+function isLocalTarget(target: string): boolean {
+	try {
+		const url = new URL(target.includes('://') ? target : `http://${target}`);
+		const host = url.hostname.replace(/^\[|\]$/g, ''); // strip IPv6 brackets
+		return host === 'localhost' || host === '::1' || host.startsWith('127.');
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Whether to route a backup command through the operation API rather than direct file access. An
+ * explicit `target=`/env target, or a saved `last_target` pointing at a *remote* server, always
+ * implies talking to a server. A saved *local* `last_target` does not: the offline backup commands
+ * exist to work on local files while the local server is stopped, so a local/absent target falls
+ * through to the liveness check — the API only when the local instance is actually running
+ * (`getHdbPid` verifies process liveness, so a stale pid file reads as stopped).
+ */
+function useOperationApi(request: any): boolean {
+	const lastTarget = loadCredentials()?.last_target;
+	if (
+		request.target ||
+		process.env.HARPER_CLI_TARGET ||
+		process.env.CLI_TARGET ||
+		(lastTarget && !isLocalTarget(lastTarget))
+	) {
+		return true;
+	}
+	initConfig();
+	return Boolean(getHdbPid());
+}
+
+/**
+ * `get_backup` streams a full-snapshot tar of the database's current state from a running server
+ * into a local file. It works against a remote server (`target=…`) or the local instance, resolving
+ * the target and auth the same way as any other CLI operation; a local connection requires Harper to
+ * be running (there is no offline form). For RocksDB the stream is gzipped by default (pass
+ * `gzip=false` for a plain tar) and includes the database's file-backed blobs by default (pass
+ * `exclude_blobs=true` for an engine-only archive). While stopped, use `create_backup` — a local
+ * incremental directory backup — instead.
+ */
+async function downloadBackup(request: any, databaseName: string): Promise<string> {
+	// only forward gzip/exclude_blobs when the user passed them — they are RocksDB-only options
+	// (sending them unconditionally would fail LMDB downloads), and when unset the server applies its
+	// own defaults (RocksDB gzips and includes blobs)
+	const body: any = { operation: terms.OPERATIONS_ENUM.GET_BACKUP, database: databaseName };
+	if (request.gzip !== undefined) body.gzip = request.gzip;
+	if (request.exclude_blobs !== undefined) body.exclude_blobs = request.exclude_blobs;
+	// resolveRequestOptions connects to a remote target (target=/env/saved) or the local domain
+	// socket with auth; for a local connection it enforces that Harper is running.
+	const { options } = await resolveRequestOptions(request);
+	options.streamResponse = true;
+	const response = await httpRequest(options, body);
+	if (response.statusCode !== 200) {
+		const chunks: Buffer[] = [];
+		for await (const chunk of response) chunks.push(Buffer.from(chunk));
+		throw new Error(`get_backup failed (${response.statusCode}): ${Buffer.concat(chunks).toString('utf8')}`);
+	}
+	// name the file after what the server is sending (RocksDB: <db>.tar[.gz]; LMDB: the database file).
+	// basename() strips any path from the server-supplied filename — a malicious/compromised target
+	// could otherwise return `../../…` and steer the write outside the cwd.
+	const serverFilename = response.headers['content-disposition']?.match(/filename="([^"]+)"/)?.[1];
+	const outputPath = request.out || (serverFilename && basename(serverFilename)) || `${databaseName}.backup`;
+	// Stream to a temporary sibling and rename on success, so a network/server failure mid-download
+	// neither truncates an existing known-good backup at `outputPath` nor leaves a partial file that
+	// looks complete. The temp name is unique per process+time so concurrent downloads never collide.
+	const tempPath = `${outputPath}.${process.pid}-${Date.now()}.part`;
+	try {
+		await pipeline(response, createWriteStream(tempPath, { flags: 'wx' }));
+		await rename(tempPath, outputPath);
+	} catch (error) {
+		await unlink(tempPath).catch(() => {});
+		throw error;
+	}
+	return `Backup of database '${databaseName}' written to ${outputPath}`;
+}

package/bin/cliOperations.ts

@@ -389,9 +389,16 @@ async function refreshExpiredOperationToken(
  * @param skipResponseLog By default, the response is logged to the console. Set this to true to skip logging it, which can be useful for sensitive responses like login calls!
  * @returns {Promise<void>}
  */
-async function cliOperations(req: any, skipResponseLog = false) {
-	require('dotenv').config();
-
+/**
+ * Resolve the transport options for a CLI operation request: a remote target URL (with auth) when
+ * one is configured (`target=`, env, or a saved `last_target`), otherwise the local domain socket.
+ * Returns the `options` object ready for `httpRequest` (method + Content-Type, and an Authorization
+ * header for remote targets, refreshing an expired operation token when possible) plus the resolved
+ * `target` (undefined for a local connection). Exits the process if a local connection is required
+ * but Harper is not running or has no domain socket. Shared by `cliOperations` and the CLI's
+ * streaming `get_backup` download so both reach local and remote servers the same way.
+ */
+export async function resolveRequestOptions(req: any): Promise<{ options: any; target: any }> {
 	const allCredentials = loadCredentials();
 	const rawTarget = resolveTarget(req, allCredentials);
 	// Userinfo is a transport credential, and `normalizeTarget` strips it so the resolved target can
@@ -434,81 +441,93 @@ async function cliOperations(req: any, skipResponseLog = false) {
 			process.exit(1);
 		}
 	}
-	await PREPARE_OPERATION[req.operation]?.(req);
-	try {
-		let options = target ?? {
-			protocol: 'http:',
-			socketPath: getConfigPath(terms.CONFIG_PARAMS.OPERATIONSAPI_NETWORK_DOMAINSOCKET),
-		};
-		options.method = 'POST';
-		options.headers = { 'Content-Type': 'application/json' };
-		options.timeout = SSE_OPERATIONS.has(req.operation) ? SSE_OPERATION_TIMEOUT_MS : CLI_OPERATION_TIMEOUT_MS;
-		// Authentication precedence: explicitly configured credentials (dedicated args, URL
-		// userinfo, env vars) beat everything, then env-var tokens, then the saved `harper login`
-		// token, and only then the legacy `username=`/`password=` payload fallback below. The
-		// tokens must outrank that fallback: for add_user/alter_user those args are the credentials
-		// of the user being created/altered, so treating them as auth would authenticate as a user
-		// who doesn't exist yet (or as the wrong identity) instead of using the admin's session.
-		const transportCredentials = target ? resolveTransportCredentials(req, urlCredentials) : undefined;
-		if (transportCredentials) {
-			options.headers.Authorization = basicAuthHeader(transportCredentials.username, transportCredentials.password);
-		} else if (target) {
-			// Bearer-token auth, for remote targets ONLY. A local operation goes over the domain
-			// socket, which the server trusts via `bypassLocalAuth` — but that bypass is an
-			// `else if` on "no Authorization header present" (security/auth.ts), so attaching a
-			// Bearer token to a local request opts out of the trust and gets validated instead,
-			// 401ing on a token minted for some other cluster. Since these env vars are meant to
-			// persist across a whole CI job (or a developer's shell), an ungated read here would
-			// break every local `harper` command run in that environment.
-			//
-			// Env-var tokens (for CI/CD — see `harper login --for-ci`) take precedence over the
-			// stored ~/.harperdb/credentials.json entry: they're an explicit per-invocation override
-			// that needs no prior `harper login` on the runner. A token refreshed from env vars is
-			// used in-memory only (there's no file to write back to); a token refreshed from the
-			// credentials file is persisted as before.
-			//
-			// Whichever namespace supplies a token owns both halves. Resolving them independently
-			// would let `HARPER_CLI_OPERATION_TOKEN` from one user pair with
-			// `CLI_TARGET_REFRESH_TOKEN` from another: commands would run as the first identity
-			// until its operation token expired, then silently continue as the second. `login.ts`
-			// selects its username/password namespace as a unit for exactly this reason.
-			const tokenPrefix = ['HARPER_CLI', 'CLI_TARGET'].find(
-				(prefix) =>
-					process.env[`${prefix}_OPERATION_TOKEN`] !== undefined || process.env[`${prefix}_REFRESH_TOKEN`] !== undefined
+	let options = target ?? {
+		protocol: 'http:',
+		socketPath: getConfigPath(terms.CONFIG_PARAMS.OPERATIONSAPI_NETWORK_DOMAINSOCKET),
+	};
+	options.method = 'POST';
+	options.headers = { 'Content-Type': 'application/json' };
+	options.timeout = SSE_OPERATIONS.has(req.operation) ? SSE_OPERATION_TIMEOUT_MS : CLI_OPERATION_TIMEOUT_MS;
+	// Authentication precedence: explicitly configured credentials (dedicated args, URL
+	// userinfo, env vars) beat everything, then env-var tokens, then the saved `harper login`
+	// token, and only then the legacy `username=`/`password=` payload fallback below. The
+	// tokens must outrank that fallback: for add_user/alter_user those args are the credentials
+	// of the user being created/altered, so treating them as auth would authenticate as a user
+	// who doesn't exist yet (or as the wrong identity) instead of using the admin's session.
+	const transportCredentials = target ? resolveTransportCredentials(req, urlCredentials) : undefined;
+	if (transportCredentials) {
+		options.headers.Authorization = basicAuthHeader(transportCredentials.username, transportCredentials.password);
+	} else if (target) {
+		// Bearer-token auth, for remote targets ONLY. A local operation goes over the domain
+		// socket, which the server trusts via `bypassLocalAuth` — but that bypass is an
+		// `else if` on "no Authorization header present" (security/auth.ts), so attaching a
+		// Bearer token to a local request opts out of the trust and gets validated instead,
+		// 401ing on a token minted for some other cluster. Since these env vars are meant to
+		// persist across a whole CI job (or a developer's shell), an ungated read here would
+		// break every local `harper` command run in that environment.
+		//
+		// Env-var tokens (for CI/CD — see `harper login --for-ci`) take precedence over the
+		// stored ~/.harperdb/credentials.json entry: they're an explicit per-invocation override
+		// that needs no prior `harper login` on the runner. A token refreshed from env vars is
+		// used in-memory only (there's no file to write back to); a token refreshed from the
+		// credentials file is persisted as before.
+		//
+		// Whichever namespace supplies a token owns both halves. Resolving them independently
+		// would let `HARPER_CLI_OPERATION_TOKEN` from one user pair with
+		// `CLI_TARGET_REFRESH_TOKEN` from another: commands would run as the first identity
+		// until its operation token expired, then silently continue as the second. `login.ts`
+		// selects its username/password namespace as a unit for exactly this reason.
+		const tokenPrefix = ['HARPER_CLI', 'CLI_TARGET'].find(
+			(prefix) =>
+				process.env[`${prefix}_OPERATION_TOKEN`] !== undefined || process.env[`${prefix}_REFRESH_TOKEN`] !== undefined
+		);
+		const envOperationToken = tokenPrefix ? process.env[`${tokenPrefix}_OPERATION_TOKEN`]?.trim() : undefined;
+		const envRefreshToken = tokenPrefix ? process.env[`${tokenPrefix}_REFRESH_TOKEN`]?.trim() : undefined;
+		// A namespace that is set but blank is a broken CI secret, not a request to fall back to
+		// whatever the developer last logged in as — say so rather than switching identity silently.
+		if (tokenPrefix && !envOperationToken && !envRefreshToken) {
+			console.error(
+				`Ignoring empty ${tokenPrefix}_OPERATION_TOKEN/${tokenPrefix}_REFRESH_TOKEN; falling back to saved login credentials.`
 			);
-			const envOperationToken = tokenPrefix ? process.env[`${tokenPrefix}_OPERATION_TOKEN`]?.trim() : undefined;
-			const envRefreshToken = tokenPrefix ? process.env[`${tokenPrefix}_REFRESH_TOKEN`]?.trim() : undefined;
-			// A namespace that is set but blank is a broken CI secret, not a request to fall back to
-			// whatever the developer last logged in as — say so rather than switching identity silently.
-			if (tokenPrefix && !envOperationToken && !envRefreshToken) {
-				console.error(
-					`Ignoring empty ${tokenPrefix}_OPERATION_TOKEN/${tokenPrefix}_REFRESH_TOKEN; falling back to saved login credentials.`
-				);
-			}
+		}
 
-			let tokens: { operation_token?: string; refresh_token?: string } | null = null;
-			let persistKey: string | null = null; // non-null => persist a refreshed operation token back to the file
-			if (envOperationToken || envRefreshToken) {
-				tokens = { operation_token: envOperationToken, refresh_token: envRefreshToken };
-			} else if (allCredentials?.targets) {
-				persistKey = target.resolvedTarget;
-				tokens = allCredentials.targets[persistKey] ?? null;
-			}
+		let tokens: { operation_token?: string; refresh_token?: string } | null = null;
+		let persistKey: string | null = null; // non-null => persist a refreshed operation token back to the file
+		if (envOperationToken || envRefreshToken) {
+			tokens = { operation_token: envOperationToken, refresh_token: envRefreshToken };
+		} else if (allCredentials?.targets) {
+			persistKey = target.resolvedTarget;
+			tokens = allCredentials.targets[persistKey] ?? null;
+		}
 
-			if (tokens?.operation_token || tokens?.refresh_token) {
-				await refreshExpiredOperationToken(options, tokens, persistKey);
-				if (tokens.operation_token) {
-					options.headers.Authorization = `Bearer ${tokens.operation_token}`;
-				}
+		if (tokens?.operation_token || tokens?.refresh_token) {
+			await refreshExpiredOperationToken(options, tokens, persistKey);
+			if (tokens.operation_token) {
+				options.headers.Authorization = `Bearer ${tokens.operation_token}`;
 			}
 		}
-		// Legacy fallback for operations where `username=`/`password=` genuinely ARE the caller's
-		// credentials (e.g. `create_table username= password=`) and nothing else is configured.
-		// Both are required — a lone `username=` (as in `drop_user username=bob`) is payload, not
-		// a credential.
-		if (target && !options.headers.Authorization && req.username && req.password) {
-			options.headers.Authorization = basicAuthHeader(req.username, req.password);
-		}
+	}
+	// Legacy fallback for operations where `username=`/`password=` genuinely ARE the caller's
+	// credentials (e.g. `create_table username= password=`) and nothing else is configured.
+	// Both are required — a lone `username=` (as in `drop_user username=bob`) is payload, not
+	// a credential.
+	if (target && !options.headers.Authorization && req.username && req.password) {
+		options.headers.Authorization = basicAuthHeader(req.username, req.password);
+	}
+	return { options, target };
+}
+
+async function cliOperations(req: any, skipResponseLog = false) {
+	require('dotenv').config();
+
+	// Resolve target/auth inside the try so a credential or connection error (e.g. an incomplete
+	// `auth_username=`/`auth_password=` pair, which resolveRequestOptions throws on) is mapped to the
+	// same console.error + process.exit(1) as every other failure below, rather than escaping as an
+	// unhandled rejection. `target` is declared out here so the catch can still reference it.
+	let options: any, target: any;
+	try {
+		({ options, target } = await resolveRequestOptions(req));
+		await PREPARE_OPERATION[req.operation]?.(req);
 		// Streaming deploy (multipart upload + SSE progress) only works against >= 5.1 servers.
 		// When deploying to a remote target, probe its version first and downgrade to the
 		// legacy JSON deploy if it predates 5.1. Local (domain-socket) deploys always

package/bin/harper.ts

@@ -8,7 +8,7 @@ import * as cliOperations from './cliOperations.ts';
 import { packageJson } from '../utility/packageUtils.js';
 import checkNode from '../launchServiceScripts/utility/checkNodeVersion.js';
 import * as hdbTerms from '../utility/hdbTerms.ts';
-const { SERVICE_ACTIONS_ENUM } = hdbTerms as any;
+const { SERVICE_ACTIONS_ENUM, OPERATIONS_ENUM } = hdbTerms as any;
 if (typeof process.setSourceMapsEnabled === 'function') {
 	process.setSourceMapsEnabled(true); // this is necessary for source maps to work, at least on the main thread.
 }
@@ -62,6 +62,18 @@ version                         - Print the version
 deploy                          - Deploy the application locally or remotely with target=<remote url>
 `;
 
+/**
+ * Format a CLI error for the terminal. Expected, user-facing errors (a `ClientError` from an
+ * operation — bad args, not found, a locked backup repo — which carry a numeric `statusCode`) get
+ * just their message, not a Node stack trace. A genuinely unexpected error keeps its stack so a bug
+ * is still debuggable. Mirrors the clean `error: <message>` output of a forwarded operation.
+ */
+export function formatCliError(error: any): string {
+	const message = `error: ${error?.message ?? error}`;
+	if (error?.stack && typeof error?.statusCode !== 'number') return `${message}\n${error.stack}`;
+	return message;
+}
+
 async function harper() {
 	let nodeResults = checkNode();
 
@@ -140,6 +152,14 @@ async function harper() {
 			let targetDbPath = process.argv[4];
 			return require('./copyDb').copyDb(sourceDb, targetDbPath);
 		}
+		case OPERATIONS_ENUM.CREATE_BACKUP:
+		case OPERATIONS_ENUM.LIST_BACKUPS:
+		case OPERATIONS_ENUM.VERIFY_BACKUP:
+		case OPERATIONS_ENUM.DELETE_BACKUP:
+		case OPERATIONS_ENUM.PURGE_BACKUPS:
+		case OPERATIONS_ENUM.GET_BACKUP:
+		case OPERATIONS_ENUM.RESTORE_BACKUP:
+			return require('./backup').runBackupCommand(service);
 		case SERVICE_ACTIONS_ENUM.DEV:
 			process.env.DEV_MODE = 'true';
 		// fall through
@@ -191,18 +211,17 @@ if (require.main === module) {
 	harper()
 		.then((message) => {
 			if (message) {
+				// console.log is the canonical terminal output for CLI results; logger.notify would
+				// print the same message a second time (its Console transport is stdout in CLI mode),
+				// so `harper help` and friends were emitted twice.
 				console.log(message);
-				logger.notify(message);
 			}
 			// Intentionally not calling `process.exit(0);` so if a CLI
 			// command resulted in a long running process (aka `run`),
 			// it continues to run.
 		})
 		.catch((error) => {
-			if (error) {
-				console.error(error);
-				logger.error(error);
-			}
+			if (error) console.error(formatCliError(error));
 			process.exit(1);
 		});
 }

package/components/Scope.ts

@@ -11,6 +11,7 @@ import type { FileAndURLPathConfig } from './Component.ts';
 import { FilesOption } from './deriveGlobOptions.ts';
 import { requestRestart } from './requestRestart.ts';
 import { resolveBaseURLPath } from './resolveBaseURLPath.ts';
+import { composeMountedUrlPath, type ScopeMount } from './scopeMount.ts';
 import { ApplicationScope } from './ApplicationScope.ts';
 import {
 	getSecretsForComponent,
@@ -81,6 +82,18 @@ export class Scope extends EventEmitter<ScopeEventsMap> {
 	// process-global side effects should validate fully but skip activation.
 	isTransientValidation?: boolean;
 
+	/**
+	 * Routing the operator declared for this application in the root config. Applied automatically
+	 * to handlers registered through `scope.server`, so plugins normally don't touch it — the
+	 * router strips the mount before a handler runs and everything inside the application
+	 * addresses itself mount-relative.
+	 *
+	 * Read it only when a plugin emits an absolute URL back to the client (e.g. a redirect
+	 * `Location`, via `externalBasePath()`) or bypasses the routed chain entirely (legacy
+	 * fastify routes register on the bare server).
+	 */
+	mount?: ScopeMount;
+
 	constructor(
 		appName: string,
 		pluginName: string,
@@ -88,10 +101,12 @@ export class Scope extends EventEmitter<ScopeEventsMap> {
 		configFilePath: string,
 		applicationScope: ApplicationScope,
 		origin: string = appName,
-		isRootConfig?: boolean
+		isRootConfig?: boolean,
+		mount?: ScopeMount
 	) {
 		super();
 
+		this.mount = mount;
 		this.#appName = appName;
 		this.#pluginName = pluginName;
 		this.#origin = typeof origin === 'string' ? origin : appName;
@@ -117,14 +132,10 @@ export class Scope extends EventEmitter<ScopeEventsMap> {
 					const method = Reflect.get(target, prop, receiver);
 					if (typeof method === 'function') {
 						return (listener: any, options?: any) => {
-							const scopeConfig = (scopeRef.options?.getAll() as any) ?? {};
 							return method.call(target, listener, {
 								name: pluginName,
-								// resolve to the same base the entry pipeline uses ('assets' -> '/assets/',
-								// './x' -> '/<name>/x/') so route matching sees a real pathname prefix (#1583)
-								urlPath: scopeConfig.urlPath ? resolveBaseURLPath(pluginName, scopeConfig.urlPath) : undefined,
-								host: scopeConfig.host || undefined,
 								...options,
+								...scopeRef.routeFor(options),
 							});
 						};
 					}
@@ -184,6 +195,41 @@ export class Scope extends EventEmitter<ScopeEventsMap> {
 		return this.#pluginName;
 	}
 
+	/**
+	 * Turns a mount-relative base path into the absolute path a client sees, by prefixing the
+	 * application's mount. Use it for anything sent back to the client — a redirect `Location`, a
+	 * generated link — since the router strips the mount before a handler runs and a handler's own
+	 * view of the path therefore excludes it.
+	 */
+	externalBasePath(baseURLPath: string): string {
+		return this.mount?.urlPath ? `${this.mount.urlPath}${baseURLPath}` : baseURLPath;
+	}
+
+	/**
+	 * The route a handler registered through `scope.server` with these options will answer on — the
+	 * single place the application mount is applied. `scope.server` uses it, and a plugin that must
+	 * identify its own route (e.g. REST deduplicating registration per mount) calls it rather than
+	 * recomposing the parts, so there is one definition of "which route is this".
+	 *
+	 * An explicit call option wins over config, but either way `urlPath` is *resolved* rather than
+	 * passed through: plugins that spread their whole config section into these options (REST does)
+	 * would otherwise hand the router a raw value — './' became the literal, unmatchable route '/.'.
+	 */
+	routeFor(options?: { urlPath?: string; host?: string }): { host?: string; urlPath?: string } {
+		const scopeConfig = (this.options?.getAll() as any) ?? {};
+		const rawUrlPath = options?.urlPath ?? scopeConfig.urlPath;
+		// resolve to the same base the entry pipeline uses ('assets' -> '/assets/', './x' ->
+		// '/<name>/x/') so route matching sees a real pathname prefix (#1583), then prefix the
+		// application's mount. The mount is applied ONLY here, at the routing boundary: the router
+		// strips it before the handler runs, so entry URL paths — and the resource paths
+		// graphqlSchema/jsResource derive from them — stay mount-relative.
+		const pluginUrlPath = rawUrlPath ? resolveBaseURLPath(this.#pluginName, rawUrlPath) : undefined;
+		return {
+			host: this.mount?.host || options?.host || scopeConfig.host || undefined,
+			urlPath: composeMountedUrlPath(this.mount?.urlPath, this.#pluginName, pluginUrlPath) || undefined,
+		};
+	}
+
 	get directory(): string {
 		return this.#directory;
 	}