active_storage-async_variants 0.1.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4395d49e7c04b9206145e2c8dbe0bf3f4466ed736054ec5e9fc3b8fc7dea3a1c
-  data.tar.gz: 1cf4f1090be29b6ff6a7a50be05ecaa2bcc79f50de9a203ec26d99c9d8e58fc8
+  metadata.gz: ed31f4592e3d865609aef29b42657856321528d5013bb2a1ec499e3de93c5bb4
+  data.tar.gz: 994460c1ae175245da3d71489b25d4143827931f926289c94c18957df8cf0610
 SHA512:
-  metadata.gz: 1d696905633e0039f8489377d41ea120fd89d5fccfcadbd8872981ea916d9032395f5f66091eba170de40f03547b7b93c90457e6796f15868ae3e7d3ecf937c4
-  data.tar.gz: 21c13be811dc6c6b9b19123f6ef8c9c23c1e2cbc0360ee9f79a88b4bf83d023f514d61964e75b749c2b073ad19e7db52f878a2b55de8c90b4018ff831a4d3f2d
+  metadata.gz: c6b94095e095899175ac9fa37497500b9947e761d2ed07a7fdd78d55a90ac05898dca086e02d8b29419fc1fde8567628a4f6c7444470826ae6fb0556220af4ef
+  data.tar.gz: 109f1670b0ad22ce670bf27751ffeac462f0f10c94d0d89f4777c211b2fb1aa179c3981373ebc9b2f36a2262c4722dcdf73cd54ff95ca29cf6b035765150357f

data/.github/workflows/ci.yml

@@ -14,9 +14,6 @@ jobs:
       matrix:
         ruby: ["3.3", "3.4", "4.0"]
         rails: ["rails-7.2", "rails-8.0", "rails-8.1"]
-        exclude:
-          - ruby: "4.0"
-            rails: "rails-7.2"
     steps:
       - uses: actions/checkout@v4
       - uses: ruby/setup-ruby@v1

data/CHANGELOG.md

@@ -1,4 +1,13 @@
-## [Unreleased]
+## [0.3.1]
+
+- Bound the stored variant `error` to 16k chars at both write sites (the failed-status callback and `ProcessJob`'s rescue). An external transformer reporting a >64KB error payload was overflowing the `TEXT` column and 500ing the callback, leaving the variant stuck instead of marked failed.
+
+## [0.3.0]
+
+- Touch attached records when a variant transitions to processed, so consumer caches keyed on `cache_key_with_version` invalidate without needing manual cascading. Multi-hop cascades remain the consumer's responsibility via standard Rails `touch:` or `after_touch`.
+- Dedupe concurrent `.processed` calls so they enqueue at most one `ProcessJob` per blob+variation. Previously, every call before the first job flipped state to "processing" enqueued another job; each job created a fresh variant blob, leaving the others as orphans. The record is now created as `pending` at enqueue time, using the unique index on `active_storage_variant_records (blob_id, variation_digest)` (already shipped by the standard Active Storage migration) as the dedupe key. Once a record reaches `failed` (after `ProcessJob` exhausts its 3-attempt `retry_on` cycle), further `.processed` calls no longer re-enqueue — the variant is permanently failed.
+- Renamed the `fallback:` variant option to `processing:` to better describe what it represents — the placeholder served while the variant is being processed.
+- New `failed:` variant option that specifies a distinct placeholder to render when the variant has permanently failed, separate from the `processing:` placeholder. Accepts `:original`, `:blank`, a String URL, or a Proc that receives the blob. Defaults to `processing:` when unspecified. Also extends `processing:` to accept a String URL directly (previously you had to wrap a static URL in a Proc).
 
 ## [0.1.0] - 2026-03-03
 

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 `fallback:` 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 `processing:` 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 (`fallback:`, `transformer:`, `max_retries:`) 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 `fallback:`
-- **`VariantWithRecordExtension`** → `ActiveStorage::VariantWithRecord` — overrides URL generation to serve fallback while processing; adds state query methods (`ready?`, `processing?`, `pending?`, `failed?`)
+- **`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?`)
 - **`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 `fallback:` to any named variant to opt into the async pipeline:
+Add `processing:` to any named variant to opt into the async pipeline. The value is what to serve while the variant is being processed:
 
 ```ruby
 class User < ApplicationRecord
