adopt markdownlint-cli2, sentence-per-line lint

authzed · Apr 24, 2024 · 2609005 · 2609005
1 parent e23c1d3
commit 2609005
Show file tree

Hide file tree

Showing 29 changed files with 1,188 additions and 1,002 deletions.
diff --git a/.github/workflows/lint.yaml b/.github/workflows/lint.yaml
@@ -16,7 +16,22 @@ jobs:
       - uses: "bewuethr/[email protected]"
         with:
           config-file: ".yamllint"
-      - uses: "nosborn/github-action-[email protected]"
+      - uses: "pnpm/action-setup@v3"
         with:
-          files: "."
-          config_file: ".markdownlint.yaml"
+          version: 8
+      - name: "Export pnpm store"
+        shell: "bash"
+        run: |
+          echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV
+      - name: "Setup pnpm cache"
+        uses: "actions/cache@v4"
+        with:
+          path: "${{ env.STORE_PATH }}"
+          key: "${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}"
+          restore-keys: "${{ runner.os }}-pnpm-store-"
+      - name: "Install dependencies"
+        shell: "bash"
+        run: "pnpm install"
+      - name: "Lint"
+        shell: "bash"
+        run: "pnpm run lint"
diff --git a/.markdownlint-cli2.yaml b/.markdownlint-cli2.yaml
@@ -0,0 +1,14 @@
+config:
+  fenced-code-langauage: false
+  fenced-code-language: false
+  first-line-h1: false
+  line-length: false
+  link-image-reference-definitions: false
+  no-duplicate-heading: false
+  no-hard-tabs: false
+  no-inline-html: false
+customRules:
+  - "markdownlint-rule-max-one-sentence-per-line"
+fix: false
+globs:
+  - "pages/**/*{.mdx,.md.markdown}"
diff --git a/.markdownlint.yaml b/.markdownlint.yaml
diff --git a/package.json b/package.json
@@ -6,7 +6,8 @@
     "dev": "next dev",
     "build": "next build",
     "postbuild": "next-sitemap",
