active_storage-async_variants 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f3d828692f86ff7b409b93f3198daae20c5c6821a0cce10da31b625abe7c04be
-  data.tar.gz: '0319ea7873525ea5d76a930e195687b3ba28bebd58922e3fc4aa821238241f28'
+  metadata.gz: 259c11526314988d60e78e9e176dc16105c6aeb578b1774693a666fc1e277a21
+  data.tar.gz: 92fc3546ed708ed709ad4fedc2d7e6258d765719fad75571844671a902f1b485
 SHA512:
-  metadata.gz: 9e80ebc6059bf84853cf7bf05d824ed5d25d5b195a4702d86495cdb29366eb02ee390558768fa66a1f5ea85e8e86987a46f9c7a2492de59e1a7287b25ef7074a
-  data.tar.gz: 23dc024c9a1ceaa334580d32af52f20e4e327f3d40d22e438616bdc0077f5b62f95deb50670ee5a30b3a1e72716e2ef9604bd6eabe2fc3a699aaa21142518ad8
+  metadata.gz: ebfe0839de2603c91a5705f3942b30b3db7685d20ce5d3d2425f98472a191d559ac9103bab5a59972e09f18385b8829283fe0323f2de4810e8619cb57e028ab2
+  data.tar.gz: 165f5796f098a3f40194a9d893ba07b98bd7b3a7ac8601fda744f5dcb1e4a98c0d69e1514e788f612ea8fa1dbf4bca6c44cbb7ee5ef072fcf5fa13fe03ce5b56

data/CHANGELOG.md

