@yume-chan/adb 2.6.0 → 3.0.0-beta.0

package/src/features-value.ts

@@ -0,0 +1,47 @@
+// cspell: ignore Libusb
+// cspell: ignore devraw
+// cspell: ignore Openscreen
+// cspell: ignore devicetracker
+
+// The order follows
+// https://cs.android.com/android/platform/superproject/main/+/main:packages/modules/adb/transport.cpp;l=81;drc=2d3e62c2af54a3e8f8803ea10492e63b8dfe709f
+
+export const Shell2 = "shell_v2";
+export const Cmd = "cmd";
+export const Stat2 = "stat_v2";
+export const Ls2 = "ls_v2";
+/**
+ * server only
+ */
+export const Libusb = "libusb";
+/**
+ * server only
+ */
+export const PushSync = "push_sync";
+export const Apex = "apex";
+export const FixedPushMkdir = "fixed_push_mkdir";
+export const Abb = "abb";
+export const FixedPushSymlinkTimestamp = "fixed_push_symlink_timestamp";
+export const AbbExec = "abb_exec";
+export const RemountShell = "remount_shell";
+export const TrackApp = "track_app";
+export const SendReceive2 = "sendrecv_v2";
+export const SendReceive2Brotli = "sendrecv_v2_brotli";
+export const SendReceive2Lz4 = "sendrecv_v2_lz4";
+export const SendReceive2Zstd = "sendrecv_v2_zstd";
+export const SendReceive2DryRunSend = "sendrecv_v2_dry_run_send";
+export const DelayedAck = "delayed_ack";
+/**
+ * server only
+ */
+export const OpenscreenMdns = "openscreen_mdns";
+/**
+ * server only
+ */
+export const DeviceTrackerProtoFormat = "devicetracker_proto_format";
+export const DevRaw = "devraw";
+export const AppInfo = "app_info";
+/**
+ * server only
+ */
+export const ServerStatus = "server_status";

package/src/features.ts

@@ -1,15 +1,32 @@
-// The order follows
-// https://cs.android.com/android/platform/superproject/+/master:packages/modules/adb/transport.cpp;l=77;drc=6d14d35d0241f6fee145f8e54ffd77252e8d29fd
-export const AdbFeature = {
-    ShellV2: "shell_v2",
-    Cmd: "cmd",
-    StatV2: "stat_v2",
-    ListV2: "ls_v2",
-    FixedPushMkdir: "fixed_push_mkdir",
-    Abb: "abb",
-    AbbExec: "abb_exec",
-    SendReceiveV2: "sendrecv_v2",
-    DelayedAck: "delayed_ack",
-} as const;
+import * as AdbFeature from "./features-value.js";
 
-export type AdbFeature = (typeof AdbFeature)[keyof typeof AdbFeature];
+// biome-ignore lint/suspicious/noRedeclare: TypeScript declaration merging for enum-like object
+type AdbFeature = (typeof AdbFeature)[keyof typeof AdbFeature];
+
+export { AdbFeature };
+
+// https://android.googlesource.com/platform/packages/modules/adb/+/79010dc6d5ca7490c493df800d4421730f5466ca/transport.cpp#1252
+// There are some other feature constants, but some of them are only used by ADB server, not devices (daemons).
+export const AdbDeviceFeatures = [
+    AdbFeature.Shell2,
+    AdbFeature.Cmd,
+    AdbFeature.Stat2,
+    AdbFeature.Ls2,
+    AdbFeature.FixedPushMkdir,
+    AdbFeature.Apex,
+    AdbFeature.Abb,
+    // only tells the client the symlink timestamp issue in `adb push --sync` has been fixed.
+    // No special handling required.
+    AdbFeature.FixedPushSymlinkTimestamp,
+    AdbFeature.AbbExec,
+    AdbFeature.RemountShell,
+    AdbFeature.TrackApp,
+    AdbFeature.SendReceive2,
+    AdbFeature.SendReceive2Brotli,
+    AdbFeature.SendReceive2Lz4,
+    AdbFeature.SendReceive2Zstd,
+    AdbFeature.SendReceive2DryRunSend,
+    AdbFeature.DevRaw,
+    AdbFeature.AppInfo,
+    AdbFeature.DelayedAck,
+] as readonly AdbFeature[];

package/src/index.ts

@@ -1,8 +1,8 @@
 export * from "./adb.js";
 export * from "./banner.js";
