rack_resize 0.1.3 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b93d3745135960f5c03fdec90f2104d5cf399d1bd67c248f16c8dd3061429c15
-  data.tar.gz: c228aa468fce0696ec89889b616b326a28d92e0e411937167f94578de242e802
+  metadata.gz: d7491afc343d0a0a7959e94542b99579cc48e4c9fbd0697a7f06a6658e3d28c0
+  data.tar.gz: d682ff508ee8ae6c75520f060b832addb33dc0db8e0a4be0966e962ea97a996c
 SHA512:
-  metadata.gz: 4dfbd29c0d898694cb4f239a03a812d937dce5fd76b829faaea9587b12acb5c6406f926ec310bc9c26a2b8fc123e7bb3c2a5fa788132a21f3d84253a6165f0e4
-  data.tar.gz: fa392a88e4dd71fc7b4d9f07e200adc67dea702c944d914f4c6808d871a5c785b73509f967dbe76eed0b00f3ca4d4a5c20f86591d9ec381bcbe17482317225c7
+  metadata.gz: c2265999fb7762371c4c075748709d89e6f303646f0e0a919ae4af225714e1b2af47f6015b66d4df88b8e5b74881f64d253a100097f1e05c9e22f79a8679ce4e
+  data.tar.gz: 4e5b7c9100e44e3477654b4cc004e2fc1f29f3ae687a3c6dd176e44f05ee81393ed4eee24349b98f6b8e9c83852ca8168e10b214efd4cd1fa1d513508fcf3f04

data/.github/workflows/test.yml

@@ -19,7 +19,7 @@ jobs:
       - name: Install package
         run: |
           sudo apt-get update
-          sudo apt-get install -y libvips42 libvips-tools imagemagick libimlib2 libimlib2-dev
+          sudo apt-get install -y libvips42 libvips-tools imagemagick libimlib2 libimlib2-dev libheif-plugin-aomenc libavif-dev
 
       - uses: ruby/setup-ruby@v1
         with:

data/.ruby-version

@@ -1 +1 @@
-4.0.5
+4.0.6

data/Gemfile

@@ -12,3 +12,6 @@ gem 'railties'
 gem 'minitest'
 gem 'minitest-reporters'
 gem 'rake'
+
+gem 'benchmark-ips'
+gem 'webrick'

data/README.md

@@ -13,7 +13,7 @@ end
 How to use with Rack
 
 ```ruby
-use RackResize::RackApp, processor: :imlib2, assets_folder: "samples"
+use RackResize::RackApp, processor: :mini_magick, assets_folders: ["samples"]
 use Rack::Static, urls: [""], root: "samples", index: "index.html" # optional
 ```
 
@@ -23,17 +23,107 @@ Cloudflare format: (can be used with helpers from `carrierwave-cloudflare` gem)
 ```
 /cdn-cgi/image/width=426,format=auto/assets/pets/dog.jpg
 ```
