133 lines
4.5 KiB
TypeScript
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");
|
|
}
|