transloadit 1.2.0 → 2.0.0

checksums.yaml

@@ -1,15 +1,7 @@
 ---
-!binary "U0hBMQ==":
-  metadata.gz: !binary |-
-    ZTY2M2FlNjUwMWY0M2Q4MDFkNzZiYzdmZWExOTFhZDZlM2U3ODE5OQ==
-  data.tar.gz: !binary |-
-    ZGYzNGU5ODZhNWE4N2ZkZGU4YWJjYWViMTE0MmE3MTdlMmNhMTljNA==
+SHA1:
+  metadata.gz: d66c5ecc22a6dc2615019e622dca2f112ac7cda1
+  data.tar.gz: 608bfd88a07b6eb14a53e32d028851d86aa0a484
 SHA512:
-  metadata.gz: !binary |-
-    ZTc3OWI0ZTM5NzRkNTQzOTExODZlOTFiMzExMTM3NjAwYWRhMDllZjI5ODYx
-    NjU0OWUxOWMzYzJhZGRmYzM0MzNlMTIxZTZiNDgzNmQ5ZjE2NDFhYzM4NDNh
-    NDFmODExYmIxZTMyNDc3NmRjNmExOTAwZDJjMmY1ZjI0OWM1ZDA=
-  data.tar.gz: !binary |-
-    MTEwNWJjNjEyNGFhYWI4M2IxMWEyYzgwNzBiMzE1YWZiZjk5ZjQyNmViMmY2
-    NGM0ZDg0OTVjOTE5YzE0NDNjOTgxODk0NGUyZDU0MmVhNzk0NjE2M2I0Nzlh
-    Yjg4ZGFjNWFiMDMzNDgxMDQ5YjE3OGQ1ZmE4M2E5Yjk3YTEwYmQ=
+  metadata.gz: e7577eb0f960c787517359bfff2f7aab1d16c0e13c2245c408a4bf8cb8efcde79af19d271afdf9aa5affc37d691b00ef14fd8a8f066fead33055b119d3b235b7
+  data.tar.gz: dfafe3de4fa8ea264c266293116f2358928b6dc7170930484ae336a7159e91f66dd10c5586ce0e3d71141e9181953945490469583043b8c8a0226e0ef425d64c

data/.gitignore

@@ -2,7 +2,7 @@
 .rvmrc
 .yardoc
 .ruby-version
-
+.idea/
 Gemfile.lock
 
 coverage
@@ -10,3 +10,5 @@ doc
 pkg
 
 transloadit-*.gem
+
+.DS_Store

data/.travis.yml

@@ -1,13 +1,13 @@
 sudo: false
 language: ruby
 rvm:
-  - 1.9.2
-  - 1.9.3
-  - 2.0.0
   - 2.1.0
   - 2.2.0
   - 2.3.0
   - rbx-2
-  - jruby-19mode
   - jruby-9.0.0.0
 script: "COVERAGE=false bundle exec rake test"
+matrix:
+  allow_failures:
+  - rvm: rbx-2
+

data/CHANGELOG.md

@@ -1,3 +1,29 @@
+### 2.0.0 / 2016-12-03 ###
+
+* Drop support for EOL'd Ruby 1.9.x and Ruby 2.0, please use version 1.2.0 if you need support for older
+  Ruby versions.
+* Fix compatibility to Ruby >=2.1 and Rails 5.
+* Remove bored instance logic (thanks @ifedapoolarewaju for the PR). This shouldn't affect users at all and removes
+  the need for another HTTP request before the actual HTTP request.
+* We now have the `transloadit.bill` method to retrieve billing reports. (@ifedapoolarewaju)
+* Deprecate `assembly.submit!` method for `assembly.create!`. This shouldn't affect users as the `submit!` method remains
+  as an alias for `create!`. (@ifedapoolarewaju)
+* Add support for new `assembly` methods (Thanks @ifedapoolarewaju):
+  * list to get a list of all assemblies.
+  * get to retrieve a particular assembly. Requires assembly id to be passed as argument.
+  * replay to replay a particular assembly. Requires assembly id to be passed as argument.
+  * get_notifications to get a list of all assembly notifications.
+  * replay_notification to replay the notification of a particular assembly. Requires assembly id to be passed as argument.
+* We now have a Template api with the following methods:
+  * create to create a new template.
+  * list to get a list of all templates.
+  * get to retrieve a particular template.
+  * update to update a particular template.
+  * delete to delete a particular template.
+* Add rate limit feature to implicitly retry assembly creation when the rate limit is reached.
+* Add `assembly.reload_until_finished!` which calls `reload!` once per second until assembly is finished (@gbuesing)
+* Added example files with a [small tutorial](examples/README.md) in `examples` (@jasonaibrahim)
+
 ### 1.2.0 / 2015-12-28 ###
 
 * allow custom fields to be passed to Transloadit and received back in the response (thanks @Acconut for the pull request)

