Module: Terminal

Defined in:
lib/terminal.com.rb,
lib/terminal.com/api.rb

Defined Under Namespace

Classes: API, NetworkError

Constant Summary collapse

VERSION =

The gem version.

'1.0.1'
API_VERSION =

The Terminal.com API version.

'v0.1'
HEADERS =

The default headers for the requests.

{'Content-Type' => 'application/json'}

BROWSE SNAPSHOTS & USERS collapse

CREATE AND MANAGE TERMINALS collapse

CREATE AND MANAGE SNAPSHOTS collapse

MANAGE TERMINAL ACCESS collapse

MANAGE TERMINAL DNS & DOMAINS collapse

MANAGE TERMINAL IDLE SETTINGS collapse

MANAGE USAGE & CREDITS collapse

MANAGE SSH PUBLIC KEYS collapse

TERMINAL PASSWORDS collapse

OTHER collapse

IMPLEMENTATION collapse

Class Method Details

.add_authorized_key_to_ssh_proxy(user_token, access_token, name, publicKey) ⇒ Hash

Add an SSH public key to our SSH proxy.

Parameters:

  • name (String) —

    desc.

  • publicKey (String) —

    desc.

  • user_token (String) —

    Your user token.

  • access_token (String) —

    Your access token.

Returns:

  • (Hash) —

    The response data parsed from JSON.

Raises:

See Also:

Since:

  • 0.0.1



890
891
892
893
894
895
896
 
# File 'lib/terminal.com.rb', line 890

def self.add_authorized_key_to_ssh_proxy(user_token, access_token, name, publicKey)
  call('/add_authorized_key_to_ssh_proxy',
    user_token: user_token,
    access_token: access_token,
    name: name,
    publicKey: publicKey)
end

.add_authorized_key_to_terminal(user_token, access_token, container_key, publicKey) ⇒ Hash

Add an SSH public key to a given Terminal’s root user.

Parameters:

  • publicKey (String) —

    desc.

  • container_key (String) —

    A valid container key. You can get it through list_terminals.

  • user_token (String) —

    Your user token.

  • access_token (String) —

    Your access token.

Returns:

  • (Hash) —

    The response data parsed from JSON.

Raises:

See Also:

Since:

  • 0.0.1



871
872
873
874
875
876
877
 
# File 'lib/terminal.com.rb', line 871

def self.add_authorized_key_to_terminal(user_token, access_token, container_key, publicKey)
  call('/add_authorized_key_to_terminal',
    user_token: user_token,
    access_token: access_token,
    container_key: container_key,
    publicKey: publicKey)
end

.add_cname_record(user_token, access_token, domain, subdomain, port) ⇒ Hash

Map a domain in your CNAME record pool to one of your Terminal instances, making it accessible via that domain.

Examples:

Terminal.add_cname_record(user_token, access_token, 'terminal.101ideas.cz', 'botanicus117', 3000)
# {"available" => [...], "assigned" => [{"domain" => "terminal.101ideas.cz", "subdomain" => "botanicus117", "port" => "3000"}]}

Parameters:

  • subdomain (String) —

    Subdomain of the Terminal you want the domain assigned to.

  • port (String) —

    Which port on the Terminal should it point to? This will typically be either ‘80` if you’re using Apache or Nginx or any other number if you’re using say Thin or Puma.

  • domain (String) —

    A domain (i. e. ‘101ideas.cz`).

  • user_token (String) —

    Your user token.

  • access_token (String) —

    Your access token.

Returns:

  • (Hash) —

    The response data parsed from JSON.

Raises:

See Also:

Since:

  • 0.0.1



621
622
623
624
625
626
627
628
 
# File 'lib/terminal.com.rb', line 621

def self.add_cname_record(user_token, access_token, domain, subdomain, port)
  call('/add_cname_record',
    user_token: user_token,
    access_token: access_token,
    domain: domain,
    subdomain: subdomain,
    port: port)
end

.add_domain_to_pool(user_token, access_token, domain) ⇒ Hash

Add a domain or subdomain of Terminal.com to your CNAME record pool, making it available to be associated with one of your Terminal instances.

Parameters:

  • domain (String) —

    A domain (i. e. ‘101ideas.cz`).

  • user_token (String) —

    Your user token.

  • access_token (String) —

    Your access token.

Returns:

  • (Hash) —

    The response data parsed from JSON.

Raises:

See Also:

Since:

  • 0.0.1



583
584
585
586
 
# File 'lib/terminal.com.rb', line 583

def self.add_domain_to_pool(user_token, access_token, domain)
  call('/add_domain_to_pool',
    user_token: user_token, access_token: access_token, domain: domain)
end

.add_terminal_links(user_token, access_token, container_key, *links) ⇒ Hash

Add to the list of your other Terminals who have access to one of your Terminal instances.

Currently this feature doesn’t have GUI, so don’t be surprised if you haven’t come across it yet.

Examples:

container_key = "1123587c-7aec-4b91-90c1-2de534033989"
link = {port: 3000, source: "botanicus117"}
Terminal.add_terminal_links(user_token, access_token, container_key, link)
# {"status":"success"}

Parameters:

  • links (Array<Hash>) —

    Links are hashes with keys ‘port` and `source`. Port is any port number and source is any subdomain (i. e. `botanicus117`).

  • container_key (String) —

    A valid container key. You can get it through list_terminals.

  • user_token (String) —

    Your user token.

  • access_token (String) —

    Your access token.

Returns:

  • (Hash) —

    The response data parsed from JSON.

Raises:

See Also:

Since:

  • 0.0.1



473
474
475
476
477
478
479
 
# File 'lib/terminal.com.rb', line 473

def self.add_terminal_links(user_token, access_token, container_key, *links)
  call('/add_terminal_links',
    user_token: user_token,
    access_token: access_token,
    container_key: container_key,
    links: links)
end

.add_terminal_password(user_token, access_token, container_key, name, password, port) ⇒ Hash

Assign login/password to a Terminal/port combination.

Parameters:

  • password (String) —

    An arbitrary password.

  • port (String) —

    A number, ‘IDE’ or ‘*’.

  • name (String) —

    An arbitrary identifier.

  • container_key (String) —

    A valid container key. You can get it through list_terminals.

  • user_token (String) —

    Your user token.

  • access_token (String) —

    Your access token.

Returns:

  • (Hash) —

    The response data parsed from JSON.

Raises:

See Also:

  • So far this is undocumented.

Since:

  • 0.0.4



944
945
946
947
948
949
950
951
952
 
# File 'lib/terminal.com.rb', line 944

def self.add_terminal_password(user_token, access_token, container_key, name, password, port)
  call('/add_terminal_password',
    user_token: user_token,
    access_token: access_token,
    container_key: container_key,
    name: name,
    password: password,
    port: port)
end

.balance(user_token, access_token) ⇒ Hash

Get the current balance of your account.

Examples:

Terminal.balance(user_token, access_token)
# {"balance" => 675.879}

Parameters:

  • user_token (String) —

    Your user token.

  • access_token (String) —

    Your access token.

Returns:

  • (Hash) —

    The response data parsed from JSON.

Raises:

See Also:

Since:

  • 0.0.1



768
769
770
 
# File 'lib/terminal.com.rb', line 768

def self.balance(user_token, access_token)
  call('/balance', user_token: user_token, access_token: access_token)
end

.balance_added(user_token, access_token) ⇒ Hash

Get a history of credits added to your account balance.

Examples:

Terminal.balance_added(user_token, access_token)
# {"events" => [{"reason" => "Terminal.com sign up gift!", "amount" => 5, "time" => 1411652507924}], "total" => 5}

Parameters:

  • user_token (String) —

    Your user token.

  • access_token (String) —

    Your access token.

Returns:

  • (Hash) —

    The response data parsed from JSON.

Raises:

See Also:

Since:

  • 0.0.1



784
785
786
 
# File 'lib/terminal.com.rb', line 784

def self.balance_added(user_token, access_token)
  call('/balance_added', user_token: user_token, access_token: access_token)
end

.burn_estimates(user_token, access_token) ⇒ Hash

Get a summary of the charges to your account, based on each Terminal instance that you have provisioned. Note that inactive and paused terminals do not incur charges.

Parameters:

  • user_token (String) —

    Your user token.

  • access_token (String) —

    Your access token.

Returns:

  • (Hash) —

    The response data parsed from JSON.

Raises:

See Also:

Since:

  • 0.0.1



854
855
856
 
# File 'lib/terminal.com.rb', line 854

def self.burn_estimates(user_token, access_token)
  call('/burn_estimates', user_token: user_token, access_token: access_token)
end

.burn_history(user_token, access_token) ⇒ Hash

Get a history of charges to your account balance.

Parameters:

  • user_token (String) —

    Your user token.

  • access_token (String) —

    Your access token.

Returns:

  • (Hash) —

    The response data parsed from JSON.

Raises:

See Also:

Since:

  • 0.0.1



816
817
818
 
# File 'lib/terminal.com.rb', line 816

def self.burn_history(user_token, access_token)
  call('/burn_history', user_token: user_token, access_token: access_token)
end

.burn_state(user_token, access_token) ⇒ Hash

Get a summary of current active charges being billed to your account.

Parameters:

  • user_token (String) —

    Your user token.

  • access_token (String) —

    Your access token.

Returns:

  • (Hash) —

    The response data parsed from JSON.

Raises:

See Also:

Since:

  • 0.0.1



840
841
842
 
# File 'lib/terminal.com.rb', line 840

def self.burn_state(user_token, access_token)
  call('/burn_state', user_token: user_token, access_token: access_token)
end

.call(path, data) ⇒ Object

Make the HTTP call, retrieve and parse the JSON response. Rewrite this method if you wish to use a different HTTP library.

Raises:

  • (Terminal::NetworkError) —

    Any network-layer error. It’s important that plugins make sure to wrap their potential exceptions in Terminal::NetworkError for predictable behaviour.

Since:

  • 0.0.1



1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
 
# File 'lib/terminal.com.rb', line 1047

def self.call(path, data)
  path = "/#{API_VERSION}#{path}"
  json = data.to_json

  curl_debug(path, data.to_json)

  response = request.post(path, json, HEADERS)
  status   = response.code.to_i

  return parse_json(response.body) if status == 200

  raise "Unexpected status #{status}: #{response.inspect}"
rescue SocketError => error
  raise NetworkError.new(error)
end

.convert_timestamps_to_time(hash) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

We are ignoring timestamps in arrays since there are none in the API. Also, JSON document doesn’t have to be an object, but in Terminal.com API, they all are. TODO: Test it.



1086
1087
1088
1089
1090
1091
1092
1093
1094
 
# File 'lib/terminal.com.rb', line 1086

def self.convert_timestamps_to_time(hash)
  hash.each do |key, value|
    if value.is_a?(Hash)
      convert_timestamps_to_time(value)
    elsif value.is_a?(String) && value.match(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d+Z$/)
      hash[key] = Time.parse(value)
    end
  end
end

.count_public_snapshots(**options) ⇒ Hash

Get a count of public snapshots, optionally filtered.

Examples:

Count of all the public snapshots.

Terminal.count_public_snapshots
# {"snapshot_count" => 474}

Count of all the featured snapshots.

Terminal.count_public_snapshots(featured: true)
# {"snapshot_count" => 135}

Parameters:

  • options (Hash) —

    Filtering options.

Options Hash (**options):

  • :username (String) —

    Any valid username (i. e. ‘botanicus`).

  • :tag (String) —

    Any tag (i. e. ‘ubuntu`).

  • :featured (true, false) —

    Search only for featured (or non-featured).

  • :title (String) —

    Title to be matched against the existing snapshots.

Returns:

  • (Hash) —

    The response data parsed from JSON.

Raises:

See Also:

Since:

  • 0.0.1



94
95
96
97
98
99
 
# File 'lib/terminal.com.rb', line 94

def self.count_public_snapshots(**options)
  ensure_options_validity(options,
    :username, :tag, :featured, :title)

  call('/count_public_snapshots', options)
end

.count_snapshots(user_token, access_token, **options) ⇒ Hash

Get a count of snapshots owned by your account, optionally filtered by the owner’s username, a tag, or the snapshot’s featured status. You may use a combination of filters.

Examples:

Number of all the snapshots owned by your account.

Terminal.count_snapshots(user_token, access_token)
# {"snapshot_count" => 12}

Number of all the featured snapshots owned by your account.

Terminal.count_public_snapshots(user_token, access_token, featured: true)
# {"snapshot_count" => 2}

Parameters:

  • options (Hash) —

    Filtering options.

  • user_token (String) —

    Your user token.

  • access_token (String) —

    Your access token.

Options Hash (**options):

  • :username (String) —

    Any valid username (i. e. ‘botanicus`).

  • :tag (String) —

    Any tag (i. e. ‘ubuntu`).

  • :featured (true, false) —

    Search only for featured (or non-featured).

  • :title (String) —

    Title to be matched against the existing snapshots.

Returns:

  • (Hash) —

    The response data parsed from JSON.

Raises:

See Also:

Since:

  • 0.0.1



381
382
383
384
385
386
387
388
 
# File 'lib/terminal.com.rb', line 381

def self.count_snapshots(user_token, access_token, **options)
  ensure_options_validity(options,
    :username, :tag, :featured, :title)

  options.merge!(user_token: user_token, access_token: access_token)

  call('/count_snapshots', options)
end

.curl_debug(path, json) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
 
# File 'lib/terminal.com.rb', line 1064

def self.curl_debug(path, json)
  return if ENV['DBG'].nil?

  headers = HEADERS.reduce(Array.new) do |buffer, (key, value)|
    buffer << "#{key}: #{value}"
  end.join(' ')

  STDERR.puts <<-EOF
curl -L -X POST -H '#{headers}' -d '#{json}' https://api.terminal.com#{path}
  EOF
end

.del_authorized_key_from_ssh_proxy(user_token, access_token, name, fingerprint) ⇒ Hash

Delete an SSH public key from our SSH proxy.

Parameters:

  • name (String) —

    TODO.

  • fingerprint (String) —

    TODO.

  • user_token (String) —

    Your user token.

  • access_token (String) —

    Your access token.

Returns:

  • (Hash) —

    The response data parsed from JSON.

Raises:

See Also:

Since:

  • 0.0.1



909
910
911
912
913
914
915
 
# File 'lib/terminal.com.rb', line 909

def self.del_authorized_key_from_ssh_proxy(user_token, access_token, name, fingerprint)
  call('/del_authorized_key_from_ssh_proxy',
    user_token: user_token,
    access_token: access_token,
    name: name,
    fingerprint: fingerprint)
end

.delete_snapshot(user_token, access_token, snapshot_id) ⇒ Hash

Delete a snapshot from your account. This cannot be undone.

Parameters:

  • user_token (String) —

    Your user token.

  • access_token (String) —

    Your access token.

  • snapshot_id (String) —

    Snapshot ID (the last part of the snapshot URL).

Returns:

  • (Hash) —

    The response data parsed from JSON.

Raises:

See Also:

Since:

  • 0.0.1



399
400
401
402
403
404
 
# File 'lib/terminal.com.rb', line 399

def self.delete_snapshot(user_token, access_token, snapshot_id)
  call('/delete_snapshot',
    user_token: user_token,
    access_token: access_token,
    snapshot_id: snapshot_id)
end

.delete_terminal(user_token, access_token, container_key) ⇒ Hash

Delete a Terminal instance.

Parameters:

  • container_key (String) —

    A valid container key. You can get it through list_terminals.

  • user_token (String) —

    Your user token.

  • access_token (String) —

    Your access token.

Returns:

  • (Hash) —

    The response data parsed from JSON.

Raises:

See Also:

Since:

  • 0.0.1



241
242
243
244
 
# File 'lib/terminal.com.rb', line 241

def self.delete_terminal(user_token, access_token, container_key)
  call('/delete_terminal',
    user_token: user_token, access_token: access_token, container_key: container_key)
end

.edit_snapshot(user_token, access_token, snapshot_id, **options) ⇒ Hash

Edit the metadata of a snapshot owned by your account.

Parameters:

  • options (Hash) —

    New snapshot metadata.

Options Hash (**options):

  • :body (String) —

    The snapshot description.

  • :title (String) —

    The snapshot title.

  • :readme (String) —

    The README.

  • :tags (String) —

    Comma-separated list of tags (i. e. ‘ubuntu,ruby`).

  • :public (Boolean) —

    Whether the snapshot will be accessible by other users.

  • :custom_data (String) —

    Metadata of your Terminal. Anything you need. It will be accessible through get_terminal, but not from within the Terminal itself.

Returns:

  • (Hash) —

    The response data parsed from JSON.

Raises:

See Also:

Since:

  • 0.0.1



422
423
424
425
426
427
428
429
 
# File 'lib/terminal.com.rb', line 422

def self.edit_snapshot(user_token, access_token, snapshot_id, **options)
  ensure_options_validity(options,
    :body, :title, :readme, :tags, :public, :custom_data)

  options.merge!(user_token: user_token, access_token: access_token, snapshot_id: snapshot_id)

  call('/edit_snapshot', options)
end

.edit_terminal(user_token, access_token, container_key, **options) ⇒ Object

See Also:

Since:

  • 0.0.1



315
316
317
318
319
320
321
322
323
324
325
 
# File 'lib/terminal.com.rb', line 315

def self.edit_terminal(user_token, access_token, container_key, **options)
  ensure_both_cpu_and_ram_are_provided(options)
  ensure_options_present(options, :cpu, :ram, :diskspace)

  ensure_options_validity(options,
    :cpu, :ram, :diskspace, :name)

  options.merge!(user_token: user_token, access_token: access_token, container_key: container_key)

  call('/edit_terminal', options)
end

.edit_terminal_access(user_token, access_token, container_key, **options) ⇒ Hash

Edit the list of users and emails who have access to one of your Terminal instances.

Parameters:

  • options (Hash) —

    Access rules.

  • container_key (String) —

    A valid container key. You can get it through list_terminals.

  • user_token (String) —

    Your user token.

  • access_token (String) —

    Your access token.

Options Hash (**options):

  • :is_public_list (Array) —

    List of open ports. Port ‘80` is open by default, you can add additional ports.

  • :access_rules (Array) —

    Array of access rules. An access rule is ‘<port>::<email>`. Port can be a port number, `IDE` or an asterisk and email can contain asterisks. Examples: `“3000::*@cloudlabs.io”`, `“*::[email protected]”, `“IDE::[email protected]”`.

Returns:

  • (Hash) —

    The response data parsed from JSON.

Raises:

See Also:

Since:

  • 0.0.1



540
541
542
543
544
545
546
 
# File 'lib/terminal.com.rb', line 540

def self.edit_terminal_access(user_token, access_token, container_key, **options)
  ensure_options_validity(options, :is_public_list, :access_rules)

  options.merge!(user_token: user_token, access_token: access_token, container_key: container_key)

  call('/edit_terminal_access', options)
end

.ensure_both_cpu_and_ram_are_provided(options) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



1106
1107
1108
1109
1110
 
# File 'lib/terminal.com.rb', line 1106

def self.ensure_both_cpu_and_ram_are_provided(options)
  if (options[:cpu] && ! options[:ram]) || (options[:ram] && ! options[:cpu])
    raise ArgumentError.new('You have to specify both cpu and ram of the corresponding instance type as described at https://www.terminal.com/faq#instanceTypes')
  end
end

.ensure_options_present(options, *required_keys) ⇒ Object 



1112
1113
1114
1115
1116
1117
1118
 
# File 'lib/terminal.com.rb', line 1112

def self.ensure_options_present(options, *required_keys)
  required_keys.each do |key|
    unless options.has_key?(key)
      raise ArgumentError.new("Option #{key} is required, but is missing.")
    end
  end
end

.ensure_options_validity(options, *valid_keys) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



1097
1098
1099
1100
1101
1102
1103
 
# File 'lib/terminal.com.rb', line 1097

def self.ensure_options_validity(options, *valid_keys)
  unrecognised_options = (options.keys - valid_keys)

  unless unrecognised_options.empty?
    raise ArgumentError.new("Unrecognised options: #{unrecognised_options.inspect[1..-2]}")
  end
end

.get_authorized_keys_from_ssh_proxy(user_token, access_token) ⇒ Hash

List the SSH public key on our SSH proxy.

Parameters:

  • user_token (String) —

    Your user token.

  • access_token (String) —

    Your access token.

Returns:

  • (Hash) —

    The response data parsed from JSON.

Raises:

See Also:

Since:

  • 0.0.1



926
927
928
929
 
# File 'lib/terminal.com.rb', line 926

def self.get_authorized_keys_from_ssh_proxy(user_token, access_token)
  call('/get_authorized_keys_from_ssh_proxy',
    user_token: user_token, access_token: access_token)
end

.get_cname_records(user_token, access_token) ⇒ Hash

Get a list of domains in your CNAME record pool. Domains returned by this call can be associated to your Terminal instances.

Examples:

Terminal.get_cname_records(user_token, access_token)
# {"available" => ["101ideas.cz", "terminal.101ideas.cz"]], "assigned": []}

Parameters:

  • user_token (String) —

    Your user token.

  • access_token (String) —

    Your access token.

Returns:

  • (Hash) —

    The response data parsed from JSON.

Raises:

See Also:

Since:

  • 0.0.1



566
567
568
569
 
# File 'lib/terminal.com.rb', line 566

def self.get_cname_records(user_token, access_token)
  call('/get_cname_records',
    user_token: user_token, access_token: access_token)
end

.get_profile(username) ⇒ Hash

Get information on a user.

Examples:

Terminal.get_profile('botanicus')
# {"user" => {"name" => "James C Russell", "url" => "https://twitter.com/botanicus", "location" => "London, UK", ...}}

Parameters:

  • username (String) —

    Any valid username (i. e. ‘botanicus`).

Returns:

  • (Hash) —

    The response data parsed from JSON.

Raises:

See Also:

Since:

  • 0.0.1



70
71
72
 
# File 'lib/terminal.com.rb', line 70

def self.get_profile(username)
  call('/get_profile', username: username)
end

.get_snapshot(snapshot_id) ⇒ Hash

Get information on a snapshot.

Examples:

Terminal.get_snapshot('987f8d702dc0a6e8158b48ccd3dec24f819a7ccb2756c396ef1fd7f5b34b7980')
# {"snapshot" => {"title" => "Official Ubuntu 14.04", "tags" => "ubuntu", "createdAt" => "2014-07-23T20:27:41.743Z", ...}}

Parameters:

  • snapshot_id (String) —

    Snapshot ID (the last part of the snapshot URL).

Returns:

  • (Hash) —

    The response data parsed from JSON.

Raises:

See Also:

Since:

  • 0.0.1



54
55
56
 
# File 'lib/terminal.com.rb', line 54

def self.get_snapshot(snapshot_id)
  call('/get_snapshot', snapshot_id: snapshot_id)
end

.get_terminal(user_token, access_token, **options) ⇒ Hash

Get info about a Terminal instance of yours. You can specify either ‘container_key` or `subdomain`.

Examples:

Get Terminal info with a container_key.

# Using get_terminal directly with list_terminals doesn't really
# make sense, since you get all the data in list_terminals, so there
# is no need to call get_terminal. This is just to show how you
# can get your container key. It works the same with a subdomain.
terminals = Terminal.list_terminals(user_token, access_token)
container_key = terminals['terminals'].first['container_key']

Terminal.get_terminal(user_token, access_token, container_key: container_key)
# {"terminal" => {"name" => "Coding Interview: John Doe Jr", "ram" => "256", ...}}

Parameters:

  • options (Hash) —

    Provide either ‘container_key` or `subdomain`.

  • user_token (String) —

    Your user token.

  • access_token (String) —

    Your access token.

Options Hash (**options):

  • :container_key (String) —

    A valid container key. You can get it through list_terminals.

  • :subdomain (String) —

    Subdomain of your Terminal (i. e. ‘johndoe117`). You can see it in the address bar when you’re in the Terminal IDE or through list_terminals.

Returns:

  • (Hash) —

    The response data parsed from JSON.

Raises:

See Also:

Since:

  • 0.0.1



177
178
179
180
181
182
183
 
# File 'lib/terminal.com.rb', line 177

def self.get_terminal(user_token, access_token, **options)
  ensure_options_validity(options, :container_key, :subdomain)

  options.merge!(user_token: user_token, access_token: access_token)

  call('/get_terminal', options)
end

.get_terminal_idle_settings(user_token, access_token, container_key) ⇒ Hash

Get the idle settings for your terminal.

Examples:

container_key = 'b878c064-fc2b-4f14-81fa-ca10ac9385ff'
Terminal.get_terminal_idle_settings(user_token, access_token, container_key)
# {"success": true,
#  "settings": {
#    "action": "pause",
#    "triggers": {
#      "cpu_load": {
#        "timeout": 3600,
#        "threshold": 10
#      },
#      "last_request": {
#        "timeout": 3600
#      }
#    }
#  }
# }

Parameters:

  • container_key (String) —

    A valid container key. You can get it through list_terminals.

  • user_token (String) —

    Your user token.

  • access_token (String) —

    Your access token.

Returns:

  • (Hash) —

    The response data parsed from JSON.

Raises:

See Also:

Since:

  • 0.0.1



703
704
705
706
707
708
 
# File 'lib/terminal.com.rb', line 703

def self.get_terminal_idle_settings(user_token, access_token, container_key)
  call('/get_terminal_idle_settings',
    user_token: user_token,
    access_token: access_token,
    container_key: container_key)
end

.gift(user_token, access_token, email, cents) ⇒ Hash

Gift some of your credits to another user. Denominated in whole integer US cents ($0.01). You may only gift credits if you have previously purchased credits.

Parameters:

  • email (String) —

    User email.

  • cents (String) —

    US cents.

  • user_token (String) —

    Your user token.

  • access_token (String) —

    Your access token.

Returns:

  • (Hash) —

    The response data parsed from JSON.

Raises:

See Also:

Since:

  • 0.0.1



800
801
802
803
804
805
806
 
# File 'lib/terminal.com.rb', line 800

def self.gift(user_token, access_token, email, cents)
  call('/gift',
    user_token: user_token,
    access_token: access_token,
    email: email,
    cents: cents)
end

.instance_price(instance_type, status = 'running') ⇒ Hash

Get the hourly pricing for a Terminal instance of a given type. If a instance is stopped, price will be zero.

Examples:

Terminal.instance_price('micro')
# {"price" => 0.006, "units" => "dollars per hour"}

Parameters:

  • instance_type (String) —

    desc.

  • status (String) (defaults to: 'running') —

    Defaults to ‘running`. It doesn’t make sense to set it to anything else: pause instances are not billed.

Returns:

  • (Hash) —

    The response data parsed from JSON.

Raises:

See Also:

Since:

  • 0.0.1



752
753
754
 
# File 'lib/terminal.com.rb', line 752

def self.instance_price(instance_type, status = 'running')
  call('/instance_price', instance_type: instance_type, status: status)
end

.instance_types ⇒ Hash

Get a list of the types of Terminals that may be started, and the specifications for each type (CPU, RAM, and pricing).

Examples:

Terminal.instance_types
# {"instance_types" => {
#   "micro" => {"cpu" => "2 (max)", "ram" => 256, "price" => 0.006},
#   "mini" => {"cpu" => 50, "ram" => 800, "price" => 0.031},
#   "small" => {"cpu" => 100, "ram" => 1600, "price" => 0.062},
#   "medium" => {"cpu" => 200, "ram" => 3200, "price" => 0.124},
#   "xlarge" => {"cpu" => 400, "ram" => 6400, "price" => 0.248},
#   "2xlarge" => {"cpu" => 800, "ram" => 12800, "price" => 0.496},
#   "4xlarge" => {"cpu" => 1600, "ram" => 25600, "price" => 0.992},
#   "8xlarge" => {"cpu" => 3200, "ram" => 51200, "price" => 1.984}}}

Returns:

  • (Hash) —

    The response data parsed from JSON.

Raises:

See Also:

Since:

  • 0.0.1



733
734
735
 
# File 'lib/terminal.com.rb', line 733

def self.instance_types
  call('/instance_types', Hash.new)
end

.list_public_snapshots(**options) ⇒ Hash

Get a list of public snapshots, optionally filtered and/or paginated.

Examples:

Return all the public snapshots.

Terminal.list_public_snapshots
# {"snapshots" => [{"title" => "Decision Tree", "tags" => "python,ipython", ...}, {...}]}

Return all the featured snapshots from user botanicus.

Terminal.list_public_snapshots(username: 'botanicus', featured: true)

Return the first page of the search results with 10 items per page, sorted by date.

Terminal.list_public_snapshots(tag: 'ubuntu', page: 1, perPage: 10, sortby: 'date')

Parameters:

  • options (Hash) —

    Filtering and pagination options.

Options Hash (**options):

  • :page (String) —

    Use with ‘perPage` for pagination.

  • :perPage (String) —

    Use with ‘page` for pagination.

  • :sortby (String) —

    Either ‘popularity` or `date`.

  • :username (String) —

    Any valid username (i. e. ‘botanicus`).

  • :tag (String) —

    Any tag (i. e. ‘ubuntu`).

  • :featured (true, false) —

    Search only for featured (or non-featured).

  • :title (String) —

    Title to be matched against the existing snapshots.

Returns:

  • (Hash) —

    The response data parsed from JSON.

Raises:

See Also:

Since:

  • 0.0.1



124
125
126
127
128
129
 
# File 'lib/terminal.com.rb', line 124

def self.list_public_snapshots(**options)
  ensure_options_validity(options,
    :username, :tag, :featured, :title, :page, :perPage, :sortby)

  call('/list_public_snapshots', options)
end

.list_snapshots(user_token, access_token, **options) ⇒ Hash

Get a list of snapshots owned by your account, optionally filtered by the owner’s username, a tag, or the snapshot’s featured status. You may use a combination of filters.

Examples:

Return all the snapshots owned by your account.

Terminal.list_snapshots(user_token, access_token)
# {"snapshots" => [{"title" => "Decision Tree", "tags" => "python,ipython", ...}, {...}]}

Return all the featured snapshots owned by your account.

Terminal.list_snapshots(user_token, access_token, featured: true)

Return the first page of the search results with 10 items per page, sorted by date.

Terminal.list_snapshots(user_token, access_token, tag: 'ubuntu', page: 1, perPage: 10, sortby: 'date')

Parameters:

  • options (Hash) —

    Filtering and pagination options.

  • user_token (String) —

    Your user token.

  • access_token (String) —

    Your access token.

Options Hash (**options):

  • :page (String) —

    Use with ‘perPage` for pagination.

  • :perPage (String) —

    Use with ‘page` for pagination.

  • :sortby (String) —

    Either ‘popularity` or `date`.

  • :username (String) —

    Any valid username (i. e. ‘botanicus`).

  • :tag (String) —

    Any tag (i. e. ‘ubuntu`).

  • :featured (true, false) —

    Search only for featured (or non-featured).

  • :title (String) —

    Title to be matched against the existing snapshots.

Returns:

  • (Hash) —

    The response data parsed from JSON.

Raises:

See Also:

Since:

  • 0.0.1



352
353
354
355
356
357
358
359
 
# File 'lib/terminal.com.rb', line 352

def self.list_snapshots(user_token, access_token, **options)
  ensure_options_validity(options,
    :username, :tag, :featured, :title, :page, :perPage)

  options.merge!(user_token: user_token, access_token: access_token)

  call('/list_snapshots', options)
end

.list_terminal_access(user_token, access_token, container_key) ⇒ Hash

List users and emails with view or edit access to one of your Terminal instances.

Examples:

Terminal.list_terminal_access(user_token, access_token, "268b0082-c96c-4c74-bf0a-a5d6d4c16b01")
# {"is_public_list" => ["80", "3000"],
#  "access_rules" => ["3000::*@cloudlabs.io", "*::[email protected]", "IDE::[email protected]", "IDE::[email protected]"],
#  "links"=>["3000::botanicus117"]}

Parameters:

  • container_key (String) —

    A valid container key. You can get it through list_terminals.

  • user_token (String) —

    Your user token.

  • access_token (String) —

    Your access token.

Returns:

  • (Hash) —

    The response data parsed from JSON.

Raises:

See Also:

Since:

  • 0.0.1



514
515
516
517
518
519
 
# File 'lib/terminal.com.rb', line 514

def self.list_terminal_access(user_token, access_token, container_key)
  call('/list_terminal_access',
    user_token: user_token,
    access_token: access_token,
    container_key: container_key)
end

.list_terminal_passwords(user_token, access_token, container_key) ⇒ Hash

List all the assigned Terminal logins and the ports they are assigned to.

Parameters:

  • container_key (String) —

    A valid container key. You can get it through list_terminals.

  • user_token (String) —

    Your user token.

  • access_token (String) —

    Your access token.

Returns:

  • (Hash) —

    The response data parsed from JSON.

Raises:

See Also:

  • So far this is undocumented.

Since:

  • 0.0.4



962
963
964
965
966
967
 
# File 'lib/terminal.com.rb', line 962

def self.list_terminal_passwords(user_token, access_token, container_key)
  call('/list_terminal_passwords',
    user_token: user_token,
    access_token: access_token,
    container_key: container_key)
end

.list_terminals(user_token, access_token) ⇒ Hash

Get a list of all Terminal instances owned by your account.

Examples:

Terminal.list_terminals(user_token, access_token)
# {"terminals" => [{"name" => "Coding Interview: John Doe Jr", "ram" => "256", ...}, {...}]}

Parameters:

  • user_token (String) —

    Your user token.

  • access_token (String) —

    Your access token.

Returns:

  • (Hash) —

    The response data parsed from JSON.

Raises:

See Also:

Since:

  • 0.0.1



147
148
149
150
 
# File 'lib/terminal.com.rb', line 147

def self.list_terminals(user_token, access_token)
  call('/list_terminals',
    user_token: user_token, access_token: access_token)
end

.parse_json(json) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



1077
1078
1079
 
# File 'lib/terminal.com.rb', line 1077

def self.parse_json(json)
  convert_timestamps_to_time(JSON.parse(json))
end

.pause_terminal(user_token, access_token, container_key) ⇒ Hash

Pause a Terminal instance. The instance will be offline and inaccessible, and you will not be charged as long as it remains paused.

Parameters:

  • container_key (String) —

    A valid container key. You can get it through list_terminals.

  • user_token (String) —

    Your user token.

  • access_token (String) —

    Your access token.

Returns:

  • (Hash) —

    The response data parsed from JSON.

Raises:

See Also:

Since:

  • 0.0.1



269
270
271
272
 
# File 'lib/terminal.com.rb', line 269

def self.pause_terminal(user_token, access_token, container_key)
  call('/pause_terminal',
    user_token: user_token, access_token: access_token, container_key: container_key)
end

.remove_cname_record(user_token, access_token, domain) ⇒ Hash

Remove a domain mapping to one of your Terminal instances. This will mean you can no longer access the Terminal instance from that domain.

Parameters:

  • domain (String) —

    A domain (i. e. ‘101ideas.cz`).

  • user_token (String) —

    Your user token.

  • access_token (String) —

    Your access token.

Returns:

  • (Hash) —

    The response data parsed from JSON.

Raises:

See Also:

Since:

  • 0.0.1



641
642
643
644
645
646
 
# File 'lib/terminal.com.rb', line 641

def self.remove_cname_record(user_token, access_token, domain)
  call('/remove_cname_record',
    user_token: user_token,
    access_token: access_token,
    domain: domain)
end

.remove_domain_from_pool(user_token, access_token, domain) ⇒ Hash

Remove a domain or subdomain of Terminal.com from your CNAME record pool.

Parameters:

  • domain (String) —

    A domain (i. e. ‘101ideas.cz`).

  • user_token (String) —

    Your user token.

  • access_token (String) —

    Your access token.

Returns:

  • (Hash) —

    The response data parsed from JSON.

Raises:

See Also:

Since:

  • 0.0.1



598
599
600
601
 
# File 'lib/terminal.com.rb', line 598

def self.remove_domain_from_pool(user_token, access_token, domain)
  call('/remove_domain_from_pool',
    user_token: user_token, access_token: access_token, domain: domain)
end

.remove_terminal_links(user_token, access_token, container_key, *links) ⇒ Hash

Remove from the list of Terminals who have access to one of your Terminal instances.

Parameters:

  • links (Array<Hash>) —

    Links are hashes with keys ‘port` and `source`. Port is any port number and source is any subdomain (i. e. `botanicus117`).

  • container_key (String) —

    A valid container key. You can get it through list_terminals.

  • user_token (String) —

    Your user token.

  • access_token (String) —

    Your access token.

Returns:

  • (Hash) —

    The response data parsed from JSON.

Raises:

See Also:

Since:

  • 0.0.1



490
491
492
493
494
495
496
 
# File 'lib/terminal.com.rb', line 490

def self.remove_terminal_links(user_token, access_token, container_key, *links)
  call('/remove_terminal_links',
    user_token: user_token,
    access_token: access_token,
    container_key: container_key,
    links: links)
end

.remove_terminal_password(user_token, access_token, container_key, name) ⇒ Hash

Remove given login/password from a Terminal.

Parameters:

  • name (String) —

    An arbitrary identifier.

  • container_key (String) —

    A valid container key. You can get it through list_terminals.

  • user_token (String) —

    Your user token.

  • access_token (String) —

    Your access token.

Returns:

  • (Hash) —

    The response data parsed from JSON.

Raises:

See Also:

  • So far this is undocumented.

Since:

  • 0.0.4



978
979
980
981
982
983
984
 
# File 'lib/terminal.com.rb', line 978

def self.remove_terminal_password(user_token, access_token, container_key, name)
  call('/remove_terminal_password',
    user_token: user_token,
    access_token: access_token,
    container_key: container_key,
    name: name)
end

.request ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



1034
1035
1036
 
# File 'lib/terminal.com.rb', line 1034

def self.request
  @request ||= Net::HTTP.new('api.terminal.com')
end

.request_progress(request_id) ⇒ Hash

Get info and status of an API request.

Parameters:

  • request_id (String) —

    desc.

Returns:

  • (Hash) —

    The response data parsed from JSON.

Raises:

See Also:

Since:

  • 0.0.1



1026
1027
1028
 
# File 'lib/terminal.com.rb', line 1026

def self.request_progress(request_id)
  call('/request_progress', request_id: request_id)
end

.restart_terminal(user_token, access_token, container_key) ⇒ Hash

Reboot a Terminal instance.

Parameters:

  • container_key (String) —

    A valid container key. You can get it through list_terminals.

  • user_token (String) —

    Your user token.

  • access_token (String) —

    Your access token.

Returns:

  • (Hash) —

    The response data parsed from JSON.

Raises:

See Also:

Since:

  • 0.0.1



254
255
256
257
 
# File 'lib/terminal.com.rb', line 254

def self.restart_terminal(user_token, access_token, container_key)
  call('/restart_terminal',
    user_token: user_token, access_token: access_token, container_key: container_key)
end

.resume_terminal(user_token, access_token, container_key) ⇒ Hash

Continue running a Terminal instance. The Terminal will continue being charged, and will keep running so long as you maintain a positive balance in your account.

Parameters:

  • container_key (String) —

    A valid container key. You can get it through list_terminals.

  • user_token (String) —

    Your user token.

  • access_token (String) —

    Your access token.

Returns:

  • (Hash) —

    The response data parsed from JSON.

Raises:

See Also:

Since:

  • 0.0.1



284
285
286
287
 
# File 'lib/terminal.com.rb', line 284

def self.resume_terminal(user_token, access_token, container_key)
  call('/resume_terminal',
    user_token: user_token, access_token: access_token, container_key: container_key)
end

.set_terminal_idle_settings(user_token, access_token, container_key, action, triggers) ⇒ Hash

Set the idle settings for your Terminal.

Examples:

Terminal.set_terminal_idle_settings(user_token, access_token, 'b878c064-fc2b-4f14-81fa-ca10ac9385ff', 'pause', cpu_load: {timeout: 5600})
# {"success" => true}

Parameters:

  • action (String) —

    Either ‘downgrade` or `pause`.

  • triggers (Hash<Hash>) —

    Keys can be ‘cpu_load` or `last_request`. Keys of those can be `timeout` and `last_request`

  • container_key (String) —

    A valid container key. You can get it through list_terminals.

  • user_token (String) —

    Your user token.

  • access_token (String) —

    Your access token.

Returns:

  • (Hash) —

    The response data parsed from JSON.

Raises:

See Also:

Since:

  • 0.0.1



667
668
669
670
671
672
673
674
 
# File 'lib/terminal.com.rb', line 667

def self.set_terminal_idle_settings(user_token, access_token, container_key, action, triggers)
  call('/set_terminal_idle_settings',
    user_token: user_token,
    access_token: access_token,
    container_key: container_key,
    action: action,
    triggers: triggers)
end

.snapshot_terminal(user_token, access_token, container_key, **options) ⇒ Hash

Create a snapshot of a Terminal instance.

Parameters:

  • options (Hash) —

    Snapshot metadata.

  • container_key (String) —

    A valid container key. You can get it through list_terminals.

  • user_token (String) —

    Your user token.

  • access_token (String) —

    Your access token.

Options Hash (**options):

  • :body (String) —

    The snapshot description.

  • :title (String) —

    The snapshot title.

  • :readme (String) —

    The README.

  • :tags (String) —

    Comma-separated list of tags (i. e. ‘ubuntu,ruby`).

  • :public (Boolean) —

    Whether the snapshot will be accessible by other users.

  • :custom_data (String) —

    Metadata of your Terminal. Anything you need. It will be accessible through get_terminal, but not from within the Terminal itself.

Returns:

  • (Hash) —

    The response data parsed from JSON.

Raises:

See Also:

Since:

  • 0.0.1



441
442
443
444
445
446
447
448
 
# File 'lib/terminal.com.rb', line 441

def self.snapshot_terminal(user_token, access_token, container_key, **options)
  ensure_options_validity(options,
    :body, :title, :readme, :tags, :public)

  options.merge!(user_token: user_token, access_token: access_token, container_key: container_key)

  call('/snapshot_terminal', options)
end

.start_snapshot(user_token, access_token, snapshot_id, **options) ⇒ Hash

Start a Terminal instance based on a snapshot.

Examples:

response = Terminal.start_snapshot(user_token, access_token, "57eff3574ac8d438224dc3aa1c6431a0dbac849a0c254e89be2e758d8113c234", name: "Test")
# {"request_id" => "1418068796272::[email protected]:create:234509::333c43ab-f6cc-41a3-8307-0fcc4ea3cfb5"}
Terminal.request_progress(response['request_id'])
# {"operation" => "create", "status" => "success", ... }

Parameters:

  • options (Hash) —

    Configuration of the new Terminal.

  • user_token (String) —

    Your user token.

  • access_token (String) —

    Your access token.

  • snapshot_id (String) —

    Snapshot ID (the last part of the snapshot URL).

Options Hash (**options):

  • :cpu (String) —

    How much CPU is required. Has to be one of the available instance types and corresponding ‘:ram` option has to be provided.

  • :ram (String) —

    How much RAM is required. Has to be one of the available instance types and corresponding ‘:cpu` option has to be provided.

  • :temporary (String) —

    If the Terminal is supposed to be temporary or not. Temporary Terminals are automatically deleted on inactivity.

  • :name (String) —

    Terminal name.

  • :autopause (String) —

    Whether the Terminal should be auto-paused on inactivity. This can be edited later using set_terminal_idle_settings.

  • :startup_script (String) —

    Shell script to be run once the Terminal is ready. As of now it cannot contain newlines, so setting a different interpreter than ‘/bin/sh` is impossible.

  • :custom_data (String) —

    Metadata of your Terminal. Anything you need. It will be accessible through get_terminal, but not from within the Terminal itself.

Returns:

  • (Hash) —

    The response data parsed from JSON.

Raises:

  • (ArgumentError) —

    If either ‘ram` or `cpu` is specified. These options has to come together.

  • (Terminal::NetworkError) —

    Any network-layer error.

See Also:

Since:

  • 0.0.1



221
222
223
224
225
226
227
228
229
 
# File 'lib/terminal.com.rb', line 221

def self.start_snapshot(user_token, access_token, snapshot_id, **options)
  ensure_both_cpu_and_ram_are_provided(options)
  ensure_options_validity(options,
    :cpu, :ram, :temporary, :name, :autopause, :startup_script, :custom_data)

  options.merge!(user_token: user_token, access_token: access_token, snapshot_id: snapshot_id)

  call('/start_snapshot', options)
end

.terminal_usage_history(user_token, access_token) ⇒ Hash

Get a history of your Terminal usage.

Parameters:

  • user_token (String) —

    Your user token.

  • access_token (String) —

    Your access token.

Returns:

  • (Hash) —

    The response data parsed from JSON.

Raises:

See Also:

Since:

  • 0.0.1



828
829
830
 
# File 'lib/terminal.com.rb', line 828

def self.terminal_usage_history(user_token, access_token)
  call('/terminal_usage_history', user_token: user_token, access_token: access_token)
end

.who_am_i(user_token, access_token) ⇒ Hash

Get information about yourself! If invalid access/user token provided, returns null (but not an error).

Examples:

Terminal.who_am_i(user_token, access_token)
# {
#   "user": {
#     "name": "James C Russell",
#     "username": "botanicus",
#     "url": "https://twitter.com/botanicus",
#     "company": "",
#     "location": "London, United Kingdom",
#     "balance": 675.879,
#     "email": "[email protected]",
#     "is_admin": false,
#     "profile_image": "//www.gravatar.com/avatar/74c419a50563fa9e5044820c2697ffd6.jpg?s=400&d=mm"
#   }
# }

Parameters:

  • user_token (String) —

    Your user token.

  • access_token (String) —

    Your access token.

Returns:

  • (Hash) —

    The response data parsed from JSON.

Raises:

See Also:

Since:

  • 0.0.1



1014
1015
1016
 
# File 'lib/terminal.com.rb', line 1014

def self.who_am_i(user_token, access_token)
  call('/who_am_i', user_token: user_token, access_token: access_token)
end