Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/packages/feature-flags/src/cache.ts
T

133 lines
4.5 KiB
TypeScript

/**
* 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<EvaluateFlagResult | null>;
set(flagName: string, ctx: EvaluationContext, result: EvaluateFlagResult): Promise<void>;
/** Increment this flag's durable generation, then notify replicas. */
invalidateFlag(flagName: string): Promise<void>;
/** Increment the durable global generation, then notify replicas. */
invalidateAll(): Promise<void>;
/** Apply a pub/sub notification received by this process. */
handleInvalidation(token: string): void;
}
export function createFlagEvalCache(
tier: TwoTierCache<EvaluateFlagResult>,
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<string, CachedGeneration>();
const resolveGeneration = async (flagName: string): Promise<CacheGeneration> => {
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");
}