safe_image 0.2.0 → 0.4.0

data/lib/safe_image/result.rb

@@ -1,28 +1,76 @@
 # frozen_string_literal: true
 
 module SafeImage
-  Info = Data.define(
-    :path,
-    :type,
-    :width,
-    :height,
-    :size,
-    :animated,
-    :orientation
-  )
+  # Public metadata return value. Optional fields (`animated`, `orientation`) are
+  # nil unless the caller opts into the extra probes.
+  Info = Data.define(:path, :type, :width, :height, :size, :animated, :orientation)
 
-  Result = Data.define(
-    :input,
-    :output,
-    :input_format,
-    :output_format,
-    :width,
-    :height,
-    :filesize,
-    :backend,
-    :duration_ms,
-    :optimizer
-  ) do
-    def success? = true
-  end
+  # Public image-operation return value. `output`/`output_format` are nil for
+  # metadata-only probes; image-producing operations always include them. `tier`
+  # records the concrete execution tier (for example :native_encode,
+  # :jpegtran_lossless or :jpegtran_fallback_reencode) so non-fatal degradation
+  # is observable without parsing the backend label.
+  Result =
+    Data.define(
+      :input,
+      :output,
+      :input_format,
+      :output_format,
+      :width,
+      :height,
+      :filesize,
+      :backend,
+      :duration_ms,
+      :optimizer,
+      :tier
+    ) do
+      def self.build(
+        input:,
+        output: nil,
+        input_format:,
+        output_format: nil,
+        width:,
+        height:,
+        backend:,
+        duration_ms:,
+        filesize: nil,
+        optimizer: nil,
+        encoder: nil,
+        tier: nil
+      )
+        new(
+          input: input.to_s,
+          output: output&.to_s,
+          input_format: input_format,
+          output_format: output_format,
+          width: width,
+          height: height,
+          filesize: filesize || result_filesize(input, output),
+          backend: BackendLabel.build(backend, encoder: encoder),
+          duration_ms: duration_ms,
+          optimizer: optimizer,
+          tier: tier
+        )
+      end
+
+      def self.metadata(input:, input_format:, width:, height:, backend:, duration_ms:)
+        build(
+          input: input,
+          input_format: input_format,
+          width: width,
+          height: height,
+          filesize: File.size(input),
+          backend: backend,
+          duration_ms: duration_ms,
+          tier: :metadata
+        )
+      end
+
+      def self.result_filesize(input, output)
+        path = output || input
+        path ? File.size(path) : nil
+      end
+
+      def success? = true
+    end
 end

data/lib/safe_image/runner.rb

@@ -6,14 +6,26 @@ require "timeout"
 
 module SafeImage
   class CommandError < Error
-    attr_reader :command, :status, :stdout, :stderr
-
-    def initialize(message, command:, status: nil, stdout: "", stderr: "")
-      super(message)
+    attr_reader :command, :status, :stdout, :stderr, :category, :operation
+
+    def initialize(
+      message,
+      command:,
+      status: nil,
+      stdout: "",
+      stderr: "",
+      category: :command,
+      operation: nil,
+      original_error_class: nil,
+      stderr_tail: nil
+    )
+      super(message, original_error_class: original_error_class, stderr_tail: stderr_tail)
       @command = command
       @status = status
       @stdout = stdout
       @stderr = stderr
+      @category = category&.to_sym
+      @operation = operation&.to_sym
     end
   end
 
@@ -22,13 +34,24 @@ module SafeImage
 
     DEFAULT_TIMEOUT = 20
     MAX_OUTPUT_BYTES = 512 * 1024
+    # Give well-behaved tools a short flush window after TERM before KILL keeps
+    # the timeout hard without leaking process groups.
+    TERMINATE_GRACE_SECONDS = 0.2
     TRUSTED_PATH = "/usr/bin:/bin:/usr/local/bin".freeze
     ALLOWED_ENV_KEYS = %w[LANG LC_ALL LC_CTYPE TZ].freeze
     IMAGEMAGICK_POLICY_PATH = File.expand_path("imagemagick_policy", __dir__)
     IMAGEMAGICK_POLICY_FILE = File.join(IMAGEMAGICK_POLICY_PATH, "policy.xml").freeze
     BASE_ENV = {
       "PATH" => TRUSTED_PATH,
-      "VIPS_BLOCK_UNTRUSTED" => "1"
+      "VIPS_BLOCK_UNTRUSTED" => "1",
+      # Cap glibc's per-thread malloc arenas. Multithreaded tools (oxipng's
+      # rayon pool, ImageMagick's OpenMP) otherwise reserve an arena per thread
+      # — up to 8x64MB of *address space* per core — which, combined with the
+      # sandbox's RLIMIT_AS memory cap, spuriously fails the tool under
+      # concurrency even though real memory use is tiny. AS counts reservations,
+      # not RSS; bounding arenas is the standard mitigation and costs nothing
+      # for these compute-bound tools.
+      "MALLOC_ARENA_MAX" => "2"
     }.freeze
 
     def run!(argv, timeout: DEFAULT_TIMEOUT, env: {}, sandbox: false, read: [], write: [])
