@yume-chan/adb 1.1.0 → 2.0.0

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

@@ -0,0 +1,42 @@
+import type { Adb } from "../../../adb.js";
+
+import { AdbNoneProtocolProcessImpl } from "./process.js";
+import { AdbNoneProtocolPtyProcess } from "./pty.js";
+import { AdbNoneProtocolSpawner } from "./spawner.js";
+
+export class AdbNoneProtocolSubprocessService extends AdbNoneProtocolSpawner {
+    readonly #adb: Adb;
+    get adb(): Adb {
+        return this.#adb;
+    }
+
+    constructor(adb: Adb) {
+        super(async (command, signal) => {
+            // `shell,raw:${command}` also triggers raw mode,
+            // But is not supported on Android version <7.
+            const socket = await this.#adb.createSocket(
+                `exec:${command.join(" ")}`,
+            );
+
+            if (signal?.aborted) {
+                await socket.close();
+                throw signal.reason;
+            }
+
+            return new AdbNoneProtocolProcessImpl(socket, signal);
+        });
+        this.#adb = adb;
+    }
+
+    async pty(command?: string | string[]): Promise<AdbNoneProtocolPtyProcess> {
+        if (command === undefined) {
+            command = "";
+        } else if (Array.isArray(command)) {
+            command = command.join(" ");
+        }
+
+        return new AdbNoneProtocolPtyProcess(
+            await this.#adb.createSocket(`shell:${command}`),
+        );
+    }
+}

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

@@ -0,0 +1,68 @@
+import type { MaybePromiseLike } from "@yume-chan/async";
+import type {
+    AbortSignal,
+    MaybeConsumable,
+    ReadableStream,
+    WritableStream,
+} from "@yume-chan/stream-extra";
+import {
+    ConcatBufferStream,
+    ConcatStringStream,
+    TextDecoderStream,
+} from "@yume-chan/stream-extra";
+
+import { splitCommand } from "../utils.js";
+
+export interface AdbNoneProtocolProcess {
+    get stdin(): WritableStream<MaybeConsumable<Uint8Array>>;
+
+    /**
+     * Mix of stdout and stderr
+     */
+    get output(): ReadableStream<Uint8Array>;
+
+    get exited(): Promise<void>;
+
+    kill(): MaybePromiseLike<void>;
+}
+
+export class AdbNoneProtocolSpawner {
+    readonly #spawn: (
+        command: string[],
+        signal: AbortSignal | undefined,
+    ) => Promise<AdbNoneProtocolProcess>;
+
+    constructor(
+        spawn: (
+            command: string[],
+            signal: AbortSignal | undefined,
+        ) => Promise<AdbNoneProtocolProcess>,
+    ) {
+        this.#spawn = spawn;
+    }
+
+    spawn(
+        command: string | string[],
+        signal?: AbortSignal,
+    ): Promise<AdbNoneProtocolProcess> {
+        signal?.throwIfAborted();
+
+        if (typeof command === "string") {
+            command = splitCommand(command);
+        }
+
+        return this.#spawn(command, signal);
+    }
+
+    async spawnWait(command: string | string[]): Promise<Uint8Array> {
+        const process = await this.spawn(command);
+        return await process.output.pipeThrough(new ConcatBufferStream());
+    }
+
+    async spawnWaitText(command: string | string[]): Promise<string> {
+        const process = await this.spawn(command);
+        return await process.output
+            .pipeThrough(new TextDecoderStream())
+            .pipeThrough(new ConcatStringStream());
+    }
+}

package/src/commands/subprocess/pty.ts

@@ -0,0 +1,15 @@
+import type { MaybePromiseLike } from "@yume-chan/async";
+import type {
+    MaybeConsumable,
+    ReadableStream,
+    WritableStream,
+} from "@yume-chan/stream-extra";
+
+export interface AdbPtyProcess<TExitCode> {
+    get input(): WritableStream<MaybeConsumable<Uint8Array>>;
+    get output(): ReadableStream<Uint8Array>;
+    get exited(): Promise<TExitCode>;
+
+    sigint(): Promise<void>;
+    kill(): MaybePromiseLike<void>;
+}

package/src/commands/subprocess/service.ts

