active_storage-async_variants 0.3.1 → 0.5.0

data/lib/active_storage/async_variants/asset_tag_helper_extension.rb

@@ -2,76 +2,58 @@
 
 module ActiveStorage
   module AsyncVariants
+    # Prepended onto ActionView::Helpers::AssetTagHelper. Adds `async:` and
+    # `direct:` options to image_tag/video_tag; routes unprocessed variants
+    # through a <turbo-frame> whose body lives in StatesController#show.
     module AssetTagHelperExtension
+      include ActiveStorage::AsyncVariants::Helper
+
       def image_tag(source, options = {})
-        options = options.symbolize_keys
-        async = options.delete(:async)
-        direct = options.delete(:direct)
-        return super if !async && !direct
-        variant = AssetTagHelperExtension.coerce_variant!(source)
-        src = AssetTagHelperExtension.resolve_src(variant, direct: direct)
-        AssetTagHelperExtension.apply_async_data!(options, variant: variant, direct: direct) if async
-        super(src, options)
+        async_variant_tag(:image, [source], options) do |urls, opts|
+          super(urls.first, opts)
+        end
       end
 
       def video_tag(*sources)
-        options = sources.extract_options!.symbolize_keys
-        async = options.delete(:async)
-        direct = options.delete(:direct)
-        return super(*sources, options) if !async && !direct
-        variant = AssetTagHelperExtension.coerce_variant!(sources.first)
-        sources[0] = AssetTagHelperExtension.resolve_src(variant, direct: direct)
-        AssetTagHelperExtension.apply_async_data!(options, variant: variant, direct: direct) if async
-        super(*sources, options)
+        options = sources.extract_options!
+        async_variant_tag(:video, sources, options) do |urls, opts|
+          super(*urls, opts)
+        end
       end
 
-      class << self
-        def coerce_variant!(source)
-          unless source.is_a?(ActiveStorage::VariantWithRecord) || source.is_a?(ActiveStorage::Preview)
-            raise ArgumentError, "image_tag/video_tag with async:/direct: requires an ActiveStorage::VariantWithRecord or Preview, got #{source.class}"
-          end
-          source
-        end
+      private
 
-        def resolve_src(variant, direct:)
-          if direct && variant.async_state == "processed"
-            direct_url(variant)
-          else
-            # Idempotent: enqueue ProcessJob if no record exists yet so a
-            # never-touched variant doesn't sit pending forever. Gated on
-            # bucket-backed services -- on Disk/Test the gem defers to
-            # vanilla ActiveStorage, and #processed would run a synchronous
-            # transform (e.g. vips on an mp4) that the external transformer
-            # is supposed to handle.
-            variant.processed if variant.blob.bucket_backed?
-            polymorphic_url(variant)
-          end
-        end
+      def async_variant_tag(kind, sources, options)
+        options = options.symbolize_keys
+        async = options.delete(:async)
+        direct = options.delete(:direct)
+        return yield(sources, options) if !async && !direct
 
-        def apply_async_data!(options, variant:, direct:)
-          data = (options[:data] || {}).symbolize_keys
-          controllers = data[:controller].to_s.split
-          controllers << "async-variant" unless controllers.include?("async-variant")
-          data[:controller] = controllers.join(" ")
-          data[:async_variant_src_value] = polymorphic_url(variant)
-          data[:async_variant_state_value] = variant.async_state
-          data[:async_variant_direct_value] = direct_url(variant) if direct && variant.async_state == "processed"
-          options[:data] = data
-        end
+        variant, *rest = sources
+        assert_async_variant!(variant)
 
-        def direct_url(variant)
-          if cdn = ActiveStorage::AsyncVariants.cdn_host
-            "#{cdn}/#{variant.key}"
-          else
-            variant.image.url
-          end
+        if async && !async_variant_processed_inline?(variant)
+          async_variant_turbo_frame(variant, kind:, direct:, html_options: options)
+        else
+          yield [async_variant_resolved_src(variant, direct:), *rest], options
         end
+      end
 
