merging in changes for the 3.1 release

Author: Scott Thompson

CHANGELOG.textile

@@ -1,6 +1,10 @@
+*3.2*
+* Add password-based authentication with `SoftLayer::Client.with_password(username: '...', password: '...', ...)`.
+
 *3.1.0*
 * Many SoftLayer Attributes are now shadowed with snake_case names.  The old CamelCase versions are deprecated and will be removed in the next major release
 * New functionality related to network monitoring has been added
+
 *3.0*
 * Substantially rewrote the ObjectFilter class. ObjectFilters used to be hashes which made it easy to manipulate their content incorrectly. The new implementation has a strict interface that makes it harder to manipulate filters incorrectly.
 * Added a model for Virtual Server Image Templates (SoftLayer::ImageTemplate) - VirtualServerOrder now requires an instance of this class rather than allowing you to provide the global_id of an image

README.md

@@ -24,7 +24,7 @@ This will create a new folder named `doc` inside of the project source and popul
 
 This software is written by the SoftLayer Development Team [sldn@softlayer.com](mailto:sldn@softlayer.com).
 
-Please join us in the [SoftLayer Developer Network forums](http://forums.softlayer.com/forum/softlayer-developer-network)
+Please join us at [Stack Overflow](https://stackoverflow.com/). Stack Overflow Best Practices Tip: Tag your posts with “SoftLayer” so our team can easily find your post.
 
 # Contributer License Agreement
 

doc_src/Welcome.md

@@ -1,6 +1,6 @@
 # Welcome
 
-The `softlyer_api` Ruby Gem provides a convenient way to call into the SoftLayer API from the Ruby programming language. This is accomplished using the XML-RPC interface provided by SoftLayer and the XMLRPC client built into the core Ruby language.
+The `softlayer_api` Ruby Gem provides a convenient way to call into the SoftLayer API from the Ruby programming language. This is accomplished using the XML-RPC interface provided by SoftLayer and the XMLRPC client built into the core Ruby language.
 
 For more information about the SoftLayer API, and the routines and data structures it offers should visit the [SoftLayer Developer Network (SLDN) website](http://sldn.softlayer.com).
 
@@ -20,4 +20,4 @@ The Model layer is built atop the foundation as object class hierarchy. The clas
 
 The Model layer is by no means complete; quite to the contrary it is in its infancy and we believe that much of the development effort in the Gem will focus on incorporating new models into this layer. Because it is incomplete, however, we have put some effort into bridges from the functionality of the model, down to the lower level foundation, without trouble. Also, as a result of this, developers interested in using the Model layer should also should familiarize themselves with the Foundation.
 
-All developers should continue their exploration of the `softlayer_api` gem by examining the Foundation documentation. Clients that wish to make use of the abstractions provided in the object hierarchy may continue their exploration by looking at the Model Layer documentation. Developers who wish to expand the models found in the `softlayer_api` Gem should read the [Contribution Guide](ContributionGuide_md.html)
+All developers should continue their exploration of the `softlayer_api` gem by examining the Foundation documentation. Clients that wish to make use of the abstractions provided in the object hierarchy may continue their exploration by looking at the Model Layer documentation. Developers who wish to expand the models found in the `softlayer_api` Gem should read the [Contribution Guide](ContributionGuide_md.html)

lib/softlayer/Client.rb

@@ -58,6 +58,32 @@ def self.default_client=(new_default)
       @@default_client = new_default
     end
 
+    ##
+    # This will be using your username and password to get a portal
+    # token with which to authenticate client calls.
+    # This is a wrapper around Client.new. You can pass it the same
+    # parameters as with Client.new, with the exception that this will
+    # be expecting a password in the options hash.
+    def self.with_password(options = {})
+      if options[:username].nil? || options[:username].empty?
+        raise 'A username is required to create this client'
+      end
+
+      if options[:password].nil? || options[:password].empty?
+        raise 'A password is required to create this client'
+      end
+
+      service = SoftLayer::Service.new('SoftLayer_User_Customer')
+      token = service.getPortalLoginToken(
+        options[:username], options[:password]
+      )
+
+      options[:userId] = token['userId']
+      options[:authToken] = token['hash']
+
+      SoftLayer::Client.new(options)
+    end
+
     ##
     #
     # Clients are built with a number of settings:
@@ -76,10 +102,14 @@ def initialize(options = {})
       settings = Config.client_settings(options)
 
       # pick up the username from the options, the global, or assume no username
-      @username = settings[:username] || ""
+      @username = settings[:username]
 
       # do a similar thing for the api key
-      @api_key = settings[:api_key] || ""
+      @api_key = settings[:api_key]
+
+      # grab token pair
+      @userId = settings[:userId]
+      @authToken = settings[:authToken]
 
       # and the endpoint url
       @endpoint_url = settings[:endpoint_url] || API_PUBLIC_ENDPOINT
@@ -90,19 +120,39 @@ def initialize(options = {})
       # and assign a time out if the settings offer one
       @network_timeout = settings[:timeout] if settings.has_key?(:timeout)
 
-      raise "A SoftLayer Client requires a username" if !@username || @username.empty?
-      raise "A SoftLayer Client requires an api_key" if !@api_key || @api_key.empty?
       raise "A SoftLayer Client requires an endpoint URL" if !@endpoint_url || @endpoint_url.empty?
     end
 
+    # return whether this client is using token-based authentication
+    def token_based?
+      @userId && @authToken && !@authToken.empty?
+    end
+
+    # return whether this client is using api_key-based authentication
+    def key_based?
+      @username && !@username.empty? && @api_key && !@api_key.empty?
+    end
+
     # return a hash of the authentication headers for the client
     def authentication_headers
-      {
-        "authenticate" => {
-          "username" => @username,
-          "apiKey" => @api_key
+      if token_based?
+        {
+          'authenticate' => {
+            'complexType' => 'PortalLoginToken',
+            'userId' => @userId,
+            'authToken' => @authToken
+          }
         }
-      }
+      elsif key_based?
+        {
+          'authenticate' => {
+            'username' => @username,
+            'apiKey' => @api_key
+          }
+        }
+      else
+        {}
+      end
     end
 
     # Returns a service with the given name.

lib/softlayer/ProductItemCategory.rb

@@ -14,7 +14,7 @@ module SoftLayer
   # DEPRECATION WARNING: The following configuration option keys have been deprecated and
   # will be removed with the next major version: capacityRestrictionMaximum, capacityRestrictionMinimum,
   # capacityRestrictionType, hourlyRecurringFee, laborFee, oneTimeFee, recurringFee, requiredCoreCount, setupFee
-  class ProductConfigurationOption < Struct.new(:capacity, :capacityRestrictionMaximum, :capicity_restriction_maximum,
+  class ProductConfigurationOption < Struct.new(:capacity, :capacityRestrictionMaximum, :capacity_restriction_maximum,
      :capacityRestrictionMinimum, :capacity_restriction_minimum, :capacityRestrictionType, :capacity_restriction_type,
      :description, :hourlyRecurringFee, :hourly_recurring_fee, :laborFee, :labor_fee, :oneTimeFee, :one_time_fee,
      :price_id, :recurringFee, :recurring_fee, :requiredCoreCount, :required_core_count, :setupFee, :setup_fee, :units)

lib/softlayer/base.rb

@@ -12,7 +12,7 @@
 module SoftLayer
   # The version number (including major, minor, and bugfix numbers)
   # This should change in accordance with the concept of Semantic Versioning
-  VERSION = "3.1.0"  # version history in the CHANGELOG.textile file at the root of the source
+  VERSION = "3.2.0"  # version history in the CHANGELOG.textile file at the root of the source
 
   # The base URL of the SoftLayer API available to the public internet.
   API_PUBLIC_ENDPOINT = 'https://api.softlayer.com/xmlrpc/v3/'

spec/Client_spec.rb

@@ -41,42 +41,43 @@
     expect(client.api_key).to eq 'fake_key'
   end
 
-  it 'raises an error if passed an empty user name' do
-    expect do
-      $SL_API_USERNAME = ''
-      client = SoftLayer::Client.new(:api_key => 'fake_key', :endpoint_url => 'http://fakeurl.org/')
-    end.to raise_error
-
-    expect do
-      $SL_API_USERNAME = 'good_username'
-      $SL_API_KEY = 'sample'
-      client = SoftLayer::Client.new(:username => '', :api_key => 'fake_key', :endpoint_url => 'http://fakeurl.org/')
-    end.to raise_error
-  end
-
-  it 'fails if the user name is nil' do
-    expect do
-      $SL_API_USERNAME = nil
-      client = SoftLayer::Client.new(:username => nil, :api_key => 'fake_key', :endpoint_url => 'http://fakeurl.org/')
-    end.to raise_error
-  end
-
-  it 'fails if the api_key is empty' do
-    expect do
-      $SL_API_KEY = ''
-      client = SoftLayer::Client.new(:username => 'fake_user', :endpoint_url => 'http://fakeurl.org/')
-    end.to raise_error
-
-    expect do
-      client = SoftLayer::Client.new(:username => 'fake_user', :api_key => '', :endpoint_url => 'http://fakeurl.org/')
-    end.to raise_error
-  end
-
-  it 'fails if the api_key is nil' do
-    expect do
-      $SL_API_KEY = nil
-      client = SoftLayer::Client.new(:username => 'fake_user', :endpoint_url => 'http://fakeurl.org/', :api_key => nil)
-    end.to raise_error
+  it 'produces empty auth headers if the username is empty' do
+
+    $SL_API_USERNAME = ''
+    client = SoftLayer::Client.new(:api_key => 'fake_key', :endpoint_url => 'http://fakeurl.org/')
+
+    expect(client.authentication_headers.empty?).to be true
+
+    $SL_API_USERNAME = 'good_username'
+    $SL_API_KEY = 'sample'
+    client = SoftLayer::Client.new(:username => '', :api_key => 'fake_key', :endpoint_url => 'http://fakeurl.org/')
+
+    expect(client.authentication_headers.empty?).to be true
+  end
+
+  it 'produces empty auth headers if the username is nil' do
+    $SL_API_USERNAME = nil
+    client = SoftLayer::Client.new(:username => nil, :api_key => 'fake_key', :endpoint_url => 'http://fakeurl.org/')
+
+    expect(client.authentication_headers.empty?).to be true
+  end
+
+  it 'produces empty auth headers if the api_key is empty' do
+    $SL_API_KEY = ''
+    client = SoftLayer::Client.new(:username => 'fake_user', :endpoint_url => 'http://fakeurl.org/')
+
+    expect(client.authentication_headers.empty?).to be true
+
+    client = SoftLayer::Client.new(:username => 'fake_user', :api_key => '', :endpoint_url => 'http://fakeurl.org/')
+
+    expect(client.authentication_headers.empty?).to be true
+  end
+
+  it 'produces empty auth headers if the api_key is nil' do
+    $SL_API_KEY = nil
+    client = SoftLayer::Client.new(:username => 'fake_user', :endpoint_url => 'http://fakeurl.org/', :api_key => nil)
+
+    expect(client.authentication_headers.empty?).to be true
   end
 
   it 'initializes by default with nil as the timeout' do