@kensio/yulin 1.21.7 → 1.21.9

package/dist/service/lambda/event-source/sim-lambda-stream-destination-config.js

@@ -0,0 +1,38 @@
+import { isRecord } from "../../../util/type-guard/record.js";
+import { SimLambdaDestinationArn } from "../destination/sim-lambda-destination-arn.js";
+import { SimLambdaInvalidParameterValueException } from "../error/sim-lambda.error.js";
+/** Validate the same destination shape for SDK and CloudFormation requests. */
+export function simLambdaStreamDestinationConfig(value, sourceKind) {
+    if (value === undefined)
+        return undefined;
+    if (sourceKind === "sqs") {
+        throw new SimLambdaInvalidParameterValueException("DestinationConfig is not supported for SQS event source mappings.");
+    }
+    if (!isRecord(value) ||
+        Object.keys(value).some((key) => key !== "OnFailure")) {
+        throw invalid();
+    }
+    const failure = value["OnFailure"];
+    if (failure === undefined)
+        return {};
+    if (!isRecord(failure) ||
+        Object.keys(failure).some((key) => key !== "Destination")) {
+        throw invalid();
+    }
+    const destination = failure["Destination"];
+    if (destination === undefined)
+        return { OnFailure: {} };
+    if (typeof destination !== "string")
+        throw invalid();
+    if (destination !== "") {
+        const arn = SimLambdaDestinationArn.of(destination);
+        if ((arn.service !== "sqs" && arn.service !== "sns") ||
+            arn.resource.endsWith(".fifo")) {
+            throw invalid();
+        }
+    }
+    return { OnFailure: { Destination: destination } };
+}
+function invalid() {
+    return new SimLambdaInvalidParameterValueException("DestinationConfig supports only OnFailure with a standard SQS queue or SNS topic ARN.");
+}

package/dist/service/lambda/event-source/stream/kinesis/sim-kinesis-event-source-streams.js

@@ -40,6 +40,7 @@ export class SimKinesisEventSourceStreams {
         }, { caller });
         return {
             records: output.Records,
+            shardId: request.shardId,
             next: { kind: "iterator", shardIterator: output.NextShardIterator },
             drained: false,
         };

package/dist/service/lambda/event-source/stream/sim-dynamodb-event-source-stream-reader.js

@@ -29,6 +29,7 @@ export class SimDynamoDbEventSourceStreamReader {
         const next = output.NextShardIterator;
         return {
             records: output.Records ?? [],
+            shardId: await this.shard.shardId(request),
             next: simDynamoDbEventSourceNextPosition(next, position),
             drained: next === undefined,
         };

package/dist/service/lambda/event-source/stream/sim-dynamodb-event-source-stream-shard.d.ts

@@ -23,5 +23,6 @@ export declare class SimDynamoDbEventSourceStreamShard {
      * is the shard.
      */
     iteratorFor(request: SimLambdaEventSourceStreamRequest, position: SimLambdaEventSourceStreamNamedPosition): Promise<string>;
+    shardId(request: SimLambdaEventSourceStreamRequest): Promise<string>;
     private describe;
 }

package/dist/service/lambda/event-source/stream/sim-dynamodb-event-source-stream-shard.js

@@ -49,6 +49,13 @@ export class SimDynamoDbEventSourceStreamShard {
         }
         return iterator.ShardIterator;
     }
