@yume-chan/adb 0.0.12 → 0.0.15

package/src/socket/dispatcher.ts

@@ -1,97 +1,119 @@
 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 type { RemoveEventListener } from '@yume-chan/event';
+import type { ValueOrPromise } from "@yume-chan/struct";
+
+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;
+const EmptyUint8Array = new Uint8Array(0);
 
-    packet: AdbPacketCore;
+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;
+}
 
-    serviceString: string;
+export type AdbIncomingSocketHandler = (socket: AdbSocket) => ValueOrPromise<boolean>;
 
-    socket: AdbSocket;
+export interface Closeable {
+    close(): ValueOrPromise<void>;
 }
 
-const EmptyUint8Array = new Uint8Array(0);
-
-export class AdbPacketDispatcher extends AutoDisposable {
+/**
+ * The dispatcher is the "dumb" part of the connection handling logic.
+ *
+ * Except some options to change some minor behaviors,
+ * its only job is forwarding packets between authenticated underlying streams
+ * and abstracted socket objects.
+ *
+ * The `Adb` class is responsible for doing the authentication,
+ * negotiating the options, and has shortcuts to high-level services.
+ */
+export class AdbPacketDispatcher implements Closeable {
     // 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 _closed = false;
     private _disconnected = new PromiseResolver<void>();
     public get disconnected() { return this._disconnected.promise; }
 
-    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 _incomingSocketHandlers: Set<AdbIncomingSocketHandler> = new Set();
 
     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) => {
-                    try {
-                        switch (packet.command) {
-                            case AdbCommand.OK:
-                                this.handleOk(packet);
-                                return;
-                            case AdbCommand.Close:
-                                await this.handleClose(packet);
-                                return;
-                            case AdbCommand.Write:
-                                if (this.sockets.has(packet.arg1)) {
-                                    await this.sockets.get(packet.arg1)!.enqueue(packet.payload);
-                                    await this.sendPacket(AdbCommand.OK, packet.arg1, packet.arg0);
-                                }
-
-                                // Maybe the device is responding to a packet of last connection
-                                // Just ignore it
-                                return;
-                            case AdbCommand.Open:
-                                await this.handleOpen(packet);
-                                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;
+                    switch (packet.command) {
+                        case AdbCommand.OK:
+                            this.handleOk(packet);
+                            break;
+                        case AdbCommand.Close:
+                            await this.handleClose(packet);
+                            break;
+                        case AdbCommand.Write:
+                            if (this.sockets.has(packet.arg1)) {
+                                await this.sockets.get(packet.arg1)!.enqueue(packet.payload);
+                                await this.sendPacket(AdbCommand.OK, packet.arg1, packet.arg0);
+                                break;
+                            }
+                            throw new Error(`Unknown local socket id: ${packet.arg1}`);
+                        case AdbCommand.Open:
+                            await this.handleOpen(packet);
+                            break;
+                        default:
+                            // Junk data may only appear in the authentication phase,
+                            // since the dispatcher only works after authentication,
+                            // all packets should have a valid command.
+                            // (although it's possible that Adb added new commands in the future)
+                            throw new Error(`Unknown command: ${packet.command.toString(16)}`);
                     }
                 },
             }), {
-                preventCancel: false,
+                // There are multiple reasons for the pipe to stop,
+                // (device disconnection, protocol error, or user abortion)
+                // if the underlying streams are still open,
+                // it's still possible to create another ADB connection.
+                // So don't close `readable` here.
+                preventCancel: true,
                 signal: this._abortController.signal,
             })
             .then(() => {
                 this.dispose();
-            }, () => {
-                // TODO: AdbPacketDispatcher: reject `_disconnected` when pipe errored?
+            }, (e) => {
+                // https://github.com/MattiasBuelens/web-streams-polyfill/issues/115
+                // `e` is always `AbortError` (instead of what I give in `abortController.abort()`)
+                // so we can't check if `e` is a real error.
+                if (!this._closed) {
+                    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 +131,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
@@ -117,13 +139,18 @@ export class AdbPacketDispatcher extends AutoDisposable {
          * CLOSE() operations.
          */
 
-        // So don't return if `reject` didn't find a pending socket
+        // If the socket is still pending
         if (packet.arg0 === 0 &&
             this.initializers.reject(packet.arg1, new Error('Socket open failed'))) {
             // Device failed to create the socket
+            // (unknown service string, failed to execute command, etc.)
+            // it doesn't break the connection,
+            // so only reject the socket creation promise,
+            // don't throw an error here.
             return;
         }
 
+        // Ignore `arg0` and search for the socket
         const socket = this.sockets.get(packet.arg1);
         if (socket) {
             // The device want to close the socket
@@ -135,11 +162,21 @@ export class AdbPacketDispatcher extends AutoDisposable {
             return;
         }
 
-        // Maybe the device is responding to a packet of last connection
-        // Just ignore it
+        // TODO: adb: is double closing an socket a catastrophic error?
+        // If the client sends two `CLSE` packets for one socket,
+        // the device may also respond with two `CLSE` packets.
     }
 
-    private async handleOpen(packet: AdbPacketCore) {
+    public addIncomingSocketHandler(handler: AdbIncomingSocketHandler): RemoveEventListener {
+        this._incomingSocketHandlers.add(handler);
+        const remove = () => {
+            this._incomingSocketHandlers.delete(handler);
+        };
+        remove.dispose = remove;
+        return remove;
+    }
+
+    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 +185,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,
@@ -156,41 +193,42 @@ export class AdbPacketDispatcher extends AutoDisposable {
             serviceString,
         });
 
-        const args: AdbIncomingSocketEventArgs = {
-            handled: false,
-            packet,
-            serviceString,
-            socket,
-        };
-        this.incomingSocketEvent.fire(args);
-
-        if (args.handled) {
-            this.sockets.set(localId, socket);
-            await this.sendPacket(AdbCommand.OK, localId, remoteId);
-        } else {
-            await this.sendPacket(AdbCommand.Close, 0, remoteId);
+        for (const handler of this._incomingSocketHandlers) {
+            if (await handler(controller.socket)) {
+                this.sockets.set(localId, controller);
+                await this.sendPacket(AdbCommand.OK, localId, remoteId);
+                return;
+            }
         }
+
+        await this.sendPacket(AdbCommand.Close, 0, remoteId);
     }
 
     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 +244,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,34 +261,44 @@ 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;
         }
 
+        await this._writer.ready;
         await this._writer.write(init as AdbPacketInit);
     }
 
-    public override dispose() {
+    public async close() {
+        // Send `CLSE` packets for all sockets
+        await Promise.all(
+            Array.from(
+                this.sockets.values(),
+                socket => socket.close(),
+            )
+        );
+
+        // Stop receiving
+        // It's possible that we haven't received all `CLSE` confirm packets,
+        // but it doesn't matter, the next connection can cope with them.
+        this._closed = true;
+        this._abortController.abort();
+        this._writer.releaseLock();
+
+        // `pipe().then()` will call `dispose`
+    }
+
+    private dispose() {
         for (const socket of this.sockets.values()) {
             socket.dispose();
         }
-        this.sockets.clear();
-
-        try {
-            // Stop pipes
-            this._abortController.abort();
-        } catch { }
-
-        this._writer.releaseLock();
 
         this._disconnected.resolve();
-
-        super.dispose();
     }
 }

package/src/socket/socket.ts

@@ -1,32 +1,24 @@
 import { PromiseResolver } from "@yume-chan/async";
+import type { Disposable } from "@yume-chan/event";
 import { AdbCommand } from '../packet.js';
-import { ChunkStream, DuplexStreamFactory, pipeFrom, ReadableStream, WritableStream, type PushReadableStreamController } from '../stream/index.js';
-import type { AdbPacketDispatcher } from './dispatcher.js';
+import { ChunkStream, DuplexStreamFactory, pipeFrom, PushReadableStream, WritableStream, type PushReadableStreamController, type ReadableStream, type ReadableWritablePair } from '../stream/index.js';
+import type { AdbPacketDispatcher, Closeable } from './dispatcher.js';
 
 export interface AdbSocketInfo {
     localId: number;
     remoteId: number;
 
     localCreated: boolean;
-
     serviceString: string;
 }
 
-export interface AdbSocketConstructionOptions {
+export interface AdbSocketConstructionOptions extends AdbSocketInfo {
     dispatcher: AdbPacketDispatcher;
 
-    localId: number;
-
-    remoteId: number;
-
-    localCreated: boolean;
-
-    serviceString: string;
-
     highWaterMark?: number | undefined;
 }
 
-export class AdbSocket implements AdbSocketInfo {
+export class AdbSocketController implements AdbSocketInfo, ReadableWritablePair<Uint8Array, Uint8Array>, Closeable, Disposable {
     private readonly dispatcher!: AdbPacketDispatcher;
 
     public readonly localId!: number;
@@ -46,6 +38,9 @@ export class AdbSocket implements AdbSocketInfo {
     private _closed = false;
     public get closed() { return this._closed; }
 
+    private _socket: AdbSocket;
+    public get socket() { return this._socket; }
+
     public constructor(options: AdbSocketConstructionOptions) {
         Object.assign(this, options);
 
@@ -55,75 +50,95 @@ export class AdbSocket implements AdbSocketInfo {
 
         this._factory = new DuplexStreamFactory<Uint8Array, Uint8Array>({
             close: async () => {
-                await this.close();
+                await this.dispatcher.sendPacket(
+                    AdbCommand.Close,
+                    this.localId,
+                    this.remoteId
+                );
+
+                // Don't `dispose` here, we need to wait for `CLSE` response packet.
+                return false;
             },
-        });
+            dispose: () => {
+                this._closed = true;
 
-        this._readable = this._factory.createPushReadable(controller => {
-            this._readableController = controller;
-        }, {
-            highWaterMark: options.highWaterMark ?? 16 * 1024,
-            size(chunk) { return chunk.byteLength; }
+                // Error out the pending writes
+                this._writePromise?.reject(new Error('Socket closed'));
+            },
         });
 
+        this._readable = this._factory.wrapReadable(
+            new PushReadableStream(controller => {
+                this._readableController = controller;
+            }, {
+                highWaterMark: options.highWaterMark ?? 16 * 1024,
+                size(chunk) { return chunk.byteLength; }
+            })
+        );
+
         this.writable = pipeFrom(
-            this._factory.createWritable({
-                write: async (chunk) => {
-                    // Wait for an ack packet
-                    this._writePromise = new PromiseResolver();
-                    await this.dispatcher.sendPacket(
-                        AdbCommand.Write,
-                        this.localId,
-                        this.remoteId,
-                        chunk
-                    );
-                    await this._writePromise.promise;
-                },
-            }),
-            new ChunkStream(this.dispatcher.maxPayloadSize)
+            this._factory.createWritable(
+                new WritableStream({
+                    write: async (chunk) => {
+                        // Wait for an ack packet
+                        this._writePromise = new PromiseResolver();
+                        await this.dispatcher.sendPacket(
+                            AdbCommand.Write,
+                            this.localId,
+                            this.remoteId,
+                            chunk
+                        );
+                        await this._writePromise.promise;
+                    }
+                }),
+            ),
+            new ChunkStream(this.dispatcher.options.maxPayloadSize)
         );
+
+        this._socket = new AdbSocket(this);
     }
 
-    /**
-     * @internal
-     */
     public async enqueue(packet: Uint8Array) {
         await this._readableController.enqueue(packet);
     }
 
-    /**
-     * @internal
-     */
     public ack() {
         this._writePromise?.resolve();
     }
 
     public async close(): Promise<void> {
-        // Error out the pending writes
-        this._writePromise?.reject(new Error('Socket closed'));
-
-        if (!this._closed) {
-            this._closed = true;
-
-            // Only send close packet when `close` is called before `dispose`
-            // (the client initiated the close)
-            await this.dispatcher.sendPacket(
-                AdbCommand.Close,
-                this.localId,
-                this.remoteId
-            );
-        }
+        this._factory.close();
     }
 
-    /**
-     * @internal
-     */
     public dispose() {
-        this._closed = true;
+        this._factory.dispose();
+    }
+}
 
-        this._factory.close();
+/**
+ * AdbSocket is a duplex stream.
+ *
+ * To close it, call either `socket.close()`,
+ * `socket.readable.cancel()`, `socket.readable.getReader().cancel()`,
+ * `socket.writable.abort()`, `socket.writable.getWriter().abort()`,
+ * `socket.writable.close()` or `socket.writable.getWriter().close()`.
+ */
+export class AdbSocket implements AdbSocketInfo, ReadableWritablePair<Uint8Array, Uint8Array>{
+    private _controller: AdbSocketController;
+
+    public get localId(): number { return this._controller.localId; }
+    public get remoteId(): number { return this._controller.remoteId; }
+    public get localCreated(): boolean { return this._controller.localCreated; }
+    public get serviceString(): string { return this._controller.serviceString; }
+
+    public get readable(): ReadableStream<Uint8Array> { return this._controller.readable; }
+    public get writable(): WritableStream<Uint8Array> { return this._controller.writable; }
+
+    public constructor(controller: AdbSocketController) {
+        this._controller = controller;
+    }
 
-        // Close `writable` side
-        this.close();
+    public close() {
+        return this._controller.close();
     }
 }

package/src/stream/buffered.ts

@@ -123,8 +123,8 @@ export class BufferedStream {
         }
     }
 
-    public close() {
-        this.reader.cancel();
+    public async close() {
+        await this.reader.cancel();
     }
 }
 

package/src/stream/detect.polyfill.ts

@@ -1,7 +1,10 @@
 // cspell: ignore ponyfill
 
 import type { AbortSignal } from "web-streams-polyfill";
-// TODO: import the ponyfill instead (as a library should do)
+// TODO: Upgrade to `web-streams-polyfill@4.0.0-beta.2` once released.
+// `web-streams-polyfill@4.0.0-beta.1` changed the default export to ponyfill,
+// But it forgot to include `type` export so it's unusable.
+// See https://github.com/MattiasBuelens/web-streams-polyfill/pull/107
 export * from 'web-streams-polyfill';
 
 /** A controller object that allows you to abort one or more DOM requests as and when desired. */
@@ -14,7 +17,7 @@ export interface AbortController {
     /**
      * Invoking this method will set this object's AbortSignal's aborted flag and signal to any observers that the associated activity is to be aborted.
      */
-    abort(): void;
+    abort(reason?: any): void;
 }
 
 export let AbortController: {

package/src/stream/detect.ts

@@ -1,25 +1,5 @@
-// cspell: ignore ponyfill
+// cspell: ignore vercel
 
-import type { AbortSignal } from "web-streams-polyfill";
-// TODO: import the ponyfill instead (as a library should do)
-export * from 'web-streams-polyfill';
-
-/** A controller object that allows you to abort one or more DOM requests as and when desired. */
-export interface AbortController {
-    /**
-     * Returns the AbortSignal object associated with this object.
-     */
-
-    readonly signal: AbortSignal;
-    /**
-     * Invoking this method will set this object's AbortSignal's aborted flag and signal to any observers that the associated activity is to be aborted.
-     */
-    abort(): void;
-}
-
-export let AbortController: {
-    prototype: AbortController;
-    new(): AbortController;
-};
-
-({ AbortController } = globalThis as any);
+// Always use polyfilled version because
+// Vercel doesn't support Node.js 16 (`streams/web` module) yet
+export * from './detect.polyfill.js';