activestorage-hotcell-client 0.0.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3a1e753c9a98025000a66d4f8aebca975b816b65285c269e8b06f0883843a203
-  data.tar.gz: dae5536d6035f67546136f12ffe1fc52d602bdffc8dd5eeba120fec2313c4cd7
+  metadata.gz: 668902d1347b4f118a31b299534d8b8bedfadd568cf3e4e6e872384ee6d6f83f
+  data.tar.gz: d55b6e9a965f5327fd2d41c2f94bd7a59e6b2af8083ea2a892a9e24b9db423cd
 SHA512:
-  metadata.gz: f39f0f4ecb84fb0898933a4375520bf9bab0b84d86a28bf2df9a3a63f3a9cab90da5477b343f708b0204e3a957d3e8de4814d16a054481b1f17c4a4e7e0ec676
-  data.tar.gz: 8cf8d948c812075b068479e25737a0d43999831f2dea87a018d6d62fe8c1049d96bb27076f88173ed91d4bd4ae1939669d768402ee9e8ce8e5c215c14014d909
+  metadata.gz: bad8f45d4e713516eb6e0c27a2a0b7ae764f48bfbffe4dd3cf81d73091276f274798a8a72eda5d45212443a120c649645c2f2861de5dad088e903aa77f6f82ae
+  data.tar.gz: 359071c3cae9ed347112afe70cd1a45d9dbbda0e1adca966d03fbcb887e16a56bebfc934997c62325b846a2560315c3f617e528cdc779303cf78aab25c0ac187

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 37signals, LLC
+
+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,3 @@
+# activestorage-hotcell-client
+
+Part of [HotCell](https://github.com/basecamp/hotcell). See the repository README.

data/lib/active_storage/hot_cell/client/analyzers/analyzing.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "active_storage"
+require "active_storage/analyzer"
+require "active_support/core_ext/class/attribute"
+
+module ActiveStorage
+  module HotCell
+    module Client
+      module Analyzers
+        # What every analyzer here shares: one round trip to the cell, and the permanent-versus-transient
+        # failure split. An analyzer names the client it asks and the KEYS it slices the cell's superset
+        # down to — the cell knows more than Rails writes, and an extra key would change the shape of every
+        # blob's metadata.
+        #
+        # **Which way `metadata` fails is the whole design of the method.** The built-in vips analyzer rescues
+        # every Vips::Error and returns an empty hash, which Rails then merges with `analyzed: true` — so an
+        # undecodable image is recorded as successfully analyzed, forever, and nothing ever re-enqueues
+        # AnalyzeJob. That is right for a permanent verdict and catastrophic for a transient one.
+        #
+        # So a permanent failure follows the built-in behaviour and lets the blob be marked analyzed, with the
+        # reason written to the log so it can be re-decided later against a newer library. A transient failure
+        # is not rescued at all, which is what leaves the blob `analyzed: false` and eligible to be tried
+        # again.
+        module Analyzing
+          def self.included(analyzer)
+            analyzer.class_attribute :client, instance_accessor: false
+          end
+
+          def metadata
+            measured.slice(*self.class::KEYS)
+          rescue self.class.client.cell.permanent => error
+            logger.warn "hotcell: #{blob.filename} could not be analyzed and will not be retried: #{error.message}"
+            {}
+          end
+
+          private
+            def measured
+              download_blob_to_tempfile do |file|
+                File.open(file.path, "rb") { |readable| self.class.client.perform_in_hotcell [ readable ], [], payload }
+              end
+            end
+
+            # What travels with the request beyond the descriptor. Nothing, for an analyzer that has no
+            # configuration to carry; the media analyzers override it with the application's ffprobe arguments.
+            def payload
+              {}
+            end
+        end
+      end
+    end
+  end
+end

data/lib/active_storage/hot_cell/client/analyzers/audio/ffprobe.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "active_storage/hot_cell/client/operations"
+require "active_storage/hot_cell/client/analyzers/audio"
+require "active_storage/hot_cell/client/analyzers/probing"
+
+module ActiveStorage
+  module HotCell
+    module Client
+      module Analyzers
+        class Audio
+          # What an application lists in `config.active_storage.analyzers`.
+          #
+          #   config.active_storage.analyzers = [ ActiveStorage::HotCell::Client::Analyzers::Audio::Ffprobe, ... ]
+          #
+          # Shares the probe operation with the video analyzer; see Analyzers::Video::Ffprobe.
+          class Ffprobe < Audio
+            include Probing
+
+            self.client = Operations::Analyzers::Media::Ffprobe
+          end
+
+          FFprobe = Ffprobe
+        end
+      end
+    end
+  end
+end

data/lib/active_storage/hot_cell/client/analyzers/audio.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "active_storage"
+require "active_storage/analyzer"
+
+require "active_storage/hot_cell/client/analyzers/analyzing"
+
+module ActiveStorage
+  module HotCell
+    module Client
+      module Analyzers
+        # Rails' AudioAnalyzer, moved to the cell the way the video analyzer is.
+        #
+        # Rails' audio keys, minus `tags`: Rails writes raw container metadata into the database, and the
+        # cell refuses it because those bytes are attacker-controlled.
+        class Audio < ActiveStorage::Analyzer
+          include Analyzing
+
+          KEYS = %i[ duration bit_rate sample_rate ].freeze
+
+          def self.accept?(blob)
+            blob.audio?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_storage/hot_cell/client/analyzers/image/magick.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "active_storage/hot_cell/client/operations"
+require "active_storage/hot_cell/client/analyzers/image"
+
+module ActiveStorage
+  module HotCell
+    module Client
+      module Analyzers
+        class Image
+          # What an application on ImageMagick lists in `config.active_storage.analyzers`.
+          #
+          #   config.active_storage.analyzers = [ ActiveStorage::HotCell::Client::Analyzers::Image::Magick, ... ]
+          #
+          # It shares the base's width-and-height slice and its permanent-versus-transient split, differing
+          # only in the client it reaches.
+          class Magick < Image
+            self.client = Operations::Analyzers::Image::Magick
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_storage/hot_cell/client/analyzers/image/vips.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "active_storage/hot_cell/client/operations"
+require "active_storage/hot_cell/client/analyzers/image"
+
+module ActiveStorage
+  module HotCell
+    module Client
+      module Analyzers
+        class Image
+          # What an application lists in `config.active_storage.analyzers`.
+          #
+          #   config.active_storage.analyzers = [ ActiveStorage::HotCell::Client::Analyzers::Image::Vips, ... ]
+          #
+          # The library itself is in the cell, so what this names is which operation to ask.
+          class Vips < Image
+            self.client = Operations::Analyzers::Image::Vips
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_storage/hot_cell/client/analyzers/image.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "active_storage"
+require "active_storage/analyzer"
+
+require "active_storage/hot_cell/client/analyzers/analyzing"
+
+module ActiveStorage
+  module HotCell
+    module Client
+      module Analyzers
+        # Shipping an analyzer is mandatory rather than a nicety. The built-in image analyzers gate `accept?` on
+        # `variant_processor` being `:vips` or `:mini_magick`, so a class value makes all of them decline,
+        # `analyzer_class` falls through to NullAnalyzer, and the blob is marked analyzed with no dimensions at
+        # all. rails/rails#58384 leaves that to us deliberately.
+        #
+        # This holds the Rails-facing contract — which blobs are accepted, which keys are written. A leaf names
+        # the client that reaches its toolchain and differs in nothing else.
+        class Image < ActiveStorage::Analyzer
+          include Analyzing
+
+          # Width and height, which is exactly what the built-in analyzer returns. The cell knows more — page
+          # count, whether the image is animated — and surfacing it would change the shape of every blob's
+          # metadata.
+          KEYS = %i[ width height ].freeze
+
+          def self.accept?(blob)
+            blob.image?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_storage/hot_cell/client/analyzers/probing.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "active_storage/hot_cell/client/tool_arguments"
+
+module ActiveStorage
+  module HotCell
+    module Client
+      module Analyzers
+        # What the two ffprobe analyzers add to the shared round trip: `config.active_storage.ffprobe_arguments`,
+        # which Rails' own video and audio analyzers splice before the input path, carried to the cell so it
+        # can do the same. Split here, the way Rails splits it, and omitted entirely when it is empty.
+        module Probing
+          private
+            def payload
+              ToolArguments.payload(:probe_arguments, ActiveStorage.ffprobe_arguments)
+            end
+        end
+      end
+    end
+  end
+end

data/lib/active_storage/hot_cell/client/analyzers/video/ffprobe.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "active_storage/hot_cell/client/operations"
+require "active_storage/hot_cell/client/analyzers/video"
+require "active_storage/hot_cell/client/analyzers/probing"
+
+module ActiveStorage
+  module HotCell
+    module Client
+      module Analyzers
+        class Video
+          # What an application lists in `config.active_storage.analyzers`.
+          #
+          #   config.active_storage.analyzers = [ ActiveStorage::HotCell::Client::Analyzers::Video::Ffprobe, ... ]
+          #
+          # One probe operation serves this and the audio analyzer: ffprobe reports both stream kinds in one
+          # pass, and each analyzer slices the shared result to its own keys.
+          class Ffprobe < Video
+            include Probing
+
+            self.client = Operations::Analyzers::Media::Ffprobe
+          end
+
+          FFprobe = Ffprobe
+        end
+      end
+    end
+  end
+end

data/lib/active_storage/hot_cell/client/analyzers/video.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "active_storage"
+require "active_storage/analyzer"
+
+require "active_storage/hot_cell/client/analyzers/analyzing"
+
+module ActiveStorage
+  module HotCell
+    module Client
+      module Analyzers
+        # Rails' VideoAnalyzer shells out to ffprobe inside the application process. Moving ffprobe into a
+        # cell means this has to move with it, or an application that adopts hotcell still analyzes media in
+        # its own process and cannot take ffprobe out of its image — the incomplete move for exactly the
+        # media type a cell exists to isolate.
+        #
+        # Rails' exact video keys, sliced from the cell's superset. The cell already applied the rotation
+        # swap and the anamorphic correction.
+        class Video < ActiveStorage::Analyzer
+          include Analyzing
+
+          KEYS = %i[ width height duration angle display_aspect_ratio audio video ].freeze
+
+          def self.accept?(blob)
+            blob.video?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_storage/hot_cell/client/operations.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require "hot_cell/client"
+
+module ActiveStorage
+  module HotCell
+    module Client
+      # The cell these all talk to by default. An application registers it under this name.
+      CELL = "active_storage"
+
+      # One client class per operation, named role, then subject, then tool — so lexical order groups
+      # siblings — and the wire name is the snake-cased class path.
+      #
+      # They are separate classes so that they need not stay together. A cell carries one toolchain by design, so
+      # an application that wants video previews in a cell with ffmpeg and variants in a cell with only libvips
+      # says so here and changes nothing else:
+      #
+      #   ActiveStorage::HotCell::Client::Operations::Previewers::Video::Ffmpeg.hotcell "video"
+      #
+      # Routing is a class-level declaration rather than a call-site argument, so call sites carry no deployment
+      # detail at all.
+      module Operations
+        module Transformers
+          module Image
+            class Vips < ::HotCell::Client
+              hotcell CELL
+              operation "active_storage.transformers.image.vips"
+            end
+
+            class Magick < ::HotCell::Client
+              hotcell CELL
+              operation "active_storage.transformers.image.magick"
+            end
+          end
+        end
+
+        module Analyzers
+          module Image
+            class Vips < ::HotCell::Client
+              hotcell CELL
+              operation "active_storage.analyzers.image.vips"
+            end
+
+            class Magick < ::HotCell::Client
+              hotcell CELL
+              operation "active_storage.analyzers.image.magick"
+            end
+          end
+
+          # One probe serves both media analyzers: ffprobe reports video and audio streams in one pass, and
+          # the video and audio analyzers each slice the shared result to their own keys.
+          module Media
+            class Ffprobe < ::HotCell::Client
+              hotcell CELL
+              operation "active_storage.analyzers.media.ffprobe"
+            end
+
+            FFprobe = Ffprobe
+          end
+        end
+
+        module Previewers
+          module Pdf
+            class Mutool < ::HotCell::Client
+              hotcell CELL
+              operation "active_storage.previewers.pdf.mutool"
+            end
+
+            class Poppler < ::HotCell::Client
+              hotcell CELL
+              operation "active_storage.previewers.pdf.poppler"
+            end
+          end
+
+          PDF = Pdf
+
+          module Video
+            class Ffmpeg < ::HotCell::Client
+              hotcell CELL
+              operation "active_storage.previewers.video.ffmpeg"
+            end
+
+            FFmpeg = Ffmpeg
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_storage/hot_cell/client/previewers/pdf/mutool.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "active_storage/previewer/mupdf_previewer"
+
+require "active_storage/hot_cell/client/previewers/previewing"
+require "active_storage/hot_cell/client/previewers/pdf"
+
+module ActiveStorage
+  module HotCell
+    module Client
+      module Previewers
+        module Pdf
+          # What Rails configures in `config.active_storage.previewers`, replacing MuPDFPreviewer.
+          class Mutool < ActiveStorage::Previewer::MuPDFPreviewer
+            include Previewing
+
+            self.client = Operations::Previewers::Pdf::Mutool
+
+            # Delegates to the superclass's content-type predicate rather than restating the list, so the
+            # accepted set cannot drift away from the one Rails ships.
+            def self.accept?(blob)
+              pdf? blob.content_type
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_storage/hot_cell/client/previewers/pdf/poppler.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "active_storage/previewer/poppler_pdf_previewer"
+
+require "active_storage/hot_cell/client/previewers/previewing"
+require "active_storage/hot_cell/client/previewers/pdf"
+
+module ActiveStorage
+  module HotCell
+    module Client
+      module Previewers
+        module Pdf
+          # The Poppler sibling of Mutool, for an application whose image carries pdftoppm rather than
+          # mutool — the previewer Rails' default chain reaches first.
+          class Poppler < ActiveStorage::Previewer::PopplerPDFPreviewer
+            include Previewing
+
+            self.client = Operations::Previewers::Pdf::Poppler
+
+            def self.accept?(blob)
+              pdf? blob.content_type
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_storage/hot_cell/client/previewers/pdf.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module ActiveStorage
+  module HotCell
+    module Client
+      module Previewers
+        # The two PDF previewers cannot share a base here: each subclasses the Rails previewer it replaces to
+        # keep its content-type predicate, and those are different classes. The namespace is the shared home.
+        module Pdf
+        end
+
+        PDF = Pdf
+      end
+    end
+  end
+end

data/lib/active_storage/hot_cell/client/previewers/previewing.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "tempfile"
+require "active_storage"
+require "active_support/core_ext/class/attribute"
+
+require "active_storage/hot_cell/client/operations"
+
+module ActiveStorage
+  module HotCell
+    module Client
+      module Previewers
+        # The preview flow every previewer here shares. A previewer names the client that renders for it and
+        # differs in nothing else.
+        #
+        # **`accept?` must not probe for a binary, and that is the reason these previewers exist as much as the
+        # sandboxing is.** `MuPDFPreviewer.accept?` calls `mutool_exists?` and `VideoPreviewer.accept?` calls
+        # `ffmpeg_exists?`, both shelling out with `system` from inside a web request. The moment those binaries
+        # leave the application image — which is the point of moving the work into a cell — both answer false,
+        # `previewable?` goes false with them, and previews stop existing. No exception, no alert, nothing in a
+        # log.
+        #
+        # The sequencing matters as much as the override: these ship and are verified *before* the binary leaves
+        # the application image, because the window between those two events fails silently.
+        module Previewing
+          def self.included(previewer)
+            previewer.class_attribute :client, instance_accessor: false
+          end
+
+          def preview(**options)
+            download_blob_to_tempfile do |input|
+              render_through(input) do |attachable|
+                yield(**attachable, **options)
+              end
+            end
+          end
+
+          private
+            # The filename extension and content type come from the cell's own result rather than being
+            # restated here, so the operation is the one source of truth for what it produced. The scratch
+            # tempfile's name never reaches Rails — only the yielded filename does.
+            #
+            # **Accepted risk.** A compromised cell chooses both of these values. It does not need to be
+            # believed for them to matter, and validating them here buys nothing, because the cell wrote the
+            # preview's bytes into this descriptor as its whole job. Active Storage re-identifies the
+            # attachment from those bytes and Marcel treats the declared type only as a hint, so bytes that
+            # carry script are identified as what they are and served under Rails' own
+            # `content_types_allowed_inline` and `content_types_to_serve_as_binary` rules. Lying about the
+            # label adds nothing to controlling the bytes. What is left is a preview that renders wrong,
+            # which is one of many things a compromised cell can do. The premise is that the bytes are
+            # already the cell's to choose; a caller that stops handing the cell an output descriptor would
+            # be the thing that changes it.
+            def render_through(input)
+              Tempfile.create("hotcell-preview", binmode: true) do |output|
+                result = File.open(input.path, "rb") do |readable|
+                  File.open(output.path, "wb") do |writable|
+                    self.class.client.perform_in_hotcell [ readable ], [ writable ], payload
+                  end
+                end
+
+                File.open(output.path, "rb") do |io|
+                  yield io: io, filename: "#{blob.filename.base}.#{result[:format]}",
+                        content_type: result[:content_type]
+                end
+              end
+            end
+
+            # What travels with the request beyond the two descriptors. Nothing, for a previewer that has no
+            # configuration to carry; the video previewer overrides it with the application's input arguments.
+            def payload
+              {}
+            end
+        end
+      end
+    end
+  end
+end

data/lib/active_storage/hot_cell/client/previewers/video/ffmpeg.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "active_storage/previewer/video_previewer"
+
+require "active_storage/hot_cell/client/previewers/previewing"
+require "active_storage/hot_cell/client/tool_arguments"
+
+module ActiveStorage
+  module HotCell
+    module Client
+      module Previewers
+        module Video
+          # What Rails configures in `config.active_storage.previewers`, replacing VideoPreviewer.
+          class Ffmpeg < ActiveStorage::Previewer::VideoPreviewer
+            include Previewing
+
+            self.client = Operations::Previewers::Video::Ffmpeg
+
+            # blob.video? is the content-type predicate the superclass uses; ffmpeg_exists? is the part that
+            # has to go.
+            def self.accept?(blob)
+              blob.video?
+            end
+
+            private
+              # `config.active_storage.video_preview_input_arguments`, which Rails splices before `-i`, carried
+              # to the cell so it can do the same. Split here, the way Rails splits it, and omitted when empty.
+              def payload
+                ToolArguments.payload(:input_arguments, ActiveStorage.video_preview_input_arguments)
+              end
+          end
+
+          FFmpeg = Ffmpeg
+        end
+      end
+    end
+  end
+end

data/lib/active_storage/hot_cell/client/railtie.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module ActiveStorage
+  module HotCell
+    module Client
+      # An application installs the transformer, the analyzer and the previewers itself, because Active Storage
+      # reads those from config and there is no way for a gem to set them that the engine does not later
+      # overwrite. Everything else this gem needs is done here.
+      class Railtie < ::Rails::Railtie
+        # to_prepare rather than after_initialize, because it runs again on every code reload and the job
+        # classes do not survive one. See retry_transient_failures!.
+        initializer "active_storage.hot_cell.client.retry_transient_failures" do |app|
+          app.config.to_prepare do
+            ActiveStorage::HotCell::Client.retry_transient_failures!
+          end
+        end
+
+        # The two settings rails/rails#58461 adds, copied from `config.active_storage.*` the way Rails' engine
+        # copies every other Active Storage setting — in after_initialize, once the environment file has run.
+        # On a Rails that already has them, its engine did this already and the same value lands twice.
+        #
+        # The engine creates `config.active_storage`; an application that has not loaded it has no such
+        # namespace, and then there is nothing to copy.
+        initializer "active_storage.hot_cell.client.tool_arguments" do
+          config.after_initialize do |app|
+            next unless app.config.respond_to?(:active_storage)
+
+            ActiveStorage.ffprobe_arguments = app.config.active_storage.ffprobe_arguments || ""
+            ActiveStorage.video_preview_input_arguments = app.config.active_storage.video_preview_input_arguments || ""
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_storage/hot_cell/client/tool_arguments.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "shellwords"
+require "active_storage"
+require "active_support/core_ext/module/attribute_accessors"
+
+module ActiveStorage
+  # The two settings rails/rails#58461 adds, defined here when the installed Active Storage predates them so
+  # that an application configures the same thing either way. Rails' own definition takes precedence when it
+  # exists — a second mattr_accessor would reset the value the engine already copied from config.
+  #
+  # Both are shell strings, the shape Rails chose for `video_preview_arguments`, and default to nothing.
+  mattr_accessor :ffprobe_arguments, default: "" unless respond_to?(:ffprobe_arguments)
+  mattr_accessor :video_preview_input_arguments, default: "" unless respond_to?(:video_preview_input_arguments)
+
+  module HotCell
+    module Client
+      # Turns one of those shell strings into the argv the cell splices in, split the way Rails splits it —
+      # here, in the application, so a malformed string raises against the configuration rather than arriving
+      # in the cell as a failed conversion that reads like the document's fault.
+      #
+      # An empty setting yields nothing at all, so the request carries no key and the operation runs its
+      # default argv unchanged.
+      module ToolArguments
+        def self.split(setting)
+          Shellwords.split(setting.to_s)
+        end
+
+        def self.payload(key, setting)
+          arguments = split(setting)
+          arguments.empty? ? {} : { key => arguments }
+        end
+      end
+    end
+  end
+end

data/lib/active_storage/hot_cell/client/transformers/image/magick.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "active_storage"
+require "active_storage/transformers/image_magick"
+
+require "active_storage/hot_cell/client/operations"
+require "active_storage/hot_cell/client/transformers/transforming"
+
+module ActiveStorage
+  module HotCell
+    module Client
+      module Transformers
+        module Image
+          # What Rails configures as `config.active_storage.variant_processor` for an application on ImageMagick.
+          #
+          #   config.active_storage.variant_processor = ActiveStorage::HotCell::Client::Transformers::Image::Magick
+          #
+          # It subclasses Rails' own ImageMagick transformer to keep its transformation allowlist —
+          # `supported_image_processing_methods` and the argument blocklist — which runs here, in the
+          # application, exactly where Rails runs it today. Only the final step changes: rather than shelling out
+          # to `magick` locally, the validated transformations cross to the cell.
+          class Magick < ActiveStorage::Transformers::ImageMagick
+            include Transforming
+
+            self.client = Operations::Transformers::Image::Magick
+
+            private
+              # `operations` is Rails' validation: it raises UnsupportedImageProcessingMethod or
+              # UnsupportedImageProcessingArgument for anything outside the allowlist. Called for that effect,
+              # then the transformations travel to the cell as the application wrote them.
+              def process(file, format:)
+                operations
+
+                super
+              end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_storage/hot_cell/client/transformers/image/vips.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "active_storage"
+require "active_storage/transformers/transformer"
+
+require "active_storage/hot_cell/client/operations"
+require "active_storage/hot_cell/client/transformers/transforming"
+
+module ActiveStorage
+  module HotCell
+    module Client
+      module Transformers
+        module Image
+          # What Rails configures as `config.active_storage.variant_processor`.
+          #
+          #   config.active_storage.variant_processor = ActiveStorage::HotCell::Client::Transformers::Image::Vips
+          #
+          # Note what adopting this does not achieve, because it is easy to assume otherwise: libvips is still loaded
+          # into the application process, by `require "active_storage/engine"`, before any configuration is read. The
+          # engine builds its default analyzers array by referencing ActiveStorage::Analyzer::ImageAnalyzer::Vips,
+          # which requires ruby-vips, which dlopens the library. No `variant_processor` value changes that. Getting
+          # the library out of the application means removing ruby-vips from the bundle, which then breaks that
+          # default array — an application's call, and not one configuration alone can make.
+          #
+          # What this does achieve is that no untrusted byte is decoded there.
+          class Vips < ActiveStorage::Transformers::Transformer
+            include Transforming
+
+            self.client = Operations::Transformers::Image::Vips
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_storage/hot_cell/client/transformers/transforming.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "tempfile"
+require "active_storage"
+require "active_support/core_ext/class/attribute"
+require "active_support/core_ext/hash/deep_transform_values"
+
+require "active_storage/hot_cell/client/operations"
+
+module ActiveStorage
+  module HotCell
+    module Client
+      module Transformers
+        # The conversion both transformers share. A transformer names the client that carries its
+        # transformations to the cell, and differs in nothing else.
+        module Transforming
+          def self.included(transformer)
+            transformer.class_attribute :client, instance_accessor: false
+          end
+
+          private
+            # Returns an open, rewound Tempfile, which is the contract.
+            #
+            # The transformations travel to the cell almost as they arrived. Rails hands this a symbol-keyed hash
+            # with :format already removed — Variation deep-symbolizes on the way in and builds the transformer
+            # with `transformations.except(:format)` — so the keys need nothing, and deciding which keys are
+            # allowed belongs to the operation rather than to this side of the socket. Values are another matter:
+            # Variation symbolizes only keys, so `crop: :attention` reaches here as the application wrote it, and
+            # stock Rails accepts it. A Symbol value cannot ride JSON, which is this gem's transport detail
+            # rather than the application's problem — so Symbol values go over as the Strings the toolchain
+            # would have been handed anyway.
+            def process(file, format:)
+              output = Tempfile.new([ "hotcell", ".#{format}" ], binmode: true)
+
+              begin
+                convert file, output, format: format.to_s, operations: stringified(transformations)
+                output.tap(&:rewind)
+              rescue StandardError
+                output.close!
+                raise
+              end
+            end
+
+            # Both handles are reopened by path, narrowly, and that is the protocol rather than fussiness. Rails
+            # hands out Tempfiles, which are read-write; an input descriptor must be read-only and an output
+            # write-only. An access mode is fixed at open, so a cell handed the wrong one cannot narrow it — it can
+            # only decline the request.
+            def convert(file, output, **payload)
+              File.open(file.path, "rb") do |readable|
+                File.open(output.path, "wb") do |writable|
+                  self.class.client.perform_in_hotcell [ readable ], [ writable ], payload
+                end
+              end
+            end
+
+            # Only Symbol values, and only to String. Anything else unserializable is refused by the payload
+            # check as ever, because for everything but a Symbol there is no value Rails would have accepted
+            # in its place.
+            def stringified(transformations)
+              transformations.deep_transform_values { |value| value.is_a?(Symbol) ? value.to_s : value }
+            end
+        end
+      end
+    end
+  end
+end

data/lib/active_storage/hot_cell/client/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module ActiveStorage
+  module HotCell
+    module Client
+      VERSION = "0.2.0"
+    end
+  end
+end

data/lib/active_storage/hot_cell/client.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "active_storage"
+require "active_support/core_ext/string/inflections"
+
+require "active_storage/hot_cell/client/version"
+require "active_storage/hot_cell/client/operations"
+require "active_storage/hot_cell/client/transformers/image/vips"
+require "active_storage/hot_cell/client/transformers/image/magick"
+require "active_storage/hot_cell/client/analyzers/image/vips"
+require "active_storage/hot_cell/client/analyzers/image/magick"
+require "active_storage/hot_cell/client/analyzers/video/ffprobe"
+require "active_storage/hot_cell/client/analyzers/audio/ffprobe"
+require "active_storage/hot_cell/client/previewers/pdf/mutool"
+require "active_storage/hot_cell/client/previewers/pdf/poppler"
+require "active_storage/hot_cell/client/previewers/video/ffmpeg"
+require "active_storage/hot_cell/client/railtie" if defined?(::Rails::Railtie)
+
+module ActiveStorage
+  module HotCell
+    # Everything the application side defines lives under this, and everything the cell side defines lives under
+    # ActiveStorage::HotCell::Server. Not a tidying convention: the two gems are never both loaded in production,
+    # and a cell is forked from a process that may well have loaded this one — after which a shared name is a
+    # superclass mismatch while the cell boots. Two namespaces make that impossible rather than avoided.
+    module Client
+      # These four jobs declare `retry_on ActiveStorage::IntegrityError` and nothing else, and ActiveJob does
+      # not retry by default. They should retry the transient class too: `capacity` most obviously, and every
+      # other transient verdict. The policy matches the one they already declare, so a cell failure and an
+      # integrity failure back off the same way.
+      #
+      # Which of these classes exists depends on the Rails version, so a name that is not loaded is skipped.
+      JOBS = %w[
+        ActiveStorage::AnalyzeJob
+        ActiveStorage::CreateVariantsJob
+        ActiveStorage::PreviewImageJob
+        ActiveStorage::TransformJob
+      ].freeze
+
+      RETRY = { wait: :polynomially_longer, attempts: 10 }.freeze
+
+      # The clients this gem ships, which is where the retry hook learns which cells' transient classes
+      # the jobs must retry. Deliberately not HotCell.clients: that records every client the process loaded,
+      # including an application's own for unrelated cells, and Active Storage's jobs have no business
+      # retrying those.
+      CLIENTS = [ Operations::Transformers::Image::Vips, Operations::Transformers::Image::Magick,
+                  Operations::Analyzers::Image::Vips, Operations::Analyzers::Image::Magick,
+                  Operations::Analyzers::Media::Ffprobe,
+                  Operations::Previewers::Pdf::Mutool, Operations::Previewers::Pdf::Poppler,
+                  Operations::Previewers::Video::Ffmpeg ].freeze
+
+      class << self
+        # The railtie calls this from a to_prepare block. Applied once at boot it would not survive a code
+        # reload: a gem engine's app/jobs is in the reloadable autoloader, so these classes are discarded and
+        # redefined, and the retry would silently disappear after the first file save in development.
+        #
+        # Every registered cell contributes its transient class, because the documented multi-cell
+        # arrangement routes PreviewVideo to a cell of its own and each cell names its own class. A cell not
+        # yet registered contributes nothing rather than raising: this runs on the boot where the application
+        # has bundled the gem and not yet written the initializer, and that boot has to succeed for the
+        # rollout to take two deploys rather than one.
+        def retry_transient_failures!(jobs: JOBS)
+          transients = CLIENTS.filter_map { |client| client.cell.transient if client.registered? }
+                              .uniq
+          return [] if transients.empty?
+
+          jobs.filter_map(&:safe_constantize)
+              .each { |job| job.retry_on(*transients, **RETRY) }
+        end
+      end
+    end
+  end
+end

data/lib/activestorage-hotcell-client.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# Bundler auto-requires this gem as "activestorage-hotcell-client", then as "activestorage/hotcell/client".
+# It uses neither path. Without this file, naming it in a Gemfile silently loads nothing.
+require "active_storage/hot_cell/client"

metadata

@@ -1,24 +1,86 @@
 --- !ruby/object:Gem::Specification
 name: activestorage-hotcell-client
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Mike Dalessio
 bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies: []
-description: To be released soon, secure sidecar for Rails with Active Storage extensions
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: hotcell-client
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+- !ruby/object:Gem::Dependency
+  name: activestorage
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 8.2.0.alpha
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 8.2.0.alpha
+description: |
+  Drop-in replacements for Active Storage's variant processor, analyzers, and previewers. Configure
+  Rails with these classes and variants, image and media analysis, and previews run in a HotCell
+  container instead of in the application process.
 email:
 - mike@37signals.com
 executables: []
 extensions: []
 extra_rdoc_files: []
-files: []
+files:
+- MIT-LICENSE
+- README.md
+- lib/active_storage/hot_cell/client.rb
+- lib/active_storage/hot_cell/client/analyzers/analyzing.rb
+- lib/active_storage/hot_cell/client/analyzers/audio.rb
+- lib/active_storage/hot_cell/client/analyzers/audio/ffprobe.rb
+- lib/active_storage/hot_cell/client/analyzers/image.rb
+- lib/active_storage/hot_cell/client/analyzers/image/magick.rb
+- lib/active_storage/hot_cell/client/analyzers/image/vips.rb
+- lib/active_storage/hot_cell/client/analyzers/probing.rb
+- lib/active_storage/hot_cell/client/analyzers/video.rb
+- lib/active_storage/hot_cell/client/analyzers/video/ffprobe.rb
+- lib/active_storage/hot_cell/client/operations.rb
+- lib/active_storage/hot_cell/client/previewers/pdf.rb
+- lib/active_storage/hot_cell/client/previewers/pdf/mutool.rb
+- lib/active_storage/hot_cell/client/previewers/pdf/poppler.rb
+- lib/active_storage/hot_cell/client/previewers/previewing.rb
+- lib/active_storage/hot_cell/client/previewers/video/ffmpeg.rb
+- lib/active_storage/hot_cell/client/railtie.rb
+- lib/active_storage/hot_cell/client/tool_arguments.rb
+- lib/active_storage/hot_cell/client/transformers/image/magick.rb
+- lib/active_storage/hot_cell/client/transformers/image/vips.rb
+- lib/active_storage/hot_cell/client/transformers/transforming.rb
+- lib/active_storage/hot_cell/client/version.rb
+- lib/activestorage-hotcell-client.rb
+homepage: https://github.com/basecamp/hotcell
 licenses:
 - MIT
-metadata: {}
+metadata:
+  homepage_uri: https://github.com/basecamp/hotcell
+  source_code_uri: https://github.com/basecamp/hotcell/tree/v0.2.0/activestorage-hotcell-client
+  changelog_uri: https://github.com/basecamp/hotcell/blob/v0.2.0/CHANGELOG.md
+  bug_tracker_uri: https://github.com/basecamp/hotcell/issues
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib
@@ -26,7 +88,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -35,5 +97,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.16
 specification_version: 4
-summary: To be released soon, secure sidecar for Rails with Active Storage extensions
+summary: Point Active Storage's transformer, analyzer, and previewers at a HotCell.
 test_files: []