zuplo 7.0.0 → 7.0.1

package/docs/dedicated/akamai/caching.mdx

@@ -2,22 +2,23 @@
 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.
+  Cache Zuplo responses at the Akamai edge with the CDN Cache Control policy.
+  Covers Edge-Control TTLs, Edge-Cache-Tag purge tags, and the Property Manager
+  settings that make them work.
 ---
 
-<!-- vale Vale.Spelling = NO -->
+An Akamai property in front of a Zuplo gateway can absorb most of the read
+traffic an API serves. A catalog endpoint that returns the same payload to every
+caller doesn't need to reach the gateway 40,000 times an hour. It needs to reach
+it once every 30 minutes, and again the moment the catalog changes.
 
-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.
+The CDN Cache Control policy writes the headers Akamai reads to make that
+happen: `Edge-Control` for the edge TTL, and `Edge-Cache-Tag` for the purge tags
+that let a content update invalidate the edge in seconds instead of waiting out
+the TTL.
 
 ## 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
@@ -28,185 +29,289 @@ API Gateway and improve response times for clients.
   <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
+    Forward to origin
   </DiagramMessage>
   <DiagramMessage from="gateway" to="cdn">
-    Response + Cache-Control headers
+    Response + Edge-Control + tag
   </DiagramMessage>
   <DiagramMessage from="cdn" to="client">
-    Response (cached at edge)
+    Response + Cache-Control (client TTL)
   </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:
+What the edge does depends on the property configuration and on the headers
+Zuplo sends:
 
-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
+1. **Akamai Property Manager settings.** The default caching rules configured in
+   your CDN property.
+2. **Origin response headers.** What Zuplo sends, which can override or
+   influence those defaults once the property is configured to honor them.
 
-When your Akamai property is configured to "Honor origin Cache-Control and
-Expires" headers, Zuplo can control caching behavior on a per-response basis.
+The edge TTL and the purge tags travel in headers the client never acts on, so
+the response the client receives carries only `Cache-Control`. Akamai also
+strips `Edge-Cache-Tag` before responses leave the edge unless the Cache Tag
+Visibility behavior is enabled, so tags stay internal by default.
 
 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
+## Set the edge TTL and purge tags
 
-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:
+Add the CDN Cache Control policy to the outbound pipeline of any route whose
+responses are safe for a shared cache to replay. Set `cdn` to `akamai` and the
+policy renders everything else into Akamai's dialect.
 
-| 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
+```json title="config/policies.json"
+{
+  "name": "catalog-edge-cache",
+  "policyType": "cdn-cache-control-outbound",
+  "handler": {
+    "export": "CdnCacheControlOutboundPolicy",
+    "module": "$import(@zuplo/runtime)",
+    "options": {
+      "cdn": "akamai",
+      "edge": {
+        "maxAge": 1800
+      },
+      "client": {
+        "visibility": "public",
+        "maxAge": 60
+      },
+      "tags": ["catalog", "cities"]
+    }
+  }
+}
+```
 
-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:
+Akamai receives:
 
+```http
+Cache-Control: public, max-age=60
+Edge-Control: cache-maxage=30m
+Edge-Cache-Tag: catalog,cities
 ```
-Cache-Control: public, max-age=60, s-maxage=3600
+
+The edge holds the response for 30 minutes and absorbs the traffic. Clients
+re-check every 60 seconds, so a purge of the `cities` tag reaches every caller
+within a minute rather than within half an hour.
+
+The policy also removes an `Edge-Control` header your backend set that the
+policy is not writing itself, because a targeted header outranks `Cache-Control`
+and an upstream value would silently beat the TTL configured here.
+
+:::note
+
+`respectUpstream` is on by default. An upstream `Cache-Control` of `no-store`,
+`no-cache`, or `private`, or a `Set-Cookie` on the response, suppresses every
+edge header and purge tag. The backend keeps the final say even when the policy
+is applied broadly.
+
+:::
+
+Splitting the edge TTL from the client TTL is the point of the policy. Because
+only Akamai reads `Edge-Control`, `Cache-Control` stays free to say whatever the
+client should do, down to `private, max-age=0` for a response that requires an
+`Authorization` header but is identical for every caller:
+
+```http
+Cache-Control: private, max-age=0
+Edge-Control: cache-maxage=5m
 ```
 
-This example caches content at the CDN for 1 hour while instructing browsers to
-cache for only 1 minute.
+Akamai reads `Edge-Control` and ignores `Cache-Control` for its own decision, so
+it never sees the `private`. The edge caches; nothing downstream does. For the
+reasoning behind the split and the variations on it, see
+[Cache at the CDN](../../caching/cdn-caching.mdx).
+
+:::caution{title="Don't put the Caching policy on the same route"}
 