-export * from "./commands/index.js";
 export * from "./daemon/index.js";
 export * from "./device-observer.js";
 export * from "./features.js";
 export * from "./server/index.js";
+export * from "./service/index.js";
 export * from "./utils/index.js";

package/src/server/client.ts

@@ -1,7 +1,6 @@
 // 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 {
@@ -11,7 +10,7 @@ import type {
 } from "@yume-chan/stream-extra";
 import { AbortController } from "@yume-chan/stream-extra";
 
-import type { AdbIncomingSocketHandler, AdbSocket, Closeable } from "../adb.js";
+import type { Closeable } from "../adb.js";
 import { Adb } from "../adb.js";
 import { AdbBanner } from "../banner.js";
 import type { DeviceObserver as DeviceObserverBase } from "../device-observer.js";
@@ -25,14 +24,53 @@ import {
     NetworkError as _NetworkError,
     UnauthorizedError as _UnauthorizedError,
 } from "./commands/index.js";
+import { AdbServerDataConnection } from "./data-connection.js";
 import { AdbServerDeviceObserverOwner } from "./observer.js";
-import { AdbServerStream } from "./stream.js";
 import { AdbServerTransport } from "./transport.js";
 
+const KeyTransportId = " transport_id:";
+const KeyDevice = " device:";
+const KeyModel = " model:";
+const KeyProduct = " product:";
+
+function parseDeviceLineItem<
+    T extends string = string,
+    Optional extends boolean = false,
+>(
+    line: string,
+    end: number,
+    key: string,
+    optional?: Optional,
+): readonly [start: number, value: Optional extends false ? T : T | undefined] {
+    const start = line.lastIndexOf(key, end - 1);
+    if (start === -1) {
+        if (optional) {
+            return [end, undefined as never] as const;
+        } else {
+            throw new Error(`Invalid device line: ${line}`);
+        }
+    }
+    return [start, line.substring(start + key.length, end) as T] as const;
+}
+
 /**
  * Client for the ADB Server.
  */
 export class AdbServerClient {
+    // https://android.googlesource.com/platform/packages/modules/adb/+/9f298fb1f3317371b49439efb20a598b3a881bf3/adb.cpp#144
+    static ConnectionState = [
+        "offline",
+        "bootloader",
+        "device",
+        "host",
+        "recovery",
+        "rescue",
+        "sideload",
+        "unauthorized",
+        "authorizing",
+        "detached",
+    ] as const;
+
     static NetworkError = _NetworkError;
     static UnauthorizedError = _UnauthorizedError;
     static AlreadyConnectedError = _AlreadyConnectedError;
@@ -50,37 +88,46 @@ export class AdbServerClient {
                 continue;
             }
 
-            const parts = line.split(" ").filter(Boolean);
-            const serial = parts[0]!;
-            const state = parts[1]! as AdbServerClient.ConnectionState;
+            // Parse backwards because `serial` might contain spaces.
+
+            let end = line.length;
+            let value: string;
+
+            // transport_id:123
+            // eslint-disable-next-line prefer-const
+            [end, value] = parseDeviceLineItem(line, end, KeyTransportId);
+            const transportId = BigInt(value);
+
+            // device:abc (optional)
+            let device: string | undefined;
+            // eslint-disable-next-line prefer-const
+            [end, device] = parseDeviceLineItem(line, end, KeyDevice, true);
+
+            // model:abc (optional)
+            let model: string | undefined;
+            // eslint-disable-next-line prefer-const
+            [end, model] = parseDeviceLineItem(line, end, KeyModel, true);
+
+            // product:abc (optional)
+            let product: string | undefined;
+            // eslint-disable-next-line prefer-const
+            [end, product] = parseDeviceLineItem(line, end, KeyProduct, true);
+
+            let state: AdbServerClient.ConnectionState;
+            do {
+                // devpath or state
+                // devpath doesn't have a fixed pattern
+                // (for example, libusb driver gives plain strings like `5-1.4`)
+                // so keep parsing until we get a valid state
+                [end, state] = parseDeviceLineItem(line, end, " ");
+            } while (!AdbServerClient.ConnectionState.includes(state));
+
             if (!includeStates.includes(state)) {
                 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}`);
-            }
+            const serial = line.substring(0, end).trim();
+
             devices.push({
                 serial,
                 state,
@@ -129,24 +176,16 @@ export class AdbServerClient {
     async createConnection(
         request: string,
         options?: AdbServerClient.ServerConnectionOptions,
-    ): Promise<AdbServerStream> {
+    ): Promise<AdbServerDataConnection> {
         const connection = await this.connector.connect(options);
-        const stream = new AdbServerStream(connection);
-
-        try {
-            await stream.writeString(request);
-        } catch (e) {
-            await stream.dispose();
-            throw e;
-        }
+        const dataConnection = new AdbServerDataConnection(connection);
 
         try {
-            // `raceSignal` throws when the signal is aborted,
-            // so the `catch` block can close the connection.
-            await raceSignal(() => stream.readOkay(), options?.signal);
-            return stream;
+            await dataConnection.writeString(request);
+            await dataConnection.readOkay();
+            return dataConnection;
         } catch (e) {
-            await stream.dispose();
+            await dataConnection.dispose();
             throw e;
         }
     }
@@ -271,13 +310,13 @@ export class AdbServerClient {
             "host:features",
         );
         // Luckily `AdbServerClient.Socket` is compatible with `AdbServerClient.ServerConnection`
-        const stream = new AdbServerStream(connection);
+        const dataConnection = new AdbServerDataConnection(connection);
         try {
-            const featuresString = await stream.readString();
+            const featuresString = await dataConnection.readString();
             const features = featuresString.split(",") as AdbFeature[];
             return { transportId: connection.transportId, features };
         } finally {
-            await stream.dispose();
+            await dataConnection.dispose();
         }
     }
 
@@ -316,12 +355,7 @@ export class AdbServerClient {
 
         try {
             await connection.writeString(service);
-        } catch (e) {
-            await connection.dispose();
-            throw e;
-        }
 
-        try {
             if (transportId === undefined) {
                 const array = await connection.readExactly(8);
                 transportId = getUint64LittleEndian(array, 0);
@@ -348,17 +382,14 @@ export class AdbServerClient {
             throw e;
         }
     }
+
     async #waitForUnchecked(
         device: AdbServerClient.DeviceSelector,
         state: "device" | "disconnect",
         options?: AdbServerClient.ServerConnectionOptions,
     ): Promise<void> {
         let type: string;
-        if (!device) {
-            type = "any";
-        } else if ("transportId" in device) {
-            type = "any";
-        } else if ("serial" in device) {
+        if (!device || "transportId" in device || "serial" in device) {
             type = "any";
         } else if ("usb" in device) {
             type = "usb";
@@ -425,12 +456,12 @@ export class AdbServerClient {
                             (device) => device.transportId === transportId,
                         )
                     ) {
-                        observer.stop();
+                        observer.close();
                         resolve();
                     }
                 });
                 observer.onError((e) => {
-                    observer.stop();
+                    observer.close();
                     reject(e);
                 });
             });
@@ -483,37 +514,6 @@ export class AdbServerClient {
     }
 }
 
-export async function raceSignal<T>(
-    callback: () => PromiseLike<T>,
-    ...signals: (AbortSignal | undefined)[]
-): Promise<T> {
-    const abortPromise = new PromiseResolver<never>();
-    function abort(this: AbortSignal) {
-        abortPromise.reject(this.reason);
-    }
-
-    try {
-        for (const signal of signals) {
-            if (!signal) {
-                continue;
-            }
-            if (signal.aborted) {
-                throw signal.reason;
-            }
-            signal.addEventListener("abort", abort);
-        }
-
-        return await Promise.race([callback(), abortPromise.promise]);
-    } finally {
-        for (const signal of signals) {
-            if (!signal) {
-                continue;
-            }
-            signal.removeEventListener("abort", abort);
-        }
-    }
-}
-
 export namespace AdbServerClient {
     export interface ServerConnectionOptions {
         unref?: boolean | undefined;
@@ -521,7 +521,8 @@ export namespace AdbServerClient {
     }
 
     export interface ServerConnection
-        extends ReadableWritablePair<Uint8Array, MaybeConsumable<Uint8Array>>,
+        extends
+            ReadableWritablePair<Uint8Array, MaybeConsumable<Uint8Array>>,
             Closeable {
         get closed(): Promise<undefined>;
     }
@@ -532,7 +533,7 @@ export namespace AdbServerClient {
         ): MaybePromiseLike<ServerConnection>;
 
         addReverseTunnel(
-            handler: AdbIncomingSocketHandler,
+            handler: Adb.IncomingSocketHandler,
             address?: string,
         ): MaybePromiseLike<string>;
 
@@ -541,7 +542,7 @@ export namespace AdbServerClient {
         clearReverseTunnels(): MaybePromiseLike<void>;
     }
 
-    export interface Socket extends AdbSocket {
+    export interface Socket extends Adb.Socket {
         transportId: bigint;
     }
 
@@ -555,7 +556,8 @@ export namespace AdbServerClient {
         | { tcp: true }
         | undefined;
 
-    export type ConnectionState = "unauthorized" | "offline" | "device";
+    export type ConnectionState =
+        (typeof AdbServerClient.ConnectionState)[number];
 
     export interface Device {
         serial: string;

package/src/server/commands/wireless.ts

@@ -2,7 +2,7 @@
 
 import { hexToNumber, sequenceEqual } from "../../utils/index.js";
 import type { AdbServerClient } from "../client.js";
-import { FAIL } from "../stream.js";
+import { FAIL } from "../data-connection.js";
 
 export class NetworkError extends Error {
     constructor(message: string) {

package/src/server/{stream.ts → data-connection.ts}

@@ -19,7 +19,7 @@ import type { AdbServerClient } from "./client.js";
 const OKAY = encodeUtf8("OKAY");
 export const FAIL = encodeUtf8("FAIL");
 
-export class AdbServerStream {
+export class AdbServerDataConnection {
     #connection: AdbServerClient.ServerConnection;
     #buffered: BufferedReadableStream;
     #writer: WritableStreamDefaultWriter<Uint8Array>;
@@ -34,7 +34,7 @@ export class AdbServerStream {
         return this.#buffered.readExactly(length);
     }
 
-    readString = bipedal(function* (this: AdbServerStream, then) {
+    readString = bipedal(function* (this: AdbServerDataConnection, then) {
         const data = yield* then(this.readExactly(4));
         const length = hexToNumber(data);
         if (length === 0) {
@@ -93,8 +93,8 @@ export class AdbServerStream {
     }
 
     async dispose() {
-        void tryCancel(this.#buffered);
-        void tryClose(this.#writer);
+        await tryCancel(this.#buffered);
+        await tryClose(this.#writer);
         await this.#connection.close();
     }
 }

package/src/server/index.ts

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

package/src/server/observer.ts

@@ -3,7 +3,7 @@ import { EventEmitter, StickyEventEmitter } from "@yume-chan/event";
 import { Ref } from "../utils/index.js";
 
 import { AdbServerClient } from "./client.js";
-import type { AdbServerStream } from "./stream.js";
+import type { AdbServerDataConnection } from "./data-connection.js";
 
 export function unorderedRemove<T>(array: T[], index: number) {
     if (index < 0 || index >= array.length) {
@@ -33,14 +33,14 @@ export class AdbServerDeviceObserverOwner {
 
     readonly #client: AdbServerClient;
 
-    #stream: Promise<AdbServerStream> | undefined;
+    #stream: Promise<AdbServerDataConnection> | undefined;
     #observers: Observer[] = [];
 
     constructor(client: AdbServerClient) {
         this.#client = client;
     }
 
-    async #receive(stream: AdbServerStream) {
+    async #receive(stream: AdbServerDataConnection) {
         const response = await stream.readString();
         const next = AdbServerClient.parseDeviceList(response);
 
@@ -93,7 +93,7 @@ export class AdbServerDeviceObserverOwner {
         }
     }
 
-    async #receiveLoop(stream: AdbServerStream) {
+    async #receiveLoop(stream: AdbServerDataConnection) {
         try {
             while (true) {
                 await this.#receive(stream);
@@ -123,10 +123,10 @@ export class AdbServerDeviceObserverOwner {
         return stream;
     }
 
-    async #handleObserverStop(stream: AdbServerStream) {
+    async #handleObserverClose(connection: AdbServerDataConnection) {
         if (this.#observers.length === 0) {
             this.#stream = undefined;
-            await stream.dispose();
+            await connection.dispose();
         }
     }
 
@@ -135,7 +135,6 @@ export class AdbServerDeviceObserverOwner {
     ): Promise<AdbServerClient.DeviceObserver> {
         options?.signal?.throwIfAborted();
 
-        let current: readonly AdbServerClient.Device[] = [];
         const onDeviceAdd = new EventEmitter<
             readonly AdbServerClient.Device[]
         >();
@@ -162,12 +161,9 @@ export class AdbServerDeviceObserverOwner {
         // So `#handleObserverStop` knows if there is any observer.
         this.#observers.push(observer);
 
-        // Read the filtered `current` value from `onListChange` event
-        onListChange.event((value) => (current = value));
-
-        let stream: AdbServerStream;
+        let stream: AdbServerDataConnection;
         if (!this.#stream) {
-            // `#connect` will initialize `onListChange` and `current`
+            // `#connect` will initialize `onListChange`
             this.#stream = this.#connect();
 
             try {
@@ -178,25 +174,31 @@ export class AdbServerDeviceObserverOwner {
             }
         } else {
             stream = await this.#stream;
-            // Initialize `onListChange` and `current` ourselves
+            // Initialize `onListChange` ourselves
             onListChange.fire(filterDeviceStates(this.current, includeStates));
         }
 
         const ref = new Ref(options);
 
-        const stop = async () => {
+        const close = async () => {
+            onDeviceAdd.dispose();
+            onDeviceRemove.dispose();
+            onListChange.dispose();
+            onError.dispose();
+
             unorderedRemove(this.#observers, this.#observers.indexOf(observer));
-            await this.#handleObserverStop(stream);
+            await this.#handleObserverClose(stream);
+
             ref.unref();
         };
 
         if (options?.signal) {
             if (options.signal.aborted) {
-                await stop();
+                await close();
                 throw options.signal.reason;
             }
 
-            options.signal.addEventListener("abort", () => void stop());
+            options.signal.addEventListener("abort", () => void close());
         }
 
         return {
@@ -205,9 +207,9 @@ export class AdbServerDeviceObserverOwner {
             onListChange: onListChange.event,
             onError: onError.event,
             get current() {
-                return current;
+                return onListChange.value;
             },
-            stop,
+            close,
         };
     }
 }

package/src/server/transport.ts

@@ -1,37 +1,11 @@
 import { PromiseResolver } from "@yume-chan/async";
 
-import type {
-    AdbIncomingSocketHandler,
-    AdbSocket,
-    AdbTransport,
-} from "../adb.js";
+import type { Adb, AdbTransport } from "../adb.js";
 import type { AdbBanner } from "../banner.js";
-import { AdbFeature } from "../features.js";
+import { AdbDeviceFeatures } from "../features.js";
 
 import type { AdbServerClient } from "./client.js";
 
-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 readonly AdbFeature[])();
-
 export class AdbServerTransport implements AdbTransport {
     #client: AdbServerClient;
 
@@ -43,7 +17,7 @@ export class AdbServerTransport implements AdbTransport {
 
     readonly banner: AdbBanner;
 
-    #sockets: AdbSocket[] = [];
+    #sockets: Adb.Socket[] = [];
 
     #closed = new PromiseResolver<void>();
     #disconnected: Promise<void>;
@@ -52,9 +26,14 @@ export class AdbServerTransport implements AdbTransport {
     }
 
     get clientFeatures() {
-        // No need to get host features (features supported by ADB server)
-        // Because we create all ADB packets ourselves
-        return ADB_SERVER_DEFAULT_FEATURES;
+        // This list tells the `Adb` instance how to invoke some commands.
+        //
+        // Because all device commands are created by the `Adb` instance, not ADB server,
+        // we don't need to fetch current server's feature list using `host-features` command.
+        //
+        // And because all server commands are created by the `AdbServerClient` instance, not `Adb`,
+        // we don't need to pass server-only features to `Adb` in this list.
+        return AdbDeviceFeatures;
     }
 
     // eslint-disable-next-line @typescript-eslint/max-params
@@ -73,7 +52,7 @@ export class AdbServerTransport implements AdbTransport {
         this.#disconnected = Promise.race([this.#closed.promise, disconnected]);
     }
 
-    async connect(service: string): Promise<AdbSocket> {
+    async connect(service: string): Promise<Adb.Socket> {
         const socket = await this.#client.createDeviceConnection(
             { transportId: this.transportId },
             service,
@@ -83,7 +62,7 @@ export class AdbServerTransport implements AdbTransport {
     }
 
     async addReverseTunnel(
-        handler: AdbIncomingSocketHandler,
+        handler: Adb.IncomingSocketHandler,
         address?: string,
     ): Promise<string> {
         return await this.#client.connector.addReverseTunnel(handler, address);

package/src/{commands → service}/index.ts

@@ -1,7 +1,6 @@
-export * from "./base.js";
 export * from "./framebuffer.js";
 export * from "./power.js";
-export * from "./reverse.js";
+export * from "./reverse/index.js";
 export * from "./subprocess/index.js";
 export * from "./sync/index.js";
 export * from "./tcpip.js";