@milpa/comal 0.2.3 → 0.2.5

package/src/qr-scan.mjs

@@ -0,0 +1,240 @@
+// /rc device scan: reads the M5Stack's pairing QR with a local camera, only while the person asked for it, 30 s at most
+// in total (finding the camera included). One ffmpeg stays open for the scan (so focus and exposure settle) and writes
+// 2 frames a second into a private 0700 directory; each completed frame is decoded with zbarimg and deleted right
+// after, and the directory goes at the end (and on process exit). Nothing is kept and nothing leaves this machine.
+// Processes are spawned with argv arrays (no shell). `spawn`, `now`, `sleep`, `readdir` (of /dev) and `tmpRoot` are
+// injectable so tests run without a camera.
+import { spawn as nodeSpawn } from 'node:child_process';
+import { rmSync } from 'node:fs';
+import { chmod, lstat, mkdtemp, readdir as fsReaddir, rm } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { t, registerMessages } from './i18n/index.mjs';
+
+/** The QR on the device's pairing screen: this prefix plus the code as shown, uppercase Crockford XXXX-XXXX.
+ * It carries nothing secret (the device's poll token never goes in it). Same constant as
+ * devices/m5stack/lib/comal_core/pairing.h (PAIR_QR_PREFIX). */
+export const PAIR_QR_PREFIX = 'comal-pair:v1:';
+const PAIR_QR = /^comal-pair:v1:([0-9A-HJKMNP-TV-Z]{4}-[0-9A-HJKMNP-TV-Z]{4})$/;
+const CAMERA = /^\/dev\/video[0-9]+$/;
+export const SCAN_TIMEOUT_MS = 30000;
+export const SCAN_INTERVAL_MS = 250;  // how often the private directory is looked at for completed frames
+const STREAM_SIZE = '1280x720';
+const STREAM_FPS = 2;
+const PROBE_TIMEOUT_MS = 5000;
+const GRAB_TIMEOUT_MS = 10000;
+const FRAME_MAX_BYTES = 32 * 1024 * 1024;
+const FRAME = /^f[0-9]{6}\.png$/;
+const DIR_PREFIX = 'comal-qr-';
+const DIR_SHAPE = /^comal-qr-[A-Za-z0-9]{6}$/;  // what mkdtemp makes of DIR_PREFIX: only these are swept
+const STALE_MS = 120000;  // a scan touches its directory every half second; one untouched for 2 min is left over
+
+registerMessages({
+  'The camera must be a /dev/videoN device.': 'La cámara debe ser un dispositivo /dev/videoN.',
+  'COMAL_CAMERA must be a /dev/videoN device.': 'COMAL_CAMERA debe ser un dispositivo /dev/videoN.',
+  'No camera found (/dev/video*). Pass one with /rc device scan /dev/videoN, or type the code: /rc device XXXX-XXXX.': 'No se encontró una cámara (/dev/video*). Indica una con /rc device scan /dev/videoN, o escribe el código: /rc device XXXX-XXXX.',
+  'Scanning needs ffmpeg and zbarimg. Install the ffmpeg and zbar packages, or type the code: /rc device XXXX-XXXX.': 'Escanear necesita ffmpeg y zbarimg. Instala los paquetes ffmpeg y zbar, o escribe el código: /rc device XXXX-XXXX.',
+  'Could not read the camera {camera}: {reason}': 'No se pudo leer la cámara {camera}: {reason}',
+  'No pairing QR seen in {seconds} s. Bring the M5Stack 10-20 cm from the camera, so the QR fills about a third of the picture, and try again, or type the code: /rc device XXXX-XXXX.': 'No se vio un QR de emparejamiento en {seconds} s. Acerca el M5Stack a 10-20 cm de la cámara, que el QR ocupe un tercio de la imagen, e inténtalo de nuevo, o escribe el código: /rc device XXXX-XXXX.',
+  'QR scan cancelled; the camera is off.': 'Escaneo del QR cancelado; la cámara está apagada.',
+});
+
+/** zbarimg's stdout counts only when it is exactly one symbol: one matching line plus its newline. */
+function onlyPairCode(stdout) {
+  const text = stdout.toString('utf8').replace(/\r?\n$/, '');
+  return /[\r\n]/.test(text) ? null : pairCodeFromQr(text);
+}
+
+/** The code in a pairing QR's text, or null for anything else (which is never echoed). */
+export function pairCodeFromQr(text) {
+  const match = PAIR_QR.exec(typeof text === 'string' ? text : '');
+  return match ? match[1] : null;
+}
+
+export const isCameraPath = value => typeof value === 'string' && CAMERA.test(value);
+
+const failure = (code, message) => Object.assign(new Error(message), { code });
+const aborted = () => Object.assign(new Error(t('QR scan cancelled; the camera is off.')), { name: 'AbortError', code: 'ABORT_ERR' });
+const missingTools = () => failure('QR_SCAN_TOOLS', t('Scanning needs ffmpeg and zbarimg. Install the ffmpeg and zbar packages, or type the code: /rc device XXXX-XXXX.'));
+const timedOut = seconds => failure('QR_SCAN_TIMEOUT', t('No pairing QR seen in {seconds} s. Bring the M5Stack 10-20 cm from the camera, so the QR fills about a third of the picture, and try again, or type the code: /rc device XXXX-XXXX.', { seconds: String(seconds) }));
+const oneLine = text => String(text || '').split(/\r?\n/).map(line => line.trim()).find(Boolean)?.replace(/[\u0000-\u001f\u007f-\u009f]/g, '').slice(0, 200) || 'no frame';
+
+/** Runs one process to its end: {code, stdout, stderr}. Killed on abort or after `timeoutMs`; ENOENT → missing tools. */
+function run(spawn, cmd, args, { signal, timeoutMs = GRAB_TIMEOUT_MS } = {}) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) { reject(aborted()); return; }
+    let child;
+    try { child = spawn(cmd, args, { stdio: ['ignore', 'pipe', 'pipe'], shell: false }); }
+    catch (error) { reject(error.code === 'ENOENT' ? missingTools() : error); return; }
+    const out = [], err = [];
+    let size = 0, errSize = 0, settled = false;
+    const settle = (fn, value) => { if (settled) return; settled = true; clearTimeout(timer); signal?.removeEventListener('abort', onAbort); fn(value); };
+    const kill = () => { try { child.kill('SIGKILL'); } catch {} };
+    const onAbort = () => { kill(); settle(reject, aborted()); };
+    const timer = setTimeout(() => { kill(); settle(resolve, { code: null, stdout: Buffer.alloc(0), stderr: 'timed out' }); }, timeoutMs);
+    timer.unref?.();
+    signal?.addEventListener('abort', onAbort, { once: true });
+    child.stdout?.on('data', chunk => { size += chunk.length; if (size > FRAME_MAX_BYTES) { kill(); settle(resolve, { code: null, stdout: Buffer.alloc(0), stderr: 'frame too large' }); } else out.push(chunk); });
+    child.stderr?.on('data', chunk => { if (errSize < 4096) { err.push(chunk); errSize += chunk.length; } });
+    child.on('error', error => settle(reject, error.code === 'ENOENT' ? missingTools() : error));
+    child.on('close', code => settle(resolve, { code, stdout: Buffer.concat(out), stderr: Buffer.concat(err).toString('utf8') }));
+  });
+}
+
+const grabArgs = device => ['-hide_banner', '-loglevel', 'error', '-f', 'v4l2', '-i', device, '-frames:v', '1', '-f', 'image2pipe', '-vcodec', 'png', '-'];
+const DECODE_ARGS = ['--raw', '-q', '-Sdisable', '-Sqrcode.enable'];
+
+/** True when `v4l2-ctl --all` says this node itself captures video (Device Caps; Capabilities is the whole device's). */
+function capturesVideo(text) {
+  const lines = String(text).split('\n');
+  const start = lines.findIndex(line => /^\s*Device Caps\s*:/.test(line));
+  if (start < 0) return false;
+  const indent = lines[start].match(/^\s*/)[0].length;
+  for (const line of lines.slice(start + 1)) {
+    if (!line.trim() || line.match(/^\s*/)[0].length <= indent) break;
+    if (/^\s*Video Capture(?: Multiplanar)?\s*$/.test(line)) return true;
+  }
+  return false;
+}
+
+/** The camera: `camera` (argument) > env COMAL_CAMERA > the first /dev/videoN that v4l2-ctl reports as Video Capture
+ * (without v4l2-ctl: the first one ffmpeg can read a frame from). Anything that is not /dev/videoN is refused. */
+export async function pickCamera({ camera, env = process.env, spawn = nodeSpawn, readdir = fsReaddir, signal, deadline = Infinity, now = Date.now, seconds = SCAN_TIMEOUT_MS / 1000 } = {}) {
+  if (camera !== undefined && camera !== null && camera !== '') {
+    if (!isCameraPath(camera)) throw failure('QR_SCAN_CAMERA_PATH', t('The camera must be a /dev/videoN device.'));
+    return camera;
+  }
+  const fromEnv = env?.COMAL_CAMERA?.trim();
+  if (fromEnv) {
+    if (!isCameraPath(fromEnv)) throw failure('QR_SCAN_CAMERA_PATH', t('COMAL_CAMERA must be a /dev/videoN device.'));
+    return fromEnv;
+  }
+  let names = [];
+  try { names = await readdir('/dev'); } catch {}
+  const candidates = names.filter(name => /^video[0-9]+$/.test(name)).sort((a, b) => Number(a.slice(5)) - Number(b.slice(5))).map(name => '/dev/' + name);
+  // Probing counts toward the scan's time: each probe gets what is left, and none starts past the deadline.
+  const left = limit => { const ms = Math.min(limit, deadline - now()); if (ms <= 0) throw timedOut(seconds); return ms; };
+  let haveV4l2 = true;
+  for (const device of candidates) {
+    if (haveV4l2) {
+      try {
+        const result = await run(spawn, 'v4l2-ctl', ['--device', device, '--all'], { signal, timeoutMs: left(PROBE_TIMEOUT_MS) });
+        if (result.code === 0 && capturesVideo(result.stdout.toString('utf8'))) return device;
+        continue;
+      } catch (error) {
+        if (error.name === 'AbortError' || error.code === 'QR_SCAN_TIMEOUT') throw error;
+        if (error.code !== 'QR_SCAN_TOOLS') continue;
+        haveV4l2 = false;
+      }
+    }
+    const result = await run(spawn, 'ffmpeg', grabArgs(device), { signal, timeoutMs: left(GRAB_TIMEOUT_MS) });
+    if (result.code === 0 && result.stdout.length) return device;
+  }
+  throw failure('QR_SCAN_NO_CAMERA', t('No camera found (/dev/video*). Pass one with /rc device scan /dev/videoN, or type the code: /rc device XXXX-XXXX.'));
+}
+
+const abortableSleep = (ms, signal) => new Promise((resolve, reject) => {
+  if (signal?.aborted) { reject(aborted()); return; }
+  const timer = setTimeout(() => { signal?.removeEventListener('abort', onAbort); resolve(); }, ms);
+  const onAbort = () => { clearTimeout(timer); reject(aborted()); };
+  signal?.addEventListener('abort', onAbort, { once: true });
+});
+
+// How the camera is opened, in order, each tried when the one before ends without a frame: 1280x720 MJPEG (a UVC
+// camera often has 1280x720 only as MJPEG and silently gives 640x480 raw frames for a bare -video_size), 1280x720 in
+// its default format, then its own default size.
+const STREAM_ATTEMPTS = [['-input_format', 'mjpeg', '-video_size', STREAM_SIZE], ['-video_size', STREAM_SIZE], []];
+// `-t` (an input option) is the seconds left to the scan, rounded up: if Comal dies without its exit hook (SIGKILL, OOM,
+// a crash) ffmpeg still ends itself, and turns the camera off, at the scan's deadline.
+const streamArgs = (device, dir, attempt, seconds) => ['-hide_banner', '-loglevel', 'error', '-f', 'v4l2', ...STREAM_ATTEMPTS[attempt], '-t', String(seconds), '-i', device, '-vf', `fps=${STREAM_FPS}`, '-f', 'image2', path.join(dir, 'f%06d.png')];
+
+/** The long-running ffmpeg of a scan: {child, exited, error, stderr, closed}. */
+function startStream(spawn, args) {
+  const stream = { child: null, exited: false, error: null, stderr: '' };
+  stream.closed = new Promise(resolve => {
+    try { stream.child = spawn('ffmpeg', args, { stdio: ['ignore', 'ignore', 'pipe'], shell: false }); }
+    catch (error) { stream.exited = true; stream.error = error; resolve(); return; }
+    stream.child.stderr?.on('data', chunk => { if (stream.stderr.length < 4096) stream.stderr += chunk.toString('utf8'); });
+    stream.child.on('error', error => { stream.error = error; stream.exited = true; resolve(); });
+    stream.child.on('close', () => { stream.exited = true; resolve(); });
+  });
+  return stream;
+}
+/** Kills a stream and waits (briefly) until it is gone, so nothing writes into the directory being removed. */
+async function stopStream(stream) {
+  if (!stream || stream.exited) return;
+  try { stream.child.kill('SIGKILL'); } catch {}
+  let timer;
+  await Promise.race([stream.closed, new Promise(resolve => { timer = setTimeout(resolve, 2000); timer.unref?.(); })]);
+  clearTimeout(timer);
+}
+
+/** Removes this user's own comal-qr-* directories in `root` that no scan has touched for a while (a killed process). */
+async function sweepStale(root) {
+  let names = [];
+  try { names = await fsReaddir(root); } catch { return; }
+  const uid = process.getuid?.();
+  for (const name of names) {
+    if (!DIR_SHAPE.test(name)) continue;
+    try {
+      const info = await lstat(path.join(root, name));
+      if (!info.isDirectory() || (uid !== undefined && info.uid !== uid) || Date.now() - info.mtimeMs < STALE_MS) continue;
+      await rm(path.join(root, name), { recursive: true, force: true });
+    } catch {}
+  }
+}
+
+/** Scans for the pairing QR for up to `timeoutMs` in total, finding the camera included. Resolves {code, camera}. */
+export async function scanPairingQr({ camera, env = process.env, timeoutMs = SCAN_TIMEOUT_MS, intervalMs = SCAN_INTERVAL_MS, signal, spawn = nodeSpawn, now = Date.now, sleep, readdir = fsReaddir, tmpRoot = os.tmpdir() } = {}) {
+  if (signal?.aborted) throw aborted();
+  const deadline = now() + timeoutMs, seconds = Math.round(timeoutMs / 1000);
+  const left = limit => { const ms = Math.min(limit, deadline - now()); if (ms <= 0) throw timedOut(seconds); return ms; };
+  const pause = sleep ?? (ms => abortableSleep(ms, signal));
+  // Both tools are checked before the camera turns on.
+  for (const [cmd, args] of [['ffmpeg', ['-hide_banner', '-version']], ['zbarimg', ['--version']]]) await run(spawn, cmd, args, { signal, timeoutMs: left(PROBE_TIMEOUT_MS) });
+  const root = path.resolve(tmpRoot);
+  await sweepStale(root);
+  const dir = await mkdtemp(path.join(root, DIR_PREFIX));
+  let stream = null;
+  const onExit = () => { try { stream?.child?.kill('SIGKILL'); } catch {} try { rmSync(dir, { recursive: true, force: true }); } catch {} };
+  process.once('exit', onExit);
+  try {
+    await chmod(dir, 0o700);
+    const device = await pickCamera({ camera, env, spawn, readdir, signal, deadline, now, seconds });
+    left(1);
+    let attempt = 0, seen = 0;
+    const secondsLeft = () => Math.max(1, Math.ceil((deadline - now()) / 1000));
+    stream = startStream(spawn, streamArgs(device, dir, attempt, secondsLeft()));
+    for (;;) {
+      await pause(Math.max(0, Math.min(intervalMs, deadline - now())));
+      if (signal?.aborted) throw aborted();
+      // Read whether ffmpeg ended BEFORE listing: then every listed frame is complete. While it runs, the newest frame
+      // may still be being written, so only the ones older than it are complete. Of those only the newest is decoded:
+      // older ones are deleted unread, so a slow decode never builds a backlog of stale frames.
+      const ended = stream.exited;
+      const frames = (await fsReaddir(dir)).filter(name => FRAME.test(name)).sort();
+      const complete = ended ? frames : frames.slice(0, -1);
+      if (complete.length) {
+        seen += complete.length;
+        for (const name of complete.slice(0, -1)) await rm(path.join(dir, name), { force: true });
+        const file = path.join(dir, complete.at(-1));
+        let decoded;
+        try { decoded = await run(spawn, 'zbarimg', [...DECODE_ARGS, file], { signal, timeoutMs: Math.max(1, Math.min(PROBE_TIMEOUT_MS, deadline - now())) }); }
+        finally { await rm(file, { force: true }); }
+        const code = decoded.code === 0 ? onlyPairCode(decoded.stdout) : null;
+        if (code) return { code, camera: device };
+      }
+      if (ended && !frames.length) {
+        if (stream.error) throw stream.error.code === 'ENOENT' ? missingTools() : stream.error;
+        // A camera that refuses a format or size is opened again the next way, down to its own default.
+        if (!seen && attempt + 1 < STREAM_ATTEMPTS.length) { attempt += 1; left(1); stream = startStream(spawn, streamArgs(device, dir, attempt, secondsLeft())); continue; }
+        throw failure('QR_SCAN_CAMERA', t('Could not read the camera {camera}: {reason}', { camera: device, reason: oneLine(stream.stderr) }));
+      }
+      if (now() >= deadline) throw timedOut(seconds);
+    }
+  } finally {
+    await stopStream(stream);
+    await rm(dir, { recursive: true, force: true });
+    process.removeListener('exit', onExit);
+  }
+}

