@yume-chan/adb 2.6.2 → 3.0.0-beta.1

package/src/service/sync/service.ts

@@ -0,0 +1,255 @@
+import type {
+    AbortSignal,
+    MaybeConsumable,
+    ReadableStream,
+} from "@yume-chan/stream-extra";
+
+import type { Adb } from "../../adb.js";
+import { AdbFeature } from "../../features.js";
+import { escapeArg } from "../subprocess/index.js";
+
+import type { LinuxFileType } from "./android.js";
+import { Compression } from "./compression/index.js";
+import { OpenDir, Receive, Send, Stat } from "./request/index.js";
+import { SocketPool } from "./socket-pool.js";
+import type { Socket } from "./socket.js";
+import { Error as AdbSyncError } from "./socket.js";
+
+export interface ServiceOptions {
+    /**
+     * Maximum number of sockets to keep in the pool for reuse.
+     * Extra sockets beyond this limit will be closed when released.
+     * @default 4
+     */
+    maxPoolSize?: number | undefined;
+
+    /**
+     * Time in milliseconds to keep idle sockets in the pool before closing them.
+     * Set to 0 to disable idle timeout (sockets will remain until pool is disposed).
+     * @default 60000 (1 minute)
+     */
+    idleTimeout?: number | undefined;
+
+    /**
+     * Abort signal to dispose the socket pool when aborted.
+     */
+    signal?: AbortSignal | undefined;
+}
+
+/**
+ * A simplified `dirname` function that only handles absolute unix paths.
+ * @param path an absolute unix path
+ * @returns the directory name of the input path
+ */
+export function dirname(path: string): string {
+    const end = path.lastIndexOf("/");
+    if (end === -1) {
+        throw new Error(`Invalid absolute unix path: ${path}`);
+    }
+    if (end === 0) {
+        return "/";
+    }
+    return path.substring(0, end);
+}
+
+export interface WriteOptions {
+    filename: string;
+    file: ReadableStream<MaybeConsumable<Uint8Array>>;
+    type?: LinuxFileType | undefined;
+    permission?: number | undefined;
+    mtime?: number | undefined;
+    /**
+     * The format to compress the file stream for sending.
+     *
+     * If the device doesn't support compressed sending, it will be ignored.
+     *
+     * If the device or current runtime doesn't support the specified format,
+     * an Error will be thrown.
+     * {@link Compression.canUseFormat} can be used to check if
+     * the device and current runtime both supports the format.
+     */
+    compression?: Compression.Format | undefined;
+    dryRun?: boolean | undefined;
+}
+
+export class Service {
+    protected _adb: Adb;
+    readonly #socketPool: SocketPool;
+
+    readonly #supportsStat2: boolean;
+    readonly #supportsLs2: boolean;
+    readonly #fixedPushMkdir: boolean;
+    readonly #supportsSendReceive2: boolean;
+    readonly #needPushMkdirWorkaround: boolean;
+
+    get supportsStat2(): boolean {
+        return this.#supportsStat2;
+    }
+
+    get supportsLs2(): boolean {
+        return this.#supportsLs2;
+    }
+
+    get fixedPushMkdir(): boolean {
+        return this.#fixedPushMkdir;
+    }
+
+    get supportsSendReceive2(): boolean {
+        return this.#supportsSendReceive2;
+    }
+
+    get needPushMkdirWorkaround(): boolean {
+        return this.#needPushMkdirWorkaround;
+    }
+
+    constructor(adb: Adb, options?: ServiceOptions) {
+        this._adb = adb;
+        this.#socketPool = new SocketPool(
+            adb,
+            options?.maxPoolSize,
+            options?.idleTimeout,
+        );
+
+        // Dispose the socket pool when the abort signal is triggered
+        options?.signal?.addEventListener("abort", () => {
+            void this.#socketPool.dispose();
+        });
+
+        this.#supportsStat2 = adb.canUseFeature(AdbFeature.Stat2);
+        this.#supportsLs2 = adb.canUseFeature(AdbFeature.Ls2);
+        this.#fixedPushMkdir = adb.canUseFeature(AdbFeature.FixedPushMkdir);
+        this.#supportsSendReceive2 = adb.canUseFeature(AdbFeature.SendReceive2);
+        // https://android.googlesource.com/platform/packages/modules/adb/+/91768a57b7138166e0a3d11f79cd55909dda7014/client/file_sync_client.cpp#1361
+        this.#needPushMkdirWorkaround =
+            this._adb.canUseFeature(AdbFeature.Shell2) && !this.fixedPushMkdir;
+    }
+
+    /**
+     * Acquires a socket from the pool for direct use.
+     *
+     * The socket must be returned to the pool using {@link releaseSocket} after use.
+     *
+     * @returns A socket from the pool
+     */
+    async acquireSocket() {
+        return await this.#socketPool.acquire();
+    }
+
+    /**
+     * Returns a socket to the pool after use.
+     *
+     * @param socket The socket to return to the pool
+     * @param discard Whether to discard the socket instead of returning it to the pool
+     */
+    async releaseSocket(socket: Socket, discard = false) {
+        await this.#socketPool.release(socket, discard);
+    }
+
+    /**
+     * Gets information of a file or folder.
+     *
+     * If `path` points to a symbolic link, the returned information is about the link itself (with `type` being `LinuxFileType.Link`).
+     */
+    lstat(path: string): Promise<Stat.Stat> {
+        return Stat.lstat(this.#socketPool, path, {
+            version: this.#supportsStat2 ? 2 : 1,
+        });
+    }
+
+    /**
+     * Gets the information of a file or folder.
+     *
+     * If `path` points to a symbolic link, it will be resolved and the returned information is about the target (with `type` being `LinuxFileType.File` or `LinuxFileType.Directory`).
+     */
+    stat(path: string) {
+        if (!this.#supportsStat2) {
+            throw new Error("Not supported");
+        }
+
+        return Stat.stat(this.#socketPool, path);
+    }
+
+    /**
+     * Checks if `path` is a directory, or a symbolic link to a directory.
+     *
+     * This uses `lstat` internally, thus works on all Android versions.
+     */
+    async isDirectory(path: string): Promise<boolean> {
+        try {
+            await this.lstat(path + "/");
+            return true;
+        } catch (e) {
+            if (e instanceof AdbSyncError) {
+                return false;
+            } else {
+                throw e;
+            }
+        }
+    }
+
+    opendir(path: string): AsyncGenerator<OpenDir.Entry, void, void> {
+        return OpenDir.opendir(this.#socketPool, path, {
+            version: this.supportsLs2 ? 2 : 1,
+        });
+    }
+
+    async readdir(path: string) {
+        // TODO: Convert to `Array.fromAsync`
+        const results: OpenDir.Entry[] = [];
+        for await (const entry of this.opendir(path)) {
+            results.push(entry);
+        }
+        return results;
+    }
+
+    /**
+     * Reads the content of a file on device.
+     *
+     * @param filename The full path of the file on device to read.
+     * @returns A `ReadableStream` that contains the file content.
+     */
+    read(filename: string): ReadableStream<Uint8Array> {
+        return Receive.stream(this.#socketPool, filename);
+    }
+
+    /**
+     * Writes a file on device. If the file name already exists, it will be overwritten.
+     *
+     * @param options The content and options of the file to write.
+     */
+    async write(options: WriteOptions): Promise<void> {
+        if (this.needPushMkdirWorkaround) {
+            // It may fail if `filename` already exists.
+            // Ignore the result.
+            // TODO: sync: test push mkdir workaround (need an Android 8 device)
+            await this._adb.subprocess.noneProtocol
+                .spawn(["mkdir", "-p", escapeArg(dirname(options.filename))])
+                .wait();
+        }
+
+        if (this.supportsSendReceive2) {
+            if (options.compression === undefined) {
+                options.compression = Compression.chooseFormat(
+                    this._adb,
+                    Compression.Mode.Compress,
+                );
+            } else if (
+                !Compression.canUseFormat(
+                    this._adb,
+                    options.compression,
+                    Compression.Mode.Compress,
+                )
+            ) {
+                throw new Error(
+                    `Compression type ${options.compression} is not supported`,
+                );
+            }
+        }
+
+        await Send.send({
+            version: this.supportsSendReceive2 ? 2 : 1,
+            pool: this.#socketPool,
+            ...options,
+        });
+    }
+}

