dis 1.2.0 → 1.3.1

data/lib/dis/model/data.rb

@@ -7,12 +7,18 @@ module Dis
     # Facilitates communication between the model and the storage,
     # and holds any newly assigned data before the record is saved.
     class Data
+      # @param record [ActiveRecord::Base] the model instance
+      # @param raw [File, IO, String, nil] newly assigned data
       def initialize(record, raw = nil)
         @record = record
         @raw = raw
       end
 
       # Returns true if two Data objects represent the same data.
+      #
+      # @param other [Dis::Model::Data, #read, Object] the object to
+      #   compare
+      # @return [Boolean]
       def ==(other)
         if !raw? && other.is_a?(self.class) && !other.changed?
           content_hash == other.content_hash
@@ -24,24 +30,33 @@ module Dis
       end
 
       # Returns true if data exists either in memory or in storage.
+      #
+      # @return [Boolean]
       def any?
         raw? || stored?
       end
 
       # Returns the data as a binary string.
+      #
+      # @return [String, nil]
       def read
         @read ||= read_from(closest)
       end
 
-      # Will be true if data has been explicitely set.
+      # Will be true if data has been explicitly set.
+      #
+      # @return [Boolean]
       #
+      # @example
       #   Dis::Model::Data.new(record).changed? # => false
-      #   Dis::Model::Data.new(record, new_file).changed? # => true
+      #   Dis::Model::Data.new(record, file).changed? # => true
       def changed?
         raw?
       end
 
-      # Returns the length of the data.
+      # Returns the length of the data in bytes.
+      #
+      # @return [Integer]
       def content_length
         if raw? && raw.respond_to?(:length)
           raw.length
@@ -50,9 +65,13 @@ module Dis
         end
       end
 
-      # Expires a data object from the storage if it's no longer being used
-      # by existing records. This is triggered from callbacks on the record
-      # whenever they are changed or destroyed.
+      # Expires a data object from the storage if it's no longer
+      # being used by existing records. This is triggered from
+      # callbacks on the record whenever they are changed or
+      # destroyed.
+      #
+      # @param hash [String] the content hash to expire
+      # @return [void]
       def expire(hash)
         return if hash.blank?
 
@@ -63,37 +82,53 @@ module Dis
         end
       end
 
-      # Stores the data. Returns a hash of the content for reference.
+      # Stores the data and returns the content hash.
+      #
+      # @return [String] the SHA1 content hash
+      # @raise [Dis::Errors::NoDataError] if no data has been
+      #   assigned
       def store!
         raise Dis::Errors::NoDataError unless raw?
 
         Dis::Storage.store(storage_type, raw)
       end
 
-      # Clears cached data and tempfiles, allowing them to be garbage
-      # collected. Subsequent calls to read or tempfile will re-fetch.
+      # Clears cached data, allowing it to be garbage collected.
+      # Subsequent calls to +read+ will re-fetch from storage.
+      #
+      # @return [void]
       def reset_read_cache!
         @read = nil
-        return unless @tempfile
-
-        @tempfile.close!
-        @tempfile = nil
       end
 
-      # Returns the file path to the data. Prefers a local storage path
-      # to avoid unnecessary copies, falls back to a tempfile.
-      def file_path
-        local_path || tempfile.path
+      # Yields a path to the data, removing any temporary copy
+      # afterwards.
+      #
+      # @yieldparam path [Pathname] path to the data
+      # @return [Object] the return value of the block
+      def with_file
+        path = local_path
+        return yield(Pathname.new(path)) if path
+
+        file = materialize
+        begin
+          yield(Pathname.new(file.path))
+        ensure
+          close_and_unlink(file)
+        end
       end
 
-      # Writes the data to a temporary file.
-      def tempfile
-        unless @tempfile
-          @tempfile = Tempfile.new(binmode: true)
-          @tempfile.write(@read || read_from(closest))
-          @tempfile.open
-        end
-        @tempfile
+      # Returns the data as an open file. Any temporary copy is
+      # unlinked first, leaving the kernel to reclaim it on close.
+      #
+      # @return [File] an open file, positioned at the start
+      def open
+        path = local_path
+        return File.open(path, "rb") if path
+
+        file = materialize
+        File.unlink(file.path)
+        file
       end
 
       protected
@@ -155,6 +190,48 @@ module Dis
         Dis::Storage.file_path(storage_type, content_hash)
       end
 
+      # Writes the data to a new temporary file. The caller owns it.
+      def materialize
+        file = Tempfile.create
+        file.binmode
+        fill(file)
+        file.rewind
+        file
+      rescue StandardError
+        close_and_unlink(file) if file
+        raise
+      end
+
+      def fill(file)
+        if raw?
+          write_raw_to(file)
+        else
+          Dis::Storage.get_file(storage_type, content_hash, file)
+        end
+      end
+
+      def write_raw_to(file)
+        if raw.respond_to?(:read)
+          rewind_raw
+          IO.copy_stream(raw, file)
+          rewind_raw
+        else
+          file.write(raw)
+        end
+        file.flush
+      end
+
+      def rewind_raw
+        raw.rewind if raw.respond_to?(:rewind)
+      end
+
+      def close_and_unlink(file)
+        file.close unless file.closed?
+        File.unlink(file.path)
+      rescue Errno::ENOENT
+        nil
+      end
+
       attr_reader :raw
     end
   end

