@blamejs/core 0.7.107 → 0.8.0

package/lib/flag-cache.js

@@ -0,0 +1,136 @@
+"use strict";
+/**
+ * Flag-evaluation cache — per-targetingKey TTL'd cache wrapping a
+ * downstream provider so a high-traffic request path does not hit
+ * the provider on every flag read.
+ *
+ *   var raw = b.flag.providers.localFile({ path: "./flags.json", watch: true });
+ *   var cached = b.flag.cache(raw, { ttlMs: 60_000, maxEntries: 10000 });
+ *
+ *   var flag = b.flag.create({ provider: cached });
+ *
+ * Cache key: `${targetingKey}::${flagKey}`. Entries TTL out after
+ * `ttlMs` (default 30 s). When the cache hits its `maxEntries` cap,
+ * oldest entries are evicted (insertion-order via a Map).
+ *
+ * Cache is bypassed for evaluation contexts without a `targetingKey`
+ * (flag value depends on every attribute, not a stable key).
+ *
+ * Operators with a hot-reload need pass `bustOn: "flag-reload"` and
+ * call `cached.bust()` from their reload handler — clears the entire
+ * map.
+ */
+
+var validateOpts = require("./validate-opts");
+var lazyRequire  = require("./lazy-require");
+var C            = require("./constants");
+var { defineClass } = require("./framework-error");
+var FlagError = defineClass("FlagError", { alwaysPermanent: true });
+
+var audit = lazyRequire(function () { return require("./audit"); });
+
+function cache(downstream, opts) {
+  opts = opts || {};
+  validateOpts(opts, ["ttlMs", "maxEntries", "audit"], "flag.cache");
+  if (!downstream || typeof downstream.evaluate !== "function") {
+    throw new FlagError("flag/bad-cache",
+      "cache: downstream provider must implement .evaluate()");
+  }
+  // allow:numeric-opt-Infinity — defaults clamped + ttl-floor enforced below
+  var ttlMs = (typeof opts.ttlMs === "number" && opts.ttlMs > 0)
+    ? opts.ttlMs
+    : C.TIME.seconds(30);
+  if (ttlMs < C.TIME.seconds(1)) {
+    throw new FlagError("flag/bad-cache",
+      "cache: ttlMs must be >= 1000ms - got " + ttlMs);
+  }
+  // allow:numeric-opt-Infinity — maxEntries default + Math.floor coerce; throws on bad type at config time
+  var maxEntries = (typeof opts.maxEntries === "number" && opts.maxEntries > 0)
+    ? Math.floor(opts.maxEntries)
+    : 10000;                                       // allow:raw-byte-literal — entry-count default
+  var auditOn = opts.audit === true;            // off by default — too chatty
+  var entries = new Map();
+  var hits   = 0;
+  var misses = 0;
+  var evictions = 0;
+
+  function _evictExpired(nowMs) {
+    var iter = entries.entries();
+    var step = iter.next();
+    while (!step.done) {
+      if (step.value[1].expiresAt <= nowMs) {
+        entries.delete(step.value[0]);
+        evictions += 1;
+      }
+      step = iter.next();
+    }
+  }
+
+  function _evictOldest() {
+    var first = entries.keys().next();
+    if (!first.done) {
+      entries.delete(first.value);
+      evictions += 1;
+    }
+  }
+
+  return {
+    kind: "cache:" + (downstream.kind || "unknown"),
+    list: typeof downstream.list === "function"
+      ? function () { return downstream.list(); }
+      : function () { return []; },
+    evaluate: function (flagKey, ctx) {
+      var tk = (ctx && typeof ctx.targetingKey === "string") ? ctx.targetingKey : null;
+      if (!tk) {
+        misses += 1;
+        return downstream.evaluate(flagKey, ctx);
+      }
+      var key = tk + "::" + flagKey;
+      var now = Date.now();
+      var entry = entries.get(key);
+      if (entry && entry.expiresAt > now) {
+        hits += 1;
+        return entry.value;
+      }
+      if (entry) entries.delete(key);
+      var freshResult = downstream.evaluate(flagKey, ctx);
+      misses += 1;
+      // Don't cache flag-not-found — operator might add it later.
+      if (freshResult && freshResult.reason !== "flag_not_found") {
+        if (entries.size >= maxEntries) _evictOldest();
+        entries.set(key, { value: freshResult, expiresAt: now + ttlMs });
+      }
+      // Periodic sweep — evict expired on every 100th miss.
+      if (misses % 100 === 0) _evictExpired(now);
+      return freshResult;
+    },
+    bust: function () {
+      var prevSize = entries.size;
+      entries.clear();
+      if (auditOn) {
+        try {
+          audit().safeEmit({
+            action:   "flag.cache.bust",
+            outcome:  "success",
+            actor:    null,
+            metadata: { prevSize: prevSize },
+          });
+        } catch (_e) { /* drop-silent */ }
+      }
+      return prevSize;
+    },
+    stats: function () {
+      return {
+        size:      entries.size,
+        hits:      hits,
+        misses:    misses,
+        evictions: evictions,
+        hitRatio:  (hits + misses) === 0 ? 0 : hits / (hits + misses),
+        ttlMs:     ttlMs,
+        maxEntries: maxEntries,
+      };
+    },
+  };
+}
+
+module.exports = { cache: cache, FlagError: FlagError };

package/lib/flag-evaluation-context.js

@@ -0,0 +1,135 @@
+"use strict";
+/**
+ * Flag evaluation context — the operator-supplied object describing
+ * the subject of a flag evaluation: targeting key, user attributes,
+ * tenant id, environment, custom attributes.
+ *
+ * Per the OpenFeature specification:
+ *   - `targetingKey` is the canonical identity for percentage-bucket
+ *     stickiness (so a 50% rollout consistently picks the SAME 50%
+ *     of users across re-evaluations).
+ *   - All other attributes flow through targeting rules.
+ *
+ * The framework's helper produces a frozen, normalised context object.
+ * Operators compose contexts incrementally: start from `fromRequest`
+ * (extracts user / tenant / locale from req), augment with `merge`,
+ * then evaluate.
+ */
+
+var nodeCrypto    = require("crypto");
+var validateOpts  = require("./validate-opts");
+var lazyRequire   = require("./lazy-require");
+var { defineClass } = require("./framework-error");
+var FlagError = defineClass("FlagError", { alwaysPermanent: true });
+
+var fwCrypto = lazyRequire(function () { return require("./crypto"); });
+
+function _normalize(input, label) {
+  if (input == null) return {};
+  if (typeof input !== "object" || Array.isArray(input)) {
+    throw new FlagError("flag/bad-context",
+      (label || "context") + ": must be a plain object");
+  }
+  var out = {};
+  for (var key in input) {
+    if (!Object.prototype.hasOwnProperty.call(input, key)) continue;
+    if (key === "__proto__" || key === "constructor" || key === "prototype") {
+      continue;                                          // poisoned-keys defense
+    }
+    out[key] = input[key];
+  }
+  return out;
+}
+
+function create(input) {
+  var normalised = _normalize(input, "create");
+  if (normalised.targetingKey != null &&
+      typeof normalised.targetingKey !== "string") {
+    throw new FlagError("flag/bad-context",
+      "create: targetingKey must be a string");
+  }
+  return Object.freeze(normalised);
+}
+
+function merge(base, overlay) {
+  var b = _normalize(base, "merge.base");
+  var o = _normalize(overlay, "merge.overlay");
+  var out = {};
+  for (var k1 in b) {
+    if (Object.prototype.hasOwnProperty.call(b, k1)) out[k1] = b[k1];
+  }
+  for (var k2 in o) {
+    if (Object.prototype.hasOwnProperty.call(o, k2)) out[k2] = o[k2];
+  }
+  return Object.freeze(out);
+}
+
+function fromRequest(req, opts) {
+  opts = opts || {};
+  validateOpts(opts, ["userKey", "tenantKey", "extra"], "flag.context.fromRequest");
+  if (!req || typeof req !== "object") {
+    return create({});
+  }
+  var ctx = {};
+  if (req.user) {
+    if (typeof req.user.id === "string")    ctx.userId = req.user.id;
+    if (typeof req.user.role === "string")  ctx.role   = req.user.role;
+    if (typeof req.user.email === "string") ctx.email  = req.user.email;
+    if (req.user.tenantId != null)          ctx.tenantId = req.user.tenantId;
+  }
+  var headers = req.headers || {};
+  if (typeof headers["accept-language"] === "string") {
+    ctx.locale = headers["accept-language"].split(",")[0].split(";")[0].trim();
+  }
+  if (typeof headers["user-agent"] === "string") {
+    ctx.userAgent = headers["user-agent"];
+  }
+  // Targeting key: prefer explicit userKey opt, then user.id, then a
+  // request-stable hash of (clientIp + userAgent) for anonymous flows.
+  var tk = null;
+  if (typeof opts.userKey === "string" && opts.userKey.length > 0) {
+    tk = opts.userKey;
+  } else if (req.user && typeof req.user.id === "string") {
+    tk = req.user.id;
+  } else {
+    var ip = (typeof headers["x-forwarded-for"] === "string" &&
+              headers["x-forwarded-for"].split(",")[0].trim()) ||
+             (req.connection && req.connection.remoteAddress) || "";
+    var ua = headers["user-agent"] || "";
+    tk = "anon:" + fwCrypto().sha3Hash(ip + ":" + ua).slice(0, 16);   // allow:raw-byte-literal — base16 prefix len
+  }
+  ctx.targetingKey = tk;
+
+  if (opts.extra && typeof opts.extra === "object") {
+    for (var k in opts.extra) {
+      if (Object.prototype.hasOwnProperty.call(opts.extra, k)) {
+        if (k === "__proto__" || k === "constructor" || k === "prototype") continue;
+        ctx[k] = opts.extra[k];
+      }
+    }
+  }
+  return create(ctx);
+}
+
+// Percentage-bucket helper — deterministic hash of (targetingKey +
+// flagKey) into [0, 100) for percentage-based rollouts.
+function bucketOf(targetingKey, flagKey) {
+  if (typeof targetingKey !== "string" || typeof flagKey !== "string" ||
+      targetingKey.length === 0 || flagKey.length === 0) {
+    return 0;
+  }
+  var digest = nodeCrypto.createHash("sha3-512")
+    .update(flagKey + ":" + targetingKey).digest();
+  // Use first 4 bytes as a uint32, then mod 10000 → 0.00-99.99 with
+  // sub-percent granularity.
+  var n = digest.readUInt32BE(0);
+  return (n % 10000) / 100;                                 // allow:raw-byte-literal — bucket-precision divisor
+}
+
+module.exports = {
+  create:       create,
+  merge:        merge,
+  fromRequest:  fromRequest,
+  bucketOf:     bucketOf,
+  FlagError:    FlagError,
+};

package/lib/flag-providers.js

@@ -0,0 +1,279 @@
+"use strict";
+/**
+ * Flag providers — backend implementations that produce flag values
+ * for a given (flagKey, evaluationContext) tuple.
+ *
+ * Three first-party providers ship with the framework:
+ *
+ *   localFile({ path, watch?, signature? })
+ *     Reads a JSON file at boot and on change-events. Each flag entry
+ *     describes default-variant + variants + targeting-rules +
+ *     percentage-rollouts.
+ *
+ *   memory({ flags })
+ *     In-process map of flagKey to flag-spec. Useful for tests and
+ *     for operators who treat flags as code (compiled into the boot
+ *     image).
+ *
+ *   environmentVariable({ envVarPattern, prefix })
+ *     Reads a flag's value from process.env. Useful for boot-time
+ *     toggles bound to deployment configuration.
+ *
+ * Operators with a remote-flag-management plane (LaunchDarkly, flagd,
+ * Unleash, OpenFeature gRPC) wire their own provider implementing the
+ * `evaluate(flagKey, ctx)` contract and pass it to b.flag.create.
+ *
+ * Provider contract:
+ *
+ *   provider.evaluate(flagKey, ctx) -> {
+ *     value:    any,            // resolved value (boolean / string / number / object)
+ *     variant:  string,         // variant name ("on" / "off" / "treatment-A" / ...)
+ *     reason:   string,         // "default" | "targeting_match" | "split" | ...
+ *     metadata: object,         // optional per-provider hints
+ *   }
+ *
+ *   provider.list() -> string[]   list of registered flag keys (for tooling)
+ *   provider.kind   -> "local-file" | "memory" | "environment" | <operator-defined>
+ */
+
+var fs = require("fs");
+var validateOpts   = require("./validate-opts");
+var lazyRequire    = require("./lazy-require");
+var safeJson       = require("./safe-json");
+var C              = require("./constants");
+var { defineClass } = require("./framework-error");
+var FlagError = defineClass("FlagError", { alwaysPermanent: true });
+
+var targeting = require("./flag-targeting");
+var contextMod = lazyRequire(function () { return require("./flag-evaluation-context"); });
+
+function _validateFlagSpec(flagKey, spec) {
+  if (!spec || typeof spec !== "object") {
+    throw new FlagError("flag/bad-spec",
+      "flag spec for " + JSON.stringify(flagKey) + " must be an object");
+  }
+  validateOpts(spec, [
+    "default", "variants", "rules", "rollout",
+    "description", "tags", "kind",
+  ], "flag spec for " + flagKey);
+  if (spec.variants == null || typeof spec.variants !== "object") {
+    throw new FlagError("flag/bad-spec",
+      flagKey + ": variants object is required (variantName -> value)");
+  }
+  if (typeof spec.default !== "string" ||
+      !Object.prototype.hasOwnProperty.call(spec.variants, spec.default)) {
+    throw new FlagError("flag/bad-spec",
+      flagKey + ": default must be a variant name; got " + JSON.stringify(spec.default));
+  }
+  if (spec.rules != null) {
+    targeting.validateRules(spec.rules, flagKey + ".rules");
+    // Every rule's variant must be a registered variant.
+    for (var i = 0; i < spec.rules.length; i += 1) {
+      var v = spec.rules[i].variant;
+      if (!Object.prototype.hasOwnProperty.call(spec.variants, v)) {
+        throw new FlagError("flag/bad-spec",
+          flagKey + ".rules[" + i + "].variant: " + JSON.stringify(v) +
+          " is not a registered variant");
+      }
+    }
+  }
+  if (spec.rollout != null) {
+    if (!Array.isArray(spec.rollout)) {
+      throw new FlagError("flag/bad-spec",
+        flagKey + ".rollout: must be an array of { variant, percentage } entries");
+    }
+    var sum = 0;
+    for (var j = 0; j < spec.rollout.length; j += 1) {
+      var entry = spec.rollout[j];
+      if (!entry || typeof entry !== "object" ||
+          typeof entry.variant !== "string" ||
+          typeof entry.percentage !== "number" ||
+          entry.percentage < 0 || entry.percentage > 100) {
+        throw new FlagError("flag/bad-spec",
+          flagKey + ".rollout[" + j + "]: must be { variant: string, percentage: 0..100 }");
+      }
+      if (!Object.prototype.hasOwnProperty.call(spec.variants, entry.variant)) {
+        throw new FlagError("flag/bad-spec",
+          flagKey + ".rollout[" + j + "].variant: " + JSON.stringify(entry.variant) +
+          " is not a registered variant");
+      }
+      sum += entry.percentage;
+    }
+    if (sum > 100.0001) {
+      throw new FlagError("flag/bad-spec",
+        flagKey + ".rollout: percentage sum must be <= 100; got " + sum);
+    }
+  }
+}
+
+function memory(opts) {
+  opts = opts || {};
+  validateOpts(opts, ["flags"], "flag.providers.memory");
+  if (!opts.flags || typeof opts.flags !== "object") {
+    throw new FlagError("flag/bad-provider",
+      "providers.memory: flags object required (flagKey -> spec)");
+  }
+  var flags = {};
+  for (var key in opts.flags) {
+    if (!Object.prototype.hasOwnProperty.call(opts.flags, key)) continue;
+    _validateFlagSpec(key, opts.flags[key]);
+    flags[key] = opts.flags[key];
+  }
+  return _makeProvider("memory", flags);
+}
+
+function localFile(opts) {
+  opts = opts || {};
+  validateOpts(opts, ["path", "watch"], "flag.providers.localFile");
+  validateOpts.requireNonEmptyString(opts.path,
+    "providers.localFile: path", FlagError, "flag/bad-provider");
+  var raw;
+  try { raw = fs.readFileSync(opts.path, "utf8"); }
+  catch (e) {
+    throw new FlagError("flag/bad-provider",
+      "providers.localFile: cannot read file " + JSON.stringify(opts.path) +
+      " - " + e.message);
+  }
+  var parsed;
+  try { parsed = safeJson.parse(raw, { maxBytes: C.BYTES.mib(1) }); }
+  catch (e) {
+    throw new FlagError("flag/bad-provider",
+      "providers.localFile: invalid JSON in " + opts.path + " - " + e.message);
+  }
+  if (!parsed || typeof parsed !== "object" || !parsed.flags) {
+    throw new FlagError("flag/bad-provider",
+      "providers.localFile: file must export { flags: { flagKey: spec, ... } }");
+  }
+  for (var key in parsed.flags) {
+    if (!Object.prototype.hasOwnProperty.call(parsed.flags, key)) continue;
+    _validateFlagSpec(key, parsed.flags[key]);
+  }
+  var provider = _makeProvider("local-file", parsed.flags);
+  provider._path = opts.path;
+  if (opts.watch === true) {
+    try {
+      fs.watch(opts.path, { persistent: false }, function () {
+        try {
+          var nextRaw = fs.readFileSync(opts.path, "utf8");
+          var nextParsed = safeJson.parse(nextRaw, { maxBytes: C.BYTES.mib(1) });
+          if (nextParsed && nextParsed.flags) {
+            for (var k in nextParsed.flags) {
+              if (Object.prototype.hasOwnProperty.call(nextParsed.flags, k)) {
+                _validateFlagSpec(k, nextParsed.flags[k]);
+              }
+            }
+            provider._replace(nextParsed.flags);
+          }
+        } catch (_e) { /* drop-silent on hot-path reload */ }
+      });
+    } catch (_w) { /* watch unavailable - non-fatal */ }
+  }
+  return provider;
+}
+
+function environmentVariable(opts) {
+  opts = opts || {};
+  validateOpts(opts, ["prefix", "flags"], "flag.providers.environmentVariable");
+  var prefix = (typeof opts.prefix === "string" && opts.prefix.length > 0)
+    ? opts.prefix
+    : "FLAG_";
+  if (!opts.flags || typeof opts.flags !== "object") {
+    throw new FlagError("flag/bad-provider",
+      "providers.environmentVariable: flags object required to bound the surface");
+  }
+  var resolved = {};
+  for (var key in opts.flags) {
+    if (!Object.prototype.hasOwnProperty.call(opts.flags, key)) continue;
+    _validateFlagSpec(key, opts.flags[key]);
+    var envName = prefix + key.toUpperCase().replace(/[-.]/g, "_");
+    var envValue = process.env[envName];
+    var clone = Object.assign({}, opts.flags[key]);
+    if (typeof envValue === "string" && envValue.length > 0) {
+      // Map known env semantics: "true"/"false" override boolean flags
+      // by replacing the default variant. Operators wanting richer
+      // overrides ship a different provider.
+      var variantNames = Object.keys(opts.flags[key].variants);
+      if (variantNames.indexOf(envValue) !== -1) {
+        clone.default = envValue;
+      } else if (envValue === "true" && variantNames.indexOf("on")  !== -1) {
+        clone.default = "on";
+      } else if (envValue === "false" && variantNames.indexOf("off") !== -1) {
+        clone.default = "off";
+      }
+    }
+    resolved[key] = clone;
+  }
+  return _makeProvider("environment", resolved);
+}
+
+function _makeProvider(kind, initialFlags) {
+  var flags = initialFlags;
+  var provider = {
+    kind: kind,
+    list: function () { return Object.keys(flags); },
+    get:  function (flagKey) { return flags[flagKey] || null; },
+    _replace: function (newFlags) { flags = newFlags; },
+    evaluate: function (flagKey, ctx) {
+      var spec = flags[flagKey];
+      if (!spec) {
+        return {
+          value:    undefined,
+          variant:  null,
+          reason:   "flag_not_found",
+          metadata: { flagKey: flagKey, provider: kind },
+        };
+      }
+      // 1. Targeting rules
+      var targetingResult = targeting.evaluateRules(spec.rules || [], ctx, spec.default);
+      if (targetingResult.reason === "targeting_match") {
+        return _buildResult(flagKey, spec, targetingResult.variant,
+                            "targeting_match", { ruleIndex: targetingResult.ruleIndex });
+      }
+      // 2. Percentage rollout
+      if (Array.isArray(spec.rollout) && spec.rollout.length > 0) {
+        var tk = (ctx && typeof ctx.targetingKey === "string") ? ctx.targetingKey : "";
+        if (tk.length > 0) {
+          var bucket = contextMod().bucketOf(tk, flagKey);
+          var cumulative = 0;
+          for (var i = 0; i < spec.rollout.length; i += 1) {
+            cumulative += spec.rollout[i].percentage;
+            if (bucket < cumulative) {
+              return _buildResult(flagKey, spec, spec.rollout[i].variant,
+                                  "split", { bucket: bucket });
+            }
+          }
+        }
+      }
+      // 3. Default variant
+      return _buildResult(flagKey, spec, spec.default, "default", {});
+    },
+  };
+  return provider;
+}
+
+function _buildResult(flagKey, spec, variantName, reason, metaAdd) {
+  var value = spec.variants[variantName];
+  if (value === undefined) {
+    // Unknown variant from rollout/rule (validated at registration,
+    // so this only fires if a rule passed validation but referenced
+    // a since-deleted variant).
+    value = spec.variants[spec.default];
+    variantName = spec.default;
+    reason = "default_fallback";
+  }
+  var metadata = { flagKey: flagKey, provider: spec._provider || null };
+  if (metaAdd) {
+    for (var k in metaAdd) {
+      if (Object.prototype.hasOwnProperty.call(metaAdd, k)) metadata[k] = metaAdd[k];
+    }
+  }
+  return { value: value, variant: variantName, reason: reason, metadata: metadata };
+}
+
+module.exports = {
+  memory:               memory,
+  localFile:            localFile,
+  environmentVariable:  environmentVariable,
+  _validateFlagSpec:    _validateFlagSpec,
+  FlagError:            FlagError,
+};