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

package/src/{commands → service}/subprocess/shell/pty.ts

@@ -12,13 +12,13 @@ import {
 } from "@yume-chan/stream-extra";
 import { encodeUtf8 } from "@yume-chan/struct";
 
-import type { AdbSocket } from "../../../adb.js";
-import type { AdbPtyProcess } from "../pty.js";
+import type { Adb } from "../../../adb.js";
+import type { AdbPty } from "../pty.js";
 
 import { AdbShellProtocolId, AdbShellProtocolPacket } from "./shared.js";
 
-export class AdbShellProtocolPtyProcess implements AdbPtyProcess<number> {
-    readonly #socket: AdbSocket;
+export class AdbShellProtocolPty implements AdbPty<number> {
+    readonly #socket: Adb.Socket;
     readonly #writer: WritableStreamDefaultWriter<MaybeConsumable<Uint8Array>>;
 
     readonly #input: WritableStream<MaybeConsumable<Uint8Array>>;
@@ -26,9 +26,9 @@ export class AdbShellProtocolPtyProcess implements AdbPtyProcess<number> {
         return this.#input;
     }
 
-    readonly #stdout: ReadableStream<Uint8Array>;
+    readonly #output: ReadableStream<Uint8Array>;
     get output() {
-        return this.#stdout;
+        return this.#output;
     }
 
     readonly #exited = new PromiseResolver<number>();
@@ -36,12 +36,12 @@ export class AdbShellProtocolPtyProcess implements AdbPtyProcess<number> {
         return this.#exited.promise;
     }
 
-    constructor(socket: AdbSocket) {
+    constructor(socket: Adb.Socket) {
         this.#socket = socket;
 
-        let stdoutController!: PushReadableStreamController<Uint8Array>;
-        this.#stdout = new PushReadableStream<Uint8Array>((controller) => {
-            stdoutController = controller;
+        let outputController!: PushReadableStreamController<Uint8Array>;
+        this.#output = new PushReadableStream<Uint8Array>((controller) => {
+            outputController = controller;
         });
 
         socket.readable
@@ -54,22 +54,23 @@ export class AdbShellProtocolPtyProcess implements AdbPtyProcess<number> {
                                 this.#exited.resolve(chunk.data[0]!);
                                 break;
                             case AdbShellProtocolId.Stdout:
-                                await stdoutController.enqueue(chunk.data);
+                                await outputController.enqueue(chunk.data);
                                 break;
+                            // PTY mode doesn't have stderr
                         }
                     },
                 }),
             )
             .then(
                 () => {
-                    stdoutController.close();
+                    outputController.close();
                     // If `#exit` has already resolved, this will be a no-op
                     this.#exited.reject(
                         new Error("Socket ended without exit message"),
                     );
                 },
                 (e) => {
-                    stdoutController.error(e);
+                    outputController.error(e);
                     // If `#exit` has already resolved, this will be a no-op
                     this.#exited.reject(e);
                 },
@@ -103,6 +104,7 @@ export class AdbShellProtocolPtyProcess implements AdbPtyProcess<number> {
     }
 
     sigint() {
+        // Write `^C`
         return this.#writeStdin(new Uint8Array([0x03]));
     }
 

package/src/service/subprocess/shell/service.ts

