aviator 0.0.9 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a9501d71ef567ef9bfe2a511a7122a23f8faca48
-  data.tar.gz: 9ae86b5df08bbceafb3481b6a4693ab2783996c1
+  metadata.gz: f56372f2f4fea06121bebdef1c2bccfef12c1f56
+  data.tar.gz: a17fe8facfb17ba357ceb772d9087e89d53a59ca
 SHA512:
-  metadata.gz: aed3dc71e256f15c8e314f4d781e369d23b6648fa7406c2e84a34f3326457e5c93fc1c2d2b073a0f71904947081da6191412e346d76ff8a5806184ffed1fd9af
-  data.tar.gz: 435d8acd62fcbf0fc8ed08f2ee9fabd6baf87f17b8258eea76f7fae30faaee19b3b36f6e74239bab1914b3603a2f10ca3cf474ca22a19e69c70edde26f0b72d1
+  metadata.gz: 00aa0e3555582535cfac8d3699259d31140cc88f920f2d162c064d64e2b483ccc8bb484aa29f59f99be99cda355d57a450de29c08714d14e07d23978a9c3a116
+  data.tar.gz: 7a0155396260c67ab9c7f1c0d03504f7a1e81f8e36463b347303198375c0486d415acd5e97d265036a0ac7a7be9878c9d304ee2743d98dd40b6733f594611cef

data/Gemfile

@@ -18,5 +18,6 @@ group :test do
   gem 'json', '~> 1.7.0'
   gem 'minitest', '~> 4.7.0'
   gem 'minitest-reporters', '~> 0.14.20'
+  gem 'mocha', '~> 1.1.0'
   gem 'vcr', '~> 2.8.0'
 end

data/aviator.gemspec

@@ -22,24 +22,24 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   # Runtime dependencies
-  spec.add_dependency 'faraday', '>= 0.8.8'
-  spec.add_dependency 'thor', '>= 0.18.1'
-  spec.add_dependency 'terminal-table', '>= 1.4.5'
+  spec.add_runtime_dependency 'faraday', '~> 0.8', '>= 0.8.8'
+  spec.add_runtime_dependency 'thor', '~> 0.18', '>= 0.18.1'
+  spec.add_runtime_dependency 'terminal-table', '~> 1.4', '>= 1.4.5'
 
   # Development dependencies. See Gemfile for more development deps.
-  spec.add_development_dependency "bundler", ">= 1.0"
-  spec.add_development_dependency 'rb-fsevent', '~> 0.9.0'
-  spec.add_development_dependency 'guard', '~> 1.8.0'
-  spec.add_development_dependency 'guard-rake', '~> 0.0.0'
-  spec.add_development_dependency 'guard-minitest', '~> 0.5.0'
+  spec.add_development_dependency 'bundler', '~> 1.0'
+  spec.add_development_dependency 'rb-fsevent', '~> 0.9', '>= 0.9.0'
+  spec.add_development_dependency 'guard', '~> 1.8', '>= 1.8.0'
+  spec.add_development_dependency 'guard-rake', '~> 0.0', '>= 0.0.0'
+  spec.add_development_dependency 'guard-minitest', '~> 0.5', '>= 0.5.0'
 
   if /darwin|mac os/ === RbConfig::CONFIG['host_os']
-    spec.add_development_dependency 'terminal-notifier-guard', '~> 1.5.3'
+    spec.add_development_dependency 'terminal-notifier-guard', '~> 1.5', '>= 1.5.3'
   else
-    spec.add_development_dependency 'ruby_gntp', '~> 0.3.0'
+    spec.add_development_dependency 'ruby_gntp', '~> 0.3', '>= 0.3.0'
   end
 
-  spec.add_development_dependency 'pry', '~> 0.9.0'
-  spec.add_development_dependency 'yard', '~> 0.8.0'
-  spec.add_development_dependency 'redcarpet', '~> 2.3.0'
+  spec.add_development_dependency 'pry', '~> 0.9', '>= 0.9.0'
+  spec.add_development_dependency 'yard', '~> 0.8', '>= 0.8.0'
+  spec.add_development_dependency 'redcarpet', '~> 2.3', '>= 2.3.0'
 end

data/lib/aviator/core/session.rb

@@ -1,5 +1,13 @@
 module Aviator
 
+  #
+  # Manages a provider (e.g. OpenStack) session.
+  #
+  # Author::    Mark Maglana (mmaglana@gmail.com)
+  # Copyright:: Copyright (c) 2014 Mark Maglana
+  # License::   Distributed under the MIT license
+  # Homepage::  http://aviator.github.io/www/
+  #
   class Session
 
     class AuthenticationError < StandardError
@@ -42,7 +50,91 @@ module Aviator
       end
     end
 
