unisender-ruby 0.1.1 → 0.2.0

data/lib/unisender/downloader.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "openssl"
+
+module Unisender
+  DownloadReceipt = Data.define(:bytes_written, :http_status)
+
+  # A failed transfer can leave a partial result in the caller's destination.
+  class DownloadError < Error
+    attr_reader :reason, :bytes_written, :http_status
+
+    def category
+      :download
+    end
+
+    def initialize(reason:, bytes_written: 0, http_status: nil)
+      @reason = reason
+      @bytes_written = bytes_written
+      @http_status = http_status
+      super("Download failed: #{reason}")
+    end
+  end
+
+  # Downloads use a separate credential-free connection and never follow redirects.
+  class Downloader
+    def initialize(open_timeout: 5, read_timeout: 60, write_timeout: 30, resolver: nil, http_factory: nil)
+      unless [open_timeout, read_timeout, write_timeout].all? do |value|
+        value.is_a?(Numeric) && value.positive? && value.finite?
+      end
+        raise ArgumentError, "Download timeouts must be positive and finite"
+      end
+
+      @open_timeout = open_timeout
+      @read_timeout = read_timeout
+      @write_timeout = write_timeout
+      @target = DownloadTarget.new(timeout: open_timeout, resolver:)
+      @http_factory = http_factory || ->(uri, address) { build_http(uri, address) }
+    end
+
+    def download(url, io, max_bytes:, execution: nil)
+      transfer = DownloadTransfer.new(io, max_bytes, execution:)
+      execute(url, transfer, execution)
+    end
+
+    private
+
+    def execute(url, transfer, execution)
+      response = download_response(url, transfer, execution)
+      DownloadReceipt.new(bytes_written: transfer.bytes_written, http_status: response.code.to_i)
+    rescue CancelledError, DeadlineExceededError => e
+      raise e.with_download(bytes_written: transfer.bytes_written), cause: nil
+    rescue DownloadError => e
+      raise DownloadError.new(reason: e.reason, bytes_written: transfer.bytes_written, http_status: e.http_status),
+            cause: nil
+    rescue StandardError
+      raise DownloadError.new(reason: :transport, bytes_written: transfer.bytes_written), cause: nil
+    end
+
+    def download_response(url, transfer, execution)
+      execution&.check!
+      uri, address = @target.resolve(url)
+      http = configured_http(uri, address, execution)
+      http.start do |connection|
+        request = Net::HTTP::Get.new(uri, { "Accept-Encoding" => "identity" })
+        connection.request(request) { |reply| stream(reply, transfer) }
+      end
+    end
+
+    def build_http(uri, address)
+      http = Net::HTTP.new(uri.hostname.to_s, uri.port, nil)
+      http.ipaddr = address
+      http
+    end
+
+    def configured_http(uri, address, execution = nil)
+      http = @http_factory.call(uri, address)
+      remaining = execution&.remaining
+      http.use_ssl = true
+      http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+      http.open_timeout = remaining ? [@open_timeout, remaining].min : @open_timeout
+      http.read_timeout = remaining ? [@read_timeout, remaining].min : @read_timeout
+      http.write_timeout = remaining ? [@write_timeout, remaining].min : @write_timeout
+      http.max_retries = 0
+      http
+    end
+
+    def stream(response, transfer)
+      status = response.code.to_i
+      raise DownloadError.new(reason: :http_error, http_status: status) unless (200..299).cover?(status)
+
+      response.read_body { |chunk| transfer.write(chunk) }
+      length = response["content-length"]
+      return unless length&.match?(/\A\d+\z/) && transfer.bytes_written != length.to_i
+
+      raise DownloadError.new(reason: :incomplete)
+    end
+  end
+end

