Route applications by host/urlPath declared in the root config

[kriszyp]

Summary

Makes host/urlPath on an application's root-config entry authoritative for where that application is served.

# harper-config.yaml
my-app:
  host: api.example.com
  urlPath: /v1

Why

Where an application is served is a deployment 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 had to be checked into the app, unoverridable from outside it (the env-config overlay is root-config-only).

Worse, these keys 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 #1113 described only ever held for a root-declared plugin, whose scope does read the root config.

Design

The mount is applied at exactly one place: the routing boundary, in Scope's server proxy. The router strips it before a handler runs, so everything inside the application — entry URL paths, and the resource paths graphqlSchema/jsResource derive from them — stays mount-relative. Scope.mount / Scope.externalBasePath() expose it narrowly for the only two cases that need it: emitting an absolute URL to the client (static's redirect Location) and bypassing the routed chain (legacy fastify).

• host replaces the app's value outright — an operator remapping a hostname must win over one the app shipped.
• urlPath composes rather than replaces, because a plugin's urlPath doubles as its app-internal base path (static's asset root, fastify's prefix). Mount /v1 + static: { urlPath: assets } → /v1/assets/. Replacing would silently relocate app-internal URLs and collapse distinct plugins onto one path.
• Applied on both load paths — the root-config package recursion and the components-root directory scan. The scan matters most: it loads apps with no root entry at all, so a mount works for a payload-deployed app too.
• deploy_component accepts and persists host alongside urlPath.

Where to look

• components/Scope.ts — the mount is applied here and nowhere else; that's the invariant the whole change rests on. The proxy also now resolves a config-supplied urlPath instead of passing it through, fixing REST spreading its config section and handing the router a literal './' (→ unmatchable route '/.').
• server/REST.ts — registration was guarded by a module-level started boolean, so with two applications mounted at different paths only the first got a chain and the second's REST API silently 404'd. Now keyed per mount. This is the headline use case, so it's worth a look.
• server/middlewareChain.ts — host matching was case-sensitive though hostnames aren't (RFC 4343), so a configured API.example.com could never match; [::1]:9926 also parsed to [.
• components/scopeMount.ts — the composed path is deliberately a fixed point of resolveBaseURLPath, since consumers resolve it again.

Second commit is the cross-model review response — it reworked the approach (see below), so reading the commits in order may be easier than the squashed diff.

Open items for the reviewer

• Legacy fastify + host is a known limitation, not fixed here. fastifyRoutes registers as a global fallback on the bare server, so it never joins a routed chain and a host mount cannot constrain it — those routes answer on every hostname. A urlPath mount does work (it becomes the fastify prefix). Loading a host-mounted app with fastifyRoutes now warns rather than implying isolation it can't provide. Fixing it properly means routing a raw http.Server through a chain, which the chain doesn't support. Happy to file a follow-up if you'd rather block on it.
• A mount is routing, not isolation. Exported tables stay instance-wide, so one app's table is reachable through any mounted REST route. Asserted explicitly in app-mount-two.test.ts and documented — flagging in case you expected a namespace boundary.
• urlPath composition vs. replacement is the one semantic judgment call; rationale above. Replacement would be the alternative if you disagree.
• The initial approach overlaid the mount inside OptionsWatcher so getAll() was the single effective view. Codex review exposed that this also feeds the entry pipeline, so graphqlSchema registered /v1/MountedThing while REST looked up MountedThing — every mounted REST route 404'd, hidden in the single-app static test because static de-prefixes its own keys. Reverted to the routing-boundary-only design above.

Tests

unitTests/components/scopeMount.test.js (new), plus additions to Scope, middlewareChain, and deployComponentValidator suites. Integration: app-root-mount.test.ts (urlPath / host / both, and a mounted table round-trip) and app-mount-two.test.ts (two apps, two mounts — the REST regression). 38/38 integration pass; affected unit suites green. componentLoader.test.js hangs locally on this machine (pre-existing watcher contention) — relying on CI for it.

Docs: Route applications by host/urlPath in the root config (HarperFast/documentation#612)

Generated by Claude Opus 5, with cross-model review by OpenAI Codex (the Gemini leg timed out — no coverage from it).

[claude]

Reviewed; no blockers found.

[Ethan-Arrowood]

The routing-boundary design is sound and docs coverage (documentation#612, including the case-sensitivity correction) is good. Two significant gaps first, then smaller items — all net-new, nothing from the earlier threads (those all resolved cleanly at b6f16619).

One question the inline comments raise: was HTTP/2 considered for host matching? If host mounts are h1-only by design, that limitation belongs in DESIGN.md and the docs PR.

Also from the PR description: it says fastify + host mount "warns", but the code throws (and DESIGN.md documents the throw — which is correct). Worth updating the description so the merge record matches.

Procedural note: both significant findings share a root cause — routing config has two entry paths (deploy op vs hand-edited root config) with validation on only one. A standing rule that a new root-config key must state where the hand-edited path is validated would catch this class at review time.

_{sent with Claude Fable 5}