@kensio/yulin 1.21.15 → 1.21.17

package/dist/service/secretsmanager/cfn/sim-cfn-secrets-manager-resource-factory.js

@@ -1,51 +1,65 @@
 import { simCfnResourceCallerOptions } from "../../cloudformation/resource/caller/sim-cfn-resource-caller-options.js";
 import { SimCfnSecretsManagerSecretCreator } from "./secret/sim-cfn-secrets-manager-secret-creator.js";
-import { assertDefined } from "../../../util/type-guard/defined.js";
+import { SimCfnSecretsManagerSecretDeleter } from "./secret/sim-cfn-secrets-manager-secret-deleter.js";
+import { SimCfnSecretsManagerSecretUpdater } from "./secret/sim-cfn-secrets-manager-secret-updater.js";
+import { simCfnSecretsManagerSecretReplaced } from "./secret/sim-cfn-secrets-manager-secret-change.js";
+import { isSimCfnSecretsManagerSecret, requireSimCfnSecretsManagerSecret, } from "./sim-cfn-secrets-manager-resource-type.js";
 /**
  * CloudFormation Resource factory for simulated Secrets Manager resources.
+ *
+ * Only `Secret` is deployed. Rotation, resource policies and target
+ * attachments are not simulated, so their Resource types are reported as
+ * unsupported and skipped rather than quietly treated as deployed.
  */
 export class SimSecretsManagerCfnResourceFactory {
-    secretsManager;
     secretCreator;
+    secretUpdater;
+    secretDeleter;
     constructor(properties) {
-        this.secretsManager = properties.secretsManager;
+        const { secretsManager } = properties;
         this.secretCreator = new SimCfnSecretsManagerSecretCreator({
-            secretsManager: properties.secretsManager,
+            secretsManager,
+        });
+        this.secretUpdater = new SimCfnSecretsManagerSecretUpdater({
+            secretsManager,
+        });
+        this.secretDeleter = new SimCfnSecretsManagerSecretDeleter({
+            secretsManager,
         });
     }
     /**
      * Create a simulated Secrets Manager resource from a CloudFormation
      * Resource.
-     *
-     * Rotation, resource policies and target attachments are not simulated, so
-     * their Resource types are reported as unsupported and skipped rather than
-     * quietly treated as deployed.
      */
     async create(resourceTypeName, resource, context) {
-        switch (resourceTypeName) {
-            case "Secret": {
-                return await this.secretCreator.create(resource, context.resolvedProperties ?? resource.properties, simCfnResourceCallerOptions(context.caller));
-            }
-            default: {
-                throw new Error(`Unsupported sim Secrets Manager CloudFormation Resource ${resourceTypeName}`);
-            }
-        }
+        requireSimCfnSecretsManagerSecret(resourceTypeName);
+        return await this.secretCreator.create(resource, context.resolvedProperties ?? resource.properties, simCfnResourceCallerOptions(context.caller));
+    }
+    /**
+     * Whether a changed secret can be applied to the deployed one.
+     *
+     * Name is the only property real CloudFormation replaces a secret for.
+     * Everything else is applied with no interruption, which is what keeps a
+     * generated value across a change to the secret's description or tags.
+     */
+    updatesInPlace(resourceTypeName, current, updated) {
+        return (isSimCfnSecretsManagerSecret(resourceTypeName) &&
+            !simCfnSecretsManagerSecretReplaced(current, updated));
+    }
+    /**
+     * Apply a changed AWS::SecretsManager::Secret Resource to the deployed
+     * secret.
+     */
+    async updateInPlace(resourceTypeName, current, updated, context) {
+        requireSimCfnSecretsManagerSecret(resourceTypeName, "update");
+        return await this.secretUpdater.update(current, updated, context);
     }
     /**
      * Delete a simulated Secrets Manager resource created from a CloudFormation
      * Resource.
-     *
-     * DeleteSecret schedules the deletion rather than carrying it out, so a torn
-     * down Stack leaves a secret waiting out its recovery window. That is what
-     * CloudFormation does: the secret is recoverable afterwards, which is the
-     * point of the window.
      */
     async delete(resourceTypeName, resource, context) {
-        if (resourceTypeName !== "Secret") {
-            throw new Error(`Unsupported sim Secrets Manager CloudFormation Resource ${resourceTypeName} deletion`);
-        }
-        const secret = resource.simResource;
-        assertDefined(secret, `sim Secrets Manager secret for CloudFormation Resource ${resource.logicalId}`);
-        await this.secretsManager.deleteSecret({ input: { SecretId: secret.arn.value } }, simCfnResourceCallerOptions(context.caller));
+        requireSimCfnSecretsManagerSecret(resourceTypeName, "deletion");
+        await this.secretDeleter.delete(resource, simCfnResourceCallerOptions(context.caller));
     }
 }