@@ -0,0 +1,32 @@
+import type { Adb } from "../../adb.js";
+import { AdbFeature } from "../../features.js";
+
+import { AdbNoneProtocolSubprocessService } from "./none/index.js";
+import { AdbShellProtocolSubprocessService } from "./shell/index.js";
+
+export class AdbSubprocessService {
+    readonly #adb: Adb;
+    get adb() {
+        return this.#adb;
+    }
+
+    readonly #noneProtocol: AdbNoneProtocolSubprocessService;
+    get noneProtocol(): AdbNoneProtocolSubprocessService {
+        return this.#noneProtocol;
+    }
+
+    readonly #shellProtocol?: AdbShellProtocolSubprocessService;
+    get shellProtocol(): AdbShellProtocolSubprocessService | undefined {
+        return this.#shellProtocol;
+    }
+
+    constructor(adb: Adb) {
+        this.#adb = adb;
+
+        this.#noneProtocol = new AdbNoneProtocolSubprocessService(adb);
+
+        if (adb.canUseFeature(AdbFeature.ShellV2)) {
+            this.#shellProtocol = new AdbShellProtocolSubprocessService(adb);
+        }
+    }
+}

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

@@ -0,0 +1,5 @@
+export * from "./process.js";
+export * from "./pty.js";
+export * from "./service.js";
+export * from "./shared.js";
+export * from "./spawner.js";

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

@@ -0,0 +1,127 @@
+import type { MaybePromiseLike } from "@yume-chan/async";
+import { PromiseResolver } from "@yume-chan/async";
+import type {
+    AbortSignal,
+    PushReadableStreamController,
+    ReadableStream,
+    WritableStreamDefaultWriter,
+} from "@yume-chan/stream-extra";
+import {
+    MaybeConsumable,
+    PushReadableStream,
+    StructDeserializeStream,
+    WritableStream,
+} from "@yume-chan/stream-extra";
+
+import type { AdbSocket } from "../../../adb.js";
+
+import { AdbShellProtocolId, AdbShellProtocolPacket } from "./shared.js";
+import type { AdbShellProtocolProcess } from "./spawner.js";
+
+export class AdbShellProtocolProcessImpl implements AdbShellProtocolProcess {
+    readonly #socket: AdbSocket;
+    readonly #writer: WritableStreamDefaultWriter<MaybeConsumable<Uint8Array>>;
+
+    readonly #stdin: WritableStream<MaybeConsumable<Uint8Array>>;
+    get stdin() {
+        return this.#stdin;
+    }
+
+    readonly #stdout: ReadableStream<Uint8Array>;
+    get stdout() {
+        return this.#stdout;
+    }
+
+    readonly #stderr: ReadableStream<Uint8Array>;
+    get stderr() {
+        return this.#stderr;
+    }
+
+    readonly #exited: Promise<number>;
+    get exited() {
+        return this.#exited;
+    }
+
+    constructor(socket: AdbSocket, signal?: AbortSignal) {
+        this.#socket = socket;
+
+        let stdoutController!: PushReadableStreamController<Uint8Array>;
+        let stderrController!: PushReadableStreamController<Uint8Array>;
+        this.#stdout = new PushReadableStream<Uint8Array>((controller) => {
+            stdoutController = controller;
+        });
+        this.#stderr = new PushReadableStream<Uint8Array>((controller) => {
+            stderrController = controller;
+        });
+
+        const exited = new PromiseResolver<number>();
+        this.#exited = exited.promise;
+
+        socket.readable
+            .pipeThrough(new StructDeserializeStream(AdbShellProtocolPacket))
+            .pipeTo(
+                new WritableStream<AdbShellProtocolPacket>({
+                    write: async (chunk) => {
+                        switch (chunk.id) {
+                            case AdbShellProtocolId.Exit:
+                                exited.resolve(chunk.data[0]!);
+                                break;
+                            case AdbShellProtocolId.Stdout:
+                                await stdoutController.enqueue(chunk.data);
+                                break;
+                            case AdbShellProtocolId.Stderr:
+                                await stderrController.enqueue(chunk.data);
+                                break;
+                            default:
+                                // Ignore unknown messages like Google ADB does
+                                // https://cs.android.com/android/platform/superproject/main/+/main:packages/modules/adb/daemon/shell_service.cpp;l=684;drc=61197364367c9e404c7da6900658f1b16c42d0da
+                                break;
+                        }
+                    },
+                }),
+            )
+            .then(
+                () => {
+                    stdoutController.close();
+                    stderrController.close();
+                    // If `exited` has already settled, this will be a no-op
+                    exited.reject(
+                        new Error("Socket ended without exit message"),
+                    );
+                },
+                (e) => {
+                    stdoutController.error(e);
+                    stderrController.error(e);
+                    // If `exited` has already settled, this will be a no-op
+                    exited.reject(e);
+                },
+            );
+
+        if (signal) {
+            // `signal` won't affect `this.stdout` and `this.stderr`
+            // So remaining data can still be read
+            // (call `controller.error` will discard all pending data)
+
+            signal.addEventListener("abort", () => {
+                exited.reject(signal.reason);
+                this.#socket.close();
+            });
+        }
+
+        this.#writer = this.#socket.writable.getWriter();
+        this.#stdin = new MaybeConsumable.WritableStream<Uint8Array>({
+            write: async (chunk) => {
+                await this.#writer.write(
+                    AdbShellProtocolPacket.serialize({
+                        id: AdbShellProtocolId.Stdin,
+                        data: chunk,
+                    }),
+                );
+            },
+        });
+    }
+
+    kill(): MaybePromiseLike<void> {
+        return this.#socket.close();
+    }
+}

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

