smithtek-mako-rf 3.4.2 → 3.5.1

package/bus-engine.js

@@ -1,9 +1,12 @@
 'use strict';
 
-// Node.js 14 compatible. Exactly one worker and one serial owner per bus.
+// Smithtek Software Licence: LICENSE.txt. Node.js 14 compatible.
+// One FIFO worker and one confirmed serial owner per bus, including PPC batches.
 module.exports = function createEngine(ModbusRTU) {
   const owners = new Map();
-  const delay = ms => new Promise(resolve => setTimeout(resolve, ms));
+  // A retired serial stream can still emit a delayed error. An inert sink keeps
+  // EventEmitter from throwing without retaining any bus, node or worker state.
+  const ignoreRetiredError = () => {};
   const bounded = (v, fallback, min, max) => v != null && v !== '' && Number.isFinite(Number(v)) ? Math.min(max, Math.max(min, Number(v))) : fallback;
   const error = (message, code) => Object.assign(new Error(message), { code });
   const timeoutMs = cfg => bounded(cfg.timeout_s, 8, 1, 120) * 1000;
@@ -11,271 +14,392 @@ module.exports = function createEngine(ModbusRTU) {
 
   function create(cfg) {
     return { cfg, queue: [], active: null, worker: null, closing: false, client: null,
-      cancel: null, dirty: false, transportFault: false, lastRx: 0, failures: new Map(), closePromise: null, ownerPath: null };
+      cancel: null, dirty: false, transportFault: false, lastRx: 0, failures: new Map(),
+      closePromise: null, ownerPath: null, epoch: 0, recovering: false, recoveryPromise: null, recoveryError: null };
+  }
+  function available(state) {
+    if (state.closing) return error('Bus closing', 'ECANCELLED');
+    if (state.recovering) return error('Bus recovery in progress; request not queued', 'EBUSRECOVERING');
+    if (state.recoveryError) return error(state.recoveryError.message, 'EBUSRECOVERYFAILED');
+    return null;
+  }
+  function checkEpoch(state, epoch) {
+    if (state.closing) throw error('Bus closing', 'ECANCELLED');
+    if (state.epoch !== epoch) throw error('Bus queue reset; operation cancelled', 'EBUSRESET');
+  }
+  function checkItem(state, item) {
+    if (item.finished) throw item.failure || error('Request already completed', 'ECANCELLED');
+    if (item.node._makoClosed) throw error('Node closed', 'ECANCELLED');
+    checkEpoch(state, item.epoch);
   }
 
+  // Every deadline, pause and quiet-period timer is owned by this operation.
+  // Cancellation clears its timers; a late callback can only settle a dead promise.
   function operation(state, label, ms, start) {
     return new Promise((resolve, reject) => {
+      const epoch = state.epoch, cleanups = [];
       let finished = false;
       const finish = (err, value) => {
         if (finished) return;
-        finished = true;
-        clearTimeout(timer);
+        finished = true; clearTimeout(timer);
+        cleanups.splice(0).forEach(fn => { try { fn(); } catch (_) {} });
         if (state.cancel === cancel) state.cancel = null;
+        if (!err) { try { checkEpoch(state, epoch); } catch (e) { err = e; } }
         err ? reject(err) : resolve(value);
       };
       const cancel = err => finish(err || error('Operation cancelled', 'ECANCELLED'));
       const timer = setTimeout(() => finish(error(label + ' deadline exceeded', 'EDEADLINE')), ms);
       state.cancel = cancel;
-      if (state.closing) return cancel();
-      try { Promise.resolve(start()).then(value => finish(null, value), finish); } catch (err) { finish(err); }
+      if (state.closing) return cancel(error('Bus closing', 'ECANCELLED'));
+      const cleanup = fn => { if (finished) fn(); else cleanups.push(fn); };
+      try { Promise.resolve(start(cleanup)).then(value => finish(null, value), finish); } catch (err) { finish(err); }
     });
   }
-
+  function pause(state, label, ms) {
+    return operation(state, label, ms + 1000, cleanup => new Promise(resolve => {
+      const timer = setTimeout(resolve, ms); cleanup(() => clearTimeout(timer));
+    }));
+  }
   function callbackCall(target, method, args) {
     return new Promise((resolve, reject) => {
       try { target[method].apply(target, (args || []).concat(err => err ? reject(err) : resolve())); }
       catch (err) { reject(err); }
     });
   }
+  function clearTransactions(client) {
+    if (typeof client._cancelPendingTransactions === 'function') client._cancelPendingTransactions();
+    if (client._transactions) client._transactions = {};
+  }
+  function cleanupClient(client) {
+    if (client._makoCleanup) { client._makoCleanup(); client._makoCleanup = null; }
+    if (!client.listeners('error').includes(ignoreRetiredError)) client.on('error', ignoreRetiredError);
+  }
 
-  // Do not release ownership until the old descriptor really closed. A timed-out
-  // close blocks this port, but never blocks other physical buses or the worker.
-  async function retire(state) {
+  // A close callback alone is not proof of closure. Require closed state on the
+  // actual serial descriptor too, and never release a still-opening descriptor.
+  // A timed-out open retains a cleanup continuation ONLY to close that old port.
+  // It can never start a new worker, reopen, or declare recovery successful.
+  function retire(state) {
     const client = state.client;
-    if (!client) return;
+    if (!client) return Promise.resolve();
     if (client._makoRetiring) return client._makoRetiring;
-    client._makoRetiring = new Promise((resolve, reject) => {
-      let settled = false;
-      const finish = err => {
-        if (settled) return;
-        settled = true; clearTimeout(timer);
-        err ? reject(err) : resolve();
+    client._makoRetiring = Promise.resolve().then(() => new Promise((resolve, reject) => {
+      const leasePath = state.ownerPath;
+      let settled = false, closeStarted = false;
+      const closed = () => {
+        const port = portOf(client);
+        return !client._makoOpening && client.isOpen === false &&
+          (!port || (port.isOpen === false && !port.opening && !port.closing));
       };
       const release = () => {
+        if (!closed()) return false;
+        clearTransactions(client); cleanupClient(client);
         if (state.client === client) state.client = null;
-        if (owners.get(state.ownerPath) === state) owners.delete(state.ownerPath);
+        if (owners.get(leasePath) === state) owners.delete(leasePath);
         client._makoClosed = true;
+        return true;
+      };
+      const finish = err => {
+        if (settled) return;
+        settled = true; clearTimeout(timer);
+        client.removeListener('close', onClose);
+        err ? reject(err) : resolve();
       };
-      const timer = setTimeout(() => finish(error('Serial close deadline exceeded; port quarantined', 'ECLOSE')), 2000);
-      if (typeof client._cancelPendingTransactions === 'function') client._cancelPendingTransactions();
-      const close = () => {
+      const onClose = () => { if (release()) finish(); };
+      const timer = setTimeout(() => {
+        if (release()) finish();
+        else finish(error('Serial closure could not be confirmed; port quarantined', 'ECLOSE'));
+      }, 2000);
+      client.on('close', onClose);
+      try { clearTransactions(client); } catch (err) { finish(err); return; }
+      const closeOld = () => {
+        if (release()) { finish(); return; }
+        if (closeStarted) return;
+        closeStarted = true;
         try { client.close(err => {
-          if (!err || !client.isOpen) release();
-          finish(err && client.isOpen ? err : null);
-        }); } catch (err) { finish(err); }
+          if (release()) finish();
+          else finish(error('Serial closure could not be confirmed' + (err ? ': ' + err.message : '') + '; port quarantined', 'ECLOSE'));
+        }); } catch (err) {
+          if (release()) finish();
+          else finish(error('Serial close failed: ' + err.message + '; port quarantined', 'ECLOSE'));
+        }
       };
-      // Opening cannot be cancelled by serialport. Wait for it to settle; close
-      // a late successful open, retaining the lease throughout.
-      if (client._makoOpening) client._makoOpening.then(close, () => {release(); finish();});
-      else close();
-    });
+      if (client._makoOpening) client._makoOpening.then(closeOld, closeOld);
+      else closeOld();
+    }));
     return client._makoRetiring;
   }
 
   async function connect(state) {
-    if (state.closing) throw error('Bus closing', 'ECANCELLED');
+    const epoch = state.epoch;
+    checkEpoch(state, epoch);
     const cfg = state.cfg;
-    if (state.client && state.transportFault) await retire(state);
-    if (state.client && state.client._makoRetiring) await retire(state);
+    if (state.client && (state.transportFault || state.client._makoRetiring)) await retire(state);
+    checkEpoch(state, epoch);
     if (state.client && state.client.isOpen) return;
     if (state.client) await retire(state);
-    const path = cfg.serialPort && await operation(state,'USB detection',5000,() => require('./usb-discovery').resolve(cfg.serialPort,state));
+    checkEpoch(state, epoch);
+    // USB enumeration itself cannot be cancelled. Use scratch identity state so
+    // a late enumeration cannot mutate a stopped/recovering bus.
+    const usb = {usbIdentity: state.usbIdentity};
+    const path = cfg.serialPort && await operation(state, 'USB detection', 5000,
+      () => require('./usb-discovery').resolve(cfg.serialPort, usb));
+    checkEpoch(state, epoch);
     if (!path) throw error('No serial port configured', 'ECONFIG');
+    if (usb.usbIdentity) state.usbIdentity = usb.usbIdentity;
     const owner = owners.get(path);
     if (owner && owner !== state) throw error('Serial port already owned by another Mako bus: ' + path, 'EPORTBUSY');
-    owners.set(path, state); state.ownerPath = path;
-    const client = new ModbusRTU(); state.client = client;
+    const client = new ModbusRTU();
+    owners.set(path, state); state.ownerPath = path; state.client = client;
+    let port;
+    const onData = () => { if (state.client === client && !client._makoRetiring) state.lastRx = Date.now(); };
     const onFault = err => {
-      if (state.client !== client || client._makoRetiring) return;
-      state.dirty = true;
-      state.transportFault = true;
+      if (state.client !== client || client._makoRetiring || client._makoClosed) return;
+      state.dirty = true; state.transportFault = true;
       const failure = err instanceof Error ? err : error('Serial port disconnected', 'EDISCONNECT');
       if (!failure.code) failure.code = 'ESERIAL';
       if (state.cancel) state.cancel(failure);
     };
-    client.on('error', onFault);
-    client.on('close', () => onFault(error('Serial port closed', 'EDISCONNECT')));
+    const onClose = () => onFault(error('Serial port closed', 'EDISCONNECT'));
+    client.on('error', onFault); client.on('close', onClose);
+    client._makoCleanup = () => {
+      client.removeListener('error', onFault); client.removeListener('close', onClose);
+      if (port) port.removeListener('data', onData);
+    };
     try {
       await operation(state, 'Serial open', 5000, () => {
-        client._makoOpening = Promise.resolve(client.connectRTUBuffered(path, {
+        const opening = Promise.resolve().then(() => { checkEpoch(state, epoch); return client.connectRTUBuffered(path, {
           baudRate: bounded(cfg.baudRate, 9600, 1200, 921600), dataBits: 8,
           stopBits: Number(cfg.stopBits) === 2 ? 2 : 1, parity: cfg.parity || 'none'
-        }));
+        }); });
+        client._makoOpening = opening.then(value => { client._makoOpening = null; return value; },
+          err => { client._makoOpening = null; throw err; });
         return client._makoOpening;
       });
-      client._makoOpening = null;
+      checkEpoch(state, epoch);
       state.transportFault = false;
-      const port = portOf(client);
-      if (port) port.on('data', () => { if (state.client === client) state.lastRx = Date.now(); });
-      // Preserve a pending recovery interval across reconnects: bytes already
-      // travelling over RF can still arrive on the new descriptor.
+      port = portOf(client);
+      if (port) port.on('data', onData);
     } catch (err) {
-      await retire(state).catch(() => {});
+      if (!state.closing && state.epoch === epoch) await retire(state).catch(() => {});
       throw err;
     }
   }
 
-  async function quiet(state, milliseconds) {
+  function quiet(state, milliseconds) {
     const start = Date.now();
-    // New bytes restart the quiet interval, but continuous noise has a deadline.
-    await operation(state, 'Serial quiet period', milliseconds * 3 + 1000, async () => {
-      while (!state.closing) {
+    return operation(state, 'Serial quiet period', milliseconds * 3 + 1000, cleanup => new Promise(resolve => {
+      let timer, stopped = false;
+      cleanup(() => { stopped = true; clearTimeout(timer); });
+      const check = () => {
+        if (stopped) return;
         const remaining = milliseconds - (Date.now() - Math.max(start, state.lastRx));
-        if (remaining <= 0) return;
-        await delay(Math.min(remaining, 50));
-      }
-      throw error('Bus closing', 'ECANCELLED');
-    });
+        if (remaining <= 0) resolve();
+        else timer = setTimeout(check, Math.min(remaining, 50));
+      };
+      check();
+    }));
   }
-
   async function recover(state) {
     if (!state.dirty) return;
-    await connect(state);
-    // RTU has no transaction identity. Wait out late replies before reusing the
-    // parser. This is bounded mitigation, not a guarantee for arbitrary RF delay.
-    const guard = bounded(state.cfg.recoveryMs, state.cfg.serialPort === '/dev/ttyAMA2' ? timeoutMs(state.cfg) : 100, 50, 30000);
+    const epoch = state.epoch;
+    await connect(state); checkEpoch(state, epoch);
+    // RTU has no reply transaction identity. This guards bounded late RF traffic;
+    // it cannot identify a response delayed beyond the configured quiet window.
+    const guard = bounded(state.cfg.recoveryMs, state.cfg.serialPort === '/dev/ttyAMA2' ? timeoutMs(state.cfg) : 100, 50, 120000);
     try {
-      await quiet(state, guard);
-      const port = portOf(state.client);
+      await quiet(state, guard); checkEpoch(state, epoch);
+      const client = state.client, port = portOf(client);
       if (port && typeof port.flush === 'function') await operation(state, 'Serial flush', 1000, () => callbackCall(port, 'flush'));
-      if (state.client._port && Buffer.isBuffer(state.client._port._buffer)) state.client._port._buffer = Buffer.alloc(0);
-      state.dirty = false;
-    } catch (err) { await retire(state).catch(() => {}); throw err; }
+      checkEpoch(state, epoch);
+      if (!client.isOpen || state.transportFault) throw error('Serial connection failed during recovery', 'ESERIAL');
+      if (client._port && Buffer.isBuffer(client._port._buffer)) client._port._buffer = Buffer.alloc(0);
+      clearTransactions(client); state.dirty = false;
+    } catch (err) {
+      if (!state.closing && state.epoch === epoch) await retire(state).catch(() => {});
+      throw err;
+    }
   }
 
-  async function request(state, req) {
-    await connect(state);
-    await recover(state);
+  async function request(state, item, req) {
+    checkItem(state, item); await connect(state);
+    checkItem(state, item); await recover(state);
+    checkItem(state, item);
     const client = state.client;
     client.setID(req.unitid); client.setTimeout(timeoutMs(state.cfg));
     const methods = {1:'readCoils',2:'readDiscreteInputs',3:'readHoldingRegisters',4:'readInputRegisters',5:'writeCoil',6:'writeRegister',15:'writeCoils',16:'writeRegisters'};
     try {
-      return await operation(state, 'Modbus request', timeoutMs(state.cfg) + 1000,
-        () => client[methods[req.fc]](req.address, req.mode === 'read' ? req.quantity : req.value));
+      return await operation(state, 'Modbus request', timeoutMs(state.cfg) + 1000, () => {
+        checkItem(state, item);
+        if (req.mode === 'write') item.writeMayHaveApplied = true;
+        return client[methods[req.fc]](req.address, req.mode === 'read' ? req.quantity : req.value);
+      });
     } catch (err) {
       if (!err.modbusCode) state.dirty = true;
-      if (state.transportFault || ['EDEADLINE','EDISCONNECT','ESERIAL'].includes(err.code) || !client.isOpen) await retire(state).catch(() => {});
+      if (!state.closing && state.epoch === item.epoch &&
+          (state.transportFault || ['EDEADLINE','EDISCONNECT','ESERIAL'].includes(err.code) || !client.isOpen)) await retire(state).catch(() => {});
       throw err;
     }
   }
 
   async function rssi(state, command, parse) {
-    const client = state.client;
-    const wrapper = client && client._port;
-    const port = portOf(client);
+    const client = state.client, wrapper = client && client._port, port = portOf(client);
     if (!port || !wrapper) throw error('RSSI serial port unavailable', 'ERSSI');
-    await operation(state, 'RSSI guard', 1100, () => delay(bounded(state.cfg.rssiGuardMs, 10, 0, 1000)));
+    await pause(state, 'RSSI guard', bounded(state.cfg.rssiGuardMs, 10, 0, 1000));
     await operation(state, 'RSSI flush', 1000, () => callbackCall(port, 'flush'));
-    // Suspend Modbus delivery while the radio's proprietary frame is read.
     wrapper.removeListener('data', client._onReceive);
     let listener;
     try {
-      const value = await operation(state, 'RSSI', bounded(state.cfg.rssiTimeoutMs, 100, 10, 5000), () => new Promise((resolve, reject) => {
-        let rx = Buffer.alloc(0);
+      return await operation(state, 'RSSI', bounded(state.cfg.rssiTimeoutMs, 100, 10, 5000), cleanup => new Promise((resolve, reject) => {
+        let rx = Buffer.alloc(0), stopped = false;
+        cleanup(() => { stopped = true; if (listener) port.removeListener('data', listener); });
         listener = chunk => {
           rx = Buffer.concat([rx, chunk]).slice(-512);
           const result = parse(rx); if (result) resolve(result.rssiDbm);
         };
         port.on('data', listener);
-        port.write(command(), err => { if (err) reject(err); else port.drain(err => {if(err)reject(err);}); });
+        port.write(command(), err => { if (stopped) return; if (err) reject(err); else port.drain(err => { if (!stopped && err) reject(err); }); });
       }));
-      return value;
     } catch (err) { state.dirty = true; throw err; }
     finally {
       if (listener) port.removeListener('data', listener);
       if (Buffer.isBuffer(wrapper._buffer)) wrapper._buffer = Buffer.alloc(0);
-      if (!state.closing && state.client === client && !client._makoRetiring) wrapper.on('data', client._onReceive);
+      if (!state.closing && !state.recovering && state.client === client && !client._makoRetiring) wrapper.on('data', client._onReceive);
     }
   }
 
   function finish(item, err, result) {
     if (item.finished) return;
     item.finished = true;
-    try { item.complete(err, result); } catch (e) { if (item.node.error) item.node.error(e); }
+    if (err) item.failure = Object.assign(new Error(err.message || String(err)), err,
+      {writeMayHaveApplied: !!item.writeMayHaveApplied});
+    try { item.complete(item.failure || null, result); } catch (e) { if (item.node.error) item.node.error(e); }
   }
-
-  async function runItem(state, item) {
-    if (item.node._makoClosed) return finish(item, error('Node closed', 'ECANCELLED'));
-    const maxAge = bounded(state.cfg.maxAge_s, 0, 0, 3600);
-    if (maxAge > 0 && Date.now() - item.queuedAt > maxAge * 1000) return finish(item, error('Queued request expired', 'EQUEUEEXPIRED'));
-    const offline = state.failures.get(item.req.unitid);
-    if (item.req.mode === 'read' && offline && Date.now() < offline) return finish(item, error('Device offline; waiting for next probe', 'EOFFLINE'));
-    const cooldown = bounded(state.cfg.offlineCooldown_s,0,0,300);
-    // After the first failed retry group, one probe is enough to discover a
-    // returning device. Do not monopolize the bus with another retry group.
-    const tries = offline && cooldown > 0 && item.req.mode === 'read' ? 1 : Math.floor(bounded(item.retries == null ? state.cfg.retries : item.retries, 2, 0, 10)) + 1;
-    let result, lastErr;
-    for (let attempt = 1; attempt <= tries && !state.closing && !item.node._makoClosed; attempt++) {
+  async function execute(state, item, req) {
+    checkItem(state, item);
+    const offline = state.failures.get(req.unitid);
+    if (req.mode === 'read' && offline && Date.now() < offline) throw error('Device offline; waiting for next probe', 'EOFFLINE');
+    const cooldown = bounded(state.cfg.offlineCooldown_s, 0, 0, 300);
+    const tries = offline && cooldown > 0 && req.mode === 'read' ? 1 : Math.floor(bounded(item.retries == null ? state.cfg.retries : item.retries, 2, 0, 10)) + 1;
+    let lastErr;
+    for (let attempt = 1; attempt <= tries; attempt++) {
+      checkItem(state, item);
       try {
-        item.node.status({fill:'blue',shape:'dot',text:'uid'+item.req.unitid+' try '+attempt+'/'+tries});
-        result = await request(state, item.req); lastErr = null; break;
+        item.node.status({fill:'blue',shape:'dot',text:'uid'+req.unitid+' try '+attempt+'/'+tries});
+        const result = await request(state, item, req);
+        checkItem(state, item); state.failures.delete(req.unitid); return result;
       } catch (err) {
-        lastErr = err;
-        if (item.node.warn) item.node.warn('uid'+item.req.unitid+' try '+attempt+'/'+tries+': '+err.message);
-        // Protocol exceptions and lifecycle/configuration errors cannot improve
-        // by repeating the same request. Timeouts retain configured retry semantics.
-        if (err.modbusCode || ['ECANCELLED','ECONFIG','EPORTBUSY','ECLOSE'].includes(err.code)) break;
-        if (attempt < tries) await operation(state, 'Retry gap', 61000, () => delay(bounded(state.cfg.gap_s, 0, 0, 60)*1000));
+        checkItem(state, item); lastErr = err;
+        if (item.node.warn) item.node.warn('uid'+req.unitid+' try '+attempt+'/'+tries+': '+err.message);
+        if (err.modbusCode || ['ECANCELLED','ECONFIG','EPORTBUSY','ECLOSE','EBUSRESET','EBUSRECOVERING','EBUSRECOVERYFAILED'].includes(err.code)) break;
+        if (attempt < tries) await pause(state, 'Retry gap', bounded(state.cfg.gap_s, 0, 0, 60)*1000);
       }
     }
-    if (state.closing || item.node._makoClosed) return finish(item, error('Node or bus closed', 'ECANCELLED'));
-    if (lastErr) {
-      if (!lastErr.modbusCode && !['ECONFIG','EPORTBUSY','ECLOSE'].includes(lastErr.code)) state.failures.set(item.req.unitid, Date.now()+cooldown*1000);
-      finish(item, lastErr);
-    } else {
-      state.failures.delete(item.req.unitid);
-      if (item.after) await item.after(result);
-      finish(item, null, result);
-    }
-    await operation(state, 'Request gap', 61000, () => delay(bounded(state.cfg.gap_s,0,0,60)*1000));
+    if (lastErr && !lastErr.modbusCode && !['ECONFIG','EPORTBUSY','ECLOSE'].includes(lastErr.code)) state.failures.set(req.unitid, Date.now()+cooldown*1000);
+    throw lastErr;
+  }
+  async function runItem(state, item) {
+    checkItem(state, item);
+    const maxAge = bounded(state.cfg.maxAge_s, 0, 0, 3600);
+    if (maxAge > 0 && Date.now() - item.queuedAt > maxAge*1000) throw error('Queued request expired', 'EQUEUEEXPIRED');
+    let result;
+    if (item.run) {
+      let groups = 0;
+      result = await item.run(async req => {
+        checkItem(state, item);
+        if (groups++) await pause(state, 'Request gap', bounded(state.cfg.gap_s, 0, 0, 60)*1000);
+        checkItem(state, item); return execute(state, item, req);
+      }, () => checkItem(state, item));
+    } else result = await execute(state, item, item.req);
+    checkItem(state, item);
+    if (item.after) await item.after(result);
+    checkItem(state, item); finish(item, null, result);
   }
-
   function kick(state) {
-    if (state.worker || state.closing) return;
+    if (state.worker || available(state) || !state.queue.length) return;
+    // Reserve the active item synchronously: Max Queue=1 still permits one
+    // active request. Only the next waiting request reaches that threshold.
+    state.active = state.queue.shift();
     state.worker = Promise.resolve().then(async () => {
-      while (!state.closing && state.queue.length) {
-        const item = state.queue.shift(); state.active = item;
+      while (state.active && !state.closing && !state.recovering) {
+        const item = state.active;
         try { await runItem(state, item); } catch (err) { finish(item, err); }
-        finally { state.active = null; }
+        if (!state.closing && !state.recovering) {
+          try { await pause(state, 'Request gap', bounded(state.cfg.gap_s, 0, 0, 60)*1000); } catch (_) {}
+        }
+        state.active = null;
+        if (!available(state)) state.active = state.queue.shift() || null;
       }
-    }).catch(err => { if (state.active) finish(state.active, err); }).finally(() => {
-      state.worker = null;
-      if (!state.closing && state.queue.length) kick(state);
+    }).finally(() => {
+      state.active = null; state.worker = null;
+      if (!available(state) && state.queue.length) kick(state);
     });
   }
-
+  function status(state, fill, text) {
+    if (typeof state.cfg.status === 'function') state.cfg.status({fill,shape:'ring',text});
+  }
+  function reset(state) {
+    if (state.closing || state.recovering) return;
+    state.recovering = true; state.epoch++;
+    const reason = error('Max Queue reached; bus reset cancelled this request. A transmitted write may already have executed.', 'EBUSRESET');
+    const queued = state.queue.splice(0);
+    if (state.active) finish(state.active, reason);
+    queued.forEach(item => finish(item, reason));
+    if (state.cancel) state.cancel(reason);
+    status(state, 'yellow', 'Recovering bus');
+    const worker = state.worker;
+    state.recoveryPromise = Promise.resolve().then(async () => {
+      if (worker) await worker;
+      if (state.closing) return;
+      await retire(state);
+      if (state.closing) return;
+      state.failures.clear(); state.transportFault = false; state.lastRx = 0; state.dirty = true;
+      await connect(state); await recover(state);
+      if (state.closing) return;
+      state.recoveryError = null;
+      status(state, 'green', 'Bus recovered; ready for new requests');
+    }).catch(err => {
+      if (state.closing) return;
+      state.recoveryError = error('Bus recovery failed: ' + err.message + '. Check the connection and redeploy before sending new requests.', 'EBUSRECOVERYFAILED');
+      state.recoveryError.causeCode = err.code;
+      status(state, 'red', 'Bus recovery failed');
+      if (typeof state.cfg.error === 'function') state.cfg.error(state.recoveryError);
+    }).finally(() => { state.recovering = false; state.recoveryPromise = null; });
+  }
   function enqueue(state, item) {
-    item.queuedAt = Date.now();
-    if (state.closing || item.node._makoClosed) return finish(item, error('Bus or node closed', 'ECANCELLED'));
-    // Retain only the newest pending read from this node. Never coalesce writes.
-    if (state.cfg.coalesceReads === true && item.req.mode === 'read') {
-      const idx = state.queue.findIndex(q => q.node === item.node && q.req.mode === 'read');
-      if (idx >= 0) finish(state.queue.splice(idx,1)[0],error('Superseded by newer poll','ESUPERSEDED'));
+    item.queuedAt = Date.now(); item.epoch = state.epoch;
+    const err = available(state);
+    if (err || item.node._makoClosed) return finish(item, err || error('Node closed', 'ECANCELLED'));
+    if (state.cfg.coalesceReads === true && item.req && item.req.mode === 'read') {
+      const idx = state.queue.findIndex(q => q.node === item.node && q.req && q.req.mode === 'read');
+      if (idx >= 0) finish(state.queue.splice(idx,1)[0], error('Superseded by newer poll','ESUPERSEDED'));
     }
-    if (state.queue.length >= bounded(state.cfg.maxQueue,50,1,1000)) return finish(item,error('Bus queue full','EQUEUEFULL'));
     state.queue.push(item); kick(state);
+    if (state.queue.length >= Math.floor(bounded(state.cfg.maxQueue, 50, 1, 1000))) reset(state);
   }
-
   function detach(state, node) {
     node._makoClosed = true;
-    state.queue = state.queue.filter(item => {if(item.node!==node)return true;finish(item,error('Node closed','ECANCELLED'));return false;});
-    if (state.active && state.active.node === node && state.cancel) {
-      state.dirty = true; state.cancel(error('Node closed','ECANCELLED'));
+    state.queue = state.queue.filter(item => { if (item.node !== node) return true; finish(item, error('Node closed','ECANCELLED')); return false; });
+    if (state.active && state.active.node === node) {
+      finish(state.active, error('Node closed','ECANCELLED'));
+      state.dirty = true; state.transportFault = true;
+      if (state.cancel) state.cancel(error('Node closed','ECANCELLED'));
     }
   }
-
   function close(state) {
     if (state.closePromise) return state.closePromise;
-    state.closing = true;
+    state.closing = true; state.epoch++;
+    const reason = error('Bus closed','ECANCELLED');
     const queued = state.queue.splice(0);
-    queued.forEach(item => finish(item,error('Bus closed','ECANCELLED')));
-    if (state.cancel) state.cancel(error('Bus closed','ECANCELLED'));
+    if (state.active) finish(state.active, reason);
+    queued.forEach(item => finish(item, reason));
+    if (state.cancel) state.cancel(reason);
     state.closePromise = (async () => {
       if (state.worker) await state.worker;
+      if (state.recoveryPromise) await state.recoveryPromise;
       await retire(state);
     })();
     return state.closePromise;
   }
-  return { create, enqueue, detach, close, rssi };
-};
+  return {create, enqueue, detach, close, rssi, available};
+};