fog 1.7.0 → 1.8.0

data/lib/fog/brightbox/models/compute/account.rb

@@ -32,7 +32,7 @@ module Fog
         attribute :load_balancers_used
         attribute :library_ftp_host
         attribute :library_ftp_user
-        # This is always returned as null/nil unless performing a reset_ftp_password request
+        # This is always returned as nil unless after a call to reset_ftp_password
         attribute :library_ftp_password
 
         # Boolean flags
@@ -51,13 +51,19 @@ module Fog
         attribute :users
         attribute :zones
 
+        # Resets the account's image library FTP password returning the new value
+        #
+        # @return [String] Newly issue FTP password
+        #
         def reset_ftp_password
           requires :identity
-          connection.reset_ftp_password_account["library_ftp_password"]
+          data = connection.reset_ftp_password_account(identity)
+          merge_attributes(data)
+          library_ftp_password
         end
 
       end
 
     end
   end
-end
+end

data/lib/fog/brightbox/models/compute/server.rb

@@ -184,9 +184,10 @@ module Fog
         # Soft reboots often timeout if the OS missed the request so we do more
         # error checking trying to detect the timeout
         #
-        # @fixme - Using side effect of wait_for's (evaluated block) to detect timeouts
+        # @todo Needs cleaner error handling when the OS times out
         def soft_reboot
           shutdown
+          # FIXME Using side effect of wait_for's (evaluated block) to detect timeouts
           if wait_for(20) { ! ready? }
             # Server is now down, start it up again
             start

data/lib/fog/brightbox/models/compute/servers.rb

@@ -14,6 +14,38 @@ module Fog
           load(data)
         end
 
+        # Creates a server and maps an Cloud IP
+        #
+        # By default the public SSH key you have registered with
+        # Brightbox is already made available in an AWS compatible
+        # metdata service.
+        #
+        # @todo Support uploading of arbitary SSH keys
+        #
+        # @param [Hash] options
+        # @option options [String] name      Name for the server
+        # @option options [String] flavor_id Identifier for virtual hardware type to request
+        # @option options [String] image_id  Identifier for image to use when creating
+        # @option options [String] zone_id   Identifer for preferred zone to locate server in
+        # @option options [Array<String>] server_groups List of group identifiers for the server to join
+        #
+        # @return Fog::Compute::Brightbox::Server
+        #
+        def bootstrap(options = {})
+          server = create(options)
+
+          # Ensure server is now available
+          server.wait_for { ready? }
+
+          # To get a public IP address we need to map a cloud IP address
+          cip = connection.cloud_ips.allocate
+          cip.map(server)
+          cip.wait_for { mapped? }
+
+          # Reload so the public IP is now available
+          server.reload
+        end
+
         def get(identifier)
           return nil if identifier.nil? || identifier == ""
           data = connection.get_server(identifier)
@@ -26,4 +58,4 @@ module Fog
 
     end
   end
-end
+end

data/lib/fog/brightbox/oauth2.rb

