omf_rc 6.0.2.pre.2 → 6.0.2

data/lib/omf_rc/util/ip.rb

@@ -1,19 +1,48 @@
+# Copyright (c) 2012 National ICT Australia Limited (NICTA).
+# This software may be used and distributed solely under the terms of the MIT license (License).
+# You should find a copy of the License in LICENSE.TXT or at http://opensource.org/licenses/MIT.
+# By downloading or using this software you accept the terms and the liability disclaimer in the License.
+
 require 'cocaine'
 
 module OmfRc::Util::Ip
   include OmfRc::ResourceProxyDSL
   include Cocaine
 
+  # @!macro extend_dsl
+
+  # @!macro group_request
+  # Retrieve IP address
+  #
+  # @return [String] IP address
+  # @!macro request
+  # @!method request_ip_addr
   request :ip_addr do |resource|
     addr = CommandLine.new("ip", "addr show dev :device", :device => resource.property.if_name).run
     addr && addr.chomp.match(/inet ([[0-9]\:\/\.]+)/) && $1
   end
 
+  # Retrieve MAC address
+  #
+  # @return [String] MAC address
+  # @!macro request
+  # @!method request_mac_addr
   request :mac_addr do |resource|
     addr = CommandLine.new("ip", "addr show dev :device", :device => resource.property.if_name).run
     addr && addr.chomp.match(/link\/ether ([\d[a-f][A-F]\:]+)/) && $1
   end
+  # @!endgroup
 
+  # @!macro group_configure
+  # Configure IP address
+  #
+  # @param value value of IP address, it should have netmask. (e.g. 0.0.0.0/24)
+  #
+  # @raise [ArgumentError] if provided no IP address or incorrect format
+  #
+  # @return [String] IP address
+  # @!macro configure
+  # @!method configure_ip_addr
   configure :ip_addr do |resource, value|
     if value.nil? || value.split('/')[1].nil?
       raise ArgumentError, "You need to provide an IP address with netmask. E.g. 0.0.0.0/24. Got #{value}."
@@ -27,13 +56,23 @@ module OmfRc::Util::Ip
     resource.interface_up
     resource.request_ip_addr
   end
+  # @!endgroup
 
+  # @!macro group_work
+  # Bring up network interface
+  # @!macro work
+  # @!method interface_up
   work :interface_up do |resource|
     CommandLine.new("ip", "link set :dev up", :dev => resource.property.if_name).run
   end
 
+  # Remove IP addresses associated with the interface
+  #
+  # @!macro work
+  # @!method flush_ip_addrs
   work :flush_ip_addrs do |resource|
     CommandLine.new("ip",  "addr flush dev :device",
                     :device => resource.property.if_name).run
   end
+  # @!endgroup
 end

data/lib/omf_rc/util/iw.rb

@@ -1,11 +1,23 @@
+# Copyright (c) 2012 National ICT Australia Limited (NICTA).
+# This software may be used and distributed solely under the terms of the MIT license (License).
+# You should find a copy of the License in LICENSE.TXT or at http://opensource.org/licenses/MIT.
+# By downloading or using this software you accept the terms and the liability disclaimer in the License.
+
 require 'hashie'
 require 'cocaine'
 
+# Utility for executing command 'iw'
 module OmfRc::Util::Iw
   include OmfRc::ResourceProxyDSL
+
   include Cocaine
   include Hashie
 
+  # @!macro extend_dsl
+  #
+  # @!parse include OmfRc::Util::Ip
+  # @!parse include OmfRc::Util::Wpa
+  # @!parse include OmfRc::Util::Hostapd
   utility :ip
   utility :wpa
   utility :hostapd
@@ -26,8 +38,18 @@ module OmfRc::Util::Iw
     logger.warn "Command iw not found"
   end
 
+  # @!macro group_request
+  #
   # Parse iw link command output and return as a mash
   #
+  # @example return value
+  #
+  #   { ssid: 'ap', freq: '2412', signal: '-67 dBm' }
+  #
+  # @return [Mash]
+  #
+  # @!method request_link
+  # @!macro request
   request :link do |device|
     known_properties = Mash.new
 
@@ -44,6 +66,13 @@ module OmfRc::Util::Iw
 
   # Parse iw info command output and return as a mash
   #
