unisender-ruby 0.1.1 → 0.2.0

data/lib/unisender/outcomes.rb

@@ -0,0 +1,320 @@
+# frozen_string_literal: true
+
+module Unisender
+  # Shared decoding for error records inside successful envelopes.
+  module Outcomes
+    def self.records(value, path)
+      return [] if value.nil?
+      unless value.is_a?(Array)
+        raise InvalidResponseError.new("Expected result records", path:, expected_type: "Array",
+                                                                  actual_type: Diagnostics.type_name(value))
+      end
+
+      value.each_with_index.map { |item, index| record(item, "#{path}[#{index}]") }
+    end
+
+    def self.record(item, path)
+      return item if item.is_a?(Record)
+
+      raise InvalidResponseError.new("Expected result record", path:, expected_type: "Hash",
+                                                               actual_type: Diagnostics.type_name(item))
+    end
+
+    def self.failures(value, path, overrides = {})
+      records(value, path).each_with_index.map { |item, index| failure(item, "#{path}[#{index}]", overrides) }
+    end
+
+    def self.failure(item, path, overrides)
+      Failure.new(item.to_h.merge(overrides))
+    rescue InvalidResponseError => e
+      raise e.prepend_path(path), cause: nil
+    end
+  end
+
+  # A record position and its upstream diagnostic, kept out of inspection output.
+  class Failure < Record
+    def index
+      self["index"].nil? ? nil : integer!("index")
+    end
+
+    def code
+      text("code")
+    end
+
+    def message
+      text("message")
+    end
+
+    def warning?
+      value = code
+      value.is_a?(String) && value.start_with?("w_")
+    end
+
+    def with_offset(offset)
+      position = index
+      return self unless position
+
+      Failure.new(to_h.merge("index" => position + offset))
+    end
+
+    protected
+
+    def normalize
+      @values["index"] = index if @values.key?("index")
+      code
+      message
+    end
+  end
+
+  # Import acceptance is distinct from recipient delivery.
+  class ImportResult < Record
+    OPTIONAL_COUNTERS = %w[inserted updated deleted new_emails].freeze
+
+    def inserted
+      integer("inserted")
+    end
+
+    def updated
+      integer("updated")
+    end
+
+    def deleted
+      integer("deleted")
+    end
+
+    def new_emails
+      integer("new_emails")
+    end
+
+    def invalid
+      integer!("invalid")
+    end
+
+    def total
+      self["total"].nil? ? nil : integer!("total")
+    end
+
+    def failures
+      Outcomes.failures(self["log"], "log").reject(&:warning?)
+    end
+
+    def row_warnings
+      Outcomes.failures(self["log"], "log").select(&:warning?)
+    end
+
+    def complete?
+      invalid.zero?
+    end
+
+    def uncertain?
+      invalid.positive? && total.nil?
+    end
+
+    def partial?
+      count = total
+      count.is_a?(Integer) && invalid.positive? && invalid < count
+    end
+
+    protected
+
+    def normalize
+      @values["invalid"] = invalid
+      @values["total"] = total if @values.key?("total")
+      OPTIONAL_COUNTERS.each { |name| @values[name] = integer(name) if @values.key?(name) }
+      failures
+    end
+  end
+
+  # Per-recipient acceptance from sendEmail with error_checking enabled.
+  class RecipientResult < Record
+    def id
+      self["id"].nil? ? nil : identifier!("id")
+    end
+
+    def index
+      self["index"].nil? ? nil : integer!("index")
+    end
+
+    def email
+      text("email")
+    end
+
+    def failures
+      Outcomes.failures(self["errors"], "errors", { "index" => index })
+    end
+
+    def accepted?
+      !id.nil? && failures.empty?
+    end
+
+    protected
+
+    def normalize
+      id
+      index
+      email
+      failures
+    end
+  end
+
+  # Handles both documented sendEmail result formats.
+  class SendResult < Record
+    def accepted_recipients
+      recipients.select(&:accepted?).freeze
+    end
+
+    def rejected_recipients
+      recipients.reject { |recipient| recipient.failures.empty? }.freeze
+    end
+
+    def unknown_recipients
+      recipients.reject { |recipient| recipient.accepted? || !recipient.failures.empty? }.freeze
+    end
+
+    def accepted_ids
+      legacy = email_id
+      (legacy ? [legacy] : accepted_recipients.filter_map(&:id)).freeze
+    end
+
+    def recipients
+      Outcomes.records(self["recipients"], "recipients").each_with_index.map do |item, index|
+        child(RecipientResult, item.to_h, "recipients[#{index}]")
+      end
+    end
+
+    def email_id
+      self["email_id"].nil? ? nil : identifier!("email_id")
+    end
+
+    def failures
+      recipients.flat_map(&:failures)
+    end
+
+    def complete?
+      return true if email_id
+
+      !recipients.empty? && recipients.all?(&:accepted?)
+    end
+
+    def uncertain?
+      return false if email_id
+
+      recipients.empty? || recipients.any? { |item| !item.accepted? && item.failures.empty? }
+    end
+
+    def partial?
+      !complete? && recipients.any?(&:accepted?)
+    end
+
+    protected
+
+    def normalize
+      email_id
+      recipients
+    end
+  end
+
+  # Event failures can have an unknown number of accepted events.
+  class EventResult < Record
+    def complete?
+      self["success"] == true
+    end
+
+    def partial?
+      false
+    end
+
+    def uncertain?
+      self["uncertain"] == true
+    end
+
+    def failures
+      []
+    end
+  end
+
+  # Uniform acceptance inspection for supported report responses.
+  class OutcomeResponse < ObjectResponse
+    def complete?
+      result.complete?
+    end
+
+    def partial?
+      result.partial?
+    end
+
+    def uncertain?
+      result.uncertain?
+    end
+
+    def failures
+      result.failures
+    end
+
+    def raise_for_partial_failure!
+      raise PartialFailure, self unless complete?
+
+      self
+    end
+  end
+
+  # Import counters and acceptance state.
+  class ImportResponse < OutcomeResponse
+    def row_warnings
+      result.row_warnings
+    end
+
+    def inserted
+      result.inserted
+    end
+
+    def updated
+      result.updated
+    end
+
+    def deleted
+      result.deleted
+    end
+
+    def new_emails
+      result.new_emails
+    end
+
+    def total
+      result.total
+    end
+
+    def invalid
+      result.invalid
+    end
+  end
+
+  # Per-recipient send acceptance.
+  class SendResponse < OutcomeResponse
+    def accepted_recipients
+      result.accepted_recipients
+    end
+
+    def rejected_recipients
+      result.rejected_recipients
+    end
+
+    def unknown_recipients
+      result.unknown_recipients
+    end
+
+    def accepted_ids
+      result.accepted_ids
+    end
+
+    def recipients
+      result.recipients
+    end
+
+    def email_id
+      result.email_id
+    end
+  end
+
+  class EventResponse < OutcomeResponse; end
+end

