shrine 2.3.0 → 2.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ed4ba1e9f5dafe48af21c7f80039ca3d0014e600
-  data.tar.gz: 2f8f7903b3032d8ef43508a0e7259ab5deaedb25
+  metadata.gz: 27f5213f9cac952b0947848a6f9b518ca5ed6705
+  data.tar.gz: d343abd428ddc64dec6d9a049509acdeebe90692
 SHA512:
-  metadata.gz: 3d9200a6bfc5fe5705272a4d01a2e62a7146e869c53ede22534ec9043fa87e7c9566b58b5a7cf10f9667de47a9e91d468e34dae146b8cc8526f94cdcbe0f4404
-  data.tar.gz: 3c9673213a120a2d8427a9bee3280bccb97819154f1bd5bc7bc548f3a70274891133c4c86151b52bd8f94bdc158a4f8be84adf364edd2fd3488f7df98b75d5ef
+  metadata.gz: f33bf01e38fa6e854467121d0d92f640491977d234a1201c7c4187503e889965ba797e54f3d05d561e8862bbe32c82edf2cbda6e63ab1557f222ce225613322a
+  data.tar.gz: 32351b7cb1fb3afd6bf31d206096fe034b038ed518950dbf82ca95cca8e4c718168ff4c50a5467c671e1d3a04ef7469e15c20ff61724edae416ebe31c7ffa0c3

data/README.md

@@ -602,7 +602,7 @@ demo apps which implement multiple uploads directly to S3.
 ## Backgrounding
 
 Shrine is the first file upload library designed for backgrounding support.
-Moving phases of managing attachments to background jobs is essential for
+Moving phases of managing file attachments to background jobs is essential for
 scaling and good user experience, and Shrine provides a `backgrounding` plugin
 which makes it really easy to plug in your favourite backgrounding library:
 
@@ -630,7 +630,7 @@ end
 
 The above puts all promoting (uploading cached file to permanent storage) and
 deleting of files into a background Sidekiq job. Obviously instead of Sidekiq
-you can use any other backgrounding library.
+you can use [any other backgrounding library][backgrounding libraries].
 
 The main advantages of Shrine's backgrounding support over other file upload
 libraries are:
@@ -720,3 +720,4 @@ The gem is available as open source under the terms of the [MIT License].
 [rails_demo]: https://github.com/erikdahlstrand/shrine-rails-example
 [Direct Uploads to S3]: http://shrinerb.com/rdoc/files/doc/direct_s3_md.html
 [website]: http://shrinerb.com
+[backgrounding libraries]: https://github.com/janko-m/shrine/wiki/Backgrounding-libraries

data/doc/creating_storages.md

@@ -10,12 +10,12 @@ methods:
 class Shrine
   module Storage
     class MyStorage
-      def upload(io, id, **options)
-        # uploads `io` to the location `id`
+      def upload(io, id, shrine_metadata: {}, **upload_options)
+        # uploads `io` to the location `id`, can accept upload options
       end
 
       def url(id, **options)
-        # URL to the remote file, accepts options for customizing the URL
+        # returns URL to the remote file, accepts options for customizing the URL
       end
 
       def open(id)
@@ -64,8 +64,8 @@ end
 ## Download
 
 Shrine automatically downloads the file to a Tempfile using `#open`. However,
-if you would like to implement your own downloading, you can define `#download`
-and Shrine will use that instead:
+if you would like to do custom downloading, you can define `#download` and
+Shrine will use that instead:
 
 ```rb
 class Shrine
@@ -83,10 +83,15 @@ class Shrine
 end
 ```
 
-## Update
+## Presign
 
-If your storage supports updating data of existing files (e.g. some metadata),
-the convention is to create an `#update` method:
+If the storage service supports direct uploads, and requires fetching
+additional information from the server, you can implement a `#presign` method,
+which will be used by the `direct_upload` plugin. The method should return an
+object which responds to
+
+* `#url` – returns the URL to which the file should be uploaded to
+* `#fields` – returns a hash of request parameters for the upload
 
 ```rb
 class Shrine
@@ -94,8 +99,8 @@ class Shrine
     class MyStorage
       # ...
 
-      def update(id, options = {})
-        # update data of the file
+      def presign(id, **options)
+        # returns an object which responds to #url and #presign
       end
 
       # ...
@@ -157,6 +162,7 @@ While this method is not used by Shrine, it is good to give users the
 possibility to delete all files in a storage, and the conventional name for
 this method is `#clear!`:
 
