zuplo 6.71.20 → 6.71.22

package/docs/policies/rate-limit-inbound/schema.json

@@ -96,14 +96,16 @@
             {
               "rateLimitBy": "ip",
               "requestsAllowed": 2,
-              "timeWindowMinutes": 1
+              "timeWindowMinutes": 1,
+              "mode": "async"
             },
             {
               "rateLimitBy": "function",
               "identifier": {
                 "export": "$import(./modules/my-module)",
                 "module": "default"
-              }
+              },
+              "mode": "async"
             }
           ]
         }
@@ -115,7 +117,8 @@
           "options": {
             "rateLimitBy": "ip",
             "requestsAllowed": 2,
-            "timeWindowMinutes": 1
+            "timeWindowMinutes": 1,
+            "mode": "async"
           }
         },
         {
@@ -126,7 +129,8 @@
             "identifier": {
               "export": "$import(./modules/my-module)",
               "module": "default"
-            }
+            },
+            "mode": "async"
           }
         }
       ]

package/docs/policies/traffic-splitting-inbound/doc.md

@@ -0,0 +1,67 @@
+On each request this policy selects one of the configured `basePaths` at random,
+weighted by each entry's `weight`. Weights are relative — they do not need to
+add up to 100. The selected URL is written to the request custom context at the
+path given by `customOutputProperty`.
+
+### Using the selected base path
+
+The selected URL is stored on `context.custom` and is intended to be consumed by
+a later handler on the same route. Reference it using the `customOutputProperty`
+path you configured. For example, with
+`"customOutputProperty": "trafficSplitting.basePath"`:
+
+```json
+// URL Rewrite handler
+{
+  "handler": {
+    "export": "urlRewriteHandler",
+    "module": "$import(@zuplo/runtime)",
+    "options": {
+      "rewritePattern": "${context.custom.trafficSplitting.basePath}/users/${params.id}"
+    }
+  }
+}
+```
+
+```json
+// URL Forward handler
+{
+  "handler": {
+    "export": "urlForwardHandler",
+    "module": "$import(@zuplo/runtime)",
+    "options": {
+      "baseUrl": "${context.custom.trafficSplitting.basePath}"
+    }
+  }
+}
+```
+
+> The `redirect` handler's `location` is not interpolated — use the URL Rewrite
+> or URL Forward handler to route to the selected base path.
+
+### Only one value is in effect
+
+`customOutputProperty` resolves to a single value. If more than one Traffic
+Splitting policy on a route writes to the same property, the **last policy to
+run wins** — its selection is the one the handler sees. In practice you should
+configure a single Traffic Splitting policy per output property.
+
+### Environment variables
+
+Because each `url` is a string value, you can reference environment variables in
+it, including mixed strings:
+
+```json
+{
+  "basePaths": [
+    { "url": "$env(STABLE_BASE_URL)", "weight": 90 },
+    { "url": "$env(CANARY_BASE_URL)/v2", "weight": 10 }
+  ],
+  "customOutputProperty": "trafficSplitting.basePath"
+}
+```
+
+### Logging the selection
+
+Set `"logSelection": true` to log which base path was selected on each request.
+This is off by default.

package/docs/policies/traffic-splitting-inbound/intro.md

@@ -0,0 +1,5 @@
+The traffic splitting policy randomly distributes incoming requests across a set
+of weighted base paths. It selects one base path per request and writes it to
+the request custom context, where a URL Rewrite or URL Forward handler can use
+it to route the request. This is useful for blue/green rollouts, canary
+releases, or splitting traffic between backends.

package/docs/policies/traffic-splitting-inbound/schema.json

