diff options
authorLars Wirzenius <>2022-03-21 17:27:17 +0200
committerLars Wirzenius <>2022-03-22 19:18:35 +0200
commitd692b1877a18e83e23cfbcad1b5e9f91f561e7c1 (patch)
parent7e49a52cee01a26b91253abb38dcc40b5ae727e2 (diff)
docs: update about client trust root chunk
Sponsored-by: author
1 files changed, 18 insertions, 25 deletions
diff --git a/ b/
index 68aa01e..a06717a 100644
--- a/
+++ b/
@@ -250,7 +250,7 @@ requirements and notes how they affect the architecture.
* **Large numbers of live data files:** Storing and accessing lists of
and meta data about files needs to done using data structures that
are efficient for that.
-* **Live data in the terabyte range:**
+* **Live data in the terabyte range:** FIXME
* **Many clients:** The architecture should enable flexibly managing
* **Shared repository:** The server component needs identify and
@@ -895,7 +895,7 @@ clients.
Chunks consist of arbitrary binary data, a small amount of metadata,
and an identifier chosen by the server. The chunk metadata is a JSON
-object, consisting of the following fields:
+object, consisting of the following field (there used to be more):
* `label` &mdash; the SHA256 checksum of the chunk contents as
determined by the client
@@ -904,21 +904,22 @@ object, consisting of the following fields:
- note that the server doesn't verify this in any way, to pave way
for future client-side encryption of the chunk data, including the
-* `generation` &mdash; set to `true` if the chunk represents a
- generation
- - may also be set to `false` or `null` or be missing entirely
- - the server allows for listing chunks where this field is set to
- `true`
-* `ended` &mdash; the timestamp of when the backup generation ended
- - note that the server doesn't process this in any way, the contents
- is entirely up to the client
- - may be set to the empty string, `null`, or be missing entirely
- - this can't be used in searches
+ - there is no requirement that only one chunk has any given label
When creating or retrieving a chunk, its metadata is carried in a
`Chunk-Meta` header as a JSON object, serialized into a textual form
that can be put into HTTP headers.
+There are several kinds of chunk. The kind only matters to the client,
+not to the server.
+* Data chunk: File content data, from live data files, or from an
+ SQLite database file listing all files in a backup.
+* Generation chunk: A list of chunks for the SQLite file for a
+ generation.
+* Client trust: A list of ids of generation chunks, plus other data
+ that are per-client, not per-backup.
## Server
@@ -929,12 +930,7 @@ The server has the following API for managing chunks:
* `GET /chunks/<ID>` &mdash; retrieve a chunk (and its metadata) from
the server, given a chunk identifier
* `GET /chunks?label=xyzzy` &mdash; find chunks on the server whose
- metadata indicates their contents has a given SHA256 checksum
-* `GET /chunks?generation=true` &mdash; find generation chunks
-* `GET /chunks?data=True` &mdash; find chunks with file data
- - this is meant for testing only
- - it excludes generation chunks, and chunks used to store the
- generation's SQLite file
+ metadata has a specific value for a label.
HTTP status codes are used to indicate if a request succeeded or not,
using the customary meanings.
@@ -958,17 +954,14 @@ and should treat it as an opaque value.
When a chunk is retrieved, the chunk metadata is returned in the
`Chunk-Meta` header, and the contents in the response body.
-It is not possible to update a chunk or its metadata.
-When searching for chunks, any matching chunk's identifiers and
-metadata are returned in a JSON object:
+It is not possible to update a chunk or its metadata. It's not
+possible to remove a chunk. When searching for chunks, any matching
+chunk's identifiers and metadata are returned in a JSON object:
"fe20734b-edb3-432f-83c3-d35fe15969dd": {
- "label": "09ca7e4eaa6e8ae9c7d261167129184883644d07dfba7cbfbc4c8a2e08360d5b",
- "generation": null,
- "ended: null,
+ "label": "09ca7e4eaa6e8ae9c7d261167129184883644d07dfba7cbfbc4c8a2e08360d5b"