RFC: persisted offline mutation queue (Qora 1.4)

[donfreddy]

Revision 4 (2026-11-12). The open question on failed predecessors is decided:

• A scope now means "these writes depend on each other". A permanent failure blocks its scope; other scopes keep draining.
• The failed list becomes a queue snapshot where each entry has a status: queued, sending, blocked, held or failed.
• retry puts the new attempt back at the head of its scope; discard blocks the dependents in turn so the user decides.

Revision 3 (2026-11-11). More feedback from Reddit. Changes:

• A mutation reports "queued" only once its storage write has completed; a failed write fails the mutation.
• Stored variables are immutable once a request has gone out. Retrying a failed mutation creates a new one.
• Conflicts (409) go through the failed list; a docs recipe covers base versions.
• Server-assigned IDs (placeholder IDs rewritten after the create succeeds) are out of scope for 1.4.
• New open question: what happens to the mutations behind a permanently failed one in the same scope.

Revision 2 (2026-11-10). Updated after feedback in this thread and on Reddit. Changes:

• Every queued call gets a stable mutationId, passed to the mutator for idempotency keys. The queue is at-least-once.
• A registered key's mutator runs in both lives, not only after a restart.
• Replay retries with backoff while online, then moves the mutation to a persisted failed list.
• For registered mutations, errors default to transient; an isPermanent predicate marks the ones to drop.
• Optional scope: mutations in the same scope replay in order, different scopes do not block each other.
• One storage entry per queued mutation, written before the request and deleted after success.

Context

Qora 1.3 queues writes made while offline (MutationOptions(offlineQueue: true)) and replays them in order on reconnect. The queue lives in memory: if the app is killed before the network returns, the writes are lost. The cache itself already survives restarts through PersistQoraClient.

1.4 makes the queue survive restarts.

The hard part

A queued mutation is a closure today: the mutator and callbacks of the widget that called it. A closure cannot be written to disk. After a restart, Qora needs another way to know what to call. The queue has to be data, not functions.

Design

1. Mutations registered by key

Mutations that must survive a restart are registered once, at startup, before hydrate():

final client = PersistQoraClient(storage: storage)
  ..registerMutation<Todo, NewTodo>(
    'todos.create',
    mutator: (input, meta) => api.createTodo(input, idempotencyKey: meta.mutationId),
    variables: QoraSerializer<NewTodo>(
      toJson: (v) => v.toJson(),
      fromJson: NewTodo.fromJson,
    ),
    scope: (input) => 'todo:${input.id}',      // optional, see 4
    isPermanent: (error) => error is ApiError && error.isClientError, // optional, see 3
    invalidates: [['todos']],
  );

await client.hydrate(); // restores the cache, then the queue

A call site opts in with the same key and passes no mutator:

QoraMutationBuilder<Todo, NewTodo, List<Todo>?>(
  options: MutationOptions(
    mutationKey: 'todos.create',
    offlineQueue: true,
    onMutate: ...,  // optimistic update, as today
    onError: ...,   // rollback, as today
  ),
  builder: ...,
)

The registered mutator runs in both lives, in the same session and after a restart. One mutator per key means:

• the first attempt and every replay send the same mutationId, so the server can deduplicate them;
• the call site and the registry cannot drift apart;
• everything the mutator needs must be in the variables. Persistence imposes this anyway; enforcing it from the first call surfaces the mistake in development instead of after a restart in production.

meta carries mutationId (generated when the call is queued, stable across replays) and attempt.

A call without mutationKey keeps working exactly as in 1.3: its own mutator, in memory only.

2. Two lives for a queued call

	Same session	After a restart
Mutator	The registered one	The registered one
onMutate context (snapshot)	Available, rollback as today	Gone
Callbacks	The call site's onSuccess / onError / onSettled	Registered invalidates / invalidatesTags only
Failure visible through	onError, the builder's state, the queue snapshot	The queue snapshot, mutationEvents

After a restart no snapshot is needed: optimistic setQueryData writes are not persisted, so the restored cache only holds server data. Invalidating after replay is enough to reconcile.

3. Delivery and replay failures

Durable before queued. A queued mutation reports its queued state only after its storage write has completed. If the write fails, the mutation fails immediately with that error instead of appearing saved. An app must never tell its user "saved" for a write that only exists in memory.

Immutable once sent. After the first request has gone out, the stored variables of a mutation never change, even if the response was lost. Only attempts and lastError are updated. A replay therefore always sends the same payload under the same mutationId, which is what server-side deduplication expects.

At-least-once. A mutation is written to storage before its request and deleted after a successful response. If the app dies after the server applied the write but before the response arrived, the mutation is replayed on the next start. Exactly-once requires the server to deduplicate on mutationId (for example as an Idempotency-Key header, or a client-generated ID with create-as-upsert). The docs will say this plainly.

Permanent failure (the server rejected the write). onError runs if the call site is still alive. What happens next depends on the scope (section 4):

• In a scope, the mutation stays at the head of its scope with status blocked and the error. The mutations behind it in that scope get status held and are not sent. Other scopes and the global lane keep draining.
• Without a scope, no dependency was declared: the mutation gets status failed, leaves the replay order, and the global lane continues, as in 1.3. One bad unscoped write never blocks the rest.

Holding a scope matters beyond tidiness. With client-generated IDs and create-as-upsert, an update sent after a rejected create could create the record with partial data that never passed the create's validation.

