@mccaskie-labs/workbench-config 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @mccaskie-labs/workbench-config
 
+## 0.1.3
+
+### Patch Changes
+
+- The `gateway` manifest is now `built` (step 4.5): the `X-Workbench-Env` request header, the per-key rate limit (300 a minute), the `not_found` and `internal_error` codes, and the `gateway.server-timing` probe.
+
 ## 0.1.2
 
 ### Patch Changes

package/capabilities/gateway.json

@@ -4,7 +4,7 @@
   "component": "gateway",
   "title": "Workbench Gateway: keys, headers, budgets and errors",
   "summary": "What every Gateway endpoint shares: project keys by environment and scope, the request and response headers, the monthly budget check and the error codes. Apps hold one Workbench key and never a vendor key.",
-  "status": "planned",
+  "status": "built",
   "surfaces": {
     "gateway": ["GET /v1/health", "GET /v1/usage", "GET /v1/capabilities"],
     "package": ["DEFAULT_GATEWAY_URL"]
@@ -38,7 +38,8 @@
       { "name": "X-Workbench-Job", "required": true, "pattern": "^[a-z0-9._-]{1,64}$", "description": "What the call is for, e.g. article.write. Recorded with usage" },
       { "name": "X-Workbench-Prompt-Version", "required": false, "description": "The app's prompt version, recorded with usage (audit F17)" },
       { "name": "X-Workbench-Subject", "required": false, "pattern": "^[a-z0-9_-]+:[^\\s]{1,128}$", "description": "type:id of the thing the call is about" },
-      { "name": "Idempotency-Key", "required": false, "description": "Email only: a repeat within 24 hours returns the stored result" }
+      { "name": "Idempotency-Key", "required": false, "description": "Email only: a repeat within 24 hours returns the stored result" },
+      { "name": "X-Workbench-Env", "required": false, "pattern": "^(development|staging|production)$", "description": "The caller's WORKBENCH_ENV. The packages send it; a key from another environment is then refused with unauthorised" }
     ],
     "response_headers": ["X-Workbench-Request-Id", "Server-Timing"],
     "server_timing_metrics": ["gw", "vendor_fb", "vendor", "total"]
