@certrev/cert-block 1.2.0-canary.6 → 1.2.0

package/src/verify/cache.ts

@@ -11,6 +11,13 @@
  *      ONE fetch, not N.
  *   3. Negative-caches failures briefly so a hard-down origin doesn't get hammered, while
  *      still recovering quickly (short negative TTL).
+ *   4. (1.2.0, opt-in through `staleMs`) STALE-WHILE-REVALIDATE and STALE-IF-ERROR: a positive
+ *      entry past its TTL but inside the stale window is served at once while ONE background
+ *      refresh replaces it; a refresh that only failed to reach the origin (`isTransient`)
+ *      keeps the stale entry instead of overwriting it. So an origin that is slow or briefly
+ *      down costs the page nothing it already had. A definitive answer (a revocation, say)
+ *      replaces the entry the moment the refresh lands. With the default `staleMs` of 0 an
+ *      expired entry is gone, exactly as before 1.2.0.
  *
  * It is deliberately tiny + dependency-free (a Map + timestamps) so it runs in any server
  * runtime (Node, edge, workerd). For multi-instance deployments this is per-instance L1 and
@@ -25,6 +32,18 @@ export interface TtlCacheOptions {
 	readonly negativeTtlMs?: number
 	/** Max entries before LRU-ish eviction of the oldest insert (default 1000). */
 	readonly maxEntries?: number
+	/**
+	 * 1.2.0: how long past its TTL a POSITIVE entry may still be served while a refresh runs (default 0: never). A
+	 * negative entry is never served stale.
+	 */
+	readonly staleMs?: number
+	/**
+	 * 1.2.0: how long an unsettled load may be joined by later callers (default: no limit). Past it, the next caller
+	 * starts a fresh load. WHY: a runtime may cancel the I/O of a request that has finished (Cloudflare workerd does),
+	 * which can leave a background refresh's promise pending forever; without a limit every later caller would join
+	 * it and none would ever refresh again.
+	 */
+	readonly inflightMaxMs?: number
 	/** Injectable clock for deterministic tests. */
 	readonly now?: () => number
 }
@@ -35,28 +54,64 @@ interface Entry<V> {
 	readonly negative: boolean
 }
 