data/lib/unisender/page_response.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Unisender
+  # Pagination is explicit; ordinary Enumerable methods only visit this page.
+  class PageResponse < CollectionResponse
+    def initialize(response, client:, method:, params:)
+      @client = client
+      @method = method
+      @params = Pagination.snapshot(params)
+      super(data: response.data, status: response.http_status, headers: response.headers, result: response.result)
+    end
+
+    # rubocop:disable Layout/LineLength
+    # @type method each_page: (?max_pages: Integer) ?{ (PageResponse[Record]) -> void } -> Enumerator[PageResponse[Record], void]
+    # rubocop:enable Layout/LineLength
+    def each_page(max_pages: 1000, &)
+      size = @params.fetch(:limit, 100) # : Integer
+      pager = Pagination.new(@client, @method, size, max_pages, @params.except(:limit), first_page: self)
+      Iteration.call(pager.each, &) # : Enumerator[PageResponse[Record], void]
+    end
+
+    # @type method auto_each: (?max_pages: Integer) ?{ (Record) -> void } -> Enumerator[Record, void]
+    def auto_each(max_pages: 1000, &)
+      Iteration.call(Iteration.items(each_page(max_pages:)), &)
+    end
+
+    def offset
+      @params.fetch(:offset, 0) # : Integer
+    end
+
+    def limit
+      @params.fetch(:limit, 100) # : Integer
+    end
+
+    def next_offset
+      count = if @method == "get_sender_domain_list"
+                result.sum do |item|
+                  raise InvalidResponseError, "Expected a sender-domain group" unless item.is_a?(SenderDomainGroup)
+
+                  item.domains.size
+                end
+              else
+                size
+              end
+      offset + count
+    end
+  end
+end

data/lib/unisender/paginated_operations.rb

@@ -21,19 +21,60 @@ module Unisender
     DEFINITIONS = definitions.transform_values(&:freeze).freeze
     private_constant :DEFINITIONS
 
+    def self.supports?(method)
+      DEFINITIONS.key?(method.to_s)
+    end
+
     def self.call(client, method, params)
+      params = prepare(method, params)
+      response = client.invoke(wire_name(method), params) # : CollectionResponse[Record]
+      PageResponse.new(response, client:, method: method.to_s, params:)
+    rescue ValidationError => e
+      raise e.with_operation(wire_name(method)), cause: nil
+    end
+
+    def self.prepare(method, params)
+      params = params.compact
+      params = params.merge(limit: params.fetch(:limit, 100))
+      wire = validate(method, params)
+      params = Inputs.normalize(wire, params)
+      validate_controls(method, params)
+      params
+    end
+
+    def self.validate(method, params)
       wire, required, allowed, = definition(method)
-      raise ArgumentError, "Unknown operation parameter" unless params.keys.all? { |key| allowed.include?(key) }
+      unless params.keys.all? do |key|
+        allowed.include?(key)
+      end
+        raise ValidationError.new(field: "parameters", code: :unknown_keyword,
+                                  operation: wire)
+      end
 
       Validation.required!(params, required.map(&:to_s))
       Validation.operation!(wire, params)
-      client.request(wire, params:) # : Response[objects]
+      wire
     end
 
     def self.page_limit(method)
       definition(method).last
     end
 
+    def self.wire_name(method)
+      definition(method).first
+    end
+
+    def self.validate_controls(method, params)
+      limit = params.fetch(:limit, 100)
+      maximum = page_limit(method)
+      unless limit.is_a?(Integer) && limit.positive? && (!maximum || limit <= maximum)
+        raise ValidationError.new(field: "limit", code: :out_of_range)
+      end
+
+      offset = params.fetch(:offset, 0)
+      raise ValidationError.new(field: "offset", code: :out_of_range) unless offset.is_a?(Integer) && offset >= 0
+    end
+
     def self.definition(method)
       DEFINITIONS.fetch(method.to_s) { raise ArgumentError, "Unsupported paginated method" }
     end

data/lib/unisender/pagination.rb

@@ -3,65 +3,98 @@
 module Unisender
   # Offset pagination is supported only for operations that document it.
   class Pagination
-    def initialize(client, method, page_size, max_pages, params)
+    # rubocop:disable-next Metrics/ParameterLists -- Adds a fetched seed page to the pagination controls.
+    def initialize(client, method, page_size, max_pages, params, first_page: nil)
       @client = client
       @method = method.to_s
       @page_size = page_size
       @max_pages = max_pages
-      @params = params.dup
+      @params = self.class.snapshot(params)
+      @first_page = first_page
+      initialize_params
+    rescue ValidationError => e
+      raise e.with_operation(PaginatedOperations.wire_name(@method)), cause: nil
+    end
+
+    def initialize_params
+      validate!(PaginatedOperations.page_limit(@method))
+      wire = PaginatedOperations.validate(@method, @params)
+      @params = self.class.snapshot(Inputs.normalize(wire, @params))
+      initial_offset
     end
 
     def each
       Enumerator.new do |pages|
-        validate!(PaginatedOperations.page_limit(@method))
         fetch_pages(pages, initial_offset)
       end
     end
 
+    def self.snapshot(params)
+      params.transform_values { |value| copy(value) }.freeze
+    end
+
+    def self.copy(value)
+      case value
+      when Hash then value.transform_values { |item| copy(item) }.freeze
+      when Array then value.map { |item| copy(item) }.freeze
+      else value.dup.freeze
+      end
+    end
+
     private
 
     def initial_offset
       offset = @params.fetch(:offset, 0)
-      raise ArgumentError, "offset must be nonnegative" unless offset.is_a?(Integer) && offset >= 0
+      raise ValidationError.new(field: "offset", code: :out_of_range) unless offset.is_a?(Integer) && offset >= 0
 
       offset
     end
 
     def fetch_pages(pages, offset)
-      @max_pages.times do
-        response = PaginatedOperations.call(@client, @method, @params.merge(limit: @page_size, offset:))
+      @max_pages.times do |index|
+        response = fetch_page(index, offset)
         count = page_length(response)
         pages << response
-        return if count < @page_size
+        return nil if count < @page_size
 
         offset += count
       end
-      raise PaginationError, "Pagination page limit reached"
+      raise PaginationError.new(operation: @method, next_offset: offset, completed_pages: @max_pages)
+    end
+
+    def fetch_page(index, offset)
+      first = @first_page
+      return first if index.zero? && first
+
+      PaginatedOperations.call(@client, @method, @params.merge(limit: @page_size, offset:))
+    rescue Error => e
+      raise e.with_pagination(next_offset: offset, completed_pages: index), cause: nil
     end
 
     def validate!(maximum)
       validate_limit!(maximum)
