@anthusai/papyrus 1.0.0-next.47 → 1.0.0-next.48

package/amplify/functions/content-actions/handler.py

@@ -4,6 +4,7 @@ import json
 import os
 from typing import Any
 
+from papyrus_content.edge_invalidation import distribution_ids_from_environment, invalidate_revalidated_paths
 from papyrus_content.graphql_authoring import create_authoring_client
 from papyrus_content.markus_renderer.derive import derive_body
 from papyrus_content.projection.engine import project, project_item_pages
@@ -133,11 +134,18 @@ def project_item_action(client, item_id: str, *, unpublished: bool) -> dict:
         message = "; ".join(report.errors)
         schedule_projection_task(task, message)
         response["error"] = message
+    if report.unpurged:
+        response["edgePurged"] = False
+        schedule_unpurged_invalidation(report.unpurged)
     if report.follow_up_item_pages:
         schedule_projection_task({"task": "item-pages", "exceptItemId": item_id}, "follow-up")
     return response
 
 
+def schedule_unpurged_invalidation(keys: list[str]) -> None:
+    schedule_projection_task({"task": "invalidate", "keys": keys}, "edge invalidation failed")
+
+
 def run_projection_task(task: dict) -> dict:
     """An asynchronous projection task. Raising makes Lambda retry it, then send the event to the dead letter queue."""
     client, _claims = create_authoring_client()
@@ -147,8 +155,15 @@ def run_projection_task(task: dict) -> dict:
         report = project(projection_context(client), task["itemId"], unpublished=bool(task.get("unpublished")))
         if report.follow_up_item_pages:
             schedule_projection_task({"task": "item-pages", "exceptItemId": task["itemId"]}, "follow-up")
+    elif task.get("task") == "invalidate":
+        invalidate = projection_context(client).invalidate
+        if invalidate is None:
+            return {"ok": True, "paths": []}
+        return {"ok": True, "paths": invalidate(list(task["keys"]))}
     else:
         raise ProjectionTaskFailed(f"Unknown projection task {task.get('task')!r}")
+    if report.unpurged:
+        schedule_unpurged_invalidation(report.unpurged)
     if not report.ok:
         raise ProjectionTaskFailed("; ".join(report.errors))
     return {"ok": True, "paths": [*report.written, *report.deleted]}
@@ -193,6 +208,9 @@ def site_triggers_for(client, item_id: str) -> dict:
             slugs = [item["slug"]] if item.get("slug") else []
             revalidated = trigger_pretext_revalidation(slugs, None, base_url=revalidate_base_url)
             triggers["revalidated"] = revalidated if revalidated is not None else {"ok": False, "reason": "not-configured"}
+            distribution_ids = distribution_ids_from_environment(os.environ)
+            if distribution_ids and revalidated is not None:
+                triggers["edgeInvalidated"] = invalidate_revalidated_paths(distribution_ids, revalidated)
         except Exception as error:  # noqa: BLE001 - a trigger failure never fails the publish
             triggers["revalidated"] = {"ok": False, "error": f"{type(error).__name__}: {error}"}
     if reader_app_id:

package/amplify/functions/renditions/handler.py

@@ -11,7 +11,10 @@ from papyrus_content.renditions import (
     RenditionSettings,
     S3RenditionStore,
     make_renditions,
+    media_originals_enabled,
     meta_key,
+    original_site_key,
+    ORIGINAL_CACHE_CONTROL,
     settings_from_static_directory,
     source_from_media_key,
 )
@@ -26,6 +29,13 @@ def configured_settings() -> RenditionSettings | None:
     return _loaded["settings"]
 
 
+def originals_enabled() -> bool:
+    if "originals" not in _loaded:
+        static_directory = (os.environ.get(SITE_STATIC_DIRECTORY_ENV) or "").strip()
+        _loaded["originals"] = media_originals_enabled(Path(static_directory) if static_directory else None)
+    return _loaded["originals"]
+
+
 def site_store() -> S3RenditionStore:
     if "store" not in _loaded:
         _loaded["store"] = S3RenditionStore(os.environ[SITE_BUCKET_ENV])
@@ -50,18 +60,32 @@ def media_objects(event: dict) -> list[tuple[str, str]]:
 
 
 def render_media_object(
-    settings: RenditionSettings, bucket: str, key: str, *, skip_existing: bool = False, dry_run: bool = False
+    settings: RenditionSettings | None,
+    bucket: str,
+    key: str,
+    *,
+    originals: bool = False,
+    skip_existing: bool = False,
+    dry_run: bool = False,
 ) -> dict:
-    source = source_from_media_key(key)
-    if source is None:
+    source = source_from_media_key(key) if settings is not None else None
+    original_key = original_site_key(key) if originals else None
+    if source is None and original_key is None:
         return {"key": key, "action": "ignored", "reason": "not an image under media/"}
-    if skip_existing and site_store().get(meta_key(settings.pipeline, source)) is not None:
-        return {"key": key, "source": source, "action": "skipped-existing"}
+    if skip_existing:
+        renditions_exist = source is None or site_store().get(meta_key(settings.pipeline, source)) is not None
+        original_exists = original_key is None or site_store().get(original_key) is not None
+        if renditions_exist and original_exists:
+            return {"key": key, "source": source or original_key, "action": "skipped-existing"}
     if dry_run:
-        return {"key": key, "source": source, "action": "would-render"}
+        return {"key": key, "source": source or original_key, "action": "would-render" if source else "would-copy"}
     started = time.perf_counter()
     data = s3_client().get_object(Bucket=bucket, Key=key)["Body"].read()
     downloaded = time.perf_counter()
+    if original_key is not None:
+        site_store().put(original_key, data, cache_control=ORIGINAL_CACHE_CONTROL)
+    if source is None:
+        return {"key": key, "source": original_key, "action": "copied", "written": 1, "sourceBytes": len(data)}
     result = make_renditions(settings, site_store(), source, data)
     finished = time.perf_counter()
     return {
@@ -69,7 +93,7 @@ def render_media_object(
         "source": source,
         "action": "rendered",
         "kind": result["kind"],
-        "written": result["written"],
+        "written": result["written"] + (1 if original_key is not None else 0),
         "sourceBytes": len(data),
         "downloadMilliseconds": round((downloaded - started) * 1000),
         "renditionMilliseconds": round((finished - downloaded) * 1000),
@@ -78,13 +102,15 @@ def render_media_object(
 
 def handler(event, context):
     settings = configured_settings()
-    if settings is None:
-        return {"ok": True, "results": [], "skipped": "this site has no images settings in projection.json"}
+    originals = originals_enabled()
+    if settings is None and not originals:
+        return {"ok": True, "results": [], "skipped": "this site has no images or media settings in projection.json"}
     results = [
         render_media_object(
             settings,
             bucket,
             key,
+            originals=originals,
             skip_existing=event.get("skipExisting") is True,
             dry_run=event.get("dryRun") is True,
         )

package/amplify/publication/invalidation-alarm.js

@@ -0,0 +1,26 @@
+import { Duration } from "aws-cdk-lib";
+import * as cloudwatch from "aws-cdk-lib/aws-cloudwatch";
+export const FREE_INVALIDATION_PATHS_PER_MONTH = 1000;
+export const DAYS_PER_MONTH = 30.4;
+export const ALARM_WINDOW_DAYS = 7;
+export const INVALIDATION_METRIC_NAMESPACE = "Papyrus/Edge";
+export const INVALIDATION_METRIC_NAME = "InvalidatedPaths";
+/** CloudWatch cannot alarm across more than seven days, so the monthly free allowance is checked as its weekly pace. */
+export const WEEKLY_INVALIDATION_PATH_THRESHOLD = Math.round((FREE_INVALIDATION_PATHS_PER_MONTH * ALARM_WINDOW_DAYS) / DAYS_PER_MONTH);
+export function addInvalidationPathAlarm(scope, id, distributionId) {
+    const metric = new cloudwatch.Metric({
+        namespace: INVALIDATION_METRIC_NAMESPACE,
+        metricName: INVALIDATION_METRIC_NAME,
+        dimensionsMap: { DistributionId: distributionId },
+        statistic: "Sum",
+        period: Duration.days(ALARM_WINDOW_DAYS),
+    });
+    return new cloudwatch.Alarm(scope, id, {
+        metric,
+        evaluationPeriods: 1,
+        threshold: WEEKLY_INVALIDATION_PATH_THRESHOLD,
+        comparisonOperator: cloudwatch.ComparisonOperator.GREATER_THAN_OR_EQUAL_TO_THRESHOLD,
+        treatMissingData: cloudwatch.TreatMissingData.NOT_BREACHING,
+        alarmDescription: `CloudFront invalidation paths on ${distributionId} are on pace to pass the ${FREE_INVALIDATION_PATHS_PER_MONTH} free paths a month.`,
+    });
+}

package/amplify/publication/invalidation-alarm.ts

@@ -0,0 +1,30 @@
+import { Duration } from "aws-cdk-lib";
+import * as cloudwatch from "aws-cdk-lib/aws-cloudwatch";
+import type { Construct } from "constructs";
+
+export const FREE_INVALIDATION_PATHS_PER_MONTH = 1000;
+export const DAYS_PER_MONTH = 30.4;
+export const ALARM_WINDOW_DAYS = 7;
+export const INVALIDATION_METRIC_NAMESPACE = "Papyrus/Edge";
+export const INVALIDATION_METRIC_NAME = "InvalidatedPaths";
+
+/** CloudWatch cannot alarm across more than seven days, so the monthly free allowance is checked as its weekly pace. */
+export const WEEKLY_INVALIDATION_PATH_THRESHOLD = Math.round((FREE_INVALIDATION_PATHS_PER_MONTH * ALARM_WINDOW_DAYS) / DAYS_PER_MONTH);
+
+export function addInvalidationPathAlarm(scope: Construct, id: string, distributionId: string): cloudwatch.Alarm {
+  const metric = new cloudwatch.Metric({
+    namespace: INVALIDATION_METRIC_NAMESPACE,
+    metricName: INVALIDATION_METRIC_NAME,
+    dimensionsMap: { DistributionId: distributionId },
+    statistic: "Sum",
+    period: Duration.days(ALARM_WINDOW_DAYS),
+  });
+  return new cloudwatch.Alarm(scope, id, {
+    metric,
+    evaluationPeriods: 1,
+    threshold: WEEKLY_INVALIDATION_PATH_THRESHOLD,
+    comparisonOperator: cloudwatch.ComparisonOperator.GREATER_THAN_OR_EQUAL_TO_THRESHOLD,
+    treatMissingData: cloudwatch.TreatMissingData.NOT_BREACHING,
+    alarmDescription: `CloudFront invalidation paths on ${distributionId} are on pace to pass the ${FREE_INVALIDATION_PATHS_PER_MONTH} free paths a month.`,
+  });
+}

package/amplify/publication/renditions-settings.js

@@ -3,8 +3,9 @@
  * site (no CDK imports, so it can be tested without synthesizing).
  *
  * The function exists only for a site whose `projection.json` carries an
- * `images` section: that section is the one place the image pipeline settings
- * live, shared by the renditions function and the projector.
+ * `images` section (the one place the image pipeline settings live, shared by
+ * the renditions function and the projector) or `media.originals: true`
+ * (every media object is also published as is, at its key without `media/`).
  */
 import fs from "node:fs";
 import path from "node:path";
@@ -20,11 +21,18 @@ export function projectionSettingsHaveImages(settingsPath) {
     const parsed = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
     return typeof parsed.images === "object" && parsed.images !== null;
 }
+export function projectionSettingsPublishOriginals(settingsPath) {
+    if (!fs.existsSync(settingsPath))
+        return false;
+    const parsed = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
+    return parsed.media?.originals === true;
+}
 export function planRenditions(publication, workingDirectory) {
     if (publication?.staticDir === undefined)
         return { enabled: false, siteFiles: [] };
     const settingsFile = path.join(publication.staticDir, "projection.json");
-    if (!projectionSettingsHaveImages(path.resolve(workingDirectory, settingsFile)))
+    const resolved = path.resolve(workingDirectory, settingsFile);
+    if (!projectionSettingsHaveImages(resolved) && !projectionSettingsPublishOriginals(resolved))
         return { enabled: false, siteFiles: [] };
     return { enabled: true, siteFiles: [{ from: settingsFile, to: "site_static/projection.json" }] };
 }

package/amplify/publication/renditions-settings.ts

@@ -3,8 +3,9 @@
  * site (no CDK imports, so it can be tested without synthesizing).
  *
  * The function exists only for a site whose `projection.json` carries an
- * `images` section: that section is the one place the image pipeline settings
- * live, shared by the renditions function and the projector.
+ * `images` section (the one place the image pipeline settings live, shared by
+ * the renditions function and the projector) or `media.originals: true`
+ * (every media object is also published as is, at its key without `media/`).
  */
 import fs from "node:fs";
 import path from "node:path";
@@ -27,10 +28,17 @@ export function projectionSettingsHaveImages(settingsPath: string): boolean {
   return typeof parsed.images === "object" && parsed.images !== null;
 }
 
+export function projectionSettingsPublishOriginals(settingsPath: string): boolean {
+  if (!fs.existsSync(settingsPath)) return false;
+  const parsed = JSON.parse(fs.readFileSync(settingsPath, "utf8")) as { media?: { originals?: unknown } };
+  return parsed.media?.originals === true;
+}
+
 export function planRenditions(publication: { staticDir?: string } | undefined, workingDirectory: string): RenditionsPlan {
   if (publication?.staticDir === undefined) return { enabled: false, siteFiles: [] };
   const settingsFile = path.join(publication.staticDir, "projection.json");
-  if (!projectionSettingsHaveImages(path.resolve(workingDirectory, settingsFile))) return { enabled: false, siteFiles: [] };
+  const resolved = path.resolve(workingDirectory, settingsFile);
+  if (!projectionSettingsHaveImages(resolved) && !projectionSettingsPublishOriginals(resolved)) return { enabled: false, siteFiles: [] };
   return { enabled: true, siteFiles: [{ from: settingsFile, to: "site_static/projection.json" }] };
 }
 

package/amplify/publication/s3-projection-settings.js

@@ -14,6 +14,10 @@ export function s3ProjectionEnvironment(input) {
         environment.PAPYRUS_EDGE_DISTRIBUTION_ID = distributionId;
     environment.PAPYRUS_REDIRECTS_KVS_ARN = input.keyValueStoreArn;
     environment.PAPYRUS_PROJECTION_DLQ_URL = input.deadLetterQueueUrl;
+    if (input.cache?.htmlSMaxAgeSeconds !== undefined)
+        environment.PAPYRUS_HTML_S_MAXAGE_SECONDS = String(input.cache.htmlSMaxAgeSeconds);
+    if (input.cache?.invalidation === "off")
+        environment.PAPYRUS_EDGE_INVALIDATION = "off";
     if (input.publicHostName !== undefined)
         environment.PAPYRUS_SITE_PUBLIC_URL = `https://${input.publicHostName}`;
     if (input.projector !== undefined)
@@ -27,7 +31,7 @@ export function s3ProjectionPolicyStatements(input) {
         { actions: ["s3:PutObject", "s3:DeleteObject", "s3:GetObject"], resources: [`${input.bucketArn}/*`] },
         { actions: ["s3:ListBucket"], resources: [input.bucketArn] },
     ];
-    if (input.distributionArn !== undefined) {
+    if (input.distributionArn !== undefined && input.cache?.invalidation !== "off") {
         statements.push({ actions: ["cloudfront:CreateInvalidation"], resources: [input.distributionArn] });
     }
     statements.push({

package/amplify/publication/s3-projection-settings.ts

@@ -11,6 +11,7 @@ export type S3ProjectionSettingsInput = {
   distributionArn?: string;
   distributionId?: string;
   publicHostName?: string;
+  cache?: { htmlSMaxAgeSeconds?: number; invalidation?: "targeted" | "off" };
   projector?: string;
   staticDir?: string;
 };
@@ -37,6 +38,8 @@ export function s3ProjectionEnvironment(input: S3ProjectionSettingsInput): Recor
   if (distributionId !== undefined) environment.PAPYRUS_EDGE_DISTRIBUTION_ID = distributionId;
   environment.PAPYRUS_REDIRECTS_KVS_ARN = input.keyValueStoreArn;
   environment.PAPYRUS_PROJECTION_DLQ_URL = input.deadLetterQueueUrl;
+  if (input.cache?.htmlSMaxAgeSeconds !== undefined) environment.PAPYRUS_HTML_S_MAXAGE_SECONDS = String(input.cache.htmlSMaxAgeSeconds);
+  if (input.cache?.invalidation === "off") environment.PAPYRUS_EDGE_INVALIDATION = "off";
   if (input.publicHostName !== undefined) environment.PAPYRUS_SITE_PUBLIC_URL = `https://${input.publicHostName}`;
   if (input.projector !== undefined) environment.PAPYRUS_SITE_PROJECTOR = S3_PROJECTION_PROJECTOR_MODULE;
   if (input.staticDir !== undefined) environment.PAPYRUS_SITE_STATIC_DIR = S3_PROJECTION_STATIC_DIRECTORY;
@@ -48,7 +51,7 @@ export function s3ProjectionPolicyStatements(input: S3ProjectionSettingsInput):
     { actions: ["s3:PutObject", "s3:DeleteObject", "s3:GetObject"], resources: [`${input.bucketArn}/*`] },
     { actions: ["s3:ListBucket"], resources: [input.bucketArn] },
   ];
-  if (input.distributionArn !== undefined) {
+  if (input.distributionArn !== undefined && input.cache?.invalidation !== "off") {
     statements.push({ actions: ["cloudfront:CreateInvalidation"], resources: [input.distributionArn] });
   }
   statements.push(

package/amplify/publication/s3-projection.js

@@ -12,7 +12,8 @@ import { fileURLToPath } from "node:url";
 import { assertValidPublicationConfig } from "../site-backend-config.js";
 import { addRenditionsFunction } from "./renditions-function.js";
 import { RENDITIONS_FUNCTION_NAME_ENV } from "./renditions-settings.js";
-import { s3ProjectionEnvironment, s3ProjectionPolicyStatements } from "./s3-projection-settings.js";
+import { addInvalidationPathAlarm } from "./invalidation-alarm.js";
+import { distributionIdFromArn, s3ProjectionEnvironment, s3ProjectionPolicyStatements } from "./s3-projection-settings.js";
 const redirectFunctionSourcePath = resolve(dirname(fileURLToPath(import.meta.url)), "redirect-and-index.js");
 function createSiteBucket(scope, retainBucketOnDelete) {
     return new s3.Bucket(scope, "SiteBucket", {
@@ -107,9 +108,15 @@ export function addS3ProjectionPublication(scope, props, media) {
         publicHostName: distribution !== undefined
             ? (props.distribution?.aliases?.[0] ?? distribution.distributionDomainName)
             : undefined,
+        cache: props.cache,
         projector: props.projector,
         staticDir: props.staticDir,
     };
+    const invalidatedDistributionId = distribution?.distributionId
+        ?? (props.edgeDistributionArn !== undefined ? distributionIdFromArn(props.edgeDistributionArn) : undefined);
+    if (invalidatedDistributionId !== undefined && props.cache?.invalidation !== "off") {
+        addInvalidationPathAlarm(scope, "EdgeInvalidationPaths", invalidatedDistributionId);
+    }
     return {
         bucket,
         keyValueStore,

package/amplify/publication/s3-projection.ts

@@ -15,7 +15,8 @@ import { fileURLToPath } from "node:url";
 import { assertValidPublicationConfig, type PapyrusPublicationConfig } from "../site-backend-config";
 import { addRenditionsFunction, type RenditionsFunction } from "./renditions-function";
 import { RENDITIONS_FUNCTION_NAME_ENV, type RenditionsPlan } from "./renditions-settings";
-import { s3ProjectionEnvironment, s3ProjectionPolicyStatements } from "./s3-projection-settings";
+import { addInvalidationPathAlarm } from "./invalidation-alarm";
+import { distributionIdFromArn, s3ProjectionEnvironment, s3ProjectionPolicyStatements } from "./s3-projection-settings";
 
 const redirectFunctionSourcePath = resolve(dirname(fileURLToPath(import.meta.url)), "redirect-and-index.js");
 
@@ -154,9 +155,15 @@ export function addS3ProjectionPublication(
     publicHostName: distribution !== undefined
       ? (props.distribution?.aliases?.[0] ?? distribution.distributionDomainName)
       : undefined,
+    cache: props.cache,
     projector: props.projector,
     staticDir: props.staticDir,
   };
+  const invalidatedDistributionId = distribution?.distributionId
+    ?? (props.edgeDistributionArn !== undefined ? distributionIdFromArn(props.edgeDistributionArn) : undefined);
+  if (invalidatedDistributionId !== undefined && props.cache?.invalidation !== "off") {
+    addInvalidationPathAlarm(scope, "EdgeInvalidationPaths", invalidatedDistributionId);
+  }
   return {
     bucket,
     keyValueStore,

package/amplify/revalidate-invalidation-settings.js

@@ -0,0 +1,30 @@
+/**
+ * Environment and IAM for purging our CloudFront copies of the paths a Pretext reader revalidated.
+ * Pure (no CDK imports) so it can be tested without synthesizing.
+ */
+export const REVALIDATE_DISTRIBUTION_IDS_ENV = "PAPYRUS_REVALIDATE_DISTRIBUTION_IDS";
+const CLOUDFRONT_DISTRIBUTION_ID = /^E[A-Z0-9]{8,}$/;
+export function validateRevalidateDistributionIds(ids, revalidateBaseUrl) {
+    if (ids === undefined)
+        return [];
+    if (!Array.isArray(ids) || ids.length === 0)
+        return ["revalidateDistributionIds must be a non-empty array of CloudFront distribution ids"];
+    const problems = [];
+    for (const id of ids) {
+        if (typeof id !== "string" || !CLOUDFRONT_DISTRIBUTION_ID.test(id)) {
+            problems.push(`revalidateDistributionIds entry ${JSON.stringify(id)} is not a CloudFront distribution id`);
+        }
+    }
+    if ((revalidateBaseUrl ?? "").trim() === "")
+        problems.push("revalidateDistributionIds requires revalidateBaseUrl");
+    return problems;
+}
+export function revalidateDistributionEnvironment(ids) {
+    return { [REVALIDATE_DISTRIBUTION_IDS_ENV]: ids.join(",") };
+}
+export function revalidateInvalidationStatement(input) {
+    return {
+        actions: ["cloudfront:CreateInvalidation"],
+        resources: input.distributionIds.map((id) => `arn:${input.partition}:cloudfront::${input.account}:distribution/${id}`),
+    };
+}

package/amplify/revalidate-invalidation-settings.ts

@@ -0,0 +1,35 @@
+/**
+ * Environment and IAM for purging our CloudFront copies of the paths a Pretext reader revalidated.
+ * Pure (no CDK imports) so it can be tested without synthesizing.
+ */
+export const REVALIDATE_DISTRIBUTION_IDS_ENV = "PAPYRUS_REVALIDATE_DISTRIBUTION_IDS";
+
+const CLOUDFRONT_DISTRIBUTION_ID = /^E[A-Z0-9]{8,}$/;
+
+export function validateRevalidateDistributionIds(ids: unknown, revalidateBaseUrl: string | undefined): string[] {
+  if (ids === undefined) return [];
+  if (!Array.isArray(ids) || ids.length === 0) return ["revalidateDistributionIds must be a non-empty array of CloudFront distribution ids"];
+  const problems: string[] = [];
+  for (const id of ids) {
+    if (typeof id !== "string" || !CLOUDFRONT_DISTRIBUTION_ID.test(id)) {
+      problems.push(`revalidateDistributionIds entry ${JSON.stringify(id)} is not a CloudFront distribution id`);
+    }
+  }
+  if ((revalidateBaseUrl ?? "").trim() === "") problems.push("revalidateDistributionIds requires revalidateBaseUrl");
+  return problems;
+}
+
+export function revalidateDistributionEnvironment(ids: string[]): Record<string, string> {
+  return { [REVALIDATE_DISTRIBUTION_IDS_ENV]: ids.join(",") };
+}
+
+export function revalidateInvalidationStatement(input: {
+  partition: string;
+  account: string;
+  distributionIds: string[];
+}): { actions: string[]; resources: string[] } {
+  return {
+    actions: ["cloudfront:CreateInvalidation"],
+    resources: input.distributionIds.map((id) => `arn:${input.partition}:cloudfront::${input.account}:distribution/${id}`),
+  };
+}

package/amplify/site-backend-config.js

@@ -1,3 +1,4 @@
+export const MAXIMUM_HTML_S_MAXAGE_SECONDS = 86400;
 const CLOUDFRONT_DISTRIBUTION_ARN = /^arn:aws[a-z-]*:cloudfront::\d{12}:distribution\/[A-Z0-9]+$/;
 function isRelativePathWithoutParentSegments(value) {
     if (value === "" || value.startsWith("/") || value.includes("\\"))
@@ -26,6 +27,16 @@ export function validatePublicationConfig(publication) {
     if (config.edgeDistributionArn !== undefined && !CLOUDFRONT_DISTRIBUTION_ARN.test(config.edgeDistributionArn)) {
         problems.push("publication.edgeDistributionArn must be a CloudFront distribution ARN (arn:aws:cloudfront::<account>:distribution/<id>)");
     }
+    const cache = config.cache;
+    if (cache !== undefined) {
+        const lifetime = cache.htmlSMaxAgeSeconds;
+        if (lifetime !== undefined && (!Number.isInteger(lifetime) || lifetime < 0 || lifetime > MAXIMUM_HTML_S_MAXAGE_SECONDS)) {
+            problems.push(`publication.cache.htmlSMaxAgeSeconds must be an integer from 0 to ${MAXIMUM_HTML_S_MAXAGE_SECONDS}`);
+        }
+        if (cache.invalidation !== undefined && cache.invalidation !== "targeted" && cache.invalidation !== "off") {
+            problems.push('publication.cache.invalidation must be "targeted" or "off"');
+        }
+    }
     const distribution = config.distribution;
     if (distribution !== undefined) {
         if (config.edgeDistributionArn !== undefined && distribution.create === true) {

package/amplify/site-backend-config.ts

@@ -29,6 +29,15 @@ export type S3ProjectionDistributionConfig = {
   acm?: { hostedZoneId: string; hostedZoneName: string };
 };
 
+export type PapyrusPublicationCacheConfig = {
+  /** Shared-cache lifetime (seconds) of projected HTML. Default 300 with targeted invalidation, 60 with `invalidation: "off"`. */
+  htmlSMaxAgeSeconds?: number;
+  /** `targeted` (default): purge exactly the written paths after each projection. `off`: rely on the short lifetime alone. */
+  invalidation?: "targeted" | "off";
+};
+
+export const MAXIMUM_HTML_S_MAXAGE_SECONDS = 86400;
+
 export type PapyrusPublicationConfig = {
   kind: "s3-projection";
   /** Site repo path (relative, `.py`) of the SiteProjector bundled into content-actions as `site_projector`. */
@@ -37,6 +46,8 @@ export type PapyrusPublicationConfig = {
   staticDir?: string;
   /** Existing CloudFront distribution that reads the site bucket through OAC. */
   edgeDistributionArn?: string;
+  /** Edge cache lifetime of projected HTML and whether each projection purges the edge. */
+  cache?: PapyrusPublicationCacheConfig;
   /** Create the distribution (and optionally its certificate) in the site backend. Default: not created. */
   distribution?: S3ProjectionDistributionConfig;
   /** Default true: the site bucket is retained when the stack is deleted. `false` destroys it and its objects. */
@@ -72,6 +83,16 @@ export function validatePublicationConfig(publication: unknown): string[] {
   if (config.edgeDistributionArn !== undefined && !CLOUDFRONT_DISTRIBUTION_ARN.test(config.edgeDistributionArn)) {
     problems.push("publication.edgeDistributionArn must be a CloudFront distribution ARN (arn:aws:cloudfront::<account>:distribution/<id>)");
   }
+  const cache = config.cache;
+  if (cache !== undefined) {
+    const lifetime = cache.htmlSMaxAgeSeconds;
+    if (lifetime !== undefined && (!Number.isInteger(lifetime) || lifetime < 0 || lifetime > MAXIMUM_HTML_S_MAXAGE_SECONDS)) {
+      problems.push(`publication.cache.htmlSMaxAgeSeconds must be an integer from 0 to ${MAXIMUM_HTML_S_MAXAGE_SECONDS}`);
+    }
+    if (cache.invalidation !== undefined && cache.invalidation !== "targeted" && cache.invalidation !== "off") {
+      problems.push('publication.cache.invalidation must be "targeted" or "off"');
+    }
+  }
   const distribution = config.distribution;
   if (distribution !== undefined) {
     if (config.edgeDistributionArn !== undefined && distribution.create === true) {
@@ -119,6 +140,11 @@ export type PapyrusSiteBackendConfig = {
   stagingBuild?: { enabled: boolean };
   /** Base URL of a Pretext reader whose `/api/revalidate` a publish calls (authenticated by the SSM secret named in branch variable `PAPYRUS_REVALIDATE_SECRET_PARAMETER`). */
   revalidateBaseUrl?: string;
+  /**
+   * CloudFront distribution ids (same account) in front of that reader. After a publish refreshes the reader's
+   * cache, content-actions invalidates the revalidated paths on each of them. Needs `revalidateBaseUrl`.
+   */
+  revalidateDistributionIds?: string[];
   /**
    * SES receipt options for a site that is not the legacy p.apyr.us backend.
    * By default the site gets its own brand-named rule set that is never

package/amplify/site-backend.js

@@ -13,6 +13,8 @@ import { contentActionsPublicationWiring, planS3ProjectionBackend } from "./publ
 import { rebuildTriggerSettings } from "./rebuild-trigger-settings.js";
 import { assertValidPublicationConfig } from "./site-backend-config.js";
 import { revalidateSecretReadStatement } from "./revalidate-secret-policy.js";
+import { revalidateDistributionEnvironment, revalidateInvalidationStatement, validateRevalidateDistributionIds, } from "./revalidate-invalidation-settings.js";
+import { addInvalidationPathAlarm } from "./publication/invalidation-alarm.js";
 import { applyCognitoDomainPrefix, authConfigFromEnv, defineSiteAuth } from "./auth/resource.js";
 import { data } from "./data/resource.js";
 import { assignmentAction } from "./functions/assignment-action/resource.js";
@@ -343,6 +345,22 @@ export function defineSiteBackend(papyrusSite) {
             account: revalidateStack.account,
             parameterName: revalidateSecretParameter,
         })));
+        const distributionProblems = validateRevalidateDistributionIds(site.revalidateDistributionIds, site.revalidateBaseUrl);
+        if (distributionProblems.length > 0)
+            throw new Error(`Invalid backend config: ${distributionProblems.join("; ")}`);
+        const distributionIds = site.revalidateDistributionIds ?? [];
+        if (distributionIds.length > 0) {
+            for (const [name, value] of Object.entries(revalidateDistributionEnvironment(distributionIds))) {
+                backend.contentActions.addEnvironment(name, value);
+            }
+            contentActionsLambda.addToRolePolicy(new PolicyStatement(revalidateInvalidationStatement({ partition: revalidateStack.partition, account: revalidateStack.account, distributionIds })));
+            for (const id of distributionIds) {
+                addInvalidationPathAlarm(revalidateStack, `ReaderEdgeInvalidationPaths${id}`, id);
+            }
+        }
+    }
+    else if (site.revalidateDistributionIds !== undefined) {
+        throw new Error("Invalid backend config: revalidateDistributionIds requires revalidateBaseUrl");
     }
     grantNewsroomReadWriteDelete(backend.modelAttachmentUpload.resources.lambda);
     grantMediaReadWriteDelete(backend.modelAttachmentUpload.resources.lambda);

package/amplify/site-backend.ts

@@ -16,6 +16,12 @@ import { contentActionsPublicationWiring, planS3ProjectionBackend } from "./publ
 import { rebuildTriggerSettings } from "./rebuild-trigger-settings";
 import { assertValidPublicationConfig } from "./site-backend-config";
 import { revalidateSecretReadStatement } from "./revalidate-secret-policy";
+import {
+  revalidateDistributionEnvironment,
+  revalidateInvalidationStatement,
+  validateRevalidateDistributionIds,
+} from "./revalidate-invalidation-settings";
+import { addInvalidationPathAlarm } from "./publication/invalidation-alarm";
 import { applyCognitoDomainPrefix, authConfigFromEnv, defineSiteAuth } from "./auth/resource";
 import { data } from "./data/resource";
 import { assignmentAction } from "./functions/assignment-action/resource";
@@ -434,6 +440,24 @@ export function defineSiteBackend(papyrusSite: PapyrusSite) {
         }),
       ),
     );
+    const distributionProblems = validateRevalidateDistributionIds(site.revalidateDistributionIds, site.revalidateBaseUrl);
+    if (distributionProblems.length > 0) throw new Error(`Invalid backend config: ${distributionProblems.join("; ")}`);
+    const distributionIds = site.revalidateDistributionIds ?? [];
+    if (distributionIds.length > 0) {
+      for (const [name, value] of Object.entries(revalidateDistributionEnvironment(distributionIds))) {
+        backend.contentActions.addEnvironment(name, value);
+      }
+      contentActionsLambda.addToRolePolicy(
+        new PolicyStatement(
+          revalidateInvalidationStatement({ partition: revalidateStack.partition, account: revalidateStack.account, distributionIds }),
+        ),
+      );
+      for (const id of distributionIds) {
+        addInvalidationPathAlarm(revalidateStack, `ReaderEdgeInvalidationPaths${id}`, id);
+      }
+    }
+  } else if (site.revalidateDistributionIds !== undefined) {
+    throw new Error("Invalid backend config: revalidateDistributionIds requires revalidateBaseUrl");
   }
   grantNewsroomReadWriteDelete(backend.modelAttachmentUpload.resources.lambda as LambdaFunction);
   grantMediaReadWriteDelete(backend.modelAttachmentUpload.resources.lambda as LambdaFunction);

package/app/[year]/[month]/[day]/[articleSlug]/page.tsx

@@ -5,7 +5,7 @@ import { getEditionDatePath, parseEditionArticleRoute } from "../../../../../lib
 import { buildPresentationFooterEntries } from "../../../../../lib/presentation-footer";
 import { SITE_BRAND } from "../../../../../lib/site-brand";
 // Keep in sync with READER_REVALIDATE_SECONDS in lib/reader-route-config.ts
-export const revalidate = 3600;
+export const revalidate = 60;
 
 type DateScopedArticlePageProps = {
   params: Promise<{

package/app/[year]/[month]/[day]/page/[pageNumber]/page.tsx

@@ -3,7 +3,7 @@ import { EditionRoutePage } from "../../edition-route-page";
 import { parseEditionPageRoute } from "../../../../../../lib/edition-routes";
 import { getDefaultPretextLayout, getForcedPresentation } from "../../../../../../lib/site-brand";
 // Keep in sync with READER_REVALIDATE_SECONDS in lib/reader-route-config.ts
-export const revalidate = 3600;
+export const revalidate = 60;
 
 type EditionPageRouteProps = {
   params: Promise<{

package/app/[year]/[month]/[day]/page.tsx

@@ -2,7 +2,7 @@ import { EditionRoutePage } from "./edition-route-page";
 import { generateEditionDateStaticParams } from "../../../../lib/reader-static-params";
 
 // Keep in sync with READER_REVALIDATE_SECONDS in lib/reader-route-config.ts
-export const revalidate = 3600;
+export const revalidate = 60;
 
 export async function generateStaticParams() {
   return generateEditionDateStaticParams();

package/app/[year]/[month]/[day]/section/[sectionKey]/page.tsx

@@ -3,7 +3,7 @@ import { EditionRoutePage } from "../../edition-route-page";
 import { createSectionKey } from "../../../../../../lib/edition-sections";
 import { parseEditionSectionRoute } from "../../../../../../lib/edition-routes";
 // Keep in sync with READER_REVALIDATE_SECONDS in lib/reader-route-config.ts
-export const revalidate = 3600;
+export const revalidate = 60;
 
 type EditionSectionRouteProps = {
   params: Promise<{

package/app/api/archive/editions/route.ts

@@ -3,7 +3,7 @@ import { loadArchiveEditionPreviews, clampArchiveLimit } from "../../../../lib/a
 import { ARCHIVE_BATCH_SIZE } from "../../../../lib/archive-types";
 
 // Keep in sync with READER_REVALIDATE_SECONDS in lib/reader-route-config.ts
-export const revalidate = 3600;
+export const revalidate = 60;
 
 export async function GET(request: Request) {
   const url = new URL(request.url);

package/app/archive/page.tsx

@@ -4,7 +4,7 @@ import { loadArchiveEditionPreviews } from "../../lib/archive-data";
 import { ARCHIVE_BATCH_SIZE } from "../../lib/archive-types";
 
 // Keep in sync with READER_REVALIDATE_SECONDS in lib/reader-route-config.ts
-export const revalidate = 3600;
+export const revalidate = 60;
 
 export default async function ArchivePage() {
   const initialBatch = await loadArchiveEditionPreviews({ limit: ARCHIVE_BATCH_SIZE });

package/app/articles/[slug]/page.tsx

@@ -5,7 +5,7 @@ import { generateArticleStaticParams, siteServesNextReaderRoutes } from "../../.
 import { SITE_BRAND } from "../../../lib/site-brand";
 
 // Keep in sync with READER_REVALIDATE_SECONDS in lib/reader-route-config.ts
-export const revalidate = 3600;
+export const revalidate = 60;
 
 export async function generateStaticParams() {
   return generateArticleStaticParams();

package/lib/reader-cache-lifetime.ts

@@ -0,0 +1,5 @@
+/**
+ * Seconds a Pretext reader page may be served from a shared cache (Next sends `s-maxage` equal to its `revalidate`).
+ * Next needs a literal in each route's `export const revalidate`, so scripts/test-reader-cache-lifetime.ts keeps them equal to this.
+ */
+export const READER_PAGE_REVALIDATE_SECONDS = 60;

package/package.json

@@ -195,6 +195,7 @@
     "./lib/public-placeholder-config": "./lib/public-placeholder-config.ts",
     "./lib/publication-items": "./lib/publication-items.ts",
     "./lib/reader-base-path": "./lib/reader-base-path.ts",
+    "./lib/reader-cache-lifetime": "./lib/reader-cache-lifetime.ts",
     "./lib/reader-route-config": "./lib/reader-route-config.ts",
     "./lib/reader-static-params": "./lib/reader-static-params.ts",
     "./lib/reader-storage-url": "./lib/reader-storage-url.ts",
@@ -302,7 +303,7 @@
       "optional": true
     }
   },
-  "version": "1.0.0-next.47",
+  "version": "1.0.0-next.48",
   "dependencies": {
     "@aws-amplify/adapter-nextjs": "^1.7.3",
     "@aws-sdk/client-cognito-identity-provider": "3.1045.0",

package/routes.manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.0.0-next.47",
+  "version": "1.0.0-next.48",
   "routes": [
     {
       "file": "app/%5F_preview/[[...path]]/route.ts",
@@ -19,7 +19,7 @@
         "generateMetadata"
       ],
       "config": {
-        "revalidate": "3600"
+        "revalidate": "60"
       }
     },
     {
@@ -30,7 +30,7 @@
         "generateStaticParams"
       ],
       "config": {
-        "revalidate": "3600"
+        "revalidate": "60"
       }
     },
     {
@@ -39,7 +39,7 @@
       "hasDefault": true,
       "exports": [],
       "config": {
-        "revalidate": "3600"
+        "revalidate": "60"
       }
     },
     {
@@ -48,7 +48,7 @@
       "hasDefault": true,
       "exports": [],
       "config": {
-        "revalidate": "3600"
+        "revalidate": "60"
       }
     },
     {
@@ -58,7 +58,7 @@
         "GET"
       ],
       "config": {
-        "revalidate": "3600"
+        "revalidate": "60"
       }
     },
     {
@@ -87,7 +87,7 @@
       "hasDefault": true,
       "exports": [],
       "config": {
-        "revalidate": "3600"
+        "revalidate": "60"
       }
     },
     {
@@ -99,7 +99,7 @@
         "generateStaticParams"
       ],
       "config": {
-        "revalidate": "3600"
+        "revalidate": "60"
       }
     },
     {

package/src/with-papyrus.d.mts

@@ -1,2 +1,3 @@
 import type { NextConfig } from "next";
 export function withPapyrus(nextConfig?: NextConfig, options?: { root?: string }): NextConfig;
+export const READER_EXPIRE_TIME_SECONDS: number;

package/src/with-papyrus.mjs

@@ -23,6 +23,13 @@ const SERVER_EXTERNAL = [
   "@aws-amplify/data-schema",
 ];
 
+/**
+ * Next sends `stale-while-revalidate` = `expireTime` - `revalidate` (one year by default), so a shared cache may serve a
+ * page for a year past its `s-maxage` while it refreshes in the background. Twice the reader's 60 s page lifetime
+ * (lib/reader-cache-lifetime.ts) bounds that to 60 s.
+ */
+export const READER_EXPIRE_TIME_SECONDS = 120;
+
 export const DEFAULT_TRANSPILE_PACKAGES = ["@anthusai/papyrus", "cyclotron"];
 
 export function mergeTranspilePackages(existing = []) {
@@ -54,6 +61,7 @@ export function withPapyrus(nextConfig = {}, options = {}) {
   };
   return {
     distDir: process.env.NEXT_DIST_DIR || ".next",
+    expireTime: READER_EXPIRE_TIME_SECONDS,
     ...nextConfig,
     transpilePackages: mergeTranspilePackages(nextConfig.transpilePackages),
     serverExternalPackages: [...new Set([...(nextConfig.serverExternalPackages ?? []), ...SERVER_EXTERNAL])],