-Fastly and bunny.net: (tbd)
+Fastly / bunny.net format (query string params):
 ```
-/assets/pets/dog.jpg?width=300
+/assets/pets/dog.jpg?width=300&height=200&fit=cover&format=webp&quality=85
+```
+Imgproxy format:
+```
+/insecure/rs:fill:400:300/q:85/f:webp/plain/local:///assets/pets/dog.jpg
+/insecure/rs:fit:200:150/plain/local:///assets/banner.jpg@webp
+```
+
+### Supported Parameters:
+
+| Parameter  | Shortcut | Imgproxy Option | Type | Description |
+|------------|----------|-----------------|------|-------------|
+| `width`    | `w`      | `w:<val>` or in `rs:<mode>:<w>:<h>` | integer | Target width in pixels. Scales proportionally if `height` is omitted. |
+| `height`   | `h`      | `h:<val>` or in `rs:<mode>:<w>:<h>` | integer | Target height in pixels. Scales proportionally if `width` is omitted. |
+| `fit`      | —        | `rs:fill` (cover), `rs:fit` (contain) | string  | Resize mode: `contain` (default), `cover`, `crop`. See below. |
+| `format`   | `f`      | `f:<fmt>` or `@<fmt>` suffix | string  | Output format: `jpeg`, `png`, `webp`, `avif`, `gif`. Use `auto` to keep original. |
+| `quality`  | `q`      | `q:<val>`       | integer (1–100) | Compression quality. Defaults to `default_quality` config value (95). |
+| `dpr`      | —        | `dpr:<val>`     | float (0.1–10) | Device pixel ratio. Multiplies `width` and `height` before processing. |
+| `bg-color` | `bg`     | `bg:<color>`    | color   | Background color for flattening transparency. Also aliased as `background`. See formats below. |
+
+**Background color formats:**
+- CSS named color: `white`, `red`, `cornflowerblue` (all 148 CSS colors supported)
+- 3-digit hex: `#a84`
+- 6-digit hex: `#aa8844`
+- 8-digit hex: `#aa884480` (last two digits = alpha 0–255)
+- Decimal RGB: `0,255,0`
+- Decimal RGBA: `0,255,0,0.5` (alpha 0.0–1.0)
+
+Supported by: `vips`, `mini_magick`. Accepted but ignored by `sips` and `imlib2`.
+
+**Fit modes:**
+- `contain` (`rs:fit`) — resizes to fit within the given box, preserving aspect ratio (default)
+- `cover` / `crop` (`rs:fill`) — resizes and center-crops to fill the exact box
+
+**Example URLs (query string format):**
+```
+# Resize to width only
+/samples/image_1.jpeg?w=400
+
+# Resize to fit within 400×300 box
+/samples/image_1.jpeg?width=400&height=300
+
+# Cover-crop to exact 400×300
+/samples/image_1.jpeg?width=400&height=300&fit=cover
+
+# Convert to WebP at 80% quality
+/samples/image_1.jpeg?w=400&f=webp&q=80
+
+# Retina (2×) resize
+/samples/image_1.jpeg?w=200&dpr=2
+
+# Flatten transparency with a background color
+/samples/image.png?w=400&f=jpeg&bg-color=white
+/samples/image.png?w=400&f=jpeg&bg=%23ff0000
+/samples/image.png?w=400&f=jpeg&background=0,255,0,0.5
+```
+
+**Example URLs (Cloudflare format):**
+```
+# Resize to width
+/cdn-cgi/image/width=400/samples/image_1.jpeg
+
+# Cover-crop with format conversion
+/cdn-cgi/image/width=400,height=300,fit=cover,format=webp/samples/image_1.jpeg
+
+# Quality + format
+/cdn-cgi/image/width=400,format=avif,quality=80/samples/image_1.jpeg
+```
+
+**Example URLs (Imgproxy format):**
+```
+# Resize to width and height with cover crop (rs:fill)
+/insecure/rs:fill:400:300/plain/local:///samples/image_1.jpeg
+
+# Resize to fit within 400×300 box (rs:fit)
+/insecure/rs:fit:400:300/plain/local:///samples/image_1.jpeg
+
+# Convert format and adjust quality
+/insecure/rs:fill:400:300/q:85/f:webp/plain/local:///samples/image_1.jpeg
+
+# Specify format via extension suffix (@webp)
+/insecure/rs:fit:200:150/plain/samples/banner.jpg@webp
+
+# Using separate width, height, and DPR
+/insecure/w:400/h:300/dpr:2/plain/samples/image_1.jpeg
+
+# Flatten transparency with background color
+/insecure/rs:fill:200:200/bg:white/plain/samples/logo.png
+
+# Rails fingerprint stripping (fingerprinted URL automatically resolves to original file)
+/insecure/w:200/plain/assets/photo-1a2b3c4d.jpg
 ```
 
 ### Configuration:
 
 ```ruby
 RackResize.configure do |config|
-  config.assets_folders     = { "assets" => Rails.root.join('app', 'assets', 'images') }
-  config.processor          = :sips / :vips / :mini_magick / :imlib2
+  config.assets_folders     = { assets: Rails.root.join('app', 'assets', 'images') }
+  config.processor          = :sips / :vips / :mini_magick / :imlib2 / :bun_image
   config.default_quality    = 95
   config.save_resized       = false
   config.cache_folder       = Rails.root.join('tmp', 'rack_resize_cache') # used if save_resized enabled
@@ -41,16 +131,44 @@ RackResize.configure do |config|
 end
 ```
 
+### Development vs. Production Architecture:
+
+`rack_resize` lets you write standard CDN / imgproxy URLs in your application code without needing external services running in development:
+
+```
+[ Local Development ]
+Browser Request  -->  Rails / Rack App  -->  RackResize Middleware  -->  Ruby Processor (:vips, :mini_magick, etc.)
+
+[ Production ]
+Browser Request  -->  Nginx / CDN Cache  -->  imgproxy (Go service)  -->  Original Image Storage (S3 / disk)
+```
+
+- **In Development**: Include `rack_resize` in your `:development` Gemfile group. It intercepts `/insecure/...`, `/cdn-cgi/image/...`, or query string parameters, processes images on the fly in Ruby, and serves them immediately.
+- **In Production**: Route image paths directly at your reverse proxy (e.g. Nginx with `proxy_cache`) to your production `imgproxy` container or CDN edge, keeping your web application servers focused on dynamic application traffic.
+
 ### Supported Processing Backends:
 
 <table>
 <tr>
