@kensio/yulin 1.21.2 → 1.21.4

package/docs/services/s3/README.md

@@ -418,6 +418,65 @@ for (const object of objectContentItems) {
 The marker is exclusive and lexicographic. A listing resumes after the key it names whether or not
 the Bucket still holds it.
 
+### Asking for encoded keys
+
+An Object key can hold characters an XML document cannot carry, and a listing writes its keys into
+XML. `EncodingType: "url"` asks for them encoded. Simulated S3 encodes every `Key`, the `Prefix` and
+`Delimiter` the request named, each prefix in `CommonPrefixes`, and the marker or `StartAfter` key
+the response carries, as real S3 encodes them. The listing reports `EncodingType` back.
+
+```typescript sim-s3-list-objects-encoded-keys
+/**
+ * Listing a simulated S3 Bucket with its keys encoded.
+ */
+
+import {
+  CreateBucketCommand,
+  ListObjectsV2Command,
+  PutObjectCommand,
+} from "@aws-sdk/client-s3";
+import { SimAws } from "@kensio/yulin";
+
+const simS3 = new SimAws().s3();
+
+await simS3.createBucket(new CreateBucketCommand({ Bucket: "uploads" }));
+
+await simS3.putObject(
+  new PutObjectCommand({
+    Bucket: "uploads",
+    Key: "invoices/March 2027 & April.pdf",
+    Body: "invoice bytes",
+  }),
+);
+
+const listed = await simS3.listObjectsV2(
+  new ListObjectsV2Command({ Bucket: "uploads", EncodingType: "url" }),
+);
+
+console.log(listed.EncodingType); // url
+
+const listedObjects = listed.Contents ?? [];
+
+for (const listedObject of listedObjects) {
+  const encodedKey = listedObject.Key ?? "";
+
+  console.log(encodedKey); // invoices/March+2027+%26+April.pdf
+
+  // S3 form-encodes a key, and a plus sign in one stands for a space.
+  console.log(decodeURIComponent(encodedKey.replaceAll("+", " ")));
+}
+```
+
+The encoding is the one an event notification record carries a key in. A space becomes a plus sign,
+and the slashes of a key prefix are left as they are. Continuation tokens are left alone in either
+version of the operation, being opaque already.
+
+A listing that names no `EncodingType` answers with the keys as they were written, and says nothing
+about an encoding. Any other value is refused with `InvalidArgument`.
+
+The `encoding-type` query parameter carries this over a
+[served endpoint](#serve-simulated-s3-on-localhost), and the SDK sets it from `EncodingType`.
+
 ## Object ETags
 
 Every Object has an ETag, the MD5 of its body in hex and quoted, as real S3 gives it for a
@@ -779,8 +838,7 @@ See [Serve simulated S3 on localhost](#serve-simulated-s3-on-localhost) for sett
 - `CopySourceIfMatch`, `CopySourceIfNoneMatch`, `CopySourceIfModifiedSince` and
   `CopySourceIfUnmodifiedSince` are ignored. A conditional copy happens whatever the condition
   says.
-- `TaggingDirective`, `StorageClass`, `ACL` and the server-side encryption members are ignored. Sim
-  S3 models none of what they describe.
+- `ACL` is ignored. Sim S3 models no Object ACL.
 - A `versionId` in `CopySource` is refused with `NotImplemented`.
 - A copy of an Object that was uploaded in parts gets a plain ETag rather than the multipart form.
   Real S3 does the same for a copy under five gigabytes, because it rewrites the bytes as one
@@ -1290,6 +1348,11 @@ The event types a configuration can name are `s3:ObjectCreated:*`, `s3:ObjectCre
 `s3:ObjectRemoved:*` and `s3:ObjectRemoved:Delete`. Any other S3 event type is refused by name rather
 than stored and never raised.
 
+A CDK [`BucketDeployment`](https://yulinsim.dev/services/cloudformation/#cdk-s3-bucketdeployment) raises
+both. It copies its files in one Object at a time, so each file the deployment writes raises
+`ObjectCreated:Put`, and each Object a pruning deployment removes raises `ObjectRemoved:Delete`. The
+sync it stands in for raises the same two in AWS.
+
 A configuration can filter on an object key prefix, a suffix, or both. Two configurations that share
 an event type and whose filters could both match the same key are refused with `InvalidArgument`, as
 real S3 refuses them. Overlapping prefixes are fine when the suffixes do not overlap, so one function
@@ -1980,12 +2043,13 @@ writes fall outside it. Without that, the simulation stops after a thousand deli
 - A destination goes where the group it was declared in says, and its ARN has no say. A queue ARN
   under `LambdaFunctionConfigurations` is refused for failing to be a function ARN, and never
   delivered to as a queue.
-- Four event types are raised: `s3:ObjectCreated:Put`, `s3:ObjectCreated:Copy`,
-  `s3:ObjectCreated:CompleteMultipartUpload` and `s3:ObjectRemoved:Delete`. `Post`,
-  `DeleteMarkerCreated`, the `ObjectRestore:*`, `Replication:*`, `LifecycleExpiration:*` and
-  `ObjectTagging:*` families, `LifecycleTransition`, `IntelligentTiering`, `ObjectAcl:Put` and
-  `ReducedRedundancyLostObject` are refused by name. `s3:ObjectCreated:*` expands to the three
-  creations and `s3:ObjectRemoved:*` to the one removal.
+- Six event types are raised: `s3:ObjectCreated:Put`, `s3:ObjectCreated:Copy`,
+  `s3:ObjectCreated:CompleteMultipartUpload`, `s3:ObjectRemoved:Delete`,
+  `s3:ObjectTagging:Put` and `s3:ObjectTagging:Delete`. `Post`, `DeleteMarkerCreated`, the
+  `ObjectRestore:*`, `Replication:*` and `LifecycleExpiration:*` families, `LifecycleTransition`,
+  `IntelligentTiering`, `ObjectAcl:Put` and `ReducedRedundancyLostObject` are refused by name.
+  `s3:ObjectCreated:*` expands to the three creations, `s3:ObjectRemoved:*` to the one removal and
+  `s3:ObjectTagging:*` to the two tagging events.
 - `userIdentity.principalId` carries the caller's ARN rather than the `AIDA...` unique id real S3
   puts there. Simulated IAM has no unique-id namespace to draw one from, and an ARN is what a test
   would assert on. `requestParameters.sourceIPAddress` is the loopback address, because the request
@@ -2008,9 +2072,11 @@ writes fall outside it. Without that, the simulation stops after a thousand deli
   same way.
 - The KMS key policy statement CDK's `SqsDestination` writes for an encrypted queue is ignored.
   Queue encryption is left out.
-- A CDK `BucketDeployment` and `mountBucketFilesystem(...)` both replace the whole storage backend
-  rather than putting Objects, and neither raises an event. Real CDK `BucketDeployment` fires one
-  `ObjectCreated:Put` per file.
+- `mountBucketFilesystem(...)` replaces the storage with the directory, and a file written there by
+  something other than S3 raises nothing. The watcher reports that the directory changed without
+  naming the file, and comparing the whole key set on every reload is a larger change than this
+  earns. A delete through S3 raises `ObjectRemoved:Delete` on a mount that
+  [allows deletion](#deleting-the-files-under-a-mount).
 - A topic destination publishes with no message attributes, since real S3 publishes none. The only
   thing on the message besides the event document is the `Amazon S3 Notification` subject.
 - `s3:TestEvent` is left out. Real S3 puts one on a queue or topic when a configuration naming it is
@@ -2172,6 +2238,111 @@ matching S3's idempotent behaviour.
 A Bucket policy granting `Principal: "*"` is refused by default. See
 [Block Public Access](#block-public-access) below.
 
+### Missing keys and `s3:ListBucket`
+
+What S3 answers for a missing Object depends on a second permission. A caller holding
+`s3:GetObject` alone is answered `403 AccessDenied` for a key the Bucket does not hold, the same
+answer it gets for a key it may not read. `s3:ListBucket` on the Bucket ARN is what buys
+`404 NoSuchKey`.
+
+Which keys a Bucket holds is what a listing tells you, and real S3 admits the absence only to a
+caller that may list. A test written against a simulator that always answered `NoSuchKey` would
+handle the absence on a path the deployed code never reaches.
+
+```typescript sim-s3-missing-key-permission
+/**
+ * What simulated S3 answers for an Object that is not there.
+ */
+
+import { CreateRoleCommand, PutRolePolicyCommand } from "@aws-sdk/client-iam";
+import { CreateBucketCommand, GetObjectCommand } from "@aws-sdk/client-s3";
+import { SimAws } from "@kensio/yulin";
+
+const simAws = new SimAws();
+const simIam = simAws.iam();
+const simS3 = simAws.s3();
+
+await simS3.createBucket(new CreateBucketCommand({ Bucket: "reports" }));
+
+const readerCreation = await simIam.createRole(
+  new CreateRoleCommand({
+    RoleName: "ReportReader",
+    AssumeRolePolicyDocument: JSON.stringify({
+      Version: "2012-10-17",
+      Statement: {
+        Effect: "Allow",
+        Principal: { Service: "lambda.amazonaws.com" },
+        Action: "sts:AssumeRole",
+      },
+    }),
+  }),
+);
+
+await simIam.putRolePolicy(
+  new PutRolePolicyCommand({
+    RoleName: "ReportReader",
+    PolicyName: "ReadReports",
+    PolicyDocument: JSON.stringify({
+      Version: "2012-10-17",
+      Statement: {
+        Effect: "Allow",
+        Action: "s3:GetObject",
+        Resource: "arn:aws:s3:::reports/*",
+      },
+    }),
+  }),
+);
+
+const asReader = {
+  caller: { kind: "arn", arn: readerCreation.Role.Arn },
+} as const;
+
+try {
+  await simS3.getObject(
+    new GetObjectCommand({ Bucket: "reports", Key: "q4/report.txt" }),
+    asReader,
+  );
+} catch (error) {
+  // AccessDenied, with a 403 status. This caller may not list the Bucket, and
+  // S3 will not tell it whether the key is there.
+  console.error("Read refused", error);
+}
+
+await simIam.putRolePolicy(
+  new PutRolePolicyCommand({
+    RoleName: "ReportReader",
+    PolicyName: "ListReports",
+    PolicyDocument: JSON.stringify({
+      Version: "2012-10-17",
+      Statement: {
+        Effect: "Allow",
+        Action: "s3:ListBucket",
+        Resource: "arn:aws:s3:::reports",
+      },
+    }),
+  }),
+);
+
+try {
+  await simS3.getObject(
+    new GetObjectCommand({ Bucket: "reports", Key: "q4/report.txt" }),
+    asReader,
+  );
+} catch (error) {
+  // NoSuchKey, with a 404 status.
+  console.error("Object missing", error);
+}
+```
+
+An Object that is there is served on `s3:GetObject` alone. The listing permission only decides what
+a caller is told about a key the Bucket does not hold.
+
+Everything that reads through GetObject follows the same rule, including the served S3 endpoint, the
+static website endpoint and a CloudFront S3 Origin. A site whose Bucket policy grants only
+`s3:GetObject` answers 403 for a page it does not hold, and serves its custom error document with
+that status. Adding `s3:ListBucket` on the Bucket ARN gives it the 404 an error document is usually
+written for.
+
 ### Where a request came from
 
 A request can say what it is being made for, and a simulated service supplies that when it reaches a
@@ -2256,12 +2427,238 @@ Bucket ACLs and Object ownership settings are left out, and stay that way by cho
 defaults to Bucket owner enforced on new Buckets, which disables ACLs, and AWS recommends keeping
 them disabled in favour of policies.
 
+## Storage classes
+
+Every Object is in a storage class. A write names one and the Object stays there until a lifecycle
+rule moves it. `PutObject`, `CopyObject` and `CreateMultipartUpload` all take a `StorageClass`, and
+both list operations, `GetObject` and `HeadObject` report where the Object ended up.
+
+```typescript sim-s3-storage-class
+/**
+ * Writing a simulated S3 Object into an archival storage class.
+ */
+
+import {
+  CreateBucketCommand,
+  HeadObjectCommand,
+  ListObjectsV2Command,
+  PutObjectCommand,
+} from "@aws-sdk/client-s3";
+import { SimAws } from "@kensio/yulin";
+
+const simAws = new SimAws();
+const simS3 = simAws.region("eu-west-2").s3();
+
+await simS3.createBucket(new CreateBucketCommand({ Bucket: "archive" }));
+
+await simS3.putObject(
+  new PutObjectCommand({
+    Bucket: "archive",
+    Key: "ledgers/2026.csv",
+    Body: "a,b",
+    StorageClass: "GLACIER",
+  }),
+);
+
+const listing = await simS3.listObjectsV2(
+  new ListObjectsV2Command({ Bucket: "archive" }),
+);
+const head = await simS3.headObject(
+  new HeadObjectCommand({ Bucket: "archive", Key: "ledgers/2026.csv" }),
+);
+
+// GLACIER, from the listing and from the Object itself.
+console.log(listing.Contents?.[0]?.StorageClass, head.StorageClass);
+```
+
+A write naming a class S3 has no such class for is refused with `InvalidStorageClass`, before
+anything is stored. The classes taken are `STANDARD`, `REDUCED_REDUNDANCY`, `STANDARD_IA`,
+`ONEZONE_IA`, `INTELLIGENT_TIERING`, `GLACIER_IR`, `GLACIER`, `DEEP_ARCHIVE`, `EXPRESS_ONEZONE`,
+`OUTPOSTS` and `SNOW`.
+
+A listing always reports a class, and a read reports one only for an Object outside `STANDARD`. That
+is how real S3 answers, and it is why `GetObject.StorageClass` is undefined for most Objects. A copy
+is stored in the class the copy names rather than the source's, and an upload in parts takes its
+class at `CreateMultipartUpload` rather than at the completion.
+
+Where the Object is changes nothing about reading it. Real S3 refuses a read of an archived Object
+until `RestoreObject` has brought it back, and sim S3 serves every Object whatever class it is in.
+See [Limitations](#limitations).
+
+## Object tags
+
+An Object carries up to ten tags. `PutObjectTaggingCommand`, `GetObjectTaggingCommand` and
+`DeleteObjectTaggingCommand` read and replace the whole set, and `PutObject`, `CopyObject` and
+`CreateMultipartUpload` take one on the write itself, as the `department=finance&retention=long`
+query string real S3 carries it in.
+
+```typescript sim-s3-object-tagging
+/**
+ * Tagging a simulated S3 Object and reading the tags back.
+ */
+
+import {
+  CreateBucketCommand,
+  GetObjectTaggingCommand,
+  PutObjectCommand,
+  PutObjectTaggingCommand,
+} from "@aws-sdk/client-s3";
+import { SimAws } from "@kensio/yulin";
+
+const simAws = new SimAws();
+const simS3 = simAws.region("eu-west-2").s3();
+
+await simS3.createBucket(new CreateBucketCommand({ Bucket: "reports" }));
+
+// A write can carry its own tags, as the query string S3 takes them in.
+await simS3.putObject(
+  new PutObjectCommand({
+    Bucket: "reports",
+    Key: "quarterly.csv",
+    Body: "period,total",
+    Tagging: "department=finance&retention=long",
+  }),
+);
+
+// A tagging request replaces the whole set.
+await simS3.putObjectTagging(
+  new PutObjectTaggingCommand({
+    Bucket: "reports",
+    Key: "quarterly.csv",
+    Tagging: { TagSet: [{ Key: "department", Value: "legal" }] },
+  }),
+);
+
+const read = await simS3.getObjectTagging(
+  new GetObjectTaggingCommand({ Bucket: "reports", Key: "quarterly.csv" }),
+);
+
+// [ { Key: "department", Value: "legal" } ]
+console.log(read.TagSet);
+```
+
+A tag set is put whole, as real S3 puts one. The request above leaves the Object carrying
+`department=legal` and nothing else. An Object nobody has tagged reads back with an empty `TagSet`.
+Having no tags is a different thing from having no Object, and only the second is `NoSuchKey`.
+
+A set of more than ten tags is refused with `InvalidTag`, and so is one stating a key twice. Both
+are checked before anything is written, leaving an Object refused eleven tags carrying none of them.
+
+A copy carries the source Object's tags. `TaggingDirective: REPLACE` puts the request's own
+`Tagging` on the copy and drops the source's.
+
+On a Bucket keeping versions, a tag set belongs to the version it was put on. Writing a new version
+leaves the one before it carrying what that version was written with, and a tagging request naming a
+`VersionId` reaches that version alone.
+
+Tagging an Object raises `s3:ObjectTagging:Put`, and removing its tags raises
+`s3:ObjectTagging:Delete`. See [Event notifications](#event-notifications). A lifecycle rule
+filtering on a tag selects the Objects carrying it. See [What a rule selects](#what-a-rule-selects).
+
+Each of the three operations is granted by a permission of its own, `s3:GetObjectTagging`,
+`s3:PutObjectTagging` and `s3:DeleteObjectTagging`. `s3:PutObject` grants none of them. All three are
+served over the S3 REST endpoint under the `?tagging` sub-resource, so the CLI reaches the same
+handlers an SDK caller does.
+
+### Limitations
+
+- Bucket tags are inert. `Tags` on an `AWS::S3::Bucket` is recorded and never read.
+- The `s3:ExistingObjectTag` and `s3:RequestObjectTag` IAM condition keys are left out. A Bucket
+  policy written against either matches no request.
+- `GetObjectAttributes` is left out, and neither `GetObject` nor `HeadObject` reports
+  `x-amz-tagging-count`.
+- Tag keys and values are stored as they arrive. Real S3 bounds a key at 128 characters and a value
+  at 256, and sim S3 accepts a longer one of either.
+- A Bucket mounted on a filesystem directory rebuilds each Object from the file on every read, and a
+  directory holds no tags. Tagging one writes the same bytes back to the file, and the next read
+  reports an untagged Object. Use the default in-memory storage to test tagging. See
+  [Metadata a file cannot carry](#metadata-a-file-cannot-carry).
+
+## Default encryption
+
+Every Bucket is encrypted, and every Object written into one reports the algorithm it was stored
+under. Nothing is actually encrypted here. The bytes are stored as they arrive and the ETag stays
+the MD5 of them, which is what real S3 reports for an SSE-S3 Object too. What this gives a test is
+the answer S3 gives about an Object, so code that reads `ServerSideEncryption` or the
+`x-amz-server-side-encryption` header has something to read.
+
+```typescript sim-s3-bucket-encryption
+/**
+ * Configuring a simulated S3 Bucket's default encryption.
+ */
+
+import {
+  CreateBucketCommand,
+  GetBucketEncryptionCommand,
+  GetObjectCommand,
+  PutBucketEncryptionCommand,
+  PutObjectCommand,
+} from "@aws-sdk/client-s3";
+import { SimAws } from "@kensio/yulin";
+
+const simAws = new SimAws();
+const simS3 = simAws.region("eu-west-2").s3();
+
+await simS3.createBucket(new CreateBucketCommand({ Bucket: "documents" }));
+
+await simS3.putBucketEncryption(
+  new PutBucketEncryptionCommand({
+    Bucket: "documents",
+    ServerSideEncryptionConfiguration: {
+      Rules: [
+        { ApplyServerSideEncryptionByDefault: { SSEAlgorithm: "aws:kms" } },
+      ],
+    },
+  }),
+);
+
+await simS3.putObject(
+  new PutObjectCommand({
+    Bucket: "documents",
+    Key: "contracts/one.pdf",
+    Body: "one",
+  }),
+);
+
+const configured = await simS3.getBucketEncryption(
+  new GetBucketEncryptionCommand({ Bucket: "documents" }),
+);
+const read = await simS3.getObject(
+  new GetObjectCommand({ Bucket: "documents", Key: "contracts/one.pdf" }),
+);
+
+// aws:kms, from the Bucket's configuration and from the Object it stamped.
+console.log(
+  configured.ServerSideEncryptionConfiguration?.Rules?.[0]
+    ?.ApplyServerSideEncryptionByDefault?.SSEAlgorithm,
+  read.ServerSideEncryption,
+);
+```
+
+A write names its own algorithm, the Bucket's configuration answers for a write that names none, and
+a Bucket nobody has configured is `AES256`. Real S3 has encrypted every new Object that way since
+January 2023, and `GetBucketEncryption` answers for an unconfigured Bucket with the same `AES256`
+rule rather than an error. `DeleteBucketEncryption` puts a Bucket back to that rule, since there is
+no such thing as an unencrypted Bucket.
+
+`AES256`, `aws:kms` and `aws:kms:dsse` are taken, and anything else is refused with
+`InvalidArgument`. The Objects already in a Bucket keep what they were written with when its
+configuration changes.
+
+An Object that reached a Bucket without a write reports no encryption at all. That covers the files
+a mounted directory serves and the ones a CDK `BucketDeployment` publishes, since neither went
+through `PutObject` to be stamped by one.
+
+An `AWS::S3::Bucket` `BucketEncryption` property is applied as the request is. CloudFormation states
+the rule under `ServerSideEncryptionByDefault` where the request states
+`ApplyServerSideEncryptionByDefault`, and the Resource translates that one name.
+
 ## Lifecycle configuration
 
 Sim S3 stores a Bucket's lifecycle rules and acts on them. An `Expiration` rule removes the Objects
-it selects once simulated time passes the boundary, a `NoncurrentVersionExpiration` rule bounds the
-history a versioned Bucket keeps, and an `AbortIncompleteMultipartUpload` rule discards uploads that
-were started and left unfinished.
+it selects once simulated time passes the boundary, a `Transitions` rule moves them between storage
+classes, a `NoncurrentVersionExpiration` rule bounds the history a versioned Bucket keeps, and an
+`AbortIncompleteMultipartUpload` rule discards uploads that were started and left unfinished.
 
 Retention is otherwise the one property of a log or a backup Bucket a test cannot demonstrate.
 Reading the rules back off a deployed Bucket says the rules arrived. Putting an Object, moving the
@@ -2421,6 +2818,77 @@ A noncurrent version is removed from the Bucket's history, and a `GetObject` nam
 answers `NoSuchVersion` afterwards. The current version is beyond every rule of this kind, however
 old it is.
 
+### Transitioning between storage classes
+
+A `Transitions` rule moves the Objects it selects into another storage class as the clock passes the
+days it names. A rule listing several walks an Object down them, and the last transition reached is
+where the Object is. `NoncurrentVersionTransitions` does the same for the versions a write has
+displaced, counted from the moment each stopped being current.
+
+```typescript sim-s3-lifecycle-transition
+/**
+ * Moving simulated S3 Objects between storage classes on a lifecycle rule.
+ */
+
+import {
+  CreateBucketCommand,
+  ListObjectsV2Command,
+  PutBucketLifecycleConfigurationCommand,
+  PutObjectCommand,
+} from "@aws-sdk/client-s3";
+import { SimAws } from "@kensio/yulin";
+
+const simAws = new SimAws();
+const simS3 = simAws.region("eu-west-2").s3();
+
+await simS3.createBucket(new CreateBucketCommand({ Bucket: "logs" }));
+await simS3.putBucketLifecycleConfiguration(
+  new PutBucketLifecycleConfigurationCommand({
+    Bucket: "logs",
+    LifecycleConfiguration: {
+      Rules: [
+        {
+          ID: "cool-then-freeze",
+          Status: "Enabled",
+          Filter: { Prefix: "raw/" },
+          Transitions: [
+            { Days: 30, StorageClass: "STANDARD_IA" },
+            { Days: 90, StorageClass: "GLACIER" },
+          ],
+        },
+      ],
+    },
+  }),
+);
+
+await simS3.putObject(
+  new PutObjectCommand({
+    Bucket: "logs",
+    Key: "raw/2026-08-24.gz",
+    Body: "one raw log line",
+  }),
+);
+
+await simAws.clock().advanceBy({ days: 90 });
+
+const listing = await simS3.listObjectsV2(
+  new ListObjectsV2Command({ Bucket: "logs", Prefix: "raw/" }),
+);
+
+// GLACIER, the last transition the clock reached.
+console.log(listing.Contents?.[0]?.StorageClass);
+```
+
+A transition is worked out when the Bucket is read, as an expiry is, so what a listing or a read
+reports is where the rules put the Object at that instant. The bytes stay where they are. Moving the
+clock back afterwards moves the Object back, and an expiry that has already happened stays done. The
+expiry deleted something on the way past, and a transition changed only what S3 says about the
+Object.
+
+A rule naming a class S3 has no such class for is refused with `InvalidStorageClass` where the
+configuration is stored, before it reaches any Object. An `Expiration` on the same rule still expires
+at its own age, whatever the transitions have done in the meantime.
+
 ### What a rule selects
 
 A rule selects Objects by its `Filter`, or by the older top-level `Prefix`. A rule with no scope at
@@ -2430,8 +2898,73 @@ all covers every key in the Bucket. `Filter.Prefix`, `Filter.And.Prefix`, `Objec
 A multipart upload is selected by its key alone. Half an upload has no size. A rule narrowed by an
 object size bound abandons no upload.
 
-Sim S3 holds no Object tags. A rule narrowed by `Filter.Tag`, `Filter.And.Tags` or a template's
-`TagFilters` selects no Object, and expires none.
+A rule narrowed by `Filter.Tag`, or by the `Filter.And.Tags` beside a prefix, selects the Objects
+carrying every tag it names. Both halves of a tag have to match, so a rule for `archive=true` leaves
+an Object tagged `archive=false` where it is. A template states the same thing as `TagFilters` beside
+the rule's `Prefix`, and it is read into the `Filter` the request takes. See
+[Object tags](#object-tags).
+
+```typescript sim-s3-lifecycle-tag-filter
+/**
+ * Expiring the simulated S3 Objects a tag selects.
+ */
+
+import {
+  CreateBucketCommand,
+  ListObjectsV2Command,
+  PutBucketLifecycleConfigurationCommand,
+  PutObjectCommand,
+} from "@aws-sdk/client-s3";
+import { SimAws } from "@kensio/yulin";
+
+const simAws = new SimAws();
+const simS3 = simAws.s3();
+
+await simS3.createBucket(new CreateBucketCommand({ Bucket: "reports" }));
+
+await simS3.putBucketLifecycleConfiguration(
+  new PutBucketLifecycleConfigurationCommand({
+    Bucket: "reports",
+    LifecycleConfiguration: {
+      Rules: [
+        {
+          ID: "expire-temporary",
+          Status: "Enabled",
+          Filter: { Tag: { Key: "lifecycle", Value: "temporary" } },
+          Expiration: { Days: 7 },
+        },
+      ],
+    },
+  }),
+);
+
+await simS3.putObject(
+  new PutObjectCommand({
+    Bucket: "reports",
+    Key: "draft.csv",
+    Body: "period,total",
+    Tagging: "lifecycle=temporary",
+  }),
+);
+await simS3.putObject(
+  new PutObjectCommand({ Bucket: "reports", Key: "final.csv", Body: "a,b" }),
+);
+
+await simAws.clock().advanceBy({ days: 8 });
+
+const listing = await simS3.listObjectsV2(
+  new ListObjectsV2Command({ Bucket: "reports" }),
+);
+
+// Only final.csv. The tagged draft is past its expiry.
+console.log(listing.Contents?.map((entry) => entry.Key));
+```
+
+A tagging request that takes an Object out of a rule's reach takes it out for good. The rule reads
+the tags the Object carries at the moment the Bucket is read.
+
+An Object a rule reaches by tag alone is reached wherever it is in the Bucket. A bare `Filter.Tag`
+says nothing about the key.
 
 ### Reading and replacing the rules
 
@@ -2513,28 +3046,30 @@ CloudFormation spells some rule fields differently from the request. `Id` become
 `TransitionInDays` becomes `Days`. The singular `Transition` a template may state alongside
 `Transitions` joins the list. `NoncurrentVersionExpirationInDays` becomes the `NoncurrentDays` of a
 `NoncurrentVersionExpiration`, which is what CDK's `noncurrentVersionExpiration` synthesises, and a
-template stating the nested object instead is taken as it stands. Everything else, `Status`,
-`Prefix`, `AbortIncompleteMultipartUpload`, `TagFilters` and the object size bounds among them, is
+template stating the nested object instead is taken as it stands. `TagFilters` becomes the `Filter`
+the request holds a rule's tags in, taking the rule's `Prefix` in with it where it states one.
+Everything else, `Status`, `AbortIncompleteMultipartUpload` and the object size bounds among them, is
 carried across as the template stated it.
 
 `LifecycleConfiguration` is one of the properties simulated S3 acts on. It stays out of
 [`stack.ignoredProperties`](https://yulinsim.dev/services/cloudformation/#properties-a-resource-was-created-without).
-The three actions it enforces are `Expiration`, whether the template flattened it onto the rule or
-not, `NoncurrentVersionExpiration`, in either of its two spellings, and
-`AbortIncompleteMultipartUpload`. A `Transitions` rule is stored and read back and goes no further. Which Objects an enforced action reaches is decided by the fields listed under
-[What a rule selects](#what-a-rule-selects).
+The actions it enforces are `Expiration`, whether the template flattened it onto the rule or not,
+`Transitions` and `NoncurrentVersionTransitions`, `NoncurrentVersionExpiration`, in either of its
+two spellings, and `AbortIncompleteMultipartUpload`. Which Objects an enforced action reaches is
+decided by the fields listed under [What a rule selects](#what-a-rule-selects).
 
 ### Limitations
 
-No Object moves between storage classes. Storage classes are left out of the simulator entirely. A
-`Transitions` rule is stored and read back and goes no further.
+Real S3 raises `s3:LifecycleExpiration:Delete` when a rule removes an Object, and
+`s3:LifecycleTransition` when one moves an Object. Both event families are among the ones sim S3
+leaves out. An expiry and a transition here are silent.
 
-Real S3 raises `s3:LifecycleExpiration:Delete` when a rule removes an Object. That event family is
-among the ones sim S3 leaves out. An expiry here is silent.
+A transition changes the class an Object reads back in and nothing else. Real S3 also takes an
+Object in an archival class out of reach until `RestoreObject` has brought it back, and sim S3
+serves every Object whatever class a rule has moved it to.
 
-`NoncurrentVersionTransitions` is stored and unread, alongside `Transitions`, because storage classes
-are left out. An `Expiration` rule on a versioned Bucket writes a delete marker over the current
-version and leaves the version itself where it is, which is what real S3 does, and a
+An `Expiration` rule on a versioned Bucket writes a delete marker over the current version and
+leaves the version itself where it is, which is what real S3 does, and a
 `NoncurrentVersionExpiration` rule is what then removes it. See
 [Object versioning](#object-versioning).
 
@@ -2870,6 +3405,52 @@ const s3Client = new S3Client({
 });
 ```
 
+### What an upload says about the Object
+
+An upload keeps the metadata headers it was sent. `cache-control`, `content-disposition`,
+`content-encoding`, `content-language`, `content-type` and `expires` are stored, and a read is
+served every one of them, the way it serves an Object written by a `PutObjectCommand`. See
+[Object system metadata](#object-system-metadata). An `x-amz-meta-` header is stored too. An
+`x-amz-tagging` header puts the tags it names on the Object, the same way a `PutObjectCommand`
+does. See [Object tags](#object-tags).
+
+```typescript
+await fetch(url, {
+  method: "PUT",
+  body: styleSheet,
+  headers: {
+    "content-type": "text/css",
+    "cache-control": "public, max-age=31536000, immutable",
+  },
+});
+```
+
+### Headers the URL asks for
+
+A read can name the headers it wants the Object served with. The SDK sets them from
+`ResponseContentType`, `ResponseContentDisposition`, `ResponseCacheControl`,
+`ResponseContentEncoding`, `ResponseContentLanguage` and `ResponseExpires`, and carries them in the
+`response-` query parameters real S3 reads. Simulated S3 serves those values in place of the
+Object's own.
+
+```typescript
+const url = await getSignedUrl(
+  s3Client,
+  new GetObjectCommand({
+    Bucket: "reports",
+    Key: "q3/report.pdf",
+    ResponseContentType: "application/octet-stream",
+    ResponseContentDisposition: 'attachment; filename="q3-report.pdf"',
+  }),
+  { expiresIn: 900 },
+);
+```
+
+The Object keeps the metadata it was written with. One URL can hand a browser a download while
+another shows the same Object in the page. A `HEAD` reads the parameters as a `GET` does, and the
+API endpoint honours them for any read rather than only a presigned one. The website endpoint serves
+none of them, as real S3 serves none there.
+
 ### Limitations
 
 - `GET`, `HEAD`, `PUT` and `DELETE` of an Object are served over a Bucket's own REST endpoint, which
@@ -3139,13 +3720,7 @@ Filesystem storage is somewhat restrictive to make it slightly safer:
 - Object keys must not be absolute paths or contain `..`
 - Only files whose extension is on a cautious list are served (see below)
 - Symlinks are ignored when listing Objects
-- Deletion is refused, and never unlinks a real file
-
-`DeleteObject` against a filesystem-backed Bucket raises `NotImplemented`, and `DeleteObjects`
-reports the same code for every key. This is stricter than real S3, deliberately. The directory a
-Bucket is mounted on is an ordinary directory of yours, and removing files from it because a test
-called `DeleteObject` would be a poor default. Leave a Bucket on the default in-memory storage
-when a test needs deletion to work.
+- Deletion is refused until the mount asks for it (see below)
 
 When reading files from filesystem-backed storage, Yulin infers common `content-type` metadata from
 file extensions such as `.html`, `.css`, `.js`, `.json`, `.png`, `.svg`, `.txt`, `.csv`, `.pdf`,
@@ -3154,6 +3729,43 @@ file extensions such as `.html`, `.css`, `.js`, `.json`, `.png`, `.svg`, `.txt`,
 for an extension a mount named itself, below. No other file is served at all, with or without a
 type.
 
+### Deleting the files under a mount
+
+`DeleteObject` against a filesystem-backed Bucket raises `NotImplemented`, and `DeleteObjects`
+reports the same code for every key. This is stricter than real S3, deliberately. The directory a
+Bucket is mounted on is an ordinary directory of yours, and removing files from it because a test
+called `DeleteObject` would be a poor default.
+
+Code that deletes what it uploaded needs a Bucket that can. A mount says so with `allowDelete`, and
+a delete then unlinks the file, reports the removal and raises the `ObjectRemoved:Delete` event an
+in-memory Bucket raises:
+
+```typescript sim-s3-mount-allow-delete
+/**
+ * Letting a mounted Bucket delete the files it serves.
+ */
+
+import path from "node:path";
+
+import { CreateBucketCommand } from "@aws-sdk/client-s3";
+import { SimAws } from "@kensio/yulin";
+
+const simAws = new SimAws();
+
+await simAws.s3().createBucket(new CreateBucketCommand({ Bucket: "uploads" }));
+
+simAws
+  .s3()
+  .mountBucketFilesystem("uploads", path.join(process.cwd(), "assets"), {
+    allowDelete: true,
+  });
+```
+
+The key goes through the checks above either way. A delete naming a path that climbs out of the
+directory is refused, and so is one naming a file type the mount does not serve. The directory the
+file was in stays where it is, since a Bucket has no directories for an empty one to be. Leave the
+option off and the refusal stands, naming the directory it would have unlinked from.
+
 ### Serving a file extension of your own
 
 A mounted Bucket only serves files whose extension is on a cautious list (the web's own types, and
@@ -3311,10 +3923,14 @@ write attached, and nothing else.
 
 Every path that serves an Object goes through the same mapping. The REST endpoint, the
 [website endpoint](#static-website-hosting) and a CloudFront S3 Origin all report the same headers
-for it. `content-encoding` is the one that matters most. Bytes served without it are bytes no client
+for it. User-defined metadata travels alongside them, one `x-amz-meta-` header per entry. An SDK
+client reading over an endpoint reports the same `Metadata` an in-process read does.
+`content-encoding` is the one that matters most. Bytes served without it are bytes no client
 can decode, and an Object stored as brotli is only usable if the header comes back with it.
 
-`PutObjectCommand` sets them, one request field per header.
+`PutObjectCommand` sets them, one request field per header. An upload over a
+[served endpoint](#presigned-urls) sets them in the headers themselves, which is the form the SDK
+sends them in.
 
 ```typescript sim-s3-object-system-metadata
 /**
@@ -3363,6 +3979,10 @@ read of an Object written without one reports `binary/octet-stream`.
 way in. A read hands back the stored HTTP date as `ExpiresString`, alongside the same value parsed
 into a `Date` as `Expires`.
 
+A read can ask for headers of its own in place of these. See
+[Headers the URL asks for](#headers-the-url-asks-for). The Object goes on holding what it was
+written with.
+
 A CDK BucketDeployment's `SystemMetadata` sets the same headers on every Object it copies. See
 [CDK S3 BucketDeployment](https://yulinsim.dev/services/cloudformation/#cdk-s3-bucketdeployment). A
 [mounted directory](#metadata-a-file-cannot-carry) declares them for the Objects under a key prefix,
@@ -3427,8 +4047,8 @@ Sim S3 currently supports:
   removable on its own
 - `PutBucketWebsiteCommand`, for static website hosting
 - `PutBucketLifecycleConfigurationCommand`, `GetBucketLifecycleConfigurationCommand` and
-  `DeleteBucketLifecycleCommand`, storing a Bucket's lifecycle rules and handing them back without
-  expiring or transitioning any Object against them
+  `DeleteBucketLifecycleCommand`, storing a Bucket's lifecycle rules and expiring, transitioning and
+  abandoning against them in simulated time
 - `PutBucketPolicyCommand`, `GetBucketPolicyCommand` and `DeleteBucketPolicyCommand`, evaluated by
   sim IAM alongside identity policies
 - The `AWS::S3::Bucket` and `AWS::S3::BucketPolicy` CloudFormation resources
@@ -3438,16 +4058,27 @@ Sim S3 currently supports:
 - Serving Object `GET`, `HEAD`, `PUT` and `DELETE` over the S3 REST endpoint, authorized by sim IAM,
   and the `?uploads` and `?uploadId` sub-resources a multipart upload is made of
 - Presigned URLs built by the real `@aws-sdk/s3-request-presigner`, with expiry in simulated time
-- Object system metadata set by a `PutObjectCommand` and returned on a read, over every endpoint
-  that serves an Object
+- Object system metadata set by a `PutObjectCommand`, or by the headers of an upload over a served
+  endpoint, and returned on a read, over every endpoint that serves an Object
+- `response-` parameters on a read, serving the headers the request named in place of the Object's
+  own, which is what a presigned URL offering a download uses
+- `EncodingType` on a listing, encoding the keys, prefixes and markers it answers with
+- Object storage classes, named on a write and moved by a lifecycle rule, reported on a listing and
+  on a read
+- Object tags, taken on a write and on a copy, read and replaced by `PutObjectTaggingCommand`,
+  `GetObjectTaggingCommand` and `DeleteObjectTaggingCommand`, filtered on by a lifecycle rule, and
+  raising `s3:ObjectTagging:Put` and `s3:ObjectTagging:Delete`
+- `PutBucketEncryptionCommand`, `GetBucketEncryptionCommand` and `DeleteBucketEncryptionCommand`,
+  and the `BucketEncryption` property of an `AWS::S3::Bucket`, deciding the algorithm an Object
+  reports
 - Bucket website index documents, error documents, trailing-slash redirects, redirect-all
   configuration, and routing-rule redirects
 - Bucket-global uniqueness within a `SimAws` instance across simulated Accounts and Regions
 - In-memory Object storage by default
 - Optional filesystem-backed Bucket storage with `mountBucketFilesystem(...)`, watching the mounted
-  directory and reloading connected browsers when it is rebuilt, and reporting the system metadata a
+  directory and reloading connected browsers when it is rebuilt, reporting the system metadata a
   CDK `BucketDeployment` into the same Bucket published, alongside anything the mount declares for a
-  key prefix itself
+  key prefix itself, and deleting the files under it where the mount allows that
 
 The simulator aims at useful behaviour for tests and local development, short of full S3 feature
 parity. Unsupported S3 options may be ignored or may throw errors depending on whether the simulator
@@ -3457,16 +4088,16 @@ needs them to model the requested behaviour.
 
 These apply across the page. The sections above each list what is specific to them.
 
-- A listing reports `StorageClass` as `STANDARD` for every Object. Storage classes themselves are
-  left out, and every Object is in that one.
-- `EncodingType` is ignored on a listing, and keys come back unencoded.
-- Object tags, ACLs, replication and server-side encryption are left out. A lifecycle rule expires
-  Objects and abandons uploads, and transitions nothing between storage classes. See
-  [Lifecycle configuration](#lifecycle-configuration).
-- A Bucket using filesystem-backed storage cannot delete Objects, and raises no event
-  notifications, because it swaps the whole storage backend in place of putting Objects.
-- An upload over the S3 REST endpoint keeps its `content-type` and no other system metadata, leaving
-  a presigned `PUT` unable to set the rest. A `PutObjectCommand` through the SDK keeps all of them.
-- A presigned `GetObject` ignores the `response-content-type`, `response-cache-control` and other
-  `response-*` parameters that override a response header in real S3. An Object is served with the
-  system metadata it was written with.
+- A storage class says where S3 keeps an Object and nothing else. Every Object is readable whatever
+  class it is in, `RestoreObject` is left out, and nothing costs or takes longer in one class than
+  another. See [Storage classes](#storage-classes).
+- `EncodingType` is read on `ListObjects` and `ListObjectsV2`. `ListMultipartUploads` and
+  `ListParts` ignore it, and both answer on one page.
+- ACLs and replication are left out. Server-side encryption is reported and never applied, and an
+  `aws:kms` Object names no key, because there is no simulated KMS behind it. See
+  [Default encryption](#default-encryption).
+- A Bucket using filesystem-backed storage refuses a delete unless the mount allowed one, and hears
+  nothing about a file something else wrote under the directory. See
+  [Deleting the files under a mount](#deleting-the-files-under-a-mount).
+- Multipart upload parts for a mounted Bucket are held in memory, and only the assembled Object
+  reaches the directory.