@yume-chan/adb 0.0.24 → 1.1.0

package/src/server/client.ts

@@ -1,148 +1,110 @@
 // cspell:ignore tport
 
+import type { MaybePromiseLike } from "@yume-chan/async";
 import { PromiseResolver } from "@yume-chan/async";
+import type { Event } from "@yume-chan/event";
 import { getUint64LittleEndian } from "@yume-chan/no-data-view";
 import type {
     AbortSignal,
-    ReadableWritablePair,
-    WritableStreamDefaultWriter,
-} from "@yume-chan/stream-extra";
-import {
-    BufferedReadableStream,
     MaybeConsumable,
-    WrapWritableStream,
+    ReadableWritablePair,
 } from "@yume-chan/stream-extra";
-import type { ValueOrPromise } from "@yume-chan/struct";
-import {
-    EMPTY_UINT8_ARRAY,
-    SyncPromise,
-    decodeUtf8,
-    encodeUtf8,
-} from "@yume-chan/struct";
+import { AbortController } from "@yume-chan/stream-extra";
 
 import type { AdbIncomingSocketHandler, AdbSocket, Closeable } from "../adb.js";
 import { AdbBanner } from "../banner.js";
+import type { DeviceObserver as DeviceObserverBase } from "../device-observer.js";
 import type { AdbFeature } from "../features.js";
-import {
-    NOOP,
-    hexToNumber,
-    sequenceEqual,
-    write4HexDigits,
-} from "../utils/index.js";
+import { hexToNumber, sequenceEqual } from "../utils/index.js";
 
+import { AdbServerDeviceObserverOwner } from "./observer.js";
+import { AdbServerStream, FAIL } from "./stream.js";
 import { AdbServerTransport } from "./transport.js";
 
