wakio 0.1.1 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0b10c47e80d5a8cdb7eb94e86babdcf24674b8b0563313a4b12459cbcc2ddf74
-  data.tar.gz: 8053fbb8ebe24f105513e04e8856ea18614b86ab25b2b34e89ad8fdadabe2462
+  metadata.gz: 41b4696d5b5dcea8872174fce7d104adeb163eb775555de498214e2ba1c49711
+  data.tar.gz: 1b7eaa7f2b2e4540b4f60a4beb979718262b54a35e64c34a52fc931aa1a748d0
 SHA512:
-  metadata.gz: d45c860e93f1c69bb3620f11dbb68179c3142bb63a8bb418e39b1c016c14d6bdba14971e3f5f3582a054dbb514f5b03c96dd8b22eeef77248058f99e8ed8ff5f
-  data.tar.gz: 8c6f7c5cb040922d14a6b2828775bdfe6ad103cf7c1bdf07123b2722e81bd78f281caae194a803fe0852d2b3bee3ed3fdd182124918c103a23447828f1630ddc
+  metadata.gz: ec7af6244e5c01a97da9b8455b23475dbf4d26a86df036e0cc97ec341020b19dc7b9b851307185f5d4d2a8052a3e53cb4db37a28f350c39acd23ea6762baae07
+  data.tar.gz: 99b951382c14c5ee5732411f3ce2f4fc75c3128c9283d495d48763881fae5d1593630886970c55a82f89148a519a881f2e7ddc41b8968d2e252726381ffaf97b

data/README.md

