shrine-content_addressable 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4f20e5a9c6b4b2a0414709d361b48b4720595775
-  data.tar.gz: 88466ca818aea8fd7bab8e8bfcc39702333711ad
+  metadata.gz: a508236ee58a19f0f50bc8dbbc8f01e769f1f726
+  data.tar.gz: ca1e2593444f15e57671f5553cfe1cd98fad16f9
 SHA512:
-  metadata.gz: ae88579392a93003c7e9c547bbe54cc7109e8441d1d17aa8632bd7911ee7cca04739f1358d9c4ebec994b2f98af0b75292dc65746cd031adeb50b0058577b718
-  data.tar.gz: c3be4fd82bd522cea507600680c0e35ec085af7a3ace7b72691a3947f64442340ed4025f7afbd727717ba8a36c1464a4453365cb3a45e56b74088be093d70c0c
+  metadata.gz: 977f6d34d1f29027ae121a310e599de195eabe4befde9e5b98a95ee880cb9a5c54131e15a7a649aa8bcd18a21c339b58adbaa3bd54cfa7faae41905a634675d8
+  data.tar.gz: f2e4df13b082e8896ba9178f6faecae1fc20c06b46532561b7daf481335ce370ea5a64f2037b2054ac38e15633818b0a204fe0eed13ce968ee4d8c41ab6db02f

data/.rubocop.yml

@@ -9,3 +9,6 @@ AllCops:
 
 Style/EndOfLine:
   EnforcedStyle: lf
+
+Naming/UncommunicativeMethodParamName:
+  AllowedNames: [_, x, y, z, i, io, id]

data/README.md

@@ -45,6 +45,19 @@ correctly supported by the `signature` plugin, and has a `multihash` code, add t
 plugin :content_addressable, hash: :blake2_b, multihash: 'blake2b'
 ```
 
+Your uploaded files will be extended with some multihash capability:
+
+```Ruby
+uploader = Uploader.new(:cache)
+uploaded_file = uploader.upload(my_file)
+
+uploaded_file.content_addressable # => the content addressable hash, regardless of location
+uploaded_file.decode # => the decoded multihash
+uploaded_file.digest # => the decoded digest (in bytes. Use .unpack('H*') to turn into hex)
+uploaded_file.digest_function # => the digest function used to create the multihash
+uploaded_file.to_content_addressable! # => ContentAddressableFile, and auto registers the storage
+```
+
 ### ContentAddressable IO
 Since a content-addressable stored file is the same across whichever storage, it *MUST* not matter what storage the file
 is accessed from when it comes to reading. A wrapper is provided so files can be looked up by their content-addressable
@@ -53,14 +66,15 @@ id / hash, instead of a data hash (default for Shrine).
 ```Ruby
 require 'content_addressable_file'
 
-# You currently need to register the storages
+# You currently need to register the storages, unless you use uploaded_file.to_content_addressable!
 ContentAddressableFile.register_storage(lookup, lookup, lookup)
 
-# You can disallow deletion using
+# You can disallow deletion
 ContentAddressableFile.register_read_only_storage(lookup, lookup, lookup) 
 
 file = ContentAddressableFile.new(content_addressable_hash)
 
+# Shares the interface with UploadedFile
 # => file methods like open, rewind, read, close and eof? are available
 # => file.url gives the first url that exists
 # => file.exists? is true if it exists in any storage
@@ -72,20 +86,25 @@ To reset known storages use:
 ContentAddressableFile.reset
 ```
 
-In a later version registration might be automatic. A lookup storage needs to respond to:
+Registration is only automatic when using `#to_content_addressable!`. Do not rely on that behaviour
+if you're not always uploading files, but trying to retrieve them.
+
+A lookup storage needs to respond to:
 ```Ruby
 lookup = Shrine::Storage::Memory.new
-id = content_addressable_hash
+content_addressable = content_addressable_hash
 
-lookup.open(id) # IO.open
-lookup.exists?(id) # true if storage has it (and can open)
+lookup.open(content_addressable) # IO.open
+lookup.exists?(content_addressable) # true if storage has it (and can open)
 
 # optional
-lookup.url(id) # url to the io (only if storage has it)
-lookup.delete(id) # delete from storage
-lookup.download(id) # download the io
+lookup.url(content_addressable) # url to the io (only if storage has it)
+lookup.delete(content_addressable) # delete from storage
+lookup.download(content_addressable) # download the io
 ```
 