data/LICENSE

@@ -1,6 +1,6 @@
 The MIT License
 
-Copyright (c) 2015 Transloadit Ltd.
+Copyright (c) 2016 Transloadit Ltd.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

data/README.md

@@ -67,12 +67,10 @@ assembly = transloadit.assembly(
   :steps => [ resize, store ]
 )
 
-response = assembly.submit! open('lolcat.jpg')
+response = assembly.create! open('lolcat.jpg')
 
-# loop until processing is finished
-until response.finished?
-  sleep 1; response.reload! # you'll want to implement a timeout in your production app
-end
+# reloads the response once per second until all processing is finished
+response.reload_until_finished!
 
 if response.error?
  # handle error
@@ -80,8 +78,10 @@ else
  # handle other cases
 end
 ```
+*(note: the assembly method `submit!` has been deprecated and replaced with `create!`.
+The submit! method remains as an alias of `create!` for backward Compatibility)*
 
-When the `submit!` method returns, the file has been uploaded but may not yet
+When the `create!` method returns, the file has been uploaded but may not yet
 be done processing. We can use the returned object to check if processing has
 completed, or examine other attributes of the request.
 
@@ -117,6 +117,10 @@ assembly to reload its results from the API.
 ```ruby
 # reloads the response's contents from the REST API
 response.reload!
+
+# reloads once per second until all processing is finished, up to number of 
+# times specified in :tries option, othewise will raise ReloadLimitReached
+response.reload_until_finished! tries: 300 # default is 600
 ```
 
 In general, you use hash accessor syntax to query any direct attribute from
@@ -128,20 +132,26 @@ Transloadit HTTP API.
 
 ### 2. Uploading multiple files
 
-Multiple files can be given to the `submit!` method in order to upload more
+Multiple files can be given to the `create!` method in order to upload more
 than one file in the same request. You can also pass a single step for the
 `steps` parameter, without having to wrap it in an Array.
 
 ```ruby
 assembly = transloadit.assembly(steps: store)
 
