--- /dev/null
+#
+# Author:: Mark Maglana (mmaglana@gmail.com)
+# Copyright:: Copyright (c) 2014 Mark Maglana
+# License:: Distributed under the MIT license
+# Homepage:: http://aviator.github.io/www/
+#
+module Aviator
+
+ #
+ # Manages a provider (e.g. OpenStack) session and serves as the entry point
+ # for a consumer class/object. See Session::new for notes on usage.
+ #
+ class Session
+
+ class AuthenticationError < StandardError
+ def initialize(last_auth_body)
+ super("Authentication failed. The server returned #{ last_auth_body }")
+ end
+ end
+
+
+ class EnvironmentNotDefinedError < ArgumentError
+ def initialize(path, env)
+ super("The environment '#{ env }' is not defined in #{ path }.")
+ end
+ end
+
+ class InitializationError < StandardError
+ def initialize
+ super("The session could not find :session_dump, :config_file, and " \
+ ":config in the constructor arguments provided")
+ end
+ end
+
+ class InvalidConfigFilePathError < ArgumentError
+ def initialize(path)
+ super("The config file at #{ path } does not exist!")
+ end
+ end
+
+
+ class NotAuthenticatedError < StandardError
+ def initialize
+ super("Session is not authenticated. Please authenticate before proceeding.")
+ end
+ end
+
+
+ class ValidatorNotDefinedError < StandardError
+ def initialize
+ super("The validator request name is not defined for this session object.")
+ end
+ end
+
+ #
+ # Create a new Session instance.
+ #
+ # <b>Initialize with a config file</b>
+ #
+ # Aviator::Session.new(:config_file => 'path/to/aviator.yml', :environment => :production)
+ #
+ # In the above example, the config file must have the following form:
+ #
+ # production:
+ # provider: openstack
+ # auth_service:
+ # name: identity
+ # host_uri: 'http://my.openstackenv.org:5000'
+ # request: create_token
+ # validator: list_tenants
+ # api_version: v2
+ # auth_credentials:
+ # username: myusername
+ # password: mypassword
+ # tenant_name: myproject
+ #
+ # <b>SIDENOTE:</b> For more information about the <tt>validator</tt> member, see Session#validate.
+ #
+ # Once the session has been instantiated, you may authenticate against the
+ # provider as follows:
+ #
+ # session.authenticate
+ #
+ # The members you put under <tt>auth_credentials</tt> will depend on the request
+ # class you declare under <tt>auth_service:request</tt> and what parameters it
+ # accepts. To know more about a request class and its parameters, you can use
+ # the CLI tool <tt>aviator describe</tt> or view the request definition file directly.
+ #
+ # If writing the <tt>auth_credentials</tt> in the config file is not acceptable,
+ # you may omit it and just supply the credentials at runtime. For example:
+ #
+ # session.authenticate do |params|
+ # params.username = ARGV[0]
+ # params.password = ARGV[1]
+ # params.tenant_name = ARGV[2]
+ # end
+ #
+ # See Session#authenticate for more info.
+ #
+ # Note that while the example config file above only has one environment (production),
+ # you can declare an arbitrary number of environments in your config file. Shifting
+ # between environments is as simple as changing the <tt>:environment</tt> to refer to that.
+ #
+ #
+ # <b>Initialize with an in-memory hash</b>
+ #
+ # You can create an in-memory hash with a structure similar to the config file but without
+ # the environment name. For example:
+ #
+ # configuration = {
+ # :provider => 'openstack',
+ # :auth_service => {
+ # :name => 'identity',
+ # :host_uri => 'http://devstack:5000/v2.0',
+ # :request => 'create_token',
+ # :validator => 'list_tenants'
+ # }
+ # }
+ #
+ # Supply this to the initializer using the <tt>:config</tt> option. For example:
+ #
+ # Aviator::Session.new(:config => configuration)
+ #
+ #
+ # <b>Initialize with a session dump</b>
+ #
+ # You can create a new Session instance using a dump from another instance. For example:
+ #
+ # session_dump = session1.dump
+ # session2 = Aviator::Session.new(:session_dump => session_dump)
+ #
+ # However, Session.load is cleaner and recommended over this method.
+ #
+ #
+ # <b>Optionally supply a log file</b>
+ #
+ # In all forms above, you may optionally add a <tt>:log_file</tt> option to make
+ # Aviator write all HTTP calls to the given path. For example:
+ #
+ # Aviator::Session.new(:config_file => 'path/to/aviator.yml', :environment => :production, :log_file => 'path/to/log')
+ #
+ def initialize(opts={})
+ if opts.has_key? :session_dump
+ initialize_with_dump(opts[:session_dump])
+ elsif opts.has_key? :config_file
+ initialize_with_config(opts[:config_file], opts[:environment])
+ elsif opts.has_key? :config
+ initialize_with_hash(opts[:config])
+ else
+ raise InitializationError.new
+ end
+
+ @log_file = opts[:log_file]
+ end
+
+ #
+ # Authenticates against the backend provider using the auth_service request class
+ # declared in the session's configuration. Please see Session.new for more information
+ # on declaring the request class to use for authentication.
+ #
+ # <b>Request params block</b>
+ #
+ # If the auth_service request class accepts parameters, you may supply that
+ # as a block and it will be directly passed to the request. For example:
+ #
+ # session = Aviator::Session.new(:config => config)
+ # session.authenticate do |params|
+ # params.username = username
+ # params.password = password
+ # params.tenant_name = project
+ # end
+ #
+ # If your configuration happens to have an <tt>auth_credentials</tt> in it, those
+ # will be overridden by this block.
+ #
+ # <b>Treat parameters as a hash</b>
+ #
+ # You can also treat the params struct like a hash with the attribute
+ # names as the keys. For example, we can rewrite the above as:
+ #
+ # session = Aviator::Session.new(:config => config)
+ # session.authenticate do |params|
+ # params[:username] = username
+ # params[:password] = password
+ # params[:tenant_name] = project
+ # end
+ #
+ # Keys can be symbols or strings.
+ #
+ # <b>Use a hash argument instead of a block</b>
+ #
+ # You may also provide request params as an argument instead of a block. This is
+ # especially useful if you want to mock Aviator as it's easier to specify ordinary
+ # argument expectations over blocks. Further rewriting the example above,
+ # we end up with:
+ #
+ # session = Aviator::Session.new(:config => config)
+ # session.authenticate :params => {
+ # :username => username,
+ # :password => password,
+ # :tenant_name => project
+ # }
+ #
+ # If both <tt>:params</tt> and a block are provided, the <tt>:params</tt>
+ # values will be used and the block ignored.
+ #
+ # <b>Success requirements</b>
+ #
+ # Expects an HTTP status 200 or 201 response from the backend. Any other
+ # status is treated as a failure.
+ #
+ def authenticate(opts={}, &block)
+ block ||= lambda do |params|
+ config[:auth_credentials].each do |key, value|
+ begin
+ params[key] = value
+ rescue NameError => e
+ raise NameError.new("Unknown param name '#{key}'")
+ end
+ end
+ end
+
+ response = auth_service.request(config[:auth_service][:request].to_sym, opts, &block)
+
+ if [200, 201].include? response.status
+ @auth_response = Hashish.new({
+ :headers => response.headers,
+ :body => response.body
+ })
+ update_services_session_data
+ else
+ raise AuthenticationError.new(response.body)
+ end
+ self
+ end
+
+ #
+ # Returns true if the session has been authenticated. Note that this relies on
+ # cached response from a previous run of Session#authenticate if one was made.
+ # If you want to check against the backend provider if the session is still valid,
+ # use Session#validate instead.
+ #
+ def authenticated?
+ !auth_response.nil?
+ end
+
+ #
+ # Returns its configuration.
+ #
+ def config
+ @config
+ end
+
+ #
+ # Returns a JSON string of its configuration and auth_data. This string can be streamed
+ # or stored and later re-loaded in another Session instance. For example:
+ #
+ # session = Aviator::Session.new(:config => configuration)
+ # str = session.dump
+ #
+ # # time passes...
+ #
+ # session = Aviator::Session.load(str)
+ #
+ def dump
+ JSON.generate({
+ :config => config,
+ :auth_response => auth_response
+ })
+ end
+
+
+ #
+ # Same as Session::load but re-uses the Session instance this method is
+ # called on instead of creating a new one.
+ #
+ def load(session_dump)
+ initialize_with_dump(session_dump)
+ update_services_session_data
+ self
+ end
+
+
+ def method_missing(name, *args, &block) # :nodoc:
+ service_name_parts = name.to_s.match(/^(\w+)_service$/)
+
+ if service_name_parts
+ get_service_obj(service_name_parts[1])
+ else
+ super name, *args, &block
+ end
+ end
+
+
+ #
+ # Creates a new Session object from a previous session's dump. See Session#dump for
+ # more information.
+ #
+ # If you want the newly deserialized session to log its output, add a <tt>:log_file</tt>
+ # option.
+ #
+ # Aviator::Session.load(session_dump_str, :log_file => 'path/to/aviator.log')
+ #
+ def self.load(session_dump, opts={})
+ opts[:session_dump] = session_dump
+
+ new(opts)
+ end
+
+
+ #
+ # Returns the log file path. May be nil if none was provided during initialization.
+ #
+ def log_file
+ @log_file
+ end
+
+
+ #
+ # Calls the given request of the given service. An example call might look like:
+ #
+ # session.request :compute_service, :create_server do |p|
+ # p.name = "My Server"
+ # p.image_ref = "7cae8c8e-fb01-4a88-bba3-ae0fcb1dbe29"
+ # p.flavor_ref = "fa283da1-59a5-4245-8569-b6eadf69f10b"
+ # end
+ #
+ # Note that you can also treat the block's argument like a hash with the attribute
+ # names as the keys. For example, we can rewrite the above as:
+ #
+ # session.request :compute_service, :create_server do |p|
+ # p[:name] = "My Server"
+ # p[:image_ref] = "7cae8c8e-fb01-4a88-bba3-ae0fcb1dbe29"
+ # p[:flavor_ref] = "fa283da1-59a5-4245-8569-b6eadf69f10b"
+ # end
+ #
+ # Keys can be symbols or strings.
+ #
+ # You may also provide parameters as an argument instead of a block. This is
+ # especially useful when mocking Aviator as it's easier to specify ordinary
+ # argument expectations over blocks. Further rewriting the example above,
+ # we end up with:
+ #
+ # session.request :compute_service, :create_server, :params => {
+ # :name => "My Server",
+ # :image_ref => "7cae8c8e-fb01-4a88-bba3-ae0fcb1dbe29",
+ # :flavor_ref => "fa283da1-59a5-4245-8569-b6eadf69f10b"
+ # }
+ #
+ # If both <tt>:params</tt> and a block are provided, the values in <tt>:params</tt>
+ # will be used and the block ignored.
+ #
+ # <b>Return Value</b>
+ #
+ # The return value will be an instance of Hashish, a lightweight replacement for
+ # activesupport's HashWithIndifferentAccess, with the following structure:
+ #
+ # {
+ # :status => 200,
+ # :headers => {
+ # 'X-Auth-Token' => 'd9186f45ce5446eaa0adc9def1c46f5f',
+ # 'Content-Type' => 'application/json'
+ # },
+ # :body => {
+ # :some_key => :some_value
+ # }
+ # }
+ #
+ # Note that the members in <tt>:headers</tt> and <tt>:body</tt> will vary depending
+ # on the provider and the request that was made.
+ #
+ # ---
+ #
+ # <b>Request Options</b>
+ #
+ # You can further customize how the method behaves by providing one or more
+ # options to the call. For example, assuming you are using the <tt>openstack</tt>
+ # provider, the following will call the <tt>:create_server</tt> request of the
+ # v1 API of <tt>:compute_service</tt>.
+ #
+ # session.request :compute_service, :create_server, :api_version => v1, :params => params
+ #
+ # The available options vary depending on the provider. See the documentation
+ # on the provider's Provider class for more information (e.g. Aviator::Openstack::Provider)
+ #
+ def request(service_name, request_name, opts={}, &block)
+ service = send("#{service_name.to_s}_service")
+ response = service.request(request_name, opts, &block)
+ response.to_hash
+ end
+
+
+ #
+ # Returns true if the session is still valid in the underlying provider. This method calls
+ # the <tt>validator</tt> request class declared under <tt>auth_service</tt> in the
+ # configuration. The validator can be any request class as long as:
+ #
+ # * The request class exists!
+ # * Is not an anonymous request. Otherwise it will always return true.
+ # * Does not require any parameters
+ # * It returns an HTTP status 200 or 203 to indicate auth info validity.
+ # * It returns any other HTTP status to indicate that the auth info is invalid.
+ #
+ # See Session::new for an example on how to specify the request class to use for session validation.
+ #
+ # Note that this method requires the session to be previously authenticated otherwise a
+ # NotAuthenticatedError will be raised. If you just want to check if the session was previously
+ # authenticated, use Session#authenticated? instead.
+ #
+ def validate
+ raise NotAuthenticatedError.new unless authenticated?
+ raise ValidatorNotDefinedError.new unless config[:auth_service][:validator]
+
+ auth_with_bootstrap = auth_response.merge({ :auth_service => config[:auth_service] })
+
+ response = auth_service.request config[:auth_service][:validator].to_sym, :session_data => auth_with_bootstrap
+ response.status == 200 || response.status == 203
+ end
+
+
+ private
+
+
+ def auth_response
+ @auth_response
+ end
+
+
+ def auth_service
+ @auth_service ||= Service.new(
+ :provider => config[:provider],
+ :service => config[:auth_service][:name],
+ :default_session_data => { :auth_service => config[:auth_service] },
+ :log_file => log_file
+ )
+ end
+
+
+ def get_service_obj(service_name)
+ @services ||= {}
+
+ if @services[service_name].nil?
+ default_options = config["#{ service_name }_service"]
+
+ @services[service_name] = Service.new(
+ :provider => config[:provider],
+ :service => service_name,
+ :default_session_data => auth_response,
+ :default_options => default_options,
+ :log_file => log_file
+ )
+ end
+
+ @services[service_name]
+ end
+
+
+ def initialize_with_config(config_path, environment)
+ raise InvalidConfigFilePathError.new(config_path) unless Pathname.new(config_path).file?
+
+ all_config = Hashish.new(YAML.load_file(config_path))
+
+ raise EnvironmentNotDefinedError.new(config_path, environment) unless all_config[environment]
+
+ @config = all_config[environment]
+ end
+
+
+ def initialize_with_dump(session_dump)
+ session_info = Hashish.new(JSON.parse(session_dump))
+ @config = session_info[:config]
+ @auth_response = session_info[:auth_response]
+ end
+
+
+ def initialize_with_hash(hash_obj)
+ @config = Hashish.new(hash_obj)
+ end
+
+
+ def update_services_session_data
+ return unless @services
+
+ @services.each do |name, obj|
+ obj.default_session_data = auth_response
+ end
+ end
+
+ end
+
+end
projects / dsa-puppet.git / blobdiff