transloadit 2.0.0 → 3.0.0

data/Rakefile

@@ -1,30 +1,25 @@
-require 'rubygems/package_task'
-require 'rake/testtask'
-
-GEMSPEC = 'transloadit.gemspec'
-
-spec = eval open(GEMSPEC).read
-Gem::PackageTask.new(spec) do |gem|
-  gem.need_tar = true
-end
+require "bundler/gem_tasks"
+require "rake/testtask"
 
 Rake::TestTask.new do |test|
-  test.libs   << 'test'
-  test.pattern = 'test/**/test_*.rb'
+  test.libs << "test"
+  test.pattern = "test/**/test_*.rb"
 end
 
 begin
-  require 'yard'
-  require 'yard/rake/yardoc_task'
+  require "yard"
+  require "yard/rake/yardoc_task"
 
   YARD::Rake::YardocTask.new :doc do |yard|
-    yard.options = %w{
-      --title  Transloadit
+    yard.options = %w[
+      --title Transloadit
       --readme README.md
       --markup rdoc
-    }
+    ]
   end
 rescue
-  desc 'You need the `yard` gem to generate documentation'
+  desc "You need the `yard` gem to generate documentation"
   task :doc
 end
+
+task default: :test

data/examples/README.md

@@ -3,6 +3,15 @@
 ### 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> \
+main.rb
+```
+
+If you wish to store results from the encoding in an s3 bucket of your own, you can set your s3 credentials as well like so:
+
 ```bash
 TRANSLOADIT_KEY=<your-transloadit-key> \
 TRANSLOADIT_SECRET=<your-transloadit-secret> \
@@ -13,66 +22,77 @@ S3_REGION=<your-s3-region> \
 main.rb
 ```
 
+Please be sure you have the `transloadit` gem installed by running `gem install transloadit` before running these examples.
+
 ##  Code Review
 
 ### Overview
 
-In each example we utilize a simple base class `MediaTranscoder`. This class provides us
-with two methods:
+In each example we utilize a simple base class `MediaTranscoder`. This class provides us a simple method:
  
 ```
 transloadit_client
-get_status!
 ```
 
-The first method is responsible for returning us an instance of the Transloadit SDK object,
+The 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.
+In the [first example](https://github.com/transloadit/ruby-sdk/blob/main/examples/basic/image-transcoder.rb)
+that gets played, we fetch an image from the cat api, optimize it using the Transloadit `/image/optimize` robot, and then optionally
+stores it in s3 if the s3 credentials are set.
 
 There are only two steps:
-```
+
+```ruby
 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'
-})
+
+steps = [optimize]
+
+begin
+  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'
+  })
+
+  steps.push(store)
+rescue KeyError => e
+  p 's3 config not set. Skipping s3 storage...'
+end
+
  ```
-Again, we utilize environment variables to access our s3 credentials and pass them to 
-our assembly.
+
+Again, we utilize environment variables to access our s3 credentials if given and pass them to 
+our assembly. If the s3 credentials are not set, this step is skipped and the transloadit temporary s3 storage is used.
 
 The job is invoked by running the following:
+
+```ruby
+assembly = transloadit_client.assembly(steps: steps)
+assembly.create! open(file)
 ```
-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
+
+We pass the 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.
+In the [second example](https://github.com/transloadit/ruby-sdk/blob/main/examples/basic/audio-transcoder.rb),
+we take a non-mp3 audio file, encode it as an mp3, add ID3 tags to it, and then optionally 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:
 
-```
+```ruby
 encode_mp3 = transloadit_client.step('mp3_encode', '/audio/encode', {
   use: ':original',
   preset: 'mp3',
@@ -85,13 +105,22 @@ write_metadata = transloadit_client.step('mp3', '/meta/write', {
   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']
-})
+
+steps = [encode_mp3, write_metadata]
+
+begin
+  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']
+  })
+
+  steps.push(store)
+rescue KeyError => e
+  p 's3 config not set. Skipping s3 storage...'
+end
 ```
 
 The first step simply uses the original file to create an mp3 version using the `audio/encode`
@@ -102,7 +131,7 @@ robot. In our simple example we set the track name to the name of the file using
 name substitution (see https://transloadit.com/docs/#assembly-variables), and set canned
 values for all other ID3 fields
 
-```
+```ruby
 def mp3_metadata
   meta = { publisher: 'Transloadit', title: '${file.name}' }
   meta[:album] = 'Transloadit Compilation'
@@ -112,23 +141,26 @@ def mp3_metadata
 end
 ```
 
+Again, we utilize environment variables to access our s3 credentials if given and pass them to 
+our assembly. If the s3 credentials are not set, this step is skipped and the transloadit temporary s3 storage is used.
+
 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)