+    async shardId(request) {
+        const description = await this.describe(request);
+        const shardId = description.Shards?.[0]?.ShardId;
+        if (shardId === undefined)
+            refuse(request, "reports no shard to read records from");
+        return shardId;
+    }
     async describe(request) {
         const { caller, streamArn } = request;
         const described = await this.commands.describeStream({ input: { StreamArn: streamArn } }, { caller });

package/dist/service/lambda/event-source/stream/sim-lambda-event-source-streams.d.ts

@@ -84,6 +84,7 @@ export interface SimLambdaEventSourceStreamReadRequest extends SimLambdaEventSou
 export interface SimLambdaEventSourceStreamProgressBatch {
     readonly next: SimLambdaEventSourceStreamPosition;
     readonly drained: boolean;
+    readonly shardId?: string;
 }
 /**
  * What one read of a DynamoDB stream came back with.

package/dist/service/lambda/index.d.ts

@@ -16,3 +16,4 @@ export type { SimLambdaDynamoDbAttributeValue, SimLambdaDynamoDbImage, } from ".
 export { SimLambdaStreamCascadeError } from "./event-source/stream/sim-lambda-stream-cascade.error.js";
 export type { SimLambdaDestinationRecord, SimLambdaDestinationRequestContext, SimLambdaDestinationResponseContext, } from "./destination/sim-lambda-destination-record.js";
 export type { SimLambdaInvocationCondition } from "./function/event-invoke/sim-lambda-event-invoke-config.js";
+export type { SimLambdaStreamFailureRecord, SimLambdaStreamFailureCondition, } from "./event-source/poll/sim-lambda-stream-failure-record.js";

package/dist/service/lambda/sim-lambda-commands.js

@@ -113,6 +113,7 @@ export class SimLambdaCommands {
             background,
         });
         this.eventSourceMappings = new SimLambdaEventSourceMappingCommands({
+            destinations,
             accountRegionScope,
             pollers: new SimLambdaEventSourcePollers({
                 functions: this.functionLookup,

package/dist/service/ses/command/authorize/sim-ses-authorizer.d.ts

@@ -30,6 +30,15 @@ export declare class SimSesAuthorizer {
      * ARN the identity is about to have.
      */
     authorizeIdentity(action: string, emailIdentity: string, caller?: SimAwsCaller): SimAwsResolvedCaller;
+    /**
+     * Ensure the caller may send from one email identity and address.
+     *
+     * SES supplies the bare sender address as `ses:FromAddress`. A policy can
+     * use this key to grant one address under a verified domain identity.
+     *
+     * https://docs.aws.amazon.com/ses/latest/dg/sending-authorization-policy-examples.html#sending-authorization-policy-example-from
+     */
+    authorizeSendEmail(emailIdentity: string, fromAddress: string, caller?: SimAwsCaller): SimAwsResolvedCaller;
     /**
      * Ensure the caller may perform an action on one email template.
      *

package/dist/service/ses/command/authorize/sim-ses-authorizer.js

@@ -40,6 +40,17 @@ export class SimSesAuthorizer {
     authorizeIdentity(action, emailIdentity, caller) {
         return this.authorizeResource(action, simSesIdentityArn(this.#accountRegionScope, emailIdentity), caller);
     }
+    /**
+     * Ensure the caller may send from one email identity and address.
+     *
+     * SES supplies the bare sender address as `ses:FromAddress`. A policy can
+     * use this key to grant one address under a verified domain identity.
+     *
+     * https://docs.aws.amazon.com/ses/latest/dg/sending-authorization-policy-examples.html#sending-authorization-policy-example-from
+     */
+    authorizeSendEmail(emailIdentity, fromAddress, caller) {
+        return this.authorizeResource("ses:SendEmail", simSesIdentityArn(this.#accountRegionScope, emailIdentity), caller, { "ses:FromAddress": fromAddress });
+    }
     /**
      * Ensure the caller may perform an action on one email template.
      *
@@ -73,8 +84,13 @@ export class SimSesAuthorizer {
     authorizeNoResource(action, caller) {
         return this.authorizeResource(action, noResource, caller);
     }
-    authorizeResource(action, resource, caller) {
-        const decision = this.#iam.authorize({ action, resource, caller });
+    authorizeResource(action, resource, caller, conditionContext) {
+        const decision = this.#iam.authorize({
+            action,
+            resource,
+            caller,
+            conditionContext,
+        });
         if (decision.isDenied) {
             throw new SimIamAccessDenied({
                 principal: decision.caller.principal,

package/dist/service/ses/command/send/sim-ses-send-email.js

@@ -42,8 +42,9 @@ export class SimSesSendEmail {
     handle(command, options) {
         const input = command.input;
         const fromEmailAddress = requiredSimSesFromAddress(input.FromEmailAddress);
+        const bareFromAddress = simSesBareAddress(fromEmailAddress);
         refuseUnsimulatedSendInput(input);
-        this.#authorizer.authorizeIdentity("ses:SendEmail", this.#identities.covering(simSesBareAddress(fromEmailAddress)), options?.caller);
+        this.#authorizer.authorizeSendEmail(this.#identities.covering(bareFromAddress), bareFromAddress, options?.caller);
         const destination = readDestination(input.Destination);
         const recipients = allRecipients(destination);
         if (recipients.length === 0) {

package/docs/README.md

@@ -15,6 +15,12 @@ npm install --save-dev @kensio/yulin
 
 ## Choose how to use Yulin
 
+Start with [test suite setup](https://yulinsim.dev/testing/) when adding Yulin to an application's
+tests. Create one simulated environment, deploy the application's infrastructure, and install SDK
+interception for the whole suite. Tests then use that shared environment as they would use an AWS
+account or a container-based simulator. Put the smaller set of tests that control simulated time in
+an isolated group because the clock belongs to the environment too.
+
 Start with [AWS SDK interception](https://yulinsim.dev/sdk/) when the code under test already uses an
 AWS SDK client. Yulin intercepts the client's `send` calls and returns responses from a simulated
 service. The application code continues to use the AWS SDK normally.
@@ -81,4 +87,5 @@ credential, or run other work that depends on time passing.
 - [Non-AWS dependencies](https://yulinsim.dev/non-aws-dependencies/ "Dependencies Yulin does not simulate usage docs")
 - [Serving on localhost](https://yulinsim.dev/serve/ "Serving simulated AWS on localhost usage docs")
 - [Simulated time](https://yulinsim.dev/time/ "Simulated time usage docs")
+- [Test suite setup](https://yulinsim.dev/testing/ "Sharing one Yulin environment across a test suite")
 - [Terraform](https://yulinsim.dev/terraform/ "Deploying Terraform into simulated AWS usage docs")

package/docs/ai-skill/README.md

@@ -37,10 +37,15 @@ The skill tells an agent how to:
 - control simulated time
 - inspect simulated state in assertions
 - match simulated service errors by `name`
-- share an expensive deployment across tests in one file
+- share one simulated deployment and SDK interception across a whole test suite
+- give tests that control simulated time their own isolated Yulin environment
 - invoke code through a simulated Lambda function with its configured role and environment
 - treat unsupported behaviour as a gap to report, not behaviour to guess
 
+The [test suite setup guide](https://yulinsim.dev/testing/) states the default explicitly. An agent
+should set Yulin up once for the suite and let tests share it as they would share an AWS account or a
+container-based simulator. Tests that move the shared simulated clock are the main exception.
+
 ## Give the agent access to the API docs
 
 The skill covers testing choices. The service guides document Yulin's APIs and supported AWS

package/docs/sdk/README.md

@@ -3,6 +3,18 @@
 `SimSdk` routes AWS SDK for JavaScript v3 commands to Yulin. Use it to test code that already sends
 commands through AWS SDK clients.
 
+## Install interception in suite setup
+
+Application tests should normally create one `SimSdk` in Vitest suite setup and keep its class
+interceptions installed for the whole suite. Every SDK client then reaches the same simulated state,
+including clients created in different test files.
+
+The [test suite setup guide](https://yulinsim.dev/testing/) shows how to share one in-process
+environment across Vitest files. It also covers the worker and isolation settings this requires.
+A separate `SimSdk` for each test or file remains supported when a case needs an empty environment.
+Tests that control the simulation's clock should use a separate `SimSdk` so their time changes cannot
+affect the shared suite.
+
 ## Intercept a client
 
 Create a `SimSdk`, intercept a client class, and run the code under test:
@@ -147,6 +159,9 @@ Restore an interception before later code needs the client's original `send` met
 - Call `simSdk.restoreAll()` to restore every client intercepted by that `SimSdk`.
 - Declare `SimSdk` or an interception handle with `using` to restore it when the scope ends.
 
+A suite-wide interception stays installed until the test worker exits. Do not restore it in a
+per-file `afterAll`, since later files use the same interception and simulated state.
+
 ## Limit the intercepted commands
 
 An interception handles every command by default. Pass an allow list when a test should accept only

package/docs/services/acm/README.md

@@ -1,8 +1,8 @@
 # Simulated ACM
 
-Yulin includes a simulated AWS Certificate Manager (ACM) for tests and local development. In this
-guide, you'll request certificates, configure DNS validation, filter certificate lists, and use ACM
-with simulated CloudFormation.
+Yulin simulates AWS Certificate Manager (ACM) in memory. You can request and inspect certificates,
+exercise DNS validation against simulated Route53, and deploy certificate resources through
+simulated CloudFormation.
 
 ## Prerequisites
 
@@ -12,9 +12,8 @@ with simulated CloudFormation.
 
 ## Request a certificate
 
-1. Create a `SimAws` instance and get a simulated ACM client.
-2. Call `requestCertificate` with a `RequestCertificateCommand`.
-3. Call `listCertificates` with a `ListCertificatesCommand` to confirm the certificate exists.
+Create a `SimAws` instance, request a certificate, then list the certificates in that account and
+region:
 
 ```typescript sim-acm-request-certificate
 /**
@@ -145,9 +144,8 @@ for (const validation of domainValidationOptions) {
 }
 ```
 
-For DNS validation, simulated ACM returns CNAME validation records for the primary domain and each
-subject alternative name. The records are deterministic, which makes them suitable for assertions in
-tests.
+For DNS validation, ACM returns a deterministic CNAME record for the primary domain and each subject
+alternative name. Tests can assert on these records directly.
 
 For EMAIL validation, the validation method is recorded but no DNS resource record is returned.
 
@@ -187,11 +185,8 @@ console.log(validation?.ResourceRecord);
 
 ## Wait for certificate issuance
 
-Requested certificates start in `PENDING_VALIDATION` status. Simulated ACM schedules background work
-to move them to `ISSUED`.
-
-If your test needs the issued state, wait for background tasks to complete before describing the
-certificate.
+Requested certificates start as `PENDING_VALIDATION`. Wait for background tasks before asserting
+that a certificate is `ISSUED`.
 
 > **Note:** Where a simulated Route53 hosted zone covers the certificate domain, issuance waits for
 > DNS validation first.
@@ -233,19 +228,14 @@ console.log(describeOutput.Certificate?.IssuedAt);
 
 ## Validate a certificate against simulated Route53
 
-Real ACM issues a DNS-validated certificate only once the CNAME it requests is resolvable. Simulated
-ACM does the same, but only where the simulation can answer for the domain.
-
-By default, the rules are:
+ACM requires the validation CNAME when simulated Route53 is authoritative for the domain. The
+default rules are:
 
 - If a simulated Route53 hosted zone covers the certificate domain, the certificate waits for its validation record.
 - If no hosted zone covers the domain, the certificate is issued as soon as background tasks drain.
 
-Templates commonly reference hosted zones managed by another team or another tool. Those
-certificates keep working here because the simulation holds no zone for their domain.
-
-[Two methods override that default](#override-when-validation-is-required) where it doesn't suit
-your test.
+This lets templates refer to externally managed hosted zones without leaving certificates pending.
+[Two methods override the default](#override-when-validation-is-required).
 
 ```typescript sim-acm-dns-validation
 /**
@@ -322,11 +312,9 @@ const issuedOutput = await simAws.acm().describeCertificate(
 console.log(issuedOutput.Certificate?.Status); // ISSUED
 ```
 
-Each domain on a certificate is validated separately. A certificate with subject alternative names
-is issued only once every domain that needs DNS validation has its record. Domains that are not
-covered by any hosted zone don't need anything published for them. Until all domains are validated,
-`DescribeCertificateCommand` reports `SUCCESS` for validated domains and `PENDING_VALIDATION` for
-the rest.
+Each domain is validated separately. A certificate is issued when every domain covered by a
+simulated hosted zone has its validation record. `DescribeCertificateCommand` reports `SUCCESS` for
+validated domains and `PENDING_VALIDATION` for the rest.
 
 Hosted zones are looked up across every simulated account, matching real ACM validating against
 public DNS. A certificate in one account can be validated by a hosted zone in another.
@@ -554,18 +542,16 @@ await scopedAcm.requestCertificate(
 );
 ```
 
-Each `SimAws` instance has its own isolated state. Create a fresh instance per test or share one across related local setup.
+Each `SimAws` instance has its own isolated state. Application tests should normally use the instance
+from their shared [test suite setup](https://yulinsim.dev/testing/). A fresh instance remains useful
+when a test specifically needs an empty simulated account.
 
 ## Register a certificate with a chosen ARN
 
-`RequestCertificateCommand` allocates its own certificate ARN, as real ACM does, and takes none from
-you. When something else already decided the ARN, register the certificate as part of your test setup
-instead.
-
-The usual reason is a CDK app that creates its certificate in one stack and uses it in another. The
-ARN crosses between the two as a plain string, and the stack using it carries that ARN into its
-synthesized template. Simulated CloudFront checks the certificate before it creates a Distribution,
-so registering the certificate first lets the template deploy as it is, with no rewriting.
+`RequestCertificateCommand` allocates the ARN. If a fixture or another stack already provides the
+ARN, register that certificate during test setup. This is useful when one CDK stack creates a
+certificate and another uses its ARN. Simulated CloudFront can then resolve the certificate without
+changing the synthesized template.
 
 ```typescript sim-acm-register-certificate
 /**
@@ -791,9 +777,7 @@ A `HostedZoneId` that names a hosted zone the simulator doesn't hold is skipped
 
 If a hosted zone covers the domain but the validation record never appears, the stack fails rather than hanging. Real CloudFormation sits in `CREATE_IN_PROGRESS` for hours before timing out, which is of little use in a test. The resource fails immediately and names the record it waited for.
 
-## Available functionality
-
-Simulated ACM supports:
+## Supported operations
 
 - `RequestCertificateCommand`, `DescribeCertificateCommand`, and `ListCertificatesCommand`
 - DNS validation against records in simulated Route53