@yume-chan/adb 0.0.16 → 0.0.18

package/src/adb.ts

@@ -1,19 +1,50 @@
 // cspell: ignore libusb
 
-import { PromiseResolver } from '@yume-chan/async';
-import { AdbAuthenticationProcessor, ADB_DEFAULT_AUTHENTICATORS, type AdbCredentialStore } from './auth.js';
-import { AdbPower, AdbReverseCommand, AdbSubprocess, AdbSync, AdbTcpIpCommand, escapeArg, framebuffer, install, type AdbFrameBuffer } from './commands/index.js';
-import { AdbFeatures } from './features.js';
-import { AdbCommand, calculateChecksum, type AdbPacketData, type AdbPacketInit } from './packet.js';
-import { AdbIncomingSocketHandler, AdbPacketDispatcher, type AdbSocket, type Closeable } from './socket/index.js';
-import { AbortController, DecodeUtf8Stream, GatherStringStream, WritableStream, type ReadableWritablePair } from "./stream/index.js";
+import { PromiseResolver } from "@yume-chan/async";
+import {
+    AbortController,
+    DecodeUtf8Stream,
+    GatherStringStream,
+    WritableStream,
+    type ReadableWritablePair,
+} from "@yume-chan/stream-extra";
+
+import {
+    ADB_DEFAULT_AUTHENTICATORS,
+    AdbAuthenticationProcessor,
+    type AdbCredentialStore,
+} from "./auth.js";
+import {
+    AdbPower,
+    AdbReverseCommand,
+    AdbSubprocess,
+    AdbSync,
+    AdbTcpIpCommand,
+    escapeArg,
+    framebuffer,
+    install,
+    type AdbFrameBuffer,
+} from "./commands/index.js";
+import { AdbFeatures } from "./features.js";
+import {
+    AdbCommand,
+    calculateChecksum,
+    type AdbPacketData,
+    type AdbPacketInit,
+} from "./packet.js";
+import {
+    AdbPacketDispatcher,
+    type AdbIncomingSocketHandler,
+    type AdbSocket,
+    type Closeable,
+} from "./socket/index.js";
 import { decodeUtf8, encodeUtf8 } from "./utils/index.js";
 
 export enum AdbPropKey {
-    Product = 'ro.product.name',
-    Model = 'ro.product.model',
-    Device = 'ro.product.device',
-    Features = 'features',
+    Product = "ro.product.name",
+    Model = "ro.product.model",
+    Device = "ro.product.device",
+    Features = "features",
 }
 
 export const VERSION_OMIT_CHECKSUM = 0x01000001;
@@ -27,44 +58,57 @@ export class Adb implements Closeable {
     public static async authenticate(
         connection: ReadableWritablePair<AdbPacketData, AdbPacketInit>,
         credentialStore: AdbCredentialStore,
-        authenticators = ADB_DEFAULT_AUTHENTICATORS,
+        authenticators = ADB_DEFAULT_AUTHENTICATORS
     ): Promise<Adb> {
         // Initially, set to highest-supported version and payload size.
         let version = 0x01000001;
         let maxPayloadSize = 0x100000;
 
         const resolver = new PromiseResolver<string>();
-        const authProcessor = new AdbAuthenticationProcessor(authenticators, credentialStore);
+        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;
-                    }
+            .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,
                 }
-            }), {
-                preventCancel: true,
-                signal: abortController.signal,
-            })
+            )
             .catch((e) => {
                 resolver.reject(e);
             });
@@ -86,20 +130,20 @@ export class Adb implements Closeable {
                 AdbFeatures.StatV2,
                 AdbFeatures.ListV2,
                 AdbFeatures.FixedPushMkdir,
-                'apex',
-                'abb',
+                "apex",
+                "abb",
                 // only tells the client the symlink timestamp issue in `adb push --sync` has been fixed.
                 // No special handling required.
-                'fixed_push_symlink_timestamp',
-                'abb_exec',
-                'remount_shell',
-                'track_app',
-                'sendrecv_v2',
-                'sendrecv_v2_brotli',
-                'sendrecv_v2_lz4',
-                'sendrecv_v2_zstd',
-                'sendrecv_v2_dry_run_send',
-            ].join(',');
+                "fixed_push_symlink_timestamp",
+                "abb_exec",
+                "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,
@@ -121,32 +165,39 @@ export class Adb implements Closeable {
             await pipe;
         }
 
