@timber-js/app 0.2.0-alpha.19 → 0.2.0-alpha.190

package/src/cdn/headers.ts

@@ -0,0 +1,153 @@
+/**
+ * CDN header helpers — pure functions that build Cache-Control,
+ * CDN-Cache-Control, Surrogate-Control, and Surrogate-Key header values.
+ *
+ * These are developer-elected utilities for wiring CDN caching in
+ * proxy.ts / middleware.ts. The framework never sets these automatically.
+ * See design/25-production-deployments.md §Layer 2.
+ */
+
+export interface CacheControlOptions {
+  /** Mark the response as publicly cacheable (CDN, shared caches). */
+  public?: boolean;
+  /** Mark the response as private (browser cache only, not CDN). */
+  private?: boolean;
+  /** Max freshness in seconds for the browser/client. */
+  maxAge?: number;
+  /** Max freshness in seconds for shared caches (CDN, proxy). Overrides maxAge for CDNs. */
+  sMaxAge?: number;
+  /** Serve stale while revalidating in the background (seconds). */
+  staleWhileRevalidate?: number;
+  /** Serve stale on upstream error (seconds). */
+  staleIfError?: number;
+  /** Response must not be stored by any cache. */
+  noStore?: boolean;
+  /** Caches must revalidate before using a stored response. */
+  noCache?: boolean;
+  /** Caches must revalidate once stale — no serving stale without checking origin. */
+  mustRevalidate?: boolean;
+  /** Response will not change — allows aggressive caching. Pair with hashed URLs. */
+  immutable?: boolean;
+}
+
+/**
+ * Build a `Cache-Control` header value.
+ *
+ * ```ts
+ * ctx.headers.set('Cache-Control', cacheControl({
+ *   public: true,
+ *   maxAge: 300,
+ *   staleWhileRevalidate: 60,
+ * }));
+ * ```
+ */
+export function cacheControl(opts: CacheControlOptions): string {
+  if (opts.public && opts.private) {
+    throw new Error('cacheControl: public and private are mutually exclusive');
+  }
+  if (opts.noStore && opts.maxAge !== undefined) {
+    throw new Error('cacheControl: noStore makes maxAge meaningless — remove one');
+  }
+
+  const parts: string[] = [];
+
+  parts.push(opts.public ? 'public' : 'private');
+
+  if (opts.noStore) parts.push('no-store');
+  if (opts.noCache) parts.push('no-cache');
+  if (opts.maxAge !== undefined) parts.push(`max-age=${opts.maxAge}`);
+  if (opts.sMaxAge !== undefined) parts.push(`s-maxage=${opts.sMaxAge}`);
+  if (opts.staleWhileRevalidate !== undefined)
+    parts.push(`stale-while-revalidate=${opts.staleWhileRevalidate}`);
+  if (opts.staleIfError !== undefined) parts.push(`stale-if-error=${opts.staleIfError}`);
+  if (opts.mustRevalidate) parts.push('must-revalidate');
+  if (opts.immutable) parts.push('immutable');
+
+  return parts.join(', ');
+}
+
+export interface SurrogateControlOptions {
+  /** Max freshness in seconds for the surrogate (CDN). */
+  maxAge?: number;
+  /** Do not store in surrogate cache. */
+  noStore?: boolean;
+  /** Serve stale while revalidating (seconds). */
+  staleWhileRevalidate?: number;
+  /** Serve stale on error (seconds). */
+  staleIfError?: number;
+}
+
+/**
+ * Build a `Surrogate-Control` header value (Fastly, Akamai, Varnish).
+ *
+ * ```ts
+ * ctx.headers.set('Surrogate-Control', surrogateControl({ maxAge: 3600 }));
+ * ```
+ */
+export function surrogateControl(opts: SurrogateControlOptions): string {
+  const parts: string[] = [];
+  if (opts.noStore) parts.push('no-store');
+  if (opts.maxAge !== undefined) parts.push(`max-age=${opts.maxAge}`);
+  if (opts.staleWhileRevalidate !== undefined)
+    parts.push(`stale-while-revalidate=${opts.staleWhileRevalidate}`);
+  if (opts.staleIfError !== undefined) parts.push(`stale-if-error=${opts.staleIfError}`);
+  return parts.join(', ');
+}
+
+/**
+ * Build a `CDN-Cache-Control` header value (Cloudflare).
+ * Same directive syntax as Surrogate-Control but recognized by Cloudflare.
+ *
+ * ```ts
+ * ctx.headers.set('CDN-Cache-Control', cdnCacheControl({ maxAge: 3600 }));
+ * ```
+ */
+export function cdnCacheControl(opts: SurrogateControlOptions): string {
+  return surrogateControl(opts);
+}
+
+/**
+ * Build a `Surrogate-Key` header value — space-separated tags for CDN
+ * tag-based purging (Fastly, Cloudflare Enterprise, Akamai).
+ *
+ * Tags are deduplicated. Tags must not contain spaces or double quotes
+ * (these are separators/delimiters in the header format).
+ *
+ * ```ts
+ * ctx.headers.set('Surrogate-Key', surrogateKey(['products', `product:${id}`]));
+ * ```
+ */
+export function surrogateKey(tags: string[]): string {
+  for (const tag of tags) {
+    if (tag.includes(' ') || tag.includes('"')) {
+      throw new Error(`surrogateKey: tag "${tag}" must not contain spaces or double quotes`);
+    }
+  }
+  return [...new Set(tags)].join(' ');
+}
+
+/**
+ * Build a `Cache-Tag` header value — comma-separated tags for Cloudflare
+ * Workers Cache tag-based purging. Available on ALL Cloudflare plans.
+ *
+ * Tags are deduplicated. Tags must not contain commas (the delimiter).
+ * Maximum tag length is 1024 characters per Cloudflare's limits.
+ *
+ * Use this instead of `surrogateKey()` when using Cloudflare Workers Cache
+ * (ctx.cache.purge). Workers Cache reads `Cache-Tag`, not `Surrogate-Key`.
+ *
+ * ```ts
+ * ctx.headers.set('Cache-Tag', cacheTag(['products', `product:${id}`]));
+ * ```
+ */
+export function cacheTag(tags: string[]): string {
+  for (const tag of tags) {
+    if (tag.includes(',')) {
+      throw new Error(`cacheTag: tag "${tag}" must not contain commas`);
+    }
+    if (tag.length > 1024) {
+      throw new Error(`cacheTag: tag "${tag}" exceeds 1024-character limit`);
+    }
+  }
+  return [...new Set(tags)].join(',');
+}

