From a08dae2504b63b70963a1f525eb2056d5a2dd83b Mon Sep 17 00:00:00 2001 From: Oli Evans Date: Wed, 4 Oct 2023 14:04:45 +0100 Subject: [PATCH] feat: add `store/get` & `upload/get` capabilities These capabilities are intended for checking inclusion and allowing users to verify all the shards for an upload have been removed when removing an upload. see also: https://github.com/web3-storage/w3up/pull/942 License: MIT Signed-off-by: Oli Evans --- w3-store.md | 124 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 124 insertions(+) diff --git a/w3-store.md b/w3-store.md index 2a1bbf5..6c85db4 100644 --- a/w3-store.md +++ b/w3-store.md @@ -22,11 +22,13 @@ The protocol is modeled as a set of capabilities which can be fulfilled by a [pr - [`store/` namespace](#store-namespace) - [`store/*`](#store) - [`store/add`](#storeadd) + - [`store/get`](#storeget) - [`store/remove`](#storeremove) - [`store/list`](#storelist) - [`upload/` namespace](#upload-namespace) - [`upload/*`](#upload) - [`upload/add`](#uploadadd) + - [`upload/get`](#uploadget) - [`upload/remove`](#uploadremove) - [`upload/list`](#uploadlist) @@ -143,6 +145,66 @@ If `status == 'upload'`, the response will include additional fields containing The client should then make an HTTP `PUT` request to the `url` specified in the response, attaching all the included `headers`. The body of the request MUST be CAR data, whose size exactly equals the size specified in the `store/add` invocation's `size` caveat. Additionally, the CID of the uploaded CAR must match the invocation's `link` caveat. In other words, attempting to upload any data other than that authorized by the `store/add` invocation will fail. +### `store/get` + +> Get metadata about a CAR shard from a space + +The `store/get` capability can be invoked to get metadata about a CAR from a [space](#spaces). + +This may be used to check for inclusion, or to get the `size` and `origin` properties for a shard. + +#### Derivations + +`store/get` can be derived from a [`store/*`](#store) or [`*`][ucan-spec-top] capability with a matching `with` field. + +#### Caveats + +When invoking `store/get`, the `link` caveat must be set to the CID of the CAR file to get metadata for. + +If a delegation contains a `link` caveat, an invocation derived from it must have the same CAR CID in its `link` field. A delegation without a `link` caveat may be invoked with any `link` value. + +| `field` | `value` | `required?` | `context` | +| --------- | --------------------------------- | ----------- | --------------------------------------------- | +| `link` | CAR CID string, e.g. `bag...` | | The CID of the CAR to get metadata for | + +#### Invocation + +```js +{ + can: "store/get", + with: "did:key:abc...", + nb: { + link: "bag...", + } +} +``` + +#### Responses + +*Note*: This section is non-normative and subject to change, pending the [formalization of receipts and invocations][invocation-spec-pr]. + +Executing a `store/get` invocation with a service provider should return a response object. + +If a failure occurs, the response will have an `error` field with a value of `true`, and a `message` string field with details about the error. + +On success, the response object will have the following shape: + +```ts +interface StoreListItem { + /** CID of the stored CAR. */ + link: string + + /** Size in bytes of the stored CAR */ + size: number + + /** Link to a related CAR, used for sharded uploads */ + origin?: string, + + /** ISO-8601 timestamp when CAR was added to the space */ + insertedAt: string, +} +``` + ### `store/remove` > Remove a stored CAR from a space @@ -340,6 +402,68 @@ interface UploadAddResponse { } ``` +### `upload/get` + +> Get metadata about a upload from a space + +The `upload/get` capability can be invoked to get metadata about an upload from a [space](#spaces). + +This may be used to check for inclusion, or to get the set of CAR shards associated with a root cid. + +The `with` resource URI must be set to the DID of the space to get the upload metadata from. + +#### Derivations + +`upload/get` can be derived from an [`upload/*`](#upload) or [`*`][ucan-spec-top] capability with a matching `with` resource URI. + +#### Caveats + +The `root` caveat must contain the root CID of the data item to remove. + +| `field` | `value` | `required?` | `context` | +| --------- | --------------------------------- | ----------- | ------------------------------------------------------------- | +| `root` | data CID string, e.g. `bafy...` | | The root CID of the upload to get metadata for | + +#### Invocation + +To invoke `upload/get`, an agent prepares a UCAN with the following shape: + +```js +{ + can: "upload/get", + with: "did:key:abc...", + nb: { + root: "bafyabc..." + } +} +``` + +#### Responses + +*Note*: This section is non-normative and subject to change, pending the [formalization of receipts and invocations][invocation-spec-pr]. + +Executing an `upload/get` invocation with a service provider should return a response object. + +If a failure occurs, the response will have an `error` field with a value of `true`, and a `message` string field with details about the error. + +On success, the response object will have the following shape: + +```ts +interface UploadListItem { + /** Root CID of the uploaded data item. */ + root: string + + /** CIDs of CARs that contain the complete DAG for the uploaded data item. */ + shards: string[] + + /** ISO-8601 timestamp when the upload was added to the space. */ + insertedAt: string, + + /** ISO-8601 timestamp when the upload entry was last modified. */ + updatedAt: string, +} +``` + ### `upload/remove` > Remove an upload from a space.