@yume-chan/adb 0.0.17 → 0.0.19

package/src/commands/index.ts

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

package/src/commands/power.ts

@@ -3,27 +3,27 @@
 // cspell: ignore keyevent
 // cspell: ignore longpress
 
-import { AdbCommandBase } from './base.js';
+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,12 +1,15 @@
 // cspell: ignore killforward
 
-import { AutoDisposable } from '@yume-chan/event';
-import { BufferedReadableStream, BufferedReadableStreamEndedError } from '@yume-chan/stream-extra';
-import Struct from '@yume-chan/struct';
+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, AdbSocket } from '../socket/index.js';
-import { decodeUtf8 } from '../utils/index.js';
+import type { Adb } from "../adb.js";
+import type { AdbIncomingSocketHandler, AdbSocket } from "../socket/index.js";
+import { decodeUtf8 } from "../utils/index.js";
 
 export interface AdbForwardListener {
     deviceSerial: string;
@@ -16,20 +19,44 @@ 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);
-        });
+export class AdbReverseError extends Error {
+    public constructor(message: string) {
+        super(message);
+        Object.setPrototypeOf(this, AdbReverseError.prototype);
+    }
+}
+
+export class AdbReverseNotSupportedError extends Error {
+    public constructor() {
+        super(
+            "ADB reverse tunnel is not supported on this device when connected wirelessly."
+        );
+        Object.setPrototypeOf(this, AdbReverseNotSupportedError.prototype);
+    }
+}
+
+const AdbReverseErrorResponse = new Struct()
+    .fields(AdbReverseStringResponse)
+    .postDeserialize((value) => {
+        // https://issuetracker.google.com/issues/37066218
+        // ADB on Android <9 can't create reverse tunnels when connected wirelessly (ADB over WiFi),
+        // 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);
+        }
+    });
 
 export class AdbReverseCommand extends AutoDisposable {
-    protected localAddressToHandler = new Map<string, AdbIncomingSocketHandler>();
+    protected localAddressToHandler = new Map<
+        string,
+        AdbIncomingSocketHandler
+    >();
 
     protected deviceAddressToLocalAddress = new Map<string, string>();
 
@@ -41,13 +68,15 @@ export class AdbReverseCommand extends AutoDisposable {
         super();
 
         this.adb = adb;
-        this.addDisposable(this.adb.onIncomingSocket(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));
     };
 
@@ -58,7 +87,7 @@ export class AdbReverseCommand extends AutoDisposable {
 
     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);
         }
@@ -66,11 +95,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 };
         });
 
@@ -78,21 +111,30 @@ 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 deviceAddress
+     * The address to be listened on device by ADB daemon. Or `tcp:0` to choose an available TCP port.
+     * @param localAddress
+     * An identifier for the reverse tunnel.
+     *
+     * When a socket wants to connect to {@link deviceAddress}, native ADB client will forward that connection to {@link localAddress}.
+     * However in this library, the {@link handler} is invoked instead. So this parameter is only used to identify the reverse tunnel.
      * @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`.
+     * @throws {AdbReverseNotSupportedError} If ADB reverse tunnel is not supported on this device when connected wirelessly.
+     * @throws {AdbReverseError} If ADB daemon returns an error.
      */
     public async add(
         deviceAddress: string,
         localAddress: string,
-        handler: AdbIncomingSocketHandler,
+        handler: AdbIncomingSocketHandler
     ): Promise<string> {
-        const stream = await this.sendRequest(`reverse:forward:${deviceAddress};${localAddress}`);
+        const stream = await this.sendRequest(
+            `reverse:forward:${deviceAddress};${localAddress}`
+        );
 
         // `tcp:0` tells the device to pick an available port.
         // On Android >=8, device will respond with the selected port for all `tcp:` requests.
-        if (deviceAddress.startsWith('tcp:')) {
+        if (deviceAddress.startsWith("tcp:")) {
             let length: number | undefined;
             try {
                 length = Number.parseInt(decodeUtf8(await stream.read(4)), 16);
@@ -107,7 +149,7 @@ export class AdbReverseCommand extends AutoDisposable {
             }
 
             if (length !== undefined) {
-                const port = decodeUtf8(await stream.read(length!));
+                const port = decodeUtf8(await stream.read(length));
                 deviceAddress = `tcp:${Number.parseInt(port, 10)}`;
             }
         }
@@ -123,7 +165,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

@@ -1,7 +1,15 @@
-import { GatherStringStream, DecodeUtf8Stream } from '@yume-chan/stream-extra';
+import { DecodeUtf8Stream, GatherStringStream } from "@yume-chan/stream-extra";
 
-import { AdbCommandBase } from '../base.js';
-import { AdbSubprocessNoneProtocol, AdbSubprocessProtocol, AdbSubprocessProtocolConstructor, AdbSubprocessShellProtocol } from './protocols/index.js';
+import { AdbCommandBase } from "../base.js";
+
+import type {
+    AdbSubprocessProtocol,
+    AdbSubprocessProtocolConstructor,
+} from "./protocols/index.js";
+import {
+    AdbSubprocessNoneProtocol,
+    AdbSubprocessShellProtocol,
+} from "./protocols/index.js";
 
 export interface AdbSubprocessOptions {
     /**
@@ -30,7 +38,7 @@ export interface AdbSubprocessWaitResult {
 
 export class AdbSubprocess extends AdbCommandBase {
     private async createProtocol(
-        mode: 'pty' | 'raw',
+        mode: "pty" | "raw",
         command?: string | string[],
         options?: Partial<AdbSubprocessOptions>
     ): Promise<AdbSubprocessProtocol> {
@@ -46,20 +54,23 @@ export class AdbSubprocess extends AdbCommandBase {
         }
 
         if (!Constructor) {
-            throw new Error('No specified protocol is supported by the device');
+            throw new Error("No specified protocol is supported by the device");
         }
 
         if (Array.isArray(command)) {
-            command = command.join(' ');
+            command = command.join(" ");
         } else if (command === undefined) {
             // spawn the default shell
-            command = '';
+            command = "";
         }
         return await Constructor[mode](this.adb, command);
     }
 
     /**
-     * Spawns an executable in PTY (interactive) mode.
+     * Spawns an executable in PTY mode.
+     *
+     * Redirection mode is enough for most simple commands, but PTY mode is required for
+     * commands that manipulate the terminal, such as `vi` and `less`.
      * @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.
@@ -68,11 +79,14 @@ export class AdbSubprocess extends AdbCommandBase {
         command?: string | string[],
         options?: Partial<AdbSubprocessOptions>
     ): Promise<AdbSubprocessProtocol> {
-        return this.createProtocol('pty', command, options);
+        return this.createProtocol("pty", command, options);
     }
 
     /**
-     * Spawns an executable and pipe the output.
+     * Spawns an executable and redirect the standard input/output stream.
+     *
+     * Redirection mode is enough for most simple commands, but PTY mode is required for
+     * commands that manipulate the terminal, such as `vi` and `less`.
      * @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.
@@ -81,7 +95,7 @@ export class AdbSubprocess extends AdbCommandBase {
         command: string | string[],
         options?: Partial<AdbSubprocessOptions>
     ): Promise<AdbSubprocessProtocol> {
-        return this.createProtocol('raw', command, options);
+        return this.createProtocol("raw", command, options);
     }
 
     /**
@@ -100,13 +114,9 @@ export class AdbSubprocess extends AdbCommandBase {
         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
+            shell.stdout.pipeThrough(new DecodeUtf8Stream()).pipeTo(stdout),
+            shell.stderr.pipeThrough(new DecodeUtf8Stream()).pipeTo(stderr),
+            shell.exit,
         ]);
 
         return {
@@ -121,11 +131,12 @@ export class AdbSubprocess extends AdbCommandBase {
      * @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] }
-        );
+    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,3 +1,3 @@
-export * from './command.js';
-export * from './protocols/index.js';
-export * from './utils.js';
+export * from "./command.js";
+export * from "./protocols/index.js";
+export * from "./utils.js";

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

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

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

@@ -1,8 +1,9 @@
-import { DuplexStreamFactory, ReadableStream } from '@yume-chan/stream-extra';
+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';
+import type { Adb } from "../../../adb.js";
+import type { AdbSocket } from "../../../socket/index.js";
+
+import type { AdbSubprocessProtocol } from "./types.js";
 
 /**
  * The legacy shell
@@ -13,16 +14,22 @@ import type { AdbSubprocessProtocol } from './types.js';
  * * `resize`: No
  */
 export class AdbSubprocessNoneProtocol implements AdbSubprocessProtocol {
-    public static isSupported() { return true; }
+    public static isSupported() {
+        return true;
+    }
 
     public static async pty(adb: Adb, command: string) {
-        return new AdbSubprocessNoneProtocol(await adb.createSocket(`shell:${command}`));
+        return new AdbSubprocessNoneProtocol(
+            await adb.createSocket(`shell:${command}`)
+        );
     }
 
     public static async raw(adb: Adb, command: string) {
         // `shell,raw:${command}` also triggers raw mode,
         // But is not supported on Android version <7.
-        return new AdbSubprocessNoneProtocol(await adb.createSocket(`exec:${command}`));
+        return new AdbSubprocessNoneProtocol(
+            await adb.createSocket(`exec:${command}`)
+        );
     }
 
     private readonly socket: AdbSocket;
@@ -30,22 +37,30 @@ export class AdbSubprocessNoneProtocol implements AdbSubprocessProtocol {
     private readonly duplex: DuplexStreamFactory<Uint8Array, Uint8Array>;
 
     // Legacy shell forwards all data to stdin.
-    public get stdin() { return this.socket.writable; }
+    public get stdin() {
+        return this.socket.writable;
+    }
 
     private _stdout: ReadableStream<Uint8Array>;
     /**
      * Legacy shell mixes stdout and stderr.
      */
-    public get stdout() { return this._stdout; }
+    public get stdout() {
+        return this._stdout;
+    }
 
     private _stderr: ReadableStream<Uint8Array>;
     /**
      * `stderr` will always be empty.
      */
-    public get stderr() { return this._stderr; }
+    public get stderr() {
+        return this._stderr;
+    }
 
     private _exit: Promise<number>;
-    public get exit() { return this._exit; }
+    public get exit() {
+        return this._exit;
+    }
 
     public constructor(socket: AdbSocket) {
         this.socket = socket;