@yume-chan/adb 0.0.16 → 0.0.18

package/src/commands/power.ts

@@ -6,24 +6,24 @@
 import { AdbCommandBase } from "./base.js";
 
 export class AdbPower extends AdbCommandBase {
-    public reboot(name: string = '') {
+    public reboot(name = "") {
         return this.adb.createSocketAndWait(`reboot:${name}`);
     }
 
     public bootloader() {
-        return this.reboot('bootloader');
+        return this.reboot("bootloader");
     }
 
     public fastboot() {
-        return this.reboot('fastboot');
+        return this.reboot("fastboot");
     }
 
     public recovery() {
-        return this.reboot('recovery');
+        return this.reboot("recovery");
     }
 
     public sideload() {
-        return this.reboot('sideload');
+        return this.reboot("sideload");
     }
 
     /**
@@ -32,15 +32,19 @@ export class AdbPower extends AdbCommandBase {
      * Only works on some Qualcomm devices.
      */
     public qualcommEdlMode() {
-        return this.reboot('edl');
+        return this.reboot("edl");
     }
 
     public powerOff() {
-        return this.adb.subprocess.spawnAndWaitLegacy(['reboot', '-p']);
+        return this.adb.subprocess.spawnAndWaitLegacy(["reboot", "-p"]);
     }
 
-    public powerButton(longPress: boolean = false) {
-        return this.adb.subprocess.spawnAndWaitLegacy(['input', 'keyevent', longPress ? '--longpress POWER' : 'POWER']);
+    public powerButton(longPress = false) {
+        return this.adb.subprocess.spawnAndWaitLegacy([
+            "input",
+            "keyevent",
+            longPress ? "--longpress POWER" : "POWER",
+        ]);
     }
 
     /**
@@ -49,6 +53,6 @@ export class AdbPower extends AdbCommandBase {
      * Only works on Samsung devices.
      */
     public samsungOdin() {
-        return this.reboot('download');
+        return this.reboot("download");
     }
 }

package/src/commands/reverse.ts

@@ -1,10 +1,17 @@
 // cspell: ignore killforward
 
-import { AutoDisposable } from '@yume-chan/event';
-import Struct from '@yume-chan/struct';
-import type { Adb } from "../adb.js";
-import type { AdbIncomingSocketHandler, AdbSocket } from '../socket/index.js';
-import { AdbBufferedStream, BufferedStreamEndedError } from '../stream/index.js';
+import { AutoDisposable } from "@yume-chan/event";
+import {
+    BufferedReadableStream,
+    BufferedReadableStreamEndedError,
+} from "@yume-chan/stream-extra";
+import Struct from "@yume-chan/struct";
+
+import { type Adb } from "../adb.js";
+import {
+    type AdbIncomingSocketHandler,
+    type AdbSocket,
+} from "../socket/index.js";
 import { decodeUtf8 } from "../utils/index.js";
 
 export interface AdbForwardListener {
@@ -15,20 +22,21 @@ export interface AdbForwardListener {
     remoteName: string;
 }
 
-const AdbReverseStringResponse =
-    new Struct()
-        .string('length', { length: 4 })
-        .string('content', { lengthField: 'length', lengthFieldRadix: 16 });
+const AdbReverseStringResponse = new Struct()
+    .string("length", { length: 4 })
+    .string("content", { lengthField: "length", lengthFieldRadix: 16 });
 
-const AdbReverseErrorResponse =
-    new Struct()
-        .fields(AdbReverseStringResponse)
-        .postDeserialize((value) => {
-            throw new Error(value.content);
-        });
+const AdbReverseErrorResponse = new Struct()
+    .fields(AdbReverseStringResponse)
+    .postDeserialize((value) => {
+        throw new Error(value.content);
+    });
 
 export class AdbReverseCommand extends AutoDisposable {
-    protected localAddressToHandler = new Map<string, AdbIncomingSocketHandler>();
+    protected localAddressToHandler = new Map<
+        string,
+        AdbIncomingSocketHandler
+    >();
 
     protected deviceAddressToLocalAddress = new Map<string, string>();
 
@@ -40,24 +48,26 @@ export class AdbReverseCommand extends AutoDisposable {
         super();
 
         this.adb = adb;
-        this.addDisposable(this.adb.addIncomingSocketHandler(this.handleIncomingSocket));
+        this.addDisposable(
+            this.adb.onIncomingSocket(this.handleIncomingSocket)
+        );
     }
 
     protected handleIncomingSocket = async (socket: AdbSocket) => {
         let address = socket.serviceString;
         // ADB daemon appends `\0` to the service string
-        address = address.replace(/\0/g, '');
+        address = address.replace(/\0/g, "");
         return !!(await this.localAddressToHandler.get(address)?.(socket));
     };
 
     private async createBufferedStream(service: string) {
         const socket = await this.adb.createSocket(service);
-        return new AdbBufferedStream(socket);
+        return new BufferedReadableStream(socket.readable);
     }
 
     private async sendRequest(service: string) {
         const stream = await this.createBufferedStream(service);
-        const success = decodeUtf8(await stream.read(4)) === 'OKAY';
+        const success = decodeUtf8(await stream.read(4)) === "OKAY";
         if (!success) {
             await AdbReverseErrorResponse.deserialize(stream);
         }
@@ -65,11 +75,15 @@ export class AdbReverseCommand extends AutoDisposable {
     }
 
     public async list(): Promise<AdbForwardListener[]> {
-        const stream = await this.createBufferedStream('reverse:list-forward');
+        const stream = await this.createBufferedStream("reverse:list-forward");
 
         const response = await AdbReverseStringResponse.deserialize(stream);
-        return response.content!.split('\n').map(line => {
-            const [deviceSerial, localName, remoteName] = line.split(' ') as [string, string, string];
+        return response.content!.split("\n").map((line) => {
+            const [deviceSerial, localName, remoteName] = line.split(" ") as [
+                string,
+                string,
+                string
+            ];
             return { deviceSerial, localName, remoteName };
         });
 
@@ -79,34 +93,38 @@ export class AdbReverseCommand extends AutoDisposable {
     /**
      * @param deviceAddress The address adbd on device is listening on. Can be `tcp:0` to let adbd choose an available TCP port by itself.
      * @param localAddress Native ADB client will open a connection to this address when reverse connection received. In WebADB, it's only used to uniquely identify a reverse tunnel registry, `handler` will be called to handle the connection.
-     * @param handler A callback to handle incoming connections
-     * @returns If `deviceAddress` is `tcp:0`, return `tcp:{ACTUAL_LISTENING_PORT}`; otherwise, return `deviceAddress`.
+     * @param handler A callback to handle incoming connections. It must return `true` if it accepts the connection.
+     * @returns `tcp:{ACTUAL_LISTENING_PORT}`, If `deviceAddress` is `tcp:0`; otherwise, `deviceAddress`.
      */
     public async add(
         deviceAddress: string,
         localAddress: string,
-        handler: AdbIncomingSocketHandler,
+        handler: AdbIncomingSocketHandler
     ): Promise<string> {
-        const stream = await this.sendRequest(`reverse:forward:${deviceAddress};${localAddress}`);
+        // TODO(reverse): handle ADB bug
+        // https://issuetracker.google.com/issues/37066218
+        const stream = await this.sendRequest(
+            `reverse:forward:${deviceAddress};${localAddress}`
+        );
 
         // `tcp:0` tells the device to pick an available port.
-        // Begin with Android 8, device will respond with the selected port for all `tcp:` requests.
-        if (deviceAddress.startsWith('tcp:')) {
+        // On Android >=8, device will respond with the selected port for all `tcp:` requests.
+        if (deviceAddress.startsWith("tcp:")) {
             let length: number | undefined;
             try {
                 length = Number.parseInt(decodeUtf8(await stream.read(4)), 16);
             } catch (e) {
-                if (!(e instanceof BufferedStreamEndedError)) {
+                if (!(e instanceof BufferedReadableStreamEndedError)) {
                     throw e;
                 }
 
-                // Device before Android 8 doesn't have this response.
+                // Android <8 doesn't have this response.
                 // (the stream is closed now)
                 // Can be safely ignored.
             }
 
             if (length !== undefined) {
-                const port = decodeUtf8(await stream.read(length!));
+                const port = decodeUtf8(await stream.read(length));
                 deviceAddress = `tcp:${Number.parseInt(port, 10)}`;
             }
         }
@@ -122,7 +140,9 @@ export class AdbReverseCommand extends AutoDisposable {
         await this.sendRequest(`reverse:killforward:${deviceAddress}`);
 
         if (this.deviceAddressToLocalAddress.has(deviceAddress)) {
-            this.localAddressToHandler.delete(this.deviceAddressToLocalAddress.get(deviceAddress)!);
+            this.localAddressToHandler.delete(
+                this.deviceAddressToLocalAddress.get(deviceAddress)!
+            );
             this.deviceAddressToLocalAddress.delete(deviceAddress);
         }
 

package/src/commands/subprocess/command.ts

@@ -0,0 +1,134 @@
+import { DecodeUtf8Stream, GatherStringStream } from "@yume-chan/stream-extra";
+
+import { AdbCommandBase } from "../base.js";
+
+import {
+    AdbSubprocessNoneProtocol,
+    AdbSubprocessShellProtocol,
+    type AdbSubprocessProtocol,
+    type AdbSubprocessProtocolConstructor,
+} from "./protocols/index.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 extends AdbCommandBase {
+    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/index.ts

@@ -1,139 +1,3 @@
-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 './command.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/none.ts

@@ -1,7 +1,9 @@
-import type { Adb } from "../../../adb.js";
-import type { AdbSocket } from "../../../socket/index.js";
-import { DuplexStreamFactory, ReadableStream } from "../../../stream/index.js";
-import type { AdbSubprocessProtocol } from "./types.js";
+import { DuplexStreamFactory, ReadableStream } from '@yume-chan/stream-extra';
+
+import { type Adb } from "../../../adb.js";
+import { type AdbSocket } from "../../../socket/index.js";
+
+import { type AdbSubprocessProtocol } from "./types.js";
 
 /**
  * The legacy shell
@@ -20,7 +22,7 @@ export class AdbSubprocessNoneProtocol implements AdbSubprocessProtocol {
 
     public static async raw(adb: Adb, command: string) {
         // `shell,raw:${command}` also triggers raw mode,
-        // But is not supported before Android 7.
+        // But is not supported on Android version <7.
         return new AdbSubprocessNoneProtocol(await adb.createSocket(`exec:${command}`));
     }
 
@@ -49,6 +51,8 @@ export class AdbSubprocessNoneProtocol implements AdbSubprocessProtocol {
     public constructor(socket: AdbSocket) {
         this.socket = socket;
 
+        // Link `stdout`, `stderr` and `stdin` together,
+        // so closing any of them will close the others.
         this.duplex = new DuplexStreamFactory<Uint8Array, Uint8Array>({
             close: async () => {
                 await this.socket.close();
@@ -61,7 +65,7 @@ export class AdbSubprocessNoneProtocol implements AdbSubprocessProtocol {
     }
 
     public resize() {
-        // Not supported
+        // Not supported, but don't throw.
     }
 
     public kill() {