active_storage-async_variants 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d60acebdeb8fe9482d73576e79abb4737fb052e6df939e09829b9c0e766b9e12
-  data.tar.gz: 68be3b6ef1f9cb34e5a08f87b20470520367e16fdcc81ec73f18d5956ab8979a
+  metadata.gz: fffff13cd7b602bc0139ae60dff32c4d38d573b738edaa244f21df5dfa331723
+  data.tar.gz: 1251c74b70fd15eaaf1e48e494b7fc9d773f2989f83e1b99ca6862fdaec6c144
 SHA512:
-  metadata.gz: a3fc174236833deeda757d08b0f8ff68769d5130beb7b3f20fd68082e73aa72ac2a088fd23fad45209cd9849caa9d0293ec5f9f11bd365dec3e6d995a5b79fb0
-  data.tar.gz: 7944a7832431949722581b13f62c99b785df7abfaf7693ea236213df1a08e730d9070bce1465ea32255b29423dc393d30bfd61f9b72cf2bdc39b48010bcd806d
+  metadata.gz: 2bfef2ba7b3d4576d20a867095c7e75f8f36ab122d0718901856ce0bab8330521f5edeb73a0e75a12f3ed20250fe28c25304b4823929167daa910d240a7b9477
+  data.tar.gz: f0e5e7a9cfe3d75ff7afe960fc7675447b466dc6e8500b7db6fca3c6a24cd8d0dfa837e938b216898a8ee8d95f470c1aa80b03be7c407e8e0ee7a63a46d74775

data/CHANGELOG.md

@@ -1,3 +1,20 @@
+## [0.10.0]
+
+- **Breaking:** Async previews now persist the same graph stock Active Storage builds. For a previewable blob (a video), an image-format variant is a `Preview`: the extracted frame is attached as the source blob's `preview_image`, and the variant record hangs off the *frame* blob, not the source. `ProcessJob` resolves the attachment's `representation` and takes the preview path when stock would. External transformers receive a frame placeholder (`byte_size: 0, checksum: "0"`) to write into; the success callback reconciles both placeholders. Read video stills through `representation`/`preview`, not `variant`.
+- **Breaking:** Naming a `transformer:` is now the only async opt-in. The `async:` option is gone and raises `ArgumentError`. The built-in `ActiveStorage::AsyncVariants::Standard` transformer replaces a bare `async: true` (the stock variant pipeline, run in the background). A transformer's kind follows from what it overrides: `Transformer#standard?` (neither), `#inline?` (`process`), `#external?` (`initiate`).
+- **Breaking:** Attaching a file enqueues an async variant only when it declares Active Storage's `preprocessed:` option (`true`, a method name, or a proc evaluated against the record). Previously every variant naming a `transformer:` was enqueued on every attach, whatever the file — so an image upload also ran the attachment's video transcode. Stock Active Storage no longer sees async variants when preprocessing, so `preprocessed: true` never also queues a `TransformJob` or a local `PreviewImageJob`.
+- Migration note: existing variant records for video stills live on the source blob under the old structure. Move them onto the frame blob (`UPDATE active_storage_variant_records SET blob_id = <frame>`), attaching a placeholder frame where none exists; the `variation_digest` is unchanged. Records whose output is itself a video (transcodes) stay on the source. Replace `async: true` with `transformer: ActiveStorage::AsyncVariants::Standard` where no transformer was named, and drop it where one was. Add `preprocessed: true` (or a condition) to each async variant that should process on attach.
+- `Preview` speaks the same progress protocol as `VariantWithRecord`: `async_state`, `progress`, `progress_known?`, `progress_rate`, `last_heartbeat_at`, `error`.
+- `async_record` is public on both `VariantWithRecord` and `Preview`, and both gain `retry!` (drop a failed record, then `enqueue!`), so callers need not know where a representation keeps its record.
+- `NamedVariantScan` compares declarations structurally instead of instantiating `attachment.variant`, which raises for videos.
+- Fix: declaring `preprocessed:` alongside a `transformer:` no longer breaks the declaration-time registry warm-up (a proc raised on `Marshal.dump`; other values registered the wrong digest).
+- MirrorService: the success callback mirrors reconciled variant blobs to the mirrors, as Rails does for direct uploads, and `bucket_backed?` resolves through the primary service.
+- Frame placeholder creation is serialized on the blob row: every image variant of one video reaches it concurrently, and a second `preview_image` attachment would be invisible to `has_one`, stranding the records hanging off it.
+- Ships the `state`/`error`/`attempts` migration for `active_storage_variant_records` (guarded with `if_not_exists`, so apps that added the columns themselves can install it harmlessly), and builds the test schema from `db/migrate` so a missing shipped migration fails the suite.
+- Fix: `ProcessJob` skips a variant record that is already processed or whose run is still heartbeating. Previously every enqueue re-dispatched the variant — attaching an already-processed blob to another record, a retry, or a duplicate job paid for a second render and flipped processed media back to processing.
+- Fix: the success callback applies the reported `byte_size` and `checksum` whenever they arrive, not only over the `0`/`"0"` placeholders, since a re-render writes over the record's existing output blob. Reported `preview_image_*` values land only on a frame, never on a variant's source blob.
+- Fix: destroying a variant record purges any output a racing render attached after the destroy read its attachments, so a purged source no longer leaves outputs pointing at a deleted record.
+
 ## [0.9.0]
 
 - **Breaking:** Split the opinionated UI out into a separate gem, [`active_storage-async_variants-ui`](https://github.com/botandrose/active_storage-async_variants-ui). This gem is now UI-free plumbing — the async state machine, `ProcessJob`, the heartbeat watchdog, the external-service callback endpoint, and the `Transformer` base class. Its only runtime dependency is `activestorage` (no more `turbo-rails` / `isolate_assets`).

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 `async: true` 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. Naming a `transformer:` on a variant definition opts it into async processing.
 
 ## Commands
 
@@ -19,17 +19,23 @@ 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 (`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`
+- **`VariationExtension`** → `ActiveStorage::Variation` — extracts the `transformer:` option from variant config before passing the rest to standard Active Storage
+- **`AttachmentExtension`** → `ActiveStorage::Attachment` — hooks into `transform_variants_later` to enqueue `ProcessJob` for async variants whose `preprocessed:` holds for the record, hiding async variants from stock preprocessing
 - **`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
+- **`PreviewExtension`** → `ActiveStorage::Preview` — blocks the synchronous preview transform for async variants and resolves state/URLs through the stock preview graph
+- **`ProcessJob`** — background job that resolves the attachment's representation (variant vs preview), determines transformer type (inline vs external), and processes accordingly
+
+### Preview Structure
+
+Async previews persist the same graph stock Active Storage builds: the extracted frame is attached as the source blob's `preview_image`, and the variant record hangs off the *frame* blob, not the source. External transformers get a frame placeholder (`byte_size: 0, checksum: "0"`) the service writes into; the success callback reconciles both the variant and frame placeholders. Inline/default transformers extract the real frame up front via the stock previewer.
 
 ### Transformer Types
 
-- **Inline**: implements `process(file, **options)` → blocks worker, returns `{ io:, content_type:, filename: }`
-- **External**: implements `initiate(source_url:, destination_url:, callback_url:, **options)` → frees worker immediately, external service POSTs to callback URL when done
+Naming a `transformer:` is the async opt-in; the kind is determined by what the transformer overrides (`Transformer#standard?`/`#inline?`/`#external?`):
 
-The gem detects which type by checking if `process` is overridden on the transformer class.
+- **Standard** (`ActiveStorage::AsyncVariants::Standard`): overrides neither → runs the stock Active Storage variant pipeline in the background. Replaces the old bare `async: true` (no transformer) declaration, which now raises.
+- **Inline**: overrides `process(file, **options)` → blocks worker, returns `{ io:, content_type:, filename: }`
+- **External**: overrides `initiate(source_url:, callback_url:, **options)` → frees worker immediately, external service POSTs to callback URL when done
 
 ### Callback Endpoint
 

data/README.md

@@ -21,7 +21,7 @@ bin/rails db:migrate
 
 ## Usage
 
-Add `async: true` to any named variant to opt into the async pipeline:
+Name a `transformer:` on any variant to opt it into the async pipeline:
 
 ```ruby
 class User < ApplicationRecord
@@ -29,33 +29,49 @@ class User < ApplicationRecord
     attachable.variant :web,
       transformer: VideoTranscoder,
       codec: "vp9",
-      resolution: "720p",
-      async: true
+      resolution: "720p"
   end
 end
 ```
 
-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:
+The presence of a `transformer:` is what opts a variant into async processing. Without it, variants behave exactly as they do in standard Active Storage. The transformer also says *how* the work happens — there are three kinds, distinguished by what they implement:
 
 ```ruby
 has_one_attached :video do |attachable|
-  # Async with custom transformer (video transcode)
+  # External: hands off to a remote service (implements #initiate)
   attachable.variant :web,
     transformer: VideoTranscoder,
-    codec: "vp9",
-    async: true
+    codec: "vp9"
 
-  # Async with default transformer (large image resize that's too slow for inline)
+  # Standard: the stock Active Storage variant pipeline, run in the background
+  # (e.g. a large image resize that's too slow for an inline request)
   attachable.variant :thumbnail,
     resize_to_limit: [200, 200],
-    async: true
+    transformer: ActiveStorage::AsyncVariants::Standard
 
-  # Sync with custom transformer (fast custom processing, no opt-in needed)
+  # Inline: custom processing in the worker (implements #process)
   attachable.variant :watermarked,
     transformer: WatermarkStamper
 end
 ```
 
+A variant with no `transformer:` is a plain synchronous Active Storage variant — the gem stays out of the way.
+
+### Processing on attach
+
+An async variant is processed when a file is attached only if it says so with Active Storage's own `preprocessed:` option. It takes `true`, a method name, or a proc, evaluated against the record — so one attachment that accepts both images and videos can transcode only the videos:
+
+```ruby
+has_one_attached :media do |attachable|
+  attachable.variant :thumb, resize_to_limit: [150, 150], format: "webp",
+    transformer: Crucible, preprocessed: true
+  attachable.variant :transcoded, resize_to_limit: [1280, 720], format: "mp4",
+    transformer: Crucible, preprocessed: :video?
+end
+```
+
+An async variant without `preprocessed:` is never enqueued on attach; call `enqueue!` on it when you want it. Stock Active Storage never preprocesses an async variant itself — the gem's `ProcessJob` is the only thing that does.
+
 In views, use the same Active Storage helpers:
 
 ```erb
@@ -205,7 +221,7 @@ variant.error   # => "ffmpeg exited with status 1: ..."
 ### External transformer flow
 
 1. User uploads a file to an attachment that has async variants defined
-2. After attachment, a background job is enqueued for each async variant
+2. After attachment, a background job is enqueued for each async variant whose `preprocessed:` holds for the record
 3. `VariantRecord` is created with state `pending`
 4. The job calls the transformer's `initiate` method with presigned source/destination URLs and a signed callback URL, then exits -- the worker is free
 5. The external service processes the file, uploads the result to the destination URL

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

@@ -4,9 +4,6 @@ module ActiveStorage
   module AsyncVariants
     class CallbacksController < ActionController::API
       def create
-        variant_record_id = ActiveStorage.verifier.verify(params[:token], purpose: :async_variant_callback)
-        variant_record = ActiveStorage::VariantRecord.find(variant_record_id)
-
         case params[:status]
         when "success"
           variant_record.update!(state: "processed")
@@ -29,33 +26,45 @@ module ActiveStorage
 
       private
 
-      # External transformers (Crucible) write the file directly to the bucket
-      # and report its byte_size/checksum on the success callback. Reconcile the
-      # placeholder blobs created with byte_size: 0, checksum: "0" -- the variant
-      # itself, and (for video previews) the extracted frame on the source blob.
+      def variant_record
+        @variant_record ||= begin
+          variant_record_id = ActiveStorage.verifier.verify(params[:token], purpose: :async_variant_callback)
+          ActiveStorage::VariantRecord.find(variant_record_id)
+        end
+      end
+
       def apply_reported_metadata(variant_record, params)
         reconcile(variant_record.image.blob, params[:byte_size], params[:checksum])
-        reconcile(variant_record.blob, params[:preview_image_byte_size], params[:preview_image_checksum])
+        if frame?(variant_record.blob)
+          reconcile(variant_record.blob, params[:preview_image_byte_size], params[:preview_image_checksum])
+        end
       end
 
-      # The placeholder sentinels (byte_size 0, checksum "0") gate each field, so
-      # this is idempotent and never overwrites a real source blob's metadata.
+      # A re-render writes over a reused blob, so the reported values describe the object now stored.
       def reconcile(blob, byte_size, checksum)
         return unless blob
 
-        attrs = {}
-        if (bytes = positive_int(byte_size)) && blob.byte_size.zero?
-          attrs[:byte_size] = bytes
+        if positive_int?(byte_size)
+          blob.byte_size = byte_size
         end
-        if checksum.present? && checksum != "0" && blob.checksum == "0"
-          attrs[:checksum] = checksum
+        if checksum.present?
+          blob.checksum = checksum
         end
-        blob.update!(attrs) if attrs.any?
+        blob.save!
+
+        if blob.checksum != "0"
+          blob.mirror_later
+        end
+      end
+
+      # preview_image_* must never land on a variant's source blob.
+      def frame?(blob)
+        blob.checksum == "0" ||
+          ActiveStorage::Attachment.exists?(record_type: "ActiveStorage::Blob", name: "preview_image", blob_id: blob.id)
       end
 
-      def positive_int(value)
-        int = value.to_i
-        int.positive? ? int : nil
+      def positive_int?(value)
+        value.to_i.positive?
       end
     end
   end

data/db/migrate/20260304000001_add_state_columns_to_variant_records.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+class AddStateColumnsToVariantRecords < ActiveRecord::Migration[7.2]
+  def change
+    add_column :active_storage_variant_records, :state, :string, default: "pending", if_not_exists: true
+    add_column :active_storage_variant_records, :error, :text, if_not_exists: true
+    add_column :active_storage_variant_records, :attempts, :integer, default: 0, if_not_exists: true
+  end
+end

data/lib/active_storage/async_variants/attachment_extension.rb

@@ -5,22 +5,39 @@ module ActiveStorage
     module AttachmentExtension
       private
 
+      # Stock would also preprocess an async variant: a TransformJob, or a PreviewImageJob that runs the local previewer.
       def transform_variants_later
-        super
+        without_async_variants { super }
         enqueue_async_variant_jobs
       end
 
+      def named_variants
+        return super unless @without_async_variants
+        super.reject { |_name, named_variant| async_variant?(named_variant) }
+      end
+
+      def without_async_variants
+        @without_async_variants = true
+        yield
+      ensure
+        @without_async_variants = false
+      end
+
       def enqueue_async_variant_jobs
         return unless blob.bucket_backed?
 
         named_variants.each do |name, named_variant|
-          next unless named_variant.transformations.key?(:async)
+          next unless async_variant?(named_variant) && named_variant.preprocessed?(record)
 
           ActiveStorage::AsyncVariants::ProcessJob.perform_later(
             record, self.name, name.to_s,
           )
         end
       end
+
+      def async_variant?(named_variant)
+        named_variant.transformations.key?(:transformer)
+      end
     end
   end
 end

data/lib/active_storage/async_variants/blob_extension.rb

@@ -7,8 +7,10 @@ module ActiveStorage
       # processing workers (Crucible, etc.) can reach via presigned URLs. The
       # Disk and Test services return false; the gem then defers to vanilla
       # ActiveStorage rather than trying to enqueue jobs or serve fallbacks.
+      # MirrorService doesn't delegate :bucket, so resolve through its primary.
       def bucket_backed?
-        service.respond_to?(:bucket)
+        resolved = service.respond_to?(:primary) ? service.primary : service
+        resolved.respond_to?(:bucket)
       end
     end
   end

data/lib/active_storage/async_variants/named_variant_scan.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module ActiveStorage
+  module AsyncVariants
+    # Finds the async named-variant declaration whose transformations match a
+    # variation, starting from a blob's attachments. Used to recover the
+    # :transformer option when the Registry is cold, and by
+    # Preview/VariantWithRecord enqueue paths to locate the attachment to
+    # dispatch ProcessJob against.
+    #
+    # Walks one level up through a preview_image attachment so a lookup from a
+    # video's extracted frame still finds the named variant declared on the
+    # parent record's source-video field.
+    #
+    # Candidates are compared structurally (order-insensitive, JSON-normalized)
+    # against the declared transformations, never by instantiating
+    # attachment.variant -- which raises InvariableError for previewable blobs.
+    module NamedVariantScan
+      module_function
+
+      def find(blob, variation, depth: 0)
+        blob.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 && find(source, variation, depth: depth + 1)
+            return result if result
+            next
+          end
+
+          attachment.send(:named_variants).each do |name, named_variant|
+            candidate = ActiveStorage::Variation.wrap(named_variant.transformations)
+            next unless candidate.async_options[:transformer]
+            return [attachment, name, candidate.async_options] if matches?(candidate, variation)
+          end
+        end
+        nil
+      end
+
+      # A format-less declaration matches any target format, because runtime
+      # resolution (Blob#variant's default_to) adds a blob-dependent format:
+      # the declaration never carries.
+      def matches?(candidate, variation)
+        declared = normalize(candidate.transformations)
+        target = normalize(variation.transformations)
+        declared_format = declared.delete("format")
+        target_format = target.delete("format")
+        declared == target && (declared_format.nil? || declared_format == target_format)
+      end
+
+      def normalize(transformations)
+        JSON.parse(transformations.to_json)
+      end
+    end
+  end
+end

data/lib/active_storage/async_variants/preview_extension.rb

@@ -11,13 +11,19 @@ module ActiveStorage
       end
 
       def enqueue!
-        if result = find_named_async_variant
-          attachment, variant_name, _ = result
-
-          blob.variant_records.create!(
-            variation_digest: variation.digest,
-            state: "pending",
-          )
+        return if async_record
+
+        if result = ActiveStorage::AsyncVariants::NamedVariantScan.find(blob, variation)
+          attachment, variant_name, options = result
+
+          transformer = options[:transformer]
+          if transformer&.new&.external?
+            ActiveStorage::AsyncVariants.ensure_preview_image_placeholder!(blob)
+            blob.preview_image.blob.variant_records.create!(
+              variation_digest: variant.variation.digest,
+              state: "pending",
+            )
+          end
           ActiveStorage::AsyncVariants::ProcessJob.perform_later(
             attachment.record, attachment.name, variant_name.to_s,
           )
@@ -26,13 +32,27 @@ module ActiveStorage
         # another caller (or a leftover record) wins; their job handles it
       end
 
+      def retry!
+        async_record&.destroy if async_state == "failed"
+        enqueue!
+      end
+
+      # Stock preview structure: the record hangs off the extracted frame (the
+      # blob's preview_image attachment), not the source blob. The digest is
+      # resolved through stock's Preview#variant so it matches the
+      # default_to-applied variation embedded in representation URLs.
+      def async_record
+        return nil unless blob.preview_image.attached?
+        blob.preview_image.blob.variant_records.find_by(variation_digest: variant.variation.digest)
+      end
+
       def processed?
         async_preview? ? preview_variant_processed? : super
       end
 
       def url(...)
         if async_preview?
-          preview_variant_processed? ? find_preview_variant_record.image.url(...) : fallback_preview_url(...)
+          preview_variant_processed? ? async_record.image.url(...) : fallback_preview_url(...)
         else
           super
         end
@@ -41,7 +61,7 @@ module ActiveStorage
       def key
         if async_preview?
           raise ActiveStorage::Preview::UnprocessedError unless preview_variant_processed?
-          find_preview_variant_record.image.blob.key
+          async_record.image.blob.key
         else
           super
         end
@@ -49,30 +69,44 @@ module ActiveStorage
 
       def async_state
         return nil unless async_preview?
-        find_preview_variant_record&.state || "pending"
+        async_record&.state || "pending"
       end
 
       def progress
-        find_preview_variant_record&.progress
+        async_record&.progress
       end
 
       def progress_known?
-        !find_preview_variant_record&.progress.nil?
+        !async_record&.progress.nil?
+      end
+
+      # Mirror of VariantWithRecordExtension so a Preview is a drop-in for the
+      # UI layer's progress protocol: percent-per-second over elapsed processing
+      # time, driving the progress bar's optimistic creep between polls.
+      def progress_rate
+        record = async_record
+        return nil unless record&.created_at && record.last_heartbeat_at && record.progress&.positive?
+        elapsed = record.last_heartbeat_at - record.created_at
+        elapsed.positive? ? (record.progress / elapsed).round(4) : nil
       end
 
       def last_heartbeat_at
-        find_preview_variant_record&.last_heartbeat_at
+        async_record&.last_heartbeat_at
+      end
+
+      def error
+        async_record&.error
       end
 
       private
 
       def async_preview?
-        resolved_async_options[:async].present?
+        resolved_async_options[:transformer].present?
       end
 
       # Variations rebuilt from the redirect URL only carry transformations --
-      # :async / :transformer are stripped at Variation#initialize and not
-      # embedded in the URL key. Recover them via the digest-keyed registry that
+      # :transformer is stripped at Variation#initialize and not
+      # embedded in the URL key. Recover it 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).
@@ -80,31 +114,12 @@ module ActiveStorage
         @resolved_async_options ||=
           variation.async_options.presence ||
           ActiveStorage::AsyncVariants::Registry[variation.digest] ||
-          find_named_async_variant&.dig(2) ||
+          ActiveStorage::AsyncVariants::NamedVariantScan.find(blob, variation)&.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[:async]
-          end
-        end
-        nil
-      end
-
       def preview_variant_processed?
-        find_preview_variant_record&.state == "processed"
-      end
-
-      # ProcessJob stores variant_records on the source blob (i.e. @variant.blob,
-      # which for a named variant declared on a previewable attachment is the
-      # original blob -- not preview_image.blob). Read from the same place.
-      def find_preview_variant_record
-        blob.variant_records.find_by(variation_digest: variation.digest)
+        async_record&.state == "processed"
       end
 
       # Serve the original until the preview variant is processed.

data/lib/active_storage/async_variants/process_job.rb

@@ -9,24 +9,12 @@ module ActiveStorage
 
       def perform(record, attachment_name, variant_name)
         attachment = record.public_send(attachment_name)
-        @variant = attachment.variant(variant_name.to_sym)
-        variation = @variant.variation
-        @async_options = variation.async_options
-        transformer_class = @async_options[:transformer]
-        blob = @variant.blob
-
-        @variant_record = blob.variant_records.create_or_find_by!(variation_digest: variation.digest)
-        @variant_record.update!(state: "processing")
-
-        if transformer_class
-          transformer = transformer_class.new
-          if transformer.inline?
-            process_inline(blob, @variant_record, transformer, variation)
-          else
-            process_external(blob, @variant_record, transformer, variation)
-          end
+        representation = attachment.representation(variant_name.to_sym)
+
+        if representation.is_a?(ActiveStorage::Preview)
+          perform_preview(representation)
         else
-          process_default(blob, @variant_record, variation)
+          perform_variant(representation)
         end
       rescue => e
         @variant_record&.update!(
@@ -39,6 +27,54 @@ module ActiveStorage
 
       private
 
+      def perform_variant(variant)
+        blob = variant.blob
+        @variant_record = blob.variant_records.create_or_find_by!(variation_digest: variant.variation.digest)
+        return if @variant_record.processed? || @variant_record.in_flight?
+        @variant_record.update!(state: "processing", last_heartbeat_at: Time.current)
+
+        dispatch(variant.variation, transform_blob: blob, source_blob: blob)
+      end
+
+      # Stock preview structure: the frame lives as a preview_image attachment
+      # on the source blob, and the variant record hangs off the frame blob.
+      # Standard/inline transformers need the real frame up front (the stock
+      # previewer extracts it); external transformers get a placeholder the
+      # service writes into, plus the source blob to extract from.
+      def perform_preview(preview)
+        blob = preview.blob
+
+        if transformer_for(preview.variation).external?
+          ActiveStorage::AsyncVariants.ensure_preview_image_placeholder!(blob)
+        else
+          preview.send(:process) unless blob.preview_image.attached?
+        end
+
+        frame_blob = blob.preview_image.blob
+        variation = preview.send(:variant).variation
+        @variant_record = frame_blob.variant_records.create_or_find_by!(variation_digest: variation.digest)
+        return if @variant_record.processed? || @variant_record.in_flight?
+        @variant_record.update!(state: "processing", last_heartbeat_at: Time.current)
+
+        dispatch(variation, transform_blob: frame_blob, source_blob: blob)
+      end
+
+      def dispatch(variation, transform_blob:, source_blob:)
+        transformer = transformer_for(variation)
+
+        if transformer.standard?
+          process_default(transform_blob, @variant_record, variation)
+        elsif transformer.inline?
+          process_inline(transform_blob, @variant_record, transformer, variation)
+        else
+          process_external(source_blob, @variant_record, transformer, variation)
+        end
+      end
+
+      def transformer_for(variation)
+        (variation.async_options[:transformer] || ActiveStorage::AsyncVariants::Standard).new
+      end
+
       def process_inline(blob, variant_record, transformer, variation)
         options = variation.transformations
 

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, async: true
+    #       transformer: Crucible
     #   end
     #
     # Without this, the Registry only warms when view-side code calls
@@ -28,7 +28,7 @@ module ActiveStorage
         # matches the URL-side digest for variants that declare an explicit
         # `format:`. Variants without an explicit `format:` still warm lazily
         # on first view-side call against a blob of that content type.
-        ActiveStorage::Variation.wrap(transformations).default_to(format: :png)
+        ActiveStorage::Variation.wrap(transformations.except(:preprocessed)).default_to(format: :png)
       end
     end
   end

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 :async in its async_options -- which happens on
+    # constructed with a :transformer in its async_options -- which happens on
     # every view-side `attachment.variant(:name)` call. The redirect controller
     # then resolves async_options by digest without scanning blob.attachments
     # for a transformations-match.

data/lib/active_storage/async_variants/transformer.rb

@@ -2,6 +2,15 @@
 
 module ActiveStorage
   module AsyncVariants
+    # Naming a transformer on a variant is what opts it into async processing.
+    # Three kinds, distinguished by what they override:
+    #
+    # - standard (overrides neither) -- runs the stock Active Storage variant
+    #   pipeline in the background. Use the built-in Standard below.
+    # - inline (overrides #process) -- does the work in the worker, returns
+    #   { io:, content_type:, filename: }.
+    # - external (overrides #initiate) -- hands off to a remote service that
+    #   POSTs back to the callback URL when done.
     class Transformer
       def process(file, **options)
         raise NotImplementedError, "#{self.class}#process must return { io:, content_type:, filename: }"
@@ -12,8 +21,30 @@ module ActiveStorage
       end
 
       def inline?
-        self.class.instance_method(:process).owner != ActiveStorage::AsyncVariants::Transformer
+        overrides?(:process)
       end
+
+      def external?
+        overrides?(:initiate)
+      end
+
+      def standard?
+        !inline? && !external?
+      end
+
+      private
+
+      def overrides?(method_name)
+        self.class.instance_method(method_name).owner != ActiveStorage::AsyncVariants::Transformer
+      end
+    end
+
+    # Async processing via the stock Active Storage variant pipeline -- the
+    # replacement for the old bare `async: true` (no transformer) declaration.
+    #
+    #   attachable.variant :thumb, resize_to_limit: [100, 100],
+    #     transformer: ActiveStorage::AsyncVariants::Standard
+    class Standard < Transformer
     end
   end
 end

data/lib/active_storage/async_variants/variant_record_extension.rb

@@ -7,6 +7,16 @@ module ActiveStorage
 
       included do
         after_update_commit :touch_attached_records, if: :reached_terminal_state?
+        after_destroy_commit :purge_late_outputs
+      end
+
+      def processed?
+        state == "processed"
+      end
+
+      # A run that stopped heartbeating is presumed dead, so it may be retried.
+      def in_flight?
+        state == "processing" && last_heartbeat_at.present? && last_heartbeat_at > ActiveStorage::AsyncVariants.heartbeat_stale_after.ago
       end
 
       private
@@ -19,6 +29,11 @@ module ActiveStorage
         saved_change_to_state? && %w[processed failed].include?(state)
       end
 
+      # A render that held the row lock can commit an output after this destroy read the record's attachments.
+      def purge_late_outputs
+        ActiveStorage::Attachment.where(record: self).find_each(&:purge_later)
+      end
+
       def touch_attached_records
         blob.attachments.includes(:record).each do |attachment|
           attachment.record&.touch

data/lib/active_storage/async_variants/variant_with_record_extension.rb

@@ -26,6 +26,15 @@ module ActiveStorage
         # another caller (or a leftover record) wins; their job handles it
       end
 
+      def retry!
+        async_record&.destroy if failed?
+        enqueue!
+      end
+
+      def async_record
+        blob.variant_records.find_by(variation_digest: variation.digest)
+      end
+
       def url(...)
         if blob.bucket_backed? && async_variant? && !processed?
           blob.url(...)
@@ -87,7 +96,7 @@ module ActiveStorage
       private
 
       def async_variant?
-        resolved_async_options[:async].present?
+        resolved_async_options[:transformer].present?
       end
 
       def resolved_async_options
@@ -103,36 +112,8 @@ module ActiveStorage
       # 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
-
-          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[:async]
-            end
-          end
-        end
-        nil
-      end
-
-      def async_record
-        blob.variant_records.find_by(variation_digest: variation.digest)
+        ActiveStorage::AsyncVariants::NamedVariantScan.find(blob, variation)
       end
     end
   end

data/lib/active_storage/async_variants/variation_extension.rb

@@ -3,17 +3,20 @@
 module ActiveStorage
   module AsyncVariants
     module VariationExtension
-      ASYNC_KEYS = %i[async transformer].freeze
-
+      # Stripped before stock sees it (it would treat it as an unknown image
+      # operation). Naming a `:transformer` is the async opt-in.
       def initialize(transformations)
         if transformations.is_a?(Hash)
-          @async_options = transformations.slice(*ASYNC_KEYS)
-          super(transformations.except(*ASYNC_KEYS))
+          if transformations.key?(:async)
+            raise ArgumentError, "async: is no longer supported; name a transformer: to opt a variant into async processing"
+          end
+          @async_options = transformations.slice(:transformer)
+          super(transformations.except(:transformer))
         else
           @async_options = {}
           super
         end
-        ActiveStorage::AsyncVariants::Registry.register(digest, @async_options) if @async_options[:async]
+        ActiveStorage::AsyncVariants::Registry.register(digest, @async_options) if @async_options[:transformer]
       end
 
       def async_options

data/lib/active_storage/async_variants/version.rb

@@ -2,6 +2,6 @@
 
 module ActiveStorage
   module AsyncVariants
-    VERSION = "0.9.0"
+    VERSION = "0.10.0"
   end
 end

data/lib/active_storage/async_variants.rb

@@ -3,6 +3,7 @@
 require_relative "async_variants/version"
 require_relative "async_variants/transformer"
 require_relative "async_variants/registry"
+require_relative "async_variants/named_variant_scan"
 require_relative "async_variants/blob_extension"
 require_relative "async_variants/variation_extension"
 require_relative "async_variants/variant_with_record_extension"
@@ -75,6 +76,34 @@ module ActiveStorage
       )
     end
 
+    # Attaches a frame placeholder (byte_size 0, checksum "0") as the blob's
+    # preview_image, mirroring stock's once-per-blob preview extraction. The
+    # external transformer writes the real frame to it; the success callback
+    # reconciles the sentinel metadata.
+    #
+    # Serialized on the blob row: every image variant of one video runs this
+    # concurrently, and a second frame would be invisible to has_one
+    # :preview_image, stranding the records that hang off it.
+    def self.ensure_preview_image_placeholder!(blob)
+      return blob.preview_image.blob if blob.preview_image.attached?
+
+      blob.with_lock do
+        # with_lock reloaded the blob, so this sees a frame a racing caller just committed.
+        next blob.preview_image.blob if blob.preview_image.attached?
+
+        frame = ActiveStorage::Blob.create_before_direct_upload!(
+          filename: "#{blob.filename.base}.jpg",
+          content_type: "image/jpeg",
+          metadata: { analyzed: true },
+          service_name: blob.service_name,
+          byte_size: 0,
+          checksum: "0",
+        )
+        blob.preview_image.attach(frame)
+        frame
+      end
+    end
+
     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.9.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Micah Geisel
 bindir: exe
 cert_chain: []
-date: 2026-06-10 00:00:00.000000000 Z
+date: 2026-11-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activestorage
@@ -40,6 +40,7 @@ files:
 - Rakefile
 - app/controllers/active_storage/async_variants/callbacks_controller.rb
 - config/routes.rb
+- db/migrate/20260304000001_add_state_columns_to_variant_records.rb
 - db/migrate/20260607000001_add_heartbeat_columns_to_variant_records.rb
 - db/migrate/20260608000001_add_created_at_to_variant_records.rb
 - gemfiles/rails_7.2.gemfile
@@ -49,6 +50,7 @@ files:
 - lib/active_storage/async_variants/attachment_extension.rb
 - lib/active_storage/async_variants/blob_extension.rb
 - lib/active_storage/async_variants/heartbeat_watchdog_job.rb
+- lib/active_storage/async_variants/named_variant_scan.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