@yume-chan/adb 0.0.10 → 0.0.11

package/src/adb.ts

@@ -1,12 +1,11 @@
 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 { AdbAuthenticationHandler, AdbDefaultAuthenticators, 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, AdbPacket, calculateChecksum, type AdbPacketCore, type AdbPacketInit } from './packet.js';
+import { AdbPacketDispatcher, 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,68 +14,21 @@ export enum AdbPropKey {
     Features = 'features',
 }
 
-export class Adb {
-    private readonly _backend: AdbBackend;
-
-    public get backend(): AdbBackend { return this._backend; }
-
-    private readonly packetDispatcher: AdbPacketDispatcher;
-
-    public get onDisconnected() { return this.backend.onDisconnected; }
-
-    private _connected = false;
-    public get connected() { return this._connected; }
-
-    public get name() { return this.backend.name; }
-
-    private _protocolVersion: number | undefined;
-    public get protocolVersion() { return this._protocolVersion; }
-
-    private _product: string | undefined;
-    public get product() { return this._product; }
-
-    private _model: string | undefined;
-    public get model() { return this._model; }
-
-    private _device: string | undefined;
-    public get device() { return this._device; }
-
-    private _features: AdbFeatures[] | undefined;
-    public get features() { return this._features; }
-
-    public readonly tcpip: AdbTcpIpCommand;
-
-    public readonly reverse: AdbReverseCommand;
-
-    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);
+export const VERSION_OMIT_CHECKSUM = 0x01000001;
 
-        backend.onDisconnected(this.dispose, this);
-    }
-
-    public async connect(
+export class Adb {
+    /**
+     * 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<AdbPacketCore, AdbPacketCore>,
         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;
+        authenticators = AdbDefaultAuthenticators,
+    ): Promise<Adb> {
+        let version = 0x01000001;
+        let maxPayloadSize = 0x100000;
 
         const features = [
             'shell_v2',
@@ -97,76 +49,129 @@ export class Adb {
             'sendrecv_v2_dry_run_send',
         ].join(',');
 
-        const resolver = new PromiseResolver<void>();
+        const resolver = new PromiseResolver<string>();
         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');
+
+        const abortController = new AbortController();
+        const pipe = connection.readable
+            .pipeTo(new WritableStream({
+                async write(packet: AdbPacket) {
+                    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 authHandler.handle(packet);
+                            await sendPacket(response);
+                            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);
-            }
-        }));
-
-        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`
-        );
+            }), {
+                preventCancel: true,
+                signal: abortController.signal,
+            })
+            .catch((e) => { resolver.reject(e); });
+
+        const writer = connection.writable.getWriter();
+        async function sendPacket(init: AdbPacketCore) {
+            // Always send checksum in auth steps
+            // Because we don't know if the device will ignore it yet.
+            await writer.write(calculateChecksum(init));
+        }
+
+        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};`),
+        });
 
         try {
-            await resolver.promise;
-            this._connected = true;
+            const banner = await resolver.promise;
+
+            // Stop piping before creating Adb object
+            // Because AdbPacketDispatcher will try to lock the streams when initializing
+            abortController.abort();
+            await pipe;
+
+            writer.releaseLock();
+
+            return new Adb(
+                connection,
+                version,
+                maxPayloadSize,
+                banner,
+            );
         } finally {
-            disposableList.dispose();
+            abortController.abort();
+            writer.releaseLock();
         }
     }
 
+    private readonly packetDispatcher: AdbPacketDispatcher;
+
+    public get disconnected() { return this.packetDispatcher.disconnected; }
+
+    private _protocolVersion: number | undefined;
+    public get protocolVersion() { return this._protocolVersion; }
+
+    private _product: string | undefined;
+    public get product() { return this._product; }
+
+    private _model: string | undefined;
+    public get model() { return this._model; }
+
+    private _device: string | undefined;
+    public get device() { return this._device; }
+
+    private _features: AdbFeatures[] | undefined;
+    public get features() { return this._features; }
+
+    public readonly subprocess: AdbSubprocess;
+    public readonly power: AdbPower;
+    public readonly reverse: AdbReverseCommand;
+    public readonly tcpip: AdbTcpIpCommand;
+
+    public constructor(
+        connection: ReadableWritablePair<AdbPacketCore, AdbPacketInit>,
+        version: number,
+        maxPayloadSize: number,
+        banner: string,
+    ) {
+        this.parseBanner(banner);
+        this.packetDispatcher = new AdbPacketDispatcher(connection);
+
+        this._protocolVersion = version;
+        if (version >= VERSION_OMIT_CHECKSUM) {
+            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.packetDispatcher.maxPayloadSize = maxPayloadSize;
+
+        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 {
         this._features = [];
 
         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,7 +194,7 @@ export class Adb {
                         this._device = value;
                         break;
                     case AdbPropKey.Features:
-                        this._features = value.split(',') as AdbFeatures[];
+                        this._features = value!.split(',') as AdbFeatures[];
                         break;
                 }
             }
@@ -197,19 +202,21 @@ export class Adb {
     }
 
     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> {
@@ -225,19 +232,16 @@ export class Adb {
         return this.packetDispatcher.createSocket(service);
     }
 
-    public async createSocketAndReadAll(service: string): Promise<string> {
+    public async createSocketAndWait(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;
+        const gatherStream = new GatherStringStream();
+        await socket.readable
+            .pipeThrough(new DecodeUtf8Stream())
+            .pipeTo(gatherStream.writable);
+        return gatherStream.result;
     }
 
     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, AdbPacket, type AdbPacketCore } 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.
@@ -44,13 +44,13 @@ export interface AdbAuthenticator {
     (
         credentialStore: AdbCredentialStore,
         getNextRequest: () => Promise<AdbPacket>
-    ): AsyncIterable<AdbPacketInit>;
+    ): AsyncIterable<AdbPacketCore>;
 }
 
 export const AdbSignatureAuthenticator: AdbAuthenticator = async function* (
     credentialStore: AdbCredentialStore,
     getNextRequest: () => Promise<AdbPacket>,
-): AsyncIterable<AdbPacketInit> {
+): AsyncIterable<AdbPacketCore> {
     for await (const key of credentialStore.iterateKeys()) {
         const packet = await getNextRequest();
 
@@ -58,12 +58,12 @@ 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),
         };
     }
 };
@@ -71,19 +71,20 @@ export const AdbSignatureAuthenticator: AdbAuthenticator = async function* (
 export const AdbPublicKeyAuthenticator: AdbAuthenticator = async function* (
     credentialStore: AdbCredentialStore,
     getNextRequest: () => Promise<AdbPacket>,
-): AsyncIterable<AdbPacketInit> {
+): AsyncIterable<AdbPacketCore> {
     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,
@@ -118,7 +122,7 @@ export class AdbAuthenticationHandler implements Disposable {
 
     private pendingRequest = new PromiseResolver<AdbPacket>();
 
-    private iterator: AsyncIterator<AdbPacketInit> | undefined;
+    private iterator: AsyncIterator<AdbPacketCore> | undefined;
 
     public constructor(
         authenticators: readonly AdbAuthenticator[],
@@ -132,7 +136,7 @@ export class AdbAuthenticationHandler implements Disposable {
         return this.pendingRequest.promise;
     };
 
-    private async* runAuthenticator(): AsyncGenerator<AdbPacketInit> {
+    private async* runAuthenticator(): AsyncGenerator<AdbPacketCore> {
         for (const authenticator of this.authenticators) {
             for await (const packet of authenticator(this.credentialStore, this.getNextRequest)) {
                 // If the authenticator yielded a response
@@ -150,7 +154,7 @@ export class AdbAuthenticationHandler implements Disposable {
         throw new Error('Cannot authenticate with device');
     }
 
-    public async handle(packet: AdbPacket): Promise<AdbPacketInit> {
+    public async handle(packet: AdbPacket): Promise<AdbPacketCore> {
         if (!this.iterator) {
             this.iterator = this.runAuthenticator();
         }

package/src/backend.ts

@@ -1,20 +1,11 @@
-import type { Event } from '@yume-chan/event';
 import type { ValueOrPromise } from '@yume-chan/struct';
+import type { AdbPacketCore, 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<AdbPacketCore, 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';

package/src/commands/install.ts

@@ -1,21 +1,32 @@
-import { Adb } from "../adb";
-import { escapeArg } from "./shell";
+import type { Adb } from "../adb.js";
+import { WrapWritableStream, WritableStream } from "../stream/index.js";
+import { escapeArg } from "./subprocess/index.js";
+import type { AdbSync } from "./sync/index.js";
 
-export async function install(
+export function install(
     adb: Adb,
-    apk: ArrayLike<number> | ArrayBufferLike | AsyncIterable<ArrayBuffer>,
-    onProgress?: (uploaded: number) => void,
-): Promise<void> {
-    const filename = `/data/local/tmp/${Math.random().toString().substr(2)}.apk`;
+): WritableStream<Uint8Array> {
+    const filename = `/data/local/tmp/${Math.random().toString().substring(2)}.apk`;
 
-    // Upload apk file to tmp folder
-    const sync = await adb.sync();
-    await sync.write(filename, apk, undefined, undefined, onProgress);
-    sync.dispose();
+    return new WrapWritableStream<Uint8Array, WritableStream<Uint8Array>, AdbSync>({
+        async start() {
+            // Upload apk file to tmp folder
+            const sync = await adb.sync();
+            const writable = sync.write(filename, undefined, undefined);
 
-    // Invoke `pm install` to install it
-    await adb.childProcess.exec('pm', 'install', escapeArg(filename));
+            return {
+                writable,
+                state: sync,
+            };
+        },
+        async close(sync) {
+            sync.dispose();
 
-    // Remove the temp file
-    await adb.rm(filename);
+            // Invoke `pm install` to install it
+            await adb.subprocess.spawnAndWaitLegacy(['pm', 'install', escapeArg(filename)]);
+
+            // Remove the temp file
+            await adb.rm(filename);
+        }
+    });
 }

package/src/commands/power.ts

@@ -0,0 +1,54 @@
+// cspell: ignore bootloader
+// cspell: ignore fastboot
+// cspell: ignore keyevent
+// cspell: ignore longpress
+
+import { AdbCommandBase } from "./base.js";
+
+export class AdbPower extends AdbCommandBase {
+    public reboot(name: string = '') {
+        return this.adb.createSocketAndWait(`reboot:${name}`);
+    }
+
+    public bootloader() {
+        return this.reboot('bootloader');
+    }
+
+    public fastboot() {
+        return this.reboot('fastboot');
+    }
+
+    public recovery() {
+        return this.reboot('recovery');
+    }
+
+    public sideload() {
+        return this.reboot('sideload');
+    }
+
+    /**
+     * Reboot to Qualcomm Emergency Download (EDL) Mode.
+     *
+     * Only works on some Qualcomm devices.
+     */
+    public qualcommEdlMode() {
+        return this.reboot('edl');
+    }
+
+    public powerOff() {
+        return this.adb.subprocess.spawnAndWaitLegacy(['reboot', '-p']);
+    }
+
+    public powerButton(longPress: boolean = false) {
+        return this.adb.subprocess.spawnAndWaitLegacy(['input', 'keyevent', longPress ? '--longpress POWER' : 'POWER']);
+    }
+
+    /**
+     * Reboot to Samsung Odin download mode.
+     *
+     * Only works on Samsung devices.
+     */
+    public samsungOdin() {
+        return this.reboot('download');
+    }
+}