@gkoos/caracal 0.1.0

package/src/core/index.ts

@@ -0,0 +1,36 @@
+export type {
+  AdmitProbeResult,
+  BreakerClassifier,
+  BreakerCoordinator,
+  BreakerIdentity,
+  BreakerOutcome,
+  BreakerSnapshot,
+  BreakerState,
+  DistributedBreakerOptions,
+  LocalBreakerOptions,
+  ObserveResult,
+  SettleProbeResult,
+} from "./circuit-breaker.js"
+export { CircuitOpenError, circuitBreaker } from "./circuit-breaker.js"
+export { operation } from "./operation.js"
+export type { RetryContext, RetryDelay, RetryOptions } from "./retry.js"
+export { retry } from "./retry.js"
+export type { TimeoutOptions } from "./timeout.js"
+export { TimeoutError, timeout } from "./timeout.js"
+export type {
+  Adapter,
+  Classification,
+  EventSink,
+  EventSinks,
+  ExecutionContext,
+  ExecutionMetadata,
+  Next,
+  Operation,
+  OperationCapabilities,
+  OperationEvent,
+  OperationExecuteOptions,
+  OperationOptions,
+  Outcome,
+  OutcomeClassifier,
+  Policy,
+} from "./types.js"

package/src/core/operation.ts

@@ -0,0 +1,174 @@
+import { randomUUID } from "node:crypto"
+
+import {
+  admissionSignal,
+  createClassifier,
+  createExecutionContext,
+} from "./runtime.js"
+import type {
+  Adapter,
+  EventSink,
+  EventSinks,
+  ExecutionMetadata,
+  Next,
+  Operation,
+  OperationCapabilities,
+  OperationEvent,
+  OperationExecuteOptions,
+  OperationOptions,
+  Outcome,
+  Policy,
+} from "./types.js"
+
+const summarizeSuccess = (): Outcome<undefined> => ({
+  status: "success",
+  value: undefined,
+})
+const summarizeFailure = (error: unknown): Outcome<undefined> => ({
+  status: "failure",
+  error,
+})
+
+function immutableCapabilities(
+  capabilities: OperationCapabilities,
+): OperationCapabilities {
+  return Object.freeze({ ...capabilities })
+}
+
+function immutableMetadata(
+  metadata: Readonly<Record<string, unknown>> | undefined,
+): ExecutionMetadata {
+  return Object.freeze({ ...(metadata ?? {}) })
+}
+
+function normalizeSinks(events: EventSinks | undefined): readonly EventSink[] {
+  if (events === undefined) {
+    return []
+  }
+
+  return "emit" in events ? [events] : events
+}
+
+function emit(sinks: readonly EventSink[], event: OperationEvent): void {
+  for (const sink of sinks) {
+    try {
+      sink.emit(event)
+    } catch {
+      // Observability must not modify resilience execution.
+    }
+  }
+}
+
+function validateName(name: string, kind: "operation" | "policy"): void {
+  if (name.trim().length === 0) {
+    throw new Error(`${kind} name must not be empty`)
+  }
+}
+
+function createPipeline<Result>(
+  policies: readonly Policy[],
+  adapter: Next<Result>,
+): Next<Result> {
+  return policies.reduceRight<Next<Result>>(
+    (next, policy) => async (context) => policy.execute(context, next),
+    adapter,
+  )
+}
+
+function invokeAdapter<Args, Result>(
+  adapter: Adapter<Args, Result>,
+  args: Args,
+  sinks: readonly EventSink[],
+): Next<Result> {
+  return async (context) => {
+    admissionSignal(context)?.throwIfAborted()
+    emit(sinks, { type: "attempt.started", at: Date.now(), context })
+
+    try {
+      const value = await adapter.execute(args, context)
+      const outcome: Outcome<Result> = { status: "success", value }
+      const classification = context.classify(outcome)
+      emit(sinks, {
+        type: "attempt.settled",
+        at: Date.now(),
+        context,
+        outcome: summarizeSuccess(),
+        classification,
+      })
+      return value
+    } catch (error) {
+      const outcome: Outcome<Result> = { status: "failure", error }
+      const classification = context.classify(outcome)
+      emit(sinks, {
+        type: "attempt.settled",
+        at: Date.now(),
+        context,
+        outcome: summarizeFailure(error),
+        classification,
+      })
+      throw error
+    }
+  }
+}
+
+/** Creates a named, protocol-agnostic operation. */
+export function operation<Args, Result>(
+  options: OperationOptions<Args, Result>,
+): Operation<Args, Result> {
+  validateName(options.name, "operation")
+  for (const policy of options.policies ?? []) {
+    validateName(policy.name, "policy")
+  }
+
+  const policies = Object.freeze([...(options.policies ?? [])])
+  const sinks = Object.freeze(normalizeSinks(options.events))
+
+  return Object.freeze({
+    name: options.name,
+    async execute(
+      args: Args,
+      executeOptions: OperationExecuteOptions = {},
+    ): Promise<Result> {
+      const capabilities = options.adapter.capabilities(args)
+      const context = createExecutionContext(
+        {
+          operationName: options.name,
+          executionId: executeOptions.executionId ?? randomUUID(),
+          signal: executeOptions.signal,
+          metadata: immutableMetadata(executeOptions.metadata),
+          capabilities: immutableCapabilities(capabilities),
+          classify: createClassifier(options.adapter.classify),
+        },
+        sinks,
+      )
+      const adapter = createPipeline(
+        policies.filter((policy) => policy.phase === "attempt"),
+        invokeAdapter(options.adapter, args, sinks),
+      )
+      const pipeline = createPipeline(
+        policies.filter((policy) => policy.phase !== "attempt"),
+        adapter,
+      )
+
+      emit(sinks, { type: "execution.started", at: Date.now(), context })
+      try {
+        const value = await pipeline(context)
+        emit(sinks, {
+          type: "execution.settled",
+          at: Date.now(),
+          context,
+          outcome: summarizeSuccess(),
+        })
+        return value
+      } catch (error) {
+        emit(sinks, {
+          type: "execution.settled",
+          at: Date.now(),
+          context,
+          outcome: summarizeFailure(error),
+        })
+        throw error
+      }
+    },
+  })
+}