+```ruby
+assembly = transloadit_client.assembly(steps: steps)
+assembly.create! 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.
+In the [third example](https://github.com/transloadit/ruby-sdk/blob/main/examples/basic/audio-concat-transcoder.rb),
+we take a series of mp3 files and concatenate them together. We then optionally 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.
 
-```
+```ruby
 concat = transloadit_client.step('concat', '/audio/concat', {
   ffmpeg_stack: 'v2.2.3',
   preset: 'mp3',
@@ -159,21 +191,28 @@ 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.
+With that step complete, we can finalize our store step (which is optionally added if the s3 credentials are set) and submit the assembly.
+
+```ruby
+begin
+  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']
+  })
+
+  steps.push(store)
+rescue KeyError => e
+  p 's3 config not set. Skipping s3 storage...'
+end
 
-```
-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)
+assembly = transloadit_client.assembly(steps: steps)
+assembly.create! *open_files(files)
 ```
 
-Note the final call to `submit` and usage of the splat (`*`) operator. The `submit!` method expects
+Note the final call to `create` and usage of the splat (`*`) operator. The `create!` 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.

data/examples/basic/audio-concat-transcoder.rb

@@ -1,40 +1,50 @@
 class AudioConcatTranscoder < MediaTranscoder
-  require 'transloadit'
-  require_relative 'media-transcoder'
+  require "transloadit"
+  require_relative "media-transcoder"
 
   # in this example a file is encoded as an mp3, id3 tags are added, and it is stored in s3
   def transcode!(files)
-    concat = transloadit_client.step('concat', '/audio/concat', {
-      preset: 'mp3',
+    concat = transloadit_client.step("concat", "/audio/concat", {
+      preset: "mp3",
       use: {
         steps: files.map.each_with_index do |f, i|
-          { name: ':original', as: "audio_#{i}", fields: "file_#{i}" }
+          {name: ":original", as: "audio_#{i}", fields: "file_#{i}"}
         end
       },
       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: ['concat']
-    })
-    assembly = transloadit_client.assembly(steps: [concat, store])
-    assembly.submit! *open_files(files)
+
+    steps = [concat]
+
+    begin
+      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"]
+      })
+
+      steps.push(store)
+    rescue KeyError
+      p "s3 config not set. Skipping s3 storage..."
+    end
+
+    assembly = transloadit_client.assembly(steps: steps)
+    assembly.create!(*open_files(files))
   end
 
   def open_files(files)
     files.map do |f|
-      open(f)
+      File.open(f)
     end
   end
 
   def mp3_metadata
-    meta = { publisher: 'Transloadit', title: '${file.name}' }
-    meta[:album] = 'Transloadit Compilation'
-    meta[:artist] = 'Transloadit'
-    meta[:track] = '1/1'
+    meta = {publisher: "Transloadit", title: "${file.name}"}
+    meta[:album] = "Transloadit Compilation"
+    meta[:artist] = "Transloadit"
+    meta[:track] = "1/1"
     meta
   end
 end

data/examples/basic/audio-transcoder.rb

@@ -1,37 +1,47 @@
 class AudioTranscoder < MediaTranscoder
-  require 'transloadit'
-  require_relative 'media-transcoder'
+  require "transloadit"
+  require_relative "media-transcoder"
 
   # in this example a file is encoded as an mp3, id3 tags are added, and it is stored in s3
   def transcode!(file)
-    encode_mp3 = transloadit_client.step('mp3_encode', '/audio/encode', {
-      use: ':original',
-      preset: 'mp3',
-      ffmpeg_stack: 'v2.2.3',
+    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',
+    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']
-    })
-    assembly = transloadit_client.assembly(steps: [encode_mp3, write_metadata, store])
-    assembly.submit! open(file)
+
+    steps = [encode_mp3, write_metadata]
+
+    begin
+      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"]
+      })
+
+      steps.push(store)
+    rescue KeyError
+      p "s3 config not set. Skipping s3 storage..."
+    end
+
+    assembly = transloadit_client.assembly(steps: steps)
+    assembly.create! File.open(file)
   end
 
   def mp3_metadata
