active_storage_dedup 1.0.0.alpha

data/lib/active_storage_dedup/blob_deduplication.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module ActiveStorageDedup
+  module BlobDeduplication
+    extend ActiveSupport::Concern
+
+    class_methods do
+      # PRIMARY HOOK: Rails 6.1+ form uploads via Changes::CreateOne
+      # This is called by ActiveStorage::Attached::Changes::CreateOne#find_or_build_blob
+      def build_after_unfurling(io:, filename:, content_type: nil, metadata: nil,
+                                service_name: nil, identify: true,
+                                __dedup_record: nil, __dedup_attachment_name: nil, **options)
+        Rails.logger.debug "[ActiveStorageDedup] build_after_unfurling called for #{filename}"
+        Rails.logger.debug "[ActiveStorageDedup] Context: record=#{__dedup_record&.class&.name}, attachment=#{__dedup_attachment_name}"
+
+        # Build the blob using the original method to get the checksum computed
+        blob = super(
+          io: io, filename: filename, content_type: content_type,
+          metadata: metadata, service_name: service_name, identify: identify, **options
+        )
+
+        Rails.logger.debug "[ActiveStorageDedup] Blob built with checksum: #{blob.checksum&.slice(0, 12)}..."
+
+        # Check if deduplication enabled for this attachment
+        should_dedup = should_deduplicate?(__dedup_record, __dedup_attachment_name)
+        Rails.logger.debug "[ActiveStorageDedup] Deduplication enabled: #{should_dedup}"
+
+        # Check if a blob with this checksum already exists
+        if should_dedup && blob.checksum
+          actual_service_name = blob.service_name || service.name
+          Rails.logger.debug "[ActiveStorageDedup] Checking for duplicates: checksum=#{blob.checksum[0..12]}..., service=#{actual_service_name}"
+
+          if existing_blob = find_by(checksum: blob.checksum, service_name: actual_service_name)
+            Rails.logger.info "[ActiveStorageDedup] ✓ Reusing existing blob #{existing_blob.id} (checksum: #{blob.checksum[0..12]}..., service: #{actual_service_name})"
+            return existing_blob
+          end
+
+          Rails.logger.debug "[ActiveStorageDedup] No duplicate found, will use new blob"
+        end
+
+        Rails.logger.info "[ActiveStorageDedup] Creating new blob for #{filename} (checksum: #{blob.checksum&.slice(0, 12)}...)" if should_dedup
+        blob
+      end
+
+      # HOOK 2: Direct uploads to cloud storage
+      def create_before_direct_upload!(key: nil, filename:, byte_size:, checksum:,
+                                       content_type: nil, metadata: nil,
+                                       service_name: nil,
+                                       __dedup_record: nil, __dedup_attachment_name: nil, **options)
+        Rails.logger.debug "[ActiveStorageDedup] create_before_direct_upload! called for #{filename}"
+        Rails.logger.debug "[ActiveStorageDedup] Context: record=#{__dedup_record&.class&.name}, attachment=#{__dedup_attachment_name}"
+        Rails.logger.debug "[ActiveStorageDedup] Checksum provided by client: #{checksum&.slice(0, 12)}..."
+
+        # Check if deduplication enabled
+        should_dedup = should_deduplicate?(__dedup_record, __dedup_attachment_name)
+        Rails.logger.debug "[ActiveStorageDedup] Deduplication enabled: #{should_dedup}"
+
+        unless should_dedup
+          Rails.logger.debug "[ActiveStorageDedup] Deduplication disabled, creating new blob"
+          return super(
+            key: key, filename: filename, byte_size: byte_size, checksum: checksum,
+            content_type: content_type, metadata: metadata,
+            service_name: service_name, **options
+          )
+        end
+
+        # Checksum already provided by client
+        actual_service_name = service_name || service.name
+        Rails.logger.debug "[ActiveStorageDedup] Checking for duplicates: checksum=#{checksum[0..12]}..., service=#{actual_service_name}"
+
+        # Check for existing blob
+        if existing_blob = find_by(checksum: checksum, service_name: actual_service_name)
+          Rails.logger.info "[ActiveStorageDedup] ✓ Reusing existing blob #{existing_blob.id} for direct upload (checksum: #{checksum[0..12]}..., service: #{actual_service_name})"
+          return existing_blob
+        end
+
+        Rails.logger.debug "[ActiveStorageDedup] No duplicate found, creating new blob"
+        # No duplicate - create new blob
+        new_blob = super(
+          key: key, filename: filename, byte_size: byte_size, checksum: checksum,
+          content_type: content_type, metadata: metadata,
+          service_name: service_name, **options
+        )
+        Rails.logger.info "[ActiveStorageDedup] Created new blob #{new_blob.id} for direct upload #{filename}"
+        new_blob
+      end
+
+      # HOOK 3: Fallback for programmatic attach (record.file.attach(io: ...))
+      def create_after_unfurling!(key: nil, io:, filename:, content_type: nil,
+                                  metadata: nil, service_name: nil, identify: true,
+                                  __dedup_record: nil, __dedup_attachment_name: nil, **options)
+        Rails.logger.debug "[ActiveStorageDedup] create_after_unfurling! called for #{filename}"
+        Rails.logger.debug "[ActiveStorageDedup] Context: record=#{__dedup_record&.class&.name}, attachment=#{__dedup_attachment_name}"
+
+        # Check if deduplication enabled
+        should_dedup = should_deduplicate?(__dedup_record, __dedup_attachment_name)
+        Rails.logger.debug "[ActiveStorageDedup] Deduplication enabled: #{should_dedup}"
+
+        unless should_dedup
+          Rails.logger.debug "[ActiveStorageDedup] Deduplication disabled, creating new blob"
+          return super(
+            key: key, io: io, filename: filename, content_type: content_type,
+            metadata: metadata, service_name: service_name, identify: identify, **options
+          )
+        end
+
+        Rails.logger.debug "[ActiveStorageDedup] Building blob to compute checksum..."
+        # Build blob first to get checksum (but don't save yet)
+        blob = build_after_unfurling(
+          io: io, filename: filename, content_type: content_type,
+          metadata: metadata, service_name: service_name, identify: identify,
+          __dedup_record: __dedup_record, __dedup_attachment_name: __dedup_attachment_name
+        )
+
+        # If build_after_unfurling returned an existing blob, just return it
+        if blob.persisted?
+          Rails.logger.debug "[ActiveStorageDedup] build_after_unfurling returned existing blob #{blob.id}"
+          return blob
+        end
+
+        # Otherwise save the new blob
+        Rails.logger.debug "[ActiveStorageDedup] Saving new blob..."
+        blob.save!
+        Rails.logger.info "[ActiveStorageDedup] Created and saved new blob #{blob.id} for #{filename}"
+        blob
+      end
+
+      private
+
+      def should_deduplicate?(record, attachment_name)
+        # If no context, use global setting
+        return ActiveStorageDedup.enabled? unless record && attachment_name
+
+        # Check per-attachment setting
+        ActiveStorageDedup.deduplicate_enabled_for?(record, attachment_name)
+      end
+    end
+  end
+end

