wakio 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0b10c47e80d5a8cdb7eb94e86babdcf24674b8b0563313a4b12459cbcc2ddf74
-  data.tar.gz: 8053fbb8ebe24f105513e04e8856ea18614b86ab25b2b34e89ad8fdadabe2462
+  metadata.gz: 701b8f414dc39686af35c768fd62f176365f50e8e10cf5fc8d47fe8473fad702
+  data.tar.gz: ab412723cc02b1ce9e04c9fdcb51b0282f467d1f43dacbd415a4df4532111406
 SHA512:
-  metadata.gz: d45c860e93f1c69bb3620f11dbb68179c3142bb63a8bb418e39b1c016c14d6bdba14971e3f5f3582a054dbb514f5b03c96dd8b22eeef77248058f99e8ed8ff5f
-  data.tar.gz: 8c6f7c5cb040922d14a6b2828775bdfe6ad103cf7c1bdf07123b2722e81bd78f281caae194a803fe0852d2b3bee3ed3fdd182124918c103a23447828f1630ddc
+  metadata.gz: 1e5191bf7700df69a86c119fd2dadbc4e8ef26e5530b68dd60727057f6f9c08e6e6e1928040001986585dd9ebf4ea9f9032da6561687330dff4f887c654aea85
+  data.tar.gz: 20c01bf3d406b7431632aac6367ecb227fc735fef780cba4f4c760db1df898fbc34b5def97e0c46f96ed1742b9e5c575666b180845300892e8fe423566cb16ea

data/README.md

@@ -24,7 +24,23 @@ 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.** 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

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,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.
       #
@@ -47,12 +54,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 +131,17 @@ 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

metadata

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