zuplo 6.67.32 → 6.68.0

package/docs/policies/query-param-to-header-inbound/schema.json

@@ -0,0 +1,74 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "http://zuplo.com/schemas/policies/auth0-jwt-auth-inbound.json",
+  "type": "object",
+  "title": "Query Parameter to Header",
+  "isDeprecated": false,
+  "isPaidAddOn": false,
+  "isEnterprise": false,
+  "isInternal": false,
+  "isBeta": false,
+  "isHidden": false,
+  "products": ["api-gateway"],
+  "description": "Extracts a query parameter and sets it as a header in the request.",
+  "deprecatedMessage": "",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "QueryParamToHeaderInboundPolicy",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(@zuplo/runtime)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "title": "QueryParamToHeaderInboundPolicyOptions",
+          "type": "object",
+          "description": "The options for the query parameter to header inbound policy.",
+          "additionalProperties": false,
+          "required": ["queryParam", "headerName", "headerValue"],
+          "properties": {
+            "queryParam": {
+              "type": "string",
+              "examples": ["apiKey", "token"],
+              "description": "The name of the query parameter to extract."
+            },
+            "headerName": {
+              "type": "string",
+              "examples": ["Authorization"],
+              "description": "The name of the header to set."
+            },
+            "headerValue": {
+              "type": "string",
+              "examples": ["Bearer {value}", "{value}"],
+              "description": "The {value} template for the header. Use {value} to substitute the query parameter value."
+            },
+            "removeFromUrl": {
+              "type": "boolean",
+              "default": true,
+              "description": "Whether to remove the query parameter from the URL after extracting it."
+            }
+          }
+        }
+      },
+      "examples": [
+        {
+          "export": "QueryParamToHeaderInboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "headerName": "Authorization",
+            "headerValue": "Bearer {value}",
+            "queryParam": "apiKey",
+            "removeFromUrl": true
+          }
+        }
+      ]
+    }
+  }
+}

package/docs/policies/quota-inbound/doc.md