data/lib/active_storage_dedup/changes_extension.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module ActiveStorageDedup
+  module ChangesExtension
+    extend ActiveSupport::Concern
+
+    # Patch Changes::CreateOne#find_or_build_blob to pass context
+    def find_or_build_blob
+      Rails.logger.debug "[ActiveStorageDedup] ChangesExtension#find_or_build_blob called for #{name} attachment"
+      Rails.logger.debug "[ActiveStorageDedup] Attachable type: #{attachable.class.name}"
+
+      case attachable
+      when ActiveStorage::Blob
+        attachable
+      when ActionDispatch::Http::UploadedFile
+        ActiveStorage::Blob.build_after_unfurling(
+          io: attachable.open,
+          filename: attachable.original_filename,
+          content_type: attachable.content_type,
+          __dedup_record: record,
+          __dedup_attachment_name: name,
+          service_name: attachment_service_name
+        )
+      when Rack::Test::UploadedFile
+        ActiveStorage::Blob.build_after_unfurling(
+          io: attachable.respond_to?(:open) ? attachable.open : attachable,
+          filename: attachable.original_filename,
+          content_type: attachable.content_type,
+          __dedup_record: record,
+          __dedup_attachment_name: name,
+          service_name: attachment_service_name
+        )
+      when Hash
+        ActiveStorage::Blob.build_after_unfurling(
+          **attachable.reverse_merge(
+            record: record,
+            service_name: attachment_service_name
+          ).symbolize_keys.merge(
+            __dedup_record: record,
+            __dedup_attachment_name: name
+          )
+        )
+      when String
+        ActiveStorage::Blob.find_signed!(attachable, record: record)
+      when File
+        ActiveStorage::Blob.build_after_unfurling(
+          io: attachable,
+          filename: File.basename(attachable),
+          __dedup_record: record,
+          __dedup_attachment_name: name,
+          service_name: attachment_service_name
+        )
+      when Pathname
+        ActiveStorage::Blob.build_after_unfurling(
+          io: attachable.open,
+          filename: File.basename(attachable),
+          __dedup_record: record,
+          __dedup_attachment_name: name,
+          service_name: attachment_service_name
+        )
+      else
+        raise(
+          ArgumentError,
+          "Could not find or build blob: expected attachable, " \
+            "got #{attachable.inspect}"
+        )
+      end
+    end
+  end
+end

