shrine-url 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a8b08fda0c471e0bd77b59fbd0b0c7dcef319c45
-  data.tar.gz: e7bf1aa59cc2890f564404a70692acd56a2a4c8a
+  metadata.gz: 05b3f6c5186e58f0cf26662a88f33a956d17d2fc
+  data.tar.gz: 321ba3cf1043b2913a6dccf3056d024582072f69
 SHA512:
-  metadata.gz: 6d798794e1e07afcfb5ea292424307bd35a456e1cbe470409c234fd046f1818b7c733e1309e1b1f8ea48e60bd366789efe6e126800f9b40966740c36c84c97b4
-  data.tar.gz: 85fb9f5f702e3a53bf815537d32a614a8f9527dbb1ecd6fdc2e2a702dd758c839a1404dd54d87d5cbd21568d46f51a4a5068a8f417488407838bfe2a96537975
+  metadata.gz: c99cdb69217eef960d553f69d1d7b4191c527bf599eeb05432e80d093d3d26325a7807b9797cc7df9021e2acd99193e41cbd8431ad0c139b812d735572d9d0a5
+  data.tar.gz: 6e9589ed93f23b8e578177b1b7e67e87241374b3c424259c0458af361309530190b1141b091c0656e62911d87d9997ab31f2ed0ee7fbb02693508c4e8c6f8263

data/README.md

@@ -1,6 +1,6 @@
 # Shrine::Storage::Url
 
-Provides a "storage" which allows you to save uploaded files defined by a
+Provides a "storage" which allows you to attach uploaded files defined by a
 custom URL.
 
 ## Installation
@@ -17,16 +17,23 @@ require "shrine/storage/url"
 Shrine.storages[:cache] = Shrine::Storage::Url.new
 ```
 
-```rb
-photo = Photo.new
+The custom URL should be assigned to the `id` field in the Shrine uploaded file
+JSON representation:
 
-attachment_data = {
-  id: "http://example.com/image.jpg",
-  storage: "cache",
-  metadata: {...}
+```rb
+{
+  "id": "http://example.com/image.jpg",
+  "storage": "cache",
+  "metadata": {
+    # ...
+  }
 }
+```
 
-photo.image = attachment_data.to_json
+Now you can assign this data as the cached attachment:
+
+```rb
+photo = Photo.new(image: data)
 photo.image #=> #<Shrine::UploadedFile>
 
 photo.image.url           #=> "http://example.com/image.jpg"
@@ -36,12 +43,34 @@ photo.image.exists?       # Sends a HEAD request and returns true if it's 2xx
 photo.image.delete        # Sends a DELETE request
 ```
 
-The custom URL can be saved to `id`, and `#url` will simply read that field.
-When this `Shrine::UploadedFile` is uploaded to another storage (e.g. permanent
-storage), if the storage doesn't support upload from URL the file will simply
-be downloaded from the custom URL, just like for any other storage.
+No HTTP requests are made at this point. When the cached file is uploaded to
+permanent storage, `shrine-url` will by default use [Down] to download the file
+from the given URL, before uploading it to permanent storage.
+
+Note that Down doesn't yet support resuming the download in case of network
+failures, so if you're expecting large files to be attached, you might want to
+tell `Shrine::Storage::Url` to use `wget` instead of Down.
+
+```rb
+Shrine::Storage::Url.new(downloader: :wget)
+```
+
+Just note that using `wget` won't work well with the `restore_cached_data`
+Shrine plugin from the performance standpoint, because `wget` doesn't support
+partial downloads, so the file would first be fully downloaded before
+extracting metadata.
+
+If you're using permanent storage that supports uploading from remote URL (like
+[shrine-cloudinary] or [shrine-uploadcare]), downloading will be completely
+skipped and the permanent storage will use only the custom URL for uploading
+the file.
+
+## Advantages and Use Cases
 
-## Use cases
+The main advantage of using `shrine-url` over the `remote_url` Shrine plugin is
+that you can put downloading from the URL into a background job by loading the
+`backgrounding` Shrine plugin. Another advantage is that you can assign
+multiple remote URLs as multiple versions.
 
 This storage can be used with [shrine-transloadit] for direct uploads, where a
 temporary URL of the uploaded file is returned, and we want to use that URL for
@@ -64,3 +93,6 @@ $ rake test
 
 [shrine-transloadit]: https://github.com/janko-m/shrine-transloadit
 [shrine-tus-demo]: https://github.com/janko-m/shrine-tus-demo
+[shrine-cloudinary]: https://github.com/janko-m/shrine-cloudinary
+[shrine-uploadcare]: https://github.com/janko-m/shrine-uploadcare
+[Down]: https://github.com/janko-m/down

data/lib/shrine/storage/url.rb

@@ -1,20 +1,23 @@
 require "shrine"
-require "down"
 require "net/http"
 
 class Shrine
   module Storage
     class Url
+      def initialize(downloader: :down)
+        @downloader = Downloader.new(downloader)
+      end
+
       def upload(io, id, **)
         id.replace(io.url)
       end
 
       def download(id)
-        Down.download(id)
+        @downloader.download(id)
       end
 
       def open(id)
-        Down.open(id)
+        @downloader.open(id)
       end
 
       def exists?(id)
@@ -44,6 +47,58 @@ class Shrine
 
         response
       end
+
+      class Downloader
+        SUPPORTED_TOOLS = [:down, :wget]
+
+        def initialize(tool)
+          raise ArgumentError, "unsupported downloading tool: #{tool}" unless SUPPORTED_TOOLS.include?(tool)
+
+          @tool = tool
+        end
+
+        def download(url)
+          send(:"download_with_#{@tool}", url)
+        end
+
+        def open(url)
+          send(:"open_with_#{@tool}", url)
+        end
+
+        private
+
+        def download_with_down(url)
+          require "down"
+          Down.download(url)
+        end
+
+        def open_with_down(url)
+          require "down"
+          Down.open(url)
+        end
+
+        def download_with_wget(url)
+          require "tempfile"
+          require "open3"
+
+          tempfile = Tempfile.new("shrine-url", binmode: true)
+          cmd = %W[wget --no-verbose #{url} -O #{tempfile.path}]
+          stdout, stderr, status = Open3.capture3(*cmd)
+
+          if !status.success?
+            tempfile.close!
+            raise "downloading from #{url} failed: #{stderr}"
+          end
+
+          tempfile.tap(&:open)
+        end
+
+        def open_with_wget(url)
+          tempfile = download_with_wget(url)
+          tempfile.instance_eval { def close(unlink_now=true) super end } # delete tempfile when it's closed
+          tempfile
+        end
+      end
     end
   end
 end

data/shrine-url.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |gem|
   gem.name          = "shrine-url"
-  gem.version       = "0.2.1"
+  gem.version       = "0.3.0"
 
   gem.required_ruby_version = ">= 2.1"
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: shrine-url
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Janko Marohnić
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-03-27 00:00:00.000000000 Z
+date: 2017-04-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: shrine