@yume-chan/adb 0.0.19 → 0.0.20

package/src/commands/reverse.ts

@@ -1,15 +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 { BufferedReadableStream } from "@yume-chan/stream-extra";
+import Struct, { ExactReadableEndedError } 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, AdbIncomingSocketHandler } from "../adb.js";
+import { decodeUtf8, hexToNumber } from "../utils/index.js";
 
 export interface AdbForwardListener {
     deviceSerial: string;
@@ -26,21 +22,20 @@ const AdbReverseStringResponse = new Struct()
 export class AdbReverseError extends Error {
     public constructor(message: string) {
         super(message);
-        Object.setPrototypeOf(this, AdbReverseError.prototype);
+        Object.setPrototypeOf(this, new.target.prototype);
     }
 }
 
-export class AdbReverseNotSupportedError extends Error {
+export class AdbReverseNotSupportedError extends AdbReverseError {
     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)
+    .concat(AdbReverseStringResponse)
     .postDeserialize((value) => {
         // https://issuetracker.google.com/issues/37066218
         // ADB on Android <9 can't create reverse tunnels when connected wirelessly (ADB over WiFi),
@@ -52,42 +47,30 @@ const AdbReverseErrorResponse = new Struct()
         }
     });
 
-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);
         }
@@ -111,23 +94,12 @@ export class AdbReverseCommand extends AutoDisposable {
     }
 
     /**
-     * @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.
+     * 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`.
-     * @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
-    ): Promise<string> {
+    public async addExternal(deviceAddress: string, localAddress: string) {
         const stream = await this.sendRequest(
             `reverse:forward:${deviceAddress};${localAddress}`
         );
@@ -135,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/protocols/none.ts

@@ -1,7 +1,6 @@
 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";
 
@@ -32,50 +31,50 @@ export class AdbSubprocessNoneProtocol implements AdbSubprocessProtocol {
         );
     }
 
-    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;
+        return this.#socket.writable;
     }
 
-    private _stdout: ReadableStream<Uint8Array>;
+    #stdout: ReadableStream<Uint8Array>;
     /**
      * Legacy shell mixes stdout and stderr.
      */
     public get stdout() {
-        return this._stdout;
+        return this.#stdout;
     }
 
-    private _stderr: ReadableStream<Uint8Array>;
+    #stderr: ReadableStream<Uint8Array>;
     /**
      * `stderr` will always be empty.
      */
     public get stderr() {
-        return this._stderr;
+        return this.#stderr;
     }
 
-    private _exit: Promise<number>;
+    #exit: Promise<number>;
     public get exit() {
-        return this._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() {
@@ -83,6 +82,6 @@ export class AdbSubprocessNoneProtocol implements AdbSubprocessProtocol {
     }
 
     public kill() {
-        return this.duplex.close();
+        return this.#duplex.close();
     }
 }

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

@@ -10,16 +10,14 @@ import {
     ConsumableWritableStream,
     PushReadableStream,
     StructDeserializeStream,
-    TransformStream,
     WritableStream,
     pipeFrom,
 } from "@yume-chan/stream-extra";
 import type { StructValueType } from "@yume-chan/struct";
 import Struct, { placeholder } from "@yume-chan/struct";
 
-import type { Adb } from "../../../adb.js";
+import type { Adb, AdbSocket } from "../../../adb.js";
 import { AdbFeature } from "../../../features.js";
-import type { AdbSocket } from "../../../socket/index.js";
 import { encodeUtf8 } from "../../../utils/index.js";
 
 import type { AdbSubprocessProtocol } from "./types.js";
@@ -62,21 +60,6 @@ class StdinSerializeStream extends ConsumableTransformStream<
     }
 }
 
-class StdoutDeserializeStream extends TransformStream<
-    AdbShellProtocolPacket,
-    Uint8Array
-> {
-    constructor(type: AdbShellProtocolId.Stdout | AdbShellProtocolId.Stderr) {
-        super({
-            transform(chunk, controller) {
-                if (chunk.id === type) {
-                    controller.enqueue(chunk.data);
-                }
-            },
-        });
-    }
-}
-
 class MultiplexStream<T> {
     private _readable: PushReadableStream<T>;
     private _readableController!: PushReadableStreamController<T>;
@@ -142,67 +125,82 @@ export class AdbSubprocessShellProtocol implements AdbSubprocessProtocol {
         );
     }
 
-    private readonly _socket: AdbSocket;
-    private _socketWriter: WritableStreamDefaultWriter<
+    readonly #socket: AdbSocket;
+    #socketWriter: WritableStreamDefaultWriter<
         Consumable<AdbShellProtocolPacketInit>
     >;
 
-    private _stdin: WritableStream<Consumable<Uint8Array>>;
+    #stdin: WritableStream<Consumable<Uint8Array>>;
     public get stdin() {
-        return this._stdin;
+        return this.#stdin;
     }
 
-    private _stdout: ReadableStream<Uint8Array>;
+    #stdout: ReadableStream<Uint8Array>;
     public get stdout() {
-        return this._stdout;
+        return this.#stdout;
     }
 
-    private _stderr: ReadableStream<Uint8Array>;
+    #stderr: ReadableStream<Uint8Array>;
     public get stderr() {
-        return this._stderr;
+        return this.#stderr;
     }
 
-    private readonly _exit = new PromiseResolver<number>();
+    readonly #exit = new PromiseResolver<number>();
     public get exit() {
-        return this._exit.promise;
+        return this.#exit.promise;
     }
 
     public constructor(socket: AdbSocket) {
-        this._socket = socket;
+        this.#socket = socket;
 
         // Check this image to help you understand the stream graph
         // cspell: disable-next-line
         // https://www.plantuml.com/plantuml/png/bL91QiCm4Bpx5SAdv90lb1JISmiw5XzaQKf5PIkiLZIqzEyLSg8ks13gYtOykpFhiOw93N6UGjVDqK7rZsxKqNw0U_NTgVAy4empOy2mm4_olC0VEVEE47GUpnGjKdgXoD76q4GIEpyFhOwP_m28hW0NNzxNUig1_JdW0bA7muFIJDco1daJ_1SAX9bgvoPJPyIkSekhNYctvIGXrCH6tIsPL5fs-s6J5yc9BpWXhKtNdF2LgVYPGM_6GlMwfhWUsIt4lbScANrwlgVVUifPSVi__t44qStnwPvZwobdSmHHlL57p2vFuHS0
 
-        // TODO: AdbShellSubprocessProtocol: Optimize stream graph
+        let stdoutController!: PushReadableStreamController<Uint8Array>;
+        let stderrController!: PushReadableStreamController<Uint8Array>;
+        this.#stdout = new PushReadableStream<Uint8Array>((controller) => {
+            stdoutController = controller;
+        });
+        this.#stderr = new PushReadableStream<Uint8Array>((controller) => {
+            stderrController = controller;
+        });
 
-        const [stdout, stderr] = socket.readable
+        socket.readable
             .pipeThrough(new StructDeserializeStream(AdbShellProtocolPacket))
