Android port reverse ownership¶
portReverse (src/server/portReverseTools.ts) lets a client own adb reverse
mappings for its session. PortReverseManager
(src/features/portReverse/PortReverseManager.ts) holds the state; the adb
commands and the adb reverse --list parser live in one place,
src/utils/android-cmdline-tools/adbReverse.ts.
Ownership¶
- One owner per device port: the routed session UUID, or
sessionless. State is per device serial, and the manager serialises operations on one device. The tool and the daemon’s session cleanup share one process-wide manager. - On
ensure, a mapping AutoMobile did not create for this session is aport_reverse_conflict, andensurenever overwrites it. That covers another session’s, a user’s or a prototype’s mapping, and one of AutoMobile’s own that something outside AutoMobile re-pointed. It judges conflicts on the device as listed, before any restore, so a refused request changes nothing. It adds with--no-rebind; if--listthen shows the port of a refused add, it reports a conflict. A later failed add rolls back this call’s earlier adds through the same re-checked removal. - A conflict gets one kind per port:
other_session(owned by another live session) orprototype(held by a prototype, to another host port). An unowned port isexternal_livewhen a host loopback connect to itstcp:target succeeds, otherwiseexternal_unknown. The owned map is in memory, so after a daemon restart every surviving mapping is external. A clash with the caller’s own mapping has no kind. ensure {reclaimStale: true}replaces an unowned mapping only when the call is session-routed (the session holds the device), the host spec istcp:H, andHostLoopbackProbefinds both 127.0.0.1:H and [::1]:H absent. The adb server tries IPv4 then IPv6, so either accepting means live. A timeout or unexpected error is unknown and never reclaims. It re-reads--listright before--removeand leaves a port that changed meanwhile (port_reverse_reclaim_failed, after rolling back this call’s adds). Otherwise it audit-logs the reclaim and adds the requested mapping with--no-rebind. The adb server connects thetcp:Htarget, soensureuses the probe only when that server is on this host’s loopback (adbServerScopeistcp-localhost-*). With a remote or non-TCP server every check is unknown: nothing is reclaimed and the result omitshostListening. A reclaimed mapping is not restored if a later add in the call fails: its host target was dead.removerefuses ports the session does not own, then re-reads--listand removes a port only while it still maps to the host port AutoMobile set. Theadb reverse --removecommand takes no host argument, so AutoMobile cannot detect a re-point between that read and the removal. The manager drops ownership only once removal succeeds or the mapping is gone or re-pointed. It never uses--remove-all.- The manager registers with an ownership view (
AdbReverseOwnership) built for sharing ports with another manager (#17253). It runs every operation on a device through its per-device queue (exclusive), so a--list, the ownership decision on it and the add or removal that follows never interleave. A task must never wait for another task on the same device. No other manager registers: prototypes make noadb reverse, so the manager never reports a prototype hold, theprototypeconflict orowner: "prototype". The view is in memory and per process.
Device listeners¶
list and verify read /proc/net/tcp and /proc/net/tcp6 in one shell call,
each file after a marker line, so a missing file is just an unreadable section.
They keep LISTEN rows whose local address is wildcard or loopback (0.0.0.0,
127/8, ::, ::1, ::ffff:127/8): the sockets that stop adbd binding the
reverse. A listened port that --list shows is reverse; any other is
process with the row’s uid, and pm list packages -U names the package only
when exactly one has that uid. No readable table is unsupported; there is no
netstat fallback. When an ensure add fails and --list shows no
reverse there, ensure reads the table again. A process holder turns the failure
into port_reverse_device_port_in_use; anything else keeps the adb error.
Verify probes¶
verify {probe: true} runs one bounded timeout nc connect per port on the
device and reads its exit status (portProbeScript). An HTTP probe
(probe: {http}) runs portHttpProbeScript. Its request lines are printf
arguments, never its format, so the path goes out verbatim. The path and Host
header must be printable ASCII without spaces (PROBE_PATH_PATTERN,
PROBE_HOST_HEADER_PATTERN), so no header can be injected. It sends HTTP/1.0
with Connection: close and prints the same exit marker as the TCP probe, so a
refused connect or a missing binary reads the same way. A status line at the
start of the output is a response whatever the exit status; anything else
without Connection refused is no_http_response, except silence until the
device timeout (timeout). Both probes retry once on an empty close (the first
connect after a host restart can race) and are bounded host-side by a
raceWithDeadline on the injected timer.
Restore¶
Reverse listeners live in adbd, so an adb server restart, adb reconnect, an
adbd restart (root/unroot) or an emulator restart drops them. Every
portReverse call except remove re-reads --list and re-adds the device’s
owned mappings that are missing, reporting the caller’s in restored or
restoreFailures. A failed restore keeps ownership so the next call retries.
The manager drops a port someone else re-mapped while ours was gone from
ownership and leaves it in place.
The reconcile(deviceId) method runs the same pass without a client call. The
transport-recovery scheduler calls it after a device’s adb transport recovers.
A periodic reconcile calls it for mappings removed while the transport stayed up
(a raw adb reverse --remove, another tool). Each ensure that leaves owned
mappings arms the periodic timer (injected Timer,
AUTOMOBILE_PORT_REVERSE_RECONCILE_INTERVAL_MS, default 30 s). Once no device
holds any, nothing re-arms it. A pass reconciles at most four devices, one
at a time, rotating through the rest on later passes; an unreachable device is
logged at debug and retried on a later pass. Disposal cancels the timer and
waits for a running pass.
Release¶
Session release and device unbind remove that session’s mappings on the device.
They register as pending device cleanup, so the next session waits for it.
Ownership is recorded only after adb reverse succeeds. A session with an
ensure still queued or running on the device therefore also counts as owning
mappings there. Its removal queues behind that ensure on the device’s serial
operation chain and removes whatever it added.
Device removal from the pool forgets sessionless ownership without sending a
command. The event cannot tell a disconnect or relaunch (whose reverses died
with the transport) from identity replacement (another device on the serial,
whose mappings are not ours). It leaves session-owned mappings alone: Android
recovery removes and re-adds a device while its session stays bound, and that
session’s next call restores its mappings.
A released mapping whose removal fails (or whose device cannot answer --list)
leaves owned, so it is never restored. It waits in a pending-removal set. The
device’s next --list retries the removal while the port still maps to the host
port AutoMobile set, and drops it once the port is gone or re-pointed. When
release reports that another device now answers on the serial (identity
replacement), the manager forgets the session’s ownership and the device’s
pending removals without sending any command.
Policy¶
Device and host ports must be 1024-65535 and, when
AUTOMOBILE_PORT_REVERSE_ALLOWED_PORTS is set, inside its ranges. An invalid
value allows nothing. The host side is always tcp:<port> on loopback. Ensure,
remove and restore are audit-logged at info with device and session.