Redesign error model: typed transport exceptions + operation result types (breaking)

[steviec]

The problem

dadb funnels nearly every failure through bare java.io.IOException, so a caller cannot tell apart "the connection is dead — reconnect" (socket reset, handshake/auth failed) from "the connection is fine, but the operation failed" (apk rejected, remote file missing, non-zero exit). Today the only way to distinguish them is string-matching exception messages.

The approach

Make the error model adbd-aware, grounded in the ADB wire protocol (packages/modules/adb/protocol.txt). One principle:

An exception means "I could not get an outcome — the transport is in trouble." A returned value means "I got an outcome — here is whether the operation succeeded."

Two orthogonal axes:

1. Transport failures throw a sealed AdbException : IOException hierarchy (one type per documented adbd failure point). No bare IOException leaks.
2. Operation outcomes are returned, not thrown — in-band adbd results (sync: FAIL, shell,v2 exit code) become values.

Breaking change → 2.0.0.

Types referenced below

• Thrown on transport failure — sealed AdbException : IOException: AdbConnectException, AdbAuthException, AdbStreamOpenException, AdbConnectionClosedException, AdbProtocolException
• Returned outcomes (new) — each sealed { Success | Failure(…) }: InstallResult, UninstallResult (Failure(reason, exitCode)), SyncResult, RootResult
• Returned, unchanged: AdbStream, AdbShellResponse (holds exitCode), AdbShellStream, AdbSyncStream, AutoCloseable

How error handling changes

// BEFORE — operation failure and a dead socket are the same exception
try {
    dadb.install(apk)
} catch (e: IOException) {
    // reconnect? or was the apk just bad? unknown
}

// AFTER — the outcome is a value; only the transport throws
try {
    when (val r = dadb.install(apk)) {
        is InstallResult.Success -> ...
        is InstallResult.Failure -> log.warn("install rejected: ${r.reason}")  // connection is fine
    }
} catch (e: AdbException) {
    reconnect()  // the transport died
}

Before / after — every public method

Method	Before	After
open(dest)	Returns: AdbStream Throws: IOException	Returns: AdbStream Throws: AdbException
shell(cmd)	Returns: AdbShellResponse Throws: IOException	Returns: AdbShellResponse Throws: AdbException
openShell(cmd)	Returns: AdbShellStream Throws: IOException	Returns: AdbShellStream Throws: AdbException
push(...)	Returns: Unit Throws: IOException (any error)	Returns: SyncResult Throws: AdbException (transport error)
pull(...)	Returns: Unit Throws: IOException (any error)	Returns: SyncResult Throws: AdbException (transport error)
openSync()	Returns: AdbSyncStream Throws: IOException	Returns: AdbSyncStream Throws: AdbException
install(...)	Returns: Unit Throws: IOException (any error)	Returns: InstallResult Throws: AdbException (transport error)
installMultiple(...)	Returns: Unit Throws: IOException (any error)	Returns: InstallResult Throws: AdbException (transport error)
uninstall(pkg)	Returns: Unit Throws: IOException (any error)	Returns: UninstallResult Throws: AdbException (transport error)
execCmd(...)	Returns: AdbStream Throws: IOException Throws: UnsupportedOperationException	Returns: AdbStream Throws: AdbException Throws: UnsupportedOperationException
abbExec(...)	Returns: AdbStream Throws: IOException Throws: UnsupportedOperationException	Returns: AdbStream Throws: AdbException Throws: UnsupportedOperationException
root()	Returns: Unit Throws: IOException (any error)	Returns: RootResult Throws: AdbException (transport error)
unroot()	Returns: Unit Throws: IOException (any error)	Returns: RootResult Throws: AdbException (transport error)
tcpForward(...)	Returns: AutoCloseable Throws: InterruptedException	Returns: AutoCloseable Throws: InterruptedException

Behavioral change

A connection dropped mid-stream now throws AdbConnectionClosedException instead of presenting as a clean end-of-stream. (A peer A_CLSE — normal stream termination — still reads as clean EOF.)

Also fixed in passing: pmInstall previously ignored the pm install result; an installMultiple finalize-error message interpolated the stream object instead of the response.

Test plan

• Full suite green on an emulator (PIXEL_6_API_31): 77 tests, 0 failed, 5 skipped — incl. open()→AdbStreamOpenException and the pm-install paths.
• 27 of those are unit tests driving the wire protocol with in-memory okio buffers (exception mapping, nextMessage clean-close vs socket-fault, sync FAIL/desync, and the result paths via a FakeDadb fixture).

Known follow-ups (non-blocking)

• Unit coverage for installMultiple failure branches and the auth-key-rejection branch (open()→AdbStreamOpenException is emulator-only — not deterministically unit-testable because open() uses a random localId).

🤖 Generated with Claude Code