@kensio/yulin 1.20.16 → 1.21.0

package/dist/service/sts/command/get-caller-identity/get-caller-identity.handler.d.ts

@@ -1,5 +1,6 @@
 import type { CommandHandler } from "../../../../command/command-handler.js";
 import type { SimAwsCaller, SimAwsDefaultCaller } from "../../../aws/caller/sim-aws-caller.js";
+import type { SimAwsAmbientCaller } from "../../../aws/caller/sim-aws-ambient-caller.js";
 import type { SimAwsAccountId } from "../../../aws/sim-aws-account.js";
 import type { SimIamAccountResolver } from "../../../iam/registry/sim-iam-account-resolver.js";
 import type { SimGetCallerIdentityCommand, SimGetCallerIdentityCommandOutput } from "./get-caller-identity.command.js";
@@ -10,6 +11,10 @@ interface GetCallerIdentityCommandHandlerProperties {
      * The caller this simulation attributes a request naming none to.
      */
     readonly defaultCaller?: SimAwsDefaultCaller | undefined;
+    /**
+     * Where a request naming no caller looks before the default.
+     */
+    readonly ambientCaller?: SimAwsAmbientCaller | undefined;
 }
 /**
  * Simulated STS GetCallerIdentity handler.

package/dist/service/sts/command/get-caller-identity/get-caller-identity.handler.js

@@ -21,6 +21,7 @@ export class GetCallerIdentityCommandHandler {
         this.iamResolver = properties.iamResolver;
         this.callerResolver = new SimAwsCallerResolver({
             defaultCaller: properties.defaultCaller,
+            ambientCaller: properties.ambientCaller,
         });
     }
     /**

package/dist/service/sts/sim-sts.d.ts

@@ -4,6 +4,7 @@ import type { SimAssumeRoleCommand, SimAssumeRoleCommandOutput } from "./command
 import type { SimGetCallerIdentityCommand, SimGetCallerIdentityCommandOutput } from "./command/get-caller-identity/get-caller-identity.command.js";
 import type { SimAwsAccountRegionScope } from "../aws/sim-aws-account-region-scope.js";
 import type { SimAwsCaller, SimAwsDefaultCaller } from "../aws/caller/sim-aws-caller.js";
+import type { SimAwsAmbientCaller } from "../aws/caller/sim-aws-ambient-caller.js";
 import type { SimSdkCommandRouter } from "../../sdk/index.js";
 interface SimStsProperties {
     readonly accountRegionScope?: SimAwsAccountRegionScope;
@@ -16,6 +17,13 @@ interface SimStsProperties {
      * the identity GetCallerIdentity then reports.
      */
     readonly defaultCaller?: SimAwsDefaultCaller | undefined;