package/src/cdn/index.ts

@@ -0,0 +1,17 @@
+// @timber-js/app/cdn — CDN integration helpers
+//
+// Header utilities and purge handler for CDN caching. Developer-elected,
+// never automatic. See design/25-production-deployments.md §Layer 2.
+
+export { cacheControl, surrogateKey, surrogateControl, cdnCacheControl, cacheTag } from './headers';
+export type { CacheControlOptions, SurrogateControlOptions } from './headers';
+
+export { setCdnPurgeHandler, getCdnPurgeHandler } from './purge-store';
+export type { CdnPurgeHandler } from './purge-store';
+
+// Platform-specific purge handlers are at their own entry points:
+//   @timber-js/app/cdn/cloudflare         → CloudflarePurge (REST API, Enterprise)
+//   @timber-js/app/cdn/cloudflare-workers → WorkersCachePurge (ctx.cache, all plans)
+//   @timber-js/app/cdn/fastly             → FastlyPurge
+// Same pattern as @timber-js/app/cache/stores/* — keeps platform
+// dependencies out of the main CDN import.

package/src/cdn/purge-store.ts

@@ -0,0 +1,34 @@
+/**
+ * CDN purge handler singleton — same pattern as cache/handler-store.ts.
+ *
+ * Set via timber.config.ts or setCdnPurgeHandler() at boot. When set,
+ * cache.invalidate({ tag }) also triggers CDN purge for the invalidated
+ * tags, so revalidateTag() composes with CDN caching out of the box.
+ *
+ * See design/25-production-deployments.md §Layer 2.
+ */
+
+export interface CdnPurgeHandler {
+  /**
+   * Purge the given cache tags from the CDN.
+   * Called by cache.invalidate when a tag is invalidated.
+   */
+  purgeTags(tags: string[]): Promise<void>;
+}
+
+let handler: CdnPurgeHandler | undefined;
+
+/** Install a CDN purge handler. Called by the framework at boot from timber.config.ts. */
+export function setCdnPurgeHandler(h: CdnPurgeHandler): void {
+  handler = h;
+}
+
+/** Get the current CDN purge handler, if configured. */
+export function getCdnPurgeHandler(): CdnPurgeHandler | undefined {
+  return handler;
+}
+
+/** @internal — reset for tests only. */
+export function _resetCdnPurgeHandler(): void {
+  handler = undefined;
+}

package/src/cdn/workers-cache-purge.ts

@@ -0,0 +1,30 @@
+/**
+ * Cloudflare Workers Cache purge handler — purges by cache tag via
+ * ctx.cache.purge() on the ExecutionContext.
+ *
+ * Available on ALL Cloudflare plans (no Enterprise requirement).
+ * No API token needed — uses the Workers runtime's built-in cache API.
+ *
+ * Auto-wired by the Cloudflare adapter when no user-configured CDN
+ * purge handler is set. Uses the Workers Cache ALS bridge to access
+ * ctx.cache from within the request context.
+ */
+
+import type { CdnPurgeHandler } from './purge-store';
+import { getWorkersCachePurgeCtx } from '../server/workers-cache-bridge.js';
+
+export class WorkersCachePurge implements CdnPurgeHandler {
+  async purgeTags(tags: string[]): Promise<void> {
+    if (tags.length === 0) return;
+
+    const ctx = getWorkersCachePurgeCtx();
+    if (!ctx) {
+      throw new Error(
+        'WorkersCachePurge: no Workers Cache context available. ' +
+          'This handler can only be used within a Cloudflare Workers request context.'
+      );
+    }
+
+    await ctx.purge({ tags });
+  }
+}