Add a process-lifecycle foreground reconnector and pure recovery policy, wiring repository recovery through the validated saved endpoint. Include lifecycle-process and focused unit coverage while preserving explicit Disconnect and stale socket callback guards. Checked packaged templates and packaged authoring skill references: neither documents Android connection lifecycle behavior, so neither needs updating. Shared android README changes are recorded in docs/notes/foreground-reconnect.md for the docs-fold writer.
5.5 KiB
Android: coming back to the app restores the connection
What this item changed
Android app only.
data/transport/ConnectionRecovery.kt(new):ForegroundActionand the one pureforegroundAction(state, confirmedAlive)policy —Idle→ leave alone (a deliberate Disconnect is the only way the client reaches Idle),Connectedwith a confirmed-alive socket → leave alone,Connectedunconfirmed → reconnect,Connecting/Disconnected→ reconnect.data/ForegroundReconnector.kt(new): the one lifecycle-aware owner. It is created once with the Application and observesProcessLifecycleOwner, never the Activity or the ViewModel (both recreated). OnON_STARTit applies the policy: a non-Connected state reconnects at once, and the reconnect cancels the client's pending backoff delay, so the operator never waits it out; a state that still claimsConnectedis first confirmed with the existingping, bounded to 3 s, and the state is re-read afterwards (the socket's own failure callback can land while the check is in flight).PipelinesApplication.kt: wires the owner to the process lifecycle;confirmAliveisrepository.ping(),reconnectisServerUrl.validate(...) + repository.recover(...). Recovery shares the client's state lock with Disconnect, so a Disconnect after the probe has made its decision but before its reconnect effect runs stays authoritative. Manual Connect/Reconnect continue to userepository.connect(...); the client's bounded backoff stays the only reconnect mechanism and the policy lives in the one pure place.data/transport/PipelinesClient.kt:open()now closes the socket it supersedes, and everyWebSocketListenercallback ignores a socket that is no longer the current one (isCurrent). A failure the replaced socket reports late — the common case when the process was frozen while it died — can then neither clear the new connection nor schedule a reconnect that would undo the recovery.app/build.gradle.ktsandgradle/libs.versions.toml:androidx.lifecycle:lifecycle-process2.8.7 (already in the offline cache, with itsandroidx.startup/androidx.tracingtransitives).- Tests:
data/transport/ConnectionRecoveryTest.kt(5 cases) anddata/ForegroundReconnectorTest.kt(8 cases).
Shared documents this change makes stale
android/README.md.
- The Configuration section (
android/README.md:99-101) — "Tap Connect to open the single shared WebSocket (probed withping, showing the server build). Reconnect uses bounded exponential backoff; Disconnect stops it." — should record that coming back to the app restores the connection on its own: the process coming to the front reconnects immediately, cancelling the pending backoff delay, and when the last state still claims Connected it first confirms the socket withpingbefore trusting it. An explicit Disconnect stays authoritative and is never reconnected over; the manual Reconnect control stays, but normal recovery never needs it. - The Architecture block (
android/README.md:310-323) listsdata/transportanddata. It should name the two new files —data/transport/ConnectionRecovery.kt(the pure return-to-foreground policy) anddata/ForegroundReconnector.kt(the process-lifecycle owner) — and the newandroidx.lifecycle:lifecycle-processdependency behind the owner.
Not stale
android/AGENTS.mdnames neither the presence nor the absence of a lifecycle observer; its "Where things are" summary stays correct (it could optionally add the new owner besidedata/PipelinesRepository.kt).docs/app-integration-verification.md— its connection mentions are about restoring the stub URL, which this item does not change.- No packaged OpenCode skill reference (
internal/author/skill/references/) documents the app's connection lifecycle, so nothing there is stale.
Verified on the device, and what was not
Built and captured on the operator's Pixel 9 Pro XL (47241FDAS00DLK) from
51a2ba4 + this change; after merging main the same tree (now b93eee2) was
rebuilt and the full unit suite re-run (691 tests, 0 failures). The operator's
ws://10.0.0.75:8080/connect and /Users/alan/repos/pipelines were used
throughout and were not changed. The phone was left on main's build.
Captured, all with android/scripts/capture_png.sh (every image validated):
- a live socket on return: the server log shows a
ping/pongon the same connection at the second of the return and no reconnect — the positive check runs and a healthy connection is left alone; - a dead socket on return: the reconnect and re-subscribe land in the same second as the return, with no interaction (the process was frozen, so the client's own backoff had not run);
- no network on return: the banner reads "Disconnected: Failed to connect to …:8080 · retrying with backoff" — never a false Connected — and recovery follows on its own once the network returns;
- an explicit Disconnect: still "Not connected. Enter the server URL in Settings, then connect." after returning, with no reconnect in the server log.
Not verified live: the stale-Connected probe branch. In every capture the
frozen socket's own failure was delivered to the client before the lifecycle
owner ran, so the client already read Disconnected and no probe was attempted
(confirmed by the client's request-id sequence never skipping a value in the
server log). That branch — Connected still claimed, probe fails, reconnect — is
covered by unit tests only.