@@ -62,7 +85,13 @@ module SafeImage
           remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
           if remaining <= 0
             kill_process_group(wait_thr.pid)
-            raise CommandError.new("command timed out after #{timeout}s", command: argv, stdout: stdout, stderr: stderr)
+            raise CommandError.new(
+                    "command timed out after #{timeout}s",
+                    command: argv,
+                    stdout: stdout,
+                    stderr: stderr,
+                    category: :timeout
+                  )
           end
 
           readable, = IO.select(streams.keys, nil, nil, remaining)
@@ -75,7 +104,13 @@ module SafeImage
               buffer << chunk
               if buffer.bytesize > MAX_OUTPUT_BYTES
                 kill_process_group(wait_thr.pid)
-                raise CommandError.new("command output exceeded #{MAX_OUTPUT_BYTES} bytes", command: argv, stdout: stdout, stderr: stderr)
+                raise CommandError.new(
+                        "command output exceeded #{MAX_OUTPUT_BYTES} bytes",
+                        command: argv,
+                        stdout: stdout,
+                        stderr: stderr,
+                        category: :output_limit
+                      )
               end
             rescue IO::WaitReadable
               next
@@ -95,7 +130,13 @@ module SafeImage
           remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
           if remaining <= 0
             kill_process_group(wait_thr.pid)
-            raise CommandError.new("command timed out after #{timeout}s", command: argv, stdout: stdout, stderr: stderr)
+            raise CommandError.new(
+                    "command timed out after #{timeout}s",
+                    command: argv,
+                    stdout: stdout,
+                    stderr: stderr,
+                    category: :timeout
+                  )
           end
           status = wait_thr.join(remaining)&.value
         end
@@ -106,15 +147,16 @@ module SafeImage
         raise
       end
 
-      return [stdout, stderr] if status&.success?
+      return stdout, stderr if status&.success?
 
       raise CommandError.new(
-        "command failed: #{argv.first} exited #{status&.exitstatus}",
-        command: argv,
-        status: status&.exitstatus,
-        stdout: stdout,
-        stderr: stderr
-      )
+              "command failed: #{argv.first} exited #{status&.exitstatus}",
+              command: argv,
+              status: status&.exitstatus,
+              stdout: stdout,
+              stderr: stderr,
+              category: :exit_status
+            )
     end
 
     def kill_process_group(pid)
@@ -122,17 +164,18 @@ module SafeImage
     rescue Errno::ESRCH, Errno::EPERM
     ensure
       begin
-        sleep 0.2
+        sleep TERMINATE_GRACE_SECONDS
         Process.kill("KILL", -pid)
       rescue Errno::ESRCH, Errno::EPERM
       end
     end
 
     def command_env(tmpdir, env = {})
-      allowed = env.each_with_object({}) do |(key, value), hash|
-        key = key.to_s
-        hash[key] = value.to_s if ALLOWED_ENV_KEYS.include?(key)
-      end
+      allowed =
+        env.each_with_object({}) do |(key, value), hash|
+          key = key.to_s
+          hash[key] = value.to_s if ALLOWED_ENV_KEYS.include?(key)
+        end
 
       BASE_ENV.merge(
         "MAGICK_CONFIGURE_PATH" => IMAGEMAGICK_POLICY_PATH,
@@ -163,10 +206,12 @@ module SafeImage
       name = name.to_s
       return name if name.include?(File::SEPARATOR) && File.file?(name) && File.executable?(name)
 
-      TRUSTED_PATH.split(File::PATH_SEPARATOR).each do |dir|
-        path = File.join(dir, name)
-        return path if File.file?(path) && File.executable?(path)
-      end
+      TRUSTED_PATH
+        .split(File::PATH_SEPARATOR)
+        .each do |dir|
+          path = File.join(dir, name)
+          return path if File.file?(path) && File.executable?(path)
+        end
 
       nil
     end

data/lib/safe_image/sandbox.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require "json"
 require "rbconfig"
 require "tmpdir"
 
@@ -15,208 +14,67 @@ module SafeImage
       open_files: 256
     }.freeze
 
