@yume-chan/adb 0.0.22 → 0.0.24

package/src/daemon/transport.ts

@@ -1,8 +1,8 @@
 import { PromiseResolver } from "@yume-chan/async";
-import type { Consumable, ReadableWritablePair } from "@yume-chan/stream-extra";
+import type { ReadableWritablePair } from "@yume-chan/stream-extra";
 import {
     AbortController,
-    ConsumableWritableStream,
+    Consumable,
     WritableStream,
 } from "@yume-chan/stream-extra";
 import type { ValueOrPromise } from "@yume-chan/struct";
@@ -26,22 +26,82 @@ 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 {
+export interface AdbDaemonAuthenticationOptions {
     serial: string;
     connection: AdbDaemonConnection;
     credentialStore: AdbCredentialStore;
     authenticators?: AdbAuthenticator[];
+    features?: readonly AdbFeature[];
+
+    /**
+     * The number of bytes the device can send before receiving an ack packet.
+     * Using delayed ack can improve the throughput,
+     * especially when the device is connected over Wi-Fi (so the latency is higher).
+     *
+     * 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 was added in Android 14,
+     * this option will be ignored when the device doesn't support it.
+     *
+     * @default ADB_DAEMON_DEFAULT_INITIAL_PAYLOAD_SIZE
+     */
+    initialDelayedAckBytes?: number;
+
     /**
-     * Whether to preserve the connection open after the `AdbDaemonTransport` is closed.
+     * Whether to keep the `connection` open (don't call `writable.close` and `readable.cancel`)
+     * when `AdbDaemonTransport.close` is called.
+     *
+     * Note that when `authenticate` fails,
+     * no matter which value this option has,
+     * the `connection` is always kept open, so it can be used in another `authenticate` call.
+     *
+     * @default false
      */
     preserveConnection?: boolean | undefined;
-    debugSlowRead?: boolean | undefined;
+
+    /**
+     * When set, the transport will throw an error when
+     * one of the socket readable stalls for this amount of milliseconds.
+     *
+     * Because ADB is a multiplexed protocol, blocking one socket will also block all other sockets.
+     * It's important to always read from all sockets to prevent stalling.
+     *
+     * This option is helpful to detect bugs in the client code.
+     *
+     * @default undefined
+     */
+    readTimeLimit?: number | undefined;
 }
 
 interface AdbDaemonSocketConnectorConstructionOptions {
@@ -50,11 +110,40 @@ interface AdbDaemonSocketConnectorConstructionOptions {
     version: number;
     maxPayloadSize: number;
     banner: string;
+    features?: readonly AdbFeature[];
+
     /**
-     * Whether to preserve the connection open after the `AdbDaemonTransport` is closed.
+     * The number of bytes the device can send before receiving an ack packet.
+     * Using delayed ack can improve the throughput,
+     * especially when the device is connected over Wi-Fi (so the latency is higher).
+     *
+     * When `features` doesn't include `AdbFeature.DelayedAck`, it must be set to 0. Otherwise,
+     * the value must be in the range of unsigned 32-bit integer. If the device enabled
+     * delayed ack but the client didn't, the device will throw an error when the client sends
+     * the first data packet. And vice versa.
+     */
+    initialDelayedAckBytes: number;
+
+    /**
+     * Whether to keep the `connection` open (don't call `writable.close` and `readable.cancel`)
+     * when `AdbDaemonTransport.close` is called.
+     *
+     * @default false
      */
     preserveConnection?: boolean | undefined;
-    debugSlowRead?: boolean | undefined;
+
+    /**
+     * When set, the transport will throw an error when
+     * one of the socket readable stalls for this amount of milliseconds.
+     *
+     * Because ADB is a multiplexed protocol, blocking one socket will also block all other sockets.
+     * It's important to always read from all sockets to prevent stalling.
+     *
+     * This option is helpful to detect bugs in the client code.
+     *
+     * @default undefined
+     */
+    readTimeLimit?: number | undefined;
 }
 
 export class AdbDaemonTransport implements AdbTransport {
@@ -62,15 +151,17 @@ export class AdbDaemonTransport implements AdbTransport {
      * Authenticates the connection and creates an `AdbDaemonTransport` instance
      * that can be used by `Adb` class.
      *
-     * If an authentication process failed, it's possible to call `authenticate` again
-     * on the same connection. Because every time the device receives a `CNXN` packet,
-     * it resets all internal state, and starts a new authentication process.
+     * If an authentication process failed,
+     * no matter which value the `preserveConnection` option has,
+     * the `connection` is always kept open, so it can be used in another `authenticate` call.
      */
     static async authenticate({
         serial,
         connection,
         credentialStore,
         authenticators = ADB_DEFAULT_AUTHENTICATORS,
+        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.
@@ -124,11 +215,10 @@ export class AdbDaemonTransport implements AdbTransport {
             )
             .then(
                 () => {
-                    if (resolver.state === "running") {
-                        resolver.reject(
-                            new Error("Connection closed unexpectedly"),
-                        );
-                    }
+                    // If `resolver` is already settled, call `reject` won't do anything.
+                    resolver.reject(
+                        new Error("Connection closed unexpectedly"),
+                    );
                 },
                 (e) => {
                     resolver.reject(e);
@@ -141,41 +231,31 @@ export class AdbDaemonTransport implements AdbTransport {
             // Because we don't know if the device needs it or not.
             (init as AdbPacketInit).checksum = calculateChecksum(init.payload);
             (init as AdbPacketInit).magic = init.command ^ 0xffffffff;
-            await ConsumableWritableStream.write(writer, init as AdbPacketInit);
+            await Consumable.WritableStream.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;
@@ -195,6 +275,8 @@ export class AdbDaemonTransport implements AdbTransport {
             version,
             maxPayloadSize,
             banner,
+            features: actualFeatures,
+            initialDelayedAckBytes,
             ...options,
         });
     }
@@ -229,16 +311,38 @@ export class AdbDaemonTransport implements AdbTransport {
         return this.#dispatcher.disconnected;
     }
 
+    #clientFeatures: readonly AdbFeature[];
+    get clientFeatures() {
+        return this.#clientFeatures;
+    }
+
     constructor({
         serial,
         connection,
         version,
         banner,
+        features = ADB_DAEMON_DEFAULT_FEATURES,
+        initialDelayedAckBytes,
         ...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 TypeError(
+                    "`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;
@@ -253,6 +357,7 @@ export class AdbDaemonTransport implements AdbTransport {
         this.#dispatcher = new AdbPacketDispatcher(connection, {
             calculateChecksum,
             appendNullToServiceString,
+            initialDelayedAckBytes,
             ...options,
         });
 

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",
 }