posthaste-rails 0.1.0

data/lib/posthaste/message_mapper.rb

@@ -0,0 +1,494 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'json'
+
+require_relative 'errors'
+
+module Posthaste
+  # Something this gem had to change to express the message. Reported on
+  # `mail.posthaste_result.warnings` and passed to the `on_warning` hook, so you
+  # find out on the first send rather than in a support ticket.
+  MappingWarning = Struct.new(:field, :code, :message, keyword_init: true) do
+    def to_s
+      "#{field}: #{message}"
+    end
+  end
+
+  # Turning a `Mail::Message` into the body of `POST /v1/emails`.
+  #
+  # ActionMailer hands the delivery method a fully-composed `Mail::Message`,
+  # which is a rich RFC 5322 object; the send API takes FIELDS. Every part of
+  # the message therefore lands in one of four buckets, and the governing rule
+  # is that NOTHING IS DROPPED IN SILENCE — a team that migrates and does not
+  # notice their Bcc stopped arriving is the outcome this design exists to
+  # prevent. So:
+  #
+  #   mapped        it becomes a field, unchanged
+  #   mapped, noted it becomes a field with something changed, and a
+  #                 MappingWarning says what
+  #   refused       a synchronous MappingError naming the field, before any
+  #                 request is made
+  #   generated     the platform composes it (Date, Message-ID, MIME structure,
+  #                 DKIM-Signature) and the Mail object's copy is an artefact of
+  #                 Mail, not authored intent, so it is discarded quietly
+  class MessageMapper
+    # Header names the platform owns, ported from `packages/mail/src/mime.ts`'s
+    # RESERVED_HEADER_NAMES.
+    #
+    # Sending one of these is a 400 from the API's own `reservedHeader`
+    # refinement, so catching it here only changes WHEN the caller finds out —
+    # synchronously, naming the first-class field to use instead, rather than
+    # after a round trip with a message about a "refinement".
+    #
+    # WHY EACH GROUP IS RESERVED (the reasons are the point): identity and
+    # routing headers are DKIM-signed by the platform, so a customer copy either
+    # duplicates a signed header — some receivers reject two `From`s — or drifts
+    # from the signed value and fails DMARC. Delivery-controlling headers
+    # (`Bcc`, `Cc`, `Sender`, `Return-Path`) would silently fan a message out or
+    # mislead bounce handling. Trust and trace headers (`DKIM-Signature`,
+    # `Received`, `Authentication-Results`, `ARC-*`) are the audit trail a
+    # receiver reads, and forging them is forging it. `Feedback-ID` is the key
+    # Google aggregates complaint rates by, so a customer who could set it could
+    # file their complaints under somebody else's identifier.
+    RESERVED_HEADER_NAMES = %w[
+      from to cc bcc sender subject date message-id mime-version content-type
+      content-transfer-encoding content-disposition return-path dkim-signature
+      received authentication-results list-unsubscribe list-unsubscribe-post
+      feedback-id
+    ].freeze
+
+    # Reserved names this mapper reads into a first-class field. Their value is
+    # carried, not lost, so they never reach the `headers` map and never warn.
+    CONSUMED = %w[from to cc bcc subject reply-to list-unsubscribe].freeze
+
+    # Reserved names that are an artefact of composing the message in Ruby.
+    #
+    # `Date` and `Message-ID` are in here on EVIDENCE, not on assumption: Mail
+    # puts both on every message before the delivery method sees it, so warning
+    # about them would fire on every single send and train people to ignore
+    # warnings — which is precisely how the ones that matter get missed. The
+    # MIME headers are structure the platform rebuilds, and the bytes the
+    # recipient's client decodes are identical either way.
+    #
+    # All of them are listed in the README under what the platform composes.
+    GENERATED = %w[
+      date message-id mime-version content-type content-transfer-encoding
+      content-disposition list-unsubscribe-post
+    ].freeze
+
+    # The first-class field to reach for instead, named in the error, because
+    # "you may not set this" without "set that" is a dead end for somebody
+    # mid-migration.
+    ALTERNATIVE = {
+      'sender' => 'the mailer\'s `from:`',
+      'return-path' => 'nothing — bounces are routed by the platform\'s own VERP return path',
+      'dkim-signature' => 'nothing — the platform signs every message with your verified key',
+      'received' => 'nothing — the trace is written by the receiving hops',
+      'authentication-results' => 'nothing — this is written by the receiver, not the sender',
+      'feedback-id' => '`X-Posthaste-Tags`, which is what the log and analytics filter on'
+    }.freeze
+
+    # Fields the send API has that ActionMailer has no word for.
+    #
+    # An `X-Posthaste-…` header is the one extension point ActionMailer offers
+    # without changing a single `mail()` call's shape: `mail()` passes any
+    # unrecognised key straight through as a header, so
+    # `mail(to: …, 'X-Posthaste-Stream' => 'transactional')` works today in
+    # every Rails version. They are CONSUMED here and never forwarded.
+    CONTROL_PREFIX = 'x-posthaste-'
+    CONTROL_HEADERS = {
+      'x-posthaste-stream' => :stream,
+      'x-posthaste-tags' => :tags,
+      'x-posthaste-metadata' => :metadata,
+      'x-posthaste-idempotency-key' => :idempotency_key,
+      'x-posthaste-template' => :template,
+      'x-posthaste-template-version' => :template_version,
+      'x-posthaste-variables' => :variables,
+      'x-posthaste-scheduled-at' => :scheduled_at
+    }.freeze
+
+    attr_reader :warnings
+
+    # `defaults` are the settings-level values applied to every message:
+    # `stream`, `tags`, `metadata`. A control header on an individual message
+    # overrides them.
+    def initialize(defaults = {})
+      @defaults = defaults
+      @warnings = []
+    end
+
+    # => [payload_hash, warnings]
+    def call(mail)
+      @warnings = []
+      control = extract_control(mail)
+
+      payload = {}
+      payload[:from] = map_from(mail)
+      payload[:to] = map_recipients(mail, :to)
+
+      cc = map_recipients(mail, :cc)
+      payload[:cc] = cc unless cc.empty?
+      bcc = map_recipients(mail, :bcc)
+      payload[:bcc] = bcc unless bcc.empty?
+
+      subject = mail.subject
+      payload[:subject] = subject if subject && !subject.empty?
+
+      reply_to = map_reply_to(mail)
+      payload[:replyTo] = reply_to if reply_to
+
+      list_unsubscribe = single_header(mail, 'List-Unsubscribe')
+      payload[:listUnsubscribe] = list_unsubscribe if list_unsubscribe
+
+      apply_body(payload, mail, control)
+      attachments = map_attachments(mail)
+      payload[:attachments] = attachments unless attachments.empty?
+
+      headers = map_headers(mail)
+      payload[:headers] = headers unless headers.empty?
+
+      apply_control(payload, control)
+
+      if payload[:to].empty?
+        raise MappingError.new(
+          'the message has no `to` recipient, so there is nobody to send it to',
+          type: 'unmappable_message'
+        )
+      end
+
+      [payload, @warnings]
+    end
+
+    private
+
+    def warn(field, code, message)
+      @warnings << MappingWarning.new(field: field, code: code, message: message)
+    end
+
+    # `from` keeps the display name — the API accepts a full `Name <a@b>` — but
+    # there can only be one of it.
+    def map_from(mail)
+      field = mail[:from]
+      formatted = field ? Array(field.formatted) : []
+
+      if formatted.empty?
+        raise MappingError.new(
+          'the message has no `from` address. Set one on the mailer, or as ' \
+          '`default from:` on ActionMailer::Base.',
+          type: 'unmappable_message'
+        )
+      end
+
+      if formatted.length > 1
+        # Nearly always an UNQUOTED COMMA in a display name — `from: "Acme,
+        # Inc. <billing@acme.test>"` is two addresses to any RFC 5322 parser,
+        # `Acme` and `"Inc." <billing@acme.test>`. Refusing names the trap,
+        # because silently taking the first would send from a domain-less
+        # address and fail far away from the cause.
+        raise MappingError.new(
+          "`from` resolved to #{formatted.length} addresses (#{formatted.join('; ')}) and a " \
+          'message has exactly one sender. If the display name contains a comma it must be ' \
+          'quoted: from: %q("Acme, Inc." <billing@acme.test>).',
+          type: 'unmappable_message'
+        )
+      end
+
+      formatted.first
+    end
+
+    # Recipients are addressed by BARE ADDRESS.
+    #
+    # This is the one place the mapping loses something a recipient could have
+    # seen, and it is only how their own address is labelled in their own client
+    # — which most clients override from the address book anyway. Refusing
+    # instead would break the migration for nearly every application that has
+    # ever set a recipient name, so it is a warning.
+    def map_recipients(mail, field_name)
+      field = mail[field_name]
+      return [] unless field
+
+      addresses = Array(mail.public_send(field_name))
+      named = Array(field.formatted).count { |f| f.include?('<') }
+      if named.positive?
+        warn(field_name.to_s, 'display_name_dropped',
+             "#{named} display name(s) on `#{field_name}` were dropped; the API addresses " \
+             'recipients by bare address. The addresses themselves are unchanged.')
+      end
+      addresses.compact
+    end
+
+    def map_reply_to(mail)
+      field = mail[:reply_to]
+      return nil unless field
+
+      formatted = Array(field.formatted)
+      return nil if formatted.empty?
+
+      formatted.join(', ')
+    end
+
+    def single_header(mail, name)
+      field = mail[name]
+      return nil unless field
+
+      value = field.respond_to?(:value) ? field.value : field.to_s
+      value.to_s.empty? ? nil : value.to_s
+    end
+
+    # `text` and `html`, from wherever the message put them.
+    #
+    # `Mail::Message#text_part` / `#html_part` walk `all_parts` and skip
+    # attachments, so `multipart/mixed[ multipart/alternative[text,html], pdf ]`
+    # — the shape ActionMailer builds for a mailer with two templates and an
+    # attachment — resolves correctly. A non-multipart message has neither, and
+    # its own Content-Type decides which field the body is.
+    def apply_body(payload, mail, control)
+      text_part = mail.text_part
+      html_part = mail.html_part
+      refuse_unmappable_parts(mail, text_part, html_part)
+
+      text = part_body(text_part, mail)
+      html = part_body(html_part, mail)
+
+      if text.nil? && html.nil? && !mail.multipart?
+        body = decode_text(mail, mail)
+        unless body.nil? || body.empty?
+          if mail.mime_type == 'text/html'
+            html = body
+          else
+            text = body
+          end
+        end
+      end
+
+      if control[:template]
+        # A stored template supplies the content. Sending both would make the
+        # API choose, and which one it chose would be a surprise either way.
+        if text || html
+          warn('body', 'template_supersedes_body',
+               'X-Posthaste-Template is set, so the stored template supplies the content and ' \
+               'the rendered view was not sent. Remove one of the two.')
+        end
+        return
+      end
+
+      payload[:text] = text if text
+      payload[:html] = html if html
+    end
+
+    def part_body(part, mail)
+      return nil unless part
+
+      decode_text(part, mail)
+    end
+
+    # A part that is neither body nor attachment is REFUSED.
+    #
+    # This one is not theoretical, and it is the sharpest edge of "fields, not
+    # a MIME document". Two shapes fall through every other check:
+    #
+    #   * a `text/calendar` part — the standard way Rails apps send meeting
+    #     invitations — which is not `text_part`, not `html_part`, and not an
+    #     attachment;
+    #   * an attachment part with no filename, which `Mail::Message#attachments`
+    #     does not return at all, because Mail identifies an attachment BY its
+    #     filename.
+    #
+    # Both are invisible to `mail.attachments`, so without this the message
+    # would send, the API would accept it, and the part would simply not exist
+    # on the delivered mail. That is the silent loss this whole mapper is built
+    # to make impossible. The SMTP relay accepts a complete RFC 5322 message and
+    # is the right answer for these.
+    def refuse_unmappable_parts(mail, text_part, html_part)
+      return unless mail.multipart?
+
+      known = [text_part, html_part].compact
+      mail.all_parts.each do |part|
+        next if part.multipart?
+        next if part.attachment?
+        next if known.any? { |k| k.equal?(part) }
+
+        raise MappingError.new(
+          "the message has a #{part.mime_type || 'typeless'} part that is neither the text " \
+          'body, the html body, nor a named attachment, and the send API has no field for it. ' \
+          'Give it a filename to send it as an attachment, or use the SMTP relay, which ' \
+          'accepts a complete MIME message.',
+          type: 'unmappable_message'
+        )
+      end
+    end
+
+    # A `Mail::Part`'s `decoded` undoes the transfer encoding but hands back a
+    # String tagged with whatever encoding Ruby guessed. JSON generation needs
+    # valid UTF-8, so the charset the part declares is applied and the result is
+    # transcoded — never `force_encoding('UTF-8')` alone, which mislabels
+    # Latin-1 bytes as UTF-8 and produces invalid JSON at generate time.
+    def decode_text(part, mail)
+      raw = part.body.decoded
+      return nil if raw.nil?
+
+      charset = part.charset || mail.charset || 'UTF-8'
+      begin
+        raw.dup.force_encoding(charset).encode('UTF-8')
+      rescue ArgumentError, EncodingError
+        # An undeclared or wrong charset. Scrubbing beats raising: the message
+        # is still delivered and the damage is confined to the bytes that were
+        # already unreadable.
+        warn('body', 'charset_scrubbed',
+             "the body declared charset #{charset.inspect} but does not decode as it; " \
+             'unreadable bytes were replaced.')
+        raw.dup.force_encoding('UTF-8').scrub
+      end
+    end
+
+    def map_attachments(mail)
+      mail.attachments.map.with_index do |attachment, index|
+        filename = attachment.filename
+        if filename.nil? || filename.to_s.empty?
+          raise MappingError.new(
+            "attachment ##{index + 1} has no filename, and the API requires one. Give it a " \
+            "name: `attachments['report.pdf'] = …`.",
+            type: 'unmappable_message'
+          )
+        end
+
+        entry = {
+          filename: filename.to_s,
+          contentType: attachment.mime_type || 'application/octet-stream',
+          content: Base64.strict_encode64(attachment.body.decoded.to_s),
+          disposition: attachment.inline? ? 'inline' : 'attachment'
+        }
+        # Only for inline parts. `Mail::Part#cid` MANUFACTURES a Content-ID for
+        # any attachment that lacks one, so sending it unconditionally would
+        # attach a meaningless cid to every ordinary file.
+        entry[:cid] = attachment.cid if attachment.inline? && attachment.cid
+        entry
+      end
+    end
+
+    # Everything left over.
+    def map_headers(mail)
+      headers = {}
+      seen = {}
+
+      mail.header.fields.each do |field|
+        name = field.name.to_s
+        lower = name.downcase
+
+        next if CONSUMED.include?(lower)
+        next if lower.start_with?(CONTROL_PREFIX)
+        next if GENERATED.include?(lower)
+
+        if RESERVED_HEADER_NAMES.include?(lower) || lower.start_with?('arc-')
+          alternative = ALTERNATIVE[lower] || 'an `X-` header of your own'
+          raise UnsupportedHeaderError.new(
+            "`#{name}` is a header the platform owns and signs; setting it would either " \
+            "duplicate a DKIM-signed header or make the signature disagree with the message. " \
+            "Use #{alternative} instead.",
+            type: 'unmappable_message'
+          )
+        end
+
+        value = field.respond_to?(:value) ? field.value.to_s : field.to_s
+        if seen.key?(lower)
+          # The API's `headers` is one value per name. Keeping one of the two
+          # would be a silent choice about which of them the recipient sees.
+          raise MappingError.new(
+            "`#{name}` is set more than once (#{seen[lower].inspect} and #{value.inspect}) " \
+            'and the API carries one value per header name. Combine them, or drop one.',
+            type: 'unmappable_message'
+          )
+        end
+
+        seen[lower] = value
+        headers[name] = value
+      end
+
+      headers
+    end
+
+    # Read the `X-Posthaste-…` headers off the message and remove them, so they
+    # can never reach the wire as ordinary custom headers.
+    def extract_control(mail)
+      found = {}
+
+      mail.header.fields.select { |f| f.name.to_s.downcase.start_with?(CONTROL_PREFIX) }
+          .each do |field|
+        name = field.name.to_s
+        key = CONTROL_HEADERS[name.downcase]
+        unless key
+          # A typo in a control header would otherwise be forwarded as an
+          # inert custom header — the send would succeed and quietly ignore the
+          # stream, tags or idempotency key it was told to use.
+          raise MappingError.new(
+            "`#{name}` is not a Posthaste control header. Known ones are: " \
+            "#{CONTROL_HEADERS.keys.sort.join(', ')}.",
+            type: 'unmappable_message'
+          )
+        end
+
+        found[key] = field.respond_to?(:value) ? field.value.to_s : field.to_s
+      end
+
+      found
+    end
+
+    def apply_control(payload, control)
+      stream = control[:stream] || @defaults[:stream]
+      payload[:stream] = stream.to_s if stream
+
+      tags = control.key?(:tags) ? split_list(control[:tags]) : Array(@defaults[:tags])
+      payload[:tags] = tags.map(&:to_s) unless tags.empty?
+
+      metadata = control.key?(:metadata) ? json_object(control[:metadata], 'X-Posthaste-Metadata') : @defaults[:metadata]
+      payload[:metadata] = stringify(metadata) if metadata && !metadata.empty?
+
+      idempotency_key = control[:idempotency_key]
+      payload[:idempotencyKey] = idempotency_key.to_s if idempotency_key
+
+      payload[:template] = control[:template].to_s if control[:template]
+
+      if control[:template_version]
+        version = Integer(control[:template_version], exception: false)
+        unless version
+          raise MappingError.new(
+            'X-Posthaste-Template-Version must be an integer, got ' \
+            "#{control[:template_version].inspect}.",
+            type: 'unmappable_message'
+          )
+        end
+        payload[:templateVersion] = version
+      end
+
+      if control[:variables]
+        payload[:variables] = stringify(json_object(control[:variables], 'X-Posthaste-Variables'))
+      end
+
+      payload[:scheduledAt] = control[:scheduled_at].to_s if control[:scheduled_at]
+    end
+
+    def split_list(value)
+      value.to_s.split(',').map(&:strip).reject(&:empty?)
+    end
+
+    def json_object(value, header_name)
+      parsed = JSON.parse(value.to_s)
+      unless parsed.is_a?(Hash)
+        raise MappingError.new("#{header_name} must be a JSON object.", type: 'unmappable_message')
+      end
+
+      parsed
+    rescue JSON::ParserError => e
+      raise MappingError.new("#{header_name} is not valid JSON: #{e.message}",
+                             type: 'unmappable_message')
+    end
+
+    # The API takes `Record<string, string>` for both metadata and variables. A
+    # number or a boolean here is an ordinary thing for a Rails app to write and
+    # would be a 400 from the server; coercing costs nothing and reads the same.
+    def stringify(hash)
+      hash.each_with_object({}) { |(k, v), out| out[k.to_s] = v.to_s }
+    end
+  end
+end

