active_storage-crucible 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9763344d4e3be738a0841cc75dec7ea5072883274c7f5a56eb71ff4b2ba53981
+  data.tar.gz: 00e8ebe2a8df40a423a77744f886ea46b31fa686798979d7438fa025f6df17ab
+SHA512:
+  metadata.gz: c04894bc2165844b26a65e47096c0199bae1b3ff123597c9d0db5dcccff460c18e24f663fdb141b44b37e91d0bc2221c17139f0824df09c5e4e98138ea1b2009
+  data.tar.gz: 49deabd5e626ae306d2dca49e3906fd0580bbf186977e2ccc821bf8226c4ce003d9e237470687709b2bdb28f6057cbac762de0279ecfc110dafd1371fd115f33

data/.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: ["3.3", "3.4", "4.0"]
+        appraisal: ["rails-7.2", "rails-8.0", "rails-8.1"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+
+      - run: bundle exec appraisal ${{ matrix.appraisal }} bundle install
+      - run: bundle exec appraisal ${{ matrix.appraisal }} rspec

data/.ruby-gemset

@@ -0,0 +1 @@
+active_storage-crucible

data/.ruby-version

@@ -0,0 +1 @@
+ruby-3.4.2

data/Appraisals

@@ -0,0 +1,11 @@
+appraise "rails-7.2" do
+  gem "rails", "~> 7.2.0"
+end
+
+appraise "rails-8.0" do
+  gem "rails", "~> 8.0.0"
+end
+
+appraise "rails-8.1" do
+  gem "rails", "~> 8.1.0"
+end

data/CLAUDE.md

@@ -0,0 +1,41 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+A Rails gem that bridges Active Storage with the Crucible image/video processing service. Provides an `AsyncVariants` transformer that delegates variant processing to Crucible via HTTP, plus video preview support and presigned S3 URL generation. Depends on `active_storage-async_variants` (from GitHub).
+
+## Commands
+
+```bash
+bundle exec rspec                                    # Run all specs
+bundle exec rspec spec/active_storage/crucible_spec.rb  # Run specific spec file
+bundle exec rake                                     # Default task runs specs
+```
+
+## Architecture
+
+The gem is a Rails Engine that prepends extensions onto Active Storage classes:
+
+- **`Crucible` module** (`lib/active_storage/crucible.rb`) — Engine setup, configurable `endpoint` for the Crucible service
+- **`Transformer`** (`lib/active_storage/crucible/transformer.rb`) — Inherits from `ActiveStorage::AsyncVariants::Transformer`. Creates a placeholder output blob, generates presigned GET/PUT URLs, then POSTs to Crucible's `/image/variant` or `/video/variant` endpoint. Crucible processes asynchronously and calls back when done.
+- **`PreviewExtension`** (`lib/active_storage/crucible/preview_extension.rb`) — Prepended onto `ActiveStorage::Preview`. For video blobs on S3, creates placeholder blobs and POSTs to `/video/preview`. Returns the original blob URL as fallback while processing.
+- **`BlobExtension`** (`lib/active_storage/crucible/blob_extension.rb`) — Prepended onto `ActiveStorage::Blob`. Makes videos report as `variable?` and `previewable?` when Crucible is configured.
+- **`Client`** (`lib/active_storage/crucible/client.rb`) — Simple `Net::HTTP` wrapper that POSTs JSON to Crucible
+- **`PresignedUrl`** (`lib/active_storage/crucible/presigned_url.rb`) — Generates presigned S3 URLs for GET/PUT access to blobs
+
+### Processing Flow
+
+1. Variant defined with `transformer: ActiveStorage::Crucible::Transformer`
+2. `async_variants` enqueues a `ProcessJob` which calls `Transformer#initiate`
+3. Transformer creates placeholder blob, gets presigned URLs, POSTs to Crucible
+4. Crucible processes the file and POSTs back to the callback URL
+5. `async_variants` callback controller marks variant as processed
+
+## Test Setup
+
+- RSpec with `rspec-rails`, SQLite3 in-memory database
+- Dummy Rails app in `spec/dummy/` with a `User` model having `avatar` and `video` attachments
+- Test schema defined in `spec/support/active_record.rb`
+- Tests mock `Client.post` and `PresignedUrl.for` to avoid real HTTP/S3 calls

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Micah Geisel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,143 @@
+# ActiveStorage::Crucible
+
+An Active Storage transformer that sends image and video variant processing to the [Crucible](https://github.com/botandrose/crucible) web service. Built on top of [active_storage-async_variants](https://github.com/botandrose/active_storage-async_variants).
+
+## The Problem
+
+Processing image variants and video previews on your Rails server ties up workers and requires installing tools like `vips` and `ffmpeg` in production. Crucible is an external service that handles these transformations -- but you need a bridge between Active Storage's variant system and Crucible's HTTP API.
+
+This gem provides that bridge. It implements the `async_variants` external transformer interface, delegating all image/video processing to Crucible via presigned S3 URLs.
+
+## Installation
+
+```ruby
+gem "active_storage-crucible"
+```
+
+Requires an S3-compatible storage service (the gem generates presigned URLs for Crucible to read source files and write results).
+
+### Configuration
+
+```ruby
+# config/initializers/crucible.rb
+ActiveStorage::Crucible.endpoint = "https://crucible.example.com"
+```
+
+Or with a block:
+
+```ruby
+ActiveStorage::Crucible.configure do |config|
+  config.endpoint = ENV["CRUCIBLE_ENDPOINT"]
+end
+```
+
+## Usage
+
+### Image and Video Variants
+
+Use `ActiveStorage::Crucible::Transformer` as the transformer for any variant:
+
+```ruby
+class User < ApplicationRecord
+  has_one_attached :avatar do |attachable|
+    attachable.variant :thumb,
+      resize_to_limit: [100, 100],
+      format: :webp,
+      transformer: ActiveStorage::Crucible::Transformer,
+      fallback: :original
+  end
+
+  has_one_attached :video do |attachable|
+    attachable.variant :web,
+      resize_to_limit: [1280, 720],
+      format: :webp,
+      transformer: ActiveStorage::Crucible::Transformer,
+      fallback: :original
+  end
+end
+```
+
+The transformer auto-detects image vs. video based on the blob's content type and calls the appropriate Crucible endpoint (`/image/variant` or `/video/variant`).
+
+In views, use standard Active Storage helpers:
+
+```erb
+<%= image_tag user.avatar.variant(:thumb).url %>
+```
+
+While the variant is processing, this serves the original file. Once Crucible finishes and calls back, it serves the processed variant.
+
+### Video Previews
+
+The gem also extends `ActiveStorage::Preview` to process video previews through Crucible. This happens automatically for video blobs on S3-compatible services -- no extra configuration needed.
+
+```erb
+<%= image_tag user.video.preview(resize_to_limit: [640, 480], format: :webp).url %>
+```
+
+While the preview is processing, the original video URL is served as a fallback.
+
+## How It Works
+
+### Variant flow
+
+1. A file is attached to a model with a Crucible-backed variant defined
+2. `async_variants` enqueues a background job for the variant
+3. The job calls `Crucible::Transformer#initiate`, which:
+   - Creates a placeholder output blob in the database
+   - Attaches it to the variant record
+   - Generates presigned GET/PUT URLs for the source and output blobs
+   - POSTs to Crucible with the URLs, dimensions, format, and a signed callback URL
+4. Crucible processes the image/video, uploads the result to the presigned PUT URL
+5. Crucible POSTs to the callback URL with `{"status": "success"}`
+6. The `async_variants` callback controller marks the variant record as processed
+
+### Preview flow
+
+1. A video preview is requested in a view
+2. `PreviewExtension#process` creates placeholder blobs for the preview image and its variant
+3. POSTs to Crucible's `/video/preview` endpoint with presigned URLs and a callback URL
+4. Crucible extracts a frame, resizes it, uploads both the preview image and variant
+5. Crucible POSTs to the callback URL to mark the variant as processed
+
+### What gets sent to Crucible
+
+**Variant requests** (`POST /image/variant` or `/video/variant`):
+
+```json
+{
+  "blob_url": "https://s3.example.com/source?presigned...",
+  "variant_url": "https://s3.example.com/output?presigned...",
+  "dimensions": "100x100",
+  "rotation": 0,
+  "format": "webp",
+  "callback_url": "https://app.example.com/active_storage/async_variants/callbacks/signed-token"
+}
+```
+
+**Preview requests** (`POST /video/preview`):
+
+```json
+{
+  "blob_url": "https://s3.example.com/source?presigned...",
+  "preview_image_url": "https://s3.example.com/preview?presigned...",
+  "preview_image_variant_url": "https://s3.example.com/variant?presigned...",
+  "dimensions": "640x480",
+  "rotation": 0,
+  "callback_url": "https://app.example.com/active_storage/async_variants/callbacks/signed-token"
+}
+```
+
+## Callbacks
+
+Callbacks are handled by `active_storage-async_variants`, not this gem. The callback endpoint is auto-mounted at:
+
+```
+POST /active_storage/async_variants/callbacks/:token
+```
+
+Crucible must POST `{"status": "success"}` or `{"status": "failed", "error": "..."}` to this URL after processing. The token is signed -- no authentication headers are needed. The endpoint must be publicly reachable by the Crucible service.
+
+## License
+
+MIT

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/gemfiles/rails_7.2.gemfile

@@ -0,0 +1,14 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "appraisal"
+gem "irb"
+gem "rake", "~> 13.0"
+gem "rspec", "~> 3.0"
+gem "rspec-rails"
+gem "simplecov"
+gem "sqlite3"
+gem "rails", "~> 7.2.0"
+
+gemspec path: "../"

data/gemfiles/rails_8.0.gemfile

@@ -0,0 +1,14 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "appraisal"
+gem "irb"
+gem "rake", "~> 13.0"
+gem "rspec", "~> 3.0"
+gem "rspec-rails"
+gem "simplecov"
+gem "sqlite3"
+gem "rails", "~> 8.0.0"
+
+gemspec path: "../"

data/gemfiles/rails_8.1.gemfile

@@ -0,0 +1,14 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "appraisal"
+gem "irb"
+gem "rake", "~> 13.0"
+gem "rspec", "~> 3.0"
+gem "rspec-rails"
+gem "simplecov"
+gem "sqlite3"
+gem "rails", "~> 8.1.0"
+
+gemspec path: "../"

data/lib/active_storage/crucible/blob_extension.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module ActiveStorage
+  module Crucible
+    module BlobExtension
+      def variable?
+        super || crucible_transformable?
+      end
+
+      def representation(transformations)
+        variation = ActiveStorage::Variation.wrap(transformations)
+        if crucible_transformable? && video_output_format?(variation.transformations[:format])
+          variant transformations
+        else
+          super
+        end
+      end
+
+      private
+
+      def crucible_transformable?
+        (image? || video?) && ActiveStorage::Crucible.endpoint.present?
+      end
+
+      def video_output_format?(format)
+        format.to_s.in?(%w[mp4 webm mov avi mkv])
+      end
+    end
+  end
+end

data/lib/active_storage/crucible/client.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+
+module ActiveStorage
+  module Crucible
+    class Client
+      def post(url, body)
+        uri = URI.parse(url)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        request = Net::HTTP::Post.new(uri.request_uri, "Content-Type": "application/json")
+        request.body = body.to_json
+        response = http.request(request)
+        unless response.code.start_with?("2")
+          raise "Crucible request failed: #{response.code} #{response.body}"
+        end
+        response
+      end
+    end
+  end
+end

data/lib/active_storage/crucible/presigned_url.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module ActiveStorage
+  module Crucible
+    module PresignedUrl
+      def self.for(blob, method: :put, expires_in: 1.hour)
+        case method
+        when :get
+          blob.url(expires_in: expires_in)
+        when :put
+          service = blob.service
+          object = service.send(:object_for, blob.key)
+          object.presigned_url(:put, expires_in: expires_in.to_i, content_type: blob.content_type)
+        end
+      end
+    end
+  end
+end

data/lib/active_storage/crucible/transformer.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require "active_storage/async_variants/transformer"
+
+module ActiveStorage
+  module Crucible
+    class Transformer < ActiveStorage::AsyncVariants::Transformer
+      def initiate(source_url:, callback_url:, variant_record_id:, **options)
+        variant_record = ActiveStorage::VariantRecord.find(variant_record_id)
+        blob = variant_record.blob
+
+        rotation = blob.metadata["rotation"].to_i
+        video_format = blob.metadata["video_format"]
+
+        source_url = PresignedUrl.for(blob, method: :get)
+        dimensions = extract_dimensions(options)
+
+        if blob.video? && !video_output_format?(options[:format])
+          output_blob = create_output_blob(blob, variant_record, options)
+          variant_url = PresignedUrl.for(output_blob, method: :put)
+
+          preview_blob = ActiveStorage::Blob.create_before_direct_upload!(
+            filename: "#{blob.filename.base}.jpg",
+            content_type: "image/jpeg",
+            service_name: blob.service_name,
+            byte_size: 0,
+            checksum: "0",
+          )
+          preview_blob.metadata[:analyzed] = true
+
+          # Pass the requested variant format so Crucible writes the right
+          # file extension via vips and PUTs with a Content-Type that matches
+          # what we signed the variant URL for (anything else gives
+          # 403 SignatureDoesNotMatch). Crucible derives the Content-Type
+          # from `format` via Marcel so there's a single source of truth.
+          Client.new.post("#{endpoint}/video/preview", {
+            blob_url: source_url,
+            dimensions: dimensions,
+            rotation: rotation,
+            format: options[:format]&.to_s,
+            preview_image_url: PresignedUrl.for(preview_blob, method: :put),
+            preview_image_variant_url: variant_url,
+            callback_url: callback_url,
+          })
+        elsif blob.video?
+          format = video_format || options[:format].to_s
+          output_blob = create_output_blob(blob, variant_record, options.merge(format: format))
+          variant_url = PresignedUrl.for(output_blob, method: :put)
+
+          # Only pass `format` -- Crucible derives Content-Type from it via
+          # the same canonical mapping output_content_type uses on this side,
+          # so the PUT header always matches what the URL was signed for.
+          Client.new.post("#{endpoint}/video/variant", {
+            blob_url: source_url,
+            variant_url: variant_url,
+            dimensions: dimensions,
+            rotation: rotation,
+            format: format,
+            callback_url: callback_url,
+          })
+        else
+          output_blob = create_output_blob(blob, variant_record, options)
+          variant_url = PresignedUrl.for(output_blob, method: :put)
+
+          Client.new.post("#{endpoint}/image/variant", {
+            blob_url: source_url,
+            variant_url: variant_url,
+            dimensions: dimensions,
+            rotation: rotation,
+            format: options[:format]&.to_s,
+            callback_url: callback_url,
+          })
+        end
+      end
+
+      def process_preview(blob:, variation:)
+        return if blob.preview_image.attached?
+
+        preview_image_blob = ActiveStorage::Blob.create_before_direct_upload!(
+          filename: "#{blob.filename.base}.jpg",
+          content_type: "image/jpeg",
+          service_name: blob.service_name,
+          byte_size: 0,
+          checksum: "0",
+        )
+        preview_image_blob.metadata[:analyzed] = true
+        blob.preview_image.attach(preview_image_blob)
+
+        variant_record = preview_image_blob.variant_records.create_or_find_by!(variation_digest: variation.digest)
+        return if variant_record.state.in?(%w[processing processed])
+        variant_record.update!(state: "processing")
+
+        variant_blob = ActiveStorage::Blob.create_before_direct_upload!(
+          filename: "#{blob.filename.base}.#{variation.format}",
+          content_type: variation.content_type,
+          service_name: blob.service_name,
+          byte_size: 0,
+          checksum: "0",
+        )
+        variant_blob.metadata[:analyzed] = true
+        variant_record.image.attach(variant_blob)
+
+        rotation = blob.metadata["rotation"].to_i
+        callback_url = ActiveStorage::AsyncVariants.callback_url_for(variant_record)
+        Client.new.post("#{endpoint}/video/preview", {
+          blob_url: PresignedUrl.for(blob, method: :get),
+          dimensions: extract_dimensions(variation.transformations),
+          rotation: rotation,
+          preview_image_url: PresignedUrl.for(preview_image_blob, method: :put),
+          preview_image_variant_url: PresignedUrl.for(variant_blob, method: :put),
+          callback_url: callback_url,
+        })
+      end
+
+      private
+
+      def create_output_blob(blob, variant_record, options)
+        output_blob = ActiveStorage::Blob.create_before_direct_upload!(
+          filename: "#{blob.filename.base}.#{options[:format] || blob.filename.extension}",
+          content_type: output_content_type(options),
+          service_name: blob.service_name,
+          byte_size: 0,
+          checksum: "0",
+        )
+        output_blob.metadata[:analyzed] = true
+        variant_record.image.attach(output_blob)
+        output_blob
+      end
+
+      def endpoint
+        ActiveStorage::Crucible.endpoint
+      end
+
+      def extract_dimensions(options)
+        resize = options[:resize_to_limit] || options[:resize_to_fit] || options[:resize_to_fill]
+        return nil unless resize
+        width, height = resize
+        "#{width}x#{height}"
+      end
+
+      def output_content_type(options)
+        case options[:format]&.to_s
+        when "webp" then "image/webp"
+        when "png" then "image/png"
+        when "jpg", "jpeg" then "image/jpeg"
+        when "gif" then "image/gif"
+        when "mp4" then "video/mp4"
+        when "webm" then "video/webm"
+        else "application/octet-stream"
+        end
+      end
+
+      def video_output_format?(format)
+        format.to_s.in?(%w[mp4 webm mov avi mkv])
+      end
+    end
+  end
+end

data/lib/active_storage/crucible/version.rb

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

data/lib/active_storage/crucible.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "crucible/version"
+require_relative "crucible/client"
+require_relative "crucible/presigned_url"
+require_relative "crucible/transformer"
+require_relative "crucible/blob_extension"
+
+module ActiveStorage
+  module Crucible
+    mattr_accessor :endpoint
+
+    def self.configure
+      yield self
+    end
+
+    class Engine < ::Rails::Engine
+      config.after_initialize do
+        ActiveStorage::Blob.prepend(
+          ActiveStorage::Crucible::BlobExtension
+        )
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,87 @@
+--- !ruby/object:Gem::Specification
+name: active_storage-crucible
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Micah Geisel
+bindir: exe
+cert_chain: []
+date: 2026-06-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activestorage
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: active_storage-async_variants
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+email:
+- micah@botandrose.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/ci.yml"
+- ".ruby-gemset"
+- ".ruby-version"
+- Appraisals
+- CLAUDE.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- gemfiles/rails_7.2.gemfile
+- gemfiles/rails_8.0.gemfile
+- gemfiles/rails_8.1.gemfile
+- lib/active_storage/crucible.rb
+- lib/active_storage/crucible/blob_extension.rb
+- lib/active_storage/crucible/client.rb
+- lib/active_storage/crucible/presigned_url.rb
+- lib/active_storage/crucible/transformer.rb
+- lib/active_storage/crucible/version.rb
+homepage: https://github.com/botandrose/active_storage-crucible
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/botandrose/active_storage-crucible
+  source_code_uri: https://github.com/botandrose/active_storage-crucible
+  changelog_uri: https://github.com/botandrose/active_storage-crucible/blob/master/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.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: Active Storage transformer for the Crucible image/video processing service.
+test_files: []