thousandmails 1.0.0

data/lib/thousandmails/utils/http.rb

@@ -0,0 +1,287 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+
+module ThousandMails
+  # The transport every resource goes through: URL building, auth header,
+  # timeout, retry policy, and turning a non-2xx response into a typed error.
+  class Http
+    RETRY_BASE_MS = 500
+    RETRY_MAX_MS = 8000
+
+    # Returned by retry_after_ms when the server's hint is longer than
+    # RETRY_MAX_MS. Distinct from nil, which means the response carried no hint
+    # at all. A real delay is never negative, so -1 is unambiguous.
+    TOO_LONG_TO_WAIT = -1
+
+    # Statuses worth trying again. 429 and 503 are both refusals issued before
+    # the handler ran (the rate limiter, and the attachment admission gate), so
+    # they are safe to retry whatever the method. A 5xx is ambiguous for a send —
+    # the mail may already be on its way — so those only retry when an
+    # idempotency key makes a repeat harmless.
+    ALWAYS_RETRY = [429, 503].freeze
+
+    attr_reader :api_key, :base_url, :timeout, :max_retries, :default_headers,
+                :user_agent, :transport
+    # Rate-limit headers from the most recent response, for callers that want to
+    # pace themselves rather than wait for a 429.
+    attr_reader :last_rate_limit
+
+    def initialize(api_key: nil, base_url: nil, timeout: nil, max_retries: nil,
+                   headers: nil, user_agent: nil, transport: nil)
+      key = api_key || ENV["THOUSANDMAILS_API_KEY"]
+
+      if !key.is_a?(String) || key.strip.empty?
+        raise ConfigError, "An API key is required: ThousandMails::Client.new(api_key:) " \
+                           "or the THOUSANDMAILS_API_KEY environment variable"
+      end
+
+      @api_key = key.strip
+      @base_url = self.class.normalise_base_url(
+        base_url.nil? || base_url.to_s.empty? ? Constants.default_base_url : base_url
+      )
+      # Per-attempt timeout in milliseconds; 0 disables. A retried request gets a
+      # fresh window rather than sharing one budget across the whole call.
+      @timeout = timeout.nil? ? Constants::DEFAULT_TIMEOUT_MS : timeout.to_i
+      @max_retries = max_retries.nil? ? Constants::DEFAULT_MAX_RETRIES : max_retries.to_i
+      @default_headers = headers || {}
+      @user_agent = user_agent || "thousandmails-ruby/#{ThousandMails::VERSION} ruby/#{RUBY_VERSION}"
+
+      if transport && !transport.is_a?(Transports::Transport)
+        raise ConfigError, "transport must be a ThousandMails::Transports::Transport"
+      end
+
+      @transport = transport || Transports::NetHttpTransport.new
+      @last_rate_limit = nil
+    end
+
+    # Absolute URL for a client-API path, with empty query params dropped.
+    def url(path, query = nil)
+      target = "#{base_url}#{Constants::CLIENT_PREFIX}#{path}"
+
+      pairs = (query || {}).reject { |_, value| value.nil? || value == "" }
+      return target if pairs.empty?
+
+      encoded = pairs.map do |name, value|
+        rendered = value == true ? "true" : (value == false ? "false" : value.to_s)
+        "#{URI.encode_www_form_component(name.to_s)}=#{URI.encode_www_form_component(rendered)}"
+      end
+
+      "#{target}?#{encoded.join('&')}"
+    end
+
+    # Perform one API call, retrying per the policy above.
+    #
+    # @param form [Array(String, String)] `[body, content_type]` for multipart
+    # @param parse [Symbol] :json decodes the body, :text returns it as a string
+    # @param retry_unsafe [Boolean] allow 5xx retries without an idempotency key
+    # @param timeout [Integer] overrides the client timeout; 0 disables it.
+    #   Applies per attempt, so a retried request gets a fresh window.
+    # @return [Hash] `{ data:, status:, headers: }`
+    def request(http_method, path, query: nil, json: :none, form: nil,
+                idempotency_key: nil, parse: :json, retry_unsafe: false,
+                timeout: nil, headers: nil)
+      target = url(path, query)
+      effective_timeout = timeout.nil? ? @timeout : timeout.to_i
+      retryable = http_method == "GET" || !idempotency_key.nil? || retry_unsafe
+
+      attempt = 0
+
+      loop do
+        request_headers = {
+          "Authorization" => "Bearer #{api_key}",
+          "Accept" => parse == :text ? "text/csv, text/plain, */*" : "application/json",
+          "User-Agent" => user_agent
+        }
+        request_headers.merge!(default_headers)
+        request_headers.merge!(headers) if headers
+
+        body = nil
+        if form
+          body, request_headers["Content-Type"] = form
+        elsif json != :none
+          request_headers["Content-Type"] = "application/json"
+          body = JSON.generate(json)
+        end
+        request_headers["Idempotency-Key"] = idempotency_key if idempotency_key
+
+        begin
+          response = transport.send_request(
+            Transports::Request.new(http_method, target, request_headers, body, effective_timeout)
+          )
+        rescue ConnectionError
+          # A connection that never produced a response may still have delivered
+          # the request, so a send is only replayed when a key makes that safe.
+          # TimeoutError subclasses ConnectionError, so a request that timed out
+          # is covered by the same rule.
+          raise unless retryable && attempt < max_retries
+
+          sleep(self.class.backoff(attempt) / 1000.0)
+          attempt += 1
+          next
+        end
+
+        @last_rate_limit = self.class.read_rate_limit(response.headers)
+
+        if response.ok?
+          return {
+            data: self.class.read_body(response.body, parse),
+            status: response.status,
+            headers: response.headers
+          }
+        end
+
+        should_retry = attempt < max_retries &&
+                       (ALWAYS_RETRY.include?(response.status) ||
+                        (response.status >= 500 && retryable))
+
+        # A Retry-After longer than we are willing to wait means the window will
+        # still be shut when the retry lands, so the attempts would be spent for
+        # nothing. Give up now instead and let the caller pace itself off
+        # `error.retry_after`, which carries the server's real figure.
+        hinted = should_retry ? self.class.retry_after_ms(response.headers) : nil
+
+        if should_retry && hinted != TOO_LONG_TO_WAIT
+          sleep((hinted || self.class.backoff(attempt)) / 1000.0)
+          attempt += 1
+          next
+        end
+
+        raise Errors.from_response(
+          response.status,
+          self.class.read_body(response.body, :json),
+          response.headers,
+          http_method,
+          target
+        )
+      end
+    end
+
+    # `request`, for the endpoints that always answer with a JSON object.
+    #
+    # A 2xx whose body is empty or isn't JSON means something between here and
+    # the API rewrote the response — a proxy error page, a truncated reply. The
+    # resource methods are documented to return hashes, so without this the
+    # caller would get a NoMethodError from deep inside the SDK instead of
+    # something that names the problem.
+    def request_object(http_method, path, **options)
+      response = request(http_method, path, **options)
+      data = response[:data]
+      return data if data.is_a?(Hash)
+
+      shown = data.nil? ? "an empty body" : "a non-JSON body"
+      raise ServerError.new(
+        "The API returned #{shown} with status #{response[:status]}, " \
+        "where a JSON object was expected",
+        status: response[:status],
+        body: data,
+        headers: response[:headers],
+        http_method: http_method,
+        url: url(path, options[:query])
+      )
+    end
+
+    # Streaming GET — used by the SSE endpoint, which must not time out.
+    # Each chunk is handed to the block; returning false from it closes the
+    # connection.
+    def open(path, query: nil, headers: nil, &on_chunk)
+      target = url(path, query)
+
+      request_headers = {
+        "Authorization" => "Bearer #{api_key}",
+        "Accept" => "text/event-stream",
+        "Cache-Control" => "no-cache",
+        "User-Agent" => user_agent
+      }
+      request_headers.merge!(default_headers)
+      request_headers.merge!(headers) if headers
+
+      response = transport.stream(
+        Transports::Request.new("GET", target, request_headers, nil, 0), &on_chunk
+      )
+
+      return if response.nil? || response.ok?
+
+      raise Errors.from_response(
+        response.status,
+        self.class.read_body(response.body, :json),
+        response.headers,
+        "GET",
+        target
+      )
+    end
+
+    class << self
+      # Percent-encode one path segment, RFC 3986 style.
+      #
+      # Not URI.encode_www_form_component, which spells a space "+" — correct in
+      # a query string, wrong in a path, where the server would read it back as a
+      # literal plus. An SMTP message id (`<uuid@domain>`) goes through here.
+      def encode_path_segment(value)
+        value.to_s.b.gsub(/[^a-zA-Z0-9\-._~]/) { |char| format("%%%02X", char.ord) }
+      end
+
+      # Exponential with full jitter, so a fleet retrying together spreads out.
+      # @return [Integer] milliseconds to wait
+      def backoff(attempt)
+        ceiling = [RETRY_BASE_MS * (2**attempt), RETRY_MAX_MS].min
+        (ceiling * (0.5 + (rand * 0.5))).round
+      end
+
+      # A base_url that isn't an absolute URL is a configuration mistake, and it
+      # has to be reported as one here. Left to the first request it would
+      # surface as a URI error from inside the SDK, on a call that looks like it
+      # failed for some other reason entirely.
+      def normalise_base_url(base_url)
+        trimmed = base_url.to_s.strip.sub(%r{/+\z}, "")
+
+        parsed = begin
+          URI.parse(trimmed)
+        rescue URI::InvalidURIError
+          nil
+        end
+
+        unless parsed && %w[http https].include?(parsed.scheme) && parsed.host
+          raise ConfigError, "base_url is not a usable absolute URL: \"#{base_url}\""
+        end
+
+        trimmed
+      end
+
+      def read_body(raw, parse)
+        text = raw.to_s
+        return text if parse == :text
+        return nil if text.empty?
+
+        begin
+          JSON.parse(text)
+        rescue JSON::ParserError
+          text
+        end
+      end
+
+      def read_rate_limit(headers)
+        limit = headers["ratelimit-limit"]
+        return nil if limit.nil?
+
+        {
+          "limit" => limit.to_i,
+          "remaining" => headers["ratelimit-remaining"].to_i,
+          "reset" => headers["ratelimit-reset"].to_i
+        }
+      end
+
+      # How long the server asked us to wait, in ms — or TOO_LONG_TO_WAIT when
+      # that exceeds the retry ceiling, or nil when it said nothing.
+      def retry_after_ms(headers)
+        seconds = Errors.parse_retry_after(headers)
+        return nil if seconds.nil?
+
+        # A date already in the past, or a negative delay, means "now".
+        ms = [0.0, seconds].max * 1000
+        ms > RETRY_MAX_MS ? TOO_LONG_TO_WAIT : ms.to_i
+      end
+    end
+  end
+end

