Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 38 additions & 0 deletions docs/content/6.errors/DF8007.md
Original file line number Diff line number Diff line change
@@ -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`.
1 change: 1 addition & 0 deletions docs/content/8.references/6.hub-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -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). |
Expand Down
69 changes: 69 additions & 0 deletions packages/hub/src/node/__tests__/build.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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('<script type="module" src="/__panel/app.js"></script>')
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('<script type="module" src="/__alpha/app.js"></script>'),
}), { 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/')
})
})
183 changes: 169 additions & 14 deletions packages/hub/src/node/build.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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'
Expand All @@ -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
/**
Expand Down Expand Up @@ -113,6 +120,9 @@ export async function buildHub(options: BuildHubOptions): Promise<void> {
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 ?? [])
Expand All @@ -132,26 +142,55 @@ export async function buildHub(options: BuildHubOptions): Promise<void> {
* 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)
: <T>(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
Expand All @@ -160,6 +199,110 @@ export async function buildHub(options: BuildHubOptions): Promise<void> {
: '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])[],
): <T>(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 = <T>(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<void> {
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
Expand Down Expand Up @@ -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<void> {
async function copyBuildStatics(
ctx: DevframeHubContext,
resolveOutPath: (urlBase: string) => string,
rebaseText?: (text: string) => string,
): Promise<void> {
const storageDir = ctx.host.getStorageDir('project')
for (const { baseUrl, source, resolveFrom } of ctx.views.buildStaticDirs) {
const target = resolveOutPath(baseUrl)
Expand All @@ -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)
}
}

Expand Down Expand Up @@ -278,12 +427,17 @@ async function writeHubIndex(
base: string,
outDir: string,
options: BuildHubOptions,
deployBase: string,
): Promise<void> {
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,
Expand All @@ -307,19 +461,20 @@ async function writeConnectionMetas(
base: string,
outDir: string,
resolveOutPath: (urlBase: string) => string,
rebaseValue: <T>(value: T) => T,
): Promise<void> {
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,
Expand Down
Loading
Loading