From d692b1877a18e83e23cfbcad1b5e9f91f561e7c1 Mon Sep 17 00:00:00 2001 From: Lars Wirzenius Date: Mon, 21 Mar 2022 17:27:17 +0200 Subject: docs: update obnam.md about client trust root chunk Sponsored-by: author --- obnam.md | 43 ++++++++++++++++++------------------------- 1 file changed, 18 insertions(+), 25 deletions(-) diff --git a/obnam.md b/obnam.md index 68aa01e..a06717a 100644 --- a/obnam.md +++ b/obnam.md @@ -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 clients. * **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` — 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 label -* `generation` — 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` — 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/` — retrieve a chunk (and its metadata) from the server, given a chunk identifier * `GET /chunks?label=xyzzy` — find chunks on the server whose - metadata indicates their contents has a given SHA256 checksum -* `GET /chunks?generation=true` — find generation chunks -* `GET /chunks?data=True` — 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: ~~~json { "fe20734b-edb3-432f-83c3-d35fe15969dd": { - "label": "09ca7e4eaa6e8ae9c7d261167129184883644d07dfba7cbfbc4c8a2e08360d5b", - "generation": null, - "ended: null, + "label": "09ca7e4eaa6e8ae9c7d261167129184883644d07dfba7cbfbc4c8a2e08360d5b" } } ~~~ -- cgit v1.2.1