Add info options support

Author: DarthSim

README.md

@@ -75,9 +75,9 @@ production:
 - With environment variables:
 
 ```bash
-IMGPROXY_ENDPOINT="http://imgproxy.example.com"\
-IMGPROXY_KEY="your_key"\
-IMGPROXY_SALT="your_salt"\
+IMGPROXY_ENDPOINT="http://imgproxy.example.com" \
+IMGPROXY_KEY="your_key" \
+IMGPROXY_SALT="your_salt" \
 rails s
 ```
 
@@ -95,7 +95,7 @@ Imgproxy.configure do |config|
 end
 ```
 
-#### Configuration options
+### Configuration options
 
 - **endpoint** (`IMGPROXY_ENDPOINT`) - Full URL to your imgproxy instance. Default: `nil`.
 - **key** (`IMGPROXY_KEY`) - Hex-encoded signature key. Default: `nil`.
@@ -129,10 +129,18 @@ Imgproxy.extend_active_storage!
 Now, to add imgproxy processing to your image attachments, just use the `imgproxy_url` method:
 
 ```ruby
-user.avatar.imgproxy_url(width: 250, height: 250)
+user.avatar.imgproxy_url(width: 500, height: 400, resizing_type: :fill)
 ```
 
-This method will return an URL to your user's avatar, resized to 250x250px on the fly.
+This method will return a URL to your user's avatar, resized to fill 500x400px on the fly.
+
+If you're a happy user of [imgproxy Pro](https://imgproxy.net#pro), you may find useful it's [Getting an image info](https://docs.imgproxy.net/usage/getting_info) feature. imgproxy.rb allows you to easily generate info URLs for your images:
+
+```ruby
+user.avatar.imgproxy_info_url(detect_objects: true, palette: 128)
+```
+
+This method will return a URL to the JSON with the requested info about your user's avatar.
 
 #### Amazon S3
 
@@ -157,10 +165,18 @@ Imgproxy.extend_shrine!
 Now you can use `imgproxy_url` method of `Shrine::UploadedFile`:
 
 ```ruby
