/** * Generation-aware evaluation cache for the feature-flags engine. * * L1/L2 values are immutable per generation. Mutations increment a durable * SharedStore generation before publishing, so a replica that misses pub/sub * cannot make an old L2 value current again. Pub/sub remains the fast path; * the short generation-cache TTL is the self-healing path. */ import type { SharedStore, TwoTierCache } from "@hivegrid/shared-store"; import { createHash } from "node:crypto"; import type { EvaluateFlagResult } from "./evaluate.js"; import type { EvaluationContext } from "./targeting/types.js"; export const FEATURE_FLAGS_INVALIDATION_CHANNEL = "feature-flags:invalidate"; interface CacheGeneration { global: number; flag: number; } interface CachedGeneration extends CacheGeneration { expiresAt: number; } export interface FlagEvalCacheOptions { /** Maximum staleness after a missed pub/sub event. Defaults to 1 second. */ generationTtlMs?: number; /** Deterministic clock seam. */ now?: () => number; } /** Stable hash over the subset of ctx fields that influence eval. */ export function hashContext(ctx: EvaluationContext): string { const parts = [ ctx.tenantId ?? "", ctx.userId ?? "", ctx.email ?? "", ctx.planTier ?? "", (ctx.roles ?? []).slice().sort().join(","), ]; return createHash("sha1").update(parts.join("|")).digest("hex").slice(0, 16); } export function buildCacheKey( flagName: string, ctx: EvaluationContext, generation: CacheGeneration = { global: 0, flag: 0 }, ): string { return `ff:${flagName}:g${generation.global}.${generation.flag}:${hashContext(ctx)}`; } export interface FlagEvalCache { get(flagName: string, ctx: EvaluationContext): Promise; set(flagName: string, ctx: EvaluationContext, result: EvaluateFlagResult): Promise; /** Increment this flag's durable generation, then notify replicas. */ invalidateFlag(flagName: string): Promise; /** Increment the durable global generation, then notify replicas. */ invalidateAll(): Promise; /** Apply a pub/sub notification received by this process. */ handleInvalidation(token: string): void; } export function createFlagEvalCache( tier: TwoTierCache, backingStore: SharedStore, options: FlagEvalCacheOptions = {}, ): FlagEvalCache { const generationTtlMs = options.generationTtlMs ?? 1_000; if (!Number.isFinite(generationTtlMs) || generationTtlMs < 0) { throw new Error("createFlagEvalCache: generationTtlMs must be >= 0"); } const clock = options.now ?? (() => Date.now()); const generations = new Map(); const resolveGeneration = async (flagName: string): Promise => { const cached = generations.get(flagName); const now = clock(); if (cached && cached.expiresAt > now) return cached; const [globalRaw, flagRaw] = await backingStore.mget([GLOBAL_GENERATION_KEY, flagGenerationKey(flagName)]); const generation = { global: parseGeneration(globalRaw), flag: parseGeneration(flagRaw), expiresAt: now + generationTtlMs, }; generations.set(flagName, generation); return generation; }; const handleInvalidation = (): void => { generations.clear(); tier.flushLocal(); }; return { async get(flagName, ctx) { return tier.get(buildCacheKey(flagName, ctx, await resolveGeneration(flagName))); }, async set(flagName, ctx, result) { const generation = await resolveGeneration(flagName); await tier.set(buildCacheKey(flagName, ctx, generation), result); }, async invalidateFlag(flagName) { const next = await backingStore.incr(flagGenerationKey(flagName)); handleInvalidation(); await tier.invalidate(`ff-gen:${encodeFlagName(flagName)}:${next}`); }, async invalidateAll() { const next = await backingStore.incr(GLOBAL_GENERATION_KEY); handleInvalidation(); await tier.invalidate(`ff-global:${next}`); }, handleInvalidation, }; } const GLOBAL_GENERATION_KEY = "cache:feature-flags:generation:global"; function flagGenerationKey(flagName: string): string { const digest = createHash("sha256").update(flagName).digest("hex"); return `cache:feature-flags:generation:flag:${digest}`; } function parseGeneration(raw: string | null): number { if (raw === null) return 0; const parsed = Number.parseInt(raw, 10); return Number.isSafeInteger(parsed) && parsed >= 0 ? parsed : 0; } function encodeFlagName(flagName: string): string { return Buffer.from(flagName, "utf8").toString("base64url"); }