@kensio/yulin 1.20.16 → 1.21.0

package/dist/service/cloudfront/cache/sim-cf-accept-encoding.js

@@ -0,0 +1,27 @@
+/**
+ * The compression the policy keys on, as CloudFront's normalized
+ * `Accept-Encoding`.
+ *
+ * This is what caches one object twice, once compressed and once not, without
+ * the header being in the policy's whitelist. An encoding the viewer accepts
+ * but the policy does not enable is left out, since CloudFront would not have
+ * asked the Origin for it.
+ */
+export function simCfNormalizedAcceptEncoding(headers, cacheKey) {
+    const enabled = [
+        ...(cacheKey.enableAcceptEncodingBrotli ? ["br"] : []),
+        ...(cacheKey.enableAcceptEncodingGzip ? ["gzip"] : []),
+    ];
+    const accepted = acceptedEncodings(headers.get("accept-encoding"));
+    return enabled.filter((encoding) => accepted.has(encoding));
+}
+/**
+ * The encodings a viewer said it accepts, by name alone. A quality value is
+ * ignored, so a viewer that sent `gzip;q=0` is taken to accept gzip.
+ */
+function acceptedEncodings(headerValue) {
+    return new Set((headerValue ?? "").split(",").map((encoding) => {
+        const [name = ""] = encoding.split(";", 1);
+        return name.trim().toLowerCase();
+    }));
+}

package/dist/service/cloudfront/cache/sim-cf-cache-control.d.ts

@@ -0,0 +1,28 @@
+/**
+ * What an Origin's `Cache-Control` header says about holding the object at an
+ * edge.
+ *
+ * Only the directives that move CloudFront's own cache duration are read.
+ * `stale-while-revalidate` and `stale-if-error` are left out, because serving
+ * a stale object is a behaviour of its own that this simulation does not have.
+ *
+ * https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/Expiration.html
+ */
+export interface SimCfCacheControl {
+    /**
+     * Whether the Origin asked for the object to stay out of a shared cache,
+     * through `no-store`, `no-cache` or `private`.
+     */
+    readonly uncacheable: boolean;
+    /** The seconds `s-maxage` names, where it names a usable number of them. */
+    readonly sharedMaxAgeSec: number | undefined;
+    /** The seconds `max-age` names, where it names a usable number of them. */
+    readonly maxAgeSec: number | undefined;
+}
+/**
+ * Read the `Cache-Control` directives a response carries.
+ *
+ * A directive naming something other than a whole number of seconds is read as
+ * absent. `max-age=soon` falls through to whatever the response says next.
+ */
+export declare function simCfCacheControl(header: string | null): SimCfCacheControl;

package/dist/service/cloudfront/cache/sim-cf-cache-control.js

@@ -0,0 +1,49 @@
+/**
+ * The three directives CloudFront and a browser both respect as a refusal.
+ */
+const uncacheableDirectives = ["no-store", "no-cache", "private"];
+/**
+ * Read the `Cache-Control` directives a response carries.
+ *
+ * A directive naming something other than a whole number of seconds is read as
+ * absent. `max-age=soon` falls through to whatever the response says next.
+ */
+export function simCfCacheControl(header) {
+    const directives = cacheControlDirectives(header);
+    return {
+        uncacheable: uncacheableDirectives.some((directive) => directives.has(directive)),
+        sharedMaxAgeSec: directiveSeconds(directives.get("s-maxage")),
+        maxAgeSec: directiveSeconds(directives.get("max-age")),
+    };
+}
+/**
+ * Split a header into its directives, by lower-cased name.
+ *
+ * A directive carrying no value is held under an empty string, which is what
+ * makes `no-store` findable the same way as `max-age=60`.
+ */
+function cacheControlDirectives(header) {
+    const directives = new Map();
+    const parts = (header ?? "").split(",");
+    for (const part of parts) {
+        const trimmed = part.trim();
+        if (trimmed.length === 0) {
+            continue;
+        }
+        const separator = trimmed.indexOf("=");
+        const name = separator === -1 ? trimmed : trimmed.slice(0, Math.max(0, separator));
+        directives.set(name.trim().toLowerCase(), separator === -1 ? "" : trimmed.slice(separator + 1).trim());
+    }
+    return directives;
+}
+/**
+ * The seconds a directive's value names, or none where it names no whole
+ * number of them.
+ */
+function directiveSeconds(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    const seconds = value.replace(/^"(.*)"$/, "$1");
+    return /^\d+$/.test(seconds) ? Number(seconds) : undefined;
+}

