Add ActiveStorage Uploadcare previewer and remote variant processing

Integrate Uploadcare-backed ActiveStorage behavior into the gem so apps can use standard Rails APIs (preview and variant) without custom helpers.

- auto-register Uploadcare PDF previewer in engine initialization
- prepend remote variant processing for Uploadcare service blobs
- map Rails-style resize_to_limit/resize_to_fill to Uploadcare transformations
- add integration, previewer, and variant processing specs
- document ActiveStorage integration usage in README

Author: vipulnsward

README.md

@@ -522,6 +522,23 @@ Current limitations:
 * direct uploads are not supported yet (`url_for_direct_upload` raises `NotImplementedError`)
 * adapter stores Uploadcare UUID mapping in `ActiveStorage::Blob#metadata["uploadcare_uuid"]`
 
+Built-in Active Storage integrations:
+
+* Uploadcare PDF previewer (`Uploadcare::Rails::ActiveStorage::UploadcarePreviewer`) is auto-registered.
+  This allows standard Rails preview calls like:
+
+```ruby
+url_for(record.file.preview(resize_to_limit: [320, 320]))
+```
+
+* Uploadcare remote variant processing is prepended into `ActiveStorage::Variant`.
+  Standard Rails variant helpers keep working while transformations are executed through Uploadcare CDN:
+
+```ruby
+image_tag(record.image.variant(resize_to_limit: [320, 320], quality: "smart"))
+image_tag(record.image.variant(resize_to_fill: [200, 120]))
+```
+
 ### Uploadcare API interfaces
 
 Uploadcare provides [APIs](https://uploadcare.com/docs/start/api/) to manage files, group, projects, webhooks, video and documents conversion and file uploads. The gem has unified interfaces to use Uploadcare APIs in RailsApp.

lib/uploadcare/rails/active_storage/integration.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'uploadcare/rails/active_storage/uploadcare_previewer'
+require 'uploadcare/rails/active_storage/variant_remote_processing'
+
+module Uploadcare
+  module Rails
+    module ActiveStorage
+      module Integration
+        module_function
+
+        def install!(previewers:)
+          install_previewer(previewers)
+          install_variant_remote_processing
+        end
+
+        def install_previewer(previewers)
+          return if previewers.nil?
+          return if previewers.include?(Uploadcare::Rails::ActiveStorage::UploadcarePreviewer)
+
+          previewers.unshift(Uploadcare::Rails::ActiveStorage::UploadcarePreviewer)
+        end
+
+        def install_variant_remote_processing
+          return unless defined?(::ActiveStorage::Variant)
+          return if ::ActiveStorage::Variant < Uploadcare::Rails::ActiveStorage::VariantRemoteProcessing
+
+          ::ActiveStorage::Variant.prepend(Uploadcare::Rails::ActiveStorage::VariantRemoteProcessing)
+        end
+      end
+    end
+  end
+end

lib/uploadcare/rails/active_storage/uploadcare_previewer.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require 'active_storage/previewer'
+require 'marcel'
+require 'net/http'
+require 'tempfile'
+
+module Uploadcare
+  module Rails
+    module ActiveStorage
+      class UploadcarePreviewer < ::ActiveStorage::Previewer
+        class << self
+          def accept?(blob)
+            !!(uploadcare_blob?(blob) && pdf?(blob.content_type))
+          end
+
+          def uploadcare_blob?(blob)
+            blob.service.is_a?(::ActiveStorage::Service::UploadcareService)
+          rescue NameError
+            false
+          end
+
+          def pdf?(content_type)
+            Marcel::Magic.child?(content_type, 'application/pdf')
+          end
+        end
+
+        def preview(**options)
+          open_preview_io(preview_url) do |output|
+            yield io: output, filename: "#{blob.filename.base}.png", content_type: 'image/png', **options
+          end
+        end
+
+        private
+
+        def preview_url
+          file = Uploadcare::FileApi.get_file(uploadcare_uuid)
+          "#{file.cdn_url}-/document/-/format/png/-/page/1/"
+        end
+
+        def uploadcare_uuid
+          blob.metadata['uploadcare_uuid'].presence || blob.key
+        end
+
+        def open_preview_io(url)
+          tempfile = Tempfile.open(['uploadcare-preview', '.png'], tmpdir)
+          tempfile.binmode
+
+          response = http_get(url)
+          raise ::ActiveStorage::PreviewError, "Uploadcare preview fetch failed: #{response.code}" unless response.is_a?(Net::HTTPSuccess)
+
+          tempfile.write(response.body)
+          tempfile.rewind
+          yield tempfile
+        ensure
+          tempfile.close! if tempfile
+        end
+
+        def http_get(url, limit = 5)
+          raise ::ActiveStorage::PreviewError, 'Uploadcare preview redirect limit exceeded' if limit.zero?
+
+          uri = URI.parse(url)
+          response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == 'https') do |http|
+            http.request(Net::HTTP::Get.new(uri))
+          end
+
+          return http_get(response['location'], limit - 1) if response.is_a?(Net::HTTPRedirection)
+
+          response
+        end
+      end
+    end
+  end
+end

