caracms 0.5.1 → 0.6.0

package/src/cloud-middleware.ts

@@ -0,0 +1,76 @@
+/**
+ * The settings fetch for a cloud site's media (caracms-cloud M3 Decision 20). The package
+ * has no boot hook in the built server, so **the first request that reaches the server, of
+ * any kind,** fetches `GET /v1/settings` (live/cloud.ts → `loadCloudSettings`) and every
+ * request waits on that one shared fetch before anything renders. The live runtime reads the
+ * same held answer, so it's one fetch per process. Prerendered pages are files and never wait.
+ *
+ * - Registered first (`addMiddleware({ order: 'pre' })` in index.ts), before the editor's.
+ * - Only for a cloud site's media: `CARACMS_CLOUD_KEY` set, `CARACMS_MEDIA` not `memory`,
+ *   and none of the site's own media variables (that's `readMediaConfig`'s problem sentence).
+ * - A fetch that fails leaves the media unset (v3's handling: the editor's media routes 503
+ *   with the cloud's sentence) and is tried again by a request after `RETRY_MS`, so a cloud
+ *   that's away doesn't hold every request for its timeout.
+ *
+ * `cloudSettingsForBuild()` is the build's start (`astro:build:start`): the same fetch, and
+ * a refusal or an unreachable cloud **fails the build** with the cloud's sentence or the
+ * package's own. The build ignores `github.repo`: a site with no repo linked still builds.
+ */
+import type { MiddlewareHandler } from 'astro';
+import { CLOUD_NO_MEDIA, CLOUD_UNREACHABLE_BUILD, isCloudRefusal, heldCloudSettings, loadCloudSettings } from './live/cloud.ts';
+import { cloudMedia } from './media.ts';
+
+type Env = Record<string, string | undefined>;
+
+/** After a failed fetch, requests in the next half minute don't wait on another. */
+export const RETRY_MS = 30_000;
+
+const NEXT_TRY = Symbol.for('caracms.cloudSettingsNextTry');
+const LOGGED = Symbol.for('caracms.cloudSettingsLogged');
+type Shared = { [NEXT_TRY]?: number; [LOGGED]?: string };
+
+/** Fetch the settings if this process doesn't hold them yet (and isn't waiting out a failure). */
+export async function ensureCloudSettings(env: Env = process.env, now = Date.now(), log: (line: string) => void = (line) => console.error(line)): Promise<void> {
+	const cloud = cloudMedia(env);
+	if (!cloud || cloud.problems.length) return;
+	if (heldCloudSettings(cloud.connection)?.kind === 'ready') return;
+	const g = globalThis as Shared;
+	if ((g[NEXT_TRY] ?? 0) > now) return;
+	try {
+		await loadCloudSettings(cloud.connection);
+		delete g[NEXT_TRY];
+		delete g[LOGGED];
+	} catch (error) {
+		g[NEXT_TRY] = now + RETRY_MS;
+		const line = isCloudRefusal(error) ? `CaraCMS Cloud (${error.error}): ${error.message}` : 'CaraCMS Cloud: the settings could not be read';
+		if (g[LOGGED] !== line) log(`[caracms] the media settings could not be fetched: ${line}`);
+		g[LOGGED] = line;
+	}
+}
+
+/** Forget the retry clock (tests). */
+export function resetCloudSettingsRetry(): void {
+	const g = globalThis as Shared;
+	delete g[NEXT_TRY];
+	delete g[LOGGED];
+}
+
+export const onRequest: MiddlewareHandler = async (_context, next) => {
+	await ensureCloudSettings();
+	return next();
+};
+
+/** The build's start: the settings, or an Error with the sentence that fails the build. Nothing for a site off the cloud. */
+export async function cloudSettingsForBuild(env: Env = process.env): Promise<void> {
+	const cloud = cloudMedia(env);
+	if (!cloud) return;
+	if (cloud.problems.length) throw new Error(`caracms: ${cloud.problems.join(' ')}`);
+	let settings;
+	try {
+		settings = await loadCloudSettings(cloud.connection);
+	} catch (error) {
+		const message = isCloudRefusal(error) && error.error !== 'unreachable' ? error.message : CLOUD_UNREACHABLE_BUILD;
+		throw new Error(`caracms: ${message}`);
+	}
+	if (!settings.media) throw new Error(`caracms: ${CLOUD_NO_MEDIA}`);
+}

package/src/editor/README.md

@@ -29,7 +29,8 @@ and an alt already used), `GET thumbnail?key=&width=` (a 302 to the signed URL),
 `POST video-upload`, `GET video-upload/<id>`, `GET clips`, `GET clips/<id>`, `GET playback/<id>`.
 Every shape is in `types.ts` → `MEDIA_ENDPOINTS`. `server/media/`: `sniff.ts` (the type and size
 from the bytes), `upload.ts` (the 40 MB cap, the key rule, no overwrite), `bucket.ts` (S3 through
-aws4fetch, and the in-memory bucket), `library.ts` (the 60 s listing, metadata per key,
+aws4fetch, and the in-memory bucket), `cloud-bucket.ts` (the same seam on CaraCMS Cloud's media
+API, `CARACMS_CLOUD_KEY`), `library.ts` (the 60 s listing, metadata per key,
 where-used), `mux.ts` (the template's Mux rules), `alt.ts` (`WaitingView.missingAlt`),
 `config.ts` (503s, images and clips apart) and `memory.ts` (`CARACMS_MEDIA=memory`: `memoryMedia()`
 to seed the bucket and the fake Mux in tests).

package/src/editor/server/media/cloud-bucket.ts

@@ -0,0 +1,144 @@
+/**
+ * The media bucket on CaraCMS Cloud (caracms-cloud M3 Decision 21), behind bucket.ts's
+ * seam, so the upload route (checks, key, dedupe, metadata) and the files route don't
+ * change. The site's server never holds R2 credentials: it asks the API (live/cloud.ts,
+ * the site key) and the API answers for the site's own folder. Keys stay `uploads/…`:
+ * the cloud adds `sites/<folder>/` and strips it again.
+ *
+ * - `list` and `first`: `GET /v1/media/list`, following its `next` tokens (`list`) or one page (`first`).
+ * - `head`: `GET /v1/media/object`; `404 not_found` is "no such object".
+ * - `get`: `POST /v1/media/download-url`, then the presigned GET, streamed (the files route).
+ * - `put`: `POST /v1/media/upload-url`, then the presigned PUT with exactly the headers it names.
+ *
+ * **The cloud's refusals are shown as sent** (`CloudRefusal`: `upload_limit`'s sentence,
+ * `storage_unavailable`'s); the media handler puts the message in its 502. A cloud that
+ * can't be reached, and the storage's own answers to the presigned URLs, are BucketErrors
+ * (the handler's own sentences). Presigned URLs go nowhere but the fetch here: never in
+ * a log line, an error or an answer to the browser.
+ */
+import { isCloudRefusal, cloudCall, type CloudConnection } from '../../../live/cloud.ts';
+import { BucketError, type Bucket, type BucketObject, type ObjectMeta } from './bucket.ts';
+
+const STORAGE_TIMEOUT_MS = 20_000;
+/** A runaway-token guard, as s3Bucket's: 1000 pages of 1000 is far past one site's library. */
+const MAX_PAGES = 1000;
+
+const num = (v: unknown) => (typeof v === 'number' && Number.isFinite(v) && v > 0 ? Math.round(v) : null);
+const text = (v: unknown) => (typeof v === 'string' && v ? v : null);
+const iso = (v: unknown) => (typeof v === 'string' && !Number.isNaN(Date.parse(v)) ? new Date(v).toISOString() : null);
+
+export function cloudBucket(connection: Pick<CloudConnection, 'key' | 'url'>, fetchImpl: typeof fetch = (...args) => globalThis.fetch(...args)): Bucket {
+	const conn: CloudConnection = { ...connection, fetch: fetchImpl };
+
+	/** One API call; a cloud that can't be reached is a BucketError, any other refusal goes up as sent. */
+	async function api(method: 'GET' | 'POST', path: string, body?: unknown): Promise<Record<string, unknown>> {
+		try {
+			return await cloudCall(conn, method, path, body);
+		} catch (error) {
+			if (isCloudRefusal(error) && error.error === 'unreachable') throw new BucketError(`${method} ${path.split('?')[0]}: CaraCMS Cloud unreachable`);
+			throw error;
+		}
+	}
+
+	/** A presigned URL's request. The timeout covers the wait for the storage's headers (a `get` streams after). */
+	async function storage(what: string, url: string, init: RequestInit): Promise<Response> {
+		const controller = new AbortController();
+		const timer = setTimeout(() => controller.abort(new Error(`no answer in ${STORAGE_TIMEOUT_MS / 1000} s`)), STORAGE_TIMEOUT_MS);
+		try {
+			return await fetchImpl(url, { ...init, signal: controller.signal });
+		} catch (error) {
+			throw new BucketError(`${what}: storage unreachable (${error instanceof Error ? error.message : String(error)})`);
+		} finally {
+			clearTimeout(timer);
+		}
+	}
+
+	async function page(prefix: string, after: string | null): Promise<{ objects: BucketObject[]; next: string | null }> {
+		const query = new URLSearchParams({ prefix });
+		if (after) query.set('after', after);
+		const answer = await api('GET', `/v1/media/list?${query}`);
+		if (!Array.isArray(answer.objects)) throw new BucketError(`list ${prefix}: the answer has no objects`);
+		const objects: BucketObject[] = [];
+		for (const o of answer.objects as Record<string, unknown>[]) {
+			const key = o && typeof o === 'object' ? text(o.key) : null;
+			if (!key) continue;
+			objects.push({ key, lastModified: iso(o.lastModified), size: typeof o.size === 'number' && Number.isFinite(o.size) ? o.size : null });
+		}
+		return { objects, next: text(answer.next) };
+	}
+
+	return {
+		async list(prefix) {
+			const out: BucketObject[] = [];
+			const seen = new Set<string>();
+			let after: string | null = null;
+			for (let n = 0; n < MAX_PAGES; n++) {
+				const { objects, next } = await page(prefix, after);
+				out.push(...objects);
+				if (!next || seen.has(next)) break;
+				seen.add(next);
+				after = next;
+			}
+			return out;
+		},
+		async first(prefix) {
+			const { objects } = await page(prefix, null);
+			return objects[0]?.key ?? null;
+		},
+		async head(key): Promise<ObjectMeta | null> {
+			let answer: Record<string, unknown>;
+			try {
+				answer = await api('GET', `/v1/media/object?${new URLSearchParams({ key })}`);
+			} catch (error) {
+				if (isCloudRefusal(error) && error.error === 'not_found') return null;
+				throw error;
+			}
+			return {
+				w: num(answer.w),
+				h: num(answer.h),
+				name: text(answer.name),
+				by: text(answer.by),
+				contentType: text(answer.contentType),
+				lastModified: iso(answer.lastModified),
+				size: typeof answer.size === 'number' && Number.isFinite(answer.size) ? answer.size : null,
+			};
+		},
+		async get(key) {
+			const { url } = await api('POST', '/v1/media/download-url', { key });
+			if (typeof url !== 'string' || !/^https?:\/\//.test(url)) throw new BucketError(`get ${key}: the answer has no URL`);
+			const res = await storage(`get ${key}`, url, { method: 'GET' });
+			if (res.status === 404) {
+				await res.body?.cancel().catch(() => {});
+				return null;
+			}
+			if (!res.ok || !res.body) {
+				await res.body?.cancel().catch(() => {});
+				throw new BucketError(`get ${key}: ${res.status}`, res.status);
+			}
+			const size = Number(res.headers.get('content-length'));
+			return { body: res.body, size: res.headers.has('content-length') && Number.isFinite(size) ? size : null };
+		},
+		async put({ key, body, contentType, sha256, meta }) {
+			const answer = await api('POST', '/v1/media/upload-url', {
+				key,
+				size: body.byteLength,
+				contentType,
+				sha256,
+				meta: { ...(meta.w !== undefined ? { w: meta.w } : {}), ...(meta.h !== undefined ? { h: meta.h } : {}), name: meta.name, by: meta.by },
+			});
+			const { url, method, headers } = answer;
+			if (typeof url !== 'string' || !/^https?:\/\//.test(url) || (method !== undefined && method !== 'PUT') || !headers || typeof headers !== 'object') {
+				throw new BucketError(`put ${key}: the upload answer isn't one`);
+			}
+			// The headers as the cloud named them, verbatim (the URL signs each one). Content-Length and Host
+			// are fetch's own to send: the body is exactly the declared size, and the URL's host is the signed one.
+			const sent = Object.fromEntries(
+				Object.entries(headers as Record<string, unknown>).filter(([name, v]) => typeof v === 'string' && !/^(content-length|host)$/i.test(name)),
+			) as Record<string, string>;
+			const res = await storage(`put ${key}`, url, { method: 'PUT', headers: sent, body: body as BodyInit });
+			await res.body?.cancel().catch(() => {});
+			// 412: R2 refused the signed If-None-Match: * because the key is there, and the key carries the bytes' hash: already stored.
+			if (!res.ok && res.status !== 412) throw new BucketError(`put ${key}: ${res.status}`, res.status);
+		},
+	};
+}

package/src/editor/server/media/config.ts

@@ -10,8 +10,12 @@
  * - Images need imgproxy's (`CARACMS_MEDIA_URL`, `IMGPROXY_KEY`, `IMGPROXY_SALT`, which
  *   sign the thumbnails) and the bucket's (`S3_BUCKET`, `S3_ENDPOINT`, `S3_REGION`,
  *   `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`). Clips need `MUX_TOKEN_ID` and `MUX_TOKEN_SECRET`.
+ * - **On CaraCMS Cloud** (caracms-cloud M3 Decision 19) `CARACMS_CLOUD_KEY` is the images'
+ *   one credential: the bucket is the cloud's (cloud-bucket.ts), the signing from the
+ *   settings the process holds (../../../media.ts). Mux is unchanged.
  */
-import { isProductionBuild, readMediaConfig, type MediaSettings } from '../../../media.ts';
+import type { CloudConnection } from '../../../live/cloud.ts';
+import { cloudMedia, isProductionBuild, readMediaConfig, type MediaSettings } from '../../../media.ts';
 
 type Env = Record<string, string | undefined>;
 
@@ -26,6 +30,7 @@ export interface BucketSettings {
 export type ImagesConfig =
 	| { kind: 'memory'; signing: MediaSettings }
 	| { kind: 's3'; signing: MediaSettings; bucket: BucketSettings }
+	| { kind: 'cloud'; signing: MediaSettings; connection: Pick<CloudConnection, 'key' | 'url'> }
 	| { kind: 'unset'; message: string; missing: string[] };
 
 export type MuxConfig = { kind: 'memory' } | { kind: 'mux'; tokenId: string; tokenSecret: string } | { kind: 'unset'; message: string; missing: string[] };
@@ -48,6 +53,11 @@ export function readImagesConfig(env: Env = process.env, production = isProducti
 		return { kind: 'memory', signing: signing.settings };
 	}
 	const signing = readMediaConfig(env, production);
+	const cloud = cloudMedia(env);
+	if (cloud) {
+		if (signing.kind === 'ready') return { kind: 'cloud', signing: signing.settings, connection: cloud.connection };
+		return { kind: 'unset', message: signing.problems.join(' '), missing: [] };
+	}
 	const missing = signing.kind === 'unset' ? [...signing.missing] : [];
 	const problems = signing.kind === 'unset' ? [...signing.problems] : [];
 	const need = (name: string) => {

package/src/editor/server/media/handler.ts

@@ -41,6 +41,8 @@ import type { DraftsStore } from '../drafts-store.ts';
 import { parseReplaceBody } from '../replace.ts';
 import { checkOrigin, seqOf, tabOf, WriteRefused } from '../write.ts';
 import { BucketError, s3Bucket, type Bucket } from './bucket.ts';
+import { cloudBucket } from './cloud-bucket.ts';
+import { isCloudRefusal } from '../../../live/cloud.ts';
 import { readImagesConfig, readMuxConfig } from './config.ts';
 import { isFileKey } from '../../../files.ts';
 import { entryOf, fileEntryOf, libraryFor, mediaUses, UPLOADS, type Library, type MediaUses } from './library.ts';
@@ -76,6 +78,7 @@ function images(ctx: MediaContext): { library: Library; signing: MediaSettings }
 	const config = readImagesConfig(ctx.env ?? process.env, ctx.production);
 	if (config.kind === 'unset') return json(503, { error: config.message, code: 'media-unset', missing: config.missing } satisfies MediaUnset);
 	if (config.kind === 'memory') return { library: libraryFor('memory', () => memoryMedia().bucket), signing: config.signing };
+	if (config.kind === 'cloud') return { library: libraryFor(`cloud:${config.connection.url}:${config.signing.prefix}`, (): Bucket => cloudBucket(config.connection, ctx.fetch)), signing: config.signing };
 	const b = config.bucket;
 	return { library: libraryFor(`s3:${b.endpoint}:${b.bucket}:${b.accessKeyId}`, (): Bucket => s3Bucket(b, ctx.fetch)), signing: config.signing };
 }
@@ -210,6 +213,11 @@ export async function handleMedia(request: Request, ctx: MediaContext): Promise<
 		if (error instanceof UploadRefused) return json(error.status, { error: error.message, code: error.code } satisfies MediaRefusal);
 		if (error instanceof MuxRouteError) return json(error.status, { error: error.message } satisfies ApiError);
 		if (error instanceof WriteRefused) return json(error.status, { error: error.message, ...error.body });
+		if (isCloudRefusal(error)) {
+			// caracms-cloud M3: the cloud's own sentence, as sent (a full site, its storage away).
+			log(`[caracms] media bucket: CaraCMS Cloud (${error.error}): ${error.message}`);
+			return json(502, { error: error.message } satisfies ApiError);
+		}
 		if (error instanceof BucketError) {
 			log(`[caracms] media bucket: ${error.message}`);
 			const said = error.status !== null && error.status >= 400 && error.status < 500;

package/src/files-route.ts

@@ -32,6 +32,7 @@ import type { APIRoute } from 'astro';
 import { clientIp, NO_GATE_MESSAGE } from './live/auth/request.ts';
 import { fileAddress, fileKeyOf, fileTypeOf } from './files.ts';
 import { s3Bucket, type Bucket } from './editor/server/media/bucket.ts';
+import { cloudBucket } from './editor/server/media/cloud-bucket.ts';
 import { readImagesConfig } from './editor/server/media/config.ts';
 import { memoryMedia } from './editor/server/media/memory.ts';
 import { isProductionBuild } from './media.ts';
@@ -168,7 +169,7 @@ export async function handleFileRequest(request: Request, ctx: FileRouteContext
 	}
 
 	// 6. The one key the allow-list passed.
-	const bucket: Bucket = config.kind === 'memory' ? memoryMedia().bucket : s3Bucket(config.bucket, ctx.fetch);
+	const bucket: Bucket = config.kind === 'memory' ? memoryMedia().bucket : config.kind === 'cloud' ? cloudBucket(config.connection, ctx.fetch) : s3Bucket(config.bucket, ctx.fetch);
 	let object;
 	try {
 		object = await bucket.get(file.key);

package/src/index.ts

@@ -46,6 +46,7 @@
  * (Decision 5) and has Vite pre-bundle the editor's browser deps. The public pages
  * have no script, no React and no editor markers in either.
  */
+import { cloudSettingsForBuild } from './cloud-middleware.ts';
 import type { AstroIntegration } from 'astro';
 import { fontProviders } from 'astro/config';
 import { execFileSync } from 'node:child_process';
@@ -198,6 +199,8 @@ export const REDIRECT_MIDDLEWARE = 'redirect-middleware.ts';
 
 /** M4 Phase 2: the unconfigured server's 503, registered before Phase 3's guard. */
 export const EDITOR_MIDDLEWARE = 'editor/middleware.ts';
+/** caracms-cloud M3 Decision 20: a cloud site's settings, fetched by the first request (cloud-middleware.ts). */
+export const CLOUD_MIDDLEWARE = 'cloud-middleware.ts';
 
 /**
  * Content files out of Vite's watch (Decision 5): a write never reloads `/admin`
@@ -410,6 +413,8 @@ export default function caracms(config: SiteConfig): AstroIntegration {
 					if (address.url) injectRoute({ pattern: SITEMAP_ROUTE.pattern, entrypoint: new URL(`./${SITEMAP_ROUTE.entrypoint}`, import.meta.url), prerender: true });
 					// M4 Phase 3: the sign-in pages (live/auth/routes.ts).
 					for (const route of LOGIN_ROUTES) injectRoute({ pattern: route.pattern, entrypoint: new URL(`./${route.entrypoint}`, import.meta.url), prerender: false });
+					// caracms-cloud M3 Decision 20: a cloud site's settings, awaited before anything renders. First of all.
+					addMiddleware({ order: 'pre', entrypoint: new URL(`./${CLOUD_MIDDLEWARE}`, import.meta.url) });
 					// M4 Phase 2: an unconfigured production server's 503 on /admin and /_caracms/*. First, so it runs before the guard.
 					addMiddleware({ order: 'pre', entrypoint: new URL(`./${EDITOR_MIDDLEWARE}`, import.meta.url) });
 					// M4 Phase 3: the sign-in guard on /admin and /_caracms/ (live mode only). Must stay after the 503 middleware.
@@ -510,7 +515,11 @@ export default function caracms(config: SiteConfig): AstroIntegration {
 				server.httpServer?.once('close', stop);
 			},
 			// Posts and tags, Decision 15: a production build reads each document once (read.ts). Never in dev.
-			'astro:build:start': () => shareBuildReads(true),
+			// caracms-cloud M3 Decision 20: a cloud site's settings, fetched once before any page renders; a refusal fails the build.
+			'astro:build:start': async () => {
+				shareBuildReads(true);
+				await cloudSettingsForBuild();
+			},
 			'astro:build:done': () => {
 				shareBuildReads(false);
 				if (buildInfo && serverDir && existsSync(serverDir)) writeFileSync(new URL(BUILD_INFO_FILE, serverDir), `${JSON.stringify(buildInfo)}\n`);

package/src/live/README.md

@@ -19,7 +19,7 @@ live drafts store, sweep, locks and status route, and Phase 3's sign-in, sit on
 | `backend.ts` | `GitBackend`; `GitHubBackend`, `MemoryBackend` (test helpers: `seed`, `push`, `file`, `deployments`, `beforeRequest`); `StaleHeadError` |
 | `branches.ts` | `Branch` (a role: `main` or `drafts`), `BranchNames` (the refs behind them), `DEFAULT_BRANCHES`. `CARACMS_MAIN_BRANCH` and `CARACMS_DRAFTS_BRANCH` (read by `mode.ts`, M9 Decision 6) name the branch Publish commits to and the one autosaves land on; unset, `main` and `drafts`. They're set together or not at all: one alone is a problem, so the mode is unconfigured (`/admin` answers 503 saying both must be set; the public site still serves). Only the backends turn a role into a ref name, so with both set a branch called `main` is never read or moved. `MemoryBackend.refs` is keyed by name |
 | `github.ts` | The App's JWT, the installation token (one repo, refreshed early), `Tracker` (request counts). A third credential, `cloud`: the token from CaraCMS Cloud, refreshed the same way; its refusals are an access problem of kind `cloud` |
-| `cloud.ts` | CaraCMS Cloud (`CARACMS_CLOUD_KEY`; caracms-cloud M2): `DEFAULT_CLOUD_URL`, `cloudSettings()` (the repo, at start), `cloudToken()`, `CloudRefusal` (the cloud's `error`, `message`, `installUrl`), and `cloudUnavailable()`, the sign-in guard's 503 for a refusal at start |
+| `cloud.ts` | CaraCMS Cloud (`CARACMS_CLOUD_KEY`; caracms-cloud M2): `DEFAULT_CLOUD_URL`, `fetchCloudSettings()` (the repo and the media; M3), `loadCloudSettings()` / `heldCloudSettings()` (one fetch per process, shared by the media and the runtime), `cloudSettings()` (the repo, at start), `cloudCall()` (one call, for the cloud bucket too), `cloudToken()`, `CloudRefusal` (the cloud's `error`, `message`, `installUrl`), and `cloudUnavailable()`, the sign-in guard's 503 for a refusal at start |
 | `webhook.ts` | `handleGithubWebhook()`, behind `POST /_caracms/github` (`../editor/routes/github.ts`) |
 | `autosaves.ts` | Phase 2. Autosaves in Redis (`caracms:autosave:<file>`, a week; stored compare-and-set, ordered per tab by `X-Caracms-Seq`), the session's last commit (the merge's ancestor) and who last changed a document (Decision 11; no expiry, and `known: false` when neither Redis nor git can say). M5a: a new document's autosave carries `created: { over }` (its ancestor until committed), a deletion is a "gone" autosave (`text` and `document` null, `gone: { title }`) |
 | `locks.ts` | Phase 2. `Locks`: taken by the first write, heartbeat on the poll (Redis diet: only when `needsBeat`), lapse only once committed, releasing, Edit here; presence, each record holding for twice its tab's poll interval plus 3 s |

package/src/live/auth/middleware.ts

@@ -25,7 +25,7 @@
 import type { MiddlewareHandler } from 'astro';
 import { site } from 'virtual:caracms/config';
 import { editorMode } from '../../editor/server/mode.ts';
-import { CloudRefusal, cloudUnavailable } from '../cloud.ts';
+import { isCloudRefusal, cloudUnavailable } from '../cloud.ts';
 import { setPerson } from '../locals.ts';
 import { guard, isFormEndpoint, isGuardedPath } from './guard.ts';
 import { authFor } from './index.ts';
@@ -42,7 +42,7 @@ export const onRequest: MiddlewareHandler = async (context, next) => {
 	try {
 		auth = await authFor(site, mode.settings, context.site);
 	} catch (error) {
-		if (error instanceof CloudRefusal) {
+		if (isCloudRefusal(error)) {
 			console.error(`[caracms] sign-in: the live runtime could not start: CaraCMS Cloud (${error.error}): ${error.message}`);
 			return cloudUnavailable(error, context.url.pathname.startsWith('/_caracms/'));
 		}

package/src/live/cloud.ts

@@ -3,8 +3,14 @@
  *
  * - `CARACMS_CLOUD_KEY` (the site key, `cck_…`) is sent as `Authorization: Bearer` and
  *   nowhere else; `CARACMS_CLOUD_URL` overrides the production address below.
- * - `cloudSettings()`: `GET /v1/settings` at start, for the site's repo (`github.repo`;
- *   null is `no_repo`, with the cloud's own sentence).
+ * - `fetchCloudSettings()`: `GET /v1/settings`, the whole answer the package uses: the
+ *   site's repo, its folder and its media (bucket, image host, imgproxy pair; M3).
+ *   `loadCloudSettings()` is the one fetch per process (M3 Decision 20): the build's start,
+ *   or the first request a server gets, and the live runtime, all share it, held on
+ *   `globalThis` (the build renders pages through another module instance than its hooks);
+ *   `heldCloudSettings()` reads that copy synchronously (`readMediaConfig`).
+ * - `cloudSettings()`: the site's repo from those settings (`github.repo`; null is
+ *   `no_repo`, with the cloud's own sentence). Only the editor needs a repo.
  * - `cloudToken()`: `POST /v1/github/token`, a fresh installation token on the site's repo,
  *   about an hour long. `GitHubClient` calls it and refreshes five minutes early.
  * - **A refusal** (any answer that isn't 2xx, carrying `{ error, message }`) throws a
@@ -15,7 +21,7 @@
  * - `cloudUnavailable()`: the sign-in guard's 503 for a refusal at start (Decision 14),
  *   the sentence escaped and the install link a link.
  *
- * The key and the tokens are never logged and never put in an error.
+ * The key, the tokens and the imgproxy pair are never logged and never put in an error.
  */
 
 /** The production API's address (caracms-cloud M0 → Contracts). The one place it's written. */
@@ -25,6 +31,8 @@ export const DEFAULT_CLOUD_URL = 'https://glad-bird-412.ap-southeast-2.convex.si
 export const CLOUD_KEY_SHAPE = /^cck_[A-Za-z0-9_-]{43}$/;
 
 export const CLOUD_UNREACHABLE = "CaraCMS Cloud couldn't be reached, so the editor can't start. Try again in a minute.";
+/** M3 Decision 20: the build's own sentence for a cloud it can't reach. */
+export const CLOUD_UNREACHABLE_BUILD = "CaraCMS Cloud couldn't be reached, so the site can't be built. Try again in a minute.";
 /** The cloud's own `no_repo` sentence (Contracts), for `github.repo: null` in the settings. */
 export const CLOUD_NO_REPO = 'This site has no GitHub repo in CaraCMS Cloud yet. Ask CaraCMS to set one.';
 /** Decision 13: a token answer named another repo than the one the server started with. */
@@ -41,8 +49,23 @@ export interface CloudConnection {
 	timeoutMs?: number;
 }
 
+/**
+ * Marks a `CloudRefusal`. `Symbol.for` is shared across module instances, so a refusal
+ * thrown by a second copy of this file (Vite's dev SSR graph can hold two) is still known.
+ */
+const REFUSAL_BRAND = Symbol.for('caracms.CloudRefusal');
+
+/**
+ * Is this a `CloudRefusal`, from any instance of this module? Use this, never
+ * `instanceof CloudRefusal`: that fails when the refusal came from the other copy.
+ */
+export function isCloudRefusal(value: unknown): value is CloudRefusal {
+	return typeof value === 'object' && value !== null && (value as Record<symbol, unknown>)[REFUSAL_BRAND] === true;
+}
+
 /** The cloud said no (or couldn't be reached). `message` is safe to show and to log. */
 export class CloudRefusal extends Error {
+	readonly [REFUSAL_BRAND] = true;
 	/** The cloud's `error` (`no_repo`, `app_not_installed`, `unknown_key`…), or the package's `unreachable` / `repo_changed`. */
 	readonly error: string;
 	/** An `https://` link the message names (the App's install page), or null. */
@@ -57,45 +80,155 @@ export class CloudRefusal extends Error {
 
 const unreachable = () => new CloudRefusal('unreachable', CLOUD_UNREACHABLE);
 
-async function call(connection: CloudConnection, method: 'GET' | 'POST', path: string): Promise<Record<string, unknown>> {
+/**
+ * One call to the API: `path` with its query, a JSON `body` for a POST. The answer's JSON
+ * object, or a `CloudRefusal` (the cloud's own, or `unreachable`). The media bucket
+ * (editor/server/media/cloud-bucket.ts) calls it too.
+ */
+export async function cloudCall(connection: CloudConnection, method: 'GET' | 'POST', path: string, body?: unknown): Promise<Record<string, unknown>> {
 	let res: Response;
-	let body: unknown;
+	let answer: unknown;
 	try {
 		res = await (connection.fetch ?? fetch)(`${connection.url}${path}`, {
 			method,
-			headers: { authorization: `Bearer ${connection.key}`, accept: 'application/json', 'user-agent': 'caracms' },
+			headers: {
+				authorization: `Bearer ${connection.key}`,
+				accept: 'application/json',
+				'user-agent': 'caracms',
+				...(body === undefined ? {} : { 'content-type': 'application/json' }),
+			},
+			...(body === undefined ? {} : { body: JSON.stringify(body) }),
 			signal: AbortSignal.timeout(connection.timeoutMs ?? CLOUD_TIMEOUT_MS),
 		});
-		body = await res.json();
+		answer = await res.json();
 	} catch {
 		throw unreachable();
 	}
-	const answer = body && typeof body === 'object' && !Array.isArray(body) ? (body as Record<string, unknown>) : null;
-	if (!answer) throw unreachable();
+	const object = answer && typeof answer === 'object' && !Array.isArray(answer) ? (answer as Record<string, unknown>) : null;
+	if (!object) throw unreachable();
 	if (!res.ok) {
-		const { error, message, installUrl } = answer;
+		const { error, message, installUrl } = object;
 		if (typeof error !== 'string' || typeof message !== 'string' || !message.trim()) throw unreachable();
 		throw new CloudRefusal(error, message, typeof installUrl === 'string' && /^https:\/\//i.test(installUrl) ? installUrl : null);
 	}
-	return answer;
+	return object;
 }
 
 const REPO = /^([A-Za-z0-9-]+)\/([A-Za-z0-9._-]+)$/;
 
-/** The site's repo, from `GET /v1/settings`. */
-export async function cloudSettings(connection: CloudConnection): Promise<{ owner: string; repo: string }> {
-	const answer = await call(connection, 'GET', '/v1/settings');
+/** What the package uses of `GET /v1/settings` (caracms-cloud M1's shape; M3 adds nothing it needs). */
+export interface CloudSettings {
+	/** The linked repo, or null (`no_repo`, which only the editor minds: a build ignores it). */
+	repo: { owner: string; repo: string } | null;
+	/** The site's media, or null when the answer lacks any of it (the editor can still start; images can't be built). */
+	media: {
+		/** The site's folder in the media bucket, `sites/<folder>/`: the prefix the cloud adds to every key. */
+		folder: string;
+		bucket: string;
+		/** Bare, `img.caracms.cloud`. */
+		imageHost: string;
+		/** imgproxy's pair for this site, hex. Never logged, never sent to a browser. */
+		key: string;
+		salt: string;
+	} | null;
+}
+
+/** The package's sentence for settings with no usable media (a cloud set up without its bucket or image host). */
+export const CLOUD_NO_MEDIA = "CaraCMS Cloud's settings for this site have no media yet, so images can't be built. Ask CaraCMS to check the site.";
+
+const FOLDER = /^sites\/[a-z0-9][a-z0-9-]*\/$/;
+const HOST = /^[A-Za-z0-9.-]+(?::\d+)?$/;
+const HEX = /^(?:[0-9a-fA-F]{2})+$/;
+const str = (v: unknown) => (typeof v === 'string' && v ? v : null);
+
+/** `GET /v1/settings`, checked. No `github` or a malformed repo counts as unreachable; incomplete media is `media: null`. */
+export async function fetchCloudSettings(connection: CloudConnection): Promise<CloudSettings> {
+	const answer = await cloudCall(connection, 'GET', '/v1/settings');
 	const github = answer.github as { repo?: unknown } | undefined;
+	const media = answer.media as { bucket?: unknown; imageHost?: unknown } | undefined;
+	const pair = answer.imgproxy as { key?: unknown; salt?: unknown } | undefined;
 	if (!github || typeof github !== 'object') throw unreachable();
-	if (github.repo === null) throw new CloudRefusal('no_repo', CLOUD_NO_REPO);
 	const m = typeof github.repo === 'string' ? REPO.exec(github.repo) : null;
-	if (!m) throw unreachable();
-	return { owner: m[1]!, repo: m[2]! };
+	if (github.repo !== null && !m) throw unreachable();
+	const folder = str(answer.folder);
+	const bucket = str(media && typeof media === 'object' ? media.bucket : null);
+	const imageHost = str(media && typeof media === 'object' ? media.imageHost : null);
+	const key = str(pair && typeof pair === 'object' ? pair.key : null);
+	const salt = str(pair && typeof pair === 'object' ? pair.salt : null);
+	const ok = folder && FOLDER.test(folder) && bucket && imageHost && HOST.test(imageHost) && key && HEX.test(key) && salt && HEX.test(salt);
+	return { repo: m ? { owner: m[1]!, repo: m[2]! } : null, media: ok ? { folder, bucket, imageHost, key, salt } : null };
+}
+
+/** The site's repo (the editor's start): `no_repo` when none is linked. */
+export async function cloudSettings(connection: CloudConnection): Promise<{ owner: string; repo: string }> {
+	return repoOf(await fetchCloudSettings(connection));
+}
+
+export function repoOf(settings: CloudSettings): { owner: string; repo: string } {
+	if (!settings.repo) throw new CloudRefusal('no_repo', CLOUD_NO_REPO);
+	return settings.repo;
+}
+
+// ── The one fetch per process (M3 Decision 20) ─────────────────────────────────
+
+const HELD = Symbol.for('caracms.cloudSettings');
+interface Held {
+	key: string;
+	url: string;
+	pending: Promise<CloudSettings> | null;
+	value: CloudSettings | null;
+	/** The last fetch's refusal, while no fetch has succeeded: the media-unset sentence. */
+	failure: CloudRefusal | null;
+}
+const held = () => globalThis as { [HELD]?: Held };
+
+/**
+ * The settings, fetched once per process and shared: the build's start, a server's first
+ * request and the live runtime all come here, so there's one `GET /v1/settings`. A fetch
+ * that fails is forgotten (its refusal kept for `heldCloudSettings`), so the next caller
+ * tries again. Another key or address than the held one fetches afresh (tests).
+ */
+export function loadCloudSettings(connection: CloudConnection): Promise<CloudSettings> {
+	const g = held();
+	const h = g[HELD];
+	if (h && h.key === connection.key && h.url === connection.url) {
+		if (h.value) return Promise.resolve(h.value);
+		if (h.pending) return h.pending;
+	}
+	const next: Held = { key: connection.key, url: connection.url, pending: null, value: null, failure: h?.key === connection.key && h.url === connection.url ? h.failure : null };
+	next.pending = fetchCloudSettings(connection).then(
+		(value) => {
+			next.value = value;
+			next.failure = null;
+			next.pending = null;
+			return value;
+		},
+		(error: unknown) => {
+			next.pending = null;
+			next.failure = isCloudRefusal(error) ? error : unreachable();
+			throw next.failure;
+		},
+	);
+	g[HELD] = next;
+	return next.pending;
+}
+
+/** The held copy for this key and address: ready, the last fetch's refusal, or null (not fetched yet, or fetching). */
+export function heldCloudSettings(connection: Pick<CloudConnection, 'key' | 'url'>): { kind: 'ready'; settings: CloudSettings } | { kind: 'failed'; refusal: CloudRefusal } | null {
+	const h = held()[HELD];
+	if (!h || h.key !== connection.key || h.url !== connection.url) return null;
+	if (h.value) return { kind: 'ready', settings: h.value };
+	return h.failure ? { kind: 'failed', refusal: h.failure } : null;
+}
+
+/** Forget the held settings (tests). */
+export function resetCloudSettings(): void {
+	delete held()[HELD];
 }
 
 /** A fresh installation token on the site's repo, from `POST /v1/github/token`. */
 export async function cloudToken(connection: CloudConnection): Promise<{ token: string; expiresAt: number; repo: string }> {
-	const answer = await call(connection, 'POST', '/v1/github/token');
+	const answer = await cloudCall(connection, 'POST', '/v1/github/token');
 	const { token, expiresAt, repo } = answer;
 	const at = typeof expiresAt === 'string' ? Date.parse(expiresAt) : Number.NaN;
 	if (typeof token !== 'string' || !token || Number.isNaN(at) || typeof repo !== 'string') throw unreachable();

package/src/live/github.ts

@@ -31,7 +31,7 @@
  * The private key, the site key and the tokens are never logged.
  */
 import { createSign } from 'node:crypto';
-import { CLOUD_REPO_CHANGED, CloudRefusal, cloudToken } from './cloud.ts';
+import { CLOUD_REPO_CHANGED, CloudRefusal, isCloudRefusal, cloudToken } from './cloud.ts';
 
 const API = 'https://api.github.com';
 
@@ -341,7 +341,7 @@ export class GitHubClient {
 		try {
 			answer = await cloudToken({ ...cloud, fetch: this.fetcher, timeoutMs: this.timeoutMs });
 		} catch (error) {
-			if (error instanceof CloudRefusal && error.error !== 'unreachable') this.cloudProblem = { message: error.message, installUrl: error.installUrl };
+			if (isCloudRefusal(error) && error.error !== 'unreachable') this.cloudProblem = { message: error.message, installUrl: error.installUrl };
 			throw error;
 		}
 		if (answer.repo.toLowerCase() !== this.nameWithOwner.toLowerCase()) {