@kensio/yulin 1.21.0 → 1.21.1

package/docs/services/backup/README.md

@@ -0,0 +1,553 @@
+# Simulated AWS Backup
+
+Yulin includes simulated AWS Backup vaults, plans, selections, backup jobs and recovery points for
+tests and local development. AWS Backup types are imported from the `@kensio/yulin/backup` subpath.
+
+## Creating a vault, plan and selection
+
+`simAws.backup()` gives the AWS Backup service for the default account and Region. A plan rule names
+an existing vault. A selection belongs to one plan and records the resource ARNs assigned to it.
+
+```typescript sim-backup-create-plan-selection
+/**
+ * Creating a daily backup plan for one DynamoDB table.
+ */
+
+import {
+  CreateBackupPlanCommand,
+  CreateBackupSelectionCommand,
+  CreateBackupVaultCommand,
+  GetBackupPlanCommand,
+  GetBackupSelectionCommand,
+} from "@aws-sdk/client-backup";
+import { assertNonNullable } from "@kensio/smartass";
+
+import { SimAws } from "@kensio/yulin";
+
+const simAws = new SimAws();
+const backup = simAws.backup();
+
+await backup.createBackupVault(
+  new CreateBackupVaultCommand({
+    BackupVaultName: "application-backups",
+  }),
+);
+
+const createdPlan = await backup.createBackupPlan(
+  new CreateBackupPlanCommand({
+    BackupPlan: {
+      BackupPlanName: "application-plan",
+      Rules: [
+        {
+          RuleName: "daily",
+          TargetBackupVaultName: "application-backups",
+          ScheduleExpression: "cron(0 1 ? * * *)",
+          Lifecycle: { DeleteAfterDays: 35 },
+        },
+      ],
+    },
+  }),
+);
+assertNonNullable(createdPlan.BackupPlanId);
+
+const createdSelection = await backup.createBackupSelection(
+  new CreateBackupSelectionCommand({
+    BackupPlanId: createdPlan.BackupPlanId,
+    BackupSelection: {
+      SelectionName: "orders",
+      IamRoleArn: "arn:aws:iam::888888888888:role/BackupRole",
+      Resources: ["arn:aws:dynamodb:us-east-1:888888888888:table/orders"],
+    },
+  }),
+);
+assertNonNullable(createdSelection.SelectionId);
+
+const plan = await backup.getBackupPlan(
+  new GetBackupPlanCommand({ BackupPlanId: createdPlan.BackupPlanId }),
+);
+console.log(plan.BackupPlan?.Rules?.[0]?.ScheduleExpression);
+// "cron(0 1 ? * * *)"
+
+const selection = await backup.getBackupSelection(
+  new GetBackupSelectionCommand({
+    BackupPlanId: createdPlan.BackupPlanId,
+    SelectionId: createdSelection.SelectionId,
+  }),
+);
+console.log(selection.BackupSelection?.Resources);
+// ["arn:aws:dynamodb:us-east-1:888888888888:table/orders"]
+```
+
+A plan needs at least one rule. Every rule needs a name and a target vault. An omitted schedule uses
+`cron(0 5 ? * * *)`, the AWS Backup default. Six-field AWS cron expressions and rate expressions
+are validated when the plan is created. A one-time `at(...)` expression is refused.
+
+`MoveToColdStorageAfterDays` can be combined with `DeleteAfterDays`. The deletion must be at least
+90 days after the move to cold storage. A shorter lifecycle raises
+`InvalidParameterValueException`. Set both values to `-1` to retain recovery points indefinitely.
+
+## Running scheduled backups
+
+Each plan rule runs on the simulated clock. A due rule creates one recovery point for each distinct
+resource ARN in the plan's selections. The recovery point records the rule, resource ARN, lifecycle
+and creation time. The simulation completes backup jobs at the scheduled instant.
+
+```typescript sim-backup-run-schedule
+/**
+ * Advancing a plan through its next scheduled backup.
+ */
+
+import {
+  CreateBackupPlanCommand,
+  CreateBackupSelectionCommand,
+  CreateBackupVaultCommand,
+  ListBackupJobsCommand,
+  ListRecoveryPointsByBackupVaultCommand,
+} from "@aws-sdk/client-backup";
+import { assertArrayLength, assertNonNullable } from "@kensio/smartass";
+
+import { SimAws, SimFixedClock } from "@kensio/yulin";
+
+const simAws = new SimAws({
+  clock: new SimFixedClock(new Date("2026-08-31T09:30:00.000Z")),
+});
+const backup = simAws.backup();
+
+await backup.createBackupVault(
+  new CreateBackupVaultCommand({ BackupVaultName: "application-backups" }),
+);
+const createdPlan = await backup.createBackupPlan(
+  new CreateBackupPlanCommand({
+    BackupPlan: {
+      BackupPlanName: "application-plan",
+      Rules: [
+        {
+          RuleName: "hourly",
+          TargetBackupVaultName: "application-backups",
+          ScheduleExpression: "rate(1 hour)",
+          Lifecycle: { DeleteAfterDays: 35 },
+        },
+      ],
+    },
+  }),
+);
+assertNonNullable(createdPlan.BackupPlanId);
+await backup.createBackupSelection(
+  new CreateBackupSelectionCommand({
+    BackupPlanId: createdPlan.BackupPlanId,
+    BackupSelection: {
+      SelectionName: "orders",
+      IamRoleArn: "arn:aws:iam::888888888888:role/BackupRole",
+      Resources: ["arn:aws:dynamodb:us-east-1:888888888888:table/orders"],
+    },
+  }),
+);
+
+await simAws.clock().advanceBy({ hours: 1 });
+
+const stored = backup.vault("application-backups").recoveryPoints();
+assertArrayLength(stored, 1);
+console.log(stored[0].creationDate.toISOString());
+// "2026-08-31T10:30:00.000Z"
+
+const points = await backup.listRecoveryPointsByBackupVault(
+  new ListRecoveryPointsByBackupVaultCommand({
+    BackupVaultName: "application-backups",
+  }),
+);
+const jobs = await backup.listBackupJobs(new ListBackupJobsCommand({}));
+console.log(points.RecoveryPoints?.[0]?.ResourceArn);
+// "arn:aws:dynamodb:us-east-1:888888888888:table/orders"
+console.log(jobs.BackupJobs?.[0]?.State); // "COMPLETED"
+```
+
+`DeleteAfterDays` removes a recovery point when the clock reaches its deletion time. Vault reads,
+`ListRecoveryPointsByBackupVault` and `DescribeRecoveryPoint` apply the expiry before returning.
+Repeated schedules keep every unexpired recovery point.
+
+Vault Lock bounds apply when a backup starts. A lifecycle shorter than `MinRetentionDays`, longer
+than `MaxRetentionDays` or indefinite under a finite maximum produces a `FAILED` backup job. The
+vault receives no recovery point for that job. Use `ListBackupJobs` or `DescribeBackupJob` to read
+the failure and its `StatusMessage`.
+
+## Starting an on-demand backup
+
+`StartBackupJob` completes an on-demand job at the current simulated time. It applies the same
+lifecycle validation and Vault Lock bounds as a scheduled rule.
+
+```typescript sim-backup-start-job
+/**
+ * Creating an on-demand recovery point.
+ */
+
+import {
+  CreateBackupVaultCommand,
+  DescribeRecoveryPointCommand,
+  StartBackupJobCommand,
+} from "@aws-sdk/client-backup";
+import { assertNonNullable } from "@kensio/smartass";
+
+import { SimAws, SimFixedClock } from "@kensio/yulin";
+
+const simAws = new SimAws({
+  clock: new SimFixedClock(new Date("2026-08-31T12:00:00.000Z")),
+});
+const backup = simAws.backup();
+await backup.createBackupVault(
+  new CreateBackupVaultCommand({ BackupVaultName: "manual-backups" }),
+);
+
+const started = await backup.startBackupJob(
+  new StartBackupJobCommand({
+    BackupVaultName: "manual-backups",
+    ResourceArn: "arn:aws:s3:::application-files",
+    IamRoleArn: "arn:aws:iam::888888888888:role/BackupRole",
+    Lifecycle: { DeleteAfterDays: 14 },
+  }),
+);
+assertNonNullable(started.RecoveryPointArn);
+
+const point = await backup.describeRecoveryPoint(
+  new DescribeRecoveryPointCommand({
+    BackupVaultName: "manual-backups",
+    RecoveryPointArn: started.RecoveryPointArn,
+  }),
+);
+console.log(point.CreationDate?.toISOString());
+// "2026-08-31T12:00:00.000Z"
+```
+
+## Vault Lock
+
+`PutBackupVaultLockConfiguration` records minimum and maximum retention periods on a vault. Adding
+`ChangeableForDays` creates a compliance lock. The configuration stays changeable until the grace
+period ends, then becomes immutable.
+
+```typescript sim-backup-vault-lock
+/**
+ * Advancing a compliance lock through its grace period.
+ */
+
+import {
+  CreateBackupVaultCommand,
+  DescribeBackupVaultCommand,
+  PutBackupVaultLockConfigurationCommand,
+} from "@aws-sdk/client-backup";
+
+import { SimAws, SimFixedClock } from "@kensio/yulin";
+
+const simAws = new SimAws({
+  clock: new SimFixedClock(new Date("2026-08-30T10:00:00.000Z")),
+});
+const backup = simAws.backup();
+
+await backup.createBackupVault(
+  new CreateBackupVaultCommand({ BackupVaultName: "compliance-backups" }),
+);
+
+await backup.putBackupVaultLockConfiguration(
+  new PutBackupVaultLockConfigurationCommand({
+    BackupVaultName: "compliance-backups",
+    ChangeableForDays: 3,
+    MinRetentionDays: 7,
+    MaxRetentionDays: 365,
+  }),
+);
+
+const changeable = await backup.describeBackupVault(
+  new DescribeBackupVaultCommand({
+    BackupVaultName: "compliance-backups",
+  }),
+);
+console.log(changeable.LockDate?.toISOString());
+// "2026-09-02T10:00:00.000Z"
+
+await simAws.clock().advanceBy({ days: 3 });
+
+try {
+  await backup.putBackupVaultLockConfiguration(
+    new PutBackupVaultLockConfigurationCommand({
+      BackupVaultName: "compliance-backups",
+      MinRetentionDays: 14,
+    }),
+  );
+} catch (error) {
+  console.log(error instanceof Error ? error.name : "unknown error");
+  // "InvalidParameterValueException"
+}
+```
+
+`ChangeableForDays` must be between 3 and 36,500. Retention periods are whole days. A minimum cannot
+exceed the maximum, and the maximum cannot exceed 36,500 days. A lock without
+`ChangeableForDays` remains changeable.
+
+## Deploying from CloudFormation
+
+Simulated CloudFormation deploys `AWS::Backup::BackupVault`, `AWS::Backup::BackupPlan` and
+`AWS::Backup::BackupSelection`. References between the resources resolve before AWS Backup creates
+them.
+
+```typescript sim-backup-cloudformation
+/**
+ * Deploying a vault, plan and selection from one template.
+ */
+
+import { GetBackupSelectionCommand } from "@aws-sdk/client-backup";
+
+import { SimAws } from "@kensio/yulin";
+
+const simAws = new SimAws();
+const stack = await simAws.cloudFormation().deployTemplate({
+  stackName: "backup-stack",
+  template: {
+    Resources: {
+      Vault: {
+        Type: "AWS::Backup::BackupVault",
+        Properties: {
+          BackupVaultName: "application-backups",
+          LockConfiguration: {
+            MinRetentionDays: 7,
+            MaxRetentionDays: 365,
+          },
+        },
+      },
+      Plan: {
+        Type: "AWS::Backup::BackupPlan",
+        Properties: {
+          BackupPlan: {
+            BackupPlanName: "application-plan",
+            BackupPlanRule: [
+              {
+                RuleName: "daily",
+                TargetBackupVault: { Ref: "Vault" },
+                ScheduleExpression: "cron(0 1 ? * * *)",
+                Lifecycle: { DeleteAfterDays: 35 },
+              },
+            ],
+          },
+        },
+      },
+      Selection: {
+        Type: "AWS::Backup::BackupSelection",
+        Properties: {
+          BackupPlanId: { Ref: "Plan" },
+          BackupSelection: {
+            SelectionName: "orders",
+            IamRoleArn: "arn:aws:iam::888888888888:role/BackupRole",
+            Resources: ["arn:aws:dynamodb:us-east-1:888888888888:table/orders"],
+          },
+        },
+      },
+    },
+    Outputs: {
+      VaultArn: {
+        Value: { "Fn::GetAtt": ["Vault", "BackupVaultArn"] },
+      },
+      PlanId: { Value: { Ref: "Plan" } },
+      SelectionId: { Value: { Ref: "Selection" } },
+    },
+  },
+});
+
+await stack.waitForDeployComplete();
+
+const selection = await simAws.backup().getBackupSelection(
+  new GetBackupSelectionCommand({
+    BackupPlanId: stack.output("PlanId"),
+    SelectionId: stack.output("SelectionId"),
+  }),
+);
+
+console.log(stack.output("VaultArn"));
+// "arn:aws:backup:us-east-1:888888888888:backup-vault:application-backups"
+console.log(selection.BackupSelection?.SelectionName); // "orders"
+```
+
+`Ref` and `Fn::GetAtt` return these values:
+
+- `AWS::Backup::BackupVault` returns the vault name from `Ref`. `BackupVaultArn` and
+  `BackupVaultName` are available through `Fn::GetAtt`.
+- `AWS::Backup::BackupPlan` returns the plan ID from `Ref`. `BackupPlanArn`, `BackupPlanId` and
+  `VersionId` are available through `Fn::GetAtt`.
+- `AWS::Backup::BackupSelection` returns the selection ID from `Ref`. `Id`, `SelectionId` and
+  `BackupPlanId` are available through `Fn::GetAtt`.
+
+Stack teardown removes all three resource types from the simulation.
+
+## Permissions
+
+Every supported operation is authorized by simulated IAM. Vault operations use the vault ARN. Plan
+and selection operations use the plan ARN. `ListBackupVaults` has no resource in its request and is
+authorized against `*`. `StartBackupJob` and `ListRecoveryPointsByBackupVault` use the vault ARN.
+`DescribeRecoveryPoint` uses the recovery point ARN. Backup job reads use `*`.
+
+```typescript sim-backup-iam-policy
+/**
+ * A Role allowed to create one named backup vault.
+ */
+
+import { CreateBackupVaultCommand } from "@aws-sdk/client-backup";
+import { CreateRoleCommand, PutRolePolicyCommand } from "@aws-sdk/client-iam";
+
+import { SimAws } from "@kensio/yulin";
+
+const simAws = new SimAws();
+const role = await simAws.iam().createRole(
+  new CreateRoleCommand({
+    RoleName: "BackupAdministrator",
+    AssumeRolePolicyDocument: JSON.stringify({
+      Version: "2012-10-17",
+      Statement: {
+        Effect: "Allow",
+        Principal: { AWS: "arn:aws:iam::888888888888:root" },
+        Action: "sts:AssumeRole",
+      },
+    }),
+  }),
+);
+
+await simAws.iam().putRolePolicy(
+  new PutRolePolicyCommand({
+    RoleName: "BackupAdministrator",
+    PolicyName: "CreateApplicationVault",
+    PolicyDocument: JSON.stringify({
+      Version: "2012-10-17",
+      Statement: {
+        Effect: "Allow",
+        Action: "backup:CreateBackupVault",
+        Resource:
+          "arn:aws:backup:us-east-1:888888888888:backup-vault:application-backups",
+      },
+    }),
+  }),
+);
+
+const created = await simAws.backup().createBackupVault(
+  new CreateBackupVaultCommand({
+    BackupVaultName: "application-backups",
+  }),
+  { caller: { kind: "arn", arn: role.Role.Arn } },
+);
+
+console.log(created.BackupVaultName); // "application-backups"
+```
+
+Authorization runs before resource lookup. An unauthorized request for a missing vault or plan
+raises `AccessDeniedException`, without revealing whether the resource exists.
+
+## SDK interception
+
+`SimSdk` routes commands from an AWS `BackupClient` to the simulation. Intercept the client instance
+when a test owns it, or intercept the class when application code creates the client.
+
+```typescript sim-backup-sdk-interception
+/**
+ * Routing an AWS Backup client into the simulation.
+ */
+
+import {
+  BackupClient,
+  CreateBackupVaultCommand,
+  ListBackupVaultsCommand,
+} from "@aws-sdk/client-backup";
+
+import { SimSdk } from "@kensio/yulin/sdk";
+
+using simSdk = new SimSdk();
+const client = new BackupClient({ region: "us-east-1" });
+simSdk.intercept(client);
+
+await client.send(
+  new CreateBackupVaultCommand({ BackupVaultName: "application-backups" }),
+);
+
+const listed = await client.send(new ListBackupVaultsCommand({}));
+console.log(listed.BackupVaultList?.[0]?.BackupVaultName);
+// "application-backups"
+```
+
+The client's configured Region selects the simulated Region. Credentials select the account and
+caller when the intercepted client has them. See the [SDK interception docs](https://yulinsim.dev/sdk/)
+for class interception and credential handling.
+
+## Account and Region scoping
+
+AWS Backup state belongs to one account and Region. The same vault name can exist in another scope.
+
+```typescript sim-backup-account-region-scoping
+/**
+ * Keeping backup vaults inside their account and Region.
+ */
+
+import {
+  CreateBackupVaultCommand,
+  ListBackupVaultsCommand,
+} from "@aws-sdk/client-backup";
+
+import { SimAws } from "@kensio/yulin";
+
+const simAws = new SimAws();
+
+await simAws
+  .account("111111111111")
+  .region("eu-west-2")
+  .backup()
+  .createBackupVault(
+    new CreateBackupVaultCommand({ BackupVaultName: "application-backups" }),
+  );
+
+const inLondon = await simAws
+  .account("111111111111")
+  .region("eu-west-2")
+  .backup()
+  .listBackupVaults(new ListBackupVaultsCommand({}));
+
+const inVirginia = await simAws
+  .account("111111111111")
+  .region("us-east-1")
+  .backup()
+  .listBackupVaults(new ListBackupVaultsCommand({}));
+
+console.log(inLondon.BackupVaultList?.length); // 1
+console.log(inVirginia.BackupVaultList?.length); // 0
+```
+
+## Available functionality
+
+- `CreateBackupVault`, `DescribeBackupVault`, `DeleteBackupVault` and `ListBackupVaults`.
+- `PutBackupVaultLockConfiguration`, including compliance lock grace periods driven by simulated
+  time.
+- `CreateBackupPlan` and `GetBackupPlan`, with rule schedule and lifecycle validation.
+- `CreateBackupSelection`, `GetBackupSelection` and `ListBackupSelections`.
+- Scheduled backup jobs driven by `simAws.clock()` and the plan rule schedule.
+- `StartBackupJob`, `ListBackupJobs` and `DescribeBackupJob`.
+- `ListRecoveryPointsByBackupVault`, `DescribeRecoveryPoint` and
+  `simAws.backup().vault(name).recoveryPoints()`.
+- Recovery point expiry from `DeleteAfterDays` and Vault Lock retention checks.
+- IAM authorization for every supported command.
+- SDK interception of `BackupClient`.
+- Account and Region scoped state, ARNs and timestamps.
+- `AWS::Backup::BackupVault`, `AWS::Backup::BackupPlan` and `AWS::Backup::BackupSelection` through
+  simulated CloudFormation.
+
+## Limitations
+
+- Recovery point copies and restores are outside the simulation.
+- Backup jobs complete immediately at their scheduled or requested simulated instant. Start and
+  completion windows are accepted by the SDK types and ignored by the simulation.
+- Cold-storage lifecycle values are recorded. Recovery points stay in one storage state.
+- Overlapping plan rules are evaluated independently. AWS Backup's overlapping-window optimisation
+  is outside the simulation.
+- Vault deletion removes the vault and its recovery points.
+- A selection stores its `Resources`. `Conditions`, `ListOfTags` and wildcard resource matching are
+  outside the selection model.
+- The selection's `IamRoleArn` is stored. No backup job assumes it, and creating a selection does
+  no `iam:PassRole` check.
+- `EncryptionKeyArn` is stored on a vault. KMS calls and recovery point encryption are outside the
+  simulation.
+- Backup tags are accepted and discarded.
+- List operations return every item. `MaxResults` and `NextToken` do not paginate the result.
+- `GetBackupPlan` returns the one stored plan version. `VersionId` is accepted and ignored. Plan
+  updates are outside the simulation.
+- A compliance lock becomes immutable when its grace period ends. Deleting a lock configuration is
+  unsupported.

package/docs/services/cloudformation/README.md

@@ -3353,7 +3353,7 @@ const stack = await simAws.cloudFormation().deployTemplate({
         Type: "AWS::S3::Bucket",
         Properties: {
           BucketName: "uploads",
-          VersioningConfiguration: { Status: "Enabled" },
+          AccelerateConfiguration: { AccelerationStatus: "Enabled" },
         },
       },
     },
@@ -3362,15 +3362,15 @@ const stack = await simAws.cloudFormation().deployTemplate({
 
 await stack.waitForDeployComplete();
 
-// The Bucket exists and is usable, unversioned.
+// The Bucket exists and is usable, without transfer acceleration.
 console.log(stack.getResource("UploadsBucket")?.deployed);
 // true
 
 for (const ignored of stack.ignoredProperties) {
   console.log(ignored.logicalId, ignored.path, ignored.reason);
-  // "UploadsBucket VersioningConfiguration VersioningConfiguration is a real
-  //  AWS::S3::Bucket property simulated S3 does not act on: Object versions
-  //  are not simulated, ..."
+  // "UploadsBucket AccelerateConfiguration AccelerateConfiguration is a real
+  //  AWS::S3::Bucket property simulated S3 does not act on: transfer
+  //  acceleration is not simulated"
 }
 ```
 
@@ -3393,7 +3393,7 @@ A property name AWS has never had is recorded the same way, and never fails the
 property AWS added after this simulator read the docs look identical from here, and a Resource that
 deploys with the unread name reported is more useful than a stack that fails over either.
 
-Two things are still refused outright, and fail the Resource:
+Three things are still refused outright, and fail the Resource:
 
 - A property that leaves nothing coherent to create, such as an `AWS::S3::Bucket` whose `BucketName`
   is some type other than a string, or an `AWS::DynamoDB::GlobalTable` whose replica list omits the
@@ -3401,6 +3401,16 @@ Two things are still refused outright, and fail the Resource:
 - A value the simulated service itself refuses, in the same words an SDK caller gets. An
   `AWS::SQS::Queue` with `FifoQueue: true` is one. A FIFO queue is named `<name>.fifo`, which
   simulated SQS refuses, leaving no queue to create under the name the template gave it.
+- A value real AWS answers with a 400, on a property that is skipped. Nothing acts on the property
+  either way, and what it says is read far enough to catch a template CloudFormation will reject. A
+  value that passes is recorded like any other skipped property. One that fails takes the Resource
+  with it, before anything is recorded against it. Two properties do this today. An
+  `AWS::S3::Bucket` `ReplicationConfiguration` is checked against the constraints the S3 API
+  documents, covered under
+  [Buckets from CloudFormation](https://yulinsim.dev/services/s3/#buckets-from-cloudformation "Buckets from CloudFormation"),
+  and an `AWS::SQS::Queue` `KmsDataKeyReusePeriodSeconds` against the minute to a day real SQS
+  accepts, covered under
+  [Deploying a queue from CloudFormation](https://yulinsim.dev/services/sqs/#deploying-a-queue-from-cloudformation "Deploying a queue from CloudFormation").
 
 Properties nothing simulated could tell apart are left off the list. There is no simulated KMS and
 Object bytes are stored as they arrive. An `AWS::S3::Bucket` carrying `BucketEncryption` and `Tags`,