@@ -0,0 +1,164 @@
+# This module covers Brightbox's partial implementation of OAuth 2.0
+# and enables fog clients to implement several authentictication strategies
+#
+# @see http://tools.ietf.org/html/draft-ietf-oauth-v2-10
+#
+module Fog::Brightbox::OAuth2
+
+  # This builds the simplest form of requesting an access token
+  # based on the arguments passed in
+  #
+  # @param [Fog::Connection] connection
+  # @param [CredentialSet] credentials
+  #
+  # @return [Excon::Response]
+  def request_access_token(connection, credentials)
+    token_strategy = credentials.best_grant_strategy
+
+    header_content = "#{credentials.client_id}:#{credentials.client_secret}"
+    encoded_credentials = Base64.encode64(header_content).chomp
+
+    connection.request({
+      :path => "/token",
+      :expects  => 200,
+      :headers  => {
+        'Authorization' => "Basic #{encoded_credentials}",
+        'Content-Type' => 'application/json'
+      },
+      :method   => 'POST',
+      :body     => Fog::JSON.encode(token_strategy.authorization_body_data)
+    })
+  end
+
+  # Encapsulates credentials required to request access tokens from the
+  # Brightbox authorisation servers
+  #
+  # @todo Interface to update certain credentials (after password change)
+  #
+  class CredentialSet
+    attr_reader :client_id, :client_secret, :username, :password
+    attr_reader :access_token, :refresh_token
+    #
+    # @param [String] client_id
+    # @param [String] client_secret
+    # @param [Hash] options
+    # @option options [String] :username
+    # @option options [String] :password
+    #
+    def initialize(client_id, client_secret, options = {})
+      @client_id     = client_id
+      @client_secret = client_secret
+      @username      = options[:username]
+      @password      = options[:password]
+      @access_token  = options[:access_token]
+      @refresh_token = options[:refresh_token]
+    end
+
+    # Returns true if user details are available
+    # @return [Boolean]
+    def user_details?
+      !!(@username && @password)
+    end
+
+    # Is an access token available for these credentials?
+    def access_token?
+      !!@access_token
+    end
+
+    # Is a refresh token available for these credentials?
+    def refresh_token?
+      !!@refresh_token
+    end
+
+    # Updates the credentials with newer tokens
+    def update_tokens(access_token, refresh_token = nil)
+      @access_token  = access_token
+      @refresh_token = refresh_token
+    end
+
+    # Based on available credentials returns the best strategy
+    #
+    # @todo Add a means to dictate which should or shouldn't be used
+    #
+    def best_grant_strategy
+      if refresh_token?
+        RefreshTokenStrategy.new(self)
+      elsif user_details?
+        UserCredentialsStrategy.new(self)
+      else
+        ClientCredentialsStrategy.new(self)
+      end
+    end
+  end
+
+  # This strategy class is the basis for OAuth2 grant types
+  #
+  # @abstract Need to implement {#authorization_body_data} to return a
+  #   Hash matching the expected parameter form for the OAuth request
+  #
+  # @todo Strategies should be able to validate if credentials are suitable
+  #   so just client credentials cannot be used with user strategies
+  #
+  class GrantTypeStrategy
+    def initialize(credentials)
+      @credentials = credentials
+    end
+
+    def authorization_body_data
+      raise "Not implemented"
+    end
+  end
+
+  # This implements client based authentication/authorization
+  # based on the existing trust relationship using the `none`
+  # grant type.
+  #
+  class ClientCredentialsStrategy < GrantTypeStrategy
+    def authorization_body_data
+      {
+        "grant_type" => "none",
+        "client_id"  => @credentials.client_id
+      }
+    end
+  end
+
+  # This passes user details through so the returned token
+  # carries the privileges of the user not account limited
+  # by the client
+  #
+  class UserCredentialsStrategy < GrantTypeStrategy
+    def authorization_body_data
+      {
+        "grant_type" => "password",
+        "client_id"  => @credentials.client_id,
+        "username"   => @credentials.username,
+        "password"   => @credentials.password
+      }
+    end
+  end
+
+  # This strategy attempts to use a refresh_token gained during an earlier
+  # request to reuse the credentials given originally
+  #
+  class RefreshTokenStrategy < GrantTypeStrategy
+    def authorization_body_data
+      {
+        "grant_type"    => "refresh_token",
+        "client_id"     => @credentials.client_id,
+        "refresh_token" => @credentials.refresh_token
+      }
+    end
+  end
+
+private
+
+  # This updates the current credentials if passed a valid response
+  #
+  # @param [CredentialSet] credentials Credentials to update
+  # @param [Excon::Response] response Response object to parse value from
+  #
+  def update_credentials_from_response(credentials, response)
+    response_data = Fog::JSON.decode(response.body)
+    credentials.update_tokens(response_data["access_token"], response_data["refresh_token"])
+  end
+end

data/lib/fog/brightbox/requests/compute/activate_console_server.rb

@@ -2,7 +2,14 @@ module Fog
   module Compute
     class Brightbox
       class Real
-
+        # Enable console access via VNC to the server for 15 minutes.
+        #
+        # @param [String] identifier Unique reference to identify the resource
+        #
+        # @return [Hash] The JSON response parsed to a Hash
+        #
+        # @see https://api.gb1.brightbox.com/1.0/#server_activate_console_server
+        #
         def activate_console_server(identifier)
           return nil if identifier.nil? || identifier == ""
           request("post", "/1.0/servers/#{identifier}/activate_console", [202])
@@ -11,4 +18,4 @@ module Fog
       end
     end
   end
-end
+end

data/lib/fog/brightbox/requests/compute/add_listeners_load_balancer.rb

@@ -2,7 +2,16 @@ module Fog
   module Compute
     class Brightbox
       class Real
-
+        # Adds a number of listeners to the load balancer to enable balancing across nodes for those settings.
+        #
+        # @param [String] identifier Unique reference to identify the resource
+        # @param [Hash] options
+        # @option options [Array] :listeners Array of Listener parameters. Timeout is optional and specified in milliseconds.
+        #
+        # @return [Hash, nil] The JSON response parsed to a Hash or nil if no options passed
+        #
+        # @see https://api.gb1.brightbox.com/1.0/#load_balancer_add_listeners_load_balancer
+        #
         def add_listeners_load_balancer(identifier, options)
           return nil if identifier.nil? || identifier == ""
           request("post", "/1.0/load_balancers/#{identifier}/add_listeners", [202], options)
@@ -11,4 +20,4 @@ module Fog
       end
     end
   end
-end
+end

data/lib/fog/brightbox/requests/compute/add_nodes_load_balancer.rb

@@ -2,7 +2,16 @@ module Fog
   module Compute
     class Brightbox
       class Real
