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

package/src/server/transport.ts

@@ -1,37 +1,11 @@
 import { PromiseResolver } from "@yume-chan/async";
 
-import type {
-    AdbIncomingSocketHandler,
-    AdbSocket,
-    AdbTransport,
-} from "../adb.js";
+import type { Adb, AdbTransport } from "../adb.js";
 import type { AdbBanner } from "../banner.js";
-import { AdbFeature } from "../features.js";
+import { AdbDeviceFeatures } from "../features.js";
 
 import type { AdbServerClient } from "./client.js";
 
-export const ADB_SERVER_DEFAULT_FEATURES = /* #__PURE__ */ (() =>
-    [
-        AdbFeature.ShellV2,
-        AdbFeature.Cmd,
-        AdbFeature.StatV2,
-        AdbFeature.ListV2,
-        AdbFeature.FixedPushMkdir,
-        "apex",
-        AdbFeature.Abb,
-        // only tells the client the symlink timestamp issue in `adb push --sync` has been fixed.
-        // No special handling required.
-        "fixed_push_symlink_timestamp",
-        AdbFeature.AbbExec,
-        "remount_shell",
-        "track_app",
-        AdbFeature.SendReceiveV2,
-        "sendrecv_v2_brotli",
-        "sendrecv_v2_lz4",
-        "sendrecv_v2_zstd",
-        "sendrecv_v2_dry_run_send",
-    ] as readonly AdbFeature[])();
-
 export class AdbServerTransport implements AdbTransport {
     #client: AdbServerClient;
 
@@ -43,7 +17,7 @@ export class AdbServerTransport implements AdbTransport {
 
     readonly banner: AdbBanner;
 
-    #sockets: AdbSocket[] = [];
+    #sockets: Adb.Socket[] = [];
 
     #closed = new PromiseResolver<void>();
     #disconnected: Promise<void>;
@@ -52,9 +26,14 @@ export class AdbServerTransport implements AdbTransport {
     }
 
     get clientFeatures() {
-        // No need to get host features (features supported by ADB server)
-        // Because we create all ADB packets ourselves
-        return ADB_SERVER_DEFAULT_FEATURES;
+        // This list tells the `Adb` instance how to invoke some commands.
+        //
+        // Because all device commands are created by the `Adb` instance, not ADB server,
+        // we don't need to fetch current server's feature list using `host-features` command.
+        //
+        // And because all server commands are created by the `AdbServerClient` instance, not `Adb`,
+        // we don't need to pass server-only features to `Adb` in this list.
+        return AdbDeviceFeatures;
     }
 
     // eslint-disable-next-line @typescript-eslint/max-params
@@ -73,7 +52,7 @@ export class AdbServerTransport implements AdbTransport {
         this.#disconnected = Promise.race([this.#closed.promise, disconnected]);
     }
 
-    async connect(service: string): Promise<AdbSocket> {
+    async connect(service: string): Promise<Adb.Socket> {
         const socket = await this.#client.createDeviceConnection(
             { transportId: this.transportId },
             service,
@@ -83,7 +62,7 @@ export class AdbServerTransport implements AdbTransport {
     }
 
     async addReverseTunnel(
-        handler: AdbIncomingSocketHandler,
+        handler: Adb.IncomingSocketHandler,
         address?: string,
     ): Promise<string> {
         return await this.#client.connector.addReverseTunnel(handler, address);

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

@@ -1,7 +1,6 @@
-export * from "./base.js";
 export * from "./framebuffer.js";
 export * from "./power.js";
-export * from "./reverse.js";
+export * from "./reverse/index.js";
 export * from "./subprocess/index.js";
 export * from "./sync/index.js";
 export * from "./tcpip.js";

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

@@ -3,11 +3,17 @@
 // cspell: ignore keyevent
 // cspell: ignore longpress
 
-import { AdbServiceBase } from "./base.js";
+import type { Adb } from "../adb.js";
+
+export class AdbPowerService {
+    readonly #adb: Adb;
+
+    constructor(adb: Adb) {
+        this.#adb = adb;
+    }
 
-export class AdbPower extends AdbServiceBase {
     reboot(mode = "") {
-        return this.adb.createSocketAndWait(`reboot:${mode}`);
+        return this.#adb.createSocketAndWait(`reboot:${mode}`);
     }
 
     bootloader() {
@@ -36,7 +42,10 @@ export class AdbPower extends AdbServiceBase {
     }
 
     powerOff(): Promise<string> {
-        return this.adb.subprocess.noneProtocol.spawnWaitText(["reboot", "-p"]);
+        return this.#adb.subprocess.noneProtocol
+            .spawn(["reboot", "-p"])
+            .wait()
+            .toString();
     }
 
     powerButton(longPress = false): Promise<string> {
@@ -46,7 +55,7 @@ export class AdbPower extends AdbServiceBase {
         }
         args.push("POWER");
 
-        return this.adb.subprocess.noneProtocol.spawnWaitText(args);
+        return this.#adb.subprocess.noneProtocol.spawn(args).wait().toString();
     }
 
     /**

package/src/service/reverse/error.ts

@@ -0,0 +1,35 @@
+const AdbReverseErrorBrand = Symbol.for("AdbReverseError.brand");
+
+export class AdbReverseError extends Error {
+    [AdbReverseErrorBrand] = true;
+
+    static override [Symbol.hasInstance](value: unknown) {
+        return !!(value as AdbReverseNotSupportedError | undefined)?.[
+            AdbReverseErrorBrand
+        ];
+    }
+
+    constructor(message: string) {
+        super(message);
+    }
+}
+
+const AdbReverseNotSupportedErrorBrand = Symbol.for(
+    "AdbReverseNotSupportedError.brand",
+);
+
+export class AdbReverseNotSupportedError extends AdbReverseError {
+    [AdbReverseNotSupportedErrorBrand] = true;
+
+    static override [Symbol.hasInstance](value: unknown) {
+        return !!(value as AdbReverseNotSupportedError | undefined)?.[
+            AdbReverseNotSupportedErrorBrand
+        ];
+    }
+
+    constructor() {
+        super(
+            "ADB reverse tunnel is not supported on this device when connected wirelessly.",
+        );
+    }
+}

package/src/service/reverse/index.ts

@@ -0,0 +1,3 @@
+export * from "./error.js";
+export * from "./service.js";
+// `response.ts` is internal

package/src/service/reverse/response.ts

@@ -0,0 +1,38 @@
+import { extend, string, struct } from "@yume-chan/struct";
+
+import { AdbReverseError, AdbReverseNotSupportedError } from "./error.js";
+
+/** @internal exported for tests */
+export 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 },
+);
+
+/** @internal exported for tests */
+export const AdbReverseErrorResponse = extend(
+    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);
+            }
+        },
+    },
+);

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,85 @@
+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) => {
+                try {
+                    const [, output] = await Promise.all([
+                        options?.stdin?.pipeTo(process.stdin),
+                        process.output.pipeThrough(new ToArrayStream()),
+                    ]);
+                    return output;
+                } finally {
+                    await process.kill();
+                }
+            });
+
+            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>;
@@ -98,27 +98,23 @@ export class AdbShellProtocolProcessImpl implements AdbShellProtocolProcess {
                 },
             );
 
-        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();
-            });
-        }
+        // `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(
+            write: (chunk) =>
+                this.#writer.write(
                     AdbShellProtocolPacket.serialize({
                         id: AdbShellProtocolId.Stdin,
                         data: chunk,
                     }),
-                );
-            },
+                ),
             close: () =>
                 // Only shell protocol + raw mode supports closing stdin
                 this.#writer.write(