@yume-chan/adb 1.0.0 → 2.0.0

package/src/server/commands/wireless.ts

@@ -0,0 +1,94 @@
+// cspell:ignore tport
+
+import { hexToNumber, sequenceEqual } from "../../utils/index.js";
+import type { AdbServerClient } from "../client.js";
+import { FAIL } from "../stream.js";
+
+export class NetworkError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = "NetworkError";
+    }
+}
+
+export class UnauthorizedError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = "UnauthorizedError";
+    }
+}
+
+export class AlreadyConnectedError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = "AlreadyConnectedError";
+    }
+}
+
+export class WirelessCommands {
+    readonly #client: AdbServerClient;
+
+    constructor(client: AdbServerClient) {
+        this.#client = client;
+    }
+
+    /**
+     * `adb pair <password> <address>`
+     */
+    async pair(address: string, password: string): Promise<void> {
+        const connection = await this.#client.createConnection(
+            `host:pair:${password}:${address}`,
+        );
+        try {
+            const response = await connection.readExactly(4);
+            // `response` is either `FAIL`, or 4 hex digits for length of the string
+            if (sequenceEqual(response, FAIL)) {
+                throw new Error(await connection.readString());
+            }
+            const length = hexToNumber(response);
+            // Ignore the string as it's always `Successful ...`
+            await connection.readExactly(length);
+        } finally {
+            await connection.dispose();
+        }
+    }
+
+    /**
+     * `adb connect <address>`
+     */
+    async connect(address: string): Promise<void> {
+        const connection = await this.#client.createConnection(
+            `host:connect:${address}`,
+        );
+        try {
+            const response = await connection.readString();
+            switch (response) {
+                case `already connected to ${address}`:
+                    throw new AlreadyConnectedError(response);
+                case `failed to connect to ${address}`: // `adb pair` mode not authorized
+                case `failed to authenticate to ${address}`: // `adb tcpip` mode not authorized
+                    throw new UnauthorizedError(response);
+                case `connected to ${address}`:
+                    return;
+                default:
+                    throw new NetworkError(response);
+            }
+        } finally {
+            await connection.dispose();
+        }
+    }
+
+    /**
+     * `adb disconnect <address>`
+     */
+    async disconnect(address: string): Promise<void> {
+        const connection = await this.#client.createConnection(
+            `host:disconnect:${address}`,
+        );
+        try {
+            await connection.readString();
+        } finally {
+            await connection.dispose();
+        }
+    }
+}

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";

package/src/server/observer.ts

@@ -0,0 +1,172 @@
+import { EventEmitter, StickyEventEmitter } from "@yume-chan/event";
+
+import { Ref } from "../utils/index.js";
+
+import { AdbServerClient } from "./client.js";
+import type { AdbServerStream } from "./stream.js";
+
+export function unorderedRemove<T>(array: T[], index: number) {
+    if (index < 0 || index >= array.length) {
+        return;
+    }
+    array[index] = array[array.length - 1]!;
+    array.length -= 1;
+}
+
+export class AdbServerDeviceObserverOwner {
+    current: readonly AdbServerClient.Device[] = [];
+
+    readonly #client: AdbServerClient;
+    #stream: Promise<AdbServerStream> | undefined;
+    #observers: {
+        onDeviceAdd: EventEmitter<readonly AdbServerClient.Device[]>;
+        onDeviceRemove: EventEmitter<readonly AdbServerClient.Device[]>;
+        onListChange: EventEmitter<readonly AdbServerClient.Device[]>;
+        onError: EventEmitter<Error>;
+    }[] = [];
+
+    constructor(client: AdbServerClient) {
+        this.#client = client;
+    }
+
+    async #receive(stream: AdbServerStream) {
+        const response = await stream.readString();
+        const next = AdbServerClient.parseDeviceList(response);
+
+        const removed = this.current.slice();
+        const added: AdbServerClient.Device[] = [];
+        for (const nextDevice of next) {
+            const index = removed.findIndex(
+                (device) => device.transportId === nextDevice.transportId,
+            );
+
+            if (index === -1) {
+                added.push(nextDevice);
+                continue;
+            }
+
+            unorderedRemove(removed, index);
+        }
+
+        this.current = next;
+
+        if (added.length) {
+            for (const observer of this.#observers) {
+                observer.onDeviceAdd.fire(added);
+            }
+        }
+        if (removed.length) {
+            for (const observer of this.#observers) {
+                observer.onDeviceRemove.fire(removed);
+            }
+        }
+
+        for (const observer of this.#observers) {
+            observer.onListChange.fire(this.current);
+        }
+    }
+
+    async #receiveLoop(stream: AdbServerStream) {
+        try {
+            while (true) {
+                await this.#receive(stream);
+            }
+        } catch (e) {
+            this.#stream = undefined;
+
+            for (const observer of this.#observers) {
+                observer.onError.fire(e as Error);
+            }
+        }
+    }
+
+    async #connect() {
+        const stream = await this.#client.createConnection(
+            "host:track-devices-l",
+            // Each individual observer will ref depending on their options
+            { unref: true },
+        );
+
+        // Set `current` and `onListChange` value before returning
+        await this.#receive(stream);
+
+        // Then start receive loop
+        void this.#receiveLoop(stream);
+
+        return stream;
+    }
+
+    async #handleObserverStop(stream: AdbServerStream) {
+        if (this.#observers.length === 0) {
+            this.#stream = undefined;
+            await stream.dispose();
+        }
+    }
+
+    async createObserver(
+        options?: AdbServerClient.ServerConnectionOptions,
+    ): Promise<AdbServerClient.DeviceObserver> {
+        options?.signal?.throwIfAborted();
+
+        const onDeviceAdd = new EventEmitter<
+            readonly AdbServerClient.Device[]
+        >();
+        const onDeviceRemove = new EventEmitter<
+            readonly AdbServerClient.Device[]
+        >();
+        const onListChange = new StickyEventEmitter<
+            readonly AdbServerClient.Device[]
+        >();
+        const onError = new StickyEventEmitter<Error>();
+
+        const observer = { onDeviceAdd, onDeviceRemove, onListChange, onError };
+        // Register `observer` before `#connect`.
+        // So `#handleObserverStop` knows if there is any observer.
+        this.#observers.push(observer);
+
+        let stream: AdbServerStream;
+        if (!this.#stream) {
+            this.#stream = this.#connect();
+
+            try {
+                stream = await this.#stream;
+            } catch (e) {
+                this.#stream = undefined;
+                throw e;
+            }
+        } else {
+            stream = await this.#stream;
+            onListChange.fire(this.current);
+        }
+
+        const ref = new Ref(options);
+
+        const stop = async () => {
+            unorderedRemove(this.#observers, this.#observers.indexOf(observer));
+            await this.#handleObserverStop(stream);
+            ref.unref();
+        };
+
+        if (options?.signal) {
+            if (options.signal.aborted) {
+                await stop();
+                throw options.signal.reason;
+            }
+
+            options.signal.addEventListener("abort", () => void stop());
+        }
+
+        // eslint-disable-next-line @typescript-eslint/no-this-alias
+        const _this = this;
+        return {
+            onDeviceAdd: onDeviceAdd.event,
+            onDeviceRemove: onDeviceRemove.event,
+            onListChange: onListChange.event,
+            onError: onError.event,
+            get current() {
+                return _this.current;
+            },
+            stop,
+        };
+    }
+}

