Added firewall ordering

Author: SLsthompson

CHANGELOG.textile

@@ -1,10 +1,11 @@
 *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 just the global_id of an image
+* 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
 * Added a model for data centers (SoftLayer::Datacenter). Bare Metal, Bare Metal Package, and Virtual server orders now use an instance of Datacenter to identify where their servers will be provisioned. The routines in those classes which used to provide lists of valid data center names now return data center objects.
 * Virtual Server Upgrades are now handled by the VirtualServerUpgradeOrder class and not the VirtualServer class. This change was made for several reasons. Firt and foremost, it allows multiple aspects of a virtual server to be upgraded at once without having to wait on separate transactions to complete between upgrades. Secondly it opens the door for additional upgrades (for example, to disk configuration) to be added in the future.
 * Added a method to reboot servers.
 * The routine to retreive the open tickets on an account has been moved from the Ticket class. The set of open tickets is now a dynamic property of an account object.
+* The Model Layer now includes models for Server (aka. Shared) and VLAN (aka. Dedicated) firewalls in the ServerFirewall, and VLANFireall classes respectively.  There are corresponding classes for ordering firewalls (ServerFirewallOrder and VLANFirewallOrder).  To facilitate the process of locating the 'id' for a firewall, the Account class includes the find_VLAN_with_number routine which lets you look up the segments of a firewall from the VLAN nubmer.
 
 *2.2*
 * Added the ability to set a timout for network requests. The timeout is given when a client is created by passing the :timeout hash parameter when creating a client. The value of the parameter is an integer number of seconds.

examples/order_server_firewall.rb

@@ -0,0 +1,63 @@
+#
+# Copyright (c) 2014 SoftLayer Technologies, Inc. All rights reserved.
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#
+
+require 'rubygems'
+require 'softlayer_api'
+require 'pp'
+
+# This is the id of the server you want to protect with a firewall.
+# The server can be Bare Metal or Virtual.  It should have a public
+# network interface, and it should not already have a firewall on it.
+server_id = 257696 # 12345
+
+# In this example, we assume this is a Bare Metal Server
+is_virtual_server = false
+
+# Work with the SoftLayer API begins with a client.  By setting
+# the "default" client we avoid having to specify the client repeatedly
+# in calls that follow.
+SoftLayer::Client.default_client = SoftLayer::Client.new(
+  # :username => "joecustomer"              # enter your username here
+  # :api_key => "feeddeadbeefbadf00d..."   # enter your api key here
+)
+
+# in this case we go straight to the appropriate class to find the server
+# an alternative might be to create the account for this client and
+# search the list of servers for the one with the appropriate ID.
+if is_virtual_server
+  server = SoftLayer::VirtualServer.server_with_id(server_id)
+else
+  server = SoftLayer::BareMetalServer.server_with_id(server_id)
+end
+
+# Create an instance of SoftLayer::ServerFirewallOrder
+order = SoftLayer::ServerFirewallOrder.new(server)
+
+begin
+  # this example calls order.verify which will build the order, submit it 
+  # to the network API, and will throw an exception if the order is
+  # invalid.
+  order.verify()
+  puts "Firewall order is good for #{server.fullyQualifiedDomainName}"
+rescue => exception
+  puts "Firewall order failed for #{server.fullyQualifiedDomainName} because #{exception}"
+end

lib/softlayer/APIParameterFilter.rb

@@ -43,6 +43,13 @@ def initialize(target, starting_parameters = nil)
     @parameters = starting_parameters || {}
   end
 
+  ##
+  # API Parameter filters will call through to a particular service
+  # but that service is defined by their target
+  def service_name
+    return @target.service_name
+  end
+
   ##
   # Adds an API filter that narrows the scope of a call to an object with
   # a particular ID. For example, if you want to get the ticket

lib/softlayer/Account.rb

@@ -126,6 +126,24 @@ def service
       softlayer_client[:Account].object_with_id(self.id)
     end
 
