wakio 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2b058707e5d5a45ba09f1ab08a918b13cd24421ff6090c957ac42e8f7ef2ddb3
+  data.tar.gz: 90c415eb9823dfca80567242d5402d3d9a61cc3636d6b8e12ab768463c1851c0
+SHA512:
+  metadata.gz: c011065c01a89cdffab9684e0aa88a175f657e601246c0780aa193f85b2cf900b541b1709d20e454f011b7f5876243e11cb55c29354c961e3ca628abca5baa22
+  data.tar.gz: f53a850d624b30ccfb86a0525b88de4946d1534bd7cb2d053f983d1faf66cd70256045d4d42d4f7944272cce1479606e57235120263b04d1ecdba273b0cf1bc8

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WorkersLab LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,82 @@
+# wakio-rails
+
+```ruby
+# Gemfile
+gem "wakio"
+```
+
+```ruby
+# config/environments/production.rb
+config.action_mailer.delivery_method = :wakio
+config.action_mailer.wakio_settings = {
+  api_key: Rails.application.credentials.wakio_api_key,
+  host: "https://api.wakio.net"
+}
+```
+
+Every existing mailer keeps working unchanged. Its rendered subject, its HTML and text parts, and its `from` go to Wakio as they are, with no server-side template involved. A text-only mailer sends a text-only email.
+
+The `from` domain must be one of your account's sendable sending domains, matched exactly: `hello@acme.com` needs `acme.com` itself verified, and a verified `mail.acme.com` does not cover it. A mismatch is refused with `422 no_verified_sending_domain`. A mailer with no `from` goes out as `no-reply@` your first sendable domain. `GET /v1/sending-identities` reports which domains are currently sendable.
+
+## Limitations worth knowing before you switch a mailer over
+
+**A suppressed address raises.** Wakio suppresses addresses that have hard-bounced or complained, and accepts a send to one rather than refusing it. The response names each recipient's status, and `deliver!` raises `Wakio::Suppressed` (a `Wakio::DeliveryError`) when every recipient was suppressed, so a one-recipient mailer to a suppressed address fails loudly instead of reporting success. Retrying cannot help, so handle it rather than letting a job backend retry it: `rescue_from Wakio::Suppressed` in your mailer also catches it under `deliver_later`. A send where only some recipients were suppressed returns normally; check the returned response's `deliveries` for which ones.
+
+**Fifty recipients per request.** `to`, `cc` and `bcc` are counted together, once
+case-insensitive duplicates collapse, against Wakio's own contract limit — and the
+whole request is refused past it rather than truncated. The number mirrors SES's own
+per-message recipient ceiling, but it is not that ceiling enforced on you: Wakio fans
+one call out into one SES message per recipient, so no individual message SES sees
+ever approaches it. It reads "per request" and not "per message" for that reason —
+the limit bounds what one `deliver!` call may name, not what any single message
+contains.
+
+**This gem does not send the mailer's `attachments`.** No files reach the recipient. Call the HTTP API directly for a send that needs them.
+
+**Ten megabytes of attachments per request** — a limit of the HTTP API you would call
+directly for the send above, since this gem posts no attachments of its own. Attachment
+content is read once from the request, not once per recipient — but Wakio still writes an
+independent copy of it to every recipient's own delivery record, so the same bytes are
+materialised once per recipient server-side. A second ceiling catches that: attachment
+bytes times recipient count may not exceed 50 MB. The full 10 MB is only available up to
+five recipients on one request; at the 50-recipient limit, attachments may total at most
+1 MB. A third caps the count rather than the size: at most 20 attachments on one request,
+however small they are.
+
+**Every recipient gets their own delivery record.** A `cc`'d address receives a
+separate message, so reply-all does not reach them, and each recipient is billed
+and gated separately.
+
+**`host` must not carry a path.** The endpoint is resolved with `URI.join`, so a
+configured host of `https://api.wakio.net/api` yields
+`https://api.wakio.net/v1/emails` — the `/api` is discarded. Give the bare
+origin.
+
+## Making a send idempotent
+
+Set a header on the message and it becomes the request's `Idempotency-Key`:
+
+```ruby
+class OrderMailer < ApplicationMailer
+  def receipt(order)
+    headers["X-Wakio-Idempotency-Key"] = "order-#{order.id}-receipt"
+    mail(to: order.email)
+  end
+end
+```
+
+A retry carrying a key Wakio has already seen, with a byte-identical request body,
+returns the original response instead of sending again, for 24 hours. The same key
+with any other body is refused with `422 idempotency_key_reused`, and a retry that
+arrives while the first request is still being processed gets `409 request_in_flight`.
+
+**Supply one whenever a duplicate would be worse than a missing send** — receipts,
+invoices, welcome emails. **Leave it off, or vary it, when a repeat is the point** — a
+resent one-time code needs to arrive even if it is identical to the last one.
+
+The gem never invents a key, and that is deliberate. Only you can tell a retry of one
+send apart from a deliberate repeat of identical content: a receipt for order 1234 has
+an obvious stable key, a resent OTP needs a fresh one, and both can produce byte-identical
+requests. The difference is intent, not data, so nothing here could infer it. Earlier
+versions sent the message's `Message-ID`, which ActionMailer regenerates on every
+delivery attempt — so it changed on exactly the retry it was supposed to catch.

data/lib/wakio/delivery_method.rb

@@ -0,0 +1,136 @@
+require "json"
+require "net/http"
+require "uri"
+
+module Wakio
+  DeliveryError = Class.new(StandardError)
+  Suppressed = Class.new(DeliveryError)
+
+  # An ActionMailer delivery method, so a host app keeps every existing mailer
+  # untouched and changes only configuration.
+  class DeliveryMethod
+    attr_reader :settings
+
+    def initialize(settings = {})
+      @settings = settings
+    end
+
+    # The mail header a caller sets to make a send idempotent. Not `Idempotency-Key`,
+    # so it cannot be confused with the outgoing HTTP header, and X- prefixed so it is
+    # obviously ours if it ever leaks into a message dump.
+    IDEMPOTENCY_HEADER = "X-Wakio-Idempotency-Key".freeze
+
+    def deliver!(mail)
+      # Caller-supplied, never derived — and no key at all when the caller gives none.
+      #
+      # This used to send the mail's own Message-ID. That is minted fresh every time
+      # ActionMailer builds the message, and MailDeliveryJob re-runs the mailer method
+      # on every delivery attempt, so a retried `deliver_later` carried a *different*
+      # key and the server deduplicated nothing. The header looked like a guarantee
+      # while providing none, which is worse than its absence.
+      #
+      # Deriving from the payload instead would break the case that matters most here:
+      # a resent OTP can be byte-identical to the original, so a content hash would
+      # silently swallow the resend and the recipient would never get their code. Only
+      # the caller can distinguish "this is a retry of one send" from "this is a
+      # deliberate repeat", because the difference is intent rather than data.
+      response = post(payload_for(mail), idempotency_key: mail[IDEMPOTENCY_HEADER]&.to_s)
+      unless response.code.to_i.between?(200, 299)
+        raise DeliveryError, "Wakio returned #{response.code}: #{response.body}"
+      end
+
+      # A separate check from the status above, deliberately: `accepted_any?` only ever
+      # returns true or raises today, but joining the two into one `&&` condition would
+      # leave a future `false` return falling through to the status-code raise above —
+      # misreporting a rejection this method caught as a problem with the response's
+      # 2xx status, which was never in question.
+      raise DeliveryError, "Wakio did not accept any recipient" unless accepted_any?(response)
+
+      response
+    end
+
+    private
+
+    def payload_for(mail)
+      html, text = bodies_for(mail)
+      {
+        to: Array(mail.to),
+        cc: Array(mail.cc),
+        bcc: Array(mail.bcc),
+        reply_to: Array(mail.reply_to),
+        from: mail[:from]&.value,
+        subject: mail.subject.to_s.gsub(/[[:space:]]+/, " ").strip,
+        html: html,
+        text: text
+      }.compact
+    end
+
+    # Parts, not `mail.body.decoded`: on a multipart message that is `""`, and multipart is
+    # what every Rails mailer with both an .html.erb and a .text.erb view produces.
+    def bodies_for(mail)
+      if mail.multipart?
+        [ mail.html_part&.decoded, mail.text_part&.decoded ]
+      elsif mail.mime_type == "text/html"
+        [ mail.decoded, nil ]
+      else
+        [ nil, mail.decoded ]
+      end
+    end
+
+    # A suppression is the gate working, not a delivery failure — but a request where
+    # every recipient was suppressed delivered nothing, so this raises rather than
+    # reporting success.
+    #
+    # Each shape is checked before it is used, rather than caught after the fact: a JSON
+    # scalar (`null`, `123`, `"ok"` - a proxy, a CDN error page that happens to be valid
+    # JSON) parses cleanly and only then answers #key? with NoMethodError, which is not in
+    # the rescue below and so escapes a host app rescuing DeliveryError. Adding NoMethodError
+    # to that rescue would swallow a real bug in this file just as readily; raising
+    # DeliveryError here does not, because the rescue names two other classes.
+    def accepted_any?(response)
+      body = JSON.parse(response.body)
+      unreadable!(response) unless body.is_a?(Hash)
+      if body.key?("id")
+        return true unless body["status"] == "suppressed"
+
+        raise Suppressed, "Wakio accepted no recipient: the address is suppressed"
+      end
+
+      entries = body.fetch("deliveries", [])
+      # `all?(Hash)` and not only `is_a?(Array)`: `{"deliveries": ["a"]}` clears the Array
+      # check, and `"a"["status"]` is String#[] returning nil rather than an error - so an
+      # unusable body would report every recipient accepted instead of being refused.
+      unreadable!(response) unless entries.is_a?(Array) && entries.all? { |entry| entry.is_a?(Hash) }
+      return true if entries.any? { |entry| entry["status"] != "suppressed" }
+
+      if entries.empty?
+        raise DeliveryError, "Wakio's response named no delivery at all: #{response.body}"
+      end
+
+      raise Suppressed,
+            "Wakio accepted no recipient: " +
+            entries.map { |e| "#{e['email']} #{e['status']}" }.join(", ")
+    rescue JSON::ParserError, TypeError
+      unreadable!(response)
+    end
+
+    def unreadable!(response)
+      raise DeliveryError, "Wakio returned an unreadable body: #{response.body}"
+    end
+
+    def post(payload, idempotency_key:)
+      uri = URI.join(settings.fetch(:host), "/v1/emails")
+      request = Net::HTTP::Post.new(uri)
+      request["Authorization"] = "Bearer #{settings.fetch(:api_key)}"
+      request["Content-Type"] = "application/json"
+      # NOT `idempotency_key.present?` — that is ActiveSupport, and this gem
+      # deliberately depends on nothing but the stdlib plus `mail`.
+      request["Idempotency-Key"] = idempotency_key unless idempotency_key.nil? || idempotency_key.empty?
+      request.body = payload.to_json
+
+      Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
+        http.request(request)
+      end
+    end
+  end
+end

data/lib/wakio/rails.rb

@@ -0,0 +1,11 @@
+require "wakio/delivery_method"
+
+module Wakio
+  module Rails
+    def self.install!
+      ActionMailer::Base.add_delivery_method(:wakio, Wakio::DeliveryMethod)
+    end
+  end
+end
+
+ActiveSupport.on_load(:action_mailer) { Wakio::Rails.install! }

data/lib/wakio.rb

@@ -0,0 +1 @@
+require "wakio/rails"

metadata

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification
+name: wakio
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- WorkersLab LLC
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: actionmailer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/wakio.rb
+- lib/wakio/delivery_method.rb
+- lib/wakio/rails.rb
+homepage: https://wakio.net/docs
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: ActionMailer delivery method for Wakio
+test_files: []