@kensio/yulin 1.20.17 → 1.21.0

package/docs/services/cloudfront/README.md

@@ -262,8 +262,12 @@ fetching it, as in CloudFront.
 A viewer-response function never sees a custom error page. CloudFront runs no viewer-response
 function once the Origin has answered 400 or higher, and simulated CloudFront does the same, for a
 CloudFront Function and a Lambda@Edge function alike. The status the Origin returned is what decides
-that, whatever `ResponseCode` puts in its place. `ErrorCachingMinTTL` is accepted and ignored, along
-with a rule that sets nothing else, since sim CloudFront has no cache to apply it to.
+that, whatever `ResponseCode` puts in its place.
+
+`ErrorCachingMinTTL` says how many seconds the Distribution holds the error for before it reads the
+Origin again. A rule carrying it alone, with no `ResponsePagePath`, configures error caching for a
+status the Distribution serves no page for. See
+[What a Distribution stores](#what-a-distribution-stores).
 
 ## Serve simulated CloudFront on localhost
 
@@ -1553,6 +1557,10 @@ error status. It runs on whatever the Origin answered, including a 400 and above
 origin events differ from the viewer events, and CloudFront documents it. Returning a response
 replaces what the viewer gets.
 
+Both origin events run on a cache miss alone. A hit answers the viewer without either of them, as
+does a request a web ACL blocked or a viewer-request function answered. An `origin-request` function
+returning a response leaves the Origin unread, with no `origin-response` event after it.
+
 At both origin events the `host` header holds the Origin's own domain name. A viewer event shows the
 domain the viewer used.
 
@@ -2221,13 +2229,16 @@ const stack = await simAws.cloudFormation().deployTemplate({
           CachePolicyConfig: {
             Name: "BeaconPolicy",
             MinTTL: 0,
-            DefaultTTL: 0,
-            MaxTTL: 0,
+            DefaultTTL: 60,
+            MaxTTL: 3600,
             ParametersInCacheKeyAndForwardedToOrigin: {
-              EnableAcceptEncodingGzip: false,
+              EnableAcceptEncodingGzip: true,
               CookiesConfig: { CookieBehavior: "none" },
               HeadersConfig: { HeaderBehavior: "none" },
-              QueryStringsConfig: { QueryStringBehavior: "none" },
+              QueryStringsConfig: {
+                QueryStringBehavior: "whitelist",
+                QueryStrings: ["page"],
+              },
             },
           },
         },
@@ -2287,18 +2298,37 @@ console.log(
   config?.CacheBehaviors?.Items?.[0]?.CachePolicyId ===
     stack.output("BeaconPolicyId"),
 );
+
+// The policy itself, holding the TTLs and the cache key the template gave it.
+const beaconPolicy = simAws
+  .cloudFront()
+  .getCachePolicyById(stack.output("BeaconPolicyId"));
+
+console.log(beaconPolicy?.defaultTtlSec); // 60
+console.log(beaconPolicy?.cacheKey.queryStringBehavior); // "whitelist"
+console.log(beaconPolicy?.cacheKey.queryStrings); // ["page"]
 ```
 
 A Behavior records the ID it was given, and `GetDistribution` reports it back for both the default
 Behavior and a named one. An update changing the policy is reported the same way.
 
-Nothing here reads the policy itself. The TTLs, the cache key and the compression settings need a
-cache, and sim CloudFront holds none. Every request reaches the Origin whatever the policy would
-have cached on real CloudFront.
+The policy itself carries everything `CachePolicyConfig` holds. `getCachePolicyById` hands back the
+three TTLs, the three sections of `ParametersInCacheKeyAndForwardedToOrigin` and the two
+`EnableAcceptEncoding` flags. A test can assert that its Behavior leaves the query string out of the
+cache key before sim CloudFront has a cache to key.
+
+The Distribution reads the policy on every request. The cache key comes from the three sections and
+the two flags, and a `MaxTTL` of zero is what makes a Behavior on `CachingDisabled` reach the Origin
+every time. [Caching](#caching) below covers what is stored and what is keyed on.
+
+A TTL the template left out falls back to CloudFront's own default (0 seconds for `MinTTL`, one day
+for `DefaultTTL` and 365 days for `MaxTTL`), and a `MinTTL` above a day raises the `DefaultTTL` with
+it the way CloudFront does. An absent cache key section falls back to `none`. A section naming a
+behaviour CloudFront does not offer fails the Stack, naming the Resource. `HeaderBehavior` takes
+`none` and `whitelist` alone, where CloudFront gives an origin request policy a wider set.
 
 A policy name is unique within an account, as it is in CloudFront. A second
 `AWS::CloudFront::CachePolicy` claiming a name is refused with `CachePolicyAlreadyExists`.
-`Name` and `Comment` are the parts of `CachePolicyConfig` the policy carries.
 
 ### Managed cache policies
 
@@ -2314,6 +2344,10 @@ Behavior names one without a template creating anything. `CachingOptimized`
 for it. CDK's `CachePolicy.CACHING_OPTIMIZED` and its six siblings synthesize those IDs. A stack
 reaching for one deploys.
 
+Each also carries the TTLs and the cache key AWS publishes for it. A Behavior on `CachingOptimized`
+here holds the same 1 second floor, the same day of default TTL and the same empty cache key as one
+in an account.
+
 The managed policies sit in CloudFront's own namespace. A template may create a policy called
 `CachingDisabled` of its own, and deleting that stack leaves the managed one where it was.
 
@@ -2324,6 +2358,830 @@ way an absent response headers policy does, and the Behavior reports no policy.
 `CreateDistribution` and `UpdateDistribution` still refuse the same ID with `NoSuchCachePolicy`, as
 real CloudFront refuses it.
 
+## Caching
+
+A Distribution holds a cache. A request for a key it already holds is answered from that cache,
+leaving the Origin unread. The Behavior's cache policy decides the key, and decides whether the
+Behavior has one at all. The policy and the Origin's own cache headers together decide how long an
+answer is held.
+
+```typescript sim-cloudfront-caching
+/**
+ * Serving a request from a Distribution's cache, and missing it at another
+ * edge.
+ */
+
+import { CreateDistributionCommand } from "@aws-sdk/client-cloudfront";
+import {
+  CreateBucketCommand,
+  PutBucketPolicyCommand,
+  PutObjectCommand,
+  PutPublicAccessBlockCommand,
+} from "@aws-sdk/client-s3";
+
+import { SimAws } from "@kensio/yulin";
+import { serveSimAws } from "@kensio/yulin/serve";
+
+const simAws = new SimAws();
+const srv = await serveSimAws({ simAws });
+
+try {
+  const simS3 = simAws.s3();
+
+  await simS3.createBucket(new CreateBucketCommand({ Bucket: "site-bucket" }));
+  await simS3.putPublicAccessBlock(
+    new PutPublicAccessBlockCommand({
+      Bucket: "site-bucket",
+      PublicAccessBlockConfiguration: {
+        BlockPublicAcls: true,
+        IgnorePublicAcls: true,
+      },
+    }),
+  );
+  await simS3.putBucketPolicy(
+    new PutBucketPolicyCommand({
+      Bucket: "site-bucket",
+      Policy: JSON.stringify({
+        Version: "2012-10-17",
+        Statement: {
+          Effect: "Allow",
+          Principal: "*",
+          Action: "s3:GetObject",
+          Resource: "arn:aws:s3:::site-bucket/*",
+        },
+      }),
+    }),
+  );
+
+  const publish = async (body: string): Promise<void> => {
+    await simS3.putObject(
+      new PutObjectCommand({
+        Bucket: "site-bucket",
+        Key: "index.html",
+        ContentType: "text/html",
+        Body: body,
+      }),
+    );
+  };
+
+  await publish("<h1>First</h1>");
+
+  const distributionCreation = await simAws.cloudFront().createDistribution(
+    new CreateDistributionCommand({
+      DistributionConfig: {
+        CallerReference: "cached-site",
+        Comment: "Cached site",
+        Enabled: true,
+        DefaultRootObject: "index.html",
+        Origins: {
+          Quantity: 1,
+          Items: [
+            {
+              Id: "site-origin",
+              DomainName: "site-bucket.s3.amazonaws.com",
+              S3OriginConfig: { OriginAccessIdentity: "" },
+            },
+          ],
+        },
+        DefaultCacheBehavior: {
+          TargetOriginId: "site-origin",
+          ViewerProtocolPolicy: "allow-all",
+          // CachingOptimized, one of CloudFront's managed policies.
+          CachePolicyId: "658327ea-f89d-4fab-a63d-7e88639e58f6",
+        },
+      },
+    }),
+  );
+
+  const distroHostname = distributionCreation.Distribution!.DomainName!;
+  const home = srv.localUrl(`http://${distroHostname}/`);
+
+  const first = await fetch(home);
+  console.log(first.headers.get("x-cache")); // Miss from cloudfront
+  console.log(await first.text()); // <h1>First</h1>
+
+  // The Bucket holds a new page, which the Distribution has not been told
+  // about.
+  await publish("<h1>Second</h1>");
+
+  const second = await fetch(home);
+  console.log(second.headers.get("x-cache")); // Hit from cloudfront
+  console.log(await second.text()); // <h1>First</h1>
+
+  // The entry goes on ageing while simulated time moves.
+  await simAws.clock().advanceBy({ seconds: 30 });
+
+  const aged = await fetch(home);
+  console.log(aged.headers.get("age")); // 30
+
+  // Another point of presence has nothing cached under that key.
+  const coldEdge = await fetch(home, {
+    headers: { "x-sim-aws-cloudfront-edge": "second-edge" },
+  });
+  console.log(await coldEdge.text()); // <h1>Second</h1>
+
+  // With caching off, every request reaches the Origin.
+  simAws.cloudFront().configureCaching({ enabled: false });
+
+  const uncached = await fetch(home);
+  console.log(await uncached.text()); // <h1>Second</h1>
+} finally {
+  await srv.close();
+}
+```
+
+### What the key is made of
+
+The key is the request path, plus whatever the Behavior's cache policy names. A query string, a
+header or a cookie the policy lists joins the key. Two requests differing only in a campaign
+parameter the policy leaves out share one entry. Where the policy enables gzip or brotli, the
+normalized `Accept-Encoding` joins the key, and one object is cached once compressed and once
+plain.
+
+The request method is part of the key as well, since a HEAD response carries no body and a GET
+response does. `CachedMethods` on the Behavior decides which methods are cached at all. It is `GET`
+and `HEAD` unless the Behavior widens it, and a POST reaches the Origin every time.
+
+### The edge a request arrives at
+
+CloudFront caches at each of its points of presence, several hundred of them, and one viewer's
+request fills the cache at one of them. The key carries an edge ID for that. Every request arrives
+at the same edge unless it sends an `x-sim-aws-cloudfront-edge` header naming another. A test that
+sends a different one is proving its app survives arriving somewhere cold.
+
+The header follows the `x-sim-aws-*` convention of the caller and request source headers, and
+`@kensio/yulin/cloudfront` exports the name as `simCfEdgeHeaderName`. Sim CloudFront takes it off
+the request once it has read it. A web ACL rule, a CloudFront Function, a
+Lambda@Edge function and the Origin all see the request the viewer sent without it.
+
+### What a Distribution stores
+
+A Behavior stores what it serves where its cache policy is one this simulation holds and that
+policy's `MaxTTL` is above zero. That leaves out a Behavior naming a `CachePolicyId` from a real
+account, a Behavior naming none at all, and a Behavior on `CachingDisabled`. The alternative in each
+case would be a guessed TTL.
+
+An error is held for a TTL of its own. It comes from the `ErrorCachingMinTTL` of the custom error
+response matching the status, and from CloudFront's ten seconds where the Distribution configures no
+rule for that status. The Origin's cache headers and the Behavior's cache policy have no say in it.
+A rule with `ErrorCachingMinTTL: 0` holds the error for no time at all, and every failing request
+reaches the Origin. A rule is matched on the status the Origin answered with. A 404 the Distribution
+serves as a 200 error page is held for the seconds the 404's own rule allows.
+
+### How long an entry is held
+
+An entry records the instant it expires, taken from the simulation's clock. A request arriving after
+that instant reaches the Origin, and what the Origin answers takes the expired entry's place. So a
+test reaches the moment its content goes stale by advancing simulated time, without waiting for it.
+
+```typescript sim-cloudfront-cache-expiry
+/**
+ * Expiring a cached object by moving simulated time past its cache control.
+ */
+
+import { CreateDistributionCommand } from "@aws-sdk/client-cloudfront";
+import {
+  CreateBucketCommand,
+  PutBucketPolicyCommand,
+  PutObjectCommand,
+  PutPublicAccessBlockCommand,
+} from "@aws-sdk/client-s3";
+
+import { SimAws } from "@kensio/yulin";
+import { serveSimAws } from "@kensio/yulin/serve";
+
+const simAws = new SimAws();
+const srv = await serveSimAws({ simAws });
+
+try {
+  const simS3 = simAws.s3();
+
+  await simS3.createBucket(new CreateBucketCommand({ Bucket: "news-bucket" }));
+  await simS3.putPublicAccessBlock(
+    new PutPublicAccessBlockCommand({
+      Bucket: "news-bucket",
+      PublicAccessBlockConfiguration: {
+        BlockPublicAcls: true,
+        IgnorePublicAcls: true,
+      },
+    }),
+  );
+  await simS3.putBucketPolicy(
+    new PutBucketPolicyCommand({
+      Bucket: "news-bucket",
+      Policy: JSON.stringify({
+        Version: "2012-10-17",
+        Statement: {
+          Effect: "Allow",
+          Principal: "*",
+          Action: "s3:GetObject",
+          Resource: "arn:aws:s3:::news-bucket/*",
+        },
+      }),
+    }),
+  );
+
+  // The Origin holds each version of the page for a minute.
+  const publish = async (body: string): Promise<void> => {
+    await simS3.putObject(
+      new PutObjectCommand({
+        Bucket: "news-bucket",
+        Key: "index.html",
+        ContentType: "text/html",
+        CacheControl: "max-age=60",
+        Body: body,
+      }),
+    );
+  };
+
+  await publish("<h1>First</h1>");
+
+  const distributionCreation = await simAws.cloudFront().createDistribution(
+    new CreateDistributionCommand({
+      DistributionConfig: {
+        CallerReference: "news-site",
+        Comment: "News site",
+        Enabled: true,
+        DefaultRootObject: "index.html",
+        Origins: {
+          Quantity: 1,
+          Items: [
+            {
+              Id: "news-origin",
+              DomainName: "news-bucket.s3.amazonaws.com",
+              S3OriginConfig: { OriginAccessIdentity: "" },
+            },
+          ],
+        },
+        DefaultCacheBehavior: {
+          TargetOriginId: "news-origin",
+          ViewerProtocolPolicy: "allow-all",
+          // CachingOptimized, one of CloudFront's managed policies.
+          CachePolicyId: "658327ea-f89d-4fab-a63d-7e88639e58f6",
+        },
+      },
+    }),
+  );
+
+  const distroHostname = distributionCreation.Distribution!.DomainName!;
+  const home = srv.localUrl(`http://${distroHostname}/`);
+
+  const first = await fetch(home);
+  console.log(await first.text()); // <h1>First</h1>
+
+  await publish("<h1>Second</h1>");
+
+  // Still inside the minute the Origin asked for.
+  const held = await fetch(home);
+  console.log(await held.text()); // <h1>First</h1>
+
+  // Simulated time moves past it, and the next request reaches the Origin.
+  await simAws.clock().advanceBy({ seconds: 61 });
+
+  const expired = await fetch(home);
+  console.log(await expired.text()); // <h1>Second</h1>
+} finally {
+  await srv.close();
+}
+```
+
+The Origin's own headers and the cache policy settle the TTL between them, the way they settle it in
+AWS. `s-maxage` is preferred to `max-age`, and `max-age` to `Expires`. Whatever the Origin asks for
+is held between the policy's `MinTTL` and `MaxTTL`. An Origin that asks for nothing gets the greater
+of `MinTTL` and `DefaultTTL`, which is a day on `CachingOptimized`.
+
+An `Expires` header has to carry one of the three date formats HTTP allows. Anything else, a
+locale-formatted date included, is read as an object that expired already, the way any HTTP cache
+reads it.
+
+`no-store`, `no-cache` and `private` keep the answer out of the cache while the policy's `MinTTL` is
+zero. Where it is higher, the floor overrides the Origin and the answer is held for `MinTTL`
+seconds. That last one is CloudFront's own behaviour, and the
+[AWS documentation](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/Expiration.html)
+carries a warning about it.
+
+### Telling a hit from a miss
+
+An answer the cache or the Origin produced carries `X-Cache`. It reads `Hit from cloudfront` where
+the Distribution held the object and `Miss from cloudfront` where the Origin answered. A response
+returned earlier in the pipeline (one a web ACL blocked, or one a viewer-request function answered
+with) carries none. A hit carries `Age` as well, the whole seconds the entry has been held, counted
+on the simulation's clock from the moment the Origin answered. Advancing simulated time by a minute
+adds 60 to the age the next hit reports.
+
+Both headers go on ahead of the Behavior's response headers policy and the viewer-response event. A
+policy listing `X-Cache` among its headers to remove takes it off, and a viewer-response CloudFront
+Function or Lambda@Edge function reads both in its event.
+
+A hit is answered without running either origin event. `origin-request` and `origin-response` run on
+the miss that filled the cache and on nothing after it, as they do on AWS. The viewer events run
+either way, and so does the Behavior's response headers policy.
+
+### Applying a response headers policy
+
+A response headers policy is applied to a response on its way out of the cache, as CloudFront
+applies one. The stored entry carries the Origin's own headers. A Behavior given a different policy
+therefore serves what it already holds under the new one, with no invalidation.
+
+### Turning it off
+
+`simAws.cloudFront().configureCaching({ enabled: false })` turns caching off for every Distribution
+in one `SimAws`, across every Account and Region. Caching is on by default, as CloudFront's is. A
+suite that repeats a request and wants each one to reach the Origin can turn it off in setup.
+
+## Invalidations
+
+`CreateInvalidation` clears what a Distribution has cached. The next request for a cleared path
+reaches the Origin. This is the step a deploy takes once it has published new files, and it decides
+whether anyone sees them.
+
+```typescript sim-cloudfront-invalidation
+/**
+ * Clearing what a Distribution has cached, and reading the invalidation back.
+ */
+
+import {
+  CreateDistributionCommand,
+  CreateInvalidationCommand,
+  GetInvalidationCommand,
+  ListInvalidationsCommand,
+} from "@aws-sdk/client-cloudfront";
+import {
+  CreateBucketCommand,
+  PutBucketPolicyCommand,
+  PutObjectCommand,
+  PutPublicAccessBlockCommand,
+} from "@aws-sdk/client-s3";
+
+import { SimAws } from "@kensio/yulin";
+import { serveSimAws } from "@kensio/yulin/serve";
+
+const simAws = new SimAws();
+const srv = await serveSimAws({ simAws });
+
+try {
+  const simS3 = simAws.s3();
+
+  await simS3.createBucket(
+    new CreateBucketCommand({ Bucket: "release-bucket" }),
+  );
+  await simS3.putPublicAccessBlock(
+    new PutPublicAccessBlockCommand({
+      Bucket: "release-bucket",
+      PublicAccessBlockConfiguration: {
+        BlockPublicAcls: true,
+        IgnorePublicAcls: true,
+      },
+    }),
+  );
+  await simS3.putBucketPolicy(
+    new PutBucketPolicyCommand({
+      Bucket: "release-bucket",
+      Policy: JSON.stringify({
+        Version: "2012-10-17",
+        Statement: {
+          Effect: "Allow",
+          Principal: "*",
+          Action: "s3:GetObject",
+          Resource: "arn:aws:s3:::release-bucket/*",
+        },
+      }),
+    }),
+  );
+
+  const publish = async (body: string): Promise<void> => {
+    await simS3.putObject(
+      new PutObjectCommand({
+        Bucket: "release-bucket",
+        Key: "index.html",
+        ContentType: "text/html",
+        Body: body,
+      }),
+    );
+  };
+
+  await publish("<h1>First</h1>");
+
+  const simCloudFront = simAws.cloudFront();
+  const distributionCreation = await simCloudFront.createDistribution(
+    new CreateDistributionCommand({
+      DistributionConfig: {
+        CallerReference: "released-site",
+        Comment: "Released site",
+        Enabled: true,
+        DefaultRootObject: "index.html",
+        Origins: {
+          Quantity: 1,
+          Items: [
+            {
+              Id: "site-origin",
+              DomainName: "release-bucket.s3.amazonaws.com",
+              S3OriginConfig: { OriginAccessIdentity: "" },
+            },
+          ],
+        },
+        DefaultCacheBehavior: {
+          TargetOriginId: "site-origin",
+          ViewerProtocolPolicy: "allow-all",
+          // CachingOptimized, one of CloudFront's managed policies.
+          CachePolicyId: "658327ea-f89d-4fab-a63d-7e88639e58f6",
+        },
+      },
+    }),
+  );
+
+  const distributionId = distributionCreation.Distribution!.Id!;
+  const distroHostname = distributionCreation.Distribution!.DomainName!;
+  const home = srv.localUrl(`http://${distroHostname}/`);
+
+  const first = await fetch(home);
+  console.log(await first.text()); // <h1>First</h1>
+
+  // The deploy publishes a new page, which the Distribution is still holding
+  // the old version of.
+  await publish("<h1>Second</h1>");
+
+  const stale = await fetch(home);
+  console.log(await stale.text()); // <h1>First</h1>
+
+  const creation = await simCloudFront.createInvalidation(
+    new CreateInvalidationCommand({
+      DistributionId: distributionId,
+      InvalidationBatch: {
+        CallerReference: "deployment-1",
+        Paths: { Quantity: 1, Items: ["/*"] },
+      },
+    }),
+  );
+
+  console.log(creation.Invalidation!.Status); // InProgress
+
+  const released = await fetch(home);
+  console.log(await released.text()); // <h1>Second</h1>
+
+  // The invalidation finishes on the background scheduler.
+  await simAws.backgroundTasksComplete();
+
+  const invalidation = await simCloudFront.getInvalidation(
+    new GetInvalidationCommand({
+      DistributionId: distributionId,
+      Id: creation.Invalidation!.Id,
+    }),
+  );
+
+  console.log(invalidation.Invalidation!.Status); // Completed
+
+  const listing = await simCloudFront.listInvalidations(
+    new ListInvalidationsCommand({ DistributionId: distributionId }),
+  );
+
+  console.log(listing.InvalidationList!.Quantity); // 1
+} finally {
+  await srv.close();
+}
+```
+
+### The paths a batch names
+
+A path names one object. A path ending in a wildcard names everything below what comes before it.
+`/images/*` clears the images and leaves `/index.html` where it was, and `/*` clears everything the
+Distribution holds. A path arriving without its leading slash is read as though it had one. The
+bare `*` a console user types is the same batch as `/*`.
+
+An invalidation reaches every edge. A page cached at three points of presence is cleared at all
+three, whichever edge the requests that filled them arrived at.
+
+The entries go as the invalidation is created. Real CloudFront clears each point of presence over
+the following seconds, and a test waiting for that before asking again would be waiting on the
+simulator.
+
+### Reading an invalidation back
+
+An invalidation starts `InProgress` and reaches `Completed` on the background scheduler, the way a
+Distribution reaches `Deployed`. `GetDistribution` counts the running ones as
+`InProgressInvalidationBatches`.
+
+`GetInvalidation` answers with the batch of paths the invalidation was created from.
+`ListInvalidations` answers with the Distribution's whole list, most recently created first. An
+invalidation ID the Distribution has never held is `NoSuchInvalidation`.
+
+### Repeating a batch
+
+`CallerReference` makes a batch idempotent. Sending one twice with the same paths answers with the
+invalidation that reference already created, and clears nothing a second time. Sending it with
+different paths is `InvalidationBatchAlreadyExists`.
+
+## Origin request policies
+
+An origin request policy decides which of the viewer's headers, cookies and query strings a cache
+Behavior carries to its Origin. Declare one as `AWS::CloudFront::OriginRequestPolicy` and point a
+Behavior's `OriginRequestPolicyId` at it with a `Ref`, which is what CDK's `OriginRequestPolicy`
+construct synthesizes.
+
+```typescript sim-cloudfront-origin-request-policy
+/**
+ * Reading back the origin request policy a Behavior was given.
+ */
+
+import { GetDistributionCommand } from "@aws-sdk/client-cloudfront";
+import { SimAws } from "@kensio/yulin";
+
+const simAws = new SimAws();
+
+const stack = await simAws.cloudFormation().deployTemplate({
+  stackName: "site-stack",
+  template: {
+    Resources: {
+      SiteBucket: {
+        Type: "AWS::S3::Bucket",
+        Properties: { BucketName: "site-bucket" },
+      },
+      BeaconPolicy: {
+        Type: "AWS::CloudFront::OriginRequestPolicy",
+        Properties: {
+          OriginRequestPolicyConfig: {
+            Name: "BeaconPolicy",
+            CookiesConfig: { CookieBehavior: "none" },
+            HeadersConfig: { HeaderBehavior: "none" },
+            QueryStringsConfig: { QueryStringBehavior: "all" },
+          },
+        },
+      },
+      SiteDistribution: {
+        Type: "AWS::CloudFront::Distribution",
+        DependsOn: ["SiteBucket", "BeaconPolicy"],
+        Properties: {
+          DistributionConfig: {
+            DefaultRootObject: "index.html",
+            Origins: [
+              {
+                Id: "SiteOrigin",
+                DomainName: "site-bucket.s3.amazonaws.com",
+                S3OriginConfig: {},
+              },
+            ],
+            DefaultCacheBehavior: {
+              TargetOriginId: "SiteOrigin",
+              ViewerProtocolPolicy: "allow-all",
+              // CORS-S3Origin, one of CloudFront's managed policies.
+              OriginRequestPolicyId: "88a5eaf4-2fd4-4709-b370-b4c650ea3fcf",
+            },
+            CacheBehaviors: [
+              {
+                PathPattern: "/beacon",
+                TargetOriginId: "SiteOrigin",
+                ViewerProtocolPolicy: "allow-all",
+                OriginRequestPolicyId: { Ref: "BeaconPolicy" },
+              },
+            ],
+          },
+        },
+      },
+    },
+    Outputs: {
+      DistributionId: { Value: { Ref: "SiteDistribution" } },
+      BeaconPolicyId: { Value: { Ref: "BeaconPolicy" } },
+    },
+  },
+});
+
+await stack.waitForDeployComplete();
+
+const read = await simAws
+  .cloudFront()
+  .getDistribution(
+    new GetDistributionCommand({ Id: stack.output("DistributionId") }),
+  );
+const config = read.Distribution?.DistributionConfig;
+
+// The managed ID the default Behavior was given.
+console.log(config?.DefaultCacheBehavior?.OriginRequestPolicyId);
+
+// The ID of the policy the template created, which the path Behavior Refs.
+console.log(
+  config?.CacheBehaviors?.Items?.[0]?.OriginRequestPolicyId ===
+    stack.output("BeaconPolicyId"),
+);
+```
+
+A Behavior records the ID it was given, and `GetDistribution` reports it back for both the default
+Behavior and a named one. An update changing the policy is reported the same way.
+
+A policy name is unique within an account, as it is in CloudFront. A second
+`AWS::CloudFront::OriginRequestPolicy` claiming a name is refused with
+`OriginRequestPolicyAlreadyExists`.
+
+`HeadersConfig`, `CookiesConfig` and `QueryStringsConfig` are read along with `Name` and `Comment`.
+`CookieBehavior` and `QueryStringBehavior` each take `none`, `whitelist`, `allExcept` and `all`.
+`HeaderBehavior` takes `none`, `whitelist`, `allExcept`, `allViewer` and
+`allViewerAndWhitelistCloudFront`. An absent section falls back to `none`. A section naming a
+behaviour CloudFront does not offer fails the Stack, naming the Resource.
+
+### What a custom Origin is sent
+
+A custom Origin is sent the headers, cookies and query strings the Behavior's cache policy and
+origin request policy name between them, and none of the rest of the viewer's request. That union is
+what real CloudFront sends. The cache policy half is in it because an Origin has to be able to
+answer for the key its response is stored under.
+
+Alongside it CloudFront sends what it sends of its own accord. `Host` is the Origin's own domain,
+whatever the policies name (a viewer's own `Host` never reaches an Origin here, so
+`AllViewerExceptHostHeader` and `AllViewer` reach a Function URL Origin alike).
+`User-Agent` is `Amazon CloudFront` unless the policies carry the viewer's own. `Accept-Encoding` is
+the normalized `gzip`, `br` or `gzip, br` the cache policy's `EnableAcceptEncoding` flags asked for.
+`Content-Length`, `Content-Type` and `Transfer-Encoding` describe the body and travel with it. The
+Origin's custom headers and its origin access control's signing headers are applied on top.
+
+```typescript sim-cloudfront-origin-request-forwarding
+/**
+ * What a custom Origin reads of the viewer's request, with and without an
+ * origin request policy.
+ */
+
+import {
+  CreateApiCommand,
+  CreateIntegrationCommand,
+  CreateRouteCommand,
+  CreateStageCommand,
+} from "@aws-sdk/client-apigatewayv2";
+import { CreateDistributionCommand } from "@aws-sdk/client-cloudfront";
+import {
+  AddPermissionCommand,
+  CreateFunctionCommand,
+} from "@aws-sdk/client-lambda";
+
+import { SimAws } from "@kensio/yulin";
+import { makeLambdaZipFileInput } from "@kensio/yulin/lambda";
+import { serveSimAws } from "@kensio/yulin/serve";
+
+const simAws = new SimAws();
+
+// A function reporting the query string and the user agent it was asked with.
+const { FunctionArn } = await simAws.lambda().createFunction(
+  new CreateFunctionCommand({
+    FunctionName: "search",
+    Role: "arn:aws:iam::111111111111:role/SearchRole",
+    Code: {
+      ZipFile: makeLambdaZipFileInput(
+        (event: {
+          rawQueryString: string;
+          headers: Record<string, string>;
+        }) => ({
+          query: event.rawQueryString,
+          userAgent: event.headers["user-agent"],
+        }),
+      ),
+    },
+  }),
+);
+
+const apiGateway = simAws.apiGatewayV2();
+
+const { ApiId, ApiEndpoint } = await apiGateway.createApi(
+  new CreateApiCommand({ Name: "search", ProtocolType: "HTTP" }),
+);
+
+const { IntegrationId } = await apiGateway.createIntegration(
+  new CreateIntegrationCommand({
+    ApiId,
+    IntegrationType: "AWS_PROXY",
+    IntegrationUri: FunctionArn,
+    PayloadFormatVersion: "2.0",
+  }),
+);
+
+await apiGateway.createRoute(
+  new CreateRouteCommand({
+    ApiId,
+    RouteKey: "GET /search",
+    Target: `integrations/${IntegrationId}`,
+  }),
+);
+
+await apiGateway.createRoute(
+  new CreateRouteCommand({
+    ApiId,
+    RouteKey: "GET /open/search",
+    Target: `integrations/${IntegrationId}`,
+  }),
+);
+
+await apiGateway.createStage(
+  new CreateStageCommand({ ApiId, StageName: "$default", AutoDeploy: true }),
+);
+
+await simAws.lambda().addPermission(
+  new AddPermissionCommand({
+    FunctionName: "search",
+    StatementId: "api-gateway-invoke",
+    Action: "lambda:InvokeFunction",
+    Principal: "apigateway.amazonaws.com",
+    SourceArn: `arn:aws:execute-api:us-east-1:888888888888:${ApiId}/*/*`,
+  }),
+);
+
+// Two Behaviors on the same Origin. The default names no policy, and /open/*
+// names AllViewer, one of CloudFront's managed policies.
+const distributionCreation = await simAws.cloudFront().createDistribution(
+  new CreateDistributionCommand({
+    DistributionConfig: {
+      CallerReference: "search-site",
+      Comment: "Search CDN",
+      Enabled: true,
+      Origins: {
+        Quantity: 1,
+        Items: [
+          {
+            Id: "api-origin",
+            DomainName: new URL(ApiEndpoint).hostname,
+            CustomOriginConfig: {
+              HTTPPort: 80,
+              HTTPSPort: 443,
+              OriginProtocolPolicy: "https-only",
+            },
+          },
+        ],
+      },
+      DefaultCacheBehavior: {
+        TargetOriginId: "api-origin",
+        ViewerProtocolPolicy: "allow-all",
+      },
+      CacheBehaviors: {
+        Quantity: 1,
+        Items: [
+          {
+            PathPattern: "/open/*",
+            TargetOriginId: "api-origin",
+            ViewerProtocolPolicy: "allow-all",
+            OriginRequestPolicyId: "216adef6-5c7f-47e4-b989-5492eafa07d3",
+          },
+        ],
+      },
+    },
+  }),
+);
+
+const distroHostname = distributionCreation.Distribution!.DomainName!;
+const srv = await serveSimAws({ simAws });
+
+try {
+  const withheld = await fetch(
+    srv.localUrl(`http://${distroHostname}/search?q=kettle`),
+    { headers: { "user-agent": "Firefox" } },
+  );
+
+  // {"query":"","userAgent":"Amazon CloudFront"}
+  console.log(await withheld.text());
+
+  const forwarded = await fetch(
+    srv.localUrl(`http://${distroHostname}/open/search?q=kettle`),
+    { headers: { "user-agent": "Firefox" } },
+  );
+
+  // {"query":"q=kettle","userAgent":"Firefox"}
+  console.log(await forwarded.text());
+} finally {
+  await srv.close();
+}
+```
+
+A Behavior naming neither policy sends the path and nothing else. That is a Distribution CloudFront
+would serve the same way, and an Origin reading a query string behind one is a bug worth a failing
+test.
+
+An S3 Origin is unaffected. It reads its Bucket through GetObject and builds no request to narrow.
+
+### Managed origin request policies
+
+CloudFront's eight managed policies are here from the start, under the IDs AWS publishes, and a
+Behavior names one without a template creating anything. `AllViewer`
+(`216adef6-5c7f-47e4-b989-5492eafa07d3`), `AllViewerAndCloudFrontHeaders-2022-06`
+(`33f36d7e-f396-46d9-90e0-52428a34d9dc`), `AllViewerExceptHostHeader`
+(`b689b0a8-53d0-40ab-baf2-68738e2966ac`), `CORS-CustomOrigin`
+(`59781a5b-3903-41f3-afcb-af62929ccde1`), `CORS-S3Origin` (`88a5eaf4-2fd4-4709-b370-b4c650ea3fcf`),
+`Elemental-MediaTailor-PersonalizedManifests` (`775133bc-15f2-49f9-abea-afb2e0bf67d2`),
+`HostHeaderOnly` (`bf0718e1-ba1e-49d1-88b1-f726733018ae`) and `UserAgentRefererHeaders`
+(`acba4595-bd28-49b8-b9fe-13317c0390fa`) are each held under the name
+[AWS publishes](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/using-managed-origin-request-policies.html)
+for it. CDK's `OriginRequestPolicy.ALL_VIEWER` and its seven siblings synthesize those IDs. A stack
+reaching for one deploys.
+
+Each also carries the three sections AWS publishes for it. A Behavior on `AllViewer` here sends the
+Origin everything the viewer sent bar its `Host`, which is the Origin's own domain under every
+policy. One on `CORS-CustomOrigin` sends the `Origin` header alone. One on
+`AllViewerExceptHostHeader` sends what `AllViewer` sends, since the `Host` it withholds was never
+the viewer's here.
+
+The managed policies sit in CloudFront's own namespace. A template may create a policy called
+`AllViewer` of its own, and deleting that stack leaves the managed one where it was.
+
+A CloudFormation Distribution whose Behavior names a policy that is neither managed nor created here
+deploys without one. The `OriginRequestPolicyId` lands on `stack.ignoredProperties` under that
+Behavior, the way an absent cache policy does, and the Behavior reports no policy.
+
+`CreateDistribution` and `UpdateDistribution` still refuse the same ID with
+`NoSuchOriginRequestPolicy`, as real CloudFront refuses it.
+
 ## Origin access controls
 
 An origin access control is how a Distribution authenticates to a private Origin. The Origin then
@@ -2945,6 +3803,12 @@ Sim CloudFront currently supports:
 - CloudFront Functions reading an associated key value store through `cf.kvs()`
 - `AWS::CloudFront::ResponseHeadersPolicy`, for headers a cache Behavior sets on every response
 - `AWS::CloudFront::CachePolicy`, and a Behavior's `CachePolicyId` read back through `GetDistribution`
+- A cache on each Distribution, keyed on the Behavior's cache policy and on the edge the request
+  arrived at, expiring on the simulation's clock
+- `CreateInvalidationCommand`, `GetInvalidationCommand` and `ListInvalidationsCommand`, clearing
+  what a Distribution holds and reading the batches back
+- `AWS::CloudFront::OriginRequestPolicy`, and a Behavior's `OriginRequestPolicyId` read back the
+  same way
 - `AWS::CloudFront::KeyValueStore`, and `KeyValueStoreAssociations` on `AWS::CloudFront::Function`
 - `AWS::CloudFront::OriginAccessControl`, letting an Origin read a private Bucket as CloudFront
 - Viewer certificates from sim ACM, including CloudFront's `us-east-1` requirement
@@ -2959,12 +3823,27 @@ whether the simulator needs them to model the requested behaviour safely.
 
 Where sim CloudFront knowingly behaves differently from AWS:
 
-- **The origin events run on every request that reaches the Origin.** Real CloudFront runs
-  `origin-request` and `origin-response` on a cache miss, and serves a cache hit without reaching
-  either. Simulated CloudFront holds no cache, and every request that gets as far as the Origin is a
-  miss here. A request a web ACL blocked or a viewer-request function answered reaches neither
-  event, and an `origin-request` function that returns a response leaves the Origin unread with no
-  `origin-response` event after it.
+- **An expired entry is fetched again rather than revalidated.** Real CloudFront asks the Origin
+  whether the object has changed and takes a `304 Not Modified` as permission to carry on serving
+  what it holds. Here the expired entry is dropped and the Origin's next answer replaces it.
+  `Stale-While-Revalidate` and `Stale-If-Error` are read as no directive at all. Nothing stale is
+  ever served.
+- **A cached entry stays until it expires or an invalidation clears it.** Nothing evicts one to make
+  room.
+- **`X-Cache` says Hit or Miss and nothing else.** Real CloudFront also reports `RefreshHit`,
+  `Error`, `Redirect`, `LambdaGeneratedResponse` and `FunctionGeneratedResponse` there. A response
+  answered before the cache was reached (one a web ACL blocked, or one a viewer-request function
+  returned) carries no `X-Cache` at all.
+- **An invalidation listing is never paged.** `ListInvalidations` echoes the `Marker` and `MaxItems`
+  it was sent and answers with every invalidation the Distribution holds. `IsTruncated` is always
+  false and no `NextMarker` comes back. Real CloudFront pages at 100.
+- **A Behavior with no cache policy caches nothing.** Real CloudFront falls back to the legacy
+  `ForwardedValues` and the TTLs beside it, and sim CloudFront skips both. Give the Behavior a
+  `CachePolicyId`, as CDK and the console both do.
+- **Every error status is held for its error TTL.** Real CloudFront caches 404, 414, 500, 501, 502,
+  503 and 504, and caches 400, 403 and 405 only where the Origin sent a `Cache-Control max-age` or
+  `s-maxage` header. It then holds the error for the longer of that header and `ErrorCachingMinTTL`.
+  Here every status of 400 and above is held for `ErrorCachingMinTTL` alone.
 - **An Origin keeps its kind and its Bucket through an origin-request function.** Real CloudFront
   lets a handler hand back `origin.s3` where it was given `origin.custom`, or point an S3 Origin at
   another Bucket. Both need something a simulated Origin does not hold, the dispatcher that reaches
@@ -3087,12 +3966,11 @@ Where sim CloudFront knowingly behaves differently from AWS:
   share of real responses carry `Server-Timing`. This simulation adds it to every response once
   `Enabled` is true. A test asserting on it never depends on chance. The header's value is a
   fixed placeholder, since nothing here measures an Origin fetch the way CloudFront's edge does.
-- **A cache policy is recorded and never applied.** Sim CloudFront models no edge caching. A
-  Behavior's `CachePolicyId` is checked against the policies this simulation holds and reported
-  back, and the TTLs, the cache key and the compression settings behind it decide nothing. Every
-  request reaches the Origin, whatever the policy would have cached on real CloudFront.
-- **A cache policy carries its name and its comment, and nothing else.** The TTLs and
-  `ParametersInCacheKeyAndForwardedToOrigin` of an `AWS::CloudFront::CachePolicy` are read past,
-  since nothing here would act on them.
-- **`OriginRequestPolicyId` is accepted and ignored.** A Behavior's origin request policy is left
-  unvalidated, and `AWS::CloudFront::OriginRequestPolicy` is skipped.
+- **A viewer's `Host` header never reaches an Origin.** Real CloudFront forwards it where a policy
+  names it, which is what `AllViewerExceptHostHeader` exists to stop. Here an Origin request always
+  carries the Origin's own domain as `Host`, since the request has to reach the simulated service
+  its URL names.
+- **CloudFront's own headers are not generated.** `X-Amz-Cf-Id`, `Via`, `X-Forwarded-For` and the
+  `CloudFront-Viewer-*` family are absent from an Origin request, so a policy naming one of them
+  forwards nothing. `Host`, `User-Agent` and the normalized `Accept-Encoding` are the three this
+  simulation sends of its own accord.