@entrinsik/vite-plugin-informer 2.10.0 → 2.12.0

package/src/server-routes.js

@@ -1,25 +1,13 @@
 import { readdir, stat } from 'node:fs/promises';
-import { join, relative, posix } from 'node:path';
+import { join } from 'node:path';
 import { parse as parseUrl } from 'node:url';
-import { loadManifest, manifestBlock, buildDevContext, buildDevCrypto, buildDevMessaging, normalizeFetchPath } from './dev-dependencies.js';
-import { createDevChannels, createDevEmit } from './dev-channels.js';
+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';
 
-// embed() is present on a real install even without the embeddings
-// capability, where it throws a written explanation. Mirroring that here
-// keeps the dev failure the same lesson as the deployed one, instead of a
-// bare "embed is not a function" that reads like a missing binding.
-const embed = async () => {
-    throw new Error('embed() is not available in the dev mirror: the embeddings capability needs a real Informer (platform.capabilities.embeddings is false)');
-};
-
 const VALID_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'];
 
-// Cap dev proxy calls at 30s so a hung upstream fails loudly instead of
-// hanging the handler.
-const FETCH_TIMEOUT_MS = 30000;
-
 // Strict base64 — see view-api.js for the rationale. Mirror kept identical to
 // keep dev and prod behavior aligned, down to the scan: the quantified
 // /^[A-Za-z0-9+/]+={0,2}$/ throws "RangeError: Maximum call stack size
@@ -37,17 +25,19 @@ function isBase64(s) {
 }
 
 /**
- * Convert a file path under server/ to a route path.
+ * Convert a file path under a handler directory to a route path (mirrors the
+ * server's route-scanner.js filePathToRoute).
  *
  * Examples:
- *   server/orders/index.js     -> /orders
- *   server/orders/[id].js      -> /orders/:id
+ *   server/orders/index.js        -> /orders
+ *   server/orders/[id].js         -> /orders/:id
  *   server/orders/[id]/approve.js -> /orders/:id/approve
- *   server/index.js            -> /
+ *   server/index.js               -> /
+ *   channels/rooms/[room].js      -> /rooms/:room   (dirPrefix 'channels')
  */
-function filePathToRoute(filePath) {
+function filePathToRoute(filePath, dirPrefix = 'server') {
     let route = filePath
-        .replace(/^server\//, '')
+        .replace(new RegExp(`^${dirPrefix}/`), '')
         .replace(/\.js$/, '');
 
     route = route.replace(/\[([^\]]+)\]/g, ':$1');
@@ -143,7 +133,7 @@ async function scanRoutes(serverDir) {
     }));
 }
 
