grilling-workbench 0.2.0

package/src/runtime.js

@@ -0,0 +1,59 @@
+import { readFile, rm } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { randomBytes, randomUUID } from 'node:crypto';
+import { once } from 'node:events';
+import { createWorkbenchServer } from './server.js';
+import { createSubmissionSocket } from './submission-socket.js';
+import { acquireLock, atomicWrite } from './storage.js';
+
+export function validPort(value) {
+  if (!Number.isInteger(value) || value < 0 || value > 65535) throw new Error('Ports must be integers from 0 to 65535 (0 chooses a free port).');
+  return value;
+}
+
+export async function readRuntime(dataDir) {
+  let info;
+  try { info = JSON.parse(await readFile(join(dataDir, 'runtime.json'), 'utf8')); }
+  catch { throw new Error('No readable running-session descriptor. Start serve for this session first.'); }
+  if (info.protocolVersion !== 1 || info.dataDir !== resolve(dataDir) || typeof info.instanceId !== 'string' || typeof info.token !== 'string' || !/^[a-f0-9]{64}$/.test(info.token)
+    || !Number.isInteger(info.signalPort) || info.signalPort < 1 || info.signalPort > 65535
+    || !Number.isInteger(info.port) || info.port < 1 || info.port > 65535
+    || info.url !== `http://127.0.0.1:${info.port}/`) throw new Error('Invalid running-session descriptor. Restart this session.');
+  return info;
+}
+
+export async function startWorkbench({ dataDir, questionsPath, port = 0, signalPort = 0 }) {
+  validPort(port); validPort(signalPort);
+  dataDir = resolve(dataDir);
+  const release = await acquireLock(join(dataDir, 'server.lock'));
+  const server = createWorkbenchServer({ dataDir, questionsPath });
+  server.instanceId = randomUUID();
+  const token = randomBytes(32).toString('hex');
+  const signals = createSubmissionSocket(server, { dataDir, token });
+  let closing;
+  const close = () => closing ||= (async () => {
+    signals.closeClients();
+    if (signals.listening) await new Promise(resolve => signals.close(resolve));
+    if (server.listening) await new Promise(resolve => server.close(resolve));
+    await server.drain();
+    await rm(join(dataDir, 'runtime.json'), { force: true });
+    await release();
+  })();
+  try {
+    await server.prepare();
+    signals.listen(signalPort, '127.0.0.1'); await once(signals, 'listening');
+    server.listen(port, '127.0.0.1'); await once(server, 'listening');
+    const info = { protocolVersion: 1, instanceId: server.instanceId, pid: process.pid, dataDir, port: server.address().port, signalPort: signals.address().port, url: `http://127.0.0.1:${server.address().port}/`, token };
+    await atomicWrite(join(dataDir, 'runtime.json'), `${JSON.stringify(info, null, 2)}\n`);
+    return { server, signals, info, close };
+  } catch (error) { await close(); throw error; }
+}
+
+export function handleShutdown(running) {
+  const shutdown = () => { void running.close().catch(error => { console.error(error.message); process.exitCode = 1; }); };
+  process.once('SIGINT', shutdown);
+  process.once('SIGTERM', shutdown);
+  for (const server of [running.server, running.signals]) server.on('error', error => {
+    console.error(error.message); process.exitCode = 1; shutdown();
+  });
+}

package/src/server.js

