attachment_saver 1.0.0

data/.gitignore

@@ -0,0 +1,3 @@
+test/log/*
+test/tmp/*
+test/attachment_saver_test_sqlite.db

data/MIT-LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2007 Will Bryant, Sekuda Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README

@@ -0,0 +1,137 @@
+AttachmentSaver
+===============
+
+This plugin implements attachment storage and processing, integrated with
+ActiveRecord models and Ruby CGI/Rails-style uploads.  Image processing
+operations including a number of different resizing & thumbnailing modes are
+provided, and the architecture simplifies clean implementation of other types
+of processing.  Errors are carefully handled to minimize the possibility of
+broken uploads leaving incomplete or corrupt data.
+
+RMagick, MiniMagick, and ImageScience image processors are supported.
+
+
+Compatibility
+=============
+
+Currently tested against Rails 3.2.13 and 3.1.8, on Ruby 1.8.7 and 2.0.0p0.
+Was also tested compatible with 2.3.14 and 3.0.17.
+
+
+Examples
+========
+
+A 'dumb' attachment store that saves minimal info
+-------------------------------------------------
+
+# in your model:
+class SomeModel
+  saves_attachment
+end
+
+# in your database schema:
+create_table :some_model do |t|
+  t.string   :storage_key,         :null => false
+end
+
+# in your new/update forms:
+file_field :some_model, :uploaded_data
+
+# no special controller handling is required.
+
+
+A 'dumb' attachment store that saves full file info automatically
+-----------------------------------------------------------------
+
+# as for above, but in the schema:
+create_table :some_model do |t|
+  t.string   :storage_key,         :null => false
+  t.string   :original_filename,   :null => false # as sent by the user's browser, with IE path removed
+  t.string   :content_type,        :null => false # as sent by the user's browser
+  t.integer  :size,                :null => false # file size in bytes
+  t.timestamps
+end
+
+
+An image store that automatically saves width and height and corrects mime types & file extensions
+--------------------------------------------------------------------------------------------------
+
+# in your models:
+class Image
+  saves_attachment :processor => 'rmagick'
+end
+
+# in your database schema:
+create_table :photos do |t|
+  t.string   :storage_key,         :null => false
+  t.string   :original_filename,   :null => false # as sent by the user's browser, with IE path removed
+  t.string   :content_type,        :null => false # corrected if the user's browser sent a mime type that didn't match the image
+  t.integer  :size,                :null => false # file size in bytes
+  t.integer  :width,               :null => false # set by the image processors
+  t.integer  :height,              :null => false # ditto
+  t.timestamps
+end
+
+
+An image store that resizes images to produce thumbnails etc.
+-------------------------------------------------------------
+
+# in your models:
+class Photo
+  saves_attachment :processor => 'RMagick', :derived_class => 'Thumbnail',
+    :formats => {:page_width => '520x',                # ImageMagick-style format string
+                 :small => [:shrink_to_fit, 250, 250], # or more explicit [operation, width, height] format
+                 :nav =>   [:cover_and_crop, 50,  50]} # lots of useful resize and/or crop modes available
+end
+
+class Thumbnail
+  saves_attachment
+end
+
+# in your database schema:
+create_table :photos do |t|
+  t.string   :storage_key,         :null => false
+  t.string   :original_filename,   :null => false # as sent by the user's browser, with IE path removed
+  t.string   :content_type,        :null => false # corrected if the user's browser sent a mime type that didn't match the image
+  t.integer  :size,                :null => false # file size in bytes
+  t.integer  :width,               :null => false # set by the image processors
+  t.integer  :height,              :null => false # ditto
+  t.timestamps
+end
+
+create_table :thumbnails do |t|
+  t.string   :original_type,       :null => false # multiple models can save their derived images as thumbnails
+  t.integer  :original_id,         :null => false
+  t.string   :format_name,         :null => false # from your :formats - eg. 'small', 'nav'
+  t.string   :storage_key,         :null => false # still required (but will be based on the original's, for convenience)
+  t.string   :content_type,        :null => false # these fields are optional (as they are for Photo)
+  t.integer  :size,                :null => false
+  t.integer  :width,               :null => false # but width and height are generally needed for layout
+  t.integer  :height,              :null => false
+  t.timestamps
+end
+
+
+A custom image-processing format using your image-processor's features
+----------------------------------------------------------------------
+
+# in a file in your lib/ directory that's required in somewhere:
+module AttachmentSaver::Processors::RMagick::Operations # or MiniMagick::Operations or ImageScience::Operations - see lib/processors
+  # this module is mixed in to the actual image objects built by the processor, so you can call its' methods directly
+  def wavy_black_and_white(wave_height, wave_length, &block)
+    # RMagick returns the new object; MiniMagick acts on the same object (so you must dup); ImageScience yields; so, look at the existing lib/processors to see the appropriate pattern
+    image = quantize(256, Magick::GRAYColorspace).wave(wave_height, wave_length)
+
+    # mix the operations in to the new image, for reuse
+    image.extend Operations
+
+    # yield up the new image
+    block.call(image)
+  end
+end
+
+# in your models:
+class Image
+  saves_attachment :processor => 'RMagick', :derived_class => 'SpecialImage',
+    :formats => {:flashback => [:wavy_and_black_and_white, 10,  200]}
+end

data/Rakefile

@@ -0,0 +1,16 @@
+#!/usr/bin/env rake
+
+require 'bundler/gem_tasks'
+require 'rake'
+require 'rake/testtask'
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test the columns_on_demand plugin.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/*_test.rb'
+  t.verbose = true
+end

data/attachment_saver.gemspec

@@ -0,0 +1,41 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/attachment_saver/version', __FILE__)
+
+spec = Gem::Specification.new do |gem|
+  gem.name         = 'attachment_saver'
+  gem.version      = AttachmentSaver::VERSION
+  gem.summary      = "Saves attachments in files, models, or columns."
+  gem.description  = <<-EOF
+This plugin implements attachment storage and processing, integrated with
+ActiveRecord models and Ruby CGI/Rails-style uploads.  Image processing
+operations including a number of different resizing & thumbnailing modes are
+provided, and the architecture simplifies clean implementation of other types
+of processing.  Errors are carefully handled to minimize the possibility of
+broken uploads leaving incomplete or corrupt data.
+
+RMagick, MiniMagick, and ImageScience image processors are supported.
+
+
+Compatibility
+=============
+
+Currently tested against Rails 3.2.13 and 3.1.8, on Ruby 1.8.7 and 2.0.0p0.
+Was also tested compatible with 2.3.14 and 3.0.17.
+EOF
+  gem.has_rdoc     = false
+  gem.author       = "Will Bryant"
+  gem.email        = "will.bryant@gmail.com"
+  gem.homepage     = "http://github.com/willbryant/attachment_saver"
+  
+  gem.executables  = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  gem.files        = `git ls-files`.split("\n")
+  gem.test_files   = `git ls-files -- {test,spec,features}/*`.split("\n")
+  gem.require_path = "lib"
+  
+  gem.add_dependency "activerecord"
+  gem.add_development_dependency "rake"
+  gem.add_development_dependency "image_science"
+  gem.add_development_dependency "rmagick"
+  gem.add_development_dependency "mini_magick"
+  gem.add_development_dependency "sqlite3"
+end

data/init.rb

@@ -0,0 +1 @@
+require 'attachment_saver'

data/lib/attachment_saver.rb

@@ -0,0 +1,171 @@
+require 'attachment_saver_errors'
+require 'misc/file_size'
+require 'tmpdir'
+
+module AttachmentSaver
+  module BaseMethods
+    def saves_attachment(options = {})
+      extend ClassMethods
+      include InstanceMethods
+      
+      class_attribute :attachment_options
+      self.attachment_options = options
+
+      attachment_options[:datastore] ||= 'file_system'
+      require "datastores/#{attachment_options[:datastore].to_s.underscore}"
+      include DataStores.const_get(attachment_options[:datastore].to_s.classify)
+      before_validation :before_validate_attachment # this callback does things like override the content-type based on the actual file data
+      before_save       :save_attachment # this callback is where most of the goodness happens; note that it runs before save, so that it prevents the record being saved if processing raises; this is why our filenames can't be based on the instance ID
+      after_save        :tidy_attachment
+      after_save        :close_open_file
+      after_destroy     :delete_attachment
+
+      if attachment_options[:formats] && reflect_on_association(:formats).nil? # this allows you to override our definition of the sizes association by simply defining it before calling has_attachment
+        attachment_options[:processor] ||= 'image_science'
+        attachment_options[:derived_class] ||= DerivedImage
+        has_many :formats, :as => :original, :class_name => attachment_options[:derived_class].to_s, :dependent => :destroy
+        after_save      :save_updated_derived_children
+      end
+      
+      if attachment_options[:processor]
+        unless Object.const_defined?(:Processors) && Processors.const_defined?(attachment_options[:processor].to_s.classify)
+          require "processors/#{attachment_options[:processor].to_s.underscore}"
+        end
+        include Processors.const_get(attachment_options[:processor].to_s.classify)
+      end
+    end
+  end
+  
+  module ClassMethods
+    # currently present only for the benefit of extensions
+  end
+  
+  module InstanceMethods
+    def uploaded_data=(uploaded)
+      # we don't go ahead and process the upload just yet - in particular, we need to wait
+      # until we have all the attributes, and then until validation passes - so we just retain
+      # the data or file reference for now.
+      if uploaded.is_a?(String) # we allow people to upload into the file field using a normal input element (eg. a textarea)
+        return if uploaded.blank? # this handles the case when a form has a file field but no file is selected - most browsers submit an empty string then (annoyingly)
+        @uploaded_data = uploaded
+        @uploaded_file = nil
+      elsif uploaded.is_a?(StringIO)
+        uploaded.rewind
+        @uploaded_data = uploaded.read
+        @uploaded_file = nil
+      elsif uploaded
+        @uploaded_data = nil
+        @uploaded_file = uploaded
+      else
+        @uploaded_data = @uploaded_file = @save_upload = nil
+        return
+      end
+      @save_upload = true
+
+      self.size =              uploaded.size                                      if respond_to?(:size=)
+      self.content_type =      uploaded.content_type.strip.downcase               if respond_to?(:content_type=) && uploaded.respond_to?(:content_type)
+      self.original_filename = trim_original_filename(uploaded.original_filename) if respond_to?(:original_filename=) && uploaded.respond_to?(:original_filename)
+    end
+    
+    def uploaded_data
+      if @uploaded_data.nil?
+        if @uploaded_file.nil?
+          nil
+        else
+          @uploaded_file.rewind
+          @uploaded_file.read
+        end
+      else
+        @uploaded_data
+      end
+    end
+    
+    def uploaded_file
+      unless @uploaded_data.nil?
+        # if we have a processor, we need to get the uploaded data into a file at some point
+        # so it can be processed.  we take advantage of the fact that our file backend knows
+        # how to hardlink temporary files into their final location (rather than copying) to
+        # simplify things without introducing an extra file copy (so long as we put the temp
+        # file in the right place); of course, for non-file backends, this file will be only
+        # temporary in any case - so doing this here represents no extra overhead (remember,
+        # uploaded files over the magic size built into the CGI module are saved to files in
+        # the first place, so we know that the overhead here is minimal anyway).
+        FileUtils.mkdir_p(tempfile_directory)
+        temp = Tempfile.new("asutemp", tempfile_directory)
+        temp.binmode
+        temp.write(@uploaded_data)
+        temp.flush
+        @uploaded_file = temp
+        @uploaded_data = nil
+      end
+      @uploaded_file
+    end
+    
+    def uploaded_file_path
+      uploaded_file.respond_to?(:tempfile) ?
+        uploaded_file.tempfile.path : # rails 3
+        uploaded_file.path # rails 2
+    end
+    
+    def close_open_file
+      @uploaded_file.close if @uploaded_file && @uploaded_file.respond_to?(:close)
+      @uploaded_file.tempfile.close if @uploaded_file.respond_to?(:tempfile) && @uploaded_file.tempfile.respond_to?(:close)
+    end
+    
+    def before_validate_attachment # overridden by the processors (and/or by the class we're mixed into)
+      # when you write code in here that needs to access the file, use the uploaded_file method to get it
+    end
+    
+    def process_attachment? # called by the datastores, overridden by the processors (and/or by the class we're mixed into)
+      false
+    end
+    
+    def process_attachment_with_wrapping(filename)
+      process_attachment(filename)
+    rescue AttachmentProcessorError
+      raise # pass any exceptions of the correct type (which anything eminating from our processors should be) straight
+    rescue Exception => ex
+      raise AttachmentProcessorError, "#{ex.class}: #{ex.message}", ex.backtrace # wrap anything else
+    end
+    
+    def tempfile_directory # called by uploaded_file, overridden by the file datastore, which sets it to the base dir that it saves into itself, so that the files are put on the same partition & so can be directly hardlinked rather than copied
+      Dir.tmpdir
+    end
+    
+    def file_extension=(extension) # used by processors to override the original extension
+      @file_extension = extension
+    end
+      
+    def file_extension
+      extension = @file_extension
+      extension = AttachmentSaver::split_filename(original_filename).last if extension.blank? && respond_to?(:original_filename) && !original_filename.blank?
+      extension = 'bin' if extension.blank?
+      extension
+    end
+    
+    def trim_original_filename(filename)
+      return filename.strip if attachment_options[:keep_original_filename_path]
+      filename.gsub(/^.*(\\|\/)/, '').strip
+    end
+      
+    def image_size
+      width.nil? || height.nil? ? nil : "#{width}x#{height}"
+    end
+    
+    def save_updated_derived_children # rails automatically saves children on create, but not on update; when uploading a new image, we don't want to save them until we've finished processing in case that raises & causes a rollback, so we have to save them ourselves later
+      @updated_derived_children.each(&:save!) unless @updated_derived_children.blank?
+      @updated_derived_children = nil
+    end
+  end
+  
+  def self.split_filename(filename)
+    pos = filename.rindex('.')
+    if pos.nil?
+      return [filename, nil]
+    else
+      return [filename[0..pos - 1], filename[pos + 1..-1]]
+    end
+  end
+end
+
+ActiveRecord::Base.send(:extend, AttachmentSaver::BaseMethods)

data/lib/attachment_saver/version.rb

@@ -0,0 +1,3 @@
+module AttachmentSaver
+  VERSION = '1.0.0'
+end

data/lib/attachment_saver_errors.rb

@@ -0,0 +1,3 @@
+class AttachmentSaverError < StandardError; end
+class AttachmentDataStoreError < AttachmentSaverError; end
+class AttachmentProcessorError < AttachmentSaverError; end

data/lib/datastores/file_system.rb

@@ -0,0 +1,189 @@
+require 'fileutils'
+require 'tempfile'
+require 'attachment_saver_errors'
+
+class FileSystemAttachmentDataStoreError < AttachmentDataStoreError; end
+
+module AttachmentSaver
+  module DataStores
+    module FileSystem
+      RETRIES = 100 # max attempts at finding a unique storage key.  very rare to have to retry at all, so if it fails after 100 attempts, something's seriously wrong.
+      
+      def self.included(base)
+        base.attachment_options[:storage_directory] ||= File.join(Rails.root, 'public') # this is the part of the full filename that _doesn't_ form part of the HTTP path to the files
+        base.attachment_options[:storage_path_base] ||= Rails.env == 'production' ? base.table_name : File.join(Rails.env, base.table_name) # and this is the part that does.
+        base.attachment_options[:filter_filenames] = Regexp.new(base.attachment_options[:filter_filenames]) if base.attachment_options[:filter_filenames].is_a?(String) # may be nil, in which case the normal randomised-filename scheme is used instead of the filtered-original-filename scheme
+        base.attachment_options[:file_permissions] = 0664 unless base.attachment_options.has_key?(:file_permissions) # we don't use || as nil is a meaningful value for this option - it means to not explicitly set the file permissions
+      end
+      
+      def save_attachment
+        return unless @save_upload # this method is called every time the model is saved, not just when a new file has been uploaded
+        
+        old_storage_key = storage_key
+        @old_filenames ||= []
+        @old_filenames << storage_filename unless storage_key.blank?
+        self.storage_key = nil
+        define_finalizer
+        
+        # choose a storage key (ie. path/filename) and try it; note that we assign a new 
+        # storage key for every new upload, not just every new AR model, so that the URL
+        # changes each time, which allows long/infinite cache TTLs & CDN support.
+        begin
+          if derive_storage_key?
+            begin
+              # for thumbnail/other derived images, we base the filename on the original 
+              # (parent) image + the derived format name
+              self.storage_key = derive_storage_key_from(original)
+              save_attachment_to(storage_filename)
+            rescue Errno::EEXIST # if clobbering pre-existing files (only possible if using filtered_filenames, and even then only if creating new derived images explicitly at some time other than during processing the parent), we still don't want to write into them, we want to use a new file & an atomic rename
+              retries = 0
+              begin
+                self.storage_key = derive_storage_key_from(original, retries + 2) # +2 is arbitrary, I just think it's more human-friendly to go from xyz_thumb.jpg to xyz_thumb2.jpg rather than xyz_thumb0.jpg
+                save_attachment_to(storage_filename)
+              rescue Errno::EEXIST
+                raise if (retries += 1) >= RETRIES # in fact it would be very unusual to ever need to retry at all, let alone multiple times; if you hit this, your operating system is actually broken (or someone's messed with storage_filename)
+                retry # pick a new random name and try again
+              end
+            end
+          else
+            retries = 0
+            begin
+              if self.class.attachment_options[:filter_filenames] && respond_to?(:original_filename) && !original_filename.blank?
+                # replace all the original_filename characters not included in the keep_filenames character list with underscores, leave the rest; store in randomized directories to avoid naming clashes
+                basename = AttachmentSaver::split_filename(original_filename).first.gsub(self.class.attachment_options[:filter_filenames], '_')
+                self.storage_key = File.join(self.class.attachment_options[:storage_path_base], random_segment(3), random_segment(3), "#{basename}.#{file_extension}")
+              else
+                # for new files under this option, we pick a random name (split into 3 parts - 2 directories and a file - to help keep the directories at manageable sizes), and never overwrite
+                # this is the default setting, and IMHO the most best choice for most apps; the original filenames are typically pretty meaningless
+                self.storage_key = File.join(self.class.attachment_options[:storage_path_base], random_segment(2), random_segment(2), "#{random_segment(6)}.#{file_extension}") # in fact just two random characters in the last part would be ample, since 36^(2+2+2) = billions, but we sacrifice 4 more characters of URL shortness for the benefit of ppl saving the assets to disk without renaming them
+              end
+              save_attachment_to(storage_filename)
+            rescue Errno::EEXIST
+              raise if (retries += 1) >= RETRIES # in fact it would be very unusual to ever need to retry at all, let alone multiple times; if you hit this, your operating system is actually broken (or someone's messed with storage_filename)
+              retry # pick a new random name and try again
+            end
+          end
+
+          # successfully written to file; process the attachment
+          process_attachment_with_wrapping(storage_filename) if process_attachment?
+          # if there's exceptions later (ie. during save itself) that prevent the record from being saved, the finalizer will clean up the file
+
+          @save_upload = nil
+        rescue Exception => ex
+          FileUtils.rm_f(storage_filename) unless storage_key.blank? || ex.is_a?(Errno::EEXIST)
+          self.storage_key = old_storage_key
+          @old_filenames.pop unless old_storage_key.blank?
+          raise if ex.is_a?(AttachmentSaverError)
+          raise FileSystemAttachmentDataStoreError, "#{ex.class}: #{ex.message}", ex.backtrace
+        end
+      end
+      
+      def storage_filename
+        File.join(self.class.attachment_options[:storage_directory], storage_key)
+      end
+      
+      def in_storage?
+        File.exists?(storage_filename)
+      end
+      
+      def public_path
+        "/#{storage_key.tr('\\', '/')}" # the tr is just for windows' benefit
+      end
+    
+      def reprocess!
+        raise "this attachment already has a file open to process" unless uploaded_file.nil?
+        process_attachment_with_wrapping(storage_filename) if process_attachment?
+        save!
+      end
+      
+    protected
+      RND_CHARS = ('a'..'z').to_a + ('0'..'9').to_a # we generously support case-insensitive filesystems.  aren't we nice?
+      
+      def tempfile_directory
+        # tempfiles go under the same directory as the actual files will, so they'll be on the same filesystem and thus hardlinkable
+        File.join(self.class.attachment_options[:storage_directory], self.class.attachment_options[:storage_path_base])
+      end
+      
+      def random_segment(chars)
+        Array.new(chars) .collect { RND_CHARS[rand(RND_CHARS.length)] } .join
+      end
+      
+      def derive_storage_key?
+        respond_to?(:format_name) && !format_name.blank? && respond_to?(:original) && !original.nil? &&
+          original.class.included_modules.include?(FileSystem) &&
+          original.respond_to?(:storage_key) && !original.storage_key.blank?
+      end
+      
+      def derive_storage_key_from(original, suffix = nil)
+        basename, extension = AttachmentSaver::split_filename(original.storage_key)
+        "#{basename}_#{format_name}#{suffix}.#{file_extension}"
+      end
+      
+      def tidy_attachment # called after_save
+        FileUtils.rm_f(@old_filenames)   unless @old_filenames.blank? || self.class.attachment_options[:keep_old_files]
+        ObjectSpace.undefine_finalizer(self)
+      rescue Exception => ex
+        raise FileSystemAttachmentDataStoreError, "#{ex.class}: #{ex.message}", ex.backtrace
+      end
+      
+      def delete_attachment # called after_destroy
+        FileUtils.rm_f(storage_filename) unless storage_key.blank?
+        FileUtils.rm_f(@old_filenames)   unless @old_filenames.blank? || self.class.attachment_options[:keep_old_files]
+        ObjectSpace.undefine_finalizer(self)
+      rescue Exception => ex
+        raise FileSystemAttachmentDataStoreError, "#{ex.class}: #{ex.message}", ex.backtrace
+      end
+      
+      def define_finalizer
+        ObjectSpace.undefine_finalizer(self)
+        ObjectSpace.define_finalizer(self, lambda { # called on GC finalization if a save was attempted at some point but wasn't completed (presumably because an exception was raised)
+          FileUtils.rm_f(storage_filename)   if new_record? && !storage_key.blank?
+          FileUtils.rm_f(@old_filenames) unless @old_filenames.blank? || self.class.attachment_options[:keep_old_files]
+        })
+      end
+      
+      # attempts to write the uploaded data/file to the given filename, setting the file
+      # open flags so that Errno::EEXIST will be thrown if the file already exists.
+      # creates any missing parent directories.
+      def save_attachment_to(filename)
+        binary_mode = defined?(File::BINARY) ? File::BINARY : 0
+        open_mode = File::CREAT | File::RDWR | File::EXCL | binary_mode
+        
+        FileUtils.mkdir_p(File.dirname(filename))
+        
+        if @uploaded_data
+          File.open(filename, open_mode, self.class.attachment_options[:file_permissions]) do |fout| 
+            fout.write(@uploaded_data)
+          end
+        else
+          # typically, the temp file we get given when a user uploads a file is on the same
+          # volume as the directory we're storing to, and since the temporary uploaded files
+          # aren't changed ever - they're unlinked when we finish processing the request - we
+          # can just efficiently hardlink it instead of wasting time & IO making an independent
+          # copy of it.  of course, we still need to make a copied file if it isn't on the same
+          # volume, if the destination file already exists, if we're on an OS that doesn't
+          # support hardlinks, or if the 'uploaded' file isn't a temporary uploaded file at all
+          # (presumably someone running an import job) - we don't want any nasty semantics 
+          # surprises with non-uploaded files!
+          uploaded_tempfile = @uploaded_file.respond_to?(:tempfile) ? @uploaded_file.tempfile : @uploaded_file
+          if uploaded_tempfile.is_a?(Tempfile)
+            uploaded_tempfile.flush
+            begin
+              FileUtils.ln(uploaded_tempfile.path, filename)
+              (File.chmod(self.class.attachment_options[:file_permissions], uploaded_tempfile.path) rescue nil) unless self.class.attachment_options[:file_permissions].nil? 
+              return # successfully linked, we're done
+            rescue
+              # ignore and fall through do, it the long way
+            end
+          end
+          File.open(filename, open_mode, self.class.attachment_options[:file_permissions]) do |fout|
+            @uploaded_file.rewind
+            while data = @uploaded_file.read(4096) 
+              fout.write(data)
+            end
+          end
+        end
+      end
+    end
+  end
+end