Repository navigation
feat(client): add client.pair() for wireless debugging - #593
Merged
Merged
Conversation
client.pair(host, port, code) sends host:pair:<code>:<host>:<port>, the
query `adb pair` sends, and lets the ADB server (platform-tools 30+) do
the pairing.
The server answers OKAY once its pairing thread starts, then either a
length-prefixed "Successfully paired to <host:port> [guid=<guid>]" or a
second status, FAIL, with the message ("Failed: Unable to start pairing
client.", "Failed: Wrong password or connection was dropped."). FAIL
replies reject with Parser.FailError; any other reply that isn't a
success rejects with an Error carrying the reply. The result type,
PairResult, holds the reported address, the guid and the raw reply.
Fixes #529
Signed-off-by: Karol Wrótniak <karol.wrotniak@droidsonroids.pl>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
From review: - Put an IPv6 host in brackets; the server can't split fe80::1:37000. - Reject, before connecting, a code that is not a non-empty string or contains ':' (the server splits the request at it), a port outside 1-65535, and a host that already includes the port. - Add pair(address, code), so the 'host:port' shown in the device's dialog can be passed as is, like connect() accepts it. - Mask the code in the adb:command debug log. - Reject a 'Failed: ...' reply with Parser.FailError, like a FAIL status. - End the connection on every outcome, also a cut-short reply. - Drop a comment claiming the FAIL check must come first. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Karol Wrótniak <karol.wrotniak@droidsonroids.pl>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #529
Adds
client.pair(address, code)andclient.pair(host, port, code), the equivalent ofadb pair <host>:<port> <code>. As withadb pair, the ADB server does the TLS/SPAKE2 pairing itself (platform-tools 30+). adbkit only sends the host queryhost:pair:<code>:<host>:<port>, the same oneadb pairsends (StringPrintf("host:pair:%s:%s", password, host)in AOSP'scommandline.cpp), and reads the outcome. It is built the same way asclient.connect().addressis thehost:portshown in the device's dialog ([ipv6]:portfor IPv6), so it can be passed as is.What the server actually replies
The server pairs in a service thread, so it answers
OKAYas soon as that thread starts. The outcome follows:FAIL, followed by the length-prefixed message. This is observed, not assumed (see below).Successfully paired to <host:port> [guid=<guid>]. This format is taken from AOSP and has not been observed here, because that needs a real phone.FAILimmediately (unknown host service).The command handles all of these:
OKAY+Successfully paired to …{ address, guid?, reply }(PairResult, exported).OKAY+FAIL+ messageParser.FailErrorcarrying the server's message.FAIL+ messageParser.FailError.OKAY+ any other textParser.FailErrorcarrying that text, so callers handle one error type.A defensive branch also accepts
OKAY OKAY <value>. The connection is ended on every outcome, including a reply that is cut short or times out.Argument checks
These reject with a
TypeErrorbefore any connection is opened::(the server splits the request at the first:after the code); a number gets its own message, since it loses a leading zero;hostthat already includes the port in the three-argument form (usepair(address, code)), and an empty host.An IPv6 host goes out in brackets (
host:pair:<code>:[fe80::1]:37000); without them the server can't split host and port. Theadb:commanddebug log shows the request with the code masked (host:pair:******:…).The code is a
stringbecause pairing codes can start with0.addressis the pairing address the server reports, not a serial. The JSDoc and README make both points:client.connect()with the device's connect port afterwards, not the pairing port.Checks against the local ADB server (platform-tools 37.0.3, host queries only, no device involved)
Raw bytes from the server for
host:pair:123456:127.0.0.1:1(closed port):client.pair('127.0.0.1', 1, '123456')rejects after 22 ms (pair('[::1]:1', '123456')andpair('::1', 1, '123456')send[::1]:1and get the same reply, so the server parses the bracketed form):A local TCP listener that accepts and immediately drops the connection gives this raw reply:
client.pair()against it rejects withFailError: Failure: 'Failed: Wrong password or connection was dropped.'.Other observations:
host:pair:123456:127.0.0.1) givesOKAYFAIL002eInvalid port while parsing address [127.0.0.1]. Not every failure starts withFailed:, so success is detected by theSuccessfully pairedprefix rather than failure byFailed:.192.0.2.1:37000, TEST-NET-1) fails the same way after about 10 s; the JSDoc mentions the delay.adb37.0.3 CLI itself printserror: protocol fault (couldn't read status message)for the closed-port case, so it doesn't parse this reply shape either.Not tested end to end: a real pairing needs a phone with Wireless debugging on the same Wi-Fi network, so the success path is covered only by unit tests using the AOSP reply format.
Tests
test/adb/command/host/pair.mts, in the style of theconnecttests:OKAYFAIL…bytes rejecting withFailErrorOKAY+Failed: …reply rejecting withFailErrorFAIL(old server)OKAY OKAY <value>TypeError, writing nothing and ending the connectionclient.pair()withhost:port,[ipv6]:portand host and port apart, and invalid arguments rejecting without connectingUndoing the masking, the brackets or the final
end()each makes a test fail.npm run lint,npm run compileandnpm testpass (354 passing).🤖 Generated with Claude Code