nucleus 0.1.0

data/lib/nucleus/adapters/v1/openshift_v2/regions.rb

@@ -0,0 +1,58 @@
+module Nucleus
+  module Adapters
+    module V1
+      class OpenshiftV2 < Stub
+        module Regions
+          # @see Stub#regions
+          def regions
+            response = get('/regions').body[:data]
+            response.each { |region| to_nucleus_region(region) }
+            # filter all non-available regions
+            response.delete_if { |region| region[:allow_selection] == false }
+            response
+          end
+
+          # @see Stub#region
+          def region(region_name)
+            region = convert_region(region_name)
+            fail Errors::AdapterResourceNotFoundError,
+                 "Region '#{region_name}' does not exist at the endpoint" if region.nil?
+            region
+          end
+
+          private
+
+          # Retrieve a native region for the abstracted ID and assign its name to the application entity
+          def retrieve_region(application)
+            return unless application.key?(:region)
+            found_region = native_region(application[:region])
+            fail Errors::SemanticAdapterRequestError,
+                 "Region '#{application[:region]}' does not exist at the endpoint" if found_region.nil?
+            application[:region] = found_region[:name]
+          end
+
+          def convert_region(region_name)
+            found_region = native_region(region_name)
+            found_region = to_nucleus_region(found_region) unless found_region.nil?
+            found_region
+          end
+
+          def native_region(region_name)
+            response = get('/regions').body[:data]
+            response.delete_if { |region| region[:allow_selection] == false }
+            response.find { |region| region[:name].casecmp(region_name) == 0 }
+          end
+
+          def to_nucleus_region(region)
+            region[:id] = region.delete(:name)
+            # first created zone
+            region[:created_at] = region[:zones].min_by { |v| v[:created_at] }
+            # last updated zone
+            region[:updated_at] = region[:zones].max_by { |v| v[:updated_at] }
+            region
+          end
+        end
+      end
+    end
+  end
+end

data/lib/nucleus/adapters/v1/openshift_v2/scaling.rb

@@ -0,0 +1,39 @@
+module Nucleus
+  module Adapters
+    module V1
+      class OpenshiftV2 < Stub
+        module Scaling
+          # @see Stub#scale
+          def scale(application_id, instances)
+            id = app_id_by_name(application_id)
+            app = get("/application/#{id}").body[:data]
+            fail_with(:not_scalable, [application_id]) unless app[:scalable]
+
+            # check if scaling would exceed the available gears
+            user = get('/user').body[:data]
+            available_gears = user[:max_gears] - user[:consumed_gears]
+            requires_additional_gears = instances - app[:gear_count]
+            if requires_additional_gears > available_gears
+              fail_with(:insufficient_gears, [application_id, instances, requires_additional_gears, available_gears])
+            end
+
+            # scale up if we require more gears
+            while requires_additional_gears > 0
+              send_event(id, 'scale-up')
+              requires_additional_gears -= 1
+            end
+
+            # scale down if we have too much gears
+            while requires_additional_gears < 0
+              send_event(id, 'scale-down')
+              requires_additional_gears += 1
+            end
+
+            # reload the app to see if all operations were taken into account
+            application(id)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/nucleus/adapters/v1/openshift_v2/semantic_errors.rb

@@ -0,0 +1,40 @@
+module Nucleus
+  module Adapters
+    module V1
+      class OpenshiftV2 < Stub
+        # Semantic error messages that are specific for Openshift V2
+        module SemanticErrors
+          # Get all Openshift V2 specific semantic error definitions.
+          # @return [Hash<Symbol,Hash<Symbol,String>>] the error message definitions, including the error +code+,
+          #   e.g. +422_200_1+ and the +message+ that shall be formatted when used.
+          def semantic_error_messages
+            {
+              # Error code '400_1': Only one runtime is allowed per Openshift V2 application
+              only_one_runtime: { code: 422_400_1, message: 'Openshift V2 only allows 1 runtime per '\
+                'application' },
+
+              must_have_runtime: { code: 422_400_2, message: 'Openshift V2 requires you to specify exactly one '\
+                'runtime when creating the application. Please provide a valid runtime in the next request.' },
+
+              # Error code '400_3': Application is not scalable
+              not_scalable: { code: 422_400_3, message: "Application '%s' is not scalable, "\
+                "instances can't be adjusted" },
+
+              # Error code '400_4': Quota exceeded, scaling would require more gears than available to the user
+              insufficient_gears: { code: 422_400_4, message: "Application '%s' can't be, "\
+                'scaled to %s instances, requires %s gears but only %s gears are available' },
+
+              no_user_domain: { code: 422_400_5, message: "Openshift V2 requires you to create a 'domain' before "\
+                'any application can be created' },
+
+              ambiguous_runtime: { code: 422_400_6, message: 'Runtime could not be identified, there are multiple '\
+                  "matches for '%s': %s" },
+
+              invalid_runtime: { code: 422_400_7, message: "Invalid runtime, could not identify cartridge for '%s'." }
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/nucleus/adapters/v1/openshift_v2/services.rb

@@ -0,0 +1,173 @@
+module Nucleus
+  module Adapters
+    module V1
+      class OpenshiftV2 < Stub
+        # Openshift V2, operations for the application's addons
+        module Services
+          # @see Stub#services
+          def services
+            embedded_cartridges.collect { |cartridge| to_nucleus_service(cartridge) }
+          end
+
+          # @see Stub#service
+          def service(service_id)
+            to_nucleus_service(embedded_cartridge(service_id))
+          end
+
+          # @see Stub#service_plans
+          def service_plans(service_id)
+            cartridge = embedded_cartridge(service_id)
+            # Currently there are no plans, implement when required...
+            return [default_plan(cartridge)] if cartridge[:usage_rates].empty?
+            cartridge[:usage_rates].collect { |usage_rate| to_nucleus_plan(cartridge, usage_rate) }
+          end
+
+          # @see Stub#service_plan
+          def service_plan(service_id, plan_id)
+            cartridge = embedded_cartridge(service_id)
+            if (cartridge[:usage_rates].empty? && plan_id != 'default') ||
+               (!cartridge[:usage_rates].empty? && !cartridge[:usage_rates].any? { |rate| rate[:plan_id] == plan_id })
+              # Currently there are no plans, implement when required...
+              fail Errors::AdapterResourceNotFoundError, "No such service plan name '#{plan_id}' for service "\
+                "'#{service_id}'"
+            end
+
+            return default_plan(cartridge) if cartridge[:usage_rates].empty?
+            to_nucleus_plan(cartridge, cartridge[:usage_rates].find { |rate| rate[:plan_id] == plan_id })
+          end
+
+          # @see Stub#installed_services
+          def installed_services(application_id)
+            installed_cartridges(application_id).collect do |installed|
+              to_nucleus_installed_service(installed)
+            end
+          end
+
+          # @see Stub#installed_service
+          def installed_service(application_id, service_id)
+            installed = get("/application/#{app_id_by_name(application_id)}/cartridge/#{service_id}").body[:data]
+            to_nucleus_installed_service(installed)
+          end
+
+          # @see Stub#add_service
+          def add_service(application_id, service_entity, plan_entity)
+            # make sure dependencies are installed
+            app_id = app_id_by_name(application_id)
+            begin
+              service_to_add = embedded_cartridge(service_entity[:id])
+            rescue Errors::AdapterResourceNotFoundError
+              raise Errors::SemanticAdapterRequestError, "Invalid service: '#{service_entity[:id]}' could not be found"
+            end
+            # verify dependencies are installed, throws error if not
+            verify_cartridge_dependencies(app_id, service_entity[:id], service_to_add)
+
+            # check plan (if there are some)
+            # no plans, chosen plan must be 'default'
+            plan_name = service_to_add[:usage_rates].find { |plan| plan[:plan_id] == plan_entity[:id] }
+            if (service_to_add[:usage_rates].empty? && plan_entity[:id] != 'default') ||
+               (!service_to_add[:usage_rates].empty? && plan_name.nil?)
+              fail Errors::SemanticAdapterRequestError, "No such service plan name '#{plan_entity[:id]}' for service "\
+              "'#{service_entity[:id]}' and application '#{application_id}'"
+            end
+
+            # TODO: if a different plan than 'default' is chosen, we can't use it yet :/
+            # However, only 'standalone' cartridges showed different plans as of April, 15th 2015
+            to_nucleus_installed_service(post("/application/#{app_id}/cartridges",
+                                              body: { cartridge: service_entity[:id] }).body[:data])
+          end
+
+          # @see Stub#remove_service
+          def remove_service(application_id, service_id)
+            delete("/application/#{app_id_by_name(application_id)}/cartridge/#{service_id}")
+          end
+
+          private
+
+          def verify_cartridge_dependencies(application_id, service_id, service_to_add)
+            missing_dependencies = service_to_add.key?(:requires) ? service_to_add[:requires] : []
+            already_installed = installed_cartridges(application_id)
+            already_installed.each { |installed_cartridge| missing_dependencies.delete(installed_cartridge[:name]) }
+            fail Errors::SemanticAdapterRequestError, "Failed to add service '#{service_id}' for application "\
+              "'#{application_id}'. The service's dependencies '#{missing_dependencies}' are not, "\
+              'but have to be installed.' unless missing_dependencies.empty?
+          end
+
+          def installed_cartridges(application_id)
+            installed = get("/application/#{app_id_by_name(application_id)}/cartridges").body[:data]
+            installed.find_all do |cartridge|
+              # exclude the 'haproxy' addon from the list. It is a core part of the application and can't be modified
+              # exclude all standalone cartridges, we do not yet support them
+              cartridge[:type] == 'embedded' && !cartridge[:name].start_with?('haproxy-')
+            end
+          end
+
+          def embedded_cartridges
+            get('/cartridges').body[:data].find_all { |cartridge| cartridge[:type] == 'embedded' }
+          end
+
+          def embedded_cartridge(service_id)
+            get("/cartridge/#{service_id}").body[:data]
+          end
+
+          def to_nucleus_service(cartridge)
+            # id, description and name is already contained
+            cartridge[:required_services] = cartridge.key?(:requires) ? cartridge[:requires] : []
+            cartridge[:documentation_url] = nil
+            cartridge[:release] = cartridge[:version]
+            cartridge[:free_plan] = cartridge[:usage_rates] == []
+            cartridge[:created_at] = cartridge[:creation_time]
+            cartridge[:updated_at] = cartridge[:creation_time]
+            cartridge
+          end
+
+          def to_nucleus_installed_service(installed_service)
+            installed_service = to_nucleus_service(installed_service)
+            # Currently there are no plans, implement when required...
+            installed_service[:active_plan] = 'default'
+            installed_service[:properties] = installed_service.key?(:properties) ? installed_service[:properties] : []
+            installed_service[:web_url] = nil
+            installed_service
+          end
+
+          def to_nucleus_plan(cartridge, usage_rate)
+            {
+              id: usage_rate[:plan_id],
+              name: usage_rate[:plan_id],
+              description: nil,
+              free: false,
+              costs: [{
+                # Openshift online currently bills in USD, EUR and CAD
+                price: [{ amount: usage_rate[:cad], currency: 'CAD' },
+                        { amount: usage_rate[:eur], currency: 'EUR' },
+                        { amount: usage_rate[:usd], currency: 'USD' }],
+                per_instance: false,
+                period: usage_rate[:duration]
+              }],
+              created_at: cartridge[:creation_time],
+              updated_at: cartridge[:creation_time]
+            }
+          end
+
+          def default_plan(cartridge)
+            {
+              id: 'default',
+              name: 'default',
+              description: 'Default plan, cartridge does not offer different plans',
+              free: true,
+              costs: [{
+                # Openshift online currently bills in USD, EUR and CAD
+                price: [{ amount: 0.00, currency: 'CAD' },
+                        { amount: 0.00, currency: 'EUR' },
+                        { amount: 0.00, currency: 'USD' }],
+                per_instance: false,
+                period: 'hour'
+              }],
+              created_at: cartridge[:creation_time],
+              updated_at: cartridge[:creation_time]
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/nucleus/adapters/v1/openshift_v2/vars.rb

@@ -0,0 +1,49 @@
+module Nucleus
+  module Adapters
+    module V1
+      class OpenshiftV2 < Stub
+        module Vars
+          # @see Stub#env_vars
+          def env_vars(application_id)
+            all_vars = get("/application/#{app_id_by_name(application_id)}/environment-variables").body[:data]
+            all_vars.collect { |var| to_nucleus_var(var) }
+          end
+
+          # @see Stub#env_var
+          def env_var(application_id, env_var_key)
+            response = get("/application/#{app_id_by_name(application_id)}/environment-variable/#{env_var_key}")
+            to_nucleus_var(response.body[:data])
+          end
+
+          # @see Stub#create_env_var
+          def create_env_var(application_id, env_var)
+            to_nucleus_var(post("/application/#{app_id_by_name(application_id)}/environment-variables",
+                                body: { name: env_var[:key], value: env_var[:value] }).body[:data])
+          end
+
+          # @see Stub#update_env_var
+          def update_env_var(application_id, env_var_key, env_var)
+            to_nucleus_var(put("/application/#{app_id_by_name(application_id)}/environment-variable/#{env_var_key}",
+                               body: { value: env_var[:value] }).body[:data])
+          end
+
+          # @see Stub#delete_env_var
+          def delete_env_var(application_id, env_var_key)
+            id = app_id_by_name(application_id)
+            # Openshift returns 204 even if the key did not exist
+            if get("/application/#{id}/environment-variable/#{env_var_key}", expects: [200, 404]).status == 404
+              fail Errors::AdapterResourceNotFoundError, "Env. var key '#{env_var_key}' does not exist"
+            end
+            delete("/application/#{id}/environment-variable/#{env_var_key}")
+          end
+
+          private
+
+          def to_nucleus_var(var)
+            { id: var[:name], key: var[:name], value: var[:value] }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/nucleus/adapters/v1/stub_adapter.rb

@@ -0,0 +1,464 @@
+module Nucleus
+  module Adapters
+    # Version 1, or the first release of the Nucleus API.<br>
+    # It provides basic management functionality to handle:<br>
+    # * applications
+    # * domains
+    # * environment variables
+    # * logging
+    # * deployment
+    # * scaling (horizontal and vertical)
+    module V1
+      # Stub adapter for Nucleus API version 1.<br>
+      # The stub provides all methods that an actual adapter should implement.<br>
+      # It also contains the documentation that describes the expected method behaviour,
+      # which must be matched by the adapters.<br>
+      # <br>
+      # Adapter methods shall raise:<br>
+      # {Errors::EndpointAuthenticationError} == 401 if a endpoint call failed due to bad credentials<br>
+      # {Errors::AdapterResourceNotFoundError} == 404 if a resource could not be found<br>
+      # {Errors::SemanticAdapterRequestError} == 422 if the request could not be processed due to
+      # common semantic errors<br>
+      # {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.<br>
+      # {Errors::UnknownAdapterCallError} == 500 if the endpoint API shows unexpected behavior,
+      # not matching the implementation<br>
+      # {Errors::AdapterMissingImplementationError} == 501 if a feature is not (yet) implemented by the adapter<br>
+      #
+      # If embedded in the Grape Restful API, authentication errors and bad requests are handled by Grape.<br>
+      # If an adapter is used within the +gem+, the developer must take care of authentication handling and
+      # missing form data.
+      #
+      # @abstract
+      class Stub < BaseAdapter
+        # Error message saying that the adapter feature has not been implemented yet.
+        NOT_IMPLEMENTED_ERROR = Errors::AdapterMissingImplementationError.new(
+          'Adapter is missing an implementation to support this feature')
+
+        # Build an Authentication client that can handle the authentication to the endpoint
+        # given the username and a matching password.
+        # @return [Nucleus::Adapters::AuthClient] authentication client
+        def auth_client
+          fail NOT_IMPLEMENTED_ERROR
+        end
+
+        # Return a list of all {Nucleus::API::Models::Region class} compatible objects
+        # that are available on the current endpoint.<br>
+        # If the platform does not offer multi-region support, one 'default' region shall be returned.
+        # @raise [Nucleus::Errors::EndpointAuthenticationError] if the authentication on the endpoint failed
+        # @return [Hash, Nucleus::API::Models::Regions] region entity compatible Hash of available regions
+        def regions
+          fail NOT_IMPLEMENTED_ERROR
+        end
+
+        # Return the {Nucleus::API::Models::Region class} compatible information
+        # regarding the region with the given region_id.
+        #
+        # @param [String] region_id Id of the region object to retrieve
+        # @raise [Nucleus::Errors::AdapterResourceNotFoundError] if no region matching the region_id could be found
+        # @raise [Nucleus::Errors::EndpointAuthenticationError] if the authentication on the endpoint failed
+        # @return [Hash, Nucleus::API::Models::Region] region entity compatible Hash with the id region_id
+        def region(region_id)
+          fail NOT_IMPLEMENTED_ERROR
+        end
+
+        # Get a list of all applications that are accessible to the authenticated user account.
+        # @raise [Nucleus::Errors::EndpointAuthenticationError] if the authentication on the endpoint failed
+        # @return [Hash, Nucleus::API::Models::Applications] application entity list compatible hash
+        def applications
+          fail NOT_IMPLEMENTED_ERROR
+        end
+
+        # Retrieve the application entity of the application with the given application_id.
+        # @param [String] application_id Id of the application object to retrieve
+        # @raise [Nucleus::Errors::AdapterResourceNotFoundError] if no app matching the application_id could be found
+        # @raise [Nucleus::Errors::EndpointAuthenticationError] if the authentication on the endpoint failed
+        # @return [Hash, Nucleus::API::Models::Application] application entity compatible Hash with the application_id
+        def application(application_id)
+          fail NOT_IMPLEMENTED_ERROR
+        end
+
+        # Create a new application on the endpoint using the given application entity.
+        # @param [Hash, Nucleus::API::Models::Application] application entity compatible Hash.
+        # @option application [String] :name The name of the application
+        # @option application [Array<String>] :runtimes Runtimes (buildpacks) to use with the application
+        # @option application [String] :region Region where the application shall be deployed,
+        #   call {#regions} for a list of allowed values
+        # @option application [Boolean] :autoscaled True if the application shall scale automatically,
+        #   false if manual scaling shall be used. WARNING: This option is currently not supported by most vendors!
+        # @raise [Nucleus::Errors::EndpointAuthenticationError] if the authentication on the endpoint failed
+        # @return [Hash, Nucleus::API::Models::Application] application entity compatible Hash
+        #   of the created application
+        def create_application(application)
+          fail NOT_IMPLEMENTED_ERROR
+        end
+
+        # Update an application on the endpoint using the given application entity.
+        # @param [Hash, Nucleus::API::Models::Application] application application entity compatible Hash.
+        # @option application [String] :name The updated name of the application
+        # @option application [Array<String>] :runtimes Runtimes (buildpacks) to use with the application
+        # @param [String] application_id Id of the application object that shall be updated
+        # @raise [Nucleus::Errors::AdapterResourceNotFoundError] if no app matching the application_id could be found
+        # @raise [Nucleus::Errors::EndpointAuthenticationError] if the authentication on the endpoint failed
+        # @return [Hash, Nucleus::API::Models::Application] application entity compatible Hash with the application_id
+        def update_application(application_id, application)
+          fail NOT_IMPLEMENTED_ERROR
+        end
+
+        # Delete the application with the given application_id on the endpoint.
+        # @param [String] application_id Id of the application object that shall be deleted
+        # @raise [Nucleus::Errors::AdapterResourceNotFoundError] if no app matching the application_id could be found
+        # @raise [Nucleus::Errors::EndpointAuthenticationError] if the authentication on the endpoint failed
+        # @return [void]
+        def delete_application(application_id)
+          fail NOT_IMPLEMENTED_ERROR
+        end
+
+        # Get a list of all domains that are assigned to the application.
+        # @param [String] application_id Id of the application for which the domains are to be retrieved
+        # @raise [Nucleus::Errors::AdapterResourceNotFoundError] if no app matching the application_id could be found
+        # @raise [Nucleus::Errors::EndpointAuthenticationError] if the authentication on the endpoint failed
+        # @return [Hash, Nucleus::API::Models::Domains] domain entity list compatible hash
+        def domains(application_id)
+          fail NOT_IMPLEMENTED_ERROR
+        end
+
+        # Retrieve the domain entity of the application with the given application_id and the domain with the domain_id.
+        # @param [String] application_id Id of the application for which the domain is to be retrieved
+        # @param [String] domain_id Id of the domain object to retrieve
+        # @raise [Nucleus::Errors::AdapterResourceNotFoundError] if no app matching the application_id,
+        #   or no domain matching the domain_id could be found
+        # @raise [Nucleus::Errors::EndpointAuthenticationError] if the authentication on the endpoint failed
+        # @return [Hash, Nucleus::API::Models::Domain] domain entity compatible hash of the domain with the domain_id
+        def domain(application_id, domain_id)
+          fail NOT_IMPLEMENTED_ERROR
+        end
+
+        # Create a new domain using the given domain entity and assign it to the application.
+        # @param [String] application_id Id of the application for which the domain is to be created
+        # @param [Hash, Nucleus::API::Models::Domain] domain domain entity compatible Hash.
+        # @option application [String] :name The domain name, e.g. +myapplication.example.org+
+        # @raise [Nucleus::Errors::AdapterResourceNotFoundError] if no app matching the application_id,
+        #   or no domain matching the domain_id could be found
+        # @raise [Nucleus::Errors::EndpointAuthenticationError] if the authentication on the endpoint failed
+        # @return [Hash, Nucleus::API::Models::Domain] domain entity compatible hash of the created domain
+        def create_domain(application_id, domain)
+          fail NOT_IMPLEMENTED_ERROR
+        end
+
+        # Delete the domain of the application with the domain_id.
+        # @param [String] application_id Id of the application for which the domain is to be deleted
+        # @param [String] domain_id Id of the domain object to delete
+        # @raise [Nucleus::Errors::AdapterResourceNotFoundError] if no app matching the application_id,
+        #   or no domain matching the domain_id could be found
+        # @raise [Nucleus::Errors::EndpointAuthenticationError] if the authentication on the endpoint failed
+        # @return [void]
+        def delete_domain(application_id, domain_id)
+          fail NOT_IMPLEMENTED_ERROR
+        end
+
+        # Get a list of all environment variables that are assigned to the application.
+        # @param [String] application_id Id of the application for which the env_vars are to be retrieved
+        # @raise [Nucleus::Errors::AdapterResourceNotFoundError] if no app matching the application_id could be found
+        # @raise [Nucleus::Errors::EndpointAuthenticationError] if the authentication on the endpoint failed
+        # @return [Hash, Nucleus::API::Models::EnvironmentVariables] environment variable entity list compatible hash
+        def env_vars(application_id)
+          fail NOT_IMPLEMENTED_ERROR
+        end
+
+        # Retrieve the environment variable entity of the application with the given application_id and the env. var
+        # with the env_var_id.
+        # @param [String] application_id Id of the application for which the env_var is to be retrieved
+        # @param [String] env_var_id Id of the env_var object to retrieve
+        # @raise [Nucleus::Errors::AdapterResourceNotFoundError] if no app matching the application_id,
+        #   or no environment variable matching the env_var_id could be found
+        # @raise [Nucleus::Errors::EndpointAuthenticationError] if the authentication on the endpoint failed
+        # @return [Hash, Nucleus::API::Models::EnvironmentVariable] environment variable entity compatible hash
+        #   of the env. var with the env_var_id
+        def env_var(application_id, env_var_id)
+          fail NOT_IMPLEMENTED_ERROR
+        end
+
+        # Create a new environment variable using the given env. var entity and assign it to the application.
+        # @param [String] application_id Id of the application for which the env_var is to be created
+        # @param [Hash, Nucleus::API::Models::EnvironmentVariable] env_var env. var entity compatible Hash.
+        # @option env_var [String] :key Key of the environment variable, e.g. +IP+
+        # @option env_var [String] :value Value of the environment variable, e.g. +0.0.0.0+
+        # @raise [Nucleus::Errors::AdapterResourceNotFoundError] if no app matching the application_id could be found
+        # @raise [Nucleus::Errors::EndpointAuthenticationError] if the authentication on the endpoint failed
+        # @return [Hash, Nucleus::API::Models::EnvironmentVariable] environment variable entity compatible hash
+        #   of the created env. var
+        def create_env_var(application_id, env_var)
+          fail NOT_IMPLEMENTED_ERROR
+        end
+
+        # Update the environment variable of the application, using the given env. var entity.
+        # @param [String] application_id Id of the application for which the env_var is to be updated
+        # @param [String] env_var_id Id of the env_var object to update
+        # @param [Hash, Nucleus::API::Models::EnvironmentVariable] env_var env. var entity compatible Hash.
+        # @option env_var [String] :value Value of the environment variable, e.g. +0.0.0.0+
+        # @raise [Nucleus::Errors::AdapterResourceNotFoundError] if no app matching the application_id,
+        #   or no environment variable matching the env_var_id could be found
+        # @raise [Nucleus::Errors::EndpointAuthenticationError] if the authentication on the endpoint failed
+        # @return [Hash, Nucleus::API::Models::EnvironmentVariable] environment variable entity compatible hash
+        #   of the updated env. var
+        def update_env_var(application_id, env_var_id, env_var)
+          fail NOT_IMPLEMENTED_ERROR
+        end
+
+        # Delete the environment variable of the application with the env_var_id.
+        # @param [String] application_id Id of the application for which the env_var is to be deleted
+        # @param [String] env_var_id Id of the env_var object to delete
+        # @raise [Nucleus::Errors::AdapterResourceNotFoundError] if no app matching the application_id,
+        #   or no environment variable matching the env_var_id could be found
+        # @raise [Nucleus::Errors::EndpointAuthenticationError] if the authentication on the endpoint failed
+        # @return [void]
+        def delete_env_var(application_id, env_var_id)
+          fail NOT_IMPLEMENTED_ERROR
+        end
+
+        # 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:<br>
+        # * application must have been deployed
+        # Postconditions (delayed):<br>
+        # * state == running
+        # @param [String] application_id Id of the application which is to be started
+        # @raise [Nucleus::Errors::AdapterResourceNotFoundError] if the application could not be found
+        # @raise [Nucleus::Errors::EndpointAuthenticationError] if the authentication on the endpoint failed
+        # @raise [Nucleus::Errors::SemanticAdapterRequestError] if the application is not deployed
+        # @return [Hash, Nucleus::API::Models::Application] application entity compatible Hash
+        def start(application_id)
+          fail NOT_IMPLEMENTED_ERROR
+        end
+
+        # 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:<br>
+        # * application must have been deployed
+        # Postconditions (delayed):<br>
+        # * state == stopped
+        # @param [String] application_id Id of the application which is to be stopped
+        # @raise [Nucleus::Errors::AdapterResourceNotFoundError] if the application could not be found
+        # @raise [Nucleus::Errors::EndpointAuthenticationError] if the authentication on the endpoint failed
+        # @raise [Nucleus::Errors::SemanticAdapterRequestError] if the application is not deployed
+        # @return [Hash, Nucleus::API::Models::Application] application entity compatible Hash
+        def stop(application_id)
+          fail NOT_IMPLEMENTED_ERROR
+        end
+
+        # 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:<br>
+        # * application must have been deployed
+        # Postconditions (delayed):<br>
+        # * state == running
+        # @param [String] application_id Id of the application which is to be restarted
+        # @raise [Nucleus::Errors::AdapterResourceNotFoundError] if the application could not be found
+        # @raise [Nucleus::Errors::EndpointAuthenticationError] if the authentication on the endpoint failed
+        # @raise [Nucleus::Errors::SemanticAdapterRequestError] if the application is not deployed
+        # @return [Hash, Nucleus::API::Models::Application] application entity compatible Hash
+        def restart(application_id)
+          fail NOT_IMPLEMENTED_ERROR
+        end
+
+        # Deploy the data of the application given the compressed application archive.<br>
+        # The application shall not be running when the deployment is finished.
+        # Postconditions (delayed):<br>
+        # * state == deployed
+        # @param [String] application_id Id of the application for which the data is to be deployed
+        # @param [Tempfile] application_archive compressed application archive that shall be deployed
+        # @param [Symbol] compression_format archive formats, see {Nucleus::API::Enums::CompressionFormats.all}
+        #   for a list of all allowed values
+        # @raise [Nucleus::Errors::AdapterResourceNotFoundError] if the application could not be found
+        # @raise [Nucleus::Errors::EndpointAuthenticationError] if the authentication on the endpoint failed
+        # @raise [Nucleus::Errors::AdapterRequestError] if the application archive that shall be deployed is no
+        #   valid application archive, or if the application_archive / compression_format are not supported
+        # @return [void]
+        def deploy(application_id, application_archive, compression_format)
+          fail NOT_IMPLEMENTED_ERROR
+        end
+
+        # Rebuild the recently deployed bits of the application.<br>
+        # 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.
+        # @param [String] application_id Id of the application which is to be rebuild
+        # @raise [Nucleus::Errors::AdapterResourceNotFoundError] if the application could not be found
+        # @raise [Nucleus::Errors::EndpointAuthenticationError] if the authentication on the endpoint failed
+        # @return [Hash, Nucleus::API::Models::Application] application entity compatible Hash
+        def rebuild(application_id)
+          fail NOT_IMPLEMENTED_ERROR
+        end
+
+        # 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.
+        # @param [String] application_id Id of the application of which the data is to be downloaded
+        # @param [Symbol] compression_format archive formats, see {Nucleus::API::Enums::CompressionFormats.all}
+        #   for a list of all allowed values
+        # @raise [Nucleus::Errors::AdapterResourceNotFoundError] if the application could not be found
+        # @raise [Nucleus::Errors::EndpointAuthenticationError] if the authentication on the endpoint failed
+        # @raise [Nucleus::Errors::AdapterRequestError] if the application archive that shall be deployed is no
+        #   valid application archive, or if the compression_format is not supported
+        # @return [StringIO] binary application data
+        def download(application_id, compression_format)
+          fail NOT_IMPLEMENTED_ERROR
+        end
+
+        # TODO: Finish documentation when vertical scaling is added
+        # Scale the application and adjust the number of instances that shall be running.
+        # @param [String] application_id Id of the application which is to be scaled
+        # @raise [Nucleus::Errors::AdapterResourceNotFoundError] if the application could not be found
+        # @raise [Nucleus::Errors::EndpointAuthenticationError] if the authentication on the endpoint failed
+        # @raise [Nucleus::Errors::SemanticAdapterRequestError] if the number of instances is disallowed on the platform
+        # @return [Hash, Nucleus::API::Models::Application] application entity compatible Hash
+        def scale(application_id, instances)
+          fail NOT_IMPLEMENTED_ERROR
+        end
+
+        # Assert whether the given log_id is valid for the application_id.
+        # @param [String] application_id Id of the application of which the log existence is to be checked
+        # @param [String] log_id Id of the log whose existence is to be checked
+        # @raise [Nucleus::Errors::AdapterResourceNotFoundError] if the application could not be found
+        # @raise [Nucleus::Errors::EndpointAuthenticationError] if the authentication on the endpoint failed
+        # @return [Boolean] returns true if there is a log for the application with the log_id,
+        #   false if it does not exist
+        def log?(application_id, log_id)
+          fail NOT_IMPLEMENTED_ERROR
+        end
+
+        # Get a list of all logs that are available for the application.
+        # @param [String] application_id Id of the application of which the logs are to be listed
+        # @raise [Nucleus::Errors::AdapterResourceNotFoundError] if the application could not be found
+        # @raise [Nucleus::Errors::EndpointAuthenticationError] if the authentication on the endpoint failed
+        # @return [Hash, Nucleus::API::Models::Logs] log entity list compatible hash
+        def logs(application_id)
+          fail NOT_IMPLEMENTED_ERROR
+        end
+
+        # Retrieve all log entries of the log.
+        # @param [String] application_id Id of the application of which the log_entries are to be retrieved
+        # @param [String] log_id Id of the log for which the entries are to be retrieved
+        # @raise [Nucleus::Errors::AdapterResourceNotFoundError] if the application or log could not be found
+        # @raise [Nucleus::Errors::EndpointAuthenticationError] if the authentication on the endpoint failed
+        # @return [Array<String>] array of log entries, starting with the earliest entry at pos [0]
+        def log_entries(application_id, log_id)
+          fail NOT_IMPLEMENTED_ERROR
+        end
+
+        # 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 {Nucleus::Adapters::TailStopper TailStopper}
+        # is called.
+        # @param [String] application_id Id of the application of which the log is to be tailed
+        # @param [String] log_id Id of the log that is to be tailed
+        # @param [Nucleus::StreamCallback] stream stream callback to which messages can be sent via
+        #   the +send_message+ method
+        # @raise [Nucleus::Errors::AdapterResourceNotFoundError] if the application or log could not be found
+        # @raise [Nucleus::Errors::EndpointAuthenticationError] if the authentication on the endpoint failed
+        # @return [Nucleus::Adapters::TailStopper] callback object to stop the ongoing tail process
+        def tail(application_id, log_id, stream)
+          fail NOT_IMPLEMENTED_ERROR
+        end
+
+        # List all services that are available at the endpoint.
+        # @raise [Nucleus::Errors::EndpointAuthenticationError] if the authentication on the endpoint failed
+        # @return [Hash, Nucleus::API::Models::Services] services list compatible hash
+        def services
+          fail NOT_IMPLEMENTED_ERROR
+        end
+
+        # Retrieve the service entity matching the given service_id.
+        # @param [String] service_id Id of the service that is to be retrieved
+        # @raise [Nucleus::Errors::AdapterResourceNotFoundError] if the service could not be found
+        # @raise [Nucleus::Errors::EndpointAuthenticationError] if the authentication on the endpoint failed
+        # @return [Hash, Nucleus::API::Models::Service] service entity compatible hash
+        def service(service_id)
+          fail NOT_IMPLEMENTED_ERROR
+        end
+
+        # List all plans that can be chosen for the service with the service_id, ascending order on the price.
+        # @param [String] service_id Id of the service the plans belong to
+        # @raise [Nucleus::Errors::AdapterResourceNotFoundError] if the service could not be found
+        # @raise [Nucleus::Errors::EndpointAuthenticationError] if the authentication on the endpoint failed
+        # @return [Hash, Nucleus::API::Models::ServicePlans] service plan list compatible hash
+        def service_plans(service_id)
+          fail NOT_IMPLEMENTED_ERROR
+        end
+
+        # Show the plan with the plan_id that is applicable to the service with the service_id.
+        # @param [String] service_id Id of the service the plans belongs to
+        # @raise [Nucleus::Errors::AdapterResourceNotFoundError] if the service or the plan could not be found
+        # @raise [Nucleus::Errors::EndpointAuthenticationError] if the authentication on the endpoint failed
+        # @return [Hash, Nucleus::API::Models::ServicePlan] service plan entity compatible hash
+        def service_plan(service_id, plan_id)
+          fail NOT_IMPLEMENTED_ERROR
+        end
+
+        # List all services that are installed on the application with the given application_id.
+        # @param [String] application_id Id of the application of which the services are to be listed of
+        # @raise [Nucleus::Errors::AdapterResourceNotFoundError] if the application could not be found
+        # @raise [Nucleus::Errors::EndpointAuthenticationError] if the authentication on the endpoint failed
+        # @return [Hash, Nucleus::API::Models::InstalledServices] installed services list compatible hash
+        def installed_services(application_id)
+          fail NOT_IMPLEMENTED_ERROR
+        end
+
+        # Retrieve the installed service entity matching the given service_id that is installed
+        # on the application with the given application_id.
+        # @param [String] service_id Id of the installed service that is to be retrieved
+        # @raise [Nucleus::Errors::AdapterResourceNotFoundError] if the application or service could not be found
+        # @raise [Nucleus::Errors::EndpointAuthenticationError] if the authentication on the endpoint failed
+        # @return [Hash, Nucleus::API::Models::InstalledService] installed service entity compatible hash
+        def installed_service(application_id, service_id)
+          fail NOT_IMPLEMENTED_ERROR
+        end
+
+        # Add the service with the service_id to the application with the application_id.
+        # @param [String] application_id Id of the application of which the service is to be added to
+        # @param [Hash, Nucleus::API::Models::Service] service_entity service entity compatible Hash.
+        # @option env_var [String] :id ID of the service to add to the application
+        # @param [Hash, Nucleus::API::Models::ServicePlan] plan_entity service plan entity compatible Hash.
+        # @option env_var [String] :id ID of the service plan that shall be applied
+        # @raise [Nucleus::Errors::AdapterResourceNotFoundError] if the application could not be found
+        # @raise [Nucleus::Errors::EndpointAuthenticationError] if the authentication on the endpoint failed
+        # @raise [Nucleus::Errors::SemanticAdapterRequestError] if the service to add or the plan to use
+        #   could not be found
+        # @return [Hash, Nucleus::API::Models::InstalledService] installed service entity compatible hash
+        def add_service(application_id, service_entity, plan_entity)
+          fail NOT_IMPLEMENTED_ERROR
+        end
+
+        # 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.
+        # @param [String] application_id Id of the application of which the service is to be changed
+        # @param [String] service_id 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.
+        # @param [Hash, Nucleus::API::Models::ServicePlan] plan_entity service plan entity compatible Hash.
+        # @option env_var [String] :id ID of the service plan that shall be applied
+        # @raise [Nucleus::Errors::AdapterResourceNotFoundError] if the application could not be found or
+        #   the service was not installed on this application
+        # @raise [Nucleus::Errors::EndpointAuthenticationError] if the authentication on the endpoint failed
+        # @raise [Nucleus::Errors::SemanticAdapterRequestError] if the plan to use could not be found
+        # @return [Hash, Nucleus::API::Models::InstalledService] installed service entity compatible hash
+        def change_service(application_id, service_id, plan_entity)
+          fail NOT_IMPLEMENTED_ERROR
+        end
+
+        # Remove the installed service with the service_id from the application with the application_id.
+        # @param [String] application_id Id of the application of which the service is to be removed from
+        # @param [String] service_id 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.
+        # @raise [Nucleus::Errors::AdapterResourceNotFoundError] if the application could not be found or
+        #   the service was not installed on this application
+        # @raise [Nucleus::Errors::EndpointAuthenticationError] if the authentication on the endpoint failed
+        # @return [void]
+        def remove_service(application_id, service_id)
+          fail NOT_IMPLEMENTED_ERROR
+        end
+      end
+    end
+  end
+end