@fabricorg/platform 1.7.0 → 1.9.0

package/dist/adapters/index.d.cts

@@ -1,3 +1,366 @@
+/**
+ * State of an adapter circuit breaker.
+ *
+ * - `closed`: calls flow and outcomes are counted.
+ * - `open`: the dependency is presumed unhealthy. In `enforce` mode calls are
+ *   rejected without being attempted until `cooldownMs` has elapsed.
+ * - `half_open`: the cooldown elapsed. One probe call is admitted; its outcome
+ *   closes the breaker (success) or reopens it (failure).
+ */
+type AdapterCircuitState = "closed" | "open" | "half_open";
+/**
+ * How a single adapter outcome counts toward the breaker.
+ *
+ * - `success`: the dependency answered and the call succeeded.
+ * - `failure`: evidence the dependency is unhealthy.
+ * - `ignored`: the dependency answered but rejected the request on its merits
+ *   (a validation or business rejection). It is neither a success nor a
+ *   dependency failure and does not enter the rolling window.
+ */
+type AdapterCircuitOutcome = "success" | "failure" | "ignored";
+/**
+ * Map an {@link AdapterOutcomeKind} to how it counts toward a circuit breaker.
+ *
+ * | Outcome kind        | Counts as |
+ * |---------------------|-----------|
+ * | `success`           | `success` |
+ * | `transient_failure` | `failure` |
+ * | `timeout`           | `failure` |
+ * | `ambiguous`         | `failure` |
+ * | `permanent_failure` | `ignored` |
+ *
+ * `ambiguous` counts as a failure: the dependency did not give a definite
+ * answer, which is a health signal even though the Host routes the invocation
+ * to reconciliation. `permanent_failure` (validation or rejection) is the
+ * dependency working correctly and saying no, so it does not trip the breaker.
+ * `executeWithAdapterRetry` classifies a thrown error with the caller's
+ * `classifyThrownError` (default `transient_failure`) and maps that kind here,
+ * so an unclassified thrown error counts as a failure.
+ */
+declare function classifyCircuitBreakerOutcome(kind: AdapterOutcomeKind): AdapterCircuitOutcome;
+/** The answer a breaker gives before a call. */
+interface AdapterCircuitAdmission {
+    /**
+     * Whether the call may proceed. Always `true` in `monitor` mode; `false`
+     * only in `enforce` mode while the breaker is open, forced open, or
+     * half-open with its probe already in flight.
+     */
+    allowed: boolean;
+    /** State at the time of the decision. */
+    state: AdapterCircuitState;
+    /** True when this admission is the half-open probe. Pass it back to `record`. */
+    probe: boolean;
+    /** Monitor mode only: true when `enforce` mode would have rejected this call. */
+    wouldReject?: boolean;
+    /**
+     * Milliseconds until the breaker will admit a probe, when known. Absent while
+     * a manual `force_open` override is set or a half-open probe is in flight.
+     */
+    retryAfterMs?: number;
+    /** Set when a manual override decided the admission. */
+    manualOverride?: AdapterCircuitBreakerManualOverride;
+    /**
+     * The breaker epoch the admission was granted in; opaque to callers.
+     * {@link InMemoryAdapterCircuitBreaker} lets an outcome change state only
+     * when this still matches its current epoch. An admission without it is
+     * treated as current.
+     */
+    generation?: number;
+}
+/**
+ * Contract between a circuit breaker and `executeWithAdapterRetry`.
+ * Implement it to plug in a shared or distributed breaker.
+ */
+interface AdapterCircuitBreaker {
+    /** Registry key this breaker guards; defaults to `adapterType:operation`. */
+    readonly key: string;
+    readonly mode: "monitor" | "enforce";
+    /** Current state, applying any elapsed cooldown or manual override. */
+    getState(): AdapterCircuitState;
+    /**
+     * Preview whether a call would be admitted now. Side-effect free: it does
+     * not commit an elapsed cooldown, take the half-open probe or emit
+     * telemetry.
+     */
+    check(): AdapterCircuitAdmission;
+    /**
+     * Decide whether a call may start now. Call it immediately before the
+     * external effect and pass the returned admission to {@link record}.
+     */
+    acquire(): AdapterCircuitAdmission;
+    /**
+     * Record the outcome of a call that was admitted by {@link acquire}. Pass
+     * that admission, not a {@link check} preview, so the breaker can tell a
+     * stale outcome from a current one.
+     */
+    record(outcome: AdapterCircuitOutcome, admission?: AdapterCircuitAdmission): void;
+}
+type AdapterCircuitBreakerEventReason = "failure_threshold" | "cooldown_elapsed" | "probe_succeeded" | "probe_failed" | "manual_override" | "manual_override_cleared";
+interface AdapterCircuitBreakerEventBase {
+    key: string;
+    mode: "monitor" | "enforce";
+    /** Epoch milliseconds from the breaker's clock. */
+    at: number;
+}
+/** Telemetry reported by {@link InMemoryAdapterCircuitBreaker}. */
+type AdapterCircuitBreakerEvent = (AdapterCircuitBreakerEventBase & {
+    type: "state_change";
+    from: AdapterCircuitState;
+    to: AdapterCircuitState;
+    reason: AdapterCircuitBreakerEventReason;
+    manualOverride?: AdapterCircuitBreakerManualOverride;
+}) | (AdapterCircuitBreakerEventBase & {
+    /** Enforce mode refused a call; it was not attempted. */
+    type: "rejected";
+    state: AdapterCircuitState;
+    retryAfterMs?: number;
+    manualOverride?: AdapterCircuitBreakerManualOverride;
+}) | (AdapterCircuitBreakerEventBase & {
+    /** Monitor mode let a call through that enforce mode would have refused. */
+    type: "would_reject";
+    state: AdapterCircuitState;
+    retryAfterMs?: number;
+    manualOverride?: AdapterCircuitBreakerManualOverride;
+});
+/**
+ * Telemetry callback. Errors it throws and promises it rejects are caught
+ * and discarded so telemetry cannot change an adapter call's outcome.
+ *
+ * {@link InMemoryAdapterCircuitBreaker} calls it only after the operation that
+ * produced the event has committed, never part-way through a decision or a
+ * record. A callback may call back into the breaker; it sees committed state,
+ * and events its own calls produce are delivered after it returns, in order.
+ */
+type AdapterCircuitBreakerEventListener = (event: AdapterCircuitBreakerEvent) => void | Promise<void>;
+interface InMemoryAdapterCircuitBreakerOptions {
+    /** Usually `adapterType:operation`. */
+    key: string;
+    config: AdapterCircuitBreakerConfig;
+    /** Epoch-millisecond clock. Defaults to `Date.now`. */
+    now?: () => number;
+    onEvent?: AdapterCircuitBreakerEventListener;
+}
+/**
+ * Validate a circuit-breaker config. Throws a `RangeError` naming the first
+ * invalid field: `mode` must be `monitor` or `enforce`; `failureThreshold` and
+ * `minimumSamples` positive integers; `windowMs` and `probeLeaseMs` positive
+ * finite numbers; `cooldownMs` a non-negative finite number; `manualOverride`
+ * `force_open` or `force_closed` when present.
+ */
+declare function assertAdapterCircuitBreakerConfig(config: AdapterCircuitBreakerConfig): void;
+/**
+ * Dependency-free, in-process circuit breaker for one adapter operation.
+ *
+ * State lives in this instance only: it is not shared between processes,
+ * hosts, or replicas, and it is lost on restart. Each replica trips on the
+ * failures it observes itself.
+ *
+ * Tripping rule (parity with the .NET `InMemoryAdapterCircuitBreaker`): after
+ * a failure is recorded while `closed`, let `N` be the outcomes recorded within
+ * the last `windowMs` and `M = minimumSamples ?? failureThreshold`. The breaker
+ * opens when `N >= M` and either
+ * 1. the most recent `failureThreshold` outcomes in the window are all
+ *    failures, or
+ * 2. the failure ratio in the window is at least `failureThreshold / M`.
+ *
+ * With `minimumSamples` omitted this reads "`failureThreshold` consecutive
+ * failures". With `minimumSamples: 20, failureThreshold: 10` it also opens at
+ * a 50% failure rate over at least 20 calls.
+ *
+ * After `cooldownMs` the breaker turns `half_open` and admits one probe. A
+ * probe success closes it and clears the window; a probe failure reopens it
+ * and restarts the cooldown. At most one probe is outstanding at a time: it
+ * holds a lease of `probeLeaseMs` (default `max(cooldownMs, windowMs)`, never
+ * derived from the cooldown alone, so `cooldownMs: 0` still admits one probe).
+ * A probe that has not recorded when its lease expires is considered lost and
+ * the next call becomes the probe.
+ *
+ * Epochs: the breaker keeps a generation counter that advances on every state
+ * change (including one committed by an elapsed cooldown), every manual
+ * override change, and every probe grant. Each admission carries the
+ * generation it was granted in. `record` first commits any elapsed cooldown,
+ * then compares generations. An outcome from an earlier epoch is stale: it is
+ * dropped entirely. It changes no state, does not resolve or free the probe
+ * slot, and is not added to the rolling window, so it cannot contribute to a
+ * later trip either. Because a probe grant starts a new epoch, the outstanding
+ * probe is the only `probe: true` admission of the current epoch, which is how
+ * a replaced probe's late outcome is told apart. An outcome recorded without an
+ * admission, or with one that has no `generation`, is treated as current: it is
+ * sampled, can trip a closed breaker and resolves an outstanding probe.
+ *
+ * Telemetry is buffered and delivered after each operation commits. An
+ * elapsed cooldown is committed, and its `cooldown_elapsed` event delivered,
+ * as a step of its own before `acquire`, `record`, `getState` or
+ * `setManualOverride` continues, so a callback reacting to it (for example by
+ * forcing the breaker open) governs the call that observed it. Every other
+ * event is delivered once the method's decision or record is final, and a
+ * callback never revokes an admission that is already committed. Two cases
+ * follow from that: a breaker call made from inside a callback queues its own
+ * `cooldown_elapsed` behind the current delivery and decides first; and with
+ * `cooldownMs: 0`, a cooldown that falls due again during the decision (because
+ * a callback reopened the breaker) is committed and admitted before its event
+ * is delivered.
+ *
+ * `monitor` mode runs the same state machine and reports the same telemetry
+ * but admits every call; calls enforce mode would have refused are reported
+ * as `would_reject`.
+ *
+ * A manual override pins the reported state (`force_open` → `open`,
+ * `force_closed` → `closed`) and suspends automatic transitions while set;
+ * outcomes of calls admitted under the override are still recorded. Like an
+ * automatic open, `force_open` blocks only in `enforce` mode. Clearing the
+ * override returns the breaker to `closed` with its window intact.
+ */
+declare class InMemoryAdapterCircuitBreaker implements AdapterCircuitBreaker {
+    readonly key: string;
+    readonly mode: "monitor" | "enforce";
+    private readonly config;
+    private readonly now;
+    private readonly onEvent;
+    private readonly probeLeaseMs;
+    private samples;
+    private state;
+    private openedAt;
+    private probeIssuedAt;
+    /** Advances on every state change, manual override change and probe grant. */
+    private generation;
+    private manualOverride;
+    /** Telemetry waiting for the current operation to commit. */
+    private readonly outbox;
+    private operationDepth;
+    private flushing;
+    constructor(options: InMemoryAdapterCircuitBreakerOptions);
+    getState(): AdapterCircuitState;
+    getManualOverride(): AdapterCircuitBreakerManualOverride | undefined;
+    /**
+     * Set (`force_open` / `force_closed`) or clear (`undefined`) the manual
+     * override. Clearing returns the breaker to `closed` with its window intact.
+     */
+    setManualOverride(override: AdapterCircuitBreakerManualOverride | undefined): void;
+    check(): AdapterCircuitAdmission;
+    acquire(): AdapterCircuitAdmission;
+    record(outcome: AdapterCircuitOutcome, admission?: AdapterCircuitAdmission): void;
+    private applyOutcome;
+    /**
+     * `take` is false for {@link check}: a pure preview that sees an elapsed
+     * cooldown without committing it, takes no probe and emits nothing.
+     */
+    private decide;
+    private refuse;
+    private releaseProbe;
+    /** Apply the time-based open → half_open transition. */
+    private advance;
+    private shouldTrip;
+    private prune;
+    private transition;
+    private reportedState;
+    /**
+     * Commit an elapsed cooldown as an operation of its own, delivering its
+     * event before the caller's operation reads state.
+     */
+    private settle;
+    /**
+     * Run `step` to completion, then deliver the telemetry it produced. The
+     * return value is fixed before any listener runs.
+     */
+    private operation;
+    private emit;
+    /**
+     * 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.
+     */
+    private flush;
+    private deliver;
+}
+/** Trusted invocation context available when selecting an adapter breaker. */
+interface AdapterCircuitBreakerScope {
+    tenantId: string;
+    spaceId?: string;
+}
+/**
+ * Key by tenant, optional space, vendor, and adapter operation. Components are
+ * URI-encoded to distinguish embedded delimiters; ordinary adapter identifiers
+ * remain readable as the trailing `adapterType:operation`.
+ *
+ * Missing scope uses a separate `unscoped` namespace (still split by vendor)
+ * rather than rejecting the call. Calls without scope share that
+ * namespace; callers must supply scope for tenant isolation. Missing space or
+ * vendor is distinct from an empty string. `vendor` is required by the public
+ * adapter type, but its absence is tolerated for JavaScript callers.
+ * Keys appear in errors and telemetry: use non-secret identifiers.
+ */
+declare function scopedAdapterCircuitBreakerKey(adapter: AdapterImplementation, scope: AdapterCircuitBreakerScope | undefined): string;
+/** Supplies the breaker, if any, that guards an adapter in invocation scope. */
+interface AdapterCircuitBreakerProvider {
+    forAdapter(adapter: AdapterImplementation, scope?: AdapterCircuitBreakerScope): AdapterCircuitBreaker | undefined;
+}
+interface AdapterCircuitBreakerRegistryOptions {
+    /**
+     * Defaults to `adapterType:operation`, shared across tenants and vendors in
+     * this registry. Use {@link scopedAdapterCircuitBreakerKey} for tenant,
+     * space, and vendor isolation. The first config seen for a key wins;
+     * later conflicting configs reuse that breaker without throwing. Breakers
+     * are never evicted, and scoped keys are high-cardinality: avoid them as
+     * metric labels.
+     */
+    key?: (adapter: AdapterImplementation, scope: AdapterCircuitBreakerScope | undefined) => string;
+    /** Epoch-millisecond clock handed to every breaker. Defaults to `Date.now`. */
+    now?: () => number;
+    onEvent?: AdapterCircuitBreakerEventListener;
+}
+/**
+ * Lazily creates one {@link InMemoryAdapterCircuitBreaker} per
+ * key, from that adapter's own `circuitBreaker` config. The default key is
+ * `adapterType:operation`, shared across tenants and vendors; override it with
+ * {@link AdapterCircuitBreakerRegistryOptions.key} to isolate invocation scopes.
+ * Adapters without a config get no breaker. The first config seen for a key
+ * wins; later conflicting configs reuse the existing breaker without throwing.
+ * Share a key only between adapters intended to use the same configuration.
+ */
+declare class AdapterCircuitBreakerRegistry implements AdapterCircuitBreakerProvider {
+    private readonly options;
+    private readonly breakers;
+    constructor(options?: AdapterCircuitBreakerRegistryOptions);
+    forAdapter(adapter: AdapterImplementation, scope?: AdapterCircuitBreakerScope): InMemoryAdapterCircuitBreaker | undefined;
+    /** Looks up the default `adapterType:operation` key without creating a breaker. */
+    get(adapterType: string, operation: string): InMemoryAdapterCircuitBreaker | undefined;
+    /** Looks up an exact key, including a custom key, without creating a breaker. */
+    getByKey(key: string): InMemoryAdapterCircuitBreaker | undefined;
+}
+/**
+ * Thrown by `executeWithAdapterRetry` when an `enforce`-mode breaker refuses
+ * an attempt. The refused attempt never reached `execute`, so no external
+ * effect happened for it.
+ */
+declare class AdapterCircuitOpenError extends Error {
+    readonly name = "AdapterCircuitOpenError";
+    readonly code: "ADAPTER_CIRCUIT_OPEN";
+    readonly reason: "circuit_open";
+    readonly adapterKey: string;
+    readonly state: AdapterCircuitState;
+    /** The attempt number that was refused (1 = refused before any call). */
+    readonly attempt: number;
+    readonly retryAfterMs?: number;
+    readonly manualOverride?: AdapterCircuitBreakerManualOverride;
+    /** Error of the previous attempt, when the breaker opened mid-retry. */
+    readonly lastError?: string;
+    constructor(input: {
+        adapterKey: string;
+        state: AdapterCircuitState;
+        attempt: number;
+        retryAfterMs?: number;
+        manualOverride?: AdapterCircuitBreakerManualOverride;
+        lastError?: string;
+    });
+}
+/**
+ * Recognise an {@link AdapterCircuitOpenError}, including one constructed by a
+ * second copy of this package (for example an ESM and a CommonJS build loaded
+ * side by side), where `instanceof` fails.
+ */
+declare function isAdapterCircuitOpenError(error: unknown): error is AdapterCircuitOpenError;
+
 interface AdapterExecutionContext {
     tenantId: string;
     spaceId: string;
@@ -89,12 +452,50 @@ interface ResolvedAdapterRetryPolicy {
     backoffMultiplier: number;
     maxDelayMs: number;
 }
+/** Manual circuit-breaker override: pin the breaker open or closed. */
+type AdapterCircuitBreakerManualOverride = "force_open" | "force_closed";
+/**
+ * Per-adapter circuit-breaker configuration, read by
+ * {@link AdapterCircuitBreakerRegistry} (and so by Platform Host) to create one
+ * in-process {@link InMemoryAdapterCircuitBreaker} per registry key (default
+ * `adapterType:operation`; configurable through the registry `key` option).
+ * Validated by {@link assertAdapterCircuitBreakerConfig}.
+ */
 interface AdapterCircuitBreakerConfig {
+    /**
+     * `monitor` records outcomes, runs the state machine and reports what it
+     * would have refused, but never blocks a call. `enforce` refuses calls
+     * while the breaker is open, without attempting them.
+     */
     mode: "monitor" | "enforce";
+    /**
+     * A failure count. Let `M = minimumSamples ?? failureThreshold`. Once at
+     * least `M` outcomes fall within `windowMs`, the breaker opens when the most
+     * recent `failureThreshold` of them are all failures, or when the failure
+     * ratio in the window reaches `failureThreshold / M`. Without
+     * `minimumSamples` this is "`failureThreshold` consecutive failures".
+     * Matches the .NET port's `InMemoryAdapterCircuitBreaker`. Positive integer.
+     */
     failureThreshold: number;
+    /** Rolling window, in milliseconds, of outcomes the thresholds consider. */
     windowMs: number;
+    /** Milliseconds an open breaker waits before admitting one half-open probe. */
     cooldownMs: number;
+    /** Outcomes required in the window before the breaker can open. Defaults to `failureThreshold`. */
     minimumSamples?: number;
+    /**
+     * How long, in milliseconds, the single half-open probe holds its slot
+     * before it is presumed lost and another call may probe. Defaults to
+     * `max(cooldownMs, windowMs)`; it is independent of `cooldownMs`, so a zero
+     * or short cooldown never admits concurrent probes. Positive.
+     */
+    probeLeaseMs?: number;
+    /**
+     * Optional initial manual override. `force_open` reports `open` (and blocks
+     * only in `enforce` mode); `force_closed` reports `closed` and never blocks.
+     * Change it at runtime with `InMemoryAdapterCircuitBreaker.setManualOverride`.
+     */
+    manualOverride?: AdapterCircuitBreakerManualOverride;
 }
 interface AdapterImplementation {
     adapterType: string;
@@ -136,6 +537,25 @@ interface ExecuteWithRetryOptions<T> {
     classifyThrownError?: (error: unknown) => AdapterOutcomeKind;
     sleep?: (delayMs: number) => Promise<void>;
     onAttempt?: (attempt: AdapterAttempt<T>) => Promise<void> | void;
+    /**
+     * Optional per-attempt preparation, awaited before the circuit breaker is
+     * consulted and before `execute` (for example, persisting the attempt
+     * number). Put every await a caller needs before the call here, so that
+     * nothing awaits between breaker admission and the external call. If it
+     * throws, no admission is taken and no breaker outcome is recorded; the
+     * error is classified with `classifyThrownError` and retried or rethrown
+     * exactly like an error thrown by `execute`.
+     */
+    prepareAttempt?: (attempt: number, maxAttempts: number) => Promise<void> | void;
+    /**
+     * Optional circuit breaker. When present, `acquire()` is called
+     * immediately before every `execute` call, with no await in between, and every attempt's outcome is
+     * recorded through {@link classifyCircuitBreakerOutcome}. In `enforce` mode
+     * a refused attempt is not executed and {@link AdapterCircuitOpenError} is
+     * thrown; if the breaker opens between attempts, retrying stops and the
+     * same error is thrown. When omitted, behaviour is unchanged.
+     */
+    circuitBreaker?: AdapterCircuitBreaker;
 }
 declare class MissingAdapterRegistrationError extends Error {
     constructor(adapterType: string, operation: string);
@@ -171,4 +591,4 @@ declare function shouldRetryAdapterOutcome(kind: AdapterOutcomeKind, idempotent:
 declare function assertAdapterOutcomeConsistency(result: AdapterExecutionResult): void;
 declare function executeWithAdapterRetry<T>(options: ExecuteWithRetryOptions<T>): Promise<T>;
 
-export { type AcceptedExternalOperation, type AdapterAttempt, type AdapterCircuitBreakerConfig, type AdapterExecutionContext, type AdapterExecutionResult, type AdapterExecutor, type AdapterImplementation, type AdapterOutcomeEvidence, type AdapterOutcomeKind, AdapterRegistry, type AdapterRetryPolicy, type ExecuteWithRetryOptions, MissingAdapterRegistrationError, type ResolvedAdapterRetryPolicy, assertAdapterOutcomeConsistency, classifyAdapterOutcome, executeWithAdapterRetry, getRetryDelayMs, resolveAdapterRetryPolicy, shouldRetryAdapterOutcome };
+export { type AcceptedExternalOperation, type AdapterAttempt, type AdapterCircuitAdmission, type AdapterCircuitBreaker, type AdapterCircuitBreakerConfig, type AdapterCircuitBreakerEvent, type AdapterCircuitBreakerEventListener, type AdapterCircuitBreakerEventReason, type AdapterCircuitBreakerManualOverride, type AdapterCircuitBreakerProvider, AdapterCircuitBreakerRegistry, type AdapterCircuitBreakerRegistryOptions, type AdapterCircuitBreakerScope, AdapterCircuitOpenError, type AdapterCircuitOutcome, type AdapterCircuitState, type AdapterExecutionContext, type AdapterExecutionResult, type AdapterExecutor, type AdapterImplementation, type AdapterOutcomeEvidence, type AdapterOutcomeKind, AdapterRegistry, type AdapterRetryPolicy, type ExecuteWithRetryOptions, InMemoryAdapterCircuitBreaker, type InMemoryAdapterCircuitBreakerOptions, MissingAdapterRegistrationError, type ResolvedAdapterRetryPolicy, assertAdapterCircuitBreakerConfig, assertAdapterOutcomeConsistency, classifyAdapterOutcome, classifyCircuitBreakerOutcome, executeWithAdapterRetry, getRetryDelayMs, isAdapterCircuitOpenError, resolveAdapterRetryPolicy, scopedAdapterCircuitBreakerKey, shouldRetryAdapterOutcome };