Add documentation about ZedTokens/Zookies and consistency #174

josephschorr · 2021-10-05T20:15:43Z

Fixes #13

jzelinskie · 2021-10-05T20:22:48Z

docs/consistency-options.md

+Consistency is provided via the [Consistency block] on API calls.
+
+[V1 API]: https://buf.build/authzed/api/tree/main/authzed/api/v1
+[Consistency block]: https://buf.build/authzed/api/file/main/authzed/api/v1/permission_service.proto#L50


That URL is guaranteed to change, you probably meant this one: https://buf.build/authzed/api/docs/main/authzed.api.v1#authzed.api.v1.Consistency

docs/consistency-options.md

jzelinskie · 2021-10-05T20:37:15Z

docs/zedtokens-and-zookies.md

@@ -0,0 +1,187 @@
+# ZedTokens and Zookies


Rather than the focus of this being documenting zed tokens / zookies, could we make this focused on "consistency and availability of spicedb" in general? Then we can answer questions like

where does SpiceDB fit into the CAP theorem?

what knobs for consistency are available to application developers?

what happens if SpiceDB is unavailable?

and also cover zed tokens/zookies in a way that people will discover them when they aren't familiar with the terms or how they relate to the system in general

IMO most people will not care initially about reading about the CAP theorem, but rather how to effectively use the system. The consistency knobs are described in the other consistency document.

If we want a section on CAP guarantees, we can add that, but it is likely too technical for people trying to integrate effectively initially.

jzelinskie · 2021-10-12T18:06:12Z

I think this needs a rebase now that we have CI linting markdown.

josephschorr · 2021-10-12T18:10:56Z

Rebased. Will fix lint issues as they appear.

josephschorr · 2021-10-12T18:22:04Z

Updated

zarakay · 2021-10-13T01:51:12Z

Was reading this PR to understand Zookies, found it very useful. I notice that the recommendations around storing/using zookies only covered the Read/Write endpoints.

Was curious which Zookie do you use for Expand/Lookup endpoints? eg. if you have a relationship between a User and their Notes, and you are using Expand, since you store a zookie against each Note resource, do you just pick one? Or always using the strongest consistency? Did I miss something?

josephschorr · 2021-10-13T14:44:02Z

Was reading this PR to understand Zookies, found it very useful. I notice that the recommendations around storing/using zookies only covered the Read/Write endpoints.

Was curious which Zookie do you use for Expand/Lookup endpoints? eg. if you have a relationship between a User and their Notes, and you are using Expand, since you store a zookie against each Note resource, do you just pick one? Or always using the strongest consistency? Did I miss something?

Generally, you always use the ZedToken for the resource on which you're performing the call. So if you previously issued a fully_consistent Check for that resource (and stored a ZedToken), you'd use the same ZedToken in Check, as well as Expand.

For Lookup or Read, it is less defined: if you are using Lookup or Read to, say, list things that a user can view, and you're concerned that a user might temporarily be able to see a change in this list (say the title of a resource was changed to have sensitive information), then the recommendation would be to store the result of the fully_consistent Check not just for the resource, but for its container as well (folder, namespace, organization, etc), and then use that ZedToken for Lookup or Read too. However, this is only necessary if sensitive information can somehow leak through your code that uses one of these calls. If it is cannot, just use the default consistency for the calls, and occasionally you'll get cached (but safe) information.

jzelinskie · 2021-10-13T21:36:57Z

docs/consistency-options.md

@@ -0,0 +1,70 @@
+# Consistency Options
+
+SpiceDB's [V1 API] provides the ability to specify the *consistency* level at which API calls are made.


We use lowercase v everywhere else. This whole document needs to be updated for that.

jzelinskie · 2021-10-13T21:37:25Z

docs/consistency-options.md

+
+SpiceDB's [V1 API] provides the ability to specify the *consistency* level at which API calls are made.
+
+Consistency is provided via the [Consistency block] on API calls.


s/block/message

... on {adjective} API calls.

supported?
available?

