From 3c7990027a86f2c4abc181bbee3fee61f3f1199d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Arma=C3=ABl=20Gu=C3=A9neau?= Date: Wed, 13 May 2026 19:14:31 +0200 Subject: [PATCH] K2V: update docs to add read monotonicity guarantees & flags --- doc/drafts/k2v-spec.md | 47 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/doc/drafts/k2v-spec.md b/doc/drafts/k2v-spec.md index b16628e2..32be024d 100644 --- a/doc/drafts/k2v-spec.md +++ b/doc/drafts/k2v-spec.md @@ -166,6 +166,25 @@ that map to zeroes. Note that we need to filter out values from nodes that are no longer part of the cluster layout, as when nodes are removed they won't necessarily have had the time to set their counters to zero. +### Consistency guarantees + +K2V provides the following consistency guarantees: + +**Read after Write**. After a write has been acknowledged (the request returned +successfully), a subsequent read is guaranteed to contain the value that was +written. + +**Monotonic Reads**. Two sequencial reads will return values in an order that is +consistent with the order in which they are written (e.g. by concurrent writes). +For example, consider a scenario where a value is set initially set to 0 and a +request writing 1 is performed. Doing two subsequent reads concurrently with the +write is guaranteed to return either `0`, `0` or `0`,`1` or `1`,`1`, but not +`1`,`0`. + +It is also possible to perform non-monotonic reads (allowing this last +behavior), which are slightly faster than monotonic reads. This is done by +passing a dedicated flag to read operations (see the endpoints documentation). + ## Important details **THIS SECTION CONTAINS A FEW WARNINGS ON THE K2V API WHICH ARE IMPORTANT @@ -210,6 +229,12 @@ Query parameters: |------------|---------------|----------------------------------| | `sort_key` | **mandatory** | The sort key of the item to read | +Headers: + +| name | default value | meaning | +|-------------------------------|---------------|------------------------------------------| +| `X-Garage-Non-Monotonic-Read` | `false` | Whether to allow for non-monotonic reads | + Returns the item with specified partition key and sort key. Values can be returned in either of two ways: @@ -325,6 +350,12 @@ Query parameters: The timeout can be set to any number of seconds, with a maximum of 600 seconds (10 minutes). +Headers: + +| name | default value | meaning | +|-------------------------------|---------------|------------------------------------------| +| `X-Garage-Non-Monotonic-Read` | `false` | Whether to allow for non-monotonic reads | + **InsertItem: `PUT //?sort_key=`** @@ -521,6 +552,14 @@ HTTP/1.1 204 NO CONTENT Batch read of triplets in a bucket. +Headers: + +| name | default value | meaning | +|-------------------------------|---------------|------------------------------------------| +| `X-Garage-Non-Monotonic-Read` | `false` | Whether to allow for non-monotonic reads | + +Body: + The request body is a JSON list of searches, that each specify a range of items to get (to get single items, set `singleItem` to `true`). A search is a JSON struct with the following fields: @@ -711,6 +750,14 @@ HTTP/1.1 200 OK Polls a range of items for changes. +Headers: + +| name | default value | meaning | +|-------------------------------|---------------|------------------------------------------| +| `X-Garage-Non-Monotonic-Read` | `false` | Whether to allow for non-monotonic reads | + +Body: + The query body is a JSON object consisting of the following fields: | name | default value | meaning |