@yume-chan/adb 0.0.12 → 0.0.13

package/src/commands/sync/sync.ts

@@ -4,11 +4,28 @@ import { AdbFeatures } from '../../features.js';
 import type { AdbSocket } from '../../socket/index.js';
 import { AdbBufferedStream, ReadableStream, WrapReadableStream, WrapWritableStream, WritableStream, WritableStreamDefaultWriter } from '../../stream/index.js';
 import { AutoResetEvent } from '../../utils/index.js';
-import { AdbSyncEntryResponse, adbSyncOpenDir } from './list.js';
+import { escapeArg } from "../index.js";
+import { adbSyncOpenDir, type AdbSyncEntry } from './list.js';
 import { adbSyncPull } from './pull.js';
 import { adbSyncPush } from './push.js';
 import { adbSyncLstat, adbSyncStat } from './stat.js';
 
+/**
+ * A simplified `dirname` function that only handles absolute unix paths.
+ * @param path an absolute unix path
+ * @returns the directory name of the input path
+ */
+export function dirname(path: string): string {
+    const end = path.lastIndexOf('/');
+    if (end === -1) {
+        throw new Error(`Invalid path`);
+    }
+    if (end === 0) {
+        return '/';
+    }
+    return path.substring(0, end);
+}
+
 export class AdbSync extends AutoDisposable {
     protected adb: Adb;
 
@@ -22,6 +39,19 @@ export class AdbSync extends AutoDisposable {
         return this.adb.features!.includes(AdbFeatures.StatV2);
     }
 
+    public get supportsList2(): boolean {
+        return this.adb.features!.includes(AdbFeatures.ListV2);
+    }
+
+    public get fixedPushMkdir(): boolean {
+        return this.adb.features!.includes(AdbFeatures.FixedPushMkdir);
+    }
+
+    public get needPushMkdirWorkaround(): boolean {
+        // https://android.googlesource.com/platform/packages/modules/adb/+/91768a57b7138166e0a3d11f79cd55909dda7014/client/file_sync_client.cpp#1361
+        return this.adb.features!.includes(AdbFeatures.ShellV2) && !this.fixedPushMkdir;
+    }
+
     public constructor(adb: Adb, socket: AdbSocket) {
         super();
 
@@ -65,18 +95,18 @@ export class AdbSync extends AutoDisposable {
 
     public async *opendir(
         path: string
-    ): AsyncGenerator<AdbSyncEntryResponse, void, void> {
+    ): AsyncGenerator<AdbSyncEntry, void, void> {
         await this.sendLock.wait();
 
         try {
-            yield* adbSyncOpenDir(this.stream, this.writer, path);
+            yield* adbSyncOpenDir(this.stream, this.writer, path, this.supportsList2);
         } finally {
             this.sendLock.notify();
         }
     }
 
     public async readdir(path: string) {
-        const results: AdbSyncEntryResponse[] = [];
+        const results: AdbSyncEntry[] = [];
         for await (const entry of this.opendir(path)) {
             results.push(entry);
         }
@@ -90,13 +120,10 @@ export class AdbSync extends AutoDisposable {
      * @returns A `ReadableStream` that reads from the file.
      */
     public read(filename: string): ReadableStream<Uint8Array> {
-        return new WrapReadableStream<Uint8Array, ReadableStream<Uint8Array>, undefined>({
+        return new WrapReadableStream({
             start: async () => {
                 await this.sendLock.wait();
-                return {
-                    readable: adbSyncPull(this.stream, this.writer, filename),
-                    state: undefined,
-                };
+                return adbSyncPull(this.stream, this.writer, filename);
             },
             close: async () => {
                 this.sendLock.notify();
@@ -120,16 +147,25 @@ export class AdbSync extends AutoDisposable {
         return new WrapWritableStream({
             start: async () => {
                 await this.sendLock.wait();
-                return {
-                    writable: adbSyncPush(
-                        this.stream,
-                        this.writer,
-                        filename,
-                        mode,
-                        mtime,
-                    ),
-                    state: undefined,
-                };
+
+                if (this.needPushMkdirWorkaround) {
+                    // It may fail if the path is already existed.
+                    // Ignore the result.
+                    // TODO: sync: test this
+                    await this.adb.subprocess.spawnAndWait([
+                        'mkdir',
+                        '-p',
+                        escapeArg(dirname(filename)),
+                    ]);
+                }
+
+                return adbSyncPush(
+                    this.stream,
+                    this.writer,
+                    filename,
+                    mode,
+                    mtime,
+                );
             },
             close: async () => {
                 this.sendLock.notify();

package/src/crypto.ts

@@ -5,48 +5,60 @@ const BigInt1 = BigInt(1);
 const BigInt2 = BigInt(2);
 const BigInt64 = BigInt(64);
 
-export function getBig(
-    array: Uint8Array,
-    offset = 0,
-    length = array.byteLength - offset
-): bigint {
-    const view = new DataView(array.buffer, array.byteOffset, array.byteLength);
-
+/**
+ * Gets the `BigInt` value at the specified byte offset and length from the start of the view. There is
+ * no alignment constraint; multi-byte values may be fetched from any offset.
+ *
+ * Only supports Big-Endian, because that's what ADB uses.
+ * @param byteOffset The place in the buffer at which the value should be retrieved.
+ */
+export function getBigUint(dataView: DataView, byteOffset: number, length: number): bigint {
     let result = BigInt0;
 
     // Currently `length` must be a multiplication of 8
     // Support for arbitrary length can be easily added
 
-    for (let i = offset; i < offset + length; i += 8) {
+    for (let i = byteOffset; i < byteOffset + length; i += 8) {
         result <<= BigInt64;
-        const value = getBigUint64(view, i, false);
+        const value = getBigUint64(dataView, i, false);
         result += value;
     }
 
     return result;
 }
 
-export function setBig(buffer: ArrayBuffer, value: bigint, offset: number = 0) {
-    const uint64Array: bigint[] = [];
-    while (value > BigInt0) {
-        uint64Array.push(BigInt.asUintN(64, value));
-        value >>= BigInt64;
-    }
+/**
+ * Stores an arbitrary-precision positive `BigInt` value at the specified byte offset from the start of the view.
+ * @param byteOffset The place in the buffer at which the value should be set.
+ * @param value The value to set.
+ * @param littleEndian If `false` or `undefined`, a big-endian value should be written,
+ * otherwise a little-endian value should be written.
+ */
+export function setBigUint(dataView: DataView, byteOffset: number, value: bigint, littleEndian?: boolean) {
+    const start = byteOffset;
+
+    if (littleEndian) {
+        while (value > BigInt0) {
+            setBigUint64(dataView, byteOffset, value, true);
+            byteOffset += 8;
+            value >>= BigInt64;
+        }
+    } else {
+        // Because we don't know how long (in bits) the `value` is,
+        // Convert it to an array of `uint64` first.
+        const uint64Array: bigint[] = [];
+        while (value > BigInt0) {
+            uint64Array.push(BigInt.asUintN(64, value));
+            value >>= BigInt64;
+        }
 
-    const view = new DataView(buffer);
-    for (let i = uint64Array.length - 1; i >= 0; i -= 1) {
-        setBigUint64(view, offset, uint64Array[i]!, false);
-        offset += 8;
+        for (let i = uint64Array.length - 1; i >= 0; i -= 1) {
+            setBigUint64(dataView, byteOffset, uint64Array[i]!, false);
+            byteOffset += 8;
+        }
     }
-}
 
-export function setBigLE(array: Uint8Array, value: bigint, offset = 0) {
-    const view = new DataView(array.buffer, array.byteOffset, array.byteLength);
-    while (value > BigInt0) {
-        setBigUint64(view, offset, value, true);
-        offset += 8;
-        value >>= BigInt64;
-    }
+    return byteOffset - start;
 }
 
 // These values are correct only if
@@ -76,9 +88,9 @@ const RsaPrivateKeyDOffset = 303;
 const RsaPrivateKeyDLength = 2048 / 8;
 
 export function parsePrivateKey(key: Uint8Array): [n: bigint, d: bigint] {
-    let n = getBig(key, RsaPrivateKeyNOffset, RsaPrivateKeyNLength);
-    let d = getBig(key, RsaPrivateKeyDOffset, RsaPrivateKeyDLength);
-
+    const view = new DataView(key.buffer, key.byteOffset, key.byteLength);
+    const n = getBigUint(view, RsaPrivateKeyNOffset, RsaPrivateKeyNLength);
+    const d = getBigUint(view, RsaPrivateKeyDOffset, RsaPrivateKeyDLength);
     return [n, d];
 }
 
@@ -132,7 +144,7 @@ export function calculatePublicKey(
     // [
     //   modulusLengthInWords, // 32-bit integer, a "word" is 32-bit so it must be 2048 / 8 / 4
     //                         // Actually the comment in Android source code was wrong
-    //   n0inv,                // 32-bit integer, the modular inverse of (lower 32 bits of) n
+    //   n0inv,                // 32-bit integer, the modular inverse of (low 32 bits of n)
     //   modulus,              // n
     //   rr,                   // Montgomery parameter R^2
     //   exponent,             // 32-bit integer, must be 65537
@@ -172,13 +184,12 @@ export function calculatePublicKey(
     outputOffset += 4;
 
     // Write n
-    setBigLE(output, n, outputOffset);
+    setBigUint(outputView, outputOffset, n, true);
     outputOffset += 256;
 
     // Calculate rr = (2^(rsa_size)) ^ 2 mod n
     let rr = BigInt(2) ** BigInt(4096) % n;
-    setBigLE(output, rr, outputOffset);
-    outputOffset += 256;
+    outputOffset += setBigUint(outputView, outputOffset, rr, true);
 
     // exponent
     outputView.setUint32(outputOffset, 65537, true);
@@ -218,21 +229,21 @@ export function powMod(base: bigint, exponent: bigint, modulus: bigint): bigint
     return r;
 }
 
-export const Sha1DigestLength = 20;
+export const SHA1_DIGEST_LENGTH = 20;
 
-export const Asn1Sequence = 0x30;
-export const Asn1OctetString = 0x04;
-export const Asn1Null = 0x05;
-export const Asn1Oid = 0x06;
+export const ASN1_SEQUENCE = 0x30;
+export const ASN1_OCTET_STRING = 0x04;
+export const ASN1_NULL = 0x05;
+export const ASN1_OID = 0x06;
 
 // PKCS#1 SHA-1 hash digest info
-export const Sha1DigestInfo = new Uint8Array([
-    Asn1Sequence, 0x0d + Sha1DigestLength,
-    Asn1Sequence, 0x09,
+export const SHA1_DIGEST_INFO = new Uint8Array([
+    ASN1_SEQUENCE, 0x0d + SHA1_DIGEST_LENGTH,
+    ASN1_SEQUENCE, 0x09,
     // SHA-1 (1 3 14 3 2 26)
-    Asn1Oid, 0x05, 1 * 40 + 3, 14, 3, 2, 26,
-    Asn1Null, 0x00,
-    Asn1OctetString, Sha1DigestLength
+    ASN1_OID, 0x05, 1 * 40 + 3, 14, 3, 2, 26,
+    ASN1_NULL, 0x00,
+    ASN1_OCTET_STRING, SHA1_DIGEST_LENGTH
 ]);
 
 // SubtleCrypto.sign() will hash the given data and sign the hash
@@ -241,7 +252,7 @@ export const Sha1DigestInfo = new Uint8Array([
 // encrypt the given data with its private key)
 // However SubtileCrypto.encrypt() doesn't accept 'RSASSA-PKCS1-v1_5' algorithm
 // So we need to implement the encryption by ourself
-export function sign(privateKey: Uint8Array, data: Uint8Array): ArrayBuffer {
+export function sign(privateKey: Uint8Array, data: Uint8Array): Uint8Array {
     const [n, d] = parsePrivateKey(privateKey);
 
     // PKCS#1 padding
@@ -254,7 +265,7 @@ export function sign(privateKey: Uint8Array, data: Uint8Array): ArrayBuffer {
     padded[index] = 1;
     index += 1;
 
-    const fillLength = padded.length - Sha1DigestInfo.length - data.length - 1;
+    const fillLength = padded.length - SHA1_DIGEST_INFO.length - data.length - 1;
     while (index < fillLength) {
         padded[index] = 0xff;
         index += 1;
@@ -263,18 +274,23 @@ export function sign(privateKey: Uint8Array, data: Uint8Array): ArrayBuffer {
     padded[index] = 0;
     index += 1;
 
-    padded.set(Sha1DigestInfo, index);
-    index += Sha1DigestInfo.length;
+    padded.set(SHA1_DIGEST_INFO, index);
+    index += SHA1_DIGEST_INFO.length;
 
     padded.set(data, index);
 
     // Encryption
     // signature = padded ** d % n
-    let signature = powMod(getBig(padded), d, n);
-
-    // Put into an ArrayBuffer
-    const result = new ArrayBuffer(256);
-    setBig(result, signature);
-
-    return result;
+    const view = new DataView(padded.buffer);
+    const signature = powMod(
+        getBigUint(view, 0, view.byteLength),
+        d,
+        n
+    );
+
+    // `padded` is not used anymore,
+    // re-use the buffer to store the result
+    setBigUint(view, 0, signature, false);
+
+    return padded;
 }

package/src/features.ts

@@ -1,5 +1,9 @@
+// The order follows
+// https://android.googlesource.com/platform/packages/modules/adb/+/79010dc6d5ca7490c493df800d4421730f5466ca/transport.cpp#1252
 export enum AdbFeatures {
-    StatV2 = 'stat_v2',
+    ShellV2 = "shell_v2",
     Cmd = 'cmd',
-    ShellV2 = "shell_v2"
+    StatV2 = 'stat_v2',
+    ListV2 = 'ls_v2',
+    FixedPushMkdir = 'fixed_push_mkdir',
 }

package/src/packet.ts

@@ -10,7 +10,7 @@ export enum AdbCommand {
     Write = 0x45545257,   // 'WRTE'
 }
 
-const AdbPacketHeader =
+export const AdbPacketHeader =
     new Struct({ littleEndian: true })
         .uint32('command')
         .uint32('arg0')
@@ -19,6 +19,8 @@ const AdbPacketHeader =
         .uint32('checksum')
         .int32('magic');
 
+export type AdbPacketHeader = typeof AdbPacketHeader['TDeserializeResult'];
+
 type AdbPacketHeaderInit = typeof AdbPacketHeader['TInit'];
 
 export const AdbPacket =
@@ -28,15 +30,24 @@ export const AdbPacket =
 
 export type AdbPacket = typeof AdbPacket['TDeserializeResult'];
 
-// All the useful fields
-export type AdbPacketCore = Omit<typeof AdbPacket['TInit'], 'checksum' | 'magic'>;
+/**
+ * `AdbPacketData` contains all the useful fields of `AdbPacket`.
+ *
+ * `AdbBackend#connect` will return a `ReadableStream<AdbPacketData>`,
+ * so each backend can encode `AdbPacket` in different ways.
+ *
+ * `AdbBackend#connect` will return a `WritableStream<AdbPacketInit>`,
+ * however, `AdbPacketDispatcher` will transform `AdbPacketData` to `AdbPacketInit` for you,
+ * so `AdbSocket#writable#write` only needs `AdbPacketData`.
+ */
+export type AdbPacketData = Omit<typeof AdbPacket['TInit'], 'checksum' | 'magic'>;
 
 // All fields except `magic`, which can be calculated in `AdbPacketSerializeStream`
 export type AdbPacketInit = Omit<typeof AdbPacket['TInit'], 'magic'>;
 
 export function calculateChecksum(payload: Uint8Array): number;
-export function calculateChecksum(init: AdbPacketCore): AdbPacketInit;
-export function calculateChecksum(payload: Uint8Array | AdbPacketCore): number | AdbPacketInit {
+export function calculateChecksum(init: AdbPacketData): AdbPacketInit;
+export function calculateChecksum(payload: Uint8Array | AdbPacketData): number | AdbPacketInit {
     if (payload instanceof Uint8Array) {
         return payload.reduce((result, item) => result + item, 0);
     } else {
@@ -49,7 +60,7 @@ export class AdbPacketSerializeStream extends TransformStream<AdbPacketInit, Uin
     public constructor() {
         super({
             transform: async (init, controller) => {
-                // This syntax is ugly, but I don't want to create an new object.
+                // This syntax is ugly, but I don't want to create a new object.
                 (init as unknown as AdbPacketHeaderInit).magic = init.command ^ 0xFFFFFFFF;
                 (init as unknown as AdbPacketHeaderInit).payloadLength = init.payload.byteLength;
 

package/src/socket/dispatcher.ts

@@ -1,14 +1,14 @@
 import { AsyncOperationManager, PromiseResolver } from '@yume-chan/async';
 import { AutoDisposable, EventEmitter } from '@yume-chan/event';
-import { AdbCommand, calculateChecksum, type AdbPacketCore, type AdbPacketInit } from '../packet.js';
+import { AdbCommand, calculateChecksum, type AdbPacketData, type AdbPacketInit } from '../packet.js';
 import { AbortController, WritableStream, WritableStreamDefaultWriter, type ReadableWritablePair } from '../stream/index.js';
 import { decodeUtf8, encodeUtf8 } from '../utils/index.js';
-import { AdbSocket } from './socket.js';
+import { AdbSocket, AdbSocketController } from './socket.js';
 
 export interface AdbIncomingSocketEventArgs {
     handled: boolean;
 
-    packet: AdbPacketCore;
+    packet: AdbPacketData;
 
     serviceString: string;
 
@@ -17,17 +17,27 @@ export interface AdbIncomingSocketEventArgs {
 
 const EmptyUint8Array = new Uint8Array(0);
 
+export interface AdbPacketDispatcherOptions {
+    calculateChecksum: boolean;
+    /**
+     * Before Android 9.0, ADB uses `char*` to parse service string,
+     * thus requires a null character to terminate.
+     *
+     * Usually it should have the same value as `calculateChecksum`.
+     */
+    appendNullToServiceString: boolean;
+    maxPayloadSize: number;
+}
+
 export class AdbPacketDispatcher extends AutoDisposable {
     // ADB socket id starts from 1
     // (0 means open failed)
     private readonly initializers = new AsyncOperationManager(1);
-    private readonly sockets = new Map<number, AdbSocket>();
+    private readonly sockets = new Map<number, AdbSocketController>();
 
     private _writer!: WritableStreamDefaultWriter<AdbPacketInit>;
 
-    public maxPayloadSize = 0;
-    public calculateChecksum = true;
-    public appendNullToServiceString = true;
+    public readonly options: AdbPacketDispatcherOptions;
 
     private _disconnected = new PromiseResolver<void>();
     public get disconnected() { return this._disconnected.promise; }
@@ -35,16 +45,16 @@ export class AdbPacketDispatcher extends AutoDisposable {
     private readonly incomingSocketEvent = this.addDisposable(new EventEmitter<AdbIncomingSocketEventArgs>());
     public get onIncomingSocket() { return this.incomingSocketEvent.event; }
 
-    private readonly errorEvent = this.addDisposable(new EventEmitter<Error>());
-    public get onError() { return this.errorEvent.event; }
-
     private _abortController = new AbortController();
 
     public constructor(
-        connection: ReadableWritablePair<AdbPacketCore, AdbPacketInit>,
+        connection: ReadableWritablePair<AdbPacketData, AdbPacketInit>,
+        options: AdbPacketDispatcherOptions
     ) {
         super();
 
+        this.options = options;
+
         connection.readable
             .pipeTo(new WritableStream({
                 write: async (packet) => {
@@ -70,8 +80,6 @@ export class AdbPacketDispatcher extends AutoDisposable {
                                 return;
                         }
                     } catch (e) {
-                        this.errorEvent.fire(e as Error);
-
                         // Throw error here will stop the pipe
                         // But won't close `readable` because of `preventCancel: true`
                         throw e;
@@ -83,15 +91,15 @@ export class AdbPacketDispatcher extends AutoDisposable {
             })
             .then(() => {
                 this.dispose();
-            }, () => {
-                // TODO: AdbPacketDispatcher: reject `_disconnected` when pipe errored?
+            }, (e) => {
+                this._disconnected.reject(e);
                 this.dispose();
             });
 
         this._writer = connection.writable.getWriter();
     }
 
-    private handleOk(packet: AdbPacketCore) {
+    private handleOk(packet: AdbPacketData) {
         if (this.initializers.resolve(packet.arg1, packet.arg0)) {
             // Device successfully created the socket
             return;
@@ -109,7 +117,7 @@ export class AdbPacketDispatcher extends AutoDisposable {
         this.sendPacket(AdbCommand.Close, packet.arg1, packet.arg0);
     }
 
-    private async handleClose(packet: AdbPacketCore) {
+    private async handleClose(packet: AdbPacketData) {
         // From https://android.googlesource.com/platform/packages/modules/adb/+/65d18e2c1cc48b585811954892311b28a4c3d188/adb.cpp#459
         /* According to protocol.txt, p->msg.arg0 might be 0 to indicate
          * a failed OPEN only. However, due to a bug in previous ADB
@@ -139,7 +147,7 @@ export class AdbPacketDispatcher extends AutoDisposable {
         // Just ignore it
     }
 
-    private async handleOpen(packet: AdbPacketCore) {
+    private async handleOpen(packet: AdbPacketData) {
         // AsyncOperationManager doesn't support get and skip an ID
         // Use `add` + `resolve` to simulate this behavior
         const [localId] = this.initializers.add<number>();
@@ -148,7 +156,7 @@ export class AdbPacketDispatcher extends AutoDisposable {
         const remoteId = packet.arg0;
         const serviceString = decodeUtf8(packet.payload);
 
-        const socket = new AdbSocket({
+        const controller = new AdbSocketController({
             dispatcher: this,
             localId,
             remoteId,
@@ -160,12 +168,12 @@ export class AdbPacketDispatcher extends AutoDisposable {
             handled: false,
             packet,
             serviceString,
-            socket,
+            socket: controller.socket,
         };
         this.incomingSocketEvent.fire(args);
 
         if (args.handled) {
-            this.sockets.set(localId, socket);
+            this.sockets.set(localId, controller);
             await this.sendPacket(AdbCommand.OK, localId, remoteId);
         } else {
             await this.sendPacket(AdbCommand.Close, 0, remoteId);
@@ -173,24 +181,30 @@ export class AdbPacketDispatcher extends AutoDisposable {
     }
 
     public async createSocket(serviceString: string): Promise<AdbSocket> {
-        if (this.appendNullToServiceString) {
+        if (this.options.appendNullToServiceString) {
             serviceString += '\0';
         }
 
         const [localId, initializer] = this.initializers.add<number>();
-        await this.sendPacket(AdbCommand.Open, localId, 0, serviceString);
+        await this.sendPacket(
+            AdbCommand.Open,
+            localId,
+            0,
+            serviceString
+        );
 
+        // Fulfilled by `handleOk`
         const remoteId = await initializer;
-        const socket = new AdbSocket({
+        const controller = new AdbSocketController({
             dispatcher: this,
             localId,
             remoteId,
             localCreated: true,
             serviceString,
         });
-        this.sockets.set(localId, socket);
+        this.sockets.set(localId, controller);
 
-        return socket;
+        return controller.socket;
     }
 
     public sendPacket(packet: AdbPacketInit): Promise<void>;
@@ -206,7 +220,7 @@ export class AdbPacketDispatcher extends AutoDisposable {
         arg1?: number,
         payload: string | Uint8Array = EmptyUint8Array,
     ): Promise<void> {
-        let init: AdbPacketCore;
+        let init: AdbPacketData;
         if (arg0 === undefined) {
             init = packetOrCommand as AdbPacketInit;
         } else {
@@ -223,11 +237,11 @@ export class AdbPacketDispatcher extends AutoDisposable {
         }
 
         if (init.payload &&
-            init.payload.byteLength > this.maxPayloadSize) {
+            init.payload.byteLength > this.options.maxPayloadSize) {
             throw new Error('payload too large');
         }
 
-        if (this.calculateChecksum) {
+        if (this.options.calculateChecksum) {
             calculateChecksum(init);
         } else {
             (init as AdbPacketInit).checksum = 0;