zuplo 6.67.32 → 6.68.0

package/docs/articles/hosting-options.mdx

@@ -0,0 +1,70 @@
+---
+title: Hosting Options
+sidebar_label: Overview
+---
+
+Your place or ours; Zuplo has a variety of hosting options to suit your needs.
+
+## 1. Managed Edge
+
+Run your Zuplo projects in a serverless environment at the edge across 300+ data
+centers worldwide. This is our most popular option and the default choice for
+all Zuplo projects. If you use our self-serve product and pay with your credit
+card, this is the option you are using.
+
+Managed Edge is ideal for organizations that want:
+
+- The simplest deployment experience with zero infrastructure management
+- Global distribution and low-latency performance for users worldwide
+- Automatic scaling to handle traffic spikes and high request volumes
+- Enterprise-grade performance proven at scale (billions of requests per month,
+  millions of requests per second)
+
+For more information, see the
+[Managed Edge documentation](/docs/managed-edge/overview).
+
+## 2. Managed Dedicated
+
+We run your gateway in a dedicated, isolated VPC on the cloud provider of your
+choice, including Akamai Connected Cloud, AWS, GCP, Azure, Equinix, TerraSwitch,
+and more. You get to choose the regions where you want your service hosted to
+meet any sovereignty or data residency concerns.
+
+Managed Dedicated is ideal for organizations that need:
+
+- To run your API Gateway on a specific cloud provider
+- Custom networking configurations, such as restricting access to the public
+  internet
+- Geographical deployment requirements where Managed Edge isn't feasible
+- Regulatory or compliance requirements that necessitate a dedicated instance
+- Private networking options like AWS PrivateLink, Azure Private Link, or GCP
+  Private Service Connect (available for both inbound and outbound connections)
+
+For more information, see the
+[Managed Dedicated documentation](/docs/dedicated/overview.mdx) or
+[schedule some time to talk with us](https://book.zuplo.com).
+
+## 3. Self-Hosted (On-Premises)
+
+Run Zuplo on your own infrastructure in any cloud or private data center using
+Kubernetes. Zuplo Self-Hosted runs exclusively on Kubernetes and can be deployed
+to any Kubernetes environment. Deployment is simple and uses Helm charts.
+
+Self-Hosted is available in two deployment models:
+
+- **Hybrid Deployment**: Run the Zuplo API Gateway on your Kubernetes cluster
+  while leveraging shared services for features such as rate limiting
+- **Full Self-Hosted**: Run all Zuplo components on your Kubernetes cluster for
+  complete control and isolation
+
+Self-Hosted is ideal for organizations that need:
+
+- Complete control over your infrastructure and deployment environment
+- To run Zuplo in a private data center or on-premises Kubernetes environment
+- To meet strict data sovereignty or regulatory requirements
+- To integrate with existing on-premises systems and networks
+- To customize the deployment architecture to match your specific requirements
+
+For more information, see the
+[Self-Hosted documentation](/docs/self-hosted/overview) or
+[book a meeting](https://zuplo.com/meeting) with us.

package/docs/articles/lazy-load-configuration-into-cache.mdx

@@ -0,0 +1,92 @@
+---
+title: Lazy Load Configuration
+sidebar_label: "Lazy Load Configuration"
+description:
+  Learn how to efficiently load and cache configuration data using
+  MemoryZoneReadThroughCache for optimal performance.
+tags:
+  - caching
+  - custom-code
+---
+
+Often when working with a programmable gateway like Zuplo you'll want to load
+some configuration and store it safely for fast access on future requests
+without impacting latency.
+
+The fastest place to store such information is in memory, but there can be
+thousands of processes on Zuplo when you're at scale and sometimes those
+processes aren't long lived.
+
+The next fastest place is in [ZoneCache](../programmable-api/zone-cache.mdx)
+which is a cache located in each data center. This requires an asynchronous
+connection but is usually much faster than going back to your configuration data
+store (often in a single location worldwide).
+
+The
+[MemoryZoneReadThroughCache](../programmable-api/memory-zone-read-through-cache.mdx)
+offers the best of both worlds - it uses memory and zone cache in combination to
+afford the lowest possible latency.
+
+:::warning
+
+Do take care not to load so much data into memory that you OOM (out-of-memory)
+your process. Processes in Zuplo typically have ~120MB of memory to perform all
+their work, including holding request bodies etc.
+
+:::
+
+Here's a simple example of the usage of MemoryZoneReadthroughCache being used to
+store configuration data.
+
+```ts
+import {
+  ZuploContext,
+  ZuploRequest,
+  MemoryZoneReadThroughCache,
+  environment,
+} from "@zuplo/runtime";
+
+interface MyConfig {
+  data: Record<string, string>[];
+}
+
+const cacheName = "CACHE_NAME";
+const configKey = "CONFIG_KEY";
+const cacheTtlSeconds = 3600;
+
+async function loadConfig(context: ZuploContext) {
+  // We will type the cache to work with MyConfig type, but
+  // you can use `any` if there. Use the same cache name
+  // when trying to use the same cache store from different modules.
+  const cache = new MemoryZoneReadThroughCache<MyConfig>(cacheName, context);
+  let config = await cache.get(configKey);
+
+  if (!config) {
+    // This is where you load the configuration for your own backend API
+    const response = await fetch(`https://your-backend-config-api.com`, {
+      headers: {
+        authorization: `Bearer ${environment.CONFIG_API_KEY}`,
+      },
+    });
+
+    if (response.status !== 200) {
+      throw new Error(
+        `Error reading config ${response.status}: '${await response.text()}'`,
+      );
+    }
+
+    config = await response.json();
+    cache.put(configKey, config, cacheTtlSeconds);
+  }
+  return config;
+}
+
+export default async function (request: ZuploRequest, context: ZuploContext) {
+  const config = await loadConfig(context);
+  context.log.info(config);
+  // use the config in your pipeline or request handler etc
+  // ...
+  // ...
+  return request;
+}
+```

package/docs/articles/limits.mdx

@@ -0,0 +1,98 @@
+---
+title: Zuplo Platform Limits
+sidebar_label: Platform Limits
+---
+
+This document describes the limits that apply to your Zuplo account.
+
+:::tip{title="Managed Dedicated Environments"}
+
+The limits in this document are primarily for Zuplo's managed edge environment .
+For managed dedicated environments and enterprise agreements, most limits are
+fully customizable to meet your specific requirements.
+
+:::
+
+## General
+
+Below are general limits that apply to deployments on Zuplo's managed edge
+environments.
+
+| Feature                       | Description                                                     | Limit                                                                                                                                                                |
+| ----------------------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Environment Variables         | The number of environment variables you can create              | Free/Builder Plans: 50 variables per environment, Other Plans: 100 per environment                                                                                   |
+| Environment Variable size     | The size of an environment variable                             | ~5kb per variable                                                                                                                                                    |
+| Request Duration              | The maximum time a request can take to complete                 | Free/Builder Plans: 30 seconds, Other Plans: No Limit                                                                                                                |
+| Memory                        | The maximum memory available when processing a request          | Free/Builder Plans: 128mb, Enterprise Plans: Custom                                                                                                                  |
+| Requests per second           | The maximum number of requests per second                       | Development Environments (Working Copy): 1000 requests per minute. No Limit outside of plan monthly limit                                                            |
+| Log Size                      | The size of a log entry                                         | Zuplo Portal live logs are limited to ~10kB. Excess will be truncated. For third-party logging providers, the value depends on the provider. Zuplo imposes no limit. |
+| Request Body Size             | The maximum size of an incoming request body                    | 500 MB                                                                                                                                                               |
+| Response Headers              | The total size of all response headers                          | 128 KB                                                                                                                                                               |
+| Subrequests                   | The maximum number of subrequests per request                   | 1,000                                                                                                                                                                |
+| Simultaneous Open Connections | The maximum number of simultaneous open connections per request | 6                                                                                                                                                                    |
+
+## HTTP connections
+
+In Zuplo's managed edge environment, HTTP connections have timeouts to ensure
+efficient use of resources. These timeouts apply to both incoming connections
+from clients to Zuplo and outgoing connections from Zuplo to your origin
+servers.
+
+## Between client and Zuplo
+
+| Type                           | Limit (seconds) | HTTP status code at limit |
+| ------------------------------ | --------------- | ------------------------- |
+| Connection Keep-Alive HTTP/1.1 | 400             | TCP connection closed     |
+| Connection Idle HTTP/2         | 400             | TCP connection closed     |
+
+## Between Zuplo and origin server
+
+| Type                    | Limit (seconds) | HTTP status code at limit |
+| ----------------------- | --------------- | ------------------------- |
+| Complete TCP Connection | 19              | 522                       |
+| TCP ACK Timeout         | 90              | 522                       |
+| TCP Keep-Alive Interval | 30              | 520                       |
+| Proxy Idle Timeout      | 900             | 520                       |
+| Proxy Read Timeout      | 180             | 524                       |
+| Proxy Write Timeout     | 30              | 524                       |
+| HTTP/2 Pings to Origin  | Off             | -                         |
+| HTTP/2 Connection Idle  | 900             | No                        |
+
+## API keys
+
+### Consumers & keys
+
+Zuplo doesn't impose a hard cap on the number of consumers or keys you can
+create. However, usage of the service is subject to "fair use" policies meaning
+if your usage is deemed excessive we may limit usage. If you require specific
+limits please contact sales to discuss pricing plans.
+
+Our general guidelines for what constitutes fair use are as follows:
+
+- Free Plan: 500 consumers or keys
+- Builder Plan: 1,000 consumers or keys
+- Enterprise Plan: Custom
+
+### Consumer metadata and tags
+
+- Consumer `metadata` - The JSON encoded object can't be larger than 1kb.
+- Consumer `tags` - Each consumer is limited to 5 key value pair tags.
+
+### API key management operations
+
+Requests to API key management operations on the Zuplo Developer API
+(dev.zuplo.com) are limited to 100 requests per second.
+
+### API key authorizations
+
+One API key authorization can be made per request. Enterprise plans can request
+custom limits to allow multiple API key authorizations per request.
+
+### Cache
+
+The [cache API](../programmable-api/cache.mdx) and abstractions on top of it
+such as [ZoneCache](../programmable-api/zone-cache.mdx) have the following
+limits:
+
+- Maximum size per cached item: 512 MB
+- Maximum cache calls per request: 1000

package/docs/articles/local-development-debugging.mdx

@@ -0,0 +1,44 @@
+---
+title: "Debugging Locally"
+sidebar_label: Debugging
+---
+
+You can debug your local gateway through VS Code using its TypeScript debugger.
+Features such as breakpoints, stepping through the code, variable inspection,
+etc., will be available to help you debug your gateway.
+
+1. Create a `.vscode/launch.json` file with the following content. If you
+   already have an older/existing `.vscode/launch.json` file, you can add the
+   section in the curly braces to the configurations array. Take note of the
+   port value since that's the value you will specify next.
+
+```json
+{
+  "configurations": [
+    {
+      "name": "Zuplo Gateway",
+      "type": "node",
+      "request": "attach",
+      "restart": true,
+      "port": 9229
+    }
+  ]
+}
+```
+
+2. Start the gateway in debug mode using the port that you specified above.
+
+```bash
+npx zuplo dev --debug-port 9229
+```
+
+3. Switch to the View > Run and Debug in VS Code. You can now attach the
+   debugger by selecting **Zuplo Gateway** and clicking the green triangle.
+
+![VS code debugging](../../public/media/local-development-debugging/image.png)
+
+## Limitations
+
+- We only support stepping through your own module code. System code provided by
+  Zuplo are minified and stripped of source maps, so you won't be able to step
+  through them.

package/docs/articles/local-development-env-variables.mdx

@@ -0,0 +1,23 @@
+---
+title: "Configuring Environment Variables Locally"
+sidebar_label: Environment variables
+---
+
+For security reasons, your local development doesn't have access to the
+environment variables that you have configured on the Zuplo Portal. Instead,
+your local Zuplo API Gateway will load environment variables from a .env file.
+
+1. Create a .env file in the root of your project.
+2. Follow the following format
+
+:::warning
+
+As the `.env` file could contain sensitive information, it shouldn't be
+committed to your version system. Consider adding .env to your .gitignore file.
+
+:::
+
+```txt
+KEY1=VALUE1
+KEY2=VALUE2
+```

package/docs/articles/local-development-installing-packages.mdx

@@ -0,0 +1,23 @@
+---
+title: "Installing Packages"
+---
+
+You can install packages from npm to use in your Zuplo Gateway. This can help
+with code completion and hover tips.
+
+However, bear in mind, these might not work out-of-the-box in the cloud (for
+example, working-copy and edge environments), as Zuplo for security reasons
+doesn't allow all packages to be installed. Consult
+[Node Modules](../programmable-api/node-modules.mdx) for the official list of
+supported modules.
+
+There are workarounds though. If you need a package to be available, you can try
+to _bundle_ it. This will bypass the `npm install` step since the module is
+already bundled and available. We've an example at
+[Custom Modules](https://github.com/zuplo/zuplo/tree/main/examples/custom-module)
+that you can follow.
+
+We're looking into ways to simplify bringing in your own modules. We're
+proceeding carefully as we want to ensure that we can provide a secure and
+reliable experience for our users. Please contact
+[Zuplo support](mailto:support@zuplo.com) if you need more assistance.

package/docs/articles/local-development-routes-designer.mdx

@@ -0,0 +1,27 @@
+---
+title: "Routes Designer"
+---
+
+The Routes Designer is a visual tool that allows you to create and edit routes,
+as well as add [policies](../policies), for your Zuplo Gateway without having to
+manually edit the OpenAPI `routes.oas.json` file manually.
+
+When you run `npm run dev`, the Routes Designer is automatically started on
+port 9100. You can access it by visiting http://localhost:9100 in your browser.
+
+```sh
+$ npm run dev
+
+Started local development setup
+Ctrl+C to exit
+
+🚀 Zuplo Gateway: http://localhost:9000
+📘 Route Designer: http://localhost:9100 # <-- Your local route designer
+```
+
+![Routes Designer](../../public/media/local-development-routes-designer/8108441d-5d60-4ff6-9b1b-2791f9a971f5.png)
+
+If you are using VS Code, you can open it in the Simple Browser extension to see
+it side-by-side as follows.
+
+![VS Code with Simple Browser](../../public/media/local-development-routes-designer/1a3594c1-18a1-4416-b7c7-05585b253dca.png)

package/docs/articles/local-development-services.mdx

@@ -0,0 +1,40 @@
+---
+title: "Connecting to Zuplo Services Locally"
+sidebar_label: Zuplo Services
+---
+
+To use Zuplo services such as API keys and rate limiting locally, you must have
+a Zuplo account and an existing project. You will be using the connections from
+your remote gateway.
+
+1. Run `npx zuplo link` to bring in relevant information from your Zuplo account
+   and project. Follow the prompt to select the right environment. For local
+   development, we recommend selecting the development environment.
+2. At this point, you will see a file called `.env.zuplo` containing some
+   information about the account, project, and environment that your local
+   gateway is linked to.
+
+:::warning
+
+As the .env.zuplo file could contain sensitive information, it shouldn't be
+committed to your version system. Consider adding .env.zuplo to your .gitignore
+file.
+
+:::
+
+4. You can run `npm run dev` as normal. The Zuplo CLI will automatically pick up
+   the relevant services from the `.env.zuplo` file.
+5. If you want to switch environments (for example, from development to
+   preview), run `npx zuplo link` again and select the new environment. You can
+   see which environment you are connected to by looking at the .env.zuplo file.
+
+```bash title="Contents of .env.zuplo "
+# This file is auto-generated from zuplo link. Please don't edit it manually.
+# It will be auto-generated afresh the next time you run zuplo link.
+# If you wish to add your own environment variables, create a separate .env file.
+
+ZUPLO_ACCOUNT_NAME=your-account-name
+ZUPLO_PROJECT_NAME=your-project-name
+ZUPLO_ENVIRONMENT_TYPE=your-environment
+
+```

package/docs/articles/local-development-troubleshooting.mdx

@@ -0,0 +1,56 @@
+---
+title: "Troubleshooting"
+---
+
+## Changing the port numbers
+
+By default the Zuplo local server runs on port 9000 and route designer runs on
+port 9100. To change the port number, you can call
+
+```sh
+npx zuplo dev --port <port number> --editor-port <editor port number>
+```
+
+## Certificates Errors
+
+When running Zuplo locally you may want to call a service with a self-signed
+certificate. By default this isn't supported - we recommend using signed/trusted
+certificates in deployed environments. However, for local development you can
+ignore certificate errors by adding the `--unsafely-ignore-certificate-errors`
+flag on the `zuplo dev` command.
+
+Run your development server with the following command:
+
+```bash
+npx zuplo dev --unsafely-ignore-certificate-errors
+```
+
+If you want to update your `package.json` to always allow self-signed
+certificates, you can add the following script:
+
+```json
+{
+  "scripts": {
+    "dev": "zuplo dev --unsafely-ignore-certificate-errors"
+  }
+}
+```
+
+## Updating the Zuplo CLI
+
+To update the CLI, run the following command in your project directory.
+
+```bash
+npm install zuplo@latest
+```
+
+You must include the @latest to ensure you are getting the latest. Otherwise,
+you could have an older version cached locally on your machine.
+
+You can compare if you have the latest version by looking at the version number
+on [NPM](https://www.npmjs.com/package/zuplo?activeTab=versions)
+
+## Getting help
+
+Please reach out to support@zuplo.com or join our
+[Discord server](https://discord.gg/8QbEjr2MgZ).

package/docs/articles/local-development.mdx

@@ -0,0 +1,81 @@
+---
+title: Running your Zuplo Gateway locally
+sidebar_label: Quickstart
+---
+
+You can configure and run your Zuplo Gateway locally on your machine for
+development purposes using your favorite code editor.
+
+## Requirements
+
+- [Node.js](https://nodejs.org/en/download) 20.0.0 or higher
+- Linux, Mac OS X, Windows, or Windows Subsystem for Linux (WSL)
+
+## Getting Started
+
+### Create a new project from scratch
+
+<Stepper>
+
+1. Create a new project using
+
+   ```bash
+   npx create-zuplo-api@latest
+   ```
+
+   ```bash title="Expected output: "
+   cd <your-new-project-directory>
+   npm run dev
+   ```
+
+1. Start your local gateway using `npm run dev`.
+1. Use the [local Route Designer](./local-development-routes-designer.mdx) to
+   create your first route.
+
+</Stepper>
+
+### Import your existing project
+
+If you have been using Zuplo using the _Zuplo Web Portal_, you can import your
+project into your local machine.
+
+<Stepper>
+
+1. Connect your project to a Git repository from the _Zuplo Web Portal_.
+   ![Connect repository](../../public/media/local-development/3bd6b736-20d7-4ac4-805c-d7fd810dea28.png)
+1. Clone your project from your Git provider to your local machine.
+1. Install the necessary dependencies:
+
+   ```sh
+   npm install
+   ```
+
+1. Start your Zuplo Gateway locally;
+
+   ```sh
+   npm run dev
+   ```
+
+1. Use the [local Route Designer](./local-development-routes-designer.mdx) to
+   create your first route.
+
+</Stepper>
+
+## Limitations
+
+While convenient and powerful, not all features of Zuplo are supported while
+developing locally. The following features are currently not supported when
+running your Zuplo Gateway locally:
+
+- Analytics
+
+## Next steps
+
+- Use the [local Route Designer](./local-development-routes-designer.mdx) to
+  create your first route.
+- Install [packages](../programmable-api/node-modules.mdx) to extend your Zuplo
+  Gateway.
+- Use the [API keys](./local-development-services.mdx) service locally to secure
+  your routes.
+- Add [environment variables](./local-development-env-variables.mdx) to your
+  project.

package/docs/articles/log-plugin-aws-cloudwatch.mdx

@@ -0,0 +1,83 @@
+---
+title: AWS CloudWatch Plugin
+sidebar_label: AWS CloudWatch Logging
+---
+
+The AWS CloudWatch Log plugin enables pushing logs to AWS CloudWatch.
+
+<EnterpriseFeature name="Custom logging" />
+
+## Setup
+
+To add the AWS CloudWatch logging plugin to your Zuplo project, add the
+following code to your `zuplo.runtime.ts` file.
+
+```ts title="modules/zuplo.runtime.ts"
+import {
+  RuntimeExtensions,
+  AWSLoggingPlugin,
+  environment,
+} from "@zuplo/runtime";
+
+export function runtimeInit(runtime: RuntimeExtensions) {
+  runtime.addPlugin(
+    new AWSLoggingPlugin({
+      region: environment.AWS_REGION,
+      accessKeyId: environment.AWS_ACCESS_KEY_ID,
+      secretAccessKey: environment.AWS_SECRET_ACCESS_KEY,
+      logGroupName: "/aws/zuplo/api",
+      logStreamName: "production",
+    }),
+  );
+}
+```
+
+## Configuration Options
+
+The `AWSLoggingPlugin` constructor accepts an options object with the following
+properties:
+
+- `region` - (required) AWS region where your CloudWatch logs are stored (for
+  example, "us-east-1")
+- `accessKeyId` - (required) AWS access key ID for authentication
+- `secretAccessKey` - (required) AWS secret access key for authentication
+- `logGroupName` - (required) CloudWatch log group name
+- `logStreamName` - (required) CloudWatch log stream name
+- `fields` - (optional) Custom fields to include in each log entry. Can contain
+  string, number, or boolean values
+
+### Custom Fields
+
+Any custom fields you want to include in the log entry can be added to the
+`fields` property. These values will be appended to every log entry.
+
+```ts
+new AWSLoggingPlugin({
+  region: environment.AWS_REGION,
+  accessKeyId: environment.AWS_ACCESS_KEY_ID,
+  secretAccessKey: environment.AWS_SECRET_ACCESS_KEY,
+  logGroupName: "/aws/zuplo/api",
+  logStreamName: "production",
+  fields: {
+    field1: "value1",
+    field2: "value2",
+  },
+});
+```
+
+## Default Fields
+
+Every log entry will include the following fields (in camelCase format):
+
+- `timestamp` - The time the log was created (ISO 8601 format)
+- `severity` - The log level (for example, `ERROR`, `INFO`, `DEBUG`, `WARN`)
+- `data` - The log message and any additional data
+- `environmentType` - Where the Zuplo API is running. Values are `edge`,
+  `working-copy`, or `local`
+- `environmentStage` - The deployment stage: `working-copy`, `preview`, or
+  `production`
+- `requestId` - The UUID of the request (the value of the `zp-rid` header)
+- `atomicCounter` - An atomic counter used to order logs with identical
+  timestamps
+- `rayId` - The network provider identifier (for example, Cloudflare Ray ID) of
+  the request