+    ##
+    # Searches the account's list of VLANs for the ones with the given
+    # vlan number. This may return multiple results because a VLAN can
+    # span different routers and you will get a separate segment for
+    # each router.
+    #
+    # The IDs of the different segments can be helpful for ordering
+    # firewalls.
+    #
+    def find_VLAN_with_number(vlan_number)
+      filter = SoftLayer::ObjectFilter.new() { |filter|
+        filter.accept('networkVlans.vlanNumber').when_it is vlan_number
+      }
+
+      vlan_data = self.service.object_mask("mask[id,vlanNumber,primaryRouter,networkSpace]").object_filter(filter).getNetworkVlans
+      return vlan_data
+    end
+    
     ##
     # Using the login credentials in the client, retrieve
     # the account associated with those credentials.

lib/softlayer/BareMetalServer.rb

@@ -55,13 +55,22 @@ def cancel!(reason = :unneeded, comment = '')
     end
 
     ##
-    # Returns the SoftLayer Service used to work with this Server
+    # Returns the typical Service used to work with this Server
     # For Bare Metal Servers that is +SoftLayer_Hardware+ though in some special cases
-    # you may have to use +SoftLayer_Hardware_Server+ as a type or service.
+    # you may have to use +SoftLayer_Hardware_Server+ as a type or service.  That
+    # service object is available thorugh the hardware_server_service method
     def service
       return softlayer_client[:Hardware].object_with_id(self.id)
     end
 
+    ##
+    # Returns the SoftLayer_Hardware_Server service for this bare metal server
+    # This service is used less often than SoftLayer_Hardware, but may be required
+    # for some operations
+    def hardware_server_service
+      self.softlayer_client[:Hardware_Server].object_with_id(self.id)
+    end
+
     ##
     # Returns the default object mask used when fetching servers from the API when an
     # explicit object mask is not provided.
@@ -106,6 +115,57 @@ def self.cancellation_reasons
       }
     end
 
+    ##
+    # Returns the max port speed of the public network interfaces of the server taking into account
+    # bound interface pairs (redundant network cards).
+    def firewall_port_speed
+      network_components = self.service.object_mask("mask[id,maxSpeed,networkComponentGroup.networkComponents]").getFrontendNetworkComponents()
+
+      # Split the interfaces into grouped and ungrouped interfaces. The max speed of a group will be the sum
+      # of the individual speeds in that group.  The max speed of ungrouped interfaces is simply the max speed
+      # of that interface.
+      grouped_interfaces, ungrouped_interfaces = network_components.partition{ |interface| interface.has_key?("networkComponentGroup") }
+
+      if !grouped_interfaces.empty?
+        group_speeds = grouped_interfaces.collect do |interface|
+          interface['networkComponentGroup']['networkComponents'].inject(0) {|total_speed, component| total_speed += component['maxSpeed']}
+        end
+
+        max_group_speed = group_speeds.max
+      else
+        max_group_speed = 0
+      end
+
+      if !ungrouped_interfaces.empty?
+        max_ungrouped_speed = ungrouped_interfaces.collect { |interface| interface['maxSpeed']}.max
+      else
+        max_ungrouped_speed = 0
+      end
+
+      return [max_group_speed, max_ungrouped_speed].max
+    end
+
+    ##
+    # Change the current port speed of the server
+    #
+    # +new_speed+ is expressed Mbps and should be 0, 10, 100, or 1000.
+    # Ports have a maximum speed that will limit the actual speed set
+    # on the port.
+    #
+    # Set +public+ to +false+ in order to change the speed of the
+    # primary private network interface.
+    #
+    def change_port_speed(new_speed, public = true)
+      if public
+        self.hardware_server_service.setPublicNetworkInterfaceSpeed(new_speed)
+      else
+        self.hardware_server_service.setPrivateNetworkInterfaceSpeed(new_speed)
+      end
+
+      self.refresh_details()
+      self
+    end
+
     ##
     # Retrive the bare metal server with the given server ID from the
     # SoftLayer API

lib/softlayer/Server.rb

@@ -170,6 +170,16 @@ def set_domain!(new_domain)
       self.refresh_details()
     end
 
