@yume-chan/adb 0.0.9 → 0.0.10

package/src/commands/shell/protocol.ts

@@ -1,94 +1,121 @@
-import { EventEmitter } from "@yume-chan/event";
-import Struct, { placeholder } from "@yume-chan/struct";
-import { AdbSocket } from "../../socket";
-import { AdbBufferedStream } from "../../stream";
-import { AdbShell } from "./types";
-
-export enum AdbShellProtocolId {
-    Stdin,
-    Stdout,
-    Stderr,
-    Exit,
-    CloseStdin,
-    WindowSizeChange,
-}
-
-const AdbShellProtocolPacket = new Struct({ littleEndian: true })
-    .uint8('id', placeholder<AdbShellProtocolId>())
-    .uint32('length')
-    .arrayBuffer('data', { lengthField: 'length' });
-
-/**
- * Shell v2 is also called Shell Protocol
- */
-export class AdbShellProtocol implements AdbShell {
-    private readonly stream: AdbBufferedStream;
-
-    private readonly stdoutEvent = new EventEmitter<ArrayBuffer>();
-    public get onStdout() { return this.stdoutEvent.event; }
-
-    private readonly stderrEvent = new EventEmitter<ArrayBuffer>();
-    public get onStderr() { return this.stderrEvent.event; }
-
-    private readonly exitEvent = new EventEmitter<number>();
-    public get onExit() { return this.exitEvent.event; }
-
-    public constructor(socket: AdbSocket) {
-        this.stream = new AdbBufferedStream(socket);
-        this.readData();
-    }
-
-    private async readData() {
-        while (true) {
-            try {
-                const packet = await AdbShellProtocolPacket.deserialize(this.stream);
-                switch (packet.id) {
-                    case AdbShellProtocolId.Stdout:
-                        this.stdoutEvent.fire(packet.data);
-                        break;
-                    case AdbShellProtocolId.Stderr:
-                        this.stderrEvent.fire(packet.data);
-                        break;
-                    case AdbShellProtocolId.Exit:
-                        this.exitEvent.fire(new Uint8Array(packet.data)[0]);
-                        break;
-                }
-            } catch {
-                return;
-            }
-        }
-    }
-
-    public async write(data: ArrayBuffer) {
-        this.stream.write(
-            AdbShellProtocolPacket.serialize(
-                {
-                    id: AdbShellProtocolId.Stdin,
-                    data,
-                },
-                this.stream
-            )
-        );
-    }
-
-    public async resize(rows: number, cols: number) {
-        this.stream.write(
-            AdbShellProtocolPacket.serialize(
-                {
-                    id: AdbShellProtocolId.WindowSizeChange,
-                    data: this.stream.encodeUtf8(
-                        // Correct format is ${rows}x${cols},${x_pixels}x${y_pixels}
-                        // But from https://linux.die.net/man/4/tty_ioctl
-                        // x_pixels and y_pixels are unused
-                        `${rows}x${cols},${0}x${0}\0`
-                    ),
-                },
-                this.stream
-            )
-        );
-    }
-
-    public kill() {
-        return this.stream.close();
-    }
-}
+import { EventEmitter } from "@yume-chan/event";
+import Struct, { placeholder } from "@yume-chan/struct";
+import type { Adb } from "../../adb";
+import { AdbFeatures } from "../../features";
+import type { AdbSocket } from "../../socket";
+import { AdbBufferedStream } from "../../stream";
+import { encodeUtf8 } from "../../utils";
+import type { AdbShell } from "./types";
+
+export enum AdbShellProtocolId {
+    Stdin,
+    Stdout,
+    Stderr,
+    Exit,
+    CloseStdin,
+    WindowSizeChange,
+}
+
+// This packet format is used in both direction.
+const AdbShellProtocolPacket = new Struct({ littleEndian: true })
+    .uint8('id', placeholder<AdbShellProtocolId>())
+    .uint32('length')
+    .arrayBuffer('data', { lengthField: 'length' });
+
+function assertUnreachable(x: never): never {
+    throw new Error("Unreachable");
+}
+
+/**
+ * Shell v2 a.k.a Shell Protocol
+ *
+ * Features:
+ * * `onStderr`: Yes
+ * * `onExit` exit code: Yes
+ * * `resize`: Yes
+ */
+export class AdbShellProtocol implements AdbShell {
+    public static isSupported(adb: Adb) {
+        return adb.features!.includes(AdbFeatures.ShellV2);
+    }
+
+    public static async spawn(adb: Adb, command: string) {
+        // TODO: the service string may support more parameters
+        return new AdbShellProtocol(await adb.createSocket(`shell,v2,pty:${command}`));
+    }
+
+    private readonly stream: AdbBufferedStream;
+
+    private readonly stdoutEvent = new EventEmitter<ArrayBuffer>();
+    public get onStdout() { return this.stdoutEvent.event; }
+
+    private readonly stderrEvent = new EventEmitter<ArrayBuffer>();
+    public get onStderr() { return this.stderrEvent.event; }
+
+    private readonly exitEvent = new EventEmitter<number>();
+    public get onExit() { return this.exitEvent.event; }
+
+    public constructor(socket: AdbSocket) {
+        this.stream = new AdbBufferedStream(socket);
+        this.readData();
+    }
+
+    private async readData() {
+        while (true) {
+            try {
+                const packet = await AdbShellProtocolPacket.deserialize(this.stream);
+                switch (packet.id) {
+                    case AdbShellProtocolId.Stdout:
+                        this.stdoutEvent.fire(packet.data);
+                        break;
+                    case AdbShellProtocolId.Stderr:
+                        this.stderrEvent.fire(packet.data);
+                        break;
+                    case AdbShellProtocolId.Exit:
+                        this.exitEvent.fire(new Uint8Array(packet.data)[0]);
+                        break;
+                    case AdbShellProtocolId.CloseStdin:
+                    case AdbShellProtocolId.Stdin:
+                    case AdbShellProtocolId.WindowSizeChange:
+                        // These ids are client-to-server
+                        throw new Error('unreachable');
+                    default:
+                        assertUnreachable(packet.id);
+                }
+            } catch {
+                return;
+            }
+        }
+    }
+
+    public async write(data: ArrayBuffer) {
+        this.stream.write(
+            AdbShellProtocolPacket.serialize(
+                {
+                    id: AdbShellProtocolId.Stdin,
+                    data,
+                }
+            )
+        );
+    }
+
+    public async resize(rows: number, cols: number) {
+        await this.stream.write(
+            AdbShellProtocolPacket.serialize(
+                {
+                    id: AdbShellProtocolId.WindowSizeChange,
+                    data: encodeUtf8(
+                        // The "correct" format is `${rows}x${cols},${x_pixels}x${y_pixels}`
+                        // However, according to https://linux.die.net/man/4/tty_ioctl
+                        // `x_pixels` and `y_pixels` are not used, so always pass `0` is fine.
+                        `${rows}x${cols},0x0\0`
+                    ),
+                }
+            )
+        );
+    }
+
+    public kill() {
+        return this.stream.close();
+    }
+}

