Class: CloudFS::Session

Inherits:
Object
  • Object
show all
Defined in:
lib/cloudfs/session.rb

Overview

Establishes a session with the api server on behalf of an authenticated end-user

It maintains a RESTful low level api 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

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

Examples:

session = CloudFS::Session.new(end_point, clientid, secret)

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(end_point, clientid, secret, **http_conf) ⇒ Session

Returns a new instance of Session.

Parameters:

  • end_point (String) —

    cloudfs application api server hostname

  • clientid (String) —

    account clientid

  • secret (String) —

    account secret

  • http_conf (Hash) —

    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



87
88
89
90
91
92
93
 
# File 'lib/cloudfs/session.rb', line 87

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

Instance Attribute Details

#account ⇒ Account (readonly)

RestAdapter::Errors::OperationNotAllowedError]

Returns:

  • (Account) —

    end-user's account linked with this session

Raises:



53
54
55
 
# File 'lib/cloudfs/session.rb', line 53

def account
  @account ||= get_account
end

#filesystem ⇒ FileSystem (readonly)

Returns FileSystem instance linked with this session.

Returns:



31
32
33
 
# File 'lib/cloudfs/session.rb', line 31

def filesystem
  @filesystem ||= FileSystem.new(@rest_adapter)
end

#user ⇒ User (readonly)

Returns profile of end-user linked with this session.

Returns:

  • (User) —

    profile of end-user linked with this session

Raises:



42
43
44
 
# File 'lib/cloudfs/session.rb', line 42

def user
  @user ||= get_user
end

Instance Method Details

#action_history(start_version: -10,, stop_version: nil) ⇒ Array<Hash>

Action history lists history of file, folder, and share actions

default -10. It can be negative in order to get most recent actions.
RestAdapter::Errors::OperationNotAllowedError]

Parameters:

  • start_version (Fixnum) (defaults to: -10,) —

    version number to start listing historical actions from,

  • stop_version (Fixnum) (defaults to: nil) —

    version number to stop listing historical actions from (non-inclusive)

Returns:

  • (Array<Hash>) —

    action history items

Raises:



243
244
245
246
 
# File 'lib/cloudfs/session.rb', line 243

def action_history(start_version: -10, stop_version: nil)
  validate_session
  @rest_adapter.list_history(start: start_version, stop: stop_version)
end

#authenticate(username, password) ⇒ true

Attempts to log into the end-user's filesystem, links this session to an account

Parameters:

  • username (String) —

    end-user's username

  • password (String) —

    end-user's password

Returns:

  • (true)

Raises:



106
107
108
109
110
111
112
113
114
115
116
 
# File 'lib/cloudfs/session.rb', line 106

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

#create_account(username, password, email: nil, first_name: nil, last_name: nil, log_in_to_created_user: false) ⇒ Account

Note:

Created Account is not linked, authenticate this session with new account credentials before using it.

Creates a new end-user account for a Paid CloudFS account

Examples:

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}

Parameters:

  • username (String) —

    username of the end-user, must be at least 4 characters and less than 256 characters

  • password (String) —

    password of the end-user, must be at least 6 characters and has no length limit

  • email (String) (defaults to: nil) —

    email of the end-user

  • first_name (String) (defaults to: nil) —

    first name of end user

  • last_name (String) (defaults to: nil) —

    last name of end user

  • log_in_to_created_user (Boolean) (defaults to: false) —

    authenticate the create users.

Returns:

Raises:

  • (Client::Errors::ServiceError, Client::Errors::ArgumentError, Client::Errors::OperationNotAllowedError)

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.



176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
 
# File 'lib/cloudfs/session.rb', line 176

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

#is_linked? ⇒ Boolean

Returns whether current session is linked to the API server and can make authenticated requests.

Returns:

  • (Boolean) —

    whether current session is linked to the API server and can make authenticated requests



120
121
122
 
# File 'lib/cloudfs/session.rb', line 120

def is_linked?
  @rest_adapter.linked?
end

#set_admin_credentials(admin_client_id, admin_client_secret) ⇒ Object

Set the admin credentials.



58
59
60
61
62
63
64
65
 
# File 'lib/cloudfs/session.rb', line 58

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

#unlink ⇒ true

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.

Discards current authentication

Returns:

  • (true) 


134
135
136
137
 
# File 'lib/cloudfs/session.rb', line 134

def unlink
  @rest_adapter.unlink
  @unlinked = true
end