lib/uploadcare/rails/active_storage/variant_remote_processing.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'tempfile'
+
+module Uploadcare
+  module Rails
+    module ActiveStorage
+      module VariantRemoteProcessing
+        private
+
+        def process
+          return super unless uploadcare_service?(service)
+
+          download_transformed_uploadcare_image do |output|
+            service.upload(key, output, content_type: content_type)
+          end
+        end
+
+        def uploadcare_service?(service_object)
+          service_object.is_a?(::ActiveStorage::Service::UploadcareService)
+        rescue NameError
+          false
+        end
+
+        def download_transformed_uploadcare_image
+          tempfile = Tempfile.open(['uploadcare-variant', ".#{variation.format}"], Dir.tmpdir)
+          tempfile.binmode
+
+          response = http_get(variant_source_url)
+          raise ::ActiveStorage::IntegrityError, "Uploadcare variant fetch failed: #{response.code}" unless response.is_a?(Net::HTTPSuccess)
+
+          tempfile.write(response.body)
+          tempfile.rewind
+          yield tempfile
+        ensure
+          tempfile.close! if tempfile
+        end
+
+        def variant_source_url
+          file = Uploadcare::Rails::File.new({ uuid: uploadcare_uuid })
+          file.transform_url(uploadcare_transformations)
+        end
+
+        def uploadcare_uuid
+          blob.metadata['uploadcare_uuid'].presence || blob.key
+        end
+
+        def uploadcare_transformations
+          mapped = variation.transformations.deep_symbolize_keys.except(:format)
+          resize_to_limit = mapped.delete(:resize_to_limit)
+          resize_to_fill = mapped.delete(:resize_to_fill)
+
+          if resize_to_limit.present?
+            width, height = resize_to_limit
+            mapped[:resize] = [width, height].compact.join('x')
+          end
+
+          if resize_to_fill.present?
+            width, height = resize_to_fill
+            mapped[:scale_crop] = {
+              dimensions: [width, height].compact.join('x'),
+              offsets: '50%,50%'
+            }
+          end
+
+          mapped
+        end
+
+        def http_get(url, limit = 5)
+          raise ::ActiveStorage::IntegrityError, 'Uploadcare variant redirect limit exceeded' if limit.zero?
+
+          uri = URI.parse(url)
+          response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == 'https') do |http|
+            http.request(Net::HTTP::Get.new(uri))
+          end
+
+          return http_get(response['location'], limit - 1) if response.is_a?(Net::HTTPRedirection)
+
+          response
+        end
+      end
+    end
+  end
+end

lib/uploadcare/rails/engine.rb

@@ -28,6 +28,15 @@ class Engine < ::Rails::Engine
           require 'uploadcare/rails/mongoid/mount_uploadcare_file_group'
         end
       end
+
+      initializer 'uploadcare-rails.active_storage' do
+        require 'uploadcare/rails/active_storage/integration'
+
+        config.after_initialize do |app|
+          previewers = app.config.active_storage.respond_to?(:previewers) ? app.config.active_storage.previewers : nil
+          Uploadcare::Rails::ActiveStorage::Integration.install!(previewers: previewers)
+        end
+      end
     end
   end
 end

spec/uploadcare/rails/active_storage/integration_spec.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'uploadcare/rails/active_storage/integration'
+
+RSpec.describe Uploadcare::Rails::ActiveStorage::Integration do
+  describe '.install_previewer' do
+    it 'adds uploadcare previewer once' do
+      previewers = []
+
+      described_class.install_previewer(previewers)
+      described_class.install_previewer(previewers)
+
+      expect(previewers.count(Uploadcare::Rails::ActiveStorage::UploadcarePreviewer)).to eq(1)
+    end
+
+    it 'does not fail when previewers is nil' do
+      expect { described_class.install_previewer(nil) }.not_to raise_error
+    end
+  end
+
+  describe '.install_variant_remote_processing' do
+    it 'prepends remote processing module once' do
+      stub_const('ActiveStorage::Variant', Class.new)
+
+      described_class.install_variant_remote_processing
+      described_class.install_variant_remote_processing
+
+      expect(ActiveStorage::Variant.ancestors.count(Uploadcare::Rails::ActiveStorage::VariantRemoteProcessing)).to eq(1)
+    end
+  end
+end

