fix: remove assets resolution

Author: antfu

docs/guide/build-your-own-hub-ui.md

@@ -61,6 +61,14 @@ Honor `when` / `visibility` clauses, `category` grouping (order from
 `DEFAULT_CATEGORIES_ORDER` in `@devframes/hub/constants`), and the
 `hub:docks:activate` broadcast.
 
+An `iframe` entry whose devframe serves its UI from a [remote assets
+package](./client-assets) can also report that those assets are unreachable: its
+fallback page posts a `RemoteAssetsErrorMessage`
+(`DEVFRAME_REMOTE_ASSETS_ERROR_MESSAGE_TYPE`, both re-exported from
+`@devframes/hub/constants`) to `window.parent`. Match the message against the
+frame's own `contentWindow` and you can offer the install command and a retry in
+your own UI; leaving it alone keeps the fallback page visible inside the frame.
+
 ### The renderer registry and its fallback
 
 **Every other dock type routes through the dock-renderer registry** — build it

docs/guide/client-assets.md

@@ -95,6 +95,12 @@ npm install @acme/my-tool-assets
 
 Set `offline: true` to guarantee the CDN is never contacted, or point `provider` at an internal npm mirror.
 
+### When the assets can't be reached
+
+A file that is in neither a local install nor the cache, with the provider unreachable, raises [`DF0060`](../errors/DF0060). An HTML navigation gets a self-contained page naming the assets package, the install command that makes it work offline, and the provider's own error, with a retry button.
+
+That page also posts its failure to `window.parent` (`DEVFRAME_REMOTE_ASSETS_ERROR_MESSAGE_TYPE` from `devframe/constants`, payload `RemoteAssetsErrorMessage`), so a viewer embedding the tool in an iframe can render the same thing in its own design — `@devframes/hub-ui` shows it as a panel over the dock's frame ([building your own](./build-your-own-hub-ui)).
+
 ### Custom provider
 
 A custom provider supplies the file URL, and optionally a file listing (used for correct 404s, SPA fallback, and static builds):

packages/devframe/src/constants.ts

@@ -80,6 +80,16 @@ export const DEVFRAME_VIEWER_ORIGIN_QUERY_PARAM = 'devframe_viewer_origin'
 /** Token that authorizes an external viewer origin registration. */
 export const DEVFRAME_VIEWER_ORIGIN_TOKEN_QUERY_PARAM = 'devframe_viewer_origin_token'
 
+/**
+ * `postMessage` type the remote-assets fallback page posts to `window.parent`
+ * on load. That page is what a devframe serves (with a 502) when its client
+ * assets can be reached neither locally nor through their CDN provider — the
+ * message lets an embedding viewer replace the bare page with its own UI
+ * (`@devframes/hub-ui` does, in its iframe view). Payload shape:
+ * `RemoteAssetsErrorMessage` (`devframe/types`).
+ */
+export const DEVFRAME_REMOTE_ASSETS_ERROR_MESSAGE_TYPE = 'devframe:remote-assets-error'
+
 /**
  * Prefix that marks an RPC method as callable before a connection is
  * trusted. This is the *only* rule the pre-trust gate applies — there is no

packages/devframe/src/types/remote-assets.ts

@@ -41,7 +41,7 @@ export interface RemoteAssets {
    * with zero network. Omitting it skips the installed-package step —
    * cache + CDN still work.
    */
-  resolveFrom?: string
+  resolveFrom?: string | null
   /** Custom fetch implementation (proxies, tests). Defaults to the global `fetch`. */
   fetch?: typeof globalThis.fetch
   /**
@@ -82,6 +82,24 @@ export interface RemoteAssetsProviderCustom {
  */
 export type StaticAssetsSource = string | RemoteAssets
 
