bouncy 0.1.0 → 0.2.1

data/lib/bouncy/webhook.rb

@@ -3,17 +3,24 @@
 module Bouncy
   class Webhook
     BODY_LIMIT = 2 * 1024 * 1024
+    METHODS = %w[GET HEAD PUT PATCH DELETE OPTIONS TRACE CONNECT].freeze
+    INVALID = "<invalid>"
+    TOPIC_ARN = /\Aarn:aws[a-z-]*:sns:[a-z]{2}(?:-[a-z]+)+-\d+:\d{12}:[A-Za-z0-9_-]{1,256}\z/
 
     def call(environment)
-      return response(405) unless environment["REQUEST_METHOD"] == "POST"
+      method = environment["REQUEST_METHOD"]
+      unless method == "POST"
+        shown = METHODS.include?(method) ? method : INVALID
+        return refuse(405, "method #{shown} is not POST")
+      end
 
       # An unconfigured receiver answers 503 so the provider retries later instead of
       # treating the endpoint as broken or, worse, as having accepted the notification.
       Bouncy.configuration.validate!
       body = environment.fetch("rack.input").read(BODY_LIMIT + 1).to_s
-      return response(400) if body.empty?
+      return refuse(400, "empty body") if body.empty?
 
-      return response(413) if body.bytesize > BODY_LIMIT
+      return refuse(413, "body over #{BODY_LIMIT} bytes") if body.bytesize > BODY_LIMIT
 
       adapter = Bouncy.adapter
       envelope = adapter.authenticate(raw_body: body, headers: environment)
@@ -21,18 +28,62 @@ module Bouncy
         raise MalformedMessage, "Unsupported SNS control type" unless envelope["Type"] == "Notification"
 
         adapter.parse(envelope).each { |event| Ingestor.new.call(event) }
+        return response(503) unless notified?(adapter, envelope)
       end
       response(200)
-    rescue AuthenticationError
-      response(401)
-    rescue MalformedMessage
-      response(400)
-    rescue ProviderError, ConfigurationError, ActiveRecord::ActiveRecordError
-      response(503)
+    rescue AuthenticationError => e
+      refuse(401, e.message, body)
+    rescue MalformedMessage => e
+      refuse(400, e.message, body)
+    rescue ProviderError, ConfigurationError => e
+      refuse(503, e.message, body)
+    rescue ActiveRecord::ActiveRecordError => e
+      # A database message can quote a statement and its values, so only the class is logged.
+      refuse(503, e.class.name, body)
     end
 
     private
 
+    # One warning per refused message: how a dead subscription is found in production. It names
+    # the reason and where the message claims to come from. The message is not authenticated, so
+    # a topic is logged only when it has the strict SNS ARN syntax and a SubscribeURL host only
+    # when it passes the SNS host check; anything else is written as <invalid>. No raw field of
+    # the body is ever copied into the log.
+    def refuse(status, reason, body = nil)
+      Rails.logger&.warn("[bouncy] refused an SNS message (#{status}): #{reason}#{origin(body)}")
+      response(status)
+    end
+
+    def origin(body)
+      envelope = JSON.parse(body.to_s, max_nesting: 30)
+      return "" unless envelope.is_a?(Hash)
+
+      parts = []
+      topic = envelope["TopicArn"] if envelope["TopicArn"].is_a?(String) && envelope["TopicArn"].match?(TOPIC_ARN)
+      parts << "topic #{topic || INVALID}" if envelope.key?("TopicArn")
+      if envelope["Type"] == "SubscriptionConfirmation" && envelope.key?("SubscribeURL")
+        uri = Providers::Ses.subscribe_uri(envelope, Bouncy.configuration.ses.region) if topic
+        parts << "SubscribeURL host #{uri&.host || INVALID}"
+      end
+      parts.map { |part| "; #{part}" }.join
+    rescue JSON::ParserError
+      ""
+    end
+
+    # config.on_notification runs after the state committed, outside Bouncy's locks, and before
+    # the answer. A failure answers 503, so SNS delivers the notification again; the repeat
+    # deduplicates and calls the hook again.
+    def notified?(adapter, envelope)
+      return true unless adapter.respond_to?(:notification)
+
+      Bouncy.configuration.on_notification.call(adapter.notification(envelope))
+      true
+    rescue StandardError => e
+      ActiveSupport::Notifications.instrument("hook_error.bouncy", hook: :on_notification, error_class: e.class.name)
+      Rails.logger&.error("[bouncy] config.on_notification raised #{e.class.name}; answering 503 so SNS retries")
+      false
+    end
+
     def response(status)
       [status, { "content-type" => "text/plain", "cache-control" => "no-store" }, [Rack::Utils::HTTP_STATUS_CODES.fetch(status)]]
     end

data/lib/bouncy.rb

@@ -48,7 +48,7 @@ module Bouncy
     # True when config.scope is set. An unconfigured Bouncy is inactive: it intercepts nothing,
     # reports no restrictions and returns empty relations, so a host can install the gem before
     # its environment variables exist without breaking mail delivery. Explicit operations
-    # (sync!, block!, release!, forget!) still raise ConfigurationError.
+    # (sync!, block!, import!, release!, forget!) still raise ConfigurationError.
     def configured? = configuration.configured?
 
     def unconfigured!(operation)
@@ -84,7 +84,7 @@ module Bouncy
         return Status.new(nil, knowledge: :unconfigured)
       end
 
-      Status.new(Suppression.find_by(scope: scope, email: Identity.normalize(email)))
+      Status.new(current_state(Suppression).find_by(scope: scope, email: Identity.normalize(email)))
     rescue ActiveRecord::ActiveRecordError => e
       raise unless database_unavailable?(e)
 
@@ -106,7 +106,7 @@ module Bouncy
         return StatusSet.new(keys.index_with { Status.new(nil, knowledge: :unconfigured) }, knowledge: :unconfigured)
       end
 
-      rows = Suppression.where(scope: scope, email: keys).index_by(&:email)
+      rows = current_state(Suppression).where(scope: scope, email: keys).index_by(&:email)
       StatusSet.new(keys.to_h { |key| [key, Status.new(rows[key])] })
     rescue ActiveRecord::ActiveRecordError => e
       raise unless database_unavailable?(e)
@@ -132,6 +132,14 @@ module Bouncy
       end
     end
 
+    # Records a block that another system recorded at the time at, for an app that moves its own
+    # suppression table to Bouncy. reason is :hard_bounce, :complaint or :manual. A bounce or a
+    # complaint is the same evidence as a webhook block; a manual block is a manual hold. The
+    # time can be of any age. The import calls no hook, writes nothing when it repeats, never
+    # weakens a block in force, and changes nothing when a release came at or after its time.
+    # Returns the suppression row. Does not call the provider.
+    def import!(email, reason:, at:, note: nil, actor: nil) = Importer.new.call(email, reason: reason, at: at, note: note, actor: actor)
+
     def forget!(email)
       current_scope = scope
       key = Identity.normalize(email)
@@ -141,6 +149,35 @@ module Bouncy
       end
     end
 
+    # Holds the address while the block runs, so no new block for it can commit between the
+    # app's own check and its send. Inside a transaction the hold lasts until the transaction
+    # ends. Returns the block's value. Unconfigured, it only runs the block. The check needs the
+    # latest committed state: see current_state. Inside a PostgreSQL REPEATABLE READ or
+    # SERIALIZABLE transaction it raises; hold around such a transaction, and around SQLite ones.
+    #
+    #   Bouncy.hold(order.email) do
+    #     ReceiptMailer.with(order:).receipt.deliver_now unless Bouncy.blocked?(order.email)
+    #   end
+    def hold(email, &)
+      raise ArgumentError, "Bouncy.hold needs a block" unless block_given?
+
+      unless configured?
+        unconfigured!("hold")
+        return yield
+      end
+
+      AddressLock.hold(email, &)
+    end
+
+    # Inside Bouncy.hold, MySQL reads restrictions with a locking read, which sees the latest
+    # committed state: a REPEATABLE READ snapshot from before the hold cannot hide a newer block
+    # or release. PostgreSQL at READ COMMITTED reads the latest state with every statement.
+    def current_state(relation)
+      return relation unless AddressLock.holding? && Record.connection_pool.with_connection(&:adapter_name).match?(/Mysql|Trilogy/i)
+
+      relation.lock("LOCK IN SHARE MODE")
+    end
+
     def unblocked
       previous = ActiveSupport::IsolatedExecutionState[:bouncy_unblocked]
       ActiveSupport::IsolatedExecutionState[:bouncy_unblocked] = true
@@ -169,17 +206,21 @@ require_relative "bouncy/suppression"
 require_relative "bouncy/event"
 require_relative "bouncy/status"
 require_relative "bouncy/status_set"
+require_relative "bouncy/address_lock"
 require_relative "bouncy/store"
 require_relative "bouncy/providers/base"
 require_relative "bouncy/providers/ses"
 require_relative "bouncy/providers/ses_parser"
+require_relative "bouncy/notification"
 require_relative "bouncy/ingestor"
+require_relative "bouncy/importer"
 require_relative "bouncy/recovery"
 require_relative "bouncy/scope_lock"
 require_relative "bouncy/reconciler"
 require_relative "bouncy/model"
 require_relative "bouncy/interceptor"
 require_relative "bouncy/webhook"
+require_relative "bouncy/body_limit"
 require_relative "bouncy/sync_job"
 require_relative "bouncy/prune_job"
 require_relative "bouncy/engine"

data/lib/generators/bouncy/templates/initializer.rb.tt

@@ -19,5 +19,19 @@ Bouncy.configure do |config|
   # config.soft_bounce_window = 30.days
   # config.soft_bounce_block_for = 30.days
 
+  # Stamp one SES configuration set on every message, so SES publishes its events to the topic.
+  # config.ses.configuration_set = "transactional"
+
+  # Confirm the SNS subscription by visiting its signed SubscribeURL instead of calling
+  # sns:ConfirmSubscription.
+  # config.ses.subscription_confirmation = :subscribe_url
+
+  # An app that runs no sync job enforces its webhook blocks alone. webhook_blocking then
+  # defaults to :strict: every Permanent bounce and every complained recipient blocks.
+  # config.require_fresh_sync = false
+
+  # Every SES notification, after Bouncy recorded it. A raise makes SNS deliver it again.
+  # config.on_notification = ->(notification) { }
+
   config.interception = :log # Review a complete sync before enabling :drop.
 end

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bouncy
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - rameerez
+autorequire:
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-10-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -61,23 +62,31 @@ files:
 - LICENSE.txt
 - README.md
 - config/routes.rb
+- guides/README.md
 - guides/admin.md
 - guides/amazon-ses.md
+- guides/api.md
 - guides/bounce-handling.md
 - guides/compatibility.md
+- guides/configuration.md
 - guides/delivery.md
 - guides/migrating.md
+- guides/operations.md
 - guides/privacy.md
 - guides/recovery.md
 - guides/troubleshooting.md
 - lib/bouncy.rb
+- lib/bouncy/address_lock.rb
+- lib/bouncy/body_limit.rb
 - lib/bouncy/configuration.rb
 - lib/bouncy/engine.rb
 - lib/bouncy/event.rb
 - lib/bouncy/identity.rb
+- lib/bouncy/importer.rb
 - lib/bouncy/ingestor.rb
 - lib/bouncy/interceptor.rb
 - lib/bouncy/model.rb
+- lib/bouncy/notification.rb
 - lib/bouncy/providers/base.rb
 - lib/bouncy/providers/ses.rb
 - lib/bouncy/providers/ses_parser.rb
@@ -106,6 +115,7 @@ metadata:
   source_code_uri: https://github.com/rameerez/bouncy/tree/main
   changelog_uri: https://github.com/rameerez/bouncy/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -120,7 +130,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
 summary: Email bounce handling and suppression management for Rails.
 test_files: []