@yume-chan/adb 2.6.0 → 3.0.0-beta.0

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,109 @@
+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) => {
+                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[]>;
+            });
+
+            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";

package/src/service/sync/id/common.ts

@@ -0,0 +1,33 @@
+import { getUint32LittleEndian } from "@yume-chan/no-data-view";
+
+function encodeAsciiUnchecked(value: string): Uint8Array<ArrayBuffer> {
+    const result = new Uint8Array(value.length);
+    for (let i = 0; i < value.length; i += 1) {
+        result[i] = value.charCodeAt(i);
+    }
+    return result;
+}
+
+/**
+ * Encode ID to numbers for faster comparison.
+ *
+ * This function skips all checks. The caller must ensure the input is valid.
+ *
+ * @param value A 4 ASCII character string.
+ * @returns A 32-bit integer by encoding the string as little-endian
+ *
+ * #__NO_SIDE_EFFECTS__
+ */
+export function encodeId(value: string): number {
+    const buffer = encodeAsciiUnchecked(value);
+    return getUint32LittleEndian(buffer, 0);
+}
+
+// https://cs.android.com/android/platform/superproject/main/+/main:packages/modules/adb/file_sync_protocol.h;l=23;drc=888a54dcbf954fdffacc8283a793290abcc589cd
+
+export const Lstat = encodeId("STAT");
+export const Stat = encodeId("STA2");
+export const LstatV2 = encodeId("LST2");
+
+export const Done = encodeId("DONE");
+export const Data = encodeId("DATA");

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

@@ -0,0 +1,7 @@
+import * as RequestId from "./request.js";
+import * as ResponseId from "./response.js";
+
+// Values of `RequestId` and `ResponseId` are all generic `number`s
+// so there is no point creating types for them
+
+export { RequestId, ResponseId };

package/src/service/sync/id/request.ts

@@ -0,0 +1,12 @@
+import { encodeId } from "./common.js";
+
+export { Data, Done, Lstat, LstatV2, Stat } from "./common.js";
+
+// https://cs.android.com/android/platform/superproject/main/+/main:packages/modules/adb/file_sync_protocol.h;l=23;drc=888a54dcbf954fdffacc8283a793290abcc589cd
+
+export const List = encodeId("LIST");
+export const ListV2 = encodeId("LIS2");
+
+export const Send = encodeId("SEND");
+export const SendV2 = encodeId("SND2");
+export const Receive = encodeId("RECV");

package/src/service/sync/id/response.ts

@@ -0,0 +1,11 @@
+import { encodeId } from "./common.js";
+
+export { Data, Done, Lstat, LstatV2, Stat } from "./common.js";
+
+// https://cs.android.com/android/platform/superproject/main/+/main:packages/modules/adb/file_sync_protocol.h;l=23;drc=888a54dcbf954fdffacc8283a793290abcc589cd
+
+export const Entry = encodeId("DENT");
+export const EntryV2 = encodeId("DNT2");
+
+export const Ok = encodeId("OKAY");
+export const Fail = encodeId("FAIL");

package/src/service/sync/index-ns.ts

@@ -0,0 +1,6 @@
+export * from "./compression/index.js";
+export * from "./id/index.js";
+export * from "./request/index.js";
+export * from "./service.js";
+export * from "./socket-pool.js";
+export * from "./socket.js";

package/src/service/sync/index.ts

@@ -0,0 +1,2 @@
+export * from "./android.js";
+export * as AdbSync from "./index-ns.js";

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

@@ -0,0 +1,4 @@
+export * as OpenDir from "./list.js";
+export * as Receive from "./pull.js";
+export * as Send from "./push.js";
+export * as Stat from "./stat.js";