bazis 0.96.1

package/core/cache/http/outputCacheSecurityWarning.ts

@@ -0,0 +1,58 @@
+import type { Class } from "../../di";
+import { resolveAuthorizeMeta } from "../../http";
+import type { ResolvedOutputCacheOptions } from "../internal/resolveCachePolicy";
+
+export interface OutputCacheSecurityWarningOptions {
+  readonly enabled?: boolean;
+  /** Default: throw. Use "warn" for compatibility, "ignore" only with an external policy. */
+  readonly behavior?: "throw" | "warn" | "ignore";
+  /** Match `jwt({ options: { requireAuthenticationByDefault } })`. Default false. */
+  readonly requireAuthenticationByDefault?: boolean;
+  readonly warn?: (message: string) => void;
+}
+
+/**
+ * Guards against `@OutputCache` on a protected route without user isolation.
+ * Called once per route at HTTP startup (composer time).
+ */
+export function guardInsecureOutputCacheRoute(
+  controllerClass: Class<object>,
+  methodName: string | symbol,
+  config: ResolvedOutputCacheOptions,
+  options: OutputCacheSecurityWarningOptions = {},
+): void {
+  if (options.enabled === false) {
+    return;
+  }
+  const behavior = options.behavior ?? "throw";
+  if (behavior === "ignore") {
+    return;
+  }
+
+  if (
+    config.varyByUser === true
+    || config.varyByClaim !== undefined
+    || config.unlessAuthenticated === true
+    || config.noStore === true
+  ) {
+    return;
+  }
+
+  const authorize = resolveAuthorizeMeta(controllerClass, methodName);
+  const protectedRoute =
+    !authorize.allowAnonymous
+    && (authorize.authorize !== undefined || options.requireAuthenticationByDefault === true);
+  if (!protectedRoute) {
+    return;
+  }
+
+  const route = `${controllerClass.name}.${String(methodName)}`;
+  const message =
+    `[cache] @OutputCache on ${route} is on an authorized route without varyByUser or unlessAuthenticated — `
+    + "responses may leak between users. Add varyByUser: true or unlessAuthenticated: true.";
+
+  if (behavior === "throw") {
+    throw new Error(message);
+  }
+  (options.warn ?? console.warn)(message);
+}

package/core/cache/http/outputRedisCacheMiddleware.ts

@@ -0,0 +1,118 @@
+import type { HttpMiddleware } from "../../http";
+import { CacheError } from "../errors/CacheError";
+import { DISTRIBUTED_OUTPUT_CACHE } from "../tokens/DISTRIBUTED_CACHE";
+import {
+  DEFAULT_OUTPUT_CACHE_METHODS,
+  DEFAULT_OUTPUT_CACHE_STATUS_CODES,
+} from "../internal/resolveCachePolicy";
+import type { ResolvedOutputRedisCacheOptions } from "../types/OutputRedisCacheOptions";
+import { canBuildPersonalizedOutputCacheKey, OUTPUT_CACHE_PRINCIPAL_STATE_KEY } from "./buildOutputCacheKey";
+import { buildRedisOutputCacheKey } from "./buildRedisOutputCacheKey";
+import { applyClientCacheHeaders, resolveOutputClientCacheOptions } from "./applyClientCacheHeaders";
+import {
+  cachedPayloadToResponse,
+  resolveCachedHttpPayloadReadOptions,
+  responseAllowsServerCache,
+  responseToCachedPayload,
+} from "./CachedHttpPayload";
+
+export interface OutputRedisCacheMiddlewareOptions {
+  readonly routeName: string;
+  readonly config: ResolvedOutputRedisCacheOptions;
+}
+
+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 Redis output cache middleware compiled from `@OutputRedisCache` metadata. */
+export function outputRedisCacheMiddleware(options: OutputRedisCacheMiddlewareOptions): HttpMiddleware {
+  const { routeName, config } = options;
+  const payloadReadOptions = resolveCachedHttpPayloadReadOptions(config);
+  const clientCache = resolveOutputClientCacheOptions(config);
+
+  return async (ctx, next) => {
+    const registry = ctx.services.tryResolve(DISTRIBUTED_OUTPUT_CACHE);
+    if (registry === undefined) {
+      throw new CacheError(
+        `@OutputRedisCache on ${routeName} requires a distributed cache backend — `
+          + 'add redisConnect(redisConfig, { cache: "distributed" }) to your @Infra manifest',
+      );
+    }
+    const cache = registry.resolve(config.connection);
+
+    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();
+      // Do not mark personalized bypass responses as public cacheable.
+      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 = buildRedisOutputCacheKey(ctx, routeName, config);
+    const cached = await cache.get(key);
+    if (cached !== undefined) {
+      ctx.response = applyClientCacheHeaders(cachedPayloadToResponse(cached), clientCache);
+      return;
+    }
+
+    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);
+      },
+      { ttlSeconds: config.seconds, tags: config.tags, lockSeconds: config.lockSeconds },
+    );
+
+    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();
+    }
+  };
+}

