active_storage-async_variants 0.1.0 → 0.3.1

data/lib/active_storage/async_variants/preview_extension.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module ActiveStorage
+  module AsyncVariants
+    module PreviewExtension
+      # Enqueue (or no-op if already done) the same ProcessJob the
+      # VariantWithRecord path uses, so Preview-side and VariantWithRecord-side
+      # processing converge on a single record-and-job machinery rather than
+      # the gem's earlier two-path design (one writing to preview_image's
+      # variant_records, one to the original blob's).
+      def processed
+        if async_preview?
+          enqueue_async_preview unless preview_variant_processed?
+          self
+        else
+          super
+        end
+      end
+
+      def processed?
+        async_preview? ? preview_variant_processed? : super
+      end
+
+      def url(...)
+        if async_preview?
+          preview_variant_processed? ? find_preview_variant_record.image.url(...) : fallback_preview_url(...)
+        else
+          super
+        end
+      end
+
+      def key
+        if async_preview?
+          raise ActiveStorage::Preview::UnprocessedError unless preview_variant_processed?
+          find_preview_variant_record.image.blob.key
+        else
+          super
+        end
+      end
+
+      def async_state
+        return nil unless async_preview?
+        find_preview_variant_record&.state || "pending"
+      end
+
+      private
+
+      def async_preview?
+        resolved_async_options[:transformer].present?
+      end
+
+      # Variations rebuilt from the redirect URL only carry transformations --
+      # :transformer / :processing / :failed are stripped at Variation#initialize
+      # and not embedded in the URL key. Recover them via the digest-keyed
+      # registry that VariationExtension warms on every view-side variant call.
+      def resolved_async_options
+        @resolved_async_options ||=
+          variation.async_options.presence ||
+          ActiveStorage::AsyncVariants::Registry[variation.digest] ||
+          {}
+      end
+
+      def preview_variant_processed?
+        find_preview_variant_record&.state == "processed"
+      end
+
+      # ProcessJob stores variant_records on the source blob (i.e. @variant.blob,
+      # which for a named variant declared on a previewable attachment is the
+      # original blob -- not preview_image.blob). Read from the same place.
+      def find_preview_variant_record
+        blob.variant_records.find_by(variation_digest: variation.digest)
+      end
+
+      # Delegate to the named-variant VariantWithRecord so we go through the
+      # exact same enqueue_processing + ProcessJob machinery as direct
+      # variant calls. Skips silently if no matching named variant exists,
+      # which can happen for raw transformations that don't correspond to
+      # any declared async variant. Also skipped on non-bucket services,
+      # where the gem defers to vanilla ActiveStorage and dispatching here
+      # would synchronously transform via vips (broken for video blobs).
+      def enqueue_async_preview
+        return unless blob.bucket_backed?
+        target = variation.transformations.to_json
+        blob.attachments.each do |attachment|
+          attachment.send(:named_variants).each do |name, _|
+            candidate = attachment.variant(name.to_sym)
+            next unless candidate.variation.transformations.to_json == target
+            next unless candidate.variation.async_options[:processing].present?
+            candidate.processed
+            return
+          end
+        end
+      end
+
+      def fallback_preview_url(...)
+        case active_fallback
+        when :original then blob.url(...)
+        when :blank then nil
+        when Proc then active_fallback.call(blob)
+        when String then active_fallback
+        end
+      end
+
+      def active_fallback
+        if failed?
+          resolved_async_options.fetch(:failed) { resolved_async_options[:processing] }
+        else
+          resolved_async_options[:processing]
+        end
+      end
+
+      def failed?
+        find_preview_variant_record&.state == "failed"
+      end
+    end
+  end
+end

data/lib/active_storage/async_variants/process_job.rb

@@ -3,6 +3,10 @@
 module ActiveStorage
   module AsyncVariants
     class ProcessJob < ActiveJob::Base
+      retry_on StandardError, wait: :polynomially_longer, attempts: 3 do |job, error|
+        job.logger.error "AsyncVariants: permanently failed: #{error.message}"
+      end
+
       def perform(record, attachment_name, variant_name)
         attachment = record.public_send(attachment_name)
         @variant = attachment.variant(variant_name.to_sym)
@@ -27,15 +31,10 @@ module ActiveStorage
       rescue => e
         @variant_record&.update!(
           state: "failed",
-          error: e.message,
+          error: e.message.to_s.truncate(16_000),
           attempts: (@variant_record&.attempts || 0) + 1,
         )
-        max_retries = @async_options&.fetch(:max_retries, 3) || 3
-        if @variant_record.nil? || @variant_record.attempts < max_retries
-          raise
-        else
-          logger.error "AsyncVariants: permanently failed after #{@variant_record.attempts} attempts: #{e.message}"
-        end
+        raise
       end
 
       private

