active_storage-async_variants 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ed31f4592e3d865609aef29b42657856321528d5013bb2a1ec499e3de93c5bb4
-  data.tar.gz: 994460c1ae175245da3d71489b25d4143827931f926289c94c18957df8cf0610
+  metadata.gz: 003cbfe68ded6c238669546679e76b7d0c8e856842450181ceb8497a9e452361
+  data.tar.gz: 0b41dad0aa8a59e81e9b2e384d6d04e55ee479c0c35822d71e3a06a46b0c64cd
 SHA512:
-  metadata.gz: c6b94095e095899175ac9fa37497500b9947e761d2ed07a7fdd78d55a90ac05898dca086e02d8b29419fc1fde8567628a4f6c7444470826ae6fb0556220af4ef
-  data.tar.gz: 109f1670b0ad22ce670bf27751ffeac462f0f10c94d0d89f4777c211b2fb1aa179c3981373ebc9b2f36a2262c4722dcdf73cd54ff95ca29cf6b035765150357f
+  metadata.gz: e5eb0728baf9f4d9cfc591625f6035d362d9df192c2c64fb7cef4e397fcef9817a460dbfba24210f01d777360a1d2e73e4dabf7d00306f8c9685ff1df4641b0e
+  data.tar.gz: 4c87c749a9dad93f251fcddf5830996f53d7c054becabdd529ea89000eb75e5f2360b6332aea764fc615931b0c350a15bfe8610d4b5efa1561a22ffd3d966ee6

data/CHANGELOG.md

