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

package/src/daemon/transport.ts

@@ -1,55 +1,14 @@
 import type { MaybePromiseLike } from "@yume-chan/async";
-import { PromiseResolver } from "@yume-chan/async";
-import type { ReadableWritablePair } from "@yume-chan/stream-extra";
-import {
-    AbortController,
-    Consumable,
-    WritableStream,
-} from "@yume-chan/stream-extra";
-import { decodeUtf8, encodeUtf8 } from "@yume-chan/struct";
+import type { Consumable, ReadableWritablePair } from "@yume-chan/stream-extra";
 
-import type {
-    AdbIncomingSocketHandler,
-    AdbSocket,
-    AdbTransport,
-} from "../adb.js";
+import type { Adb, AdbTransport } from "../adb.js";
 import { AdbBanner } from "../banner.js";
-import { AdbFeature } from "../features.js";
+import { AdbDeviceFeatures, AdbFeature } from "../features.js";
 
-import type { AdbAuthenticator, AdbCredentialStore } from "./auth.js";
-import {
-    ADB_DEFAULT_AUTHENTICATORS,
-    AdbAuthenticationProcessor,
-} from "./auth.js";
 import { AdbPacketDispatcher } from "./dispatcher.js";
 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 = /* #__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 readonly AdbFeature[])();
 export const ADB_DAEMON_DEFAULT_INITIAL_PAYLOAD_SIZE = 32 * 1024 * 1024;
 
 export type AdbDaemonConnection = ReadableWritablePair<
@@ -57,55 +16,7 @@ export type AdbDaemonConnection = ReadableWritablePair<
     Consumable<AdbPacketInit>
 >;
 
-export interface AdbDaemonAuthenticationOptions {
-    serial: string;
-    connection: AdbDaemonConnection;
-    credentialStore: AdbCredentialStore;
-    authenticators?: readonly 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 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;
-
-    /**
-     * 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 {
+export interface AdbDaemonTransportInit {
     serial: string;
     connection: AdbDaemonConnection;
     version: number;
@@ -116,16 +27,16 @@ interface AdbDaemonSocketConnectorConstructionOptions {
     /**
      * The number of bytes the device can send before receiving an ack packet.
      *
-     * On Android 14 and newer, the Delayed Acknowledgement feature is added to
-     * improve performance, especially for high-latency connections like ADB over Wi-Fi.
+     * Android 14 added the Delayed Acknowledgement feature to improve performance,
+     * especially for high-latency connections like ADB over Wi-Fi.
      *
-     * 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.
+     * Whether the feature is enabled is negotiated in the handshake process
+     * using the {@linkcode AdbFeature.DelayedAck} feature.
+     * If the feature is enabled, this parameter must be set to a positive 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.
+     * If not specified, the default value is {@linkcode ADB_DAEMON_DEFAULT_INITIAL_PAYLOAD_SIZE}.
      */