-export { filePathToRoute, walkJsFiles };
+export { filePathToRoute, matchRoute, walkJsFiles };
 
 async function walkJsFiles(dir, basePath) {
     const results = [];
@@ -169,6 +159,54 @@ async function walkJsFiles(dir, basePath) {
     return results;
 }
 
+/**
+ * Write a handler's `{ status, headers?, body?, encoding? }` response
+ * 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.
+ */
+function sendDescriptor(res, result) {
+    const encoding = typeof result.encoding === 'string' ? result.encoding : null;
+    if (encoding !== null && encoding !== 'base64') {
+        throw new Error(`Unknown response encoding: ${JSON.stringify(encoding)} (expected 'base64' or omitted)`);
+    }
+    if (encoding === 'base64' && typeof result.body !== 'string') {
+        throw new Error(`encoding: 'base64' requires body to be a base64-encoded string, got ${typeof result.body}`);
+    }
+    const responseBody = result.body !== undefined ? result.body : null;
+
+    res.statusCode = result.status || 200;
+    for (const [key, value] of Object.entries(result.headers || {})) {
+        res.setHeader(key, value);
+    }
+
+    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));
+    }
+}
+
+function isDescriptor(value) {
+    return value !== null && typeof value === 'object' && typeof value.status === 'number';
+}
+
 /**
  * Create Connect middleware for dev-mode server route execution.
  *
@@ -187,100 +225,14 @@ async function walkJsFiles(dir, basePath) {
  *   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 }) {
-    // The viewer identity dev handlers see — the same object the page gets as
-    // window.__INFORMER__.user, so `@user/${request.user.username}` on the
-    // server names the channel the page subscribes to.
-    const devUser = {
-        username: (user && user.username) || 'dev',
-        displayName: (user && user.displayName) || 'Local Developer',
-        email: (user && user.email) || null,
-        timezone: (user && user.timezone) || null
-    };
+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();
-
-    // query() implementation — proxies to the workspace _sql endpoint
-    async function query(sql, params) {
-        if (!devWorkspaceId) {
-            throw new Error('query() requires INFORMER_DEV_WORKSPACE. Run: npx informer-workspace init');
-        }
-
-        const resp = await globalThis.fetch(`${serverOrigin}/api/datasources/${devWorkspaceId}/_sql`, {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json', Authorization: authHeader },
-            body: JSON.stringify({ sql, params: params || [] })
-        });
-
-        if (!resp.ok) {
-            const err = await resp.json().catch(() => ({}));
-            const detail = err.message || resp.statusText;
-            throw new Error(`query() failed: ${resp.status} ${detail} (${serverOrigin}/api/datasources/${devWorkspaceId}/_sql)`);
-        }
-
-        const data = await resp.json();
-        return data.rows;
-    }
-
-    // fetch() implementation — proxies API calls to the Informer server
-    async function fetchAs(auth, path, opts = {}) {
-        const method = (opts.method || 'GET').toUpperCase();
-        // Same strict canonicalization as prod (app-sandbox.js normalizeFetchPath);
-        // reject non-canonical shapes here instead of silently accepting them.
-        const apiPath = normalizeFetchPath(path);
-        if (!apiPath) {
-            return { status: 400, body: { error: `Invalid fetch path: ${String(path).slice(0, 80)}` }, contentType: 'application/json' };
-        }
-        const url = `${serverOrigin}${apiPath}`;
-        const fetchOpts = {
-            method,
-            headers: { Authorization: auth, 'Content-Type': 'application/json', ...(opts.headers || {}) }
-        };
-
-        if (opts.body && ['POST', 'PUT', 'PATCH', 'DELETE'].includes(method)) {
-            fetchOpts.body = JSON.stringify(opts.body);
-        }
-
-        // Read the stream exactly once — `.json()` consumes/locks the body, so a
-        // `.text()` fallback would throw "Body is unusable" on any non-JSON
-        // response (auth-bounce HTML, proxy error page). Parse in memory
-        // instead — same as prod's unwrapInject.
-        let status, contentType, text;
-        try {
-            const resp = await globalThis.fetch(url, { ...fetchOpts, signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
-            status = resp.status;
-            contentType = resp.headers.get('content-type') || '';
-            text = await resp.text();
-        } catch (err) {
-            // Transport failure or timeout — fetch throws (TypeError 'fetch failed'
-            // with the real reason on err.cause, or a TimeoutError). Return a
-            // synthetic 502 so the dependency layer names it (dep + url + cause)
-            // rather than a bare unhandled "fetch failed".
-            const reason = (err.cause && err.cause.message) || err.message;
-            return { status: 502, body: { message: `fetch to ${url} failed: ${reason}` }, contentType: 'application/json' };
-        }
-        let body;
-        try { body = JSON.parse(text); } catch { body = text; }
-        return { status, body, contentType };
-    }
-
-    async function apiFetch(path, opts = {}) {
-        return await fetchAs(authHeader, path, opts);
-    }
-
-    // Cross-app request() targets /api/apps/<id>/view/_/<path>, whose auth accepts
-    // only the token/session strategies — NOT basic auth. In API-key mode the
-    // INFORMER_API_KEY Bearer already satisfies that, so reuse it; under basic
-    // auth a separate API token (INFORMER_APP_TOKEN) is required, and without one
-    // the app proxy's request() throws a pointed error instead of a bare 401.
-    // appFetch also stamps x-informer-app-depth:1 so the target runs one hop deep
-    // and enforces the same one-hop guard it does in production.
-    const appAuth = appToken
-        ? `Bearer ${appToken}`
-        : (authHeader && authHeader.startsWith('Bearer ') ? authHeader : null);
-    const appFetch = appAuth
-        ? async (path, opts = {}) => await fetchAs(appAuth, path, { ...opts, headers: { ...(opts.headers || {}), 'x-informer-app-depth': '1' } })
-        : null;
+    const bagBuilder = createDevBagBuilder({ serverOrigin, authHeader, devWorkspaceId, projectRoot, devBindings, appToken, channels, logPrefix: '[app]', platform, appId });
+    const { query } = bagBuilder;
 
     return async function serverRoutesMiddleware(req, res, next) {
         try {
@@ -325,34 +277,6 @@ export function createMiddleware(viteServer, { serverOrigin, authHeader, devWork
                 try { body = JSON.parse(rawBody); } catch { body = rawBody; }
             }
 
-            // crypto helper — mirrors the prod sandbox crypto surface
-            const cryptoHelper = buildDevCrypto();
-
-            // log helper — mirrors sandbox log(message, data) + log.info/warn/error/debug
-            const logCall = (level, message, data) => {
-                const msg = typeof message === 'string' ? message : JSON.stringify(message);
-                const args = [`[app-log] [${level}] ${msg}`];
-                if (data) args.push(data);
-                console.log(...args);
-            };
-            const log = Object.assign(
-                (message, data) => logCall('info', message, data),
-                {
-                    debug: (message, data) => logCall('debug', message, data),
-                    info: (message, data) => logCall('info', message, data),
-                    warn: (message, data) => logCall('warn', message, data),
-                    error: (message, data) => logCall('error', message, data)
-                }
-            );
-
-            // markdown helper — passthrough in dev (production uses `marked`)
-            const markdown = (text) => text;
-
-            // notify/email — delivery is a console-logged no-op in dev, but the
-            // required-field validation mirrors prod so an app that passes here
-            // won't 500 in production.
-            const { notify, email } = buildDevMessaging('[app]');
-
             // Build request context
             const request = {
                 method: req.method.toUpperCase(),
@@ -387,8 +311,11 @@ export function createMiddleware(viteServer, { serverOrigin, authHeader, devWork
                 serveDevDownload(streams, item, res);
             }
 
-            // respond() — sends early response, handler continues in background.
-            // respond(download) streams the staged bytes instead of JSON.
+            // respond() — sends the early response, the handler continues in
+            // the background. A `{ status, headers?, body?, encoding? }`
+            // descriptor is honored as such (app-sandbox.js respondCallback);
+            // anything else is wrapped as 200 JSON; a download handle streams
+            // the staged bytes.
             let responded = false;
             async function respond(earlyBody) {
                 if (responded) return;
@@ -401,29 +328,16 @@ export function createMiddleware(viteServer, { serverOrigin, authHeader, devWork
                     return serveDownloadHandle(earlyBody);
                 }
                 responded = true;
+                if (isDescriptor(earlyBody)) return sendDescriptor(res, earlyBody);
                 res.statusCode = 200;
                 res.setHeader('Content-Type', 'application/json');
                 res.end(JSON.stringify(earlyBody));
             }
 
-            // Build the dependency-injection context the same way the prod
-            // sandbox does, so handlers using `await context.myDep.method(...)`
-            // work locally. The manifest is parsed once per request (deps, env
-            // and channels all come from that one read) so edits to
-            // informer.yaml take effect without a dev-server restart.
-            const manifest = await loadManifest(projectRoot);
-            const deps = manifestBlock(manifest, 'dependencies');
-            const context = buildDevContext({ deps, apiFetch, devBindings, appFetch });
-            const env = manifestBlock(manifest, 'env');
-
-            // emit() writes no app_event row in dev, but still relays a listed
-            // event to its `channels:` channel; broadcast() publishes a live
-            // frame to the page (see dev-channels.js).
-            const emit = createDevEmit({ channels, manifestChannels: manifestBlock(manifest, 'channels'), logPrefix: '[app-event]' });
-            const { broadcast } = channels;
+            const { bag } = await bagBuilder.build({ forwarding: streamServices.forwarding });
 
             // Call handler — bag mirrors the prod sandbox (see app-sandbox.js).
-            const result = await handler({ request, context, query: streamQuery, fetch: apiFetch, respond, emit, broadcast, notify, email, embed, crypto: cryptoHelper, markdown, uploads: streamServices.uploads, downloads: streamServices.downloads, log, env, platform: devPlatform() });
+            const result = await handler({ ...bag, request, query: streamQuery, respond, uploads: streamServices.uploads, downloads: streamServices.downloads });
 
             // Seal any download the handler left open (prod finalizes the same way).
             await streamServices.finalize();
@@ -434,60 +348,14 @@ export function createMiddleware(viteServer, { serverOrigin, authHeader, devWork
             // A returned download handle streams as the response.
             if (isStreamRef(result, 'download')) return serveDownloadHandle(result);
 
-            // Normalize response (mirrors app-sandbox.js buildInvokeScript logic).
-            // The encoding allow-list and contract checks are enforced inside the
-            // ivm in production; replicate them 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.
-            let status, responseBody, responseHeaders, encoding;
-
+            // Normalize the return value (mirrors app-sandbox.js buildInvokeScript).
             if (result === undefined || result === null) {
-                status = 204;
-                responseBody = null;
-                responseHeaders = {};
-            } else if (typeof result === 'object' && typeof result.status === 'number') {
-                encoding = typeof result.encoding === 'string' ? result.encoding : null;
-                if (encoding !== null && encoding !== 'base64') {
-                    throw new Error(`Unknown response encoding: ${JSON.stringify(encoding)} (expected 'base64' or omitted)`);
-                }
-                if (encoding === 'base64' && typeof result.body !== 'string') {
-                    throw new Error(`encoding: 'base64' requires body to be a base64-encoded string, got ${typeof result.body}`);
-                }
-                status = result.status || 200;
-                responseBody = result.body !== undefined ? result.body : null;
-                responseHeaders = result.headers || {};
-            } else {
-                status = 200;
-                responseBody = result;
-                responseHeaders = { 'content-type': 'application/json' };
-            }
-
-            res.statusCode = status;
-            for (const [key, value] of Object.entries(responseHeaders)) {
-                res.setHeader(key, value);
-            }
-
-            if (responseBody === null) {
+                res.statusCode = 204;
                 res.end();
-            } else if (encoding === 'base64' && typeof responseBody === 'string') {
-                if (!isBase64(responseBody)) {
-                    throw new Error('Handler returned malformed base64 body');
-                }
-                res.end(Buffer.from(responseBody, 'base64'));
-            } else if (typeof responseBody === 'string') {
-                // Pre-PR the dev middleware always JSON.stringify'd the body, so
-                // a handler returning { body: 'hello' } emitted "hello" (with
-                // quotes) — diverging from prod which passed strings verbatim.
-                // This branch fixes that parity.
-                if (!res.getHeader('content-type')) {
-                    res.setHeader('Content-Type', 'application/json');
-                }
-                res.end(responseBody);
+            } else if (isDescriptor(result)) {
+                sendDescriptor(res, result);
             } else {
-                if (!res.getHeader('content-type')) {
-                    res.setHeader('Content-Type', 'application/json');
-                }
-                res.end(JSON.stringify(responseBody));
+                sendDescriptor(res, { status: 200, headers: { 'content-type': 'application/json' }, body: result });
             }
         } catch (err) {
             viteServer.ssrFixStacktrace(err);

package/src/streams-client.js

@@ -1,6 +1,8 @@
 /**
  * Dev copy of the injected app streams client (I5-12979):
- * `__INFORMER__.upload(file, opts)` and `__INFORMER__.downloadUrl(id, filename)`.
+ * `__INFORMER__.upload(file, opts)`, `__INFORMER__.downloadUrl(id, filename)` and
+ * `__INFORMER__.streams` (I5-13030: status / list / discard, plus upload()'s onEvent
+ * and task.created).
  *
  * VERBATIM copy of modules/app/routes/lib/html-utils.js#generateStreamsHelper
  * in its origin-mode form (base "", plain window.fetch / XHR transport — the
@@ -11,7 +13,7 @@
  * that test says exactly what to paste here. The dev page must upload the way
  * a deployed one does.
  *
- * @returns {string} JavaScript expression evaluating to { upload, downloadUrl }
+ * @returns {string} JavaScript expression evaluating to { upload, downloadUrl, streams }
  */
 export function streamsClientSource() {
     return `(function (base, transport) {
@@ -80,6 +82,24 @@ export function streamsClientSource() {
             return [opts.filename || file.name || '', file.size, file.lastModified || 0].join(':');
         }
 
+        // The transfer's event stream for the page (I5-13030): what the helper
+        // already knows at each step, handed out rather than inferred from a
+        // percentage. A listener's own throw must not fail the transfer it is
+        // watching, so it is rethrown on a fresh tick — still reaching
+        // window.onerror and the console, but not the chunk promise chain.
+        function notify (opts, event) {
+            if (typeof opts.onEvent !== 'function') return;
+            try {
+                opts.onEvent(event);
+            } catch (err) {
+                // Say so where it happened: the deferred rethrow below reaches
+                // window.onerror and nothing else, by which point the event it
+                // came from is long gone.
+                try { console.error('[informer] upload onEvent listener threw for ' + event.type + '; the transfer continues', err); } catch (e) {}
+                setTimeout(function () { throw err; }, 0);
+            }
+        }
+
         function upload (file, opts) {
             opts = opts || {};
             if (!file || typeof file.slice !== 'function' || typeof file.size !== 'number') {
@@ -97,6 +117,20 @@ export function streamsClientSource() {
             var task = { id: opts.resume || null, abort: function () { controller.abort(); } };
             var loaded = {};
 
+            // Settles with the upload's geometry the moment the store has reserved
+            // it — before a chunk moves — or with the create-time refusal (a 413
+            // over the cap, a resume that does not match). Nobody has to await
+            // it: a create failure still surfaces on the task itself.
+            var settleCreated;
+            var createdSettled = false;
+            task.created = new Promise(function (resolve, reject) {
+                // failed is its own argument rather than inferred from err:
+                // code that throws a falsy value would otherwise settle this
+                // as a resolve(undefined) — a failure read as success.
+                settleCreated = function (failed, err, value) { createdSettled = true; if (failed) reject(err); else resolve(value); };
+            });
+            task.created.catch(function () {});
+
             function progress () {
                 if (typeof opts.onProgress !== 'function') return;
                 var sum = 0;
@@ -105,16 +139,24 @@ export function streamsClientSource() {
             }
             function abortError () { var err = new Error('Upload aborted'); err.code = 'aborted'; return err; }
 
+            // 'attempt' is 1-based in events: the first try is attempt 1, and a
+            // 'retry' names the attempt that just failed.
             function sendChunk (meta, n, attempt) {
                 if (signal.aborted) return Promise.reject(abortError());
                 var start = (n - 1) * meta.chunkSize;
                 var blob = file.slice(start, Math.min(file.size, start + meta.chunkSize));
+                notify(opts, { type: 'chunk', n: n, state: 'sent', attempt: attempt + 1 });
                 return putChunk(base + '/_uploads/' + meta.id + '/' + n, blob, signal, function (sent) { loaded[n] = sent; progress(); })
-                    .then(function () { loaded[n] = blob.size; progress(); })
+                    .then(function () {
+                        loaded[n] = blob.size;
+                        progress();
+                        notify(opts, { type: 'chunk', n: n, state: 'landed', attempt: attempt + 1 });
+                    })
                     .catch(function (err) {
                         if (err.code === 'aborted' || signal.aborted) throw err;
                         if (err.status === 404) { var gone = new Error('Upload expired before it completed'); gone.code = 'upload_expired'; gone.status = 404; throw gone; }
                         if (!retryable(err.status) || attempt >= retries) throw err;
+                        notify(opts, { type: 'chunk', n: n, state: 'retry', attempt: attempt + 1, status: err.status });
                         return delay(backoff(attempt)).then(function () { return sendChunk(meta, n, attempt + 1); });
                     });
             }
@@ -131,6 +173,24 @@ export function streamsClientSource() {
                 return Promise.all(workers);
             }
 
+            // Seal. A 412 means the store is missing chunks a PUT reported as
+            // landed (a proxy that answered before the bytes were durable, an
+            // expiry racing the last write): send exactly those once more and
+            // seal again. The server names at most 50 (app-streams.js
+            // completeUpload), so a gap wider than that cannot be closed this
+            // way — a second 412 is a failure the caller resumes from.
+            function seal (meta, resent) {
+                return json('POST', base + '/_uploads/' + meta.id + '/_complete').catch(function (err) {
+                    var missing = err.status === 412 && err.data && err.data.missing;
+                    if (resent || !missing || !missing.length) throw err;
+                    for (var i = 0; i < missing.length; i++) notify(opts, { type: 'chunk', n: missing[i], state: 'resend' });
+                    return sendAll(meta, missing).then(function () {
+                        if (signal.aborted) throw abortError();
+                        return seal(meta, true);
+                    });
+                });
+            }
+
             var plan = signal.aborted ? Promise.reject(abortError()) : opts.resume
                 ? json('GET', base + '/_uploads/' + encodeURIComponent(opts.resume)).then(function (meta) {
                     // Size alone is not identity: two same-length files would be
@@ -159,26 +219,45 @@ export function streamsClientSource() {
             var promise = plan
                 .then(function (p) {
                     task.id = p.meta.id;
+                    var created = {
+                        id: p.meta.id,
+                        size: p.meta.size,
+                        chunks: p.meta.chunks,
+                        chunkSize: p.meta.chunkSize,
+                        resumed: !!opts.resume,
+                        // Chunks a resumed upload already holds; empty for a new one.
+                        received: opts.resume ? (p.meta.received || []) : []
+                    };
+                    settleCreated(false, null, created);
+                    notify(opts, { type: 'created', id: created.id, size: created.size, chunks: created.chunks, chunkSize: created.chunkSize, resumed: created.resumed, received: created.received });
                     progress();
                     return sendAll(p.meta, p.chunks).then(function () {
                         if (signal.aborted) throw abortError();
-                        return json('POST', base + '/_uploads/' + p.meta.id + '/_complete');
+                        return seal(p.meta, false);
                     });
                 })
-                .then(function (handle) { progress(); return handle; })
+                .then(function (handle) {
+                    progress();
+                    notify(opts, { type: 'sealed', handle: handle });
+                    return handle;
+                })
                 .catch(function (err) {
                     var aborted = err.code === 'aborted' || signal.aborted;
                     // Promise.all rejects on the first failure but leaves the other
                     // workers retrying with backoff; stop them before returning.
                     controller.abort();
+                    if (!createdSettled) settleCreated(true, err);
                     if (task.id) {
                         // Discard only on an explicit abort — the caller is done
                         // with it. Any other failure keeps the staged chunks so
                         // upload({ resume: err.uploadId }) can finish the job; the
-                        // TTL reclaims them if it never does.
+                        // TTL reclaims them if it never does. An expired upload is
+                        // the exception: the server already reclaimed it, so
+                        // offering a resume would send the page into a 404 loop.
                         if (aborted) transport.fetch(base + '/_uploads/' + task.id, { method: 'DELETE', credentials: 'same-origin' }).catch(function () {});
-                        else err.uploadId = task.id;
+                        else if (err.code !== 'upload_expired') err.uploadId = task.id;
                     }
+                    notify(opts, { type: 'failed', error: err, aborted: aborted, resumable: !!err.uploadId });
                     throw err;
                 });
 
@@ -192,7 +271,41 @@ export function streamsClientSource() {
             return base + '/_downloads/' + encodeURIComponent(id) + (filename ? '/' + encodeURIComponent(filename) : '');
         }
 
-        return { upload: upload, downloadUrl: downloadUrl };
+        // What the store holds for this user in this app (I5-13030). The helper
+        // owns the base URL, so these are the sanctioned way to ask — a page
+        // must not derive the prefix from downloadUrl() and hand-build the calls.
+        var streams = {
+            // Resume state for an upload there is no task for: which chunks
+            // landed, which are missing, whether it is sealed.
+            status: function (id) {
+                return json('GET', base + '/_uploads/' + encodeURIComponent(id));
+            },
+            // Every upload and download this user has staged for the app,
+            // oldest first. What a truthful "n of maxStreamsPerUser" reads.
+            list: function () {
+                return Promise.all([json('GET', base + '/_uploads'), json('GET', base + '/_downloads')])
+                    .then(function (r) {
+                        // A truthy non-array (an auth-bounce page body) would
+                        // otherwise pass through as an empty-looking listing.
+                        if (!Array.isArray(r[0]) || !Array.isArray(r[1])) {
+                            throw new Error('streams.list(): the staging routes did not answer with listings');
+                        }
+                        return { uploads: r[0], downloads: r[1] };
+                    });
+            },
+            // Free a staged stream now rather than at expiry. Takes a handle or
+            // a bare id; a handle already carries its kind, so only a bare id
+            // needs the second argument (which still defaults to 'upload').
+            discard: function (idOrHandle, type) {
+                var handle = idOrHandle && typeof idOrHandle === 'object' ? idOrHandle : null;
+                var id = handle ? handle.id : idOrHandle;
+                var kind = type || (handle && handle.__appStream) || 'upload';
+                var prefix = kind === 'download' ? '/_downloads/' : '/_uploads/';
+                return json('DELETE', base + prefix + encodeURIComponent(id)).then(function () { return true; });
+            }
+        };
+
+        return { upload: upload, downloadUrl: downloadUrl, streams: streams };
     })("", {
             fetch: function (url, opts) { return window.fetch(url, opts); },
             open: function (xhr, method, url) { xhr.open(method, url); }