@kensio/yulin 1.21.7 → 1.21.9

package/docs/services/scheduler/README.md

@@ -1,14 +1,12 @@
 # Simulated EventBridge Scheduler
 
-Yulin includes a simulated Amazon EventBridge Scheduler for tests and local development. Schedules
-are held in memory and every operation is authorized by simulated IAM. Scheduler-specific types are
-imported from the `@kensio/yulin/scheduler` subpath.
+Yulin simulates Amazon EventBridge Scheduler in memory. Schedules run when simulated time advances,
+and every management operation is authorized by simulated IAM. Import Scheduler-specific types from
+`@kensio/yulin/scheduler`.
 
-Scheduler is a separate service from [EventBridge](https://yulinsim.dev/services/eventbridge/), not a corner of it. It has its
-own SDK client, its own ARN shape, and its own way of reaching a target. A schedule assumes an IAM
-execution role, where an EventBridge rule relies on a resource policy admitting a service principal.
-A project using Scheduler cannot be tested against simulated EventBridge rules. That is why this
-exists separately.
+Scheduler is separate from [EventBridge](https://yulinsim.dev/services/eventbridge/). It uses its own
+SDK client and ARN format. It also assumes an execution role to invoke a target, while EventBridge
+rules use the target's resource policy.
 
 ## Creating a schedule
 
@@ -56,8 +54,7 @@ IAM policy naming a schedule needs the group in it, or it matches no schedule.
 
 ## Writing the schedule expression
 
-Three forms, and the same parser as an [EventBridge scheduled
-rule](https://yulinsim.dev/services/eventbridge/#rules-that-fire-on-a-schedule) with two differences:
+Scheduler accepts three expression forms:
 
 - `at(yyyy-mm-ddThh:mm:ss)` runs once, at that instant. The timezone is a separate setting on the
   schedule, outside the expression, and a trailing `Z` is refused.
@@ -71,9 +68,7 @@ rule](https://yulinsim.dev/services/eventbridge/#rules-that-fire-on-a-schedule)
 
 ## Firing a schedule
 
-A schedule fires on the simulation's clock. Advancing simulated time past a due
-instant invokes the target. Leave time alone and the target is never invoked. A nightly job takes no
-time at all to test.
+A schedule fires on the simulation's clock. Advance time past a due instant to invoke the target.
 
 ```typescript sim-scheduler-firing
 /**
@@ -163,12 +158,11 @@ own to describe.
 
 ### The execution role
 
-This is the part that differs most from an [EventBridge rule](https://yulinsim.dev/services/eventbridge/), and the part that
-most often goes wrong in a real account. A rule reaches its target as the `events.amazonaws.com`
-service principal, and the target's own resource policy decides. A schedule assumes the `RoleArn` on
-its target, and that role's policies decide. No resource policy on the target is involved at all.
+A schedule assumes the target's `RoleArn`, and that role's policies authorize delivery. An
+[EventBridge rule](https://yulinsim.dev/services/eventbridge/) instead invokes as
+`events.amazonaws.com` and depends on the target's resource policy.
 
-Two things therefore have to be right, and they are fixed in different places:
+The execution role needs both:
 
 - The role's **trust policy** has to let `scheduler.amazonaws.com` assume it. A role copied from an
   EventBridge rule trusts `events.amazonaws.com` and fails here.
@@ -176,14 +170,13 @@ Two things therefore have to be right, and they are fixed in different places:
   `sqs:SendMessage`, `sns:Publish` or `ecs:RunTask`.
 
 A trust policy may also carry the condition AWS recommends against the confused deputy problem. The
-schedule's group ARN is supplied as `aws:SourceArn`, and the Account the schedule is in as
-`aws:SourceAccount`. A role scoped to one schedule group is assumable by schedules in that group and
-by nothing else. CDK writes that condition into the execution roles it generates for a schedule
-target, so a role taken from a synthesized template works here unchanged.
+schedule's group ARN is supplied as `aws:SourceArn`, and the account is supplied as
+`aws:SourceAccount`. A role scoped to one schedule group is assumable only by schedules in that
+group. CDK writes that condition into the execution roles it generates for a schedule target, so a
+role from a synthesized template works unchanged.
 
-When either is missing the target goes uninvoked and no error is thrown, exactly as on AWS, where the
-failure goes to CloudWatch and nowhere the caller can see. `advanceBy(...)` still returns normally. A
-test asserting on a failed invocation reads `deliveryFailures`:
+If either permission is missing, `advanceBy(...)` still returns normally and the target is not
+invoked. Read `deliveryFailures` to assert on the failed delivery:
 
 ```typescript sim-scheduler-delivery-failures
 /**
@@ -256,9 +249,8 @@ following delay doubles to 2, 4, 8 seconds and so on. A retry does not run while
 still. `advanceBy(...)` runs every retry that becomes due in the interval and settles their work
 before it returns.
 
-Scheduler does not retry a failure that cannot clear by trying the same request. A missing target,
-a missing execution role, an execution role that does not trust Scheduler and an IAM denial are
-permanent failures. They are abandoned after the initial attempt.
+Scheduler retries only failures that may clear. A missing target, missing execution role, invalid
+trust policy, or IAM denial is permanent and is abandoned after the initial attempt.
 
 Set `Target.DeadLetterConfig.Arn` to a standard SQS queue ARN to keep an input that Scheduler abandons.
 The execution role needs `sqs:SendMessage` on this queue as well as permission to invoke the target.
@@ -267,19 +259,17 @@ shape and include the error, schedule ARN, target ARN, scheduled time and retry
 `EXHAUSTED_RETRY_CONDITION` is `MaximumRetryAttempts` or `MaximumEventAgeInSeconds` for an exhausted
 retryable failure. A permanent failure leaves that attribute out.
 
-A successful DLQ send does not add an entry to `deliveryFailures`, since the configured destination
-received the input. A missing queue or denied `sqs:SendMessage` is recorded there instead. This keeps
-a misconfigured DLQ visible to a test.
+A successful DLQ send leaves `deliveryFailures` empty because the configured destination received the
+input. A missing queue or denied `sqs:SendMessage` is recorded there instead.
 
 ### One-time schedules and what happens after
 
-An `at(...)` schedule fires once and then stops. By default it stays in the Account afterwards, which
-surprises people who expected it to clean up. It keeps counting against the schedule quota and keeps
-turning up in listings. `ActionAfterCompletion: "DELETE"` is what removes it, and after that
-`GetSchedule` reports it gone.
+An `at(...)` schedule fires once. It remains in the account unless
+`ActionAfterCompletion: "DELETE"` removes it. A retained schedule continues to appear in listings
+and count against the schedule quota.
 
-A schedule that is disabled when its only instant passes has not completed, since nothing was
-invoked. It is still there afterwards whatever `ActionAfterCompletion` says.
+A disabled schedule remains incomplete when its only instant passes. It stays in the account
+regardless of `ActionAfterCompletion`.
 
 `State: "DISABLED"` stops a recurring schedule firing while it is off, and an `UpdateSchedule`
 enabling it picks up from the next due instant. What it missed is never replayed. An update that
@@ -287,9 +277,8 @@ changes the expression reschedules from the new one.
 
 ## Running an ECS task on a schedule
 
-A target whose ARN names an ECS cluster runs a [simulated ECS](https://yulinsim.dev/services/ecs/) task, in place of being
-invoked with a payload. That is the shape a nightly batch job usually has. A container runs, does
-its work and stops.
+A target whose ARN names an ECS cluster runs a [simulated ECS](https://yulinsim.dev/services/ecs/)
+task. Use `EcsParameters` to select the task definition and use `Input` for task overrides.
 
 ```typescript sim-scheduler-ecs-target
 /**
@@ -404,8 +393,8 @@ target with no `Input` runs the task with no overrides.
 
 [Simulated ECS](https://yulinsim.dev/services/ecs/) decides which containers actually run. A container
 with a binding runs its handler, and a container without one is recorded as not simulated.
-A target naming a task definition with nothing bound therefore records a task that never started,
-and the schedule counts as invoked.
+A target naming a task definition without a bound container records a task that never started, and
+the schedule counts as invoked.
 
 ## Updating and deleting
 
@@ -457,8 +446,8 @@ console.log(described.ScheduleExpression); // "rate(30 minutes)"
 console.log(described.Description); // undefined, and not by accident
 ```
 
-`UpdateSchedule` carries the whole of a schedule, and anything an earlier request set and this one
-leaves out is gone. That is real behaviour and a common surprise. The schedule has to exist.
+`UpdateSchedule` replaces the full schedule definition. Any optional value omitted from the update
+is removed. The schedule must already exist.
 Updating one that is absent raises `ResourceNotFoundException`. EventBridge's `PutRule` creates it.
 
 `CreateSchedule` for a name that already exists raises `ConflictException`. A deployment running it
@@ -618,10 +607,10 @@ against the `RoleArn` on the target.
 
 ## Deploying from a CloudFormation template
 
-`AWS::Scheduler::Schedule` deploys through [simulated CloudFormation](https://yulinsim.dev/services/cloudformation/). A stack
-that declares its schedules can be exercised end to end, with no SDK calls of its own. Everything the
-Resource carries lines up with `CreateSchedule`, and a target ARN or execution role resolved by
-`Fn::GetAtt` from the same template works as it would in a real deployment.
+`AWS::Scheduler::Schedule` deploys through [simulated
+CloudFormation](https://yulinsim.dev/services/cloudformation/). Its properties follow
+`CreateSchedule`, and the target ARN or execution role can use `Fn::GetAtt` references to resources
+in the same template.
 
 ```typescript sim-scheduler-cloudformation
 /**
@@ -786,7 +775,7 @@ anyway. Read the record back from `stack.getResource("<logicalId>")?.ignoredProp
 Tearing the stack down removes the group. Its schedules go with it, whether or not they are
 Resources of the same stack.
 
-## Available functionality
+## Supported operations
 
 - `CreateSchedule`, `GetSchedule`, `UpdateSchedule`, `DeleteSchedule` and `ListSchedules`.
 - `at(...)`, `rate(...)` and six-field `cron(...)` expressions, fired by advancing the simulation's
@@ -839,7 +828,7 @@ Resources of the same stack.
 - A target `EventBridgeParameters`, `KinesisParameters`, `SageMakerPipelineParameters` and
   `SqsParameters` are refused outright, as is `EcsParameters` on a target whose ARN names something
   other than an ECS cluster. A `DeadLetterConfig` must name a standard SQS queue because simulated
-  SQS does not support FIFO queues.
+  SQS supports only standard queues.
 - 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
@@ -849,5 +838,5 @@ Resources of the same stack.
   on an ECS target, where every other target type takes any text.
 - A `TaskCount` above one runs that many simulated tasks, and a bound container handler runs once
   for each of them, in this process and one after another.
-- `KmsKeyArn` is refused, and `ClientToken` is accepted and ignored. Schedule management requests
-  are not retried, so the token has no request to make idempotent.
+- `KmsKeyArn` is refused, and `ClientToken` is accepted and ignored. Yulin makes each schedule
+  management request once, so the token has no retry to make idempotent.

package/docs/services/secretsmanager/README.md

@@ -1,7 +1,7 @@
 # Simulated Secrets Manager
 
-Yulin includes a simulated AWS Secrets Manager for tests and local development. Secrets are stored
-in memory, versioned by staging label, and every operation is authorized by simulated IAM.
+Yulin simulates AWS Secrets Manager in memory. Secrets have encrypted versions and staging labels,
+and simulated IAM authorizes every operation.
 
 Secrets Manager-specific types are imported from the `@kensio/yulin/secretsmanager` subpath.
 
@@ -45,19 +45,14 @@ on read.
 
 ## Encryption and KMS permissions
 
-Every version is encrypted through simulated KMS when it is written and decrypted when
-`GetSecretValue` reads it. There is no flag for reading a secret without decrypting it. The read
-either returns the plaintext or fails.
+Every secret version is encrypted through simulated KMS. `GetSecretValue` decrypts the version and
+either returns its plaintext or fails.
 
-A secret naming no `KmsKeyId` uses the `aws/secretsmanager` AWS managed key, which asks the caller
-for no KMS permission at all. Secrets Manager supplies `kms:ViaService`, and that key's policy allows
-the account's principals to use it through Secrets Manager. A Lambda role granted only
-`secretsmanager:GetSecretValue` therefore reads the secret, as it does on real AWS.
+A secret without `KmsKeyId` uses the `aws/secretsmanager` AWS managed key. Its policy permits use
+through Secrets Manager, so callers do not need a separate KMS permission.
 
-Pass `KmsKeyId` to encrypt under a customer managed key instead, and the caller's own permissions on
-that key start to matter. Secrets Manager uses envelope encryption, asking KMS for a data key per
-version. A write needs `kms:GenerateDataKey` and a read needs `kms:Decrypt`. A role granted the
-secret but not the key fails here, ahead of a deployment.
+Pass `KmsKeyId` to use a customer managed key. Writing a version requires `kms:GenerateDataKey`, and
+reading it requires `kms:Decrypt`, in addition to the relevant Secrets Manager permission.
 
 ```typescript sim-secrets-manager-customer-key
 /**
@@ -141,10 +136,9 @@ they were made with and stay readable, as they do on real AWS.
 
 ## Secret ARNs and IAM policies
 
-Real Secrets Manager appends a hyphen and six random characters to the secret name in its ARN. A
-secret named `db-creds` gets an ARN ending `:secret:db-creds-AbCdEf`, and sim Secrets Manager does
-the same. A policy naming the bare ARN therefore matches nothing, and a policy has to end in
-`-??????` or a wildcard.
+Secret ARNs end with a hyphen and six random characters. A secret named `db-creds`, for example,
+gets an ARN ending in `:secret:db-creds-AbCdEf`. An IAM resource pattern for the secret must include
+that suffix, such as `-??????` or `-*`.
 
 ```typescript sim-secrets-manager-iam-policy
 /**
@@ -214,17 +208,16 @@ nothing, here as there.
 
 ## Naming a secret
 
-Every operation takes its target as a `SecretId`, in any of the three forms real Secrets Manager
-accepts. Those are the friendly name, the full ARN including the suffix, and the partial ARN without
-it.
+`SecretId` accepts the friendly name, the full ARN with its random suffix, or the partial ARN without
+the suffix.
 
 An ARN naming another account or region resolves to no secret at all. Its name is never read out and
 looked up locally, and a foreign ARN cannot reach a secret that happens to share a name.
 
 ## Versions and staging labels
 
-Every write creates a version, leaving the earlier ones in place. `AWSCURRENT` names the version a
-plain read returns, and writing a new current version demotes the previous one to `AWSPREVIOUS`.
+Every write creates a version. `AWSCURRENT` marks the version returned by a plain read. Writing a new
+current version moves `AWSPREVIOUS` to the former current version.
 
 ```typescript sim-secrets-manager-staging-labels
 /**
@@ -273,12 +266,9 @@ label. A version that has lost every label is on its way out of existence, and i
 
 ## Deletion and the recovery window
 
-`DeleteSecret` schedules deletion for later. The recovery window is 7 to 30 days, defaulting to 30.
-During that window the secret is still there. It can be described and restored, it refuses to be
-read or written, and it still holds its name.
-
-Holding the name is what a redeployed stack hits. Advancing the simulated clock past the window frees
-it.
+`DeleteSecret` schedules deletion after a recovery window of 7 to 30 days, defaulting to 30. During
+that window the secret can be described or restored, but it cannot be read or changed. Its name also
+remains reserved. Advance simulated time past the window to complete deletion.
 
 ```typescript sim-secrets-manager-deletion
 /**
@@ -435,14 +425,14 @@ console.log(credentials.username); // "app"
 console.log(credentials.password?.length); // 24
 ```
 
-Generated passwords are random. A test reads the value back out of the simulation the way a deployed
-application does.
+Generated passwords are random. Read the deployed value through Secrets Manager instead of asserting
+on an exact password.
 
 ## Reading a secret with a dynamic reference
 
-A template reads a secret that already exists through a `{{resolve:secretsmanager:...}}` dynamic
-reference. The reference is replaced with the secret's value as the resource holding it is created.
-CDK emits one from `SecretValue.secretsManager`.
+A `{{resolve:secretsmanager:...}}` dynamic reference reads an existing secret while CloudFormation
+creates the resource containing the reference. CDK emits this form for
+`SecretValue.secretsManager`.
 
 The whole form is
 `{{resolve:secretsmanager:secret-id:secret-string:json-key:version-stage:version-id}}`. Only the
@@ -554,11 +544,10 @@ another resource of the same stack creates is only there in time when the templa
 Resource properties are reported as they resolved, including this one. Real CloudFormation keeps a
 resolved secret out of its own logs and events, and sim CloudFormation has no such protection.
 
-### A reference the simulation cannot answer
+### Unresolved references
 
-Simulated CloudFormation deploys what it can. A reference naming a secret that was never created
-resolves to `dummy-value-for-<secret-id>`, and the stack carries on deploying. A template reading a
-secret a test does not care about is still worth deploying for everything else in it.
+If Yulin cannot resolve a reference, it substitutes `dummy-value-for-<secret-id>` and continues the
+deployment.
 
 The substitution is recorded on
 [`stack.ignoredProperties`](https://yulinsim.dev/services/cloudformation/#properties-a-resource-was-created-without),
@@ -596,9 +585,7 @@ The same applies to `SimSdk` interception. Intercepting `SecretsManagerClient` r
 code into the simulation, served in process. See
 [AWS SDK interception](https://yulinsim.dev/sdk/ "Simulated AWS SDK docs").
 
-## Available functionality
-
-Sim Secrets Manager currently supports:
+## Supported operations
 
 - `CreateSecretCommand`, holding either a string or binary
 - `GetSecretValueCommand`, by staging label or by version id
@@ -619,8 +606,6 @@ Sim Secrets Manager currently supports:
 
 ## Limitations
 
-Current documented limitations:
-
 - A `KmsKeyId` is checked when a version is written under it, not when it is set on its own. An
   `UpdateSecret` changing only the key accepts a key that is absent, and the next write of a value
   fails.

package/docs/services/ses/README.md

@@ -1,20 +1,14 @@
 # Simulated SES
 
-Yulin includes a simulated Amazon SES for tests and local development, through the SES v2 API. It
-holds email identities, applies the sandbox rules, and keeps a record of every message it would have
-sent. A test can assert that signing someone up produced a welcome email addressed to them, without
-an AWS account and without a mailbox to read.
-
-There is no delivery to simulate. A message SES accepts leaves AWS for a mail system. The whole of
-the observable AWS behaviour is whether SES would have accepted the message and what it would have
-sent. That is what makes this service small and what makes it useful.
+Yulin simulates the Amazon SES v2 API in memory. It stores email identities, applies sandbox and
+suppression rules, renders templates, and records accepted messages. It does not deliver email.
 
 SES specific types are imported from the `@kensio/yulin/ses` subpath.
 
 ## Asserting on a message that was sent
 
-`sentEmails()` hands over the record. Each message carries who it was from, the three recipient
-lists, the subject, the body, its attachments and the message id SES answered with.
+Use `sentEmails()` to inspect accepted messages. Each record contains the sender, To/Cc/Bcc lists,
+subject, body, attachments, and message ID.
 
 ```typescript sim-ses-send-and-assert
 /**
@@ -115,9 +109,8 @@ console.log(
 
 ## Verifying identities
 
-Real SES verifies an email address by emailing it a link and a domain by looking for DNS records.
-Neither can happen inside a test process, so verification here is the simulator's own operation
-instead of an API call. `verifyIdentity` performs it, creating the identity where one is absent.
+SES normally verifies an address by email and a domain through DNS. In tests, call `verifyIdentity`
+instead. It creates the identity if necessary and marks it verified.
 
 Everything else about identities is the ordinary SES API. `CreateEmailIdentity` starts one, and it
 starts unverified, exactly as a real one does:
@@ -631,13 +624,10 @@ one answer whoever asked.
 
 ## The sandbox
 
-An account starts in the SES sandbox, where **both** the sender and every recipient have to be
-verified. That is the state most tests should be written against. It is the configuration that
-refuses to mail an address nobody verified, and catching that refusal in a test is much better than
-catching it in an account.
+An account starts in the SES sandbox. Both the sender and every recipient must be verified. Outside
+the sandbox, only the sender must be verified.
 
-Outside the sandbox only the sender is checked. `PutAccountDetails` with `ProductionAccessEnabled`
-is how an account gets there:
+Call `PutAccountDetails` with `ProductionAccessEnabled` to leave the sandbox:
 
 ```typescript sim-ses-sandbox
 /**
@@ -696,17 +686,12 @@ caller finds out everything it has to verify from one failure:
 Email address is not verified. The following identities failed the check in region US-EAST-1: someone@example.org
 ```
 
-Real SES treats `ProductionAccessEnabled` as a request that a human at AWS then reviews, and an
-account stays in the sandbox until that review lands. Granting it immediately is a deliberate
-divergence. The alternative is a simulator no test can get out of the sandbox in, and waiting for a
-review is beyond what a test can assert on anyway.
+Unlike AWS, Yulin grants production access immediately instead of waiting for a manual review.
 
 ## The suppression list
 
-Real SES holds an account-level suppression list and fills it from hard bounces and complaints.
-Tests supply that feedback explicitly with `recordFeedback`. Suppression commands manage the same
-list. The support tool that lists suppressed addresses, the form that removes one and the script
-that seeds the list all have somewhere to run.
+SES maintains an account suppression list for hard bounces and complaints. Tests add feedback with
+`recordFeedback`, and the suppression commands read and change the same list.
 
 `PutSuppressedDestination`, `GetSuppressedDestination`, `ListSuppressedDestinations` and
 `DeleteSuppressedDestination` manage it.
@@ -870,8 +855,7 @@ recorded.
 
 ## Messages on the console
 
-`sentEmails()` is test code. A dev server has the same messages going past and nothing to read them
-with, so `serveSimAws` prints a summary of each one as SES accepts it:
+For local development, `serveSimAws` prints a summary whenever SES accepts a message:
 
 ```
 sim SES: hello@example.com to alice@example.com, bcc audit@example.com
@@ -899,13 +883,12 @@ pool kept. Both services recorded it, and each block says what that service hold
 
 ## Permissions
 
-Every command authorizes through simulated IAM. A send authorizes against the identity being sent
-**from**, and recipients never enter into it. That is worth knowing when a policy looks like it
-should cover a send and fails to.
+Every command uses simulated IAM. A send authorizes against the sender identity, not the recipient
+addresses.
 
 ```typescript sim-ses-permissions
 /**
- * A Role that may only send from one domain.
+ * A Role that may only send from one address at a verified domain.
  */
 
 import { CreateRoleCommand, PutRolePolicyCommand } from "@aws-sdk/client-iam";
@@ -945,6 +928,9 @@ await simAws.iam().putRolePolicy(
           Effect: "Allow",
           Action: "ses:SendEmail",
           Resource: "arn:aws:ses:us-east-1:111111111111:identity/example.com",
+          Condition: {
+            StringEquals: { "ses:FromAddress": "hello@example.com" },
+          },
         },
       ],
     }),
@@ -953,7 +939,7 @@ await simAws.iam().putRolePolicy(
 
 await ses.sendEmail(
   new SendEmailCommand({
-    FromEmailAddress: "anything@example.com",
+    FromEmailAddress: "hello@example.com",
     Destination: { ToAddresses: ["someone@example.com"] },
     Content: {
       Simple: {
@@ -978,6 +964,10 @@ The more specific identity wins when both exist. A policy naming `identity/examp
 send from any address at the domain, unless that address is an identity in its own right, in which
 case the send authorizes against `identity/hello@example.com` instead.
 
+`ses:FromAddress` carries the bare `FromEmailAddress`. A policy can use it to allow one address at a
+verified domain. A display name does not change the value. For example, `Welcome team
+<hello@example.com>` supplies `hello@example.com` to IAM.
+
 `ses:ListEmailIdentities`, `ses:GetAccount` and `ses:PutAccountDetails` have no resource type at all
 on real SES, and only a policy written against `*` allows them. A policy scoped to identity ARNs
 allows none of the three. Not even one written against `identity/*`, the intuitive reading and the

package/docs/services/sns/README.md

@@ -1,14 +1,11 @@
 # Simulated SNS
 
-Yulin includes a simulated Amazon SNS for tests and local development. Topics are held in memory and
-every operation is authorized by simulated IAM.
+Yulin simulates Amazon SNS standard topics for tests and local development. A published message can
+reach simulated SQS queues, invoke simulated Lambda functions or create SMS records that tests can
+inspect. Direct SMS publishes are recorded in the same way.
 
-Standard topics only. SNS-specific types are imported from the `@kensio/yulin/sns` subpath.
-
-A message published to a topic is delivered to every queue subscribed to it, invokes every Lambda
-function subscribed to it, and is recorded as an SMS for every phone number subscribed to it. Only
-those three protocols are simulated. A message published straight to a phone number is recorded
-as an SMS a test can assert on.
+Topics are stored in memory, and simulated IAM authorizes every operation. FIFO topics and other
+subscription protocols are not simulated. Import SNS-specific types from `@kensio/yulin/sns`.
 
 ## Creating a topic and publishing to it
 
@@ -103,11 +100,10 @@ console.log(read.Attributes?.["SubscriptionsConfirmed"]); // "0"
 reports it. The three subscription counts are reported as zero, the counts a topic with no
 subscriptions has.
 
-An attribute real SNS has and this simulation gives no behaviour to is refused by name rather than
-taken and ignored. That covers `FifoTopic`, `KmsMasterKeyId`, `SignatureVersion`, `TracingConfig`,
-`ArchivePolicy`, `DeliveryPolicy`, `ContentBasedDeduplication` and the delivery status logging
-attributes such as `SQSSuccessFeedbackRoleArn`. A topic that appeared to accept `KmsMasterKeyId`
-would look encrypted to the request that set it and be plain to everything else.
+Unsupported topic attributes are rejected instead of being stored without effect. These include
+`FifoTopic`, `KmsMasterKeyId`, `SignatureVersion`, `TracingConfig`, `ArchivePolicy`, `DeliveryPolicy`,
+`ContentBasedDeduplication` and delivery status logging attributes such as
+`SQSSuccessFeedbackRoleArn`.
 
 ## Publishing
 
@@ -148,12 +144,11 @@ const published = await sns.publish(
 console.log(published.MessageId !== undefined); // true
 ```
 
-The name and data type rules are the real ones. A data type is `String`, `String.Array`, `Number` or
-`Binary`, and each takes a custom label after a dot, so `Number.int` is a number as far as the rules
-go. A reserved `AWS.` or `Amazon.` prefix on a name, a data type built on none of the four, or a
-value that disagrees with its data type is refused. A test finds any of those without going near AWS. The two reserved names real
-SNS defines for SMS, `AWS.SNS.SMS.SenderID` and `AWS.SNS.SMS.SMSType`, are the exception.
-[Sending an SMS](#sending-an-sms) covers those.
+Message attributes use the AWS name and type rules. A type starts with `String`, `String.Array`,
+`Number` or `Binary` and may add a custom label after a dot, such as `Number.int`. SNS rejects
+reserved `AWS.` and `Amazon.` name prefixes, unknown base types and values that do not match their
+type. The SMS attributes `AWS.SNS.SMS.SenderID` and `AWS.SNS.SMS.SMSType` are exceptions. See
+[Sending an SMS](#sending-an-sms).
 
 A `Subject` is UTF-8 text with no line breaks or control characters, of fewer than 100 characters.
 That is the contract real SNS states. A subject of exactly 100 characters is already too long. A
@@ -164,9 +159,8 @@ publish with no `Message`, or with one over the size limit, is refused with
 the rest of the batch goes through, as real SNS reports it. An empty batch, more than ten entries, a
 malformed entry id or two entries sharing an id fail the whole request.
 
-The size limit is the one thing a batch is held to as a whole. Ten entries each just inside it are
-one batch far outside it, and a single entry over it fails the whole batch with
-`BatchRequestTooLongException`. The response singles out no entry.
+The size limit applies to the whole batch. A batch over the limit fails with
+`BatchRequestTooLongException`, without identifying one entry as the cause.
 
 ```typescript sim-sns-publish-batch
 /**
@@ -1762,9 +1756,9 @@ synthesises an `AWS::SNS::Subscription` alongside the `AWS::SQS::QueuePolicy` th
 delivery, and both deploy. `new subscriptions.LambdaSubscription(fn)` does the same with the
 `AWS::Lambda::Permission` beside it.
 
-## Available functionality
+## Supported operations
 
-Sim SNS currently supports:
+Simulated SNS supports:
 
 - `CreateTopicCommand`, idempotent for a name already taken, and `DeleteTopicCommand`
 - `ListTopicsCommand`, paged at a hundred topics with a `NextToken`
@@ -1807,8 +1801,6 @@ Sim SNS currently supports:
 
 ## Limitations
 
-Current documented limitations:
-
 - Only the `sqs`, `lambda` and `sms` subscription protocols are simulated. A queue, a function and a
   phone number are the only things a topic can deliver to. `http`, `https`, `email`, `email-json`,
   `application` and `firehose` are refused at `Subscribe` time.

package/docs/services/sqs/README.md

@@ -1,9 +1,11 @@
 # Simulated SQS
 
-Yulin includes a simulated Amazon SQS for tests and local development. Messages are held in memory,
-hidden and released on the simulation's own clock, and every operation is authorized by simulated IAM.
+Yulin simulates Amazon SQS standard queues for tests and local development. You can create queues,
+send and receive messages, test visibility timeouts and redrive messages to dead-letter queues.
+Messages are stored in memory, time-based behavior uses the simulation's clock, and simulated IAM
+authorizes every operation.
 
-Standard queues only. SQS-specific types are imported from the `@kensio/yulin/sqs` subpath.
+FIFO queues are not simulated. Import SQS-specific types from `@kensio/yulin/sqs`.
 
 ## Creating a queue and sending a message
 
@@ -57,10 +59,9 @@ differ. A request naming no attributes always matches.
 
 ## Visibility timeouts
 
-A received message is hidden from other consumers for the queue's visibility timeout, 30 seconds by
-default. The message records the instant it is hidden until. It becomes receivable again once
-simulated time reaches that instant. Advancing the clock is all a test needs to watch an undeleted
-message come back.
+A received message is hidden from other consumers for the queue's visibility timeout, which is 30
+seconds by default. If the consumer does not delete it, the message becomes available again when the
+simulated clock reaches the end of that timeout.
 
 ```typescript sim-sqs-visibility-timeout
 /**
@@ -127,8 +128,8 @@ Every receive issues a fresh receipt handle, and a delete has to use the handle
 receive of that message. A handle from an earlier receive is accepted and deletes nothing. Real SQS
 accepts one too, and promises only that the message might not be deleted.
 
-That is the failure a consumer slower than its visibility timeout hits. Its message went back on the
-queue, someone else took it, and its own delete quietly does nothing.
+This can happen when a consumer runs past the visibility timeout and another consumer receives the
+same message. The first consumer's later delete succeeds without deleting the message.
 
 ```typescript sim-sqs-stale-receipt-handle
 /**
@@ -187,10 +188,9 @@ still the most recent one, so deleting with it works. A handle the queue never i
 
 ## Dead-letter queues
 
-A `RedrivePolicy` says where a message goes once a consumer has had enough attempts at it. Once a
-message has been received `maxReceiveCount` times without being deleted, the next lapse of its
-visibility timeout moves it to the queue named by `deadLetterTargetArn`. Advancing the clock drives
-the move, as it drives the timeout itself.
+A `RedrivePolicy` sends repeatedly received messages to a dead-letter queue. After a message reaches
+`maxReceiveCount` without being deleted, the next visibility timeout moves it to the queue named by
+`deadLetterTargetArn`. Advance the simulated clock to trigger the timeout and move.
 
 ```typescript sim-sqs-dead-letter-queue
 /**
@@ -1137,7 +1137,7 @@ that deploys here, with the queue URL reaching the function through its environm
 policy naming the queue by the ARN `Fn::GetAtt` gives. A grant to a service principal synthesises an
 `AWS::SQS::QueuePolicy` alongside it, which deploys too.
 
-## Available functionality
+## Supported operations
 
 Sim SQS currently supports: