3c47b08d98
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.
96 lines
5.5 KiB
Markdown
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.
|