@kensio/yulin 1.21.3 → 1.21.5

package/docs/services/cloudformation/README.md

@@ -132,6 +132,66 @@ console.log(describeOutput.Stacks?.[0]?.StackStatus);
 continues asynchronously, similar to real CloudFormation. Use `waitForStackDeployComplete(...)` when
 you need final stack state.
 
+## Stack IDs
+
+A stack is given a stack ID when it is created, in the ARN shape CloudFormation gives one:
+
+```
+arn:aws:cloudformation:<region>:<account>:stack/<name>/<uuid>
+```
+
+The account and region are the ones the stack was created in. The UUID on the end is generated for
+each stack. Deploying the same name a second time produces a stack with an ID of its own.
+
+`CreateStackCommand` and `UpdateStackCommand` answer with the ID, `DescribeStacksCommand` reports it
+as `StackId`, and a template reading `AWS::StackId` resolves to it. `AWS::StackName` still resolves
+to the name. A `CREATE` change set makes the ID along with the stack it puts into review, and the
+change set commands report it as `StackId` too.
+
+`DescribeStacksCommand` accepts either a stack name or a stack ID in `StackName`, as CloudFormation
+does. A stack ID goes on working once the stack has been deleted (its name does not).
+
+```typescript sim-cloudformation-stack-id
+/**
+ * Describing a deleted simulated CloudFormation Stack by its Stack ID.
+ */
+
+import {
+  CreateStackCommand,
+  DeleteStackCommand,
+  DescribeStacksCommand,
+} from "@aws-sdk/client-cloudformation";
+
+import { SimAws } from "@kensio/yulin";
+
+const simAws = new SimAws();
+const simCfn = simAws.cloudFormation();
+
+const created = await simCfn.createStack(
+  new CreateStackCommand({
+    StackName: "identified-stack",
+    TemplateBody: JSON.stringify({ Resources: {} }),
+  }),
+);
+
+// arn:aws:cloudformation:<region>:<account>:stack/identified-stack/<uuid>
+console.log(created.StackId);
+
+await simCfn.waitForStackDeployComplete("identified-stack");
+
+await simCfn.deleteStack(
+  new DeleteStackCommand({ StackName: "identified-stack" }),
+);
+await simCfn.waitForStackDeleteComplete("identified-stack");
+
+const described = await simCfn.describeStacks(
+  new DescribeStacksCommand({ StackName: created.StackId }),
+);
+
+// DELETE_COMPLETE
+console.log(described.Stacks?.[0]?.StackStatus);
+```
+
 ## Stack deployment is asynchronous
 
 A stack may be visible before all resources have finished creating.
@@ -302,6 +362,78 @@ A template that changes nothing at all is refused with a `ValidationError` readi
 `No updates are to be performed.`, the same answer CloudFormation gives. So is an update asked for
 while another is still running.
 
+### Updating without the whole template
+
+`UsePreviousTemplate: true` updates the stack from the template it already holds. That is how a
+parameter value is changed on its own, when the caller has no copy of the template body to hand.
+Sending a `TemplateBody` alongside it is refused with a `ValidationError`, the way CloudFormation
+refuses it.
+
+A parameter carrying `UsePreviousValue: true` takes the value the stack was deployed with. Sending a
+`ParameterValue` for that same parameter is refused the same way. A parameter the stack was deployed
+without takes its template `Default` again.
+
+```typescript sim-cloudformation-update-previous-template
+/**
+ * Changing one parameter value without resending the template.
+ */
+
+import {
+  CreateStackCommand,
+  UpdateStackCommand,
+} from "@aws-sdk/client-cloudformation";
+
+import { SimAws } from "@kensio/yulin";
+
+const simAws = new SimAws();
+const simCfn = simAws.cloudFormation();
+
+await simCfn.createStack(
+  new CreateStackCommand({
+    StackName: "reports",
+    TemplateBody: JSON.stringify({
+      Parameters: {
+        Environment: { Type: "String" },
+        Version: { Type: "String" },
+      },
+      Resources: {
+        ReportsBucket: {
+          Type: "AWS::S3::Bucket",
+          Properties: {
+            // eslint-disable-next-line no-template-curly-in-string
+            BucketName: { "Fn::Sub": "reports-${Environment}-${Version}" },
+          },
+        },
+      },
+    }),
+    Parameters: [
+      { ParameterKey: "Environment", ParameterValue: "staging" },
+      { ParameterKey: "Version", ParameterValue: "one" },
+    ],
+  }),
+);
+await simCfn.waitForStackDeployComplete("reports");
+
+// Only the version moves. The template and the environment stay where the
+// deployment put them.
+await simCfn.updateStack(
+  new UpdateStackCommand({
+    StackName: "reports",
+    UsePreviousTemplate: true,
+    Parameters: [
+      { ParameterKey: "Environment", UsePreviousValue: true },
+      { ParameterKey: "Version", ParameterValue: "two" },
+    ],
+  }),
+);
+await simCfn.waitForStackUpdateComplete("reports");
+
+console.log(simAws.s3().getSimBucketByName("reports-staging-two"));
+```
+
+An update from the held template with the deployed values changes nothing, and is refused with
+`No updates are to be performed.` like any other.
+
 ### Changed resources are replaced
 
 A resource whose template entry changed is deleted and created again from the new template. Real
@@ -309,20 +441,297 @@ CloudFormation updates most properties in place and keeps what the resource hold
 divergence worth knowing about. A bucket that gains a property loses its objects here, where in AWS
 it would keep them. In-place update is the obvious next step, still to be built.
 
-Two things follow from replacement:
+Three things follow from replacement:
 
 - A resource naming a replaced resource is replaced too, all the way up the dependency chain, and
   nothing is left pointing at a resource that has gone. Real CloudFormation hands the dependent the
   new physical name and leaves it standing.