package/src/commands/shell/types.ts

@@ -1,21 +1,55 @@
-import { Event } from "@yume-chan/event";
-import { ValueOrPromise } from "@yume-chan/struct";
-import { AdbSocket } from "../../socket";
-
-export interface AdbShell {
-    readonly onStdout: Event<ArrayBuffer>;
-
-    readonly onStderr: Event<ArrayBuffer>;
-
-    readonly onExit: Event<number>;
-
-    write(data: ArrayBuffer): Promise<void>;
-
-    resize(rows: number, cols: number): ValueOrPromise<void>;
-
-    kill(): ValueOrPromise<void>;
-}
-
-export interface AdbShellConstructor {
-    new(socket: AdbSocket): AdbShell;
-}
+import type { Event } from "@yume-chan/event";
+import type { ValueOrPromise } from "@yume-chan/struct";
+import type { Adb } from "../../adb";
+import type { AdbSocket } from "../../socket";
+
+export interface AdbShell {
+    /**
+     * Notifies that new data has been written into the `stdout` stream.
+     */
+    readonly onStdout: Event<ArrayBuffer>;
+
+    /**
+     * Notifies that new data has been written into the `stderr` stream.
+     *
+     * Some `AdbShell`s may not support separate output streams
+     * and will always fire the `onStdout` event instead.
+     */
+    readonly onStderr: Event<ArrayBuffer>;
+
+    /**
+     * Notifies that the current process has exited.
+     *
+     * The event arg is the exit code.
+     * Some `AdbShell`s may not support returning exit code and will always return `0` instead.
+     */
+    readonly onExit: Event<number>;
+
+    /**
+     * Writes raw PTY data into the `stdin` stream.
+     */
+    write(data: ArrayBuffer): Promise<void>;
+
+    /**
+     * Resizes the current shell.
+     *
+     * Some `AdbShell`s may not support resizing and will always ignore calls to this method.
+     */
+    resize(rows: number, cols: number): ValueOrPromise<void>;
+
+    /**
+     * Kills the current process.
+     */
+    kill(): ValueOrPromise<void>;
+}
+
+export interface AdbShellConstructor {
+    /** 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<AdbShell>;
+
+    /** Creates a new `AdbShell` by attaching to an exist `AdbSocket` */
+    new(socket: AdbSocket): AdbShell;
+}