-    "start": "next start"
+    "start": "next start",
+    "lint": "markdownlint-cli2"
   },
   "bugs": {
     "url": "https://github.com/authzed/docs/issues"
@@ -40,6 +41,8 @@
     "@types/node": "18.11.10",
     "@types/react": "^18.2.55",
     "autoprefixer": "^10.4.17",
+    "markdownlint-cli2": "^0.13.0",
+    "markdownlint-rule-max-one-sentence-per-line": "^0.0.2",
     "postcss": "^8.4.35",
     "shiki": "^0.14.7",
     "tailwindcss": "^3.4.1",

diff --git a/pages/authzed/concepts/audit-logging.mdx b/pages/authzed/concepts/audit-logging.mdx
@@ -54,7 +54,8 @@ Logs contain the full details related to a request including:
 
 ## Log Sinks
 
-Log Sinks are the targets where logs will be shipped in order to be persisted. In order to configure a log sink, you must file a request with your AuthZed customer success team.
+Log Sinks are the targets where logs will be shipped in order to be persisted.
+In order to configure a log sink, you must file a request with your AuthZed customer success team.
 
 The following are the supported log sinks:
 

diff --git a/pages/authzed/concepts/expedited-support.mdx b/pages/authzed/concepts/expedited-support.mdx
@@ -53,15 +53,13 @@ For bug reports, feature requests, or questions [GitHub issues] is also availabl
 While AuthZed's products are proprietary, lots of the software used to deliver these products are open source.
 Many folks participating in these open source communities are AuthZed customers or employees that have relevant experience.
 
-[Discord]: https://authzed.com/discord
-[GitHub issues]: https://github.com/authzed/spicedb/issues
-[Code of Conduct]: https://github.com/authzed/spicedb/blob/main/CODE-OF-CONDUCT.md
-
 <Callout type="warning">
   **Warning:**
   Help from the community is a volunteer effort.
 
   Be appreciative of any help you receive and always follow the [Code of Conduct].
-
-  [Code of Conduct]: https://github.com/authzed/spicedb/blob/main/CODE-OF-CONDUCT.md
 </Callout>
+
+[Discord]: https://authzed.com/discord
+[GitHub issues]: https://github.com/authzed/spicedb/issues
+[Code of Conduct]: https://github.com/authzed/spicedb/blob/main/CODE-OF-CONDUCT.md
diff --git a/pages/authzed/concepts/extenders.mdx b/pages/authzed/concepts/extenders.mdx
@@ -5,6 +5,7 @@ import { Callout } from 'nextra/components'
 Enterprise builds of SpiceDB support additional behavior provided by an extension point called `Extender`.
 
 Extenders include:
+
 - [Audit Logging](audit-logging)
 - [Restricted API Access (FGAM)](restricted-api-access)
 
@@ -17,20 +18,20 @@ Extenders include:
 
 ## Flags
 
-| Flag | Description | Default |
-| -- | -- | -- |
---extender-audit-batch-size-limit | defines the maximum number of audit events to be processed as a unit | `10000` |
---extender-audit-buffer-size | defines the size of the audit log buffer that holds events to be processed by workers | `1000000` |
---extender-audit-buffer-window | defines maximum amount of time events are buffered before being pushed | `1s` |
---extender-audit-disabled-on-methods strings                      | list of comma-separated, fully-qualified API methods to disable events for. Watch API is always excluded (e.g. `/authzed.api.v1.PermissionsService/CheckPermission`) | |
---extender-audit-initial-retry-interval duration                  | sets the first retry backoff in case of a failure to push audit events to the backend | `1s` |
---extender-audit-max-retry-interval duration                      | sets the maximum backoff duration in case of failure to push events | `30s` |
---extender-audit-retry-randomizer-factor | sets the randomization factor for the backoff duration - this helps prevent thundering herds on event push errors | `0.5` |
---extender-audit-stream-name | defines the name of the target stream/topic (e.g. Kafka Topic, Kinesis Stream...) | `spicedb` |
---extender-audit-target-configuration | target-type specific configuration | `[]` |
---extender-audit-target-endpoint-url string                       | defines the URL of target endpoint to ingest audit events. If left unspecified, some types will try to determine automatically (e.g. AWS SDK) |
---extender-audit-target-type | defines the type of target to ingest audit events | `noop` |
---extender-audit-worker-count | defines the number of worker goroutines to process audit events (default 5) |
---extender-authzed-fgam-endpoint | defines the external SpiceDB endpoint used to authorize operations for the authzed-fgam extender. If a file:// endpoint is provided, server is run embedded with static configuration |
---extender-authzed-fgam-preshared-key | defines the external SpiceDB preshared key used to authorize operations for the authzed-fgam extender. Ignored if endpoint is local (file://) |
---extender-enabled | enables one or more extenders out of [authzed-fgam spicedb-enterprise-serverversion authzed-audit usage]. |
+| Flag                                             | Description                                                                                                                                                                           | Default   |
+| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
+| --extender-audit-batch-size-limit                | defines the maximum number of audit events to be processed as a unit                                                                                                                  | `10000`   |
+| --extender-audit-buffer-size                     | defines the size of the audit log buffer that holds events to be processed by workers                                                                                                 | `1000000` |
+| --extender-audit-buffer-window                   | defines maximum amount of time events are buffered before being pushed                                                                                                                | `1s`      |
+| --extender-audit-disabled-on-methods strings     | list of comma-separated, fully-qualified API methods to disable events for. Watch API is always excluded (e.g. `/authzed.api.v1.PermissionsService/CheckPermission`)                  |           |
+| --extender-audit-initial-retry-interval duration | sets the first retry backoff in case of a failure to push audit events to the backend                                                                                                 | `1s`      |
+| --extender-audit-max-retry-interval duration     | sets the maximum backoff duration in case of failure to push events                                                                                                                   | `30s`     |
+| --extender-audit-retry-randomizer-factor         | sets the randomization factor for the backoff duration - this helps prevent thundering herds on event push errors                                                                     | `0.5`     |
+| --extender-audit-stream-name                     | defines the name of the target stream/topic (e.g. Kafka Topic, Kinesis Stream...)                                                                                                     | `spicedb` |
+| --extender-audit-target-configuration            | target-type specific configuration                                                                                                                                                    | `[]`      |
+| --extender-audit-target-endpoint-url string      | defines the URL of target endpoint to ingest audit events. If left unspecified, some types will try to determine automatically (e.g. AWS SDK)                                         |           |
+| --extender-audit-target-type                     | defines the type of target to ingest audit events                                                                                                                                     | `noop`    |
+| --extender-audit-worker-count                    | defines the number of worker goroutines to process audit events (default 5)                                                                                                           |           |
+| --extender-authzed-fgam-endpoint                 | defines the external SpiceDB endpoint used to authorize operations for the authzed-fgam extender. If a file:// endpoint is provided, server is run embedded with static configuration |           |
+| --extender-authzed-fgam-preshared-key            | defines the external SpiceDB preshared key used to authorize operations for the authzed-fgam extender. Ignored if endpoint is local (file://)                                         |           |
+| --extender-enabled                               | enables one or more extenders out of [authzed-fgam spicedb-enterprise-serverversion authzed-audit usage].                                                                             |           |
diff --git a/pages/authzed/concepts/management-dashboard.mdx b/pages/authzed/concepts/management-dashboard.mdx
@@ -11,5 +11,3 @@ In order to support a wider variety of environments, [Enterprise] customers conf
 [Serverless]: ../guides/picking-a-product#serverless
 [Enterprise]: ../guides/picking-a-product#enterprise
 [Extenders]: ./extenders
-
-
diff --git a/pages/authzed/concepts/private-networking.mdx b/pages/authzed/concepts/private-networking.mdx
@@ -1,17 +1,16 @@
 # Private Networking
 
-Private Networking is functionality exclusive to AuthZed Dedicated that restricts network access to internal networks. When enabled, connections that are not configured are rejected.
+Private Networking is functionality exclusive to AuthZed Dedicated that restricts network access to internal networks.
+When enabled, connections that are not configured are rejected.
 
 By adding this additional layer of security, entire classes of security risk are eliminated because only trusted networks have access to the software powering your authorization systems.
 
 While completely optional, we recommend all users to secure their connections to SpiceDB using Private Networking.
 
 In the scenario you choose not to use Private Networking, AuthZed Dedicated can alternatively be configured for access over the open internet.
 
-## Architecture 
+## Architecture
 
 The following diagram models Private Networking on AWS using AWS PrivateLink:
 
 ![Diagram displaying PrivateLink connecting AWS accounts](/images/aws-dedicated-diagram.png)
-
-
diff --git a/pages/authzed/concepts/restricted-api-access.mdx b/pages/authzed/concepts/restricted-api-access.mdx
@@ -159,6 +159,7 @@ Enterprise builds of SpiceDB can have their API access configured statically wit
 </Callout>
 
 This functionality is configured with the following flags:
+
 - `--extender-authzed-fgam-endpoint`
 - `--extender-authzed-fgam-preshared-key`
 

diff --git a/pages/authzed/concepts/workload-isolation.mdx b/pages/authzed/concepts/workload-isolation.mdx
@@ -9,6 +9,7 @@ Workload Isolation is functionality exclusive to AuthZed products that guarantee
 Services that are secondary to serving real-time requests run one shared workload called the control plane.
 
 These services include:
+
 - AuthZed management UI and its accompanying machinery
 - Observability services for the SRE team (e.g. Prometheus, Grafana, Jaeger)
 - Compliance infrastructure
@@ -17,7 +18,7 @@ These services include:
 
 ## Example Architecture Diagram
 
-![](/images/workload-isolation-diagram.png)
+![Workload Isolation Diagram](/images/workload-isolation-diagram.png)
 
 ## Low-latency Workloads on Kubernetes
 

diff --git a/pages/authzed/guides/setting-up-private-networking.mdx b/pages/authzed/guides/setting-up-private-networking.mdx
@@ -4,7 +4,6 @@ import { Steps } from 'nextra/components'
 
 This guide walks through setting up AuthZed Dedicated [Private Networking].
 
-
 [Private Networking]: ../concepts/private-networking
 
 ## AWS Steps
@@ -73,6 +72,7 @@ For zed to connect to SpiceDB, we'll first have to create an context named `netw
 ```sh
 zed context set network-test example.us-east-1.aws.authzed.net:443 sdbst_h256_cef4fc239bf...
 ```
+
 With our context set, we're free to make requests to our Permission System:
 
 ```sh

diff --git a/pages/spicedb/concepts/caveats.mdx b/pages/spicedb/concepts/caveats.mdx
@@ -113,8 +113,10 @@ WriteRelationshipsRequest {
 
 A few important notes:
 
-- The **Context** of a caveat is defined both by the values written in the `Relationship`, as well as those provided in the `CheckPermissionRequest`: if empty, then only the context specified on a CheckPermission request will be used. Otherwise, the values in the `Relationship` take precedence over those in the `CheckPermissionRequest`.
-  - Context of a caveat provided in `Relationship` is stored alongside the relationship and is provided to the caveat expression at runtime. This allows for **partial** binding of data at write time.
+- The **Context** of a caveat is defined both by the values written in the `Relationship`, as well as those provided in the `CheckPermissionRequest`: if empty, then only the context specified on a CheckPermission request will be used.
+  Otherwise, the values in the `Relationship` take precedence over those in the `CheckPermissionRequest`.
+  - Context of a caveat provided in `Relationship` is stored alongside the relationship and is provided to the caveat expression at runtime.
+    This allows for **partial** binding of data at write time.
 - The Context is a `structpb`, which is defined by Google and represents JSON-like data: [https://pkg.go.dev/google.golang.org/protobuf/types/known/structpb](https://pkg.go.dev/google.golang.org/protobuf/types/known/structpb)
   - To send 64-bit integers, encode them as strings.
 - A relationship cannot be duplicated, with or without a caveat, e.g. two relationships that differ only on their use of a caveat cannot both exist.

diff --git a/pages/spicedb/concepts/commands.mdx b/pages/spicedb/concepts/commands.mdx
@@ -21,7 +21,6 @@ The following are configuration flags that can be provided to every SpiceDB comm
 | --skip-release-check | if true, skips checking for new SpiceDB releases |  |
 | --termination-log-path | define the path to the termination log file, which contains a JSON payload to surface as reason for termination - disabled by default |  |
 
-
 ## Migrate
 
 ### Flags
@@ -37,15 +36,13 @@ The following are configuration flags that can be provided to every SpiceDB comm
 | --migration-backfill-batch-size | number of items to migrate per iteration of a datastore backfill (default 1000) |  |
 | --migration-timeout | defines a timeout for the execution of the migration, set to 1 hour by default (default 1h0m0s) |  |
 
-
 ## Serve
 
 The `serve` command is the primary command for running SpiceDB.
 This command serves the gRPC and HTTP APIs by default.
 
 ### Flags
 
-
 | Flag | Description | Default |
 | --- | --- | --- |
 | --dashboard-addr | address to listen on to serve dashboard | `:8080` |
@@ -157,4 +154,3 @@ This command serves the gRPC and HTTP APIs by default.
 ## Serve-Testing
 
 ### Flags
-
diff --git a/pages/spicedb/concepts/consistency.mdx b/pages/spicedb/concepts/consistency.mdx
@@ -5,7 +5,8 @@ import { Callout } from 'nextra/components'
 
 Consistency is a fundamental concept in distributed systems, databases, and authorization.
 
-SpiceDB is no exception! In fact, the paper that inspired SpiceDB is entitled "Zanzibar: Google's __**Consistent**__, Global Authorization System".
+SpiceDB is no exception!
+In fact, the paper that inspired SpiceDB is entitled "Zanzibar: Google's __**Consistent**__, Global Authorization System".
 
 ## What is consistency?
 
@@ -16,6 +17,7 @@ The following presentation submitted to the [CNCF] gives an overview and example
 [CNCF]: https://cncf.io
 
 ## Consistency in SpiceDB
+
 In SpiceDB, there is a requirement for both proper consistency, as well as excellent performance.
 
 To achieve performance, SpiceDB implements a number of levels of caching, to ensure that repeated permissions checks do not need to be recomputed over and over again, so long as the underlying relationships behind those permissions have not changed.
@@ -113,6 +115,7 @@ ZedTokens are used for data consistency guarantees when using the SpiceDB API.
 ZedToken is the SpiceDB equivalant of Google Zanzibar's [Zookie] concept which protects users from the [New Enemy Problem].
 
 SpiceDB returns ZedTokens from the APIs that perform permission checks or modify data:
+
 - [CheckPermission]
 - [BulkCheckPermission]
 - [WriteRelationships]
@@ -131,6 +134,7 @@ There are scenarios where it makes sense to store ZedTokens in an applications p
 The goal of this workflow is to ensure the application can query SpiceDB with consistency that is causally tied to the content of the protected resource.
 
 Stored ZedTokens should be updated under these events:
+
 - The resource is created or deleted
 - The contents of the resource changes
 - Adding or removing access to the resource (e.g. writing a relationship)

diff --git a/pages/spicedb/concepts/datastores.mdx b/pages/spicedb/concepts/datastores.mdx
@@ -122,14 +122,16 @@ If you need a longer time window for the Watch API or querying at exact snapshot
 ```sql
 ALTER ZONE default CONFIGURE ZONE USING gc.ttlseconds = 90000;
 ```
+
 [crdb-gc]: https://www.cockroachlabs.com/docs/stable/configure-replication-zones.html#replication-zone-variables
 
 ## Cloud Spanner
 
 ### Usage Notes
 
 - Requires a Google Cloud Account with an active Cloud Spanner instance
-- Take advantage of Google's TrueTime. The Spanner driver assumes the database is linearizable and skips the transaction overlap strategy required by CockroachDB.
+- Take advantage of Google's TrueTime.
+  The Spanner driver assumes the database is linearizable and skips the transaction overlap strategy required by CockroachDB.
 
 ### Developer Notes
 
@@ -185,7 +187,6 @@ ALTER ZONE default CONFIGURE ZONE USING gc.ttlseconds = 90000;
   [commit-ts]: https://www.postgresql.org/docs/current/runtime-config-replication.html#GUC-TRACK-COMMIT-TIMESTAMP
 </Callout>
 
-
 ### Developer Notes
 
 - Code can be found [here][pg-code]
@@ -307,4 +308,3 @@ ALTER ZONE default CONFIGURE ZONE USING gc.ttlseconds = 90000;
 | `datastore-revision-fuzzing-duration` | Sets a fuzzing window on all zookies/zedtokens                                      | `--datastore-revision-fuzzing-duration=50ms` |
 | `datastore-gc-window`                 | Sets the window outside of which overwritten relationships are no longer accessible | `--datastore-gc-window=1s`                   |
 | `datastore-readonly`                  | Places the datastore into readonly mode                                             | `--datastore-readonly=true`                  |
-
Original file line number	Diff line number	Diff line change
Expand Up		@@ -11,5 +11,3 @@ In order to support a wider variety of environments, [Enterprise] customers conf
		[Serverless]: ../guides/picking-a-product#serverless
		[Enterprise]: ../guides/picking-a-product#enterprise
		[Extenders]: ./extenders