@@ -0,0 +1,112 @@
+import { PromiseResolver } from "@yume-chan/async";
+import type {
+    PushReadableStreamController,
+    ReadableStream,
+    WritableStreamDefaultWriter,
+} from "@yume-chan/stream-extra";
+import {
+    MaybeConsumable,
+    PushReadableStream,
+    StructDeserializeStream,
+    WritableStream,
+} from "@yume-chan/stream-extra";
+import { encodeUtf8 } from "@yume-chan/struct";
+
+import type { AdbSocket } from "../../../adb.js";
+import type { AdbPtyProcess } from "../pty.js";
+
+import { AdbShellProtocolId, AdbShellProtocolPacket } from "./shared.js";
+
+export class AdbShellProtocolPtyProcess implements AdbPtyProcess<number> {
+    readonly #socket: AdbSocket;
+    readonly #writer: WritableStreamDefaultWriter<MaybeConsumable<Uint8Array>>;
+
+    readonly #input: WritableStream<MaybeConsumable<Uint8Array>>;
+    get input() {
+        return this.#input;
+    }
+
+    readonly #stdout: ReadableStream<Uint8Array>;
+    get output() {
+        return this.#stdout;
+    }
+
+    readonly #exited = new PromiseResolver<number>();
+    get exited() {
+        return this.#exited.promise;
+    }
+
+    constructor(socket: AdbSocket) {
+        this.#socket = socket;
+
+        let stdoutController!: PushReadableStreamController<Uint8Array>;
+        this.#stdout = new PushReadableStream<Uint8Array>((controller) => {
+            stdoutController = controller;
+        });
+
+        socket.readable
+            .pipeThrough(new StructDeserializeStream(AdbShellProtocolPacket))
+            .pipeTo(
+                new WritableStream<AdbShellProtocolPacket>({
+                    write: async (chunk) => {
+                        switch (chunk.id) {
+                            case AdbShellProtocolId.Exit:
+                                this.#exited.resolve(chunk.data[0]!);
+                                break;
+                            case AdbShellProtocolId.Stdout:
+                                await stdoutController.enqueue(chunk.data);
+                                break;
+                        }
+                    },
+                }),
+            )
+            .then(
+                () => {
+                    stdoutController.close();
+                    // If `#exit` has already resolved, this will be a no-op
+                    this.#exited.reject(
+                        new Error("Socket ended without exit message"),
+                    );
+                },
+                (e) => {
+                    stdoutController.error(e);
+                    // If `#exit` has already resolved, this will be a no-op
+                    this.#exited.reject(e);
+                },
+            );
+
+        this.#writer = this.#socket.writable.getWriter();
+        this.#input = new MaybeConsumable.WritableStream<Uint8Array>({
+            write: (chunk) => this.#writeStdin(chunk),
+        });
+    }
+
+    #writeStdin(chunk: Uint8Array) {
+        return this.#writer.write(
+            AdbShellProtocolPacket.serialize({
+                id: AdbShellProtocolId.Stdin,
+                data: chunk,
+            }),
+        );
+    }
+
+    async resize(rows: number, cols: number) {
+        await this.#writer.write(
+            AdbShellProtocolPacket.serialize({
+                id: AdbShellProtocolId.WindowSizeChange,
+                // 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 unused, so always sending `0` should be fine.
+                data: encodeUtf8(`${rows}x${cols},0x0\0`),
+            }),
+        );
+    }
+
+    sigint() {
+        return this.#writeStdin(new Uint8Array([0x03]));
+    }
+
+    kill() {
+        return this.#socket.close();
+    }
+}

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

