@yume-chan/adb 0.0.23 → 1.0.0

package/src/commands/sync/push.ts

@@ -1,10 +1,10 @@
-import type { Consumable, ReadableStream } from "@yume-chan/stream-extra";
+import type { ReadableStream } from "@yume-chan/stream-extra";
 import {
     AbortController,
-    ConsumableWritableStream,
     DistributionStream,
+    MaybeConsumable,
 } from "@yume-chan/stream-extra";
-import Struct, { placeholder } from "@yume-chan/struct";
+import { struct, u32 } from "@yume-chan/struct";
 
 import { NOOP } from "../../utils/index.js";
 
@@ -18,20 +18,21 @@ export const ADB_SYNC_MAX_PACKET_SIZE = 64 * 1024;
 export interface AdbSyncPushV1Options {
     socket: AdbSyncSocket;
     filename: string;
-    file: ReadableStream<Consumable<Uint8Array>>;
+    file: ReadableStream<MaybeConsumable<Uint8Array>>;
     type?: LinuxFileType;
     permission?: number;
     mtime?: number;
     packetSize?: number;
 }
 
-export const AdbSyncOkResponse = new Struct({ littleEndian: true }).uint32(
-    "unused",
+export const AdbSyncOkResponse = struct(
+    { unused: u32 },
+    { littleEndian: true },
 );
 
 async function pipeFileData(
     locked: AdbSyncSocketLocked,
-    file: ReadableStream<Consumable<Uint8Array>>,
+    file: ReadableStream<MaybeConsumable<Uint8Array>>,
     packetSize: number,
     mtime: number,
 ) {
@@ -40,9 +41,9 @@ async function pipeFileData(
     const abortController = new AbortController();
     file.pipeThrough(new DistributionStream(packetSize, true))
         .pipeTo(
-            new ConsumableWritableStream({
-                write: async (chunk) => {
-                    await adbSyncWriteRequest(
+            new MaybeConsumable.WritableStream({
+                write(chunk) {
+                    return adbSyncWriteRequest(
                         locked,
                         AdbSyncRequestId.Data,
                         chunk,
@@ -86,22 +87,22 @@ export async function adbSyncPushV1({
     }
 }
 
-export enum AdbSyncSendV2Flags {
-    None = 0,
-    Brotli = 1,
+export const AdbSyncSendV2Flags = {
+    None: 0,
+    Brotli: 1,
     /**
      * 2
      */
-    Lz4 = 1 << 1,
+    Lz4: 1 << 1,
     /**
      * 4
      */
-    Zstd = 1 << 2,
-    /**
-     * 0x80000000
-     */
-    DryRun = (1 << 31) >>> 0,
-}
+    Zstd: 1 << 2,
+    DryRun: 0x80000000,
+} as const;
+
+export type AdbSyncSendV2Flags =
+    (typeof AdbSyncSendV2Flags)[keyof typeof AdbSyncSendV2Flags];
 
 export interface AdbSyncPushV2Options extends AdbSyncPushV1Options {
     /**
@@ -113,10 +114,10 @@ export interface AdbSyncPushV2Options extends AdbSyncPushV1Options {
     dryRun?: boolean;
 }
 
-export const AdbSyncSendV2Request = new Struct({ littleEndian: true })
-    .uint32("id", placeholder<AdbSyncRequestId>())
-    .uint32("mode")
-    .uint32("flags", placeholder<AdbSyncSendV2Flags>());
+export const AdbSyncSendV2Request = struct(
+    { id: u32, mode: u32, flags: u32<AdbSyncSendV2Flags>() },
+    { littleEndian: true },
+);
 
 export async function adbSyncPushV2({
     socket,

package/src/commands/sync/request.ts

@@ -1,27 +1,24 @@
-import Struct from "@yume-chan/struct";
-
-import { encodeUtf8 } from "../../utils/index.js";
-
-export enum AdbSyncRequestId {
-    List = "LIST",
-    ListV2 = "LIS2",
-    Send = "SEND",
-    SendV2 = "SND2",
-    Lstat = "STAT",
-    Stat = "STA2",
-    LstatV2 = "LST2",
-    Data = "DATA",
-    Done = "DONE",
-    Receive = "RECV",
-}
+import { encodeUtf8, struct, u32 } from "@yume-chan/struct";
+
+import { adbSyncEncodeId } from "./response.js";
 
-export const AdbSyncNumberRequest = new Struct({ littleEndian: true })
-    .string("id", { length: 4 })
-    .uint32("arg");
+export const AdbSyncRequestId = {
+    List: adbSyncEncodeId("LIST"),
+    ListV2: adbSyncEncodeId("LIS2"),
+    Send: adbSyncEncodeId("SEND"),
+    SendV2: adbSyncEncodeId("SND2"),
+    Lstat: adbSyncEncodeId("STAT"),
+    Stat: adbSyncEncodeId("STA2"),
+    LstatV2: adbSyncEncodeId("LST2"),
+    Data: adbSyncEncodeId("DATA"),
+    Done: adbSyncEncodeId("DONE"),
+    Receive: adbSyncEncodeId("RECV"),
+} as const;
 
-export const AdbSyncDataRequest = new Struct({ littleEndian: true })
-    .concat(AdbSyncNumberRequest)
-    .uint8Array("data", { lengthField: "arg" });
+export const AdbSyncNumberRequest = struct(
+    { id: u32, arg: u32 },
+    { littleEndian: true },
+);
 
 export interface AdbSyncWritable {
     write(buffer: Uint8Array): Promise<void>;
@@ -29,26 +26,28 @@ export interface AdbSyncWritable {
 
 export async function adbSyncWriteRequest(
     writable: AdbSyncWritable,
-    id: AdbSyncRequestId | string,
+    id: number | string,
     value: number | string | Uint8Array,
 ): Promise<void> {
+    if (typeof id === "string") {
+        id = adbSyncEncodeId(id);
+    }
+
     if (typeof value === "number") {
-        const buffer = AdbSyncNumberRequest.serialize({
-            id,
-            arg: value,
-        });
-        await writable.write(buffer);
-    } else if (typeof value === "string") {
-        // Let `writable` buffer writes
-        const buffer = encodeUtf8(value);
         await writable.write(
-            AdbSyncNumberRequest.serialize({ id, arg: buffer.byteLength }),
+            AdbSyncNumberRequest.serialize({ id, arg: value }),
         );
-        await writable.write(buffer);
-    } else {
-        await writable.write(
-            AdbSyncNumberRequest.serialize({ id, arg: value.byteLength }),
-        );
-        await writable.write(value);
+        return;
+    }
+
+    if (typeof value === "string") {
+        value = encodeUtf8(value);
     }
+
+    // `writable` is buffered, it copies inputs to an internal buffer,
+    // so don't concatenate headers and data here, that will be an unnecessary copy.
+    await writable.write(
+        AdbSyncNumberRequest.serialize({ id, arg: value.length }),
+    );
+    await writable.write(value);
 }

package/src/commands/sync/response.ts

@@ -1,60 +1,86 @@
-import type {
-    AsyncExactReadable,
-    StructLike,
-    StructValueType,
-} from "@yume-chan/struct";
-import Struct from "@yume-chan/struct";
+import { getUint32LittleEndian } from "@yume-chan/no-data-view";
+import type { AsyncExactReadable, StructLike } from "@yume-chan/struct";
+import { decodeUtf8, string, struct, u32 } from "@yume-chan/struct";
 
-import { decodeUtf8 } from "../../utils/index.js";
+function encodeAsciiUnchecked(value: string): Uint8Array {
+    const result = new Uint8Array(value.length);
+    for (let i = 0; i < value.length; i += 1) {
+        result[i] = value.charCodeAt(i);
+    }
+    return result;
+}
 
-export enum AdbSyncResponseId {
-    Entry = "DENT",
-    Entry2 = "DNT2",
-    Lstat = "STAT",
-    Stat = "STA2",
-    Lstat2 = "LST2",
-    Done = "DONE",
-    Data = "DATA",
-    Ok = "OKAY",
-    Fail = "FAIL",
+/**
+ * Encode ID to numbers for faster comparison
+ * @param value A 4-character string
+ * @returns A 32-bit integer by encoding the string as little-endian
+ *
+ * #__NO_SIDE_EFFECTS__
+ */
+export function adbSyncEncodeId(value: string): number {
+    const buffer = encodeAsciiUnchecked(value);
+    return getUint32LittleEndian(buffer, 0);
 }
 
+export const AdbSyncResponseId = {
+    Entry: adbSyncEncodeId("DENT"),
+    Entry2: adbSyncEncodeId("DNT2"),
+    Lstat: adbSyncEncodeId("STAT"),
+    Stat: adbSyncEncodeId("STA2"),
+    Lstat2: adbSyncEncodeId("LST2"),
+    Done: adbSyncEncodeId("DONE"),
+    Data: adbSyncEncodeId("DATA"),
+    Ok: adbSyncEncodeId("OKAY"),
+    Fail: adbSyncEncodeId("FAIL"),
+};
+
 export class AdbSyncError extends Error {}
 
-export const AdbSyncFailResponse = new Struct({ littleEndian: true })
-    .uint32("messageLength")
-    .string("message", { lengthField: "messageLength" })
-    .postDeserialize((object) => {
-        throw new AdbSyncError(object.message);
-    });
+export const AdbSyncFailResponse = struct(
+    { message: string(u32) },
+    {
+        littleEndian: true,
+        postDeserialize(value) {
+            throw new AdbSyncError(value.message);
+        },
+    },
+);
 
 export async function adbSyncReadResponse<T>(
     stream: AsyncExactReadable,
-    id: AdbSyncResponseId,
+    id: number | string,
     type: StructLike<T>,
 ): Promise<T> {
-    const actualId = decodeUtf8(await stream.readExactly(4));
-    switch (actualId) {
+    if (typeof id === "string") {
+        id = adbSyncEncodeId(id);
+    }
+
+    const buffer = await stream.readExactly(4);
+    switch (getUint32LittleEndian(buffer, 0)) {
         case AdbSyncResponseId.Fail:
             await AdbSyncFailResponse.deserialize(stream);
             throw new Error("Unreachable");
         case id:
             return await type.deserialize(stream);
         default:
-            throw new Error(`Expected '${id}', but got '${actualId}'`);
+            throw new Error(
+                `Expected '${id}', but got '${decodeUtf8(buffer)}'`,
+            );
     }
 }
 
-export async function* adbSyncReadResponses<
-    T extends Struct<object, PropertyKey, object, unknown>,
->(
+export async function* adbSyncReadResponses<T>(
     stream: AsyncExactReadable,
-    id: AdbSyncResponseId,
-    type: T,
-): AsyncGenerator<StructValueType<T>, void, void> {
+    id: number | string,
+    type: StructLike<T>,
+): AsyncGenerator<T, void, void> {
+    if (typeof id === "string") {
+        id = adbSyncEncodeId(id);
+    }
+
     while (true) {
-        const actualId = decodeUtf8(await stream.readExactly(4));
-        switch (actualId) {
+        const buffer = await stream.readExactly(4);
+        switch (getUint32LittleEndian(buffer, 0)) {
             case AdbSyncResponseId.Fail:
                 await AdbSyncFailResponse.deserialize(stream);
                 throw new Error("Unreachable");
@@ -66,11 +92,11 @@ export async function* adbSyncReadResponses<
                 await stream.readExactly(type.size);
                 return;
             case id:
-                yield (await type.deserialize(stream)) as StructValueType<T>;
+                yield await type.deserialize(stream);
                 break;
             default:
                 throw new Error(
-                    `Expected '${id}' or '${AdbSyncResponseId.Done}', but got '${actualId}'`,
+                    `Expected '${id}' or '${AdbSyncResponseId.Done}', but got '${decodeUtf8(buffer)}'`,
                 );
         }
     }

package/src/commands/sync/socket.ts

@@ -1,11 +1,11 @@
 import type {
-    Consumable,
+    MaybeConsumable,
     WritableStreamDefaultWriter,
 } from "@yume-chan/stream-extra";
 import {
     BufferCombiner,
     BufferedReadableStream,
-    ConsumableWritableStream,
+    Consumable,
 } from "@yume-chan/stream-extra";
 import type { AsyncExactReadable } from "@yume-chan/struct";
 
@@ -13,7 +13,7 @@ import type { AdbSocket } from "../../adb.js";
 import { AutoResetEvent } from "../../utils/index.js";
 
 export class AdbSyncSocketLocked implements AsyncExactReadable {
-    readonly #writer: WritableStreamDefaultWriter<Consumable<Uint8Array>>;
+    readonly #writer: WritableStreamDefaultWriter<MaybeConsumable<Uint8Array>>;
     readonly #readable: BufferedReadableStream;
     readonly #socketLock: AutoResetEvent;
     readonly #writeLock = new AutoResetEvent();
@@ -24,7 +24,7 @@ export class AdbSyncSocketLocked implements AsyncExactReadable {
     }
 
     constructor(
-        writer: WritableStreamDefaultWriter<Consumable<Uint8Array>>,
+        writer: WritableStreamDefaultWriter<MaybeConsumable<Uint8Array>>,
         readable: BufferedReadableStream,
         bufferSize: number,
         lock: AutoResetEvent,
@@ -35,8 +35,9 @@ export class AdbSyncSocketLocked implements AsyncExactReadable {
         this.#combiner = new BufferCombiner(bufferSize);
     }
 
-    async #writeInnerStream(buffer: Uint8Array) {
-        await ConsumableWritableStream.write(this.#writer, buffer);
+    #write(buffer: Uint8Array) {
+        // `#combiner` will reuse the buffer, so we need to use the Consumable pattern
+        return Consumable.WritableStream.write(this.#writer, buffer);
     }
 
     async flush() {
@@ -44,7 +45,7 @@ export class AdbSyncSocketLocked implements AsyncExactReadable {
             await this.#writeLock.wait();
             const buffer = this.#combiner.flush();
             if (buffer) {
-                await this.#writeInnerStream(buffer);
+                await this.#write(buffer);
             }
         } finally {
             this.#writeLock.notifyOne();
@@ -55,7 +56,7 @@ export class AdbSyncSocketLocked implements AsyncExactReadable {
         try {
             await this.#writeLock.wait();
             for (const buffer of this.#combiner.push(data)) {
-                await this.#writeInnerStream(buffer);
+                await this.#write(buffer);
             }
         } finally {
             this.#writeLock.notifyOne();
@@ -63,11 +64,15 @@ export class AdbSyncSocketLocked implements AsyncExactReadable {
     }
 
     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);
     }
 
     release(): void {
+        // In theory, the writer shouldn't leave anything in the buffer,
+        // but to be safe, call `flush` to throw away any remaining data.
         this.#combiner.flush();
         this.#socketLock.notifyOne();
     }

package/src/commands/sync/stat.ts

@@ -1,15 +1,18 @@
-import Struct, { placeholder } from "@yume-chan/struct";
+import type { StructValue } from "@yume-chan/struct";
+import { struct, u32, u64 } from "@yume-chan/struct";
 
 import { AdbSyncRequestId, adbSyncWriteRequest } from "./request.js";
 import { AdbSyncResponseId, adbSyncReadResponse } from "./response.js";
 import type { AdbSyncSocket } from "./socket.js";
 
 // https://github.com/python/cpython/blob/4e581d64b8aff3e2eda99b12f080c877bb78dfca/Lib/stat.py#L36
-export enum LinuxFileType {
-    Directory = 0o04,
-    File = 0o10,
-    Link = 0o12,
-}
+export const LinuxFileType = {
+    Directory: 0o04,
+    File: 0o10,
+    Link: 0o12,
+} as const;
+
+export type LinuxFileType = (typeof LinuxFileType)[keyof typeof LinuxFileType];
 
 export interface AdbSyncStat {
     mode: number;
@@ -24,81 +27,98 @@ export interface AdbSyncStat {
     ctime?: bigint;
 }
 
-export const AdbSyncLstatResponse = new Struct({ littleEndian: true })
-    .int32("mode")
-    .int32("size")
-    .int32("mtime")
-    .extra({
-        id: AdbSyncResponseId.Lstat as const,
-        get type() {
-            return (this.mode >> 12) as LinuxFileType;
+export const AdbSyncLstatResponse = 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;
+            },
         },
-        get permission() {
-            return this.mode & 0b00001111_11111111;
+        postDeserialize(value) {
+            if (value.mode === 0 && value.size === 0 && value.mtime === 0) {
+                throw new Error("lstat error");
+            }
+            return value;
         },
-    })
-    .postDeserialize((object) => {
-        if (object.mode === 0 && object.size === 0 && object.mtime === 0) {
-            throw new Error("lstat error");
-        }
-    });
+    },
+);
 
-export type AdbSyncLstatResponse =
-    (typeof AdbSyncLstatResponse)["TDeserializeResult"];
+export type AdbSyncLstatResponse = StructValue<typeof AdbSyncLstatResponse>;
 
-export enum AdbSyncStatErrorCode {
-    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,
-}
+export const AdbSyncStatErrorCode = {
+    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 const AdbSyncStatResponse = new Struct({ littleEndian: true })
-    .uint32("error", placeholder<AdbSyncStatErrorCode>())
-    .uint64("dev")
-    .uint64("ino")
-    .uint32("mode")
-    .uint32("nlink")
-    .uint32("uid")
-    .uint32("gid")
-    .uint64("size")
-    .uint64("atime")
-    .uint64("mtime")
-    .uint64("ctime")
-    .extra({
-        id: AdbSyncResponseId.Stat as const,
-        get type() {
-            return (this.mode >> 12) as LinuxFileType;
+export type AdbSyncStatErrorCode =
+    (typeof AdbSyncStatErrorCode)[keyof typeof AdbSyncStatErrorCode];
+
+const AdbSyncStatErrorName = /* #__PURE__ */ (() =>
+    Object.fromEntries(
+        Object.entries(AdbSyncStatErrorCode).map(([key, value]) => [
+            value,
+            key,
+        ]),
+    ))();
+
+export const AdbSyncStatResponse = struct(
+    {
+        error: u32<AdbSyncStatErrorCode>(),
+        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;
+            },
         },
-        get permission() {
-            return this.mode & 0b00001111_11111111;
+        postDeserialize(value) {
+            if (value.error) {
+                throw new Error(AdbSyncStatErrorName[value.error]);
+            }
+            return value;
         },
-    })
-    .postDeserialize((object) => {
-        if (object.error) {
-            throw new Error(AdbSyncStatErrorCode[object.error]);
-        }
-    });
+    },
+);
 
-export type AdbSyncStatResponse =
-    (typeof AdbSyncStatResponse)["TDeserializeResult"];
+export type AdbSyncStatResponse = StructValue<typeof AdbSyncStatResponse>;
 
 export async function adbSyncLstat(
     socket: AdbSyncSocket,

package/src/commands/sync/sync.ts

@@ -1,5 +1,4 @@
-import { AutoDisposable } from "@yume-chan/event";
-import type { Consumable, ReadableStream } from "@yume-chan/stream-extra";
+import type { MaybeConsumable, ReadableStream } from "@yume-chan/stream-extra";
 
 import type { Adb, AdbSocket } from "../../adb.js";
 import { AdbFeature } from "../../features.js";
@@ -9,6 +8,7 @@ import type { AdbSyncEntry } from "./list.js";
 import { adbSyncOpenDir } from "./list.js";
 import { adbSyncPull } from "./pull.js";
 import { adbSyncPush } from "./push.js";
+import type { AdbSyncSocketLocked } from "./socket.js";
 import { AdbSyncSocket } from "./socket.js";
 import type { AdbSyncStat, LinuxFileType } from "./stat.js";
 import { adbSyncLstat, adbSyncStat } from "./stat.js";
@@ -31,14 +31,14 @@ export function dirname(path: string): string {
 
 export interface AdbSyncWriteOptions {
     filename: string;
-    file: ReadableStream<Consumable<Uint8Array>>;
+    file: ReadableStream<MaybeConsumable<Uint8Array>>;
     type?: LinuxFileType;
     permission?: number;
     mtime?: number;
     dryRun?: boolean;
 }
 
-export class AdbSync extends AutoDisposable {
+export class AdbSync {
     protected _adb: Adb;
     protected _socket: AdbSyncSocket;
 
@@ -69,8 +69,6 @@ export class AdbSync extends AutoDisposable {
     }
 
     constructor(adb: Adb, socket: AdbSocket) {
-        super();
-
         this._adb = adb;
         this._socket = new AdbSyncSocket(socket, adb.maxPayloadSize);
 
@@ -116,7 +114,7 @@ export class AdbSync extends AutoDisposable {
         try {
             await this.lstat(path + "/");
             return true;
-        } catch (e) {
+        } catch {
             return false;
         }
     }
@@ -150,7 +148,7 @@ export class AdbSync extends AutoDisposable {
      */
     async write(options: AdbSyncWriteOptions): Promise<void> {
         if (this.needPushMkdirWorkaround) {
-            // It may fail if the path is already existed.
+            // 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.spawnAndWait([
@@ -167,8 +165,11 @@ export class AdbSync extends AutoDisposable {
         });
     }
 
-    override async dispose() {
-        super.dispose();
-        await this._socket.close();
+    lockSocket(): Promise<AdbSyncSocketLocked> {
+        return this._socket.lock();
+    }
+
+    dispose() {
+        return this._socket.close();
     }
 }