emdash 0.21.0 → 0.23.0

package/src/object-cache/types.ts

@@ -0,0 +1,124 @@
+/**
+ * Object cache types
+ *
+ * The object cache is an optional, distributed read-through cache that sits
+ * *beneath* the per-request cache (`requestCached`) and *above* the database.
+ * Query results (content entries, settings, menus, taxonomies) are stored in a
+ * fast key/value store (Cloudflare KV, or an in-isolate memory store for Node)
+ * so repeat reads across requests and isolates skip the database entirely.
+ *
+ * Backends only ever deal in strings — serialization (including `Date`
+ * preservation) is handled by the core read-through layer in `./codec.ts`, so
+ * every backend behaves identically.
+ */
+
+/**
+ * A pluggable object-cache backend.
+ *
+ * Implementations must be safe to call concurrently and should never throw on
+ * cache misses — `get` returns `null` for a miss. A backend that throws (e.g.
+ * a transient KV error) degrades gracefully: the read-through layer treats a
+ * thrown `get` as a miss and a thrown `set` as a no-op, so the database
+ * remains the source of truth.
+ */
+export interface ObjectCacheBackend {
+	/** Return the stored string for `key`, or `null` on a miss. */
+	get(key: string): Promise<string | null>;
+	/**
+	 * Store `value` under `key`.
+	 *
+	 * @param ttlSeconds Optional time-to-live in seconds. Backends that don't
+	 *   support TTLs may ignore it, but distributed backends (KV) should honor
+	 *   it so orphaned, epoch-busted keys are eventually reclaimed.
+	 */
+	set(key: string, value: string, ttlSeconds?: number): Promise<void>;
+	/** Remove `key`. Idempotent — deleting a missing key is not an error. */
+	delete(key: string): Promise<void>;
+}
+
+/**
+ * Serializable descriptor for an object-cache backend.
+ *
+ * Mirrors {@link import("../storage/types.js").StorageDescriptor}: `entrypoint`
+ * is a module specifier resolved at build time that exports a
+ * {@link CreateObjectCacheBackendFn} named `createObjectCache`; `config` is the
+ * plain, serializable runtime config passed to it.
+ */
+export interface ObjectCacheDescriptor {
+	/** Module path exporting a `createObjectCache` function. */
+	entrypoint: string;
+	/** Serializable config passed to `createObjectCache` at runtime. */
+	config: ObjectCacheRuntimeConfig;
+}
+
+/**
+ * Runtime config shared by every backend, plus backend-specific keys.
+ *
+ * The read-through layer reads `defaultTtl`, `revalidate`, and `keyPrefix`;
+ * individual backends read their own keys (e.g. the KV backend reads
+ * `binding`).
+ */
+export interface ObjectCacheRuntimeConfig {
+	/**
+	 * Default time-to-live for cached entries, in seconds.
+	 *
+	 * Invalidation works by epoch comparison, not key deletion: a stale value
+	 * is detected on read (its stored epoch no longer matches) and overwritten
+	 * in place under the same key. The TTL is just a backstop that reclaims
+	 * keys that are never read again.
+	 *
+	 * @default 3600 (1 hour)
+	 */
+	defaultTtl?: number;
+	/**
+	 * How long (milliseconds) an isolate may reuse a cached namespace epoch
+	 * before re-reading it from the backend.
+	 *
+	 * After a write bumps a namespace's epoch, an isolate keeps serving the
+	 * previous epoch's keys until its cached epoch expires after this window. It
+	 * is only part of the cross-isolate staleness: a distributed backend adds its
+	 * own propagation delay (KV's edge cache is eventually consistent, up to
+	 * ~60s), so on KV the effective window is that propagation plus this value.
+	 * Only anonymous visitors are affected — preview and edit requests bypass the
+	 * cache.
+	 *
+	 * Set to `0` to re-read the epoch on every query (strongest freshness, more
+	 * backend reads).
+	 *
+	 * @default 1000
+	 */
+	revalidate?: number;
+	/**
+	 * Prefix applied to every cache key. Lets multiple EmDash sites share one
+	 * KV namespace without colliding.
+	 *
+	 * @default "em"
+	 */
+	keyPrefix?: string;
+	/**
+	 * Maximum time (milliseconds) to wait for a single backend read before
+	 * treating it as a cache miss and falling back to the database.
+	 *
+	 * Guards against a backend operation that stalls without resolving or
+	 * rejecting (e.g. a cold cross-region KV read, or one queued behind the
+	 * Workers simultaneous-connection limit), which would otherwise hang the
+	 * request. A timed-out read degrades to a miss; the database remains the
+	 * source of truth.
+	 *
+	 * Set to `0` to disable the timeout (not recommended on Cloudflare).
+	 *
+	 * @default 2000
+	 */
+	timeout?: number;
+	/** Backend-specific keys (e.g. the KV binding name). */
+	[key: string]: unknown;
+}
+
+/**
+ * Factory signature exported as `createObjectCache` from a backend entrypoint.
+ *
+ * Each backend accesses its own resources directly: the KV backend imports
+ * bindings from `cloudflare:workers`; the memory backend uses an in-isolate
+ * map.
+ */
+export type CreateObjectCacheBackendFn = (config: ObjectCacheRuntimeConfig) => ObjectCacheBackend;

