@mmmbuto/nexuscrew 0.8.39 → 0.8.41

package/lib/audio/queue.js

@@ -0,0 +1,191 @@
+'use strict';
+// lib/audio/queue.js — coda degli enunciati di UN nodo.
+//
+// Un nodo ha una voce sola: gli enunciati si serializzano, non si sovrappongono.
+// La coda e' bounded, deduplica per utteranceId, applica la prelazione di
+// urgency alta e possiede il watchdog dell'ack di avvio.
+//
+// Transizioni di stato, tutte osservabili via `onStatus` e tutte oneste:
+//   accepted -> spoken    l'adapter ha AVVIATO la sintesi (non "qualcuno ha sentito")
+//   accepted -> refused   reason `adapter-error`   l'avvio non e' riuscito
+//   accepted -> refused   reason `preempted`       prelazionato da un urgency alto
+//   accepted -> refused   reason `stopped`         stop locale o remoto
+//   accepted -> unknown   l'ack non e' arrivato entro il timeout: non si mente
+//
+// `unknown` non e' un fallimento nascosto: e' l'ammissione che il nodo non puo'
+// dire cosa sia successo. Un fan-out o un failover devono poterlo distinguere da
+// un rifiuto esplicito, altrimenti riprovano dove non serve o si fermano dove
+// invece dovrebbero riprovare.
+const ACK_TIMEOUT_MS = 5000;
+const MAX_PENDING = 2;
+
+function createSpeakQueue(opts = {}) {
+  const adapter = opts.adapter || null;
+  const onStatus = typeof opts.onStatus === 'function' ? opts.onStatus : () => {};
+  const ackTimeoutMs = Number.isFinite(opts.ackTimeoutMs) ? opts.ackTimeoutMs : ACK_TIMEOUT_MS;
+  const maxPending = Number.isInteger(opts.maxPending) && opts.maxPending > 0 ? opts.maxPending : MAX_PENDING;
+  const setTimeoutImpl = opts.setTimeoutImpl || setTimeout;
+  const clearTimeoutImpl = opts.clearTimeoutImpl || clearTimeout;
+
+  const pending = []; // enunciati in attesa, in ordine
+  let current = null; // { utteranceId, handle, ackTimer }
+  const known = new Set(); // utteranceId gia' visti: dedup finche' sono vivi
+
+  // `spoken` e' un ACK, non una conclusione: l'enunciato e' partito e puo'
+  // ancora essere fermato o prelazionato. Confondere le due cose renderebbe
+  // impossibile registrare uno stop dopo l'avvio, che e' proprio il caso d'uso.
+  function ack(entry) {
+    if (entry.finished) return;
+    entry.acked = true;
+    if (entry.ackTimer) { clearTimeoutImpl(entry.ackTimer); entry.ackTimer = null; }
+    onStatus(entry.utteranceId, 'spoken');
+  }
+
+  // Stato terminale: emette la transizione finale e libera il dedup.
+  function settle(entry, status, reason) {
+    if (entry.finished) return;
+    entry.finished = true;
+    if (entry.ackTimer) { clearTimeoutImpl(entry.ackTimer); entry.ackTimer = null; }
+    known.delete(entry.utteranceId);
+    onStatus(entry.utteranceId, status, reason);
+  }
+
+  // Fine naturale dopo un ack: nessuna nuova transizione da annunciare, `spoken`
+  // resta lo stato finale. Si libera solo il dedup.
+  function complete(entry) {
+    if (entry.finished) return;
+    entry.finished = true;
+    if (entry.ackTimer) { clearTimeoutImpl(entry.ackTimer); entry.ackTimer = null; }
+    known.delete(entry.utteranceId);
+  }
+
+  function startNext() {
+    if (current || !pending.length) return;
+    const entry = pending.shift();
+    if (entry.finished) return startNext();
+    current = entry;
+    if (!adapter || typeof adapter.speak !== 'function') {
+      current = null;
+      settle(entry, 'refused', 'no-adapter');
+      return startNext();
+    }
+    let handle;
+    try {
+      handle = adapter.speak({ text: entry.text, lang: entry.lang, voice: entry.voice });
+    } catch (_) {
+      current = null;
+      settle(entry, 'refused', 'adapter-error');
+      return startNext();
+    }
+    if (!handle || handle.started !== true) {
+      current = null;
+      settle(entry, 'refused', handle && handle.reason ? handle.reason : 'adapter-error');
+      return startNext();
+    }
+    entry.handle = handle;
+    // Gli adapter nativi possono verificare lo spawn solo in modo asincrono:
+    // finche' la loro `start` Promise non attesta l'avvio, il receipt resta
+    // `accepted`. I seam legacy senza `start` mantengono il comportamento
+    // sincrono usato dai test e dagli adapter gia' affidabili.
+    const confirmStart = (result) => {
+      if (entry.finished) return;
+      if (result && result.started === true) {
+        ack(entry);
+        return;
+      }
+      if (current === entry) current = null;
+      settle(entry, 'refused', (result && result.reason) || 'adapter-start-failed');
+      startNext();
+    };
+    if (handle.start && typeof handle.start.then === 'function') {
+      handle.start.then(confirmStart, () => confirmStart({ started: false, reason: 'adapter-start-failed' }));
+    } else {
+      confirmStart({ started: true });
+    }
+    const finish = () => {
+      complete(entry);
+      if (current === entry) { current = null; startNext(); }
+    };
+    if (handle.done && typeof handle.done.then === 'function') handle.done.then(finish, finish);
+    else finish();
+    return undefined;
+  }
+
+  // enqueue(): l'ammissione e' sincrona e bounded. Ritorna sempre uno stato per
+  // endpoint, mai un booleano aggregato.
+  function enqueue({ utteranceId, text, lang = '', voice = '', urgency = 'normal' } = {}) {
+    if (typeof utteranceId !== 'string' || !utteranceId) return { status: 'refused', reason: 'invalid-utterance' };
+    if (typeof text !== 'string' || !text) return { status: 'refused', reason: 'invalid-text' };
+    // Dedup: lo stesso utteranceId non viene mai pronunciato due volte mentre e'
+    // ancora vivo. Un retry idempotente non produce una seconda voce.
+    if (known.has(utteranceId)) return { status: 'accepted', reason: 'duplicate' };
+    if (!adapter || typeof adapter.speak !== 'function') return { status: 'refused', reason: 'no-adapter' };
+
+    const entry = { utteranceId, text, lang, voice, urgency, finished: false, acked: false, handle: null, ackTimer: null };
+
+    if (urgency === 'high' && current) {
+      // Prelazione: l'enunciato corrente non diventa mai `spoken` a posteriori,
+      // transita a `refused/preempted`. La coda in attesa NON viene svuotata:
+      // urgency cambia l'ordine, non cancella il consenso altrui a essere letto.
+      const victim = current;
+      current = null;
+      try { if (victim.handle && typeof victim.handle.kill === 'function') victim.handle.kill(); } catch (_) {}
+      settle(victim, 'refused', 'preempted');
+      pending.unshift(entry);
+    } else if (pending.length >= maxPending) {
+      return { status: 'refused', reason: 'queue-full' };
+    } else if (urgency === 'high') {
+      pending.unshift(entry);
+    } else {
+      pending.push(entry);
+    }
+
+    known.add(utteranceId);
+    entry.ackTimer = setTimeoutImpl(() => {
+      // Timeout dell'ack: non si e' potuto confermare l'avvio. `unknown` e'
+      // l'unica risposta corretta; promuoverlo a spoken sarebbe una bugia.
+      const idx = pending.indexOf(entry);
+      if (idx >= 0) pending.splice(idx, 1);
+      if (current === entry) current = null;
+      settle(entry, 'unknown', 'ack-timeout');
+      startNext();
+    }, ackTimeoutMs);
+    if (entry.ackTimer && typeof entry.ackTimer.unref === 'function') entry.ackTimer.unref();
+
+    startNext();
+    return { status: 'accepted' };
+  }
+
+  // stop(): stop LOCALE sovrano. Non richiede rete, non richiede l'hub, non
+  // richiede che l'origine sia raggiungibile. Un endpoint deve poter tacere.
+  function stop(utteranceId) {
+    let acted = false;
+    if (current && (!utteranceId || current.utteranceId === utteranceId)) {
+      const victim = current;
+      current = null;
+      try { if (victim.handle && typeof victim.handle.kill === 'function') victim.handle.kill(); } catch (_) {}
+      settle(victim, 'refused', 'stopped');
+      acted = true;
+    }
+    for (let i = pending.length - 1; i >= 0; i -= 1) {
+      if (!utteranceId || pending[i].utteranceId === utteranceId) {
+        const [entry] = pending.splice(i, 1);
+        settle(entry, 'refused', 'stopped');
+        acted = true;
+      }
+    }
+    startNext();
+    return acted;
+  }
+
+  return {
+    enqueue,
+    stop,
+    stopAll: () => stop(null),
+    pendingSize: () => pending.length,
+    isBusy: () => current !== null,
+    currentId: () => (current ? current.utteranceId : null),
+  };
+}
+
+module.exports = { createSpeakQueue, ACK_TIMEOUT_MS, MAX_PENDING };