-const OKAY = encodeUtf8("OKAY");
-const FAIL = encodeUtf8("FAIL");
-
-class AdbServerStream {
-    #connection: AdbServerClient.ServerConnection;
-    #buffered: BufferedReadableStream;
-    #writer: WritableStreamDefaultWriter<Uint8Array>;
-
-    constructor(connection: AdbServerClient.ServerConnection) {
-        this.#connection = connection;
-        this.#buffered = new BufferedReadableStream(connection.readable);
-        this.#writer = connection.writable.getWriter();
-    }
+/**
+ * Client for the ADB Server.
+ */
+export class AdbServerClient {
+    static parseDeviceList(value: string): AdbServerClient.Device[] {
+        const devices: AdbServerClient.Device[] = [];
+        for (const line of value.split("\n")) {
+            if (!line) {
+                continue;
+            }
 
-    readExactly(length: number): ValueOrPromise<Uint8Array> {
-        return this.#buffered.readExactly(length);
-    }
+            const parts = line.split(" ").filter(Boolean);
+            const serial = parts[0]!;
+            const status = parts[1]!;
+            if (status !== "device" && status !== "unauthorized") {
+                continue;
+            }
 
-    readString() {
-        return SyncPromise.try(() => this.readExactly(4))
-            .then((buffer) => {
-                const length = hexToNumber(buffer);
-                if (length === 0) {
-                    return EMPTY_UINT8_ARRAY;
-                } else {
-                    return this.readExactly(length);
+            let product: string | undefined;
+            let model: string | undefined;
+            let device: string | undefined;
+            let transportId: bigint | undefined;
+            for (let i = 2; i < parts.length; i += 1) {
+                const [key, value] = parts[i]!.split(":");
+                switch (key) {
+                    case "product":
+                        product = value;
+                        break;
+                    case "model":
+                        model = value;
+                        break;
+                    case "device":
+                        device = value;
+                        break;
+                    case "transport_id":
+                        transportId = BigInt(value!);
+                        break;
                 }
-            })
-            .then((buffer) => {
-                // TODO: Investigate using stream mode `TextDecoder` for long strings.
-                // Because concatenating strings uses rope data structure,
-                // which only points to the original strings and doesn't copy the data,
-                // it's more efficient than concatenating `Uint8Array`s.
-                //
-                // ```
-                // const decoder = new TextDecoder();
-                // let result = '';
-                // for await (const chunk of stream.iterateExactly(length)) {
-                //     result += decoder.decode(chunk, { stream: true });
-                // }
-                // result += decoder.decode();
-                // return result;
-                // ```
-                //
-                // Although, it will be super complex to use `SyncPromise` with async iterator,
-                // `stream.iterateExactly` need to return an
-                // `Iterator<Uint8Array | Promise<Uint8Array>>` instead of a true async iterator.
-                // Maybe `SyncPromise` should support async iterators directly.
-                return decodeUtf8(buffer);
-            })
-            .valueOrPromise();
-    }
-
-    async writeString(value: string): Promise<void> {
-        // TODO: investigate using `encodeUtf8("0000" + value)` then modifying the length
-        // That way allocates a new string (hopefully only a rope) instead of a new buffer
-        const encoded = encodeUtf8(value);
-        const buffer = new Uint8Array(4 + encoded.length);
-        write4HexDigits(buffer, 0, encoded.length);
-        buffer.set(encoded, 4);
-        await this.#writer.write(buffer);
+            }
+            if (!transportId) {
+                throw new Error(`No transport id for device ${serial}`);
+            }
+            devices.push({
+                serial,
+                authenticating: status === "unauthorized",
+                product,
+                model,
+                device,
+                transportId,
+            });
+        }
+        return devices;
     }
 
-    async readOkay(): Promise<void> {
-        const response = await this.readExactly(4);
-        if (sequenceEqual(response, OKAY)) {
-            // `OKAY` is followed by data length and data
-            // But different services want to parse the data differently
-            // So don't read the data here
-            return;
+    static formatDeviceService(
+        device: AdbServerClient.DeviceSelector,
+        command: string,
+    ) {
+        if (!device) {
+            return `host:${command}`;
         }
-
-        if (sequenceEqual(response, FAIL)) {
-            const reason = await this.readString();
-            throw new Error(reason);
+        if ("transportId" in device) {
+            return `host-transport-id:${device.transportId}:${command}`;
         }
-
-        throw new Error(`Unexpected response: ${decodeUtf8(response)}`);
-    }
-
-    release() {
-        this.#writer.releaseLock();
-        return {
-            readable: this.#buffered.release(),
-            writable: this.#connection.writable,
-            closed: this.#connection.closed,
-            close: () => this.#connection.close(),
-        };
-    }
-
-    async dispose() {
-        await this.#buffered.cancel().catch(NOOP);
-        await this.#writer.close().catch(NOOP);
-        try {
-            await this.#connection.close();
-        } catch {
-            // ignore
+        if ("serial" in device) {
+            return `host-serial:${device.serial}:${command}`;
         }
+        if ("usb" in device) {
+            return `host-usb:${command}`;
+        }
+        if ("tcp" in device) {
+            return `host-local:${command}`;
+        }
+        throw new TypeError("Invalid device selector");
     }
-}
-
-export class AdbServerClient {
-    static readonly VERSION = 41;
 
     readonly connector: AdbServerClient.ServerConnector;
 
     readonly wireless = new AdbServerClient.WirelessCommands(this);
     readonly mDns = new AdbServerClient.MDnsCommands(this);
+    #observerOwner = new AdbServerDeviceObserverOwner(this);
 
-    constructor(connection: AdbServerClient.ServerConnector) {
-        this.connector = connection;
+    constructor(connector: AdbServerClient.ServerConnector) {
+        this.connector = connector;
     }
 
     async createConnection(
@@ -184,11 +146,11 @@ export class AdbServerClient {
         }
     }
 
-    async validateVersion() {
+    async validateVersion(minimalVersion: number) {
         const version = await this.getVersion();
-        if (version !== AdbServerClient.VERSION) {
+        if (version < minimalVersion) {
             throw new Error(
-                `adb server version (${version}) doesn't match this client (${AdbServerClient.VERSION})`,
+                `adb server version (${version}) doesn't match this client (${minimalVersion})`,
             );
         }
     }
@@ -214,118 +176,28 @@ export class AdbServerClient {
         }
     }
 
-    parseDeviceList(value: string): AdbServerClient.Device[] {
-        const devices: AdbServerClient.Device[] = [];
-        for (const line of value.split("\n")) {
-            if (!line) {
-                continue;
-            }
-
-            const parts = line.split(" ").filter(Boolean);
-            const serial = parts[0]!;
-            const status = parts[1]!;
-            if (status !== "device" && status !== "unauthorized") {
-                continue;
-            }
-
-            let product: string | undefined;
-            let model: string | undefined;
-            let device: string | undefined;
-            let transportId: bigint | undefined;
-            for (let i = 2; i < parts.length; i += 1) {
-                const [key, value] = parts[i]!.split(":");
-                switch (key) {
-                    case "product":
-                        product = value;
-                        break;
-                    case "model":
-                        model = value;
-                        break;
-                    case "device":
-                        device = value;
-                        break;
-                    case "transport_id":
-                        transportId = BigInt(value!);
-                        break;
-                }
-            }
-            if (!transportId) {
-                throw new Error(`No transport id for device ${serial}`);
-            }
-            devices.push({
-                serial,
-                authenticating: status === "unauthorized",
-                product,
-                model,
-                device,
-                transportId,
-            });
-        }
-        return devices;
-    }
-
     /**
-     * `adb devices -l`
+     * Get a list of connected devices from ADB Server.
+     *
+     * Equivalent ADB Command: `adb devices -l`
      */
     async getDevices(): Promise<AdbServerClient.Device[]> {
         const connection = await this.createConnection("host:devices-l");
         try {
             const response = await connection.readString();
-            return this.parseDeviceList(response);
+            return AdbServerClient.parseDeviceList(response);
         } finally {
             await connection.dispose();
         }
     }
 
     /**
-     * Track the device list.
-     *
-     * @param signal An optional `AbortSignal` to stop tracking
-     *
-     * When `signal` is aborted, `trackDevices` will return normally, instead of throwing `signal.reason`.
+     * Monitors device list changes.
      */
-    async *trackDevices(
-        signal?: AbortSignal,
-    ): AsyncGenerator<AdbServerClient.Device[], void, void> {
-        const connection = await this.createConnection("host:track-devices-l");
-        try {
-            while (true) {
-                const response = await raceSignal(
-                    async () => await connection.readString(),
-                    signal,
-                );
-                const devices = this.parseDeviceList(response);
-                yield devices;
-            }
-        } catch (e) {
-            if (e === signal?.reason) {
-                return;
-            }
-        } finally {
-            await connection.dispose();
-        }
-    }
-
-    formatDeviceService(
-        device: AdbServerClient.DeviceSelector,
-        command: string,
-    ) {
-        if (!device) {
-            return `host:${command}`;
-        }
-        if ("transportId" in device) {
-            return `host-transport-id:${device.transportId}:${command}`;
-        }
-        if ("serial" in device) {
-            return `host-serial:${device.serial}:${command}`;
-        }
-        if ("usb" in device) {
-            return `host-usb:${command}`;
-        }
-        if ("tcp" in device) {
-            return `host-local:${command}`;
-        }
-        throw new TypeError("Invalid device selector");
+    async trackDevices(
+        options?: AdbServerClient.ServerConnectionOptions,
+    ): Promise<AdbServerClient.DeviceObserver> {
+        return this.#observerOwner.createObserver(options);
     }
 
     /**
@@ -335,7 +207,7 @@ export class AdbServerClient {
         const connection = await this.createConnection(
             device === "offline"
                 ? "host:reconnect-offline"
-                : this.formatDeviceService(device, "reconnect"),
+                : AdbServerClient.formatDeviceService(device, "reconnect"),
         );
         try {
             await connection.readString();
@@ -395,20 +267,22 @@ export class AdbServerClient {
         device: AdbServerClient.DeviceSelector,
         service: string,
     ): Promise<AdbServerClient.Socket> {
-        await this.validateVersion();
-
         let switchService: string;
         let transportId: bigint | undefined;
         if (!device) {
+            await this.validateVersion(41);
             switchService = `host:tport:any`;
         } else if ("transportId" in device) {
             switchService = `host:transport-id:${device.transportId}`;
             transportId = device.transportId;
         } else if ("serial" in device) {
+            await this.validateVersion(41);
             switchService = `host:tport:serial:${device.serial}`;
         } else if ("usb" in device) {
+            await this.validateVersion(41);
             switchService = `host:tport:usb`;
         } else if ("tcp" in device) {
+            await this.validateVersion(41);
             switchService = `host:tport:local`;
         } else {
             throw new TypeError("Invalid device selector");
@@ -437,9 +311,7 @@ export class AdbServerClient {
                 transportId,
                 service,
                 readable: socket.readable,
-                writable: new WrapWritableStream(
-                    socket.writable,
-                ).bePipedThroughFrom(new MaybeConsumable.UnwrapStream()),
+                writable: socket.writable,
                 get closed() {
                     return socket.closed;
                 },
@@ -452,18 +324,7 @@ export class AdbServerClient {
             throw e;
         }
     }
-
-    /**
-     * Wait for a device to be connected or disconnected.
-     *
-     * `adb wait-for-<state>`
-     *
-     * @param device The device selector
-     * @param state The state to wait for
-     * @param options The options
-     * @returns A promise that resolves when the condition is met.
-     */
-    async waitFor(
+    async #waitForUnchecked(
         device: AdbServerClient.DeviceSelector,
         state: "device" | "disconnect",
         options?: AdbServerClient.ServerConnectionOptions,
@@ -485,7 +346,7 @@ export class AdbServerClient {
 
         // `waitFor` can't use `connectDevice`, because the device
         // might not be available yet.
-        const service = this.formatDeviceService(
+        const service = AdbServerClient.formatDeviceService(
             device,
             `wait-for-${type}-${state}`,
         );
@@ -498,6 +359,63 @@ export class AdbServerClient {
         }
     }
 
+    /**
+     * Wait for a device to be connected or disconnected.
+     *
+     * `adb wait-for-<state>`
+     *
+     * @param device The device selector
+     * @param state The state to wait for
+     * @param options The options
+     * @returns A promise that resolves when the condition is met.
+     */
+    async waitFor(
+        device: AdbServerClient.DeviceSelector,
+        state: "device" | "disconnect",
+        options?: AdbServerClient.ServerConnectionOptions,
+    ): Promise<void> {
+        if (state === "disconnect") {
+            await this.validateVersion(41);
+        }
+
+        return this.#waitForUnchecked(device, state, options);
+    }
+
+    async waitForDisconnect(
+        transportId: bigint,
+        options?: AdbServerClient.ServerConnectionOptions,
+    ): Promise<void> {
+        const serverVersion = await this.getVersion();
+        if (serverVersion >= 41) {
+            return this.#waitForUnchecked(
+                { transportId },
+                "disconnect",
+                options,
+            );
+        } else {
+            const observer = await this.trackDevices(options);
+            return new Promise<void>((resolve, reject) => {
+                observer.onDeviceRemove((devices) => {
+                    if (
+                        devices.some(
+                            (device) => device.transportId === transportId,
+                        )
+                    ) {
+                        observer.stop();
+                        resolve();
+                    }
+                });
+                observer.onError((e) => {
+                    observer.stop();
+                    reject(e);
+                });
+            });
+        }
+    }
+
+    /**
+     * Creates an ADB Transport for the specified device.
+     */
     async createTransport(
         device: AdbServerClient.DeviceSelector,
     ): Promise<AdbServerTransport> {
@@ -515,12 +433,26 @@ export class AdbServerClient {
             features,
         );
 
-        return new AdbServerTransport(
+        const waitAbortController = new AbortController();
+        const disconnected = this.waitForDisconnect(transportId, {
+            unref: true,
+            signal: waitAbortController.signal,
+        });
+
+        const transport = new AdbServerTransport(
             this,
             info?.serial ?? "",
             banner,
             transportId,
+            disconnected,
         );
+
+        transport.disconnected.then(
+            () => waitAbortController.abort(),
+            () => waitAbortController.abort(),
+        );
+
+        return transport;
     }
 }
 
@@ -562,7 +494,7 @@ export namespace AdbServerClient {
     }
 
     export interface ServerConnection
-        extends ReadableWritablePair<Uint8Array, Uint8Array>,
+        extends ReadableWritablePair<Uint8Array, MaybeConsumable<Uint8Array>>,
             Closeable {
         get closed(): Promise<void>;
     }
@@ -570,22 +502,25 @@ export namespace AdbServerClient {
     export interface ServerConnector {
         connect(
             options?: ServerConnectionOptions,
-        ): ValueOrPromise<ServerConnection>;
+        ): MaybePromiseLike<ServerConnection>;
 
         addReverseTunnel(
             handler: AdbIncomingSocketHandler,
             address?: string,
-        ): ValueOrPromise<string>;
+        ): MaybePromiseLike<string>;
 
-        removeReverseTunnel(address: string): ValueOrPromise<void>;
+        removeReverseTunnel(address: string): MaybePromiseLike<void>;
 
-        clearReverseTunnels(): ValueOrPromise<void>;
+        clearReverseTunnels(): MaybePromiseLike<void>;
     }
 
     export interface Socket extends AdbSocket {
         transportId: bigint;
     }
 
+    /**
+     * A union type for selecting a device.
+     */
     export type DeviceSelector =
         | { transportId: bigint }
         | { serial: string }
@@ -732,4 +667,8 @@ export namespace AdbServerClient {
             }
         }
     }
+
+    export interface DeviceObserver extends DeviceObserverBase<Device> {
+        onError: Event<Error>;
+    }
 }

package/src/server/index.ts

@@ -1,2 +1,4 @@
 export * from "./client.js";
+export * from "./observer.js";
+export * from "./stream.js";
 export * from "./transport.js";