package/src/commands/shell/utils.ts

@@ -1,20 +1,20 @@
-export function escapeArg(s: string) {
-    let result = '';
-    result += `'`;
-
-    let base = 0;
-    while (true) {
-        const found = s.indexOf(`'`, base);
-        if (found === -1) {
-            result += s.substring(base);
-            break;
-        }
-        result += s.substring(base, found);
-        // a'b becomes a'\'b
-        result += String.raw`'\''`;
-        base = found + 1;
-    }
-
-    result += `'`;
-    return result;
-}
+export function escapeArg(s: string) {
+    let result = '';
+    result += `'`;
+
+    let base = 0;
+    while (true) {
+        const found = s.indexOf(`'`, base);
+        if (found === -1) {
+            result += s.substring(base);
+            break;
+        }
+        result += s.substring(base, found);
+        // a'b becomes a'\'b
+        result += String.raw`'\''`;
+        base = found + 1;
+    }
+
+    result += `'`;
+    return result;
+}

package/src/commands/sync/index.ts

@@ -1,7 +1,7 @@
-export * from './list';
-export * from './pull';
-export * from './request';
-export * from './response';
-export * from './push';
-export * from './stat';
-export * from './sync';
+export * from './list';
+export * from './pull';
+export * from './request';
+export * from './response';
+export * from './push';
+export * from './stat';
+export * from './sync';

package/src/commands/sync/list.ts

@@ -1,39 +1,39 @@
-import Struct from '@yume-chan/struct';
-import { AdbBufferedStream } from '../../stream';
-import { AdbSyncRequestId, adbSyncWriteRequest } from './request';
-import { AdbSyncDoneResponse, adbSyncReadResponse, AdbSyncResponseId } from './response';
-import { AdbSyncLstatResponse } from './stat';
-
-export const AdbSyncEntryResponse =
-    new Struct({ littleEndian: true })
-        .fields(AdbSyncLstatResponse)
-        .uint32('nameLength')
-        .string('name', { lengthField: 'nameLength' })
-        .extra({ id: AdbSyncResponseId.Entry as const });
-
-export type AdbSyncEntryResponse = typeof AdbSyncEntryResponse['TDeserializeResult'];
-
-const ResponseTypes = {
-    [AdbSyncResponseId.Entry]: AdbSyncEntryResponse,
-    [AdbSyncResponseId.Done]: new AdbSyncDoneResponse(AdbSyncEntryResponse.size),
-};
-
-export async function* adbSyncOpenDir(
-    stream: AdbBufferedStream,
-    path: string
-): AsyncGenerator<AdbSyncEntryResponse, void, void> {
-    await adbSyncWriteRequest(stream, AdbSyncRequestId.List, path);
-
-    while (true) {
-        const response = await adbSyncReadResponse(stream, ResponseTypes);
-        switch (response.id) {
-            case AdbSyncResponseId.Entry:
-                yield response;
-                break;
-            case AdbSyncResponseId.Done:
-                return;
-            default:
-                throw new Error('Unexpected response id');
-        }
-    }
-}
+import Struct from '@yume-chan/struct';
+import { AdbBufferedStream } from '../../stream';
+import { AdbSyncRequestId, adbSyncWriteRequest } from './request';
+import { AdbSyncDoneResponse, adbSyncReadResponse, AdbSyncResponseId } from './response';
+import { AdbSyncLstatResponse } from './stat';
+
+export const AdbSyncEntryResponse =
+    new Struct({ littleEndian: true })
+        .fields(AdbSyncLstatResponse)
+        .uint32('nameLength')
+        .string('name', { lengthField: 'nameLength' })
+        .extra({ id: AdbSyncResponseId.Entry as const });
+
+export type AdbSyncEntryResponse = typeof AdbSyncEntryResponse['TDeserializeResult'];
+
+const ResponseTypes = {
+    [AdbSyncResponseId.Entry]: AdbSyncEntryResponse,
+    [AdbSyncResponseId.Done]: new AdbSyncDoneResponse(AdbSyncEntryResponse.size),
+};
+
+export async function* adbSyncOpenDir(
+    stream: AdbBufferedStream,
+    path: string
+): AsyncGenerator<AdbSyncEntryResponse, void, void> {
+    await adbSyncWriteRequest(stream, AdbSyncRequestId.List, path);
+
+    while (true) {
+        const response = await adbSyncReadResponse(stream, ResponseTypes);
+        switch (response.id) {
+            case AdbSyncResponseId.Entry:
+                yield response;
+                break;
+            case AdbSyncResponseId.Done:
+                return;
+            default:
+                throw new Error('Unexpected response id');
+        }
+    }
+}

