oximg 0.18.0-aarch64-linux-gnu → 0.18.1-aarch64-linux-gnu

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fb8e10a4f8d26016ab0a30feea53bd15ae14f8c40c101af4af254faa385b2431
-  data.tar.gz: 86643933723d7deb8f050df9b090baea89b70a30263eee9df848f13fa2831b5a
+  metadata.gz: d4d3cb7265d61a0d89d9851f6e0938951ca773603a02dcdc19ad5b8abf3d68de
+  data.tar.gz: 7cfa66df5ffac827bc245ddd387cc321054dabd6f97c97a13bf3e6b3e8ad50e5
 SHA512:
-  metadata.gz: ec4435ce5ef51e46423e3cac7316f44dd2976c287481d4f67feeb074eefb234c6855ab0e766d30632da625a7e2c4f1f331eef6c15bc6a60959b201df85c48db0
-  data.tar.gz: 8edf8c025ad4fd2a143a7e430d5e730a80577344b6a358d3406e20e2ed9057ee3fa8b98a8fafea0e2ec0cce6b484479405facbb6f36e6046cd449986bff743d0
+  metadata.gz: 1be6c2171b1eb682a4d495d3130eca32b7e856db393a5319aba109ada1f5d5cdd1e636ebf8072243894b58d6801849aa0cee30cb34d91adee4f0ff4593bfeb53
+  data.tar.gz: 5c2cf3b537d675e748cd62e3787a1008099ab2e16103ecdfee11d80a8e4b1535f81a5ebc3e3a7b5124410948042b230269f7ffae0dec5a75ea5f91770bfa6dbc

data/README.md

@@ -31,7 +31,8 @@ the name does not say, and `:gif` is not a `format:` you can ask for.
 
 ```ruby
 Oximg.resize(source, destination, width: 0, height: 0,
-             quality: nil, format: nil, preset: nil)
+             quality: nil, format: nil, preset: nil,
+             icc: nil, auto_rotate: nil)
 ```
 
 The source is fitted within `width` x `height` and **never enlarged**. A
@@ -50,6 +51,12 @@ Oximg.resize("photo.jpg", "smaller.jpg", quality: 70)
 | `quality` | 1–100, default 80. JPEG quality |
 | `format` | `:jpg`, `:jpeg`, `:png`, `:webp`, `:avif`. Defaults to the destination's extension, else the source's own format |
 | `preset` | `:jpegli` (default — maximum quality per byte), `:fast`, `:small` |
+| `icc` | `:keep` or `:strip` the source's colour profile. Default: `OXIMG_ICC`, else keep |
+| `auto_rotate` | `false` keeps the stored orientation, `true` applies the EXIF one. Default: `OXIMG_AUTO_ROTATE`, else true |
+
+`icc` and `auto_rotate` apply to that call only, and win over the
+environment, so a threaded job runner can treat one image differently
+without touching `ENV`.
 
 `resize` returns the destination path and raises `Oximg::ProcessingError`
 on failure, carrying the binary's own message and exit status. Paths are
@@ -59,7 +66,7 @@ cannot be read as a flag.
 ## Stripping metadata
 
 ```ruby
-Oximg.strip(source, destination, icc: nil)
+Oximg.strip(source, destination, icc: nil, env: nil)
 ```
 
 Removes EXIF (GPS, camera, timestamps), XMP, IPTC and comments from a
@@ -71,10 +78,26 @@ still displays upright. `icc: :strip` also drops the colour profile.
 The default is `:keep`, or `OXIMG_ICC`. Dropping a CMYK JPEG's profile
 raises `Oximg::ProcessingError`, as do GIF and AVIF sources.
 
+## Knobs, per process or per call
+
 Everything the server tunes through `OXIMG_*` environment variables
 applies here too, and is validated the same fail-closed way: a typo'd
 knob is a startup error, never a silent default.
 
+To set one for a single call, pass `env:` to `resize` or `strip`:
+
+```ruby
+Oximg.resize("in.jpg", "out.jpg", width: 750, env: {"OXIMG_JPEG_PROGRESSIVE" => "0"})
+```
+
+Each call spawns its own process, and `env:` reaches that process
+only: `ENV` is never touched, so concurrent calls in a threaded job
+runner each get their own settings. Names must be in `Oximg::KNOBS`
+(the pipeline knobs; server settings such as `OXIMG_KEY` are refused),
+values are Strings or Integers, and `nil` unsets a name for that call.
+An unknown name raises `ArgumentError` before anything runs; a bad
+value is refused by the binary (`ProcessingError`, status 2).
+
 ## Probing
 
 ```ruby
@@ -138,8 +161,8 @@ Oximg.in_process_probe?  #=> true on a platform gem
 
 ```ruby
 Oximg.available?  #=> true
