zuplo 6.67.32 → 6.68.0

package/docs/concepts/rate-limiting.md

@@ -0,0 +1,246 @@
+---
+title: Rate Limiting
+---
+
+Rate limiting controls how many requests a client can make to your API within a
+given time window. It protects your backend from traffic spikes, enforces fair
+usage across consumers, and enables tiered access for different customer plans.
+
+Zuplo's rate limiter uses a **sliding window algorithm** enforced globally
+across all edge locations. When a client exceeds the limit, they receive a
+`429 Too Many Requests` response with a `retry-after` header indicating when
+they can retry.
+
+## Rate limiting policies
+
+Zuplo provides two rate limiting policies, each suited to different levels of
+complexity.
+
+### Rate Limiting policy
+
+The [Rate Limiting policy](../policies/rate-limit-inbound.mdx) enforces a single
+request counter per time window. Configure a maximum number of requests, a time
+window, and how to identify callers.
+
+```json
+{
+  "name": "my-rate-limit-policy",
+  "policyType": "rate-limit-inbound",
+  "handler": {
+    "export": "RateLimitInboundPolicy",
+    "module": "$import(@zuplo/runtime)",
+    "options": {
+      "rateLimitBy": "user",
+      "requestsAllowed": 100,
+      "timeWindowMinutes": 1
+    }
+  }
+}
+```
+
+Use this policy when you need a straightforward "X requests per Y minutes"
+limit.
+
+### 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
+      }
+    }
+  }
+}
+```
+
+You can override counter increments programmatically per request using
+`ComplexRateLimitInboundPolicy.setIncrements()`. This is useful for usage-based
+pricing where different endpoints consume different amounts of a resource (for
+example, counting compute units or tokens instead of raw requests).
+
+## Choosing a policy
+
+| Scenario                                               | Policy                                        |
+| ------------------------------------------------------ | --------------------------------------------- |
+| Fixed requests-per-minute limit for all callers        | Rate Limiting                                 |
+| Different limits per customer tier (free vs. paid)     | Rate Limiting with a custom function          |
+| Counting multiple resources (requests + compute units) | Complex Rate Limiting                         |
+| Usage-based billing with variable cost per request     | Complex Rate Limiting with dynamic increments |
+
+## How `rateLimitBy` works
+
+The `rateLimitBy` option determines how the rate limiter groups requests into
+buckets. Both policies 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.
+
+### `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.
+
+### `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`.
+
+This mode enables dynamic rate limiting where limits vary based on customer
+tier, route parameters, or any other request property.
+
+### `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.
+
+## Dynamic rate limiting with custom functions
+
+When `rateLimitBy` is set to `"function"`, you provide a TypeScript module that
+determines the rate limit at request time. The function signature is:
+
+```ts
+import {
+  CustomRateLimitDetails,
+  ZuploContext,
+  ZuploRequest,
+} from "@zuplo/runtime";
+
+export function rateLimit(
+  request: ZuploRequest,
+  context: ZuploContext,
+  policyName: string,
+): CustomRateLimitDetails | undefined {
+  const user = request.user;
+
+  if (user.data.customerType === "premium") {
+    return {
+      key: user.sub,
+      requestsAllowed: 1000,
+      timeWindowMinutes: 1,
+    };
+  }
+
+  return {
+    key: user.sub,
+    requestsAllowed: 50,
+    timeWindowMinutes: 1,
+  };
+}
+```
+
+The `CustomRateLimitDetails` object has the following properties:
+
+- `key` - The string used to group requests into rate limit buckets
+- `requestsAllowed` (optional) - Overrides the policy's `requestsAllowed` value
+- `timeWindowMinutes` (optional) - Overrides the policy's `timeWindowMinutes`
+  value
+
+Returning `undefined` skips rate limiting for that request entirely.
+
+The function can also be `async` if you need to look up limits from a database
+or external service. See
+[Per-user rate limiting using a database](../articles/per-user-rate-limits-using-db.mdx)
+for a complete example using the ZoneCache for performance.
+
+Wire the function into the policy configuration using the `identifier` option:
+
+```json
+{
+  "export": "RateLimitInboundPolicy",
+  "module": "$import(@zuplo/runtime)",
+  "options": {
+    "rateLimitBy": "function",
+    "requestsAllowed": 50,
+    "timeWindowMinutes": 1,
+    "identifier": {
+      "export": "rateLimit",
+      "module": "$import(./modules/rate-limit)"
+    }
+  }
+}
+```
+
+:::note
+
+The `requestsAllowed` and `timeWindowMinutes` values in the policy configuration
+serve as defaults. The custom function can override them per request.
+
+:::
+
+## Combining rate limiting with authentication
+
+Rate limiting works best when combined with authentication so that limits apply
+per consumer rather than per IP. A typical policy pipeline is:
+
+1. **Authentication** (e.g., API Key Authentication) -- validates credentials
+   and populates `request.user`
+2. **Rate Limiting** with `rateLimitBy: "user"` -- enforces per-consumer limits
+   using `request.user.sub`
+
+With API key authentication, the consumer's metadata (stored when creating the
+key) is available at `request.user.data`. A custom rate limit function can read
+fields like `customerType` or `plan` from the metadata to apply tiered limits.
+
+## Rate limiting and monetization
+
+If you use Zuplo's
+[Monetization](../articles/monetization/monetization-policy.md) feature, the
+monetization policy handles quota enforcement based on subscription plans. You
+can still add a rate limiting policy after the monetization policy to provide
+per-second or per-minute spike protection on top of monthly billing quotas.
+These serve different purposes:
+
+- **Monetization quotas** enforce monthly or billing-period usage limits tied to
+  a subscription plan
+- **Rate limiting** protects against short-duration traffic spikes that could
+  overwhelm your backend
+
+## Combining multiple rate limit policies
+
+You can apply multiple rate limiting policies to the same route. For example,
+you might enforce both a per-minute and a per-hour limit. When using multiple
+policies, apply the longest time window first, followed by shorter durations.
+
+## 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
+- `mode` - Set to `"strict"` (default) for synchronous enforcement, or `"async"`
+  for non-blocking checks that may allow some requests over the limit
+- `throwOnFailure` - Set to `true` to return an error if the rate limit service
+  is unreachable, or `false` (default) to allow the request through
+
+## Related resources
+
+- [Rate Limiting policy reference](../policies/rate-limit-inbound.mdx)
+- [Complex Rate Limiting policy reference](../policies/complex-rate-limit-inbound.mdx)
+- [Dynamic Rate Limiting tutorial](../articles/step-5-dynamic-rate-limiting.mdx)
+- [Per-user rate limiting with a database](../articles/per-user-rate-limits-using-db.mdx)
+- [Quota policy](../policies/quota-inbound.mdx)
+- [Monetization policy](../articles/monetization/monetization-policy.md)

