active_storage-crucible 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2656213e02772d6fa0094857594ad926a718ea12896b9d0398bee0daefe575f6
-  data.tar.gz: e78728082130e9daec29363ce14551a96decb246ebed19f288dd2ba94b2cd6c3
+  metadata.gz: 198afc548c8b397642733f6739431743056cb4057c1c4a446d5570d68710e6d5
+  data.tar.gz: 192a962e2436123deb30f4c8e1ac4e691c885f18dd3da75a71a6e0785b68c1af
 SHA512:
-  metadata.gz: 86a2e01e5d41443a985d0bbf9b8ac362cd2838427f4f96a0b507ccf6b2921d63d3d9dd967cf35ff375d2faede45b6980f10f3bacce02e5e74e5d7e8f0fec3a9f
-  data.tar.gz: 4df7ad1ccc4bb0eaf58025f12b7785aa5247757a265d3220763700d691d80a94f3d646cb4218c8abf622128d215cbabf7d6a974626753744e9329ebc74fa78de
+  metadata.gz: 16631a3fc64fb178429b4f81a27503e78bf529d8b86b9aadced917a1cb4c465b30de4f23c0daf4a98e836e92d9bfce894e1d614dd0e46a272a541d393e2593fa
+  data.tar.gz: 6eae4dcfecdcfc77834bfc4cf4f0c5bde74886792f150316eb3d4c38bac8d93681627ffeab40d05e30c850b7e1fee016194cf801bc8cb0128c85a016454fa669

data/CLAUDE.md

@@ -19,19 +19,31 @@ bundle exec rake                                     # Default task runs specs
 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.
+- **`Transformer`** (`lib/active_storage/crucible/transformer.rb`) — Inherits from `ActiveStorage::AsyncVariants::Transformer`. `#initiate` reads the variant record's blob to pick one of three routes: an image → `/image/variant`; a video → `/video/variant` (transcode); or a video's extracted-frame placeholder → `/video/preview` (the stock preview graph). It creates the placeholder output blob and generates presigned GET/PUT URLs. Crucible processes asynchronously and calls back when done.
+- **`BlobExtension`** (`lib/active_storage/crucible/blob_extension.rb`) — Prepended onto `ActiveStorage::Blob`. Makes videos (and images) report as `variable?`, and videos as `previewable?`, when Crucible is configured — independent of a local ffmpeg, since Crucible extracts frames server-side. `#representation` routes video output formats (mp4/webm/…) to `variant` and everything else to `super`.
 - **`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
+1. Variant defined with `transformer: ActiveStorage::Crucible::Transformer, async: true`
+2. `async_variants`' `ProcessJob` resolves `attachment.representation(name)` and calls `Transformer#initiate`
+3. `#initiate` resolves the source/output blobs, gets presigned URLs, POSTs to Crucible
+4. Crucible processes the file(s) and POSTs back to the callback URL
+5. `async_variants`' callback controller marks the variant processed and reconciles blob metadata
+
+### Video Previews (stock graph)
+
+Because videos are both `previewable?` and `variable?`, an image-format request
+(`representation(:thumb)`) resolves to a **preview**, matching stock Active Storage:
+the frame is persisted as the video's `preview_image` and the variant record hangs
+off the *frame* blob. `#initiate` detects this by finding the `preview_image`
+attachment whose blob is the variant record's blob, then POSTs `/video/preview` with
+both `preview_image_url` (the frame) and `preview_image_variant_url` (the resized
+output). The success callback reconciles both placeholders, so the frame is a
+legitimate persisted preview — not an orphan. A video *output* format
+(`representation(format: :mp4)`) instead resolves to a `variant` and transcodes via
+`/video/variant`, with the record on the video blob.
 
 ## Test Setup
 

data/README.md

@@ -102,11 +102,15 @@ While the preview is processing, the original video URL is served as a fallback.
 
 ### 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
+An image-format variant of a video is a stock `Preview`: the extracted frame is the video blob's `preview_image`, and the variant record hangs off that frame blob.
+
+1. `ProcessJob` resolves the attachment's `representation`, attaches a frame placeholder as the video's `preview_image` if none exists, and creates the variant record on the frame blob
+2. The transformer sees the record's blob is a video's `preview_image` and creates a placeholder output blob for the resized still
+3. POSTs to Crucible's `/video/preview` endpoint with presigned PUT URLs for both the frame and the still, the dimensions, format, rotation, and a signed callback URL
+4. Crucible extracts a frame, resizes it, and uploads both the frame and the still
+5. Crucible POSTs to the callback URL; `async_variants` reconciles both placeholders and marks the record processed
+
+Video-format variants of a video (transcodes) stay on the video blob and go through `/video/variant`.
 
 ### What gets sent to Crucible
 
@@ -132,6 +136,7 @@ While the preview is processing, the original video URL is served as a fallback.
   "preview_image_variant_url": "https://s3.example.com/variant?presigned...",
   "dimensions": "640x480",
   "rotation": 0,