spec/uploadcare/rails/active_storage/uploadcare_previewer_spec.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'active_storage/errors'
+require 'active_storage/service/uploadcare_service'
+require 'uploadcare/rails/active_storage/uploadcare_previewer'
+
+RSpec.describe Uploadcare::Rails::ActiveStorage::UploadcarePreviewer do
+  let(:service) { ActiveStorage::Service::UploadcareService.new(public_key: 'demopublickey', secret_key: 'demosecretkey') }
+  let(:uuid) { '2d33999d-c74a-4ff9-99ea-abc23496b052' }
+  let(:filename) { double(base: 'report') }
+  let(:blob) do
+    double(
+      service: service,
+      content_type: 'application/pdf',
+      metadata: { 'uploadcare_uuid' => uuid },
+      key: 'fallback-key',
+      filename: filename
+    )
+  end
+
+  describe '.accept?' do
+    it 'accepts uploadcare-backed pdf blobs' do
+      expect(described_class.accept?(blob)).to eq(true)
+    end
+
+    it 'rejects non-pdf blobs' do
+      image_blob = double(service: service, content_type: 'image/png')
+      expect(described_class.accept?(image_blob)).to eq(false)
+    end
+  end
+
+  describe '#preview' do
+    it 'yields png preview attachable payload' do
+      previewer = described_class.new(blob)
+      allow(Uploadcare::FileApi).to receive(:get_file).with(uuid).and_return(double(cdn_url: "https://ucarecdn.com/#{uuid}/"))
+
+      response = Net::HTTPOK.new('1.1', '200', 'OK')
+      allow(response).to receive(:body).and_return('png-preview-data')
+      allow(previewer).to receive(:http_get).and_return(response)
+
+      yielded = nil
+      previewer.preview do |attachable|
+        yielded = attachable
+        expect(attachable[:io].read).to eq('png-preview-data')
+      end
+
+      expect(yielded[:filename].to_s).to eq('report.png')
+      expect(yielded[:content_type]).to eq('image/png')
+    end
+  end
+end

spec/uploadcare/rails/active_storage/variant_remote_processing_spec.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'active_storage/errors'
+require 'active_storage/service/uploadcare_service'
+require 'uploadcare/rails/active_storage/variant_remote_processing'
+
+RSpec.describe Uploadcare::Rails::ActiveStorage::VariantRemoteProcessing do
+  let(:service) { ActiveStorage::Service::UploadcareService.new(public_key: 'demopublickey', secret_key: 'demosecretkey') }
+  let(:uuid) { '2d33999d-c74a-4ff9-99ea-abc23496b052' }
+
+  let(:variant_host_class) do
+    Class.new do
+      prepend Uploadcare::Rails::ActiveStorage::VariantRemoteProcessing
+
+      attr_reader :service, :blob, :variation
+
+      def initialize(service:, blob:, variation:)
+        @service = service
+        @blob = blob
+        @variation = variation
+      end
+
+      def key
+        'variant-key'
+      end
+
+      def content_type
+        'image/png'
+      end
+
+      def process
+        :base_process_called
+      end
+    end
+  end
+
+  let(:blob) { double(metadata: { 'uploadcare_uuid' => uuid }, key: 'blob-key') }
+  let(:variation) { double(format: 'png', transformations: { resize_to_limit: [320, 320], quality: 'smart' }) }
+
+  it 'downloads transformed image from uploadcare and uploads variant to service' do
+    host = variant_host_class.new(service: service, blob: blob, variation: variation)
+
+    allow(service).to receive(:upload)
+
+    file = instance_double(Uploadcare::Rails::File)
+    allow(Uploadcare::Rails::File).to receive(:new).with({ uuid: uuid }).and_return(file)
+    allow(file).to receive(:transform_url).with(hash_including(resize: '320x320', quality: 'smart')).and_return("https://ucarecdn.com/#{uuid}/-/resize/320x320/-/quality/smart/")
+
+    response = Net::HTTPOK.new('1.1', '200', 'OK')
+    allow(response).to receive(:body).and_return('transformed-bytes')
+    allow(host).to receive(:http_get).and_return(response)
+
+    host.send(:process)
+
+    expect(service).to have_received(:upload).with('variant-key', anything, content_type: 'image/png')
+  end
+
+  it 'maps resize_to_fill into uploadcare scale_crop operation' do
+    fill_variation = double(format: 'png', transformations: { resize_to_fill: [200, 100] })
+    host = variant_host_class.new(service: service, blob: blob, variation: fill_variation)
+
+    mapped = host.send(:uploadcare_transformations)
+
+    expect(mapped[:scale_crop]).to eq({ dimensions: '200x100', offsets: '50%,50%' })
+  end
+
+  it 'falls back to base process when service is not uploadcare service' do
+    non_uploadcare_service = Object.new
+    host = variant_host_class.new(service: non_uploadcare_service, blob: blob, variation: variation)
+
+    expect(host.send(:process)).to eq(:base_process_called)
+  end
+end