package/core/cache/index.ts

@@ -0,0 +1,97 @@
+/**
+ * Bazis cache: in-memory {@link ICache}, HTTP output cache, and service method
+ * cache. Use it as a self-installing value: `memory({ ... })`. For multi-instance
+ * caching add `redisConnect(redisConfig, { cache: "distributed" })` to your `@Infra` manifest — the
+ * distributed backend is then discovered from DI by `@CacheableRedis` / `@OutputRedisCache`.
+ */
+export { ICache, cacheToken } from "./ICache";
+export type { CacheFactory } from "./ICache";
+export type { CacheEntry } from "./types/CacheEntry";
+export {
+  CACHE_OPTIONS,
+  DEFAULT_MAX_KEY_LENGTH,
+  DEFAULT_MAX_IN_FLIGHT,
+  validateCacheOptions,
+  type CacheOptions,
+  type CacheSetOptions,
+} from "./types/CacheOptions";
+export type {
+  CachePolicy,
+  CachePolicyRegistry,
+  CacheableOptions,
+  CacheablePolicyFields,
+  ClientCacheOptions,
+  OutputCacheOptions,
+  OutputCachePolicyFields,
+} from "./types/CachePolicy";
+export type {
+  OutputRedisCacheOptions,
+  ResolvedOutputRedisCacheOptions,
+} from "./types/OutputRedisCacheOptions";
+export type {
+  CacheableRedisOptions,
+  ResolvedCacheableRedisOptions,
+} from "./types/CacheableRedisOptions";
+export { CACHE_POLICIES } from "./tokens/CACHE_POLICIES";
+export { MemoryCache } from "./MemoryCache";
+
+// Distributed cache abstraction (backends live in @/core/infra/*).
+export {
+  DEFAULT_CACHE_CONNECTION,
+  DistributedCache,
+  NamedCacheRegistry,
+  jsonCacheCodec,
+  httpPayloadCacheCodec,
+  type CacheCodec,
+  type DistributedCacheStores,
+  type DistributedCacheConfig,
+  type DistributedCacheDriver,
+  type DistributedCacheFencedWrite,
+  type DistributedCacheTagWrite,
+  type DistributedCacheVersionCheck,
+  type DistributedCachePing,
+  type DistributedCacheSetOptions,
+  type IDistributedCache,
+} from "./distributed";
+export {
+  DISTRIBUTED_CACHE_BACKEND,
+  DISTRIBUTED_OUTPUT_CACHE,
+  DISTRIBUTED_SERVICE_CACHE,
+} from "./tokens/DISTRIBUTED_CACHE";
+
+export { memory } from "./cacheModule";
+/** @internal Advanced builder used by the hosting layer. */
+export {
+  buildCacheModule,
+  type CacheModuleConfig,
+  type CacheOutputCacheOptions,
+} from "./internal/buildCacheProviders";
+export { CacheError, CacheKeyError, CacheValueError, CacheCapacityError } from "./errors/CacheError";
+
+export { OutputCache, type OutputCacheOptions as OutputCacheDecoratorOptions } from "./decorators/OutputCache";
+export {
+  OutputRedisCache,
+  type OutputRedisCacheOptions as OutputRedisCacheDecoratorOptions,
+} from "./decorators/OutputRedisCache";
+export { Cacheable, type CacheableOptions as CacheableDecoratorOptions } from "./decorators/Cacheable";
+export {
+  CacheableRedis,
+  type CacheableRedisOptions as CacheableRedisDecoratorOptions,
+} from "./decorators/CacheableRedis";
+
+export { createRouteOutputCacheComposer, type RouteOutputCacheComposer } from "./http/composeOutputCache";
+export {
+  guardInsecureOutputCacheRoute,
+  type OutputCacheSecurityWarningOptions,
+} from "./http/outputCacheSecurityWarning";
+export type { CachedHttpPayload } from "./http/CachedHttpPayload";
+export {
+  DEFAULT_OUTPUT_CACHE_METHODS,
+  DEFAULT_OUTPUT_CACHE_STATUS_CODES,
+} from "./internal/resolveCachePolicy";
+export { buildOutputCacheKey, OUTPUT_CACHE_PRINCIPAL_STATE_KEY } from "./http/buildOutputCacheKey";
+export { wrapCachedService, type CacheProxyOptions } from "./services/cacheProxy";
+export {
+  cachedSingleton,
+  cachedScoped,
+} from "./providers/cachedProviders";

