sender-core 0.0.0

data/lib/sender/core/router.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module Sender
+  module Core
+    # Selects one eligible configured provider for a delivery.
+    class Router
+      # @param registry [ProviderRegistry] provider registry to route through
+      def initialize(registry: ProviderRegistry.new, circuit_options: {}, state_store: StateStore::Memory.new,
+                     observer: Observability::Memory.new)
+        @registry = registry
+        @circuit_options = circuit_options
+        @state_store = state_store
+        @observer = observer
+        @election = Election.new(state_store: @state_store)
+      end
+
+      # Deliver a normalized message through the best eligible provider.
+      #
+      # Providers are ordered by descending priority, then by name for stable
+      # tie-breaking. Failover is bounded by the eligible provider count.
+      # @param message [Message] normalized outbound message
+      # @param provider [Symbol, String, nil] optional explicit provider
+      # @param max_attempts [Integer, nil] optional upper bound on attempts
+      # @return [Delivery] provider-neutral delivery result
+      def deliver(message, provider: nil, max_attempts: nil)
+        validate_message(message)
+        candidates = eligible_providers(provider, requirements: message.requirements)
+        attempt_limit = validate_max_attempts(max_attempts || candidates.length)
+        attempts = []
+        last_error = nil
+
+        candidates.first(attempt_limit).each do |candidate|
+          started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          delivery = candidate.deliver(message)
+          previous_state = circuit_for(candidate).state
+          circuit_for(candidate).record_success
+          if previous_state != circuit_for(candidate).state
+            emit(type: :circuit_transition, provider: candidate.name, from: previous_state,
+                 to: circuit_for(candidate).state)
+          end
+          health_for(candidate).record_success(
+            latency: elapsed_since(started_at), circuit_state: circuit_for(candidate).state
+          )
+          emit(type: :attempt, provider: candidate.name, status: :accepted, latency: elapsed_since(started_at))
+          return with_attempt(delivery, attempts, candidate.name, :accepted)
+        rescue Errors::Base => e
+          previous_state = circuit_for(candidate).state
+          circuit_for(candidate).record_failure(e)
+          if previous_state != circuit_for(candidate).state
+            emit(type: :circuit_transition, provider: candidate.name, from: previous_state,
+                 to: circuit_for(candidate).state)
+          end
+          health_for(candidate).record_failure(
+            latency: elapsed_since(started_at), error: e, circuit_state: circuit_for(candidate).state
+          )
+          emit(type: :attempt, provider: candidate.name, status: :failed, error: e.category,
+               latency: elapsed_since(started_at))
+          attempts << attempt_record(candidate.name, :failed, e)
+          last_error = e
+          if e.failover? && attempts.length < attempt_limit
+            emit(type: :failover, from: candidate.name, to: candidates[attempts.length]&.name)
+          end
+          raise unless e.failover?
+        end
+
+        Delivery.new(status: :failed, provider: last_error.provider, attempts: attempts, error: last_error)
+      end
+
+      # @param name [Symbol, String] configured provider name
+      # @return [Hash] current provider health snapshot
+      def health(name)
+        health_for(@registry.provider(name)).snapshot
+      end
+
+      # @return [Array<Hash>] structured events emitted by this router
+      def events
+        @observer.events
+      end
+
+      private
+
+      def eligible_providers(name = nil, requirements: [])
+        candidates = name ? [@registry.provider(name)] : @registry.providers
+        selected = @election.rank(
+          candidates, requirements: requirements, circuits: circuit_map(candidates), health: health_map(candidates)
+        )
+        emit(type: :election, candidates: selected.map(&:name), selected: selected.first&.name)
+        return selected unless selected.empty?
+
+        raise Errors::ConfigurationError.new("no eligible provider is configured", category: :configuration)
+      end
+
+      def validate_max_attempts(value)
+        return value if value.is_a?(Integer) && value.positive?
+
+        raise ArgumentError, "max_attempts must be a positive Integer"
+      end
+
+      def circuit_map(providers)
+        providers.to_h { |provider| [provider.name, circuit_for(provider)] }
+      end
+
+      def health_map(providers)
+        providers.to_h { |provider| [provider.name, health_for(provider)] }
+      end
+
+      def circuit_for(provider)
+        @state_store.fetch([:circuit, provider.name]) { CircuitBreaker.new(**@circuit_options) }
+      end
+
+      def health_for(provider)
+        @state_store.fetch([:health, provider.name]) do
+          Health.new(
+            observation_window: @circuit_options.fetch(:observation_window, CircuitBreaker::DEFAULT_OBSERVATION_WINDOW)
+          )
+        end
+      end
+
+      def elapsed_since(started_at)
+        Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at
+      end
+
+      def emit(event)
+        @observer.emit(event)
+      end
+
+      def attempt_record(provider, status, error = nil)
+        { provider: provider, status: status, error: error&.category }.compact
+      end
+
+      def with_attempt(delivery, attempts, provider, status)
+        Delivery.new(
+          status: delivery.status,
+          provider: delivery.provider,
+          provider_message_id: delivery.provider_message_id,
+          attempts: attempts + [attempt_record(provider, status)],
+          error: delivery.error,
+          metadata: delivery.metadata
+        )
+      end
+
+      def validate_message(message)
+        return if message.is_a?(Message)
+
+        raise ArgumentError, "message must be a Sender::Core::Message"
+      end
+    end
+  end
+end

