@kensio/yulin 1.21.2 → 1.21.4

package/dist/service/cloudformation/stack/update/sim-cfn-stack-update-lifecycle.d.ts

@@ -4,6 +4,14 @@ interface SimCfnStackUpdateLifecycleProperties {
     readonly background: BackgroundScheduler;
     readonly stackName: SimCloudFormationStackName;
 }
+/**
+ * The two halves of one Stack update: applying the new template, and putting
+ * the Stack back the way it was if that fails.
+ */
+export interface SimCfnStackUpdateWork {
+    readonly apply: () => Promise<void>;
+    readonly rollBack: () => Promise<void>;
+}
 /**
  * Owns the simulated CloudFormation Stack update lifecycle state.
  *
@@ -21,7 +29,9 @@ export declare class SimCfnStackUpdateLifecycle {
     private readonly background;
     private readonly stackName;
     private completePromise;
+    private rollbackPromise;
     private updateError;
+    private rollbackError;
     constructor(properties: SimCfnStackUpdateLifecycleProperties);
     /**
      * The current Stack update status, or undefined if the Stack has never been
@@ -30,14 +40,13 @@ export declare class SimCfnStackUpdateLifecycle {
     get status(): SimCloudFormationStackStatus | undefined;
     /**
      * The error captured during a background update, if any.
-     */
-    get error(): Error | undefined;
-    /**
-     * Refuse an update while one is already running.
      *
-     * CloudFormation takes one update at a time, and a second here would read
-     * the difference to apply from a Stack half way through the first.
+     * A rollback that failed answers with its own failure, because that is what
+     * the Stack is left in UPDATE_ROLLBACK_FAILED by and what has to be dealt
+     * with before the Stack works again.
      */
+    get error(): Error | undefined;
+    /** Refuse an update while one is already running, or being rolled back. */
     assertNotUpdating(): void;
     /**
      * Start the Stack update lifecycle.
@@ -46,17 +55,19 @@ export declare class SimCfnStackUpdateLifecycle {
      * and deletion do. The Resource work continues in the background, so callers
      * that need the final state should use waitForComplete().
      *
-     * An update that fails leaves the Stack in UPDATE_FAILED with the reason on
-     * it. Sim CloudFormation does not roll the Stack back to the template it was
-     * deployed from, so the Stack is left holding whatever the update managed.
+     * An update that fails is rolled back. The Stack moves to
+     * UPDATE_ROLLBACK_IN_PROGRESS with the reason on it, the rollback is
+     * scheduled as an operation of its own, and the Stack settles in
+     * UPDATE_ROLLBACK_COMPLETE, or in UPDATE_ROLLBACK_FAILED if the rollback
+     * could not finish either.
      */
-    update(runUpdate: () => Promise<void>): Promise<void>;
+    update(work: SimCfnStackUpdateWork): Promise<void>;
     /**
-     * Wait for the scheduled update to finish.
+     * Wait for the scheduled update to finish, rollback included.
      *
-     * If the update failed, this rethrows the captured error, so a caller can see
-     * what stopped the new template being applied. A Stack that was never updated
-     * has nothing to wait for.
+     * If the update failed, this rethrows the captured error once the Stack has
+     * settled, so a caller can see what stopped the new template being applied.
+     * A Stack that was never updated has nothing to wait for.
      */
     waitForComplete(): Promise<void>;
 }

package/dist/service/cloudformation/stack/update/sim-cfn-stack-update-lifecycle.js

@@ -1,5 +1,5 @@
-import { SimCloudFormationValidationError } from "../../error/sim-cloudformation.error.js";
 import { SimCfnStackOperationScheduler } from "../sim-cfn-stack-operation-scheduler.js";
+import { assertSimCfnStackNotUpdating } from "./sim-cfn-stack-update-guard.js";
 /**
  * Owns the simulated CloudFormation Stack update lifecycle state.
  *
@@ -17,7 +17,9 @@ export class SimCfnStackUpdateLifecycle {
     stackName;
     #status;
     completePromise;
+    rollbackPromise;
     updateError;
+    rollbackError;
     constructor(properties) {
         this.background = properties.background;
         this.stackName = properties.stackName;
@@ -31,20 +33,17 @@ export class SimCfnStackUpdateLifecycle {
     }
     /**
      * The error captured during a background update, if any.
+     *
+     * A rollback that failed answers with its own failure, because that is what
+     * the Stack is left in UPDATE_ROLLBACK_FAILED by and what has to be dealt
+     * with before the Stack works again.
      */
     get error() {
-        return this.updateError;
+        return this.rollbackError ?? this.updateError;
     }
