safe_image 0.3.0 → 0.4.0

data/lib/safe_image/api/metadata.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module SafeImage
+  module API
+    # Public read-only metadata operations. Methods stay exposed on SafeImage via
+    # `extend`; inline behavior lives in operation classes.
+    module Metadata
+      def probe(path, max_pixels: nil)
+        metadata_operations.probe(path, max_pixels: max_pixels)
+      end
+
+      def type(path, max_pixels: nil)
+        metadata_operations.type(path, max_pixels: max_pixels)
+      end
+
+      def size(path, max_pixels: nil)
+        metadata_operations.size(path, max_pixels: max_pixels)
+      end
+
+      def dimensions(path, max_pixels: nil)
+        metadata_operations.dimensions(path, max_pixels: max_pixels)
+      end
+
+      def info(path, max_pixels: nil, animated: false, orientation: false)
+        metadata_operations.info(path, max_pixels: max_pixels, animated: animated, orientation: orientation)
+      end
+
+      def orientation(path, max_pixels: nil)
+        metadata_operations.orientation(path, max_pixels: max_pixels)
+      end
+
+      def dominant_color(path, max_pixels: nil)
+        metadata_operations.dominant_color(path, max_pixels: max_pixels)
+      end
+
+      def remote_info(url, **kwargs)
+        config
+        Remote.info(url, **kwargs)
+      end
+
+      def remote_size(url, **kwargs)
+        config
+        Remote.size(url, **kwargs)
+      end
+
+      def remote_dimensions(url, **kwargs)
+        remote_size(url, **kwargs)
+      end
+
+      def remote_type(url, **kwargs)
+        config
+        Remote.type(url, **kwargs)
+      end
+
+      def remote_animated?(url, **kwargs)
+        config
+        Remote.animated?(url, **kwargs)
+      end
+
+      def remote_dominant_color(url, **kwargs)
+        config
+        Remote.dominant_color(url, **kwargs)
+      end
+
+      def fetch_remote(url, **kwargs, &block)
+        config
+        Remote.fetch(url, **kwargs, &block)
+      end
+
+      def frame_count(path, max_pixels: nil)
+        metadata_operations.frame_count(path, max_pixels: max_pixels)
+      end
+
+      def animated?(path, max_pixels: nil)
+        metadata_operations.animated?(path, max_pixels: max_pixels)
+      end
+
+      private
+
+      def metadata_operations
+        MetadataOperations.new(config: SafeImage.config)
+      end
+    end
+  end
+end