-
+        # Add a number of nodes to the load balancer
+        #
+        # @param [String] identifier Unique reference to identify the resource
+        # @param [Hash] options
+        # @option options [Array] :nodes Array of Node parameters
+        #
+        # @return [Hash, nil] The JSON response parsed to a Hash or nil if no options passed
+        #
+        # @see https://api.gb1.brightbox.com/1.0/#load_balancer_add_nodes_load_balancer
+        #
         def add_nodes_load_balancer(identifier, options)
           return nil if identifier.nil? || identifier == ""
           request("post", "/1.0/load_balancers/#{identifier}/add_nodes", [202], options)
@@ -11,4 +20,4 @@ module Fog
       end
     end
   end
-end
+end

data/lib/fog/brightbox/requests/compute/add_servers_server_group.rb

@@ -2,20 +2,18 @@ module Fog
   module Compute
     class Brightbox
       class Real
-
-        # Add a number of servers to a server group
+        # Add a number of servers to the server group.
         #
-        #  >> Compute[:brightbox].add_servers_server_group "grp-12345", :servers => [{:server => "srv-abcde"}]
+        # @param [String] identifier Unique reference to identify the resource
+        # @param [Hash] options
+        # @option options [Array<Hash>] :servers Array of Hashes containing `{"server" => server_id}` for each server to add
         #
-        # == Parameters:
-        # * identifier (String) - The identifier of the server group to add to
-        # * options
-        #   * servers (Array) - An Array of Hashes containing {"server" => server_id} for each server to add
-        #   [\[{"server" => "srv-abcde"}, {"server" => "srv-fghij"}\]]
+        # @return [Hash, nil] The JSON response parsed to a Hash or nil if no options passed
         #
-        # == Returns:
+        # @see https://api.gb1.brightbox.com/1.0/#server_group_add_servers_server_group
         #
-        # A Ruby hash of the server response
+        # @example
+        #    Compute[:brightbox].add_servers_server_group "grp-12345", :servers => [{"server" => "srv-abcde"}, {"server" => "srv-fghij"}]
         #
         def add_servers_server_group(identifier, options)
           return nil if identifier.nil? || identifier == ""
@@ -25,4 +23,4 @@ module Fog
       end
     end
   end
-end
+end

data/lib/fog/brightbox/requests/compute/apply_to_firewall_policy.rb

@@ -2,7 +2,16 @@ module Fog
   module Compute
     class Brightbox
       class Real
-
+        # Applies firewall policy to given server group
+        #
+        # @param [String] identifier Unique reference to identify the resource
+        # @param [Hash] options
+        # @option options [String] :server_group Server Group to apply to
+        #
+        # @return [Hash, nil] The JSON response parsed to a Hash or nil if no options passed
+        #
+        # @see https://api.gb1.brightbox.com/1.0/#firewall_policy_apply_to_firewall_policy
+        #
         def apply_to_firewall_policy(identifier, options)
           return nil if identifier.nil? || identifier == ""
           request("post", "/1.0/firewall_policies/#{identifier}/apply_to", [202], options)
@@ -11,4 +20,4 @@ module Fog
       end
     end
   end
-end
+end

data/lib/fog/brightbox/requests/compute/create_api_client.rb

@@ -2,7 +2,16 @@ module Fog
   module Compute
     class Brightbox
       class Real
-
+        # Create a new API client for the account.
+        #
+        # @param [Hash] options
+        # @option options [String] :name
+        # @option options [String] :description
+        #
+        # @return [Hash, nil] The JSON response parsed to a Hash or nil if no options passed
+        #
+        # @see https://api.gb1.brightbox.com/1.0/#api_client_create_api_client
+        #
         def create_api_client(options)
           request("post", "/1.0/api_clients", [201], options)
         end
@@ -10,4 +19,4 @@ module Fog
       end
     end
   end
-end
+end

data/lib/fog/brightbox/requests/compute/create_application.rb

@@ -2,7 +2,16 @@ module Fog
   module Compute
     class Brightbox
       class Real
-
+        # Create a new application for the user.
+        #
+        # @param [Hash] options
+        # @option options [String] :name
+        # @option options [String] :description
+        #
+        # @return [Hash, nil] The JSON response parsed to a Hash or nil if no options passed
+        #
+        # @see https://api.gb1.brightbox.com/1.0/#application_create_application
+        #
         def create_application(options)
           request("post", "/1.0/applications", [201], options)
         end
@@ -10,4 +19,4 @@ module Fog
       end
     end
   end
-end
+end

data/lib/fog/brightbox/requests/compute/create_cloud_ip.rb

@@ -2,7 +2,17 @@ module Fog
   module Compute
     class Brightbox
       class Real
-
+        # Requests a new cloud IP address for the account.
+        #
+        # @param [Hash] options
+        # @option options [String] :reverse_dns Reverse DNS hostname
+        # @option options [String] :name Name for Cloud IP
+        # @option options [Array] :port_translators Port on which external clients connect and port on which your service is listening.
+        #
+        # @return [Hash, nil] The JSON response parsed to a Hash or nil if no options passed
+        #
+        # @see https://api.gb1.brightbox.com/1.0/#cloud_ip_create_cloud_ip
+        #
         def create_cloud_ip(options = {})
           request("post", "/1.0/cloud_ips", [201], options)
         end