brownout policy docs

policies/brownout-inbound/intro.md

@@ -0,0 +1,12 @@
+The brownout policy allows performing scheduled downtime on your API. This can
+be useful for helping notify clients of an impending deprecation or for
+scheduling maintenance.
+
+This policy uses [cron schedules](https://crontab.guru/) to check if a request
+should experience a brownout or not. When a request falls into a scheduled
+brownout an error response will be return. The error response can be customized
+by setting the `problem` properties.
+
+For more information using brownouts to alert clients on impending API
+changes/deprecations see our blog post
+[How to version an API](https://zuplo.com/blog/2022/05/17/how-to-version-an-api)

policies/brownout-inbound/schema.json

@@ -0,0 +1,74 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "http://zuplo.com/schemas/policies/brown-out-inbound.json",
+  "type": "object",
+  "title": "Brown Out",
+  "description": "Set periods of downtime based on cron schedules. Useful for alerting users of impending deprecations.",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "BrownOutInbound",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(@zuplo/runtime)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "type": "object",
+          "description": "The options for this policy",
+          "required": ["cronSchedule"],
+          "properties": {
+            "cronSchedule": {
+              "oneOf": [
+                { "type": "string" },
+                { "type": "array", "item": { "type": "string" } }
+              ],
+              "description": "The cron schedule for when this policy is enabled. This can be a single cron string or an array of multiple cron strings"
+            },
+            "problem": {
+              "type": "object",
+              "description": "The problem that is returned in the response body when this policy is enabled",
+              "additionalProperties": true,
+              "properties": {
+                "type": {
+                  "type": "string",
+                  "description": "The type of problem"
+                },
+                "title": {
+                  "type": "string",
+                  "description": "The title of problem"
+                },
+                "detail": {
+                  "type": "string",
+                  "description": "The detail of problem"
+                },
+                "status": {
+                  "type": "number",
+                  "description": "Http status code of the problem"
+                }
+              }
+            }
+          }
+        }
+      },
+      "examples": [
+        {
+          "export": "BrownOutInbound",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "cronSchedule": "0 23 * * *",
+            "problem": {
+              "detail": "This endpoint is deprecated and will be removed in the next version"
+            }
+          }
+        }
+      ]
+    }
+  }
+}

scripts/update-policies.tsx

@@ -188,7 +188,7 @@ sidebar_label: ${schema.title}
 ${
   schema.isCustom
     ? `<CustomPolicyNotice name="${schema.title}" id="${policyId}" />`
-    : null
+    : ""
 }
 
 <!-- start: intro.md -->

sidebars.js

@@ -234,6 +234,7 @@ const sidebars = {
               label: "Other",
               items: [
                 "policies/composite-inbound",
+                "policies/brownout-inbound",
                 "policies/caching-inbound",
                 "policies/archive-request-inbound",
                 "policies/archive-response-outbound",

vercel.json

@@ -756,6 +756,11 @@
       "source": "/docs/articles/supabase-auth{/}?",
       "destination": "/docs/articles/dev-portal-supabase-auth",
       "permanent": true
+    },
+    {
+      "source": "/docs/policies/brown-out-inbound{/}?",
+      "destination": "/docs/policies/brownout-inbound",
+      "permanent": true
     }
   ],
   "headers": [