@emdash-cms/cloudflare 0.0.1

package/src/cache/config.ts

@@ -0,0 +1,81 @@
+/**
+ * Cloudflare Cache API route cache provider - CONFIG ENTRY
+ *
+ * This is the config-time helper. Import it in your astro.config.mjs:
+ *
+ * ```ts
+ * import { cloudflareCache } from "@emdash-cms/cloudflare";
+ *
+ * export default defineConfig({
+ *   experimental: {
+ *     cache: {
+ *       provider: cloudflareCache(),
+ *     },
+ *   },
+ * });
+ * ```
+ *
+ * This module does NOT import cloudflare:workers and is safe to use at
+ * config time.
+ */
+
+import type { CacheProviderConfig } from "astro";
+
+import type { CloudflareCacheConfig } from "./runtime.js";
+
+export type { CloudflareCacheConfig };
+
+/**
+ * Cloudflare Cache API route cache provider.
+ *
+ * Uses the Workers Cache API (`cache.put()`/`cache.match()`) to cache
+ * rendered route responses at the edge. Invalidation uses the Cloudflare
+ * purge-by-tag REST API for global purge across all edge locations.
+ *
+ * This is a stopgap until CacheW provides native distributed caching
+ * for Workers. Worker responses can't go through the CDN cache today,
+ * so we use the Cache API directly. The standard `Cache-Tag` header is
+ * set on stored responses so the purge-by-tag API can find them.
+ *
+ * Tag-based invalidation requires a Zone ID and an API token with
+ * "Cache Purge" permission. These can be passed directly in the config
+ * or read from environment variables at runtime (default: `CF_ZONE_ID`
+ * and `CF_CACHE_PURGE_TOKEN`).
+ *
+ * @param config Optional configuration.
+ * @returns A {@link CacheProviderConfig} to pass to `experimental.cache.provider`.
+ *
+ * @example Basic usage (reads zone ID and token from env vars)
+ * ```ts
+ * import { defineConfig } from "astro/config";
+ * import cloudflare from "@astrojs/cloudflare";
+ * import { cloudflareCache } from "@emdash-cms/cloudflare";
+ *
+ * export default defineConfig({
+ *   adapter: cloudflare(),
+ *   experimental: {
+ *     cache: {
+ *       provider: cloudflareCache(),
+ *     },
+ *   },
+ * });
+ * ```
+ *
+ * @example With explicit config
+ * ```ts
+ * cloudflareCache({
+ *   cacheName: "my-site",
+ *   zoneId: "abc123...",
+ *   apiToken: "xyz789...",
+ * })
+ * ```
+ */
+export function cloudflareCache(
+	config: CloudflareCacheConfig = {},
+): CacheProviderConfig<CloudflareCacheConfig> {
+	return {
+		// Resolved by Vite/Astro at build time — points to the runtime module
+		entrypoint: "@emdash-cms/cloudflare/cache",
+		config,
+	};
+}

package/src/cache/runtime.ts