-    meta = { publisher: 'Transloadit', title: '${file.name}' }
-    meta[:album] = 'Transloadit Compilation'
-    meta[:artist] = 'Transloadit'
-    meta[:track] = '1/1'
+    meta = {publisher: "Transloadit", title: "${file.name}"}
+    meta[:album] = "Transloadit Compilation"
+    meta[:artist] = "Transloadit"
+    meta[:track] = "1/1"
     meta
   end
 end

data/examples/basic/image-transcoder.rb

@@ -1,27 +1,32 @@
 class ImageTranscoder < MediaTranscoder
-  require 'transloadit'
-  require_relative 'media-transcoder'
+  require "transloadit"
+  require_relative "media-transcoder"
 
   # in this example a file is submitted, optimized, and then stored in s3
   def transcode!(file)
-    optimize = transloadit_client.step('image', '/image/optimize', {
+    optimize = transloadit_client.step("image", "/image/optimize", {
       progressive: true,
-      use: ':original',
+      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'
-    })
-    assembly = transloadit_client.assembly(steps: [optimize, store])
-    assembly.submit! open(file)
-  end
 
-  def get_status!(assembly_id)
-    req = Transloadit::Request.new('/assemblies/' + assembly_id.to_s, ENV.fetch('TRANSLOADIT_SECRET'))
-    req.get.extend!(Transloadit::Response::Assembly)
+    steps = [optimize]
+
+    begin
+      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"
+      })
+
+      steps.push(store)
+    rescue KeyError
+      p "s3 config not set. Skipping s3 storage..."
+    end
+
+    assembly = transloadit_client.assembly(steps: steps)
+    assembly.create! File.open(file)
   end
 end

data/examples/basic/main.rb

@@ -1,69 +1,63 @@
-require 'open-uri'
-require_relative 'media-transcoder'
-require_relative 'image-transcoder'
-require_relative 'audio-transcoder'
-require_relative 'audio-concat-transcoder'
+require "open-uri"
+require_relative "media-transcoder"
+require_relative "image-transcoder"
+require_relative "audio-transcoder"
+require_relative "audio-concat-transcoder"
 
-p 'starting image transcoding job...'
-p 'fetching image from the cat api...'
+p "starting image transcoding job..."
+p "fetching image from the cat api..."
 
-open('http://thecatapi.com/api/images/get') do |f|
-  p 'starting transcoding job...'
+open("http://thecatapi.com/api/images/get") do |f|
+  p "starting transcoding job..."
   image_transcoder = ImageTranscoder.new
   response = image_transcoder.transcode!(f)
 
   # if you are using rails one thing you can do would be to start an ActiveJob process that recursively
   # checks on the status of the assembly until it is finished
-  while !response.finished?
-    sleep 1
-    p 'checking job status...'
-    response = image_transcoder.get_status!(response[:assembly_id])
-  end
+  p "checking job status..."
+  response.reload_until_finished!
+
   p response[:message]
-  p response[:results]['image'][0]['url']
+  p response[:results]["image"][0]["url"]
 end
 
-p 'starting audio transcoding job...'
-p 'fetching soundbite from nasa...'
+p "starting audio transcoding job..."
+p "fetching soundbite from nasa..."
 p "\n"
 
-open('http://www.nasa.gov/640379main_Computers_are_in_Control.m4r') do |f|
-  p 'starting transcoding job...'
+open("https://www.nasa.gov/640379main_Computers_are_in_Control.m4r") do |f|
+  p "starting transcoding job..."
   audio_transcoder = AudioTranscoder.new
   response = audio_transcoder.transcode!(f)
 
   # if you are using rails one thing you can do would be to start an ActiveJob process that recursively
   # checks on the status of the assembly until it is finished
-  while !response.finished?
-    sleep 1
-    p 'checking job status...'
-    response = audio_transcoder.get_status!(response[:assembly_id])
-  end
+  p "checking job status..."
+  response.reload_until_finished!
+
   p response[:message]
