active_storage-async_variants 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 34c672d7d6d989bb7c633aa1e57e081d6879a8ea9695ffd65997b9df9cf8f8ab
-  data.tar.gz: aca54bb9b2ae6af16016f1e96e6e3f221bc7029b8eca9c145535eadefeb57d66
+  metadata.gz: d60acebdeb8fe9482d73576e79abb4737fb052e6df939e09829b9c0e766b9e12
+  data.tar.gz: 68be3b6ef1f9cb34e5a08f87b20470520367e16fdcc81ec73f18d5956ab8979a
 SHA512:
-  metadata.gz: e86b3777c71d70d2014fe439fb91f395f1711cce40efefa3c5e5291a22bd2fc6d1933aad3a1c095557726e45547d7112f9e2f2bbd24fece75726adebddd6f686
-  data.tar.gz: 591deb4316c685316084ebb26904e5fe5b2ecbea0328cc832469ae4185388239511e35507b53264e137cf85153bfe1a846e7bd0491ba023bb991333653cfb532
+  metadata.gz: a3fc174236833deeda757d08b0f8ff68769d5130beb7b3f20fd68082e73aa72ac2a088fd23fad45209cd9849caa9d0293ec5f9f11bd365dec3e6d995a5b79fb0
+  data.tar.gz: 7944a7832431949722581b13f62c99b785df7abfaf7693ea236213df1a08e730d9070bce1465ea32255b29423dc393d30bfd61f9b72cf2bdc39b48010bcd806d

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [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`).
+- Moved to the UI gem: `image_tag`/`video_tag` with `async:`/`direct:`, the `<turbo-frame>` state endpoint and partials, the circular progress bar, the filename-bearing placeholder route, the retry affordance, and the `cdn_host` / `parent_controller` / `retry_visible_if` configuration. A variant's `.url` (serving the original until processed) is unchanged.
+- Migration note: apps that relied on the rendering helpers should add `gem "active_storage-async_variants-ui"`. Apps using `active_storage-crucible` or only the variant pipeline need no change.
+
 ## [0.8.0]
 
 - The processing progress bar now advances smoothly between polls: variants expose a `rate` (percent-per-second, derived from the record's `created_at`, last heartbeat, and reported progress) that the `@botandrose/progress-bar` element uses to optimistically creep forward, instead of only stepping on each refresh. Includes a migration adding a `created_at` column to `active_storage_variant_records`; run it before deploying.

data/README.md

@@ -2,6 +2,8 @@
 
 Extends Active Storage with pluggable per-variant transformers, async-safe variant processing, and failure handling.
 
+This gem is the UI-free plumbing. A variant's `.url` serves the original while it is pending/processing/failed, and the processed variant once ready — nothing renders a spinner or progress bar. For the optional turbo-frame UI (`image_tag`/`video_tag` with `async:`/`direct:`, a circular progress bar, and a retry affordance), add the companion gem [`active_storage-async_variants-ui`](https://github.com/botandrose/active_storage-async_variants-ui).
+
 ## The Problem
 
 Active Storage's variant system assumes transformations are fast and reliable -- like generating an image thumbnail. But some transformations are slow (transcoding a 1GB video to 720p VP9) and fallible (the transcode may permanently fail). When you use `process: :later`, Active Storage enqueues a background job, but if the variant is requested before the job finishes, it falls through to synchronous processing -- blocking the request for minutes or timing out entirely. And if the transformation fails, the error bubbles up with no tracking or retry limits.
@@ -62,67 +64,22 @@ In views, use the same Active Storage helpers:
 
 While the variant is still processing (or has failed), this serves the original video. Once processing completes, it serves the transcoded variant.
 
-## `image_tag` / `video_tag` with `async:` and `direct:`
-
-For a polish layer that shows a progress bar while a variant is being processed, polls for completion in the background, and optionally serves the finished variant straight from your CDN, the gem adds two options to `image_tag` and `video_tag`:
-
-```erb
-<%# Variant URL with the async client wired up: a progress bar while pending,
-    polls for completion, swaps to the real image when ready. %>
-<%= image_tag user.avatar.variant(:web), async: true %>
-
-<%# When the variant is ready, render its direct CDN/S3 URL instead of
-    routing through Rails. While pending/failed, falls back to the
-    Rails representation URL (which serves the original). %>
-<%= image_tag user.avatar.variant(:web), direct: true %>
-
-<%# Both together: direct URL once processed, progress bar 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}"`.
-
-### JavaScript
-
-No manual wiring is required. The async state partials are self-contained `<turbo-frame>`s. The only requirement is that the host app loads **Turbo** -- the gem depends on `turbo-rails`, which a default Rails app already includes.
-
 ## Configuration
 
-Set options in an initializer. The `configure` block groups them (each is also a plain accessor, e.g. `ActiveStorage::AsyncVariants.cdn_host = …`):
+Set options in an initializer. The `configure` block groups them (each is also a plain accessor, e.g. `ActiveStorage::AsyncVariants.heartbeat_interval = …`):
 
 ```ruby
 # config/initializers/active_storage_async_variants.rb
 ActiveStorage::AsyncVariants.configure do |config|
-  config.cdn_host              = "https://d1234abcd.cloudfront.net"
   config.heartbeat_interval    = 5.seconds
   config.heartbeat_stale_after = 60.seconds
-  config.parent_controller     = "ApplicationController"
-  config.retry_visible_if { current_user&.admin? }
 end
 ```
 
 | Option | Default | Purpose |
 |--------|---------|---------|
-| `cdn_host` | `nil` | Host for `direct:` URLs (`"#{cdn_host}/#{variant.key}"`); falls back to the storage service URL. |
-| `heartbeat_interval` | `5.seconds` | Expected cadence of progress heartbeats; the processing `<turbo-frame>` re-polls at this rate. |
+| `heartbeat_interval` | `5.seconds` | Expected cadence of progress heartbeats from external transformers. (The UI gem's processing `<turbo-frame>` re-polls at this rate.) |
 | `heartbeat_stale_after` | `60.seconds` | A processing variant with no heartbeat for this long is marked `failed`. Must exceed `heartbeat_interval`. |
-| `parent_controller` | `"ActionController::Base"` | Base class for the gem's controllers, so the retry view can reach your app's `current_user`. Set as a String. |
-| `retry_visible_if` | off | Block (run in the view context) gating the failed-state retry affordance. |
 
 ## Writing a Transformer
 
@@ -229,7 +186,7 @@ variant.error        # => error message string, or nil
 
 ## Placeholders
 
-There is nothing to configure. A variant's `.url` serves the original while it is pending, processing, or failed, and the processed variant once ready. With `async: true` on `image_tag`/`video_tag`, the gem instead shows a circular progress bar while processing, and a red error glyph -- the same progress bar in its error state -- once the variant has permanently failed.
+There is nothing to configure. A variant's `.url` serves the original while it is pending, processing, or failed, and the processed variant once ready. (For a circular progress bar while processing and a red error glyph once failed, add the [`active_storage-async_variants-ui`](https://github.com/botandrose/active_storage-async_variants-ui) gem.)
 
 ## Failure Handling
 

data/Rakefile

@@ -5,23 +5,4 @@ require "rspec/core/rake_task"
 
 RSpec::Core::RakeTask.new(:spec)
 
-desc "Run browser-level acceptance tests (cucumber + cuprite against spec/dummy)"
-task :cucumber do
-  sh "bundle exec cucumber"
-end
-
-desc "Run rspec and cucumber"
-task all: [:spec, :cucumber]
-
-namespace :vendor do
-  desc "Pull the latest @botandrose/progress-bar from unpkg.com into app/assets"
-  task :progress_bar do
-    require "open-uri"
-    url = "https://unpkg.com/@botandrose/progress-bar"
-    dest = File.expand_path("app/assets/javascripts/progress-bar.js", __dir__)
-    File.write(dest, URI.open(url).read)
-    puts "Vendored #{url} -> #{dest}"
-  end
-end
-
-task default: :all
+task default: :spec

data/config/routes.rb

@@ -4,21 +4,4 @@ Rails.application.routes.draw do
   post "/active_storage/async_variants/callbacks/:token",
     to: "active_storage/async_variants/callbacks#create",
     as: :active_storage_async_variant_callback
-
-  get  "/active_storage/async_variants/states/:signed_blob_id/:variation_key",
-    to: "active_storage/async_variants/states#show",
-    as: :async_variant_state
-  post "/active_storage/async_variants/states/:signed_blob_id/:variation_key/retry",
-    to: "active_storage/async_variants/states#retry",
-    as: :async_variant_state_retry
-
-  # Tiny 1x1 GIF whose URL carries the media's filename, so the processing/failed
-  # box reserves layout without fetching the original through a representation.
-  get "/active_storage/async_variants/placeholder/:filename",
-    to: "active_storage/async_variants/states#placeholder",
-    as: :async_variant_placeholder,
-    constraints: { filename: %r{[^/]+} },
-    format: false
-
-  ActiveStorage::AsyncVariants::Assets.draw(self, "/active_storage/async_variants/assets")
 end

data/gemfiles/rails_7.2.gemfile

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

data/gemfiles/rails_8.0.gemfile

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

data/gemfiles/rails_8.1.gemfile

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

data/lib/active_storage/async_variants/version.rb

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

data/lib/active_storage/async_variants.rb

@@ -1,9 +1,6 @@
 # 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/blob_extension"
@@ -15,41 +12,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 +47,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,8 +75,6 @@ module ActiveStorage
       )
     end
 
-    Assets = IsolateAssets.register(namespace: self, engine: Engine, route_name: :async_variant_asset)
-
     def self.callback_token_for(variant_record)
       ActiveStorage.verifier.generate(variant_record.id, purpose: :async_variant_callback)
     end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: active_storage-async_variants
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Micah Geisel
 bindir: exe
 cert_chain: []
-date: 2026-06-08 00:00:00.000000000 Z
+date: 2026-06-10 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,17 @@ 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/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/preview_extension.rb
 - lib/active_storage/async_variants/process_job.rb
 - lib/active_storage/async_variants/reflection_extension.rb