+  "format": "webp",
   "callback_url": "https://app.example.com/active_storage/async_variants/callbacks/signed-token"
 }
 ```

data/lib/active_storage/crucible/blob_extension.rb

@@ -7,6 +7,14 @@ module ActiveStorage
         super || crucible_transformable?
       end
 
+      # Videos are previewable whenever Crucible is configured, regardless of a
+      # local ffmpeg. Crucible extracts the frame server-side, so video->image
+      # representations deterministically take the stock preview path rather than
+      # depending on what's installed on the worker.
+      def previewable?
+        super || (video? && ActiveStorage::Crucible.endpoint.present?)
+      end
+
       def representation(transformations)
         variation = ActiveStorage::Variation.wrap(transformations)
         if crucible_transformable? && video_output_format?(variation.transformations[:format])

data/lib/active_storage/crucible/transformer.rb

@@ -5,114 +5,101 @@ require "active_storage/async_variants/transformer"
 module ActiveStorage
   module Crucible
     class Transformer < ActiveStorage::AsyncVariants::Transformer
+      # The variant_record's blob tells us which graph we're in:
+      #
+      # - a frame placeholder attached as a video's preview_image -> the stock
+      #   preview path. Crucible extracts the frame (persisted as preview_image)
+      #   and the resized variant in one /video/preview call.
+      # - a video blob -> the "video is variable" transcode path (/video/variant).
+      # - a plain image -> /image/variant.
       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,
-          })
+        if (video = preview_source_video(blob))
+          initiate_video_preview(video, blob, variant_record, options, 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,
-          })
+          initiate_video_variant(blob, variant_record, options, 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,
-          })
+          initiate_image_variant(blob, variant_record, options, callback_url)
         end
       end
 
-      def process_preview(blob:, variation:)
-        return if blob.preview_image.attached?
+      private
 
-        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",
+      # When +blob+ is the extracted-frame placeholder (the video's preview_image),
+      # returns the source video blob; otherwise nil.
+      def preview_source_video(blob)
+        attachment = ActiveStorage::Attachment.find_by(
+          name: "preview_image",
+          record_type: "ActiveStorage::Blob",
+          blob_id: blob.id,
         )
-        preview_image_blob.metadata[:analyzed] = true
-        blob.preview_image.attach(preview_image_blob)
+        attachment && ActiveStorage::Blob.find_by(id: attachment.record_id)
+      end
 
-        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")
+      # Crucible writes the full frame to the preview_image placeholder and the
+      # resized variant to the output blob in a single call; the success callback
+      # reconciles both (byte_size/checksum for the variant, preview_image_* for
+      # the frame).
+      def initiate_video_preview(video, frame_blob, variant_record, options, callback_url)
+        output_blob = output_blob_for(video, variant_record, options)
+
+        # 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: PresignedUrl.for(video, method: :get),
+          dimensions: extract_dimensions(options),
+          rotation: video.metadata["rotation"].to_i,
+          format: options[:format]&.to_s,
+          preview_image_url: PresignedUrl.for(frame_blob, method: :put),
+          preview_image_variant_url: PresignedUrl.for(output_blob, method: :put),
+          callback_url: callback_url,
+        })
+      end
 
-        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)
+      def initiate_video_variant(blob, variant_record, options, callback_url)
+        format = blob.metadata["video_format"] || options[:format].to_s
+        output_blob = output_blob_for(blob, variant_record, options.merge(format: format))
 
-        rotation = blob.metadata["rotation"].to_i
-        callback_url = ActiveStorage::AsyncVariants.callback_url_for(variant_record)
-        Client.new.post("#{endpoint}/video/preview", {
+        # 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: 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),
+          variant_url: PresignedUrl.for(output_blob, method: :put),
+          dimensions: extract_dimensions(options),
+          rotation: blob.metadata["rotation"].to_i,
+          format: format,
           callback_url: callback_url,
         })
       end
 
-      private
+      def initiate_image_variant(blob, variant_record, options, callback_url)
+        output_blob = output_blob_for(blob, variant_record, options)
+
+        Client.new.post("#{endpoint}/image/variant", {
+          blob_url: PresignedUrl.for(blob, method: :get),
+          variant_url: PresignedUrl.for(output_blob, method: :put),
+          dimensions: extract_dimensions(options),
+          rotation: blob.metadata["rotation"].to_i,
+          format: options[:format]&.to_s,
+          callback_url: callback_url,
+        })
+      end
+
+      # A fresh blob would purge this one before an in-flight run writes to it, orphaning the file.
+      # The row lock makes a racing run reuse that blob too, and a purged record raise instead of gaining an orphan.
+      def output_blob_for(blob, variant_record, options)
+        variant_record.with_lock do
+          existing = variant_record.image.blob
+          next existing if existing&.content_type == output_content_type(options)
+          create_output_blob(blob, variant_record, options)
+        end
+      end
 
       def create_output_blob(blob, variant_record, options)
         output_blob = ActiveStorage::Blob.create_before_direct_upload!(
@@ -149,10 +136,6 @@ module ActiveStorage
         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

@@ -2,6 +2,6 @@
 
 module ActiveStorage
   module Crucible
-    VERSION = "0.2.0"
+    VERSION = "0.3.0"
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: active_storage-crucible
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Micah Geisel
 bindir: exe
 cert_chain: []
-date: 2026-08-02 00:00:00.000000000 Z
+date: 2026-11-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activestorage
@@ -29,14 +29,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.10'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.10'
 email:
 - micah@botandrose.com
 executables: []