@@ -28,12 +28,12 @@ class User < ApplicationRecord
       transformer: VideoTranscoder,
       codec: "vp9",
       resolution: "720p",
-      fallback: :original
+      processing: :original
   end
 end
 ```
 
-The presence of `fallback:` 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 `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:
 
 ```ruby
 has_one_attached :video do |attachable|
@@ -41,14 +41,14 @@ has_one_attached :video do |attachable|
   attachable.variant :web,
     transformer: VideoTranscoder,
     codec: "vp9",
-    fallback: :original
+    processing: :original
 
   # Async with default transformer (large image resize that's too slow for inline)
   attachable.variant :thumbnail,
     resize_to_limit: [200, 200],
-    fallback: :original
+    processing: :original
 
-  # Sync with custom transformer (fast custom processing, no fallback needed)
+  # Sync with custom transformer (fast custom processing, no opt-in needed)
   attachable.variant :watermarked,
     transformer: WatermarkStamper
 end
@@ -62,6 +62,65 @@ In views, use the same Active Storage helpers:
 
 If the variant is still processing, 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`:
+
+```erb
+<%# Variant URL with the async client wired up: spinner 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). %>
+<%= image_tag user.avatar.variant(:web), direct: true %>
+
+<%# Both together: direct URL once processed, placeholder while pending,
+    polling for completion. %>
+<%= image_tag user.avatar.variant(:web), async: true, direct: true %>
+
+<%# Same for videos. %>
+<%= video_tag user.video.variant(:web), async: true, controls: true %>
+```
+
+The first argument must be a `VariantWithRecord` or `Preview` when either option is set; otherwise `image_tag` / `video_tag` behave exactly as in stock Rails.
+
+### Configure the direct URL host
+
+By default `direct:` uses the storage service's URL (presigned for private buckets, unsigned for public). To serve from a CDN, set the host in an initializer:
+
+```ruby
+# config/initializers/active_storage_async_variants.rb
+ActiveStorage::AsyncVariants.cdn_host = "https://d1234abcd.cloudfront.net"
+```
+
+The resulting URL is `"#{cdn_host}/#{variant.key}"`.
+
+### Wiring the JavaScript
+
+The gem ships a dependency-free Stimulus-like controller at `app/assets/javascripts/active_storage_async_variants.js`. It is registered with the asset pipeline by the engine but not auto-imported. Wire it up the same way as `@rails/activestorage` -- pick whichever fits your bundler:
+
+Using **importmap-rails**:
+
+```ruby
+# config/importmap.rb
+pin "@active_storage/async_variants", to: "active_storage_async_variants.js", preload: true
+```
+
+```js
+// app/javascript/application.js
+import "@active_storage/async_variants"
+```
+
+Using **the asset pipeline** (sprockets/propshaft) with a classic `javascript_include_tag`:
+
+```erb
+<%= javascript_include_tag "active_storage_async_variants" %>
+```
+
+The module auto-starts on `DOMContentLoaded` and finds elements with `data-async-variant-state-value`. Opt out by setting `window.ActiveStorageAsyncVariants = null` before the script loads, then calling `start()` yourself from the exported module when ready.
+
 ## Writing a Transformer
 
 Transformers come in two flavors: **inline** (the job blocks until processing completes) and **external** (the job kicks off remote work and a webhook signals completion).
@@ -158,41 +217,42 @@ The gem determines the mode by which method the transformer implements: `initiat
 ```ruby
 variant = user.video.variant(:web)
 
