Class: Nucleus::Adapters::V1::Stub Abstract

Inherits:
BaseAdapter show all
Defined in:
lib/nucleus/adapters/v1/stub_adapter.rb

Overview

This class is abstract.

Stub adapter for Nucleus API version 1.
The stub provides all methods that an actual adapter should implement.
It also contains the documentation that describes the expected method behaviour, which must be matched by the adapters.

Adapter methods shall raise:
Errors::EndpointAuthenticationError == 401 if a endpoint call failed due to bad credentials
Errors::AdapterResourceNotFoundError == 404 if a resource could not be found
Errors::SemanticAdapterRequestError == 422 if the request could not be processed due to common semantic errors
Errors::PlatformSpecificSemanticError == 422 if the request could not be processed due to semantic errors that are specific to the endpoint / platform, for instance quota restrictions.
Errors::UnknownAdapterCallError == 500 if the endpoint API shows unexpected behavior, not matching the implementation
Errors::AdapterMissingImplementationError == 501 if a feature is not (yet) implemented by the adapter

If embedded in the Grape Restful API, authentication errors and bad requests are handled by Grape.
If an adapter is used within the gem, the developer must take care of authentication handling and missing form data.

Direct Known Subclasses

CloudControl, CloudFoundryV2, Heroku, OpenshiftV2

Constant Summary collapse

NOT_IMPLEMENTED_ERROR =

Error message saying that the adapter feature has not been implemented yet.

Errors::AdapterMissingImplementationError.new(
'Adapter is missing an implementation to support this feature')

Instance Attribute Summary

Attributes inherited from BaseAdapter

#endpoint_url

Instance Method Summary collapse

Methods inherited from BaseAdapter

#cache, #cache?, #cache_key, #cached, #endpoint_call, #fail_with, #headers, #initialize

Methods included from Logging

configure_logger_for, #log, logger_for

Methods included from HttpTailClient

#tail_http_response

Methods included from HttpClient

#delete, #get, #head, #patch, #post, #put

Constructor Details

This class inherits a constructor from Nucleus::Adapters::BaseAdapter

Instance Method Details

#add_service(application_id, service_entity, plan_entity) ⇒ Hash, Nucleus::API::Models::InstalledService

Add the service with the service_id to the application with the application_id.

Parameters:

  • application_id (String) —

    Id of the application of which the service is to be added to

  • service_entity (Hash, Nucleus::API::Models::Service) —

    service entity compatible Hash.

  • plan_entity (Hash, Nucleus::API::Models::ServicePlan) —

    service plan entity compatible Hash.

  • env_var (Hash) —

    a customizable set of options

Returns:

  • (Hash, Nucleus::API::Models::InstalledService) —

    installed service entity compatible hash

Raises:



430
431
432
 
# File 'lib/nucleus/adapters/v1/stub_adapter.rb', line 430

def add_service(application_id, service_entity, plan_entity)
  fail NOT_IMPLEMENTED_ERROR
end

#application(application_id) ⇒ Hash, Nucleus::API::Models::Application

Retrieve the application entity of the application with the given application_id.

Parameters:

  • application_id (String) —

    Id of the application object to retrieve

Returns:

  • (Hash, Nucleus::API::Models::Application) —

    application entity compatible Hash with the application_id

Raises:



77
78
79
 
# File 'lib/nucleus/adapters/v1/stub_adapter.rb', line 77

def application(application_id)
  fail NOT_IMPLEMENTED_ERROR
end

#applications ⇒ Hash, Nucleus::API::Models::Applications

Get a list of all applications that are accessible to the authenticated user account.

Returns:

  • (Hash, Nucleus::API::Models::Applications) —

    application entity list compatible hash

Raises:



68
69
70
 
# File 'lib/nucleus/adapters/v1/stub_adapter.rb', line 68

def applications
  fail NOT_IMPLEMENTED_ERROR
end

#auth_client ⇒ Nucleus::Adapters::AuthClient

Build an Authentication client that can handle the authentication to the endpoint given the username and a matching password.

Returns:



41
42
43
 
# File 'lib/nucleus/adapters/v1/stub_adapter.rb', line 41

