zuplo 6.70.70 → 6.70.71

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

package/docs/rate-limiting/getting-started.mdx

@@ -0,0 +1,339 @@
+---
+title: Getting started with rate limiting
+sidebar_label: Getting started
+description:
+  Pick a rate limiting strategy and add it to an existing Zuplo project, with
+  hands-on examples for IP-based and authenticated per-user limits.
+---
+
+Rate limiting caps how many requests a client can make to your API within a time
+window. It protects your backend from traffic spikes, enforces fair usage across
+consumers, and supports tiered access for different customer plans. When a
+client exceeds the configured limit, they receive a `429 Too Many Requests`
+response with a `Retry-After` header indicating when they can retry.
+
+This guide walks you through picking a `rateLimitBy` strategy, adding the policy
+to a route, and testing it end to end. If you want the sliding window algorithm,
+every `rateLimitBy` mode in detail, and the full set of configuration levers,
+read [How Rate Limiting Works](./how-it-works.md) alongside or after this guide.
+
+## Choose an approach
+
+Pick a `rateLimitBy` mode based on what your API looks like today. If you are
+not sure, start from the first row that matches and follow the linked guide or
+section below.
+
+| Use case                                                    | `rateLimitBy` | Policy                                                                           | Learn more                                                                |
+| ----------------------------------------------------------- | ------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| Public API with no authentication                           | `ip`          | [Rate Limiting](../policies/rate-limit-inbound.mdx)                              | Follow the steps below                                                    |
+| Authenticated API, same limit for every consumer            | `user`        | [Rate Limiting](../policies/rate-limit-inbound.mdx)                              | [§5 Rate limit authenticated users](#5-rate-limit-authenticated-users)    |
+| Tiered limits (free, pro, enterprise) from API key metadata | `function`    | [Rate Limiting](../policies/rate-limit-inbound.mdx) with a custom function       | [Dynamic Rate Limiting](./dynamic-rate-limiting.mdx)                      |
+| Tiered limits sourced from a database                       | `function`    | [Rate Limiting](../policies/rate-limit-inbound.mdx) with a custom function       | [Per-user limits with a database](./per-user-rate-limits-using-db.mdx)    |
+| Single global cap on an expensive endpoint                  | `all`         | [Rate Limiting](../policies/rate-limit-inbound.mdx)                              | [How rate limiting works](./how-it-works.md#all)                          |
+| Usage-based pricing counting multiple resources per request | `user`        | [Complex Rate Limiting](../policies/complex-rate-limit-inbound.mdx) (enterprise) | [How rate limiting works](./how-it-works.md#complex-rate-limiting-policy) |
+
+:::note
+
+`rateLimitBy: "user"` requires an authentication policy (such as API key or JWT
+authentication) earlier in the route's policy pipeline. Without it, the rate
+limit policy has no user to group requests by and returns an error. Section 5
+below walks through the full authenticated setup.
+
+:::
+
+For a definition of `rateLimitBy`, the sliding window algorithm, and the full
+list of configuration options (`mode`, `headerMode`, `throwOnFailure`, and
+more), see [How Rate Limiting Works](./how-it-works.md).
+
+## Prerequisites
+
+- An existing Zuplo project with at least one route configured in
+  `config/routes.oas.json`.
+- The [Zuplo CLI](../cli/overview.mdx) installed, or access to the
+  [Zuplo Portal](https://portal.zuplo.com).
+- To test rate limiting locally, the project must be linked to a Zuplo
+  environment. Run `npx zuplo link` once in the project directory and select an
+  environment. Rate limiting uses a globally distributed counter service, so an
+  unlinked local project cannot enforce limits. See
+  [Connecting to Zuplo Services Locally](../articles/local-development-services.mdx)
+  for more detail.
+
+## 1. Add the policy
+
+Open `config/policies.json` and add a rate limiting policy to the `policies`
+array. This example limits each IP address to 2 requests per minute, which makes
+it easy to test.
+
+```json title="config/policies.json"
+{
+  "policies": [
+    {
+      "name": "rate-limit-inbound",
+      "policyType": "rate-limit-inbound",
+      "handler": {
+        "export": "RateLimitInboundPolicy",
+        "module": "$import(@zuplo/runtime)",
+        "options": {
+          "rateLimitBy": "ip",
+          "requestsAllowed": 2,
+          "timeWindowMinutes": 1
+        }
+      }
+    }
+  ]
+}
+```
+
+The key options are:
+
+- **`rateLimitBy`** -- How to group requests into rate limit buckets. `"ip"`
+  groups by the caller's IP address and requires no authentication.
+- **`requestsAllowed`** -- The maximum number of requests allowed in the time
+  window.
+- **`timeWindowMinutes`** -- The length of the sliding time window in minutes.
+
+:::tip
+
+If your project already has other policies in `config/policies.json`, add the
+rate limiting entry to the existing `policies` array rather than replacing it.
+
+:::
+
+:::warning
+
+The `name` field (`rate-limit-inbound` above) is what scopes the counter. Every
+route that references this exact name shares the same counter. If you later copy
+this policy block to create a second limit, change the `name` — a forgotten
+rename silently merges two unrelated limits into one. Policy names must also
+match exactly between `config/policies.json` and `config/routes.oas.json`; a
+typo there causes the policy to be skipped without any error. See
+[Counter scoping](./combining-policies.mdx#counter-scoping) for the full rules.
+
+:::
+
+## 2. Attach the policy to a route
+
+Open `config/routes.oas.json` and add the policy name to the `policies.inbound`
+array inside the `x-zuplo-route` object of the route you want to protect.
+
+```json title="config/routes.oas.json"
+{
+  "paths": {
+    "/my-route": {
+      "get": {
+        "operationId": "get-my-route",
+        "x-zuplo-route": {
+          "corsPolicy": "anything-goes",
+          "handler": {
+            "export": "urlForwardHandler",
+            "module": "$import(@zuplo/runtime)",
+            "options": {
+              "baseUrl": "https://api.example.com"
+            }
+          },
+          "policies": {
+            "inbound": ["rate-limit-inbound"]
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+The `"rate-limit-inbound"` string must match the `name` field from the policy
+you defined in `config/policies.json`. When a request hits this route, Zuplo
+runs each inbound policy in array order before forwarding to the handler.
+
+:::note
+
+You can attach the same policy to multiple routes. Add its name to the
+`policies.inbound` array on each route that needs rate limiting.
+
+:::
+
+## 3. Test the rate limit
+
+Start your local dev server (or deploy to a Zuplo environment) and send requests
+to the protected route. With the configuration above, the third request within a
+one-minute window returns a `429` response.
+
+```bash
+# Send three requests in quick succession
+for i in 1 2 3; do
+  echo "--- Request $i ---"
+  curl -s -w "\nHTTP Status: %{http_code}\n" http://localhost:9000/my-route
+done
+```
+
+The first two requests return a `200` response from your upstream service. The
+third request returns a `429 Too Many Requests` response in
+[Problem Details](https://httpproblems.com) format:
+
+```json
+{
+  "type": "https://httpproblems.com/http-status/429",
+  "title": "Too Many Requests",
+  "status": 429,
+  "detail": "Rate limit exceeded",
+  "instance": "/my-route",
+  "trace": {
+    "requestId": "4d54e4ee-c003-4d75-aba9-e09a6d707b08",
+    "timestamp": "2026-04-14T12:00:00.000Z",
+    "buildId": "ec44e831-3a02-467e-a26c-7e401e4473bf"
+  }
+}
+```
+
+The response also includes a `Retry-After` header with the number of seconds
+until the client can send another request (for example, `Retry-After: 42`).
+
+## 4. Choose production limits
+
+The `requestsAllowed: 2` value above exists so the limit triggers on your third
+curl. Production APIs need numbers that reflect real usage. There is no single
+right answer, but these reference points from widely used APIs are a useful
+starting point:
+
+| API     | Typical per-consumer limit                                 |
+| ------- | ---------------------------------------------------------- |
+| Stripe  | 100 read and 100 write requests per second per account     |
+| GitHub  | 5,000 authenticated requests per hour per user             |
+| Twilio  | 100 requests per second per account (varies by resource)   |
+| Shopify | 40 requests per app per store (bucket refills at 2/second) |
+
+When sizing your own limit, consider three inputs:
+
+- **What your backend can sustain.** Start from a conservative fraction of your
+  backend's measured capacity so that a single caller cannot exhaust it.
+- **What legitimate callers actually do.** If p99 usage for your best customers
+  is 10 requests per minute, a 100-per-minute limit leaves headroom without
+  being permissive.
+- **How your customers are structured.** Per-API-key limits usually give tighter
+  control than per-IP; a single corporate IP can hide dozens of real users.
+
+It is almost always easier to _raise_ a limit in response to a support ticket
+than to _lower_ one that customers have started relying on. When in doubt, start
+low, measure, and increase.
+
+## 5. Rate limit authenticated users
+
+IP-based limits are a good first layer but they penalize every user behind a
+shared NAT or corporate proxy. For an authenticated API, limit per consumer
+instead. This requires an authentication policy earlier in the pipeline so that
+`request.user` is populated before the rate limit policy runs.
+
+The full policies configuration looks like this:
+
+```json title="config/policies.json"
+{
+  "policies": [
+    {
+      "name": "api-key-auth",
+      "policyType": "api-key-inbound",
+      "handler": {
+        "export": "ApiKeyInboundPolicy",
+        "module": "$import(@zuplo/runtime)",
+        "options": {
+          "allowUnauthenticatedRequests": false
+        }
+      }
+    },
+    {
+      "name": "rate-limit-per-user",
+      "policyType": "rate-limit-inbound",
+      "handler": {
+        "export": "RateLimitInboundPolicy",
+        "module": "$import(@zuplo/runtime)",
+        "options": {
+          "rateLimitBy": "user",
+          "requestsAllowed": 60,
+          "timeWindowMinutes": 1
+        }
+      }
+    }
+  ]
+}
+```
+
+Attach both policies to the route, with authentication first so the rate limit
+policy has a user to group by:
+
+```json title="config/routes.oas.json (excerpt)"
+{
+  "x-zuplo-route": {
+    "policies": {
+      "inbound": ["api-key-auth", "rate-limit-per-user"]
+    }
+  }
+}
+```
+
+Create two API keys in the Zuplo Portal (or with the CLI) so you can verify that
+each consumer has its own counter. Then send requests with each key:
+
+```bash
+# Replace with the tokens from your two API keys.
+KEY_A="zpka_xxxxxxxxxxxxxxxxxxxxxx"
+KEY_B="zpka_yyyyyyyyyyyyyyyyyyyyyy"
+
+# Burn through the limit on key A; key B should still succeed.
+for i in $(seq 1 61); do
+  curl -s -o /dev/null -w "A #$i: %{http_code}\n" \
+    -H "Authorization: Bearer $KEY_A" \
+    http://localhost:9000/my-route
+done
+
+curl -s -w "\nB #1: %{http_code}\n" \
+  -H "Authorization: Bearer $KEY_B" \
+  http://localhost:9000/my-route
+```
+
+Requests 1–60 for key A return `200`, request 61 returns `429`, and the first
+request for key B still returns `200`. That confirms the counter is scoped to
+each consumer, not shared across the API key pool.
+
+:::note
+
+See [API Key Authentication](../articles/api-key-authentication.mdx) for the
+full walkthrough of creating and managing API keys. If you use JWT
+authentication instead, replace the `api-key-auth` policy with your JWT policy —
+the rate limit policy works the same way as long as `request.user.sub` is
+populated.
+
+:::
+
+## Next steps
+
+**Understand the mechanics:**
+
+- [How Rate Limiting Works](./how-it-works.md) — The sliding window algorithm,
+  every `rateLimitBy` mode in detail, and advanced options like `mode`,
+  `headerMode`, and `throwOnFailure`.
+
+**Customize the behavior:**
+
+- [Dynamic Rate Limiting](./dynamic-rate-limiting.mdx) — Vary limits per caller
+  using a custom TypeScript function (for example, higher limits for paid
+  plans).
+- [Per-user limits with a database](./per-user-rate-limits-using-db.mdx) — An
+  advanced example using ZoneCache and a database lookup to drive limits per
+  customer.
+
+**Combine with other policies:**
+
+- [Combining Policies](./combining-policies.mdx) — Stack per-minute and per-hour
+  limits, pair rate limiting with quotas, and layer in monetization.
+
+**Operate in production:**
+
+- [Monitoring and Troubleshooting](./monitoring-and-troubleshooting.mdx) —
+  Observe limits in production, alert on silent failures, and diagnose
+  unexpected 429s.
+
+**Reference:**
+
+- [Rate Limiting policy reference](../policies/rate-limit-inbound.mdx) — Every
+  configuration option for the standard policy.
+- [Complex Rate Limiting policy reference](../policies/complex-rate-limit-inbound.mdx)
+  — Multi-counter configuration for usage-based pricing (enterprise).