@yume-chan/adb 0.0.10 → 0.0.13

package/src/commands/install.ts

@@ -1,21 +1,30 @@
-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();
+    let sync!: AdbSync;
+    return new WrapWritableStream<Uint8Array>({
+        async start() {
+            // TODO: install: support other install apk methods (streaming, etc.)
 
-    // Invoke `pm install` to install it
-    await adb.childProcess.exec('pm', 'install', escapeArg(filename));
+            // Upload apk file to tmp folder
+            sync = await adb.sync();
+            return sync.write(filename, undefined, undefined);
+        },
+        async close() {
+            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');
+    }
+}

package/src/commands/reverse.ts

@@ -1,12 +1,14 @@
+// cspell: ignore killforward
+
 import { AutoDisposable } from '@yume-chan/event';
 import Struct from '@yume-chan/struct';
-import type { AdbPacket } from '../packet';
-import type { AdbIncomingSocketEventArgs, AdbPacketDispatcher, AdbSocket } from '../socket';
-import { AdbBufferedStream } from '../stream';
-import { decodeUtf8 } from "../utils";
+import type { AdbPacketData } from '../packet.js';
+import type { AdbIncomingSocketEventArgs, AdbPacketDispatcher, AdbSocket } from '../socket/index.js';
+import { AdbBufferedStream } from '../stream/index.js';
+import { decodeUtf8 } from "../utils/index.js";
 
 export interface AdbReverseHandler {
-    onSocket(packet: AdbPacket, socket: AdbSocket): void;
+    onSocket(packet: AdbPacketData, socket: AdbSocket): void;
 }
 
 export interface AdbForwardListener {
@@ -50,8 +52,8 @@ export class AdbReverseCommand extends AutoDisposable {
             return;
         }
 
-        const address = decodeUtf8(e.packet.payload!);
-        // tcp:1234\0
+        const address = decodeUtf8(e.packet.payload);
+        // Address format: `tcp:12345\0`
         const port = Number.parseInt(address.substring(4));
         if (this.localPortToHandler.has(port)) {
             this.localPortToHandler.get(port)!.onSocket(e.packet, e.socket);
@@ -78,7 +80,7 @@ export class AdbReverseCommand extends AutoDisposable {
 
         const response = await AdbReverseStringResponse.deserialize(stream);
         return response.content!.split('\n').map(line => {
-            const [deviceSerial, localName, remoteName] = line.split(' ');
+            const [deviceSerial, localName, remoteName] = line.split(' ') as [string, string, string];
             return { deviceSerial, localName, remoteName };
         });
 

package/src/commands/subprocess/index.ts

@@ -0,0 +1,139 @@
+import type { Adb } from '../../adb.js';
+import { DecodeUtf8Stream, GatherStringStream } from "../../stream/index.js";
+import { AdbSubprocessNoneProtocol, AdbSubprocessShellProtocol, type AdbSubprocessProtocol, type AdbSubprocessProtocolConstructor } from './protocols/index.js';
+
+export * from './protocols/index.js';
+export * from './utils.js';
+
+export interface AdbSubprocessOptions {
+    /**
+     * A list of `AdbSubprocessProtocolConstructor`s to be used.
+     *
+     * Different `AdbSubprocessProtocol` has different capabilities, thus requires specific adaptations.
+     * Check their documentations for details.
+     *
+     * The first protocol whose `isSupported` returns `true` will be used.
+     * If no `AdbSubprocessProtocol` is supported, an error will be thrown.
+     *
+     * @default [AdbSubprocessShellProtocol, AdbSubprocessNoneProtocol]
+     */
+    protocols: AdbSubprocessProtocolConstructor[];
+}
+
+const DEFAULT_OPTIONS: AdbSubprocessOptions = {
+    protocols: [AdbSubprocessShellProtocol, AdbSubprocessNoneProtocol],
+};
+
+export interface AdbSubprocessWaitResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+
+export class AdbSubprocess {
+    public readonly adb: Adb;
+
+    public constructor(adb: Adb) {
+        this.adb = adb;
+    }
+
+    private async createProtocol(
+        mode: 'pty' | 'raw',
+        command?: string | string[],
+        options?: Partial<AdbSubprocessOptions>
+    ): Promise<AdbSubprocessProtocol> {
+        const { protocols } = { ...DEFAULT_OPTIONS, ...options };
+
+        let Constructor: AdbSubprocessProtocolConstructor | undefined;
+        for (const item of protocols) {
+            // It's async so can't use `Array#find`
+            if (await item.isSupported(this.adb)) {
+                Constructor = item;
+                break;
+            }
+        }
+
+        if (!Constructor) {
+            throw new Error('No specified protocol is supported by the device');
+        }
+
+        if (Array.isArray(command)) {
+            command = command.join(' ');
+        } else if (command === undefined) {
+            // spawn the default shell
+            command = '';
+        }
+        return await Constructor[mode](this.adb, command);
+    }
+
+    /**
+     * Spawns an executable in PTY (interactive) mode.
+     * @param command The command to run. If omitted, the default shell will be spawned.
+     * @param options The options for creating the `AdbSubprocessProtocol`
+     * @returns A new `AdbSubprocessProtocol` instance connecting to the spawned process.
+     */
+    public shell(
+        command?: string | string[],
+        options?: Partial<AdbSubprocessOptions>
+    ): Promise<AdbSubprocessProtocol> {
+        return this.createProtocol('pty', command, options);
+    }
+
+    /**
+     * Spawns an executable and pipe the output.
+     * @param command The command to run, or an array of strings containing both command and args.
+     * @param options The options for creating the `AdbSubprocessProtocol`
+     * @returns A new `AdbSubprocessProtocol` instance connecting to the spawned process.
+     */
+    public spawn(
+        command: string | string[],
+        options?: Partial<AdbSubprocessOptions>
+    ): Promise<AdbSubprocessProtocol> {
+        return this.createProtocol('raw', command, options);
+    }
+
+    /**
+     * Spawns a new process, waits until it exits, and returns the entire output.
+     * @param command The command to run
+     * @param options The options for creating the `AdbSubprocessProtocol`
+     * @returns The entire output of the command
+     */
+    public async spawnAndWait(
+        command: string | string[],
+        options?: Partial<AdbSubprocessOptions>
+    ): Promise<AdbSubprocessWaitResult> {
+        const shell = await this.spawn(command, options);
+
+        const stdout = new GatherStringStream();
+        const stderr = new GatherStringStream();
+
+        const [, , exitCode] = await Promise.all([
+            shell.stdout
+                .pipeThrough(new DecodeUtf8Stream())
+                .pipeTo(stdout),
+            shell.stderr
+                .pipeThrough(new DecodeUtf8Stream())
+                .pipeTo(stderr),
+            shell.exit
+        ]);
+
+        return {
+            stdout: stdout.result,
+            stderr: stderr.result,
+            exitCode,
+        };
+    }
+
+    /**
+     * Spawns a new process, waits until it exits, and returns the entire output.
+     * @param command The command to run
+     * @returns The entire output of the command
+     */
+    public async spawnAndWaitLegacy(command: string | string[]): Promise<string> {
+        const { stdout } = await this.spawnAndWait(
+            command,
+            { protocols: [AdbSubprocessNoneProtocol] }
+        );
+        return stdout;
+    }
+}

package/src/commands/subprocess/protocols/index.ts

@@ -0,0 +1,3 @@
+export * from './none.js';
+export * from './shell.js';
+export * from './types.js';

package/src/commands/subprocess/protocols/none.ts

@@ -0,0 +1,68 @@
+import type { Adb } from "../../../adb.js";
+import type { AdbSocket } from "../../../socket/index.js";
+import { DuplexStreamFactory, type ReadableStream } from "../../../stream/index.js";
+import type { AdbSubprocessProtocol } from "./types.js";
+
+/**
+ * The legacy shell
+ *
+ * Features:
+ * * `stderr`: No
+ * * `exit` exit code: No
+ * * `resize`: No
+ */
+export class AdbSubprocessNoneProtocol implements AdbSubprocessProtocol {
+    public static isSupported() { return true; }
+
+    public static async pty(adb: Adb, command: string) {
+        return new AdbSubprocessNoneProtocol(await adb.createSocket(`shell:${command}`));
+    }
+
+    public static async raw(adb: Adb, command: string) {
+        // Native ADB client doesn't allow none protocol + raw mode,
+        // But ADB daemon supports it.
+        return new AdbSubprocessNoneProtocol(await adb.createSocket(`shell,raw:${command}`));
+    }
+
+    private readonly socket: AdbSocket;
+
+    // Legacy shell forwards all data to stdin.
+    public get stdin() { return this.socket.writable; }
+
+    private _stdout: ReadableStream<Uint8Array>;
+    /**
+     * Legacy shell mixes stdout and stderr.
+     */
+    public get stdout() { return this._stdout; }
+
+    private _stderr: ReadableStream<Uint8Array>;
+    /**
+     * `stderr` will always be empty.
+     */
+    public get stderr() { return this._stderr; }
+
+    private _exit: Promise<number>;
+    public get exit() { return this._exit; }
+
+    public constructor(socket: AdbSocket) {
+        this.socket = socket;
+
+        const factory = new DuplexStreamFactory<Uint8Array, Uint8Array>({
+            close: async () => {
+                await this.socket.close();
+            },
+        });
+
+        this._stdout = factory.createWrapReadable(this.socket.readable);
+        this._stderr = factory.createReadable();
+        this._exit = factory.closed.then(() => 0);
+    }
+
+    public resize() {
+        // Not supported
+    }
+
+    public kill() {
+        return this.socket.close();
+    }
+}

package/src/commands/subprocess/protocols/shell.ts

@@ -0,0 +1,190 @@
+import { PromiseResolver } from "@yume-chan/async";
+import Struct, { placeholder, type StructValueType } from "@yume-chan/struct";
+import type { Adb } from "../../../adb.js";
+import { AdbFeatures } from "../../../features.js";
+import type { AdbSocket } from "../../../socket/index.js";
+import { pipeFrom, PushReadableStream, ReadableStream, StructDeserializeStream, StructSerializeStream, TransformStream, WritableStream, WritableStreamDefaultWriter, type PushReadableStreamController } from "../../../stream/index.js";
+import { encodeUtf8 } from "../../../utils/index.js";
+import type { AdbSubprocessProtocol } from "./types.js";
+
+export enum AdbShellProtocolId {
+    Stdin,
+    Stdout,
+    Stderr,
+    Exit,
+    CloseStdin,
+    WindowSizeChange,
+}
+
+// This packet format is used in both direction.
+const AdbShellProtocolPacket =
+    new Struct({ littleEndian: true })
+        .uint8('id', placeholder<AdbShellProtocolId>())
+        .uint32('length')
+        .uint8Array('data', { lengthField: 'length' });
+
+type AdbShellProtocolPacketInit = typeof AdbShellProtocolPacket['TInit'];
+
+type AdbShellProtocolPacket = StructValueType<typeof AdbShellProtocolPacket>;
+
+class StdinSerializeStream extends TransformStream<Uint8Array, AdbShellProtocolPacketInit>{
+    constructor() {
+        super({
+            transform(chunk, controller) {
+                controller.enqueue({
+                    id: AdbShellProtocolId.Stdin,
+                    data: chunk,
+                });
+            },
+            flush() {
+                // TODO: AdbShellSubprocessProtocol: support closing stdin
+            }
+        });
+    }
+}
+
+class StdoutDeserializeStream extends TransformStream<AdbShellProtocolPacket, Uint8Array>{
+    constructor(type: AdbShellProtocolId.Stdout | AdbShellProtocolId.Stderr) {
+        super({
+            transform(chunk, controller) {
+                if (chunk.id === type) {
+                    controller.enqueue(chunk.data);
+                }
+            },
+        });
+    }
+}
+
+class MultiplexStream<T>{
+    private _readable: PushReadableStream<T>;
+    private _readableController!: PushReadableStreamController<T>;
+    public get readable() { return this._readable; }
+
+    private _activeCount = 0;
+
+    constructor() {
+        this._readable = new PushReadableStream(controller => {
+            this._readableController = controller;
+        });
+    }
+
+    public createWriteable() {
+        return new WritableStream<T>({
+            start: () => {
+                this._activeCount += 1;
+            },
+            write: async (chunk) => {
+                await this._readableController.enqueue(chunk);
+            },
+            abort: async (e) => {
+                this._activeCount -= 1;
+                if (this._activeCount === 0) {
+                    this._readableController.close();
+                }
+            },
+            close: async () => {
+                this._activeCount -= 1;
+                if (this._activeCount === 0) {
+                    this._readableController.close();
+                }
+            },
+        });
+    }
+}
+
+/**
+ * Shell v2 a.k.a Shell Protocol
+ *
+ * Features:
+ * * `stderr`: Yes
+ * * `exit` exit code: Yes
+ * * `resize`: Yes
+ */
+export class AdbSubprocessShellProtocol implements AdbSubprocessProtocol {
+    public static isSupported(adb: Adb) {
+        return adb.features!.includes(AdbFeatures.ShellV2);
+    }
+
+    public static async pty(adb: Adb, command: string) {
+        // TODO: AdbShellSubprocessProtocol: Support setting `XTERM` environment variable
+        return new AdbSubprocessShellProtocol(await adb.createSocket(`shell,v2,pty:${command}`));
+    }
+
+    public static async raw(adb: Adb, command: string) {
+        return new AdbSubprocessShellProtocol(await adb.createSocket(`shell,v2,raw:${command}`));
+    }
+
+    private readonly _socket: AdbSocket;
+    private _socketWriter: WritableStreamDefaultWriter<AdbShellProtocolPacketInit>;
+
+    private _stdin: WritableStream<Uint8Array>;
+    public get stdin() { return this._stdin; }
+
+    private _stdout: ReadableStream<Uint8Array>;
+    public get stdout() { return this._stdout; }
+
+    private _stderr: ReadableStream<Uint8Array>;
+    public get stderr() { return this._stderr; }
+
+    private readonly _exit = new PromiseResolver<number>();
+    public get exit() { return this._exit.promise; }
+
+    public constructor(socket: AdbSocket) {
+        this._socket = socket;
+
+        // Check this image to help you understand the stream graph
+        // cspell: disable-next-line
+        // https://www.plantuml.com/plantuml/png/bL91QiCm4Bpx5SAdv90lb1JISmiw5XzaQKf5PIkiLZIqzEyLSg8ks13gYtOykpFhiOw93N6UGjVDqK7rZsxKqNw0U_NTgVAy4empOy2mm4_olC0VEVEE47GUpnGjKdgXoD76q4GIEpyFhOwP_m28hW0NNzxNUig1_JdW0bA7muFIJDco1daJ_1SAX9bgvoPJPyIkSekhNYctvIGXrCH6tIsPL5fs-s6J5yc9BpWXhKtNdF2LgVYPGM_6GlMwfhWUsIt4lbScANrwlgVVUifPSVi__t44qStnwPvZwobdSmHHlL57p2vFuHS0
+
+        // TODO: AdbShellSubprocessProtocol: Optimize stream graph
+
+        const [stdout, stderr] = socket.readable
+            .pipeThrough(new StructDeserializeStream(AdbShellProtocolPacket))
+            .pipeThrough(new TransformStream<AdbShellProtocolPacket, AdbShellProtocolPacket>({
+                transform: (chunk, controller) => {
+                    if (chunk.id === AdbShellProtocolId.Exit) {
+                        this._exit.resolve(new Uint8Array(chunk.data)[0]!);
+                        // We can let `StdoutDeserializeStream` to process `AdbShellProtocolId.Exit`,
+                        // but since we need this `TransformStream` to capture the exit code anyway,
+                        // terminating child streams here is killing two birds with one stone.
+                        controller.terminate();
+                        return;
+                    }
+                    controller.enqueue(chunk);
+                }
+            }))
+            .tee();
+        this._stdout = stdout
+            .pipeThrough(new StdoutDeserializeStream(AdbShellProtocolId.Stdout));
+        this._stderr = stderr
+            .pipeThrough(new StdoutDeserializeStream(AdbShellProtocolId.Stderr));
+
+        const multiplexer = new MultiplexStream<AdbShellProtocolPacketInit>();
+        multiplexer.readable
+            .pipeThrough(new StructSerializeStream(AdbShellProtocolPacket))
+            .pipeTo(socket.writable);
+
+        this._stdin = pipeFrom(
+            multiplexer.createWriteable(),
+            new StdinSerializeStream()
+        );
+
+        this._socketWriter = multiplexer.createWriteable().getWriter();
+    }
+
+    public async resize(rows: number, cols: number) {
+        await this._socketWriter.write({
+            id: AdbShellProtocolId.WindowSizeChange,
+            data: encodeUtf8(
+                // The "correct" format is `${rows}x${cols},${x_pixels}x${y_pixels}`
+                // However, according to https://linux.die.net/man/4/tty_ioctl
+                // `x_pixels` and `y_pixels` are not used, so always passing `0` is fine.
+                `${rows}x${cols},0x0\0`
+            ),
+        });
+    }
+
+    public kill() {
+        return this._socket.close();
+    }
+}

package/src/commands/subprocess/protocols/types.ts

@@ -0,0 +1,59 @@
+import type { ValueOrPromise } from "@yume-chan/struct";
+import type { Adb } from "../../../adb.js";
+import type { AdbSocket } from "../../../socket/index.js";
+import type { ReadableStream, WritableStream } from "../../../stream/index.js";
+
+export interface AdbSubprocessProtocol {
+    /**
+     * A WritableStream that writes to the `stdin` pipe.
+     */
+    readonly stdin: WritableStream<Uint8Array>;
+
+    /**
+     * The `stdout` pipe of the process.
+     */
+    readonly stdout: ReadableStream<Uint8Array>;
+
+    /**
+     * The `stderr` pipe of the process.
+     *
+     * Note: Some `AdbSubprocessProtocol` doesn't separate `stdout` and `stderr`,
+     * All output will be sent to `stdout`.
+     */
+    readonly stderr: ReadableStream<Uint8Array>;
+
+    /**
+     * A `Promise` that resolves to the exit code of the process.
+     *
+     * Note: Some `AdbSubprocessProtocol` doesn't support exit code,
+     * They will always resolve it with `0`.
+     */
+    readonly exit: Promise<number>;
+
+    /**
+     * Resizes the current shell.
+     *
+     * Some `AdbSubprocessProtocol`s may not support resizing
+     * and will ignore calls to this method.
+     */
+    resize(rows: number, cols: number): ValueOrPromise<void>;
+
+    /**
+     * Kills the current process.
+     */
+    kill(): ValueOrPromise<void>;
+}
+
+export interface AdbSubprocessProtocolConstructor {
+    /** Returns `true` if the `adb` instance supports this shell */
+    isSupported(adb: Adb): ValueOrPromise<boolean>;
+
+    /** Spawns an executable in PTY (interactive) mode. */
+    pty(adb: Adb, command: string): ValueOrPromise<AdbSubprocessProtocol>;
+
+    /** Spawns an executable and pipe the output. */
+    raw(adb: Adb, command: string): ValueOrPromise<AdbSubprocessProtocol>;
+
+    /** Creates a new `AdbShell` by attaching to an exist `AdbSocket` */
+    new(socket: AdbSocket): AdbSubprocessProtocol;
+}

package/src/commands/sync/index.ts

@@ -1,7 +1,7 @@
-export * from './list';
-export * from './pull';
-export * from './request';
-export * from './response';
-export * from './push';
-export * from './stat';
-export * from './sync';
+export * from './list.js';
+export * from './pull.js';
+export * from './request.js';
+export * from './response.js';
+export * from './push.js';
+export * from './stat.js';
+export * from './sync.js';