@@ -0,0 +1,328 @@
+/**
+ * Cloudflare Cache API route cache provider - RUNTIME ENTRY
+ *
+ * Implements Astro's CacheProvider interface as a runtime provider using the
+ * Workers Cache API for storage and the Cloudflare purge-by-tag REST API for
+ * global invalidation.
+ *
+ * This is a temporary solution until CacheW exists. Workers responses can't
+ * go through the CDN cache, so we use cache.put()/cache.match() directly.
+ * The standard `Cache-Tag` header (set by Astro's default setHeaders) is
+ * preserved on cached responses so the purge-by-tag API works globally.
+ *
+ * We do NOT implement setHeaders() — Astro's defaultSetHeaders correctly
+ * emits CDN-Cache-Control and Cache-Tag. Our onRequest() reads those
+ * headers from the response that next() returns.
+ *
+ * Do NOT import this at config time. Use cloudflareCache() from
+ * "@emdash-cms/cloudflare" or "@emdash-cms/cloudflare/cache/config" instead.
+ */
+
+import type { CacheProviderFactory } from "astro";
+import { env, waitUntil } from "cloudflare:workers";
+
+/**
+ * Internal headers stored on cached responses for freshness tracking.
+ * These are removed before returning to the client.
+ */
+const STORED_AT_HEADER = "X-EmDash-Stored-At";
+const MAX_AGE_HEADER = "X-EmDash-Max-Age";
+const SWR_HEADER = "X-EmDash-SWR";
+
+/** Cloudflare purge API base */
+const CF_API_BASE = "https://api.cloudflare.com/client/v4";
+
+/** Matches max-age in CDN-Cache-Control */
+const MAX_AGE_REGEX = /max-age=(\d+)/;
+
+/** Matches stale-while-revalidate in CDN-Cache-Control */
+const SWR_REGEX = /stale-while-revalidate=(\d+)/;
+
+/** Internal headers to strip before returning responses to the client */
+const INTERNAL_HEADERS = [STORED_AT_HEADER, MAX_AGE_HEADER, SWR_HEADER];
+
+/** Default D1 bookmark cookie name (from @emdash-cms/cloudflare d1 config) */
+const DEFAULT_BOOKMARK_COOKIE = "__ec_d1_bookmark";
+
+export interface CloudflareCacheConfig {
+	/**
+	 * Name of the Cache API cache to use.
+	 * @default "emdash"
+	 */
+	cacheName?: string;
+
+	/**
+	 * D1 bookmark cookie name. Responses whose only Set-Cookie is this
+	 * bookmark will have it stripped before caching. Responses with any
+	 * other Set-Cookie headers will not be cached.
+	 * @default "__ec_d1_bookmark"
+	 */
+	bookmarkCookie?: string;
+
+	/**
+	 * Cloudflare Zone ID. Required for tag-based invalidation.
+	 * If not provided, reads from `zoneIdEnvVar` at runtime.
+	 */
+	zoneId?: string;
+
+	/**
+	 * Environment variable name containing the Zone ID.
+	 * @default "CF_ZONE_ID"
+	 */
+	zoneIdEnvVar?: string;
+
+	/**
+	 * Cloudflare API token with Cache Purge permission.
+	 * If not provided, reads from `apiTokenEnvVar` at runtime.
+	 */
+	apiToken?: string;
+
+	/**
+	 * Environment variable name containing the API token.
+	 * @default "CF_CACHE_PURGE_TOKEN"
+	 */
+	apiTokenEnvVar?: string;
+}
+
+/**
+ * Parse CDN-Cache-Control header for max-age and stale-while-revalidate.
+ */
+function parseCdnCacheControl(header: string | null): { maxAge: number; swr: number } {
+	let maxAge = 0;
+	let swr = 0;
+	if (!header) return { maxAge, swr };
+	const maxAgeMatch = MAX_AGE_REGEX.exec(header);
+	if (maxAgeMatch) maxAge = parseInt(maxAgeMatch[1]!, 10) || 0;
+	const swrMatch = SWR_REGEX.exec(header);
+	if (swrMatch) swr = parseInt(swrMatch[1]!, 10) || 0;
+	return { maxAge, swr };
+}
+
+/**
+ * Normalize a URL for use as a cache key.
+ * Strips common tracking query parameters and sorts the rest.
+ */
+function normalizeCacheKey(url: URL): string {
+	const normalized = new URL(url.toString());
+
+	const trackingParams = [
+		"utm_source",
+		"utm_medium",
+		"utm_campaign",
+		"utm_term",
+		"utm_content",
+		"fbclid",
+		"gclid",
+		"gbraid",
+		"wbraid",
+		"dclid",
+		"msclkid",
+		"twclid",
+		"_ga",
+		"_gl",
+	];
+	for (const param of trackingParams) {
+		normalized.searchParams.delete(param);
+	}
+	normalized.searchParams.sort();
+
+	return normalized.toString();
+}
+
+/**
+ * Read a config value, falling back to an env var.
+ */
+function resolveEnvValue(explicit: string | undefined, envVarName: string): string | undefined {
+	if (explicit) return explicit;
+	return (env as Record<string, unknown>)[envVarName] as string | undefined;
+}
+
+/**
+ * Strip internal tracking headers from a response before returning to client.
+ */
+function stripInternalHeaders(response: Response): void {
+	for (const header of INTERNAL_HEADERS) {
+		response.headers.delete(header);
+	}
+}
+
+/**
+ * Check whether all Set-Cookie headers on a response are only the D1
+ * bookmark cookie. Returns true if we can safely strip them for caching.
+ * Returns false if there are non-bookmark cookies (session, auth, etc.)
+ * which means the response should NOT be cached.
+ */
+function hasOnlyBookmarkCookies(response: Response, bookmarkCookie: string): boolean {
+	const cookies = response.headers.getSetCookie();
+	if (cookies.length === 0) return true;
+	return cookies.every((c) => c.startsWith(`${bookmarkCookie}=`));
+}
+
+/**
+ * Prepare a response for storage in the Cache API.
+ * - Adds internal tracking headers (stored-at, max-age, swr)
+ * - Strips Set-Cookie (only called when cookies are safe to strip)
+ *
+ * Returns null if the response has non-bookmark Set-Cookie headers
+ * and should not be cached.
+ */
+function prepareForCache(
+	response: Response,
+	maxAge: number,
+	swr: number,
+	bookmarkCookie: string,
+): Response | null {
+	if (!hasOnlyBookmarkCookies(response, bookmarkCookie)) {
+		return null;
+	}
+	const prepared = new Response(response.body, response);
+	prepared.headers.set(STORED_AT_HEADER, String(Date.now()));
+	prepared.headers.set(MAX_AGE_HEADER, String(maxAge));
+	prepared.headers.set(SWR_HEADER, String(swr));
+	prepared.headers.delete("Set-Cookie");
+	return prepared;
+}
+
+const factory: CacheProviderFactory<CloudflareCacheConfig> = (config) => {
+	const cacheName = config?.cacheName ?? "emdash";
+	const bookmarkCookie = config?.bookmarkCookie ?? DEFAULT_BOOKMARK_COOKIE;
+	const zoneIdEnvVar = config?.zoneIdEnvVar ?? "CF_ZONE_ID";
+	const apiTokenEnvVar = config?.apiTokenEnvVar ?? "CF_CACHE_PURGE_TOKEN";
+
+	async function getCache(): Promise<Cache> {
+		return caches.open(cacheName);
+	}
+
+	return {
+		name: "cloudflare-cache-api",
+
+		// No setHeaders() — we use Astro's defaultSetHeaders which correctly
+		// emits CDN-Cache-Control and Cache-Tag. Our onRequest() reads those.
+
+		async onRequest(context, next) {
+			// Only cache GET requests
+			if (context.request.method !== "GET") {
+				return next();
+			}
+
+			// Skip cache for authenticated users. Their responses may differ
+			// (edit toolbar, admin UI, draft content) and must not be served
+			// to other visitors. The Astro session cookie indicates a logged-in user.
+			const cookieHeader = context.request.headers.get("Cookie") ?? "";
+			if (cookieHeader.includes("astro-session=")) {
+				return next();
+			}
+
+			const cacheKey = normalizeCacheKey(context.url);
+			const cache = await getCache();
+
+			const cached = await cache.match(cacheKey);
+
+			if (cached) {
+				const storedAt = parseInt(cached.headers.get(STORED_AT_HEADER) ?? "0", 10);
+				const maxAge = parseInt(cached.headers.get(MAX_AGE_HEADER) ?? "0", 10);
+				const swr = parseInt(cached.headers.get(SWR_HEADER) ?? "0", 10);
+				const ageSeconds = (Date.now() - storedAt) / 1000;
+
+				if (ageSeconds < maxAge) {
+					// Fresh — serve from cache
+					const hit = new Response(cached.body, cached);
+					hit.headers.set("X-Astro-Cache", "HIT");
+					stripInternalHeaders(hit);
+					return hit;
+				}
+
+				if (swr > 0 && ageSeconds < maxAge + swr) {
+					// Stale but within SWR window — serve stale, revalidate in background
+					const stale = new Response(cached.body, cached);
+					stale.headers.set("X-Astro-Cache", "STALE");
+					stripInternalHeaders(stale);
+
+					waitUntil(
+						(async () => {
+							try {
+								const fresh = await next();
+								const cdnCC = fresh.headers.get("CDN-Cache-Control");
+								const parsed = parseCdnCacheControl(cdnCC);
+								if (parsed.maxAge > 0 && fresh.ok) {
+									const toStore = prepareForCache(fresh, parsed.maxAge, parsed.swr, bookmarkCookie);
+									if (toStore) {
+										await cache.put(cacheKey, toStore);
+									}
+								}
+							} catch {
+								// Non-fatal — next request will retry
+							}
+						})(),
+					);
+
+					return stale;
+				}
+
+				// Expired and past SWR window — delete and fall through
+				await cache.delete(cacheKey);
+			}
+
+			// Cache MISS — render
+			const response = await next();
+
+			// Read cache directives from CDN-Cache-Control (set by Astro's defaultSetHeaders)
+			const cdnCC = response.headers.get("CDN-Cache-Control");
+			const { maxAge, swr } = parseCdnCacheControl(cdnCC);
+
+			if (maxAge > 0 && response.ok) {
+				const toStore = prepareForCache(response.clone(), maxAge, swr, bookmarkCookie);
+				if (toStore) {
+					await cache.put(cacheKey, toStore);
+				}
+
+				const miss = new Response(response.body, response);
+				miss.headers.set("X-Astro-Cache", "MISS");
+				return miss;
+			}
+
+			// No cache directives — pass through without caching
+			return response;
+		},
+
+		async invalidate(options) {
+			if (options.tags) {
+				const zoneId = resolveEnvValue(config?.zoneId, zoneIdEnvVar);
+				const apiToken = resolveEnvValue(config?.apiToken, apiTokenEnvVar);
+
+				if (!zoneId || !apiToken) {
+					throw new Error(
+						`[cloudflare-cache-api] Tag-based invalidation requires a Zone ID and API token. ` +
+							`Set the ${zoneIdEnvVar} and ${apiTokenEnvVar} environment variables, ` +
+							`or pass zoneId/apiToken in the cloudflareCache() config.`,
+					);
+				}
+
+				const tags = Array.isArray(options.tags) ? options.tags : [options.tags];
+
+				const response = await fetch(`${CF_API_BASE}/zones/${zoneId}/purge_cache`, {
+					method: "POST",
+					headers: {
+						Authorization: `Bearer ${apiToken}`,
+						"Content-Type": "application/json",
+					},
+					body: JSON.stringify({ tags }),
+				});
+
+				if (!response.ok) {
+					const body = await response.text().catch(() => "");
+					throw new Error(
+						`[cloudflare-cache-api] Cache purge failed (${response.status}): ${body}`,
+					);
+				}
+			}
+
+			if (options.path) {
+				const cache = await getCache();
+				await cache.delete(options.path);
+			}
+		},
+	};
+};
+
+export default factory;

package/src/cloudflare.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Type declarations for Cloudflare virtual modules
+ *
+ * These are only available at runtime on Cloudflare Workers.
+ * The types here are minimal - just enough for our usage.
+ */
+
+declare module "cloudflare:workers" {
+	/**
+	 * Environment bindings object
+	 * Contains all bindings defined in wrangler.toml (D1, R2, KV, etc.)
+	 */
+	export const env: Record<string, unknown>;
+
+	/**
+	 * Exports object for loopback bindings
+	 */
+	export const exports: Record<string, unknown>;
+
+	/**
+	 * Base class for Worker Entrypoints
+	 */
+	export class WorkerEntrypoint<TEnv = unknown, TProps = unknown> {
+		env: TEnv;
+		ctx: ExecutionContext & { props: TProps };
+	}
+}
+
+declare module "cloudflare:email" {
+	// Email worker types if needed
+}

package/src/db/d1-introspector.ts

@@ -0,0 +1,120 @@
+/**
+ * D1-compatible SQLite Introspector
+ *
+ * D1 doesn't allow the correlated cross-join pattern that Kysely's default
+ * SqliteIntrospector uses: `FROM tl, pragma_table_info(tl.name)`
+ *
+ * This introspector queries tables individually instead.
+ */
+
+import type { DatabaseIntrospector, DatabaseMetadata, SchemaMetadata, TableMetadata } from "kysely";
+import { sql } from "kysely";
+
+// Kysely's default migration table names
+const DEFAULT_MIGRATION_TABLE = "kysely_migration";
+const DEFAULT_MIGRATION_LOCK_TABLE = "kysely_migration_lock";
+
+// Kysely's DatabaseIntrospector.createIntrospector receives Kysely<any>.
+// We must use `any` here to match Kysely's own interface contract —
+// it needs untyped schema access to query sqlite_master dynamically.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyKysely = any;
+
+// Regex patterns for parsing CREATE TABLE statements
+const SPLIT_PARENS_PATTERN = /[(),]/;
+const WHITESPACE_PATTERN = /\s+/;
+const QUOTES_PATTERN = /["`]/g;
+
+export class D1Introspector implements DatabaseIntrospector {
+	readonly #db: AnyKysely;
+
+	constructor(db: AnyKysely) {
+		this.#db = db;
+	}
+
+	async getSchemas(): Promise<SchemaMetadata[]> {
+		// SQLite doesn't support schemas
+		return [];
+	}
+
+	async getTables(options: { withInternalKyselyTables?: boolean } = {}): Promise<TableMetadata[]> {
+		// Get table names from sqlite_master
+		let query = this.#db
+			.selectFrom("sqlite_master")
+			.where("type", "in", ["table", "view"])
+			.where("name", "not like", "sqlite_%")
+			.where("name", "not like", "_cf_%") // Skip Cloudflare internal tables
+			.select(["name", "sql", "type"])
+			.orderBy("name");
+
+		if (!options.withInternalKyselyTables) {
+			query = query
+				.where("name", "!=", DEFAULT_MIGRATION_TABLE)
+				.where("name", "!=", DEFAULT_MIGRATION_LOCK_TABLE);
+		}
+
+		const tables = await query.execute();
+
+		// Query each table's columns individually (avoiding the problematic cross-join)
+		const result: TableMetadata[] = [];
+
+		for (const table of tables) {
+			// eslint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- Kysely's DatabaseIntrospector returns untyped results
+			const tableName = table.name as string;
+			// eslint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- Kysely's DatabaseIntrospector returns untyped results
+			const tableType = table.type as string;
+			// eslint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- Kysely's DatabaseIntrospector returns untyped results
+			const tableSql = table.sql as string | null;
+
+			// Get columns for this specific table
+			// Use sql.raw() to insert table name directly into query string
+			// D1 doesn't allow parameterized table names in pragma_table_info()
+			// Note: tableName comes from sqlite_master so it's safe
+			const columns = await sql<{
+				cid: number;
+				name: string;
+				type: string;
+				notnull: number;
+				dflt_value: string | null;
+				pk: number;
+			}>`SELECT * FROM pragma_table_info('${sql.raw(tableName)}')`.execute(this.#db);
+
+			// Try to find autoincrement column from CREATE TABLE statement
+			let autoIncrementCol = tableSql
+				?.split(SPLIT_PARENS_PATTERN)
+				?.find((it) => it.toLowerCase().includes("autoincrement"))
+				?.trimStart()
+				?.split(WHITESPACE_PATTERN)?.[0]
+				?.replace(QUOTES_PATTERN, "");
+
+			// Otherwise, check for INTEGER PRIMARY KEY (implicit autoincrement)
+			if (!autoIncrementCol) {
+				const pkCols = columns.rows.filter((r) => r.pk > 0);
+				if (pkCols.length === 1 && pkCols[0]!.type.toLowerCase() === "integer") {
+					autoIncrementCol = pkCols[0]!.name;
+				}
+			}
+
+			result.push({
+				name: tableName,
+				isView: tableType === "view",
+				columns: columns.rows.map((col) => ({
+					name: col.name,
+					dataType: col.type,
+					isNullable: !col.notnull,
+					isAutoIncrementing: col.name === autoIncrementCol,
+					hasDefaultValue: col.dflt_value != null,
+					comment: undefined,
+				})),
+			});
+		}
+
+		return result;
+	}
+
+	async getMetadata(options?: { withInternalKyselyTables?: boolean }): Promise<DatabaseMetadata> {
+		return {
+			tables: await this.getTables(options),
+		};
+	}
+}

package/src/db/d1.ts

@@ -0,0 +1,112 @@
+/**
+ * Cloudflare D1 runtime adapter - RUNTIME ENTRY
+ *
+ * Creates a Kysely dialect for D1.
+ * Loaded at runtime via virtual module when database queries are needed.
+ *
+ * This module imports directly from cloudflare:workers to access the D1 binding.
+ * Do NOT import this at config time - use { d1 } from "@emdash-cms/cloudflare" instead.
+ */
+
+import { env } from "cloudflare:workers";
+import type { DatabaseIntrospector, Dialect, Kysely } from "kysely";
+import { D1Dialect } from "kysely-d1";
+
+import { D1Introspector } from "./d1-introspector.js";
+
+/**
+ * D1 configuration (runtime type — matches the config-time type in index.ts)
+ */
+interface D1Config {
+	binding: string;
+	session?: "disabled" | "auto" | "primary-first";
+	bookmarkCookie?: string;
+}
+
+/**
+ * Custom D1 Dialect that uses our D1-compatible introspector
+ *
+ * The default kysely-d1 dialect uses SqliteIntrospector which does a
+ * cross-join with pragma_table_info() that D1 doesn't allow.
+ */
+class EmDashD1Dialect extends D1Dialect {
+	override createIntrospector(db: Kysely<any>): DatabaseIntrospector {
+		return new D1Introspector(db);
+	}
+}
+
+/**
+ * Create a D1 dialect from config
+ *
+ * @param config - D1 configuration with binding name
+ */
+export function createDialect(config: D1Config): Dialect {
+	// eslint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- Worker binding accessed from untyped env object
+	const db = (env as Record<string, unknown>)[config.binding];
+
+	if (!db) {
+		throw new Error(
+			`D1 binding "${config.binding}" not found in environment. ` +
+				`Check your wrangler.toml configuration:\n\n` +
+				`[[d1_databases]]\n` +
+				`binding = "${config.binding}"\n` +
+				`database_name = "your-database-name"\n` +
+				`database_id = "your-database-id"`,
+		);
+	}
+
+	// Use our custom dialect with D1-compatible introspector
+	// db is unknown from env access; D1Dialect expects D1Database
+	// eslint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- D1Database binding from untyped env object
+	return new EmDashD1Dialect({ database: db as D1Database });
+}
+
+// =========================================================================
+// D1 Read Replica Session Helpers
+//
+// These are exported through virtual:emdash/dialect so the middleware
+// can create per-request D1 sessions without importing cloudflare:workers.
+// =========================================================================
+
+/**
+ * Whether D1 sessions are enabled in the config.
+ */
+export function isSessionEnabled(config: D1Config): boolean {
+	return !!config.session && config.session !== "disabled";
+}
+
+/**
+ * Get the raw D1 binding for creating sessions.
+ * Returns null if sessions are disabled.
+ */
+export function getD1Binding(config: D1Config): D1Database | null {
+	if (!isSessionEnabled(config)) return null;
+	// eslint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- Worker binding accessed from untyped env object
+	const db = (env as Record<string, unknown>)[config.binding] as D1Database | undefined;
+	return db ?? null;
+}
+
+/**
+ * Get the default session constraint for the config's session mode.
+ */
+export function getDefaultConstraint(config: D1Config): string {
+	if (config.session === "primary-first") return "first-primary";
+	return "first-unconstrained";
+}
+
+/**
+ * Get the cookie name used for storing D1 session bookmarks.
+ */
+export function getBookmarkCookieName(config: D1Config): string {
+	return config.bookmarkCookie ?? "__ec_d1_bookmark";
+}
+
+/**
+ * Create a Kysely dialect from a D1 session object.
+ *
+ * D1DatabaseSession has the same `prepare()` / `batch()` interface
+ * as D1Database, so we pass it directly to D1Dialect.
+ */
+export function createSessionDialect(session: D1Database): Dialect {
+	return new EmDashD1Dialect({ database: session });
+}