-<th>libaray</th>
-<th>dependency</th>
+<th>processor</th>
 <th>config</th>
+<th>system library</th>
+<th>gems</th>
+</tr>
+<tr>
+<td>sips (macOS only)</td>
+<td><code>processor: :sips</code></td>
+<td>built-in on macOS</td>
+<td>none</td>
 </tr>
 <tr>
 <td>mini_magick</td>
+<td><code>processor: :mini_magick</code></td>
+<td>
+
+ImageMagick — `brew install imagemagick`
+
+</td>
 <td>
 
 ```ruby
@@ -59,14 +177,15 @@ gem "mini_magick"
 ```
 
 </td>
+</tr>
+<tr>
+<td>vips</td>
+<td><code>processor: :vips</code></td>
 <td>
 
-`processor: :mini_magick`
+libvips — `brew install vips`
 
 </td>
-</tr>
-<tr>
-<td>vips</td>
 <td>
 
 ```ruby
@@ -74,35 +193,77 @@ gem "image_processing"
 gem "ruby-vips"
 ```
 
-</td>
-<td>
-
-`processor: :vips`
-
 </td>
 </tr>
 <tr>
-<td>sips (MacOS only)</td>
-<td>none</td>
+<td>imlib2</td>
+<td><code>processor: :imlib2</code></td>
 <td>
 
-`processor: :sips`
+Imlib2 — `brew install imlib2`
 
 </td>
-</tr>
-<tr>
-<td>imlib2</td>
 <td>
 
 ```ruby
-gem  "rszr"
+gem "rszr"
 ```
 
 </td>
+</tr>
+<tr>
+<td>bun_image</td>
+<td><code>processor: :bun_image</code></td>
 <td>
 
-`processor: :imlib2`
+Bun ≥ 1.3.14 — `brew install oven-sh/bun/bun`
 
 </td>
+<td>none (shells out to <code>bun</code>)</td>
 </tr>
 </table>
+
+Note: <code>fit=cover</code>/<code>fit=crop</code> falls back to stretch (fill) with <code>bun_image</code> — Bun.Image has no crop yet.
+
+### Supported Image Formats:
+
+| Format | sips | mini_magick | vips | imlib2 | bun_image |
+|--------|:----:|:-----------:|:----:|:------:|:---------:|
+| JPEG   | ✅   | ✅          | ✅   | ✅     | ✅        |
+| PNG    | ✅   | ✅          | ✅   | ✅     | ✅        |
+| GIF    | ✅   | ✅          | ✅   | ✅     | ❌        |
+| WebP   | ❌   | ✅ ¹        | ✅ ¹ | ❌     | ✅        |
+| AVIF   | ✅ ² | ✅ ³        | ✅ ⁴ | ❌     | ✅ ⁷      |
+| HEIC   | ✅   | ✅ ³        | ✅ ⁴ | ❌     | ✅ ⁷      |
+| SVG    | ❌   | ✅ ⁵        | ✅ ⁶ | ❌     | ❌        |
+
+¹ Requires ImageMagick / libvips built with **libwebp** support (`brew install webp`)
+² macOS 13 (Ventura) or later
+³ Requires ImageMagick built with **libheif** support (`brew install libheif`)
+⁴ Requires libvips built with **libheif** support (`brew install libheif`)
+⁵ Requires **Inkscape** or **librsvg** (`brew install librsvg`)
+⁶ Requires libvips built with **librsvg** support (`brew install librsvg`)
+⁷ AVIF/HEIC encode is macOS/Windows only in Bun.Image
+
+### Performance Benchmarks:
+
+Measured on an Apple M1 Pro with Ruby 4.0.5. Output size: 300×200 px.
+Run with `ruby benchmark/processor_benchmark.rb`
+
+**JPEG — image_1.jpeg (51 KB)**
+
+| Processor   | i/s   | ms/i  | vs fastest |
+|-------------|------:|------:|:----------:|
+| imlib2      | 613.0 | 1.63  | —          |
+| vips        | 216.9 | 4.61  | 2.83×      |
+| mini_magick |  36.4 | 27.49 | 16.85×     |
+| sips        |  20.1 | 49.68 | 30.45×     |
+
+**PNG — sample.png (2 KB)**
+
+| Processor   | i/s   | ms/i | vs fastest |
+|-------------|------:|-----:|:----------:|
+| vips        | 431.1 | 2.32 | —          |
+| imlib2      | 221.7 | 4.51 | 1.94×      |
+| mini_magick |  36.9 | 27.12| 11.69×     |
+| sips        |  19.4 | 51.62| 22.25×     |