package/core/cache/internal/AutomaticCacheKey.ts

@@ -0,0 +1,106 @@
+import { randomUUID } from "node:crypto";
+import { types } from "node:util";
+
+const mapEntries = Map.prototype.entries;
+const setValues = Set.prototype.values;
+const unsupported = Symbol("unsupported automatic cache argument");
+
+interface ValueNode {
+  value?: unknown;
+  identity?: string;
+}
+
+/** Value snapshots and collection-key identities belong to one service proxy. */
+export class AutomaticCacheKey {
+  private readonly identities = new WeakMap<object, string>();
+  private readonly namespace = randomUUID();
+  private nextIdentity = 0;
+
+  /** Unsupported input disables caching for this call; it never invokes application accessors. */
+  public build(args: readonly unknown[]): string | undefined {
+    const indices = new WeakMap<object, number>();
+    const active = new WeakSet<object>();
+    const nodes: ValueNode[] = [];
+    const encode = (value: unknown, identity = false): unknown => {
+      if (value === undefined) return ["undefined"];
+      if (value === null) return ["null"];
+      if (typeof value === "string") return ["string", value];
+      if (typeof value === "boolean") return ["boolean", value];
+      if (typeof value === "number") {
+        if (Number.isNaN(value)) return ["number", "NaN"];
+        if (value === Infinity) return ["number", "+Infinity"];
+        if (value === -Infinity) return ["number", "-Infinity"];
+        if (Object.is(value, -0)) return ["number", "-0"];
+        return ["number", value];
+      }
+      if (typeof value === "bigint") return ["bigint", value.toString()];
+      if (typeof value !== "object" || types.isProxy(value) || active.has(value)) throw unsupported;
+      let index = indices.get(value);
+      if (index === undefined) {
+        index = nodes.length;
+        indices.set(value, index);
+        nodes.push({});
+        active.add(value);
+        nodes[index]!.value = contents(value);
+        active.delete(value);
+      }
+      // The same object may have appeared in an earlier argument before its role
+      // as a Map key / Set member becomes known. Update its shared node in place.
+      if (identity) nodes[index]!.identity = this.identityOf(value);
+      return ["ref", index];
+    };
+    const contents = (value: object): unknown => {
+      const prototype = Object.getPrototypeOf(value);
+      if (prototype === Date.prototype || prototype === Map.prototype || prototype === Set.prototype) {
+        if (Reflect.ownKeys(value).length !== 0) throw unsupported;
+        if (prototype === Date.prototype) return ["date", Date.prototype.toISOString.call(value)];
+        if (prototype === Map.prototype) {
+          const entries: unknown[] = [];
+          for (const [key, entry] of mapEntries.call(value as Map<unknown, unknown>)) {
+            entries.push([encode(key, true), encode(entry)]);
+          }
+          return ["map", entries];
+        }
+        const entries: unknown[] = [];
+        for (const entry of setValues.call(value as Set<unknown>)) entries.push(encode(entry, true));
+        return ["set", entries];
+      }
+      const array = Array.isArray(value);
+      if (array ? prototype !== Array.prototype : prototype !== Object.prototype && prototype !== null) throw unsupported;
+      const descriptors = Object.getOwnPropertyDescriptors(value);
+      for (const key of Reflect.ownKeys(descriptors)) {
+        if (array && key === "length") continue;
+        const descriptor = descriptors[key as string]!;
+        if (typeof key !== "string" || !descriptor.enumerable || !("value" in descriptor)
+          || (array && (!/^(0|[1-9]\d*)$/.test(key) || Number(key) >= value.length))) throw unsupported;
+      }
+      if (array) {
+        const entries: unknown[] = [];
+        for (let index = 0; index < value.length; index++) {
+          const descriptor = descriptors[index];
+          entries.push(descriptor ? encode(descriptor.value) : ["hole"]);
+        }
+        return ["array", entries];
+      }
+      return ["object", prototype === null ? "null-prototype" : "Object",
+        Object.keys(descriptors).sort().map((key) => [key, encode(descriptors[key]!.value)])];
+    };
+    try {
+      return JSON.stringify([args.map((value) => encode(value)), nodes]);
+    } catch {
+      // Includes invalid Date/internal-slot impostors and traversal limits.
+      // Explicit key builders and the original method run outside this boundary.
+      return undefined;
+    }
+  }
+
+  private identityOf(value: object): string {
+    let identity = this.identities.get(value);
+    if (identity === undefined) {
+      if (!Number.isSafeInteger(++this.nextIdentity)) throw unsupported;
+      identity = `${this.namespace}:${this.nextIdentity}`;
+      this.identities.set(value, identity);
+    }
+    return identity;
+  }
+}