-variant.ready?       # => true if processed successfully
+variant.processed?   # => true if processed successfully
 variant.processing?  # => true if job is running or external service is working
 variant.pending?     # => true if job is enqueued
 variant.failed?      # => true if permanently failed
 variant.error        # => error message string, or nil
 ```
 
-## Fallback Options
+## Placeholder Options
 
-The `fallback:` option controls what gets served while a variant is processing (or after it fails):
+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
-attachable.variant :web, fallback: :original
+# Serve the original unprocessed file while processing
+attachable.variant :web, processing: :original
 
 # Return nil -- let the view handle it
-attachable.variant :web, fallback: :blank
+attachable.variant :web, processing: :blank
+
+# Static URL while processing
+attachable.variant :web, processing: "/placeholders/processing.svg"
 
-# Custom fallback
+# Dynamic placeholder via Proc
 attachable.variant :web,
-  fallback: -> (blob) { "/placeholders/processing.svg" }
+  processing: -> (blob) { "/placeholders/processing.svg" }
+
+# Distinct placeholder when permanently failed
+attachable.variant :web,
+  processing: :original,
+  failed: "/icons/broken.svg"
 ```
 
-## Failure Handling
+Both options accept the same set of values: `:original`, `:blank`, a String URL, or a Proc that receives the blob.
 
-By default, a variant is retried 3 times before being marked as permanently failed. Configure per-variant:
+## Failure Handling
 
-```ruby
-attachable.variant :web,
-  transformer: VideoTranscoder,
-  codec: "vp9",
-  resolution: "720p",
-  fallback: :original,
-  max_retries: 5
-```
+A variant is retried up to 3 times before being marked as permanently failed. Once permanently failed, `.processed` no longer re-enqueues the job — the variant stays failed until you delete the `ActiveStorage::VariantRecord` row manually (or re-attach a fresh blob).
 
 Inspect failures:
 
@@ -213,15 +273,15 @@ 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 fallback
+8. When a view requests the variant URL, the gem checks state and serves the variant or the `processing:`/`failed:` placeholder
 
 ### Inline transformer flow
 
 1-3. Same as above
 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 `max_retries`)
-7. When a view requests the variant URL, the gem checks state and serves the variant or the fallback
+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
 
 ## License
 

data/app/assets/javascripts/active_storage_async_variants.js

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

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

@@ -10,8 +10,10 @@ module ActiveStorage
         case params[:status]
         when "success"
           variant_record.update!(state: "processed")
+          apply_reported_metadata(variant_record, params)
         when "failed"
-          variant_record.update!(state: "failed", error: params[:error])
+          # error column is TEXT (64KB); utf8mb4 is up to 4 bytes/char, so cap at 16k chars.
+          variant_record.update!(state: "failed", error: params[:error].to_s.truncate(16_000))
         else
           head :unprocessable_entity and return
         end
@@ -20,6 +22,37 @@ module ActiveStorage
       rescue ActiveSupport::MessageVerifier::InvalidSignature
         head :unauthorized
       end
+
+      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 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])
+      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.
+      def reconcile(blob, byte_size, checksum)
+        return unless blob
+
+        attrs = {}
+        if (bytes = positive_int(byte_size)) && blob.byte_size.zero?
+          attrs[:byte_size] = bytes
+        end
+        if checksum.present? && checksum != "0" && blob.checksum == "0"
+          attrs[:checksum] = checksum
+        end
+        blob.update!(attrs) if attrs.any?
+      end
+
+      def positive_int(value)
+        int = value.to_i
+        int.positive? ? int : nil
+      end
     end
   end
 end

data/gemfiles/rails_7.2.gemfile

@@ -6,6 +6,7 @@ gem "appraisal"
 gem "irb"
 gem "rake", "~> 13.0"
 gem "rspec", "~> 3.0"
+gem "simplecov", require: false
 gem "rspec-rails"
 gem "rails", "~> 7.2.0"
 gem "sqlite3"

data/gemfiles/rails_8.0.gemfile

@@ -6,6 +6,7 @@ gem "appraisal"
 gem "irb"
 gem "rake", "~> 13.0"
 gem "rspec", "~> 3.0"
+gem "simplecov", require: false
 gem "rspec-rails"
 gem "rails", "~> 8.0.0"
 gem "sqlite3"

data/gemfiles/rails_8.1.gemfile

@@ -6,6 +6,7 @@ gem "appraisal"
 gem "irb"
 gem "rake", "~> 13.0"
 gem "rspec", "~> 3.0"
+gem "simplecov", require: false
 gem "rspec-rails"
 gem "rails", "~> 8.1.0"
 gem "sqlite3"

data/lib/active_storage/async_variants/asset_tag_helper_extension.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module ActiveStorage
+  module AsyncVariants
+    module AssetTagHelperExtension
+      def image_tag(source, options = {})
+        options = options.symbolize_keys
+        async = options.delete(:async)
+        direct = options.delete(:direct)
+        return super if !async && !direct
+        variant = AssetTagHelperExtension.coerce_variant!(source)
+        src = AssetTagHelperExtension.resolve_src(variant, direct: direct)
+        AssetTagHelperExtension.apply_async_data!(options, variant: variant, direct: direct) if async
+        super(src, options)
+      end
+
+      def video_tag(*sources)
+        options = sources.extract_options!.symbolize_keys
+        async = options.delete(:async)
+        direct = options.delete(:direct)
+        return super(*sources, options) if !async && !direct
+        variant = AssetTagHelperExtension.coerce_variant!(sources.first)
+        sources[0] = AssetTagHelperExtension.resolve_src(variant, direct: direct)
+        AssetTagHelperExtension.apply_async_data!(options, variant: variant, direct: direct) if async
+        super(*sources, options)
+      end
+
+      class << self
+        def coerce_variant!(source)
+          unless source.is_a?(ActiveStorage::VariantWithRecord) || source.is_a?(ActiveStorage::Preview)
+            raise ArgumentError, "image_tag/video_tag with async:/direct: requires an ActiveStorage::VariantWithRecord or Preview, got #{source.class}"
+          end
+          source
+        end
+
+        def resolve_src(variant, direct:)
+          if direct && variant.async_state == "processed"
+            direct_url(variant)
+          else
+            # Idempotent: enqueue ProcessJob if no record exists yet so a
+            # never-touched variant doesn't sit pending forever. Gated on
+            # bucket-backed services -- on Disk/Test the gem defers to
+            # vanilla ActiveStorage, and #processed would run a synchronous
+            # transform (e.g. vips on an mp4) that the external transformer
+            # is supposed to handle.
+            variant.processed if variant.blob.bucket_backed?
+            polymorphic_url(variant)
+          end
+        end
+
+        def apply_async_data!(options, variant:, direct:)
+          data = (options[:data] || {}).symbolize_keys
+          controllers = data[:controller].to_s.split
+          controllers << "async-variant" unless controllers.include?("async-variant")
+          data[:controller] = controllers.join(" ")
+          data[:async_variant_src_value] = polymorphic_url(variant)
+          data[:async_variant_state_value] = variant.async_state
+          data[:async_variant_direct_value] = direct_url(variant) if direct && variant.async_state == "processed"
+          options[:data] = data
+        end
+
+        def direct_url(variant)
+          if cdn = ActiveStorage::AsyncVariants.cdn_host
+            "#{cdn}/#{variant.key}"
+          else
+            variant.image.url
+          end
+        end
+
+        def polymorphic_url(variant)
+          url_options = ActiveStorage::Current.url_options || Rails.application.routes.default_url_options
+          Rails.application.routes.url_helpers.polymorphic_url(variant, **url_options)
+        end
+      end
+    end
+  end
+end

data/lib/active_storage/async_variants/attachment_extension.rb

@@ -11,8 +11,10 @@ module ActiveStorage
       end
 
       def enqueue_async_variant_jobs
+        return unless blob.bucket_backed?
+
         named_variants.each do |name, named_variant|
-          next unless named_variant.transformations.key?(:fallback)
+          next unless named_variant.transformations.key?(:processing)
 
           ActiveStorage::AsyncVariants::ProcessJob.perform_later(
             record, self.name, name.to_s,

data/lib/active_storage/async_variants/blob_extension.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module ActiveStorage
+  module AsyncVariants
+    module BlobExtension
+      # True when the blob's service is a remote/cloud service that the async
+      # 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.
+      def bucket_backed?
+        service.respond_to?(:bucket)
+      end
+    end
+  end
+end