data/lib/active_storage_dedup/configuration.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module ActiveStorageDedup
+  class Configuration
+    # Master switch to enable/disable the entire gem (default: true)
+    # If false, no deduplication or lifecycle management will occur at all
+    attr_accessor :enabled
+
+    # Default deduplication setting for attachments when gem is enabled (default: true)
+    # This can be overridden per-attachment using the deduplicate: option
+    # Only applies when enabled = true
+    attr_accessor :deduplicate_by_default
+
+    # Automatically purge orphaned blobs when reference_count reaches 0 (default: true)
+    # Only applies when enabled = true
+    attr_accessor :auto_purge_orphans
+
+    def initialize
+      @enabled = true
+      @deduplicate_by_default = true
+      @auto_purge_orphans = true
+      Rails.logger.debug "[ActiveStorageDedup] Configuration initialized with defaults: enabled=#{@enabled}, deduplicate_by_default=#{@deduplicate_by_default}, auto_purge_orphans=#{@auto_purge_orphans}" if defined?(Rails)
+    end
+  end
+
+  class << self
+    attr_writer :configuration
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      Rails.logger.debug "[ActiveStorageDedup] Configuring ActiveStorageDedup..." if defined?(Rails)
+      yield(configuration)
+      Rails.logger.info "[ActiveStorageDedup] Configuration updated: enabled=#{configuration.enabled}, deduplicate_by_default=#{configuration.deduplicate_by_default}, auto_purge_orphans=#{configuration.auto_purge_orphans}" if defined?(Rails)
+    end
+
+    def enabled?
+      configuration.enabled
+    end
+
+    # Track which attachments have deduplicate disabled
+    def attachment_settings
+      @attachment_settings ||= {}
+    end
+
+    def register_attachment(model_name, attachment_name, deduplicate:)
+      key = "#{model_name}##{attachment_name}"
+      attachment_settings[key] = { deduplicate: deduplicate }
+      Rails.logger.debug "[ActiveStorageDedup] Registered attachment #{key} with deduplicate=#{deduplicate}" if defined?(Rails)
+    end
+
+    def deduplicate_enabled_for?(record, attachment_name)
+      # First check: Is the gem enabled at all?
+      unless configuration.enabled
+        Rails.logger.debug "[ActiveStorageDedup] Gem is disabled globally (enabled=false)" if defined?(Rails)
+        return false
+      end
+
+      key = "#{record.class.name}##{attachment_name}"
+      settings = attachment_settings[key]
+
+      # Second check: Model-level setting takes precedence over global default
+      # If model explicitly sets deduplicate: true/false, use that
+      # Otherwise, fall back to configuration.deduplicate_by_default
+      if settings.nil?
+        result = configuration.deduplicate_by_default
+        Rails.logger.debug "[ActiveStorageDedup] Deduplication check for #{key}: #{result} (using deduplicate_by_default)" if defined?(Rails)
+      else
+        result = settings[:deduplicate]
+        Rails.logger.debug "[ActiveStorageDedup] Deduplication check for #{key}: #{result} (model-level override)" if defined?(Rails)
+      end
+
+      result
+    end
+  end
+end