-Oximg.executable  #=> "/…/gems/oximg-0.18.0-arm64-darwin/exe/oximg"
-Oximg.version     #=> "0.18.0"   # the binary's version, not the gem's
+Oximg.executable  #=> "/…/gems/oximg-0.18.1-arm64-darwin/exe/oximg"
+Oximg.version     #=> "0.18.1"   # 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

@@ -60,8 +60,14 @@ module Oximg
       # nothing in a filename can be interpreted as syntax. Returns
       # [stdout, stderr]; a non-zero exit raises with the binary's own
       # stderr, which already names what it refused.
-      def run(*args)
-        out, err, status = Open3.capture3(path, *args)
+      #
+      # +env+ is merged into the child's environment only (a nil value
+      # unsets that name there): one process per call means one call's
+      # knobs never reach another's, even across threads, and the
+      # parent's ENV is never touched. Validate it first; Oximg.resize
+      # and Oximg.strip do.
+      def run(*args, env: {})
+        out, err, status = Open3.capture3(env, path, *args)
         unless status.success?
           message = err.strip
           message = "oximg exited #{status.exitstatus}" if message.empty?

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.18.0"
+  VERSION = "0.18.1"
 end

data/lib/oximg.rb

@@ -45,9 +45,52 @@ module Oximg
   # mozjpeg's fast/small trade differently.
   PRESETS = %i[jpegli fast small].freeze
 
-  # What `strip` may do with an embedded colour profile.
+  # What `resize` and `strip` may do with an embedded colour profile.
   ICC_MODES = %i[keep strip].freeze
 