-        return new Adb(
-            connection,
-            version,
-            maxPayloadSize,
-            banner,
-        );
+        return new Adb(connection, version, maxPayloadSize, banner);
     }
 
     private readonly dispatcher: AdbPacketDispatcher;
 
-    public get disconnected() { return this.dispatcher.disconnected; }
+    public get disconnected() {
+        return this.dispatcher.disconnected;
+    }
 
     private _protocolVersion: number | undefined;
-    public get protocolVersion() { return this._protocolVersion; }
+    public get protocolVersion() {
+        return this._protocolVersion;
+    }
 
     private _product: string | undefined;
-    public get product() { return this._product; }
+    public get product() {
+        return this._product;
+    }
 
     private _model: string | undefined;
-    public get model() { return this._model; }
+    public get model() {
+        return this._model;
+    }
 
     private _device: string | undefined;
-    public get device() { return this._device; }
+    public get device() {
+        return this._device;
+    }
 
-    private _features: AdbFeatures[] | undefined;
-    public get features() { return this._features; }
+    private _features: AdbFeatures[] = [];
+    public get features() {
+        return this._features;
+    }
 
     public readonly subprocess: AdbSubprocess;
     public readonly power: AdbPower;
@@ -157,7 +208,7 @@ export class Adb implements Closeable {
         connection: ReadableWritablePair<AdbPacketData, AdbPacketInit>,
         version: number,
         maxPayloadSize: number,
-        banner: string,
+        banner: string
     ) {
         this.parseBanner(banner);
 
@@ -171,14 +222,11 @@ export class Adb implements Closeable {
             appendNullToServiceString = true;
         }
 
-        this.dispatcher = new AdbPacketDispatcher(
-            connection,
-            {
-                calculateChecksum,
-                appendNullToServiceString,
-                maxPayloadSize,
-            }
-        );
+        this.dispatcher = new AdbPacketDispatcher(connection, {
+            calculateChecksum,
+            appendNullToServiceString,
+            maxPayloadSize,
+        });
 
         this._protocolVersion = version;
 
@@ -189,17 +237,15 @@ export class Adb implements Closeable {
     }
 
     private parseBanner(banner: string): void {
-        this._features = [];
-
-        const pieces = banner.split('::');
+        const pieces = banner.split("::");
         if (pieces.length > 1) {
             const props = pieces[1]!;
-            for (const prop of props.split(';')) {
+            for (const prop of props.split(";")) {
                 if (!prop) {
                     continue;
                 }
 
-                const keyValue = prop.split('=');
+                const keyValue = prop.split("=");
                 if (keyValue.length !== 2) {
                     continue;
                 }
@@ -216,15 +262,20 @@ export class Adb implements Closeable {
                         this._device = value;
                         break;
                     case AdbPropKey.Features:
-                        this._features = value!.split(',') as AdbFeatures[];
+                        this._features = value!.split(",") as AdbFeatures[];
                         break;
                 }
             }
         }
     }
 
-    public addIncomingSocketHandler(handler: AdbIncomingSocketHandler) {
-        return this.dispatcher.addIncomingSocketHandler(handler);
+    /**
+     * Add a handler for incoming socket.
+     * @param handler A function to call with new incoming sockets. It must return `true` if it accepts the socket.
+     * @returns A function to remove the handler.
+     */
+    public onIncomingSocket(handler: AdbIncomingSocketHandler) {
+        return this.dispatcher.onIncomingSocket(handler);
     }
 
     public async createSocket(service: string): Promise<AdbSocket> {
@@ -241,16 +292,19 @@ export class Adb implements Closeable {
     }
 
     public async getProp(key: string): Promise<string> {
-        const stdout = await this.subprocess.spawnAndWaitLegacy(
-            ['getprop', key]
-        );
+        const stdout = await this.subprocess.spawnAndWaitLegacy([
+            "getprop",
+            key,
+        ]);
         return stdout.trim();
     }
 
     public async rm(...filenames: string[]): Promise<string> {
-        const stdout = await this.subprocess.spawnAndWaitLegacy(
-            ['rm', '-rf', ...filenames.map(arg => escapeArg(arg))],
-        );
+        const stdout = await this.subprocess.spawnAndWaitLegacy([
+            "rm",
+            "-rf",
+            ...filenames.map((arg) => escapeArg(arg)),
+        ]);
         return stdout;
     }
 
@@ -259,7 +313,7 @@ export class Adb implements Closeable {
     }
 
     public async sync(): Promise<AdbSync> {
-        const socket = await this.createSocket('sync:');
+        const socket = await this.createSocket("sync:");
         return new AdbSync(this, socket);
     }
 

package/src/auth.ts

@@ -1,9 +1,14 @@
-import { PromiseResolver } from '@yume-chan/async';
-import type { Disposable } from '@yume-chan/event';
-import type { ValueOrPromise } from '@yume-chan/struct';
-import { calculatePublicKey, calculatePublicKeyLength, sign } from './crypto.js';
-import { AdbCommand, type AdbPacketData } from './packet.js';
-import { calculateBase64EncodedLength, encodeBase64 } from './utils/index.js';
+import { PromiseResolver } from "@yume-chan/async";
+import { type Disposable } from "@yume-chan/event";
+import { type ValueOrPromise } from "@yume-chan/struct";
+
+import {
+    calculatePublicKey,
+    calculatePublicKeyLength,
+    sign,
+} from "./crypto.js";
+import { AdbCommand, type AdbPacketData } from "./packet.js";
+import { calculateBase64EncodedLength, encodeBase64 } from "./utils/index.js";
 
 export type AdbKeyIterable = Iterable<Uint8Array> | AsyncIterable<Uint8Array>;
 
@@ -49,7 +54,7 @@ export interface AdbAuthenticator {
 
 export const AdbSignatureAuthenticator: AdbAuthenticator = async function* (
     credentialStore: AdbCredentialStore,
-    getNextRequest: () => Promise<AdbPacketData>,
+    getNextRequest: () => Promise<AdbPacketData>
 ): AsyncIterable<AdbPacketData> {
     for await (const key of credentialStore.iterateKeys()) {
         const packet = await getNextRequest();
@@ -70,7 +75,7 @@ export const AdbSignatureAuthenticator: AdbAuthenticator = async function* (
 
 export const AdbPublicKeyAuthenticator: AdbAuthenticator = async function* (
     credentialStore: AdbCredentialStore,
-    getNextRequest: () => Promise<AdbPacketData>,
+    getNextRequest: () => Promise<AdbPacketData>
 ): AsyncIterable<AdbPacketData> {
     const packet = await getNextRequest();
 
@@ -84,23 +89,20 @@ export const AdbPublicKeyAuthenticator: AdbAuthenticator = async function* (
         break;
     }
 
-
     if (!privateKey) {
         privateKey = await credentialStore.generateKey();
     }
 
     const publicKeyLength = calculatePublicKeyLength();
-    const [publicKeyBase64Length] = calculateBase64EncodedLength(publicKeyLength);
+    const [publicKeyBase64Length] =
+        calculateBase64EncodedLength(publicKeyLength);
 
     // The public key is null terminated,
     // So we allocate the buffer with one extra byte.
     const publicKeyBuffer = new Uint8Array(publicKeyBase64Length + 1);
 
     calculatePublicKey(privateKey, publicKeyBuffer);
-    encodeBase64(
-        publicKeyBuffer.subarray(0, publicKeyLength),
-        publicKeyBuffer
-    );
+    encodeBase64(publicKeyBuffer.subarray(0, publicKeyLength), publicKeyBuffer);
 
     yield {
         command: AdbCommand.Auth,
@@ -136,9 +138,16 @@ export class AdbAuthenticationProcessor implements Disposable {
         return this.pendingRequest.promise;
     };
 
-    private async* invokeAuthenticator(): AsyncGenerator<AdbPacketData, void, void> {
+    private async *invokeAuthenticator(): AsyncGenerator<
+        AdbPacketData,
+        void,
+        void
+    > {
         for (const authenticator of this.authenticators) {
-            for await (const packet of authenticator(this.credentialStore, this.getNextRequest)) {
+            for await (const packet of authenticator(
+                this.credentialStore,
+                this.getNextRequest
+            )) {
                 // If the authenticator yielded a response
                 // Prepare `nextRequest` for next authentication request
                 this.pendingRequest = new PromiseResolver();
@@ -161,13 +170,13 @@ export class AdbAuthenticationProcessor implements Disposable {
 
         const result = await this.iterator.next();
         if (result.done) {
-            throw new Error('No authenticator can handle the request');
+            throw new Error("No authenticator can handle the request");
         }
 
         return result.value;
     }
 
     public dispose() {
-        this.iterator?.return?.();
+        void this.iterator?.return?.();
     }
 }

package/src/backend.ts

@@ -1,11 +1,14 @@
-import type { ValueOrPromise } from '@yume-chan/struct';
-import type { AdbPacketData, AdbPacketInit } from "./packet.js";
-import type { ReadableWritablePair } from "./stream/index.js";
+import { type ReadableWritablePair } from "@yume-chan/stream-extra";
+import { type ValueOrPromise } from "@yume-chan/struct";
+
+import { type AdbPacketData, type AdbPacketInit } from "./packet.js";
 
 export interface AdbBackend {
     readonly serial: string;
 
     readonly name: string | undefined;
 
-    connect(): ValueOrPromise<ReadableWritablePair<AdbPacketData, AdbPacketInit>>;
+    connect(): ValueOrPromise<
+        ReadableWritablePair<AdbPacketData, AdbPacketInit>
+    >;
 }

package/src/commands/base.ts

@@ -1,5 +1,6 @@
-import { AutoDisposable } from '@yume-chan/event';
-import type { Adb } from '../adb.js';
+import { AutoDisposable } from "@yume-chan/event";
+
+import { type Adb } from "../adb.js";
 
 export class AdbCommandBase extends AutoDisposable {
     protected adb: Adb;

package/src/commands/framebuffer.ts

@@ -1,14 +1,50 @@
+import { BufferedReadableStream } from "@yume-chan/stream-extra";
 import Struct from "@yume-chan/struct";
-import type { Adb } from '../adb.js';
-import { AdbBufferedStream } from '../stream/index.js';
 
-const Version =
-    new Struct({ littleEndian: true })
-        .uint32('version');
+import { type Adb } from "../adb.js";
 
-/*
+const Version = new Struct({ littleEndian: true }).uint32("version");
+
+export const AdbFrameBufferV1 = new Struct({ littleEndian: true })
+    .uint32("bpp")
+    .uint32("size")
+    .uint32("width")
+    .uint32("height")
+    .uint32("red_offset")
+    .uint32("red_length")
+    .uint32("blue_offset")
+    .uint32("blue_length")
+    .uint32("green_offset")
+    .uint32("green_length")
+    .uint32("alpha_offset")
+    .uint32("alpha_length")
+    .uint8Array("data", { lengthField: "size" });
+
+export type AdbFrameBufferV1 = typeof AdbFrameBufferV1["TDeserializeResult"];
+
+export const AdbFrameBufferV2 = new Struct({ littleEndian: true })
+    .uint32("bpp")
+    .uint32("colorSpace")
+    .uint32("size")
+    .uint32("width")
+    .uint32("height")
+    .uint32("red_offset")
+    .uint32("red_length")
+    .uint32("blue_offset")
+    .uint32("blue_length")
+    .uint32("green_offset")
+    .uint32("green_length")
+    .uint32("alpha_offset")
+    .uint32("alpha_length")
+    .uint8Array("data", { lengthField: "size" });
+
+export type AdbFrameBufferV2 = typeof AdbFrameBufferV2["TDeserializeResult"];
+
+/**
  * ADB uses 8 int32 fields to describe bit depths
+ *
  * The only combination I have seen is RGBA8888, which is
+ *
  *   red_offset:   0
  *   red_length:   8
  *   blue_offset:  16
@@ -17,57 +53,22 @@ const Version =
  *   green_length: 8
  *   alpha_offset: 24
  *   alpha_length: 8
+ *
+ * But it doesn't mean that other combinations are not possible.
  */
-
-export const AdbFrameBufferV1 =
-    new Struct({ littleEndian: true })
-        .uint32('bpp')
-        .uint32('size')
-        .uint32('width')
-        .uint32('height')
-        .uint32('red_offset')
-        .uint32('red_length')
-        .uint32('blue_offset')
-        .uint32('blue_length')
-        .uint32('green_offset')
-        .uint32('green_length')
-        .uint32('alpha_offset')
-        .uint32('alpha_length')
-        .uint8Array('data', { lengthField: 'size' });
-
-export type AdbFrameBufferV1 = typeof AdbFrameBufferV1['TDeserializeResult'];
-
-export const AdbFrameBufferV2 =
-    new Struct({ littleEndian: true })
-        .uint32('bpp')
-        .uint32('colorSpace')
-        .uint32('size')
-        .uint32('width')
-        .uint32('height')
-        .uint32('red_offset')
-        .uint32('red_length')
-        .uint32('blue_offset')
-        .uint32('blue_length')
-        .uint32('green_offset')
-        .uint32('green_length')
-        .uint32('alpha_offset')
-        .uint32('alpha_length')
-        .uint8Array('data', { lengthField: 'size' });
-
-export type AdbFrameBufferV2 = typeof AdbFrameBufferV2['TDeserializeResult'];
-
 export type AdbFrameBuffer = AdbFrameBufferV1 | AdbFrameBufferV2;
 
 export async function framebuffer(adb: Adb): Promise<AdbFrameBuffer> {
-    const socket = await adb.createSocket('framebuffer:');
-    const stream = new AdbBufferedStream(socket);
+    const socket = await adb.createSocket("framebuffer:");
+    const stream = new BufferedReadableStream(socket.readable);
     const { version } = await Version.deserialize(stream);
     switch (version) {
         case 1:
+            // TODO: AdbFrameBuffer: does all v1 responses uses the same color space? Add it so the command returns same format for all versions.
             return AdbFrameBufferV1.deserialize(stream);
         case 2:
             return AdbFrameBufferV2.deserialize(stream);
         default:
-            throw new Error('Unknown FrameBuffer version');
+            throw new Error("Unknown FrameBuffer version");
     }
 }

package/src/commands/install.ts

@@ -1,30 +1,40 @@
-import type { Adb } from "../adb.js";
-import { WrapWritableStream, WritableStream } from "../stream/index.js";
+import {
+    WrapWritableStream,
+    type WritableStream,
+} from "@yume-chan/stream-extra";
+
+import { type Adb } from "../adb.js";
+
 import { escapeArg } from "./subprocess/index.js";
-import type { AdbSync } from "./sync/index.js";
+import { type AdbSync } from "./sync/index.js";
 
-export function install(
-    adb: Adb,
-): WritableStream<Uint8Array> {
-    const filename = `/data/local/tmp/${Math.random().toString().substring(2)}.apk`;
+export function install(adb: Adb): WritableStream<Uint8Array> {
+    const filename = `/data/local/tmp/${Math.random()
+        .toString()
+        .substring(2)}.apk`;
 
     let sync!: AdbSync;
     return new WrapWritableStream<Uint8Array>({
         async start() {
             // TODO: install: support other install apk methods (streaming, etc.)
+            // TODO: install: support split apk formats (`adb install-multiple`)
 
             // Upload apk file to tmp folder
             sync = await adb.sync();
             return sync.write(filename, undefined, undefined);
         },
         async close() {
-            sync.dispose();
+            await sync.dispose();
 
             // Invoke `pm install` to install it
-            await adb.subprocess.spawnAndWaitLegacy(['pm', 'install', escapeArg(filename)]);
+            await adb.subprocess.spawnAndWaitLegacy([
+                "pm",
+                "install",
+                escapeArg(filename),
+            ]);
 
             // Remove the temp file
             await adb.rm(filename);
-        }
+        },
     });
 }