@zuplo/runtime 6.74.10 → 6.74.12

package/out/types/index.d.ts

@@ -3162,6 +3162,168 @@ declare interface Category {
   Attribute: Attribute_2[];
 }
 
+/**
+ * How to combine the configured client policy with a `Cache-Control` the upstream already sent. `strictest` (default) emits the more conservative of the two — the lower `max-age` and the union of restrictive directives. `replace` overwrites whatever upstream sent. `preserve` leaves the upstream header untouched and only adds the CDN headers.
+ * @public
+ */
+declare type CdnCacheControlClientMode = "strictest" | "replace" | "preserve";
+
+/**
+ * The `Cache-Control` sent to the browser or app. Separate from `edge` so the CDN can absorb load without clients holding stale data.
+ * @public
+ */
+declare interface CdnCacheControlClientOptions {
+  /**
+   * Seconds the client may reuse this response. Omit to send no `max-age`.
+   */
+  maxAge?: number;
+  visibility?: CdnCacheControlClientVisibility;
+  /**
+   * Adds `no-cache`, so the client must revalidate before reusing the response. Distinct from `visibility: no-store`, which forbids storing it at all.
+   */
+  noCache?: boolean;
+  /**
+   * Adds `must-revalidate`, so the client may not serve the response once stale.
+   */
+  mustRevalidate?: boolean;
+  mode?: CdnCacheControlClientMode;
+}
+
+/**
+ * `public` allows any cache to store the response, `private` restricts it to the client's own cache, `no-store` forbids client caching entirely. With `strategy: targeted` a `private`/`no-store` client policy still permits edge caching, because the CDN reads its own header.
+ * @public
+ */
+declare type CdnCacheControlClientVisibility =
+  | "public"
+  | "private"
+  | "no-store";
+
+/**
+ * A cache policy for one response: what the static options normalise into, and
+ * what a `cacheConfig` function returns.
+ *
+ * A function's return value **replaces** this wholesale rather than being merged
+ * field by field. Returning nothing falls back to the static options, which is
+ * how a route enforces defaults and overrides them in only the few cases that
+ * need it.
+ */
+export declare interface CdnCacheControlConfig {
+  /** Set to false to emit no edge headers or tags for this response. */
+  cache?: boolean;
+  edge?: EdgeCacheDirectives;
+  client?: ClientCacheDirectives;
+  tags?: string[];
+}
+
+/**
+ * A `cacheConfig` function: returns the CDN cache policy for one response.
+ *
+ * Return `undefined` or `null` to fall back to the static options, which is how
+ * a route enforces defaults and overrides them only where it needs to.
+ *
+ * @public
+ */
+export declare type CdnCacheControlConfigFn = (
+  response: Response,
+  request: ZuploRequest,
+  context: ZuploContext
+) =>
+  | CdnCacheControlConfig
+  | undefined
+  | null
+  | Promise<CdnCacheControlConfig | undefined | null>;
+
+/**
+ * A function that overrides the cache configuration per response, for rules that cannot be expressed statically (per-entity purge tags, a TTL that depends on a response header, or skipping an empty result set). Returning nothing (`undefined` or `null`) falls back to the `edge`, `client` and `tags` options, so those stay the enforced default and the function only handles exceptions. A returned config **replaces** those options wholesale rather than being merged directive by directive, so include every directive the response needs. Return `{ cache: false }` to skip caching a response entirely — note that also sends `Cache-Control: no-store` to the client unless `client.mode` is `preserve`. The function receives the live response: it must not consume the body, and should call `response.clone()` if it needs to read it.
+ * @public
+ */
+declare interface CdnCacheControlConfigFunction {
+  /**
+   * Specifies the export that holds your cache config function, e.g. `default`, `cdnCacheConfig`.
+   */
+  export: string;
+  /**
+   * Specifies the module that holds your cache config function, in the format `$import(./modules/my-module)`.
+   */
+  module: string;
+}
+
+/**
+ * How long the CDN may serve this response. These directives are sent only to the CDN, never to the browser (unless `strategy` is `s-maxage`).
+ * @public
+ */
+declare interface CdnCacheControlEdgeOptions {
+  /**
+   * Seconds the CDN may serve this response without revalidating.
+   */
+  maxAge: number;
+  /**
+   * Seconds the CDN may keep serving a stale response while it revalidates in the background. Not expressible in Akamai's `Edge-Control` — configure it in Property Manager, or use `strategy: s-maxage`.
+   */
+  staleWhileRevalidate?: number;
+  /**
+   * Seconds the CDN may serve a stale response when the gateway returns an error. Not expressible in Akamai's `Edge-Control` — configure it in Property Manager, or use `strategy: s-maxage`.
+   */
+  staleIfError?: number;
+}
+
+/**
+ * Sets the response headers that tell a CDN how long it may cache a response and
+ * which purge tags it belongs to, separately from what the browser is told.
+ *
+ * @title CDN Cache Control
+ * @product api-gateway
+ * @public
+ * @param response - The Response
+ * @param request - The ZuploRequest
+ * @param context - The ZuploContext
+ * @param options - The policy options set in policies.json
+ * @param policyName - The name of the policy as set in policies.json
+ * @returns A Response
+ */
+export declare const CdnCacheControlOutboundPolicy: OutboundPolicyHandler<CdnCacheControlOutboundPolicyOptions>;
+
+/**
+ * The options for this policy.
+ * @public
+ */
+export declare interface CdnCacheControlOutboundPolicyOptions {
+  cdn: CdnCacheControlVendor;
+  strategy?: CdnCacheControlStrategy;
+  edge?: CdnCacheControlEdgeOptions;
+  client?: CdnCacheControlClientOptions;
+  /**
+   * Purge tags, rendered in the target CDN's format: comma-joined `Edge-Cache-Tag` (Akamai), space-joined `Surrogate-Key` (Fastly), comma-joined `Cache-Tag` (Cloudflare). CloudFront has no tag purge and rejects this option. Tags are validated against the CDN's length and character limits, because an over-long tag header is silently truncated rather than rejected.
+   */
+  tags?: string[];
+  /**
+   * Request headers that vary this response, unioned with any `Vary` the upstream already sent and emitted as `Vary`. The union is deliberate: replacing an upstream `Vary: Authorization` would stop a shared cache keying on it and let it serve one user's response to another. Off by default: Akamai skips caching any response carrying `Vary` until Cache ID Modification is configured, so enabling this can silently disable edge caching entirely.
+   */
+  vary?: string[];
+  /**
+   * When true (default), an upstream `Cache-Control` of `no-store`/`no-cache`/`private`, or a `Set-Cookie` on the response, suppresses all edge headers and purge tags. This keeps the application's ability to mark a response uncacheable. Set to false to override it — on Akamai this emits `Edge-Control: !no-store`.
+   */
+  respectUpstream?: boolean;
+  cacheConfig?: CdnCacheControlConfigFunction;
+}
+
+/**
+ * How the edge TTL is carried. `targeted` uses the CDN's own header (`Edge-Control`, `Surrogate-Control`, `CDN-Cache-Control`) and is the only way to cache at the edge without also caching in the browser. `s-maxage` folds the edge TTL into `Cache-Control` instead, for a property that honors origin `Cache-Control` but not the targeted header. Defaults to `targeted`, except on a CDN that reads no targeted header — CloudFront defaults to `s-maxage`, which is the only thing it supports.
+ * @public
+ */
+declare type CdnCacheControlStrategy = "targeted" | "s-maxage";
+
+/**
+ * The CDN in front of this gateway. Required, with no default — each CDN reads a different header for shared-cache TTL and purge tags, and a wrong guess fails silently. Use `generic` for an RFC 9213 CDN that is not listed.
+ * @public
+ */
+declare type CdnCacheControlVendor =
+  | "akamai"
+  | "fastly"
+  | "cloudflare"
+  | "cloudfront"
+  | "generic";
+
 /**
  * Changes the HTTP method of the incoming request.
  *
@@ -3388,6 +3550,14 @@ export declare interface ClerkJwtInboundPolicyOptions {
   oAuthResourceMetadataEnabled?: boolean;
 }
 
+/** The client (browser/app) half of the policy. */
+export declare interface ClientCacheDirectives {
+  maxAge?: number;
+  visibility?: CdnCacheControlClientVisibility;
+  mustRevalidate?: boolean;
+  noCache?: boolean;
+}
+
 /**
  * Authentication options for OIDC authentication.
  * @public
@@ -4603,6 +4773,13 @@ export declare class DynatraceMetricsPlugin extends MetricsPlugin {
   static setContext(context: ZuploContext, data: DynatraceMetricsContext): void;
 }
 
+/** The edge (shared cache) half of the policy. */
+export declare interface EdgeCacheDirectives {
+  maxAge: number;
+  staleWhileRevalidate?: number;
+  staleIfError?: number;
+}
+
 declare interface EmbeddingsFallbacks {
   fallback?: FallbackModel;
   quotaFallback?: QuotaFallbackModel;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zuplo/runtime",
   "type": "module",
-  "version": "6.74.10",
+  "version": "6.74.12",
   "repository": "https://github.com/zuplo/zuplo",
   "author": "Zuplo, Inc.",
   "exports": {