Transient failure (timeout, connection reset, 503): the mutation and the ones behind it in its scope stay queued. Replay retries with exponential backoff while the device is online, not only on the next reconnect. After maxAttempts (default 5), the mutation is treated as permanent.

Classification. Qora does not see HTTP status codes, so the app decides:

• isPermanent on registerMutation, falling back to a default in QoraClientConfig;
• without a predicate, errors of registered mutations are transient. Dropping a write on a network blip is worse than retrying a rejected one a few times. The cost: without a predicate, a validation error blocks its scope for the backoff duration (about 30 s with the defaults) before it becomes blocked (in a scope) or failed (without one).

Unregistered (in-memory) mutations keep their 1.3 behaviour. OfflineMutationQueue.stopOnFirstError, documented but without effect, is deprecated.

Queue snapshot. The queue is readable at any time, including after a restart, as a list of entries with their key, scope, variables, attempts, last error and status:

Status	Meaning
queued	Waiting for its turn or for the network.
sending	Request in flight.
blocked	Failed for good at the head of its scope; waits for a decision.
held	Behind a blocked entry in the same scope; not sent.
failed	Failed for good without a scope; out of the replay order, kept until dismissed.

Statuses are persisted. Replay can run during hydrate(), before any widget listens to mutationEvents, so a stream alone would lose those failures. The same snapshot feeds the sync status API (useOfflineQueue).

Decisions on a blocked or failed entry:

• retry(mutationId, variables: ...) enqueues a new mutation (new mutationId, optionally new variables), consistent with "immutable once sent". For a blocked entry, the new mutation takes its place at the head of the scope, and the held entries drain in order after it succeeds.
• discard(mutationId) removes the entry. In a scope, the entries it was holding become blocked in turn: they may target a record that will never exist, so the user sees what would be lost and decides for each. discardScope(scope) drops a whole chain at once.

maxAttempts exhausted on a transient error leads to the same statuses as a permanent failure.

Conflicts. A 409 is a permanent failure like any other: the mutation becomes blocked or failed with its error. The app recognises the conflict from the error, lets the user choose, and retries with new variables. Optimistic concurrency (a base version the server checks) stays in the app's variables; Qora does not need to know about it. The docs will include a recipe.

4. Ordering and scopes

Without a scope, all queued mutations share one global lane and replay in order, as in 1.3.

With scope, mutations sharing a scope replay in order, and a mutation stuck in one scope does not block the others. Lanes replay concurrently, bounded by the existing ReconnectStrategy concurrency.

A scope declares a dependency chain: a write in a scope may rely on every earlier write in the same scope. That is why a permanent failure holds the rest of the scope (section 3) instead of letting it run.

Qora cannot see which record a mutation targets, so the scope comes from the app. Pick the narrowest scope that covers the dependencies, usually the record's ID, or the parent's ID for children: a task created inside a project created offline must use the project's scope, or it can be sent before the project exists. A scope wider than needed holds more writes than necessary when something fails.

This is the model TanStack Query uses (scope.id on mutations).

5. Storage

The queue uses the same StorageAdapter as the cache. Each queued mutation is its own entry, under a key with a reserved prefix and a sequence number, so entries cannot collide with query keys (JSON arrays) or app keys, and order survives a restart. Rewriting one entry never rewrites the whole queue.

Stored record: {version, mutationId, key, scope, variables, enqueuedAt, attempts, lastError, status}. version allows the format to evolve.

Files do not belong in the queue. Key-value adapters such as SharedPreferences store strings and are not meant for binary payloads. For a photo taken offline, the app writes the bytes to a durable file first and queues its path in the variables.

6. Logout

A queued write belongs to the user who made it. Replaying user A's writes after user B signs in would be a data leak. clearStorage() also clears the persisted queue, whatever the status of its entries, and clearPendingMutations() covers the in-memory part. Since 1.3.1, hydrate() and clearStorage() only touch keys Qora wrote, so a shared Hive box or SharedPreferences instance is safe.

Out of scope for 1.4

• Collapsing a queued update into a pending create. Qora cannot merge opaque variables; if needed, it could come later as an optional per-mutation hook.
• Server-assigned IDs. When the backend assigns the ID, an offline update has to target a placeholder (local:<mutationId>) that is swapped for the real ID once the create succeeds. That needs the create's response persisted (a result serializer on registerMutation), an explicit link between the two mutations, and a hook to rewrite the dependent variables. The versioned storage format leaves room for it later. In 1.4 the supported path is client-generated IDs, with scopes for ordering.
• Code generation of any kind.

Answered questions

1. Identity: string keys registered at startup.
2. Failure policy: transient by default for registered mutations, isPermanent per mutation with a client-level default.
3. Dependent writes: client-generated IDs, plus scopes for ordering.
4. After a restart: rollback by invalidation, failures in the persisted queue snapshot.
5. Storage: same adapter as the cache, one entry per mutation.

Decided after the first round

• A permanently failed predecessor holds its scope; see sections 3 and 4.

Still open

• Default backoff (initial delay, cap, jitter) and maxAttempts.

[donfreddy]

Hi @RandalSchwartz, in June you reported two Qora bugs (#1, #2) with root-cause analyses precise enough that both were fixed in 1.1.0. Thanks again. For 1.4 I'm designing a persisted offline mutation queue and wrote the trade-offs up here. Given how closely you read the internals, I'd value your take on question 1 (string keys vs typed handles) or question 3 (dependent offline writes) if you have ten minutes. No pressure either way.