package/src/relay/broker.mjs

@@ -9,6 +9,19 @@ import { RELAY_ANSWERS } from '../remote-relay.mjs';
 // intento (otra superficie, un control repetido o viejo) responde already_decided sin mutar.
 // Hace falta en Comal porque relayd admite rechazar un plan ya aprobado y aún no aplicado.
 registerMessages({
+  'Open /rc first, with a Comal backend that supports devices.': 'Abre /rc primero, con un backend de Comal que admita dispositivos.',
+  'Device: {label} ({id}){connected}.': 'Dispositivo: {label} ({id}){connected}.',
+  ', connected {time}': ', conectado {time}',
+  'No device paired.': 'Ningún dispositivo emparejado.',
+  'Device removed; its permission answers are off.': 'Dispositivo quitado; sus respuestas de permisos quedan apagadas.',
+  'Permission answers from the M5Stack: armed until {time}.': 'Respuestas de permisos desde el M5Stack: armadas hasta las {time}.',
+  'Permission answers from the M5Stack: off.': 'Respuestas de permisos desde el M5Stack: apagadas.',
+  'Pair a device first with /rc device CODE.': 'Empareja un dispositivo primero con /rc device CODE.',
+  'The /rc session has expired; open /rc again.': 'La sesión de /rc caducó; abre /rc de nuevo.',
+  'M5Stack permission answers are armed until {time}. Each card\'s command or path goes through comal.milpahq.com to the device and is not stored.': 'Permisos desde el M5Stack activos hasta {time}. El comando o la ruta de cada tarjeta pasa por comal.milpahq.com hacia el aparato y no se guarda.',
+  'Device paired: {label} ({id}).': 'Dispositivo emparejado: {label} ({id}).',
+  'Answered on the M5Stack: {decision} · {tool}': 'Contestada en el M5Stack: {decision} · {tool}',
+  'allowed once': 'permitida una vez', 'denied': 'negada',
   '{what} was decided from the browser ({outcome}).': '{what} se decidió desde el navegador ({outcome}).',
   'Already decided from the browser ({outcome}); nothing was sent.': 'Ya decidida desde el navegador ({outcome}); no se envió nada.',
   'This card is being decided in this terminal right now.': 'Esta tarjeta se está decidiendo ahora mismo en esta terminal.',