-  p response[:results]['mp3'][0]['url']
+  p response[:results]["mp3"][0]["url"]
   p "\n"
 end
 
-p 'starting audio concat transcoding job...'
-p 'fetching 3 soundbites from nasa...'
+p "starting audio concat transcoding job..."
+p "fetching 3 soundbites from nasa..."
 
 files = [
-  'http://www.nasa.gov/mp3/640148main_APU%20Shutdown.mp3',
-  'http://www.nasa.gov/mp3/640164main_Go%20for%20Deploy.mp3',
-  'http://www.nasa.gov/mp3/640165main_Lookin%20At%20It.mp3'
+  "https://www.nasa.gov/mp3/640148main_APU%20Shutdown.mp3",
+  "https://www.nasa.gov/mp3/640164main_Go%20for%20Deploy.mp3",
+  "https://www.nasa.gov/mp3/640165main_Lookin%20At%20It.mp3"
 ]
 
-p 'starting transcoding job...'
+p "starting transcoding job..."
 audio_concat_transcoder = AudioConcatTranscoder.new
 response = audio_concat_transcoder.transcode!(files)
 
 # if you are using rails one thing you can do would be to start an ActiveJob process that recursively
 # checks on the status of the assembly until it is finished
-while !response.finished?
-  sleep 1
-  p 'checking job status...'
-  response = audio_concat_transcoder.get_status!(response[:assembly_id])
-end
+p "checking job status..."
+response.reload_until_finished!
+
 p response[:message]
-p response[:results]['concat'][0]['url']
+p response[:results]["concat"][0]["url"]
 p "\n"

data/examples/basic/media-transcoder.rb

@@ -1,13 +1,8 @@
 class MediaTranscoder
   def transloadit_client
     @transloadit ||= Transloadit.new({
-      key: ENV.fetch('TRANSLOADIT_KEY'),
-      secret: ENV.fetch('TRANSLOADIT_SECRET')
+      key: ENV.fetch("TRANSLOADIT_KEY"),
+      secret: ENV.fetch("TRANSLOADIT_SECRET")
     })
   end
-
-  def get_status!(assembly_id)
-    req = Transloadit::Request.new('/assemblies/' + assembly_id.to_s, ENV.fetch('TRANSLOADIT_SECRET'))
-    req.get.extend!(Transloadit::Response::Assembly)
-  end
 end

data/lib/transloadit/api_model.rb

@@ -1,4 +1,4 @@
-require 'transloadit'
+require "transloadit"
 
 #
 # Represents an API class that more Transloadit specific API classes
@@ -20,30 +20,30 @@ class Transloadit::ApiModel
   #
   def initialize(transloadit, options = {})
     self.transloadit = transloadit
-    self.options     = options
+    self.options = options
   end
 
   #
   # @return [String] a human-readable version of the API
   #
   def inspect
-    self.to_hash.inspect
+    to_hash.inspect
   end
 
   #
   # @return [Hash] a Transloadit-compatible Hash of the API's contents
   #
   def to_hash
-    self.options.merge(
-      :auth  => self.transloadit.to_hash,
-    ).delete_if {|_,v| v.nil?}
+    options.merge(
+      auth: transloadit.to_hash
+    ).delete_if { |_, v| v.nil? }
   end
 
   #
   # @return [String] JSON-encoded String containing the API's contents
   #
   def to_json
-    MultiJson.dump(self.to_hash)
+    MultiJson.dump(to_hash)
   end
 
   protected
@@ -62,12 +62,12 @@ class Transloadit::ApiModel
   #
   # @return [Transloadit::Response] the response
   #
-  def _do_request(path, params = nil, method = 'get', extra_params = nil)
-    if !params.nil?
-      params = self.to_hash.update(params)
-      params = { :params => params } if ['post', 'put', 'delete'].include? method
-      params.merge!(extra_params) if !extra_params.nil?
+  def _do_request(path, params = nil, method = "get", extra_params = nil)
+    unless params.nil?
+      params = to_hash.update(params)
+      params = {params: params} if ["post", "put", "delete"].include? method
+      params.merge!(extra_params) unless extra_params.nil?
     end
-    Transloadit::Request.new(path, self.transloadit.secret).public_send(method, params)
+    Transloadit::Request.new(path, transloadit.secret).public_send(method, params)
   end
 end