shrine-transloadit 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5d366d63207d1f1f9344a18d85cb0600c1666fa9
-  data.tar.gz: c78ce1f611b524aa62d971603f5de6c4e3974eff
+  metadata.gz: 6f101f3b58938e3d62d0af2ae6dcd3d7e49d3623
+  data.tar.gz: 8314af9c2984e0ddf629bb190a499f8bc7d84280
 SHA512:
-  metadata.gz: 77b6562932f477793fec069cb1a71d8ec568b48729c0a8e3d60bd30655f737db9c479ce63723959fc556d88ba8409cbe3c35792d127c929dba5eeb7f816d2748
-  data.tar.gz: a1dd95f697d0882d92f7b362d5ae1757902d1d59fd3a9787ea56d73ede417a21b7c6c48d550e21dd27d5343d69512a78d04de8834fda697a6f670fc4eb53cc91
+  metadata.gz: 9f9ab0417eb5087a1d5c3652f8002781b45e0123053ad47b38856bd05755bb55e32585caf22985bb2b9796fcb1165d3fd00af7c36fcdc65b815a614bcc1a39e9
+  data.tar.gz: 000c35dbf448f1308e4f99f1de673ef71bb9ef6de22bd9b710314277608c10de156c5a74cc94f4bbc5164ea88af84b69dd8afd139d1906484ae95a24629d4b73

data/README.md

@@ -107,29 +107,34 @@ class MyUploader < Shrine
 end
 ```
 
-### Webhooks
+### Direct uploads
 
-Transloadit performs its processing asynchronously, and you can provide a URL
-where you want Transloadit to POST results of processing once it's finished.
+Transloadit supports direct uploads, allowing you to do additional processing
+on upload, along with a [jQuery plugin] for easy integration. Generally you
+only want to do some light processing on direct uploads, and without any
+exporting, so that you have better control over your Transloadit bandwidth.
 
-```rb
-class MyUploader < Shrine
-  def transloadit_process(io, context)
-    # ...
+When direct upload finishes, Transloadit returns information about the uploaded
+file(s). The default `:cache` storage allows you to store Transloadit's
+temporary file URL as an attachment. This means that you can use the following
+JavaScript to convert Transloadit's data hash into Shrine's format:
 
-    transloadit_assembly(files, notify_url: "http://myapp.com/webhooks/transloadit")
-  end
-end
+```js
+{
+  id: data['url'], // we save the URL
+  storage: 'cache',
+  metadata: {
+    size: data['size'],
+    filename: data['name'],
+    mime_type: data['mime'],
+    width: data['meta'] && data['meta']['width'],
+    height: data['meta'] && data['meta']['height'],
+    transloadit: data['meta'],
+  }
+}
 ```
 
-Then in your `POST /webhooks/transloadit` route you can call the plugin to
-automatically save the results to the attachment column in Shrine's format.
-
-```rb
-post "/webhooks/transloadit" do
-  Shrine::Attacher.transloadit_save(params)
-end
-```
+See the **[demo app]** for a complete implementation of direct uploads.
 
 ### Templates
 
@@ -163,10 +168,34 @@ class MyUploader < Shrine
 end
 ```
 
+### Webhooks
+
+Transloadit performs its processing asynchronously, and you can provide a URL
+where you want Transloadit to POST results of processing once it's finished.
+
+```rb
+class MyUploader < Shrine
+  def transloadit_process(io, context)
+    # ...
+
+    transloadit_assembly(files, notify_url: "http://myapp.com/webhooks/transloadit")
+  end
+end
+```
+
+Then in your `POST /webhooks/transloadit` route you can call the plugin to
+automatically save the results to the attachment column in Shrine's format.
+
+```rb
+post "/webhooks/transloadit" do
+  Shrine::Attacher.transloadit_save(params)
+end
+```
+
 ### Backgrounding
 
 Even though submitting a Transloadit assembly doesn't require any uploading, it
-still does two HTTP requests, so you might want to put it into a backgrond job.
+still does two HTTP requests, so you might want to put it into a background job.
 This plugin naturally hooks onto Shrine's backgrounding plugin:
 
 ```rb