def auth_client
  fail NOT_IMPLEMENTED_ERROR
end

#change_service(application_id, service_id, plan_entity) ⇒ Hash, Nucleus::API::Models::InstalledService

Change the service, e.g. the active plan, of the service with the service_id for the application with the application_id. Use the fields of the service_entity to execute the update.

Parameters:

  • application_id (String) —

    Id of the application of which the service is to be changed

  • service_id (String) —

    Id of the installed service that is to be updated. The id must not (but can) be identical to the id of the service the installed service is based on.

  • plan_entity (Hash, Nucleus::API::Models::ServicePlan) —

    service plan entity compatible Hash.

  • env_var (Hash) —

    a customizable set of options

Returns:

  • (Hash, Nucleus::API::Models::InstalledService) —

    installed service entity compatible hash

Raises:



446
447
448
 
# File 'lib/nucleus/adapters/v1/stub_adapter.rb', line 446

def change_service(application_id, service_id, plan_entity)
  fail NOT_IMPLEMENTED_ERROR
end

#create_application(application) ⇒ Hash, Nucleus::API::Models::Application

Create a new application on the endpoint using the given application entity.

Parameters:

  • application (Hash, Nucleus::API::Models::Application) —

    entity compatible Hash.

Options Hash (application):

  • :name (String) —

    The name of the application

  • :runtimes (Array<String>) —

    Runtimes (buildpacks) to use with the application

  • :region (String) —

    Region where the application shall be deployed, call #regions for a list of allowed values

  • :autoscaled (Boolean) —

    True if the application shall scale automatically, false if manual scaling shall be used. WARNING: This option is currently not supported by most vendors!

Returns:

  • (Hash, Nucleus::API::Models::Application) —

    application entity compatible Hash of the created application

Raises:



92
93
94
 
# File 'lib/nucleus/adapters/v1/stub_adapter.rb', line 92

def create_application(application)
  fail NOT_IMPLEMENTED_ERROR
end

#create_domain(application_id, domain) ⇒ Hash, Nucleus::API::Models::Domain

Create a new domain using the given domain entity and assign it to the application.

Parameters:

  • application_id (String) —

    Id of the application for which the domain is to be created

  • domain (Hash, Nucleus::API::Models::Domain) —

    domain entity compatible Hash.

  • application (Hash) —

    a customizable set of options

Returns:

  • (Hash, Nucleus::API::Models::Domain) —

    domain entity compatible hash of the created domain

Raises:



145
146
147
 
# File 'lib/nucleus/adapters/v1/stub_adapter.rb', line 145

def create_domain(application_id, domain)
  fail NOT_IMPLEMENTED_ERROR
end

#create_env_var(application_id, env_var) ⇒ Hash, Nucleus::API::Models::EnvironmentVariable

Create a new environment variable using the given env. var entity and assign it to the application.

Parameters:

  • application_id (String) —

    Id of the application for which the env_var is to be created

  • env_var (Hash, Nucleus::API::Models::EnvironmentVariable) —

    env. var entity compatible Hash.

Options Hash (env_var):

  • :key (String) —

    Key of the environment variable, e.g. IP

  • :value (String) —

    Value of the environment variable, e.g. 0.0.0.0

Returns:

  • (Hash, Nucleus::API::Models::EnvironmentVariable) —

    environment variable entity compatible hash of the created env. var

Raises:



191
192
193
 
# File 'lib/nucleus/adapters/v1/stub_adapter.rb', line 191

def create_env_var(application_id, env_var)
  fail NOT_IMPLEMENTED_ERROR
end

#delete_application(application_id) ⇒ void

This method returns an undefined value.

Delete the application with the given application_id on the endpoint.

Parameters:

  • application_id (String) —

    Id of the application object that shall be deleted

Raises:



113
114
115
 
# File 'lib/nucleus/adapters/v1/stub_adapter.rb', line 113

def delete_application(application_id)
  fail NOT_IMPLEMENTED_ERROR
end

#delete_domain(application_id, domain_id) ⇒ void

This method returns an undefined value.

Delete the domain of the application with the domain_id.

Parameters:

  • application_id (String) —

    Id of the application for which the domain is to be deleted

  • domain_id (String) —

    Id of the domain object to delete

Raises:



156
157
158
 
# File 'lib/nucleus/adapters/v1/stub_adapter.rb', line 156

def delete_domain(application_id, domain_id)
  fail NOT_IMPLEMENTED_ERROR
end

#delete_env_var(application_id, env_var_id) ⇒ void

This method returns an undefined value.

Delete the environment variable of the application with the env_var_id.

Parameters:

  • application_id (String) —

    Id of the application for which the env_var is to be deleted

  • env_var_id (String) —

    Id of the env_var object to delete

Raises:



216
217
218
 
# File 'lib/nucleus/adapters/v1/stub_adapter.rb', line 216

def delete_env_var(application_id, env_var_id)
  fail NOT_IMPLEMENTED_ERROR
end

#deploy(application_id, application_archive, compression_format) ⇒ void

This method returns an undefined value.

Deploy the data of the application given the compressed application archive.
The application shall not be running when the deployment is finished. Postconditions (delayed):

  • state == deployed

Parameters:

  • application_id (String) —

    Id of the application for which the data is to be deployed

  • application_archive (Tempfile) —

    compressed application archive that shall be deployed

  • compression_format (Symbol) —

    archive formats, see Nucleus::API::Enums::CompressionFormats.all for a list of all allowed values

Raises:



280
281
282
 
# File 'lib/nucleus/adapters/v1/stub_adapter.rb', line 280

def deploy(application_id, application_archive, compression_format)
  fail NOT_IMPLEMENTED_ERROR
end

#domain(application_id, domain_id) ⇒ Hash, Nucleus::API::Models::Domain

Retrieve the domain entity of the application with the given application_id and the domain with the domain_id.

Parameters:

  • application_id (String) —

    Id of the application for which the domain is to be retrieved

  • domain_id (String) —

    Id of the domain object to retrieve

Returns:

  • (Hash, Nucleus::API::Models::Domain) —

    domain entity compatible hash of the domain with the domain_id

Raises:



133
134
135
 
# File 'lib/nucleus/adapters/v1/stub_adapter.rb', line 133

def domain(application_id, domain_id)
  fail NOT_IMPLEMENTED_ERROR
end

#domains(application_id) ⇒ Hash, Nucleus::API::Models::Domains

Get a list of all domains that are assigned to the application.

Parameters:

  • application_id (String) —

    Id of the application for which the domains are to be retrieved

Returns:

  • (Hash, Nucleus::API::Models::Domains) —

    domain entity list compatible hash

Raises:



122
123
124
 
# File 'lib/nucleus/adapters/v1/stub_adapter.rb', line 122

def domains(application_id)
  fail NOT_IMPLEMENTED_ERROR
end

#download(application_id, compression_format) ⇒ StringIO

Download the application data that is currently deployed on the platform. The downloaded application archive must contain at least all files that were originally deployed, but can also contain additional files, for instance log files.

Parameters:

  • application_id (String) —

    Id of the application of which the data is to be downloaded

  • compression_format (Symbol) —

    archive formats, see Nucleus::API::Enums::CompressionFormats.all for a list of all allowed values

Returns:

  • (StringIO) —

    binary application data

Raises:



306
307
308
 
# File 'lib/nucleus/adapters/v1/stub_adapter.rb', line 306

def download(application_id, compression_format)
  fail NOT_IMPLEMENTED_ERROR
end

#env_var(application_id, env_var_id) ⇒ Hash, Nucleus::API::Models::EnvironmentVariable

Retrieve the environment variable entity of the application with the given application_id and the env. var with the env_var_id.

Parameters:

  • application_id (String) —

    Id of the application for which the env_var is to be retrieved

  • env_var_id (String) —

    Id of the env_var object to retrieve

Returns:

  • (Hash, Nucleus::API::Models::EnvironmentVariable) —

    environment variable entity compatible hash of the env. var with the env_var_id

Raises:



178
179
180
 
# File 'lib/nucleus/adapters/v1/stub_adapter.rb', line 178

def env_var(application_id, env_var_id)
  fail NOT_IMPLEMENTED_ERROR
end