package/docs/concepts/request-lifecycle.mdx

@@ -0,0 +1,56 @@
+---
+title: Request Lifecycle
+---
+
+Every request that reaches Zuplo passes through a well-defined pipeline of
+stages. Click any stage below to learn what it does, when to use it, and find
+relevant documentation.
+
+<RequestLifecycle />
+
+## Short-circuiting
+
+At several stages, the pipeline can be short-circuited by returning a `Response`
+instead of passing the request through:
+
+- **[Pre-routing hooks](../programmable-api/runtime-extensions.mdx)** can return
+  a `Response` to skip routing entirely
+- **[Request hooks](../programmable-api/hooks.mdx)** can return a `Response` to
+  skip policies and the handler
+- **[Inbound policies](../articles/policies.mdx)** can return a `Response`
+  (e.g., 401 Unauthorized) to skip the handler and outbound policies
+
+This is how [authentication policies](./authentication.mdx) work: they check
+credentials and return an error response if the request is not authorized,
+preventing it from reaching your backend.
+
+## Choosing the right extension point
+
+**Use a [policy](../articles/policies.mdx)** when you need reusable logic that
+applies to multiple routes. Policies are configured per-route in your
+[OpenAPI spec](../articles/openapi.mdx) and can be shared across any number of
+routes. Examples: [authentication](./authentication.mdx),
+[rate limiting](../policies/rate-limit-inbound.mdx),
+[request validation](../policies/request-validation-inbound.mdx),
+[header manipulation](../policies/set-headers-inbound.mdx).
+
+**Use a [handler](../handlers/custom-handler.mdx)** when you need to define the
+core behavior of a route -
+[forwarding to a backend](../handlers/url-forward.mdx), generating a response,
+or implementing business logic. Each route has exactly one handler.
+
+**Use a [hook](../programmable-api/hooks.mdx)** when you need logic that runs on
+every request globally, regardless of route. Examples: adding correlation IDs,
+security headers, [logging](../articles/logging.mdx), analytics.
+
+| I want to...                  | Use                                                            |
+| ----------------------------- | -------------------------------------------------------------- |
+| Authenticate requests         | [Inbound policy](./authentication.mdx)                         |
+| Rate limit requests           | [Inbound policy](../policies/rate-limit-inbound.mdx)           |
+| Validate request bodies       | [Inbound policy](../policies/request-validation-inbound.mdx)   |
+| Forward to a backend          | [URL Forward Handler](../handlers/url-forward.mdx)             |
+| Return custom responses       | [Function Handler](../handlers/custom-handler.mdx)             |
+| Transform response bodies     | [Outbound policy](../policies/transform-body-outbound.mdx)     |
+| Add headers to all responses  | [Response hook](../programmable-api/hooks.mdx)                 |
+| Log every request             | [Response final hook](../programmable-api/hooks.mdx)           |
+| Normalize URLs before routing | [Pre-routing hook](../programmable-api/runtime-extensions.mdx) |