data/lib/active_storage_dedup/deduplication_job.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module ActiveStorageDedup
+  class DeduplicationJob < ActiveJob::Base
+    queue_as :default
+
+    # Sanity check job to find and merge duplicate blobs across the entire database
+    # Can be run on-demand or scheduled (daily/weekly) to clean up any duplicates
+    # that may have slipped through due to race conditions
+    #
+    # @example Run manually
+    #   ActiveStorageDedup::DeduplicationJob.perform_now
+    #
+    # @example Schedule with whenever gem
+    #   every 1.day, at: '2:00 am' do
+    #     runner "ActiveStorageDedup::DeduplicationJob.perform_later"
+    #   end
+    #
+    # @example Schedule with sidekiq-cron
+    #   ActiveStorageDedup::DeduplicationJob.set(cron: '0 2 * * *').perform_later
+    def perform
+      Rails.logger.info "[ActiveStorageDedup] 🔍 Starting sanity check - scanning for duplicate blobs..."
+
+      # Find all checksum+service combinations that have duplicates
+      duplicate_groups = ActiveStorage::Blob
+        .select(:checksum, :service_name)
+        .group(:checksum, :service_name)
+        .having('COUNT(*) > 1')
+        .count
+
+      if duplicate_groups.empty?
+        Rails.logger.info "[ActiveStorageDedup] ✓ No duplicate blobs found - database is clean!"
+        return
+      end
+
+      Rails.logger.info "[ActiveStorageDedup] Found #{duplicate_groups.size} group(s) with duplicates"
+
+      total_merged = 0
+      duplicate_groups.each do |(checksum, service_name), count|
+        merged = process_duplicate_group(checksum, service_name)
+        total_merged += merged
+      end
+
+      Rails.logger.info "[ActiveStorageDedup] ✓ Sanity check complete - merged #{total_merged} duplicate blob(s)"
+    end
+
+    private
+
+    def process_duplicate_group(checksum, service_name)
+      Rails.logger.debug "[ActiveStorageDedup] Processing duplicate group: checksum=#{checksum[0..12]}..., service=#{service_name}"
+
+      # Find all blobs with same checksum and service
+      duplicate_blobs = ActiveStorage::Blob
+        .where(checksum: checksum, service_name: service_name)
+        .order(:created_at)
+        .to_a
+
+      Rails.logger.debug "[ActiveStorageDedup] Found #{duplicate_blobs.size} blob(s) with checksum #{checksum[0..12]}..."
+
+      # Keep the oldest blob (first created)
+      keeper = duplicate_blobs.first
+      duplicates = duplicate_blobs[1..]
+
+      Rails.logger.info "[ActiveStorageDedup] 🔄 Merging #{duplicates.size} duplicate(s) into blob #{keeper.id} (checksum: #{checksum[0..12]}...)"
+
+      # Merge each duplicate into the keeper
+      duplicates.each do |duplicate_blob|
+        merge_duplicate(keeper, duplicate_blob)
+      end
+
+      duplicates.size
+    end
+
+    def merge_duplicate(keeper, duplicate)
+      Rails.logger.debug "[ActiveStorageDedup] Merging blob #{duplicate.id} into keeper #{keeper.id}..."
+
+      # Count attachments to move
+      attachment_count = duplicate.attachments.count
+      Rails.logger.debug "[ActiveStorageDedup] Moving #{attachment_count} attachment(s) from blob #{duplicate.id} to #{keeper.id}"
+
+      # Move all attachments from duplicate to keeper
+      duplicate.attachments.update_all(blob_id: keeper.id)
+
+      # Update counter cache on keeper
+      # Rails counter cache won't auto-update since we used update_all
+      keeper.increment!(:reference_count, attachment_count)
+      Rails.logger.debug "[ActiveStorageDedup] Updated keeper #{keeper.id} reference_count to #{keeper.reference_count}"
+
+      # Delete duplicate blob record (without purging file, since it's same as keeper)
+      duplicate.delete
+      Rails.logger.debug "[ActiveStorageDedup] Deleted duplicate blob #{duplicate.id} record"
+
+      Rails.logger.info "[ActiveStorageDedup] ✓ Merged blob #{duplicate.id} (#{attachment_count} attachment(s)) into #{keeper.id}"
+    rescue => e
+      Rails.logger.error "[ActiveStorageDedup] ✗ Error merging blob #{duplicate.id}: #{e.class.name} - #{e.message}"
+      Rails.logger.debug "[ActiveStorageDedup] Error backtrace: #{e.backtrace.first(5).join("\n")}"
+      # Don't raise - allow job to complete for other duplicates
+    end
+  end
+end

data/lib/active_storage_dedup/railtie.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module ActiveStorageDedup
+  class Railtie < ::Rails::Railtie
+    # Use after_initialize for reliable patching
+    config.after_initialize do
+      Rails.logger.info "[ActiveStorageDedup] Initializing ActiveStorageDedup gem..."
+
+      # Patch ActiveStorage::Blob with deduplication hooks
+      ActiveSupport.on_load(:active_storage_blob) do
+        Rails.logger.debug "[ActiveStorageDedup] Patching ActiveStorage::Blob with BlobDeduplication module"
+        # Prepend deduplication module to singleton class (for class methods)
+        # Using prepend allows us to use 'super' to call the original methods
+        ActiveStorage::Blob.singleton_class.prepend(
+          ActiveStorageDedup::BlobDeduplication::ClassMethods
+        )
+        Rails.logger.debug "[ActiveStorageDedup] ✓ ActiveStorage::Blob patched successfully"
+      end
+
+      # Patch ActiveStorage::Attachment with counter cache and lifecycle
+      ActiveSupport.on_load(:active_storage_attachment) do
+        Rails.logger.debug "[ActiveStorageDedup] Patching ActiveStorage::Attachment with AttachmentExtension module"
+        include ActiveStorageDedup::AttachmentExtension
+        Rails.logger.debug "[ActiveStorageDedup] ✓ ActiveStorage::Attachment patched successfully"
+      end
+
+      # Patch Changes::CreateOne to pass context (Rails 6.0+)
+      if defined?(ActiveStorage::Attached::Changes::CreateOne)
+        Rails.logger.debug "[ActiveStorageDedup] Patching ActiveStorage::Attached::Changes::CreateOne with ChangesExtension module"
+        ActiveStorage::Attached::Changes::CreateOne.prepend(
+          ActiveStorageDedup::ChangesExtension
+        )
+        Rails.logger.debug "[ActiveStorageDedup] ✓ ActiveStorage::Attached::Changes::CreateOne patched successfully"
+      else
+        Rails.logger.debug "[ActiveStorageDedup] ActiveStorage::Attached::Changes::CreateOne not found, skipping patch"
+      end
+
+      # Extend ActiveRecord with has_attached options
+      ActiveSupport.on_load(:active_record) do
+        Rails.logger.debug "[ActiveStorageDedup] Extending ActiveRecord with AttachmentOptions module"
+        extend ActiveStorageDedup::AttachmentOptions
+        Rails.logger.debug "[ActiveStorageDedup] ✓ ActiveRecord extended successfully"
+      end
+
+      Rails.logger.info "[ActiveStorageDedup] ✓ Gem initialization complete"
+    end
+  end
+end

data/lib/active_storage_dedup/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ActiveStorageDedup
+  VERSION = "1.0.0.alpha"
+end

data/lib/active_storage_dedup.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative "active_storage_dedup/version"
+require_relative "active_storage_dedup/configuration"
+require_relative "active_storage_dedup/blob_deduplication"
+require_relative "active_storage_dedup/changes_extension"
+require_relative "active_storage_dedup/attachment_options"
+require_relative "active_storage_dedup/attachment_extension"
+
+module ActiveStorageDedup
+  # Background job for deduplication
+  autoload :DeduplicationJob, "active_storage_dedup/deduplication_job"
+end
+
+# Load Railtie for Rails integration
+require_relative "active_storage_dedup/railtie" if defined?(Rails::Railtie)

data/lib/generators/active_storage_dedup/install_generator.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/migration"
+
+module ActiveStorageDedup
+  module Generators
+    class InstallGenerator < ::Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates ActiveStorageDedup initializer and migration files"
+
+      def self.next_migration_number(path)
+        next_migration_number = current_migration_number(path) + 1
+        ActiveRecord::Migration.next_migration_number(next_migration_number)
+      end
+
+      def copy_initializer
+        template "initializer.rb", "config/initializers/active_storage_dedup.rb"
+      end
+
+      def copy_migrations
+        migration_template(
+          "add_active_storage_dedup.rb.erb",
+          "db/migrate/add_active_storage_dedup.rb"
+        )
+      end
+
+      def show_readme
+        readme "README" if behavior == :invoke
+      end
+    end
+  end
+end

data/lib/generators/active_storage_dedup/templates/README

