gsadmin/garage
1
0
Fork 0
mirror of https://github.com/deuxfleurs-org/garage.git synced 2026-07-26 07:58:14 +00:00
Code Issues Packages Projects Releases Wiki Activity

K2V: update docs to add read monotonicity guarantees & flags

Browse Source
This commit is contained in:
Armaël Guéneau
2026-05-13 19:14:31 +02:00
committed by Alex
parent a159c1c483
commit 3c7990027a
1 changed files with 47 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/drafts/k2v-spec.md
+47
View File
@@ -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 /<bucket>/<partition key>?sort_key=<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 |