Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 1 addition & 9 deletions .github/workflows/claude-code-review.yml
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,7 @@ name: "Claude Code Review"

"on":
pull_request:
types:
[
"opened",
"synchronize",
"ready_for_review",
"reopened",
"labeled",
"edited",
]
types: ["opened", "synchronize", "ready_for_review", "reopened", "labeled", "edited"]
# Optional: Only run on specific file changes
# paths:
# - "src/**/*.ts"
Expand Down
4 changes: 4 additions & 0 deletions .oxfmtrc.jsonc
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
{
"$schema": "./node_modules/oxfmt/configuration_schema.json",
"ignorePatterns": ["pnpm-lock.yaml", "app/spicedb/concepts/commands/page.mdx"],
}
2 changes: 0 additions & 2 deletions .prettierignore

This file was deleted.

38 changes: 18 additions & 20 deletions app/authzed/concepts/authzed-materialize/page.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,9 @@ import { Callout } from "nextra/components";
# AuthZed Materialize

<Callout type="info">
AuthZed Materialize is available to users of AuthZed [Dedicated] as part of an
early access program. Don't hesitate to get in touch with your AuthZed account
team if you would like to participate.
AuthZed Materialize is available to users of AuthZed [Dedicated] as part of an early access
program. Don't hesitate to get in touch with your AuthZed account team if you would like to
participate.
</Callout>