-    OPERATIONS = %w[
-      probe thumbnail type size dimensions info orientation dominant_color optimize resize crop downsize convert convert_to_jpeg fix_orientation
-      convert_favicon_to_png frame_count animated? letter_avatar optimize_image!
-      sanitize_svg!
-    ].freeze
-
     def available?
       require "landlock"
-      Landlock::SafeExec.supported?
+      landlock_supported?
     rescue LoadError
       false
     end
 
-    def capture_command!(argv, read:, write:, timeout: Runner::DEFAULT_TIMEOUT, env: nil, rlimits: DEFAULT_RLIMITS)
-      require "landlock"
-      env ||= Runner.command_env(Dir.tmpdir)
-
-      result = Landlock::SafeExec.capture!(
-        *argv.map(&:to_s),
-        read: existing_paths([*Landlock::SafeExec.default_read_paths, *runtime_read_paths, *read]),
-        write: existing_paths(write),
-        execute: existing_paths([*Landlock::SafeExec.default_execute_paths, File.dirname(RbConfig.ruby)]),
-        env: env.merge("SAFE_IMAGE_SANDBOX_CHILD" => "1"),
-        inherit_env: false,
-        timeout: timeout,
-        rlimits: rlimits,
-        seccomp_deny_network: true,
-        max_output_bytes: 512 * 1024,
-        truncate_output: false
-      )
-      [result.stdout, result.stderr]
-    rescue LoadError
-      raise Error, "landlock sandbox requested but the landlock gem is unavailable"
-    rescue Landlock::SafeExec::CommandError => e
-      raise CommandError.new(
-        "sandboxed command failed: #{failure_detail(e)}",
-        command: argv,
-        status: e.status&.exitstatus,
-        stdout: e.stdout,
-        stderr: e.stderr
-      )
+    def landlock_supported?
+      Landlock.supported?
     end
 
-    def public_call!(operation, args:, kwargs:)
-      operation = operation.to_s
-      raise ArgumentError, "unsupported sandbox operation: #{operation}" unless OPERATIONS.include?(operation)
-      result = run_worker!(operation, { args: args, kwargs: kwargs })
-      operation == "type" && result ? result.to_sym : result
+    def landlock_command_error
+      Landlock::CommandError
     end
 
-    def run_worker!(operation, request)
-      operation = operation.to_s
-      raise ArgumentError, "unsupported sandbox operation: #{operation}" unless OPERATIONS.include?(operation)
-
-      require "landlock"
-      config = SafeImage.config
-      payload = JSON.dump(
-        {
-          operation: operation,
-          request: request,
-          # The worker is a fresh process and must be configured like the
-          # parent — minus landlock, since it already runs inside the sandbox.
-          config: { backend: config.backend, max_pixels: config.max_pixels }
-        }
-      )
-      code = <<~'RUBY'
-        require "json"
-        require "safe_image"
-
-        def deep_symbolize(value)
-          case value
-          when Hash
-            value.each_with_object({}) { |(k, v), h| h[k.to_sym] = deep_symbolize(v) }
-          when Array
-            value.map { |v| deep_symbolize(v) }
-          else
-            value
-          end
-        end
-
-        payload = JSON.parse(ARGV.fetch(0), symbolize_names: true)
-        operation = payload.fetch(:operation).to_s
-        allowed_operations = %w[
-          probe thumbnail type size dimensions info orientation dominant_color optimize resize crop downsize convert convert_to_jpeg fix_orientation
-          convert_favicon_to_png frame_count animated? letter_avatar optimize_image! sanitize_svg!
-        ]
-        raise ArgumentError, "unsupported sandbox operation: #{operation}" unless allowed_operations.include?(operation)
-
-        request = payload.fetch(:request)
-        args = request[:args] || []
-        kwargs = deep_symbolize(request[:kwargs] || {})
+    def landlock_abi
+      Landlock.abi_version
+    end
 
