@redeemid/emdash 0.0.24 → 0.0.26

package/src/route-cache.ts

@@ -0,0 +1,134 @@
+/**
+ * Astro's route cache, made safe for gated content.
+ *
+ * The route cache keys pages by URL and serves a stored page without running
+ * any code, middleware included. So a page cached for one reader reaches the
+ * next one whoever they are: a visitor's copy (wall included) reaches a
+ * member, and a page cached while its entry was free keeps showing all of it
+ * after a rule locks it. Use these in page frontmatter instead of calling
+ * `Astro.cache.set()` yourself:
+ *
+ *   const { entry: post, cacheHint } = await getEmDashEntry("posts", slug);
+ *   await cacheEntry(Astro, "posts", post, cacheHint);
+ *
+ *   const { entries, cacheHint } = await getEmDashCollection("posts");
+ *   cachePage(Astro, cacheHint);
+ *
+ * cacheEntry caches the page only when it reads the same for everyone: no
+ * rule covers the entry, no open window is running out, and the body has no
+ * Members only part, single sale, Plan or Preferences block. Otherwise the
+ * page stays out of the route cache, even when a layout sets a hint later:
+ * redeemidGuard() opts it out again after the page renders.
+ *
+ * RedeemID's member-aware components (Content for a locked body, Gate, Plan,
+ * MemberCard, Preferences, YourData) call noRouteCache() themselves as a
+ * safety net, for pages that set hints by hand or sites with route rules.
+ *
+ * Both tag the page `redeemid`. Saving on the Access page or an entry's
+ * Access panel purges that tag, so cached pages follow the new rules.
+ *
+ * The cache still serves its copy to signed-in members (no code runs on a
+ * hit), so keep member-aware chrome on cached pages, such as the header's
+ * Account link, in the browser (window.redeemid) or out of cached pages.
+ */
+
+import { entryRequirement, entryRuleFor, type AstroLike, type Terms } from "./access.js";
+import { ITEM_BLOCK, MEMBERS_BLOCK, PLAN_BLOCK, PREFERENCES_BLOCK } from "./blocks-names.js";
+import { siteConfig } from "./site-config.js";
+
+/** The cache tag RedeemID puts on pages it lets into the route cache. */
+export const CACHE_TAG = "redeemid";
+
+/** Blocks whose output depends on who reads them. */
+export const MEMBER_BLOCKS: readonly string[] = [MEMBERS_BLOCK, ITEM_BLOCK, PLAN_BLOCK, PREFERENCES_BLOCK];
+
+type Hint = { tags?: string[]; maxAge?: number; swr?: number; lastModified?: Date; etag?: string };
+interface RouteCache {
+	enabled?: boolean;
+	set(options: Hint | false): void;
+}
+type CacheAstro = AstroLike & { cache?: RouteCache };
+
+const KEEP_OUT = Symbol.for("redeemid:keep-out-of-route-cache");
+
+/** Did page code ask to keep this request out of the route cache? (Read by redeemidGuard.) */
+export function keptOut(locals: unknown): boolean {
+	return Boolean(locals && typeof locals === "object" && (locals as Record<symbol, unknown>)[KEEP_OUT]);
+}
+
+/**
+ * Keep this page out of the route cache, whatever sets a hint later. Its
+ * Cache-Control stays as it was: a visitor's copy is the same for every
+ * visitor, and redeemidGuard() already makes signed-in pages private.
+ */
+export function noRouteCache(astro: CacheAstro): void {
+	if (astro.locals && typeof astro.locals === "object") (astro.locals as Record<symbol, unknown>)[KEEP_OUT] = true;
+	astro.cache?.set(false);
+}
+
+/** Cache a page that shows no gated body (a list, a page RedeemID doesn't touch), tagged so Access saves purge it. */
+export function cachePage(astro: CacheAstro, hint?: Hint | null): void {
+	if (keptOut(astro.locals) || !astro.cache?.enabled) return;
+	astro.cache.set({ ...(hint ?? {}), tags: [...(hint?.tags ?? []), CACHE_TAG] });
+}
+
+/** Does a body hold a block that reads differently for members? Looks at every field of the entry's data. */
+export function hasMemberBlocks(data: Record<string, unknown> | null | undefined): boolean {
+	for (const v of Object.values(data ?? {})) {
+		if (Array.isArray(v) && v.some((b) => MEMBER_BLOCKS.includes((b as { _type?: string })?._type ?? ""))) return true;
+	}
+	return false;
+}
+
+/**
+ * May this entry's page be stored and served to everyone? Only when it reads
+ * the same for every visitor, now and until the cache could expire.
+ */
+export async function cacheable(
+	astro: AstroLike,
+	collection: string,
+	entry: { id?: string; data?: Record<string, unknown> | null } | null | undefined,
+): Promise<boolean> {
+	if (!entry) return false;
+	const config = await siteConfig(astro.locals);
+	if (!config) return !hasMemberBlocks(entry.data);
+	if (config.unavailable) return false;
+	const terms = entry.data?.terms as Terms | undefined;
+	if ((await entryRequirement(config, collection, terms, entry.id)) !== null) return false;
+	// Free until a date: a stored copy would outlive the window.
+	const own = entryRuleFor(config, collection, entry.id);
+	if (own?.openUntil && Date.now() < Date.parse(own.openUntil)) return false;
+	return !hasMemberBlocks(entry.data);
+}
+
+/**
+ * Cache an entry's page with its hint when it reads the same for everyone;
+ * otherwise keep it out of the route cache. Returns whether it was cached.
+ */
+export async function cacheEntry(
+	astro: CacheAstro,
+	collection: string,
+	entry: { id?: string; data?: Record<string, unknown> | null } | null | undefined,
+	hint?: Hint | null,
+): Promise<boolean> {
+	if (keptOut(astro.locals)) return false;
+	if (!(await cacheable(astro, collection, entry))) {
+		noRouteCache(astro);
+		return false;
+	}
+	if (!astro.cache?.enabled) return false;
+	cachePage(astro, hint);
+	return true;
+}
+
+// ------------------------------------------------------------------ purging
+
+/** Purge RedeemID's cached pages. Never throws: the save it follows already happened. */
+export async function purgeRouteCache(cache: { enabled?: boolean; invalidate?(o: { tags: string[] }): Promise<unknown> } | undefined): Promise<void> {
+	if (!cache?.enabled || !cache.invalidate) return;
+	try {
+		await cache.invalidate({ tags: [CACHE_TAG] });
+	} catch (e) {
+		console.error("[redeemid] couldn't purge the route cache:", (e as Error).message);
+	}
+}