package/dist/service/secretsmanager/cfn/sim-cfn-secrets-manager-resource-type.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Whether a Resource type name is the secret this simulation deploys.
+ */
+export declare function isSimCfnSecretsManagerSecret(resourceTypeName: string): boolean;
+/**
+ * Refuse an operation on a Resource type this simulation does not deploy.
+ *
+ * The refusal reads as an unsupported Resource, so the Stack records it and
+ * carries on rather than failing. Creation names no operation, since a
+ * Resource type nothing creates is the plain case a reader meets first.
+ */
+export declare function requireSimCfnSecretsManagerSecret(resourceTypeName: string, operation?: string): void;

package/dist/service/secretsmanager/cfn/sim-cfn-secrets-manager-resource-type.js

@@ -0,0 +1,22 @@
+/** The one AWS::SecretsManager::* Resource type this simulation deploys. */
+const secretResourceTypeName = "Secret";
+/**
+ * Whether a Resource type name is the secret this simulation deploys.
+ */
+export function isSimCfnSecretsManagerSecret(resourceTypeName) {
+    return resourceTypeName === secretResourceTypeName;
+}
+/**
+ * Refuse an operation on a Resource type this simulation does not deploy.
+ *
+ * The refusal reads as an unsupported Resource, so the Stack records it and
+ * carries on rather than failing. Creation names no operation, since a
+ * Resource type nothing creates is the plain case a reader meets first.
+ */
+export function requireSimCfnSecretsManagerSecret(resourceTypeName, operation) {
+    if (isSimCfnSecretsManagerSecret(resourceTypeName)) {
+        return;
+    }
+    const refused = operation === undefined ? "" : ` ${operation}`;
+    throw new Error(`Unsupported sim Secrets Manager CloudFormation Resource ${resourceTypeName}${refused}`);
+}

package/docs/sdk/README.md

@@ -282,7 +282,8 @@ service throws `SimSdkUnknownServiceError`.
 - Simulated errors have SDK-shaped `name` and `$metadata` fields. They are separate classes from the
   SDK exceptions, so match them by `error.name` instead of `instanceof`.
 - The callback form of `send(command, callback)` is not supported. Use the promise form.
