zuplo 6.67.32 → 6.68.0

package/docs/articles/monorepo-deployment.mdx

@@ -0,0 +1,350 @@
+---
+title: Deploying Zuplo from a Monorepo
+sidebar_label: Monorepo Deployment
+description:
+  "Deploy a Zuplo API gateway from a monorepo subdirectory using the Zuplo CLI
+  and GitHub Actions."
+---
+
+If your Zuplo API gateway lives inside a monorepo alongside other services, you
+can deploy it using the [Zuplo CLI](../cli/overview.mdx) and your CI/CD
+provider. Zuplo's
+[built-in GitHub integration](./source-control-setup-github.mdx) connects each
+project to a dedicated repository and deploys automatically on every push.
+Because it doesn't natively support projects located in a subdirectory, you need
+to use the Zuplo CLI with a [custom CI/CD pipeline](./custom-ci-cd.mdx) to
+deploy from the correct directory.
+
+This guide covers the project structure requirements, CI/CD configuration, local
+development, and common troubleshooting steps for monorepo setups.
+
+## Project structure
+
+A monorepo with a Zuplo project in a subdirectory typically looks like this:
+
+```text
+my-monorepo/
+├── apps/
+│   ├── web/                  # Frontend application
+│   └── backend/              # Backend service
+├── packages/
+│   └── api-gateway/          # Zuplo project
+│       ├── config/
+│       │   ├── routes.oas.json
+│       │   └── policies.json
+│       ├── modules/          # Custom TypeScript handlers and policies
+│       ├── tests/            # API tests
+│       ├── zuplo.jsonc
+│       └── package.json
+├── package.json              # Root package.json (workspaces)
+└── ...
+```
+
+The Zuplo subdirectory must contain these files at minimum:
+
+- **`zuplo.jsonc`** — Project configuration including `version`,
+  `compatibilityDate`, and `projectType`
+- **`package.json`** — Dependencies (must include `zuplo` as a dependency)
+- **`config/routes.oas.json`** — Route definitions in OpenAPI format
+- **`config/policies.json`** — Policy configuration
+
+The `config/policies.json` file must be valid JSON with a `policies` array. Each
+policy entry requires a `name`, `policyType`, and a `handler` object with
+`export`, `module`, and `options` fields. Here's an example:
+
+```json title="config/policies.json"
+{
+  "policies": [
+    {
+      "name": "my-rate-limit-inbound-policy",
+      "policyType": "rate-limit-inbound",
+      "handler": {
+        "export": "RateLimitInboundPolicy",
+        "module": "$import(@zuplo/runtime)",
+        "options": {
+          "rateLimitBy": "ip",
+          "requestsAllowed": 100,
+          "timeWindowMinutes": 1
+        }
+      }
+    }
+  ]
+}
+```
+
+:::caution
+
+Every policy in `policies.json` must include the `handler` block with `export`,
+`module`, and `options`. Omitting the `handler` block causes schema validation
+errors during `zuplo deploy`.
+
+:::
+
+## GitHub Actions configuration
+
+The key to deploying from a subdirectory is setting `working-directory` on your
+job steps so the Zuplo CLI runs in the correct folder.
+
+### Basic deployment
+
+```yaml title=".github/workflows/deploy.yaml"
+name: Deploy Zuplo API
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "packages/api-gateway/**"
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: packages/api-gateway
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Deploy to Zuplo
+        run: npx zuplo deploy --api-key "$ZUPLO_API_KEY"
+        env:
+          ZUPLO_API_KEY: ${{ secrets.ZUPLO_API_KEY }}
+```
+
+This workflow:
+
+1. Triggers only when files in the Zuplo subdirectory change (via the `paths`
+   filter)
+2. Sets `working-directory` at the job level so every `run` step executes inside
+   the Zuplo project folder
+3. Installs dependencies and deploys using the Zuplo CLI
+
+:::tip
+
+Set `working-directory` at the `defaults.run` level of the job rather than on
+each individual step. This avoids accidentally running CLI commands from the
+repository root.
+
+:::
+
+### PR preview environments
+
+For preview deployments on pull requests, combine `working-directory` with
+environment cleanup:
+
+```yaml title=".github/workflows/pr-preview.yaml"
+name: PR Preview
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, closed]
+    paths:
+      - "packages/api-gateway/**"
+
+jobs:
+  deploy:
+    if: github.event.action != 'closed'
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: packages/api-gateway
+    env:
+      ZUPLO_API_KEY: ${{ secrets.ZUPLO_API_KEY }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Deploy to Zuplo
+        id: deploy
+        shell: bash
+        run: |
+          OUTPUT=$(npx zuplo deploy --api-key "$ZUPLO_API_KEY" 2>&1)
+          echo "$OUTPUT"
+          DEPLOYMENT_URL=$(echo "$OUTPUT" | grep -oP 'Deployed to \K(https://[^ ]+)')
+          echo "url=$DEPLOYMENT_URL" >> $GITHUB_OUTPUT
+
+      - name: Comment PR with deployment URL
+        uses: actions/github-script@v7
+        with:
+          script: |
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: `🚀 Deployed to: ${{ steps.deploy.outputs.url }}`
+            })
+
+  cleanup:
+    if: github.event.action == 'closed'
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: packages/api-gateway
+    env:
+      ZUPLO_API_KEY: ${{ secrets.ZUPLO_API_KEY }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Delete environment
+        run: |
+          BRANCH_NAME="${{ github.head_ref }}"
+          ENV_NAME="${BRANCH_NAME//\//-}"
+          npx zuplo delete \
+            --environment "$ENV_NAME" \
+            --api-key "$ZUPLO_API_KEY" \
+            --wait
+```
+
+### Secrets and environment variables
+
+Store your Zuplo API key as a GitHub Actions secret:
+
+1. Go to [portal.zuplo.com](https://portal.zuplo.com) and navigate to your
+   account **Settings** > **API Keys**
+2. Copy the API key
+3. In your GitHub repository, go to **Settings** > **Secrets and variables** >
+   **Actions**
+4. Create a secret named `ZUPLO_API_KEY`
+
+For more details on CI/CD authentication, see the
+[Custom CI/CD](./custom-ci-cd.mdx) guide.
+
+:::note
+
+The examples above use GitHub Actions. If you use GitLab, Bitbucket, Azure
+DevOps, or CircleCI, the same principles apply — set the working directory to
+your Zuplo subdirectory and run `npx zuplo deploy`. See the provider-specific
+guides under [Custom CI/CD Pipelines](./custom-ci-cd.mdx) for detailed workflow
+examples.
+
+:::
+
+## Local development
+
+To run local development from a monorepo subdirectory, navigate to the Zuplo
+project folder and start the development server:
+
+```bash
+cd packages/api-gateway
+npm install
+npx zuplo dev
+```
+
+The `zuplo dev` command looks for `zuplo.jsonc` and the `config/` directory in
+the current working directory. Running it from the repository root instead of
+the Zuplo subdirectory causes resolution errors.
+
+If you use npm or pnpm workspaces, you can add a script to your root
+`package.json` to run local development from the workspace:
+
+```json title="Root package.json"
+{
+  "scripts": {
+    "dev:api-gateway": "npm -w packages/api-gateway run dev"
+  }
+}
+```
+
+For troubleshooting local development issues, see the
+[local development troubleshooting guide](./local-development-troubleshooting.mdx).
+
+## Troubleshooting
+
+### Schema validation errors in policies.json
+
+**Error**: `zuplo deploy` exits with code 1 and reports schema validation
+errors.
+
+This typically happens when `policies.json` is missing required fields. Every
+policy entry must include the full `handler` object:
+
+```json
+{
+  "name": "my-policy",
+  "policyType": "rate-limit-inbound",
+  "handler": {
+    "export": "RateLimitInboundPolicy",
+    "module": "$import(@zuplo/runtime)",
+    "options": {}
+  }
+}
+```
+
+**Common causes:**
+
+- Missing the `handler` block entirely
+- Missing `export` or `module` inside the `handler` block
+- Using an invalid `policyType` value
+
+### "Could not resolve .zuplo/worker.ts"
+
+**Error**: `npx zuplo dev` fails with "Could not resolve .zuplo/worker.ts".
+
+This error occurs when the CLI can't locate the project files. Verify that:
+
+- You're running the command from the Zuplo project directory (not the monorepo
+  root)
+- The `zuplo.jsonc` file exists in the current directory
+- Dependencies are installed (`npm install`)
+
+### Deployment health check timeouts
+
+**Error**: The build succeeds but the deployment fails with a health check
+timeout.
+
+After the CLI builds and uploads your project, Zuplo runs a health check against
+the deployed environment. Timeouts can indicate:
+
+- **Invalid route configuration** — Check `config/routes.oas.json` for syntax
+  errors or invalid handler references
+- **Missing modules** — Verify that any custom handler modules referenced in
+  `routes.oas.json` or `policies.json` exist in the `modules/` directory
+- **Missing environment variables** — If your policies or handlers reference
+  environment variables with `$env(VAR_NAME)`, make sure those variables are
+  configured in the Zuplo portal under your project's
+  [environment variables](./environment-variables.mdx)
+
+### Build succeeds but deploy fails
+
+If `npm install` and the build step complete successfully but `zuplo deploy`
+fails:
+
+- Confirm your `ZUPLO_API_KEY` is set correctly in your CI/CD secrets
+- Verify the project is correctly linked by running `npx zuplo link` or by
+  passing explicit `--project` and `--account` flags to `zuplo deploy`
+- Check that `working-directory` points to the correct subdirectory in your
+  workflow file
+
+## Next steps
+
+Once your monorepo deployment is working, consider these follow-up tasks:
+
+- **Set up branch-based environments** for staging and production with
+  [Branch-Based Deployments](./branch-based-deployments.mdx)
+- **Add API tests** to your CI pipeline using the patterns in
+  [Custom CI/CD Pipelines](./custom-ci-cd.mdx)
+- **Explore the full CLI** for additional commands in the
+  [Zuplo CLI Reference](../cli/overview.mdx)
+- **Configure local development** to work alongside your other services with
+  [Local Development](./local-development.mdx)

