zuplo 6.67.32 → 6.68.0

package/docs/articles/custom-logging-example.mdx

@@ -0,0 +1,139 @@
+---
+title: Custom Logging Policy
+---
+
+Some of our customers want to build custom logging for their gateway runtime.
+This is an example of just how powerful the programmability of Zuplo is.
+
+In this custom inbound policy we show how you could post to a service (in this
+case we just use RequestBin.com).
+
+```ts
+import { ZuploContext, ZuploRequest, ResponseSentEvent } from "@zuplo/runtime";
+
+type CustomLoggingOptions = {
+  endpoint: string;
+};
+
+const serializableHeaders = (headers: Headers) => {
+  const output = {};
+  headers.forEach((value, key) => {
+    output[key] = value;
+  });
+  return output;
+};
+
+const serializableRequest = async (request: ZuploRequest) => {
+  // if we're going to read the body, we need to clone
+  // the request first - otherwise the response pipeline will
+  // encounter a drained stream
+  const clone = request.clone();
+  const body = await clone.text(); // read as text
+  const data = {
+    method: request.method,
+    url: request.url,
+    headers: serializableHeaders(request.headers),
+    body,
+  };
+
+  return data;
+};
+
+const serializableResponse = async (response: Response) => {
+  // if we're going to read the body, we need to clone
+  // the response first - otherwise the response pipeline will
+  // encounter a drained stream
+  const clone = response.clone();
+  const body = await clone.text(); // read as text
+
+  const data = {
+    status: response.status,
+    headers: serializableHeaders(response.headers),
+    body,
+  };
+
+  return data;
+};
+
+const logReqRes = async (
+  endpoint: string,
+  req: any,
+  response: Response,
+  context: ZuploContext,
+  start: number,
+) => {
+  // we don't want any errors thrown that might impact
+  // our consumers experience so catch everything and
+  // use context.log
+  try {
+    const data = {
+      req,
+      res: await serializableResponse(response),
+      timeMs: Date.now() - start,
+    };
+
+    return fetch(endpoint, {
+      method: "POST",
+      body: JSON.stringify(data),
+    });
+  } catch (err) {
+    context.log.error(err, "error in custom-logging policy");
+  }
+};
+
+export default async function (
+  request: ZuploRequest,
+  context: ZuploContext,
+  options: CustomLoggingOptions,
+  policyName: string,
+) {
+  // We need to read the body of the request before it's used by the handler
+  // so let's serialize the request now
+  const req = await serializableRequest(request);
+  const start = Date.now();
+
+  // The 'responseSent' event will fire at the very last stage in the response
+  // pipeline, when no more mutations can be made - so you can be confident
+  // this was the response sent by Zuplo
+  context.addEventListener("responseSent", async (event: ResponseSentEvent) => {
+    const promise = logReqRes(
+      options.endpoint,
+      req,
+      event.response,
+      context,
+      start,
+    );
+
+    // We need to ask the runtime now to shut down until this is complete,
+    // as this will run asynchronously to our response
+    context.waitUntil(promise);
+  });
+  return request;
+}
+```
+
+We would then configure the policy as follows
+
+```json
+{
+  "name": "custom-logging-policy",
+  "policyType": "custom-code-inbound",
+  "handler": {
+    "export": "default",
+    "module": "$import(./modules/custom-logging)",
+    "options": {
+      "endpoint": "https://YOUR_MOCKIN_URL_HERE"
+    }
+  }
+}
+```
+
+And don't forget to register your new custom policy on your routes! This should
+be the first inbound policy to see the incoming request, unmodified by other
+policies (or blocked by auth, rate-limiting, etc.).
+
+You'll then see live entries with details of the requests and responses for your
+test calls/
+
+You can create a free Mockbin at [mockbin.io](https://mockbin.io) - to get
+started quickly look for the link to create a new bin (not OpenAPI bin).

package/docs/articles/ddos-protection.mdx

@@ -0,0 +1,138 @@
+---
+title: Managed DDoS Protection
+sidebar_label: DDoS Protection
+---
+
+<!-- vale Vale.Spelling["slowloris","Unmetered"] = NO -->
+
+Zuplo provides automatic DDoS (Distributed Denial of Service) protection for all
+APIs deployed on the platform. This service detects and mitigates attacks in
+real-time, ensuring your APIs remain available even under attack.
+
+:::note
+
+Zuplo Managed DDoS is only available for customers using Zuplo's managed edge
+deployment model. Customers using managed dedicated deployments should refer to
+the
+[Managed Dedicated WAF Options](./zuplo-waf.mdx#managed-dedicated-waf-options)
+document.
+
+:::
+
+## What's DDoS?
+
+DDoS attacks attempt to overwhelm your API by flooding it with malicious traffic
+from multiple sources. Zuplo's protection covers both:
+
+- **Network Layer Attacks (Layer 3/4)**: UDP floods, SYN floods, and other
+  network-level attacks
+- **Application Layer Attacks (Layer 7)**: HTTP floods, slowloris, and other
+  application-level attacks
+
+## Key Benefits
+
+- **Always-On**: Protection is automatic from deployment—no configuration needed
+- **Multi-Layer Defense**: Covers both network and application layer attacks
+- **Unmetered Protection**: No bandwidth limits during attacks
+- **Adaptive**: Continuously updated to handle new attack patterns
+- **Minimal False Positives**: Smart detection reduces blocking of legitimate
+  traffic
+- **Avoid Unexpected Costs**: Zuplo never charges for requests that are blocked
+  by DDoS protection protecting you from unexpected overage fees.
+
+## Protection Levels
+
+Zuplo offers different sensitivity levels for DDoS protection, allowing you to
+balance security with accessibility based on your specific needs.
+
+### Working Copy Environments
+
+All Working Copy environments (`.zuplo.dev` domains) are automatically protected
+with **Medium** sensitivity. This provides robust protection while minimizing
+the risk of blocking legitimate traffic during development and testing.
+
+### Preview and Production Environments
+
+Preview and production deployments benefit from advanced DDoS protection
+capabilities:
+
+- **Default Setting**: Medium sensitivity (balanced protection)
+- **Enterprise Customization**: Optional enterprise add-on allowing
+  configuration of protection levels
+
+### Sensitivity Levels Explained
+
+Enterprise customers with the DDoS customization add-on can choose from four
+sensitivity levels:
+
+#### High Sensitivity
+
+- Most aggressive protection with the lowest threshold for triggering mitigation
+- Ideal for APIs that face frequent attacks or handle highly sensitive data
+- May occasionally block legitimate traffic during unusual usage patterns
+
+#### Medium Sensitivity (Default)
+
+- Balanced approach providing strong protection with moderate thresholds
+- Recommended for most production APIs
+- Optimizes for both security and accessibility
+
+#### Low Sensitivity
+
+- Higher threshold for triggering mitigation
+- Suitable for APIs with highly variable traffic patterns
+- Reduces false positives for legitimate traffic spikes
+
+#### Essentially Off
+
+- Minimal protection with the highest threshold
+- Protection still activates for extremely large attacks to maintain network
+  stability
+- Recommended only when you have alternative DDoS protection mechanisms.
+
+## How Protection Works
+
+### Detection
+
+Zuplo's DDoS protection uses sophisticated algorithms to analyze traffic
+patterns in real-time. The system examines multiple factors including:
+
+- Request rates and patterns
+- Source IP reputation
+- Geographic distribution
+- Protocol compliance
+- Behavioral anomalies
+
+### Mitigation
+
+When an attack is detected, the system automatically applies appropriate
+mitigation techniques:
+
+1. **Traffic Filtering**: Malicious traffic is filtered at the edge before
+   reaching your API
+2. **Rate Limiting**: Excessive requests from suspicious sources are throttled
+3. **Connection Management**: Advanced TCP protection handles sophisticated
+   connection-based attacks
+
+### Continuous Improvement
+
+The protection system continuously evolves:
+
+- Managed rulesets are regularly updated
+- New attack patterns are incorporated into detection algorithms
+- Protection mechanisms adapt based on the global threat landscape
+
+## Enterprise Customization
+
+Enterprise customers can enhance their DDoS protection with:
+
+- **Custom Sensitivity Levels**: Adjust protection thresholds per environment
+- **Advanced Analytics**: Detailed attack reports and traffic analysis
+- **Custom Rule Configuration**: Tailor protection to specific traffic patterns
+
+:::tip
+
+Contact your Zuplo account team to learn more about Enterprise DDoS
+customization options.
+
+:::

package/docs/articles/development-options.mdx

@@ -0,0 +1,49 @@
+---
+title: Development Options
+---
+
+Zuplo offers both a local and web-based development experiences. For most
+customers, we recommend the local developer experience as this is the most
+flexible and fastest way to work with your Zuplo API and Developer Portal.
+
+## Local Development
+
+The [local experience](./local-development.mdx) allows users to run both the API
+Gateway and Dev Portal locally. It also includes a local version of the Route
+Designer that's integrated into the Zuplo Portal (portal.zuplo.com). Local
+development allows customers to use the IDE of their choice and run everything
+locally.
+
+Local development is available for all customers regardless of their deployment
+model. It's designed to be fast and lightweight, allowing developers to quickly
+iterate on their APIs without needing to deploy to the cloud.
+
+Local development is the fastest way to develop and test your APIs as you can
+test changes immediately without waiting for a deployment. Changes to your API
+are automatically loaded into the local API Gateway and Dev Portal.
+
+## Web-Based Development Experience
+
+:::note{title="Managed Dedicated"}
+
+Working copy environments aren't available for customers using the
+[managed dedicated deployment model](../dedicated/overview.mdx).
+
+:::
+
+The web-based development experience on (portal.zuplo.com) allows customers on
+our managed-edge deployment model to make edits to their project right from
+within the browser. This experience is designed to be fast and light-weight. The
+web-based experience provides each developer their own
+[developer environment](./environments.mdx) (called **working copy**)
+environment.
+
+The working copy environment is a special environment that's unique to each
+developer. It's optimized for development which means it has slightly different
+configurations than the standard environments. For example, it doesn't cache
+resources as aggressively so changes are reflected more quickly. You can tell if
+an environment is a working copy as it will be deployed to the `zuplo.dev`
+domain. Working copy environments can't have custom domains.
+
+The working copy environment isn't intended for production use and shouldn't be
+used as such. It's designed for development and testing purposes only.

package/docs/articles/environment-variables.mdx

@@ -0,0 +1,134 @@
+---
+title: Configuring Environment Variables
+sidebar_label: Environment Variables
+---
+
+Environment variables are key-value pairs that are stored outside of source
+code. The values of environment variables can be applied to particular
+environments in order to change behavior or configuration.
+
+Environment variables can be read into source code and many configuration files
+in your project. Variables are only applied to environments on new deployments.
+If you change an environment variable, you must redeploy the environment in
+order for the updated value to take effect.
+
+Environment variables can be configuration or secrets. While all values are
+stored encrypted at rest, only non-secret values can be read. Secrets are
+write-only, meaning the value can't be retrieved once it's set.
+
+:::tip
+
+API Reference For detailed information about accessing environment variables in
+code, see the
+[Environment Variables API Reference](../programmable-api/environment.mdx).
+
+:::
+
+## Environment Variable Editor
+
+To set environment variables in your project, click **Settings** and then select
+**Environment Variables**.
+
+To create a new variable, click **Add new variable**.
+
+![Adding a new environment variable](../../public/media/environment-variables/bec84962-0139-4371-b3fd-a30e70860169.png)
+
+Enter the name and value of your environment variable and select if you would
+like the value to be a secret or a regular value.
+
+## Environments
+
+Environment variables can be applied to one or many different environments. You
+can select one or more environments in which to apply the variable.
+
+| Environment                | Description                                                                                                                                                                                    |
+| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Prod                       | The environment that's deployed from your **default** branch in source control. This is usually called `main`.                                                                                 |
+| Preview                    | Any environment that's deployed from source control that's **not the default** branch. (for example `staging` or `preview`). This also includes any branch that's created from a pull request. |
+| Development (Working Copy) | Any environment that's deployed while developing with the portal. Each developer gets their own development environment. These environments are always deployed to `zuplo.dev`                 |
+
+For the **Preview** environment option, a specific named environment can be
+selected. For example, if you want a variable set only for the environment
+deployed from the `staging` branch in source control.
+
+For the **Working Copy** option, developers can set a personal override. This
+value **ONLY** applies to the developer who set the value.
+
+:::info
+
+A single environment variable name can't overlap environments. For example, if
+you set a variable named `MY_VAR` and select all the environments a second
+variable named `MY_VAR` can't be set on say the **Production** environments.
+
+:::
+
+## Reserved Environment Variables
+
+Environment variables can't start with `ZUPLO` or `__ZUPLO`.
+
+## Using Environment Variables
+
+Environment variables can be used in several places within your Zuplo project:
+
+### In Code
+
+Variables are accessed through the `environment` object from `@zuplo/runtime`.
+See the
+[Environment Variables API Reference](../programmable-api/environment.mdx) for
+detailed usage examples and patterns.
+
+### In Configuration Files
+
+Inside some configuration files, environment variables can be referenced with
+the pattern `$env(MY_VAR)`.
+
+For example, in the `policies.json` file, an environment variable could be set
+on a policy option.
+
+```json
+{
+  "name": "my-custom-code-inbound-policy",
+  "policyType": "custom-code-inbound",
+  "handler": {
+    "export": "default",
+    "module": "$import(./modules/YOUR_MODULE)",
+    "options": {
+      "config1": "$env(MY_CONFIG_VAR)",
+      "config2": true
+    }
+  }
+}
+```
+
+### Rewrite & Forwarding Handler
+
+When referencing environment variables inside of the URL Rewrite handler and the
+URL Forward handler, variables are substituted using JavaScript style string
+interpolation.
+
+```txt
+https://${env.API_URL}/path/to/call
+```
+
+## System Environment Variables
+
+The following variables are automatically set by the system and are available to
+use in your code:
+
+- `ZUPLO_ENVIRONMENT_TYPE` - The current environment type the API is running.
+  Values are `edge`, `local`.
+- `ZUPLO_ENVIRONMENT_STAGE` - The stage of the environment. Values are
+  `production`, `preview`, `working-copy`, and `local`.
+- `ZUPLO_ENVIRONMENT_NAME` - The name of the environment. This is a globally
+  unique name for the environment. This is the same name that's used in the URL
+  of the environment. For example, `my-project-main-1235.zuplo.app`. Setting a
+  custom domain on the environment won't change this value.
+- `ZUPLO_ACCOUNT_NAME` - The name of the Zuplo account where the environment is
+  deployed.
+- `ZUPLO_PROJECT_NAME` - The name of the project where the environment is
+  deployed.
+- `ZUPLO_BUILD_ID` - The build ID of the environment. This is a unique ID for
+  each build of the environment. This is a UUID.
+- `ZUPLO_COMPATIBILITY_DATE` - The
+  [compatibility date](../programmable-api/compatibility-dates.mdx) of runtime
+  environment.

package/docs/articles/environments.mdx

@@ -0,0 +1,143 @@
+---
+title: Environments
+---
+
+One of the things that makes Zuplo different from most API gateways, and API
+management platforms is that you can rapidly deploy many environments. Some of
+our customers have hundreds of deployed environments! This facilitates
+collaboration, where teams can collaborate on new features with a dedicated
+environment, deployed for no additional cost in under 20 seconds.
+
+:::tip
+
+For a comprehensive guide to how branches map to environments, see
+[Branch-Based Deployments](./branch-based-deployments.mdx).
+
+:::
+
+## Environment Types
+
+There are three types of environments on Zuplo - Production, Preview, and
+Development (called Working Copy). Each environment has a unique URL and every
+environment is deployed to 300+ edge locations around the world.
+
+### Development (Working Copy)
+
+This is your development environment. You can think of this as your personal
+cloud laptop. To deploy to this environment you just need to save a change in
+portal.zuplo.com, that will automatically trigger a build and deploy of your
+working-copy. A working-copy environment ends in a `.dev` URL. While these
+environments are deployed to the edge in 300+ data centers around the world,
+they're optimized for development purposes. There are some minor differences
+with production and preview environments with caching and other features.
+
+### Preview
+
+These are environments that are deployed using the
+[GitHub integration](/docs/articles/source-control.mdx) or building a
+[custom CI/CD pipeline](/docs/articles/custom-ci-cd.mdx). Preview environments
+are deployed from any branch that isn't set as your default (for example
+production branch). Preview environments are deployed to the edge and have the
+same behavior as production environments, but are typically used for staging,
+testing pull requests, etc.
+
+### Production
+
+These are environments that are deployed using the
+[GitHub integration](/docs/articles/source-control.mdx) or building a
+[custom CI/CD pipeline](/docs/articles/custom-ci-cd.mdx). Each project has only
+one Production environment and is deployed from the git branch that's set as
+your production branch in your source control settings.
+
+#### Changing the Production Environment
+
+The Production environment is determined by your repository's **default branch**
+setting (configured in your Git provider, not Zuplo). To change which branch
+deploys to Production:
+
+1. Go to your Git repository settings:
+   - **GitHub**: Settings > General > Default branch
+   - **GitLab**: Settings > Repository > Branch defaults
+   - **Bitbucket**: Repository settings > Branching model
+   - **Azure DevOps**: Project settings > Repositories > Default branch
+2. Change the default branch to your desired branch
+3. Zuplo automatically treats the new default branch 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.
+
+:::
+
+### Preview vs Production Environments (or multiple Production Environments)
+
+:::note
+
+There is **no technical difference** between a Production environment and a
+Preview environment. Both deploy to the same infrastructure, run in the same
+300+ edge locations, and have identical performance characteristics. The
+"production" label simply means "deployed from the default branch." It controls
+which set of [environment variables](/docs/articles/environment-variables.mdx)
+and [API key buckets](/docs/articles/api-key-buckets.mdx) apply by default, but
+the underlying deployment is exactly the same.
+
+:::
+
+Some customers choose to use a specific (or multiple) Preview environments as
+"production" deployments of their API. For example, you might deploy your US
+traffic from `main` (Production) and your EU traffic from an `eu-production`
+branch (Preview). This works because the environments are technically identical.
+Environment variables and API key buckets can be overridden for specific Preview
+environments to support this pattern.
+
+For a comprehensive overview of how source control, branches, and environments
+relate to each other, see
+[Source Control and Deployment](/docs/concepts/source-control-and-deployment.mdx).
+
+## Navigating Environments
+
+On the bottom toolbar of the Zuplo portal you will see a selector for the
+current environment. You can switch between environments by clicking on the name
+of the current environment and then selecting another environment.
+
+![Environments](../../public/media/environments/image.png)
+
+Your development (working copy) environment will be listed at the top in a
+separate section. Your git deployed environments will be listed next with the
+production environment on top.
+
+For users using [source control integration](/docs/articles/source-control.mdx)
+the name of the deployment matches the branch name (yes - creating a new
+environment is literally as easy as creating a new branch).
+
+You can't edit the code of an production or preview environment in
+portal.zuplo.com but you can switch into those environments to perform a number
+of functions, such as:
+
+- edit API consumers for this environment
+- view analytics for this environment
+- view Live Logs for this environment
+
+## Different Backends per Environment
+
+It's common to want a different backend for your production, staging and preview
+environments. This can be easily achieved by using
+[environment variables](./environment-variables.mdx) to specify the origin of
+the backend and then using that in your
+[URL Rewrite Handlers](../handlers/url-rewrite.mdx).
+
+For example,
+
+```json
+${env.BASE_PATH}${pathname}
+```
+
+A url rewrite like this will combine the `BASE_PATH` environment variable, say
+`https://example.com` with the incoming path, for example `/foo/bar` to create a
+re-written URL:
+
+```json
+https://example.com/foo/bar
+```

package/docs/articles/fastly-zuplo-host-setup.mdx

@@ -0,0 +1,41 @@
+---
+title: Using Zuplo as a Fastly Host
+sidebar_label: Fastly Setup
+---
+
+This document outlines how to use Zuplo as a host for Fastly. While this isn't a
+necessary setup for most people as Zuplo already runs at the edge and can be
+used for CDN like caching. However, there are some scenarios where you may want
+to put Zuplo behind Fastly. For example, if you are using Fastly's
+[WAF or DDoS protection](./waf-ddos-fastly.mdx) and want to ensure that all
+traffic goes through Fastly before hitting your Zuplo API Gateway.
+
+## Configuring Zuplo as a Fastly Host
+
+The following settings will allow you to run Zuplo as a host behind Fastly.
+
+### Zuplo Configuration
+
+It's recommended that you use a custom domain for your Zuplo API Gateway. This
+will allow you to more configure your Fastly host as well as ensure that your
+domain is stable regardless of your Zuplo configuration.
+
+### Fastly Configuration
+
+1. Create a new Fastly CDN service or use an existing one.
+2. Create a new Origin and name it whatever you like.
+3. Set the **Address** to your Zuplo API Gateway domain. For example,
+   `api.example.com` if using a custom domain, or
+   `my-project-main-021839d.zuplo.app` without a custom domain.
+4. Enable TLS and keep the port as `443`.
+5. Select Yes on Verify the Certificate.
+6. If using a custom domain, set the _Certificate Hostname_ to your custom
+   domain. If using a `zuplo.app` domain, set the set the _Certificate Hostname_
+   to `zuplo.app`.
+7. Set the **SNI hostname** to your custom domain or full `zuplo.app` domain
+   (for example, `my-project-main-021839d.zuplo.app`)
+8. Set the **Override Host** to your custom domain or full `zuplo.app` domain
+   (for example, `my-project-main-021839d.zuplo.app`)
+
+Additional settings like mTLS are also supported. Please refer to the Fastly
+documentation for more information.