-response = assembly.submit!(
+response = assembly.create!(
   open('puppies.jpg'),
   open('kittens.jpg'),
   open('ferrets.jpg')
 )
 ```
 
+You can also pass an array of files to the `create!` method. Just unpack the array using the splat `*` operator.
+```ruby
+files = [open('puppies.jpg'), open('kittens.jpg'), open('ferrets.jpg')]
+response = assembly.create! *files
+```
+
 ### 3. Parallel Assembly
 
 Transloadit allows you to perform several processing steps in parallel. You
@@ -157,7 +167,7 @@ export.use [ encode, thumbs ]
 
 transloadit.assembly(
   :steps => [ encode, thumbs, export ]
-).submit! open('ninja-cat.mpg')
+).create! open('ninja-cat.mpg')
 ```
 
 You can also tell a step to use the original uploaded file by passing the
@@ -166,15 +176,15 @@ Symbol `:original` instead of another step.
 Check the YARD documentation for more information on using
 [use](http://rubydoc.info/gems/transloadit/frames/Transloadit/Step#use-instance_method).
 
-### 4. Using a Template
+### 4. Creating an Assembly with Templates
 
-Transloadit allows you to use custom [templates](http://transloadit.com/docs/templates)
+Transloadit allows you to use custom [templates](https://github.com/transloadit/ruby-sdk/blob/master/README.md#8-templates)
 for recurring encoding tasks. In order to use these do the following:
 
 ```ruby
 transloadit.assembly(
   :template_id => 'YOUR_TEMPLATE_ID'
-).submit! open('ninja-cat.mpg')
+).create! open('ninja-cat.mpg')
 ```
 
 You can use your steps together with this template and even use variables.
@@ -190,7 +200,7 @@ to the upload itself. You can use fields like the following:
 ```ruby
 transloadit.assembly(
   :fields => {:tag => 'ninjacats'}
-).submit! open('ninja-cat.mpg')
+).create! open('ninja-cat.mpg')
 ```
 
 ### 6. Notify URL
@@ -201,24 +211,139 @@ a notify url for the assembly.
 ```ruby
 transloadit.assembly(
   :notify_url => 'http://example.com/processing_finished'
-).submit! open('ninja-cat.mpg')
+).create! open('ninja-cat.mpg')
 ```
 
 Read up more on the notifications [on Transloadit's documentation page](http://transloadit.com/docs/notifications-vs-redirect-url)
 
+### 7. Other Assembly methods
+
+Transloadit also provides methods to retrieve/replay assemblies and their notifications.
+
+```ruby
+assembly = transloadit.assembly
+
+# returns a list of all assemblies
+assembly.list
+
+# returns a specific assembly
+assembly.get 'YOUR_ASSEMBLY_ID'
+
+# replays a specific assembly
+response = assembly.replay 'YOUR_ASSEMBLY_ID'
+# should return true if assembly is replaying and false otherwise.
+response.replaying?
+
+# returns all assembly notifications
+assembly.get_notifications
+
+# replays an assembly notification
+assembly.replay_notification 'YOUR_ASSEMBLY_ID'
+```
+
+### 8. Templates
+
+Transloadit provides a [templates api](https://transloadit.com/docs/templates)
+for recurring encoding tasks. Here's how you would create a template:
+
+```ruby
+template = transloadit.template
+
+# creates a new template
+template.create(
+  :name => 'TEMPLATE_NAME',
+  :template => {
+    "steps": {
+      "encode": {
+        "use": ":original",
+        "robot": "/video/encode",
+        "result": true
+      }
+    }
+  }
+)
+```
+
+There are also some other methods to retrieve, update and delete a template.
+
+```ruby
+# returns a list of all templates.
+template.list
+
+# returns a specific template.
+template.get 'YOUR_TEMPLATE_ID'
+
+# updates the template whose id is specified.
+template.update(
+  'YOUR_TEMPLATE_ID',
+  :name => 'CHANGED_TEMPLATE_NAME',
+  :template => {
+    :steps => {
+      :encode => {
+        :use => ':original',
+        :robot => '/video/merge'
+      }
+    }
+  }
+)
+
+# deletes a specific template
+template.delete 'YOUR_TEMPLATE_ID'
+```
+
+### 9. Getting Bill reports
+
+If you want to retrieve your transloadit account billing report for a particular month and year
+you can use the `bill` method passing the required month and year like the following:
+
+```ruby
+# returns bill report for February, 2016.
+transloadit.bill(2, 2016)
+```
+Not specifying the `month` or `year` would default to the current month or year.
+
+### 10. Rate limits
+
+Transloadit enforces rate limits to guarantee that no customers are adversely affected by the usage
+of any given customer. See [Rate Limiting](https://transloadit.com/docs/api-docs/#rate-limiting).
+
+While creating an assembly, if a rate limit error is received, by default, 2 more attempts would be made for a succesful
+response. If after these attempts the rate limit error persists, a `RateLimitReached` exception will be raised.
+
+To change the number of attempts that will be made when creating an assembly, you may pass the `tries` option to your
+assembly like so.
+
+```ruby
+# would make one extra attempt after a failed attempt.
+transloadit.assembly(:tries => 2).create! open('ninja-cat.mpg')
+
+# Would make no attempt at all. Your request would not be sent.
+transloadit.assembly(:tries => 0).create! open('ninja-cat.mpg')
+```
+
 ## Documentation
 
 Up-to-date YARD documentation is automatically generated. You can view the
 docs for the [released gem](http://rubydoc.info/gems/transloadit/frames) or
 for the latest [git master](http://rubydoc.info/github/transloadit/ruby-sdk/master/frames).
 
+## Examples
+
+An small sample tutorial of using the Transloadit ruby-sdk to optimize an image, encode MP3 audio, add ID3 tags,
+and more can be found [here](examples/README.md).
+
 ## Compatibility
 
-At a minimum, this gem should work on MRI 2.3.0, 2.2.0, 2.1.0, 2.0.0, 1.9.3, 1.9.2, Rubinius,
-and JRuby in 1.9 mode. It may also work on older ruby versions, but support for those
+At a minimum, this gem should work on MRI 2.3.0, 2.2.0, 2.1.0, Rubinius,
+and JRuby. It may also work on older ruby versions, but support for those
 Rubies is not guaranteed. If it doesn't work on one of the officially supported Rubies, please file a
 [bug report](https://github.com/transloadit/ruby-sdk/issues). Compatibility patches for other Rubies
 are welcome.
 
 Testing against these versions is performed automatically by
 [Travis CI](https://travis-ci.org/transloadit/ruby-sdk).
+
+### Ruby 1.9.x & 2.0
+
+If you still need support for older versions of Ruby, 1.2.0 is the last version that
+supports those.

data/examples/README.md

@@ -0,0 +1,185 @@
+# Example Usage of the Transloadit Ruby SDK
+
+### See an example
+Navigate to an example directory (e.g. ```basic```) and then run the following, making sure to 
+substitute your own values for the environment variables below:
+```bash
+TRANSLOADIT_KEY=<your-transloadit-key> \
+TRANSLOADIT_SECRET=<your-transloadit-secret> \
+S3_BUCKET=<your-s3-bucket> \
+S3_ACCESS_KEY=<your-s3-access-key> \ 
+S3_SECRET_KEY=<your-s3-secret-key> \ 
+S3_REGION=<your-s3-region> \ 
+main.rb
+```
+
+##  Code Review
+
+### Overview
+
+In each example we utilize a simple base class `MediaTranscoder`. This class provides us
+with two methods:
+ 
+```
+transloadit_client
+get_status!
+```
+
+The first method is responsible for returning us an instance of the Transloadit SDK object,
+utilizing our credentials that we set in environment variables.
+
+The second method is responsible for returning us the status of an assembly. Note that it
+extends `Transloadit::Response::Assembly` to give us access to convenience methods like
+`finished?`.
+
+### First example
+
+In the first example that gets played, we fetch an image from the cat api, optimize it
+using the Transloadit `/image/optimize` robot, and then store it in s3.
+
+There are only two steps:
+```
+optimize = transloadit_client.step('image', '/image/optimize', {
+  progressive: true,
+  use: ':original',
+  result: true
+})
+store = transloadit_client.step('store', '/s3/store', {
+  key: ENV.fetch('S3_ACCESS_KEY'),
+  secret: ENV.fetch('S3_SECRET_KEY'),
+  bucket: ENV.fetch('S3_BUCKET'),
+  bucket_region: ENV.fetch('S3_REGION'),
+  use: 'image'
+})
+ ```
+Again, we utilize environment variables to access our s3 credentials and pass them to 
+our assembly.
+
+The job is invoked by running the following:
+```
+assembly = transloadit_client.assembly(steps: [optimize, store])
+assembly.submit! open(file)
+```
+We pass the two steps we defined above and call `open` on the file passed in. This method
+assumes the file object passed in responds to `open`.
+
+### Second example
+
+In the second example, we take a non-mp3 audio file, encode it as an mp3, add ID3 tags to it,
+and then store it in s3. There are many use cases for audio uploads, and adding ID3 tags
+provides the necessary metadata to display artist and track information in audio players
+such as iTunes.
+
+We have the following steps:
+
+```
+encode_mp3 = transloadit_client.step('mp3_encode', '/audio/encode', {
+  use: ':original',
+  preset: 'mp3',
+  ffmpeg_stack: 'v2.2.3',
+  result: true
+})
+write_metadata = transloadit_client.step('mp3', '/meta/write', {
+  use: 'mp3_encode',
+  ffmpeg_stack: 'v2.2.3',
+  result: true,
+  data_to_write: mp3_metadata
+})
+store = transloadit_client.step('store', '/s3/store', {
+  key: ENV.fetch('S3_ACCESS_KEY'),
+  secret: ENV.fetch('S3_SECRET_KEY'),
+  bucket: ENV.fetch('S3_BUCKET'),
+  bucket_region: ENV.fetch('S3_REGION'),
+  use: ['mp3']
+})
+```
+
+The first step simply uses the original file to create an mp3 version using the `audio/encode`
+robot.
+
+The second step takes the first step as input, and adds the appropriate metadata using the `meta/write`
+robot. In our simple example we set the track name to the name of the file using variable
+name substitution (see https://transloadit.com/docs/#assembly-variables), and set canned
+values for all other ID3 fields
+
+```
+def mp3_metadata
+  meta = { publisher: 'Transloadit', title: '${file.name}' }
+  meta[:album] = 'Transloadit Compilation'
+  meta[:artist] = 'Transloadit'
+  meta[:track] = '1/1'
+  meta
+end
+```
+
+Finally, we submit the assembly in the same way as the previous example:
+
+```
+assembly = transloadit_client.assembly(steps: [encode_mp3, write_metadata, store])
+assembly.submit! open(file)
+```
+
+### Third example
+
+In the third example, we take a series of mp3 files and concatenate them together.
+We upload the result to s3.
+
+This example is provided to showcase advanced usage of the `use` parameter in the `audio/concat` assembly.
+
+In our `transcode` method, note that this time we are passed an array of files.
+
+```
+concat = transloadit_client.step('concat', '/audio/concat', {
+  ffmpeg_stack: 'v2.2.3',
+  preset: 'mp3',
+  use: {
+    steps: files.map.each_with_index do |f, i|
+      { name: ':original', as: "audio_#{i}", fields: "file_#{i}" }
+    end
+  },
+  result: true
+})
+```
+
+Taking a look at the `concat` step, we see a different usage of the `use` parameter
+than we have seen in previous examples. We are effectively able to define the ordering of the
+concatenation by specifying the ```name```,  `as` and `fields` parameters.
+ 
+In this example, we have set the name for each to `:original`, specifying that the input
+at index `i` should be the input file defined at index  `i`.
+ 
+It is equally important to specify the `as` parameter. This simple parameter tells the assembly
+the ordering.
+ 
+Finally, we have the `fields` parameter. Files that get uploaded via the Ruby SDK get sent to Transloadit
+through an HTTP Rest client as a multipart/form-data request. This means that each field needs a name. The Ruby SDK
+automatically adds the name `file_<index>` to the outgoing request, where `<index>` is the number specified
+by its position in the array. 
+
+This is why it is important to define the ordering in the `steps` array, as there is no guarantee that items
+will finish uploading in the order they are sent.
+
+With that step complete, we can finalize our store step and submit the assembly.
+
+```
+store = transloadit_client.step('store', '/s3/store', {
+  key: ENV.fetch('S3_ACCESS_KEY'),
+  secret: ENV.fetch('S3_SECRET_KEY'),
+  bucket: ENV.fetch('S3_BUCKET'),
+  bucket_region: ENV.fetch('S3_REGION'),
+  use: ['concat']
+})
+assembly = transloadit_client.assembly(steps: [concat, store])
+assembly.submit! *open_files(files)
+```
+
+Note the final call to `submit` and usage of the splat (`*`) operator. The `submit!` method expects
+one or more arguments. If you would like to pass an array to this method, you must unpack the contents of the array
+or the method will treat the argument passed in as a single object, and you may have unexpected results in your 
+final results.
+
+### Conclusion
+
+With the above examples, we have seen how we can utilize the Transloadit Ruby SDK to perform simple image optimization,
+mp3 encoding and metadata writing, and audio concatenation features provided by the Transloadit service. Please visit
+https://transloadit.com/docs for the full Transloadit API documentation.