From 9d05bc1bc62d29aeff5f8ac56a588d365a0738ca Mon Sep 17 00:00:00 2001 From: Dylan Murphy Date: Wed, 18 Nov 2026 16:15:17 -0500 Subject: [PATCH 1/3] Android: never expire a request The library no longer settles an entry 'expired'. It ignores the descriptor's expiresAt and configure()'s lifetimeMs. Removed: the expiry checks before an attempt, at each network poll and in each chunked part; the cap of in-worker backoffs, long releases and timeout releases at expiresAt; and the expiry wake of a parked entry at park, in the boot sweep and in the repair. A parked entry now gets no WorkManager row, and the sweep cancels a wake an earlier version left for it. New entries store expiresAt = Long.MAX_VALUE, so 11.3.0, which reads the field as a deadline, does not expire them after a downgrade. Entries from earlier versions keep their value and are sent. A stored 'expired' outcome is still delivered. The boot snapshot keeps delayedPastHorizon, now with its own 24-hour constant. Co-Authored-By: Claude Fable 5.2 --- CHANGELOG.md | 17 +++ README.md | 24 ++-- .../backgroundupload/BootSnapshot.kt | 10 +- .../backgroundupload/ChunkedUploadWorker.kt | 3 +- .../backgroundupload/EnqueueRules.kt | 4 +- .../backgroundupload/EntryParsing.kt | 7 +- .../ai/openspace/backgroundupload/EntryRun.kt | 39 +------ .../backgroundupload/LegacyImport.kt | 1 - .../backgroundupload/QueueController.kt | 28 ++--- .../openspace/backgroundupload/QueueEntry.kt | 14 ++- .../backgroundupload/RetryClassifier.kt | 5 - .../openspace/backgroundupload/Scheduler.kt | 20 +--- .../backgroundupload/UploadWorker.kt | 4 +- .../backgroundupload/UploaderModule.kt | 2 +- .../openspace/backgroundupload/WorkerOps.kt | 7 +- .../backgroundupload/EntryParsingTest.kt | 16 ++- .../backgroundupload/EntryRunTest.kt | 109 ++++++++++++++---- .../backgroundupload/EntryTransitionsTest.kt | 5 +- .../backgroundupload/NetworkDoorbellTest.kt | 30 ++++- .../backgroundupload/QueueControllerTest.kt | 82 ++++++++++--- .../backgroundupload/RetryClassifierTest.kt | 12 -- .../openspace/backgroundupload/TestSupport.kt | 3 +- .../backgroundupload/WorkerOpsTest.kt | 27 ++--- src/NativeRNFileUploader.ts | 11 +- src/index.ts | 4 +- src/types.ts | 7 +- 26 files changed, 302 insertions(+), 189 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c9a3e8a6..3efb465c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,22 @@ ## Unreleased +Android never expires a request. It ignores the descriptor's `expiresAt` and +`configure()`'s `lifetimeMs`, and accepts a call with or without them. A +request waits and retries until the server accepts it, it settles as an +error (for example a 4xx that the retry rules do not cover, or a missing +file), or the app cancels it. Before, Android +settled an entry `error` with `errorKind: 'expired'` once `expiresAt` +passed, and gave each parked (`awaiting-auth`) entry a WorkManager wake at +its `expiresAt` when that was less than 24 hours away. Those wakes could +fill the app's 20 JobScheduler slots, so other uploads had to wait. A parked +entry now has no WorkManager row and waits for `updateHeaders()`. An app +that needs a limit calls `cancel(id)` itself. Entries an earlier version +queued keep going and are sent, also when their `expiresAt` has passed. An +`expired` outcome that an earlier version stored and the app has not yet +acknowledged is still delivered, unchanged. New entries store an +`expiresAt` that 11.3.0 never reaches, so an app that goes back to 11.3.0 +does not expire them. + Android: a system stop now counts as a failed attempt only when it cut a request. Before, every stop at the job's time limit added one backoff step, up to 2 hours, also for a run that only waited for the network or for a free diff --git a/README.md b/README.md index 9dd25019..087aca78 100644 --- a/README.md +++ b/README.md @@ -137,7 +137,7 @@ TypeScript does not flag a misspelled key on an inferred arrow return. | `file` | Whole file body. Copied. Moved when `parts` is set. | | `parts` | Chunked over `file`: `[{ url, headers?, range: { start, end } }]`, bytes, end exclusive, tiling the file from 0. | | `accept` | Non-2xx responses to treat as success: `[{ status, bodyIncludes? }]`. | -| `expiresAt` | Epoch ms. Default now + `lifetimeMs` (14 days). Past it: `error` with `errorKind: 'expired'`. | +| `expiresAt` | Epoch ms. Default now + `lifetimeMs` (14 days). On iOS, past it: `error` with `errorKind: 'expired'`. Android ignores it and never expires a request. To put a limit on a request, call `cancel()`. | | `retry` | Per-request override of the `configure()` retry defaults: `backoff`, `terminalHttp.exempt`, and `transient` rules. See "Reliable delivery". | | `wifiOnly` | `true` waits for Wi-Fi before each attempt; `false` never waits. Overrides `setWifiOnly()` for this entry. Omit it to follow `setWifiOnly()`, including later toggles. | | `priority` | `'high'` or `'normal'` (default). On Android at most 4 requests transmit at once, and one of those slots is kept for `'high'`. Normal requests can use only the other 3, so a high-priority request, such as a small JSON POST that creates a session, gets a slot without waiting behind a backlog of file parts. It can still wait when other high-priority requests hold every slot. iOS ignores it for now. | @@ -190,11 +190,12 @@ Nothing else deletes them. different `url` or `method` counts as a different body. `mutate()` with an id that exists: -- Same body: resume. New headers, `expiresAt`, and `vars` replace the stored - ones. +- Same body: resume. New headers and `vars` replace the stored ones. On iOS + a new `expiresAt` does too; Android ignores `expiresAt`. - Different body (`data`, `form`, `file`, or `parts`) and the entry is not running (queued, paused, awaiting-auth, or settled): the descriptor, staged - body, `vars`, headers, and `expiresAt` are replaced and the entry reopens. + body, `vars`, and headers are replaced (on iOS `expiresAt` too) and the + entry reopens. It settles once more. - Different body, entry running: `mutate()` rejects with `E_RUNNING`. - A cancelled entry whose outcome is not yet acknowledged: a fresh @@ -341,8 +342,9 @@ while the app was dead from being sent twice. never gives up on its own; the app decides a poison policy from that number. 3. **One outcome per settle cycle.** `pause()` produces none, for the whole - queue or for a set of keys. A paused entry past `expiresAt` settles - `error` with `errorKind: 'expired'` when it is resumed. A same-id + queue or for a set of keys. On iOS a paused entry past `expiresAt` + settles `error` with `errorKind: 'expired'` when it is resumed. On + Android it runs again. A same-id `mutate()` on a settled entry reopens it, and it settles once more. 4. **Never before `mutate()` resolves.** Delivery for an id waits for the caller's promise. While native has not answered `enqueue`, the id's @@ -375,13 +377,13 @@ Retry classes: | Attempt outcome | Action | | --- | --- | | 2xx, or an `accept` rule matches | settle `completed` | -| network failure, 5xx, 408, 429 | exponential backoff (base 1 s, max 2 h, jitter 0.2) until `expiresAt`. On Android a call whose every try failed while it connected waits at most 15 minutes | +| network failure, 5xx, 408, 429 | exponential backoff (base 1 s, max 2 h, jitter 0.2). On iOS until `expiresAt`. Android has no deadline: it retries until a response settles the request or the app calls `cancel()`. On Android a call whose every try failed while it connected waits at most 15 minutes | | 401, 403 | park as `awaiting-auth`; resume on `updateHeaders()` | | other 4xx matching a `retry.transient` rule (`status`, optional `bodyIncludes`), under the rule's `maxRetries` | as transient. The first matching rule in the list wins. `maxRetries: 3` retries three matching responses; the fourth settles. No `maxRetries` means no cap. See "Transient rule counts" below. A rule for 401, 403, 408 or 429 is rejected at the call | | other 4xx in `retry.terminalHttp.exempt` (default `[404]`), when no rule matched | as transient, with no cap | | other 4xx, or a rule past its `maxRetries` | settle `error` with `errorKind: 'http'`, response attached | | payload missing on disk | settle `error` with `errorKind: 'file'` | -| `expiresAt` passed | settle `error` with `errorKind: 'expired'`; bytes kept | +| `expiresAt` passed (iOS only) | settle `error` with `errorKind: 'expired'`; bytes kept. Android never settles `expired`: it ignores `expiresAt` | | response body over 1 MB with a `response` parser | `onError` with `errorKind: 'truncated'`; the entry is `completed` | **Transient rule counts.** The library counts the responses each rule @@ -476,7 +478,7 @@ reached its key before it; see rule 5 of "Reliable delivery". | Option | Notes | | --- | --- | | `definitions` | Optional. Every definition, as `define()` returned it. Listing a handle imports its module, so its `define()` runs before replay starts. In development, a later `define()` of a key that is not listed logs a warning. That key still receives its outcomes, and `mutate()` works for it. Throws when it is not an array of handles. | -| `lifetimeMs` | Default `expiresAt` distance. Default 14 days. | +| `lifetimeMs` | Default `expiresAt` distance. Default 14 days. Android ignores it. | | `maxVarsBytes` | Cap on the JSON length of `vars`. Default 1 MB. `mutate()` rejects above it. JS-side only. | | `retry` | `{ backoff?: { baseMs, maxMs, jitter }, terminalHttp?: { exempt }, transient?: Array<{ status, bodyIncludes?, maxRetries? }> }`. Each object is optional, but one you give must be complete. Defaults 1 s, 2 h, 0.2, `[404]`, `[]`. A descriptor's `retry` replaces each field it names. | | `headers` | `() => Record`, called at `mutate()`. The descriptor merges over it. | @@ -503,8 +505,8 @@ await Upload.resume({ keys: ['capture.upload'] }); // captures run Both states are persisted natively. Each entry that moves emits one `state` event (`paused`, then `queued`). No outcome is produced and the bytes are -kept. A paused entry past `expiresAt` settles `error` with -`errorKind: 'expired'` when it is resumed. +kept. On iOS a paused entry past `expiresAt` settles `error` with +`errorKind: 'expired'` when it is resumed. On Android it runs again. On Android, `resume()` also ends some retry backoff waits of the queued entries in its scope, and they run at once. `pause()` keeps an entry's diff --git a/android/src/main/java/ai/openspace/backgroundupload/BootSnapshot.kt b/android/src/main/java/ai/openspace/backgroundupload/BootSnapshot.kt index 339bb894..618c62a2 100644 --- a/android/src/main/java/ai/openspace/backgroundupload/BootSnapshot.kt +++ b/android/src/main/java/ai/openspace/backgroundupload/BootSnapshot.kt @@ -13,11 +13,17 @@ package ai.openspace.backgroundupload * setting. entriesByWake counts the queued entries by what starts them: * their backoff wake, or the network or Wi-Fi doorbell; doorbells says * which doorbell rows exist. Both describe the rows and entries before the - * sweep changed them. + * sweep changed them. delayedPastHorizon counts the delayed runs due more + * than [FAR_DELAY_MS] ahead. This version makes none with the default retry + * settings (a backoff waits 2 hours at most), so such a run is a wake an + * earlier version left, or a backoff whose maxMs is over a day. */ internal object BootSnapshot { const val MESSAGE = "boot sweep" + /** A delayed run due further ahead than this holds a JobScheduler slot for long. */ + const val FAR_DELAY_MS = 24L * 60 * 60 * 1000 + /** * [entries]: the entries the sweep schedules, as it found them, so an * entry that was running when its process died still reads as running @@ -49,7 +55,7 @@ internal object BootSnapshot { "runsByState" to runs.groupingBy { it.state }.eachCount(), "delayedRuns" to runs.count { it.delayed }, "delayedPastHorizon" to runs.count { run -> - run.delayed && run.nextScheduleAt != null && run.nextScheduleAt - now > EXPIRY_WAKE_HORIZON_MS + run.delayed && run.nextScheduleAt != null && run.nextScheduleAt - now > FAR_DELAY_MS }, "maxRunAttemptCount" to runs.maxOfOrNull { it.runAttemptCount }, "entriesByWake" to entriesByWake(entries, runs, now, settings), diff --git a/android/src/main/java/ai/openspace/backgroundupload/ChunkedUploadWorker.kt b/android/src/main/java/ai/openspace/backgroundupload/ChunkedUploadWorker.kt index 81c7e6b0..66a5b1fd 100644 --- a/android/src/main/java/ai/openspace/backgroundupload/ChunkedUploadWorker.kt +++ b/android/src/main/java/ai/openspace/backgroundupload/ChunkedUploadWorker.kt @@ -89,7 +89,6 @@ internal class ChunkedTransfer(private val run: EntryRun) { val latest = run.ops.latest(run.entryId, run.generation) val stored = latest.descriptor!!.parts!![index] if (stored.accepted) return - if (RetryClassifier.isExpired(run.host.now(), latest.expiresAt)) throw EntryRun.ExpiredException() // A range past EOF can never be sent. length() is 0 for a missing file; // that case falls through to the attempt, which classifies it as file. @@ -125,7 +124,7 @@ internal class ChunkedTransfer(private val run: EntryRun) { onPartProgress(index, 0L) if (streakPart == null && acceptedHere.isNotEmpty()) base = 0 failures++ - run.backoffOrRelease(a.policy, base + failures, a.entry.expiresAt, a.cause, partStart) + run.backoffOrRelease(a.policy, base + failures, a.cause, partStart) } is EntryRun.AttemptResult.Terminal -> { onPartProgress(index, 0L) diff --git a/android/src/main/java/ai/openspace/backgroundupload/EnqueueRules.kt b/android/src/main/java/ai/openspace/backgroundupload/EnqueueRules.kt index 7e46604a..2a449ec7 100644 --- a/android/src/main/java/ai/openspace/backgroundupload/EnqueueRules.kt +++ b/android/src/main/java/ai/openspace/backgroundupload/EnqueueRules.kt @@ -97,7 +97,6 @@ object EnqueueRules { attempts = 0, bytesSent = runParts?.let { ChunkedParts.acceptedBytes(it) } ?: 0L, totalBytes = staged.body.totalBytes, - expiresAt = p.expiresAt, createdAt = now, updatedAt = now, headerGeneration = headerGeneration, @@ -121,7 +120,7 @@ object EnqueueRules { ) /** - * Same body. New headers, expiresAt, vars, accept, retry, wifiOnly, + * Same body. New headers, vars, accept, retry, wifiOnly, * priority, and notification flag replace the stored ones; the body and * accepted parts stay. A settled entry reopens with a fresh generation, * attempts 0 (attempts count the current generation), and no transient @@ -155,7 +154,6 @@ object EnqueueRules { state = if (running) EntryState.RUNNING else initialState(paused), attempts = if (reopen) 0 else existing.attempts, bytesSent = parts?.let { ChunkedParts.acceptedBytes(it) } ?: if (running) existing.bytesSent else 0L, - expiresAt = p.expiresAt, updatedAt = now, nextAttemptAt = null, backoffStreak = 0, diff --git a/android/src/main/java/ai/openspace/backgroundupload/EntryParsing.kt b/android/src/main/java/ai/openspace/backgroundupload/EntryParsing.kt index 76c9ad9e..f236a973 100644 --- a/android/src/main/java/ai/openspace/backgroundupload/EntryParsing.kt +++ b/android/src/main/java/ai/openspace/backgroundupload/EntryParsing.kt @@ -16,6 +16,9 @@ import java.net.URI * because React Native on iOS drops object keys whose value is null. Native * keeps the text as it came: it is the body that goes out. A dataJson of * "null" is the JSON body null, a real body. + * + * A descriptor may still carry `expiresAt`. Native ignores it: the library + * never expires a request. */ object EntryParsing { class InvalidEntryException(message: String) : IllegalArgumentException(message) @@ -25,7 +28,6 @@ object EntryParsing { val key: String, val varsJson: String, val descriptor: Descriptor, - val expiresAt: Long, ) private val METHODS = setOf("POST", "PUT", "PATCH", "DELETE", "GET") @@ -36,8 +38,7 @@ object EntryParsing { val varsJson = entry.string("varsJson") ?: invalid("varsJson is required") if (!JsonBridge.isJson(varsJson)) invalid("varsJson is not JSON text") val d = entry.map("descriptor") ?: invalid("descriptor is required") - val expiresAt = d.number("expiresAt")?.toLong() ?: invalid("descriptor.expiresAt is required") - return Parsed(id, key, varsJson, descriptor(d), expiresAt) + return Parsed(id, key, varsJson, descriptor(d)) } fun descriptor(d: ReadableMap): Descriptor { diff --git a/android/src/main/java/ai/openspace/backgroundupload/EntryRun.kt b/android/src/main/java/ai/openspace/backgroundupload/EntryRun.kt index 65abd594..c9de5298 100644 --- a/android/src/main/java/ai/openspace/backgroundupload/EntryRun.kt +++ b/android/src/main/java/ai/openspace/backgroundupload/EntryRun.kt @@ -4,7 +4,6 @@ import kotlinx.coroutines.CancellationException import okhttp3.RequestBody import java.io.IOException import java.util.UUID -import kotlin.math.max import kotlin.math.min /** @@ -16,7 +15,7 @@ import kotlin.math.min * settle, park, or release. The body kind at run time picks the transfer, * [SimpleTransfer] or [ChunkedTransfer], so a kind change under a queued run * is safe. The entry is read from the store at start and again before every - * attempt, so fresh headers and a new expiresAt reach a running run. + * attempt, so fresh headers reach a running run. */ internal class EntryRun( val entryId: String, @@ -37,8 +36,6 @@ internal class EntryRun( val partStart: Long?, ) : Exception("released for backoff") - class ExpiredException : Exception("expired before completion") - /** * The run waited long enough for the network and hands the wait to a * doorbell row ([WorkerOps.awaitNetwork]). @@ -176,14 +173,6 @@ internal class EntryRun( suspend fun run() { val initial = store.load(entryId) ?: return // forgotten while queued if (initial.legacy) return - if (initial.state == EntryState.AWAITING_AUTH) { - // The expiry wake of a parked entry. No attempt ran here, so the - // stored bytes stand. - if (RetryClassifier.isExpired(host.now(), initial.expiresAt)) { - ops.settle(entryId, initial.generation, expired(initial).copy(bytesSent = null)) - } - return - } if (initial.state != EntryState.QUEUED && initial.state != EntryState.RUNNING) return if (ops.settings().isPaused(initial.key)) return if (!waitUntilDue(initial)) return @@ -212,10 +201,6 @@ internal class EntryRun( endProgress(completed = false) ops.release(entryId, generation, backoff.nextAttemptAt, backoff.streak, cause = backoff.waitCause, partStart = backoff.partStart) return - } catch (error: ExpiredException) { - endProgress(completed = false) - ops.settle(entryId, generation, expired(current)) - return } catch (error: NotOwnedException) { endProgress(completed = false) return @@ -271,16 +256,6 @@ internal class EntryRun( private fun liveBytesOf(entry: QueueEntry): Long? = if (entry.body?.kind == StagedBody.CHUNKED) null else liveBytes - private fun expired(entry: QueueEntry) = Settlement.Failed( - errorKind = "expired", - message = "expired before completion", - response = null, - partIndex = null, - url = entry.descriptor?.reportUrl ?: "", - method = entry.descriptor?.method ?: "POST", - bytesSent = liveBytesOf(entry), - ) - /** * A system stop. Only a time-limit stop that cut a request is a failed * attempt. A run that only waited (for the network, a slot, or a short @@ -326,11 +301,10 @@ internal class EntryRun( val e = store.load(entryId) if (!EntryTransitions.isOwnedRun(e, generation)) return val streak = e!!.backoffStreak + 1 - val now = host.now() val backoff = RetryClassifier.backoffMs(policy(e), streak) // A cut request has no response. Which part it cut is not known. ops.release( - entryId, generation, RetryClassifier.nextAttemptAt(now, backoff, e.expiresAt), streak, wake, + entryId, generation, host.now() + backoff, streak, wake, cause = WaitCause.NO_RESPONSE, partStart = null, ) }.onFailure { @@ -402,7 +376,6 @@ internal class EntryRun( val s = ops.settings() val entry = ops.latest(entryId, generation) if (s.isPaused(entry.key)) throw PausedException() - if (RetryClassifier.isExpired(host.now(), entry.expiresAt)) throw ExpiredException() val wifiOnly = s.wifiOnlyFor(entry) val network = safeConnectivity(wifiOnly) { host.connectivity(wifiOnly) } if (network == Connectivity.Ok) return @@ -542,19 +515,17 @@ internal class EntryRun( suspend fun backoffOrRelease( policy: RetryClassifier.Policy, streak: Int, - expiresAt: Long, cause: String, partStart: Long? = null, ) { val backoff = RetryClassifier.backoffMs(policy, streak) val now = host.now() if (backoff <= RetryClassifier.IN_WORKER_BACKOFF_MAX_MS) { - val wait = min(backoff, max(0L, expiresAt - now)) - ops.backingOff(entryId, generation, now + wait, streak, cause, partStart) - host.sleep(wait) + ops.backingOff(entryId, generation, now + backoff, streak, cause, partStart) + host.sleep(backoff) return } - throw BackoffException(RetryClassifier.nextAttemptAt(now, backoff, expiresAt), streak, cause, partStart) + throw BackoffException(now + backoff, streak, cause, partStart) } fun progressStarted(total: Long, sent: Long) { diff --git a/android/src/main/java/ai/openspace/backgroundupload/LegacyImport.kt b/android/src/main/java/ai/openspace/backgroundupload/LegacyImport.kt index da5b19ab..44981274 100644 --- a/android/src/main/java/ai/openspace/backgroundupload/LegacyImport.kt +++ b/android/src/main/java/ai/openspace/backgroundupload/LegacyImport.kt @@ -94,7 +94,6 @@ object LegacyImport { attempts = 0, bytesSent = 0, totalBytes = 0, - expiresAt = at, createdAt = at, updatedAt = at, generation = 1, diff --git a/android/src/main/java/ai/openspace/backgroundupload/QueueController.kt b/android/src/main/java/ai/openspace/backgroundupload/QueueController.kt index 009c5ddd..c8813296 100644 --- a/android/src/main/java/ai/openspace/backgroundupload/QueueController.kt +++ b/android/src/main/java/ai/openspace/backgroundupload/QueueController.kt @@ -636,8 +636,9 @@ class QueueController( * orphans from a cancel race. Ack them. * 4. A completed or cancelled entry whose own record is gone: the ack * landed but the forget did not. Forget it. - * 5. Schedule every queued entry, and the expiry wake of every parked one. - * A row that WorkManager holds back after a stop is replaced + * 5. Schedule every queued entry. A parked entry gets no row, and a wake + * an earlier version made for it is cancelled. A row that WorkManager + * holds back after a stop is replaced * ([WorkScheduler.schedule]), so each queued entry can start now. * * 6. Delete the orphan directories that hold only copied bodies and are @@ -708,7 +709,7 @@ class QueueController( } if (cur !== e) changed += cur } - if (!paused || cur.state == EntryState.AWAITING_AUTH) { + if (!paused) { toSchedule += cur found += e } @@ -770,9 +771,8 @@ class QueueController( /** * Runs [entry] when it is queued. A backoff longer than a worker waits goes - * to the wake; a parked entry gets a wake at its expiry, so it settles - * 'expired' on time, once that expiry is near (see [EXPIRY_WAKE_HORIZON_MS]). - * Any other wake of the entry is stale, so it is cancelled. + * to the wake. A parked entry gets no row: updateHeaders() starts it. Any + * other wake of the entry is stale, so it is cancelled. * * With a [probe] (a repair: the boot sweep, resume(), a return to the * foreground, a same-id enqueue, setWifiOnly(), a doorbell), an entry @@ -799,12 +799,7 @@ class QueueController( cancelStaleWake(entry.id) } } - EntryState.AWAITING_AUTH -> - if (expiryWakeIsNear(entry.expiresAt, now)) { - scheduler.scheduleWake(entry, entry.expiresAt, replace = !keepWake) - } else { - cancelStaleWake(entry.id) - } + EntryState.AWAITING_AUTH -> cancelStaleWake(entry.id) else -> Unit } } @@ -888,13 +883,13 @@ class QueueController( * whose WorkManager calls failed. One WorkManager query. An entry with * no long wait and no row that can start now is scheduled as a repair * (its main row when the network fits, else its doorbell); an entry with - * a long wait and no wake gets its wake (KEEP); a parked entry gets its - * expiry wake. It does not end a backoff wait. When it fails too, it + * a long wait and no wake gets its wake (KEEP). A parked entry needs no + * row. It does not end a backoff wait. When it fails too, it * asks for itself again, later each time, up to [REPAIR_MAX_MS]. */ fun repairRows() { val now = clock() - val entries = store.all().filter { !it.legacy && (it.state == EntryState.QUEUED || it.state == EntryState.AWAITING_AUTH) } + val entries = store.all().filter { !it.legacy && it.state == EntryState.QUEUED } val pass = SchedulePass("repair") if (entries.isNotEmpty()) { val rows = try { @@ -909,8 +904,7 @@ class QueueController( val at = e.nextAttemptAt val longWait = at != null && at - now > RetryClassifier.IN_WORKER_BACKOFF_MAX_MS when { - e.state == EntryState.AWAITING_AUTH || longWait -> - if (e.id !in rows.withWake) pass.schedule { scheduleRun(e, keepWake = true) } + longWait -> if (e.id !in rows.withWake) pass.schedule { scheduleRun(e, keepWake = true) } e.id !in rows.startable -> pass.schedule { scheduleRun(e, probe = probe) } } } diff --git a/android/src/main/java/ai/openspace/backgroundupload/QueueEntry.kt b/android/src/main/java/ai/openspace/backgroundupload/QueueEntry.kt index ed149f51..87be476f 100644 --- a/android/src/main/java/ai/openspace/backgroundupload/QueueEntry.kt +++ b/android/src/main/java/ai/openspace/backgroundupload/QueueEntry.kt @@ -112,7 +112,14 @@ data class QueueEntry( val attempts: Int, val bytesSent: Long, val totalBytes: Long, - val expiresAt: Long, + /** + * Not read. This version never expires an entry. 11.3.0 and earlier read + * this field as the time to settle the entry 'expired', and read a + * missing one as 0, which is already past. So a new entry stores + * [NO_DEADLINE], and an app that goes back to such a version does not + * expire it. An entry from an earlier version keeps the value it had. + */ + val expiresAt: Long = NO_DEADLINE, val createdAt: Long, val updatedAt: Long, /** Set while the entry waits out a backoff: queued for a long one, running for a short one. */ @@ -153,6 +160,11 @@ data class QueueEntry( */ val backoffPartStart: Long? = null, ) { + companion object { + /** The [expiresAt] a new entry stores. 11.3.0 never reaches it, and does no sum with it that overflows. */ + const val NO_DEADLINE = Long.MAX_VALUE + } + val isLive get() = state.isLive val isSettled get() = !state.isLive diff --git a/android/src/main/java/ai/openspace/backgroundupload/RetryClassifier.kt b/android/src/main/java/ai/openspace/backgroundupload/RetryClassifier.kt index 8f0b5e5f..42630228 100644 --- a/android/src/main/java/ai/openspace/backgroundupload/RetryClassifier.kt +++ b/android/src/main/java/ai/openspace/backgroundupload/RetryClassifier.kt @@ -150,8 +150,6 @@ object RetryClassifier { */ fun failureKind(verdict: Verdict): String = (verdict as? Verdict.Terminal)?.errorKind ?: "network" - fun isExpired(now: Long, expiresAt: Long) = now >= expiresAt - /** * base * 2^(streak-1), capped at maxMs, then spread by ± jitter and capped * again. streak 1 is baseMs. @@ -163,7 +161,4 @@ object RetryClassifier { val spread = raw * (1.0 + jitter * (2.0 * random.nextDouble() - 1.0)) return min(spread, policy.maxMs.toDouble()).toLong().coerceAtLeast(0L) } - - /** The wake time, never later than expiresAt, so an entry expires on time. */ - fun nextAttemptAt(now: Long, backoffMs: Long, expiresAt: Long): Long = min(now + backoffMs, expiresAt) } diff --git a/android/src/main/java/ai/openspace/backgroundupload/Scheduler.kt b/android/src/main/java/ai/openspace/backgroundupload/Scheduler.kt index 58085a29..872f2100 100644 --- a/android/src/main/java/ai/openspace/backgroundupload/Scheduler.kt +++ b/android/src/main/java/ai/openspace/backgroundupload/Scheduler.kt @@ -15,20 +15,6 @@ import androidx.work.workDataOf import java.util.concurrent.TimeUnit import kotlin.math.min -/** - * How far ahead a parked entry's expiry wake may be scheduled. A delayed - * WorkManager row holds one of the app's JobScheduler slots (20 by default) - * until it runs, and WorkManager's in-process scheduler reads only the 200 - * oldest enqueued rows. Wakes years ahead, from long-lived requests that - * parked, filled both, so no other work started. An entry that expires past - * this horizon gets its wake from a later boot sweep, and settles at the - * first launch after it expires at the latest. - */ -const val EXPIRY_WAKE_HORIZON_MS = 24L * 60 * 60 * 1000 - -/** Whether an expiry wake at [expiresAt] is near enough to schedule now. */ -fun expiryWakeIsNear(expiresAt: Long, now: Long): Boolean = expiresAt - now <= EXPIRY_WAKE_HORIZON_MS - /** * When WorkManager 2.12.0 starts a row again after a system stop. Read from * the 2.12.0 classes: a stop sets the row back to ENQUEUED and keeps its @@ -141,9 +127,9 @@ interface WorkScheduler { fun scheduleAndWait(entry: QueueEntry) = schedule(entry) /** - * A run at [at] under a second unique name. Used for long backoffs and for - * the expiry of a parked entry. [replace] false keeps a wake that already - * exists (the boot sweep). + * A run at [at] under a second unique name. Used for long backoffs and + * after a stop. [replace] false keeps a wake that already exists (the boot + * sweep). */ fun scheduleWake(entry: QueueEntry, at: Long, replace: Boolean) diff --git a/android/src/main/java/ai/openspace/backgroundupload/UploadWorker.kt b/android/src/main/java/ai/openspace/backgroundupload/UploadWorker.kt index 9f1dbfb2..13b57aed 100644 --- a/android/src/main/java/ai/openspace/backgroundupload/UploadWorker.kt +++ b/android/src/main/java/ai/openspace/backgroundupload/UploadWorker.kt @@ -28,8 +28,6 @@ internal class SimpleTransfer(private val run: EntryRun) { var streak = start.backoffStreak while (true) { - val latest = run.ops.latest(run.entryId, run.generation) - if (RetryClassifier.isExpired(run.host.now(), latest.expiresAt)) throw EntryRun.ExpiredException() run.waitForNetwork() val a = run.attempt( @@ -47,7 +45,7 @@ internal class SimpleTransfer(private val run: EntryRun) { EntryRun.AttemptResult.Transient -> { run.reportProgress(0L, total) streak++ - run.backoffOrRelease(a.policy, streak, a.entry.expiresAt, a.cause) + run.backoffOrRelease(a.policy, streak, a.cause) } is EntryRun.AttemptResult.Terminal -> return Settlement.Failed(r.errorKind, r.message, r.response, null, a.url, a.method, bytesSent = run.liveBytes) diff --git a/android/src/main/java/ai/openspace/backgroundupload/UploaderModule.kt b/android/src/main/java/ai/openspace/backgroundupload/UploaderModule.kt index 26022767..d0391538 100644 --- a/android/src/main/java/ai/openspace/backgroundupload/UploaderModule.kt +++ b/android/src/main/java/ai/openspace/backgroundupload/UploaderModule.kt @@ -175,7 +175,7 @@ class UploaderModule(context: ReactApplicationContext) : /** * Saves the notification configuration (read by headless workers) and the * retry defaults. Each call replaces the full configuration. lifetimeMs is - * not stored: JS already applied it to expiresAt. + * ignored: the library never expires a request. */ override fun configure(options: ReadableMap) { NotificationConfig.save(reactApplicationContext, NotificationConfig.fromReadableMap(options)) diff --git a/android/src/main/java/ai/openspace/backgroundupload/WorkerOps.kt b/android/src/main/java/ai/openspace/backgroundupload/WorkerOps.kt index 1b7e85fb..6eafdd81 100644 --- a/android/src/main/java/ai/openspace/backgroundupload/WorkerOps.kt +++ b/android/src/main/java/ai/openspace/backgroundupload/WorkerOps.kt @@ -326,11 +326,8 @@ class WorkerOps( } } } - if (result == ParkResult.PARKED && next != null) { - events.state(next.toRow()) - // A parked entry still expires on time. A far expiry waits for a later boot sweep. - if (expiryWakeIsNear(next.expiresAt, now)) scheduler.scheduleWake(next, next.expiresAt, replace = true) - } + // A parked entry gets no row. updateHeaders() or a same-id enqueue starts it again. + if (result == ParkResult.PARKED && next != null) events.state(next.toRow()) return result } diff --git a/android/src/test/java/ai/openspace/backgroundupload/EntryParsingTest.kt b/android/src/test/java/ai/openspace/backgroundupload/EntryParsingTest.kt index 1a8b6a44..d1691614 100644 --- a/android/src/test/java/ai/openspace/backgroundupload/EntryParsingTest.kt +++ b/android/src/test/java/ai/openspace/backgroundupload/EntryParsingTest.kt @@ -24,7 +24,6 @@ class EntryParsingTest { assertEquals("e1", p.id) assertEquals("note", p.key) assertEquals("""{"b":2,"a":null}""", p.varsJson) // key order and null values survive - assertEquals(9_000L, p.expiresAt) assertEquals("POST", p.descriptor.method) assertEquals(text, p.descriptor.dataJson) assertEquals(StagedBody.JSON, p.descriptor.bodyKind) @@ -169,10 +168,23 @@ class EntryParsingTest { } } + @Test + fun `a descriptor parses with expiresAt missing, in the past, or of any type`() { + listOf( + JavaOnlyMap.of("url", "https://example.com/items"), + base(), // 9 s after 1970: long past + JavaOnlyMap.of("url", "https://example.com/items", "expiresAt", 0.0), + JavaOnlyMap.of("url", "https://example.com/items", "expiresAt", -1.0), + JavaOnlyMap.of("url", "https://example.com/items", "expiresAt", "soon"), + JavaOnlyMap.of("url", "https://example.com/items", "expiresAt", null), + ).forEach { d -> + assertEquals("$d", "https://example.com/items", EntryParsing.parse(entryMap(d)).descriptor.url) + } + } + @Test fun `what native can not run is rejected`() { val cases = listOf( - JavaOnlyMap.of("url", "https://example.com"), // no expiresAt JavaOnlyMap.of("expiresAt", 1.0), // no url and no parts base("dataJson", "1", "file", "/a"), // two body kinds base("method", "GET", "dataJson", "1"), // GET with a body diff --git a/android/src/test/java/ai/openspace/backgroundupload/EntryRunTest.kt b/android/src/test/java/ai/openspace/backgroundupload/EntryRunTest.kt index 84548031..605209cb 100644 --- a/android/src/test/java/ai/openspace/backgroundupload/EntryRunTest.kt +++ b/android/src/test/java/ai/openspace/backgroundupload/EntryRunTest.kt @@ -406,13 +406,20 @@ class EntryRunTest { assertEquals(listOf("file"), host.attempts.map { it.errorKind }) } + /** The stored entry as an earlier version saved it, with [expiresAt]. Native no longer reads it. */ + private fun withExpiresAt(expiresAt: Long, id: String = "e1") = + store.save(store.load(id)!!.copy(expiresAt = expiresAt)) + @Test - fun `a 401 parks the entry and wakes it at expiry`() { - controller.enqueue(parsed(expiresAt = 90_000)) + fun `a 401 parks the entry with no WorkManager row, also with expiresAt near`() { + controller.enqueue(parsed()) + withExpiresAt(host.clock + 80_000) + val scheduledBefore = scheduler.scheduled.toList() respond(401) run() assertEquals(EntryState.AWAITING_AUTH, store.load("e1")!!.state) - assertEquals(listOf("e1" to 90_000L), scheduler.wakes) + assertEquals(emptyList>(), scheduler.wakes) + assertEquals(scheduledBefore, scheduler.scheduled) assertEquals(listOf("error"), host.attempts.map { it.outcome }) assertEquals(emptyList(), journal.unacknowledged()) } @@ -434,29 +441,91 @@ class EntryRunTest { } @Test - fun `the expiry wake of a parked entry settles expired and keeps the stored bytes`() { - controller.enqueue(parsed(expiresAt = 20_000)) - store.save(store.load("e1")!!.copy(state = EntryState.AWAITING_AUTH, bytesSent = 3)) + fun `a wake that finds a parked entry past expiresAt leaves it parked, with no row and no outcome`() { + controller.enqueue(parsed()) + store.save(store.load("e1")!!.copy(state = EntryState.AWAITING_AUTH, parkedGeneration = 0, bytesSent = 3, expiresAt = 20_000)) + host.clock = 30_000 + run() // a wake an earlier version left + val e = store.load("e1")!! + assertEquals(EntryState.AWAITING_AUTH, e.state) + assertEquals(3, e.bytesSent) + assertEquals(emptyList(), journal.unacknowledged()) + assertEquals(emptyList(), host.requests) + assertEquals(emptyList>(), scheduler.wakes) + // New headers start it, and it is sent. + controller.updateHeaders(mapOf("Authorization" to "Bearer new")) run() - assertEquals(EntryState.AWAITING_AUTH, store.load("e1")!!.state) // not yet expired - host.clock = 20_000 + assertEquals(EntryState.COMPLETED, store.load("e1")!!.state) + assertEquals("Bearer new", host.requests.single().headers["Authorization"]) + } + + @Test + fun `an entry with expiresAt in the past is sent`() { + controller.enqueue(parsed()) + withExpiresAt(5_000) // host.clock is 10 000 run() - assertEquals("expired", outcome().errorKind) - assertEquals(3, outcome().bytesSent) - assertEquals(emptyList(), host.requests) + assertEquals(EntryState.COMPLETED, store.load("e1")!!.state) + assertEquals(1, host.requests.size) + assertEquals(EventJournal.KIND_COMPLETED, outcome().kind) } @Test - fun `an entry past expiresAt settles error expired`() { - controller.enqueue(parsed(expiresAt = 5_000)) + fun `a chunked entry with expiresAt in the past sends every part`() { + chunked() + withExpiresAt(5_000) run() - assertEquals("expired", outcome().errorKind) - assertEquals(emptyList(), host.requests) + assertEquals(EntryState.COMPLETED, store.load("e1")!!.state) + assertEquals(3, host.requests.size) + } + + @Test + fun `a network wait that passes expiresAt keeps polling, then sends`() { + controller.enqueue(parsed()) + withExpiresAt(host.clock + 5_000) + host.network = ArrayDeque(listOf(Connectivity.NoInternet, Connectivity.NoInternet)) + run() + assertEquals(listOf(EntryRun.CONNECTIVITY_POLL_MS, EntryRun.CONNECTIVITY_POLL_MS), host.sleeps) + assertEquals(EntryState.COMPLETED, store.load("e1")!!.state) } @Test - fun `a paused entry past expiresAt stays paused, and settles expired at resume`() { - controller.enqueue(parsed(expiresAt = 20_000)) + fun `a transient failure past expiresAt retries on the normal backoff`() { + controller.enqueue(parsed()) + withExpiresAt(host.clock + 500) + respond(503, 503, 200) + run() + // base 1 s, then 2 s: not cut at expiresAt, and no settle at it. + assertEquals(listOf(1_000L, 2_000L), host.sleeps) + assertEquals(EntryState.COMPLETED, store.load("e1")!!.state) + assertEquals(3, host.requests.size) + } + + @Test + fun `a long backoff past expiresAt releases to the full wait`() { + controller.configureRetry(RetryDefaults(baseMs = 60_000, jitter = 0.0)) + controller.enqueue(parsed()) + withExpiresAt(host.clock + 500) + respond(503) + run() + assertEquals(host.clock + 60_000, store.load("e1")!!.nextAttemptAt) + assertEquals(listOf("e1" to host.clock + 60_000), scheduler.wakes) + } + + @Test + fun `a timeout stop past expiresAt releases to the full next backoff step`() { + controller.enqueue(parsed()) + store.save(store.load("e1")!!.copy(backoffStreak = 2, expiresAt = host.clock + 500)) + host.stop = StopKind.TIME_LIMIT + host.handler = { _, _ -> throw CancellationException("timeout") } + assertThrows(CancellationException::class.java) { run() } + assertEquals(host.clock + 4_000, store.load("e1")!!.nextAttemptAt) + assertEquals(listOf("e1" to host.clock + 4_000), scheduler.wakes) + } + + @Test + fun `a paused entry past expiresAt stays paused, and is sent at resume`() { + controller.enqueue(parsed()) + withExpiresAt(20_000) controller.pause() host.clock = 30_000 run() // a wake that fires during the pause @@ -465,8 +534,8 @@ class EntryRunTest { controller.resume() assertEquals(EntryState.QUEUED, store.load("e1")!!.state) run() - assertEquals("expired", outcome().errorKind) - assertEquals(EntryState.ERROR, store.load("e1")!!.state) + assertEquals(EntryState.COMPLETED, store.load("e1")!!.state) + assertEquals(1, host.requests.size) } @Test @@ -1278,7 +1347,7 @@ class EntryRunTest { controller.enqueue(parsed(descriptor = desc(dataJson = """{"a":1}""", retry = before))) store.save(store.load("e1")!!.copy(transientHitsByRule = mapOf("404" to 40))) val after = RetryOverride(null, null, null, null, transient = listOf(bodyStopped.copy(maxRetries = 3), notFound48)) - controller.enqueue(parsed(descriptor = desc(dataJson = """{"a":1}""", retry = after), expiresAt = FAR_FUTURE + 1)) + controller.enqueue(parsed(descriptor = desc(dataJson = """{"a":1}""", retry = after))) assertEquals(mapOf("404" to 40), store.load("e1")!!.transientHitsByRule) respondShaped(400, 400, 200) run() diff --git a/android/src/test/java/ai/openspace/backgroundupload/EntryTransitionsTest.kt b/android/src/test/java/ai/openspace/backgroundupload/EntryTransitionsTest.kt index b65ffd8f..f1b30da2 100644 --- a/android/src/test/java/ai/openspace/backgroundupload/EntryTransitionsTest.kt +++ b/android/src/test/java/ai/openspace/backgroundupload/EntryTransitionsTest.kt @@ -12,7 +12,7 @@ class EntryTransitionsTest { fun `a settle on a cancelled entry or an older generation is not allowed`() { for (accepted in listOf(true, false)) { assertTrue(EntryTransitions.canSettle(entry(state = EntryState.RUNNING), 1, accepted)) - assertTrue(EntryTransitions.canSettle(entry(state = EntryState.AWAITING_AUTH), 1, accepted)) // the expiry wake + assertTrue(EntryTransitions.canSettle(entry(state = EntryState.AWAITING_AUTH), 1, accepted)) assertFalse(EntryTransitions.canSettle(entry(state = EntryState.CANCELLED), 1, accepted)) assertFalse(EntryTransitions.canSettle(entry(state = EntryState.COMPLETED), 1, accepted)) assertFalse(EntryTransitions.canSettle(entry(state = EntryState.RUNNING, generation = 2), 1, accepted)) @@ -200,7 +200,6 @@ class EnqueueRulesTest { descriptor = desc(url = null, method = "PUT", file = "/f", headers = mapOf("Authorization" to "Bearer new"), parts = parts.map { it.copy(accepted = false) }), varsJson = """{"n":2}""", - expiresAt = 77, ) val next = EnqueueRules.resumed(stored, incoming, paused = false, headerGeneration = 5, now = 9) assertEquals(EntryState.QUEUED, next.state) @@ -208,7 +207,7 @@ class EnqueueRulesTest { assertTrue(next.descriptor!!.parts!![0].accepted) assertEquals(10, next.bytesSent) assertEquals(4, next.attempts) - assertEquals(77, next.expiresAt) + assertEquals(stored.expiresAt, next.expiresAt) // not read, so not replaced assertEquals("""{"n":2}""", next.varsJson) assertEquals(5, next.headerGeneration) assertNull(next.parkedGeneration) diff --git a/android/src/test/java/ai/openspace/backgroundupload/NetworkDoorbellTest.kt b/android/src/test/java/ai/openspace/backgroundupload/NetworkDoorbellTest.kt index 3eb1bf3d..8f66febf 100644 --- a/android/src/test/java/ai/openspace/backgroundupload/NetworkDoorbellTest.kt +++ b/android/src/test/java/ai/openspace/backgroundupload/NetworkDoorbellTest.kt @@ -311,13 +311,37 @@ class NetworkDoorbellTest { assertEquals(work.now + 30_000, work.nextScheduleAt(bell)) } + @Test + fun `250 parked entries and 250 doorbell waiters with expiresAt 12 hours away make one sleeping row in all`() { + // An earlier version gave each parked entry a wake at its expiresAt + // when that was less than 24 hours away: 250 rows here, which fill the + // 20-row JobScheduler window. Now a parked entry has no row. + network(RequiredNetwork.NONE) + val expiresAt = work.now + 12 * 60 * minute + for (n in 1..250) { + store.save(entry(id = "p$n", state = EntryState.RUNNING, expiresAt = expiresAt)) + assertEquals(WorkerOps.ParkResult.PARKED, ops().park("p$n", 1, headerGeneration = 0)) + } + for (n in 1..250) handedOver("d$n", entry(id = "d$n", state = EntryState.RUNNING, expiresAt = expiresAt)) + newController().sweep() // the next app start + work.now = expiresAt + minute // past every expiresAt + newController().sweep() + val unfinished = work.rows.filter { !it.state.isFinished } + // One row: the network doorbell. No row of any entry. + assertEquals(1, unfinished.size) + assertEquals(doorbellRows(RequiredNetwork.CONNECTED), unfinished) + assertEquals(1, sleeping().size) + assertEquals(250, store.all().count { it.state == EntryState.AWAITING_AUTH }) + assertEquals(250, store.all().count { it.state == EntryState.QUEUED }) + assertEquals(emptyList(), journal.unacknowledged()) + } + @Test fun `with 20 older sleeping rows the doorbell is outside the JobScheduler window until some of them run`() { // Review probe P4. The result: while the app process is dead, the // doorbell cannot ring before one of the older rows has run. A backoff - // wake runs at the latest at its backoff maximum, an expiry wake within - // the 24-hour horizon. The app's start, resume() or foreground starts - // the entry sooner when the network fits. + // wake runs at the latest at its backoff maximum. The app's start, + // resume() or foreground starts the entry sooner when the network fits. network(RequiredNetwork.NONE) val older = (1..20).map { work.add("x$it#wake", initialDelay = 6 * 60 * minute) } handedOver("a") diff --git a/android/src/test/java/ai/openspace/backgroundupload/QueueControllerTest.kt b/android/src/test/java/ai/openspace/backgroundupload/QueueControllerTest.kt index 0c3438af..d0849752 100644 --- a/android/src/test/java/ai/openspace/backgroundupload/QueueControllerTest.kt +++ b/android/src/test/java/ai/openspace/backgroundupload/QueueControllerTest.kt @@ -90,16 +90,21 @@ class QueueControllerTest { } @Test - fun `same body on a queued entry resumes with the new headers, vars, and expiry`() { + fun `same body on a queued entry resumes with the new headers and vars, and keeps the stored expiresAt`() { controller.enqueue(parsed()) + assertEquals(QueueEntry.NO_DEADLINE, store.load("e1")!!.expiresAt) + // An earlier version's entry, with its expiresAt long past. + store.save(store.load("e1")!!.copy(expiresAt = 5)) val bodyFile = store.load("e1")!!.body!!.fileName - controller.enqueue(parsed(descriptor = desc(dataJson = """{"a":1}""", headers = mapOf("Authorization" to "Bearer new")), varsJson = """{"n":2}""", expiresAt = 5)) + controller.enqueue(parsed(descriptor = desc(dataJson = """{"a":1}""", headers = mapOf("Authorization" to "Bearer new")), varsJson = """{"n":2}""")) val e = store.load("e1")!! assertEquals("Bearer new", e.descriptor!!.headers["Authorization"]) assertEquals("""{"n":2}""", e.varsJson) - assertEquals(5, e.expiresAt) + assertEquals(5, e.expiresAt) // not read, so not replaced + assertEquals(EntryState.QUEUED, e.state) assertEquals(1, e.generation) assertEquals(bodyFile, e.body!!.fileName) + assertEquals(listOf("e1", "e1"), scheduler.scheduled) } @Test @@ -176,7 +181,7 @@ class QueueControllerTest { fun `same body on an error entry reopens it with attempts 0`() { controller.enqueue(parsed()) store.save(store.load("e1")!!.copy(state = EntryState.ERROR, attempts = 3, settledEventId = "ev")) - controller.enqueue(parsed(expiresAt = FAR_FUTURE + 1)) + controller.enqueue(parsed()) val e = store.load("e1")!! assertEquals(EntryState.QUEUED, e.state) assertEquals(2, e.generation) @@ -187,10 +192,10 @@ class QueueControllerTest { fun `a reopened error entry starts its transient hits at zero, a live one keeps them`() { controller.enqueue(parsed()) store.save(store.load("e1")!!.copy(state = EntryState.ERROR, transientHitsByRule = mapOf("404" to 3), settledEventId = "ev")) - controller.enqueue(parsed(expiresAt = FAR_FUTURE + 1)) + controller.enqueue(parsed()) assertEquals(null, store.load("e1")!!.transientHitsByRule) store.save(store.load("e1")!!.copy(transientHitsByRule = mapOf("404" to 1))) - controller.enqueue(parsed(expiresAt = FAR_FUTURE + 2)) + controller.enqueue(parsed()) assertEquals(mapOf("404" to 1), store.load("e1")!!.transientHitsByRule) } @@ -203,11 +208,11 @@ class QueueControllerTest { val counted = e.descriptor!!.parts!!.map { it.copy(transientHitsByRule = mapOf("400" to it.start.toInt() / 10 + 1)) } store.save(e.copy(descriptor = e.descriptor!!.copy(parts = counted))) // The same parts in the other order: each count follows its range start. - controller.enqueue(parsed(descriptor = forward.copy(parts = forward.parts!!.reversed()), expiresAt = FAR_FUTURE + 1)) + controller.enqueue(parsed(descriptor = forward.copy(parts = forward.parts!!.reversed()))) val live = store.load("e1")!!.descriptor!!.parts!! assertEquals(listOf(10L to mapOf("400" to 2), 0L to mapOf("400" to 1)), live.map { it.start to it.transientHitsByRule }) store.save(store.load("e1")!!.copy(state = EntryState.ERROR, settledEventId = "ev")) - controller.enqueue(parsed(descriptor = forward, expiresAt = FAR_FUTURE + 2)) + controller.enqueue(parsed(descriptor = forward)) val reopened = store.load("e1")!! assertEquals(2, reopened.generation) assertEquals(listOf(null, null), reopened.descriptor!!.parts!!.map { it.transientHitsByRule }) @@ -217,7 +222,7 @@ class QueueControllerTest { fun `same body on a live entry keeps its attempts`() { controller.enqueue(parsed()) store.save(store.load("e1")!!.copy(attempts = 3)) - controller.enqueue(parsed(expiresAt = FAR_FUTURE + 1)) + controller.enqueue(parsed()) assertEquals(3, store.load("e1")!!.attempts) } @@ -692,7 +697,7 @@ class QueueControllerTest { assertEquals(EntryState.AWAITING_AUTH, store.load("a")!!.state) assertEquals(EntryState.QUEUED, store.load("s")!!.state) assertTrue(scheduler.scheduled.containsAll(listOf("q", "r", "s"))) - // The parked one waits for its expiry, which is too far ahead for a wake. + // The parked one gets no row, and a wake an earlier version left is cancelled. assertEquals(emptyList>(), scheduler.wakes) assertTrue("a" in scheduler.cancelledWakes) } @@ -1154,7 +1159,7 @@ class QueueControllerTest { } @Test - fun `updateHeaders cancels the expiry wake of the entries it unparks`() { + fun `updateHeaders cancels a wake an earlier version left for the entries it unparks`() { store.save(entry(id = "p", state = EntryState.AWAITING_AUTH, parkedGeneration = 0)) controller.updateHeaders(mapOf("Authorization" to "Bearer new")) assertEquals(listOf("p"), scheduler.cancelledWakes) @@ -1314,19 +1319,64 @@ class QueueControllerTest { assertEquals(EntryState.QUEUED, store.load("r")!!.state) // "w" no longer waits for its backoff: the sweep runs it now. assertEquals(setOf("r", "q", "w"), scheduler.scheduled.toSet()) - assertEquals(setOf("p" to now + 50), scheduler.wakes.toSet()) + assertEquals(emptyList>(), scheduler.wakes) } @Test - fun `sweep cancels the stale wakes of due work and of a parked entry with a far expiry`() { + fun `sweep cancels the stale wakes of due work and of every parked entry, past expiresAt or not`() { store.save(entry(id = "q", state = EntryState.QUEUED)) store.save(entry(id = "w", state = EntryState.QUEUED, nextAttemptAt = now + 3_600_000).copy(waitCause = WaitCause.NO_RESPONSE, failedAt = now - 60_000)) store.save(entry(id = "far", state = EntryState.AWAITING_AUTH, expiresAt = FAR_FUTURE)) - store.save(entry(id = "near", state = EntryState.AWAITING_AUTH, expiresAt = now + EXPIRY_WAKE_HORIZON_MS)) + store.save(entry(id = "near", state = EntryState.AWAITING_AUTH, expiresAt = now + 60_000)) + store.save(entry(id = "past", state = EntryState.AWAITING_AUTH, expiresAt = now - 60_000)) controller.sweep() // The backoff wake of "w" is stale too: the sweep cleared its wait. - assertEquals(setOf("q", "w", "far"), scheduler.cancelledWakes.toSet()) - assertEquals(setOf("near" to now + EXPIRY_WAKE_HORIZON_MS), scheduler.wakes.toSet()) + assertEquals(setOf("q", "w", "far", "near", "past"), scheduler.cancelledWakes.toSet()) + assertEquals(emptyList>(), scheduler.wakes) + assertEquals(setOf("q", "w"), scheduler.scheduled.toSet()) + assertEquals(listOf(EntryState.AWAITING_AUTH, EntryState.AWAITING_AUTH, EntryState.AWAITING_AUTH), listOf("far", "near", "past").map { store.load(it)!!.state }) + assertEquals(emptyList(), journal.unacknowledged()) + } + + @Test + fun `an entry an earlier version saved with expiresAt in the past loads after a relaunch and is scheduled`() { + store.save(entry(id = "old")) + val file = File(store.entryDir("old"), "entry.json") + val text = file.readText() + assertTrue(text, text.contains("\"expiresAt\":${FAR_FUTURE}")) + file.writeText(text.replace("\"expiresAt\":${FAR_FUTURE}", "\"expiresAt\":${now - 60_000}")) + val relaunched = QueueStore(root, RequestIndex()) + val loaded = relaunched.load("old")!! + assertEquals(now - 60_000, loaded.expiresAt) + QueueController(relaunched, journal, settings, events, scheduler, { false }, { now }).sweep() + assertEquals(EntryState.QUEUED, relaunched.load("old")!!.state) + assertEquals(listOf("old"), scheduler.scheduled) + assertEquals(emptyList>(), scheduler.wakes) + assertEquals(emptyList(), journal.unacknowledged()) + } + + @Test + fun `a new entry stores the downgrade expiresAt, and it reads back exact`() { + controller.enqueue(parsed()) + assertTrue(File(store.entryDir("e1"), "entry.json").readText().contains("\"expiresAt\":${Long.MAX_VALUE}")) + assertEquals(Long.MAX_VALUE, QueueStore(root, RequestIndex()).load("e1")!!.expiresAt) + } + + @Test + fun `an expired outcome an earlier version stored is still delivered unchanged after the upgrade`() { + val dir = tmp.newFolder("journal-11.3") + val stored = record("00000000-0000-0000-0000-0000000000e1", id = "x", kind = EventJournal.KIND_ERROR).copy( + errorKind = "expired", message = "expired before completion", + ) + EventJournal(dir, retryLater = { _, _ -> }).append(stored) // no JS listener then + store.save(entry(id = "x", state = EntryState.ERROR, settledEventId = "00000000-0000-0000-0000-0000000000e1")) + val upgraded = EventJournal(dir, retryLater = { _, _ -> }) + QueueController(store, upgraded, settings, events, scheduler, { false }, { now }).sweep() + val delivered = upgraded.drain(listener).single() + assertEquals(stored.copy(deliveries = 1), delivered) + assertEquals(mapOf("errorKind" to "expired", "message" to "expired before completion"), delivered.toMap()["error"]) + assertEquals(EntryState.ERROR, store.load("x")!!.state) + assertEquals(emptyList(), scheduler.scheduled) } @Test diff --git a/android/src/test/java/ai/openspace/backgroundupload/RetryClassifierTest.kt b/android/src/test/java/ai/openspace/backgroundupload/RetryClassifierTest.kt index b840bd17..86220123 100644 --- a/android/src/test/java/ai/openspace/backgroundupload/RetryClassifierTest.kt +++ b/android/src/test/java/ai/openspace/backgroundupload/RetryClassifierTest.kt @@ -157,18 +157,6 @@ class RetryClassifierTest { } } - @Test - fun `nextAttemptAt clamps to expiresAt`() { - assertEquals(3_000, RetryClassifier.nextAttemptAt(now = 1_000, backoffMs = 2_000, expiresAt = 10_000)) - assertEquals(10_000, RetryClassifier.nextAttemptAt(now = 1_000, backoffMs = 7_200_000, expiresAt = 10_000)) - } - - @Test - fun `expiry is inclusive of the deadline`() { - assertFalse(RetryClassifier.isExpired(4_999, 5_000)) - assertTrue(RetryClassifier.isExpired(5_000, 5_000)) - } - @Test fun `policy overrides field by field`() { val defaults = RetryDefaults() diff --git a/android/src/test/java/ai/openspace/backgroundupload/TestSupport.kt b/android/src/test/java/ai/openspace/backgroundupload/TestSupport.kt index b4923d3e..8133b878 100644 --- a/android/src/test/java/ai/openspace/backgroundupload/TestSupport.kt +++ b/android/src/test/java/ai/openspace/backgroundupload/TestSupport.kt @@ -68,9 +68,8 @@ internal fun parsed( id: String = "e1", descriptor: Descriptor = desc(dataJson = """{"a":1}"""), varsJson: String = """{"n":1}""", - expiresAt: Long = FAR_FUTURE, key: String = "note", -) = EntryParsing.Parsed(id, key, varsJson, descriptor, expiresAt) +) = EntryParsing.Parsed(id, key, varsJson, descriptor) internal fun record( eventId: String, diff --git a/android/src/test/java/ai/openspace/backgroundupload/WorkerOpsTest.kt b/android/src/test/java/ai/openspace/backgroundupload/WorkerOpsTest.kt index d737c6e3..628b0275 100644 --- a/android/src/test/java/ai/openspace/backgroundupload/WorkerOpsTest.kt +++ b/android/src/test/java/ai/openspace/backgroundupload/WorkerOpsTest.kt @@ -320,23 +320,18 @@ class WorkerOpsTest { } @Test - fun `park sets awaiting-auth once and wakes at expiry`() { - store.save(entry(state = EntryState.RUNNING, expiresAt = 90_000)) - assertEquals(WorkerOps.ParkResult.PARKED, ops.park("e1", 1, headerGeneration = 0)) - val e = store.load("e1")!! - assertEquals(EntryState.AWAITING_AUTH, e.state) - assertEquals(0, e.parkedGeneration) - assertEquals(listOf("state:e1:awaiting-auth"), events.log) - assertEquals(listOf("e1" to 90_000L), scheduler.wakes) - assertEquals(emptyList(), journal.unacknowledged()) - } - - @Test - fun `park with an expiry past the horizon schedules no wake`() { - store.save(entry(state = EntryState.RUNNING, expiresAt = FAR_FUTURE)) - assertEquals(WorkerOps.ParkResult.PARKED, ops.park("e1", 1, headerGeneration = 0)) - assertEquals(EntryState.AWAITING_AUTH, store.load("e1")!!.state) + fun `park sets awaiting-auth once and makes no row, with expiresAt near or past`() { + for ((id, expiresAt) in listOf("near" to 90_000L, "past" to 1L)) { + store.save(entry(id = id, state = EntryState.RUNNING, expiresAt = expiresAt)) + assertEquals(WorkerOps.ParkResult.PARKED, ops.park(id, 1, headerGeneration = 0)) + val e = store.load(id)!! + assertEquals(EntryState.AWAITING_AUTH, e.state) + assertEquals(0, e.parkedGeneration) + } + assertEquals(listOf("state:near:awaiting-auth", "state:past:awaiting-auth"), events.log) assertEquals(emptyList>(), scheduler.wakes) + assertEquals(emptyList(), scheduler.scheduled) + assertEquals(emptyList(), journal.unacknowledged()) } @Test diff --git a/src/NativeRNFileUploader.ts b/src/NativeRNFileUploader.ts index 50948451..2e375138 100644 --- a/src/NativeRNFileUploader.ts +++ b/src/NativeRNFileUploader.ts @@ -13,6 +13,7 @@ import { TurboModuleRegistry } from 'react-native'; // and 6 mirror them. export interface Spec extends TurboModule { // Queue-wide settings: { lifetimeMs, retry, ...androidNotificationConfig }. + // Android ignores lifetimeMs and expiresAt: it never expires a request. // Android persists the notification config, so a headless WorkManager // relaunch (no JS) can read it. Each call replaces the full configuration. configure(options: CodegenTypes.UnsafeObject): void; @@ -36,11 +37,11 @@ export interface Spec extends TurboModule { // // Same id, again. The body is data/form/file/parts, and a different url or // method is a different body. - // - Same body: resume. New headers, expiresAt and vars replace the stored - // ones. + // - Same body: resume. New headers, expiresAt (iOS) and vars replace the + // stored ones. // - Different body (data/form/file/parts) and the entry is NOT running // (queued, paused, awaiting-auth, or settled): replace the descriptor, - // staged body, vars, headers and expiresAt, and reopen the entry. It + // staged body, vars, headers and expiresAt (iOS), and reopen the entry. It // settles once more. // - Different body, entry running: reject E_RUNNING. // - Cancelled-but-unacked entry: a fresh generation. ack forgets the entry @@ -63,8 +64,8 @@ export interface Spec extends TurboModule { // Each live entry that becomes paused moves to 'paused', and each that // stops being paused moves back to 'queued', with one 'state' event per // entry. A running attempt stops. No outcome is produced and no attempt - // event is emitted. A paused entry past expiresAt settles error/expired - // when it stops being paused. + // event is emitted. On iOS a paused entry past expiresAt settles + // error/expired when it stops being paused. // // pause, resume, setWifiOnly, updateHeaders and configure apply the new // settings in memory, then save them best-effort. A failed settings save diff --git a/src/index.ts b/src/index.ts index a36bc010..f6812faa 100644 --- a/src/index.ts +++ b/src/index.ts @@ -256,8 +256,8 @@ export const createUploadClient = ({ /** * No scope pauses the whole queue. `{ keys }` pauses the entries of those * keys, queued and future. No outcome is produced; live rows show - * 'paused'. A paused entry past its expiresAt settles error/expired when - * it resumes. + * 'paused'. On iOS a paused entry past its expiresAt settles + * error/expired when it resumes. Android never expires a request. */ const pause = async (scope?: PauseScope): Promise => native.pause(toNativeScope('pause', scope)); diff --git a/src/types.ts b/src/types.ts index 4e583cfb..df98e4d8 100644 --- a/src/types.ts +++ b/src/types.ts @@ -25,7 +25,8 @@ export type Method = 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'GET'; * Why a request failed. `http` means the server answered and the status was * not accepted. `network` is a transport failure. `file` means the payload is * missing on disk, so a retry can never succeed. `expired` means `expiresAt` - * passed. `truncated` means the response body hit the 1 MB cap, so the + * passed: iOS only, or an outcome an earlier Android version stored. + * `truncated` means the response body hit the 1 MB cap, so the * `response` parser could not run. `unknown` covers a parser throw. */ export type ErrorKind = @@ -126,7 +127,7 @@ export type RequestDescriptor = { /** Chunked over `file`. Each part sends its own byte range. */ parts?: Part[]; accept?: AcceptRule[]; - /** Epoch ms. Default now + `lifetimeMs`. */ + /** Epoch ms. Default now + `lifetimeMs`. Android ignores it. */ expiresAt?: number; retry?: Partial; /** @@ -395,7 +396,7 @@ export type ConfigureOptions = { * unlisted key still receives its outcomes. */ definitions?: readonly AnyDefined[]; - /** Default 14 days. Sets the default `expiresAt` of every entry. */ + /** Default 14 days. Sets the default `expiresAt` of every entry. Android ignores it. */ lifetimeMs?: number; /** * Default 1 MB. `mutate()` rejects `vars` whose JSON is longer. Only `vars` From 0e312bdf1acf237c61440bdeda70e144fb6b4bd6 Mon Sep 17 00:00:00 2001 From: Dylan Murphy Date: Wed, 18 Nov 2026 16:27:42 -0500 Subject: [PATCH 2/3] README: name every way an Android retry ends Co-Authored-By: Claude Fable 5.2 --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 087aca78..a47f2666 100644 --- a/README.md +++ b/README.md @@ -377,7 +377,7 @@ Retry classes: | Attempt outcome | Action | | --- | --- | | 2xx, or an `accept` rule matches | settle `completed` | -| network failure, 5xx, 408, 429 | exponential backoff (base 1 s, max 2 h, jitter 0.2). On iOS until `expiresAt`. Android has no deadline: it retries until a response settles the request or the app calls `cancel()`. On Android a call whose every try failed while it connected waits at most 15 minutes | +| network failure, 5xx, 408, 429 | exponential backoff (base 1 s, max 2 h, jitter 0.2). On iOS until `expiresAt`. Android has no deadline: it retries until a later attempt settles the request (accepted, a terminal status, or a missing file) or the app calls `cancel()`. On Android a call whose every try failed while it connected waits at most 15 minutes | | 401, 403 | park as `awaiting-auth`; resume on `updateHeaders()` | | other 4xx matching a `retry.transient` rule (`status`, optional `bodyIncludes`), under the rule's `maxRetries` | as transient. The first matching rule in the list wins. `maxRetries: 3` retries three matching responses; the fourth settles. No `maxRetries` means no cap. See "Transient rule counts" below. A rule for 401, 403, 408 or 429 is rejected at the call | | other 4xx in `retry.terminalHttp.exempt` (default `[404]`), when no rule matched | as transient, with no cap | From 58b7bfa39bf12ea80a8f0278a51c4d1b0a0c3deb Mon Sep 17 00:00:00 2001 From: Dylan Murphy Date: Wed, 18 Nov 2026 16:51:19 -0500 Subject: [PATCH 3/3] Store NO_DEADLINE on a re-queue, and leave the README and JS docs to the contract PR A same-body mutate() now writes expiresAt = Long.MAX_VALUE too, so an entry from 11.3.0 that is queued again here does not expire after a downgrade. The comment names the versions this is checked for: 11.0.2 to 11.3.0. README.md and the doc comments in src/ go back to the base branch. The contract PR rewrites the same sentences, and its text is the end state. The CHANGELOG entry now speaks of the native module only. Co-Authored-By: Claude Fable 5.2 --- CHANGELOG.md | 33 ++++++++++--------- README.md | 24 +++++++------- .../backgroundupload/EnqueueRules.kt | 2 ++ .../openspace/backgroundupload/QueueEntry.kt | 11 ++++--- .../backgroundupload/EntryTransitionsTest.kt | 2 +- .../backgroundupload/QueueControllerTest.kt | 4 +-- src/NativeRNFileUploader.ts | 11 +++---- src/index.ts | 4 +-- src/types.ts | 7 ++-- 9 files changed, 49 insertions(+), 49 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3efb465c..3a855be1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,21 +1,22 @@ ## Unreleased -Android never expires a request. It ignores the descriptor's `expiresAt` and -`configure()`'s `lifetimeMs`, and accepts a call with or without them. A -request waits and retries until the server accepts it, it settles as an -error (for example a 4xx that the retry rules do not cover, or a missing -file), or the app cancels it. Before, Android -settled an entry `error` with `errorKind: 'expired'` once `expiresAt` -passed, and gave each parked (`awaiting-auth`) entry a WorkManager wake at -its `expiresAt` when that was less than 24 hours away. Those wakes could -fill the app's 20 JobScheduler slots, so other uploads had to wait. A parked -entry now has no WorkManager row and waits for `updateHeaders()`. An app -that needs a limit calls `cancel(id)` itself. Entries an earlier version -queued keep going and are sent, also when their `expiresAt` has passed. An -`expired` outcome that an earlier version stored and the app has not yet -acknowledged is still delivered, unchanged. New entries store an -`expiresAt` that 11.3.0 never reaches, so an app that goes back to 11.3.0 -does not expire them. +Android never expires a request. Its native code ignores the descriptor's +`expiresAt` and `configure()`'s `lifetimeMs`. The native module accepts an +entry with or without `expiresAt`, also one in the past, and a +`configure()` call with or without `lifetimeMs`. A request waits and retries +until the server accepts it, it settles as an error (for example a 4xx that +the retry rules do not cover, or a missing file), or the app cancels it. +Before, Android settled an entry `error` with `errorKind: 'expired'` once +`expiresAt` passed, and gave each parked (`awaiting-auth`) entry a +WorkManager wake at its `expiresAt` when that was less than 24 hours away. +Those wakes could fill the app's 20 JobScheduler slots, so other uploads had +to wait. A parked entry now has no WorkManager row and waits for +`updateHeaders()`. An app that needs a limit calls `cancel(id)` itself. +Entries an earlier version queued keep going and are sent, also when their +`expiresAt` has passed. An `expired` outcome that an earlier version stored +and the app has not yet acknowledged is still delivered, unchanged. New and +re-queued entries store an `expiresAt` that 11.0.2 to 11.3.0 never reach, so +an app that goes back to one of those versions does not expire them. Android: a system stop now counts as a failed attempt only when it cut a request. Before, every stop at the job's time limit added one backoff step, diff --git a/README.md b/README.md index a47f2666..9dd25019 100644 --- a/README.md +++ b/README.md @@ -137,7 +137,7 @@ TypeScript does not flag a misspelled key on an inferred arrow return. | `file` | Whole file body. Copied. Moved when `parts` is set. | | `parts` | Chunked over `file`: `[{ url, headers?, range: { start, end } }]`, bytes, end exclusive, tiling the file from 0. | | `accept` | Non-2xx responses to treat as success: `[{ status, bodyIncludes? }]`. | -| `expiresAt` | Epoch ms. Default now + `lifetimeMs` (14 days). On iOS, past it: `error` with `errorKind: 'expired'`. Android ignores it and never expires a request. To put a limit on a request, call `cancel()`. | +| `expiresAt` | Epoch ms. Default now + `lifetimeMs` (14 days). Past it: `error` with `errorKind: 'expired'`. | | `retry` | Per-request override of the `configure()` retry defaults: `backoff`, `terminalHttp.exempt`, and `transient` rules. See "Reliable delivery". | | `wifiOnly` | `true` waits for Wi-Fi before each attempt; `false` never waits. Overrides `setWifiOnly()` for this entry. Omit it to follow `setWifiOnly()`, including later toggles. | | `priority` | `'high'` or `'normal'` (default). On Android at most 4 requests transmit at once, and one of those slots is kept for `'high'`. Normal requests can use only the other 3, so a high-priority request, such as a small JSON POST that creates a session, gets a slot without waiting behind a backlog of file parts. It can still wait when other high-priority requests hold every slot. iOS ignores it for now. | @@ -190,12 +190,11 @@ Nothing else deletes them. different `url` or `method` counts as a different body. `mutate()` with an id that exists: -- Same body: resume. New headers and `vars` replace the stored ones. On iOS - a new `expiresAt` does too; Android ignores `expiresAt`. +- Same body: resume. New headers, `expiresAt`, and `vars` replace the stored + ones. - Different body (`data`, `form`, `file`, or `parts`) and the entry is not running (queued, paused, awaiting-auth, or settled): the descriptor, staged - body, `vars`, and headers are replaced (on iOS `expiresAt` too) and the - entry reopens. + body, `vars`, headers, and `expiresAt` are replaced and the entry reopens. It settles once more. - Different body, entry running: `mutate()` rejects with `E_RUNNING`. - A cancelled entry whose outcome is not yet acknowledged: a fresh @@ -342,9 +341,8 @@ while the app was dead from being sent twice. never gives up on its own; the app decides a poison policy from that number. 3. **One outcome per settle cycle.** `pause()` produces none, for the whole - queue or for a set of keys. On iOS a paused entry past `expiresAt` - settles `error` with `errorKind: 'expired'` when it is resumed. On - Android it runs again. A same-id + queue or for a set of keys. A paused entry past `expiresAt` settles + `error` with `errorKind: 'expired'` when it is resumed. A same-id `mutate()` on a settled entry reopens it, and it settles once more. 4. **Never before `mutate()` resolves.** Delivery for an id waits for the caller's promise. While native has not answered `enqueue`, the id's @@ -377,13 +375,13 @@ Retry classes: | Attempt outcome | Action | | --- | --- | | 2xx, or an `accept` rule matches | settle `completed` | -| network failure, 5xx, 408, 429 | exponential backoff (base 1 s, max 2 h, jitter 0.2). On iOS until `expiresAt`. Android has no deadline: it retries until a later attempt settles the request (accepted, a terminal status, or a missing file) or the app calls `cancel()`. On Android a call whose every try failed while it connected waits at most 15 minutes | +| network failure, 5xx, 408, 429 | exponential backoff (base 1 s, max 2 h, jitter 0.2) until `expiresAt`. On Android a call whose every try failed while it connected waits at most 15 minutes | | 401, 403 | park as `awaiting-auth`; resume on `updateHeaders()` | | other 4xx matching a `retry.transient` rule (`status`, optional `bodyIncludes`), under the rule's `maxRetries` | as transient. The first matching rule in the list wins. `maxRetries: 3` retries three matching responses; the fourth settles. No `maxRetries` means no cap. See "Transient rule counts" below. A rule for 401, 403, 408 or 429 is rejected at the call | | other 4xx in `retry.terminalHttp.exempt` (default `[404]`), when no rule matched | as transient, with no cap | | other 4xx, or a rule past its `maxRetries` | settle `error` with `errorKind: 'http'`, response attached | | payload missing on disk | settle `error` with `errorKind: 'file'` | -| `expiresAt` passed (iOS only) | settle `error` with `errorKind: 'expired'`; bytes kept. Android never settles `expired`: it ignores `expiresAt` | +| `expiresAt` passed | settle `error` with `errorKind: 'expired'`; bytes kept | | response body over 1 MB with a `response` parser | `onError` with `errorKind: 'truncated'`; the entry is `completed` | **Transient rule counts.** The library counts the responses each rule @@ -478,7 +476,7 @@ reached its key before it; see rule 5 of "Reliable delivery". | Option | Notes | | --- | --- | | `definitions` | Optional. Every definition, as `define()` returned it. Listing a handle imports its module, so its `define()` runs before replay starts. In development, a later `define()` of a key that is not listed logs a warning. That key still receives its outcomes, and `mutate()` works for it. Throws when it is not an array of handles. | -| `lifetimeMs` | Default `expiresAt` distance. Default 14 days. Android ignores it. | +| `lifetimeMs` | Default `expiresAt` distance. Default 14 days. | | `maxVarsBytes` | Cap on the JSON length of `vars`. Default 1 MB. `mutate()` rejects above it. JS-side only. | | `retry` | `{ backoff?: { baseMs, maxMs, jitter }, terminalHttp?: { exempt }, transient?: Array<{ status, bodyIncludes?, maxRetries? }> }`. Each object is optional, but one you give must be complete. Defaults 1 s, 2 h, 0.2, `[404]`, `[]`. A descriptor's `retry` replaces each field it names. | | `headers` | `() => Record`, called at `mutate()`. The descriptor merges over it. | @@ -505,8 +503,8 @@ await Upload.resume({ keys: ['capture.upload'] }); // captures run Both states are persisted natively. Each entry that moves emits one `state` event (`paused`, then `queued`). No outcome is produced and the bytes are -kept. On iOS a paused entry past `expiresAt` settles `error` with -`errorKind: 'expired'` when it is resumed. On Android it runs again. +kept. A paused entry past `expiresAt` settles `error` with +`errorKind: 'expired'` when it is resumed. On Android, `resume()` also ends some retry backoff waits of the queued entries in its scope, and they run at once. `pause()` keeps an entry's diff --git a/android/src/main/java/ai/openspace/backgroundupload/EnqueueRules.kt b/android/src/main/java/ai/openspace/backgroundupload/EnqueueRules.kt index 2a449ec7..c02bdf81 100644 --- a/android/src/main/java/ai/openspace/backgroundupload/EnqueueRules.kt +++ b/android/src/main/java/ai/openspace/backgroundupload/EnqueueRules.kt @@ -154,6 +154,8 @@ object EnqueueRules { state = if (running) EntryState.RUNNING else initialState(paused), attempts = if (reopen) 0 else existing.attempts, bytesSent = parts?.let { ChunkedParts.acceptedBytes(it) } ?: if (running) existing.bytesSent else 0L, + // Not read here. Written so that a downgrade does not expire the entry. + expiresAt = QueueEntry.NO_DEADLINE, updatedAt = now, nextAttemptAt = null, backoffStreak = 0, diff --git a/android/src/main/java/ai/openspace/backgroundupload/QueueEntry.kt b/android/src/main/java/ai/openspace/backgroundupload/QueueEntry.kt index 87be476f..7de01e5f 100644 --- a/android/src/main/java/ai/openspace/backgroundupload/QueueEntry.kt +++ b/android/src/main/java/ai/openspace/backgroundupload/QueueEntry.kt @@ -113,11 +113,12 @@ data class QueueEntry( val bytesSent: Long, val totalBytes: Long, /** - * Not read. This version never expires an entry. 11.3.0 and earlier read + * Not read. This version never expires an entry. 11.0.2 to 11.3.0 read * this field as the time to settle the entry 'expired', and read a - * missing one as 0, which is already past. So a new entry stores - * [NO_DEADLINE], and an app that goes back to such a version does not - * expire it. An entry from an earlier version keeps the value it had. + * missing one as 0, which is already past. So a new or re-queued entry + * stores [NO_DEADLINE], and an app that goes back to such a version does + * not expire it. An entry from an earlier version that is not queued + * again keeps the value it had. */ val expiresAt: Long = NO_DEADLINE, val createdAt: Long, @@ -161,7 +162,7 @@ data class QueueEntry( val backoffPartStart: Long? = null, ) { companion object { - /** The [expiresAt] a new entry stores. 11.3.0 never reaches it, and does no sum with it that overflows. */ + /** The [expiresAt] a new or re-queued entry stores. 11.0.2 to 11.3.0 never reach it, and do no sum with it that overflows. */ const val NO_DEADLINE = Long.MAX_VALUE } diff --git a/android/src/test/java/ai/openspace/backgroundupload/EntryTransitionsTest.kt b/android/src/test/java/ai/openspace/backgroundupload/EntryTransitionsTest.kt index f1b30da2..0e98b2e2 100644 --- a/android/src/test/java/ai/openspace/backgroundupload/EntryTransitionsTest.kt +++ b/android/src/test/java/ai/openspace/backgroundupload/EntryTransitionsTest.kt @@ -207,7 +207,7 @@ class EnqueueRulesTest { assertTrue(next.descriptor!!.parts!![0].accepted) assertEquals(10, next.bytesSent) assertEquals(4, next.attempts) - assertEquals(stored.expiresAt, next.expiresAt) // not read, so not replaced + assertEquals(QueueEntry.NO_DEADLINE, next.expiresAt) // safe after a downgrade assertEquals("""{"n":2}""", next.varsJson) assertEquals(5, next.headerGeneration) assertNull(next.parkedGeneration) diff --git a/android/src/test/java/ai/openspace/backgroundupload/QueueControllerTest.kt b/android/src/test/java/ai/openspace/backgroundupload/QueueControllerTest.kt index d0849752..7067276b 100644 --- a/android/src/test/java/ai/openspace/backgroundupload/QueueControllerTest.kt +++ b/android/src/test/java/ai/openspace/backgroundupload/QueueControllerTest.kt @@ -90,7 +90,7 @@ class QueueControllerTest { } @Test - fun `same body on a queued entry resumes with the new headers and vars, and keeps the stored expiresAt`() { + fun `same body on a queued entry resumes with the new headers and vars, and stores the downgrade expiresAt`() { controller.enqueue(parsed()) assertEquals(QueueEntry.NO_DEADLINE, store.load("e1")!!.expiresAt) // An earlier version's entry, with its expiresAt long past. @@ -100,7 +100,7 @@ class QueueControllerTest { val e = store.load("e1")!! assertEquals("Bearer new", e.descriptor!!.headers["Authorization"]) assertEquals("""{"n":2}""", e.varsJson) - assertEquals(5, e.expiresAt) // not read, so not replaced + assertEquals(QueueEntry.NO_DEADLINE, e.expiresAt) // so 11.3.0 does not expire it after a downgrade assertEquals(EntryState.QUEUED, e.state) assertEquals(1, e.generation) assertEquals(bodyFile, e.body!!.fileName) diff --git a/src/NativeRNFileUploader.ts b/src/NativeRNFileUploader.ts index 2e375138..50948451 100644 --- a/src/NativeRNFileUploader.ts +++ b/src/NativeRNFileUploader.ts @@ -13,7 +13,6 @@ import { TurboModuleRegistry } from 'react-native'; // and 6 mirror them. export interface Spec extends TurboModule { // Queue-wide settings: { lifetimeMs, retry, ...androidNotificationConfig }. - // Android ignores lifetimeMs and expiresAt: it never expires a request. // Android persists the notification config, so a headless WorkManager // relaunch (no JS) can read it. Each call replaces the full configuration. configure(options: CodegenTypes.UnsafeObject): void; @@ -37,11 +36,11 @@ export interface Spec extends TurboModule { // // Same id, again. The body is data/form/file/parts, and a different url or // method is a different body. - // - Same body: resume. New headers, expiresAt (iOS) and vars replace the - // stored ones. + // - Same body: resume. New headers, expiresAt and vars replace the stored + // ones. // - Different body (data/form/file/parts) and the entry is NOT running // (queued, paused, awaiting-auth, or settled): replace the descriptor, - // staged body, vars, headers and expiresAt (iOS), and reopen the entry. It + // staged body, vars, headers and expiresAt, and reopen the entry. It // settles once more. // - Different body, entry running: reject E_RUNNING. // - Cancelled-but-unacked entry: a fresh generation. ack forgets the entry @@ -64,8 +63,8 @@ export interface Spec extends TurboModule { // Each live entry that becomes paused moves to 'paused', and each that // stops being paused moves back to 'queued', with one 'state' event per // entry. A running attempt stops. No outcome is produced and no attempt - // event is emitted. On iOS a paused entry past expiresAt settles - // error/expired when it stops being paused. + // event is emitted. A paused entry past expiresAt settles error/expired + // when it stops being paused. // // pause, resume, setWifiOnly, updateHeaders and configure apply the new // settings in memory, then save them best-effort. A failed settings save diff --git a/src/index.ts b/src/index.ts index f6812faa..a36bc010 100644 --- a/src/index.ts +++ b/src/index.ts @@ -256,8 +256,8 @@ export const createUploadClient = ({ /** * No scope pauses the whole queue. `{ keys }` pauses the entries of those * keys, queued and future. No outcome is produced; live rows show - * 'paused'. On iOS a paused entry past its expiresAt settles - * error/expired when it resumes. Android never expires a request. + * 'paused'. A paused entry past its expiresAt settles error/expired when + * it resumes. */ const pause = async (scope?: PauseScope): Promise => native.pause(toNativeScope('pause', scope)); diff --git a/src/types.ts b/src/types.ts index df98e4d8..4e583cfb 100644 --- a/src/types.ts +++ b/src/types.ts @@ -25,8 +25,7 @@ export type Method = 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'GET'; * Why a request failed. `http` means the server answered and the status was * not accepted. `network` is a transport failure. `file` means the payload is * missing on disk, so a retry can never succeed. `expired` means `expiresAt` - * passed: iOS only, or an outcome an earlier Android version stored. - * `truncated` means the response body hit the 1 MB cap, so the + * passed. `truncated` means the response body hit the 1 MB cap, so the * `response` parser could not run. `unknown` covers a parser throw. */ export type ErrorKind = @@ -127,7 +126,7 @@ export type RequestDescriptor = { /** Chunked over `file`. Each part sends its own byte range. */ parts?: Part[]; accept?: AcceptRule[]; - /** Epoch ms. Default now + `lifetimeMs`. Android ignores it. */ + /** Epoch ms. Default now + `lifetimeMs`. */ expiresAt?: number; retry?: Partial; /** @@ -396,7 +395,7 @@ export type ConfigureOptions = { * unlisted key still receives its outcomes. */ definitions?: readonly AnyDefined[]; - /** Default 14 days. Sets the default `expiresAt` of every entry. Android ignores it. */ + /** Default 14 days. Sets the default `expiresAt` of every entry. */ lifetimeMs?: number; /** * Default 1 MB. `mutate()` rejects `vars` whose JSON is longer. Only `vars`