fix: prefer uncached Hyperdrive after content writes

.changeset/prefer-uncached-hyperdrive-after-write.md

@@ -0,0 +1,6 @@
+---
+"emdash": patch
+"@emdash-cms/cloudflare": patch
+---
+
+Fixes anonymous public pages reseeding edge/object caches with stale Hyperdrive query results right after content publishes. When `cachedBinding` is set, public reads prefer the uncached Hyperdrive binding for a short window after content writes (default 60s, overridable via `preferUncachedAfterWriteMs` to match your Hyperdrive max_age).

docs/src/content/docs/deployment/database.mdx

@@ -307,11 +307,14 @@ wrangler hyperdrive create emdash-db \
 
 ### Configuration
 
-| Option          | Type     | Default       | Description                                                          |
-| --------------- | -------- | ------------- | -------------------------------------------------------------------- |
-| `binding`       | `string` | `"HYPERDRIVE"` | Primary (caching-disabled) Hyperdrive binding name                  |
-| `cachedBinding` | `string` | —             | Optional caching-enabled binding for anonymous reads (see below)     |
-| `max`           | `number` | `5`           | Max size of the in-Worker connection pool to Hyperdrive              |
+| Option                         | Type     | Default        | Description                                                                                                      |
+| ------------------------------ | -------- | -------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `binding`                      | `string` | `"HYPERDRIVE"` | Primary (caching-disabled) Hyperdrive binding name                                                               |
+| `cachedBinding`                | `string` | —              | Optional caching-enabled binding for anonymous reads (see below)                                                 |
+| `preferUncachedAfterWriteMs`   | `number` | `60000`\*      | After a content publish, prefer `binding` for this many ms on anonymous public reads (match Hyperdrive `max_age`) |
+| `max`                          | `number` | `5`            | Max size of the in-Worker connection pool to Hyperdrive                                                          |
+
+\*Default `60000` applies only when `cachedBinding` is set; ignored otherwise.
 
 ### Serving anonymous reads from cache
 