#env_vars(application_id) ⇒ Hash, Nucleus::API::Models::EnvironmentVariables

Get a list of all environment variables that are assigned to the application.

Parameters:

  • application_id (String) —

    Id of the application for which the env_vars are to be retrieved

Returns:

  • (Hash, Nucleus::API::Models::EnvironmentVariables) —

    environment variable entity list compatible hash

Raises:



165
166
167
 
# File 'lib/nucleus/adapters/v1/stub_adapter.rb', line 165

def env_vars(application_id)
  fail NOT_IMPLEMENTED_ERROR
end

#installed_service(application_id, service_id) ⇒ Hash, Nucleus::API::Models::InstalledService

Retrieve the installed service entity matching the given service_id that is installed on the application with the given application_id.

Parameters:

  • service_id (String) —

    Id of the installed service that is to be retrieved

Returns:

  • (Hash, Nucleus::API::Models::InstalledService) —

    installed service entity compatible hash

Raises:



415
416
417
 
# File 'lib/nucleus/adapters/v1/stub_adapter.rb', line 415

def installed_service(application_id, service_id)
  fail NOT_IMPLEMENTED_ERROR
end

#installed_services(application_id) ⇒ Hash, Nucleus::API::Models::InstalledServices

List all services that are installed on the application with the given application_id.

Parameters:

  • application_id (String) —

    Id of the application of which the services are to be listed of

Returns:

  • (Hash, Nucleus::API::Models::InstalledServices) —

    installed services list compatible hash

Raises:



405
406
407
 
# File 'lib/nucleus/adapters/v1/stub_adapter.rb', line 405

def installed_services(application_id)
  fail NOT_IMPLEMENTED_ERROR
end

#log?(application_id, log_id) ⇒ Boolean

Assert whether the given log_id is valid for the application_id.

Parameters:

  • application_id (String) —

    Id of the application of which the log existence is to be checked

  • log_id (String) —

    Id of the log whose existence is to be checked

Returns:

  • (Boolean) —

    returns true if there is a log for the application with the log_id, false if it does not exist

Raises:



328
329
330
 
# File 'lib/nucleus/adapters/v1/stub_adapter.rb', line 328

def log?(application_id, log_id)
  fail NOT_IMPLEMENTED_ERROR
end

#log_entries(application_id, log_id) ⇒ Array<String>

Retrieve all log entries of the log.

Parameters:

  • application_id (String) —

    Id of the application of which the log_entries are to be retrieved

  • log_id (String) —

    Id of the log for which the entries are to be retrieved

Returns:

  • (Array<String>) —

    array of log entries, starting with the earliest entry at pos [0]

Raises:



347
348
349
 
# File 'lib/nucleus/adapters/v1/stub_adapter.rb', line 347

def log_entries(application_id, log_id)
  fail NOT_IMPLEMENTED_ERROR
end

#logs(application_id) ⇒ Hash, Nucleus::API::Models::Logs

Get a list of all logs that are available for the application.

Parameters:

  • application_id (String) —

    Id of the application of which the logs are to be listed

Returns:

  • (Hash, Nucleus::API::Models::Logs) —

    log entity list compatible hash

Raises:



337
338
339
 
# File 'lib/nucleus/adapters/v1/stub_adapter.rb', line 337

def logs(application_id)
  fail NOT_IMPLEMENTED_ERROR
end

#rebuild(application_id) ⇒ Hash, Nucleus::API::Models::Application

Rebuild the recently deployed bits of the application.
The rebuild can be used to update the application to use a new version of the underlying runtime or fix a previously failed application start after the issues have been resolved.

Parameters:

  • application_id (String) —

    Id of the application which is to be rebuild

Returns:

  • (Hash, Nucleus::API::Models::Application) —

    application entity compatible Hash

Raises:



291
292
293
 
# File 'lib/nucleus/adapters/v1/stub_adapter.rb', line 291

def rebuild(application_id)
  fail NOT_IMPLEMENTED_ERROR
end

#region(region_id) ⇒ Hash, Nucleus::API::Models::Region

Return the class compatible information regarding the region with the given region_id.

Parameters:

  • region_id (String) —

    Id of the region object to retrieve