data/lib/safe_image/api/transform.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module SafeImage
+  module API
+    # Public image-producing operations. Every method requires explicit output
+    # paths; callers own any file replacement outside this API.
+    module Transform
+      def thumbnail(
+        input:,
+        output:,
+        width:,
+        height:,
+        format: nil,
+        quality: QualityDefaults::JPEG,
+        max_pixels: nil,
+        optimize: false,
+        optimize_mode: :lossless,
+        chroma_subsampling: :auto
+      )
+        transform_operations.thumbnail(
+          input: input,
+          output: output,
+          width: width,
+          height: height,
+          format: format,
+          quality: quality,
+          max_pixels: max_pixels,
+          optimize: optimize,
+          optimize_mode: optimize_mode,
+          chroma_subsampling: chroma_subsampling
+        )
+      end
+
+      def optimize(input:, output:, mode: :lossless, strip_metadata: true, quality: nil, strict: true)
+        transform_operations.optimize(
+          input: input,
+          output: output,
+          mode: mode,
+          strip_metadata: strip_metadata,
+          quality: quality,
+          strict: strict
+        )
+      end
+
+      def resize(
+        input:,
+        output:,
+        width:,
+        height:,
+        quality: nil,
+        optimize: true,
+        max_pixels: nil,
+        chroma_subsampling: :auto
+      )
+        transform_operations.resize(
+          input: input,
+          output: output,
+          width: width,
+          height: height,
+          quality: quality,
+          optimize: optimize,
+          max_pixels: max_pixels,
+          chroma_subsampling: chroma_subsampling
+        )
+      end
+
+      def crop(
+        input:,
+        output:,
+        width:,
+        height:,
+        quality: nil,
+        optimize: true,
+        max_pixels: nil,
+        chroma_subsampling: :auto
+      )
+        transform_operations.crop(
+          input: input,
+          output: output,
+          width: width,
+          height: height,
+          quality: quality,
+          optimize: optimize,
+          max_pixels: max_pixels,
+          chroma_subsampling: chroma_subsampling
+        )
+      end
+
+      def downsize(
+        input:,
+        output:,
+        dimensions:,
+        optimize: true,
+        max_pixels: nil,
+        quality: QualityDefaults::JPEG,
+        chroma_subsampling: :auto
+      )
+        transform_operations.downsize(
+          input: input,
+          output: output,
+          dimensions: dimensions,
+          optimize: optimize,
+          max_pixels: max_pixels,
+          quality: quality,
+          chroma_subsampling: chroma_subsampling
+        )
+      end
+
+      def convert(input:, output:, format:, quality: nil, optimize: true, max_pixels: nil, chroma_subsampling: :auto)
+        transform_operations.convert(
+          input: input,
+          output: output,
+          format: format,
+          quality: quality,
+          optimize: optimize,
+          max_pixels: max_pixels,
+          chroma_subsampling: chroma_subsampling
+        )
+      end
+
+      def fix_orientation(input:, output:, max_pixels: nil, quality: nil)
+        transform_operations.fix_orientation(input: input, output: output, max_pixels: max_pixels, quality: quality)
+      end
+
+      def convert_favicon_to_png(input:, output:, optimize: true, max_pixels: nil)
+        transform_operations.convert_favicon_to_png(
+          input: input,
+          output: output,
+          optimize: optimize,
+          max_pixels: max_pixels
+        )
+      end
+
+      def letter_avatar(output:, size:, background_rgb:, letter:, pointsize: 280, font: "DejaVu-Sans")
+        transform_operations.letter_avatar(
+          output: output,
+          size: size,
+          background_rgb: background_rgb,
+          letter: letter,
+          pointsize: pointsize,
+          font: font
+        )
+      end
+
+      private
+
+      def transform_operations
+        TransformOperations.new(config: SafeImage.config)
+      end
+    end
+  end
+end

data/lib/safe_image/backend_label.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module SafeImage
+  module BackendLabel
+    module_function
+
+    BASE = {
+      vips: "libvips-helper",
+      imagemagick: "imagemagick",
+      vips_helper: "libvips-helper",
+      svg_metadata: "svg-metadata",
+      ico_metadata: "ico-metadata",
+      ico_vips: "ico-ruby+libvips-helper",
+      jpegtran: "jpegtran"
+    }.freeze
+
+    def build(backend, encoder: nil)
+      base = BASE.fetch(backend.to_sym)
+      encoder.to_s == "cjpegli" ? "#{base}+cjpegli" : base
+    end
+  end
+
+  private_constant :BackendLabel
+end

