@yume-chan/adb 0.0.21 → 0.0.23

package/src/daemon/transport.ts

@@ -26,28 +26,79 @@ import type { AdbPacketData, AdbPacketInit } from "./packet.js";
 import { AdbCommand, calculateChecksum } from "./packet.js";
 
 export const ADB_DAEMON_VERSION_OMIT_CHECKSUM = 0x01000001;
+// 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 ADB_DAEMON_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",
+    AdbFeature.DelayedAck,
+] as AdbFeature[];
+export const ADB_DAEMON_DEFAULT_INITIAL_PAYLOAD_SIZE = 32 * 1024 * 1024;
+
+export type AdbDaemonConnection = ReadableWritablePair<
+    AdbPacketData,
+    Consumable<AdbPacketInit>
+>;
 
 interface AdbDaemonAuthenticationOptions {
     serial: string;
-    connection: ReadableWritablePair<AdbPacketData, Consumable<AdbPacketInit>>;
+    connection: AdbDaemonConnection;
     credentialStore: AdbCredentialStore;
     authenticators?: AdbAuthenticator[];
+    features?: readonly AdbFeature[];
+    /**
+     * The number of bytes the device can send before receiving an ack packet.
+     *
+     * Set to 0 or any negative value to disable delayed ack in handshake.
+     * Otherwise the value must be in the range of unsigned 32-bit integer.
+     *
+     * Delayed ack requires Android 14, this option is ignored on older versions.
+     */
+    initialDelayedAckBytes?: number;
     /**
      * Whether to preserve the connection open after the `AdbDaemonTransport` is closed.
      */
     preserveConnection?: boolean | undefined;
+    debugSlowRead?: boolean | undefined;
 }
 
 interface AdbDaemonSocketConnectorConstructionOptions {
     serial: string;
-    connection: ReadableWritablePair<AdbPacketData, Consumable<AdbPacketInit>>;
+    connection: AdbDaemonConnection;
     version: number;
     maxPayloadSize: number;
     banner: string;
+    features?: readonly AdbFeature[];
+    /**
+     * The number of bytes the device can send before receiving an ack packet.
+     *
+     * Set to 0 or any negative value to disable delayed ack in handshake.
+     * Otherwise the value must be in the range of unsigned 32-bit integer.
+     *
+     * Delayed ack requires Android 14, this option is ignored on older versions.
+     */
+    initialDelayedAckBytes?: number;
     /**
      * Whether to preserve the connection open after the `AdbDaemonTransport` is closed.
      */
     preserveConnection?: boolean | undefined;
+    debugSlowRead?: boolean | undefined;
 }
 
 export class AdbDaemonTransport implements AdbTransport {
@@ -64,7 +115,9 @@ export class AdbDaemonTransport implements AdbTransport {
         connection,
         credentialStore,
         authenticators = ADB_DEFAULT_AUTHENTICATORS,
-        preserveConnection,
+        features = ADB_DAEMON_DEFAULT_FEATURES,
+        initialDelayedAckBytes = ADB_DAEMON_DEFAULT_INITIAL_PAYLOAD_SIZE,
+        ...options
     }: AdbDaemonAuthenticationOptions): Promise<AdbDaemonTransport> {
         // Initially, set to highest-supported version and payload size.
         let version = 0x01000001;
@@ -94,9 +147,8 @@ export class AdbDaemonTransport implements AdbTransport {
                                 resolver.resolve(decodeUtf8(packet.payload));
                                 break;
                             case AdbCommand.Auth: {
-                                const response = await authProcessor.process(
-                                    packet,
-                                );
+                                const response =
+                                    await authProcessor.process(packet);
                                 await sendPacket(response);
                                 break;
                             }
@@ -138,38 +190,25 @@ export class AdbDaemonTransport implements AdbTransport {
             await ConsumableWritableStream.write(writer, init as AdbPacketInit);
         }
 
+        const actualFeatures = features.slice();
+        if (initialDelayedAckBytes <= 0) {
+            const index = features.indexOf(AdbFeature.DelayedAck);
+            if (index !== -1) {
+                actualFeatures.splice(index, 1);
+            }
+        }
+
         let banner: string;
         try {
-            // 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).
-            const 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",
-            ].join(",");
-
             await sendPacket({
                 command: AdbCommand.Connect,
                 arg0: version,
                 arg1: maxPayloadSize,
                 // The terminating `;` is required in formal definition
                 // But ADB daemon (all versions) can still work without it
-                payload: encodeUtf8(`host::features=${features}`),
+                payload: encodeUtf8(
+                    `host::features=${actualFeatures.join(",")}`,
+                ),
             });
 
             banner = await resolver.promise;
@@ -189,10 +228,17 @@ export class AdbDaemonTransport implements AdbTransport {
             version,
             maxPayloadSize,
             banner,
-            preserveConnection,
+            features: actualFeatures,
+            initialDelayedAckBytes,
+            ...options,
         });
     }
 
