@git-stunts/alfred 0.2.0

package/src/policies/retry.js

@@ -0,0 +1,170 @@
+/**
+ * @fileoverview Retry policy for resilient async operations.
+ *
+ * Provides configurable retry logic with multiple backoff strategies
+ * and jitter options to prevent thundering herd problems.
+ *
+ * @module @git-stunts/alfred/policies/retry
+ */
+
+import { SystemClock } from '../utils/clock.js';
+import { createJitter } from '../utils/jitter.js';
+import { RetryExhaustedError } from '../errors.js';
+import { NoopSink } from '../telemetry.js';
+
+/**
+ * @typedef {'constant' | 'linear' | 'exponential'} BackoffStrategy
+ */
+
+/**
+ * @typedef {'none' | 'full' | 'equal' | 'decorrelated'} JitterStrategy
+ */
+
+/**
+ * @typedef {Object} RetryOptions
+ * @property {number} [retries=3] - Maximum number of retry attempts
+ * @property {number} [delay=1000] - Base delay in milliseconds
+ * @property {number} [maxDelay=30000] - Maximum delay cap in milliseconds
+ * @property {BackoffStrategy} [backoff='constant'] - Backoff strategy
+ * @property {JitterStrategy} [jitter='none'] - Jitter strategy
+ * @property {(error: Error) => boolean} [shouldRetry] - Predicate to determine if error is retryable
+ * @property {(error: Error, attempt: number, delay: number) => void} [onRetry] - Callback invoked before each retry
+ * @property {{ now(): number, sleep(ms: number): Promise<void> }} [clock] - Clock for testing
+ * @property {import('../telemetry.js').TelemetrySink} [telemetry] - Telemetry sink
+ */
+
+const DEFAULT_OPTIONS = {
+  retries: 3,
+  delay: 1000,
+  maxDelay: 30000,
+  backoff: 'constant',
+  jitter: 'none'
+};
+
+function calculateBackoff(strategy, baseDelay, attempt) {
+  switch (strategy) {
+    case 'linear':
+      return baseDelay * attempt;
+    case 'exponential':
+      return baseDelay * Math.pow(2, attempt - 1);
+    case 'constant':
+    default:
+      return baseDelay;
+  }
+}
+
+class RetryExecutor {
+  constructor(fn, options) {
+    this.fn = fn;
+    this.options = { ...DEFAULT_OPTIONS, ...options };
+    this.clock = options.clock || new SystemClock();
+    this.telemetry = options.telemetry || new NoopSink();
+    this.applyJitter = createJitter(this.options.jitter);
+    this.prevDelay = this.options.delay;
+  }
+
+  calculateDelay(attempt) {
+    const { backoff, delay: baseDelay, maxDelay, jitter } = this.options;
+    const rawDelay = calculateBackoff(backoff, baseDelay, attempt);
+
+    if (jitter === 'decorrelated') {
+      const actual = this.applyJitter(baseDelay, this.prevDelay, maxDelay);
+      this.prevDelay = actual;
+      return actual;
+    }
+    
+    return Math.min(this.applyJitter(rawDelay), maxDelay);
+  }
+
+  async execute() {
+    const totalAttempts = this.options.retries + 1;
+
+    for (let attempt = 1; attempt <= totalAttempts; attempt++) {
+      const shouldStop = await this.tryAttempt(attempt, totalAttempts);
+      if (shouldStop) {
+        return shouldStop.result;
+      }
+    }
+    
+    // Should be unreachable if logic is correct, but satisfied strict returns
+    throw new Error('Unexpected retry loop termination');
+  }
+
+  async tryAttempt(attempt) {
+    const startTime = this.clock.now();
+    try {
+      const result = await this.fn();
+      this.emitSuccess(attempt, startTime);
+      return { result };
+    } catch (error) {
+      this.handleFailure(error, attempt, startTime);
+      // If we didn't throw in handleFailure, we need to wait
+      // But we need to calculate delay first
+      const delay = this.calculateDelay(attempt);
+      this.emitScheduled(attempt, delay, error);
+      
+      if (this.options.onRetry) {
+        this.options.onRetry(error, attempt, delay);
+      }
+      
+      await this.clock.sleep(delay);
+      return null; // Continue loop
+    }
+  }
+
+  emitSuccess(attempt, startTime) {
+    this.telemetry.emit({
+      type: 'retry.success',
+      timestamp: this.clock.now(),
+      attempt,
+      duration: this.clock.now() - startTime
+    });
+  }
+
+  emitScheduled(attempt, delay, error) {
+    this.telemetry.emit({
+      type: 'retry.scheduled',
+      timestamp: this.clock.now(),
+      attempt,
+      delay,
+      error
+    });
+  }
+
+  handleFailure(error, attempt, startTime) {
+    this.telemetry.emit({
+      type: 'retry.failure',
+      timestamp: this.clock.now(),
+      attempt,
+      error,
+      duration: this.clock.now() - startTime
+    });
+
+    if (this.options.shouldRetry && !this.options.shouldRetry(error)) {
+      throw error;
+    }
+
+    const totalAttempts = this.options.retries + 1;
+    if (attempt >= totalAttempts) {
+      this.telemetry.emit({
+        type: 'retry.exhausted',
+        timestamp: this.clock.now(),
+        attempts: attempt,
+        error
+      });
+      throw new RetryExhaustedError(attempt, error);
+    }
+  }
+}
+
+/**
+ * Executes an async function with configurable retry logic.
+ *
+ * @template T
+ * @param {() => Promise<T>} fn - Async function to execute
+ * @param {RetryOptions} [options={}] - Retry configuration
+ * @returns {Promise<T>} Result of the successful execution
+ */
+export async function retry(fn, options = {}) {
+  return new RetryExecutor(fn, options).execute();
+}