-### Common Cache-Control patterns
+Keep the [Caching](../../policies/caching-inbound.mdx) policy off any route that
+uses CDN Cache Control. The Caching policy serves a hit from an inbound policy,
+which short-circuits the pipeline before outbound policies run, so CDN Cache
+Control never executes on a gateway cache hit. Akamai then receives the copy
+that the Caching policy stored, and the Caching policy sanitizes every copy it
+stores: it drops several CDN cache headers (exactly which ones depends on the
+CDN) and overwrites `Cache-Control` with its own `s-maxage` (its TTL, 60 seconds
+by default). The edge and client TTLs collapse into one number. Cache misses run
+the full outbound stack and look correct, so the problem stays invisible until
+traffic warms the cache, and nothing logs it. Pick one place to cache.
 
-| 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
+## Akamai-specific constraints
 
-### Using the Set Headers policy
+### Stale serving needs Property Manager
 
-The simplest way to add cache headers is using the
-[Set Headers Outbound Policy](../../policies/set-headers-outbound.mdx):
+`edge.staleWhileRevalidate` and `edge.staleIfError` have no `Edge-Control`
+equivalent. Rather than dropping those directives silently, the policy rejects
+the combination on Akamai. Two ways forward:
+
+- **Configure stale serving in Property Manager.** Leave
+  `edge.staleWhileRevalidate` and `edge.staleIfError` unset, keep `strategy` at
+  its default, and let the property decide how long the edge may serve a stale
+  object while revalidating or while the origin is failing.
+- **Set `strategy` to `s-maxage`.** The edge TTL and the stale windows then
+  travel in `Cache-Control`, which works on a property that honors origin
+  `Cache-Control` but has not enabled `Edge-Control`.
 
 ```json title="config/policies.json"
 {
-  "name": "cache-one-hour",
-  "policyType": "set-headers-outbound",
+  "name": "catalog-edge-cache",
+  "policyType": "cdn-cache-control-outbound",
   "handler": {
-    "export": "SetHeadersOutboundPolicy",
+    "export": "CdnCacheControlOutboundPolicy",
     "module": "$import(@zuplo/runtime)",
     "options": {
-      "headers": [
-        {
-          "name": "Cache-Control",
-          "value": "public, max-age=60, s-maxage=3600"
-        }
-      ]
+      "cdn": "akamai",
+      "strategy": "s-maxage",
+      "edge": {
+        "maxAge": 1800,
+        "staleIfError": 86400
+      },
+      "client": {
+        "visibility": "public",
+        "maxAge": 60
+      }
     }
   }
 }
 ```
 
