active_storage-async_variants 0.8.0 → 0.10.0

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.8.0"
+    VERSION = "0.10.0"
   end
 end

data/lib/active_storage/async_variants.rb

@@ -1,11 +1,9 @@
 # frozen_string_literal: true
 
-require "turbo-rails"
-require "isolate_assets"
 require_relative "async_variants/version"
-require_relative "async_variants/helper"
 require_relative "async_variants/transformer"
 require_relative "async_variants/registry"
+require_relative "async_variants/named_variant_scan"
 require_relative "async_variants/blob_extension"
 require_relative "async_variants/variation_extension"
 require_relative "async_variants/variant_with_record_extension"
@@ -15,41 +13,18 @@ require_relative "async_variants/attachment_extension"
 require_relative "async_variants/reflection_extension"
 require_relative "async_variants/process_job"
 require_relative "async_variants/heartbeat_watchdog_job"
-require_relative "async_variants/asset_tag_helper_extension"
 
 module ActiveStorage
   module AsyncVariants
-    # HTML attributes round-tripped through the state-endpoint URL so the
-    # eventual processed-state render can apply them to the inner <img>/<video>.
-    PASS_THROUGH_HTML_OPTIONS = %i[alt width height controls autoplay preload].freeze
-
-    mattr_accessor :cdn_host
-    mattr_accessor :retry_visible_proc, default: ->(_view) { false }
-
-    # 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"
-
     # How long an external transform may go without a heartbeat before the
     # watchdog fails it. Must exceed the transformer's heartbeat interval.
     mattr_accessor :heartbeat_stale_after, default: 60.seconds
 
-    # The transformer's heartbeat cadence. The turbo-frame poll matches it so
-    # each reload lands on fresh progress; keep heartbeat_stale_after well above it.
+    # The transformer's heartbeat cadence. External services report at this
+    # rate; the UI layer's turbo-frame poll matches it. Keep heartbeat_stale_after
+    # well above it.
     mattr_accessor :heartbeat_interval, default: 5.seconds
 
-    # 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
-
     def self.configure
       yield self
     end
@@ -73,10 +48,6 @@ module ActiveStorage
         # demand, and we just need the extensions in place by the time
         # the first one loads.
         ActiveStorage::AsyncVariants.prepend_model_extensions!
-
-        ActionView::Helpers::AssetTagHelper.prepend(
-          ActiveStorage::AsyncVariants::AssetTagHelperExtension
-        )
       end
     end
 
@@ -105,7 +76,33 @@ module ActiveStorage
       )
     end
 
-    Assets = IsolateAssets.register(namespace: self, engine: Engine, route_name: :async_variant_asset)
+    # 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)

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: active_storage-async_variants
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Micah Geisel
 bindir: exe
 cert_chain: []
-date: 2026-06-08 00:00:00.000000000 Z
+date: 2026-11-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activestorage
@@ -23,34 +23,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '7.2'
-- !ruby/object:Gem::Dependency
-  name: turbo-rails
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '2.0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '2.0'
-- !ruby/object:Gem::Dependency
-  name: isolate_assets
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0.4'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0.4'
 email:
 - micah@botandrose.com
 executables: []
@@ -66,34 +38,19 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
-- app/assets/javascripts/progress-bar.js
-- app/assets/javascripts/retry.js
-- app/assets/stylesheets/progress.css
-- app/assets/stylesheets/retry.css
 - app/controllers/active_storage/async_variants/callbacks_controller.rb
-- app/controllers/active_storage/async_variants/states_controller.rb
-- app/views/active_storage/async_variants/states/_failed.html.erb
-- app/views/active_storage/async_variants/states/_pending.html.erb
-- app/views/active_storage/async_variants/states/_processed.html.erb
-- app/views/active_storage/async_variants/states/_processing.html.erb
-- app/views/active_storage/async_variants/states/show.html.erb
 - config/routes.rb
+- 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
-- features/retry_flow.feature
-- features/retry_visibility.feature
-- features/state_rendering.feature
-- features/step_definitions/dummy_steps.rb
-- features/support/env.rb
 - gemfiles/rails_7.2.gemfile
 - gemfiles/rails_8.0.gemfile
 - gemfiles/rails_8.1.gemfile
 - lib/active_storage/async_variants.rb
-- 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/heartbeat_watchdog_job.rb
-- lib/active_storage/async_variants/helper.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