data/benchmark/http_benchmark.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+#
+# HTTP benchmark: starts a WEBrick server in a background thread, mounts one
+# RackResize::RackApp per available processor at a distinct path prefix, then
+# measures throughput with benchmark-ips over persistent HTTP connections.
+#
+# Usage:
+#   bundle exec ruby benchmark/http_benchmark.rb
+
+require 'bundler/setup'
+require 'rack'
+require 'webrick'
+require 'net/http'
+require 'benchmark/ips'
+require 'logger'
+require 'stringio'
+require 'timeout'
+require_relative '../lib/rack_resize'
+
+SAMPLES_DIR  = File.expand_path('../samples', __dir__)
+BENCH_PORT   = 14_569
+BENCH_IMAGE  = 'image_1.jpeg'
+BENCH_PARAMS = 'width=300&height=200'
+NULL_LOGGER  = Logger.new(IO::NULL)
+
+# ── One RackApp per available processor ──────────────────────────────────────
+
+available_apps = {}
+
+puts "Loading processors..."
+%i[sips vips mini_magick imlib2 bun_image].each do |name|
+  begin
+    app = RackResize::RackApp.new(
+      processor:      name,
+      assets_folders: { '/' => SAMPLES_DIR },
+      save_resized:   false,
+      logger:         NULL_LOGGER,
+    )
+    available_apps[name] = app
+    puts "  ✓ #{name}"
+  rescue => e
+    puts "  ✗ #{name}: #{e.message}"
+  end
+end
+
+abort "\nNo processors available." if available_apps.empty?
+
+# ── URLMap: /sips → sips_app, /vips → vips_app, etc. ────────────────────────
+
+rack_app = Rack::Builder.new do
+  available_apps.each do |name, app|
+    map("/#{name}") { run app }
+  end
+end.to_app
+
+# ── WEBrick with a minimal Rack env bridge ───────────────────────────────────
+
+webrick = WEBrick::HTTPServer.new(
+  Port:      BENCH_PORT,
+  Logger:    WEBrick::Log.new(IO::NULL),
+  AccessLog: [],
+)
+
+webrick.mount_proc('/') do |req, res|
+  env = {
+    'REQUEST_METHOD'    => req.request_method,
+    'PATH_INFO'         => req.path,
+    'QUERY_STRING'      => req.query_string.to_s,
+    'SERVER_NAME'       => 'localhost',
+    'SERVER_PORT'       => BENCH_PORT.to_s,
+    'HTTP_HOST'         => "localhost:#{BENCH_PORT}",
+    'SCRIPT_NAME'       => '',
+    'rack.version'      => Rack::VERSION,
+    'rack.input'        => StringIO.new(''),
+    'rack.errors'       => $stderr,
+    'rack.multithread'  => true,
+    'rack.multiprocess' => false,
+    'rack.run_once'     => false,
+    'rack.url_scheme'   => 'http',
+  }
+  req.header.each do |key, values|
+    env["HTTP_#{key.upcase.tr('-', '_')}"] = values.join(', ')
+  end
+
+  status, headers, body = rack_app.call(env)
+
+  res.status = status
+  headers.each { |k, v| res[k] = v }
+  body_str = +''
+  body.each { |chunk| body_str << chunk }
+  res.body = body_str
+end
+
+server_thread = Thread.new { webrick.start }
+
+Timeout.timeout(10) do
+  loop do
+    TCPSocket.new('localhost', BENCH_PORT).close
+    break
+  rescue Errno::ECONNREFUSED
+    sleep 0.05
+  end
+end
+
+puts "\nServer listening on port #{BENCH_PORT}"
+
+# ── Smoke-test each endpoint before benchmarking ─────────────────────────────
+
+puts "\nVerifying endpoints..."
+available_apps.keys.each do |name|
+  uri  = URI("http://localhost:#{BENCH_PORT}/#{name}/#{BENCH_IMAGE}?#{BENCH_PARAMS}")
+  resp = Net::HTTP.get_response(uri)
+  if resp.is_a?(Net::HTTPOK)
+    puts "  ✓ /#{name}/#{BENCH_IMAGE} → 200 (#{resp.body.bytesize} B)"
+  else
+    warn "  ✗ /#{name}/#{BENCH_IMAGE} → #{resp.code}: #{resp.body}"
+    available_apps.delete(name)
+  end
+end
+
+abort "\nNo processors passed smoke test." if available_apps.empty?
+
+# ── Persistent HTTP connections, one per processor ───────────────────────────
+
+connections = available_apps.keys.to_h do |name|
+  http = Net::HTTP.new('localhost', BENCH_PORT)
+  http.start
+  [name, http]
+end
+
+puts "\n── HTTP rack server benchmark ───────────────────────────────────────────────"
+puts "   image : #{BENCH_IMAGE}"
+puts "   params: #{BENCH_PARAMS}"
+puts
+
+Benchmark.ips do |x|
+  x.config(time: 10, warmup: 3)
+
+  connections.each do |name, http|
+    path = "/#{name}/#{BENCH_IMAGE}?#{BENCH_PARAMS}"
+    x.report(name.to_s) { http.get(path) }
+  end
+
+  x.compare!
+end
+
+# ── Cleanup ───────────────────────────────────────────────────────────────────
+
+connections.each_value(&:finish)
+webrick.shutdown
+server_thread.join

