From 57eabe787948ad6c23eae7761d02545c675bf7ff Mon Sep 17 00:00:00 2001
From: Alex Auvolat <alex@adnab.me>
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 /<bucket>/<partition key>?poll_range`**, or alternatively<br/>
+**PollRange: `SEARCH /<bucket>/<partition key>?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