feat: route applications by host/urlPath declared in the root config

Where an application is served is a deployment concern, not an application concern, but
`host`/`urlPath` were only readable from the config file that declared a plugin. For an
application that is its own `config.yaml`, so the hostname and mount point had to be
checked into the app — unoverridable from outside it (the env-config overlay is
root-config-only).

Worse, `host`/`urlPath` on a root-config *application* entry were silently inert. An
application's plugin scopes read the application's own config.yaml and nothing carried the
root entry's routing down to them, so `deploy_component urlPath=/api` (#1113) persisted a
value that changed nothing. The flow described in #1113 only ever held for a root-declared
*plugin*, whose scope does read the root config.

The root config is now authoritative for where an application is served:

    my-app:
      host: api.example.com
      urlPath: /v1

- `scopeMount.ts` — pure mount model. `host` is replaced outright (an operator remapping a
  hostname must win over a value the app shipped). `urlPath` is composed rather than
  replaced, because a plugin's `urlPath` doubles as its app-internal base path (static's
  asset root, fastify's route prefix); replacing it would silently relocate app-internal
  URLs and collapse distinct plugins onto one path. Mount `/v1` + `static: { urlPath:
  assets }` → `/v1/assets/`. The composed value is a fixed point of `resolveBaseURLPath`,
  so downstream consumers keep resolving it without compounding the prefix.
- Overlaid in `OptionsWatcher`, not at each call site, so `scope.options.getAll()` is the
  one effective view of a plugin's config. static's redirects and external paths, the
  EntryHandler's entry URLs, and fastify's route prefix are all correct with no changes of
  their own. Composed from the freshly-parsed file on every read, so live reload cannot
  compound the prefix.
- Applied on both load paths: the root-config `package` recursion and the components-root
  directory scan. The scan is the path that matters most — it loads apps with no root
  entry at all, so a mount works for a payload-deployed app, not just an installed one.
