sender-core 0.0.0

data/lib/sender/core/health.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Sender
+  module Core
+    # Thread-safe in-memory health history for one provider.
+    class Health
+      # @param observation_window [Numeric] period for retaining observations
+      # @param clock [#call] monotonic clock returning seconds
+      def initialize(observation_window: CircuitBreaker::DEFAULT_OBSERVATION_WINDOW,
+                     clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
+        unless observation_window.is_a?(Numeric) && observation_window.positive?
+          raise ArgumentError, "observation_window must be a positive number"
+        end
+
+        @observation_window = observation_window
+        @clock = clock
+        @successes = []
+        @failures = []
+        @consecutive_failures = 0
+        @circuit_state = :closed
+        @lock = Mutex.new
+      end
+
+      # Record a successful provider attempt.
+      # @param latency [Numeric] elapsed request time in seconds
+      # @param circuit_state [Symbol] circuit state after the attempt
+      def record_success(latency:, circuit_state: :closed)
+        @lock.synchronize do
+          prune
+          @successes << [@clock.call, validate_latency(latency)]
+          @consecutive_failures = 0
+          @circuit_state = circuit_state.to_sym
+        end
+      end
+
+      # Record a failed provider attempt.
+      # @param latency [Numeric] elapsed request time in seconds
+      # @param error [Errors::Base] normalized error
+      # @param circuit_state [Symbol] circuit state after the attempt
+      def record_failure(latency:, error:, circuit_state: :closed)
+        @lock.synchronize do
+          prune
+          @failures << [@clock.call, validate_latency(latency), error.category]
+          @consecutive_failures += 1
+          @circuit_state = circuit_state.to_sym
+        end
+      end
+
+      # @return [Hash] immutable health snapshot
+      def snapshot
+        @lock.synchronize do
+          prune
+          latencies = (@successes + @failures).map { |event| event[1] }
+          snapshot_values(latencies).freeze
+        end
+      end
+
+      private
+
+      def prune
+        cutoff = @clock.call - @observation_window
+        @successes.reject! { |event| event[0] < cutoff }
+        @failures.reject! { |event| event[0] < cutoff }
+        @consecutive_failures = 0 if @failures.empty?
+      end
+
+      def snapshot_values(latencies)
+        {
+          recent_successes: @successes.length,
+          recent_failures: @failures.length,
+          consecutive_failures: @consecutive_failures,
+          average_latency: latencies.empty? ? nil : latencies.sum / latencies.length.to_f,
+          circuit_state: @circuit_state
+        }
+      end
+
+      def validate_latency(value)
+        return value if value.is_a?(Numeric) && value >= 0
+
+        raise ArgumentError, "latency must be a non-negative number"
+      end
+    end
+  end
+end

data/lib/sender/core/http.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "timeout"
+require "uri"
+
+module Sender
+  module Core
+    # Internal HTTP transport used by provider adapters.
+    module HTTP
+      # Normalized HTTP response returned by the transport.
+      class Response
+        attr_reader :status, :headers, :body
+
+        # @param status [Integer] HTTP status code
+        # @param headers [Hash] response headers
+        # @param body [String] response body
+        def initialize(status:, headers: {}, body: "")
+          raise ArgumentError, "status must be an Integer" unless status.is_a?(Integer)
+          raise ArgumentError, "headers must be a Hash" unless headers.is_a?(Hash)
+
+          @status = status
+          @headers = headers.transform_keys(&:to_s).freeze
+          @body = body.to_s.freeze
+          freeze
+        end
+
+        # @return [Boolean] whether the response has a 2xx status
+        def successful?
+          status.between?(200, 299)
+        end
+      end
+
+      # Standard-library Net::HTTP implementation of the transport boundary.
+      class NetHttpTransport
+        # @param http_factory [#call] factory returning a configured HTTP client
+        def initialize(http_factory: ->(uri) { Net::HTTP.new(uri.host, uri.port) })
+          @http_factory = http_factory
+        end
+
+        # @return [Response] normalized HTTP response
+        def call(method:, url:, headers:, body:, open_timeout:, read_timeout:, write_timeout:)
+          uri = URI.parse(url)
+          http = @http_factory.call(uri)
+          http.use_ssl = true if uri.scheme == "https"
+          http.open_timeout = open_timeout
+          http.read_timeout = read_timeout
+          http.write_timeout = write_timeout if http.respond_to?(:write_timeout=)
+
+          request = Net::HTTPGenericRequest.new(
+            method.to_s.upcase,
+            !body.nil?,
+            true,
+            uri.request_uri,
+            headers
+          )
+          request.body = body if body
+          response = http.start { http.request(request) }
+          Response.new(status: response.code.to_i, headers: response.each_header.to_h, body: response.body)
+        end
+      end
+
+      # Executes HTTP requests and maps transport details into domain values.
+      class Client
+        # Default connection timeout in seconds.
+        DEFAULT_OPEN_TIMEOUT = 5
+        # Default response read timeout in seconds.
+        DEFAULT_READ_TIMEOUT = 10
+        # Default request write timeout in seconds.
+        DEFAULT_WRITE_TIMEOUT = 10
+
+        # @param transport [#call, nil] injectable transport implementation
+        # @param open_timeout [Numeric] connection timeout in seconds
+        # @param read_timeout [Numeric] response read timeout in seconds
+        # @param write_timeout [Numeric] request write timeout in seconds
+        # @param total_timeout [Numeric, nil] complete request timeout in seconds
+        def initialize(transport: nil, open_timeout: DEFAULT_OPEN_TIMEOUT, read_timeout: DEFAULT_READ_TIMEOUT,
+                       write_timeout: DEFAULT_WRITE_TIMEOUT, total_timeout: nil)
+          @transport = transport || NetHttpTransport.new
+          @open_timeout = open_timeout
+          @read_timeout = read_timeout
+          @write_timeout = write_timeout
+          @total_timeout = total_timeout
+        end
+
+        # @param method [Symbol, String] HTTP method
+        # @param url [String] absolute request URL
+        # @param headers [Hash] request headers
+        # @param body [String, Hash, nil] request body
+        # @return [Response] normalized response
+        def request(method, url, headers: {}, body: nil)
+          request_headers = normalize_headers(headers)
+          serialized_body, request_headers = serialize_body(body, request_headers)
+          result = with_total_timeout do
+            @transport.call(
+              method: method,
+              url: url,
+              headers: request_headers,
+              body: serialized_body,
+              open_timeout: @open_timeout,
+              read_timeout: @read_timeout,
+              write_timeout: @write_timeout
+            )
+          end
+          normalize_response(result)
+        rescue ::Timeout::Error
+          raise Errors::Timeout, "HTTP request timed out"
+        rescue SocketError, SystemCallError, EOFError
+          raise Errors::Network, "HTTP request failed"
+        end
+
+        # @param headers [Hash] request headers
+        # @return [Hash] headers safe for diagnostics
+        def redacted_headers(headers)
+          redacted = normalize_headers(headers)
+          redacted.each_key do |key|
+            redacted[key] = "[REDACTED]" if sensitive_header?(key)
+          end
+          redacted.freeze
+        end
+
+        private
+
+        def normalize_headers(headers)
+          raise ArgumentError, "headers must be a Hash" unless headers.is_a?(Hash)
+
+          headers.to_h { |key, value| [key.to_s, value.to_s] }
+        end
+
+        def serialize_body(body, headers)
+          return [nil, headers] if body.nil?
+          return [body, headers] if body.is_a?(String)
+          return [JSON.generate(body), headers.merge("Content-Type" => "application/json")] if body.is_a?(Hash)
+
+          raise ArgumentError, "body must be a String, Hash, or nil"
+        end
+
+        def with_total_timeout(&)
+          return yield unless @total_timeout
+
+          ::Timeout.timeout(@total_timeout, &)
+        end
+
+        def sensitive_header?(key)
+          key = key.downcase
+          key.include?("authorization") || key.include?("api-key") || key.include?("token")
+        end
+
+        def normalize_response(response)
+          return response if response.is_a?(Response)
+
+          unless response.respond_to?(:status) && response.respond_to?(:headers) && response.respond_to?(:body)
+            raise ArgumentError, "transport must return an HTTP::Response"
+          end
+
+          Response.new(status: response.status, headers: response.headers, body: response.body)
+        end
+      end
+    end
+  end
+end

data/lib/sender/core/message.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Sender
+  module Core
+    # Immutable provider-neutral outbound message.
+    class Message
+      # @return [String] normalized recipient address
+      attr_reader :to
+      # @return [String] message body
+      attr_reader :body
+      # @return [Hash] application metadata
+      attr_reader :metadata
+      # @return [Array<Symbol>] required provider capabilities
+      attr_reader :requirements
+
+      # @param to [String] recipient address
+      # @param body [String] message body
+      # @param metadata [Hash] optional application metadata
+      # @param requirements [Array<Symbol>] required provider capabilities
+      def initialize(to:, body:, metadata: {}, requirements: [])
+        @to = normalize_recipient(to)
+        @body = validate_body(body)
+        @metadata = normalize_metadata(metadata)
+        @requirements = Capabilities.normalize(requirements)
+        freeze
+      end
+
+      private
+
+      def normalize_recipient(value)
+        raise ArgumentError, "to must be a String" unless value.is_a?(String)
+
+        recipient = value.strip
+        raise ArgumentError, "to must not be empty" if recipient.empty?
+
+        recipient
+      end
+
+      def validate_body(value)
+        raise ArgumentError, "body must be a String" unless value.is_a?(String)
+        raise ArgumentError, "body must not be empty" if value.strip.empty?
+
+        value.dup.freeze
+      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/observability.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Sender
+  module Core
+    # Namespace for dependency-free runtime event sinks.
+    module Observability
+      # Thread-safe in-memory event sink with optional subscribers.
+      class Memory
+        def initialize
+          @events = []
+          @subscribers = []
+          @lock = Mutex.new
+        end
+
+        # Record an event and notify subscribers.
+        # @param event [Hash] structured sender event
+        # @return [Hash] frozen event
+        def emit(event)
+          normalized = event.dup.freeze
+          @lock.synchronize do
+            @events << normalized
+            @subscribers.each { |subscriber| subscriber.call(normalized) }
+          end
+          normalized
+        end
+
+        # Subscribe a callable to future events.
+        # @param subscriber [#call] event subscriber
+        def subscribe(subscriber = nil, &block)
+          callback = subscriber || block
+          raise ArgumentError, "subscriber must respond to call" unless callback.respond_to?(:call)
+
+          @lock.synchronize { @subscribers << callback }
+          callback
+        end
+
+        # @return [Array<Hash>] immutable event history
+        def events
+          @lock.synchronize { @events.dup.freeze }
+        end
+
+        # Clear recorded events.
+        def clear
+          @lock.synchronize { @events.clear }
+        end
+      end
+    end
+  end
+end

data/lib/sender/core/provider.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Sender
+  module Core
+    # Base contract implemented by provider adapters.
+    class Provider
+      # @return [ProviderConfiguration] provider configuration
+      attr_reader :configuration
+
+      # @param configuration [ProviderConfiguration] provider configuration
+      def initialize(configuration:)
+        unless configuration.is_a?(ProviderConfiguration)
+          raise ArgumentError, "configuration must be a ProviderConfiguration"
+        end
+
+        @configuration = configuration
+      end
+
+      # @return [Symbol] provider name
+      def name
+        configuration.name
+      end
+
+      # @return [Array<Symbol>] provider capabilities
+      def capabilities
+        configuration.capabilities
+      end
+
+      # Deliver a normalized message through the provider.
+      #
+      # @raise [NotImplementedError] when called on the base contract
+      def deliver(_message)
+        raise NotImplementedError, "provider adapters must implement #deliver"
+      end
+    end
+  end
+end

data/lib/sender/core/provider_configuration.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Sender
+  module Core
+    # Immutable configuration shared by provider adapters.
+    class ProviderConfiguration
+      attr_reader :name, :settings, :enabled, :priority, :capabilities
+
+      # @param name [Symbol, String] provider name
+      # @param settings [Hash] provider-specific settings
+      # @param enabled [Boolean] whether the provider may be used
+      # @param priority [Integer] static provider preference
+      # @param capabilities [Array<Symbol>] advertised capabilities
+      def initialize(name:, settings: {}, enabled: true, priority: 0, capabilities: [])
+        @name = normalize_name(name)
+        @settings = normalize_settings(settings)
+        @enabled = validate_enabled(enabled)
+        @priority = validate_priority(priority)
+        @capabilities = normalize_capabilities(capabilities)
+        freeze
+      end
+
+      # @param key [Symbol, String] setting name
+      # @return [Object, nil] configured setting
+      def [](key)
+        settings[key] || settings[key.to_sym]
+      end
+
+      # @return [Boolean] whether this configuration has been enabled
+      def enabled?
+        enabled
+      end
+
+      private
+
+      def normalize_name(value)
+        name = value.to_sym
+        raise ArgumentError, "name must not be empty" if name.empty?
+
+        name
+      rescue NoMethodError
+        raise ArgumentError, "name must be symbolizable"
+      end
+
+      def normalize_settings(value)
+        raise ArgumentError, "settings must be a Hash" unless value.is_a?(Hash)
+
+        value.dup.freeze
+      end
+
+      def validate_enabled(value)
+        return value if [true, false].include?(value)
+
+        raise ArgumentError, "enabled must be true or false"
+      end
+
+      def validate_priority(value)
+        return value if value.is_a?(Integer)
+
+        raise ArgumentError, "priority must be an Integer"
+      end
+
+      def normalize_capabilities(value)
+        Capabilities.normalize(value)
+      end
+    end
+  end
+end

data/lib/sender/core/provider_registry.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Sender
+  module Core
+    # Catalogs, configures, and lazily loads provider adapters.
+    class ProviderRegistry
+      # Internal metadata for a registered provider.
+      Entry = Struct.new(:name, :loader, :capabilities, keyword_init: true) do
+        def load
+          adapter = loader.call
+          raise Errors::ConfigurationError, "provider #{name} loader did not return a class" unless adapter.is_a?(Class)
+
+          adapter
+        end
+      end
+
+      # Empty by default; channel gems register their provider adapters.
+      DEFAULT_PROVIDERS = {}.freeze
+
+      # @param catalog [Hash] provider names mapped to adapter paths
+      # @param default_capabilities [Array<Symbol>] catalog entry capabilities
+      def initialize(catalog: DEFAULT_PROVIDERS, default_capabilities: [])
+        @entries = {}
+        @configurations = {}
+        catalog.each do |name, path|
+          register(name, loader: lazy_loader(path), capabilities: default_capabilities)
+        end
+      end
+
+      # @return [Array<Symbol>] providers known to the registry
+      def supported
+        @entries.keys.freeze
+      end
+
+      # @return [Array<Symbol>] configured providers
+      def configured
+        @configurations.keys.freeze
+      end
+
+      # Register a provider without loading its adapter.
+      # @param name [Symbol, String] provider name
+      # @param loader [#call] callable returning the adapter class
+      # @param capabilities [Array<Symbol>] advertised capabilities
+      def register(name, loader:, capabilities: [:sms])
+        provider_name = normalize_name(name)
+        raise ArgumentError, "loader must respond to call" unless loader.respond_to?(:call)
+        raise ArgumentError, "provider already registered: #{provider_name}" if @entries.key?(provider_name)
+
+        @entries[provider_name] = Entry.new(
+          name: provider_name,
+          loader: loader,
+          capabilities: normalize_capabilities(capabilities)
+        ).freeze
+        provider_name
+      end
+
+      # Configure a registered provider without loading its adapter.
+      # @return [ProviderConfiguration] the stored configuration
+      def configure(name, settings: {}, enabled: true, priority: 0, capabilities: nil)
+        entry = fetch_entry(name)
+        configuration = ProviderConfiguration.new(
+          name: entry.name,
+          settings: settings,
+          enabled: enabled,
+          priority: priority,
+          capabilities: capabilities || entry.capabilities
+        )
+        @configurations[entry.name] = configuration
+      end
+
+      # Instantiate a configured provider, loading its adapter on demand.
+      # @return [Provider] configured provider adapter
+      def provider(name)
+        entry = fetch_entry(name)
+        configuration = @configurations.fetch(entry.name) do
+          raise Errors::ConfigurationError, "provider is not configured: #{entry.name}"
+        end
+        entry.load.new(configuration: configuration)
+      rescue LoadError => e
+        raise Errors::ConfigurationError, "could not load provider #{entry.name}: #{e.message}"
+      end
+
+      # @return [Array<Provider>] instantiated configured providers
+      def providers
+        configured.map { |name| provider(name) }
+      end
+
+      private
+
+      def fetch_entry(name)
+        @entries.fetch(normalize_name(name)) do
+          raise Errors::ConfigurationError, "unknown provider: #{name.inspect}"
+        end
+      end
+
+      def lazy_loader(path)
+        lambda do
+          require path
+          constant_name = path.split("/").last.split("_").map(&:capitalize).join
+          Sender::Core.const_get(:Providers).const_get(constant_name)
+        end
+      end
+
+      def normalize_name(value)
+        name = value.to_sym
+        raise ArgumentError, "provider name must not be empty" if name.empty?
+
+        name
+      rescue NoMethodError
+        raise ArgumentError, "provider name must be symbolizable"
+      end
+
+      def normalize_capabilities(value)
+        raise ArgumentError, "capabilities must be an Array" unless value.is_a?(Array)
+
+        value.map(&:to_sym).uniq.freeze
+      rescue NoMethodError
+        raise ArgumentError, "capabilities must contain symbolizable values"
+      end
+    end
+  end
+end