imgproxy 0.0.3 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6d8d21bfc06b321d89874525a7177c4c9e31e1bcca9823c19b6e121e727d6fb3
-  data.tar.gz: aa451c75c7a5df5ab49e7d9b52cb8c9deeb46c858b576eb3cb6526b51c61145e
+  metadata.gz: 90e13f160840d97192d6499cc36cc2bf9c5e96d58348706339f2215333c44f17
+  data.tar.gz: 3631ee4b306561b4f7ab00d8930e80a510013fd37dba059b825e21aa115d6977
 SHA512:
-  metadata.gz: a627220618a4797014aa867e483d9e57000d37c4576a14d5691de52ed63d0d4b66bccfad51b471da6eb987578e6beaf285717ba3bf74edcbc15ec238718f4825
-  data.tar.gz: 25d2aa9d5075a57b37109c2cfade3b48e72f9d63774adf90964e7e099f4ef8ca2f0fb327da77bdaa2018358fae51e65fc55b6b6ba63f053af14c81ca493dfd1e
+  metadata.gz: b519665418fabeda9bbc356454952e4490163cfeea490fa620aae7a475df95d8c58c1fe051e567b650733d9bd388b26c3f5344c638a238a22c4bb6fd2b889018
+  data.tar.gz: 37c777751a3f6d0384cafd4f08e84b02c4f26221b61550605e95c9c6ffec05e5be5cbe2c8030a84efca6c39ab5c41c8997e3a87bb3b58b268cf0c907a5215a49

data/README.md

@@ -1,163 +1,199 @@
 # imgproxy.rb
 