package/src/commands/sync/pull.ts

@@ -1,34 +1,34 @@
-import Struct from '@yume-chan/struct';
-import { AdbBufferedStream } from '../../stream';
-import { AdbSyncRequestId, adbSyncWriteRequest } from './request';
-import { AdbSyncDoneResponse, adbSyncReadResponse, AdbSyncResponseId } from './response';
-
-export const AdbSyncDataResponse =
-    new Struct({ littleEndian: true })
-        .uint32('dataLength')
-        .arrayBuffer('data', { lengthField: 'dataLength' })
-        .extra({ id: AdbSyncResponseId.Data as const });
-
-const ResponseTypes = {
-    [AdbSyncResponseId.Data]: AdbSyncDataResponse,
-    [AdbSyncResponseId.Done]: new AdbSyncDoneResponse(AdbSyncDataResponse.size),
-};
-
-export async function* adbSyncPull(
-    stream: AdbBufferedStream,
-    path: string,
-): AsyncGenerator<ArrayBuffer, void, void> {
-    await adbSyncWriteRequest(stream, AdbSyncRequestId.Receive, path);
-    while (true) {
-        const response = await adbSyncReadResponse(stream, ResponseTypes);
-        switch (response.id) {
-            case AdbSyncResponseId.Data:
-                yield response.data!;
-                break;
-            case AdbSyncResponseId.Done:
-                return;
-            default:
-                throw new Error('Unexpected response id');
-        }
-    }
-}
+import Struct from '@yume-chan/struct';
+import { AdbBufferedStream } from '../../stream';
+import { AdbSyncRequestId, adbSyncWriteRequest } from './request';
+import { AdbSyncDoneResponse, adbSyncReadResponse, AdbSyncResponseId } from './response';
+
+export const AdbSyncDataResponse =
+    new Struct({ littleEndian: true })
+        .uint32('dataLength')
+        .arrayBuffer('data', { lengthField: 'dataLength' })
+        .extra({ id: AdbSyncResponseId.Data as const });
+
+const ResponseTypes = {
+    [AdbSyncResponseId.Data]: AdbSyncDataResponse,
+    [AdbSyncResponseId.Done]: new AdbSyncDoneResponse(AdbSyncDataResponse.size),
+};
+
+export async function* adbSyncPull(
+    stream: AdbBufferedStream,
+    path: string,
+): AsyncGenerator<ArrayBuffer, void, void> {
+    await adbSyncWriteRequest(stream, AdbSyncRequestId.Receive, path);
+    while (true) {
+        const response = await adbSyncReadResponse(stream, ResponseTypes);
+        switch (response.id) {
+            case AdbSyncResponseId.Data:
+                yield response.data!;
+                break;
+            case AdbSyncResponseId.Done:
+                return;
+            default:
+                throw new Error('Unexpected response id');
+        }
+    }
+}