+interface Inflight<V> {
+	readonly promise: Promise<V>
+	readonly startedAt: number
+}
+
 export class TtlCache<V> {
 	private readonly store = new Map<string, Entry<V>>()
-	private readonly inflight = new Map<string, Promise<V>>()
+	private readonly inflight = new Map<string, Inflight<V>>()
 	private readonly ttlMs: number
 	private readonly negativeTtlMs: number
 	private readonly maxEntries: number
+	private readonly staleMs: number
+	private readonly inflightMaxMs: number
 	private readonly now: () => number
 
 	constructor(opts: TtlCacheOptions = {}) {
 		this.ttlMs = opts.ttlMs ?? 60_000
 		this.negativeTtlMs = opts.negativeTtlMs ?? 5_000
 		this.maxEntries = opts.maxEntries ?? 1000
+		this.staleMs = opts.staleMs !== undefined && opts.staleMs > 0 ? opts.staleMs : 0
+		this.inflightMaxMs = opts.inflightMaxMs ?? Number.POSITIVE_INFINITY
 		this.now = opts.now ?? Date.now
 	}
 
-	/** Read a live (non-expired) entry, or undefined. Prunes the entry if expired. */
-	peek(key: string): V | undefined {
+	/** The entry while it may still be served (fresh, or positive and inside the stale window); prunes it past that. */
+	private servable(key: string): Entry<V> | undefined {
 		const e = this.store.get(key)
 		if (!e) return undefined
+		const now = this.now()
+		if (e.expiresAt > now) return e
+		if (!e.negative && now < e.expiresAt + this.staleMs) return e
+		this.store.delete(key)
+		return undefined
+	}
+
+	/** Read a live (non-expired) entry, or undefined. Never serves a stale one; prunes an entry past its stale window. */
+	peek(key: string): V | undefined {
+		const e = this.servable(key)
+		return e && e.expiresAt > this.now() ? e.value : undefined
+	}
+
+	/**
+	 * The synchronous stale-while-revalidate read: a fresh value; or a positive entry past its TTL but inside the stale
+	 * window, returned at once while this starts (or joins) ONE background refresh through `loader`; else undefined,
+	 * and the caller loads (`getOrLoad`). The refresh caches as `getOrLoad` does, with the same arguments; its failure
+	 * is swallowed (the stale value was already served, and a thrown loader is never cached).
+	 */
+	peekOrRefresh(
+		key: string,
+		loader: () => Promise<V>,
+		isNegative?: (v: V) => boolean,
+		positiveTtlMs?: number,
+		isTransient?: (v: V) => boolean,
+	): V | undefined {
+		const e = this.servable(key)
+		if (!e) return undefined
 		if (e.expiresAt <= this.now()) {
-			this.store.delete(key)
-			return undefined
+			this.load(key, loader, isNegative, positiveTtlMs, isTransient).catch(() => undefined)
 		}
 		return e.value
 	}
@@ -74,29 +129,50 @@ export class TtlCache<V> {
 	 * It deliberately does NOT apply to a negative result: a caller asking for a 10-minute
 	 * positive TTL is asking for fewer origin reads, not for a transient failure to be
 	 * remembered for ten minutes (see the negative-TTL rationale in the module header).
+	 *
+	 * 1.2.0: inside the stale window (`staleMs`) an expired positive entry is returned at once and refreshed in the
+	 * background (`peekOrRefresh`). `isTransient(value)` marks a result that says only "the origin was not reached"
+	 * (a timeout, a 5xx): when a servable positive entry exists, such a result is NOT cached over it and the caller
+	 * gets that entry's value instead (stale-if-error). With no entry to keep, it is cached as `isNegative` says.
 	 */
 	async getOrLoad(
 		key: string,
 		loader: () => Promise<V>,
 		isNegative?: (v: V) => boolean,
 		positiveTtlMs?: number,
+		isTransient?: (v: V) => boolean,
 	): Promise<V> {
-		const cached = this.peek(key)
-		if (cached !== undefined) return cached
+		const served = this.peekOrRefresh(key, loader, isNegative, positiveTtlMs, isTransient)
+		if (served !== undefined) return served
+		return this.load(key, loader, isNegative, positiveTtlMs, isTransient)
+	}
 
+	/** Single-flight load and cache (joins an unsettled load younger than `inflightMaxMs`). */
+	private load(
+		key: string,
+		loader: () => Promise<V>,
+		isNegative: ((v: V) => boolean) | undefined,
+		positiveTtlMs: number | undefined,
+		isTransient: ((v: V) => boolean) | undefined,
+	): Promise<V> {
 		const existing = this.inflight.get(key)
-		if (existing) return existing
+		if (existing && this.now() - existing.startedAt < this.inflightMaxMs) return existing.promise
 
-		const promise = (async () => {
+		const promise: Promise<V> = (async () => {
 			const value = await loader()
+			if (isTransient?.(value)) {
+				const kept = this.servable(key)
+				if (kept && !kept.negative) return kept.value
+			}
 			const negative = isNegative ? isNegative(value) : false
 			this.set(key, value, negative, negative ? undefined : positiveTtlMs)
 			return value
 		})().finally(() => {
-			this.inflight.delete(key)
+			// Only this load's own slot: a newer load that replaced an abandoned one keeps its place.
+			if (this.inflight.get(key)?.promise === promise) this.inflight.delete(key)
 		})
 
-		this.inflight.set(key, promise)
+		this.inflight.set(key, { promise, startedAt: this.now() })
 		return promise
 	}
 

package/src/verify/get-verified-delivery.ts

@@ -29,12 +29,20 @@
  * `peekVerifiedDelivery` is the synchronous read of the same cache: a React component suspends on
  * `getVerifiedDelivery` once, then reads the settled value without a second promise (which is what
  * keeps a streaming SSR render from suspending forever on a fresh promise every retry).
+ *
+ * 1.2.0: a suppressed read that only failed to REACH CertREV (the fetch threw or hit its deadline, a 5xx or other
+ * non-OK status but 404/410, a body that is not JSON or not an object) is marked `unreachable`. It says nothing
+ * about the credential, so a cache with a stale window keeps a verified entry over it (stale-if-error), and the
+ * card paints its options face instead of nothing. A definitive answer (404/410, a key or signature that does not
+ * verify, a revoked, expired or mismatched artifact) is never `unreachable`. `readVerifiedDelivery` is the
+ * synchronous read that also serves a stale entry while refreshing it.
  */
 
 import type { CertChromeRenderDef } from '../builder/cert-chrome-data.js'
 import type {
 	CertDeliveryArtifact,
 	CertPayload,
+	CertSignature,
 	CertSuppressReason,
 	CertVerdict,
 	RenderContext,
@@ -44,16 +52,34 @@ import { renderVerdict, verifyArtifact } from '../contract/kernel.js'
 import { TtlCache } from './cache.js'
 import { DEFAULT_FETCH_TIMEOUT_MS, fetchWithDeadline } from './fetch-with-deadline.js'
 
-/** What one Delivery read settles to, as cached: a verified payload + its def, or the reason not. */
+/**
+ * What one Delivery read settles to, as cached: a verified payload + its def (and, from 1.2.0, the signature it
+ * verified with, so a server render can hand the signed envelope to the browser), or the reason not.
+ */
 export type CachedDelivery =
-	| { readonly kind: 'verified'; readonly payload: CertPayload; readonly renderDef: CertChromeRenderDef | null }
-	| { readonly kind: 'suppressed'; readonly reason: CertSuppressReason }
+	| {
+			readonly kind: 'verified'
+			readonly payload: CertPayload
+			readonly renderDef: CertChromeRenderDef | null
+			/** Absent only in a cache filled by hand (a test, a custom cache); a read always keeps it. */
+			readonly signature?: CertSignature
+	  }
+	| {
+			readonly kind: 'suppressed'
+			readonly reason: CertSuppressReason
+			/** 1.2.0: true when CertREV was not reached (no answer about the credential); see the module header. */
+			readonly unreachable?: true
+	  }
 
 /** The answer for one render: the verdict AT THIS RENDER'S CLOCK, and the def to paint it with. */
 export interface VerifiedDelivery {
 	readonly verdict: CertVerdict
 	/** The brand's render def, or null (no def resolved, a malformed one, or a suppress verdict). */
 	readonly renderDef: CertChromeRenderDef | null
+	/** The verified envelope's signature, on a `render` verdict whose read kept it; else undefined. */
+	readonly signature?: CertSignature
+	/** 1.2.0: on a suppress verdict, true when CertREV was not reached; else undefined. */
+	readonly unreachable?: true
 }
 
 export interface GetVerifiedDeliveryOptions {
@@ -70,7 +96,7 @@ export interface GetVerifiedDeliveryOptions {
 	readonly cache?: TtlCache<CachedDelivery>
 	/** TTL in ms for a VERIFIED read (default: the cache's positive TTL, 60_000 on the shared one). */
 	readonly ttlMs?: number
-	/** Deadline in ms for the fetch (default `DEFAULT_FETCH_TIMEOUT_MS`, 3s). */
+	/** Deadline in ms for the fetch (default `DEFAULT_FETCH_TIMEOUT_MS`, 3s; the Builder card's runtime passes 8s). */
 	readonly timeoutMs?: number
 	/**
 	 * 1.2.0-canary.5: read one saved design version instead of the brand's live def. CertREV's own canary
@@ -96,6 +122,13 @@ function suppressed(reason: CertSuppressReason): CachedDelivery {
 	return { kind: 'suppressed', reason }
 }
 
+/** A read that did not reach CertREV: the same least-wrong reason as before 1.2.0, marked `unreachable`. */
+function unreachable(): CachedDelivery {
+	return { kind: 'suppressed', reason: 'unsupported_contract_version', unreachable: true }
+}
+
+const isUnreachable = (v: CachedDelivery): boolean => v.kind === 'suppressed' && v.unreachable === true
+
 /** The Delivery route; a design pin adds `?design=<v>` and, with a brand, `&designBrand=<brand>`. */
 export function deliveryUrl(baseUrl: string, platform: string, externalId: string, design?: DesignPin): string {
 	const base = baseUrl.replace(/\/+$/, '')
@@ -210,19 +243,19 @@ async function loadDelivery(opts: GetVerifiedDeliveryOptions): Promise<CachedDel
 		)
 	} catch {
 		// Unreachable, DNS/TLS, or the deadline. Same least-wrong member as getVerifiedEnvelope.
-		return suppressed('unsupported_contract_version')
+		return unreachable()
 	}
 	// Nothing served for this placement: never certified, or withdrawn. A LIVE revocation is a 200
 	// tombstone, so a 4xx here genuinely means "no credential for this subject".
 	if (res.status === 404 || res.status === 410) return suppressed('subject_mismatch')
-	if (!res.ok) return suppressed('unsupported_contract_version')
+	if (!res.ok) return unreachable()
 	let body: unknown
 	try {
 		body = await res.json()
 	} catch {
-		return suppressed('unsupported_contract_version')
+		return unreachable()
 	}
-	if (!isRecord(body)) return suppressed('unsupported_contract_version')
+	if (!isRecord(body)) return unreachable()
 	let verdict: CertVerdict
 	try {
 		// `verifyArtifact`, so a tombstone verifies as itself and reports 'revoked'. The kernel reads
@@ -233,14 +266,28 @@ async function loadDelivery(opts: GetVerifiedDeliveryOptions): Promise<CachedDel
 		return suppressed('unknown_key')
 	}
 	if (verdict.decision !== 'render') return suppressed(verdict.reason)
-	return { kind: 'verified', payload: verdict.payload, renderDef: parseRenderDef(body.renderDef) }
+	// A `render` verdict came from an envelope (a tombstone never renders), so `signature` is the one just verified.
+	const signature = isRecord(body.signature) ? (body.signature as unknown as CertSignature) : undefined
+	return {
+		kind: 'verified',
+		payload: verdict.payload,
+		renderDef: parseRenderDef(body.renderDef),
+		...(signature ? { signature } : {}),
+	}
 }
 
 /** Apply the render-time policy to a cached read: lifecycle + subject at THIS render's clock. */
 export function settleDelivery(cached: CachedDelivery, context: RenderContext): VerifiedDelivery {
-	if (cached.kind === 'suppressed') return { verdict: { decision: 'suppress', reason: cached.reason }, renderDef: null }
+	if (cached.kind === 'suppressed') {
+		return {
+			verdict: { decision: 'suppress', reason: cached.reason },
+			renderDef: null,
+			...(cached.unreachable ? { unreachable: true as const } : {}),
+		}
+	}
 	const verdict = renderVerdict(cached.payload, context)
-	return { verdict, renderDef: verdict.decision === 'render' ? cached.renderDef : null }
+	if (verdict.decision !== 'render') return { verdict, renderDef: null }
+	return { verdict, renderDef: cached.renderDef, ...(cached.signature ? { signature: cached.signature } : {}) }
 }
 
 /**
@@ -255,10 +302,29 @@ export async function getVerifiedDelivery(opts: GetVerifiedDeliveryOptions): Pro
 		() => loadDelivery(opts),
 		(v) => v.kind === 'suppressed',
 		opts.ttlMs,
+		isUnreachable,
 	)
 	return settleDelivery(cached, opts.context)
 }
 
+/**
+ * 1.2.0, the synchronous read a render uses: the settled answer for a fresh cached read; or, inside the cache's
+ * stale window, the stale read's answer at once while ONE background refresh (the same fetch `getVerifiedDelivery`
+ * makes) replaces it; else `undefined`, and the caller awaits `getVerifiedDelivery`. The verdict is still settled
+ * at `context.now`, so a stale payload that has expired or been revoked in its own fields still suppresses.
+ */
+export function readVerifiedDelivery(opts: GetVerifiedDeliveryOptions): VerifiedDelivery | undefined {
+	const cache = opts.cache ?? sharedDeliveryCache
+	const cached = cache.peekOrRefresh(
+		deliveryCacheKey(opts),
+		() => loadDelivery(opts),
+		(v) => v.kind === 'suppressed',
+		opts.ttlMs,
+		isUnreachable,
+	)
+	return cached === undefined ? undefined : settleDelivery(cached, opts.context)
+}
+
 /**
  * The synchronous read: the settled answer when a fresh read is cached, else `undefined` (the
  * caller then awaits `getVerifiedDelivery`). Never fetches.