+  # @example return value
+  #
+  #   { ifindex: '3', type: 'managed', wiphy: '0' }
+  #
+  # @return [Mash]
+  # @!method request_info
+  # @!macro request
   request :info do |device|
     known_properties = Mash.new
 
@@ -58,14 +87,93 @@ module OmfRc::Util::Iw
     known_properties
   end
 
+  # @!endgroup
+
+  # @!macro group_configure
+  #
+  # Configure the interface with mode: managed, master, adhoc or monitor
+  #
+  # @example Sample opts for mode property
+  #   # Master
+  #   { mode: :master, hw_mode: 'a', channel: 1, essid: 'bob' }
+  #
+  #   # Managed
+  #   { mode: :managed, essid: 'bob' }
+  #
+  #   # Ad-hoc
+  #   { mode: :adhoc, essid: 'bob', frequency: 2412 }
+  #
+  #   # Monitor
+  #   { mode: :monitor }
+  #
+  # @param [Hash] opts the hash to set up mode of wireless interface
+  #
+  # @option opts [Symbol] :mode wireless connection mode (:master, :managed, :adhoc)
+  # @option opts [Symbol] :hw_mode wireless connection hardware mode ('a', 'b', 'g', 'n')
+  # @option opts [Symbol] :essid
+  # @option opts [Symbol] :channel
+  # @option opts [Symbol] :frequency
+  #
+  # @raise [ArgumentError] if wifi device specified cannot be found on the system
+  #
+  # @return [String] ip address of the device if configured properly
+  #
+  # @!method configure_mode(opts)
+  # @!macro configure
+  configure :mode do |device, opts|
+    # capture opts hash and store internally
+    device.property.update(opts)
+
+    if device.property.phy && device.property.phy =~ /^%(\d+)%$/
+      wlan_phy_device = device.request_wlan_devices[$1.to_i]
+      if wlan_phy_device
+        device.property.phy = wlan_phy_device[:name]
+      else
+        raise ArgumentError, "Could not find your wifi device no #{$1.to_i}"
+      end
+    end
+
+    device.validate_iw_properties
+
+    device.delete_interface rescue logger.warn "Interface #{device.property.if_name} not found"
+
+    # TODO should just remove all interfaces from physical device, at least make it optional
+
+    case device.property.mode.to_sym
+    when :master
+      device.add_interface(:managed)
+      device.hostapd
+    when :managed
+      device.add_interface(:managed)
+      device.wpasup
+    when :adhoc
+      device.add_interface(:adhoc)
+      device.interface_up
+      device.join_ibss
+    when :monitor
+      device.add_interface(:monitor)
+      device.interface_up
+    end
+
+    device.configure_ip_addr(device.property.ip_addr) if device.property.ip_addr
+  end
+
+  # @!endgroup
+  #
+  # @!macro group_work
+  #
   # Delete current interface, clean up
   #
+  # @return [String] iw command output
+  # @!macro work
   work :delete_interface do |device|
     CommandLine.new("iw", "dev :dev del", :dev => device.property.if_name).run
   end
 
   # Add interface to device
   #