-
+    #
+    # Create a new Session instance with options provided in <tt>opts</tt> which can
+    # have many forms discussed below.
+    #
+    # <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
+    #
+    # Once the session has been instantiated, you may authenticate against the
+    # provider as follows:
+    #
+    #  session.authenticate
+    #
+    # Note that the required items under <tt>auth_credentials</tt> in the config
+    # file depends on the required parameters of the request class declared under
+    # <tt>auth_service</tt>. 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 instance, assume that the <tt>auth_credentials</tt> section in the
+    # config file above is missing. You would then authenticate as follows:
+    #
+    #  session.authenticate do |params|
+    #    params.username    = ARGV[0]
+    #    params.password    = ARGV[1]
+    #    params.tenant_name = ARGV[2]
+    #  end
+    #
+    # Please 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 which is similar in structure to the config file except
+    # that you don't need to specify an 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])
@@ -57,15 +149,47 @@ module Aviator
       @log_file = opts[:log_file]
     end
 
-
+    #
+    # Authenticates against the auth_service request class declared in the session's
+    # configuration during initialization. Please see Session.new for more information
+    # on declaring the request class to use for authentication.
+    #
+    # If the auth_service request class accepts a parameter block, you may also supply that
+    # when calling this method 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
+    #
+    # Expects an HTTP status 200 or 201. Any other status is treated as a failure.
+    #
+    # 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 = 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.
+    #
     def authenticate(&block)
       block ||= lambda do |params|
-        environment[:auth_credentials].each do |key, value|
-          params[key] = value
+        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 environment[:auth_service][:request].to_sym, &block
+      response = auth_service.request config[:auth_service][:request].to_sym, &block
 
       if [200, 201].include? response.status
         @auth_response = Hashish.new({
@@ -79,20 +203,43 @@ module Aviator
       self
     end
 
-
+    #
+    # Returns true if the session has been authenticated.
+    #
     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({
-        :environment   => environment,
+        :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
@@ -111,6 +258,14 @@ module Aviator
     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, make sure to indicate it on load
+    #
+    #  Aviator::Session.load(session_dump_str, :log_file => 'path/to/aviator.log')
+    #
     def self.load(session_dump, opts={})
       opts[:session_dump] = session_dump
 
@@ -118,13 +273,72 @@ module Aviator
     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.
+    #
+    # ---
+    #
+    # <b>Request Options</b>
+    #
+    # You can further customize how the request is fulfilled by providing one or more
+    # options to the method call. For example, the following ensures that the request
+    # will call the :create_server request for the v1 API.
+    #
+    #  session.request :compute_service, :create_server, :api_version => v1
+    #
+    # 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={}, &params)
+      service = send("#{service_name.to_s}_service")
+      service.request(request_name, opts, &params)
+    end
+
+
+    #
+    # Returns true if the session is still valid in the underlying provider. This method does this
+    # by calling the validator request class declared declared under <tt>auth_service</tt> in the
+    # configuration. The validator can be any request class as long as:
+    #
+    # * The request class exists!
+    # * 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.
+    #
     def validate
       raise NotAuthenticatedError.new unless authenticated?
-      raise ValidatorNotDefinedError.new unless environment[:auth_service][:validator]
+      raise ValidatorNotDefinedError.new unless config[:auth_service][:validator]
 
-      auth_with_bootstrap = auth_response.merge({ :auth_service  => environment[:auth_service] })
+      auth_with_bootstrap = auth_response.merge({ :auth_service  => config[:auth_service] })
 
-      response = auth_service.request environment[:auth_service][:validator].to_sym, :session_data => auth_with_bootstrap
+      response = auth_service.request config[:auth_service][:validator].to_sym, :session_data => auth_with_bootstrap
       response.status == 200 || response.status == 203
     end
 
@@ -139,27 +353,22 @@ module Aviator
 
     def auth_service
       @auth_service ||= Service.new(
-        :provider             => environment[:provider],
-        :service              => environment[:auth_service][:name],
-        :default_session_data => { :auth_service => environment[:auth_service] },
+        :provider             => config[:provider],
+        :service              => config[:auth_service][:name],
+        :default_session_data => { :auth_service => config[:auth_service] },
         :log_file             => log_file
       )
     end
 
 
-    def environment
-      @environment
-    end
-
-
     def get_service_obj(service_name)
       @services ||= {}
 
       if @services[service_name].nil?
-        default_options = environment["#{ service_name }_service"]
+        default_options = config["#{ service_name }_service"]
 
         @services[service_name] = Service.new(
-          :provider             => environment[:provider],
+          :provider             => config[:provider],
           :service              => service_name,
           :default_session_data => auth_response,
           :default_options      => default_options,
@@ -174,28 +383,23 @@ module Aviator
     def initialize_with_config(config_path, environment)
       raise InvalidConfigFilePathError.new(config_path) unless Pathname.new(config_path).file?
 
-      config = Hashish.new(YAML.load_file(config_path))
+      all_config = Hashish.new(YAML.load_file(config_path))
 
-      raise EnvironmentNotDefinedError.new(config_path, environment) unless config[environment]
+      raise EnvironmentNotDefinedError.new(config_path, environment) unless all_config[environment]
 
-      @environment = config[environment]
+      @config = all_config[environment]
     end
 
 
     def initialize_with_dump(session_dump)
       session_info   = Hashish.new(JSON.parse(session_dump))
-      @environment   = session_info[:environment]
+      @config        = session_info[:config]
       @auth_response = session_info[:auth_response]
     end
 
 
     def initialize_with_hash(hash_obj)
-      @environment = Hashish.new(hash_obj)
-    end
-
-
-    def log_file
-      @log_file
+      @config = Hashish.new(hash_obj)
     end
 
 

data/lib/aviator/openstack/identity/requests/v2/admin/create_user.rb

@@ -24,6 +24,7 @@ module Aviator
     param :email,     :required => false
     param :enabled,   :required => false
     param :tenantId,  :required => false, :alias => :tenant_id
+    param :extras,    :required => false
 
 
     def body

data/lib/aviator/openstack/identity/requests/v2/admin/update_user.rb

@@ -20,6 +20,7 @@ module Aviator
     param :email,     :required => false
     param :enabled,   :required => false
     param :tenantId,  :required => false, :alias => :tenant_id
+    param :extras,    :required => false
 
 
     def body

data/lib/aviator/openstack/provider.rb

@@ -1,6 +1,68 @@
 module Aviator
 module Openstack
 
+  #
+  # Manages a provider (e.g. OpenStack) session.
+  #
+  # Author::    Mark Maglana (mmaglana@gmail.com)
+  # Copyright:: Copyright (c) 2014 Mark Maglana
+  # License::   Distributed under the MIT license
+  # Homepage::  http://aviator.github.io/www/
+  #
+  # <b>Request Options</b>
+  #
+  # The following options may be used in combination with each other when calling
+  # an OpenStack request class
+  #
+  # :api_version => :v2::
+  #     Forces Aviator to use the request class for the v2 API. For any other
+  #     version, replace Note that this may throw an error if no such request
+  #     class exists. If you want to globally specify the API version to use for
+  #     a specific service, declare it in your config file under the correct
+  #     environment. For example:
+  #
+  #  production:
+  #    provider: openstack
+  #    ...
+  #    compute_service:
+  #       api_version: v2
+  #
+  # Note that the <tt>:api_version</tt> option overrides whatever is declared in the
+  # configuration.
+  #
+  # :endpoint_type => (:public|:admin)::
+  #    This allows you to be specific about the endpoint type in cases where two
+  #    request classes under admin and public endpoints of the same service share
+  #    the same name. This is true, for example, for the :list_tenants request of
+  #    the identity service's v2 API. Its public endpoint will return only the tenants
+  #    the user is a member of whereas the admin endpoint will return all tenants
+  #    in the system.
+  #
+  # :session_data => Hash::
+  #    Under normal situations, you wouldn't need to use this as it is automatically populated
+  #    by the Session object provided it is authenticated. The specific use case when you'd
+  #    need to set thsi optin is when you want to use Aviator to seed your OpenStack installation.
+  #    In such a scenario, you would need to use a service token since no usernames and tenants
+  #    would exist yet in the environment. To use a service token with Aviator, you will need to
+  #    write something similar to the following example:
+  #
+  #  openstack = Aviator::Session.new(:config => { :provider => 'openstack'})
+  #
+  #  session_data = {:base_url      => 'http://example.com',
+  #                  :service_token => 'service-token-created-at-openstack-install-time'}
+  #
+  #  openstack.request :identity, :create_tenant, :api_version => :v2, :session_data => session_data) do |params|
+  #    params.name        = 'Tenant A'
+  #    params.description = 'First Tenant!'
+  #    params.enabled     = true
+  #  end
+  #
+  # Notice how the above code skips authentication. This is because the service token is
+  # pre-validated and ready for use with any request. Also note how we're providing a <tt>:base_url</tt>
+  # member in our session data. This is necessary since we normally get the service endpoints from
+  # Keystone when we authenticate. Now since we are not authenticating against Keystone, we don't have
+  # that catalogue to begin with. Thus the need to hardcode it in the request.
+  #
   module Provider
 
     class MultipleServiceApisError < StandardError
@@ -35,6 +97,7 @@ EOF
 
     class << self
 
+      #:nodoc:
       def find_request(service, name, session_data, options)
         service = service.to_s
         endpoint_type = options[:endpoint_type]