@kensio/yulin 1.21.6 → 1.21.8

package/docs/services/wafv2/README.md

@@ -1,16 +1,11 @@
 # Simulated WAFv2
 
-Yulin includes a simulated AWS WAFv2 for tests and local development. It holds web ACLs, IP sets and
-regex pattern sets, and it evaluates a request against a web ACL's rules to reach a decision. A test
-can assert that a request to `/admin` is blocked and one to `/` is allowed, without an AWS account
-and without a distribution in front of anything.
+Yulin simulates AWS WAFv2 web ACLs, IP sets and regex pattern sets for tests and local development.
+You can evaluate a `Request` directly or associate a web ACL with a simulated API Gateway REST API,
+Cognito user pool or CloudFront distribution. Each request is checked against the web ACL before
+the protected service handles it.
 
-A web ACL can also go in front of what serves the requests. A simulated API Gateway REST API stage
-and a simulated Cognito user pool each take one through `AssociateWebACL`, and a simulated
-CloudFront distribution takes one through its own `WebACLId`. The requests that stage, pool or
-distribution serves are then put through the web ACL's rules.
-
-WAFv2 specific types are imported from the `@kensio/yulin/wafv2` subpath.
+Import WAFv2-specific types from `@kensio/yulin/wafv2`.
 
 ## Deciding what happens to a request
 
@@ -91,11 +86,11 @@ carrying the status, the body and any headers the rule named.
 
 ## Rules run in priority order
 
-Rules are evaluated in ascending `Priority` and not in the order the list was written. The first
-rule that matches and carries a terminating action (`Allow` or `Block`) decides the request.
+Rules are evaluated by ascending `Priority`, regardless of their order in the input list. The first
+matching rule with an `Allow` or `Block` action decides the request.
 