+    #connection: AdbDaemonConnection;
+    get connection() {
+        return this.#connection;
+    }
+
     readonly #dispatcher: AdbPacketDispatcher;
 
     #serial: string;
@@ -205,9 +251,8 @@ export class AdbDaemonTransport implements AdbTransport {
         return this.#protocolVersion;
     }
 
-    #maxPayloadSize: number;
     get maxPayloadSize() {
-        return this.#maxPayloadSize;
+        return this.#dispatcher.options.maxPayloadSize;
     }
 
     #banner: AdbBanner;
@@ -219,16 +264,38 @@ export class AdbDaemonTransport implements AdbTransport {
         return this.#dispatcher.disconnected;
     }
 
+    #clientFeatures: readonly AdbFeature[];
+    get clientFeatures() {
+        return this.#clientFeatures;
+    }
+
     constructor({
         serial,
         connection,
         version,
-        maxPayloadSize,
         banner,
-        preserveConnection,
+        features = ADB_DAEMON_DEFAULT_FEATURES,
+        initialDelayedAckBytes = ADB_DAEMON_DEFAULT_INITIAL_PAYLOAD_SIZE,
+        ...options
     }: AdbDaemonSocketConnectorConstructionOptions) {
         this.#serial = serial;
+        this.#connection = connection;
         this.#banner = AdbBanner.parse(banner);
+        this.#clientFeatures = features;
+
+        if (features.includes(AdbFeature.DelayedAck)) {
+            if (initialDelayedAckBytes <= 0) {
+                throw new Error(
+                    "`initialDelayedAckBytes` must be greater than 0 when DelayedAck feature is enabled.",
+                );
+            }
+
+            if (!this.#banner.features.includes(AdbFeature.DelayedAck)) {
+                initialDelayedAckBytes = 0;
+            }
+        } else {
+            initialDelayedAckBytes = 0;
+        }
 
         let calculateChecksum: boolean;
         let appendNullToServiceString: boolean;
@@ -243,12 +310,11 @@ export class AdbDaemonTransport implements AdbTransport {
         this.#dispatcher = new AdbPacketDispatcher(connection, {
             calculateChecksum,
             appendNullToServiceString,
-            maxPayloadSize,
-            preserveConnection,
+            initialDelayedAckBytes,
+            ...options,
         });
 
         this.#protocolVersion = version;
