openstack_activeresource 0.2.1 → 0.3.0

data/VERSION

@@ -1 +1 @@
-0.2.1
+0.3.0

data/lib/hot_fixes.rb

@@ -17,8 +17,9 @@
 
 # Reopens ActiveResource::Base to fix "ActiveResource nested resources not being persisted"
 # See https://github.com/rails/rails/pull/3107
-module ActiveResource
+module ActiveResource #:nodoc:
   class Base
+
     def load(attributes, remove_root = false)
       raise ArgumentError, "expected an attributes Hash, got #{attributes.inspect}" unless attributes.is_a?(Hash)
       @prefix_options, attributes = split_options(attributes)
@@ -49,7 +50,9 @@ module ActiveResource
                 value.duplicable? ? value.dup : value
             end
       end
+
       self
     end
+
   end
 end

data/lib/open_stack/base.rb

@@ -26,6 +26,7 @@ module OpenStack
     self.format = :json
     self.timeout = 5
 
+    # Set the X-Auth-Token header if the OpenStack authentication token is present
     def self.headers
       if defined?(@headers)
         _headers = @headers
@@ -44,11 +45,15 @@ module OpenStack
 
     protected
 
+    # Set the authentication token
     def self.token=(token)
+      # Trying to be thread safe here...
       Thread.current[:open_stack_token] = token.is_a?(OpenStack::Keystone::Public::Auth::Token) ? token.id : token
     end
 
+    # Get the current authentication token
     def self.token
+      # Trying to be thread safe here...
       Thread.current[:open_stack_token]
     end
 

data/lib/open_stack/keystone/admin/role.rb

@@ -19,13 +19,20 @@ module OpenStack
   module Keystone
     module Admin
 
+      # An OpenStack Role ("admin view")
+      #
+      # ==== Attributes
+      # * +name+ - The name of this role
       class Role < Base
         self.element_name = "OS-KSADM/role"
 
-        def self.find_by_name(name)
-          all.each { |role| return role if role.name == name }
+        schema do
+          attribute :name, :string
+        end
 
-          nil
+        # List Roles with a given name
+        def self.find_by_name(name)
+          all.detect { |role| role.name == name }
         end
 
       end

data/lib/open_stack/keystone/admin/tenant.rb

@@ -19,6 +19,12 @@ module OpenStack
   module Keystone
     module Admin
 
+      # An OpenStack Tenant ("admin view")
+      #
+      # ==== Attributes
+      # * +name+ - The name of this tenant
+      # * +description+ - A description of this tenant
+      # * +enabled+ - True if this tenant is enabled
       class Tenant < Base
 
         schema do