+/**
+ * What the remote-assets fallback page posts to `window.parent` when a
+ * devframe's client assets could be served from neither a local install nor
+ * their provider. A viewer embedding the devframe in an iframe listens for
+ * `DEVFRAME_REMOTE_ASSETS_ERROR_MESSAGE_TYPE` (`devframe/constants`) and can
+ * render the failure in its own design, with the two ways out the page also
+ * spells out: install `package@version` locally, or restore network access.
+ */
+export interface RemoteAssetsErrorMessage {
+  type: 'devframe:remote-assets-error'
+  /** npm package the assets are published as. */
+  package: string
+  /** Exact version the devframe asked for. */
+  version: string
+  /** Why the fetch failed, as reported by the provider or the network stack. */
+  reason: string
+}
+
 /**
  * A resolved, servable handle over a {@link RemoteAssets} declaration —
  * produced by `resolveStaticAssetsSource()` (`devframe/utils/remote-assets`)

packages/devframe/src/utils/remote-assets.test.ts

@@ -1,13 +1,14 @@
 import type { AddressInfo } from 'node:net'
 import type { MockInstance } from 'vitest'
-import type { RemoteAssets, RemoteAssetsStore } from '../types/remote-assets'
+import type { RemoteAssets, RemoteAssetsErrorMessage, RemoteAssetsStore } from '../types/remote-assets'
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs'
 import { createServer } from 'node:http'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { pathToFileURL } from 'node:url'
 import { H3, toNodeHandler } from 'h3'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { DEVFRAME_REMOTE_ASSETS_ERROR_MESSAGE_TYPE } from '../constants'
 import { resolveStaticAssetsSource } from './remote-assets'
 import { serveStaticHandler } from './serve-static'
 
@@ -101,6 +102,43 @@ describe('resolveStaticAssetsSource (remote store)', () => {
     expect(cdn.calls.filter(u => u.includes('app.js')).length).toBe(before)
   })
 
+  it('proxies the provider response: own content headers, no transfer-level ones', async () => {
+    const upstream = (): Response => new Response('console.log("app")', {
+      status: 200,
+      headers: {
+        'content-type': 'application/octet-stream',
+        'content-encoding': 'gzip',
+        'content-length': '11',
+        'etag': 'W/"abc"',
+        'set-cookie': 'session=1',
+        'x-frame-options': 'DENY',
+        'cache-control': 'public, max-age=31536000',
+      },
+    })
+    const store = storeFor({ fetch: async () => upstream() }, makeTmp())
+
+    const res = (await store.serve('/assets/app.js'))!
+    // `fetch` hands over a decoded body, so the encoded length would be a lie.
+    expect(res.headers.get('content-encoding')).toBeNull()
+    expect(res.headers.get('content-length')).toBeNull()
+    // The provider's policy headers stay with the provider.
+    expect(res.headers.get('set-cookie')).toBeNull()
+    expect(res.headers.get('x-frame-options')).toBeNull()
+    expect(res.status).toBe(200)
+    expect(res.headers.get('content-type')).toBe('text/javascript')
+    expect(res.headers.get('cache-control')).toBe('no-store')
+    expect(res.headers.get('etag')).toBe('W/"abc"')
+    await expect(res.text()).resolves.toBe('console.log("app")')
+  })
+
+  it('keeps the upstream content-length when the body arrived unencoded', async () => {
+    const store = storeFor(
+      { fetch: async () => new Response('hello', { headers: { 'content-length': '5' } }) },
+      makeTmp(),
+    )
+    expect((await store.serve('/assets/app.js'))!.headers.get('content-length')).toBe('5')
+  })
+
   it('resolves the manifest: index fallback, SPA fallback, and extension-ed 404', async () => {
     const cdn = fakeCdn(CDN_FILES)
     const store = storeFor(cdn, makeTmp())
@@ -273,6 +311,13 @@ describe('serveStaticHandler with a remote store', () => {
       const body = await res.text()
       expect(body).toContain('Client assets unavailable')
       expect(body).toContain('@scope/demo-client')
+      // The page reports itself to an embedding viewer, which renders the
+      // same failure in its own UI (`@devframes/hub-ui`'s iframe view).
+      expect(body).toContain('window.parent.postMessage(')
+      expect(body).toContain(DEVFRAME_REMOTE_ASSETS_ERROR_MESSAGE_TYPE)
+      const payload = JSON.parse(/postMessage\((\{.*?\}), '\*'\)/.exec(body)![1]) as RemoteAssetsErrorMessage
+      expect(payload).toMatchObject({ package: '@scope/demo-client', version: '1.2.3' })
+      expect(payload.reason).toContain('network down')
 
       const asset = await fetch(`${url}/app.js`, { headers: { accept: '*/*' } })
       expect(asset.status).toBe(502)

packages/devframe/src/utils/remote-assets.ts

@@ -10,11 +10,27 @@ import { mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises'
 import { createRequire } from 'node:module'
 import { Readable } from 'node:stream'
 import { lookup } from 'mrmime'
+import { createDebug } from 'obug'
 import { dirname, extname, join, normalize, sep } from 'pathe'
 import { diagnostics } from '../node/diagnostics'
 
+const debugFetch = createDebug('devframe:remote-assets:fetch')
+const debugCache = createDebug('devframe:remote-assets:cache')
+
 const MANIFEST_FILENAME = '.manifest.json'
 
+/**
+ * Upstream response headers replayed to the browser. Everything outside this
+ * list is dropped, because it describes the *provider's* transfer rather than
+ * the file: hop-by-hop and encoding headers no longer match the body `fetch`
+ * already decoded, and a CDN's policy headers (`set-cookie`, `cache-control`,
+ * framing/CSP) belong to its origin — replaying them under the dev server's
+ * origin could just as well break the iframe these assets render in.
+ */
+const PROXIED_HEADERS = ['content-language', 'etag', 'last-modified'] as const
+
+const CACHE_CONTROL_HEADER = 'no-store'
+
 // ---------------------------------------------------------------------------
 // Providers
 // ---------------------------------------------------------------------------
@@ -48,18 +64,22 @@ const providers: Record<'jsdelivr' | 'unpkg', Required<RemoteAssetsProviderCusto
   jsdelivr: {
     fileUrl: (pkg, version, filePath) => `https://cdn.jsdelivr.net/npm/${pkg}@${version}/${filePath}`,
     listFiles: async (pkg, version, fetchImpl) => {
-      const res = await fetchImpl(`https://data.jsdelivr.com/v1/packages/npm/${pkg}@${version}`)
+      const url = `https://data.jsdelivr.com/v1/packages/npm/${pkg}@${version}`
+      debugFetch('listing files for %s@%s from %s', pkg, version, url)
+      const res = await fetchImpl(url)
       if (!res.ok)
-        throw new Error(`HTTP ${res.status} from data.jsdelivr.com`)
+        throw new Error(`HTTP ${res.status} from ${url}`)
       return flattenTree((await res.json() as { files?: TreeNode[] }).files ?? [], 'name')
     },
   },
   unpkg: {
     fileUrl: (pkg, version, filePath) => `https://unpkg.com/${pkg}@${version}/${filePath}`,
     listFiles: async (pkg, version, fetchImpl) => {
-      const res = await fetchImpl(`https://unpkg.com/${pkg}@${version}/?meta`)
+      const url = `https://unpkg.com/${pkg}@${version}/?meta`
+      debugFetch('listing files for %s@%s from %s', pkg, version, url)
+      const res = await fetchImpl(url)
       if (!res.ok)
-        throw new Error(`HTTP ${res.status} from unpkg.com`)
+        throw new Error(`HTTP ${res.status} from ${url}`)
       return flattenTree([await res.json() as TreeNode], 'path')
     },
   },
@@ -81,7 +101,7 @@ function resolveProvider(assets: RemoteAssets): { provider: RemoteAssetsProvider
  * installed version warns (`DF0062`); a different major throws (`DF0061`).
  */
 function resolveInstalled(assets: RemoteAssets): string | undefined {
-  if (!assets.resolveFrom)
+  if (assets.resolveFrom == null)
     return undefined
   let pkgJsonPath: string
   let installed: unknown
@@ -116,6 +136,30 @@ function contentTypeFor(filePath: string): string {
   return type === 'text/html' ? 'text/html; charset=utf-8' : type
 }
 
+/**
+ * Headers for a file streamed through from the provider. `Content-Type` and
+ * `Cache-Control` are ours, so a file looks identical whether it came from the
+ * provider or from the cache ({@link createStore}'s `serveCached`).
+ */
+function proxyHeaders(filePath: string, upstream: Headers): Headers {
+  const headers = new Headers({
+    'Content-Type': contentTypeFor(filePath),
+    'Cache-Control': CACHE_CONTROL_HEADER,
+  })
+  // `fetch` decodes the body, so an encoded response's `Content-Length`
+  // counts bytes the browser will never see — it only survives verbatim.
+  const encoding = upstream.get('content-encoding')
+  const length = upstream.get('content-length')
+  if (length && (!encoding || encoding === 'identity'))
+    headers.set('Content-Length', length)
+  for (const name of PROXIED_HEADERS) {
+    const value = upstream.get(name)
+    if (value != null)
+      headers.set(name, value)
+  }
+  return headers
+}
+
 /** Clean a request path into a safe package-relative POSIX path, or `null` if it escapes root. */
 function cleanRequestPath(urlPath: string): string | null {
   let cleaned: string
@@ -155,13 +199,19 @@ function createStore(assets: RemoteAssets, cacheDir: string): RemoteAssetsStore
 
   async function loadManifest(): Promise<Set<string> | null> {
     const manifestFile = join(cacheDir, MANIFEST_FILENAME)
-    try {
-      return new Set(JSON.parse(await readFile(manifestFile, 'utf8')) as string[])
+    if (existsSync(manifestFile)) {
+      try {
+        return new Set(JSON.parse(await readFile(manifestFile, 'utf8')) as string[])
+      }
+      catch {}
     }
-    catch {}
     if (assets.offline || !provider.listFiles)
       return null
     try {
+      // A listing failure is not fatal — requests degrade to probing the
+      // provider per candidate. Only a file that can't be fetched at all
+      // surfaces to the user (`DF0060`, and the fallback page that carries
+      // it into the viewer — see `remoteErrorPage` in `serve-static`).
       const files = await provider.listFiles(normalized.package, normalized.version, fetchImpl)
       await mkdir(cacheDir, { recursive: true })
       await writeFile(manifestFile, JSON.stringify(files), 'utf8').catch(() => {})
@@ -188,8 +238,13 @@ function createStore(assets: RemoteAssets, cacheDir: string): RemoteAssetsStore
     catch {
       return null
     }
+    debugCache('serving %s from cache (%d bytes)', filePath, size)
     return new Response(Readable.toWeb(createReadStream(abs)) as ReadableStream<Uint8Array>, {
-      headers: { 'Content-Type': contentTypeFor(filePath), 'Content-Length': String(size), 'Cache-Control': 'no-store' },
+      headers: {
+        'Content-Type': contentTypeFor(filePath),
+        'Content-Length': String(size),
+        'Cache-Control': CACHE_CONTROL_HEADER,
+      },
     })
   }
 
@@ -213,6 +268,7 @@ function createStore(assets: RemoteAssets, cacheDir: string): RemoteAssetsStore
     const url = provider.fileUrl(normalized.package, normalized.version, filePath)
     let res: Response
     try {
+      debugFetch('fetching %s from %s', filePath, url)
       res = await fetchImpl(url)
     }
     catch (error) {
@@ -226,11 +282,15 @@ function createStore(assets: RemoteAssets, cacheDir: string): RemoteAssetsStore
       await res.body?.cancel().catch(() => {})
       throw diagnostics.DF0060({ url, package: normalized.package, reason: `HTTP ${res.status}` })
     }
+    // The body is consumed twice — once by the client, once by the cache
+    // writer — so the client gets a fresh `Response` over its own branch of
+    // the tee; `res` itself is unusable from here on (the tee locked its body).
     const [toClient, toCache] = res.body.tee()
     void persist(filePath, toCache)
-    const length = res.headers.get('content-length')
     return new Response(toClient, {
-      headers: { 'Content-Type': contentTypeFor(filePath), 'Cache-Control': 'no-store', ...(length ? { 'Content-Length': length } : {}) },
+      status: res.status,
+      statusText: res.statusText,
+      headers: proxyHeaders(filePath, res.headers),
     })
   }
 

packages/devframe/src/utils/serve-static.ts

@@ -1,13 +1,14 @@
 import type { EventHandler } from 'h3'
 import type { IncomingMessage, ServerResponse } from 'node:http'
 import type { ReadableStream as NodeWebReadableStream } from 'node:stream/web'
-import type { RemoteAssetsStore } from '../types/remote-assets'
+import type { RemoteAssetsErrorMessage, RemoteAssetsStore } from '../types/remote-assets'
 import { createReadStream } from 'node:fs'
 import { stat } from 'node:fs/promises'
 import { Readable } from 'node:stream'
 import { defineHandler, H3 } from 'h3'
 import { lookup } from 'mrmime'
 import { extname, join, normalize, resolve, sep } from 'pathe'
+import { DEVFRAME_REMOTE_ASSETS_ERROR_MESSAGE_TYPE } from '../constants'
 
 /**
  * What the static-serving engine accepts: a local directory, or a resolved
@@ -311,11 +312,20 @@ export function serveStaticNodeMiddleware(
 /**
  * Minimal, dependency-free HTML shown when a remote-assets request cannot
  * be satisfied (no installed package, no cache, provider unreachable).
+ *
+ * The page stands on its own when a devframe is opened directly, and
+ * announces itself over `postMessage` when it loads inside a viewer's iframe
+ * ({@link DEVFRAME_REMOTE_ASSETS_ERROR_MESSAGE_TYPE}) so the viewer can show
+ * the same failure in its own UI instead.
  */
 function remoteErrorPage(pkg: string, version: string, reason: string): string {
   const esc = (s: string): string => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
   const name = esc(pkg)
   const ver = esc(version)
+  const message: RemoteAssetsErrorMessage = { type: DEVFRAME_REMOTE_ASSETS_ERROR_MESSAGE_TYPE, package: pkg, version, reason }
+  // `</script>` inside the JSON would end the block early; `<` is the only
+  // character that can do that, and escaping it keeps the literal valid JS.
+  const payload = JSON.stringify(message).replace(/</g, '\\u003c')
   return `<!doctype html>
 <html lang="en">
 <head>
@@ -345,6 +355,10 @@ function remoteErrorPage(pkg: string, version: string, reason: string): string {
   <button onclick="location.reload()">Retry</button>
   <p class="muted">devframe remote assets</p>
 </main>
+<script>
+  if (window.parent !== window)
+    window.parent.postMessage(${payload}, '*')
+</script>
 </body>
 </html>
 `