cloudfs 1.0.0

data/lib/cloudfs/client/utils.rb

@@ -0,0 +1,93 @@
+require 'cgi'
+require 'base64'
+require 'openssl'
+require 'multi_json'
+
+module CloudFS
+  class RestAdapter
+    #	@private
+    # Utility functions module, used to handle common tasks
+    module Utils
+      extend self
+      # Urlencode value
+      #
+      # @param value [#to_s] to urlencode
+      # @return [String] url encoded string
+      def urlencode(value)
+        CGI.escape("#{value}")
+      end
+
+      # Converts hash to url encoded string
+      #
+      # @param hash [Hash] hash to be converted
+      # @param delim [#to_s]
+      # @param join_with [#to_s]
+      #
+      # @return [String] url encode string
+      #		"#{ key }#{ delim }#{ value }#{ join_with }#{ key }#{ delim }#{ value }"
+      # @optimize does not handle nested hash
+      def hash_to_urlencoded_str(hash = {}, delim, join_with)
+        hash.map { |k, v|
+          "#{urlencode(k)}#{delim}#{urlencode(v)}" }.join("#{join_with}")
+      end
+
+      # Sorts hash by key.downcase
+      # @param hash [Hash] unsorted hash
+      # @return [Hash] sorted hash
+      def sort_hash(hash={})
+        sorted_hash = {}
+        hash.sort_by { |k, _| k.to_s.downcase }.each { |k, v| sorted_hash["#{k}"] = v }
+        sorted_hash
+      end
+
+      # Generate OAuth2 signature based on cloudfs
+      #		signature calculation algorithm
+      #
+      # @param endpoint [String] server endpoint
+      # @param params [Hash] form data
+      # @param headers [Hash] http request headers
+      # @param secret [Hash] cloudfs account secret
+      #
+      # @return [String] OAuth2 signature
+      def generate_auth_signature(endpoint, params, headers, secret)
+        params_sorted = sort_hash(params)
+        params_encoded = hash_to_urlencoded_str(params_sorted, '=', '&')
+        headers_encoded = hash_to_urlencoded_str(headers, ':', '&')
+        string_to_sign = "POST&#{endpoint}&#{params_encoded}&#{headers_encoded}"
+        hmac_str = OpenSSL::HMAC.digest('sha1', secret, string_to_sign)
+        Base64.strict_encode64(hmac_str)
+      end
+
+      # Coverts Json sting to hash
+      #		calls MultiJson#load
+      # @param json_str [String] json format string
+      # @return [Hash] converted hash
+      def json_to_hash(json_str)
+        MultiJson.load(json_str, :symbolize_keys => true)
+      end
+
+      #	Converts hash to json string
+      #		calls MultiJson#dump
+      # @param hash [Hash] hash to convert
+      # @return [String] json formated string
+      def hash_to_json(hash={})
+        MultiJson.dump(hash)
+      end
+
+      # @param hash [Hash]
+      # @option filed [Array<String>, Array<Symbol>]
+      # @return [Array<Object>]	values at found fields
+      def hash_to_arguments(hash, *field)
+        if field.any? { |f| hash.key?(f) }
+          hash.values_at(*field)
+        end
+      end
+
+      # @return [Boolean] whether variable is nil, empty
+      def is_blank?(var)
+        var.respond_to?(:empty?) ? var.empty? : !var
+      end
+
+    end
+  end
+end

data/lib/cloudfs/container.rb

