safe_image 0.2.0 → 0.4.0

data/lib/safe_image/operation_backends/vips.rb

@@ -0,0 +1,251 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module SafeImage
+  module OperationBackends
+    # libvips operation orchestration. This is the configured-backend path for
+    # untrusted raster bytes; optional cjpegli/jpegtran tiers run only after
+    # SafeImage has decoded or validated the input.
+    class Vips < Base
+      NATIVE_CONVERT_DEFAULT_QUALITY = QualityDefaults::NATIVE_CONVERT_JPEG
+
+      def resize(input:, output:, width:, height:, quality:, optimize:, max_pixels:, chroma_subsampling:)
+        input, output = input_output!(input, output)
+        max_pixels = resolved_max_pixels(max_pixels)
+        result =
+          Processor.new(max_pixels: max_pixels, chroma_subsampling: chroma_subsampling, config: config).thumbnail(
+            input: input,
+            output: output,
+            width: width,
+            height: height,
+            quality: quality || QualityDefaults::JPEG,
+            optimize: optimize
+          )
+        result.with(tier: result.backend.include?("cjpegli") ? :cjpegli : :resize)
+      end
+
+      def crop(input:, output:, width:, height:, quality:, optimize:, max_pixels:, chroma_subsampling:)
+        input, output = input_output!(input, output)
+        max_pixels = resolved_max_pixels(max_pixels)
+        probe = operation_probe(input, max_pixels: max_pixels)
+        output = safe_output!(output)
+        format = Formats.extension(output)
+
+        info =
+          if jpegli_for_generated_jpeg?(format)
+            JpegliBackend.encode_generated_jpeg(
+              output: output,
+              quality: quality || JpegliBackend::DEFAULT_QUALITY,
+              chroma_subsampling: chroma_subsampling,
+              input_format: probe.input_format
+            ) do |tmp_path|
+              VipsBackend.crop_north(
+                input: probe.input,
+                output: tmp_path,
+                width: width,
+                height: height,
+                format: "png",
+                quality: 100,
+                max_pixels: max_pixels
+              )
+            end
+          else
+            VipsBackend.crop_north(
+              input: probe.input,
+              output: output,
+              width: width,
+              height: height,
+              format: format,
+              quality: quality || QualityDefaults::JPEG,
+              max_pixels: max_pixels
+            )
+          end
+        optimize_output(output, quality) if optimize
+        result_from_info(probe.input, output, info, :vips, tier: info[:encoder] == "cjpegli" ? :cjpegli : :crop)
+      end
+
+      def downsize(input:, output:, dimensions:, optimize:, max_pixels:, quality:, chroma_subsampling:)
+        input, output = input_output!(input, output)
+        max_pixels = resolved_max_pixels(max_pixels)
+        probe = operation_probe(input, max_pixels: max_pixels)
+        output = safe_output!(output)
+        format = Formats.extension(output)
+        info =
+          if jpegli_for_generated_jpeg?(format)
+            JpegliBackend.encode_generated_jpeg(
+              output: output,
+              quality: quality,
+              chroma_subsampling: chroma_subsampling,
+              input_format: probe.input_format
+            ) do |tmp_path|
+              VipsBackend.downsize(
+                input: probe.input,
+                output: tmp_path,
+                dimensions: dimensions,
+                format: "png",
+                quality: 100,
+                max_pixels: max_pixels
+              )
+            end
+          else
+            VipsBackend.downsize(
+              input: probe.input,
+              output: output,
+              dimensions: dimensions,
+              format: format,
+              quality: quality,
+              max_pixels: max_pixels
+            )
+          end
+        optimize_output(output, nil) if optimize
+        result_from_info(probe.input, output, info, :vips, tier: info[:encoder] == "cjpegli" ? :cjpegli : :downsize)
+      end
+
+      def convert(input:, output:, format:, quality:, optimize:, max_pixels:, chroma_subsampling:)
+        input, output = input_output!(input, output)
+        max_pixels = resolved_max_pixels(max_pixels)
+        input = PathSafety.ensure_regular_file!(input).to_s
+        normalized_format = Formats.normalize(format)
+
+        if jpegli_for_convert?(input, normalized_format)
+          info =
+            jpegli_convert_after_native_decode(
+              input: input,
+              output: output,
+              quality: quality || JpegliBackend::DEFAULT_QUALITY,
+              max_pixels: max_pixels,
+              chroma_subsampling: chroma_subsampling
+            )
+          return result_from_info(input, output, info, :vips, tier: :cjpegli)
+        end
+
+        info =
+          write_through_tempfile(output) do |tmp_path|
+            Native.convert(input, tmp_path, normalized_format, quality || NATIVE_CONVERT_DEFAULT_QUALITY, max_pixels)
+          end
+        optimize_output(output, normalized_format == "jpg" ? quality : nil) if optimize
+        result_from_info(input, output, info, :vips, tier: :native_convert)
+      end
+
+      def fix_orientation(input:, output:, max_pixels:, quality:)
+        input, output = input_output!(input, output)
+        max_pixels = resolved_max_pixels(max_pixels)
+        input = PathSafety.ensure_regular_file!(input).to_s
+        format = Formats.extension(input)
+        # Validates the format against the native loader allowlist and enforces
+        # the pixel cap before any pixel decode.
+        orient = VipsBackend.orientation(input, max_pixels: max_pixels)
+
+        # Lossless tier: jpegtran transforms JPEG DCT coefficients directly, so
+        # there is no generation loss. -perfect refuses when the dimensions are
+        # not MCU-aligned; only that expected refusal falls through to the
+        # observable re-encode tier.
+        tier = :native_reencode
+        if format == "jpg" && orient > 1 && Runner.available?("jpegtran")
+          begin
+            return jpegtran_fix_orientation(input, output, orient)
+          rescue CommandError => e
+            raise unless Optimizer.jpegtran_perfect_reject?(e)
+
+            tier = :jpegtran_fallback_reencode
+          end
+        end
+
+        quality = quality.nil? ? QualityDefaults::FIX_ORIENTATION_REENCODE_JPEG : Integer(quality)
+        raise ArgumentError, "quality must be 1..100" unless (1..100).cover?(quality)
+
+        info =
+          write_through_tempfile(output) { |tmp_path| Native.resize(input, tmp_path, 1.0, format, quality, max_pixels) }
+        result_from_info(input, output, info, :vips, tier: tier)
+      end
+
+      def convert_favicon_to_png(input:, output:, optimize:, max_pixels:)
+        input, output = input_output!(input, output)
+        max_pixels = resolved_max_pixels(max_pixels)
+        # Pure-Ruby ICO parse; libvips only encodes the extracted pixels.
+        info = Ico.convert_to_png(input, output, max_pixels: max_pixels)
+        optimize_output(output, nil) if optimize
+        result_from_info(input, output, info, :ico_vips, tier: :ico_ruby)
+      end
+
+      def letter_avatar(output:, size:, background_rgb:, letter:, pointsize:, font:)
+        output = safe_output!(output)
+        request = {
+          output: output,
+          size: size,
+          background_rgb: background_rgb,
+          letter: letter,
+          pointsize: pointsize,
+          font: font
+        }
+        result_from_info("generated", output, VipsBackend.letter_avatar(**request), :vips, tier: :letter_avatar)
+      end
+
+      private
+
+      def operation_probe(path, max_pixels:)
+        Processor.new(max_pixels: max_pixels, config: config).probe(Pathname.new(path).expand_path.to_s)
+      end
+
+      def backend_frame_count(path, max_pixels:)
+        VipsBackend.frame_count(path, max_pixels: max_pixels)
+      end
+
+      def jpegli_for_convert?(input, normalized_format)
+        normalized_format == "jpg" && JpegliBackend.available? && JpegliBackend.suitable_direct_input?(input)
+      end
+
+      # cjpegli is an output-quality tool, not a configuration choice: installed
+      # means used for JPEG output on the native path. It encodes only pixels
+      # this gem already decoded, so it is not part of the untrusted-input
+      # surface the backend choice controls.
+      def jpegli_for_generated_jpeg?(format)
+        Formats.normalize(format) == "jpg" && JpegliBackend.available?
+      end
+
+      def jpegli_convert_after_native_decode(input:, output:, quality:, max_pixels:, chroma_subsampling:)
+        JpegliBackend.encode_generated_jpeg(
+          output: output,
+          quality: quality,
+          chroma_subsampling: chroma_subsampling
+        ) { |tmp_path| Native.convert(input, tmp_path, "png", 100, max_pixels) }
+      end
+
+      def jpegtran_fix_orientation(input, output, orient)
+        started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        info =
+          write_through_tempfile(output) do |tmp_path|
+            Runner.run!(
+              [
+                "jpegtran",
+                "-copy",
+                "none",
+                "-perfect",
+                *Optimizer::JPEGTRAN_OPERATIONS.fetch(orient),
+                "-outfile",
+                tmp_path,
+                input
+              ],
+              read: [input],
+              write: [tmp_path, File.dirname(tmp_path)]
+            )
+            Native.probe(tmp_path)
+          end
+        result_from_info(
+          input,
+          output,
+          {
+            input_format: "jpg",
+            output_format: "jpg",
+            width: info.fetch(:width),
+            height: info.fetch(:height),
+            duration_ms: (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000
+          },
+          :jpegtran,
+          tier: :jpegtran_lossless
+        )
+      end
+    end
+  end
+end

data/lib/safe_image/operation_backends.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "operation_backends/base"
+require_relative "operation_backends/vips"
+require_relative "operation_backends/image_magick"
+
+module SafeImage
+  # Factory for operation orchestration strategies. Transform and metadata
+  # operation objects select one strategy per call from the supplied config; the
+  # strategy owns the backend-specific pipeline details.
+  module OperationBackends
+    module_function
+
+    def for(config)
+      case config.backend
+      when :vips
+        Vips.new(config: config)
+      when :imagemagick
+        ImageMagick.new(config: config)
+      else
+        raise ArgumentError, "unknown backend: #{config.backend.inspect}"
+      end
+    end
+  end
+
+  private_constant :OperationBackends
+end

data/lib/safe_image/operation_set.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module SafeImage
+  # Shared plumbing for public-operation implementations. Concrete operation
+  # classes contain the inline implementation; child-process sandboxing happens
+  # at the helper/command boundary, not by proxying these Ruby objects.
+  class OperationSet
+    attr_reader :config
+
+    def initialize(config:)
+      @config = config
+    end
+
+    private
+
+    def resolved_max_pixels(max_pixels)
+      SafeImage.resolved_max_pixels(max_pixels, config: config)
+    end
+  end
+
+  private_constant :OperationSet
+end

data/lib/safe_image/optimizer.rb

@@ -1,78 +1,280 @@
 # frozen_string_literal: true
 
-require "tempfile"
+require "fileutils"
 
 module SafeImage
   module Optimizer
     module_function
 
+    # pngquant's lossy trial is worthwhile only for small generated PNGs; above
+    # this size the extra decode/quantize pass is comparatively expensive. The
+    # lossless PNG optimizer still runs for larger PNGs.
     MAX_PNGQUANT_SIZE = 500_000
 
-    def optimize(path, mode: :lossless, strip_metadata: true, quality: nil, timeout: Runner::DEFAULT_TIMEOUT, strict: true)
-      path = PathSafety.ensure_regular_file!(path)
+    # EXIF orientation values mapped onto jpegtran's lossless transforms.
+    JPEGTRAN_OPERATIONS = {
+      2 => %w[-flip horizontal],
+      3 => %w[-rotate 180],
+      4 => %w[-flip vertical],
+      5 => ["-transpose"],
+      6 => %w[-rotate 90],
+      7 => ["-transverse"],
+      8 => %w[-rotate 270]
+    }.freeze
+
+    def jpegtran_perfect_reject?(error)
+      error.is_a?(CommandError) && error.category == :exit_status && error.status.to_i == 1 &&
+        Array(error.command).include?("-perfect")
+    end
 
-      ext = path.extname.delete_prefix(".").downcase
-      ext = "jpg" if ext == "jpeg"
+    # assume_upright: skips the JPEG orientation check; only for callers
+    # optimising output this gem just encoded (which is always upright).
+    def optimize(
+      input:,
+      output:,
+      mode: :lossless,
+      strip_metadata: true,
+      quality: nil,
+      timeout: Runner::DEFAULT_TIMEOUT,
+      strict: true,
+      assume_upright: false
+    )
+      input, output = PathSafety.ensure_distinct_file_paths!(input, output)
+      ext = normalized_extension(input)
 
+      StagedOutput.replace(output, suffix: ".safe-image.#{ext}") do |tmp_path|
+        FileUtils.cp(input, tmp_path)
+        optimize_working_file!(
+          tmp_path,
+          mode: mode,
+          strip_metadata: strip_metadata,
+          quality: quality,
+          timeout: timeout,
+          strict: strict,
+          assume_upright: assume_upright
+        )
+      end
+    end
+
+    def optimize_working_file!(
+      path,
+      mode: :lossless,
+      strip_metadata: true,
+      quality: nil,
+      timeout: Runner::DEFAULT_TIMEOUT,
+      strict: true,
+      assume_upright: false
+    )
+      path = PathSafety.ensure_regular_file!(path)
+      ext = normalized_extension(path)
       before = File.size(path)
-      tools = []
+      state = { tools: [], rotated_from: nil, trimmed: false }
 
       case ext
       when "jpg"
-        if Runner.available?("jpegoptim")
-          argv = ["jpegoptim", "--quiet"]
-          argv << (strip_metadata ? "--strip-all" : "--strip-none")
-          argv << "--max=#{Integer(quality)}" if quality
-          argv << path.to_s
-          Runner.run!(argv, timeout: timeout)
-          tools << "jpegoptim"
-        else
-          raise Error, "jpegoptim is required for strict JPEG optimisation" if strict
-        end
+        skipped =
+          optimize_jpeg!(
+            path,
+            state,
+            strip_metadata: strip_metadata,
+            quality: quality,
+            timeout: timeout,
+            strict: strict,
+            assume_upright: assume_upright,
+            before: before
+          )
+        return skipped if skipped
       when "png"
-        if mode.to_sym == :lossy && before < MAX_PNGQUANT_SIZE
-          if Runner.available?("pngquant")
-            tmp = Tempfile.new([path.basename(".*").to_s, ".pngquant.png"], path.dirname.to_s)
-            tmp_path = Pathname.new(tmp.path)
-            tmp.close
-            begin
-              argv = ["pngquant", "--force", "--skip-if-larger", "--output", tmp_path.to_s]
-              argv << "--quality=#{quality}" if quality # e.g. "65-90"
-              argv << path.to_s
-              Runner.run!(argv, timeout: timeout)
-              if tmp_path.file? && File.size(tmp_path) < File.size(path)
-                FileUtils.mv(tmp_path, path)
-                tools << "pngquant"
-              end
-            ensure
-              FileUtils.rm_f(tmp_path)
-            end
-          elsif strict
-            raise Error, "pngquant is required for strict lossy PNG optimisation"
-          end
+        optimize_png!(
+          path,
+          state,
+          mode: mode,
+          strip_metadata: strip_metadata,
+          quality: quality,
+          timeout: timeout,
+          strict: strict,
+          before: before
+        )
+      else
+        raise UnsupportedFormatError, "unsupported optimize format: #{ext.inspect}"
+      end
+
+      build_result(ext, before, File.size(path), state)
+    end
+
+    def optimize_jpeg!(path, state, strip_metadata:, quality:, timeout:, strict:, assume_upright:, before:)
+      # Stripping metadata deletes the EXIF orientation tag, so an oriented
+      # image must have the rotation baked into its pixels first or it ships
+      # sideways. jpegtran does that losslessly; without it, leave the file
+      # untouched rather than strip-without-rotate.
+      orientation = strip_metadata && !assume_upright ? jpeg_orientation(path) : 1
+      if orientation > 1
+        unless Runner.available?("jpegtran")
+          raise Error, "jpegtran is required to optimize a JPEG with EXIF orientation" if strict
+          return skipped_result("jpg", before, state.fetch(:tools))
         end
 
-        if Runner.available?("oxipng")
-          argv = ["oxipng", "--quiet", "-o", "3"]
-          argv.concat(["--strip", strip_metadata ? "safe" : "none"])
+        state[:trimmed] = upright_working_file!(path, orientation, timeout: timeout)
+        state[:rotated_from] = orientation
+        state[:tools] << "jpegtran"
+      end
+
+      if Runner.available?("jpegoptim")
+        argv = %w[jpegoptim --quiet]
+        argv << (strip_metadata ? "--strip-all" : "--strip-none")
+        argv << "--max=#{Integer(quality)}" if quality
+        argv << path.to_s
+        Runner.run!(argv, timeout: timeout, read: [path.to_s], write: [path.to_s, File.dirname(path.to_s)])
+        state[:tools] << "jpegoptim"
+      else
+        raise Error, "jpegoptim is required for strict JPEG optimisation" if strict
+      end
+
+      nil
+    end
+
+    def optimize_png!(path, state, mode:, strip_metadata:, quality:, timeout:, strict:, before:)
+      # Discourse/image_optim parity: run the lossless PNG optimizer before the
+      # optional lossy pngquant pass.
+      png_lossless_optimizer!(path, state, strip_metadata: strip_metadata, timeout: timeout, strict: strict)
+      if mode.to_sym == :lossy && before < MAX_PNGQUANT_SIZE
+        pngquant!(path, state, quality: quality, timeout: timeout, strict: strict)
+      end
+    end
+
+    def pngquant!(path, state, quality:, timeout:, strict:)
+      if Runner.available?("pngquant")
+        StagedOutput.with_temp_path_near(path, suffix: ".pngquant.png") do |tmp_path|
+          argv = ["pngquant", "--force", "--skip-if-larger", "--output", tmp_path.to_s]
+          argv << "--quality=#{quality}" if quality # e.g. "65-90"
           argv << path.to_s
-          Runner.run!(argv, timeout: timeout)
-          tools << "oxipng"
-        else
-          raise Error, "oxipng is required for strict PNG optimisation" if strict
+          skipped = false
+          begin
+            Runner.run!(argv, timeout: timeout, read: [path.to_s], write: [tmp_path.to_s, File.dirname(tmp_path.to_s)])
+          rescue CommandError => e
+            # 98: --skip-if-larger declined the result; 99: --quality not met.
+            # Both mean "keep the original", not a failure — and the pre-created
+            # tempfile is still empty, so it must not win the size comparison.
+            raise if [98, 99].none? { |status| status == e.status }
+            skipped = true
+          end
+          if !skipped && tmp_path.file? && File.size(tmp_path).positive? && File.size(tmp_path) < File.size(path)
+            FileUtils.mv(tmp_path, path)
+            state[:tools] << "pngquant"
+          end
         end
-      else
-        raise UnsupportedFormatError, "unsupported optimize format: #{ext.inspect}"
+      elsif strict
+        raise Error, "pngquant is required for strict lossy PNG optimisation"
       end
+    end
+
+    def png_lossless_optimizer!(path, state, strip_metadata:, timeout:, strict:)
+      if Runner.available?("oxipng")
+        oxipng!(path, state, strip_metadata: strip_metadata, timeout: timeout)
+      elsif Runner.available?("optipng")
+        optipng!(path, state, strip_metadata: strip_metadata, timeout: timeout)
+      elsif strict
+        raise Error, "oxipng or optipng is required for strict PNG optimisation"
+      end
+    end
 
-      after = File.size(path)
+    def oxipng!(path, state, strip_metadata:, timeout:)
+      argv = %w[oxipng --quiet -o 3]
+      argv.concat(["--strip", strip_metadata ? "safe" : "none"])
+      argv << path.to_s
+      Runner.run!(argv, timeout: timeout, read: [path.to_s], write: [path.to_s, File.dirname(path.to_s)])
+      state[:tools] << "oxipng"
+    end
+
+    def optipng!(path, state, strip_metadata:, timeout:)
+      argv = %w[optipng -quiet -o2]
+      argv.concat(%w[-strip all]) if strip_metadata
+      argv << path.to_s
+      Runner.run!(argv, timeout: timeout, read: [path.to_s], write: [path.to_s, File.dirname(path.to_s)])
+      state[:tools] << "optipng"
+    end
+
+    def build_result(format, before, after, state)
       {
-        format: ext,
+        format: format,
         before_bytes: before,
         after_bytes: after,
         saved_bytes: before - after,
-        tools: tools
+        tools: state.fetch(:tools),
+        rotated_from: state.fetch(:rotated_from),
+        trimmed: state.fetch(:trimmed)
+      }
+    end
+
+    def skipped_result(format, bytes, tools)
+      {
+        format: format,
+        before_bytes: bytes,
+        after_bytes: bytes,
+        saved_bytes: 0,
+        tools: tools,
+        rotated_from: nil,
+        trimmed: false
       }
     end
+
+    def normalized_extension(path)
+      Formats.extension(path)
+    end
+
+    def jpeg_orientation(path)
+      case SafeImage.config.backend
+      when :vips
+        VipsBackend.orientation(path.to_s)
+      when :imagemagick
+        ImageMagickBackend.orientation(path.to_s)
+      end
+    end
+
+    # Applies the orientation's lossless jpegtran transform to the working copy,
+    # dropping the metadata in the same pass (-copy none; this path only runs
+    # when strip_metadata is set). -perfect refuses dimensions that are not
+    # MCU-aligned; the -trim retry drops the partial edge blocks (under one MCU,
+    # at most 15px) instead of hiding a lossy re-encode here. Returns true when
+    # the fallback trimmed.
+    def upright_working_file!(path, orientation, timeout:)
+      transform = JPEGTRAN_OPERATIONS.fetch(orientation)
+      StagedOutput.with_temp_path_near(path, suffix: ".jpegtran.jpg") do |tmp_path|
+        trimmed = false
+        begin
+          Runner.run!(
+            ["jpegtran", "-copy", "none", "-perfect", *transform, "-outfile", tmp_path.to_s, path.to_s],
+            timeout: timeout,
+            read: [path.to_s],
+            write: [tmp_path.to_s, File.dirname(tmp_path.to_s)]
+          )
+        rescue CommandError => e
+          raise unless jpegtran_perfect_reject?(e)
+
+          Runner.run!(
+            ["jpegtran", "-copy", "none", "-trim", *transform, "-outfile", tmp_path.to_s, path.to_s],
+            timeout: timeout,
+            read: [path.to_s],
+            write: [tmp_path.to_s, File.dirname(tmp_path.to_s)]
+          )
+          trimmed = true
+        end
+        FileUtils.mv(tmp_path, path)
+        trimmed
+      end
+    end
+
+    private_class_method :optimize_working_file!,
+                         :optimize_jpeg!,
+                         :optimize_png!,
+                         :pngquant!,
+                         :png_lossless_optimizer!,
+                         :oxipng!,
+                         :optipng!,
+                         :build_result,
+                         :skipped_result,
+                         :normalized_extension,
+                         :jpeg_orientation,
+                         :upright_working_file!
   end
 end

data/lib/safe_image/path_safety.rb

@@ -37,10 +37,21 @@ module SafeImage
       reject_symlink_components!(path.dirname)
       if File.exist?(path.to_s)
         raise UnsafePathError, "output path is a symlink: #{path}" if File.lstat(path.to_s).symlink?
+        raise UnsafePathError, "output path is a directory: #{path}" if File.directory?(path.to_s)
       end
       path
     end
 
+    def ensure_distinct_file_paths!(input, output)
+      input = ensure_regular_file!(input)
+      output = ensure_safe_output_path!(output)
+      same_path = input.to_s == output.to_s
+      same_file = output.exist? && File.identical?(input.to_s, output.to_s)
+      raise UnsafePathError, "input and output must be different paths" if same_path || same_file
+
+      [input, output]
+    end
+
     def ensure_imagemagick_safe!(path)
       path = local_path(path)
       raise UnsafePathError, "path contains NUL" if path.include?("\0")