@yume-chan/adb 0.0.18 → 0.0.20

package/src/banner.ts

@@ -0,0 +1,82 @@
+import type { AdbFeature } from "./features.js";
+
+export enum AdbBannerKey {
+    Product = "ro.product.name",
+    Model = "ro.product.model",
+    Device = "ro.product.device",
+    Features = "features",
+}
+
+export class AdbBanner {
+    public static parse(banner: string) {
+        let product: string | undefined;
+        let model: string | undefined;
+        let device: string | undefined;
+        let features: AdbFeature[] = [];
+
+        const pieces = banner.split("::");
+        if (pieces.length > 1) {
+            const props = pieces[1]!;
+            for (const prop of props.split(";")) {
+                if (!prop) {
+                    continue;
+                }
+
+                const keyValue = prop.split("=");
+                if (keyValue.length !== 2) {
+                    continue;
+                }
+
+                const [key, value] = keyValue;
+                switch (key) {
+                    case AdbBannerKey.Product:
+                        product = value;
+                        break;
+                    case AdbBannerKey.Model:
+                        model = value;
+                        break;
+                    case AdbBannerKey.Device:
+                        device = value;
+                        break;
+                    case AdbBannerKey.Features:
+                        features = value!.split(",") as AdbFeature[];
+                        break;
+                }
+            }
+        }
+
+        return new AdbBanner(product, model, device, features);
+    }
+
+    #product: string | undefined;
+    public get product() {
+        return this.#product;
+    }
+
+    #model: string | undefined;
+    public get model() {
+        return this.#model;
+    }
+
+    #device: string | undefined;
+    public get device() {
+        return this.#device;
+    }
+
+    #features: AdbFeature[] = [];
+    public get features() {
+        return this.#features;
+    }
+
+    public constructor(
+        product: string | undefined,
+        model: string | undefined,
+        device: string | undefined,
+        features: AdbFeature[]
+    ) {
+        this.#product = product;
+        this.#model = model;
+        this.#device = device;
+        this.#features = features;
+    }
+}

package/src/commands/base.ts

@@ -1,6 +1,6 @@
 import { AutoDisposable } from "@yume-chan/event";
 
