@yume-chan/adb 0.0.23 → 0.0.24

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 { EMPTY_UINT8_ARRAY } 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;
         }
@@ -175,6 +177,7 @@ export class AdbDaemonSocketController
             AdbCommand.Close,
             this.localId,
             this.remoteId,
+            EMPTY_UINT8_ARRAY,
         );
     }
 
@@ -216,7 +219,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,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";
@@ -56,26 +56,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,20 +111,39 @@ interface AdbDaemonSocketConnectorConstructionOptions {
     maxPayloadSize: number;
     banner: string;
     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.
+     * 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;
 }
 
 export class AdbDaemonTransport implements AdbTransport {
@@ -106,9 +151,9 @@ 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,
@@ -170,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);
@@ -187,7 +231,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 +322,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 +332,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.",
                 );
             }