active_storage-async_variants 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 003cbfe68ded6c238669546679e76b7d0c8e856842450181ceb8497a9e452361
-  data.tar.gz: 0b41dad0aa8a59e81e9b2e384d6d04e55ee479c0c35822d71e3a06a46b0c64cd
+  metadata.gz: bc926d64601c238db11edd005f220c0842cbf4316f405d43c23d08a99ff874de
+  data.tar.gz: 177a3d4a3647e41ac5e23db1908265c556a8c4c006b5497cbb802b2cf9ebb02e
 SHA512:
-  metadata.gz: e5eb0728baf9f4d9cfc591625f6035d362d9df192c2c64fb7cef4e397fcef9817a460dbfba24210f01d777360a1d2e73e4dabf7d00306f8c9685ff1df4641b0e
-  data.tar.gz: 4c87c749a9dad93f251fcddf5830996f53d7c054becabdd529ea89000eb75e5f2360b6332aea764fc615931b0c350a15bfe8610d4b5efa1561a22ffd3d966ee6
+  metadata.gz: 25f4d2430ce2547c9a4109bd648f338914e92cacdb38bf2e651cdfff21a9a045e90480c10e6170f0723dbcb5e675a35370cda7c91ced43ec41c5bfa3f112f2a1
+  data.tar.gz: c02fac50058fd3465435bf194e09ffb0732deda2c61316b8e960b1179e4ee8e9eb417e1dd192fdf564c0e059d87a674fe76aa852f99a385592ddfcd71fb1a453

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+## [0.5.0]
+
+- Added an opt-in retry affordance to the failed state: hovering a failed variant reveals a control that opens a dialog with the error and a "Retry processing" button that re-runs the transform. Disabled by default; enable it with `ActiveStorage::AsyncVariants.retry_visible_if { … }` (the block runs in the view context, so it can check `current_user`).
+
 ## [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.

data/app/assets/javascripts/retry.js

@@ -0,0 +1,11 @@
+// Declarative shadow roots are only attached by the initial HTML parser, not by
+// fragment insertion (innerHTML / Turbo frame swaps), so promote them on connect.
+customElements.define("async-variant-retry", class extends HTMLElement {
+  connectedCallback() {
+    if (this.shadowRoot) return
+    const template = this.querySelector(":scope > template[shadowrootmode]")
+    if (!template) return
+    this.attachShadow({ mode: template.getAttribute("shadowrootmode") }).append(template.content)
+    template.remove()
+  }
+})

data/app/assets/stylesheets/retry.css