package/src/policies/timeout.js

@@ -0,0 +1,83 @@
+/**
+ * @fileoverview Timeout policy for async operations.
+ *
+ * Provides time-limited execution with AbortSignal support for
+ * cooperative cancellation of in-flight operations.
+ *
+ * @module @git-stunts/alfred/policies/timeout
+ */
+
+import { TimeoutError } from '../errors.js';
+import { NoopSink } from '../telemetry.js';
+
+/**
+ * @typedef {Object} TimeoutOptions
+ * @property {(elapsed: number) => void} [onTimeout] - Callback invoked when timeout occurs
+ * @property {import('../telemetry.js').TelemetrySink} [telemetry] - Telemetry sink
+ */
+
+/**
+ * Executes a function with a timeout limit.
+ *
+ * If the function accepts an argument, an AbortSignal is passed to allow
+ * cooperative cancellation of in-flight operations (e.g., fetch requests).
+ *
+ * @template T
+ * @param {number} ms - Timeout duration in milliseconds
+ * @param {((signal: AbortSignal) => Promise<T>) | (() => Promise<T>)} fn - Function to execute
+ * @param {TimeoutOptions} [options={}] - Optional configuration
+ * @returns {Promise<T>} - Result of the function if it completes in time
+ * @throws {TimeoutError} - If the operation exceeds the timeout
+ *
+ * @example
+ * // Simple usage
+ * const result = await timeout(5000, () => slowOperation());
+ *
+ * @example
+ * // With AbortSignal for fetch
+ * const result = await timeout(5000, (signal) => fetch(url, { signal }));
+ *
+ * @example
+ * // With onTimeout callback
+ * const result = await timeout(5000, () => slowOperation(), {
+ *   onTimeout: (elapsed) => console.log(`Timed out after ${elapsed}ms`)
+ * });
+ */
+export async function timeout(ms, fn, options = {}) {
+  const { onTimeout, telemetry = new NoopSink() } = options;
+  const controller = new AbortController();
+  const startTime = Date.now();
+
+  let timeoutId;
+
+  const timeoutPromise = new Promise((_, reject) => {
+    timeoutId = setTimeout(() => {
+      controller.abort();
+      const elapsed = Date.now() - startTime;
+
+      if (onTimeout) {
+        onTimeout(elapsed);
+      }
+      
+      telemetry.emit({
+        type: 'timeout',
+        timestamp: Date.now(),
+        timeout: ms,
+        elapsed
+      });
+
+      reject(new TimeoutError(ms, elapsed));
+    }, ms);
+  });
+
+  try {
+    // Check if fn expects an argument (signal)
+    const fnAcceptsSignal = fn.length > 0;
+    const operationPromise = fnAcceptsSignal ? fn(controller.signal) : fn();
+
+    const result = await Promise.race([operationPromise, timeoutPromise]);
+    return result;
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}

package/src/policy.js

@@ -0,0 +1,271 @@
+/**
+ * @typedef {(fn: () => Promise<T>) => Promise<T>} Executor
+ * @template T
+ */
+
+/**
+ * @typedef {Object} RetryOptions
+ * @property {number} [retries=3] - Maximum retry attempts
+ * @property {number} [delay=1000] - Base delay in milliseconds
+ * @property {number} [maxDelay=30000] - Maximum delay cap
+ * @property {'constant' | 'linear' | 'exponential'} [backoff='constant'] - Backoff strategy
+ * @property {'none' | 'full' | 'equal' | 'decorrelated'} [jitter='none'] - Jitter strategy
+ * @property {(error: Error) => boolean} [shouldRetry] - Predicate to filter retryable errors
+ * @property {(error: Error, attempt: number, delay: number) => void} [onRetry] - Callback on each retry
+ */
+
+/**
+ * @typedef {Object} CircuitBreakerOptions
+ * @property {number} threshold - Failures before opening
+ * @property {number} duration - How long to stay open (ms)
+ * @property {number} [successThreshold=1] - Successes to close from half-open
+ * @property {(error: Error) => boolean} [shouldTrip] - Which errors count as failures
+ * @property {() => void} [onOpen] - Called when circuit opens
+ * @property {() => void} [onClose] - Called when circuit closes
+ * @property {() => void} [onHalfOpen] - Called when entering half-open
+ */
+
+/**
+ * @typedef {Object} TimeoutOptions
+ * @property {(elapsed: number) => void} [onTimeout] - Called when operation times out
+ */
+
+import { retry } from './policies/retry.js';
+import { circuitBreaker } from './policies/circuit-breaker.js';
+import { timeout } from './policies/timeout.js';
+import { bulkhead } from './policies/bulkhead.js';
+import { compose, fallback, race } from './compose.js';
+
+/**
+ * Fluent API for building resilience policies.
+ *
+ * Provides a chainable, immutable interface for composing retry, circuit breaker,
+ * timeout, and other resilience patterns.
+ *
+ * @example
+ * // Build a resilient policy with retry, timeout, and fallback
+ * const policy = Policy.retry({ retries: 3, backoff: 'exponential' })
+ *   .wrap(Policy.timeout(5000))
+ *   .or(Policy.retry({ retries: 1, delay: 5000 }));
+ *
+ * const result = await policy.execute(() => fetch(url));
+ *
+ * @example
+ * // Race two strategies
+ * const policy = Policy.timeout(1000)
+ *   .race(Policy.timeout(2000));
+ *
+ * // First to complete wins
+ * const result = await policy.execute(() => fetch(url));
+ */
+export class Policy {
+  /**
+   * Creates a new Policy with the given executor function.
+   * @param {Executor<any>} executor - Function that takes fn and returns promise
+   * @private
+   */
+  constructor(executor) {
+    this._executor = executor;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Static Factory Methods
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Creates a Policy that retries failed operations.
+   *
+   * @param {RetryOptions} [options={}] - Retry configuration
+   * @returns {Policy} A new Policy wrapping retry behavior
+   *
+   * @example
+   * const policy = Policy.retry({ retries: 3, backoff: 'exponential' });
+   * await policy.execute(() => unstableOperation());
+   */
+  static retry(options = {}) {
+    return new Policy((fn) => retry(fn, options));
+  }
+
+  /**
+   * Creates a Policy that fails fast when a service is degraded.
+   *
+   * Note: Circuit breakers are stateful. Each call to this factory creates
+   * a new circuit breaker instance with its own state.
+   *
+   * @param {CircuitBreakerOptions} options - Circuit breaker configuration
+   * @returns {Policy} A new Policy wrapping circuit breaker behavior
+   *
+   * @example
+   * const policy = Policy.circuitBreaker({ threshold: 5, duration: 60000 });
+   * await policy.execute(() => callExternalService());
+   */
+  static circuitBreaker(options) {
+    const breaker = circuitBreaker(options);
+    return new Policy((fn) => breaker.execute(fn));
+  }
+
+  /**
+   * Creates a Policy that enforces a time limit on operations.
+   *
+   * @param {number} ms - Timeout in milliseconds
+   * @param {TimeoutOptions} [options={}] - Timeout configuration
+   * @returns {Policy} A new Policy wrapping timeout behavior
+   *
+   * @example
+   * const policy = Policy.timeout(5000);
+   * await policy.execute(() => slowOperation());
+   */
+  static timeout(ms, options = {}) {
+    return new Policy((fn) => timeout(ms, fn, options));
+  }
+
+  /**
+   * Creates a Policy that limits concurrent executions.
+   *
+   * @param {import('./policies/bulkhead.js').BulkheadOptions} options - Bulkhead configuration
+   * @returns {Policy} A new Policy wrapping bulkhead behavior
+   *
+   * @example
+   * const policy = Policy.bulkhead({ limit: 10, queueLimit: 50 });
+   * await policy.execute(() => heavyOperation());
+   */
+  static bulkhead(options) {
+    const limiter = bulkhead(options);
+    return new Policy((fn) => limiter.execute(fn));
+  }
+
+  /**
+   * Creates a no-op Policy that passes through to the function directly.
+   *
+   * Useful as a starting point for building policies or for conditional
+   * composition where you might want to skip certain policies.
+   *
+   * @returns {Policy} A pass-through Policy
+   *
+   * @example
+   * const base = Policy.noop();
+   * const withRetry = shouldRetry ? base.wrap(Policy.retry()) : base;
+   */
+  static noop() {
+    return new Policy((fn) => fn());
+  }
+
+  // ---------------------------------------------------------------------------
+  // Instance Methods (Immutable - return new Policy)
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Wraps this policy with another, creating sequential composition.
+   *
+   * The outer policy (this) wraps the inner policy (other). Execution flows
+   * from outer to inner: this policy is applied first, and when it calls
+   * the function, that function is actually the other policy's execution.
+   *
+   * Equivalent to the `+` operator in ninelives DSL.
+   *
+   * @param {Policy} otherPolicy - The inner policy to wrap
+   * @returns {Policy} A new Policy representing the composition
+   *
+   * @example
+   * // Retry wraps timeout: retries will include timeout behavior
+   * const policy = Policy.retry({ retries: 3 })
+   *   .wrap(Policy.timeout(5000));
+   *
+   * // Execution: retry -> timeout -> fn
+   * await policy.execute(() => fetch(url));
+   */
+  wrap(otherPolicy) {
+    const outer = this._executor;
+    const inner = otherPolicy._executor;
+
+    return new Policy((fn) => {
+      // Compose: outer wraps inner
+      // When outer calls its "fn", that fn is actually inner's execution
+      return compose(
+        { execute: outer },
+        { execute: inner }
+      ).execute(fn);
+    });
+  }
+
+  /**
+   * Creates a fallback composition with another policy.
+   *
+   * If this policy fails, the other policy is tried. This enables graceful
+   * degradation strategies.
+   *
+   * Equivalent to the `|` operator in ninelives DSL.
+   *
+   * @param {Policy} otherPolicy - The fallback policy
+   * @returns {Policy} A new Policy with fallback behavior
+   *
+   * @example
+   * // Try fast, fall back to slow
+   * const policy = Policy.timeout(1000)
+   *   .or(Policy.timeout(10000));
+   *
+   * // If the first times out, try again with longer timeout
+   * await policy.execute(() => fetch(url));
+   */
+  or(otherPolicy) {
+    const primary = this._executor;
+    const secondary = otherPolicy._executor;
+
+    return new Policy((fn) => {
+      return fallback(
+        { execute: primary },
+        { execute: secondary }
+      ).execute(fn);
+    });
+  }
+
+  /**
+   * Races this policy against another, returning the first to complete.
+   *
+   * Both policies execute concurrently. The first successful result wins.
+   * If both fail, the error from the primary (this) policy is thrown.
+   *
+   * Equivalent to the `&` operator in ninelives DSL.
+   *
+   * @param {Policy} otherPolicy - The policy to race against
+   * @returns {Policy} A new Policy with race behavior
+   *
+   * @example
+   * // Race two different strategies
+   * const policy = Policy.retry({ retries: 2, delay: 100 })
+   *   .race(Policy.timeout(500));
+   *
+   * // First to succeed wins
+   * await policy.execute(() => fetch(url));
+   */
+  race(otherPolicy) {
+    const first = this._executor;
+    const second = otherPolicy._executor;
+
+    return new Policy((fn) => {
+      return race(
+        { execute: first },
+        { execute: second }
+      ).execute(fn);
+    });
+  }
+
+  /**
+   * Executes a function through this policy chain.
+   *
+   * @template T
+   * @param {() => Promise<T>} fn - The async function to execute
+   * @returns {Promise<T>} The result of the function
+   * @throws {Error} Any error from the function or policy (e.g., TimeoutError, CircuitOpenError)
+   *
+   * @example
+   * const policy = Policy.retry({ retries: 3 });
+   * const data = await policy.execute(async () => {
+   *   const response = await fetch(url);
+   *   return response.json();
+   * });
+   */
+  execute(fn) {
+    return this._executor(fn);
+  }
+}

package/src/telemetry.js

@@ -0,0 +1,75 @@
+/**
+ * @fileoverview Telemetry system for observing resilience policy behavior.
+ * Provides composable sinks for capturing events.
+ */
+
+/**
+ * @typedef {Object} TelemetryEvent
+ * @property {string} type - Event type (e.g. 'retry', 'circuit.open')
+ * @property {number} timestamp - Event timestamp
+ * @property {Object} [metadata] - Additional event data
+ */
+
+/**
+ * @interface TelemetrySink
+ * @method emit(event: TelemetryEvent) => void
+ */
+
+/**
+ * Sink that stores events in memory. Useful for testing and debugging.
+ * @implements {TelemetrySink}
+ */
+export class InMemorySink {
+  constructor() {
+    this.events = [];
+  }
+
+  emit(event) {
+    this.events.push(event);
+  }
+
+  clear() {
+    this.events = [];
+  }
+}
+
+/**
+ * Sink that logs events to console.
+ * @implements {TelemetrySink}
+ */
+export class ConsoleSink {
+  emit(event) {
+    const { type, timestamp = Date.now(), ...rest } = event;
+    // eslint-disable-next-line no-console
+    console.log(`[${type}] ${new Date(timestamp).toISOString()}`, rest);
+  }
+}
+
+/**
+ * Sink that does nothing. Default.
+ * @implements {TelemetrySink}
+ */
+export class NoopSink {
+  emit(_event) {
+    // No-op
+  }
+}
+
+/**
+ * Sink that broadcasts to multiple other sinks.
+ * @implements {TelemetrySink}
+ */
+export class MultiSink {
+  /**
+   * @param {TelemetrySink[]} sinks
+   */
+  constructor(sinks = []) {
+    this.sinks = sinks;
+  }
+
+  emit(event) {
+    for (const sink of this.sinks) {
+      sink.emit(event);
+    }
+  }
+}