+```rb
 class Shrine
   module Strorage
     class MyStorage
@@ -170,6 +176,28 @@ class Shrine
     end
   end
 end
+```
+
+## Update
+
+If your storage supports updating data of existing files (e.g. some metadata),
+the convention is to create an `#update` method:
+
+```rb
+class Shrine
+  module Storage
+    class MyStorage
+      # ...
+
+      def update(id, options = {})
+        # update data of the file
+      end
+
+      # ...
+    end
+  end
+end
+```
 
 ## Linter
 

data/doc/direct_s3.md

@@ -3,21 +3,21 @@
 Shrine gives you the ability to upload files directly to Amazon S3, which is
 beneficial for several use cases:
 
-* accepting uploads is resource-intensive for the server, and delegating it to
-  an external service makes scaling easier
+* Accepting uploads is resource-intensive for the server, and delegating it to
+  an external service makes scaling easier.
 
-* if both temporary and permanent storage are S3, promoting an S3 file to
+* If both temporary and permanent storage are S3, promoting an S3 file to
   permanent storage will simply issue an S3 copy request, without any
-  downloading and reuploading
+  downloading and reuploading.
 
-* with multiple servers it's generally not possible to cache files to the disk,
-  unless you're using a distibuted filesystem that's shared between servers
+* With multiple servers it's generally not possible to cache files to the disk,
+  unless you're using a distibuted filesystem that's shared between servers.
 
 * Heroku restricts file uploads to disk, allowing you to save files only in
-  the temporary folder, which gets wiped out between deploys
+  the temporary folder, which gets wiped out between deploys.
 
 * Heroku has a 30-second request limit, so if the client has a slow connection
-  and/or your files are larger, uploads to your app can easily hit that limit
+  and/or your files are larger, uploads to your app can easily hit that limit.
 
 You can start by setting both temporary and permanent storage to S3 with
 different prefixes (or even buckets):
@@ -28,7 +28,12 @@ gem "aws-sdk", "~> 2.1"
 ```rb
 require "shrine/storage/s3"
 
-s3_options = {access_key_id: "...", secret_access_key: "...", region: "..."}
+s3_options = {
+  access_key_id:     "abc",
+  secret_access_key: "123",
+  region:            "my-region",
+  bucket:            "my-bucket",
+}
 
 Shrine.storages = {
   cache: Shrine::Storage::S3.new(prefix: "cache", **s3_options),
@@ -227,4 +232,5 @@ end
 [demo app]: https://github.com/janko-m/shrine/tree/master/demo
 [Dropzone]: https://github.com/enyo/dropzone
 [jQuery-File-Upload]: https://github.com/blueimp/jQuery-File-Upload
+[FineUploader]: https://github.com/FineUploader/fine-uploader
 [Amazon S3 Data Consistency Model]: http://docs.aws.amazon.com/AmazonS3/latest/dev/Introduction.html#ConsistencyMode

data/lib/shrine/plugins/concatenation.rb

@@ -0,0 +1,73 @@
+class Shrine
+  module Plugins
+    # The `concatenation` plugin allows you to assign to the attacher a
+    # cached file which is composed of multiple uploaded parts. The plugin
+    # will then call `#concat` on the storage, which is expected to
+    # concatenate the given parts into a single file. The assigned
+    # attachment will then be a complete cached file.
+    #
+    #     plugin :concatenation
+    #
+    # The plugin expects to receive the cached file in the standard JSON
+    # format, with an additional `"parts"` key which is the array of
+    # uploaded parts:
+    #
+    #     {
+    #       "id": "lsdg94l31.jpg",
+    #       "storage": "cache",
+    #       "parts": [
+    #         {"id": "aaa", "storage": "cache", "metadata": {}},
+    #         {"id": "bbb", "storage": "cache", "metadata": {}},
+    #         # ...
+    #       ],
+    #       "metadata": {
+    #         # ...
+    #       }
+    #     }
+    #
+    # The `"metadata"` field of individual parts should contain information
+    # that your storage needs to perform concatenation, refer to the
+    # documentation of your storage.
+    #
+    # You can also pass additional storage-specific concatenation options:
+    #
+    #     plugin :concatenation, options: {use_accelerate_endpoint: true}
+    #
+    #     plugin :concatenation, options: ->(io, context) do
+    #       {use_accelerate_endpoint: true} unless context[:record].guest?
+    #     end
+    module Concatenation
+      def self.configure(uploader, opts = {})
+        uploader.opts[:concatenation_options] = opts.fetch(:options, uploader.opts.fetch(:options, {}))
+      end
+
+      module AttacherMethods
+        def assign(value)
+          if value.is_a?(String) && !value.empty?
+            data = JSON.parse(value)
+
+            if data.key?("parts")
+              parts    = data["parts"].map { |part_data| uploaded_file(part_data) }
+              location = data["id"]
+              metadata = data["metadata"]
+
+              options   = shrine_class.opts[:concatenation_options]
+              options   = options.call(uploaded_file(data), context) if options.respond_to?(:call)
+              options ||= {}
+
+              cache.storage.concat(parts, location, shrine_metadata: metadata, **options)
+
+              data.delete("parts")
+
+              assign(data.to_json)
+            else
+              super
+            end
+          end
+        end
+      end
+    end
+
+    register_plugin(:concatenation, Concatenation)
+  end
+end