data/lib/unisender/error_diagnostics.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Unisender
+  # Stable categories and safe recovery hints supplement the upstream details.
+  class Error
+    HINTS = {
+      authentication: "Check the API key.", authorization: "Check API access and account permissions.",
+      invalid_argument: "Check the operation parameters.", payment: "Check the account balance.",
+      rate_limit: "Wait before another request; check whether repeating this operation is safe.",
+      not_found: "Check the requested identifier.", client_closed: "Create an open client before making a request.",
+      pagination_limit: "Resume from next_offset with an explicit page budget.",
+      task_failed: "Inspect the task response before starting another task.",
+      task_state: "Inspect the task response and documented states.",
+      unknown_task_state: "Inspect the task response and update the supported task states.",
+      partial_failure: "Reconcile accepted records before retrying rejected records.",
+      download: "Inspect the download reason and discard or retain partial output explicitly."
+    }.freeze
+    def self.safe_operation(operation)
+      OPERATIONS.include?(operation) ? operation.dup.freeze : nil
+    end
+
+    def category
+      error = self # : Error
+      case error
+      when APIError then api_category(error.code)
+      when HTTPError then http_category(error.response.http_status)
+      when InvalidResponseError then :invalid_response
+      when TimeoutError then :timeout
+      when TransportError then :transport
+      else :unknown
+      end
+    end
+
+    def transient?
+      error = self # : Error
+      case error
+      when APIError then RetryPolicy::TRANSIENT_CODES.include?(error.code)
+      when HTTPError then [429, 502, 503, 504].include?(error.response.http_status)
+      when TimeoutError then true
+      when TransportError then error.retryable?
+      else false
+      end
+    end
+
+    def safe_to_retry?
+      name = operation
+      name.is_a?(String) && RetryPolicy::READ_ONLY.include?(name) && transient?
+    end
+
+    def request_id
+      response = diagnostic_response
+      @context_request_id || response&.headers&.[]("x-request-id")
+    end
+
+    def recovery_hint
+      HINTS.fetch(category, "Inspect the failure and reconcile mutations before repeating the operation.")
+    end
+
+    private
+
+    def api_category(code)
+      case code
+      when "invalid_api_key" then :authentication
+      when "access_denied" then :authorization
+      when "invalid_arg" then :invalid_argument
+      when "not_enough_money" then :payment
+      when "retry_later" then :transient
+      when "api_call_limit_exceeded_for_api_key", "api_call_limit_exceeded_for_ip" then :rate_limit
+      else :unknown
+      end
+    end
+
+    def http_category(status)
+      case status
+      when 401 then :authentication
+      when 403 then :authorization
+      when 429 then :rate_limit
+      when 500..599 then :service_unavailable
+      else :http
+      end
+    end
+  end
+end

data/lib/unisender/errors.rb

@@ -13,11 +13,62 @@ module Unisender
       createEmailTemplate deleteTemplate getTemplate getTemplates listTemplates updateEmailTemplate
       createField deleteField deleteTag getFields getTags updateField getContactFieldValues
       createSubscriberNote updateSubscriberNote deleteSubscriberNote getSubscriberNote getSubscriberNotes
-      track_events
+      track_events setHook listHooks removeHook
     ].freeze
     private_constant :OPERATIONS
 
-    attr_reader :operation
+    attr_reader :operation, :next_offset, :completed_pages, :last_response
+
+    def diagnostics
+      Diagnostics.for_error(self)
+    end
+
+    def documentation_url
+      Diagnostics::URLS[@operation.to_s]
+    end
+
+    def with_http(status:, request_id:)
+      @context_http_status = status
+      @context_request_id = request_id&.dup&.freeze
+      self
+    end
+
+    def http_status
+      response = diagnostic_response
+      @context_http_status || response&.http_status
+    end
+
+    def diagnostic_response
+      error = self # : Error
+      case error
+      when APIError, HTTPError, PartialFailure, TaskError, TaskTimeoutError then error.response
+      end
+    end
+
+    def bytes_written
+      @download_bytes_written
+    end
+
+    def with_download(bytes_written:)
+      @download_bytes_written = bytes_written
+      self
+    end
+
+    def task_uuid
+      @polling_task_uuid
+    end
+
+    def with_task(task_uuid:, last_response:)
+      @polling_task_uuid = task_uuid.dup.freeze
+      @last_response = last_response
+      self
+    end
+
+    def with_pagination(next_offset:, completed_pages:)
+      @next_offset = next_offset
+      @completed_pages = completed_pages
+      self
+    end
 
     def with_operation(operation)
       @operation = OPERATIONS.include?(operation) ? operation.dup.freeze : nil
@@ -44,6 +95,11 @@ module Unisender
 
     attr_reader :response, :code, :details
 
+    def safe_code
+      code = @code
+      code if code.is_a?(String) && SAFE_CODES.include?(code)
+    end
+
     def initialize(response)
       @response = response
       @code = response.data["code"]
@@ -58,11 +114,30 @@ module Unisender
 
     def initialize(response)
       @response = response
-      super("HTTP #{response.status}")
+      super("HTTP #{response.http_status}")
     end
   end
 
-  class InvalidResponseError < Error; end
+  # A malformed response with optional safe structural context.
+  class InvalidResponseError < Error
+    attr_reader :path, :expected_type, :actual_type
+
+    def initialize(message = "Invalid response", path: nil, expected_type: nil, actual_type: nil)
+      @path = path
+      @expected_type = expected_type
+      @actual_type = actual_type
+      super(message)
+    end
+
+    def prepend_path(prefix)
+      @path = @path ? "#{prefix}.#{@path}".freeze : prefix.dup.freeze
+      self
+    end
+
+    def to_s
+      @path ? "#{super} at #{@path}" : super
+    end
+  end
 
   # Network or TLS failure with no complete HTTP response.
   class TransportError < Error
@@ -80,6 +155,10 @@ module Unisender
 
   # A failed event request can still have accepted some events (HTTP 400).
   class EventError < HTTPError
+    def report
+      EventResult.new({ "success" => false, "uncertain" => response.http_status != 401 })
+    end
+
     def code
       response.data["code"]
     end
@@ -89,26 +168,60 @@ module Unisender
     end
 
     def possibly_partially_accepted?
-      response.status == 400
+      response.http_status == 400
     end
   end
 
   # Carries the completed batches and the range whose outcome needs inspection.
   class BatchError < Error
-    attr_reader :completed_responses, :failed_range, :error
+    attr_reader :completed_responses, :failed_range, :error, :report
 
-    def initialize(completed_responses:, failed_range:, error:)
+    def initialize(completed_responses:, failed_range:, error:, report: nil)
       @completed_responses = completed_responses.dup.freeze
       @failed_range = failed_range.freeze
       @error = error
+      @report = report || BatchReport.new(@completed_responses, error:, failed_range:)
       super("UniSender batch failed; inspect the completed responses and failed range")
     end
+
+    def category
+      error = @error
+      error.is_a?(Error) || error.is_a?(ValidationError) ? error.category : :unexpected
+    end
+
+    def request_id
+      error = @error
+      error.request_id if error.is_a?(Error)
+    end
   end
 
-  class PaginationError < Error; end
+  # Identifies the next unread offset when the page bound is reached.
+  class PaginationError < Error
+    def category
+      :pagination_limit
+    end
+
+    def initialize(operation:, next_offset:, completed_pages:)
+      @operation = operation
+      @next_offset = next_offset
+      @completed_pages = completed_pages
+      super("Pagination page limit reached")
+    end
+  end
+
+  # A singular operation returned no matching record.
+  class NotFoundError < Error
+    def category
+      :not_found
+    end
+  end
 
   # The API accepted the import request but rejected some records.
   class PartialFailure < Error
+    def category
+      :partial_failure
+    end
+
     attr_reader :response
 
     def initialize(response)
@@ -119,6 +232,10 @@ module Unisender
 
   # Includes the last response for an unexpected or failed asynchronous task state.
   class TaskError < Error
+    def category
+      :task_state
+    end
+
     attr_reader :response
 
     def initialize(response)

data/lib/unisender/event_batches.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Unisender
+  # Chooses request boundaries before sending any event in a chunk.
+  module EventBatches
+    def self.each(events, size)
+      Batches.validate_size(size, 25)
+      Enumerator.new { |output| build(events, size, output) }
+    end
+
+    def self.build(events, size, output)
+      # @type var batch: Array[params]
+      batch = []
+      events.each_with_index do |event, index|
+        validate(event, index)
+        batch = append(batch, event, size, output)
+      end
+      output << batch unless batch.empty?
+    end
+
+    def self.append(batch, event, size, output)
+      if EventPayload.serialize(batch + [event]).bytesize > EventPayload::MAX_BYTES
+        output << batch
+        batch = [] # : Array[params]
+      end
+      batch << event
+      return batch unless batch.size == size
+
+      output << batch
+      []
+    end
+
+    def self.validate(event, index)
+      EventPayload.encode([event])
+    rescue ArgumentError
+      raise ValidationError.new(field: "events[#{index}]", code: :invalid_event, operation: "track_events", index:),
+            cause: nil
+    end
+  end
+end

data/lib/unisender/event_payload.rb

@@ -3,59 +3,87 @@
 module Unisender
   # Event Tracking uses JSON with its own batch and payload limits.
   module EventPayload
+    MAX_BYTES = 130 * 1024
+
     def self.encode(events)
-      raise ArgumentError, "Expected 1 to 25 events" unless (1..25).cover?(events.size)
+      unless events.is_a?(Array)
+        raise ValidationError.new(field: "events", code: :invalid_type, expected_type: "Array",
+                                  actual_type: Diagnostics.type_name(events))
+      end
+      raise ValidationError.new(field: "events", code: :invalid_count) unless (1..25).cover?(events.size)
 
-      normalized = events.map { |event| validate(normalize(event, 0)) }
-      body = JSON.generate({ "events" => normalized })
-      raise ArgumentError, "Event payload exceeds 130 KB" if body.bytesize > 130 * 1024
+      body = serialize(events)
+      raise ValidationError.new(field: "events", code: :too_large) if body.bytesize > MAX_BYTES
 
       body
+    end
+
+    def self.serialize(events)
+      normalized = events.each_with_index.map do |event, index|
+        path = "events[#{index}]"
+        validate(normalize(with_timestamp(event), 0, path), path)
+      end
+      JSON.generate({ "events" => normalized })
     rescue EncodingError, JSON::GeneratorError
-      raise ArgumentError, "Events must contain valid JSON values and UTF-8 text", cause: nil
+      raise ValidationError.new(field: "events", code: :invalid_encoding), cause: nil
     end
 
-    def self.validate(event)
-      raise ArgumentError, "Each event must be an object" unless event.is_a?(Hash)
-      raise ArgumentError, "Each event may have at most 25 fields" if event.size > 25
+    def self.with_timestamp(event)
+      return event unless event.is_a?(Hash)
+
+      event.to_h do |key, value|
+        item = key.to_s == "created" && value.is_a?(Time) ? value.getutc.strftime("%Y-%m-%d %H:%M:%S") : value
+        [key, item]
+      end
+    end
+
+    def self.validate(event, path)
+      unless event.is_a?(Hash)
+        raise ValidationError.new(field: path, code: :invalid_type, expected_type: "Hash",
+                                  actual_type: Diagnostics.type_name(event))
+      end
+      raise ValidationError.new(field: path, code: :too_many_fields) if event.size > 25
 
-      validate_name(event["name"])
-      validate_email(event["email"])
+      validate_name(event["name"], "#{path}.name")
+      validate_email(event["email"], "#{path}.email")
       event
     end
 
-    def self.validate_name(name)
+    def self.validate_name(name, path)
       return if name.is_a?(String) && (1..40).cover?(name.size)
 
-      raise ArgumentError, "Event name must contain 1 to 40 characters"
+      raise ValidationError.new(field: path, code: :invalid_name, expected_type: "String",
+                                actual_type: Diagnostics.type_name(name))
     end
 
-    def self.validate_email(email)
+    def self.validate_email(email, path)
       return if email.is_a?(String) && email.ascii_only? && email.match?(/\A[^\s@]+@[^\s@]+\z/)
 
-      raise ArgumentError, "Event email must be an ASCII email address"
+      raise ValidationError.new(field: path, code: :invalid_email, expected_type: "String",
+                                actual_type: Diagnostics.type_name(email))
     end
 
-    def self.normalize(value, depth)
-      raise ArgumentError, "Events are nested too deeply" if depth > 32
+    def self.normalize(value, depth, path)
+      raise ValidationError.new(field: path, code: :too_deep) if depth > 32
 
       case value
-      when Hash then normalize_hash(value, depth)
-      when Array then value.map { |item| normalize(item, depth + 1) }
+      when Hash then normalize_hash(value, depth, path)
+      when Array then value.each_with_index.map { |item, index| normalize(item, depth + 1, "#{path}[#{index}]") }
       when String then value.encode(Encoding::UTF_8)
       when Integer, Float, true, false, nil then value
-      else raise ArgumentError, "Unsupported JSON value"
+      else raise ValidationError.new(field: path, code: :invalid_type, actual_type: Diagnostics.type_name(value))
       end
     end
 
-    def self.normalize_hash(value, depth)
+    def self.normalize_hash(value, depth, path)
       # @type var result: Hash[String, json]
       result = {}
       value.each do |key, item|
         name = key.to_s.encode(Encoding::UTF_8)
-        raise ArgumentError, "Duplicate event field names" if result.key?(name)
+        raise ValidationError.new(field: path, code: :duplicate_key) if result.key?(name)
 
-        result[name] = normalize(item, depth + 1)
+        field = Diagnostics::FIELDS.include?(name) ? name : "*"
+        result[name] = normalize(item, depth + 1, "#{path}.#{field}")
       end
       result
     end

data/lib/unisender/events.rb

@@ -5,15 +5,31 @@ module Unisender
   class Client
     def track_events(events:)
       body = EventPayload.encode(events)
-      headers = { "Content-Type" => "application/json", "Authorization" => "Bearer #{@api_key}" }
-      http = @transport.post(URI("https://event.unisender.com/v1/events/"), headers:, body:)
+      headers = { "Content-Type" => "application/json", "Authorization" => "Bearer #{@api_key}",
+                  "User-Agent" => USER_AGENT }
+      exchange("track_events", URI("https://event.unisender.com/v1/events/"), headers:, body:,
+                                                                              input_count: events.size) do |http|
+        decode_event_response(http, events.size)
+      end
+    rescue Error, ValidationError => e
+      raise e.with_operation("track_events"), cause: nil
+    end
+
+    private
+
+    def decode_event_response(http, count)
+      response = parse_event_response(http)
+      observe_acceptance("track_events", count, response, nil)
+      response
+    end
+
+    def parse_event_response(http)
       response = Response.new(data: Protocol.decode(http), status: http.status, headers: http.headers)
       raise EventError, response, cause: nil unless (200..299).cover?(http.status)
       raise InvalidResponseError, "Missing event success status", cause: nil unless response.data["success"] == true
 
-      response # : Response[event_accepted]
-    rescue Error => e
-      raise e.with_operation("track_events"), cause: nil
+      EventResponse.new(data: response.data, status: response.http_status, headers: response.headers,
+                        result: EventResult.new(response.data))
     end
   end
 end

data/lib/unisender/execution_context.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Unisender
+  # Thread-safe cooperative cancellation. It never interrupts in-flight work.
+  class CancellationToken
+    def initialize
+      @cancelled = false
+      @mutex = Mutex.new
+    end
+
+    def cancel
+      @mutex.synchronize { @cancelled = true }
+    end
+
+    def cancelled?
+      @mutex.synchronize { @cancelled }
+    end
+  end
+
+  # Cancellation reached a cooperative boundary.
+  class CancelledError < Error
+    def category
+      :cancelled
+    end
+  end
+
+  # The shared monotonic budget expired at a cooperative boundary.
+  class DeadlineExceededError < Error
+    def category
+      :deadline_exceeded
+    end
+  end
+
+  # Separate from request-attempt measurements and free of payloads.
+  ExecutionEvent = Data.define(:kind, :operation, :duration, :outcome)
+
+  # One monotonic budget shared by all work in a scoped client.
+  class ExecutionContext
+    def initialize(timeout: nil, cancellation: nil, parent: nil, instrumentation: nil, clock: nil)
+      if timeout && !(timeout.is_a?(Numeric) && timeout.positive? && timeout.finite?)
+        raise ArgumentError, "Execution timeout must be positive and finite"
+      end
+
+      @clock = clock || -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+      @deadline = @clock.call + Float(timeout) if timeout
+      @cancellation = cancellation
+      @parent = parent
+      @instrumentation = instrumentation
+      @closed = false
+      @owned_clients = []
+    end
+
+    def check!
+      raise ClientClosedError, "Execution scope is closed" if @closed
+
+      @parent&.check!
+      raise CancelledError, "Execution cancelled" if @cancellation&.cancelled?
+
+      deadline = @deadline
+      raise DeadlineExceededError, "Execution deadline exceeded" if deadline && @clock.call >= deadline
+    end
+
+    def close
+      @closed = true
+      @owned_clients.each(&:close)
+      @owned_clients.clear
+    end
+
+    def own(client)
+      @owned_clients << client
+    end
+
+    def remaining
+      check!
+      deadline = @deadline
+      values = [deadline ? deadline - @clock.call : nil, @parent&.remaining].compact
+      values.min
+    end
+
+    def wait(delay, kind, operation, sleeper)
+      measure(kind, operation) do
+        endpoint = @clock.call + delay
+        loop do
+          check!
+          remaining = endpoint - @clock.call
+          break unless remaining.positive?
+
+          sleeper.call([remaining, 0.05].min)
+        end
+      end
+    end
+
+    def measure(kind, operation)
+      started = @clock.call
+      outcome = :failure
+      begin
+        result = yield
+        outcome = :success
+        result
+      ensure
+        emit(ExecutionEvent.new(kind:, operation: Error.safe_operation(operation) || "workflow",
+                                duration: @clock.call - started, outcome:))
+      end
+    end
+
+    private
+
+    def emit(event)
+      @instrumentation&.call(event)
+    rescue StandardError
+      nil
+    end
+  end
+end