-- Yulin ignores the translation options in
-  `DynamoDBDocumentClient.from(client, { marshallOptions, unmarshallOptions })`. The conversion uses
-  the defaults. `removeUndefinedValues: true` has no effect. Yulin refuses an `undefined` attribute
-  that the configured document client would otherwise remove.
+- Yulin reads the `marshallOptions` in
+  `DynamoDBDocumentClient.from(client, { marshallOptions, unmarshallOptions })` and ignores the
+  `unmarshallOptions`. A stored value comes back the way a document client built with no options of
+  its own reads it. See
+  [the DynamoDB docs](https://yulinsim.dev/services/dynamodb/#marshalling-options).

package/docs/services/cloudformation/README.md

@@ -446,6 +446,22 @@ Replacement also affects dependencies and retention policies:
   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.
 
+### Resources a service changes where they are
+
+A service can claim a change for the properties real CloudFormation applies with no interruption.
+The resource is then left where it is. It keeps its physical name and everything it holds, and
+every resource naming it is left standing too.
+
+`AWS::SecretsManager::Secret` is the one resource type that does this so far. `Name` is the only
+property real CloudFormation replaces a secret for. A change to anything else is applied to the
+deployed secret, which keeps its ARN and its versions across the update. See the
+[simulated Secrets Manager docs](https://yulinsim.dev/services/secretsmanager/ "Simulated Secrets Manager usage docs")
+for which changes write a new secret version and which leave the value alone.
+
+These changes are applied first, while everything the stack had is still deployed. An update that
+fails on one has deleted nothing yet. A claimed resource the replacement spread reaches is replaced
+after all, and the claim is taken back, since its dependency is being deleted and created again.
+
 ### Rolling back a failed update
 
 A failed update is rolled back onto the template the stack was deployed from. The stack moves to
@@ -4393,13 +4409,15 @@ Each service's own docs describe what its resource types support.
   [properties a Resource was created without](#properties-a-resource-was-created-without) for what
   is still refused outright.
 - A stack update replaces a changed resource rather than updating it in place, so what the resource
-  held is lost. See [changed resources are replaced](#changed-resources-are-replaced).
+  held is lost. `AWS::SecretsManager::Secret` is the exception. See
+  [changed resources are replaced](#changed-resources-are-replaced) and
+  [resources a service changes where they are](#resources-a-service-changes-where-they-are).
 - A watched template file updates its stack in place. That makes the update itself no gentler. A
   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 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
+- A change set reports every `Modify` as `Replacement: True`, even for a resource an update would
+  change where it is. `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

package/docs/services/dynamodb/README.md

@@ -3040,6 +3040,84 @@ Intercept the document client itself. `DynamoDBDocumentClient.from(client)` buil
 outside the `DynamoDBClient` class, so intercepting the base client leaves Commands sent through the
 document one untouched. See [the SDK docs](https://yulinsim.dev/sdk/#the-dynamodb-document-client).
 
+### Marshalling options
+
+`DynamoDBDocumentClient.from(client, { marshallOptions })` changes what the conversion does with a
+value the defaults refuse. Yulin reads those options off the client each Command was sent through.
+Two document clients over one simulation each convert by their own.
+
+- `removeUndefinedValues` drops an `undefined` out of a map, a list or a `Set`. Without it, an
+  `undefined` in any of the three is refused. The real client refuses it in the same place.
+- `convertEmptyValues` writes an empty string, an empty binary value and an empty `Set` as `NULL`.
+- `convertClassInstanceToMap` reads an object with behaviour as a map of its own properties.
+- `allowImpreciseNumbers` writes a number past `Number.MAX_SAFE_INTEGER` with the digits it has
+  already been rounded to.
+
+An `undefined` attribute of an item, a key or a set of expression values is left out whatever the
+client was built with. `removeUndefinedValues` governs the values held inside an attribute, and the
+attributes of an item sit a level above that (the real client drops an undefined one there without
+being asked to).
+
+```typescript sim-dynamodb-document-marshall-options
+/**
+ * Writing a partly filled object through a document client that drops
+ * undefined values.
+ */
+
+import { CreateTableCommand, DynamoDBClient } from "@aws-sdk/client-dynamodb";
+import {
+  DynamoDBDocumentClient,
+  GetCommand,
+  PutCommand,
+} from "@aws-sdk/lib-dynamodb";
+
+import { SimSdk } from "@kensio/yulin/sdk";
+
+using simSdk = new SimSdk();
+
+const documents = DynamoDBDocumentClient.from(
+  new DynamoDBClient({ region: "eu-west-2" }),
+  { marshallOptions: { removeUndefinedValues: true } },
+);
+simSdk.intercept(documents);
+
+await documents.send(
+  new CreateTableCommand({
+    TableName: "PagesTable",
+    KeySchema: [{ AttributeName: "pageId", KeyType: "HASH" }],
+    AttributeDefinitions: [{ AttributeName: "pageId", AttributeType: "S" }],
+    BillingMode: "PAY_PER_REQUEST",
+  }),
+);
+await simSdk.simAws.backgroundTasksComplete();
+
+// The summary was never filled in, and one section is still to be written.
+await documents.send(
+  new PutCommand({
+    TableName: "PagesTable",
+    Item: {
+      pageId: "page-1",
+      meta: { title: "Home", summary: undefined },
+      sections: ["intro", undefined, "outro"],
+    },
+  }),
+);
+
+const read = await documents.send(
+  new GetCommand({ TableName: "PagesTable", Key: { pageId: "page-1" } }),
+);
+
+const meta = read.Item?.["meta"] as Record<string, string>;
+console.log(Object.keys(meta)); // [ 'title' ]
+
+// A dropped member takes its position with it.
+const sections = read.Item?.["sections"] as string[];
+console.log(sections); // [ 'intro', 'outro' ]
+```
+
+`unmarshallOptions` are ignored. A stored value comes back the way a document client built with no
+options of its own reads it.
+
 ### Querying and scanning through the document client
 
 `@aws-sdk/lib-dynamodb` names its `QueryCommand` and `ScanCommand` exactly as
@@ -3152,8 +3230,9 @@ A simulated table holds a number's digits exactly, but the document client conve
 JavaScript numbers, and that is where digits are lost. It is the same loss AWS has. A test that
 passes here is telling you something true about the real thing.
 
-- Writing a `number` outside the safe integer range is refused, never stored already rounded. Write
-  a `bigint`, or a `NumberValue` from `@aws-sdk/lib-dynamodb`, to keep the digits.
+- Writing a `number` outside the safe integer range is refused unless the client was built with
+  `allowImpreciseNumbers`. Write a `bigint`, or a `NumberValue` from `@aws-sdk/lib-dynamodb`, to keep
+  the digits.
 - Reading a stored number outside the safe integer range gives a `bigint`.
 - Reading a stored decimal with more digits than a JavaScript number carries gives a rounded
   `number`. The table still holds every digit, and the rounding is the document client's. Read

package/docs/services/secretsmanager/README.md

@@ -428,6 +428,37 @@ console.log(credentials.password?.length); // 24
 Generated passwords are random. Read the deployed value through Secrets Manager instead of asserting
 on an exact password.
 
+## Updating a deployed secret
+
+`Name` is the only property real CloudFormation replaces a secret for. A stack update that changes
+anything else applies it to the deployed secret, which keeps its ARN and its versions.
+
+A change to the description, the tags or the KMS key leaves the value alone. That is what carries a
+generated password across an update, and it keeps a resource that read the secret as the stack
+deployed, such as a CloudFront origin custom header, holding the value the secret still has.
+
+A new version is written when the template asks for a different value, which is a changed
+`SecretString` or a changed `GenerateSecretString`. A changed `GenerateSecretString` generates a new
+password, as real CloudFormation writes a new version for one. **A resource that resolved the old
+value keeps it.** Its own template entry is unchanged, so the update leaves it alone, and it goes on
+holding what it read at deploy time. A consumer that has to follow the value must read the secret
+when it runs, the way a Lambda function given the secret's ARN does, rather than take a copy through
+a `{{resolve:secretsmanager:...}}` reference.
+
+The template is the desired state. A property the new template leaves out is cleared. A dropped
+`Description` is emptied, and a dropped `KmsKeyId` puts the secret back on the `aws/secretsmanager`
+key. Versions already written keep the key they were made with and stay
+readable.
+
+Changing the `Name` replaces the secret. The new one is created under the new name and the old one
+is scheduled for deletion, waiting out its recovery window.
+
+A secret is also replaced when a resource it names is replaced, because the update deletes and
+recreates that resource and the secret would otherwise be applied against the one on its way out.
+That replacement then fails, since the name is held for the recovery window. Real CloudFormation
+updates the secret in place and hands it the new physical name. Nothing is applied to the deployed
+secret before the failure.
+
 ## Reading a secret with a dynamic reference
 
 A `{{resolve:secretsmanager:...}}` dynamic reference reads an existing secret while CloudFormation
@@ -641,7 +672,10 @@ code into the simulation, served in process. See
   empty page.
 - Tags are stored and reported by `DescribeSecret` and `ListSecrets`, but `TagResource` and
   `UntagResource` are absent, and the `secretsmanager:ResourceTag` and `aws:ResourceTag` condition
-  keys are left underived.
+  keys are left underived. A stack update applies the tags its template declares to the deployed
+  secret, since there is no command to ask for it with.
+- A stack update authorizes the whole change as `secretsmanager:UpdateSecret`. Real CloudFormation
+  needs `secretsmanager:TagResource` as well for a change to the tags.
 - Other Secrets Manager condition keys, such as `secretsmanager:SecretId` and
   `secretsmanager:VersionStage`, are left underived too, and a policy relying on them fails to match.
   Ordinary condition operators on values sim IAM does supply work as usual.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kensio/yulin",
-  "version": "1.21.15",
+  "version": "1.21.17",
   "description": "AWS system behaviour simulation for isolated unit testing",
   "repository": "https://github.com/KensioSoftware/yulin",
   "homepage": "https://yulinsim.dev/",

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

@@ -1,21 +0,0 @@
-import type { SimCfnResource } from "../../resource/sim-cfn-resource.js";
-interface SimCfnStackReplacedResourcesProperties {
-    readonly current: ReadonlyMap<string, SimCfnResource>;
-    readonly updated: ReadonlyMap<string, SimCfnResource>;
-}
-/**
- * The logical IDs an update has to replace, given the Stack's deployed
- * Resources and the ones its new template describes.
- *
- * A Resource is replaced when its resolved template entry changed. Sim
- * CloudFormation has no in-place update, so replacement means deleting the
- * Resource and creating it again from the new template.
- *
- * A Resource that names a replaced Resource is replaced too, all the way up the
- * dependency chain. Real CloudFormation hands the dependent the new physical
- * name instead, but nothing here can rewrite an already created simulated
- * Resource, and leaving the dependent alone would leave it pointing at a
- * Resource that has gone.
- */
-export declare function simCfnStackReplacedLogicalIds(properties: SimCfnStackReplacedResourcesProperties): ReadonlySet<string>;
-export {};

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

@@ -1,51 +0,0 @@
-import { simCfnTemplateSignature } from "./sim-cfn-template-signature.js";
-/**
- * The logical IDs an update has to replace, given the Stack's deployed
- * Resources and the ones its new template describes.
- *
- * A Resource is replaced when its resolved template entry changed. Sim
- * CloudFormation has no in-place update, so replacement means deleting the
- * Resource and creating it again from the new template.
- *
- * A Resource that names a replaced Resource is replaced too, all the way up the
- * dependency chain. Real CloudFormation hands the dependent the new physical
- * name instead, but nothing here can rewrite an already created simulated
- * Resource, and leaving the dependent alone would leave it pointing at a
- * Resource that has gone.
- */
-export function simCfnStackReplacedLogicalIds(properties) {
-    const { current, updated } = properties;
-    const replaced = changedLogicalIds({ current, updated });
-    // Each pass replaces the Resources naming one already being replaced, until a
-    // pass finds none, which is the end of the dependency chain.
-    let spreading = true;
-    while (spreading) {
-        spreading = false;
-        for (const [logicalId, resource] of updated) {
-            const spreads = current.has(logicalId) &&
-                !replaced.has(logicalId) &&
-                resource.dependencies().some((dependency) => replaced.has(dependency));
-            if (spreads) {
-                replaced.add(logicalId);
-                spreading = true;
-            }
-        }
-    }
-    return replaced;
-}
-/**
- * The logical IDs whose resolved template entry differs from the deployed one.
- */
-function changedLogicalIds(properties) {
-    const { current, updated } = properties;
-    const changed = new Set();
-    for (const [logicalId, resource] of updated) {
-        const deployed = current.get(logicalId);
-        if (deployed !== undefined &&
-            simCfnTemplateSignature(deployed.template) !==
-                simCfnTemplateSignature(resource.template)) {
-            changed.add(logicalId);
-        }
-    }
-    return changed;
-}