package/src/core/retry.ts

@@ -0,0 +1,204 @@
+import { admissionSignal, emitRuntimeEvent, nextAttempt } from "./runtime.js"
+import type {
+  Classification,
+  ExecutionContext,
+  ExecutionMetadata,
+  Next,
+  OperationCapabilities,
+  Outcome,
+  Policy,
+} from "./types.js"
+
+/**
+ * Settled-attempt information passed to a custom `delay` function.
+ *
+ * `result` and `error` are conveniences over `outcome`; the core never
+ * interprets them, so an adapter-specific helper can pace retries from
+ * protocol feedback (for example an HTTP `Retry-After` header) without
+ * leaking protocol types into the core.
+ */
+export interface RetryContext {
+  readonly outcome: Outcome<unknown>
+  readonly result: unknown
+  readonly error: unknown
+  readonly capabilities: OperationCapabilities
+  readonly metadata: ExecutionMetadata
+}
+
+export type RetryDelay =
+  | number
+  | ((attempt: number, context: RetryContext) => number)
+
+export interface RetryOptions {
+  readonly maxAttempts: number
+  readonly delay?: RetryDelay
+}
+
+function throwIfAborted(signal: AbortSignal | undefined): void {
+  if (!signal?.aborted) {
+    return
+  }
+
+  throw (
+    signal.reason ?? new DOMException("The operation was aborted", "AbortError")
+  )
+}
+
+function retryContext(
+  context: ExecutionContext,
+  outcome: Outcome<unknown>,
+): RetryContext {
+  return {
+    outcome,
+    result: outcome.status === "success" ? outcome.value : undefined,
+    error: outcome.status === "failure" ? outcome.error : undefined,
+    capabilities: context.capabilities,
+    metadata: context.metadata,
+  }
+}
+
+function delayFor(
+  options: RetryOptions,
+  context: ExecutionContext,
+  attempt: number,
+  outcome: Outcome<unknown>,
+): number {
+  const configured = options.delay
+  const delay =
+    typeof configured === "function"
+      ? configured(attempt, retryContext(context, outcome))
+      : (configured ?? 0)
+  if (!Number.isFinite(delay) || delay < 0) {
+    throw new RangeError("retry delay must be a finite non-negative number")
+  }
+
+  return delay
+}
+
+function wait(delayMs: number, signal: AbortSignal | undefined): Promise<void> {
+  if (delayMs === 0) {
+    throwIfAborted(signal)
+    return Promise.resolve()
+  }
+
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(done, delayMs)
+
+    function done(): void {
+      signal?.removeEventListener("abort", aborted)
+      resolve()
+    }
+
+    function aborted(): void {
+      clearTimeout(timer)
+      reject(
+        signal?.reason ??
+          new DOMException("The operation was aborted", "AbortError"),
+      )
+    }
+
+    if (signal?.aborted) {
+      aborted()
+      return
+    }
+
+    signal?.addEventListener("abort", aborted, { once: true })
+  })
+}
+
+function summarized<Result>(outcome: Outcome<Result>): Outcome<undefined> {
+  return outcome.status === "success"
+    ? { status: "success", value: undefined }
+    : { status: "failure", error: outcome.error }
+}
+
+function classification<Result>(
+  context: ExecutionContext,
+  outcome: Outcome<Result>,
+): Classification {
+  return context.classify(outcome)
+}
+
+/** Retries adapter-classified failures within a single logical invocation. */
+export function retry(options: RetryOptions): Policy {
+  if (!Number.isInteger(options.maxAttempts) || options.maxAttempts < 1) {
+    throw new RangeError("maxAttempts must be a positive integer")
+  }
+
+  return Object.freeze({
+    name: "retry",
+    async execute<Result>(
+      initialContext: ExecutionContext,
+      next: Next<Result>,
+    ): Promise<Result> {
+      let context = initialContext
+
+      for (;;) {
+        throwIfAborted(admissionSignal(context))
+
+        try {
+          const value = await next(context)
+          const outcome: Outcome<Result> = { status: "success", value }
+          const outcomeClassification = classification(context, outcome)
+          if (
+            outcomeClassification !== "retryable" ||
+            context.capabilities.replay !== "safe"
+          ) {
+            return value
+          }
+
+          if (context.attempt >= options.maxAttempts) {
+            emitRuntimeEvent(context, {
+              type: "retry.exhausted",
+              outcome: summarized(outcome),
+              classification: outcomeClassification,
+            })
+            return value
+          }
+
+          const delayMs = delayFor(options, context, context.attempt, outcome)
+          emitRuntimeEvent(context, {
+            type: "retry.scheduled",
+            nextAttempt: context.attempt + 1,
+            delayMs,
+            outcome: summarized(outcome),
+            classification: outcomeClassification,
+          })
+          await wait(delayMs, admissionSignal(context))
+          context = nextAttempt(context)
+        } catch (error) {
+          const outcome: Outcome<Result> = { status: "failure", error }
+          const outcomeClassification = classification(context, outcome)
+
+          if (
+            admissionSignal(context)?.aborted ||
+            context.capabilities.replay !== "safe" ||
+            outcomeClassification !== "retryable"
+          ) {
+            throw error
+          }
+
+          if (context.attempt >= options.maxAttempts) {
+            emitRuntimeEvent(context, {
+              type: "retry.exhausted",
+              outcome: summarized(outcome),
+              classification: outcomeClassification,
+            })
+            throw error
+          }
+
+          const delayMs = delayFor(options, context, context.attempt, outcome)
+          emitRuntimeEvent(context, {
+            type: "retry.scheduled",
+            nextAttempt: context.attempt + 1,
+            delayMs,
+            outcome: summarized(outcome),
+            classification: outcomeClassification,
+          })
+          await wait(delayMs, admissionSignal(context))
+          context = nextAttempt(context)
+        }
+      }
+    },
+  })
+}

package/src/core/runtime.ts

@@ -0,0 +1,123 @@
+import type {
+  Classification,
+  EventSink,
+  ExecutionContext,
+  OperationEvent,
+  Outcome,
+  OutcomeClassifier,
+} from "./types.js"
+
+const eventSinks = Symbol("caracal.eventSinks")
+const admissionSignals = new WeakMap<ExecutionContext, AbortSignal>()
+export function admissionSignal(
+  context: ExecutionContext,
+): AbortSignal | undefined {
+  const admission = admissionSignals.get(context)
+  return admission && context.signal
+    ? AbortSignal.any([admission, context.signal])
+    : (admission ?? context.signal)
+}
+export function withAdmissionSignal(
+  context: ExecutionContext,
+  signal: AbortSignal,
+): ExecutionContext {
+  const derived = attachRuntime(
+    { ...context },
+    runtimeContext(context)[eventSinks] ?? [],
+  )
+  const previous = admissionSignal(context)
+  admissionSignals.set(
+    derived,
+    previous ? AbortSignal.any([previous, signal]) : signal,
+  )
+  return derived
+}
+function inheritAdmission(
+  source: ExecutionContext,
+  target: ExecutionContext,
+): ExecutionContext {
+  const signal = admissionSignals.get(source)
+  if (signal) admissionSignals.set(target, signal)
+  return target
+}
+
+type EventWithoutRuntimeFields = OperationEvent extends infer Event
+  ? Event extends OperationEvent
+    ? Omit<Event, "at" | "context">
+    : never
+  : never
+
+type RuntimeExecutionContext = ExecutionContext & {
+  readonly [eventSinks]: readonly EventSink[]
+}
+
+function runtimeContext(context: ExecutionContext): RuntimeExecutionContext {
+  return context as RuntimeExecutionContext
+}
+
+function attachRuntime(
+  values: ExecutionContext,
+  sinks: readonly EventSink[],
+): ExecutionContext {
+  const context = values as RuntimeExecutionContext
+  Object.defineProperty(context, eventSinks, { value: sinks })
+  return Object.freeze(context)
+}
+
+export function createExecutionContext(
+  values: Omit<ExecutionContext, "attempt">,
+  sinks: readonly EventSink[],
+): ExecutionContext {
+  return attachRuntime({ attempt: 1, ...values }, sinks)
+}
+
+export function nextAttempt(context: ExecutionContext): ExecutionContext {
+  return inheritAdmission(
+    context,
+    attachRuntime(
+      { ...context, attempt: context.attempt + 1 },
+      runtimeContext(context)[eventSinks] ?? [],
+    ),
+  )
+}
+
+export function withSignal(
+  context: ExecutionContext,
+  signal: AbortSignal | undefined,
+): ExecutionContext {
+  return inheritAdmission(
+    context,
+    attachRuntime(
+      { ...context, signal },
+      runtimeContext(context)[eventSinks] ?? [],
+    ),
+  )
+}
+
+export function emitRuntimeEvent(
+  context: ExecutionContext,
+  event: EventWithoutRuntimeFields,
+): void {
+  const sinks = runtimeContext(context)[eventSinks] ?? []
+  const fullEvent = { ...event, at: Date.now(), context } as OperationEvent
+
+  for (const sink of sinks) {
+    try {
+      sink.emit(fullEvent)
+    } catch {
+      // Observability must not modify resilience execution.
+    }
+  }
+}
+
+export function createClassifier<Result>(
+  classify: ((outcome: Outcome<Result>) => Classification) | undefined,
+): OutcomeClassifier {
+  return (outcome) => {
+    if (classify === undefined) {
+      return outcome.status === "success" ? "success" : "failure"
+    }
+
+    return classify(outcome as Outcome<Result>)
+  }
+}

package/src/core/scope-state-cache.ts

@@ -0,0 +1,50 @@
+/**
+ * In-process record of the scopes whose last known distributed state was
+ * non-closed.
+ *
+ * It exists for one decision only: when `readState()` fails, a scope last seen
+ * OPEN or HALF_OPEN must fail closed, because admitting work to a known-open
+ * breaker removes the protection it exists to provide.
+ *
+ * CLOSED states are deliberately not retained. A missing entry and a CLOSED
+ * entry are treated identically by that decision, so storing CLOSED would grow
+ * this map with every scope ever observed while changing nothing.
+ *
+ * Entries are keyed by `(operation, scope)` to match the coordinator identity
+ * `(name, operation, scope)`: one policy instance shared by several operations
+ * must not read another operation's last known state.
+ */
+
+/** Non-closed breaker state retained in process memory. */
+export type RetainedScopeState = "open" | "half-open"
+
+export interface ScopeStateCache {
+  remember(operation: string, scope: string, state: RetainedScopeState): void
+  forget(operation: string, scope: string): void
+  read(operation: string, scope: string): RetainedScopeState | undefined
+  /** Number of retained scopes. Internal; used by tests. */
+  size(): number
+}
+
+export function createScopeStateCache(): ScopeStateCache {
+  const retained = new Map<string, RetainedScopeState>()
+  // JSON encoding keeps the parts unambiguous even if a name contains the
+  // separator or other special characters.
+  const keyFor = (operation: string, scope: string) =>
+    JSON.stringify([operation, scope])
+
+  return {
+    remember(operation, scope, state) {
+      retained.set(keyFor(operation, scope), state)
+    },
+    forget(operation, scope) {
+      retained.delete(keyFor(operation, scope))
+    },
+    read(operation, scope) {
+      return retained.get(keyFor(operation, scope))
+    },
+    size() {
+      return retained.size
+    },
+  }
+}