data/lib/dis/model.rb

@@ -7,7 +7,7 @@ module Dis
   # = Dis Model
   #
   # ActiveModel extension for the model holding your data. To use it,
-  # simply include the module in your model:
+  # include the module in your model:
   #
   #   class Document < ActiveRecord::Base
   #     include Dis::Model
@@ -36,24 +36,24 @@ module Dis
   #
   # == Usage
   #
-  # To save a file, simply assign to the <tt>file</tt> attribute.
+  # To save a file, assign to the <tt>file</tt> attribute.
   #
   #   document = Document.create(file: params.permit(:file))
   #
   # <tt>content_type</tt> and <tt>filename</tt> will automatically be set if
-  # the supplied object quacks like a file. <tt>content_length</tt> will always
-  # be set. <tt>content_hash</tt> won't be set until the record is being saved.
+  # the supplied object quacks like a file. <tt>content_length</tt> and
+  # <tt>content_hash</tt> will always be set.
   #
-  # If you don't care about filenames and content types and just want to store
-  # a binary blob, you can also just set the <tt>data</tt> attribute.
+  # To store a binary blob without filenames or content types, set the
+  # <tt>data</tt> attribute directly.
   #
   #   my_data = File.read('document.pdf')
   #   document.update(data: my_data)
   #
-  # The data won't be stored until the record is saved, and not unless
+  # The data won't be stored until the record is saved, and only if
   # the record is valid.
   #
-  # To retrieve your data, simply read the <tt>data</tt> attribute. The file
+  # To retrieve your data, read the <tt>data</tt> attribute. The file
   # will be lazily loaded from the store on demand and cached in memory as long
   # as the record stays in scope.
   #
@@ -73,7 +73,7 @@ module Dis
   #     validates_data_presence
   #   end
   #
-  # If you want to validate content types, size or similar, simply use standard
+  # If you want to validate content types, size or similar, use standard
   # Rails validations on the metadata attributes:
   #
   #   validates :content_type, presence: true, format: /\Aapplication\/pdf\z/
@@ -89,18 +89,26 @@ module Dis
       attribute :data, :binary
     end
 
-    # Returns the data as a binary string, or nil if no data has been set.
+    # Returns the data as a binary string, or nil if no data has
+    # been set.
+    #
+    # @return [String, nil]
     def data
       dis_data.read
     end
 
     # Returns true if data is set.
+    #
+    # @return [Boolean]
     def data?
       dis_data.any?
     end
 
-    # Assigns new data. This also sets <tt>content_length</tt>, and resets
-    # <tt>content_hash</tt> to nil.
+    # Assigns new data. This also sets +content_length+ and
+    # +content_hash+.
+    #
+    # @param raw_data [File, IO, String, nil] the content to store
+    # @return [void]
     def data=(raw_data)
       new_data = Dis::Model::Data.new(self, raw_data)
       attribute_will_change!("data") unless new_data == dis_data
@@ -113,32 +121,67 @@ module Dis
       dis_set :content_length, dis_data.content_length
     end
 
-    # Returns true if the data has been changed since the object was last saved.
+    # Returns true if the data has been changed since the object
+    # was last saved.
+    #
+    # @return [Boolean]
     def data_changed?
       changes.include?("data")
     end
 
+    # Returns true if the record has been persisted and its data
+    # has not been changed since the last save.
+    #
+    # @return [Boolean]
     def dis_stored?
       !(new_record? || data_changed?)
     end
 
-    # Assigns new data from an uploaded file. In addition to the actions
-    # performed by <tt>data=</tt>, this will set <tt>content_type</tt> and
-    # <tt>filename</tt>.
+    # Assigns new data from an uploaded file. In addition to the
+    # actions performed by {#data=}, this will set +content_type+
+    # and +filename+.
+    #
+    # @param file [ActionDispatch::Http::UploadedFile,
+    #   Rack::Test::UploadedFile] an uploaded file that responds to
+    #   +content_type+ and +original_filename+
+    # @return [void]
     def file=(file)
       self.data = file
       dis_set :content_type, file.content_type
       dis_set :filename, file.original_filename
     end
 
-    # Returns a file path to the data, preferring local storage paths.
-    def data_file_path
-      dis_data.file_path
+    # Yields the path to a file containing the data, for tools that
+    # need a file name rather than the bytes. The path is valid for
+    # the duration of the block only, so resolve anything lazy before
+    # returning.
+    #
+    # @yieldparam path [Pathname] path to the data
+    # @return [Object] the return value of the block
+    #
+    # @example
+    #   document.with_data_file { |path| Vips::Image.new_from_file(path.to_s).avg }
+    def with_data_file(&)
+      dis_data.with_file(&)
+    end
+
+    # Returns the data as an open, read-only file, or yields it and
+    # closes it afterwards. The data stays readable until the file is
+    # closed, even if the content is deleted or evicted meanwhile.
+    #
+    # @yieldparam file [File] an open file, positioned at the start
+    # @return [File, Object] the open file, or the block's value
+    def open_data
+      file = dis_data.open
+      return file unless block_given?
+
+      begin
+        yield file
+      ensure
+        file.close unless file.closed?
+      end
     end
 
-    # Returns the data as a temporary file.
-    delegate :tempfile, to: :dis_data
-
     private
 
     def cleanup_data