Class: CloudFS::RestAdapter

Inherits:
Object
  • Object
show all
Defined in:
lib/cloudfs/rest_adapter.rb,
lib/cloudfs/client/error.rb,
lib/cloudfs/client/utils.rb,
lib/cloudfs/client/constants.rb,
lib/cloudfs/client/connection.rb

Overview

Examples:

Upload file

::File.open(local_file_path, "r") do |file|
	rest_adapter.upload(path, file,
			name: 'somename', exists: 'FAIL')
end

Download file

Download into buffer
buffer = rest_adapter.download(path, startbyte: 0, bytecount: 1000)

Streaming download i.e. chunks are synchronously returned as soon as
 available
	preferable for large files download:

::File.open(local_filepath, 'wb') do |file|
		rest_adapter.download(path) { |buffer| file.write(buffer) }
end

OPTIMIZE:

  • Support async requests, blocker methods like wait for async operations, chunked/streaming upload i.e. chunked upload(not sure if server supports), StringIO, String upload, debug

Defined Under Namespace

Modules: Errors Classes: Connection

Instance Method Summary collapse

Constructor Details

#initialize(clientid, secret, host, **params) ⇒ RestAdapter

Creates RestAdapter instance that manages rest api calls to CloudFS service

default is 16KB. Configurable keep alive timeout for persistent connections in connection pool, default is 15 seconds. Async api support

Parameters:

  • clientid (String) —

    application clientid

  • secret (String) —

    application secret

  • host (String) —

    server address

  • params (Hash) —

    RESTful connection configurations

Options Hash (**params):

  • :connect_timeout (Fixnum) — default: 60 —

    for server handshake

  • :send_timeout (Fixnum) — default: 0 —

    for send request, default is set to never, in order to support large uploads

  • :receive_timeout (Fixnum) — default: 120 —

    for read timeout per block

  • :max_retry (Fixnum) — default: 3 —

    for http 500 level errors

  • :http_debug (#<<) — default: nil —

    to enable http debugging, example STDERR, STDOUT, File object opened with permissions to write

Raises:

OPTIMIZE:

  • Configurable chunk size for chunked stream downloads,

REVIEW:

  • optimum default values for send and receive timeouts



76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
 
# File 'lib/cloudfs/rest_adapter.rb', line 76

def initialize(clientid, secret, host, ** params)
  fail Errors::ArgumentError,
       'Invalid argument provided' if (Utils.is_blank?(clientid) ||
      Utils.is_blank?(secret) || Utils.is_blank?(host))

  @clientid = "#{clientid}"
  @secret = "#{secret}"
  @host = /https:\/\// =~ host ? "#{host}" :
      "#{Constants::URI_PREFIX_HTTPS}#{host}"
  @access_token = nil

  connect_timeout, send_timeout, receive_timeout, max_retries, http_debug =
      params.values_at(
          :connect_timeout,
          :send_timeout,
          :receive_timeout,
          :max_retries,
          :http_debug)

  connect_timeout ||= 60
  send_timeout ||= 0
  receive_timeout ||= 120
  max_retries ||= 3

  @http_connection = Connection.new(
      connect_timeout: connect_timeout,
      send_timeout: send_timeout,
      receive_timeout: receive_timeout,
      max_retries: max_retries, debug_dev: http_debug,
      agent_name: "#{Constants::HTTP_AGENT_NAME} (#{CloudFS::VERSION})")
end

Instance Method Details

#alter_file_meta(path, version, version_conflict: 'FAIL', **properties) ⇒ Hash

Alter file metadata

Parameters:

  • path (String) —

    file path

  • version (Fixnum) —

    version number of file

  • version_conflict (String) (defaults to: 'FAIL') —

    ('FAIL', 'IGNORE') action to take if the version on rest_adapter does not match the version on server

  • properties (Hash)

Options Hash (**properties):

  • :name (String) — default: nil —

    new name

  • :date_created (Fixnum) — default: nil —

    timestamp

  • :date_meta_last_modified (Fixnum) — default: nil —

    timestamp

  • :date_content_last_modified (Fixnum) — default: nil —

    timestamp

  • :application_data (Hash) — default: {} —

    will be merged with existing application data

Returns:

  • (Hash) —

    updated metadata of file

Raises:



586
587
588
589
 
# File 'lib/cloudfs/rest_adapter.rb', line 586

def alter_file_meta(path, version, version_conflict: 'FAIL', ** properties)
  alter_meta(Constants::ENDPOINT_FILES, path, version,
             version_conflict: version_conflict, ** properties)
end

#alter_folder_meta(path, version, version_conflict: 'FAIL', **properties) ⇒ Hash

Alter folder metadata

Parameters:

  • path (String) —

    folder path

  • version (Fixnum) —

    version number of folder

  • version_conflict (String) (defaults to: 'FAIL') —

    ('FAIL', 'IGNORE') action to take if the version on the rest_adapter does not match the version on the server

  • properties (Hash)

Options Hash (**properties):

  • :name (String) — default: nil —

    new name

  • :date_created (Fixnum) — default: nil —

    timestamp

  • :date_meta_last_modified (Fixnum) — default: nil —

    timestamp

  • :date_content_last_modified (Fixnum) — default: nil —

    timestamp

  • :application_data({}) (Hash) —

    will be merged with existing application data

Returns:

  • (Hash) —

    updated metadata of folder

Raises:



563
564
565
566
 
# File 'lib/cloudfs/rest_adapter.rb', line 563

def alter_folder_meta(path, version, version_conflict: 'FAIL', ** properties)
  alter_meta(Constants::ENDPOINT_FOLDERS, path, version,
             version_conflict: version_conflict, ** properties)
end

#alter_share_info(share_key, current_password: nil, password: nil, name: nil) ⇒ Hash

Alter share info changes, adds, or removes the share’s password or updates the name

Parameters:

  • share_key (String) —

    id of the share whose attributes are to be changed

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

    current password for this share, if has been set, it is necessary even if share has been unlocked

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

    new password of share

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

    new name of share

Returns:

  • (Hash) —

    updated metadata of share

Raises:

REVIEW:

  • remove password has not been tested



982
983
984
985
986
987
988
989
990
991
992
993
994
995
 
# File 'lib/cloudfs/rest_adapter.rb', line 982

def alter_share_info(share_key, current_password: nil,
                     password: nil, name: nil)
  fail Errors::ArgumentError,
       'Invalid argument, must pass valid path' if Utils.is_blank?(share_key)

  uri = set_uri_params(Constants::ENDPOINT_SHARES, name: share_key,
                       operation: 'info')
  form = {}
  form[:current_password] = current_password if current_password
  form[:password] = password if password
  form[:name] = name unless Utils.is_blank?(name)

  request('POST', uri: uri, body: form)
end

#authenticate(username, password) ⇒ true

Obtains an OAuth2 access token that authenticates an end-user for this rest_adapter

Parameters:

  • username (String) —

    username of the end-user

  • password (String) —

    password of the end-user

Returns:

  • (true)

Raises:



139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
 
# File 'lib/cloudfs/rest_adapter.rb', line 139

def authenticate(username, password)
  fail Errors::ArgumentError,
       'Invalid argument, must pass username' if Utils.is_blank?(username)
  fail Errors::ArgumentError,
       'Invalid argument, must pass password' if Utils.is_blank?(password)

  date = Time.now.utc.strftime(Constants::DATE_FORMAT)
  form = {
      Constants::PARAM_GRANT_TYPE => Constants::PARAM_PASSWORD,
      Constants::PARAM_PASSWORD => password,
      Constants::PARAM_USER => username
  }

  headers = {
      Constants::HEADER_CONTENT_TYPE =>
          Constants::CONTENT_TYPE_APP_URLENCODED,
      Constants::HEADER_DATE => date
  }

  uri = {endpoint: Constants::ENDPOINT_OAUTH}
  signature = Utils.generate_auth_signature(Constants::ENDPOINT_OAUTH,
                                            form, headers, @secret)
  headers[Constants::HEADER_AUTHORIZATION] =
      "#{Constants::HEADER_AUTH_PREFIX_BCS} #{@clientid}:#{signature}"

  access_info = request('POST', uri: uri, header: headers, body: form)
  @access_token = access_info.fetch(:access_token)
  true
end

#browse_share(share_key, path: nil) ⇒ Hash

List files and folders in a share

Parameters:

  • share_key (String) —

    id of the share

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

    path to any folder in share, default is root of share

Returns:

  • (Hash) —

    metadata of browsed path in share defaults share, share's metadata and array of hashes representing list of items under browsed item if folder - { :meta => Hash, share: Hash, :items => Array }

Raises:



900
901
902
903
904
905
906
907
908
909
 
# File 'lib/cloudfs/rest_adapter.rb', line 900

def browse_share(share_key, path: nil)
  fail Errors::ArgumentError,
       'Invalid argument, must pass valid path' if Utils.is_blank?(share_key)

  uri = set_uri_params(Constants::ENDPOINT_SHARES,
                       name: "#{share_key}#{path}", operation: 'meta')

  request('GET', uri: uri,
          header: Constants::HEADER_CONTENT_TYPE_APP_URLENCODED)
end

#browse_trash(path: nil) ⇒ Hash

List files and folders in trash at specified path

root of trash

representing list of items under browsed item if folder - { :meta => Hash, :items => }

Parameters:

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

    path to location in user's trash, defaults to

Returns:

  • (Hash) —

    metadata of browsed trash item and array of hashes

Raises:



1027
1028
1029
1030
1031
 
# File 'lib/cloudfs/rest_adapter.rb', line 1027

def browse_trash(path: nil)
  uri = set_uri_params(Constants::ENDPOINT_TRASH, name: path)
  request('GET', uri: uri,
          header: Constants::HEADER_CONTENT_TYPE_APP_URLENCODED)
end

#copy_file(path, destination, name, exists: 'RENAME') ⇒ Hash

Copy file to specified destination folder

Parameters:

  • path (String) —

    source file path

  • destination (String) —

    destination folder path

  • name (String) —

    new name of copied file

  • exists (String) (defaults to: 'RENAME') —

    ('FAIL', 'OVERWRITE', 'RENAME') action to take in case of a conflict with an existing file An unused integer is appended to file name if exists: RENAME

Returns:

  • (Hash) —

    metadata of new file

Raises:



380
381
382
 
# File 'lib/cloudfs/rest_adapter.rb', line 380

def copy_file(path, destination, name, exists: 'RENAME')
  copy(Constants::ENDPOINT_FILES, path, destination, name, exists: exists)
end

#copy_folder(path, destination, name, exists: 'FAIL') ⇒ Hash

Copy folder to specified destination folder

Parameters:

  • path (String) —

    source folder path

  • destination (String) —

    destination folder path

  • name (String) —

    new name of copied folder

  • exists (String) (defaults to: 'FAIL') —

    ('FAIL', 'OVERWRITE', 'RENAME') action to take in case of a conflict with an existing folder An unused integer is appended to folder name if exists: RENAME

Returns:

  • (Hash) —

    metadata of new folder

Raises:



363
364
365
 
# File 'lib/cloudfs/rest_adapter.rb', line 363

def copy_folder(path, destination, name, exists: 'FAIL')
  copy(Constants::ENDPOINT_FOLDERS, path, destination, name, exists: exists)
end

#create_account(username, password, email: nil, first_name: nil, last_name: nil) ⇒ Hash

Creates a new end-user account for a Paid CloudFS (developer’s) account

Parameters:

  • username (String) —

    username of the end-user.

  • password (String) —

    password of the end-user.

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

    email of the end-user

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

    first name of the end-user

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

    last name of the end-user

Returns:

  • (Hash) —

    end-user's attributes

Raises:



191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
 
# File 'lib/cloudfs/rest_adapter.rb', line 191

def create_account(username, password, email: nil,
                   first_name: nil, last_name: nil)
  fail Errors::ArgumentError,
       'Invalid argument, must pass username' if Utils.is_blank?(username)
  fail Errors::ArgumentError,
       'Invalid argument, must pass password' if Utils.is_blank?(password)

  date = Time.now.utc.strftime(Constants::DATE_FORMAT)
  form = {
      Constants::PARAM_PASSWORD => password,
      Constants::PARAM_USER => username
  }

  form[Constants::PARAM_EMAIL] = email unless Utils.is_blank?(email)
  form[Constants::PARAM_FIRST_NAME] =
      first_name unless Utils.is_blank?(first_name)
  form[Constants::PARAM_LAST_NAME] =
      last_name unless Utils.is_blank?(last_name)

  headers = {
      Constants::HEADER_CONTENT_TYPE =>
          Constants::CONTENT_TYPE_APP_URLENCODED,
      Constants::HEADER_DATE => date
  }
  uri = {endpoint: Constants::ENDPOINT_CUSTOMERS}
  signature = Utils.generate_auth_signature(Constants::ENDPOINT_CUSTOMERS,
                                            form, headers, @secret)
  headers[Constants::HEADER_AUTHORIZATION] =
      "#{Constants::HEADER_AUTH_PREFIX_BCS} #{@clientid}:#{signature}"

  request('POST', uri: uri, header: headers, body: form)
end

#create_folder(name, path: nil, exists: 'FAIL') ⇒ Hash

Create folder at specified destination path in end-user's account

Parameters:

  • name (Sting) —

    name of folder to create

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

    default: root, absolute path to destination folder

  • exists (String) (defaults to: 'FAIL') —

    ('FAIL', 'OVERWRITE', 'RENAME', 'REUSE')

Returns:

  • (Hash) —

    metadata of created folder

Raises:

REVIEW:

  • why this api returns an array of items



248
249
250
251
252
253
254
255
256
257
258
259
260
261
 
# File 'lib/cloudfs/rest_adapter.rb', line 248

def create_folder(name, path: nil, exists: 'FAIL')
  fail Errors::ArgumentError,
       'Invalid argument, must pass name' if Utils.is_blank?(name)
  exists = Constants::EXISTS.fetch(exists.to_sym) {
    fail Errors::ArgumentError, 'Invalid value for exists' }

  uri = set_uri_params(Constants::ENDPOINT_FOLDERS, name: path)
  query = {operation: Constants::QUERY_OPS_CREATE}
  form = {name: name, exists: exists}

  response = request('POST', uri: uri, query: query, body: form)
  items = response.fetch(:items)
  items.first
end

#create_share(paths, password: nil) ⇒ Hash

Creates a share of locations specified by the passed list of paths

Parameters:

  • paths (Array<String>) —

    array of file/folder paths in end-user's accoun

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

    password of the share

Returns:

  • (Hash) —

    metadata of share

Raises:

REVIEW:

  • according to cloudfs rest doc: If the share points to a single item, only the share data is returned (not the item’s metadata). Observed only share data returned even when share points to multiple paths?



855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
 
# File 'lib/cloudfs/rest_adapter.rb', line 855

def create_share(paths, password: nil)
  fail Errors::ArgumentError,
       'Invalid argument, must pass valid list of paths' if Utils.is_blank?(paths)

  body = [*paths].map { |path|
    path = prepend_path_with_forward_slash(path)
    "path=#{Utils.urlencode(path)}" }.join('&')

  unless password.nil?
    body += "&password=#{password}"
  end

  uri = {endpoint: Constants::ENDPOINT_SHARES}

  request('POST', uri: uri, body: body)
end

#delete_file(path, commit: false) ⇒ Hash

Delete file

Parameters:

  • path (String) —

    file path

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

    set true to remove file permanently, else will be moved to trash

Returns:

  • (Hash) —

    hash with key for success and deleted file's last version

Raises:



316
317
318
 
# File 'lib/cloudfs/rest_adapter.rb', line 316

def delete_file(path, commit: false)
  delete(Constants::ENDPOINT_FILES, path, commit: commit)
end

#delete_folder(path, commit: false, force: false) ⇒ Object

Raises:



302
303
304
 
# File 'lib/cloudfs/rest_adapter.rb', line 302

def delete_folder(path, commit: false, force: false)
  delete(Constants::ENDPOINT_FOLDERS, path, commit: commit, force: force)
end

#delete_share(share_key) ⇒ Hash

Deletes the user created share

Parameters:

  • share_key (String) —

    id of the share to be deleted

Returns:

  • (Hash) —

    hash containing success string

Raises:



880
881
882
883
884
885
886
887
888
 
# File 'lib/cloudfs/rest_adapter.rb', line 880

def delete_share(share_key)
  fail Errors::ArgumentError,
       'Invalid argument, must pass valid share key' if Utils.is_blank?(share_key)

  uri = set_uri_params(Constants::ENDPOINT_SHARES, name: "#{share_key}/")

  request('DELETE', uri: uri,
          header: Constants::HEADER_CONTENT_TYPE_APP_URLENCODED)
end

#delete_trash_item(path: nil) ⇒ Hash

Delete trash item

expected behaviour is to delete all items in trash

Parameters:

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

    default: trash root, path to location in user's trash, default all trash items are deleted

Returns:

  • (Hash) —

    containing success: true

Raises:

REVIEW:

  • CloudFS Server returns Unspecified Error 9999 if no path provided,



1044
1045
1046
1047
1048
 
# File 'lib/cloudfs/rest_adapter.rb', line 1044

def delete_trash_item(path: nil)
  uri = set_uri_params(Constants::ENDPOINT_TRASH, name: path)
  request('DELETE', uri: uri,
          header: Constants::HEADER_CONTENT_TYPE_APP_URLENCODED)
end

#download(path, startbyte: 0, bytecount: 0) {|String| ... } ⇒ String

Download file

Examples:

Download into buffer
buffer = rest_adapter.download(path, startbyte: 0, bytecount: 1000)

Streaming download i.e. chunks are synchronously returned as soon as available
	preferable for large files download:

::File.open(local_filepath, 'wb') do |file|
		rest_adapter.download(path) { |buffer| file.write(buffer) }
end

Parameters:

  • path (String) —

    path of file in end-user's account

  • startbyte (Fixnum) (defaults to: 0) —

    starting byte (offset) in file

  • bytecount (Fixnum) (defaults to: 0) —

    number of bytes to download

Yields:

  • (String) —

    chunk of data as soon as available, chunksize size may vary each time

Returns:

  • (String) —

    file data is returned if no block given

Raises:



724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
 
# File 'lib/cloudfs/rest_adapter.rb', line 724

def download(path, startbyte: 0, bytecount: 0, &block)
  fail Errors::ArgumentError,
       'Invalid argument, must pass path' if Utils.is_blank?(path)
  fail Errors::ArgumentError,
       'Size must be positive' if (bytecount < 0 || startbyte < 0)

  uri = set_uri_params(Constants::ENDPOINT_FILES, name: path)
  header = Constants::HEADER_CONTENT_TYPE_APP_URLENCODED.dup

  unless startbyte == 0 && bytecount == 0
    if bytecount == 0
      header[:Range] = "bytes=#{startbyte}-"
    else
      header[:Range] = "bytes=#{startbyte}-#{startbyte + bytecount - 1}"
    end
  end

  request('GET', uri: uri, header: header, &block)
end

#download_url(path) ⇒ String

Get the download URL of the file.

RestAdapter::Errors::ArgumentError,

RestAdapter::Errors::InvalidItemError, RestAdapter::Errors::OperationNotAllowedError]

Returns:

  • (String) —

    request response containing the download URL.

Raises:



753
754
755
756
757
758
759
760
 
# File 'lib/cloudfs/rest_adapter.rb', line 753

def download_url(path)
  uri = set_uri_params(Constants::ENDPOINT_FILES, name: path)
  header = {
      Constants::HEADER_REDIRECT => false
  }.merge(Constants::HEADER_CONTENT_TYPE_APP_URLENCODED.dup)

  request('GET', uri: uri, header: header)
end

#get_file_meta(path) ⇒ Hash

Get file meta

Parameters:

  • path (String) —

    file path

Returns:

  • (Hash) —

    metadata of file

Raises:



508
509
510
 
# File 'lib/cloudfs/rest_adapter.rb', line 508

def get_file_meta(path)
  get_meta(Constants::ENDPOINT_FILES, path)
end

#get_folder_meta(path) ⇒ Hash

Get folder meta

Parameters:

  • path (String) —

    folder path

Returns:

  • (Hash) —

    metadata of folder

Raises:



496
497
498
 
# File 'lib/cloudfs/rest_adapter.rb', line 496

def get_folder_meta(path)
  get_meta(Constants::ENDPOINT_FOLDERS, path)
end

#get_item_meta(path) ⇒ Hash

Get item meta

