bazis 0.96.1

package/core/cache/http/CachedHttpPayload.ts

@@ -0,0 +1,213 @@
+import { CacheValueError } from "../errors/CacheError";
+
+/** Headers that must not be stored or replayed from output cache. */
+const STRIP_RESPONSE_HEADERS = new Set([
+  "authorization",
+  "cookie",
+  "proxy-authenticate",
+  "proxy-authorization",
+  "set-cookie",
+  "www-authenticate",
+]);
+
+export function stripSensitiveResponseHeaders(headers: Readonly<Record<string, string>>): Record<string, string> {
+  const next: Record<string, string> = {};
+  for (const [key, value] of Object.entries(headers)) {
+    if (!STRIP_RESPONSE_HEADERS.has(key.toLowerCase())) {
+      next[key] = value;
+    }
+  }
+  return next;
+}
+
+/** Serialized HTTP response stored in {@link ICache}. */
+export interface CachedHttpPayload {
+  readonly status: number;
+  readonly headers: Readonly<Record<string, string>>;
+  readonly body: Uint8Array;
+}
+
+export interface CachedHttpPayloadReadOptions {
+  /** Default 16 MiB. Set to 0 only for an explicit unbounded compatibility path. */
+  readonly maxBodyBytes?: number;
+  /** Total materialization timeout. Default 5000ms; 0 disables it. */
+  readonly bodyReadTimeoutMs?: number;
+}
+
+export interface ResolvedCachedHttpPayloadReadOptions {
+  readonly maxBodyBytes: number;
+  readonly bodyReadTimeoutMs: number;
+}
+
+export const DEFAULT_OUTPUT_CACHE_MAX_BODY_BYTES = 16 * 1024 * 1024;
+export const DEFAULT_OUTPUT_CACHE_BODY_READ_TIMEOUT_MS = 5_000;
+
+export function resolveCachedHttpPayloadReadOptions(
+  options: CachedHttpPayloadReadOptions = {},
+): ResolvedCachedHttpPayloadReadOptions {
+  const maxBodyBytes = options.maxBodyBytes ?? DEFAULT_OUTPUT_CACHE_MAX_BODY_BYTES;
+  const bodyReadTimeoutMs = options.bodyReadTimeoutMs ?? DEFAULT_OUTPUT_CACHE_BODY_READ_TIMEOUT_MS;
+  if (!Number.isSafeInteger(maxBodyBytes) || maxBodyBytes < 0) {
+    throw new CacheValueError("output cache maxBodyBytes must be a non-negative safe integer");
+  }
+  if (!Number.isSafeInteger(bodyReadTimeoutMs) || bodyReadTimeoutMs < 0) {
+    throw new CacheValueError("output cache bodyReadTimeoutMs must be a non-negative safe integer");
+  }
+  return Object.freeze({ maxBodyBytes, bodyReadTimeoutMs });
+}
+
+/**
+ * Dynamic response directives always win over decorator metadata. This keeps
+ * authentication/session responses and application-declared private responses
+ * out of shared server caches.
+ */
+export function responseAllowsServerCache(
+  response: Response,
+  configuredVaryHeaders: readonly string[] = [],
+): boolean {
+  if (response.headers.has("set-cookie")) {
+    return false;
+  }
+
+  const cacheControl = response.headers.get("cache-control")?.toLowerCase() ?? "";
+  const directives = cacheControl.split(",").map((part) => part.trim().split("=", 1)[0]);
+  if (directives.includes("no-store") || directives.includes("private")) {
+    return false;
+  }
+
+  const vary = response.headers.get("vary");
+  if (vary === null || vary.trim().length === 0) {
+    return true;
+  }
+  const allowed = new Set(configuredVaryHeaders.map((name) => name.trim().toLowerCase()));
+  for (const name of vary.split(",").map((part) => part.trim().toLowerCase())) {
+    if (name === "*" || name.length === 0 || !allowed.has(name)) {
+      return false;
+    }
+  }
+  return true;
+}
+
+export async function responseToCachedPayload(
+  response: Response,
+  options: CachedHttpPayloadReadOptions | ResolvedCachedHttpPayloadReadOptions = {},
+): Promise<CachedHttpPayload | undefined> {
+  const limits = resolveCachedHttpPayloadReadOptions(options);
+  const advertised = Number(response.headers.get("content-length"));
+  if (limits.maxBodyBytes > 0 && Number.isFinite(advertised) && advertised > limits.maxBodyBytes) {
+    return undefined;
+  }
+
+  const headers: Record<string, string> = {};
+  response.headers.forEach((value, key) => {
+    const lower = key.toLowerCase();
+    if (!STRIP_RESPONSE_HEADERS.has(lower)) {
+      headers[lower] = value;
+    }
+  });
+  if (response.body === null) {
+    return { status: response.status, headers, body: new Uint8Array() };
+  }
+
+  let clone: ReturnType<Response["clone"]>;
+  try {
+    // Read a tee so an over-limit/slow response remains available to the
+    // caller and is merely skipped by the cache.
+    clone = response.clone();
+  } catch {
+    return undefined;
+  }
+  const body = await readBoundedBody(clone.body as unknown as CacheReadableBody | null, limits);
+  if (body === undefined) {
+    return undefined;
+  }
+  // The cached payload replaces the original response. Release its tee branch
+  // after the clone has been fully materialized.
+  await response.body.cancel().catch(() => undefined);
+  return { status: response.status, headers, body };
+}
+
+export function cachedPayloadToResponse(payload: CachedHttpPayload): Response {
+  return new Response(payload.body as unknown as ConstructorParameters<typeof Response>[0], {
+    status: payload.status,
+    headers: stripSensitiveResponseHeaders(payload.headers),
+  });
+}
+
+const BODY_READ_TIMEOUT = Symbol("output-cache-body-read-timeout");
+
+async function readBoundedBody(
+  body: CacheReadableBody | null,
+  options: ResolvedCachedHttpPayloadReadOptions,
+): Promise<Uint8Array | undefined> {
+  if (body === null) return new Uint8Array();
+  const reader = body.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  const deadline = options.bodyReadTimeoutMs === 0
+    ? undefined
+    : performance.now() + options.bodyReadTimeoutMs;
+  try {
+    while (true) {
+      const item = await readBeforeDeadline(reader, deadline);
+      if (item === BODY_READ_TIMEOUT) {
+        void reader.cancel("output cache body read timed out").catch(() => undefined);
+        return undefined;
+      }
+      if (item.done) break;
+      total += item.value.byteLength;
+      if (options.maxBodyBytes > 0 && total > options.maxBodyBytes) {
+        void reader.cancel("output cache body exceeds maxBodyBytes").catch(() => undefined);
+        return undefined;
+      }
+      chunks.push(item.value);
+    }
+  } catch {
+    void reader.cancel().catch(() => undefined);
+    return undefined;
+  } finally {
+    reader.releaseLock();
+  }
+
+  const result = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    result.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return result;
+}
+
+async function readBeforeDeadline(
+  reader: CacheBodyReader,
+  deadline: number | undefined,
+): Promise<CacheBodyReadResult | typeof BODY_READ_TIMEOUT> {
+  if (deadline === undefined) return reader.read();
+  const remaining = deadline - performance.now();
+  if (remaining <= 0) return BODY_READ_TIMEOUT;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      reader.read(),
+      new Promise<typeof BODY_READ_TIMEOUT>((resolve) => {
+        timer = setTimeout(() => resolve(BODY_READ_TIMEOUT), remaining);
+      }),
+    ]);
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+  }
+}
+
+type CacheBodyReadResult =
+  | { readonly done: true; readonly value?: undefined }
+  | { readonly done: false; readonly value: Uint8Array };
+
+interface CacheBodyReader {
+  read(): Promise<CacheBodyReadResult>;
+  cancel(reason?: unknown): Promise<void>;
+  releaseLock(): void;
+}
+
+interface CacheReadableBody {
+  getReader(): CacheBodyReader;
+}

