@yume-chan/adb 0.0.9 → 0.0.10

package/src/commands/reverse.ts

@@ -1,133 +1,134 @@
-import { AutoDisposable } from '@yume-chan/event';
-import Struct from '@yume-chan/struct';
-import { AdbPacket } from '../packet';
-import { AdbIncomingSocketEventArgs, AdbPacketDispatcher, AdbSocket } from '../socket';
-import { AdbBufferedStream } from '../stream';
-
-export interface AdbReverseHandler {
-    onSocket(packet: AdbPacket, socket: AdbSocket): void;
-}
-
-export interface AdbForwardListener {
-    deviceSerial: string;
-
-    localName: string;
-
-    remoteName: string;
-}
-
-const AdbReverseStringResponse =
-    new Struct({ littleEndian: true })
-        .string('length', { length: 4 })
-        .string('content', { lengthField: 'length', lengthFieldBase: 16 });
-
-const AdbReverseErrorResponse =
-    new Struct({ littleEndian: true })
-        .fields(AdbReverseStringResponse)
-        .postDeserialize((value) => {
-            throw new Error(value.content);
-        });
-
-export class AdbReverseCommand extends AutoDisposable {
-    protected localPortToHandler = new Map<number, AdbReverseHandler>();
-
-    protected deviceAddressToLocalPort = new Map<string, number>();
-
-    protected dispatcher: AdbPacketDispatcher;
-
-    protected listening = false;
-
-    public constructor(dispatcher: AdbPacketDispatcher) {
-        super();
-
-        this.dispatcher = dispatcher;
-        this.addDisposable(this.dispatcher.onIncomingSocket(this.handleIncomingSocket, this));
-    }
-
-    protected handleIncomingSocket(e: AdbIncomingSocketEventArgs): void {
-        if (e.handled) {
-            return;
-        }
-
-        const address = this.dispatcher.backend.decodeUtf8(e.packet.payload!);
-        // tcp:1234\0
-        const port = Number.parseInt(address.substring(4));
-        if (this.localPortToHandler.has(port)) {
-            this.localPortToHandler.get(port)!.onSocket(e.packet, e.socket);
-            e.handled = true;
-        }
-    }
-
-    private async createBufferedStream(service: string) {
-        const socket = await this.dispatcher.createSocket(service);
-        return new AdbBufferedStream(socket);
-    }
-
-    private async sendRequest(service: string) {
-        const stream = await this.createBufferedStream(service);
-        const success = this.dispatcher.backend.decodeUtf8(await stream.read(4)) === 'OKAY';
-        if (!success) {
-            await AdbReverseErrorResponse.deserialize(stream);
-        }
-        return stream;
-    }
-
-    public async list(): Promise<AdbForwardListener[]> {
-        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(' ');
-            return { deviceSerial, localName, remoteName };
-        });
-
-        // No need to close the stream, device will close it
-    }
-
-    /**
-     * @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 localPort Native ADB will open a connection to localPort when reverse connection starts. In webadb, it's only used to uniquely identify a reverse registry, `handler` will be called on connection.
-     * @param handler A callback to handle incoming connections
-     * @returns If `deviceAddress` is `tcp:0`, return `tcp:{ACTUAL_LISTENING_PORT}`; otherwise, return `deviceAddress`.
-     */
-    public async add(
-        deviceAddress: string,
-        localPort: number,
-        handler: AdbReverseHandler,
-    ): Promise<string> {
-        const stream = await this.sendRequest(`reverse:forward:${deviceAddress};tcp:${localPort}`);
-
-        // `tcp:0` tells the device to pick an available port.
-        // However, device will response with the selected port for all `tcp:` requests.
-        if (deviceAddress.startsWith('tcp:')) {
-            const response = await AdbReverseStringResponse.deserialize(stream);
-            deviceAddress = `tcp:${Number.parseInt(response.content!, 10)}`;
-        }
-
-        this.localPortToHandler.set(localPort, handler);
-        this.deviceAddressToLocalPort.set(deviceAddress, localPort);
-        return deviceAddress;
-
-        // No need to close the stream, device will close it
-    }
-
-    public async remove(deviceAddress: string): Promise<void> {
-        await this.sendRequest(`reverse:killforward:${deviceAddress}`);
-
-        if (this.deviceAddressToLocalPort.has(deviceAddress)) {
-            this.localPortToHandler.delete(this.deviceAddressToLocalPort.get(deviceAddress)!);
-            this.deviceAddressToLocalPort.delete(deviceAddress);
-        }
-
-        // No need to close the stream, device will close it
-    }
-
-    public async removeAll(): Promise<void> {
-        await this.sendRequest(`reverse:killforward-all`);
-
-        this.deviceAddressToLocalPort.clear();
-        this.localPortToHandler.clear();
-
-        // No need to close the stream, device will close it
-    }
-}
+import { AutoDisposable } from '@yume-chan/event';
+import Struct from '@yume-chan/struct';
+import type { AdbPacket } from '../packet';
+import type { AdbIncomingSocketEventArgs, AdbPacketDispatcher, AdbSocket } from '../socket';
+import { AdbBufferedStream } from '../stream';
+import { decodeUtf8 } from "../utils";
+
+export interface AdbReverseHandler {
+    onSocket(packet: AdbPacket, socket: AdbSocket): void;
+}
+
+export interface AdbForwardListener {
+    deviceSerial: string;
+
+    localName: string;
+
+    remoteName: string;
+}
+
+const AdbReverseStringResponse =
+    new Struct({ littleEndian: true })
+        .string('length', { length: 4 })
+        .string('content', { lengthField: 'length', lengthFieldBase: 16 });
+
+const AdbReverseErrorResponse =
+    new Struct({ littleEndian: true })
+        .fields(AdbReverseStringResponse)
+        .postDeserialize((value) => {
+            throw new Error(value.content);
+        });
+
+export class AdbReverseCommand extends AutoDisposable {
+    protected localPortToHandler = new Map<number, AdbReverseHandler>();
+
+    protected deviceAddressToLocalPort = new Map<string, number>();
+
+    protected dispatcher: AdbPacketDispatcher;
+
+    protected listening = false;
+
+    public constructor(dispatcher: AdbPacketDispatcher) {
+        super();
+
+        this.dispatcher = dispatcher;
+        this.addDisposable(this.dispatcher.onIncomingSocket(this.handleIncomingSocket, this));
+    }
+
+    protected handleIncomingSocket(e: AdbIncomingSocketEventArgs): void {
+        if (e.handled) {
+            return;
+        }
+
+        const address = decodeUtf8(e.packet.payload!);
+        // tcp:1234\0
+        const port = Number.parseInt(address.substring(4));
+        if (this.localPortToHandler.has(port)) {
+            this.localPortToHandler.get(port)!.onSocket(e.packet, e.socket);
+            e.handled = true;
+        }
+    }
+
+    private async createBufferedStream(service: string) {
+        const socket = await this.dispatcher.createSocket(service);
+        return new AdbBufferedStream(socket);
+    }
+
+    private async sendRequest(service: string) {
+        const stream = await this.createBufferedStream(service);
+        const success = decodeUtf8(await stream.read(4)) === 'OKAY';
+        if (!success) {
+            await AdbReverseErrorResponse.deserialize(stream);
+        }
+        return stream;
+    }
+
+    public async list(): Promise<AdbForwardListener[]> {
+        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(' ');
+            return { deviceSerial, localName, remoteName };
+        });
+
+        // No need to close the stream, device will close it
+    }
+
+    /**
+     * @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 localPort Native ADB will open a connection to localPort when reverse connection starts. In webadb, it's only used to uniquely identify a reverse registry, `handler` will be called on connection.
+     * @param handler A callback to handle incoming connections
+     * @returns If `deviceAddress` is `tcp:0`, return `tcp:{ACTUAL_LISTENING_PORT}`; otherwise, return `deviceAddress`.
+     */
+    public async add(
+        deviceAddress: string,
+        localPort: number,
+        handler: AdbReverseHandler,
+    ): Promise<string> {
+        const stream = await this.sendRequest(`reverse:forward:${deviceAddress};tcp:${localPort}`);
+
+        // `tcp:0` tells the device to pick an available port.
+        // However, device will response with the selected port for all `tcp:` requests.
+        if (deviceAddress.startsWith('tcp:')) {
+            const response = await AdbReverseStringResponse.deserialize(stream);
+            deviceAddress = `tcp:${Number.parseInt(response.content!, 10)}`;
+        }
+
+        this.localPortToHandler.set(localPort, handler);
+        this.deviceAddressToLocalPort.set(deviceAddress, localPort);
+        return deviceAddress;
+
+        // No need to close the stream, device will close it
+    }
+
+    public async remove(deviceAddress: string): Promise<void> {
+        await this.sendRequest(`reverse:killforward:${deviceAddress}`);
+
+        if (this.deviceAddressToLocalPort.has(deviceAddress)) {
+            this.localPortToHandler.delete(this.deviceAddressToLocalPort.get(deviceAddress)!);
+            this.deviceAddressToLocalPort.delete(deviceAddress);
+        }
+
+        // No need to close the stream, device will close it
+    }
+
+    public async removeAll(): Promise<void> {
+        await this.sendRequest(`reverse:killforward-all`);
+
+        this.deviceAddressToLocalPort.clear();
+        this.localPortToHandler.clear();
+
+        // No need to close the stream, device will close it
+    }
+}