@@ -31,7 +37,13 @@ module OpenStack
         validates :name, :format => {:with => /\A\w[\w\s]+\w\Z/}
         validates :description, :format => {:with => /\A[\w\s\.\-:@+,'"]+\Z/}
 
-        def self.find_every(options)
+        def initialize(params = {}, persisted = false) #:notnew:
+          super(params, persisted)
+
+          self.description = description
+        end
+
+        def self.find_every(options) #:nodoc:
           class_name = self.name.split('::').last.downcase
           begin
             case from = options[:from]
@@ -52,29 +64,46 @@ module OpenStack
           end
         end
 
+        # List of tenant with a given name
+        #
+        # ==== Attributes
+        # * +name+ - A string
         def self.find_by_name(name)
           all.detect { |x| x.name == name }
         end
 
-        def initialize(params = {}, persisted = false)
-          super(params, persisted)
-
-          self.description = description
-        end
-
-
+        # List of Users (instances of OpenStack::Keystone::Admin::User) in this tenant
+        #
+        # ==== Attributes
+        # * +scope+ - An ActiveResource scope (defaults to :all)
         def users(scope = :all)
           User.find(scope, :params => {:tenant_id => self.id})
         end
 
+        # Returns the instance of OpenStack::Keystone::Admin::User with the given id
+        #
+        # ==== Attributes
+        # * +id+ - A string
         def user(id)
           users(id)
         end
 
+        # List if roles in this tenant for a given instance of OpenStack::Keystone::Admin::User or user id
+        #
+        # ==== Attributes
+        # * +user+ - A string
+        # * +scope+ - An ActiveResource scope (defaults to :all)
         def user_roles(user, scope = :all)
-          Role.find(scope, :params => {:tenant_id => self.id, :user_id => user.is_a?(User) ? user.id : user})
+          user_id = user.is_a?(OpenStack::Keystone::Admin::User) ? user.id : user
+
+          Role.find(scope, :params => {:tenant_id => self.id, :user_id => user_id})
         end
 
+        # Adds a role to a user in this tenant
+        #
+        # ==== Attributes
+        # * +role+ - Instance of OpenStack::Keystone::Admin::Role or a role id
+        # * +user+ - Instance of OpenStack::Keystone::Admin::User or a user id
         def add_role_to_user(role, user)
           role_id = role.is_a?(OpenStack::Keystone::Admin::Role) ? role.id : role
           user_id = user.is_a?(OpenStack::Keystone::Admin::User) ? user.id : user
@@ -82,6 +111,11 @@ module OpenStack
           put("users/#{user_id}/roles/OS-KSADM/#{role_id}", {}, "null")
         end
 
+        # Removes a role to a user in this tenant
+        #
+        # ==== Attributes
+        # * +role+ - Instance of OpenStack::Keystone::Admin::Role or a role id
+        # * +user+ - Instance of OpenStack::Keystone::Admin::User or a user id
         def delete_role_from_user(role, user)
           role_id = role.is_a?(OpenStack::Keystone::Admin::Role) ? role.id : role
           user_id = user.is_a?(OpenStack::Keystone::Admin::User) ? user.id : user
@@ -89,10 +123,7 @@ module OpenStack
           delete("users/#{user_id}/roles/OS-KSADM/#{role_id}")
         end
 
-        def role(user)
-          users(user)
-        end
-
+        # Returns a filtered description for this tenant
         def description=(description)
           @attributes[:description] = description.gsub /[^\w\s\.\-:@+,'"]/, '_' if description
 

data/lib/open_stack/keystone/admin/user.rb

@@ -19,6 +19,14 @@ module OpenStack
   module Keystone
     module Admin
 
+      # An OpenStack User ("admin view")
+      #
+      # ==== Attributes
+      # * +name+ - The name of this user
+      # * +password+ - Password (possibly encrypted) of this user
+      # * +email+ - E-mail address of this user
+      # * +enabled+ - True if this user is enabled
+      # * +tenant_id+ - Default (i.e. primary) tenant for this user
       class User < Base
 
         schema do
@@ -37,7 +45,7 @@ module OpenStack
         validates_format_of :email, :with => /\A[-a-z0-9_+\.]+\@([-a-z0-9]+\.)+[a-z0-9]{2,4}\Z/i
         validates :enabled, :presence => true, :inclusion => {:in => [true, false]}
 
-        def initialize(attributes = {}, persisted = false)
+        def initialize(attributes = {}, persisted = false) #:notnew:
           attributes = attributes.with_indifferent_access
 
           if attributes[:tenant].present?
@@ -51,9 +59,8 @@ module OpenStack
           super(attributes, persisted)
         end
 
-        # Overload ActiveRecord::encode method
-        # Custom encoding to deal with openstack API
-        def encode(options={})
+        # Overloads ActiveRecord::encode method
+        def encode(options={}) #:nodoc: Custom encoding to deal with openstack API
           to_encode = {
               :user => {
                   :name => name,
@@ -68,12 +75,21 @@ module OpenStack
           to_encode.send("to_#{self.class.format.extension}", options)
         end
 
+        # List of users in a given tenant
+        #
+        # ==== Attributes
+        # * +tenant+ - An instance of OpenStack::Keystone::Admin::Tenant or a tenant id
         def self.all_by_tenant(tenant)
           tenant_id = tenant.is_a?(OpenStack::Keystone::Admin::Tenant) ? tenant.id : tenant
 
           all.select { |user| user.tenant_id == tenant_id }
         end
 
+        # Find a user in a given tenant
+        #
+        # ==== Attributes
+        # * +id+ - The user id
+        # * +tenant+ - An instance of OpenStack::Keystone::Admin::Tenant or a tenant id
         def self.find_by_tenant(id, tenant)
           tenant_id = tenant.is_a?(OpenStack::Keystone::Admin::Tenant) ? tenant.id : tenant
 
@@ -81,17 +97,28 @@ module OpenStack
           user.tenant_id == tenant_id ? user : nil
         end
 
+        # List of user with a given name
+        #
+        # ==== Attributes
+        # * +name+ - A string
         def self.find_by_name(name)
           all.detect { |user| user.name == name }
         end
-        
+
+        # The primary (default) tenant (i.e. an instance of OpenStack::Keystone::Admin::Tenant) associated with this user
         def tenant
           OpenStack::Keystone::Admin::Tenant.find tenant_id
         end
 
+        # File role(s) (i.e. instances of OpenStack::Keystone::Admin::UserRole) for this user in a given tenant
+        #
+        # ==== Attributes
+        # * +scope+ - The ActiveResource scope (defaults to :all)
+        # * +tenant+ - An optional instance of OpenStack::Keystone::Admin::Tenant (or a tenant id). Defaults to the primary tenant for this user
         def roles(scope = :all, tenant = nil)
           tenant_id = tenant.is_a?(OpenStack::Keystone::Admin::Tenant) ? tenant.id : (tenant || self.tenant_id)
-          OpenStack::Keystone::Admin::UserRole.find(scope, :params => { :tenant_id => tenant_id, :user_id => self.id })
+
+          OpenStack::Keystone::Admin::UserRole.find(scope, :params => {:tenant_id => tenant_id, :user_id => self.id})
         end
 
       end

data/lib/open_stack/keystone/admin/user_role.rb

@@ -19,10 +19,25 @@ module OpenStack
   module Keystone
     module Admin
 
+      # User Role ("admin view") (\*Warning:* incomplete)
+      #
+      # ==== Attributes
+      # * +name+ - The name of the Role
+      # * +description+ - A description of the role
       class UserRole < Base
         self.element_name = "role"
         self.site = superclass.site + "tenants/:tenant_id/users/:user_id"
 
+        schema do
+          attribute :name, :string
+          attribute :description, :string
+        end
+
+        # Return the associated instance of OpenStack::Keystone::Admin::Role
+        def role
+          OpenStack::Keystone::Admin::Role.find(self.id) if persisted?
+        end
+
       end
 
     end

data/lib/open_stack/keystone/public/auth.rb

@@ -19,6 +19,7 @@ module OpenStack
   module Keystone
     module Public
 
+      # End user authentication
       class Auth < Base
         self.element_name = "token"
 
@@ -31,7 +32,7 @@ module OpenStack
         validates :username, :presence => true, :unless => Proc.new { token.present? }
         validates :password, :presence => true, :unless => Proc.new { token.present? }
 
-        def initialize(attributes = {}, persisted = false)
+        def initialize(attributes = {}, persisted = false) #:notnew:
           attributes[:username] ||= ""
           attributes[:password] ||= ""
 
@@ -44,9 +45,8 @@ module OpenStack
           super(attributes, persisted)
         end
 
-        # Overload ActiveRecord::encode method
-        # Custom encoding to deal with openstack API
-        def encode(options={})
+        # Overloads ActiveRecord::encode method
+        def encode(options={}) #:nodoc: Custom encoding to deal with openstack API
           to_encode = {}
           if token.present?
             to_encode[:auth] = {
@@ -68,26 +68,33 @@ module OpenStack
           to_encode.send("to_#{self.class.format.extension}", options)
         end
 
-        # Catch some exceptions to perform "remote validation" of this resource
-        def save
+        def save #:nodoc: Catch some exceptions to perform "remote validation" of this resource
           super
         rescue ActiveResource::UnauthorizedAccess
           errors.add :password, I18n.t(:is_invalid)
           return false
         end
 
+        # Returns the service catalog for current authentication
         def service_catalog
           @attributes[:serviceCatalog].is_a?(Array) ? @attributes[:serviceCatalog] : []
         end
 
+        # Returns the OpenStack::Keystone::Public::Auth::Token instance for current authentication
         def token
           @attributes[:token]
         end
 
+        # Returns the token_id (string) for current authentication
         def token_id
           token.id if token.present?
         end
 
+        # Returns the list of endpoint for current authentication and for a given endpoint_type and region
+        #
+        # ==== Attributes
+        # * +endpoint_type+ - The type of endpoint. Currently valid values are: "Compute", "Volume"
+        # * +region+ - Restrict the search to given a region (can be omitted)
         def endpoints_for(endpoint_type, region=nil)
           return [] unless service_catalog.present?
 
@@ -105,18 +112,24 @@ module OpenStack
           endpoints
         end
 
+        # Returns the first endpoint for current authentication and for a given endpoint_type and region
+        #
+        # ==== Attributes
+        # * +endpoint_type+ - The type of endpoint. Currently valid values are: "Compute", "Volume"
+        # * +region+ - Restrict the search to given a region (can be omitted)
         def endpoint_for(endpoint_type, region=nil)
           endpoints_for(endpoint_type, region)[0]
         end
 
       end
 
+      # Authentication Token
       class Auth::Token < Base
         schema do
           attribute :expires, :string
         end
 
-        def initialize(attributes = {}, persisted = false)
+        def initialize(attributes = {}, persisted = false) #:notnew:
           attributes = attributes.with_indifferent_access
           new_attributes = {
               :id => attributes[:id],
@@ -126,10 +139,12 @@ module OpenStack
           super(new_attributes, persisted)
         end
 
+        # Expiration date and time for this token
         def expires_at
           DateTime.strptime(attributes[:expires], OpenStack::DATETIME_FORMAT)
         end
 
+        # True if the token is expired
         def expired?
           DateTime.strptime(attributes[:expires], OpenStack::DATETIME_FORMAT) < DateTime.now.utc
         end

data/lib/open_stack/keystone/public/base.rb

@@ -21,6 +21,7 @@ module OpenStack
 
       class Base < OpenStack::Common
 
+        # Get the Keystone endpoint assigned to OpenStack::Keystone::Public classes
         def self.site
           if self == OpenStack::Keystone::Public::Base
             Thread.current[:open_stack_keystone_public_site]
@@ -29,6 +30,7 @@ module OpenStack
           end
         end
 
+        # Set the Keystone endpoint assigned to OpenStack::Keystone::Public classes
         def self.site=(site)
           super(site)
           Thread.current[:open_stack_keystone_public_site] = @site

data/lib/open_stack/keystone/public/tenant.rb

@@ -19,6 +19,12 @@ module OpenStack
   module Keystone
     module Public
 
+      # An OpenStack Tenant ("public view")
+      #
+      # ==== Attributes
+      # * +name+ - The name of the tenant
+      # * +description+ - A description of the tenant
+      # * +enabled+ - True if the tenant is enabled
       class Tenant < Base
 
         schema do
@@ -28,7 +34,7 @@ module OpenStack
 
         end
 
-        def self.find_every(options)
+        def self.find_every(options) #:nodoc:
           class_name = self.name.split('::').last.downcase
           begin
             case from = options[:from]
@@ -49,12 +55,20 @@ module OpenStack
           end
         end
 
+        # List of tenants with a given name (accessible by the current authenticated user...)
+        #
+        # ==== Attributes
+        # * +name+ - A string
         def self.find_by_name(name)
-          self.all.each { |tenant| return tenant if tenant.name == name }
+          all.detect { |tenant| tenant.name == name }
         end
 
+        # The first tenant with a given name (accessible by the current authenticated user...)
+        #
+        # ==== Attributes
+        # * +name+ - A string
         def self.find_all_by_name(name)
-          self.all.reject! { |tenant| tenant.name != name }
+          all.reject! { |tenant| tenant.name != name }
         end
 
       end