data/lib/posthaste/railtie.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'rails/railtie'
+
+module Posthaste
+  # What the Railtie is for — and it is one specific thing.
+  #
+  # `config.action_mailer.posthaste_settings = { … }` only works if
+  # `add_delivery_method(:posthaste, …)` has already defined that accessor when
+  # Rails applies the `config.action_mailer.*` options. Rails applies them in
+  # its own `action_mailer.set_configs` initializer.
+  #
+  # The `ActiveSupport.on_load(:action_mailer)` hook in `actionmailer.rb`
+  # normally wins that race on its own, because the gem is required by
+  # `Bundler.require` before any initializer runs and load hooks fire in
+  # registration order. It does NOT win when the gem is listed as
+  # `require: false` and required later from `config/initializers/…`, which is
+  # a completely ordinary thing to do — and the failure mode is a
+  # `NoMethodError: undefined method 'posthaste_settings='` from
+  # `production.rb`, pointing at the configuration rather than at the ordering.
+  #
+  # `before: 'action_mailer.set_configs'` removes the race in both cases.
+  class Railtie < ::Rails::Railtie
+    initializer 'posthaste.add_delivery_method', before: 'action_mailer.set_configs' do
+      ActiveSupport.on_load(:action_mailer) do
+        Posthaste.register_delivery_method!(self)
+        Posthaste.extend_mail_message!
+      end
+    end
+  end
+end

data/lib/posthaste/redaction.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Posthaste
+  # Keeping the API key out of everything that can be printed.
+  #
+  # A key is a bearer credential: whoever holds it can send mail from every
+  # verified domain on the account. The places it escapes from are not the ones
+  # people guard — nobody logs the key on purpose. In Ruby it escapes through
+  # the DEFAULT `#inspect`, which prints every instance variable, and a lot of
+  # things call `#inspect` on your behalf:
+  #
+  #   * `p object`, and the console echoing a return value
+  #   * a `binding.irb` session pasted into a ticket
+  #   * Rails' exception page, which inspects the delivery method
+  #   * an error reporter (Sentry, Bugsnag, Honeybadger) capturing locals and
+  #     shipping them to a third party
+  #
+  # So every object in this gem that can reach the key defines its own
+  # `#inspect`, and every string built for a human goes through `redact` first.
+  module Redaction
+    REDACTED = '***redacted***'
+
+    # `ph_live_…` / `ph_test_…`. The prefix is not secret — it is printed in the
+    # dashboard beside every key — and it is the one piece that helps somebody
+    # staring at a 401 work out that they pasted the test key into production.
+    PREFIX = /\Aph_(?:live|test)_/
+
+    # Anything key-shaped, wherever it turns up. Used for text this gem did not
+    # build itself — a server message that echoed the credential back, a
+    # transport error that quoted the request line — where there is no key to
+    # compare against.
+    KEY_SHAPED = /ph_(?:live|test)_[A-Za-z0-9_-]{8,}/
+
+    module_function
+
+    # A label for a key that cannot be turned back into the key.
+    #
+    # Deliberately NOT the usual "last four characters" convention. Four
+    # characters of a token this size is not enough to authenticate with, but it
+    # is enough to confirm a guess, and the thing it is normally used for —
+    # telling two keys apart — is served just as well by the environment prefix
+    # without narrowing the search space at all.
+    def describe_key(api_key)
+      return '(none)' if api_key.nil? || api_key.to_s.empty?
+
+      match = PREFIX.match(api_key.to_s)
+      "#{match ? match[0] : ''}#{REDACTED}"
+    end
+
+    # Remove the key from a string meant for a human.
+    #
+    # Two passes on purpose. The first removes this client's own key, which
+    # catches it however short or oddly formatted it is. The second removes
+    # anything key-shaped, which catches a DIFFERENT account's key echoed back
+    # by a server or quoted by a library underneath us.
+    def redact(text, api_key = nil)
+      out = text.to_s
+      out = out.gsub(api_key.to_s, REDACTED) if api_key && !api_key.to_s.empty?
+      out.gsub(KEY_SHAPED, REDACTED)
+    end
+  end
+end