package/docs/articles/multiple-auth-policies.mdx

@@ -0,0 +1,81 @@
+---
+title: Handling Multiple Authentication Policies
+sidebar_label: Multiple Auth Policies
+description:
+  Learn how to configure multiple authentication methods like JWT and API Key on
+  a single API route in Zuplo.
+tags:
+  - authentication
+---
+
+Sometimes multiple types of authentication are needed on an API. For example, an
+API could support JWT Authentication and API Key authentication or two different
+OAuth providers (for example Azure AD for employees and Auth0 for partners).
+Configuring multiple policies in Zuplo can be done in several ways.
+
+## JWT and API Key Authentication
+
+JWT and API Key authentication can be handled by adding three policies to a
+route (or using [composite policies](../policies/composite-inbound.mdx) to keep
+everything organized). The three policies required are:
+
+1. [API Key Authentication Policy](../policies/api-key-inbound.mdx)
+1. [Any JWT Authentication Policy](../policies/open-id-jwt-auth-inbound.mdx)
+1. [A Custom Policy](../policies/custom-code-inbound.mdx)
+
+:::warning
+
+The order of these policies is critical. Placing them in the wrong order can
+cause errors or lead to security issues.
+
+:::
+
+All of the Zuplo built-in authentication policies have an option called
+`allowUnauthenticatedRequests`. This option is `true` by default, meaning for an
+anonymous request, the policy will immediately return a response with a 401:
+Unauthorized status. **In the case of multiple policies, this setting must be
+`false`.** This means that even if the request isn't authenticated, the policy
+will still let the request through.
+
+:::tip
+
+The option `allowUnauthenticatedRequests` can also be used to make a route work
+for both authenticated and anonymous users. Allowing unauthenticated requests on
+a public API allows modifying behaviors based on the type of user. For example,
+rate limits could be set higher for authenticated users.
+
+:::
+
+In the route that handles multiple authentication policies, add the API Key
+Authentication policy and the JWT Authentication policy of your choice (for
+example Auth0, Okta, Cognito, etc.). For both policies, set the option
+`allowUnauthenticatedRequests` to `true`.
+
+Configure the other options as usual.
+
+Finally, if the route **requires** authentication, a third policy is necessary
+to enforce that after both authentication policies run, the request has been
+authenticated. Generally, this policy would come immediately **after** the two
+authentication policies.
+
+To enforce authentication, check that the value of `request.user.sub` is as
+expected. Additional checks can be added as your API requires. Below is an
+example of a simple authentication check policy.
+
+```ts
+import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+export default async function (request: ZuploRequest, context: ZuploContext) {
+  if (!request.user?.sub) {
+    return new Response("Unauthorized", { status: 401 });
+  }
+}
+```
+
+### Multiple JWT Authentication Policies
+
+Multiple JWT authentication policies is slightly more challenging than adding
+JWT and API key authentication because JWT authentication performs validation on
+the token value. In some cases, the easiest approach is to write a custom policy
+that checks the issuer of the token first then applies validation appropriate
+for each issuer.