package/src/commands/sync/push.ts

@@ -1,46 +1,46 @@
-import Struct from '@yume-chan/struct';
-import { AdbBufferedStream } from '../../stream';
-import { chunkArrayLike, chunkAsyncIterable } from '../../utils';
-import { AdbSyncRequestId, adbSyncWriteRequest } from './request';
-import { adbSyncReadResponse, AdbSyncResponseId } from './response';
-import { LinuxFileType } from './stat';
-
-export const AdbSyncOkResponse =
-    new Struct({ littleEndian: true })
-        .uint32('unused');
-
-const ResponseTypes = {
-    [AdbSyncResponseId.Ok]: AdbSyncOkResponse,
-};
-
-export const AdbSyncMaxPacketSize = 64 * 1024;
-
-export async function adbSyncPush(
-    stream: AdbBufferedStream,
-    filename: string,
-    content: ArrayLike<number> | ArrayBufferLike | AsyncIterable<ArrayBuffer>,
-    mode: number = (LinuxFileType.File << 12) | 0o666,
-    mtime: number = (Date.now() / 1000) | 0,
-    packetSize: number = AdbSyncMaxPacketSize,
-    onProgress?: (uploaded: number) => void,
-): Promise<void> {
-    const pathAndMode = `${filename},${mode.toString()}`;
-    await adbSyncWriteRequest(stream, AdbSyncRequestId.Send, pathAndMode);
-
-    let chunkReader: Iterable<ArrayBuffer> | AsyncIterable<ArrayBuffer>;
-    if ('length' in content || 'byteLength' in content) {
-        chunkReader = chunkArrayLike(content, packetSize);
-    } else {
-        chunkReader = chunkAsyncIterable(content, packetSize);
-    }
-
-    let uploaded = 0;
-    for await (const buffer of chunkReader) {
-        await adbSyncWriteRequest(stream, AdbSyncRequestId.Data, buffer);
-        uploaded += buffer.byteLength;
-        onProgress?.(uploaded);
-    }
-
-    await adbSyncWriteRequest(stream, AdbSyncRequestId.Done, mtime);
-    await adbSyncReadResponse(stream, ResponseTypes);
-}
+import Struct from '@yume-chan/struct';
+import { AdbBufferedStream } from '../../stream';
+import { chunkArrayLike, chunkAsyncIterable } from '../../utils';
+import { AdbSyncRequestId, adbSyncWriteRequest } from './request';
+import { adbSyncReadResponse, AdbSyncResponseId } from './response';
+import { LinuxFileType } from './stat';
+
+export const AdbSyncOkResponse =
+    new Struct({ littleEndian: true })
+        .uint32('unused');
+
+const ResponseTypes = {
+    [AdbSyncResponseId.Ok]: AdbSyncOkResponse,
+};
+
+export const AdbSyncMaxPacketSize = 64 * 1024;
+
+export async function adbSyncPush(
+    stream: AdbBufferedStream,
+    filename: string,
+    content: ArrayLike<number> | ArrayBufferLike | AsyncIterable<ArrayBuffer>,
+    mode: number = (LinuxFileType.File << 12) | 0o666,
+    mtime: number = (Date.now() / 1000) | 0,
+    packetSize: number = AdbSyncMaxPacketSize,
+    onProgress?: (uploaded: number) => void,
+): Promise<void> {
+    const pathAndMode = `${filename},${mode.toString()}`;
+    await adbSyncWriteRequest(stream, AdbSyncRequestId.Send, pathAndMode);
+
+    let chunkReader: Iterable<ArrayBuffer> | AsyncIterable<ArrayBuffer>;
+    if ('length' in content || 'byteLength' in content) {
+        chunkReader = chunkArrayLike(content, packetSize);
+    } else {
+        chunkReader = chunkAsyncIterable(content, packetSize);
+    }
+
+    let uploaded = 0;
+    for await (const buffer of chunkReader) {
+        await adbSyncWriteRequest(stream, AdbSyncRequestId.Data, buffer);
+        uploaded += buffer.byteLength;
+        onProgress?.(uploaded);
+    }
+
+    await adbSyncWriteRequest(stream, AdbSyncRequestId.Done, mtime);
+    await adbSyncReadResponse(stream, ResponseTypes);
+}