@entrinsik/vite-plugin-informer 2.11.0 → 2.13.0

package/src/dev-streams.js

@@ -1,5 +1,5 @@
 import { randomUUID } from 'node:crypto';
-import { extname } from 'node:path';
+import { extname, basename } from 'node:path';
 
 /**
  * Dev-mode app streams (I5-12979) — the local stand-in for the production
@@ -151,6 +151,47 @@ export function createStreamStore(limits = LIMITS) {
     return { create, get, bytes, remove, reserve, seal, sweep, touch, items, limits };
 }
 
+/**
+ * The staged streams of one type, oldest first (I5-13030). Dev has a single
+ * user, so the store IS their ledger — no per-user filter to apply.
+ */
+export function listStreams(store, type) {
+    store.sweep();
+    return [...store.items.values()].filter(item => item.type === type).sort((a, b) => a.createdAt - b.createdAt);
+}
+
+/** Where the dev origin serves a download: the same shape the bag's download.url takes. */
+export function downloadUrl(item, base = '') {
+    return `${base}/_downloads/${encodeURIComponent(item.id)}${item.filename ? `/${encodeURIComponent(item.filename)}` : ''}`;
+}
+
+/**
+ * MIRRORED from modules/app/lib/app-stream-forwarding.js (I5-13030) and pinned
+ * by the parity test: how a filled stream is named when the guest did not
+ * name it — the upstream's Content-Disposition, else the request path.
+ */
+export function filenameFromDisposition(header) {
+    if (typeof header !== 'string') return null;
+    const utf8 = /filename\*\s*=\s*(?:UTF-8|utf-8)''([^;]+)/.exec(header);
+    if (utf8) {
+        try { return decodeURIComponent(utf8[1].trim()); } catch { /* fall through to the plain form */ }
+    }
+    const plain = /filename\s*=\s*"?([^";]+)"?/.exec(header);
+    return plain ? plain[1].trim() : null;
+}
+
+export function filenameFor(headers, url) {
+    const named = filenameFromDisposition(headers && headers['content-disposition']);
+    if (named) return basename(named);
+    if (typeof url === 'string') {
+        try {
+            const last = basename(new URL(url, 'http://upstream.invalid').pathname);
+            if (last && last !== '/') return last;
+        } catch { /* not a URL we can name a file after */ }
+    }
+    return 'download';
+}
+
 /** Guest-facing handle: never the store item itself. */
 export function toHandle(item, extra = {}) {
     return {
@@ -402,35 +443,38 @@ export function createStreamServices({ store, query, base = '' }) {
         return { rowCount };
     }
 
+    /** A live upload handle — what uploads.get() and a filled `into: 'upload'` both hand out. */
+    function uploadHandle(item) {
+        return {
+            ...toHandle(item),
+            text: async (encoding) => {
+                if (encoding !== undefined && encoding !== null && !Buffer.isEncoding(encoding)) throw httpError(422, `Unknown text encoding "${encoding}"`);
+                return inline(item).toString(encoding || 'utf8');
+            },
+            json: async () => {
+                const text = inline(item).toString('utf8');
+                try {
+                    return JSON.parse(text);
+                } catch (err) {
+                    throw httpError(422, `Upload is not valid JSON: ${err.message}`);
+                }
+            },
+            base64: async () => inline(item).toString('base64'),
+            extractText: async () => { throw httpError(501, 'upload.extractText() is not available in dev — the platform text extractor runs on the Informer server; test it against a deployed app'); },
+            copyInto: async (table, opts) => await copyInto(item, table, opts || {}),
+            discard: async () => { store.remove(item.id); return true; }
+        };
+    }
+
     const uploads = {
         async get(id) {
-            const item = ownedUpload(id);
-            return {
-                ...toHandle(item),
-                text: async (encoding) => {
-                    if (encoding !== undefined && encoding !== null && !Buffer.isEncoding(encoding)) throw httpError(422, `Unknown text encoding "${encoding}"`);
-                    return inline(item).toString(encoding || 'utf8');
-                },
-                json: async () => {
-                    const text = inline(item).toString('utf8');
-                    try {
-                        return JSON.parse(text);
-                    } catch (err) {
-                        throw httpError(422, `Upload is not valid JSON: ${err.message}`);
-                    }
-                },
-                base64: async () => inline(item).toString('base64'),
-                extractText: async () => { throw httpError(501, 'upload.extractText() is not available in dev — the platform text extractor runs on the Informer server; test it against a deployed app'); },
-                copyInto: async (table, opts) => await copyInto(item, table, opts || {}),
-                discard: async () => { store.remove(item.id); return true; }
-            };
+            return uploadHandle(ownedUpload(id));
         }
     };
 
     function downloadHandle(item) {
-        const url = `${base}/_downloads/${encodeURIComponent(item.id)}${item.filename ? `/${encodeURIComponent(item.filename)}` : ''}`;
         const handle = {
-            ...toHandle(item, { url }),
+            ...toHandle(item, { url: downloadUrl(item, base) }),
             async write(chunk) {
                 writableDownload(item.id);
                 const buf = toBytes(chunk);
@@ -504,7 +548,93 @@ export function createStreamServices({ store, query, base = '' }) {
         }
     }
 
-    return { uploads, downloads, resolveQueryParams, endDownload, finalize };
+    /**
+     * Forwarding to an integration (I5-13030). Prod streams the bytes between
+     * the staging store and the upstream; the dev proxy reaches the real
+     * request route over HTTP with a JSON body, so here the bytes ride that
+     * route's base64 envelope instead — the same semantics, under the
+     * envelope's own cap (dev-dependencies.js names the gap when a file is
+     * over it). What the store does is identical: an outbound handle is read,
+     * an `into` target is claimed before the call and filled after it.
+     */
+    const forwarding = {
+        /** The bytes behind an owned, sealed upload reference, with what describes them. */
+        body(ref) {
+            const item = ownedUpload(ref.id);
+            return { bytes: store.bytes(item), contentType: item.contentType || 'application/octet-stream', filename: item.filename, size: item.size };
+        },
+        /**
+         * Claim an `into` target now — a download the guest created (unsealed,
+         * unwritten) or 'upload' for a fresh one — and return fill(), which
+         * lands the upstream body and seals it. Over the byte cap, fill() fails
+         * 413 and leaves a download empty and unsealed, a fresh upload gone.
+         */
+        receiver(target, url) {
+            if (target === 'upload') {
+                store.reserve(limits.maxUploadBytes);
+                const item = store.create('upload', { filename: null, contentType: null, size: 0, chunks: 0, reserved: limits.maxUploadBytes });
+                let settled = false;
+                return {
+                    // Prod's appStream.release: the upstream delivered no body,
+                    // so give the claim back rather than leaving an upload
+                    // nobody holds a handle to until the TTL.
+                    release() {
+                        if (settled) return;
+                        settled = true;
+                        store.remove(item.id);
+                    },
+                    fill(bytes, headers = {}) {
+                        settled = true;
+                        if (bytes.length > limits.maxUploadBytes) {
+                            store.remove(item.id);
+                            throw httpError(413, `The upstream body exceeds the ${limits.maxUploadBytes} byte limit`, { maxUploadBytes: limits.maxUploadBytes });
+                        }
+                        item.contentType = (headers['content-type'] || 'application/octet-stream').split(';')[0].trim();
+                        item.filename = filenameFor(headers, url);
+                        // An `into` fill is the append producer, which never sets
+                        // a chunk size — prod reports null, and so must the
+                        // listing below, not just the handle returned here.
+                        item.chunkSize = null;
+                        item.chunks = 1;
+                        item.chunkData.set(1, Buffer.from(bytes));
+                        item.size = bytes.length;
+                        item.complete = true;
+                        store.seal(item);
+                        // The same extra KEYS prod's handle carries for a filled
+                        // upload. Dev is one in-memory buffer, so chunks is always
+                        // 1 where prod reports the real append-producer count.
+                        return { ...uploadHandle(item), complete: true, chunks: 1, chunkSize: null };
+                    }
+                };
+            }
+            if (isStreamRef(target, 'download')) {
+                const item = writableDownload(target.id);
+                if (item.parts.length) throw httpError(409, 'Download already has bytes; `into` fills a download from empty and seals it');
+                return {
+                    // The guest still owns this one, so there is nothing to
+                    // reclaim — it stays empty and unsealed, as prod leaves it.
+                    release() {},
+                    fill(bytes, headers = {}) {
+                        if (bytes.length > limits.maxUploadBytes) {
+                            item.parts = [];
+                            item.size = 0;
+                            throw httpError(413, `The upstream body exceeds the ${limits.maxUploadBytes} byte limit`, { maxUploadBytes: limits.maxUploadBytes });
+                        }
+                        if (!item.contentType) item.contentType = (headers['content-type'] || 'application/octet-stream').split(';')[0].trim();
+                        if (!item.filename) item.filename = filenameFor(headers, url);
+                        item.parts = [Buffer.from(bytes)];
+                        item.size = bytes.length;
+                        pending.delete(item.id);
+                        store.seal(item);
+                        return { ...downloadHandle(item), complete: true };
+                    }
+                };
+            }
+            throw httpError(400, `request(): \`into\` must be a download handle or 'upload'`);
+        }
+    };
+
+    return { uploads, downloads, resolveQueryParams, endDownload, finalize, forwarding };
 }
 
 // What a guest hands write(): a string or bytes. Anything else is a 422 in
@@ -591,7 +721,7 @@ async function readBody(req) {
 
 function uploadSummary(item) {
     const { received, missing } = missingChunks(item);
-    return toHandle(item, { chunkSize: item.chunkSize, chunks: item.chunks, complete: item.complete, received, missing });
+    return toHandle(item, { chunkSize: Number(item.chunkSize) || null, chunks: item.chunks, complete: item.complete, received, missing });
 }
 
 /**
@@ -612,6 +742,11 @@ export function createUploadsMiddleware(store) {
                 res.setHeader('Location', `/_uploads/${item.id}`);
                 return sendJson(res, 201, uploadSummary(item));
             }
+            // GET /_uploads — what is staged (I5-13030). Dev has one user, so
+            // the store's uploads are all theirs, oldest first like prod.
+            if (parts.length === 0 && method === 'GET') {
+                return sendJson(res, 200, listStreams(store, 'upload').map(item => toHandle(item, { chunkSize: Number(item.chunkSize) || null, chunks: item.chunks, complete: item.complete })));
+            }
             if (parts.length === 0) return next();
 
             const item = store.get('upload', parts[0]);
@@ -639,14 +774,28 @@ export function createUploadsMiddleware(store) {
     };
 }
 
-/** Connect middleware for GET /_downloads/{id}/{filename?}?keep&inline. */
+/**
+ * Connect middleware for GET /_downloads/{id}/{filename?}?keep&inline, plus
+ * (I5-13030) GET /_downloads to list what is staged and DELETE /_downloads/{id}
+ * to drop one unserved.
+ */
 export function createDownloadsMiddleware(store) {
     return function downloadsMiddleware(req, res, next) {
         try {
-            if (req.method.toUpperCase() !== 'GET') return next();
+            const method = req.method.toUpperCase();
             const url = new URL(req.url, 'http://dev.local');
             const [id] = url.pathname.split('/').filter(Boolean);
+            if (!id && method === 'GET') {
+                return sendJson(res, 200, listStreams(store, 'download').map(item => toHandle(item, { complete: item.complete, url: downloadUrl(item) })));
+            }
             if (!id) return next();
+            if (method === 'DELETE') {
+                if (!store.get('download', id)) throw httpError(404, 'Not Found');
+                store.remove(id);
+                res.statusCode = 204;
+                return res.end();
+            }
+            if (method !== 'GET') return next();
             const item = store.get('download', id);
             if (!item || !item.complete) throw httpError(404, 'Not Found');
             return serveDownload(store, item, res, {

package/src/index.js

@@ -39,6 +39,36 @@ function buildMock(options) {
     };
 }
 
+/**
+ * The app id dev surfaces address on the server (the opt-in dev `embed()`
+ * posts to its `_embed` route). `informer-init` generates it locally into
+ * package.json `informer.id` and the first deploy creates the app under it.
+ * Absent, the surface says so at call time rather than the dev server
+ * refusing to start.
+ */
+function readAppId(projectRoot) {
+    const pkgPath = resolve(projectRoot, 'package.json');
+    let raw;
+    try {
+        raw = readFileSync(pkgPath, 'utf8');
+    } catch (err) {
+        // Unreadable is not the same as "no id set", and the two want
+        // different fixes. Saying which one it is beats telling someone to
+        // set a field in a file they are already looking at — or that the
+        // dev server never found.
+        if (err.code !== 'ENOENT') console.warn(`[informer] Could not read ${pkgPath}: ${err.message}`);
+        else console.warn(`[informer] No package.json at ${pkgPath}; dev surfaces that address the deployed app are unavailable.`);
+        return null;
+    }
+    try {
+        const pkg = JSON.parse(raw);
+        return (pkg.informer && pkg.informer.id) || null;
+    } catch (err) {
+        console.warn(`[informer] Could not parse ${pkgPath}: ${err.message}`);
+        return null;
+    }
+}
+
 /**
  * Occupied-spot check for the dev /api mount: does informer.yaml's
  * access.apis declare this method+path? Mirrors the server's matchWhitelist
@@ -103,8 +133,10 @@ async function writeAppDepTypes (projectRoot, dts) {
  * - Sets base to './' so built assets use relative paths
  *
  * @param {Object} [options]
- * @param {{ report?: object, theme?: 'light'|'dark', roles?: string[] }} [options.mock]
- *   window.__INFORMER__ mock injected in dev.
+ * @param {{ report?: object, theme?: 'light'|'dark', roles?: string[], user?: object, platform?: object }} [options.mock]
+ *   window.__INFORMER__ mock injected in dev. `platform` merges into the dev
+ *   descriptor, so `{ capabilities: { embeddings: true } }` opts one capability
+ *   in and leaves the rest. See InformerPluginOptions in index.d.ts.
  * @param {Object} [options.devBindings] - dev bindings for `target: app` and
  *   `target: pack` deps. App slots can't be defaultBound in the manifest; pack
  *   slots resolve their marketplace pin via installs dev doesn't have, so the
@@ -181,6 +213,15 @@ export default function informer(options = {}) {
             const projectRoot = process.cwd();
             const migrationsDir = resolve(projectRoot, 'migrations');
 
+            // One merged descriptor for the whole dev server. Built once
+            // rather than per consumer so "the channel hub, the handler bags
+            // and the browser all see the same mock" is structural — which is
+            // the property the embeddings opt-in depends on, since the flag
+            // the app reads and the flag that binds embed() must be the same
+            // flag. (transformIndexHtml is a separate hook and builds its own.)
+            const mock = buildMock(options);
+            const appId = readAppId(projectRoot);
+
             // One API client for the whole dev-server setup — createClient just
             // builds an auth header (no I/O), so it's hoisted out of the two
             // branches that each used to rebuild an identical one.
@@ -279,7 +320,7 @@ export default function informer(options = {}) {
             // Every page receives every frame; the subscribe loop mounted below
             // (join / joined / leave / send against channels/ files) is what
             // tells a page which channels it may dispatch.
-            const channels = createDevChannels({ appId: buildMock(options).report.id });
+            const channels = createDevChannels({ appId: mock.report.id });
             channels.emitter.on(BROADCAST_EVENT, (frame) => {
                 server.ws.send({ type: 'custom', event: DEV_CHANNEL_EVENT, data: frame });
             });
@@ -291,8 +332,10 @@ export default function informer(options = {}) {
                 devBindings: options.devBindings || {},
                 appToken,
                 channels,
-                user: buildMock(options).user,
-                roles: (options.mock && options.mock.roles) || []
+                user: mock.user,
+                roles: (options.mock && options.mock.roles) || [],
+                platform: mock.platform,
+                appId
             }));
 
             // Generate .d.ts types for bound `target: app` / `target: pack`
@@ -368,6 +411,11 @@ export default function informer(options = {}) {
             server.middlewares.use('/_uploads', createUploadsMiddleware(streamStore));
             server.middlewares.use('/_downloads', createDownloadsMiddleware(streamStore));
 
+            // The merged platform descriptor (dev defaults + mock.platform) is
+            // what the handler bags see too, not only the browser: an app that
+            // opts into `embeddings` there must find embed() bound, not throwing.
+            const platform = mock.platform;
+
             // Mount server-side route handlers if a server/ directory exists
             const serverDir = resolve(projectRoot, 'server');
 
@@ -378,7 +426,7 @@ export default function informer(options = {}) {
                     devWorkspaceId,
                     projectRoot,
                     roles: (options.mock && options.mock.roles) || [],
-                    user: buildMock(options).user,
+                    user: mock.user,
                     // Dev-only bindings for `target: app` / `target: pack`
                     // slots (app: overrides the manifest defaultBinding; pack:
                     // names the locally-installed pack app). Shape:
@@ -386,7 +434,9 @@ export default function informer(options = {}) {
                     devBindings: options.devBindings || {},
                     appToken,
                     channels,
-                    streamStore
+                    streamStore,
+                    platform,
+                    appId
                 });
                 server.middlewares.use('/api/_server', serverRoutes);
                 // Occupied-spot precedence (App API v2, matches production
@@ -418,7 +468,9 @@ export default function informer(options = {}) {
                     projectRoot,
                     devBindings: options.devBindings || {},
                     appToken,
-                    channels
+                    channels,
+                    platform,
+                    appId
                 });
                 server.middlewares.use('/api/_agent', agentDev);
             }
@@ -446,6 +498,7 @@ export default function informer(options = {}) {
     var __streams = ${streamsClientSource()};
     window.__INFORMER__.upload = __streams.upload;
     window.__INFORMER__.downloadUrl = __streams.downloadUrl;
+    window.__INFORMER__.streams = __streams.streams;
 })();
 </script>
 ${renderDevChannelScript({ hub: Boolean(serverOrigin) })}`;

package/src/openapi-to-dts.js

@@ -109,6 +109,10 @@ function slotInterface (iface, spec) {
     return [
         `export interface ${iface} {`,
         overloads.join('\n'),
+        `    /** Link into the target app's UI: its view root, or a path, query or`,
+        `     *  fragment under it. Absolute wherever the deployment names an`,
+        `     *  external address — always, when apps serve from their own origins. */`,
+        '    url(path?: string): Promise<string>;',
         '}'
     ].join('\n');
 }

package/src/server-routes.js

@@ -3,6 +3,7 @@ import { join } from 'node:path';
 import { parse as parseUrl } from 'node:url';
 import { createDevBagBuilder, buildDevUser } from './dev-bag.js';
 import { createDevChannels } from './dev-channels.js';
+import { devPlatform } from './dev-platform.js';
 import { createStreamStore, createStreamServices, isStreamRef, serveDownload as serveDevDownload } from './dev-streams.js';
 
 const VALID_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'];
@@ -163,8 +164,8 @@ async function walkJsFiles(dir, basePath) {
  * descriptor (mirrors app-sandbox.js buildInvokeScript / respondCallback).
  * The encoding allow-list and contract checks are enforced inside the ivm in
  * production; replicated here so handlers see the same errors in dev (where
- * there's no isolate to attribute the throw to). If you change this, mirror
- * it in modules/app/routes/view-api.js.
+ * there's no isolate to attribute the throw to). The header rule is shared
+ * with prod's modules/app/lib/handler-headers.js — change both.
  */
 function sendDescriptor(res, result) {
     const encoding = typeof result.encoding === 'string' ? result.encoding : null;
@@ -176,28 +177,38 @@ function sendDescriptor(res, result) {
     }
     const responseBody = result.body !== undefined ? result.body : null;
 
+    // Validate before writing anything: prod rejects a malformed body while
+    // building the response, so nothing of the handler's reaches the client. Left
+    // below the header loop, a 500 here still carried the handler's
+    // Content-Disposition and the browser saved a .pdf full of JSON.
+    if (encoding === 'base64' && !isBase64(responseBody)) {
+        throw new Error('Handler returned malformed base64 body');
+    }
+
     res.statusCode = result.status || 200;
+    // Lowercased for wire parity with Hapi. Node's header lookup is
+    // case-insensitive either way, which is why dev never reproduced I5-12972.
     for (const [key, value] of Object.entries(result.headers || {})) {
-        res.setHeader(key, value);
+        res.setHeader(key.toLowerCase(), value);
+    }
+
+    // Same rule as prod's applyHandlerHeaders, and applied before the body is
+    // branched on so it covers base64 too. Dev used to leave a binary response
+    // unlabelled, which the browser sniffed happily while prod shipped it as
+    // application/json — the I5-12972 failure, arrived at from the other side.
+    const declaredType = res.getHeader('content-type');
+    if (typeof declaredType !== 'string' || !declaredType.trim()) {
+        res.setHeader('content-type', 'application/json');
     }
 
     if (responseBody === null) {
         res.end();
     } else if (encoding === 'base64') {
-        if (!isBase64(responseBody)) {
-            throw new Error('Handler returned malformed base64 body');
-        }
         res.end(Buffer.from(responseBody, 'base64'));
     } else if (typeof responseBody === 'string') {
         // Strings go out verbatim, as prod passes them.
-        if (!res.getHeader('content-type')) {
-            res.setHeader('Content-Type', 'application/json');
-        }
         res.end(responseBody);
     } else {
-        if (!res.getHeader('content-type')) {
-            res.setHeader('Content-Type', 'application/json');
-        }
         res.end(JSON.stringify(responseBody));
     }
 }
@@ -224,13 +235,13 @@ function isDescriptor(value) {
  *   and /_downloads middleware (createStreamStore()); a private one when omitted
  * @returns {Function} Connect middleware
  */
-export function createMiddleware(viteServer, { serverOrigin, authHeader, devWorkspaceId, projectRoot, roles, user, devBindings, appToken, channels = createDevChannels(), streamStore }) {
+export function createMiddleware(viteServer, { serverOrigin, authHeader, devWorkspaceId, projectRoot, roles, user, devBindings, appToken, channels = createDevChannels(), streamStore, platform = devPlatform(), appId = null }) {
     // `@user/${request.user.username}` on the server names the channel the
     // page subscribes to.
     const devUser = buildDevUser(user);
     const serverDir = join(projectRoot, 'server');
     const streams = streamStore || createStreamStore();
-    const bagBuilder = createDevBagBuilder({ serverOrigin, authHeader, devWorkspaceId, projectRoot, devBindings, appToken, channels, logPrefix: '[app]' });
+    const bagBuilder = createDevBagBuilder({ serverOrigin, authHeader, devWorkspaceId, projectRoot, devBindings, appToken, channels, logPrefix: '[app]', platform, appId });
     const { query } = bagBuilder;
 
     return async function serverRoutesMiddleware(req, res, next) {
@@ -333,7 +344,7 @@ export function createMiddleware(viteServer, { serverOrigin, authHeader, devWork
                 res.end(JSON.stringify(earlyBody));
             }
 
-            const { bag } = await bagBuilder.build();
+            const { bag } = await bagBuilder.build({ forwarding: streamServices.forwarding });
 
             // Call handler — bag mirrors the prod sandbox (see app-sandbox.js).
             const result = await handler({ ...bag, request, query: streamQuery, respond, uploads: streamServices.uploads, downloads: streamServices.downloads });