package/src/server/stream.ts

@@ -0,0 +1,100 @@
+import type { MaybePromiseLike } from "@yume-chan/async";
+import type { WritableStreamDefaultWriter } from "@yume-chan/stream-extra";
+import {
+    BufferedReadableStream,
+    tryCancel,
+    tryClose,
+} from "@yume-chan/stream-extra";
+import {
+    bipedal,
+    decodeUtf8,
+    encodeUtf8,
+    TextDecoder,
+} from "@yume-chan/struct";
+
+import { hexToNumber, sequenceEqual, write4HexDigits } from "../utils/index.js";
+
+import type { AdbServerClient } from "./client.js";
+
+const OKAY = encodeUtf8("OKAY");
+export const FAIL = encodeUtf8("FAIL");
+
+export 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();
+    }
+
+    readExactly(length: number): MaybePromiseLike<Uint8Array> {
+        return this.#buffered.readExactly(length);
+    }
+
+    readString = bipedal(function* (this: AdbServerStream, then) {
+        const data = yield* then(this.readExactly(4));
+        const length = hexToNumber(data);
+        if (length === 0) {
+            return "";
+        } else {
+            const decoder = new TextDecoder();
+            let result = "";
+            const iterator = this.#buffered.iterateExactly(length);
+            while (true) {
+                const { done, value } = iterator.next();
+                if (done) {
+                    break;
+                }
+                result += decoder.decode(yield* then(value), { stream: true });
+            }
+            result += decoder.decode();
+            return result;
+        }
+    });
+
+    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;
+        }
+
+        if (sequenceEqual(response, FAIL)) {
+            const reason = await this.readString();
+            throw new Error(reason);
+        }
+
+        throw new Error(`Unexpected response: ${decodeUtf8(response)}`);
+    }
+
+    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);
+    }
+
+    release() {
+        this.#writer.releaseLock();
+        return {
+            readable: this.#buffered.release(),
+            writable: this.#connection.writable,
+            closed: this.#connection.closed,
+            close: () => this.#connection.close(),
+        };
+    }
+
+    async dispose() {
+        void tryCancel(this.#buffered);
+        void tryClose(this.#writer);
+        await this.#connection.close();
+    }
+}

package/src/server/transport.ts

@@ -1,6 +1,4 @@
-import type { MaybePromiseLike } from "@yume-chan/async";
 import { PromiseResolver } from "@yume-chan/async";
-import { AbortController } from "@yume-chan/stream-extra";
 
 import type {
     AdbIncomingSocketHandler,
@@ -12,26 +10,27 @@ import { AdbFeature } from "../features.js";
 
 import type { AdbServerClient } from "./client.js";
 
-export const ADB_SERVER_DEFAULT_FEATURES = [
-    AdbFeature.ShellV2,
-    AdbFeature.Cmd,
-    AdbFeature.StatV2,
-    AdbFeature.ListV2,
-    AdbFeature.FixedPushMkdir,
-    "apex",
-    AdbFeature.Abb,
-    // only tells the client the symlink timestamp issue in `adb push --sync` has been fixed.
-    // No special handling required.
-    "fixed_push_symlink_timestamp",
-    AdbFeature.AbbExec,
-    "remount_shell",
-    "track_app",
-    AdbFeature.SendReceiveV2,
-    "sendrecv_v2_brotli",
-    "sendrecv_v2_lz4",
-    "sendrecv_v2_zstd",
-    "sendrecv_v2_dry_run_send",
-] as AdbFeature[];
+export const ADB_SERVER_DEFAULT_FEATURES = /* #__PURE__ */ (() =>
+    [
+        AdbFeature.ShellV2,
+        AdbFeature.Cmd,
+        AdbFeature.StatV2,
+        AdbFeature.ListV2,
+        AdbFeature.FixedPushMkdir,
+        "apex",
+        AdbFeature.Abb,
+        // only tells the client the symlink timestamp issue in `adb push --sync` has been fixed.
+        // No special handling required.
+        "fixed_push_symlink_timestamp",
+        AdbFeature.AbbExec,
+        "remount_shell",
+        "track_app",
+        AdbFeature.SendReceiveV2,
+        "sendrecv_v2_brotli",
+        "sendrecv_v2_lz4",
+        "sendrecv_v2_zstd",
+        "sendrecv_v2_dry_run_send",
+    ] as AdbFeature[])();
 
 export class AdbServerTransport implements AdbTransport {
     #client: AdbServerClient;
@@ -44,9 +43,13 @@ export class AdbServerTransport implements AdbTransport {
 
     readonly banner: AdbBanner;
 
+    #sockets: AdbSocket[] = [];
+
     #closed = new PromiseResolver<void>();
-    #waitAbortController = new AbortController();
-    readonly disconnected: Promise<void>;
+    #disconnected: Promise<void>;
+    get disconnected() {
+        return this.#disconnected;
+    }
 
     get clientFeatures() {
         // No need to get host features (features supported by ADB server)
@@ -54,31 +57,29 @@ export class AdbServerTransport implements AdbTransport {
         return ADB_SERVER_DEFAULT_FEATURES;
     }
 
+    // eslint-disable-next-line @typescript-eslint/max-params
     constructor(
         client: AdbServerClient,
         serial: string,
         banner: AdbBanner,
         transportId: bigint,
+        disconnected: Promise<void>,
     ) {
         this.#client = client;
         this.serial = serial;
         this.banner = banner;
         this.transportId = transportId;
 
-        this.disconnected = Promise.race([
-            this.#closed.promise,
-            client.waitFor({ transportId }, "disconnect", {
-                signal: this.#waitAbortController.signal,
-                unref: true,
-            }),
-        ]);
+        this.#disconnected = Promise.race([this.#closed.promise, disconnected]);
     }
 
     async connect(service: string): Promise<AdbSocket> {
-        return await this.#client.createDeviceConnection(
+        const socket = await this.#client.createDeviceConnection(
             { transportId: this.transportId },
             service,
         );
+        this.#sockets.push(socket);
+        return socket;
     }
 
     async addReverseTunnel(
@@ -96,8 +97,11 @@ export class AdbServerTransport implements AdbTransport {
         await this.#client.connector.clearReverseTunnels();
     }
 
-    close(): MaybePromiseLike<void> {
+    async close(): Promise<void> {
+        for (const socket of this.#sockets) {
+            await socket.close();
+        }
+        this.#sockets.length = 0;
         this.#closed.resolve();
-        this.#waitAbortController.abort();
     }
 }

package/src/utils/index.ts

@@ -3,4 +3,5 @@ export * from "./auto-reset-event.js";
 export * from "./base64.js";
 export * from "./hex.js";
 export * from "./no-op.js";
+export * from "./ref.js";
 export * from "./sequence-equal.js";

package/src/utils/ref.ts

@@ -0,0 +1,37 @@
+interface GlobalExtension {
+    setInterval: (callback: () => void, delay: number) => number;
+    clearInterval: (id: number) => void;
+}
+
+const { setInterval, clearInterval } = globalThis as unknown as GlobalExtension;
+
+/**
+ * An object to keep current Node.js process alive even when no code is running.
+ *
+ * Does nothing in Web environments.
+ *
+ * Note that it does't have reference counting. Calling `unref` will
+ * remove the ref no matter how many times `ref` has been previously called, and vice versa.
+ * This is the same as how Node.js works.
+ */
+export class Ref {
+    #intervalId: number | undefined;
+
+    constructor(options?: { unref?: boolean | undefined }) {
+        if (!options?.unref) {
+            this.ref();
+        }
+    }
+
+    ref() {
+        // `setInterval` can keep current Node.js alive, the delay value doesn't matter
+        this.#intervalId = setInterval(() => {}, 60 * 1000);
+    }
+
+    unref() {
+        if (this.#intervalId) {
+            clearInterval(this.#intervalId);
+            this.#intervalId = undefined;
+        }
+    }
+}