-[![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/)
+<img align="right" width="200" height="200" title="imgproxy logo"
+     src="https://cdn.rawgit.com/DarthSim/imgproxy/master/logo.svg">
 
-Gem for [imgproxy](https://github.com/DarthSim/imgproxy) URLs generation.
+[![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)
 
-[imgproxy](https://github.com/DarthSim/imgproxy) is a fast and secure standalone server for resizing and converting remote images. The main principles of imgproxy are simplicity, speed, and security.
+**[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.
 
-## Installation
+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.
 
-```
-gem install imgproxy
-```
+**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 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).
+
+<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">
+</a>
+
+## Installation
 
-or add it to your `Gemfile`:
+Add this to your `Gemfile`:
 
 ```ruby
 gem "imgproxy"
 ```
 
+or install system-wide:
+
+```
+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`:
+
 ```ruby
 # config/initializers/imgproxy.rb
 
 Imgproxy.configure do |config|
   # imgproxy endpoint
+  #
+  # Full URL to where your imgproxy lives.
   config.endpoint = "http://imgproxy.example.com"
-  # hex-encoded signature key
+
+  # 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
+  # Hex-encoded signature salt
   config.hex_salt = "your_salt"
-  # signature size. Defaults to 32
-  config.signature_size = 5
-  # use short processing option names (`rs` for `resize`, `g` for `gravity`, etc).
-  # Defaults to true
-  config.use_short_options = false
 end
 ```
 
 ## Usage
 
-```ruby
-Imgproxy.url_for(
-  "http://images.example.com/images/image.jpg",
-  width: 500,
-  height: 400,
-  resizing_type: :fill,
-  sharpen: 0.5
-)
-# => http://imgproxy.example.com/2tjGMpWqjO/rs:fill:500:400/sh:0.5/plain/http://images.example.com/images/image.jpg
-```
+### Using with Active Storage
 
-You can reuse processing options by using `Imgproxy::Builder`:
+imgproxy.rb comes with built-in Active Storage support. To enable it, modify your initializer at `config/initializers/imgproxy.rb`:
 
 ```ruby
-builder = Imgproxy::Builder.new(
-  width: 500,
-  height: 400,
-  resizing_type: :fill,
-  sharpen: 0.5
-)
+# config/initializers/imgproxy.rb
 
-builder.url_for("http://images.example.com/images/image1.jpg")
-builder.url_for("http://images.example.com/images/image2.jpg")
+Imgproxy.extend_active_storage!
 ```
 
-Available options are:
-
-* `resizing_type`
-* `width`
-* `height`
-* `dpr`
-* `enlarge`
-* `extend`
-* `gravity`
-* `gravity_x`
-* `gravity_y`
-* `quality`
-* `background`
-* `blur`
-* `sharpen`
-* `watermark_opacity`
-* `watermark_position`
-* `watermark_x_offset`
-* `watermark_y_offset`
-* `watermark_scale`
-* `preset`
-* `cachebuster`
-* `format`
-* `use_short_options`
-
-_See [imgproxy URL format guide](https://github.com/DarthSim/imgproxy/blob/master/docs/generating_the_url_advanced.md) for more info_
-
-### Using with ActiveStorage
-
-If you use [ActiveStorage](https://guides.rubyonrails.org/active_storage_overview.html), you can configure imgproxy gem to work with ActiveStorage attachments:
+Now, to add imgproxy processing to your image attachments, just use the `imgproxy_url` method:
 
 ```ruby
-Imgproxy.extend_active_storage
-
-# Now you can use ActiveStorage attachment as a source URL
-Imgproxy.url_for(user.avatar, width: 250, height: 250)
-# or you can use #imgproxy_url method of an attachment
 user.avatar.imgproxy_url(width: 250, height: 250)
 ```
 
-If you configured both your imgproxy server and ActiveStorage for working with Amazon S3, you may want to use short and beautiful `s3://...` source URLs instead of long ones generated by Rails:
+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
-Imgproxy.extend_active_storage(use_s3: true)
+# config/initializers/imgproxy.rb
+
+Imgproxy.extend_active_storage!(use_s3: true)
 ```
 
-You can do the same for Google Cloud Storage:
+You can do the same if you are using Google Cloud Storage:
 
 ```ruby
-# ActiveStorage hides GCS config in private, so we have to provide GCS bucket name
-Imgproxy.extend_active_storage(use_gcs: true, gcs_bucket: "my_bucket")
+# config/initializers/imgproxy.rb
+
+Imgproxy.extend_active_storage!(use_gcs: true, gcs_bucket: "my_bucket")
 ```
 
+**Note** that you need to explicitly provide GCS bucket name since Active Storage "hides" the GCS config.
+
 ### Using with Shrine
 
-If you use [Shrine](https://shrinerb.com/), you can configure imgproxy gem to work with `Shrine::UploadedFile`:
+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`:
 
 ```ruby
-Imgproxy.extend_shrine
+# config/initializers/imgproxy.rb
 
-# Now you can use Shrine::UploadedFile as a source URL
-Imgproxy.url_for(user.avatar, width: 250, height: 250)
-# or you can use #imgproxy_url method of an Shrine::UploadedFile
+Imgproxy.extend_shrine!
+```
+
+Now you can use `imgproxy_url` method of `Shrine::UploadedFile`:
+
+```ruby
 user.avatar.imgproxy_url(width: 250, height: 250)
 ```
 
-**Note:** If you use `Shrine::Storage::FileSystem` as a storage, uploaded file URLs won't include host and imgproxy server won't have access to them. To fix this, initialize `Shrine::Storage::FileSystem` with `host` option:
+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, initialize `Shrine::Storage::FileSystem` with the `host` option:
 
 ```ruby
+# Your Shrine initializer
+
 Shrine.storages = {
   store: Shrine::Storage::FileSystem.new("public", host: "http://your-host.test")
 }
 ```
 
-Or you can launch your imgproxy server with `IMGPROXY_BASE_URL` setting:
+Alternatively, you can launch your imgproxy server with the `IMGPROXY_BASE_URL` setting:
 
 ```
 IMGPROXY_BASE_URL="http://your-host.test" imgproxy
 ```
 
-If you configured both your imgproxy server and Shrine for working with Amazon S3, you may want to use short and beautiful `s3://...` source URLs:
+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:
 
 ```ruby
-Imgproxy.extend_shrine(use_s3: true)
+Imgproxy.extend_shrine!(use_s3: true)
 ```
 
+### Usage 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:
+
+```ruby
+Imgproxy.url_for(
+  "http://images.example.com/images/image.jpg",
+  width: 500,
+  height: 400,
+  resizing_type: :fill,
+  sharpen: 0.5
+)
+# => http://imgproxy.example.com/2tjGMpWqjO/rs:fill:500:400/sh:0.5/plain/http://images.example.com/images/image.jpg
+```
+
+You can reuse processing options by using `Imgproxy::Builder`:
+
+```ruby
+builder = Imgproxy::Builder.new(
+  width: 500,
+  height: 400,
+  resizing_type: :fill,
+  sharpen: 0.5
+)
+
+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.
+* `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` — floating point numbers between 0 and 1 that define the coordinates of the center of the resulting image when `fp` gravity is used.
+* `quality` — defines the quality of the resulting image, percentage.
+* `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).
+* `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.
+* `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).
+* `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`).
+* `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
 
-By default, `Imgproxy.url_for` accepts only `String` or `URI` as source URL, but you can extend this by using URL adapters. URL adapter is a simple class that implements `applicable?` and `url` methods. See the example below:
+By default, `Imgproxy.url_for` accepts only `String` and `URI` as the source URL, but you can extend that behavior by using URL adapters.
+
+URL adapter is a simple class that implements `applicable?` and `url` methods. See the example below:
 
 ```ruby
 class MyItemAdapter
-  # `applicable?` checks if the adapter can extract source URL from the provided object
+  # `applicable?` checks if the adapter can extract
+  # source URL from the provided object
   def applicable?(item)
     item.is_a? MyItem
   end
@@ -168,18 +204,49 @@ class MyItemAdapter
   end
 end
 
+# ...
+
 Imgproxy.configure do |config|
   config.url_adapters.add MyItemAdapter.new
 end
 ```
 
-**Note:** `Imgproxy` will use the first applicable URL adapter. If you need to add your adapter to the beginning of the list, use `prepend` method instead of `add`.
+**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
 
-imgproxy gem provides adapters for ActiveStorage and Shrine that are automatically added by `Imgproxy.extend_active_storage` and `Imgproxy.extend_shrine`.
+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:
+
+```ruby
+# config/initializers/imgproxy.rb
+
+Imgproxy.configure do |config|
+  config.use_short_options = false
+end
+```
 
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/imgproxy/imgproxy.rb.
 
+If you are having any problems with image processing of imgproxy itself, be sure to visit https://github.com/imgproxy/imgproxy first and check out the docs at https://github.com/imgproxy/imgproxy/blob/master/docs/.
+
 ## License
+
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/lib/imgproxy.rb

@@ -80,7 +80,7 @@ module Imgproxy
     # @param use_s3 [Boolean] enable Amazon S3 source URLs
     # @param use_gcs [Boolean] enable Google Cloud Storage source URLs
     # @param gcs_bucket [String] Google Cloud Storage bucket name
-    def extend_active_storage(use_s3: false, use_gcs: false, gcs_bucket: nil)
+    def extend_active_storage!(use_s3: false, use_gcs: false, gcs_bucket: nil)
       ActiveSupport.on_load(:active_storage_blob) do
         ::ActiveStorage::Blob.include Imgproxy::Extensions::ActiveStorage
 
@@ -97,7 +97,7 @@ module Imgproxy
     #
     # @return [void]
     # @param use_s3 [Boolean] enable Amazon S3 source URLs
-    def extend_shrine(use_s3: false)
+    def extend_shrine!(use_s3: false)
       ::Shrine::UploadedFile.include Imgproxy::Extensions::Shrine
 
       url_adapters = Imgproxy.config.url_adapters

data/lib/imgproxy/builder.rb

@@ -85,7 +85,7 @@ module Imgproxy
     end
 
     def sign_path(path)
-      return "unsafe" if signature_key.nil? || signature_salt.nil?
+      return "unsafe" unless ready_to_sign?
 
       digest = OpenSSL::HMAC.digest(
         OpenSSL::Digest.new("sha256"),
@@ -96,6 +96,11 @@ module Imgproxy
       Base64.urlsafe_encode64(digest).tr("=", "")
     end
 
+    def ready_to_sign?
+      !(signature_key.nil? || signature_salt.nil? ||
+        signature_key.empty? || signature_salt.empty?)
+    end
+
     def signature_key
       config.key
     end

data/lib/imgproxy/config.rb

@@ -26,14 +26,14 @@ module Imgproxy
     #
     # @param value [String] hex-encoded signature key
     def hex_key=(value)
-      self.key = [value].pack("H*")
+      self.key = value.nil? ? nil : [value].pack("H*")
     end
 
     # Decodes hex-encoded salt and sets it to {#salt}
     #
     # @param value [String] hex-encoded signature salt
     def hex_salt=(value)
-      self.salt = [value].pack("H*")
+      self.salt = value.nil? ? nil : [value].pack("H*")
     end
 
     def endpoint=(value)

data/lib/imgproxy/extensions/active_storage.rb

@@ -1,7 +1,7 @@
 module Imgproxy
   module Extensions
     # Extension for ActiveStorage
-    # @see Imgproxy.extend_active_storage
+    # @see Imgproxy.extend_active_storage!
     module ActiveStorage
       # Returns imgproxy URL for an attachment
       #

data/lib/imgproxy/extensions/shrine.rb

@@ -1,7 +1,7 @@
 module Imgproxy
   module Extensions
     # Extension for Shrine::UploadedFile
-    # @see Imgproxy.extend_shrine
+    # @see Imgproxy.extend_shrine!
     module Shrine
       # Returns imgproxy URL for a Shrine::UploadedFile instance
       #

data/lib/imgproxy/version.rb

@@ -1,3 +1,3 @@
 module Imgproxy
-  VERSION = "0.0.3".freeze
+  VERSION = "1.0.1".freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: imgproxy
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 1.0.1
 platform: ruby
 authors:
 - Sergey Alexandrovich