@entrinsik/vite-plugin-informer 2.10.0 → 2.12.0

package/src/dev-channel-handlers.js

@@ -0,0 +1,335 @@
+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 { devPlatform } from './dev-platform.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 budget (token bucket): send() and the replay reads a reconnect makes.
+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 deeper than `minDepth` segments
+// under `prefix`? (`/rooms/:room` and `/rooms/east/members` both cover names
+// under `rooms/`.) `minDepth` is what the wildcard's own handler already gates:
+// the prefix length for an unmatched wildcard, one more for a matched one.
+function coversUnder(routePath, prefix, minDepth) {
+    const segments = routePath.split('/').filter(Boolean);
+    return segments.length > minDepth && 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, platform = devPlatform(), appId = null }) {
+    const devUser = buildDevUser(user);
+    // The same merged descriptor the page and the server/ bag see: a channels/
+    // handler reading platform.capabilities.embeddings must not disagree with
+    // the route beside it, and its embed() must be bound when they agree.
+    const bagBuilder = createDevBagBuilder({ serverOrigin, authHeader, devWorkspaceId, projectRoot, devBindings, appToken, channels, logPrefix: '[app]', platform, appId });
+    // 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 and is admitted only when
+    // nothing sits deeper than the file that took it (or, unmatched, deeper
+    // than its prefix): a deeper file's gate would otherwise be listened around.
+    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 (isWildcardName(channel)) {
+            const prefix = channel.slice(0, -2).split('/');
+            // an unmatched wildcard gates nothing; a matched one gates its own
+            // depth, and a file deeper than that would go ungated either way
+            const gatedTo = match ? prefix.length + 1 : prefix.length;
+            if (table.some(route => coversUnder(route.path, prefix, gatedTo))) throw channelError('app_channel_wildcard_gated', 403);
+        }
+        return match ? { params: match.params, file: match.route } : 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);
+                // the same per-user bucket as send(), spent before anything else, as on the server
+                if (!takeSendToken(devUser.username)) throw channelError('app_channel_rate_limited', 429);
+                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 });
+        }
+    };
+}