package/docs/articles/non-standard-ports.mdx

@@ -0,0 +1,30 @@
+---
+title: Non-Standard Ports
+description:
+  Learn how to make requests to non-standard ports in Zuplo with compatibility
+  dates 2024-09-02 or later.
+tags:
+  - deployment
+  - request-handling
+---
+
+Zuplo supports making requests to non-standard ports when your runtime is
+configured with a
+[compatibility date](../programmable-api/compatibility-dates.mdx) of
+[2024-09-02](../programmable-api/compatibility-dates.mdx#2024-09-02) or later.
+
+## Making a Request to a Non-Supported Port
+
+Making requests to non-standard ports can be done using the built in handlers or
+`fetch` API. Simply set the URL to use the port, for example
+`http://example.com:8080`.
+
+```ts
+const response = await fetch("http://example.com:8080");
+```
+
+## Older Compatibility Dates
+
+Before [2024-09-02](../programmable-api/compatibility-dates.mdx#2024-09-02),
+Zuplo didn't support making requests to non-standard ports. If you make a
+request to a non-standard port on an older runtime, the port will be ignored.

package/docs/articles/oauth-authentication.mdx

@@ -0,0 +1,54 @@
+---
+title: OAuth Authentication
+---
+
+Zuplo comes with build-in and extensible OAuth policies out of the box. These
+policies allow you to easily authenticate requests using popular services like
+Auth0, AWS Cognito, and more.
+
+Some of the built-in policies are listed below.
+
+- [OpenId JWT Authentication Policy](../policies/open-id-jwt-auth-inbound.mdx)
+- [Auth0 JWT Authentication Policy](../policies/auth0-jwt-auth-inbound.mdx)
+- [Okta JWT Authentication Policy](../policies/okta-jwt-auth-inbound.mdx)
+- [AWS Cognito JWT Authentication Policy](../policies/cognito-jwt-auth-inbound.mdx)
+
+## Request User
+
+The OAuth policies will validate and decode the incoming JWT and add the data
+from the JWT. If the user is successfully authenticated the claims of their JWT
+`access_token` will be available on the `request.user` object.
+
+The user's identifier (also known as the `sub` or subject) is available on the
+`request.user.sub` property. Other claims can be found on the
+`request.user.data` object as demonstrated below.
+
+```ts
+async function (request: ZuploRequest, context: ZuploContext) {
+  // Log the user's sub
+  context.log.debug(`User ${request.user.sub} is authenticated`)
+
+  // Check a custom claim
+  if (request.user.data["orgId"] === "1234") {
+    // do something
+  }
+}
+```
+
+## Authorization Header
+
+The built-in policies will validate the incoming JWT on the Authorization
+header. By default, the Authorization header will be left on the request and
+forwarded on to your backend.
+
+It isn't recommended to validate the Access Token on both the gateway and the
+backend. However, by forwarding the header to the backend you can transition
+your API from doing authentication on your backend to authorizing at the
+Gateway. See
+[this blog post](https://zuplo.com/blog/2023/07/16/zero-downtime-api-auth-migration)
+for more details.
+
+If you would like to remove the authorization header after you use one of the
+authorization policies, simply add the
+[Remove Request Headers](/docs/policies/remove-headers-inbound) policy after the
+authorization policy and set it to remove the `Authorization` header.

package/docs/articles/openapi-server-urls.mdx

@@ -0,0 +1,60 @@
+---
+title: OpenAPI Server URLs in Zuplo
+sidebar_label: OpenAPI Server URLs
+description:
+  Learn how Zuplo automatically manages server URLs in OpenAPI specs across
+  environments and custom domains.
+tags:
+  - openapi
+  - deployment
+---
+
+When working with OpenAPI specifications in Zuplo, it's important to understand
+how server URLs are handled across different environments.
+
+## Automatic Server URL Overwriting
+
+Zuplo automatically overwrites the server URLs in your OpenAPI specification
+files with the URL of the current environment. This automatic behavior ensures
+that:
+
+- You don't need to manually update server URLs when creating new branches
+- Each environment uses its correct API endpoint
+- The developer portal always displays the appropriate URL for that environment
+
+## Default Behavior
+
+By default, every Zuplo environment receives its own unique API URL in the
+format:
+
+```
+https://[environment-name].zuplo.app
+```
+
+This URL is automatically reflected in:
+
+- The OpenAPI specification file
+- The developer portal for that environment
+- All API documentation
+
+## Custom Domains
+
+If you need to use a [custom domain](./custom-domains.mdx) instead of the
+default Zuplo URL, you can configure one on a per-environment basis. When a
+custom domain is configured:
+
+- The OpenAPI server URL will show your custom domain (for example,
+  `developer-dev.accuweather.com`)
+- The developer portal will display the custom domain
+- All documentation will reflect the custom domain URL
+
+## Important Considerations
+
+- The server URL specified in your original OpenAPI file is never used directly
+- Each environment maintains its own server URL configuration
+- Changes to custom domains require configuration through Zuplo support or the
+  API
+- Cache invalidation may be needed when switching from direct Zuplo URLs to
+  custom domains served through CDNs
+
+For assistance with custom domain configuration, please contact Zuplo support.