@yume-chan/adb 0.0.18 → 0.0.20

package/src/{socket → daemon}/socket.ts

@@ -1,38 +1,44 @@
 import { PromiseResolver } from "@yume-chan/async";
-import { type Disposable } from "@yume-chan/event";
+import type { Disposable } from "@yume-chan/event";
+import type {
+    Consumable,
+    PushReadableStreamController,
+    ReadableStream,
+    ReadableWritablePair,
+    WritableStream,
+} from "@yume-chan/stream-extra";
 import {
-    ChunkStream,
+    ConsumableWritableStream,
+    DistributionStream,
     DuplexStreamFactory,
     PushReadableStream,
-    WritableStream,
     pipeFrom,
-    type PushReadableStreamController,
-    type ReadableStream,
-    type ReadableWritablePair,
 } from "@yume-chan/stream-extra";
 
-import { AdbCommand } from "../packet.js";
+import type { Closeable } from "../adb.js";
 
-import { type AdbPacketDispatcher, type Closeable } from "./dispatcher.js";
+import type { AdbPacketDispatcher } from "./dispatcher.js";
+import { AdbCommand } from "./packet.js";
 
-export interface AdbSocketInfo {
+export interface AdbDaemonSocketInfo {
     localId: number;
     remoteId: number;
 
     localCreated: boolean;
-    serviceString: string;
+    service: string;
 }
 
-export interface AdbSocketConstructionOptions extends AdbSocketInfo {
+export interface AdbDaemonSocketConstructionOptions
+    extends AdbDaemonSocketInfo {
     dispatcher: AdbPacketDispatcher;
 
     highWaterMark?: number | undefined;
 }
 
-export class AdbSocketController
+export class AdbDaemonSocketController
     implements
-        AdbSocketInfo,
-        ReadableWritablePair<Uint8Array, Uint8Array>,
+        AdbDaemonSocketInfo,
+        ReadableWritablePair<Uint8Array, Consumable<Uint8Array>>,
         Closeable,
         Disposable
 {
@@ -41,44 +47,47 @@ export class AdbSocketController
     public readonly localId!: number;
     public readonly remoteId!: number;
     public readonly localCreated!: boolean;
-    public readonly serviceString!: string;
+    public readonly service!: string;
 
-    private _duplex: DuplexStreamFactory<Uint8Array, Uint8Array>;
+    #duplex: DuplexStreamFactory<Uint8Array, Consumable<Uint8Array>>;
 
-    private _readable: ReadableStream<Uint8Array>;
-    private _readableController!: PushReadableStreamController<Uint8Array>;
+    #readable: ReadableStream<Uint8Array>;
+    #readableController!: PushReadableStreamController<Uint8Array>;
     public get readable() {
-        return this._readable;
+        return this.#readable;
     }
 
-    private _writePromise: PromiseResolver<void> | undefined;
-    public readonly writable: WritableStream<Uint8Array>;
+    #writePromise: PromiseResolver<void> | undefined;
+    public readonly writable: WritableStream<Consumable<Uint8Array>>;
 
-    private _closed = false;
+    #closed = false;
     /**
      * Whether the socket is half-closed (i.e. the local side initiated the close).
      *
      * It's only used by dispatcher to avoid sending another `CLSE` packet to remote.
      */
     public get closed() {
-        return this._closed;
+        return this.#closed;
     }
 
-    private _socket: AdbSocket;
+    private _socket: AdbDaemonSocket;
     public get socket() {
         return this._socket;
     }
 
-    public constructor(options: AdbSocketConstructionOptions) {
+    public constructor(options: AdbDaemonSocketConstructionOptions) {
         Object.assign(this, options);
 
         // Check this image to help you understand the stream graph
         // cspell: disable-next-line
         // https://www.plantuml.com/plantuml/png/TL0zoeGm4ErpYc3l5JxyS0yWM6mX5j4C6p4cxcJ25ejttuGX88ZftizxUKmJI275pGhXl0PP_UkfK_CAz5Z2hcWsW9Ny2fdU4C1f5aSchFVxA8vJjlTPRhqZzDQMRB7AklwJ0xXtX0ZSKH1h24ghoKAdGY23FhxC4nS2pDvxzIvxb-8THU0XlEQJ-ZB7SnXTAvc_LhOckhMdLBnbtndpb-SB7a8q2SRD_W00
 
-        this._duplex = new DuplexStreamFactory<Uint8Array, Uint8Array>({
+        this.#duplex = new DuplexStreamFactory<
+            Uint8Array,
+            Consumable<Uint8Array>
+        >({
             close: async () => {
-                this._closed = true;
+                this.#closed = true;
 
                 await this.dispatcher.sendPacket(
                     AdbCommand.Close,
@@ -91,14 +100,14 @@ export class AdbSocketController
             },
             dispose: () => {
                 // Error out the pending writes
-                this._writePromise?.reject(new Error("Socket closed"));
+                this.#writePromise?.reject(new Error("Socket closed"));
             },
         });
 
-        this._readable = this._duplex.wrapReadable(
+        this.#readable = this.#duplex.wrapReadable(
             new PushReadableStream(
                 (controller) => {
-                    this._readableController = controller;
+                    this.#readableController = controller;
                 },
                 {
                     highWaterMark: options.highWaterMark ?? 16 * 1024,
@@ -110,47 +119,47 @@ export class AdbSocketController
         );
 
         this.writable = pipeFrom(
-            this._duplex.createWritable(
-                new WritableStream({
+            this.#duplex.createWritable(
+                new ConsumableWritableStream<Uint8Array>({
                     write: async (chunk) => {
                         // Wait for an ack packet
-                        this._writePromise = new PromiseResolver();
+                        this.#writePromise = new PromiseResolver();
                         await this.dispatcher.sendPacket(
                             AdbCommand.Write,
                             this.localId,
                             this.remoteId,
                             chunk
                         );
-                        await this._writePromise.promise;
+                        await this.#writePromise.promise;
                     },
                 })
             ),
-            new ChunkStream(this.dispatcher.options.maxPayloadSize)
+            new DistributionStream(this.dispatcher.options.maxPayloadSize)
         );
 
-        this._socket = new AdbSocket(this);
+        this._socket = new AdbDaemonSocket(this);
     }
 
-    public async enqueue(packet: Uint8Array) {
+    public async enqueue(data: Uint8Array) {
         // Consumer may abort the `ReadableStream` to close the socket,
         // it's OK to throw away further packets in this case.
-        if (this._readableController.abortSignal.aborted) {
+        if (this.#readableController.abortSignal.aborted) {
             return;
         }
 
-        await this._readableController.enqueue(packet);
+        await this.#readableController.enqueue(data);
     }
 
     public ack() {
-        this._writePromise?.resolve();
+        this.#writePromise?.resolve();
     }
 
     public async close(): Promise<void> {
-        await this._duplex.close();
+        await this.#duplex.close();
     }
 
     public dispose() {
-        return this._duplex.dispose();
+        return this.#duplex.dispose();
     }
 }
 
@@ -162,36 +171,42 @@ export class AdbSocketController
  * `socket.writable.abort()`, `socket.writable.getWriter().abort()`,
  * `socket.writable.close()` or `socket.writable.getWriter().close()`.
  */
-export class AdbSocket
-    implements AdbSocketInfo, ReadableWritablePair<Uint8Array, Uint8Array>
+export class AdbDaemonSocket
+    implements
+        AdbDaemonSocketInfo,
+        ReadableWritablePair<Uint8Array, Consumable<Uint8Array>>
 {
-    private _controller: AdbSocketController;
+    #controller: AdbDaemonSocketController;
 
     public get localId(): number {
-        return this._controller.localId;
+        return this.#controller.localId;
     }
     public get remoteId(): number {
-        return this._controller.remoteId;
+        return this.#controller.remoteId;
     }
     public get localCreated(): boolean {
-        return this._controller.localCreated;
+        return this.#controller.localCreated;
     }
-    public get serviceString(): string {
-        return this._controller.serviceString;
+    public get service(): string {
+        return this.#controller.service;
     }
 
     public get readable(): ReadableStream<Uint8Array> {
-        return this._controller.readable;
+        return this.#controller.readable;
+    }
+    public get writable(): WritableStream<Consumable<Uint8Array>> {
+        return this.#controller.writable;
     }
-    public get writable(): WritableStream<Uint8Array> {
-        return this._controller.writable;
+
+    public get closed(): boolean {
+        return this.#controller.closed;
     }
 
-    public constructor(controller: AdbSocketController) {
-        this._controller = controller;
+    public constructor(controller: AdbDaemonSocketController) {
+        this.#controller = controller;
     }
 
     public close() {
-        return this._controller.close();
+        return this.#controller.close();
     }
 }

package/src/daemon/transport.ts

@@ -0,0 +1,269 @@
+import { PromiseResolver } from "@yume-chan/async";
+import type { Consumable, ReadableWritablePair } from "@yume-chan/stream-extra";
+import {
+    AbortController,
+    ConsumableWritableStream,
+    WritableStream,
+} from "@yume-chan/stream-extra";
+import type { ValueOrPromise } from "@yume-chan/struct";
+import { decodeUtf8, encodeUtf8 } from "@yume-chan/struct";
+
+import type {
+    AdbIncomingSocketHandler,
+    AdbSocket,
+    AdbTransport,
+} from "../adb.js";
+import { AdbBanner } from "../banner.js";
+import { 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;
+
+interface AdbDaemonAuthenticationOptions {
+    serial: string;
+    connection: ReadableWritablePair<AdbPacketData, Consumable<AdbPacketInit>>;
+    credentialStore: AdbCredentialStore;
+    authenticators?: AdbAuthenticator[];
+}
+
+interface AdbDaemonSocketConnectorConstructionOptions {
+    serial: string;
+    connection: ReadableWritablePair<AdbPacketData, Consumable<AdbPacketInit>>;
+    version: number;
+    maxPayloadSize: number;
+    banner: string;
+}
+
+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.
+     */
+    public static async authenticate({
+        serial,
+        connection,
+        credentialStore,
+        authenticators = ADB_DEFAULT_AUTHENTICATORS,
+    }: 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.state === "running") {
+                        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 ConsumableWritableStream.write(writer, init as AdbPacketInit);
+        }
+
+        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",
+                "sendrecv_v2",
+                "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}`),
+            });
+
+            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,
+        });
+    }
+
+    readonly #dispatcher: AdbPacketDispatcher;
+
+    #serial: string;
+    public get serial() {
+        return this.#serial;
+    }
+
+    #protocolVersion: number;
+    public get protocolVersion() {
+        return this.#protocolVersion;
+    }
+
+    #maxPayloadSize: number;
+    public get maxPayloadSize() {
+        return this.#maxPayloadSize;
+    }
+
+    #banner: AdbBanner;
+    public get banner() {
+        return this.#banner;
+    }
+
+    public get disconnected() {
+        return this.#dispatcher.disconnected;
+    }
+
+    public constructor({
+        serial,
+        connection,
+        version,
+        maxPayloadSize,
+        banner,
+    }: AdbDaemonSocketConnectorConstructionOptions) {
+        this.#serial = serial;
+        this.#banner = AdbBanner.parse(banner);
+
+        let calculateChecksum: boolean;
+        let appendNullToServiceString: boolean;
+        if (version >= ADB_DAEMON_VERSION_OMIT_CHECKSUM) {
+            calculateChecksum = false;
+            appendNullToServiceString = false;
+        } else {
+            calculateChecksum = true;
+            appendNullToServiceString = true;
+        }
+
+        this.#dispatcher = new AdbPacketDispatcher(connection, {
+            calculateChecksum,
+            appendNullToServiceString,
+            maxPayloadSize,
+        });
+
+        this.#protocolVersion = version;
+        this.#maxPayloadSize = maxPayloadSize;
+    }
+
+    public connect(service: string): ValueOrPromise<AdbSocket> {
+        return this.#dispatcher.createSocket(service);
+    }
+
+    public addReverseTunnel(
+        handler: AdbIncomingSocketHandler,
+        address?: string
+    ): string {
+        if (!address) {
+            const id = Math.random().toString().substring(2);
+            address = `localabstract:reverse_${id}`;
+        }
+        this.#dispatcher.addReverseTunnel(address, handler);
+        return address;
+    }
+
+    public removeReverseTunnel(address: string): void {
+        this.#dispatcher.removeReverseTunnel(address);
+    }
+
+    public clearReverseTunnels(): void {
+        this.#dispatcher.clearReverseTunnels();
+    }
+
+    public close(): ValueOrPromise<void> {
+        return this.#dispatcher.close();
+    }
+}

package/src/features.ts

@@ -1,9 +1,12 @@
 // The order follows
 // https://android.googlesource.com/platform/packages/modules/adb/+/79010dc6d5ca7490c493df800d4421730f5466ca/transport.cpp#1252
-export enum AdbFeatures {
-    ShellV2 = 'shell_v2',
-    Cmd = 'cmd',
-    StatV2 = 'stat_v2',
-    ListV2 = 'ls_v2',
-    FixedPushMkdir = 'fixed_push_mkdir',
+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",
 }

package/src/index.ts

@@ -1,9 +1,7 @@
 export * from "./adb.js";
-export * from "./auth.js";
-export * from "./backend.js";
+export * from "./banner.js";
 export * from "./commands/index.js";
-export * from "./crypto.js";
+export * from "./daemon/index.js";
 export * from "./features.js";
-export * from "./packet.js";
-export * from "./socket/index.js";
+export * from "./server/index.js";
 export * from "./utils/index.js";