package/docs/concepts/source-control-and-deployment.mdx

@@ -0,0 +1,229 @@
+---
+title: Source Control and Deployment
+---
+
+Zuplo uses a GitOps model where your API configuration lives in source control
+and deployments happen automatically when you push code. This page explains how
+the working copy, source control, branches, environments, and deployment options
+fit together.
+
+## Working copy
+
+Every developer gets a personal **working copy** environment when they use the
+Zuplo Portal. The working copy is a cloud-hosted development environment that
+deploys instantly when you save a file. You can think of it as your personal
+cloud sandbox.
+
+Working copy environments use a `.dev` URL (for example,
+`my-project-abc123.zuplo.dev`) and are optimized for rapid iteration rather than
+production traffic.
+
+:::note
+
+Working copy environments are available on the managed edge deployment model.
+For managed dedicated deployments, use
+[local development](../articles/local-development.mdx) instead.
+
+:::
+
+### Before connecting source control
+
+When you first create a project, your working copy is standalone. You can edit
+files in the portal, and Zuplo saves them. There is no Git repository involved
+yet. This is fine for prototyping and exploring Zuplo, but for team
+collaboration and production deployments you need source control.
+
+### After connecting source control
+
+When you connect a Git repository, the portal gains push/pull capabilities. You
+can commit your working copy changes to Git and pull changes from teammates.
+Your working copy becomes a personal branch-like workspace layered on top of the
+repository.
+
+## Connecting source control
+
+Zuplo supports four Git providers: GitHub, GitLab, Bitbucket, and Azure DevOps.
+The integration has two parts, and which parts you get depends on your provider.
+
+| Capability            | GitHub | GitLab           | Bitbucket        | Azure DevOps     |
+| --------------------- | ------ | ---------------- | ---------------- | ---------------- |
+| Portal push/pull      | Yes    | Yes (Enterprise) | Yes (Enterprise) | Yes (Enterprise) |
+| Automatic deployments | Yes    | No -- use CLI    | No -- use CLI    | No -- use CLI    |
+
+**GitHub** provides the most complete experience with both portal integration
+and automatic deployments on every push.
+
+**GitLab, Bitbucket, and Azure DevOps** provide portal integration for pushing
+and pulling code but do **not** include automatic deployments. You must set up
+CI/CD pipelines that call the Zuplo CLI to deploy. See
+[Custom CI/CD](../articles/custom-ci-cd.mdx) for details.
+
+## Branch to environment mapping
+
+Every Git branch maps to a Zuplo environment. The repository's default branch
+(typically `main`) maps to the **Production** environment. Every other branch
+maps to a **Preview** environment.
+
+<Diagram height="h-80">
+  <DiagramGroup id="git" label="Git Repository">
+    <DiagramNode id="main" variant="green">
+      main (default branch)
+    </DiagramNode>
+    <DiagramNode id="staging">staging</DiagramNode>
+    <DiagramNode id="feature">feature/auth</DiagramNode>
+  </DiagramGroup>
+  <DiagramGroup id="zuplo" label="Zuplo Environments">
+    <DiagramNode id="prod" variant="green">
+      Production
+    </DiagramNode>
+    <DiagramNode id="preview-staging" variant="blue">
+      Preview (staging)
+    </DiagramNode>
+    <DiagramNode id="preview-feature" variant="blue">
+      Preview (feature/auth)
+    </DiagramNode>
+  </DiagramGroup>
+  <DiagramEdge from="main" to="prod" />
+  <DiagramEdge from="staging" to="preview-staging" />
+  <DiagramEdge from="feature" to="preview-feature" />
+</Diagram>
+
+The environment name matches the branch name. For example, pushing to a branch
+called `staging` creates an environment named `staging` with a URL like
+`https://my-project-staging-abc1234.zuplo.app`.
+
+:::tip
+
+There is **no technical difference** between Production and Preview
+environments. Both run on the same infrastructure with identical performance
+characteristics. The distinction controls which set of
+[environment variables](../articles/environment-variables.mdx) and
+[API key buckets](../articles/api-key-buckets.mdx) apply by default. Some teams
+use Preview environments to serve production traffic for different regions or
+tenants.
+
+:::
+
+For full details on branch-based deployments, see
+[Branch-Based Deployments](../articles/branch-based-deployments.mdx).
+
+## Deployment options
+
+Zuplo offers two ways to deploy your API: the built-in GitHub integration and
+the Zuplo CLI.
+
+### GitHub integration (automatic)
+
+With GitHub connected, every push to any branch triggers an automatic
+deployment. Push to `main` and your Production environment updates within
+seconds. Push to a feature branch and a Preview environment is created or
+updated automatically.
+
+This is the recommended setup for most teams. No CI/CD configuration is
+required.
+
+**[Set up GitHub integration](../articles/source-control-setup-github.mdx)**
+
+### CLI deployment (for all other providers)
+
+For GitLab, Bitbucket, Azure DevOps, or any other Git provider, use the Zuplo
+CLI in your CI/CD pipeline to deploy.
+
+```bash
+npx zuplo deploy --api-key $ZUPLO_API_KEY
+```
+
+:::warning
+
+GitLab, Bitbucket, and Azure DevOps do **not** have built-in automatic
+deployments. You **must** configure CI/CD pipelines that run `zuplo deploy` to
+deploy your API. Without this, pushing code to your repository does not trigger
+a deployment.
+
+:::
+
+See the provider-specific CI/CD guides:
+
+- [GitLab CI/CD](../articles/custom-ci-cd-gitlab.mdx)
+- [Bitbucket Pipelines](../articles/custom-ci-cd-bitbucket.mdx)
+- [Azure DevOps Pipelines](../articles/custom-ci-cd-azure.mdx)
+- [CircleCI](../articles/custom-ci-cd-circleci.mdx)
+
+## CLI deploy and environment naming
+
+When you run `zuplo deploy`, the CLI determines the environment name using the
+following logic:
+
+1. If you pass `--environment my-env`, the CLI uses `my-env` as the environment
+   name.
+2. If you do not pass `--environment`, the CLI uses the **current Git branch
+   name** as the environment name.
+
+This means in a typical CI/CD pipeline, the deploy command automatically names
+the environment after the branch being built without any extra configuration.
+
+```bash
+# On the "staging" branch, this creates/updates the "staging" environment
+npx zuplo deploy --api-key $ZUPLO_API_KEY
+
+# Override the environment name explicitly
+npx zuplo deploy --api-key $ZUPLO_API_KEY --environment production
+```
+
+For full CLI deploy reference, see [CLI: deploy](../cli/deploy.mdx).
+
+## Environment URLs
+
+Each environment gets a unique URL based on the project name, environment name,
+and a unique identifier:
+
+| Environment  | Example URL                                    |
+| ------------ | ---------------------------------------------- |
+| Production   | `https://my-project-main-abc1234.zuplo.app`    |
+| Preview      | `https://my-project-staging-def5678.zuplo.app` |
+| Working Copy | `https://my-project-abc123.zuplo.dev`          |
+
+Production and Preview environments use the `.zuplo.app` domain. Working copy
+environments use the `.zuplo.dev` domain. You can configure
+[custom domains](../articles/custom-domains.mdx) for any non-working-copy
+environment.
+
+## Putting it all together
+
+The typical workflow from development to production looks like this:
+
+<Diagram direction="vertical" height="h-96">
+  <DiagramNode id="develop" variant="blue">
+    Develop (local or working copy)
+  </DiagramNode>
+  <DiagramNode id="push">Push to feature branch</DiagramNode>
+  <DiagramNode id="preview" variant="orange">
+    Preview environment deployed
+  </DiagramNode>
+  <DiagramNode id="merge">Merge to main</DiagramNode>
+  <DiagramNode id="production" variant="green">
+    Production environment updated
+  </DiagramNode>
+  <DiagramEdge from="develop" to="push" />
+  <DiagramEdge from="push" to="preview" />
+  <DiagramEdge from="preview" to="merge" />
+  <DiagramEdge from="merge" to="production" />
+</Diagram>
+
+1. **Develop** locally with `zuplo dev` or in the portal working copy.
+2. **Push** your changes to a feature branch. If using GitHub, a Preview
+   environment deploys automatically. If using another provider, your CI/CD
+   pipeline runs `zuplo deploy`.
+3. **Test** against the Preview environment URL.
+4. **Merge** to the default branch. The Production environment updates
+   automatically (GitHub) or via your CI/CD pipeline (other providers).
+
+## Next steps
+
+- [Environments](../articles/environments.mdx) -- Environment types and
+  configuration
+- [Source Control & Deployments](../articles/source-control.mdx) -- Provider
+  setup guides
+- [Custom CI/CD](../articles/custom-ci-cd.mdx) -- Build your own deployment
+  pipeline
+- [CLI: deploy](../cli/deploy.mdx) -- Full CLI deploy reference

package/docs/conferences/conference-prize-terms.mdx

@@ -0,0 +1,80 @@
+---
+title: Conference Prize Terms
+---
+
+1. By entering the prize draw you are agreeing to these prize draw terms and
+   conditions.
+2. The prize draw is being run by Zuplo, Inc.
+
+## Eligibility to enter
+
+3. The prize draw is open to entrants over 18 years of age and who are
+   registered and attending the conference in-person on the standard
+   presentation days (for example, excluding and days of workshops, etc.).
+   Ticketed attendees and speakers are eligible to enter. Exhibitors, sponsors,
+   and conference staff are **not** eligible.
+4. In entering the prize draw, you confirm that you are eligible to do so and
+   eligible to claim any prize you may win.
+5. A maximum of one entry per individual per day is permitted. Limit of one
+   prize per family during the conference.
+6. The prize draw is free to enter.
+
+## How to enter
+
+7. The prize draw will include those attendees who complete the project that's
+   shared at the booth and return to the Zuplo booth to show the completed
+   quickstart to the booth staff. Entries must be received 15 minutes before the
+   scheduled drawing. Entries after that time and date won't be included in the
+   draw.
+8. Zuplo won't accept responsibility if contact details provided are incomplete
+   or inaccurate.
+
+## The prize
+
+10. The prize will be a Lego kit (one of those on display at the booth).
+11. Zuplo's use of particular brands as prizes doesn't imply any affiliation
+    with or endorsement of such brands.
+12. The winner will be drawn at random.
+13. The prize is non-exchangeable, non-transferable and no cash alternatives
+    will be offered.
+14. We reserve the right to substitute prizes with another prize of equal or
+    higher value if circumstances beyond our control make it necessary to do so.
+15. The decision of Zuplo regarding any aspect of the prize draw is final and
+    binding and no correspondence will be entered into about it.
+
+## Winner announcement
+
+16. The winner for each day will be announced at the end of the day (6:00 PM on
+    Wednesday, 4:05 PM on Thursday)
+17. The winner must be present at the time of the announcement to receive the
+    prize or another winner will be selected.
+
+## Data protection and publicity
+
+18. You consent to any personal information you provide in entering the prize
+    draw being used by Zuplo for the purposes of administering the prize draw,
+    and for those purposes as defined within our privacy notice.
+19. All entrants may apply for details of the winning participant by contacting
+    us at whatzup@zuplo.com
+20. The winner agrees to the release of their first name and place of work to
+    any other prize draw participants if requested via Zuplo.
+21. An announcement of the winner's first name and place of work will be made
+    via Zuplo's website and social media.
+22. All personal information shall be used in accordance with Zuplo's Privacy
+    Policy.
+
+## Limitation of Liability
+
+23. Zuplo doesn't accept any liability for any damage, loss, injury or
+    disappointment suffered by any entrants as a result of either participating
+    in the prize draw or being selected for a prize, save that Zuplo doesn't
+    exclude its liability for death or personal injury as a result of its own
+    negligence.
+24. Zuplo doesn't provide any form of practical or IT support for this prize. On
+    receipt, all responsibilities relating to warranty and the product are that
+    of the prize winner.
+
+## General
+
+25. Zuplo reserves the right to cancel the prize draw or amend these terms and
+    conditions at any time, without prior notice.