zuplo 6.70.69 → 6.70.71

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).

package/docs/rate-limiting/how-it-works.md

@@ -0,0 +1,225 @@
+---
+title: How rate limiting works
+sidebar_label: How it works
+description:
+  Understand Zuplo's sliding window rate limiter — how requests are counted,
+  what each rateLimitBy mode does, the Complex Rate Limiting policy, and every
+  configuration option.
+---
+
+This page covers the mechanics behind Zuplo's rate limiter: how requests are
+counted, what each `rateLimitBy` mode does in detail, and every configuration
+option available. If you just want to add a rate limit to your API, start with
+the [Getting Started guide](./getting-started.mdx) instead — this page is the
+deep dive you can read alongside or after it.
+
+Zuplo's rate limiter uses a **sliding window algorithm** enforced globally
+across all edge locations. Unlike a fixed window algorithm (which resets
+counters at fixed intervals and can allow bursts at window boundaries), the
+sliding window continuously tracks requests over a rolling time period. This
+produces smoother, more predictable throttling behavior.
+
+## Key terms
+
+A few terms show up repeatedly in the rate limiting docs. They are related but
+not interchangeable.
+
+- **Counter (or bucket)** — The running tally Zuplo keeps for a single caller
+  and a single policy. Each unique combination of policy `name` and caller
+  identifier gets its own counter. Two different policies tracking the same
+  caller do _not_ share a counter; two different callers under the same policy
+  do not share a counter either.
+- **Rate limit key** — The string value that identifies a caller for bucketing.
+  For `rateLimitBy: "ip"` the key is the client's IP address; for `"user"` it is
+  `request.user.sub`; for `"function"` it is whatever your custom function
+  returns as `CustomRateLimitDetails.key`; for `"all"` there is a single
+  implicit key shared by every request to the route.
+- **`identifier` option** — A field in the policy's configuration that points
+  Zuplo at your custom TypeScript function when `rateLimitBy` is `"function"`.
+  Zuplo calls that function on each request, and the function returns a
+  `CustomRateLimitDetails` object whose `key` property becomes the rate limit
+  key. In short: `identifier` is _where the function lives_; `key` is _what the
+  function returns_.
+
+## How `rateLimitBy` works
+
+The `rateLimitBy` option determines how the rate limiter groups requests into
+buckets. Both the standard
+[Rate Limiting policy](../policies/rate-limit-inbound.mdx) and the
+[Complex Rate Limiting policy](../policies/complex-rate-limit-inbound.mdx)
+support the same four modes.
+
+### `ip`
+
+Groups requests by the client's IP address. No authentication is required. This
+is the simplest option and works well for public APIs or as a first layer of
+protection.
+
+:::caution
+
+Multiple clients behind the same corporate proxy, cloud NAT, or shared Wi-Fi
+network can share a single IP address. In these cases, IP-based rate limiting
+can unfairly throttle unrelated users. For authenticated APIs, prefer
+`rateLimitBy: "user"` instead.
+
+:::
+
+### `user`
+
+Groups requests by the authenticated user's identity (`request.user.sub`). When
+using [API key authentication](../articles/api-key-authentication.mdx), the
+`sub` value is the consumer name you assigned when creating the API key. When
+using JWT authentication, it comes from the token's `sub` claim.
+
+This is the recommended mode for authenticated APIs because it ties limits to
+the actual consumer rather than a shared IP address.
+
+:::note
+
+The `user` mode requires an authentication policy (such as API key or JWT
+authentication) earlier in the policy pipeline. If no authenticated user is
+present on the request, the policy returns an error. See
+[Getting Started §5](./getting-started.mdx#5-rate-limit-authenticated-users) for
+a full authenticated pipeline example.
+
+:::
+
+### `function`
+
+Groups requests using a custom TypeScript function that you provide. The
+function returns a `CustomRateLimitDetails` object containing a grouping key
+and, optionally, overridden values for `requestsAllowed` and
+`timeWindowMinutes`. See
+[Custom rate limit functions](#custom-rate-limit-functions) below for the
+function signature and field reference.
+
+### `all`
+
+Applies a single shared counter across all requests to the route, regardless of
+who makes them. Use this for global rate limits on endpoints that call
+resource-constrained backends.
+
+## Custom rate limit functions
+
+When `rateLimitBy` is set to `"function"`, Zuplo calls a TypeScript function you
+provide on every request. The function receives the request, context, and policy
+name, and returns a `CustomRateLimitDetails` object describing how to count that
+request.
+
+```ts
+import {
+  CustomRateLimitDetails,
+  ZuploContext,
+  ZuploRequest,
+} from "@zuplo/runtime";
+
+export function rateLimit(
+  request: ZuploRequest,
+  context: ZuploContext,
+  policyName: string,
+): CustomRateLimitDetails | undefined {
+  return {
+    key: request.user.sub,
+    requestsAllowed: 100,
+    timeWindowMinutes: 1,
+  };
+}
+```
+
+### `CustomRateLimitDetails`
+
+- `key` (required) — The string used to group requests into rate limit buckets.
+- `requestsAllowed` (optional) — Overrides the policy's `requestsAllowed` value
+  for this request.
+- `timeWindowMinutes` (optional) — Overrides the policy's `timeWindowMinutes`
+  value for this request.
+
+Returning `undefined` skips rate limiting for the request entirely — useful for
+health checks or privileged callers. The function can also be `async` if you
+need to await a database lookup or external service call.
+
+Wire the function into the policy using the `identifier` option. The policy's
+configured `requestsAllowed` and `timeWindowMinutes` serve as defaults; the
+function can override them per request.
+
+For concrete walkthroughs (tier-based, route-based, method-based,
+database-backed, selective bypass), see
+[Dynamic Rate Limiting](./dynamic-rate-limiting.mdx). For an advanced
+database-backed example with caching, see
+[Per-user rate limiting with a database](./per-user-rate-limits-using-db.mdx).
+
+## Additional options
+
+Both rate limiting policies support the following additional options:
+
+- `headerMode` — Set to `"retry-after"` (default) to include the `Retry-After`
+  header in 429 responses, or `"none"` to omit it. The `Retry-After` value is
+  returned as a number of seconds (delay-seconds format).
+- `mode` — Set to `"strict"` (default) or `"async"`. In **strict** mode, the
+  request is held until the rate limit check completes — the backend is never
+  called if the limit is exceeded. This adds some latency to every request
+  because the check hits a globally distributed rate limit service. In **async**
+  mode, the request proceeds to the backend in parallel with the rate limit
+  check. This minimizes added latency but means some requests may get through
+  even after the limit is exceeded. Async mode is a good fit when low latency
+  matters more than exact enforcement.
+- `throwOnFailure` — Controls behavior when the rate limit service is
+  unreachable. When set to `false` (default), requests are allowed through
+  (fail-open). When set to `true`, the policy returns an error to the client.
+  The fail-open default prevents a rate limit service outage from blocking all
+  traffic to your API.
+
+## Complex Rate Limiting policy
+
+The [Complex Rate Limiting policy](../policies/complex-rate-limit-inbound.mdx)
+supports **multiple named counters** in a single policy. Each counter tracks a
+different resource or unit of work.
+
+```json
+{
+  "name": "my-complex-rate-limit-policy",
+  "policyType": "complex-rate-limit-inbound",
+  "handler": {
+    "export": "ComplexRateLimitInboundPolicy",
+    "module": "$import(@zuplo/runtime)",
+    "options": {
+      "rateLimitBy": "user",
+      "timeWindowMinutes": 1,
+      "limits": {
+        "requests": 100,
+        "compute": 500
+      }
+    }
+  }
+}
+```
+
+Override counter increments programmatically per request with
+`ComplexRateLimitInboundPolicy.setIncrements()`. This suits usage-based pricing,
+where different endpoints consume different amounts of a resource (for example,
+counting compute units or tokens instead of raw requests).
+
+## Related resources
+
+**Go deeper on configuration:**
+
+- [Rate Limiting policy reference](../policies/rate-limit-inbound.mdx) — Every
+  option for the standard policy.
+- [Complex Rate Limiting policy reference](../policies/complex-rate-limit-inbound.mdx)
+  — Multi-counter limits for usage-based pricing (enterprise).
+
+**Learn by example:**
+
+- [Dynamic Rate Limiting](./dynamic-rate-limiting.mdx) — Tiered limits by
+  customer type.
+- [Per-user rate limiting with a database](./per-user-rate-limits-using-db.mdx)
+  — Look up limits at request time using ZoneCache and a database.
+
+**Combine with other policies:**
+
+- [Combining Policies](./combining-policies.mdx) — Stack multiple rate limits,
+  and pair rate limiting with quotas or monetization.
+- [Quota policy](../policies/quota-inbound.mdx) — Monthly or billing-period
+  usage caps.
+- [Monetization policy](../articles/monetization/monetization-policy.md) —
+  Subscription-based access control and metering.