shrine 0.9.0

data/lib/shrine/plugins/direct_upload.rb

@@ -0,0 +1,274 @@
+require "roda"
+
+require "json"
+require "forwardable"
+require "securerandom"
+
+class Shrine
+  module Plugins
+    # The direct_upload plugin provides a Rack endpoint (implemented in [Roda])
+    # which you can use to implement AJAX uploads.
+    #
+    #     plugin :direct_upload, max_size: 20*1024*1024
+    #
+    # This is how you could mount the endpoint in a Rails application:
+    #
+    #     Rails.application.routes.draw do
+    #       # adds `POST /attachments/images/:storage/:name`
+    #       mount ImageUploader.direct_endpoint => "/attachments/images"
+    #     end
+    #
+    # Note that you should mount a separate endpoint for each uploader that you
+    # want to use it with. This now gives your Ruby application a
+    # `POST /attachments/images/:storage/:name` route, which accepts a "file"
+    # query parameter:
+    #
+    #     $ curl -F "file=@/path/to/avatar.jpg" localhost:3000/attachments/images/cache/avatar
+    #     # {"id":"43kewit94.jpg","storage":"cache","metadata":{...}}
+    #
+    # The endpoint returns all responses in JSON format. There are many great
+    # JavaScript libraries for AJAX file uploads, so for example if we have
+    # this form:
+    #
+    #     <%= form_for @user do |f| %>
+    #       <%= f.hidden_field :avatar, value: @user.avatar_data %>
+    #       <%= f.file_field :avatar %>
+    #     <% end %>
+    #
+    # this is how we could hook up [jQuery-File-Upload] to our direct upload
+    # endpoint:
+    #
+    #     $('[type="file"]').fileupload({
+    #       url: '/attachments/images/cache/avatar',
+    #       paramName: 'file',
+    #       done: function(e, data) { $(this).prev().value(data.result) }
+    #     });
+    #
+    # Now whenever a file gets chosen, the upload will automatically start in
+    # the background. It's typically good to show a progress bar to the user,
+    # which jQuery-File-Upload [supports]. After the upload has finished, the
+    # uploaded file JSON is written to the hidden field, and will be sent on
+    # form submit.
+    #
+    # ## Presigned
+    #
+    # An alternative to the direct endpoint is doing direct uploads to the
+    # underlying storage. These uploads usually requires extra information
+    # from the server, and this plugin can provide an endpoint to it, which
+    # you can enable by passing in `presign: true`:
+    #
+    #     plugin :direct_upload, presign: true
+    #
+    # This will disable the default `POST /:storage/:name` route (for security
+    # reasons), and enable `GET /:storage/presign`. The response for that
+    # request looks something like this:
+    #
+    #     {
+    #       "url" => "https://shrine-testing.s3-eu-west-1.amazonaws.com",
+    #       "fields" => {
+    #         "key" => "b7d575850ba61b44c8a9ff889dfdb14d88cdc25f8dd121004c8",
+    #         "policy" => "eyJleHBpcmF0aW9uIjoiMjAxNS0QwMToxMToyOVoiLCJjb25kaXRpb25zIjpbeyJidWNrZXQiOiJzaHJpbmUtdGVzdGluZyJ9LHsia2V5IjoiYjdkNTc1ODUwYmE2MWI0NGU3Y2M4YTliZmY4OGU5ZGZkYjE2NTQ0ZDk4OGNkYzI1ZjhkZDEyMTAwNGM4In0seyJ4LWFtei1jcmVkZW50aWFsIjoiQUtJQUlKRjU1VE1aWlk0NVVUNlEvMjAxNTEwMjQvZXUtd2VzdC0xL3MzL2F3czRfcmVxdWVzdCJ9LHsieC1hbXotYWxnb3JpdGhtIjoiQVdTNC1ITUFDLVNIQTI1NiJ9LHsieC1hbXotZGF0ZSI6IjIwMTUxMDI0VDAwMTEyOVoifV19",
+    #         "x-amz-credential" => "AKIAIJF55TMZYT6Q/20151024/eu-west-1/s3/aws4_request",
+    #         "x-amz-algorithm" => "AWS4-HMAC-SHA256",
+    #         "x-amz-date" => "20151024T001129Z",
+    #         "x-amz-signature" => "c1eb634f83f96b69bd675f535b3ff15ae184b102fcba51e4db5f4959b4ae26f4"
+    #       }
+    #     }
+    #
+    # The `url` is where the file needs to be uploaded to, and `fields` is
+    # additional data that needs to be send on the upload. The `fields.key`
+    # attribute is the location where the file will be uploaded to, it is
+    # generated randomly. `GET /:storage/presign` accepts additional parameters:
+    #
+    # :extension
+    # : The extension of the file being uploaded (e.g ".jpg").
+    #
+    # :content_type
+    # : Sets the Content-Type header for the uploaded file on S3.
+    #
+    # Example:
+    #
+    #     GET /cache/presign?content_type=image/jpeg
+    #     GET /cache/presign?extension=.png
+    #
+    # ## Constraints
+    #
+    # Note that the direct upload doesn't run validations, they are only run
+    # when attached to the record. If you want to limit the MIME type of files,
+    # you could add an ["accept" attribute] to your file field. You could also
+    # add client side validations for the maximum file size.
+    #
+    # It's encouraged that you set the `:max_size` option for the endpoint.
+    # Once set, when a file that is too big is uploaded, the endpoint will
+    # automatically delete the file and return a 413 response.  However, if for
+    # whatever reason you don't want to impose a limit on filesize, you can set
+    # the option to nil:
+    #
+    #     plugin :direct_upload, max_size: nil
+    #
+    # ## Allowed storages
+    #
+    # While Shrine only accepts cached attachments on form submits (for security
+    # reasons), you can use this endpoint to upload files to any storage, just
+    # add it do allowed storages:
+    #
+    #     plugin :direct_upload, allowed_storages: [:cache, :store]
+    #
+    # ## Authentication
+    #
+    # If you want to authenticate the endpoint, you should be able to do it
+    # easily if your web framework has a good enough router. For example, in
+    # Rails you could add a `constraints` directive:
+    #
+    #     Rails.application.routes.draw do
+    #       constraints(->(r){r.env["warden"].authenticate!}) do
+    #         mount ImageUploader.direct_endpoint => "/attachments/images"
+    #       end
+    #     end
+    #
+    # [Roda]: https://github.com/jeremyevans/roda
+    # [jQuery-File-Upload]: https://github.com/blueimp/jQuery-File-Upload
+    # [supports]: https://github.com/blueimp/jQuery-File-Upload/wiki/Options#progress
+    # ["accept" attribute]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#attr-accept
+    module DirectUpload
+      def self.configure(uploader, allowed_storages: [:cache], max_size:, presign: nil)
+        uploader.opts[:direct_upload_allowed_storages] = allowed_storages
+        uploader.opts[:direct_upload_max_size] = max_size
+        uploader.opts[:direct_upload_presign] = presign
+      end
+
+      module ClassMethods
+        # Return the cached Roda endpoint.
+        def direct_endpoint
+          @direct_endpoint ||= build_direct_endpoint
+        end
+
+        private
+
+        # Builds the endpoint and assigns it the current Shrine class.
+        def build_direct_endpoint
+          app = Class.new(App)
+          app.opts[:shrine_class] = self
+          app.app
+        end
+      end
+
+      class App < Roda
+        plugin :default_headers, "Content-Type"=>"application/json"
+        plugin :halt
+
+        # Routes incoming requests. We first check if the storage is allowed,
+        # then proceed further with the upload, returning the uploaded file
+        # as JSON.
+        route do |r|
+          r.on ":storage" do |storage_key|
+            allow_storage!(storage_key)
+            @uploader = shrine_class.new(storage_key.to_sym)
+
+            r.post ":name" do |name|
+              file = get_file
+              context = {name: name, phase: :cache}
+
+              json @uploader.upload(file, context)
+            end unless presign?
+
+            r.get "presign" do
+              location = SecureRandom.hex(30).to_s + r.params["extension"].to_s
+              options = {}
+              options[:content_length_range] = 0..max_size if max_size
+              options[:content_type] = r.params["content_type"] if r.params["content_type"]
+
+              signature = @uploader.storage.presign(location, options)
+
+              json Hash[url: signature.url, fields: signature.fields]
+            end if presign?
+          end
+        end
+
+        def json(object)
+          object.to_json
+        end
+
+        # Halts the request if storage is not allowed.
+        def allow_storage!(storage)
+          if !allowed_storages.map(&:to_s).include?(storage)
+            error! 403, "Storage #{storage.inspect} is not allowed."
+          end
+        end
+
+        # Returns the Rack file wrapped in an IO-like object. If "file" is
+        # missing or is too big, the request is halted.
+        def get_file
+          file = require_param!("file")
+          error! 400, "The \"file\" query parameter is not a file." if !(file.is_a?(Hash) && file.key?(:tempfile))
+          check_filesize!(file[:tempfile]) if max_size
+
+          RackFile.new(file)
+        end
+
+        # If the file is too big, deletes the file and halts the request.
+        def check_filesize!(file)
+          if file.size > max_size
+            file.delete
+            megabytes = max_size.to_f / 1024 / 1024
+            error! 413, "The file is too big (maximum size is #{megabytes} MB)."
+          end
+        end
+
+        # Loudly requires the param.
+        def require_param!(name)
+          request.params.fetch(name)
+        rescue KeyError
+          error! 400, "Missing query parameter: #{name.inspect}"
+        end
+
+        # Halts the request with the error message.
+        def error!(status, message)
+          request.halt status, {error: message}.to_json
+        end
+
+        def shrine_class
+          opts[:shrine_class]
+        end
+
+        def allowed_storages
+          shrine_class.opts[:direct_upload_allowed_storages]
+        end
+
+        def max_size
+          shrine_class.opts[:direct_upload_max_size]
+        end
+
+        def presign?
+          shrine_class.opts[:direct_upload_presign]
+        end
+      end
+
+      # This is used to wrap the Rack hash into an IO-like object which Shrine
+      # can upload.
+      class RackFile
+        attr_reader :original_filename, :content_type
+        attr_accessor :tempfile
+
+        def initialize(tempfile:, filename: nil, type: nil, **)
+          @tempfile          = tempfile
+          @original_filename = filename
+          @content_type      = type
+        end
+
+        def path
+          @tempfile.path
+        end
+
+        def to_io
+          @tempfile
+        end
+
+        extend Forwardable
+        delegate Shrine::IO_METHODS.keys => :@tempfile
+      end
+    end
+
+    register_plugin(:direct_upload, DirectUpload)
+  end
+end

data/lib/shrine/plugins/dynamic_storage.rb

@@ -0,0 +1,57 @@
+class Shrine
+  module Plugins
+    # The dynamic_storage plugin allows you to register a storage using a
+    # regex, and evaluate the storage class dynamically depending on the regex.
+    #
+    # Example:
+    #
+    #     plugin :dynamic_storage
+    #
+    #     storage /store_(\w+)/ do |match|
+    #       Shrine::Storages::S3.new(bucket: match[1])
+    #     end
+    #
+    # The above example uses S3 storage where the bucket name depends on the
+    # storage name suffix. For example, `:store_foo` will use S3 storage which
+    # saves files to the bucket "foo". The block is yielded an instance of
+    # `MatchData`.
+    #
+    # This can be useful in combination with the default_storage plugin.
+    module DynamicStorage
+      module ClassMethods
+        def dynamic_storages
+          @dynamic_storages ||= {}
+        end
+
+        def storage(regex, &block)
+          dynamic_storages[regex] = block
+        end
+
+        def find_storage(name)
+          resolve_dynamic_storage(name) or super
+        end
+
+        private
+
+        def resolve_dynamic_storage(name)
+          dynamic_storage_cache.fetch(name) do
+            dynamic_storages.each do |regex, block|
+              if match = name.to_s.match(regex)
+                dynamic_storage_cache[name] = block.call(match)
+                break
+              end
+            end
+
+            dynamic_storage_cache[name]
+          end
+        end
+
+        def dynamic_storage_cache
+          @dynamic_storage_cache ||= {}
+        end
+      end
+    end
+
+    register_plugin(:dynamic_storage, DynamicStorage)
+  end
+end

