RECIPE

Conditional writes design

Conditional writes let Meridian clients commit a state change only when a precondition holds against the current backend version. They are the core primitive for safe concurrent updates, optimistic UI, and idempotent retries without external locks.

1. Pick a precondition strategy

Meridian supports three precondition modes on every write: If-Match for strict ETag equality, If-None-Match for create-only semantics, and If-Version for monotonic counter checks. Pick one per resource and document it next to the schema so readers know which header to send.

2. Echo the version on every read

Every GET response carries an ETag and a x-meridian-version header. Cache both on the client and replay them verbatim on the next mutating call. The server compares against the durable record and returns 412 Precondition Failed when stale.

3. Retry deterministically

On a 412, refetch, replay the user intent against the new state, and reissue with the fresh ETag. Cap retries at 3 with jittered backoff. The example below shows a minimal client loop that survives a hot row without coordination.

async function patchOrder(id, mutate) {
  for (let attempt = 0; attempt < 3; attempt++) {
    const cur = await fetch(`/v1/orders/${id}`);
    const etag = cur.headers.get('etag');
    const body = mutate(await cur.json());
    const res = await fetch(`/v1/orders/${id}`, {
      method: 'PATCH',
      headers: { 'If-Match': etag, 'content-type': 'application/json' },
      body: JSON.stringify(body),
    });
    if (res.status !== 412) return res;
  }
  throw new Error('conflict: max retries');
}