@@ -14,7 +14,9 @@ config.action_mailer.wakio_settings = {
 }
 ```
 
-`open_timeout` and `read_timeout` are optional, in seconds, and default to 5 and 10. A timeout raises `Net::OpenTimeout` or `Net::ReadTimeout`, not `Wakio::DeliveryError`. A read timeout can come after Wakio accepted the send, so a retry without an idempotency key (below) may send twice.
+`open_timeout` and `read_timeout` are optional, in seconds, and default to 5 and 10. A timeout raises `Net::OpenTimeout` or `Net::ReadTimeout`, and any other network failure raises Ruby's own error, not `Wakio::DeliveryError`. A read timeout can come after Wakio accepted the send, so a retry without an idempotency key (below) may send twice.
+
+`host` must be `https`. An `http` host other than `localhost` raises `Wakio::Misconfigured` before anything is sent, so the API key never travels in cleartext.
 
 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.
 
@@ -24,7 +26,36 @@ The `from` domain must be one of your account's sendable sending domains, matche
 
 **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.
 
-**A refusal a retry cannot fix raises `Wakio::Rejected`.** Every 4xx except `409 request_in_flight` raises it: a revoked key, an unverified `from` domain, an idempotency key reused with a different body. It is a `Wakio::DeliveryError` carrying `status`, `code` (the response's `error`, such as `"no_verified_sending_domain"`) and the parsed `body`, so a host app can `discard_on` it or alert instead of letting a job backend retry it for weeks. A 409 and every 5xx stay a plain `Wakio::DeliveryError`, because a retry is the right response to both.
+**Refusals split by whether a retry can ever send the message.** A refusal from Wakio is a `Wakio::DeliveryError` carrying `status`, `code` (the response's `error`, such as `"invalid_request"`) and the parsed `body`.
+
+- `Wakio::Rejected`: retrying this message cannot help. `400`, `413`, `422 invalid_request` (usually a mailer bug; `detail` names the field) and `422 idempotency_key_reused` (an earlier request with that key already went out). Report it and drop it.
+- `Wakio::Misconfigured`: the account or its configuration is wrong, and the same message sends once that is fixed. `401 invalid_api_key`, `402 not_entitled`, `403 account_suspended`, `404`, `422 no_verified_sending_domain`, `422 unknown_template`, a redirect, an `http` host, and any 4xx this gem does not know. Retry it.
+- A plain `Wakio::DeliveryError`: `409 request_in_flight`, every 5xx, and a success response the gem cannot read. Retry it; after an unreadable success only a keyed send is safe to repeat.
+
+Action Mailer's delivery job retries nothing itself, and Solid Queue and GoodJob do not retry a failed job by default, so give it a policy:
+
+```ruby
+class WakioDeliveryJob < ActionMailer::MailDeliveryJob
+  retry_on Wakio::DeliveryError, Net::OpenTimeout, Net::ReadTimeout, wait: :polynomially_longer, attempts: 25
+end
+
+# config/application.rb
+config.action_mailer.delivery_job = "WakioDeliveryJob"
+```
+
+The mailer's `rescue_from` below catches `Suppressed` and `Rejected` before the job sees them.
+
+```ruby
+class ApplicationMailer < ActionMailer::Base
+  rescue_from Wakio::Suppressed do |error|
+    Rails.logger.info(error.message)
+  end
+
+  rescue_from Wakio::Rejected do |error|
+    Rails.error.report(error)
+  end
+end
+```
 
 **Fifty recipients per request.** `to`, `cc` and `bcc` are counted together, once
 case-insensitive duplicates collapse, against Wakio's own contract limit — and the

data/lib/wakio/delivery_method.rb

@@ -3,13 +3,10 @@ require "net/http"
 require "uri"
 
 module Wakio
-  DeliveryError = Class.new(StandardError)
-  Suppressed = Class.new(DeliveryError)
-
-  class Rejected < DeliveryError
+  class DeliveryError < StandardError
     attr_reader :status, :code, :body
 
-    def initialize(message, status:, body:)
+    def initialize(message = nil, status: nil, body: nil)
       super(message)
       @status = status
       @body = body
@@ -17,6 +14,10 @@ module Wakio
     end
   end
 
+  Suppressed = Class.new(DeliveryError)
+  Rejected = Class.new(DeliveryError)
+  Misconfigured = Class.new(DeliveryError)
+
   # An ActionMailer delivery method, so a host app keeps every existing mailer
   # untouched and changes only configuration.
   class DeliveryMethod
@@ -31,6 +32,14 @@ module Wakio
     # obviously ours if it ever leaks into a message dump.
     IDEMPOTENCY_HEADER = "X-Wakio-Idempotency-Key".freeze
 
+    # Refusals about this message itself, which no retry can fix. Every other 4xx is about the
+    # account or its configuration and sends once an operator fixes it, so an unknown code fails
+    # towards retrying rather than towards dropping mail.
+    REJECTED_STATUSES = [ 400, 413 ].freeze
+    REJECTED_CODES = %w[invalid_request idempotency_key_reused].freeze
+    LOCAL_HOSTS = %w[localhost 127.0.0.1 ::1].freeze
+    MESSAGE_BODY_LIMIT = 300
+
     def deliver!(mail)
       # Caller-supplied, never derived — and no key at all when the caller gives none.
       #
@@ -47,12 +56,7 @@ module Wakio
       # deliberate repeat", because the difference is intent rather than data.
       response = post(payload_for(mail), idempotency_key: mail[IDEMPOTENCY_HEADER]&.to_s)
       status = response.code.to_i
-      unless status.between?(200, 299)
-        message = "Wakio returned #{status}: #{response.body}"
-        raise Rejected.new(message, status: status, body: parsed(response.body)) if status.between?(400, 499) && status != 409
-
-        raise DeliveryError, message
-      end
+      raise refusal(status, response.body) unless status.between?(200, 299)
 
       # 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
@@ -129,6 +133,18 @@ module Wakio
       unreadable!(response)
     end
 
+    def refusal(status, raw)
+      body = parsed(raw)
+      code = body["error"] if body.is_a?(Hash)
+      kind =
+        if status.between?(300, 399) then Misconfigured
+        elsif !status.between?(400, 499) || status == 409 then DeliveryError
+        elsif REJECTED_STATUSES.include?(status) || REJECTED_CODES.include?(code) then Rejected
+        else Misconfigured
+        end
+      kind.new("Wakio returned #{status}: #{raw.to_s[0, MESSAGE_BODY_LIMIT]}", status: status, body: body)
+    end
+
     def parsed(body)
       JSON.parse(body.to_s)
     rescue JSON::ParserError
@@ -141,6 +157,9 @@ module Wakio
 
     def post(payload, idempotency_key:)
       uri = URI.join(settings.fetch(:host), "/v1/emails")
+      unless uri.scheme == "https" || LOCAL_HOSTS.include?(uri.hostname)
+        raise Misconfigured, "Wakio host must be https, or the API key travels in cleartext: #{settings.fetch(:host)}"
+      end
       request = Net::HTTP::Post.new(uri)
       request["Authorization"] = "Bearer #{settings.fetch(:api_key)}"
       request["Content-Type"] = "application/json"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: wakio
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.3
 platform: ruby
 authors:
 - WorkersLab LLC