@@ -0,0 +1,44 @@
+===============================================================================
+
+ActiveStorageDedup has been installed!
+
+Next steps:
+
+1. Run the migration:
+   rails db:migrate
+
+2. Review the configuration in config/initializers/active_storage_dedup.rb
+   The initializer has been created with sensible defaults.
+
+3. Optional: Control deduplication per-attachment:
+
+   class Product < ApplicationRecord
+     has_many_attached :images                         # Uses config.deduplicate_by_default
+     has_one_attached :unique_badge, deduplicate: false # Override: don't deduplicate
+   end
+
+4. Optional: Backfill reference_count for existing blobs:
+   rails active_storage_dedup:backfill_reference_count
+
+5. Optional: Schedule sanity check job (recommended weekly/monthly):
+
+   # Run manually
+   ActiveStorageDedup::DeduplicationJob.perform_now
+
+   # Or via rake task
+   rails active_storage_dedup:cleanup_all
+
+   # Or schedule with whenever/sidekiq-cron
+   every 1.week do
+     runner "ActiveStorageDedup::DeduplicationJob.perform_later"
+   end
+
+Available rake tasks:
+  - rails active_storage_dedup:report_duplicates
+  - rails active_storage_dedup:cleanup_all
+  - rails active_storage_dedup:backfill_reference_count
+
+For more information, visit:
+https://github.com/yourusername/active_storage_dedup
+
+===============================================================================

data/lib/generators/active_storage_dedup/templates/add_active_storage_dedup.rb.erb

@@ -0,0 +1,41 @@
+class AddActiveStorageDedup < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def up
+    # Add reference_count column to active_storage_blobs
+    unless column_exists?(:active_storage_blobs, :reference_count)
+      add_column :active_storage_blobs, :reference_count, :integer, default: 0, null: false
+    end
+
+    # Add composite index on checksum and service_name for deduplication lookups
+    unless index_exists?(:active_storage_blobs, [:checksum, :service_name])
+      add_index :active_storage_blobs, [:checksum, :service_name], name: "index_active_storage_blobs_on_checksum_and_service"
+    end
+
+    # Backfill reference_count with actual attachment counts
+    # Using SQL for efficiency with large datasets
+    execute <<-SQL.squish
+      UPDATE active_storage_blobs
+      SET reference_count = (
+        SELECT COUNT(*)
+        FROM active_storage_attachments
+        WHERE active_storage_attachments.blob_id = active_storage_blobs.id
+      )
+    SQL
+
+    puts "ActiveStorageDedup migration complete!"
+    puts "  - Added reference_count column to active_storage_blobs"
+    puts "  - Added composite index on [checksum, service_name]"
+    puts "  - Backfilled reference_count for #{ActiveStorage::Blob.count} existing blobs"
+  end
+
+  def down
+    # Remove index
+    if index_exists?(:active_storage_blobs, [:checksum, :service_name])
+      remove_index :active_storage_blobs, name: "index_active_storage_blobs_on_checksum_and_service"
+    end
+
+    # Remove column
+    if column_exists?(:active_storage_blobs, :reference_count)
+      remove_column :active_storage_blobs, :reference_count
+    end
+  end
+end

data/lib/generators/active_storage_dedup/templates/initializer.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+ActiveStorageDedup.configure do |config|
+  # Master switch to enable/disable the entire gem
+  # Set to false to completely disable deduplication and lifecycle management
+  # Default: true
+  config.enabled = true
+
+  # Default deduplication setting for all attachments
+  # When enabled=true, this controls whether attachments deduplicate by default
+  # Can be overridden per-attachment using: has_many_attached :images, deduplicate: false
+  # Default: true
+  config.deduplicate_by_default = true
+
+  # Automatically purge orphaned blobs when reference_count reaches 0
+  # When enabled, blobs are automatically deleted when no attachments reference them
+  # Default: true
+  config.auto_purge_orphans = true
+end
+
+# Usage Examples:
+#
+# Opt-out pattern (deduplicate everything except specific attachments):
+#   config.enabled = true
+#   config.deduplicate_by_default = true
+#
+#   class Product < ApplicationRecord
+#     has_many_attached :images                         # Deduplicates (uses default)
+#     has_one_attached :unique_badge, deduplicate: false # Does NOT deduplicate (override)
+#   end
+#
+# Opt-in pattern (only deduplicate specific attachments):
+#   config.enabled = true
+#   config.deduplicate_by_default = false
+#
+#   class Product < ApplicationRecord
+#     has_many_attached :images, deduplicate: true      # Deduplicates (override)
+#     has_one_attached :avatar                          # Does NOT deduplicate (uses default)
+#   end
+#
+# Disable gem entirely (useful for development/testing):
+#   config.enabled = false