active_storage-async_variants 0.1.0

data/lib/active_storage/async_variants/variant_with_record_extension.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module ActiveStorage
+  module AsyncVariants
+    module VariantWithRecordExtension
+      def url(...)
+        if processed?
+          super
+        else
+          fallback_url(...)
+        end
+      end
+
+      def ready?
+        async_record&.state == "processed"
+      end
+
+      def processing?
+        async_record&.state == "processing"
+      end
+
+      def pending?
+        async_record.nil? || async_record.state == "pending"
+      end
+
+      def failed?
+        async_record&.state == "failed"
+      end
+
+      def error
+        async_record&.error
+      end
+
+      private
+
+      def processed?
+        async? ? ready? : super
+      end
+
+      def async?
+        variation.async_options[:fallback].present?
+      end
+
+      def async_record
+        blob.variant_records.find_by(variation_digest: variation.digest)
+      end
+
+      def fallback_url(...)
+        case variation.async_options[:fallback]
+        when :original
+          blob.url(...)
+        when :blank
+          nil
+        when Proc
+          variation.async_options[:fallback].call(blob)
+        end
+      end
+    end
+  end
+end

data/lib/active_storage/async_variants/variation_extension.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module ActiveStorage
+  module AsyncVariants
+    module VariationExtension
+      ASYNC_KEYS = %i[fallback transformer max_retries].freeze
+
+      def initialize(transformations)
+        if transformations.is_a?(Hash)
+          @async_options = transformations.slice(*ASYNC_KEYS)
+          super(transformations.except(*ASYNC_KEYS))
+        else
+          @async_options = {}
+          super
+        end
+      end
+
+      def async_options
+        @async_options || {}
+      end
+
+      def default_to(defaults)
+        self.class.new(transformations.merge(@async_options).reverse_merge(defaults))
+      end
+    end
+  end
+end

data/lib/active_storage/async_variants/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module ActiveStorage
+  module AsyncVariants
+    VERSION = "0.1.0"
+  end
+end

data/lib/active_storage/async_variants.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "async_variants/version"
+require_relative "async_variants/transformer"
+require_relative "async_variants/variation_extension"
+require_relative "async_variants/variant_with_record_extension"
+require_relative "async_variants/attachment_extension"
+require_relative "async_variants/process_job"
+
+module ActiveStorage
+  module AsyncVariants
+    class Engine < ::Rails::Engine
+      config.after_initialize do
+        ActiveStorage::Variation.prepend(
+          ActiveStorage::AsyncVariants::VariationExtension
+        )
+        ActiveStorage::VariantWithRecord.prepend(
+          ActiveStorage::AsyncVariants::VariantWithRecordExtension
+        )
+        ActiveStorage::Attachment.prepend(
+          ActiveStorage::AsyncVariants::AttachmentExtension
+        )
+      end
+    end
+
+    def self.callback_token_for(variant_record)
+      ActiveStorage.verifier.generate(variant_record.id, purpose: :async_variant_callback)
+    end
+
+    def self.callback_url_for(variant_record)
+      token = callback_token_for(variant_record)
+      Rails.application.routes.url_helpers.active_storage_async_variant_callback_url(
+        token: token,
+        **ActiveStorage::Current.url_options,
+      )
+    end
+  end
+end

data/sig/active_storage/async_variants.rbs

@@ -0,0 +1,6 @@
+module ActiveStorage
+  module AsyncVariants
+    VERSION: String
+    # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+  end
+end

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification
+name: active_storage-async_variants
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Micah Geisel
+bindir: exe
+cert_chain: []
+date: 2026-03-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activestorage
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+email:
+- micah@botandrose.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/ci.yml"
+- ".ruby-gemset"
+- ".ruby-version"
+- Appraisals
+- CHANGELOG.md
+- CLAUDE.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- app/controllers/active_storage/async_variants/callbacks_controller.rb
+- config/routes.rb
+- gemfiles/rails_7.2.gemfile
+- gemfiles/rails_7.2.gemfile.lock
+- gemfiles/rails_8.0.gemfile
+- gemfiles/rails_8.0.gemfile.lock
+- gemfiles/rails_8.1.gemfile
+- gemfiles/rails_8.1.gemfile.lock
+- lib/active_storage/async_variants.rb
+- lib/active_storage/async_variants/attachment_extension.rb
+- lib/active_storage/async_variants/process_job.rb
+- lib/active_storage/async_variants/transformer.rb
+- lib/active_storage/async_variants/variant_with_record_extension.rb
+- lib/active_storage/async_variants/variation_extension.rb
+- lib/active_storage/async_variants/version.rb
+- log/.gitkeep
+- sig/active_storage/async_variants.rbs
+homepage: https://github.com/botandrose/active_storage-async_variants
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/botandrose/active_storage-async_variants
+  source_code_uri: https://github.com/botandrose/active_storage-async_variants
+  changelog_uri: https://github.com/botandrose/active_storage-async_variants/blob/master/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Async-safe variant processing with pluggable transformers for Active Storage.
+test_files: []