AuthZed Materialize takes inspiration from the Leopard index component described in the [Zanzibar paper](https://zanzibar.tech/2IoYDUFMAE:0:T).
Expand Down Expand Up @@ -74,8 +74,8 @@ In situations like these, one may want to store the events in batches, and in su
If a failure happened in between those batches, the consumer will be able to restart processing from the start of the revision and idempotently overwrite whatever events were already in place.

<Callout type="info">
Change events are stored up to 24h to make sure Materialize storage does not
grow unbounded and affect its performance.
Change events are stored up to 24h to make sure Materialize storage does not grow unbounded and
affect its performance.
</Callout>

## Configuration
Expand All @@ -90,9 +90,8 @@ resource#edit@user
```

<Callout type="info">
During early access provisioning, Materialize instances are not self-service,
so you’ll need to provide the permissions to be computed by Materialize
directly to your AuthZed account team.
During early access provisioning, Materialize instances are not self-service, so you’ll need to
provide the permissions to be computed by Materialize directly to your AuthZed account team.
</Callout>

### Relational Database
Expand Down Expand Up @@ -427,8 +426,8 @@ The AuthZed team has optimized Materialize to reduce the number of instances whe
To determine if a schema change is breaking, we provide the `materialize-cli` tool.

<Callout type="info">
`materialize-cli` is still in early development, please reach out to us if you
want to try it as part of AuthZed Materialize early access.
`materialize-cli` is still in early development, please reach out to us if you want to try it as
part of AuthZed Materialize early access.
</Callout>

#### Errors
Expand Down Expand Up @@ -458,10 +457,9 @@ This is useful when the client has been notified a [breaking schema change] occu
If both `optional_at_revision` and `optional_starting_after` are provided, the latter always takes precedence.

<Callout type="warning">
Client **must** provide the revision token after a [breaking schema change]
through `optional_starting_after`, otherwise Materialize will start streaming
permission sets for whatever snapshot revision is available at the moment, and
won't reflect the schema changes.
Client **must** provide the revision token after a [breaking schema change] through
`optional_starting_after`, otherwise Materialize will start streaming permission sets for whatever
snapshot revision is available at the moment, and won't reflect the schema changes.
</Callout>

The current cursor is provided with each event in the stream, so if the consumer client crashes it knows where to restart from, alongside the revision at which the data is computed.
Expand All @@ -478,10 +476,10 @@ In the event of the customer consumer being restarted, it should:
- Resume ingestion as usual

<Callout type="info">
While AuthZed treats correctness very seriously, bugs may be identified that
affect the correctness of the denormalized permissions computed by
Materialize. Those incidents should be rare, but consumers must have all the
machinery in place to re-index via [LookupPermissionSets] at any given time.
While AuthZed treats correctness very seriously, bugs may be identified that affect the
correctness of the denormalized permissions computed by Materialize. Those incidents should be
rare, but consumers must have all the machinery in place to re-index via [LookupPermissionSets] at
any given time.
</Callout>

#### Reindexing After A Breaking Schema Change
Expand Down Expand Up @@ -519,8 +517,8 @@ Once your index is ingested and is updated with [WatchPermissionSets], your appl
This strategy requires more steps and careful planning, but in exchange completely avoids any lag.

<Callout type="info">
For the time being, Materialize instances are not self-serve, so you'll need
to work with your Account Team to execute the off-band ingestion strategy.
For the time being, Materialize instances are not self-serve, so you'll need to work with your
Account Team to execute the off-band ingestion strategy.
</Callout>

#### Request
Expand Down
4 changes: 2 additions & 2 deletions app/authzed/concepts/private-networking/page.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,8 @@ By adding this additional layer of security, entire classes of security risk are
In the scenario you choose not to use Private Networking, AuthZed Dedicated can alternatively be configured for access over the open internet.

<Callout type="info">
Private networking is recommended, but optional. Authzed Dedicated can be
configured to allow for connecting from the public internet.
Private networking is recommended, but optional. Authzed Dedicated can be configured to allow for
connecting from the public internet.
</Callout>

## Architecture
Expand Down
19 changes: 7 additions & 12 deletions app/authzed/concepts/restricted-api-access/page.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -31,15 +31,12 @@ SpiceDB clients must provide a Token in the Authorization header of an API reque
Service Accounts can have an arbitrary number of Tokens.

<Callout type="info">
We recommend deploying new Tokens before deprovisioning any old Tokens to
avoid downtime.
We recommend deploying new Tokens before deprovisioning any old Tokens to avoid downtime.
</Callout>

#### Token Format

<Callout type="warning">
The entire contents of a Token is considered secret.
</Callout>
<Callout type="warning">The entire contents of a Token is considered secret.</Callout>

Tokens come in the form of `{prefix}_{key}`.

Expand Down Expand Up @@ -100,11 +97,10 @@ Policies are what bind Roles to a Service Account.
Each policy is composed of a unique identifier for the policy itself, the principal (the target of the role assignment), and any roles being assigned.

<Callout type="info">
**Policies are additive.** When multiple policies apply to the same Service
Account, the resulting permissions are the union of all permissions granted by
those policies. This means a Service Account with multiple policies will have
access to any API method allowed by any of its policies. For example, if one
policy grants read access and another grants write access, the Service Account
**Policies are additive.** When multiple policies apply to the same Service Account, the resulting
permissions are the union of all permissions granted by those policies. This means a Service
Account with multiple policies will have access to any API method allowed by any of its policies.
For example, if one policy grants read access and another grants write access, the Service Account
will have both read and write access.
</Callout>

Expand Down Expand Up @@ -221,8 +217,7 @@ Use the following command-line flags:
If you set `--extender-authzed-fgam-endpoint` to a file, it must be a YAML configuration file.

<Callout type="warning">
This configuration file should be treated like a secret because it contains
token hashes.
This configuration file should be treated like a secret because it contains token hashes.
</Callout>

Here's an example showcasing the structure of static configuration:
Expand Down
4 changes: 2 additions & 2 deletions app/authzed/guides/setting-up-private-networking/page.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,8 @@ This guide walks through setting up AuthZed Dedicated [Private Networking].
[Private Networking]: ../concepts/private-networking

<Callout type="info">
Private networking is recommended, but optional. Authzed Dedicated can be
configured to allow for connecting from the public internet.
Private networking is recommended, but optional. Authzed Dedicated can be configured to allow for
connecting from the public internet.
</Callout>

## AWS Steps
Expand Down
3 changes: 1 addition & 2 deletions app/layout.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -44,8 +44,7 @@ export const generateMetadata = async (

export default async function RootLayout({ children }) {
const pageMap = await getPageMap();
const enableSearch =
process.env.NEXT_PUBLIC_ENABLE_SEARCH_BLOG_INTEGRATION === "true";
const enableSearch = process.env.NEXT_PUBLIC_ENABLE_SEARCH_BLOG_INTEGRATION === "true";

const navbar = (
<Navbar
Expand Down
6 changes: 1 addition & 5 deletions app/page.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -7,11 +7,7 @@ Browse documentation for **SpiceDB** or **AuthZed Products** by selecting one be
import { Cards } from "nextra/components";

<Cards num={2}>
<Cards.Card
arrow
title="View"
href="/spicedb/getting-started/discovering-spicedb"
>
<Cards.Card arrow title="View" href="/spicedb/getting-started/discovering-spicedb">
<div className="p-4">
<h3>SpiceDB Documentation</h3>
</div>
Expand Down
6 changes: 3 additions & 3 deletions app/spicedb/concepts/caveats/page.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -207,9 +207,9 @@ zed check -r resource:specificresource#view -p view -s user:specificuser --cavea
```

<Callout type="info">
Please note the use of single quotes to escape the characters in the JSON
representation of the context. You don't need character escaping when
providing context using zed in the Authzed Playground.
Please note the use of single quotes to escape the characters in the JSON representation of the
context. You don't need character escaping when providing context using zed in the Authzed
Playground.
</Callout>

## Full Example
Expand Down
3 changes: 1 addition & 2 deletions app/spicedb/concepts/consistency/page.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -52,8 +52,7 @@ Consistency is provided via the [Consistency message][msg] on supported API call
`minimize_latency` will attempt to minimize the latency of the API call by selecting data that is most likely to exist in the cache.

<Callout type="warning">
If used exclusively, this can lead to a window of time where the [New Enemy
Problem] can occur.
If used exclusively, this can lead to a window of time where the [New Enemy Problem] can occur.
</Callout>

[New Enemy Problem]: ./zanzibar#new-enemy-problem
Expand Down
12 changes: 5 additions & 7 deletions app/spicedb/concepts/datastore-migrations/page.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -9,10 +9,9 @@ Transitioning between versions is often as simple as executing a new binary or c
Releases that include changes to datastore (for example, adding a new index) can require that users run a command to update the datastore version.

<Callout type="info">
This page explains migrating the schema of a datastore underlying SpiceDB. If
you need information about migrating between SpiceDB instances, go
[here](/spicedb/ops/data/migrations). If you need information about making
changes to a SpiceDB schema that result in a migration, go
This page explains migrating the schema of a datastore underlying SpiceDB. If you need information
about migrating between SpiceDB instances, go [here](/spicedb/ops/data/migrations). If you need
information about making changes to a SpiceDB schema that result in a migration, go
[here](/spicedb/modeling/migrating-schema).
</Callout>

Expand All @@ -26,9 +25,8 @@ Releases that include changes to datastore (for example, adding a new index) can
Before a datastore can be used by SpiceDB or before running a new version of SpiceDB, you must execute all available migrations.

<Callout type="info">
All datastores supported by SpiceDB (CockroachDB, MySQL, etc) support
migrations. The only exception is the [memdb datastore](datastores#memdb)
because it does not persist any data.
All datastores supported by SpiceDB (CockroachDB, MySQL, etc) support migrations. The only
exception is the [memdb datastore](datastores#memdb) because it does not persist any data.
</Callout>

For this purpose, the SpiceDB binary contains a migration command, `spicedb datastore migrate`. To migrate your datastore to the latest revision, run the following command with your desired values:
Expand Down
11 changes: 5 additions & 6 deletions app/spicedb/concepts/datastores/page.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -325,8 +325,8 @@ If you run into this issue, the fix is [documented here](https://authzed.com/doc
### Read Replicas

<Callout type="warning">
Do not use a load balancer between SpiceDB and MySQL replicas because SpiceDB
will not be able to maintain consistency guarantees.
Do not use a load balancer between SpiceDB and MySQL replicas because SpiceDB will not be able to
maintain consistency guarantees.
</Callout>

SpiceDB supports MySQL read replicas and does it while retaining consistency guarantees.
Expand Down Expand Up @@ -360,8 +360,7 @@ Read replicas are configured with the `--datastore-read-replica-*` family of fla
| `datastore-conn-uri` | connection string used to connect to MySQL | `--datastore-conn-uri="user:password@(localhost:3306)/spicedb?parseTime=True"` |

<Callout type="warning">
SpiceDB requires `--datastore-conn-uri` to contain the query parameter
`parseTime=True`.
SpiceDB requires `--datastore-conn-uri` to contain the query parameter `parseTime=True`.
</Callout>

#### Optional Parameters
Expand Down Expand Up @@ -402,8 +401,8 @@ Read replicas are configured with the `--datastore-read-replica-*` family of fla
- Cannot be ran highly-available as multiple instances will not share the same in-memory data

<Callout type="info">
If you need an ephemeral datastore designed for validation or testing, see the
test server system in [Validating and Testing]
If you need an ephemeral datastore designed for validation or testing, see the test server system
in [Validating and Testing]
</Callout>

[validating and testing]: /spicedb/modeling/validation-testing-debugging
Expand Down
30 changes: 14 additions & 16 deletions app/spicedb/concepts/expiring-relationships/page.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -21,13 +21,12 @@ The time must be specified in [RFC 3339 format].
[RFC 3339 format]: https://datatracker.ietf.org/doc/html/rfc3339#section-5.8

<Callout type="info">
The clock used to determine if a relationship is expired is that of the
underlying SpiceDB datastore. This gets trickier when using distributed
databases like CockroachDB or Spanner, where clocks have an uncertainty range.
When operating your own database, it's key to keep node clocks in sync - we
recommend services like [Amazon Time Sync
Service](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/set-time.html).
You should evaluate the impact of clock drift in your application.
The clock used to determine if a relationship is expired is that of the underlying SpiceDB
datastore. This gets trickier when using distributed databases like CockroachDB or Spanner, where
clocks have an uncertainty range. When operating your own database, it's key to keep node clocks
in sync - we recommend services like [Amazon Time Sync
Service](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/set-time.html). You should evaluate
the impact of clock drift in your application.
</Callout>

## Schema
Expand Down Expand Up @@ -72,10 +71,9 @@ WriteRelationshipsRequest {
```

<Callout type="warning">
When using the WriteRelationships API, it is recommended to always use the
TOUCH operation to create and update expiring relationships. If a relationship
has expired but has not yet been garbage collected, using the CREATE operation
will return an error for that relationship.
When using the WriteRelationships API, it is recommended to always use the TOUCH operation to
create and update expiring relationships. If a relationship has expired but has not yet been
garbage collected, using the CREATE operation will return an error for that relationship.
</Callout>

## Playground
Expand Down Expand Up @@ -115,11 +113,11 @@ the datastore chosen.
Relationships will be reclaimed after 24 hours by default.

<Callout type="info">
The GC Window should be adjusted according to the application's needs. How far
back in time does your application need to go? If this is a common use case,
we recommend drastically reducing the GC window (e.g., 1 hour or 30 minutes).
This means SpiceDB will have to evaluate less data when serving authorization
checks, which can improve performance drastically in large-scale deployments.
The GC Window should be adjusted according to the application's needs. How far back in time does
your application need to go? If this is a common use case, we recommend drastically reducing the
GC window (e.g., 1 hour or 30 minutes). This means SpiceDB will have to evaluate less data when
serving authorization checks, which can improve performance drastically in large-scale
deployments.
</Callout>

## Migrating Off Of Expiration With Caveats
Expand Down
12 changes: 5 additions & 7 deletions app/spicedb/concepts/querying-data/page.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -5,16 +5,14 @@ import { Callout } from "nextra/components";
This page walks through the main ways to query data in SpiceDB. The options are listed roughly in the order of how often you should be calling them, and roughly in order of their expected performance. Choose the one that makes sense for your use case, but consider whether your use case actually requires the call you're looking at.

<Callout type="info">
In most of the APIs below, if you want to be able to read your write, you can
pass a `consistency` parameter to the queries. Use either `fully_consistent`
or `at_least_as_fresh(revision)` depending on how strict you need to be. See
[Consistency](consistency) for more details.
In most of the APIs below, if you want to be able to read your write, you can pass a `consistency`
parameter to the queries. Use either `fully_consistent` or `at_least_as_fresh(revision)` depending
on how strict you need to be. See [Consistency](consistency) for more details.
</Callout>

<Callout type="important">
When invoking any of our APIs, you can send a header `X-Request-ID=somevalue`
and it will be echoed back in the response, which makes correlating logs or
tracing requests easy.
When invoking any of our APIs, you can send a header `X-Request-ID=somevalue` and it will be
echoed back in the response, which makes correlating logs or tracing requests easy.
</Callout>

## Check Permission
Expand Down
Loading