@@ -1,3 +1,10 @@
+## [0.7.0]
+
+- **Breaking:** A variant now opts into async processing with `async: true` instead of `processing:`. The `processing:` and `failed:` placeholder options are removed entirely — there is nothing to configure. A variant's `.url` serves the original while pending/processing/failed, and the processed variant once ready.
+- The `async:`-helper UI no longer fetches a placeholder through the representations path on every poll. The processing/failed states render a zero-network sized box with the progress bar floating over it.
+- The failed state now renders the progress bar in its error state (a static red ring with an X, via `@botandrose/progress-bar`'s `error` attribute) rather than a configurable failed SVG. The retry affordance is unchanged.
+- Migration note: replace `processing: <anything>` with `async: true` on each async variant and drop any `failed:` option. Any `:original`/`:blank`/String/Proc placeholder values no longer have an effect.
+
 ## [0.6.0]
 
 - External transforms can now report progress: a `progress` callback records the percent complete and a heartbeat, readable via `#progress` / `#progress_known?` on variants and previews.

data/CLAUDE.md

@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## What This Is
 
-A Rails engine gem that extends Active Storage with async-safe variant processing. Solves the problem where slow transformations (e.g., video transcoding) block requests or fail silently. The `processing:` option on a variant definition opts it into async processing.
+A Rails engine gem that extends Active Storage with async-safe variant processing. Solves the problem where slow transformations (e.g., video transcoding) block requests or fail silently. The `async: true` option on a variant definition opts it into async processing.
 
 ## Commands
 
@@ -19,9 +19,9 @@ bundle exec rspec spec/active_storage/async_variants_spec.rb -e "description" #
 
 The gem works by prepending extension modules onto Active Storage classes:
 
-- **`VariationExtension`** → `ActiveStorage::Variation` — extracts async options (`processing:`, `failed:`, `transformer:`) from variant config before passing the rest to standard Active Storage
-- **`AttachmentExtension`** → `ActiveStorage::Attachment` — hooks into `transform_variants_later` to enqueue `ProcessJob` for variants with `processing:`
-- **`VariantWithRecordExtension`** → `ActiveStorage::VariantWithRecord` — overrides URL generation to serve the `processing:` (or `failed:`) placeholder while not ready; adds state query methods (`processed?`, `processing?`, `pending?`, `failed?`)
+- **`VariationExtension`** → `ActiveStorage::Variation` — extracts async options (`async:`, `transformer:`) from variant config before passing the rest to standard Active Storage
+- **`AttachmentExtension`** → `ActiveStorage::Attachment` — hooks into `transform_variants_later` to enqueue `ProcessJob` for variants with `async: true`
+- **`VariantWithRecordExtension`** → `ActiveStorage::VariantWithRecord` — overrides URL generation to serve the original blob while not ready; adds state query methods (`processed?`, `processing?`, `pending?`, `failed?`)
 - **`ProcessJob`** — background job that determines transformer type (inline vs external) and processes accordingly
 
 ### Transformer Types

data/README.md

@@ -19,7 +19,7 @@ bin/rails db:migrate
 
 ## Usage
 
-Add `processing:` to any named variant to opt into the async pipeline. The value is what to serve while the variant is being processed:
+Add `async: true` to any named variant to opt into the async pipeline:
 
 ```ruby
 class User < ApplicationRecord
@@ -28,12 +28,12 @@ class User < ApplicationRecord
       transformer: VideoTranscoder,
       codec: "vp9",
       resolution: "720p",
-      processing: :original
+      async: true
   end
 end
 ```
 
-The presence of `processing:` is what opts a variant into async processing. Without it, variants behave exactly as they do in standard Active Storage. The `transformer:` option is independent -- you can use a custom transformer synchronously, or use the default transformer asynchronously:
+The presence of `async: true` is what opts a variant into async processing. Without it, variants behave exactly as they do in standard Active Storage. The `transformer:` option is independent -- you can use a custom transformer synchronously, or use the default transformer asynchronously:
 
 ```ruby
 has_one_attached :video do |attachable|
@@ -41,12 +41,12 @@ has_one_attached :video do |attachable|
   attachable.variant :web,
     transformer: VideoTranscoder,
     codec: "vp9",
-    processing: :original
+    async: true
 
   # Async with default transformer (large image resize that's too slow for inline)
   attachable.variant :thumbnail,
     resize_to_limit: [200, 200],
-    processing: :original
+    async: true
 
   # Sync with custom transformer (fast custom processing, no opt-in needed)
   attachable.variant :watermarked,
@@ -60,23 +60,23 @@ In views, use the same Active Storage helpers:
 <%= video_tag user.video.variant(:web).url %>
 ```
 
-If the variant is still processing, this serves the original video. Once processing completes, it serves the transcoded variant.
+While the variant is still processing (or has failed), this serves the original video. Once processing completes, it serves the transcoded variant.
 
 ## `image_tag` / `video_tag` with `async:` and `direct:`
 
-For a polish layer that swaps in placeholder content while a variant is being processed, polls for completion in the background, and optionally serves the finished variant straight from your CDN, the gem adds two options to `image_tag` and `video_tag`:
+For a polish layer that shows a progress bar while a variant is being processed, polls for completion in the background, and optionally serves the finished variant straight from your CDN, the gem adds two options to `image_tag` and `video_tag`:
 
 ```erb
-<%# Variant URL with the async client wired up: spinner while pending,
+<%# Variant URL with the async client wired up: a progress bar while pending,
     polls for completion, swaps to the real image when ready. %>
 <%= image_tag user.avatar.variant(:web), async: true %>
 
 <%# When the variant is ready, render its direct CDN/S3 URL instead of
     routing through Rails. While pending/failed, falls back to the
-    Rails representation URL (which serves the placeholder). %>
+    Rails representation URL (which serves the original). %>
 <%= image_tag user.avatar.variant(:web), direct: true %>
 
-<%# Both together: direct URL once processed, placeholder while pending,
+<%# Both together: direct URL once processed, progress bar while pending,
     polling for completion. %>
 <%= image_tag user.avatar.variant(:web), async: true, direct: true %>
 
@@ -227,31 +227,9 @@ variant.failed?      # => true if permanently failed
 variant.error        # => error message string, or nil
 ```
 
-## Placeholder Options
+## Placeholders
 
-The `processing:` option controls what gets served while a variant is being processed. The `failed:` option (optional) controls what gets served once the variant has permanently failed; if omitted, it defaults to the `processing:` value.
-
-```ruby
-# Serve the original unprocessed file while processing
-attachable.variant :web, processing: :original
-
-# Return nil -- let the view handle it
-attachable.variant :web, processing: :blank
-
-# Static URL while processing
-attachable.variant :web, processing: "/placeholders/processing.svg"
-
-# Dynamic placeholder via Proc
-attachable.variant :web,
-  processing: -> (blob) { "/placeholders/processing.svg" }
-
-# Distinct placeholder when permanently failed
-attachable.variant :web,
-  processing: :original,
-  failed: "/icons/broken.svg"
-```
-
-Both options accept the same set of values: `:original`, `:blank`, a String URL, or a Proc that receives the blob.
+There is nothing to configure. A variant's `.url` serves the original while it is pending, processing, or failed, and the processed variant once ready. With `async: true` on `image_tag`/`video_tag`, the gem instead shows a circular progress bar while processing, and a red error glyph -- the same progress bar in its error state -- once the variant has permanently failed.
 
 ## Failure Handling
 
@@ -276,7 +254,7 @@ variant.error   # => "ffmpeg exited with status 1: ..."
 5. The external service processes the file, uploads the result to the destination URL
 6. The external service POSTs to the callback URL with success/failure status
 7. The gem's callback endpoint transitions the `VariantRecord` to `processed` or `failed`
-8. When a view requests the variant URL, the gem checks state and serves the variant or the `processing:`/`failed:` placeholder
+8. When a view requests the variant URL, the gem checks state and serves the processed variant or, while pending/processing/failed, the original
 
 ### Inline transformer flow
 
@@ -284,7 +262,7 @@ variant.error   # => "ffmpeg exited with status 1: ..."
 4. The job calls the transformer's `process` method, blocking until complete
 5. On success, the output is uploaded, the `VariantRecord` transitions to `processed`
 6. On failure, the error is recorded and the job is re-enqueued (up to 3 attempts)
-7. When a view requests the variant URL, the gem checks state and serves the variant or the `processing:`/`failed:` placeholder
+7. When a view requests the variant URL, the gem checks state and serves the processed variant or, while pending/processing/failed, the original
 
 ## License
 

data/app/assets/javascripts/progress-bar.js

@@ -98,8 +98,13 @@ const STYLES = `
     stroke: var(--indeterminate-color);
   }
 
-  :host([error]) .progress-ring {
+  /* The X of the error glyph; revealed by [error]. */
+  .error-mark {
+    display: none;
+    fill: none;
     stroke: var(--error-color);
+    stroke-width: var(--circular-thickness);
+    stroke-linecap: round;
   }
 
   .label {
@@ -132,6 +137,12 @@ const STYLES = `
     0%   { transform: rotate(-90deg); }
     100% { transform: rotate(270deg); }
   }