Returns:

  • (Hash, Nucleus::API::Models::Region) —

    region entity compatible Hash with the id region_id

Raises:



61
62
63
 
# File 'lib/nucleus/adapters/v1/stub_adapter.rb', line 61

def region(region_id)
  fail NOT_IMPLEMENTED_ERROR
end

#regions ⇒ Hash, Nucleus::API::Models::Regions

Return a list of all class compatible objects that are available on the current endpoint.
If the platform does not offer multi-region support, one ‘default’ region shall be returned.

Returns:

  • (Hash, Nucleus::API::Models::Regions) —

    region entity compatible Hash of available regions

Raises:



50
51
52
 
# File 'lib/nucleus/adapters/v1/stub_adapter.rb', line 50

def regions
  fail NOT_IMPLEMENTED_ERROR
end

#remove_service(application_id, service_id) ⇒ void

This method returns an undefined value.

Remove the installed service with the service_id from the application with the application_id.

Parameters:

  • application_id (String) —

    Id of the application of which the service is to be removed from

  • service_id (String) —

    Id of the installed service that is to be removed from the application. The id must not (but can) be identical to the id of the service the installed service is based on.

Raises:



458
459
460
 
# File 'lib/nucleus/adapters/v1/stub_adapter.rb', line 458

def remove_service(application_id, service_id)
  fail NOT_IMPLEMENTED_ERROR
end

#restart(application_id) ⇒ Hash, Nucleus::API::Models::Application

Restart all instances of the application with the application_id. The state of all application instances should become running when all actions are finished (unless there are technical errors preventing the application to start). Preconditions:

  • application must have been deployed

Postconditions (delayed):

  • state == running

Parameters:

  • application_id (String) —

    Id of the application which is to be restarted

Returns:

  • (Hash, Nucleus::API::Models::Application) —

    application entity compatible Hash

Raises:



263
264
265
 
# File 'lib/nucleus/adapters/v1/stub_adapter.rb', line 263

def restart(application_id)
  fail NOT_IMPLEMENTED_ERROR
end

#scale(application_id, instances) ⇒ Hash, Nucleus::API::Models::Application

TODO: Finish documentation when vertical scaling is added Scale the application and adjust the number of instances that shall be running.

Parameters:

  • application_id (String) —

    Id of the application which is to be scaled

Returns:

  • (Hash, Nucleus::API::Models::Application) —

    application entity compatible Hash

Raises:



317
318
319
 
# File 'lib/nucleus/adapters/v1/stub_adapter.rb', line 317

def scale(application_id, instances)
  fail NOT_IMPLEMENTED_ERROR
end

#service(service_id) ⇒ Hash, Nucleus::API::Models::Service

Retrieve the service entity matching the given service_id.

Parameters:

  • service_id (String) —

    Id of the service that is to be retrieved

Returns:

  • (Hash, Nucleus::API::Models::Service) —

    service entity compatible hash

Raises:



378
379
380
 
# File 'lib/nucleus/adapters/v1/stub_adapter.rb', line 378

def service(service_id)
  fail NOT_IMPLEMENTED_ERROR
end

#service_plan(service_id, plan_id) ⇒ Hash, Nucleus::API::Models::ServicePlan

Show the plan with the plan_id that is applicable to the service with the service_id.

Parameters:

  • service_id (String) —

    Id of the service the plans belongs to

Returns:

  • (Hash, Nucleus::API::Models::ServicePlan) —

    service plan entity compatible hash

Raises:



396
397
398
 
# File 'lib/nucleus/adapters/v1/stub_adapter.rb', line 396

def service_plan(service_id, plan_id)
  fail NOT_IMPLEMENTED_ERROR
end

#service_plans(service_id) ⇒ Hash, Nucleus::API::Models::ServicePlans

List all plans that can be chosen for the service with the service_id, ascending order on the price.

Parameters:

  • service_id (String) —

    Id of the service the plans belong to

Returns:

  • (Hash, Nucleus::API::Models::ServicePlans) —

    service plan list compatible hash

Raises:



387
388
389
 
# File 'lib/nucleus/adapters/v1/stub_adapter.rb', line 387

def service_plans(service_id)
  fail NOT_IMPLEMENTED_ERROR
end

#services ⇒ Hash, Nucleus::API::Models::Services

List all services that are available at the endpoint.

Returns:

  • (Hash, Nucleus::API::Models::Services) —

    services list compatible hash

Raises:



369
370
371
 
# File 'lib/nucleus/adapters/v1/stub_adapter.rb', line 369

def services
  fail NOT_IMPLEMENTED_ERROR
end

#start(application_id) ⇒ Hash, Nucleus::API::Models::Application

Start all instances of the application with the application_id. The state of all application instances should become running when all actions are finished (unless there are technical errors preventing the application to start). Preconditions:

  • application must have been deployed

Postconditions (delayed):

  • state == running

Parameters:

  • application_id (String) —

    Id of the application which is to be started

Returns:

  • (Hash, Nucleus::API::Models::Application) —

    application entity compatible Hash

Raises:



232
233
234
 
# File 'lib/nucleus/adapters/v1/stub_adapter.rb', line 232

def start(application_id)
  fail NOT_IMPLEMENTED_ERROR
end

#stop(application_id) ⇒ Hash, Nucleus::API::Models::Application

Stop all instances of the application with the application_id. The state of all application instances will become stopped when all actions are finished. Preconditions:

  • application must have been deployed

Postconditions (delayed):

  • state == stopped

Parameters:

  • application_id (String) —

    Id of the application which is to be stopped

Returns:

  • (Hash, Nucleus::API::Models::Application) —

    application entity compatible Hash

Raises:



247
248
249
 
# File 'lib/nucleus/adapters/v1/stub_adapter.rb', line 247

def stop(application_id)
  fail NOT_IMPLEMENTED_ERROR
end

#tail(application_id, log_id, stream) ⇒ Nucleus::Adapters::TailStopper

Tail the logfile of the application and send each retrieved chunk, which can be a line of a file, a new chunk in a received http message, or a websocket message, to the stream. The deferred tailing process shall be stoppable when the stop method of the returned TailStopper is called.

Parameters:

  • application_id (String) —

    Id of the application of which the log is to be tailed

  • log_id (String) —

    Id of the log that is to be tailed

  • stream (Nucleus::StreamCallback) —

    stream callback to which messages can be sent via the send_message method

Returns:

Raises:



362
363
364
 
# File 'lib/nucleus/adapters/v1/stub_adapter.rb', line 362

def tail(application_id, log_id, stream)
  fail NOT_IMPLEMENTED_ERROR
end

#update_application(application_id, application) ⇒ Hash, Nucleus::API::Models::Application

Update an application on the endpoint using the given application entity.

Parameters:

  • application (Hash, Nucleus::API::Models::Application) —

    application entity compatible Hash.

  • application_id (String) —

    Id of the application object that shall be updated

Options Hash (application):

  • :name (String) —

    The updated name of the application

  • :runtimes (Array<String>) —

    Runtimes (buildpacks) to use with the application

Returns:

  • (Hash, Nucleus::API::Models::Application) —

    application entity compatible Hash with the application_id

Raises:



104
105
106
 
# File 'lib/nucleus/adapters/v1/stub_adapter.rb', line 104

def update_application(application_id, application)
  fail NOT_IMPLEMENTED_ERROR
end

#update_env_var(application_id, env_var_id, env_var) ⇒ Hash, Nucleus::API::Models::EnvironmentVariable

Update the environment variable of the application, using the given env. var entity.

Parameters:

  • application_id (String) —

    Id of the application for which the env_var is to be updated

  • env_var_id (String) —

    Id of the env_var object to update

  • env_var (Hash, Nucleus::API::Models::EnvironmentVariable) —

    env. var entity compatible Hash.

Options Hash (env_var):

  • :value (String) —

    Value of the environment variable, e.g. 0.0.0.0

Returns:

  • (Hash, Nucleus::API::Models::EnvironmentVariable) —

    environment variable entity compatible hash of the updated env. var

Raises:



205
206
207
 
# File 'lib/nucleus/adapters/v1/stub_adapter.rb', line 205

def update_env_var(application_id, env_var_id, env_var)
  fail NOT_IMPLEMENTED_ERROR
end