wakio 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2b058707e5d5a45ba09f1ab08a918b13cd24421ff6090c957ac42e8f7ef2ddb3
-  data.tar.gz: 90c415eb9823dfca80567242d5402d3d9a61cc3636d6b8e12ab768463c1851c0
+  metadata.gz: 701b8f414dc39686af35c768fd62f176365f50e8e10cf5fc8d47fe8473fad702
+  data.tar.gz: ab412723cc02b1ce9e04c9fdcb51b0282f467d1f43dacbd415a4df4532111406
 SHA512:
-  metadata.gz: c011065c01a89cdffab9684e0aa88a175f657e601246c0780aa193f85b2cf900b541b1709d20e454f011b7f5876243e11cb55c29354c961e3ca628abca5baa22
-  data.tar.gz: f53a850d624b30ccfb86a0525b88de4946d1534bd7cb2d053f983d1faf66cd70256045d4d42d4f7944272cce1479606e57235120263b04d1ecdba273b0cf1bc8
+  metadata.gz: 1e5191bf7700df69a86c119fd2dadbc4e8ef26e5530b68dd60727057f6f9c08e6e6e1928040001986585dd9ebf4ea9f9032da6561687330dff4f887c654aea85
+  data.tar.gz: 20c01bf3d406b7431632aac6367ecb227fc735fef780cba4f4c760db1df898fbc34b5def97e0c46f96ed1742b9e5c575666b180845300892e8fe423566cb16ea

data/README.md

@@ -14,6 +14,8 @@ 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.
+
 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.
@@ -22,6 +24,24 @@ 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.
 
+**Refusals split by whether a retry can ever send the message.** Every error is a `Wakio::DeliveryError` carrying `status`, `code` (the response's `error`, such as `"invalid_request"`) and the parsed `body`.
+
+- `Wakio::Rejected`: this message can never be sent. `400`, `413`, `422 invalid_request` and `422 idempotency_key_reused`. 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`, and any 4xx this gem does not know. Let it raise so the job retries and your error tracker shows it.
+- A plain `Wakio::DeliveryError`: `409 request_in_flight` and every 5xx. Let it retry.
+
+```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
 whole request is refused past it rather than truncated. The number mirrors SES's own

data/lib/wakio/delivery_method.rb

@@ -3,8 +3,20 @@ require "net/http"
 require "uri"
 
 module Wakio
-  DeliveryError = Class.new(StandardError)
+  class DeliveryError < StandardError
+    attr_reader :status, :code, :body
+
+    def initialize(message = nil, status: nil, body: nil)
+      super(message)
+      @status = status
+      @body = body
+      @code = body["error"] if body.is_a?(Hash)
+    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.
@@ -20,6 +32,12 @@ 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
+
     def deliver!(mail)
       # Caller-supplied, never derived — and no key at all when the caller gives none.
       #
@@ -35,9 +53,8 @@ module Wakio
       # 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
+      status = response.code.to_i
+      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
@@ -114,6 +131,23 @@ module Wakio
       unreadable!(response)
     end
 
+    def refusal(status, raw)
+      body = parsed(raw)
+      code = body["error"] if body.is_a?(Hash)
+      kind =
+        if !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}", status: status, body: body)
+    end
+
+    def parsed(body)
+      JSON.parse(body.to_s)
+    rescue JSON::ParserError
+      nil
+    end
+
     def unreadable!(response)
       raise DeliveryError, "Wakio returned an unreadable body: #{response.body}"
     end
@@ -128,7 +162,8 @@ module Wakio
       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|
+      Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https",
+                      open_timeout: settings.fetch(:open_timeout, 5), read_timeout: settings.fetch(:read_timeout, 10)) do |http|
         http.request(request)
       end
     end

metadata

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