package/src/service/sync/socket-pool.ts

@@ -0,0 +1,97 @@
+import type { Adb } from "../../adb.js";
+
+import { Error as AdbSyncError, Socket } from "./socket.js";
+
+export class SocketPool {
+    readonly #adb: Adb;
+    readonly #maxSize: number;
+    readonly #idleTimeout: number;
+    readonly #availableSockets: Socket[] = [];
+    readonly #inUseSockets = new Set<Socket>();
+    #closed = false;
+
+    constructor(adb: Adb, maxSize = 4, idleTimeout = 60000) {
+        this.#adb = adb;
+        this.#maxSize = maxSize;
+        this.#idleTimeout = idleTimeout;
+    }
+
+    async acquire(): Promise<Socket> {
+        if (this.#closed) {
+            throw new Error("SocketPool is closed");
+        }
+        // Try to reuse an available socket
+        if (this.#availableSockets.length > 0) {
+            const socket = this.#availableSockets.pop()!;
+            // Clear the idle timeout
+            socket.clearIdleTimer();
+            this.#inUseSockets.add(socket);
+            return socket;
+        }
+
+        // Create a new socket
+        const adbSocket = await this.#adb.createSocket("sync:");
+        if (this.#closed) {
+            await adbSocket.close();
+            throw new Error("SocketPool is closed");
+        }
+        const socket = new Socket(adbSocket, this.#adb.maxPayloadSize);
+        this.#inUseSockets.add(socket);
+        return socket;
+    }
+
+    async withSocket<T>(fn: (socket: Socket) => Promise<T>): Promise<T> {
+        const socket = await this.acquire();
+        try {
+            const result = await fn(socket);
+            await this.release(socket);
+            return result;
+        } catch (e) {
+            await this.release(socket, !(e instanceof AdbSyncError));
+            throw e;
+        }
+    }
+
+    async release(socket: Socket, discard = false): Promise<void> {
+        this.#inUseSockets.delete(socket);
+
+        // If discarding or we already have enough sockets in the pool, close this socket
+        if (discard || this.#availableSockets.length >= this.#maxSize) {
+            await socket.close();
+            return;
+        }
+
+        // Otherwise, return it to the pool and start idle timeout
+        socket.startIdleTimer(this.#idleTimeout, () => {
+            this.#closeIdleSocket(socket);
+        });
+        this.#availableSockets.push(socket);
+    }
+
+    #closeIdleSocket(socket: Socket): void {
+        // Remove from available sockets
+        const index = this.#availableSockets.indexOf(socket);
+        if (index !== -1) {
+            this.#availableSockets.splice(index, 1);
+            void socket.close();
+        }
+    }
+
+    async dispose(): Promise<void> {
+        this.#closed = true;
+
+        // Close all available sockets
+        const closePromises = this.#availableSockets.map((socket) =>
+            socket.close(),
+        );
+        this.#availableSockets.length = 0;
+
+        // Force close all in-use sockets immediately
+        const inUseClosePromises = Array.from(this.#inUseSockets).map(
+            (socket) => socket.close(),
+        );
+        this.#inUseSockets.clear();
+
+        await Promise.all([...closePromises, ...inUseClosePromises]);
+    }
+}

package/src/service/sync/socket.ts

@@ -0,0 +1,201 @@
+import { getUint32LittleEndian } from "@yume-chan/no-data-view";
+import type {
+    MaybeConsumable,
+    WritableStreamDefaultWriter,
+} from "@yume-chan/stream-extra";
+import {
+    BufferCombiner,
+    BufferedReadableStream,
+    clearTimeout,
+    Consumable,
+    setTimeout,
+    tryCancel,
+} from "@yume-chan/stream-extra";
+import type { AsyncExactReadable, StructDeserializer } from "@yume-chan/struct";
+import { decodeUtf8, string, struct, u32 } from "@yume-chan/struct";
+
+import type { Adb } from "../../adb.js";
+import { AutoResetEvent, encodeUtf8, unreachable } from "../../utils/index.js";
+
+import { ResponseId } from "./id/index.js";
+
+const NumberRequest = struct({ id: u32, arg: u32 }, { littleEndian: true });
+
+class AdbSyncError extends Error {}
+export { AdbSyncError as Error };
+
+const FailResponse = struct(
+    { message: string(u32) },
+    {
+        littleEndian: true,
+        postDeserialize(value) {
+            throw new AdbSyncError(value.message);
+        },
+    },
+);
+
+function i32ToHex(i: number) {
+    return "0x" + i.toString(16).padStart(8, "0");
+}
+
+export class Socket implements AsyncExactReadable {
+    static readonly NumberRequest = NumberRequest;
+    static readonly FailResponse = FailResponse;
+
+    readonly #socket: Adb.Socket;
+    readonly #writer: WritableStreamDefaultWriter<MaybeConsumable<Uint8Array>>;
+    readonly #readable: BufferedReadableStream;
+    readonly #writeLock = new AutoResetEvent();
+    readonly #combiner: BufferCombiner;
+    #idleTimeoutId: ReturnType<typeof setTimeout> | null = null;
+
+    get position() {
+        return this.#readable.position;
+    }
+
+    get closed(): Promise<undefined> {
+        return this.#socket.closed;
+    }
+
+    constructor(socket: Adb.Socket, bufferSize: number) {
+        this.#socket = socket;
+        this.#writer = socket.writable.getWriter();
+        this.#readable = new BufferedReadableStream(socket.readable);
+        this.#combiner = new BufferCombiner(bufferSize);
+    }
+
+    /**
+     * Start an idle timer that will close the socket after the specified duration.
+     * The timer is automatically cancelled when the socket is used.
+     * @param timeout The timeout in milliseconds
+     * @param callback The callback to invoke when the timeout expires
+     */
+    startIdleTimer(timeout: number, callback: () => void) {
+        this.clearIdleTimer();
+        this.#idleTimeoutId = setTimeout(callback, timeout);
+    }
+
+    /**
+     * Clear the idle timer.
+     */
+    clearIdleTimer() {
+        if (this.#idleTimeoutId !== null) {
+            clearTimeout(this.#idleTimeoutId);
+            this.#idleTimeoutId = null;
+        }
+    }
+
+    /**
+     * Write a packet to the socket.
+     * @param packet The packet to write. Must be smaller than the buffer size.
+     */
+    #writeOne(packet: Uint8Array) {
+        // `#combiner` will reuse the buffer, so we need to use the Consumable pattern
+        return Consumable.WritableStream.write(this.#writer, packet);
+    }
+
+    async #withWriteLock(callback: () => Promise<void>) {
+        try {
+            await this.#writeLock.wait();
+            await callback();
+        } finally {
+            this.#writeLock.notifyOne();
+        }
+    }
+
+    async flush() {
+        const buffer = this.#combiner.flush();
+        if (buffer) {
+            await this.#withWriteLock(() => this.#writeOne(buffer));
+        }
+    }
+
+    async #write(data: Uint8Array) {
+        for (const buffer of this.#combiner.push(data)) {
+            await this.#writeOne(buffer);
+        }
+    }
+
+    write(data: Uint8Array) {
+        return this.#withWriteLock(() => this.#write(data));
+    }
+
+    async writeRequest(id: number, value: number | string | Uint8Array) {
+        return this.#withWriteLock(async () => {
+            if (typeof value === "number") {
+                await this.#write(NumberRequest.serialize({ id, arg: value }));
+                return;
+            }
+
+            if (typeof value === "string") {
+                value = encodeUtf8(value);
+            }
+
+            await this.#write(
+                NumberRequest.serialize({ id, arg: value.length }),
+            );
+            await this.#write(value);
+        });
+    }
+
+    async readExactly(length: number) {
+        // The request may still be in the internal buffer.
+        // Call `flush` to send it before starting reading
+        await this.flush();
+        return await this.#readable.readExactly(length);
+    }
+
+    async readResponse<T>(id: number, type: StructDeserializer<T>) {
+        const buffer = await this.readExactly(4);
+        switch (getUint32LittleEndian(buffer, 0)) {
+            case ResponseId.Fail:
+                await FailResponse.deserialize(this.#readable);
+                unreachable();
+            case id:
+                return await type.deserialize(this.#readable);
+            default:
+                // non-recoverable
+                throw new Error(
+                    `Expected '${id}', but got '${decodeUtf8(buffer)}'`,
+                );
+        }
+    }
+
+    async *readResponses<T>(
+        expectedId: number,
+        type: StructDeserializer<T>,
+    ): AsyncGenerator<T, void, void> {
+        await this.flush();
+
+        while (true) {
+            const buffer = await this.#readable.readExactly(4);
+            const actualId = getUint32LittleEndian(buffer, 0);
+            switch (actualId) {
+                case ResponseId.Fail:
+                    await FailResponse.deserialize(this.#readable);
+                    unreachable();
+                case ResponseId.Done:
+                    // `DONE` responses' size are always same as the request's normal response.
+                    //
+                    // For example, `DONE` responses for `LIST` requests are 16 bytes (same as `DENT` responses),
+                    // but `DONE` responses for `STAT` requests are 12 bytes (same as `STAT` responses).
+                    await this.#readable.readExactly(type.size);
+                    return;
+                case expectedId:
+                    yield await type.deserialize(this.#readable);
+                    break;
+                default:
+                    // non-recoverable
+                    throw new Error(
+                        `Expected ${i32ToHex(expectedId)} or ${i32ToHex(ResponseId.Done)}, but got ${i32ToHex(actualId)}`,
+                    );
+            }
+        }
+    }
+
+    async close() {
+        this.clearIdleTimer();
+        await tryCancel(this.#readable);
+        await this.#socket.close();
+    }
+}

package/src/{commands → service}/tcpip.ts

@@ -1,4 +1,4 @@
-import { AdbServiceBase } from "./base.js";
+import type { Adb } from "../adb.js";
 
 /**
  * ADB daemon checks for the following properties in the order of
@@ -27,13 +27,19 @@ function parsePort(value: string): number | undefined {
     return Number.parseInt(value, 10);
 }
 
-export class AdbTcpIpService extends AdbServiceBase {
+export class AdbTcpIpService {
+    readonly #adb: Adb;
+
+    constructor(adb: Adb) {
+        this.#adb = adb;
+    }
+
     async getListenAddresses(): Promise<AdbTcpIpListenAddresses> {
-        const serviceListenAddresses = await this.adb.getProp(
+        const serviceListenAddresses = await this.#adb.getProp(
             "service.adb.listen_addrs",
         );
-        const servicePort = await this.adb.getProp("service.adb.tcp.port");
-        const persistPort = await this.adb.getProp("persist.adb.tcp.port");
+        const servicePort = await this.#adb.getProp("service.adb.tcp.port");
+        const persistPort = await this.#adb.getProp("persist.adb.tcp.port");
 
         return {
             serviceListenAddresses:
@@ -50,7 +56,7 @@ export class AdbTcpIpService extends AdbServiceBase {
             throw new TypeError(`Invalid port ${port}`);
         }
 
-        const output = await this.adb.createSocketAndWait(`tcpip:${port}`);
+        const output = await this.#adb.createSocketAndWait(`tcpip:${port}`);
         if (output !== `restarting in TCP mode port: ${port}\n`) {
             throw new Error(output);
         }
@@ -58,7 +64,7 @@ export class AdbTcpIpService extends AdbServiceBase {
     }
 
     async disable(): Promise<string> {
-        const output = await this.adb.createSocketAndWait("usb:");
+        const output = await this.#adb.createSocketAndWait("usb:");
         if (output !== "restarting in USB mode\n") {
             throw new Error(output);
         }

package/src/utils/array-buffer.ts

@@ -3,7 +3,6 @@ export function toLocalUint8Array(value: Uint8Array): Uint8Array<ArrayBuffer> {
         return value as Uint8Array<ArrayBuffer>;
     }
 
-    const copy = new Uint8Array(value.length);
-    copy.set(value);
-    return copy;
+    // This invokes the `constructor(Iterable<number>)` overload and copies the data
+    return new Uint8Array(value);
 }

package/src/utils/base64.ts

@@ -293,7 +293,20 @@ function encodeBackward(
     }
 }
 
+function getCharIndex(input: string, offset: number) {
+    const charCode = input.charCodeAt(offset);
+    const index = charToIndex[charCode];
+    if (index === undefined) {
+        throw new Error("Invalid Base64 character: " + input[offset]);
+    }
+    return index;
+}
+
 export function decodeBase64(input: string): Uint8Array<ArrayBuffer> {
+    if (input.length % 4 !== 0) {
+        throw new Error("Invalid Base64 length: " + input.length);
+    }
+
     let padding: number;
     if (input[input.length - 2] === "=") {
         padding = 2;
@@ -307,17 +320,18 @@ export function decodeBase64(input: string): Uint8Array<ArrayBuffer> {
     let sIndex = 0;
     let dIndex = 0;
 
-    while (sIndex < input.length - (padding !== 0 ? 4 : 0)) {
-        const a = charToIndex[input.charCodeAt(sIndex)]!;
+    const loopEnd = input.length - (padding !== 0 ? 4 : 0);
+    while (sIndex < loopEnd) {
+        const a = getCharIndex(input, sIndex);
         sIndex += 1;
 
-        const b = charToIndex[input.charCodeAt(sIndex)]!;
+        const b = getCharIndex(input, sIndex);
         sIndex += 1;
 
-        const c = charToIndex[input.charCodeAt(sIndex)]!;
+        const c = getCharIndex(input, sIndex);
         sIndex += 1;
 
-        const d = charToIndex[input.charCodeAt(sIndex)]!;
+        const d = getCharIndex(input, sIndex);
         sIndex += 1;
 
         result[dIndex] = (a << 2) | ((b & 0b11_0000) >> 4);
@@ -331,23 +345,23 @@ export function decodeBase64(input: string): Uint8Array<ArrayBuffer> {
     }
 
     if (padding === 1) {
-        const a = charToIndex[input.charCodeAt(sIndex)]!;
+        const a = getCharIndex(input, sIndex);
         sIndex += 1;
 
-        const b = charToIndex[input.charCodeAt(sIndex)]!;
+        const b = getCharIndex(input, sIndex);
         sIndex += 1;
 
-        const c = charToIndex[input.charCodeAt(sIndex)]!;
+        const c = getCharIndex(input, sIndex);
 
         result[dIndex] = (a << 2) | ((b & 0b11_0000) >> 4);
         dIndex += 1;
 
         result[dIndex] = ((b & 0b1111) << 4) | ((c & 0b11_1100) >> 2);
     } else if (padding === 2) {
-        const a = charToIndex[input.charCodeAt(sIndex)]!;
+        const a = getCharIndex(input, sIndex);
         sIndex += 1;
 
-        const b = charToIndex[input.charCodeAt(sIndex)]!;
+        const b = getCharIndex(input, sIndex);
 
         result[dIndex] = (a << 2) | ((b & 0b11_0000) >> 4);
     }

package/src/utils/index.ts

@@ -3,6 +3,7 @@ export * from "./array-buffer.js";
 export * from "./auto-reset-event.js";
 export * from "./base64.js";
 export * from "./hex.js";
+export * from "./md5.js";
 export * from "./no-op.js";
 export * from "./ref.js";
 export * from "./sequence-equal.js";