+    ##
+    # Returns the max port speed of the public network interfaces of the server taking into account
+    # bound interface pairs (redundant network cards).
+    def firewall_port_speed
+      network_components = self.service.object_mask("mask[id,maxSpeed]").getFrontendNetworkComponents()
+      max_speeds = network_components.collect { |component| component['maxSpeed'] }
+
+      max_speeds.empty? ? 0 : max_speeds.max
+    end
+
     ##
     # Change the current port speed of the server
     #
@@ -180,15 +190,9 @@ def set_domain!(new_domain)
     # Set +public+ to +false+ in order to change the speed of the
     # primary private network interface.
     #
+    # This is an abstract method implemented by subclasses
     def change_port_speed(new_speed, public = true)
-      if public
-        self.service.setPublicNetworkInterfaceSpeed(new_speed)
-      else
-        self.service.setPrivateNetworkInterfaceSpeed(new_speed)
-      end
-
-      self.refresh_details()
-      self
+      raise "The abstract change_port_speed method of SoftLayer::Server was called. Subclasses should implement the method for their particular service"
     end
 
     ##

lib/softlayer/ServerFirewallOrder.rb

@@ -0,0 +1,84 @@
+#--
+# Copyright (c) 2014 SoftLayer Technologies, Inc. All rights reserved.
+#
+# For licensing information see the LICENSE.md file in the project root.
+#++
+
+module SoftLayer
+  #
+  # This class allows you to order a Firewall for a server
+  #
+  class ServerFirewallOrder
+    # The server that you are ordering the firewall for.
+    attr_reader :server
+
+    ##
+    # Create a new order for the given server
+    def initialize (server)
+      @server = server
+
+      raise ArgumentError.new("Server does not have an active Public interface") if server.firewall_port_speed == 0
+    end
+
+    ##
+    # Calls the SoftLayer API to verify that the template provided by this order is valid
+    # This routine will return the order template generated by the API or will throw an exception
+    #
+    # This routine will not actually create a Bare Metal Instance and will not affect billing.
+    #
+    # If you provide a block, it will receive the order template as a parameter and
+    # the block may make changes to the template before it is submitted.
+    def verify()
+      order_template = firewall_order_template
+      order_template = yield order_template if block_given?
+
+      server.softlayer_client[:Product_Order].verifyOrder(order_template)
+    end
+
+    ##
+    # Calls the SoftLayer API to place an order for a new server based on the template in this
+    # order. If this succeeds then you will be billed for the new server.
+    #
+    # If you provide a block, it will receive the order template as a parameter and
+    # the block may make changes to the template before it is submitted.
+    def place_order!()
+      order_template = firewall_order_template
+      order_template = yield order_template if block_given?
+
+      server.softlayer_client[:Product_Order].placeOrder(order_template)
+    end
+
+    protected
+
+    ##
+    # Returns a hash of the creation options formatted to be sent *to*
+    # the SoftLayer API for either verification or completion
+    def firewall_order_template
+      client = server.softlayer_client
+      additional_products_package = SoftLayer::ProductPackage.additional_products_package(client)
+
+      template = {
+          'complexType' => 'SoftLayer_Container_Product_Order_Network_Protection_Firewall',
+          'quantity' => 1,
+          'packageId' => additional_products_package.id
+        }
+
+      if @server.service.service_name == "SoftLayer_Virtual_Guest"
+        template['virtualGuests'] = [{'id' => @server.id}]
+      else
+        template['hardware'] = [{'id' => @server.id}]
+      end
+
+      expected_description = "#{@server.firewall_port_speed}Mbps Hardware Firewall"
+      firewall_items = additional_products_package.items_with_description(expected_description)
+
+      raise "Could not find a price item matching the description '#{expected_description}'" if firewall_items.empty?
+
+      firewall_item = firewall_items[0]
+
+      template['prices'] = [{ 'id' => firewall_item.price_id }] if firewall_item.respond_to?(:price_id)
+
+      template
+    end
+  end # class ServerFirewallOrder
+end # module SoftLayer