@entrinsik/vite-plugin-informer 2.11.0 → 2.13.0

package/src/dev-bag.js

@@ -1,6 +1,7 @@
 import { loadManifest, manifestBlock, buildDevContext, buildDevCrypto, buildDevMessaging, normalizeFetchPath } from './dev-dependencies.js';
 import { createDevChannels, createDevEmit } from './dev-channels.js';
-import { devPlatform } from './dev-platform.js';
+import { LIMITS } from './dev-streams.js';
+import { devPlatform, createDevEmbed } from './dev-platform.js';
 
 /**
  * The part of the dev handler bag every surface shares — `server/` routes and
@@ -11,18 +12,33 @@ import { devPlatform } from './dev-platform.js';
  * for channels), the same split the prod sandbox's buildInvokeScript makes.
  */
 
-// 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.
-export 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)');
-};
-
 // Cap dev proxy calls at 30s so a hung upstream fails loudly instead of
 // hanging the handler.
 const FETCH_TIMEOUT_MS = 30000;
 
+/**
+ * Read a response body into memory, refusing once it passes `max` and cancelling
+ * the reader so the rest never arrives. `arrayBuffer()` would buffer whatever the
+ * upstream sends before anything could measure it.
+ */
+async function readCapped(resp, max) {
+    if (!resp.body) return Buffer.from(await resp.arrayBuffer());
+    const reader = resp.body.getReader();
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        total += value.byteLength;
+        if (total > max) {
+            await reader.cancel();
+            throw new RangeError(`The upstream body exceeds the ${max} bytes the dev server holds in memory`);
+        }
+        chunks.push(Buffer.from(value));
+    }
+    return Buffer.concat(chunks);
+}
+
 /** log(message, data) + log.debug/info/warn/error — the sandbox log surface, to the terminal. */
 export function buildDevLog(prefix = '[app-log]') {
     const logCall = (level, message, data) => {
@@ -65,9 +81,15 @@ export function buildDevUser(user) {
  * @param {string|null} [opts.appToken] - INFORMER_APP_TOKEN for cross-app request()
  * @param {ReturnType<typeof createDevChannels>} [opts.channels] - the dev channels hub
  * @param {string} [opts.logPrefix] - prefix for notify/email/emit console lines
- * @returns {{ query: Function, apiFetch: Function, build: () => Promise<{ manifest: Object, bag: Object }> }}
+ * @param {Object} [opts.platform] - the MERGED platform descriptor (dev defaults
+ *   + mock.platform). The bag must see the same one the browser does, or an app
+ *   that opts into `embeddings` reads the flag as true and still finds embed()
+ *   throwing. Defaults to the bare dev descriptor.
+ * @param {string|null} [opts.appId] - the deployed app's id, for the opt-in
+ *   dev embed()'s call to its `_embed` route
+ * @returns {{ query: Function, apiFetch: Function, build: (opts?: { forwarding?: Object|null }) => Promise<{ manifest: Object, bag: Object }> }}
  */
-export function createDevBagBuilder({ serverOrigin, authHeader, devWorkspaceId, projectRoot, devBindings = {}, appToken = null, channels = createDevChannels(), logPrefix = '[app]' }) {
+export function createDevBagBuilder({ serverOrigin, authHeader, devWorkspaceId, projectRoot, devBindings = {}, appToken = null, channels = createDevChannels(), logPrefix = '[app]', platform = devPlatform(), appId = null }) {
     // query() implementation — proxies to the workspace _sql endpoint
     async function query(sql, params) {
         if (!devWorkspaceId) {
@@ -97,7 +119,12 @@ export function createDevBagBuilder({ serverOrigin, authHeader, devWorkspaceId,
         // 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' };
+            // `message` is where every other failure from here puts its
+            // sentence (the synthetic 502 below, and boom's own answers), so
+            // one field read by a caller finds all of them. `error` stays
+            // beside it for anything already reading that.
+            const reason = `Invalid fetch path: ${String(path).slice(0, 80)}`;
+            return { status: 400, body: { message: reason, error: reason }, contentType: 'application/json' };
         }
         const url = `${serverOrigin}${apiPath}`;
         const fetchOpts = {
@@ -112,13 +139,31 @@ export function createDevBagBuilder({ serverOrigin, authHeader, devWorkspaceId,
         // 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;
+        // instead — same as prod's unwrapInject. `raw: true` (I5-13030, a
+        // stream being filled from an integration) keeps the bytes as bytes and
+        // hands the headers back too; the body is still parsed for an error.
+        let status, contentType, text, bytes, headers;
         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();
+            if (opts.raw) {
+                // Bounded before it is buffered. Prod meters the body mid-stream
+                // and tears the socket down at the first byte past the cap; here
+                // the whole thing lands in memory, so an unbounded read turns a
+                // clean 413 into an OOM'd dev server with nothing naming the
+                // cause. The declared length is the cheap check; the running one
+                // covers a chunked response that declares nothing.
+                const declared = Number(resp.headers.get('content-length'));
+                if (Number.isFinite(declared) && declared > LIMITS.maxUploadBytes) {
+                    throw new RangeError(`The upstream body is ${declared} bytes; the dev server holds at most ${LIMITS.maxUploadBytes} in memory`);
+                }
+                bytes = await readCapped(resp, LIMITS.maxUploadBytes);
+                headers = Object.fromEntries(resp.headers.entries());
+                text = status >= 400 ? bytes.toString('utf8') : '';
+            } else {
+                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
@@ -129,7 +174,7 @@ export function createDevBagBuilder({ serverOrigin, authHeader, devWorkspaceId,
         }
         let body;
         try { body = JSON.parse(text); } catch { body = text; }
-        return { status, body, contentType };
+        return opts.raw ? { status, body, contentType, bytes, headers } : { status, body, contentType };
     }
 
     async function apiFetch(path, opts = {}) {
@@ -155,6 +200,11 @@ export function createDevBagBuilder({ serverOrigin, authHeader, devWorkspaceId,
     // won't 500 in production.
     const { notify, email } = buildDevMessaging(logPrefix);
     const log = buildDevLog();
+    // Throws the written explanation a real install gives an app type without
+    // the capability, unless the mock platform opts into embeddings; then it
+    // posts to the deployed app's _embed route through apiFetch. See
+    // createDevEmbed.
+    const embed = createDevEmbed({ platform, apiFetch, appId });
     // markdown helper — passthrough in dev (production uses `marked`)
     const markdown = (text) => text;
 
@@ -162,11 +212,17 @@ export function createDevBagBuilder({ serverOrigin, authHeader, devWorkspaceId,
      * The shared bag for one invocation. The manifest is parsed per call
      * (deps, env and channels all come from that one read) so edits to
      * informer.yaml take effect without a dev-server restart.
+     *
+     * @param {Object} [opts]
+     * @param {Object|null} [opts.forwarding] - the request's stream forwarding
+     *   services (dev-streams.js createStreamServices), so an integration
+     *   request() can send a staged upload or fill a download; only `server/`
+     *   routes have streams, so channel handlers leave it null
      */
-    async function build() {
+    async function build({ forwarding = null } = {}) {
         const manifest = await loadManifest(projectRoot);
         const deps = manifestBlock(manifest, 'dependencies');
-        const context = buildDevContext({ deps, apiFetch, devBindings, appFetch });
+        const context = buildDevContext({ deps, apiFetch, devBindings, appFetch, forwarding, serverOrigin });
         const env = manifestBlock(manifest, 'env');
 
         // emit() writes no app_event row in dev, but still relays a listed
@@ -177,7 +233,7 @@ export function createDevBagBuilder({ serverOrigin, authHeader, devWorkspaceId,
 
         return {
             manifest,
-            bag: { context, query, fetch: apiFetch, emit, broadcast, notify, email, embed, crypto: buildDevCrypto(), markdown, log, env, platform: devPlatform() }
+            bag: { context, query, fetch: apiFetch, emit, broadcast, notify, email, embed, crypto: buildDevCrypto(), markdown, log, env, platform }
         };
     }
 

package/src/dev-channel-actors.js

@@ -0,0 +1,352 @@
+import { createHash } from 'node:crypto';
+
+/**
+ * Channel actors in the dev mirror, the counterpart of the server's
+ * app-channel-actors.js. A `channels/` file whose `config.actor` is an object
+ * gets one live module instance per concrete channel (`match/42`), kept while
+ * pages are subscribed:
+ *
+ *   - start({ channel, restored }) runs first, then join / joined / leave and
+ *     every event export run inside that instance, one call at a time
+ *   - tick({ dt, frame }) runs `config.actor.tick` times a second; a tick that
+ *     comes due while a call is still running is skipped, not queued
+ *   - the actor stops `idleMs` after its last page leaves, with its
+ *     stop({ reason }), and the next join or send starts a fresh one
+ *   - snapshot() is called every `snapshotMs` and kept in memory; when a file
+ *     the actors load changes, each actor keeps a snapshot, stops with reason
+ *     'redeploy', and restarts at once on the new code from it, with the same
+ *     pages: a game survives an edit, as it survives a deploy on the server
+ *
+ * A page is one member here (a dev page is one client, with no reconnects),
+ * so leave runs when it unsubscribes. The server's cluster, leases, billing
+ * and rate limits have no dev counterpart.
+ */
+
+export const ACTOR_LIFECYCLE = Object.freeze(['start', 'stop', 'tick', 'snapshot']);
+// The server's actors.callTimeoutMs: a call that runs longer stops the actor.
+export const ACTOR_CALL_TIMEOUT_MS = 1000;
+export const ACTOR_STOP_TIMEOUT_MS = 5000;
+const DEFAULTS = Object.freeze({ tick: 0, idleMs: 30000, snapshotMs: 5000 });
+const MAX_TICK_HZ = 60;
+
+export function isActorModule(mod) {
+    const actor = mod && mod.config && mod.config.actor;
+    return Boolean(actor && typeof actor === 'object' && !Array.isArray(actor));
+}
+
+/** `request.member` for a dev page: a hash of its client id, shaped like the server's. */
+export function memberIdFor(clientId) {
+    return `m_${createHash('sha256').update(`dev:${clientId}`).digest('base64url').slice(0, 16)}`;
+}
+
+function optionsOf(mod) {
+    const asked = mod.config.actor;
+    return {
+        tickHz: Math.min(Math.max(Number(asked.tick) || 0, 0), MAX_TICK_HZ),
+        idleMs: asked.idleMs === undefined ? DEFAULTS.idleMs : Math.max(0, Number(asked.idleMs) || 0),
+        snapshotMs: Math.min(Math.max(Number(asked.snapshotMs) || DEFAULTS.snapshotMs, 1000), 60000)
+    };
+}
+
+// What `config.actor` may say, and the wording the deploy uses to refuse it
+// (channel-scanner.js assertActorConfig on the server). Without this, a file
+// that sets `actor: { tickRate: 30 }` or exports tick() with no rate runs
+// quietly tick-less in dev and 400s at deploy time.
+const ACTOR_KEYS = ['tick', 'idleMs', 'memoryMb', 'snapshotMs'];
+
+function assertActorConfig(mod, filePath) {
+    const actor = mod.config.actor;
+    const exports = Object.keys(mod);
+    const fail = message => {
+        throw new Error(`channel handler "${filePath}" ${message} Fix config.actor.`);
+    };
+    const unknown = Object.keys(actor).filter(key => !ACTOR_KEYS.includes(key));
+    if (unknown.length) fail(`sets config.actor.${unknown.join(', config.actor.')}, which is not an actor setting (${ACTOR_KEYS.join(', ')} are).`);
+    const number = (key, min) => {
+        if (actor[key] === undefined) return;
+        if (typeof actor[key] !== 'number' || !Number.isFinite(actor[key]) || actor[key] < min) {
+            fail(`sets config.actor.${key} to ${JSON.stringify(actor[key])}; it must be a number of at least ${min}.`);
+        }
+    };
+    number('tick', 0);
+    number('idleMs', 0);
+    number('memoryMb', 8);
+    number('snapshotMs', 1000);
+    if (actor.tick > 0 && !exports.includes('tick')) fail(`sets config.actor.tick to ${actor.tick} but exports no tick() to call.`);
+    if (exports.includes('tick') && !(actor.tick > 0)) fail('exports tick() but config.actor.tick does not say how often to call it.');
+    if (actor.snapshotMs !== undefined && !exports.includes('snapshot')) fail(`sets config.actor.snapshotMs to ${actor.snapshotMs} but exports no snapshot() to call.`);
+}
+
+const unavailable = name => () => {
+    throw new Error(`${name}() is not available in a channel actor: it would run with one subscriber's credentials on behalf of all of them. Call a server/ route from the page instead.`);
+};
+
+/**
+ * @param {Object} opts
+ * @param {Object} opts.viteServer - loads a fresh module instance per actor run (ssrLoadModule with a query)
+ * @param {Function} opts.bagFor - async (channel, params) => the handler bag (broadcast, query, log, …)
+ * @param {string} [opts.logPrefix]
+ * @param {number} [opts.callTimeoutMs]
+ */
+export function createDevActors({ viteServer, bagFor, logPrefix = '[app-channel]', callTimeoutMs = ACTOR_CALL_TIMEOUT_MS }) {
+    const actors = new Map();       // channel name → actor
+    const starting = new Map();     // channel name → its start in flight
+    const snapshots = new Map();    // channel name → the last snapshot() kept
+    let runs = 0;
+
+    async function load(filePath, channel) {
+        // a query per run: a separate instance per channel, and a fresh one per start
+        return await viteServer.ssrLoadModule(`${filePath}?actor=${encodeURIComponent(channel)}&run=${++runs}`);
+    }
+
+    function queue(actor, exportName, extras, timeoutMs = callTimeoutMs) {
+        const run = async () => {
+            if (actor.state === 'stopped') throw Object.assign(new Error('app_channel_actor_stopped'), { statusCode: 503, code: 'app_channel_actor_stopped' });
+            actor.busy = true;
+            let timer;
+            try {
+                const call = Promise.resolve().then(() => actor.mod[exportName]({ ...actor.bag, ...extras }));
+                const overrun = new Promise((_, reject) => {
+                    timer = setTimeout(() => reject(Object.assign(new Error(`${exportName} ran past ${timeoutMs} ms`), { overrun: true })), timeoutMs);
+                });
+                return await Promise.race([call, overrun]);
+            } catch (err) {
+                if (err && err.overrun) {
+                    console.error(`${logPrefix} actor "${actor.channel}" stopped: ${err.message}; the next join or send starts a new one`);
+                    stop(actor, 'timeout');
+                    throw Object.assign(new Error('app_channel_actor_timeout'), { statusCode: 504, code: 'app_channel_actor_timeout' });
+                }
+                if (err && typeof err.statusCode === 'number') throw err;
+                console.error(`${logPrefix} ${exportName}("${actor.channel}") failed:`, err);
+                throw Object.assign(new Error(`app_channel_${exportName}_failed`), { statusCode: 500, code: 'app_channel_send_failed' });
+            } finally {
+                clearTimeout(timer);
+                actor.busy = false;
+            }
+        };
+        const result = actor.queue.then(run, run);
+        actor.queue = result.catch(() => {});
+        return result;
+    }
+
+    const has = (actor, name) => typeof actor.mod[name] === 'function';
+
+    // Another actor took this channel while this one was stopping: the
+    // channel's shared state (its kept snapshot, its registry slot) is that
+    // one's now, and this one must not write over it.
+    const isReplaced = actor => actors.has(actor.channel) && actors.get(actor.channel) !== actor;
+
+    function scheduleTick(actor) {
+        const period = 1000 / actor.options.tickHz;
+        const next = actor.tickOrigin + (actor.frame + 1) * period;
+        actor.timers.tick = setTimeout(() => {
+            if (actor.state !== 'running') return;
+            actor.frame++;
+            if (!actor.busy) {
+                const now = Date.now();
+                const dt = (now - actor.lastTickAt) / 1000;
+                actor.lastTickAt = now;
+                queue(actor, 'tick', { dt, frame: actor.frame, request: null }).catch(() => {});
+            }
+            scheduleTick(actor);
+        }, Math.max(0, next - Date.now()));
+    }
+
+    function armIdle(actor) {
+        clearTimeout(actor.timers.idle);
+        if (actor.members.size > 0 || actor.state !== 'running') return;
+        actor.timers.idle = setTimeout(() => stop(actor, 'idle'), actor.options.idleMs);
+    }
+
+    async function saveSnapshot(actor) {
+        if (!has(actor, 'snapshot')) return;
+        try {
+            const state = await queue(actor, 'snapshot', { request: null });
+            // taken between messages, so a replacement may have started meanwhile
+            if (state !== undefined && state !== null && !isReplaced(actor)) snapshots.set(actor.channel, JSON.parse(JSON.stringify(state)));
+        } catch {
+            // reported by queue()
+        }
+    }
+
+    async function start(channel, params, filePath) {
+        const mod = await load(filePath, channel);
+        assertActorConfig(mod, filePath);
+        const bag = await bagFor(channel, params);
+        // An actor's broadcast to its own channel answers the production shape:
+        // there it is queued on the actor's ordered chain and has no seq yet,
+        // and `const { seq } = await channel.broadcast(...)` must not read as a
+        // usable number locally and null once deployed. Any other channel goes
+        // the way every handler's broadcast does.
+        const broadcastOwn = async (event, body, options) => {
+            await bag.broadcast(channel, event, body, options);
+            return { ok: true, queued: true, seq: null };
+        };
+        const actor = {
+            channel, params, filePath, mod,
+            options: optionsOf(mod),
+            bag: {
+                ...bag,
+                broadcast: (name, event, body, options) => (name === channel
+                    ? broadcastOwn(event, body, options)
+                    : bag.broadcast(name, event, body, options)),
+                fetch: unavailable('fetch'),
+                context: undefined,
+                channel: { name: channel, params, broadcast: broadcastOwn }
+            },
+            members: new Map(),     // clientId → the request it joined with
+            queue: Promise.resolve(),
+            busy: false,
+            timers: {},
+            frame: 0,
+            state: 'running'
+        };
+        actors.set(channel, actor);
+        const restored = has(actor, 'snapshot') ? snapshots.get(channel) : undefined;
+        if (has(actor, 'start')) {
+            try {
+                await queue(actor, 'start', { restored, request: null });
+            } catch (err) {
+                // a state the new start cannot take would fail every start after it too
+                snapshots.delete(channel);
+                actors.delete(channel);
+                actor.state = 'stopped';
+                throw err;
+            }
+        }
+        if (actor.options.tickHz > 0 && has(actor, 'tick')) {
+            actor.tickOrigin = Date.now();
+            actor.lastTickAt = actor.tickOrigin;
+            scheduleTick(actor);
+        }
+        if (has(actor, 'snapshot')) actor.timers.snapshot = setInterval(() => saveSnapshot(actor), actor.options.snapshotMs);
+        armIdle(actor);
+        console.log(`${logPrefix} actor "${channel}" started${restored !== undefined ? ' from its snapshot' : ''}`);
+        return actor;
+    }
+
+    /**
+     * Stop an actor: for a redeploy (an edited file) keep a snapshot first;
+     * after idle or a timeout drop it; stop() runs unless the actor hung.
+     */
+    function stop(actor, reason) {
+        if (actor.stopping) return actor.stopping;
+        // Synchronously, as the server does: a stop that only marks the actor
+        // dead after its awaits hands it out of ensure() for the whole
+        // graceful stop, and the page joins an actor that is on its way out.
+        actor.state = 'stopping';
+        actor.stopping = (async () => {
+            clearTimeout(actor.timers.tick);
+            clearTimeout(actor.timers.idle);
+            clearInterval(actor.timers.snapshot);
+            if (reason === 'redeploy' || reason === 'shutdown') await saveSnapshot(actor);
+            if (reason !== 'timeout' && has(actor, 'stop')) {
+                await queue(actor, 'stop', { reason, request: null }, ACTOR_STOP_TIMEOUT_MS).catch(() => {});
+            }
+            actor.state = 'stopped';
+            const replaced = isReplaced(actor);
+            // a replacement started while this one was stopping owns the
+            // channel's snapshot now
+            if ((reason === 'idle' || reason === 'timeout') && !replaced) snapshots.delete(actor.channel);
+            if (!replaced) actors.delete(actor.channel);
+            console.log(`${logPrefix} actor "${actor.channel}" stopped (${reason})`);
+        })();
+        return actor.stopping;
+    }
+
+    /**
+     * Admit a page: the actor's join decides (exactly true admits), and an
+     * actor never holds a member its join did not admit. Every admission goes
+     * through here, as on the server, so a join that seeds per-member state or
+     * caps seats is exercised in dev too -- not just on the subscribe path.
+     */
+    async function admit(actor, clientId, request) {
+        if (has(actor, 'join') && await queue(actor, 'join', { payload: null, request }) !== true) {
+            armIdle(actor);
+            throw Object.assign(new Error('app_channel_join_refused'), { statusCode: 403, code: 'app_channel_join_refused' });
+        }
+        actor.members.set(clientId, request);
+        clearTimeout(actor.timers.idle);
+    }
+
+    // The running actor for a channel, starting one if there is none; two
+    // callers at once share one start.
+    async function ensure(channel, params, filePath) {
+        const running = actors.get(channel);
+        if (running && running.state === 'running' && !starting.has(channel)) return running;
+        if (!starting.has(channel)) {
+            starting.set(channel, start(channel, params, filePath).finally(() => starting.delete(channel)));
+        }
+        return await starting.get(channel);
+    }
+
+    return {
+        /** A page subscribes: the actor's join decides (exactly true admits). */
+        async join({ channel, params, filePath, clientId, request }) {
+            const actor = await ensure(channel, params, filePath);
+            await admit(actor, clientId, request);
+        },
+        async joined({ channel, clientId, request }) {
+            const actor = actors.get(channel);
+            if (!actor || !actor.members.has(clientId) || !has(actor, 'joined')) return;
+            await queue(actor, 'joined', { payload: null, request });
+        },
+        async leave({ channel, clientId }) {
+            const actor = actors.get(channel);
+            if (!actor || !actor.members.has(clientId)) return;
+            const request = actor.members.get(clientId);
+            actor.members.delete(clientId);
+            armIdle(actor);
+            if (has(actor, 'leave')) await queue(actor, 'leave', { payload: null, request });
+        },
+        /** A page's send(): a call into the running actor, started afresh if it stopped. */
+        async send({ channel, params, filePath, clientId, request, event, payload }) {
+            const actor = await ensure(channel, params, filePath);
+            if (ACTOR_LIFECYCLE.includes(event) || typeof actor.mod[event] !== 'function') {
+                throw Object.assign(new Error('app_channel_no_handler'), { statusCode: 404, code: 'app_channel_no_handler' });
+            }
+            // a sender this actor has not admitted (it restarted, or its code
+            // changed since the page joined) goes through join like anyone else
+            if (!actor.members.has(clientId)) await admit(actor, clientId, request);
+            return await queue(actor, event, { payload: payload === undefined ? null : payload, request });
+        },
+        /**
+         * A file an actor loads changed: an actor that keeps snapshots and has
+         * pages stops with one and restarts at once on the new code, carrying
+         * its pages in through the new code's own join. Any other actor just
+         * stops, and the next join or send starts it fresh -- the same two
+         * rules the server follows across a deploy, so a join that refuses the
+         * carried page (or a file that keeps no snapshot) behaves here as it
+         * will there.
+         */
+        async restartAll() {
+            const running = [...actors.values()].filter(a => a.state === 'running');
+            await Promise.all(running.map(async actor => {
+                const carry = has(actor, 'snapshot') && actor.members.size > 0;
+                const members = new Map(actor.members);
+                await stop(actor, 'redeploy');
+                if (!carry) return;
+                try {
+                    const next = await ensure(actor.channel, actor.params, actor.filePath);
+                    for (const [clientId, request] of members) {
+                        try {
+                            await admit(next, clientId, request);
+                        } catch (err) {
+                            console.log(`${logPrefix} a page was not carried into actor "${actor.channel}" on the edited code: ${err.message}`);
+                        }
+                    }
+                } catch (err) {
+                    console.error(`${logPrefix} actor "${actor.channel}" did not restart on the edited code:`, err);
+                }
+            }));
+        },
+        async stopAll(reason = 'shutdown') {
+            await Promise.all([...actors.values()].map(actor => stop(actor, reason)));
+        },
+        /** What is running, for the terminal and tests. */
+        list() {
+            return [...actors.values()].map(a => ({ channel: a.channel, members: a.members.size, frame: a.frame, state: a.state }));
+        },
+        snapshots
+    };
+}