@yume-chan/adb 2.6.2 → 3.0.0-beta.0

package/src/{commands/reverse.ts → service/reverse/service.ts}

@@ -1,73 +1,15 @@
 // cspell: ignore killforward
 
 import { BufferedReadableStream } from "@yume-chan/stream-extra";
-import {
-    encodeUtf8,
-    ExactReadableEndedError,
-    extend,
-    string,
-    struct,
-} from "@yume-chan/struct";
-
-import type { AdbIncomingSocketHandler } from "../adb.js";
-import { hexToNumber, sequenceEqual } from "../utils/index.js";
-
-import { AdbServiceBase } from "./base.js";
-
-export interface AdbForwardListener {
-    deviceSerial: string;
-
-    localName: string;
-
-    remoteName: string;
-}
+import { encodeUtf8, ExactReadableEndedError } from "@yume-chan/struct";
 
-const AdbReverseStringResponse = struct(
-    {
-        length: string(4),
-        content: string({
-            field: "length",
-            convert(value: string) {
-                return Number.parseInt(value, 16);
-            },
-            back(value) {
-                return value.toString(16).padStart(4, "0");
-            },
-        }),
-    },
-    { littleEndian: true },
-);
-
-export class AdbReverseError extends Error {
-    constructor(message: string) {
-        super(message);
-    }
-}
+import type { Adb } from "../../adb.js";
+import { hexToNumber, sequenceEqual } from "../../utils/index.js";
 