-        config = payload.fetch(:config)
-        SafeImage.configure!(
-          backend: config.fetch(:backend).to_sym,
-          landlock: false,
-          max_pixels: config.fetch(:max_pixels)
-        )
+    def default_read_paths
+      %w[/usr /lib /lib64 /etc /bin /sbin /opt].select { |path| File.exist?(path) }
+    end
 
-        result = SafeImage.__send__(operation, *args, **kwargs)
+    def default_execute_paths
+      %w[/usr /lib /lib64 /bin /sbin /opt].select { |path| File.exist?(path) }
+    end
 
-        if defined?(SafeImage::Result) && result.is_a?(SafeImage::Result)
-          puts JSON.dump({ __type: "Result", data: result.to_h })
-        elsif defined?(SafeImage::Info) && result.is_a?(SafeImage::Info)
-          puts JSON.dump({ __type: "Info", data: result.to_h })
-        else
-          puts JSON.dump({ __type: "Value", data: result })
-        end
-      RUBY
+    def landlock_capture!(argv, **options)
+      Landlock.capture!(argv.map(&:to_s), allow_all_known: true, **options)
+    end
 
-      paths = sandbox_paths(request, operation)
-      Dir.mktmpdir("safe-image-worker-") do |tmpdir|
-        worker_env = Runner.command_env(tmpdir).merge(
-          "SAFE_IMAGE_SANDBOX_CHILD" => "1",
-          "GEM_HOME" => ENV["GEM_HOME"].to_s,
-          "GEM_PATH" => ENV["GEM_PATH"].to_s,
-          "RUBYLIB" => $LOAD_PATH.select { |p| p && File.directory?(p) }.join(File::PATH_SEPARATOR)
-        )
+    def capture_command!(argv, read:, write:, timeout: Runner::DEFAULT_TIMEOUT, env: nil, rlimits: DEFAULT_RLIMITS)
+      require "landlock"
+      env ||= Runner.command_env(Dir.tmpdir)
 
-        stdout, = Landlock::SafeExec.capture!(
-          RbConfig.ruby,
-          "-I#{File.expand_path("../../", __dir__)}",
-          "-rjson",
-          "-e",
-          code,
-          payload,
-          read: existing_paths([*Landlock::SafeExec.default_read_paths, *runtime_read_paths, *paths.fetch(:read), tmpdir]),
-          write: existing_paths([*paths.fetch(:write), tmpdir]),
-          execute: existing_paths([*Landlock::SafeExec.default_execute_paths, File.dirname(RbConfig.ruby)]),
-          env: worker_env,
-          inherit_env: false,
-          timeout: Runner::DEFAULT_TIMEOUT,
-          rlimits: DEFAULT_RLIMITS,
+      result =
+        landlock_capture!(
+          argv,
+          read: existing_paths([*default_read_paths, *runtime_read_paths, *read]),
+          write: existing_paths(write),
+          execute: existing_paths([*default_execute_paths, File.dirname(RbConfig.ruby)]),
+          env: env.merge("SAFE_IMAGE_SANDBOX_CHILD" => "1"),
+          unsetenv_others: true,
+          timeout: timeout,
+          rlimits: rlimits,
           seccomp_deny_network: true,
           max_output_bytes: 512 * 1024,
           truncate_output: false
         )
-        response = JSON.parse(stdout, symbolize_names: true)
-        if response[:__type] == "Result"
-          data = response.fetch(:data)
-          Result.new(**data)
-        elsif response[:__type] == "Info"
-          data = response.fetch(:data)
-          Info.new(**data)
-        else
-          response[:data]
-        end
-      end
+      [result.stdout, result.stderr]
     rescue LoadError
       raise Error, "landlock sandbox requested but the landlock gem is unavailable"
-    rescue Landlock::SafeExec::CommandError => e
+    rescue landlock_command_error => e
       raise CommandError.new(
-        "sandboxed worker failed: #{failure_detail(e)}",
-        command: [RbConfig.ruby, "-e", "..."],
-        status: e.status&.exitstatus,
-        stdout: e.stdout,
-        stderr: e.stderr
-      )
-    end
-
-    def sandbox_paths(request, operation)
-      read = []
-      write = []
-
-      values = []
-      values.concat(Array(request[:args]))
-      values.concat(Array(request.dig(:kwargs)&.values))
-      values.flatten.compact.each do |value|
-        next unless value.is_a?(String)
-        next if value.empty? || value.include?("\0")
-
-        expanded = File.expand_path(value) rescue next
-        if File.exist?(expanded)
-          read << expanded
-        elsif looks_like_path?(value)
-          write << File.dirname(expanded)
-        end
-      end
-
-      # Common keyword names for generated outputs. Include the containing dir
-      # even when a stale file already exists, because operations may replace it.
-      kwargs = request[:kwargs] || {}
-      %i[output to path].each do |key|
-        next unless kwargs[key].is_a?(String)
-        write << File.dirname(File.expand_path(kwargs[key]))
-      end
-
-      # In-place mutators need write permission for an existing input path too.
-      if %w[optimize optimize_image! sanitize_svg! fix_orientation].include?(operation.to_s)
-        first = Array(request[:args]).first
-        if first.is_a?(String) && File.exist?(first)
-          expanded = File.expand_path(first)
-          write << expanded
-          write << File.dirname(expanded)
-        end
-      end
-
-      { read: read.uniq, write: write.uniq }
-    end
-
-    def looks_like_path?(value)
-      value.start_with?("/", "./", "../") || File.extname(value) != ""
+              "sandboxed command failed: #{failure_detail(e)}",
+              command: argv,
+              status: e.status&.exitstatus,
+              stdout: e.stdout,
+              stderr: e.stderr,
+              category: :sandbox_command
+            )
     end
 
     def runtime_read_paths
