@yume-chan/adb 0.0.11 → 0.0.14

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, type PushReadableStreamController, type ReadableStream, type ReadableWritablePair, type WritableStream } 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,17 +50,32 @@ 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) => {
@@ -80,50 +90,53 @@ export class AdbSocket implements AdbSocketInfo {
                     await this._writePromise.promise;
                 },
             }),
-            new ChunkStream(this.dispatcher.maxPayloadSize)
+            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/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. */

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';

package/src/stream/transform.ts

@@ -1,93 +1,57 @@
 import { PromiseResolver } from "@yume-chan/async";
 import type Struct from "@yume-chan/struct";
-import type { StructValueType } from "@yume-chan/struct";
+import type { StructValueType, ValueOrPromise } from "@yume-chan/struct";
 import { decodeUtf8 } from "../utils/index.js";
 import { BufferedStream, BufferedStreamEndedError } from "./buffered.js";
-import { AbortController, AbortSignal, ReadableStream, ReadableStreamDefaultReader, TransformStream, WritableStream, WritableStreamDefaultWriter, type QueuingStrategy, type ReadableStreamDefaultController, type ReadableWritablePair, type UnderlyingSink, type UnderlyingSource } from "./detect.js";
+import { AbortController, AbortSignal, ReadableStream, ReadableStreamDefaultReader, TransformStream, WritableStream, WritableStreamDefaultWriter, type QueuingStrategy, type ReadableStreamDefaultController, type ReadableWritablePair, type UnderlyingSink } from "./detect.js";
 
 export interface DuplexStreamFactoryOptions {
-    preventCloseReadableStreams?: boolean | undefined;
+    close?: (() => ValueOrPromise<boolean | void>) | undefined;
 
-    close?: (() => void | Promise<void>) | undefined;
+    dispose?: (() => void | Promise<void>) | undefined;
 }
 
