Reorganize repo structure and standards references

This commit is contained in:
david committed 2026-06-29 05:03:42 +02:00
1 parent 3cb93a81be
commit be2054274d
5885 files changed
+2588 -195

No files matched your search

@@ -0,0 +1,81 @@
/**
* Eval-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).
*/
import type { TwoTierCache } from "@toolctrl/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";
/** 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): string {
return `ff:${flagName}:${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.
*/
invalidateFlag(flagName: string): Promise<void>;
/** Drop everything (e.g. admin "rebuild cache" button). */
invalidateAll(): Promise<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>,
): FlagEvalCache {
return {
async get(flagName, ctx) {
return store.get(buildCacheKey(flagName, ctx));
},
async set(flagName, ctx, result) {
await store.set(buildCacheKey(flagName, ctx), 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}`);
},
async invalidateAll() {
await store.invalidate("*");
},
};
}