emdash 0.34.0 → 0.36.0

package/src/astro/middleware/scoped-db.ts

@@ -24,6 +24,27 @@ interface ScopedDbLifecycle {
 	close?: () => void;
 }
 
+/**
+ * Whether the request ended authenticated, for the db adapter's `commit()`.
+ * `isAuthenticated` is captured before the route runs, so it misses
+ * login/signup/invite requests that create the Astro session mid-request;
+ * `session.set()` writes the `astro-session` cookie into the jar synchronously,
+ * so scanning the outgoing cookies detects them. Only outgoing cookies count —
+ * a stale `astro-session` cookie arriving on an anonymous render must not
+ * qualify, or its replica-read bookmark would overwrite a fresher one from an
+ * earlier authenticated write.
+ */
+export function requestEndedAuthenticated(
+	isAuthenticated: boolean,
+	cookies: { headers(): Iterable<string> },
+): boolean {
+	if (isAuthenticated) return true;
+	for (const header of cookies.headers()) {
+		if (header.startsWith("astro-session=")) return true;
+	}
+	return false;
+}
+
 /** Hold the real adapter close behind both response and deferred-task completion. */
 export function coordinateScopedDbLifecycle(scoped: ScopedDbLifecycle): {
 	closed?: Promise<void>;

package/src/astro/middleware.ts

@@ -39,11 +39,15 @@ import {
 	flushRecorder,
 	isInstrumentationEnabled,
 } from "../database/instrumentation.js";
+import {
+	PendingMigrationsError,
+	resolveRuntimeMigrationMode,
+	type RuntimeMigrationMode,
+} from "../database/migrations/policy.js";
 import { createDeferredTaskTracker } from "../deferred-tasks.js";
 import {
 	DB_INIT_DEADLINE_MS,
 	EmDashRuntime,
-	type MediaUsageMaintenanceResult,
 	type RuntimeDependencies,
 	type SandboxedPluginEntry,
 	type MediaProviderEntry,
@@ -70,6 +74,7 @@ import {
 	ASTRO_COOKIES_SYMBOL,
 	coordinateScopedDbLifecycle,
 	finishScoped,
+	requestEndedAuthenticated,
 } from "./middleware/scoped-db.js";
 import { wrapBodyForStreamMetrics } from "./middleware/stream-end-metrics.js";
 import { prefetchLayoutData } from "./prefetch.js";
@@ -192,7 +197,10 @@ function getPlugins(): ResolvedPlugin[] {
 /**
  * Build runtime dependencies from virtual modules
  */
-function buildDependencies(config: EmDashConfig): RuntimeDependencies {
+function buildDependencies(
+	config: EmDashConfig,
+	migrationMode: RuntimeMigrationMode,
+): RuntimeDependencies {
 	/* eslint-disable typescript-eslint/no-unsafe-type-assertion --
 	   The virtual:emdash/* imports above use @ts-ignore because tsgo/IDE
 	   resolution can't see virtual-modules.d.ts in every consumer setup,
@@ -202,6 +210,7 @@ function buildDependencies(config: EmDashConfig): RuntimeDependencies {
 	const sandboxModule = virtualSandboxRunnerModule as Record<string, unknown>;
 	return {
 		config,
+		migrationMode,
 		plugins: getPlugins(),
 		createDialect: virtualCreateDialect as (config: Record<string, unknown>) => unknown,
 		// Optional: only batching backends (D1, DO) export this; undefined otherwise.
@@ -229,6 +238,7 @@ function buildDependencies(config: EmDashConfig): RuntimeDependencies {
  */
 async function getRuntime(
 	config: EmDashConfig,
+	migrationMode: RuntimeMigrationMode,
 	initTimings?: Array<{ name: string; dur: number; desc?: string }>,
 ): Promise<EmDashRuntime> {
 	// Waiters poll rather than awaiting the initializing request's promise —
@@ -243,7 +253,7 @@ async function getRuntime(
 		holder.lock,
 		() => holder.instance,
 		async (isCurrentClaim) => {
-			const deps = buildDependencies(config);
+			const deps = buildDependencies(config, migrationMode);
 			const runtime = await EmDashRuntime.create(deps, initTimings);
 			if (isCurrentClaim()) {
 				holder.instance = runtime;
@@ -289,12 +299,6 @@ export async function runScheduledTasks(
 	return runOutsideRequest(config, (runtime) => runtime.runScheduledTasks(options));
 }
 
-export async function runScheduledMediaUsageTasks(): Promise<MediaUsageMaintenanceResult> {
-	const config = getConfig();
-	if (!config) return { outcome: "inactive", taskClass: null, turn: null };
-	return runOutsideRequest(config, (runtime) => runtime.runScheduledMediaUsageTasks());
-}
-
 /**
  * Run a callback against the EmDash runtime outside any HTTP request — from a
  * Cloudflare Queue consumer, a `scheduled()` handler, or any other
@@ -360,8 +364,9 @@ async function runOutsideRequest<T>(
 	config: EmDashConfig,
 	fn: (runtime: EmDashRuntime) => Promise<T>,
 ): Promise<T> {
+	const migrationMode = resolveConfiguredMigrationMode(config);
 	if (getRequestContext()) {
-		const runtime = await getRuntime(config);
+		const runtime = await getRuntime(config, migrationMode);
 		return runOutsideRequestWithRuntime(config, runtime, fn);
 	}
 
@@ -374,7 +379,7 @@ async function runOutsideRequest<T>(
 	return runWithContext(context, async () => {
 		const runtime = await (async () => {
 			try {
-				return await getRuntime(config);
+				return await getRuntime(config, migrationMode);
 			} finally {
 				deferredTasks.settle();
 				await deferredTasks.settled;
@@ -452,6 +457,31 @@ const NOOP_COOKIE_JAR = {
  */
 const CRON_EVENT_URL = new URL("https://cron.emdash.internal/");
 
+function resolveConfiguredMigrationMode(config: EmDashConfig): RuntimeMigrationMode {
+	const processOverride =
+		typeof process !== "undefined" && process.env ? process.env.EMDASH_MIGRATIONS_MODE : undefined;
+	const importMetaOverride = import.meta.env.EMDASH_MIGRATIONS_MODE;
+	return resolveRuntimeMigrationMode(config.migrations, {
+		dev: import.meta.env.DEV,
+		override: processOverride ?? importMetaOverride,
+	});
+}
+
+function pendingMigrationsResponse(error: PendingMigrationsError): Response {
+	console.error("[emdash] database migrations are pending:", error.pending.join(", "));
+	return migrationRequiredResponse();
+}
+
+function migrationRequiredResponse(): Response {
+	return new Response(
+		"Database migrations are required. Apply the deployment migration manifest and retry.",
+		{
+			status: 503,
+			headers: { "Retry-After": "60" },
+		},
+	);
+}
+
 /**
  * Baseline security headers applied to all responses.
  * Admin routes get additional headers (strict CSP) from auth middleware.
@@ -601,6 +631,8 @@ export const onRequest = defineMiddleware(async (context, next) => {
 	const metrics = createRequestMetrics(performance.now());
 
 	const run = async (): Promise<Response> => {
+		const config = getConfig();
+		const migrationMode = config ? resolveConfiguredMigrationMode(config) : "auto";
 		// Process /_emdash routes and public routes with an active session
 		// (logged-in editors need the runtime for toolbar/visual editing on public pages)
 		const isEmDashRoute = url.pathname.startsWith("/_emdash");
@@ -643,6 +675,7 @@ export const onRequest = defineMiddleware(async (context, next) => {
 			.startsWith("bearer ");
 		const isWrite = request.method !== "GET" && request.method !== "HEAD";
 		const isAuthenticated = !!sessionUser || hasBearerAuth;
+		const endedAuthenticated = () => requestEndedAuthenticated(isAuthenticated, cookies);
 		const canUseCachedBinding =
 			!isAuthenticated &&
 			!isWrite &&
@@ -668,7 +701,7 @@ export const onRequest = defineMiddleware(async (context, next) => {
 				// production. The build database is legitimately empty in CI and there
 				// is no live visitor to send to the wizard at build time (session reads
 				// are already skipped for prerender above for the same reason).
-				if (!isSetupVerified() && !context.isPrerendered) {
+				if (migrationMode === "auto" && !isSetupVerified() && !context.isPrerendered) {
 					const t0 = performance.now();
 					try {
 						const { getDb } = await import("../loader.js");
@@ -695,14 +728,13 @@ export const onRequest = defineMiddleware(async (context, next) => {
 				// The runtime is a cached singleton — after the first request,
 				// getRuntime() is just a null-check. This enables SEO plugins to
 				// contribute meta tags for all visitors, not just logged-in editors.
-				const config = getConfig();
 				if (config) {
 					// Sub-phase timings are populated only on the cold init. Warm
 					// requests hit the cached runtime and leave this empty.
 					const initSubTimings: Array<{ name: string; dur: number; desc?: string }> = [];
 					const t0 = performance.now();
 					try {
-						const runtime = await getRuntime(config, initSubTimings);
+						const runtime = await getRuntime(config, migrationMode, initSubTimings);
 						markSetupVerified();
 						const handlePublicPluginApiRoute = createPublicPluginApiRouteHandler(runtime);
 						// eslint-disable-next-line typescript/no-unsafe-type-assertion -- partial object; getPageRuntime() only checks for the page-contribution methods
@@ -717,6 +749,16 @@ export const onRequest = defineMiddleware(async (context, next) => {
 							storage: runtime.storage,
 						} as EmDashHandlers;
 					} catch (error) {
+						if (error instanceof PendingMigrationsError) {
+							return pendingMigrationsResponse(error);
+						}
+						if (migrationMode === "manual" && isMissingTableError(error)) {
+							console.error(
+								"[emdash] database schema is unavailable in manual migration mode:",
+								error,
+							);
+							return migrationRequiredResponse();
+						}
 						// Non-fatal — EmDashHead falls back to base SEO contributions —
 						// but log it (throttled): a persistently failing init (e.g. a
 						// failing migration, #1744) is otherwise invisible on the
@@ -743,6 +785,7 @@ export const onRequest = defineMiddleware(async (context, next) => {
 				const anonScoped = createRequestScopedDb({
 					config: config?.database?.config,
 					isAuthenticated,
+					endedAuthenticated,
 					isWrite,
 					canUseCachedBinding,
 					cookies,
@@ -796,7 +839,6 @@ export const onRequest = defineMiddleware(async (context, next) => {
 			}
 		}
 
-		const config = getConfig();
 		if (!config) {
 			console.error("EmDash: No configuration found");
 			return finalizeResponse(await next());
@@ -816,14 +858,14 @@ export const onRequest = defineMiddleware(async (context, next) => {
 				// instance and `initSubTimings` stays empty.
 				const initSubTimings: Array<{ name: string; dur: number; desc?: string }> = [];
 				let t0 = performance.now();
-				const runtime = await getRuntime(config, initSubTimings);
+				const runtime = await getRuntime(config, migrationMode, initSubTimings);
 				timings.push({ name: "rt", dur: performance.now() - t0, desc: "Runtime init" });
 				// Forward any sub-phase samples so cold-start breakdown is visible
 				// in Server-Timing. Each phase appears prefixed "rt." to distinguish
 				// from the aggregate "rt" timing above.
 				for (const sub of initSubTimings) timings.push(sub);
 
-				// Runtime init runs migrations, so the DB is guaranteed set up
+				// Runtime initialization has satisfied the effective migration policy.
 				markSetupVerified();
 
 				// The manifest is no longer pre-loaded here. It's admin-only
@@ -942,6 +984,13 @@ export const onRequest = defineMiddleware(async (context, next) => {
 					setPluginStatus: runtime.setPluginStatus.bind(runtime),
 				};
 			} catch (error) {
+				if (error instanceof PendingMigrationsError) {
+					return pendingMigrationsResponse(error);
+				}
+				if (migrationMode === "manual" && isMissingTableError(error)) {
+					console.error("[emdash] database schema is unavailable in manual migration mode:", error);
+					return migrationRequiredResponse();
+				}
 				console.error("EmDash middleware error:", error);
 			}
 
@@ -956,6 +1005,7 @@ export const onRequest = defineMiddleware(async (context, next) => {
 			const scoped = createRequestScopedDb({
 				config: config?.database?.config,
 				isAuthenticated,
+				endedAuthenticated,
 				isWrite,
 				canUseCachedBinding,
 				cookies: context.cookies,

package/src/astro/routes/api/admin/media-usage/activation.ts

@@ -0,0 +1,42 @@
+import type { APIRoute } from "astro";
+
+import { requirePerm } from "#api/authorize.js";
+import { requireDb, unwrapResult } from "#api/error.js";
+import {
+	handleMediaUsageActivationAdvance,
+	handleMediaUsageActivationStatus,
+} from "#api/handlers/media-usage-activation.js";
+import { isParseError, parseBody } from "#api/parse.js";
+import { mediaUsageActivationAdvanceBody } from "#api/schemas.js";
+import { requireScope } from "#auth/scopes.js";
+
+export const prerender = false;
+
+export const GET: APIRoute = async ({ locals }) => {
+	const { emdash, user } = locals;
+	const dbErr = requireDb(emdash?.db);
+	if (dbErr) return dbErr;
+
+	const denied = requirePerm(user, "schema:manage");
+	if (denied) return denied;
+	const scopeDenied = requireScope(locals, "admin");
+	if (scopeDenied) return scopeDenied;
+
+	return unwrapResult(await handleMediaUsageActivationStatus(emdash.db));
+};
+
+export const POST: APIRoute = async ({ request, locals }) => {
+	const { emdash, user } = locals;
+	const dbErr = requireDb(emdash?.db);
+	if (dbErr) return dbErr;
+
+	const denied = requirePerm(user, "schema:manage");
+	if (denied) return denied;
+	const scopeDenied = requireScope(locals, "admin");
+	if (scopeDenied) return scopeDenied;
+
+	const body = await parseBody(request, mediaUsageActivationAdvanceBody);
+	if (isParseError(body)) return body;
+
+	return unwrapResult(await handleMediaUsageActivationAdvance(emdash.db, body));
+};

package/src/astro/routes/api/admin/media-usage/progress.ts

@@ -0,0 +1,37 @@
+import type { APIRoute } from "astro";
+
+import { requirePerm } from "#api/authorize.js";
+import { requireDb, unwrapResult } from "#api/error.js";
+import {
+	handleMediaUsageProgress,
+	handleMediaUsageProgressAdvance,
+} from "#api/handlers/media-usage.js";
+import { requireScope } from "#auth/scopes.js";
+
+export const prerender = false;
+
+export const GET: APIRoute = async ({ locals }) => {
+	const { emdash, user } = locals;
+	const dbErr = requireDb(emdash?.db);
+	if (dbErr) return dbErr;
+
+	const denied = requirePerm(user, "schema:manage");
+	if (denied) return denied;
+	const scopeDenied = requireScope(locals, "admin");
+	if (scopeDenied) return scopeDenied;
+
+	return unwrapResult(await handleMediaUsageProgress(emdash.db));
+};
+
+export const POST: APIRoute = async ({ locals }) => {
+	const { emdash, user } = locals;
+	const dbErr = requireDb(emdash?.db);
+	if (dbErr) return dbErr;
+
+	const denied = requirePerm(user, "schema:manage");
+	if (denied) return denied;
+	const scopeDenied = requireScope(locals, "admin");
+	if (scopeDenied) return scopeDenied;
+
+	return unwrapResult(await handleMediaUsageProgressAdvance(emdash.db));
+};