jzelinskie · 2021-10-13T21:38:21Z

docs/consistency-options.md

+[V1 API]: https://buf.build/authzed/api/tree/main/authzed/api/v1
+[Consistency block]: https://buf.build/authzed/api/docs/main/authzed.api.v1#authzed.api.v1.Consistency
+
+## Default Consistency: minimize_latency


I meant we should just change this section title to be "Defaults" since it not only talks about minimize_latency, but also the fully consistent APIs like the schema APIs and write/delete.

jzelinskie · 2021-10-13T21:40:30Z

docs/consistency-options.md

+
+## Default Consistency: minimize_latency
+
+The default consistency level for all V1 API calls (except `WriteRelationships` and `DeleteRelationships`, which are always fully consistent) is `minimize_latency`.


Schema operations are also fully consistent

jzelinskie · 2021-10-13T21:43:18Z

docs/consistency-options.md

+
+Note that the snapshot used will be loaded at the beginning of the API call, and that new data  written *after* the API starts executing will be ignored.
+
+**WARNING:** Use of `fully_consistent` means little caching will be available, which means performance will suffer. Only use if a [ZedToken/Zookie] is not available or absolutely latest information is required.


one sentence per line

jzelinskie · 2021-10-13T21:43:46Z

docs/consistency-options.md

+
+**WARNING:** Use of `fully_consistent` means little caching will be available, which means performance will suffer. Only use if a [ZedToken/Zookie] is not available or absolutely latest information is required.
+
+[ZedToken/Zookie]:zedtokens-and-zookies.md


space between : and zedtokens-and-zookies.md

jzelinskie · 2021-10-13T21:48:51Z

docs/zedtokens-and-zookies.md

+
+### What is a ZedToken or Zookie?
+
+In simplest terms a `ZedToken` (or `Zookie`) is a token representing a **point-in-time** of the SpiceDB datastore, encoded for easy storage and transmission.


"ZedToken (v1) or Zookie (v0)" or maybe even link to the buf docs for each

jzelinskie · 2021-10-13T21:57:30Z

docs/zedtokens-and-zookies.md

+[V1 API]: https://buf.build/authzed/api/tree/main/authzed/api/v1
+[Consistency]: consistency-options.md
+
+#### v0 API


I think we should de-emphasize v0 somehow. Either put it in a <details> or just get rid of it all together.

jzelinskie · 2021-10-13T21:58:42Z

docs/zedtokens-and-zookies.md

+
+In V1, you can pass the `ZedToken` as `at_exact_snapshot` in the [Consistency] options to ensure the API result is computed at that exact point.
+
+**WARNING:** SpiceDB will expire garbage and collect it over time. The above API call *can fail with a "Snapshot Expired" error*. This window is determined by the `--datastore-gc-window` when running SpiceDB.


one sentence per line

I think this probably needs one more sentence describing how you should basically only use this if you're paginating something over a very short amount of time and nothing else.

jzelinskie · 2021-10-13T22:01:09Z

docs/zedtokens-and-zookies.md

+    V1Zookie deprecated_v1_zookie = 2;
+    V1ZedToken v1 = 3;
+  }
+}


I'm afraid of these codeblocks rotting. Maybe we should just link to the proto files?

josephschorr · 2021-10-14T16:17:50Z

Updated

Fixes #13 Signed-off-by: Joseph Schorr <josephschorr@users.noreply.github.com>

josephschorr force-pushed the zedtoken-docs branch from 574f86b to 5c95054 Compare October 5, 2021 20:15

jzelinskie reviewed Oct 5, 2021

View reviewed changes

josephschorr force-pushed the zedtoken-docs branch 2 times, most recently from d84b79b to 63820a9 Compare October 5, 2021 20:47

josephschorr force-pushed the zedtoken-docs branch from 63820a9 to 47ba4a8 Compare October 12, 2021 18:10

josephschorr force-pushed the zedtoken-docs branch 2 times, most recently from 6a53838 to a91c78e Compare October 12, 2021 18:19

jzelinskie requested changes Oct 13, 2021

