From 57eabe787948ad6c23eae7761d02545c675bf7ff Mon Sep 17 00:00:00 2001 From: Alex Auvolat Date: Tue, 10 Jan 2023 14:56:57 +0100 Subject: [PATCH] Add proposal spec for PollRange API endpoint --- doc/drafts/k2v-spec.md | 57 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) diff --git a/doc/drafts/k2v-spec.md b/doc/drafts/k2v-spec.md index 9d41b2c0..a335aee3 100644 --- a/doc/drafts/k2v-spec.md +++ b/doc/drafts/k2v-spec.md @@ -706,6 +706,63 @@ HTTP/1.1 200 OK ] ``` +**PollRange: `POST //?poll_range`**, or alternatively
+**PollRange: `SEARCH //?poll_range`** + +Polls a range of items for changes. + +The query body is a JSON object consisting of the following fields: + +| name | default value | meaning | +|-----------------|---------------|----------------------------------------------------------------------------------------| +| `prefix` | `null` | Restrict items to poll to those whose sort keys start with this prefix | +| `start` | `null` | The sort key of the first item to poll | +| `end` | `null` | The sort key of the last item to poll (excluded) | +| `timeout` | 300 | The timeout before 304 NOT MODIFIED is returned if no value in the range is updated | +| `seenMarker` | `null` | An opaque string returned by a previous PollRange call, that represents items already seen | + +The timeout can be set to any number of seconds, with a maximum of 600 seconds (10 minutes). + +The response is either: + +- A HTTP 304 NOT MODIFIED response with an empty body, if the timeout expired and no changes occurred + +- A HTTP 200 response, indicating that some changes have occurred since the last PollRange call, in which case a JSON object is returned in the body with the following fields: + +| name | meaning | +|-----------------|----------------------------------------------------------------------------------------| +| `seenMarker` | An opaque string that represents items already seen for future PollRange calls | +| `items` | The list of items that have changed since last PollRange call, in the same format as ReadBatch | + + +Example query: + +```json +SEARCH /my_bucket?poll_range HTTP/1.1 + +{ + "prefix": "0391.", + "start": "0391.000001973107", + "seenMarker": "opaquestring123", +} +``` + + +Example response: + +```json +HTTP/1.1 200 OK +Content-Type: application/json + +{ + "seenMarker": "opaquestring456", + "items": [ + { sk: "0391.000001973221", ct: "opaquetoken123", v: ["b64cryptoblob123", "b64cryptoblob'123"] }, + { sk: "0391.000001974191", ct: "opaquetoken456", v: ["b64cryptoblob456", "b64cryptoblob'456"] }, + ] +} +``` + ## Internals: causality tokens