Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 188 lines (126 sloc) 6.463 kB
09ee23c @leehambley Initial commit, includes readme, but not a lot else
authored
1 # Rack::Thumb::Proxy
2
3 Resize remotely hosted images not hosted on your servers dynamically.
4 Safely proxy request
5
6 `Rack::Thumb::Proxy` is a project in the spirit of `Rack::Thumb`, but
7 for use in situations when one doesn't host the images statically on
8 one's own server, consider such an example:
9
10 <img src="http://a-site-which-doesnt-run-ssl.com/the/product/image.png" />
11
12 One could download, resize, host and be responsible for this image, but
13 in the days of realtime systems, massive data, clustered storage,
14 etcetera, why bother? One could hot-link the image, but then this
15 doesn't work for cross-protocol, with https in the mix.
16
17 <img src="/media/thumbs/http%3A%2F%2Fa-site-which-doesnt-run-ssl.com%2Fthe%2Fproduct%2Fimage.png" />
18
19 Where, in this case one has predefined `thumbs` as a category. One could
20 also do something such as:
21
22 <img src="/media/50x50/http%3A%2F%2Fa-site-which-doesnt-run-ssl.com%2Fthe%2Fproduct%2Fimage.png" />
23
24 or even
25
26 <img src="/media/50x50/http%3A%2F%2Fa-site-which-doesnt-run-ssl.com%2Fthe%2Fproduct%2Fimage.png" />
27
28 When combined with a CDN or Rack::Cache, this shouldn't cause too heavy
29 a performance penalty, and images from upstream will even be cached
30 locally.
31
32 ## Safety
33
34 To ensure that someone doesn't decide to use your server resources to resize
35 their entire collection of cat pictures, there's a hash mechanism which
36 is also available. This works very much like `Rack::Thumb`.
37
38 To use this feature, simply configure `Rack::Thumb::Proxy` with a
39 `secret`, and a `key_length` (the latter may be ommitted and defaults
40 to 10), urls will be then generated with the following appearance:
41
42 <img src="/media/15a5683b74/50x50/http%3A%2F%2Fa-site-which-doesnt-run-ssl.com%2Fthe%2Fproduct%2Fimage.png" />
43
44 The key is calculated as a result of the following pattern:
45
46 "%s\t%s\t%s" % <secret>, <options>, <url encoded image source>
47
48 For example with a terrible secret of `secret`:
49
50 echo "secret\t50x50\thttp%3A%2F%2Fa-site-which-doesnt-run-ssl.com%2Fthe%2Fproduct%2Fimage.png" | openssl dgst -sha1
51
52 The resulting SHA is as you see above. it is recommended that you choose
53 a secret using a token generation tool, if you are using Rails, you have
54 one baked-in simply use `rake secret` from your Rails project root.
55
56 Requests which do not match the expected format will receive a `400 Bad
57 Request` response.
58
59 ## (Rails) Helpers
60
61 A helper module is provided which can be used in Rails, Sinatra, or your
62 unit tests. This is loaded automatically via a Railtie into Rails,
63 available from all views. The following methods are defined:
64
65 proxied_image_url("image url", options)
66 proxied_image_tag("image url", options)
67
68 Somewhat of a private API are the following, which you may find useful:
69
70 signature_hash_for("image url", options)
71
72 The image url passed here should not be URL encoded, as
73 `Rack::Thumb::Proxy` will encode it correctly for you.
74
75 ## `options`
76
77 "50x" `[String]`Constrain to 50 pixels height, maintaining
78 original aspect ratio
79
80 "x100" `[String]`Constrain to 100 pixels width, maintaining
81 original aspect ratio
82
83 "50x75n" `[String]` Constrain to 50 pixels height, distorting the
84 image to acheive a 75 pixels width with *northern* gravity
85 (see below)
86
87 "50x75" `[String]` Crop to 50 pixels height, without distorting the
88 image to acheive a 75 pixels width
89
90 :label `[Symbol]` Take the options specified in
91 the label (see below)
92
93 {width: 123, height: } `[Hash]` The keys `width`, `height`, and
94 `gravity` are accepted
95
96 ## Option Labels
97
98 One can use the configuration API as such to name a label:
99
100 Rack::Thumb::Proxy.configure do
101 option_label :product_thumbnail, "100x100"
102 end
103
104 ## Gravity
105
106 Gravity can be specified which will pull the crop (in the case that both
107 width, and height are given), it will focus the cropped area of the
954c826 @leehambley Starting to write the configuration API
authored
108 image, valid options are `n`, `ne`, `e`, `se`, `s`, `sw`, `w`, `nw`. The
109 default gracity is `c`, which will focus the crop on the centre of the
110 image.
09ee23c @leehambley Initial commit, includes readme, but not a lot else
authored
111
112 ## No Magic
113
114 If you don't need to resize the image, specifying a magical option of
115 `noop` disables any kind of resizing, this is useful if you just need to
116 use the software a as a proxy. When operating in this mode there is no
117 dependency on imagemagick.
118
119 ## Installation
120
121 Add this line to your application's Gemfile:
122
123 gem 'rack-thumb-proxy'
124
125 And then execute:
126
127 $ bundle
128
129 Or install it yourself as:
130
131 $ gem install rack-thumb-proxy
132
133 ## Usage
134
135 The included railtie will ensure that this is available in your Rails
136 application, you can simply use something like:
137
954c826 @leehambley Starting to write the configuration API
authored
138 match '/media', :to => Rack::Thumb::Proxy
09ee23c @leehambley Initial commit, includes readme, but not a lot else
authored
139
140 If you need to configure additional options, this can be done in an
954c826 @leehambley Starting to write the configuration API
authored
141 initializer, or by passing a configuaation hash to the
09ee23c @leehambley Initial commit, includes readme, but not a lot else
authored
142 Rack::Thumb::Proxy initialzer. The former is preferred.
143
144 ## Example Configuration
145
146 Rack::Thumb::Proxy.configure do
147 prefix "/media/"
148 secret "d94bba3d2e0b4809a570158506"
149 key_length 10
150 end
151
152 When one doesn't want to use the configuration API, the more succinct
153 version would be to do something like:
154
155 # ./config/routes.rb
156 match '/media' => Rack::Thumb::Proxy { prefix: "/",
157 secret: "ABC1234", key_length: 10 }
158
159 # config.ru
160 use Rack::Thumb::Proxy { prefix: "/", secret: "ABC1234", key_length: 10 }
161
162 One complication is that when using the link generator functions, one
163 **must** use the configuration API, otherwise the default path will be
164 `/`.
165
5fc8437 @leehambley Satisfies my requirements for getting some sleep.
authored
166 ## To Do
167
168 * Implement Railtie/helpers.
169 * Ensure the hash signatures are checked.
170 * Make it possible to control the cache control header.
171 * Don't use open-uri.
172 * Check earlier in the process that upstream is an image,
173 don't rely on MiniMagick to blow up on non-image content.
1aa14eb @leehambley WIP, so far requests with no options should be proxied
authored
174 * Take the cache-control headers from upstream
5fc8437 @leehambley Satisfies my requirements for getting some sleep.
authored
175 if we can.
1aa14eb @leehambley WIP, so far requests with no options should be proxied
authored
176 * Allow a local cache for the images, perhaps somewhere
5fc8437 @leehambley Satisfies my requirements for getting some sleep.
authored
177 in `/tmp`.
178 * Actually support option labels, it just looks good in
179 the readme right now, alas.
1aa14eb @leehambley WIP, so far requests with no options should be proxied
authored
180
09ee23c @leehambley Initial commit, includes readme, but not a lot else
authored
181 ## Contributing
182
183 1. Fork it
184 2. Create your feature branch (`git checkout -b my-new-feature`)
185 3. Commit your changes (`git commit -am 'Added some feature'`)
186 4. Push to the branch (`git push origin my-new-feature`)
187 5. Create new Pull Request
Something went wrong with that request. Please try again.