@entrinsik/vite-plugin-informer 2.11.0 → 2.13.0

package/src/dev-dependencies.js

@@ -1,3 +1,4 @@
+import { isStreamRef } from './dev-streams.js';
 import { readFile, access } from 'node:fs/promises';
 import { join } from 'node:path';
 import crypto from 'node:crypto';
@@ -164,8 +165,8 @@ const METHOD_SURFACE = {
     query: ['execute'],
     datasource: ['query'],
     integration: ['request'],
-    app: ['request'],
-    pack: ['request']
+    app: ['request', 'url'],
+    pack: ['request', 'url']
 };
 
 // Cross-app request() method allow-list — mirrors REQUEST_METHODS in
@@ -387,7 +388,14 @@ export function resolveAppBinding(binding) {
  * @returns {Object} An object keyed by dependency name, values are typed
  *   proxies with methods matching the target's production method surface.
  */
-export function buildDevContext({ deps, apiFetch, devBindings = {}, appFetch = null }) {
+// The integration request route carries a base64 body of at most 50 MB
+// (integration/routes/request.js REQUEST_MAX_BYTES), so a staged stream the dev
+// proxy forwards through it can be at most this many raw bytes — a little less
+// in practice, since the envelope also carries url, headers and params. Pinned
+// to the server constant by test/streams-parity.test.js.
+export const DEV_FORWARD_MAX_BYTES = Math.floor(52428800 * 3 / 4);
+
+export function buildDevContext({ deps, apiFetch, devBindings = {}, appFetch = null, forwarding = null, serverOrigin = null }) {
     const context = {};
     for (const [name, decl] of Object.entries(deps || {})) {
         if (!decl || typeof decl !== 'object') continue;
@@ -395,11 +403,10 @@ export function buildDevContext({ deps, apiFetch, devBindings = {}, appFetch = n
         if (!VALID_TARGETS.has(target)) continue;
 
         // App and pack slots bind from the plugin's `devBindings` (a human
-        // `owner:slug` pointing request() at the target app). App slots fall
-        // back to the manifest `defaultBinding` UUID; pack slots have no
-        // fallback — the pin resolves via marketplace installs, which dev
-        // doesn't have, so the devBinding names the locally-installed app.
-        // request() is the only surface either way.
+        // `owner:slug` pointing request() and url() at the target app). App
+        // slots fall back to the manifest `defaultBinding` UUID; pack slots
+        // have no fallback — the pin resolves via marketplace installs, which
+        // dev doesn't have, so the devBinding names the locally-installed app.
         if (target === 'app' || target === 'pack') {
             const fallback = (target === 'app'
                 && typeof decl.defaultBinding === 'string' && UUID_PATTERN.test(decl.defaultBinding))
@@ -407,7 +414,7 @@ export function buildDevContext({ deps, apiFetch, devBindings = {}, appFetch = n
                 : null;
             const binding = devBindings[name] != null ? devBindings[name] : fallback;
             context[name] = binding
-                ? makeAppDevProxy({ name, binding, appFetch, kind: target })
+                ? makeAppDevProxy({ name, binding, appFetch, serverOrigin, kind: target })
                 : makeUnboundDevProxy({ name, target });
             continue;
         }
@@ -417,19 +424,38 @@ export function buildDevContext({ deps, apiFetch, devBindings = {}, appFetch = n
             : null;
 
         context[name] = targetId
-            ? makeDevProxy({ name, target, targetId, apiFetch })
+            ? makeDevProxy({ name, target, targetId, apiFetch, forwarding })
             : makeUnboundDevProxy({ name, target });
     }
     return context;
 }
 
 /**
- * Dev proxy for a `target: app` or `target: pack` slot. `request()` is the
- * only surface. Pack slots reuse this wholesale — in production the pack
- * driver resolves its marketplace pin and then delegates the runtime to the
- * app driver, and the devBinding IS that resolution done by hand. The prod
- * version gate (pack_dependency_out_of_range) is not emulated: dev has no
- * pack_install to read a version from.
+ * Append an app-relative path, query string, or fragment to a view URL, or
+ * null when the result would leave the view. Mirrors joinViewPath in
+ * informer-server's modules/app/lib/app-launch.js so dev refuses the same
+ * paths prod 400s; exported so test/streams-parity.test.js can hold the two
+ * copies to the same input table.
+ *
+ * Unguarded, as the server copy is: no `path` makes the parse throw, so the
+ * one thing that can is a malformed INFORMER_URL, and that deserves to read
+ * as the config error it is rather than as a claim about '..' segments.
+ */
+export function joinViewPath(viewUrl, path) {
+    if (!path) return viewUrl;
+    const joined = /^[?#]/.test(path) ? `${viewUrl}${path}` : `${viewUrl}/${path.replace(/^\/+/, '')}`;
+    const base = new URL(viewUrl, 'http://localhost').pathname;
+    const resolved = new URL(joined, 'http://localhost').pathname;
+    return resolved === base || resolved.startsWith(`${base}/`) ? joined : null;
+}
+
+/**
+ * Dev proxy for a `target: app` or `target: pack` slot, with prod's
+ * `request()` and `url()` surface. Pack slots reuse this wholesale — in
+ * production the pack driver resolves its marketplace pin and then delegates
+ * the runtime to the app driver, and the devBinding IS that resolution done
+ * by hand. The prod version gate (pack_dependency_out_of_range) is not
+ * emulated: dev has no pack_install to read a version from.
  *
  * Production runs `request()` through the target's own /view/_/ dispatch, and
  * dev injects into the same route:
@@ -444,16 +470,21 @@ export function buildDevContext({ deps, apiFetch, devBindings = {}, appFetch = n
  *       Non-JSON success responses follow the prod envelope contract: text/HTML
  *       returns a text envelope; binary is rejected (dev can't emulate it yet).
  *
+ *   url(path) -> <INFORMER_URL>/api/apps/<app>/view[/path | ?query | #fragment]
+ *       The target's view URL on the configured server, for a page to open.
+ *
  * @param {Object} args
  * @param {string} args.name - dependency slot name
  * @param {string|{app?: string}} args.binding - devBindings entry (or the
  *   manifest defaultBinding UUID). A bare string is shorthand for `{ app }`.
  * @param {Function|null} args.appFetch - token-authed fetch, or null when
  *   INFORMER_APP_TOKEN is unset.
+ * @param {string|null} [args.serverOrigin] - INFORMER_URL, the server url()
+ *   links point at.
  * @param {'app'|'pack'} [args.kind] - slot flavor, for error labels and the
  *   structured resourceType guest code branches on.
  */
-function makeAppDevProxy({ name, binding, appFetch, kind = 'app' }) {
+function makeAppDevProxy({ name, binding, appFetch, serverOrigin = null, kind = 'app' }) {
     const { app } = resolveAppBinding(binding);
 
     return {
@@ -514,11 +545,30 @@ function makeAppDevProxy({ name, binding, appFetch, kind = 'app' }) {
                 return { status, body, contentType: contentType || '', headers: { 'content-type': contentType || '' } };
             }
             return body;
+        },
+
+        async url(path) {
+            if (!app) {
+                throw new Error(
+                    `Dependency "${name}" (${kind}): dev url() needs the target app — set devBindings.${name}.app (e.g. 'admin:kanban')`
+                );
+            }
+            if (!serverOrigin) {
+                throw new Error(`Dependency "${name}" (${kind}): dev url() needs INFORMER_URL, the server its links point at`);
+            }
+            if (path !== undefined && path !== null && typeof path !== 'string') {
+                throw new Error(`Dependency "${name}" (${kind}): url(path) takes a string`);
+            }
+            const href = joinViewPath(`${serverOrigin}/api/apps/${encodeURIComponent(app)}/view`, path);
+            if (!href) {
+                throw new Error(`Dependency "${name}" (${kind}): url(path) must not escape the target app with ".." path segments`);
+            }
+            return href;
         }
     };
 }
 
-function makeDevProxy({ name, target, targetId, apiFetch }) {
+function makeDevProxy({ name, target, targetId, apiFetch, forwarding = null }) {
     switch (target) {
         case 'dataset':
             return {
@@ -544,7 +594,75 @@ function makeDevProxy({ name, target, targetId, apiFetch }) {
         case 'integration':
             return {
                 async request(payload) {
-                    return await devCall(apiFetch, 'POST', `integrations/${targetId}/request`, payload || {}, name, 'integration');
+                    const { data, form, into, ...rest } = payload || {};
+                    const wantsBody = isStreamRef(data, 'upload');
+                    const wantsForm = Boolean(form) && typeof form === 'object' && !Array.isArray(form);
+                    const wantsInto = into !== undefined && into !== null;
+                    // Ahead of the plain-call shortcut below: on its own a
+                    // download handle leaves every flag false, and falling
+                    // through would JSON-POST the handle to the third party as
+                    // the request body. Prod refuses it (app-stream-forwarding.js).
+                    if (isStreamRef(data, 'download')) {
+                        throw dependencyError('request(): only an upload handle can be sent as the body; a download is what a route produces, not what it forwards', 400, { dependencyName: name, resourceType: 'integration' });
+                    }
+                    if (!wantsBody && !wantsForm && !wantsInto) {
+                        return await devCall(apiFetch, 'POST', `integrations/${targetId}/request`, payload || {}, name, 'integration');
+                    }
+                    // Staged streams as bodies (I5-13030). Prod streams them
+                    // through the proxy; dev rides the route's base64 envelope
+                    // with the same request shape, so anything an author sees
+                    // here, deployed code sees too — except the envelope's cap.
+                    if (!forwarding) {
+                        throw dependencyError(`Dependency "${name}" (integration): staged streams are unavailable in this context`, 400, { dependencyName: name, resourceType: 'integration' });
+                    }
+                    if (wantsBody && wantsForm) {
+                        throw dependencyError('request(): use either `data` or `form` for the body, not both', 400, { dependencyName: name, resourceType: 'integration' });
+                    }
+                    // A `data` that is not a stream handle is the caller's own
+                    // body: keep it. Mirrors app-stream-forwarding.js — without
+                    // it, request({ data: { q }, into: dl }) sends nothing.
+                    let body = (!wantsBody && !wantsForm && data !== undefined) ? { ...rest, data } : rest;
+                    if (wantsForm && data !== undefined) {
+                        throw dependencyError('request(): use either `data` or `form` for the body, not both', 400, { dependencyName: name, resourceType: 'integration' });
+                    }
+                    if (wantsBody) {
+                        const upload = forwarding.body(data);
+                        assertForwardable(name, upload.size);
+                        // content-length describes bytes only this side counted;
+                        // content-type stays the caller's to relabel, as in prod.
+                        assertStreamOwnedHeaders(rest.headers, { 'content-length': upload.size }, name);
+                        body = { ...rest, data: upload.bytes.toString('base64'), encoding: 'base64', headers: withDefaultHeader(rest.headers, 'content-type', upload.contentType) };
+                    } else if (wantsForm) {
+                        const { bytes, contentType } = multipart(form, forwarding, name);
+                        assertForwardable(name, bytes.length);
+                        // The boundary is generated in multipart() and nowhere
+                        // else, so content-type is the stream's here; a caller's
+                        // `multipart/form-data` would drop it.
+                        assertStreamOwnedHeaders(rest.headers, { 'content-type': contentType, 'content-length': bytes.length }, name);
+                        body = { ...rest, data: bytes.toString('base64'), encoding: 'base64', headers: withDefaultHeader(rest.headers, 'content-type', contentType) };
+                    }
+                    if (!wantsInto) {
+                        return await devCall(apiFetch, 'POST', `integrations/${targetId}/request`, body, name, 'integration');
+                    }
+                    // `into` is claimed before the call, as prod does, so a bad
+                    // target fails without an upstream round trip — and is given
+                    // back on every path that does not deliver a body.
+                    const receiver = forwarding.receiver(into, rest.url);
+                    let answer;
+                    try {
+                        answer = await apiFetch(`integrations/${targetId}/request`, { method: 'POST', body, raw: true });
+                    } catch (err) {
+                        receiver.release();
+                        throw err;
+                    }
+                    const { status, bytes, headers, body: parsed } = answer;
+                    // Prod gates the fill on < 300 (request.js); a 3xx that axios
+                    // did not follow must not be sealed as the file here either.
+                    if (status >= 300) {
+                        receiver.release();
+                        throw dependencyCallError(name, 'integration', status, parsed);
+                    }
+                    return receiver.fill(bytes, headers);
                 }
             };
         default:
@@ -634,6 +752,66 @@ function isBinaryContentType(contentType) {
     return Boolean(ct) && !ct.startsWith('text/') && !ct.includes('json') && !ct.includes('event-stream');
 }
 
+function assertForwardable(name, size) {
+    if (size > DEV_FORWARD_MAX_BYTES) {
+        throw new Error(
+            `Dependency "${name}" (integration): the dev proxy forwards a staged stream through the request route's base64 envelope, which holds at most ${DEV_FORWARD_MAX_BYTES} bytes (this one is ${size}). A deployed app streams it without the cap — test files this size against a deployment.`
+        );
+    }
+}
+
+/**
+ * Refuse a caller-declared header that describes the staged stream, the way
+ * prod's applyStreamHeaders does (modules/integration/routes/request.js).
+ *
+ * Dev sends the body as a base64 envelope and never ships these names, so
+ * without the refusal an author learns a contract that 400s on deploy — or
+ * worse, ships a boundary-less multipart body no upstream can parse.
+ */
+function assertStreamOwnedHeaders(headers, owned, name) {
+    for (const [ownedName, value] of Object.entries(owned)) {
+        const declared = Object.keys(headers || {}).find(k => k.toLowerCase() === ownedName);
+        if (declared && String(headers[declared]) !== String(value)) {
+            throw dependencyError(
+                `request(): \`${declared}\` describes the staged stream and cannot be set by the caller (you sent "${headers[declared]}", the stream is "${value}")`,
+                400, { dependencyName: name, resourceType: 'integration' }
+            );
+        }
+    }
+}
+
+function withDefaultHeader(headers, name, value) {
+    const out = { ...(headers || {}) };
+    if (!Object.keys(out).some(k => k.toLowerCase() === name)) out[name] = value;
+    return out;
+}
+
+/** A multipart/form-data body built here — the plugin ships without form-data. */
+function multipart(form, forwarding, name) {
+    const boundary = `----InformerDevForm${Math.random().toString(16).slice(2)}${Date.now().toString(16)}`;
+    const parts = [];
+    for (const [field, value] of Object.entries(form)) {
+        if (value === undefined || value === null) continue;
+        if (isStreamRef(value, 'download')) {
+            throw dependencyError(`request(): form field "${field}" is a download handle; only uploads can be sent`, 400, { dependencyName: name, resourceType: 'integration' });
+        }
+        if (isStreamRef(value, 'upload')) {
+            const upload = forwarding.body(value);
+            // filenameSchema permits a double quote, which would close the
+            // disposition early and let a filename inject its own part headers.
+            // form-data escapes this for us in prod; here it is hand-rolled.
+            const filename = String(upload.filename || 'upload').replace(/["\r\n]/g, '_');
+            parts.push(Buffer.from(`--${boundary}\r\nContent-Disposition: form-data; name="${field}"; filename="${filename}"\r\nContent-Type: ${upload.contentType}\r\n\r\n`), upload.bytes, Buffer.from('\r\n'));
+        } else if (typeof value === 'object') {
+            parts.push(Buffer.from(`--${boundary}\r\nContent-Disposition: form-data; name="${field}"\r\nContent-Type: application/json\r\n\r\n${JSON.stringify(value)}\r\n`));
+        } else {
+            parts.push(Buffer.from(`--${boundary}\r\nContent-Disposition: form-data; name="${field}"\r\n\r\n${String(value)}\r\n`));
+        }
+    }
+    parts.push(Buffer.from(`--${boundary}--\r\n`));
+    return { bytes: Buffer.concat(parts), contentType: `multipart/form-data; boundary=${boundary}` };
+}
+
 async function devCall(apiFetch, method, path, body, depName, resourceType) {
     const opts = { method };
     if (body !== null && body !== undefined) opts.body = body;

package/src/dev-platform.js

@@ -3,13 +3,14 @@
  * the server injects on `window.__INFORMER__.platform` and on the server
  * handler / tool bag: the Informer build version and the capability flags.
  *
- * Every capability the dev server mirrors is on. `embeddings` is off: the
- * pump and query-time `embed()` need a real Informer, so an app that
- * feature-detects on it sees locally exactly what it sees on an install
- * without the feature. `version` is `'dev'` (not semver) so a floor check
- * treats the dev mirror as "unknown" rather than as any particular release.
- * `originMode` is on: the dev server behaves like an app served from its own
- * origin, where live channels work.
+ * Every capability the dev server mirrors is on. `embeddings` is off by
+ * default: the pump needs a real Informer, so an app that feature-detects on
+ * it sees locally exactly what it sees on an install without the feature.
+ * Turning it on binds query-time `embed()` to a deployed app's `_embed` route
+ * (see createDevEmbed); the pump itself is still not mirrored. `version` is
+ * `'dev'` (not semver) so a floor check treats the dev mirror as "unknown"
+ * rather than as any particular release. `originMode` is on: the dev server
+ * behaves like an app served from its own origin, where live channels work.
  *
  * Override any of it per project with `informer({ mock: { platform: {…} } })`.
  */
@@ -30,6 +31,8 @@ export const DEV_CAPABILITIES = Object.freeze({
     // live channels: broadcast() in the sandbox, the `channels:` relay block,
     // and channels/ join/leave handlers — the dev server mirrors all three.
     channels: true,
+    // channels/ files with config.actor: one live instance per channel (dev-channel-actors.js)
+    channelActors: true,
     embeddings: false
 });
 
@@ -42,3 +45,75 @@ export function devPlatform(overrides = {}) {
         capabilities: { ...DEV_CAPABILITIES, ...capabilities }
     };
 }
+
+/**
+ * Whatever the response carries by way of an explanation.
+ *
+ * fetchAs returns a parsed JSON body when it can and the raw text when it
+ * cannot (an auth-bounce HTML page, a proxy error page). Boom answers put the
+ * sentence on `message`; fetchAs's own invalid-path synthetic uses `error`.
+ * Reading only `message` drops both of the others and leaves the tautology
+ * `failed (502): HTTP 502` with the text that explained the failure thrown
+ * away.
+ */
+function failureReason(body, status) {
+    if (typeof body === 'string') return body.trim().slice(0, 200) || `HTTP ${status}`;
+    return (body && (body.message || body.error)) || `HTTP ${status}`;
+}
+
+/**
+ * The dev bag's `embed(name, text)`, shared by the server-routes and agent
+ * mirrors so the two cannot drift.
+ *
+ * Off by default: the same written explanation a real install gives an app
+ * type without the capability, so the dev failure reads as the deployed
+ * lesson instead of a bare "embed is not a function".
+ *
+ * Opted in — `informer({ mock: { platform: { capabilities: { embeddings: true } } } })`
+ * — it posts to the deployed app's `_embed` route on the configured server.
+ * That route runs the same host function a deployed handler's `embed()`
+ * runs, so the vector, the revision and the billing are the deployed ones.
+ * The corpus is not: `query()` still goes to the dev workspace datasource,
+ * which the pump never writes to, so a search route compares a deployed
+ * vector against local rows.
+ *
+ * It addresses the app by package.json `informer.id`. `informer-init`
+ * generates that id locally and the first deploy creates the app under it, so
+ * for a scaffolded project it is always set and the question is whether THIS
+ * server has ever had a deploy of it — a 404, answered below with what to do
+ * about it.
+ */
+export function createDevEmbed({ platform, apiFetch, appId }) {
+    if (!(platform && platform.capabilities && platform.capabilities.embeddings)) {
+        return async () => {
+            throw new Error('embed() is not available in the dev mirror: the embeddings capability needs a real Informer (platform.capabilities.embeddings is false)');
+        };
+    }
+    return async (name, text) => {
+        if (!appId) {
+            throw new Error('embed() in dev needs an app id to address: set informer.id in package.json (informer-init writes it) and deploy once');
+        }
+        const { status, body } = await apiFetch(`apps/${appId}/embeddings/${encodeURIComponent(String(name))}/_embed`, {
+            method: 'POST',
+            body: { text }
+        });
+
+        if (status === 404) {
+            throw new Error(`embed('${name}') failed (404): the configured server has no app ${appId} with an embeddings use case "${name}". Deploy this project there (npm run deploy) and declare the use case in embeddings/${name}.js.`);
+        }
+        if (status < 200 || status >= 300) {
+            throw new Error(`embed('${name}') failed (${status}): ${failureReason(body, status)}`);
+        }
+        // A 2xx is not yet an answer. globalThis.fetch FOLLOWS redirects, so
+        // an expired INFORMER_API_KEY or an SSO proxy in front of the server
+        // answers 200 with a sign-in page, and a 204 answers nothing at all.
+        // Returned as-is, `result.embedding` is undefined and the failure
+        // surfaces much later as a Postgres parameter-type error inside the
+        // app's own SQL — sending the developer to debug their query for what
+        // is an auth failure.
+        if (!body || !Array.isArray(body.embedding)) {
+            throw new Error(`embed('${name}') got ${status} but no embedding vector — the response did not come from the _embed route. An expired INFORMER_API_KEY or a sign-in proxy in front of the server both answer 200 with a page. Response: ${failureReason(body, status)}`);
+        }
+        return body;
+    };
+}