package/lib/audio/rate-limit.js

@@ -0,0 +1,71 @@
+'use strict';
+// lib/audio/rate-limit.js — budget dedicato agli enunciati, separato da quello
+// delle notifiche visuali: saturare le notifiche non deve poter zittire la voce,
+// e viceversa.
+//
+// Tre finestre scorrevoli da 60s, tutte e tre da rispettare:
+//   origin-cell   : per (nodo, cella) di origine — 6/60s verso qualunque target
+//   target-origin : per (target, nodo, cella) — 6/60s
+//   target-global : per nodo target — 12/60s sommando TUTTE le origini
+//
+// Il terzo bucket e' quello che limita il danno di un nodo che mente sulla
+// propria cella: puo' inventare nomi quanto vuole, ma il tetto per target e'
+// calcolato sul nodo, che invece e' verificato dalla catena `visited`.
+//
+// L'urgency non scavalca nulla. Un chiamante rumoroso — o compromesso — non deve
+// poter uscire dal limite semplicemente dichiarandosi urgente.
+const WINDOW_MS = 60 * 1000;
+const LIMITS = Object.freeze({ 'origin-cell': 6, 'target-origin': 6, 'target-global': 12 });
+
+// Stessa chiave dello store dei receipt: nodo + cella. Contare per sola cella
+// permetterebbe a due nodi con celle omonime di consumarsi il budget a vicenda.
+function originKey(origin) {
+  if (!origin || typeof origin !== 'object') return null;
+  const node = typeof origin.node === 'string' ? origin.node : '';
+  const cell = typeof origin.cell === 'string' ? origin.cell : '';
+  if (!node || !cell) return null;
+  return `${node} ${cell}`;
+}
+
+function createSpeakRateLimiter({ now = Date.now } = {}) {
+  const buckets = { 'origin-cell': new Map(), 'target-origin': new Map(), 'target-global': new Map() };
+
+  function prune(map, t) {
+    const cutoff = t - WINDOW_MS;
+    for (const [k, ts] of map) {
+      const kept = ts.filter((x) => x > cutoff);
+      if (kept.length === 0) map.delete(k);
+      else map.set(k, kept);
+    }
+  }
+
+  function check({ origin, target, urgency } = {}) {
+    const key = originKey(origin);
+    if (!key) throw new Error('rate-limit: origin {node,cell} mancante');
+    if (typeof target !== 'string' || !target) throw new Error('rate-limit: target mancante');
+    void urgency; // ignorata di proposito: non esiste una corsia preferenziale
+    const t = now();
+    for (const name of Object.keys(buckets)) prune(buckets[name], t);
+    const keys = {
+      'origin-cell': key,
+      'target-origin': `${target}\x00${key}`,
+      'target-global': target,
+    };
+    for (const bucket of ['origin-cell', 'target-origin', 'target-global']) {
+      const arr = buckets[bucket].get(keys[bucket]) || [];
+      if (arr.length >= LIMITS[bucket]) {
+        return { allowed: false, bucket, limit: LIMITS[bucket], retryInMs: WINDOW_MS - (t - arr[0]) };
+      }
+    }
+    for (const bucket of ['origin-cell', 'target-origin', 'target-global']) {
+      const arr = buckets[bucket].get(keys[bucket]) || [];
+      arr.push(t);
+      buckets[bucket].set(keys[bucket], arr);
+    }
+    return { allowed: true };
+  }
+
+  return { check, LIMITS, WINDOW_MS };
+}
+
+module.exports = { createSpeakRateLimiter, originKey, LIMITS, WINDOW_MS };

