@kensio/yulin 1.21.21 → 1.21.22

package/docs/services/lambda/README.md

@@ -1738,8 +1738,8 @@ const { TableDescription } = await simAws.dynamoDb().createTable(
 const streamArn = TableDescription?.LatestStreamArn;
 
 // The projection goes into a second table. A function writing back into the
-// table whose stream invoked it would be delivered its own writes, which the
-// simulator refuses rather than looping on.
+// table whose stream invoked it is delivered its own writes, and the simulator
+// refuses a chain of those that keeps going.
 await simAws.dynamoDb().createTable(
   new CreateTableCommand({
     TableName: "order-totals",
@@ -2161,12 +2161,16 @@ created without `FunctionResponseTypes` ignores a report entirely.
 
 ### Writing back to the source table
 
-A handler that writes into the table whose stream invoked it is delivered its own write, which
-writes again. Real Lambda runs that loop for as long as the account is willing to pay for it. The
-simulation refuses instead, with an error naming the function, the stream and the table, before the
-test times out.
+A handler that writes into the table whose stream invoked it is delivered its own write. Where that
+write brings on another, and that one another, the simulation is going round a loop. Real Lambda
+runs the loop for as long as the account is willing to pay for it. Yulin counts the deliveries a
+handler's own writes bring on and refuses after ten of them in a row, with an error naming the
+function, the stream, the table and the count.
 
-The write itself succeeds. The refusal comes afterwards, from whatever is waiting for the simulation
+A handler that settles is left to finish. Writing back once and then finding the work already done
+ends the chain at one link, and the delivery that link caused writes nothing.
+
+The write itself succeeds. A refusal comes afterwards, from whatever is waiting for the simulation
 to settle:
 
 ```typescript
@@ -2177,7 +2181,7 @@ Only the handler's own writes count. Items written at the same time by the test,
 in the simulation, are an ordinary batch however many of them there are, because the guard tells them
 apart by where the write came from, and never by when it landed.
 
-Writing the projection into a second table is what the guard is asking for, and is what a real
+A projection that writes back on every delivery belongs in a second table. That is what a real
 aggregation or search index does anyway.
 
 ### Making a stream event without a table
@@ -2361,9 +2365,11 @@ the mapping's execution-role check is looking for.
 
 `bisectBatchOnError` is simulated, and is covered under
 [Splitting a failed batch around the record that broke it](#splitting-a-failed-batch-around-the-record-that-broke-it).
-The other properties a non-default `DynamoEventSource` adds are recorded rather than acted on. Those
-are `FilterCriteria`, `ParallelizationFactor` and `TumblingWindowInSeconds`.
-The mapping deploys, delivers every record whole and unfiltered, and each property it was created
+So is `filters`, which is covered under
+[Filtering the records a mapping delivers](#filtering-the-records-a-mapping-delivers). The other
+properties a non-default `DynamoEventSource` adds are recorded and left alone. Those are
+`ParallelizationFactor` and `TumblingWindowInSeconds`.
+The mapping deploys, delivers every record whole, and each property it was created
 without is listed in
 [`stack.ignoredProperties`](https://yulinsim.dev/services/cloudformation/#properties-a-resource-was-created-without "Properties a Resource was created without")
 with what the mapping does in its place. `CreateEventSourceMapping` still refuses the same
@@ -2531,6 +2537,137 @@ 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.
 
+## Filtering the records a mapping delivers
+
+`FilterCriteria` on an event source mapping decides which records reach the function. A record that
+matches is delivered. One that does not is treated as handled. A stream moves its checkpoint past it
+and a queue deletes it, the way real Lambda handles a record it filtered out. A batch that comes back
+empty invokes nothing at all.
+
+AWS documents Lambda's filter rules as EventBridge event patterns, and simulated EventBridge's
+matcher is what evaluates them here. Exact values, `prefix`, `suffix`, `anything-but`, `numeric` and
+`exists` all work. A mapping naming an operator the matcher has no behaviour for is refused when it
+is created. A mapping carrying several filters delivers a record any one of them matches.
+
+What a pattern reads depends on the source:
+
+- **SQS** filters on `body` alone, as real Lambda does. A body holding JSON is read as the object it
+  parses to, and one holding anything else is read as the string it is. A pattern naming any other
+  key is refused when the mapping is created.
+- **DynamoDB streams** filter on the record the function would have received, so `eventName` and
+  `dynamodb.NewImage.status.S` both work, with the attribute values in their DynamoDB shapes.
+- **Kinesis streams** filter on the record with the payload decoded, under a top-level `data` key.
+  The payload has to hold JSON for a pattern to read inside it.
+
+```typescript sim-lambda-event-source-filter-criteria
+/**
+ * Delivering only the queue messages a filter matches.
+ */
+
+import { CreateRoleCommand, PutRolePolicyCommand } from "@aws-sdk/client-iam";
+import {
+  CreateEventSourceMappingCommand,
+  CreateFunctionCommand,
+} from "@aws-sdk/client-lambda";
+import { CreateQueueCommand, SendMessageCommand } from "@aws-sdk/client-sqs";
+
+import { SimAws } from "@kensio/yulin";
+import {
+  makeLambdaZipFileInput,
+  type SimLambdaSqsEvent,
+} from "@kensio/yulin/lambda";
+
+const simAws = new SimAws();
+const queueArn = `arn:aws:sqs:${simAws.defaultRegionName}:${simAws.defaultAccountId}:orders`;
+
+const { QueueUrl } = await simAws
+  .sqs()
+  .createQueue(new CreateQueueCommand({ QueueName: "orders" }));
+
+const role = await simAws.iam().createRole(
+  new CreateRoleCommand({
+    RoleName: "ShippedOrdersRole",
+    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: "ShippedOrdersRole",
+    PolicyName: "ConsumeOrders",
+    PolicyDocument: JSON.stringify({
+      Version: "2012-10-17",
+      Statement: {
+        Effect: "Allow",
+        Action: [
+          "sqs:ReceiveMessage",
+          "sqs:DeleteMessage",
+          "sqs:GetQueueAttributes",
+        ],
+        Resource: queueArn,
+      },
+    }),
+  }),
+);
+
+const shipped: string[] = [];
+
+await simAws.lambda().createFunction(
+  new CreateFunctionCommand({
+    FunctionName: "shipped-orders",
+    Role: role.Role.Arn,
+    Code: {
+      ZipFile: makeLambdaZipFileInput((event: SimLambdaSqsEvent) => {
+        for (const record of event.Records) {
+          shipped.push(
+            (JSON.parse(record.body) as { orderId: string }).orderId,
+          );
+        }
+      }),
+    },
+  }),
+);
+
+await simAws.lambda().createEventSourceMapping(
+  new CreateEventSourceMappingCommand({
+    EventSourceArn: queueArn,
+    FunctionName: "shipped-orders",
+    FilterCriteria: {
+      Filters: [{ Pattern: JSON.stringify({ body: { status: ["shipped"] } }) }],
+    },
+  }),
+);
+
+for (const order of [
+  { orderId: "order-1", status: "placed" },
+  { orderId: "order-2", status: "shipped" },
+]) {
+  await simAws
+    .sqs()
+    .sendMessage(
+      new SendMessageCommand({ QueueUrl, MessageBody: JSON.stringify(order) }),
+    );
+}
+
+await simAws.backgroundTasksComplete();
+
+console.log(shipped); // ["order-2"]
+```
+
+`GetEventSourceMappingCommand` reports the patterns back as they were written. A mapping created
+without filters reports none.
+
+An `AWS::Lambda::EventSourceMapping` carrying `FilterCriteria` deploys with it, and so does a SAM
+function's queue or stream event. A CDK `SqsEventSource` or `DynamoEventSource` given `filters`
+therefore filters here the way it does deployed.
+
 ## Function URLs
 
 A Function URL is an HTTP endpoint for one function. Creating one with
@@ -4199,6 +4336,8 @@ Sim Lambda currently supports:
   `CreateEventSourceMappingCommand` and read with `GetEventSourceMappingCommand`,
   `ListEventSourceMappingsCommand` and `DeleteEventSourceMappingCommand`, delivering real-shaped SQS,
   DynamoDB stream and Kinesis events and honouring `BatchSize`
+- `FilterCriteria` on any of those mappings, evaluated with EventBridge event patterns, delivering
+  the records that match and handling the rest without an invocation
 - `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
@@ -4361,7 +4500,7 @@ 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. `CreateEventSourceMapping` also refuses
-  `FilterCriteria`, `ScalingConfig`, `ParallelizationFactor`, `TumblingWindowInSeconds` and the
+  `ScalingConfig`, `ParallelizationFactor`, `TumblingWindowInSeconds` and the
   other inputs this simulation has no behaviour for. An
   `AWS::Lambda::EventSourceMapping` naming any of them deploys instead, and records each one against
   the Resource (see
@@ -4377,9 +4516,14 @@ Current documented limitations:
   AWS counts a bisected batch's deliveries against the same quota. Without that, the simulator's own
   cap of five attempts would discard a batch of a hundred long before it was down to one record. The
   splitting still ends on its own, because a batch halves at every step.
-- 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.
+- Ten deliveries in a row, each one brought on by the handler's own writes to the source that
+  invoked it, are refused with `SimLambdaStreamCascadeError`. Real Lambda runs that loop for as long
+  as it is paid for. A handler that writes back and then settles is delivered its own writes and
+  finishes.
+- `FilterCriteria` is evaluated by simulated EventBridge's pattern matcher, which leaves out the
+  `equals-ignore-case` and `$or` operators real Lambda takes. A pattern naming one is refused when
+  the mapping is created. The limits AWS puts on the number and length of patterns go unenforced,
+  and `KMSKeyArn` is refused, so criteria are held in plaintext.
 - A shard iterator never expires, where a real one is good for 15 minutes.
 - `MaximumBatchingWindowInSeconds` is only simulated as 0. A partial batch is delivered as soon as
   anything is on the event source, leaving a batching window nothing to wait for. A non-zero value

package/docs/services/scheduler/README.md

@@ -61,10 +61,38 @@ Scheduler accepts three expression forms:
 - `rate(<value> <unit>)` runs from when the schedule was created. The unit is `minute`, `hour` or
   `day`, and Scheduler lets it disagree with its value. `rate(1 hours)` is an hour here and a
   refusal on an EventBridge rule.
-- `cron(<six fields>)` names absolute instants in UTC. Minutes, hours, day-of-month, month,
-  day-of-week and year, so every day at two in the morning is `cron(0 2 * * ? *)`. The day-of-month
-  and day-of-week fields cannot both say something. Whichever is not deciding the day is written
-  `?`.
+- `cron(<six fields>)` names a wall-clock time. Minutes, hours, day-of-month, month, day-of-week and
+  year, so every day at two in the morning is `cron(0 2 * * ? *)`. The day-of-month and day-of-week
+  fields cannot both say something. Whichever is not deciding the day is written `?`.
+
+### The zone a schedule runs in
+
+`ScheduleExpressionTimezone` says which zone the wall-clock time belongs to, and a schedule created
+without one runs in UTC. Any IANA name the host's own `Intl` timezone data recognises works, and a
+name it does not is refused when the schedule is created.
+
+```typescript
+await simAws.scheduler().createSchedule(
+  new CreateScheduleCommand({
+    Name: "nightly-rollup",
+    ScheduleExpression: "cron(0 2 * * ? *)",
+    ScheduleExpressionTimezone: "Europe/London",
+    FlexibleTimeWindow: { Mode: "OFF" },
+    Target: { Arn: functionArn, RoleArn: roleArn },
+  }),
+);
+```
+
+That schedule is due at 01:00 UTC through British Summer Time and at 02:00 UTC through the winter,
+which is what a nightly job written for a zone actually does. The two days a year a zone changes
+offset are read the same way. A schedule keeps its hour on the clock across both.
+
+The hour the clocks move takes the rule real Scheduler uses. A wall-clock time inside the hour that
+never happens falls due at the first instant after it (02:30 on the morning the clocks go forward
+fires at 03:30). A wall-clock time the clocks read twice falls due once, at the first of the two
+readings.
+
+`GetSchedule` reports the zone back as it was written.
 
 ## Firing a schedule
 
@@ -819,8 +847,9 @@ Resources of the same stack.
 - `FlexibleTimeWindow` with `Mode: "FLEXIBLE"` is refused. Real Scheduler invokes the target at an
   unpredictable moment inside the window, and firing at the exact due time instead would let a test
   rely on timing AWS leaves unpromised.
-- `ScheduleExpressionTimezone` other than `UTC` is refused outright, since running a schedule in the
-  wrong zone fires it at the wrong hour.
+- `ScheduleExpressionTimezone` is read from the host's own timezone data through `Intl`, so a zone
+  the host has never heard of is refused even where AWS would take it. A schedule that names none
+  runs in UTC.
 - `StartDate` and `EndDate` are refused outright.
 - Targets are Lambda, SQS, SNS and ECS. The universal target
   (`arn:aws:scheduler:::aws-sdk:<service>:<action>`) and every other target service are refused when

package/package.json

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