bouncy 0.1.0

data/lib/bouncy/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Bouncy
+  VERSION = "0.1.0"
+end

data/lib/bouncy/webhook.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Bouncy
+  class Webhook
+    BODY_LIMIT = 2 * 1024 * 1024
+
+    def call(environment)
+      return response(405) unless environment["REQUEST_METHOD"] == "POST"
+
+      # 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 response(413) if body.bytesize > BODY_LIMIT
+
+      adapter = Bouncy.adapter
+      envelope = adapter.authenticate(raw_body: body, headers: environment)
+      unless adapter.control(envelope)
+        raise MalformedMessage, "Unsupported SNS control type" unless envelope["Type"] == "Notification"
+
+        adapter.parse(envelope).each { |event| Ingestor.new.call(event) }
+      end
+      response(200)
+    rescue AuthenticationError
+      response(401)
+    rescue MalformedMessage
+      response(400)
+    rescue ProviderError, ConfigurationError, ActiveRecord::ActiveRecordError
+      response(503)
+    end
+
+    private
+
+    def response(status)
+      [status, { "content-type" => "text/plain", "cache-control" => "no-store" }, [Rack::Utils::HTTP_STATUS_CODES.fetch(status)]]
+    end
+  end
+end

data/lib/bouncy.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require "rails"
+require "active_record"
+require "active_support/all"
+require "digest"
+require "json"
+require "time"
+require_relative "bouncy/version"
+
+module Bouncy
+  class Error < StandardError; end
+  class InvalidAddress < Error; end
+  class ConfigurationError < Error; end
+  class ProviderError < Error; end
+
+  class ReleaseFailed < ProviderError
+    attr_reader :outcomes
+
+    def initialize(message, outcomes:)
+      @outcomes = outcomes
+      super(message)
+    end
+  end
+
+  class UnsafeSnapshot < ProviderError; end
+  class ReleaseConflict < Error; end
+  class AuthenticationError < Error; end
+  class MalformedMessage < Error; end
+
+  DATABASE_UNAVAILABLE = [ActiveRecord::ConnectionNotEstablished, ActiveRecord::ConnectionTimeoutError].freeze
+
+  class << self
+    def configuration = (@configuration ||= Configuration.new)
+
+    def configure
+      yield configuration
+    end
+
+    def reset_configuration!
+      @warned_unconfigured = false
+      @configuration = Configuration.new
+    end
+
+    def scope = configuration.validate!.scope
+    def adapter = configuration.adapter || Providers::Ses.new(configuration)
+
+    # 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.
+    def configured? = configuration.configured?
+
+    def unconfigured!(operation)
+      ActiveSupport::Notifications.instrument("unconfigured.bouncy", operation: operation)
+      return if @warned_unconfigured
+
+      @warned_unconfigured = true
+      Rails.logger&.warn("[bouncy] config.scope is not set, so Bouncy is inactive: no interception, no restrictions, no sync. " \
+                         "Set it in config/initializers/bouncy.rb.")
+      nil
+    end
+
+    def blocked = configured? ? Suppression.where(scope: scope).blocked : Suppression.none
+    def events = configured? ? Event.where(scope: scope) : Event.none
+    def last_sync = events.where(kind: "sync").order(created_at: :desc, id: :desc).first
+
+    def sync_fresh?(sync = last_sync)
+      !!(configured? && sync && sync.scope == scope && sync.details["complete"] && sync.created_at >= configuration.stale_after.ago)
+    end
+
+    def bootstrap!
+      sync! unless sync_fresh?
+      raise UnsafeSnapshot, "Bootstrap requires a fresh complete sync with verified sending policy; run bouncy:doctor" unless sync_fresh?
+
+      last_sync
+    end
+
+    def last_successful_sync = events.where(kind: "sync").order(created_at: :desc, id: :desc).detect { |event| event.details["complete"] }
+
+    def status(email)
+      unless configured?
+        unconfigured!("status")
+        return Status.new(nil, knowledge: :unconfigured)
+      end
+
+      Status.new(Suppression.find_by(scope: scope, email: Identity.normalize(email)))
+    rescue ActiveRecord::ActiveRecordError => e
+      raise unless database_unavailable?(e)
+
+      Status.new(nil, knowledge: :unavailable)
+    end
+
+    def blocked?(email) = status(email).blocked?
+
+    # Statuses for many addresses in one query, for list views and bulk checks. Returns a
+    # StatusSet; look addresses up by any spelling. Invalid addresses are skipped.
+    def statuses(emails)
+      keys = Array(emails).filter_map do |email|
+        Identity.normalize(email)
+      rescue InvalidAddress
+        nil
+      end.uniq
+      unless configured?
+        unconfigured!("statuses")
+        return StatusSet.new(keys.index_with { Status.new(nil, knowledge: :unconfigured) }, knowledge: :unconfigured)
+      end
+
+      rows = 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)
+
+      StatusSet.new(keys.index_with { Status.new(nil, knowledge: :unavailable) }, knowledge: :unavailable)
+    end
+
+    def sync! = Reconciler.new(adapter).call
+    def release!(email, note: nil, actor: nil, at: :provider) = Recovery.new(adapter).call(email, note: note, actor: actor, at: at)
+
+    def block!(email, note:, actor: nil)
+      raise ArgumentError, "A support note is required" if note.to_s.strip.empty?
+
+      Store.change(email) do |row|
+        was_blocked = row.blocked?
+        row.manual_blocked_at ||= Time.current
+        row.manual_note = note.to_s.truncate(1000)
+        row.summarize!
+        Store.event!("manual_block", email: row.email, details: {
+                       "note" => row.manual_note, "actor" => actor.to_s.truncate(200), "became_blocked" => !was_blocked
+                     })
+        row
+      end
+    end
+
+    def forget!(email)
+      current_scope = scope
+      key = Identity.normalize(email)
+      Suppression.transaction do
+        Event.where(scope: current_scope, email: key).delete_all
+        Suppression.where(scope: current_scope, email: key).delete_all
+      end
+    end
+
+    def unblocked
+      previous = ActiveSupport::IsolatedExecutionState[:bouncy_unblocked]
+      ActiveSupport::IsolatedExecutionState[:bouncy_unblocked] = true
+      yield
+    ensure
+      ActiveSupport::IsolatedExecutionState[:bouncy_unblocked] = previous
+    end
+
+    def notify(hook, event)
+      configuration.public_send(hook).call(event)
+    rescue StandardError => e
+      ActiveSupport::Notifications.instrument("hook_error.bouncy", hook: hook, error_class: e.class.name)
+    end
+
+    def database_unavailable?(error)
+      DATABASE_UNAVAILABLE.any? { |type| error.is_a?(type) } ||
+        %w[PG::ConnectionBad PG::UnableToSend SQLite3::CantOpenException].include?(error.cause&.class&.name)
+    end
+  end
+end
+
+require_relative "bouncy/configuration"
+require_relative "bouncy/identity"
+require_relative "bouncy/record"
+require_relative "bouncy/suppression"
+require_relative "bouncy/event"
+require_relative "bouncy/status"
+require_relative "bouncy/status_set"
+require_relative "bouncy/store"
+require_relative "bouncy/providers/base"
+require_relative "bouncy/providers/ses"
+require_relative "bouncy/providers/ses_parser"
+require_relative "bouncy/ingestor"
+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/sync_job"
+require_relative "bouncy/prune_job"
+require_relative "bouncy/engine"