-        def polymorphic_url(variant)
-          url_options = ActiveStorage::Current.url_options || Rails.application.routes.default_url_options
-          Rails.application.routes.url_helpers.polymorphic_url(variant, **url_options)
+      def assert_async_variant!(source)
+        unless source.is_a?(ActiveStorage::VariantWithRecord) || source.is_a?(ActiveStorage::Preview)
+          raise ArgumentError, "image_tag/video_tag with async:/direct: requires an ActiveStorage::VariantWithRecord or Preview, got #{source.class}"
         end
       end
+
+      def async_variant_turbo_frame(variant, kind:, direct:, html_options:)
+        content_tag(
+          :"turbo-frame",
+          "",
+          id: async_variant_frame_id(variant),
+          src: async_variant_frame_src(variant, kind: kind, direct: direct, html_options: html_options),
+          refresh: "morph",
+        )
+      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

@@ -3,18 +3,27 @@
 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).
+      # 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
-        if async_preview?
-          enqueue_async_preview unless preview_variant_processed?
-          self
-        else
-          super
+        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?
@@ -52,14 +61,29 @@ module ActiveStorage
       # 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.
+      # 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
@@ -71,27 +95,6 @@ module ActiveStorage
         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(...)

data/lib/active_storage/async_variants/variant_with_record_extension.rb

@@ -3,13 +3,27 @@
 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
-        if blob.bucket_backed?
-          enqueue_processing unless processed? || processing?
-          self
-        else
-          super
+        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(...)
@@ -62,6 +76,7 @@ module ActiveStorage
         @resolved_async_options ||=
           variation.async_options.presence ||
           ActiveStorage::AsyncVariants::Registry[variation.digest] ||
+          find_named_async_variant&.dig(2) ||
           {}
       end
 
@@ -73,33 +88,29 @@ module ActiveStorage
         end
       end
 
-      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
-
-      # 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.
+      # 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 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
 
-        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
@@ -107,7 +118,6 @@ module ActiveStorage
             end
           end
         end
-
         nil
       end
 

data/lib/active_storage/async_variants/version.rb

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

data/lib/active_storage/async_variants.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
+require "turbo-rails"
+require "isolate_assets"
 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"
@@ -11,22 +14,34 @@ 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
+    # 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
+    mattr_accessor :retry_visible_proc, default: ->(_view) { false }
 
-    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:
+    # 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"
+
+    # Gates the failed-state retry affordance; the block runs in the view context.
+    def self.retry_visible_if(&block)
+      self.retry_visible_proc = block
+    end
 
+    def self.retry_visible?(view)
+      !!view.instance_exec(&retry_visible_proc)
+    rescue StandardError
+      false
+    end
+
+    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
@@ -46,9 +61,6 @@ module ActiveStorage
         # the first one loads.
         ActiveStorage::AsyncVariants.prepend_model_extensions!
 
-        ActiveStorage::Representations::RedirectController.prepend(
-          ActiveStorage::AsyncVariants::RepresentationsRedirectControllerExtension
-        )
         ActionView::Helpers::AssetTagHelper.prepend(
           ActiveStorage::AsyncVariants::AssetTagHelperExtension
         )
@@ -56,9 +68,6 @@ module ActiveStorage
     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
@@ -83,6 +92,8 @@ module ActiveStorage
       )
     end
 
+    Assets = IsolateAssets.register(namespace: self, engine: Engine, route_name: :async_variant_asset)
+
     def self.callback_token_for(variant_record)
       ActiveStorage.verifier.generate(variant_record.id, purpose: :async_variant_callback)
     end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: active_storage-async_variants
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Micah Geisel
 bindir: exe
 cert_chain: []
-date: 2026-05-29 00:00:00.000000000 Z
+date: 2026-06-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activestorage
@@ -23,6 +23,34 @@ 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'
+- !ruby/object:Gem::Dependency
+  name: isolate_assets
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.4'
 email:
 - micah@botandrose.com
 executables: []
@@ -38,9 +66,21 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
-- app/assets/javascripts/active_storage_async_variants.js
+- app/assets/javascripts/retry.js
+- app/assets/stylesheets/retry.css
 - 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/retry_flow.feature
+- features/retry_visibility.feature
+- features/state_rendering.feature
+- features/step_definitions/dummy_steps.rb
+- features/support/env.rb
 - gemfiles/rails_7.2.gemfile
 - gemfiles/rails_8.0.gemfile
 - gemfiles/rails_8.1.gemfile
@@ -48,11 +88,11 @@ files:
 - 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/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