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

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";

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

@@ -0,0 +1,110 @@
+import type { StructValue } from "@yume-chan/struct";
+import { extend, string, u32 } from "@yume-chan/struct";
+
+import { AndroidSyscallErrorCode } from "../android.js";
+import { RequestId, ResponseId } from "../id/index.js";
+import type { SocketPool } from "../socket-pool.js";
+import { Error as AdbSyncError } from "../socket.js";
+
+import type { Stat } from "./stat.js";
+import { LstatResponse, StatResponse } from "./stat.js";
+
+export const EntryResponse = extend(LstatResponse, {
+    name: string(u32),
+});
+
+export type EntryResponse = StructValue<typeof EntryResponse>;
+
+export async function* v1(
+    pool: SocketPool,
+    path: string,
+): AsyncGenerator<EntryResponse, void, void> {
+    const socket = await pool.acquire();
+    let completed = false;
+    let error: unknown;
+
+    try {
+        await socket.writeRequest(RequestId.List, path);
+        yield* socket.readResponses(ResponseId.Entry, EntryResponse);
+        completed = true;
+    } catch (e) {
+        error = e;
+        throw e;
+    } finally {
+        await pool.release(
+            socket,
+            !(completed || error instanceof AdbSyncError),
+        );
+    }
+}
+
+export const EntryV2Response = extend(StatResponse, {
+    name: string(u32),
+});
+
+export type EntryV2Response = StructValue<typeof EntryV2Response>;
+
+export async function* v2(
+    pool: SocketPool,
+    path: string,
+): AsyncGenerator<EntryV2Response, void, void> {
+    const socket = await pool.acquire();
+    let completed = false;
+    let error: unknown;
+
+    try {
+        await socket.writeRequest(RequestId.ListV2, path);
+        for await (const item of socket.readResponses(
+            ResponseId.EntryV2,
+            EntryV2Response,
+        )) {
+            // `LST2` can return error codes for failed `lstat` calls.
+            // `LIST` just ignores them.
+            // But they only contain `name` so still pretty useless.
+            if (item.error !== AndroidSyscallErrorCode.SUCCESS) {
+                continue;
+            }
+            yield item;
+        }
+        completed = true;
+    } catch (e) {
+        error = e;
+        throw e;
+    } finally {
+        await pool.release(
+            socket,
+            !(completed || error instanceof AdbSyncError),
+        );
+    }
+}
+
+export interface Entry extends Stat {
+    name: string;
+}
+
+export async function* opendir(
+    pool: SocketPool,
+    path: string,
+    { version }: { version: 1 | 2 },
+): AsyncGenerator<Entry, void, void> {
+    if (version === 2) {
+        yield* v2(pool, path);
+    } else {
+        for await (const item of v1(pool, path)) {
+            // Convert to same format as `AdbSyncEntry2Response` for easier consumption.
+            // However it will add some overhead.
+            yield {
+                mode: item.mode,
+                size: BigInt(item.size),
+                mtime: BigInt(item.mtime),
+                get type() {
+                    return item.type;
+                },
+                get permission() {
+                    return item.permission;
+                },
+                name: item.name,
+            };
+        }
+    }
+}

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

@@ -0,0 +1,49 @@
+import { ReadableStream } from "@yume-chan/stream-extra";
+import type { StructValue } from "@yume-chan/struct";
+import { buffer, struct, u32 } from "@yume-chan/struct";
+
+import { RequestId, ResponseId } from "../id/index.js";
+import type { SocketPool } from "../socket-pool.js";
+import { Error as AdbSyncError } from "../socket.js";
+
+export const DataResponse = struct(
+    { data: buffer(u32) },
+    { littleEndian: true },
+);
+
+export type DataResponse = StructValue<typeof DataResponse>;
+
+export async function* generator(
+    pool: SocketPool,
+    path: string,
+): AsyncGenerator<Uint8Array, void, void> {
+    const socket = await pool.acquire();
+    let completed = false;
+    let error: unknown;
+
+    try {
+        await socket.writeRequest(RequestId.Receive, path);
+        for await (const packet of socket.readResponses(
+            ResponseId.Data,
+            DataResponse,
+        )) {
+            yield packet.data;
+        }
+        completed = true;
+    } catch (e) {
+        error = e;
+        throw e;
+    } finally {
+        await pool.release(
+            socket,
+            !(completed || error instanceof AdbSyncError),
+        );
+    }
+}
+
+export function stream(
+    pool: SocketPool,
+    path: string,
+): ReadableStream<Uint8Array> {
+    return ReadableStream.from(generator(pool, path));
+}

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

