cloudfs 1.0.0

data/lib/cloudfs/session.rb

@@ -0,0 +1,256 @@
+require_relative 'rest_adapter'
+require_relative 'account'
+require_relative 'user'
+require_relative 'filesystem'
+
+module CloudFS
+  # Establishes a session with the api server on behalf of an authenticated
+  # end-user
+  #
+  #	It maintains a RESTful low level api {CloudFS::Client} object
+  # that provides authenticated access to CloudFS  service end user's
+  #	account and is shared with file system objects linked with this session -
+  #	{FileSystem}, {Container}, {File}, {Folder}, {Share}, {Account}, {User}
+  #
+  #	@author Mrinal Dhillon
+  #	@example
+  #   session = CloudFS::Session.new(end_point, clientid, secret)
+  #		session.is_linked?		#=> false
+  #		session.autheticate(username, password)
+  #		session.is_linked?		#=> true
+  #		folder = session.filesystem.root.create_folder(folder_name)
+  #		folder.name = newname
+  #		folder.save
+  #		file = folder.upload(local_filepath)
+  #		session.unlink
+  class Session
+
+    #	@!attribute [r] filesystem
+    #
+    # @return [FileSystem] {FileSystem} instance linked with this session
+    def filesystem
+      @filesystem ||= FileSystem.new(@rest_adapter)
+    end
+
+    #	@!attribute [r] user
+    #
+    # @return [User] profile of end-user linked with this session
+    #
+    # @raise [RestAdapter::Errors::SessionNotLinked,
+    #   RestAdapter::Errors::ServiceError,
+    #   RestAdapter::Errors::OperationNotAllowedError]
+    def user
+      @user ||= get_user
+    end
+
+    #	@!attribute [r] account
+    #
+    # @return [Account] end-user's account linked with this session
+    #
+    # @raise [RestAdapter::Errors::SessionNotLinked,
+    #   RestAdapter::Errors::ServiceError,
+    #		RestAdapter::Errors::OperationNotAllowedError]
+    def account
+      @account ||= get_account
+    end
+
+    #	Set the admin credentials.
+    def set_admin_credentials(admin_client_id, admin_client_secret)
+      if RestAdapter::Utils.is_blank?(admin_client_id) || RestAdapter::Utils.is_blank?(admin_client_secret)
+        fail RestAdapter::Errors::ArgumentError,
+             'Invalid input, expected admin client id and admin client secret'
+      end
+      @admin_credentials[:clientid] = admin_client_id ? admin_client_id : nil
+      @admin_credentials[:secret] = admin_client_secret ? admin_client_secret : nil
+    end
+
+    # @param end_point [String] cloudfs application api server hostname
+    # @param clientid [String] account clientid
+    # @param secret [String] account secret
+    #	@param [Hash] http_conf RESTful connection configurations
+    #	  @option http_conf [Fixnum] :connect_timeout (60) for server handshake
+    #	  @option http_conf [Fixnum] :send_timeout (0) for send request,
+    #		  default is set to never, in order to support large uploads
+    #	  @option http_conf [Fixnum] :receive_timeout (120) for read timeout
+    #     per block
+    #	  @option http_conf [Fixnum] :max_retry (3) for http 500 level errors
+    #	  @option http_conf [#<<] :http_debug (nil) to enable http debugging,
+    #		  example STDERR, STDOUT, {::File} object opened with
+    #     permissions to write
+    #
+    # @optimize Configurable chunk size for chunked stream downloads,
+    #   default is 16KB.
+    #   Configurable keep alive timeout for persistent connections in
+    #   connection pool, default is 15 seconds. Async api support
+    #
+    # @review optimum default values for http timeouts
+    def initialize(end_point, clientid, secret, ** http_conf)
+      @http_debug = http_conf[:http_debug]
+      @rest_adapter = RestAdapter.new(clientid, secret, end_point, ** http_conf)
+      @unlinked = false
+      @admin_credentials = {}
+      @admin_credentials[:host] = end_point ? end_point : 'access.bitcasa.com'
+    end
+
+    # Attempts to log into the end-user's filesystem, links this session
+    # to an account
+    #
+    # @param username [String] end-user's username
+    # @param password [String] end-user's password
+    #
+    # @return [true]
+    #
+    # @raise [RestAdapter::Errors::ServiceError,
+    #		RestAdapter::Errors::ArgumentError,
+    #   RestAdapter::Errors::OperationNotAllowedError]
+    def authenticate(username, password)
+      validate_session
+      fail RestAdapter::Errors::OperationNotAllowedError,
+           'Cannot re-authenticate, initialize new session instance' if is_linked?
+      fail RestAdapter::Errors::ArgumentError,
+           'Invalid argument, must pass username' if RestAdapter::Utils.is_blank?(username)
+      fail RestAdapter::Errors::ArgumentError,
+           'Invalid argument, must pass password' if RestAdapter::Utils.is_blank?(password)
+
+      @rest_adapter.authenticate(username, password)
+    end
+
+    # @return [Boolean] whether current session is linked to the API server
+    #		and can make authenticated requests
+    def is_linked?
+      @rest_adapter.linked?
+    end
+
+    # Discards current authentication
+    #
+    # @note	CloudFS objects remain valid only till session is linked,
+    #		once unlinked all RESTful objects generated through this session
+    #		are expected to raise {RestAdapter::Errors::SessionNotLinked} exception
+    #		for any RESTful operation.
+    #
+    # @note Session cannot be re-authenticated once unlinked.
+    #
+    # @return [true]
+    def unlink
+      @rest_adapter.unlink
+      @unlinked = true
+    end
+
+    # Creates a new end-user account for a Paid CloudFS account
+    #
+    # @param username [String] username of the end-user,
+    #		must be at least 4 characters and less than 256 characters
+    # @param password [String] password of the end-user,
+    #		must be at least 6 characters and has no length limit
+    # @param email [String] email of the end-user
+    # @param first_name [String] first name of end user
+    # @param last_name [String] last name of end user
+    # @param log_in_to_created_user [Boolean] authenticate the create users.
+    # @return [Account] new user account
+    #
+    # @raise [Client::Errors::ServiceError, Client::Errors::ArgumentError,
+    #		Client::Errors::OperationNotAllowedError]
+    #
+    # @note Created {Account} is not linked,
+    #		authenticate this session with new account credentials before using it.
+    #
+    #	@example
+    #		Initialize session, create new account and link session with
+    #     created account's credentials
+    #
+    #		# Set credentials of prototype account
+    #		session = Session.new(clientid, secret, end_point)
+    #
+    #		# Set credentials of Paid CloudFS admin account
+    #		session.admin_credentials={ clientid: clientid, secret: secret }
+    #
+    #		# Create account
+    #		account = session.create_account(new_username, new_password)
+    #		session.authenticate(new_username, new_password)
+    #		account.usage		#=> {Fixnum}
+    #
+    # @review Does not allow account creation if current session has already been
+    #		authenticated. In such scenario account creation can be made possible
+    #		but returning new {Account} instance with this session's RESTful client
+    #		is not possible since session does not allow re-authentication.
+    def create_account(username, password, email: nil, first_name: nil,
+                       last_name: nil, log_in_to_created_user: false)
+      validate_session
+      fail RestAdapter::Errors::OperationNotAllowedError,
+           'New account creation with already linked session is not possible,
+						initialize new session instance' if is_linked?
+
+      fail RestAdapter::Errors::ArgumentError,
+           'Invalid argument, must pass username' if RestAdapter::Utils.is_blank?(username)
+      fail RestAdapter::Errors::ArgumentError,
+           'Invalid argument, must pass password' if RestAdapter::Utils.is_blank?(password)
+
+      if RestAdapter::Utils.is_blank?(@admin_credentials[:clientid]) ||
+          RestAdapter::Utils.is_blank?(@admin_credentials[:secret])
+        fail RestAdapter::Errors::ArgumentError,
+             'Please set the admin credentials in order to create account.'
+      end
+
+      admin_client = RestAdapter.new(
+      @admin_credentials[:clientid],
+      @admin_credentials[:secret], @admin_credentials[:host],
+      http_debug: @http_debug)
+
+      begin
+        response = admin_client.create_account(
+            username,
+            password, email: email,
+            first_name: first_name,
+            last_name: last_name)
+
+        if log_in_to_created_user
+          admin_client.authenticate(username, password)
+        end
+
+        Account.new(@rest_adapter, ** response)
+      ensure
+        admin_client.unlink
+      end
+    end
+
+    # @see #account
+    def get_account
+      validate_session
+      response = @rest_adapter.get_profile
+      Account.new(@rest_adapter, ** response)
+    end
+
+    #	@see #user
+    def get_user
+      validate_session
+      response = @rest_adapter.get_profile
+      User.new(@rest_adapter, ** response)
+    end
+
+    # Action history lists history of file, folder, and share actions
+    #
+    # @param start_version [Fixnum] version number to start listing historical
+    #   actions from,
+    #		default -10. It can be negative in order to get most recent actions.
+    # @param stop_version [Fixnum] version number to stop listing historical
+    #		actions from (non-inclusive)
+    #
+    # @return [Array<Hash>] action history items
+    #
+    # @raise [RestAdapter::Errors::SessionNotLinked,
+    #   RestAdapter::Errors::ServiceError,
+    #		RestAdapter::Errors::OperationNotAllowedError]
+    def action_history(start_version: -10, stop_version: nil)
+      validate_session
+      @rest_adapter.list_history(start: start_version, stop: stop_version)
+    end
+
+    # @raise [RestAdapter::Errors::OperationNotAllowedError]
+    def validate_session
+      fail RestAdapter::Errors::OperationNotAllowedError,
+           'This session has been unlinked, initialize new session instance' if @unlinked
+    end
+
+    private :validate_session, :get_user, :get_account
+  end
+end