@@ -0,0 +1,51 @@
+require_relative 'item'
+require_relative 'rest_adapter'
+require_relative 'filesystem_common'
+
+module CloudFS
+  # Base class for {Folder}
+  #
+  # @author Mrinal Dhillon
+  #	@example
+  #		folder = session.filesystem.root.create_folder(name_of_folder)
+  #		folder.list		# => []
+  #		session.filesystem.root.list	# => Array<File, Folder>
+  class Container < Item
+    # @see Item#initialize
+    def initialize(rest_adapter, parent: nil, parent_state: nil, in_trash: false,
+                   in_share: false, ** properties)
+      fail RestAdapter::Errors::ArgumentError,
+           "Invalid item of type #{properties[:type]}" unless properties[:type] ==
+          'folder' || properties[:type] == 'root'
+      super
+    end
+
+    # List contents of this container
+    #
+    # @return [Array<Folder, File>] list of items
+    # @raise [RestAdapter::Errors::SessionNotLinked, RestAdapter::Errors::ServiceError,
+    #		RestAdapter::Errors::InvalidItemError]
+    def list
+      fail RestAdapter::Errors::InvalidItemError,
+           'Operation not allowed as item does not exist anymore' unless exists?
+
+      if @in_share
+        response = @rest_adapter.browse_share(@state[:share_key], path: @url).fetch(:items)
+      elsif @in_trash
+        response = @rest_adapter.browse_trash(path: @url).fetch(:items)
+      else
+        response = @rest_adapter.list_folder(path: @url, depth: 1)
+      end
+      FileSystemCommon.create_items_from_hash_array(
+          response,
+          @rest_adapter,
+          parent: @url,
+          in_share: @in_share,
+          in_trash: @in_trash,
+          parent_state: @state)
+    end
+
+    # overriding inherited properties that are not not valid for folder
+    private :blocklist_key, :blocklist_id, :versions, :old_version?
+  end
+end

data/lib/cloudfs/file.rb

