refile 0.4.2 → 0.5.0

data/lib/refile/backend/s3.rb

@@ -4,9 +4,30 @@ require "open-uri"
 module Refile
   module Backend
     # A refile backend which stores files in Amazon S3
+    #
+    # @example
+    #   backend = Refile::Backend::S3.new(
+    #     access_key_id: "xyz",
+    #     secret_access_key: "abcd1234",
+    #     bucket: "my-bucket",
+    #     prefix: "files"
+    #   )
+    #   file = backend.upload(StringIO.new("hello"))
+    #   backend.read(file.id) # => "hello"
     class S3
       attr_reader :access_key_id, :max_size
 
+      # Sets up an S3 backend with the given credentials.
+      #
+      # @param [String] access_key_id
+      # @param [String] secret_access_key
+      # @param [String] bucket            The name of the bucket where files will be stored
+      # @param [String] prefix            A prefix to add to all files. Prefixes on S3 are kind of like folders.
+      # @param [Integer, nil] max_size    The maximum size of an uploaded file
+      # @param [#hash] hasher             A hasher which is used to generate ids from files
+      # @param [Hash] s3_options          Additional options to initialize S3 with
+      # @see http://docs.aws.amazon.com/AWSRubySDK/latest/AWS/Core/Configuration.html
+      # @see http://docs.aws.amazon.com/AWSRubySDK/latest/AWS/S3.html
       def initialize(access_key_id:, secret_access_key:, bucket:, max_size: nil, prefix: nil, hasher: Refile::RandomHasher.new, **s3_options)
         @access_key_id = access_key_id
         @secret_access_key = secret_access_key
@@ -19,6 +40,10 @@ module Refile
         @max_size = max_size
       end
 
+      # Upload a file into this backend
+      #
+      # @param [IO] uploadable      An uploadable IO-like object.
+      # @return [Refile::File]      The uploaded file
       def upload(uploadable)
         Refile.verify_uploadable(uploadable, @max_size)
 
@@ -33,39 +58,80 @@ module Refile
         Refile::File.new(self, id)
       end
 
+      # Get a file from this backend.
+      #
+      # Note that this method will always return a {Refile::File} object, even
+      # if a file with the given id does not exist in this backend. Use
+      # {FileSystem#exists?} to check if the file actually exists.
+      #
+      # @param [Sring] id           The id of the file
+      # @return [Refile::File]      The retrieved file
       def get(id)
         Refile::File.new(self, id)
       end
 
+      # Delete a file from this backend
+      #
+      # @param [Sring] id           The id of the file
+      # @return [void]
       def delete(id)
         object(id).delete
       end
 
+      # Return an IO object for the uploaded file which can be used to read its
+      # content.
+      #
+      # @param [Sring] id           The id of the file
+      # @return [IO]                An IO object containing the file contents
       def open(id)
         Kernel.open(object(id).url_for(:read))
       end
 
+      # Return the entire contents of the uploaded file as a String.
+      #
+      # @param [String] id           The id of the file
+      # @return [String]             The file's contents
       def read(id)
         object(id).read
       rescue AWS::S3::Errors::NoSuchKey
         nil
       end
 
+      # Return the size in bytes of the uploaded file.
+      #
+      # @param [Sring] id           The id of the file
+      # @return [Integer]           The file's size
       def size(id)
         object(id).content_length
       rescue AWS::S3::Errors::NoSuchKey
         nil
       end
 
+      # Return whether the file with the given id exists in this backend.
+      #
+      # @param [Sring] id           The id of the file
+      # @return [Boolean]
       def exists?(id)
         object(id).exists?
       end
 
+      # Remove all files in this backend. You must confirm the deletion by
+      # passing the symbol `:confirm` as an argument to this method.
+      #
+      # @example
+      #   backend.clear!(:confirm)
+      # @raise [Refile::Confirm]     Unless the `:confirm` symbol has been passed.
+      # @param [:confirm] confirm    Pass the symbol `:confirm` to confirm deletion.
+      # @return [void]
       def clear!(confirm = nil)
         raise Refile::Confirm unless confirm == :confirm
         @bucket.objects.with_prefix(@prefix).delete_all
       end
 
+      # Return a presign signature which can be used to upload a file into this
+      # backend directly.
+      #
+      # @return [Refile::Signature]
       def presign
         id = RandomHasher.new.hash
         signature = @bucket.presigned_post(key: [*@prefix, id].join("/"))

data/lib/refile/custom_logger.rb

@@ -0,0 +1,46 @@
+require "rack/body_proxy"
+
+module Refile
+  # @api private
+  class CustomLogger
+    LOG_FORMAT = %(%s: [%s] %s "%s%s" %d %0.1fms\n)
+
+    def initialize(app, prefix, logger_proc)
+      @app, @prefix, @logger_proc = app, prefix, logger_proc
+    end
+
+    def call(env)
+      began_at = Time.now
+      status, header, body = @app.call(env)
+      body = Rack::BodyProxy.new(body) { log(env, status, began_at) }
+      [status, header, body]
+    end
+
+  private
+
+    def log(env, status, began_at)
+      now = Time.now
+      logger.info do
+        format(
+          LOG_FORMAT,
+          @prefix,
+          now.strftime("%F %T %z"),
+          env["REQUEST_METHOD"],
+          env["PATH_INFO"],
+          env["QUERY_STRING"].empty? ? "" : "?" + env["QUERY_STRING"],
+          status.to_s[0..3],
+          (now - began_at) * 1000
+        )
+      end
+    end
+
+    def logger
+      @logger ||= @logger_proc.call
+      @logger || fallback_logger
+    end
+
+    def fallback_logger
+      @fallback_logger ||= Logger.new(nil)
+    end
+  end
+end

data/lib/refile/file.rb

@@ -1,40 +1,71 @@
 module Refile
   class File
-    attr_reader :backend, :id
+    # @return [Backend] the backend the file is stored in
+    attr_reader :backend
 
+    # @return [String] the id of the file
+    attr_reader :id
+
+    # @api private
     def initialize(backend, id)
       @backend = backend
       @id = id
     end
 
+    # Reads from the file.
+    #
+    # @see http://www.ruby-doc.org/core-2.2.0/IO.html#method-i-read
+    #
+    # @return [String] The contents of the read chunk
     def read(*args)
       io.read(*args)
     end
 
+    # Returns whether there is more data to read. Returns true if the end of
+    # the data has been reached.
+    #
+    # @return [Boolean]
     def eof?
       io.eof?
     end
 
+    # Close the file object and release its file descriptor.
+    #
+    # @return [void]
     def close
       io.close
     end
 
+    # @return [Integer] the size of the file in bytes
     def size
       backend.size(id)
     end
 
+    # Remove the file from the backend.
+    #
+    # @return [void]
     def delete
       backend.delete(id)
     end
 
+    # @return [Boolean] whether the file exists in the backend
     def exists?
       backend.exists?(id)
     end
 
+    # @return [IO] an IO object which contains the contents of the file
     def to_io
       io
     end
 
+    # Downloads the file to a Tempfile on disk and returns this tempfile.
+    #
+    # @example
+    #   file = backend.upload(StringIO.new("hello"))
+    #   tempfile = file.download
+    #   File.read(tempfile.path) # => "hello"
+    #
+    # @return [Tempfile] a tempfile with the file's content
     def download
       return io if io.is_a?(Tempfile)
 

data/lib/refile/image_processing.rb

@@ -2,27 +2,67 @@ require "refile"
 require "mini_magick"
 
 module Refile
+  # Processes images via MiniMagick, resizing cropping and padding them.
   class ImageProcessor
+    # @param [Symbol] method        The method to invoke on {#call}
     def initialize(method)
       @method = method
     end
 
+    # Changes the image encoding format to the given format
+    #
+    # @see http://www.imagemagick.org/script/command-line-options.php#format
+    # @param [MiniMagick::Image] img      the image to convert
+    # @param [String] format              the format to convert to
+    # @return [void]
     def convert(img, format)
       img.format(format.to_s.downcase)
     end
 
+    # Resize the image to fit within the specified dimensions while retaining
+    # the original aspect ratio. Will only resize the image if it is larger
+    # than the specified dimensions. The resulting image may be shorter or
+    # narrower than specified in either dimension but will not be larger than
+    # the specified values.
+    #
+    # @param [MiniMagick::Image] img      the image to convert
+    # @param [#to_s] width                the maximum width
+    # @param [#to_s] height               the maximum height
+    # @return [void]
     def limit(img, width, height)
       img.resize "#{width}x#{height}>"
     end
 
+    # Resize the image to fit within the specified dimensions while retaining
+    # the original aspect ratio. The image may be shorter or narrower than
+    # specified in the smaller dimension but will not be larger than the
+    # specified values.
+    #
+    # @param [MiniMagick::Image] img      the image to convert
+    # @param [#to_s] width                the width to fit into
+    # @param [#to_s] height               the height to fit into
+    # @return [void]
     def fit(img, width, height)
       img.resize "#{width}x#{height}"
     end
 
-    # @ignore
-    #   rubocop:disable Metrics/AbcSize
-    #   FIXME: test and rewrite to simpler implementation!
+    # Resize the image so that it is at least as large in both dimensions as
+    # specified, then crops any excess outside the specified dimensions.
+    #
+    # The resulting image will always be exactly as large as the specified
+    # dimensions.
+    #
+    # By default, the center part of the image is kept, and the remainder
+    # cropped off, but this can be changed via the `gravity` option.
+    #
+    # @param [MiniMagick::Image] img      the image to convert
+    # @param [#to_s] width                the width to fill out
+    # @param [#to_s] height               the height to fill out
+    # @param [String] gravity             which part of the image to focus on
+    # @return [void]
+    # @see http://www.imagemagick.org/script/command-line-options.php#gravity
     def fill(img, width, height, gravity = "Center")
+      # FIXME: test and rewrite to simpler implementation!
       width = width.to_i
       height = height.to_i
       cols, rows = img[:dimensions]
@@ -46,6 +86,26 @@ module Refile
       end
     end
 
+    # resize the image to fit within the specified dimensions while retaining
+    # the original aspect ratio in the same way as {#fill}. unlike {#fill} it
+    # will, if necessary, pad the remaining area with the given color, which
+    # defaults to transparent where supported by the image format and white
+    # otherwise.
+    #
+    # the resulting image will always be exactly as large as the specified
+    # dimensions.
+    #
+    # by default, the image will be placed in the center but this can be
+    # changed via the `gravity` option.
+    #
+    # @param [minimagick::image] img      the image to convert
+    # @param [#to_s] width                the width to fill out
+    # @param [#to_s] height               the height to fill out
+    # @param [string] background          the color to use as a background
+    # @param [string] gravity             which part of the image to focus on
+    # @return [void]
+    # @see http://www.imagemagick.org/script/color.php
+    # @see http://www.imagemagick.org/script/command-line-options.php#gravity
     def pad(img, width, height, background = "transparent", gravity = "Center")
       img.combine_options do |cmd|
         cmd.thumbnail "#{width}x#{height}>"
@@ -59,6 +119,15 @@ module Refile
       end
     end
 
+    # Process the given file. The file will be processed via one of the
+    # instance methods of this class, depending on the `method` argument passed
+    # to the constructor on initialization.
+    #
+    # If the format is given it will convert the image to the given file format.
+    #
+    # @param [Tempfile] file        the file to manipulate
+    # @param [String] format        the file format to convert to
+    # @return [File]                the processed file
     def call(file, *args, format: nil)
       img = ::MiniMagick::Image.new(file.path)
       img.format(format.to_s.downcase) if format

data/lib/refile/rails.rb

@@ -2,13 +2,7 @@ require "refile"
 require "refile/rails/attachment_helper"
 
 module Refile
-  module AttachmentFieldHelper
-    def attachment_field(method, options = {})
-      self.multipart = true
-      @template.attachment_field(@object_name, method, objectify_options(options))
-    end
-  end
-
+  # @api private
   class Engine < Rails::Engine
     initializer "refile.setup", before: :load_environment_config do
       Refile.store ||= Refile::Backend::FileSystem.new(Rails.root.join("tmp/uploads/store").to_s)
@@ -19,7 +13,7 @@ module Refile
       end
 
       ActionView::Base.send(:include, Refile::AttachmentHelper)
-      ActionView::Helpers::FormBuilder.send(:include, AttachmentFieldHelper)
+      ActionView::Helpers::FormBuilder.send(:include, AttachmentHelper::FormBuilder)
     end
 
     initializer "refile.app" do

data/lib/refile/rails/attachment_helper.rb

@@ -1,10 +1,49 @@
 module Refile
+  # Rails view helpers which aid in using Refile from views.
   module AttachmentHelper