data/lib/thousandmails/utils/options.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module ThousandMails
+  # Reconciles the two ways a Ruby caller naturally passes a payload.
+  #
+  # Ruby folds bare keyword arguments into a positional Hash only for methods
+  # that take no keywords of their own. Every method here takes options
+  # (`timeout:`, `idempotency_key:`), so the natural call
+  #
+  #   client.send_mail(senderemail: "...", to: "...", subject: "...")
+  #
+  # would otherwise drop the whole message into the options bucket and leave the
+  # payload empty. Folding the leftover keywords back into the payload puts them
+  # where the caller plainly meant them, while an explicit hash still works when
+  # options travel alongside:
+  #
+  #   client.send_mail({ senderemail: "...", to: "..." }, timeout: 5_000)
+  module Options
+    module_function
+
+    def merge(payload, extra)
+      base = payload.nil? ? {} : payload
+      return base if extra.nil? || extra.empty?
+      return extra unless base.is_a?(Hash)
+
+      base.merge(extra)
+    end
+  end
+end

data/lib/thousandmails/utils/stream.rb

@@ -0,0 +1,252 @@
+# frozen_string_literal: true
+
+require "json"
+
+module ThousandMails
+  # Server-Sent Events client for GET /client/realtime/stream.
+  #
+  # The endpoint emits a `ready` frame on connect, an `email` frame per recorded
+  # event, and a `: ping` comment every 25s to keep proxies from closing an idle
+  # connection. Anything that isn't one of those is surfaced as a raw frame
+  # rather than dropped, so a new server-side event type doesn't need an SDK
+  # release.
+  #
+  # Usage — either style:
+  #
+  #   stream = thousandmails.realtime.stream
+  #   stream.on("email") { |event| puts event["type"] }
+  #   stream.listen
+  #
+  #   thousandmails.realtime.stream.events.each { |event| ... }
+  #
+  # The Node SDK exposes these as an EventEmitter and an async iterable. Ruby has
+  # no event loop in play here, so `listen` blocks and dispatches to handlers
+  # while `events` returns an Enumerator that yields one event at a time. Neither
+  # queues anything: an event is handed to exactly one consumer and then dropped,
+  # so a stream held open for days does not grow.
+  class EventStream
+    # Set when the loop stopped because of a failure it could not recover from.
+    attr_reader :error
+
+    def initialize(http, reconnect: true, max_reconnects: nil,
+                   on_event: nil, on_ready: nil, on_error: nil)
+      @http = http
+      @reconnect = reconnect != false
+      @max_reconnects = max_reconnects || Float::INFINITY
+
+      @listeners = Hash.new { |hash, key| hash[key] = [] }
+      @closed = false
+      @connected = false
+      @ended = false
+      @error = nil
+      # The last `id:` the server labelled a frame with, replayed as
+      # Last-Event-ID on reconnect. See connect_and_read.
+      @last_event_id = nil
+
+      on("email", &on_event) if on_event
+      on("ready", &on_ready) if on_ready
+      on("error", &on_error) if on_error
+    end
+
+    # Register a handler. Event names: ready, email, heartbeat, frame, open,
+    # close, error, end.
+    #
+    # Unlike the Node SDK, a stream with no `error` handler is not itself an
+    # error — an unhandled failure is reported through `end` and, for `events`,
+    # raised at the consumer.
+    def on(event, &listener)
+      @listeners[event.to_s] << listener
+      self
+    end
+
+    def connected?
+      @connected
+    end
+
+    def closed?
+      @closed
+    end
+
+    # Stop listening and close the underlying connection. Safe to call from a
+    # handler, from another thread, or twice.
+    #
+    # From a handler, or by breaking out of `events`, this takes effect at once.
+    # From another thread it takes effect when the next frame arrives, because
+    # the reader is parked on a blocking socket read until then — at worst one
+    # heartbeat interval, which the server sends every 25 seconds. `closed?` is
+    # true immediately either way; it is only the socket that lingers.
+    def close
+      return if @closed
+
+      @closed = true
+      finish
+      nil
+    end
+
+    # Run the stream, dispatching to the handlers registered with `on`.
+    #
+    # Blocks until the connection ends and reconnection is exhausted or
+    # disabled, or until a handler calls `close`.
+    def listen
+      frames { |name, payload| emit(name, payload) }
+      nil
+    ensure
+      finish
+    end
+
+    # The same loop, as an Enumerator of `email` events.
+    #
+    # Handlers registered with `on` still fire, so a caller can iterate the email
+    # events while watching `error` or `heartbeat` on the side. Breaking out of
+    # the loop closes the connection.
+    def events
+      Enumerator.new do |yielder|
+        begin
+          frames do |name, payload|
+            emit(name, payload)
+            yielder << payload if name == "email" && !@closed
+          end
+        ensure
+          # A `break` in the caller's loop lands here, which would otherwise
+          # leave the socket open with nobody reading it.
+          close
+        end
+
+        raise @error if @error
+      end
+    end
+
+    private
+
+    # The reconnect loop, yielding `[name, payload]` for every frame. Both entry
+    # points drive this; they differ only in what they do with a frame once it
+    # arrives.
+    def frames(&dispatch)
+      failures = 0
+
+      until @closed
+        dropped = false
+
+        begin
+          connect_and_read(&dispatch)
+        rescue ThousandMails::Error => e
+          break if @closed
+
+          dropped = true
+          failures += 1
+          dispatch.call("error", e)
+
+          # An auth failure will never resolve itself, so retrying it only burns
+          # the rate-limit budget.
+          status = e.respond_to?(:status) ? e.status : nil
+          fatal = status == 401 || status == 403 || !@reconnect
+
+          if fatal || failures >= @max_reconnects
+            @error = e
+            return
+          end
+        end
+
+        dispatch.call("close", nil) unless dropped
+        break if @closed || !@reconnect
+
+        sleep(Http.backoff([failures, 4].min) / 1000.0)
+      end
+    end
+
+    # Open the connection and dispatch complete frames. SSE frames are separated
+    # by a blank line; a chunk boundary can land anywhere, so partial frames stay
+    # in the buffer until their terminator arrives.
+    def connect_and_read(&dispatch)
+      # Where to resume from, per the SSE spec. The server does not label frames
+      # with `id:` today, so this stays unset and a reconnect picks up from the
+      # live edge — events that occurred during the gap are missed. Reconcile
+      # with client.logs when that matters. The moment the server starts
+      # labelling frames, this resumes without an SDK release.
+      headers = @last_event_id ? { "Last-Event-ID" => @last_event_id } : nil
+
+      pending = +""
+      opened = false
+
+      @http.open("/realtime/stream", headers: headers) do |chunk|
+        unless opened
+          opened = true
+          @connected = true
+          dispatch.call("open", nil)
+        end
+
+        # Normalised on the whole buffer, not per chunk, so a CRLF split across a
+        # chunk boundary still reads as one line ending.
+        pending << chunk.to_s.dup.force_encoding(Encoding::UTF_8)
+        pending = pending.gsub("\r\n", "\n")
+
+        while (split = pending.index("\n\n"))
+          frame = pending[0, split]
+          pending = pending[(split + 2)..]
+
+          parsed, event_id = self.class.parse_frame(frame)
+          @last_event_id = event_id if event_id
+          parsed.each { |name, payload| dispatch.call(name, payload) }
+
+          break if @closed
+        end
+
+        !@closed
+      end
+    ensure
+      @connected = false
+    end
+
+    def emit(event, payload)
+      @listeners[event].each { |listener| listener.call(payload) }
+    end
+
+    # Called from both close and the end of a run, so it has to be idempotent —
+    # a consumer must not see two `end` events for one stream.
+    def finish
+      @closed = true
+      return if @ended
+
+      @ended = true
+      emit("end", @error)
+    end
+
+    # One SSE frame, as the events it should be dispatched under.
+    #
+    # A named frame produces two: a generic `frame` carrying the envelope, then
+    # the frame's own name. A comment frame produces only `heartbeat`.
+    #
+    # @return [Array] `[frames, event_id]`
+    def self.parse_frame(frame)
+      # A comment frame (": ping") is the heartbeat — proof of life, nothing more.
+      return [[["heartbeat", nil]], nil] if frame.strip.empty? || frame.start_with?(":")
+
+      name = "message"
+      data = []
+      event_id = nil
+
+      frame.split("\n").each do |line|
+        if line.start_with?("event:")
+          name = line[6..].strip
+        elsif line.start_with?("data:")
+          data << line[5..].sub(/\A /, "")
+        elsif line.start_with?("id:")
+          # The spec says a field value containing NUL is ignored rather than
+          # stored, and that the id survives the frame it arrived on.
+          candidate = line[3..].strip
+          event_id = candidate unless candidate.empty? || candidate.include?("\0")
+        end
+      end
+
+      raw = data.join("\n")
+      payload = begin
+        JSON.parse(raw)
+      rescue JSON::ParserError
+        # Leave it as text — a frame the SDK doesn't model is still delivered.
+        raw
+      end
+
+      [[["frame", { "event" => name, "data" => payload }], [name, payload]], event_id]
+    end
+  end
+end