-        this.#maxPayloadSize = maxPayloadSize;
     }
 
     connect(service: string): ValueOrPromise<AdbSocket> {

package/src/features.ts

@@ -1,5 +1,5 @@
 // The order follows
-// https://android.googlesource.com/platform/packages/modules/adb/+/79010dc6d5ca7490c493df800d4421730f5466ca/transport.cpp#1252
+// https://cs.android.com/android/platform/superproject/+/master:packages/modules/adb/transport.cpp;l=77;drc=6d14d35d0241f6fee145f8e54ffd77252e8d29fd
 export enum AdbFeature {
     ShellV2 = "shell_v2",
     Cmd = "cmd",
@@ -9,4 +9,5 @@ export enum AdbFeature {
     Abb = "abb",
     AbbExec = "abb_exec",
     SendReceiveV2 = "sendrecv_v2",
+    DelayedAck = "delayed_ack",
 }

package/src/server/client.ts

@@ -3,13 +3,11 @@
 import { PromiseResolver } from "@yume-chan/async";
 import type {
     AbortSignal,
-    Consumable,
     ReadableWritablePair,
     WritableStreamDefaultWriter,
 } from "@yume-chan/stream-extra";
 import {
     BufferedReadableStream,
-    DuplexStreamFactory,
     UnwrapConsumableStream,
     WrapWritableStream,
 } from "@yume-chan/stream-extra";
@@ -20,15 +18,16 @@ import type {
 } from "@yume-chan/struct";
 import {
     BigIntFieldType,
+    EMPTY_UINT8_ARRAY,
     SyncPromise,
     decodeUtf8,
     encodeUtf8,
 } from "@yume-chan/struct";
 
-import type { AdbIncomingSocketHandler, AdbSocket } from "../adb.js";
+import type { AdbIncomingSocketHandler, AdbSocket, Closeable } from "../adb.js";
 import { AdbBanner } from "../banner.js";
 import type { AdbFeature } from "../features.js";
-import { NOOP, hexToNumber, numberToHex } from "../utils/index.js";
+import { NOOP, hexToNumber, numberToHex, unreachable } from "../utils/index.js";
 
 import { AdbServerTransport } from "./transport.js";
 
@@ -37,10 +36,16 @@ export interface AdbServerConnectionOptions {
     signal?: AbortSignal | undefined;
 }
 
-export interface AdbServerConnection {
+export interface AdbServerConnection
+    extends ReadableWritablePair<Uint8Array, Uint8Array>,
+        Closeable {
+    get closed(): Promise<void>;
+}
+
+export interface AdbServerConnector {
     connect(
         options?: AdbServerConnectionOptions,
-    ): ValueOrPromise<ReadableWritablePair<Uint8Array, Uint8Array>>;
+    ): ValueOrPromise<AdbServerConnection>;
 
     addReverseTunnel(
         handler: AdbIncomingSocketHandler,
@@ -57,10 +62,8 @@ export interface AdbServerSocket extends AdbSocket {
 }
 
 export type AdbServerDeviceSelector =
-    | {
-          serial: string;
-      }
     | { transportId: bigint }
+    | { serial: string }
     | { usb: true }
     | { tcp: true }
     | undefined;
@@ -76,9 +79,9 @@ export interface AdbServerDevice {
 export class AdbServerClient {
     static readonly VERSION = 41;
 
-    readonly connection: AdbServerConnection;
+    readonly connection: AdbServerConnector;
 
-    constructor(connection: AdbServerConnection) {
+    constructor(connection: AdbServerConnector) {
         this.connection = connection;
     }
 
@@ -90,7 +93,11 @@ export class AdbServerClient {
         return SyncPromise.try(() => stream.readExactly(4))
             .then((buffer) => {
                 const length = hexToNumber(buffer);
-                return stream.readExactly(length);
+                if (length === 0) {
+                    return EMPTY_UINT8_ARRAY;
+                } else {
+                    return stream.readExactly(length);
+                }
             })
             .then((valueBuffer) => {
                 return decodeUtf8(valueBuffer);
@@ -128,30 +135,41 @@ export class AdbServerClient {
     async connect(
         request: string,
         options?: AdbServerConnectionOptions,
-    ): Promise<ReadableWritablePair<Uint8Array, Uint8Array>> {
+    ): Promise<AdbServerConnection> {
         const connection = await this.connection.connect(options);
 
-        const writer = connection.writable.getWriter();
-        await AdbServerClient.writeString(writer, request);
+        try {
+            const writer = connection.writable.getWriter();
+            await AdbServerClient.writeString(writer, request);
+            writer.releaseLock();
+        } catch (e) {
+            await connection.readable.cancel();
+            await connection.close();
+            throw e;
+        }
 
         const readable = new BufferedReadableStream(connection.readable);
-
         try {
-            // `raceSignal` throws if the signal is aborted,
+            // `raceSignal` throws when the signal is aborted,
             // so the `catch` block can close the connection.
             await raceSignal(
                 () => AdbServerClient.readOkay(readable),
                 options?.signal,
             );
 
-            writer.releaseLock();
             return {
                 readable: readable.release(),
                 writable: connection.writable,
+                get closed() {
+                    return connection.closed;
+                },
+                async close() {
+                    await connection.close();
+                },
             };
         } catch (e) {
-            writer.close().catch(NOOP);
-            readable.cancel().catch(NOOP);
+            await readable.cancel().catch(NOOP);
+            await connection.close();
             throw e;
         }
     }
@@ -196,63 +214,91 @@ export class AdbServerClient {
         }
     }
 
+    parseDeviceList(value: string): AdbServerDevice[] {
+        const devices: AdbServerDevice[] = [];
+        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") {
+                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,
+                product,
+                model,
+                device,
+                transportId,
+            });
+        }
+        return devices;
+    }
+
     async getDevices(): Promise<AdbServerDevice[]> {
         const connection = await this.connect("host:devices-l");
         const readable = new BufferedReadableStream(connection.readable);
         try {
-            const devices: AdbServerDevice[] = [];
             const response = await AdbServerClient.readString(readable);
-            for (const line of response.split("\n")) {
-                if (!line) {
-                    continue;
-                }
-
-                const parts = line.split(" ").filter(Boolean);
-                const serial = parts[0]!;
-                const status = parts[1]!;
-                if (status !== "device") {
-                    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,
-                    product,
-                    model,
-                    device,
-                    transportId,
-                });
-            }
-            return devices;
+            return this.parseDeviceList(response);
         } finally {
             connection.writable.close().catch(NOOP);
             readable.cancel().catch(NOOP);
         }
     }
 
+    async trackDevices(
+        callback: (devices: AdbServerDevice[]) => void,
+    ): Promise<() => void> {
+        const connection = await this.connect("host:track-devices-l");
+        const readable = new BufferedReadableStream(connection.readable);
+        let running = true;
+        (async () => {
+            try {
+                while (running) {
+                    const response = await AdbServerClient.readString(readable);
+                    const devices = this.parseDeviceList(response);
+                    callback(devices);
+                }
+            } catch {
+                // ignore
+            }
+        })().catch(unreachable);
+        return () => {
+            running = false;
+            readable.cancel().catch(NOOP);
+            Promise.resolve(connection.close()).catch(NOOP);
+        };
+    }
+
     formatDeviceService(device: AdbServerDeviceSelector, command: string) {
         if (!device) {
             return `host:${command}`;
@@ -330,8 +376,18 @@ export class AdbServerClient {
         }
 
         const connection = await this.connect(switchService);
+
+        try {
+            const writer = connection.writable.getWriter();
+            await AdbServerClient.writeString(writer, service);
+            writer.releaseLock();
+        } catch (e) {
+            await connection.readable.cancel();
+            await connection.close();
+            throw e;
+        }
+
         const readable = new BufferedReadableStream(connection.readable);
-        const writer = connection.writable.getWriter();
         try {
             if (transportId === undefined) {
                 const array = await readable.readExactly(8);
@@ -344,34 +400,25 @@ export class AdbServerClient {
                 transportId = BigIntFieldType.Uint64.getter(dataView, 0, true);
             }
 
-            await AdbServerClient.writeString(writer, service);
             await AdbServerClient.readOkay(readable);
 
-            writer.releaseLock();
-
-            const duplex = new DuplexStreamFactory<
-                Uint8Array,
-                Consumable<Uint8Array>
-            >();
-            const wrapReadable = duplex.wrapReadable(readable.release());
-            const wrapWritable = duplex.createWritable(
-                new WrapWritableStream(connection.writable).bePipedThroughFrom(
-                    new UnwrapConsumableStream(),
-                ),
-            );
-
             return {
                 transportId,
                 service,
-                readable: wrapReadable,
-                writable: wrapWritable,
-                close() {
-                    return duplex.close();
+                readable: readable.release(),
+                writable: new WrapWritableStream(
+                    connection.writable,
+                ).bePipedThroughFrom(new UnwrapConsumableStream()),
+                get closed() {
+                    return connection.closed;
+                },
+                async close() {
+                    await connection.close();
                 },
             };
         } catch (e) {
-            writer.close().catch(NOOP);
-            readable.cancel().catch(NOOP);
+            await readable.cancel().catch(NOOP);
+            await connection.close();
             throw e;
         }
     }
@@ -410,9 +457,12 @@ export class AdbServerClient {
             `wait-for-${type}-${state}`,
         );
 
-        // `connect` resolves when server writes `OKAY`,
-        // but for this command the server writes `OKAY` after the condition is met.
-        await this.connect(service, options);
+        const socket = await this.connect(service, options);
+        const readable = new BufferedReadableStream(socket.readable);
+        await AdbServerClient.readOkay(readable);
+
+        await readable.cancel();
+        await socket.close();
     }
 
     async createTransport(
@@ -441,7 +491,7 @@ export class AdbServerClient {
     }
 }
 
-async function raceSignal<T>(
+export async function raceSignal<T>(
     callback: () => Promise<T>,
     ...signals: (AbortSignal | undefined)[]
 ): Promise<T> {

package/src/server/transport.ts

@@ -8,9 +8,31 @@ import type {
     AdbTransport,
 } from "../adb.js";
 import type { AdbBanner } from "../banner.js";
+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 class AdbServerTransport implements AdbTransport {
     #client: AdbServerClient;
 
@@ -26,6 +48,12 @@ export class AdbServerTransport implements AdbTransport {
     #waitAbortController = new AbortController();
     readonly disconnected: Promise<void>;
 
+    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;
+    }
+
     constructor(
         client: AdbServerClient,
         serial: string,