diff --git a/.markdownlint.yaml b/.markdownlint.yaml index e1a282493d..80875d44c6 100644 --- a/.markdownlint.yaml +++ b/.markdownlint.yaml @@ -1,2 +1,3 @@ --- line-length: false +no-hard-tabs: false diff --git a/CODE-OF-CONDUCT.md b/CODE-OF-CONDUCT.md index 697f83fbd5..868514bdb9 100644 --- a/CODE-OF-CONDUCT.md +++ b/CODE-OF-CONDUCT.md @@ -1,3 +1,5 @@ +# Code of Conduct + As contributors and maintainers of this project, and in the interest of fostering an open and welcoming community, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities. We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, religion, or nationality. @@ -19,4 +21,4 @@ This code of conduct applies both within project spaces and in public spaces whe Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting one or more of the project maintainers. -This Code of Conduct is adapted from the Contributor Covenant, version 1.2.0, available at https://www.contributor-covenant.org/version/1/2/0/code-of-conduct.html +This Code of Conduct is adapted from the Contributor Covenant, version 1.2.0, available [here](https://www.contributor-covenant.org/version/1/2/0/code-of-conduct.html) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6a6af22cce..5b12f3d74d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -58,7 +58,7 @@ In order to protect both you and ourselves, all commits will require an explicit Sign-off commits end with the following line: -``` +```git Signed-off-by: Random J Developer ``` diff --git a/README.md b/README.md index 2e942bce34..c26fed55d5 100644 --- a/README.md +++ b/README.md @@ -13,6 +13,7 @@ SpiceDB is a [Zanzibar]-inspired database that stores, computes, and validates a Developers create a schema that models their permissions requirements and use a [client library] to apply the schema to the database, insert data into the database, and query the data to efficiently check permissions in their applications. Features that distinguish SpiceDB from other systems include: + - [Expressive APIs] for checking permissions, listing access, and powering devtools - An architecture faithful to the [Google Zanzibar] paper, including resistance to the [New Enemy Problem] - An intuitive and expressive [schema language] complete with a [playground] dev environment diff --git a/e2e/newenemy/README.md b/e2e/newenemy/README.md index 74b651ecb9..ae8b9cabeb 100644 --- a/e2e/newenemy/README.md +++ b/e2e/newenemy/README.md @@ -1,14 +1,12 @@ # New Enemy Test -This test suite performs testing for the New Enemy problem on CockroachDB, including -verification that they occur without mitigations and ensuring that when present, -those mitigations work to prevent the issue from occurring. +This test suite performs testing for the New Enemy problem on CockroachDB, including verification that they occur without mitigations and ensuring that when present, those mitigations work to prevent the issue from occurring. -## The Test +## The Test This is the schema: -``` +```zed definition user {} definition resource { relation direct: user @@ -30,34 +28,36 @@ This is how each operation is translated to SQL 1. Write exclusion tuple -```sql -INSERT INTO relation_tuple (namespace,object_id,relation,userset_namespace,userset_object_id,userset_relation) VALUES ("resource","thegoods","direct","user","1","...") ON CONFLICT (namespace,object_id,relation,userset_namespace,userset_object_id,userset_relation) DO UPDATE SET timestamp = now() RETURNING cluster_logical_timestamp() -``` + ```sql + INSERT INTO relation_tuple (namespace,object_id,relation,userset_namespace,userset_object_id,userset_relation) VALUES ("resource","thegoods","direct","user","1","...") ON CONFLICT (namespace,object_id,relation,userset_namespace,userset_object_id,userset_relation) DO UPDATE SET timestamp = now() RETURNING cluster_logical_timestamp() + ``` 2. Write direct tuple -```sql -INSERT INTO relation_tuple (namespace,object_id,relation,userset_namespace,userset_object_id,userset_relation) VALUES ("resource","thegoods","excluded","user","1","...") ON CONFLICT (namespace,object_id,relation,userset_namespace,userset_object_id,userset_relation) DO UPDATE SET timestamp = now() RETURNING cluster_logical_timestamp() -``` + ```sql + INSERT INTO relation_tuple (namespace,object_id,relation,userset_namespace,userset_object_id,userset_relation) VALUES ("resource","thegoods","excluded","user","1","...") ON CONFLICT (namespace,object_id,relation,userset_namespace,userset_object_id,userset_relation) DO UPDATE SET timestamp = now() RETURNING cluster_logical_timestamp() + ``` + 3. Check -```sql -SET TRANSACTION AS OF SYSTEM TIME 1631462510162458000; + ```sql + SET TRANSACTION AS OF SYSTEM TIME 1631462510162458000; -SELECT namespace, object_id, relation, userset_namespace, userset_object_id, userset_relation FROM relation_tuple WHERE namespace = "resource" AND object_id = "thegoods" AND relation = "excluded"; + SELECT namespace, object_id, relation, userset_namespace, userset_object_id, userset_relation FROM relation_tuple WHERE namespace = "resource" AND object_id = "thegoods" AND relation = "excluded"; -SET TRANSACTION AS OF SYSTEM TIME 1631462510162458000; + SET TRANSACTION AS OF SYSTEM TIME 1631462510162458000; -SELECT namespace, object_id, relation, userset_namespace, userset_object_id, userset_relation FROM relation_tuple WHERE namespace = "resource" AND object_id = "thegoods" AND relation = "direct"; -``` + SELECT namespace, object_id, relation, userset_namespace, userset_object_id, userset_relation FROM relation_tuple WHERE namespace = "resource" AND object_id = "thegoods" AND relation = "direct"; + ``` ## Triggering a "New Enemy" -The new enemy problem occurs when a client can observe test steps `exclude write` and `direct write` in sequence, request a check with the revision returned by `direct write`, but still be granted access. This should only happen if the timestamp returned by `direct write` is below the timestamp returned by `exclude write`. +The new enemy problem occurs when a client can observe test steps `exclude write` and `direct write` in sequence, request a check with the revision returned by `direct write`, but still be granted access. +This should only happen if the timestamp returned by `direct write` is below the timestamp returned by `exclude write`. In Zanzibar, this is prevented by Spanner's TrueTime: -> Spanner’s TrueTime mechanism assigns each ACL write a microsecond-resolution timestamp, such that the timestamps of writes reflect the causal ordering between writes, and thereby provide external consistency. +> Spanner’s TrueTime mechanism assigns each ACL write a microsecond-resolution timestamp, such that the timestamps of writes reflect the causal ordering between writes, and thereby provide external consistency. CockroachDB doesn't provide the same guarantees, instead choosing to wait on subsequent reads of overlapping keys. @@ -76,7 +76,7 @@ It's easier to force these conditions by configuring cockroach with: ALTER DATABASE spicedb CONFIGURE ZONE USING range_min_bytes = 0, range_max_bytes = 65536, num_replicas = 1;" ``` -This makes ranges as small as possible (increasing the likelihood keys will land in different ranges) and reduces the replica count to 1 (making it impossible for a node to have a follower of the raft leader) +This makes ranges as small as possible (increasing the likelihood keys will land in different ranges) and reduces the replica count to 1 (making it impossible for a node to have a follower of the raft leader). Even under these conditions, to trigger the new enemy problem we have to: @@ -87,7 +87,7 @@ _Note: timechaos only works on amd64 and ptrace calls don't work in qemu, which ## Build notes -This runs in CI and builds spicedb from head. +This runs in CI and builds spicedb from head. The go.mod/go.sum may get out of sync. If they do, they can be fixed with: @@ -96,4 +96,4 @@ cd e2e go get -d github.com/authzed/spicedb/cmd/spicedb/... go build github.com/authzed/spicedb/cmd/spicedb/... go mod tidy -``` \ No newline at end of file +```