@@ -1,3 +1,14 @@
+## [0.4.0]
+
+- **Breaking:** Replaced the polling-`<img>` architecture with a `<turbo-frame>` for unprocessed variants. `image_tag`/`video_tag` with `async: true` now emits a normal `<img>`/`<video>` when the variant is already processed, and a `<turbo-frame src="…">` otherwise. The frame hits a new gem-shipped endpoint (`GET /active_storage/async_variants/states/:signed_blob_id/:variation_key`) that renders one of `_processing`/`_failed`/`_processed` partials. Non-terminal renders include an inline `<script>` that schedules the frame's next reload, so the state polls itself until it terminates.
+- New `app/views/active_storage/async_variants/states/` partial set — apps can override any partial by creating a same-named file in their own `app/views/active_storage/async_variants/states/`. The processing state defaults to a bare `<img>`/`<video>` pointing at the variant's URL, which the gem redirects to the app's configured `processing:` SVG.
+- All CSS and JavaScript ship inline in the per-response state partials — no asset-pipeline footprint. Apps don't need to include any stylesheet or script.
+- **Breaking:** `Variant#processed` and `Preview#processed` are now no-ops on bucket-backed services (they previously also lazy-enqueued `ProcessJob` for any record that wasn't already processed). Enqueue now happens only at attachment time (via `AttachmentExtension#transform_variants_later`). Pre-existing blobs that missed the auto-enqueue won't self-heal on first view; backfill via a rake task.
+- New public `#enqueue!` method on both `Variant` and `Preview` with the same signature — no `respond_to?` dance. Creates a pending `VariantRecord` (RecordNotUnique guards dedupe) and dispatches `ProcessJob`. Replaces the previously private `enqueue_processing` / `enqueue_async_preview`.
+- The named-variant lookup now walks one level back through `preview_image` attachments, so a request for a Variant of a video's extracted preview frame can recover the named-variant declaration from the parent record's source-video field. Fixes nil-URL 500s in dev where the cold Registry can't resolve a redirect-controller request.
+- Added `turbo-rails >= 2.0` as a runtime dependency.
+- Removed `RepresentationsRedirectControllerExtension`, the `[data-async-variant-*]` polling JS, the bundled `app/assets/stylesheets/active_storage_async_variants.css`, the engine's asset precompile initializer, and the `apply_async_data!` helper machinery. Consumers depending on those data attributes must migrate to targeting the new `.async-variant-state` classes or override the partials.
+
 ## [0.3.1]
 
 - Bound the stored variant `error` to 16k chars at both write sites (the failed-status callback and `ProcessJob`'s rescue). An external transformer reporting a >64KB error payload was overflowing the `TEXT` column and 500ing the callback, leaving the variant stuck instead of marked failed.

data/README.md

@@ -97,29 +97,9 @@ ActiveStorage::AsyncVariants.cdn_host = "https://d1234abcd.cloudfront.net"
 
 The resulting URL is `"#{cdn_host}/#{variant.key}"`.
 
-### Wiring the JavaScript
+### JavaScript
 
-The gem ships a dependency-free Stimulus-like controller at `app/assets/javascripts/active_storage_async_variants.js`. It is registered with the asset pipeline by the engine but not auto-imported. Wire it up the same way as `@rails/activestorage` -- pick whichever fits your bundler:
-
-Using **importmap-rails**:
-
-```ruby
-# config/importmap.rb
-pin "@active_storage/async_variants", to: "active_storage_async_variants.js", preload: true
-```
-
-```js
-// app/javascript/application.js
-import "@active_storage/async_variants"
-```
-
-Using **the asset pipeline** (sprockets/propshaft) with a classic `javascript_include_tag`:
-
-```erb
-<%= javascript_include_tag "active_storage_async_variants" %>
-```
-
-The module auto-starts on `DOMContentLoaded` and finds elements with `data-async-variant-state-value`. Opt out by setting `window.ActiveStorageAsyncVariants = null` before the script loads, then calling `start()` yourself from the exported module when ready.
+No manual wiring is required. The async state partials are self-contained `<turbo-frame>`s. The only requirement is that the host app loads **Turbo** -- the gem depends on `turbo-rails`, which a default Rails app already includes.
 
 ## Writing a Transformer
 

data/Rakefile

@@ -5,4 +5,12 @@ require "rspec/core/rake_task"
 
 RSpec::Core::RakeTask.new(:spec)
 
-task default: :spec
+desc "Run browser-level acceptance tests (cucumber + cuprite against spec/dummy)"
+task :cucumber do
+  sh "bundle exec cucumber"
+end
+
+desc "Run rspec and cucumber"
+task all: [:spec, :cucumber]
+
+task default: :all

data/app/controllers/active_storage/async_variants/states_controller.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module ActiveStorage
+  module AsyncVariants
+    class StatesController < ActiveStorage::AsyncVariants.parent_controller.constantize
+      # signed_blob_id + variation_key in URL act as CSRF: both require app's secret.
+      skip_forgery_protection
+
+      helper "turbo/frames"
+      helper ActiveStorage::AsyncVariants::Helper
+
+      layout false
+
+      before_action :set_variant
+
+      def show
+      end
+
+      helper_method :async_variant_kind, :async_variant_direct?, :async_variant_html_options
+
+      private
+
+      def set_variant
+        blob = ActiveStorage::Blob.find_signed!(params[:signed_blob_id])
+        variation = ActiveStorage::Variation.decode(params[:variation_key])
+        @variant = blob.variant(variation)
+      rescue ActiveSupport::MessageVerifier::InvalidSignature
+        head :not_found
+      end
+
+      def async_variant_kind
+        params[:kind].to_s == "video" ? :video : :image
+      end
+
+      def async_variant_direct?
+        ActiveModel::Type::Boolean.new.cast(params[:direct])
+      end
+
+      def async_variant_html_options
+        params[:opts]
+          &.permit(*ActiveStorage::AsyncVariants::PASS_THROUGH_HTML_OPTIONS)
+          .to_h
+      end
+    end
+  end
+end

data/app/views/active_storage/async_variants/states/_failed.html.erb

@@ -0,0 +1,4 @@
+<div class="async-variant-state async-variant-failed">
+  <% method = kind == :video ? :video_tag : :image_tag %>
+  <%= send method, async_variant_representation_path(variant), **html_options.symbolize_keys %>
+</div>

data/app/views/active_storage/async_variants/states/_pending.html.erb

@@ -0,0 +1 @@
+<%= render "active_storage/async_variants/states/processing", local_assigns %>

data/app/views/active_storage/async_variants/states/_processed.html.erb

@@ -0,0 +1,5 @@
+<%
+  method = kind == :video ? :video_tag : :image_tag
+  src = direct ? async_variant_direct_url(variant) : async_variant_representation_path(variant)
+%>
+<%= send method, src, **html_options.symbolize_keys %>

data/app/views/active_storage/async_variants/states/_processing.html.erb

@@ -0,0 +1,10 @@
+<div class="async-variant-state async-variant-processing">
+  <% method = kind == :video ? :video_tag : :image_tag %>
+  <%= send method, async_variant_representation_path(variant), **html_options.symbolize_keys %>
+</div>
+<%# Self-perpetuating poll: Turbo runs <script>s in frame swaps, so each
+    pending/processing response schedules its own next reload. Terminal
+    partials (_failed, _processed) emit no script -> chain stops. %>
+<script>
+  setTimeout(() => document.getElementById("<%= async_variant_frame_id(variant) %>")?.reload(), 3000)
+</script>

data/app/views/active_storage/async_variants/states/show.html.erb

@@ -0,0 +1,8 @@
+<%= turbo_frame_tag async_variant_frame_id(@variant) do %>
+  <%= render "active_storage/async_variants/states/#{@variant.async_state}", {
+    variant: @variant,
+    html_options: async_variant_html_options,
+    kind: async_variant_kind,
+    direct: async_variant_direct?,
+  } %>
+<% end %>

data/config/routes.rb

@@ -4,4 +4,8 @@ Rails.application.routes.draw do
   post "/active_storage/async_variants/callbacks/:token",
     to: "active_storage/async_variants/callbacks#create",
     as: :active_storage_async_variant_callback
+
+  get  "/active_storage/async_variants/states/:signed_blob_id/:variation_key",
+    to: "active_storage/async_variants/states#show",
+    as: :async_variant_state
 end

data/features/state_rendering.feature

@@ -0,0 +1,21 @@
+Feature: image_tag with async: true emits the right markup per variant state
+
+  Scenario: A processed variant emits a plain <img> -- no turbo-frame, no chrome
+    Given a user with an attached avatar
+    And the avatar's :thumb_proc variant is in processed state
+    When I visit the avatar page for the :thumb_proc variant
+    Then the page should NOT contain a turbo-frame
+
+  Scenario: An unprocessed variant emits a turbo-frame in processing state
+    Given a user with an attached avatar
+    And the avatar's :thumb_proc variant is in processing state
+    When I visit the avatar page for the :thumb_proc variant
+    Then the page should contain a turbo-frame
+    And the frame should render the processing state
+
+  Scenario: A failed variant renders the failed partial inside the frame
+    Given a user with an attached avatar
+    And the avatar's :thumb_proc variant is in failed state with error "boom"
+    When I visit the avatar page for the :thumb_proc variant
+    Then the page should contain a turbo-frame
+    And the frame should render the failed state

data/features/step_definitions/dummy_steps.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+Given /^a user with an attached avatar$/ do
+  @user = User.create!
+  attach_avatar_to(@user)
+end
+
+Given /^the avatar's :(\w+) variant is in (pending|processing|processed|failed) state(?: with error "([^"]+)")?$/ do |variant_name, state, error|
+  variant = @user.avatar.variant(variant_name.to_sym)
+  if state == "processed"
+    simulate_processed_variant(variant)
+  else
+    create_variant_record(variant, state: state, error: error)
+  end
+end
+
+Given /^the retry affordance is visible to everyone$/ do
+  ActiveStorage::AsyncVariants.retry_visible_if { true }
+end
+
+Given /^the retry affordance is hidden$/ do
+  ActiveStorage::AsyncVariants.retry_visible_if { false }
+end
+
+Given /^the retry affordance requires a signed-in user$/ do
+  ActiveStorage::AsyncVariants.retry_visible_if { current_user.present? }
+end
+
+When /^I sign in as the (admin|user)$/ do |_kind|
+  visit "/session/#{@user.id}"
+end
+
+When /^I visit the avatar page for the :(\w+) variant$/ do |variant_name|
+  visit "/avatars/#{@user.id}/#{variant_name}"
+end
+
+Then /^the page should contain a turbo-frame$/ do
+  expect(page).to have_css("turbo-frame")
+end
+
+Then /^the page should NOT contain a turbo-frame$/ do
+  expect(page).to have_no_css("turbo-frame")
+  expect(page).to have_css("img")
+end
+
+Then /^the frame should render the (failed|processing|processed) state$/ do |state|
+  expect(page).to have_css("turbo-frame .async-variant-#{state}")
+end
+
+Then /^the retry affordance should be visible$/ do
+  expect(page).to have_css("async-variant-retry", visible: :all)
+end
+
+Then /^the retry affordance should NOT be visible$/ do
+  expect(page).to have_no_css("async-variant-retry", visible: :all)
+end
+
+Then /^the page should not have navigated away$/ do
+  expect(page).to have_css("h1#page-marker")
+end
+
+Then /^the failure dialog should be open$/ do
+  expect(page).to have_css("async-variant-retry", visible: :all)
+  open = page.evaluate_script(<<~JS)
+    (() => {
+      const host = document.querySelector("async-variant-retry")
+      if (!host || !host.shadowRoot) return false
+      const dialog = host.shadowRoot.querySelector("dialog")
+      return dialog ? dialog.open : false
+    })()
+  JS
+  expect(open).to eq(true)
+end
+
+Then /^the failure dialog should contain "([^"]+)"$/ do |text|
+  contains = page.evaluate_script(<<~JS)
+    (() => {
+      const host = document.querySelector("async-variant-retry")
+      if (!host || !host.shadowRoot) return false
+      return host.shadowRoot.textContent.includes(#{text.inspect})
+    })()
+  JS
+  expect(contains).to eq(true)
+end
+
+# Wait for Turbo to swap the frame and our shim to attach the shadow root.
+def wait_for_shadow!
+  Timeout.timeout(5) do
+    loop do
+      attached = page.evaluate_script("!!document.querySelector('async-variant-retry')?.shadowRoot")
+      break if attached
+      sleep 0.05
+    end
+  end
+end
+
+When /^I click the retry opener$/ do
+  wait_for_shadow!
+  page.evaluate_script(<<~JS)
+    document.querySelector("async-variant-retry").shadowRoot.querySelector(".opener").click()
+  JS
+end
+
+When /^I click "Retry processing"$/ do
+  wait_for_shadow!
+  page.evaluate_script(<<~JS)
+    document.querySelector("async-variant-retry").shadowRoot.querySelector("footer button").click()
+  JS
+end
+
+When /^I close the failure dialog$/ do
+  wait_for_shadow!
+  page.evaluate_script(<<~JS)
+    document.querySelector("async-variant-retry").shadowRoot.querySelector("dialog > button[type=button]").click()
+  JS
+end

data/features/support/env.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+ENV["RAILS_ENV"] ||= "test"
+require File.expand_path("../../spec/dummy/config/environment", __dir__)
+
+require "capybara"
+require "capybara/cucumber"
+require "capybara/cuprite"
+require_relative "../../spec/support/schema"
+
+DummySchema.load!
+
+Capybara.register_driver(:cuprite) do |app|
+  Capybara::Cuprite::Driver.new(app, window_size: [1200, 900], timeout: 10, process_timeout: 20, js_errors: true)
+end
+Capybara.app                = Rails.application
+Capybara.javascript_driver  = :cuprite
+Capybara.default_driver     = :cuprite
+Capybara.server             = :puma, { Silent: true }
+
+ActionController::Base.allow_forgery_protection = false
+
+# Test adapter just records enqueued jobs -- we don't want them to actually run
+# during browser tests (they'd call real transformers and modify variant_records
+# behind the test's back). The retry step seeds the new state explicitly.
+ActiveJob::Base.queue_adapter = :test
+
+Before { DummySchema.cleanup! }

data/lib/active_storage/async_variants/asset_tag_helper_extension.rb

@@ -2,76 +2,61 @@
 
 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
+        if async && !async_variant_processed_inline?(variant)
+          async_variant_turbo_frame(variant, kind:, direct:, html_options: options) do
+            # populate TurboFrame with a placeholder image/video, so there's valid markup right away
+            yield [async_variant_representation_path(variant), *rest], options.except(:data)
           end
+        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:, &block)
+        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",
+          &block
+        )
+      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.4.0"
   end
 end

