Files
pipelines/docs/notes/foreground-reconnect.md
alan 3c47b08d98 Restore connections on app foregrounding
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.
2026-10-18 12:37:20 +01:00

5.5 KiB

Android: coming back to the app restores the connection

What this item changed

Android app only.

  • data/transport/ConnectionRecovery.kt (new): ForegroundAction and the one pure foregroundAction(state, confirmedAlive) policy — Idle → leave alone (a deliberate Disconnect is the only way the client reaches Idle), Connected with a confirmed-alive socket → leave alone, Connected unconfirmed → reconnect, Connecting/Disconnected → reconnect.
  • data/ForegroundReconnector.kt (new): the one lifecycle-aware owner. It is created once with the Application and observes ProcessLifecycleOwner, never the Activity or the ViewModel (both recreated). On ON_START it 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 claims Connected is first confirmed with the existing ping, 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; confirmAlive is repository.ping(), reconnect is ServerUrl.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 use repository.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 every WebSocketListener callback 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.kts and gradle/libs.versions.toml: androidx.lifecycle:lifecycle-process 2.8.7 (already in the offline cache, with its androidx.startup/androidx.tracing transitives).
  • Tests: data/transport/ConnectionRecoveryTest.kt (5 cases) and data/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 with ping, 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 with ping before 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) lists data/transport and data. It should name the two new files — data/transport/ConnectionRecovery.kt (the pure return-to-foreground policy) and data/ForegroundReconnector.kt (the process-lifecycle owner) — and the new androidx.lifecycle:lifecycle-process dependency behind the owner.

Not stale

  • android/AGENTS.md names neither the presence nor the absence of a lifecycle observer; its "Where things are" summary stays correct (it could optionally add the new owner beside data/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/pong on 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.