@yume-chan/adb 0.0.23 → 1.0.0

package/src/daemon/packet.ts

@@ -1,32 +1,43 @@
-import { ConsumableTransformStream } from "@yume-chan/stream-extra";
-import Struct from "@yume-chan/struct";
+import { Consumable, TransformStream } from "@yume-chan/stream-extra";
+import type { StructInit, StructValue } from "@yume-chan/struct";
+import { buffer, s32, struct, u32 } from "@yume-chan/struct";
 
-export enum AdbCommand {
-    Auth = 0x48545541, // 'AUTH'
-    Close = 0x45534c43, // 'CLSE'
-    Connect = 0x4e584e43, // 'CNXN'
-    Okay = 0x59414b4f, // 'OKAY'
-    Open = 0x4e45504f, // 'OPEN'
-    Write = 0x45545257, // 'WRTE'
-}
+export const AdbCommand = {
+    Auth: 0x48545541, // 'AUTH'
+    Close: 0x45534c43, // 'CLSE'
+    Connect: 0x4e584e43, // 'CNXN'
+    Okay: 0x59414b4f, // 'OKAY'
+    Open: 0x4e45504f, // 'OPEN'
+    Write: 0x45545257, // 'WRTE'
+} as const;
+
+export type AdbCommand = (typeof AdbCommand)[keyof typeof AdbCommand];
 
-export const AdbPacketHeader = new Struct({ littleEndian: true })
-    .uint32("command")
-    .uint32("arg0")
-    .uint32("arg1")
-    .uint32("payloadLength")
-    .uint32("checksum")
-    .int32("magic");
+export const AdbPacketHeader = struct(
+    {
+        command: u32,
+        arg0: u32,
+        arg1: u32,
+        payloadLength: u32,
+        checksum: u32,
+        magic: s32,
+    },
+    { littleEndian: true },
+);
 
-export type AdbPacketHeader = (typeof AdbPacketHeader)["TDeserializeResult"];
+export type AdbPacketHeader = StructValue<typeof AdbPacketHeader>;
 
-type AdbPacketHeaderInit = (typeof AdbPacketHeader)["TInit"];
+type AdbPacketHeaderInit = StructInit<typeof AdbPacketHeader>;
 
-export const AdbPacket = new Struct({ littleEndian: true })
-    .concat(AdbPacketHeader)
-    .uint8Array("payload", { lengthField: "payloadLength" });
+export const AdbPacket = struct(
+    /* #__PURE__ */ (() => ({
+        ...AdbPacketHeader.fields,
+        payload: buffer("payloadLength"),
+    }))(),
+    { littleEndian: true },
+);
 
-export type AdbPacket = (typeof AdbPacket)["TDeserializeResult"];
+export type AdbPacket = StructValue<typeof AdbPacket>;
 
 /**
  * `AdbPacketData` contains all the useful fields of `AdbPacket`.
@@ -39,36 +50,44 @@ export type AdbPacket = (typeof AdbPacket)["TDeserializeResult"];
  * so `AdbSocket#writable#write` only needs `AdbPacketData`.
  */
 export type AdbPacketData = Omit<
-    (typeof AdbPacket)["TInit"],
+    StructInit<typeof AdbPacket>,
     "checksum" | "magic"
 >;
 
-export type AdbPacketInit = (typeof AdbPacket)["TInit"];
+export type AdbPacketInit = StructInit<typeof AdbPacket>;
 
 export function calculateChecksum(payload: Uint8Array): number {
     return payload.reduce((result, item) => result + item, 0);
 }
 
