From d23f8320ecce19d8738c5f5950a56aaed9138f94 Mon Sep 17 00:00:00 2001 From: Nathan Totten Date: Thu, 2 Nov 2023 11:29:46 -0400 Subject: [PATCH] brownout policy docs --- policies/brown-out-inbound/schema.json | 51 ------------- .../icon.svg | 0 policies/brownout-inbound/intro.md | 12 +++ policies/brownout-inbound/schema.json | 74 +++++++++++++++++++ scripts/update-policies.tsx | 2 +- sidebars.js | 1 + vercel.json | 5 ++ 7 files changed, 93 insertions(+), 52 deletions(-) delete mode 100644 policies/brown-out-inbound/schema.json rename policies/{brown-out-inbound => brownout-inbound}/icon.svg (100%) create mode 100644 policies/brownout-inbound/intro.md create mode 100644 policies/brownout-inbound/schema.json diff --git a/policies/brown-out-inbound/schema.json b/policies/brown-out-inbound/schema.json deleted file mode 100644 index 564f17dc..00000000 --- a/policies/brown-out-inbound/schema.json +++ /dev/null @@ -1,51 +0,0 @@ -{ - "$schema": "https://json-schema.org/draft-07/schema", - "$id": "http://zuplo.com/schemas/policies/brown-out-inbound.json", - "type": "object", - "title": "Brown Out", - "isPreview": true, - "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": [], - "properties": { - "cronExpression": { - "type": "string", - "description": "The cron schedule for when this policy is enabled." - }, - "durationSeconds": { - "type": "number", - "description": "The length of time in seconds that the policy stays enabled after the scheduled time starts." - } - } - } - }, - "examples": [ - { - "export": "BrownOutInbound", - "module": "$import(@zuplo/runtime)", - "options": { - "cronExpression": "0 23 * * ?", - "durationSeconds": 60 - } - } - ] - } - } -} diff --git a/policies/brown-out-inbound/icon.svg b/policies/brownout-inbound/icon.svg similarity index 100% rename from policies/brown-out-inbound/icon.svg rename to policies/brownout-inbound/icon.svg diff --git a/policies/brownout-inbound/intro.md b/policies/brownout-inbound/intro.md new file mode 100644 index 00000000..0959303c --- /dev/null +++ b/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) diff --git a/policies/brownout-inbound/schema.json b/policies/brownout-inbound/schema.json new file mode 100644 index 00000000..7c5075a7 --- /dev/null +++ b/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" + } + } + } + ] + } + } +} diff --git a/scripts/update-policies.tsx b/scripts/update-policies.tsx index 730c07b9..ad54d1f3 100644 --- a/scripts/update-policies.tsx +++ b/scripts/update-policies.tsx @@ -188,7 +188,7 @@ sidebar_label: ${schema.title} ${ schema.isCustom ? `` - : null + : "" } diff --git a/sidebars.js b/sidebars.js index 519b994e..2f493cc2 100644 --- a/sidebars.js +++ b/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", diff --git a/vercel.json b/vercel.json index 47edafd9..bc7db8c8 100644 --- a/vercel.json +++ b/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": [