oximg 0.19.0-x86_64-linux-gnu → 0.20.0-x86_64-linux-gnu

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fdd7fdd2f3c27c97b38a6508bf50964ae4f00f1be242a5dd97e07a206955a015
-  data.tar.gz: 6a9423ee0d2dc23a51cafdb5d162a231839cd4438bad3f48a1ed6896efd536f9
+  metadata.gz: '06849ede237a4dc45defa469d60d6eb4099d96faa5331943309d67fb663f3f28'
+  data.tar.gz: 71ea1303b3b7e214e1b45a356f13a020767e1d2a4e29261df5b8952b0fc28fe7
 SHA512:
-  metadata.gz: 6f93b5ae88282b32281e31468d217dfd82ebaec92b4ccccfbedf84b921d18fb436763c9721fbad8e320ff938ff91c03c2d21c466d7d4283738b9489b6ef3bfe0
-  data.tar.gz: baa7d3df34af999f1f6fef0c2d1c69195053a00566eac36dbef8897ce015b713f5ac0c0957bb0f83a7e4b17005b3d75c6b286a11c9c573fab6a7e527b741130b
+  metadata.gz: b16f37b956d93aef19e8878d8cc5577b0e6d88fd70bfa2270a49bad0aa2686fc149c982ca1aaf24593ad765ba28e34d84df1dff12737ed8d667c104472b0c19e
+  data.tar.gz: fa6968198360451ca0527316b722a2c643192016a980d46ab8e30969617b6682f70e00b2f6d492afa015cc8b85d8caca04fefd13e60cd37ac74301b4ae462708

data/README.md

@@ -85,10 +85,32 @@ re-encoding: its compressed 8x8 blocks are moved, as `jpegtran
 reader, not only for ones that honor EXIF. That is only exact when the
 edges it moves are whole 8 or 16 px blocks (a phone's 4032x3024 is);
 otherwise, and for PNG and WebP, the file is stripped as without it,
-orientation kept. `Oximg.probe(destination)` tells which: orientation
-1, or the one kept. It costs a full entropy decode and encode, about
+orientation kept. It costs a full entropy decode and encode, about
 170 ms for a 12 MP photo.
 
+`strip` returns an `Oximg::Stripped`, the binary's own account of the
+run, so telling which happened needs no second read:
+
+```ruby
+result = Oximg.strip(upload, clean, icc: :keep, auto_rotate: true)
+result.upright?             # no orientation tag left: stored size is displayed size
+result.rotated?             # the pixels were turned upright
+result.orientation          #=> 6, the tag kept, or nil
+result.not_rotated&.code    #=> :unaligned_edges, :corrupt, :over_limit or :not_jpeg
+result.not_rotated&.message # for humans; the wording may change
+```
+
+`not_rotated` is nil unless `auto_rotate: true` left a rotated source
+tagged. The code is the contract (the table is in
+[docs/features/paths.md](../../docs/features/paths.md)), so count
+fallbacks by it. The result also stands in for the destination path
+`strip` used to return: `to_s`, `to_path` and `to_str` are the path and
+it compares equal to that String, so `File.size(Oximg.strip(...))`
+still works. With an `oximg` older than 0.20, which has no `strip
+--json`, the gem reads the summary line that binary prints instead:
+`orientation` and `rotated?` are still right, `removed` is nil, and
+the code is `:unknown` beside the binary's own reason.
+
 ## Knobs, per process or per call
 
 Everything the server tunes through `OXIMG_*` environment variables
@@ -181,8 +203,8 @@ Oximg.in_process_probe?  #=> true on a platform gem
 
 ```ruby
 Oximg.available?  #=> true