package/core/cache/http/applyClientCacheHeaders.ts

@@ -0,0 +1,61 @@
+import type { ClientCacheOptions } from "../types/CachePolicy";
+import type { OutputCachePolicyFields } from "../types/CachePolicy";
+import { CacheValueError } from "../errors/CacheError";
+
+/** Validates client-cache directives and forces personalized responses private. */
+export function resolveOutputClientCacheOptions(
+  policy: Pick<OutputCachePolicyFields, "clientCache" | "varyByUser" | "varyByClaim">,
+): ClientCacheOptions | undefined {
+  if (policy.varyByClaim !== undefined && policy.varyByClaim.trim().length === 0) {
+    throw new CacheValueError("output cache varyByClaim must be a non-empty string");
+  }
+  const options = policy.clientCache;
+  if (options?.maxAge !== undefined && (!Number.isFinite(options.maxAge) || options.maxAge < 0)) {
+    throw new CacheValueError("output cache clientCache.maxAge must be a non-negative finite number");
+  }
+  if (options?.public === true && options.private === true) {
+    throw new CacheValueError("output cache clientCache cannot be both public and private");
+  }
+  const personalized = policy.varyByUser === true || policy.varyByClaim !== undefined;
+  if (!personalized) return options;
+  if (options?.public === true) {
+    throw new CacheValueError("personalized output cache cannot use clientCache.public");
+  }
+  return Object.freeze({ ...(options ?? {}), public: false, private: true });
+}
+
+/** Applies client/proxy Cache-Control headers (ASP.NET Response Cache layer). */
+export function applyClientCacheHeaders(
+  response: Response,
+  options: ClientCacheOptions | undefined,
+): Response {
+  if (options === undefined) {
+    return response;
+  }
+
+  const directives: string[] = [];
+  if (options.noCache === true) {
+    directives.push("no-cache");
+  }
+  if (options.public === true) {
+    directives.push("public");
+  }
+  if (options.private === true) {
+    directives.push("private");
+  }
+  if (options.maxAge !== undefined) {
+    directives.push(`max-age=${Math.max(0, Math.floor(options.maxAge))}`);
+  }
+
+  if (directives.length === 0) {
+    return response;
+  }
+
+  const headers = new Headers(response.headers);
+  headers.set("cache-control", directives.join(", "));
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  });
+}

package/core/cache/http/buildOutputCacheKey.ts

@@ -0,0 +1,154 @@
+import { PRINCIPAL_STATE_KEY, type HttpContext, type RequestPrincipal } from "../../http";
+import { createHash } from "node:crypto";
+import type { ResolvedOutputCacheOptions } from "../internal/resolveCachePolicy";
+
+/**
+ * The `ctx.state` key holding the request principal. Equal to the kernel's
+ * {@link PRINCIPAL_STATE_KEY}, so `varyByUser`/`unlessAuthenticated` see the same
+ * subject the authentication layer stores.
+ */
+export const OUTPUT_CACHE_PRINCIPAL_STATE_KEY = PRINCIPAL_STATE_KEY;
+
+function appendQueryParts(
+  parts: CacheKeyPart[],
+  url: URL,
+  keys: readonly string[] | "*",
+): void {
+  if (keys === "*") {
+    const names = [...new Set(url.searchParams.keys())].sort((left, right) => left.localeCompare(right));
+    for (const name of names) {
+      parts.push(["query", name, url.searchParams.getAll(name)]);
+    }
+    return;
+  }
+  for (const name of keys) {
+    const values = url.searchParams.getAll(name);
+    if (values.length > 0) {
+      parts.push(["query", name, values]);
+    }
+  }
+}
+
+function appendRouteParts(
+  parts: CacheKeyPart[],
+  params: HttpContext["params"],
+  keys: readonly string[],
+): void {
+  for (const name of keys) {
+    const value = params[name];
+    if (value !== undefined) {
+      parts.push(["route", name, value]);
+    }
+  }
+}
+
+function appendHeaderParts(
+  parts: CacheKeyPart[],
+  ctx: HttpContext,
+  keys: readonly string[],
+): void {
+  for (const name of keys) {
+    const value = ctx.header(name);
+    if (value !== undefined) {
+      parts.push(["header", name.toLowerCase(), value]);
+    }
+  }
+}
+
+function appendUserPart(parts: CacheKeyPart[], ctx: HttpContext, varyByUser: boolean, varyByClaim?: string): void {
+  const principal = ctx.state.get(OUTPUT_CACHE_PRINCIPAL_STATE_KEY) as RequestPrincipal | undefined;
+  if (varyByUser) {
+    parts.push(["user", principal === undefined ? "anonymous" : "authenticated", principal?.subject ?? ""]);
+  }
+  if (varyByClaim !== undefined) {
+    parts.push([
+      "claim",
+      varyByClaim,
+      principal === undefined ? "anonymous" : "authenticated",
+      principal?.findFirst?.(varyByClaim) ?? "",
+    ]);
+  }
+}
+
+/** Authenticated requests need every configured identity component to exist. */
+export function canBuildPersonalizedOutputCacheKey(
+  ctx: HttpContext,
+  options: {
+    readonly varyByUser?: boolean;
+    readonly varyByClaim?: string;
+    readonly allowAuthenticatedShared?: boolean;
+  },
+): boolean {
+  if (options.varyByClaim !== undefined && options.varyByClaim.trim().length === 0) {
+    return false;
+  }
+  const principal = ctx.state.get(OUTPUT_CACHE_PRINCIPAL_STATE_KEY) as RequestPrincipal | undefined;
+  if (principal === undefined) return true;
+  if (
+    options.varyByUser !== true
+    && options.varyByClaim === undefined
+    && options.allowAuthenticatedShared !== true
+  ) {
+    return false;
+  }
+  if (
+    options.varyByUser === true
+    && (typeof principal.subject !== "string" || principal.subject.trim().length === 0)
+  ) {
+    return false;
+  }
+  if (options.varyByClaim !== undefined) {
+    const claim = principal.findFirst?.(options.varyByClaim);
+    if (typeof claim !== "string" || claim.trim().length === 0) {
+      return false;
+    }
+  }
+  return true;
+}
+
+type CacheKeyPart = readonly [kind: string, ...values: readonly (string | number | boolean | readonly string[])[]];
+
+/**
+ * Cache keys can contain credentials, subject identifiers and arbitrary query
+ * values. Keep those values out of memory listings/Redis keyspace and use a
+ * collision-resistant digest over an unambiguous JSON tuple representation.
+ */
+function digestKey(parts: readonly CacheKeyPart[]): string {
+  return `http:${createHash("sha256").update(JSON.stringify(parts)).digest("hex")}`;
+}
+
+/** Builds a deterministic output-cache key for the request. */
+export function buildOutputCacheKey(
+  ctx: HttpContext,
+  routeName: string,
+  options: ResolvedOutputCacheOptions,
+): string {
+  // Runtime class names are not globally unique (dynamic modules can contain
+  // two same-named controllers). The concrete path is an independent route
+  // identity component and also prevents accidental sharing across route-param
+  // values when varyByRoute was omitted.
+  const parts: CacheKeyPart[] = [
+    ["action", ctx.method.toUpperCase(), routeName],
+    ["origin", ctx.url.origin],
+    ["path", ctx.url.pathname],
+  ];
+
+  // Query is part of the safe default identity. `[]` is the explicit opt-out
+  // for an endpoint whose representation is proven query-independent.
+  appendQueryParts(parts, ctx.url, options.varyByQuery ?? "*");
+  if (options.varyByRoute !== undefined) {
+    appendRouteParts(parts, ctx.params, options.varyByRoute);
+  }
+  if (options.varyByHeader !== undefined) {
+    appendHeaderParts(parts, ctx, options.varyByHeader);
+  }
+  if (options.varyByUser === true || options.varyByClaim !== undefined) {
+    appendUserPart(parts, ctx, options.varyByUser === true, options.varyByClaim);
+  }
+
+  if (ctx.apiVersion !== undefined) {
+    parts.push(["version", ctx.apiVersion]);
+  }
+
+  return digestKey(parts);
+}

