From 6daee1acdd88f486e84b801512a8186021ed4e9c Mon Sep 17 00:00:00 2001 From: 0froq Date: Sun, 15 Nov 2026 23:52:38 +0800 Subject: [PATCH] feat(hub): serve static builds from a deploy base buildHub bakes root-absolute URLs for frame bases, dock entries, page scripts, and per-SPA asset references. A deploy base prefixes them so the same output serves under a subpath, while the on-disk deploy-root layout stays unchanged. --- docs/content/6.errors/DF8007.md | 38 ++++ docs/content/8.references/6.hub-api.md | 1 + packages/hub/src/node/__tests__/build.test.ts | 69 +++++++ packages/hub/src/node/build.ts | 183 ++++++++++++++++-- packages/hub/src/node/diagnostics.ts | 4 + .../tsnapi/@devframes/hub/build.snapshot.d.ts | 1 + 6 files changed, 282 insertions(+), 14 deletions(-) create mode 100644 docs/content/6.errors/DF8007.md diff --git a/docs/content/6.errors/DF8007.md b/docs/content/6.errors/DF8007.md new file mode 100644 index 00000000..02dcae81 --- /dev/null +++ b/docs/content/6.errors/DF8007.md @@ -0,0 +1,38 @@ +--- +title: 'DF8007: Hub Base Is Outside the Deploy Base' +description: 'buildHub''s base ("{base}") is not under its deployBase ("{deployBase}"), so the hub itself would be served outside the deploy root.' +--- + +## Message + +> buildHub's base ("`{base}`") is not under its deployBase ("`{deployBase}`"), so the hub itself would be served outside the deploy root. + +## Cause + +`deployBase` is the URL prefix the whole output tree is served under, and the hub sits inside that tree. A hub `base` outside it describes a second deployment, so the baked URLs and the file layout would disagree. + +## Example + +```ts +// ✓ Good: the hub base includes the deploy prefix +await buildHub({ + outDir: 'dist/__devtools', + base: '/ci-build-123456/__devtools/', + deployBase: '/ci-build-123456/', +}) + +// ✗ Bad: the hub would be served at the domain root +await buildHub({ + outDir: 'dist/__devtools', + base: '/__devtools/', + deployBase: '/ci-build-123456/', +}) +``` + +## Fix + +Include the deploy prefix in `base`, or omit `deployBase` when the output is served at the domain root. + +## Source + +- [`packages/hub/src/node/build.ts`](https://github.com/devframes/devframe/blob/main/packages/hub/src/node/build.ts): `buildHub()` rejects a `base` that does not start with `deployBase`. diff --git a/docs/content/8.references/6.hub-api.md b/docs/content/8.references/6.hub-api.md index a79606e3..b16d02c4 100644 --- a/docs/content/8.references/6.hub-api.md +++ b/docs/content/8.references/6.hub-api.md @@ -124,6 +124,7 @@ The options of `buildHub()` from `@devframes/hub/build`: [Static builds](/guide/ |---|---| | `outDir` | Output directory for the hub subtree; corresponds to `base` at serve time (build `base: '/__devframes/'` into `dist/__devframes`). A mount served outside the hub base (a devframe SPA or asset dir kept as a sibling of it) is written to this directory's parent (the deploy root) by its absolute path. | | `base` | Mount base baked into every absolute URL the build emits. Default `/__devframes/`. | +| `deployBase` | URL prefix the deploy root is served under. Root-absolute URLs the build emits are rebased under it. Must be a prefix of `base`. Default `/`. | | `context` | An already-mounted `DevframeHubContext` to bake instead of `devframes` (the build counterpart of `initHub({ context })`); reads `ctx.frames` and `ctx.views.buildStaticDirs`. Mutually exclusive with `devframes`. | | `clean` | Remove `outDir` before writing. Default `true`; set `false` to bake beside an app's own build output. | | `pretty` | Pretty-print RPC dump JSON shards. Default `false` (minified). | diff --git a/packages/hub/src/node/__tests__/build.test.ts b/packages/hub/src/node/__tests__/build.test.ts index 378a79cc..1cf0589c 100644 --- a/packages/hub/src/node/__tests__/build.test.ts +++ b/packages/hub/src/node/__tests__/build.test.ts @@ -228,4 +228,73 @@ describe('buildHub', () => { const index = JSON.parse(readFileSync(join(outDir, '__index.json'), 'utf-8')) expect(index.frames.map((frame: { id: string }) => frame.id)).toEqual(['gamma']) }) + + it('rejects a hub base outside `deployBase`', async () => { + await expect(buildHub({ + outDir: join(mkdtempSync(join(tmpdir(), 'hub-build-out-')), 'hub'), + base: '/__hub/', + deployBase: '/sub/', + cwd: mkdtempSync(join(tmpdir(), 'hub-build-cwd-')), + })).rejects.toThrow(/not under its deployBase/) + }) + + it('rebases the deploy-root layout under `deployBase`', async () => { + const deployRoot = mkdtempSync(join(tmpdir(), 'hub-build-out-')) + const outDir = join(deployRoot, '__devtools') + const panel = makeDist('') + writeFileSync(join(panel, 'app.js'), 'export const base = "/__panel/"\n', 'utf-8') + + await buildHub({ + outDir, + base: '/ci-build-123456/__devtools/', + deployBase: '/ci-build-123456/', + cwd: mkdtempSync(join(tmpdir(), 'hub-build-cwd-')), + async configure(ctx) { + await ctx.install(makeFrame('alpha', { + distDir: makeDist(''), + }), { base: '/__alpha/' }) + ctx.views.hostStatic('/__panel/', panel) + ctx.docks.register({ + id: 'panel', + title: 'Panel', + icon: '/__panel/icon.svg', + type: 'iframe', + url: '/__panel/', + }) + }, + }) + + // The deploy root layout is unchanged on disk: siblings sit beside the hub. + expect(existsSync(join(outDir, '__connection.json'))).toBe(true) + expect(existsSync(join(deployRoot, '__alpha/index.html'))).toBe(true) + expect(existsSync(join(deployRoot, '__panel/app.js'))).toBe(true) + + // Discovery and per-frame meta spell the served URLs. + const index = JSON.parse(readFileSync(join(outDir, '__index.json'), 'utf-8')) + expect(index.base).toBe('/ci-build-123456/__devtools/') + expect(index.frames).toEqual([ + { id: 'alpha', base: '/ci-build-123456/__alpha/', title: 'Frame alpha' }, + ]) + const frameMeta = JSON.parse(readFileSync(join(deployRoot, '__alpha/__connection.json'), 'utf-8')) + expect(frameMeta.baseUrl).toBe('/ci-build-123456/__devtools/__connection.json') + + // The baked RPC dump carries the served dock URL, not the root-absolute one. + const manifest = JSON.parse(readFileSync(join(outDir, '__rpc-dump/index.json'), 'utf-8')) + const stateEntry = manifest['devframe:rpc:server-state:get'] + const records = (Object.values(stateEntry.records) as string[]) + .map(path => readFileSync(join(outDir, path), 'utf-8')) + const docksRecord = records.find(text => text.includes(HUB_EVENTS.sharedState.docks))! + expect(docksRecord).toContain('/ci-build-123456/__alpha/') + expect(docksRecord).toContain('/ci-build-123456/__panel/') + expect(docksRecord).not.toContain('"/__alpha/"') + expect(docksRecord).not.toContain('"/__panel/"') + + // Root-absolute asset references inside copied SPAs follow the new location. + expect(readFileSync(join(deployRoot, '__alpha/index.html'), 'utf-8')) + .toContain('/ci-build-123456/__alpha/app.js') + expect(readFileSync(join(deployRoot, '__panel/index.html'), 'utf-8')) + .toContain('/ci-build-123456/__panel/app.js') + expect(readFileSync(join(deployRoot, '__panel/app.js'), 'utf-8')) + .toContain('/ci-build-123456/__panel/') + }) }) diff --git a/packages/hub/src/node/build.ts b/packages/hub/src/node/build.ts index 1a580b65..dd182bb2 100644 --- a/packages/hub/src/node/build.ts +++ b/packages/hub/src/node/build.ts @@ -12,7 +12,7 @@ import { collectStaticRpcDump, writeStaticRpcDump } from 'devframe/rpc/dump' import { colors as c } from 'devframe/utils/colors' import { resolveStaticAssetsSource } from 'devframe/utils/remote-assets' import { joinURL } from 'devframe/utils/url' -import { dirname, resolve } from 'pathe' +import { dirname, extname, resolve } from 'pathe' import { DEVFRAMES_HUB_BASE, DOCK_RENDERERS_STATE_KEY, normalizeHubBase } from '../constants' import { mountDevframes, renderClientImportsModule, resolveDevframesInput, resolveRendererRegistrations } from './assemble' import { createHubContext } from './context' @@ -35,6 +35,13 @@ export interface BuildHubOptions { * pointers). Default: `/__devframes/`. */ base?: string + /** + * URL prefix the deploy root is served under (e.g. `/ci-build-123456/`). + * Root-absolute URLs the build emits are rebased under it, so the output + * works below the domain root. Must be a prefix of + * {@link BuildHubOptions.base}. Default: `/`. + */ + deployBase?: string /** Devframes to bake as docks, same input as `initHub({ devframes })`. */ devframes?: DevframesInput /** @@ -113,6 +120,9 @@ export async function buildHub(options: BuildHubOptions): Promise { throw diagnostics.DF8002() const base = normalizeHubBase(options.base ?? DEVFRAMES_HUB_BASE) + const deployBase = normalizeHubBase(options.deployBase ?? '/') + if (deployBase !== '/' && !base.startsWith(deployBase)) + throw diagnostics.DF8007({ base, deployBase }) const cwd = options.cwd ?? process.cwd() const outDir = resolve(cwd, options.outDir) const rendererRegistrations = resolveRendererRegistrations(options.renderers ?? []) @@ -132,26 +142,55 @@ export async function buildHub(options: BuildHubOptions): Promise { * corresponds to the hub base). A base outside it is a deploy-root sibling: * `outDir`'s parent is the deploy root, and the base resolves under it by its * absolute path. This is the layout Vite DevTools serves, where devframe SPAs - * and assets sit beside `/__devtools/` rather than under it. + * and assets sit beside `/__devtools/` rather than under it. The deploy + * prefix, when set, is stripped first: it moves the URLs, not the files. */ const deployRoot = dirname(outDir) + const hubBase = stripDeployBase(base, deployBase) const resolveOutPath = (urlBase: string): string => { - if (urlBase.startsWith(base)) - return resolve(outDir, urlBase.slice(base.length)) - if (!urlBase.startsWith('/')) + const localBase = stripDeployBase(urlBase, deployBase) + if (localBase.startsWith(hubBase)) + return resolve(outDir, localBase.slice(hubBase.length)) + if (!localBase.startsWith('/')) throw diagnostics.DF8006({ urlBase, base }) - return resolve(deployRoot, urlBase.slice(1)) + return resolve(deployRoot, localBase.slice(1)) } - await copyBuildStatics(ctx, resolveOutPath) + // Everything served outside the deploy prefix needs it added to the baked + // URLs. Longest first, so a nested mount is rewritten before its parent. + const servedBases = new Set([ + ...ctx.frames.map(frame => frame.base), + ...ctx.views.buildStaticDirs.map(dir => dir.baseUrl), + ]) + const rewrites = deployBase === '/' + ? [] + : [...servedBases] + .filter(url => url.startsWith('/') && !isUnderDeployBase(url, deployBase)) + .sort((a, b) => b.length - a.length) + .map(url => [ + url, + serveUrl(url, deployBase), + ] as const) + const rebaseText = createTextRebaser(rewrites, deployBase) + const rebaseValue = rewrites.length + ? createUrlValueRebaser(rewrites) + : (value: T): T => value + + await copyBuildStatics(ctx, resolveOutPath, rewrites.length ? rebaseText : undefined) await publishRendererManifest(ctx, rendererRegistrations, base, outDir) await writeUiArtifacts(options.ui, outDir) - await fs.writeFile(resolve(outDir, DEVFRAME_DOCK_IMPORTS_FILENAME), renderClientImportsModule(ctx), 'utf-8') - await writeHubIndex(ctx, base, outDir, options) - await writeConnectionMetas(ctx, base, outDir, resolveOutPath) + await fs.writeFile( + resolve(outDir, DEVFRAME_DOCK_IMPORTS_FILENAME), + rebaseText(renderClientImportsModule(ctx)), + 'utf-8', + ) + await writeHubIndex(ctx, base, outDir, options, deployBase) + await writeConnectionMetas(ctx, base, outDir, resolveOutPath, rebaseValue) console.log(c.cyan`[devframes-hub] writing RPC dump to ${resolve(outDir, '__rpc-dump')}`) const dump = await collectStaticRpcDump(ctx.rpc.definitions.values(), ctx) + for (const file of Object.values(dump.files)) + file.data = rebaseValue(file.data) await writeStaticRpcDump(dump, outDir, { pretty: options.pretty }) const count = ctx.frames.length @@ -160,6 +199,110 @@ export async function buildHub(options: BuildHubOptions): Promise { : 's'} -> ${outDir}`) } +/** File types that can carry absolute URLs. */ +const TEXT_ASSET_EXTENSIONS = new Set([ + '.css', + '.html', + '.js', + '.json', + '.mjs', + '.svg', +]) + +/** Whether a root-absolute URL already sits under the deploy prefix. */ +function isUnderDeployBase(url: string, deployBase: string): boolean { + return deployBase === '/' || url === deployBase || url.startsWith(deployBase) +} + +/** + * `url` without the deploy prefix, so a served URL maps onto its on-disk + * layout. The prefix moves URLs, not files. + */ +function stripDeployBase(url: string, deployBase: string): string { + return deployBase !== '/' && url.startsWith(deployBase) + ? `/${url.slice(deployBase.length)}` + : url +} + +/** Prefix a root-absolute URL with the deploy base. Idempotent. */ +function serveUrl(url: string, deployBase: string): string { + if (!url.startsWith('/') || isUnderDeployBase(url, deployBase)) + return url + return joinURL(deployBase, url) +} + +/** + * Rewrite each URL prefix in a text asset, skipping occurrences that already + * carry the deploy prefix. + */ +function createTextRebaser( + rewrites: readonly (readonly [string, string])[], + deployBase: string, +): (text: string) => string { + if (!rewrites.length || deployBase === '/') + return text => text + const prefixedBefore = deployBase.slice(0, -1) + return (text) => { + let result = text + for (const [from, to] of rewrites) { + result = result.replaceAll(from, (match: string, offset: number, whole: string) => { + const alreadyPrefixed = offset >= prefixedBefore.length + && whole.startsWith(prefixedBefore, offset - prefixedBefore.length) + return alreadyPrefixed ? match : to + }) + } + return result + } +} + +/** Rebase strings in an RPC payload that start with a registered URL prefix. */ +function createUrlValueRebaser( + rewrites: readonly (readonly [string, string])[], +): (value: T) => T { + const rebaseString = (value: string): string => { + for (const [from, to] of rewrites) { + if (value === from.slice(0, -1)) + return to.slice(0, -1) + if (value.startsWith(from)) + return `${to}${value.slice(from.length)}` + } + return value + } + const visit = (value: T): T => { + if (typeof value === 'string') + return rebaseString(value) as T + if (Array.isArray(value)) + return value.map(item => visit(item)) as T + if (value && typeof value === 'object') { + const prototype = Object.getPrototypeOf(value) + if (prototype !== Object.prototype && prototype !== null) + return value + return Object.fromEntries( + Object.entries(value).map(([key, item]) => [ + key, + visit(item), + ]), + ) as T + } + return value + } + return visit +} + +/** Rewrite the text assets under a copied static dir in place. */ +async function rebaseTextAssets(dir: string, rebase: (text: string) => string): Promise { + const entries = await fs.readdir(dir, { recursive: true, withFileTypes: true }) + for (const entry of entries) { + if (!entry.isFile() || !TEXT_ASSET_EXTENSIONS.has(extname(entry.name))) + continue + const filepath = resolve(entry.parentPath, entry.name) + const text = await fs.readFile(filepath, 'utf-8') + const next = rebase(text) + if (next !== text) + await fs.writeFile(filepath, next, 'utf-8') + } +} + /** * Build a `mode: 'build'` hub context and mount the `devframes` input. The host * copies nothing live (`mountStatic`/`mountConnectionMeta` are no-ops): every @@ -213,7 +356,11 @@ async function createAndMountContext(options: BuildHubOptions, base: string, cwd * remote source (e.g. a plugin's `--assets` package) resolves to the same * locally-installed copy it would serve live. */ -async function copyBuildStatics(ctx: DevframeHubContext, resolveOutPath: (urlBase: string) => string): Promise { +async function copyBuildStatics( + ctx: DevframeHubContext, + resolveOutPath: (urlBase: string) => string, + rebaseText?: (text: string) => string, +): Promise { const storageDir = ctx.host.getStorageDir('project') for (const { baseUrl, source, resolveFrom } of ctx.views.buildStaticDirs) { const target = resolveOutPath(baseUrl) @@ -223,6 +370,8 @@ async function copyBuildStatics(ctx: DevframeHubContext, resolveOutPath: (urlBas await fs.cp(resolved, target, { recursive: true }) else await resolved.materialize(target) + if (rebaseText) + await rebaseTextAssets(target, rebaseText) } } @@ -278,12 +427,17 @@ async function writeHubIndex( base: string, outDir: string, options: BuildHubOptions, + deployBase: string, ): Promise { await fs.writeFile(resolve(outDir, '__index.json'), `${JSON.stringify({ name: options.name, version: options.version, base, - frames: ctx.frames.map(({ id, base, title }) => ({ id, base, title })), + frames: ctx.frames.map(({ id, base, title }) => ({ + id, + base: serveUrl(base, deployBase), + title, + })), endpoints: { connection: DEVFRAME_CONNECTION_META_FILENAME, clientImports: DEVFRAME_DOCK_IMPORTS_FILENAME, @@ -307,19 +461,20 @@ async function writeConnectionMetas( base: string, outDir: string, resolveOutPath: (urlBase: string) => string, + rebaseValue: (value: T) => T, ): Promise { const jsonSerializableMethods: string[] = [] for (const def of ctx.rpc.definitions.values()) { if (def.jsonSerializable === true) jsonSerializableMethods.push(def.name) } - const meta: ConnectionMeta = { + const meta: ConnectionMeta = rebaseValue({ backend: 'static', jsonSerializableMethods, ...(Object.keys(ctx.staticConfig).length > 0 ? { configs: ctx.staticConfig } : {}), - } + } satisfies ConnectionMeta) await fs.writeFile(resolve(outDir, DEVFRAME_CONNECTION_META_FILENAME), JSON.stringify(meta, null, 2), 'utf-8') const frameMeta: ConnectionMeta = { ...meta, diff --git a/packages/hub/src/node/diagnostics.ts b/packages/hub/src/node/diagnostics.ts index 55933c41..b4acfe47 100644 --- a/packages/hub/src/node/diagnostics.ts +++ b/packages/hub/src/node/diagnostics.ts @@ -34,6 +34,10 @@ export const diagnostics = defineDiagnostics({ why: (p: { urlBase: string, base: string }) => `A static hub build writes each mount either under its base ("${p.base}") or as an absolute-path sibling of it, but "${p.urlBase}" is neither.`, fix: 'buildHub maps a mount under the hub base into its `outDir`, and any other mount to the deploy root (`outDir`\'s parent) by its absolute path. Give the mount an absolute base (starting with `/`) so it resolves to one of those.', }, + DF8007: { + why: (p: { base: string, deployBase: string }) => `buildHub's base ("${p.base}") is not under its deployBase ("${p.deployBase}"), so the hub itself would be served outside the deploy root.`, + fix: 'Pass the hub mount base with the deploy prefix included, e.g. `base: "/ci-build-123456/__devtools/"` with `deployBase: "/ci-build-123456/"`.', + }, DF8100: { why: (p: { id: string }) => `Dock with id "${p.id}" is already registered`, fix: 'Use the `force` parameter to overwrite an existing registration.', diff --git a/tests/__snapshots__/tsnapi/@devframes/hub/build.snapshot.d.ts b/tests/__snapshots__/tsnapi/@devframes/hub/build.snapshot.d.ts index 4178d6dd..5553f68f 100644 --- a/tests/__snapshots__/tsnapi/@devframes/hub/build.snapshot.d.ts +++ b/tests/__snapshots__/tsnapi/@devframes/hub/build.snapshot.d.ts @@ -5,6 +5,7 @@ export interface BuildHubOptions { outDir: string; base?: string; + deployBase?: string; devframes?: DevframesInput; context?: DevframeHubContext; services?: DevframeServiceInput[];