-    initialDelayedAckBytes: number;
+    initialDelayedAckBytes?: number | undefined;
 
     /**
      * Whether to keep the `connection` open (don't call `writable.close` and `readable.cancel`)
@@ -153,135 +64,6 @@ interface AdbDaemonSocketConnectorConstructionOptions {
  * An ADB Transport that connects to ADB Daemons directly.
  */
 export class AdbDaemonTransport implements AdbTransport {
-    /**
-     * Authenticate with the ADB Daemon and create a new transport.
-     */
-    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.
-        let version = 0x01000001;
-        // Android 4: 4K, Android 7: 256K, Android 9: 1M
-        let maxPayloadSize = 1024 * 1024;
-
-        const resolver = new PromiseResolver<string>();
-        const authProcessor = new AdbAuthenticationProcessor(
-            authenticators,
-            credentialStore,
-        );
-
-        // Here is similar to `AdbPacketDispatcher`,
-        // But the received packet types and send packet processing are different.
-        const abortController = new AbortController();
-        const pipe = connection.readable
-            .pipeTo(
-                new WritableStream({
-                    async write(packet) {
-                        switch (packet.command) {
-                            case AdbCommand.Connect:
-                                version = Math.min(version, packet.arg0);
-                                maxPayloadSize = Math.min(
-                                    maxPayloadSize,
-                                    packet.arg1,
-                                );
-                                resolver.resolve(decodeUtf8(packet.payload));
-                                break;
-                            case AdbCommand.Auth: {
-                                const response =
-                                    await authProcessor.process(packet);
-                                await sendPacket(response);
-                                break;
-                            }
-                            default:
-                                // Maybe the previous ADB client exited without reading all packets,
-                                // so they are still waiting in OS internal buffer.
-                                // Just ignore them.
-                                // Because a `Connect` packet will reset the device,
-                                // Eventually there will be `Connect` and `Auth` response packets.
-                                break;
-                        }
-                    },
-                }),
-                {
-                    // Don't cancel the source ReadableStream on AbortSignal abort.
-                    preventCancel: true,
-                    signal: abortController.signal,
-                },
-            )
-            .then(
-                () => {
-                    // If `resolver` is already settled, call `reject` won't do anything.
-                    resolver.reject(
-                        new Error("Connection closed unexpectedly"),
-                    );
-                },
-                (e) => {
-                    resolver.reject(e);
-                },
-            );
-
-        const writer = connection.writable.getWriter();
-        async function sendPacket(init: AdbPacketData) {
-            // Always send checksum in auth steps
-            // 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 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 {
-            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=${actualFeatures.join(",")}`,
-                ),
-            });
-
-            banner = await resolver.promise;
-        } finally {
-            // When failed, release locks on `connection` so the caller can try again.
-            // When success, also release locks so `AdbPacketDispatcher` can use them.
-            abortController.abort();
-            writer.releaseLock();
-
-            // Wait until pipe stops (`ReadableStream` lock released)
-            await pipe;
-        }
-
-        return new AdbDaemonTransport({
-            serial,
-            connection,
-            version,
-            maxPayloadSize,
-            banner,
-            features: actualFeatures,
-            initialDelayedAckBytes,
-            ...options,
-        });
-    }
-
     #connection: AdbDaemonConnection;
     get connection() {
         return this.#connection;
@@ -322,42 +104,42 @@ export class AdbDaemonTransport implements AdbTransport {
         connection,
         version,
         banner,
-        features = ADB_DAEMON_DEFAULT_FEATURES,
-        initialDelayedAckBytes,
+        features = AdbDeviceFeatures,
+        initialDelayedAckBytes = ADB_DAEMON_DEFAULT_INITIAL_PAYLOAD_SIZE,
         ...options
-    }: AdbDaemonSocketConnectorConstructionOptions) {
+    }: AdbDaemonTransportInit) {
         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 {
+        if (
+            !this.#banner.features.includes(AdbFeature.DelayedAck) ||
+            !features.includes(AdbFeature.DelayedAck)
+        ) {
+            // For `AdbPacketDispatcher`, 0 means disabled
             initialDelayedAckBytes = 0;
+        } else if (initialDelayedAckBytes <= 0) {
+            // Delayed Ack is enabled in handshake process, we can't disable it here,
+            // so it must be a positive integer
+            throw new TypeError(
+                "`initialDelayedAckBytes` must be greater than 0 when DelayedAck feature is enabled.",
+            );
         }
 
-        let calculateChecksum: boolean;
-        let appendNullToServiceString: boolean;
+        let shouldCalculateChecksum: boolean;
+        let shouldAppendNullToServiceString: boolean;
         if (version >= ADB_DAEMON_VERSION_OMIT_CHECKSUM) {
-            calculateChecksum = false;
-            appendNullToServiceString = false;
+            shouldCalculateChecksum = false;
+            shouldAppendNullToServiceString = false;
         } else {
-            calculateChecksum = true;
-            appendNullToServiceString = true;
+            shouldCalculateChecksum = true;
+            shouldAppendNullToServiceString = true;
         }
 
         this.#dispatcher = new AdbPacketDispatcher(connection, {
-            calculateChecksum,
-            appendNullToServiceString,
+            calculateChecksum: shouldCalculateChecksum,
+            appendNullToServiceString: shouldAppendNullToServiceString,
             initialDelayedAckBytes,
             ...options,
         });
@@ -365,12 +147,12 @@ export class AdbDaemonTransport implements AdbTransport {
         this.#protocolVersion = version;
     }
 
-    connect(service: string): MaybePromiseLike<AdbSocket> {
+    connect(service: string): MaybePromiseLike<Adb.Socket> {
         return this.#dispatcher.createSocket(service);
     }
 
     addReverseTunnel(
-        handler: AdbIncomingSocketHandler,
+        handler: Adb.IncomingSocketHandler,
         address?: string,
     ): string {
         if (!address) {

package/src/device-observer.ts

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

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";