package/core/cache/http/buildRedisOutputCacheKey.ts

@@ -0,0 +1,16 @@
+import type { HttpContext } from "../../http";
+import { buildOutputCacheKey } from "./buildOutputCacheKey";
+import type { ResolvedOutputRedisCacheOptions } from "../types/OutputRedisCacheOptions";
+
+/** Builds Redis storage key (connection prefix applied separately in {@link RedisOutputCache}). */
+export function buildRedisOutputCacheKey(
+  ctx: HttpContext,
+  routeName: string,
+  options: ResolvedOutputRedisCacheOptions,
+): string {
+  const base = buildOutputCacheKey(ctx, routeName, options);
+  if (options.keyPrefix === undefined || options.keyPrefix.length === 0) {
+    return base;
+  }
+  return `${options.keyPrefix}${base}`;
+}

package/core/cache/http/composeOutputCache.ts

@@ -0,0 +1,130 @@
+import type { Class, InjectionToken } from "../../di";
+import type { RouteMiddlewareComposer } from "../../http";
+import type { ActionMeta, ControllerMeta } from "../../http/Decorators/metadata";
+import type { ICache } from "../ICache";
+import {
+  outputCacheMetaOf,
+  resolveOutputCacheRequirement,
+} from "../decorators/outputCacheMetadata";
+import {
+  outputRedisCacheMetaOf,
+  resolveOutputRedisCacheRequirement,
+} from "../decorators/outputRedisCacheMetadata";
+import {
+  requireCacheSeconds,
+  resolveCacheOptions,
+  type ResolvedOutputCacheOptions,
+} from "../internal/resolveCachePolicy";
+import { resolveOutputRedisCacheOptions } from "../internal/resolveOutputRedisCachePolicy";
+import type { CachePolicyRegistry } from "../types/CachePolicy";
+import type { ResolvedOutputRedisCacheOptions } from "../types/OutputRedisCacheOptions";
+import type { CachedHttpPayload } from "./CachedHttpPayload";
+import { outputCacheMiddleware } from "./outputCacheMiddleware";
+import { outputRedisCacheMiddleware } from "./outputRedisCacheMiddleware";
+import {
+  guardInsecureOutputCacheRoute,
+  type OutputCacheSecurityWarningOptions,
+} from "./outputCacheSecurityWarning";
+
+/** Composes per-route output cache middleware from `@OutputCache` / `@OutputRedisCache`. */
+export type RouteOutputCacheComposer = RouteMiddlewareComposer;
+
+export interface CreateRouteOutputCacheComposerOptions {
+  readonly policies: CachePolicyRegistry;
+  readonly globalEnabled: boolean;
+  readonly cacheToken: InjectionToken<ICache<CachedHttpPayload>>;
+  readonly securityWarnings?: OutputCacheSecurityWarningOptions;
+  /** Whether a distributed cache backend is configured (enables `@OutputRedisCache`). */
+  readonly distributedEnabled?: boolean;
+}
+
+export function createRouteOutputCacheComposer(
+  policies: CachePolicyRegistry,
+  globalEnabled: boolean,
+  cacheToken: InjectionToken<ICache<CachedHttpPayload>>,
+  securityWarnings?: OutputCacheSecurityWarningOptions,
+  distributedEnabled = false,
+): RouteOutputCacheComposer {
+  return createRouteOutputCacheComposerWithOptions({
+    policies,
+    globalEnabled,
+    cacheToken,
+    securityWarnings,
+    distributedEnabled,
+  });
+}
+
+export function createRouteOutputCacheComposerWithOptions(
+  options: CreateRouteOutputCacheComposerOptions,
+): RouteOutputCacheComposer {
+  const { policies, globalEnabled, cacheToken, securityWarnings, distributedEnabled = false } = options;
+
+  return (controllerClass: Class<object>, methodName: string | symbol, _httpMeta: ControllerMeta, _action: ActionMeta) => {
+    if (!globalEnabled) {
+      return [];
+    }
+
+    const middlewares = [];
+
+    const redisMeta = outputRedisCacheMetaOf(controllerClass);
+    const redisRequirement = resolveOutputRedisCacheRequirement(redisMeta, methodName);
+    const memoryMeta = outputCacheMetaOf(controllerClass);
+    const memoryRequirement = resolveOutputCacheRequirement(memoryMeta, methodName);
+
+    if (redisRequirement !== undefined && memoryRequirement !== undefined) {
+      console.warn(
+        `[cache] ${controllerClass.name}.${String(methodName)} has both @OutputCache and @OutputRedisCache — `
+          + "using @OutputRedisCache only.",
+      );
+    }
+
+    if (redisRequirement !== undefined) {
+      if (!distributedEnabled) {
+        throw new Error(
+          `@OutputRedisCache on ${controllerClass.name}.${String(methodName)} requires a distributed backend (add redisConnect(redisConfig, { cache: "distributed" }) to your @Infra manifest)`,
+        );
+      }
+
+      const resolved = resolveOutputRedisCacheOptions(redisRequirement, policies);
+      if (resolved.enabled !== false && resolved.noStore !== true) {
+        const seconds = requireCacheSeconds(
+          resolved,
+          `@OutputRedisCache on ${controllerClass.name}.${String(methodName)}`,
+        );
+        const config: ResolvedOutputRedisCacheOptions = { ...resolved, seconds };
+        guardInsecureOutputCacheRoute(controllerClass, methodName, config, securityWarnings);
+        middlewares.push(
+          outputRedisCacheMiddleware({
+            routeName: `${controllerClass.name}.${String(methodName)}`,
+            config,
+          }),
+        );
+      }
+      return middlewares;
+    }
+
+    if (memoryRequirement === undefined) {
+      return [];
+    }
+
+    const resolved = resolveCacheOptions(memoryRequirement, policies);
+    if (resolved.enabled === false || resolved.noStore === true) {
+      return [];
+    }
+
+    const seconds = requireCacheSeconds(resolved, `@OutputCache on ${controllerClass.name}.${String(methodName)}`);
+    const config: ResolvedOutputCacheOptions = { ...resolved, seconds };
+
+    guardInsecureOutputCacheRoute(controllerClass, methodName, config, securityWarnings);
+
+    middlewares.push(
+      outputCacheMiddleware({
+        cacheToken,
+        routeName: `${controllerClass.name}.${String(methodName)}`,
+        config,
+      }),
+    );
+
+    return middlewares;
+  };
+}