-- `UpdateReplacePolicy` is not read. Honouring `Retain` would leave the old resource holding the
-  name the replacement needs, and CDK marks buckets and tables with it as a matter of course, so
-  every such update would fail. The old resource is deleted whatever the policy says.
+- A resource declared with `UpdateReplacePolicy: Retain` is kept, and the replacement is created
+  beside it. See [`UpdateReplacePolicy`](#updatereplacepolicy) below.
+- A resource a failed update had already replaced comes back empty when the stack is rolled back.
+  The deployed one was deleted to make room for the replacement, and there is nothing left to put
+  back. See [rolling back a failed update](#rolling-back-a-failed-update) below.
+
+### Rolling back a failed update
+
+A failed update is rolled back onto the template the stack was deployed from. The stack moves to
+`UPDATE_ROLLBACK_IN_PROGRESS`, the previous template is applied over whatever the update left
+behind, and the stack settles in `UPDATE_ROLLBACK_COMPLETE`. `DescribeStacksCommand` reports each of
+those statuses as the stack reaches it, with the reason the update stopped as `StackStatusReason`.
+`waitForStackUpdateComplete(...)` waits for the rollback and then rethrows the update's error.
+
+```typescript sim-cloudformation-update-rollback
+/**
+ * Rolling a failed stack update back to the deployed template.
+ */
+
+import {
+  CreateStackCommand,
+  DescribeStacksCommand,
+  UpdateStackCommand,
+} from "@aws-sdk/client-cloudformation";
+
+import { SimAws } from "@kensio/yulin";
+
+const simAws = new SimAws();
+const simCfn = simAws.cloudFormation();
+
+await simCfn.createStack(
+  new CreateStackCommand({
+    StackName: "reports",
+    TemplateBody: JSON.stringify({
+      Resources: {
+        ReportsBucket: {
+          Type: "AWS::S3::Bucket",
+          Properties: { BucketName: "reports-2025" },
+        },
+      },
+    }),
+  }),
+);
+await simCfn.waitForStackDeployComplete("reports");
+
+// This update renames the bucket and asks for one S3 will not create.
+await simCfn.updateStack(
+  new UpdateStackCommand({
+    StackName: "reports",
+    TemplateBody: JSON.stringify({
+      Resources: {
+        ReportsBucket: {
+          Type: "AWS::S3::Bucket",
+          Properties: { BucketName: "reports-2026" },
+        },
+        ArchiveBucket: {
+          Type: "AWS::S3::Bucket",
+          Properties: { BucketName: "Invalid_Bucket_Name" },
+        },
+      },
+    }),
+  }),
+);
+
+try {
+  await simCfn.waitForStackUpdateComplete("reports");
+} catch (error) {
+  console.error("Stack update failed", error);
+}
+
+const described = await simCfn.describeStacks(
+  new DescribeStacksCommand({ StackName: "reports" }),
+);
+
+console.log(described.Stacks?.[0]?.StackStatus);
+// "UPDATE_ROLLBACK_COMPLETE"
+
+// The bucket the deployed template describes is back in simulated S3.
+console.log(simAws.s3().getSimBucketByName("reports-2025"));
+```
+
+The difference the rollback applies is worked out from the resources the stack holds when the update
+stops. A failure part way through is reconciled from where it got to, and an update that failed
+before it touched a resource has nothing to undo.
+
+A rollback that cannot finish leaves the stack in `UPDATE_ROLLBACK_FAILED`, with its own failure as
+the reason. `UpdateReplacePolicy: Retain` on a replaced resource is one way to reach that. The kept
+resource still holds the name, and the rollback asks for that name again when it recreates the
+resource the deployed template describes.
+
+Dealing with the cause and sending `UpdateStackCommand` again applies the change to the rolled-back
+stack.
+
+### `UpdateReplacePolicy`
+
+A resource declared with `UpdateReplacePolicy: Retain` is left in simulated AWS when an update
+replaces it. The stack stops tracking it, the replacement takes over its logical ID, and the kept
+resource is reported on the stack the way a retained resource is after a teardown.
+
+```typescript sim-cloudformation-update-replace-policy
+/**
+ * Keeping a Resource an update replaces.
+ */
+
+import {
+  CreateStackCommand,
+  UpdateStackCommand,
+} from "@aws-sdk/client-cloudformation";
+
+import { SimAws } from "@kensio/yulin";
+
+const simAws = new SimAws();
+const simCfn = simAws.cloudFormation();
+
+function reportsTemplate(bucketName: string): string {
+  return JSON.stringify({
+    Resources: {
+      ReportsBucket: {
+        Type: "AWS::S3::Bucket",
+        UpdateReplacePolicy: "Retain",
+        Properties: { BucketName: bucketName },
+      },
+    },
+  });
+}
+
+await simCfn.createStack(
+  new CreateStackCommand({
+    StackName: "reports",
+    TemplateBody: reportsTemplate("reports-2025"),
+  }),
+);
+await simCfn.waitForStackDeployComplete("reports");
+
+// Renaming the bucket replaces it.
+await simCfn.updateStack(
+  new UpdateStackCommand({
+    StackName: "reports",
+    TemplateBody: reportsTemplate("reports-2026"),
+  }),
+);
+await simCfn.waitForStackUpdateComplete("reports");
+
+// The bucket the update replaced is still in simulated S3.
+console.log(simAws.s3().getSimBucketByName("reports-2025"));
+
+// And so is the one created in its place.
+console.log(simAws.s3().getSimBucketByName("reports-2026"));
+
+// The stack reports what it kept.
+const stack = simCfn.getStackByName("reports");
+console.log(stack?.retainedResources.map((resource) => resource.logicalId));
+```
+
+The attribute is read from the template being applied, which is where CloudFormation reads it. An
+update that adds `UpdateReplacePolicy: Retain` keeps the resource it replaces, and one that drops
+the attribute deletes it.
+
+`DeletionPolicy` has no say in this. CloudFormation reads `DeletionPolicy` for a resource an update
+drops from the template, and `UpdateReplacePolicy` for one it replaces. A bucket marked only with
+`DeletionPolicy: Retain` still goes when its replacement is created. `Snapshot` is treated as
+`Delete`, because no simulated service takes snapshots.
+
+The kept resource holds the name it was created with. Real CloudFormation gives the replacement a
+fresh random name, while simulated CloudFormation generates the same name for the same stack name
+and logical ID every time (see
+[names CloudFormation generates](#names-cloudformation-generates)). A replacement whose name the
+template leaves to CloudFormation therefore asks for a name the kept resource still holds, and fails
+to create. Name the replacement in the template, as the example above does, to have both.
+
+## Deploying through a change set
+
+A change set says what a template would do to a stack before anything happens to it. `cdk deploy`
+goes through one by default, and so does any deployment script that wants to see what an update will
+touch. Simulated CloudFormation serves `CreateChangeSetCommand`, `DescribeChangeSetCommand`,
+`ExecuteChangeSetCommand`, `DeleteChangeSetCommand` and `ListChangeSetsCommand`.
+
+```typescript sim-cloudformation-change-set
+/**
+ * Deploying a simulated CloudFormation Stack through a change set.
+ */
+
+import {
+  CreateChangeSetCommand,
+  DescribeChangeSetCommand,
+  ExecuteChangeSetCommand,
+} from "@aws-sdk/client-cloudformation";
+
+import { SimAws } from "@kensio/yulin";
+
+const simAws = new SimAws();
+const simCfn = simAws.cloudFormation();
+
+const templateBody = JSON.stringify({
+  Resources: {
+    ReportsBucket: {
+      Type: "AWS::S3::Bucket",
+      Properties: { BucketName: "change-set-reports" },
+    },
+  },
+});
+
+// A CREATE change set brings the Stack into being in REVIEW_IN_PROGRESS,
+// holding no created Resources.
+await simCfn.createChangeSet(
+  new CreateChangeSetCommand({
+    StackName: "reports-stack",
+    ChangeSetName: "reports-create",
+    ChangeSetType: "CREATE",
+    TemplateBody: templateBody,
+  }),
+);
+
+// Describing it says what executing it would do. Nothing is deployed yet.
+const described = await simCfn.describeChangeSet(
+  new DescribeChangeSetCommand({
+    StackName: "reports-stack",
+    ChangeSetName: "reports-create",
+  }),
+);
+
+// [{ Action: "Add", LogicalResourceId: "ReportsBucket" }]
+console.log(
+  described.Changes?.map((change) => ({
+    Action: change.ResourceChange.Action,
+    LogicalResourceId: change.ResourceChange.LogicalResourceId,
+  })),
+);
+
+// Executing it deploys the template.
+await simCfn.executeChangeSet(
+  new ExecuteChangeSetCommand({
+    StackName: "reports-stack",
+    ChangeSetName: "reports-create",
+  }),
+);
+await simCfn.waitForStackDeployComplete("reports-stack");
+
+console.log(simAws.s3().getSimBucketByName("change-set-reports"));
+```
+
+`ChangeSetType: CREATE` creates the stack in `REVIEW_IN_PROGRESS` and creates none of its resources.
+`DescribeStacksCommand` reports the stack from that point on, and executing the change set is what
+deploys it. The default, `ChangeSetType: UPDATE`, works out the change against a stack that is
+already deployed and leaves it exactly as it is until the change set is executed.
+
+`CreateChangeSetCommand` returns the change set ARN as `Id`. Every command naming a change set takes
+either that ARN on its own or the change set name together with `StackName`, the way CloudFormation
+takes them.
+
+### What a change set reports
+
+`DescribeChangeSetCommand` answers with one `Changes` entry per resource, each carrying a
+`ResourceChange` with its `Action`, `LogicalResourceId`, `ResourceType` and `Replacement`. A resource
+only the new template has is an `Add`, one only the stack has is a `Remove`, and one both have whose
+template entry changed is a `Modify`.
+
+Every `Modify` carries `Replacement: "True"`. Simulated CloudFormation replaces a changed resource
+rather than updating it in place, and it replaces everything naming a replaced resource as well, so a
+change set reports each of those as a modification too. See
+[changed resources are replaced](#changed-resources-are-replaced) for what that costs.
 
-A failed update leaves the stack in `UPDATE_FAILED` with the reason on it, and leaves the resources
-where the update got to. There is no rollback to the previous template.
-`waitForStackUpdateComplete(...)` rethrows the error, and `DescribeStacksCommand` reports it as
-`StackStatusReason`. Dealing with the cause and sending `UpdateStackCommand` again applies the rest
-of the change.
+A change set describing a template the stack already holds is `FAILED`, carrying the reason
+CloudFormation gives, and refuses to execute. That is the same no-op rule an update follows, so a
+template that only moves an output still has something to execute.
+
+### Executing a change set
+
+`executeChangeSet(...)` returns once the stack operation has started, as `createStack(...)` and
+`updateStack(...)` do. Follow it with `waitForStackDeployComplete(...)` for a `CREATE` change set or
+`waitForStackUpdateComplete(...)` for an `UPDATE` one.
+
+The change set reports its own execution through `ExecutionStatus`. It reads `AVAILABLE` before,
+`EXECUTE_IN_PROGRESS` while the stack operation runs, and `EXECUTE_COMPLETE` or `EXECUTE_FAILED`
+after. Every other executable change set against the same stack becomes `OBSOLETE`, because each was
+worked out against a stack the execution has moved on.
+
+A change set whose stack has moved on since it was created is refused as `OBSOLETE`, which is what
+CloudFormation calls a change set whose stack was already updated. An update sent directly, and
+another change set executed first, both leave it there. Executing it would apply a difference nobody
+has seen, because what it reports was worked out against the template the stack held then.
+
+`DeleteChangeSetCommand` takes a change set away without executing it, and a change set name that is
+not there is a success rather than an error. Every other command naming one that is not there is
+refused with a `ChangeSetNotFoundException`. `ListChangeSetsCommand` reports the ones a stack still
+holds, in the order they were created.
 
 ## Deleting a stack
 
@@ -385,7 +794,8 @@ Deletion runs in the background, as deployment does. `deleteStack(...)` returns
 moved to `DELETE_IN_PROGRESS`, and `waitForStackDeleteComplete(...)` waits for the resources to go.
 `DescribeStacksCommand` reports `DELETE_IN_PROGRESS` in between, and then refuses the stack name with
 a `ValidationError` once the deletion has finished. That is how CloudFormation answers a name it no
-longer holds.
+longer holds. The stack itself is still there under its
+[stack ID](#stack-ids), reporting `DELETE_COMPLETE` and the Outputs it finished with.
 
 Deleting a stack name that was never deployed succeeds, as it does in CloudFormation.
 
@@ -413,6 +823,77 @@ Retained resources are readable from the stack:
 console.log(stack.retainedResources.map((resource) => resource.logicalId));
 ```
 
+### `RetainResources`
+
+`DeleteStackCommand` takes `RetainResources`, naming resources to leave in simulated AWS. Each one
+is kept whatever its own `DeletionPolicy` says, and the stack deletes around it and reaches
+`DELETE_COMPLETE`.
+
+```typescript sim-cloudformation-retain-resources
+/**
+ * Keeping named Resources when a Stack is deleted.
+ */
+
+import {
+  CreateStackCommand,
+  DeleteStackCommand,
+} from "@aws-sdk/client-cloudformation";
+import { PutObjectCommand } from "@aws-sdk/client-s3";
+
+import { SimAws } from "@kensio/yulin";
+
+const simAws = new SimAws();
+const simCfn = simAws.cloudFormation();
+
+await simCfn.createStack(
+  new CreateStackCommand({
+    StackName: "reports-stack",
+    TemplateBody: JSON.stringify({
+      Resources: {
+        ReportsBucket: {
+          Type: "AWS::S3::Bucket",
+          Properties: { BucketName: "reports" },
+        },
+        ArchiveBucket: {
+          Type: "AWS::S3::Bucket",
+          Properties: { BucketName: "archive" },
+        },
+      },
+    }),
+  }),
+);
+await simCfn.waitForStackDeployComplete("reports-stack");
+
+await simAws.s3().putObject(
+  new PutObjectCommand({
+    Bucket: "reports",
+    Key: "january.csv",
+    Body: "reported",
+  }),
+);
+
+await simCfn.deleteStack(
+  new DeleteStackCommand({
+    StackName: "reports-stack",
+    RetainResources: ["ReportsBucket"],
+  }),
+);
+await simCfn.waitForStackDeleteComplete("reports-stack");
+
+// The named bucket is still in simulated S3, with the object it held.
+console.log(simAws.s3().getSimBucketByName("reports"));
+
+// The bucket the call did not name has gone.
+console.log(simAws.s3().getSimBucketByName("archive"));
+```
+
+Keeping a bucket that holds objects is one reason to reach for this. S3 refuses to delete such a
+bucket, which fails the whole teardown, and naming it here steps over it.
+
+A name the stack has no resource for is refused with a `ValidationError`, as CloudFormation refuses
+one. A CDK construct ID resolves here as well as a logical ID, the same way `stack.getResource(...)`
+takes either.
+
 ## Parameters
 
 Template parameters can be supplied when creating a stack.
@@ -771,6 +1252,23 @@ The value a lookup returns can be any type. A list value is returned as a list.
 used in resource properties and in `Outputs`. A map name or key missing from `Mappings` fails the
 deployment with an error naming the path that could not be found.
 
+A fourth argument of `{ "DefaultValue": ... }` gives the lookup an answer for that case.
+
+```json
+{
+  "Fn::FindInMap": [
+    "EnvironmentMap",
+    { "Ref": "Environment" },
+    "BucketName",
+    { "DefaultValue": "fallback-site-bucket" }
+  ]
+}
+```
+
+The default answers a map name, a top-level key or a second-level key the `Mappings` section does
+not carry. It is a template value like any other, so it can itself be a `Ref` or a nested
+expression. A lookup that finds its value in the map ignores the default.
+
 ### `Fn::Split` and `Fn::Select`
 
 `Fn::Split` cuts a string into a list on a delimiter. `Fn::Select` reads one value out of a list by
@@ -1002,10 +1500,10 @@ console.log(stack.getResource("Backups") !== undefined);
 
 ### Writing a condition
 
-A condition is built from `Fn::Equals`, `Fn::And`, `Fn::Or` and `Fn::Not`. `Fn::And` and `Fn::Or`
-take a list of two to ten conditions, and `Fn::Not` takes a list of exactly one. A condition can
-name another condition with `{ "Condition": "OtherCondition" }`, in any order, so a condition may
-name one written below it in the section.
+A condition is built from `Fn::Equals`, `Fn::And`, `Fn::Or`, `Fn::Not` and `Fn::If`. `Fn::And` and
+`Fn::Or` take a list of two to ten conditions, and `Fn::Not` takes a list of exactly one. A
+condition can name another condition with `{ "Condition": "OtherCondition" }`, in any order, so a
+condition may name one written below it in the section.
 
 ```json
 {
@@ -1020,9 +1518,27 @@ name one written below it in the section.
 `Fn::Equals` compares its two values as strings, as CloudFormation does. A JSON number in the
 template matches the string a parameter carries.
 
+An `Fn::If` inside the section takes a condition name and two conditions, and evaluates whichever
+one the named condition selects. The condition it names can be written anywhere in the section.
+
+```json
+{
+  "IsProd": { "Fn::Equals": [{ "Ref": "EnvName" }, "prod"] },
+  "IsBackedUp": {
+    "Fn::If": [
+      "IsProd",
+      { "Fn::Equals": [{ "Ref": "BackupPlan" }, "nightly"] },
+      { "Fn::Equals": ["never", "nightly"] }
+    ]
+  }
+}
+```
+
 The whole section is evaluated once per deployment, before any resource is created. A condition can
 read parameters and pseudo parameters and nothing else. A comparison that would need a created
-resource, such as an `Fn::GetAtt`, fails the deployment rather than reading as false.
+resource, such as an `Fn::GetAtt`, fails the deployment rather than reading as false. A condition
+that closes a cycle through `{ "Condition": ... }` or `Fn::If` fails the deployment naming the route
+it took back to itself.
 
 ### `Fn::If`
 
@@ -1046,6 +1562,15 @@ fails.
 
 A `Condition` attribute naming a condition the template leaves undefined fails the same way.
 
+### The output `Condition` attribute
+
+An output carrying a `Condition` attribute whose condition is false is left out of the stack. It is
+absent from `stack.outputs` and from `DescribeStacks`, and the export name it carries is never
+published, so another stack's `Fn::ImportValue` for that name finds nothing.
+
+An output whose condition is true resolves and exports as any other output does. One naming a
+condition the template leaves undefined fails the deployment.
+
 ## Resource dependencies
 
 Resources can depend on each other explicitly with `DependsOn`.
@@ -1590,8 +2115,62 @@ const stacks = await simAws.cloudFormation().deployCdkOut({
 console.log(stacks.get("PipelineStack")?.stackName);
 ```
 
-A staged CDK asset is published under the same principal, before CloudFormation reads the template
-that points at it.
+### The principal a CDK asset is published as
+
+A real `cdk deploy` runs in two phases under two Roles. `cdk-assets` publishes every staged file
+asset to the bootstrap staging bucket as the file publishing Role, and CloudFormation then processes
+the template as the execution Role. `assetsCaller` names the first of those, beside the `caller`
+naming the second.
+
+```typescript sim-cloudformation-assets-caller
+/**
+ * Publishing a Stack's CDK file assets as the file publishing Role.
+ */
+
+import { SimAws } from "@kensio/yulin";
+
+const simAws = new SimAws({
+  defaultAccountId: "123456789012",
+  defaultRegionName: "eu-west-2",
+});
+
+const publisher = await simAws.iam().makeDeployRole({
+  roleName: "cdk-file-publishing",
+  policyDocument: {
+    Version: "2012-10-17",
+    Statement: {
+      Effect: "Allow",
+      Action: ["s3:GetObject*", "s3:GetBucket*", "s3:List*", "s3:PutObject"],
+      Resource: "arn:aws:s3:::cdk-hnb659fds-assets-*",
+    },
+  },
+});
+
+const executor = await simAws.iam().makeDeployRole({
+  roleName: "cdk-exec",
+  policyDocument: {
+    Version: "2012-10-17",
+    Statement: { Effect: "Allow", Action: "s3:*", Resource: "*" },
+  },
+});
+
+const stacks = await simAws.cloudFormation().deployCdkOut({
+  directoryPath: "cdk.out",
+  caller: executor,
+  assetsCaller: publisher,
+});
+
+console.log(stacks.size);
+```
+
+`deployTemplate(...)` and `deployTemplateFile(...)` take the same option, and a Stack in an assembly
+names its own in `stackOptions`. A deployment that names no `assetsCaller` publishes its assets as
+`caller`, the way every deployment did before the two could be told apart.
+
+The CDK bootstrap stack provisions the staging bucket, long before either Role runs. Yulin stands in
+for that and makes the bucket outside IAM when the first asset is published into it. So a Role
+holding only what a scoped execution policy grants on `cdk-hnb659fds-assets-*` deploys a cloud
+assembly with file assets, with no `s3:CreateBucket` or `s3:PutObject` added to it.
 
 ## Editing a synthesized template before deploying it
 
@@ -1732,10 +2311,9 @@ await simAws.cloudFormation().updateTemplateFile({ templatePath });
 The sibling assets manifest is read again with the template. A resource the update replaces reads the
 assets that synthesis staged, not the ones the stack was deployed with.
 
-A file written without being changed is refused with `No updates are to be performed.`, and a failed
-update leaves the stack in `UPDATE_FAILED` holding whatever the update reached. There is no rollback
-to the template it was deployed from. A failure part way through has already deleted, replaced or
-created some of the resources the change asked for.
+A file written without being changed is refused with `No updates are to be performed.`. A failed
+update is rolled back onto the template the stack was deployed from, and settles in
+`UPDATE_ROLLBACK_COMPLETE`. See [rolling back a failed update](#rolling-back-a-failed-update).
 
 ## Watching a template file
 
@@ -1783,9 +2361,10 @@ browser arriving on the new resources finds whatever the callback left ready for
 
 `onFailed` is given the update the changed template failed to survive. It reports the failure and
 nothing else.
-The stack is left holding whatever the update reached, as it is after an update through the command.
-What a failure does keep is the process, and the resources it never got to. A template that no longer
-deploys leaves a working environment where a restart on it would leave none.
+The stack is rolled back onto the template it was deployed from, as it is after an update through the
+command. A resource the update had already replaced comes back empty. What a failure keeps is the
+process. A template that no longer deploys leaves a working environment where a restart on it would
+leave none.
 
 A burst of writes is one update. Saving a file is several filesystem events, so changes are held
 until they stop arriving. `settleMs` is how long that wait is, and it defaults to the 250ms
@@ -1867,6 +2446,11 @@ around it are read the same way:
   the deployment turns it off, as the construct is. Pruning only considers what the filters and the
   key prefix select, and leaves alone any Object the deployment would never have copied.
 
+A Bucket with an event notification configuration hears the deployment. Every file the deployment
+writes raises `s3:ObjectCreated:Put`, and every Object a pruning deployment removes raises
+`s3:ObjectRemoved:Delete`, the two the real provider function's sync raises. See
+[Event notifications](https://yulinsim.dev/services/s3/#event-notifications).
+
 Several deployments can share one Bucket. That is the usual arrangement when the headers differ by
 file type, since a `BucketDeployment` sets them for all of its files at once. A second deployment is
 how the rest of the site gets different ones. Give the second one `prune: false`, or filters that miss
@@ -2266,9 +2850,9 @@ its own `Role` runs as that role, and gets no expanded one.
 ### Function events
 
 `Events` on a SAM function expand into whatever puts the function behind them. `Api`, `HttpApi`,
-`SQS`, `DynamoDB`, `SNS`, `S3`, `Schedule`, `ScheduleV2` and `EventBridgeRule` are the types this
-covers. An event of any other type is left where it is, and the function deploys with nothing in
-front of it.
+`SQS`, `DynamoDB`, `SNS`, `S3`, `Cognito`, `Schedule`, `ScheduleV2` and `EventBridgeRule` are the
+types this covers. An event of any other type is left where it is, and the function deploys with
+nothing in front of it.
 
 An `HttpApi` event becomes an `AWS::ApiGatewayV2::Integration`, an `AWS::ApiGatewayV2::Route` and the
 `AWS::Lambda::Permission` the API invokes the function under. `Path` and `Method` become the route
@@ -2340,7 +2924,8 @@ console.log(await response.text());
 await srv.close();
 ```
 
-`Auth` on the event is left out. Every request matching the expanded route reaches the function.
+`Auth` on the event names one of the API's authorizers. A route the event and the API both leave
+open is reached by every request matching it.
 
 An `Api` event is the REST half of the same idea. It becomes an `AWS::ApiGateway::Resource` for each
 segment of `Path`, an `AWS::ApiGateway::Method` on the last of them carrying a proxy `Integration`
@@ -2507,8 +3092,7 @@ time window gets `OFF`.
 once, and a failed one is recorded by the rule or the schedule that made it.
 
 A `FunctionUrlConfig` on the function expands into an `AWS::Lambda::Url` named after it, `RatesUrl`
-for a function called `Rates`. `AuthType` and `InvokeMode` carry over. `Cors` is left out (the
-simulated Function URL answers no preflight request).
+for a function called `Rates`. `AuthType`, `InvokeMode` and `Cors` carry over.
 
 ### Queue, stream, topic and bucket events
 
@@ -2639,8 +3223,9 @@ reaches an API the template declared, and how an `AWS::ApiGatewayV2::Route` reso
 does. An API naming a `DefinitionUri` is recorded as unsupported, because nothing here reads a
 document off disk or out of S3.
 
-The API is deployed without `Auth` and `Domain`. SAM writes an `Auth` block into the document it
-generates, and deploys a `Domain` as a custom domain name resource, and neither is expanded here.
+An `Auth` block becomes the authorizer resources it declares, covered under
+[API authorizers](#api-authorizers) below. A `Domain` is deployed by SAM as a custom domain name
+resource, and an API declaring one is deployed without it.
 
 ```typescript sim-cloudformation-sam-table-api
 /**
@@ -2711,9 +3296,9 @@ created without, because reading the document is outside this. An API declaring
 root resource and an empty tree under it. An API naming a `DefinitionUri` is recorded as
 unsupported, because this reads no document off disk or out of S3.
 
-The API is deployed without `Auth`, `Cors`, `Domain`, `GatewayResponses`, `MethodSettings` and
+The API is deployed without `Cors`, `Domain`, `GatewayResponses`, `MethodSettings` and
 `BinaryMediaTypes`. SAM writes each of them into the document it generates, and none is expanded
-here.
+here. `Auth` is expanded, and has [a section of its own](#api-authorizers) below.
 
 ```typescript sim-cloudformation-sam-rest-api
 /**
@@ -2758,6 +3343,162 @@ something the stack holds, answers `Ref` for and tears down. The APIs, stages an
 the same either way, and the logical IDs of the path resources have no counterpart in what SAM
 produces.
 
+### API authorizers
+
+`Auth` on an `AWS::Serverless::Api` or an `AWS::Serverless::HttpApi` expands into the authorizers it
+declares. A REST API gets one `AWS::ApiGateway::Authorizer` per entry in `Authorizers`, and an HTTP
+API gets one `AWS::ApiGatewayV2::Authorizer`. Each carries the logical ID of the API with the
+authorizer's name and `Authorizer` after it (`OrdersPoolAuthAuthorizer` for an authorizer called
+`PoolAuth` on an API called `Orders`). A template can `Ref` that name, and the stack tears the
+authorizer down with everything else.
+
+On a REST API, an authorizer naming a `UserPoolArn` verifies Cognito tokens, and one naming a
+`FunctionArn` asks a function of the template. `FunctionPayloadType` picks between the `TOKEN`
+authorizer that is handed one header and the `REQUEST` authorizer that is handed the whole request.
+SAM defaults to `TOKEN`. `Identity` names the parts of the request the authorizer reads (`Header`,
+`Headers`, `QueryStrings`, `StageVariables` and `Context`), and `ReauthorizeEvery` becomes the
+authorizer's result TTL.
+
+On an HTTP API, an authorizer naming a `JwtConfiguration` verifies tokens against the issuer it
+names, and one naming a `FunctionArn` asks a function. The issuer and audience are read under either
+spelling (SAM writes them in lower case and CloudFormation capitalises them).
+`AuthorizerPayloadFormatVersion` defaults to `2.0`. `EnableIamAuthorizer` puts `AWS_IAM` among the
+names a route can take, and a REST API carries that name already.
+
+`DefaultAuthorizer` names the authorizer every method and route takes. An `Api` or `HttpApi` event
+picks another one with `Auth.Authorizer`, and opens its own method with `Auth.Authorizer: NONE`.
+`Auth.AuthorizationScopes` on the event replaces the scopes the authorizer asks for. The implicit
+API a function's events create reads its `Auth` from `Globals.Api` or `Globals.HttpApi`.
+
+An `Auth` property outside that set fails the transform, naming the property. `ApiKeyRequired`,
+`UsagePlan`, `ResourcePolicy`, `InvokeRole`, `AddDefaultAuthorizerToCorsPreflight` and
+`Identity.ValidationExpression` are all refused that way. Dropping one of them would deploy an API
+that authorizes less than the template asked for, and the failure says which property it was.
+
+```typescript sim-cloudformation-sam-api-auth
+/**
+ * A SAM HTTP API closed by the Cognito user pool its Auth block names.
+ */
+
+import { SimAws } from "@kensio/yulin";
+import { serveSimAws } from "@kensio/yulin/serve";
+
+const simAws = new SimAws();
+
+const stack = await simAws.cloudFormation().deployTemplate({
+  stackName: "orders-api-stack",
+  template: {
+    Transform: "AWS::Serverless-2016-10-31",
+    Resources: {
+      Users: {
+        Type: "AWS::Cognito::UserPool",
+        Properties: { UserPoolName: "orders-users" },
+      },
+      WebClient: {
+        Type: "AWS::Cognito::UserPoolClient",
+        Properties: {
+          UserPoolId: { Ref: "Users" },
+          ClientName: "web",
+          ExplicitAuthFlows: ["ALLOW_ADMIN_USER_PASSWORD_AUTH"],
+        },
+      },
+      Orders: {
+        Type: "AWS::Serverless::HttpApi",
+        Properties: {
+          Auth: {
+            DefaultAuthorizer: "PoolAuth",
+            Authorizers: {
+              PoolAuth: {
+                JwtConfiguration: {
+                  issuer: { "Fn::GetAtt": ["Users", "ProviderURL"] },
+                  audience: [{ Ref: "WebClient" }],
+                },
+              },
+            },
+          },
+        },
+      },
+      Handler: {
+        Type: "AWS::Serverless::Function",
+        Properties: {
+          Handler: "index.handler",
+          Runtime: "nodejs22.x",
+          Events: {
+            Get: {
+              Type: "HttpApi",
+              Properties: {
+                ApiId: { Ref: "Orders" },
+                Path: "/orders",
+                Method: "GET",
+              },
+            },
+          },
+        },
+      },
+    },
+    Outputs: {
+      ApiEndpoint: { Value: { "Fn::GetAtt": ["Orders", "ApiEndpoint"] } },
+      PoolId: { Value: { Ref: "Users" } },
+      ClientId: { Value: { Ref: "WebClient" } },
+    },
+  },
+  bindings: [
+    {
+      logicalId: "Handler",
+      handler: (): { statusCode: number; body: string } => ({
+        statusCode: 200,
+        body: "orders",
+      }),
+    },
+  ],
+});
+
+await stack.waitForDeployComplete();
+
+const cognito = simAws.cognitoIdentityProvider();
+const userPoolId = stack.output("PoolId");
+const clientId = stack.output("ClientId");
+
+await cognito.adminCreateUser({
+  input: { UserPoolId: userPoolId, Username: "ada" },
+});
+await cognito.adminSetUserPassword({
+  input: {
+    UserPoolId: userPoolId,
+    Username: "ada",
+    Password: "Correct-horse-1",
+    Permanent: true,
+  },
+});
+const signedIn = await cognito.adminInitiateAuth({
+  input: {
+    UserPoolId: userPoolId,
+    ClientId: clientId,
+    AuthFlow: "ADMIN_USER_PASSWORD_AUTH",
+    AuthParameters: { USERNAME: "ada", PASSWORD: "Correct-horse-1" },
+  },
+});
+
+const srv = await serveSimAws({ simAws });
+const url = srv.localUrl(`${stack.output("ApiEndpoint")}/orders`);
+
+const refused = await fetch(url);
+
+console.log(refused.status);
+// 401
+
+const admitted = await fetch(url, {
+  headers: {
+    authorization: `Bearer ${signedIn.AuthenticationResult?.AccessToken}`,
+  },
+});
+
+console.log(admitted.status);
+// 200
+
+await srv.close();
+```
+
 ## Serving deployed resources on localhost
 
 CloudFormation itself is not served as an HTTP API. Instead, you deploy infrastructure through Sim
@@ -3489,8 +4230,18 @@ Sim CloudFormation currently supports:
 
 - `CreateStackCommand`, `DescribeStacksCommand`, `UpdateStackCommand` and `DeleteStackCommand`,
   taking a `TemplateBody` written as JSON or as YAML with short-form intrinsic tags
+- `UsePreviousTemplate` on `UpdateStackCommand`, and `UsePreviousValue` on one of its parameters,
+  for an update that changes a parameter value on its own
+- Rollback of a failed update onto the template the stack was deployed from, through
+  `UPDATE_ROLLBACK_IN_PROGRESS` to `UPDATE_ROLLBACK_COMPLETE` or `UPDATE_ROLLBACK_FAILED`
+- `CreateChangeSetCommand`, `DescribeChangeSetCommand`, `ExecuteChangeSetCommand`,
+  `DeleteChangeSetCommand` and `ListChangeSetsCommand`, for both `CREATE` and `UPDATE` change sets
 - Waiting for simulated stack deployment, update and deletion completion
-- The resource `DeletionPolicy` attribute, for `Retain` and `RetainExceptOnCreate`
+- Stack IDs in the CloudFormation ARN shape, accepted by `DescribeStacksCommand` in place of a stack
+  name, and still describing a stack once it has been deleted
+- The resource `DeletionPolicy` attribute, for `Retain` and `RetainExceptOnCreate`, and
+  `UpdateReplacePolicy`, for `Retain`
+- `RetainResources` on `DeleteStackCommand`, naming resources a teardown leaves in simulated AWS
 - `deployTemplate(...)` for parsed template objects, optionally naming the synthesized template file
   a template edited in memory came from
 - `deployTemplateFile(...)` for template files, written as JSON or as YAML with short-form
@@ -3500,8 +4251,9 @@ Sim CloudFormation currently supports:
 - Template `Parameters` with supplied values and defaults
 - Template `Outputs`, resolved after resource creation and read from `stack.outputs`
 - Template `Mappings`, read with `Fn::FindInMap`
-- Template `Conditions`, built from `Fn::Equals`, `Fn::And`, `Fn::Or` and `Fn::Not`
-- The resource `Condition` attribute, which decides whether a resource is created
+- Template `Conditions`, built from `Fn::Equals`, `Fn::And`, `Fn::Or`, `Fn::Not` and `Fn::If`
+- The `Condition` attribute on a resource, which decides whether the resource is created, and on an
+  output, which decides whether the output and its export are published
 - The `Ref`, `Fn::GetAtt`, `Fn::Join`, `Fn::Sub`, `Fn::FindInMap`, `Fn::If`, `Fn::Split` and
   `Fn::Select` intrinsic functions
 - Explicit resource dependencies with `DependsOn`
@@ -3514,6 +4266,10 @@ Sim CloudFormation currently supports:
 - The `HttpApi` event of a SAM function, expanded into the API, integration, route, stage and invoke
   permission that serve it, and the `Api` event, expanded into the API, path resources, method,
   deployment, stage and invoke permission that serve it
+- `Auth` on a SAM API, expanded into the Cognito, JWT and Lambda authorizers it declares, with
+  `DefaultAuthorizer` and the `Auth` an event states deciding which one guards each method or route
+- The `Cognito` event of a SAM function, expanded into the pool's `LambdaConfig` entry and the
+  permission the pool invokes the function under
 - `FunctionUrlConfig` on a SAM function, expanded into a Function URL
 - The `Schedule`, `ScheduleV2` and `EventBridgeRule` events of a SAM function, expanded into the
   EventBridge rule or Scheduler schedule that fires the function, and the permission or execution
@@ -3589,48 +4345,56 @@ Each service's own docs describe what its resource types support.
   changed resource is still replaced and loses what it holds, the same as any other update.
 - Yulin never synthesizes a CDK app. It watches the synthesized output template. A change to the app
   itself reaches the stack once something has run `cdk synth` over it.
-- A stack update applies a whole template directly. Change sets are outside the simulation, so
-  `CreateChangeSetCommand` and `ExecuteChangeSetCommand` have nothing behind them, and neither does
-  drift detection.
-- A failed stack update is not rolled back to the template the stack was deployed from. The stack is
-  left in `UPDATE_FAILED` holding whatever the update managed.
-- `UpdateStackCommand` reads `StackName`, `TemplateBody` and `Parameters`. `UsePreviousTemplate` and
-  `UsePreviousValue` are not read, so an update has to be given the whole new template.
-- An update asked for while another is still running is refused, as CloudFormation refuses it. There
-  is no queue behind it.
+- A change set reports every `Modify` as `Replacement: True`, because a changed resource is replaced
+  rather than updated in place. `ChangeSetType: IMPORT` is refused, and so is a `CREATE` change set
+  naming a stack that is already there, where CloudFormation allows a second one against a stack
+  still in review. Drift detection is outside the simulation.
+- A rolled-back update recreates a resource it had already replaced, and the resource comes back
+  empty. Real CloudFormation puts most properties back on the resource it updated in place, and what
+  the resource holds survives. See
+  [rolling back a failed update](#rolling-back-a-failed-update).
+- `UpdateStackCommand` reads `StackName`, `TemplateBody`, `UsePreviousTemplate` and `Parameters`,
+  including `UsePreviousValue` on a parameter. `DisableRollback` and `RollbackConfiguration` are not
+  read, so a failed update is always rolled back.
+- An update asked for while another is still running, or while one is being rolled back, is refused,
+  as CloudFormation refuses it. There is no queue behind it.
+- A stack left in `UPDATE_ROLLBACK_FAILED` can be updated again, reconciled from the resources it is
+  holding. Real CloudFormation refuses until `ContinueUpdateRollback` has finished the rollback, and
+  that command is outside the simulation.
 - A stack deletion deletes only the resource types the simulator can delete. A resource type it
   creates but cannot delete is recorded in `stack.skippedResourceDeletions` and stepped over, the
   same way an unsupported resource type is on create, and the stack still deletes with that resource
   left behind.
-- `DeletionPolicy` is read for `Retain` and `RetainExceptOnCreate` only. `Snapshot` is treated as
-  `Delete`, because no simulated service takes snapshots.
-- `UpdateReplacePolicy` is not read. A replaced resource is deleted whatever it says, for the reason
-  given under [changed resources are replaced](#changed-resources-are-replaced).
-- `DeleteStackCommand` reads only `StackName`. `RetainResources`, `DeletionMode`, `RoleARN` and
-  `ClientRequestToken` are not read, so a stack left in `DELETE_FAILED` cannot be forced through the
-  way `FORCE_DELETE_STACK` forces it in AWS.
-- A deleted stack cannot be described. Real CloudFormation keeps a deleted stack readable by its
-  unique stack ID, and the simulator identifies a stack by its name alone.
-- `Fn::FindInMap` accepts only the three-argument form. The four-argument form, where the fourth
-  argument is `{ "DefaultValue": ... }`, is rejected.
+- `DeletionPolicy` is read for `Retain` and `RetainExceptOnCreate` only, and `UpdateReplacePolicy`
+  for `Retain` only. `Snapshot` is treated as `Delete` in both, because no simulated service takes
+  snapshots.
+- A resource kept by `UpdateReplacePolicy: Retain` holds the name it was created with, and a
+  replacement whose name the template leaves to CloudFormation asks for that same name and fails to
+  create. Real CloudFormation gives the replacement a fresh random name. See
+  [`UpdateReplacePolicy`](#updatereplacepolicy).
+- `DeleteStackCommand` reads `StackName` and `RetainResources`. `DeletionMode`, `RoleARN` and
+  `ClientRequestToken` are not read, and a stack left in `DELETE_FAILED` cannot be forced through
+  the way `FORCE_DELETE_STACK` forces it in AWS.
+- A deleted stack stays describable by its stack ID for as long as the simulation lives. Real
+  CloudFormation drops it after 90 days. `DescribeStacks` with no `StackName` lists the live stacks
+  in both, and `ListStacks` is unsupported, so there is no way to find a deleted stack whose ID you
+  have lost.
 - `Fn::FindInMap` arguments are resolved from literals, `Parameters` and pseudo parameters. An
   argument that depends on a created resource, such as a `Ref` to a resource logical ID, fails the
   resource with a "could not find map" error. Real CloudFormation allows only `Ref` and a nested
   `Fn::FindInMap` inside `Fn::FindInMap`. The templates affected here are ones real CloudFormation
   would reject as well. The simulator just rejects them later rather than up front.
-- `Fn::If` is unsupported inside the `Conditions` section itself. It is rejected there rather than
-  read against a half-evaluated section.
+- `Fn::If` is a condition function inside the `Conditions` section, and is not a value an
+  `Fn::Equals` can compare. Real CloudFormation allows only `Ref` and `Fn::FindInMap` there.
 - `Fn::Split` and `Fn::Select` accept any argument that resolves to the type they need. Real
   CloudFormation allows only a named set of functions inside each of them. A template the simulator
   resolves may still be one CloudFormation rejects.
-- The `Condition` attribute is read on resources but not on outputs. An output carrying one is
-  resolved and present in `stack.outputs` whichever way its condition falls, where real
-  CloudFormation would leave it out.
 - The SAM transform is expanded for `AWS::Serverless::Function`, `AWS::Serverless::SimpleTable`,
   `AWS::Serverless::HttpApi` and `AWS::Serverless::Api`. Every other `AWS::Serverless::*` resource
-  type is recorded as unsupported. `Api`, `HttpApi`, `SQS`, `DynamoDB`, `SNS`, `S3`, `Schedule`,
-  `ScheduleV2` and `EventBridgeRule` are the event types expanded, and an event of another type,
-  such as `Cognito`, is left where it is. `Auth` on an `Api` or `HttpApi` event, and on the implicit API
-  either of them shares, is left out. `AutoPublishAlias` and `DeploymentPreference` are left out
-  too, because the simulator has one version of a function and nothing to shift traffic between.
+  type is recorded as unsupported. `Api`, `HttpApi`, `SQS`, `DynamoDB`, `SNS`, `S3`, `Cognito`,
+  `Schedule`, `ScheduleV2` and `EventBridgeRule` are the event types expanded, and an event of
+  another type is left where it is. Under `Auth`, `ApiKeyRequired`, `UsagePlan`, `ResourcePolicy`,
+  `InvokeRole` and `AddDefaultAuthorizerToCorsPreflight` fail the transform by name.
+  `AutoPublishAlias` and `DeploymentPreference` are left out, because the simulator has one version
+  of a function and nothing to shift traffic between.
 - Many advanced CloudFormation features are outside the simulation.