data/lib/active_storage/async_variants.rb

@@ -1,6 +1,8 @@
 # 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"
@@ -11,22 +13,22 @@ 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
 
-    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"
 
+    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 +48,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 +55,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

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.4.0
 platform: ruby
 authors:
 - Micah Geisel
 bindir: exe
 cert_chain: []
-date: 2026-05-29 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: []
@@ -38,9 +52,17 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
-- app/assets/javascripts/active_storage_async_variants.js
 - 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_8.0.gemfile
 - gemfiles/rails_8.1.gemfile
@@ -48,11 +70,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

data/app/assets/javascripts/active_storage_async_variants.js

@@ -1,169 +0,0 @@
-// active-storage-async_variants
-// Renders the correct fallback for async ActiveStorage variants, and polls
-// for completion. Pairs with the gem's image_tag/video_tag `async:` /
-// `direct:` options.
-
-const STATE_ATTR = "data-async-variant-state-value"
-const SRC_ATTR = "data-async-variant-src-value"
-const DIRECT_ATTR = "data-async-variant-direct-value"
-const SELECTOR = `[${STATE_ATTR}]`
-const HEADER = "X-Async-Variant-State"
-const POLLABLE_STATES = ["pending", "processing"]
-const POLL_BASE_MS = 3000
-const MAX_POLLS = 10
-const RETRY_BASE_MS = 10000
-const MAX_RETRIES = 3
-
-const isSafari = typeof navigator !== "undefined" &&
-  /^((?!chrome|android).)*safari/i.test(navigator.userAgent)
-
-const elementState = new WeakMap()
-
-function stateFor(el) {
-  let s = elementState.get(el)
-  if (!s) {
-    s = { pollTimer: null, pollCount: 0, retries: 0 }
-    elementState.set(el, s)
-  }
-  return s
-}
-
-function srcUrl(el) { return el.getAttribute(SRC_ATTR) }
-function directUrl(el) { return el.getAttribute(DIRECT_ATTR) }
-function variantState(el) { return el.getAttribute(STATE_ATTR) }
-
-async function fetchAsyncState(url) {
-  if (!url) return null
-  try {
-    const response = await fetch(url, { method: "HEAD", redirect: "manual", cache: "no-store" })
-    if (response.type === "opaqueredirect") return null
-    return response.headers.get(HEADER)
-  } catch {
-    return null
-  }
-}
-
-function schedulePoll(el) {
-  const s = stateFor(el)
-  s.pollTimer = setTimeout(() => poll(el), POLL_BASE_MS * Math.pow(2, s.pollCount))
-}
-
-function stopPolling(el) {
-  const s = elementState.get(el)
-  if (s && s.pollTimer) {
-    clearTimeout(s.pollTimer)
-    s.pollTimer = null
-  }
-}
-
-function startPolling(el) {
-  const s = stateFor(el)
-  if (s.pollTimer) return
-  s.pollCount = 0
-  schedulePoll(el)
-}
-
-async function poll(el) {
-  const state = await fetchAsyncState(srcUrl(el))
-  const s = stateFor(el)
-  s.pollTimer = null
-  if (POLLABLE_STATES.includes(state)) {
-    s.pollCount += 1
-    if (s.pollCount < MAX_POLLS) schedulePoll(el)
-    return
-  }
-  if (state === "failed") {
-    el.setAttribute(STATE_ATTR, "failed")
-    return
-  }
-  const target = directUrl(el) || srcUrl(el)
-  if (!target) return
-  el.setAttribute(STATE_ATTR, "processed")
-  el.src = target + (target.includes("?") ? "&" : "?") + "_t=" + Date.now()
-}
-
-function fallback(el) {
-  const url = srcUrl(el)
-  if (url) el.setAttribute("src", url)
-}
-
-function onLoad(event) {
-  const el = event.target
-  if (!el.matches || !el.matches(SELECTOR)) return
-  if (POLLABLE_STATES.includes(variantState(el))) startPolling(el)
-}
-
-function onError(event) {
-  const el = event.target
-  if (!el.matches || !el.matches(SELECTOR)) return
-  const s = stateFor(el)
-  if (s.retries >= MAX_RETRIES) return
-  setTimeout(() => fallback(el), RETRY_BASE_MS * Math.pow(2, s.retries))
-  s.retries += 1
-}
-
-function setupVideo(el) {
-  if (el.nodeName !== "VIDEO") return
-  if (isSafari) fallback(el)
-  // Browser autoplay-via-attribute is permitted on first load, but the
-  // attribute also makes Turbo's cloneNode(true) snapshot start playback on
-  // the detached clone (ghost audio). Strip the attribute after insertion --
-  // playback is already scheduled -- and rely on play() here for restored
-  // snapshots (which won't have the attribute anymore).
-  // https://github.com/hotwired/turbo/issues/1017
-  if (el.hasAttribute("autoplay")) {
-    el.removeAttribute("autoplay")
-    const promise = el.play()
-    if (promise && typeof promise.catch === "function") promise.catch(() => {})
-  }
-}
-
-function processAdded(node) {
-  if (node.nodeType !== 1) return
-  if (node.matches && node.matches(SELECTOR)) setupVideo(node)
-  if (node.querySelectorAll) node.querySelectorAll(SELECTOR).forEach(setupVideo)
-}
-
-function processRemoved(node) {
-  if (node.nodeType !== 1) return
-  if (node.matches && node.matches(SELECTOR)) {
-    stopPolling(node)
-    elementState.delete(node)
-  }
-  if (node.querySelectorAll) {
-    node.querySelectorAll(SELECTOR).forEach(el => {
-      stopPolling(el)
-      elementState.delete(el)
-    })
-  }
-}
-
-let started = false
-function start() {
-  if (started || typeof document === "undefined") return
-  started = true
-  document.addEventListener("load", onLoad, true)
-  document.addEventListener("error", onError, true)
-  const observer = new MutationObserver(records => {
-    for (const r of records) {
-      r.addedNodes.forEach(processAdded)
-      r.removedNodes.forEach(processRemoved)
-    }
-  })
-  observer.observe(document.documentElement, { childList: true, subtree: true })
-  document.querySelectorAll(SELECTOR).forEach(setupVideo)
-}
-
-function autostart() {
-  if (typeof window === "undefined" || window.ActiveStorageAsyncVariants !== null) start()
-}
-
-if (typeof document !== "undefined") {
-  if (document.readyState === "loading") {
-    document.addEventListener("DOMContentLoaded", autostart)
-  } else {
-    setTimeout(autostart, 1)
-  }
-}
-
-export { start }

data/lib/active_storage/async_variants/representations_redirect_controller_extension.rb

@@ -1,26 +0,0 @@
-# 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