-export class AdbReverseNotSupportedError extends AdbReverseError {
-    constructor() {
-        super(
-            "ADB reverse tunnel is not supported on this device when connected wirelessly.",
-        );
-    }
-}
-
-export const AdbReverseErrorResponse = extend(
+import {
+    AdbReverseErrorResponse,
     AdbReverseStringResponse,
-    {},
-    {
-        postDeserialize(value) {
-            // https://issuetracker.google.com/issues/37066218
-            // ADB on Android <9 can't create reverse tunnels when connected wirelessly (ADB over Wi-Fi),
-            // and returns this confusing "more than one device/emulator" error.
-            if (value.content === "more than one device/emulator") {
-                throw new AdbReverseNotSupportedError();
-            } else {
-                throw new AdbReverseError(value.content);
-            }
-        },
-    },
-);
+} from "./response.js";
 
 // Like `hexToNumber`, it's much faster than first converting `buffer` to a string
 function decimalToNumber(buffer: Uint8Array) {
@@ -84,11 +26,21 @@ function decimalToNumber(buffer: Uint8Array) {
 
 const OKAY = encodeUtf8("OKAY");
 
-export class AdbReverseService extends AdbServiceBase {
+export class AdbReverseService {
+    static readonly StringResponse = AdbReverseStringResponse;
+
+    static readonly ErrorResponse = AdbReverseErrorResponse;
+
+    readonly #adb: Adb;
+
+    constructor(adb: Adb) {
+        this.#adb = adb;
+    }
+
     readonly #deviceAddressToLocalAddress = new Map<string, string>();
 
     protected async createBufferedStream(service: string) {
-        const socket = await this.adb.createSocket(service);
+        const socket = await this.#adb.createSocket(service);
         return new BufferedReadableStream(socket.readable);
     }
 
@@ -106,7 +58,7 @@ export class AdbReverseService extends AdbServiceBase {
     /**
      * Get a list of all reverse port forwarding on the device.
      */
-    async list(): Promise<AdbForwardListener[]> {
+    async list(): Promise<AdbReverseService.Listener[]> {
         const stream = await this.createBufferedStream("reverse:list-forward");
 
         const response = await AdbReverseStringResponse.deserialize(stream);
@@ -161,10 +113,10 @@ export class AdbReverseService extends AdbServiceBase {
      */
     async add(
         deviceAddress: string,
-        handler: AdbIncomingSocketHandler,
+        handler: Adb.IncomingSocketHandler,
         localAddress?: string,
     ): Promise<string> {
-        localAddress = await this.adb.transport.addReverseTunnel(
+        localAddress = await this.#adb.transport.addReverseTunnel(
             handler,
             localAddress,
         );
@@ -174,7 +126,7 @@ export class AdbReverseService extends AdbServiceBase {
             this.#deviceAddressToLocalAddress.set(deviceAddress, localAddress);
             return deviceAddress;
         } catch (e) {
-            await this.adb.transport.removeReverseTunnel(localAddress);
+            await this.#adb.transport.removeReverseTunnel(localAddress);
             throw e;
         }
     }
@@ -186,7 +138,7 @@ export class AdbReverseService extends AdbServiceBase {
         const localAddress =
             this.#deviceAddressToLocalAddress.get(deviceAddress);
         if (localAddress) {
-            await this.adb.transport.removeReverseTunnel(localAddress);
+            await this.#adb.transport.removeReverseTunnel(localAddress);
         }
 
         await this.sendRequest(`reverse:killforward:${deviceAddress}`);
@@ -198,7 +150,7 @@ export class AdbReverseService extends AdbServiceBase {
      * Remove all reverse port forwarding, including the ones added by other programs.
      */
     async removeAll(): Promise<void> {
-        await this.adb.transport.clearReverseTunnels();
+        await this.#adb.transport.clearReverseTunnels();
         this.#deviceAddressToLocalAddress.clear();
 
         await this.sendRequest(`reverse:killforward-all`);
@@ -206,3 +158,11 @@ export class AdbReverseService extends AdbServiceBase {
         // No need to close the stream, device will close it
     }
 }
+
+export namespace AdbReverseService {
+    export interface Listener {
+        deviceSerial: string;
+        localName: string;
+        remoteName: string;
+    }
+}

package/src/{commands → service}/subprocess/index.ts

@@ -1,4 +1,5 @@
 export * from "./none/index.js";
 export * from "./service.js";
 export * from "./shell/index.js";
+export * from "./types.js";
 export * from "./utils.js";

package/src/{commands → service}/subprocess/none/process.ts

@@ -7,12 +7,12 @@ import type {
     WritableStream,
 } from "@yume-chan/stream-extra";
 
-import type { AdbSocket } from "../../../adb.js";
+import type { Adb } from "../../../adb.js";
 
 import type { AdbNoneProtocolProcess } from "./spawner.js";
 
 export class AdbNoneProtocolProcessImpl implements AdbNoneProtocolProcess {
-    readonly #socket: AdbSocket;
+    readonly #socket: Adb.Socket;
 
     get stdin(): WritableStream<MaybeConsumable<Uint8Array>> {
         return this.#socket.writable;
@@ -27,7 +27,7 @@ export class AdbNoneProtocolProcessImpl implements AdbNoneProtocolProcess {
         return this.#exited;
     }
 
-    constructor(socket: AdbSocket, signal?: AbortSignal) {
+    constructor(socket: Adb.Socket, signal?: AbortSignal) {
         this.#socket = socket;
 
         if (signal) {

package/src/{commands → service}/subprocess/none/pty.ts

@@ -6,11 +6,11 @@ import type {
 } from "@yume-chan/stream-extra";
 import { MaybeConsumable } from "@yume-chan/stream-extra";
 
-import type { AdbSocket } from "../../../adb.js";
-import type { AdbPtyProcess } from "../pty.js";
+import type { Adb } from "../../../adb.js";
+import type { AdbPty } from "../pty.js";
 
-export class AdbNoneProtocolPtyProcess implements AdbPtyProcess<undefined> {
-    readonly #socket: AdbSocket;
+export class AdbNoneProtocolPty implements AdbPty<undefined> {
+    readonly #socket: Adb.Socket;
     readonly #writer: WritableStreamDefaultWriter<MaybeConsumable<Uint8Array>>;
 
     readonly #input: MaybeConsumable.WritableStream<Uint8Array>;
@@ -26,7 +26,7 @@ export class AdbNoneProtocolPtyProcess implements AdbPtyProcess<undefined> {
         return this.#socket.closed;
     }
 
-    constructor(socket: AdbSocket) {
+    constructor(socket: Adb.Socket) {
         this.#socket = socket;
 
         this.#writer = this.#socket.writable.getWriter();

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

@@ -0,0 +1,57 @@
+import type { Adb } from "../../../adb.js";
+
+import { AdbNoneProtocolProcessImpl } from "./process.js";
+import { AdbNoneProtocolPty } from "./pty.js";
+import { adbNoneProtocolSpawner } from "./spawner.js";
+
+export class AdbNoneProtocolSubprocessService {
+    readonly #adb: Adb;
+    get adb(): Adb {
+        return this.#adb;
+    }
+
+    constructor(adb: Adb) {
+        this.#adb = adb;
+    }
+
+    spawn = adbNoneProtocolSpawner(async (command, signal) => {
+        if (!command.length) {
+            throw new Error("Command cannot be empty");
+        }
+
+        // Android 7 added `shell,raw:${command}` service which also triggers raw mode,
+        // but we want to keep backward compatibility.
+        let service = "exec:";
+
+        // Similar to SSH, we don't escape the `command`,
+        // because the command will be invoked by `sh -c`,
+        // it can contain environment variables (`KEY=value command`),
+        // and shell expansions (`echo "$KEY"` vs `echo '$KEY'`),
+        // which we can't know how to properly escape.
+        service += command.join(" ");
+
+        const socket = await this.#adb.createSocket(service);
+
+        if (signal?.aborted) {
+            await socket.close();
+            throw signal.reason;
+        }
+
+        return new AdbNoneProtocolProcessImpl(socket, signal);
+    });
+
+    async pty(
+        command?: string | readonly string[],
+    ): Promise<AdbNoneProtocolPty> {
+        let service = "shell:";
+
+        if (typeof command === "string") {
+            service += command;
+        } else if (Array.isArray(command)) {
+            // Don't escape `command`. See `spawn` above for details
+            service += command.join(" ");
+        }
+
+        return new AdbNoneProtocolPty(await this.#adb.createSocket(service));
+    }
+}

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

@@ -0,0 +1,81 @@
+import type { MaybePromiseLike } from "@yume-chan/async";
+import type {
+    AbortSignal,
+    MaybeConsumable,
+    ReadableStream,
+    WritableStream,
+} from "@yume-chan/stream-extra";
+import { concatUint8Arrays } from "@yume-chan/stream-extra";
+
+import type { AdbSubprocessSpawner } from "../types.js";
+import {
+    createLazyPromise,
+    decodeUtf8Chunked,
+    splitCommand,
+    ToArrayStream,
+} 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 type AdbNoneProtocolSpawner = (
+    command: string | readonly string[],
+    signal?: AbortSignal,
+) => Promise<AdbNoneProtocolProcess> &
+    AdbSubprocessSpawner.Wait<Uint8Array, string>;
+
+export function adbNoneProtocolSpawner(
+    spawn: (
+        command: readonly string[],
+        signal: AbortSignal | undefined,
+    ) => Promise<AdbNoneProtocolProcess>,
+): AdbNoneProtocolSpawner {
+    return (command, signal) => {
+        signal?.throwIfAborted();
+
+        if (typeof command === "string") {
+            command = splitCommand(command);
+        }
+
+        const processPromise = spawn(
+            command,
+            signal,
+        ) as Promise<AdbNoneProtocolProcess> &
+            AdbSubprocessSpawner.Wait<Uint8Array, string>;
+
+        processPromise.wait = (options) => {
+            const waitPromise = processPromise.then(async (process) => {
+                const [, output] = await Promise.all([
+                    options?.stdin?.pipeTo(process.stdin),
+                    process.output.pipeThrough(new ToArrayStream()),
+                ]);
+                return output;
+            });
+
+            return createLazyPromise(
+                async () => {
+                    const chunks = await waitPromise;
+                    return concatUint8Arrays(chunks);
+                },
+                {
+                    async toString() {
+                        const chunks = await waitPromise;
+                        return decodeUtf8Chunked(chunks);
+                    },
+                },
+            );
+        };
+
+        return processPromise;
+    };
+}

package/src/{commands → service}/subprocess/pty.ts

@@ -5,7 +5,7 @@ import type {
     WritableStream,
 } from "@yume-chan/stream-extra";
 
-export interface AdbPtyProcess<TExitCode> {
+export interface AdbPty<TExitCode> {
     get input(): WritableStream<MaybeConsumable<Uint8Array>>;
     get output(): ReadableStream<Uint8Array>;
     get exited(): Promise<TExitCode>;

package/src/{commands → service}/subprocess/service.ts

@@ -25,7 +25,7 @@ export class AdbSubprocessService {
 
         this.#noneProtocol = new AdbNoneProtocolSubprocessService(adb);
 
-        if (adb.canUseFeature(AdbFeature.ShellV2)) {
+        if (adb.canUseFeature(AdbFeature.Shell2)) {
             this.#shellProtocol = new AdbShellProtocolSubprocessService(adb);
         }
     }

package/src/{commands → service}/subprocess/shell/index.ts

@@ -1,5 +1,5 @@
 export * from "./process.js";
 export * from "./pty.js";
 export * from "./service.js";
-export * from "./shared.js";
 export * from "./spawner.js";
+// `shared.ts` is internal

package/src/{commands → service}/subprocess/shell/process.ts

@@ -14,13 +14,13 @@ import {
 } from "@yume-chan/stream-extra";
 import { EmptyUint8Array } from "@yume-chan/struct";
 
-import type { AdbSocket } from "../../../adb.js";
+import type { Adb } from "../../../adb.js";
 
 import { AdbShellProtocolId, AdbShellProtocolPacket } from "./shared.js";
 import type { AdbShellProtocolProcess } from "./spawner.js";
 
 export class AdbShellProtocolProcessImpl implements AdbShellProtocolProcess {
-    readonly #socket: AdbSocket;
+    readonly #socket: Adb.Socket;
     readonly #writer: WritableStreamDefaultWriter<MaybeConsumable<Uint8Array>>;
 
     readonly #stdin: WritableStream<MaybeConsumable<Uint8Array>>;
@@ -43,7 +43,7 @@ export class AdbShellProtocolProcessImpl implements AdbShellProtocolProcess {
         return this.#exited;
     }
 
-    constructor(socket: AdbSocket, signal?: AbortSignal) {
+    constructor(socket: Adb.Socket, signal?: AbortSignal) {
         this.#socket = socket;
 
         let stdoutController!: PushReadableStreamController<Uint8Array>;
@@ -111,14 +111,13 @@ export class AdbShellProtocolProcessImpl implements AdbShellProtocolProcess {
 
         this.#writer = this.#socket.writable.getWriter();
         this.#stdin = new MaybeConsumable.WritableStream<Uint8Array>({
-            write: async (chunk) => {
-                await this.#writer.write(
+            write: (chunk) =>
+                this.#writer.write(
                     AdbShellProtocolPacket.serialize({
                         id: AdbShellProtocolId.Stdin,
                         data: chunk,
                     }),
-                );
-            },
+                ),
             close: () =>
                 // Only shell protocol + raw mode supports closing stdin
                 this.#writer.write(

package/src/{commands → service}/subprocess/shell/pty.ts

@@ -12,13 +12,13 @@ import {
 } from "@yume-chan/stream-extra";
 import { encodeUtf8 } from "@yume-chan/struct";
 
-import type { AdbSocket } from "../../../adb.js";
-import type { AdbPtyProcess } from "../pty.js";
+import type { Adb } from "../../../adb.js";
+import type { AdbPty } from "../pty.js";
 
 import { AdbShellProtocolId, AdbShellProtocolPacket } from "./shared.js";
 
-export class AdbShellProtocolPtyProcess implements AdbPtyProcess<number> {
-    readonly #socket: AdbSocket;
+export class AdbShellProtocolPty implements AdbPty<number> {
+    readonly #socket: Adb.Socket;
     readonly #writer: WritableStreamDefaultWriter<MaybeConsumable<Uint8Array>>;
 
     readonly #input: WritableStream<MaybeConsumable<Uint8Array>>;
@@ -26,9 +26,9 @@ export class AdbShellProtocolPtyProcess implements AdbPtyProcess<number> {
         return this.#input;
     }
 
-    readonly #stdout: ReadableStream<Uint8Array>;
+    readonly #output: ReadableStream<Uint8Array>;
     get output() {
-        return this.#stdout;
+        return this.#output;
     }
 
     readonly #exited = new PromiseResolver<number>();
@@ -36,12 +36,12 @@ export class AdbShellProtocolPtyProcess implements AdbPtyProcess<number> {
         return this.#exited.promise;
     }
 
-    constructor(socket: AdbSocket) {
+    constructor(socket: Adb.Socket) {
         this.#socket = socket;
 
-        let stdoutController!: PushReadableStreamController<Uint8Array>;
-        this.#stdout = new PushReadableStream<Uint8Array>((controller) => {
-            stdoutController = controller;
+        let outputController!: PushReadableStreamController<Uint8Array>;
+        this.#output = new PushReadableStream<Uint8Array>((controller) => {
+            outputController = controller;
         });
 
         socket.readable
@@ -54,22 +54,23 @@ export class AdbShellProtocolPtyProcess implements AdbPtyProcess<number> {
                                 this.#exited.resolve(chunk.data[0]!);
                                 break;
                             case AdbShellProtocolId.Stdout:
-                                await stdoutController.enqueue(chunk.data);
+                                await outputController.enqueue(chunk.data);
                                 break;
+                            // PTY mode doesn't have stderr
                         }
                     },
                 }),
             )
             .then(
                 () => {
-                    stdoutController.close();
+                    outputController.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);
+                    outputController.error(e);
                     // If `#exit` has already resolved, this will be a no-op
                     this.#exited.reject(e);
                 },
@@ -103,6 +104,7 @@ export class AdbShellProtocolPtyProcess implements AdbPtyProcess<number> {
     }
 
     sigint() {
+        // Write `^C`
         return this.#writeStdin(new Uint8Array([0x03]));
     }
 

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

@@ -0,0 +1,75 @@
+import type { Adb } from "../../../adb.js";
+import { AdbFeature } from "../../../features.js";
+
+import { AdbShellProtocolProcessImpl } from "./process.js";
+import { AdbShellProtocolPty } from "./pty.js";
+import { AdbShellProtocolId, AdbShellProtocolPacket } from "./shared.js";
+import { adbShellProtocolSpawner } from "./spawner.js";
+
+export class AdbShellProtocolSubprocessService {
+    static readonly PacketId = AdbShellProtocolId;
+
+    static readonly Packet = AdbShellProtocolPacket;
+
+    readonly #adb: Adb;
+    get adb() {
+        return this.#adb;
+    }
+
+    get isSupported() {
+        return this.#adb.canUseFeature(AdbFeature.Shell2);
+    }
+
+    constructor(adb: Adb) {
+        this.#adb = adb;
+    }
+
+    spawn = adbShellProtocolSpawner(async (command, signal) => {
+        if (!command.length) {
+            throw new Error("Command cannot be empty");
+        }
+
+        // Don't escape `command`. See `AdbNoneProtocolSubprocessService.prototype.spawn` for details.
+        const service = "shell,v2,raw:" + command.join(" ");
+        const socket = await this.#adb.createSocket(service);
+
+        if (signal?.aborted) {
+            await socket.close();
+            throw signal.reason;
+        }
+
+        return new AdbShellProtocolProcessImpl(socket, signal);
+    });
+
+    async pty(options?: {
+        command?: string | readonly string[] | undefined;
+        terminalType?: string;
+    }): Promise<AdbShellProtocolPty> {
+        const { command, terminalType } = options ?? {};
+
+        let service = "shell,v2,pty";
+
+        if (terminalType) {
+            if (terminalType.includes(",") || terminalType.includes(":")) {
+                throw new Error("terminalType must not contain ',' or ':'");
+            }
+            service += `,TERM=` + terminalType;
+        }
+        service += ":";
+
+        if (typeof command === "string") {
+            service += command;
+        } else if (Array.isArray(command)) {
+            // Don't escape `command`. See `AdbNoneProtocolSubprocessService.prototype.spawn` for details.
+            service += command.join(" ");
+        }
+
+        return new AdbShellProtocolPty(await this.#adb.createSocket(service));
+    }
+}
+
+export namespace AdbShellProtocolSubprocessService {
+    export type PacketId = AdbShellProtocolId;
+
+    export type Packet = AdbShellProtocolPacket;
+}

package/src/{commands → service}/subprocess/shell/shared.ts

@@ -1,6 +1,7 @@
 import type { StructValue } from "@yume-chan/struct";
 import { buffer, struct, u32, u8 } from "@yume-chan/struct";
 
+/** @internal */
 export const AdbShellProtocolId = {
     Stdin: 0,
     Stdout: 1,
@@ -10,10 +11,12 @@ export const AdbShellProtocolId = {
     WindowSizeChange: 5,
 } as const;
 
+/** @internal */
 export type AdbShellProtocolId =
     (typeof AdbShellProtocolId)[keyof typeof AdbShellProtocolId];
 
 // This packet format is used in both directions.
+/** @internal */
 export const AdbShellProtocolPacket = struct(
     {
         id: u8<AdbShellProtocolId>(),
@@ -22,4 +25,6 @@ export const AdbShellProtocolPacket = struct(
     { littleEndian: true },
 );
 
+// `StructValue` and `StructInit` is same for `AdbShellProtocolPacket`.
+/** @internal */
 export type AdbShellProtocolPacket = StructValue<typeof AdbShellProtocolPacket>;