data/lib/safe_image/formats.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module SafeImage
+  # Single source of truth for Ruby-side format normalization and allowlists.
+  # Native C helpers keep their own low-level allowlists, but Ruby orchestration
+  # should ask this module before building backend-specific commands.
+  module Formats
+    module_function
+
+    NATIVE_INPUTS = %w[jpg png gif webp heic heif avif jxl].freeze
+    NATIVE_OUTPUTS = %w[jpg png gif webp avif jxl].freeze
+    IMAGEMAGICK_INPUTS = (NATIVE_INPUTS + %w[ico]).freeze
+    IMAGEMAGICK_OUTPUTS = (NATIVE_OUTPUTS + %w[ico]).freeze
+    OPTIMIZABLE_OUTPUTS = %w[jpg png].freeze
+    CJPEGLI_DIRECT_INPUTS = %w[png].freeze
+
+    IMAGEMAGICK_DECODERS = {
+      "jpg" => "jpeg",
+      "png" => "png",
+      "gif" => "gif",
+      "webp" => "webp",
+      "heic" => "heic",
+      "heif" => "heic",
+      "avif" => "heic",
+      "ico" => "ico",
+      "jxl" => "jxl"
+    }.freeze
+
+    IMAGEMAGICK_OUTPUT_CODERS = {
+      "jpg" => "jpeg",
+      "png" => "png",
+      "gif" => "gif",
+      "webp" => "webp",
+      "avif" => "avif",
+      "ico" => "ico",
+      "jxl" => "jxl"
+    }.freeze
+
+    def normalize(format)
+      format = format.to_s.delete_prefix(".").downcase
+      format == "jpeg" ? "jpg" : format
+    end
+
+    # Canonical names used by libvips' explicit loaders/savers. HEIF-family
+    # inputs share the HEIC loader; AVIF remains distinct because saves need the
+    # AV1 compression option.
+    def native_canonical(format)
+      normalized = normalize(format)
+      normalized == "heif" ? "heic" : normalized
+    end
+
+    def extension(path)
+      normalize(File.extname(PathSafety.local_path(path)).delete_prefix("."))
+    end
+
+    def native_input?(format)
+      NATIVE_INPUTS.include?(normalize(format))
+    end
+
+    def native_output?(format)
+      NATIVE_OUTPUTS.include?(normalize(format))
+    end
+
+    def imagemagick_input?(format)
+      IMAGEMAGICK_INPUTS.include?(normalize(format))
+    end
+
+    def imagemagick_output?(format)
+      IMAGEMAGICK_OUTPUTS.include?(normalize(format))
+    end
+
+    def optimizable_output?(format)
+      OPTIMIZABLE_OUTPUTS.include?(normalize(format))
+    end
+
+    def cjpegli_direct_input?(format)
+      CJPEGLI_DIRECT_INPUTS.include?(normalize(format))
+    end
+
+    def imagemagick_decoder(format)
+      normalized = normalize(format)
+      IMAGEMAGICK_DECODERS.fetch(normalized) do
+        raise UnsupportedFormatError, "unsupported ImageMagick input format: #{normalized.inspect}"
+      end
+    end
+
+    def imagemagick_output_coder(format)
+      normalized = normalize(format)
+      IMAGEMAGICK_OUTPUT_CODERS.fetch(normalized) do
+        raise UnsupportedFormatError, "unsupported ImageMagick output format: #{normalized.inspect}"
+      end
+    end
+  end
+
+  private_constant :Formats
+end

data/lib/safe_image/ico.rb

@@ -45,7 +45,7 @@ module SafeImage
     end
 
     # Extracts the largest icon and writes it as PNG. Returns an info hash in
-    # the shape DiscourseCompat.result_from_info expects.
+    # the shape OperationBackends::Base#result_from_info expects.
     def convert_to_png(input, output, max_pixels: nil)
       started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
       data, entries = parse(input)
@@ -53,25 +53,27 @@ module SafeImage
       output = PathSafety.ensure_safe_output_path!(output).to_s
 
       width = height = nil
-      if entry.png
-        # Enforce the pixel cap from the IHDR dimensions before the payload
-        # reaches a decoder.
-        validate_pixels!(*entry_dimensions(data, entry), max_pixels)
-        payload = data.byteslice(entry.offset, entry.size)
-        Tempfile.create(["safe-image-ico", ".png"]) do |tmp|
-          tmp.binmode
-          tmp.write(payload)
-          tmp.close
-          # Sanitizing no-op resize: validates the PNG bytes, enforces the
-          # pixel cap and strips metadata on the way through libvips.
-          info = Native.resize(tmp.path, output, 1.0, "png", 100, max_pixels)
-          width = info.fetch(:width)
-          height = info.fetch(:height)
+      StagedOutput.replace(output, suffix: ".safe-image.png") do |tmp_path|
+        if entry.png
+          # Enforce the pixel cap from the IHDR dimensions before the payload
+          # reaches a decoder.
+          validate_pixels!(*entry_dimensions(data, entry), max_pixels)
+          payload = data.byteslice(entry.offset, entry.size)
+          Tempfile.create(%w[safe-image-ico .png]) do |tmp|
+            tmp.binmode
+            tmp.write(payload)
+            tmp.close
+            # Sanitizing no-op resize: validates the PNG bytes, enforces the
+            # pixel cap and strips metadata on the way through libvips.
+            info = Native.resize(tmp.path, tmp_path.to_s, 1.0, "png", 100, max_pixels)
+            width = info.fetch(:width)
+            height = info.fetch(:height)
+          end
+        else
+          rgba, width, height = decode_rgba(data, entry)
+          validate_pixels!(width, height, max_pixels)
+          Native.png_from_rgba(rgba, width, height, tmp_path.to_s)
         end
-      else
-        rgba, width, height = decode_rgba(data, entry)
-        validate_pixels!(width, height, max_pixels)
-        Native.png_from_rgba(rgba, width, height, output)
       end
 
       {
@@ -83,14 +85,6 @@ module SafeImage
       }
     end
 
