zuplo 6.70.70 → 6.71.0

package/docs/rate-limiting/combining-policies.mdx

@@ -0,0 +1,293 @@
+---
+title: Combining rate limit policies
+sidebar_label: Combining policies
+description:
+  Apply multiple rate limits to the same route, combine rate limiting with
+  quotas, and design multi-layer protection strategies.
+---
+
+Real-world APIs rarely need just one rate limiting boundary. A payment endpoint
+might need a per-minute burst limit to protect against runaway scripts _and_ a
+per-hour cap to enforce fair usage. A monetized API might pair a monthly quota
+with a per-second spike guard. Zuplo supports all of these patterns by letting
+you stack multiple policies on the same route.
+
+## Multiple rate limits on one route
+
+You can apply two or more rate limiting policies to a single route. Each policy
+maintains its own counter independently, and the request must pass every policy
+to reach the backend.
+
+A common pattern is combining a short-window burst limit with a longer-window
+sustained limit. The following example enforces both a 1,000-requests-per-hour
+ceiling and a 100-requests-per-minute burst limit on the same route.
+
+### Define the policies
+
+```json title="config/policies.json"
+{
+  "policies": [
+    {
+      "name": "rate-limit-hourly",
+      "policyType": "rate-limit-inbound",
+      "handler": {
+        "export": "RateLimitInboundPolicy",
+        "module": "$import(@zuplo/runtime)",
+        "options": {
+          "rateLimitBy": "user",
+          "requestsAllowed": 1000,
+          "timeWindowMinutes": 60
+        }
+      }
+    },
+    {
+      "name": "rate-limit-per-minute",
+      "policyType": "rate-limit-inbound",
+      "handler": {
+        "export": "RateLimitInboundPolicy",
+        "module": "$import(@zuplo/runtime)",
+        "options": {
+          "rateLimitBy": "user",
+          "requestsAllowed": 100,
+          "timeWindowMinutes": 1
+        }
+      }
+    }
+  ]
+}
+```
+
+### Attach them to a route
+
+List both policies in the route's inbound pipeline. Place the longest time
+window first:
+
+```json title="config/routes.oas.json (excerpt)"
+{
+  "x-zuplo-route": {
+    "policies": {
+      "inbound": ["rate-limit-hourly", "rate-limit-per-minute"]
+    }
+  }
+}
+```
+
+:::tip
+
+Apply the longest time window first. If a caller already exhausted the hourly
+quota, the request is rejected immediately without incrementing the per-minute
+counter. This avoids wasting counter writes on requests that would fail anyway.
+
+:::
+
+Each policy tracks its own sliding window counter scoped by its `name`. A
+request that passes the hourly check still gets evaluated against the per-minute
+check. If either policy rejects the request, the client receives a
+`429 Too Many Requests` response.
+
+## Rate limiting vs. quotas
+
+Rate limiting and quotas both cap usage, but they solve different problems.
+
+| Aspect            | Rate limiting                                       | Quota                                        |
+| ----------------- | --------------------------------------------------- | -------------------------------------------- |
+| **Time window**   | Short: seconds, minutes, or hours                   | Long: hourly, daily, weekly, or monthly      |
+| **Purpose**       | Protect backends from traffic spikes                | Enforce billing-period usage caps            |
+| **Counter reset** | Sliding window rolls continuously                   | Fixed period anchored to a start date        |
+| **Typical use**   | "100 requests per minute per user"                  | "10,000 requests per month per subscription" |
+| **Policy**        | [Rate Limiting](../policies/rate-limit-inbound.mdx) | [Quota](../policies/quota-inbound.mdx)       |
+
+Use rate limiting when you need to smooth traffic and prevent bursts. Use quotas
+when you need to enforce a usage allowance over a billing cycle. In many APIs,
+you use both together: a monthly quota to cap total usage and a per-minute rate
+limit to prevent any single caller from overwhelming the backend within that
+quota.
+
+### Example: quota plus rate limit
+
+```json title="config/policies.json"
+{
+  "policies": [
+    {
+      "name": "monthly-quota",
+      "policyType": "quota-inbound",
+      "handler": {
+        "export": "QuotaInboundPolicy",
+        "module": "$import(@zuplo/runtime)",
+        "options": {
+          "period": "monthly",
+          "quotaBy": "user",
+          "allowances": {
+            "requests": 10000
+          }
+        }
+      }
+    },
+    {
+      "name": "burst-rate-limit",
+      "policyType": "rate-limit-inbound",
+      "handler": {
+        "export": "RateLimitInboundPolicy",
+        "module": "$import(@zuplo/runtime)",
+        "options": {
+          "rateLimitBy": "user",
+          "requestsAllowed": 100,
+          "timeWindowMinutes": 1
+        }
+      }
+    }
+  ]
+}
+```
+
+On the route, place the quota policy first so that callers who already used
+their monthly allowance are rejected before the rate limit counter is
+incremented:
+
+```json title="config/routes.oas.json (excerpt)"
+{
+  "x-zuplo-route": {
+    "policies": {
+      "inbound": ["monthly-quota", "burst-rate-limit"]
+    }
+  }
+}
+```
+
+## Rate limiting with monetization
+
+The [Monetization policy](../articles/monetization/monetization-policy.md)
+handles subscription validation, quota enforcement, and metering in one step. It
+already enforces billing-period usage limits tied to the customer's plan, so you
+do not need a separate quota policy on monetized routes.
+
+Rate limiting is still valuable alongside monetization. A customer with a 50,000
+requests-per-month plan could theoretically send all 50,000 requests in a single
+minute, which would overwhelm your backend even though it falls within the
+monthly allowance. Adding a rate limiting policy prevents that spike.
+
+```json title="config/routes.oas.json (excerpt)"
+{
+  "x-zuplo-route": {
+    "policies": {
+      "inbound": ["monetization-inbound", "rate-limit-per-minute"]
+    }
+  }
+}
+```
+
+:::note
+
+The monetization policy handles API key authentication internally. You do not
+need a separate `api-key-auth` policy on monetized routes. Place the
+monetization policy first so that `request.user` is populated before the rate
+limit policy runs.
+
+:::
+
+These two layers are complementary:
+
+- **Monetization** enforces monthly or billing-period usage limits and tracks
+  metered usage for billing.
+- **Rate limiting** enforces per-minute or per-second spike protection to keep
+  your backend healthy.
+
+## Counter scoping
+
+Rate limit counters are scoped by the policy's `name` field combined with the
+caller identifier (user, IP, or custom key). Understanding this scoping is
+important when you apply the same policy type to multiple routes.
+
+### Shared counters
+
+If two routes reference the same policy name, they share a counter. A caller who
+makes 60 requests to `/orders` and 40 requests to `/products` — both using a
+policy named `rate-limit-per-minute` — counts as 100 total requests against that
+policy's limit.
+
+```json title="config/routes.oas.json (excerpt)"
+{
+  "paths": {
+    "/orders": {
+      "get": {
+        "x-zuplo-route": {
+          "policies": {
+            "inbound": ["rate-limit-per-minute"]
+          }
+        }
+      }
+    },
+    "/products": {
+      "get": {
+        "x-zuplo-route": {
+          "policies": {
+            "inbound": ["rate-limit-per-minute"]
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+Shared counters are useful when you want a single global limit that applies
+across all routes for a given caller.
+
+### Independent counters
+
+To give each route its own counter, create separate policy instances with
+different names:
+
+```json title="config/policies.json"
+{
+  "policies": [
+    {
+      "name": "rate-limit-orders",
+      "policyType": "rate-limit-inbound",
+      "handler": {
+        "export": "RateLimitInboundPolicy",
+        "module": "$import(@zuplo/runtime)",
+        "options": {
+          "rateLimitBy": "user",
+          "requestsAllowed": 100,
+          "timeWindowMinutes": 1
+        }
+      }
+    },
+    {
+      "name": "rate-limit-products",
+      "policyType": "rate-limit-inbound",
+      "handler": {
+        "export": "RateLimitInboundPolicy",
+        "module": "$import(@zuplo/runtime)",
+        "options": {
+          "rateLimitBy": "user",
+          "requestsAllowed": 200,
+          "timeWindowMinutes": 1
+        }
+      }
+    }
+  ]
+}
+```
+
+Now a caller can make 100 requests per minute to `/orders` and 200 requests per
+minute to `/products` independently. Exhausting the orders limit does not affect
+the products limit.
+
+:::warning
+
+If you duplicate a policy definition and forget to change the `name`, both
+routes share the same counter. Always verify that policy names are distinct when
+you intend independent counters.
+
+:::
+
+## Related resources
+
+- [Rate Limiting policy reference](../policies/rate-limit-inbound.mdx)
+- [Complex Rate Limiting policy reference](../policies/complex-rate-limit-inbound.mdx)
+- [Quota policy reference](../policies/quota-inbound.mdx)
+- [Monetization policy](../articles/monetization/monetization-policy.md)
+- [How rate limiting works](./how-it-works.md)
+- [Dynamic Rate Limiting](./dynamic-rate-limiting.mdx)

package/docs/rate-limiting/dynamic-rate-limiting.mdx

@@ -0,0 +1,240 @@
+---
+title: Dynamic rate limiting
+sidebar_label: Dynamic rate limiting
+description:
+  Learn how to implement dynamic rate limiting with custom functions to apply
+  different limits based on customer tier, route, or any request property.
+---
+
+Static rate limits apply the same threshold to every caller. Dynamic rate
+limiting lets you determine limits at request time — so premium customers get
+higher throughput, free-tier users get a lower ceiling, and internal services
+can bypass limits entirely.
+
+Dynamic rate limiting works with both the
+[Rate Limiting policy](../policies/rate-limit-inbound.mdx) and the
+[Complex Rate Limiting policy](../policies/complex-rate-limit-inbound.mdx).
+
+## How it works
+
+When you set `rateLimitBy` to `"function"`, the policy calls a TypeScript
+function you provide on every request. That function returns a
+`CustomRateLimitDetails` object that tells the rate limiter:
+
+- **`key`** — The string used to group requests into buckets (e.g., a user ID or
+  API key consumer name).
+- **`requestsAllowed`** (optional) — Overrides the policy's default
+  `requestsAllowed` for this request.
+- **`timeWindowMinutes`** (optional) — Overrides the policy's default
+  `timeWindowMinutes` for this request.
+
+Returning `undefined` skips rate limiting for that request entirely.
+
+## Create a rate limit function
+
+Create a new module (for example `modules/rate-limit.ts`) with a function that
+inspects the request and returns the appropriate limits.
+
+The following example reads a `customerType` field from the authenticated user's
+metadata and applies different limits per tier:
+
+```ts title="modules/rate-limit.ts"
+import {
+  CustomRateLimitDetails,
+  ZuploContext,
+  ZuploRequest,
+} from "@zuplo/runtime";
+
+export function rateLimit(
+  request: ZuploRequest,
+  context: ZuploContext,
+  policyName: string,
+): CustomRateLimitDetails | undefined {
+  const user = request.user;
+
+  // Premium customers get 1000 requests per minute
+  if (user.data.customerType === "premium") {
+    return {
+      key: user.sub,
+      requestsAllowed: 1000,
+      timeWindowMinutes: 1,
+    };
+  }
+
+  // Free customers get 50 requests per minute
+  if (user.data.customerType === "free") {
+    return {
+      key: user.sub,
+      requestsAllowed: 50,
+      timeWindowMinutes: 1,
+    };
+  }
+
+  // Default for any other customer type
+  return {
+    key: user.sub,
+    requestsAllowed: 100,
+    timeWindowMinutes: 1,
+  };
+}
+```
+
+:::tip
+
+When using [API key authentication](../articles/api-key-authentication.mdx), the
+`user.data` object contains the metadata you set when creating the API key
+consumer. When using JWT authentication, it contains the decoded token claims.
+
+:::
+
+## Configure the policy
+
+Wire the function into the rate limiting policy by setting `rateLimitBy` to
+`"function"` and pointing the `identifier` option at your module:
+
+```json title="config/policies.json"
+{
+  "name": "my-dynamic-rate-limit-policy",
+  "policyType": "rate-limit-inbound",
+  "handler": {
+    "export": "RateLimitInboundPolicy",
+    "module": "$import(@zuplo/runtime)",
+    "options": {
+      "rateLimitBy": "function",
+      "requestsAllowed": 100,
+      "timeWindowMinutes": 1,
+      "identifier": {
+        "export": "rateLimit",
+        "module": "$import(./modules/rate-limit)"
+      }
+    }
+  }
+}
+```
+
+The `requestsAllowed` and `timeWindowMinutes` values in the policy configuration
+serve as defaults. Your function can override them per request, or omit them to
+use the defaults.
+
+## Common patterns
+
+### Tier-based limits from API key metadata
+
+Store a `plan` or `customerType` field in your API key consumer metadata, then
+branch on it in your rate limit function. This is the simplest approach and
+requires no external lookups.
+
+### Route-based limits
+
+Use `request.url` or `request.params` to apply different limits to different
+endpoints. For example, a search endpoint might allow 10 requests per minute
+while a read endpoint allows 100.
+
+```ts
+export function rateLimit(
+  request: ZuploRequest,
+  context: ZuploContext,
+  policyName: string,
+): CustomRateLimitDetails | undefined {
+  const isSearch = new URL(request.url).pathname.includes("/search");
+
+  return {
+    key: request.user.sub,
+    requestsAllowed: isSearch ? 10 : 100,
+    timeWindowMinutes: 1,
+  };
+}
+```
+
+### Method-based limits
+
+Apply different limits to read operations (GET) vs. write operations (POST, PUT,
+DELETE). Write-heavy endpoints often need tighter limits to protect backends:
+
+```ts
+export function rateLimit(
+  request: ZuploRequest,
+  context: ZuploContext,
+  policyName: string,
+): CustomRateLimitDetails | undefined {
+  const isWrite = ["POST", "PUT", "DELETE", "PATCH"].includes(request.method);
+
+  return {
+    key: request.user.sub,
+    requestsAllowed: isWrite ? 20 : 200,
+    timeWindowMinutes: 1,
+  };
+}
+```
+
+### Database-driven limits
+
+For limits that change frequently or are managed outside your gateway
+configuration, look them up from a database at request time. Use the
+[ZoneCache](../programmable-api/zone-cache.mdx) to avoid hitting the database on
+every request.
+
+See
+[Per-user rate limiting with a database](./per-user-rate-limits-using-db.mdx)
+for a complete example using Supabase and ZoneCache.
+
+### Skip rate limiting for specific requests
+
+Return `undefined` to bypass rate limiting entirely. This is useful for health
+checks, internal services, or admin users:
+
+```ts
+export function rateLimit(
+  request: ZuploRequest,
+  context: ZuploContext,
+  policyName: string,
+): CustomRateLimitDetails | undefined {
+  if (request.user.data.role === "admin") {
+    return undefined;
+  }
+
+  return {
+    key: request.user.sub,
+    requestsAllowed: 100,
+    timeWindowMinutes: 1,
+  };
+}
+```
+
+## Testing
+
+To verify that dynamic limits are applied correctly, create API key consumers
+with different metadata values (for example, one with
+`{"customerType": "premium"}` and one with `{"customerType": "free"}`).
+
+Make requests with each key until you receive a `429 Too Many Requests`
+response. For example, with a free-tier key limited to 50 requests per minute:
+
+```bash
+# Replace with your API URL and key
+for i in $(seq 1 55); do
+  curl -s -o /dev/null -w "%{http_code}\n" \
+    -H "Authorization: Bearer YOUR_API_KEY" \
+    https://your-api.zuplo.dev/your-route
+done
+```
+
+The first 50 requests return `200`. Requests 51-55 return `429` with a
+`Retry-After` header. Repeat with the premium key and confirm the higher limit
+applies.
+
+:::tip
+
+Rate limit counters are per-environment. Preview and development environments
+have their own counters separate from production, so testing does not affect
+production limits.
+
+:::
+
+## Related resources
+
+- [How rate limiting works](./how-it-works.md) — Full explanation of
+  `rateLimitBy` modes and configuration options
+- [Rate Limiting policy reference](../policies/rate-limit-inbound.mdx)
+- [Per-user rate limiting with a database](./per-user-rate-limits-using-db.mdx)
+  — Advanced example with database lookups and caching