View reviewed changes

josephschorr force-pushed the zedtoken-docs branch from a91c78e to 43528b1 Compare October 14, 2021 16:17

josephschorr force-pushed the zedtoken-docs branch 2 times, most recently from 55f0248 to 7e9e3b5 Compare October 14, 2021 17:49

Add documentation about ZedTokens/Zookies and consistency

51ef755

Fixes #13 Signed-off-by: Joseph Schorr <josephschorr@users.noreply.github.com>

josephschorr force-pushed the zedtoken-docs branch from 7e9e3b5 to 51ef755 Compare October 14, 2021 17:51

jzelinskie approved these changes Oct 14, 2021

View reviewed changes

josephschorr merged commit e264e9c into main Oct 14, 2021

josephschorr deleted the zedtoken-docs branch October 14, 2021 17:56

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add documentation about ZedTokens/Zookies and consistency #174

Add documentation about ZedTokens/Zookies and consistency #174

josephschorr commented Oct 5, 2021

jzelinskie Oct 5, 2021

jzelinskie Oct 5, 2021

josephschorr Oct 5, 2021

jzelinskie commented Oct 12, 2021

josephschorr commented Oct 12, 2021

josephschorr commented Oct 12, 2021

zarakay commented Oct 13, 2021

josephschorr commented Oct 13, 2021 •

edited

jzelinskie Oct 13, 2021

jzelinskie Oct 13, 2021

jzelinskie Oct 13, 2021

jzelinskie Oct 13, 2021

josephschorr Oct 14, 2021

jzelinskie Oct 14, 2021

jzelinskie Oct 13, 2021

jzelinskie Oct 13, 2021

jzelinskie Oct 13, 2021

jzelinskie Oct 13, 2021

jzelinskie Oct 13, 2021

jzelinskie Oct 13, 2021

jzelinskie Oct 13, 2021

jzelinskie Oct 13, 2021

josephschorr Oct 14, 2021

josephschorr commented Oct 14, 2021

		@@ -0,0 +1,70 @@
		# Consistency Options

		SpiceDB's [V1 API] provides the ability to specify the consistency level at which API calls are made.


		SpiceDB's [V1 API] provides the ability to specify the consistency level at which API calls are made.

		Consistency is provided via the [Consistency block] on API calls.


		## Default Consistency: minimize_latency

		The default consistency level for all V1 API calls (except `WriteRelationships` and `DeleteRelationships`, which are always fully consistent) is `minimize_latency`.


		Note that the snapshot used will be loaded at the beginning of the API call, and that new data written after the API starts executing will be ignored.

		WARNING: Use of `fully_consistent` means little caching will be available, which means performance will suffer. Only use if a [ZedToken/Zookie] is not available or absolutely latest information is required.


		WARNING: Use of `fully_consistent` means little caching will be available, which means performance will suffer. Only use if a [ZedToken/Zookie] is not available or absolutely latest information is required.

		[ZedToken/Zookie]:zedtokens-and-zookies.md


		### What is a ZedToken or Zookie?

		In simplest terms a `ZedToken` (or `Zookie`) is a token representing a point-in-time of the SpiceDB datastore, encoded for easy storage and transmission.


		In V1, you can pass the `ZedToken` as `at_exact_snapshot` in the [Consistency] options to ensure the API result is computed at that exact point.

		WARNING: SpiceDB will expire garbage and collect it over time. The above API call can fail with a "Snapshot Expired" error. This window is determined by the `--datastore-gc-window` when running SpiceDB.

Add documentation about ZedTokens/Zookies and consistency #174

Add documentation about ZedTokens/Zookies and consistency #174

Conversation

josephschorr commented Oct 5, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jzelinskie commented Oct 12, 2021

josephschorr commented Oct 12, 2021

josephschorr commented Oct 12, 2021

zarakay commented Oct 13, 2021

josephschorr commented Oct 13, 2021 • edited

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

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

josephschorr commented Oct 14, 2021

josephschorr commented Oct 13, 2021 •

edited