-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");
-  }
+`s-maxage` gives up the split: every directive becomes visible to clients, and
+caching at the edge without caching in the browser is no longer expressible.
+Prefer Property Manager for stale serving when the property already honors
+`Edge-Control`.
+
+### Vary suppresses caching
+
+The `vary` option is off by default because of a behavior specific to Akamai:
+the edge skips caching any response carrying a `Vary` header until Cache ID
+Modification is configured in Property Manager. Turning `vary` on can therefore
+disable edge caching entirely while every response still looks correct. The
+policy logs a warning when `vary` is set together with `cdn: akamai`.
+
+If a response genuinely varies by a request header, put that header in the cache
+key with
+[Cache ID Modification](https://techdocs.akamai.com/property-mgr/docs/cache-id-modification)
+instead of relying on `Vary`. Cache-key configuration is not expressible in
+response headers and stays CDN configuration.
+
+### Purge tag limits
+
+Tags are validated against Akamai's limits before they are emitted, because the
+failure mode at the edge is silent truncation rather than an error.
+
+| Limit                     | Akamai value                     |
+| ------------------------- | -------------------------------- |
+| Maximum tag length        | 128 characters                   |
+| Maximum tags per response | 128                              |
+| Maximum header size       | 8192 bytes                       |
+| Disallowed characters     | spaces, commas, colons, brackets |
+
+A static tag in `config/policies.json` that violates a limit is a configuration
+error you fix before deploying. A tag produced at request time is dropped and
+logged as a warning instead.
+
+## Purge by tag with Fast Purge
+
+Tagging responses is what makes targeted invalidation possible. A city sync that
+changes one record can invalidate `city-42` across every edge server, leaving
+the rest of the catalog cached. Without tags, the choices are waiting out the
+TTL or purging far more than changed.
+
+The policy emits the tags. It does not purge. Invalidation is a
+[Fast Purge](https://techdocs.akamai.com/purge-cache/docs) API call from your
+own tooling: a webhook on a content change, a step at the end of a sync job, or
+an operator-run script. Point it at the
+[invalidate-by-tag endpoint](https://techdocs.akamai.com/purge-cache/reference/post-invalidate-tag)
+with the same tag strings the policy emits.
+
+Two Akamai details worth knowing:
+
+- Akamai strips `Edge-Cache-Tag` from responses before they reach end users
+  unless the
+  [Cache Tag Visibility](https://techdocs.akamai.com/property-mgr/docs/cache-tag-visibility)
+  behavior is enabled. Enable it temporarily to confirm tags are landing, then
+  turn it back off.
+- Tag names must respect the charset and limits above. See Akamai's guide to
+  [assigning cache tags](https://techdocs.akamai.com/purge-cache/docs/assign-cache-tags).
+
+## Per-response cache rules
+
+Static options cover a route. Per-entity tags such as `city-42`, a TTL that
+depends on a response header, or refusing to cache an empty result set cannot be
+expressed statically. For those, the policy takes a `cacheConfig` function that
+returns cache intent per response, and falls back to the static options whenever
+the function returns nothing.
+
+The function returns intent rather than headers, so the same module works
+unchanged if the CDN in front of the gateway changes. See
+[Per-response cache rules](../../caching/dynamic-cache-rules.mdx) for the
+contract, the return values, and worked examples.
+
+## Configure Property Manager
+
+None of the headers above matter until the property is configured to act on
+them. This is the part you cannot do from Zuplo.
+
+1. **Caching behavior.** Set the Caching Option to "Honor origin Cache-Control
+   and Expires" and enable the directives you want honored (`max-age`,
+   `s-maxage`, `no-store`, `private`, `must-revalidate`). Without this the
+   property applies its own fixed TTL and ignores what the gateway sends.
+2. **Honor `Edge-Control`.** Confirm with your Akamai team that the property
+   acts on `Edge-Control`. `Edge-Control: cache-maxage` outranks `Cache-Control`
+   at the edge, which is what keeps the edge TTL out of the client's copy. If
+   the property ignores it, set `strategy` to `s-maxage` until it is enabled.
+3. **Default Max-age.** Set a fallback TTL for responses that arrive with no
+   cache headers, such as routes that do not carry the policy.
+4. **Cache ID Modification.** Configure this if a response varies by a request
+   header. It is also the prerequisite for caching any response that carries a
+   `Vary` header.
+5. **Cache Tag Visibility.** Off by default, which keeps `Edge-Cache-Tag`
+   internal. Turn it on only while verifying that tags reach the edge.
 
-  return new Response(response.body, {
-    status: response.status,
-    statusText: response.statusText,
-    headers,
-  });
-}
-```
+For detailed CDN setup instructions, see [Setting up Akamai CDNs](./cdn.mdx).
 
 ## 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.
+By default, Akamai sends clients the smaller of the origin's `Cache-Control`
+`max-age` and the remaining edge cache lifetime, so browsers never cache content
+longer than it remains valid at the edge. With the policy in place, the origin
+`max-age` is whatever `client.maxAge` sets; the edge TTL lives in `Edge-Control`
+and never reaches the client at all.
 
-For more information, see
+Property Manager's downstream cacheability settings can override this. 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).
+1. **Make the client TTL much shorter than the edge TTL.** The edge is what you
+   can purge; clients are not. A short `client.maxAge` with a long `edge.maxAge`
+   gives you offload and control at the same time.
+2. **Tag by entity, not just by route.** `city-42` lets you purge one city;
+   `cities` alone forces you to purge them all.
+3. **Leave `respectUpstream` on** so the application keeps the ability to mark a
+   response uncacheable.
+4. **Verify at the edge, not just at the gateway.** `curl -I` against the Zuplo
+   URL shows the headers the policy emits. Whether Akamai honors them depends on
+   the property configuration above.
 
 ## 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
+- [Cache at the CDN](../../caching/cdn-caching.mdx) — the CDN Cache Control
+  policy across every supported CDN
+- [Caching in Zuplo](../../caching/overview.mdx) — where to cache, and how to
+  choose
+- [CDN Cache Control policy](../../policies/cdn-cache-control-outbound.mdx) —
+  every configuration option in detail
+- [Caching policy](../../policies/caching-inbound.mdx) — the gateway-side
+  alternative, not to be combined with CDN Cache Control
+- [Akamai caching documentation](https://techdocs.akamai.com/property-mgr/docs/caching-2)
+  — the complete Akamai caching reference
+- [Akamai Fast Purge](https://techdocs.akamai.com/purge-cache/docs) — purge by
+  tag from your own tooling

package/docs/dev-portal/local-development.mdx

@@ -11,7 +11,7 @@ get started.
 
 ## Prerequisites
 
-- [Node.js](https://nodejs.org) `>=v22.7.0` (or `>=20.19` will work as well)
+- [Node.js](https://nodejs.org) `>=v24.0.0`
 - [Git](https://git-scm.com)
 
 ## Getting Started

package/docs/dev-portal/migration.mdx

@@ -214,7 +214,7 @@ process, continue with the manual migration steps below.
      },
      "devDependencies": {
        "typescript": "^5",
-       "@types/node": "^22",
+       "@types/node": "^24",
        "@types/react": "^19",
        "@types/react-dom": "^19"
      }

package/docs/mcp-gateway/quickstart-local.mdx

@@ -28,7 +28,7 @@ Portal UI.
 
 ## Prerequisites
 
-- [Node.js](https://nodejs.org/en/download) 20 or higher.
+- [Node.js](https://nodejs.org/en/download) 24 or higher.
 - A local Zuplo project. Create an empty one with:
 
   ```bash

package/docs/policies/api-key-inbound/schema.json

@@ -58,13 +58,15 @@
               "type": "string",
               "x-show-example": false,
               "x-advanced": true,
-              "description": "The ID of the API Key service bucket. Preferred over bucketName. Defaults to the autogenerated bucket ID for your project."
+              "description": "The ID of the API Key service bucket. Defaults to the autogenerated bucket ID for your project."
             },
             "bucketName": {
               "type": "string",
               "x-show-example": false,
               "x-advanced": true,
-              "description": "The name of the API Key service bucket. Defaults to the autogenerated bucket name for your project."
+              "deprecated": true,
+              "doNotSuggest": true,
+              "description": "\\*\\*Deprecated\\*\\*: Use `bucketId` instead. The name of the API Key service bucket."
             },
             "allowUnauthenticatedRequests": {
               "type": "boolean",

package/docs/programmable-api/cache.mdx

@@ -184,3 +184,10 @@ const cachedResponse = new Response(response, {
 // Add the response to the cache
 await cache.put(request, cachedResponse);
 ```
+
+## See Also
+
+- [Caching in Zuplo](../caching/overview.mdx) - Where the programmable cache
+  sits relative to the CDN, gateway, and client caches
+- [Build a custom caching policy](../caching/custom-caching-policy.mdx) - A
+  worked inbound and outbound policy pair built on `caches.open`

package/docs/programmable-api/memory-zone-read-through-cache.mdx

@@ -94,3 +94,5 @@ export default async function handler(
 - [ZoneCache](./zone-cache.mdx) - For distributed caching across zones
 - [StreamingZoneCache](./streaming-zone-cache.mdx) - For caching streaming data
 - [BackgroundLoader](./background-loader.mdx) - For automatic cache population
+- [Cache part of a response](../caching/partial-response-caching.mdx) - Choosing
+  between this cache and ZoneCache for a cached response fragment

package/docs/programmable-api/streaming-zone-cache.mdx

@@ -142,5 +142,7 @@ export default async function handler(
 - [ZoneCache](./zone-cache.mdx) - For caching JSON and other structured data
 - [MemoryZoneReadThroughCache](./memory-zone-read-through-cache.mdx) - For
   in-memory caching
+- [Caching in Zuplo](../caching/overview.mdx) - Where the programmable cache
+  sits relative to the CDN and gateway caches
 - [Web Streams API](https://developer.mozilla.org/en-US/docs/Web/API/Streams_API) -
   MDN documentation on streams

package/docs/programmable-api/zone-cache.mdx

@@ -141,3 +141,10 @@ For full Zuplo platform limits see the
 
 - Maximum size per cached item: 512 MB
 - Maximum cache calls per request: 1000
+
+## See Also
+
+- [Cache part of a response](../caching/partial-response-caching.mdx) - Cache a
+  shared fragment in ZoneCache and fetch only the caller-specific slice
+- [Caching in Zuplo](../caching/overview.mdx) - How ZoneCache compares to the
+  CDN, gateway, and client caching layers

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zuplo",
-  "version": "7.0.0",
+  "version": "7.0.1",
   "type": "module",
   "description": "The programmable API Gateway",
   "author": "Zuplo, Inc.",
@@ -19,9 +19,9 @@
     "zuplo": "zuplo.js"
   },
   "dependencies": {
-    "@zuplo/cli": "7.0.0",
-    "@zuplo/core": "7.0.0",
-    "@zuplo/runtime": "7.0.0",
-    "@zuplo/test": "7.0.0"
+    "@zuplo/cli": "7.0.1",
+    "@zuplo/core": "7.0.1",
+    "@zuplo/runtime": "7.0.1",
+    "@zuplo/test": "7.0.1"
   }
 }