package/core/cache/internal/CacheKeyGuard.ts

@@ -0,0 +1,56 @@
+import { CacheKeyError } from "../errors/CacheError";
+import { DEFAULT_MAX_KEY_LENGTH } from "../types/CacheOptions";
+
+const FORBIDDEN_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+
+const encoder = new TextEncoder();
+
+/** Validates a cache key: type, length, prototype pollution protection. */
+export function assertCacheKey(key: unknown, maxKeyLength = DEFAULT_MAX_KEY_LENGTH): asserts key is string {
+  if (typeof key !== "string") {
+    throw new CacheKeyError("Cache key must be a string");
+  }
+  if (key.length === 0) {
+    throw new CacheKeyError("Cache key must not be empty");
+  }
+  if (key.length > maxKeyLength) {
+    throw new CacheKeyError(`Cache key exceeds max length of ${maxKeyLength}`);
+  }
+  if (FORBIDDEN_KEYS.has(key)) {
+    throw new CacheKeyError(`Cache key '${key}' is not allowed`);
+  }
+}
+
+/** Estimates the size of a string value in UTF-8 bytes. */
+export function measureStringBytes(value: string): number {
+  return encoder.encode(value).byteLength;
+}
+
+/**
+ * Best-effort value size in bytes for the `maxValueBytes` limit.
+ * Covers strings, binary buffers and HTTP payloads (via `body: Uint8Array`).
+ * Returns `undefined` when the size cannot be measured; the limit is not applied then.
+ */
+export function measureValueBytes(value: unknown): number | undefined {
+  if (typeof value === "string") {
+    return encoder.encode(value).byteLength;
+  }
+  if (value instanceof Uint8Array || ArrayBuffer.isView(value)) {
+    return value.byteLength;
+  }
+  if (value instanceof ArrayBuffer) {
+    return value.byteLength;
+  }
+  if (value !== null && typeof value === "object") {
+    const body = (value as { body?: unknown }).body;
+    if (body instanceof Uint8Array) {
+      return body.byteLength;
+    }
+    try {
+      return encoder.encode(JSON.stringify(value)).byteLength;
+    } catch {
+      return undefined;
+    }
+  }
+  return undefined;
+}