package/src/plugins/adapt-sandbox-entry.ts

@@ -278,7 +278,11 @@ export function adaptSandboxEntry(
 		};
 	}
 
-	// Build admin config from descriptor
+	// Build admin config from descriptor.
+	// Portable Text blocks and field widgets are declarative (Block Kit), so they
+	// are forwarded for standard/sandboxed plugins just like pages and widgets —
+	// the admin editor consumes them from the manifest. Only the site-side render
+	// component (`componentsEntry`) stays native-only.
 	const admin: PluginAdminConfig = {};
 	if (descriptor.adminPages) {
 		admin.pages = descriptor.adminPages;
@@ -286,6 +290,12 @@ export function adaptSandboxEntry(
 	if (descriptor.adminWidgets) {
 		admin.widgets = descriptor.adminWidgets;
 	}
+	if (descriptor.portableTextBlocks) {
+		admin.portableTextBlocks = descriptor.portableTextBlocks;
+	}
+	if (descriptor.fieldWidgets) {
+		admin.fieldWidgets = descriptor.fieldWidgets;
+	}
 
 	return {
 		id: pluginId,

package/src/plugins/context.ts

@@ -432,23 +432,55 @@ export function createMediaAccess(db: Kysely<Database>): MediaAccess {
 
 /**
  * Create full media access with write operations.
- * If storage is not provided, upload() will throw at call time.
+ *
+ * `getUploadUrlFn` is optional: when omitted, `getUploadUrl()` is derived from
+ * `storage` (create a pending record + a signed PUT URL), mirroring the REST
+ * `/_emdash/api/media/upload-url` endpoint. `upload()` only needs `storage`.
+ * If storage is not provided, both throw at call time.
  */
 export function createMediaAccessWithWrite(
 	db: Kysely<Database>,
-	getUploadUrlFn: (
-		filename: string,
-		contentType: string,
-	) => Promise<{ uploadUrl: string; mediaId: string }>,
+	getUploadUrlFn:
+		| ((filename: string, contentType: string) => Promise<{ uploadUrl: string; mediaId: string }>)
+		| undefined,
 	storage?: Storage,
 ): MediaAccessWithWrite {
 	const mediaRepo = new MediaRepository(db);
 	const readAccess = createMediaAccess(db);
 
+	const getUploadUrl =
+		getUploadUrlFn ??
+		(async (filename: string, contentType: string) => {
+			if (!storage) {
+				throw new Error(
+					"Media getUploadUrl() requires a storage backend. Configure storage in PluginContextFactoryOptions.",
+				);
+			}
+
+			const basename = filename.split("/").pop() ?? filename;
+			const dotIdx = basename.lastIndexOf(".");
+			const ext = dotIdx > 0 ? basename.slice(dotIdx).toLowerCase() : "";
+			const storageKey = `${ulid()}${ext}`;
+
+			const media = await mediaRepo.createPending({
+				filename: basename,
+				mimeType: contentType,
+				storageKey,
+			});
+
+			const signed = await storage.getSignedUploadUrl({
+				key: storageKey,
+				contentType,
+				expiresIn: 3600,
+			});
+
+			return { uploadUrl: signed.url, mediaId: media.id };
+		});
+
 	return {
 		...readAccess,
 
-		getUploadUrl: getUploadUrlFn,
+		getUploadUrl,
 
 		async upload(
 			filename: string,
@@ -836,14 +868,26 @@ export function createUserAccess(db: Kysely<Database>): UserAccess {
 
 export interface PluginContextFactoryOptions {
 	db: Kysely<Database>;
+	/**
+	 * Resolver for the database connection, preferred over `db` when present.
+	 * Called per `createContext()` so connection-backed adapters (e.g. Postgres
+	 * over Hyperdrive) get the current request/event-scoped connection from ALS
+	 * rather than a snapshot of the per-isolate singleton — reusing the
+	 * singleton's socket from a later event trips workerd's cross-request I/O
+	 * guard. When omitted, `db` is used directly (correct for stateless
+	 * adapters like D1 and Node SQLite). `db` remains required as the fallback.
+	 */
+	getDb?: () => Kysely<Database>;
 	/**
 	 * Storage backend for direct media uploads.
 	 * If not provided, upload() will throw.
 	 */
 	storage?: Storage;
 	/**
-	 * Function to generate upload URLs for media.
-	 * If not provided, media write operations will throw.
+	 * Explicit provider for `ctx.media.getUploadUrl()`. Optional: when omitted
+	 * but `storage` is configured, the factory derives a working `getUploadUrl()`
+	 * (and `upload()`) from storage. Only when neither `getUploadUrl` nor
+	 * `storage` is present do media write operations become unavailable.
 	 */
 	getUploadUrl?: (
 		filename: string,
@@ -877,8 +921,7 @@ export interface PluginContextFactoryOptions {
  * Factory for creating plugin contexts
  */
 export class PluginContextFactory {
-	private optionsRepo: OptionsRepository;
-	private db: Kysely<Database>;
+	private resolveDb: () => Kysely<Database>;
 	private storage?: Storage;
 	private getUploadUrl?: (
 		filename: string,
@@ -888,10 +931,16 @@ export class PluginContextFactory {
 	private urlHelper: (path: string) => string;
 	private cronReschedule?: () => void;
 	private emailPipeline?: EmailPipeline;
+	/**
+	 * Plugin IDs already warned about a missing media-write backend, so the
+	 * warning fires once per factory instead of on every hook/route context
+	 * creation (which would spam logs for hook-participating plugins).
+	 */
+	private warnedMissingMediaBackend = new Set<string>();
 
 	constructor(options: PluginContextFactoryOptions) {
-		this.db = options.db;
-		this.optionsRepo = new OptionsRepository(options.db);
+		const fixedDb = options.db;
+		this.resolveDb = options.getDb ?? (() => fixedDb);
 		this.storage = options.storage;
 		this.getUploadUrl = options.getUploadUrl;
 		this.site = createSiteInfo(options.siteInfo ?? {});
@@ -906,10 +955,17 @@ export class PluginContextFactory {
 	createContext(plugin: ResolvedPlugin): PluginContext {
 		const capabilities = new Set(plugin.capabilities);
 
+		// Resolve the connection once per context. For stateless adapters this
+		// is the singleton; for connection-backed adapters it's the current
+		// request/event-scoped connection from ALS. All repos below are built
+		// from this local `db` so a hook never queries a stale singleton socket.
+		const db = this.resolveDb();
+		const optionsRepo = new OptionsRepository(db);
+
 		// Always available
-		const kv = createKVAccess(this.optionsRepo, plugin.id);
+		const kv = createKVAccess(optionsRepo, plugin.id);
 		const log = createLogAccess(plugin.id);
-		const storage = createStorageAccess(this.db, plugin.id, plugin.storage);
+		const storage = createStorageAccess(db, plugin.id, plugin.storage);
 
 		// Capability-gated: content
 		// Note: capabilities reach this point already normalized to the
@@ -917,17 +973,33 @@ export class PluginContextFactory {
 		// names ("read:content", "write:content") never appear here.
 		let content: ContentAccess | ContentAccessWithWrite | undefined;
 		if (capabilities.has("content:write")) {
-			content = createContentAccessWithWrite(this.db);
+			content = createContentAccessWithWrite(db);
 		} else if (capabilities.has("content:read")) {
-			content = createContentAccess(this.db);
+			content = createContentAccess(db);
 		}
 
 		// Capability-gated: media
+		// `upload()` only needs `storage`; `getUploadUrl()` is derived from
+		// storage when no explicit provider is wired. Granting write access on
+		// either avoids silently degrading media:write to read-only — the bug
+		// where the runtime threads `storage` but not `getUploadUrl`.
 		let media: MediaAccess | MediaAccessWithWrite | undefined;
-		if (capabilities.has("media:write") && this.getUploadUrl) {
-			media = createMediaAccessWithWrite(this.db, this.getUploadUrl, this.storage);
+		if (capabilities.has("media:write")) {
+			if (this.getUploadUrl || this.storage) {
+				media = createMediaAccessWithWrite(db, this.getUploadUrl, this.storage);
+			} else {
+				if (!this.warnedMissingMediaBackend.has(plugin.id)) {
+					this.warnedMissingMediaBackend.add(plugin.id);
+					log.warn(
+						"declares the media:write capability but no storage backend is configured; upload() is unavailable.",
+					);
+				}
+				if (capabilities.has("media:read")) {
+					media = createMediaAccess(db);
+				}
+			}
 		} else if (capabilities.has("media:read")) {
-			media = createMediaAccess(this.db);
+			media = createMediaAccess(db);
 		}
 
 		// Capability-gated: http
@@ -941,14 +1013,14 @@ export class PluginContextFactory {
 		// Capability-gated: users
 		let users: UserAccess | undefined;
 		if (capabilities.has("users:read")) {
-			users = createUserAccess(this.db);
+			users = createUserAccess(db);
 		}
 
-		// Cron access ��� always available (scoped to plugin), but only if
+		// Cron access — always available (scoped to plugin), but only if
 		// the runtime provided a reschedule callback (i.e. cron is wired up).
 		let cron: CronAccess | undefined;
 		if (this.cronReschedule) {
-			cron = new CronAccessImpl(this.db, plugin.id, this.cronReschedule);
+			cron = new CronAccessImpl(db, plugin.id, this.cronReschedule);
 		}
 
 		// Email access — requires email:send capability AND a configured provider

package/src/plugins/cron.ts

@@ -39,10 +39,26 @@ export type RescheduleFn = () => void;
  * Stateless — all state lives in the database.
  */
 export class CronExecutor {
+	/**
+	 * Resolves the database connection to use for this tick. A resolver (not a
+	 * captured instance) so connection-backed adapters work across events: on
+	 * Cloudflare the `scheduled()` handler installs an event-scoped connection
+	 * in ALS, and this resolves to it instead of the per-isolate singleton
+	 * whose socket belongs to an earlier request. Accepts a plain `Kysely` too
+	 * (wrapped in a constant resolver) for callers/tests that don't need ALS.
+	 */
+	private readonly resolveDb: () => Kysely<Database>;
+
 	constructor(
-		private db: Kysely<Database>,
+		db: Kysely<Database> | (() => Kysely<Database>),
 		private invokeCronHook: InvokeCronHookFn,
-	) {}
+	) {
+		this.resolveDb = typeof db === "function" ? db : () => db;
+	}
+
+	private get db(): Kysely<Database> {
+		return this.resolveDb();
+	}
 
 	/**
 	 * Process all overdue tasks.

package/src/plugins/routes.ts

@@ -12,6 +12,42 @@ import { PluginContextFactory, type PluginContextFactoryOptions } from "./contex
 import { extractRequestMeta } from "./request-meta.js";
 import type { ResolvedPlugin, RouteContext, PluginRoute } from "./types.js";
 
+/**
+ * Body-reading methods on `Request`. EmDash parses the request body once before
+ * the handler runs and exposes the result as `ctx.input`, leaving the underlying
+ * stream consumed. Calling any of these on `ctx.request` would re-read a spent
+ * stream and throw an opaque platform error ("Body is unusable: Body has already
+ * been read") with no hint about `ctx.input` — so the guard replaces them with an
+ * actionable message instead (#1293).
+ */
+const CONSUMED_BODY_METHODS = new Set(["json", "text", "arrayBuffer", "blob", "formData", "bytes"]);
+
+/**
+ * Wrap the request handed to a plugin route handler so an accidental
+ * `ctx.request.json()` (or `.text()`, `.formData()`, …) fails with a message
+ * pointing at `ctx.input` rather than the runtime's cryptic "body already read"
+ * error. Every non-body member passes through unchanged; function members are
+ * bound to the underlying request so methods like `clone()` don't throw an
+ * "Illegal invocation" when called on the proxy.
+ */
+function guardConsumedRequestBody(request: Request): Request {
+	return new Proxy(request, {
+		get(target, prop) {
+			if (typeof prop === "string" && CONSUMED_BODY_METHODS.has(prop)) {
+				return () => {
+					throw new Error(
+						`[emdash] ctx.request.${prop}() is not available inside a plugin route handler: ` +
+							`EmDash has already parsed the request body and exposes it as ctx.input. ` +
+							`Read ctx.input instead of ctx.request.${prop}().`,
+					);
+				};
+			}
+			const value = Reflect.get(target, prop, target);
+			return typeof value === "function" ? value.bind(target) : value;
+		},
+	});
+}
+
 /**
  * Route metadata (public flag) without the handler.
  * Used by the catch-all route to decide auth before dispatch.
@@ -100,7 +136,10 @@ export class PluginRouteHandler {
 		const routeContext: RouteContext = {
 			...baseContext,
 			input: validatedInput,
-			request: options.request,
+			// The body is already parsed into `input`; guard `ctx.request`'s
+			// body-reading methods so a re-read fails with an actionable message
+			// (#1293). Metadata extraction uses the original request (headers only).
+			request: guardConsumedRequestBody(options.request),
 			requestMeta: extractRequestMeta(options.request, this.trustedProxyHeaders),
 		};