@yume-chan/adb 0.0.12 → 0.0.15

package/src/adb.ts

@@ -1,9 +1,11 @@
+// cspell: ignore libusb
+
 import { PromiseResolver } from '@yume-chan/async';
-import { AdbAuthenticationHandler, AdbDefaultAuthenticators, type AdbCredentialStore } from './auth.js';
+import { AdbAuthenticationProcessor, ADB_DEFAULT_AUTHENTICATORS, type AdbCredentialStore } from './auth.js';
 import { AdbPower, AdbReverseCommand, AdbSubprocess, AdbSync, AdbTcpIpCommand, escapeArg, framebuffer, install, type AdbFrameBuffer } from './commands/index.js';
 import { AdbFeatures } from './features.js';
-import { AdbCommand, AdbPacket, calculateChecksum, type AdbPacketCore, type AdbPacketInit } from './packet.js';
-import { AdbPacketDispatcher, AdbSocket } from './socket/index.js';
+import { AdbCommand, calculateChecksum, type AdbPacketData, type AdbPacketInit } from './packet.js';
+import { AdbIncomingSocketHandler, AdbPacketDispatcher, type AdbSocket, type Closeable } from './socket/index.js';
 import { AbortController, DecodeUtf8Stream, GatherStringStream, WritableStream, type ReadableWritablePair } from "./stream/index.js";
 import { decodeUtf8, encodeUtf8 } from "./utils/index.js";
 