@@ -212,20 +241,35 @@ response.reload!
 response.finished? #=> true
 ```
 
-### Direct uploads
+### Metadata
 
-Transloadit supports direct uploads, allowing you to do additional processing
-on upload, along with a [jQuery plugin] for easy integration. Generally you
-only want to do some light processing on direct uploads, and without any
-exporting, so that you have better control over your Transloadit bandwidth.
+For each processed file Transloadit also extracts a great deal of useful
+metadata. When the Transloadit processing is finished and the results are saved
+as a Shrine attachment, this metadata will be automatically used to populate
+the attachment's metadata.
 
-When direct upload finishes, Transloadit returns information about the uploaded
-file(s). You can just convert that data to a JSON string and pass it as attachment
-value (e.g. by assigning it to the hidden attachment field), and the plugin
-will automatically recognize it and convert it to Shrine's attachment
-representation.
+Additionally the Transloadit's metadata hash will be saved in an additional
+metadata key, so that you can access any other values:
 
-See the **[demo app]** for a complete implementation of direct uploads.
+```rb
+photo = Photo.create(image: image_file)
+photo.image.metadata["transloadit"] #=>
+# {
+#   "date_recorded"         => "2013/09/04 08:03:39",
+#   "date_file_created"     => "2013/09/04 12:03:39 GMT",
+#   "date_file_modified"    => "2016/07/11 02:27:11 GMT",
+#   "aspect_ratio"          => "1.504",
+#   "city"                  => "Decatur",
+#   "state"                 => "Georgia",
+#   "country"               => "United States",
+#   "latitude"              => 33.77519301,
+#   "longitude"             => -84.295608,
+#   "orientation"           => "Horizontal (normal)",
+#   "colorspace"            => "RGB",
+#   "average_color"         => "#8b8688",
+#   ...
+# }
+```
 
 ### Import & Export
 

data/lib/shrine/plugins/transloadit.rb

@@ -1,14 +1,19 @@
 require "transloadit"
-require "down"
 
 require "uri"
 require "json"
 require "openssl"
-require "net/http"
 
 class Shrine
   module Plugins
     module Transloadit
+      # Accepts Transloadit credentials via `:auth_key` and `:auth_secret`.
+      #
+      # If :cache storage wasn't assigned, it will be assigned to a URL storage
+      # for direct uploads.
+      #
+      # If promoting was not yet overriden, it is set to automatically trigger
+      # Transloadit processing defined in `Shrine#transloadit_process`.
       def self.configure(uploader, opts = {})
         uploader.opts[:transloadit_auth_key] = opts.fetch(:auth_key, uploader.opts[:transloadit_auth_key])
         uploader.opts[:transloadit_auth_secret] = opts.fetch(:auth_secret, uploader.opts[:transloadit_auth_secret])
@@ -16,15 +21,22 @@ class Shrine
         raise Error, "The :auth_key is required for transloadit plugin" if uploader.opts[:transloadit_auth_key].nil?
         raise Error, "The :auth_secret is required for transloadit plugin" if uploader.opts[:transloadit_auth_secret].nil?
 
-        uploader.storages[:cache] ||= UrlStorage.new
+        uploader.storages[:cache] ||= (
+          require "shrine/storage/url"
+          Shrine::Storage::Url.new
+        )
+
         uploader.opts[:backgrounding_promote] ||= proc { transloadit_process }
       end
 
+      # It loads the backgrounding plugin, so that it can override promoting.
       def self.load_dependencies(uploader, opts = {})
         uploader.plugin :backgrounding
       end
 
       module AttacherClassMethods
+        # Loads the attacher from the data, and triggers Transloadit
+        # processing. Intended to be used in a background job.
         def transloadit_process(data)
           attacher = self.load(data)
           cached_file = attacher.uploaded_file(data["attachment"])
@@ -32,6 +44,9 @@ class Shrine
           attacher
         end
 