-      raise ArgumentError, "max_pages must be positive" unless @max_pages.is_a?(Integer) && @max_pages.positive?
-      raise ArgumentError, "Use page_size instead of limit" if @params.key?(:limit)
+      unless @max_pages.is_a?(Integer) && @max_pages.positive?
+        raise ValidationError.new(field: "max_pages",
+                                  code: :out_of_range)
+      end
+      raise ValidationError.new(field: "limit", code: :use_page_size) if @params.key?(:limit)
     end
 
     def validate_limit!(maximum)
-      raise ArgumentError, "Invalid page_size" unless @page_size.is_a?(Integer) && @page_size.positive?
-      raise ArgumentError, "page_size exceeds the method limit" if maximum && @page_size > maximum
+      unless @page_size.is_a?(Integer) && @page_size.positive?
+        raise ValidationError.new(field: "page_size",
+                                  code: :out_of_range)
+      end
+      raise ValidationError.new(field: "page_size", code: :out_of_range) if maximum && @page_size > maximum
     end
 
     def page_length(response)
-      result = response.result
-      raise InvalidResponseError, "Expected paginated result array" unless result.is_a?(Array)
+      result = response.result # : Array[Record]
       return result.size unless @method == "get_sender_domain_list"
 
       result.sum do |group|
-        raise InvalidResponseError, "Expected sender domain groups" unless group.is_a?(Hash)
-
-        domains = group["domains"]
-        raise InvalidResponseError, "Expected sender domain groups" unless domains.is_a?(Array)
-
-        domains.size
+        record = group # : SenderDomainGroup
+        record.domains.size
       end
     end
   end

data/lib/unisender/persistent_transport.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Unisender
+  # Serializes requests per client and reuses verified HTTPS connections.
+  class PersistentTransport < Transport
+    Connection = Data.define(:http, :used_at)
+    HOSTS = %w[api.unisender.com event.unisender.com].freeze
+
+    # rubocop:disable-next Metrics/ParameterLists -- Preserves transport injection and explicit timeouts.
+    def initialize(idle_timeout: 30, clock: nil, pid: nil, open_timeout: 5, read_timeout: 60,
+                   write_timeout: 30, http_factory: nil)
+      unless idle_timeout.is_a?(Numeric) && idle_timeout.positive? && idle_timeout.finite?
+        raise ArgumentError, "idle_timeout must be positive and finite"
+      end
+
+      super(open_timeout:, read_timeout:, write_timeout:, http_factory:)
+      @idle_timeout = idle_timeout
+      initialize_pool(clock, pid)
+    end
+
+    def initialize_pool(clock, pid)
+      @clock = clock || -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+      @pid_source = pid || -> { Process.pid }
+      @pid = @pid_source.call
+      @connections = {}
+      @mutex = Mutex.new
+      @closed = false
+    end
+
+    def close
+      reset_after_fork
+      @mutex.synchronize do
+        @closed = true
+        # rubocop:disable-next Style/HashEachMethods -- Snapshot keys before removing pooled entries.
+        @connections.keys.each { |key| discard(key) }
+      end
+      nil
+    end
+
+    def inspect
+      "#<Unisender::PersistentTransport>"
+    end
+
+    private
+
+    def perform(uri, request, execution:)
+      reset_after_fork
+      key = origin(uri)
+      @mutex.synchronize do
+        raise TransportError, "Transport is closed" if @closed
+
+        execution&.check!
+        send_request(key, uri, request, execution)
+      end
+    end
+
+    def send_request(key, uri, request, execution)
+      http = connection(key, uri, execution)
+      configure_timeouts(http, execution)
+      response = http.request(request)
+      @connections[key] = Connection.new(http:, used_at: @clock.call)
+      response
+    rescue StandardError
+      discard(key)
+      raise
+    end
+
+    def origin(uri)
+      unless uri.scheme == "https" && uri.port == 443 && HOSTS.include?(uri.hostname)
+        raise ArgumentError, "Persistent transport requires a UniSender API origin"
+      end
+
+      uri.hostname.to_s
+    end
+
+    def connection(key, uri, execution)
+      current = @connections[key]
+      return current.http if current && @clock.call - current.used_at < @idle_timeout
+
+      discard(key)
+      http = configured_http(uri, execution:)
+      http.start
+      @connections[key] = Connection.new(http:, used_at: @clock.call)
+      http
+    end
+
+    def discard(key)
+      http = @connections.delete(key)&.http
+      http.finish if http&.started?
+    rescue IOError, SystemCallError, OpenSSL::SSL::SSLError
+      nil
+    end
+
+    def reset_after_fork
+      current = @pid_source.call
+      return if @pid == current
+
+      # rubocop:disable-next Style/HashEachMethods -- Snapshot keys before removing pooled entries.
+      @connections.keys.each { |key| discard(key) }
+      @pid = current
+      @mutex = Mutex.new
+    end
+  end
+end