package/lib/audio/receipt.js

@@ -0,0 +1,146 @@
+'use strict';
+// lib/audio/receipt.js — receipt degli enunciati, bounded e ridotto all'osso.
+//
+// Scope del chiamante = NODO + CELLA. Non la sola cella: due nodi possono avere
+// celle omonime (`Dev` esiste su piu' installazioni), e una chiave basata solo
+// sul nome permetterebbe a un nodo di leggere o sovrascrivere i receipt di una
+// cella altrui con lo stesso nome. La chiave e' costruita qui, dal server, mai
+// accettata dal client.
+//
+// Cosa NON entra mai in un receipt: testo, lingua, voce, path, credenziali,
+// header. L'attribuzione e' {utteranceId, origin{node,cell}, target, stato,
+// reason, timestamp} e nient'altro. `attested` distingue una cella verificata
+// localmente dal bridge da una dichiarata da un altro nodo: la differenza e' di
+// sicurezza e non va persa per strada.
+//
+// Nessun booleano aggregato di successo: chi legge deve guardare lo stato per
+// endpoint, altrimenti "vero" finirebbe per significare "ho provato".
+const crypto = require('node:crypto');
+
+const STATUS = Object.freeze(['refused', 'unreachable', 'accepted', 'spoken', 'unknown']);
+const CAP = 512;
+const TTL_MS = 24 * 60 * 60 * 1000;
+
+// Chiave di scope: il separatore e' uno spazio, non rappresentabile in un nodeId
+// (hex) ne' in un nome cella ([A-Za-z0-9._-]), quindi non e' ambigua.
+function callerKey(origin) {
+  if (!origin || typeof origin !== 'object') return null;
+  const node = typeof origin.node === 'string' ? origin.node : '';
+  const cell = typeof origin.cell === 'string' ? origin.cell : '';
+  if (!node || !cell) return null;
+  return `${node} ${cell}`;
+}
+
+function createReceiptStore({ now = Date.now } = {}) {
+  const byId = new Map();
+
+  const expired = (e, t) => t - e.timestamp > TTL_MS;
+
+  function cleanup(t) {
+    for (const [id, e] of byId) if (expired(e, t)) byId.delete(id);
+  }
+
+  function redact(e) {
+    return {
+      utteranceId: e.utteranceId,
+      origin: { node: e.origin.node, cell: e.origin.cell, attested: e.attested === true },
+      target: e.target,
+      status: e.status,
+      timestamp: e.timestamp,
+      ...(e.reason ? { reason: e.reason } : {}),
+    };
+  }
+
+  // find(): sonda di idempotenza. Non muta. `collision` segnala che lo stesso
+  // utteranceId appartiene a un altro chiamante o a un altro target: fail-closed,
+  // perche' riusare l'id di un altro sarebbe un modo per leggerne il receipt.
+  function find(utteranceId, origin, target) {
+    if (typeof utteranceId !== 'string' || !utteranceId) return null;
+    const key = callerKey(origin);
+    const e = byId.get(utteranceId);
+    if (!e) return null;
+    if (expired(e, now())) { byId.delete(utteranceId); return null; }
+    if (!key || e.caller !== key || e.target !== target) return 'collision';
+    return redact(e);
+  }
+
+  function record(opts) {
+    if (!opts || typeof opts !== 'object') throw new Error('record: opts mancante');
+    const key = callerKey(opts.origin);
+    if (!key) throw new Error('record: origin {node,cell} mancante');
+    if (typeof opts.target !== 'string' || !opts.target) throw new Error('record: target mancante');
+    if (!STATUS.includes(opts.status)) throw new Error(`status non valida (enum: ${STATUS.join('|')})`);
+    const t = now();
+    cleanup(t);
+    const provided = typeof opts.utteranceId === 'string' && opts.utteranceId ? opts.utteranceId : null;
+    if (provided) {
+      const existing = byId.get(provided);
+      if (existing && !expired(existing, t)) {
+        if (existing.caller === key && existing.target === opts.target) return redact(existing);
+        throw new Error('utteranceId collision (diverso caller/target)');
+      }
+    }
+    const utteranceId = provided || crypto.randomUUID();
+    const entry = {
+      utteranceId,
+      caller: key,
+      origin: { node: opts.origin.node, cell: opts.origin.cell },
+      attested: opts.attested === true,
+      target: opts.target,
+      status: opts.status,
+      ...(opts.reason ? { reason: String(opts.reason).slice(0, 64) } : {}),
+      timestamp: t,
+    };
+    byId.set(utteranceId, entry);
+    if (byId.size > CAP) {
+      const sorted = [...byId.entries()].sort((a, b) => a[1].timestamp - b[1].timestamp);
+      for (let i = 0; i < byId.size - CAP; i += 1) byId.delete(sorted[i][0]);
+    }
+    return redact(entry);
+  }
+
+  // update(): transizione di stato di un enunciato gia' registrato (accepted ->
+  // spoken/refused/unknown quando la coda locale conclude). Non crea receipt
+  // nuovi e non cambia mai origine o target: solo lo stato puo' evolvere.
+  function update(utteranceId, status, reason) {
+    if (!STATUS.includes(status)) throw new Error('status non valida');
+    const e = byId.get(utteranceId);
+    if (!e) return null;
+    if (expired(e, now())) { byId.delete(utteranceId); return null; }
+    e.status = status;
+    if (reason) e.reason = String(reason).slice(0, 64);
+    else delete e.reason;
+    return redact(e);
+  }
+
+  // get(): lettura scoped. Solo lo stesso nodo+cella vede il proprio receipt;
+  // per chiunque altro l'enunciato semplicemente non esiste.
+  function get(origin, utteranceId) {
+    const key = callerKey(origin);
+    const e = byId.get(utteranceId);
+    if (!key || !e) return null;
+    if (expired(e, now())) { byId.delete(utteranceId); return null; }
+    if (e.caller !== key) return null;
+    return redact(e);
+  }
+
+  function list(origin) {
+    const key = callerKey(origin);
+    if (!key) return [];
+    const t = now();
+    const out = [];
+    for (const [, e] of byId) if (!expired(e, t) && e.caller === key) out.push(redact(e));
+    return out;
+  }
+
+  function count() {
+    const t = now();
+    let c = 0;
+    for (const [, e] of byId) if (!expired(e, t)) c += 1;
+    return c;
+  }
+
+  return { record, update, find, get, list, count, STATUS };
+}
+
+module.exports = { createReceiptStore, callerKey, STATUS, CAP, TTL_MS };