package/dist/service/cloudfront/cache/sim-cf-cache-entry-key-path.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The request path one cache entry was keyed under.
+ *
+ * `simCfCacheEntryKey` builds the key as a JSON array with the path third in
+ * it, and this reads that element back out. An invalidation matches entries by
+ * path this way, and the cache keeps its one map keyed on the whole key.
+ *
+ * A key of another shape answers with nothing. An invalidation then leaves the
+ * entry where it is.
+ */
+export declare function simCfCacheEntryKeyPath(key: string): string | undefined;

package/dist/service/cloudfront/cache/sim-cf-cache-entry-key-path.js

@@ -0,0 +1,22 @@
+/**
+ * Where the request path sits in a cache entry key.
+ */
+const cacheEntryKeyPathIndex = 2;
+/**
+ * The request path one cache entry was keyed under.
+ *
+ * `simCfCacheEntryKey` builds the key as a JSON array with the path third in
+ * it, and this reads that element back out. An invalidation matches entries by
+ * path this way, and the cache keeps its one map keyed on the whole key.
+ *
+ * A key of another shape answers with nothing. An invalidation then leaves the
+ * entry where it is.
+ */
+export function simCfCacheEntryKeyPath(key) {
+    const parts = JSON.parse(key);
+    if (!Array.isArray(parts)) {
+        return undefined;
+    }
+    const path = parts.at(cacheEntryKeyPathIndex);
+    return typeof path === "string" ? path : undefined;
+}

package/dist/service/cloudfront/cache/sim-cf-cache-entry-key.d.ts

@@ -0,0 +1,32 @@
+import type { SimCloudFrontCacheKey } from "../cache-policy/sim-cf-cache-key.js";
+interface SimCfCacheEntryKeyProperties {
+    readonly request: Request;
+    /**
+     * What the Behavior's cache policy keys on.
+     */
+    readonly cacheKey: SimCloudFrontCacheKey;
+    /**
+     * The edge the request arrived at, which caches apart from every other edge.
+     */
+    readonly edgeId: string;
+}
+/**
+ * The key one request is cached under.
+ *
+ * CloudFront keys on the request path plus whatever the cache policy names:
+ * the query strings, the headers and the cookies it lists, and the normalized
+ * `Accept-Encoding` where it enables gzip or brotli. Two requests differing
+ * only in something the policy leaves out share one entry, which is the whole
+ * point of a cache key.
+ *
+ * The path sits third in the key, which `simCfCacheEntryKeyPath` reads it back
+ * out of when an invalidation matches an entry.
+ *
+ * The method is part of the key here because a HEAD response carries no body
+ * and a GET response does, so serving one from the other would answer with the
+ * wrong thing.
+ *
+ * https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/understanding-the-cache-key.html
+ */
+export declare function simCfCacheEntryKey(properties: SimCfCacheEntryKeyProperties): string;
+export {};

package/dist/service/cloudfront/cache/sim-cf-cache-entry-key.js

@@ -0,0 +1,112 @@
+import { jsonStringify } from "../../../util/type-guard/json.js";
+import { simCfNormalizedAcceptEncoding } from "./sim-cf-accept-encoding.js";
+/**
+ * The key one request is cached under.
+ *
+ * CloudFront keys on the request path plus whatever the cache policy names:
+ * the query strings, the headers and the cookies it lists, and the normalized
+ * `Accept-Encoding` where it enables gzip or brotli. Two requests differing
+ * only in something the policy leaves out share one entry, which is the whole
+ * point of a cache key.
+ *
+ * The path sits third in the key, which `simCfCacheEntryKeyPath` reads it back
+ * out of when an invalidation matches an entry.
+ *
+ * The method is part of the key here because a HEAD response carries no body
+ * and a GET response does, so serving one from the other would answer with the
+ * wrong thing.
+ *
+ * https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/understanding-the-cache-key.html
+ */
+export function simCfCacheEntryKey(properties) {
+    const { request, cacheKey, edgeId } = properties;
+    const url = new URL(request.url);
+    return jsonStringify([
+        edgeId,
+        request.method.toUpperCase(),
+        url.pathname,
+        keyedQueryStrings(url.searchParams, cacheKey),
+        keyedHeaders(request.headers, cacheKey),
+        keyedCookies(request.headers, cacheKey),
+        simCfNormalizedAcceptEncoding(request.headers, cacheKey),
+    ]);
+}
+/**
+ * The query strings the policy keys on, in an order two requests sending them
+ * differently still agree on.
+ */
+function keyedQueryStrings(searchParameters, cacheKey) {
+    return [...searchParameters]
+        .filter(([name]) => isKeyedOn(cacheKey.queryStringBehavior, cacheKey.queryStrings, name))
+        .map(([name, value]) => `${name}=${value}`)
+        .toSorted(byCodePoint);
+}
+/**
+ * The headers the policy keys on, by lower-case name since a header name is
+ * case insensitive.
+ *
+ * A header the policy names and the viewer did not send keys as an empty
+ * value, so a request sending it and one leaving it out are kept apart.
+ */
+function keyedHeaders(headers, cacheKey) {
+    if (cacheKey.headerBehavior === "none") {
+        return [];
+    }
+    return cacheKey.headers
+        .map((name) => `${name.toLowerCase()}=${headers.get(name) ?? ""}`)
+        .toSorted(byCodePoint);
+}
+/**
+ * The cookies the policy keys on, read out of the one `Cookie` header a
+ * request sends them all in.
+ */
+function keyedCookies(headers, cacheKey) {
+    return (headers.get("cookie") ?? "")
+        .split(";")
+        .map((cookie) => cookie.trim())
+        .filter((cookie) => cookie.length > 0)
+        .filter((cookie) => isKeyedOn(cacheKey.cookieBehavior, cacheKey.cookies, cookieName(cookie)))
+        .toSorted(byCodePoint);
+}
+/**
+ * Order two parts of a key the same way whatever the host's locale is, which a
+ * key two requests have to agree on cannot be left to `localeCompare`.
+ */
+function byCodePoint(one, other) {
+    if (one === other) {
+        return 0;
+    }
+    return one < other ? -1 : 1;
+}
+/**
+ * The name half of one `name=value` cookie.
+ */
+function cookieName(cookie) {
+    const [name = ""] = cookie.split("=", 1);
+    return name;
+}
+/**
+ * Whether one name is in the cache key, under the behaviour its section names.
+ *
+ * A `whitelist` keys on the names listed and an `allExcept` keys on everything
+ * but them, which is the same list read two ways.
+ *
+ * The cookie behaviours and the query string behaviours are the same four
+ * values, so one function reads both.
+ */
+function isKeyedOn(behavior, names, name) {
+    switch (behavior) {
+        case "all": {
+            return true;
+        }
+        case "whitelist": {
+            return names.includes(name);
+        }
+        case "allExcept": {
+            return !names.includes(name);
+        }
+        case "none": {
+            return false;
+        }
+    }
+}

package/dist/service/cloudfront/cache/sim-cf-cache-status.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The header a hit carries its age in, in seconds.
+ */
+export declare const simCfAgeHeaderName = "age";
+/**
+ * What `X-Cache` reads when the Distribution's cache answered.
+ */
+export declare const simCfCacheHit = "Hit from cloudfront";
+/**
+ * What `X-Cache` reads when the Origin answered.
+ */
+export declare const simCfCacheMiss = "Miss from cloudfront";
+/**
+ * The response with `X-Cache` saying which of the two answered it.
+ *
+ * An `X-Cache` an Origin sent is replaced, the way CloudFront replaces one.
+ */
+export declare function simCfCacheStatusResponse(response: Response, hit: boolean): Response;
+/**
+ * How long an entry stored at one instant has been held at another, in whole
+ * seconds.
+ *
+ * Both instants come off the simulation's clock. A test reaches any age it
+ * wants by advancing simulated time. A clock wound backwards would give a
+ * negative age, and HTTP has no such thing, so zero is the floor.
+ */
+export declare function simCfCacheAgeSec(storedAt: Date, now: Date): number;

package/dist/service/cloudfront/cache/sim-cf-cache-status.js

@@ -0,0 +1,53 @@
+/**
+ * What CloudFront tells the viewer about the cache that answered.
+ *
+ * `X-Cache` says whether the Distribution held the object, and `Age` says how
+ * long it has held it. Both go on ahead of the Behavior's response headers
+ * policy and the viewer-response event. A policy can take either off, and a
+ * viewer-response function sees them.
+ *
+ * Real CloudFront writes several other values into `X-Cache` (`RefreshHit` and
+ * `LambdaGeneratedResponse` among them). A hit and a miss are the two this
+ * simulation reaches, and a response answered before the cache was consulted
+ * carries no `X-Cache` at all.
+ *
+ * https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/RequestAndResponseBehaviorCustomOrigin.html
+ */
+const xCacheHeaderName = "x-cache";
+/**
+ * The header a hit carries its age in, in seconds.
+ */
+export const simCfAgeHeaderName = "age";
+/**
+ * What `X-Cache` reads when the Distribution's cache answered.
+ */
+export const simCfCacheHit = "Hit from cloudfront";
+/**
+ * What `X-Cache` reads when the Origin answered.
+ */
+export const simCfCacheMiss = "Miss from cloudfront";
+/**
+ * The response with `X-Cache` saying which of the two answered it.
+ *
+ * An `X-Cache` an Origin sent is replaced, the way CloudFront replaces one.
+ */
+export function simCfCacheStatusResponse(response, hit) {
+    const headers = new Headers(response.headers);
+    headers.set(xCacheHeaderName, hit ? simCfCacheHit : simCfCacheMiss);
+    return new Response(response.body, {
+        status: response.status,
+        statusText: response.statusText,
+        headers,
+    });
+}
+/**
+ * How long an entry stored at one instant has been held at another, in whole
+ * seconds.
+ *
+ * Both instants come off the simulation's clock. A test reaches any age it
+ * wants by advancing simulated time. A clock wound backwards would give a
+ * negative age, and HTTP has no such thing, so zero is the floor.
+ */
+export function simCfCacheAgeSec(storedAt, now) {
+    return Math.max(0, Math.floor((now.getTime() - storedAt.getTime()) / 1000));
+}

package/dist/service/cloudfront/cache/sim-cf-cache-ttl.d.ts

@@ -0,0 +1,28 @@
+import type { SimCloudFrontCachePolicy } from "../cache-policy/sim-cf-cache-policy.js";
+interface SimCfCacheTtlProperties {
+    /** The response the Origin answered with, whose headers carry the ask. */
+    readonly response: Response;
+    /** The Behavior's cache policy, whose three TTLs decide the answer. */
+    readonly policy: SimCloudFrontCachePolicy;
+    /** Now, off the simulation's clock, which `Expires` is measured from. */
+    readonly now: Date;
+}
+/**
+ * How many seconds a Distribution holds this response for. Zero says it holds
+ * it not at all.
+ *
+ * The Origin asks and the policy decides how much of the ask to grant. An
+ * Origin naming a duration gets it held between the policy's `MinTTL` and
+ * `MaxTTL`, and one naming none gets the greater of `MinTTL` and `DefaultTTL`.
+ * `s-maxage` is preferred to `max-age`, and `max-age` to `Expires`, which is
+ * the order CloudFront reads them in.
+ *
+ * `no-store`, `no-cache` and `private` are respected where `MinTTL` is 0, and
+ * held for `MinTTL` where it is higher. That last one is CloudFront's own
+ * surprise. A policy with a floor overrides an Origin that asked for nothing to
+ * be stored.
+ *
+ * https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/Expiration.html
+ */
+export declare function simCfCacheTtlSec(properties: SimCfCacheTtlProperties): number;
+export {};

package/dist/service/cloudfront/cache/sim-cf-cache-ttl.js

@@ -0,0 +1,50 @@
+import { simCfCacheControl } from "./sim-cf-cache-control.js";
+import { simCfHttpDateInstant } from "./sim-cf-http-date.js";
+/**
+ * How many seconds a Distribution holds this response for. Zero says it holds
+ * it not at all.
+ *
+ * The Origin asks and the policy decides how much of the ask to grant. An
+ * Origin naming a duration gets it held between the policy's `MinTTL` and
+ * `MaxTTL`, and one naming none gets the greater of `MinTTL` and `DefaultTTL`.
+ * `s-maxage` is preferred to `max-age`, and `max-age` to `Expires`, which is
+ * the order CloudFront reads them in.
+ *
+ * `no-store`, `no-cache` and `private` are respected where `MinTTL` is 0, and
+ * held for `MinTTL` where it is higher. That last one is CloudFront's own
+ * surprise. A policy with a floor overrides an Origin that asked for nothing to
+ * be stored.
+ *
+ * https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/Expiration.html
+ */
+export function simCfCacheTtlSec(properties) {
+    const { response, policy, now } = properties;
+    const control = simCfCacheControl(response.headers.get("cache-control"));
+    if (control.uncacheable) {
+        return policy.minTtlSec;
+    }
+    const asked = control.sharedMaxAgeSec ??
+        control.maxAgeSec ??
+        expiresTtlSec(response, now);
+    if (asked === undefined) {
+        return Math.max(policy.minTtlSec, policy.defaultTtlSec);
+    }
+    return Math.min(Math.max(asked, policy.minTtlSec), policy.maxTtlSec);
+}
+/**
+ * The seconds left until the `Expires` header's instant, or none where the
+ * response carries no such header.
+ *
+ * A date already gone by counts as no seconds, which the policy's `MinTTL`
+ * then raises where it has one. A value that is not an HTTP date counts the
+ * same way, following RFC 9111, which reads an unparsable `Expires` as an
+ * object that has already expired.
+ */
+function expiresTtlSec(response, now) {
+    const expires = response.headers.get("expires");
+    if (expires === null) {
+        return undefined;
+    }
+    const instant = simCfHttpDateInstant(expires.trim());
+    return instant === undefined ? 0 : (instant - now.getTime()) / 1000;
+}

package/dist/service/cloudfront/cache/sim-cf-cacheable-request.d.ts

@@ -0,0 +1,35 @@
+import type { SimCloudFrontBehavior } from "../behaviour/sim-cloud-front-behavior.js";
+import type { SimCloudFrontCachePolicy } from "../cache-policy/sim-cf-cache-policy.js";
+import type { SimCloudFront } from "../sim-cloudfront.js";
+interface SimCfCacheableRequestProperties {
+    readonly cloudFront: SimCloudFront;
+    readonly behaviour: SimCloudFrontBehavior;
+    readonly request: Request;
+    readonly edgeId: string;
+}
+/**
+ * A request the Behavior caches, and what decides for how long.
+ */
+export interface SimCfCacheableRequest {
+    /** The key the request is cached under. */
+    readonly key: string;
+    /**
+     * The policy the key came from, whose TTLs settle how long the Origin's
+     * answer is held.
+     */
+    readonly policy: SimCloudFrontCachePolicy;
+}
+/**
+ * The key this request is cached under and the policy that decided it, or none
+ * where the Behavior caches nothing.
+ *
+ * Three things stop a Behavior caching. Its cache policy may be one this
+ * simulation does not hold, including the Behavior that names no policy at
+ * all, and there is nothing to key on and no TTL that is not a guess. Its
+ * policy may cache nothing, which is what a `MaxTTL` of zero says and is how
+ * `CachingDisabled` reaches the Origin every time. Or the request's method may
+ * be outside the Behavior's `CachedMethods`, which is CloudFront's own rule
+ * that a POST is never served from a cache.
+ */
+export declare function simCfCacheableRequest(properties: SimCfCacheableRequestProperties): SimCfCacheableRequest | undefined;
+export {};

package/dist/service/cloudfront/cache/sim-cf-cacheable-request.js

@@ -0,0 +1,32 @@
+import { simCfCacheEntryKey } from "./sim-cf-cache-entry-key.js";
+/**
+ * The key this request is cached under and the policy that decided it, or none
+ * where the Behavior caches nothing.
+ *
+ * Three things stop a Behavior caching. Its cache policy may be one this
+ * simulation does not hold, including the Behavior that names no policy at
+ * all, and there is nothing to key on and no TTL that is not a guess. Its
+ * policy may cache nothing, which is what a `MaxTTL` of zero says and is how
+ * `CachingDisabled` reaches the Origin every time. Or the request's method may
+ * be outside the Behavior's `CachedMethods`, which is CloudFront's own rule
+ * that a POST is never served from a cache.
+ */
+export function simCfCacheableRequest(properties) {
+    const { cloudFront, behaviour, request, edgeId } = properties;
+    if (!cloudFront.cachingEnabled) {
+        return undefined;
+    }
+    const policy = behaviour.cachePolicyId === undefined
+        ? undefined
+        : cloudFront.getCachePolicyById(behaviour.cachePolicyId);
+    if (policy === undefined || policy.maxTtlSec <= 0) {
+        return undefined;
+    }
+    if (!behaviour.cachedMethods.has(request.method.toUpperCase())) {
+        return undefined;
+    }
+    return {
+        key: simCfCacheEntryKey({ request, cacheKey: policy.cacheKey, edgeId }),
+        policy,
+    };
+}

package/dist/service/cloudfront/cache/sim-cf-distribution-cache.d.ts

@@ -0,0 +1,57 @@
+import { type SimClock } from "../../../util/clock/sim-clock.js";
+/**
+ * What one simulated Distribution has cached.
+ *
+ * Real CloudFront caches at each of its points of presence rather than once
+ * per Distribution, which the edge in the key stands for. One cache holds an
+ * entry per edge, and a request arriving at another edge misses.
+ *
+ * An entry leaves the cache two ways. It expires on the simulation's clock
+ * rather than the host's. A test reaches the instant an object goes stale by
+ * advancing simulated time, with no waiting. Or an invalidation clears it ahead
+ * of that instant.
+ *
+ * Storing takes its seconds from the caller. An Origin's answer is held for
+ * what its cache policy allows, and an error's own `ErrorCachingMinTTL` fits
+ * the same call.
+ */
+export declare class SimCfDistributionCache {
+    private readonly entries;
+    private readonly clock;
+    /**
+     * A cache built standalone, outside a Distribution, falls back to the real
+     * clock.
+     */
+    constructor(clock?: SimClock);
+    /**
+     * The response cached under a key, or none where the cache does not hold it.
+     *
+     * An entry that has reached its expiry is dropped here. The request then goes
+     * to the Origin, and what the Origin answers replaces the expired entry.
+     *
+     * What comes back carries `Age`, counted on the simulation's clock from the
+     * instant the Origin's answer was stored. An `Age` the Origin sent is
+     * replaced by the Distribution's own, as CloudFront replaces one.
+     */
+    read(key: string): Response | undefined;
+    /**
+     * Cache a response under a key for a number of seconds, and hand back one to
+     * carry on with.
+     *
+     * Storing reads the response's body, which can only happen once, so the
+     * response the caller continues with is built from the bytes that were
+     * stored rather than being the one passed in. A TTL of no seconds stores
+     * nothing, and the response passed in is handed straight back unread.
+     */
+    store(key: string, response: Response, ttlSec: number): Promise<Response>;
+    /**
+     * Forget every entry an invalidation's paths name, at every edge.
+     *
+     * The path an entry was cached under is read back out of its key, so
+     * matching a batch costs a pass over the keys rather than a second map from
+     * path to entry. Nothing here is keyed on the edge, because an invalidation
+     * reaches every point of presence rather than the one a viewer happened to
+     * arrive at.
+     */
+    clearPaths(paths: readonly string[]): void;
+}