Add transport status events (#790)

* Transport status events Add symbol docs Emit transport status events Transport test suite * Review fixes * Remove core dependency * HTTP transport use AbortSignal, error handling in TransportNode * Improve stream handling * Update packages/transport-web-serial/src/transport.ts Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Fix linting --------- Co-authored-by: philon- <philon-@users.noreply.github.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
2025-08-23 20:44:03 -04:00
parent 449fb3ac36
commit d7e32e9b03
15 changed files with 1884 additions and 181 deletions
@@ -0,0 +1,186 @@
+import { describe, vi, expect, beforeEach, afterEach, it } from "vitest";
+import { Duplex } from "node:stream";
+import type { Socket } from "node:net";
+import { runTransportContract } from "../../../tests/utils/transportContract";
+import { TransportNode } from "./transport";
+import { Utils, Types } from "@meshtastic/core";
+
+function isStatusEvent(
+  out: Types.DeviceOutput | undefined,
+): out is Extract<Types.DeviceOutput, { type: "status" }> {
+  return !!out && (out as any).type === "status";
+}
+
+class FakeSocket extends Duplex {
+  public lastWritten: Uint8Array | undefined;
+
+  constructor() {
+    super({ objectMode: false });
+  }
+
+  _read() {}
+
+  _write(
+    chunk: Buffer,
+    _encoding: BufferEncoding,
+    callback: (error?: Error | null) => void,
+  ) {
+    this.lastWritten = new Uint8Array(
+      chunk.buffer,
+      chunk.byteOffset,
+      chunk.byteLength,
+    );
+    callback();
+  }
+
+  pushIncoming(data: Uint8Array) {
+    const buf = Buffer.from(data.buffer, data.byteOffset, data.byteLength);
+    this.push(buf);
+  }
+
+  emitErrorOnce(message = "simulated error") {
+    this.emit("error", new Error(message));
+  }
+
+  emitClose() {
+    this.emit("close");
+  }
+
+  override destroy(error?: Error) {
+    super.destroy(error);
+    this.emit("close");
+    return this;
+  }
+}
+
+function stubCoreTransforms() {
+  const toDevice = new TransformStream<Uint8Array, Uint8Array>({
+    transform(chunk, controller) {
+      controller.enqueue(chunk);
+    },
+  });
+
+  const fromDeviceFactory = () =>
+    new TransformStream<Uint8Array, Types.DeviceOutput>({
+      transform(chunk, controller) {
+        controller.enqueue({ type: "packet", data: chunk });
+      },
+    });
+
+  vi.spyOn(Utils, "toDeviceStream", "get").mockReturnValue(
+    toDevice as unknown as typeof Utils.toDeviceStream,
+  );
+
+  vi
+    .spyOn(Utils, "fromDeviceStream")
+    .mockImplementation(
+      () =>
+        fromDeviceFactory() as unknown as TransformStream<
+          Uint8Array,
+          Types.DeviceOutput
+        >,
+    );
+
+  return {
+    restore: () => vi.restoreAllMocks(),
+  };
+}
+
+describe("TransportNode (contract)", () => {
+  let transformsStub: { restore: () => void } | undefined;
+
+  beforeEach(() => {
+    transformsStub = stubCoreTransforms();
+  });
+
+  afterEach(() => {
+    transformsStub?.restore();
+  });
+
+  runTransportContract({
+    name: "TransportNode",
+    setup: () => {},
+    teardown: () => {
+      vi.restoreAllMocks();
+    },
+    create: async () => {
+      const fakeSocket = new FakeSocket();
+      const transport = new TransportNode(fakeSocket as unknown as Socket);
+      await Promise.resolve();
+      (globalThis as unknown as { __nodeSock: FakeSocket }).__nodeSock =
+        fakeSocket;
+      return transport;
+    },
+    pushIncoming: async (bytes) => {
+      (globalThis as unknown as { __nodeSock: FakeSocket }).__nodeSock.pushIncoming(
+        bytes,
+      );
+      await Promise.resolve();
+    },
+    assertLastWritten: (bytes) => {
+      const sock = (globalThis as unknown as { __nodeSock: FakeSocket })
+        .__nodeSock;
+      expect(sock.lastWritten).toBeDefined();
+      expect(sock.lastWritten).toEqual(bytes);
+    },
+    triggerDisconnect: async () => {
+      (globalThis as unknown as { __nodeSock: FakeSocket }).__nodeSock.emitErrorOnce(
+        "test-disconnect",
+      );
+      await Promise.resolve();
+    },
+  });
+});
+
+describe("TransportNode (extras)", () => {
+  let transformsStub: { restore: () => void } | undefined;
+
+  beforeEach(() => {
+    transformsStub = stubCoreTransforms();
+  });
+
+  afterEach(() => {
+    transformsStub?.restore();
+  });
+
+  it("emits DeviceDisconnected with reason 'socket-closed' on close event", async () => {
+    const fakeSocket = new FakeSocket();
+    const transport = new TransportNode(fakeSocket as unknown as Socket);
+    const reader = transport.fromDevice.getReader();
+
+    await Promise.resolve();
+
+    const first = await reader.read();
+    expect(isStatusEvent(first.value)).toBe(true);
+    if (isStatusEvent(first.value)) {
+      expect(first.value.data.status).toBe(
+        Types.DeviceStatusEnum.DeviceConnecting,
+      );
+    }
+
+    const second = await reader.read();
+    expect(isStatusEvent(second.value)).toBe(true);
+    if (isStatusEvent(second.value)) {
+      expect(second.value.data.status).toBe(
+        Types.DeviceStatusEnum.DeviceConnected,
+      );
+    }
+
+    fakeSocket.emitClose();
+    await Promise.resolve();
+
+    let sawClosed = false;
+    for (let i = 0; i < 6; i++) {
+      const { value } = await reader.read();
+      if (isStatusEvent(value) && value.data.reason === "socket-closed") {
+        sawClosed = true;
+        break;
+      }
+    }
+    expect(sawClosed).toBe(true);
+
+    reader.releaseLock();
+    await transport.disconnect();
+  });
+
+});
@@ -1,12 +1,25 @@
 import { Socket } from "node:net";
 import { Readable, Writable } from "node:stream";
-import type { Types } from "@meshtastic/core";
-import { Utils } from "@meshtastic/core";
+import { Types, Utils } from "@meshtastic/core";

+/**
+ * Node.js TCP transport for Meshtastic.
+ *
+ * Implements {@link Types.Transport} on top of a Node `net.Socket`.
+ * Use {@link TransportNode.create} to open a new connection, or
+ * construct directly with an existing socket.
+ */
 export class TransportNode implements Types.Transport {
  private readonly _toDevice: WritableStream<Uint8Array>;
  private readonly _fromDevice: ReadableStream<Types.DeviceOutput>;
+  private fromDeviceController?: ReadableStreamDefaultController<Types.DeviceOutput>;
  private socket: Socket | undefined;
+  private pipePromise?: Promise<void>;
+  private abortController: AbortController;
+  private lastStatus: Types.DeviceStatusEnum =
+    Types.DeviceStatusEnum.DeviceDisconnected;
+
+  private closingByUser = false;

  /**
   * Creates and connects a new TransportNode instance.
@@ -38,47 +51,131 @@ export class TransportNode implements Types.Transport {
   */
  constructor(connection: Socket) {
    this.socket = connection;
+
    this.socket.on("error", (err) => {
      console.error("Socket connection error:", err);
+      if (!this.closingByUser) {
+        this.emitStatus(
+          Types.DeviceStatusEnum.DeviceDisconnected,
+          "socket-error",
+        );
+      }
    });

+    this.socket.on("close", () => {
+      if (this.closingByUser) {
+        return; // suppress close-derived disconnect in user flow
+      }
+      this.emitStatus(
+        Types.DeviceStatusEnum.DeviceDisconnected,
+        "socket-closed",
+      );
+    });
+
+    this.abortController = new AbortController();
+    const abortController = this.abortController;
+
    const fromDeviceSource = Readable.toWeb(
      connection,
    ) as ReadableStream<Uint8Array>;
-    this._fromDevice = fromDeviceSource.pipeThrough(Utils.fromDeviceStream());
+    const transformed = fromDeviceSource.pipeThrough(Utils.fromDeviceStream());
+
+    this._fromDevice = new ReadableStream<Types.DeviceOutput>({
+      start: async (ctrl) => {
+        this.fromDeviceController = ctrl;
+
+        this.emitStatus(Types.DeviceStatusEnum.DeviceConnecting);
+        this.emitStatus(Types.DeviceStatusEnum.DeviceConnected);
+
+        const reader = transformed.getReader();
+        try {
+          while (true) {
+            const { value, done } = await reader.read();
+            if (done) {
+              break;
+            }
+            ctrl.enqueue(value);
+          }
+          ctrl.close();
+        } catch (error) {
+          if (this.closingByUser) {
+            ctrl.close();
+          } else {
+            this.emitStatus(
+              Types.DeviceStatusEnum.DeviceDisconnected,
+              "read-error",
+            );
+
+            ctrl.error(
+              error instanceof Error ? error : new Error(String(error)),
+            );
+          }
+          try {
+            await transformed.cancel();
+          } catch {}
+        } finally {
+          reader.releaseLock();
+        }
+      },
+    });

    // Stream for data going FROM the application TO the Meshtastic device.
    const toDeviceTransform = Utils.toDeviceStream;
    this._toDevice = toDeviceTransform.writable;

-    // The readable end of the transform is then piped to the Node.js socket.
-    // A similar assertion is needed here because `Writable.toWeb` also returns
-    // a generically typed stream (`WritableStream<any>`).
-    toDeviceTransform.readable
-      .pipeTo(Writable.toWeb(connection) as WritableStream<Uint8Array>)
+    this.pipePromise = toDeviceTransform.readable
+      .pipeTo(Writable.toWeb(connection) as WritableStream<Uint8Array>, {
+        signal: abortController.signal,
+      })
      .catch((err) => {
+        if (abortController.signal.aborted) {
+          return;
+        }
        console.error("Error piping data to socket:", err);
-        this.socket.destroy(err as Error);
+        const error = err instanceof Error ? err : new Error(String(err));
+        this.socket?.destroy(error);
      });
  }

-  /**
-   * The WritableStream to send data to the Meshtastic device.
-   */
+  /** WritableStream to send data to the device. */
  public get toDevice(): WritableStream<Uint8Array> {
    return this._toDevice;
  }

-  /**
-   * The ReadableStream to receive data from the Meshtastic device.
-   */
+  /** ReadableStream to receive data from the device. */
  public get fromDevice(): ReadableStream<Types.DeviceOutput> {
    return this._fromDevice;
  }

-  disconnect() {
-    this.socket.destroy();
-    this.socket = undefined;
-    return Promise.resolve();
+  /**
+   * Disconnect from the TCP socket and emit `DeviceDisconnected("user")`.
+   * Safe to call multiple times.
+   */
+  async disconnect(): Promise<void> {
+    try {
+      this.closingByUser = true;
+      this.emitStatus(Types.DeviceStatusEnum.DeviceDisconnected, "user");
+
+      this.abortController.abort();
+      if (this.pipePromise) {
+        await this.pipePromise;
+      }
+
+      this.socket?.destroy();
+    } finally {
+      this.socket = undefined;
+      this.closingByUser = false;
+    }
+  }
+
+  private emitStatus(next: Types.DeviceStatusEnum, reason?: string): void {
+    if (next === this.lastStatus) {
+      return;
+    }
+    this.lastStatus = next;
+    this.fromDeviceController?.enqueue({
+      type: "status",
+      data: { status: next, reason },
+    });
  }
 }