@@ -0,0 +1,110 @@
+import http from 'node:http';
+import { readFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { initialState, restoreState, transition, validateQuestionnaire } from './core.js';
+import { atomicWrite } from './storage.js';
+import { readReceipts } from './delivery.js';
+export { atomicWrite } from './storage.js';
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const publicFiles = { '/': ['public/index.html', 'text/html'], '/app.js': ['public/app.js', 'text/javascript'], '/styles.css': ['public/styles.css', 'text/css'], '/core.js': ['src/core.js', 'text/javascript'] };
+
+export function createWorkbenchServer({ dataDir = join(root, '.workbench'), questionsPath = join(root, 'data/questions.json'), write = atomicWrite } = {}) {
+  const statePath = join(dataDir, 'session.json');
+  let saved;
+  let queue = Promise.resolve();
+  const serial = fn => {
+    const next = queue.then(fn);
+    queue = next.catch(() => {});
+    return next;
+  };
+  async function commit(next) {
+    const previousIds = new Set(saved?.state.submissions.map(s => s.id));
+    try { await write(statePath, `${JSON.stringify(next, null, 2)}\n`); }
+    catch { throw new Error('The form could not be saved on this computer. Keep the page open and retry.'); }
+    saved = next;
+    for (const submission of saved.state.submissions) {
+      if (!previousIds.has(submission.id)) server.emit('submission', structuredClone(submission));
+    }
+    return saved;
+  }
+  async function load() {
+    let doc;
+    try { doc = validateQuestionnaire(JSON.parse(await readFile(questionsPath, 'utf8'))); }
+    catch { throw new Error('Question definitions could not be loaded. Ask the agent to check the question file, then retry. Saved answers have been kept.'); }
+    if (!saved) {
+      let raw;
+      try { raw = JSON.parse(await readFile(statePath, 'utf8')); }
+      catch (error) { if (error.code !== 'ENOENT') throw new Error('Saved work could not be read. The file has been kept; restore a valid backup to continue.'); }
+      if (raw) {
+        if (!Number.isSafeInteger(raw.version) || raw.version < 1 || !Array.isArray(raw.operations) || !raw.operations.every(id => typeof id === 'string')) throw new Error('Saved work has an unsupported format. The file has been kept.');
+        saved = { version: raw.version, operations: raw.operations, state: restoreState(raw.state) };
+      } else await commit({ version: 1, operations: [], state: initialState(doc) });
+    }
+    const state = transition(saved.state, { type: 'definitions', questionnaire: doc });
+    if (state !== saved.state) await commit({ ...saved, version: saved.version + 1, state });
+    return saved;
+  }
+  const envelope = value => ({ version: value.version, state: value.state });
+  function respond(res, status, body) {
+    res.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store' });
+    res.end(JSON.stringify(body));
+  }
+  async function readBody(req) {
+    if (req.headers['content-type'] !== 'application/json') throw Object.assign(new Error('JSON is required.'), { status: 415 });
+    let body = '';
+    for await (const chunk of req) {
+      body += chunk;
+      if (Buffer.byteLength(body) > 2_000_000) throw Object.assign(new Error('This update is too large.'), { status: 413 });
+    }
+    try { return JSON.parse(body); } catch { throw Object.assign(new Error('Invalid JSON.'), { status: 400 }); }
+  }
+  const server = http.createServer(async (req, res) => {
+    res.setHeader('X-Content-Type-Options', 'nosniff');
+    res.setHeader('Content-Security-Policy', "default-src 'self'; script-src 'self'; style-src 'self'; connect-src 'self'; img-src 'self' data:; frame-ancestors 'none'; base-uri 'none'; form-action 'none'");
+    const host = req.headers.host || '';
+    if (!/^(127\.0\.0\.1|localhost):\d+$/.test(host) || (req.headers.origin && req.headers.origin !== `http://${host}`)) return respond(res, 403, { error: 'This workbench accepts requests from its own local page only.' });
+    const path = new URL(req.url, `http://${host}`).pathname;
+    try {
+      if (path === '/api/health' && req.method === 'GET') {
+        await serial(load);
+        return respond(res, 200, { status: 'ok', instanceId: server.instanceId ?? null });
+      }
+      if (path === '/api/delivery' && req.method === 'GET') return respond(res, 200, await readReceipts(dataDir));
+      if (path === '/api/session' && req.method === 'GET') return respond(res, 200, envelope(await serial(load)));
+      if (path === '/api/actions' && req.method === 'POST') {
+        const input = await readBody(req);
+        const result = await serial(async () => {
+          await load();
+          if (!input || typeof input.requestId !== 'string' || input.requestId.length > 100 || !input.requestId.length) throw Object.assign(new Error('A request ID is required.'), { status: 400 });
+          if (saved.operations.includes(input.requestId)) return envelope(saved);
+          // A lost submission response can be retried even after another save.
+          if (input.action?.type === 'submit' && saved.state.submissions.some(s => s.id === input.action.review?.id)) {
+            transition(saved.state, input.action);
+            return envelope(saved);
+          }
+          if (input.version !== saved.version) throw Object.assign(new Error('The saved form changed in another tab or the questions were updated. Your unsaved work is still available here.'), { status: 409, current: envelope(saved) });
+          if (!['edit', 'defer', 'adopt', 'submit'].includes(input.action?.type)) throw Object.assign(new Error('Unsupported form action.'), { status: 400 });
+          let state;
+          try { state = transition(saved.state, input.action); }
+          catch (error) { throw Object.assign(error, { status: 422 }); }
+          return envelope(await commit({ version: saved.version + 1, operations: [...saved.operations, input.requestId].slice(-100), state }));
+        });
+        return respond(res, 200, result);
+      }
+      if (req.method === 'GET' && publicFiles[path]) {
+        const [file, type] = publicFiles[path];
+        const body = await readFile(join(root, file));
+        res.writeHead(200, { 'Content-Type': `${type}; charset=utf-8`, 'Cache-Control': 'no-store' });
+        return res.end(body);
+      }
+      respond(res, 404, { error: 'Not found.' });
+    } catch (error) {
+      respond(res, error.status || 500, { error: error.status ? error.message : `Could not load or save the form. ${error.message}`, ...(error.current ? { current: error.current } : {}) });
+    }
+  });
+  server.prepare = () => serial(load);
+  server.drain = () => queue;
+  return server;
+}

package/src/storage.js

@@ -0,0 +1,35 @@
+import { mkdir, open, rename, rm } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+export async function atomicWrite(path, text) {
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  let handle;
+  try {
+    handle = await open(temporary, 'wx', 0o600);
+    await handle.writeFile(text);
+    await handle.sync();
+    await handle.close();
+    handle = undefined;
+    await rename(temporary, path);
+  } finally {
+    if (handle) await handle.close();
+    await rm(temporary, { force: true });
+  }
+}
+
+// Never steal a lock: a reused PID or slow writer must not lose ownership.
+export async function acquireLock(path) {
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  let handle;
+  try { handle = await open(path, 'wx', 0o600); }
+  catch (error) {
+    if (error.code === 'EEXIST') throw new Error(`Session is locked: ${path}. Stop its owner before recovery; see the deployment guide.`);
+    throw error;
+  }
+  try { await handle.writeFile(JSON.stringify({ pid: process.pid, startedAt: new Date().toISOString() })); }
+  catch (error) { await handle.close(); await rm(path, { force: true }); throw error; }
+  await handle.close();
+  return () => rm(path, { force: true });
+}

package/src/submission-socket.js

@@ -0,0 +1,87 @@
+import net from 'node:net';
+import { pendingSubmissions } from './delivery.js';
+
+// One newline-delimited JSON event per saved form. No interval or polling.
+export function createSubmissionSocket(workbench, { dataDir, token } = {}) {
+  const clients = new Set();
+  const socketServer = net.createServer(socket => {
+    clients.add(socket);
+    const sent = new Set();
+    const send = submission => {
+      if (socket.destroyed || sent.has(submission.id)) return;
+      sent.add(submission.id);
+      socket.write(`${JSON.stringify({ type: 'submission', submission })}\n`);
+    };
+    socket.on('error', () => socket.destroy());
+    socket.on('close', () => { clients.delete(socket); workbench.off('submission', send); });
+    function subscribe() {
+      // Subscribe before replay so a submission cannot fall between the two.
+      workbench.on('submission', send);
+      void pendingSubmissions(dataDir).then(submissions => {
+        if (socket.destroyed) return;
+        for (const submission of submissions) send(submission);
+        socket.write(`${JSON.stringify({ type: 'ready' })}\n`);
+      }).catch(() => {
+        socket.end(`${JSON.stringify({ type: 'error', error: 'Saved submissions could not be read. They have been retained.' })}\n`);
+      });
+    }
+    if (!token) subscribe(); // Compatibility for direct library users.
+    else {
+      let input = '';
+      const timer = setTimeout(() => socket.destroy(), 5000);
+      timer.unref();
+      socket.on('close', () => clearTimeout(timer));
+      const authenticate = chunk => {
+        input += chunk;
+        if (input.length > 4096) return socket.destroy();
+        const newline = input.indexOf('\n');
+        if (newline < 0) return;
+        socket.off('data', authenticate);
+        clearTimeout(timer);
+        let request;
+        try { request = JSON.parse(input.slice(0, newline)); } catch { return socket.destroy(); }
+        if (request.type !== 'subscribe' || request.protocolVersion !== 1 || request.token !== token) {
+          return socket.end(`${JSON.stringify({ type: 'error', error: 'Wrong session or unsupported socket protocol. Restart the listener with the current session.' })}\n`);
+        }
+        subscribe();
+      };
+      socket.setEncoding('utf8');
+      socket.on('data', authenticate);
+    }
+  });
+  socketServer.closeClients = () => { for (const socket of clients) socket.destroy(); };
+  workbench.on('close', () => { socketServer.closeClients(); if (socketServer.listening) socketServer.close(); });
+  return socketServer;
+}
+
+export function waitForSubmission({ port = 4311, host = '127.0.0.1', signal, token, onReady = () => {} } = {}) {
+  if (!['127.0.0.1', 'localhost'].includes(host)) throw new Error('The submission listener must be local.');
+  return new Promise((resolve, reject) => {
+    const socket = net.createConnection({ port, host, signal });
+    if (token) socket.on('connect', () => socket.write(`${JSON.stringify({ type: 'subscribe', protocolVersion: 1, token })}\n`));
+    let buffer = '', settled = false;
+    const finish = (error, submission) => {
+      if (settled) return;
+      settled = true;
+      socket.destroy();
+      if (error) reject(error); else resolve(submission);
+    };
+    socket.setEncoding('utf8');
+    socket.on('data', chunk => {
+      buffer += chunk;
+      if (buffer.length > 20_000_000) return finish(new Error('The submission event is too large. The saved form is retained.'));
+      let newline;
+      while (!settled && (newline = buffer.indexOf('\n')) >= 0) {
+        const line = buffer.slice(0, newline); buffer = buffer.slice(newline + 1);
+        try {
+          const event = JSON.parse(line);
+          if (event.type === 'submission' && event.submission?.id) finish(null, event.submission);
+          else if (event.type === 'ready') onReady();
+          else if (event.type === 'error') finish(new Error(event.error));
+        } catch (error) { finish(error); }
+      }
+    });
+    socket.on('error', error => finish(error));
+    socket.on('close', () => finish(new Error('The submission socket disconnected. Reconnect to receive the saved form.')));
+  });
+}