@@ -0,0 +1,209 @@
+require_relative 'item'
+require_relative 'rest_adapter'
+require_relative 'filesystem_common'
+
+module CloudFS
+  # File class is aimed to provide native File object like interface
+  #		to cloudfs files
+  #
+  # @author Mrinal Dhillon
+  # @example
+  #		file = session.filesystem.root.upload(local_file_path)
+  #		file.seek(4, IO::SEEK_SET) #=> 4
+  #		file.tell #=> 4
+  #		file.read #=> " is some buffer till end of file"
+  #		file.rewind
+  #		file.read {|chunk| puts chunk} #=> "this is some buffer till end of file"
+  # 	file.download(local_folder_path, filename: new_name_of_downloaded_file)
+  class File < Item
+
+    # @return [String] the size.
+    attr_reader :size
+
+    # @return [String] the extension.
+    attr_reader :extension
+
+    # @return [String] the mime type of file
+    attr_reader :mime
+
+    # Sets the mime type of the item and updates to CloudFS
+    def mime=(value)
+      fail RestAdapter::Errors::ArgumentError,
+           'Invalid input, expected new mime' if RestAdapter::Utils.is_blank?(value)
+
+      @mime = value
+      @changed_properties[:mime] = value
+      change_attributes(@changed_properties)
+    end
+
+    # @see #extension
+    def extension=(value)
+      FileSystemCommon.validate_item_state(self)
+      @extension = value
+      @changed_properties[:extension] = value
+    end
+
+    # @see Item#initialize
+    def initialize(rest_adapter, parent: nil, parent_state: nil, in_trash: false,
+                   in_share: false, old_version: false, ** properties)
+      fail RestAdapter::Errors::ArgumentError,
+           "Invalid item of type #{properties[:type]}" unless properties[:type] == 'file'
+
+      @offset = 0
+      super
+    end
+
+    # Download this file to local directory
+    #
+    # @param local_destination_path [String] path of local folder
+    # @param filename [String] name of downloaded file, default is name of this file
+    # @yield [Integer] download progress.
+    #
+    #	@return [true]
+    #
+    # @raise [RestAdapter::Errors::SessionNotLinked, RestAdapter::Errors::ServiceError,
+    #		RestAdapter::Errors::ArgumentError, RestAdapter::Errors::InvalidItemError,
+    #		RestAdapter::Errors::OperationNotAllowedError]
+    # @review overwrites a file if it exists at local path
+    #	@note Internally uses chunked stream download,
+    #		max size of in-memory chunk is 16KB.
+    def download(local_destination_path, filename: nil, &block)
+      fail RestAdapter::Errors::ArgumentError,
+           'local path is not a valid directory' unless ::File.directory?(local_destination_path)
+      FileSystemCommon.validate_item_state(self)
+
+      filename ||= @name
+      if local_destination_path[-1] == '/'
+        local_filepath = "#{local_destination_path}#{filename}"
+      else
+        local_filepath = "#{local_destination_path}/#{filename}"
+      end
+      ::File.open(local_filepath, 'wb') do |file|
+        downloaded = 0
+        @rest_adapter.download(@url) do |buffer|
+          downloaded += buffer.size
+          file.write(buffer)
+          yield @size, downloaded if block_given?
+        end
+      end
+      true
+    end
+
+    # Get the download URL of the file.
+    # @raise [RestAdapter::Errors::SessionNotLinked, RestAdapter::Errors::ServiceError,
+    #		RestAdapter::Errors::ArgumentError, RestAdapter::Errors::InvalidItemError,
+    #		RestAdapter::Errors::OperationNotAllowedError]
+    # @return [String] download URL of the file.
+    def download_url
+      url = @rest_adapter.download_url(@url)
+      URI.extract(url).first.chomp(';')
+    end
+
+
+    # Read from file to buffer
+    #
+    #	@param bytecount [Fixnum] number of bytes to read from current access position
+    # @return [String] buffer
+    # @raise [RestAdapter::Errors::SessionNotLinked, RestAdapter::Errors::ServiceError]
+    def read_to_buffer(bytecount)
+      buffer = @rest_adapter.download(@url, startbyte: @offset, bytecount: bytecount)
+      @offset += buffer.nil? ? 0 : buffer.size
+      buffer
+    end
+
+    # Read from file to proc
+    #
+    #	@param bytecount [Fixnum] number of bytes to read from current access position
+    # @yield [String] chunk of data as soon as available,
+    #		chunksize size may vary each time
+    # @raise [RestAdapter::Errors::SessionNotLinked, RestAdapter::Errors::ServiceError]
+    def read_to_proc(bytecount, &block)
+      @rest_adapter.download(@url, startbyte: @offset, bytecount: bytecount) do |chunk|
+        @offset += chunk.nil? ? 0 : chunk.size
+        yield chunk
+      end
+    end
+
+    # Read from file
+    #
+    #	@param bytecount [Fixnum] number of bytes to read from
+    #		current access position, default reads upto end of file
+    #
+    # @yield [String] chunk data as soon as available,
+    #		chunksize size may vary each time
+    # @return [String] buffer, unless block is given
+    # @raise [RestAdapter::Errors::SessionNotLinked, RestAdapter::Errors::ServiceError,
+    #		RestAdapter::Errors::ArgumentError, RestAdapter::Errors::InvalidItemError,
+    #		RestAdapter::Errors::OperationNotAllowedError]
+    #
+    #	@note	Pass block to stream chunks as soon as available,
+    #		preferable for large reads.
+    def read(bytecount: nil, &block)
+      fail RestAdapter::Errors::ArgumentError,
+           "Negative length given - #{bytecount}" if bytecount && bytecount < 0
+      FileSystemCommon.validate_item_state(self)
+
+      if bytecount == 0 || @offset >= @size
+        return yield '' if block_given?
+        return ''
+      end
+
+      # read till end of file if no bytecount is given
+      # 	or offset + bytecount  > size of file
+      bytecount = @size - @offset if bytecount.nil? || (@offset + bytecount > @size)
+
+      if block_given?
+        read_to_proc(bytecount, &block)
+      else
+        read_to_buffer(bytecount)
+      end
+    end
+
+    #	Reset position indicator
+    def rewind
+      @offset = 0
+    end
+
+    # Return current access position in this file
+    # @return [Fixnum] current position in file
+    def tell
+      @offset
+    end
+
+    # Seek to a particular byte in this file
+    # @param offset [Fixnum] offset in this file to seek to
+    # @param whence [Fixnum] defaults 0,
+    #		If whence is 0 file offset shall be set to offset bytes
+    #		If whence is 1, the file offset shall be set to its
+    #			current location plus offset
+    #		If whence is 2, the file offset shall be set to the size of
+    #			the file plus offset
+    # @return [Fixnum] resulting offset
+    # @raise [RestAdapter::Errors::ArgumentError]
+    def seek(offset, whence: 0)
+
+      case whence
+        when 0
+          @offset = offset if whence == 0
+        when 1
+          @offset += offset if whence == 1
+        when 2
+          @offset = @size + offset if whence == 2
+        else
+          fail RestAdapter::Errors::ArgumentError,
+               'Invalid value of whence, should be 0 or IO::SEEK_SET, 1 or IO::SEEK_CUR, 2 or IO::SEEK_END'
+      end
+
+      @offset
+    end
+
+    #	@return [String]
+    #	@!visibility private
+    def to_s
+      "#{self.class}: url #{@url}, name: #{@name}, mime: #{@mime}, version: #{@version}, size: #{@size} bytes"
+    end
+
+    alias inspect to_s
+    private :read_to_buffer, :read_to_proc
+  end
+end