@@ -46,6 +47,7 @@
   "limits": [
     { "id": "gateway.key-cache", "value": 60, "unit": "seconds", "per": "isolate", "enforced_by": "gateway" },
     { "id": "gateway.budget-cache", "value": 60, "unit": "seconds", "per": "isolate", "enforced_by": "gateway" },
+    { "id": "gateway.rate-limit", "value": 300, "unit": "requests", "per": "minute per key", "enforced_by": "gateway", "refusal": "rate_limited" },
     { "id": "gateway.job-format", "value": "[a-z0-9._-]{1,64}", "unit": "pattern", "per": "request", "enforced_by": "gateway", "refusal": "invalid_request" }
   ],
   "errors": [
@@ -56,15 +58,19 @@
     { "code": "rate_limited", "http": 429, "retryable": true, "meaning": "Per-key rate limit; it stops runaway loops, budgets limit spend" },
     { "code": "not_available", "http": 501, "retryable": false, "meaning": "Not built yet, e.g. bulk email" },
     { "code": "upstream_error", "http": 502, "retryable": true, "meaning": "The vendor failed after the Gateway's retries" },
-    { "code": "upstream_timeout", "http": 504, "retryable": true, "meaning": "The vendor didn't answer in time" }
+    { "code": "upstream_timeout", "http": 504, "retryable": true, "meaning": "The vendor didn't answer in time" },
+    { "code": "not_found", "http": 404, "retryable": false, "meaning": "No such path. Every documented endpoint checks the key and scope first, even one not built yet" },
+    { "code": "internal_error", "http": 500, "retryable": true, "meaning": "The Gateway failed, for example it couldn't read the platform database; nothing was sent to a vendor" }
   ],
   "rules": [
     { "id": "gateway.no-vendor-keys", "kind": "must_not", "text": "Hold a vendor key (Anthropic, Google, OpenAI, Serper, email) in an app. The Gateway key is the only Workbench credential an app has.", "enforced_by": "review", "probe": "gateway.no-vendor-keys.scan" },
     { "id": "gateway.key-per-environment", "kind": "must", "text": "Use the key issued for the Worker's own environment. A staging key is refused by production and the other way round.", "enforced_by": "gateway", "probe": "gateway.wrong-environment" },
+    { "id": "gateway.timing-headers", "kind": "must", "text": "Every Gateway response carries X-Workbench-Request-Id and Server-Timing with gw, vendor_fb, vendor and total, refusals included.", "enforced_by": "gateway", "probe": "gateway.server-timing" },
     { "id": "gateway.request-id-kept", "kind": "must", "text": "Keep X-Workbench-Request-Id with any output stored or any error logged, so it can be matched to a usage row.", "enforced_by": "review", "probe": "gateway.health" }
   ],
   "probes": [
     { "id": "gateway.health", "half": "runtime", "expect": "pass", "smoke": true, "cost_hint_usd": 0 },
+    { "id": "gateway.server-timing", "half": "runtime", "expect": "pass", "smoke": true, "cost_hint_usd": 0 },
     { "id": "gateway.bad-key", "half": "runtime", "expect": "refused_as_expected", "refusal": "unauthorised", "smoke": true, "cost_hint_usd": 0 },
     { "id": "gateway.wrong-scope", "half": "runtime", "expect": "refused_as_expected", "refusal": "forbidden_scope", "cost_hint_usd": 0 },
     { "id": "gateway.wrong-environment", "half": "runtime", "expect": "refused_as_expected", "refusal": "unauthorised", "cost_hint_usd": 0 },

package/dist/capabilities.gen.d.ts

@@ -1,4 +1,4 @@
-export declare const MANIFEST_VERSION: "ce5a8067dcd6";
+export declare const MANIFEST_VERSION: "491c578e91bc";
 export declare const capabilities: {
     readonly ai: {
         readonly $schema: "./schema.json";
@@ -214,7 +214,7 @@ export declare const capabilities: {
         readonly component: "gateway";
         readonly title: "Workbench Gateway: keys, headers, budgets and errors";
         readonly summary: "What every Gateway endpoint shares: project keys by environment and scope, the request and response headers, the monthly budget check and the error codes. Apps hold one Workbench key and never a vendor key.";
-        readonly status: "planned";
+        readonly status: "built";
         readonly surfaces: {
             readonly gateway: readonly ["GET /v1/health", "GET /v1/usage", "GET /v1/capabilities"];
             readonly package: readonly ["DEFAULT_GATEWAY_URL"];
@@ -267,6 +267,11 @@ export declare const capabilities: {
                 readonly name: "Idempotency-Key";
                 readonly required: false;
                 readonly description: "Email only: a repeat within 24 hours returns the stored result";
+            }, {
+                readonly name: "X-Workbench-Env";
+                readonly required: false;
+                readonly pattern: "^(development|staging|production)$";
+                readonly description: "The caller's WORKBENCH_ENV. The packages send it; a key from another environment is then refused with unauthorised";
             }];
             readonly response_headers: readonly ["X-Workbench-Request-Id", "Server-Timing"];
             readonly server_timing_metrics: readonly ["gw", "vendor_fb", "vendor", "total"];
@@ -283,6 +288,13 @@ export declare const capabilities: {
             readonly unit: "seconds";
             readonly per: "isolate";
             readonly enforced_by: "gateway";
+        }, {
+            readonly id: "gateway.rate-limit";
+            readonly value: 300;
+            readonly unit: "requests";
+            readonly per: "minute per key";
+            readonly enforced_by: "gateway";
+            readonly refusal: "rate_limited";
         }, {
             readonly id: "gateway.job-format";
             readonly value: "[a-z0-9._-]{1,64}";
@@ -331,6 +343,16 @@ export declare const capabilities: {
             readonly http: 504;
             readonly retryable: true;
             readonly meaning: "The vendor didn't answer in time";
+        }, {
+            readonly code: "not_found";
+            readonly http: 404;
+            readonly retryable: false;
+            readonly meaning: "No such path. Every documented endpoint checks the key and scope first, even one not built yet";
+        }, {
+            readonly code: "internal_error";
+            readonly http: 500;
+            readonly retryable: true;
+            readonly meaning: "The Gateway failed, for example it couldn't read the platform database; nothing was sent to a vendor";
         }];
         readonly rules: readonly [{
             readonly id: "gateway.no-vendor-keys";
@@ -344,6 +366,12 @@ export declare const capabilities: {
             readonly text: "Use the key issued for the Worker's own environment. A staging key is refused by production and the other way round.";
             readonly enforced_by: "gateway";
             readonly probe: "gateway.wrong-environment";
+        }, {
+            readonly id: "gateway.timing-headers";
+            readonly kind: "must";
+            readonly text: "Every Gateway response carries X-Workbench-Request-Id and Server-Timing with gw, vendor_fb, vendor and total, refusals included.";
+            readonly enforced_by: "gateway";
+            readonly probe: "gateway.server-timing";
         }, {
             readonly id: "gateway.request-id-kept";
             readonly kind: "must";
@@ -357,6 +385,12 @@ export declare const capabilities: {
             readonly expect: "pass";
             readonly smoke: true;
             readonly cost_hint_usd: 0;
+        }, {
+            readonly id: "gateway.server-timing";
+            readonly half: "runtime";
+            readonly expect: "pass";
+            readonly smoke: true;
+            readonly cost_hint_usd: 0;
         }, {
             readonly id: "gateway.bad-key";
             readonly half: "runtime";

package/dist/capabilities.gen.js

@@ -1,6 +1,6 @@
 // Generated by `npm run capabilities:build` from capabilities/*.json. Do not edit.
 // check:capabilities fails in Checks when this file is stale.
-export const MANIFEST_VERSION = "ce5a8067dcd6";
+export const MANIFEST_VERSION = "491c578e91bc";
 export const capabilities = {
     "ai": {
         "$schema": "./schema.json",
@@ -303,7 +303,7 @@ export const capabilities = {
         "component": "gateway",
         "title": "Workbench Gateway: keys, headers, budgets and errors",
         "summary": "What every Gateway endpoint shares: project keys by environment and scope, the request and response headers, the monthly budget check and the error codes. Apps hold one Workbench key and never a vendor key.",
-        "status": "planned",
+        "status": "built",
         "surfaces": {
             "gateway": [
                 "GET /v1/health",
@@ -386,6 +386,12 @@ export const capabilities = {
                     "name": "Idempotency-Key",
                     "required": false,
                     "description": "Email only: a repeat within 24 hours returns the stored result"
+                },
+                {
+                    "name": "X-Workbench-Env",
+                    "required": false,
+                    "pattern": "^(development|staging|production)$",
+                    "description": "The caller's WORKBENCH_ENV. The packages send it; a key from another environment is then refused with unauthorised"
                 }
             ],
             "response_headers": [
@@ -414,6 +420,14 @@ export const capabilities = {
                 "per": "isolate",
                 "enforced_by": "gateway"
             },
+            {
+                "id": "gateway.rate-limit",
+                "value": 300,
+                "unit": "requests",
+                "per": "minute per key",
+                "enforced_by": "gateway",
+                "refusal": "rate_limited"
+            },
             {
                 "id": "gateway.job-format",
                 "value": "[a-z0-9._-]{1,64}",
@@ -471,6 +485,18 @@ export const capabilities = {
                 "http": 504,
                 "retryable": true,
                 "meaning": "The vendor didn't answer in time"
+            },
+            {
+                "code": "not_found",
+                "http": 404,
+                "retryable": false,
+                "meaning": "No such path. Every documented endpoint checks the key and scope first, even one not built yet"
+            },
+            {
+                "code": "internal_error",
+                "http": 500,
+                "retryable": true,
+                "meaning": "The Gateway failed, for example it couldn't read the platform database; nothing was sent to a vendor"
             }
         ],
         "rules": [
@@ -488,6 +514,13 @@ export const capabilities = {
                 "enforced_by": "gateway",
                 "probe": "gateway.wrong-environment"
             },
+            {
+                "id": "gateway.timing-headers",
+                "kind": "must",
+                "text": "Every Gateway response carries X-Workbench-Request-Id and Server-Timing with gw, vendor_fb, vendor and total, refusals included.",
+                "enforced_by": "gateway",
+                "probe": "gateway.server-timing"
+            },
             {
                 "id": "gateway.request-id-kept",
                 "kind": "must",
@@ -504,6 +537,13 @@ export const capabilities = {
                 "smoke": true,
                 "cost_hint_usd": 0
             },
+            {
+                "id": "gateway.server-timing",
+                "half": "runtime",
+                "expect": "pass",
+                "smoke": true,
+                "cost_hint_usd": 0
+            },
             {
                 "id": "gateway.bad-key",
                 "half": "runtime",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mccaskie-labs/workbench-config",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Workbench app configuration: WORKBENCH_ENV, typed variables that fail by name, secrets that are never printed, and the capabilities manifest.",
   "license": "UNLICENSED",
   "type": "module",