zuplo 6.67.32 → 6.68.0

package/docs/dedicated/akamai/caching.mdx

@@ -0,0 +1,212 @@
+---
+title: Controlling Akamai CDN Caching
+sidebar_label: CDN Caching
+description:
+  How to control Akamai CDN caching behavior using response headers from your
+  Zuplo API Gateway.
+---
+
+<!-- vale Vale.Spelling = NO -->
+
+When running Zuplo on Akamai Connected Cloud, your API Gateway can control how
+the Akamai CDN caches responses by setting the `Cache-Control` header. This
+allows you to optimize caching behavior for different endpoints without
+modifying Akamai Property Manager configurations.
+
+## How Akamai caching works
+
+Akamai's CDN can cache responses at edge servers to reduce load to your Zuplo
+API Gateway and improve response times for clients.
+
+<Diagram type="sequence" height="h-[420px]">
+  <DiagramActor id="client" variant="yellow">
+    Client
+  </DiagramActor>
+  <DiagramActor id="cdn" variant="blue">
+    Akamai CDN
+  </DiagramActor>
+  <DiagramActor id="gateway" variant="zuplo">
+    Zuplo
+  </DiagramActor>
+  <DiagramActor id="backend" variant="green">
+    Backend
+  </DiagramActor>
+  <DiagramMessage from="client" to="cdn">
+    Request (cache miss)
+  </DiagramMessage>
+  <DiagramMessage from="cdn" to="gateway">
+    Forward request
+  </DiagramMessage>
+  <DiagramMessage from="gateway" to="backend">
+    Forward request
+  </DiagramMessage>
+  <DiagramMessage from="backend" to="gateway">
+    Response
+  </DiagramMessage>
+  <DiagramMessage from="gateway" to="cdn">
+    Response + Cache-Control headers
+  </DiagramMessage>
+  <DiagramMessage from="cdn" to="client">
+    Response (cached at edge)
+  </DiagramMessage>
+</Diagram>
+
+When a request arrives, Akamai checks if a cached response exists. On a cache
+miss, the request goes to Zuplo, which can set cache headers on the response.
+Akamai caches the response according to those headers and serves subsequent
+requests directly from the edge cache.
+
+The CDN determines caching behavior based on:
+
+1. **Akamai Property Manager settings** - Default caching rules configured in
+   your CDN property
+2. **Origin response headers** - Headers sent by Zuplo that can override or
+   influence default behavior
+
+When your Akamai property is configured to "Honor origin Cache-Control and
+Expires" headers, Zuplo can control caching behavior on a per-response basis.
+
+For complete details on Akamai's caching behavior, see the
+[Akamai caching documentation](https://techdocs.akamai.com/property-mgr/docs/caching-2).
+
+## Cache-Control header
+
+The `Cache-Control` header controls caching for both the CDN and downstream
+clients (browsers). Akamai honors the following directives when configured to
+respect origin headers:
+
+| Directive         | Description                                                 |
+| ----------------- | ----------------------------------------------------------- |
+| `max-age`         | Cache duration for browsers and downstream caches (seconds) |
+| `s-maxage`        | Cache duration for shared caches like CDNs (seconds)        |
+| `no-cache`        | Revalidate with origin before serving cached content        |
+| `no-store`        | Don't cache the response at all                             |
+| `private`         | Only allow browser caching, not CDN caching                 |
+| `public`          | Allow caching by CDNs and browsers                          |
+| `must-revalidate` | Must revalidate after max-age expires                       |
+
+### Using s-maxage for CDN caching
+
+The `s-maxage` directive is specifically for shared caches like CDNs. When both
+`max-age` and `s-maxage` are present, Akamai uses `s-maxage` for edge caching
+and forwards `max-age` to browsers:
+
+```
+Cache-Control: public, max-age=60, s-maxage=3600
+```
+
+This example caches content at the CDN for 1 hour while instructing browsers to
+cache for only 1 minute.
+
+### Common Cache-Control patterns
+
+| Scenario                   | Header Value                                         |
+| -------------------------- | ---------------------------------------------------- |
+| CDN: 1 hour, Browser: none | `Cache-Control: public, s-maxage=3600, max-age=0`    |
+| CDN: 1 day, Browser: 5 min | `Cache-Control: public, s-maxage=86400, max-age=300` |
+| No caching                 | `Cache-Control: no-store`                            |
+| Browser only, no CDN       | `Cache-Control: private, max-age=3600`               |
+
+## Setting cache headers in Zuplo
+
+### Using the Set Headers policy
+
+The simplest way to add cache headers is using the
+[Set Headers Outbound Policy](../../policies/set-headers-outbound.mdx):
+
+```json title="config/policies.json"
+{
+  "name": "cache-one-hour",
+  "policyType": "set-headers-outbound",
+  "handler": {
+    "export": "SetHeadersOutboundPolicy",
+    "module": "$import(@zuplo/runtime)",
+    "options": {
+      "headers": [
+        {
+          "name": "Cache-Control",
+          "value": "public, max-age=60, s-maxage=3600"
+        }
+      ]
+    }
+  }
+}
+```
+
+This configuration caches responses at the CDN for 1 hour while allowing
+browsers to cache for only 1 minute.
+
+### Using custom code
+
+For dynamic cache control based on response content or status, use a custom
+outbound policy:
+
+```typescript title="modules/cache-control.ts"
+import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+export default async function (
+  response: Response,
+  request: ZuploRequest,
+  context: ZuploContext,
+) {
+  const headers = new Headers(response.headers);
+
+  // Cache successful responses for 1 hour at CDN, 1 minute in browser
+  if (response.status >= 200 && response.status < 300) {
+    headers.set("Cache-Control", "public, max-age=60, s-maxage=3600");
+  }
+  // Don't cache error responses
+  else if (response.status >= 400) {
+    headers.set("Cache-Control", "no-store");
+  }
+
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  });
+}
+```
+
+## Downstream cacheability
+
+By default, Akamai sends the smaller of the origin's `Cache-Control` max-age and
+the remaining edge cache lifetime to clients. This ensures browsers don't cache
+content longer than it remains valid at the edge.
+
+You can control downstream (client) caching independently using Property Manager
+settings or by setting explicit `max-age` values in your `Cache-Control` header.
+
+For more information, see
+[Akamai's downstream cacheability documentation](https://techdocs.akamai.com/property-mgr/docs/downstream-cacheability).
+
+## Best practices
+
+1. **Use s-maxage for CDN caching** - Separate CDN and browser cache durations
+   for better control
+2. **Don't cache authenticated responses** - Use `private` or `no-store` for
+   user-specific data
+3. **Set appropriate Vary headers** - If responses vary by header (like
+   `Accept-Language`), include a `Vary` header
+
+## Akamai Property Manager configuration
+
+For Zuplo to control caching via headers, ensure your Akamai CDN property is
+configured to honor origin headers:
+
+1. In Property Manager, navigate to your property's caching behavior
+2. Set **Caching Option** to "Honor origin Cache-Control and Expires"
+3. Enable the Cache-Control directives you want to honor (max-age, s-maxage,
+   etc.)
+4. Set a **Default Max-age** as a fallback when origin headers are missing
+
+For detailed CDN setup instructions, see [Setting up Akamai CDNs](./cdn.mdx).
+
+## Related resources
+
+- [Set Headers Policy](../../policies/set-headers-outbound.mdx) - Add headers to
+  responses
+- [Caching Policy](../../policies/caching-inbound.mdx) - Zuplo's built-in
+  response caching
+- [Akamai Caching Documentation](https://techdocs.akamai.com/property-mgr/docs/caching-2) -
+  Complete Akamai caching reference

package/docs/dedicated/akamai/cdn.mdx

@@ -0,0 +1,156 @@
+---
+title: Setting up Akamai CDNs
+sidebar_label: Akamai CDN
+---
+
+<!-- vale Vale.Spelling["Edgescape","Maxage"] = NO -->
+
+When running managed dedicated on the Akamai Cloud, you need to set up 2 CDNs,
+one for your API endpoint deployments, and one for your developer portal.
+
+This document outlines the configurations you need to add to your Akamai CDNs to
+set them up to access your API gateway and developer portal.
+
+All configurations in this guide were done on the Akamai Property Manager, see
+the
+[Akamai docs](https://techdocs.akamai.com/property-mgr/docs/know-your-around)
+for more details.
+
+### Domains
+
+Before you configure the CDN for your API Gateway and Developer Portal, you will
+to decide how you would like your domains to be set up. Generally, you will
+provision two types of domains - a static domain for production and wildcard
+domains for preview environments.
+
+For preview environments, you will use wildcard domains so that each environment
+(normally each git branch) will have its own subdomain. For example, you might
+use `*.api.example.com` for the API gateway and `*.dev.example.com` for the
+developer portal. This will allow you to have URLs for each environment like
+`https://my-environment-123.api.example.com` and
+`https://my-environment-123.dev.example.com`.
+
+For production, you will want to use friendly domains like `api.example.com` and
+`developers.example.com`. Some customers also choose to host environments like
+staging on custom domains as well. This is up to you, just let your Zuplo
+account manager know how you would like to set up your domains.
+
+The setup for both configurations is the same, but the domain name and
+certificates will be different.
+
+### Prerequisites
+
+1. Provision the domains that you would like these CDNs to have and certificates
+   for those domains, according to the domain section.
+2. Request the Origin URLs for your API gateway and developer portal from your
+   Zuplo account manager.
+3. Let your Zuplo account manager know what hostnames/domains you will be using
+   in your CDNs.
+
+## API Gateway CDN
+
+This section guides you on how to configure your API Gateway CDN.
+
+Add the API gateway domain you provisioned to the Property Hostname for the API
+Gateway CDN. See the Akamai docs on
+[configuring HTTPS host names](https://techdocs.akamai.com/property-mgr/docs/serve-content-over-https).
+
+An example of how you might configure your API Gateway CDN domains for your
+preview environment and your production environment is below. Note that for your
+development environment CDN, you would need the wildcard domain since many
+development environments are named things like
+"api-main-someuuid.your-account.zuplo.work".
+
+![Configure multiple host names](../../../public/media/managed-dedicated-akamai/multiple_hostname_domains.png)
+
+In this example, the preview environment domain is the wildcard domain
+`*.zuplo.apidemo.org`, and the production domain is `ftest.zuplo.apidemo.org`.
+
+After configuring the CDN domains, make the following behavior changes:
+
+1. Create a Set Variable behavior with the following configurations (also shown
+   in the screenshot below):
+
+   a. Create a variable. This is called PMUSER_REPLACE_URL in the example below,
+   but you can name this anything. This is used for a URL REGEX replacement to
+   forward the proper host header to the Zuplo Origin.
+
+   b. The "Create Value From" field should be "Extract".
+
+   c. The "Get Data From" field should be "Request Header".
+
+   d. The "Header Name" field should be "Host".
+
+   e. The "Operation" field should be "Substitute (Regular Expression)".
+
+   f. The "Regex" field should be ^([^.]+)\..\*$.
+
+   g. The "Replacement" field should be something like
+   $1.your-account.zuplo.work. This is modeled off the origin URL. For example,
+   if the origin URL is "cname.your-account.zuplo.work", then the replacement
+   should be $1.your-account.zuplo.work.
+
+   h. Case Sensitive and Global Substitution should be set to "Off".
+
+   ![Set variable behavior](../../../public/media/managed-dedicated-akamai/regex-behaviour.png)
+
+2. Configure the Origin URL to point to the URL given to you by Zuplo for your
+   API gateway. Ensure that the Forward Host Header is configured to be a Custom
+   Value, and the value should be the variable you created in the previous step.
+   This would look something similar to below:
+   ![API gateway origin URL](../../../public/media/managed-dedicated-akamai/api_gateway_origin_url.png)
+
+3. Turn on Content Targeting (Edgescape) in the Geolocation rule in the Property
+   Manager Sidebar.
+   ![Geolocation](../../../public/media/managed-dedicated-akamai/geolocation.png)
+4. Enable all Allowed Methods rules (POST, OPTIONS, PUT, DELETE, PATCH) in the
+   Property Manager sidebar.
+
+## Developer Portal CDN
+
+This section guides you on how to set up the Developer Portal CDN.
+
+Add the Developer Portal gateway domain you provisioned to the Property Hostname
+for the API Gateway CDN. See the Akamai docs on
+[configuring HTTPS host names](https://techdocs.akamai.com/property-mgr/docs/serve-content-over-https).
+This is done similarly to your API gateway CDN hostname configuration, but with
+the domains you provisioned for your Developer Portal.
+
+An example of how you might configure your Developer Portal CDN domains for your
+preview environment and your production environment is below.
+
+![Configure multiple host names](../../../public/media/managed-dedicated-akamai/multiple_hostname_domains.png)
+
+In this example, the preview environment domain is the wildcard domain
+`*.zuplo.apidemo.org`, and the production domain is `ftest.zuplo.apidemo.org`.
+
+Under the Default Rule page, add the following behaviors:
+
+1.  Configure the origin URL to be the URL given to be the one given to you by
+    Zuplo for your Developer Portal. This will look similarly to how you
+    configured it for your API Gateway CDN. Take note that the Forward Host
+    header should also be set as the Origin Hostname.
+
+2.  Modify Incoming Request Header behavior, with the following fields:
+    - Action: Add
+    - Select Header Name: Other
+    - Custom Header Name: `X-Forwarded-Host`
+    - Header Value: `\{\{builtin.AK_HOST\}\}`.
+
+    This should look like the picture below:
+
+    ![Dev portal CDN base path and incoming header behaviors](../../../public/media/managed-dedicated-akamai/default_rule_dev_portal_config.png)
+
+3.  Caching, which should have the following configurations: Caching Option
+    should be set to "Honor origin Cache-Control and Expires", Force Validation
+    of stale objects should be set to "Always revalidate with origin", Default
+    Maxage should be set to 0 seconds, and all the Cache-Control header
+    directives should be enabled. This will look like below:
+
+    ![Dev portal caching behavior](../../../public/media/managed-dedicated-akamai/dev_portal_cdn_caching_behavior.png)
+
+Congratulations, you've set up your Akamai CDN to serve your API Gateway and
+Developer Portal! At this point, you should be able to test that these things
+are working by either hitting an endpoint in your API gateway (e.g.,
+mygateway.com/my/endpoint), or navigating to a page in your developer portal
+(e.g., myportal.com/home).

package/docs/dedicated/architecture.mdx

@@ -0,0 +1,208 @@
+---
+title: "Managed Dedicated: Architecture"
+sidebar_label: Architecture
+---
+
+Zuplo's managed dedicated instances are highly available, scalable, and secure.
+With a managed dedicated instance of Zuplo, your API Gateway runs on isolated
+instances and, when running on a cloud provider that supports it, a dedicated
+VPC. This document outlines the components and architecture of a managed
+dedicated instance of a Zuplo API Gateway.
+
+## Components
+
+A managed dedicated instance of Zuplo consists of the following components:
+
+- **API Gateway**: The API Gateway is the core component of Zuplo. It receives
+  incoming requests, routes them to the appropriate backend, and returns the
+  response to the client. The API Gateway handles authentication, authorization,
+  rate limiting, and other features.
+- **Gateway Services**: Zuplo, being a highly distributed API Gateway, uses
+  services to facilitate features such as
+  [Rate Limiting](../articles/step-2-add-rate-limiting.mdx) and
+  [API Key Authentication](../articles/api-key-management.mdx).
+- **Control Plane**: The Control Plane manages the configuration of the API
+  Gateway. It deploys new configurations, manages the lifecycle of the API
+  Gateway, and monitors its health.
+- **Analytics and Logging**: Zuplo provides analytics and logging for your API
+  Gateway. This includes request/response logging, error logging, and analytics
+  on request volume, latency, and other metrics.
+- **Developer Portal**: The Developer Portal is a web-based interface that
+  enables developers to interact with your API. It provides documentation,
+  testing tools, and other features to help developers integrate with your API.
+
+## Custom requirements
+
+Customize a managed dedicated instance of Zuplo to meet your specific
+requirements. Examples include:
+
+- **Regions & Availability Zones** - Zuplo can deploy to multiple regions,
+  availability zones, or data centers to provide high availability and low
+  latency.
+- **Developer Portal Hosting** - Zuplo manages the developer portal hosting from
+  a CDN. By default, the developer portal's static assets serve from a global
+  CDN. However, you can configure it to use only regional CDN locations if
+  required.
+- **Networking** - Zuplo can deploy with a variety of network configurations. To
+  learn more, see [Networking](./networking.mdx).
+- **Disabling Features** - Zuplo can disable unnecessary features for specific
+  use cases or those that don't meet security or compliance requirements. For
+  example, if you prefer custom analytics over the built-in API analytics, you
+  can disable the built-in analytics. When disabled, Zuplo stops collecting or
+  storing analytics data for the APIs.
+- **Custom Logging & Monitoring** - Zuplo can integrate with your existing
+  logging and monitoring systems. Logs and other data go directly from the API
+  Gateway to your logging provider. Zuplo doesn't collect or store this data.
+
+## Security
+
+All deployment models of Zuplo are secure and provide isolation between each
+customer and environment. Managed dedicated instances of Zuplo add the ability
+for you to customize the networking and connectivity to meet your specific
+security requirements.
+
+- **IAM Authorization**: Managed dedicated instances of Zuplo can use the IAM
+  capabilities to control traffic between the API Gateway and other services.
+- **Encryption**: Zuplo encrypts data both in transit and at rest. TLS secures
+  all data sent to or from the API Gateway. Zuplo encrypts stored data at rest.
+- **Access Control**: Zuplo provides robust authentication and access control
+  mechanisms. You control who has access to your API Gateway management
+  capabilities, what they can do, and what data they can access.
+- **Audit Logs**: Zuplo provides detailed audit logs of all management
+  operations. You can see who did what, when they did it, and what data they
+  accessed. Additionally, Zuplo maintains internal audit logs of all activity
+  performed by the Zuplo team.
+
+## Architecture
+
+The architecture of a managed dedicated instance of Zuplo provides you with all
+the benefits of a SaaS platform while giving you the control and isolation of a
+dedicated instance. The architecture is highly available, scalable, and secure.
+
+The following diagram shows the high-level architecture of a managed dedicated
+instance of Zuplo and how the components interact with each other.
+
+<Diagram height="h-64">
+  <DiagramNode id="client">Client</DiagramNode>
+  <DiagramGroup id="dedicated-vpc" label="Dedicated VPC">
+    <DiagramNode id="gateway" variant="zuplo">
+      Zuplo API Gateway
+    </DiagramNode>
+    <DiagramNode id="services" variant="zuplo">
+      Gateway Services
+    </DiagramNode>
+  </DiagramGroup>
+  <DiagramGroup id="customer-vpc" label="Customer VPC">
+    <DiagramNode id="backend">Backend</DiagramNode>
+  </DiagramGroup>
+  <DiagramNode id="control" variant="zuplo">
+    Control Plane
+  </DiagramNode>
+  <DiagramEdge from="client" to="gateway" />
+  <DiagramEdge from="gateway" to="backend" />
+  <DiagramEdge from="gateway" to="services" fromSide="bottom" toSide="top" />
+  <DiagramEdge from="control" to="gateway" />
+</Diagram>
+
+### Deployments
+
+When you deploy to your managed dedicated instance of Zuplo, you upload your
+source code and configuration files to the Control Plane. The Control Plane then
+deploys your API Gateway to the appropriate infrastructure. The API Gateway
+deploys to multiple nodes in multiple regions to provide high availability and
+low latency. If you run in multiple regions, the Control Plane manages the
+deployment to each region without any downtime.
+
+If you use Zuplo's Developer Portal, the control plane also deploys the web
+application that powers the Developer Portal. The Developer Portal hosts on a
+CDN to provide low latency access to end-users. The CDN configuration can be
+customized to meet your specific requirements.
+
+<Diagram height="h-56">
+  <DiagramNode id="source">Source Control</DiagramNode>
+  <DiagramNode id="control" variant="zuplo">
+    Control Plane
+  </DiagramNode>
+  <DiagramNode id="gateway" variant="zuplo">
+    Zuplo API Gateway
+  </DiagramNode>
+  <DiagramNode id="portal" variant="zuplo">
+    Dev Portal
+  </DiagramNode>
+  <DiagramEdge from="source" to="control" label="Deploy" />
+  <DiagramEdge from="control" to="gateway" />
+  <DiagramEdge from="control" to="portal" />
+</Diagram>
+
+### Multiple regions
+
+It's common practice to deploy your API Gateway to multiple regions to provide
+higher availability, lower latency, and meet regulatory requirements. Zuplo can
+deploy your API Gateway to multiple regions and manage the deployment to each
+region without any downtime.
+
+When you deploy your API Gateway to multiple regions, Zuplo uses a global load
+balancer to route traffic to the closest region. This provides low latency
+access to your APIs for end-users around the world. The load balancer also
+handles failover in case of an outage in one region.
+
+<Diagram height="h-64">
+  <DiagramNode id="client">Client</DiagramNode>
+  <DiagramNode id="lb">Load Balancer</DiagramNode>
+  <DiagramNode id="region1" variant="zuplo">
+    API Gateway (Region 1)
+  </DiagramNode>
+  <DiagramNode id="region2" variant="zuplo">
+    API Gateway (Region 2)
+  </DiagramNode>
+  <DiagramNode id="region3" variant="zuplo">
+    API Gateway (Region 3)
+  </DiagramNode>
+  <DiagramEdge from="client" to="lb" />
+  <DiagramEdge from="lb" to="region1" />
+  <DiagramEdge from="lb" to="region2" />
+  <DiagramEdge from="lb" to="region3" />
+</Diagram>
+
+### Instances
+
+Customers running managed dedicated Zuplo typically have multiple instances of
+Zuplo deployed. The most common case is to have a production instance and a
+non-production instance. The non-production instance is used to deploy and test
+changes to your API Gateway before deploying them to production. Each instance
+can run many different deployments. A typical setup, the production instance
+hosts only the production deployment, while the non-production instance hosts
+many other deployments (for example staging, development, QA, or any feature
+branch deployments).
+
+Each instance operates in isolation and runs within its own VPC or network.
+
+It's possible to have multiple instances depending on your requirements. For
+example, some customers have separate instances for production, staging, and
+development. For most customers, though, a single production and a single
+development instance are sufficient.
+
+During the onboarding process to Zuplo, an account manager will assist in
+determining the configuration that best meets the requirements. The project will
+be pre-configured with the agreed-upon number of instances, and rules will be
+set up to determine where each environment gets deployed.
+
+The most common setup is where your `main` branch deploys to production and all
+other branches deploy to a non-production environment, but this is fully
+customizable.
+
+<Diagram height="h-56">
+  <DiagramNode id="source">Source Control</DiagramNode>
+  <DiagramNode id="control" variant="zuplo">
+    Control Plane
+  </DiagramNode>
+  <DiagramNode id="prod" variant="zuplo">
+    API Gateway (Production)
+  </DiagramNode>
+  <DiagramNode id="non-prod" variant="zuplo">
+    API Gateway (Non-Production)
+  </DiagramNode>
+  <DiagramEdge from="source" to="control" label="Deploy" />
+  <DiagramEdge from="control" to="prod" />
+  <DiagramEdge from="control" to="non-prod" />
+</Diagram>

package/docs/dedicated/custom-domains.mdx

@@ -0,0 +1,31 @@
+---
+title: "Managed Dedicated: Custom Domains"
+sidebar_label: Custom Domains
+---
+
+Configuration of custom domains with your managed dedicated instance of Zuplo
+varies depending on how your
+[instance networking is configured](./networking.mdx). For customers using their
+Zuplo API Gateway as the ingress the bulk of the configuration is managed by
+Zuplo. You will be provided an IP address or CNAME to point your DNS to.
+Normally, Zuplo manages the SSL certificates in this type of configuration as
+well.
+
+Custom configurations are supported with Zuplo Managed Dedicated instances. For
+example, you can use your own SSL certificates, or if you are using your own VPC
+as the ingress, you can even use your own IP addresses.
+
+For the full details on how to configure custom domains with your managed
+dedicated instance of Zuplo, please contact your account manager.
+
+## Preview environments
+
+By default, preview environments are deployed to a wildcard subdomain managed by
+Zuplo. For example, if your account name is `acme`, the preview environment URLs
+are hosted at `*.acme.zuplo.work`, so each environment will have a URL like
+`https://my-environment-123.acme.zuplo.work`.
+
+Some customer want to use their own domain for preview environments. For
+example, `*.dev.acme.com`. This is supported with Zuplo Managed Dedicated
+instances. Depending on your cloud provider, this may require you to create a
+wildcard certificate for your domain.