@@ -0,0 +1,58 @@
+import type { Adb } from "../../../adb.js";
+import { AdbFeature } from "../../../features.js";
+
+import { AdbShellProtocolProcessImpl } from "./process.js";
+import { AdbShellProtocolPtyProcess } from "./pty.js";
+import { AdbShellProtocolSpawner } from "./spawner.js";
+
+export class AdbShellProtocolSubprocessService extends AdbShellProtocolSpawner {
+    readonly #adb: Adb;
+    get adb() {
+        return this.#adb;
+    }
+
+    get isSupported() {
+        return this.#adb.canUseFeature(AdbFeature.ShellV2);
+    }
+
+    constructor(adb: Adb) {
+        super(async (command, signal) => {
+            const socket = await this.#adb.createSocket(
+                `shell,v2,raw:${command.join(" ")}`,
+            );
+
+            if (signal?.aborted) {
+                await socket.close();
+                throw signal.reason;
+            }
+
+            return new AdbShellProtocolProcessImpl(socket, signal);
+        });
+        this.#adb = adb;
+    }
+
+    async pty(options?: {
+        command?: string | string[] | undefined;
+        terminalType?: string;
+    }): Promise<AdbShellProtocolPtyProcess> {
+        let service = "shell,v2,pty";
+
+        if (options?.terminalType) {
+            service += `,TERM=` + options.terminalType;
+        }
+
+        service += ":";
+
+        if (options) {
+            if (typeof options.command === "string") {
+                service += options.command;
+            } else if (Array.isArray(options.command)) {
+                service += options.command.join(" ");
+            }
+        }
+
+        return new AdbShellProtocolPtyProcess(
+            await this.#adb.createSocket(service),
+        );
+    }
+}

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

@@ -0,0 +1,25 @@
+import type { StructValue } from "@yume-chan/struct";
+import { buffer, struct, u32, u8 } from "@yume-chan/struct";
+
+export const AdbShellProtocolId = {
+    Stdin: 0,
+    Stdout: 1,
+    Stderr: 2,
+    Exit: 3,
+    CloseStdin: 4,
+    WindowSizeChange: 5,
+} as const;
+
+export type AdbShellProtocolId =
+    (typeof AdbShellProtocolId)[keyof typeof AdbShellProtocolId];
+
+// This packet format is used in both directions.
+export const AdbShellProtocolPacket = struct(
+    {
+        id: u8<AdbShellProtocolId>(),
+        data: buffer(u32),
+    },
+    { littleEndian: true },
+);
+
+export type AdbShellProtocolPacket = StructValue<typeof AdbShellProtocolPacket>;

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

@@ -0,0 +1,90 @@
+import type { MaybePromiseLike } from "@yume-chan/async";
+import type {
+    AbortSignal,
+    MaybeConsumable,
+    ReadableStream,
+    WritableStream,
+} from "@yume-chan/stream-extra";
+import {
+    ConcatBufferStream,
+    ConcatStringStream,
+    TextDecoderStream,
+} from "@yume-chan/stream-extra";
+
+import { splitCommand } from "../utils.js";
+
+export interface AdbShellProtocolProcess {
+    get stdin(): WritableStream<MaybeConsumable<Uint8Array>>;
+
+    get stdout(): ReadableStream<Uint8Array>;
+    get stderr(): ReadableStream<Uint8Array>;
+
+    get exited(): Promise<number>;
+
+    kill(): MaybePromiseLike<void>;
+}
+
+export class AdbShellProtocolSpawner {
+    readonly #spawn: (
+        command: string[],
+        signal: AbortSignal | undefined,
+    ) => Promise<AdbShellProtocolProcess>;
+
+    constructor(
+        spawn: (
+            command: string[],
+            signal: AbortSignal | undefined,
+        ) => Promise<AdbShellProtocolProcess>,
+    ) {
+        this.#spawn = spawn;
+    }
+
+    spawn(
+        command: string | string[],
+        signal?: AbortSignal,
+    ): Promise<AdbShellProtocolProcess> {
+        signal?.throwIfAborted();
+
+        if (typeof command === "string") {
+            command = splitCommand(command);
+        }
+
+        return this.#spawn(command, signal);
+    }
+
+    async spawnWait(
+        command: string | string[],
+    ): Promise<AdbShellProtocolSpawner.WaitResult<Uint8Array>> {
+        const process = await this.spawn(command);
+        const [stdout, stderr, exitCode] = await Promise.all([
+            process.stdout.pipeThrough(new ConcatBufferStream()),
+            process.stderr.pipeThrough(new ConcatBufferStream()),
+            process.exited,
+        ]);
+        return { stdout, stderr, exitCode };
+    }
+
+    async spawnWaitText(
+        command: string | string[],
+    ): Promise<AdbShellProtocolSpawner.WaitResult<string>> {
+        const process = await this.spawn(command);
+        const [stdout, stderr, exitCode] = await Promise.all([
+            process.stdout
+                .pipeThrough(new TextDecoderStream())
+                .pipeThrough(new ConcatStringStream()),
+            process.stderr
+                .pipeThrough(new TextDecoderStream())
+                .pipeThrough(new ConcatStringStream()),
+            process.exited,
+        ]);
+        return { stdout, stderr, exitCode };
+    }
+}
+
+export namespace AdbShellProtocolSpawner {
+    export interface WaitResult<T> {
+        stdout: T;
+        stderr: T;
+        exitCode: number;
+    }
+}