+/**
+ * A factory for creating a duplex stream.
+ *
+ * It can create multiple `ReadableStream`s and `WritableStream`s,
+ * when any of them is closed, all other streams will be closed as well.
+ */
 export class DuplexStreamFactory<R, W> {
     private readableControllers: ReadableStreamDefaultController<R>[] = [];
-    private pushReadableControllers: PushReadableStreamController<R>[] = [];
+
+    private _writableClosed = false;
+    public get writableClosed() { return this._writableClosed; }
 
     private _closed = new PromiseResolver<void>();
     public get closed() { return this._closed.promise; }
 
     private options: DuplexStreamFactoryOptions;
 
-    private _closeRequestedByReadable = false;
-    private _writableClosed = false;
-
     public constructor(options?: DuplexStreamFactoryOptions) {
         this.options = options ?? {};
     }
 
-    public createPushReadable(source: PushReadableStreamSource<R>, strategy?: QueuingStrategy<R>): PushReadableStream<R> {
-        return new PushReadableStream<R>(controller => {
-            this.pushReadableControllers.push(controller);
-
-            controller.abortSignal.addEventListener('abort', async () => {
-                this._closeRequestedByReadable = true;
+    public wrapReadable(readable: ReadableStream<R>): WrapReadableStream<R> {
+        return new WrapReadableStream<R>({
+            start: (controller) => {
+                this.readableControllers.push(controller);
+                return readable;
+            },
+            cancel: async () => {
+                // cancel means the local peer closes the connection first.
                 await this.close();
-            });
-
-            source({
-                abortSignal: controller.abortSignal,
-                async enqueue(chunk) {
-                    await controller.enqueue(chunk);
-                },
-                close: async () => {
-                    controller.close();
-                    this._closeRequestedByReadable = true;
-                    await this.close();
-                },
-                error: async (e?: any) => {
-                    controller.error(e);
-                    this._closeRequestedByReadable = true;
-                    await this.close();
-                },
-            });
-        }, strategy);
-    };
-
-    public createWrapReadable(readable: ReadableStream<R>): WrapReadableStream<R, ReadableStream<R>, void> {
-        return new WrapReadableStream<R, ReadableStream<R>, void>({
-            async start() {
-                return {
-                    readable,
-                    state: undefined,
-                };
             },
             close: async () => {
-                this._closeRequestedByReadable = true;
-                await this.close();
+                // stream end means the remote peer closed the connection first.
+                await this.dispose();
             },
         });
     }
 
-    public createReadable(source?: UnderlyingSource<R>, strategy?: QueuingStrategy<R>): ReadableStream<R> {
-        return new ReadableStream<R>({
-            start: async (controller) => {
-                this.readableControllers.push(controller);
-                await source?.start?.(controller);
-            },
-            pull: (controller) => {
-                return source?.pull?.(controller);
-            },
-            cancel: async (reason) => {
-                await source?.cancel?.(reason);
-                this._closeRequestedByReadable = true;
-                await this.close();
-            },
-        }, strategy);
-    }
-
     public createWritable(sink: UnderlyingSink<W>, strategy?: QueuingStrategy<W>): WritableStream<W> {
+        // `WritableStream` has no way to tell if the remote peer has closed the connection.
+        // So it only triggers `close`.
         return new WritableStream<W>({
             start: async (controller) => {
                 await sink.start?.(controller);
@@ -99,41 +63,37 @@ export class DuplexStreamFactory<R, W> {
 
                 await sink.write?.(chunk, controller);
             },
-            close: async () => {
-                await sink.close?.();
-                this.close();
-            },
             abort: async (reason) => {
                 await sink.abort?.(reason);
                 await this.close();
             },
+            close: async () => {
+                await sink.close?.();
+                await this.close();
+            },
         }, strategy);
     }
 
-    public async closeReadableStreams() {
-        this._closed.resolve();
-        await this.options.close?.();
-
-        for (const controller of this.readableControllers) {
-            try {
-                controller.close();
-            } catch { }
+    public async close() {
+        if (this._writableClosed) {
+            return;
         }
-
-        for (const controller of this.pushReadableControllers) {
-            try {
-                controller.close();
-            } catch { }
+        this._writableClosed = true;
+        if (await this.options.close?.() !== false) {
+            // `close` can return `false` to disable automatic `dispose`.
+            await this.dispose();
         }
     }
 
-    public async close() {
+    public async dispose() {
         this._writableClosed = true;
+        this._closed.resolve();
 
-        if (this._closeRequestedByReadable ||
-            !this.options.preventCloseReadableStreams) {
-            await this.closeReadableStreams();
+        for (const controller of this.readableControllers) {
+            try { controller.close(); } catch { }
         }
+
+        await this.options.dispose?.();
     }
 }
 
@@ -147,21 +107,21 @@ export class DecodeUtf8Stream extends TransformStream<Uint8Array, string>{
     }
 }
 
-export class GatherStringStream extends TransformStream<string, string>{
+export class GatherStringStream extends WritableStream<string>{
     // Optimization: rope (concat strings) is faster than `[].join('')`
     private _result = '';
     public get result() { return this._result; }
 
     public constructor() {
         super({
-            transform: (chunk) => {
+            write: (chunk) => {
                 this._result += chunk;
             },
         });
     }
 }
 
-// TODO: Find other ways to implement `StructTransformStream`
+// TODO: StructTransformStream: Looking for better implementation
 export class StructDeserializeStream<T extends Struct<any, any, any, any>>
     implements ReadableWritablePair<Uint8Array, StructValueType<T>>{
     private _readable: ReadableStream<StructValueType<T>>;
@@ -219,25 +179,43 @@ export class StructSerializeStream<T extends Struct<any, any, any, any>>
     }
 }
 
-export interface WritableStreamWrapper<T, W extends WritableStream<T>, S> {
-    start(): Promise<{ writable: W, state: S; }>;
-    close?(state: S): Promise<void>;
+export type WrapWritableStreamStart<T> = () => ValueOrPromise<WritableStream<T>>;
+
+export interface WritableStreamWrapper<T> {
+    start: WrapWritableStreamStart<T>;
+    close?(): Promise<void>;
+}
+
+async function getWrappedWritableStream<T>(
+    wrapper: WritableStream<T> | WrapWritableStreamStart<T> | WritableStreamWrapper<T>
+) {
+    if ('start' in wrapper) {
+        return await wrapper.start();
+    } else if (typeof wrapper === 'function') {
+        return await wrapper();
+    } else {
+        // Can't use `wrapper instanceof WritableStream`
+        // Because we want to be compatible with any WritableStream-like objects
+        return wrapper;
+    }
 }
 
-export class WrapWritableStream<T, W extends WritableStream<T>, S> extends WritableStream<T>{
-    public writable!: W;
+export class WrapWritableStream<T> extends WritableStream<T> {
+    public writable!: WritableStream<T>;
 
     private writer!: WritableStreamDefaultWriter<T>;
 
-    private state!: S;
-
-    public constructor(wrapper: WritableStreamWrapper<T, W, S>) {
+    public constructor(wrapper: WritableStream<T> | WrapWritableStreamStart<T> | WritableStreamWrapper<T>) {
         super({
             start: async () => {
-                const { writable, state } = await wrapper.start();
-                this.writable = writable;
-                this.writer = writable.getWriter();
-                this.state = state;
+                // `start` is invoked before `ReadableStream`'s constructor finish,
+                // so using `this` synchronously causes
+                // "Must call super constructor in derived class before accessing 'this' or returning from derived constructor".
+                // Queue a microtask to avoid this.
+                await Promise.resolve();
+
+                this.writable = await getWrappedWritableStream(wrapper);
+                this.writer = this.writable.getWriter();
             },
             write: async (chunk) => {
                 // Maintain back pressure
@@ -246,45 +224,84 @@ export class WrapWritableStream<T, W extends WritableStream<T>, S> extends Writa
             },
             abort: async (reason) => {
                 await this.writer.abort(reason);
-                wrapper.close?.(this.state);
+                if ('close' in wrapper) {
+                    await wrapper.close?.();
+                }
             },
             close: async () => {
+                // Close the inner stream first.
+                // Usually the inner stream is a logical sub-stream over the outer stream,
+                // closing the outer stream first will make the inner stream incapable of
+                // sending data in its `close` handler.
                 await this.writer.close();
-                await wrapper.close?.(this.state);
+                if ('close' in wrapper) {
+                    await wrapper.close?.();
+                }
             },
         });
     }
 }
 
-export interface ReadableStreamWrapper<T, R extends ReadableStream<T>, S> {
-    start(): Promise<{ readable: R, state: S; }>;
-    close?(state: S): Promise<void>;
+export type WrapReadableStreamStart<T> = (controller: ReadableStreamDefaultController<T>) => ValueOrPromise<ReadableStream<T>>;
+
+export interface ReadableStreamWrapper<T> {
+    start: WrapReadableStreamStart<T>;
+    cancel?(reason?: any): ValueOrPromise<void>;
+    close?(): ValueOrPromise<void>;
 }
 
-export class WrapReadableStream<T, R extends ReadableStream<T>, S> extends ReadableStream<T>{
-    public readable!: R;
+function getWrappedReadableStream<T>(
+    wrapper: ReadableStream<T> | WrapReadableStreamStart<T> | ReadableStreamWrapper<T>,
+    controller: ReadableStreamDefaultController<T>
+) {
+    if ('start' in wrapper) {
+        return wrapper.start(controller);
+    } else if (typeof wrapper === 'function') {
+        return wrapper(controller);
+    } else {
+        // Can't use `wrapper instanceof ReadableStream`
+        // Because we want to be compatible with any ReadableStream-like objects
+        return wrapper;
+    }
+}
 
-    private reader!: ReadableStreamDefaultReader<T>;
+/**
+ * This class has multiple usages:
+ *
+ * 1. Get notified when the stream is cancelled or closed.
+ * 2. Synchronously create a `ReadableStream` by asynchronously return another `ReadableStream`.
+ * 3. Convert native `ReadableStream`s to polyfilled ones so they can `pipe` between.
+ */
+export class WrapReadableStream<T> extends ReadableStream<T>{
+    public readable!: ReadableStream<T>;
 
-    private state!: S;
+    private reader!: ReadableStreamDefaultReader<T>;
 
-    public constructor(wrapper: ReadableStreamWrapper<T, R, S>) {
+    public constructor(wrapper: ReadableStream<T> | WrapReadableStreamStart<T> | ReadableStreamWrapper<T>) {
         super({
-            start: async () => {
-                const { readable, state } = await wrapper.start();
-                this.readable = readable;
-                this.reader = readable.getReader();
-                this.state = state;
+            start: async (controller) => {
+                // `start` is invoked before `ReadableStream`'s constructor finish,
+                // so using `this` synchronously causes
+                // "Must call super constructor in derived class before accessing 'this' or returning from derived constructor".
+                // Queue a microtask to avoid this.
+                await Promise.resolve();
+
+                this.readable = await getWrappedReadableStream(wrapper, controller);
+                this.reader = this.readable.getReader();
             },
             cancel: async (reason) => {
                 await this.reader.cancel(reason);
-                wrapper.close?.(this.state);
+                if ('cancel' in wrapper) {
+                    await wrapper.cancel?.(reason);
+                }
             },
             pull: async (controller) => {
                 const result = await this.reader.read();
                 if (result.done) {
-                    wrapper.close?.(this.state);
                     controller.close();
+                    if ('close' in wrapper) {
+                        await wrapper.close?.();
+                    }
                 } else {
                     controller.enqueue(result.value);
                 }
@@ -394,7 +411,7 @@ export class PushReadableStream<T> extends ReadableStream<T> {
                 source({
                     abortSignal: canceled.signal,
                     async enqueue(chunk) {
-                        // Only when the stream in errored, `desiredSize` will be `null`.
+                        // Only when the stream is errored, `desiredSize` will be `null`.
                         // But since `null <= 0` is `true`
                         // (`null <= 0` is evaluated as `!(null > 0)` => `!false` => `true`),
                         // not handling it will cause a deadlock.
@@ -419,8 +436,8 @@ export class PushReadableStream<T> extends ReadableStream<T> {
                 waterMarkLow?.resolve();
             },
             cancel: async (reason) => {
-                waterMarkLow?.reject(reason);
                 canceled.abort();
+                waterMarkLow?.reject(reason);
             },
         }, strategy);
     }

package/src/utils/index.ts

@@ -1,3 +1,3 @@
+export { decodeUtf8, encodeUtf8 } from '@yume-chan/struct';
 export * from './auto-reset-event.js';
 export * from './base64.js';
-export * from './encoding.js';