package/core/cache/internal/buildCacheProviders.ts

@@ -0,0 +1,146 @@
+import {
+  DI,
+  CLASS_PROVIDER_HOOK,
+  OptionsValidationError,
+  singleton,
+  singletonValue,
+  type InjectionToken,
+  type Options,
+  type BazisModuleRef,
+  type ProviderDefinition,
+} from "../../di";
+import { ROUTE_MIDDLEWARE_COMPOSER, type RouteMiddlewareComposerRegistration } from "../../http";
+import { HEALTH_CHECK } from "../../kernel";
+import { cacheableClassProviderHook } from "../di/classProviderHook";
+import { createRouteOutputCacheComposerWithOptions } from "../http/composeOutputCache";
+import type { CachedHttpPayload } from "../http/CachedHttpPayload";
+import { ICache } from "../ICache";
+import { MemoryCache } from "../MemoryCache";
+import { CACHE_POLICIES } from "../tokens/CACHE_POLICIES";
+import { CACHE_OPTIONS, validateCacheOptions, type CacheOptions } from "../types/CacheOptions";
+import type { CachePolicyRegistry } from "../types/CachePolicy";
+
+// =============================================================================
+// The cache "engine room". Nothing here is part of the simple public surface —
+// `memory()` (./cacheModule) and `redisConnect()` (@/core/infra) are. Advanced
+// wiring (policies, output cache, health) lives below so the
+// public module stays flat and unintimidating.
+// =============================================================================
+
+/** HTTP output-cache tuning (advanced). */
+export interface CacheOutputCacheOptions {
+  /** Global HTTP output cache switch (default true). */
+  readonly enabled?: boolean;
+  /**
+   * Protected route policy when output cache lacks `varyByUser`/`unlessAuthenticated`.
+   * Default: "throw". Use "warn" only for compatibility during migration.
+   */
+  readonly insecureAuthorizedRouteBehavior?: "throw" | "warn" | "ignore";
+  /** Match `jwt({ options: { requireAuthenticationByDefault } })` for security warnings. */
+  readonly requireAuthenticationByDefault?: boolean;
+}
+
+/**
+ * Full cache configuration (advanced). Application code uses the simple values
+ * `memory(CacheOptions)`; the hosting layer uses this richer shape to add policies
+ * and output-cache tuning. Infra registers distributed stores separately in DI.
+ */
+export interface CacheModuleConfig extends CacheOptions {
+  /** Named policies shared by `@OutputCache` / `@Cacheable`. */
+  readonly policies?: CachePolicyRegistry;
+  readonly outputCache?: CacheOutputCacheOptions;
+  /** DI token for the cache store; default {@link ICache}. */
+  readonly token?: typeof ICache;
+  readonly imports?: readonly BazisModuleRef[];
+  /** Register health-check (default true). */
+  readonly healthCheck?: boolean;
+}
+
+/** Output-cache route middleware runs after auth (order 0) so `@Authorize` is honored first. */
+const OUTPUT_CACHE_COMPOSER_ORDER = 100;
+
+/** Builds the global cache module from an advanced {@link CacheModuleConfig}. */
+export function buildCacheModule(config: CacheModuleConfig = {}): BazisModuleRef {
+  const token = config.token ?? ICache;
+
+  return {
+    global: true,
+    imports: config.imports,
+    providers: buildCacheProviders(config),
+    exports: [token, CACHE_OPTIONS, CACHE_POLICIES],
+  };
+}
+
+/** Turns a {@link CacheModuleConfig} into the DI providers. */
+function buildCacheProviders(config: CacheModuleConfig): ProviderDefinition[] {
+  const token = config.token ?? ICache;
+  const policies = config.policies ?? {};
+
+  const providers: ProviderDefinition[] = [
+    singletonValue(CLASS_PROVIDER_HOOK, cacheableClassProviderHook),
+    cacheOptionsProvider(config),
+    DI.singleton(DI.valueProvider(CACHE_POLICIES, policies)),
+    singleton(token, MemoryCache, [CACHE_OPTIONS] as const),
+    outputCacheComposerProvider(config),
+  ];
+
+  if (config.healthCheck !== false) {
+    providers.push(healthProvider(token));
+  }
+  return providers;
+}
+
+/** Validated in-memory cache options (fail-fast at startup). */
+function cacheOptionsProvider(config: CacheModuleConfig): ProviderDefinition {
+  const value: CacheOptions = {
+    maxEntries: config.maxEntries,
+    maxInFlight: config.maxInFlight,
+    defaultTtlSeconds: config.defaultTtlSeconds,
+    maxKeyLength: config.maxKeyLength,
+    maxValueBytes: config.maxValueBytes,
+  };
+  return DI.singleton(
+    DI.factoryProvider(CACHE_OPTIONS, [], (): Options<CacheOptions> => {
+      const issues = validateCacheOptions(value);
+      if (issues.length > 0) {
+        throw new OptionsValidationError(issues.map((issue) => `IOptions<Cache>: ${issue}`));
+      }
+      return { value };
+    }),
+  );
+}
+
+/** Registers the `@OutputCache` / `@OutputRedisCache` middleware via the HTTP DI token. */
+function outputCacheComposerProvider(config: CacheModuleConfig): ProviderDefinition {
+  const token = config.token ?? ICache;
+  const compose = createRouteOutputCacheComposerWithOptions({
+    policies: config.policies ?? {},
+    globalEnabled: config.outputCache?.enabled !== false,
+    cacheToken: token as InjectionToken<ICache<CachedHttpPayload>>,
+    securityWarnings: {
+      behavior: outputCacheSecurityBehavior(config.outputCache),
+      requireAuthenticationByDefault: config.outputCache?.requireAuthenticationByDefault,
+    },
+    // Registries for `@OutputRedisCache` are published by Infra through DI.
+    // Without a registry the middleware reports an error on the first request.
+    distributedEnabled: true,
+  });
+  return singletonValue(ROUTE_MIDDLEWARE_COMPOSER, {
+    order: OUTPUT_CACHE_COMPOSER_ORDER,
+    compose,
+  } satisfies RouteMiddlewareComposerRegistration);
+}
+
+function outputCacheSecurityBehavior(options: CacheOutputCacheOptions | undefined): "throw" | "warn" | "ignore" {
+  return options?.insecureAuthorizedRouteBehavior ?? "throw";
+}
+
+/** Memory health belongs to Cache; connection health belongs to Infra. */
+function healthProvider(token: typeof ICache): ProviderDefinition {
+  return DI.singleton(
+    DI.factoryProvider(HEALTH_CHECK, [token], (cache: ICache) => ({
+      name: "cache:memory",
+      check: () => ({ healthy: true, details: `entries=${cache.size}` }),
+    })),
+  );
+}