+    # Form builder extension
+    module FormBuilder
+      # @see AttachmentHelper#attachment_field
+      def attachment_field(method, options = {})
+        self.multipart = true
+        @template.attachment_field(@object_name, method, objectify_options(options))
+      end
+    end
+
+    # View helper which generates a url for an attachment. This generates a URL
+    # to the {Refile::App} which is assumed to be mounted in the Rails
+    # application.
+    #
+    # Optionally the name of a processor and a arguments to it can be appended.
+    #
+    # If the filename option is not given, the filename falls back to the
+    # `name`.
+    #
+    # The host defaults to {Refile.host}, which is useful for serving all
+    # attachments from a CDN. You can also override the host via the `host`
+    # option.
+    #
+    # Returns `nil` if there is no file attached.
+    #
+    # @example
+    #   attachment_url(@post, :document)
+    #
+    # @example With processor
+    #   attachment_url(@post, :image, :fill, 300, 300, format: "jpg")
+    #
+    # @param [Refile::Attachment] record   Instance of a class which has an attached file
+    # @param [Symbol] name                 The name of the attachment column
+    # @param [String, nil] filename        The filename to be appended to the URL
+    # @param [String, nil] format          A file extension to be appended to the URL
+    # @param [String, nil] host            Override the host
+    # @return [String, nil]                The generated URL
     def attachment_url(record, name, *args, filename: nil, format: nil, host: nil)
-      file = record.send(name)
+      attacher = record.send(:"#{name}_attacher")
+      file = attacher.get
       return unless file
 
-      filename ||= name.to_s
+      filename ||= attacher.basename || name.to_s
+      format ||= attacher.extension
 
       backend_name = Refile.backends.key(file.backend)
       host = host || Refile.host || request.base_url
@@ -15,6 +54,16 @@ module Refile
       ::File.join(host, main_app.refile_app_path, backend_name, *args.map(&:to_s), file.id.to_s, filename)
     end
 
+    # Generates an image tag for the given attachment, adding appropriate
+    # classes and optionally falling back to the given fallback image if there
+    # is no file attached.
+    #
+    # Returns `nil` if there is no file attached and no fallback specified.
+    #
+    # @param [String] fallback                   The path to an image asset to be used as a fallback
+    # @param [Hash] options                      Additional options for the image tag
+    # @see #attachment_url
+    # @return [ActiveSupport::SafeBuffer, nil]   The generated image tag
     def attachment_image_tag(record, name, *args, fallback: nil, format: nil, host: nil, **options)
       file = record.send(name)
       classes = ["attachment", record.class.model_name.singular, name, *options[:class]]
@@ -27,29 +76,38 @@ module Refile
       end
     end
 
-    # @ignore
-    #   rubocop:disable Metrics/AbcSize
-    def attachment_field(object_name, method, options = {})
+    # Generates a form field which can be used with records which have
+    # attachments. This will generate both a file field as well as a hidden
+    # field which tracks the id of the file in the cache before it is
+    # permanently stored.
+    #
+    # @param object_name                    The name of the object to generate a field for
+    # @param method                         The name of the field
+    # @param [Hash] options
+    # @option options [Object] object       Set by the form builder, currently required for direct/presigned uploads to work.
+    # @option options [Boolean] direct      If set to true, adds the appropriate data attributes for direct uploads with refile.js.
+    # @option options [Boolean] presign     If set to true, adds the appropriate data attributes for presigned uploads with refile.js.
+    # @return [ActiveSupport::SafeBuffer]   The generated form field
+    def attachment_field(object_name, method, object:, **options)
       options[:data] ||= {}
 
-      if options[:object]
-        attacher = options[:object].send(:"#{method}_attacher")
-        options[:accept] = attacher.accept
+      attacher = object.send(:"#{method}_attacher")
+      options[:accept] = attacher.accept
 
-        if options[:direct]
-          host = options[:host] || Refile.host || request.base_url
-          backend_name = Refile.backends.key(attacher.cache)
+      if options[:direct]
+        host = options[:host] || Refile.host || request.base_url
+        backend_name = Refile.backends.key(attacher.cache)
 
-          url = ::File.join(host, main_app.refile_app_path, backend_name)
-          options[:data].merge!(direct: true, as: "file", url: url)
-        end
+        url = ::File.join(host, main_app.refile_app_path, backend_name)
+        options[:data].merge!(direct: true, as: "file", url: url)
+      end
 
-        if options[:presigned] and attacher.cache.respond_to?(:presign)
-          options[:data].merge!(direct: true).merge!(attacher.cache.presign.as_json)
-        end
+      if options[:presigned] and attacher.cache.respond_to?(:presign)
+        options[:data].merge!(direct: true).merge!(attacher.cache.presign.as_json)
       end
-      hidden_field(object_name, :"#{method}_cache_id", options.slice(:object)) +
-        file_field(object_name, method, options)
+
+      html = hidden_field(object_name, method, value: attacher.data.to_json, object: object)
+      html + file_field(object_name, method, options)
     end
   end
 end