package/src/settings.ts

@@ -159,9 +159,18 @@ export function forgetAccess(): void {
 	held()[HELD] = undefined;
 }
 
+const WRITES = Symbol.for("redeemid:access-writes");
+
+/** How many times this server has saved access settings. redeemidGuard() purges the route cache when a request moves it. */
+export function accessWrites(): number {
+	return (globalThis as unknown as Record<symbol, number | undefined>)[WRITES] ?? 0;
+}
+
 /** Record that the settings changed, so every server reads them again. */
 export async function touchAccess(store: StorageCollection<AccessRecord>): Promise<void> {
 	forgetAccess();
+	const g = globalThis as unknown as Record<symbol, number | undefined>;
+	g[WRITES] = (g[WRITES] ?? 0) + 1;
 	await store.put(STAMP_ID, { kind: "stamp", version: crypto.randomUUID() });
 }
 

package/src/template-scan.ts

@@ -4,6 +4,10 @@
  * every rule, Paywall break and Members only part, so a gated collection
  * rendered that way reaches every visitor in full.
  *
+ * Also templates that call `Astro.cache.set()` themselves on a gated
+ * collection's pages instead of cacheEntry()/cachePage() (route-cache.ts):
+ * the route cache then serves one reader's copy to everyone.
+ *
  * redeemidGuard() scans the site's src/ at build time (scanTemplate, in
  * Node) and hands the findings to the running site; the Status page then
  * compares them with the rules as they are now (gatedFindings), because
@@ -17,8 +21,10 @@ import type { RedeemIDConfig } from "./config.js";
 export interface TemplateFinding {
 	/** Path from the site's root, e.g. src/pages/[slug].astro. */
 	file: string;
-	/** Lines with a <PortableText> tag. */
+	/** Lines with a <PortableText> tag (from emdash/ui). */
 	lines: number[];
+	/** Lines that call Astro.cache.set() directly; absent when there are none. */
+	cache?: number[];
 	/** Collections the file loads with getEmDashEntry or getEmDashCollection. */
 	collections: string[];
 }
@@ -26,16 +32,20 @@ export interface TemplateFinding {
 const FROM_EMDASH_UI = /import\s*\{[^}]*\bPortableText\b[^}]*\}\s*from\s*["']emdash\/ui["']/;
 const LOADS = /getEmDash(?:Entry|Collection)\(\s*["'`]([\w-]+)["'`]/g;
 
-/** One template's finding, or null when it doesn't render <PortableText> from emdash/ui. */
+const CACHE_SET = /\bAstro\.cache\??\.set\(/;
+
+/** One template's finding, or null when it neither renders <PortableText> from emdash/ui nor sets a cache hint. */
 export function scanTemplate(file: string, source: string): TemplateFinding | null {
-	if (!FROM_EMDASH_UI.test(source)) return null;
+	const fromUi = FROM_EMDASH_UI.test(source);
 	const lines: number[] = [];
+	const cache: number[] = [];
 	source.split("\n").forEach((line, i) => {
-		if (/<PortableText[\s/>]/.test(line)) lines.push(i + 1);
+		if (fromUi && /<PortableText[\s/>]/.test(line)) lines.push(i + 1);
+		if (CACHE_SET.test(line)) cache.push(i + 1);
 	});
-	if (!lines.length) return null;
+	if (!lines.length && !cache.length) return null;
 	const collections = [...new Set([...source.matchAll(LOADS)].map((m) => m[1]!))].sort();
-	return { file, lines, collections };
+	return cache.length ? { file, lines, cache, collections } : { file, lines, collections };
 }
 
 /** Collections some rule or entry rule can lock: "*" when the site default does. */
@@ -61,12 +71,29 @@ export function gatedFindings(findings: TemplateFinding[], config: RedeemIDConfi
 	if (!gated.size) return [];
 	const all = gated.has("*");
 	return findings.flatMap((f) => {
+		if (!f.lines.length) return [];
 		if (!f.collections.length) return [{ ...f, gated: [] }];
 		const hit = f.collections.filter((c) => all || gated.has(c));
 		return hit.length ? [{ ...f, gated: hit }] : [];
 	});
 }
 
+/**
+ * Templates that set a route cache hint themselves on pages that load a
+ * gated collection. Files whose collection we can't see (layouts, which set
+ * hints for menus and settings) aren't listed: cacheEntry() on the page keeps
+ * those out anyway.
+ */
+export function cacheFindings(findings: TemplateFinding[], config: RedeemIDConfig): GatedFinding[] {
+	const gated = gatedCollections(config);
+	if (!gated.size) return [];
+	const all = gated.has("*");
+	return findings.flatMap((f) => {
+		const hit = f.collections.filter((c) => all || gated.has(c));
+		return f.cache?.length && hit.length ? [{ ...f, gated: hit }] : [];
+	});
+}
+
 /** Where the running site keeps the scan; unset when redeemidGuard() isn't installed. */
 export const TEMPLATES_KEY = "__redeemidTemplates";
 

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = "0.0.24";
+export const VERSION = "0.0.26";