Files
pipelines/docs/notes/foreground-reconnect.md
T
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

96 lines
5.5 KiB
Markdown

# 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.