package/src/commands/subprocess/utils.ts

@@ -18,3 +18,44 @@ export function escapeArg(s: string) {
     result += `'`;
     return result;
 }
+
+export function splitCommand(command: string): string[] {
+    const result: string[] = [];
+    let quote: string | undefined;
+    let isEscaped = false;
+    let start = 0;
+
+    for (let i = 0, len = command.length; i < len; i += 1) {
+        if (isEscaped) {
+            isEscaped = false;
+            continue;
+        }
+
+        const char = command.charAt(i);
+        switch (char) {
+            case " ":
+                if (!quote && i !== start) {
+                    result.push(command.substring(start, i));
+                    start = i + 1;
+                }
+                break;
+            case "'":
+            case '"':
+                if (!quote) {
+                    quote = char;
+                } else if (char === quote) {
+                    quote = undefined;
+                }
+                break;
+            case "\\":
+                isEscaped = true;
+                break;
+        }
+    }
+
+    if (start < command.length) {
+        result.push(command.substring(start));
+    }
+
+    return result;
+}

package/src/commands/sync/list.ts

@@ -1,5 +1,5 @@
 import type { StructValue } from "@yume-chan/struct";
-import { string, struct, u32 } from "@yume-chan/struct";
+import { extend, string, u32 } from "@yume-chan/struct";
 
 import { AdbSyncRequestId, adbSyncWriteRequest } from "./request.js";
 import { AdbSyncResponseId, adbSyncReadResponses } from "./response.js";
@@ -15,25 +15,15 @@ export interface AdbSyncEntry extends AdbSyncStat {
     name: string;
 }
 
-export const AdbSyncEntryResponse = /* #__PURE__ */ (() =>
-    struct(
-        {
-            ...AdbSyncLstatResponse.fields,
-            name: string(u32),
-        },
-        { littleEndian: true, extra: AdbSyncLstatResponse.extra },
-    ))();
+export const AdbSyncEntryResponse = extend(AdbSyncLstatResponse, {
+    name: string(u32),
+});
 
 export type AdbSyncEntryResponse = StructValue<typeof AdbSyncEntryResponse>;
 
-export const AdbSyncEntry2Response = /* #__PURE__ */ (() =>
-    struct(
-        {
-            ...AdbSyncStatResponse.fields,
-            name: string(u32),
-        },
-        { littleEndian: true, extra: AdbSyncStatResponse.extra },
-    ))();
+export const AdbSyncEntry2Response = extend(AdbSyncStatResponse, {
+    name: string(u32),
+});
 
 export type AdbSyncEntry2Response = StructValue<typeof AdbSyncEntry2Response>;
 

package/src/commands/sync/pull.ts

@@ -1,5 +1,4 @@
-import type { ReadableStream } from "@yume-chan/stream-extra";
-import { PushReadableStream } from "@yume-chan/stream-extra";
+import { ReadableStream } from "@yume-chan/stream-extra";
 import type { StructValue } from "@yume-chan/struct";
 import { buffer, struct, u32 } from "@yume-chan/struct";
 
@@ -52,10 +51,5 @@ export function adbSyncPull(
     socket: AdbSyncSocket,
     path: string,
 ): ReadableStream<Uint8Array> {
-    // TODO: use `ReadableStream.from` when it's supported
-    return new PushReadableStream(async (controller) => {
-        for await (const data of adbSyncPullGenerator(socket, path)) {
-            await controller.enqueue(data);
-        }
-    });
+    return ReadableStream.from(adbSyncPullGenerator(socket, path));
 }