data/lib/generators/bouncy/install_generator.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "rails/generators/active_record"
+
+module Bouncy
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      def self.next_migration_number(dirname)
+        ActiveRecord::Generators::Base.next_migration_number(dirname)
+      end
+
+      def create_files
+        migration_template "create_bouncy_tables.rb.erb", File.join(db_migrate_path, "create_bouncy_tables.rb")
+        destination = "config/initializers/bouncy.rb"
+        if File.exist?(File.expand_path(destination, destination_root))
+          say_status :skip, "#{destination} already exists; keeping your configuration", :yellow
+        else
+          template "initializer.rb.tt", destination
+        end
+        say "Run bin/rails db:migrate. Set your account scope, region and allowed SNS topics."
+        say "Mount Bouncy::Engine at /bouncy, then follow guides/amazon-ses.md."
+        say "Schedule Bouncy::SyncJob hourly and Bouncy::PruneJob daily using your application's scheduler."
+        say "Optional model integration: bouncy :email. No model or admin files were changed."
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
+      end
+    end
+  end
+end

data/lib/generators/bouncy/templates/create_bouncy_tables.rb.erb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+class CreateBouncyTables < ActiveRecord::Migration<%= migration_version %>
+  def change
+    primary_key_type, = primary_and_foreign_key_types
+
+    create_table :bouncy_suppressions, **primary_key_options(primary_key_type) do |t|
+      t.string :scope, null: false, limit: 191, **identity_column_options
+      t.string :email, null: false, limit: 254, **identity_column_options
+      t.string :provider, null: false
+      t.string :reason
+      t.datetime :blocked_at
+      t.datetime :manual_blocked_at
+      t.text :manual_note
+      t.public_send(json_column_type, :provider_entries, **json_column_options([]))
+      t.datetime :provider_blocked_at
+      t.string :provider_reason
+      t.datetime :event_blocked_at
+      t.string :event_reason
+      t.datetime :last_event_at
+      t.datetime :provider_checked_at
+      t.datetime :released_before
+      t.integer :soft_bounce_count, null: false, default: 0
+      t.datetime :last_soft_bounce_at
+      t.datetime :soft_blocked_until
+      t.integer :lock_version, null: false, default: 0
+      t.public_send(json_column_type, :details, **json_column_options({}))
+      t.timestamps
+    end
+    add_index :bouncy_suppressions, [ :scope, :email ], unique: true
+    add_index :bouncy_suppressions, [ :scope, :blocked_at ]
+    add_index :bouncy_suppressions, [ :scope, :reason ]
+
+    create_table :bouncy_events, **primary_key_options(primary_key_type) do |t|
+      t.string :scope, null: false, limit: 191, **identity_column_options
+      t.string :email, limit: 254, **identity_column_options
+      t.string :kind, null: false
+      t.string :source, null: false
+      t.string :provider
+      t.string :provider_event_id
+      t.string :message_id
+      t.string :dedupe_key, limit: 64
+      t.datetime :occurred_at, null: false
+      t.datetime :received_at, null: false
+      t.string :provider_reason
+      t.string :status_code
+      t.text :diagnostic
+      t.public_send(json_column_type, :details, **json_column_options({}))
+      t.datetime :created_at, null: false
+    end
+    add_index :bouncy_events, :dedupe_key, unique: true
+    add_index :bouncy_events, [ :scope, :email, :occurred_at ]
+    add_index :bouncy_events, [ :scope, :kind, :created_at ]
+    add_index :bouncy_events, :created_at
+  end
+
+  private
+
+  # Shared house convention: resolve the host key setting when migrating,
+  # not when generating, so one checked-in migration works in every environment.
+  def primary_and_foreign_key_types
+    config = Rails.configuration.generators
+    setting = config.options.fetch(config.orm, {})[:primary_key_type]
+    [ setting || :primary_key, setting || :bigint ]
+  end
+
+  def primary_key_options(type)
+    # PostgreSQL generates native UUIDs. Other adapters store application-generated
+    # UUID strings; Bouncy::Record supplies them without adapter queries at boot.
+    return { id: :string, limit: 36 } if type.to_s == "uuid" && !postgresql?
+
+    { id: type }
+  end
+
+  def json_column_type
+    postgresql? ? :jsonb : :json
+  end
+
+  def json_column_options(default)
+    # Avoid literal JSON defaults on MySQL. Models supply fresh Ruby defaults.
+    # This also works on versions that require an expression for JSON defaults.
+    mysql? ? { null: false } : { null: false, default: default }
+  end
+
+  def identity_column_options
+    # A case/accent-insensitive MySQL collation would broaden our canonical key.
+    mysql? ? { collation: "utf8mb4_bin" } : {}
+  end
+
+  def postgresql?
+    connection.adapter_name.downcase.include?("postgres")
+  end
+
+  def mysql?
+    connection.adapter_name.downcase.match?(/mysql|trilogy/)
+  end
+end

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

@@ -0,0 +1,23 @@
+Bouncy.configure do |config|
+  config.provider = :ses
+  # Leave the scope blank and Bouncy stays inactive: mail is delivered untouched, every address
+  # reads as unrestricted, and a warning is logged once. Set it to start observing.
+  config.scope = ENV["BOUNCY_SCOPE"] # ses:123456789012:us-east-1:account
+  config.ses.region = ENV["AWS_REGION"]
+  config.ses.topic_arns = ENV.fetch("BOUNCY_SNS_TOPIC_ARNS", "").split(",").map(&:strip)
+
+  # Imported provider restrictions are enforced only after `bin/rails bouncy:doctor` reports
+  # policy_verified: true. List every identity and configuration set you send through, then
+  # confirm the lists are complete. Until then sync mirrors the list without blocking anything.
+  config.ses.identities = []
+  config.ses.configuration_sets = []
+  config.ses.all_sending_paths_listed = false
+
+  # Soft bounces are temporary refusals, so they are recorded without blocking. Set a threshold
+  # from 1 to 50 to hold an address after repeated SES MailboxFull events inside the window.
+  # config.soft_bounce_threshold = 3
+  # config.soft_bounce_window = 30.days
+  # config.soft_bounce_block_for = 30.days
+
+  config.interception = :log # Review a complete sync before enabling :drop.
+end

data/lib/tasks/bouncy.rake

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+namespace :bouncy do
+  desc "Require a fresh verified mirror before starting a host's mail workers"
+  task bootstrap: :environment do
+    puts JSON.pretty_generate(Bouncy.bootstrap!.details)
+  end
+
+  desc "Import and reconcile the configured provider scope"
+  task sync: :environment do
+    puts JSON.pretty_generate(Bouncy.sync!.details)
+  end
+
+  desc "Check provider scope and local freshness without changing AWS"
+  task doctor: :environment do
+    checks = Bouncy.adapter.doctor
+    checks["last_attempt"] = Bouncy.last_sync&.created_at
+    checks["last_success"] = Bouncy.last_successful_sync&.created_at
+    puts JSON.pretty_generate(checks)
+  end
+
+  namespace :ses do
+    desc "Print a read-only SES setup plan; never provisions resources"
+    task setup: :environment do
+      raise Bouncy::ConfigurationError, "Write mode is not supported; omit APPLY" if ENV.key?("APPLY")
+
+      puts JSON.pretty_generate(Bouncy.adapter.doctor)
+      puts "1. Deploy POST <engine mount>/webhooks/ses with the exact topic allowlist (the mount is usually /bouncy)."
+      puts "2. Review the SNS publisher policy: SES service principal plus SourceAccount and SourceArn conditions."
+      puts "3. Subscribe that HTTPS URL; preserve existing feedback destinations. Disable raw message delivery."
+      puts "4. Confirm subscription status in SNS and test receiver delivery/retries."
+      puts "5. Run bouncy:sync; schedule Bouncy::SyncJob hourly and Bouncy::PruneJob daily."
+      puts "6. Review imported restrictions and perform a staging delivery test before enabling :drop."
+    end
+  end
+end

metadata

@@ -0,0 +1,126 @@
+--- !ruby/object:Gem::Specification
+name: bouncy
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- rameerez
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.2.3.2
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.2.3.2
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+description: Know when your app's emails bounce. Mirror provider restrictions, query
+  email status locally, and recover addresses with an audited, provider-aware release.
+email:
+- rubygems@rameerez.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- config/routes.rb
+- guides/admin.md
+- guides/amazon-ses.md
+- guides/bounce-handling.md
+- guides/compatibility.md
+- guides/delivery.md
+- guides/migrating.md
+- guides/privacy.md
+- guides/recovery.md
+- guides/troubleshooting.md
+- lib/bouncy.rb
+- lib/bouncy/configuration.rb
+- lib/bouncy/engine.rb
+- lib/bouncy/event.rb
+- lib/bouncy/identity.rb
+- lib/bouncy/ingestor.rb
+- lib/bouncy/interceptor.rb
+- lib/bouncy/model.rb
+- lib/bouncy/providers/base.rb
+- lib/bouncy/providers/ses.rb
+- lib/bouncy/providers/ses_parser.rb
+- lib/bouncy/providers/sns_verifier.rb
+- lib/bouncy/prune_job.rb
+- lib/bouncy/reconciler.rb
+- lib/bouncy/record.rb
+- lib/bouncy/recovery.rb
+- lib/bouncy/scope_lock.rb
+- lib/bouncy/status.rb
+- lib/bouncy/status_set.rb
+- lib/bouncy/store.rb
+- lib/bouncy/suppression.rb
+- lib/bouncy/sync_job.rb
+- lib/bouncy/version.rb
+- lib/bouncy/webhook.rb
+- lib/generators/bouncy/install_generator.rb
+- lib/generators/bouncy/templates/create_bouncy_tables.rb.erb
+- lib/generators/bouncy/templates/initializer.rb.tt
+- lib/tasks/bouncy.rake
+homepage: https://github.com/rameerez/bouncy
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  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'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Email bounce handling and suppression management for Rails.
+test_files: []