@kensio/yulin 1.21.2 → 1.21.4

package/docs/services/lambda/README.md

@@ -286,6 +286,70 @@ console.log(logged.events?.map((event) => event.message));
 await simAws.backgroundTasksComplete();
 ```
 
+#### Keeping handler output out of the test console
+
+A handler that logs on every invocation makes that tee expensive. Powertools' `Metrics` writes an
+EMF document for every metric it counts, and a suite invoking a function a few hundred times buries
+its own output under them. `captureOnly()` stops the forwarding for every function of one simulated
+Lambda:
+
+```typescript sim-lambda-capture-only-output
+/**
+ * Recording what a handler prints without printing it again.
+ */
+
+import { FilterLogEventsCommand } from "@aws-sdk/client-cloudwatch-logs";
+import { CreateFunctionCommand, InvokeCommand } from "@aws-sdk/client-lambda";
+
+import { SimAws } from "@kensio/yulin";
+import { makeLambdaZipFileInput } from "@kensio/yulin/lambda";
+
+const simAws = new SimAws();
+
+await simAws.lambda().createFunction(
+  new CreateFunctionCommand({
+    FunctionName: "user",
+    Role: "arn:aws:iam::111111111111:role/UserRole",
+    Code: {
+      ZipFile: makeLambdaZipFileInput(() => {
+        // What AWS Lambda Powertools' Metrics writes for every metric it
+        // counts, once per request.
+        process.stdout.write(
+          `${JSON.stringify({ service: "user", UserRequest: 1 })}\n`,
+        );
+
+        return { statusCode: 200 };
+      }),
+    },
+  }),
+);
+
+// The test run's own console stays clean from here on.
+simAws.lambda().output().captureOnly();
+
+await simAws.lambda().invoke(new InvokeCommand({ FunctionName: "user" }));
+
+// The log group holds the line, as it did before.
+const found = await simAws
+  .logs()
+  .filterLogEvents(
+    new FilterLogEventsCommand({ logGroupName: "/aws/lambda/user" }),
+  );
+
+console.log(found.events?.[0]?.message);
+```
+
+The log group holds every line either way. Nothing is lost by it, and `teeToHost()` puts the
+forwarding back.
+
+The settings belong to one Account and Region, as the functions do. A suite invoking through
+`simAws.region("eu-west-1")` sets them on that scope. They are read as each line is written. A
+change reaches a function that has already cold started.
+
+A function with no simulated CloudWatch Logs behind it goes on printing whatever the settings say.
+That is a function on a standalone `SimLambda`, built outside a `SimAws` instance, and it has no log
+group for its output to be read back out of.
+
 ### When a handler throws
 
 An invocation that ends in an error nothing caught leaves an `ERROR Invoke Error` line in the
@@ -687,7 +751,13 @@ AWS JSON protocol. Those are the ones that can be read back without the operatio
 ACM, CloudWatch Logs, Cognito Identity Provider, DynamoDB, DynamoDB Streams, ECS, EventBridge, KMS,
 Rekognition, Secrets Manager, SQS and SSM.
 
-A bundled call to any other simulated service, such as S3, SNS, SES or Lambda itself, fails with an
+S3 states its operation in the method and the path. A bundled S3 client reaches the endpoint that
+already serves S3 to a client given `--endpoint-url`, in either of the two addressing styles an SDK
+sends. A function can read and write Objects with an `S3Client` its archive inlines. The execution
+Role authorizes each request, and a read it holds no `s3:GetObject` for comes back to the SDK as
+`AccessDenied`.
+
+A bundled call to any other simulated service, such as SNS, SES or Lambda itself, fails with an
 error naming the service. Leaving the SDK out of that archive puts it back
 on the module interception path above, which every simulated service is reachable through.
 
@@ -946,6 +1016,19 @@ results go. An invocation that fails its last attempt is sent to the `OnFailure`
 one whose handler returns is sent to `OnSuccess`. A destination ARN can name a simulated SQS queue,
 SNS topic, EventBridge event bus or Lambda function.
 
+The source function's execution role must allow the operation that writes to the destination:
+
+| Destination           | Required action         |
+| --------------------- | ----------------------- |
+| SQS queue             | `sqs:SendMessage`       |
+| SNS topic             | `sns:Publish`           |
+| EventBridge event bus | `events:PutEvents`      |
+| Lambda function       | `lambda:InvokeFunction` |
+
+Simulated Lambda calls the destination service with that role as its caller. A denied delivery
+rejects the background task without changing the destination. A Lambda destination is invoked
+asynchronously, so the delivery succeeds once the target invocation has been accepted.
+
 ```typescript sim-lambda-async-destinations
 /**
  * Asynchronous invocation retries and an OnFailure destination.
@@ -956,6 +1039,7 @@ import {
   InvokeCommand,
   PutFunctionEventInvokeConfigCommand,
 } from "@aws-sdk/client-lambda";
+import { CreateRoleCommand, PutRolePolicyCommand } from "@aws-sdk/client-iam";
 import { CreateQueueCommand, ReceiveMessageCommand } from "@aws-sdk/client-sqs";
 
 import { SimAws } from "@kensio/yulin";
@@ -964,19 +1048,51 @@ import {
   type SimLambdaDestinationRecord,
 } from "@kensio/yulin/lambda";
 
-const simAws = new SimAws();
+const simAws = new SimAws({ defaultAccountId: "111111111111" });
+const iam = simAws.iam();
 const lambda = simAws.lambda();
 const sqs = simAws.sqs();
+const queueArn = `arn:aws:sqs:${simAws.defaultRegionName}:${simAws.defaultAccountId}:order-failures`;
 
 const created = await sqs.createQueue(
   new CreateQueueCommand({ QueueName: "order-failures" }),
 );
 
+const role = await iam.createRole(
+  new CreateRoleCommand({
+    RoleName: "OrdersRole",
+    AssumeRolePolicyDocument: JSON.stringify({
+      Version: "2012-10-17",
+      Statement: {
+        Effect: "Allow",
+        Principal: { Service: "lambda.amazonaws.com" },
+        Action: "sts:AssumeRole",
+      },
+    }),
+  }),
+);
+const roleArn = role.Role.Arn;
+
+await iam.putRolePolicy(
+  new PutRolePolicyCommand({
+    RoleName: "OrdersRole",
+    PolicyName: "SendFailedOrders",
+    PolicyDocument: JSON.stringify({
+      Version: "2012-10-17",
+      Statement: {
+        Effect: "Allow",
+        Action: "sqs:SendMessage",
+        Resource: queueArn,
+      },
+    }),
+  }),
+);
+
 const attempts: string[] = [];
 await lambda.createFunction(
   new CreateFunctionCommand({
     FunctionName: "orders",
-    Role: "arn:aws:iam::111111111111:role/OrdersRole",
+    Role: roleArn,
     Code: {
       ZipFile: makeLambdaZipFileInput((event: { id: number }) => {
         attempts.push(`tried order ${event.id}`);
@@ -992,7 +1108,7 @@ await lambda.putFunctionEventInvokeConfig(
     MaximumRetryAttempts: 1,
     DestinationConfig: {
       OnFailure: {
-        Destination: "arn:aws:sqs:us-east-1:888888888888:order-failures",
+        Destination: queueArn,
       },
     },
   }),
@@ -1041,33 +1157,67 @@ a config of its own, and an invocation of a qualifier with no config of its own
 `DeadLetterConfig` is the older way to keep a failed asynchronous invocation, and simulated Lambda
 takes it on `CreateFunction` and `UpdateFunctionConfiguration`. Its `TargetArn` names a simulated
 SQS queue or SNS topic, which receives the event as it was invoked rather than the destination
-record around it.
+record around it. The execution role needs `sqs:SendMessage` for a queue or `sns:Publish` for a
+topic. A denied delivery rejects the background task and leaves the target unchanged.
 
 ```typescript sim-lambda-dead-letter-queue
 /**
  * A simulated Lambda function with a dead-letter queue.
  */
 
