Refresh HiveGrid Cloud reference snapshot
This commit is contained in:
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");
|
||||
}
|
||||
Reference in new issue
Block a user