- `deploy_component` accepts and persists `host` alongside `urlPath`, rejecting a host
  that carries a port or path (it would never match the router's host compare).

Also fixes the Scope `server` proxy passing a raw config `urlPath` straight to the router:
a plugin that spreads its whole config section into these options (REST does) handed the
router the literal './', which normalized to the unmatchable route '/.'. The proxy now
resolves whichever source supplied the value.

Documented in HarperFast/documentation#595.

Author: kriszyp

components/OptionsWatcher.ts

@@ -9,6 +9,7 @@ import { DEFAULT_CONFIG } from './DEFAULT_CONFIG.ts';
 import { cloneDeep } from 'lodash';
 import { POLLING_FALLBACK_OPTIONS, isWatcherExhaustionError, warnWatcherFallback } from '../utility/watcherFallback.ts';
 import { overlayRootEnvConfig, isRootConfigFilename } from '../config/harperConfigEnvVars.ts';
+import { applyScopeMount, type ScopeMount } from './scopeMount.ts';
 
 export interface Config {
 	[key: string]: ConfigValue;
@@ -94,12 +95,18 @@ export class OptionsWatcher extends EventEmitter<OptionsWatcherEventMap> {
 	#closed: boolean;
 	#openCount: number = 0;
 	#pendingReads: Set<Promise<void>> = new Set();
+	#mount?: ScopeMount;
 	ready: Promise<any[]>;
 
-	constructor(name: string, filePath: string, logger?: Logger, isRootConfig?: boolean) {
+	constructor(name: string, filePath: string, logger?: Logger, isRootConfig?: boolean, mount?: ScopeMount) {
 		super();
 		this.#name = name;
 		this.#filePath = filePath;
+		// The operator-declared mount for the application this scope belongs to (root config).
+		// Overlaid on every read so `getAll()` is the single effective view of this plugin's
+		// config — consumers that resolve routing from it (the `server` proxy, EntryHandler,
+		// static, fastifyRoutes) are correct without each having to know about mounts.
+		this.#mount = mount;
 		// Root-config watchers must see runtime env config (HARPER_SET_CONFIG et al.)
 		// even when it hasn't been flushed to disk yet — see #handleChange (#1618).
 		// Application scopes watch their own config.yaml and are never overlaid.
@@ -143,12 +150,12 @@ export class OptionsWatcher extends EventEmitter<OptionsWatcherEventMap> {
 					// If a config object does not exist
 					if (!this.#scopedConfig) {
 						// set it
-						this.#scopedConfig = this.#rootConfig[this.#name];
+						this.#scopedConfig = this.#mountedSection(this.#rootConfig[this.#name]);
 						// and emit a ready event
 						this.emit('ready', this.#scopedConfig);
 					} else {
 						// Otherwise, merge the new config with the old config
-						this.#merge(this.#rootConfig[this.#name], this.#scopedConfig);
+						this.#merge(this.#mountedSection(this.#rootConfig[this.#name]), this.#scopedConfig);
 					}
 				} else {
 					// Otherwise, if the extension is not in the config file
@@ -255,17 +262,26 @@ export class OptionsWatcher extends EventEmitter<OptionsWatcherEventMap> {
 		if (!composed || !(this.#name in composed)) return false;
 		this.#rootConfig = composed;
 		if (!this.#scopedConfig) {
-			this.#scopedConfig = composed[this.#name];
+			this.#scopedConfig = this.#mountedSection(composed[this.#name]);
 			this.emit('ready', this.#scopedConfig);
 		} else {
-			this.#merge(composed[this.#name], this.#scopedConfig);
+			this.#merge(this.#mountedSection(composed[this.#name]), this.#scopedConfig);
 		}
 		return true;
 	}
 
 	#resetConfig() {
 		this.#rootConfig = DEFAULT_CONFIG;
-		this.#scopedConfig = this.#rootConfig[this.#name];
+		this.#scopedConfig = this.#mountedSection(this.#rootConfig[this.#name]);
+	}
+
+	/**
+	 * Overlays this scope's application mount onto a raw config section. Composed from the
+	 * freshly-parsed value on every read, so the prefix never compounds. Returns the section
+	 * unchanged (same reference) when there is no mount.
+	 */
+	#mountedSection(section: ConfigValue): ConfigValue {
+		return applyScopeMount(section, this.#name, this.#mount);
 	}
 
 	/**

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 { type ScopeMount } from './scopeMount.ts';
 import { ApplicationScope } from './ApplicationScope.ts';
 import {
 	getSecretsForComponent,
@@ -88,7 +89,8 @@ export class Scope extends EventEmitter<ScopeEventsMap> {
 		configFilePath: string,
 		applicationScope: ApplicationScope,
 		origin: string = appName,
-		isRootConfig?: boolean
+		isRootConfig?: boolean,
+		mount?: ScopeMount
 	) {
 		super();
 
@@ -118,13 +120,18 @@ export class Scope extends EventEmitter<ScopeEventsMap> {
 					if (typeof method === 'function') {
 						return (listener: any, options?: any) => {
 							const scopeConfig = (scopeRef.options?.getAll() as any) ?? {};
+							// An explicit call option wins over config, but either way the value is
+							// resolved here rather than passed through: plugins that spread their whole
+							// config section into these options (e.g. REST) would otherwise hand the
+							// router a raw, unresolved `urlPath` — './' became the literal route '/.'.
+							const rawUrlPath = options?.urlPath ?? scopeConfig.urlPath;
 							return method.call(target, listener, {
 								name: pluginName,
+								...options,
 								// 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,
+								urlPath: rawUrlPath ? resolveBaseURLPath(pluginName, rawUrlPath) : undefined,
+								host: options?.host || scopeConfig.host || undefined,
 							});
 						};
 					}
@@ -142,7 +149,7 @@ export class Scope extends EventEmitter<ScopeEventsMap> {
 		// isRootConfig is the loader's authoritative isRoot signal — it decides whether the
 		// watcher overlays runtime env config (#1618). When a caller doesn't provide it,
 		// OptionsWatcher falls back to its root-config filename heuristic.
-		this.options = new OptionsWatcher(pluginName, configFilePath, this.#logger, isRootConfig)
+		this.options = new OptionsWatcher(pluginName, configFilePath, this.#logger, isRootConfig, mount)
 			.on('error', this.#handleError.bind(this))
 			.on('change', this.#optionsWatcherChangeListener.bind(this)())
 			.on('ready', this.#handleOptionsWatcherReady.bind(this));

components/componentLoader.ts

@@ -29,6 +29,7 @@ import * as scheduler from '../resources/scheduler/scheduler.ts';
 import { restartWorkers, getWorkerIndex } from '../server/threads/manageThreads.js';
 import { resetRestartNeeded, subscribeToRestartRequests } from './requestRestart.ts';
 import { trackScopeClose } from './scopeShutdown.ts';
+import { toScopeMount, type ScopeMount } from './scopeMount.ts';
 import { scopedImport } from '../security/jsLoader.ts';
 import { server } from '../server/Server.ts';
 import { Resources } from '../resources/Resources.ts';
@@ -63,6 +64,33 @@ let resources;
  * @param loadedPluginModules
  * @param loadedResources
  */
+/**
+ * The application mount an operator declared for `appName` in the root config.
+ *
+ * Applications in the components root are loaded by directory scan, not from a root-config
+ * entry, so this is what makes a root-config entry authoritative for where an app is served:
+ *
+ * ```yaml
+ * my-app:
+ *   host: api.example.com
+ *   urlPath: /v1
+ * ```
+ *
+ * Works whether or not the entry also carries `package` — a payload-deployed app is mounted the
+ * same way as an installed one. A built-in plugin's config block is never an application mount;
+ * those keys (`http`, `mqtt`, …) configure the plugin itself.
+ */
+function rootConfigMount(appName: string): ScopeMount | undefined {
+	if (Object.hasOwn(TRUSTED_RESOURCE_PLUGINS, appName)) return undefined;
+	try {
+		return toScopeMount(getConfigObj()?.[appName]);
+	} catch (error) {
+		// An invalid mount must not take down every other application's load.
+		harperLogger.error(`Ignoring invalid routing configured for '${appName}': ${(error as Error).message}`);
+		return undefined;
+	}
+}
+
 export async function loadComponentDirectories(loadedPluginModules?: Map<any, any>, loadedResources?: Resources) {
 	if (loadedResources) resources = loadedResources;
 	if (loadedPluginModules) loadedComponents = loadedPluginModules;
@@ -82,7 +110,12 @@ export async function loadComponentDirectories(loadedPluginModules?: Map<any, an
 			const appName = appEntry.name;
 			const appFolder = join(CF_ROUTES_DIR, appName);
 			cfsLoaded.push(
-				loadComponent(appFolder, resources, HDB_ROOT_DIR_NAME, { isRoot: false, autoReload: false, appName })
+				loadComponent(appFolder, resources, HDB_ROOT_DIR_NAME, {
+					isRoot: false,
+					autoReload: false,
+					appName,
+					mount: rootConfigMount(appName),
+				})
 			);
 		}
 	}
@@ -94,6 +127,7 @@ export async function loadComponentDirectories(loadedPluginModules?: Map<any, an
 				isRoot: false,
 				autoReload: Boolean(process.env.DEV_MODE),
 				appName: hdbAppFolder,
+				mount: rootConfigMount(basename(hdbAppFolder)),
 			})
 		);
 	}
@@ -316,6 +350,10 @@ export interface LoadComponentOptions {
 	// (e.g. the deploy pre-flight validation) so their deploy-lifecycle listeners don't accumulate
 	// across deploys (#1462).
 	collectScopes?: Set<Scope>;
+	// Routing the operator declared for this application in the root config (`host`/`urlPath` on
+	// the application's entry). Applied to every plugin scope this load creates, and inherited by
+	// components the application itself declares, so the whole subtree moves together.
+	mount?: ScopeMount;
 }
 
 /**
@@ -342,6 +380,7 @@ export async function loadComponent(
 		isRoot,
 		autoReload,
 		appName,
+		mount,
 	} = options;
 	applicationScope.allowedPath ??= realpathSync(componentDirectory);
 	if (providedLoadedComponents) loadedComponents = providedLoadedComponents;
@@ -485,6 +524,12 @@ export async function loadComponent(
 								autoReload: false,
 								appName: appName || componentName,
 								collectScopes: options.collectScopes,
+								// `host`/`urlPath` on this entry route the component being loaded. For an
+								// application (no plugin module of its own) that entry is the only place an
+								// operator can say where the app is served — its own config.yaml declares the
+								// plugins, not the deployment. An inherited mount wins so a nested component
+								// can't escape the mount its parent application was given.
+								mount: mount ?? toScopeMount(componentConfig),
 							});
 							componentFunctionality[componentName] = true;
 						}
@@ -554,7 +599,10 @@ export async function loadComponent(
 						// authoritative root-ness: only root-load scopes watch THE root config and
 						// get the runtime env-config overlay (#1618) — an app component that happens
 						// to ship a root-named config file does not
-						isRoot
+						isRoot,
+						// A root-declared plugin reads its own `host`/`urlPath` straight from this
+						// config, so only an inherited application mount applies here.
+						mount
 					);
 
 					if (options.collectScopes) {

components/operations.js

@@ -410,6 +410,7 @@ async function deployComponent(req) {
 			};
 		}
 		if (req.urlPath !== undefined) applicationConfig.urlPath = req.urlPath;
+		if (req.host !== undefined) applicationConfig.host = req.host;
 		// Persist credential references (never tokens) so every cold install of this component —
 		// reboot, new peer, rollback — re-resolves the credential from the store.
 		if (credentialReferences.length) applicationConfig.credentials = credentialReferences;

components/operationsValidation.js

@@ -461,6 +461,10 @@ function deployComponentValidator(req) {
 			})
 			.optional()
 			.messages({ 'any.invalid': 'urlPath must not contain ".."' }),
+		// Virtual hostname the component is served on. Like `urlPath`, this is deployment routing and
+		// belongs on the root-config entry, not in the component's own config.yaml. `hostname()`
+		// rejects a value carrying a port or path, which would never match the router's host compare.
+		host: Joi.string().hostname().optional(),
 		// 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
@@ -490,7 +494,9 @@ function deployComponentValidator(req) {
 		registryAuth: Joi.any().forbidden().messages({
 			'any.unknown': `'registryAuth' has been renamed to 'credentials'`,
 		}),
-	}).with('urlPath', 'package');
+	})
+		.with('urlPath', 'package')
+		.with('host', 'package');
 
 	return validator.validateBySchema(req, deployProjSchema);
 }

components/scopeMount.ts

@@ -0,0 +1,90 @@
+import { InvalidBaseURLPathError, resolveBaseURLPath } from './resolveBaseURLPath.ts';
+
+/**
+ * The routing an operator declared for an application in the *root* config, e.g.
+ *
+ * ```yaml
+ * my-app:
+ *   package: '@my/app'
+ *   host: api.example.com
+ *   urlPath: /v1
+ * ```
+ *
+ * Where an application is served is a deployment concern, not an application concern, so
+ * the root config is authoritative: a checked-in `config.yaml` cannot pin the hostname or
+ * mount point an operator has chosen. The mount is applied to every plugin scope loaded
+ * for that application (and, transitively, to plugins the application itself declares).
+ */
+export interface ScopeMount {
+	host?: string;
+	urlPath?: string;
+}
+
+/**
+ * Normalizes a mount prefix to a leading-slash, no-trailing-slash form ('/v1'), or
+ * undefined when it constrains nothing ('', '/', undefined) — matching
+ * `middlewareChain.normalizeUrlPath`, so a mount that means "the root" composes to
+ * exactly the plugin's own path rather than rewriting it.
+ */
+export function normalizeMountPath(urlPath: string | undefined): string | undefined {
+	if (!urlPath) return undefined;
+	if (urlPath.includes('..')) throw new InvalidBaseURLPathError(urlPath);
+	let normalized = urlPath.startsWith('/') ? urlPath : `/${urlPath}`;
+	normalized = normalized.replace(/\/+$/, '');
+	return normalized.length <= 1 ? undefined : normalized;
+}
+
+/**
+ * Returns the mount, or undefined when it declares no routing at all — so callers can
+ * skip the overlay entirely and leave existing (unmounted) config objects untouched.
+ */
+export function toScopeMount(config: unknown): ScopeMount | undefined {
+	if (!config || typeof config !== 'object') return undefined;
+	const { host, urlPath } = config as ScopeMount;
+	const mountHost = typeof host === 'string' && host ? host : undefined;
+	const mountPath = normalizeMountPath(typeof urlPath === 'string' ? urlPath : undefined);
+	if (!mountHost && !mountPath) return undefined;
+	return { host: mountHost, urlPath: mountPath };
+}
+
+/**
+ * Composes an application mount with a plugin's own `urlPath`.
+ *
+ * The plugin part is resolved first (`resolveBaseURLPath` semantics: `'.'`/`'./x'` namespace
+ * under the plugin name) and the mount is then prefixed, so app-internal structure survives
+ * relocation: mount `/v1` + `static: { urlPath: assets }` → `/v1/assets/`. The result is
+ * already absolute and slash-terminated, which makes it a fixed point of
+ * `resolveBaseURLPath` — downstream consumers (the `server` proxy, `EntryHandler`,
+ * `static`, `fastifyRoutes`) can keep resolving it without compounding the prefix.
+ */
+export function composeMountedUrlPath(
+	mountPath: string | undefined,
+	pluginName: string,
+	pluginUrlPath: string | undefined
+): string | undefined {
+	if (!mountPath) return pluginUrlPath;
+	return `${mountPath}${resolveBaseURLPath(pluginName, pluginUrlPath)}`;
+}
+
+/**
+ * Overlays an application mount onto one plugin's config section.
+ *
+ * `host` is replaced outright — an operator remapping an app's hostname must win over a
+ * value the app shipped, which is the whole point of moving routing to the root config.
+ * `urlPath` is composed rather than replaced, because a plugin's `urlPath` doubles as its
+ * app-internal base path (static's asset root, fastify's route prefix); replacing it would
+ * silently relocate app-internal URLs and collapse distinct plugins onto one path.
+ *
+ * Returns `section` unchanged when there is no mount, so unmounted applications keep both
+ * their exact config values and object identity.
+ */
+export function applyScopeMount<T>(section: T, pluginName: string, mount?: ScopeMount): T {
+	if (!mount || section === undefined || section === null) return section;
+	// A plugin enabled with a bare `true` (e.g. `rest: true`) still needs to carry the mount,
+	// so promote it to an object rather than dropping the routing on the floor.
+	const base: Record<string, unknown> = typeof section === 'object' ? { ...(section as object) } : {};
+	if (mount.host) base.host = mount.host;
+	const composed = composeMountedUrlPath(mount.urlPath, pluginName, base.urlPath as string | undefined);
+	if (composed !== undefined) base.urlPath = composed;
+	return base as T;
+}