sender-core 0.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7b541836b2290d80cb723414c53339cafc3704af0ec52c4b8f3ab72696cb723e
+  data.tar.gz: aad6ca0e0ca13461430e02f1135eedc5d8cc01d7961752d502be2ba9a5967777
+SHA512:
+  metadata.gz: 4fa574c030ee74ad81e1090728363af0be00bb8c36f2d30ca0fa79b5fff5f372ab5529f17e688c0501d1dd5176f81d51b8e1963b229aec10f3ad240c5add1dcf
+  data.tar.gz: f8bb566e3b84e787151fd7e1f15a08ec5f23ed00796cf69512db956975af259c07867cb26a751e3a1161bb32f3ec03891e5a3fe6f6830604b1001711aadffd7c

data/CHANGELOG.md

@@ -0,0 +1,20 @@
+## [Unreleased]
+
+### Added
+
+- Add immutable provider-neutral message, delivery, capability, delivery-event,
+  and normalized-error contracts.
+- Add provider configuration and lazy registry primitives for channel gems.
+- Add bounded provider election, routing, failover, circuit protection, health
+  tracking, and attempt history.
+- Add replaceable in-memory state and structured observability primitives.
+- Add a standard-library HTTP transport with configurable request timeouts and
+  normalized network and timeout errors.
+- Add the shared runtime integration boundary used by channel gems such as
+  `sms-sender` and `email-sender`.
+
+### Quality
+
+- Add focused tests, RBS signatures, and channel-independent defaults.
+- Add the `bundle exec rake` quality harness covering tests, RuboCop, RBS, and
+  100% YARD documentation coverage.

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"sender-core" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["kenneth.c.demanawa@gmail.com"](mailto:"kenneth.c.demanawa@gmail.com").

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Ken C. Demanawa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,120 @@
+# sender-core
+
+`sender-core` is the channel-neutral Ruby runtime for sender gems such as
+[`sms-sender`](https://github.com/kanutocd/sms-sender) and `email-sender`.
+It provides reusable delivery contracts, provider selection, failover,
+resilience, state, and observability primitives.
+
+## Origin
+
+The sender gems were extracted from the Pink House SaaS project to make its
+delivery capabilities reusable, independently testable, and composable across
+communication channels. `sender-core` contains the shared runtime extracted
+from the original application; channel gems remain responsible for their own
+input validation and provider integrations.
+
+Channel gems remain responsible for channel-specific validation, provider
+adapters, authentication, payload mapping, and response mapping. The shared
+runtime is independent of SMS, email, Rails, Redis, PostgreSQL, provider
+SDKs, and live network services.
+
+## Installation
+
+Add the gem to your application's Gemfile:
+
+```ruby
+gem "sender-core"
+```
+
+Then install it with Bundler:
+
+```bash
+bundle install
+```
+
+## Architecture
+
+```text
+channel facade
+      |
+sender-core message and delivery contracts
+      |
+election -> router -> channel provider adapter -> HTTP/provider API
+      |
+health, circuit breaker, state store, and observability
+```
+
+`sender-core` is not a standalone email or SMS client. It supplies the
+provider-neutral runtime that channel gems compose into their public APIs.
+
+## Usage
+
+Channel gems normalize their input into a core message, configure one or more
+providers, and delegate delivery to the shared router:
+
+```ruby
+message = Sender::Core::Message.new(
+  to: "recipient@example.test",
+  body: "Hello",
+  requirements: [:email]
+)
+
+delivery = Sender::Core::Router.new(registry: registry).deliver(message)
+```
+
+The returned delivery exposes its normalized status, selected provider,
+provider message ID, attempt history, and error. Channel-specific validation
+and provider request mapping belong in the composing channel gem.
+
+## Development
+
+Install development dependencies with:
+
+```bash
+bin/setup
+```
+
+Run the complete quality harness with:
+
+```bash
+bundle exec rake
+```
+
+The harness runs tests, RuboCop, RBS validation, YARD generation, and a 100%
+YARD documentation coverage check. Tests must remain deterministic and must
+not require credentials, network access, or live provider availability.
+
+Useful individual tasks include:
+
+```bash
+bundle exec rake test
+bundle exec rake rubocop
+bundle exec rake rbs
+bundle exec rake yard
+bundle exec rake yard:coverage
+bundle exec rake build
+bin/console
+```
+
+## Design principles
+
+- Keep the core channel-neutral and provider-independent.
+- Use immutable value objects for delivery context.
+- Make retry and failover policy explicit and bounded.
+- Keep mutable runtime state behind replaceable abstractions.
+- Load providers lazily and keep adapters thin.
+- Prefer standard-library boundaries and minimal dependencies.
+- Keep live integration checks separate from the default quality gate.
+
+## Contributing
+
+Bug reports and pull requests are welcome at
+[github.com/kanutocd/sender-core](https://github.com/kanutocd/sender-core).
+Meaningful user, operator, integration, tooling, and architectural changes
+should be recorded in `CHANGELOG.md` under `Unreleased`.
+
+## License
+
+This project is available under the [MIT License](LICENSE.txt).
+
+See [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for community guidelines.

data/Rakefile

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |task|
+  task.libs << "test"
+  task.libs << "lib"
+  task.test_files = FileList["test/**/test_*.rb", "test/**/*_test.rb"]
+end
+
+require "rubocop/rake_task"
+require "yard"
+require "yard/rake/yardoc_task"
+
+RuboCop::RakeTask.new do |task|
+  task.options = ["--cache", "false"]
+end
+
+YARD::Rake::YardocTask.new(:yard) do |task|
+  task.files = ["lib/**/*.rb"]
+  task.options = ["--output-dir", "doc", "--readme", "README.md", "--markup", "markdown"]
+end
+
+desc "Validate RBS signatures"
+task :rbs do
+  sh "rbs validate"
+end
+
+desc "Enforce YARD documentation coverage"
+task "yard:coverage" => :yard do
+  output = `yard stats --no-progress --list-undoc --exclude sig`
+  puts output
+  coverage = output[/([0-9]+(?:\.[0-9]+)?)% documented/, 1]&.to_f
+  abort "Could not determine YARD documentation coverage" unless coverage
+  abort "YARD documentation coverage #{coverage}% is below 100%" if coverage < 100.0
+end
+
+desc "Run the test and lint quality gates"
+task quality: %i[test rubocop rbs yard:coverage]
+
+task default: :quality

data/lib/sender/core/capabilities.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Sender
+  module Core
+    # Shared capability vocabulary and normalization rules.
+    module Capabilities
+      # Initial capability names understood by routing policies.
+      KNOWN = %i[sms email unicode sender_id alphanumeric_sender delivery_receipts attachments].freeze
+
+      # Normalize capability values without preventing provider extensions.
+      # @param values [Array<Symbol, String>] capability names
+      # @return [Array<Symbol>] unique normalized names
+      def self.normalize(values)
+        raise ArgumentError, "capabilities must be an Array" unless values.is_a?(Array)
+
+        values.map(&:to_sym).uniq.freeze
+      rescue NoMethodError
+        raise ArgumentError, "capabilities must contain symbolizable values"
+      end
+    end
+  end
+end

data/lib/sender/core/circuit_breaker.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Sender
+  module Core
+    # In-memory circuit breaker for one provider.
+    class CircuitBreaker
+      # Circuit states exposed for observability and routing.
+      STATES = %i[closed open half_open].freeze
+      # Conservative default consecutive-failure threshold.
+      DEFAULT_FAILURE_THRESHOLD = 3
+      # Default period for retaining failure observations, in seconds.
+      DEFAULT_OBSERVATION_WINDOW = 60
+      # Default period before an open circuit can be probed, in seconds.
+      DEFAULT_OPEN_COOLDOWN = 30
+      # Default number of concurrent half-open probes.
+      DEFAULT_HALF_OPEN_PROBE_LIMIT = 1
+
+      # @param failure_threshold [Integer] failures required to open
+      # @param observation_window [Numeric] failure retention period
+      # @param open_cooldown [Numeric] open period before probing
+      # @param half_open_probe_limit [Integer] concurrent probe limit
+      # @param clock [#call] monotonic clock returning seconds
+      def initialize(failure_threshold: DEFAULT_FAILURE_THRESHOLD, observation_window: DEFAULT_OBSERVATION_WINDOW,
+                     open_cooldown: DEFAULT_OPEN_COOLDOWN, half_open_probe_limit: DEFAULT_HALF_OPEN_PROBE_LIMIT,
+                     clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
+        @failure_threshold = positive_integer(failure_threshold, "failure_threshold")
+        @observation_window = positive_number(observation_window, "observation_window")
+        @open_cooldown = positive_number(open_cooldown, "open_cooldown")
+        @half_open_probe_limit = positive_integer(half_open_probe_limit, "half_open_probe_limit")
+        @clock = clock
+        @state = :closed
+        @failures = []
+        @opened_at = nil
+        @probes = 0
+        @lock = Mutex.new
+      end
+
+      # @return [Symbol] current circuit state
+      def state
+        @lock.synchronize do
+          transition_if_ready
+          @state
+        end
+      end
+
+      # Reserve permission for one request.
+      # @return [Boolean] whether the request may proceed
+      def allow?
+        @lock.synchronize do
+          transition_if_ready
+          return true if @state == :closed
+          return false if @state == :open
+          return false if @probes >= @half_open_probe_limit
+
+          @probes += 1
+          true
+        end
+      end
+
+      # Record a successful request and close the circuit.
+      def record_success
+        @lock.synchronize do
+          @state = :closed
+          @failures.clear
+          @opened_at = nil
+          @probes = 0
+        end
+      end
+
+      # Record a retryable provider failure.
+      # @param error [Errors::Base] normalized provider error
+      def record_failure(error)
+        return unless error.retryable?
+
+        @lock.synchronize do
+          if @state == :half_open
+            open_circuit
+          else
+            prune_failures
+            @failures << @clock.call
+            open_circuit if @failures.length >= @failure_threshold
+          end
+        end
+      end
+
+      private
+
+      def transition_if_ready
+        return unless @state == :open && @clock.call - @opened_at >= @open_cooldown
+
+        @state = :half_open
+        @probes = 0
+      end
+
+      def open_circuit
+        @state = :open
+        @opened_at = @clock.call
+        @probes = 0
+      end
+
+      def prune_failures
+        cutoff = @clock.call - @observation_window
+        @failures.reject! { |timestamp| timestamp < cutoff }
+      end
+
+      def positive_integer(value, name)
+        return value if value.is_a?(Integer) && value.positive?
+
+        raise ArgumentError, "#{name} must be a positive Integer"
+      end
+
+      def positive_number(value, name)
+        return value if value.is_a?(Numeric) && value.positive?
+
+        raise ArgumentError, "#{name} must be a positive number"
+      end
+    end
+  end
+end

data/lib/sender/core/delivery.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Sender
+  module Core
+    # Immutable provider-neutral delivery result.
+    class Delivery
+      # Statuses exposed by the provider-neutral delivery result.
+      STATUSES = %i[pending submitted accepted delivered failed unknown].freeze
+
+      attr_reader :status, :provider, :provider_message_id, :attempts, :error, :metadata
+
+      # @param status [Symbol] normalized delivery status
+      # @param provider [Symbol, nil] provider that handled the delivery
+      # @param provider_message_id [String, nil] provider-side identifier
+      # @param attempts [Array<Hash>] delivery attempt records
+      # @param error [Errors::Base, nil] normalized failure
+      # @param metadata [Hash] provider-neutral metadata
+      def initialize(status: :unknown, provider: nil, provider_message_id: nil, attempts: [], error: nil, metadata: {})
+        @status = normalize_status(status)
+        @provider = provider&.to_sym
+        @provider_message_id = provider_message_id&.to_s&.freeze
+        @attempts = normalize_attempts(attempts)
+        @error = validate_error(error)
+        @metadata = normalize_metadata(metadata)
+        freeze
+      end
+
+      # @return [Boolean] whether the provider accepted the message
+      def accepted?
+        %i[submitted accepted].include?(status)
+      end
+
+      # @return [Boolean] whether delivery was confirmed
+      def delivered?
+        status == :delivered
+      end
+
+      # @return [Boolean] whether delivery failed terminally
+      def failed?
+        status == :failed
+      end
+
+      # Apply a provider status event to this immutable delivery state.
+      # @param event [DeliveryEvent] normalized provider status update
+      # @return [Delivery] updated delivery state
+      def with_event(event)
+        raise ArgumentError, "event must be a Sender::Core::DeliveryEvent" unless event.is_a?(DeliveryEvent)
+        if provider && (event.provider != provider || event.provider_message_id != provider_message_id)
+          raise ArgumentError, "delivery event does not match this delivery"
+        end
+
+        Delivery.new(
+          status: event.status,
+          provider: event.provider,
+          provider_message_id: event.provider_message_id,
+          attempts: attempts,
+          error: event.error,
+          metadata: metadata.merge(event.metadata)
+        )
+      end
+
+      private
+
+      def normalize_status(value)
+        status = value.to_sym
+        return status if STATUSES.include?(status)
+
+        raise ArgumentError, "unknown delivery status: #{value.inspect}"
+      rescue NoMethodError
+        raise ArgumentError, "status must be symbolizable"
+      end
+
+      def normalize_attempts(value)
+        raise ArgumentError, "attempts must be an Array" unless value.is_a?(Array)
+
+        value.map do |attempt|
+          raise ArgumentError, "each attempt must be a Hash" unless attempt.is_a?(Hash)
+
+          attempt.dup.freeze
+        end.freeze
+      end
+
+      def validate_error(value)
+        return unless value
+        return value if value.is_a?(Errors::Base)
+
+        raise ArgumentError, "error must be a normalized sender error"
+      end
+
+      def normalize_metadata(value)
+        raise ArgumentError, "metadata must be a Hash" unless value.is_a?(Hash)
+
+        value.dup.freeze
+      end
+    end
+  end
+end

data/lib/sender/core/delivery_event.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Sender
+  module Core
+    # Provider-neutral delivery status update, suitable for webhook adapters.
+    class DeliveryEvent
+      attr_reader :provider, :provider_message_id, :status, :metadata, :error, :occurred_at
+
+      # @param provider [Symbol, String] source provider
+      # @param provider_message_id [String] provider-side message identifier
+      # @param status [Symbol] normalized delivery status
+      # @param metadata [Hash] provider event metadata
+      # @param error [Errors::Base, nil] normalized delivery error
+      # @param occurred_at [Time] provider event timestamp
+      def initialize(provider:, provider_message_id:, status:, metadata: {}, error: nil, occurred_at: Time.now)
+        @provider = provider.to_sym
+        @provider_message_id = provider_message_id.to_s
+        @status = normalize_status(status)
+        @metadata = validate_metadata(metadata)
+        @error = validate_error(error)
+        @occurred_at = validate_time(occurred_at)
+        freeze
+      end
+
+      private
+
+      def normalize_status(value)
+        return value.to_sym if Delivery::STATUSES.include?(value.to_sym)
+
+        raise ArgumentError, "unknown delivery event status: #{value.inspect}"
+      rescue NoMethodError
+        raise ArgumentError, "status must be symbolizable"
+      end
+
+      def validate_metadata(value)
+        raise ArgumentError, "metadata must be a Hash" unless value.is_a?(Hash)
+
+        value.dup.freeze
+      end
+
+      def validate_error(value)
+        return unless value
+        return value if value.is_a?(Errors::Base)
+
+        raise ArgumentError, "error must be a normalized sender error"
+      end
+
+      def validate_time(value)
+        return value if value.is_a?(Time)
+
+        raise ArgumentError, "occurred_at must be a Time"
+      end
+    end
+  end
+end

data/lib/sender/core/election.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Sender
+  module Core
+    # Selects eligible providers using priority and lightweight health signals.
+    class Election
+      # @param state_store [StateStore::Memory] election state persistence
+      def initialize(state_store: StateStore::Memory.new)
+        @state_store = state_store
+      end
+
+      # Return providers in deterministic descending preference order.
+      # @param providers [Array<Provider>] configured providers
+      # @param requirements [Array<Symbol>] required message capabilities
+      # @param circuits [Hash<Symbol, CircuitBreaker>] provider circuits
+      # @param health [Hash<Symbol, Health>] provider health records
+      # @return [Array<Provider>] eligible providers
+      def rank(providers, requirements: [], circuits: {}, health: {})
+        result = providers
+                 .select { |provider| eligible?(provider, requirements, circuits) }
+                 .sort_by { |provider| election_key(provider, snapshot_for(health[provider.name])) }
+                 .reverse
+        @state_store.write(:last_election, result.first&.name)
+        result
+      end
+
+      # @return [Symbol, nil] most recently preferred provider
+      def last_selection
+        @state_store.read(:last_election)
+      end
+
+      private
+
+      def eligible?(provider, requirements, circuits)
+        provider.configuration.enabled? &&
+          requirements.all? { |requirement| provider.capabilities.include?(requirement.to_sym) } &&
+          (circuits[provider.name]&.allow? != false)
+      end
+
+      def election_key(provider, snapshot)
+        priority = provider.configuration.priority
+        success_rate = success_rate(snapshot)
+        failure_penalty = snapshot ? snapshot[:recent_failures] + snapshot[:consecutive_failures] : 0
+        [priority + success_rate - failure_penalty, priority, provider.name.to_s]
+      end
+
+      def success_rate(snapshot)
+        return 0 unless snapshot
+
+        successes = snapshot[:recent_successes]
+        failures = snapshot[:recent_failures]
+        total = successes + failures
+        total.zero? ? 0 : successes.to_f / total
+      end
+
+      def snapshot_for(value)
+        return unless value
+
+        value.respond_to?(:snapshot) ? value.snapshot : value
+      end
+    end
+  end
+end

data/lib/sender/core/errors.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Sender
+  module Core
+    # Namespace for normalized delivery errors.
+    module Errors
+      # Errors that may be retried and sent to another provider.
+      FAILOVER_CATEGORIES = %i[network timeout rate_limited provider_unavailable].freeze
+      # Errors that may be retried against the same provider.
+      RETRYABLE_CATEGORIES = (FAILOVER_CATEGORIES + %i[authentication authorization]).freeze
+
+      # Base error raised by the sender runtime.
+      class Base < Core::Error
+        # @return [Symbol] normalized error category
+        attr_reader :category
+        # @return [Symbol, nil] associated provider
+        attr_reader :provider
+
+        # @param message [String] safe error message
+        # @param category [Symbol] normalized error category
+        # @param provider [Symbol, nil] provider associated with the error
+        def initialize(message = nil, category: nil, provider: nil)
+          @category = (category || inferred_category).to_sym
+          @provider = provider&.to_sym
+          super(message || @category.to_s)
+        end
+
+        # @return [Symbol] category inferred from the concrete error class
+        def inferred_category
+          name = self.class.name&.split("::")&.last
+          name ? name.gsub(/([a-z])([A-Z])/, '\\1_\\2').downcase.to_sym : :unknown
+        end
+
+        # @return [Boolean] whether this error can be retried
+        def retryable?
+          RETRYABLE_CATEGORIES.include?(category)
+        end
+
+        # @return [Boolean] whether this error permits provider failover
+        def failover?
+          FAILOVER_CATEGORIES.include?(category)
+        end
+      end
+
+      # Base class for errors originating from a provider or its transport.
+      class ProviderError < Base; end
+      # A network-level failure occurred before a response was received.
+      class Network < ProviderError; end
+      # The provider request exceeded its timeout.
+      class Timeout < ProviderError; end
+      # The provider rate-limited the request.
+      class RateLimited < ProviderError; end
+      # Provider authentication failed.
+      class Authentication < ProviderError; end
+      # Provider authorization failed.
+      class Authorization < ProviderError; end
+      # The outbound request was invalid.
+      class InvalidRequest < Base; end
+      # The recipient address was invalid.
+      class InvalidRecipient < Base; end
+      # The provider is unavailable and the request may be retried elsewhere.
+      class ProviderUnavailable < ProviderError; end
+      # The provider rejected the message for a request-specific reason.
+      class ProviderRejected < Base; end
+      # An error that could not be mapped to a more specific category.
+      class Unknown < Base; end
+      # A provider or provider configuration cannot be loaded or validated.
+      class ConfigurationError < Base; end
+    end
+  end
+end