@@ -0,0 +1,235 @@
+The Quota policy needs to know when to anchor the quota start date so that the
+Zuplo runtime can know where in the quota cycle you are. By default the runtime
+uses the `"quotaAnchorMode": "first-api-call"` which checks to see if we have an
+existing quota record for this user or custom quota key and, if not, sets it
+based on the time of the first API call for this key.
+
+You can customize the subscription date by setting the `getAnchorDateExport`
+function, more below under **Custom Anchor Date**.
+
+## Quota Cycles / Periods
+
+The quota periods run from the anchor date and **time** until the next matching
+cycle. For `monthly` periods, if the anchor date is `2024-01-31 04:30Z` then the
+quota cycle will terminate on the same day of the next month or the last day of
+that month if it is a shorter month, at the same time. In this case the quota
+cycle will reset on `2024-02-29 04:30Z` (because 2024 is a leap year).
+
+`weekly` cycles shift on the same day of the next week, at the same time.
+
+`daily` on the next day, at the same time.
+
+`hourly` on the same minute, of the next hour.
+
+## Custom Meters
+
+You can set custom meters in the allowances property of the options to include
+custom meters other than `requests`. For example, here we set a monthly
+allowance of 10 `bananas`.
+
+```json
+{
+  "name": "my-quota-inbound-policy",
+  "policyType": "quota-inbound",
+  "handler": {
+    "export": "QuotaInboundPolicy",
+    "module": "$import(@zuplo/runtime)",
+    "options": {
+      "period": "monthly",
+      "quotaBy": "user",
+      "allowances": {
+        "bananas": 10
+      }
+    }
+  }
+}
+```
+
+For this to work you must tell the runtime how many `bananas` to increment in a
+given request/response lifecycle. This is achieved by using the `setMeters`
+method on the `QuotaInboundPolicy` class:
+
+```ts
+import { QuotaInboundPolicy } from "@zuplo/runtime";
+
+// ...
+
+QuotaInboundPolicy.setMeters(context, { bananas: 5, oranges: 3 });
+```
+
+This is typically invoked in a custom inbound or outbound policy or a handler.s
+
+## Dynamic Quota Allowances and Keys
+
+Like **Dynamic Rate Limiting**, Quota Keys and allowances can also be set
+dynamically in Zuplo. This is achieved by setting the `identifier` module and
+`getQuotaDetailExport` in your options:
+
+```json
+{
+  "name": "my-quota-inbound-policy",
+  "policyType": "quota-inbound",
+  "handler": {
+    "export": "QuotaInboundPolicy",
+    "module": "$import(@zuplo/runtime)",
+    "options": {
+      "identifier": {
+        "getQuotaDetailExport": "getQuotaDetail",
+        "module": "$import(./modules/my-module)"
+      },
+      "quotaAnchorMode": "first-api-call",
+      // Note this must be 'function' when using a custom detail function
+      "quotaBy": "function"
+    }
+  }
+}
+```
+
+If you wanted to key on a property from the user metadata, like organizationId
+you might have a `getQuotaDetail` implementation that looks like this.
+
+```ts
+// ./modules/my-module.ts
+import { GetQuotaDetailFunction } from "@zuplo/runtime";
+
+export const getQuotaDetail: GetQuotaDetailFunction = async (
+  request,
+  context,
+  policyName
+) => {
+  return {
+    key: request.user.data.organizationId,
+    allowances: {
+      bananas: 100,
+    },
+  };
+};
+```
+
+Note that this method supports async calls and could be used to load quotas from
+another API, but we would recommend caching the results for performance reasons.
+
+## Custom Anchor Date
+
+Similarly, the Anchor Date can be set programmatically - for example you may
+load the 'subscription' start date from another database or API.
+
+```json
+{
+  "name": "my-quota-inbound-policy",
+  "policyType": "quota-inbound",
+  "handler": {
+    "export": "QuotaInboundPolicy",
+    "module": "$import(@zuplo/runtime)",
+    "options": {
+      "identifier": {
+        "getAnchorDateExport": "getAnchorDate",
+        "module": "$import(./modules/my-module)"
+      },
+      // Note this must be 'function' when using a custom anchor date
+      "quotaAnchorMode": "function",
+      "quotaBy": "user"
+    }
+  }
+}
+```
+
+```ts
+// ./modules/my-module.ts
+import { GetQuotaAnchorDateFunction } from "@zuplo/runtime";
+
+export const getAnchorDate: GetQuotaAnchorDateFunction = async (
+  request,
+  context,
+  policyName
+) => {
+  // simple example fetch call, needs error handling, auth etc.
+  const response = await fetch(
+    `https://my-subs-api/subs/${request.user.data.organizationId}`
+  );
+  const data = await response.json();
+
+  return new Date(data.startDate);
+};
+```
+
+Similarly, if you wanted to have a daily quota policy with the Anchor Date set
+to 24 hours from the UTC start of the day (instead of based on the first API
+request for this bucket) you could do the following:
+
+```json
+{
+  "name": "my-quota-inbound-policy",
+  "policyType": "quota-inbound",
+  "handler": {
+    "export": "QuotaInboundPolicy",
+    "module": "$import(@zuplo/runtime)",
+    "options": {
+      "identifier": {
+        "getAnchorDateExport": "getAnchorDate",
+        "module": "$import(./modules/my-module)"
+      },
+      // Note this must be 'function' when using a custom anchor date
+      "quotaAnchorMode": "function",
+      "quotaBy": "user",
+      "period": "daily"
+    }
+  }
+}
+```
+
+With this function to set the anchor date:
+
+```ts
+import { GetQuotaAnchorDateFunction } from "@zuplo/runtime";
+
+export const getAnchorDate: GetQuotaAnchorDateFunction = async (
+  request,
+  context,
+  policyName
+) => {
+  const anchorDate = getStartOfDayUTC(new Date());
+  return anchorDate;
+};
+
+function getStartOfDayUTC(date: Date): Date {
+  const utcDate = new Date(date.getTime());
+  utcDate.setUTCHours(0, 0, 0, 0);
+  return utcDate;
+}
+```
+
+## Get Usage
+
+You can also programmatically access the usage counts with the `getUsage` static
+function on `QuotaInboundPolicy`. This call **must** occur **after** the
+Quota-Inbound policy has executed.
+
+```ts
+
+const usage = QuotaInboundPolicy.getUsage(context, 'quota-policy-name');
+context.log.info(usage);
+
+// This would generate the following output:
+
+{
+  anchorDate: string;
+  nextResetDate: string;
+  meters: Record<string, number>;
+}
+
+// example
+
+{
+  anchorDate: "2023-08-20T03:05:05.493Z",
+  nextResetDate: "2024-08-20T03:05:05.493Z",
+  meters: {
+    requests: 1,
+    bananas: 10
+  }
+
+}
+```
+
+Note that if the quota has not yet been updated for a particular meter, the
+meter will be undefined in the response.

package/docs/policies/quota-inbound/intro.md

@@ -0,0 +1,7 @@
+You can use the Quota policy to limit the number of requests that are allowed to
+happen in a given time period (e.g., monthly). The policy can be applied the
+users or based on custom keys.
+
+It supports `monthly`, `weekly`, `daily` and `hourly` quotas. By default a
+`requests` meter is incremented by 1 for every request but you can also quota by
+other arbitrary meters; more on this below.

package/docs/policies/quota-inbound/schema.json

@@ -0,0 +1,133 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "http://zuplo.com/schemas/policies/auth0-jwt-auth-inbound.json",
+  "type": "object",
+  "title": "Quota",
+  "isDeprecated": false,
+  "isPaidAddOn": false,
+  "isEnterprise": false,
+  "isInternal": false,
+  "isBeta": false,
+  "isHidden": false,
+  "products": ["api-gateway"],
+  "description": "The Quota policy enables you to set monthly, weekly, daily or hourly quotas on your API.",
+  "deprecatedMessage": "",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "QuotaInboundPolicy",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(@zuplo/runtime)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "title": "QuotaInboundPolicyOptions",
+          "type": "object",
+          "description": "The options for this policy.",
+          "additionalProperties": false,
+          "required": ["period", "quotaBy"],
+          "properties": {
+            "period": {
+              "type": "string",
+              "description": "The period of the quota.",
+              "enum": ["hourly", "daily", "weekly", "monthly"]
+            },
+            "quotaBy": {
+              "type": "string",
+              "description": "The quota by.",
+              "enum": ["user", "function"],
+              "default": "user"
+            },
+            "quotaAnchorMode": {
+              "type": "string",
+              "description": "How the policy determines the anchor date for ongoing quota cycles - defaults to `first-api-call` which uses the first API call for this key.",
+              "enum": ["first-api-call", "function"],
+              "default": "first-api-call"
+            },
+            "allowances": {
+              "type": "object",
+              "description": "The allowances for the quota.",
+              "additionalProperties": {
+                "type": "number"
+              }
+            },
+            "quotaOnStatusCodes": {
+              "oneOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "array",
+                  "items": {
+                    "type": "number"
+                  }
+                }
+              ],
+              "x-show-example": false,
+              "description": "A list of successful status codes and ranges \"200-299, 304\" that should trigger a quota increment.",
+              "default": "200-299",
+              "examples": ["200-399"]
+            },
+            "identifier": {
+              "type": "object",
+              "additionalProperties": false,
+              "description": "The module and functions to dynamically set the anchor date and/or the key/allowances for this request.",
+              "required": ["module"],
+              "properties": {
+                "module": {
+                  "type": "string",
+                  "default": "$import(./modules/my-module)",
+                  "description": "Specifies the module to load your custom functions, in the format `$import(./modules/my-module)`.",
+                  "examples": ["$import(./modules/my-module)"]
+                },
+                "getAnchorDateExport": {
+                  "type": "string",
+                  "default": "getAnchorDate",
+                  "description": "used when quotaAnchorMode is `function`. Specifies the export to load your custom function to get the anchor date.",
+                  "examples": ["getAnchorDate"]
+                },
+                "getQuotaDetailExport": {
+                  "type": "string",
+                  "default": "getQuotaDetail",
+                  "description": "used when quotaBy is `function`. Specifies the export to load your custom function to get the quota detail.",
+                  "examples": ["getQuotaDetail"]
+                }
+              }
+            }
+          },
+          "examples": [
+            {
+              "period": "monthly",
+              "quotaBy": "user",
+              "allowances": {
+                "requests": 10
+              },
+              "quotaOnStatusCodes": "200-399"
+            }
+          ]
+        }
+      },
+      "examples": [
+        {
+          "export": "QuotaInboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "allowances": {
+              "requests": 10
+            },
+            "period": "monthly",
+            "quotaBy": "user",
+            "quotaOnStatusCodes": "200-399"
+          }
+        }
+      ]
+    }
+  }
+}

package/docs/policies/rate-limit-inbound/doc.md

@@ -0,0 +1,78 @@
+The Rate Limit Inbound policy allows you to control the number of requests that
+can be made to your API within a specified time window. This helps protect your
+API from abuse, ensures fair usage among clients, and prevents downstream
+services from being overwhelmed.
+
+## Configuration Options
+
+The policy offers several ways to identify and group requests for rate limiting:
+
+- **IP Address**: Limit requests based on the client's IP address
+- **User ID**: Limit requests based on the authenticated user's identity
+- **Custom Function**: Create custom rate limiting logic based on any request
+  property
+- **API Key**: Limit requests based on the API key used for authentication
+
+:::tip
+
+Note you can have multiple instances of rate-limiting policies to use in
+combination. You should apply the longest duration timeWindow first, followed by
+shorter duration time windows.
+
+:::
+
+## Using a custom function
+
+You can create a rate-limit bucket based on any property of a request using a
+custom function that returns a `CustomRateLimitDetails` object (which provides
+the identifier used by the limiting system).
+
+The `CustomRateLimitDetails` object can be used to override the
+`timeWindowMinutes` & `requestsAllowed` options.
+
+This example creates a unique rate-limiting function based on the `customerId`
+parameter in routes (note it's important that a policy like this is applied to a
+route that has a `/:customerId` parameter).
+
+```ts
+//module - ./modules/rate-limiter.ts
+
+import {
+  CustomRateLimitDetails,
+  ZuploRequest,
+  ZuploContext,
+} from "@zuplo/runtime";
+
+export function rateLimitKey(
+  request: ZuploRequest,
+  context: ZuploContext,
+  policyName: string
+): CustomRateLimitDetails | undefined {
+  context.log.info(
+    `processing customerId '${request.params.customerId}' for rate-limit policy '${policyName}'`
+  );
+  if (request.params.customerId === "43567890") {
+    // Override timeWindowMinutes & requestsAllowed
+    return {
+      key: request.params.customerId,
+      requestsAllowed: 100,
+      timeWindowMinutes: 1,
+    };
+  }
+}
+```
+
+```json
+// config - ./config/policies.json
+"export": "RateLimitInboundPolicy",
+"module": "$import(@zuplo/runtime)",
+"options": {
+  "rateLimitBy": "function",
+  "requestsAllowed": 2,
+  "timeWindowMinutes": 1,
+  "identifier": {
+    "module": "$import(./modules/rate-limiter)",
+    "export": "rateLimitKey"
+  }
+}
+```

package/docs/policies/rate-limit-inbound/intro.md

@@ -0,0 +1,30 @@
+Rate-limiting allows you to set a maximum rate of requests for your API gateway.
+This is useful to enforce rate limits agreed with your clients and protect your
+downstream services from being overwhelmed.
+
+The Zuplo Rate-Limit policy allows you to limit requests based on different
+attributes of the incoming request. For example, you might set a rate limit of
+10 requests per minute per user, or 20 requests per minute for a given IP
+address.
+
+With this policy, you'll benefit from:
+
+- **API Protection**: Shield your backend services from traffic spikes and
+  potential DoS attacks
+- **Flexible Limiting Options**: Limit by IP address, user ID, API key, or
+  custom attributes
+- **Granular Control**: Set different limits for different routes, users, or
+  customer tiers
+- **Custom Rate Limit Logic**: Implement dynamic rate limiting with custom
+  functions
+- **Fair Usage Enforcement**: Ensure equitable API access across all consumers
+- **Quota Management**: Easily implement usage-based pricing tiers for your API
+- **Automatic Response Handling**: Returns standard 429 status codes with
+  appropriate headers
+
+The Zuplo rate-limiter also allows you to set a custom bucket name to implement
+rate limits using a function, giving you complete control over how requests are
+grouped and limited.
+
+When a client reaches a rate limit, they will receive a `429 Too Many Requests`
+response code with appropriate headers indicating when they can retry.