data/lib/cloudfs/share.rb

@@ -0,0 +1,286 @@
+require_relative 'rest_adapter'
+require_relative 'filesystem_common'
+
+module CloudFS
+  # Share class is used to create and manage shares in end-user's account
+  #
+  # @author Mrinal Dhillon
+  class Share
+
+    # @return [String] share_key
+    attr_reader :share_key
+
+    # @return [String] name
+    attr_reader :name
+
+    # @return [String] type
+    attr_reader :type
+
+    # @return [String] url
+    attr_reader :url
+
+    # @return [String] short_url
+    attr_reader :short_url
+
+    # @return [String] size
+    attr_reader :size
+
+    # @return [String] application data
+    attr_reader :application_data
+
+    # Set the name of the share
+    # @param new_name [String] new name of the share.
+    # @param password [String] current password of the share.
+    def set_name(new_name, password: nil)
+      FileSystemCommon.validate_share_state(self)
+      fail RestAdapter::Errors::ArgumentError,
+           'Invalid input, expected new name' if RestAdapter::Utils.is_blank?(new_name)
+
+      response = @rest_adapter.alter_share_info(
+          @share_key,
+          current_password: password,
+          name: new_name)
+
+      set_share_info(** response)
+      self
+    end
+
+    #	@!attribute [r] date_created
+    #	@return [Time] creation time
+    def date_created
+      if @date_created
+        Time.at(@date_created)
+      else
+        nil
+      end
+    end
+
+    #	@!attribute [r] date_content_last_modified
+    #	@return [Time] modified time
+    def date_content_last_modified
+      if @date_content_last_modified
+        Time.at(@date_content_last_modified)
+      else
+        nil
+      end
+    end
+
+    #	@!attribute [r] date_meta_last_modified
+    #	@return [Time] modified time
+    def date_meta_last_modified
+      if @date_meta_last_modified
+        Time.at(@date_meta_last_modified)
+      else
+        nil
+      end
+    end
+
+    # @param rest_adapter [RestAdapter] cloudfs RESTful api object
+    #
+    # @param [Hash] properties metadata of share
+    #   @option  properties [String] :share_key
+    #   @option properties [String] :share_type
+    #   @option properties [String] :share_name
+    #   @option properties [String] :url
+    #   @option properties [String] :short_url
+    #   @option properties [String] :share_size
+    #   @option properties [Fixnum] :date_created
+    def initialize(rest_adapter, ** properties)
+      fail RestAdapter::Errors::ArgumentError,
+           'Invalid RestAdapter, input type must be CloudFS::RestAdapter' unless rest_adapter.is_a?(CloudFS::RestAdapter)
+      @rest_adapter = rest_adapter
+      set_share_info(** properties)
+    end
+
+    # @see #initialize
+    def set_share_info(** params)
+      @share_key = params.fetch(:share_key) { fail RestAdapter::Errors::ArgumentError,
+                                                   'missing parameter, share_key must be defined' }
+      @type = params[:share_type]
+      @name = params[:share_name]
+      @url = params[:url]
+      @short_url = params[:short_url]
+      @size = params[:share_size]
+      @date_created = params[:date_created]
+      @exists = true
+
+      if params[:single_item]
+        @application_data = params[:single_item][:application_data]
+        @date_content_last_modified = params[:single_item][:date_content_last_modified]
+        @date_meta_last_modified = params[:single_item][:date_meta_last_modified]
+      end
+
+      @parent_state = {:share_key => @share_key}
+
+      changed_properties_reset
+    end
+
+    # Reset changed properties
+    def changed_properties_reset
+      @changed_properties = {}
+    end
+
+    #	@return [Boolean] whether the share exists,
+    #		false only if it has been deleted
+    def exists?
+      @exists
+    end
+
+
+    # List items in this share
+    # @return [Array<File, Folder>] list of items
+    # @raise [RestAdapter::Errors::SessionNotLinked,
+    #   RestAdapter::Errors::ServiceError,
+    #		RestAdapter::Errors::InvalidShareError]
+    def list
+      FileSystemCommon.validate_share_state(self)
+      response = @rest_adapter.browse_share(@share_key).fetch(:items)
+      FileSystemCommon.create_items_from_hash_array(
+          response,
+          @rest_adapter,
+          parent_state: @parent_state,
+          in_share: true)
+    end
+
+    # Delete this share
+    #
+    #	@return [true]
+    #
+    # @note Subsequent operations shall fail
+    # {RestAdapter::Errors::InvalidShareError}
+    #
+    # @raise [RestAdapter::Errors::SessionNotLinked,
+    #   RestAdapter::Errors::ServiceError,
+    #		RestAdapter::Errors::InvalidShareError]
+    def delete
+      FileSystemCommon.validate_share_state(self)
+      @rest_adapter.delete_share(@share_key)
+      @exists = false
+      true
+    end
+
+    # Change password of this share
+    #
+    # @param password	[String] new password for this share
+    # @param current_password [String] is required if password is already
+    #   set for this share
+    #
+    # @return [Share] return self
+    #
+    # @raise [RestAdapter::Errors::SessionNotLinked,
+    #   RestAdapter::Errors::ServiceError,
+    #		RestAdapter::Errors::InvalidShareError]
+    def set_password(password, current_password: nil)
+      FileSystemCommon.validate_share_state(self)
+      fail RestAdapter::Errors::ArgumentError,
+           'Invalid input, expected the password' if RestAdapter::Utils.is_blank?(password)
+
+      response = @rest_adapter.alter_share_info(
+          @share_key,
+          current_password: current_password,
+          password: password)
+
+      set_share_info(** response)
+      self
+    end
+
+    # Changes, adds, or removes the share’s password or updates the name.
+    #
+    # @param [Hash] values metadata of share.
+    # @option values [String] :current_password
+    # @option values [String] :password
+    # @option values [String] :name
+    #
+    # @param password [String] current password of the share.
+    #
+    #	@return [Boolean] based on the success or fail status of the action.
+    def change_attributes(values, password: nil)
+      current_password = values.has_key?('current_password') ? values['current_password'] : password
+      new_password = values.has_key?('password') ? values['password'] : nil
+      name = values.has_key?('name') ? values['name'] : nil
+
+      response = @rest_adapter.alter_share_info(
+          @share_key, current_password: current_password, password: new_password, name: name)
+
+      set_share_info(** response)
+      response.has_key?(:share_key)
+    end
+
+    # Save this share's current state.
+    #		Only name, is committed to this share in user's account
+    # @param password [String] current password for this share,
+    #		if has been set, it is necessary even if share has been unlocked
+    #
+    # @return [Share] returns self
+    #
+    # @raise [RestAdapter::Errors::SessionNotLinked,
+    #   RestAdapter::Errors::ServiceError,
+    #   RestAdapter::Errors::InvalidShareError]
+    def save(password: nil)
+      FileSystemCommon.validate_share_state(self)
+      if @changed_properties[:name]
+        response = @rest_adapter.alter_share_info(
+            @share_key,
+            current_password: password,
+            name: @changed_properties[:name])
+
+        set_share_info(** response)
+      end
+      self
+    end
+
+    # Receive contents of this share at specified path in user's filesystem.
+    #		All items found in share are copied to given location.
+    #
+    # @param path [String] path in user's account to receive share at,
+    #   default is "/" root
+    # @param exists [String] ('RENAME', 'FAIL', 'OVERWRITE') action to take in
+    #		case of conflict with existing items at path
+    #
+    # @return [Array<File, Folder>] items
+    #
+    # @raise [RestAdapter::Errors::SessionNotLinked,
+    #   RestAdapter::Errors::ServiceError,
+    #		RestAdapter::Errors::InvalidShareError]
+    def receive(path: nil, exists: 'RENAME')
+      FileSystemCommon.validate_share_state(self)
+      response = @rest_adapter.receive_share(
+          @share_key,
+          path: path,
+          exists: exists)
+
+      FileSystemCommon.create_items_from_hash_array(
+          response,
+          @rest_adapter,
+          parent: path)
+    end
+
+    # Refresh this share to latest state
+    #	@note Locally changed properties i.e. name get discarded
+    #
+    # @note raises RestAdapter::Errors::ServiceError if share is locked,
+    #		unlock share if password is set
+    #
+    #	@return [Share] returns self
+    #
+    # @raise [RestAdapter::Errors::SessionNotLinked,
+    #   RestAdapter::Errors::ServiceError,
+    #		RestAdapter::Errors::InvalidShareError]
+    def refresh
+      FileSystemCommon.validate_share_state(self)
+      response = @rest_adapter.browse_share(share_key).fetch(:share)
+      set_share_info(** response)
+      self
+    end
+
+    #	@return [String]
+    #	@!visibility private
+    def to_s
+      "#{self.class}: name: #{@name}, size: #{@size}bytes"
+    end
+
+    alias inspect to_s
+
+    private :set_share_info, :changed_properties_reset
+  end
+end