@@ -0,0 +1,98 @@
+/* Scoped to the retry dialog's shadow root (linked inside its <template>). */
+:host { display: contents; }
+
+button { font: inherit; cursor: pointer; }
+
+.opener {
+  position: absolute;
+  top: 6px; right: 6px;
+  width: 22px; height: 22px;
+  background: #2b7cd6;
+  color: #fff;
+  border: 2px solid #fff;
+  border-radius: 50%;
+  font-size: 13px;
+  font-weight: bold;
+  line-height: 1;
+  padding: 0;
+  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.35);
+  display: var(--retry-opener-display, none);
+  align-items: center;
+  justify-content: center;
+}
+.opener:hover { background: #1a5fb0; }
+
+dialog {
+  width: 720px;
+  max-width: 90vw;
+  max-height: 80vh;
+  padding: 0;
+  border: 1px solid #999;
+  border-radius: 6px;
+  background: #fff;
+  color: #222;
+  box-shadow: 0 8px 32px rgba(0, 0, 0, 0.3);
+  font: 13px/1.4 system-ui, -apple-system, sans-serif;
+}
+dialog[open] { display: flex; flex-direction: column; }
+dialog::backdrop { background: rgba(0, 0, 0, 0.5); }
+
+dialog > button {
+  position: absolute;
+  top: 10px;
+  right: 12px;
+  width: 32px; height: 32px;
+  background: transparent;
+  border: none;
+  color: #888;
+  font-size: 24px;
+  line-height: 1;
+  padding: 0;
+  border-radius: 4px;
+  z-index: 1;
+}
+dialog > button:hover { color: #000; background: rgba(0, 0, 0, 0.08); }
+
+header { padding: 20px 24px 0 24px; }
+header h3 {
+  margin: 0;
+  font-size: 16px;
+  font-weight: bold;
+  color: #111;
+  padding-right: 32px;
+}
+
+section {
+  flex: 1 1 auto;
+  overflow: auto;
+  padding: 12px 24px 20px 24px;
+  min-height: 0;
+}
+section pre {
+  background: #f5f5f5;
+  color: #222;
+  border: 1px solid #ddd;
+  padding: 8px;
+  font: 11px/1.4 ui-monospace, Menlo, monospace;
+  white-space: pre-wrap;
+  word-break: break-all;
+  margin: 0;
+}
+
+footer {
+  flex: 0 0 auto;
+  border-top: 1px solid #ddd;
+  padding: 12px 20px;
+  display: flex;
+  justify-content: flex-end;
+  background: #fafafa;
+}
+footer button {
+  padding: 8px 16px;
+  background: #2a7;
+  color: #fff;
+  border: none;
+  border-radius: 4px;
+  font-weight: bold;
+}
+footer button:disabled { opacity: 0.5; cursor: wait; }

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

@@ -16,6 +16,22 @@ module ActiveStorage
       def show
       end
 
+      def retry
+        @variant.blob.variant_records.where(
+          variation_digest: @variant.variation.digest,
+          state: "failed",
+        ).destroy_all
+        @variant.enqueue!
+
+        redirect_to Rails.application.routes.url_helpers.async_variant_state_path(
+          signed_blob_id: params[:signed_blob_id],
+          variation_key: params[:variation_key],
+          kind: params[:kind],
+          direct: params[:direct],
+          opts: async_variant_html_options.presence,
+        ), status: :see_other
+      end
+
       helper_method :async_variant_kind, :async_variant_direct?, :async_variant_html_options
 
       private

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

@@ -1,4 +1,43 @@
 <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 %>
+  <%= image_tag async_variant_representation_path(variant), **html_options.symbolize_keys.except(:controls, :autoplay, :preload) %>
+
+  <% if ActiveStorage::AsyncVariants.retry_visible?(self) %>
+    <% dialog_id = "#{async_variant_frame_id(variant)}-error" %>
+    <% form_id = "#{dialog_id}-form" %>
+    <%# Light DOM, so the custom property inherits into the shadow root. %>
+    <style>
+      .async-variant-failed {
+        position: relative;
+        display: inline-block;
+        --retry-opener-display: none;
+      }
+      .async-variant-failed:hover { --retry-opener-display: inline-flex; }
+    </style>
+    <%# In the light DOM so its submit reaches Turbo, and so preventDefault on the
+        buttons doesn't also cancel the submit. %>
+    <form action="<%= Rails.application.routes.url_helpers.async_variant_state_retry_path(signed_blob_id:, variation_key:, kind:, direct:, opts: html_options) %>"
+          method="post"
+          id="<%= form_id %>"
+          data-turbo-frame="<%= async_variant_frame_id(variant) %>"
+          hidden></form>
+    <async-variant-retry>
+      <template shadowrootmode="open">
+        <%= ActiveStorage::AsyncVariants.stylesheet_link_tag "retry" %>
+        <button class="opener" type="button"
+                onclick="event.preventDefault(); event.stopPropagation(); this.getRootNode().getElementById('<%= dialog_id %>').showModal()"
+                title="Variant processing failed — click for details">?</button>
+        <dialog id="<%= dialog_id %>">
+          <button type="button"
+                  onclick="event.preventDefault(); event.stopPropagation(); this.closest('dialog').close()">&times;</button>
+          <header><h3>Variant processing failed</h3></header>
+          <section><pre><%= variant.error %></pre></section>
+          <footer>
+            <button type="button"
+                    onclick="event.preventDefault(); event.stopPropagation(); this.disabled = true; this.textContent = 'Retrying…'; document.getElementById('<%= form_id %>').requestSubmit()">Retry processing</button>
+          </footer>
+        </dialog>
+      </template>
+    </async-variant-retry>
+    <%= ActiveStorage::AsyncVariants.javascript_include_tag "retry", type: "module" %>
+  <% end %>
 </div>

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

@@ -1,6 +1,5 @@
 <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 %>
+  <%= image_tag async_variant_representation_path(variant), **html_options.symbolize_keys.except(:controls, :autoplay, :preload) %>
 </div>
 <%# Self-perpetuating poll: Turbo runs <script>s in frame swaps, so each
     pending/processing response schedules its own next reload. Terminal

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

@@ -4,5 +4,7 @@
     html_options: async_variant_html_options,
     kind: async_variant_kind,
     direct: async_variant_direct?,
+    signed_blob_id: params[:signed_blob_id],
+    variation_key: params[:variation_key],
   } %>
 <% end %>

data/config/routes.rb

@@ -8,4 +8,9 @@ Rails.application.routes.draw do
   get  "/active_storage/async_variants/states/:signed_blob_id/:variation_key",
     to: "active_storage/async_variants/states#show",
     as: :async_variant_state
+  post "/active_storage/async_variants/states/:signed_blob_id/:variation_key/retry",
+    to: "active_storage/async_variants/states#retry",
+    as: :async_variant_state_retry
+
+  ActiveStorage::AsyncVariants::Assets.draw(self, "/active_storage/async_variants/assets")
 end

data/features/retry_flow.feature

@@ -0,0 +1,20 @@
+Feature: Clicking the retry affordance opens a dialog and resubmits the variant
+
+  Background:
+    Given a user with an attached avatar
+    And the retry affordance is visible to everyone
+
+  Scenario: Clicking the opener reveals the error inside the shadow-DOM dialog
+    Given the avatar's :thumb_proc variant is in failed state with error "boom from upstream"
+    When I visit the avatar page for the :thumb_proc variant
+    And I click the retry opener
+    Then the failure dialog should be open
+    And the failure dialog should contain "boom from upstream"
+
+  Scenario: Submitting Retry destroys the failed record and re-enqueues
+    Given the avatar's :thumb_proc variant is in failed state with error "boom"
+    When I visit the avatar page for the :thumb_proc variant
+    And I click the retry opener
+    And I click "Retry processing"
+    Then the frame should render the processing state
+    And the page should not have navigated away

data/features/retry_visibility.feature

@@ -0,0 +1,23 @@
+Feature: The retry affordance is gated by ActiveStorage::AsyncVariants.retry_visible_if
+
+  Scenario: When retry_visible_if returns true, the retry chrome renders
+    Given a user with an attached avatar
+    And the retry affordance is visible to everyone
+    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 retry affordance should be visible
+
+  Scenario: When retry_visible_if returns false, the retry chrome is omitted
+    Given a user with an attached avatar
+    And the retry affordance is hidden
+    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 retry affordance should NOT be visible
+
+  Scenario: A proc that consults current_user gates the affordance per-viewer
+    Given a user with an attached avatar
+    And the retry affordance requires a signed-in user
+    And the avatar's :thumb_proc variant is in failed state with error "boom"
+    When I sign in as the user
+    And I visit the avatar page for the :thumb_proc variant
+    Then the retry affordance should be visible

data/features/state_rendering.feature

@@ -15,6 +15,7 @@ Feature: image_tag with async: true emits the right markup per variant state
 
   Scenario: A failed variant renders the failed partial inside the frame
     Given a user with an attached avatar
+    And the retry affordance is visible to everyone
     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

data/gemfiles/rails_7.2.gemfile

@@ -10,5 +10,9 @@ gem "simplecov", require: false
 gem "rspec-rails"
 gem "rails", "~> 7.2.0"
 gem "sqlite3"
+gem "cucumber"
+gem "capybara"
+gem "cuprite"
+gem "puma"
 
 gemspec path: "../"

data/gemfiles/rails_8.0.gemfile

@@ -10,5 +10,9 @@ gem "simplecov", require: false
 gem "rspec-rails"
 gem "rails", "~> 8.0.0"
 gem "sqlite3"
+gem "cucumber"
+gem "capybara"
+gem "cuprite"
+gem "puma"
 
 gemspec path: "../"

data/gemfiles/rails_8.1.gemfile

@@ -10,5 +10,9 @@ gem "simplecov", require: false
 gem "rspec-rails"
 gem "rails", "~> 8.1.0"
 gem "sqlite3"
+gem "cucumber"
+gem "capybara"
+gem "cuprite"
+gem "puma"
 
 gemspec path: "../"

data/lib/active_storage/async_variants/asset_tag_helper_extension.rb

@@ -33,10 +33,7 @@ module ActiveStorage
         assert_async_variant!(variant)
 
         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
+          async_variant_turbo_frame(variant, kind:, direct:, html_options: options)
         else
           yield [async_variant_resolved_src(variant, direct:), *rest], options
         end
@@ -48,13 +45,13 @@ module ActiveStorage
         end
       end
 
-      def async_variant_turbo_frame(variant, kind:, direct:, html_options:, &block)
+      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",
-          &block
         )
       end
     end

data/lib/active_storage/async_variants/version.rb

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

data/lib/active_storage/async_variants.rb

@@ -1,6 +1,7 @@
 # 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"
@@ -22,12 +23,24 @@ module ActiveStorage
     PASS_THROUGH_HTML_OPTIONS = %i[alt width height controls autoplay preload].freeze
 
     mattr_accessor :cdn_host
+    mattr_accessor :retry_visible_proc, default: ->(_view) { false }
 
     # 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
@@ -79,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.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Micah Geisel
 bindir: exe
 cert_chain: []
-date: 2026-06-06 00:00:00.000000000 Z
+date: 2026-06-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activestorage
@@ -37,6 +37,20 @@ dependencies:
     - - ">="
       - !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: []
@@ -52,6 +66,8 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- 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
@@ -60,6 +76,8 @@ files:
 - 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