data/lib/posthaste/result.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Posthaste
+  # What the API said about one send.
+  #
+  # Reachable as `mail.posthaste_result` after `deliver_now`, because
+  # ActionMailer's own return value is the `Mail::Message` and there is nowhere
+  # else to put a message id that a caller needs in order to look the delivery
+  # up later.
+  class Result
+    attr_reader :id, :status, :group_id, :scheduled_at, :emails, :suppressed,
+                :warnings, :mapping_warnings, :raw
+
+    def initialize(body, mapping_warnings: [])
+      @raw = body
+      @id = body['id']
+      @status = body['status']
+      @group_id = body['groupId']
+      @scheduled_at = body['scheduledAt']
+      # Per-recipient outcome, present only when there was more than one.
+      @emails = body['emails'] || []
+      # Recipients skipped because they are on the suppression list. Repeated
+      # here as well as inside `emails` deliberately: a recipient we did not
+      # send to is the one outcome that must be impossible to miss.
+      @suppressed = body['suppressed'] || []
+      # The platform's pre-send lint findings, warnings included.
+      @warnings = body['warnings'] || []
+      # What this gem had to change to express the message.
+      @mapping_warnings = mapping_warnings
+    end
+
+    # An idempotency replay: no new message was created and `id` is the
+    # original's.
+    #
+    # Read off the BODY, not off a 200-versus-202, because the body is the
+    # authoritative answer and survives a proxy that normalises the status.
+    def duplicate?
+      status == 'duplicate'
+    end
+
+    def scheduled?
+      status == 'scheduled'
+    end
+
+    def inspect
+      "#<Posthaste::Result id=#{id.inspect} status=#{status.inspect} " \
+        "suppressed=#{suppressed.length} warnings=#{warnings.length}>"
+    end
+  end
+
+  # `Mail::Message#posthaste_result`.
+  #
+  # The only method this gem adds to somebody else's class, and it is additive:
+  # it reads an instance variable this gem set and returns nil otherwise, so a
+  # message delivered by any other delivery method is unaffected.
+  module MessageExtensions
+    def posthaste_result
+      defined?(@posthaste_result) ? @posthaste_result : nil
+    end
+  end
+end

data/lib/posthaste/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Posthaste
+  # Kept in step with the gemspec, which reads it from here rather than
+  # restating it — a version stated twice is a version that disagrees with
+  # itself the first time somebody bumps one of them.
+  VERSION = '0.1.0'
+end

data/lib/posthaste-rails.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# Bundler requires the file named after the gem. This is that file; the code
+# lives in `posthaste/actionmailer.rb`, because what it registers is an
+# ActionMailer delivery method and the path should say so.
+require_relative 'posthaste/actionmailer'