@@ -343,7 +346,7 @@ database: hyperdrive({ binding: "HYPERDRIVE", cachedBinding: "HYPERDRIVE_CACHED"
 
 This is the [two-configuration pattern](https://developers.cloudflare.com/hyperdrive/configuration/query-caching/#disable-caching) Cloudflare documents for caching. EmDash decides which binding to use per request:
 
-- **Anonymous reads of public-site paths** (`GET`/`HEAD`, no session, not under `/_emdash`) → cache-enabled `cachedBinding`.
+- **Anonymous reads of public-site paths** (`GET`/`HEAD`, no session, not under `/_emdash`) → cache-enabled `cachedBinding`, **except** for a short window after a content publish (default 60s; set `preferUncachedAfterWriteMs` to your Hyperdrive `max_age`) when EmDash prefers the uncached `binding` so a rebuild cannot reseed edge/object caches from still-stale Hyperdrive results.
 - **Authenticated requests** (editors, authors) → uncached `binding`.
 - **Writes** (`POST`, `PUT`, `DELETE`, including anonymous ones) → uncached `binding`.
 - **Any request under `/_emdash`** (admin, setup, auth, internal APIs), even an anonymous `GET` → uncached `binding`.
@@ -357,7 +360,7 @@ This is the [two-configuration pattern](https://developers.cloudflare.com/hyperd
 </Aside>
 
 <Aside type="caution">
-	Both configurations must point at the **same** database, or anonymous visitors see a different dataset than editors. Anonymous reads of just-published content can be up to the cache's `max_age` stale (Hyperdrive default 60s, max 1h), and this cache is independent of EmDash's own cache invalidation. Only opt in if a short public-read staleness window is acceptable; otherwise omit `cachedBinding` and keep caching disabled.
+	Both configurations must point at the **same** database, or anonymous visitors see a different dataset than editors. Set `preferUncachedAfterWriteMs` to your cached config's `max_age` (default 60s) so post-publish public rebuilds read fresh SQL. Outside that window, anonymous public reads can still be up to `max_age` stale relative to non-content writes. Only opt in if that trade-off is acceptable; otherwise omit `cachedBinding` and keep caching disabled.
 </Aside>
 
 <Aside>

packages/cloudflare/src/db/hyperdrive.ts

@@ -81,8 +81,18 @@ interface HyperdriveConfig {
 	 * authenticated requests and all writes stay on `binding`.
 	 */
 	cachedBinding?: string;
+	/**
+	 * After a content publish, prefer the primary uncached binding for this
+	 * many ms on anonymous public reads. Defaults to 60_000 when
+	 * `cachedBinding` is set (Hyperdrive's default `max_age`); 0 otherwise.
+	 * Set equal to your cached Hyperdrive config's `max_age`.
+	 */
+	preferUncachedAfterWriteMs?: number;
 }
 
+/** Hyperdrive default query-cache max_age when caching is enabled. */
+const DEFAULT_PREFER_UNCACHED_AFTER_WRITE_MS = 60_000;
+
 /**
  * Minimal shape of a Hyperdrive binding. Workers inject `connectionString`
  * (and the discrete parts) at runtime; we only need the string for pg.
@@ -147,6 +157,8 @@ export interface RequestScopedDbOpts {
 	isWrite: boolean;
 	cookies: CookieJar;
 	url: URL;
+	/** ms-epoch of last content-namespace invalidation; from core object-cache. */
+	lastContentWriteAt?: number;
 }
 
 export interface RequestScopedDb {
@@ -182,6 +194,7 @@ export function createRequestScopedDb(opts: RequestScopedDbOpts): RequestScopedD
 		isAuthenticated: opts.isAuthenticated,
 		isWrite: opts.isWrite,
 		url: opts.url,
+		lastContentWriteAt: opts.lastContentWriteAt,
 	});
 	let binding = getBinding(bindingName);
 	// If the cached binding was selected but isn't present at runtime (e.g.
@@ -241,6 +254,17 @@ function isEmDashInternalPath(url: URL): boolean {
 	return url.pathname === EMDASH_BASE_PATH || url.pathname.startsWith(`${EMDASH_BASE_PATH}/`);
 }
 
+/**
+ * Effective window (ms) to prefer the primary binding after a content write.
+ * Defaults to Hyperdrive's 60s `max_age` when `cachedBinding` is set.
+ */
+function preferUncachedDurationMs(config: HyperdriveConfig): number {
+	if (config.preferUncachedAfterWriteMs !== undefined) {
+		return config.preferUncachedAfterWriteMs;
+	}
+	return config.cachedBinding ? DEFAULT_PREFER_UNCACHED_AFTER_WRITE_MS : 0;
+}
+
 /**
  * Decide which binding a given request should use.
  *
@@ -255,19 +279,32 @@ function isEmDashInternalPath(url: URL): boolean {
  *   even an anonymous GET → primary. The setup-status and login-state reads
  *   are anonymous GETs that must see writes made moments earlier; routing them
  *   to the cache would loop the setup wizard and show stale auth state.
+ * - anonymous public reads within `preferUncachedAfterWriteMs` of the last
+ *   content-namespace invalidation → primary, so a post-publish rebuild does
+ *   not reseed edge/object caches from Hyperdrive's still-stale query cache.
  *
  * Pure (no I/O) so the routing rule can be unit-tested directly.
  */
 export function selectBindingName(
 	config: HyperdriveConfig,
-	opts: { isAuthenticated: boolean; isWrite: boolean; url: URL },
+	opts: {
+		isAuthenticated: boolean;
+		isWrite: boolean;
+		url: URL;
+		lastContentWriteAt?: number;
+	},
 ): string {
 	if (
 		config.cachedBinding &&
 		!opts.isAuthenticated &&
 		!opts.isWrite &&
 		!isEmDashInternalPath(opts.url)
 	) {
+		const duration = preferUncachedDurationMs(config);
+		const lastWrite = opts.lastContentWriteAt ?? 0;
+		if (duration > 0 && lastWrite > 0 && Date.now() - lastWrite < duration) {
+			return config.binding;
+		}
 		return config.cachedBinding;
 	}
 	return config.binding;

packages/cloudflare/src/index.ts

@@ -139,11 +139,11 @@ export interface HyperdriveConfig {
 	 * check, which must observe a write made moments earlier. Migrations and the
 	 * cold-start singleton always use `binding`.
 	 *
-	 * Anonymous reads of just-published content can be up to the cache's
-	 * `max_age` stale (Hyperdrive default 60s, max 1h), and this cache is
-	 * independent of EmDash's own cache invalidation — only opt in if a short
-	 * public-read staleness window is acceptable. Omit it and the adapter uses
-	 * the single primary binding as before.
+	 * After a content publish, EmDash prefers the primary uncached binding for
+	 * anonymous public reads for a short window (see
+	 * {@link preferUncachedAfterWriteMs}) so edge/object caches are not reseeded
+	 * from Hyperdrive's still-stale query results. Outside that window,
+	 * anonymous public reads use this cache-enabled binding.
 	 *
 	 * Bind both configs in wrangler:
 	 * ```jsonc
@@ -157,6 +157,17 @@ export interface HyperdriveConfig {
 	 */
 	cachedBinding?: string;
 
+	/**
+	 * How long (ms) after a content write anonymous public reads should use the
+	 * primary uncached `binding` instead of `cachedBinding`. Set this equal to
+	 * your cached Hyperdrive configuration's `max_age` so the prefer-uncached
+	 * window covers the query-cache TTL.
+	 *
+	 * Only applies when `cachedBinding` is set. Default: `60_000` (Hyperdrive's
+	 * default `max_age`) when `cachedBinding` is set; ignored otherwise.
+	 */
+	preferUncachedAfterWriteMs?: number;
+
 	/**
 	 * Maximum size of the in-Worker node-postgres connection pool.
 	 *
@@ -299,12 +310,18 @@ export function d1(config: D1Config): DatabaseDescriptor {
  *
  * **Optional: serve anonymous reads from cache.** If a short public-read
  * staleness window is acceptable, pass a second `cachedBinding` pointing at a
- * caching-enabled Hyperdrive config over the same database. Anonymous read
- * requests then route through the cache-enabled binding while authenticated
- * requests and writes stay on the uncached `binding`, keeping read-after-write
- * consistency intact:
+ * caching-enabled Hyperdrive config over the same database. Anonymous public
+ * reads then route through the cache-enabled binding while authenticated
+ * requests and writes stay on the uncached `binding`. For a short window after
+ * each content publish (default 60s; set `preferUncachedAfterWriteMs` to match
+ * your Hyperdrive `max_age`), anonymous public reads also use the primary so a
+ * rebuild cannot reseed edge caches from stale Hyperdrive results:
  * ```ts
- * database: hyperdrive({ binding: "HYPERDRIVE", cachedBinding: "HYPERDRIVE_CACHED" })
+ * database: hyperdrive({
+ *   binding: "HYPERDRIVE",
+ *   cachedBinding: "HYPERDRIVE_CACHED",
+ *   // preferUncachedAfterWriteMs: 60_000, // default when cachedBinding is set
+ * })
  * ```
  *
  * For best latency, pair this with a Smart Placement hint so the Worker runs in
@@ -338,6 +355,9 @@ export function hyperdrive(config: HyperdriveConfig = {}): DatabaseDescriptor {
 			binding: config.binding ?? "HYPERDRIVE",
 			max: config.max,
 			...(config.cachedBinding !== undefined ? { cachedBinding: config.cachedBinding } : {}),
+			...(config.preferUncachedAfterWriteMs !== undefined
+				? { preferUncachedAfterWriteMs: config.preferUncachedAfterWriteMs }
+				: {}),
 		},
 		type: "postgres",
 		// Each request gets a fresh pg connection that is closed afterwards —

packages/cloudflare/tests/db/hyperdrive-routing.test.ts

@@ -110,6 +110,82 @@ describe("selectBindingName", () => {
 			),
 		).toBe("HYPERDRIVE");
 	});
+
+	it("uses the primary binding for anonymous public reads soon after a content write", () => {
+		const name = selectBindingName(cfg, {
+			isAuthenticated: false,
+			isWrite: false,
+			url: publicUrl,
+			lastContentWriteAt: Date.now() - 1_000,
+		});
+		expect(name).toBe("HYPERDRIVE");
+	});
+
+	it("uses the cached binding once the prefer-uncached window has elapsed", () => {
+		const name = selectBindingName(cfg, {
+			isAuthenticated: false,
+			isWrite: false,
+			url: publicUrl,
+			lastContentWriteAt: Date.now() - 61_000,
+		});
+		expect(name).toBe("HYPERDRIVE_CACHED");
+	});
+
+	it("uses the cached binding when lastContentWriteAt is zero or missing", () => {
+		expect(
+			selectBindingName(cfg, {
+				isAuthenticated: false,
+				isWrite: false,
+				url: publicUrl,
+				lastContentWriteAt: 0,
+			}),
+		).toBe("HYPERDRIVE_CACHED");
+		expect(
+			selectBindingName(cfg, {
+				isAuthenticated: false,
+				isWrite: false,
+				url: publicUrl,
+			}),
+		).toBe("HYPERDRIVE_CACHED");
+	});
+
+	it("respects a custom preferUncachedAfterWriteMs", () => {
+		const custom = {
+			binding: "HYPERDRIVE",
+			cachedBinding: "HYPERDRIVE_CACHED",
+			preferUncachedAfterWriteMs: 5_000,
+		};
+		expect(
+			selectBindingName(custom, {
+				isAuthenticated: false,
+				isWrite: false,
+				url: publicUrl,
+				lastContentWriteAt: Date.now() - 2_000,
+			}),
+		).toBe("HYPERDRIVE");
+		expect(
+			selectBindingName(custom, {
+				isAuthenticated: false,
+				isWrite: false,
+				url: publicUrl,
+				lastContentWriteAt: Date.now() - 6_000,
+			}),
+		).toBe("HYPERDRIVE_CACHED");
+	});
+
+	it("ignores lastContentWriteAt when no cachedBinding is set", () => {
+		expect(
+			selectBindingName(
+				{ binding: "HYPERDRIVE" },
+				{
+					isAuthenticated: false,
+					isWrite: false,
+					url: publicUrl,
+					lastContentWriteAt: Date.now(),
+				},
+			),
+		).toBe("HYPERDRIVE");
+	});
 });
 
 describe("createRequestScopedDb binding routing", () => {
@@ -127,6 +203,19 @@ describe("createRequestScopedDb binding routing", () => {
 		expect(poolCalls[0]!.connectionString).toBe("postgres://replica/cached");
 	});
 
+	it("builds the pool from the primary binding when lastContentWriteAt is recent", () => {
+		poolCalls.length = 0;
+		createRequestScopedDb({
+			config: { binding: "HYPERDRIVE", cachedBinding: "HYPERDRIVE_CACHED" },
+			isAuthenticated: false,
+			isWrite: false,
+			cookies,
+			url,
+			lastContentWriteAt: Date.now() - 500,
+		});
+		expect(poolCalls[0]!.connectionString).toBe("postgres://primary/uncached");
+	});
+
 	it("builds the pool from the primary binding for authenticated reads", () => {
 		poolCalls.length = 0;
 		createRequestScopedDb({

packages/cloudflare/tests/hyperdrive-config.test.ts

@@ -42,4 +42,18 @@ describe("hyperdrive()", () => {
 			cachedBinding: "HYPERDRIVE_CACHED",
 		});
 	});
+
+	it("passes through preferUncachedAfterWriteMs", () => {
+		const result = hyperdrive({
+			binding: "HYPERDRIVE",
+			cachedBinding: "HYPERDRIVE_CACHED",
+			preferUncachedAfterWriteMs: 120_000,
+		});
+		expect(result.config).toEqual({
+			binding: "HYPERDRIVE",
+			max: undefined,
+			cachedBinding: "HYPERDRIVE_CACHED",
+			preferUncachedAfterWriteMs: 120_000,
+		});
+	});
 });

packages/core/src/astro/middleware.ts

@@ -47,6 +47,7 @@ import {
 import { setI18nConfig } from "../i18n/config.js";
 import type { Database, Storage } from "../index.js";
 import { createPublicMediaUrlResolver } from "../media/url.js";
+import { getLastContentWriteAt } from "../object-cache/index.js";
 import type { SandboxRunnerFactory } from "../plugins/sandbox/types.js";
 import type { ResolvedPlugin } from "../plugins/types.js";
 import { invalidateUrlPatternCache } from "../query.js";
@@ -346,6 +347,7 @@ async function runOutsideRequest<T>(
 ): Promise<T> {
 	const runtime = await getRuntime(config);
 
+	const lastContentWriteAt = await getLastContentWriteAt();
 	const scoped = createRequestScopedDb({
 		config: config.database?.config,
 		isAuthenticated: false,
@@ -354,6 +356,7 @@ async function runOutsideRequest<T>(
 		isWrite: true,
 		cookies: NOOP_COOKIE_JAR,
 		url: CRON_EVENT_URL,
+		lastContentWriteAt,
 	});
 	if (!scoped?.close) {
 		// Stateless adapter (or no per-request scoping): the singleton is safe
@@ -647,12 +650,14 @@ export const onRequest = defineMiddleware(async (context, next) => {
 				// Even on the anonymous fast path we ask the adapter for a per-request
 				// scoped db. For D1 with read replication this routes anonymous reads
 				// to the nearest replica; for other adapters it's a no-op.
+				const lastContentWriteAt = await getLastContentWriteAt();
 				const anonScoped = createRequestScopedDb({
 					config: config?.database?.config,
 					isAuthenticated: false,
 					isWrite: request.method !== "GET" && request.method !== "HEAD",
 					cookies,
 					url,
+					lastContentWriteAt,
 				});
 				const runAnon = async () => {
 					const t0 = performance.now();
@@ -855,12 +860,14 @@ export const onRequest = defineMiddleware(async (context, next) => {
 			// it in ALS so the runtime's db getter and loader's getDb() pick it up,
 			// then call commit() after next() so the adapter can persist any
 			// per-request state (e.g. a D1 bookmark cookie for read-your-writes).
+			const lastContentWriteAt = await getLastContentWriteAt();
 			const scoped = createRequestScopedDb({
 				config: config?.database?.config,
 				isAuthenticated: !!sessionUser || hasBearerAuth,
 				isWrite: request.method !== "GET" && request.method !== "HEAD",
 				cookies: context.cookies,
 				url,
+				lastContentWriteAt,
 			});
 
 			const renderAndFinalize = async () => {

packages/core/src/index.ts

@@ -199,6 +199,7 @@ export { EmDashStorageError } from "./storage/types.js";
 // Object cache (distributed read-through query cache)
 export {
 	cachedQuery,
+	getLastContentWriteAt,
 	invalidateObjectCache,
 	invalidateCollectionCache,
 	invalidateTaxonomyObjectCache,