+  # The OXIMG_* pipeline knobs an +env:+ may set for one call. Pinned to
+  # the binary's own inventory (KNOBS in src/config.rs) by a test there,
+  # so a knob the binary gains or drops cannot drift from this list.
+  # Server-startup settings (OXIMG_KEY, OXIMG_BIND, ...) are not here:
+  # a one-shot never reads them.
+  KNOBS = %w[
+    OXIMG_TIMING
+    OXIMG_RESIZE
+    OXIMG_RESIZE_BACKEND
+    OXIMG_AUTO_ROTATE
+    OXIMG_ICC
+    OXIMG_DCT_MARGIN
+    OXIMG_LINEAR_SHRINK
+    OXIMG_JPEG_PROGRESSIVE
+    OXIMG_JPEG_SEQUENTIAL_PIXELS
+    OXIMG_JPEG_STREAMING_PIXELS
+    OXIMG_FLATTEN_BG
+    OXIMG_PNG_EFFORT
+    OXIMG_PNG_QUANTIZE
+    OXIMG_PNG_QUANTIZE_COLORS
+    OXIMG_WEBP_QUALITY
+    OXIMG_WEBP_EFFORT
+    OXIMG_WEBP_DECODE_THREADS
+    OXIMG_AVIF_QUALITY
+    OXIMG_AVIF_ALPHA_QUALITY
+    OXIMG_AVIF_SPEED
+    OXIMG_AVIF_DECODE_THREADS
+    OXIMG_MAX_SOURCE_BYTES
+    OXIMG_MAX_SRC_PIXELS
+    OXIMG_GIF_ANIMATION
+    OXIMG_MAX_ANIM_FRAMES
+    OXIMG_MAX_ANIM_WORK
+    OXIMG_ANIM_FRAME_STEP
+    OXIMG_MAX_DECODED_BYTES
+    OXIMG_LOG_DECODED_BYTES_ABOVE
+    OXIMG_UPSTREAM_CONNECT_TIMEOUT
+    OXIMG_UPSTREAM_TIMEOUT
+    OXIMG_GCS_ENDPOINT
+    OXIMG_S3_ENDPOINT
+    OXIMG_S3_PATH_STYLE
+    OXIMG_OVERLAP
+  ].freeze
+
   CONTENT_TYPE_FORMATS = {
     "image/jpeg" => :jpeg,
     "image/png" => :png,
@@ -106,10 +149,24 @@ module Oximg
     # The output format follows +format:+, else +destination+'s
     # extension, else the source's own format. Returns the destination
     # path.
-    def resize(source, destination, width: 0, height: 0, quality: nil, format: nil, preset: nil)
+    #
+    # +icc:+ (:keep or :strip) and +auto_rotate:+ (true or false)
+    # override the binary's OXIMG_ICC and OXIMG_AUTO_ROTATE for this
+    # call only; nil leaves them to the environment (default: keep the
+    # profile, apply the EXIF orientation).
+    #
+    # +env:+ sets any other pipeline knob for this call only, e.g.
+    # <tt>env: {"OXIMG_JPEG_PROGRESSIVE" => "0"}</tt>: it reaches the
+    # one child process this call spawns, never ENV, so it is safe in a
+    # threaded job runner. Names must be in KNOBS; nil unsets a name
+    # for the call. The binary validates the values, fail-closed.
+    def resize(source, destination, width: 0, height: 0, quality: nil, format: nil, preset: nil,
+      icc: nil, auto_rotate: nil, env: nil)
       output = expand(destination, "destination")
-      Binary.run(*resize_argv(source, output,
-        width: width, height: height, quality: quality, format: format, preset: preset))
+      argv = resize_argv(source, output,
+        width: width, height: height, quality: quality, format: format, preset: preset,
+        icc: icc, auto_rotate: auto_rotate)
+      Binary.run(*argv, env: knob_env(env))
       output
     end
 
@@ -123,12 +180,37 @@ module Oximg
     #
     # This is what <tt>saver(strip: true)</tt> / <tt>-strip</tt> did
     # under libvips or ImageMagick, minus the re-encode.
-    def strip(source, destination, icc: nil)
+    #
+    # +env:+ is per-call knobs, as for resize.
+    def strip(source, destination, icc: nil, env: nil)
       output = expand(destination, "destination")
-      Binary.run(*strip_argv(source, output, icc: icc))
+      argv = strip_argv(source, output, icc: icc)
+      Binary.run(*argv, env: knob_env(env))
       output
     end
 
+    # The child environment an +env:+ turns into: String names and
+    # values, each name a known knob. A typo raises here rather than
+    # being passed along and ignored, which is the same fail-closed
+    # promise the binary makes about the values. Public for the same
+    # reason as resize_argv.
+    def knob_env(env)
+      return {} if env.nil?
+      raise ArgumentError, "env must be a Hash, got #{env.inspect}" unless env.is_a?(Hash)
+
+      env.each_with_object({}) do |(name, value), out|
+        key = name.to_s
+        unless KNOBS.include?(key)
+          raise ArgumentError, "unknown knob #{name.inspect} in env (one of Oximg::KNOBS)"
+        end
+        unless value.nil? || value.is_a?(String) || value.is_a?(Integer)
+          raise ArgumentError, "#{key} must be a String, an Integer or nil, got #{value.inspect}"
+        end
+
+        out[key] = value&.to_s
+      end
+    end
+
     # The argv `strip` would run, minus the executable; public for the
     # same reason as resize_argv.
     def strip_argv(source, destination, icc: nil)
@@ -180,7 +262,8 @@ module Oximg
     # The argv `resize` would run, minus the executable. Public because
     # it is the honest way to see what a call turns into — and the way
     # to test that without a binary present.
-    def resize_argv(source, destination, width: 0, height: 0, quality: nil, format: nil, preset: nil)
+    def resize_argv(source, destination, width: 0, height: 0, quality: nil, format: nil, preset: nil,
+      icc: nil, auto_rotate: nil)
       argv = [
         "resize",
         expand(source, "source"),
@@ -191,6 +274,8 @@ module Oximg
       argv.push("-q", bounded(quality, "quality", 1, 100).to_s) unless quality.nil?
       argv.push("-f", token(format, FORMATS, "format")) unless format.nil?
       argv.push("--preset", token(preset, PRESETS, "preset")) unless preset.nil?
+      argv.push("--icc", token(icc, ICC_MODES, "icc")) unless icc.nil?
+      argv.push(boolean(auto_rotate, "auto_rotate") ? "--auto-rotate" : "--no-auto-rotate") unless auto_rotate.nil?
       argv
     end
 
@@ -319,6 +404,16 @@ module Oximg
       value
     end
 
+    # Strictly true or false: a truthy "0" or "false" read as true would
+    # rotate exactly the images the caller asked not to.
+    def boolean(value, name)
+      unless value == true || value == false
+        raise ArgumentError, "#{name} must be true or false, got #{value.inspect}"
+      end
+
+      value
+    end
+
     def token(value, allowed, name)
       token = value.to_s.downcase
       unless allowed.include?(token.to_sym)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: oximg
 version: !ruby/object:Gem::Version
-  version: 0.18.0
+  version: 0.18.1
 platform: aarch64-linux-gnu
 authors:
 - oximg contributors