authzed/docs

Documentation website for Authzed & SpiceDB

docs's Issues

Document HTTP Gateway

As of v1.1.0, SpiceDB ships an HTTP server that runs grpc gateway. This is currently entirely undocumented.

Document SpiceDB proxies (e.g. prom-authzed-proxy)

prom-authzed-proxy is a project that enables secure, multi-tenant PromQL queries by first performing a permissions check in SpiceDB and then enforcing label a label on the downstream PromQL queries.

This could be an entry in a larger document that describes existing proxies that integrate with SpiceDB and how to go about implementing new ones.

Caveats search keyword takes you to legacy link

Searching for caveats at what seems to be the top level results in a link to the legacy API doc (https://authzed.com/docs/reference/api#caveats) and I would expect it to send me here: https://authzed.com/docs/reference/caveats

Start of search:

Search result top of page:

Search result bottom of page:

Search result bottom of page, expanded:

Where search result should go:

Update spicedb parameter to select a datastore

The documentation refers to --datastore-kind for parameter and memdb for an option and it's --datastore-engine and memory in the code.

golang client creation example does not build

I need to change
https://github.com/authzed/docs/blob/main/docs/guides/first-app.mdx?plain=1#L172
to:

	grpcutil.WithInsecureBearerToken("xxxx"),
	grpc.WithTransportCredentials(insecure.NewCredentials()),

(and this needs 2 extra imports). Should I send a PR for the tutorial, or do you want to handle this in the grpcutil module?

The error I otherwise get from go run xxx.go is:

2022/11/15 16:01:54 unable to initialize client: grpc: no transport security set (use grpc.WithTransportCredentials(insecure.NewCredentials()) explicitly or set credentials)
exit status 1

Generate screenshots via GHA

There's an interesting blog post the details using GitHub Actions for generating screenshots of websites.
We could use this to make sure our images are never stale.

https://simonwillison.net/2022/Mar/14/shot-scraper-template/

unclear naming instructions for relations

The documentation for naming relations mentions that relations should be adjectives, but all of the examples are nouns:

docs/docs/reference/schema-lang.md

Lines 116 to 127 in 8ae70d3

	### Naming Relations
	Relations define how one object relates to another object/subject, and thus **relations should be named as adjectives**, read as `{relation name} (of the object)`.
	Examples:
	| Name | Read as |
	| -------- | ---------------------- |
	| `reader` | reader of the document |
	| `writer` | writer of the document |
	| `member` | member of the group |
	| `parent` | parent of the folder |

Create comprehensive documentation on supporting read after writes using zed token

This is a requirement in almost all applications but it's not something we discuss well anywhere.

Configure and pass markdownlint

Match announcementbar CSS with authzed.com

The announcementbar isn't exactly the same as the one on Authzed.com.
It has a white border on the bottom and isn't padded enough.

document x-request-id header

SpiceDB supports clients to provide a x-request-id header that will be returned back in the response as part of the io.spicedb.respmeta.requestid header. This allows clients to trace application requests to SpiceDB requests.

This functionality is unfortunately not documented.

Add documentation on preferred subject IDs and their tradeoffs

Links to sections don't scroll the page down to that section

Originally reported by @ecordell:

Links like https://docs.authzed.com/guides/schema#writing-expected-relations only take you to the top of the page, but if you click on the same link in the table of contents on the right, it does the intended behavior: scrolling to the header.

Browser/OS: Chrome, macOS Monterey

Add spell checking to CI

Possibly using this GHA: https://github.com/rojopolis/spellcheck-github-actions

REST postman sample collection has wrong body for Lookup Subjects

The link https://www.postman.com/authzed/workspace/spicedb/request/21043612-bdadf2bc-b239-4bb4-b248-b21bcf676d31
states for Lookup Subjects the body:
{ "consistency": { "minimizeLatency": true }, "subjectObjectType": "user", "permission": "view", "resource": { "object": { "objectType": "document", "objectId": "topsecret1" } } }

But it should be without the "object" { }
{ "consistency": { "minimizeLatency": true }, "subjectObjectType": "user", "permission": "view", "resource": { "objectType": "document", "objectId": "topsecret1" } }

Standardize a convention for notes, callouts, etc... in documentation

Each doc in the SpiceDB documentation should follow the same conventions for linking to external URLs, presenting notes, callouts, and any other recurring styles.

Documentation missing Docker migration command for persistent storage

Documentation missing Docker migration command for persistent storage:
docker run --rm authzed/spicedb migrate head --datastore-engine=postgres --datastore-conn-uri="postgres://postgres:<db-password>@spicedb-datastore:5432/spicedb?sslmode=disable"

Documentation only states: spicedb migrate head
https://authzed.com/docs/spicedb/selecting-a-datastore

Add caveats to the schema documentation

MySQL is missing from Selecting a Datastore

Not sure if there just aren't MySQL specific flags or if this is an oversight

https://github.com/authzed/docs/blob/main/docs/spicedb/selecting-a-datastore.md
https://docs.authzed.com/spicedb/selecting-a-datastore#mysql

Feedback for “Schema Language”

I think adding a section on Resources and Subjects giving them precise definitions with examples at the start of the doc can make it a lot easier grok and build a mental model from.

I have been trying to answer the question. How is the schema being used and what is the relationship between the schema and what gets put into the database, I wanted to know what goes into the postgres not what is shown the playground which is higher level. How is the engine executing a query for a permission check. I was not able to find any details I am looking for.

I think adding a section along the lines of "How the schema is used by SpiceDB" can be quite helpful. The section should answer the following questions.

1. What happens when a schema is written to spiceDB
2. If I change something in the schema how is versioning handled?
3. There is no version number in the schema how do I evolve the schema?
4. How is a check query executed against a schema, what SQL gets generated is it one SQL query per check or multiple? I have a mental model of how a typical SQL engine executes a query TableScan, HashJoin ... etc. What are operations that are executed during a check? Or a tuple update / insert.

Building a strong mental model of how SpiceDB works is important to building the trust to use it in an application and to fully understand the trade offs of using it.

Add some documentation for SpiceDB Operator

Add documentation for dispatching via XDS

document how to propagate OpenTelemetry traces

some folks have tried to "connect" various service traces using OpenTelemetry, and it was identified there isn't any documentation on how to instrument the various clients

Add quiz component to articles

The NextJS docs have really nice components that quiz the user to see if they understood a section. Applying this idea to some of the documents on complicated topics would be a great addition.

Update notes about when prefixes are required

See: https://authzed.com/docs/reference/schema-lang
See: https://authzed.com/docs/guides/schema

broken links in docs

broken link to Start protecting your first application on https://authzed.com/docs/guides/schema
broken link to schema on: https://authzed.com/docs/guides/writing-relationships

Document SpiceDB dispatching and its configuration

In order to operate a highly available deployment of SpiceDB, you must configure dispatching, which is pretty subtle and undiscoverable until we add documentation for it.

This document should cover

• What is dispatching
• How it works
• Default configuration
• HA configuration

Add debug flag in zed to docs

See: authzed/zed#130

Create a doc dedicated to explaining and configuring billing

Right now users are requesting access to discover what a paid plan looks like.
This should be documented and made obvious to everyone regardless of whether or not they've even registered or starting using a development permissions system.

Add node examples to First-App guide

Now that node supports typescript and the v1 API, we should add that to the examples in the first app guide.
Maybe consider dropping Java in the meantime.

Document `x-request-id` header

SpiceDB supports client-provided Request ID via x-request-id header, but this is not documented.

Add documentation for configuring tracing and OTEL