@kensio/yulin 1.21.26 → 1.21.27

package/docs/services/eventbridge/README.md

@@ -921,6 +921,91 @@ and a rule routes the same events whether it carries them or not. They are recor
 property and the deploy stands. Nothing reads them back. A rule or a bus deployed with tags behaves
 as though the template had never named them.
 
+## Receiving events from a SaaS partner
+
+A SaaS partner such as Stripe sends events to an account through a partner event source, named like
+`aws.partner/stripe.com/ed_...`. The partner creates the source from its own account, so a test
+shares one with `addPartnerEventSource(...)`. The account then creates a partner event bus with the
+same `Name` and `EventSourceName`, and `putPartnerEvents(...)` sends events onto it as the partner
+would.
+
+```typescript sim-event-bridge-partner-events
+/**
+ * Receiving Stripe's events on a partner event bus.
+ */
+
+import {
+  CreateEventBusCommand,
+  PutPartnerEventsCommand,
+  PutRuleCommand,
+} from "@aws-sdk/client-eventbridge";
+
+import { SimAws } from "@kensio/yulin";
+
+const simAws = new SimAws();
+const events = simAws.eventBridge();
+const source = "aws.partner/stripe.com/ed_test_billing";
+
+// What Stripe does when an event destination is set up for the account.
+events.addPartnerEventSource(source);
+
+// What the account does to receive from it.
+await events.createEventBus(
+  new CreateEventBusCommand({ Name: source, EventSourceName: source }),
+);
+await events.putRule(
+  new PutRuleCommand({
+    Name: "subscriptions",
+    EventBusName: source,
+    EventPattern: JSON.stringify({
+      source: [{ prefix: "aws.partner/stripe.com" }],
+      "detail-type": ["customer.subscription.created"],
+    }),
+  }),
+);
+
+// What Stripe sends when a subscription starts.
+await events.putPartnerEvents(
+  new PutPartnerEventsCommand({
+    Entries: [
+      {
+        Source: source,
+        DetailType: "customer.subscription.created",
+        Detail: JSON.stringify({
+          id: "evt_test_subscription",
+          type: "customer.subscription.created",
+          data: { object: { id: "sub_test" } },
+        }),
+      },
+    ],
+  }),
+);
+
+console.log(events.receiptsOn(source)[0]?.matchedRuleNames); // ["subscriptions"]
+```
+
+`putPartnerEvents(...)` takes the entries of the partner's `PutPartnerEvents` request. Each entry's
+`Source` names a shared source, and the event goes to the bus of the same name. Rules match it on
+`source`, `detail-type` and `detail` like any other event. A target receives the usual envelope, with
+`account` set to the receiving account. Stripe puts its event type in `DetailType` and the whole
+Stripe event object, as JSON, in `Detail`. An entry whose `Source` names no shared source fails the
+whole request with `ResourceNotFoundException`.
+
+An `AWS::Events::EventBus` with `Name` and `EventSourceName` both set to the source name creates the
+same bus from a template, and a rule names it with a `Ref` to the bus.
+
+The source has to be shared before the bus is created. `CreateEventBus` fails with
+`ResourceNotFoundException` when it is missing, and a template creating the bus fails its stack, as
+both do on AWS. A `Name` that differs from the `EventSourceName` is a `ValidationException`, as is a
+`/` in the name of a bus created without one.
+
+`DescribeEventSource` reports the source as `PENDING` until its bus exists, and `ACTIVE` after.
+Deleting the bus puts it back to `PENDING`. An event sent while the source is pending is dropped,
+as AWS documents.
+
+Only the partner sends events to a partner event bus. `PutEvents` naming one is refused with a
+`ValidationException` (its `EventBusName` takes no `/`).
+
 ## Reading back a failed delivery
 
 Real EventBridge tells the caller nothing about a failed delivery. A `PutEvents` that matched a rule
@@ -981,6 +1066,125 @@ no is a modelled outcome a test may be asking for on purpose.
 `JSON.stringify` on a failure carries the message alongside the rule, the target and the event it
 names.
 