+
+  /* Error (circular): static full ring + X. Last so it beats the indeterminate rules. */
+  :host([error]) .track { stroke: var(--error-color); }
+  :host([error]) .progress-ring { display: none; }
+  :host([error]) .ring { animation: none; }
+  :host([error]) .error-mark { display: block; }
 `;
 
 const LINEAR_HTML = `
@@ -144,6 +155,7 @@ const CIRCULAR_HTML = `
     <svg class="ring" viewBox="0 0 100 100">
       <circle class="track" cx="50" cy="50" r="${CIRCLE_RADIUS}"></circle>
       <circle class="progress-ring" cx="50" cy="50" r="${CIRCLE_RADIUS}" pathLength="${PATH_LENGTH}"></circle>
+      <path class="error-mark" d="M37 37 L63 63 M63 37 L37 63"></path>
     </svg>
     <span class="label"><slot></slot></span>
   </div>

data/app/assets/stylesheets/progress.css

@@ -2,19 +2,23 @@
    media box (and the progress bar centered on it) coincides with the parent
    figure box, instead of sitting in a taller line box from the baseline gap --
    otherwise an overlay centered on the figure lands off-center from the ring. */
-turbo-frame:has(> .async-variant-processing) {
+turbo-frame:has(> .async-variant-processing),
+turbo-frame:has(> .async-variant-failed) {
   display: block;
 }
-.async-variant-processing {
+.async-variant-processing,
+.async-variant-failed {
   position: relative;
   display: block;
 }
-/* Present to reserve the processed media's box, but rendered invisible via
-   opacity rather than visibility/display -- so it still has layout and stays
-   queryable by Capybara. The spinner floats over it. block drops the baseline
-   descender so the ring centers on the media, not a few px below it. */
+/* Present to reserve the variant's box, but rendered invisible via opacity
+   rather than visibility/display -- so it still has layout and stays queryable
+   by Capybara. The progress bar floats over it. block drops the baseline
+   descender so the ring centers on the box, not a few px below it. */
 .async-variant-processing img,
-.async-variant-processing video {
+.async-variant-processing video,
+.async-variant-failed img,
+.async-variant-failed video {
   opacity: 0.001;
   display: block;
 }
@@ -27,4 +31,5 @@ turbo-frame:has(> .async-variant-processing) {
   --progress-color: #2E7D32;
   --indeterminate-color: #2E7D32;
   --track-color: rgba(0, 0, 0, 0.25);
+  --error-color: #ff7c81;
 }

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

@@ -1,16 +1,17 @@
 <div class="async-variant-state async-variant-failed">
-  <%= image_tag async_variant_representation_path(variant), **html_options.symbolize_keys.except(:controls, :autoplay, :preload) %>
+  <%= async_variant_placeholder_tag(variant, html_options, kind: kind) %>
+
+  <%= content_tag "progress-bar", "", mode: "circular", error: "", class: "async-variant-progress" %>
+
+  <%= ActiveStorage::AsyncVariants.stylesheet_link_tag "progress" %>
+  <%= ActiveStorage::AsyncVariants.javascript_include_tag "progress-bar", type: "module" %>
 
   <% 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 { --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

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 %>
+  <%= async_variant_placeholder_tag(variant, html_options, kind: kind) %>
 
   <%= content_tag "progress-bar", "", mode: "circular", class: "async-variant-progress", percent: variant.progress %>
 </div>

data/features/state_rendering.feature

@@ -37,3 +37,4 @@ Feature: image_tag with async: true emits the right markup per variant 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 failed state
+    And the frame should render an error progress bar

data/features/step_definitions/dummy_steps.rb

@@ -24,6 +24,10 @@ Then /^the frame should render a progress bar$/ do
   expect(page).to have_css("turbo-frame progress-bar", visible: :all)
 end
 
+Then /^the frame should render an error progress bar$/ do
+  expect(page).to have_css("turbo-frame progress-bar[error]", visible: :all)
+end
+
 Then /^the progress bar should be indeterminate$/ do
   expect(page).to have_css("turbo-frame progress-bar:not([percent])", visible: :all)
 end

data/lib/active_storage/async_variants/attachment_extension.rb

@@ -14,7 +14,7 @@ module ActiveStorage
         return unless blob.bucket_backed?
 
         named_variants.each do |name, named_variant|
-          next unless named_variant.transformations.key?(:processing)
+          next unless named_variant.transformations.key?(:async)
 
           ActiveStorage::AsyncVariants::ProcessJob.perform_later(
             record, self.name, name.to_s,

data/lib/active_storage/async_variants/helper.rb

@@ -7,6 +7,25 @@ module ActiveStorage
     # `helper ActiveStorage::AsyncVariants::Helper` (so the state partials can
     # use them).
     module Helper
+      # 1x1 transparent GIF: reserves the variant's box without fetching the
+      # original through the representations path on every poll.
+      PLACEHOLDER_SRC = "data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7"
+
+      def async_variant_placeholder_tag(variant, html_options = {}, kind: :image)
+        opts = async_variant_box_dimensions(variant)
+          .merge(html_options.symbolize_keys.except(:src, :controls, :autoplay, :preload, :poster))
+        # A video placeholder carries no <source>, so it reserves the box
+        # without loading anything -- same zero-network intent as the GIF.
+        kind == :video ? content_tag(:video, "", opts) : image_tag(PLACEHOLDER_SRC, opts)
+      end
+
+      def async_variant_box_dimensions(variant)
+        resize = variant.variation.transformations
+          .values_at(:resize_to_limit, :resize_to_fit, :resize_to_fill)
+          .compact.first
+        resize.is_a?(Array) ? { width: resize[0], height: resize[1] } : {}
+      end
+
       # 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

data/lib/active_storage/async_variants/preview_extension.rb

@@ -67,15 +67,15 @@ module ActiveStorage
       private
 
       def async_preview?
-        resolved_async_options[:transformer].present?
+        resolved_async_options[:async].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).
+      # :async / :transformer 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 ||
@@ -90,7 +90,7 @@ module ActiveStorage
           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?
+            return [attachment, name, candidate.variation.async_options] if candidate.variation.async_options[:async]
           end
         end
         nil
@@ -107,25 +107,9 @@ module ActiveStorage
         blob.variant_records.find_by(variation_digest: variation.digest)
       end
 
+      # Serve the original until the preview variant is processed.
       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"
+        blob.url(...)
       end
     end
   end

data/lib/active_storage/async_variants/reflection_extension.rb

@@ -7,7 +7,7 @@ module ActiveStorage
     #
     #   has_one_attached :avatar do |attachable|
     #     attachable.variant :thumb, resize_to_limit: [150, 150], format: "webp",
-    #       transformer: Crucible, processing: "/spinner.svg"
+    #       transformer: Crucible, async: true
     #   end
     #
     # Without this, the Registry only warms when view-side code calls

data/lib/active_storage/async_variants/registry.rb

@@ -7,7 +7,7 @@ module ActiveStorage
     # 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
+    # constructed with :async 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.

data/lib/active_storage/async_variants/variant_record_extension.rb

@@ -13,8 +13,8 @@ module ActiveStorage
 
       # 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.).
+      # render sees the new state (swaps the processing box for the failed
+      # error state, swaps src to the direct CDN URL, etc.).
       def reached_terminal_state?
         saved_change_to_state? && %w[processed failed].include?(state)
       end

data/lib/active_storage/async_variants/variant_with_record_extension.rb

@@ -27,15 +27,8 @@ module ActiveStorage
       end
 
       def url(...)
-        if blob.bucket_backed? && !processed?
-          fallback = active_fallback
-          case fallback
-          when :original then blob.url(...)
-          when :blank then nil
-          when Proc then fallback.call(blob)
-          when String then fallback
-          else super
-          end
+        if blob.bucket_backed? && async_variant? && !processed?
+          blob.url(...)
         else
           super
         end
@@ -84,6 +77,10 @@ module ActiveStorage
 
       private
 
+      def async_variant?
+        resolved_async_options[:async].present?
+      end
+
       def resolved_async_options
         @resolved_async_options ||=
           variation.async_options.presence ||
@@ -92,14 +89,6 @@ module ActiveStorage
           {}
       end
 
-      def active_fallback
-        if failed?
-          resolved_async_options.fetch(:failed) { resolved_async_options[:processing] }
-        else
-          resolved_async_options[:processing]
-        end
-      end
-
       # 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
@@ -126,7 +115,7 @@ module ActiveStorage
           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?
+              return [attachment, name, candidate.variation.async_options] if candidate.variation.async_options[:async]
             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[processing failed transformer].freeze
+      ASYNC_KEYS = %i[async transformer].freeze
 
       def initialize(transformations)
         if transformations.is_a?(Hash)
@@ -13,7 +13,7 @@ module ActiveStorage
           @async_options = {}
           super
         end
-        ActiveStorage::AsyncVariants::Registry.register(digest, @async_options) if @async_options[:processing].present?
+        ActiveStorage::AsyncVariants::Registry.register(digest, @async_options) if @async_options[:async]
       end
 
       def async_options

data/lib/active_storage/async_variants/version.rb

@@ -2,6 +2,6 @@
 
 module ActiveStorage
   module AsyncVariants
-    VERSION = "0.6.0"
+    VERSION = "0.7.0"
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: active_storage-async_variants
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Micah Geisel
 bindir: exe
 cert_chain: []
-date: 2026-06-07 00:00:00.000000000 Z
+date: 2026-06-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activestorage