package/src/core/timeout.ts

@@ -0,0 +1,73 @@
+import { emitRuntimeEvent, withAdmissionSignal, withSignal } from "./runtime.js"
+import type { ExecutionContext, Next, Policy } from "./types.js"
+
+export class TimeoutError extends Error {
+  readonly timeoutMs: number
+
+  constructor(timeoutMs: number) {
+    super(`Operation timed out after ${timeoutMs}ms`)
+    this.name = "TimeoutError"
+    this.timeoutMs = timeoutMs
+  }
+}
+
+export interface TimeoutOptions {
+  readonly ms: number
+}
+
+function combineSignals(
+  external: AbortSignal | undefined,
+  timeoutController: AbortController,
+): AbortSignal {
+  if (external === undefined) {
+    return timeoutController.signal
+  }
+
+  return AbortSignal.any([external, timeoutController.signal])
+}
+
+/** Bounds caller wait time and requests cancellation only when the adapter supports it. */
+export function timeout(options: TimeoutOptions): Policy {
+  if (!Number.isFinite(options.ms) || options.ms <= 0) {
+    throw new RangeError("timeout ms must be a finite positive number")
+  }
+
+  return Object.freeze({
+    name: "timeout",
+    async execute<Result>(
+      context: ExecutionContext,
+      next: Next<Result>,
+    ): Promise<Result> {
+      const timeoutError = new TimeoutError(options.ms)
+      const supportsAbort = context.capabilities.abort === "supported"
+      const controller = new AbortController()
+      const attemptContext = withAdmissionSignal(
+        supportsAbort
+          ? withSignal(context, combineSignals(context.signal, controller))
+          : context,
+        controller.signal,
+      )
+      let timer: ReturnType<typeof setTimeout> | undefined
+
+      const timeoutPromise = new Promise<never>((_resolve, reject) => {
+        timer = setTimeout(() => {
+          controller.abort(timeoutError)
+          emitRuntimeEvent(context, {
+            type: "timeout.triggered",
+            timeoutMs: options.ms,
+            abortRequested: supportsAbort,
+          })
+          reject(timeoutError)
+        }, options.ms)
+      })
+
+      try {
+        return await Promise.race([next(attemptContext), timeoutPromise])
+      } finally {
+        if (timer !== undefined) {
+          clearTimeout(timer)
+        }
+      }
+    },
+  })
+}