-    def dominant_color(path, max_pixels: nil)
-      Tempfile.create(["safe-image-ico", ".png"]) do |tmp|
-        tmp.close
-        convert_to_png(path, tmp.path, max_pixels: max_pixels)
-        VipsBackend.dominant_color(tmp.path, max_pixels: max_pixels)
-      end
-    end
-
     # -- container parsing ---------------------------------------------------
 
     def parse(path)
@@ -136,7 +130,7 @@ module SafeImage
     # PNG payloads carry their real dimensions in the IHDR chunk; the
     # one-byte directory fields saturate at 256.
     def entry_dimensions(data, entry)
-      return [entry.width, entry.height] unless entry.png
+      return entry.width, entry.height unless entry.png
       raise InvalidImageError, "png payload is truncated" if entry.size < 24
       data.byteslice(entry.offset + 16, 8).unpack("NN")
     end
@@ -160,7 +154,7 @@ module SafeImage
         payload.unpack("Vl<l<vvVVl<l<V")
       raise InvalidImageError, "unsupported dib header (size #{header_size})" if header_size != 40
       raise InvalidImageError, "unsupported dib compression #{compression}" unless compression == BI_RGB
-      raise InvalidImageError, "unsupported dib bit depth #{bpp}" unless [1, 4, 8, 24, 32].include?(bpp)
+      raise InvalidImageError, "unsupported dib bit depth #{bpp}" if [1, 4, 8, 24, 32].none? { |bits| bits == bpp }
 
       top_down = height2.negative?
       height = height2.abs / 2
@@ -174,9 +168,12 @@ module SafeImage
         palette_count = colors_used.zero? ? (1 << bpp) : colors_used
         raise InvalidImageError, "dib palette is invalid" if palette_count > 1 << bpp
         raise InvalidImageError, "dib palette is truncated" if payload.bytesize < palette_offset + palette_count * 4
-        palette = payload.byteslice(palette_offset, palette_count * 4).unpack("C*").each_slice(4).map do |b, g, r, _x|
-          [r, g, b]
-        end
+        palette =
+          payload
+            .byteslice(palette_offset, palette_count * 4)
+            .unpack("C*")
+            .each_slice(4)
+            .map { |b, g, r, _x| [r, g, b] }
         palette_offset += palette_count * 4
       end
 
@@ -184,7 +181,9 @@ module SafeImage
       and_stride = ((width + 31) / 32) * 4
       xor_bytes = xor_stride * height
       and_bytes = and_stride * height
-      raise InvalidImageError, "dib pixel data is truncated" if payload.bytesize < palette_offset + xor_bytes + and_bytes
+      if payload.bytesize < palette_offset + xor_bytes + and_bytes
+        raise InvalidImageError, "dib pixel data is truncated"
+      end
 
       xor_data = payload.byteslice(palette_offset, xor_bytes)
       and_data = payload.byteslice(palette_offset + xor_bytes, and_bytes)
@@ -205,9 +204,7 @@ module SafeImage
     # rotate-right-by-8.
     def decode_32bpp(xor_data, and_data, width, height, and_stride, top_down)
       stride = width * 4
-      unless top_down
-        xor_data = (0...height).map { |y| xor_data.byteslice((height - 1 - y) * stride, stride) }.join
-      end
+      xor_data = (0...height).map { |y| xor_data.byteslice((height - 1 - y) * stride, stride) }.join unless top_down
       pixels = xor_data.unpack("N*")
 
       if alpha_all_zero?(xor_data)
@@ -261,10 +258,15 @@ module SafeImage
 
           index =
             case bpp
-            when 8 then xor_row.getbyte(x)
-            when 4 then (byte = xor_row.getbyte(x >> 1)
-                         x.even? ? byte >> 4 : byte & 0x0F)
-            else (xor_row.getbyte(x >> 3) >> (7 - (x & 7))) & 1
+            when 8
+              xor_row.getbyte(x)
+            when 4
+              (
+                byte = xor_row.getbyte(x >> 1)
+                x.even? ? byte >> 4 : byte & 0x0F
+              )
+            else
+              (xor_row.getbyte(x >> 3) >> (7 - (x & 7))) & 1
             end
           rgba << (masked ? transparent : opaque).fetch(index) do
             raise InvalidImageError, "dib palette index #{index} is out of range"