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

package/src/banner.ts

@@ -21,8 +21,7 @@ export class AdbBanner {
         const pieces = banner.split("::");
         if (pieces.length > 1) {
             state = (pieces[0]!.trim() || undefined) as
-                | AdbServerClient.ConnectionState
-                | undefined;
+                AdbServerClient.ConnectionState | undefined;
             const props = pieces[1]!;
             for (const prop of props.split(";")) {
                 // istanbul ignore if

package/src/daemon/crypto.ts

@@ -18,10 +18,12 @@ export function getBigUint(
 ): bigint {
     let result = 0n;
 
-    // Currently `length` must be a multiplication of 8
-    // Support for arbitrary length can be easily added
+    // The leading bytes that do not fill a whole 64-bit word.
+    for (let j = 0; j < length % 8; j += 1) {
+        result = (result << 8n) | BigInt(array[byteOffset + j]!);
+    }
 
-    for (let i = byteOffset; i < byteOffset + length; i += 8) {
+    for (let i = byteOffset + (length % 8); i < byteOffset + length; i += 8) {
         result <<= 64n;
         const value = getUint64BigEndian(array, i);
         result |= value;
@@ -73,14 +75,6 @@ export interface SimpleRsaPrivateKey {
     d: bigint;
 }
 
-// These values are correct only if
-// modulus length is 2048 and
-// public exponent (e) is 65537
-// Anyway, that's how this library generates keys
-
-// To support other parameters,
-// a proper ASN.1 parser can be used
-
 // References:
 //
 //   https://tools.ietf.org/html/rfc8017#appendix-A.1.2
@@ -94,20 +88,68 @@ export interface SimpleRsaPrivateKey {
 //   https://www.itu.int/rec/T-REC-X.690-201508-I/en
 //   X.690: Specification of Distinguished Encoding Rules (DER)
 
-const RsaPrivateKeyNOffset = 38;
-const RsaPrivateKeyNLength = 2048 / 8;
-const RsaPrivateKeyDOffset = 303;
-const RsaPrivateKeyDLength = 2048 / 8;
-
-export function rsaParsePrivateKey(key: Uint8Array): SimpleRsaPrivateKey {
-    if (key.length < RsaPrivateKeyDOffset + RsaPrivateKeyDLength) {
-        throw new Error(
-            "RSA private key is too short. Expecting a PKCS#8 formatted RSA private key with modulus length 2048 bits and public exponent 65537.",
-        );
+/**
+ * One DER tag-length-value header: where its content starts and how long it is.
+ * @param data The DER-encoded data.
+ * @param offset The offset of the header in the data.
+ * @returns The content offset and length.
+ */
+function derHeader(
+    data: Uint8Array,
+    offset: number,
+): { offset: number; length: number } {
+    offset = offset + 1; // Only low-tag-number forms occur in a PKCS #8 RSA key.
+
+    let length = data[offset]!;
+    offset += 1;
+
+    if (length & 0x80) {
+        const lengthBytes = length & 0x7f;
+        length = 0;
+        for (let i = 0; i < lengthBytes; i += 1) {
+            length = (length << 8) | data[offset]!;
+            offset += 1;
+        }
     }
 
-    const n = getBigUint(key, RsaPrivateKeyNOffset, RsaPrivateKeyNLength);
-    const d = getBigUint(key, RsaPrivateKeyDOffset, RsaPrivateKeyDLength);
+    return { offset, length };
+}
+
+export function rsaParsePrivateKey(key: Uint8Array): SimpleRsaPrivateKey {
+    // PrivateKeyInfo ::= SEQUENCE {
+    //     version             INTEGER,
+    //     privateKeyAlgorithm AlgorithmIdentifier,
+    //     privateKey          OCTET STRING -- wrapping an RSAPrivateKey
+    // }
+    // RSAPrivateKey ::= SEQUENCE {
+    //     version         Version,
+    //     modulus         INTEGER, -- n
+    //     publicExponent  INTEGER, -- e
+    //     privateExponent INTEGER  -- d
+    //     -- ... other fields omitted
+    // }
+
+    let offset = derHeader(key, 0).offset; // into PrivateKeyInfo
+
+    let header = derHeader(key, offset); // skip version
+    offset = header.offset + header.length;
+    header = derHeader(key, offset); // skip privateKeyAlgorithm
+    offset = header.offset + header.length;
+
+    offset = derHeader(key, offset).offset; // into OCTET STRING
+    offset = derHeader(key, offset).offset; // into RSAPrivateKey
+
+    header = derHeader(key, offset); // skip version
+    offset = header.offset + header.length;
+
+    const nHeader = derHeader(key, offset); // get modulus
+    offset = nHeader.offset + nHeader.length;
+    const eHeader = derHeader(key, offset); // skip publicExponent
+    offset = eHeader.offset + eHeader.length;
+    const dHeader = derHeader(key, offset); // get privateExponent
+
+    const n = getBigUint(key, nHeader.offset, nHeader.length);
+    const d = getBigUint(key, dHeader.offset, dHeader.length);
     return { n, d };
 }
 

package/src/server/client.ts

@@ -510,7 +510,11 @@ export class AdbServerClient {
             disconnected,
         );
 
-        void transport.disconnected.finally(() => waitAbortController.abort());
+        const abortDisconnectWait = () => waitAbortController.abort();
+        void transport.disconnected.then(
+            abortDisconnectWait,
+            abortDisconnectWait,
+        );
 
         return transport;
     }

package/src/server/transport.ts

@@ -52,10 +52,14 @@ export class AdbServerTransport implements AdbTransport {
         this.#disconnected = Promise.race([this.#closed.promise, disconnected]);
     }
 
-    async connect(service: string): Promise<Adb.Socket> {
+    async connect(
+        service: string,
+        options?: AdbTransport.ConnectOptions,
+    ): Promise<Adb.Socket> {
         const socket = await this.#client.createDeviceConnection(
             { transportId: this.transportId },
             service,
+            options,
         );
         this.#sockets.push(socket);
         return socket;

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

@@ -78,7 +78,9 @@ export function adbShellProtocolSpawner(
                         stdout,
                         stderr,
                         exitCode,
-                    } satisfies AdbShellProtocolSpawner.WaitResult<Uint8Array[]>;
+                    } satisfies AdbShellProtocolSpawner.WaitResult<
+                        Uint8Array[]
+                    >;
                 } finally {
                     await process.kill();
                 }

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);
 }