data/benchmark/processor_benchmark.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+#
+# Direct processor benchmark: instantiates each available RackResize processor
+# and calls resize() directly on images from the samples/ folder.
+#
+# Usage:
+#   bundle exec ruby benchmark/processor_benchmark.rb
+
+require 'bundler/setup'
+require 'benchmark/ips'
+require_relative '../lib/rack_resize'
+
+SAMPLES_DIR   = File.expand_path('../samples', __dir__)
+BENCH_IMAGES  = Dir[File.join(SAMPLES_DIR, '{image_1,sample}.{jpg,jpeg,png,webp,heic,avif}')].sort
+BENCH_WIDTH   = 300
+BENCH_HEIGHT  = 200
+
+abort 'No sample images found in samples/.' if BENCH_IMAGES.empty?
+
+# ── Collect available processor instances ────────────────────────────────────
+
+PROCESSOR_CLASSES = {
+  sips:        RackResize::Processors::Sips,
+  vips:        RackResize::Processors::Vips,
+  mini_magick: RackResize::Processors::MiniMagick,
+  imlib2:      RackResize::Processors::Imlib2,
+  bun_image:   RackResize::Processors::BunImage,
+}.freeze
+
+puts "Loading processors..."
+processors = {}
+
+PROCESSOR_CLASSES.each do |name, klass|
+  begin
+    instance = klass.new
+    # Verify the processor actually works before including it
+    instance.resize(
+      source_file:   BENCH_IMAGES.first,
+      target_file:   nil,
+      target_width:  BENCH_WIDTH,
+      target_height: BENCH_HEIGHT,
+    )
+    processors[name] = instance
+    puts "  ✓ #{name}"
+  rescue => e
+    puts "  ✗ #{name}: #{e.message}"
+  end
+end
+
+abort "\nNo processors available." if processors.empty?
+
+puts "\nSample images: #{BENCH_IMAGES.map { |f| File.basename(f) }.join(', ')}"
+
+# ── Benchmark each sample image independently ─────────────────────────────────
+
+BENCH_IMAGES.each do |image_path|
+  image_name = File.basename(image_path)
+  image_size = File.size(image_path)
+
+  puts "\n── Direct processor benchmark ───────────────────────────────────────────────"
+  puts "   image : #{image_name} (#{image_size / 1024} KB)"
+  puts "   output: #{BENCH_WIDTH}x#{BENCH_HEIGHT}"
+  puts
+
+  Benchmark.ips do |x|
+    x.config(time: 5, warmup: 2)
+
+    processors.each do |name, processor|
+      next if name.to_s == "imlib2" && image_name =~ /heic|webp|avif/
+      next if name.to_s == "sips" && image_name =~ /webp/
+
+      x.report(name.to_s) do
+        processor.resize(
+          source_file:   image_path,
+          target_file:   nil,
+          target_width:  BENCH_WIDTH,
+          target_height: BENCH_HEIGHT,
+        )
+      end
+    end
+
+    x.compare!
+  end
+end

data/config.ru

@@ -7,7 +7,7 @@
 require_relative "lib/rack_resize"
 require "rack/static"
 
-use RackResize::RackApp, processor: :imlib2, assets_folder: "samples"
+use RackResize::RackApp, processor: :vips, assets_folders: ["samples"]
 
 use Rack::Static, urls: [""], root: "samples", index: "index.html"