caracms 0.5.1 → 0.6.0

package/src/live/mode.ts

@@ -97,6 +97,10 @@ export const CLOUD_KEY_PROBLEM =
 	"CARACMS_CLOUD_KEY isn't a CaraCMS Cloud site key: a key is cck_ followed by 43 letters, digits, - and _. Copy it again from app.caracms.com.";
 export const CLOUD_AND_GITHUB_PROBLEM = (other: string) =>
 	`Both CARACMS_CLOUD_KEY and ${other} are set: a site uses one GitHub credential, so remove ${other}.`;
+/** The site's own media variables, which `CARACMS_CLOUD_KEY` replaces (caracms-cloud M3 Decision 19). */
+export const OWN_MEDIA_VARIABLES = ['S3_ENDPOINT', 'S3_REGION', 'S3_BUCKET', 'S3_ACCESS_KEY_ID', 'S3_SECRET_ACCESS_KEY', 'IMGPROXY_KEY', 'IMGPROXY_SALT', 'CARACMS_MEDIA_URL'] as const;
+const listed = (names: readonly string[]) => (names.length <= 1 ? names.join('') : `${names.slice(0, -1).join(', ')} and ${names[names.length - 1]}`);
+export const CLOUD_AND_MEDIA_PROBLEM = (names: readonly string[]) => `Set CARACMS_CLOUD_KEY or the site's own media variables, not both: remove ${listed(names)}.`;
 export const CLOUD_REPO_PROBLEM = 'CARACMS_CLOUD_KEY is set, so the repo comes from CaraCMS Cloud; remove GITHUB_REPO.';
 export const CLOUD_URL_PROBLEM = (url: string) =>
 	`CARACMS_CLOUD_URL must be the cloud's https:// address (http:// works for localhost only; got "${url}"). Leave it unset for CaraCMS Cloud itself.`;
@@ -187,6 +191,9 @@ export function readMode(env: Env = process.env, production = env.NODE_ENV === '
 		if (ghToken) problems.push(CLOUD_AND_GITHUB_PROBLEM('CARACMS_GITHUB_TOKEN'));
 		if (get('GITHUB_APP_ID')) problems.push(CLOUD_AND_GITHUB_PROBLEM('GITHUB_APP_ID'));
 		if (get('GITHUB_REPO')) problems.push(CLOUD_REPO_PROBLEM);
+		// M3 Decision 19: the key is the media credential too (unless the tests' in-memory media is on).
+		const ownMedia = OWN_MEDIA_VARIABLES.filter((name) => get(name));
+		if (ownMedia.length && get('CARACMS_MEDIA') !== 'memory') problems.push(CLOUD_AND_MEDIA_PROBLEM(ownMedia));
 		github = { kind: 'cloud', key: cloudKey, url: readCloudUrl(get('CARACMS_CLOUD_URL'), problems) };
 	} else if (!memory || production) {
 		const appId = get('GITHUB_APP_ID');
@@ -298,7 +305,7 @@ function isBranchName(name: string): boolean {
 }
 
 /** CARACMS_CLOUD_URL, without a trailing slash: https://, or http:// on localhost. Unset, the production address. */
-function readCloudUrl(raw: string | null, problems: string[]): string {
+export function readCloudUrl(raw: string | null, problems: string[]): string {
 	if (!raw) return DEFAULT_CLOUD_URL;
 	let url: URL | null = null;
 	try {

package/src/live/runtime.ts

@@ -20,7 +20,7 @@ import { join, relative, sep } from 'node:path';
 import { repoPrefix, type ResolvedSite } from '../config.ts';
 import { GitHubBackend, MemoryBackend, type FileWrite, type GitBackend } from './backend.ts';
 import { DEFAULT_BRANCHES } from './branches.ts';
-import { cloudSettings } from './cloud.ts';
+import { fetchCloudSettings, heldCloudSettings, loadCloudSettings, repoOf, type CloudConnection } from './cloud.ts';
 import { GitHubClient, Tracker } from './github.ts';
 import { LiveGit, SITE_SETTINGS_FILE } from './git.ts';
 import type { LiveSettings } from './mode.ts';
@@ -57,6 +57,19 @@ export interface RuntimeOptions {
 	fetch?: typeof fetch;
 }
 
+/**
+ * The repo for the editor's start. M3 Decision 20: the settings the process already holds (the
+ * first request fetched them for the media), so one GET /v1/settings, not two; a test's own fetch
+ * asks afresh. A held copy with no repo isn't reused: the repo may have been linked since, so
+ * this start asks again (one more GET, only while the repo is missing). The held copy is left
+ * as it is, so the media keep working off it.
+ */
+export async function cloudRepoForStart(connection: CloudConnection): Promise<{ owner: string; repo: string }> {
+	const held = heldCloudSettings(connection);
+	const stale = held?.kind === 'ready' && !held.settings.repo;
+	return repoOf(await (connection.fetch || stale ? fetchCloudSettings(connection) : loadCloudSettings(connection)));
+}
+
 /** Build and start a runtime (not shared: tests make their own). */
 export async function createLiveRuntime(options: RuntimeOptions): Promise<LiveRuntime> {
 	const { site, settings } = options;
@@ -80,7 +93,7 @@ export async function createLiveRuntime(options: RuntimeOptions): Promise<LiveRu
 			if (gh.kind === 'cloud') {
 				// caracms-cloud M2 Decision 13: the repo from the cloud's settings, then the first
 				// token, so a refusal of either stops the start (the sign-in guard shows its sentence).
-				const { owner, repo } = await cloudSettings({ key: gh.key, url: gh.url, fetch });
+				const { owner, repo } = await cloudRepoForStart({ key: gh.key, url: gh.url, fetch });
 				client = new GitHubClient({ cloudKey: gh.key, cloudUrl: gh.url, owner, repo, now, fetch }, tracker);
 				await client.ready();
 				log(`live mode on ${owner}/${repo} through CaraCMS Cloud`);

package/src/media.ts

@@ -22,9 +22,19 @@
  * `IMGPROXY_KEY` and `IMGPROXY_SALT` (hex, the values imgproxy has), `S3_BUCKET` (the
  * bucket in the `s3://` source). `CARACMS_MEDIA=memory` supplies `https://img.test`, a
  * fixed test key and salt and a test bucket, and is refused on a production server.
+ *
+ * **On CaraCMS Cloud** (caracms-cloud M3 Decisions 19–20) `CARACMS_CLOUD_KEY` replaces all
+ * of them: the origin (`https://<media.imageHost>`), the pair, the bucket and the site's
+ * folder come from the cloud's settings, fetched once per process (live/cloud.ts →
+ * `loadCloudSettings`, at the build's start and by a server's first request) and read here
+ * from that held copy. The folder goes before the key in the source,
+ * `s3://<bucket>/sites/<folder>/<key>`; content keeps `uploads/…`. The key with any of the
+ * site's own media variables is a problem sentence (one credential, not two).
  */
 import { createHmac } from 'node:crypto';
 import type { ImageFormat } from './fields.ts';
+import { CLOUD_NO_MEDIA, heldCloudSettings, type CloudConnection } from './live/cloud.ts';
+import { CLOUD_AND_MEDIA_PROBLEM, OWN_MEDIA_VARIABLES, readCloudUrl } from './live/mode.ts';
 import { renderMedia, type RenderImage } from './media-value.ts';
 
 /** The srcset width ladder every fluid image draws from (Decision 2). 1920 at the top: imgproxy doesn't upscale. */
@@ -52,6 +62,8 @@ export interface MediaSettings {
 	key: string;
 	salt: string;
 	bucket: string;
+	/** Before every key in the source: the site's folder on CaraCMS Cloud (`sites/<folder>/`), else none. */
+	prefix?: string;
 	memory: boolean;
 }
 
@@ -70,6 +82,40 @@ export function isProductionBuild(): boolean {
 type Env = Record<string, string | undefined>;
 const HEX = /^(?:[0-9a-fA-F]{2})+$/;
 
+export { CLOUD_AND_MEDIA_PROBLEM, OWN_MEDIA_VARIABLES };
+/** No settings held yet: nothing has fetched them in this process (the middleware and the build's start do). */
+export const CLOUD_MEDIA_NOT_FETCHED = "The site's media settings haven't come from CaraCMS Cloud yet.";
+/** A held fetch that couldn't reach the cloud, in the media's words (the cloud's own refusals are shown as sent). */
+export const CLOUD_MEDIA_UNREACHABLE = "CaraCMS Cloud couldn't be reached, so images can't be shown. Try again in a minute.";
+
+/**
+ * The cloud as the media credential: the connection when `CARACMS_CLOUD_KEY` is set and
+ * `CARACMS_MEDIA` isn't `memory` (which wins over everything), with any problems (the
+ * site's own media variables beside it, a bad `CARACMS_CLOUD_URL`). Null: not a cloud site's media.
+ */
+export function cloudMedia(env: Env = process.env): { connection: Pick<CloudConnection, 'key' | 'url'>; problems: string[] } | null {
+	const get = (name: string) => env[name]?.trim() || null;
+	const key = get('CARACMS_CLOUD_KEY');
+	if (!key || get('CARACMS_MEDIA') === 'memory') return null;
+	const problems: string[] = [];
+	const both = OWN_MEDIA_VARIABLES.filter((name) => get(name));
+	if (both.length) problems.push(CLOUD_AND_MEDIA_PROBLEM(both));
+	const url = readCloudUrl(get('CARACMS_CLOUD_URL'), problems);
+	return { connection: { key, url }, problems };
+}
+
+/** The media settings from the held cloud settings (or why there are none). */
+function cloudMediaConfig(cloud: NonNullable<ReturnType<typeof cloudMedia>>, problems: string[]): MediaConfig {
+	problems.push(...cloud.problems);
+	if (problems.length) return { kind: 'unset', missing: [], problems };
+	const held = heldCloudSettings(cloud.connection);
+	if (!held) return { kind: 'unset', missing: [], problems: [CLOUD_MEDIA_NOT_FETCHED] };
+	if (held.kind === 'failed') return { kind: 'unset', missing: [], problems: [held.refusal.error === 'unreachable' ? CLOUD_MEDIA_UNREACHABLE : held.refusal.message] };
+	const media = held.settings.media;
+	if (!media) return { kind: 'unset', missing: [], problems: [CLOUD_NO_MEDIA] };
+	return { kind: 'ready', settings: { origin: `https://${media.imageHost}`, key: media.key, salt: media.salt, bucket: media.bucket, prefix: media.folder, memory: false } };
+}
+
 /** The media variables (Decision 5). Read on each call (cheap), so tests can change them. */
 export function readMediaConfig(env: Env = process.env, production = isProductionBuild()): MediaConfig {
 	const get = (name: string) => {
@@ -83,6 +129,8 @@ export function readMediaConfig(env: Env = process.env, production = isProductio
 		return { kind: 'ready', settings: { ...MEMORY_MEDIA, memory: true } };
 	}
 	if (mode) problems.push(`CARACMS_MEDIA must be "memory" or unset (got "${mode}").`);
+	const cloud = cloudMedia(env);
+	if (cloud) return cloudMediaConfig(cloud, problems);
 	const missing: string[] = [];
 	const need = (name: string) => {
 		const v = get(name);
@@ -131,8 +179,8 @@ function side(value: number | undefined): number {
 	return Math.min(Math.round(value), IMAGE_MAX_DIMENSION);
 }
 
-/** A key as imgproxy's `plain` source takes it: each part percent-encoded, slashes kept. */
-const sourceOf = (settings: MediaSettings, key: string) => `s3://${settings.bucket}/${key.split('/').map(encodeURIComponent).join('/')}`;
+/** A key as imgproxy's `plain` source takes it, after the cloud folder when there is one: each part percent-encoded, slashes kept. */
+const sourceOf = (settings: MediaSettings, key: string) => `s3://${settings.bucket}/${`${settings.prefix ?? ''}${key}`.split('/').map(encodeURIComponent).join('/')}`;
 
 const signed = (settings: MediaSettings, path: string) => `${settings.origin}/${signPath(path, settings.key, settings.salt)}${path}`;