storage.rb

module Paperclip
  module Storage

    # The default place to store attachments is in the filesystem. Files on the local
    # filesystem can be very easily served by Apache without requiring a hit to your app.
    # They also can be processed more easily after they've been saved, as they're just
    # normal files. There is one Filesystem-specific option for has_attached_file.
    # * +path+: The location of the repository of attachments on disk. This can (and, in
    #   almost all cases, should) be coordinated with the value of the +url+ option to
    #   allow files to be saved into a place where Apache can serve them without
    #   hitting your app. Defaults to 
    #   ":rails_root/public/:attachment/:id/:style/:basename.:extension"
    #   By default this places the files in the app's public directory which can be served 
    #   directly. If you are using capistrano for deployment, a good idea would be to 
    #   make a symlink to the capistrano-created system directory from inside your app's 
    #   public directory.
    #   See Paperclip::Attachment#interpolate for more information on variable interpolaton.
    #     :path => "/var/app/attachments/:class/:id/:style/:basename.:extension"
    module Filesystem
      def self.extended base
      end
      
      def exists?(style = default_style)
        if original_filename
          File.exist?(path(style))
        else
          false
        end
      end

      # Returns representation of the data of the file assigned to the given
      # style, in the format most representative of the current storage.
      def to_file style = default_style
        @queued_for_write[style] || (File.new(path(style), 'rb') if exists?(style))
      end
      alias_method :to_io, :to_file

      def flush_writes #:nodoc:
        @queued_for_write.each do |style, file|
          file.close
          FileUtils.mkdir_p(File.dirname(path(style)))
          logger.info("[paperclip] saving #{path(style)}")
          FileUtils.mv(file.path, path(style))
          FileUtils.chmod(0644, path(style))
        end
        @queued_for_write = {}
      end

      def flush_deletes #:nodoc:
        @queued_for_delete.each do |path|
          begin
            logger.info("[paperclip] deleting #{path}")
            FileUtils.rm(path) if File.exist?(path)
          rescue Errno::ENOENT => e
            # ignore file-not-found, let everything else pass
          end
          begin
            while(true)
              path = File.dirname(path)
              FileUtils.rmdir(path)
            end
          rescue Errno::EEXIST, Errno::ENOTEMPTY, Errno::ENOENT, Errno::EINVAL, Errno::ENOTDIR
            # Stop trying to remove parent directories
          rescue SystemCallError => e
            logger.info("[paperclip] There was an unexpected error while deleting directories: #{e.class}")
            # Ignore it
          end
        end
        @queued_for_delete = []
      end
    end

    # Amazon's S3 file hosting service is a scalable, easy place to store files for
    # distribution. You can find out more about it at http://aws.amazon.com/s3
    # There are a few S3-specific options for has_attached_file:
    # * +s3_credentials+: Takes a path, a File, or a Hash. The path (or File) must point
    #   to a YAML file containing the +access_key_id+ and +secret_access_key+ that Amazon
    #   gives you. You can 'environment-space' this just like you do to your
    #   database.yml file, so different environments can use different accounts:
    #     development:
    #       access_key_id: 123...
    #       secret_access_key: 123... 
    #     test:
    #       access_key_id: abc...
    #       secret_access_key: abc... 
    #     production:
    #       access_key_id: 456...
    #       secret_access_key: 456... 
    #   This is not required, however, and the file may simply look like this:
    #     access_key_id: 456...
    #     secret_access_key: 456... 
    #   In which case, those access keys will be used in all environments. You can also
    #   put your bucket name in this file, instead of adding it to the code directly.
    #   This is useful when you want the same account but a different bucket for 
    #   development versus production.
    # * +s3_permissions+: This is a String that should be one of the "canned" access
    #   policies that S3 provides (more information can be found here:
    #   http://docs.amazonwebservices.com/AmazonS3/2006-03-01/RESTAccessPolicy.html#RESTCannedAccessPolicies)
    #   The default for Paperclip is "public-read".
    # * +s3_protocol+: The protocol for the URLs generated to your S3 assets. Can be either 
    #   'http' or 'https'. Defaults to 'http' when your :s3_permissions are 'public-read' (the
    #   default), and 'https' when your :s3_permissions are anything else.
    # * +s3_headers+: A hash of headers such as {'Expires' => 1.year.from_now.httpdate}
    # * +bucket+: This is the name of the S3 bucket that will store your files. Remember
    #   that the bucket must be unique across all of Amazon S3. If the bucket does not exist
    #   Paperclip will attempt to create it. The bucket name will not be interpolated.
    #   You can define the bucket as a Proc if you want to determine it's name at runtime.
    #   Paperclip will call that Proc with attachment as the only argument.
    # * +s3_host_alias+: The fully-qualified domain name (FQDN) that is the alias to the
    #   S3 domain of your bucket. Used with the :s3_alias_url url interpolation. See the
    #   link in the +url+ entry for more information about S3 domains and buckets.
    # * +url+: There are three options for the S3 url. You can choose to have the bucket's name
    #   placed domain-style (bucket.s3.amazonaws.com) or path-style (s3.amazonaws.com/bucket).
    #   Lastly, you can specify a CNAME (which requires the CNAME to be specified as
    #   :s3_alias_url. You can read more about CNAMEs and S3 at 
    #   http://docs.amazonwebservices.com/AmazonS3/latest/index.html?VirtualHosting.html
    #   Normally, this won't matter in the slightest and you can leave the default (which is
    #   path-style, or :s3_path_url). But in some cases paths don't work and you need to use
    #   the domain-style (:s3_domain_url). Anything else here will be treated like path-style.
    #   NOTE: If you use a CNAME for use with CloudFront, you can NOT specify https as your
    #   :s3_protocol; This is *not supported* by S3/CloudFront. Finally, when using the host
    #   alias, the :bucket parameter is ignored, as the hostname is used as the bucket name
    #   by S3.
    # * +path+: This is the key under the bucket in which the file will be stored. The
    #   URL will be constructed from the bucket and the path. This is what you will want
    #   to interpolate. Keys should be unique, like filenames, and despite the fact that
    #   S3 (strictly speaking) does not support directories, you can still use a / to
    #   separate parts of your file name.
    module S3
      def self.extended base
        require 'right_aws'
        base.instance_eval do
          @s3_credentials = parse_credentials(@options[:s3_credentials])
          @bucket         = @options[:bucket]         || @s3_credentials[:bucket]
          @bucket         = @bucket.call(self) if @bucket.is_a?(Proc)
          @s3_options     = @options[:s3_options]     || {}
          @s3_permissions = @options[:s3_permissions] || 'public-read'
          @s3_protocol    = @options[:s3_protocol]    || (@s3_permissions == 'public-read' ? 'http' : 'https')
          @s3_headers     = @options[:s3_headers]     || {}
          @s3_host_alias  = @options[:s3_host_alias]
          @url            = ":s3_path_url" unless @url.to_s.match(/^:s3.*url$/)
        end
        base.class.interpolations[:s3_alias_url] = lambda do |attachment, style|
          "#{attachment.s3_protocol}://#{attachment.s3_host_alias}/#{attachment.path(style).gsub(%r{^/}, "")}"
        end
        base.class.interpolations[:s3_path_url] = lambda do |attachment, style|
          "#{attachment.s3_protocol}://s3.amazonaws.com/#{attachment.bucket_name}/#{attachment.path(style).gsub(%r{^/}, "")}"
        end
        base.class.interpolations[:s3_domain_url] = lambda do |attachment, style|
          "#{attachment.s3_protocol}://#{attachment.bucket_name}.s3.amazonaws.com/#{attachment.path(style).gsub(%r{^/}, "")}"
        end
      end

      def s3
        @s3 ||= RightAws::S3.new(@s3_credentials[:access_key_id],
                                 @s3_credentials[:secret_access_key],
                                 @s3_options)
      end

      def s3_bucket
        @s3_bucket ||= s3.bucket(@bucket, true, @s3_permissions)
      end

      def bucket_name
        @bucket
      end

      def s3_host_alias
        @s3_host_alias
      end

      def parse_credentials creds
        creds = find_credentials(creds).stringify_keys
        (creds[ENV['RAILS_ENV']] || creds).symbolize_keys
      end
      
      def exists?(style = default_style)
        s3_bucket.key(path(style)) ? true : false
      end

      def s3_protocol
        @s3_protocol
      end

      # Returns representation of the data of the file assigned to the given
      # style, in the format most representative of the current storage.
      def to_file style = default_style
        @queued_for_write[style] || s3_bucket.key(path(style))
      end
      alias_method :to_io, :to_file

      def flush_writes #:nodoc:
        @queued_for_write.each do |style, file|
          begin
            logger.info("[paperclip] saving #{path(style)}")
            key = s3_bucket.key(path(style))
            key.data = file
            key.put(nil, @s3_permissions, {'Content-type' => instance_read(:content_type)}.merge(@s3_headers))
          rescue RightAws::AwsError => e
            raise
          end
        end
        @queued_for_write = {}
      end

      def flush_deletes #:nodoc:
        @queued_for_delete.each do |path|
          begin
            logger.info("[paperclip] deleting #{path}")
            if file = s3_bucket.key(path)
              file.delete
            end
          rescue RightAws::AwsError
            # Ignore this.
          end
        end
        @queued_for_delete = []
      end
      
      def find_credentials creds
        case creds
        when File
          YAML.load_file(creds.path)
        when String
          YAML.load_file(creds)
        when Hash
          creds
        else
          raise ArgumentError, "Credentials are not a path, file, or hash."
        end
      end
      private :find_credentials

    end

    # Store files in a database.
    # 
    # Usage is identical to the file system storage version, except:
    # 
    # 1. In your model specify the "database" storage option; for example:
    #   has_attached_file :avatar, :storage => :database
    # 
    # 2. The file will be stored in a column called [attachment name]_file (e.g. "avatar_file") by default.
    # 
    # To specify a different column name, use :column, like this:
    #   has_attached_file :avatar, :storage => :database, :column => 'avatar_data'
    # 
    # If you have defined different styles, these files will be stored in additional columns called
    # [attachment name]_[style name]_file (e.g. "avatar_thumb_file") by default.
    # 
    # To specify different column names for styles, use :column in the style definition, like this:
    #   has_attached_file :avatar,
    #                     :storage => :database,
    #                     :styles => { 
    #                       :medium => {:geometry => "300x300>", :column => 'medium_file'},
    #                       :thumb => {:geometry => "100x100>", :column => 'thumb_file'}
    #                     }
    # 
    # 3. You need to create these new columns in your migrations or you'll get an exception. Example:
    #   add_column :users, :avatar_file, :binary
    #   add_column :users, :avatar_medium_file, :binary
    #   add_column :users, :avatar_thumb_file, :binary
    # 
    # Note the "binary" migration will not work for the LONGBLOB type in MySQL for the
    # file_contents column. You may need to craft a SQL statement for your migration,
    # depending on which database server you are using. Here's an example migration for MySQL:
    #   execute 'ALTER TABLE users ADD COLUMN avatar_file LONGBLOB'
    #   execute 'ALTER TABLE users ADD COLUMN avatar_medium_file LONGBLOB'
    #   execute 'ALTER TABLE users ADD COLUMN avatar_thumb_file LONGBLOB'
    # 
    # 4. To avoid performance problems loading all of the BLOB columns every time you access
    # your ActiveRecord object, a class method is provided on your model called
    # “select_without_file_columns_for.” This is set to a :select scope hash that will
    # instruct ActiveRecord::Base.find to load all of the columns except the BLOB/file data columns.
    # 
    # If you’re using Rails 2.3, you can specify this as a default scope:
    #   default_scope select_without_file_columns_for(:avatar)
    # 
    # Or if you’re using Rails 2.1 or 2.2 you can use it to create a named scope:
    #   named_scope :without_file_data, select_without_file_columns_for(:avatar)
    # 
    # 5. By default, URLs will be set to this pattern:
    #   /:relative_root/:class/:attachment/:id?style=:style
    # 
    # Example:
    #   /app-root-url/users/avatars/23?style=original
    # 
    # The idea here is that to retrieve a file from the database storage, you will need some
    # controller's code to be executed.
    #     
    # Once you pick a controller to use for downloading, you can add this line
    # to generate the download action for the default URL/action (the plural attachment name),
    # "avatars" in this example:
    #   downloads_files_for :user, :avatar
    # 
    # Or you can write a download method manually if there are security, logging or other
    # requirements.
    # 
    # If you prefer a different URL for downloading files you can specify that in the model; e.g.:
    #   has_attached_file :avatar, :storage => :database, :url => '/users/show_avatar/:id/:style'
    # 
    # 6. Add a route for the download to the controller which will handle downloads, if necessary.
    # 
    # The default URL, /:relative_root/:class/:attachment/:id?style=:style, will be matched by
    # the default route: :controller/:action/:id
    # 
    module Database
      def self.extended base
        base.instance_eval do
          @file_columns = @options[:file_columns]
          if @url == base.class.default_options[:url]
            @url = ":relative_root/:class/:attachment/:id?style=:style"
          end
        end
        base.class.interpolations[:relative_root] = lambda do |attachment, style|
          begin
            if ActionController::AbstractRequest.respond_to?(:relative_url_root)
              relative_url_root = ActionController::AbstractRequest.relative_url_root
            end
          rescue NameError
          end
          if !relative_url_root && ActionController::Base.respond_to?(:relative_url_root)
            relative_url_root = ActionController::Base.relative_url_root
          end
          relative_url_root
        end
        ActiveRecord::Base.logger.info("[paperclip] Database Storage Initalized.")
      end

      def column_for_style style
        @file_columns[style.to_sym]
      end
        
      def instance_read_file(style)
        column = column_for_style(style)
        responds = instance.respond_to?(column)
        cached = self.instance_variable_get("@_#{column}")
        return cached if cached
        # The blob attribute will not be present if select_without_file_columns_for was used
        instance.reload :select => column if !instance.attribute_present?(column) && !instance.new_record?
        instance.send(column) if responds
      end

      def instance_write_file(style, value)
        setter = :"#{column_for_style(style)}="
        responds = instance.respond_to?(setter)
        self.instance_variable_set("@_#{setter.to_s.chop}", value)
        instance.send(setter, value) if responds
      end

      def file_contents(style = default_style)
        instance_read_file(style)
      end
      alias_method :data, :file_contents

      def exists?(style = default_style)
        !file_contents(style).nil?
      end

      # Returns representation of the data of the file assigned to the given
      # style, in the format most representative of the current storage.
      def to_file style = default_style
        if @queued_for_write[style]
          @queued_for_write[style]
        elsif exists?(style)
          tempfile = Tempfile.new instance_read(:file_name)
          tempfile.write file_contents(style)
          tempfile
        else
          nil
        end
      end
      alias_method :to_io, :to_file

      def path style = default_style
        original_filename.nil? ? nil : column_for_style(style)
      end

      def assign uploaded_file

        # Assign standard metadata attributes and perform post processing as usual
        super

        # Save the file contents for all styles in ActiveRecord immediately (before save)
        @queued_for_write.each do |style, file|
          instance_write_file(style, file.read)
        end
        
        # If we are assigning another Paperclip attachment, then fixup the
        # filename and content type; necessary since Tempfile is used in to_file
        if uploaded_file.is_a?(Paperclip::Attachment)
          instance_write(:file_name,       uploaded_file.instance_read(:file_name))
          instance_write(:content_type,    uploaded_file.instance_read(:content_type))
        end
      end

      def queue_existing_for_delete
        [:original, *@styles.keys].uniq.each do |style|
          instance_write_file(style, nil)
        end
        instance_write(:file_name, nil)
        instance_write(:content_type, nil)
        instance_write(:file_size, nil)
        instance_write(:updated_at, nil)
      end

      def flush_writes
        @queued_for_write = {}
      end

      def flush_deletes
        @queued_for_delete = []
      end
      
      module ControllerClassMethods
        def self.included(base)
          base.extend(self)
        end
        def downloads_files_for(model, attachment)
          define_method("#{attachment.to_s.pluralize}") do
            model_record = Object.const_get(model.to_s.camelize.to_sym).find(params[:id])
            style = params[:style] ? params[:style] : 'original'
            send_data model_record.send(attachment).file_contents(style),
                      :filename => model_record.send("#{attachment}_file_name".to_sym),
                      :type => model_record.send("#{attachment}_content_type".to_sym)
          end
        end
      end
    end

  end
end