+        # This should be called when receiving a webhook, where arguments are
+        # params that Transloadit POSTed to the endpoint. It checks the
+        # signature, loads the attacher, saves processing results to the record.
         def transloadit_save(params)
           params["transloadit"] = params["transloadit"].to_json if params["transloadit"].is_a?(Hash)
           check_transloadit_signature!(params)
@@ -43,6 +58,9 @@ class Shrine
           attacher
         end
 
+        # Checks if the webhook has indeed been triggered by Transloadit, by
+        # checking if sent signature matches the calculated signature, and
+        # raising a `Shrine::Error` if signatures don't match.
         def check_transloadit_signature!(params)
           sent_signature = params["signature"]
           payload = params["transloadit"]
@@ -54,6 +72,16 @@ class Shrine
       end
 
       module AttacherMethods
+        # Triggers Transloadit processing defined by the user in
+        # `Shrine#transloadit_process`. It dumps the attacher in the payload of
+        # the request, so that it's included in the webhook and that we know
+        # which webhook belongs to which record/attachment.
+        #
+        # After the Transloadit assembly was submitted, the response is saved
+        # into cached file's metadata, which can then be reloaded at will for
+        # checking progress of the assembly.
+        #
+        # It raises a `Shrine::Error` if Transloadit returned an error.
         def transloadit_process(cached_file = get)
           assembly = store.transloadit_process(cached_file, context)
           assembly.options[:fields] ||= {}
@@ -64,6 +92,13 @@ class Shrine
           swap(cached_file) or _set(cached_file)
         end
 
+        # It receives the result of Transloadit processing, and converts it into
+        # Shrine's representation(s) of an uploaded file (either as a single
+        # file or a hash of versions).
+        #
+        # If attachment has changed in the meanwhile, meaning the result of
+        # this processing is no longer valid, it deletes the processed files
+        # from the main storage.
         def transloadit_save(response, valid: true)
           if versions = response["fields"]["versions"]
             stored_file = versions.inject({}) do |hash, (name, key)|
@@ -82,22 +117,11 @@ class Shrine
             _delete(stored_file, phase: :abort)
           end
         end
-
-        def uploaded_file(value)
-          if value.is_a?(String) || value.is_a?(Hash)
-            value = JSON.parse(value) if value.is_a?(String)
-            if value["url"].is_a?(String) # from direct upload
-              cache.transloadit_uploaded_file(value)
-            else
-              super
-            end
-          else
-            super
-          end
-        end
       end
 
       module ClassMethods