data/lib/shrine/plugins/hooks.rb

@@ -0,0 +1,123 @@
+class Shrine
+  module Plugins
+    # The hooks plugin allows you to trigger some code around
+    # processing/storing/deleting of each file.
+    #
+    #     plugin :hooks
+    #
+    # Shrine uses instance methods for hooks. To define a hook for an uploader,
+    # you just add an instance method to the uploader:
+    #
+    #     class ImageUploader < Shrine
+    #       def around_process(io, context)
+    #         super
+    #       rescue
+    #         ExceptionNotifier.processing_failed(io, context)
+    #       end
+    #     end
+    #
+    # Each hook will be called with 2 arguments, `io` and `context`.  It's
+    # generally good to always call super when overriding a hook, especially if
+    # you're using inheritance with your uploaders.
+    #
+    # Shrine calls hooks in the following order when uploading a file:
+    #
+    # * `around_process`
+    #     * `before_process`
+    #     * PROCESS
+    #     * `after_process`
+    # * `around_store`
+    #     * `before_store`
+    #     * STORE
+    #     * `after_store`
+    #
+    # Shrine calls hooks in the following order when deleting a file:
+    #
+    # * `around_delete`
+    #     * `before_delete`
+    #     * DELETE
+    #     * `after_delete`
+    #
+    # It may be useful to know that you can realize some form of communication
+    # between the hooks; whatever you save to the `context` hash will be
+    # forwarded further down:
+    #
+    #     class ImageUploader < Shrine
+    #       def before_process(io, context)
+    #         context[:_foo] = "bar"
+    #         super
+    #       end
+    #
+    #       def before_store(io, context)
+    #         context[:_foo] #=> "bar"
+    #         super
+    #       end
+    #     end
+    #
+    # In that case you should always somehow mark this key as private (for
+    # example with an underscore) so that it doesn't clash with any
+    # existing keys.
+    module Hooks
+      module InstanceMethods
+        def processed(io, context)
+          result = nil
+          around_process(io, context) { result = super }
+          result
+        end
+        private :processed
+
+        def around_process(*args)
+          before_process(*args)
+          yield
+          after_process(*args)
+        end
+
+        def before_process(*)
+        end
+
+        def after_process(*)
+        end
+
+
+        def store(io, context = {})
+          result = nil
+          around_store(io, context) { result = super }
+          result
+        end
+
+        def around_store(*args)
+          before_store(*args)
+          yield
+          after_store(*args)
+        end
+
+        def before_store(*)
+        end
+
+        def after_store(*)
+        end
+
+
+        def delete(io, context = {})
+          result = nil
+          around_delete(io, context) { result = super }
+          result
+        end
+
+        def around_delete(*args)
+          before_delete(*args)
+          yield
+          after_delete(*args)
+        end
+
+        def before_delete(*)
+        end
+
+        def after_delete(*)
+        end
+      end
+    end
+
+    register_plugin(:hooks, Hooks)
+  end
+end