data/lib/active_storage/async_variants/reflection_extension.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module ActiveStorage
+  module AsyncVariants
+    # Eagerly warm the digest-keyed Registry when a named variant is declared
+    # via has_X_attached's block:
+    #
+    #   has_one_attached :avatar do |attachable|
+    #     attachable.variant :thumb, resize_to_limit: [150, 150], format: "webp",
+    #       transformer: Crucible, processing: "/spinner.svg"
+    #   end
+    #
+    # Without this, the Registry only warms when view-side code calls
+    # `attachment.variant(:thumb)` -- so a Puma worker that has never rendered
+    # a view for the variant misses on URL-reconstructed lookups.
+    #
+    # Caveat: registration uses the declared transformations. Rails applies a
+    # blob-dependent default `format:` at runtime via default_to. Variants that
+    # specify `format:` explicitly register the same digest the URL carries
+    # (cold-resolvable). Variants that rely on the format default still warm
+    # lazily on first view-side call against a blob of that content type.
+    module ReflectionExtension
+      def variant(name, transformations)
+        super
+        return unless transformations.is_a?(Hash)
+        # Mirror Blob#variant at runtime: wrap and default_to. The default_to
+        # call reorders hash keys (default key first) so the registered digest
+        # matches the URL-side digest for variants that declare an explicit
+        # `format:`. Variants without an explicit `format:` still warm lazily
+        # on first view-side call against a blob of that content type.
+        ActiveStorage::Variation.wrap(transformations).default_to(format: :png)
+      end
+    end
+  end
+end

data/lib/active_storage/async_variants/registry.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "monitor"
+
+module ActiveStorage
+  module AsyncVariants
+    # Process-wide lookup of async_options keyed by Variation#digest.
+    #
+    # Populated lazily by VariationExtension#initialize whenever a Variation is
+    # constructed with :transformer in its async_options -- which happens on
+    # every view-side `attachment.variant(:name)` call. The redirect controller
+    # then resolves async_options by digest without scanning blob.attachments
+    # for a transformations-match.
+    #
+    # Cold-worker behavior: if a worker receives a redirect-URL request before
+    # any view-side call has registered the variant's digest, the lookup misses
+    # and resolution falls through to standard Rails (no leak, no spinner).
+    # Self-warms on subsequent view requests.
+    class Registry
+      MONITOR = Monitor.new
+      STORE = {}
+
+      class << self
+        def register(digest, async_options)
+          MONITOR.synchronize { STORE[digest] = async_options }
+        end
+
+        def [](digest)
+          MONITOR.synchronize { STORE[digest] }
+        end
+
+        def clear
+          MONITOR.synchronize { STORE.clear }
+        end
+      end
+    end
+  end
+end

data/lib/active_storage/async_variants/representations_redirect_controller_extension.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module ActiveStorage
+  module AsyncVariants
+    module RepresentationsRedirectControllerExtension
+      ASYNC_HEADER = "X-Async-Variant-State"
+      INTERCEPT_STATES = %w[pending processing failed].freeze
+
+      def show
+        state = @representation.async_state
+        if INTERCEPT_STATES.include?(state)
+          fallback = @representation.url(disposition: params[:disposition])
+          if fallback.is_a?(String) && fallback.start_with?("/")
+            path = Rails.public_path.join(fallback.delete_prefix("/"))
+            if File.exist?(path)
+              response.set_header(ASYNC_HEADER, state)
+              response.set_header("Cache-Control", "no-store, private")
+              return send_file path, disposition: "inline"
+            end
+          end
+        end
+        super
+      end
+    end
+  end
+end

data/lib/active_storage/async_variants/variant_record_extension.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module ActiveStorage
+  module AsyncVariants
+    module VariantRecordExtension
+      extend ActiveSupport::Concern
+
+      included do
+        after_update_commit :touch_attached_records, if: :reached_terminal_state?
+      end
+
+      private
+
+      # processed and failed are terminal states: cache fragments built when
+      # state was pending/processing need to be invalidated so the next
+      # render sees the new state (and serves the failed: fallback URL,
+      # swaps src to the direct CDN URL, etc.).
+      def reached_terminal_state?
+        saved_change_to_state? && %w[processed failed].include?(state)
+      end
+
+      def touch_attached_records
+        blob.attachments.includes(:record).each do |attachment|
+          attachment.record&.touch
+        end
+      end
+    end
+  end
+end

data/lib/active_storage/async_variants/variant_with_record_extension.rb

@@ -3,16 +3,36 @@
 module ActiveStorage
   module AsyncVariants
     module VariantWithRecordExtension
-      def url(...)
-        if processed?
+      def processed
+        if blob.bucket_backed?
+          enqueue_processing unless processed? || processing?
+          self
+        else
           super
+        end
+      end
+
+      def url(...)
+        if blob.bucket_backed? && !processed?
+          fallback = active_fallback
+          case fallback
+          when :original then blob.url(...)
+          when :blank then nil
+          when Proc then fallback.call(blob)
+          when String then fallback
+          else super
+          end
         else
-          fallback_url(...)
+          super
         end
       end
 
-      def ready?
-        async_record&.state == "processed"
+      def processed?
+        if blob.bucket_backed?
+          async_record&.state == "processed"
+        else
+          super
+        end
       end
 
       def processing?
@@ -31,29 +51,68 @@ module ActiveStorage
         async_record&.error
       end
 
+      def async_state
+        return nil unless blob.bucket_backed?
+        async_record&.state || "pending"
+      end
+
       private
 
-      def processed?
-        async? ? ready? : super
+      def resolved_async_options
+        @resolved_async_options ||=
+          variation.async_options.presence ||
+          ActiveStorage::AsyncVariants::Registry[variation.digest] ||
+          {}
       end
 
-      def async?
-        variation.async_options[:fallback].present?
+      def active_fallback
+        if failed?
+          resolved_async_options.fetch(:failed) { resolved_async_options[:processing] }
+        else
+          resolved_async_options[:processing]
+        end
       end
 
-      def async_record
-        blob.variant_records.find_by(variation_digest: variation.digest)
+      def enqueue_processing
+        result = find_named_async_variant
+        return unless result
+        attachment, variant_name, _ = result
+
+        return if async_record
+
+        blob.variant_records.create!(
+          variation_digest: variation.digest,
+          state: "pending",
+        )
+
+        ActiveStorage::AsyncVariants::ProcessJob.perform_later(
+          attachment.record, attachment.name, variant_name.to_s,
+        )
+      rescue ActiveRecord::RecordNotUnique
+        # another caller won the race; their job will handle processing
       end
 
-      def fallback_url(...)
-        case variation.async_options[:fallback]
-        when :original
-          blob.url(...)
-        when :blank
-          nil
-        when Proc
-          variation.async_options[:fallback].call(blob)
+      # Cold-path scan: only used by enqueue_processing, which needs the
+      # (attachment.record, attachment.name, variant_name) tuple to dispatch
+      # ProcessJob -- more than the digest registry stores. Hot-path URL
+      # resolution goes through Registry, not this method.
+      def find_named_async_variant
+        target = variation.transformations.to_json
+
+        blob.attachments.each do |attachment|
+          attachment.send(:named_variants).each do |name, _|
+            candidate = attachment.variant(name.to_sym)
+            if candidate.variation.transformations.to_json == target
+              return [attachment, name, candidate.variation.async_options] if candidate.variation.async_options[:processing].present?
+            end
+          end
         end
+
+        nil
+      end
+
+      def async_record
+        blob.variant_records.find_by(variation_digest: variation.digest)
       end
     end
   end

data/lib/active_storage/async_variants/variation_extension.rb

@@ -3,7 +3,7 @@
 module ActiveStorage
   module AsyncVariants
     module VariationExtension
-      ASYNC_KEYS = %i[fallback transformer max_retries].freeze
+      ASYNC_KEYS = %i[processing failed transformer].freeze
 
       def initialize(transformations)
         if transformations.is_a?(Hash)
@@ -13,6 +13,7 @@ module ActiveStorage
           @async_options = {}
           super
         end
+        ActiveStorage::AsyncVariants::Registry.register(digest, @async_options) if @async_options[:processing].present?
       end
 
       def async_options

data/lib/active_storage/async_variants/version.rb

@@ -2,6 +2,6 @@
 
 module ActiveStorage
   module AsyncVariants
-    VERSION = "0.1.0"
+    VERSION = "0.3.1"
   end
 end

data/lib/active_storage/async_variants.rb

@@ -2,36 +2,97 @@
 
 require_relative "async_variants/version"
 require_relative "async_variants/transformer"
+require_relative "async_variants/registry"
+require_relative "async_variants/blob_extension"
 require_relative "async_variants/variation_extension"
 require_relative "async_variants/variant_with_record_extension"
+require_relative "async_variants/variant_record_extension"
+require_relative "async_variants/preview_extension"
 require_relative "async_variants/attachment_extension"
+require_relative "async_variants/reflection_extension"
 require_relative "async_variants/process_job"
+require_relative "async_variants/representations_redirect_controller_extension"
+require_relative "async_variants/asset_tag_helper_extension"
 
 module ActiveStorage
   module AsyncVariants
+    mattr_accessor :cdn_host
+
     class Engine < ::Rails::Engine
+      # :nocov:
+      initializer "active_storage_async_variants.assets" do |app|
+        if app.config.respond_to?(:assets)
+          app.config.assets.precompile += %w[active_storage_async_variants.js]
+        end
+      end
+      # :nocov:
+
+      # Prepend the core model/reflection extensions before eager_load runs
+      # so that models' has_X_attached blocks (and the Variation.wrap calls
+      # they trigger via reflection.variant) go through our hooks. The
+      # :before_eager_load load_hook fires from the eager_load! initializer
+      # in finisher_hook, after all autoload paths have been set up but
+      # before any model class is loaded.
+      # :nocov:
+      ActiveSupport.on_load(:before_eager_load) do
+        ActiveStorage::AsyncVariants.prepend_model_extensions!
+      end
+      # :nocov:
+
       config.after_initialize do
-        ActiveStorage::Variation.prepend(
-          ActiveStorage::AsyncVariants::VariationExtension
-        )
-        ActiveStorage::VariantWithRecord.prepend(
-          ActiveStorage::AsyncVariants::VariantWithRecordExtension
+        # Idempotent — covers eager_load=false (dev/test) where the
+        # :before_eager_load hook never fires. Models autoload lazily on
+        # demand, and we just need the extensions in place by the time
+        # the first one loads.
+        ActiveStorage::AsyncVariants.prepend_model_extensions!
+
+        ActiveStorage::Representations::RedirectController.prepend(
+          ActiveStorage::AsyncVariants::RepresentationsRedirectControllerExtension
         )
-        ActiveStorage::Attachment.prepend(
-          ActiveStorage::AsyncVariants::AttachmentExtension
+        ActionView::Helpers::AssetTagHelper.prepend(
+          ActiveStorage::AsyncVariants::AssetTagHelperExtension
         )
       end
     end
 
+    def self.prepend_model_extensions!
+      return if @model_extensions_prepended
+      @model_extensions_prepended = true
+
+      require "active_storage/reflection"
+      ActiveStorage::Reflection::HasAttachedReflection.prepend(
+        ActiveStorage::AsyncVariants::ReflectionExtension
+      )
+      ActiveStorage::Blob.prepend(
+        ActiveStorage::AsyncVariants::BlobExtension
+      )
+      ActiveStorage::Variation.prepend(
+        ActiveStorage::AsyncVariants::VariationExtension
+      )
+      ActiveStorage::VariantWithRecord.prepend(
+        ActiveStorage::AsyncVariants::VariantWithRecordExtension
+      )
+      ActiveStorage::VariantRecord.include(
+        ActiveStorage::AsyncVariants::VariantRecordExtension
+      )
+      ActiveStorage::Attachment.prepend(
+        ActiveStorage::AsyncVariants::AttachmentExtension
+      )
+      ActiveStorage::Preview.prepend(
+        ActiveStorage::AsyncVariants::PreviewExtension
+      )
+    end
+
     def self.callback_token_for(variant_record)
       ActiveStorage.verifier.generate(variant_record.id, purpose: :async_variant_callback)
     end
 
     def self.callback_url_for(variant_record)
+      url_options = ActiveStorage::Current.url_options || Rails.application.default_url_options
       token = callback_token_for(variant_record)
       Rails.application.routes.url_helpers.active_storage_async_variant_callback_url(
         token: token,
-        **ActiveStorage::Current.url_options,
+        **url_options,
       )
     end
   end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: active_storage-async_variants
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Micah Geisel
 bindir: exe
 cert_chain: []
-date: 2026-03-04 00:00:00.000000000 Z
+date: 2026-05-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activestorage
@@ -38,18 +38,23 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- app/assets/javascripts/active_storage_async_variants.js
 - app/controllers/active_storage/async_variants/callbacks_controller.rb
 - config/routes.rb
 - gemfiles/rails_7.2.gemfile
-- gemfiles/rails_7.2.gemfile.lock
 - gemfiles/rails_8.0.gemfile
-- gemfiles/rails_8.0.gemfile.lock
 - gemfiles/rails_8.1.gemfile
-- gemfiles/rails_8.1.gemfile.lock
 - lib/active_storage/async_variants.rb
+- lib/active_storage/async_variants/asset_tag_helper_extension.rb
 - lib/active_storage/async_variants/attachment_extension.rb
+- lib/active_storage/async_variants/blob_extension.rb
+- lib/active_storage/async_variants/preview_extension.rb
 - lib/active_storage/async_variants/process_job.rb
+- lib/active_storage/async_variants/reflection_extension.rb
+- lib/active_storage/async_variants/registry.rb
+- lib/active_storage/async_variants/representations_redirect_controller_extension.rb
 - lib/active_storage/async_variants/transformer.rb
+- lib/active_storage/async_variants/variant_record_extension.rb
 - lib/active_storage/async_variants/variant_with_record_extension.rb
 - lib/active_storage/async_variants/variation_extension.rb
 - lib/active_storage/async_variants/version.rb