-    /**
-     * Refuse an update while one is already running.
-     *
-     * CloudFormation takes one update at a time, and a second here would read
-     * the difference to apply from a Stack half way through the first.
-     */
+    /** Refuse an update while one is already running, or being rolled back. */
     assertNotUpdating() {
-        if (this.#status === "UPDATE_IN_PROGRESS") {
-            throw new SimCloudFormationValidationError(`Stack ${this.stackName} is in UPDATE_IN_PROGRESS state and can not be updated`);
-        }
+        assertSimCfnStackNotUpdating(this.stackName, this.#status);
     }
     /**
      * Start the Stack update lifecycle.
@@ -53,40 +52,58 @@ export class SimCfnStackUpdateLifecycle {
      * and deletion do. The Resource work continues in the background, so callers
      * that need the final state should use waitForComplete().
      *
-     * An update that fails leaves the Stack in UPDATE_FAILED with the reason on
-     * it. Sim CloudFormation does not roll the Stack back to the template it was
-     * deployed from, so the Stack is left holding whatever the update managed.
+     * An update that fails is rolled back. The Stack moves to
+     * UPDATE_ROLLBACK_IN_PROGRESS with the reason on it, the rollback is
+     * scheduled as an operation of its own, and the Stack settles in
+     * UPDATE_ROLLBACK_COMPLETE, or in UPDATE_ROLLBACK_FAILED if the rollback
+     * could not finish either.
      */
-    async update(runUpdate) {
+    async update(work) {
         this.#status = "UPDATE_IN_PROGRESS";
         this.updateError = undefined;
+        this.rollbackError = undefined;
+        this.rollbackPromise = undefined;
         const scheduler = new SimCfnStackOperationScheduler({
             background: this.background,
             failureMessage: "Sim CloudFormation Stack update failed",
         });
         await scheduler.sequence();
         this.completePromise = scheduler.schedule({
-            operation: runUpdate,
+            operation: work.apply,
             onSuccess: () => {
                 this.#status = "UPDATE_COMPLETE";
             },
             onFailure: (error) => {
-                this.#status = "UPDATE_FAILED";
+                this.#status = "UPDATE_ROLLBACK_IN_PROGRESS";
                 this.updateError = error;
+                // Scheduled rather than run where the failure was caught, so the Stack
+                // is visibly rolling back while it happens, the way it is visibly
+                // updating while the update happens.
+                this.rollbackPromise = scheduler.schedule({
+                    operation: work.rollBack,
+                    onSuccess: () => {
+                        this.#status = "UPDATE_ROLLBACK_COMPLETE";
+                    },
+                    onFailure: (failure) => {
+                        this.#status = "UPDATE_ROLLBACK_FAILED";
+                        this.rollbackError = failure;
+                    },
+                });
             },
         });
     }
     /**
-     * Wait for the scheduled update to finish.
+     * Wait for the scheduled update to finish, rollback included.
      *
-     * If the update failed, this rethrows the captured error, so a caller can see
-     * what stopped the new template being applied. A Stack that was never updated
-     * has nothing to wait for.
+     * If the update failed, this rethrows the captured error once the Stack has
+     * settled, so a caller can see what stopped the new template being applied.
+     * A Stack that was never updated has nothing to wait for.
      */
     async waitForComplete() {
-        if (this.completePromise !== undefined) {
-            await this.completePromise;
-        }
+        // Awaiting nothing is how a Stack that was never updated, and one that was
+        // never rolled back, wait for the operation they never had.
+        await this.completePromise;
+        await this.rollbackPromise;
         if (this.updateError !== undefined) {
             throw this.updateError;
         }

package/dist/service/cloudformation/stack/update/sim-cfn-stack-update-plan.d.ts

@@ -3,6 +3,10 @@ interface SimCfnStackUpdatePlanProperties {
     readonly current: ReadonlyMap<string, SimCfnResource>;
     readonly updated: ReadonlyMap<string, SimCfnResource>;
 }
+export interface SimCfnStackResourceReplacement {
+    readonly current: SimCfnResource;
+    readonly updated: SimCfnResource;
+}
 /**
  * What an update has to do to a Stack's Resources, worked out before any of it
  * happens.
@@ -17,6 +21,8 @@ interface SimCfnStackUpdatePlanProperties {
  * simCfnStackReplacedLogicalIds decides what changed.
  */
 export declare class SimCfnStackUpdatePlan {
+    /** The current and updated halves of each Resource replacement. */
+    readonly replacements: readonly SimCfnStackResourceReplacement[];
     /**
      * The deployed Resources to delete: the ones the new template drops, and the
      * deployed halves of the ones it replaces.
@@ -27,8 +33,17 @@ export declare class SimCfnStackUpdatePlan {
      * halves of the ones it replaces.
      */
     readonly creations: readonly SimCfnResource[];
-    private readonly updated;
+    readonly updated: ReadonlyMap<string, SimCfnResource>;
     constructor(properties: SimCfnStackUpdatePlanProperties);
+    /**
+     * For each logical ID the update is replacing, whether the definition taking
+     * its place says to keep the deployed Resource.
+     *
+     * The new half answers it because CloudFormation reads UpdateReplacePolicy
+     * off the template it is applying. An update that adds the attribute keeps
+     * the Resource it replaces, and one that drops it deletes that Resource.
+     */
+    replacementRetentions(): ReadonlyMap<string, boolean>;
     /**
      * Whether the update changes any Resource at all.
      *

package/dist/service/cloudformation/stack/update/sim-cfn-stack-update-plan.js

@@ -13,6 +13,8 @@ import { simCfnStackReplacedLogicalIds } from "./sim-cfn-stack-replaced-resource
  * simCfnStackReplacedLogicalIds decides what changed.
  */
 export class SimCfnStackUpdatePlan {
+    /** The current and updated halves of each Resource replacement. */
+    replacements;
     /**
      * The deployed Resources to delete: the ones the new template drops, and the
      * deployed halves of the ones it replaces.
@@ -28,6 +30,17 @@ export class SimCfnStackUpdatePlan {
         const { current, updated } = properties;
         const replaced = simCfnStackReplacedLogicalIds({ current, updated });
         this.updated = updated;
+        this.replacements = replaced
+            .values()
+            .map((logicalId) => {
+            const currentResource = current.get(logicalId);
+            const updatedResource = updated.get(logicalId);
+            if (currentResource === undefined || updatedResource === undefined) {
+                throw new Error(`CloudFormation replacement ${logicalId} is missing one of its Resource definitions`);
+            }
+            return { current: currentResource, updated: updatedResource };
+        })
+            .toArray();
         // Both lists are worked out now rather than on demand, because the Stack's
         // Resource map is the current one and applying the plan changes it.
         this.deletions = current
@@ -43,6 +56,20 @@ export class SimCfnStackUpdatePlan {
         })
             .toArray();
     }
+    /**
+     * For each logical ID the update is replacing, whether the definition taking
+     * its place says to keep the deployed Resource.
+     *
+     * The new half answers it because CloudFormation reads UpdateReplacePolicy
+     * off the template it is applying. An update that adds the attribute keeps
+     * the Resource it replaces, and one that drops it deletes that Resource.
+     */
+    replacementRetentions() {
+        return new Map(this.replacements.map(({ current, updated }) => [
+            current.logicalId,
+            updated.retainedOnReplace,
+        ]));
+    }
     /**
      * Whether the update changes any Resource at all.
      *

package/dist/service/cloudformation/stack/update/sim-cfn-stack-updater.js

@@ -2,6 +2,7 @@ import { SimCloudFormationValidationError } from "../../error/sim-cloudformation
 import { makeSimCfnStackResourceMap } from "../resource-map/sim-cfn-stack-resource-map.js";
 import { SimCfnStackUpdatePlan } from "./sim-cfn-stack-update-plan.js";
 import { simCfnStackTemplateChanged } from "./sim-cfn-stack-template-changes.js";
+import { SimCfnResourceRetention } from "../../resource/delete/sim-cfn-resource-retention.js";
 /**
  * What CloudFormation answers an update that would change nothing.
  *
@@ -57,8 +58,13 @@ export class SimCfnStackUpdater {
     async apply() {
         const { resources, operations } = this.properties;
         const { plan } = this;
-        await operations.delete(resources, plan.deletions);
+        await operations.assertUpdatesAllowed(resources, plan.updated, plan.replacements);
+        await operations.delete(resources, plan.deletions, new SimCfnResourceRetention({ replaced: plan.replacementRetentions() }));
         plan.applyTo(resources);
+        // Once the Stack has stopped holding them, and before the replacements are
+        // created. An update that keeps a Resource and then fails to create the one
+        // taking its place still reports what it kept.
+        operations.recordRetained(plan.deletions.filter((resource) => resource.retained));
         await operations.create(resources, plan.creations);
     }
 }

package/dist/service/cloudformation/template/condition/sim-cfn-condition-expression.d.ts

@@ -16,9 +16,9 @@ interface SimCfnConditionExpressionProperties {
  *
  * The tree is `Fn::Equals` at the leaves and `Fn::And`, `Fn::Or` and `Fn::Not`
  * above them, with `{ "Condition": "OtherCondition" }` handing off to the
- * Condition of that name. Where that other Condition comes from is the
- * evaluator's business, so it arrives as a reader rather than being looked up
- * here.
+ * Condition of that name. `Fn::If` picks one of two conditions by the answer to
+ * a third. Where a named Condition comes from is the evaluator's business, so it
+ * arrives as a reader rather than being looked up here.
  *
  * A function name this simulation has no behaviour for is refused rather than
  * read as false, which would deploy a Stack the template did not describe. The
@@ -39,6 +39,15 @@ export declare class SimCfnConditionExpression {
     evaluate(expression: SimCfnTemplateValue): boolean;
     private apply;
     private operands;
+    /**
+     * Evaluate whichever of an `Fn::If`'s two conditions its Condition selects.
+     *
+     * Only the selected one is evaluated, as CloudFormation resolves only the
+     * branch it takes. The name goes through the same reader a
+     * `{ "Condition": ... }` reference uses, so an `Fn::If` that closes a cycle
+     * is caught by the chain the evaluator carries rather than recursing.
+     */
+    private selected;
     private negated;
 }
 export {};

package/dist/service/cloudformation/template/condition/sim-cfn-condition-expression.js

@@ -5,9 +5,9 @@ import { SimCfnValueShape, } from "../value/sim-cfn-value-shape.js";
  *
  * The tree is `Fn::Equals` at the leaves and `Fn::And`, `Fn::Or` and `Fn::Not`
  * above them, with `{ "Condition": "OtherCondition" }` handing off to the
- * Condition of that name. Where that other Condition comes from is the
- * evaluator's business, so it arrives as a reader rather than being looked up
- * here.
+ * Condition of that name. `Fn::If` picks one of two conditions by the answer to
+ * a third. Where a named Condition comes from is the evaluator's business, so it
+ * arrives as a reader rather than being looked up here.
  *
  * A function name this simulation has no behaviour for is refused rather than
  * read as false, which would deploy a Stack the template did not describe. The
@@ -54,6 +54,9 @@ export class SimCfnConditionExpression {
         if (functionName === "Fn::Not") {
             return this.negated(value);
         }
+        if (functionName === "Fn::If") {
+            return this.selected(value);
+        }
         if (functionName === "Condition") {
             return this.named(this.shape.string(value, `${this.label} Condition reference`));
         }
@@ -67,6 +70,29 @@ export class SimCfnConditionExpression {
         }
         return listed.map((operand) => this.evaluate(operand));
     }
+    /**
+     * Evaluate whichever of an `Fn::If`'s two conditions its Condition selects.
+     *
+     * Only the selected one is evaluated, as CloudFormation resolves only the
+     * branch it takes. The name goes through the same reader a
+     * `{ "Condition": ... }` reference uses, so an `Fn::If` that closes a cycle
+     * is caught by the chain the evaluator carries rather than recursing.
+     */
+    selected(value) {
+        const listed = this.shape.list(value, `${this.label} Fn::If`);
+        if (listed.length !== 3) {
+            throw this.error(`${this.label} Fn::If must be a list of a Condition name and two ` +
+                "conditions");
+        }
+        const conditionName = listed[0];
+        const whenTrue = listed[1];
+        const whenFalse = listed[2];
+        assertDefined(conditionName, `${this.label} Fn::If Condition name`);
+        assertDefined(whenTrue, `${this.label} Fn::If condition if true`);
+        assertDefined(whenFalse, `${this.label} Fn::If condition if false`);
+        const selected = this.named(this.shape.string(conditionName, `${this.label} Fn::If Condition name`));
+        return this.evaluate(selected ? whenTrue : whenFalse);
+    }
     negated(value) {
         const listed = this.shape.list(value, `${this.label} Fn::Not`);
         if (listed.length !== 1) {

package/dist/service/cloudformation/template/condition/sim-cfn-output-conditions.d.ts

@@ -0,0 +1,28 @@
+import type { SimCfnTemplateValueRecord } from "../value/sim-cfn-template-value.js";
+import type { SimCfnConditions } from "./sim-cfn-conditions.js";
+interface SimCfnOutputConditionsProperties {
+    readonly conditions: SimCfnConditions;
+    readonly stackName?: string | undefined;
+}
+/**
+ * Applies the Output-level `Condition` attribute to a template's Outputs.
+ *
+ * An Output whose Condition is false is left out of the Stack altogether. It is
+ * never resolved, so it is absent from `stack.outputs` and from `DescribeStacks`,
+ * and the export name it carries is never published for another Stack to import.
+ *
+ * Naming a Condition the template does not define fails the deployment, the way
+ * it does on a Resource. An Output that quietly disappeared because its
+ * Condition was misspelled is worse than a Stack that refuses to deploy.
+ */
+export declare class SimCfnOutputConditions {
+    private readonly conditions;
+    private readonly stackName;
+    constructor(properties: SimCfnOutputConditionsProperties);
+    /**
+     * Whether the template asked for this Output but its Condition is false.
+     */
+    excludes(outputKey: string, outputTemplate: SimCfnTemplateValueRecord): boolean;
+    private error;
+}
+export {};

package/dist/service/cloudformation/template/condition/sim-cfn-output-conditions.js

@@ -0,0 +1,39 @@
+/**
+ * Applies the Output-level `Condition` attribute to a template's Outputs.
+ *
+ * An Output whose Condition is false is left out of the Stack altogether. It is
+ * never resolved, so it is absent from `stack.outputs` and from `DescribeStacks`,
+ * and the export name it carries is never published for another Stack to import.
+ *
+ * Naming a Condition the template does not define fails the deployment, the way
+ * it does on a Resource. An Output that quietly disappeared because its
+ * Condition was misspelled is worse than a Stack that refuses to deploy.
+ */
+export class SimCfnOutputConditions {
+    conditions;
+    stackName;
+    constructor(properties) {
+        this.conditions = properties.conditions;
+        this.stackName = properties.stackName;
+    }
+    /**
+     * Whether the template asked for this Output but its Condition is false.
+     */
+    excludes(outputKey, outputTemplate) {
+        const conditionName = outputTemplate["Condition"];
+        if (conditionName === undefined) {
+            return false;
+        }
+        if (typeof conditionName !== "string") {
+            throw this.error(`Output ${outputKey} Condition must be a string`);
+        }
+        if (!this.conditions.has(conditionName)) {
+            throw this.error(`Output ${outputKey} names Condition ${conditionName}, which the ` +
+                "template does not define");
+        }
+        return !this.conditions.value(conditionName);
+    }
+    error(detail) {
+        return new Error(`Sim CloudFormation Stack ${this.stackName ?? "unknown"} ${detail}`);
+    }
+}

package/dist/service/cloudformation/template/node/fn/find-in-map/sim-cfn-fn-find-in-map.d.ts

@@ -1,14 +1,26 @@
 import { SimCfnNode } from "../../sim-cfn-node.js";
 import type { SimCfnResolveContext } from "../../../resolve/sim-cfn-resolve-context.js";
 import type { SimCfnTemplateValue } from "../../../value/sim-cfn-template-value.js";
+interface SimCfnFnFindInMapProperties {
+    readonly mapName: SimCfnNode;
+    readonly topLevelKey: SimCfnNode;
+    readonly secondLevelKey: SimCfnNode;
+    readonly defaultValue?: SimCfnNode | undefined;
+}
 /**
  * Simulated CloudFormation `Fn::FindInMap` intrinsic function.
+ *
+ * The fourth argument a template can carry, `{ "DefaultValue": ... }`, answers
+ * a lookup the Mappings section has no value for. Without it a missing map or
+ * key fails the Resource, because a template that reads a key it never wrote is
+ * a mistake worth being told about.
  */
 export declare class SimCfnFnFindInMap extends SimCfnNode {
     private readonly mapName;
     private readonly topLevelKey;
     private readonly secondLevelKey;
-    constructor(mapName: SimCfnNode, topLevelKey: SimCfnNode, secondLevelKey: SimCfnNode);
+    private readonly defaultValue;
+    constructor(properties: SimCfnFnFindInMapProperties);
     /**
      * Resolve a value from the template Mappings section.
      */
@@ -17,6 +29,18 @@ export declare class SimCfnFnFindInMap extends SimCfnNode {
      * Collect referenced names from every key expression.
      */
     referencedNames(): string[];
+    /**
+     * The `DefaultValue` a lookup falls back to, or a failure naming the path.
+     */
+    private missing;
+    /**
+     * The expression left for a later pass, once a key can be a string.
+     *
+     * The `DefaultValue` goes back with it, so the lookup that eventually reads
+     * the Mappings still has the answer for a key that is not there.
+     */
+    private unresolved;
     private resolveKey;
     private isResolvedKey;
 }
+export {};

package/dist/service/cloudformation/template/node/fn/find-in-map/sim-cfn-fn-find-in-map.js

@@ -1,19 +1,25 @@
 import { SimCfnNode } from "../../sim-cfn-node.js";
 import { isRecord } from "../../../../../../util/type-guard/record.js";
-import { assertDefined } from "../../../../../../util/type-guard/defined.js";
 import { isSimCfnUnresolvedExpression } from "../../../value/sim-cfn-unresolved-expression.js";
 /**
  * Simulated CloudFormation `Fn::FindInMap` intrinsic function.
+ *
+ * The fourth argument a template can carry, `{ "DefaultValue": ... }`, answers
+ * a lookup the Mappings section has no value for. Without it a missing map or
+ * key fails the Resource, because a template that reads a key it never wrote is
+ * a mistake worth being told about.
  */
 export class SimCfnFnFindInMap extends SimCfnNode {
     mapName;
     topLevelKey;
     secondLevelKey;
-    constructor(mapName, topLevelKey, secondLevelKey) {
+    defaultValue;
+    constructor(properties) {
         super();
-        this.mapName = mapName;
-        this.topLevelKey = topLevelKey;
-        this.secondLevelKey = secondLevelKey;
+        this.mapName = properties.mapName;
+        this.topLevelKey = properties.topLevelKey;
+        this.secondLevelKey = properties.secondLevelKey;
+        this.defaultValue = properties.defaultValue;
     }
     /**
      * Resolve a value from the template Mappings section.
@@ -25,19 +31,18 @@ export class SimCfnFnFindInMap extends SimCfnNode {
         if (!this.isResolvedKey(mapName) ||
             !this.isResolvedKey(topLevelKey) ||
             !this.isResolvedKey(secondLevelKey)) {
-            return {
-                "Fn::FindInMap": [mapName, topLevelKey, secondLevelKey],
-            };
+            return this.unresolved([mapName, topLevelKey, secondLevelKey], context);
         }
         // oxlint-disable-next-line security/detect-object-injection
         const topLevel = context.mappings?.[mapName]?.[topLevelKey];
-        /* v8 ignore if -- defensive */
         if (!isRecord(topLevel)) {
-            throw new Error(`Sim CloudFormation Fn::FindInMap could not find map ${mapName}.${topLevelKey}`);
+            return this.missing(`${mapName}.${topLevelKey}`, context);
         }
         // oxlint-disable-next-line security/detect-object-injection
         const value = topLevel[secondLevelKey];
-        assertDefined(value, `Sim CloudFormation Fn::FindInMap could not find map ${mapName}.${topLevelKey}.${secondLevelKey}`);
+        if (value === undefined) {
+            return this.missing(`${mapName}.${topLevelKey}.${secondLevelKey}`, context);
+        }
         return value;
     }
     /**
@@ -49,8 +54,35 @@ export class SimCfnFnFindInMap extends SimCfnNode {
             ...this.mapName.referencedNames(),
             ...this.topLevelKey.referencedNames(),
             ...this.secondLevelKey.referencedNames(),
+            ...(this.defaultValue?.referencedNames() ?? []),
         ];
     }
+    /**
+     * The `DefaultValue` a lookup falls back to, or a failure naming the path.
+     */
+    missing(path, context) {
+        if (this.defaultValue !== undefined) {
+            return this.defaultValue.resolve(context);
+        }
+        throw new Error(`Sim CloudFormation Fn::FindInMap could not find map ${path}`);
+    }
+    /**
+     * The expression left for a later pass, once a key can be a string.
+     *
+     * The `DefaultValue` goes back with it, so the lookup that eventually reads
+     * the Mappings still has the answer for a key that is not there.
+     */
+    unresolved(keys, context) {
+        if (this.defaultValue === undefined) {
+            return { "Fn::FindInMap": [...keys] };
+        }
+        return {
+            "Fn::FindInMap": [
+                ...keys,
+                { DefaultValue: this.defaultValue.resolve(context) },
+            ],
+        };
+    }
     resolveKey(node, context) {
         const value = node.resolve(context);
         if (typeof value === "string") {

package/dist/service/cloudformation/template/parse/fn/find-in-map/sim-cfn-fn-find-in-map-parser.d.ts

@@ -9,6 +9,13 @@ export declare class SimCfnFnFindInMapParser {
     constructor(valueParser: SimCfnValueParser);
     /**
      * Parse and validate the value inside a Fn::FindInMap expression.
+     *
+     * The optional fourth argument is the `{ "DefaultValue": ... }` object
+     * CloudFormation answers a missing map or key with.
      */
     parse(value: SimCfnTemplateValue): SimCfnFunctionFindInMap;
+    /**
+     * Parse the fourth argument, which the template need not carry.
+     */
+    private defaultValue;
 }

package/dist/service/cloudformation/template/parse/fn/find-in-map/sim-cfn-fn-find-in-map-parser.js

@@ -1,5 +1,6 @@
 import { SimCfnFnFindInMap as SimCfnFunctionFindInMap } from "../../../node/fn/find-in-map/sim-cfn-fn-find-in-map.js";
 import { assertDefined } from "../../../../../../util/type-guard/defined.js";
+import { isRecord } from "../../../../../../util/type-guard/record.js";
 /**
  * Parses CloudFormation Fn::FindInMap values.
  */
@@ -10,10 +11,14 @@ export class SimCfnFnFindInMapParser {
     }
     /**
      * Parse and validate the value inside a Fn::FindInMap expression.
+     *
+     * The optional fourth argument is the `{ "DefaultValue": ... }` object
+     * CloudFormation answers a missing map or key with.
      */
     parse(value) {
-        if (!Array.isArray(value) || value.length !== 3) {
-            throw new Error("Sim CloudFormation Fn::FindInMap value must be [mapName, topLevelKey, secondLevelKey]");
+        if (!Array.isArray(value) || value.length < 3 || value.length > 4) {
+            throw new Error("Sim CloudFormation Fn::FindInMap value must be [mapName, " +
+                'topLevelKey, secondLevelKey] with an optional { "DefaultValue": ... }');
         }
         const mapName = value[0];
         const topLevelKey = value[1];
@@ -21,6 +26,27 @@ export class SimCfnFnFindInMapParser {
         assertDefined(mapName, "Fn::FindInMap map name");
         assertDefined(topLevelKey, "Fn::FindInMap top level key");
         assertDefined(secondLevelKey, "Fn::FindInMap second level key");
-        return new SimCfnFunctionFindInMap(this.valueParser.parse(mapName), this.valueParser.parse(topLevelKey), this.valueParser.parse(secondLevelKey));
+        return new SimCfnFunctionFindInMap({
+            mapName: this.valueParser.parse(mapName),
+            topLevelKey: this.valueParser.parse(topLevelKey),
+            secondLevelKey: this.valueParser.parse(secondLevelKey),
+            defaultValue: this.defaultValue(value[3]),
+        });
+    }
+    /**
+     * Parse the fourth argument, which the template need not carry.
+     */
+    defaultValue(value) {
+        if (value === undefined) {
+            return undefined;
+        }
+        if (!isRecord(value) ||
+            Object.keys(value).length !== 1 ||
+            !("DefaultValue" in value)) {
+            throw new Error('Sim CloudFormation Fn::FindInMap fourth value must be { "DefaultValue": ... }');
+        }
+        const defaultValue = value["DefaultValue"];
+        assertDefined(defaultValue, "Fn::FindInMap DefaultValue");
+        return this.valueParser.parse(defaultValue);
     }
 }