@blamejs/core 0.7.106 → 0.8.0

package/lib/flag-targeting.js

@@ -0,0 +1,210 @@
+"use strict";
+/**
+ * Flag targeting — rule-based evaluation against an operator's
+ * evaluation-context object (subject id, role, region, custom
+ * attributes). Operators describe targeting in declarative JSON; the
+ * framework evaluates without expression-injection risk.
+ *
+ * Rule shape:
+ *
+ *   { variant: "on", conditions: [
+ *       { attribute: "user.role",   op: "eq",  value: "admin" },
+ *       { attribute: "user.region", op: "in",  value: ["EU", "UK"] },
+ *       { attribute: "user.tier",   op: "gte", value: 2 },
+ *   ] }
+ *
+ * Operators are: eq / neq / in / nin / gt / gte / lt / lte / startsWith
+ * / endsWith / contains / regex / exists / not_exists / between.
+ *
+ * Evaluation is conjunctive across `conditions` (all must pass for
+ * the variant to apply). Multiple rules are evaluated in declaration
+ * order; first match wins. If no rule matches, the flag's default
+ * variant is returned.
+ *
+ * Per the validation-tier policy: rule-shape validation throws at
+ * boot (config-time entry-point); evaluation hot-path returns
+ * structured falsey on bad-shape rather than throwing.
+ */
+
+var validateOpts = require("./validate-opts");
+var { defineClass } = require("./framework-error");
+var FlagError = defineClass("FlagError", { alwaysPermanent: true });
+
+var VALID_OPS = [
+  "eq", "neq", "in", "nin", "gt", "gte", "lt", "lte",
+  "starts_with", "ends_with", "contains",
+  "regex", "exists", "not_exists", "between",
+];
+
+function _readPath(ctx, attribute) {
+  if (typeof attribute !== "string" || attribute.length === 0) return undefined;
+  if (!ctx || typeof ctx !== "object") return undefined;
+  var parts = attribute.split(".");
+  var current = ctx;
+  for (var i = 0; i < parts.length; i += 1) {
+    if (current == null || typeof current !== "object") return undefined;
+    current = current[parts[i]];
+  }
+  return current;
+}
+
+function _evaluateCondition(condition, ctx) {
+  if (!condition || typeof condition !== "object") return false;
+  if (typeof condition.op !== "string") return false;
+  if (VALID_OPS.indexOf(condition.op) === -1) return false;
+
+  var presented = _readPath(ctx, condition.attribute);
+  switch (condition.op) {
+    case "eq":           return presented === condition.value;
+    case "neq":          return presented !== condition.value;
+    case "in":           return Array.isArray(condition.value) &&
+                                condition.value.indexOf(presented) !== -1;
+    case "nin":          return Array.isArray(condition.value) &&
+                                condition.value.indexOf(presented) === -1;
+    case "gt":           return typeof presented === "number" &&
+                                typeof condition.value === "number" &&
+                                presented > condition.value;
+    case "gte":          return typeof presented === "number" &&
+                                typeof condition.value === "number" &&
+                                presented >= condition.value;
+    case "lt":           return typeof presented === "number" &&
+                                typeof condition.value === "number" &&
+                                presented < condition.value;
+    case "lte":          return typeof presented === "number" &&
+                                typeof condition.value === "number" &&
+                                presented <= condition.value;
+    case "starts_with":  return typeof presented === "string" &&
+                                typeof condition.value === "string" &&
+                                presented.indexOf(condition.value) === 0;
+    case "ends_with":    return typeof presented === "string" &&
+                                typeof condition.value === "string" &&
+                                presented.length >= condition.value.length &&
+                                presented.slice(-condition.value.length) === condition.value;
+    case "contains":     return typeof presented === "string" &&
+                                typeof condition.value === "string" &&
+                                presented.indexOf(condition.value) !== -1;
+    case "regex":
+      // Regex bounded — operator-supplied regex compiled at rule-validate
+      // time and re-used here. Refuse to evaluate if regex isn't pre-
+      // compiled (defense against runtime regex compilation per call).
+      if (!(condition._compiledRegex instanceof RegExp)) return false;
+      return typeof presented === "string" &&
+             condition._compiledRegex.test(presented);
+    case "exists":       return presented !== undefined;
+    case "not_exists":   return presented === undefined;
+    case "between":      return Array.isArray(condition.value) &&
+                                condition.value.length === 2 &&
+                                typeof presented === "number" &&
+                                presented >= condition.value[0] &&
+                                presented <= condition.value[1];
+    default:             return false;
+  }
+}
+
+function evaluateRules(rules, ctx, defaultVariant) {
+  if (!Array.isArray(rules)) return { variant: defaultVariant, ruleIndex: -1, reason: "default" };
+  for (var i = 0; i < rules.length; i += 1) {
+    var rule = rules[i];
+    if (!rule || typeof rule !== "object") continue;
+    if (!Array.isArray(rule.conditions)) continue;
+    var allPass = true;
+    for (var j = 0; j < rule.conditions.length; j += 1) {
+      if (!_evaluateCondition(rule.conditions[j], ctx)) {
+        allPass = false; break;
+      }
+    }
+    if (allPass) {
+      return { variant: rule.variant, ruleIndex: i, reason: "targeting_match" };
+    }
+  }
+  return { variant: defaultVariant, ruleIndex: -1, reason: "default" };
+}
+
+function validateRules(rules, label) {
+  label = label || "rules";
+  if (rules == null) return [];
+  if (!Array.isArray(rules)) {
+    throw new FlagError("flag/bad-rules",
+      label + ": rules must be an array of rule objects");
+  }
+  var validated = [];
+  for (var i = 0; i < rules.length; i += 1) {
+    var rule = rules[i];
+    if (!rule || typeof rule !== "object") {
+      throw new FlagError("flag/bad-rule",
+        label + "[" + i + "]: rule must be an object");
+    }
+    validateOpts(rule, ["variant", "conditions", "weight"], label + "[" + i + "]");
+    validateOpts.requireNonEmptyString(rule.variant, label + "[" + i + "].variant",
+      FlagError, "flag/bad-rule");
+    if (!Array.isArray(rule.conditions)) {
+      throw new FlagError("flag/bad-rule",
+        label + "[" + i + "].conditions: must be an array");
+    }
+    var validatedConds = [];
+    for (var j = 0; j < rule.conditions.length; j += 1) {
+      var cond = rule.conditions[j];
+      var clabel = label + "[" + i + "].conditions[" + j + "]";
+      if (!cond || typeof cond !== "object") {
+        throw new FlagError("flag/bad-condition",
+          clabel + ": condition must be an object");
+      }
+      validateOpts(cond, ["attribute", "op", "value"], clabel);
+      validateOpts.requireNonEmptyString(cond.attribute, clabel + ".attribute",
+        FlagError, "flag/bad-condition");
+      if (VALID_OPS.indexOf(cond.op) === -1) {
+        throw new FlagError("flag/bad-condition",
+          clabel + ".op: must be one of " + VALID_OPS.join(", ") +
+          " - got " + JSON.stringify(cond.op));
+      }
+      var validatedCond = {
+        attribute: cond.attribute,
+        op:        cond.op,
+        value:     cond.value,
+      };
+      if (cond.op === "regex") {
+        if (typeof cond.value !== "string") {
+          throw new FlagError("flag/bad-condition",
+            clabel + ".value: regex op requires a string value");
+        }
+        if (cond.value.length > 200) {
+          throw new FlagError("flag/bad-condition",
+            clabel + ".value: regex pattern must be <= 200 chars (DoS defense)");
+        }
+        try {
+          // allow:dynamic-regex — operator-supplied targeting pattern, length-bounded to 200 chars above
+          validatedCond._compiledRegex = new RegExp(cond.value);
+        } catch (e) {
+          throw new FlagError("flag/bad-condition",
+            clabel + ".value: invalid regex - " + e.message);
+        }
+      }
+      if (cond.op === "between") {
+        if (!Array.isArray(cond.value) || cond.value.length !== 2 ||
+            typeof cond.value[0] !== "number" || typeof cond.value[1] !== "number") {
+          throw new FlagError("flag/bad-condition",
+            clabel + ".value: between op requires [number, number]");
+        }
+      }
+      if ((cond.op === "in" || cond.op === "nin") && !Array.isArray(cond.value)) {
+        throw new FlagError("flag/bad-condition",
+          clabel + ".value: " + cond.op + " op requires an array value");
+      }
+      validatedConds.push(validatedCond);
+    }
+    validated.push({
+      variant:    rule.variant,
+      conditions: validatedConds,
+      weight:     (typeof rule.weight === "number") ? rule.weight : null,
+    });
+  }
+  return validated;
+}
+
+module.exports = {
+  evaluateRules:  evaluateRules,
+  validateRules:  validateRules,
+  VALID_OPS:      VALID_OPS,
+  _readPath:      _readPath,
+  FlagError:      FlagError,
+};

package/lib/flag.js

@@ -0,0 +1,284 @@
+"use strict";
+/**
+ * b.flag — feature-flag client per the OpenFeature specification
+ * (https://openfeature.dev/specification/).
+ *
+ *   var flag = b.flag.create({
+ *     provider: b.flag.providers.localFile({ path: "./flags.json" }),
+ *     defaultEvaluationContext: { environment: "production" },
+ *   });
+ *
+ *   var enabled = flag.getBoolean("new-checkout-flow", { targetingKey: req.user.id });
+ *   var sample  = flag.getString ("greeting-banner", { targetingKey: req.user.id }, "default-text");
+ *   var rate    = flag.getNumber ("upsell-rate",     { targetingKey: req.user.id }, 0);
+ *   var cfg     = flag.getObject ("checkout-config", { targetingKey: req.user.id }, {});
+ *
+ *   var details = flag.getDetails("new-checkout-flow", ctx);
+ *   //  → { value, variant, reason, metadata }
+ *
+ *   flag.middleware()  → request-time middleware that attaches a
+ *                         per-request `flag` accessor onto req.
+ *
+ * Per the validation-tier policy: create() throws on bad opts; the
+ * hot-path getValue / getBoolean / etc. NEVER throw — they return the
+ * operator-supplied default + emit `flag.evaluation.error` on the
+ * audit chain so the operator sees the problem without taking down
+ * the request.
+ */
+
+var validateOpts   = require("./validate-opts");
+var lazyRequire    = require("./lazy-require");
+var providersMod   = require("./flag-providers");
+var contextMod     = require("./flag-evaluation-context");
+var targeting      = require("./flag-targeting");
+var cacheMod       = require("./flag-cache");
+var { defineClass } = require("./framework-error");
+var FlagError = defineClass("FlagError", { alwaysPermanent: true });
+
+var audit = lazyRequire(function () { return require("./audit"); });
+
+function _validateHooks(rawHooks) {
+  var out = { before: [], after: [], error: [], finally: [] };
+  if (rawHooks == null) return out;
+  if (typeof rawHooks !== "object") {
+    throw new FlagError("flag/bad-hooks",
+      "create: hooks must be an object { before, after, error, finally }");
+  }
+  var stages = ["before", "after", "error", "finally"];
+  for (var i = 0; i < stages.length; i += 1) {
+    var stage = stages[i];
+    if (rawHooks[stage] == null) continue;
+    var arr = Array.isArray(rawHooks[stage]) ? rawHooks[stage] : [rawHooks[stage]];
+    for (var j = 0; j < arr.length; j += 1) {
+      if (typeof arr[j] !== "function") {
+        throw new FlagError("flag/bad-hooks",
+          "create: hooks." + stage + "[" + j + "] must be a function");
+      }
+    }
+    out[stage] = arr.slice();
+  }
+  return out;
+}
+
+function create(opts) {
+  opts = opts || {};
+  validateOpts(opts, [
+    "provider", "providers", "defaultEvaluationContext",
+    "audit", "errorHandler", "hooks",
+  ], "flag.create");
+  var providers = [];
+  if (opts.provider) {
+    if (typeof opts.provider.evaluate !== "function") {
+      throw new FlagError("flag/bad-provider",
+        "create: provider must implement .evaluate(flagKey, ctx)");
+    }
+    providers.push(opts.provider);
+  }
+  if (Array.isArray(opts.providers)) {
+    for (var i = 0; i < opts.providers.length; i += 1) {
+      if (typeof opts.providers[i].evaluate !== "function") {
+        throw new FlagError("flag/bad-provider",
+          "create: providers[" + i + "] must implement .evaluate()");
+      }
+      providers.push(opts.providers[i]);
+    }
+  }
+  if (providers.length === 0) {
+    throw new FlagError("flag/no-provider",
+      "create: at least one provider is required - pass `provider` or `providers`");
+  }
+  var defaultCtx = contextMod.create(opts.defaultEvaluationContext || {});
+  var auditOn    = opts.audit !== false;
+  var errorHandler = (typeof opts.errorHandler === "function")
+    ? opts.errorHandler : null;
+  var hooks = _validateHooks(opts.hooks);
+
+  function _emitErrorAudit(flagKey, err, ctx) {
+    if (!auditOn) return;
+    try {
+      audit().safeEmit({
+        action:   "flag.evaluation.error",
+        outcome:  "fail",
+        actor:    { targetingKey: ctx && ctx.targetingKey || null },
+        metadata: {
+          flagKey: flagKey,
+          message: err && err.message || String(err),
+          code:    err && err.code || "flag/unknown",
+        },
+      });
+    } catch (_e) { /* drop-silent */ }
+  }
+
+  function _runHook(stage, info) {
+    var arr = hooks[stage];
+    if (!arr || arr.length === 0) return;
+    for (var i = 0; i < arr.length; i += 1) {
+      try { arr[i](info); } catch (_e) { /* drop-silent — hooks are observability, not blocking */ }
+    }
+  }
+
+  function _evaluate(flagKey, ctx) {
+    var mergedCtx = contextMod.merge(defaultCtx, ctx || {});
+    var startMs = Date.now();
+    _runHook("before", { flagKey: flagKey, ctx: mergedCtx });
+    for (var i = 0; i < providers.length; i += 1) {
+      try {
+        var result = providers[i].evaluate(flagKey, mergedCtx);
+        if (result && result.reason !== "flag_not_found") {
+          if (auditOn) {
+            try {
+              audit().safeEmit({
+                action:   "flag.evaluated",
+                outcome:  "success",
+                actor:    { targetingKey: mergedCtx.targetingKey || null },
+                metadata: {
+                  flagKey:  flagKey,
+                  variant:  result.variant,
+                  reason:   result.reason,
+                  provider: providers[i].kind || null,
+                },
+              });
+            } catch (_e) { /* drop-silent */ }
+          }
+          _runHook("after", { flagKey: flagKey, ctx: mergedCtx, result: result, elapsedMs: Date.now() - startMs });
+          _runHook("finally", { flagKey: flagKey, ctx: mergedCtx, result: result });
+          return result;
+        }
+      } catch (err) {
+        _emitErrorAudit(flagKey, err, mergedCtx);
+        _runHook("error", { flagKey: flagKey, ctx: mergedCtx, err: err });
+        if (errorHandler) {
+          try { errorHandler({ flagKey: flagKey, err: err, ctx: mergedCtx }); }
+          catch (_e2) { /* drop-silent */ }
+        }
+      }
+    }
+    var notFound = {
+      value:    undefined,
+      variant:  null,
+      reason:   "flag_not_found",
+      metadata: { flagKey: flagKey, providers: providers.map(function (p) { return p.kind; }) },
+    };
+    _runHook("after", { flagKey: flagKey, ctx: mergedCtx, result: notFound, elapsedMs: Date.now() - startMs });
+    _runHook("finally", { flagKey: flagKey, ctx: mergedCtx, result: notFound });
+    return notFound;
+  }
+
+  function _coerceBoolean(v) {
+    if (v === true || v === false) return v;
+    if (v === "true")  return true;
+    if (v === "false") return false;
+    if (v === 1) return true;
+    if (v === 0) return false;
+    return null;
+  }
+
+  return {
+    getValue: function (flagKey, ctx, defaultValue) {
+      var r = _evaluate(flagKey, ctx);
+      if (r.value === undefined) return defaultValue;
+      return r.value;
+    },
+    getDetails: function (flagKey, ctx) {
+      return _evaluate(flagKey, ctx);
+    },
+    getBoolean: function (flagKey, ctx, defaultValue) {
+      var r = _evaluate(flagKey, ctx);
+      if (r.value === undefined) return defaultValue === true;
+      var coerced = _coerceBoolean(r.value);
+      return coerced != null ? coerced : (defaultValue === true);
+    },
+    getString: function (flagKey, ctx, defaultValue) {
+      var r = _evaluate(flagKey, ctx);
+      if (typeof r.value === "string") return r.value;
+      return (typeof defaultValue === "string") ? defaultValue : "";
+    },
+    getNumber: function (flagKey, ctx, defaultValue) {
+      var r = _evaluate(flagKey, ctx);
+      if (typeof r.value === "number" && isFinite(r.value)) return r.value;
+      return (typeof defaultValue === "number") ? defaultValue : 0;
+    },
+    getObject: function (flagKey, ctx, defaultValue) {
+      var r = _evaluate(flagKey, ctx);
+      if (r.value && typeof r.value === "object") return r.value;
+      return defaultValue == null ? {} : defaultValue;
+    },
+    list: function () {
+      var keys = Object.create(null);
+      for (var i = 0; i < providers.length; i += 1) {
+        if (typeof providers[i].list === "function") {
+          var arr = providers[i].list();
+          for (var j = 0; j < arr.length; j += 1) keys[arr[j]] = true;
+        }
+      }
+      return Object.keys(keys);
+    },
+    providers: providers.slice(),
+    defaultEvaluationContext: defaultCtx,
+    getValues: function (flagKeys, ctx) {
+      var out = {};
+      if (!Array.isArray(flagKeys)) return out;
+      for (var i = 0; i < flagKeys.length; i += 1) {
+        var k = flagKeys[i];
+        if (typeof k !== "string") continue;
+        var r = _evaluate(k, ctx);
+        out[k] = r.value;
+      }
+      return out;
+    },
+    getDetailsAll: function (flagKeys, ctx) {
+      var out = {};
+      if (!Array.isArray(flagKeys)) return out;
+      for (var i = 0; i < flagKeys.length; i += 1) {
+        var k = flagKeys[i];
+        if (typeof k !== "string") continue;
+        out[k] = _evaluate(k, ctx);
+      }
+      return out;
+    },
+    addProvider: function (next) {
+      if (!next || typeof next.evaluate !== "function") {
+        throw new FlagError("flag/bad-provider",
+          "addProvider: provider must implement .evaluate()");
+      }
+      providers.push(next);
+      return providers.length;
+    },
+    removeProvider: function (target) {
+      var before = providers.length;
+      for (var i = providers.length - 1; i >= 0; i -= 1) {
+        if (providers[i] === target) providers.splice(i, 1);
+      }
+      return before - providers.length;
+    },
+    middleware: function (mwOpts) {
+      mwOpts = mwOpts || {};
+      validateOpts(mwOpts, ["userKey"], "flag.middleware");
+      var self = this;
+      return function flagMiddleware(req, res, next) {
+        var reqCtx = contextMod.fromRequest(req, {
+          userKey: mwOpts.userKey,
+        });
+        req.flag = {
+          getBoolean: function (k, def)         { return self.getBoolean(k, reqCtx, def); },
+          getString:  function (k, def)         { return self.getString (k, reqCtx, def); },
+          getNumber:  function (k, def)         { return self.getNumber (k, reqCtx, def); },
+          getObject:  function (k, def)         { return self.getObject (k, reqCtx, def); },
+          getValue:   function (k, def)         { return self.getValue  (k, reqCtx, def); },
+          getDetails: function (k)              { return self.getDetails(k, reqCtx); },
+          ctx:        reqCtx,
+        };
+        return next();
+      };
+    },
+  };
+}
+
+module.exports = {
+  create:           create,
+  providers:        providersMod,
+  context:          contextMod,
+  targeting:        targeting,
+  cache:            cacheMod.cache,
+  FlagError:        FlagError,
+};