posthaste-rails 0.1.0

data/lib/posthaste/errors.rb

@@ -0,0 +1,311 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'time'
+require_relative 'redaction'
+
+module Posthaste
+  # Every `error.type` the API emits, plus the ones this gem synthesises.
+  #
+  # Kept as data rather than as a set of classes so a caller can check whether a
+  # type is one this version knows about. An unrecognised type is NOT a bug: the
+  # API is allowed to add refusal reasons, and one that arrives here unknown
+  # becomes the class its HTTP status implies instead of being mistaken for a
+  # documented one.
+  KNOWN_ERROR_TYPES = %w[
+    unauthorized unauthenticated forbidden csrf_failed email_unverified
+    invalid_request not_found conflict address_taken
+    batch_too_large fanout_too_large unknown_template invalid_template
+    template_in_use unknown_stream reserved_slug slug_taken invalid_address
+    domain_not_found domain_not_verified suppressed
+    rate_limited daily_limit_reached monthly_limit_reached platform_paused
+    bulk_send_refused
+    attachments_too_many attachments_too_large attachment_type_blocked
+    attachment_invalid
+    schedule_too_far not_scheduled
+    content_blocked
+    domain_limit_reached domain_in_use token_required
+    cloudflare_token_invalid cloudflare_zone_not_found cloudflare_write_failed
+    suppression_protected suppression_platform suppression_hard_bounce
+    not_configured provider_error already_subscribed
+    internal
+    unknown_error connection_error timeout
+    configuration_error unmappable_message
+  ].freeze
+
+  # Why a recipient stopped receiving mail. Read off a SuppressedError.
+  SuppressionInfo = Struct.new(:address, :reason, keyword_init: true)
+
+  # The root of everything this gem raises.
+  #
+  # Rescue `Posthaste::Error` to catch every refusal, or one of the subclasses
+  # below to catch a KIND of refusal. Branch on `#type`, never on `#message`:
+  # the type is the stable contract and the sentence is not.
+  class Error < StandardError
+    attr_reader :type, :status, :body, :request_id, :retry_after_seconds
+
+    def initialize(message, type: 'unknown_error', status: 0, body: nil, request_id: nil,
+                   retry_after_seconds: nil, api_key: nil)
+      # Redacted at CONSTRUCTION, not at print time. An exception message is
+      # copied into logs, error reporters and tickets by machinery this gem
+      # never sees, so the only safe moment is before the string exists.
+      super(Redaction.redact(message, api_key))
+      @type = type
+      @status = status
+      @body = body
+      @request_id = request_id
+      @retry_after_seconds = retry_after_seconds
+    end
+
+    # The four 429s mean four different things and nothing about the status
+    # says which. These two predicates are the difference between waiting a
+    # few seconds and hammering a wall until the calendar moves.
+    def rate_limited?
+      type == 'rate_limited' || type == 'platform_paused'
+    end
+
+    def quota_exhausted?
+      type == 'daily_limit_reached' || type == 'monthly_limit_reached'
+    end
+
+    # Worth repeating the same request later. NOT a promise that repeating it
+    # is safe — that depends on whether the request can duplicate an effect,
+    # which is what an idempotency key settles.
+    def transient?
+      rate_limited? || status == 408 || status == 429 || status >= 500
+    end
+
+    def error_field(name)
+      envelope = body.is_a?(Hash) ? body['error'] : nil
+      envelope.is_a?(Hash) ? envelope[name.to_s] : nil
+    end
+
+    def inspect
+      "#<#{self.class.name} type=#{type.inspect} status=#{status} " \
+        "message=#{message.inspect}>"
+    end
+  end
+
+  # Something is wrong with how the delivery method was configured — most often
+  # a missing API key. Raised before any request is attempted.
+  class ConfigurationError < Error; end
+
+  # The `Mail::Message` cannot be expressed as a Posthaste send.
+  #
+  # Raised BEFORE the request, naming the field, because the alternative — a
+  # quiet omission — is a team that migrates and does not notice their Bcc
+  # stopped arriving. Nothing is dropped in silence.
+  class MappingError < Error; end
+
+  # A header the platform owns, set by the application. Names the first-class
+  # field to use instead, because "you may not set this" without "set that" is
+  # a dead end for somebody mid-migration.
+  class UnsupportedHeaderError < MappingError; end
+
+  # The request never produced a response. `status` is 0.
+  class ConnectionError < Error; end
+
+  # The request opened and the server never answered in time.
+  class TimeoutError < ConnectionError; end
+
+  # The server answered, and the answer was a refusal.
+  class APIStatusError < Error; end
+
+  # 401 — the key is missing, malformed, revoked, or from another account.
+  class AuthenticationError < APIStatusError; end
+
+  # 403 — a real key that does not hold `emails:send`.
+  class PermissionDeniedError < APIStatusError; end
+
+  # 400 — the body is wrong. `error.fields` often says where.
+  class InvalidRequestError < APIStatusError; end
+
+  # 404 — no such id, on this account.
+  class NotFoundError < APIStatusError; end
+
+  # 409 — it already exists. Frequently the correct answer to a retry.
+  class ConflictError < APIStatusError; end
+
+  # 422 — well formed, and we will not act on it.
+  #
+  # Permanent by construction: the same bytes get the same answer, so nothing
+  # under this class is ever retried automatically.
+  class UnprocessableError < APIStatusError; end
+
+  # The recipient is on the suppression list. Read `#suppression`.
+  #
+  # Never work around this. Sending to a suppressed address is how a sending IP
+  # gets blocklisted, and the block lands on every other customer sharing it —
+  # which is why the API refuses rather than warns.
+  class SuppressedError < UnprocessableError
+    def suppression
+      address = error_field(:address)
+      reason = error_field(:reason)
+      return nil unless address.is_a?(String)
+
+      SuppressionInfo.new(address: address, reason: reason.is_a?(String) ? reason : nil)
+    end
+  end
+
+  # The `from` domain has not had its DKIM record verified. Publish the record
+  # and verify it; there is no flag that skips this.
+  class DomainNotVerifiedError < UnprocessableError; end
+
+  # The pre-send lint refused the CONTENT.
+  class ContentBlockedError < UnprocessableError
+    # Which check refused it, e.g. `dangerous_link` or `empty_body`.
+    def check
+      value = error_field(:check)
+      value.is_a?(String) ? value : nil
+    end
+
+    # The whole lint report, warnings included, so one fix pass can address
+    # everything rather than playing whack-a-mole one refusal at a time.
+    def findings
+      value = error_field(:findings)
+      value.is_a?(Array) ? value : []
+    end
+  end
+
+  # Too many files, too many bytes, a blocked type, or unreadable content.
+  class AttachmentError < UnprocessableError; end
+
+  # `scheduledAt` is out of range, or the message already left.
+  class ScheduleError < UnprocessableError; end
+
+  # The named template is unknown, invalid, or still in use.
+  class TemplateError < UnprocessableError; end
+
+  # The named message stream does not exist on this account.
+  class StreamError < UnprocessableError; end
+
+  # A transient throttle. Honour `retry_after_seconds` and come back.
+  #
+  # Covers `rate_limited` (this key's request rate) and `platform_paused` (the
+  # platform's own daily send ceiling). Both clear on their own.
+  class RateLimited < APIStatusError; end
+
+  # The account's allowance is spent — `Retry-After` is hours or days.
+  #
+  # A SIBLING of RateLimited, never a subclass. Retrying this in process burns
+  # your own request budget on calls that are all going to be refused until the
+  # calendar moves. Queue it, or alert.
+  class QuotaExhausted < APIStatusError; end
+
+  # 5xx. Safe to retry, if the request is one that repeating cannot duplicate.
+  class ServerError < APIStatusError; end
+
+  # Mapping a refusal onto a class.
+  module ErrorMapping
+    # By TYPE first, because the type is the stable contract and the status is
+    # not specific enough. Only types that say more than their status does are
+    # listed; everything else falls through to BY_STATUS, which is the honest
+    # answer for a refusal reason this version has never seen.
+    BY_TYPE = {
+      'unauthorized' => AuthenticationError,
+      'unauthenticated' => AuthenticationError,
+      'csrf_failed' => AuthenticationError,
+      'email_unverified' => AuthenticationError,
+      'forbidden' => PermissionDeniedError,
+      'invalid_request' => InvalidRequestError,
+      'not_found' => NotFoundError,
+      'conflict' => ConflictError,
+      'address_taken' => ConflictError,
+      'suppressed' => SuppressedError,
+      'suppression_protected' => UnprocessableError,
+      'suppression_platform' => UnprocessableError,
+      'suppression_hard_bounce' => UnprocessableError,
+      'domain_not_verified' => DomainNotVerifiedError,
+      'content_blocked' => ContentBlockedError,
+      'attachments_too_many' => AttachmentError,
+      'attachments_too_large' => AttachmentError,
+      'attachment_type_blocked' => AttachmentError,
+      'attachment_invalid' => AttachmentError,
+      'schedule_too_far' => ScheduleError,
+      'not_scheduled' => ScheduleError,
+      'unknown_template' => TemplateError,
+      'invalid_template' => TemplateError,
+      'template_in_use' => TemplateError,
+      'unknown_stream' => StreamError,
+      # The four 429s. Two transient, two not.
+      'rate_limited' => RateLimited,
+      'platform_paused' => RateLimited,
+      'daily_limit_reached' => QuotaExhausted,
+      'monthly_limit_reached' => QuotaExhausted,
+      'internal' => ServerError
+      # `connection_error` and `timeout` are deliberately ABSENT. They are
+      # synthesised by the transport, which constructs the exception directly,
+      # so an entry here would only ever fire on a response that carried one of
+      # those strings as an HTTP-level refusal — and mapping a real 408 onto
+      # ConnectionError ("never reached the server") would be a lie about what
+      # happened.
+    }.freeze
+
+    BY_STATUS = {
+      400 => InvalidRequestError,
+      401 => AuthenticationError,
+      403 => PermissionDeniedError,
+      404 => NotFoundError,
+      409 => ConflictError,
+      422 => UnprocessableError,
+      # An unrecognised 429 is treated as transient rather than as spent quota.
+      # That direction is the safe one: a wrongly-retried throttle costs a few
+      # seconds, while a wrongly-abandoned one drops mail that would have gone.
+      429 => RateLimited
+    }.freeze
+
+    module_function
+
+    def class_for(error_type, status)
+      known = BY_TYPE[error_type]
+      return known if known
+      return ServerError if status >= 500
+
+      BY_STATUS.fetch(status, APIStatusError)
+    end
+
+    # Build the exception for one refused response.
+    def from_response(status, raw_body, retry_after_header, request_id: nil, api_key: nil)
+      body = begin
+        parsed = raw_body.to_s.empty? ? nil : JSON.parse(raw_body)
+        parsed.is_a?(Hash) ? parsed : nil
+      rescue JSON::ParserError
+        nil
+      end
+
+      envelope = body.is_a?(Hash) && body['error'].is_a?(Hash) ? body['error'] : {}
+      type = envelope['type'].is_a?(String) ? envelope['type'] : 'unknown_error'
+      message = envelope['message'].is_a?(String) ? envelope['message'] : "HTTP #{status}"
+
+      class_for(type, status).new(
+        message,
+        type: type,
+        status: status,
+        body: body,
+        request_id: request_id,
+        retry_after_seconds: parse_retry_after(retry_after_header, envelope),
+        api_key: api_key
+      )
+    end
+
+    # `Retry-After` is seconds or an HTTP-date. The body may also carry it as
+    # `retryAfterSeconds`, and the body wins when both are present because it
+    # is the value the limiter actually computed.
+    def parse_retry_after(header, envelope = {})
+      from_body = envelope['retryAfterSeconds']
+      return from_body.to_f if from_body.is_a?(Numeric)
+
+      return nil if header.nil? || header.to_s.strip.empty?
+
+      text = header.to_s.strip
+      return text.to_f if /\A\d+(\.\d+)?\z/.match?(text)
+
+      begin
+        seconds = Time.httpdate(text) - Time.now
+        seconds.positive? ? seconds : 0.0
+      rescue ArgumentError
+        nil
+      end
+    end
+  end
+end

data/lib/posthaste/http_client.rb

@@ -0,0 +1,256 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'net/http'
+require 'uri'
+
+require_relative 'errors'
+require_relative 'redaction'
+require_relative 'version'
+
+module Posthaste
+  # The default host. Override it with `base_url:` when self-hosting.
+  DEFAULT_BASE_URL = 'https://api.posthastemail.dev'
+
+  # One HTTP response, in the shape the retry loop wants.
+  Response = Struct.new(:status, :body, :headers, keyword_init: true) do
+    # HTTP header names are not case-sensitive and the sources these come from
+    # disagree about casing: Net::HTTP preserves what the server sent, a
+    # hand-written test double does whatever its author typed.
+    def header(name)
+      wanted = name.to_s.downcase
+      pair = (headers || {}).find { |k, _| k.to_s.downcase == wanted }
+      pair && pair[1]
+    end
+  end
+
+  # The seam every test stubs.
+  #
+  # A transport takes a fully-built request and returns a Response. It knows
+  # nothing about retries, authentication or error typing — all of which live in
+  # HttpClient — so a test double is four lines and still exercises the whole
+  # policy above it.
+  class NetHttpTransport
+    def initialize(open_timeout: 10, read_timeout: 30)
+      @open_timeout = open_timeout
+      @read_timeout = read_timeout
+    end
+
+    def call(method, url, headers, body)
+      uri = URI.parse(url)
+      request = Net::HTTP.const_get(method.to_s.capitalize).new(uri)
+      headers.each { |name, value| request[name] = value }
+      request.body = body if body
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == 'https'
+      http.open_timeout = @open_timeout
+      http.read_timeout = @read_timeout
+      # Redirects are NOT followed. A 3xx would send the bearer token to
+      # whatever host the Location names, so it arrives at the caller as an
+      # unhandled answer instead.
+      response = http.request(request)
+
+      Response.new(
+        status: response.code.to_i,
+        body: response.body.to_s,
+        headers: response.each_header.to_h
+      )
+    end
+
+    # No key here, but the timeouts are the only state and printing them is
+    # useful. Defined anyway so the class never inherits a default `#inspect`
+    # if somebody adds an ivar later.
+    def inspect
+      "#<Posthaste::NetHttpTransport open_timeout=#{@open_timeout} read_timeout=#{@read_timeout}>"
+    end
+  end
+
+  # Authentication, the retry policy, and turning a refusal into an exception.
+  #
+  # The retry rules are ported from the Python and TypeScript SDKs rather than
+  # reinvented, so a Rails app and a Python worker hitting the same API behave
+  # the same way under the same throttle.
+  class HttpClient
+    DEFAULT_MAX_RETRIES = 2
+    DEFAULT_MAX_RETRY_DELAY = 60.0
+
+    # First backoff step, in seconds. Doubles per attempt, capped at 8s, with
+    # full jitter applied on top.
+    BASE_BACKOFF = 0.5
+    MAX_BACKOFF = 8.0
+
+    def initialize(api_key:, base_url: DEFAULT_BASE_URL, transport: nil,
+                   max_retries: DEFAULT_MAX_RETRIES, max_retry_delay: DEFAULT_MAX_RETRY_DELAY,
+                   open_timeout: 10, read_timeout: 30, user_agent: nil,
+                   sleeper: nil, randomizer: nil)
+      @api_key = api_key.to_s
+      @base_url = base_url.to_s.sub(%r{/+\z}, '')
+      @transport = transport || NetHttpTransport.new(open_timeout: open_timeout,
+                                                     read_timeout: read_timeout)
+      @max_retries = max_retries
+      @max_retry_delay = max_retry_delay
+      @user_agent = user_agent || self.class.default_user_agent
+      # Injected so the retry tests do not actually wait, and so the jitter is
+      # deterministic under test without the policy itself knowing it is a test.
+      @sleeper = sleeper || ->(seconds) { sleep(seconds) }
+      @randomizer = randomizer || -> { Kernel.rand }
+    end
+
+    def self.default_user_agent
+      mailer = defined?(::ActionMailer::VERSION::STRING) ? ::ActionMailer::VERSION::STRING : 'none'
+      "posthaste-rails/#{Posthaste::VERSION} ruby/#{RUBY_VERSION} actionmailer/#{mailer}"
+    end
+
+    # `POST /v1/emails`.
+    #
+    # Two success statuses, and they mean different things:
+    #   202 {"status":"queued"}    — accepted, a new message exists.
+    #   200 {"status":"duplicate"} — an idempotency replay. No new message was
+    #                                created; the id is the original's.
+    #
+    # `idempotent:` is the whole retry rule. Without an idempotency key a retry
+    # after a lost response sends the email TWICE, so a send is only repeated
+    # automatically when the caller supplied one.
+    def send_email(payload, idempotent:)
+      decode(perform('post', '/v1/emails', payload, idempotent: idempotent))
+    end
+
+    # Never prints the key. See Posthaste::Redaction for why this matters.
+    def inspect
+      "#<Posthaste::HttpClient base_url=#{@base_url.inspect} " \
+        "api_key=#{Redaction.describe_key(@api_key).inspect} max_retries=#{@max_retries}>"
+    end
+    alias to_s inspect
+
+    private
+
+    def decode(response)
+      return {} if response.body.to_s.empty?
+
+      parsed = JSON.parse(response.body)
+      parsed.is_a?(Hash) ? parsed : {}
+    rescue JSON::ParserError => e
+      raise ServerError.new(
+        "the API answered #{response.status} with a body that is not JSON: #{e.message}",
+        type: 'internal', status: response.status, api_key: @api_key
+      )
+    end
+
+    def perform(method, path, payload, idempotent:)
+      url = "#{@base_url}#{path}"
+      headers = build_headers(body: !payload.nil?)
+      body = payload.nil? ? nil : JSON.generate(payload)
+
+      attempt = 0
+      loop do
+        begin
+          response = @transport.call(method, url, headers, body)
+        rescue StandardError => e
+          error = transport_error(e)
+          # A connection that never produced a response is safe to repeat only
+          # under the same rule as everything else: the request has to be one
+          # that repeating cannot duplicate.
+          if idempotent && attempt < @max_retries
+            @sleeper.call(jittered_backoff(attempt))
+            attempt += 1
+            next
+          end
+          raise error
+        end
+
+        # `< 300`, not `< 400`. The transport refuses to follow redirects, so a
+        # 3xx arrives here as an unhandled answer rather than as a success —
+        # reporting it beats handing back an empty body as though it worked.
+        return response if response.status < 300
+
+        error = ErrorMapping.from_response(
+          response.status,
+          response.body,
+          response.header('retry-after'),
+          request_id: response.header('x-request-id'),
+          api_key: @api_key
+        )
+
+        wait = retry_delay_for(error, idempotent: idempotent, attempt: attempt)
+        raise error if wait.nil?
+
+        @sleeper.call(wait)
+        attempt += 1
+      end
+    end
+
+    # How long to wait before repeating, or nil for "do not".
+    #
+    # The decision branches on `error.type` and NOT on the status, which is the
+    # whole point. All FOUR of these are 429 and they mean four different
+    # things:
+    #
+    #   rate_limited          the per-key request limiter. Transient, measured
+    #                         in seconds — exactly what a retry is for.
+    #   platform_paused       the platform-wide daily send ceiling. Also
+    #                         transient, and NOT a statement about this account.
+    #   daily_limit_reached   the account's warmup cap. `Retry-After` is the
+    #                         seconds until midnight UTC.
+    #   monthly_limit_reached the plan allowance. `Retry-After` can be weeks.
+    #
+    # A retry loop written against the status treats the last two as a hiccup
+    # and hammers a wall it cannot get through until the calendar moves.
+    def retry_delay_for(error, idempotent:, attempt:)
+      return nil if attempt >= @max_retries
+      return nil unless idempotent
+      # Quota exhaustion. Never in process, whatever Retry-After says.
+      return nil if error.quota_exhausted?
+      return nil unless error.transient?
+
+      requested = error.retry_after_seconds
+      unless requested.nil?
+        # Honour it — unless honouring it would mean blocking for longer than a
+        # caller could reasonably want, in which case hand the error back and
+        # let them schedule.
+        return nil if requested > @max_retry_delay
+
+        return [requested, 0.0].max
+      end
+
+      jittered_backoff(attempt)
+    end
+
+    # Exponential with FULL jitter.
+    #
+    # Without jitter every client that failed on the same upstream blip retries
+    # in the same millisecond, and the recovery attempt is itself a thundering
+    # herd against a service that has only just come back.
+    def jittered_backoff(attempt)
+      ceiling = [MAX_BACKOFF, BASE_BACKOFF * (2.0**attempt)].min
+      @randomizer.call * ceiling
+    end
+
+    def build_headers(body:)
+      headers = {
+        'accept' => 'application/json',
+        'user-agent' => @user_agent
+      }
+      headers['content-type'] = 'application/json' if body
+      # Last, so nothing above can replace it.
+      headers['authorization'] = "Bearer #{@api_key}"
+      headers
+    end
+
+    def transport_error(cause)
+      timeout = cause.is_a?(Timeout::Error) ||
+                cause.class.name.include?('Timeout') ||
+                cause.is_a?(Net::OpenTimeout) ||
+                cause.is_a?(Net::ReadTimeout)
+      klass = timeout ? Posthaste::TimeoutError : Posthaste::ConnectionError
+      # The cause's message can quote the request line, which can quote the
+      # Authorization header, so it goes through `redact` like everything else.
+      klass.new(
+        "#{cause.class}: #{cause.message}",
+        type: timeout ? 'timeout' : 'connection_error',
+        status: 0,
+        api_key: @api_key
+      )
+    end
+  end
+end