-A `Count` action records the match and lets the next rule have a look. That is how a rule is staged
-before it is turned on, and `countedRuleNames` is what a test asserts against.
+A `Count` action records the match and continues to the next rule. Tests can inspect
+`countedRuleNames` before changing a rule to `Allow` or `Block`.
 
 ```typescript sim-wafv2-count
 /**
@@ -154,8 +149,8 @@ whatever serves the request has usually read it by the time WAF gets a look.
 
 ## What a statement can inspect
 
-A statement reads one part of the request, applies the rule's text transformations to it, and tests
-what comes out.
+A statement selects part of the request, applies its text transformations, and then tests the
+result.
 
 The parts a statement can be pointed at are `UriPath`, `QueryString`, `SingleQueryArgument`,
 `AllQueryArguments`, `SingleHeader`, `Headers`, `Cookies`, `Method` and `Body`. `Headers` and
@@ -1371,7 +1366,7 @@ Tags, logging, sampled requests and CloudWatch metrics for a web ACL are not sim
 `AssociationConfig`, `DataProtectionConfig`, `OnSourceDDoSProtectionConfig` and `ApplicationConfig`
 are refused for the same reason, each naming what it would have configured.
 
-## Simulated commands
+## Supported operations
 
 `CreateWebACL`, `GetWebACL`, `UpdateWebACL`, `ListWebACLs`, `DeleteWebACL`, `CreateIPSet`,
 `GetIPSet`, `UpdateIPSet`, `ListIPSets`, `DeleteIPSet`, `CreateRegexPatternSet`,

package/docs/terraform/README.md

@@ -1,27 +1,29 @@
-# Terraform
+# Deploy Terraform plans
 
-A team whose infrastructure is written in Terraform can deploy it into simulated AWS without
-hand-writing a second CloudFormation template describing the same infrastructure. `TerraformAdapter`
-reads the JSON `terraform show -json` writes for a saved plan file and creates the resources the
-plan declares.
+`TerraformAdapter` reads a Terraform plan in JSON form and deploys its AWS resources into a
+`SimAws` instance.
 
 ```bash
 npm i -D @kensio/yulin
 ```
 
-## Deploying a plan
+## Create the plan JSON
 
-Write the JSON first. `terraform plan` produces the saved plan in Terraform's own binary format, and
-`terraform show -json` turns that into the document the adapter reads.
+Save a plan, then convert it to JSON:
 
 ```bash
 terraform plan -out=orders.tfplan
 terraform show -json orders.tfplan > orders.tfplan.json
 ```
 
-A plan carries no code for its functions. It points at a zip on disk, an S3 object or a container
-image, and none of the three is a handler Yulin can run. A binding matched on the function name the
-plan declares is where the behaviour comes from.
+`TerraformAdapter` expects the JSON file produced by `terraform show -json`. The binary `.tfplan`
+file is only the input to that command.
+
+## Deploy the plan
+
+Create an adapter for the `SimAws` instance and pass the JSON path to `deployPlan`. A Terraform plan
+records the location of each Lambda deployment package. Use a binding to supply an executable
+handler for the simulated function:
 
 ```typescript terraform-deploy-plan
 /**
@@ -50,9 +52,10 @@ console.log(simAws.dynamoDb().findTable("orders-orders")?.tableName);
 console.log(stack.status);
 ```
 
-The Stack is named after the plan file when the deployment does not name one, so
-`orders.tfplan.json` deploys as `orders`. Pass `stackName` to name it yourself, and pass the path on
-its own where nothing else needs saying.
+The default stack name comes from the plan filename. For example, `orders.tfplan.json` creates a
+stack named `orders`. Pass `stackName` when the stack needs a different name.
+
+If the deployment needs no bindings, overrides, or custom stack name, pass the path directly:
 
 ```typescript terraform-deploy-plan-path
 /**
@@ -71,43 +74,75 @@ const { stack } = await new TerraformAdapter(simAws).deployPlan(
 console.log(stack.stackName);
 ```
 
-## What comes back
+## Read the deployed stack and import report
+
+`deployPlan` returns `stack` and `report`.
+
+`stack` is a simulated CloudFormation stack. Use `stack.getResource(...)` to read a resource,
+`stack.output(...)` to read an output, and `stack.delete()` to delete it. The
+[CloudFormation guide](https://yulinsim.dev/services/cloudformation/ "Simulated CloudFormation usage docs")
+describes the rest of the stack API.
+
+`report` explains how Terraform resources were imported:
+
+```typescript terraform-plan-report
+/**
+ * Reading what a Terraform plan import made of the plan.
+ */
+
+import { SimAws } from "@kensio/yulin";
+import { TerraformAdapter } from "@kensio/yulin/terraform";
+
+const simAws = new SimAws();
+
+const { report } = await new TerraformAdapter(simAws).deployPlan(
+  "terraform/orders.tfplan.json",
+);
+
+// [ { address: 'aws_s3_bucket.uploads', type: 'aws_s3_bucket',
+//     cfnType: 'AWS::S3::Bucket', logicalId: 'AwsS3BucketUploads' } ]
+console.log(report.mapped);
 
-`deployPlan` answers with the Stack and a report of what reading the plan made of it.
+// [ { address: 'aws_route53_zone.public', type: 'aws_route53_zone',
+//     reason: 'no mapping for resource type' } ]
+console.log(report.skipped);
 
