react-native-web-serial-api 0.1.0 → 0.2.0

package/lib/commonjs/websocket/WebSocketSerialTransport.js

@@ -0,0 +1,659 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.WebSocketSerialTransport = void 0;
+var _protocol = require("./protocol");
+/**
+ * A {@link SerialTransport} that talks to a remote serial port over a WebSocket
+ * bridge (run `expose-serial-websocket` on the host — see `bin/expose-serial.js`).
+ *
+ * Because it implements the same transport contract as the native `UsbSerialModule` and the
+ * in-memory `InMemorySerialTransport`, it's a drop-in: the whole `Serial` /
+ * `SerialPort` polyfill (streams, signals, reconnect, the conformance suite)
+ * works on top of it unchanged.
+ *
+ * **Resilience.** The socket is supervised: an unexpected drop (server restart,
+ * network blip) is handled transparently — the transport reconnects with
+ * exponential backoff and *restores the session* (line coding, control signals,
+ * and read state) so the app's open `SerialPort` keeps working. A transient
+ * drop is therefore invisible to the polyfill (reads pause and resume; writes
+ * issued during the gap wait for the reconnection). Only a real remote
+ * disconnect (the host's serial port going away) or giving up after
+ * `maxReconnectAttempts` surfaces as a serial disconnect.
+ *
+ * @example
+ * import {Serial} from 'react-native-web-serial-api';
+ * import {WebSocketSerialTransport} from 'react-native-web-serial-api/websocket';
+ *
+ * const serial = new Serial(new WebSocketSerialTransport('ws://localhost:8080'));
+ * const [port] = await serial.getPorts();
+ * await port.open({baudRate: 115200});
+ */
+
+/** Minimal structural WebSocket shape (browser & React Native both provide it). */
+
+const PARITY = {
+  0: 'none',
+  1: 'odd',
+  2: 'even'
+};
+class WebSocketSerialTransport {
+  #deviceId = 1;
+  #portNumber = 0;
+  #usbVendorId;
+  #usbProductId;
+  #serialNumber;
+  #url;
+  #Ctor;
+  #reconnectEnabled;
+  #initialDelay;
+  #maxDelay;
+  #maxAttempts;
+  #connectTimeout;
+  #commandTimeout;
+  #options;
+  #ws = null;
+  #state = 'connecting';
+  #everConnected = false;
+  #reconnectAttempts = 0;
+  #reconnectTimer;
+  #metadataLoaded = false;
+
+  // Session state to restore on reconnect.
+  #portOpen = false;
+  #reading = false;
+  #lastLineCoding = null;
+  #nextId = 1;
+  #dtr = false;
+  #rts = false;
+  #pending = new Map();
+  #connectWaiters = new Set();
+  #dataListeners = new Set();
+  #errorListeners = new Set();
+  #connectListeners = new Set();
+  #disconnectListeners = new Set();
+  constructor(url, options = {}) {
+    this.#options = options;
+    this.#usbVendorId = options.usbVendorId ?? 0;
+    this.#usbProductId = options.usbProductId ?? 0;
+    this.#serialNumber = options.serialNumber ?? '';
+    const Ctor = options.WebSocket ?? globalThis.WebSocket;
+    if (!Ctor) {
+      throw new Error('No WebSocket implementation is available.');
+    }
+    this.#url = url;
+    this.#Ctor = Ctor;
+    this.#reconnectEnabled = options.reconnect ?? true;
+    this.#initialDelay = options.reconnectInitialDelayMs ?? 250;
+    this.#maxDelay = options.reconnectMaxDelayMs ?? 10000;
+    this.#maxAttempts = options.maxReconnectAttempts ?? Number.POSITIVE_INFINITY;
+    this.#connectTimeout = options.connectTimeoutMs ?? 10000;
+    this.#commandTimeout = options.commandTimeoutMs ?? 10000;
+    this.#connect();
+  }
+
+  /** Current connection state (advisory; the polyfill keeps working across reconnects). */
+  get connectionState() {
+    return this.#state;
+  }
+
+  // ── connection lifecycle ────────────────────────────────────────────────────
+
+  #connect() {
+    /* istanbul ignore next — reconnect timers are cleared on explicit disconnect() */
+    if (this.#state === 'closed') {
+      return;
+    }
+    this.#state = this.#everConnected ? 'reconnecting' : 'connecting';
+    let ws;
+    try {
+      ws = new this.#Ctor(this.#url);
+    } catch {
+      // Construction itself failed (e.g. bad URL on some impls) — treat as a drop.
+      this.#handleSocketDown();
+      return;
+    }
+    ws.binaryType = 'arraybuffer';
+    this.#ws = ws;
+    let dead = false;
+    const onDown = () => {
+      // Fire once per socket, and ignore a stale socket we've already replaced.
+      if (dead || ws !== this.#ws) {
+        return;
+      }
+      dead = true;
+      this.#handleSocketDown();
+    };
+    ws.addEventListener('open', () => {
+      if (ws === this.#ws) {
+        void this.#onOpen();
+      }
+    });
+    ws.addEventListener('message', event => {
+      if (ws === this.#ws) {
+        this.#onMessage(event.data);
+      }
+    });
+    ws.addEventListener('error', onDown);
+    ws.addEventListener('close', onDown);
+  }
+  async #onOpen() {
+    const reconnected = this.#everConnected;
+    this.#everConnected = true;
+    this.#state = 'open';
+    this.#reconnectAttempts = 0;
+    try {
+      // Re-establish the remote session before letting queued I/O resume, so
+      // writes never go out at the wrong baud rate / signal state.
+      await this.#restoreSession();
+      await this.#loadPortInfo();
+    } catch {
+      // A drop happened mid-restore; the close handler schedules another retry.
+      return;
+    }
+    if (!reconnected) {
+      this.#emit(this.#connectListeners, this.#connectEvent());
+    }
+    this.#options.onConnected?.({
+      reconnected
+    });
+    this.#releaseWaiters();
+  }
+  async #restoreSession() {
+    if (!this.#portOpen) {
+      return; // nothing to restore until the app has opened the port
+    }
+    /* istanbul ignore next */
+    if (this.#lastLineCoding) {
+      await this.#sendCommand('setLineCoding', {
+        ...this.#lastLineCoding
+      });
+    }
+    if (this.#dtr || this.#rts) {
+      await this.#sendCommand('setSignals', {
+        dtr: this.#dtr,
+        rts: this.#rts
+      });
+    }
+    // A fresh bridge connection forwards data by default; mirror the app's intent.
+    await this.#sendCommand(this.#reading ? 'startReading' : 'stopReading');
+  }
+  async #loadPortInfo() {
+    if (this.#metadataLoaded) {
+      return;
+    }
+    let info = null;
+    try {
+      info = await this.#sendCommand('getPortInfo');
+    } catch {
+      // Older bridge versions won't implement getPortInfo; keep defaults.
+      return;
+    }
+    if (info && typeof info === 'object') {
+      if (typeof info.usbVendorId === 'number') {
+        this.#usbVendorId = info.usbVendorId;
+      }
+      if (typeof info.usbProductId === 'number') {
+        this.#usbProductId = info.usbProductId;
+      }
+      if (typeof info.serialNumber === 'string') {
+        this.#serialNumber = info.serialNumber;
+      }
+    }
+    this.#metadataLoaded = true;
+  }
+  async #probeAlive() {
+    try {
+      // `getSignals` is supported by all bridge versions and gives us a
+      // request/response roundtrip to detect half-open sockets.
+      await this.#sendCommand('getSignals');
+    } catch (error) {
+      this.#handleSocketDown();
+      throw error;
+    }
+  }
+  #handleSocketDown() {
+    if (this.#state === 'closed') {
+      return;
+    }
+    // Commands tied to the dead socket can never be answered — reject them.
+    this.#failAll('WebSocket connection lost');
+    if (this.#reconnectEnabled && this.#reconnectAttempts < this.#maxAttempts) {
+      this.#scheduleReconnect();
+    } else {
+      this.#terminate('WebSocket connection lost and will not be retried.');
+    }
+  }
+  #scheduleReconnect() {
+    this.#state = 'reconnecting';
+    const attempt = this.#reconnectAttempts++; // 0-based for the backoff curve
+    const delay = Math.min(this.#initialDelay * 2 ** attempt, this.#maxDelay);
+    // Full jitter in the upper half keeps a herd of clients from syncing up.
+    const jittered = Math.round(delay * (0.5 + Math.random() * 0.5));
+    this.#options.onReconnecting?.(attempt + 1, jittered);
+    this.#reconnectTimer = setTimeout(() => {
+      this.#reconnectTimer = undefined;
+      this.#connect();
+    }, jittered);
+  }
+  #terminate(reason) {
+    /* istanbul ignore next — terminate() only runs once per transport lifecycle */
+    if (this.#state === 'closed') {
+      return;
+    }
+    this.#state = 'closed';
+    this.#portOpen = false;
+    this.#reading = false;
+    /* istanbul ignore next — reconnect timers are either fired or cleared earlier */
+    if (this.#reconnectTimer !== undefined) {
+      clearTimeout(this.#reconnectTimer);
+      this.#reconnectTimer = undefined;
+    }
+    this.#failAll(reason);
+    this.#rejectWaiters(new Error(reason));
+    // Surface to the polyfill so any open stream fails with a NetworkError.
+    this.#emit(this.#errorListeners, {
+      deviceId: this.#deviceId,
+      portNumber: this.#portNumber,
+      error: reason
+    });
+    this.#emit(this.#disconnectListeners, this.#connectEvent());
+    this.#options.onClosed?.(reason);
+  }
+
+  /**
+   * Release the socket because the consumer closed the port. Unlike a drop, this
+   * does not auto-reconnect (no lingering bridge session) — the next `open()` or
+   * discovery reconnects on demand. Distinct from the terminal `disconnect()`.
+   */
+  #suspend() {
+    if (this.#reconnectTimer !== undefined) {
+      clearTimeout(this.#reconnectTimer);
+      this.#reconnectTimer = undefined;
+    }
+    this.#reconnectAttempts = 0;
+    this.#failAll('serial port closed');
+    this.#state = 'suspended';
+    const ws = this.#ws;
+    this.#ws = null; // detach first so the socket's close handler is a no-op
+    try {
+      ws?.close();
+    } catch {
+      // already closing
+    }
+  }
+
+  /**
+   * Resolve when the socket is connected; reject on timeout or terminal close.
+   * Wakes a `suspended` transport (after `close()`) by reconnecting on demand.
+   */
+  #whenConnected() {
+    if (this.#state === 'open') {
+      return Promise.resolve();
+    }
+    if (this.#state === 'closed') {
+      return Promise.reject(new Error('WebSocket transport is closed.'));
+    }
+    if (this.#state === 'suspended') {
+      this.#connect(); // reconnect on demand
+    }
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.#connectWaiters.delete(waiter);
+        reject(new Error('Timed out waiting for the WebSocket connection.'));
+      }, this.#connectTimeout);
+      const waiter = {
+        resolve: () => {
+          clearTimeout(timer);
+          resolve();
+        },
+        reject: e => {
+          clearTimeout(timer);
+          reject(e);
+        }
+      };
+      this.#connectWaiters.add(waiter);
+    });
+  }
+  #releaseWaiters() {
+    for (const waiter of [...this.#connectWaiters]) {
+      waiter.resolve();
+    }
+    this.#connectWaiters.clear();
+  }
+  #rejectWaiters(reason) {
+    for (const waiter of [...this.#connectWaiters]) {
+      waiter.reject(reason);
+    }
+    this.#connectWaiters.clear();
+  }
+
+  // ── message handling ───────────────────────────────────────────────────────
+
+  #onMessage(data) {
+    if (data instanceof ArrayBuffer) {
+      this.#emit(this.#dataListeners, {
+        deviceId: this.#deviceId,
+        portNumber: this.#portNumber,
+        data: Array.from(new Uint8Array(data))
+      });
+      return;
+    }
+    if (typeof data !== 'string') {
+      return;
+    }
+    const msg = (0, _protocol.parseControlMessage)(data);
+    if (!msg) {
+      return;
+    }
+    if (msg.type === 'response') {
+      const pending = this.#pending.get(msg.id);
+      if (pending) {
+        this.#pending.delete(msg.id);
+        if (msg.error) {
+          pending.reject(new Error(msg.error));
+        } else {
+          pending.resolve(msg.result);
+        }
+      }
+    } else if (msg.type === 'event') {
+      if (msg.event === 'error') {
+        this.#emit(this.#errorListeners, {
+          deviceId: this.#deviceId,
+          portNumber: this.#portNumber,
+          error: msg.error ?? 'serial error'
+        });
+      } else if (msg.event === 'close') {
+        // The host's serial port itself went away — a real disconnect (distinct
+        // from a transport drop, which we reconnect through silently).
+        this.#portOpen = false;
+        this.#emit(this.#disconnectListeners, this.#connectEvent());
+      }
+    }
+  }
+  #failAll(reason) {
+    for (const [, pending] of this.#pending) {
+      pending.reject(new Error(reason));
+    }
+    this.#pending.clear();
+  }
+  #connectEvent() {
+    return {
+      deviceId: this.#deviceId,
+      usbVendorId: this.#usbVendorId,
+      usbProductId: this.#usbProductId
+    };
+  }
+
+  /** Register a pending command and send it on the (already-open) socket. */
+  #sendCommand(command, args) {
+    const ws = this.#ws;
+    if (!ws || this.#state === 'closed') {
+      return Promise.reject(new Error('WebSocket transport is closed.'));
+    }
+    const id = this.#nextId++;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        if (this.#pending.delete(id)) {
+          reject(new Error(`Command "${command}" timed out.`));
+        }
+      }, this.#commandTimeout);
+      this.#pending.set(id, {
+        resolve: value => {
+          clearTimeout(timer);
+          resolve(value);
+        },
+        reject: error => {
+          clearTimeout(timer);
+          reject(error);
+        }
+      });
+      try {
+        ws.send(JSON.stringify({
+          type: 'command',
+          id,
+          command,
+          args
+        }));
+      } catch (e) {
+        this.#pending.delete(id);
+        clearTimeout(timer);
+        reject(e instanceof Error ? e : new Error(String(e)));
+      }
+    });
+  }
+
+  /** Wait for a connection (reconnecting if necessary), then run a command. */
+  async #command(command, args) {
+    await this.#whenConnected();
+    return this.#sendCommand(command, args);
+  }
+  #subscribe(set, listener) {
+    set.add(listener);
+    return {
+      remove: () => set.delete(listener)
+    };
+  }
+  #emit(set, event) {
+    for (const listener of [...set]) {
+      listener(event);
+    }
+  }
+
+  // ── discovery & permission ─────────────────────────────────────────────────
+
+  async findAllDrivers() {
+    try {
+      await this.#whenConnected();
+      await this.#probeAlive();
+      await this.#loadPortInfo();
+    } catch {
+      // Discovery should be resilient: treat transport down as "no devices".
+      return [];
+    }
+    return [{
+      deviceId: this.#deviceId,
+      portNumber: this.#portNumber,
+      usbVendorId: this.#usbVendorId,
+      usbProductId: this.#usbProductId,
+      hasPermission: true
+    }];
+  }
+  async showPortPicker(_filter, _labels) {
+    const [port] = await this.findAllDrivers();
+    return port;
+  }
+  requestPermission(_deviceId) {
+    return Promise.resolve(true);
+  }
+
+  // ── lifecycle ──────────────────────────────────────────────────────────────
+
+  #lineCoding(options) {
+    return {
+      baudRate: options.baudRate,
+      dataBits: options.dataBits,
+      stopBits: options.stopBits,
+      parity: PARITY[options.parity ?? 0] ?? 'none'
+    };
+  }
+  async open(_deviceId, _portNumber, options) {
+    this.#lastLineCoding = this.#lineCoding(options);
+    await this.#command('setLineCoding', {
+      ...this.#lastLineCoding
+    });
+    this.#portOpen = true;
+  }
+  async close(_deviceId, _portNumber) {
+    this.#portOpen = false;
+    this.#reading = false;
+    if (this.#state === 'closed' || this.#state === 'suspended') {
+      return;
+    }
+    // Tell the bridge to stop forwarding, then drop the socket so the remote
+    // serial session is released and the device isn't left in a stale state.
+    // A later open() reconnects on demand (see #whenConnected → #suspend).
+    if (this.#state === 'open') {
+      await this.#sendCommand('stopReading').catch(() => undefined);
+    }
+    this.#suspend();
+  }
+  isOpen(_deviceId, _portNumber) {
+    return this.#portOpen;
+  }
+
+  // ── I/O ────────────────────────────────────────────────────────────────────
+
+  async write(_deviceId, _portNumber, data, _timeout) {
+    await this.#whenConnected();
+    const ws = this.#ws;
+    /* istanbul ignore next — #whenConnected() guarantees an attached socket */
+    if (!ws) {
+      throw new Error('WebSocket transport is closed.');
+    }
+    ws.send(Uint8Array.from(data));
+  }
+  async startReading(_deviceId, _portNumber) {
+    this.#reading = true;
+    await this.#command('startReading');
+  }
+  async stopReading(_deviceId, _portNumber) {
+    this.#reading = false;
+    await this.#command('stopReading');
+  }
+  async setParameters(_deviceId, _portNumber, options) {
+    this.#lastLineCoding = this.#lineCoding(options);
+    await this.#command('setLineCoding', {
+      ...this.#lastLineCoding
+    });
+  }
+
+  // ── control signals ────────────────────────────────────────────────────────
+
+  async setDTR(_d, _p, value) {
+    this.#dtr = value;
+    await this.#command('setSignals', {
+      dtr: value
+    });
+  }
+  async setRTS(_d, _p, value) {
+    this.#rts = value;
+    await this.#command('setSignals', {
+      rts: value
+    });
+  }
+  getDTR(_d, _p) {
+    return Promise.resolve(this.#dtr);
+  }
+  getRTS(_d, _p) {
+    return Promise.resolve(this.#rts);
+  }
+  async #signals() {
+    const s = await this.#command('getSignals');
+    return {
+      cts: !!s?.cts,
+      dsr: !!s?.dsr,
+      dcd: !!s?.dcd,
+      ri: !!s?.ri
+    };
+  }
+  async getCD(_d, _p) {
+    return (await this.#signals()).dcd;
+  }
+  async getCTS(_d, _p) {
+    return (await this.#signals()).cts;
+  }
+  async getDSR(_d, _p) {
+    return (await this.#signals()).dsr;
+  }
+  async getRI(_d, _p) {
+    return (await this.#signals()).ri;
+  }
+  async getControlLines(_d, _p) {
+    const s = await this.#signals();
+    const lines = [];
+    if (this.#rts) lines.push('RTS');
+    if (this.#dtr) lines.push('DTR');
+    if (s.cts) lines.push('CTS');
+    if (s.dsr) lines.push('DSR');
+    if (s.dcd) lines.push('CD');
+    if (s.ri) lines.push('RI');
+    return lines;
+  }
+  getSupportedControlLines(_d, _p) {
+    return Promise.resolve(['RTS', 'CTS', 'DTR', 'DSR', 'CD', 'RI']);
+  }
+
+  // ── flow control ───────────────────────────────────────────────────────────
+
+  setFlowControl(_d, _p, _flowControl) {
+    // Flow control is fixed at the rate the bridge was started with; accept the
+    // call so open({flowControl}) doesn't fail, but it isn't changed live.
+    return Promise.resolve();
+  }
+  getFlowControl(_d, _p) {
+    return Promise.resolve('NONE');
+  }
+  getSupportedFlowControl(_d, _p) {
+    return Promise.resolve(['NONE', 'RTS_CTS']);
+  }
+
+  // ── misc ───────────────────────────────────────────────────────────────────
+
+  async setBreak(_d, _p, value) {
+    await this.#command('setSignals', {
+      brk: value
+    });
+  }
+  async purgeHwBuffers(_d, _p, _purgeWrite, _purgeRead) {
+    await this.#command('flush').catch(() => undefined);
+  }
+  getSerial(_d, _p) {
+    return Promise.resolve(this.#serialNumber);
+  }
+
+  // ── subscriptions ──────────────────────────────────────────────────────────
+
+  onData(listener) {
+    return this.#subscribe(this.#dataListeners, listener);
+  }
+  onError(listener) {
+    return this.#subscribe(this.#errorListeners, listener);
+  }
+  onConnect(listener) {
+    return this.#subscribe(this.#connectListeners, listener);
+  }
+  onDisconnect(listener) {
+    return this.#subscribe(this.#disconnectListeners, listener);
+  }
+
+  /**
+   * Permanently close the transport (and the remote port session). Cancels any
+   * pending reconnect and stops auto-reconnecting.
+   */
+  disconnect() {
+    const alreadyClosed = this.#state === 'closed';
+    this.#state = 'closed'; // set first so the socket's close handler won't reconnect
+    if (this.#reconnectTimer !== undefined) {
+      clearTimeout(this.#reconnectTimer);
+      this.#reconnectTimer = undefined;
+    }
+    try {
+      this.#ws?.close();
+    } catch {
+      // already closing
+    }
+    if (!alreadyClosed) {
+      this.#portOpen = false;
+      this.#reading = false;
+      this.#failAll('WebSocket transport closed by client');
+      this.#rejectWaiters(new Error('WebSocket transport is closed.'));
+      this.#emit(this.#disconnectListeners, this.#connectEvent());
+      this.#options.onClosed?.('closed by client');
+    }
+  }
+}
+exports.WebSocketSerialTransport = WebSocketSerialTransport;
+//# sourceMappingURL=WebSocketSerialTransport.js.map