package/src/commands/shell/index.ts

@@ -1,68 +1,87 @@
-import { Adb } from '../../adb';
-import { AdbFeatures } from '../../features';
-import { AdbLegacyShell } from './legacy';
-import { AdbShellProtocol } from './protocol';
-import { AdbShell } from './types';
-
-export * from './legacy';
-export * from './protocol';
-export * from './types';
-export * from './utils';
-
-export type AdbShellProtocolOption = 'auto' | 'enable' | 'disable';
-
-export interface AdbChildProcessOptions {
-    shellProtocol: 'auto' | 'enable' | 'disable',
-}
-
-const DefaultOptions: AdbChildProcessOptions = {
-    shellProtocol: 'auto',
-};
-
-export class AdbChildProcess {
-    public readonly adb: Adb;
-
-    public get supportsShellProtocol(): boolean {
-        return this.adb.features!.includes(AdbFeatures.ShellV2);
-    }
-
-    public constructor(adb: Adb) {
-        this.adb = adb;
-    }
-
-    private async createShell(command: string, options?: Partial<AdbChildProcessOptions>): Promise<AdbShell> {
-        let { shellProtocol } = { ...DefaultOptions, ...options };
-        switch (shellProtocol) {
-            case 'auto':
-                shellProtocol = this.supportsShellProtocol ? 'enable' : 'disable';
-                break;
-            case 'enable':
-                if (!shellProtocol) {
-                    throw new Error('`shellProtocol` has been set to `enable` but the device does not support it');
-                }
-                break;
-        }
-
-        if (shellProtocol === 'enable') {
-            return new AdbShellProtocol(await this.adb.createSocket(`shell,v2,pty:${command}`));
-        }
-
-        return new AdbLegacyShell(await this.adb.createSocket(`shell:${command}`));
-    }
-
-    public shell(options?: Partial<AdbChildProcessOptions>): Promise<AdbShell> {
-        return this.createShell('', options);
-    }
-
-    public spawn(command: string | string[], options?: Partial<AdbChildProcessOptions>): Promise<AdbShell> {
-        if (Array.isArray(command)) {
-            command = command.join(' ');
-        }
-        return this.createShell(command, options);
-    }
-
-    public exec(command: string, ...args: string[]): Promise<string> {
-        // `exec` only need all output, using Shell Protocol only makes it more complicate.
-        return this.adb.createSocketAndReadAll(`shell:${command} ${args.join(' ')}`);
-    }
-}
+import type { Adb } from '../../adb';
+import { AdbLegacyShell } from './legacy';
+import { AdbShellProtocol } from './protocol';
+import type { AdbShell, AdbShellConstructor } from './types';
+
+export * from './legacy';
+export * from './protocol';
+export * from './types';
+export * from './utils';
+
+export interface AdbChildProcessOptions {
+    /**
+     * A list of `AdbShellConstructor`s to be used.
+     *
+     * Different `AdbShell` has different capabilities, thus requires specific adaptations.
+     * Check each `AdbShell`'s documentation for details.
+     *
+     * The first one whose `isSupported` returns `true` will be used.
+     * If no `AdbShell` is supported, an error will be thrown.
+     *
+     * The default value is `[AdbShellProtocol, AdbLegacyShell]`.
+     */
+    shells: AdbShellConstructor[];
+}
+
+const DefaultOptions: AdbChildProcessOptions = {
+    shells: [AdbShellProtocol, AdbLegacyShell],
+};
+
+export class AdbChildProcess {
+    public readonly adb: Adb;
+
+    public constructor(adb: Adb) {
+        this.adb = adb;
+    }
+
+    private async createShell(command: string, options?: Partial<AdbChildProcessOptions>): Promise<AdbShell> {
+        let { shells } = { ...DefaultOptions, ...options };
+
+        let shell: AdbShellConstructor | undefined;
+        for (const item of shells) {
+            if (await item.isSupported(this.adb)) {
+                shell = item;
+                break;
+            }
+        }
+
+        if (!shell) {
+            throw new Error('No specified shell is supported by the device');
+        }
+
+        return await shell.spawn(this.adb, command);
+    }
+
+    /**
+     * Spawns the default shell in interactive mode.
+     * @param options The options for creating the `AdbShell`
+     * @returns A new `AdbShell` instance connecting to the spawned shell process.
+     */
+    public shell(options?: Partial<AdbChildProcessOptions>): Promise<AdbShell> {
+        return this.createShell('', options);
+    }
+
+    /**
+     * Spawns a new process using the given `command`.
+     * @param command The command to run, or an array of strings containing both command and args.
+     * @param options The options for creating the `AdbShell`
+     * @returns A new `AdbShell` instance connecting to the spawned process.
+     */
+    public spawn(command: string | string[], options?: Partial<AdbChildProcessOptions>): Promise<AdbShell> {
+        if (Array.isArray(command)) {
+            command = command.join(' ');
+        }
+        return this.createShell(command, options);
+    }
+
+    /**
+     * Spawns a new process, waits until it exits, and returns the entire output.
+     * @param command The command to run
+     * @param args List of command arguments
+     * @returns The entire output of the command
+     */
+    public exec(command: string, ...args: string[]): Promise<string> {
+        // `exec` only needs the entire output, use Legacy Shell is simpler.
+        return this.adb.createSocketAndReadAll(`shell:${command} ${args.join(' ')}`);
+    }
+}

package/src/commands/shell/legacy.ts

@@ -1,42 +1,59 @@
-import { EventEmitter } from "@yume-chan/event";
-import { AdbSocket } from "../../socket";
-import { AdbShell } from "./types";
-
-export class AdbLegacyShell implements AdbShell {
-    private readonly socket: AdbSocket;
-
-    private readonly stdoutEvent = new EventEmitter<ArrayBuffer>();
-    public get onStdout() { return this.stdoutEvent.event; }
-
-    private readonly stderrEvent = new EventEmitter<ArrayBuffer>();
-    public get onStderr() { return this.stderrEvent.event; }
-
-    private readonly exitEvent = new EventEmitter<number>();
-    public get onExit() { return this.exitEvent.event; }
-
-    public constructor(socket: AdbSocket) {
-        this.socket = socket;
-        this.socket.onData(this.handleData, this);
-        this.socket.onClose(this.handleExit, this);
-    }
-
-    private handleData(data: ArrayBuffer) {
-        this.stdoutEvent.fire(data);
-    }
-
-    private handleExit() {
-        this.exitEvent.fire(0);
-    }
-
-    public async write(data: ArrayBuffer) {
-        this.socket.write(data);
-    }
-
-    public resize() {
-        // Not supported
-    }
-
-    public kill() {
-        return this.socket.close();
-    }
-}
+import { EventEmitter } from "@yume-chan/event";
+import type { Adb } from "../../adb";
+import type { AdbSocket } from "../../socket";
+import type { AdbShell } from "./types";
+
+/**
+ * The legacy shell
+ *
+ * Features:
+ * * `onStderr`: No
+ * * `onExit` exit code: No
+ * * `resize`: No
+ */
+export class AdbLegacyShell implements AdbShell {
+    public static isSupported() { return true; }
+
+    public static async spawn(adb: Adb, command: string) {
+        return new AdbLegacyShell(await adb.createSocket(`shell:${command}`));
+    }
+
+    private readonly socket: AdbSocket;
+
+    private readonly stdoutEvent = new EventEmitter<ArrayBuffer>();
+    public get onStdout() { return this.stdoutEvent.event; }
+
+    private readonly stderrEvent = new EventEmitter<ArrayBuffer>();
+    public get onStderr() { return this.stderrEvent.event; }
+
+    private readonly exitEvent = new EventEmitter<number>();
+    public get onExit() { return this.exitEvent.event; }
+
+    public constructor(socket: AdbSocket) {
+        this.socket = socket;
+        this.socket.onData(this.handleData, this);
+        this.socket.onClose(this.handleExit, this);
+    }
+
+    private handleData(data: ArrayBuffer) {
+        // Legacy shell doesn't support splitting output streams.
+        this.stdoutEvent.fire(data);
+    }
+
+    private handleExit() {
+        // Legacy shell doesn't support returning exit code.
+        this.exitEvent.fire(0);
+    }
+
+    public async write(data: ArrayBuffer) {
+        this.socket.write(data);
+    }
+
+    public resize() {
+        // Not supported
+    }
+
+    public kill() {
+        return this.socket.close();
+    }
+}