@yume-chan/adb 0.0.11 → 0.0.14

package/src/commands/subprocess/protocols/index.ts

@@ -0,0 +1,3 @@
+export * from './none.js';
+export * from './shell.js';
+export * from './types.js';

package/src/commands/subprocess/{legacy.ts → protocols/none.ts}

@@ -1,6 +1,6 @@
-import type { Adb } from "../../adb.js";
-import type { AdbSocket } from "../../socket/index.js";
-import { DuplexStreamFactory, type ReadableStream } from "../../stream/index.js";
+import type { Adb } from "../../../adb.js";
+import type { AdbSocket } from "../../../socket/index.js";
+import { DuplexStreamFactory, ReadableStream } from "../../../stream/index.js";
 import type { AdbSubprocessProtocol } from "./types.js";
 
 /**
@@ -11,11 +11,17 @@ import type { AdbSubprocessProtocol } from "./types.js";
  * * `exit` exit code: No
  * * `resize`: No
  */
-export class AdbNoneSubprocessProtocol implements AdbSubprocessProtocol {
+export class AdbSubprocessNoneProtocol implements AdbSubprocessProtocol {
     public static isSupported() { return true; }
 
-    public static async spawn(adb: Adb, command: string) {
-        return new AdbNoneSubprocessProtocol(await adb.createSocket(`shell:${command}`));
+    public static async pty(adb: Adb, command: string) {
+        return new AdbSubprocessNoneProtocol(await adb.createSocket(`shell:${command}`));
+    }
+
+    public static async raw(adb: Adb, command: string) {
+        // `shell,raw:${command}` also triggers raw mode,
+        // But is not supported before Android 7.
+        return new AdbSubprocessNoneProtocol(await adb.createSocket(`exec:${command}`));
     }
 
     private readonly socket: AdbSocket;
@@ -24,11 +30,15 @@ export class AdbNoneSubprocessProtocol implements AdbSubprocessProtocol {
     public get stdin() { return this.socket.writable; }
 
     private _stdout: ReadableStream<Uint8Array>;
-    // Legacy shell doesn't support splitting output streams.
+    /**
+     * Legacy shell mixes stdout and stderr.
+     */
     public get stdout() { return this._stdout; }
 
-    // `stderr` of Legacy shell is always empty.
     private _stderr: ReadableStream<Uint8Array>;
+    /**
+     * `stderr` will always be empty.
+     */
     public get stderr() { return this._stderr; }
 
     private _exit: Promise<number>;
@@ -43,8 +53,8 @@ export class AdbNoneSubprocessProtocol implements AdbSubprocessProtocol {
             },
         });
 
-        this._stdout = factory.createWrapReadable(this.socket.readable);
-        this._stderr = factory.createReadable();
+        this._stdout = factory.wrapReadable(this.socket.readable);
+        this._stderr = factory.wrapReadable(new ReadableStream());
         this._exit = factory.closed.then(() => 0);
     }
 

package/src/commands/subprocess/{protocol.ts → protocols/shell.ts}

@@ -1,10 +1,10 @@
 import { PromiseResolver } from "@yume-chan/async";
 import Struct, { placeholder, type StructValueType } from "@yume-chan/struct";
-import type { Adb } from "../../adb.js";
-import { AdbFeatures } from "../../features.js";
-import type { AdbSocket } from "../../socket/index.js";
-import { PushReadableStream, ReadableStream, StructDeserializeStream, StructSerializeStream, TransformStream, WritableStream, WritableStreamDefaultWriter, type PushReadableStreamController } from "../../stream/index.js";
-import { encodeUtf8 } from "../../utils/index.js";
+import type { Adb } from "../../../adb.js";
+import { AdbFeatures } from "../../../features.js";
+import type { AdbSocket } from "../../../socket/index.js";
+import { pipeFrom, PushReadableStream, ReadableStream, StructDeserializeStream, StructSerializeStream, TransformStream, WritableStream, WritableStreamDefaultWriter, type PushReadableStreamController } from "../../../stream/index.js";
+import { encodeUtf8 } from "../../../utils/index.js";
 import type { AdbSubprocessProtocol } from "./types.js";
 
 export enum AdbShellProtocolId {
@@ -17,10 +17,11 @@ export enum AdbShellProtocolId {
 }
 
 // This packet format is used in both direction.
-const AdbShellProtocolPacket = new Struct({ littleEndian: true })
-    .uint8('id', placeholder<AdbShellProtocolId>())
-    .uint32('length')
-    .uint8Array('data', { lengthField: 'length' });
+const AdbShellProtocolPacket =
+    new Struct({ littleEndian: true })
+        .uint8('id', placeholder<AdbShellProtocolId>())
+        .uint32('length')
+        .uint8Array('data', { lengthField: 'length' });
 
 type AdbShellProtocolPacketInit = typeof AdbShellProtocolPacket['TInit'];
 
@@ -99,15 +100,18 @@ class MultiplexStream<T>{
  * * `exit` exit code: Yes
  * * `resize`: Yes
  */
-export class AdbShellSubprocessProtocol implements AdbSubprocessProtocol {
+export class AdbSubprocessShellProtocol implements AdbSubprocessProtocol {
     public static isSupported(adb: Adb) {
         return adb.features!.includes(AdbFeatures.ShellV2);
     }
 
-    public static async spawn(adb: Adb, command: string) {
-        // TODO: AdbShellSubprocessProtocol: Support raw mode
+    public static async pty(adb: Adb, command: string) {
         // TODO: AdbShellSubprocessProtocol: Support setting `XTERM` environment variable
-        return new AdbShellSubprocessProtocol(await adb.createSocket(`shell,v2,pty:${command}`));
+        return new AdbSubprocessShellProtocol(await adb.createSocket(`shell,v2,pty:${command}`));
+    }
+
+    public static async raw(adb: Adb, command: string) {
+        return new AdbSubprocessShellProtocol(await adb.createSocket(`shell,v2,raw:${command}`));
     }
 
     private readonly _socket: AdbSocket;
@@ -140,7 +144,7 @@ export class AdbShellSubprocessProtocol implements AdbSubprocessProtocol {
                 transform: (chunk, controller) => {
                     if (chunk.id === AdbShellProtocolId.Exit) {
                         this._exit.resolve(new Uint8Array(chunk.data)[0]!);
-                        // We can let `StdoutTransformStream` to process `AdbShellProtocolId.Exit`,
+                        // We can let `StdoutDeserializeStream` to process `AdbShellProtocolId.Exit`,
                         // but since we need this `TransformStream` to capture the exit code anyway,
                         // terminating child streams here is killing two birds with one stone.
                         controller.terminate();
@@ -160,9 +164,10 @@ export class AdbShellSubprocessProtocol implements AdbSubprocessProtocol {
             .pipeThrough(new StructSerializeStream(AdbShellProtocolPacket))
             .pipeTo(socket.writable);
 
-        const { readable, writable } = new StdinSerializeStream();
-        this._stdin = writable;
-        readable.pipeTo(multiplexer.createWriteable());
+        this._stdin = pipeFrom(
+            multiplexer.createWriteable(),
+            new StdinSerializeStream()
+        );
 
         this._socketWriter = multiplexer.createWriteable().getWriter();
     }

package/src/commands/subprocess/{types.ts → protocols/types.ts}

@@ -1,7 +1,7 @@
 import type { ValueOrPromise } from "@yume-chan/struct";
-import type { Adb } from "../../adb.js";
-import type { AdbSocket } from "../../socket/index.js";
-import type { ReadableStream, WritableStream } from "../../stream/index.js";
+import type { Adb } from "../../../adb.js";
+import type { AdbSocket } from "../../../socket/index.js";
+import type { ReadableStream, WritableStream } from "../../../stream/index.js";
 
 export interface AdbSubprocessProtocol {
     /**
@@ -17,7 +17,7 @@ export interface AdbSubprocessProtocol {
     /**
      * The `stderr` pipe of the process.
      *
-     * Note: Some `AdbShell` doesn't separate `stdout` and `stderr`,
+     * Note: Some `AdbSubprocessProtocol` doesn't separate `stdout` and `stderr`,
      * All output will be sent to `stdout`.
      */
     readonly stderr: ReadableStream<Uint8Array>;
@@ -25,15 +25,16 @@ export interface AdbSubprocessProtocol {
     /**
      * A `Promise` that resolves to the exit code of the process.
      *
-     * Note: Some `AdbShell` doesn't support exit code,
-     * They will always resolve with `0`.
+     * Note: Some `AdbSubprocessProtocol` doesn't support exit code,
+     * They will always resolve it with `0`.
      */
     readonly exit: Promise<number>;
 
     /**
      * Resizes the current shell.
      *
-     * Some `AdbShell`s may not support resizing and will always ignore calls to this method.
+     * Some `AdbSubprocessProtocol`s may not support resizing
+     * and will ignore calls to this method.
      */
     resize(rows: number, cols: number): ValueOrPromise<void>;
 
@@ -47,8 +48,11 @@ export interface AdbSubprocessProtocolConstructor {
     /** Returns `true` if the `adb` instance supports this shell */
     isSupported(adb: Adb): ValueOrPromise<boolean>;
 
-    /** Creates a new `AdbShell` using the specified `Adb` and `command` */
-    spawn(adb: Adb, command: string): ValueOrPromise<AdbSubprocessProtocol>;
+    /** Spawns an executable in PTY (interactive) mode. */
+    pty(adb: Adb, command: string): ValueOrPromise<AdbSubprocessProtocol>;
+
+    /** Spawns an executable and pipe the output. */
+    raw(adb: Adb, command: string): ValueOrPromise<AdbSubprocessProtocol>;
 
     /** Creates a new `AdbShell` by attaching to an exist `AdbSocket` */
     new(socket: AdbSocket): AdbSubprocessProtocol;

package/src/commands/sync/list.ts

@@ -2,7 +2,11 @@ import Struct from '@yume-chan/struct';
 import type { AdbBufferedStream, WritableStreamDefaultWriter } from '../../stream/index.js';
 import { AdbSyncRequestId, adbSyncWriteRequest } from './request.js';
 import { AdbSyncDoneResponse, adbSyncReadResponse, AdbSyncResponseId } from './response.js';
-import { AdbSyncLstatResponse } from './stat.js';
+import { AdbSyncLstatResponse, AdbSyncStatResponse, type AdbSyncStat } from './stat.js';
+
+export interface AdbSyncEntry extends AdbSyncStat {
+    name: string;
+}
 
 export const AdbSyncEntryResponse =
     new Struct({ littleEndian: true })
@@ -13,22 +17,64 @@ export const AdbSyncEntryResponse =
 
 export type AdbSyncEntryResponse = typeof AdbSyncEntryResponse['TDeserializeResult'];
 
-const ResponseTypes = {
+export const AdbSyncEntry2Response =
+    new Struct({ littleEndian: true })
+        .fields(AdbSyncStatResponse)
+        .uint32('nameLength')
+        .string('name', { lengthField: 'nameLength' })
+        .extra({ id: AdbSyncResponseId.Entry2 as const });
+
+export type AdbSyncEntry2Response = typeof AdbSyncEntry2Response['TDeserializeResult'];
+
+const LIST_V1_RESPONSE_TYPES = {
     [AdbSyncResponseId.Entry]: AdbSyncEntryResponse,
     [AdbSyncResponseId.Done]: new AdbSyncDoneResponse(AdbSyncEntryResponse.size),
 };
 
+const LIST_V2_RESPONSE_TYPES = {
+    [AdbSyncResponseId.Entry2]: AdbSyncEntry2Response,
+    [AdbSyncResponseId.Done]: new AdbSyncDoneResponse(AdbSyncEntry2Response.size),
+};
+
 export async function* adbSyncOpenDir(
     stream: AdbBufferedStream,
     writer: WritableStreamDefaultWriter<Uint8Array>,
     path: string,
-): AsyncGenerator<AdbSyncEntryResponse, void, void> {
-    await adbSyncWriteRequest(writer, AdbSyncRequestId.List, path);
+    v2: boolean,
+): AsyncGenerator<AdbSyncEntry, void, void> {
+    let requestId: AdbSyncRequestId.List | AdbSyncRequestId.List2;
+    let responseType: typeof LIST_V1_RESPONSE_TYPES | typeof LIST_V2_RESPONSE_TYPES;
+
+    if (v2) {
+        requestId = AdbSyncRequestId.List2;
+        responseType = LIST_V2_RESPONSE_TYPES;
+    } else {
+        requestId = AdbSyncRequestId.List;
+        responseType = LIST_V1_RESPONSE_TYPES;
+    }
+
+    await adbSyncWriteRequest(writer, requestId, path);
 
     while (true) {
-        const response = await adbSyncReadResponse(stream, ResponseTypes);
+        const response = await adbSyncReadResponse(stream, responseType);
         switch (response.id) {
             case AdbSyncResponseId.Entry:
+                yield {
+                    mode: response.mode,
+                    size: BigInt(response.size),
+                    mtime: BigInt(response.mtime),
+                    get type() { return response.type; },
+                    get permission() { return response.permission; },
+                    name: response.name,
+                };
+                break;
+            case AdbSyncResponseId.Entry2:
+                // `LST2` can return error codes for failed `lstat` calls.
+                // `LIST` just ignores them.
+                // But they only contain `name` so still pretty useless.
+                if (response.error !== 0) {
+                    continue;
+                }
                 yield response;
                 break;
             case AdbSyncResponseId.Done:

package/src/commands/sync/pull.ts

@@ -9,7 +9,7 @@ export const AdbSyncDataResponse =
         .uint8Array('data', { lengthField: 'dataLength' })
         .extra({ id: AdbSyncResponseId.Data as const });
 
-const ResponseTypes = {
+const RESPONSE_TYPES = {
     [AdbSyncResponseId.Data]: AdbSyncDataResponse,
     [AdbSyncResponseId.Done]: new AdbSyncDoneResponse(AdbSyncDataResponse.size),
 };
@@ -24,7 +24,7 @@ export function adbSyncPull(
             await adbSyncWriteRequest(writer, AdbSyncRequestId.Receive, path);
         },
         async pull(controller) {
-            const response = await adbSyncReadResponse(stream, ResponseTypes);
+            const response = await adbSyncReadResponse(stream, RESPONSE_TYPES);
             switch (response.id) {
                 case AdbSyncResponseId.Data:
                     controller.enqueue(response.data!);
@@ -35,7 +35,10 @@ export function adbSyncPull(
                 default:
                     throw new Error('Unexpected response id');
             }
-        }
+        },
+        cancel() {
+            throw new Error(`Sync commands don't support cancel.`);
+        },
     }, {
         highWaterMark: 16 * 1024,
         size(chunk) { return chunk.byteLength; }

package/src/commands/sync/request.ts

@@ -4,6 +4,7 @@ import { encodeUtf8 } from "../../utils/index.js";
 
 export enum AdbSyncRequestId {
     List = 'LIST',
+    List2 = 'LIS2',
     Send = 'SEND',
     Lstat = 'STAT',
     Stat = 'STA2',

package/src/commands/sync/response.ts

@@ -4,6 +4,7 @@ import { decodeUtf8 } from "../../utils/index.js";
 
 export enum AdbSyncResponseId {
     Entry = 'DENT',
+    Entry2 = 'DNT2',
     Lstat = 'STAT',
     Stat = 'STA2',
     Lstat2 = 'LST2',
@@ -43,7 +44,12 @@ export const AdbSyncFailResponse =
 export async function adbSyncReadResponse<T extends Record<string, StructLike<any>>>(
     stream: AdbBufferedStream,
     types: T,
-): Promise<StructValueType<T[keyof T]>> {
+    // When `T` is a union type, `T[keyof T]` only includes their common keys.
+    // For example, let `type T = { a: string, b: string } | { a: string, c: string}`,
+    // `keyof T` is `'a'`, not `'a' | 'b' | 'c'`.
+    // However, `T extends unknown ? keyof T : never` will distribute `T`,
+    // so returns all keys.
+): Promise<StructValueType<T extends unknown ? T[keyof T] : never>> {
     const id = decodeUtf8(await stream.read(4));
 
     if (id === AdbSyncResponseId.Fail) {
@@ -54,5 +60,5 @@ export async function adbSyncReadResponse<T extends Record<string, StructLike<an
         return types[id]!.deserialize(stream);
     }
 
-    throw new Error('Unexpected response id');
+    throw new Error(`Expected '${Object.keys(types).join(', ')}', but got '${id}'`);
 }

package/src/commands/sync/stat.ts

@@ -10,6 +10,19 @@ export enum LinuxFileType {
     Link = 0o12,
 }
 
+export interface AdbSyncStat {
+    mode: number;
+    size: bigint;
+    mtime: bigint;
+    get type(): LinuxFileType;
+    get permission(): number;
+
+    uid?: number;
+    gid?: number;
+    atime?: bigint;
+    ctime?: bigint;
+}
+
 export const AdbSyncLstatResponse =
     new Struct({ littleEndian: true })
         .int32('mode')
@@ -32,6 +45,7 @@ export const AdbSyncLstatResponse =
 export type AdbSyncLstatResponse = typeof AdbSyncLstatResponse['TDeserializeResult'];
 
 export enum AdbSyncStatErrorCode {
+    SUCCESS = 0,
     EACCES = 13,
     EEXIST = 17,
     EFAULT = 14,
@@ -80,15 +94,15 @@ export const AdbSyncStatResponse =
 
 export type AdbSyncStatResponse = typeof AdbSyncStatResponse['TDeserializeResult'];
 
-const StatResponseType = {
+const STAT_RESPONSE_TYPES = {
     [AdbSyncResponseId.Stat]: AdbSyncStatResponse,
 };
 
-const LstatResponseType = {
+const LSTAT_RESPONSE_TYPES = {
     [AdbSyncResponseId.Lstat]: AdbSyncLstatResponse,
 };
 
-const Lstat2ResponseType = {
+const LSTAT_V2_RESPONSE_TYPES = {
     [AdbSyncResponseId.Lstat2]: AdbSyncStatResponse,
 };
 
@@ -97,20 +111,33 @@ export async function adbSyncLstat(
     writer: WritableStreamDefaultWriter<Uint8Array>,
     path: string,
     v2: boolean,
-): Promise<AdbSyncLstatResponse | AdbSyncStatResponse> {
+): Promise<AdbSyncStat> {
     let requestId: AdbSyncRequestId.Lstat | AdbSyncRequestId.Lstat2;
-    let responseType: typeof LstatResponseType | typeof Lstat2ResponseType;
+    let responseType: typeof LSTAT_RESPONSE_TYPES | typeof LSTAT_V2_RESPONSE_TYPES;
 
     if (v2) {
         requestId = AdbSyncRequestId.Lstat2;
-        responseType = Lstat2ResponseType;
+        responseType = LSTAT_V2_RESPONSE_TYPES;
     } else {
         requestId = AdbSyncRequestId.Lstat;
-        responseType = LstatResponseType;
+        responseType = LSTAT_RESPONSE_TYPES;
     }
 
     await adbSyncWriteRequest(writer, requestId, path);
-    return adbSyncReadResponse(stream, responseType);
+    const response = await adbSyncReadResponse(stream, responseType);
+
+    switch (response.id) {
+        case AdbSyncResponseId.Lstat:
+            return {
+                mode: response.mode,
+                size: BigInt(response.size),
+                mtime: BigInt(response.mtime),
+                get type() { return response.type; },
+                get permission() { return response.permission; },
+            };
+        default:
+            return response;
+    }
 }
 
 export async function adbSyncStat(
@@ -119,5 +146,5 @@ export async function adbSyncStat(
     path: string,
 ): Promise<AdbSyncStatResponse> {
     await adbSyncWriteRequest(writer, AdbSyncRequestId.Stat, path);
-    return await adbSyncReadResponse(stream, StatResponseType);
+    return await adbSyncReadResponse(stream, STAT_RESPONSE_TYPES);
 }

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