@@ -0,0 +1,75 @@
+import type { Adb } from "../../../adb.js";
+import { AdbFeature } from "../../../features.js";
+
+import { AdbShellProtocolProcessImpl } from "./process.js";
+import { AdbShellProtocolPty } from "./pty.js";
+import { AdbShellProtocolId, AdbShellProtocolPacket } from "./shared.js";
+import { adbShellProtocolSpawner } from "./spawner.js";
+
+export class AdbShellProtocolSubprocessService {
+    static readonly PacketId = AdbShellProtocolId;
+
+    static readonly Packet = AdbShellProtocolPacket;
+
+    readonly #adb: Adb;
+    get adb() {
+        return this.#adb;
+    }
+
+    get isSupported() {
+        return this.#adb.canUseFeature(AdbFeature.Shell2);
+    }
+
+    constructor(adb: Adb) {
+        this.#adb = adb;
+    }
+
+    spawn = adbShellProtocolSpawner(async (command, signal) => {
+        if (!command.length) {
+            throw new Error("Command cannot be empty");
+        }
+
+        // Don't escape `command`. See `AdbNoneProtocolSubprocessService.prototype.spawn` for details.
+        const service = "shell,v2,raw:" + command.join(" ");
+        const socket = await this.#adb.createSocket(service);
+
+        if (signal?.aborted) {
+            await socket.close();
+            throw signal.reason;
+        }
+
+        return new AdbShellProtocolProcessImpl(socket, signal);
+    });
+
+    async pty(options?: {
+        command?: string | readonly string[] | undefined;
+        terminalType?: string;
+    }): Promise<AdbShellProtocolPty> {
+        const { command, terminalType } = options ?? {};
+
+        let service = "shell,v2,pty";
+
+        if (terminalType) {
+            if (terminalType.includes(",") || terminalType.includes(":")) {
+                throw new Error("terminalType must not contain ',' or ':'");
+            }
+            service += `,TERM=` + terminalType;
+        }
+        service += ":";
+
+        if (typeof command === "string") {
+            service += command;
+        } else if (Array.isArray(command)) {
+            // Don't escape `command`. See `AdbNoneProtocolSubprocessService.prototype.spawn` for details.
+            service += command.join(" ");
+        }
+
+        return new AdbShellProtocolPty(await this.#adb.createSocket(service));
+    }
+}
+
+export namespace AdbShellProtocolSubprocessService {
+    export type PacketId = AdbShellProtocolId;
+
+    export type Packet = AdbShellProtocolPacket;
+}

package/src/{commands → service}/subprocess/shell/shared.ts

@@ -1,6 +1,7 @@
 import type { StructValue } from "@yume-chan/struct";
 import { buffer, struct, u32, u8 } from "@yume-chan/struct";
 
+/** @internal */
 export const AdbShellProtocolId = {
     Stdin: 0,
     Stdout: 1,
@@ -10,10 +11,12 @@ export const AdbShellProtocolId = {
     WindowSizeChange: 5,
 } as const;
 
+/** @internal */
 export type AdbShellProtocolId =
     (typeof AdbShellProtocolId)[keyof typeof AdbShellProtocolId];
 
 // This packet format is used in both directions.
+/** @internal */
 export const AdbShellProtocolPacket = struct(
     {
         id: u8<AdbShellProtocolId>(),
@@ -22,4 +25,6 @@ export const AdbShellProtocolPacket = struct(
     { littleEndian: true },
 );
 
+// `StructValue` and `StructInit` is same for `AdbShellProtocolPacket`.
+/** @internal */
 export type AdbShellProtocolPacket = StructValue<typeof AdbShellProtocolPacket>;

package/src/service/subprocess/shell/spawner.ts

@@ -0,0 +1,113 @@
+import type { MaybePromiseLike } from "@yume-chan/async";
+import type {
+    AbortSignal,
+    MaybeConsumable,
+    ReadableStream,
+    WritableStream,
+} from "@yume-chan/stream-extra";
+import { concatUint8Arrays } from "@yume-chan/stream-extra";
+
+import type { AdbSubprocessSpawner } from "../types.js";
+import {
+    createLazyPromise,
+    decodeUtf8Chunked,
+    splitCommand,
+    ToArrayStream,
+} from "../utils.js";
+
+export interface AdbShellProtocolProcess {
+    get stdin(): WritableStream<MaybeConsumable<Uint8Array>>;
+
+    get stdout(): ReadableStream<Uint8Array>;
+    get stderr(): ReadableStream<Uint8Array>;
+
+    get exited(): Promise<number>;
+
+    kill(): MaybePromiseLike<void>;
+}
+
+export type AdbShellProtocolSpawner = (
+    command: string | readonly string[],
+    signal?: AbortSignal,
+) => Promise<AdbShellProtocolProcess> &
+    AdbSubprocessSpawner.Wait<
+        AdbShellProtocolSpawner.WaitResult<Uint8Array>,
+        AdbShellProtocolSpawner.WaitResult<string>
+    >;
+
+export namespace AdbShellProtocolSpawner {
+    export interface WaitResult<T> {
+        stdout: T;
+        stderr: T;
+        exitCode: number;
+    }
+}
+
+export function adbShellProtocolSpawner(
+    spawn: (
+        command: readonly string[],
+        signal: AbortSignal | undefined,
+    ) => Promise<AdbShellProtocolProcess>,
+): AdbShellProtocolSpawner {
+    return (command, signal) => {
+        signal?.throwIfAborted();
+
+        if (typeof command === "string") {
+            command = splitCommand(command);
+        }
+
+        const processPromise = spawn(
+            command,
+            signal,
+        ) as Promise<AdbShellProtocolProcess> &
+            AdbSubprocessSpawner.Wait<
+                AdbShellProtocolSpawner.WaitResult<Uint8Array>,
+                AdbShellProtocolSpawner.WaitResult<string>
+            >;
+
+        processPromise.wait = (options) => {
+            const waitPromise = processPromise.then(async (process) => {
+                try {
+                    const [, stdout, stderr, exitCode] = await Promise.all([
+                        options?.stdin?.pipeTo(process.stdin),
+                        process.stdout.pipeThrough(new ToArrayStream()),
+                        process.stderr.pipeThrough(new ToArrayStream()),
+                        process.exited,
+                    ]);
+                    return {
+                        stdout,
+                        stderr,
+                        exitCode,
+                    } satisfies AdbShellProtocolSpawner.WaitResult<Uint8Array[]>;
+                } finally {
+                    await process.kill();
+                }
+            });
+
+            return createLazyPromise(
+                async () => {
+                    const { stdout, stderr, exitCode } = await waitPromise;
+
+                    return {
+                        stdout: concatUint8Arrays(stdout),
+                        stderr: concatUint8Arrays(stderr),
+                        exitCode,
+                    };
+                },
+                {
+                    async toString() {
+                        const { stdout, stderr, exitCode } = await waitPromise;
+
+                        return {
+                            stdout: decodeUtf8Chunked(stdout),
+                            stderr: decodeUtf8Chunked(stderr),
+                            exitCode,
+                        };
+                    },
+                },
+            );
+        };
+
+        return processPromise;
+    };
+}

package/src/service/subprocess/types.ts

@@ -0,0 +1,19 @@
+import type { MaybeConsumable, ReadableStream } from "@yume-chan/stream-extra";
+
+import type { LazyPromise } from "./utils.js";
+
+export namespace AdbSubprocessSpawner {
+    export interface WaitToString<T> {
+        toString(): Promise<T>;
+    }
+
+    export interface WaitOptions {
+        stdin?: ReadableStream<MaybeConsumable<Uint8Array>> | undefined;
+    }
+
+    export interface Wait<TBuffer, TString> {
+        wait(
+            options?: WaitOptions,
+        ): LazyPromise<TBuffer, WaitToString<TString>>;
+    }
+}

package/src/service/subprocess/utils.ts

@@ -0,0 +1,166 @@
+import { AccumulateStream } from "@yume-chan/stream-extra";
+import { TextDecoder } from "@yume-chan/struct";
+
+export function escapeArg(s: string) {
+    let result = "";
+    result += `'`;
+
+    let base = 0;
+    while (true) {
+        const found = s.indexOf(`'`, base);
+        if (found === -1) {
+            result += s.substring(base);
+            break;
+        }
+        result += s.substring(base, found);
+        // a'b becomes 'a'\'b', which is 'a' + \' + 'b'
+        // (quoted string 'a', escaped single quote, and quoted string 'b')
+        result += String.raw`'\''`;
+        base = found + 1;
+    }
+
+    result += `'`;
+    return result;
+}
+
+/**
+ * Split the command.
+ *
+ * Quotes and escaped characters are supported, and will be returned as-is.
+ * @param input The input command
+ * @returns An array of string containing the arguments
+ */
+export function splitCommand(input: string): string[] {
+    const result: string[] = [];
+    let quote: string | undefined;
+    let isEscaped = false;
+    let start = 0;
+
+    for (let i = 0, len = input.length; i < len; i += 1) {
+        if (isEscaped) {
+            isEscaped = false;
+            continue;
+        }
+
+        const char = input.charAt(i);
+        switch (char) {
+            case " ":
+                if (!quote) {
+                    if (i !== start) {
+                        result.push(input.substring(start, i));
+                    }
+                    start = i + 1;
+                }
+                break;
+            case "'":
+            case '"':
+                if (!quote) {
+                    quote = char;
+                } else if (char === quote) {
+                    quote = undefined;
+                }
+                break;
+            case "\\":
+                isEscaped = true;
+                break;
+        }
+    }
+
+    if (start < input.length) {
+        result.push(input.substring(start));
+    }
+
+    return result;
+}
+
+// Omit `Symbol.toStringTag` so it's incompatible with `Promise`.
+// It can't be returned from async function like `Promise`s.
+export type LazyPromise<T, U> = Omit<Promise<T>, typeof Symbol.toStringTag> & U;
+
+/**
+ * Creates a `Promise`-like object that lazily computes the result
+ * only when it's being used as a `Promise`.
+ *
+ * For example, if an API returns a value `p` of type `Promise<T> & { asU(): Promise<U> }`,
+ * and the user calls `p.asU()` instead of using it as a `Promise` (`p.then()`, `await p`, etc.),
+ * is unnecessary to compute the result `T` (unless `asU` also depends on it).
+ *
+ * By using `createLazyPromise(computeT, { asU: computeU })`,
+ * `computeT` will only run when `p` is used as a `Promise`.
+ *
+ * Note that the result object can't be returned from an async function,
+ * as async functions always creates a new `Promise` with the return value,
+ * which runs `initializer` immediately, and discards any extra `methods` attached.
+ * @param initializer
+ * The initializer function when the result object is being used as a `Promise`.
+ *
+ * The result value will be cached.
+ * @param methods Any extra methods to add to the result object
+ * @returns
+ * A `Promise`-like object that runs `initializer` when used as a `Promise`, and contains `methods`.
+ */
+export function createLazyPromise<
+    T,
+    U extends Record<PropertyKey, () => unknown>,
+>(initializer: () => Promise<T>, methods: U): LazyPromise<T, U> {
+    let promise: Promise<T> | undefined;
+
+    const getOrCreatePromise = () => {
+        if (!promise) {
+            promise = initializer();
+        }
+        return promise;
+    };
+
+    const result = {
+        // biome-ignore lint/suspicious/noThenProperty: This object is intentionally thenable
+        then(onfulfilled, onrejected) {
+            return getOrCreatePromise().then(onfulfilled, onrejected);
+        },
+        // biome-ignore lint/suspicious/noThenProperty: This object is intentionally thenable
+        catch(onrejected) {
+            return getOrCreatePromise().catch(onrejected);
+        },
+        // biome-ignore lint/suspicious/noThenProperty: This object is intentionally thenable
+        finally(onfinally) {
+            return getOrCreatePromise().finally(onfinally);
+        },
+        // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+    } satisfies LazyPromise<T, {}> as LazyPromise<T, U>;
+
+    for (const [key, value] of Object.entries(methods)) {
+        Object.defineProperty(result, key, {
+            configurable: true,
+            writable: true,
+            enumerable: false,
+            value,
+        });
+    }
+
+    return result;
+}
+
+export class ToArrayStream<T> extends AccumulateStream<T, T[]> {
+    constructor() {
+        super(
+            [],
+            (chunk, current) => {
+                current.push(chunk);
+                return current;
+            },
+            (output) => output,
+        );
+    }
+}
+
+export function decodeUtf8Chunked(chunks: Uint8Array[]): string {
+    // PERF: `TextDecoder`'s `stream` mode can decode from `chunks` directly.
+    // This avoids an extra allocation and copy.
+    const decoder = new TextDecoder();
+    let output = "";
+    for (const chunk of chunks) {
+        output += decoder.decode(chunk, { stream: true });
+    }
+    output += decoder.decode();
+    return output;
+}

package/src/service/sync/android.ts

@@ -0,0 +1,43 @@
+// https://github.com/python/cpython/blob/4e581d64b8aff3e2eda99b12f080c877bb78dfca/Lib/stat.py#L36
+export const LinuxFileType = {
+    Directory: 0o04,
+    File: 0o10,
+    Link: 0o12,
+} as const;
+
+export type LinuxFileType = (typeof LinuxFileType)[keyof typeof LinuxFileType];
+
+export const AndroidSyscallErrorCode = {
+    SUCCESS: 0,
+    EACCES: 13,
+    EEXIST: 17,
+    EFAULT: 14,
+    EFBIG: 27,
+    EINTR: 4,
+    EINVAL: 22,
+    EIO: 5,
+    EISDIR: 21,
+    ELOOP: 40,
+    EMFILE: 24,
+    ENAMETOOLONG: 36,
+    ENFILE: 23,
+    ENOENT: 2,
+    ENOMEM: 12,
+    ENOSPC: 28,
+    ENOTDIR: 20,
+    EOVERFLOW: 75,
+    EPERM: 1,
+    EROFS: 30,
+    ETXTBSY: 26,
+} as const;
+
+export type AndroidSyscallErrorCode =
+    (typeof AndroidSyscallErrorCode)[keyof typeof AndroidSyscallErrorCode];
+
+export const AndroidSyscallErrorNameMap = /* #__PURE__ */ (() =>
+    Object.fromEntries(
+        Object.entries(AndroidSyscallErrorCode).map(([key, value]) => [
+            value,
+            key,
+        ]),
+    ))();

package/src/service/sync/compression/compression.ts

@@ -0,0 +1,126 @@
+import {
+    CompressionStream,
+    DecompressionStream,
+    TransformStream,
+} from "@yume-chan/stream-extra";
+
+import type { Adb } from "../../../adb.js";
+import { AdbFeature } from "../../../features.js";
+import { NOOP } from "../../../utils/no-op.js";
+
+import { Format } from "./format.js";
+
+export { Format };
+
+export const Mode = {
+    Compress: 0,
+    Decompress: 1,
+} as const;
+
+export type Mode = (typeof Mode)[keyof typeof Mode];
+
+const FormatMap: Record<Format, string> = {
+    [Format.None]: "",
+    // https://github.com/whatwg/compression/pull/80
+    [Format.Zstd]: "zstd",
+    // placeholder
+    [Format.Lz4]: "lz4",
+    // https://github.com/whatwg/compression/pull/80
+    [Format.Brotli]: "brotli",
+};
+
+const CompressionFormatCache = new Map<Format, boolean>();
+const DecompressionFormatCache = new Map<Format, boolean>();
+
+export function hasRuntimeSupport(format: Format, mode: Mode) {
+    if (format === Format.None) {
+        return true;
+    }
+
+    const Cache =
+        mode === Mode.Compress
+            ? CompressionFormatCache
+            : DecompressionFormatCache;
+    if (Cache.has(format)) {
+        return Cache.get(format)!;
+    }
+
+    const Stream =
+        mode === Mode.Compress ? CompressionStream : DecompressionStream;
+    if (!Stream) {
+        return false;
+    }
+
+    try {
+        const stream = new Stream(FormatMap[format]);
+        void stream.writable.abort().catch(NOOP);
+        Cache.set(format, true);
+        return true;
+    } catch {
+        Cache.set(format, false);
+        return false;
+    }
+}
+
+export function canUseBrotli(adb: Adb, mode: Mode) {
+    return (
+        adb.canUseFeature(AdbFeature.SendReceive2Brotli) &&
+        hasRuntimeSupport(Format.Brotli, mode)
+    );
+}
+
+export function canUseLz4(adb: Adb, mode: Mode) {
+    return (
+        adb.canUseFeature(AdbFeature.SendReceive2Lz4) &&
+        hasRuntimeSupport(Format.Lz4, mode)
+    );
+}
+
+export function canUseZstd(adb: Adb, mode: Mode) {
+    return (
+        adb.canUseFeature(AdbFeature.SendReceive2Zstd) &&
+        hasRuntimeSupport(Format.Zstd, mode)
+    );
+}
+
+export function canUseFormat(adb: Adb, format: Format, mode: Mode) {
+    switch (format) {
+        case Format.None:
+            return true;
+        case Format.Brotli:
+            return canUseBrotli(adb, mode);
+        case Format.Lz4:
+            return canUseLz4(adb, mode);
+        case Format.Zstd:
+            return canUseZstd(adb, mode);
+        default:
+            return false;
+    }
+}
+
+export function chooseFormat(adb: Adb, mode: Mode) {
+    // The order follows
+    // https://android.googlesource.com/platform/packages/modules/adb/+/3da39565cad412a743a58b94b875a43ed3c640d3/client/file_sync_client.cpp#277
+
+    if (canUseZstd(adb, mode)) {
+        return Format.Zstd;
+    }
+
+    if (canUseLz4(adb, mode)) {
+        return Format.Lz4;
+    }
+
+    if (canUseBrotli(adb, mode)) {
+        return Format.Brotli;
+    }
+
+    return Format.None;
+}
+
+export function createCompressionStream(format: Format): CompressionStream {
+    if (format === Format.None) {
+        return new TransformStream();
+    }
+
+    return new CompressionStream(FormatMap[format]);
+}

package/src/service/sync/compression/format-ns.ts

@@ -0,0 +1,4 @@
+export const None = 0;
+export const Brotli = 2;
+export const Lz4 = 3;
+export const Zstd = 4;

package/src/service/sync/compression/format.ts

@@ -0,0 +1,5 @@
+import * as Format from "./format-ns.js";
+
+type Format = (typeof Format)[keyof typeof Format];
+
+export { Format };

package/src/service/sync/compression/index.ts

@@ -0,0 +1 @@
+export * as Compression from "./compression.js";