haskimail 1.0.0

data/lib/haskimail/api_object.rb

@@ -0,0 +1,294 @@
+# frozen_string_literal: true
+
+require_relative "util"
+require_relative "http/response_parser"
+
+module Haskimail
+  # Immutable wrapper around a JSON object returned by the API.
+  #
+  # Field access is lossless: the original keys are kept, and snake_case
+  # names are resolved to them on the fly.
+  #
+  #   result = client.emails.deliver(...)
+  #   result.message_id        # => "6f1c0b2d..."
+  #   result[:message_id]      # same
+  #   result["MessageID"]      # exact API key
+  #   result.to_h              # => { "MessageID" => "...", ... } (mutable deep copy)
+  #
+  # Keys that are not identifiers (e.g. "Apple Mail" in e-mail client stats)
+  # are available through #[] with either spelling: `stats["Apple Mail"]`,
+  # `stats[:apple_mail]`.
+  class ApiObject
+    # @param data [Hash] parsed API object (deep-copied and frozen)
+    def initialize(data)
+      raise ArgumentError, "ApiObject expects a Hash, got #{data.class}" unless data.is_a?(Hash)
+
+      setup(Util.deep_freeze(Util.deep_dup(data)))
+    end
+
+    # @param key [String, Symbol] exact API key or snake_case alias
+    # @return [Object, ApiObject, Array, nil]
+    def [](key)
+      original = resolve(key)
+      original.nil? ? nil : self.class.wrap(@data[original])
+    end
+
+    # Like Hash#fetch, with the same key resolution as #[].
+    def fetch(key, *default, &block)
+      original = resolve(key)
+      return self.class.wrap(@data[original]) unless original.nil?
+      return yield(key) if block
+      return default.first unless default.empty?
+
+      raise KeyError.new("key not found: #{key.inspect}", receiver: self, key: key)
+    end
+
+    # True when the key exists under any accepted spelling.
+    def key?(key)
+      !resolve(key).nil?
+    end
+    alias include? key?
+
+    # Like Hash#dig, with the same key resolution as #[].
+    def dig(key, *rest)
+      value = self[key]
+      return value if rest.empty? || value.nil?
+
+      value.respond_to?(:dig) ? value.dig(*rest) : nil
+    end
+
+    # Original API keys.
+    def keys
+      @data.keys
+    end
+
+    # Yields each original key with its (wrapped) value.
+    def each(&block)
+      return enum_for(:each) unless block
+
+      @data.each_key { |key| yield key, self[key] }
+      self
+    end
+
+    # @return [Hash] deep, mutable copy of the raw API data (String keys)
+    def to_h
+      Util.deep_dup(@data)
+    end
+    alias to_hash to_h
+
+    # JSON of the original API data.
+    def to_json(*args)
+      @data.to_json(*args)
+    end
+
+    # Value equality: same class and same data.
+    def ==(other)
+      other.instance_of?(self.class) && other.data == @data
+    end
+
+    # Strict equality (numbers compared by type too), consistent with #hash.
+    def eql?(other)
+      other.instance_of?(self.class) && other.data.eql?(@data)
+    end
+
+    # Consistent with #eql?.
+    def hash
+      [self.class, @data].hash
+    end
+
+    # Marshal support (e.g. Rails.cache): only the data is stored, and the
+    # loaded object is frozen again.
+    def marshal_dump
+      @data
+    end
+
+    # Restores an object written by #marshal_dump, frozen again.
+    # @api private
+    def marshal_load(data)
+      setup(Util.deep_freeze(data))
+    end
+
+    # Full data, for debugging.
+    def inspect
+      "#<#{self.class.name} #{@data.inspect}>"
+    end
+    alias to_s inspect
+
+    # `result.message_id` reads "MessageID". Setters, bang and predicate
+    # names are never resolved: the object is read-only.
+    def method_missing(name, *args, &block)
+      return super unless args.empty? && block.nil? && reader_name?(name)
+
+      original = resolve(name)
+      original.nil? ? super : self.class.wrap(@data[original])
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      (reader_name?(name) && !resolve(name).nil?) || super
+    end
+
+    # Key form used for case- and punctuation-insensitive lookup:
+    # "MessageID", :message_id and "message-id" all become "messageid".
+    # @api private
+    def self.normalize(key)
+      key.to_s.downcase.gsub(/[^[:alnum:]]/, "")
+    end
+
+    # @api private
+    # Wraps already-frozen nested data without copying it again.
+    def self.wrap(value)
+      case value
+      when Hash then ApiObject.allocate.tap { |object| object.send(:setup, value) }
+      when Array then value.map { |item| wrap(item) }.freeze
+      else value
+      end
+    end
+
+    protected
+
+    # Frozen raw data, for comparisons between objects.
+    # @api private
+    attr_reader :data
+
+    private
+
+    def reader_name?(name)
+      !name.end_with?("=", "!", "?")
+    end
+
+    # Value under the exact API key, without case-insensitive matching.
+    def exact(key)
+      self.class.wrap(@data[key])
+    end
+
+    def setup(frozen_data)
+      @data = frozen_data
+      @index = @data.keys.each_with_object({}) do |key, index|
+        index[self.class.normalize(key)] ||= key
+      end.freeze
+      freeze
+    end
+
+    def resolve(key)
+      return key if key.is_a?(String) && @data.key?(key)
+      return nil unless key.is_a?(String) || key.is_a?(Symbol)
+
+      @index[self.class.normalize(key)]
+    end
+  end
+
+  # Result of sending one email (also one element of a batch result).
+  class SendResult < ApiObject
+    # @return [Integer, nil] nil when the API did not send a numeric code
+    def error_code
+      HTTP::ResponseParser.error_code(@data)
+    end
+
+    # True only for ErrorCode 0. `false` appears inside batch results —
+    # single sends raise instead.
+    def success?
+      error_code&.zero? == true
+    end
+
+    # MessageID, one per recipient (the API joins them with commas).
+    # @return [Array<String>]
+    def message_ids
+      self["MessageID"].to_s.split(",").map(&:strip).reject(&:empty?)
+    end
+
+    # @return [Time, nil]
+    def submitted_at_time
+      Util.parse_time(self["SubmittedAt"])
+    end
+  end
+
+  # Result of /email/batch and /email/batchWithTemplates.
+  # The API answers 200 even if some emails were rejected,
+  # so check #success? or #failed.
+  class BatchResult
+    include Enumerable
+
+    # @return [Array<SendResult>] frozen, in the order the emails were given
+    attr_reader :results
+
+    # @param results [Array<SendResult>]
+    def initialize(results)
+      @results = results.dup.freeze
+      freeze
+    end
+
+    # Yields each SendResult.
+    def each(&block)
+      return enum_for(:each) unless block
+
+      @results.each(&block)
+      self
+    end
+
+    # @return [SendResult, nil]
+    def [](index)
+      @results[index]
+    end
+
+    # Number of results (equals the number of emails sent).
+    def size
+      @results.size
+    end
+    alias length size
+
+    def empty?
+      @results.empty?
+    end
+
+    # True when every email was accepted.
+    def success?
+      @results.all?(&:success?)
+    end
+
+    # @return [Array<SendResult>]
+    def successful
+      @results.select(&:success?)
+    end
+
+    # @return [Array<SendResult>]
+    def failed
+      @results.reject(&:success?)
+    end
+
+    # @return [Array<SendResult>] mutable copy
+    def to_a
+      @results.dup
+    end
+
+    # @return [Array<Hash>] raw API data of every result
+    def as_json(*)
+      @results.map(&:to_h)
+    end
+
+    # JSON array of the raw API results.
+    # json's RBS types the state argument of Array#to_json too narrowly.
+    def to_json(*args)
+      as_json.to_json(*args) # steep:ignore
+    end
+
+    # Same class and equal results.
+    def ==(other)
+      other.instance_of?(self.class) && other.results == @results
+    end
+
+    def eql?(other)
+      other.instance_of?(self.class) && other.results.eql?(@results)
+    end
+
+    # Consistent with #eql?.
+    def hash
+      [self.class, @results].hash
+    end
+
+    # Summary: number of results and failures.
+    def inspect
+      "#<#{self.class.name} size=#{size} failed=#{failed.size}>"
+    end
+    alias to_s inspect
+  end
+end

data/lib/haskimail/attachment.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+require_relative "util"
+
+module Haskimail
+  # An email attachment. Encodes content to Base64 and refuses file types
+  # that Haskimail rejects, before anything goes over the network.
+  #
+  #   Haskimail::Attachment.from_file("invoice.pdf")
+  #   Haskimail::Attachment.new(name: "report.csv", content: csv_string, content_type: "text/csv")
+  #   Haskimail::Attachment.from_file("logo.png", content_id: "cid:logo") # inline: <img src="cid:logo">
+  #
+  # Instances can be put straight into `attachments:` of any send method.
+  class Attachment
+    # https://haskimail.ru/developer/user-guide/send-email-with-api#attachments
+    FORBIDDEN_EXTENSIONS = %w[
+      vbs exe bin bat chm com cpl crt hlp hta inf ins isp jse lnk mdb pcd pif reg
+      scr sct shs vbe vba wsf wsh wsl msc msi msp mst
+    ].freeze
+
+    # Total message size limit, attachments counted after Base64 encoding.
+    MAX_MESSAGE_SIZE = 10 * 1024 * 1024
+
+    # Content type guessed from the file extension.
+    MIME_TYPES = {
+      "pdf" => "application/pdf", "zip" => "application/zip", "json" => "application/json",
+      "xml" => "application/xml", "txt" => "text/plain", "csv" => "text/csv", "html" => "text/html",
+      "htm" => "text/html", "ics" => "text/calendar", "png" => "image/png", "jpg" => "image/jpeg",
+      "jpeg" => "image/jpeg", "gif" => "image/gif", "webp" => "image/webp", "svg" => "image/svg+xml",
+      "doc" => "application/msword", "xls" => "application/vnd.ms-excel",
+      "docx" => "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+      "xlsx" => "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+      "pptx" => "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+      "odt" => "application/vnd.oasis.opendocument.text", "rtf" => "application/rtf",
+      "mp3" => "audio/mpeg", "mp4" => "video/mp4", "eml" => "message/rfc822"
+    }.freeze
+
+    # Content type for unknown extensions.
+    DEFAULT_CONTENT_TYPE = "application/octet-stream"
+
+    # RFC 2045 type/subtype, optionally followed by parameters
+    # ("text/plain; charset=utf-8").
+    CONTENT_TYPE_FORMAT = %r{\A[!#$%&'*+.^_`|~0-9A-Za-z-]+/[!#$%&'*+.^_`|~0-9A-Za-z-]+(?:[ \t]*;.*)?\z}
+
+    attr_reader :name, :content_type, :content_id
+
+    # @param path [String, Pathname]
+    # @raise [ValidationError] when the file cannot be read
+    def self.from_file(path, name: nil, content_type: nil, content_id: nil)
+      content = begin
+        File.binread(path.to_s)
+      rescue SystemCallError, IOError => e
+        raise ValidationError, "Attachment file #{path.to_s.inspect} cannot be read: #{e.message}"
+      end
+      new(name: name || File.basename(path.to_s), content: content, content_type: content_type, content_id: content_id)
+    end
+
+    # @param name [String] file name shown to the recipient
+    # @param content [String] raw (not encoded) bytes
+    # @param content_type [String, nil] detected from the extension when nil
+    # @param content_id [String, nil] makes the attachment inline (`cid:...`)
+    def initialize(name:, content:, content_type: nil, content_id: nil)
+      @name = self.class.validate_name!(name)
+      raise ValidationError, "Attachment content must be a String" unless content.is_a?(String)
+
+      @encoded = [content].pack("m0").freeze
+      @content_type = self.class.validate_content_type!(content_type || self.class.detect_content_type(@name))
+      @content_id = content_id.nil? ? nil : self.class.validate_content_id!(content_id)
+      if @encoded.bytesize > MAX_MESSAGE_SIZE
+        raise ValidationError, "Attachment #{@name} exceeds 10 MB after Base64 encoding"
+      end
+
+      freeze
+    end
+
+    # True for inline attachments (with a content ID).
+    def inline?
+      !@content_id.nil?
+    end
+
+    # Size after Base64 encoding — the number Haskimail checks against its limit.
+    def encoded_size
+      @encoded.bytesize
+    end
+
+    # @return [Hash] API representation
+    def to_haskimail
+      hash = { "Name" => @name, "Content" => @encoded, "ContentType" => @content_type }
+      content_id = @content_id
+      hash["ContentID"] = content_id if content_id
+      hash
+    end
+    alias to_h to_haskimail
+
+    # Name, type and size; never the content.
+    def inspect
+      "#<#{self.class.name} name=#{@name.inspect} content_type=#{@content_type.inspect} " \
+        "encoded_size=#{encoded_size}#{" content_id=#{@content_id.inspect}" if inline?}>"
+    end
+
+    # @api private
+    def self.validate_name!(name)
+      text = name.to_s
+      raise ValidationError, "Attachment name must be valid #{text.encoding} text" unless text.valid_encoding?
+
+      text = Util.utf8(text) # binary names (e.g. from a multipart upload) are relabelled
+      raise ValidationError, "Attachment name must not be blank" if text.strip.empty?
+      if text.match?(/[[:cntrl:]]/) || Util::UNSAFE_HEADER_CHARS.match?(text)
+        raise ValidationError, "Attachment name must not contain control characters or line separators"
+      end
+
+      extension = extension_of(text)
+      if FORBIDDEN_EXTENSIONS.include?(extension)
+        raise ValidationError, "Attachments of type .#{extension} are not accepted by Haskimail"
+      end
+
+      text.dup.freeze
+    end
+
+    # @api private
+    # @return [String] frozen, valid content type
+    def self.validate_content_type!(value)
+      text = header_text!(value, "Attachment content type")
+      raise ValidationError, "Invalid attachment content type #{text.inspect}" unless CONTENT_TYPE_FORMAT.match?(text)
+
+      text
+    end
+
+    # @api private
+    # @return [String] frozen content ID ("cid:logo" or "logo")
+    def self.validate_content_id!(value)
+      text = header_text!(value, "Attachment content ID")
+      raise ValidationError, "Attachment content ID must not be blank" if text.strip.empty?
+
+      text
+    end
+
+    # @api private
+    def self.header_text!(value, label)
+      unless value.is_a?(String) || value.is_a?(Symbol) || value.is_a?(Integer)
+        raise ValidationError, "#{label} must be a String"
+      end
+
+      text = Util.utf8(value.to_s)
+      # TAB is allowed: it may separate parameters ("text/plain;\tcharset=utf-8").
+      raise ValidationError, "#{label} must not contain control characters" if text.match?(/[[:cntrl:]&&[^\t]]/)
+      raise ValidationError, "#{label} must not contain line separators" if Util::UNSAFE_HEADER_CHARS.match?(text)
+
+      text.dup.freeze
+    end
+    private_class_method :header_text!
+
+    # Windows ignores trailing dots and spaces ("virus.exe. " runs as .exe),
+    # so they are stripped before the check.
+    # @api private
+    def self.extension_of(name)
+      base = File.basename(name.sub(/[.\s]+\z/, ""))
+      # A name like ".exe" has no extname, but Windows still treats it as an .exe.
+      extension = File.extname(base).delete_prefix(".")
+      extension = base.delete_prefix(".") if extension.empty? && base.start_with?(".")
+      extension.downcase
+    end
+
+    # Content type for a file name, from MIME_TYPES.
+    # @api private
+    def self.detect_content_type(name)
+      MIME_TYPES.fetch(extension_of(name), DEFAULT_CONTENT_TYPE)
+    end
+  end
+end

data/lib/haskimail/base_client.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+require_relative "version"
+require_relative "redacted"
+require_relative "errors"
+require_relative "configuration"
+require_relative "util"
+require_relative "api_object"
+require_relative "http/net_http_transport"
+require_relative "http/retry_policy"
+require_relative "http/response_parser"
+
+module Haskimail
+  # Shared HTTP plumbing for {ServerClient} and {AccountClient}:
+  # authentication, JSON, error mapping, retries and logging.
+  class BaseClient
+    include Redacted
+
+    # Methods accepted by #request.
+    HTTP_METHODS = %i[get post put patch delete].freeze
+
+    attr_reader :config
+
+    # @param token [String] API token
+    # @param transport [#call, nil] custom HTTP transport (see HTTP::NetHttpTransport)
+    # @param sleeper [#call, nil] used between retries; injectable for tests
+    # @param options [Hash] overrides of {Configuration} attributes
+    def initialize(token, transport: nil, sleeper: nil, **options)
+      @token = self.class.validate_token!(token)
+      @config = Haskimail.configuration.dup.update(**options).freeze
+      @transport = transport || HTTP::NetHttpTransport.new(proxy: @config.proxy, ca_file: @config.ca_file)
+      @retry_policy = HTTP::RetryPolicy.new(max_retries: @config.max_retries)
+      @sleeper = sleeper || ->(seconds) { sleep(seconds) }
+      @user_agent = build_user_agent
+      build_resources
+      freeze
+    end
+
+    # Low-level escape hatch for endpoints not wrapped by the SDK.
+    #
+    #   client.request(:get, "/messages", query: { "count" => 10 })
+    #
+    # @param method [Symbol] :get, :post, :put, :patch, :delete
+    # @param path [String] path starting with "/"
+    # @param query [Hash] query string parameters (sent verbatim)
+    # @param body [Hash, Array, nil] JSON body (sent verbatim, strings converted to UTF-8)
+    # @return [ApiObject, Array, nil]
+    def request(method, path, query: nil, body: nil)
+      wrap(perform(method, path, query: query, body: body))
+    end
+
+    # The token is never shown.
+    def inspect
+      "#<#{self.class.name} base_url=#{config.base_url.inspect} token=[FILTERED]>"
+    end
+    alias to_s inspect
+
+    # @api private
+    def self.validate_token!(token)
+      raise ConfigurationError, "API token is required" if Util.blank?(token)
+
+      value = token.to_s.b
+      unless value.match?(/\A[\x21-\x7e]+\z/n)
+        raise ConfigurationError, "API token contains forbidden characters (spaces, line breaks or non-ASCII)"
+      end
+
+      value.dup.freeze
+    end
+
+    # @api private
+    # Performs the request with retries and returns the parsed JSON (Hash/Array/nil).
+    def perform(method, path, query: nil, body: nil, idempotent: nil)
+      request = build_request(method, path, query, body, idempotent)
+      attempt = 0
+
+      loop do
+        response = attempt_request(request, attempt)
+        data = HTTP::ResponseParser.parse(response)
+        if @retry_policy.retry_response?(request, response, HTTP::ResponseParser.error_code(data), attempt)
+          attempt += 1
+          pause(attempt, response, "HTTP #{response.status}")
+          next
+        end
+
+        return checked(request, response, data)
+      rescue ConnectionError => e
+        raise unless @retry_policy.retry_error?(request, e, attempt)
+
+        attempt += 1
+        pause(attempt, nil, e.class.name)
+      end
+    end
+
+    # @api private
+    # Ensures a documented JSON-object response.
+    def expect_object(data)
+      return data if data.is_a?(Hash)
+
+      raise UnexpectedResponseError.new("Expected a JSON object from Haskimail, got #{data.class}. " \
+                                        "If this was a send request, the email MAY have been accepted — " \
+                                        "check the message log before re-sending", http_status: 200)
+    end
+
+    # Wraps parsed JSON: objects become ApiObject, arrays are mapped.
+    # @api private
+    def wrap(data)
+      case data
+      when Hash then ApiObject.new(data)
+      when Array then data.map { |item| item.is_a?(Hash) ? ApiObject.new(item) : item }
+      else data
+      end
+    end
+
+    protected
+
+    # Name of the authentication header.
+    def token_header
+      raise NotImplementedError
+    end
+
+    # Subclasses create their resource objects here.
+    def build_resources; end
+
+    private
+
+    def build_request(method, path, query, body, idempotent)
+      unless HTTP_METHODS.include?(method)
+        raise ValidationError, "HTTP method must be one of #{HTTP_METHODS.map(&:inspect).join(', ')}"
+      end
+      raise ValidationError, "path must start with '/'" unless path.is_a?(String) && path.start_with?("/")
+
+      headers = { "Accept" => "application/json", "User-Agent" => @user_agent, token_header => @token }
+      payload = nil
+      unless body.nil?
+        headers["Content-Type"] = "application/json"
+        payload = Util.generate_json(Util.utf8_strings(body))
+      end
+      HTTP::Request.new(method: method, url: build_url(path, query), headers: headers.freeze, body: payload,
+                        idempotent: idempotent)
+    end
+
+    def build_url(path, query)
+      url = config.base_url + path
+      url += "?#{URI.encode_www_form(query)}" if query && !query.empty?
+      URI.parse(url)
+      url
+    rescue URI::InvalidURIError
+      raise ValidationError, "Invalid request path #{path.inspect}"
+    end
+
+    def checked(request, response, data)
+      if (200..299).cover?(response.status) && HTTP::ResponseParser.malformed_error_code?(data)
+        raise HTTP::ResponseParser.unexpected_body_error(request, response, "a non-numeric ErrorCode")
+      end
+      raise HTTP::ResponseParser.api_error(response, data) unless HTTP::ResponseParser.success?(response, data)
+      if data.nil? && !HTTP::ResponseParser.blank_body?(response.body)
+        raise HTTP::ResponseParser.unexpected_body_error(request, response)
+      end
+
+      data
+    end
+
+    def attempt_request(request, attempt)
+      started = monotonic_now
+      response = @transport.call(request, open_timeout: config.open_timeout,
+                                          read_timeout: config.read_timeout,
+                                          write_timeout: config.write_timeout)
+      log(:debug) do
+        "Haskimail #{request.method.upcase} #{log_path(request)} -> #{response.status} " \
+          "(#{((monotonic_now - started) * 1000).round} ms, attempt #{attempt + 1})"
+      end
+      response
+    end
+
+    def pause(attempt, response, reason)
+      delay = @retry_policy.delay(attempt, response)
+      log(:warn) { "Haskimail retry #{attempt}/#{config.max_retries} in #{delay.round(2)}s (#{reason})" }
+      @sleeper.call(delay)
+    end
+
+    # The query string is never logged: it contains recipient addresses (personal data).
+    def log_path(request)
+      URI.parse(request.url).path
+    end
+
+    def log(level, &)
+      config.logger&.public_send(level, &)
+    end
+
+    def monotonic_now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def build_user_agent
+      agent = "haskimail-ruby/#{VERSION} ruby/#{RUBY_VERSION} (#{RUBY_PLATFORM})"
+      config.user_agent ? "#{agent} #{config.user_agent}" : agent
+    end
+  end
+end