-user.avatar.imgproxy_url(width: 250, height: 250)
+user.avatar.imgproxy_url(width: 500, height: 400, resizing_type: :fill)
 ```
 
-This method will return an URL to your user's avatar, resized to 250x250px on the fly.
+This method will return a URL to your user's avatar, resized to fill 500x400px on the fly.
+
+If you're a happy user of [imgproxy Pro](https://imgproxy.net#pro), you may find useful it's [Getting an image info](https://docs.imgproxy.net/usage/getting_info) feature. imgproxy.rb allows you to easily generate info URLs for your images:
+
+```ruby
+user.avatar.imgproxy_info_url(detect_objects: true, palette: 128)
+```
+
+This method will return a URL to the JSON with the requested info about your user's avatar.
 
 **NOTE:** If you use `Shrine::Storage::FileSystem` as storage, uploaded file URLs won't include the hostname, so imgproxy server won't be able to access them. To fix this, use `shrine_host` config.
 
@@ -183,16 +199,28 @@ Imgproxy.url_for(
   "http://images.example.com/images/image.jpg",
   width: 500,
   height: 400,
-  resizing_type: :fill,
-  sharpen: 0.5
+  resizing_type: :fill
+)
+```
+
+This method will return a URL to the image, resized to fill 500x400px on the fly.
+
+If you're a happy user of [imgproxy Pro](https://imgproxy.net#pro), you may find useful it's [Getting an image info](https://docs.imgproxy.net/usage/getting_info) feature. imgproxy.rb allows you to easily generate info URLs for your images:
+
+```ruby
+Imgproxy.info_url_for(
+  "http://images.example.com/images/image.jpg",
+  detect_objects: true,
+  palette: 128
 )
-# => http://imgproxy.example.com/2tjGMpWqjO/rs:fill:500:400/sh:0.5/plain/http://images.example.com/images/image.jpg
 ```
 
+This method will return a URL to the JSON with the requested info about the image.
+
 You can reuse processing options by using `Imgproxy::Builder`:
 
 ```ruby
-builder = Imgproxy::Builder.new(
+builder = Imgproxy::UrlBuilders::Processing.new(
   width: 500,
   height: 400,
   resizing_type: :fill,
@@ -201,9 +229,27 @@ builder = Imgproxy::Builder.new(
 
 builder.url_for("http://images.example.com/images/image1.jpg")
 builder.url_for("http://images.example.com/images/image2.jpg")
+
+info_builder = Imgproxy::UrlBuilders::Info.new(
+  detect_objects: true,
+  palette: 128
+)
+
+info_builder.url_for("http://images.example.com/images/image1.jpg")
+info_builder.url_for("http://images.example.com/images/image2.jpg")
 ```
 
-### Supported imgproxy processing options
+## Supported imgproxy options
+
+### Common options
+
+- `base64_encode_url` — per-call redefinition of `base64_encode_urls` config.
+- `escape_plain_url` — per-call redefinition of `always_escape_plain_urls` config.
+- `use_short_options` — per-call redefinition of `use_short_options` config.
+- `encrypt_source_url` - _(pro)_ per-call redefinition of `always_encrypt_source_urls` config.
+- `source_url_encryption_iv` - _(pro)_ an initialization vector (IV) to be used for the source URL encryption if encryption is needed. If not specified, a random IV is used.
+
+### Processing options
 
 - [resize](https://docs.imgproxy.net/usage/processing#resize)
 - [size](https://docs.imgproxy.net/usage/processing#size)
@@ -250,11 +296,41 @@ builder.url_for("http://images.example.com/images/image2.jpg")
 - [return_attachment](https://docs.imgproxy.net/usage/processing#return-attachment)
 - [expires](https://docs.imgproxy.net/usage/processing#expires)
 
-_See [imgproxy URL format guide](https://docs.imgproxy.net/usage/processing#processing-options) for more info._
+_See [imgproxy processing options guide](https://docs.imgproxy.net/usage/processing#processing-options) for more info._
+
+### Info options (pro)
+
+- [size](https://docs.imgproxy.net/usage/getting_info#size)
+- [format](https://docs.imgproxy.net/usage/getting_info#format)
+- [dimensions](https://docs.imgproxy.net/usage/getting_info#dimensions)
+- [video_meta](https://docs.imgproxy.net/usage/getting_info#video_meta)
+- [detect_objects](https://docs.imgproxy.net/usage/getting_info#detect_objects)
+- [colorspace](https://docs.imgproxy.net/usage/getting_info#colorspace)
+- [bands](https://docs.imgproxy.net/usage/getting_info#bands)
+- [sample_format](https://docs.imgproxy.net/usage/getting_info#sample_format)
+- [pages_number](https://docs.imgproxy.net/usage/getting_info#pages_number)
+- [alpha](https://docs.imgproxy.net/usage/getting_info#alpha)
+- [crop](https://docs.imgproxy.net/usage/getting_info#crop)
+- [palette](https://docs.imgproxy.net/usage/getting_info#palette)
+- [average](https://docs.imgproxy.net/usage/getting_info#average)
+- [dominant_colors](https://docs.imgproxy.net/usage/getting_info#dominant_colors)
+- [blurhash](https://docs.imgproxy.net/usage/getting_info#blurhash)
+- [calc_hashsum](https://docs.imgproxy.net/usage/getting_info#calc_hashsum)
+- [page](https://docs.imgproxy.net/usage/getting_info#page)
+- [video_thumbnail_second](https://docs.imgproxy.net/usage/getting_info#video_thumbnail_second)
+- [video_thumbnail_keyframes](https://docs.imgproxy.net/usage/getting_info#video_thumbnail_keyframes)
+- [cachebuster](https://docs.imgproxy.net/usage/getting_info#cachebuster)
+- [expires](https://docs.imgproxy.net/usage/getting_info#expires)
+- [preset](https://docs.imgproxy.net/usage/getting_info#preset)
+- [hashsum](https://docs.imgproxy.net/usage/getting_info#hashsum)
+- [max_src_resolution](https://docs.imgproxy.net/usage/getting_info#max_src_resolution)
+- [max_src_file_size](https://docs.imgproxy.net/usage/getting_info#max_src_file_size)
+
+_See [imgproxy info options guide](https://docs.imgproxy.net/usage/getting_info#info-options) for more info._
 
 ### Complex processing options
 
-Some of the processing options like `crop` or `gravity` may have multiple arguments, and you can define these arguments multiple ways:
+Some of the processing and info options like `crop` or `gravity` may have multiple arguments, and you can define these arguments multiple ways:
 
 #### Named arguments
 
@@ -335,35 +411,6 @@ Imgproxy.url_for(
 # => .../wmu:aHR0cDovL2V4YW1wbGUuY29tL3dhdGVybWFyay5qcGc/st:Y29sb3I6IHJnYmEoMjU1LCAyNTUsIDI1NSwgLjUp/...
 ```
 
-### Special options:
-
-- `base64_encode_url` — per-call redefinition of `base64_encode_urls` config.
-- `escape_plain_url` — per-call redefinition of `always_escape_plain_urls` config.
-- `use_short_options` — per-call redefinition of `use_short_options` config.
-- `encrypt_source_url` - _(pro)_ per-call redefinition of `always_encrypt_source_urls` config.
-- `source_url_encryption_iv` - _(pro)_ an initialization vector (IV) to be used for the source URL encryption if encryption is needed. If not specified, a random IV is used.
-
-## Getting the image info
-
-If you're a happy user of imgproxy Pro, you may find useful it's [Getting the image info](https://docs.imgproxy.net/usage/getting_info) feature. imgproxy.rb allows you to easily generate info URLs for your images:
-
-```ruby
-# Framework-agnositic way
-Imgproxy.info_url_for("http://images.example.com/images/image.jpg")
-# Using Active Storage or Shrine
-user.avatar.imgproxy_info_url
-
-# You can also use base64_encode_url or escape_plain_url options
-Imgproxy.info_url_for(
-  "http://images.example.com/images/image.jpg",
-  base64_encode_url: true
-)
-Imgproxy.info_url_for(
-  "http://images.example.com/images/image.jpg",
-  escape_plain_url: true
-)
-```
-
 ## URL adapters
 
 By default, `Imgproxy.url_for` accepts only `String` and `URI` as the source URL, but you can extend that behavior by using URL adapters.

lib/imgproxy.rb

@@ -1,6 +1,7 @@
 require "imgproxy/version"
 require "imgproxy/config"
-require "imgproxy/builder"
+require "imgproxy/url_builders/processing"
+require "imgproxy/url_builders/info"
 
 require "imgproxy/extensions/active_storage"
 require "imgproxy/extensions/shrine"
@@ -59,73 +60,31 @@ def configure
     # @param [String,URI, Object] image Source image URL or object applicable for
     #   the configured URL adapters
     # @param [Hash] options Processing options
-    # @option options [Hash|Array|String] :resize
-    # @option options [Hash|Array|String] :size
-    # @option options [String] :resizing_type
-    # @option options [String] :resizing_algorithm supported only by imgproxy pro
-    # @option options [Integer] :width
-    # @option options [Integer] :height
-    # @option options [Float] :dpr
-    # @option options [Boolean] :enlarge
-    # @option options [Hash|Array|Boolean|String] :extend
-    # @option options [Hash|Array|String] :gravity
-    # @option options [Hash|Array|String] :crop
-    # @option options [Array] :padding
-    # @option options [Hash|Array|String] :trim
-    # @option options [Integer] :rotate
-    # @option options [Integer] :quality
-    # @option options [Integer] :max_bytes
-    # @option options [Array|String] :background
-    # @option options [Float] :background_alpha supported only by imgproxy pro
-    # @option options [Hash|Array|String] :adjust
-    # @option options [Integer] :brightness supported only by imgproxy pro
-    # @option options [Float] :contrast supported only by imgproxy pro
-    # @option options [Float] :saturation supported only by imgproxy pro
-    # @option options [Float] :blur
-    # @option options [Float] :sharpen
-    # @option options [Integer] :pixelate supported only by imgproxy pro
-    # @option options [String] :unsharpening supported only by imgproxy pro
-    # @option options [Hash|Array|Float|String] :watermark
-    # @option options [String] :watermark_url supported only by imgproxy pro
-    # @option options [String] :watermark_text supported only by imgproxy pro
-    # @option options [String] :style supported only by imgproxy pro
-    # @option options [Hash|Array|String] :jpeg_options supported only by imgproxy pro
-    # @option options [Hash|Array|String] :png_options supported only by imgproxy pro
-    # @option options [Hash|Array|String] :gif_options supported only by imgproxy pro
-    # @option options [Integer] :page supported only by imgproxy pro
-    # @option options [Integer] :video_thumbnail_second supported only by imgproxy pro
-    # @option options [Array] :preset
-    # @option options [String] :cachebuster
-    # @option options [Boolean] :strip_metadata
-    # @option options [Boolean] :strip_color_profile
-    # @option options [Boolean] :auto_rotate
-    # @option options [String] :filename
-    # @option options [String] :format
-    # @option options [Boolean] :return_attachment
-    # @option options [Integer] :expires
-    # @option options [Boolean] :use_short_options
-    # @option options [Boolean] :base64_encode_urls
-    # @option options [Boolean] :escape_plain_url
-    # @option options [Boolean] :encrypt_source_url
-    # @option options [Boolean] :source_url_encryption_iv
-    # @see https://docs.imgproxy.net/generating_the_url_advanced?id=processing-options
-    #   Available imgproxy URL processing options and their arguments
+    # @see https://github.com/imgproxy/imgproxy.rb#processing-options
+    #   Supported processing options
     def url_for(image, options = {})
-      Imgproxy::Builder.new(options).url_for(image)
+      Imgproxy::UrlBuilders::Processing.new(options).url_for(image)
     end
 
-    # Genrates imgproxy info URL. Supported only by imgproxy pro
+    # Genrates imgproxy info URL. Supported only by imgproxy Pro
     #
-    #   Imgproxy.info_url_for("http://images.example.com/images/image.jpg")
+    #   Imgproxy.info_url_for(
+    #     "http://images.example.com/images/image.jpg",
+    #     alpha: {
+    #       alpha: true,
+    #       check_transparency: true
+    #     },
+    #     palette: 128,
+    #   )
     #
     # @return [String] imgproxy info URL
     # @param [String,URI, Object] image Source image URL or object applicable for
     #   the configured URL adapters
-    # @param [Hash] options Processing options
-    # @option options [Boolean] :base64_encode_urls
-    # @option options [Boolean] :escape_plain_url
+    # @param [Hash] options Info options
+    # @see https://github.com/imgproxy/imgproxy.rb#info-options
+    #   Supported info options
     def info_url_for(image, options = {})
-      Imgproxy::Builder.new(options).info_url_for(image)
+      Imgproxy::UrlBuilders::Info.new(options).url_for(image)
     end
 
     # Extends +ActiveStorage::Blob+ with {Imgproxy::Extensions::ActiveStorage.imgproxy_url} method