+        # Creates a new Transloadit client, so that the expiration timestamp is
+        # refreshed on new processing requests.
         def transloadit
           ::Transloadit.new(
             key:    opts[:transloadit_auth_key],
@@ -107,11 +131,18 @@ class Shrine
       end
 
       module InstanceMethods
+        # Converts Transloadit's representation of an uploaded file into
+        # Shrine's representation. It currently only accepts files exported to
+        # S3. All Transloadit's metadata is saved into a "transloadit"
+        # attribute.
+        #
+        # When doing direct uploads to Transloadit you will only get a
+        # temporary URL, which will be saved in the "id" attribute and it's
+        # expected that the URL storage is used.
         def transloadit_uploaded_file(result)
           case url = result.fetch("url")
-          when /tmp\.transloadit\.com/
-            id = url
           when /amazonaws\.com/
+            raise Error, "Cannot save a processed file which wasn't exported: #{url.inspect}" if url.include?("tmp.transloadit.com")
             path = URI(url).path
             id = path.match(/^\/#{storage.prefix}/).post_match
           else
@@ -132,6 +163,9 @@ class Shrine
           )
         end
 
+        # Generates a Transloadit import step from the Shrine::UploadedFile.
+        # If it's from the S3 storage, an S3 import step will be generated.
+        # Otherwise either a generic HTTP(S) or an FTP import will be generated.
         def transloadit_import_step(name, io, **step_options)
           uri = URI.parse(io.url)
 
@@ -163,6 +197,8 @@ class Shrine
           step
         end
 
+        # Generates an export step from the current (permanent) storage.
+        # At the moment only Amazon S3 is supported.
         def transloadit_export_step(name, **step_options)
           if defined?(Storage::S3) && storage.is_a?(Storage::S3)
             step = transloadit.step(name, "/s3/store",
@@ -180,12 +216,20 @@ class Shrine
           step
         end
 
+        # Creates a new TransloaditFile for building steps, with an optional
+        # import step applied.
         def transloadit_file(io = nil)
           file = TransloaditFile.new(transloadit: transloadit)
           file = file.add_step(transloadit_import_step("import", io)) if io
           file
         end
 
+        # Accepts a TransloaditFile, a hash of TransloaditFiles or a template,
+        # and converts it into a Transloadit::Assembly.
+        #
+        # If a hash of versions are given, the version information is saved in
+        # assembly's payload, so that later in the webhook it can be used to
+        # construct a hash of versions.
         def transloadit_assembly(value, context: {}, **options)
           options[:steps] ||= []
           options[:fields] ||= {}
@@ -224,12 +268,16 @@ class Shrine
           transloadit.assembly(options)
         end
 
+        # An cached instance of a Tranloadit client.
         def transloadit
           @transloadit ||= self.class.transloadit
         end
       end
 
       module FileMethods
+        # Converts the "transloadit_response" that was saved in cached file's
+        # metadata into a reloadable object which is normally returned by the
+        # Transloadit gem.
         def transloadit_response
           @transloadit_response ||= (
             body = metadata["transloadit_response"] or return
@@ -249,6 +297,11 @@ class Shrine
           @steps = steps
         end
 
+        # Adds a step to the pipeline, automatically setting :use to the
+        # previous step, so that later multiple pipelines can be seamlessly
+        # joined into a single assembly.
+        #
+        # It returns a new TransloaditFile with the step added.
         def add_step(*args)
           if args[0].is_a?(::Transloadit::Step)
             step = args[0]
@@ -263,8 +316,9 @@ class Shrine
           TransloaditFile.new(transloadit: transloadit, steps: @steps + [step])
         end
 
-        # Transloadit in its result uses the name of the last step before the
-        # export step.
+        # The key that Transloadit will use in its processing results for the
+        # corresponding processed file. This equals to the name of the last
+        # step, unless the last step is an export step.
         def name
           if exported?
             @steps[-2].name
@@ -273,35 +327,16 @@ class Shrine
           end
         end
 
+        # Returns true if this TransloaditFile includes an import step.
         def imported?
           @steps.any? && @steps.first.robot.end_with?("/import")
         end
 
+        # Returns true if this TransloaditFile includes an export step.
         def exported?
           @steps.any? && @steps.last.robot.end_with?("/store")
         end
       end
-
-      class UrlStorage
-        def download(id)
-          Down.download(id)
-        end
-
-        def open(id)
-          Down.open(id)
-        end
-
-        def exists?(id)
-          response = nil
-          uri = URI(id)
-          Net::HTTP.start(uri.host, uri.port) { |http| response = http.head(id) }
-          response.code.to_i == 200
-        end
-
-        def url(id, **options)
-          id
-        end
-      end
     end
 
     register_plugin(:transloadit, Transloadit)

data/shrine-transloadit.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |gem|
   gem.name          = "shrine-transloadit"
-  gem.version       = "0.2.1"
+  gem.version       = "0.3.0"
 
   gem.required_ruby_version = ">= 2.1"
 
@@ -15,7 +15,7 @@ Gem::Specification.new do |gem|
 
   gem.add_dependency "shrine", "~> 2.1"
   gem.add_dependency "transloadit", "~> 1.2"
-  gem.add_dependency "down", ">= 2.3.3"
+  gem.add_dependency "shrine-url"
 
   gem.add_development_dependency "rake"
   gem.add_development_dependency "minitest"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: shrine-transloadit
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Janko Marohnić
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-07-08 00:00:00.000000000 Z
+date: 2016-07-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: shrine
@@ -39,19 +39,19 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '1.2'
 - !ruby/object:Gem::Dependency
-  name: down
+  name: shrine-url
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.3.3
+        version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.3.3
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement