zuplo 6.67.32 → 6.68.0

package/docs/articles/api-key-react-component.mdx

@@ -0,0 +1,90 @@
+---
+title: API Key Manager React Component
+sidebar_label: React Component
+---
+
+Zuplo provides an open source react component that can be used on your own UI to
+provider users with self-serve access to API Keys for your Zuplo powered API.
+
+![Component Screenshot](../../public/media/api-key-react-component/cedd8ad0-9433-4433-80f6-86545ba0d41a.png)
+
+To see a demo of the component visit https://api-key-manager.com.
+
+## Getting Started
+
+This component can be used with any React framework. It's compatible with
+Tailwind CSS, but Tailwind isn't required.
+
+:::tip
+
+See our blog for an
+[end to end tutorial](https://zuplo.com/blog/2023/08/08/open-source-release) on
+using this React component and the translation API.
+
+:::
+
+### Install
+
+Install the component in your React project
+
+```bash
+npm install @zuplo/react-api-key-manager
+```
+
+### With Tailwind
+
+Import the component's stylesheet into your `global.css` or equivalent file. The
+styles will use your project's tailwind configuration to provide a consistent
+theme.
+
+```css
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+@import "@zuplo/react-api-key-manager/tailwind.css";
+```
+
+### Without Tailwind
+
+Import the component's stylesheet into your root component (for example,
+`App.jsx`), typically below your other stylesheets.
+
+```jsx
+import "./styles/globals.css";
+import "@zuplo/react-api-key-manager/index.css";
+```
+
+### Custom Styles
+
+The component's CSS can be completely customized by copying either the
+`tailwind.css` or `index.css` files from
+`node_modules/@zuplo/react-api-key-manager/dist/` and modifying the styles to
+suite your needs.
+
+## Usage
+
+You can import the `ReactAPIKeyManager` into your React project directly.
+
+```ts
+import {
+  ApiKeyManager,
+  DefaultApiKeyManagerProvider,
+} from "@zuplo/react-api-key-manager";
+
+const MyComponent = () => {
+  const defaultProvider = new DefaultApiKeyManagerProvider(
+    "<BASE_URL>",
+    "<ACCESS_TOKEN>"
+  );
+
+  return <ApiKeyManager provider={provider} />;
+};
+```
+
+## Backend API
+
+The API Key Manager component interacts with an API that allows authorized users
+to manage their own keys. The easiest way to get started is to use the
+[Auth Translation API](https://github.com/zuplo/sample-auth-translation-api)
+sample and deploy it to [Zuplo](https://zuplo.com). By default this sample
+connects the [Zuplo API Key Management Service](./api-key-management.mdx).

package/docs/articles/api-key-service-limits.mdx

@@ -0,0 +1,14 @@
+---
+title: Service Limits
+---
+
+Zuplo's API Key Service can handle billions of requests and tokens. The service
+can accommodate even virtually any scale required. However, by default the
+service is set with limits to ensure that each Zuplo customer has a performant
+and reliable experience.
+
+For customers who need limits beyond what's set in this document, reach out to
+our sales team and we'll be happy to design a plan that fits your needs. Email
+[sales@zuplo.com](mailto:sales@zuplo.com).
+
+For more details see [Zuplo Platform Limits](./limits.mdx).

package/docs/articles/archiving-requests-to-storage.mdx

@@ -0,0 +1,119 @@
+---
+title: Archiving requests to storage
+sidebar_label: "Archiving Requests"
+description:
+  Learn how to archive incoming request text bodies to Azure Blob Storage using
+  custom policies in Zuplo.
+tags:
+  - request-handling
+  - observability
+---
+
+> Note - this sample uses Policies, read [this guide](../policies) first.
+
+In this sample, we'll show how you can archive the text body of incoming
+requests to Azure Blob Storage. We also have a post on
+[Archiving to AWS S3 Storage](https://zuplo.com/blog/2022/03/22/custom-policies-in-code-archiving-requests-to-s3).
+
+First, let's set up Azure. You'll need a container in Azure storage
+([docs](https://learn.microsoft.com/en-us/azure/storage/common/storage-account-create?tabs=azure-portal)).
+Once you have your container you'll need the URL - click the **Properties** tab
+of your container as shown below.
+
+![Azure](../../public/media/guides/archiving-requests-to-storage/Untitled.png)
+
+This URL will be the `blobPath` in our policy options.
+
+Next, we'll need a SAS (Shared Access Secret) to authenticate with Azure. You
+can generate one of these on the `Shared access tokens` tab.
+
+Note, you should minimize the permissions - and select only the `Create`
+permission. Choose a sensible start and expiration time for your token. Note, we
+don't recommend restricting IP addresses because Zuplo runs at the edge in over
+200 data-centers world-wide.
+
+![shared access tokens](../../public/media/guides/archiving-requests-to-storage/Untitled_1.png)
+
+Then generate your SAS token - copy the token (not the URL) to the clipboard and
+enter it into a new environment variable in your API called `BLOB_CREATE_SAS`.
+You'll need another environment variable called `BLOB_CONTAINER_PATH`.
+
+![Zuplo portal](../../public/media/guides/archiving-requests-to-storage/Untitled_2.png)
+
+> Note - production customers should talk to a Zuplo representative to get help
+> managing their secure keys.
+
+We'll write a policy called `request-archive-policy` that can be used on all
+routes.
+
+```ts title="file-archive-policy.ts"
+import { ZuploRequest, ZuploContext } from "@zuplo/runtime";
+
+export type RequestArchivePolicyOptions = {
+  blobContainerPath: string;
+  blobCreateSas: string;
+};
+
+export default async function (
+  request: ZuploRequest,
+  context: ZuploContext,
+  options: RequestArchivePolicyOptions,
+) {
+  // because we will read the body, we need to
+  // create a clone of this request first, otherwise
+  // there may be two attempts to read the body
+  // causing a runtime error
+  const clone = request.clone();
+  const body = await clone.text();
+
+  // let's generate a unique blob name based on the date and requestId
+  const blobName = `${Date.now()}-${request.requestId}.req.txt`;
+
+  const url = `${options.blobContainerPath}/${blobName}?${options.blobCreateSas}`;
+
+  const result = await fetch(url, {
+    method: "PUT",
+    body: body,
+    headers: {
+      "x-ms-blob-type": "BlockBlob",
+    },
+  });
+
+  if (result.status > 201) {
+    const err = {
+      message: `Error archiving file`,
+      status: result.status,
+      body: await result.text(),
+    };
+    request.logger.error(err);
+  }
+
+  // continue
+  return request;
+}
+```
+
+Finally, you need to configure your policies.json file to include the policy,
+example below:
+
+```json
+{
+  "name": "request-archive-policy",
+  "policyType": "code-policy",
+  "handler": {
+    "export": "default",
+    "module": "$import(./modules/archive-request-policy)",
+    "options": {
+      "blobCreateSas": "$env(BLOB_CREATE_SAS)",
+      "blobContainerPath": "$env(BLOB_CONTAINER_PATH)"
+    }
+  }
+}
+```
+
+Don't forget to reference the `file-archive-policy` in the policies.inbound
+property of your routes.
+
+Here's the policy in action:
+
+![Archive request policy in action](../../public/media/guides/archiving-requests-to-storage/2021-11-21_22.51.33.gif)

package/docs/articles/branch-based-deployments.mdx

@@ -0,0 +1,184 @@
+---
+title: Branch-Based Deployments
+sidebar_label: Branch-Based Deployments
+---
+
+Zuplo uses a branch-based deployment model that automatically maps Git branches
+to environments. This GitOps approach allows teams to manage API deployments
+using familiar version control workflows.
+
+## How Branch-Based Deployments Work
+
+When you connect your Zuplo project to a Git repository (GitHub, GitLab,
+Bitbucket, or Azure DevOps), Zuplo automatically deploys your API whenever
+changes are pushed to a branch. The deployment model follows these rules:
+
+1. **One branch = One environment**: Each Git branch creates a corresponding
+   Zuplo environment
+2. **Default branch = Production**: The repository's default branch (typically
+   `main` or `master`) deploys to the **Production** environment
+3. **All other branches = Preview**: Any branch that's not the default branch
+   deploys to a **Preview** environment
+
+```
+Git Repository                    Zuplo Environments
+─────────────────                 ──────────────────
+main          ─────────────────►  Production (main)
+staging       ─────────────────►  Preview (staging)
+feature/auth  ─────────────────►  Preview (feature/auth)
+bugfix/123    ─────────────────►  Preview (bugfix/123)
+```
+
+## Environment Names and URLs
+
+When Zuplo deploys an environment from a branch, the environment name matches
+the branch name. For example:
+
+| Branch Name    | Environment Name | Example URL                                         |
+| -------------- | ---------------- | --------------------------------------------------- |
+| `main`         | main             | `https://my-project-main-abc1234.zuplo.app`         |
+| `staging`      | staging          | `https://my-project-staging-def5678.zuplo.app`      |
+| `feature/auth` | feature/auth     | `https://my-project-feature-auth-ghi9012.zuplo.app` |
+
+:::note
+
+The environment URL includes a unique identifier to ensure each deployment has a
+distinct address. Configure [custom domains](./custom-domains.mdx) for your
+environments.
+
+:::
+
+## Production vs Preview Environments
+
+### What Determines the Production Environment
+
+The **Production** environment is determined by your repository's **default
+branch** setting. This is configured in your Git provider (GitHub, GitLab,
+etc.), not in Zuplo. When you change your repository's default branch, Zuplo
+automatically treats the new default branch as Production.
+
+To change which branch is your Production environment:
+
+1. Go to your Git repository settings (for example, GitHub > Settings >
+   General > Default branch)
+2. Change the default branch to your desired branch
+3. Zuplo will now treat deployments from this branch as Production
+
+### Technical Differences
+
+There is **no technical difference** between Production and Preview
+environments. Both:
+
+- Have identical performance characteristics
+- Support all Zuplo features
+- Run on the same infrastructure
+
+The distinction is primarily for:
+
+- **Environment variable management**: You can set different values for
+  Production vs Preview environments
+- **API key buckets**: Production and Preview environments use separate API key
+  buckets by default
+- **Organization**: Helps teams distinguish between live and test deployments
+
+### Using Preview Environments as Production
+
+Some customers choose to use Preview environments as additional "production"
+deployments. For example, you might have:
+
+- `main` → Production (US customers)
+- `eu-production` → Preview, but serving EU customers
+- `staging` → Preview for testing
+
+This works because Preview environments have identical capabilities to
+Production. You can override
+[environment variables](./environment-variables.mdx) and
+[API key buckets](./api-key-buckets.mdx) for specific Preview environments to
+support this pattern.
+
+## Creating New Environments
+
+Creating a new environment is as simple as creating a new Git branch:
+
+```bash
+# Create and push a new branch
+git checkout -b my-new-feature
+git push -u origin my-new-feature
+```
+
+Within seconds, Zuplo deploys a new environment named `my-new-feature`. You can
+see the new environment in the Zuplo portal's environment selector.
+
+## Deleting Environments
+
+When you delete a branch in your Git repository, the corresponding Zuplo
+environment is **not automatically deleted**. To delete an environment:
+
+1. Go to the Zuplo portal
+2. Navigate to **Settings** > **Environments**
+3. Select the environment and delete it
+
+Alternatively, use the [Zuplo CLI](../cli/delete.mdx):
+
+```bash
+npx zuplo delete --url https://your-environment-url.zuplo.app --api-key $ZUPLO_API_KEY
+```
+
+## Automatic Deployments on Push
+
+With the Git integration enabled, every push to a branch triggers an automatic
+deployment:
+
+1. **Push to default branch**: Updates the Production environment
+2. **Push to other branches**: Updates the corresponding Preview environment
+3. **Create new branch**: Creates a new Preview environment
+4. **Merge pull request**: Updates the target branch's environment
+
+This enables powerful GitOps workflows:
+
+- **Feature branches**: Each feature gets its own testable environment
+- **Pull request previews**: Review changes in a live environment before merging
+- **Protected branches**: Use branch protection rules to gate Production
+  deployments
+
+## Environment Variables Per Branch
+
+Environment variables can be scoped to specific environments:
+
+| Scope            | Description                                                |
+| ---------------- | ---------------------------------------------------------- |
+| Production       | Only applies to the Production environment                 |
+| Preview          | Applies to all Preview environments                        |
+| Specific Preview | Applies to a specific Preview environment (by branch name) |
+| Working Copy     | Only applies to development environments                   |
+
+See [Environment Variables](./environment-variables.mdx) for configuration
+details.
+
+## Switching the Production Branch
+
+If you need to change which branch serves as Production:
+
+1. **Update your Git repository's default branch**:
+   - GitHub: Settings > General > Default branch
+   - GitLab: Settings > Repository > Branch defaults
+   - Bitbucket: Repository settings > Branching model
+   - Azure DevOps: Project settings > Repositories > Default branch
+
+2. **Verify the change in Zuplo**: The environment deployed from your new
+   default branch will now be labeled as Production
+
+:::caution
+
+Changing the default branch affects which environment receives Production
+environment variables and uses the Production API key bucket. Plan this change
+carefully to avoid service disruption.
+
+:::
+
+## Next Steps
+
+- [Environments Overview](./environments.mdx) - Learn about environment types
+- [Source Control Integration](./source-control.mdx) - Set up Git integration
+- [Custom CI/CD Pipelines](./custom-ci-cd.mdx) - Build custom deployment
+  workflows

package/docs/articles/bypass-policy-for-testing.mdx

@@ -0,0 +1,117 @@
+---
+title: Bypass a Policy for Testing
+sidebar_label: Bypass a Policy
+description:
+  Learn how to bypass policies for testing and debugging using API key metadata
+  or custom policies in Zuplo.
+tags:
+  - testing
+  - authentication
+  - custom-code
+---
+
+There are times when you need to bypass a policy for purposes such as testing,
+debugging, writing health checks, etc. This guide will show you a few ways to
+bypass a policy.
+
+## Bypass a Policy Using a Test API Key
+
+If you are using Zuplo API Key Authentication and want to create a test API Key
+that can bypass a policy, you can quickly do so by using the API Key metadata
+and a custom policy.
+
+### Step 1: Create a Custom Policy
+
+The
+[Custom Code Inbound Policy](../policies/custom-code-inbound.mdx#writing-a-policy)
+is essentially a wrapper around whatever policy you want to bypass. In this
+example, we will create a custom policy that bypasses the `monetization-inbound`
+policy.
+
+This policy first checks for the presence of a `testApiKey` flag in the user's
+`data` (which is the API Key metadata). If the flag is present, the policy
+returns the request as is. Otherwise, it invokes the `monetization-inbound`
+policy using the `invokeInboundPolicy` method on the `ZuploContext` object.
+
+Create the custom policy configuration in the `policies.json` file.
+
+```json title="config/policies.json"
+{
+    "policies": [{
+    {
+      "name": "monetization-with-bypass-inbound",
+      "policyType": "custom-code-inbound",
+      "handler": {
+        "export": "default",
+        "module": "$import(./modules/monetization-with-bypass)",
+        "options": {
+          "config1": "YOUR_VALUE",
+          "config2": true
+        }
+      },
+    }
+  }]
+}
+```
+
+Create a new module for the policy code.
+
+```ts title="modules/monetization-with-bypass.ts"
+import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+export default async function policy(
+  request: ZuploRequest,
+  context: ZuploContext,
+) {
+  if (request.user.data.testApiKey === true) {
+    context.log.info("Bypassing monetization-inbound policy for testing.");
+    return request;
+  }
+
+  return context.invokeInboundPolicy("monetization-inbound", request);
+}
+```
+
+### Step 2: Replace the Monetization Policy with the Custom Policy
+
+Wherever you use the `monetization-inbound` policy, replace it with the custom
+the custom policy.
+
+```json title="config/routes.oas.json"
+"x-zuplo-route": {
+  "corsPolicy": "none",
+  "handler": {
+    "export": "default",
+    "module": "$import(./modules/todos-and-users)",
+    "options": {}
+  },
+  "policies": {
+    "inbound": ["monetization-with-bypass-inbound"]
+  }
+}
+```
+
+### Step 3: Create a Test API Key
+
+To create a test API Key, navigate to **Services** in your Zuplo Project. Select
+the API Key Bucket you want to use and click **Create Consumer**. Enter a name
+for the consumer. Set the metadata to include the `testApiKey` flag as shown
+below.
+
+![Test API Key](../../public/media/bypass-policy-for-testing/image.png)
+
+Now when you call the API with the test API Key, the `monetization-inbound`
+policy will be bypassed.
+
+## Use a JWT Token Claim
+
+In the above example, we used the API Key metadata to bypass the policy.
+However, if you are using JWT authentication, you can follow the same principle
+by adding a custom claim to the JWT token. Many providers, like
+[Auth0](https://auth0.com/docs/secure/tokens/json-web-tokens/create-custom-claims),
+allow you to add custom claims to the JWT token.
+
+The claims for a JWT token are added to the `request.user.data` object when you
+use one of the Zuplo JWT Authentication policies. So you can use the same code
+as the previous API Token example, by adding a custom `testApiKey` claim to the
+JWT token.

package/docs/articles/check-ip-address.mdx

@@ -0,0 +1,17 @@
+---
+title: How to check an incoming IP address
+sidebar_label: "Check IP Address"
+description:
+  Learn how to access the true client IP address of requests using the
+  true-client-ip header.
+tags:
+  - request-handling
+  - deployment
+---
+
+Sometimes you want to access the true IP address of the gateway's client making
+the current request. To do this you can read the `true-client-ip` header:
+
+```ts
+const ip = request.headers.get("true-client-ip");
+```

package/docs/articles/ci-cd-azure/basic-deployment.mdx

@@ -0,0 +1,49 @@
+---
+title: "Azure Pipelines: Basic Deployment"
+sidebar_label: Basic Deployment
+---
+
+The simplest pipeline deploys your API to Zuplo on every push to main.
+
+```yaml title="azure-pipelines.yml"
+trigger:
+  - main
+
+pool:
+  vmImage: ubuntu-latest
+
+steps:
+  - task: NodeTool@0
+    inputs:
+      versionSpec: "20.x"
+    displayName: "Install Node.js"
+
+  - script: npm install
+    displayName: "Install dependencies"
+
+  - script: npx zuplo deploy --api-key $(ZUPLO_API_KEY)
+    displayName: "Deploy to Zuplo"
+```
+
+This pipeline:
+
+1. Triggers on pushes to the `main` branch
+2. Sets up Node.js 20
+3. Installs dependencies
+4. Deploys to Zuplo using the branch name as the environment name
+
+## Adding the API Key
+
+Add `ZUPLO_API_KEY` as a pipeline variable:
+
+1. Edit your pipeline in Azure DevOps
+2. Click **Variables**
+3. Add `ZUPLO_API_KEY` with your API key
+4. Check **Keep this value secret**
+
+Or use a variable group for sharing across pipelines.
+
+## Next Steps
+
+- Add [testing after deployment](./deploy-and-test.mdx)
+- Set up [PR preview environments](./pr-preview-environments.mdx)

package/docs/articles/ci-cd-azure/deploy-and-test.mdx

@@ -0,0 +1,47 @@
+---
+title: "Azure Pipelines: Deploy and Test"
+sidebar_label: Deploy and Test
+---
+
+Run your test suite against the deployed environment to validate changes.
+
+```yaml title="azure-pipelines.yml"
+trigger:
+  - main
+
+pr:
+  - main
+
+pool:
+  vmImage: ubuntu-latest
+
+steps:
+  - task: NodeTool@0
+    inputs:
+      versionSpec: "20.x"
+    displayName: "Install Node.js"
+
+  - script: npm install
+    displayName: "Install dependencies"
+
+  - script: |
+      set -o pipefail
+      npx zuplo deploy --api-key $(ZUPLO_API_KEY) 2>&1 | tee ./DEPLOYMENT_STDOUT
+    displayName: "Deploy to Zuplo"
+
+  - script: |
+      DEPLOYMENT_URL=$(grep -oP 'Deployed to \K(https://[^ ]+)' ./DEPLOYMENT_STDOUT)
+      npx zuplo test --endpoint "$DEPLOYMENT_URL"
+    displayName: "Run tests"
+```
+
+This pipeline:
+
+1. Deploys to Zuplo and captures the output
+2. Extracts the deployment URL from the output
+3. Runs tests against the deployed environment
+
+## Next Steps
+
+- Add [PR preview environments](./pr-preview-environments.mdx) with cleanup
+- Run [local tests](./local-testing.mdx) before deploying

package/docs/articles/ci-cd-azure/local-testing.mdx

@@ -0,0 +1,59 @@
+---
+title: "Azure Pipelines: Local Testing in CI"
+sidebar_label: Local Testing in CI
+---
+
+Test against a local Zuplo server before deploying anywhere.
+
+```yaml title="azure-pipelines.yml"
+trigger:
+  - main
+
+pool:
+  vmImage: ubuntu-latest
+
+stages:
+  - stage: LocalTest
+    displayName: "Local Testing"
+    jobs:
+      - job: Test
+        steps:
+          - task: NodeTool@0
+            inputs:
+              versionSpec: "20.x"
+            displayName: "Install Node.js"
+
+          - script: npm install
+            displayName: "Install dependencies"
+
+          - script: |
+              npx zuplo dev &
+              DEV_PID=$!
+              sleep 10
+              npx zuplo test --endpoint http://localhost:9000
+              kill $DEV_PID
+            displayName: "Start local server and run tests"
+
+  - stage: Deploy
+    displayName: "Deploy to Zuplo"
+    dependsOn: LocalTest
+    condition:
+      and(succeeded(), eq(variables['Build.SourceBranch'], 'refs/heads/main'))
+    jobs:
+      - job: Deploy
+        steps:
+          - task: NodeTool@0
+            inputs:
+              versionSpec: "20.x"
+
+          - script: npm install
+
+          - script: npx zuplo deploy --api-key $(ZUPLO_API_KEY)
+            displayName: "Deploy to Zuplo"
+```
+
+Local tests run first. Only if they pass does deployment proceed.
+
+## Next Steps
+
+- Add [multi-stage deployment](./multi-stage-deployment.mdx) with staging