package/core/cache/internal/normalizeCacheKey.ts

@@ -0,0 +1,9 @@
+import { DEFAULT_MAX_KEY_LENGTH } from "../types/CacheOptions";
+
+/** Shortens keys that exceed {@link DEFAULT_MAX_KEY_LENGTH} via stable hash. */
+export function normalizeCacheKey(key: string, maxLength = DEFAULT_MAX_KEY_LENGTH): string {
+  if (key.length <= maxLength) {
+    return key;
+  }
+  return `h:${Bun.hash(key).toString(16)}`;
+}

package/core/cache/internal/resolveCachePolicy.ts

@@ -0,0 +1,32 @@
+import { CacheError } from "../errors/CacheError";
+import type { CachePolicy, CacheableOptions, OutputCacheOptions } from "../types/CachePolicy";
+
+/** Merges named policy with inline decorator options (inline wins). */
+export function resolveCacheOptions<T extends OutputCacheOptions | CacheableOptions>(
+  inline: T,
+  policies: Readonly<Record<string, CachePolicy>>,
+): T & CachePolicy {
+  const policyName = inline.policy;
+  const base = policyName !== undefined ? policies[policyName] ?? {} : {};
+  return { ...base, ...inline };
+}
+
+/** Resolved output cache requirement attached to a controller action. */
+export type ResolvedOutputCacheOptions = OutputCacheOptions & CachePolicy & {
+  readonly seconds: number;
+};
+
+/** Resolved cacheable requirement attached to a service method. */
+export type ResolvedCacheableOptions = CacheableOptions & CachePolicy & {
+  readonly seconds: number;
+};
+
+export function requireCacheSeconds(options: CachePolicy, context: string): number {
+  if (options.seconds === undefined || !Number.isFinite(options.seconds) || options.seconds <= 0) {
+    throw new CacheError(`${context}: "seconds" (or policy with seconds) is required`);
+  }
+  return options.seconds;
+}
+
+export const DEFAULT_OUTPUT_CACHE_METHODS = ["GET", "HEAD"] as const;
+export const DEFAULT_OUTPUT_CACHE_STATUS_CODES = [200] as const;