Parameters:

  • path (String) —

    file path

Returns:

  • (Hash) —

    metadata of item

Raises:



520
521
522
 
# File 'lib/cloudfs/rest_adapter.rb', line 520

def get_item_meta(path)
  get_meta(Constants::ENDPOINT_ITEM, path)
end

#get_profile ⇒ Hash

Get cloudfs end-user profile information

Returns:

  • (Hash) —

    account metadata for the authenticated user

Raises:



229
230
231
232
233
234
 
# File 'lib/cloudfs/rest_adapter.rb', line 229

def get_profile
  uri = {endpoint: Constants::ENDPOINT_USER_PROFILE}

  request('GET', uri: uri,
          header: Constants::HEADER_CONTENT_TYPE_APP_URLENCODED)
end

#linked? ⇒ Boolean

Returns whether rest_adapter can make authenticated requests to cloudfs service.

Returns:

  • (Boolean) —

    whether rest_adapter can make authenticated requests to cloudfs service

Raises:



111
112
113
114
115
116
 
# File 'lib/cloudfs/rest_adapter.rb', line 111

def linked?
  ping
  true
rescue Errors::SessionNotLinked
  false
end

#list_file_versions(path, start_version: 0, stop_version: nil, limit: 10) ⇒ Array<Hash>

List versions of file

Parameters:

  • path (String) —

    file path

  • start_version (Fixnum) (defaults to: 0) —

    version number to begin listing file versions

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

    version number from which to stop listing file versions

  • limit (Fixnum) (defaults to: 10) —

    how many versions to list in the result set. It can be negative.

Returns:

  • (Array<Hash>) —

    hashes representing metadata for selected versions of the file as recorded in the History

Raises:

REVIEW:

  • Returns empty items array if file has no old version



826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
 
# File 'lib/cloudfs/rest_adapter.rb', line 826

def list_file_versions(path, start_version: 0, stop_version: nil, limit: 10)
  fail Errors::ArgumentError,
       'Invalid argument, must pass valid path' if Utils.is_blank?(path)

  uri = set_uri_params(Constants::ENDPOINT_FILES, name: path,
                       operation: 'versions')

  query = {
      :'start-version' => start_version, :'limit' => limit
  }
  query[:'stop-version'] = stop_version if stop_version

  request('GET', uri: uri, query: query,
          header: Constants::HEADER_CONTENT_TYPE_APP_URLENCODED)
end

#list_folder(path: nil, depth: nil, filter: nil, strict_traverse: false) ⇒ Array<Hash>

TODO:

accept filter array, return { meta: Hash, items: Array }

Errors::ArgumentError]

Parameters:

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

    defaults: root, folder path to list

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

    default: nil, levels to recurse, 0 - infinite depth

  • filter (String) (defaults to: nil)
  • strict_traverse (Boolean) (defaults to: false) —

    traversal based on success of filters and possibly the depth parameters

Returns:

  • (Array<Hash>) —

    metadata of files and folders under listed folder

Raises:



275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
 
# File 'lib/cloudfs/rest_adapter.rb', line 275

def list_folder(path: nil, depth: nil, filter: nil, strict_traverse: false)
  fail Errors::ArgumentError,
       'Invalid argument must pass strict_traverse of type boolean' unless !!strict_traverse == strict_traverse

  uri = set_uri_params(Constants::ENDPOINT_FOLDERS, name: path)
  query = {}
  query = {depth: depth} if depth
  unless Utils.is_blank?(filter)
    query[:filter] = filter
    query[:'strict-traverse'] = "#{strict_traverse}"
  end

  response = request('GET', uri: uri, query: query)
  response.fetch(:items)
end

#list_history(start: -10,, stop: nil) ⇒ Array<Hash>

List the history of file, folder, and share actions

actions from, default -10. It can be negative in order to get most recent actions. from (non-inclusive)

Parameters:

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

    version number to start listing historical

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

    version number to stop listing historical actions

Returns:

  • (Array<Hash>) —

    history items

Raises:



1008
1009
1010
1011
1012
1013
1014
1015
 
# File 'lib/cloudfs/rest_adapter.rb', line 1008

def list_history(start: -10, stop: nil)
  uri = {endpoint: Constants::ENDPOINT_HISTORY}
  query = {start: start}
  query[:stop] = stop if stop

  request('GET', uri: uri, query: query,
          header: Constants::HEADER_CONTENT_TYPE_APP_URLENCODED)
end

#list_shares ⇒ Array<Hash>

Lists the metadata of the shares the authenticated user has created

Returns:

  • (Array<Hash>) —

    metatdata of user's shares

Raises:



916
917
918
919
920
921
 
# File 'lib/cloudfs/rest_adapter.rb', line 916

def list_shares
  uri = {endpoint: Constants::ENDPOINT_SHARES}

  request('GET', uri: uri,
          header: Constants::HEADER_CONTENT_TYPE_APP_URLENCODED)
end

#list_single_file_version(path, version) ⇒ Hash

List specified version of file

Parameters:

  • path (String) —

    file path

  • version (Fixnum) —

    desired version of the file referenced by path

Returns:

  • (Hash) —

    metatdata passed version of file

Raises:

REVIEW:

  • If current version of file is passed, CloudFS Server returns unspecified error 9999, works for pervious file versions.



774
775
776
777
778
779
780
781
782
783
784
785
 
# File 'lib/cloudfs/rest_adapter.rb', line 774

def list_single_file_version(path, version)
  fail Errors::ArgumentError,
       'Invalid argument, must pass valid path' if Utils.is_blank?(path)
  fail Errors::ArgumentError,
       'Invalid argument, must pass valid path' unless version.is_a?(Fixnum)

  uri = set_uri_params(Constants::ENDPOINT_FILES, name: path,
                       operation: "versions/#{version}")

  request('GET', uri: uri,
          header: Constants::HEADER_CONTENT_TYPE_APP_URLENCODED)
end

#move_file(path, destination, name, exists: 'RENAME') ⇒ Hash

Move file to specified destination folder

Parameters:

  • path (String) —

    source file path

  • destination (String) —

    destination folder path

  • name (String) —

    name of moved file

  • exists (String) (defaults to: 'RENAME') —

    ('FAIL', 'OVERWRITE', 'RENAME') action to take in case of a conflict with an existing file An unused integer is appended to file name if exists: RENAME

Returns:

  • (Hash) —

    metadata of moved file

Raises:



448
449
450
 
# File 'lib/cloudfs/rest_adapter.rb', line 448

def move_file(path, destination, name, exists: 'RENAME')
  move(Constants::ENDPOINT_FILES, path, destination, name, exists: exists)
end

#move_folder(path, destination, name, exists: 'FAIL') ⇒ Object

Raises:



431
432
433
 
# File 'lib/cloudfs/rest_adapter.rb', line 431

def move_folder(path, destination, name, exists: 'FAIL')
  move(Constants::ENDPOINT_FOLDERS, path, destination, name, exists: exists)
end

#ping ⇒ Object

Ping cloudfs server to verifies the end-user’s access token

Returns:

Raises:



174
175
176
177
178
 
# File 'lib/cloudfs/rest_adapter.rb', line 174

def ping
  request('GET', uri: {endpoint: Constants::ENDPOINT_PING},
          header: Constants::HEADER_CONTENT_TYPE_APP_URLENCODED)
  true
end

#promote_file_version(path, version) ⇒ Hash

Given a specified version, set that version’s metadata to current metadata for the file, creating a new version in the process

Parameters:

  • path (String) —

    file path

  • version (Fixnum) —

    version of file specified by path

Returns:

  • (Hash) —

    update metadata with new version number

Raises:



797
798
799
800
801
802
803
804
805
806
807
808
 
# File 'lib/cloudfs/rest_adapter.rb', line 797

def promote_file_version(path, version)
  fail Errors::ArgumentError,
       'Invalid argument, must pass valid path' if Utils.is_blank?(path)
  fail Errors::ArgumentError,
       'Invalid argument, must pass valid version' unless version.is_a?(Fixnum)

  uri = set_uri_params(Constants::ENDPOINT_FILES, name: path,
                       operation: "versions/#{version}")
  query = {operation: Constants::QUERY_OPS_PROMOTE}

  request('POST', uri: uri, query: query)
end

#receive_share(share_key, path: nil, exists: 'RENAME') ⇒ Array<Hash>

Add contents of share to user's filesystem

Parameters:

  • share_key (String) —

    id of the share

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

    default root, path in user's account to receive share at

  • exists (String) (defaults to: 'RENAME') —

    ('RENAME', 'FAIL', 'OVERWRITE']

Returns:

  • (Array<Hash>) —

    metadata of files and folders in share

Raises:



934
935
936
937
938
939
940
941
942
943
944
945
 
# File 'lib/cloudfs/rest_adapter.rb', line 934

def receive_share(share_key, path: nil, exists: 'RENAME')
  fail Errors::ArgumentError,
       'Invalid argument, must pass valid share key' if Utils.is_blank?(share_key)
  exists = Constants::EXISTS.fetch(exists.to_sym) {
    fail Errors::ArgumentError, 'Invalid value for exists' }

  uri = set_uri_params(Constants::ENDPOINT_SHARES, name: "#{share_key}/")
  form = {exists: exists}
  form[:path] = path unless Utils.is_blank?(path)

  request('POST', uri: uri, body: form)
end

#recover_trash_item(path, restore: 'FAIL', destination: nil) ⇒ Object

Recover trash item

Parameters:

  • path (String) —

    path to location in user's trash

  • restore (String) (defaults to: 'FAIL') —

    ('FAIL', 'RESCUE', 'RECREATE') action to take if recovery operation encounters issues

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

    rescue (default root) or recreate(named path) path depending on exists option to place item into if the original path does not exist

Raises:



1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
 
# File 'lib/cloudfs/rest_adapter.rb', line 1061

def recover_trash_item(path, restore: 'FAIL', destination: nil)
  fail Errors::ArgumentError,
       'Invalid argument, must pass valid path' if Utils.is_blank?(path)
  restore = Constants::RESTORE_METHOD.fetch(restore.to_sym) {
    fail Errors::ArgumentError, 'Invalid value for restore' }

  uri = set_uri_params(Constants::ENDPOINT_TRASH, name: path)

  form = {:'restore' => restore}
  if restore == Constants::RESTORE_METHOD[:RESCUE]
    unless Utils.is_blank?(destination)
      destination = prepend_path_with_forward_slash(destination)
      form[:'rescue-path'] = destination
    end
  elsif restore == Constants::RESTORE_METHOD[:RECREATE]
    unless Utils.is_blank?(destination)
      destination = prepend_path_with_forward_slash(destination)
      form[:'recreate-path'] = destination
    end
  end

  request('POST', uri: uri, body: form)
end

#unlink ⇒ Object

Note:

this will disconnect all keep alive connections and internal

Unlinks this rest_adapter object from cloudfs user's account

sessions



122
123
124
125
126
127
128
 
# File 'lib/cloudfs/rest_adapter.rb', line 122

def unlink
  if @access_token
    @access_token = ''
    @http_connection.unlink
  end
  true
end

#unlock_share(share_key, password) ⇒ Object

Unlock share

Parameters:

  • share_key (String) —

    id of the share

  • password (String) —

    password of share

Raises:



954
955
956
957
958
959
960
961
962
963
964
965
 
# File 'lib/cloudfs/rest_adapter.rb', line 954

def unlock_share(share_key, password)
  fail Errors::ArgumentError,
       'Invalid argument, must pass valid path' if Utils.is_blank?(share_key)
  fail Errors::ArgumentError,
       'Invalid argument, must pass valid path' if Utils.is_blank?(password)

  uri = set_uri_params(Constants::ENDPOINT_SHARES, name: share_key,
                       operation: 'unlock')
  form = {password: password}

  request('POST', uri: uri, body: form)
end

#upload(path, source, name: nil, exists: 'FAIL') ⇒ Hash

TODO:

reuse fallback and reuse attributes

Note:

name must be set if source does not respond to #path

Upload file

Examples:

Upload file
	::File.open(local_file_path, "r") do |file|
		rest_adapter.upload(path, file, name: "testfile.txt")
	end
Upload string
	rest_adapter.upload(path, "This is upload string", name: 'testfile.txt')

Upload stream
	io = StringIO.new
	io.write("this is test stringio")
	rest_adapter.upload(path, io, name: 'testfile.txt')
	io.close

Parameters:

  • path (String) —

    path to upload file to

  • source (#read&#pos&#pos=, String) —

    any object that responds to first set of methods or is an in-memory string

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

    name of uploaded file, must be set if source does not respond to #path

  • exists (String) (defaults to: 'FAIL') —

    ('FAIL', 'OVERWRITE', 'RENAME', 'REUSE') action to take if the filename of the file being uploaded conflicts with an existing file

Returns:

  • (Hash) —

    metadata of uploaded file

Raises:



669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
 
# File 'lib/cloudfs/rest_adapter.rb', line 669

def upload(path, source, name: nil, exists: 'FAIL')
  exists = Constants::EXISTS.fetch(exists.to_sym) {
    fail Errors::ArgumentError, 'Invalid value for exists' }

  if source.respond_to?(:path)
    name ||= ::File.basename(source.path)
  elsif Utils.is_blank?(name)
    fail Errors::ArgumentError, 'Invalid argument, custom name is required if source does not respond to path'
  end

  if source.respond_to?(:pos) && source.respond_to?(:pos=)
    original_pos = source.pos
    # Setting source offset to start of stream
    source.pos=0
  end

  uri = set_uri_params(Constants::ENDPOINT_FILES, name: path)
  form = {file: source, exists: exists}
  form[:name] = name

  headers = {
      Constants::HEADER_CONTENT_TYPE => Constants::CONTENT_TYPE_MULTI
  }

  begin
    request('POST', uri: uri, header: headers, body: form)
  ensure
    # Reset source offset to original position
    source.pos=original_pos if source.respond_to?(:pos=)
  end
end