+Note that you input the hash, and not some arbitrary path.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can
@@ -107,5 +126,5 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the Shrine::ConfigurableStorage project’s codebases, issue trackers, chat rooms and mailing
-lists is expected to follow the [code of conduct](https://github.com/SleeplessByte/shrine-configurable_storage/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the `Shrine::Plugins::ContentAddressable` project’s codebases, issue trackers, chat rooms and
+mailing lists is expected to follow the [code of conduct](https://github.com/SleeplessByte/shrine-configurable_storage/blob/master/CODE_OF_CONDUCT.md).

data/lib/content_addressable_file.rb

@@ -1,52 +1,12 @@
 # frozen_string_literal: true
 
-require 'English'
 require 'multihashes'
-require 'forwardable'
+require 'set'
 
-class ReadOnlyStorage
-  extend Forwardable
-  def_delegators :@storage, :exists?, :download, :url
-
-  def initialize(storage)
-    @storage = storage
-  end
-end
+require 'content_addressable_file/acts_as_uploaded_file'
+require 'content_addressable_file/shared_interface'
 
 class ContentAddressableFile
-
-  class << self
-    attr_accessor :storages
-
-    # Registers a storage to be used with content-addressable file. All shrine
-    # storages are supported by default, as is any duck type that responds to
-    # Storage#open(content-addressable-hash) and Storage#exists?(hash).
-    #
-    # Additional functionality needs Storage#url(hash), Storage#delete(hash)
-    # and Storage#download(hash).
-    #
-    # When a content-addressable file is deleted, it's deleted from all
-    # registered storages. use #register_read_only_storage to prevent deletion.
-    #
-    def register_storage(*storage)
-      self.storages = Array(storages).push(*storage)
-      self
-    end
-
-    # Same as #register_storage, but only forwards read only methods.
-    def register_read_only_storage(*storage)
-      read_only = Array(storage).map { |s| ReadOnlyStorage.new(s) }
-      self.storages = Array(storages).push(*read_only)
-      self
-    end
-
-    # Removes all registered storages
-    def reset
-      self.storages = []
-      self
-    end
-  end
-
   attr_reader :id
 
   # Creates a new content-addressable file wrapper that uses the given id as
@@ -58,212 +18,10 @@ class ContentAddressableFile
     self.id = id
   end
 
-  # Tries to decode the multihash. This is a good check to see if the given id
-  # is actually a content-addressable, but also easy to "fake", as the only way
-  # to be certain that the id is a content addressable is actually getting the
-  # file and hashing it again.
-  def decode
-    @decode ||= Multihashes.decode id
-  end
-
-  # The #deocode digest as a byte array
-  def digest
-    decode[:digest]
-  end
-
-  # The #decode digest length
-  def digest_length
-    decode[:length]
-  end
-
-  # The #decode hash function
-  def digest_hash_function
-    decode[:hash_function]
-  end
-
-  # Calls `#open` on the storages to open the uploaded file for reading.
-  # Most storages will return a lazy IO object which dynamically
-  # retrieves file content from the storage as the object is being read.
-  #
-  # If a block is given, the opened IO object is yielded to the block,
-  # and at the end of the block it's automatically closed. In this case
-  # the return value of the method is the block return value.
-  #
-  # If no block is given, the opened IO object is returned.
-  #
-  # @example
-  #
-  #     content_addressable.open #=> IO object returned by the storage
-  #     content_addressable.read #=> "..."
-  #     content_addressable.close
-  #
-  #     # or
-  #
-  #     content_addressable.open { |io| io.read }
-  #     #=> "..."
-  def open(*args)
-    return to_io unless block_given?
-
-    begin
-      @io = pin_storage(:open, id, *args)
-      yield @io
-    ensure
-      @io&.close
-      @io = nil
-    end
-  end
-
-  alias safe_open open
-
-  # Calls `#download` on the storages if the storage that has the file
-  # implements it, otherwise streams content into a newly created Tempfile.
-  #
-  # If the file exists in multiple storages, any that allows download will
-  # be pinned.
-  #
-  # If a block is given, the opened Tempfile object is yielded to the
-  # block, and at the end of the block it's automatically closed and
-  # deleted. In this case the return value of the method is the block
-  # return value.
-  #
-  # If no block is given, the opened Tempfile is returned.
-  #
-  #     content_addressable.download
-  #     #=> #<File:/var/folders/.../20180302-33119-1h1vjbq.jpg>
-  #
-  #     # or
-  #
-  #     content_addressable.download { |tempfile| tempfile.read }
-  #     # tempfile is deleted
-  #     #=> "..."
-  def download(*args)
-    if any_storage(:respond_to?, :download)
-      tempfile = pin_storage(:download, id, *args)
-    else
-      tempfile = Tempfile.new(['content-addressable', id], binmode: true)
-      stream(tempfile, *args)
-      tempfile.open
-    end
-
-    block_given? ? yield(tempfile) : tempfile
-  ensure
-    tempfile.close! if ($ERROR_INFO || block_given?) && tempfile
-  end
-
-  # Streams uploaded file content into the specified destination. The
-  # destination object is given directly to `IO.copy_stream`, so it can
-  # be either a path on disk or an object that responds to `#write`.
-  #
-  # If the uploaded file is already opened, it will be simply rewinded
-  # after streaming finishes. Otherwise the uploaded file is opened and
-  # then closed after streaming.
-  #
-  #     content_addressable.stream(StringIO.new)
-  #     # or
-  #     content_addressable.stream("/path/to/destination")
-  def stream(destination, *args)
-    if @io
-      IO.copy_stream(io, destination)
-      io.rewind
-    else
-      safe_open(*args) { |io| IO.copy_stream(io, destination) }
-    end
-  end
-
-  # Part of complying to the IO interface. It delegates to the internally
-  # opened IO object.
-  def read(*args)
-    io.read(*args)
-  end
-
-  # Part of complying to the IO interface. It delegates to the internally
-  # opened IO object.
-  def eof?
-    io.eof?
-  end
-
-  # Part of complying to the IO interface. It delegates to the internally
-  # opened IO object.
-  def rewind
-    io.rewind
-  end
-
-  # Part of complying to the IO interface. It delegates to the internally
-  # opened IO object.
-  def close
-    io.close if @io
-  end
-
-  # Calls `#url` on the storage where the file is first found, forwarding any
-  # given URL options.
-  def url(**options)
-    pin_storage(:url, id, **options)
-  end
-
-  # Calls `#exists?` on the storages, which checks whether the file exists
-  # on any of the storages.
-  def exists?
-    pin_storage(:exists?, id)
-  end
-
-  # Calls `#delete` on the storages, which deletes the file from the
-  # storage.
-  def delete
-    all_storages(:delete, id)
-  end
-
-  # Returns an opened IO object for the uploaded file.
-  def to_io
-    io
-  end
-
-  # Returns true if the other File has the same id
-  def ==(other)
-    other.is_a?(self.class) && id == other.id
-  end
-  alias eql? ==
-
-  # Enables using File objects as hash keys.
-  def hash
-    [id].hash
-  end
-
-  # Returns the storage that this file was uploaded to.
-  def storage
-    pin_storage(:exists?, id) && @pin_storage
-  end
+  include ActsAsUploadedFile
+  include SharedInterface
 
   private
 
   attr_writer :id
-
-  # Returns an opened IO object for the uploaded file by calling `#open`
-  # on the storage.
-  def io
-    @io ||= pin_storage(:open, id)
-  end
-
-  # rubocop:disable Style/RescueModifier
-  def all_storages(method, *args)
-    self.class.storages.map do |storage|
-      storage.send(method, *args) rescue next
-    end
-  end
-
-  def any_storage(method, *args)
-    self.class.storages.each do |storage|
-      result = storage.send(method, *args) rescue next
-      break result if result
-    end
-  end
-
-  def pin_storage(method, *args)
-    @pin_storage = self.class.storages.find do |storage|
-      storage.send(:exists?, id) rescue next
-    end
-
-    @pin_storage&.send(method, *args)
-  end
-  # rubocop:enable Style/RescueModifier
-
 end

data/lib/content_addressable_file/acts_as_uploaded_file.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+require 'English'
+require 'set'
+require 'content_addressable_file/read_only_storage'
+
+class ContentAddressableFile
+  module ActsAsUploadedFile
+    def self.included(base)
+      base.send :include, InstanceMethods
+      base.extend ClassMethods
+    end
+
+    module InstanceMethods
+      # Calls `#open` on the storages to open the uploaded file for reading.
+      # Most storages will return a lazy IO object which dynamically
+      # retrieves file content from the storage as the object is being read.
+      #
+      # If a block is given, the opened IO object is yielded to the block,
+      # and at the end of the block it's automatically closed. In this case
+      # the return value of the method is the block return value.
+      #
+      # If no block is given, the opened IO object is returned.
+      #
+      # @example
+      #
+      #     content_addressable.open #=> IO object returned by the storage
+      #     content_addressable.read #=> "..."
+      #     content_addressable.close
+      #
+      #     # or
+      #
+      #     content_addressable.open { |io| io.read }
+      #     #=> "..."
+      def open(*args)
+        return to_io unless block_given?
+
+        begin
+          @io = pin_storage(:open, id, *args)
+          yield @io
+        ensure
+          @io&.close
+          @io = nil
+        end
+      end
+
+      alias safe_open open
+
+      # Calls `#download` on the storages if the storage that has the file
+      # implements it, otherwise streams content into a newly created Tempfile.
+      #
+      # If the file exists in multiple storages, any that allows download will
+      # be pinned.
+      #
+      # If a block is given, the opened Tempfile object is yielded to the
+      # block, and at the end of the block it's automatically closed and
+      # deleted. In this case the return value of the method is the block
+      # return value.
+      #
+      # If no block is given, the opened Tempfile is returned.
+      #
+      #     content_addressable.download
+      #     #=> #<File:/var/folders/.../20180302-33119-1h1vjbq.jpg>
+      #
+      #     # or
+      #
+      #     content_addressable.download { |tempfile| tempfile.read }
+      #     # tempfile is deleted
+      #     #=> "..."
+      def download(*args)
+        if any_storage(:respond_to?, :download)
+          tempfile = pin_storage(:download, id, *args)
+        else
+          tempfile = Tempfile.new(['content-addressable', id], binmode: true)
+          stream(tempfile, *args)
+          tempfile.open
+        end
+
+        block_given? ? yield(tempfile) : tempfile
+      ensure
+        tempfile.close! if ($ERROR_INFO || block_given?) && tempfile
+      end
+
+      # Streams uploaded file content into the specified destination. The
+      # destination object is given directly to `IO.copy_stream`, so it can
+      # be either a path on disk or an object that responds to `#write`.
+      #
+      # If the uploaded file is already opened, it will be simply rewinded
+      # after streaming finishes. Otherwise the uploaded file is opened and
+      # then closed after streaming.
+      #
+      #     content_addressable.stream(StringIO.new)
+      #     # or
+      #     content_addressable.stream("/path/to/destination")
+      def stream(destination, *args)
+        if @io
+          IO.copy_stream(io, destination)
+          io.rewind
+        else
+          safe_open(*args) { |io| IO.copy_stream(io, destination) }
+        end
+      end
+
+      # Part of complying to the IO interface. It delegates to the internally
+      # opened IO object.
+      def read(*args)
+        io.read(*args)
+      end
+
+      # Part of complying to the IO interface. It delegates to the internally
+      # opened IO object.
+      def eof?
+        io.eof?
+      end
+
+      # Part of complying to the IO interface. It delegates to the internally
+      # opened IO object.
+      def rewind
+        io.rewind
+      end
+
+      # Part of complying to the IO interface. It delegates to the internally
+      # opened IO object.
+      def close
+        io.close if @io
+      end
+
+      # Calls `#url` on the storage where the file is first found, forwarding any
+      # given URL options.
+      def url(**options)
+        pin_storage(:url, id, **options)
+      end
+
+      # Calls `#exists?` on the storages, which checks whether the file exists
+      # on any of the storages.
+      def exists?
+        pin_storage(:exists?, id)
+      end
+
+      # Calls `#delete` on the storages, which deletes the file from the
+      # storage.
+      def delete
+        all_storages(:delete, id)
+      end
+
+      # Returns an opened IO object for the uploaded file.
+      def to_io
+        io
+      end
+
+      # Returns the storage that this file was uploaded to.
+      def storage
+        pin_storage(:exists?, id) && @pin_storage
+      end
+
+      # Returns an opened IO object for the uploaded file by calling `#open`
+      # on the storage.
+      def io
+        @io ||= pin_storage(:open, id)
+      end
+
+      private
+
+      # rubocop:disable Style/RescueModifier
+      def all_storages(method, *args)
+        self.class.storages.map do |storage|
+          storage.send(method, *args) rescue next
+        end
+      end
+
+      def any_storage(method, *args)
+        self.class.storages.each do |storage|
+          result = storage.send(method, *args) rescue next
+          break result if result
+        end
+      end
+
+      def pin_storage(method, *args)
+        @pin_storage = self.class.storages.find do |storage|
+          storage.send(:exists?, id) rescue next
+        end
+
+        @pin_storage&.send(method, *args)
+      end
+      # rubocop:enable Style/RescueModifier
+    end
+
+    module ClassMethods
+      attr_accessor :storages
+
+      # Registers a storage to be used with content-addressable file. All shrine
+      # storages are supported by default, as is any duck type that responds to
+      # Storage#open(content-addressable-hash) and Storage#exists?(hash).
+      #
+      # Additional functionality needs Storage#url(hash), Storage#delete(hash)
+      # and Storage#download(hash).
+      #
+      # When a content-addressable file is deleted, it's deleted from all
+      # registered storages. use #register_read_only_storage to prevent deletion.
+      #
+      def register_storage(*storage)
+        self.storages = Set.new(storages).merge(Array(storage))
+        self
+      end
+
+      # Same as #register_storage, but only forwards read only methods.
+      def register_read_only_storage(*storage)
+        read_only = Array(storage).map { |s| ReadOnlyStorage.new(s) }
+        self.storages = Set.new(storages).merge(read_only)
+        self
+      end
+
+      # Removes all registered storages
+      def reset
+        self.storages = Set.new(storages).clear
+        self
+      end
+    end
+  end
+end

data/lib/content_addressable_file/read_only_storage.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+
+class ContentAddressableFile
+  class ReadOnlyStorage
+    extend Forwardable
+    def_delegators :@storage,
+                   :exists?, :download, :url, :class, :equal?, :eql?, :hash
+
+    def initialize(storage)
+      @storage = storage
+    end
+  end
+end

data/lib/content_addressable_file/shared_interface.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require 'multihashes'
+
+class ContentAddressableFile
+  module SharedInterface
+    def content_addressable
+      @content_addressable ||= String(id).rpartition('/').last
+    end
+
+    # Tries to decode the multihash. This is a good check to see if the given id
+    # is actually a content-addressable, but also easy to "fake", as the only way
+    # to be certain that the id is a content addressable is actually getting the
+    # file and hashing it again.
+    def decode
+      @decode ||= Multihashes.decode([content_addressable].pack('H*'))
+    end
+
+    # The #deocode digest as a byte array
+    def digest
+      decode[:digest]
+    end
+
+    # The #decode digest length
+    def digest_length
+      decode[:length]
+    end
+
+    # The #decode hash function
+    def digest_hash_function
+      decode[:hash_function]
+    end
+
+    # Returns true if the other File has the same id
+    def ==(other)
+      other.respond_to?(:digest) && content_addressable == other.content_addressable
+    end
+    alias eql? ==
+
+    # Enables using File objects as hash keys.
+    def hash
+      [content_addressable].hash
+    end
+  end
+end

data/lib/shrine/plugins/content_addressable.rb

@@ -6,6 +6,8 @@ require 'shrine/plugins/signature'
 require 'multihashes'
 require 'digest'
 
+require 'shrine/plugins/content_addressable/file_methods'
+
 class Shrine
   module Plugins
     ##
@@ -75,7 +77,9 @@ class Shrine
         end
 
         def generate_location(io, _)
-          [opts[:content_addressable_prefix], content_addressable_hex(io)].compact.join('/')
+          [opts[:content_addressable_prefix], content_addressable_hex(io)]
+            .compact
+            .join('/')
         end
       end
     end

data/lib/shrine/plugins/content_addressable/file_methods.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'content_addressable_file'
+require 'content_addressable_file/shared_interface'
+
+class Shrine
+  module Plugins
+    module ContentAddressable
+      module FileMethods
+        include ContentAddressableFile::SharedInterface
+
+        def to_content_addressable!
+          ContentAddressableFile.register_storage(storage)
+          ContentAddressableFile.new(id)
+        end
+      end
+    end
+  end
+end

data/shrine-content_addressable.gemspec

@@ -5,7 +5,7 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 
 Gem::Specification.new do |spec|
   spec.name          = 'shrine-content_addressable'
-  spec.version       = '0.3.1'
+  spec.version       = '0.4.0'
   spec.authors       = ['Derk-Jan Karrenbeld']
   spec.email         = ['derk-jan+github@karrenbeld.info']
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: shrine-content_addressable
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Derk-Jan Karrenbeld
@@ -133,7 +133,11 @@ files:
 - bin/console
 - bin/setup
 - lib/content_addressable_file.rb
+- lib/content_addressable_file/acts_as_uploaded_file.rb
+- lib/content_addressable_file/read_only_storage.rb
+- lib/content_addressable_file/shared_interface.rb
 - lib/shrine/plugins/content_addressable.rb
+- lib/shrine/plugins/content_addressable/file_methods.rb
 - shrine-content_addressable.gemspec
 homepage: 
 licenses: