active_storage-async_variants 0.1.0 → 0.4.0

data/lib/active_storage/async_variants/attachment_extension.rb

@@ -11,8 +11,10 @@ module ActiveStorage
       end
 
       def enqueue_async_variant_jobs
+        return unless blob.bucket_backed?
+
         named_variants.each do |name, named_variant|
-          next unless named_variant.transformations.key?(:fallback)
+          next unless named_variant.transformations.key?(:processing)
 
           ActiveStorage::AsyncVariants::ProcessJob.perform_later(
             record, self.name, name.to_s,

data/lib/active_storage/async_variants/blob_extension.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module ActiveStorage
+  module AsyncVariants
+    module BlobExtension
+      # True when the blob's service is a remote/cloud service that the async
+      # processing workers (Crucible, etc.) can reach via presigned URLs. The
+      # Disk and Test services return false; the gem then defers to vanilla
+      # ActiveStorage rather than trying to enqueue jobs or serve fallbacks.
+      def bucket_backed?
+        service.respond_to?(:bucket)
+      end
+    end
+  end
+end

data/lib/active_storage/async_variants/helper.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module ActiveStorage
+  module AsyncVariants
+    # View/controller helper methods. Included in the AssetTagHelperExtension
+    # (so image_tag/video_tag can use them) and added to StatesController via
+    # `helper ActiveStorage::AsyncVariants::Helper` (so the state partials can
+    # use them).
+    module Helper
+      # In test with non-bucket-backed services, the gem defers to vanilla
+      # ActiveStorage (synchronous vips transform) -- inline rendering keeps
+      # those environments simple. Otherwise, only inline a normal <img> when
+      # the variant has reached the processed terminal state.
+      def async_variant_processed_inline?(variant)
+        !variant.blob.bucket_backed? || variant.async_state == "processed"
+      end
+
+      def async_variant_resolved_src(variant, direct:)
+        if direct && variant.async_state == "processed"
+          async_variant_direct_url(variant)
+        else
+          variant.processed if variant.blob.bucket_backed?
+          async_variant_representation_path(variant)
+        end
+      end
+
+      def async_variant_frame_id(variant)
+        digest = variant.variation.digest.gsub(/[^a-zA-Z0-9_-]/, "")
+        "async-variant-#{variant.blob.id}-#{digest}"
+      end
+
+      def async_variant_frame_src(variant, kind:, direct:, html_options: {})
+        async_variant_state_path(
+          signed_blob_id: variant.blob.signed_id,
+          variation_key: variant.variation.key,
+          kind:,
+          direct:,
+          opts: html_options.slice(*PASS_THROUGH_HTML_OPTIONS),
+        )
+      end
+
+      def async_variant_direct_url(variant)
+        if cdn = ActiveStorage::AsyncVariants.cdn_host
+          "#{cdn}/#{variant.key}"
+        else
+          variant.image.url
+        end
+      end
+
+      def async_variant_representation_path(variant)
+        Rails.application.routes.url_helpers.rails_blob_representation_path(
+          variant.blob.signed_id,
+          variant.variation.key,
+          variant.blob.filename.to_s,
+        )
+      end
+    end
+  end
+end

data/lib/active_storage/async_variants/preview_extension.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module ActiveStorage
+  module AsyncVariants
+    module PreviewExtension
+      # Block vanilla ActiveStorage's synchronous preview transform on
+      # async-backed services; rely on the auto-enqueue (AttachmentExtension)
+      # path -- and the public #enqueue! -- to dispatch ProcessJob.
+      def processed
+        async_preview? ? self : super
+      end
+
+      def enqueue!
+        if result = find_named_async_variant
+          attachment, variant_name, _ = result
+
+          blob.variant_records.create!(
+            variation_digest: variation.digest,
+            state: "pending",
+          )
+          ActiveStorage::AsyncVariants::ProcessJob.perform_later(
+            attachment.record, attachment.name, variant_name.to_s,
+          )
+        end
+      rescue ActiveRecord::RecordNotUnique
+        # another caller (or a leftover record) wins; their job handles it
+      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,
+      # or fall back to scanning attached named variants when the registry is
+      # cold (autoloader hasn't touched the consumer model yet).
+      def resolved_async_options
+        @resolved_async_options ||=
+          variation.async_options.presence ||
+          ActiveStorage::AsyncVariants::Registry[variation.digest] ||
+          find_named_async_variant&.dig(2) ||
+          {}
+      end
+
+      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)
+            next unless candidate.variation.transformations.to_json == target
+            return [attachment, name, candidate.variation.async_options] if candidate.variation.async_options[:transformer].present?
+          end
+        end
+        nil
+      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
+
+      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/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,50 @@
 module ActiveStorage
   module AsyncVariants
     module VariantWithRecordExtension
