feat: add `store/get` & `upload/get` capabilities #82

olizilla · 2023-10-04T13:12:19Z

These capabilities are intended for checking inclusion, or getting the additional properties we store. This will allow clients to verify all the shards for an upload have been removed before removing an upload.

`store/get` delegation

{
  can: "store/get",
  with: "did:key:abc...",
  nb: {
    link: "bag...",
  }
}

Response

Error if link shard cid is not in space or...

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,
}

`upload/get` delegation

{
  can: "upload/get",
  with: "did:key:abc...",
  nb: {
    root: "bafyabc..."
  }
}

Response

Error if root is not in uploads for space or...

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,
}

see also: storacha/w3up#942

License: MIT

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: storacha/w3up#942 License: MIT Signed-off-by: Oli Evans <[email protected]>

License: MIT Signed-off-by: Oli Evans <[email protected]>

alanshaw

Looks fine but we should update all of these to not use strings for CIDs....

travis

could update these post-merge of course, but I do think these changes need doing

travis · 2023-10-04T18:04:04Z

w3-store.md

+
+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.


maybe I'm misunderstanding this, but won't the error response look like:

{ error: { name: "ErrorName", message: "An error message" } }

?

ah yes you right. I was blending this in with the rest of this spec, but things have changed!

I can't find a place in our other specs where we document the expected output shapes which seems odd too.

yeaaaa I agree, I think it's a hole in our specs that we haven't documented the input/return types across the board, maybe even a DX issue worth fixing asap?

travis · 2023-10-04T18:05:43Z

w3-store.md

+
+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:


and similarly, I think the response will look like:

{ ok: {link: "bagy...", size: 42, insertedAt: "2023-01-01T01:01:01" } }

travis · 2023-10-04T18:06:13Z

w3-store.md

+
+#### Caveats
+
+The `root` caveat must contain the root CID of the data item to remove.


s/remove/return/

travis · 2023-10-04T18:06:37Z

w3-store.md

+
+| `field`   | `value`                           | `required?` | `context`                                                     |
+| --------- | --------------------------------- | ----------- | ------------------------------------------------------------- |
+| `root`    | data CID string, e.g. `bafy...`   |             | The root CID of the upload to get metadata for                |


required should be true I think

yep, but i think we need to make it clearer that these tables are referring to "when used as an invocation", as the root is not required in the schema, as folks should be allowed to make a delegation that grants you upload/get on any root. same for store.get. My gut feel is we should make the tables present the ucanto schema rather than the "when used as invocation" form.

(yep, as i deliberately differed from the other items in this spec where they have marked an optional field as required)

ahhhh got it, I agree re: presenting ucanto schema!!

travis · 2023-10-04T18:06:59Z

w3-store.md

+
+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.


ditto re: response formats in this section

Capability definitions to allow clients to check for inclusion of cid in store shards or upload roots. Also allows client to fetch the additional properties we store. This will, for example, let a client verify all shards for an upload have been removed before removing an upload. _I'm aiming to simplify things with this PR so that we return insertedAt info on the Upload/Store ListItem types, and return the same object shape for a single object get. If this is pleasing, then I will continue in this direction and make Remove also return the same shape if it removes something_ TODO: - [x] spec update storacha/specs#82 - [x] tests License: MIT --------- Signed-off-by: Oli Evans <[email protected]> Co-authored-by: Alan Shaw <[email protected]>

w3-store.md

olizilla · 2023-12-18T16:23:19Z

implemented in storacha/w3up#1178

Adds the `blob/get` capability spec which is analogous to #82 --------- Co-authored-by: Vasco Santos <[email protected]> Co-authored-by: Alan Shaw <[email protected]>

olizilla added 2 commits October 4, 2023 14:04

chore: capitalise CID

59f5eb6

License: MIT Signed-off-by: Oli Evans <[email protected]>

olizilla requested review from travis, Gozala, alanshaw and vasco-santos October 4, 2023 13:16

olizilla mentioned this pull request Oct 4, 2023

feat: add store/get and upload/get capabilities storacha/w3up#942

Merged

2 tasks

alanshaw approved these changes Oct 4, 2023

View reviewed changes

travis requested changes Oct 4, 2023

View reviewed changes

olizilla commented Dec 18, 2023

View reviewed changes

w3-store.md Outdated Show resolved Hide resolved

docs: Update w3-store.md

69bcfac

olizilla merged commit 32806f9 into main Dec 18, 2023
2 checks passed

olizilla deleted the get-caps branch December 18, 2023 16:22

joaosa mentioned this pull request May 30, 2024

feat: add blob/get #126

Merged

joaosa added a commit that referenced this pull request Jun 5, 2024

feat: add blob/get (#126)

ff36626

Adds the `blob/get` capability spec which is analogous to #82 --------- Co-authored-by: Vasco Santos <[email protected]> Co-authored-by: Alan Shaw <[email protected]>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add `store/get` & `upload/get` capabilities #82

feat: add `store/get` & `upload/get` capabilities #82

olizilla commented Oct 4, 2023 •

edited

Loading

alanshaw left a comment

travis left a comment

travis Oct 4, 2023

olizilla Oct 5, 2023

travis Oct 6, 2023

travis Oct 4, 2023

travis Oct 4, 2023

travis Oct 4, 2023

olizilla Oct 5, 2023

olizilla Oct 5, 2023

travis Oct 6, 2023

travis Oct 4, 2023

olizilla commented Dec 18, 2023


		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.


		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:


		#### Caveats

		The `root` caveat must contain the root CID of the data item to remove.


		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.

feat: add store/get & upload/get capabilities #82

feat: add store/get & upload/get capabilities #82

Conversation

olizilla commented Oct 4, 2023 • edited Loading

store/get delegation

Response

upload/get delegation

Response

alanshaw left a comment

Choose a reason for hiding this comment

travis left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

olizilla commented Dec 18, 2023

feat: add `store/get` & `upload/get` capabilities #82

feat: add `store/get` & `upload/get` capabilities #82

olizilla commented Oct 4, 2023 •

edited

Loading

`store/get` delegation

`upload/get` delegation