data/lib/sender/core/state_store.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Sender
+  module Core
+    # Namespace for replaceable runtime state persistence implementations.
+    module StateStore
+      # Thread-safe process-local state store.
+      class Memory
+        def initialize
+          @values = {}
+          @lock = Mutex.new
+        end
+
+        # @param key [Object] state key
+        # @return [Object, nil] stored value
+        def read(key)
+          @lock.synchronize { @values[key] }
+        end
+
+        # Store a value and return it.
+        # @param key [Object] state key
+        # @param value [Object] state value
+        # @return [Object] stored value
+        def write(key, value)
+          @lock.synchronize { @values[key] = value }
+        end
+
+        # Read a value or initialize it atomically.
+        # @param key [Object] state key
+        # @return [Object] existing or initialized value
+        def fetch(key)
+          @lock.synchronize { @values.fetch(key) { @values[key] = yield } }
+        end
+
+        # Remove a value.
+        # @param key [Object] state key
+        # @return [Object, nil] removed value
+        def delete(key)
+          @lock.synchronize { @values.delete(key) }
+        end
+
+        # Remove all state values.
+        def clear
+          @lock.synchronize { @values.clear }
+        end
+      end
+    end
+  end
+end

data/lib/sender/core/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Sender
+  module Core
+    # Current sender-core version.
+    VERSION = "0.0.0"
+  end
+end

data/lib/sender/core.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "core/version"
+
+# Top-level namespace for sender-related libraries.
+module Sender
+  # Namespace for sender-related libraries.
+  module Core
+    # Channel-neutral delivery runtime shared by sender gems.
+    # Base error raised by sender-core.
+    class Error < StandardError; end
+  end
+end
+
+require_relative "core/capabilities"
+require_relative "core/errors"
+require_relative "core/message"
+require_relative "core/delivery"
+require_relative "core/delivery_event"
+require_relative "core/provider_configuration"
+require_relative "core/provider"
+require_relative "core/state_store"
+require_relative "core/observability"
+require_relative "core/circuit_breaker"
+require_relative "core/health"
+require_relative "core/election"
+require_relative "core/provider_registry"
+require_relative "core/router"
+require_relative "core/http"

data/sig/sender/core.rbs

@@ -0,0 +1,78 @@
+module Sender
+  module Core
+    class Error < StandardError
+    end
+
+    VERSION: String
+
+    module Capabilities
+      KNOWN: Array[Symbol]
+
+      def self.normalize: (Array[Symbol | String] values) -> Array[Symbol]
+    end
+
+    module Errors
+      FAILOVER_CATEGORIES: Array[Symbol]
+      RETRYABLE_CATEGORIES: Array[Symbol]
+
+      class Base < Error
+        attr_reader category: Symbol
+        attr_reader provider: Symbol?
+
+        def initialize: (?String?, ?category: Symbol?, ?provider: Symbol?) -> void
+        def retryable?: () -> bool
+        def failover?: () -> bool
+      end
+
+      class ProviderError < Base
+      end
+      class Network < ProviderError
+      end
+      class Timeout < ProviderError
+      end
+      class RateLimited < ProviderError
+      end
+      class Authentication < ProviderError
+      end
+      class Authorization < ProviderError
+      end
+      class InvalidRequest < Base
+      end
+      class InvalidRecipient < Base
+      end
+      class ProviderUnavailable < ProviderError
+      end
+      class ProviderRejected < Base
+      end
+      class Unknown < Base
+      end
+      class ConfigurationError < Base
+      end
+    end
+
+    class Message
+      attr_reader to: String
+      attr_reader body: String
+      attr_reader metadata: Hash[untyped, untyped]
+      attr_reader requirements: Array[Symbol]
+
+      def initialize: (to: String, body: String, ?metadata: Hash[untyped, untyped], ?requirements: Array[Symbol | String]) -> void
+    end
+
+    class Delivery
+      STATUSES: Array[Symbol]
+      attr_reader status: Symbol
+      attr_reader provider: Symbol?
+      attr_reader provider_message_id: String?
+      attr_reader attempts: Array[Hash[untyped, untyped]]
+      attr_reader error: Errors::Base?
+      attr_reader metadata: Hash[untyped, untyped]
+
+      def initialize: (?status: Symbol | String, ?provider: Symbol | String?, ?provider_message_id: untyped, ?attempts: Array[Hash[untyped, untyped]], ?error: Errors::Base?, ?metadata: Hash[untyped, untyped]) -> void
+      def accepted?: () -> bool
+      def delivered?: () -> bool
+      def failed?: () -> bool
+      def with_event: (DeliveryEvent event) -> Delivery
+    end
+  end
+end

metadata

@@ -0,0 +1,72 @@
+--- !ruby/object:Gem::Specification
+name: sender-core
+version: !ruby/object:Gem::Version
+  version: 0.0.0
+platform: ruby
+authors:
+- Ken C. Demanawa
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: |
+  Sender Core provides provider-neutral message delivery contracts,
+  routing, failover, resilience, state, and observability primitives for
+  Ruby channel gems such as sms-sender and email-sender.
+email:
+- kenneth.c.demanawa@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/sender/core.rb
+- lib/sender/core/capabilities.rb
+- lib/sender/core/circuit_breaker.rb
+- lib/sender/core/delivery.rb
+- lib/sender/core/delivery_event.rb
+- lib/sender/core/election.rb
+- lib/sender/core/errors.rb
+- lib/sender/core/health.rb
+- lib/sender/core/http.rb
+- lib/sender/core/message.rb
+- lib/sender/core/observability.rb
+- lib/sender/core/provider.rb
+- lib/sender/core/provider_configuration.rb
+- lib/sender/core/provider_registry.rb
+- lib/sender/core/router.rb
+- lib/sender/core/state_store.rb
+- lib/sender/core/version.rb
+- sig/sender/core.rbs
+homepage: https://kanutocd.github.io/sender-core
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://kanutocd.github.io/sender-core
+  source_code_uri: https://github.com/kanutocd/sender-core
+  changelog_uri: https://github.com/kanutocd/sender-core/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/kanutocd/sender-core/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.19
+specification_version: 4
+summary: Channel-neutral delivery runtime for Ruby sms-sender and email-sender gems
+test_files: []