+  # @return [String] iw command output
+  # @!macro work
   work :add_interface do |device, type|
     CommandLine.new("iw", "phy :phy interface add :dev type :type",
                     :phy => device.property.phy,
@@ -75,6 +183,8 @@ module OmfRc::Util::Iw
 
   # Set up or join a ibss network
   #
+  # @return [String] iw command output
+  # @!macro work
   work :join_ibss do |device|
     CommandLine.new("iw", "dev :device ibss join :essid :frequency",
                       :device => device.property.if_name.to_s,
@@ -84,6 +194,10 @@ module OmfRc::Util::Iw
 
   # Validate internal properties based on interface mode
   #
+  # @raise [ArgumentError] if validation failed
+  #
+  # @return [nil]
+  # @!macro work
   work :validate_iw_properties do |device|
     raise ArgumentError, "Missing phyical device name" if device.property.phy.nil?
 
@@ -110,43 +224,5 @@ module OmfRc::Util::Iw
     end
   end
 
-  # Configure the interface with mode managed, master, adhoc or monitor
-  #
-  configure :mode do |device, value|
-    # capture value hash and store internally
-    device.property.update(value)
-
-    if device.property.phy && device.property.phy =~ /^%(\d+)%$/
-      wlan_phy_device = device.request_wlan_devices[$1.to_i]
-      if wlan_phy_device
-        device.property.phy = wlan_phy_device[:name]
-      else
-        raise ArgumentError, "Could not find your wifi device no #{$1.to_i}"
-      end
-    end
-
-    device.validate_iw_properties
-
-    device.delete_interface rescue logger.warn "Interface #{device.property.if_name} not found"
-
-    # TODO should just remove all interfaces from physical device, at least make it optional
-
-    case device.property.mode.to_sym
-    when :master
-      device.add_interface(:managed)
-      device.hostapd
-    when :managed
-      device.add_interface(:managed)
-      device.wpasup
-    when :adhoc
-      device.add_interface(:adhoc)
-      device.interface_up
-      device.join_ibss
-    when :monitor
-      device.add_interface(:monitor)
-      device.interface_up
-    end
-
-    device.configure_ip_addr(device.property.ip_addr) if device.property.ip_addr
-  end
+  # @!endgroup
 end

data/lib/omf_rc/util/libvirt.rb

@@ -1,3 +1,8 @@
+# Copyright (c) 2012 National ICT Australia Limited (NICTA).
+# This software may be used and distributed solely under the terms of the MIT license (License).
+# You should find a copy of the License in LICENSE.TXT or at http://opensource.org/licenses/MIT.
+# By downloading or using this software you accept the terms and the liability disclaimer in the License.
+
 #
 # Copyright (c) 2012 National ICT Australia (NICTA), Australia
 #

data/lib/omf_rc/util/mod.rb

@@ -1,17 +1,35 @@
+# Copyright (c) 2012 National ICT Australia Limited (NICTA).
+# This software may be used and distributed solely under the terms of the MIT license (License).
+# You should find a copy of the License in LICENSE.TXT or at http://opensource.org/licenses/MIT.
+# By downloading or using this software you accept the terms and the liability disclaimer in the License.
+
 require 'hashie'
 require 'cocaine'
 
+# Manage Linux modules
 module OmfRc::Util::Mod
   include OmfRc::ResourceProxyDSL
   include Cocaine
   include Hashie
+  # @!macro extend_dsl
 
+  # @!macro group_request
+  # @!macro request
+  # @!method request_modules
   request :modules do
     CommandLine.new('lsmod').run.split("\n").map do |v|
       v.match(/^(\w+).+$/) && $1
     end.compact.tap { |ary| ary.shift }
   end
-
+  # @!endgroup
+
+  # @!macro group_configure
+  #
+  # Load additional modules
+  #
+  # @param value name of the module to load
+  # @!macro configure
+  # @!method configure_load_module
   configure :load_module do |resource, value|
     raise ArgumentError, "Please provide at least module name" if value.name.nil?
 
@@ -38,4 +56,5 @@ module OmfRc::Util::Mod
 
     "#{value.name} loaded"
   end
+  # @!endgroup
 end

data/lib/omf_rc/util/openflow_tools.rb

@@ -1,3 +1,8 @@
+# Copyright (c) 2012 National ICT Australia Limited (NICTA).
+# This software may be used and distributed solely under the terms of the MIT license (License).
+# You should find a copy of the License in LICENSE.TXT or at http://opensource.org/licenses/MIT.
+# By downloading or using this software you accept the terms and the liability disclaimer in the License.
+
 require 'xmlrpc/client'
 
 module OmfRc::Util::OpenflowTools

data/lib/omf_rc/util/package.rb

@@ -1,3 +1,8 @@
+# Copyright (c) 2012 National ICT Australia Limited (NICTA).
+# This software may be used and distributed solely under the terms of the MIT license (License).
+# You should find a copy of the License in LICENSE.TXT or at http://opensource.org/licenses/MIT.
+# By downloading or using this software you accept the terms and the liability disclaimer in the License.
+
 # Package management utility, could be included in application resource proxy
 #
 module OmfRc::ResourceProxy::Package

data/lib/omf_rc/util/platform_tools.rb

@@ -1,3 +1,8 @@
+# Copyright (c) 2012 National ICT Australia Limited (NICTA).
+# This software may be used and distributed solely under the terms of the MIT license (License).
+# You should find a copy of the License in LICENSE.TXT or at http://opensource.org/licenses/MIT.
+# By downloading or using this software you accept the terms and the liability disclaimer in the License.
+
 #
 # Copyright (c) 2012 National ICT Australia (NICTA), Australia
 #

data/lib/omf_rc/util/sysfs.rb

@@ -1,6 +1,21 @@
+# Copyright (c) 2012 National ICT Australia Limited (NICTA).
+# This software may be used and distributed solely under the terms of the MIT license (License).
+# You should find a copy of the License in LICENSE.TXT or at http://opensource.org/licenses/MIT.
+# By downloading or using this software you accept the terms and the liability disclaimer in the License.
+
+# Getting available hardware by browsing sysfs directories
 module OmfRc::Util::Sysfs
   include OmfRc::ResourceProxyDSL
+  # @!macro extend_dsl
 
+  # @!macro group_request
+  # @!macro request
+  # @!method request_devices
+  #
+  # @example Sample return value
+  #   [
+  #     { name: 'eth0', driver: 'e1000e', category: 'net', proxy: 'net' },
+  #     { name: 'phy0', driver: 'iwlwifi', category: 'net', subcategory: 'wlan', proxy: 'wlan' } ]
   request :devices do |resource|
     devices = []
     # Support net devices for now
@@ -18,16 +33,16 @@ module OmfRc::Util::Sysfs
           File.exist?("#{v}/operstate") && File.open("#{v}/operstate") do |fo|
             device[:op_state] = (fo.read || '').chomp
           end
-          # Let's see if the interface is already up 
+          # Let's see if the interface is already up
           # NOTE: THIS MAY NOT BE ROBUST
           s = `ifconfig #{File.basename(v)}`
           unless s.empty?
             if m = s.match(/inet addr:\s*([0-9.]+)/)
               device[:ip4] = m[1]
-            end 
+            end
             if m = s.match(/inet6 addr:\s*([0-9a-f.:\/]+)/)
               device[:ip6] = m[1]
-            end 
+            end
           end
           devices << device
         end
@@ -47,6 +62,11 @@ module OmfRc::Util::Sysfs
     devices
   end
 
+  # @!macro request
+  # @!method request_wlan_devices
+  #
+  # @example Sample return value
+  #   [ { name: 'phy0', driver: 'iwlwifi', category: 'net', subcategory: 'wlan', proxy: 'wlan' } ]
   request :wlan_devices do |resource|
     resource.request_devices.find_all { |v| v[:proxy] == 'wlan' }
   end

data/lib/omf_rc/util/vmbuilder.rb

@@ -1,3 +1,8 @@
+# Copyright (c) 2012 National ICT Australia Limited (NICTA).
+# This software may be used and distributed solely under the terms of the MIT license (License).
+# You should find a copy of the License in LICENSE.TXT or at http://opensource.org/licenses/MIT.
+# By downloading or using this software you accept the terms and the liability disclaimer in the License.
+
 #
 # Copyright (c) 2012 National ICT Australia (NICTA), Australia
 #

data/lib/omf_rc/util/wpa.rb

@@ -1,18 +1,28 @@
+# Copyright (c) 2012 National ICT Australia Limited (NICTA).
+# This software may be used and distributed solely under the terms of the MIT license (License).
+# You should find a copy of the License in LICENSE.TXT or at http://opensource.org/licenses/MIT.
+# By downloading or using this software you accept the terms and the liability disclaimer in the License.
+
 require 'hashie'
 require 'cocaine'
 require 'tempfile'
 
+# Manage WPA instances
 module OmfRc::Util::Wpa
   include OmfRc::ResourceProxyDSL
   include Cocaine
+  # @!macro extend_dsl
 
+  # @!macro group_work
   # Initialise wpa related conf and pid location
   #
+  # @!method init_wpa_conf_pid
   work :init_wpa_conf_pid do |device|
     device.property.wpa_conf = Tempfile.new(["wpa.#{device.property.if_name}", ".conf"]).path
     device.property.wpa_pid = Tempfile.new(["wpa.#{device.property.if_name}", ".pid"]).path
   end
 
+  # @!method wpasup
   work :wpasup do |device|
     device.init_wpa_conf_pid
 
@@ -25,6 +35,7 @@ module OmfRc::Util::Wpa
                     :wpa_pid => device.property.wpa_pid).run
   end
 
+  # @!method stop_wpa
   work :stop_wpa do |device|
     begin
       File.open(device.property.wpa_pid,'r') do |f|
@@ -40,4 +51,5 @@ module OmfRc::Util::Wpa
       logger.warn e.message
     end
   end
+  # @!endgroup
 end

data/lib/omf_rc/version.rb

@@ -1,3 +1,8 @@
+# Copyright (c) 2012 National ICT Australia Limited (NICTA).
+# This software may be used and distributed solely under the terms of the MIT license (License).
+# You should find a copy of the License in LICENSE.TXT or at http://opensource.org/licenses/MIT.
+# By downloading or using this software you accept the terms and the liability disclaimer in the License.
+
 module OmfRc
-  VERSION = "6.0.2.pre.2"
+  VERSION = "6.0.2"
 end

data/lib/omf_rc.rb

@@ -1,3 +1,8 @@
+# Copyright (c) 2012 National ICT Australia Limited (NICTA).
+# This software may be used and distributed solely under the terms of the MIT license (License).
+# You should find a copy of the License in LICENSE.TXT or at http://opensource.org/licenses/MIT.
+# By downloading or using this software you accept the terms and the liability disclaimer in the License.
+
 require 'omf_common'
 require 'omf_rc/version'
 

data/omf_rc.gemspec

@@ -25,6 +25,7 @@ Gem::Specification.new do |s|
   s.add_development_dependency "em-minitest-spec", "~> 1.1.1"
   s.add_development_dependency "pry"
   s.add_development_dependency "simplecov"
-  s.add_runtime_dependency "omf_common", "~> 6.0.2.pre.2"
+  s.add_runtime_dependency "omf_common", "~> 6.0.2"
   s.add_runtime_dependency "cocaine", "~> 0.3.0"
+  s.add_runtime_dependency "mocha"
 end

data/test/omf_rc/deferred_process_spec.rb

@@ -1,3 +1,8 @@
+# Copyright (c) 2012 National ICT Australia Limited (NICTA).
+# This software may be used and distributed solely under the terms of the MIT license (License).
+# You should find a copy of the License in LICENSE.TXT or at http://opensource.org/licenses/MIT.
+# By downloading or using this software you accept the terms and the liability disclaimer in the License.
+
 require 'test_helper'
 require 'em/minitest/spec'
 require 'omf_rc/deferred_process'

data/test/omf_rc/message_process_error_spec.rb

@@ -1,3 +1,8 @@
+# Copyright (c) 2012 National ICT Australia Limited (NICTA).
+# This software may be used and distributed solely under the terms of the MIT license (License).
+# You should find a copy of the License in LICENSE.TXT or at http://opensource.org/licenses/MIT.
+# By downloading or using this software you accept the terms and the liability disclaimer in the License.
+
 require 'test_helper'
 
 describe OmfRc::MessageProcessError do

data/test/omf_rc/resource_factory_spec.rb

@@ -1,3 +1,8 @@
+# Copyright (c) 2012 National ICT Australia Limited (NICTA).
+# This software may be used and distributed solely under the terms of the MIT license (License).
+# You should find a copy of the License in LICENSE.TXT or at http://opensource.org/licenses/MIT.
+# By downloading or using this software you accept the terms and the liability disclaimer in the License.
+
 require 'test_helper'
 require 'omf_rc/resource_factory'
 
@@ -10,17 +15,14 @@ describe OmfRc::ResourceFactory do
 
     it "must have list of registered proxies and utilities" do
       OmfRc::ResourceFactory.load_default_resource_proxies
-      OmfRc::ResourceFactory.proxy_list.must_include :mock
+      OmfRc::ResourceFactory.proxy_list.must_include :node
     end
 
     it "must be able to create new resource proxy" do
       OmfCommon.stub :comm, @xmpp do
         OmfRc::ResourceFactory.load_default_resource_proxies
-        mock = OmfRc::ResourceFactory.new(:mock)
-        mock.must_be_kind_of OmfRc::ResourceProxy::AbstractResource
-        mock.must_respond_to :request_nothing
-        mock.request_nothing.must_equal mock.uid
-        mock.must_respond_to :configure_nothing
+        node = OmfRc::ResourceFactory.create(:node)
+        node.must_be_kind_of OmfRc::ResourceProxy::AbstractResource
       end
     end