+import { CreateRoleCommand, PutRolePolicyCommand } from "@aws-sdk/client-iam";
 import { CreateFunctionCommand, InvokeCommand } from "@aws-sdk/client-lambda";
 import { CreateQueueCommand, ReceiveMessageCommand } from "@aws-sdk/client-sqs";
 
 import { SimAws } from "@kensio/yulin";
 import { makeLambdaZipFileInput } from "@kensio/yulin/lambda";
 
-const simAws = new SimAws();
+const simAws = new SimAws({ defaultAccountId: "111111111111" });
+const iam = simAws.iam();
 const lambda = simAws.lambda();
 const sqs = simAws.sqs();
+const queueArn = `arn:aws:sqs:${simAws.defaultRegionName}:${simAws.defaultAccountId}:orders-dlq`;
 
 const created = await sqs.createQueue(
   new CreateQueueCommand({ QueueName: "orders-dlq" }),
 );
 
+const role = await iam.createRole(
+  new CreateRoleCommand({
+    RoleName: "OrdersRole",
+    AssumeRolePolicyDocument: JSON.stringify({
+      Version: "2012-10-17",
+      Statement: {
+        Effect: "Allow",
+        Principal: { Service: "lambda.amazonaws.com" },
+        Action: "sts:AssumeRole",
+      },
+    }),
+  }),
+);
+const roleArn = role.Role.Arn;
+
+await iam.putRolePolicy(
+  new PutRolePolicyCommand({
+    RoleName: "OrdersRole",
+    PolicyName: "SendFailedOrders",
+    PolicyDocument: JSON.stringify({
+      Version: "2012-10-17",
+      Statement: {
+        Effect: "Allow",
+        Action: "sqs:SendMessage",
+        Resource: queueArn,
+      },
+    }),
+  }),
+);
+
 await lambda.createFunction(
   new CreateFunctionCommand({
     FunctionName: "orders",
-    Role: "arn:aws:iam::111111111111:role/OrdersRole",
+    Role: roleArn,
     DeadLetterConfig: {
-      TargetArn: "arn:aws:sqs:us-east-1:888888888888:orders-dlq",
+      TargetArn: queueArn,
     },
     Code: {
       ZipFile: makeLambdaZipFileInput(() => {
@@ -1755,15 +1905,152 @@ Advancing the simulation's clock is what hands the batch over again:
 await simAws.clock().advanceBy({ seconds: 30 });
 ```
 
-The batch is delivered again five times, after 1, 2, 4, 8 and 16 seconds, so six deliveries in all.
-Then it is discarded and the mapping carries on with the stream, as AWS does once a stream mapping's
-error handling has run out.
+A mapping that asks for no limit of its own delivers the batch again five times, after 1, 2, 4, 8
+and 16 seconds, so six deliveries in all. Then it is discarded and the mapping carries on with the
+stream, as AWS does once a stream mapping's error handling has run out.
+
+The delays are a simulator constraint. AWS documents no delay between attempts. A delay of zero here
+would fall due at the instant the clock already reads, and a handler that always throws would leave
+`advanceBy` with work falling due forever. The growing delay is also what lets a test walk through
+the attempts by advancing the clock.
+
+The five attempts are a cap on a mapping that named neither of the limits below. AWS retries until
+the records age out of the stream, a day later, and waiting out a simulated day is the same hang
+with more steps.
+
+### Limiting the retries and the record age
+
+`MaximumRetryAttempts` and `MaximumRecordAgeInSeconds` govern the same failed-batch lifecycle, and a
+stream mapping keeps both. `MaximumRetryAttempts: 0` makes one delivery and no retries, and a
+positive value allows that many retries after the first delivery. `MaximumRecordAgeInSeconds`
+discards a record once the next attempt would fall past that age. Lambda's `-1` means no limit
+(that is what a mapping naming neither reports back).
+
+```typescript sim-lambda-stream-retry-limits
+/**
+ * Giving up on a stream batch once its retries have run out.
+ */
+
+import { CreateTableCommand, PutItemCommand } from "@aws-sdk/client-dynamodb";
+import { CreateRoleCommand, PutRolePolicyCommand } from "@aws-sdk/client-iam";
+import {
+  CreateEventSourceMappingCommand,
+  CreateFunctionCommand,
+} from "@aws-sdk/client-lambda";
+
+import { SimAws } from "@kensio/yulin";
+import {
+  makeLambdaZipFileInput,
+  type SimLambdaDynamoDbStreamEvent,
+} from "@kensio/yulin/lambda";
+
+const simAws = new SimAws();
+
+const { TableDescription } = await simAws.dynamoDb().createTable(
+  new CreateTableCommand({
+    TableName: "orders",
+    KeySchema: [{ AttributeName: "orderId", KeyType: "HASH" }],
+    AttributeDefinitions: [{ AttributeName: "orderId", AttributeType: "S" }],
+    BillingMode: "PAY_PER_REQUEST",
+    StreamSpecification: {
+      StreamEnabled: true,
+      StreamViewType: "NEW_AND_OLD_IMAGES",
+    },
+  }),
+);
+
+const streamArn = TableDescription?.LatestStreamArn;
 
-Both the cadence and the number of attempts are simulator constraints rather than AWS behaviour. AWS
-documents no delay between attempts and retries until the records age out of the stream, a day
-later. A delay of zero here would fall due at the instant the clock already reads. A handler that
-always throws would then leave `advanceBy` with work falling due forever, and waiting out a
-simulated day is the same problem with more steps.
+const role = await simAws.iam().createRole(
+  new CreateRoleCommand({
+    RoleName: "OrderProjectorRole",
+    AssumeRolePolicyDocument: JSON.stringify({
+      Version: "2012-10-17",
+      Statement: {
+        Effect: "Allow",
+        Principal: { Service: "lambda.amazonaws.com" },
+        Action: "sts:AssumeRole",
+      },
+    }),
+  }),
+);
+
+await simAws.iam().putRolePolicy(
+  new PutRolePolicyCommand({
+    RoleName: "OrderProjectorRole",
+    PolicyName: "ReadOrdersStream",
+    PolicyDocument: JSON.stringify({
+      Version: "2012-10-17",
+      Statement: [
+        {
+          Effect: "Allow",
+          Action: [
+            "dynamodb:DescribeStream",
+            "dynamodb:GetRecords",
+            "dynamodb:GetShardIterator",
+          ],
+          Resource: streamArn,
+        },
+        { Effect: "Allow", Action: "dynamodb:ListStreams", Resource: "*" },
+      ],
+    }),
+  }),
+);
+
+// The handler never gets through the batch, so the retries are what decide
+// how many times it is given one.
+const deliveries: SimLambdaDynamoDbStreamEvent[] = [];
+
+await simAws.lambda().createFunction(
+  new CreateFunctionCommand({
+    FunctionName: "order-projector",
+    Role: role.Role.Arn,
+    Code: {
+      ZipFile: makeLambdaZipFileInput(
+        (event: SimLambdaDynamoDbStreamEvent): undefined => {
+          deliveries.push(event);
+
+          throw new Error("Projector could not handle the batch");
+        },
+      ),
+    },
+  }),
+);
+
+await simAws.lambda().createEventSourceMapping(
+  new CreateEventSourceMappingCommand({
+    EventSourceArn: streamArn,
+    FunctionName: "order-projector",
+    StartingPosition: "TRIM_HORIZON",
+    MaximumRetryAttempts: 2,
+    MaximumRecordAgeInSeconds: 120,
+  }),
+);
+
+await simAws.dynamoDb().putItem(
+  new PutItemCommand({
+    TableName: "orders",
+    Item: { orderId: { S: "order-1" }, total: { N: "42" } },
+  }),
+);
+
+await simAws.backgroundTasksComplete();
+
+// The two retries fall due 1 and 2 seconds after the deliveries they follow.
+await simAws.clock().advanceBy({ seconds: 30 });
+
+console.log(deliveries.length); // 3
+```
+
+Records age out of the front of a batch, since a batch is in stream order. A batch whose oldest
+records are past the age goes over again from the first record that is still young enough, and the
+shard keeps moving. A batch that has had its retries, or whose records have all aged out, is
+discarded, and the mapping reads on from behind it.
+
+`GetEventSourceMapping` and `ListEventSourceMappings` report both values, and
+`AWS::Lambda::EventSourceMapping` takes both in a template. A value outside Lambda's range (`-1` to
+10,000 retries, `-1` to 604,800 seconds) is a `ValidationException`. A queue mapping takes neither,
+because a message the handler never takes is left to the queue's own redrive policy.
 
 ### Reporting individual record failures
 
@@ -1797,7 +2084,7 @@ why a stream consumer has to be idempotent.
 
 So a report naming only the last record of a batch delivers that record again. A report naming the
 first record delivers the whole batch again. The redelivery is a retry like any other. It waits out
-the same backoff, counts against the same five attempts, and what is left is discarded when they run
+the same backoff, counts against the same retries, and what is left is discarded when they run
 out.
 
 A report naming a sequence number that was not in the batch delivers the whole batch again, as real
@@ -2167,6 +2454,8 @@ AWS managed policy and CDK's own grant give a stream consumer. A role missing on
 handler names a record by its `sequenceNumber`, and the mapping goes back to the lowest one the
 report names, so that record and everything after it on that shard is delivered again. A failing
 batch blocks its own shard and no other.
+[`MaximumRetryAttempts` and `MaximumRecordAgeInSeconds`](#limiting-the-retries-and-the-record-age)
+work the same way here, and each shard counts its own attempts.
 
 A mapping naming an enhanced fan-out consumer ARN is refused, since consumers are unsimulated.
 `AWS::Lambda::EventSourceMapping` deploys a Kinesis mapping the same way it deploys a DynamoDB one.
@@ -2364,11 +2653,115 @@ the route key, the stage and the path parameters are the endpoint's rather than
 ### Managing a Function URL
 
 `GetFunctionUrlConfigCommand` reads the configuration back, `UpdateFunctionUrlConfigCommand`
-changes the `AuthType` or `InvokeMode` while keeping the same endpoint, and
+changes the `AuthType`, `InvokeMode` or `Cors` while keeping the same endpoint, and
 `DeleteFunctionUrlConfigCommand` removes it, after which the hostname stops resolving and returns
 `404`. `ListFunctionUrlConfigsCommand` lists what a function has, which is one configuration or
 none, since a function has at most one Function URL.
 
+A `Cors` block on an update replaces the whole block the URL was created with. An update that leaves
+`Cors` out keeps the block already in place.
+
+### Cross-origin resource sharing
+
+A Function URL created with a `Cors` block sends the CORS headers that block describes on every
+response it serves, and answers a browser preflight from the block alone.
+
+```typescript sim-lambda-function-url-cors
+/**
+ * Serving a simulated Lambda Function URL configured for CORS.
+ */
+
+import {
+  CreateFunctionCommand,
+  CreateFunctionUrlConfigCommand,
+} from "@aws-sdk/client-lambda";
+
+import { SimAws } from "@kensio/yulin";
+import { makeLambdaZipFileInput } from "@kensio/yulin/lambda";
+import { serveSimAws } from "@kensio/yulin/serve";
+
+const simAws = new SimAws();
+const lambda = simAws.lambda();
+
+await lambda.createFunction(
+  new CreateFunctionCommand({
+    FunctionName: "rates",
+    Role: "arn:aws:iam::111111111111:role/RatesRole",
+    Code: {
+      ZipFile: makeLambdaZipFileInput(() => ({
+        statusCode: 200,
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ gbp: 1.27 }),
+      })),
+    },
+  }),
+);
+
+const urlConfig = await lambda.createFunctionUrlConfig(
+  new CreateFunctionUrlConfigCommand({
+    FunctionName: "rates",
+    AuthType: "NONE",
+    Cors: {
+      AllowOrigins: ["https://shop.example.com"],
+      AllowMethods: ["GET", "POST"],
+      AllowHeaders: ["content-type"],
+      ExposeHeaders: ["x-request-id"],
+      AllowCredentials: true,
+      MaxAge: 600,
+    },
+  }),
+);
+
+const srv = await serveSimAws({ simAws });
+const endpoint = srv.localUrl(urlConfig.FunctionUrl);
+
+try {
+  const preflight = await fetch(endpoint, {
+    method: "OPTIONS",
+    headers: {
+      origin: "https://shop.example.com",
+      "access-control-request-method": "GET",
+    },
+  });
+
+  // 200 https://shop.example.com GET,POST
+  console.log(
+    preflight.status,
+    preflight.headers.get("access-control-allow-origin"),
+    preflight.headers.get("access-control-allow-methods"),
+  );
+
+  const response = await fetch(endpoint, {
+    headers: { origin: "https://shop.example.com" },
+  });
+
+  // {"gbp":1.27} x-request-id
+  console.log(
+    await response.text(),
+    response.headers.get("access-control-expose-headers"),
+  );
+} finally {
+  await srv.close();
+}
+```
+
+`AllowOrigins` decides what goes in `Access-Control-Allow-Origin`. A list holding `*` allows every
+Origin. Any other list is matched against the `Origin` header the request carried, and a request
+from an Origin the list does not name gets no `Access-Control-Allow-Origin` header. `AllowMethods`,
+`AllowHeaders` and `ExposeHeaders` each go out as one comma-separated header, and an empty list
+leaves its header off. `AllowCredentials` sends `Access-Control-Allow-Credentials: true` when it is
+set. `MaxAge` sets `Access-Control-Max-Age` in seconds.
+
+A preflight is an `OPTIONS` request carrying both `Origin` and `Access-Control-Request-Method`.
+Lambda answers it from the configuration and the function never runs. Every other method reaches the
+handler, and the configured headers are added to the response it returned. A handler that sends CORS
+headers of its own leaves the response carrying both values, which is what real Lambda serves.
+Browsers report the duplicate as an error, so keep CORS on the Function URL and leave it out of the
+handler.
+
+An `AWS_IAM` Function URL authorizes a preflight the way it authorizes any other request. A browser
+cannot sign the preflight it sends, and an unsigned request to that URL is answered with `403`.
+
 ### IAM-authenticated Function URLs
 
 A URL created with `AuthType: "AWS_IAM"` invokes the function only for a caller allowed
@@ -2748,6 +3141,129 @@ otherwise. A time read at module scope is therefore read too early, exactly as i
 variables. See [simulated time](https://yulinsim.dev/time/) for the whole picture, including where real
 AWS puts the time on the event.
 
+## Timers and the invocation deadline
+
+A handler's `setTimeout`, `clearTimeout`, `setInterval` and `clearInterval` measure their delays on
+the simulation's clock. A handler that sleeps wakes when a test advances time past its delay, and a
+frozen clock holds it asleep for as long as the test wants. The timers belong to one invocation. Two
+simulations running at once each keep their own, and code outside an invocation keeps the host
+timers it already had.
+
+A sleeping handler is released by the clock. A test asks for the invocation and moves time before
+waiting on the answer.
+
+```typescript sim-lambda-handler-timers
+/**
+ * A simulated Lambda handler sleeping on the simulation's clock.
+ */
+
+import { CreateFunctionCommand, InvokeCommand } from "@aws-sdk/client-lambda";
+
+import { SimAws } from "@kensio/yulin";
+import { makeLambdaZipFileInput } from "@kensio/yulin/lambda";
+
+const simAws = new SimAws();
+const lambda = simAws.lambda();
+
+await lambda.createFunction(
+  new CreateFunctionCommand({
+    FunctionName: "batcher",
+    Role: "arn:aws:iam::111111111111:role/BatcherRole",
+    Timeout: 60,
+    Code: {
+      ZipFile: makeLambdaZipFileInput(async () => {
+        await new Promise((resolve) => {
+          setTimeout(resolve, 30_000);
+        });
+
+        return "batched";
+      }),
+    },
+  }),
+);
+
+// Asked for and left running, because the handler is waiting on the clock.
+const invocation = lambda.invoke(
+  new InvokeCommand({ FunctionName: "batcher" }),
+);
+
+await simAws.clock().advanceBy({ seconds: 30 });
+
+const output = await invocation;
+if (output.Payload === undefined) throw new Error("No invoke Payload");
+console.log(Buffer.from(output.Payload).toString());
+```
+
+An interval runs once for each period an advance covers. Advancing eleven seconds past a two second
+interval runs it five times. A delay of zero, or none at all, is due at the instant it was asked
+for, and a handler yielding with `setTimeout(resolve, 0)` gets going again without the clock moving.
+
+The function's `Timeout` is a deadline on the same clock. Where it arrives before the handler
+answers, the invocation ends in the error the real runtime reports.
+
+```typescript sim-lambda-invocation-timeout
+/**
+ * A simulated Lambda invocation running out of the time its Timeout allows.
+ */
+
+import { CreateFunctionCommand, InvokeCommand } from "@aws-sdk/client-lambda";
+
+import { SimAws } from "@kensio/yulin";
+import { makeLambdaZipFileInput } from "@kensio/yulin/lambda";
+
+const simAws = new SimAws();
+const lambda = simAws.lambda();
+
+await lambda.createFunction(
+  new CreateFunctionCommand({
+    FunctionName: "slowcoach",
+    Role: "arn:aws:iam::111111111111:role/SlowcoachRole",
+    Timeout: 3,
+    Code: {
+      ZipFile: makeLambdaZipFileInput(async () => {
+        await new Promise((resolve) => {
+          setTimeout(resolve, 60_000);
+        });
+
+        return "too late";
+      }),
+    },
+  }),
+);
+
+const invocation = lambda.invoke(
+  new InvokeCommand({ FunctionName: "slowcoach" }),
+);
+
+await simAws.clock().advanceBy({ seconds: 10 });
+
+const output = await invocation;
+if (output.Payload === undefined) throw new Error("No invoke Payload");
+
+// Unhandled
+console.log(output.FunctionError);
+
+const failure = JSON.parse(Buffer.from(output.Payload).toString()) as {
+  errorType: string;
+  errorMessage: string;
+};
+
+// Sandbox.Timedout
+console.log(failure.errorType);
+// <deadline instant> <request id> Task timed out after 3.00 seconds
+console.log(failure.errorMessage);
+```
+
+The log group gets the `ERROR Invoke Error` line the runtime writes, and `AWS/Lambda` counts an
+`Errors` datapoint beside the `Invocations`. A handler that answers after its deadline reaches
+nobody, and the timers it left running are given up with the rest of the invocation.
+
+For an `Event` invocation a timeout is a failed attempt. It goes to the same
+[retries and destinations](#asynchronous-retries-and-destinations) an attempt that threw goes to.
+
+A frozen clock never reaches the deadline. A handler under one runs for as long as the host process
+lets it, and `context.getRemainingTimeInMillis()` reports the same budget throughout.
+
 ## What an invocation counts in CloudWatch
 
 Every invocation publishes `Invocations` and a `Duration` into `AWS/Lambda`, dimensioned by
@@ -3226,11 +3742,45 @@ const stack = await simAws.cloudFormation().deployTemplate({
         Type: "AWS::SQS::Queue",
         Properties: { QueueName: "orders-dlq" },
       },
+      OrdersRole: {
+        Type: "AWS::IAM::Role",
+        Properties: {
+          RoleName: "OrdersRole",
+          AssumeRolePolicyDocument: {
+            Version: "2012-10-17",
+            Statement: [
+              {
+                Effect: "Allow",
+                Principal: { Service: "lambda.amazonaws.com" },
+                Action: "sts:AssumeRole",
+              },
+            ],
+          },
+          Policies: [
+            {
+              PolicyName: "SendFailedOrders",
+              PolicyDocument: {
+                Version: "2012-10-17",
+                Statement: [
+                  {
+                    Effect: "Allow",
+                    Action: "sqs:SendMessage",
+                    Resource: [
+                      { "Fn::GetAtt": ["OrderFailures", "Arn"] },
+                      { "Fn::GetAtt": ["OrderDeadLetters", "Arn"] },
+                    ],
+                  },
+                ],
+              },
+            },
+          ],
+        },
+      },
       OrdersFunction: {
         Type: "AWS::Lambda::Function",
         Properties: {
           FunctionName: "orders",
-          Role: "arn:aws:iam::111111111111:role/OrdersRole",
+          Role: { "Fn::GetAtt": ["OrdersRole", "Arn"] },
           Handler: "index.handler",
           Runtime: "nodejs22.x",
           Code: {
@@ -3529,9 +4079,12 @@ Sim Lambda currently supports:
 - `ListFunctionsCommand`, reporting every function in the Account and Region, and their published
   versions with `FunctionVersion: "ALL"`
 - `InvokeCommand`, with the `RequestResponse`, `Event` and `DryRun` invocation types
+- Handler timers on the simulation's clock, and the function's `Timeout` as a deadline on the same
+  clock, reported as real Lambda reports a timeout
 - Asynchronous invocation retries on the simulated clock, and `OnSuccess`/`OnFailure` destinations
   written with `PutFunctionEventInvokeConfigCommand`, delivering the AWS destination record to a
-  simulated SQS queue, SNS topic, EventBridge event bus or Lambda function
+  simulated SQS queue, SNS topic, EventBridge event bus or Lambda function after authorizing the
+  target operation against the source function's execution role
 - `GetFunctionEventInvokeConfigCommand`, `UpdateFunctionEventInvokeConfigCommand`,
   `DeleteFunctionEventInvokeConfigCommand` and `ListFunctionEventInvokeConfigsCommand`, each taking
   a `Qualifier` for a version's or an alias's own config
@@ -3539,6 +4092,8 @@ Sim Lambda currently supports:
   event to a simulated SQS queue or SNS topic
 - Function URLs, created with `CreateFunctionUrlConfigCommand` and served over HTTP on localhost
   with `serveSimAws`
+- `Cors` on a Function URL, adding the configured headers to every response and answering a browser
+  preflight without invoking the function
 - `iam:PassRole` authorization of the execution role named by `CreateFunctionCommand` and
   `UpdateFunctionConfigurationCommand`, with `iam:PassedToService` supplied
 - `AuthType: "AWS_IAM"` Function URLs, authorizing `lambda:InvokeFunctionUrl` against the caller
@@ -3554,6 +4109,8 @@ Sim Lambda currently supports:
   DynamoDB stream and Kinesis events and honouring `BatchSize`
 - `StartingPosition: "TRIM_HORIZON"` and `"LATEST"` on a stream mapping, and `"AT_TIMESTAMP"` on a
   Kinesis one, with a failing batch blocking its shard until it is through or discarded
+- `MaximumRetryAttempts` and `MaximumRecordAgeInSeconds` on a stream mapping, ending the retries at
+  a quota or at a record age
 - Every shard of a Kinesis stream read by a processor of its own, as real Lambda reads one
 - `FunctionResponseTypes: ["ReportBatchItemFailures"]` on a queue mapping, returning only the
   message ids the handler reported, and on a stream mapping, rewinding to the lowest sequence number
@@ -3565,6 +4122,8 @@ Sim Lambda currently supports:
 - A Node.js `vm` runtime for zip-packaged code, with warm module state across invocations, and
   writable standard streams for handler output, including a bundled AWS Lambda Powertools logger's
   own console
+- Handler output recorded into the function's log group and forwarded to the host console, with
+  `simAws.lambda().output().captureOnly()` to drop the forwarding
 - Per-function environment variables with `Environment.Variables`
 - Runtime-provided `@aws-sdk/*` packages inside function code, routed into the owning simulated AWS
   environment
@@ -3609,17 +4168,14 @@ Current documented limitations:
   settings simulated Lambda models, leaving out `Layers`, `VpcConfig`, `TracingConfig`, `KMSKeyArn`,
   `EphemeralStorage`, `SnapStart`, `LoggingConfig` and `RevisionId`. `ListFunctions` leaves out
   `Marker`/`MaxItems` paging and `MasterRegion`.
-- A destination is delivered to without checking that the function's execution role may write to it.
-  Real Lambda delivers under that role and drops the record where the role cannot, which would be
-  silent, so simulated Lambda delivers instead. Nothing else about the destination has to be set up,
-  since a destination needs no resource policy on real AWS either.
 - SAM's `EventInvokeConfig` and `DeadLetterQueue` on `AWS::Serverless::Function` are left out. A
   SAM application declaring either deploys a function with the default retries, no destinations and
   no dead-letter target. The `AWS::Lambda::EventInvokeConfig` Resource and the `DeadLetterConfig`
   property a CloudFormation or CDK template writes are both deployed. See
   [retries and destinations in templates](#retries-and-destinations-in-templates).
-- Throttling and timeouts do not drive a retry. A retry follows a handler that threw, and the
-  `MaximumEventAgeInSeconds` a config carries is measured from when the invocation was accepted.
+- Throttling does not drive a retry. A retry follows a handler that threw or ran out of time, and
+  the `MaximumEventAgeInSeconds` a config carries is measured from when the invocation was
+  accepted.
 - `DestinationConfig` on an event source mapping is left out. It is a different mechanism from the
   asynchronous invocation destinations above.
 - A settings change takes effect at once. Real Lambda reports `LastUpdateStatus: "InProgress"` while
@@ -3638,7 +4194,9 @@ Current documented limitations:
 - `requestContext.authorizer.iam` reports `accessKey` as empty, and `callerId` and `userId` as the
   caller ARN rather than the opaque unique id real AWS uses. `cognitoIdentity` and `principalOrgId`
   are always null.
-- The Function URL `Cors` configuration is left out, including OPTIONS preflight handling.
+- A Function URL's `Cors` block is checked against the bounds the Lambda API documents for each
+  member. Values inside those bounds are taken as they are. An `AllowOrigins` entry that is not a
+  well-formed Origin is stored and matches no request.
 - `InvokeMode: "RESPONSE_STREAM"` is accepted and reported, but responses are always served
   buffered.
 - A function has at most one Function URL, and qualified (version or alias) Function URLs are left
@@ -3691,9 +4249,15 @@ Current documented limitations:
 - An unsigned request to a service API endpoint is served over HTTP when the simulation serves that
   endpoint, which today means Cognito's regional endpoint and the S3 endpoints. Anywhere else it is
   read as a Command and refused as one.
-- `Timeout` is recorded and never interrupts handler execution.
-- Timers inside a handler are host timers. `setTimeout` waits in real time, and advancing the
-  simulation's clock leaves a sleeping handler asleep.
+- A handler is interrupted at its deadline only where it yields. The deadline waits on the
+  simulation's clock like any other work, and dispatching it needs the event loop, so a handler
+  looping over the CPU without awaiting anything runs to the end of its loop.
+- The global `setTimeout`, `clearTimeout`, `setInterval` and `clearInterval` are the timers on the
+  simulation's clock. `node:timers`, `node:timers/promises` and `util.promisify(setTimeout)` are
+  imported directly rather than read from the globals, and they wait in real time.
+- Module-scope initialization time and execution environment recycling are left out. A cold start
+  costs nothing against the deadline, and a function keeps one warm environment for as long as it
+  exists.
 - A time read at module scope, like an environment variable read there, is read before any
   invocation and sees the host clock. See [The time inside a handler](#the-time-inside-a-handler).
 - `Event` invocation retries and failure destinations are left out, and handler errors are dropped.
@@ -3703,15 +4267,15 @@ Current documented limitations:
   it stands.
 - SQS queues, DynamoDB streams and Kinesis streams are the only event sources. Kafka, DocumentDB and
   Kinesis enhanced fan-out consumers are refused outright, and so are `FilterCriteria`,
-  `ScalingConfig`, `DestinationConfig`, `MaximumRetryAttempts`, `BisectBatchOnFunctionError`,
-  `ParallelizationFactor`, `TumblingWindowInSeconds` and the other mapping inputs this simulation
-  has no behaviour for.
-- A stream batch is delivered again five times, after 1, 2, 4, 8 and 16 seconds, and then discarded.
-  AWS documents no delay between attempts and retries until the records age out. Both differences
-  are deliberate. A delay of zero falls due at the instant the clock already reads, and a handler
-  that always throws would leave `advanceBy` with work falling due forever. A batch item failure
-  report counts against the same five attempts, and never starts them again for the records it
-  rewound to.
+  `ScalingConfig`, `DestinationConfig`, `BisectBatchOnFunctionError`, `ParallelizationFactor`,
+  `TumblingWindowInSeconds` and the other mapping inputs this simulation has no behaviour for.
+- A failed stream batch waits 1, 2, 4, 8 and 16 seconds between attempts, where AWS documents no
+  delay. That is deliberate. A delay of zero falls due at the instant the clock already reads, and a
+  handler that always throws would leave `advanceBy` with work falling due forever. A mapping that
+  names neither `MaximumRetryAttempts` nor `MaximumRecordAgeInSeconds` gets five retries and then
+  discards the batch, where AWS goes on until the records age out a day later. A batch item failure
+  report counts against the same retries, and never starts them again for the records it rewound
+  to.
 - A handler writing into the table whose stream invoked it is refused with
   `SimLambdaStreamCascadeError` rather than being delivered its own writes forever. Real Lambda runs
   that loop.