zuplo 6.67.32 → 6.68.0

package/docs/articles/tunnel-setup.mdx

@@ -0,0 +1,195 @@
+---
+title: Tunnel Setup & Use
+---
+
+<EnterpriseFeature name="Secure tunneling" />
+
+## Setting up Tunnels
+
+A tunnel is a way to expose your _internal services_ to the Zuplo gateway
+without exposing it to the public internet. Your Zuplo Gateway accesses those
+services through the `service://` protocol.
+
+The easiest way to deploy your tunnel is using a Docker container. The three
+basic requirements for deploying a secure tunnel with Docker are:
+
+1. A tunnel secret that's provided to the Docker container as an environment
+   variable named `TUNNEL_TOKEN` (the secret is provided by the Zuplo CLI when
+   you create the tunnel. See [creating a tunnel](../cli/tunnel-create.mdx))
+1. The ability for the tunnel service to make an outbound connection to the
+   public internet to establish the secure tunnel.
+1. The ability for the tunnel service to make a request to your internal API by
+   a DNS address. (for example `https://my-service.local/api`).
+
+The tunnel can run anywhere you can deploy a Docker container. Where you deploy
+depends on your specific setup. To run the Docker container on your own
+infrastructure, refer to instructions from your cloud provider or contact
+[Zuplo support](mailto:support@zuplo.com) for assistance.
+
+Below are a few option for deploying the tunnel.
+
+- [Deploying Docker containers on Azure](https://docs.microsoft.com/en-us/learn/modules/run-docker-with-azure-container-instances/)
+- [Deploying Docker containers on AWS ECS](https://docs.aws.amazon.com/AmazonECS/latest/userguide/getting-started.html)
+- [Deploying container images to GCP](https://cloud.google.com/compute/docs/containers/deploying-containers)
+
+The docker container is `zuplo/tunnel` and is available on
+[Docker Hub](https://hub.docker.com/r/zuplo/tunnel).
+
+Your running container needs a single environment variable named `TUNNEL_TOKEN`.
+You should store the value as a secret using the recommended means of secret
+storage and environment variable injection for your platform.
+
+## Configuring services
+
+Once you have created a tunnel, you can
+[configure which services](../cli/tunnel-services-update.mdx) it should expose
+using a configuration file. Below is a sample configuration file. The properties
+in the `services` objects are explained below.
+
+- `name` - This is the name of the service that you will use from your Zuplo
+  project
+- `endpoint` - This is the local endpoint of your service that you tunnel can
+  connect to
+- `configurations` - This object specifies which projects and which environments
+  can access this service.
+  - `project` - The name of the Zuplo project
+  - `accessibleBy` - The environments which can use the tunnel. Valid values are
+    `production`, `preview`, and `working-copy`.
+
+```json title="tunnel-config.json"
+{
+  "version": 1,
+  "services": [
+    {
+      "name": "my-awesome-service-prod",
+      "endpoint": "http://localhost:8000",
+      "configurations": [
+        {
+          "project": "my-project",
+          "accessibleBy": ["production"]
+        },
+        {
+          "project": "my-other-project",
+          "accessibleBy": ["production"]
+        }
+      ]
+    },
+    {
+      "name": "my-awesome-service-staging",
+      "endpoint": "http://localhost:9000",
+      "configurations": [
+        {
+          "project": "my-project",
+          "accessibleBy": ["preview", "working-copy"]
+        },
+        {
+          "project": "my-other-project",
+          "accessibleBy": ["preview", "working-copy"]
+        }
+      ]
+    }
+  ]
+}
+```
+
+```bash
+zuplo tunnel services update \
+--configuration-file <path-to-your-configuration-file> \
+--tunnel-id <your-tunnel-id>
+```
+
+## Using Services Exposed through Tunnels in Code
+
+Once set up, the services in the tunnels can be treated like any API host that
+you call from your Zuplo gateway. Each service exposed through tunnels is called
+with the URL schema `service://`, so if your service is named
+`my-awesome-service` you will call it using the URL
+`service://my-awesome-service`.
+
+This URL can be used in code as shown below.
+
+```ts
+import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+export default async function (request: ZuploRequest, context: ZuploContext) {
+  const response = await fetch("service://my-awesome-service/hello-world");
+  if (response.status > 399) {
+    return "It didn't work. :(";
+  } else {
+    return response;
+  }
+}
+```
+
+It's common to have multiple services for each of your internal environments.
+Each service can be restricted so that it's only accessible by specific Zuplo
+environments. For example, you might have two services one for production and
+one for staging.
+
+- `service://my-awesome-service-prod` (Production)
+- `service://my-awesome-service-staging` (Staging)
+
+## Using Services Exposed through Tunnels in Configuration
+
+Services can also be used in routes.oas.json file such as with the URL Rewrite
+handler. To call a tunnel service simply use it as part of the rewrite URL as
+shown in the image below.
+
+![Zuplo route handling](../../public/media/tunnel-setup/0c91be91-a591-4cef-ac29-d266e8a3181e.png)
+
+## Service Environment Variables
+
+When using these services in your code or configuration, it's often useful to
+store the values as an environment variable. This way you can change which
+environment calls which tunnel without changing code or configuration.
+
+For the production environment you would set the `BASE_SERVICE_URL` to the
+production service name. See
+[this document](../articles/environment-variables.mdx) for more about
+[Environment Variables](../articles/environment-variables.mdx)
+
+```text
+BASE_SERVICE_URL=service://my-awesome-service-prod
+```
+
+And for staging, you would use the staging service name.
+
+```text
+BASE_SERVICE_URL=service://my-awesome-service-staging
+```
+
+In your handler code or other configuration, the service can be accessed using
+the environment variable.
+
+```ts
+import { ZuploContext, ZuploRequest, environment } from "@zuplo/runtime";
+
+export default async function (request: ZuploRequest, context: ZuploContext) {
+  const response = await fetch(`${environment.BASE_SERVICE_URL}/hello-world`);
+  if (response.status > 399) {
+    return "It didn't work. :(";
+  } else {
+    return response;
+  }
+}
+```
+
+Environment variables can also be used in configuration, such as the URL Rewrite
+handler as shown below.
+
+![Zuplo environment variables](../../public/media/tunnel-setup/16b93099-511d-435b-af85-167fab5814b2.png)
+
+## Tunnel Upgrades
+
+Zuplo publishes a new release of the tunnel Docker image about once per month or
+whenever Cloudflare ships a release to their underlying tunnel tools. The most
+recent version of the Docker Image is always tagged with the `latest` tag. We
+recommend periodically checking and upgrading the tunnel to the latest release
+to ensure you have the latest security and performance updates.
+
+We recommend testing each release of the tunnel in a staging environment before
+rolling out to production.
+
+## Troubleshooting
+
+For troubleshooting see [this document](./tunnel-troubleshooting.mdx).

package/docs/articles/tunnel-troubleshooting.mdx

@@ -0,0 +1,50 @@
+---
+title: Tunnel Troubleshooting
+---
+
+Setting up a secure tunnel involves configuring several different networks to
+work together. When setting up your tunnel it's common for traffic to initially
+not reach your destination initially. This is almost always caused by
+configurations (firewalls, VPCs, IAM rules, etc.) in your internal network.
+
+## Tunnel status
+
+As a first step, check if the tunnel is up and running. You can use the
+following CLI command to check the status of the tunnel:
+
+```bash
+# For brevity, the commands assume that you have exported your API key as an environment variable,
+# export ZUPLO_API_KEY=zpka_d67b7e241bb948758f415b79aa8exxxx_2efbxxxx
+
+zuplo tunnel list # Get the list of tunnels
+zuplo tunnel describe --tunnel-id tnl_xxxxxxxxxxx # Narrow it down to the problematic tunnel
+```
+
+Check the `status` field from the output of `zuplo tunnel describe`. If it's
+"down" that means that your tunnel isn't up. If you are using a Docker
+container, check the container for errors. It takes a few seconds for new
+tunnels to register with the Cloudflare network for the first time.
+
+## Tunnel Logging
+
+If the tunnel is up (as verified in the previous step) but you aren't seeing any
+traffic, you can inspect the logs to see if there are any network or IAM issues
+that might be blocking a connection.
+
+The tunnel by default logs only errors. For the purposes of debugging, it's
+useful to set a more verbose log level. To set logging to a different level,
+simply set the environment variable `TUNNEL_LOGLEVEL` on your Zuplo tunnel
+instance to `debug`. Other log levels available are `info`, `warn`, `error`, and
+`fatal`, but `debug` is recommended for troubleshooting.
+
+The way you set an environment variable will vary depending on where you
+deployed the tunnel. If you are using a Docker container, you can set it as the
+environment variables for the container. See your cloud provider's documentation
+for more details.
+
+```txt
+TUNNEL_LOGLEVEL=debug
+```
+
+Once you are done debugging, we recommend resetting the log level to something
+less verbose since the `debug` level can generate a lot of logs.

package/docs/articles/update-zup-in-github-action.mdx

@@ -0,0 +1,110 @@
+---
+title: Automate Zuplo API Updates with GitHub Actions
+sidebar_label: GitHub Action Automation
+---
+
+<!-- vale Vale.Spelling["Huma"] = NO -->
+
+Because Zuplo is OpenAPI native, you can automate the process of updating your
+Zuplo API when a downstream OpenAPI file changes. For example, if you have an
+API built in Go that uses [Huma](https://github.com/danielgtaylor/huma) you can
+easily generate an OpenAPI file for your API. Then using that generated OpenAPI
+file, you can write a script that updates your Zuplo API based on changes in
+your generated file.
+
+This example shows a GitHub Action that updates a Zuplo API from an OpenAPI file
+that's generated in your API.
+
+You would run this GitHub Action in the repository that contains your downstream
+API. When you push changes to your API, the action will run, generate the
+OpenAPI file. Then it will clone the Zuplo API repository, update the Zuplo
+OpenAPI file, commit and push the changes to a new branch, and open a pull
+request. It will also generate an
+[Action Summary](https://github.blog/2022-05-09-supercharging-github-actions-with-job-summaries/)
+that links to the Pull Request.
+
+```yaml
+name: Update Zuplo API
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  release:
+    name: Update Zuplo from OpenAPI
+    runs-on: ubuntu-latest
+
+    env:
+      REPO_OWNER: my-org
+      # the repository with your Zuplo API
+      REPO_NAME: my-zuplo-api
+      # the branch you want to update
+      REPO_BRANCH: main
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # Override the default token because the built
+          # in token can't trigger other workflows
+          # https://github.community/t/github-actions-workflow-not-triggering-with-tag-push/17053/2
+          token: ${{ secrets.CUSTOM_GITHUB_TOKEN }}
+
+      - uses: actions/checkout@v4
+        with:
+          repository: ${{ env.REPO_OWNER }}/${{ env.REPO_NAME }}
+          path: temp
+          ref: ${{ env.REPO_BRANCH }}
+          token: ${{ secrets.CUSTOM_GITHUB_TOKEN }}
+
+      - name: Use Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20.x
+          cache: "npm"
+
+      # Run your build/generate scripts here to generate the OpenAPI file
+      - run: GENERATE OPEN API FILE HERE
+
+      # Run your script to update the Zuplo API from the OpenAPI file
+      # NOTE: This script is something you write based on your requirements
+      - name: Update the OpenAPI File
+        run: node ./scripts/update-zup-from-openapi.mjs
+
+      - run: git config --global user.email "bot@example.com"
+      - run: git config --global user.name "Updater Bot"
+
+      - name: Commit Changes
+        run: |
+          git checkout -b "zup_${{ github.action_ref}}"
+          git add -A
+          git commit -m "Update OpenAPI File From ${{ github.repository }}"
+          git push origin head
+
+      - name: Open a Pull Request
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.CUSTOM_GITHUB_TOKEN }}
+          script: |
+            const result = await github.rest.pulls.create({
+              title: "Update OpenAPI File From ${{ github.repository }}",
+              owner: "${{ env.REPO_OWNER }}",
+              repo: "${{ env.REPO_NAME }}",
+              head: "zup_${{ github.action_ref}}",
+              base: "${{ env.REPO_BRANCH }}",
+              body: [
+                'This PR is auto-generated by a GitHub Action.',
+                'Add more information here.'
+              ].join('\n')
+            });
+
+            // Update the Summary
+            // You can do a lot more with this, see the core toolkit documentation
+            // SEE: https://github.com/actions/toolkit/tree/main/packages/core#populating-job-summary
+            await core.summary.addRaw(`GitHub Pull Request Opened. [Pull Request](${result.data.html_url})`, true)
+```
+
+This script is a starting point. You will need to modify it to fit your needs.
+You might want to add more checks, tests, or other steps to ensure the update is
+correct. You can also add more information to the pull request body to help your
+team understand the changes.

package/docs/articles/use-openapi-extension-data.mdx

@@ -0,0 +1,79 @@
+---
+title: Using the OpenAPI Extension Data in Code
+sidebar_label: "OpenAPI Extension Data"
+description:
+  Learn how to add custom vendor-specific extensions to OpenAPI files and access
+  that data in your Zuplo API Gateway code.
+tags:
+  - openapi
+  - custom-code
+---
+
+The OpenAPI specification allows for the use of vendor-specific extensions to
+add custom configuration to the API definition. An example of this is the
+`x-internal` extension, which can be used to mark an API as internal and not
+intended for public use.
+
+This same type of extensibility can be used to add custom data to the OpenAPI
+file which can then be used inside of your Zuplo API Gateway. This data can be
+used to configure the behavior of the API Gateway, such as setting up rate
+limiting, authentication, or other custom behavior.
+
+In this article, we will show you how to use the OpenAPI extension data in your
+code.
+
+## Custom Data in the OpenAPI File
+
+To add custom data to your OpenAPI file, you can use the `x-` prefix followed by
+the name of the extension. Add this extension to the operation (for example the
+`get`, `post`, etc. section). For example, to add a custom field called
+`my-custom-config` to the OpenAPI file, you would use the following syntax:
+
+```json title="config/routes.oas.json"
+{
+  "paths": {
+    "/hello": {
+      "x-zuplo-path": {
+        "pathMode": "open-api"
+      },
+
+      "get": {
+        "summary": "Hello World",
+        "x-my-custom-config": 10,
+        "x-zuplo-route": {
+          "corsPolicy": "none",
+          "handler": {
+            "export": "default",
+            "module": "$import(./modules/route-data)",
+            "options": {}
+          },
+          "policies": {
+            "inbound": []
+          }
+        },
+        "operationId": "8914135b-d7b5-49fc-9e41-a8256a0dcf93"
+      }
+    }
+  }
+}
+```
+
+## Using the Custom Data in Code
+
+To use the custom data in your code, you can access it through the
+`ZuploContext` object via the `route.raw` method. The `route.raw` method returns
+an object that contains all of the values in the operation.
+
+```ts title="modules/route-data.ts"
+import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+export default async function (request: ZuploRequest, context: ZuploContext) {
+  const routeData = context.route.raw();
+  const myCustomConfig = routeData["x-my-custom-config"];
+
+  // Logs "Customer config, 10"
+  context.log.debug("Custom config", myCustomConfig);
+
+  return "Hello";
+}
+```

package/docs/articles/users/multifactor-authentication.mdx

@@ -0,0 +1,64 @@
+---
+title: Multifactor Authentication
+sidebar_label: Multifactor Auth
+---
+
+Zuplo supports multifactor authentication (MFA) to help keep your account
+secure. MFA adds an extra layer of security by requiring a second form of
+verification in addition to your password. This can be done using an
+authenticator app or security keys.
+
+## Enabling Multifactor Authentication
+
+To enable multifactor authentication for your account, follow these steps:
+
+<Stepper>
+
+1. Go to your user profile by clicking on your avatar in the top right corner of
+   the Zuplo Portal and selecting **Profile**.
+1. Find the **Multifactor Authentication** section and click **Enroll** on the
+   type of multifactor authentication you want to use.
+1. Follow the instructions to set up your chosen method of multifactor
+   authentication.
+1. The next time you log in, you will be prompted to enter your second form of
+   verification in addition.
+
+</Stepper>
+
+## Disabling Multifactor Authentication
+
+To disable multifactor authentication for your account, simply navigate to the
+**Multifactor Authentication** section of your user profile and click
+**Disable** next to the multifactor authentication method you want to remove.
+
+## Enforcing Multifactor Authentication for Tenant Members
+
+If you have MFA enabled and you are an admin of a tenant account, you can
+enforce all members of that account to use multifactor authentication. This adds
+an additional layer of security for your entire organization.
+
+### Enabling MFA Enforcement
+
+To enforce multifactor authentication for all tenant members:
+
+<Stepper>
+
+1. Navigate to **Settings** → **Members** in the Zuplo Portal.
+1. Find the **Multi-Factor Authentication** section.
+1. Toggle the enforcement setting to **On**.
+
+</Stepper>
+
+### What Happens When MFA is Enforced
+
+When MFA enforcement is enabled:
+
+- All existing tenant members who don't have MFA set up will be redirected to
+  the MFA enrollment page when they next log in
+- New members joining the tenant will be required to set up MFA before they can
+  access the portal
+- Members can't bypass or skip the MFA setup process
+
+Members will need to complete the MFA enrollment process using either an
+authenticator app or security keys before they can continue using the Zuplo
+Portal.

package/docs/articles/users/profile.mdx

@@ -0,0 +1,13 @@
+---
+title: User Profile
+sidebar_label: Profile
+---
+
+Your user profile is set automatically by your identity provider when you sign
+in to your Zuplo account. To set your profile picture, name, and email address,
+you must update your profile in your identity provider. Zuplo doesn't control
+this information, and it's not stored in Zuplo.
+
+If you are authenticating with a username and password, you won't have a profile
+picture or name. Currently, Zuplo doesn't support setting a profile picture or
+name for accounts that authenticate with a username and password.

package/docs/articles/versioning-on-zuplo.mdx

@@ -0,0 +1,89 @@
+---
+title: Versioning on Zuplo
+sidebar_label: "API Versioning"
+description: >-
+  Learn how to version your APIs using URL-based versioning with separate
+  OpenAPI files and custom policies on Zuplo.
+tags:
+  - openapi
+  - custom-code
+---
+
+This guide explains how to approach versioning APIs on Zuplo.
+
+The recommended versioning approach uses URL-based versioning. Read more at
+[How to version an API](https://zuplo.com/blog/2022/05/17/how-to-version-an-api).
+
+## Separate OpenAPI files
+
+A best practice is to have separate OpenAPI files for different major versions
+of an API. A single Zuplo project can have as many OpenAPI routing files as
+needed. The default `routes.oas.json` file can be renamed, as shown here:
+
+![Multiple OpenAPI files](../../public/media/versioning-on-zuplo/multiple-openapi-files.png)
+
+Note you can create a new OpenAPI file by clicking the '+' icon shown.
+
+Each routing file would now have its own routes, each prefixed by `/v1` and
+`/v2`.
+
+Also update the `info` properties in the OpenAPI file to include the version.
+This helps users disambiguate versions in the developer portal:
+
+```json
+{
+  "openapi": "3.1.0",
+  "info": {
+    "title": "My Api (v2)",
+    "version": "2.0.0"
+  }
+}
+```
+
+When Zuplo generates the developer portal, each OpenAPI version appears in its
+own document, allowing users to select the version. This is presented as a
+dropdown:
+
+![Multiple APIs in docs](../../public/media/versioning-on-zuplo/multiple-apis-in-docs.png)
+
+## Using Zuplo as a versioning layer
+
+Because Zuplo is a programmable gateway it's a powerful tool in your versioning
+arsenal. For example, let's imagine you want to make a breaking change between
+v1 and v2 of your `todos` API where the `todoItems` in v2 won't include a piece
+of information in the previous version.
+
+This can be entirely achieved in Zuplo by adding a v2 OpenAPI file and adding an
+identical route from v1 but changing the path:
+
+`/v1/todos` ==> `/v2/todos`
+
+The only other change you'd need to make to this new version is to add an
+outbound custom policy that removes the property, e.g.
+
+```ts
+export default async function policy(
+  response: Response,
+  request: ZuploRequest,
+  context: ZuploContext,
+  options: never,
+  policyName: string,
+) {
+  if (response.status === 200) {
+    const json = await response.json();
+    json.forEach((item) => {
+      delete item.userId;
+    });
+
+    return new Response(JSON.stringify(json), response);
+  }
+
+  return response;
+}
+```
+
+And QED - your Zuplo gateway is being used to update your old API and make it
+shiny and new.
+
+There's a video accompaniment for this document on YouTube here:
+[Versioning an API on Zuplo](https://youtu.be/U0_sfNf5x18)