-Oximg.executable  #=> "/…/gems/oximg-0.19.0-arm64-darwin/exe/oximg"
-Oximg.version     #=> "0.19.0"   # the binary's version, not the gem's
+Oximg.executable  #=> "/…/gems/oximg-0.20.0-arm64-darwin/exe/oximg"
+Oximg.version     #=> "0.20.0"   # the binary's version, not the gem's
 ```
 
 `resize` shells out to that binary — one process per image, which is

data/lib/oximg/binary.rb

@@ -76,11 +76,23 @@ module Oximg
         [out, err]
       end
 
+      # True once the executable refused `strip --json` (an oximg older
+      # than 0.20): Oximg.strip then runs without it and reads the
+      # summary line that binary prints. Memoized per executable, like
+      # the path, so a process
+      # pays the refused spawn once.
+      attr_accessor :legacy_strip
+
+      def legacy_strip?
+        @legacy_strip == true
+      end
+
       # Resets the memoized lookup. For tests, and for a process that
       # changes OXIMG_BIN after boot.
       def reset!
         @path = nil
         @version = nil
+        @legacy_strip = nil
       end
 
       private

data/lib/oximg/stripped.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Oximg
+  # What Oximg.strip did: where it wrote, and whether the output
+  # displays upright. Built from <tt>oximg strip --json</tt>, so it is
+  # the binary's own account of the run, not a second read of the file.
+  #
+  # It stands in for the destination path Oximg.strip returned before
+  # (#176): #to_s, #to_path and #to_str are the path, and it compares
+  # equal to that path as a String, so
+  # <tt>File.size(Oximg.strip(...))</tt>, <tt>File.join</tt> and
+  # <tt>assert_equal out, Oximg.strip(...)</tt> keep working.
+  #
+  #   result = Oximg.strip(upload, clean, auto_rotate: true)
+  #   result.rotated?                #=> false
+  #   result.orientation             #=> 6, the tag the output keeps
+  #   result.not_rotated.code        #=> :unaligned_edges
+  #   result.not_rotated.message     #=> "1601x1203 does not divide into ..."
+  class Stripped
+    # Why <tt>auto_rotate: true</tt> left a rotated source tagged.
+    # +code+ is the contract, a Symbol from NOT_ROTATED_CODES (or
+    # :unknown, below); +message+ is for humans and may change.
+    NotRotated = Data.define(:code, :message)
+
+    # The binary's codes (docs/features/paths.md). A code missing here
+    # still comes through, as its Symbol: a newer binary may add one.
+    NOT_ROTATED_CODES = %i[unaligned_edges corrupt over_limit not_jpeg].freeze
+
+    # The destination, absolute.
+    attr_reader :path
+    # The output's content type ("image/jpeg", ...).
+    attr_reader :content_type
+    # Output size in bytes.
+    attr_reader :bytes
+    # What was dropped: <tt>[{name: "APP1 Exif", count: 1, bytes: 1204}, ...]</tt>;
+    # nil from an oximg older than 0.20.
+    attr_reader :removed
+    # The orientation tag the output keeps, 2..8, or nil when it
+    # displays as stored (upright, untagged, or rotated upright).
+    attr_reader :orientation
+    # The orientation turned into the pixels, 2..8, or nil.
+    attr_reader :rotated
+    # A NotRotated, or nil unless auto_rotate left a rotated source
+    # tagged. From an oximg older than 0.20, which has no --json and
+    # gives the reason only as a sentence, the code is :unknown.
+    attr_reader :not_rotated
+
+    # From the hash <tt>oximg strip --json</tt> prints.
+    def self.from_json(path, report)
+      why = report["not_rotated"]
+      new(
+        path: path,
+        content_type: report["content_type"],
+        bytes: report["bytes"],
+        removed: report["removed"]&.map { |r| {name: r["name"], count: r["count"], bytes: r["bytes"]} },
+        orientation: report["orientation"],
+        rotated: report["rotated"],
+        not_rotated: why && NotRotated.new(code: why["code"].to_sym, message: why["message"])
+      )
+    end
+
+    def initialize(path:, bytes:, content_type:, orientation:, rotated:, not_rotated:, removed: nil)
+      @path = path
+      @content_type = content_type
+      @bytes = bytes
+      @removed = removed
+      @orientation = orientation
+      @rotated = rotated
+      @not_rotated = not_rotated
+      freeze
+    end
+
+    # True when the pixels were turned upright (auto_rotate).
+    def rotated?
+      !@rotated.nil?
+    end
+
+    # True when the output displays as stored: no orientation tag left,
+    # so its stored width and height are the displayed ones.
+    def upright?
+      @orientation.nil?
+    end
+
+    def to_s
+      @path
+    end
+    alias_method :to_path, :to_s
+    alias_method :to_str, :to_s
+
+    # Equal to another result for the same run, or to the destination
+    # path as a String (String#== defers here for anything with to_str).
+    def ==(other)
+      case other
+      when Stripped then to_h == other.to_h
+      when String then @path == other
+      else false
+      end
+    end
+
+    def to_h
+      {path: @path, content_type: @content_type, bytes: @bytes, removed: @removed,
+       orientation: @orientation, rotated: @rotated, not_rotated: @not_rotated&.to_h}
+    end
+
+    def inspect
+      "#<#{self.class.name} #{@path} #{to_h.except(:path).compact.inspect}>"
+    end
+  end
+end

data/lib/oximg/version.rb

@@ -7,5 +7,5 @@ module Oximg
   # names a binary it does not carry. `Oximg.version` reports what the
   # resolved executable actually is, which can differ when it comes
   # from PATH.
-  VERSION = "0.19.0"
+  VERSION = "0.20.0"
 end

data/lib/oximg.rb

@@ -1,10 +1,12 @@
 # frozen_string_literal: true
 
 require "fcntl"
+require "json"
 require "tempfile"
 require_relative "oximg/version"
 require_relative "oximg/binary"
 require_relative "oximg/native"
+require_relative "oximg/stripped"
 
 # Ruby bindings for oximg (https://github.com/oximg/oximg):
 # high-performance image compression and resizing, in-process work for a
@@ -198,7 +200,12 @@ module Oximg
     # a rotated photo keeps only its EXIF orientation, so it still
     # displays upright. +icc:+ is :keep or :strip (default: the
     # binary's OXIMG_ICC, else keep); dropping a CMYK JPEG's profile is
-    # refused with a ProcessingError. Returns the destination path.
+    # refused with a ProcessingError.
+    #
+    # Returns an Oximg::Stripped: the binary's own account of the run
+    # (orientation kept, rotated?, not_rotated with a stable code). It
+    # stands in for the destination path this returned before:
+    # #to_path, #to_str and == against a String are the path.
     #
     # This is what <tt>saver(strip: true)</tt> / <tt>-strip</tt> did
     # under libvips or ImageMagick, minus the re-encode.
@@ -209,14 +216,33 @@ module Oximg
     # dimensions agree for every reader and no orientation tag is left.
     # That is only exact when the edges it moves are whole 8 or 16 px
     # blocks; otherwise, and for PNG and WebP, the orientation is kept
-    # as without it. Probe the destination to see which happened.
+    # as without it, and the result says why:
+    #
+    #   result = Oximg.strip(upload, clean, auto_rotate: true)
+    #   unless result.upright?
+    #     result.not_rotated.code  #=> :unaligned_edges, :corrupt, :over_limit, :not_jpeg
+    #   end
     #
     # +env:+ is per-call knobs, as for resize.
     def strip(source, destination, icc: nil, auto_rotate: nil, env: nil)
       output = expand(destination, "destination")
       argv = strip_argv(source, output, icc: icc, auto_rotate: auto_rotate)
-      Binary.run(*argv, env: knob_env(env))
-      output
+      child_env = knob_env(env)
+      unless Binary.legacy_strip?
+        begin
+          out, = Binary.run(*argv, "--json", env: child_env)
+          return Stripped.from_json(output, JSON.parse(out))
+        rescue ProcessingError => e
+          # An oximg older than 0.20 refuses the flag at parse time,
+          # before it reads or writes anything: remember that, and run
+          # the strip it does know.
+          raise unless e.status == 2 && e.message.include?('unknown option "--json"')
+
+          Binary.legacy_strip = true
+        end
+      end
+      _, err = Binary.run(*argv, env: child_env)
+      legacy_stripped(output, err)
     end
 
     # The child environment an +env:+ turns into: String names and
@@ -241,8 +267,9 @@ module Oximg
       end
     end
 
-    # The argv `strip` would run, minus the executable; public for the
-    # same reason as resize_argv.
+    # The argv `strip` would run, minus the executable and the --json it
+    # adds to read the outcome; public for the same reason as
+    # resize_argv.
     def strip_argv(source, destination, icc: nil, auto_rotate: nil)
       argv = ["strip", expand(source, "source"), expand(destination, "destination")]
       argv.push("--icc", token(icc, ICC_MODES, "icc")) unless icc.nil?
@@ -402,6 +429,30 @@ module Oximg
       Header.build(match[1], Integer(match[2]), Integer(match[3]), match[4] ? Integer(match[4]) : 1)
     end
 
+    # The summary every oximg since 0.18 ends a strip with, after
+    # "oximg: wrote <out> " (src/cli.rs). Those releases are frozen, so
+    # their wording is a fixed format here, though it is not a contract
+    # for later ones (they have --json). Removed block names are JPEG
+    # segment names or 4-byte chunk types, so the tail is unambiguous.
+    LEGACY_STRIP_SUMMARY = /\A\((\d+) bytes, ([^;\s]+); (.*?)(?:; kept orientation ([2-8])(?:, not rotated: (.*))?|; rotated orientation ([2-8]) upright)?\)\z/m
+
+    # The result from an oximg without --json, read from that summary
+    # rather than by probing: probe stops looking for the orientation
+    # after 1 MiB of metadata and needs a header libjpeg reads, where
+    # strip does neither. The reason a rotation was not made has no
+    # code before 0.20, so it is :unknown, with the binary's sentence.
+    def legacy_stripped(output, stderr)
+      prefix = "oximg: wrote #{output} "
+      line = stderr.lines.map(&:chomp).reverse.find { |l| l.start_with?(prefix) }
+      match = line && line.delete_prefix(prefix).match(LEGACY_STRIP_SUMMARY)
+      raise ProcessingError, "unparsable strip summary: #{stderr.strip.inspect}" unless match
+
+      kept = match[4] && Integer(match[4])
+      why = match[5] && Stripped::NotRotated.new(code: :unknown, message: match[5])
+      Stripped.new(path: output, bytes: Integer(match[1]), content_type: match[2],
+        orientation: kept, rotated: match[6] && Integer(match[6]), not_rotated: why)
+    end
+
     # Absolute paths throughout: a relative name beginning with "-"
     # would otherwise reach the CLI's argument parser as a flag, and
     # the caller rarely controls what an uploaded file is called.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: oximg
 version: !ruby/object:Gem::Version
-  version: 0.19.0
+  version: 0.20.0
 platform: x86_64-linux-gnu
 authors:
 - oximg contributors
@@ -37,6 +37,7 @@ files:
 - lib/oximg/binary.rb
 - lib/oximg/native.rb
 - lib/oximg/native/liboximg_probe.so
+- lib/oximg/stripped.rb
 - lib/oximg/version.rb
 homepage: https://github.com/oximg/oximg
 licenses: