@fjall/components-infrastructure 22.0.0 → 24.0.0

package/dist/lib/patterns/aws/account.d.ts

@@ -55,6 +55,21 @@ export interface AccountProps extends StackProps {
      */
     machineTrustMode?: MachineTrustMode;
 }
+/**
+ * `fjall:description` values for the governance tiers — the same user-facing
+ * gold-plating the domain-side constructs carry, so a governance stack's
+ * resources explain themselves in the console exactly like a zone or
+ * certificate does. Keyed by `organisationType` so each tier self-describes
+ * from ONE stamp in this base class.
+ *
+ * CHARSET CONTRACT: every value must stay inside the AWS tag-value pattern
+ * `^[\p{L}\p{Z}\p{N}_.:/=+\-@]*$` — no commas. IAM roles and nested-stack
+ * resources (AWS::CloudFormation::Stack) validate tag values against it, so
+ * one comma aborts the whole governance deploy at changeset creation ("Tag
+ * [fjall:description] contained invalid characters"). Exported so the
+ * governanceTagging suite pins the contract for every tier.
+ */
+export declare const GOVERNANCE_TIER_DESCRIPTIONS: Record<OrganisationType, string>;
 export declare class Account extends Stack {
     readonly organisationType: OrganisationType;
     protected readonly resolvedRegion: string;

package/dist/lib/patterns/aws/account.js

@@ -22,9 +22,16 @@ import { InspectorEnablement } from "../../config/aws/inspectorEnablement.js";
  * resources explain themselves in the console exactly like a zone or
  * certificate does. Keyed by `organisationType` so each tier self-describes
  * from ONE stamp in this base class.
+ *
+ * CHARSET CONTRACT: every value must stay inside the AWS tag-value pattern
+ * `^[\p{L}\p{Z}\p{N}_.:/=+\-@]*$` — no commas. IAM roles and nested-stack
+ * resources (AWS::CloudFormation::Stack) validate tag values against it, so
+ * one comma aborts the whole governance deploy at changeset creation ("Tag
+ * [fjall:description] contained invalid characters"). Exported so the
+ * governanceTagging suite pins the contract for every tier.
  */
-const GOVERNANCE_TIER_DESCRIPTIONS = {
-    organisation: "Fjall-managed organisation governance: org root, member accounts and organisation-wide policy",
+export const GOVERNANCE_TIER_DESCRIPTIONS = {
+    organisation: "Fjall-managed organisation governance: org root and member accounts under organisation-wide policy",
     platform: "Fjall-managed platform governance: shared platform services and CI trust",
     account: "Fjall-managed account governance: account security and operations baseline"
 };
@@ -49,9 +56,17 @@ export class Account extends Stack {
         // so `this.organisationType` here would say "account" for every tier (the
         // same trap the connector-mode note below documents). By synth the field
         // is final and the tag renders the true tier.
+        //
+        // excludeResourceTypes is load-bearing: stack-level tags travel on the
+        // CloudFormation API call as literal strings, so a Lazy token there
+        // aborts every governance deploy at changeset creation ("Tag
+        // [fjall:description] contained invalid characters"). Resources render
+        // the resolved value in-template; only the stack's own tag set is
+        // skipped — CloudFormation would re-propagate a stack tag to those same
+        // resources anyway.
         Tags.of(this).add("fjall:description", Lazy.string({
             produce: () => GOVERNANCE_TIER_DESCRIPTIONS[this.organisationType]
-        }));
+        }), { excludeResourceTypes: ["aws:cdk:stack"] });
         this.resolvedRegion = region ?? this.region;
         const orgId = this.node.tryGetContext(CDK_CONTEXT_KEYS.ORG_ID);
         if (orgId) {

package/dist/lib/patterns/aws/cdn.d.ts

@@ -98,7 +98,8 @@ export interface S3CdnProps extends BaseCdnProps {
     originAccess?: "oai" | "oac";
     /** Object served for `/` (static sites: "index.html"). */
     defaultRootObject?: string;
-    /** "multipage" → clean-URL `.html` rewriting; "spa" → 403/404 fallback to index. */
+    /** "multipage" (/about → /about.html), "directory" (/about →
+     * /about/index.html) or "spa" (403/404 fall back to /index.html). */
     routing?: StaticSiteRouting;
     /** Security-headers policy (built by the caller, e.g. SecurityHeadersPolicy). */
     responseHeadersPolicy?: IResponseHeadersPolicy;
@@ -193,9 +194,6 @@ export interface SmartCdnBehaviour {
      */
     originRecord?: "alias" | "none";
 }
-/**
- * CDN wrapper class that extends CloudFrontDistribution with Fjall patterns.
- */
 export declare class Cdn extends CloudFrontDistribution implements ICdn {
     constructor(scope: Construct, id: string, props: ICdnProps);
     private static createEcsOriginResolver;

package/dist/lib/patterns/aws/cdn.js

@@ -208,6 +208,19 @@ function validateCdnProps(props) {
 /**
  * CDN wrapper class that extends CloudFrontDistribution with Fjall patterns.
  */
+/**
+ * What each routing mode asks of the distribution, total over the routing
+ * vocabulary — a mode added to `STATIC_SITE_ROUTING_VALUES` fails to compile
+ * here until it declares its CDN behaviour, instead of silently synthesising
+ * a distribution that ignores it. `multipage` and `directory` rewrite URIs in
+ * a viewer-request function; `spa` skips rewriting and relies on 403/404
+ * error responses falling back to `/index.html`.
+ */
+const ROUTING_CDN_BEHAVIOUR = {
+    multipage: { uriRewrite: "html" },
+    directory: { uriRewrite: "directory-index" },
+    spa: { spaFallback: true }
+};
 export class Cdn extends CloudFrontDistribution {
     constructor(scope, id, props) {
         validateCdnProps(props);
@@ -429,8 +442,8 @@ export class Cdn extends CloudFrontDistribution {
         const s3Routing = props.originType === "s3"
             ? {
                 defaultRootObject: props.defaultRootObject,
-                cleanUrls: props.routing === "multipage",
-                spaFallback: props.routing === "spa",
+                ...(props.routing !== undefined &&
+                    ROUTING_CDN_BEHAVIOUR[props.routing]),
                 responseHeadersPolicy: props.responseHeadersPolicy,
                 originRequestPolicy: props.originRequestPolicy
             }

package/dist/lib/patterns/aws/interfaces/pattern.d.ts

@@ -452,7 +452,10 @@ export interface IStaticSiteProps {
     source: string;
     /** Build command + output directory (single source of truth). */
     build: StaticSiteBuildConfig;
-    /** "multipage" (clean-URL `.html` rewriting) or "spa". Default: "multipage". */
+    /** "multipage" (/about → /about.html), "directory" (/about →
+     * /about/index.html — Astro's default layout) or "spa" (unknown paths fall
+     * back to /index.html). Match it to the build's emitted layout.
+     * Default: "multipage". */
     routing?: StaticSiteRouting;
     /** Security-header configuration. */
     security?: StaticSiteSecurityConfig;

package/dist/lib/patterns/aws/staticSite.d.ts

@@ -7,7 +7,7 @@
  *
  * Resources created:
  * - Private S3 bucket + BucketDeployment (asset upload)
- * - CloudFront distribution (OAC, clean-URL function, security-headers policy)
+ * - CloudFront distribution (OAC, routing-mode viewer function, security-headers policy)
  * - ACM certificate + Route53 alias record (when `domain` is set)
  * - Contact-form Lambda + Function URL (when `forms` is set)
  *

package/dist/lib/patterns/aws/staticSite.js

@@ -7,7 +7,7 @@
  *
  * Resources created:
  * - Private S3 bucket + BucketDeployment (asset upload)
- * - CloudFront distribution (OAC, clean-URL function, security-headers policy)
+ * - CloudFront distribution (OAC, routing-mode viewer function, security-headers policy)
  * - ACM certificate + Route53 alias record (when `domain` is set)
  * - Contact-form Lambda + Function URL (when `forms` is set)
  *
@@ -182,6 +182,11 @@ export class StaticSite extends Construct {
             bucket: this._bucket,
             originAccess: "oac",
             defaultRootObject: "index.html",
+            // The default VALUE stays "multipage" for configs that omit `routing`,
+            // but multipage's own semantics changed with the mode split: the old
+            // hybrid fragment served trailing-slash links from `…/index.html`. A
+            // deployed directory-layout site that relied on that must now state
+            // routing: "directory" — the default cannot protect it.
             routing: this.props.routing ?? "multipage",
             cachePolicy: "CACHING_OPTIMIZED",
             priceClass: "PriceClass_100",

package/dist/lib/resources/aws/cdn/cloudFront.d.ts

@@ -38,6 +38,8 @@ export interface AccessGateConfig {
     username: string;
     password: string;
 }
+/** See {@link CloudFrontDistributionProps.uriRewrite}. */
+export type UriRewriteMode = "html" | "directory-index";
 export interface CloudFrontDistributionProps {
     /**
      * App this CDN fronts. Keys the cross-stack export a `Domain` resolves via
@@ -67,9 +69,22 @@ export interface CloudFrontDistributionProps {
     accessGate?: false | AccessGateConfig;
     /** Object served for a bare `/` request (static sites: "index.html"). */
     defaultRootObject?: string;
-    /** Rewrites extensionless URLs to `.html`/`/index.html` via a CloudFront
-     * Function. Dynamic `/api/` paths are carved out so POSTs are not rewritten. */
-    cleanUrls?: boolean;
+    /**
+     * Rewrites pretty URLs onto the objects the build actually emitted, via a
+     * CloudFront Function. Each mode serves BOTH link shapes (`/about` and
+     * `/about/`) from its layout's object:
+     *
+     * - `"html"` → `/about.html`: builds that emit sibling `.html` files
+     *   (Astro `build.format: "file"`, Next.js default export).
+     * - `"directory-index"` → `/about/index.html`: builds that emit a
+     *   directory per page (Astro's default `build.format: "directory"`).
+     *
+     * Dynamic `/api/` paths are carved out so POSTs are not rewritten.
+     * Replaces the former `cleanUrls: boolean`, whose single fragment rewrote
+     * trailing-slash requests to `…/index.html` and bare requests to `….html`
+     * — a hybrid that served neither layout completely.
+     */
+    uriRewrite?: UriRewriteMode;
     /** SPA fallback: 403/404 → `/index.html` @200 for client-side routing. */
     spaFallback?: boolean;
     /** Security-headers policy applied to the default + every additional behaviour. */
@@ -98,14 +113,14 @@ export declare class CloudFrontDistribution extends Construct {
     constructor(scope: Construct, id: string, props: CloudFrontDistributionProps);
     /**
      * Build a composable CloudFront Function for VIEWER_REQUEST.
-     * Merges accessGate, forwardHostHeader and cleanUrls into a single function
-     * (CloudFront allows only one function per event type).
+     * Merges accessGate, forwardHostHeader and uriRewrite into a single
+     * function (CloudFront allows only one function per event type).
      *
      * ORDER IS LOAD-BEARING. The access gate is emitted first because it is the
      * only fragment that can reject a request, and a fragment that returns early
      * ahead of it would silently un-gate whatever paths it short-circuits. The
-     * cleanUrls fragment carves `/api/*` out of the `.html` rewriting — that
-     * carve-out must therefore be a guard around the rewrite, never an early
+     * uriRewrite fragments carve `/api/*` out of the rewriting — that carve-out
+     * must therefore be a guard around the rewrite, never an early
      * `return request`, or the whole `/api/*` surface leaves the gate behind it.
      */
     private buildViewerRequestFunction;

package/dist/lib/resources/aws/cdn/cloudFront.js

@@ -4,6 +4,43 @@ import { toPascalCase } from "../../../utils/capitaliseString.js";
 import { cdnDomainExportName } from "@fjall/util";
 import { Distribution, PriceClass, ViewerProtocolPolicy, CachePolicy, OriginRequestPolicy, AllowedMethods, OriginProtocolPolicy, Function as CloudFrontFunction, FunctionCode, FunctionRuntime, FunctionEventType, OriginAccessIdentity, S3OriginAccessControl } from "aws-cdk-lib/aws-cloudfront";
 import { S3BucketOrigin, LoadBalancerV2Origin, HttpOrigin } from "aws-cdk-lib/aws-cloudfront-origins";
+/**
+ * The viewer-request rewrite for each `UriRewriteMode`, keyed on the mode so
+ * a new mode fails to compile until it states its rewrite.
+ *
+ * Both fragments keep the `/api/*` carve-out as a GUARD around the rewrite,
+ * never an early `return request` — see the ordering contract on
+ * `buildViewerRequestFunction`: a fragment that returns early would let every
+ * path it short-circuits leave later fragments behind it.
+ *
+ * `"html"`: `/about` and `/about/` both → `/about.html`. The trailing slash
+ * is stripped before `.html` is appended — the build emitted a FILE, so the
+ * old hybrid's `/about/` → `/about/index.html` named an object that does not
+ * exist in this layout. The root `/` becomes `/index.html` (both layouts
+ * emit one), so neither mode depends on `defaultRootObject` being set.
+ *
+ * `"directory-index"`: `/about` and `/about/` both → `/about/index.html`,
+ * matching the directory-per-page layout (the root `/` likewise becomes
+ * `/index.html`).
+ *
+ * Requests whose last segment carries an extension (`/assets/app.css`) pass
+ * through untouched in both modes, and so does any path containing a
+ * dot-directory (`/.well-known/apple-app-site-association` must be served
+ * byte-for-byte — dot-paths are literal files, never pretty URLs).
+ */
+const URI_REWRITE_FRAGMENTS = {
+    html: " var uri = request.uri;" +
+        " if (!uri.startsWith('/api/') && uri.indexOf('/.') === -1) {" +
+        " if (uri === '/') { request.uri = '/index.html'; }" +
+        " else if (uri.endsWith('/')) { request.uri = uri.substring(0, uri.length - 1) + '.html'; }" +
+        " else { var seg = uri.substring(uri.lastIndexOf('/') + 1);" +
+        " if (seg.indexOf('.') === -1) { request.uri = uri + '.html'; } } }",
+    "directory-index": " var uri = request.uri;" +
+        " if (!uri.startsWith('/api/') && uri.indexOf('/.') === -1) {" +
+        " if (uri.endsWith('/')) { request.uri = uri + 'index.html'; }" +
+        " else { var seg = uri.substring(uri.lastIndexOf('/') + 1);" +
+        " if (seg.indexOf('.') === -1) { request.uri = uri + '/index.html'; } } }"
+};
 export class CloudFrontDistribution extends Construct {
     id;
     distribution;
@@ -20,8 +57,8 @@ export class CloudFrontDistribution extends Construct {
         const defaultOrigin = this.createOrigin(props.defaultOrigin);
         const defaultCachePolicy = this.resolveCachePolicy(props.defaultCachePolicy);
         // Build composable viewer request function (accessGate + forwardHostHeader
-        // + cleanUrls)
-        const viewerRequestFunction = this.buildViewerRequestFunction(id, props.forwardHostHeader, props.accessGate, props.cleanUrls);
+        // + uriRewrite)
+        const viewerRequestFunction = this.buildViewerRequestFunction(id, props.forwardHostHeader, props.accessGate, props.uriRewrite);
         const functionAssociations = viewerRequestFunction
             ? [
                 {
@@ -96,18 +133,18 @@ export class CloudFrontDistribution extends Construct {
     }
     /**
      * Build a composable CloudFront Function for VIEWER_REQUEST.
-     * Merges accessGate, forwardHostHeader and cleanUrls into a single function
-     * (CloudFront allows only one function per event type).
+     * Merges accessGate, forwardHostHeader and uriRewrite into a single
+     * function (CloudFront allows only one function per event type).
      *
      * ORDER IS LOAD-BEARING. The access gate is emitted first because it is the
      * only fragment that can reject a request, and a fragment that returns early
      * ahead of it would silently un-gate whatever paths it short-circuits. The
-     * cleanUrls fragment carves `/api/*` out of the `.html` rewriting — that
-     * carve-out must therefore be a guard around the rewrite, never an early
+     * uriRewrite fragments carve `/api/*` out of the rewriting — that carve-out
+     * must therefore be a guard around the rewrite, never an early
      * `return request`, or the whole `/api/*` surface leaves the gate behind it.
      */
-    buildViewerRequestFunction(id, forwardHostHeader, accessGate, cleanUrls) {
-        if (!accessGate && !forwardHostHeader && !cleanUrls) {
+    buildViewerRequestFunction(id, forwardHostHeader, accessGate, uriRewrite) {
+        if (!accessGate && !forwardHostHeader && uriRewrite === undefined) {
             return undefined;
         }
         const fragments = [];
@@ -125,12 +162,8 @@ export class CloudFrontDistribution extends Construct {
         if (forwardHostHeader) {
             fragments.push(" request.headers['x-forwarded-host'] = { value: request.headers.host.value };");
         }
-        if (cleanUrls) {
-            fragments.push(" var uri = request.uri;" +
-                " if (!uri.startsWith('/api/')) {" +
-                " if (uri.endsWith('/')) { request.uri = uri + 'index.html'; }" +
-                " else { var seg = uri.substring(uri.lastIndexOf('/') + 1);" +
-                " if (seg.indexOf('.') === -1) { request.uri = uri + '.html'; } } }");
+        if (uriRewrite !== undefined) {
+            fragments.push(URI_REWRITE_FRAGMENTS[uriRewrite]);
         }
         const functionBody = "function handler(event) { var request = event.request;" +
             fragments.join("") +

package/dist/lib/utils/validationLogger.js

@@ -6,17 +6,8 @@
 import { appendFileSync, existsSync, mkdirSync } from "fs";
 import { join } from "path";
 import { fjallLogDir } from "@fjall/util";
-import { FileRotator, LOG_ROTATION_DEFAULTS } from "@fjall/util/logRotation";
+import { FileRotator, resolveLogRotationBudget } from "@fjall/util/logRotation";
 const LOG_FILENAME = "infrastructure.jsonl";
-/**
- * Shared with the CLI's own logs, so this file cannot outgrow the budget
- * the rest of Fjall's logging keeps to. Without it this log had no bound of
- * any kind: it is appended to on every CDK synth, and one developer machine
- * reached 267MB of it inside a single release cycle.
- */
-const rotator = new FileRotator({
-    maxFiles: LOG_ROTATION_DEFAULTS.MAX_FILES
-});
 /**
  * Write a log entry to the infrastructure JSONL file
  */
@@ -36,7 +27,14 @@ function writeToLog(level, message) {
             source: "cdk-subprocess"
         });
         const logPath = join(logDir, LOG_FILENAME);
-        rotator.rotateIfNeeded(logPath, LOG_ROTATION_DEFAULTS.MAX_FILE_SIZE);
+        // Budget shared with the CLI's own logs — same defaults, same
+        // FJALL_LOG_MAX_SIZE / FJALL_LOG_MAX_FILES overrides — so this file
+        // cannot outgrow what the rest of Fjall's logging keeps to. It reached
+        // 267MB on one developer machine when it had no bound. Resolved per
+        // write for the same reason as the log dir above: CDK imports this
+        // module long before a command's environment is readable.
+        const { maxFileSize, maxFiles } = resolveLogRotationBudget();
+        new FileRotator({ maxFiles }).rotateIfNeeded(logPath, maxFileSize);
         appendFileSync(logPath, entry + "\n");
     }
     catch (err) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fjall/components-infrastructure",
-  "version": "22.0.0",
+  "version": "24.0.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/fjall-tech/fjall.git",
@@ -80,8 +80,8 @@
   },
   "dependencies": {
     "@aws-sdk/client-organizations": "^3.1098.0",
-    "@fjall/generator": "^22.0.0",
-    "@fjall/util": "^22.0.0",
+    "@fjall/generator": "^24.0.0",
+    "@fjall/util": "^24.0.0",
     "constructs": "^10.7.2"
   },
   "overrides": {