@@ -16,46 +18,30 @@ export enum AdbPropKey {
 
 export const VERSION_OMIT_CHECKSUM = 0x01000001;
 
-export class Adb {
+export class Adb implements Closeable {
     /**
      * It's possible to call `authenticate` multiple times on a single connection,
      * every time the device receives a `CNXN` packet, it resets its internal state,
      * and starts a new authentication process.
      */
     public static async authenticate(
-        connection: ReadableWritablePair<AdbPacketCore, AdbPacketCore>,
+        connection: ReadableWritablePair<AdbPacketData, AdbPacketInit>,
         credentialStore: AdbCredentialStore,
-        authenticators = AdbDefaultAuthenticators,
+        authenticators = ADB_DEFAULT_AUTHENTICATORS,
     ): Promise<Adb> {
+        // Initially, set to highest-supported version and payload size.
         let version = 0x01000001;
         let maxPayloadSize = 0x100000;
 
-        const features = [
-            'shell_v2',
-            'cmd',
-            AdbFeatures.StatV2,
-            'ls_v2',
-            'fixed_push_mkdir',
-            'apex',
-            'abb',
-            'fixed_push_symlink_timestamp',
-            'abb_exec',
-            'remount_shell',
-            'track_app',
-            'sendrecv_v2',
-            'sendrecv_v2_brotli',
-            'sendrecv_v2_lz4',
-            'sendrecv_v2_zstd',
-            'sendrecv_v2_dry_run_send',
-        ].join(',');
-
         const resolver = new PromiseResolver<string>();
-        const authHandler = new AdbAuthenticationHandler(authenticators, credentialStore);
+        const authProcessor = new AdbAuthenticationProcessor(authenticators, credentialStore);
 
+        // Here is similar to `AdbPacketDispatcher`,
+        // But the received packet types and send packet processing are different.
         const abortController = new AbortController();
         const pipe = connection.readable
             .pipeTo(new WritableStream({
-                async write(packet: AdbPacket) {
+                async write(packet) {
                     switch (packet.command) {
                         case AdbCommand.Connect:
                             version = Math.min(version, packet.arg0);
@@ -63,64 +49,89 @@ export class Adb {
                             resolver.resolve(decodeUtf8(packet.payload));
                             break;
                         case AdbCommand.Auth:
-                            const response = await authHandler.handle(packet);
+                            const response = await authProcessor.process(packet);
                             await sendPacket(response);
                             break;
-                        case AdbCommand.Close:
-                            // Last connection was interrupted
-                            // Ignore this packet, device will recover
-                            break;
                         default:
-                            throw new Error('Device not in correct state. Reconnect your device and try again');
+                            // Maybe the previous ADB client exited without reading all packets,
+                            // so they are still waiting in OS internal buffer.
+                            // Just ignore them.
+                            // Because a `Connect` packet will reset the device,
+                            // Eventually there will be `Connect` and `Auth` response packets.
+                            break;
                     }
                 }
             }), {
                 preventCancel: true,
                 signal: abortController.signal,
             })
-            .catch((e) => { resolver.reject(e); });
+            .catch((e) => {
+                resolver.reject(e);
+            });
 
         const writer = connection.writable.getWriter();
-        async function sendPacket(init: AdbPacketCore) {
+        async function sendPacket(init: AdbPacketData) {
             // Always send checksum in auth steps
-            // Because we don't know if the device will ignore it yet.
+            // Because we don't know if the device needs it or not.
             await writer.write(calculateChecksum(init));
         }
 
-        await sendPacket({
-            command: AdbCommand.Connect,
-            arg0: version,
-            arg1: maxPayloadSize,
-            // The terminating `;` is required in formal definition
-            // But ADB daemon (all versions) can still work without it
-            payload: encodeUtf8(`host::features=${features};`),
-        });
-
+        let banner: string;
         try {
-            const banner = await resolver.promise;
-
-            // Stop piping before creating Adb object
-            // Because AdbPacketDispatcher will try to lock the streams when initializing
-            abortController.abort();
-            await pipe;
-
-            writer.releaseLock();
-
-            return new Adb(
-                connection,
-                version,
-                maxPayloadSize,
-                banner,
-            );
+            // https://android.googlesource.com/platform/packages/modules/adb/+/79010dc6d5ca7490c493df800d4421730f5466ca/transport.cpp#1252
+            // There are some other feature constants, but some of them are only used by ADB server, not devices (daemons).
+            const features = [
+                AdbFeatures.ShellV2,
+                AdbFeatures.Cmd,
+                AdbFeatures.StatV2,
+                AdbFeatures.ListV2,
+                AdbFeatures.FixedPushMkdir,
+                'apex',
+                'abb',
+                // only tells the client the symlink timestamp issue in `adb push --sync` has been fixed.
+                // No special handling required.
+                'fixed_push_symlink_timestamp',
+                'abb_exec',
+                'remount_shell',
+                'track_app',
+                'sendrecv_v2',
+                'sendrecv_v2_brotli',
+                'sendrecv_v2_lz4',
+                'sendrecv_v2_zstd',
+                'sendrecv_v2_dry_run_send',
+            ].join(',');
+
+            await sendPacket({
+                command: AdbCommand.Connect,
+                arg0: version,
+                arg1: maxPayloadSize,
+                // The terminating `;` is required in formal definition
+                // But ADB daemon (all versions) can still work without it
+                payload: encodeUtf8(`host::features=${features};`),
+            });
+
+            banner = await resolver.promise;
         } finally {
+            // When failed, release locks on `connection` so the caller can try again.
+            // When success, also release locks so `AdbPacketDispatcher` can use them.
             abortController.abort();
             writer.releaseLock();
+
+            // Wait until pipe stops (`ReadableStream` lock released)
+            await pipe;
         }
+
+        return new Adb(
+            connection,
+            version,
+            maxPayloadSize,
+            banner,
+        );
     }
 
-    private readonly packetDispatcher: AdbPacketDispatcher;
+    private readonly dispatcher: AdbPacketDispatcher;
 
-    public get disconnected() { return this.packetDispatcher.disconnected; }
+    public get disconnected() { return this.dispatcher.disconnected; }
 
     private _protocolVersion: number | undefined;
     public get protocolVersion() { return this._protocolVersion; }
@@ -143,26 +154,37 @@ export class Adb {
     public readonly tcpip: AdbTcpIpCommand;
 
     public constructor(
-        connection: ReadableWritablePair<AdbPacketCore, AdbPacketInit>,
+        connection: ReadableWritablePair<AdbPacketData, AdbPacketInit>,
         version: number,
         maxPayloadSize: number,
         banner: string,
     ) {
         this.parseBanner(banner);
-        this.packetDispatcher = new AdbPacketDispatcher(connection);
 
-        this._protocolVersion = version;
+        let calculateChecksum: boolean;
+        let appendNullToServiceString: boolean;
         if (version >= VERSION_OMIT_CHECKSUM) {
-            this.packetDispatcher.calculateChecksum = false;
-            // Android prior to 9.0.0 uses char* to parse service string
-            // thus requires an extra null character
-            this.packetDispatcher.appendNullToServiceString = false;
+            calculateChecksum = false;
+            appendNullToServiceString = false;
+        } else {
+            calculateChecksum = true;
+            appendNullToServiceString = true;
         }
-        this.packetDispatcher.maxPayloadSize = maxPayloadSize;
+
+        this.dispatcher = new AdbPacketDispatcher(
+            connection,
+            {
+                calculateChecksum,
+                appendNullToServiceString,
+                maxPayloadSize,
+            }
+        );
+
+        this._protocolVersion = version;
 
         this.subprocess = new AdbSubprocess(this);
         this.power = new AdbPower(this);
-        this.reverse = new AdbReverseCommand(this.packetDispatcher);
+        this.reverse = new AdbReverseCommand(this);
         this.tcpip = new AdbTcpIpCommand(this);
     }
 
@@ -201,6 +223,23 @@ export class Adb {
         }
     }
 
+    public addIncomingSocketHandler(handler: AdbIncomingSocketHandler) {
+        return this.dispatcher.addIncomingSocketHandler(handler);
+    }
+
+    public async createSocket(service: string): Promise<AdbSocket> {
+        return this.dispatcher.createSocket(service);
+    }
+
+    public async createSocketAndWait(service: string): Promise<string> {
+        const socket = await this.createSocket(service);
+        const gatherStream = new GatherStringStream();
+        await socket.readable
+            .pipeThrough(new DecodeUtf8Stream())
+            .pipeTo(gatherStream);
+        return gatherStream.result;
+    }
+
     public async getProp(key: string): Promise<string> {
         const stdout = await this.subprocess.spawnAndWaitLegacy(
             ['getprop', key]
@@ -228,20 +267,7 @@ export class Adb {
         return framebuffer(this);
     }
 
-    public async createSocket(service: string): Promise<AdbSocket> {
-        return this.packetDispatcher.createSocket(service);
-    }
-
-    public async createSocketAndWait(service: string): Promise<string> {
-        const socket = await this.createSocket(service);
-        const gatherStream = new GatherStringStream();
-        await socket.readable
-            .pipeThrough(new DecodeUtf8Stream())
-            .pipeTo(gatherStream.writable);
-        return gatherStream.result;
-    }
-
-    public async dispose(): Promise<void> {
-        this.packetDispatcher.dispose();
+    public async close(): Promise<void> {
+        await this.dispatcher.close();
     }
 }

package/src/auth.ts

@@ -2,7 +2,7 @@ import { PromiseResolver } from '@yume-chan/async';
 import type { Disposable } from '@yume-chan/event';
 import type { ValueOrPromise } from '@yume-chan/struct';
 import { calculatePublicKey, calculatePublicKeyLength, sign } from './crypto.js';
-import { AdbCommand, AdbPacket, type AdbPacketCore } from './packet.js';
+import { AdbCommand, type AdbPacketData } from './packet.js';
 import { calculateBase64EncodedLength, encodeBase64 } from './utils/index.js';
 
 export type AdbKeyIterable = Iterable<Uint8Array> | AsyncIterable<Uint8Array>;
@@ -43,14 +43,14 @@ export interface AdbAuthenticator {
      */
     (
         credentialStore: AdbCredentialStore,
-        getNextRequest: () => Promise<AdbPacket>
-    ): AsyncIterable<AdbPacketCore>;
+        getNextRequest: () => Promise<AdbPacketData>
+    ): AsyncIterable<AdbPacketData>;
 }
 
 export const AdbSignatureAuthenticator: AdbAuthenticator = async function* (
     credentialStore: AdbCredentialStore,
-    getNextRequest: () => Promise<AdbPacket>,
-): AsyncIterable<AdbPacketCore> {
+    getNextRequest: () => Promise<AdbPacketData>,
+): AsyncIterable<AdbPacketData> {
     for await (const key of credentialStore.iterateKeys()) {
         const packet = await getNextRequest();
 
@@ -70,8 +70,8 @@ export const AdbSignatureAuthenticator: AdbAuthenticator = async function* (
 
 export const AdbPublicKeyAuthenticator: AdbAuthenticator = async function* (
     credentialStore: AdbCredentialStore,
-    getNextRequest: () => Promise<AdbPacket>,
-): AsyncIterable<AdbPacketCore> {
+    getNextRequest: () => Promise<AdbPacketData>,
+): AsyncIterable<AdbPacketData> {
     const packet = await getNextRequest();
 
     if (packet.arg0 !== AdbAuthType.Token) {
@@ -110,19 +110,19 @@ export const AdbPublicKeyAuthenticator: AdbAuthenticator = async function* (
     };
 };
 
-export const AdbDefaultAuthenticators: AdbAuthenticator[] = [
+export const ADB_DEFAULT_AUTHENTICATORS: AdbAuthenticator[] = [
     AdbSignatureAuthenticator,
     AdbPublicKeyAuthenticator,
 ];
 
-export class AdbAuthenticationHandler implements Disposable {
+export class AdbAuthenticationProcessor implements Disposable {
     public readonly authenticators: readonly AdbAuthenticator[];
 
     private readonly credentialStore: AdbCredentialStore;
 
-    private pendingRequest = new PromiseResolver<AdbPacket>();
+    private pendingRequest = new PromiseResolver<AdbPacketData>();
 
-    private iterator: AsyncIterator<AdbPacketCore> | undefined;
+    private iterator: AsyncIterator<AdbPacketData, void, void> | undefined;
 
     public constructor(
         authenticators: readonly AdbAuthenticator[],
@@ -132,16 +132,16 @@ export class AdbAuthenticationHandler implements Disposable {
         this.credentialStore = credentialStore;
     }
 
-    private getNextRequest = (): Promise<AdbPacket> => {
+    private getNextRequest = (): Promise<AdbPacketData> => {
         return this.pendingRequest.promise;
     };
 
-    private async* runAuthenticator(): AsyncGenerator<AdbPacketCore> {
+    private async* invokeAuthenticator(): AsyncGenerator<AdbPacketData, void, void> {
         for (const authenticator of this.authenticators) {
             for await (const packet of authenticator(this.credentialStore, this.getNextRequest)) {
                 // If the authenticator yielded a response
                 // Prepare `nextRequest` for next authentication request
-                this.pendingRequest = new PromiseResolver<AdbPacket>();
+                this.pendingRequest = new PromiseResolver();
 
                 // Yield the response to outer layer
                 yield packet;
@@ -150,17 +150,20 @@ export class AdbAuthenticationHandler implements Disposable {
             // If the authenticator returned,
             // Next authenticator will be given the same `pendingRequest`
         }
-
-        throw new Error('Cannot authenticate with device');
     }
 
-    public async handle(packet: AdbPacket): Promise<AdbPacketCore> {
+    public async process(packet: AdbPacketData): Promise<AdbPacketData> {
         if (!this.iterator) {
-            this.iterator = this.runAuthenticator();
+            this.iterator = this.invokeAuthenticator();
         }
 
         this.pendingRequest.resolve(packet);
+
         const result = await this.iterator.next();
+        if (result.done) {
+            throw new Error('No authenticator can handle the request');
+        }
+
         return result.value;
     }
 

package/src/backend.ts

@@ -1,5 +1,5 @@
 import type { ValueOrPromise } from '@yume-chan/struct';
-import type { AdbPacketCore, AdbPacketInit } from "./packet.js";
+import type { AdbPacketData, AdbPacketInit } from "./packet.js";
 import type { ReadableWritablePair } from "./stream/index.js";
 
 export interface AdbBackend {
@@ -7,5 +7,5 @@ export interface AdbBackend {
 
     readonly name: string | undefined;
 
-    connect(): ValueOrPromise<ReadableWritablePair<AdbPacketCore, AdbPacketInit>>;
+    connect(): ValueOrPromise<ReadableWritablePair<AdbPacketData, AdbPacketInit>>;
 }

package/src/commands/install.ts

@@ -8,18 +8,16 @@ export function install(
 ): WritableStream<Uint8Array> {
     const filename = `/data/local/tmp/${Math.random().toString().substring(2)}.apk`;
 
-    return new WrapWritableStream<Uint8Array, WritableStream<Uint8Array>, AdbSync>({
+    let sync!: AdbSync;
+    return new WrapWritableStream<Uint8Array>({
         async start() {
-            // Upload apk file to tmp folder
-            const sync = await adb.sync();
-            const writable = sync.write(filename, undefined, undefined);
+            // TODO: install: support other install apk methods (streaming, etc.)
 
-            return {
-                writable,
-                state: sync,
-            };
+            // Upload apk file to tmp folder
+            sync = await adb.sync();
+            return sync.write(filename, undefined, undefined);
         },
-        async close(sync) {
+        async close() {
             sync.dispose();
 
             // Invoke `pm install` to install it

package/src/commands/reverse.ts

@@ -2,15 +2,11 @@
 
 import { AutoDisposable } from '@yume-chan/event';
 import Struct from '@yume-chan/struct';
-import type { AdbPacketCore } from '../packet.js';
-import type { AdbIncomingSocketEventArgs, AdbPacketDispatcher, AdbSocket } from '../socket/index.js';
-import { AdbBufferedStream } from '../stream/index.js';
+import type { Adb } from "../adb.js";
+import type { AdbIncomingSocketHandler, AdbSocket } from '../socket/index.js';
+import { AdbBufferedStream, BufferedStreamEndedError } from '../stream/index.js';
 import { decodeUtf8 } from "../utils/index.js";
 
-export interface AdbReverseHandler {
-    onSocket(packet: AdbPacketCore, socket: AdbSocket): void;
-}
-
 export interface AdbForwardListener {
     deviceSerial: string;
 
@@ -20,49 +16,42 @@ export interface AdbForwardListener {
 }
 
 const AdbReverseStringResponse =
-    new Struct({ littleEndian: true })
+    new Struct()
         .string('length', { length: 4 })
-        .string('content', { lengthField: 'length', lengthFieldBase: 16 });
+        .string('content', { lengthField: 'length', lengthFieldRadix: 16 });
 
 const AdbReverseErrorResponse =
-    new Struct({ littleEndian: true })
+    new Struct()
         .fields(AdbReverseStringResponse)
         .postDeserialize((value) => {
             throw new Error(value.content);
         });
 
 export class AdbReverseCommand extends AutoDisposable {
-    protected localPortToHandler = new Map<number, AdbReverseHandler>();
+    protected localAddressToHandler = new Map<string, AdbIncomingSocketHandler>();
 
-    protected deviceAddressToLocalPort = new Map<string, number>();
+    protected deviceAddressToLocalAddress = new Map<string, string>();
 
-    protected dispatcher: AdbPacketDispatcher;
+    protected adb: Adb;
 
     protected listening = false;
 
-    public constructor(dispatcher: AdbPacketDispatcher) {
+    public constructor(adb: Adb) {
         super();
 
-        this.dispatcher = dispatcher;
-        this.addDisposable(this.dispatcher.onIncomingSocket(this.handleIncomingSocket, this));
+        this.adb = adb;
+        this.addDisposable(this.adb.addIncomingSocketHandler(this.handleIncomingSocket));
     }
 
-    protected handleIncomingSocket(e: AdbIncomingSocketEventArgs): void {
-        if (e.handled) {
-            return;
-        }
-
-        const address = decodeUtf8(e.packet.payload);
-        // Address format: `tcp:12345\0`
-        const port = Number.parseInt(address.substring(4));
-        if (this.localPortToHandler.has(port)) {
-            this.localPortToHandler.get(port)!.onSocket(e.packet, e.socket);
-            e.handled = true;
-        }
-    }
+    protected handleIncomingSocket = async (socket: AdbSocket) => {
+        let address = socket.serviceString;
+        // ADB daemon appends `\0` to the service string
+        address = address.replace(/\0/g, '');
+        return !!(await this.localAddressToHandler.get(address)?.(socket));
+    };
 
     private async createBufferedStream(service: string) {
-        const socket = await this.dispatcher.createSocket(service);
+        const socket = await this.adb.createSocket(service);
         return new AdbBufferedStream(socket);
     }
 
@@ -89,26 +78,41 @@ export class AdbReverseCommand extends AutoDisposable {
 
     /**
      * @param deviceAddress The address adbd on device is listening on. Can be `tcp:0` to let adbd choose an available TCP port by itself.
-     * @param localPort Native ADB will open a connection to localPort when reverse connection starts. In webadb, it's only used to uniquely identify a reverse registry, `handler` will be called on connection.
+     * @param localAddress Native ADB client will open a connection to this address when reverse connection received. In WebADB, it's only used to uniquely identify a reverse tunnel registry, `handler` will be called to handle the connection.
      * @param handler A callback to handle incoming connections
      * @returns If `deviceAddress` is `tcp:0`, return `tcp:{ACTUAL_LISTENING_PORT}`; otherwise, return `deviceAddress`.
      */
     public async add(
         deviceAddress: string,
-        localPort: number,
-        handler: AdbReverseHandler,
+        localAddress: string,
+        handler: AdbIncomingSocketHandler,
     ): Promise<string> {
-        const stream = await this.sendRequest(`reverse:forward:${deviceAddress};tcp:${localPort}`);
+        const stream = await this.sendRequest(`reverse:forward:${deviceAddress};${localAddress}`);
 
         // `tcp:0` tells the device to pick an available port.
-        // However, device will response with the selected port for all `tcp:` requests.
+        // Begin with Android 8, device will respond with the selected port for all `tcp:` requests.
         if (deviceAddress.startsWith('tcp:')) {
-            const response = await AdbReverseStringResponse.deserialize(stream);
-            deviceAddress = `tcp:${Number.parseInt(response.content!, 10)}`;
+            let length: number | undefined;
+            try {
+                length = Number.parseInt(decodeUtf8(await stream.read(4)), 16);
+            } catch (e) {
+                if (!(e instanceof BufferedStreamEndedError)) {
+                    throw e;
+                }
+
+                // Device before Android 8 doesn't have this response.
+                // (the stream is closed now)
+                // Can be safely ignored.
+            }
+
+            if (length !== undefined) {
+                const port = decodeUtf8(await stream.read(length!));
+                deviceAddress = `tcp:${Number.parseInt(port, 10)}`;
+            }
         }
 
-        this.localPortToHandler.set(localPort, handler);
-        this.deviceAddressToLocalPort.set(deviceAddress, localPort);
+        this.localAddressToHandler.set(localAddress, handler);
+        this.deviceAddressToLocalAddress.set(deviceAddress, localAddress);
         return deviceAddress;
 
         // No need to close the stream, device will close it
@@ -117,9 +121,9 @@ export class AdbReverseCommand extends AutoDisposable {
     public async remove(deviceAddress: string): Promise<void> {
         await this.sendRequest(`reverse:killforward:${deviceAddress}`);
 
-        if (this.deviceAddressToLocalPort.has(deviceAddress)) {
-            this.localPortToHandler.delete(this.deviceAddressToLocalPort.get(deviceAddress)!);
-            this.deviceAddressToLocalPort.delete(deviceAddress);
+        if (this.deviceAddressToLocalAddress.has(deviceAddress)) {
+            this.localAddressToHandler.delete(this.deviceAddressToLocalAddress.get(deviceAddress)!);
+            this.deviceAddressToLocalAddress.delete(deviceAddress);
         }
 
         // No need to close the stream, device will close it
@@ -128,8 +132,8 @@ export class AdbReverseCommand extends AutoDisposable {
     public async removeAll(): Promise<void> {
         await this.sendRequest(`reverse:killforward-all`);
 
-        this.deviceAddressToLocalPort.clear();
-        this.localPortToHandler.clear();
+        this.deviceAddressToLocalAddress.clear();
+        this.localAddressToHandler.clear();
 
         // No need to close the stream, device will close it
     }