+## Retrying and dead-lettering a delivery
+
+A target can carry a `RetryPolicy` and a `DeadLetterConfig`, from `PutTargets` or from a target in an
+`AWS::Events::Rule`. The dead-letter queue receives an event once EventBridge gives up delivering it.
+
+```typescript sim-event-bridge-dead-letter
+/**
+ * Sending an event a target refused to its dead-letter queue.
+ */
+
+import {
+  PutEventsCommand,
+  PutRuleCommand,
+  PutTargetsCommand,
+} from "@aws-sdk/client-eventbridge";
+import {
+  CreateQueueCommand,
+  ReceiveMessageCommand,
+  SetQueueAttributesCommand,
+} from "@aws-sdk/client-sqs";
+
+import { SimAws } from "@kensio/yulin";
+
+const simAws = new SimAws();
+const dlqArn = "arn:aws:sqs:us-east-1:888888888888:undelivered-orders";
+
+// A dead-letter queue admitting EventBridge for the rule.
+const { QueueUrl } = await simAws
+  .sqs()
+  .createQueue(new CreateQueueCommand({ QueueName: "undelivered-orders" }));
+await simAws.sqs().setQueueAttributes(
+  new SetQueueAttributesCommand({
+    QueueUrl,
+    Attributes: {
+      Policy: JSON.stringify({
+        Version: "2012-10-17",
+        Statement: [
+          {
+            Effect: "Allow",
+            Principal: { Service: "events.amazonaws.com" },
+            Action: "sqs:SendMessage",
+            Resource: dlqArn,
+            Condition: {
+              ArnEquals: {
+                "aws:SourceArn":
+                  "arn:aws:events:us-east-1:888888888888:rule/orders",
+              },
+            },
+          },
+        ],
+      }),
+    },
+  }),
+);
+
+// A target queue that was never created, so every delivery fails.
+await simAws.eventBridge().putRule(
+  new PutRuleCommand({
+    Name: "orders",
+    EventPattern: JSON.stringify({ source: ["orders.service"] }),
+  }),
+);
+await simAws.eventBridge().putTargets(
+  new PutTargetsCommand({
+    Rule: "orders",
+    Targets: [
+      {
+        Id: "fulfilment",
+        Arn: "arn:aws:sqs:us-east-1:888888888888:fulfilment",
+        RetryPolicy: { MaximumRetryAttempts: 2 },
+        DeadLetterConfig: { Arn: dlqArn },
+      },
+    ],
+  }),
+);
+
+await simAws.eventBridge().putEvents(
+  new PutEventsCommand({
+    Entries: [
+      { Source: "orders.service", DetailType: "OrderPlaced", Detail: "{}" },
+    ],
+  }),
+);
+await simAws.backgroundTasksComplete();
+
+const { Messages } = await simAws
+  .sqs()
+  .receiveMessage(
+    new ReceiveMessageCommand({ QueueUrl, MessageAttributeNames: ["All"] }),
+  );
+
+console.log(Messages?.[0]?.MessageAttributes?.["ERROR_CODE"]?.StringValue);
+// "NO_RESOURCE"
+```
+
+The message body is the event, as JSON. Its attributes are the ones EventBridge documents.
+`RULE_ARN` and `TARGET_ARN` name where the event was going. `ERROR_CODE` and `ERROR_MESSAGE` say why
+it failed, and `RETRY_ATTEMPTS` counts the retries made. `EXHAUSTED_RETRY_CONDITION` is
+`MaximumRetryAttempts` or `MaximumEventAgeInSeconds` when a retry limit ran out.
+
+`ERROR_CODE` is `NO_PERMISSIONS` for a target that refused EventBridge and `NO_RESOURCE` for one
+that is not there. Every other failure is `ERROR_FROM_TARGET`. EventBridge lists these codes
+without saying which failure gets which.
+
+A missing target and a refusal are never retried, because the same request gets the same answer.
+EventBridge sends both straight to the dead-letter queue, and so does Yulin. Any other failure is
+retried on the simulation's clock. The first retry is due one second after the failed attempt, and
+each following wait doubles to 2, 4, 8 seconds and so on. Retries stop at `MaximumRetryAttempts`, or
+once the event is `MaximumEventAgeInSeconds` old. A retry only runs as `advanceBy(...)` moves the
+clock past it.
+
+EventBridge sends to the dead-letter queue as `events.amazonaws.com`, with the rule ARN as
+`aws:SourceArn`, so the queue policy has to admit it. A dead-letter queue that is missing or refuses
+EventBridge leaves the failure in `deliveryFailures`. An event that reached its dead-letter queue
+leaves nothing there.
+
+A Lambda target is invoked asynchronously. Once Lambda accepts the invocation the delivery is done,
+and a handler error is left to the function's own retries and destinations.
+
 ## Permissions
 
 Most operations are authorized by simulated IAM against the bus ARN. The two that name no bus
@@ -1048,6 +1252,8 @@ no permission for.
 ## Supported operations
 
 - `CreateEventBus`, `DeleteEventBus`, `DescribeEventBus`, `ListEventBuses` and `PutEvents`.
+- Partner event buses created with `EventSourceName`, and `DescribeEventSource`. A test acts as the
+  partner through `addPartnerEventSource(...)` and `putPartnerEvents(...)`.
 - `PutRule`, `DeleteRule`, `DescribeRule`, `ListRules`, `EnableRule`, `DisableRule` and
   `TestEventPattern`.
 - Scheduled rules, with a `rate(...)` or six-field `cron(...)` `ScheduleExpression`, fired by
@@ -1061,6 +1267,8 @@ no permission for.
 - Targets in another account or region of the same simulation, admitted by the target's own resource
   policy on `aws:SourceArn` or `aws:SourceAccount`, as real EventBridge does.
 - A target's fixed `Input`, and `deliveryFailures` for a delivery that failed.
+- A target's `RetryPolicy`, retried on the simulation's clock, and its `DeadLetterConfig`, with the
+  dead-letter message attributes EventBridge documents.
 - The `default` bus in every account and region, without one being created.
 - Bus descriptions, creation timestamps from the simulation's clock, and prefix-narrowed paged
   listings.
@@ -1073,9 +1281,13 @@ no permission for.
 
 - Targets deliver to Lambda, SQS and SNS, and run a task in ECS. A target ARN naming any other
   service is refused as the target is added, ahead of any matching event.
-- Target `InputPath` and `InputTransformer` are refused, as are dead letter queues and retry
-  policies. A delivery is attempted once. A target `RoleArn` is refused except on an ECS target.
-  That is the one target type that runs as a role, where the others run as the service principal.
+- Target `InputPath` and `InputTransformer` are refused. A target `RoleArn` is refused except on an
+  ECS target. That is the one target type that runs as a role, where the others run as the service
+  principal.
+- A target with no `RetryPolicy` is delivered once. Real EventBridge retries such a target for up to
+  24 hours and 185 times. Retry waits are deterministic powers of two seconds, where real
+  EventBridge uses exponential backoff with jitter. The fixed sequence lets a test move the clock to
+  a known retry.
 - An ECS target's `EcsParameters` takes `TaskDefinitionArn` and `TaskCount`, and takes and ignores
   `LaunchType`, `PlatformVersion`, `NetworkConfiguration` and `CapacityProviderStrategy`, since
   there is no placement and no network here for them to apply to. Anything else it can carry, such
@@ -1115,8 +1327,13 @@ no permission for.
   attribute are all missing, and a caller from another account cannot be admitted to a bus. That is
   stricter than real AWS.
 - Putting an event onto another account's or region's bus is refused.
-- Partner event buses and partner event sources are refused, as are event bus tags, encryption with
-  a customer managed key, dead letter queues, logging configuration and global endpoints. An
-  `AWS::Events::EventBus` carrying `Tags` deploys with the tags dropped and the property recorded.
+- Event bus tags, encryption with a customer managed key, dead letter queues, logging configuration
+  and global endpoints are refused. An `AWS::Events::EventBus` carrying `Tags` deploys with the tags
+  dropped and the property recorded.
+- A pending partner event source never expires, and `DescribeEventSource` leaves out
+  `ExpirationTime`. Its `CreatedBy` is the segment after `aws.partner/`, such as `stripe.com`.
+  `ListEventSources`, `ActivateEventSource` and `DeactivateEventSource` are absent, as are the
+  partner's own commands. A partner is a test calling `addPartnerEventSource(...)` and
+  `putPartnerEvents(...)`.
 - Archives, replay, schema registry and discovery, API destinations and connections are not
   simulated.

package/package.json

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