-export class AdbPacketSerializeStream extends ConsumableTransformStream<
-    AdbPacketInit,
-    Uint8Array
+export class AdbPacketSerializeStream extends TransformStream<
+    Consumable<AdbPacketInit>,
+    Consumable<Uint8Array>
 > {
     constructor() {
         const headerBuffer = new Uint8Array(AdbPacketHeader.size);
         super({
             transform: async (chunk, controller) => {
-                const init = chunk as AdbPacketInit & AdbPacketHeaderInit;
-                init.payloadLength = init.payload.byteLength;
+                await chunk.tryConsume(async (chunk) => {
+                    const init = chunk as AdbPacketInit & AdbPacketHeaderInit;
+                    init.payloadLength = init.payload.length;
 
-                AdbPacketHeader.serialize(init, headerBuffer);
-                await controller.enqueue(headerBuffer);
+                    AdbPacketHeader.serialize(init, headerBuffer);
+                    await Consumable.ReadableStream.enqueue(
+                        controller,
+                        headerBuffer,
+                    );
 
-                if (init.payload.byteLength) {
-                    // USB protocol preserves packet boundaries,
-                    // so we must write payload separately as native ADB does,
-                    // otherwise the read operation on device will fail.
-                    await controller.enqueue(init.payload);
-                }
+                    if (init.payloadLength) {
+                        // USB protocol preserves packet boundaries,
+                        // so we must write payload separately as native ADB does,
+                        // otherwise the read operation on device will fail.
+                        await Consumable.ReadableStream.enqueue(
+                            controller,
+                            init.payload,
+                        );
+                    }
+                });
             },
         });
     }

package/src/daemon/socket.ts

@@ -1,17 +1,13 @@
 import { PromiseResolver } from "@yume-chan/async";
 import type { Disposable } from "@yume-chan/event";
 import type {
-    AbortSignal,
-    Consumable,
     PushReadableStreamController,
     ReadableStream,
     WritableStream,
     WritableStreamDefaultController,
 } from "@yume-chan/stream-extra";
-import {
-    ConsumableWritableStream,
-    PushReadableStream,
-} from "@yume-chan/stream-extra";
+import { MaybeConsumable, PushReadableStream } from "@yume-chan/stream-extra";
+import { EmptyUint8Array } from "@yume-chan/struct";
 
 import type { AdbSocket } from "../adb.js";
 
@@ -26,11 +22,15 @@ export interface AdbDaemonSocketInfo {
     service: string;
 }
 
-export interface AdbDaemonSocketConstructionOptions
-    extends AdbDaemonSocketInfo {
+export interface AdbDaemonSocketInit extends AdbDaemonSocketInfo {
     dispatcher: AdbPacketDispatcher;
 
     highWaterMark?: number | undefined;
+
+    /**
+     * The initial delayed ack byte count, or `Infinity` if delayed ack is disabled.
+     */
+    availableWriteBytes: number;
 }
 
 export class AdbDaemonSocketController
@@ -50,7 +50,7 @@ export class AdbDaemonSocketController
     }
 
     #writableController!: WritableStreamDefaultController;
-    readonly writable: WritableStream<Consumable<Uint8Array>>;
+    readonly writable: WritableStream<MaybeConsumable<Uint8Array>>;
 
     #closed = false;
 
@@ -66,16 +66,16 @@ export class AdbDaemonSocketController
 
     #availableWriteBytesChanged: PromiseResolver<void> | undefined;
     /**
-     * When delayed ack is disabled, can be `Infinity` if the socket is ready to write.
-     * Exactly one packet can be written no matter how large it is. Or `-1` if the socket
-     * is waiting for ack.
+     * When delayed ack is disabled, returns `Infinity` if the socket is ready to write
+     * (exactly one packet can be written no matter how large it is), or `-1` if the socket
+     * is waiting for ack message.
      *
-     * When delayed ack is enabled, a non-negative finite number indicates the number of
-     * bytes that can be written to the socket before receiving an ack.
+     * When delayed ack is enabled, returns a non-negative finite number indicates the number of
+     * bytes that can be written to the socket before waiting for ack message.
      */
     #availableWriteBytes = 0;
 
-    constructor(options: AdbDaemonSocketConstructionOptions) {
+    constructor(options: AdbDaemonSocketInit) {
         this.#dispatcher = options.dispatcher;
         this.localId = options.localId;
         this.remoteId = options.remoteId;
@@ -86,11 +86,16 @@ export class AdbDaemonSocketController
             this.#readableController = controller;
         });
 
-        this.writable = new ConsumableWritableStream<Uint8Array>({
+        this.writable = new MaybeConsumable.WritableStream<Uint8Array>({
             start: (controller) => {
                 this.#writableController = controller;
+                controller.signal.addEventListener("abort", () => {
+                    this.#availableWriteBytesChanged?.reject(
+                        controller.signal.reason,
+                    );
+                });
             },
-            write: async (data, controller) => {
+            write: async (data) => {
                 const size = data.length;
                 const chunkSize = this.#dispatcher.options.maxPayloadSize;
                 for (
@@ -99,24 +104,21 @@ export class AdbDaemonSocketController
                     start = end, end += chunkSize
                 ) {
                     const chunk = data.subarray(start, end);
-                    await this.#writeChunk(chunk, controller.signal);
+                    await this.#writeChunk(chunk);
                 }
             },
         });
 
         this.#socket = new AdbDaemonSocket(this);
+        this.#availableWriteBytes = options.availableWriteBytes;
     }
 
-    async #writeChunk(data: Uint8Array, signal: AbortSignal) {
-        const length = data.byteLength;
+    async #writeChunk(data: Uint8Array) {
+        const length = data.length;
         while (this.#availableWriteBytes < length) {
             // Only one lock is required because Web Streams API guarantees
             // that `write` is not reentrant.
             const resolver = new PromiseResolver<void>();
-            signal.addEventListener("abort", () => {
-                resolver.reject(signal.reason);
-            });
-
             this.#availableWriteBytesChanged = resolver;
             await resolver.promise;
         }
@@ -136,20 +138,7 @@ export class AdbDaemonSocketController
     }
 
     async enqueue(data: Uint8Array) {
-        // Consumers can `cancel` the `readable` if they are not interested in future data.
-        // Throw away the data if that happens.
-        if (this.#readableController.abortSignal.aborted) {
-            return;
-        }
-
-        try {
-            await this.#readableController.enqueue(data);
-        } catch (e) {
-            if (this.#readableController.abortSignal.aborted) {
-                return;
-            }
-            throw e;
-        }
+        await this.#readableController.enqueue(data);
     }
 
     public ack(bytes: number) {
@@ -175,27 +164,18 @@ export class AdbDaemonSocketController
             AdbCommand.Close,
             this.localId,
             this.remoteId,
+            EmptyUint8Array,
         );
     }
 
     dispose() {
-        try {
-            this.#readableController.close();
-        } catch {
-            // ignore
-        }
-
+        this.#readableController.close();
         this.#closedPromise.resolve();
     }
 }
 
 /**
  * A duplex stream representing a socket to ADB daemon.
- *
- * To close it, call either `socket.close()`,
- * `socket.readable.cancel()`, `socket.readable.getReader().cancel()`,
- * `socket.writable.abort()`, `socket.writable.getWriter().abort()`,
- * `socket.writable.close()` or `socket.writable.getWriter().close()`.
  */
 export class AdbDaemonSocket implements AdbDaemonSocketInfo, AdbSocket {
     #controller: AdbDaemonSocketController;
@@ -216,7 +196,7 @@ export class AdbDaemonSocket implements AdbDaemonSocketInfo, AdbSocket {
     get readable(): ReadableStream<Uint8Array> {
         return this.#controller.readable;
     }
-    get writable(): WritableStream<Consumable<Uint8Array>> {
+    get writable(): WritableStream<MaybeConsumable<Uint8Array>> {
         return this.#controller.writable;
     }
 

package/src/daemon/transport.ts

@@ -1,11 +1,11 @@
+import type { MaybePromiseLike } from "@yume-chan/async";
 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";
 import { decodeUtf8, encodeUtf8 } from "@yume-chan/struct";
 
 import type {
@@ -28,27 +28,28 @@ 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_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",
+        AdbFeature.DelayedAck,
+    ] as AdbFeature[])();
 export const ADB_DAEMON_DEFAULT_INITIAL_PAYLOAD_SIZE = 32 * 1024 * 1024;
 
 export type AdbDaemonConnection = ReadableWritablePair<
@@ -56,26 +57,52 @@ export type AdbDaemonConnection = ReadableWritablePair<
     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 requires Android 14, this option is ignored on older versions.
+     * 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 {
@@ -85,30 +112,49 @@ interface AdbDaemonSocketConnectorConstructionOptions {
     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.
+     * On Android 14 and newer, the Delayed Acknowledgement feature is added to
+     * improve performance, especially for high-latency connections like ADB over Wi-Fi.
      *
-     * Delayed ack requires Android 14, this option is ignored on older versions.
+     * 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;
+    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.
+     *
+     * @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;
 }
 
+/**
+ * An ADB Transport that connects to ADB Daemons directly.
+ */
 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.
+     * Authenticate with the ADB Daemon and create a new transport.
      */
     static async authenticate({
         serial,
@@ -170,11 +216,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);
@@ -187,7 +232,10 @@ 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();
@@ -275,7 +323,7 @@ export class AdbDaemonTransport implements AdbTransport {
         version,
         banner,
         features = ADB_DAEMON_DEFAULT_FEATURES,
-        initialDelayedAckBytes = ADB_DAEMON_DEFAULT_INITIAL_PAYLOAD_SIZE,
+        initialDelayedAckBytes,
         ...options
     }: AdbDaemonSocketConnectorConstructionOptions) {
         this.#serial = serial;
@@ -285,7 +333,7 @@ export class AdbDaemonTransport implements AdbTransport {
 
         if (features.includes(AdbFeature.DelayedAck)) {
             if (initialDelayedAckBytes <= 0) {
-                throw new Error(
+                throw new TypeError(
                     "`initialDelayedAckBytes` must be greater than 0 when DelayedAck feature is enabled.",
                 );
             }
@@ -317,7 +365,7 @@ export class AdbDaemonTransport implements AdbTransport {
         this.#protocolVersion = version;
     }
 
-    connect(service: string): ValueOrPromise<AdbSocket> {
+    connect(service: string): MaybePromiseLike<AdbSocket> {
         return this.#dispatcher.createSocket(service);
     }
 
@@ -341,7 +389,7 @@ export class AdbDaemonTransport implements AdbTransport {
         this.#dispatcher.clearReverseTunnels();
     }
 
-    close(): ValueOrPromise<void> {
+    close(): MaybePromiseLike<void> {
         return this.#dispatcher.close();
     }
 }

package/src/device-observer.ts

@@ -0,0 +1,10 @@
+import type { MaybePromiseLike } from "@yume-chan/async";
+import type { Event } from "@yume-chan/event";
+
+export interface DeviceObserver<T> {
+    onDeviceAdd: Event<T[]>;
+    onDeviceRemove: Event<T[]>;
+    onListChange: Event<T[]>;
+    current: T[];
+    stop(): MaybePromiseLike<void>;
+}

package/src/features.ts

@@ -1,13 +1,15 @@
 // The order follows
 // 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",
-    StatV2 = "stat_v2",
-    ListV2 = "ls_v2",
-    FixedPushMkdir = "fixed_push_mkdir",
-    Abb = "abb",
-    AbbExec = "abb_exec",
-    SendReceiveV2 = "sendrecv_v2",
-    DelayedAck = "delayed_ack",
-}
+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;
+
+export type AdbFeature = (typeof AdbFeature)[keyof typeof AdbFeature];

package/src/index.ts

@@ -2,6 +2,7 @@ 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 "./utils/index.js";