-            .pipeThrough(
-                new TransformStream<
-                    AdbShellProtocolPacket,
-                    AdbShellProtocolPacket
-                >({
-                    transform: (chunk, controller) => {
-                        if (chunk.id === AdbShellProtocolId.Exit) {
-                            this._exit.resolve(new Uint8Array(chunk.data)[0]!);
-                            // We can let `StdoutDeserializeStream` to process `AdbShellProtocolId.Exit`,
-                            // but since we need this `TransformStream` to capture the exit code anyway,
-                            // terminating child streams here is killing two birds with one stone.
-                            controller.terminate();
-                            return;
+            .pipeTo(
+                new WritableStream<AdbShellProtocolPacket>({
+                    write: async (chunk) => {
+                        switch (chunk.id) {
+                            case AdbShellProtocolId.Exit:
+                                this.#exit.resolve(chunk.data[0]!);
+                                break;
+                            case AdbShellProtocolId.Stdout:
+                                await stdoutController.enqueue(chunk.data);
+                                break;
+                            case AdbShellProtocolId.Stderr:
+                                await stderrController.enqueue(chunk.data);
+                                break;
                         }
-                        controller.enqueue(chunk);
                     },
                 })
             )
-            .tee();
-        this._stdout = stdout.pipeThrough(
-            new StdoutDeserializeStream(AdbShellProtocolId.Stdout)
-        );
-        this._stderr = stderr.pipeThrough(
-            new StdoutDeserializeStream(AdbShellProtocolId.Stderr)
-        );
+            .then(
+                () => {
+                    stdoutController.close();
+                    stderrController.close();
+                    // If `#exit` has already resolved, this will be a no-op
+                    this.#exit.reject(
+                        new Error("Socket ended without exit message")
+                    );
+                },
+                (e) => {
+                    stdoutController.error(e);
+                    stderrController.error(e);
+                    // If `#exit` has already resolved, this will be a no-op
+                    this.#exit.reject(e);
+                }
+            );
 
         const multiplexer = new MultiplexStream<
             Consumable<AdbShellProtocolPacketInit>
@@ -219,16 +217,16 @@ export class AdbSubprocessShellProtocol implements AdbSubprocessProtocol {
             )
             .pipeTo(socket.writable);
 
-        this._stdin = pipeFrom(
+        this.#stdin = pipeFrom(
             multiplexer.createWriteable(),
             new StdinSerializeStream()
         );
 
-        this._socketWriter = multiplexer.createWriteable().getWriter();
+        this.#socketWriter = multiplexer.createWriteable().getWriter();
     }
 
     public async resize(rows: number, cols: number) {
-        await ConsumableWritableStream.write(this._socketWriter, {
+        await ConsumableWritableStream.write(this.#socketWriter, {
             id: AdbShellProtocolId.WindowSizeChange,
             data: encodeUtf8(
                 // The "correct" format is `${rows}x${cols},${x_pixels}x${y_pixels}`
@@ -240,6 +238,6 @@ export class AdbSubprocessShellProtocol implements AdbSubprocessProtocol {
     }
 
     public kill() {
-        return this._socket.close();
+        return this.#socket.close();
     }
 }

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

@@ -5,8 +5,7 @@ import type {
 } from "@yume-chan/stream-extra";
 import type { ValueOrPromise } from "@yume-chan/struct";
 
-import type { Adb } from "../../../adb.js";
-import type { AdbSocket } from "../../../socket/index.js";
+import type { Adb, AdbSocket } from "../../../adb.js";
 
 export interface AdbSubprocessProtocol {
     /**

package/src/commands/sync/list.ts

@@ -11,7 +11,7 @@ export interface AdbSyncEntry extends AdbSyncStat {
 }
 
 export const AdbSyncEntryResponse = new Struct({ littleEndian: true })
-    .fields(AdbSyncLstatResponse)
+    .concat(AdbSyncLstatResponse)
     .uint32("nameLength")
     .string("name", { lengthField: "nameLength" })
     .extra({ id: AdbSyncResponseId.Entry as const });
@@ -20,7 +20,7 @@ export type AdbSyncEntryResponse =
     (typeof AdbSyncEntryResponse)["TDeserializeResult"];
 
 export const AdbSyncEntry2Response = new Struct({ littleEndian: true })
-    .fields(AdbSyncStatResponse)
+    .concat(AdbSyncStatResponse)
     .uint32("nameLength")
     .string("name", { lengthField: "nameLength" })
     .extra({ id: AdbSyncResponseId.Entry2 as const });

package/src/commands/sync/push.ts

@@ -6,22 +6,21 @@ import {
 } from "@yume-chan/stream-extra";
 import Struct, { placeholder } from "@yume-chan/struct";
 
+import { NOOP } from "../../utils/index.js";
+
 import { AdbSyncRequestId, adbSyncWriteRequest } from "./request.js";
 import { AdbSyncResponseId, adbSyncReadResponse } from "./response.js";
 import type { AdbSyncSocket, AdbSyncSocketLocked } from "./socket.js";
 import { LinuxFileType } from "./stat.js";
 
-const NOOP = () => {
-    // no-op
-};
-
 export const ADB_SYNC_MAX_PACKET_SIZE = 64 * 1024;
 
 export interface AdbSyncPushV1Options {
     socket: AdbSyncSocket;
     filename: string;
     file: ReadableStream<Consumable<Uint8Array>>;
-    mode?: number;
+    type?: LinuxFileType;
+    permission?: number;
     mtime?: number;
     packetSize?: number;
 }
@@ -30,7 +29,7 @@ export const AdbSyncOkResponse = new Struct({ littleEndian: true }).uint32(
     "unused"
 );
 
-async function pipeFile(
+async function pipeFileData(
     locked: AdbSyncSocketLocked,
     file: ReadableStream<Consumable<Uint8Array>>,
     packetSize: number,
@@ -71,15 +70,17 @@ export async function adbSyncPushV1({
     socket,
     filename,
     file,
-    mode = (LinuxFileType.File << 12) | 0o666,
+    type = LinuxFileType.File,
+    permission = 0o666,
     mtime = (Date.now() / 1000) | 0,
     packetSize = ADB_SYNC_MAX_PACKET_SIZE,
 }: AdbSyncPushV1Options) {
     const locked = await socket.lock();
     try {
+        const mode = (type << 12) | permission;
         const pathAndMode = `${filename},${mode.toString()}`;
         await adbSyncWriteRequest(locked, AdbSyncRequestId.Send, pathAndMode);
-        await pipeFile(locked, file, packetSize, mtime);
+        await pipeFileData(locked, file, packetSize, mtime);
     } finally {
         locked.release();
     }
@@ -103,6 +104,12 @@ export enum AdbSyncSendV2Flags {
 }
 
 export interface AdbSyncPushV2Options extends AdbSyncPushV1Options {
+    /**
+     * Don't write the file to disk. Requires the `sendrecv_v2` feature.
+     *
+     * It was used during ADB development to benchmark the performance of
+     * compression algorithms.
+     */
     dryRun?: boolean;
 }
 
@@ -115,7 +122,8 @@ export async function adbSyncPushV2({
     socket,
     filename,
     file,
-    mode = (LinuxFileType.File << 12) | 0o666,
+    type = LinuxFileType.File,
+    permission = 0o666,
     mtime = (Date.now() / 1000) | 0,
     packetSize = ADB_SYNC_MAX_PACKET_SIZE,
     dryRun = false,
@@ -124,6 +132,7 @@ export async function adbSyncPushV2({
     try {
         await adbSyncWriteRequest(locked, AdbSyncRequestId.SendV2, filename);
 
+        const mode = (type << 12) | permission;
         let flags: AdbSyncSendV2Flags = AdbSyncSendV2Flags.None;
         if (dryRun) {
             flags |= AdbSyncSendV2Flags.DryRun;
@@ -136,13 +145,16 @@ export async function adbSyncPushV2({
             })
         );
 
-        await pipeFile(locked, file, packetSize, mtime);
+        await pipeFileData(locked, file, packetSize, mtime);
     } finally {
         locked.release();
     }
 }
 
 export interface AdbSyncPushOptions extends AdbSyncPushV2Options {
+    /**
+     * Whether to use the v2 protocol. Requires the `sendrecv_v2` feature.
+     */
     v2: boolean;
 }
 

package/src/commands/sync/request.ts

@@ -20,7 +20,7 @@ export const AdbSyncNumberRequest = new Struct({ littleEndian: true })
     .uint32("arg");
 
 export const AdbSyncDataRequest = new Struct({ littleEndian: true })
-    .fields(AdbSyncNumberRequest)
+    .concat(AdbSyncNumberRequest)
     .uint8Array("data", { lengthField: "arg" });
 
 export interface AdbSyncWritable {