imgproxy 1.2.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 138bb555a390e397e8bdc3e5f68534416bac212660f1c48aa2fc8332e5ab4828
-  data.tar.gz: 73d3c3357b1eb2959084b827e790e2aaa2145499ec69539a069d47e02e160c43
+  metadata.gz: f30666a2a3a8a1097534749a93ca6d53492982f59f43e0fa91553f19957535d8
+  data.tar.gz: c0ac3bddc82a2e515b728107ad1bc58fedac3eb8edca76532a3f23d8b8def706
 SHA512:
-  metadata.gz: 8891f46189c8b7a646d8fbed5202e7b66f51e63357b999158fc71c3fae19b5d3ae38a48c21f2acac7d937b6f53c512fe4f4654c528bb1a3e4a83ade50f065535
-  data.tar.gz: 82821cd8bd891a5dc0ed51846e490b09228ac070e2d0b1dd8af544c8046fc998f628e2cd283ee8011e7d365b2a3c087241129b3fe0d8c88d13e751b260fa9b5b
+  metadata.gz: 3c242a4e67d4e726ebae337e9264454ad223e2fbd31e8f5655cd8a47288e6ab8ee035bebbd0d99dbe17aa9de75ed3fc098cedae1acc7501ac5ea6e3dc43feea7
+  data.tar.gz: ccd34093cb91dbe50d1a59139db8c94da96fe0f6dba780ae1c1538ccb91646de982055aad509adceb6a3eb6af63f9a2f9af74450ce00aaa6bb0f00439b92acae

data/README.md

@@ -3,15 +3,15 @@
 <img align="right" width="200" height="200" title="imgproxy logo"
      src="https://cdn.rawgit.com/DarthSim/imgproxy/master/logo.svg">
 
-[![CircleCI branch](https://img.shields.io/circleci/project/github/imgproxy/imgproxy.rb/master.svg?style=for-the-badge)](https://circleci.com/gh/imgproxy/imgproxy.rb) [![Gem](https://img.shields.io/gem/v/imgproxy.svg?style=for-the-badge)](https://rubygems.org/gems/imgproxy) [![rubydoc.org](https://img.shields.io/badge/rubydoc-reference-blue.svg?style=for-the-badge)](https://www.rubydoc.info/gems/imgproxy)
+[![GH Test](https://img.shields.io/github/workflow/status/imgproxy/imgproxy.rb/Test?label=Test&logo=github&style=for-the-badge)](https://github.com/imgproxy/imgproxy.rb/actions) [![GH Lint](https://img.shields.io/github/workflow/status/imgproxy/imgproxy.rb/Lint?label=Lint&logo=github&style=for-the-badge)](https://github.com/imgproxy/imgproxy.rb/actions) [![Gem](https://img.shields.io/gem/v/imgproxy.svg?style=for-the-badge)](https://rubygems.org/gems/imgproxy) [![rubydoc.org](https://img.shields.io/badge/rubydoc-reference-blue.svg?style=for-the-badge)](https://www.rubydoc.info/gems/imgproxy)
 
 **[imgproxy](https://github.com/imgproxy/imgproxy)** is a fast and secure standalone server for resizing and converting remote images. The main principles of imgproxy are simplicity, speed, and security. It is a Go application, ready to be installed and used in any Unix environment—also ready to be containerized using Docker.
 
-imgproxy can be used to provide a fast and secure way to replace all the image resizing code of your web application (like calling ImageMagick or GraphicsMagick, or using libraries), while also being able to resize everything on the fly, fast and easy. imgproxy is also indispensable when handling lots of image resizing, especially when images come from a remote source.
+imgproxy can be used to provide a fast and secure way to _get rid of all the image resizing code_ in your web application (like calling ImageMagick or GraphicsMagick, or using libraries), while also being able to resize everything on the fly on a separate server that only you control. imgproxy is fast, easy to use, and requires zero processing power or storage from the main application. imgproxy is indispensable when handling image resizing of epic proportions, especially when original images are coming from a remote source.
 
-**imgproxy.rb** is a Ruby Gem for imgproxy that is framework-agnostic, but includes proper support for Ruby on Rails' most popular image attachment options.
+[imgproxy.rb](https://github.com/imgproxy/imgproxy.rb) is a framework-agnostic Ruby Gem for imgproxy that includes proper support for Ruby on Rails' most popular image attachment options: [Active Storage](https://edgeguides.rubyonrails.org/active_storage_overview.html) and [Shrine](https://github.com/shrinerb/shrine).
 
-imgproxy.rb provides easy configuration and URL generation as well as plug&play support for [Active Storage](https://edgeguides.rubyonrails.org/active_storage_overview.html) and [Shrine](https://github.com/shrinerb/shrine).
+**NOTE:** this readme shows documentation for 2.x version. For version 1.x see the [v1.2.0](https://github.com/imgproxy/imgproxy.rb/tree/v1.2.0) tag. See [2.0-Upgrade.md](2.0-Upgrade.md) for the upgrade guide.
 
 <a href="https://evilmartians.com/?utm_source=imgproxy.rb">
 <img src="https://evilmartians.com/badges/sponsored-by-evil-martians.svg" alt="Sponsored by Evil Martians" width="236" height="54">
@@ -33,35 +33,81 @@ gem install imgproxy
 
 ## Configuration
 
-Next, some basic configuration. We will use a Ruby on Rails application as an example; place the following code to `config/initializers/imgproxy.rb`:
+imgproxy.rb uses [anyway_config](https://github.com/palkan/anyway_config) to load configuration, so you can configure it in different ways.
+
+- With a separate config file:
+
+```yaml
+# <Rails root>/config/imgproxy.yml
+development:
+  # Full URL to where your imgproxy lives.
+  endpoint: "http://imgproxy.example.com"
+  # Hex-encoded signature key and salt
+  key: "your_key"
+  salt: "your_salt"
+production: ...
+test: ...
+```
+
+- With a `secrets.yml` entry for imgproxy:
+
+```yaml
+# secrets.yml
+production:
+  ...
+  imgproxy:
+    # Full URL to where your imgproxy lives.
+    endpoint: "http://imgproxy.example.com"
+    # Hex-encoded signature key and salt
+    key: "your_key"
+    salt: "your_salt"
+...
+```
+
+- With environment variables:
+
+```bash
+IMGPROXY_ENDPOINT="http://imgproxy.example.com"\
+IMGPROXY_KEY="your_key"\
+IMGPROXY_SALT="your_salt"\
+rails s
+```
+
+- ...or right in your application code:
 
 ```ruby
 # config/initializers/imgproxy.rb
 
 Imgproxy.configure do |config|
-  # imgproxy endpoint
-  #
   # Full URL to where your imgproxy lives.
   config.endpoint = "http://imgproxy.example.com"
-
-  # Next, you have to provide your signature key and salt.
-  # If unsure, check out https://github.com/imgproxy/imgproxy/blob/master/docs/configuration.md first.
-
-  # Hex-encoded signature key
-  config.hex_key = "your_key"
-  # Hex-encoded signature salt
-  config.hex_salt = "your_salt"
-
-  # Base64 encode all URLs
-  # config.base64_encode_urls = true
+  # Hex-encoded signature key and salt
+  config.key = "your_key"
+  config.salt = "your_salt"
 end
 ```
 
+#### Configuration options
+
+- **endpoint** (`IMGPROXY_ENDPOINT`) - Full URL to your imgproxy instance. Default: `nil`.
+- **key** (`IMGPROXY_KEY`) - Hex-encoded signature key. Default: `nil`.
+- **salt** (`IMGPROXY_SALT`) - Hex-encoded signature salt. Default: `nil`.
+- **raw_key** (`IMGPROXY_RAW_KEY`) - Raw (not hex-encoded) signature key. Default: `nil`.
+- **raw_salt** (`IMGPROXY_RAW_SALT`) - Raw (not hex-encoded) signature salt. Default: `nil`.
+- **signature_size** (`IMGPROXY_SIGNATURE_SIZE`) - Signature size. See [URL signature](https://docs.imgproxy.net/#/configuration?id=url-signature) section of imgproxy docs. Default: 32.
+- **use_short_options** (`IMGPROXY_USE_SHORT_OPTIONS`) - Use short processing options names (`rs` for `resize`, `g` for `gravity`, etc). Default: true.
+- **base64_encode_urls** (`IMGPROXY_BASE64_ENCODE_URLS`) - Encode source URLs to base64. Default: false.
+- **always_escape_plain_urls** (`IMGPROXY_ALWAYS_ESCAPE_PLAIN_URLS`) - Always escape plain source URLs even when ones don't need to be escaped. Default: false.
+- **use_s3_urls** (`IMGPROXY_USE_S3_URLS`) - Use `s3://...` source URLs for Active Storage and Shrine attachments stored in Amazon S3. Default: false.
+- **use_gcs_urls** (`IMGPROXY_USE_GCS_URLS`) - Use `gs://...` source URLs for Active Storage and Shrine attachments stored in Google Cloud Storage. Default: false.
+- **gcs_bucket** (`IMGPROXY_GCS_BUCKET`) - Google Cloud Storage bucket name. Default: `nil`.
+- **shrine_host** (`IMGPROXY_SHRINE_HOST`) - Shrine host for locally stored files.
+
 ## Usage
 
 ### Using with Active Storage
 
-imgproxy.rb comes with built-in Active Storage support. To enable it, modify your initializer at `config/initializers/imgproxy.rb`:
+imgproxy.rb comes with the Active Storage support built-in. It is enabled _automagically_ if you load `imgproxy` gem after `rails` (basically, just put `gem "imgproxy"` after `gem "rails"` in your `Gemfile`). Otherwise, modify your initializer at `config/initializers/imgproxy.rb`:
 
 ```ruby
 # config/initializers/imgproxy.rb
@@ -75,29 +121,21 @@ Now, to add imgproxy processing to your image attachments, just use the `imgprox
 user.avatar.imgproxy_url(width: 250, height: 250)
 ```
 
-will give you an URL to your user's avatar, resized to 250x250px on the fly.
-
-If you have configured both your imgproxy server and Active Storage to work with Amazon S3, you may want to use the short `s3://...` source URL scheme instead of the long one generated by Rails:
-
-```ruby
-# config/initializers/imgproxy.rb
+This method will return an URL to your user's avatar, resized to 250x250px on the fly.
 
-Imgproxy.extend_active_storage!(use_s3: true)
-```
+#### Amazon S3
 
-You can do the same if you are using Google Cloud Storage:
+If you have configured both your imgproxy server and Active Storage to work with Amazon S3, you can use `use_s3_urls` config option (or `IMGPROXY_USE_S3_URLS` env variable) to make imgproxy.rb use short `s3://...` source URLs instead of long ones generated by Rails.
 
-```ruby
-# config/initializers/imgproxy.rb
+#### Google Cloud Storage
 
-Imgproxy.extend_active_storage!(use_gcs: true, gcs_bucket: "my_bucket")
-```
+You can also enable `gs://...` URLs usage for the files stored in Google Cloud Storage with `use_gcs_urls` and `gcs_bucket` config options (or `IMGPROXY_USE_GCS_URLS` and `IMGPROXY_GCS_BUCKET` env variables).
 
-**Note** that you need to explicitly provide GCS bucket name since Active Storage "hides" the GCS config.
+**NOTE** that you need to explicitly provide GCS bucket name since Active Storage "hides" the GCS config.
 
 ### Using with Shrine
 
-You can also use imgproxy.rb's built-in [Shrine](https://github.com/shrinerb/shrine) support. To enable it, modify your initializer at `config/initializers/imgproxy.rb`:
+You can also use imgproxy.rb's built-in [Shrine](https://github.com/shrinerb/shrine) support. It is enabled automagically if you load `imgproxy` gem after `shrine` (basically, just put `gem "imgproxy"` after `gem "shrine"` in your `Gemfile`). Otherwise, modify your initializer at `config/initializers/imgproxy.rb`:
 
 ```ruby
 # config/initializers/imgproxy.rb
@@ -111,15 +149,9 @@ Now you can use `imgproxy_url` method of `Shrine::UploadedFile`:
 user.avatar.imgproxy_url(width: 250, height: 250)
 ```
 
-will give you an URL to your user's avatar, resized to 250x250px on the fly.
-
-**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 `host` option of `Imgproxy.extend_shrine!`:
-
-```ruby
-# config/initializers/imgproxy.rb
+This method will return an URL to your user's avatar, resized to 250x250px on the fly.
 
-Imgproxy.extend_shrine!(host: "http://your-host.test")
-```
+**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.
 
 Alternatively, you can launch your imgproxy server with the `IMGPROXY_BASE_URL` setting:
 
@@ -127,13 +159,11 @@ Alternatively, you can launch your imgproxy server with the `IMGPROXY_BASE_URL`
 IMGPROXY_BASE_URL="http://your-host.test" imgproxy
 ```
 
-If you have configured both your imgproxy server and Shrine to work with Amazon S3, you may want to use the short `s3://...` source URL scheme instead of the long one generated by Rails:
+#### Amazon S3
 
-```ruby
-Imgproxy.extend_shrine!(use_s3: true)
-```
+If you have configured both your imgproxy server and Shrine to work with Amazon S3, you can use `use_s3_urls` config option (or `IMGPROXY_USE_S3_URLS` env variable) to make imgproxy.rb use short `s3://...` source URLs instead of long ones generated by Shrine.
 
-### Usage in a framework-agnostic way
+### Usage imgproxy.rb in a framework-agnostic way
 
 If you use another gem for your attachment operations, you like to keep things minimal or Rails-free, or if you want to generate imgproxy URLs for pictures that did not originate from your application, you can use the `Imgproxy.url_for` method:
 
@@ -162,44 +192,165 @@ builder.url_for("http://images.example.com/images/image1.jpg")
 builder.url_for("http://images.example.com/images/image2.jpg")
 ```
 
-### Available imgproxy options
-
-* `resizing_type` — defines how imgproxy will resize the image. See [URL format guide](https://github.com/imgproxy/imgproxy/blob/master/docs/generating_the_url_advanced.md#resizing-type) for available values.
-* `width` — defines the width of the resulting image.
-* `height` — defines the height of the resulting image.
-* `dpr` — when set, imgproxy will multiply the image dimensions according to this factor for HiDPI (Retina) devices.
-* `enlarge` — when true, imgproxy will enlarge the image if it is smaller than the given size.
-* `extend` — when true, imgproxy will extend the image if the resizing result is smaller than the given size.
-* `extend_gravity`, `extend_gravity_x`, `extend_gravity_y` — define the gravity of the extend. These options accept the same values as `gravity`, `gravity_x` and `gravity_y` (see below).
-* `gravity` — defines gravity that will be used when imgproxy needs to cut some parts of the image. See [URL format guide](https://github.com/imgproxy/imgproxy/blob/master/docs/generating_the_url_advanced.md#gravity) for available values.
-* `gravity_x`, `gravity_y` — specify gravity offset by X and Y axes. When `fp` gravity is used, these are floating point numbers between 0 and 1 that define the coordinates of the center of the resulting image.
-* `crop_width`, `crop_height` — define the size of an area of the image to be processed (crop before resize).
-* `crop_gravity`, `crop_gravity_x`, `crop_gravity_y` - define the gravity of the crop. These options accept the same values as `gravity`, `gravity_x` and `gravity_y` (see above).
-* `padding` - defines padding size in css manner (you can use array here). See [URL guide](https://docs.imgproxy.net/#/generating_the_url_advanced?id=padding) for more info.
-* `trim_threshold` - when set, imgproxy removes surrounding background.
-* `trim_color`, `trim_equal_hor`, `trim_equal_ver` - additional trim options described in the [URL guide](https://docs.imgproxy.net/#/generating_the_url_advanced?id=trim).
-* `quality` — defines the quality of the resulting image, percentage.
-* `max_bytes` — when set, imgproxy automatically degrades the quality of the image until the image is under the specified amount of bytes.
-* `background` — when set, imgproxy will fill the resulting image background with the specified color. Can be a hex-color string or an array of red, green and blue values (0-255).
-* `brightness` — when set, imgproxy will adjust brightness of the resulting image. _Supported only by imgproxy pro._
-* `contrast` — when set, imgproxy will adjust contrast of the resulting image. _Supported only by imgproxy pro._
-* `saturation` — when set, imgproxy will adjust saturation of the resulting image. _Supported only by imgproxy pro._
-* `blur` — when set, imgproxy will apply the gaussian blur filter to the resulting image. Value is the size of a mask imgproxy will use.
-* `sharpen` — when set, imgproxy will apply the sharpen filter to the resulting image. Value is the size of a mask imgproxy will use.
-* `pixelate` — when set, imgproxy will apply the pixelate filter to the resulting image. Value is the size of a pixel. _Supported only by imgproxy pro._
-* `watermark_opacity` — when set, imgproxy will put a watermark on the resulting image. See [watermars guide](https://github.comimgproxym/imgproxy/blob/master/docs/watermark.md) for more info.
-* `watermark_position`, `watermark_x_offset`, `watermark_y_offset`, `watermark_scale` — additional watermark options described in the [watermars guide](https://github.com/imgproxy/imgproxy/blob/master/docs/watermark.md).
-* `watermark_url` — when set, imgproxy will use the image from the specified URL as a watermark. _Supported only by imgproxy pro._
-* `style` — when set, imgproxy will prepend `<style>` node with provided content to the `<svg>` node of source SVG image. _Supported only by imgproxy pro._
-* `preset` — array of names of presets that will be used by imgproxy. See [presets guide](https://github.com/imgproxy/imgproxy/blob/master/docs/presets.md) for more info.
-* `cachebuster` — defines cache buster that doesn't affect image processing but it's changing allows to bypass CDN, proxy server and browser cache.
-* `format` — specifies the resulting image format (`jpg`, `png`, `webp`).
-* `base64_encode_url` — encode the URL as a base64 string.
-* `use_short_options` — per-call redefinition of `use_short_options` config.
-
-**See [imgproxy URL format guide](https://github.com/imgproxy/imgproxy/blob/master/docs/generating_the_url_advanced.md) for more info.**
-
-### URL adapters
+### Supported imgproxy processing options
+
+- [resize](https://docs.imgproxy.net/#/generating_the_url_advanced?id=resize)
+- [size](https://docs.imgproxy.net/#/generating_the_url_advanced?id=size)
+- [resizing_type](https://docs.imgproxy.net/#/generating_the_url_advanced?id=resizing-type)
+- [resizing_algorithm](https://docs.imgproxy.net/#/generating_the_url_advanced?id=resizing-algorithm) _(pro)_
+- [width](https://docs.imgproxy.net/#/generating_the_url_advanced?id=width)
+- [height](https://docs.imgproxy.net/#/generating_the_url_advanced?id=height)
+- [dpr](https://docs.imgproxy.net/#/generating_the_url_advanced?id=dpr)
+- [enlarge](https://docs.imgproxy.net/#/generating_the_url_advanced?id=enlarge)
+- [extend](https://docs.imgproxy.net/#/generating_the_url_advanced?id=extend)
+- [gravity](https://docs.imgproxy.net/#/generating_the_url_advanced?id=gravity)
+- [crop](https://docs.imgproxy.net/#/generating_the_url_advanced?id=crop)
+- [padding](https://docs.imgproxy.net/#/generating_the_url_advanced?id=padding)
+- [trim](https://docs.imgproxy.net/#/generating_the_url_advanced?id=trim)
+- [rotate](https://docs.imgproxy.net/#/generating_the_url_advanced?id=rotate)
+- [quality](https://docs.imgproxy.net/#/generating_the_url_advanced?id=quality)
+- [max_bytes](https://docs.imgproxy.net/#/generating_the_url_advanced?id=max-bytes)
+- [background](https://docs.imgproxy.net/#/generating_the_url_advanced?id=background)
+- [background_alpha](https://docs.imgproxy.net/#/generating_the_url_advanced?id=background-alpha) _(pro)_
+- [adjust](https://docs.imgproxy.net/#/generating_the_url_advanced?id=adjust) _(pro)_
+- [brightness](https://docs.imgproxy.net/#/generating_the_url_advanced?id=brightness) _(pro)_
+- [contrast](https://docs.imgproxy.net/#/generating_the_url_advanced?id=contrast) _(pro)_
+- [saturation](https://docs.imgproxy.net/#/generating_the_url_advanced?id=saturation) _(pro)_
+- [blur](https://docs.imgproxy.net/#/generating_the_url_advanced?id=blur)
+- [sharpen](https://docs.imgproxy.net/#/generating_the_url_advanced?id=sharpen)
+- [pixelate](https://docs.imgproxy.net/#/generating_the_url_advanced?id=pixelate) _(pro)_
+- [unsharpening](https://docs.imgproxy.net/#/generating_the_url_advanced?id=unsharpening) _(pro)_
+- [watermark](https://docs.imgproxy.net/#/generating_the_url_advanced?id=watermark)
+- [watermark_url](https://docs.imgproxy.net/#/generating_the_url_advanced?id=watermark-url) _(pro)_
+- [style](https://docs.imgproxy.net/#/generating_the_url_advanced?id=style) _(pro)_
+- [jpeg_options](https://docs.imgproxy.net/#/generating_the_url_advanced?id=jpeg-options) _(pro)_
+- [png_options](https://docs.imgproxy.net/#/generating_the_url_advanced?id=png-options) _(pro)_
+- [gif_options](https://docs.imgproxy.net/#/generating_the_url_advanced?id=gif-options) _(pro)_
+- [page](https://docs.imgproxy.net/#/generating_the_url_advanced?id=page) _(pro)_
+- [video_thumbnail_second](https://docs.imgproxy.net/#/generating_the_url_advanced?id=video-thumbnail-second) _(pro)_
+- [preset](https://docs.imgproxy.net/#/generating_the_url_advanced?id=preset)
+- [cachebuster](https://docs.imgproxy.net/#/generating_the_url_advanced?id=cachebuster)
+- [strip_metadata](https://docs.imgproxy.net/#/generating_the_url_advanced?id=strip-metadata)
+- [strip_color_profile](https://docs.imgproxy.net/#/generating_the_url_advanced?id=strip-color-profile)
+- [auto_rotate](https://docs.imgproxy.net/#/generating_the_url_advanced?id=auto-rotate)
+- [filename](https://docs.imgproxy.net/#/generating_the_url_advanced?id=filename)
+- [format](https://docs.imgproxy.net/#/generating_the_url_advanced?id=format)
+- [return_attachment](https://docs.imgproxy.net/#/generating_the_url_advanced?id=return-attachment)
+- [expires](https://docs.imgproxy.net/#/generating_the_url?id=expires)
+
+_See [imgproxy URL format guide](https://docs.imgproxy.net/#/generating_the_url_advanced?id=processing-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:
+
+#### Named arguments
+
+First and the most readable way is to use a `Hash` with named arguments:
+
+```ruby
+Imgproxy.url_for(
+  "http://images.example.com/images/image.jpg",
+  crop: {
+    width: 500,
+    height: 600,
+    gravity: {
+      type: :nowe,
+      x_offset: 10,
+      y_offset: 5
+    }
+  }
+)
+# => .../c:500:600:nowe:10:5/...
+```
+
+All the arguments have the same names as in [imgproxy documentation](https://docs.imgproxy.net/#/generating_the_url_advanced?id=processing-options).
+
+You can use named arguments even if the processing option is not supported by the gem. In this case the arguments won't be reordered nor formatted, so you should provide them in the same order and right the same way they should appear in the URL:
+
+```ruby
+Imgproxy.url_for(
+  "http://images.example.com/images/image.jpg",
+  unsupported: {
+    arg1: 1,
+    nested1: {
+      arg2: 2,
+      nested2: {
+        arg3: 3
+      }
+    }
+  }
+)
+# => .../unsupported:1:2:3/...
+```
+
+#### Unnamed arguments
+
+The arguments of the complex options can be provided as an array of formatted values or even as a colon-separated string:
+
+```ruby
+Imgproxy.url_for(
+  "http://images.example.com/images/image.jpg",
+  crop: [500, 600, :nowe, 10, 5],
+  trim: "10:aabbcc:1:1"
+)
+# => .../c:500:600:nowe:10:5/t:10:aabbcc:1:1/...
+```
+
+#### Single required argument
+
+If a complex option has a single required argument, and you don't want to use the optional ones, you can just use its value:
+
+```ruby
+Imgproxy.url_for(
+  "http://images.example.com/images/image.jpg",
+  gravity: :nowe,
+  trim: 10
+)
+# => .../g:nowe/t:10/...
+```
+
+### Base64 processing options arguments
+
+Some of the processing options like `watermark_url` or `style` require their arguments to be base64-encoded. Good news is that imgproxy gem will encode them for you:
+
+```ruby
+Imgproxy.url_for(
+  "http://images.example.com/images/image.jpg",
+  watermark_url: "http://example.com/watermark.jpg",
+  style: "color: rgba(255, 255, 255, .5)"
+)
+# => .../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.
+
+## 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/#/getting_the_image_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.
 
@@ -226,35 +377,9 @@ Imgproxy.configure do |config|
 end
 ```
 
-**Note:** `Imgproxy` will use the first applicable URL adapter. If you need to add your adapter to the beginning of the list, use the `prepend` method instead of `add`.
-
-**Note:** imgproxy.rb provides built-inadapters for Active Storage and Shrine that are automatically added by `Imgproxy.extend_active_storage!` and `Imgproxy.extend_shrine!`.
-
-## Further configuration
-
-### Using truncated signature
-
-By default, the imgproxy server uses a full-length signature (32 bytes), but you can set signature length with `IMGPROXY_SIGNATURE_SIZE` environment variable. If you have configured your imgproxy server to use truncated signatures, you need to configure the gem too:
-
-```ruby
-# config/initializers/imgproxy.rb
-
-Imgproxy.configure do |config|
-  config.signature_size = 5
-end
-```
-
-### Using full processing options names
-
-By default, imgproxy gem uses short processing options names (`rs` for `resize`, `g` for `gravity`, etc), but it can be configured to use full names:
+**NOTE:** `Imgproxy` will use the first applicable URL adapter. If you need to add your adapter to the beginning of the list, use the `prepend` method instead of `add`.
 
-```ruby
-# config/initializers/imgproxy.rb
-
-Imgproxy.configure do |config|
-  config.use_short_options = false
-end
-```
+**NOTE:** imgproxy.rb provides built-in adapters for Active Storage and Shrine that are automatically added when Active Storage or Shrine support is enabled.
 
 ## Contributing
 

data/lib/imgproxy/builder.rb

@@ -3,6 +3,7 @@ require "base64"
 require "erb"
 
 require "imgproxy/options"
+require "imgproxy/options_aliases"
 
 module Imgproxy
   # Builds imgproxy URL
@@ -17,19 +18,15 @@ module Imgproxy
   #   builder.url_for("http://images.example.com/images/image1.jpg")
   #   builder.url_for("http://images.example.com/images/image2.jpg")
   class Builder
-    OMITTED_OPTIONS = %i[format].freeze
     # @param [Hash] options Processing options
     # @see Imgproxy.url_for
     def initialize(options = {})
       options = options.dup
 
-      @base64_encode_url = options.delete(:base64_encode_url)
-      @use_short_options = options.delete(:use_short_options)
-
-      @use_short_options = config.use_short_options if @use_short_options.nil?
-      @base64_encode_url = config.base64_encode_urls if @base64_encode_url.nil?
+      extract_builder_options(options)
 
       @options = Imgproxy::Options.new(options)
+      @format = @options.delete(:format)
     end
 
     # Genrates imgproxy URL
@@ -39,77 +36,68 @@ module Imgproxy
     #   the configured URL adapters
     # @see Imgproxy.url_for
     def url_for(image)
-      path = [*processing_options, url(image)].join("/")
+      path = [*processing_options, url(image, ext: @format)].join("/")
       signature = sign_path(path)
 
       File.join(Imgproxy.config.endpoint.to_s, signature, path)
     end
 
-    private
+    # Genrates imgproxy info URL
+    #
+    # @return [String] imgproxy info URL
+    # @param [String,URI, Object] image Source image URL or object applicable for
+    #   the configured URL adapters
+    # @see Imgproxy.info_url_for
+    def info_url_for(image)
+      path = url(image)
+      signature = sign_path(path)
 
-    OPTIONS_ALIASES = {
-      resize: :rs,
-      size: :s,
-      resizing_type: :rt,
-      width: :w,
-      height: :h,
-      enlarge: :en,
-      extend: :ex,
-      gravity: :g,
-      crop: :c,
-      padding: :pd,
-      trim: :t,
-      quality: :q,
-      max_bytes: :mb,
-      background: :bg,
-      adjust: :a,
-      brightness: :br,
-      contrast: :co,
-      saturation: :sa,
-      blur: :bl,
-      sharpen: :sh,
-      pixelate: :pix,
-      watermark: :wm,
-      watermark_url: :wmu,
-      preset: :pr,
-      cachebuster: :cb,
-    }.freeze
+      File.join(Imgproxy.config.endpoint.to_s, "info", signature, path)
+    end
+
+    private
 
     NEED_ESCAPE_RE = /[@?% ]|[^\p{Ascii}]/.freeze
 
+    def extract_builder_options(options)
+      @use_short_options = not_nil_or(options.delete(:use_short_options), config.use_short_options)
+      @base64_encode_url = not_nil_or(options.delete(:base64_encode_url), config.base64_encode_urls)
+      @escape_plain_url =
+        not_nil_or(options.delete(:escape_plain_url), config.always_escape_plain_urls)
+    end
+
     def processing_options
-      @processing_options ||=
-        @options.reject { |k, _| OMITTED_OPTIONS.include?(k) }.map do |key, value|
-          "#{option_alias(key)}:#{wrap_array(value).join(':')}"
-        end
+      @processing_options ||= @options.map do |key, value|
+        [option_alias(key), value].join(":")
+      end
     end
 
-    def plain_url_for(url)
-      escaped_url = url.match?(NEED_ESCAPE_RE) ? ERB::Util.url_encode(url) : url
+    def url(image, ext: nil)
+      url = config.url_adapters.url_of(image)
 
-      @options[:format] ? "plain/#{escaped_url}@#{@options[:format]}" : "plain/#{escaped_url}"
+      @base64_encode_url ? base64_url_for(url, ext: ext) : plain_url_for(url, ext: ext)
     end
 
-    def base64_url_for(url)
-      encoded_url = Base64.urlsafe_encode64(url).tr("=", "").scan(/.{1,16}/).join("/")
+    def plain_url_for(url, ext: nil)
+      escaped_url = need_escape_url?(url) ? ERB::Util.url_encode(url) : url
 
-      @options[:format] ? "#{encoded_url}.#{@options[:format]}" : encoded_url
+      ext ? "plain/#{escaped_url}@#{ext}" : "plain/#{escaped_url}"
     end
 
-    def option_alias(name)
-      return name unless config.use_short_options
+    def base64_url_for(url, ext: nil)
+      encoded_url = Base64.urlsafe_encode64(url).tr("=", "").scan(/.{1,16}/).join("/")
 
-      OPTIONS_ALIASES.fetch(name, name)
+      ext ? "#{encoded_url}.#{ext}" : encoded_url
     end
 
-    def wrap_array(value)
-      value.is_a?(Array) ? value : [value]
+    def need_escape_url?(url)
+      @escape_plain_url || url.match?(NEED_ESCAPE_RE)
     end
 
-    def url(image)
-      url = config.url_adapters.url_of(image)
+    def option_alias(name)
+      return name unless @use_short_options
 
-      @base64_encode_url ? base64_url_for(url) : plain_url_for(url)
+      Imgproxy::OPTIONS_ALIASES.fetch(name, name)
     end
 
     def sign_path(path)
@@ -130,11 +118,11 @@ module Imgproxy
     end
 
     def signature_key
-      config.key
+      config.raw_key
     end
 
     def signature_salt
-      config.salt
+      config.raw_salt
     end
 
     def signature_size
@@ -144,5 +132,9 @@ module Imgproxy
     def config
       Imgproxy.config
     end
+
+    def not_nil_or(value, fallback)
+      value.nil? ? fallback : value
+    end
   end
 end