Merge preserved connection reconnect baseline

This commit is contained in:
2026-10-18 13:44:20 +01:00
8 changed files with 393 additions and 0 deletions
+1
View File
@@ -58,6 +58,7 @@ dependencies {
implementation(libs.androidx.compose.material.icons.extended)
implementation(libs.androidx.navigation.compose)
implementation(libs.androidx.lifecycle.runtime.compose)
implementation(libs.androidx.lifecycle.process)
implementation(libs.androidx.lifecycle.viewmodel.compose)
implementation(libs.androidx.lifecycle.viewmodel.ktx)
implementation(libs.kotlinx.coroutines.android)
@@ -1,12 +1,15 @@
package net.awan.pipelines
import android.app.Application
import androidx.lifecycle.ProcessLifecycleOwner
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.SupervisorJob
import net.awan.pipelines.data.ForegroundReconnector
import net.awan.pipelines.data.PipelinesRepository
import net.awan.pipelines.data.SettingsRepository
import net.awan.pipelines.data.transport.PipelinesClient
import net.awan.pipelines.data.transport.ServerUrl
import net.awan.pipelines.notify.RunNotifier
/**
@@ -30,8 +33,39 @@ class PipelinesApplication : Application() {
*/
val runNotifier: RunNotifier by lazy { RunNotifier(this) }
/**
* The one owner of return-to-foreground recovery: when the process comes back
* to the front it restores a connection the background took away, with no
* interaction. It is created once with the Application and observes the
* process lifecycle, so every Activity and ViewModel recreation leaves it
* untouched. The liveness check is the existing `ping`; the reconnect is the
* same shared-client connect the app's own Connect/Reconnect uses, so the
* policy lives only in `foregroundAction` and the client's backoff stays the
* only reconnect mechanism.
*/
private val foregroundReconnector: ForegroundReconnector by lazy {
ForegroundReconnector(
state = { repository.connectionState.value },
confirmAlive = {
// The existing ping is the positive check: on a dead socket it
// throws (or never answers) instead of returning, so reaching the
// next line is the proof of life.
repository.ping()
true
},
reconnect = {
// A saved URL that no longer validates is left for Settings to
// report; there is nothing to reconnect to.
val validated = ServerUrl.validate(settings.serverUrl.value)
if (validated.valid) repository.recover(validated)
},
scope = applicationScope,
)
}
override fun onCreate() {
super.onCreate()
runNotifier.ensureChannel()
ProcessLifecycleOwner.get().lifecycle.addObserver(foregroundReconnector)
}
}
@@ -0,0 +1,81 @@
package net.awan.pipelines.data
import androidx.lifecycle.DefaultLifecycleObserver
import androidx.lifecycle.LifecycleOwner
import kotlinx.coroutines.CancellationException
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.launch
import kotlinx.coroutines.withTimeoutOrNull
import net.awan.pipelines.data.transport.ConnectionState
import net.awan.pipelines.data.transport.ForegroundAction
import net.awan.pipelines.data.transport.foregroundAction
/**
* The one lifecycle-aware owner of the app's return-to-foreground recovery.
*
* While another app is in front Android freezes — and often kills — this process,
* so the socket it holds dies or goes quiet and the client's own bounded backoff
* either never starts or starts too late for the operator, who comes back and
* taps Connect. The client's backoff (see `PipelinesClient.scheduleReconnect`) is
* still the only reconnect mechanism; this owner only decides *when* to drive it,
* and does so the moment the app becomes visible again.
*
* It observes the whole process lifecycle (a `ProcessLifecycleOwner`), never the
* Activity or the ViewModel, both of which Android recreates: the owner is
* created once with the Application and survives every recreation. The decision
* itself is the one pure [foregroundAction] policy; this class supplies only the
* current state, a positive liveness check and the reconnect effect, so the
* policy is unit-testable with no device, socket or framework.
*/
class ForegroundReconnector(
private val state: () -> ConnectionState,
private val confirmAlive: suspend () -> Boolean,
private val reconnect: () -> Unit,
private val scope: CoroutineScope,
private val confirmTimeoutMillis: Long = CONFIRM_TIMEOUT_MILLIS,
) : DefaultLifecycleObserver {
/**
* The app became visible again. A state the policy calls reconnecting is
* reconnected at once — the pending backoff delay is cancelled by the
* reconnect effect, so the operator never waits it out. A socket the state
* still calls Connected is first confirmed to answer, so a silent
* "Connected" is never trusted; the state is re-read afterwards, because the
* socket's own failure callback may have run while the check was in flight.
*/
override fun onStart(owner: LifecycleOwner) {
val before = state()
if (before !is ConnectionState.Connected) {
if (foregroundAction(before, confirmedAlive = false) == ForegroundAction.Reconnect) reconnect()
return
}
scope.launch {
val alive = confirm()
if (foregroundAction(state(), alive) == ForegroundAction.Reconnect) reconnect()
}
}
/**
* Confirms a supposedly-connected socket still answers, bounded so a dead one
* cannot hold recovery: the check runs off the main thread on the app scope
* and a probe that fails, throws or outlives its budget counts as not alive.
*/
private suspend fun confirm(): Boolean =
withTimeoutOrNull(confirmTimeoutMillis) {
try {
confirmAlive()
} catch (t: Throwable) {
if (t is CancellationException) throw t
false
}
} ?: false
companion object {
/**
* Bounds the liveness check. A healthy round trip on the trusted LAN/VPN
* is far shorter, so a socket that cannot answer is noticed promptly
* instead of holding the "Connected" the operator is looking at.
*/
const val CONFIRM_TIMEOUT_MILLIS = 3_000L
}
}
@@ -66,6 +66,9 @@ class PipelinesRepository(
/** Opens the single shared connection to a validated server URL. */
fun connect(validated: ServerUrl.Validated) = client.connect(validated)
/** Recovers a lost connection without reversing an explicit Disconnect. */
fun recover(validated: ServerUrl.Validated) = client.recover(validated)
/** Explicit disconnect; the client then stays Idle. */
fun disconnect() = client.disconnect()
@@ -0,0 +1,40 @@
package net.awan.pipelines.data.transport
/** What the app does with the connection the moment it becomes visible again. */
enum class ForegroundAction {
/** Leave the connection exactly as it is. */
LeaveAlone,
/** Re-establish the connection now, cancelling any pending reconnect delay. */
Reconnect,
}
/**
* The app's return-to-foreground recovery policy, in one pure place.
*
* Android freezes and often kills a backgrounded app's process, so the socket
* the app holds dies or goes quiet while another app is in front and nothing in
* the process notices in time. Coming back must restore that connection without
* the operator tapping Connect — but an explicit Disconnect is the operator's
* own decision and stays authoritative. A deliberate Disconnect is the only way
* the client reaches [ConnectionState.Idle], so Idle is left alone; every other
* state reconnects.
*
* A still [ConnectionState.Connected] socket is not trusted on return: a frozen
* process can leave it claiming Connected while it answers nothing, which is
* exactly the stale state this replaces. The caller therefore checks it with a
* positive probe (the existing ping) and passes the verdict as [confirmedAlive];
* only a connection just confirmed to answer is left alone.
*
* @param state the connection state at the moment the app became visible again.
* @param confirmedAlive whether a [ConnectionState.Connected] socket has just
* been confirmed to answer. It is consulted only for Connected; every other
* state carries its own answer.
*/
fun foregroundAction(state: ConnectionState, confirmedAlive: Boolean): ForegroundAction = when (state) {
ConnectionState.Idle -> ForegroundAction.LeaveAlone
is ConnectionState.Connected ->
if (confirmedAlive) ForegroundAction.LeaveAlone else ForegroundAction.Reconnect
is ConnectionState.Connecting -> ForegroundAction.Reconnect
is ConnectionState.Disconnected -> ForegroundAction.Reconnect
}
@@ -0,0 +1,138 @@
package net.awan.pipelines.data
import androidx.lifecycle.Lifecycle
import androidx.lifecycle.LifecycleOwner
import java.util.concurrent.CountDownLatch
import java.util.concurrent.TimeUnit
import java.util.concurrent.atomic.AtomicInteger
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.delay
import net.awan.pipelines.data.transport.ConnectionState
import org.junit.Assert.assertEquals
import org.junit.Test
/**
* The one lifecycle-aware owner of return-to-foreground recovery: it applies the
* pure `foregroundAction` policy to the state it reads, confirms a supposedly
* connected socket before trusting it, and reconnects when — and only when — the
* policy says so. The state, the liveness check and the reconnect are injected,
* so the owner is exercised with no device, socket or Android framework. The
* owner never touches the LifecycleOwner it is handed.
*/
class ForegroundReconnectorTest {
private val reconnects = AtomicInteger(0)
private val probes = AtomicInteger(0)
private val owner = object : LifecycleOwner {
override val lifecycle: Lifecycle get() = throw UnsupportedOperationException("not used")
}
private val connected = ConnectionState.Connected(build = null, serverTime = null)
/**
* A reconnector whose probe answers [alive] without suspending, so
* `Dispatchers.Unconfined` runs the whole `onStart` decision inline and the
* assertions below hold the moment it returns.
*/
private fun reconnector(
state: () -> ConnectionState,
alive: suspend () -> Boolean = { true },
) = ForegroundReconnector(
state = state,
confirmAlive = { probes.incrementAndGet(); alive() },
reconnect = { reconnects.incrementAndGet() },
scope = CoroutineScope(Dispatchers.Unconfined),
)
@Test
fun aDeliberateDisconnectIsLeftAloneAndNotEvenProbed() {
reconnector(state = { ConnectionState.Idle }).onStart(owner)
assertEquals(0, probes.get())
assertEquals(0, reconnects.get())
}
@Test
fun aDroppedConnectionReconnectsImmediatelyWithoutProbing() {
reconnector(state = { ConnectionState.Disconnected("socket closed", retrying = true) }).onStart(owner)
assertEquals("a dropped socket has nothing to confirm", 0, probes.get())
assertEquals(1, reconnects.get())
}
@Test
fun aConfirmedConnectedSocketIsLeftAlone() {
reconnector(state = { connected }).onStart(owner)
assertEquals(1, probes.get())
assertEquals(0, reconnects.get())
}
@Test
fun aConnectedSocketThatDoesNotAnswerReconnects() {
reconnector(state = { connected }, alive = { false }).onStart(owner)
assertEquals(1, probes.get())
assertEquals(1, reconnects.get())
}
@Test
fun aProbeThatThrowsIsNotAlive() {
reconnector(
state = { connected },
alive = { throw IllegalStateException("socket closed") },
).onStart(owner)
assertEquals(1, reconnects.get())
}
@Test
fun aSocketThatDiesWhileTheProbeRunsStillReconnects() {
// The socket's own failure callback lands mid-check; the owner re-reads
// the state and the policy then decides on what is actually there.
var state: ConnectionState = connected
reconnector(
state = { state },
alive = {
state = ConnectionState.Disconnected("socket closed", retrying = true)
false
},
).onStart(owner)
assertEquals(1, reconnects.get())
}
@Test
fun aDisconnectWhileTheProbeRunsStaysDisconnected() {
// The user can tap Disconnect while the bounded foreground probe is in
// flight. Re-reading state after that probe keeps the explicit choice
// authoritative rather than reconnecting over it.
var state: ConnectionState = connected
reconnector(
state = { state },
alive = {
state = ConnectionState.Idle
true
},
).onStart(owner)
assertEquals(0, reconnects.get())
}
@Test
fun aProbeThatNeverAnswersIsNotAliveWhenItsBudgetExpires() {
val done = CountDownLatch(1)
val reconnector = ForegroundReconnector(
state = { connected },
confirmAlive = { delay(5_000); true },
reconnect = {
reconnects.incrementAndGet()
done.countDown()
},
scope = CoroutineScope(Dispatchers.Unconfined),
confirmTimeoutMillis = 20L,
)
reconnector.onStart(owner)
assertEquals(
"the bounded check must give up on its own rather than hold the UI's Connected",
true,
done.await(2, TimeUnit.SECONDS),
)
assertEquals(1, reconnects.get())
}
}
+1
View File
@@ -23,6 +23,7 @@ androidx-compose-material3 = { group = "androidx.compose.material3", name = "mat
androidx-compose-material-icons-extended = { group = "androidx.compose.material", name = "material-icons-extended" }
androidx-navigation-compose = { group = "androidx.navigation", name = "navigation-compose", version.ref = "navigationCompose" }
androidx-lifecycle-runtime-compose = { group = "androidx.lifecycle", name = "lifecycle-runtime-compose", version.ref = "lifecycle" }
androidx-lifecycle-process = { group = "androidx.lifecycle", name = "lifecycle-process", version.ref = "lifecycle" }
androidx-lifecycle-viewmodel-compose = { group = "androidx.lifecycle", name = "lifecycle-viewmodel-compose", version.ref = "lifecycle" }
androidx-lifecycle-viewmodel-ktx = { group = "androidx.lifecycle", name = "lifecycle-viewmodel-ktx", version.ref = "lifecycle" }
kotlinx-coroutines-android = { group = "org.jetbrains.kotlinx", name = "kotlinx-coroutines-android", version.ref = "coroutines" }
+95
View File
@@ -0,0 +1,95 @@
# 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.