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

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

@@ -0,0 +1,137 @@
+import type { TransformStream } from "@yume-chan/stream-extra";
+
+import type { Adb } from "../../../adb.js";
+import { AdbFeature } from "../../../features.js";
+
+import { Format, FormatNameMap } from "./format.js";
+import { Mode } from "./mode.js";
+import {
+    createNativeCompressionStream,
+    createNativeDecompressionStream,
+    hasNativeSupport,
+} from "./native.js";
+
+export { Format, FormatNameMap, Mode };
+
+export type Adapter = () => TransformStream<Uint8Array, Uint8Array>;
+
+const CompressionRegistry: Partial<
+    Record<Exclude<Format, typeof Format.None>, Adapter>
+> = {};
+
+const DecompressionRegistry: Partial<
+    Record<Exclude<Format, typeof Format.None>, Adapter>
+> = {};
+
+export function registerCompressionAdapter(
+    format: Exclude<Format, typeof Format.None>,
+    adapter: Adapter,
+) {
+    CompressionRegistry[format] = adapter;
+}
+
+export function registerDecompressionAdapter(
+    format: Exclude<Format, typeof Format.None>,
+    adapter: Adapter,
+) {
+    DecompressionRegistry[format] = adapter;
+}
+
+function hasAdapterOrNativeSupport(format: Format, mode: Mode) {
+    if (format === Format.None) {
+        return true;
+    }
+
+    const Registry =
+        mode === Mode.Compress ? CompressionRegistry : DecompressionRegistry;
+    if (Registry[format]) {
+        return true;
+    }
+
+    return hasNativeSupport(format, mode);
+}
+
+export function canUseBrotli(adb: Adb, mode: Mode) {
+    return (
+        adb.canUseFeature(AdbFeature.SendReceive2Brotli) &&
+        hasAdapterOrNativeSupport(Format.Brotli, mode)
+    );
+}
+
+export function canUseLz4(adb: Adb, mode: Mode) {
+    return (
+        adb.canUseFeature(AdbFeature.SendReceive2Lz4) &&
+        hasAdapterOrNativeSupport(Format.Lz4, mode)
+    );
+}
+
+export function canUseZstd(adb: Adb, mode: Mode) {
+    return (
+        adb.canUseFeature(AdbFeature.SendReceive2Zstd) &&
+        hasAdapterOrNativeSupport(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: Exclude<Format, typeof Format.None>,
+): TransformStream<Uint8Array, Uint8Array> {
+    const adapter = CompressionRegistry[format];
+    if (adapter) {
+        return adapter();
+    }
+    if (hasNativeSupport(format, Mode.Compress)) {
+        return createNativeCompressionStream(format);
+    }
+    throw new Error(
+        `No adapter registered for format ${FormatNameMap[format]}`,
+    );
+}
+
+export function createDecompressionStream(
+    format: Exclude<Format, typeof Format.None>,
+): TransformStream<Uint8Array, Uint8Array> {
+    const adapter = DecompressionRegistry[format];
+    if (adapter) {
+        return adapter();
+    }
+    if (hasNativeSupport(format, Mode.Decompress)) {
+        return createNativeDecompressionStream(format);
+    }
+    throw new Error(
+        `No adapter registered for format ${FormatNameMap[format]}`,
+    );
+}

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

@@ -1,3 +1,5 @@
+// https://android.googlesource.com/platform/packages/modules/adb/+/888a54dcbf954fdffacc8283a793290abcc589cd/file_sync_protocol.h#102
+
 export const None = 0;
 export const Brotli = 2;
 export const Lz4 = 3;

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

@@ -2,4 +2,9 @@ import * as Format from "./format-ns.js";
 
 type Format = (typeof Format)[keyof typeof Format];
 
+export const FormatNameMap = /* #__PURE__ */ (() =>
+    Object.fromEntries(
+        Object.entries(Format).map(([key, value]) => [value, key]),
+    ))() as Record<Format, string>;
+
 export { Format };

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

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

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

@@ -0,0 +1,6 @@
+export const Mode = {
+    Compress: 0,
+    Decompress: 1,
+} as const;
+
+export type Mode = (typeof Mode)[keyof typeof Mode];

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

@@ -0,0 +1,73 @@
+import {
+    CompressionStream,
+    DecompressionStream,
+    TransformStream,
+} from "@yume-chan/stream-extra";
+
+import { NOOP } from "../../../utils/no-op.js";
+
+import { Format } from "./format.js";
+import { Mode } from "./mode.js";
+
+export const FormatMap: Record<Format, string> = {
+    [Format.None]: "",
+    // https://github.com/whatwg/compression/issues/54
+    [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 hasNativeSupport(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 createNativeCompressionStream(
+    format: Format,
+): CompressionStream {
+    if (format === Format.None) {
+        return new TransformStream();
+    }
+
+    return new CompressionStream(FormatMap[format]);
+}
+
+export function createNativeDecompressionStream(
+    format: Format,
+): DecompressionStream {
+    if (format === Format.None) {
+        return new TransformStream();
+    }
+
+    return new DecompressionStream(FormatMap[format]);
+}

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

@@ -10,3 +10,4 @@ export const ListV2 = encodeId("LIS2");
 export const Send = encodeId("SEND");
 export const SendV2 = encodeId("SND2");
 export const Receive = encodeId("RECV");
+export const ReceiveV2 = encodeId("RCV2");

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

@@ -0,0 +1,9 @@
+export const SyncFlag = {
+    None: 0,
+    Brotli: 1,
+    Lz4: 2,
+    Zstd: 4,
+    DryRun: 0x80000000,
+} as const;
+
+export type SyncFlag = (typeof SyncFlag)[keyof typeof SyncFlag];

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

@@ -1,11 +1,15 @@
-import { ReadableStream } from "@yume-chan/stream-extra";
+import type { TransformStream } from "@yume-chan/stream-extra";
+import { InspectStream, 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 { Compression } from "../index-ns.js";
 import type { SocketPool } from "../socket-pool.js";
 import { Error as AdbSyncError } from "../socket.js";
 
+import { SyncFlag } from "./flag.js";
+
 export const DataResponse = struct(
     { data: buffer(u32) },
     { littleEndian: true },
@@ -13,37 +17,141 @@ export const DataResponse = struct(
 
 export type DataResponse = StructValue<typeof DataResponse>;
 
-export async function* generator(
+export interface ReceiveSession {
+    /**
+     * The readable stream to read the file content from.
+     */
+    readable: ReadableStream<Uint8Array>;
+    /**
+     * Gets the number of bytes read from {@link readable}.
+     */
+    bytesRead: number;
+    /**
+     * When using Pull v2, gets the compression format used (might be `None`).
+     *
+     * When using Pull v1, this will always be `undefined`.
+     */
+    compression?: Compression.Format | undefined;
+    /**
+     * When using Pull v2, gets the size of the compressed data received from the device.
+     * Might be same as {@link bytesRead} if no compression was applied.
+     */
+    bytesCompressed: number;
+}
+
+export function receiveV1(pool: SocketPool, path: string): ReceiveSession {
+    let bytesReceived = 0;
+    return {
+        readable: ReadableStream.from(
+            pool.withSocketGenerator(async function* (socket) {
+                await socket.writeRequest(RequestId.Receive, path);
+
+                for await (const packet of socket.readResponses(
+                    ResponseId.Data,
+                    DataResponse,
+                )) {
+                    bytesReceived += packet.data.length;
+                    yield packet.data;
+                }
+            }),
+        ),
+        get bytesRead() {
+            return bytesReceived;
+        },
+        compression: undefined,
+        get bytesCompressed() {
+            return bytesReceived;
+        },
+    };
+}
+
+export function receiveV2(
     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),
-        );
+    compression?: Compression.Format,
+): ReceiveSession {
+    let flags: SyncFlag = SyncFlag.None;
+    let decompressStream: TransformStream<Uint8Array, Uint8Array> | undefined;
+    switch (compression) {
+        case Compression.Format.Brotli:
+            flags |= SyncFlag.Brotli;
+            decompressStream = Compression.createDecompressionStream(
+                Compression.Format.Brotli,
+            );
+            break;
+        case Compression.Format.Lz4:
+            flags |= SyncFlag.Lz4;
+            decompressStream = Compression.createDecompressionStream(
+                Compression.Format.Lz4,
+            );
+            break;
+        case Compression.Format.Zstd:
+            flags |= SyncFlag.Zstd;
+            decompressStream = Compression.createDecompressionStream(
+                Compression.Format.Zstd,
+            );
+            break;
     }
+
+    let bytesReceived = 0;
+    const raw = ReadableStream.from(
+        pool.withSocketGenerator(async function* (socket) {
+            await socket.writeRequest(RequestId.ReceiveV2, path);
+            await socket.writeRequest(RequestId.ReceiveV2, flags);
+
+            for await (const packet of socket.readResponses(
+                ResponseId.Data,
+                DataResponse,
+            )) {
+                bytesReceived += packet.data.length;
+                yield packet.data;
+            }
+        }),
+    );
+
+    if (decompressStream) {
+        let bytesRead = 0;
+        return {
+            readable: raw.pipeThrough(decompressStream).pipeThrough(
+                new InspectStream((chunk) => {
+                    bytesRead += chunk.length;
+                }),
+            ),
+            get bytesRead() {
+                return bytesRead;
+            },
+            compression,
+            get bytesCompressed() {
+                return bytesReceived;
+            },
+        };
+    }
+
+    return {
+        readable: raw,
+        get bytesRead() {
+            return bytesReceived;
+        },
+        compression: Compression.Format.None,
+        get bytesCompressed() {
+            return bytesReceived;
+        },
+    };
 }
 
-export function stream(
+export function receive(
+    version: 1 | 2,
     pool: SocketPool,
     path: string,
-): ReadableStream<Uint8Array> {
-    return ReadableStream.from(generator(pool, path));
+    compression?: Compression.Format,
+) {
+    if (version === 2) {
+        return receiveV2(pool, path, compression);
+    }
+
+    if (compression !== undefined && compression !== Compression.Format.None) {
+        throw new AdbSyncError("compression is not supported in v1");
+    }
+
+    return receiveV1(pool, path);
 }