+    /**
+     * Where a request naming no caller looks before the default.
+     *
+     * A run-as block decides who the requests inside it are, so an unattributed
+     * GetCallerIdentity in one reports the caller that block named.
+     */
+    readonly ambientCaller?: SimAwsAmbientCaller | undefined;
 }
 /**
  * Simulated AWS Security Token Service.
@@ -29,6 +37,7 @@ export declare class SimSts {
     private readonly background;
     private readonly iamResolver;
     private readonly defaultCaller?;
+    private readonly ambientCaller?;
     private readonly sdkRouter;
     constructor(properties?: SimStsProperties);
     /**

package/dist/service/sts/sim-sts.js

@@ -16,6 +16,7 @@ export class SimSts {
     background;
     iamResolver;
     defaultCaller;
+    ambientCaller;
     sdkRouter = new SimStsSdkCommandRouter(this);
     constructor(properties = {}) {
         this.accountRegionScope =
@@ -23,6 +24,7 @@ export class SimSts {
         this.iamResolver = properties.iamResolver ?? new SimIamRegistry();
         this.background = properties.background ?? new BackgroundTasks();
         this.defaultCaller = properties.defaultCaller;
+        this.ambientCaller = properties.ambientCaller;
     }
     /**
      * Handle an AssumeRoleCommand from the SDK.
@@ -34,6 +36,7 @@ export class SimSts {
             iamResolver: this.iamResolver,
             background: this.background,
             defaultCaller: this.defaultCaller,
+            ambientCaller: this.ambientCaller,
         });
         return await handler.handle(command, options);
     }
@@ -45,6 +48,7 @@ export class SimSts {
             sourceAccountId: this.accountRegionScope.accountId,
             iamResolver: this.iamResolver,
             defaultCaller: this.defaultCaller,
+            ambientCaller: this.ambientCaller,
         });
         return await handler.handle(command, options);
     }

package/dist/util/memo/bounded-memo.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Memoization cache holding a bounded number of values.
+ *
+ * The bound stops a long-running process accumulating entries without limit.
+ * Which values survive it matters little. A caller gets the same value back
+ * either way, and an evicted one costs another call to the factory that made
+ * it.
+ *
+ * Eviction is by insertion order, and a value read again stays where it is. A
+ * memo worth bounding is one whose reads are hot, and reordering the cache on
+ * every read costs more than the occasional recomputation it saves.
+ *
+ * A cached value has to be something (undefined stands for a key the cache is
+ * missing). A hit then costs one map lookup.
+ */
+export declare class BoundedMemo<T extends NonNullable<unknown>> {
+    private readonly limit;
+    private readonly cache;
+    /**
+     * Hold up to `limit` values, dropping the oldest to make room past that.
+     */
+    constructor(limit: number);
+    /**
+     * Returns the cached value for the given key, or creates and caches it using
+     * `factory`.
+     */
+    getOrCreate<V extends T>(key: PropertyKey, factory: () => V): V;
+    /**
+     * Returns whether the cache is currently holding `key`.
+     */
+    has(key: PropertyKey): boolean;
+    /**
+     * Drop what was cached first, until the cache is back within its limit.
+     */
+    private evictOverflow;
+}

package/dist/util/memo/bounded-memo.js

@@ -0,0 +1,58 @@
+/**
+ * Memoization cache holding a bounded number of values.
+ *
+ * The bound stops a long-running process accumulating entries without limit.
+ * Which values survive it matters little. A caller gets the same value back
+ * either way, and an evicted one costs another call to the factory that made
+ * it.
+ *
+ * Eviction is by insertion order, and a value read again stays where it is. A
+ * memo worth bounding is one whose reads are hot, and reordering the cache on
+ * every read costs more than the occasional recomputation it saves.
+ *
+ * A cached value has to be something (undefined stands for a key the cache is
+ * missing). A hit then costs one map lookup.
+ */
+export class BoundedMemo {
+    limit;
+    cache = new Map();
+    /**
+     * Hold up to `limit` values, dropping the oldest to make room past that.
+     */
+    constructor(limit) {
+        this.limit = limit;
+    }
+    /**
+     * Returns the cached value for the given key, or creates and caches it using
+     * `factory`.
+     */
+    getOrCreate(key, factory) {
+        const cached = this.cache.get(key);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const value = factory();
+        this.cache.set(key, value);
+        this.evictOverflow();
+        return value;
+    }
+    /**
+     * Returns whether the cache is currently holding `key`.
+     */
+    has(key) {
+        return this.cache.has(key);
+    }
+    /**
+     * Drop what was cached first, until the cache is back within its limit.
+     */
+    evictOverflow() {
+        while (this.cache.size > this.limit) {
+            const oldest = this.cache.keys().next();
+            /* v8 ignore next 3 -- a cache over its limit has a first key */
+            if (oldest.done === true) {
+                return;
+            }
+            this.cache.delete(oldest.value);
+        }
+    }
+}

package/docs/sdk/README.md

@@ -85,7 +85,9 @@ none. See
 [Name the caller a simulation uses by default](https://yulinsim.dev/services/iam/#name-the-caller-a-simulation-uses-by-default).
 
 `runAs` runs a function with an ambient simulated caller, such as an IAM Role. Commands sent during
-the run are attributed to that caller, with no changes to the client or the code under test:
+the run are attributed to that caller, with no changes to the client or the code under test. A
+direct sim service call inside the run is attributed to it too, covered in
+[Run a block of calls as one caller](https://yulinsim.dev/services/iam/#run-a-block-of-calls-as-one-caller):
 
 ```typescript sim-sdk-run-as
 /**

package/docs/services/athena/README.md

@@ -383,10 +383,15 @@ its declared result.
 | Binary        | `md5`, `sha1`, `sha256`, `sha512`, `xxhash64`, `murmur3`, `crc32`, `to_hex`, `from_hex`, `to_base64`, `from_base64`, `to_utf8`, `from_utf8`                                                           |
 | URL           | `url_extract_host`, `url_extract_path`, `url_extract_protocol`, `url_extract_port`, `url_extract_query`, `url_extract_fragment`, `url_extract_parameter`, `url_decode`, `url_encode`                  |
 | Approximate   | `approx_distinct`, `approx_percentile`                                                                                                                                                                |
+| Comparison    | `least`, `greatest`                                                                                                                                                                                   |
 
 `substr` and `format` are SQLite's own. Both count from one and take the same `%s` and `%d` a
 statement writes, so shadowing either would replace something that works.
 
+`least` and `greatest` take two arguments or more. Numbers order numerically and text orders by its
+code units, matching SQLite's own `min` and `max` in their wider forms. Trino refuses a call mixing
+the two types and this answers one, ordering everything as text. A `varbinary` argument raises.
+
 The hashing functions answer with bytes and `to_hex` writes those bytes in the upper case Trino
 writes them in. Node carries every digest here apart from xxHash64 and MurmurHash3, and both of
 those are written out by hand against their published vectors. Trino refuses text where a
@@ -404,7 +409,8 @@ instant the query started, which is what the execution records.
 
 A function that cannot answer faithfully raises rather than guessing, and the query falls back.
 `date_add` with a unit Trino does not name, `slice` starting at zero, `array_join` over an array of
-objects, and `regexp_extract` naming a capture group the pattern has not got all land there. A null
+objects, `least` over a `varbinary`, and `regexp_extract` naming a capture group the pattern has not
+got all land there. A null
 answer would be a wrong answer wearing the shape of a right one.
 
 A function answers null where any argument is null, the way Trino's do. An argument left out takes

package/docs/services/cloudformation/README.md

@@ -1086,6 +1086,99 @@ await stack.waitForDeployComplete();
 Resources that reference another resource with `Ref` are also created after the referenced resource
 is ready.
 
+### Deploying independent Resources in either order
+
+Resources with no dependency between them are created together, and the template's own order
+decides which one starts first. CloudFormation is free to pick either. A Stack that deploys only
+because of the order its template happens to be written in passes here and then fails in the
+account.
+
+The pair that costs a real deployment is an `AWS::IAM::Policy` widening the deploy Role and a
+Resource in the service that widening allows. Declare the policy first and the deployment succeeds.
+Declare the Topic first and it fails on `sns:CreateTopic`. Both templates are the same template.
+
+`resourceOrder: "reversed"` starts each dependency batch from its last Resource.
+
+```typescript sim-cloudformation-resource-order
+/**
+ * Deploying a template in the order CloudFormation could have picked instead.
+ */
+
+import { SimAws } from "@kensio/yulin";
+
+const simAws = new SimAws({ defaultAccountId: "123456789012" });
+
+// The Role a real deployment already runs as, allowed to attach policies and
+// nothing else.
+await simAws.iam().createRole({
+  input: {
+    RoleName: "cdk-deploy-role",
+    AssumeRolePolicyDocument: JSON.stringify({
+      Version: "2012-10-17",
+      Statement: {
+        Effect: "Allow",
+        Action: "sts:AssumeRole",
+        Principal: { Service: "cloudformation.amazonaws.com" },
+      },
+    }),
+  },
+});
+
+await simAws.iam().putRolePolicy({
+  input: {
+    RoleName: "cdk-deploy-role",
+    PolicyName: "deploy",
+    PolicyDocument: JSON.stringify({
+      Version: "2012-10-17",
+      Statement: { Effect: "Allow", Action: "iam:*", Resource: "*" },
+    }),
+  },
+});
+
+const stack = await simAws.cloudFormation().deployTemplate({
+  stackName: "alerts-stack",
+  template: {
+    Resources: {
+      DeployerSns: {
+        Type: "AWS::IAM::Policy",
+        Properties: {
+          PolicyName: "DeployerSns",
+          Roles: ["cdk-deploy-role"],
+          PolicyDocument: {
+            Version: "2012-10-17",
+            Statement: { Effect: "Allow", Action: "sns:*", Resource: "*" },
+          },
+        },
+      },
+      Alerts: {
+        Type: "AWS::SNS::Topic",
+        DependsOn: "DeployerSns",
+        Properties: { TopicName: "alerts" },
+      },
+    },
+  },
+  caller: {
+    kind: "arn",
+    arn: "arn:aws:iam::123456789012:role/cdk-deploy-role",
+  },
+  resourceOrder: "reversed",
+});
+
+console.log(stack.getResource("Alerts")?.status); // "CREATE_COMPLETE"
+```
+
+Declared dependencies hold under either order. A Resource waits for everything its `Ref` and
+`Fn::GetAtt` expressions reach, and for everything its `DependsOn` names. Reversing a batch moves
+only the Resources CloudFormation was free to create either way round (the `DependsOn` above is what
+keeps the Topic behind the policy).
+
+Reversing one order gives the other one. Run a deployment both ways to cover the pair, since the
+template's own order is one of the two and `"reversed"` is the other. The default is `"template"`,
+which every deployment that asks for nothing gets.
+
+`deployTemplateFile(...)` takes the option too. `deployCdkOut(...)` takes one order for every Stack
+in the assembly, and a Stack named in `stackOptions` carries its own.
+
 ## Deploying synthesized CDK templates
 
 Use `deployTemplateFile(...)` to deploy a template file, including the JSON templates CDK synthesis
@@ -1427,6 +1520,40 @@ The named principal has to be allowed what the template asks for. IAM allows the
 default and allows a role only what its policies say. A role with no S3 permission leaves the bucket
 above `CREATE_FAILED`, with the role's ARN in the message.
 
+A project that scopes its own deploy permissions has the policy document already.
+`makeDeployRole(...)` turns one into a caller in a single call, creating the role with the trust
+CloudFormation needs and returning its ARN:
+
+```typescript sim-cloudformation-make-deploy-role
+/**
+ * Deploying a cloud assembly as a Role made from a policy document.
+ */
+
+import { SimAws } from "@kensio/yulin";
+
+const simAws = new SimAws({
+  defaultAccountId: "123456789012",
+  defaultRegionName: "eu-west-2",
+});
+
+const deployer = 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: deployer });
+
+console.log(stacks.size);
+```
+
+See [simulated IAM](https://yulinsim.dev/services/iam/ "Simulated IAM usage docs") for the documents
+it takes.
+
 ### One caller for an assembly, and one per Stack
 
 `deployCdkOut(...)` takes a caller for every Stack in the assembly. A Stack deployed by a different
@@ -1864,9 +1991,14 @@ CloudFront hostname adapted to the local server.
 
 ## CloudFront Function bindings
 
-When a CDK template contains a CloudFront Function, you can bind the template resource to a real
-local handler function. This lets local integration tests execute the same handler function that
-will run at the CloudFront edge.
+A `bindings` entry backs an executable Resource of the template with a real in-process handler.
+`AWS::CloudFront::Function` and `AWS::Lambda::Function` both take one, and a binding is what to
+reach for first. The bound handler stops on a breakpoint and can close over the test's own state.
+Deploy without one where the test is about the code the template carries. That is the artefact a
+deployment runs.
+
+Binding a CloudFront Function a CDK template declares lets a local integration test run the same
+handler function that will run at the CloudFront edge.
 
 ```typescript sim-cloudformation-cloudfront-function-binding
 /**
@@ -1942,9 +2074,8 @@ to provide an executable local function directly.
 ## Lambda function bindings
 
 `AWS::Lambda::Function` resources support the same bindings. The deployed function is backed by your
-real in-process handler. Tests can close over test state and step through the handler in a debugger,
-while the stack still wires roles, grants and references as the template declares. A bound function
-may omit template `Code` and `Handler` entirely.
+real in-process handler, while the stack still wires roles, grants and references as the template
+declares. A bound function may omit template `Code` and `Handler` entirely.
 
 ```typescript sim-cloudformation-lambda-binding
 /**
@@ -1989,9 +2120,10 @@ console.log(new TextDecoder().decode(output.Payload));
 
 Bindings can target the CloudFormation logical ID (or the CDK construct ID recovered from
 synthesized metadata), the function name, or the function ARN. Bound handlers still run with the
-function's execution Role as the ambient simulated caller, so downstream calls made through
-`SimSdk`-intercepted clients are authorized by simulated IAM as on real Lambda. Functions without
-a matching binding keep their template code, running in the simulated vm runtime.
+function's execution Role as the ambient simulated caller. Simulated IAM authorizes their downstream
+calls as on real Lambda, whether those go through a `SimSdk`-intercepted client or straight to a
+simulated service. Functions without a matching binding keep their template code, running in the
+simulated vm runtime.
 
 ### Naming the binding type
 
@@ -2838,6 +2970,59 @@ one that reaches an Output in these docs.
 const nameServers = stack.outputs.get("HostedZoneNameServers")?.value;
 ```
 
+## Names CloudFormation generates
+
+A Resource whose template leaves its name out is named `<stack name>-<logical ID>-<tail>`, as real
+CloudFormation names one. The tail is twelve characters derived from the other two parts, standing
+in for the twelve random characters an account produces. The same template deployed under the same
+stack name generates the same name again, and a test reads that name back from a `Ref` or an
+attribute.
+
+```typescript sim-cloudformation-generated-resource-name
+/**
+ * Reading the name CloudFormation generated for a Resource the template does
+ * not name.
+ */
+
+import { SimAws } from "@kensio/yulin";
+
+const simAws = new SimAws();
+
+const stack = await simAws.cloudFormation().deployTemplate({
+  stackName: "orders-stack",
+  template: {
+    Resources: {
+      OrdersQueue: { Type: "AWS::SQS::Queue" },
+    },
+    Outputs: {
+      QueueName: {
+        Value: { "Fn::GetAtt": ["OrdersQueue", "QueueName"] },
+      },
+    },
+  },
+});
+
+await stack.waitForDeployComplete();
+
+const queueName = stack.output("QueueName");
+
+console.log(queueName); // "orders-stack-OrdersQueue-1dca4dbe253b"
+```
+
+Each service caps how long a name may be. Where the stack name and the logical ID are too long
+together, thirteen characters of the limit are kept for the tail and its hyphen, and what is left is
+shared between the two parts either side of one more hyphen. The stack name rounds up, and each part
+takes the characters the other leaves. Where a service allows 64 characters, a long stack name keeps
+25 of them and a long logical ID keeps 25.
+
+The trimmed stack name is what an IAM policy scoped by name prefix matches. A stack called
+`ChineseboostAnalyticsStack` deploying an unnamed `AWS::Events::Rule` puts the rule under
+`ChineseboostAnalyticsStac-`. A deploy Role allowed `events:PutRule` on
+`ChineseboostAnalyticsStack-*` is refused here, as it is in an account.
+
+AWS documents none of the trimming, and the rule here is inferred from names real CloudFormation
+produced.
+
 ## Inspecting stacks and resources
 
 After deployment, you can inspect the returned stack and its resources.
@@ -3332,8 +3517,9 @@ The resource types it creates are:
   `AWS::ApiGatewayV2::Stage`
 - `AWS::CertificateManager::Certificate`
 - `AWS::CloudFormation::WaitConditionHandle`
-- `AWS::CloudFront::Distribution`, `AWS::CloudFront::Function` and
-  `AWS::CloudFront::ResponseHeadersPolicy`
+- `AWS::CloudFront::Distribution`, `AWS::CloudFront::Function`,
+  `AWS::CloudFront::ResponseHeadersPolicy`, `AWS::CloudFront::CachePolicy` and
+  `AWS::CloudFront::OriginRequestPolicy`
 - `AWS::CloudWatch::Alarm`
 - `AWS::Cognito::UserPool`, `AWS::Cognito::UserPoolClient` and
   `AWS::Cognito::UserPoolGroup`