breaker_machines 0.1.0

data/sig/breaker_machines/circuit.rbs

@@ -0,0 +1,154 @@
+module BreakerMachines
+  class Circuit
+    include StateManagement
+    include Configuration
+    include Execution
+    include Introspection
+    include Callbacks
+
+    # Instance variables from Configuration module
+    @name: String
+    @config: Hash[Symbol, untyped]
+    @storage: _StorageBackend?
+    @metrics: _MetricsRecorder?
+    @opened_at: Concurrent::AtomicReference[Float?]
+    @half_open_attempts: Concurrent::AtomicFixnum
+    @half_open_successes: Concurrent::AtomicFixnum
+    @mutex: Concurrent::ReentrantReadWriteLock
+    @last_failure_at: Concurrent::AtomicReference[Float?]
+    @last_error: Concurrent::AtomicReference[StandardError?]
+
+    # State machine status (from StateManagement)
+    attr_reader status: (:open | :closed | :half_open)
+  end
+
+  module StateManagement
+    interface _StateManagementState
+      def status: () -> (:open | :closed | :half_open)
+      def status=: (:open | :closed | :half_open value) -> void
+      def status_name: () -> (:open | :closed | :half_open)
+      def open?: () -> bool
+      def closed?: () -> bool
+      def half_open?: () -> bool
+      def trip: () -> bool
+      def attempt_recovery: () -> bool
+      def reset: () -> bool
+      def force_open: () -> bool
+      def force_close: () -> bool
+    end
+
+    def self.included: (singleton(Circuit) base) -> void
+
+    private
+
+    def on_circuit_open: () -> void
+    def on_circuit_close: () -> void
+    def on_circuit_half_open: () -> void
+    def restore_status_from_storage: () -> void
+    def reset_timeout_elapsed?: () -> bool
+    def monotonic_time: () -> Float
+  end
+
+  module Configuration
+    extend ActiveSupport::Concern
+
+    interface _ConfigurationMethods
+      def name: () -> String
+      def config: () -> Hash[Symbol, untyped]
+      def opened_at: () -> Concurrent::AtomicReference[Float?]
+    end
+
+    type storage_type = Storage::Base | Storage::Memory | Storage::BucketMemory | Storage::Null
+    type metrics_type = untyped
+    type callback_type = Proc | nil
+    type fallback_type = Proc | Array[Proc | untyped] | untyped
+
+    type circuit_config = {
+      failure_threshold: Integer,
+      failure_window: Integer,
+      success_threshold: Integer,
+      timeout: Integer?,
+      reset_timeout: Integer,
+      reset_timeout_jitter: Float,
+      half_open_calls: Integer,
+      storage: storage_type?,
+      metrics: metrics_type?,
+      fallback: fallback_type?,
+      on_open: callback_type,
+      on_close: callback_type,
+      on_half_open: callback_type,
+      on_reject: callback_type,
+      exceptions: Array[Class],
+      owner: untyped
+    }
+
+    def initialize: (String name, ?circuit_config options) -> void
+
+    private
+
+    def default_config: () -> circuit_config
+    def create_default_storage: () -> storage_type
+  end
+
+  module Execution
+    def call: [T] () { () -> T } -> untyped
+    def wrap: [T] () { () -> T } -> untyped
+
+    private
+
+    def handle_open_status: () { () -> untyped } -> untyped
+    def handle_half_open_status: () { () -> untyped } -> untyped
+    def handle_closed_status: () { () -> untyped } -> untyped
+    def execute_call: () { () -> untyped } -> untyped
+    def reject_call: () -> untyped
+    def handle_success: () -> void
+    def handle_failure: () -> void
+    def failure_threshold_exceeded?: () -> bool
+    def success_threshold_reached?: () -> bool
+    def record_success: (Float duration) -> void
+    def record_failure: (Float duration, ?StandardError? error) -> void
+  end
+
+  module Introspection
+    type stats_hash = {
+      state: (:open | :closed | :half_open),
+      failure_count: Integer,
+      success_count: Integer,
+      last_failure_at: Float?,
+      opened_at: Float?,
+      half_open_attempts: Integer,
+      half_open_successes: Integer
+    }
+
+    type error_info = {
+      class: String,
+      message: String,
+      occurred_at: Float
+    }
+
+    type circuit_hash = {
+      name: String,
+      state: (:open | :closed | :half_open),
+      stats: stats_hash,
+      config: Hash[Symbol, untyped],
+      event_log: Array[untyped],
+      last_error: error_info?
+    }
+
+    def stats: () -> stats_hash
+    def configuration: () -> Hash[Symbol, untyped]
+    def event_log: (?limit: Integer) -> Array[untyped]?
+    def last_error: () -> StandardError?
+    def to_h: () -> circuit_hash
+    def summary: () -> String
+    def last_error_info: () -> error_info?
+  end
+
+  module Callbacks
+    private
+
+    def invoke_callback: (Symbol callback_name) -> void
+    def invoke_fallback: (StandardError error) -> untyped
+    def invoke_single_fallback: (Proc | untyped fallback, StandardError error) -> untyped
+  end
+end

data/sig/breaker_machines/console.rbs

@@ -0,0 +1,32 @@
+module BreakerMachines
+  class Console
+    @running: bool
+
+    def self.start: () -> void
+
+    def initialize: () -> void
+    def run: () -> void
+
+    private
+
+    def print_header: () -> void
+    def print_help: () -> void
+    def print_prompt: () -> void
+    def process_command: (String command) -> void
+
+    # Command methods
+    def list_circuits: () -> void
+    def show_stats: () -> void
+    def show_circuit: (String? name) -> void
+    def show_events: (String? name, Integer limit) -> void
+    def reset_circuit: (String? name) -> void
+    def force_open_circuit: (String? name) -> void
+    def force_close_circuit: (String? name) -> void
+    def generate_report: () -> void
+    def cleanup_registry: () -> void
+
+    # Utility methods
+    def colorize_state: (Symbol state) -> String
+    def colorize_event_type: (Symbol type) -> String
+  end
+end

data/sig/breaker_machines/dsl.rbs

@@ -0,0 +1,50 @@
+module BreakerMachines
+  module DSL
+    extend ActiveSupport::Concern
+
+    @instance_registries: Concurrent::Map[Class, Concurrent::Array[WeakRef[untyped]]]
+
+    module ClassMethods
+      @circuits: Hash[Symbol, Hash[Symbol, untyped]]
+
+      def instance_registry: () -> Concurrent::Array[WeakRef[untyped]]
+      def cleanup_instance_registry: () -> void
+      def circuit: (Symbol name) ?{ (CircuitBuilder) -> void } -> Hash[Symbol, untyped]
+      def circuits: () -> Hash[Symbol, Hash[Symbol, untyped]]
+      def circuit_definitions: () -> Hash[Symbol, Hash[Symbol, untyped]]
+      def reset_all_circuits: () -> void
+      def circuit_stats: () -> Hash[Symbol, { total: Integer, by_state: Hash[Symbol, Integer] }]
+    end
+
+    def circuit: (Symbol name) -> Circuit
+    def circuit_instances: () -> Hash[Symbol, Circuit]
+    def circuits_summary: () -> Hash[Symbol, String]
+    def circuits_report: () -> Hash[Symbol, untyped]
+    def reset_all_circuits: () -> void
+
+    class CircuitBuilder
+      attr_reader config: Hash[Symbol, untyped]
+
+      def initialize: () -> void
+
+      # Configuration methods
+      def threshold: (?failures: Integer?, ?within: Integer, ?successes: Integer?) -> void
+      def reset_after: (Integer duration, ?jitter: Float?) -> void
+      def timeout: (Integer duration) -> void
+      def half_open_requests: (Integer count) -> void
+      def storage: ((:memory | :bucket_memory | :redis | Class | Storage::Base) backend, **untyped) -> void
+      def metrics: (?untyped recorder) ?{ () -> void } -> void
+      def fallback: (?untyped value) ?{ (StandardError) -> untyped } -> void
+      def on_open: () { () -> void } -> void
+      def on_close: () { () -> void } -> void
+      def on_half_open: () { () -> void } -> void
+      def on_reject: () { () -> void } -> void
+      def notify: (Symbol service, ?String? url, ?events: Array[Symbol], **untyped options) -> void
+      def handle: (*Class exceptions) -> void
+
+      # Advanced features
+      def backends: (Array[untyped] list) -> void
+      def parallel_calls: (Integer count, ?timeout: Integer?) -> void
+    end
+  end
+end

data/sig/breaker_machines/errors.rbs

@@ -0,0 +1,24 @@
+module BreakerMachines
+  class Error < StandardError
+  end
+
+  class CircuitOpenError < Error
+    attr_reader circuit_name: String
+    attr_reader opened_at: Float?
+
+    def initialize: (String circuit_name, ?Float? opened_at) -> void
+  end
+
+  class CircuitTimeoutError < Error
+    attr_reader circuit_name: String
+    attr_reader timeout: Numeric
+
+    def initialize: (String circuit_name, Numeric timeout) -> void
+  end
+
+  class ConfigurationError < Error
+  end
+
+  class StorageError < Error
+  end
+end

data/sig/breaker_machines/interfaces.rbs

@@ -0,0 +1,46 @@
+module BreakerMachines
+  # Interface for objects that can record metrics
+  interface _MetricsRecorder
+    def record_success: (String circuit_name, Float duration) -> void
+    def record_failure: (String circuit_name, Float duration) -> void
+    def record_rejection: (String circuit_name) -> void
+  end
+
+  # Interface for storage backends
+  interface _StorageBackend
+    def get_status: (String circuit_name) -> status_record?
+    def set_status: (String circuit_name, circuit_state status, ?Float? opened_at) -> void
+    def record_success: (String circuit_name, Float duration) -> void
+    def record_failure: (String circuit_name, Float duration) -> void
+    def success_count: (String circuit_name, Integer window_seconds) -> Integer
+    def failure_count: (String circuit_name, Integer window_seconds) -> Integer
+    def clear: (String circuit_name) -> void
+    def clear_all: () -> void
+  end
+
+  # Interface for advanced storage backends with event logging
+  interface _AdvancedStorageBackend
+    def record_success: (String circuit_name, ?Float? duration) -> void
+    def record_failure: (String circuit_name, ?Float? duration) -> void
+    def success_count: (String circuit_name, ?Integer? window) -> Integer
+    def failure_count: (String circuit_name, ?Integer? window) -> Integer
+    def get_status: (String circuit_name) -> Hash[Symbol, untyped]?
+    def set_status: (String circuit_name, circuit_state status, ?Float? opened_at) -> void
+    def clear: (String circuit_name) -> void
+    def record_event_with_details: (String circuit_name, event_type event_type, Float duration, ?Hash[Symbol, untyped] details) -> void
+    def event_log: (String circuit_name, ?Integer limit) -> Array[event_record]
+  end
+
+  # Interface for circuit-like objects
+  interface _CircuitLike
+    def name: () -> String
+    def call: () { () -> untyped } -> untyped
+    def wrap: () { () -> untyped } -> untyped
+    def status_name: () -> circuit_state
+    def open?: () -> bool
+    def closed?: () -> bool
+    def half_open?: () -> bool
+    def reset: () -> bool
+    def stats: () -> Hash[Symbol, untyped]
+  end
+end

data/sig/breaker_machines/registry.rbs

@@ -0,0 +1,30 @@
+module BreakerMachines
+  class Registry
+    include Singleton
+
+    @circuits: Concurrent::Map[Integer, WeakRef[Circuit]]
+    @mutex: Mutex
+    @registration_count: Integer
+    @cleanup_interval: Integer
+
+    def initialize: () -> void
+
+    # Circuit management
+    def register: (Circuit circuit) -> void
+    def unregister: (Circuit circuit) -> void
+    def all_circuits: () -> Array[Circuit]
+    def find_by_name: (Symbol name) -> Array[Circuit]
+
+    # Reporting
+    def stats_summary: () -> { total: Integer, by_state: Hash[Symbol, Integer], by_name: Hash[Symbol, Integer] }
+    def detailed_report: () -> Array[Hash[Symbol, untyped]]
+
+    # Maintenance
+    def clear: () -> void
+    def cleanup_dead_references: () -> void
+
+    private
+
+    def cleanup_dead_references_unsafe: () -> void
+  end
+end

data/sig/breaker_machines/storage.rbs

@@ -0,0 +1,65 @@
+module BreakerMachines
+  module Storage
+    class Base
+      @options: Hash[Symbol, untyped]
+
+      def initialize: (**untyped options) -> void
+
+      # Status management
+      def get_status: (String circuit_name) -> { status: (:open | :closed | :half_open), opened_at: Float? }?
+      def set_status: (String circuit_name, (:open | :closed | :half_open) status, ?Float? opened_at) -> void
+
+      # Metrics tracking
+      def record_success: (String circuit_name, Float duration) -> void
+      def record_failure: (String circuit_name, Float duration) -> void
+      def success_count: (String circuit_name, Integer window_seconds) -> Integer
+      def failure_count: (String circuit_name, Integer window_seconds) -> Integer
+
+      # Cleanup
+      def clear: (String circuit_name) -> void
+      def clear_all: () -> void
+    end
+
+    class Memory < Base
+      @circuits: Concurrent::Map[String, untyped]
+      @events: Concurrent::Map[String, Concurrent::Array[untyped]]
+      @event_logs: Concurrent::Map[String, Concurrent::Array[untyped]]
+      @max_events: Integer
+
+      def initialize: (**untyped options) -> void
+      def record_event_with_details: (String circuit_name, (:success | :failure | :state_change) type, Float duration, ?error: StandardError?, ?new_state: (:open | :closed | :half_open)?) -> void
+      def event_log: (String circuit_name, Integer limit) -> Array[event_record]
+
+      private
+
+      def record_event: (String circuit_name, (:success | :failure) type, Float duration) -> void
+      def count_events: (String circuit_name, (:success | :failure) type, Integer window_seconds) -> Integer
+      def monotonic_time: () -> Float
+    end
+
+    class BucketMemory < Base
+      @buckets: Concurrent::Map[String, untyped]
+      @bucket_duration: Integer
+      @bucket_count: Integer
+      @lock: Concurrent::ReentrantReadWriteLock
+      @last_cleanup: Concurrent::AtomicReference[Float]
+      @cleanup_interval: Integer
+
+      def record_event_with_details: (String circuit_name, (:success | :failure | :state_change) event_type, Float duration, ?Hash[Symbol, untyped] details) -> void
+      def event_log: (String circuit_name, ?Integer limit) -> Array[event_record]
+
+      private
+
+      def circuit_buckets: (String circuit_name) -> Hash[Symbol, untyped]
+      def current_bucket_index: () -> Integer
+      def bucket_indices_for_window: (Integer window_seconds) -> Array[Integer]
+      def cleanup_old_buckets: (Hash[Symbol, untyped] buckets) -> void
+      def maybe_cleanup_all_buckets: () -> void
+    end
+
+    class Null < Base
+      def record_event_with_details: (String circuit_name, Symbol event_type, Float duration, ?Hash[Symbol, untyped] metadata) -> void
+      def event_log: (String circuit_name, ?Integer limit) -> Array[untyped]
+    end
+  end
+end

data/sig/breaker_machines/types.rbs

@@ -0,0 +1,97 @@
+# Common type aliases used throughout BreakerMachines
+
+# External dependencies type declarations not included in their gems
+module Concurrent
+  class AtomicReference[T]
+    def initialize: (?T initial_value) -> void
+    def value: () -> T
+    def value=: (T value) -> T
+    def get: () -> T
+    def set: (T value) -> T
+  end
+
+  class AtomicFixnum
+    def initialize: (?Integer initial_value) -> void
+    def value: () -> Integer
+    def value=: (Integer value) -> Integer
+    def increment: (?Integer delta) -> Integer
+    def decrement: (?Integer delta) -> Integer
+  end
+
+  class ReentrantReadWriteLock
+    def initialize: () -> void
+    def with_read_lock: [T] () { () -> T } -> T
+    def with_write_lock: [T] () { () -> T } -> T
+  end
+end
+
+class WeakRef[T]
+  def initialize: (T object) -> void
+  def weakref_alive?: () -> bool
+  def __getobj__: () -> T
+end
+
+module Zeitwerk
+  class Loader
+    def push_dir: (String path) -> void
+    def setup: () -> void
+    def eager_load: () -> void
+  end
+end
+
+module BreakerMachines
+  # Circuit states
+  type circuit_state = :open | :closed | :half_open
+
+  # Event types
+  type event_type = :success | :failure | :state_change | :rejection
+
+  # Callback names
+  type callback_name = :on_open | :on_close | :on_half_open | :on_reject
+
+  # Storage backend symbols
+  type storage_backend = :memory | :bucket_memory | :null | :redis
+
+  # Generic callback proc
+  type callback_proc = Proc | nil
+
+  # Fallback can be a proc, array of procs/values, or any static value
+  type fallback_value = Proc | Array[Proc | untyped] | untyped
+
+  # Options hash for circuits
+  type circuit_options = {
+    failure_threshold: Integer?,
+    failure_window: Integer?,
+    success_threshold: Integer?,
+    timeout: Integer?,
+    reset_timeout: Integer?,
+    reset_timeout_jitter: Float?,
+    half_open_calls: Integer?,
+    storage: (Storage::Base | storage_backend | Class)?,
+    metrics: untyped,
+    fallback: fallback_value?,
+    on_open: callback_proc,
+    on_close: callback_proc,
+    on_half_open: callback_proc,
+    on_reject: callback_proc,
+    exceptions: Array[Class]?,
+    owner: untyped
+  }
+
+  # Event record structure
+  type event_record = {
+    timestamp: Float,
+    type: event_type,
+    duration: Float,
+    duration_ms: Float?,
+    error_class: String?,
+    new_state: circuit_state?,
+    details: Hash[Symbol, untyped]?
+  }
+
+  # Status record from storage
+  type status_record = {
+    status: circuit_state,
+    opened_at: Float?
+  }
+end

data/sig/breaker_machines.rbs

@@ -0,0 +1,30 @@
+module BreakerMachines
+  VERSION: String
+
+  # Global configuration
+  extend ActiveSupport::Configurable
+
+  # Configuration accessors
+  self.@config: untyped
+  def self.config: () -> ActiveSupport::Configurable::Configuration
+  def self.default_storage: () -> (:memory | :bucket_memory | :null | untyped)
+  def self.default_storage=: (:memory | :bucket_memory | :null | untyped value) -> void
+  def self.default_timeout: () -> Integer?
+  def self.default_timeout=: (Integer? value) -> void
+  def self.default_reset_timeout: () -> Integer
+  def self.default_reset_timeout=: (Integer value) -> void
+  def self.default_failure_threshold: () -> Integer
+  def self.default_failure_threshold=: (Integer value) -> void
+  def self.log_events: () -> bool
+  def self.log_events=: (bool value) -> void
+
+  # Class methods
+  def self.configure: () { (untyped config) -> void } -> void
+  def self.setup_notifications: () -> void
+  def self.logger: () -> ActiveSupport::Logger?
+  def self.logger=: (ActiveSupport::Logger? logger) -> void
+  def self.instrument: (String event, ?Hash[Symbol, untyped] payload) -> void
+  def self.console: () -> void
+  def self.registry: () -> Registry
+  def self.loader: () -> Zeitwerk::Loader
+end

data/sig/manifest.yaml

@@ -0,0 +1,5 @@
+dependencies:
+  - name: activesupport
+  - name: concurrent-ruby
+  - name: state_machines
+  - name: zeitwerk