+      # Block vanilla ActiveStorage's synchronous transform on bucket-backed
+      # services; rely on the auto-enqueue (AttachmentExtension) path -- and the
+      # public #enqueue! -- to dispatch ProcessJob.
+      def processed
+        blob.bucket_backed? ? self : super
+      end
+
+      def enqueue!
+        if result = find_named_async_variant
+          attachment, variant_name, _ = result
+
+          blob.variant_records.create!(
+            variation_digest: variation.digest,
+            state: "pending",
+          )
+          ActiveStorage::AsyncVariants::ProcessJob.perform_later(
+            attachment.record, attachment.name, variant_name.to_s,
+          )
+        end
+      rescue ActiveRecord::RecordNotUnique
+        # another caller (or a leftover record) wins; their job handles it
+      end
+
       def url(...)
-        if processed?
-          super
+        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 +65,64 @@ 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] ||
+          find_named_async_variant&.dig(2) ||
+          {}
       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)
+      # Cold-path scan: used by enqueue! (which needs the attachment +
+      # variant_name to dispatch ProcessJob) and by resolved_async_options as
+      # a fallback when the Registry is cold (e.g. in dev, when a
+      # RepresentationsRedirectController request hits a worker that hasn't
+      # autoloaded the consumer model yet).
+      #
+      # Walks one level through preview_image attachments so a request for
+      # a Variant of a video's extracted preview frame can still find the
+      # named variant declared on the parent record's source-video field.
+      def find_named_async_variant
+        target = variation.transformations.to_json
+        scan_for_named_variant(blob, target)
       end
 
-      def fallback_url(...)
-        case variation.async_options[:fallback]
-        when :original
-          blob.url(...)
-        when :blank
-          nil
-        when Proc
-          variation.async_options[:fallback].call(blob)
+      def scan_for_named_variant(blob_to_scan, target, depth: 0)
+        blob_to_scan.attachments.each do |attachment|
+          if attachment.name == "preview_image" && attachment.record_type == "ActiveStorage::Blob" && depth < 1
+            source = ActiveStorage::Blob.find_by(id: attachment.record_id)
+            result = source && scan_for_named_variant(source, target, depth: depth + 1)
+            return result if result
+            next
+          end
+
+          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.4.0"
   end
 end

data/lib/active_storage/async_variants.rb

@@ -1,37 +1,94 @@
 # frozen_string_literal: true
 
+require "turbo-rails"
 require_relative "async_variants/version"
+require_relative "async_variants/helper"
 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/asset_tag_helper_extension"
 
 module ActiveStorage
   module AsyncVariants
+    # HTML attributes round-tripped through the state-endpoint URL so the
+    # eventual processed-state render can apply them to the inner <img>/<video>.
+    PASS_THROUGH_HTML_OPTIONS = %i[alt width height controls autoplay preload].freeze
+
+    mattr_accessor :cdn_host
+
+    # Lets the host app plug its auth chain (and thus `current_user`) into the
+    # gem's StatesController. Set to a string so resolution is deferred until
+    # the host's class is autoloadable. Defaults to ActionController::Base.
+    mattr_accessor :parent_controller, default: "ActionController::Base"
+
     class Engine < ::Rails::Engine
+      # 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
-        )
-        ActiveStorage::Attachment.prepend(
-          ActiveStorage::AsyncVariants::AttachmentExtension
+        # 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!
+
+        ActionView::Helpers::AssetTagHelper.prepend(
+          ActiveStorage::AsyncVariants::AssetTagHelperExtension
         )
       end
     end
 
+    def self.prepend_model_extensions!
+      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.4.0
 platform: ruby
 authors:
 - Micah Geisel
 bindir: exe
 cert_chain: []
-date: 2026-03-04 00:00:00.000000000 Z
+date: 2026-06-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activestorage
@@ -23,6 +23,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '7.2'
+- !ruby/object:Gem::Dependency
+  name: turbo-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
 email:
 - micah@botandrose.com
 executables: []
@@ -39,17 +53,30 @@ files:
 - README.md
 - Rakefile
 - app/controllers/active_storage/async_variants/callbacks_controller.rb
+- app/controllers/active_storage/async_variants/states_controller.rb
+- app/views/active_storage/async_variants/states/_failed.html.erb
+- app/views/active_storage/async_variants/states/_pending.html.erb
+- app/views/active_storage/async_variants/states/_processed.html.erb
+- app/views/active_storage/async_variants/states/_processing.html.erb
+- app/views/active_storage/async_variants/states/show.html.erb
 - config/routes.rb
+- features/state_rendering.feature
+- features/step_definitions/dummy_steps.rb
+- features/support/env.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/helper.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/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