data/lib/cloudfs/filesystem.rb

@@ -0,0 +1,111 @@
+require_relative 'rest_adapter'
+require_relative 'folder'
+require_relative 'filesystem_common'
+
+module CloudFS
+  # FileSystem class provides interface to maintain cloudfs user's filesystem
+  #
+  # @author Mrinal Dhillon
+  class FileSystem
+
+    # Get root object of filesystem
+    #
+    # @return [Folder] represents root folder of filesystem
+    #
+    # @raise RestAdapter::Errors::SessionNotLinked,
+    #   RestAdapter::Errors::ServiceError
+    def root
+      response = @rest_adapter.get_folder_meta('/')
+      FileSystemCommon.create_item_from_hash(@rest_adapter, ** response)
+    end
+
+    # @param rest_adapter [RestAdapter] cloudfs RESTful api object
+    #
+    # @raise [RestAdapter::Errors::ArgumentError]
+    def initialize(rest_adapter)
+      fail RestAdapter::Errors::ArgumentError,
+           'invalid RestAdapter, input type must be RestAdapter' unless rest_adapter.is_a?(RestAdapter)
+      @rest_adapter = rest_adapter
+    end
+
+    # @return [Array<File, Folder>] items in trash
+    #
+    # @raise [RestAdapter::Errors::SessionNotLinked,
+    #   RestAdapter::Errors::ServiceError, RestAdapter::Errors::InvalidItemError,
+    #   RestAdapter::Errors::OperationNotAllowedError]
+    def list_trash
+      response = @rest_adapter.browse_trash.fetch(:items)
+      FileSystemCommon.create_items_from_hash_array(
+          response,
+          @rest_adapter,
+          in_trash: true)
+    end
+
+    # List shares created by end-user
+    # @return [Array<Share>] shares
+    #
+    # @raise [RestAdapter::Errors::SessionNotLinked,
+    # RestAdapter::Errors::ServiceError]
+    def list_shares
+      response = @rest_adapter.list_shares
+      FileSystemCommon.create_items_from_hash_array(response, @rest_adapter)
+    end
+
+    # Create share of paths in user's filesystem
+    #
+    # @param paths [Array<File, Folder, String>] file, folder or url
+    # @param password [String] password.
+    #
+    # @return [Share] instance
+    #
+    # @raise [RestAdapter::Errors::SessionNotLinked,
+    #   RestAdapter::Errors::ServiceError, RestAdapter::Errors::ArgumentError,
+    #   RestAdapter::Errors::InvalidItemError,
+    #   RestAdapter::Errors::OperationNotAllowedError]
+    def create_share(paths, password: nil)
+      fail RestAdapter::Errors::ArgumentError,
+           'Invalid input, expected items or paths' unless paths
+
+      path_list = []
+      [*paths].each do |path|
+        FileSystemCommon.validate_item_state(path)
+        path_list << FileSystemCommon.get_item_url(path)
+      end
+
+      response = @rest_adapter.create_share(path_list, password: password)
+      FileSystemCommon.create_item_from_hash(@rest_adapter, ** response)
+    end
+
+    # Fetches share associated with share key.
+    #
+    #	@param share_key [String] valid share key
+    #	@param password [String] password if share is locked
+    #
+    #	@return [Share] instance of share
+    # @raise [RestAdapter::Errors::SessionNotLinked,
+    #   RestAdapter::Errors::ServiceError, RestAdapter::Errors::ArgumentError]
+    #
+    #	@note	This method is intended for retrieving share from another user
+    def retrieve_share(share_key, password: nil)
+      fail RestAdapter::Errors::ArgumentError,
+           'Invalid input, expected items or paths' if RestAdapter::Utils.is_blank?(share_key)
+
+      @rest_adapter.unlock_share(share_key, password) if password
+      response = @rest_adapter.browse_share(share_key).fetch(:share)
+      FileSystemCommon.create_item_from_hash(@rest_adapter, ** response)
+    end
+
+    # Get an item located in a given location.
+    def get_item(path)
+      fail RestAdapter::Errors::ArgumentError,
+           'Invalid input, expected item path' if RestAdapter::Utils.is_blank?(path)
+
+      if path.is_a?(String)
+        FileSystemCommon.get_item(@rest_adapter, path)
+      else
+        nil
+      end
+    end
+
+  end
+end