package/core/cache/http/outputCacheMiddleware.ts

@@ -0,0 +1,111 @@
+import type { HttpMiddleware } from "../../http";
+import type { InjectionToken } from "../../di";
+import { ICache } from "../ICache";
+import {
+  DEFAULT_OUTPUT_CACHE_METHODS,
+  DEFAULT_OUTPUT_CACHE_STATUS_CODES,
+  type ResolvedOutputCacheOptions,
+} from "../internal/resolveCachePolicy";
+import { canBuildPersonalizedOutputCacheKey, OUTPUT_CACHE_PRINCIPAL_STATE_KEY } from "./buildOutputCacheKey";
+import { buildOutputCacheKey } from "./buildOutputCacheKey";
+import { applyClientCacheHeaders, resolveOutputClientCacheOptions } from "./applyClientCacheHeaders";
+import {
+  cachedPayloadToResponse,
+  resolveCachedHttpPayloadReadOptions,
+  responseAllowsServerCache,
+  responseToCachedPayload,
+  type CachedHttpPayload,
+} from "./CachedHttpPayload";
+
+export interface OutputCacheMiddlewareOptions {
+  readonly cacheToken?: InjectionToken<ICache<CachedHttpPayload>>;
+  readonly routeName: string;
+  readonly config: ResolvedOutputCacheOptions;
+}
+
+function isAuthenticated(ctx: Parameters<HttpMiddleware>[0]): boolean {
+  return ctx.state.get(OUTPUT_CACHE_PRINCIPAL_STATE_KEY) !== undefined;
+}
+
+function allowsMethod(method: string, allowed: readonly string[] | undefined): boolean {
+  const methods = allowed ?? DEFAULT_OUTPUT_CACHE_METHODS;
+  return methods.includes(method.toUpperCase());
+}
+
+function allowsStatus(status: number, allowed: readonly number[] | undefined): boolean {
+  const codes = allowed ?? DEFAULT_OUTPUT_CACHE_STATUS_CODES;
+  return codes.includes(status);
+}
+
+/** Per-route output cache middleware compiled from `@OutputCache` metadata. */
+export function outputCacheMiddleware(options: OutputCacheMiddlewareOptions): HttpMiddleware {
+  const { routeName, config } = options;
+  const cacheToken = options.cacheToken ?? (ICache as InjectionToken<ICache<CachedHttpPayload>>);
+  const payloadReadOptions = resolveCachedHttpPayloadReadOptions(config);
+  const clientCache = resolveOutputClientCacheOptions(config);
+
+  return async (ctx, next) => {
+    const cache = ctx.services.resolve(cacheToken);
+    if (config.enabled === false || config.noStore === true) {
+      await next();
+      return;
+    }
+
+    if (!allowsMethod(ctx.method, config.methods)) {
+      await next();
+      return;
+    }
+
+    if (config.unlessAuthenticated === true && isAuthenticated(ctx)) {
+      await next();
+      // Never add a public/shared-cache directive to a personalized response.
+      // The action may still provide its own deliberate Cache-Control policy.
+      return;
+    }
+
+    if (!canBuildPersonalizedOutputCacheKey(ctx, config)) {
+      await next();
+      return;
+    }
+
+    if (config.when !== undefined) {
+      const allowed = await config.when(ctx);
+      if (!allowed) {
+        await next();
+        return;
+      }
+    }
+
+    const key = buildOutputCacheKey(ctx, routeName, config);
+    const cached = cache.get(key);
+    if (cached !== undefined) {
+      ctx.response = applyClientCacheHeaders(cachedPayloadToResponse(cached), clientCache);
+      return;
+    }
+
+    const setOptions = { ttlSeconds: config.seconds, tags: config.tags };
+    const payload = await cache.getOrCreateAsync(key, async () => {
+      await next();
+      if (
+        ctx.response === undefined
+        || !allowsStatus(ctx.response.status, config.statusCodes)
+        || !responseAllowsServerCache(ctx.response, config.varyByHeader)
+      ) {
+        return undefined;
+      }
+      return responseToCachedPayload(ctx.response, payloadReadOptions);
+    }, setOptions);
+
+    if (payload !== undefined) {
+      ctx.response = applyClientCacheHeaders(cachedPayloadToResponse(payload), clientCache);
+      return;
+    }
+
+    // Anti-stampede may have merged our request with another one whose response turned out
+    // uncacheable: then the factory ran on the other context and our `ctx.response`
+    // is empty, so run the pipeline ourselves to return a complete response.
+    if (ctx.response === undefined) {
+      await next();
+    }
+  };
+}