@@ -229,12 +87,11 @@ module SafeImage
       paths << RbConfig::CONFIG["vendorarchdir"]
       # An --enable-shared Ruby installed outside the default read roots
       # (e.g. GitHub Actions' /opt/hostedtoolcache builds) keeps libruby in
-      # libdir; without read access the worker dies at dynamic-link time
-      # before any Ruby code runs.
+      # libdir; helper/tool subprocesses need read access before they can start.
       paths << RbConfig::CONFIG["libdir"]
       paths << File.dirname(RbConfig.ruby)
       # Pango/fontconfig need the font directories and configs for the native
-      # letter_avatar text rendering inside the worker.
+      # letter_avatar text rendering inside the helper.
       paths << "/etc/fonts"
       paths << "/usr/share/fonts"
       paths << "/usr/local/share/fonts"
@@ -246,17 +103,13 @@ module SafeImage
       paths.flatten.compact.map(&:to_s).reject(&:empty?).select { |path| File.exist?(path) }.uniq
     end
 
-    # Sandbox failures often happen before the child can run any Ruby (e.g. a
-    # denied shared-library read kills it at dynamic-link time); without the
-    # child's stderr in the message they are undiagnosable from a CI log.
+    # Sandbox failures often happen before the child can write structured output
+    # (e.g. a denied shared-library read kills it at dynamic-link time); include
+    # stderr so CI logs remain diagnosable.
     def failure_detail(error)
       detail = error.stderr.to_s.strip
       detail = "exit status #{error.status&.exitstatus.inspect}" if detail.empty?
       detail[0, 2000]
     end
-
-    def symbolize(hash)
-      hash.transform_keys(&:to_sym)
-    end
   end
 end

data/lib/safe_image/staged_output.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "pathname"
+require "tempfile"
+
+module SafeImage
+  # Helpers for same-directory temporary outputs. External tools often require a
+  # path, not an fd, so the helper intentionally creates and closes the tempfile
+  # before yielding its path. The temp path is always next to the destination so
+  # the final move stays on the same filesystem.
+  module StagedOutput
+    module_function
+
+    def replace(output, suffix: nil)
+      output_path = PathSafety.ensure_safe_output_path!(output)
+      output_path.dirname.mkpath
+      with_temp_path(output_path, suffix: suffix || output_path.extname) do |tmp_path|
+        result = yield tmp_path, output_path
+        FileUtils.mv(tmp_path, output_path)
+        result
+      end
+    end
+
+    def with_temp_path_near(output, suffix:)
+      output_path = PathSafety.ensure_safe_output_path!(output)
+      output_path.dirname.mkpath
+      with_temp_path(output_path, suffix: suffix) { |tmp_path| yield tmp_path, output_path }
+    end
+
+    def with_temp_path(output_path, suffix:)
+      Tempfile.create([output_path.basename(".*").to_s, suffix], output_path.dirname.to_s) do |tmp|
+        tmp_path = Pathname.new(tmp.path)
+        tmp.close
+        yield tmp_path
+      ensure
+        FileUtils.rm_f(tmp_path) if defined?(tmp_path) && tmp_path
+      end
+    end
+    private_class_method :with_temp_path
+  end
+
+  private_constant :StagedOutput
+end