Refresh HiveGrid Cloud reference snapshot

This commit is contained in:
david committed 2026-08-03 15:31:14 +02:00
1 parent 5e99e14772
commit 7f88026f79
5955 files changed
+1177325 -188362

No files matched your search

@@ -1,29 +1,35 @@
/**
* Eval-cache for the feature-flags engine.
* Generation-aware evaluation cache for the feature-flags engine.
*
* Wraps the shared-store two-tier cache (#39) with a key-shape and
* invalidation surface specific to flag evaluation. Cache-key is
* `<flagName>:<hash(ctx)>` so different evaluation contexts (tenant,
* user, plan) get distinct entries.
*
* Invalidation: when a flag mutates (admin save) the API calls
* `invalidateFlag(flagName)`. The two-tier cache publishes on the
* pub/sub channel — every replica drops its L1 entries for the flag.
*
* Note: the two-tier cache deletes ONE key per invalidate-call. Because
* a single flag can have many context-hashed entries we publish a
* wildcard `<flagName>:*` token and listen for it on the subscriber.
* Receiving replicas wipe their L1 entirely (cheap — L1 is a small Map),
* which is correct because flag mutations are rare (~ minutes).
* 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 { TwoTierCache } from "@hivegrid/shared-store";
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 = [
@@ -36,46 +42,91 @@ export function hashContext(ctx: EvaluationContext): string {
return createHash("sha1").update(parts.join("|")).digest("hex").slice(0, 16);
}
export function buildCacheKey(flagName: string, ctx: EvaluationContext): string {
return `ff:${flagName}:${hashContext(ctx)}`;
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>;
/**
* Drop every cached evaluation for `flagName` across replicas.
* Publishes a wildcard token on the invalidation channel.
*/
/** Increment this flag's durable generation, then notify replicas. */
invalidateFlag(flagName: string): Promise<void>;
/** Drop everything (e.g. admin "rebuild cache" button). */
/** Increment the durable global generation, then notify replicas. */
invalidateAll(): Promise<void>;
/** Apply a pub/sub notification received by this process. */
handleInvalidation(token: string): void;
}
/**
* Build a flag-eval cache on top of an existing TwoTierCache. The
* cache must be configured with `namespace: "feature-flags"` so its
* pub/sub channel matches what the publishers send.
*/
export function createFlagEvalCache(
store: TwoTierCache<EvaluateFlagResult>,
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 store.get(buildCacheKey(flagName, ctx));
return tier.get(buildCacheKey(flagName, ctx, await resolveGeneration(flagName)));
},
async set(flagName, ctx, result) {
await store.set(buildCacheKey(flagName, ctx), result);
const generation = await resolveGeneration(flagName);
await tier.set(buildCacheKey(flagName, ctx, generation), result);
},
async invalidateFlag(flagName) {
// The wildcard sentinel makes subscribers flush their L1 entirely,
// which is correct because we don't index L1 entries by flag-name
// prefix. Publish via the underlying two-tier cache's invalidate
// wildcard so peer L1s flush.
await store.invalidate(`ff-flag:${flagName}`);
const next = await backingStore.incr(flagGenerationKey(flagName));
handleInvalidation();
await tier.invalidate(`ff-gen:${encodeFlagName(flagName)}:${next}`);
},
async invalidateAll() {
await store.invalidate("*");
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");
}