@fabricorg/platform 1.7.0 → 1.8.0

package/dist/chunk-IF6NJORI.cjs

@@ -0,0 +1,526 @@
+'use strict';
+
+// adapters/circuit-breaker.ts
+function classifyCircuitBreakerOutcome(kind) {
+  switch (kind) {
+    case "success":
+      return "success";
+    case "permanent_failure":
+      return "ignored";
+    case "transient_failure":
+    case "timeout":
+    case "ambiguous":
+      return "failure";
+    default:
+      return "failure";
+  }
+}
+var MANUAL_OVERRIDES = ["force_open", "force_closed"];
+function assertAdapterCircuitBreakerConfig(config) {
+  if (!config || typeof config !== "object") {
+    throw new RangeError("Adapter circuit breaker config must be an object.");
+  }
+  if (config.mode !== "monitor" && config.mode !== "enforce") {
+    throw new RangeError(`Adapter circuit breaker mode must be "monitor" or "enforce"; got ${JSON.stringify(config.mode)}.`);
+  }
+  if (!Number.isInteger(config.failureThreshold) || config.failureThreshold < 1) {
+    throw new RangeError(`Adapter circuit breaker failureThreshold must be a positive integer; got ${String(config.failureThreshold)}.`);
+  }
+  if (typeof config.windowMs !== "number" || !Number.isFinite(config.windowMs) || config.windowMs <= 0) {
+    throw new RangeError(`Adapter circuit breaker windowMs must be a positive number of milliseconds; got ${String(config.windowMs)}.`);
+  }
+  if (typeof config.cooldownMs !== "number" || !Number.isFinite(config.cooldownMs) || config.cooldownMs < 0) {
+    throw new RangeError(`Adapter circuit breaker cooldownMs must be a non-negative number of milliseconds; got ${String(config.cooldownMs)}.`);
+  }
+  if (config.minimumSamples !== void 0 && (!Number.isInteger(config.minimumSamples) || config.minimumSamples < 1)) {
+    throw new RangeError(`Adapter circuit breaker minimumSamples must be a positive integer; got ${String(config.minimumSamples)}.`);
+  }
+  if (config.probeLeaseMs !== void 0 && (typeof config.probeLeaseMs !== "number" || !Number.isFinite(config.probeLeaseMs) || config.probeLeaseMs <= 0)) {
+    throw new RangeError(`Adapter circuit breaker probeLeaseMs must be a positive number of milliseconds; got ${String(config.probeLeaseMs)}.`);
+  }
+  if (config.manualOverride !== void 0 && !MANUAL_OVERRIDES.includes(config.manualOverride)) {
+    throw new RangeError(`Adapter circuit breaker manualOverride must be "force_open" or "force_closed"; got ${JSON.stringify(config.manualOverride)}.`);
+  }
+}
+var InMemoryAdapterCircuitBreaker = class {
+  key;
+  mode;
+  config;
+  now;
+  onEvent;
+  probeLeaseMs;
+  samples = [];
+  state = "closed";
+  openedAt = 0;
+  probeIssuedAt;
+  /** Advances on every state change, manual override change and probe grant. */
+  generation = 0;
+  manualOverride;
+  /** Telemetry waiting for the current operation to commit. */
+  outbox = [];
+  operationDepth = 0;
+  flushing = false;
+  constructor(options) {
+    assertAdapterCircuitBreakerConfig(options.config);
+    this.key = options.key;
+    this.config = { ...options.config };
+    this.mode = options.config.mode;
+    this.now = options.now ?? Date.now;
+    this.onEvent = options.onEvent;
+    this.manualOverride = options.config.manualOverride;
+    this.probeLeaseMs = options.config.probeLeaseMs ?? Math.max(options.config.cooldownMs, options.config.windowMs);
+  }
+  getState() {
+    this.settle(this.now());
+    return this.reportedState();
+  }
+  getManualOverride() {
+    return this.manualOverride;
+  }
+  /**
+   * Set (`force_open` / `force_closed`) or clear (`undefined`) the manual
+   * override. Clearing returns the breaker to `closed` with its window intact.
+   */
+  setManualOverride(override) {
+    if (override !== void 0 && !MANUAL_OVERRIDES.includes(override)) {
+      throw new RangeError(`Adapter circuit breaker manualOverride must be "force_open" or "force_closed"; got ${JSON.stringify(override)}.`);
+    }
+    const now = this.now();
+    this.settle(now);
+    if (override === this.manualOverride) return;
+    this.operation(() => {
+      const from = this.reportedState();
+      this.manualOverride = override;
+      this.generation++;
+      if (override === void 0) {
+        this.state = "closed";
+        this.releaseProbe();
+      }
+      this.emit({
+        type: "state_change",
+        key: this.key,
+        mode: this.mode,
+        at: now,
+        from,
+        to: this.reportedState(),
+        reason: override === void 0 ? "manual_override_cleared" : "manual_override",
+        ...override ? { manualOverride: override } : {}
+      });
+    });
+  }
+  check() {
+    return this.decide(false, this.now());
+  }
+  acquire() {
+    const now = this.now();
+    this.settle(now);
+    return this.operation(() => this.decide(true, now));
+  }
+  record(outcome, admission) {
+    const now = this.now();
+    this.settle(now);
+    this.operation(() => this.applyOutcome(outcome, admission, now));
+  }
+  applyOutcome(outcome, admission, now) {
+    const generation = admission?.generation;
+    if (generation !== void 0 && generation !== this.generation) return;
+    const resolvesProbe = this.state === "half_open" && this.probeIssuedAt !== void 0 && (generation === void 0 || admission?.probe === true);
+    if (outcome === "ignored") {
+      if (resolvesProbe) this.releaseProbe();
+      return;
+    }
+    this.prune(now);
+    this.samples.push({ at: now, failure: outcome === "failure" });
+    if (this.manualOverride) return;
+    if (resolvesProbe) {
+      this.releaseProbe();
+      if (outcome === "success") {
+        this.samples = [];
+        this.transition("closed", "probe_succeeded", now);
+      } else {
+        this.openedAt = now;
+        this.transition("open", "probe_failed", now);
+      }
+      return;
+    }
+    if (this.state === "closed" && outcome === "failure" && this.shouldTrip()) {
+      this.openedAt = now;
+      this.transition("open", "failure_threshold", now);
+    }
+  }
+  /**
+   * `take` is false for {@link check}: a pure preview that sees an elapsed
+   * cooldown without committing it, takes no probe and emits nothing.
+   */
+  decide(take, now) {
+    if (this.manualOverride === "force_closed") {
+      return { allowed: true, state: "closed", probe: false, manualOverride: "force_closed", generation: this.generation };
+    }
+    if (this.manualOverride === "force_open") {
+      return this.refuse(take, { state: "open", manualOverride: "force_open" });
+    }
+    const cooldownElapsed = this.state === "open" && now - this.openedAt >= this.config.cooldownMs;
+    if (take) this.advance(now);
+    const state = !take && cooldownElapsed ? "half_open" : this.state;
+    if (state === "closed") return { allowed: true, state: "closed", probe: false, generation: this.generation };
+    if (state === "open") {
+      return this.refuse(take, {
+        state: "open",
+        retryAfterMs: Math.max(0, this.openedAt + this.config.cooldownMs - now)
+      });
+    }
+    const probeFree = !take && cooldownElapsed || this.probeIssuedAt === void 0 || now - this.probeIssuedAt >= this.probeLeaseMs;
+    if (!probeFree) return this.refuse(take, { state: "half_open" });
+    if (!take) return { allowed: true, state: "half_open", probe: true, generation: this.generation };
+    this.probeIssuedAt = now;
+    this.generation++;
+    return { allowed: true, state: "half_open", probe: true, generation: this.generation };
+  }
+  refuse(take, detail) {
+    const enforce = this.mode === "enforce";
+    if (take) {
+      this.emit({
+        type: enforce ? "rejected" : "would_reject",
+        key: this.key,
+        mode: this.mode,
+        at: this.now(),
+        ...detail
+      });
+    }
+    const generation = this.generation;
+    return enforce ? { allowed: false, probe: false, ...detail, generation } : { allowed: true, probe: false, wouldReject: true, ...detail, generation };
+  }
+  releaseProbe() {
+    this.probeIssuedAt = void 0;
+  }
+  /** Apply the time-based open → half_open transition. */
+  advance(now) {
+    if (this.state === "open" && now - this.openedAt >= this.config.cooldownMs) {
+      this.releaseProbe();
+      this.transition("half_open", "cooldown_elapsed", now);
+    }
+  }
+  shouldTrip() {
+    const minimumSamples = this.config.minimumSamples ?? this.config.failureThreshold;
+    const total = this.samples.length;
+    if (total < minimumSamples) return false;
+    let consecutive = 0;
+    for (let index = total - 1; index >= 0 && this.samples[index].failure; index--) consecutive++;
+    if (consecutive >= this.config.failureThreshold) return true;
+    const failures = this.samples.reduce((count, sample) => count + (sample.failure ? 1 : 0), 0);
+    return failures / total >= this.config.failureThreshold / minimumSamples;
+  }
+  prune(now) {
+    const cutoff = now - this.config.windowMs;
+    let drop = 0;
+    while (drop < this.samples.length && this.samples[drop].at < cutoff) drop++;
+    if (drop > 0) this.samples.splice(0, drop);
+  }
+  transition(to, reason, at) {
+    const from = this.state;
+    if (from === to) return;
+    this.state = to;
+    this.generation++;
+    this.emit({ type: "state_change", key: this.key, mode: this.mode, at, from, to, reason });
+  }
+  reportedState() {
+    if (this.manualOverride) return this.manualOverride === "force_open" ? "open" : "closed";
+    return this.state;
+  }
+  /**
+   * Commit an elapsed cooldown as an operation of its own, delivering its
+   * event before the caller's operation reads state.
+   */
+  settle(now) {
+    if (this.manualOverride) return;
+    this.operation(() => this.advance(now));
+  }
+  /**
+   * Run `step` to completion, then deliver the telemetry it produced. The
+   * return value is fixed before any listener runs.
+   */
+  operation(step) {
+    this.operationDepth++;
+    try {
+      return step();
+    } finally {
+      this.operationDepth--;
+      if (this.operationDepth === 0) this.flush();
+    }
+  }
+  emit(event) {
+    if (this.onEvent) this.outbox.push(event);
+  }
+  /**
+   * Deliver buffered events in order. A listener that calls back into the
+   * breaker queues its own events; this loop delivers them after it returns
+   * instead of recursing.
+   */
+  flush() {
+    if (this.flushing) return;
+    this.flushing = true;
+    try {
+      for (let event = this.outbox.shift(); event; event = this.outbox.shift()) this.deliver(event);
+    } finally {
+      this.flushing = false;
+    }
+  }
+  deliver(event) {
+    const listener = this.onEvent;
+    if (!listener) return;
+    try {
+      const result = listener(event);
+      if (result && typeof result.then === "function") {
+        result.then(void 0, () => void 0);
+      }
+    } catch {
+    }
+  }
+};
+var AdapterCircuitBreakerRegistry = class {
+  constructor(options = {}) {
+    this.options = options;
+  }
+  options;
+  breakers = /* @__PURE__ */ new Map();
+  forAdapter(adapter) {
+    if (!adapter.circuitBreaker) return void 0;
+    const key = `${adapter.adapterType}:${adapter.operation}`;
+    let breaker = this.breakers.get(key);
+    if (!breaker) {
+      breaker = new InMemoryAdapterCircuitBreaker({
+        key,
+        config: adapter.circuitBreaker,
+        ...this.options.now ? { now: this.options.now } : {},
+        ...this.options.onEvent ? { onEvent: this.options.onEvent } : {}
+      });
+      this.breakers.set(key, breaker);
+    }
+    return breaker;
+  }
+  /** The breaker already created for `adapterType:operation`, if any. */
+  get(adapterType, operation) {
+    return this.breakers.get(`${adapterType}:${operation}`);
+  }
+};
+var AdapterCircuitOpenError = class extends Error {
+  name = "AdapterCircuitOpenError";
+  code = "ADAPTER_CIRCUIT_OPEN";
+  reason = "circuit_open";
+  adapterKey;
+  state;
+  /** The attempt number that was refused (1 = refused before any call). */
+  attempt;
+  retryAfterMs;
+  manualOverride;
+  /** Error of the previous attempt, when the breaker opened mid-retry. */
+  lastError;
+  constructor(input) {
+    const after = input.retryAfterMs !== void 0 ? `; retry after ${input.retryAfterMs} ms` : "";
+    super(`Adapter circuit is ${input.state === "half_open" ? "half-open with its probe in flight" : "open"} for ${input.adapterKey}; the call was not attempted${after}.`);
+    this.adapterKey = input.adapterKey;
+    this.state = input.state;
+    this.attempt = input.attempt;
+    if (input.retryAfterMs !== void 0) this.retryAfterMs = input.retryAfterMs;
+    if (input.manualOverride !== void 0) this.manualOverride = input.manualOverride;
+    if (input.lastError !== void 0) this.lastError = input.lastError;
+  }
+};
+function isAdapterCircuitOpenError(error) {
+  if (error instanceof AdapterCircuitOpenError) return true;
+  return typeof error === "object" && error !== null && error.name === "AdapterCircuitOpenError" && error.code === "ADAPTER_CIRCUIT_OPEN";
+}
+
+// adapters/index.ts
+function adapterKey(adapterType, operation) {
+  return `${adapterType}:${operation}`;
+}
+var MissingAdapterRegistrationError = class extends Error {
+  constructor(adapterType, operation) {
+    super(`No adapter registered for adapterType "${adapterType}" and operation "${operation}"`);
+    this.name = "MissingAdapterRegistrationError";
+  }
+};
+var AdapterRegistry = class {
+  adapters = /* @__PURE__ */ new Map();
+  register(adapter) {
+    const key = adapterKey(adapter.adapterType, adapter.operation);
+    if (this.adapters.has(key)) {
+      throw new Error(
+        `Adapter already registered for adapterType "${adapter.adapterType}" and operation "${adapter.operation}"`
+      );
+    }
+    this.adapters.set(key, adapter);
+  }
+  resolve(adapterType, operation) {
+    return this.adapters.get(adapterKey(adapterType, operation));
+  }
+  require(adapterType, operation) {
+    const adapter = this.resolve(adapterType, operation);
+    if (!adapter) {
+      throw new MissingAdapterRegistrationError(adapterType, operation);
+    }
+    return adapter;
+  }
+};
+var DEFAULT_RETRY_POLICY = {
+  maxAttempts: 3,
+  initialDelayMs: 100,
+  backoffMultiplier: 2,
+  maxDelayMs: 1e3
+};
+var NO_RETRY_POLICY = {
+  idempotent: false,
+  maxAttempts: 1,
+  initialDelayMs: 0,
+  backoffMultiplier: 1,
+  maxDelayMs: 0
+};
+function resolveAdapterRetryPolicy(policy, defaultIdempotent) {
+  const idempotent = policy?.idempotent ?? defaultIdempotent;
+  if (!idempotent) {
+    return NO_RETRY_POLICY;
+  }
+  return {
+    idempotent: true,
+    maxAttempts: Math.max(1, Math.min(policy?.maxAttempts ?? DEFAULT_RETRY_POLICY.maxAttempts, 5)),
+    initialDelayMs: Math.max(0, policy?.initialDelayMs ?? DEFAULT_RETRY_POLICY.initialDelayMs),
+    backoffMultiplier: Math.max(
+      1,
+      policy?.backoffMultiplier ?? DEFAULT_RETRY_POLICY.backoffMultiplier
+    ),
+    maxDelayMs: Math.max(0, policy?.maxDelayMs ?? DEFAULT_RETRY_POLICY.maxDelayMs)
+  };
+}
+function getRetryDelayMs(attempt, policy) {
+  const exponentialDelay = policy.initialDelayMs * policy.backoffMultiplier ** Math.max(0, attempt - 1);
+  return Math.min(exponentialDelay, policy.maxDelayMs);
+}
+function classifyAdapterOutcome(result) {
+  if (result.outcome) {
+    assertAdapterOutcomeConsistency(result);
+    return result.outcome;
+  }
+  return result.success ? "success" : "transient_failure";
+}
+function shouldRetryAdapterOutcome(kind, idempotent) {
+  return kind === "transient_failure" && idempotent;
+}
+function assertAdapterOutcomeConsistency(result) {
+  if (result.success && result.outcome && result.outcome !== "success") {
+    throw new Error(
+      `Adapter returned success=true with contradictory outcome "${result.outcome}"; a successful result must not declare a non-success outcome.`
+    );
+  }
+}
+function recordCircuitOutcome(breaker, outcome, admission) {
+  if (!breaker) return;
+  try {
+    breaker.record(outcome, admission);
+  } catch {
+  }
+}
+function circuitOpenError(breaker, admission, attempt, lastError) {
+  return new AdapterCircuitOpenError({
+    adapterKey: breaker.key,
+    state: admission.state,
+    attempt,
+    ...admission.retryAfterMs !== void 0 ? { retryAfterMs: admission.retryAfterMs } : {},
+    ...admission.manualOverride !== void 0 ? { manualOverride: admission.manualOverride } : {},
+    ...lastError !== void 0 ? { lastError } : {}
+  });
+}
+async function executeWithAdapterRetry(options) {
+  const policy = resolveAdapterRetryPolicy(options.policy, options.defaultIdempotent);
+  const sleep = options.sleep ?? ((delayMs) => new Promise((resolve) => setTimeout(resolve, delayMs)));
+  const breaker = options.circuitBreaker;
+  let lastError;
+  for (let attempt = 1; attempt <= policy.maxAttempts; attempt++) {
+    let admission;
+    let executed = false;
+    let recorded = false;
+    const record = (outcome) => {
+      if (!executed || recorded) return;
+      recorded = true;
+      recordCircuitOutcome(breaker, outcome, admission);
+    };
+    let refusal;
+    async function handleThrown(error) {
+      lastError = error instanceof Error ? error.message : String(error);
+      const thrownOutcome = options.classifyThrownError ? options.classifyThrownError(error) : "transient_failure";
+      record(classifyCircuitBreakerOutcome(thrownOutcome));
+      let willRetry = shouldRetryAdapterOutcome(thrownOutcome, policy.idempotent) && attempt < policy.maxAttempts;
+      const blocked = willRetry ? refusedRetry(breaker) : void 0;
+      if (blocked) willRetry = false;
+      const nextDelayMs = willRetry ? getRetryDelayMs(attempt, policy) : void 0;
+      await options.onAttempt?.({ attempt, error: lastError, willRetry, nextDelayMs });
+      if (blocked) return blocked;
+      if (!willRetry) return "rethrow";
+      await sleep(nextDelayMs ?? 0);
+      return "retry";
+    }
+    try {
+      if (options.prepareAttempt) await options.prepareAttempt(attempt, policy.maxAttempts);
+    } catch (error) {
+      const decision = await handleThrown(error);
+      if (decision === "rethrow") throw error;
+      if (decision === "retry") continue;
+      refusal = decision;
+    }
+    if (!refusal) {
+      if (breaker) {
+        admission = breaker.acquire();
+        if (!admission.allowed) throw circuitOpenError(breaker, admission, attempt, lastError);
+      }
+      try {
+        executed = true;
+        const result = await options.execute(attempt, policy.maxAttempts);
+        if (options.isSuccessful(result)) {
+          record("success");
+          await options.onAttempt?.({ attempt, result, willRetry: false });
+          return result;
+        }
+        lastError = options.getError(result) ?? "Adapter returned unsuccessful result";
+        const outcome = options.classifyOutcome ? options.classifyOutcome(result) : "transient_failure";
+        record(classifyCircuitBreakerOutcome(outcome));
+        let willRetry = shouldRetryAdapterOutcome(outcome, policy.idempotent) && attempt < policy.maxAttempts;
+        refusal = willRetry ? refusedRetry(breaker) : void 0;
+        if (refusal) willRetry = false;
+        const nextDelayMs = willRetry ? getRetryDelayMs(attempt, policy) : void 0;
+        await options.onAttempt?.({ attempt, result, error: lastError, willRetry, nextDelayMs });
+        if (!willRetry && !refusal) {
+          return result;
+        }
+        if (!refusal) await sleep(nextDelayMs ?? 0);
+      } catch (error) {
+        const decision = await handleThrown(error);
+        if (decision === "rethrow") throw error;
+        refusal = decision === "retry" ? void 0 : decision;
+      }
+    }
+    if (refusal && breaker) throw circuitOpenError(breaker, refusal, attempt + 1, lastError);
+  }
+  throw new Error(lastError ?? "Adapter retry exhausted");
+}
+function refusedRetry(breaker) {
+  if (!breaker) return void 0;
+  const preview = breaker.check();
+  return preview.allowed ? void 0 : preview;
+}
+
+exports.AdapterCircuitBreakerRegistry = AdapterCircuitBreakerRegistry;
+exports.AdapterCircuitOpenError = AdapterCircuitOpenError;
+exports.AdapterRegistry = AdapterRegistry;
+exports.InMemoryAdapterCircuitBreaker = InMemoryAdapterCircuitBreaker;
+exports.MissingAdapterRegistrationError = MissingAdapterRegistrationError;
+exports.assertAdapterCircuitBreakerConfig = assertAdapterCircuitBreakerConfig;
+exports.assertAdapterOutcomeConsistency = assertAdapterOutcomeConsistency;
+exports.classifyAdapterOutcome = classifyAdapterOutcome;
+exports.classifyCircuitBreakerOutcome = classifyCircuitBreakerOutcome;
+exports.executeWithAdapterRetry = executeWithAdapterRetry;
+exports.getRetryDelayMs = getRetryDelayMs;
+exports.isAdapterCircuitOpenError = isAdapterCircuitOpenError;
+exports.resolveAdapterRetryPolicy = resolveAdapterRetryPolicy;
+exports.shouldRetryAdapterOutcome = shouldRetryAdapterOutcome;
+//# sourceMappingURL=chunk-IF6NJORI.cjs.map
+//# sourceMappingURL=chunk-IF6NJORI.cjs.map