Libraries¶

Even though the process of generating safe image URLs is explained in the Security page, we’ll try to provide libraries in each programming language to ease this process.

Available Libraries¶

Ruby¶

• ruby-thumbor - Ruby’s gem to interact with thumbor server.
• thumbor_rails - Ruby’s gem to make easier to generate urls in Rails projects.

Java¶

• Pollexor - Java client for the Thumbor image service which allows you to build URIs in an expressive fashion using a fluent API.

• thumbor-enterprise-edition - Java library to enable generating encrypted URLs. This library is deprecated in favor of Pollexor.

Swift¶

• Bumbo - A swifty client for Thumbor

Objective-C¶

• OCThumbor - Objective-C for the Thumbor image service which allows you to build URIs in an expressive fashion using a fluent API.

.NET¶

• DotNetThumbor - DotNet client for the Thumbor image service. Provides an expressive fluent API.

Implementing a library¶

If you want to provide a library to enable easy usage of thumbor in your favorite programming language, please send an e-mail to thumbor@googlegroups.com and we’ll add it here.

Below are all the scenarios we think are worth testing automatically so you can guarantee compatibility with thumbor. Please note that this is not meant to be a replacement for TDD or for any other testing methodology you might want to use. These are just helper scenarios that we thought would help any library developers.

Library Tests - Generating HMAC of the URLs¶

We sincerely advise you to have thumbor installed in your machine, so you can implement a method in your tests that has thumbor generate a signature for your URL so you can compare with your own signature. This way you can make sure your url formatting and signing are working properly.

Here’s how it was implemented in Ruby:

def sign_in_thumbor(key, str)
#bash command to call thumbor's decrypt method
command = "python -c 'from thumbor.crypto import Signer; signer = Signer(\"" << key << "\"); print signer.signature(\"" << str << "\")'"

#execute it in the shell using ruby's popen mechanism
result = Array.new
IO.popen(command) { |f| result.push(f.gets) }

result.join('')
end


You should be able to implement this easily in any modern programming language. It makes for very reliable tests.

Library Tests - Scenarios¶

Remember that these are in pseudo-code (BDD-like) language, and not in any programming language specifically.

Encryption Testing¶

These scenarios assume that you separate the logic of composing the url to be signed into a different “module”, that is to be tested with the URL Testing Scenarios after these scenarios.

Scenario 1 - Signing of a known url results¶

Given
A security key of 'my-security-key'
And an image URL of "my.server.com/some/path/to/image.jpg"
And a width of 300
And a height of 200
When
I ask my library for a signed url
Then
I get '/8ammJH8D-7tXy6kU3lTvoXlhu4o=/300x200/my.server.com/some/path/to/image.jpg' as url


Scenario 2 - Thumbor matching of signature with my library signature¶

Given
A security key of 'my-security-key'
And an image URL of "my.server.com/some/path/to/image.jpg"
And a width of 300
And a height of 200
When
I ask my library for an encrypted URL
Then
I get the proper url (/8ammJH8D-7tXy6kU3lTvoXlhu4o=/300x200/my.server.com/some/path/to/image.jpg)


Scenario 3 - Thumbor matching of signature with my library signature with meta¶

Given
A security key of 'my-security-key'
And an image URL of "my.server.com/some/path/to/image.jpg"
And the meta flag
When
I ask my library for an encrypted URL
Then
I get the proper url (/Ps3ORJDqxlSQ8y00T29GdNAh2CY=/meta/my.server.com/some/path/to/image.jpg)


Scenario 4 - Thumbor matching of signature with my library signature with smart¶

Given
A security key of 'my-security-key'
And an image URL of "my.server.com/some/path/to/image.jpg"
And the smart flag
When
I ask my library for an encrypted URL
Then
I get the proper url (/-2NHpejRK2CyPAm61FigfQgJBxw=/smart/my.server.com/some/path/to/image.jpg)


Scenario 5 - Thumbor matching of signature with my library signature with fit-in¶

Given
A security key of 'my-security-key'
And an image URL of "my.server.com/some/path/to/image.jpg"
And the fit-in flag
When
I ask my library for an encrypted URL
Then
I get the proper url (/uvLnA6TJlF-Cc-L8z9pEtfasO3s=/fit-in/my.server.com/some/path/to/image.jpg)


Scenario 6 - Thumbor matching of signature with my library signature with filters¶

Given
A security key of 'my-security-key'
And an image URL of "my.server.com/some/path/to/image.jpg"
And a 'quality(20)' filter
And a 'brightness(10)' filter
When
I ask my library for an encrypted URL
Then
I get the proper url (/ZZtPCw-BLYN1g42Kh8xTcRs0Qls=/filters:brightness(10):contrast(20)/my.server.com/some/path/to/image.jpg)


You should test the same kind of tests for horizontal and vertical flip, horizontal and vertical alignment and manual cropping.