@yume-chan/adb 0.0.10 → 0.0.13

package/src/adb.ts

@@ -1,12 +1,13 @@
+// cspell: ignore libusb
+
 import { PromiseResolver } from '@yume-chan/async';
-import { DisposableList } from '@yume-chan/event';
-import { AdbAuthenticationHandler, AdbCredentialStore, AdbDefaultAuthenticators } from './auth';
-import { AdbBackend } from './backend';
-import { AdbChildProcess, AdbDemoMode, AdbFrameBuffer, AdbReverseCommand, AdbSync, AdbTcpIpCommand, escapeArg, framebuffer, install } from './commands';
-import { AdbFeatures } from './features';
-import { AdbCommand } from './packet';
-import { AdbLogger, AdbPacketDispatcher, AdbSocket } from './socket';
-import { decodeUtf8 } from "./utils";
+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 { AdbPacketDispatcher, type AdbSocket } from './socket/index.js';
+import { AbortController, DecodeUtf8Stream, GatherStringStream, WritableStream, type ReadableWritablePair } from "./stream/index.js";
+import { decodeUtf8, encodeUtf8 } from "./utils/index.js";
 
 export enum AdbPropKey {
     Product = 'ro.product.name',
@@ -15,19 +16,123 @@ export enum AdbPropKey {
     Features = 'features',
 }
 
+export const VERSION_OMIT_CHECKSUM = 0x01000001;
+
 export class Adb {
-    private readonly _backend: AdbBackend;
+    /**
+     * It's possible to call `authenticate` multiple times on a single connection,
+     * every time the device receives a `CNXN` packet, it resets its internal state,
+     * and starts a new authentication process.
+     */
+    public static async authenticate(
+        connection: ReadableWritablePair<AdbPacketData, AdbPacketInit>,
+        credentialStore: AdbCredentialStore,
+        authenticators = ADB_DEFAULT_AUTHENTICATORS,
+    ): Promise<Adb> {
+        // Initially, set to highest-supported version and payload size.
+        let version = 0x01000001;
+        let maxPayloadSize = 0x100000;
 
-    public get backend(): AdbBackend { return this._backend; }
+        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 session 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;
+                    }
+                }
+            }), {
+                preventCancel: true,
+                signal: abortController.signal,
+            })
+            .catch((e) => {
+                resolver.reject(e);
+            });
 
-    private readonly packetDispatcher: AdbPacketDispatcher;
+        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.
+            await writer.write(calculateChecksum(init));
+        }
 
-    public get onDisconnected() { return this.backend.onDisconnected; }
+        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.
+            const features = [
+                AdbFeatures.ShellV2,
+                AdbFeatures.Cmd,
+                AdbFeatures.StatV2,
+                AdbFeatures.ListV2,
+                'fixed_push_mkdir',
+                'apex',
+                'abb',
+                '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,
+                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};`),
+            });
+
+            const banner = await resolver.promise;
+
+            // Stop piping before creating `Adb` object
+            // Because `AdbPacketDispatcher` will lock the streams when initializing
+            abortController.abort();
+            writer.releaseLock();
+
+            // Wait until pipe stops (`ReadableStream` lock released)
+            await pipe;
+
+            return new Adb(
+                connection,
+                version,
+                maxPayloadSize,
+                banner,
+            );
+        } catch (e) {
+            abortController.abort();
+            writer.releaseLock();
+            throw e;
+        }
+    }
 
-    private _connected = false;
-    public get connected() { return this._connected; }
+    private readonly packetDispatcher: AdbPacketDispatcher;
 
-    public get name() { return this.backend.name; }
+    public get disconnected() { return this.packetDispatcher.disconnected; }
 
     private _protocolVersion: number | undefined;
     public get protocolVersion() { return this._protocolVersion; }
@@ -44,121 +149,44 @@ export class Adb {
     private _features: AdbFeatures[] | undefined;
     public get features() { return this._features; }
 
-    public readonly tcpip: AdbTcpIpCommand;
-
+    public readonly subprocess: AdbSubprocess;
+    public readonly power: AdbPower;
     public readonly reverse: AdbReverseCommand;
+    public readonly tcpip: AdbTcpIpCommand;
 
-    public readonly demoMode: AdbDemoMode;
-
-    public readonly childProcess: AdbChildProcess;
-
-    public constructor(backend: AdbBackend, logger?: AdbLogger) {
-        this._backend = backend;
-        this.packetDispatcher = new AdbPacketDispatcher(backend, logger);
-
-        this.tcpip = new AdbTcpIpCommand(this);
-        this.reverse = new AdbReverseCommand(this.packetDispatcher);
-        this.demoMode = new AdbDemoMode(this);
-        this.childProcess = new AdbChildProcess(this);
-
-        backend.onDisconnected(this.dispose, this);
-    }
+    public constructor(
+        connection: ReadableWritablePair<AdbPacketData, AdbPacketInit>,
+        version: number,
+        maxPayloadSize: number,
+        banner: string,
+    ) {
+        this.parseBanner(banner);
+
+        let calculateChecksum: boolean;
+        let appendNullToServiceString: boolean;
+        if (version >= VERSION_OMIT_CHECKSUM) {
+            calculateChecksum = false;
+            appendNullToServiceString = false;
+        } else {
+            calculateChecksum = true;
+            appendNullToServiceString = true;
+        }
 
-    public async connect(
-        credentialStore: AdbCredentialStore,
-        authenticators = AdbDefaultAuthenticators
-    ): Promise<void> {
-        await this.backend.connect?.();
-        this.packetDispatcher.maxPayloadSize = 0x1000;
-        this.packetDispatcher.calculateChecksum = true;
-        this.packetDispatcher.appendNullToServiceString = true;
-        this.packetDispatcher.start();
-
-        const version = 0x01000001;
-        const versionNoChecksum = 0x01000001;
-        const maxPayloadSize = 0x100000;
-
-        const features = [
-            'shell_v2',
-            'cmd',
-            AdbFeatures.StatV2,
-            'ls_v2',
-            'fixed_push_mkdir',
-            'apex',
-            'abb',
-            '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(',');
-
-        const resolver = new PromiseResolver<void>();
-        const authHandler = new AdbAuthenticationHandler(authenticators, credentialStore);
-        const disposableList = new DisposableList();
-        disposableList.add(this.packetDispatcher.onPacket(async (e) => {
-            e.handled = true;
-
-            const { packet } = e;
-            try {
-                switch (packet.command) {
-                    case AdbCommand.Connect:
-                        this.packetDispatcher.maxPayloadSize = Math.min(maxPayloadSize, packet.arg1);
-
-                        const finalVersion = Math.min(version, packet.arg0);
-                        this._protocolVersion = finalVersion;
-
-                        if (finalVersion >= versionNoChecksum) {
-                            this.packetDispatcher.calculateChecksum = false;
-                            // Android prior to 9.0.0 uses char* to parse service string
-                            // thus requires an extra null character
-                            this.packetDispatcher.appendNullToServiceString = false;
-                        }
-
-                        this.parseBanner(decodeUtf8(packet.payload!));
-                        resolver.resolve();
-                        break;
-                    case AdbCommand.Auth:
-                        const authPacket = await authHandler.handle(e.packet);
-                        await this.packetDispatcher.sendPacket(authPacket);
-                        break;
-                    case AdbCommand.Close:
-                        // Last connection was interrupted
-                        // Ignore this packet, device will recover
-                        break;
-                    default:
-                        throw new Error('Device not in correct state. Reconnect your device and try again');
-                }
-            } catch (e) {
-                resolver.reject(e);
+        this.packetDispatcher = new AdbPacketDispatcher(
+            connection,
+            {
+                calculateChecksum,
+                appendNullToServiceString,
+                maxPayloadSize,
             }
-        }));
-
-        disposableList.add(this.packetDispatcher.onError(e => {
-            resolver.reject(e);
-        }));
-
-        // Android prior 9.0.0 requires the null character
-        // Newer versions can also handle the null character
-        // The terminating `;` is required in formal definition
-        // But ADB daemon can also work without it
-        await this.packetDispatcher.sendPacket(
-            AdbCommand.Connect,
-            version,
-            maxPayloadSize,
-            `host::features=${features};\0`
         );
 
-        try {
-            await resolver.promise;
-            this._connected = true;
-        } finally {
-            disposableList.dispose();
-        }
+        this._protocolVersion = version;
+
+        this.subprocess = new AdbSubprocess(this);
+        this.power = new AdbPower(this);
+        this.reverse = new AdbReverseCommand(this.packetDispatcher);
+        this.tcpip = new AdbTcpIpCommand(this);
     }
 
     private parseBanner(banner: string): void {
@@ -166,7 +194,7 @@ export class Adb {
 
         const pieces = banner.split('::');
         if (pieces.length > 1) {
-            const props = pieces[1];
+            const props = pieces[1]!;
             for (const prop of props.split(';')) {
                 if (!prop) {
                     continue;
@@ -189,27 +217,42 @@ export class Adb {
                         this._device = value;
                         break;
                     case AdbPropKey.Features:
-                        this._features = value.split(',') as AdbFeatures[];
+                        this._features = value!.split(',') as AdbFeatures[];
                         break;
                 }
             }
         }
     }
 
+    public async createSocket(service: string): Promise<AdbSocket> {
+        return this.packetDispatcher.createSocket(service);
+    }
+
+    public async createSocketAndWait(service: string): Promise<string> {
+        const socket = await this.createSocket(service);
+        const gatherStream = new GatherStringStream();
+        await socket.readable
+            .pipeThrough(new DecodeUtf8Stream())
+            .pipeTo(gatherStream);
+        return gatherStream.result;
+    }
+
     public async getProp(key: string): Promise<string> {
-        const output = await this.childProcess.exec('getprop', key);
-        return output.trim();
+        const stdout = await this.subprocess.spawnAndWaitLegacy(
+            ['getprop', key]
+        );
+        return stdout.trim();
     }
 
     public async rm(...filenames: string[]): Promise<string> {
-        return await this.childProcess.exec('rm', '-rf', ...filenames.map(arg => escapeArg(arg)));
+        const stdout = await this.subprocess.spawnAndWaitLegacy(
+            ['rm', '-rf', ...filenames.map(arg => escapeArg(arg))],
+        );
+        return stdout;
     }
 
-    public async install(
-        apk: ArrayLike<number> | ArrayBufferLike | AsyncIterable<ArrayBuffer>,
-        onProgress?: (uploaded: number) => void,
-    ): Promise<void> {
-        return await install(this, apk, onProgress);
+    public install() {
+        return install(this);
     }
 
     public async sync(): Promise<AdbSync> {
@@ -221,23 +264,7 @@ export class Adb {
         return framebuffer(this);
     }
 
-    public async createSocket(service: string): Promise<AdbSocket> {
-        return this.packetDispatcher.createSocket(service);
-    }
-
-    public async createSocketAndReadAll(service: string): Promise<string> {
-        const socket = await this.createSocket(service);
-        const resolver = new PromiseResolver<string>();
-        let result = '';
-        socket.onData(buffer => {
-            result += decodeUtf8(buffer);
-        });
-        socket.onClose(() => resolver.resolve(result));
-        return resolver.promise;
-    }
-
     public async dispose(): Promise<void> {
         this.packetDispatcher.dispose();
-        await this.backend.dispose();
     }
 }

package/src/auth.ts

@@ -1,19 +1,19 @@
 import { PromiseResolver } from '@yume-chan/async';
-import { Disposable } from '@yume-chan/event';
-import { ValueOrPromise } from '@yume-chan/struct';
-import { calculatePublicKey, calculatePublicKeyLength, sign } from './crypto';
-import { AdbCommand, AdbPacket, AdbPacketInit } from './packet';
-import { calculateBase64EncodedLength, encodeBase64 } from './utils';
+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<ArrayBuffer> | AsyncIterable<ArrayBuffer>;
+export type AdbKeyIterable = Iterable<Uint8Array> | AsyncIterable<Uint8Array>;
 
 export interface AdbCredentialStore {
     /**
      * Generate and store a RSA private key with modulus length `2048` and public exponent `65537`.
      *
-     * The returned `ArrayBuffer` is the private key in PKCS #8 format.
+     * The returned `Uint8Array` is the private key in PKCS #8 format.
      */
-    generateKey(): ValueOrPromise<ArrayBuffer>;
+    generateKey(): ValueOrPromise<Uint8Array>;
 
     /**
      * Synchronously or asynchronously iterate through all stored RSA private keys.
@@ -43,14 +43,14 @@ export interface AdbAuthenticator {
      */
     (
         credentialStore: AdbCredentialStore,
-        getNextRequest: () => Promise<AdbPacket>
-    ): AsyncIterable<AdbPacketInit>;
+        getNextRequest: () => Promise<AdbPacketData>
+    ): AsyncIterable<AdbPacketData>;
 }
 
 export const AdbSignatureAuthenticator: AdbAuthenticator = async function* (
     credentialStore: AdbCredentialStore,
-    getNextRequest: () => Promise<AdbPacket>,
-): AsyncIterable<AdbPacketInit> {
+    getNextRequest: () => Promise<AdbPacketData>,
+): AsyncIterable<AdbPacketData> {
     for await (const key of credentialStore.iterateKeys()) {
         const packet = await getNextRequest();
 
@@ -58,32 +58,33 @@ export const AdbSignatureAuthenticator: AdbAuthenticator = async function* (
             return;
         }
 
-        const signature = sign(key, packet.payload!);
+        const signature = sign(key, packet.payload);
         yield {
             command: AdbCommand.Auth,
             arg0: AdbAuthType.Signature,
             arg1: 0,
-            payload: signature,
+            payload: new Uint8Array(signature),
         };
     }
 };
 
 export const AdbPublicKeyAuthenticator: AdbAuthenticator = async function* (
     credentialStore: AdbCredentialStore,
-    getNextRequest: () => Promise<AdbPacket>,
-): AsyncIterable<AdbPacketInit> {
+    getNextRequest: () => Promise<AdbPacketData>,
+): AsyncIterable<AdbPacketData> {
     const packet = await getNextRequest();
 
     if (packet.arg0 !== AdbAuthType.Token) {
         return;
     }
 
-    let privateKey: ArrayBuffer | undefined;
+    let privateKey: Uint8Array | undefined;
     for await (const key of credentialStore.iterateKeys()) {
         privateKey = key;
         break;
     }
 
+
     if (!privateKey) {
         privateKey = await credentialStore.generateKey();
     }
@@ -93,10 +94,13 @@ export const AdbPublicKeyAuthenticator: AdbAuthenticator = async function* (
 
     // The public key is null terminated,
     // So we allocate the buffer with one extra byte.
-    const publicKeyBuffer = new ArrayBuffer(publicKeyBase64Length + 1);
+    const publicKeyBuffer = new Uint8Array(publicKeyBase64Length + 1);
 
     calculatePublicKey(privateKey, publicKeyBuffer);
-    encodeBase64(publicKeyBuffer, 0, publicKeyLength, publicKeyBuffer);
+    encodeBase64(
+        publicKeyBuffer.subarray(0, publicKeyLength),
+        publicKeyBuffer
+    );
 
     yield {
         command: AdbCommand.Auth,
@@ -106,19 +110,19 @@ export const AdbPublicKeyAuthenticator: AdbAuthenticator = async function* (
     };
 };
 
-export const AdbDefaultAuthenticators: AdbAuthenticator[] = [
+export const ADB_DEFAULT_AUTHENTICATORS: AdbAuthenticator[] = [
     AdbSignatureAuthenticator,
     AdbPublicKeyAuthenticator,
 ];
 
-export class AdbAuthenticationHandler implements Disposable {
+export class AdbAuthenticationProcessor implements Disposable {
     public readonly authenticators: readonly AdbAuthenticator[];
 
     private readonly credentialStore: AdbCredentialStore;
 
-    private pendingRequest = new PromiseResolver<AdbPacket>();
+    private pendingRequest = new PromiseResolver<AdbPacketData>();
 
-    private iterator: AsyncIterator<AdbPacketInit> | undefined;
+    private iterator: AsyncIterator<AdbPacketData, void, void> | undefined;
 
     public constructor(
         authenticators: readonly AdbAuthenticator[],
@@ -128,16 +132,16 @@ export class AdbAuthenticationHandler implements Disposable {
         this.credentialStore = credentialStore;
     }
 
-    private getNextRequest = (): Promise<AdbPacket> => {
+    private getNextRequest = (): Promise<AdbPacketData> => {
         return this.pendingRequest.promise;
     };
 
-    private async* runAuthenticator(): AsyncGenerator<AdbPacketInit> {
+    private async* invokeAuthenticator(): AsyncGenerator<AdbPacketData, void, void> {
         for (const authenticator of this.authenticators) {
             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<AdbPacket>();
+                this.pendingRequest = new PromiseResolver();
 
                 // Yield the response to outer layer
                 yield packet;
@@ -146,17 +150,20 @@ export class AdbAuthenticationHandler implements Disposable {
             // If the authenticator returned,
             // Next authenticator will be given the same `pendingRequest`
         }
-
-        throw new Error('Cannot authenticate with device');
     }
 
-    public async handle(packet: AdbPacket): Promise<AdbPacketInit> {
+    public async process(packet: AdbPacketData): Promise<AdbPacketData> {
         if (!this.iterator) {
-            this.iterator = this.runAuthenticator();
+            this.iterator = this.invokeAuthenticator();
         }
 
         this.pendingRequest.resolve(packet);
+
         const result = await this.iterator.next();
+        if (result.done) {
+            throw new Error('No authenticator can handle the request');
+        }
+
         return result.value;
     }
 

package/src/backend.ts

@@ -1,20 +1,11 @@
-import type { Event } from '@yume-chan/event';
 import type { ValueOrPromise } from '@yume-chan/struct';
+import type { AdbPacketData, AdbPacketInit } from "./packet.js";
+import type { ReadableWritablePair } from "./stream/index.js";
 
 export interface AdbBackend {
     readonly serial: string;
 
     readonly name: string | undefined;
 
-    readonly connected: boolean;
-
-    readonly onDisconnected: Event<void>;
-
-    connect?(): ValueOrPromise<void>;
-
-    read(length: number): ValueOrPromise<ArrayBuffer>;
-
-    write(buffer: ArrayBuffer): ValueOrPromise<void>;
-
-    dispose(): ValueOrPromise<void>;
+    connect(): ValueOrPromise<ReadableWritablePair<AdbPacketData, AdbPacketInit>>;
 }

package/src/commands/base.ts

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

package/src/commands/framebuffer.ts

@@ -1,6 +1,6 @@
 import Struct from "@yume-chan/struct";
-import { Adb } from '../adb';
-import { AdbBufferedStream } from '../stream';
+import type { Adb } from '../adb.js';
+import { AdbBufferedStream } from '../stream/index.js';
 
 const Version =
     new Struct({ littleEndian: true })
@@ -33,7 +33,7 @@ export const AdbFrameBufferV1 =
         .uint32('green_length')
         .uint32('alpha_offset')
         .uint32('alpha_length')
-        .uint8ClampedArray('data', { lengthField: 'size' });
+        .uint8Array('data', { lengthField: 'size' });
 
 export type AdbFrameBufferV1 = typeof AdbFrameBufferV1['TDeserializeResult'];
 
@@ -52,7 +52,7 @@ export const AdbFrameBufferV2 =
         .uint32('green_length')
         .uint32('alpha_offset')
         .uint32('alpha_length')
-        .uint8ClampedArray('data', { lengthField: 'size' });
+        .uint8Array('data', { lengthField: 'size' });
 
 export type AdbFrameBufferV2 = typeof AdbFrameBufferV2['TDeserializeResult'];
 

package/src/commands/index.ts

@@ -1,8 +1,8 @@
-export * from './base';
-export * from './demo-mode';
-export * from './framebuffer';
-export * from './install';
-export * from './reverse';
-export * from './shell';
-export * from './sync';
-export * from './tcpip';
+export * from './base.js';
+export * from './framebuffer.js';
+export * from './install.js';
+export * from './power.js';
+export * from './reverse.js';
+export * from './subprocess/index.js';
+export * from './sync/index.js';
+export * from './tcpip.js';