@@ -0,0 +1,184 @@
+import type { ReadableStream } from "@yume-chan/stream-extra";
+import {
+    AbortController,
+    DistributionStream,
+    MaybeConsumable,
+} from "@yume-chan/stream-extra";
+import { struct, u32 } from "@yume-chan/struct";
+
+import { NOOP } from "../../../utils/index.js";
+import { LinuxFileType } from "../android.js";
+import { Compression } from "../compression/index.js";
+import { RequestId, ResponseId } from "../id/index.js";
+import type { SocketPool } from "../socket-pool.js";
+import type { Socket } from "../socket.js";
+import { Error as AdbSyncError } from "../socket.js";
+
+export const MaxPacketSize = 64 * 1024;
+
+export const OkResponse = struct({ unused: u32 }, { littleEndian: true });
+
+// eslint-disable-next-line @typescript-eslint/max-params
+async function pipeFileData(
+    socket: Socket,
+    file: ReadableStream<MaybeConsumable<Uint8Array>>,
+    packetSize: number,
+    mtime: number,
+    compression: Compression.Format,
+): Promise<void> {
+    if (compression !== Compression.Format.None) {
+        const stream = Compression.createCompressionStream(compression);
+        void file
+            .pipeTo(new MaybeConsumable.WrapWritableStream(stream.writable))
+            .catch(NOOP);
+        file = stream.readable;
+    }
+
+    // Read and write in parallel,
+    // allow error response to abort the write.
+    const abortController = new AbortController();
+    file.pipeThrough(new DistributionStream(packetSize, true))
+        .pipeTo(
+            new MaybeConsumable.WritableStream({
+                write(chunk) {
+                    return socket.writeRequest(RequestId.Data, chunk);
+                },
+            }),
+            { signal: abortController.signal },
+        )
+        .then(async () => {
+            await socket.writeRequest(RequestId.Done, mtime);
+            await socket.flush();
+        }, NOOP);
+
+    try {
+        await socket.readResponse(ResponseId.Ok, OkResponse);
+    } catch (e) {
+        abortController.abort(e);
+        throw e;
+    }
+}
+
+export interface SendV1Options {
+    pool: SocketPool;
+    filename: string;
+    file: ReadableStream<MaybeConsumable<Uint8Array>>;
+    type?: LinuxFileType | undefined;
+    permission?: number | undefined;
+    mtime?: number | undefined;
+    packetSize?: number | undefined;
+}
+
+export function sendV1({
+    pool,
+    filename,
+    file,
+    type = LinuxFileType.File,
+    permission = 0o666,
+    mtime = (Date.now() / 1000) | 0,
+    packetSize = MaxPacketSize,
+}: SendV1Options) {
+    return pool.withSocket(async (socket) => {
+        const mode = (type << 12) | permission;
+        const pathAndMode = `${filename},${mode.toString()}`;
+        await socket.writeRequest(RequestId.Send, pathAndMode);
+        await pipeFileData(
+            socket,
+            file,
+            packetSize,
+            mtime,
+            Compression.Format.None,
+        );
+    });
+}
+
+export const SendV2Flags = {
+    None: 0,
+    Brotli: 1,
+    Lz4: 2,
+    Zstd: 4,
+    DryRun: 0x80000000,
+} as const;
+
+export type SendV2Flags = (typeof SendV2Flags)[keyof typeof SendV2Flags];
+
+export const SendV2Request = struct(
+    { id: u32, mode: u32, flags: u32 },
+    { littleEndian: true },
+);
+
+export interface SendV2Options extends SendV1Options {
+    compression?: Compression.Format | undefined;
+
+    /**
+     * 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 | undefined;
+}
+
+export function sendV2({
+    pool,
+    filename,
+    file,
+    type = LinuxFileType.File,
+    permission = 0o666,
+    mtime = (Date.now() / 1000) | 0,
+    packetSize = MaxPacketSize,
+    compression = Compression.Format.None,
+    dryRun = false,
+}: SendV2Options) {
+    return pool.withSocket(async (socket) => {
+        let flags: SendV2Flags = SendV2Flags.None;
+        switch (compression) {
+            case Compression.Format.Brotli:
+                flags |= SendV2Flags.Brotli;
+                break;
+            case Compression.Format.Lz4:
+                flags |= SendV2Flags.Lz4;
+                break;
+            case Compression.Format.Zstd:
+                flags |= SendV2Flags.Zstd;
+                break;
+        }
+        if (dryRun) {
+            flags |= SendV2Flags.DryRun;
+        }
+
+        await socket.writeRequest(RequestId.SendV2, filename);
+        await socket.write(
+            SendV2Request.serialize({
+                id: RequestId.SendV2,
+                mode: (type << 12) | permission,
+                flags,
+            }),
+        );
+
+        await pipeFileData(socket, file, packetSize, mtime, compression);
+    });
+}
+
+export interface SendOptions extends SendV2Options {
+    version: 1 | 2;
+}
+
+export function send(options: SendOptions) {
+    if (options.version === 2) {
+        return sendV2(options);
+    }
+
+    if (options.dryRun) {
+        throw new AdbSyncError("dryRun is not supported in v1");
+    }
+
+    if (
+        options.compression !== undefined &&
+        options.compression !== Compression.Format.None
+    ) {
+        throw new AdbSyncError("compression is not supported in v1");
+    }
+
+    return sendV1(options);
+}

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

@@ -0,0 +1,127 @@
+import type { StructValue } from "@yume-chan/struct";
+import { struct, u32, u64 } from "@yume-chan/struct";
+
+import type { AndroidSyscallErrorCode, LinuxFileType } from "../android.js";
+import { AndroidSyscallErrorNameMap } from "../android.js";
+import { RequestId, ResponseId } from "../id/index.js";
+import type { SocketPool } from "../socket-pool.js";
+import { Error as AdbSyncError } from "../socket.js";
+
+export const LstatResponse = struct(
+    { mode: u32, size: u32, mtime: u32 },
+    {
+        littleEndian: true,
+        extra: {
+            get type(): LinuxFileType {
+                return (this.mode >> 12) as LinuxFileType;
+            },
+            get permission(): number {
+                return this.mode & 0b00001111_11111111;
+            },
+        },
+        postDeserialize(value) {
+            if (value.mode === 0 && value.size === 0 && value.mtime === 0) {
+                throw new AdbSyncError("lstat error");
+            }
+            return value;
+        },
+    },
+);
+
+export type LstatResponse = StructValue<typeof LstatResponse>;
+
+export function lstatV1(
+    pool: SocketPool,
+    path: string,
+): Promise<LstatResponse> {
+    return pool.withSocket(async (socket) => {
+        await socket.writeRequest(RequestId.Lstat, path);
+        return await socket.readResponse(ResponseId.Lstat, LstatResponse);
+    });
+}
+
+export const StatResponse = struct(
+    {
+        error: u32<AndroidSyscallErrorCode>(),
+        dev: u64,
+        ino: u64,
+        mode: u32,
+        nlink: u32,
+        uid: u32,
+        gid: u32,
+        size: u64,
+        atime: u64,
+        mtime: u64,
+        ctime: u64,
+    },
+    {
+        littleEndian: true,
+        extra: {
+            get type(): LinuxFileType {
+                return (this.mode >> 12) as LinuxFileType;
+            },
+            get permission(): number {
+                return this.mode & 0b00001111_11111111;
+            },
+        },
+        postDeserialize(value) {
+            if (value.error) {
+                throw new AdbSyncError(AndroidSyscallErrorNameMap[value.error]);
+            }
+            return value;
+        },
+    },
+);
+
+export type StatResponse = StructValue<typeof StatResponse>;
+
+export function lstatV2(pool: SocketPool, path: string) {
+    return pool.withSocket(async (socket) => {
+        await socket.writeRequest(RequestId.LstatV2, path);
+        return await socket.readResponse(ResponseId.LstatV2, StatResponse);
+    });
+}
+
+export async function lstat(
+    pool: SocketPool,
+    path: string,
+    { version }: { version: 1 | 2 },
+): Promise<Stat> {
+    if (version === 2) {
+        return await lstatV2(pool, path);
+    } else {
+        const response = await lstatV1(pool, path);
+        return {
+            mode: response.mode,
+            // Convert to `BigInt` to make it compatible with `StatResponse`
+            size: BigInt(response.size),
+            mtime: BigInt(response.mtime),
+            get type() {
+                return response.type;
+            },
+            get permission() {
+                return response.permission;
+            },
+        };
+    }
+}
+
+export interface Stat {
+    mode: number;
+    size: bigint;
+    mtime: bigint;
+    get type(): LinuxFileType;
+    get permission(): number;
+
+    uid?: number;
+    gid?: number;
+    atime?: bigint;
+    ctime?: bigint;
+}
+
+export function stat(pool: SocketPool, path: string): Promise<StatResponse> {
+    return pool.withSocket(async (socket) => {
+        await socket.writeRequest(RequestId.Stat, path);
+        return await socket.readResponse(ResponseId.Stat, StatResponse);
+    });
+}