package/core/cache/internal/resolveCacheableRedisPolicy.ts

@@ -0,0 +1,17 @@
+import { DEFAULT_CACHE_CONNECTION } from "../distributed/IDistributedCache";
+import type { CachePolicyRegistry } from "../types/CachePolicy";
+import type { CacheableRedisOptions } from "../types/CacheableRedisOptions";
+import { resolveCacheOptions } from "./resolveCachePolicy";
+
+/**
+ * Merges inline `@CacheableRedis` options with the named policy and fills in the
+ * default `connection`. `seconds` is NOT required here: the caller validates it
+ * after checking `enabled`/`noStore`, so a disabled cache without a TTL does not fail.
+ */
+export function resolveCacheableRedisOptions(
+  inline: CacheableRedisOptions,
+  policies: CachePolicyRegistry,
+): CacheableRedisOptions & { readonly connection: string } {
+  const resolved = resolveCacheOptions(inline, policies) as CacheableRedisOptions;
+  return { ...resolved, connection: resolved.connection ?? DEFAULT_CACHE_CONNECTION };
+}

package/core/cache/internal/resolveOutputRedisCachePolicy.ts

@@ -0,0 +1,17 @@
+import { DEFAULT_CACHE_CONNECTION } from "../distributed/IDistributedCache";
+import type { CachePolicyRegistry } from "../types/CachePolicy";
+import type { OutputRedisCacheOptions } from "../types/OutputRedisCacheOptions";
+import { resolveCacheOptions } from "./resolveCachePolicy";
+
+/**
+ * Merges inline `@OutputRedisCache` options with the named policy and fills in the
+ * default `connection`. The caller validates `seconds` after checking
+ * `enabled`/`noStore` (a disabled cache without a TTL must not fail at startup).
+ */
+export function resolveOutputRedisCacheOptions(
+  inline: OutputRedisCacheOptions,
+  policies: CachePolicyRegistry,
+): OutputRedisCacheOptions & { readonly connection: string } {
+  const resolved = resolveCacheOptions(inline, policies) as OutputRedisCacheOptions;
+  return { ...resolved, connection: resolved.connection ?? DEFAULT_CACHE_CONNECTION };
+}