@entrinsik/vite-plugin-informer 2.10.0 → 2.11.0

package/README.md

@@ -23,7 +23,7 @@ The assembler uploads your built frontend plus these source trees, matching how
 | `webhooks/` | Publicly callable webhook routes |
 | `tools/` | AI tools, private to the App's agents |
 | `mcp/` | Tools exposed over the App's MCP endpoint |
-| `channels/` | Live channel join/leave handlers |
+| `channels/` | Live channel handlers: `join` / `joined` / `leave` and event-named handlers for `channel.send()`; `npm run dev` runs them locally, and the `channels:` block in `informer.yaml` declares relays only (each entry needs `on`) |
 | `migrations/` | Workspace database migrations, run in order on deploy |
 | `embeddings/` | Declarative embedding use cases (see below) |
 | `lib/`, `shared/` | Modules importable by the trees above |
@@ -44,6 +44,8 @@ Against an older server the CLI:
 
 A server whose version isn't comparable (a `dev` build, or an `/about` behind a proxy) is treated as current and warned about — gating it would break deploys to builds made from source.
 
+App Channels phase 2 (plugin 2.11.0: `channel.send()`, the `joined` export and event-named exports in `channels/` files, wildcard subscriptions, frame `seq` and replay, `connected`) needs a 2026.1.3 server that carries I5-13027. The version probe cannot tell such a server from an earlier 2026.1.3 build, so the deploy is not gated: an earlier build refuses a `channels/` file that exports `joined` or an event name, and accepts a `channels:` entry without `on` that a current server rejects. The dev server runs the phase 2 contract regardless.
+
 Feature-detect at runtime with optional chaining, since `platform` is absent entirely before 2026.1.3:
 
 ```javascript

package/bin/workspace.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 
 import { readFile } from 'node:fs/promises';
-import { resolve } from 'node:path';
+import { resolve, basename } from 'node:path';
 import { createClient } from '../src/client.js';
-import { loadEnv, envWritePath, parseModeArg } from '../src/env.js';
+import { loadEnv, envWritePath, localEnvValue, parseModeArg } from '../src/env.js';
 import { init, migrate, reset } from '../src/workspace.js';
 
 const mode = parseModeArg(process.argv);
@@ -41,12 +41,22 @@ const api = createClient({ baseUrl, apiKey, user, pass });
 const migrationsDir = resolve('migrations');
 const envPath = envWritePath({ mode });
 
+// loadEnv walks up to a parent .env (monorepo config), so process.env may
+// carry ANOTHER app's workspace id. Only this app's own env file decides
+// whether it is initialized; migrate/reset fall back to the inherited value.
+const localWorkspaceId = localEnvValue('INFORMER_DEV_WORKSPACE', { mode });
+const inheritedWorkspaceId = process.env.INFORMER_DEV_WORKSPACE || null;
+if (!localWorkspaceId && inheritedWorkspaceId && command === 'init') {
+    console.log(`Ignoring INFORMER_DEV_WORKSPACE=${inheritedWorkspaceId} inherited from the environment: ${basename(envPath)} does not define it.`);
+}
+const workspaceId = localWorkspaceId || inheritedWorkspaceId;
+
 try {
     if (command === 'init') {
         // Check if already initialized
-        if (process.env.INFORMER_DEV_WORKSPACE) {
-            console.error(`Workspace already initialized: ${process.env.INFORMER_DEV_WORKSPACE}`);
-            console.error('Run workspace:reset to start fresh, or remove INFORMER_DEV_WORKSPACE from .env to re-initialize.');
+        if (localWorkspaceId) {
+            console.error(`Workspace already initialized: ${localWorkspaceId}`);
+            console.error(`Run workspace:reset to start fresh, or remove INFORMER_DEV_WORKSPACE from ${basename(envPath)} to re-initialize.`);
             process.exit(1);
         }
 
@@ -72,7 +82,6 @@ try {
         await init({ api, slug, migrationsDir, envPath });
 
     } else if (command === 'migrate') {
-        const workspaceId = process.env.INFORMER_DEV_WORKSPACE;
         if (!workspaceId) {
             console.error('No dev workspace found. Run workspace:init first.');
             process.exit(1);
@@ -80,7 +89,6 @@ try {
         await migrate({ api, workspaceId, migrationsDir });
 
     } else if (command === 'reset') {
-        const workspaceId = process.env.INFORMER_DEV_WORKSPACE;
         if (!workspaceId) {
             console.error('No dev workspace found. Run workspace:init first.');
             process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@entrinsik/vite-plugin-informer",
-    "version": "2.10.0",
+    "version": "2.11.0",
     "description": "Vite plugin and deploy tool for Informer App development",
     "scripts": {
         "test": "node --test"

package/src/dev-bag.js

@@ -0,0 +1,185 @@
+import { loadManifest, manifestBlock, buildDevContext, buildDevCrypto, buildDevMessaging, normalizeFetchPath } from './dev-dependencies.js';
+import { createDevChannels, createDevEmit } from './dev-channels.js';
+import { devPlatform } from './dev-platform.js';
+
+/**
+ * The part of the dev handler bag every surface shares — `server/` routes and
+ * `channels/` handlers alike: the platform services (`query`, `fetch`, the
+ * typed dependency `context`, `emit`, `broadcast`, `notify`, `email`,
+ * `crypto`, `markdown`, `log`, `env`, `platform`). Each surface adds only its
+ * own inbound members (`request` + `respond` for HTTP, `channel` + `payload`
+ * 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;
+
+/** 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) => {
+        const msg = typeof message === 'string' ? message : JSON.stringify(message);
+        const args = [`${prefix} [${level}] ${msg}`];
+        if (data) args.push(data);
+        console.log(...args);
+    };
+    return 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)
+        }
+    );
+}
+
+/** The viewer identity dev handlers see — the same object the page gets as window.__INFORMER__.user. */
+export function buildDevUser(user) {
+    return {
+        username: (user && user.username) || 'dev',
+        displayName: (user && user.displayName) || 'Local Developer',
+        email: (user && user.email) || null,
+        timezone: (user && user.timezone) || null
+    };
+}
+
+/**
+ * Build the shared services once per dev server and the per-invocation bag
+ * on demand.
+ *
+ * @param {Object} opts
+ * @param {string} opts.serverOrigin - Informer server origin
+ * @param {string} opts.authHeader - Basic or Bearer auth header for /api calls
+ * @param {string|null} opts.devWorkspaceId - workspace datasource id for query()
+ * @param {string} opts.projectRoot - app project root
+ * @param {Object} [opts.devBindings] - dev bindings for `target: app` / `target: pack` deps
+ * @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 }> }}
+ */
+export function createDevBagBuilder({ serverOrigin, authHeader, devWorkspaceId, projectRoot, devBindings = {}, appToken = null, channels = createDevChannels(), logPrefix = '[app]' }) {
+    // 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;
+
+    // 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(logPrefix);
+    const log = buildDevLog();
+    // markdown helper — passthrough in dev (production uses `marked`)
+    const markdown = (text) => text;
+
+    /**
+     * 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.
+     */
+    async function build() {
+        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;
+
+        return {
+            manifest,
+            bag: { context, query, fetch: apiFetch, emit, broadcast, notify, email, embed, crypto: buildDevCrypto(), markdown, log, env, platform: devPlatform() }
+        };
+    }
+
+    return { query, apiFetch, build };
+}

package/src/dev-channel-handlers.js

@@ -0,0 +1,325 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parse as parseUrl } from 'node:url';
+import { createDevBagBuilder, buildDevUser } from './dev-bag.js';
+import { filePathToRoute, matchRoute, walkJsFiles } from './server-routes.js';
+import { createDevChannels, isChannelName, isWildcardName, isEventName, isReservedEvent, channelError, USER_CHANNEL_PREFIX } from './dev-channels.js';
+
+/**
+ * The dev counterpart of app-channel-handlers.js: a page's `channel()` mock
+ * subscribes, unsubscribes and sends over plain POSTs to DEV_CHANNEL_API, and
+ * the matching `channels/` file runs in-process the way a deployed handler
+ * runs in the sandbox — `join` decides admission, `joined` runs after it,
+ * `leave` runs on unsubscribe, and an event-named export answers `send()`.
+ * Frames still ride Vite's websocket to every page; admission is what tells
+ * the page which frames it may dispatch.
+ */
+
+export const CHANNELS_DIR = 'channels';
+// The synthetic method channel handlers are matched under (deploy.js rebuildRouteTable).
+export const CHANNEL_METHOD = 'CHANNEL';
+// The deployment's joinTimeoutMs cap; a file's `config.timeout` may only lower it.
+export const HANDLER_TIMEOUT_MS = 5000;
+// Per-user inbound send budget (token bucket).
+export const SEND_RATE = Object.freeze({ perSecond: 10, burst: 30 });
+// Exports with a fixed meaning; every other export must be an event name.
+export const LIFECYCLE_EXPORTS = Object.freeze(['config', 'join', 'joined', 'leave']);
+
+// One literal segment of a channel name (app-channel-broadcast.js CHANNEL_SEGMENT).
+const CHANNEL_SEGMENT = /^[\w.-]+$/;
+const USER_SEGMENT = USER_CHANNEL_PREFIX.slice(0, -1);
+
+// Named exports as the deploy's scanner would list them: declarations and
+// `export { a, b as c }` lists (`export default` lands as "default").
+const EXPORT_DECL = /^\s*export\s+(?:async\s+)?(?:function\s*\*?\s*|const\s+|let\s+|var\s+|class\s+)([A-Za-z_$][\w$]*)/gm;
+const EXPORT_LIST = /^\s*export\s*\{([^}]*)\}/gm;
+const EXPORT_DEFAULT = /^\s*export\s+default\b/m;
+
+/** The export names a channel handler source declares. */
+export function exportNames(source) {
+    const names = new Set();
+    for (const m of source.matchAll(EXPORT_DECL)) names.add(m[1]);
+    for (const m of source.matchAll(EXPORT_LIST)) {
+        for (const entry of m[1].split(',')) {
+            const parts = entry.trim().split(/\s+as\s+/);
+            const name = (parts[1] || parts[0]).trim();
+            if (name) names.add(name);
+        }
+    }
+    if (EXPORT_DEFAULT.test(source)) names.add('default');
+    return [...names].sort();
+}
+
+/**
+ * Scan the app's channels/ directory into handler routes, the same
+ * file-convention mapping server/ uses: `channels/rooms/[room].js` → `/rooms/:room`.
+ *
+ * @param {string} projectRoot
+ * @returns {Promise<Array<{ path: string, relPath: string, filePath: string }>>}
+ */
+export async function scanChannelHandlers(projectRoot) {
+    const files = await walkJsFiles(join(projectRoot, CHANNELS_DIR), CHANNELS_DIR);
+    return files.map(({ relPath, absPath }) => ({
+        path: filePathToRoute(relPath, CHANNELS_DIR),
+        relPath,
+        filePath: absPath
+    }));
+}
+
+/**
+ * The deploy-time rules for channels/ files (channel-scanner.js), as boot
+ * diagnostics: a file may export `config`, `join`, `joined`, `leave` and
+ * event-named handlers; it must export something; its path must name a
+ * channel a page can subscribe to; two files may not share a path.
+ *
+ * @param {string} projectRoot
+ * @returns {Promise<string[]>} one message per problem, prefixed with the file
+ */
+export async function validateChannelHandlers(projectRoot) {
+    const problems = [];
+    const byPath = new Map();
+    for (const handler of await scanChannelHandlers(projectRoot)) {
+        const source = await readFile(handler.filePath, 'utf8');
+        const names = exportNames(source);
+        if (names.length === 0) {
+            problems.push(`${handler.relPath}: exports nothing — a channel handler exports join, joined, leave and/or event handlers (and optionally config)`);
+        }
+        const invalid = names.filter(name => !LIFECYCLE_EXPORTS.includes(name) && (name === 'default' || !isEventName(name) || isReservedEvent(name)));
+        if (invalid.length) {
+            problems.push(`${handler.relPath}: exports ${invalid.join(', ')} — only config, join, joined, leave and event-named handlers (not error/connected) are allowed`);
+        }
+        const segments = handler.path === '/' ? [] : handler.path.slice(1).split('/');
+        const subscribable = segments.length > 0 && segments.every((segment, i) =>
+            segment.startsWith(':') || CHANNEL_SEGMENT.test(segment) || (i === 0 && segment === USER_SEGMENT));
+        if (!subscribable) {
+            problems.push(`${handler.relPath}: maps to "${handler.path}", a channel no page can subscribe to — name segments use letters, digits, "_", "." and "-" (or a [param]), and channels/index.js names no channel at all`);
+        }
+        const dup = byPath.get(handler.path);
+        if (dup) problems.push(`${handler.relPath}: channel "${handler.path}" is also defined by ${dup}`);
+        byPath.set(handler.path, handler.relPath);
+    }
+    return problems;
+}
+
+// Does a handler route cover some channel strictly under `prefix` segments?
+// (`/rooms/:room` and `/rooms/east/members` both cover names under `rooms/`.)
+function coversUnder(routePath, prefix) {
+    const segments = routePath.split('/').filter(Boolean);
+    return segments.length > prefix.length && prefix.every((seg, i) => segments[i].startsWith(':') || segments[i] === seg);
+}
+
+function readJson(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on('data', chunk => chunks.push(chunk));
+        req.on('error', reject);
+        req.on('end', () => {
+            const text = Buffer.concat(chunks).toString('utf8');
+            if (!text) return resolve({});
+            try { resolve(JSON.parse(text)); } catch { reject(channelError('app_channel_invalid_body', 400)); }
+        });
+    });
+}
+
+function sendJson(res, status, body) {
+    res.statusCode = status;
+    res.setHeader('Content-Type', 'application/json');
+    res.end(JSON.stringify(body));
+}
+
+/**
+ * Create the Connect middleware behind DEV_CHANNEL_API.
+ *
+ *   POST /subscribe   { clientId, channel }              → { ok: true } | error
+ *   POST /unsubscribe { clientId, channel }              → { ok: true }
+ *   POST /send        { clientId, channel, event, payload } → { result } | error
+ *   GET  /replay?channel=&since=                          → { frames, oldest, current }
+ *
+ * Errors are `{ error: <code> }` with the status the server would use.
+ *
+ * @param {Object} viteServer - Vite dev server (ssrLoadModule loads the handler files)
+ * @param {Object} opts - createDevBagBuilder options plus:
+ * @param {Object} [opts.user] - the mocked viewer (window.__INFORMER__.user)
+ * @param {string[]} [opts.roles] - the mocked viewer's roles
+ * @param {string} [opts.logPrefix]
+ * @param {number} [opts.timeoutMs] - the handler wall-clock cap
+ * @param {{ perSecond: number, burst: number }} [opts.rate] - the per-user send budget
+ * @param {() => number} [opts.now] - clock, for the rate limiter
+ * @returns {Function} Connect middleware
+ */
+export function createDevChannelHandlers(viteServer, { serverOrigin, authHeader, devWorkspaceId, projectRoot, devBindings = {}, appToken = null, channels = createDevChannels(), user, roles = [], logPrefix = '[app-channel]', timeoutMs = HANDLER_TIMEOUT_MS, rate = SEND_RATE, now = Date.now }) {
+    const devUser = buildDevUser(user);
+    const bagBuilder = createDevBagBuilder({ serverOrigin, authHeader, devWorkspaceId, projectRoot, devBindings, appToken, channels, logPrefix: '[app]' });
+    // clientId → channel name → { clientId, channel, params, file }
+    const subscriptions = new Map();
+    // username → { tokens, ts }
+    const buckets = new Map();
+
+    function recordsFor(clientId) {
+        let records = subscriptions.get(clientId);
+        if (!records) {
+            records = new Map();
+            subscriptions.set(clientId, records);
+        }
+        return records;
+    }
+
+    function takeSendToken(username) {
+        const at = now();
+        let bucket = buckets.get(username);
+        if (!bucket) {
+            bucket = { tokens: rate.burst, ts: at };
+            buckets.set(username, bucket);
+        }
+        bucket.tokens = Math.min(rate.burst, bucket.tokens + (Math.max(0, at - bucket.ts) / 1000) * rate.perSecond);
+        bucket.ts = at;
+        if (bucket.tokens < 1) return false;
+        bucket.tokens -= 1;
+        return true;
+    }
+
+    // The handler file covering a channel name, or null for an open channel.
+    // A wildcard resolves with `*` as the param; when no file takes the
+    // wildcard itself but some file gates a name under its prefix, the
+    // wildcard is refused rather than letting it listen around the gate.
+    async function resolveChannel(channel) {
+        const table = (await scanChannelHandlers(projectRoot)).map(h => ({ ...h, method: CHANNEL_METHOD }));
+        let match;
+        try {
+            match = matchRoute(table, CHANNEL_METHOD, `/${channel}`);
+        } catch (err) {
+            if (err instanceof URIError) throw channelError('app_channel_invalid_name', 400);
+            throw err;
+        }
+        if (match) return { params: match.params, file: match.route };
+        if (isWildcardName(channel)) {
+            const prefix = channel.slice(0, -2).split('/');
+            if (table.some(route => coversUnder(route.path, prefix))) throw channelError('app_channel_wildcard_gated', 403);
+        }
+        return null;
+    }
+
+    // Run one export with the channel bag under the handler's timeout. A thrown
+    // channel error keeps its status; anything else is 500 app_channel_<export>_failed.
+    async function runExport(mod, exportName, { channel, params, payload }) {
+        const { bag } = await bagBuilder.build();
+        const invocation = {
+            ...bag,
+            channel: { name: channel, params, broadcast: async (event, body, options) => await bag.broadcast(channel, event, body, options) },
+            payload: payload === undefined ? null : payload,
+            request: { user: { ...devUser }, roles }
+        };
+        const cap = Math.min(Number(mod.config && mod.config.timeout) || timeoutMs, timeoutMs);
+        let timer;
+        const timeout = new Promise((_, reject) => {
+            timer = setTimeout(() => reject(channelError(`app_channel_${exportName}_timeout`, 504)), cap);
+        });
+        try {
+            return await Promise.race([Promise.resolve().then(() => mod[exportName](invocation)), timeout]);
+        } catch (err) {
+            if (err && typeof err.statusCode === 'number') throw err;
+            console.error(`${logPrefix} ${exportName}("${channel}") failed:`, err);
+            throw channelError(`app_channel_${exportName}_failed`, 500);
+        } finally {
+            clearTimeout(timer);
+        }
+    }
+
+    async function subscribe({ clientId, channel }) {
+        if (!isChannelName(channel)) throw channelError('app_channel_invalid_name', 400);
+        // `@user/<username>` is private to that user; the whole remainder is the username.
+        if (channel.startsWith(USER_CHANNEL_PREFIX) && channel.slice(USER_CHANNEL_PREFIX.length) !== devUser.username) {
+            throw channelError('app_channel_user_mismatch', 403);
+        }
+        const resolved = await resolveChannel(channel);
+        const record = { clientId, channel, params: resolved ? resolved.params : {}, file: resolved ? resolved.file : null };
+        if (!resolved) {
+            recordsFor(clientId).set(channel, record);
+            console.log(`${logPrefix} join("${channel}") admitted (open channel)`);
+            return null;
+        }
+
+        const mod = await viteServer.ssrLoadModule(resolved.file.filePath);
+        const required = mod.config && mod.config.roles;
+        if (Array.isArray(required) && required.length > 0 && !required.some(r => roles.includes(r))) {
+            throw channelError('app_channel_role_required', 403);
+        }
+        if (typeof mod.join === 'function') {
+            // admitted only when the handler returned exactly true
+            if (await runExport(mod, 'join', record) !== true) throw channelError('app_channel_join_refused', 403);
+        }
+        recordsFor(clientId).set(channel, record);
+        console.log(`${logPrefix} join("${channel}") admitted${typeof mod.join === 'function' ? '' : ' (no join export)'}`);
+        return mod;
+    }
+
+    async function unsubscribe({ clientId, channel }) {
+        const records = subscriptions.get(clientId);
+        const record = records && records.get(channel);
+        if (!record) return;
+        records.delete(channel);
+        if (!record.file) return;
+        try {
+            const mod = await viteServer.ssrLoadModule(record.file.filePath);
+            if (typeof mod.leave === 'function') await runExport(mod, 'leave', record);
+        } catch (err) {
+            console.warn(`${logPrefix} leave("${channel}") failed: ${err.message}`);
+        }
+    }
+
+    async function send({ clientId, channel, event, payload }) {
+        const records = subscriptions.get(clientId);
+        const record = records && records.get(channel);
+        if (!record) throw channelError('app_channel_not_subscribed', 403);
+        if (!isEventName(event)) throw channelError('app_channel_invalid_event', 400);
+        if (isReservedEvent(event)) throw channelError('app_channel_reserved_event', 400);
+        if (!record.file) throw channelError('app_channel_no_handler', 404);
+        const mod = await viteServer.ssrLoadModule(record.file.filePath);
+        if (LIFECYCLE_EXPORTS.includes(event) || typeof mod[event] !== 'function') throw channelError('app_channel_no_handler', 404);
+        if (!takeSendToken(devUser.username)) throw channelError('app_channel_rate_limited', 429);
+        const result = await runExport(mod, event, { ...record, payload });
+        console.log(`${logPrefix} send("${channel}", "${event}") handled`);
+        return result === undefined ? null : result;
+    }
+
+    return async function devChannelHandlersMiddleware(req, res, next) {
+        const parsed = parseUrl(req.url, true);
+        const route = `${req.method} ${parsed.pathname}`;
+        let body = {};
+        try {
+            if (route === 'GET /replay') {
+                const { channel, since } = parsed.query;
+                if (!isChannelName(channel)) throw channelError('app_channel_invalid_name', 400);
+                return sendJson(res, 200, channels.replay(channel, Number(since) || 0));
+            }
+            if (!['POST /subscribe', 'POST /unsubscribe', 'POST /send'].includes(route)) return next();
+
+            body = await readJson(req);
+            if (typeof body.clientId !== 'string' || !body.clientId) throw channelError('app_channel_client_required', 400);
+
+            if (route === 'POST /subscribe') {
+                const mod = await subscribe(body);
+                sendJson(res, 200, { ok: true });
+                // joined runs once the page has its answer; a failure is the
+                // author's to read in the terminal, never the subscribe's.
+                if (mod && typeof mod.joined === 'function') {
+                    const record = recordsFor(body.clientId).get(body.channel);
+                    setImmediate(() => {
+                        runExport(mod, 'joined', record).catch(err => console.warn(`${logPrefix} joined("${body.channel}") failed: ${err.message}`));
+                    });
+                }
+                return;
+            }
+            if (route === 'POST /unsubscribe') {
+                await unsubscribe(body);
+                return sendJson(res, 200, { ok: true });
+            }
+            return sendJson(res, 200, { result: await send(body) });
+        } catch (err) {
+            const status = typeof err.statusCode === 'number' ? err.statusCode : 500;
+            if (status === 500) console.error(logPrefix, err);
+            else if (route === 'POST /subscribe') console.log(`${logPrefix} join("${body.channel}") refused (${err.code || err.message})`);
+            sendJson(res, status, { error: err.code || err.message });
+        }
+    };
+}