@edryslabs/edrys-dev 0.0.0-stage → 0.1.1

package/dist/modules.js

@@ -0,0 +1,130 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import express from 'express';
+/**
+ * Reports a module's uncaught errors, rejected promises and console.error to
+ * edrys-dev. Plain text without reading the answer, so the browser sends it to
+ * another origin without asking first; `name` comes from the server, since a
+ * module that edrys-Lite inlines runs on a data: URL.
+ */
+export function errorReporter(name, reportUrl) {
+    // a string literal that cannot end the script tag
+    const literal = (value) => JSON.stringify(value).replace(/</g, '\\u003c');
+    return `<script>(function () {
+  var send = function (kind, message) {
+    try {
+      // no-cors: the answer is of no use, and reading it would log a CORS error
+      fetch(${literal(reportUrl)}, {
+        method: 'POST',
+        mode: 'no-cors',
+        body: JSON.stringify({ module: ${literal(name)}, kind: kind, message: String(message).slice(0, 2000) }),
+        keepalive: true
+      }).catch(function () {})
+    } catch (e) {}
+  }
+  addEventListener('error', function (e) {
+    // a failed <img> or <script> load fires this too, without a message
+    if (e.error || e.message) send('error', (e.error && e.error.stack) || e.message)
+  })
+  addEventListener('unhandledrejection', function (e) {
+    send('error', (e.reason && e.reason.stack) || e.reason)
+  })
+  var original = console.error
+  console.error = function () {
+    send('console', [].map.call(arguments, function (a) {
+      try { return typeof a === 'string' ? a : (a && a.stack) || JSON.stringify(a) } catch (_) { return String(a) }
+    }).join(' '))
+    return original.apply(console, arguments)
+  }
+})()</script>`;
+}
+/**
+ * Runs code the class tab sends (run_in_module): only from the parent frame,
+ * and only when that is edrys-Lite served by edrys-dev (`pageOrigins`). The
+ * code is an expression, or statements whose last value is the result; with
+ * await, statements need return.
+ */
+export function runner(pageOrigins) {
+    const literal = JSON.stringify(pageOrigins).replace(/</g, '\\u003c');
+    return `<script>(function () {
+  var origins = ${literal}
+  var AsyncFunction = (async function () {}).constructor
+  var show = function (value) {
+    if (value === undefined) return 'undefined'
+    try {
+      var text = JSON.stringify(value)
+      if (text !== undefined) return text.length > 20000 ? text.slice(0, 20000) + '…' : text
+    } catch (e) {}
+    return String(value)
+  }
+  addEventListener('message', function (e) {
+    var data = e.data
+    if (e.source !== parent || origins.indexOf(e.origin) < 0 || !data || data.event !== 'dev-run') return
+    var answer = function (result) {
+      result.event = 'dev-ran'
+      result.id = data.id
+      parent.postMessage(result, e.origin)
+    }
+    var code = String(data.code).replace(/[\\s;]+$/, '')
+    var run
+    try {
+      run = new AsyncFunction('return (' + code + '\\n)')
+    } catch (e) {
+      try {
+        // statements: their last value, as in the console; with await they need return
+        run = /\\b(await|return)\\b/.test(code)
+          ? new AsyncFunction(code)
+          : function () { return Promise.resolve((0, eval)(code)) }
+      } catch (error) {
+        return answer({ error: String(error) })
+      }
+    }
+    // without the stack: for an inlined module it holds its whole data: URL
+    Promise.resolve().then(run).then(
+      function (value) { answer({ value: show(value) }) },
+      function (error) { answer({ error: String(error) }) }
+    )
+  })
+})()</script>`;
+}
+/** `script` as early in `html` as possible, before the module's own scripts. */
+export function inject(html, script) {
+    // a function, so a $ in the script is no replacement pattern
+    for (const tag of [/<head(\s[^>]*)?>/i, /<html(\s[^>]*)?>/i]) {
+        if (tag.test(html))
+            return html.replace(tag, (match) => match + script);
+    }
+    return script + html;
+}
+/**
+ * Serves local modules (`dir/<name>/...`), on a port of their own: a module on
+ * edrys-Lite's origin could read its storage, the owner's key included. Real
+ * modules always come from another origin, so these do too. HTML pages get
+ * the error reporter, which posts to `reportUrl`, and the runner, which takes
+ * code from edrys-Lite at `pageOrigins`.
+ */
+export function moduleApp(dir, reportUrl, pageOrigins) {
+    const app = express();
+    app.use((req, res, next) => {
+        // edrys-Lite fetches a module from its own origin to read its meta tags
+        res.setHeader('Access-Control-Allow-Origin', '*');
+        // a reload must get the files as they are now
+        res.setHeader('Cache-Control', 'no-store');
+        next();
+    });
+    app.get(/(\/|\.html?)$/i, async (req, res, next) => {
+        const file = path.resolve(dir, '.' + decodeURIComponent(req.path) + (req.path.endsWith('/') ? 'index.html' : ''));
+        const name = path.relative(dir, file).split(path.sep)[0];
+        if (!file.startsWith(dir + path.sep) || !name)
+            return next();
+        try {
+            const html = await fs.readFile(file, 'utf8');
+            res.type('html').send(inject(html, errorReporter(name, reportUrl) + runner(pageOrigins)));
+        }
+        catch {
+            next();
+        }
+    });
+    app.use(express.static(dir, { etag: false, lastModified: false }));
+    return app;
+}

package/dist/origin.js

@@ -0,0 +1,5 @@
+/** Requests from a page of another origin, e.g. a module's own site, are refused. */
+export function sameOrigin(req) {
+    const origin = req.headers.origin;
+    return origin === undefined || origin === `http://${req.headers.host}`;
+}

package/dist/server.js

@@ -0,0 +1,260 @@
+import crypto from 'node:crypto';
+import http from 'node:http';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { EventEmitter } from 'node:events';
+import { createRequire } from 'node:module';
+import express from 'express';
+import { unpack } from 'msgpackr';
+import { watchFile, watchModules } from './watch.js';
+import { moduleApp } from './modules.js';
+import { sameOrigin } from './origin.js';
+import { Chat, PANEL_SCRIPT } from './chat.js';
+// entries the log keeps, oldest first out
+const LOG_MAX = 300;
+// a body in the log is cut to this many characters of JSON
+const BODY_MAX = 1000;
+/**
+ * A module message body as the agent can read it: edrys.js sends bodies as
+ * base64 MessagePack, the class tab passes them on as they are.
+ */
+export function readableBody(body) {
+    let value = body;
+    if (typeof body === 'string' && body.length % 4 === 0 && /^[A-Za-z0-9+/]+={0,2}$/.test(body)) {
+        try {
+            value = unpack(Buffer.from(body, 'base64'));
+        }
+        catch { }
+    }
+    let text;
+    try {
+        text = JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        text = String(value);
+    }
+    return text.length > BODY_MAX ? text.slice(0, BODY_MAX) + '…' : text;
+}
+// A reload closes the owner tab's stream and opens a new one within a moment;
+// only a change that lasts this long counts.
+const SETTLE_MS = 2000;
+/** The built edrys-Lite this package serves. */
+export function edrysDist() {
+    const require = createRequire(import.meta.url);
+    return path.join(path.dirname(require.resolve('@edryslabs/edrys-lite/package.json')), 'dist');
+}
+/**
+ * Serves edrys-Lite with the endpoints its DevBridge talks to (see
+ * edrys-Lite src/ts/DevBridge.ts), plus a sync server with `local`, all on
+ * one port. When the port is taken, the next free one is used.
+ */
+export async function startDevServer(options) {
+    const app = express();
+    const bus = new EventEmitter();
+    const clients = new Set();
+    let share = null;
+    let classState = null;
+    const log = [];
+    let dropped = 0;
+    const addLog = (entry) => {
+        log.push(entry);
+        if (log.length > LOG_MAX)
+            log.splice(0, log.length - LOG_MAX);
+    };
+    let reported = false;
+    let settling;
+    const settle = () => {
+        clearTimeout(settling);
+        settling = setTimeout(() => {
+            const connected = clients.size > 0;
+            if (connected !== reported)
+                bus.emit('connection', (reported = connected));
+        }, SETTLE_MS);
+    };
+    app.get('/edrys-dev/lab', async (req, res) => {
+        res.json({
+            path: options.lab,
+            text: await fs.readFile(options.lab, 'utf8'),
+            // Without it the class keeps its own (or edrys-Lite's default) transport.
+            communication: options.local
+                ? { communicationMethod: 'Websocket', websocketUrl: `ws://${req.headers.host}` }
+                : undefined,
+        });
+    });
+    app.get('/edrys-dev/events', (req, res) => {
+        res.writeHead(200, {
+            'Content-Type': 'text/event-stream',
+            'Cache-Control': 'no-cache',
+            Connection: 'keep-alive',
+        });
+        res.write(': edrys-dev\n\n');
+        clients.add(res);
+        settle();
+        req.on('close', () => {
+            clients.delete(res);
+            settle();
+        });
+    });
+    // Student and station tabs have no DevBridge: they only learn that a local
+    // module changed, and load the page again. Not counted as the owner tab.
+    const others = new Set();
+    app.get('/edrys-dev/reload', (req, res) => {
+        res.writeHead(200, {
+            'Content-Type': 'text/event-stream',
+            'Cache-Control': 'no-cache',
+            Connection: 'keep-alive',
+        });
+        res.write(': edrys-dev\n\n');
+        others.add(res);
+        req.on('close', () => others.delete(res));
+    });
+    // questions to the owner tab, by id, until it replies
+    const pending = new Map();
+    // a reply carries a room's whole state
+    app.post('/edrys-dev/bridge', express.json({ limit: '2mb' }), (req, res) => {
+        if (!sameOrigin(req))
+            return res.sendStatus(403);
+        const report = req.body;
+        if (report.type === 'reply') {
+            pending.get(report.id)?.(report);
+            return res.sendStatus(204);
+        }
+        if (report.type === 'open' && typeof report.url === 'string')
+            share = report.url;
+        if (report.type === 'class') {
+            const { type, ...state } = report;
+            classState = state;
+        }
+        if (report.type === 'messages' && Array.isArray(report.messages)) {
+            for (const m of report.messages)
+                addLog({ ...m, body: readableBody(m.body), kind: 'message' });
+            dropped += Number(report.dropped) || 0;
+        }
+        bus.emit('report', report);
+        res.sendStatus(204);
+    });
+    // The error reporter of local modules (see modules.ts): from the module
+    // server's origin, or "null" for a module edrys-Lite inlined.
+    let moduleOrigins = [];
+    app.post('/edrys-dev/module-error', express.text({ type: () => true }), (req, res) => {
+        if (!moduleOrigins.includes(String(req.headers.origin)))
+            return res.sendStatus(403);
+        let error;
+        try {
+            error = JSON.parse(req.body);
+        }
+        catch {
+            return res.sendStatus(400);
+        }
+        const entry = {
+            t: Date.now(),
+            kind: 'error',
+            module: String(error.module),
+            source: error.kind === 'console' ? 'console' : 'error',
+            message: String(error.message).slice(0, 2000),
+        };
+        addLog(entry);
+        bus.emit('report', { type: 'module-error', ...entry });
+        res.sendStatus(204);
+    });
+    const chat = new Chat(path.join(path.dirname(options.lab), '.edrys-dev', 'chat.json'));
+    chat.routes(app);
+    // edrys-Lite's page, with the chat panel (it shows only in the class tab)
+    app.get(['/', '/index.html'], async (req, res) => {
+        const page = await fs.readFile(path.join(edrysDist(), 'index.html'), 'utf8');
+        res.type('html').send(page + PANEL_SCRIPT);
+    });
+    app.use(express.static(edrysDist()));
+    const server = http.createServer(app);
+    // Loaded only when used: @edryslabs/websocket-server is an optional dependency.
+    const stopSync = options.local ? (await import('./sync.js')).attachSync(server) : () => { };
+    const send = (event, data) => {
+        for (const client of clients)
+            client.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
+    };
+    const request = (event, data, ms = 5000) => new Promise((resolve, reject) => {
+        if (!clients.size)
+            return reject(new Error('the class tab is not open'));
+        const id = crypto.randomUUID();
+        const timer = setTimeout(() => {
+            pending.delete(id);
+            reject(new Error(`the class tab did not answer within ${ms / 1000} s`));
+        }, ms);
+        pending.set(id, (reply) => {
+            clearTimeout(timer);
+            pending.delete(id);
+            if (reply.error !== undefined)
+                reject(new Error(String(reply.error)));
+            else
+                resolve(reply.value);
+        });
+        send(event, { id, ...data });
+    });
+    const stopWatching = watchFile(options.lab, () => send('reload-lab', {}));
+    const port = await listen(server, options.port, options.host);
+    let modules = null;
+    let stopModules = async () => { };
+    if (options.modules) {
+        const dir = options.modules;
+        // the class tab may use either local address
+        const pageOrigins = [...new Set(['localhost', '127.0.0.1', options.host].map((host) => `http://${host}:${port}`))];
+        const moduleServer = http.createServer(moduleApp(dir, `http://localhost:${port}/edrys-dev/module-error`, pageOrigins));
+        const modulePort = await listen(moduleServer, port + 1, options.host);
+        modules = { dir, url: `http://localhost:${modulePort}/` };
+        moduleOrigins = [`http://localhost:${modulePort}`, `http://127.0.0.1:${modulePort}`, 'null'];
+        const stopWatchingModules = watchModules(dir, (name) => {
+            // the lab may name either local address
+            for (const host of ['localhost', '127.0.0.1']) {
+                send('reload-module', { url: `http://${host}:${modulePort}/${name}/` });
+            }
+            for (const other of others)
+                other.write('event: reload-module\ndata: {}\n\n');
+            bus.emit('module-changed', name);
+        });
+        stopModules = async () => {
+            await stopWatchingModules();
+            moduleServer.closeAllConnections();
+            await new Promise((resolve) => moduleServer.close(resolve));
+        };
+    }
+    return {
+        port,
+        app,
+        bus,
+        chat,
+        state: () => ({ connected: clients.size > 0, share, class: classState }),
+        send,
+        request,
+        modules,
+        log: () => ({ entries: log, dropped }),
+        async close() {
+            clearTimeout(settling);
+            await stopWatching();
+            await stopModules();
+            stopSync();
+            for (const client of [...clients, ...others])
+                client.end();
+            server.closeAllConnections();
+            await new Promise((resolve) => server.close(resolve));
+        },
+    };
+}
+async function listen(server, port, host, tries = 20) {
+    for (let next = port; next < port + tries; next++) {
+        try {
+            await new Promise((resolve, reject) => {
+                server.once('error', reject);
+                server.listen(next, host, () => {
+                    server.off('error', reject);
+                    resolve();
+                });
+            });
+            return next;
+        }
+        catch (error) {
+            if (error.code !== 'EADDRINUSE')
+                throw error;
+        }
+    }
+    throw new Error(`no free port in ${port}-${port + tries - 1}`);
+}

package/dist/sync.js

@@ -0,0 +1,15 @@
+import { WebSocketServer } from 'ws';
+import { setupWSConnection } from '@edryslabs/websocket-server/utils';
+/**
+ * Yjs sync on the dev server's own port (`--local`), as in the edrys
+ * websocket-server: every path is a doc named after it. Returns a function
+ * that shuts it down.
+ */
+export function attachSync(server) {
+    const docs = new WebSocketServer({ noServer: true });
+    docs.on('connection', setupWSConnection);
+    server.on('upgrade', (request, socket, head) => {
+        docs.handleUpgrade(request, socket, head, (ws) => docs.emit('connection', ws, request));
+    });
+    return () => docs.close();
+}

package/dist/watch.js

@@ -0,0 +1,44 @@
+import path from 'node:path';
+import { watch } from 'chokidar';
+/**
+ * Calls `onChange` once per save of `file`: editors often write a file in
+ * several steps (truncate + write, or write a copy and rename it over).
+ * Returns a function that stops watching.
+ */
+export function watchFile(file, onChange, delay = 100) {
+    let timer;
+    const watcher = watch(file, { ignoreInitial: true });
+    watcher.on('all', () => {
+        clearTimeout(timer);
+        timer = setTimeout(onChange, delay);
+    });
+    return () => {
+        clearTimeout(timer);
+        return watcher.close();
+    };
+}
+/**
+ * Calls `onChange(name)` once per save in a folder `dir/<name>/`, i.e. per
+ * module; files directly in `dir` are no module. Returns a function that
+ * stops watching.
+ */
+export function watchModules(dir, onChange, delay = 100) {
+    const timers = new Map();
+    // hidden files and node_modules below dir; dir itself may sit in a hidden folder
+    const ignored = (file) => path
+        .relative(dir, file)
+        .split(path.sep)
+        .some((part) => part.startsWith('.') || part === 'node_modules');
+    const watcher = watch(dir, { ignoreInitial: true, ignored });
+    watcher.on('all', (_event, file) => {
+        const [name, ...rest] = path.relative(dir, file).split(path.sep);
+        if (!name || !rest.length)
+            return;
+        clearTimeout(timers.get(name));
+        timers.set(name, setTimeout(() => onChange(name), delay));
+    });
+    return () => {
+        timers.forEach(clearTimeout);
+        return watcher.close();
+    };
+}

package/package.json

@@ -1,6 +1,60 @@
 {
   "name": "@edryslabs/edrys-dev",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Develop edrys-Lite labs locally: serves edrys-Lite, syncs on its own port and republishes the class whenever the lab file changes",
+  "type": "module",
+  "bin": {
+    "edrys-dev": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "views"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc --watch",
+    "test": "tsc && node --test",
+    "prepublishOnly": "rm -rf dist && tsc"
+  },
+  "keywords": [
+    "edrys",
+    "edrys-lite",
+    "remote lab",
+    "devServer"
+  ],
+  "license": "MIT",
+  "author": "edrys-labs (https://github.com/edrys-labs)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/edrys-labs/edrys-devserver.git"
+  },
+  "bugs": {
+    "url": "https://github.com/edrys-labs/edrys-devserver/issues"
+  },
+  "homepage": "https://github.com/edrys-labs/edrys-devserver#readme",
+  "dependencies": {
+    "@edryslabs/edrys-lite": "3.2.0-dev.0",
+    "chokidar": "^4.0.3",
+    "dompurify": "^3.4.17",
+    "express": "^5.1.0",
+    "marked": "^18.1.1",
+    "msgpackr": "^2.1.2",
+    "open": "^10.1.0"
+  },
+  "optionalDependencies": {
+    "@edryslabs/websocket-server": "1.1.0",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.0",
+    "@types/node": "^22.10.0",
+    "@types/ws": "^8.5.13",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}