data/lib/shrine/storage/file_system.rb

@@ -85,10 +85,14 @@ class Shrine
       #    can use this option to set a CDN host (e.g. `//abc123.cloudfront.net`).
       #
       # :permissions
-      # :  Changes the UNIX permissions of created files (default is 0644).
+      # :  The UNIX permissions applied to created files. Can be set to `nil`,
+      #    in which case the default permissions will be applied. Defaults to
+      #    `0644`.
       #
       # :directory_permissions
-      # :  Changes the UNIX permissions of created directories (default is 0755).
+      # :  The UNIX permissions applied to created directories. Can be set to
+      #    `nil`, in which case the default permissions will be applied. Defaults
+      #    to `0755`.
       #
       # :clean
       # :  By default empty folders inside the directory are automatically
@@ -107,8 +111,10 @@ class Shrine
         @directory_permissions = directory_permissions
         @clean = clean
 
-        @directory.mkpath
-        @directory.chmod(directory_permissions) if directory_permissions
+        unless @directory.exist?
+          @directory.mkpath
+          @directory.chmod(directory_permissions) if directory_permissions
+        end
       end
 
       # Copies the file into the given location.

data/lib/shrine/storage/linter.rb

@@ -35,7 +35,7 @@ class Shrine
       def call(io_factory = default_io_factory)
         storage.upload(io_factory.call, id = "foo", {})
 
-        lint_download(id)
+        lint_download(id) if storage.respond_to?(:download)
         lint_open(id)
         lint_exists(id)
         lint_url(id)

data/lib/shrine/version.rb

@@ -6,7 +6,7 @@ class Shrine
   module VERSION
     MAJOR = 2
     MINOR = 3
-    TINY  = 0
+    TINY  = 1
     PRE   = nil
 
     STRING = [MAJOR, MINOR, TINY, PRE].compact.join('.')

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: shrine
 version: !ruby/object:Gem::Version
-  version: 2.3.0
+  version: 2.3.1
 platform: ruby
 authors:
 - Janko Marohnić
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-08-27 00:00:00.000000000 Z
+date: 2016-09-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: down
@@ -311,6 +311,7 @@ files:
 - lib/shrine/plugins/backgrounding.rb
 - lib/shrine/plugins/backup.rb
 - lib/shrine/plugins/cached_attachment_data.rb
+- lib/shrine/plugins/concatenation.rb
 - lib/shrine/plugins/copy.rb
 - lib/shrine/plugins/data_uri.rb
 - lib/shrine/plugins/default_storage.rb