-import { type Adb } from "../adb.js";
+import type { Adb } from "../adb.js";
 
 export class AdbCommandBase extends AutoDisposable {
     protected adb: Adb;

package/src/commands/framebuffer.ts

@@ -1,7 +1,7 @@
 import { BufferedReadableStream } from "@yume-chan/stream-extra";
 import Struct from "@yume-chan/struct";
 
-import { type Adb } from "../adb.js";
+import type { Adb } from "../adb.js";
 
 const Version = new Struct({ littleEndian: true }).uint32("version");
 
@@ -20,7 +20,7 @@ export const AdbFrameBufferV1 = new Struct({ littleEndian: true })
     .uint32("alpha_length")
     .uint8Array("data", { lengthField: "size" });
 
-export type AdbFrameBufferV1 = typeof AdbFrameBufferV1["TDeserializeResult"];
+export type AdbFrameBufferV1 = (typeof AdbFrameBufferV1)["TDeserializeResult"];
 
 export const AdbFrameBufferV2 = new Struct({ littleEndian: true })
     .uint32("bpp")
@@ -38,7 +38,7 @@ export const AdbFrameBufferV2 = new Struct({ littleEndian: true })
     .uint32("alpha_length")
     .uint8Array("data", { lengthField: "size" });
 
-export type AdbFrameBufferV2 = typeof AdbFrameBufferV2["TDeserializeResult"];
+export type AdbFrameBufferV2 = (typeof AdbFrameBufferV2)["TDeserializeResult"];
 
 /**
  * ADB uses 8 int32 fields to describe bit depths
@@ -69,6 +69,6 @@ export async function framebuffer(adb: Adb): Promise<AdbFrameBuffer> {
         case 2:
             return AdbFrameBufferV2.deserialize(stream);
         default:
-            throw new Error("Unknown FrameBuffer version");
+            throw new Error("Unsupported FrameBuffer version");
     }
 }

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

@@ -6,8 +6,8 @@
 import { AdbCommandBase } from "./base.js";
 
 export class AdbPower extends AdbCommandBase {
-    public reboot(name = "") {
-        return this.adb.createSocketAndWait(`reboot:${name}`);
+    public reboot(mode = "") {
+        return this.adb.createSocketAndWait(`reboot:${mode}`);
     }
 
     public bootloader() {

package/src/commands/reverse.ts

@@ -1,18 +1,11 @@
 // cspell: ignore killforward
 
 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";
+import { BufferedReadableStream } from "@yume-chan/stream-extra";
+import Struct, { ExactReadableEndedError } from "@yume-chan/struct";
+
+import type { Adb, AdbIncomingSocketHandler } from "../adb.js";
+import { decodeUtf8, hexToNumber } from "../utils/index.js";
 
 export interface AdbForwardListener {
     deviceSerial: string;
@@ -26,48 +19,58 @@ const AdbReverseStringResponse = new Struct()
     .string("length", { length: 4 })
     .string("content", { lengthField: "length", lengthFieldRadix: 16 });
 
+export class AdbReverseError extends Error {
+    public constructor(message: string) {
+        super(message);
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+
+export class AdbReverseNotSupportedError extends AdbReverseError {
+    public constructor() {
+        super(
+            "ADB reverse tunnel is not supported on this device when connected wirelessly."
+        );
+    }
+}
+
 const AdbReverseErrorResponse = new Struct()
-    .fields(AdbReverseStringResponse)
+    .concat(AdbReverseStringResponse)
     .postDeserialize((value) => {
-        throw new Error(value.content);
+        // 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 deviceAddressToLocalAddress = new Map<string, string>();
+async function readString(stream: BufferedReadableStream, length: number) {
+    const buffer = await stream.readExactly(length);
+    return decodeUtf8(buffer);
+}
 
+export class AdbReverseCommand extends AutoDisposable {
     protected adb: Adb;
 
-    protected listening = false;
+    readonly #deviceAddressToLocalAddress = new Map<string, string>();
 
     public constructor(adb: Adb) {
         super();
 
         this.adb = adb;
-        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, "");
-        return !!(await this.localAddressToHandler.get(address)?.(socket));
-    };
-
-    private async createBufferedStream(service: string) {
+    protected async createBufferedStream(service: string) {
         const socket = await this.adb.createSocket(service);
         return new BufferedReadableStream(socket.readable);
     }
 
-    private async sendRequest(service: string) {
+    protected async sendRequest(service: string) {
         const stream = await this.createBufferedStream(service);
-        const success = decodeUtf8(await stream.read(4)) === "OKAY";
+        const success = (await readString(stream, 4)) === "OKAY";
         if (!success) {
             await AdbReverseErrorResponse.deserialize(stream);
         }
@@ -91,18 +94,12 @@ 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. It must return `true` if it accepts the connection.
+     * Add an already existing reverse tunnel. Depends on the transport type, this may not do anything.
+     * @param deviceAddress The address to be listened on device by ADB daemon. Or `tcp:0` to choose an available TCP port.
+     * @param localAddress The address that listens on the local machine.
      * @returns `tcp:{ACTUAL_LISTENING_PORT}`, If `deviceAddress` is `tcp:0`; otherwise, `deviceAddress`.
      */
-    public async add(
-        deviceAddress: string,
-        localAddress: string,
-        handler: AdbIncomingSocketHandler
-    ): Promise<string> {
-        // TODO(reverse): handle ADB bug
-        // https://issuetracker.google.com/issues/37066218
+    public async addExternal(deviceAddress: string, localAddress: string) {
         const stream = await this.sendRequest(
             `reverse:forward:${deviceAddress};${localAddress}`
         );
@@ -110,50 +107,73 @@ export class AdbReverseCommand extends AutoDisposable {
         // `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:")) {
-            let length: number | undefined;
+            const position = stream.position;
             try {
-                length = Number.parseInt(decodeUtf8(await stream.read(4)), 16);
+                const length = hexToNumber(await stream.readExactly(4));
+                const port = await readString(stream, length);
+                deviceAddress = `tcp:${Number.parseInt(port, 10)}`;
             } catch (e) {
-                if (!(e instanceof BufferedReadableStreamEndedError)) {
+                if (
+                    e instanceof ExactReadableEndedError &&
+                    stream.position === position
+                ) {
+                    // Android <8 doesn't have this response.
+                    // (the stream is closed now)
+                    // Can be safely ignored.
+                } else {
                     throw e;
                 }
-
-                // 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));
-                deviceAddress = `tcp:${Number.parseInt(port, 10)}`;
             }
         }
 
-        this.localAddressToHandler.set(localAddress, handler);
-        this.deviceAddressToLocalAddress.set(deviceAddress, localAddress);
         return deviceAddress;
+    }
 
-        // No need to close the stream, device will close it
+    /**
+     * @param deviceAddress The address to be listened on device by ADB daemon. Or `tcp:0` to choose an available TCP port.
+     * @param handler A callback to handle incoming connections.
+     * @param localAddressThe The address that listens on the local machine. May be `undefined` to let the transport choose an appropriate one.
+     * @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,
+        handler: AdbIncomingSocketHandler,
+        localAddress?: string
+    ): Promise<string> {
+        localAddress = await this.adb.transport.addReverseTunnel(
+            handler,
+            localAddress
+        );
+
+        try {
+            deviceAddress = await this.addExternal(deviceAddress, localAddress);
+            this.#deviceAddressToLocalAddress.set(deviceAddress, localAddress);
+            return deviceAddress;
+        } catch (e) {
+            await this.adb.transport.removeReverseTunnel(localAddress);
+            throw e;
+        }
     }
 
     public async remove(deviceAddress: string): Promise<void> {
-        await this.sendRequest(`reverse:killforward:${deviceAddress}`);
-
-        if (this.deviceAddressToLocalAddress.has(deviceAddress)) {
-            this.localAddressToHandler.delete(
-                this.deviceAddressToLocalAddress.get(deviceAddress)!
-            );
-            this.deviceAddressToLocalAddress.delete(deviceAddress);
+        const localAddress =
+            this.#deviceAddressToLocalAddress.get(deviceAddress);
+        if (localAddress) {
+            await this.adb.transport.removeReverseTunnel(localAddress);
         }
 
+        await this.sendRequest(`reverse:killforward:${deviceAddress}`);
+
         // No need to close the stream, device will close it
     }
 
     public async removeAll(): Promise<void> {
-        await this.sendRequest(`reverse:killforward-all`);
+        await this.adb.transport.clearReverseTunnels();
+        this.#deviceAddressToLocalAddress.clear();
 
-        this.deviceAddressToLocalAddress.clear();
-        this.localAddressToHandler.clear();
+        await this.sendRequest(`reverse:killforward-all`);
 
         // No need to close the stream, device will close it
     }

package/src/commands/subprocess/command.ts

@@ -2,11 +2,13 @@ import { DecodeUtf8Stream, GatherStringStream } from "@yume-chan/stream-extra";
 
 import { AdbCommandBase } from "../base.js";
 
+import type {
+    AdbSubprocessProtocol,
+    AdbSubprocessProtocolConstructor,
+} from "./protocols/index.js";
 import {
     AdbSubprocessNoneProtocol,
     AdbSubprocessShellProtocol,
-    type AdbSubprocessProtocol,
-    type AdbSubprocessProtocolConstructor,
 } from "./protocols/index.js";
 
 export interface AdbSubprocessOptions {
@@ -65,7 +67,10 @@ export class AdbSubprocess extends AdbCommandBase {
     }
 
     /**
-     * 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.
@@ -78,7 +83,10 @@ export class AdbSubprocess extends AdbCommandBase {
     }
 
     /**
-     * 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.

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,9 +1,8 @@
-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 { Adb, AdbSocket } from "../../../adb.js";
 
-import { type AdbSubprocessProtocol } from "./types.js";
+import type { AdbSubprocessProtocol } from "./types.js";
 
 /**
  * The legacy shell
@@ -14,54 +13,68 @@ 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;
+    readonly #socket: AdbSocket;
 
-    private readonly duplex: DuplexStreamFactory<Uint8Array, Uint8Array>;
+    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>;
+    #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: 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; }
+    #exit: Promise<number>;
+    public get exit() {
+        return this.#exit;
+    }
 
     public constructor(socket: AdbSocket) {
-        this.socket = socket;
+        this.#socket = socket;
 
         // Link `stdout`, `stderr` and `stdin` together,
         // so closing any of them will close the others.
-        this.duplex = new DuplexStreamFactory<Uint8Array, Uint8Array>({
+        this.#duplex = new DuplexStreamFactory<Uint8Array, Uint8Array>({
             close: async () => {
-                await this.socket.close();
+                await this.#socket.close();
             },
         });
 
-        this._stdout = this.duplex.wrapReadable(this.socket.readable);
-        this._stderr = this.duplex.wrapReadable(new ReadableStream());
-        this._exit = this.duplex.closed.then(() => 0);
+        this.#stdout = this.#duplex.wrapReadable(this.#socket.readable);
+        this.#stderr = this.#duplex.wrapReadable(new ReadableStream());
+        this.#exit = this.#duplex.closed.then(() => 0);
     }
 
     public resize() {
@@ -69,6 +82,6 @@ export class AdbSubprocessNoneProtocol implements AdbSubprocessProtocol {
     }
 
     public kill() {
-        return this.duplex.close();
+        return this.#duplex.close();
     }
 }