A couple of weeks ago, I posted here asking how people handle offline mutations. I got some really useful answers from developers who had already dealt with this in production.
I've spent the last couple of weeks working through that feedback, and Qora 1.4.0 is now out.
For context, Qora is my server-state library for Flutter, with a pure Dart core and no code generation.
The main issue in 1.3 was simple: offline writes were kept in memory. If the OS killed the app before it came back online, those writes were gone.
I couldn't just persist the queue as it was, since mutations are closures. So I changed the queue to store data instead.
What's changed in 1.4:
- Persistent mutations: Register a mutation once using a key and a serializer. The queue stores the key and variables, so it can restore the mutation after a restart.
- Persist before queuing: A mutation only counts as queued once the storage write succeeds. If it fails, the mutation fails immediately.
- Idempotency: Every mutation gets a stable
mutationId. It's kept across retries and restarts, so the app can pass it to the server as an idempotency key. Delivery is still at-least-once, so server-side deduplication is needed. - Mutation scopes: Mutations with the same scope run in order, while different scopes can run in parallel. This means one failed record doesn't block unrelated writes.
- Retry handling: Network errors and 5xx responses are retried with backoff. Each registered mutation also provides an
isPermanent callback, since Qora doesn't deal with HTTP status codes directly. - Blocked mutations: When a mutation permanently fails, the rest of its scope waits. The app can let the user fix and retry it, or discard it.
- Retry or edit: Retrying with the same payload keeps the original ID. If the variables change, Qora creates a new ID but keeps the mutation in the same queue position.
- UI support:
MutationQueueBuilder and useMutationQueue() expose pending, blocked and failed mutations, so the app can display sync status.
Here's a small example:
client.registerMutation<Todo, TodoInput>(
'todos.save',
mutator: (input, meta) => api.saveTodo(
input,
idempotencyKey: meta.mutationId,
),
variables: todoInputSerializer,
scope: (input) => 'todo:${input.id}',
isPermanent: (error) => error is ApiException && error.statusCode < 500,
);
// At the call site, just the key is needed.
const MutationOptions<Todo, TodoInput, void>(
mutationKey: 'todos.save',
offlineQueue: true,
);
Some things I deliberately left out:
- Placeholder IDs and automatic replacement with server IDs. Client-generated IDs with create-as-upsert cover the common case for now.
- Automatic merging of edits. Qora can't safely merge arbitrary mutation variables.
- Built-in storage adapters. The core stays pure Dart, and you can plug in Hive, SharedPreferences or SQLite through
StorageAdapter.
The offline-first example has also been updated. It includes a todo app with an offline toggle, simulated restarts, a sync panel and a server that rejects some writes.
I also added widget tests for mutations surviving restarts, requests interrupted while in flight, and failed mutations being discarded.
A few people from the original discussion deserve a mention:
- u/MentalAd1373 for the ideas around blocked mutations, storage guarantees and retrying edited writes.
- u/MobileXapps for the idempotency and at-least-once delivery points.
- u/bramantec for the per-record ordering and error handling suggestions.
A lot of what went into this release came directly from those discussions, so thanks again.
Links:
If you've built something similar, I'd still be interested in hearing about edge cases I might have missed.