@@ -0,0 +1,121 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "https://cdn.zuplo.com/policies/runtime/schemas/traffic-splitting-inbound.json",
+  "type": "object",
+  "title": "Traffic Splitting",
+  "isDeprecated": false,
+  "isPaidAddOn": false,
+  "isEnterprise": false,
+  "isInternal": false,
+  "isBeta": false,
+  "isHidden": false,
+  "requiresAI": false,
+  "products": ["api-gateway"],
+  "description": "Splits traffic randomly across a set of weighted base paths. On each request one base path is selected (weighted by `weight`) and written to the request custom context at `customOutputProperty`. Reference it from a later URL Rewrite `rewritePattern` or URL Forward `baseUrl`, e.g. `${context.custom.trafficSplitting.basePath}`.",
+  "deprecatedMessage": "",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "TrafficSplittingInboundPolicy",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(@zuplo/runtime)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "title": "TrafficSplittingInboundPolicyOptions",
+          "type": "object",
+          "description": "The options for this policy.",
+          "additionalProperties": false,
+          "required": ["basePaths", "customOutputProperty"],
+          "properties": {
+            "basePaths": {
+              "type": "array",
+              "description": "The set of base paths (URLs) to split traffic across. One entry is selected at random per request, weighted by its `weight`.",
+              "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["url", "weight"],
+                "properties": {
+                  "url": {
+                    "type": "string",
+                    "examples": ["https://api-v1.example.com"],
+                    "description": "The base path (URL) to route to when this entry is selected. Supports environment variables, e.g. `$env(BASE_URL)/v2`."
+                  },
+                  "weight": {
+                    "type": "number",
+                    "minimum": 0,
+                    "examples": [80],
+                    "description": "The relative weight for this base path. Higher weights receive proportionally more traffic. Weights are relative and do not need to add up to 100."
+                  }
+                }
+              }
+            },
+            "customOutputProperty": {
+              "type": "string",
+              "pattern": "^[A-Za-z_$][A-Za-z0-9_$]*(\\.[A-Za-z_$][A-Za-z0-9_$]*)*$",
+              "examples": ["trafficSplitting.basePath"],
+              "description": "A simple dotted property path under the request custom context where the selected URL is written (e.g. `trafficSplitting.basePath`). Reference it later in a URL Rewrite `rewritePattern` or URL Forward `baseUrl` as `${context.custom.trafficSplitting.basePath}`. Only one value is in effect; if multiple Traffic Splitting policies write the same property, the last one to run wins. Array indexes and brackets are not allowed."
+            },
+            "logSelection": {
+              "type": "boolean",
+              "default": false,
+              "x-show-example": false,
+              "description": "When `true`, logs which base path was selected for each request. Defaults to `false`."
+            }
+          },
+          "examples": [
+            {
+              "basePaths": [
+                {
+                  "url": "https://api-v1.example.com",
+                  "weight": 80
+                },
+                {
+                  "url": "https://api-v2.example.com",
+                  "weight": 15
+                },
+                {
+                  "url": "$env(CANARY_BASE_URL)",
+                  "weight": 5
+                }
+              ],
+              "customOutputProperty": "trafficSplitting.basePath",
+              "logSelection": true
+            }
+          ]
+        }
+      },
+      "examples": [
+        {
+          "export": "TrafficSplittingInboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "basePaths": [
+              {
+                "url": "https://api-v1.example.com",
+                "weight": 80
+              },
+              {
+                "url": "https://api-v2.example.com",
+                "weight": 15
+              },
+              {
+                "url": "$env(CANARY_BASE_URL)",
+                "weight": 5
+              }
+            ],
+            "customOutputProperty": "trafficSplitting.basePath",
+            "logSelection": true
+          }
+        }
+      ]
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zuplo",
-  "version": "6.71.20",
+  "version": "6.71.22",
   "type": "module",
   "description": "The programmable API Gateway",
   "author": "Zuplo, Inc.",
@@ -19,9 +19,9 @@
     "zuplo": "zuplo.js"
   },
   "dependencies": {
-    "@zuplo/cli": "6.71.20",
-    "@zuplo/core": "6.71.20",
-    "@zuplo/runtime": "6.71.20",
+    "@zuplo/cli": "6.71.22",
+    "@zuplo/core": "6.71.22",
+    "@zuplo/runtime": "6.71.22",
     "@zuplo/test": "1.4.0"
   }
 }