-The Stack is an ordinary simulated CloudFormation Stack, and everything the [CloudFormation
-docs](https://yulinsim.dev/services/cloudformation/ "Simulated CloudFormation usage docs") describe applies to it.
-Resources are read with `stack.getResource(...)`, Outputs with `stack.output(...)`, and the whole
-thing is torn down with `stack.delete()`.
+// The aws_s3_bucket_versioning and friends that became bucket properties.
+console.log(report.folded);
 
-## What the adapter reads
+// Attributes a mapping could not carry and no override supplied, such as a
+// Lambda's environment variables, which Terraform collapses whole when one of
+// them is unknown.
+console.log(report.lost);
+```
+
+- `mapped` lists resources that became CloudFormation resources.
+- `folded` lists Terraform resources that became properties of another resource.
+- `skipped` lists resources that were omitted and gives the reason for each omission.
+- `lost` lists attributes that the plan could not supply and no override replaced.
+
+The `mapped`, `folded`, and `skipped` lists account for every managed resource in the plan.
+
+## How resources and references are imported
 
 A resource declared with `count` or `for_each` arrives in the plan already expanded, and each
-instance becomes a resource of its own. Resources declared inside a module are reached through the
-module path they were declared under, however many modules deep.
+instance becomes a separate simulated resource. The adapter also reads resources from nested
+modules.
 
-An attribute Terraform could not resolve at plan time is absent from the plan's values. The plan
-keeps the reference behind it, and that reference becomes the link a hand-written template would
-have carried.
+When an attribute is unknown at plan time, Terraform omits its value but keeps its references. The
+adapter follows references through module inputs, module outputs, `each.value`, and `each.key`.
 
-Ordering is rebuilt. Terraform resolves what it can before writing the plan, so a Lambda permission
-naming a function the same plan creates carries the function's name as a plain string. The value is
-right and the edge CloudFormation orders from has gone with it. Every reference a resource declares
-becomes an ordering edge, whether or not the value resolved.
+The adapter also restores dependency ordering from each resource's references. This matters when
+Terraform has already resolved a reference to a plain string in the planned values.
 
 ## Supplying environment variables and role policies
 
-Terraform resolves nothing inside a value it could not build. A Lambda `environment.variables` map
-holding one reference to a queue of the same plan arrives unknown in its entirety, and the variable
-names go with it. An `aws_iam_role_policy` written with `jsonencode` around an ARN of the same plan
-arrives without its statements.
+Terraform marks a whole compound value as unknown when any part of it cannot be resolved. This can
+remove every key from a Lambda `environment.variables` map. It can also remove every statement from
+an IAM policy built with `jsonencode`.
 
-Those two cost more than their count suggests (four attributes out of 154 on a hand-written
-application configuration). A handler reads its configuration out of environment variables, and
-simulated IAM evaluates authorization.
-
-`overrides` supplies them, matched on the name the plan carries, the way a binding is matched on a
-function name. An environment is matched on the function's name and an inline policy on the role's.
+Use `overrides` to supply these values. Lambda environment overrides match the function name. IAM
+policy overrides match the role name:
 
 ```typescript terraform-plan-overrides
 /**
@@ -160,89 +195,36 @@ const { report } = await new TerraformAdapter(simAws).deployPlan({
 console.log(report.lost);
 ```
 
-An override fills a gap. Where Terraform resolved the value, the plan wins, and environment
-variables are merged one variable at a time. A configuration that stops collapsing a value stops
-needing the override written for it.
-
-A role whose policy no override supplies is created allowing everything, and `policy` is named on
-the report's `lost`. Simulated IAM evaluates authorization, and a role holding no policy would deny
-what the configuration allowed and fail the resources using it (an event source mapping is refused
-outright when its execution role cannot poll the queue). Supplying the policy takes that default
-off. The document is evaluated as it stands, and one omitting `sqs:ReceiveMessage` fails the mapping
-the way AWS fails it.
-
-## What it maps
-
-The adapter maps 24 Terraform resource types and folds 11 more into the resource they configure. The
-set covers API Gateway, CloudWatch (log groups, metric alarms and EventBridge rules), Cognito,
-DynamoDB, ECR, IAM, KMS, Lambda, S3, Secrets Manager, SNS, SQS and SSM Parameter Store.
-
-A hand-written application configuration of 46 resources deploys whole. A configuration built out of
-published `terraform-aws-modules` modules reaches 21 of its 25. Of the four it leaves, the Lambda
-module uses `null_resource` and `local_file` to package a zip, and an integration and a route read
-their values through a `for_each` hop the adapter steps over.
-
-## What the report says
-
-A type with no mapping, and a resource from a provider other than AWS, are recorded and stepped over
-rather than failing the deployment.
-
-```typescript terraform-plan-report
-/**
- * Reading what a Terraform plan import made of the plan.
- */
-
-import { SimAws } from "@kensio/yulin";
-import { TerraformAdapter } from "@kensio/yulin/terraform";
-
-const simAws = new SimAws();
-
-const { report } = await new TerraformAdapter(simAws).deployPlan(
-  "terraform/orders.tfplan.json",
-);
-
-// [ { address: 'aws_s3_bucket.uploads', type: 'aws_s3_bucket',
-//     cfnType: 'AWS::S3::Bucket', logicalId: 'AwsS3BucketUploads' } ]
-console.log(report.mapped);
-
-// [ { address: 'aws_route53_zone.public', type: 'aws_route53_zone',
-//     reason: 'no mapping for resource type' } ]
-console.log(report.skipped);
-
-// The aws_s3_bucket_versioning and friends that became bucket properties.
-console.log(report.folded);
-
-// Attributes a mapping could not carry and no override supplied, such as a
-// Lambda's environment variables, which Terraform collapses whole when one of
-// them is unknown.
-console.log(report.lost);
-```
-
-`mapped`, `folded` and `skipped` add up to the plan's managed resource count. `lost` names the
-attributes that did not survive the plan and that no override covered, per resource. A Terraform
-value that names a resource of the same plan and sits inside something Terraform builds in one go,
-such as a `jsonencode` document or a `for_each` map, is unknown in its entirety and its contents go
-with it.
-
-## What a reference cannot reach
-
-A value a plan resolved arrives as a value. A value the plan could not resolve arrives as a
-reference, and the import follows that reference to the resource that will produce it, through
-module outputs, module variables, `each.value` and `each.key`. That covers what a community module
-such as `terraform-aws-modules/apigateway-v2/aws` does with a `routes` map.
-
-Two shapes stop it, and both are recorded as `unresolved required attribute` on `report.skipped`.
-
-A plan records the references of a whole collection in one list, and the list says what the
-collection was built from without saying which entry holds which. A `routes` map naming one function
-is unambiguous. A `routes` map naming two functions leaves `each.value.uri` able to mean either, and
-the import declines. Setting the value with a resource of its own, or with one module call per
-function, gives each reference a collection to itself.
-
-A value reaching a resource through a `local` is out of range whatever it holds. A plan carries the
-locals' effects and none of their definitions, so there is nothing to follow.
-
-## The scope of what it reads
-
-One plan JSON file, already produced. Reading HCL, reading `terraform.tfstate`, and running
-`terraform` as a subprocess are all outside it.
+An override only fills a missing value. A value resolved by Terraform takes precedence. Environment
+variables are merged by key.
+
+If an IAM role's inline policy is missing, Yulin gives the role an allow-all policy so resources can
+still be created. The report records `policy` under `lost`. Supplying a policy override removes that
+fallback, and simulated IAM evaluates the supplied policy normally.
+
+## Available functionality
+
+- `TerraformAdapter` reads JSON produced by `terraform show -json` for a saved plan.
+- `deployPlan` accepts a path or an object containing `planPath`, `stackName`, `bindings`, and
+  `overrides`.
+- The adapter maps 24 Terraform resource types and folds 11 configuration resources into their
+  parent resources.
+- Supported resource areas include API Gateway HTTP APIs, CloudWatch, Cognito, DynamoDB, ECR, IAM,
+  KMS, Lambda, S3, Secrets Manager, SNS, SQS, and SSM Parameter Store.
+- Resources created with `count` and `for_each` are imported as separate instances.
+- Resources in nested modules are imported.
+- The adapter reports mapped, folded, skipped, and lost data for the plan.
+
+## Limitations
+
+- The adapter reads one existing plan JSON file. It does not read HCL or Terraform state, and it does
+  not run Terraform.
+- Resources from non-AWS providers and Terraform types without a mapping are skipped and recorded in
+  `report.skipped`.
+- The adapter cannot follow values through Terraform `local` declarations because a plan contains
+  their results but not their definitions.
+- A collection reference can be ambiguous. For example, `each.value.uri` cannot be resolved when the
+  source collection contains several possible Lambda function references. The affected resource is
+  skipped with the reason `unresolved required attribute`.
+- Some unknown compound values need an override because Terraform omits the whole value from the
+  plan.

package/docs/testing/README.md

@@ -0,0 +1,228 @@
+# Test suite setup
+
+Run one Yulin environment for an application's test suite. Create the simulation, deploy the
+application's infrastructure, and install AWS SDK interception once. Every test then interacts with
+the same simulated account and resources.
+
+This is the recommended setup. It matches the way a suite uses a shared AWS account or a
+container-based simulator such as LocalStack. Creating a new Yulin environment for every test or
+test file is supported, but it should be reserved for cases that need a blank simulated account.
+
+The simulated clock is the main exception. A suite-wide `SimAws` has one clock, so a test that moves
+it changes time for every resource in that environment. Keep the majority of tests in the shared
+environment without changing its clock. Put clock-controlling tests in a smaller isolated group.
+
+## Split the Vitest suite
+
+Yulin holds state in the process that created it. Vitest must run the Yulin tests in one worker for
+all shared files to reach the same environment. Give that project disabled file parallelism and file
+isolation, then load a setup module before each test file.
+
+The second project below matches files ending in `.clock.test.ts`. Those tests do not load the shared
+setup and can create isolated Yulin environments:
+
+```typescript testing-vitest-config
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "node",
+    projects: [
+      {
+        extends: true,
+        test: {
+          name: "shared Yulin",
+          include: ["test/**/*.test.ts"],
+          exclude: ["test/**/*.clock.test.ts"],
+          fileParallelism: false,
+          isolate: false,
+          setupFiles: ["./test/setup-yulin.ts"],
+        },
+      },
+      {
+        extends: true,
+        test: {
+          name: "isolated Yulin clock",
+          include: ["test/**/*.clock.test.ts"],
+        },
+      },
+    ],
+  },
+});
+```
+
+Vitest executes a `setupFiles` entry before every test file. With isolation disabled, modules
+imported by that entry stay cached in the worker. Put the Yulin initialization in an imported module
+to make it run once.
+
+See Vitest's documentation for [`setupFiles`](https://vitest.dev/config/setupfiles),
+[`fileParallelism`](https://vitest.dev/config/fileparallelism), and
+[`isolate`](https://vitest.dev/config/isolate).
+
+## Create and deploy the shared environment
+
+Put the suite environment in a module such as `test/yulin-environment.ts`. Intercept client classes
+used by the application and deploy its synthesized CDK cloud assembly:
+
+```typescript testing-shared-yulin-environment
+import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
+import { S3Client } from "@aws-sdk/client-s3";
+import type { SimAws } from "@kensio/yulin";
+import { SimSdk } from "@kensio/yulin/sdk";
+
+interface YulinTestEnvironment {
+  readonly simAws: SimAws;
+  readonly simSdk: SimSdk;
+  readonly uploadsBucketName: string;
+}
+
+type YulinTestGlobal = typeof globalThis & {
+  yulinEnvironment?: Promise<YulinTestEnvironment>;
+};
+
+const testGlobal = globalThis as YulinTestGlobal;
+
+// oxlint-disable-next-line unicorn-js/prefer-top-level-await -- The shared promise prevents setup from running again before another test file.
+export const yulin = await (testGlobal.yulinEnvironment ??= startYulin());
+
+async function startYulin(): Promise<YulinTestEnvironment> {
+  const simSdk = new SimSdk();
+  simSdk.intercept(DynamoDBClient);
+  simSdk.intercept(S3Client);
+
+  const stacks = await simSdk.simAws.cloudFormation().deployCdkOut({
+    directoryPath: "cdk.out",
+    stackNames: ["ApplicationStack"],
+  });
+  const appStack = stacks.get("ApplicationStack");
+
+  if (appStack === undefined) {
+    throw new Error("ApplicationStack was not deployed");
+  }
+
+  process.once("exit", () => {
+    simSdk.restoreAll();
+  });
+
+  return {
+    simAws: simSdk.simAws,
+    simSdk,
+    uploadsBucketName: appStack.output("UploadsBucketName"),
+  };
+}
+```
+
+Use the same templates that the application deploys. `deployCdkOut(...)` can deploy the whole cloud
+assembly or the named application Stacks. Read generated resource names from stack outputs or
+resource accessors after deployment.
+
+The configured setup entry only needs to import that module:
+
+```typescript
+// test/setup-yulin.ts
+import "./yulin-environment.js";
+```
+
+Do not put the initialization directly in `setup-yulin.ts`. Vitest executes that file for every test
+file, even when isolation is disabled.
+
+## Use the environment from every test
+
+Application code continues to construct and send through ordinary AWS SDK clients. Class-level
+interception routes all of them to the suite's Yulin environment.
+
+A test that needs direct access can import the shared environment:
+
+```typescript
+import { randomUUID } from "node:crypto";
+
+import {
+  GetObjectCommand,
+  PutObjectCommand,
+  S3Client,
+} from "@aws-sdk/client-s3";
+import { expect, it } from "vitest";
+
+import { yulin } from "../yulin-environment.js";
+
+it("stores an upload", async () => {
+  const key = `test-uploads/${randomUUID()}.txt`;
+  const s3 = new S3Client({ region: "eu-west-2" });
+
+  await s3.send(
+    new PutObjectCommand({
+      Bucket: yulin.uploadsBucketName,
+      Key: key,
+      Body: "an upload",
+    }),
+  );
+
+  const stored = await yulin.simAws
+    .region("eu-west-2")
+    .s3()
+    .getObject(
+      new GetObjectCommand({
+        Bucket: yulin.uploadsBucketName,
+        Key: key,
+      }),
+    );
+
+  expect(await stored?.Body?.transformToString()).toBe("an upload");
+});
+```
+
+The `SimAws` object is mainly useful for preparing input state and reading state back in assertions.
+Exercise the application through its normal interfaces whenever possible.
+
+## Keep tests independent in shared state
+
+Shared infrastructure does not require tests to depend on one another. Give each test's records,
+object keys, user names, and other mutable data unique values. Read CloudFormation-generated names
+from the deployed stack. Avoid assertions that assume the simulated account contains no other data.
+
+Keep `beforeEach` for the records a test needs. A per-file `beforeAll` can prepare data used by every
+test in that file. Leave the suite's stacks and SDK interception in place until the worker exits.
+
+Tests run sequentially with `fileParallelism: false`. If a test uses `it.concurrent`, its data still
+needs unique identifiers because those cases share the same environment at the same time.
+
+## Give clock-controlling tests their own environment
+
+Every service in a `SimAws` reads the same simulated clock. Calling `advanceBy(...)` can expire
+credentials, delete resources whose retention period has passed, and run scheduled work anywhere in
+the environment. Resetting the clock afterwards cannot reverse those changes.
+
+Tests in the shared project should treat the clock as read-only. Put a test that calls `freeze()`,
+`setTo(...)`, `advanceBy(...)`, or `resume()` in a `.clock.test.ts` file and create a fresh environment
+inside the test:
+
+```typescript
+import { SimAws, SimFixedClock } from "@kensio/yulin";
+import { it } from "vitest";
+
+it("expires a session", async () => {
+  const simAws = new SimAws({
+    clock: new SimFixedClock(new Date("2026-09-04T09:00:00.000Z")),
+  });
+
+  // Deploy only the infrastructure this clock-controlling test needs.
+
+  await simAws.clock().advanceBy({ minutes: 20 });
+
+  // Assert the behaviour after the time change.
+});
+```
+
+Create a `SimSdk` around that `SimAws` when application code uses SDK clients. Restore its
+interceptions at the end of the test. The [simulated time guide](https://yulinsim.dev/time/) describes
+what moving the clock runs and changes.
+
+## When to create another environment
+
+A fresh `SimAws` or `SimSdk` is useful when the empty environment is part of the behaviour under
+test, or when the test needs to control simulated time. Yulin's own service unit tests are another
+example because they test resource creation and account isolation directly.
+
+Vitest workers cannot share an in-memory `SimAws`. A suite that keeps file parallelism creates one
+environment per worker. Put Yulin-based application tests in a Vitest project with
+`fileParallelism: false` when the rest of the unit suite should remain parallel.