@yume-chan/adb 0.0.23 → 1.0.0

package/esm/server/client.js

@@ -1,121 +1,91 @@
 // cspell:ignore tport
 import { PromiseResolver } from "@yume-chan/async";
-import { BufferedReadableStream, UnwrapConsumableStream, WrapWritableStream, } from "@yume-chan/stream-extra";
-import { BigIntFieldType, EMPTY_UINT8_ARRAY, SyncPromise, decodeUtf8, encodeUtf8, } from "@yume-chan/struct";
+import { EventEmitter } from "@yume-chan/event";
+import { getUint64LittleEndian } from "@yume-chan/no-data-view";
+import { BufferedReadableStream, tryCancel, tryClose, } from "@yume-chan/stream-extra";
+import { bipedal, decodeUtf8, encodeUtf8, TextDecoder, } from "@yume-chan/struct";
 import { AdbBanner } from "../banner.js";
-import { NOOP, hexToNumber, numberToHex, unreachable } from "../utils/index.js";
+import { hexToNumber, sequenceEqual, write4HexDigits } from "../utils/index.js";
 import { AdbServerTransport } from "./transport.js";
-export class AdbServerClient {
-    static VERSION = 41;
-    connection;
+const OKAY = encodeUtf8("OKAY");
+const FAIL = encodeUtf8("FAIL");
+class AdbServerStream {
+    #connection;
+    #buffered;
+    #writer;
     constructor(connection) {
-        this.connection = connection;
+        this.#connection = connection;
+        this.#buffered = new BufferedReadableStream(connection.readable);
+        this.#writer = connection.writable.getWriter();
     }
-    static readString(stream) {
-        return SyncPromise.try(() => stream.readExactly(4))
-            .then((buffer) => {
-            const length = hexToNumber(buffer);
-            if (length === 0) {
-                return EMPTY_UINT8_ARRAY;
-            }
-            else {
-                return stream.readExactly(length);
-            }
-        })
-            .then((valueBuffer) => {
-            return decodeUtf8(valueBuffer);
-        })
-            .valueOrPromise();
+    readExactly(length) {
+        return this.#buffered.readExactly(length);
     }
-    static async writeString(writer, value) {
-        const valueBuffer = encodeUtf8(value);
-        const buffer = new Uint8Array(4 + valueBuffer.length);
-        buffer.set(numberToHex(valueBuffer.length));
-        buffer.set(valueBuffer, 4);
-        await writer.write(buffer);
+    readString = bipedal(function* (then) {
+        const data = yield* then(this.readExactly(4));
+        const length = hexToNumber(data);
+        if (length === 0) {
+            return "";
+        }
+        else {
+            const decoder = new TextDecoder();
+            let result = "";
+            const iterator = this.#buffered.iterateExactly(length);
+            while (true) {
+                const { done, value } = iterator.next();
+                if (done) {
+                    break;
+                }
+                result += decoder.decode(yield* then(value), { stream: true });
+            }
+            result += decoder.decode();
+            return result;
+        }
+    });
+    async writeString(value) {
+        // TODO: investigate using `encodeUtf8("0000" + value)` then modifying the length
+        // That way allocates a new string (hopefully only a rope) instead of a new buffer
+        const encoded = encodeUtf8(value);
+        const buffer = new Uint8Array(4 + encoded.length);
+        write4HexDigits(buffer, 0, encoded.length);
+        buffer.set(encoded, 4);
+        await this.#writer.write(buffer);
     }
-    static async readOkay(stream) {
-        const response = decodeUtf8(await stream.readExactly(4));
-        if (response === "OKAY") {
+    async readOkay() {
+        const response = await this.readExactly(4);
+        if (sequenceEqual(response, OKAY)) {
+            // `OKAY` is followed by data length and data
+            // But different services want to parse the data differently
+            // So don't read the data here
             return;
         }
-        if (response === "FAIL") {
-            const reason = await AdbServerClient.readString(stream);
+        if (sequenceEqual(response, FAIL)) {
+            const reason = await this.readString();
             throw new Error(reason);
         }
-        throw new Error(`Unexpected response: ${response}`);
+        throw new Error(`Unexpected response: ${decodeUtf8(response)}`);
     }
-    async connect(request, options) {
-        const connection = await this.connection.connect(options);
-        try {
-            const writer = connection.writable.getWriter();
-            await AdbServerClient.writeString(writer, request);
-            writer.releaseLock();
-        }
-        catch (e) {
-            await connection.readable.cancel();
-            await connection.close();
-            throw e;
-        }
-        const readable = new BufferedReadableStream(connection.readable);
-        try {
-            // `raceSignal` throws when the signal is aborted,
-            // so the `catch` block can close the connection.
-            await raceSignal(() => AdbServerClient.readOkay(readable), options?.signal);
-            return {
-                readable: readable.release(),
-                writable: connection.writable,
-                get closed() {
-                    return connection.closed;
-                },
-                async close() {
-                    await connection.close();
-                },
-            };
-        }
-        catch (e) {
-            await readable.cancel().catch(NOOP);
-            await connection.close();
-            throw e;
-        }
-    }
-    async getVersion() {
-        const connection = await this.connect("host:version");
-        const readable = new BufferedReadableStream(connection.readable);
-        try {
-            const length = hexToNumber(await readable.readExactly(4));
-            const version = hexToNumber(await readable.readExactly(length));
-            return version;
-        }
-        finally {
-            connection.writable.close().catch(NOOP);
-            readable.cancel().catch(NOOP);
-        }
-    }
-    async validateVersion() {
-        const version = await this.getVersion();
-        if (version !== AdbServerClient.VERSION) {
-            throw new Error(`adb server version (${version}) doesn't match this client (${AdbServerClient.VERSION})`);
-        }
-    }
-    async killServer() {
-        const connection = await this.connect("host:kill");
-        connection.writable.close().catch(NOOP);
-        connection.readable.cancel().catch(NOOP);
+    release() {
+        this.#writer.releaseLock();
+        return {
+            readable: this.#buffered.release(),
+            writable: this.#connection.writable,
+            closed: this.#connection.closed,
+            close: () => this.#connection.close(),
+        };
     }
-    async getServerFeatures() {
-        const connection = await this.connect("host:host-features");
-        const readable = new BufferedReadableStream(connection.readable);
-        try {
-            const response = await AdbServerClient.readString(readable);
-            return response.split(",");
-        }
-        finally {
-            connection.writable.close().catch(NOOP);
-            readable.cancel().catch(NOOP);
-        }
+    async dispose() {
+        void tryCancel(this.#buffered);
+        void tryClose(this.#writer);
+        await this.#connection.close();
     }
-    parseDeviceList(value) {
+}
+/**
+ * Client for the ADB Server.
+ */
+export class AdbServerClient {
+    static VERSION = 41;
+    static parseDeviceList(value) {
         const devices = [];
         for (const line of value.split("\n")) {
             if (!line) {
@@ -124,7 +94,7 @@ export class AdbServerClient {
             const parts = line.split(" ").filter(Boolean);
             const serial = parts[0];
             const status = parts[1];
-            if (status !== "device") {
+            if (status !== "device" && status !== "unauthorized") {
                 continue;
             }
             let product;
@@ -153,6 +123,7 @@ export class AdbServerClient {
             }
             devices.push({
                 serial,
+                authenticating: status === "unauthorized",
                 product,
                 model,
                 device,
@@ -161,41 +132,7 @@ export class AdbServerClient {
         }
         return devices;
     }
-    async getDevices() {
-        const connection = await this.connect("host:devices-l");
-        const readable = new BufferedReadableStream(connection.readable);
-        try {
-            const response = await AdbServerClient.readString(readable);
-            return this.parseDeviceList(response);
-        }
-        finally {
-            connection.writable.close().catch(NOOP);
-            readable.cancel().catch(NOOP);
-        }
-    }
-    async trackDevices(callback) {
-        const connection = await this.connect("host:track-devices-l");
-        const readable = new BufferedReadableStream(connection.readable);
-        let running = true;
-        (async () => {
-            try {
-                while (running) {
-                    const response = await AdbServerClient.readString(readable);
-                    const devices = this.parseDeviceList(response);
-                    callback(devices);
-                }
-            }
-            catch {
-                // ignore
-            }
-        })().catch(unreachable);
-        return () => {
-            running = false;
-            readable.cancel().catch(NOOP);
-            Promise.resolve(connection.close()).catch(NOOP);
-        };
-    }
-    formatDeviceService(device, command) {
+    static formatDeviceService(device, command) {
         if (!device) {
             return `host:${command}`;
         }
@@ -211,7 +148,153 @@ export class AdbServerClient {
         if ("tcp" in device) {
             return `host-local:${command}`;
         }
-        throw new Error("Invalid device selector");
+        throw new TypeError("Invalid device selector");
+    }
+    connector;
+    wireless = new AdbServerClient.WirelessCommands(this);
+    mDns = new AdbServerClient.MDnsCommands(this);
+    constructor(connector) {
+        this.connector = connector;
+    }
+    async createConnection(request, options) {
+        const connection = await this.connector.connect(options);
+        const stream = new AdbServerStream(connection);
+        try {
+            await stream.writeString(request);
+        }
+        catch (e) {
+            await stream.dispose();
+            throw e;
+        }
+        try {
+            // `raceSignal` throws when the signal is aborted,
+            // so the `catch` block can close the connection.
+            await raceSignal(() => stream.readOkay(), options?.signal);
+            return stream;
+        }
+        catch (e) {
+            await stream.dispose();
+            throw e;
+        }
+    }
+    /**
+     * `adb version`
+     */
+    async getVersion() {
+        const connection = await this.createConnection("host:version");
+        try {
+            const length = hexToNumber(await connection.readExactly(4));
+            const version = hexToNumber(await connection.readExactly(length));
+            return version;
+        }
+        finally {
+            await connection.dispose();
+        }
+    }
+    async validateVersion() {
+        const version = await this.getVersion();
+        if (version !== AdbServerClient.VERSION) {
+            throw new Error(`adb server version (${version}) doesn't match this client (${AdbServerClient.VERSION})`);
+        }
+    }
+    /**
+     * `adb kill-server`
+     */
+    async killServer() {
+        const connection = await this.createConnection("host:kill");
+        await connection.dispose();
+    }
+    /**
+     * `adb host-features`
+     */
+    async getServerFeatures() {
+        const connection = await this.createConnection("host:host-features");
+        try {
+            const response = await connection.readString();
+            return response.split(",");
+        }
+        finally {
+            await connection.dispose();
+        }
+    }
+    /**
+     * Get a list of connected devices from ADB Server.
+     *
+     * Equivalent ADB Command: `adb devices -l`
+     */
+    async getDevices() {
+        const connection = await this.createConnection("host:devices-l");
+        try {
+            const response = await connection.readString();
+            return AdbServerClient.parseDeviceList(response);
+        }
+        finally {
+            await connection.dispose();
+        }
+    }
+    /**
+     * Monitors device list changes.
+     */
+    async trackDevices() {
+        const connection = await this.createConnection("host:track-devices-l");
+        let current = [];
+        const onError = new EventEmitter();
+        const onDeviceAdd = new EventEmitter();
+        const onDeviceRemove = new EventEmitter();
+        const onListChange = new EventEmitter();
+        void (async () => {
+            try {
+                while (true) {
+                    const response = await connection.readString();
+                    const next = AdbServerClient.parseDeviceList(response);
+                    const added = [];
+                    for (const nextDevice of next) {
+                        const index = current.findIndex((device) => device.transportId === nextDevice.transportId);
+                        if (index === -1) {
+                            added.push(nextDevice);
+                            continue;
+                        }
+                        current[index] = current[current.length - 1];
+                        current.length -= 1;
+                    }
+                    if (added.length) {
+                        onDeviceAdd.fire(added);
+                    }
+                    if (current.length) {
+                        onDeviceRemove.fire(current);
+                    }
+                    current = next;
+                    onListChange.fire(current);
+                }
+            }
+            catch (e) {
+                onError.fire(e);
+            }
+        })();
+        return {
+            onError: onError.event,
+            onDeviceAdd: onDeviceAdd.event,
+            onDeviceRemove: onDeviceRemove.event,
+            onListChange: onListChange.event,
+            get current() {
+                return current;
+            },
+            stop: () => connection.dispose(),
+        };
+    }
+    /**
+     * `adb -s <device> reconnect` or `adb reconnect offline`
+     */
+    async reconnectDevice(device) {
+        const connection = await this.createConnection(device === "offline"
+            ? "host:reconnect-offline"
+            : AdbServerClient.formatDeviceService(device, "reconnect"));
+        try {
+            await connection.readString();
+        }
+        finally {
+            await connection.dispose();
+        }
     }
     /**
      * Gets the features supported by the device.
@@ -221,31 +304,41 @@ export class AdbServerClient {
      * @returns The transport ID of the selected device, and the features supported by the device.
      */
     async getDeviceFeatures(device) {
-        // Usually the client sends a device command using `connectDevice`,
-        // so the command got forwarded and handled by ADB daemon.
-        // However, in fact, `connectDevice` only forwards unknown services to device,
-        // if the service is a host command, it will still be handled by ADB server.
-        // Also, if the command is about a device, but didn't specify a selector,
-        // it will be executed against the device selected previously by `connectDevice`.
-        // Using this method, we can get the transport ID and device features in one connection.
-        const socket = await this.connectDevice(device, "host:features");
+        // On paper, `host:features` is a host service (device features are cached in host),
+        // so it shouldn't use `createDeviceConnection`,
+        // which is used to forward the service to the device.
+        //
+        // However, `createDeviceConnection` is a two step process:
+        //
+        //    1. Send a switch device service to host, to switch the connection to the device.
+        //    2. Send the actual service to host, let it forward the service to the device.
+        //
+        // In step 2, the host only forward the service to device if the service is unknown to host.
+        // If the service is a host service, it's still handled by host.
+        //
+        // Even better, if the service needs a device selector, but the selector is not provided,
+        // the service will be executed against the device selected by the switch device service.
+        // So we can use all device selector formats for the host service,
+        // and get the transport ID in the same time.
+        const connection = await this.createDeviceConnection(device, "host:features");
+        // Luckily `AdbServerClient.Socket` is compatible with `AdbServerClient.ServerConnection`
+        const stream = new AdbServerStream(connection);
         try {
-            const readable = new BufferedReadableStream(socket.readable);
-            const featuresString = await AdbServerClient.readString(readable);
+            const featuresString = await stream.readString();
             const features = featuresString.split(",");
-            return { transportId: socket.transportId, features };
+            return { transportId: connection.transportId, features };
         }
         finally {
-            await socket.close();
+            await stream.dispose();
         }
     }
     /**
      * Creates a connection that will forward the service to device.
      * @param device The device selector
      * @param service The service to forward
-     * @returns An `AdbServerSocket` that can be used to communicate with the service
+     * @returns An `AdbServerClient.Socket` that can be used to communicate with the service
      */
-    async connectDevice(device, service) {
+    async createDeviceConnection(device, service) {
         await this.validateVersion();
         let switchService;
         let transportId;
@@ -266,49 +359,46 @@ export class AdbServerClient {
             switchService = `host:tport:local`;
         }
         else {
-            throw new Error("Invalid device selector");
+            throw new TypeError("Invalid device selector");
         }
-        const connection = await this.connect(switchService);
+        const connection = await this.createConnection(switchService);
         try {
-            const writer = connection.writable.getWriter();
-            await AdbServerClient.writeString(writer, service);
-            writer.releaseLock();
+            await connection.writeString(service);
         }
         catch (e) {
-            await connection.readable.cancel();
-            await connection.close();
+            await connection.dispose();
             throw e;
         }
-        const readable = new BufferedReadableStream(connection.readable);
         try {
             if (transportId === undefined) {
-                const array = await readable.readExactly(8);
-                // TODO: switch to a more performant algorithm.
-                const dataView = new DataView(array.buffer, array.byteOffset, array.byteLength);
-                transportId = BigIntFieldType.Uint64.getter(dataView, 0, true);
+                const array = await connection.readExactly(8);
+                transportId = getUint64LittleEndian(array, 0);
             }
-            await AdbServerClient.readOkay(readable);
+            await connection.readOkay();
+            const socket = connection.release();
             return {
                 transportId,
                 service,
-                readable: readable.release(),
-                writable: new WrapWritableStream(connection.writable).bePipedThroughFrom(new UnwrapConsumableStream()),
+                readable: socket.readable,
+                writable: socket.writable,
                 get closed() {
-                    return connection.closed;
+                    return socket.closed;
                 },
                 async close() {
-                    await connection.close();
+                    await socket.close();
                 },
             };
         }
         catch (e) {
-            await readable.cancel().catch(NOOP);
-            await connection.close();
+            await connection.dispose();
             throw e;
         }
     }
     /**
      * Wait for a device to be connected or disconnected.
+     *
+     * `adb wait-for-<state>`
+     *
      * @param device The device selector
      * @param state The state to wait for
      * @param options The options
@@ -332,17 +422,22 @@ export class AdbServerClient {
             type = "local";
         }
         else {
-            throw new Error("Invalid device selector");
+            throw new TypeError("Invalid device selector");
         }
         // `waitFor` can't use `connectDevice`, because the device
         // might not be available yet.
-        const service = this.formatDeviceService(device, `wait-for-${type}-${state}`);
-        const socket = await this.connect(service, options);
-        const readable = new BufferedReadableStream(socket.readable);
-        await AdbServerClient.readOkay(readable);
-        await readable.cancel();
-        await socket.close();
+        const service = AdbServerClient.formatDeviceService(device, `wait-for-${type}-${state}`);
+        const connection = await this.createConnection(service, options);
+        try {
+            await connection.readOkay();
+        }
+        finally {
+            await connection.dispose();
+        }
     }
+    /**
+     * Creates an ADB Transport for the specified device.
+     */
     async createTransport(device) {
         const { transportId, features } = await this.getDeviceFeatures(device);
         const devices = await this.getDevices();
@@ -377,4 +472,125 @@ export async function raceSignal(callback, ...signals) {
         }
     }
 }
+(function (AdbServerClient) {
+    class NetworkError extends Error {
+        constructor(message) {
+            super(message);
+            this.name = "NetworkError";
+        }
+    }
+    AdbServerClient.NetworkError = NetworkError;
+    class UnauthorizedError extends Error {
+        constructor(message) {
+            super(message);
+            this.name = "UnauthorizedError";
+        }
+    }
+    AdbServerClient.UnauthorizedError = UnauthorizedError;
+    class AlreadyConnectedError extends Error {
+        constructor(message) {
+            super(message);
+            this.name = "AlreadyConnectedError";
+        }
+    }
+    AdbServerClient.AlreadyConnectedError = AlreadyConnectedError;
+    class WirelessCommands {
+        #client;
+        constructor(client) {
+            this.#client = client;
+        }
+        /**
+         * `adb pair <password> <address>`
+         */
+        async pair(address, password) {
+            const connection = await this.#client.createConnection(`host:pair:${password}:${address}`);
+            try {
+                const response = await connection.readExactly(4);
+                // `response` is either `FAIL`, or 4 hex digits for length of the string
+                if (sequenceEqual(response, FAIL)) {
+                    throw new Error(await connection.readString());
+                }
+                const length = hexToNumber(response);
+                // Ignore the string as it's always `Successful ...`
+                await connection.readExactly(length);
+            }
+            finally {
+                await connection.dispose();
+            }
+        }
+        /**
+         * `adb connect <address>`
+         */
+        async connect(address) {
+            const connection = await this.#client.createConnection(`host:connect:${address}`);
+            try {
+                const response = await connection.readString();
+                switch (response) {
+                    case `already connected to ${address}`:
+                        throw new AdbServerClient.AlreadyConnectedError(response);
+                    case `failed to connect to ${address}`: // `adb pair` mode not authorized
+                    case `failed to authenticate to ${address}`: // `adb tcpip` mode not authorized
+                        throw new AdbServerClient.UnauthorizedError(response);
+                    case `connected to ${address}`:
+                        return;
+                    default:
+                        throw new AdbServerClient.NetworkError(response);
+                }
+            }
+            finally {
+                await connection.dispose();
+            }
+        }
+        /**
+         * `adb disconnect <address>`
+         */
+        async disconnect(address) {
+            const connection = await this.#client.createConnection(`host:disconnect:${address}`);
+            try {
+                await connection.readString();
+            }
+            finally {
+                await connection.dispose();
+            }
+        }
+    }
+    AdbServerClient.WirelessCommands = WirelessCommands;
+    class MDnsCommands {
+        #client;
+        constructor(client) {
+            this.#client = client;
+        }
+        async check() {
+            const connection = await this.#client.createConnection("host:mdns:check");
+            try {
+                const response = await connection.readString();
+                return !response.startsWith("ERROR:");
+            }
+            finally {
+                await connection.dispose();
+            }
+        }
+        async getServices() {
+            const connection = await this.#client.createConnection("host:mdns:services");
+            try {
+                const response = await connection.readString();
+                return response
+                    .split("\n")
+                    .filter(Boolean)
+                    .map((line) => {
+                    const parts = line.split("\t");
+                    return {
+                        name: parts[0],
+                        service: parts[1],
+                        address: parts[2],
+                    };
+                });
+            }
+            finally {
+                await connection.dispose();
+            }
+        }
+    }
+    AdbServerClient.MDnsCommands = MDnsCommands;
+})(AdbServerClient || (AdbServerClient = {}));
 //# sourceMappingURL=client.js.map