ws_discovery 0.0.1

data/Gemfile

@@ -0,0 +1,2 @@
+source :rubygems
+gemspec

data/History.rdoc

@@ -0,0 +1,3 @@
+=== 0.0.1 / 2012-11-12
+
+* Initial release.

data/README.rdoc

@@ -0,0 +1,77 @@
+= ws_discovery
+
+* {Homepage}[https://github.com/pelco-automation/ws-discovery]
+* {WS-Discovery 1.0 Specification}[http://specs.xmlsoap.org/ws/2005/04/discovery/ws-discovery.pdf]
+* {SOAP-over-UDP Specification}[http://specs.xmlsoap.org/ws/2004/09/soap-over-udp/soap-over-udp.pdf]
+
+== Description
+
+This gem aims to provide the ability to search for WS-Discovery compatible target
+services.
+
+This uses EventMachine[http://github.com/eventmachine/eventmachine], so if
+you're not already, getting familiar with its concepts will be helpful here.
+
+== Features
+
+* Search for WS-Discovery compatible target services.
+
+== Examples
+
+=== WS-Discovery Searches
+
+A WS-Discovery search simply sends the probe out to the multicast group and
+listens for responses for a given (or default of 5 seconds) amount of time.  The
+return from this depends on if you're running it within an EventMachine reactor
+or not.  If not, it returns an Array of responses as WSDiscovery::Responses.
+Take a look at the WSDiscovery#search docs for more on the options here.
+
+  require 'ws_discovery'
+
+  # Search for all devices (do a probe with Types left unspecified)
+  all_devices = WSDiscovery.search                         # this is default
+
+  # Search for devices of a specific Type
+  network_video_transmitters = WSDiscovery.search(
+    env_namespaces: { "xmlns:dn" => "http://www.onvif.org/ver10/network/wsdl" },
+    types: "dn:NetworkVideoTransmitter")
+
+  # These searches will return an Array of WSDiscovery::Responses.  See the
+  # WSDiscovery::Response documentation for more information.
+
+If you do the search inside of an EventMachine reactor, as the
+WSDiscovery::Searcher receives and parses responses, it adds them to the accessor
+#discovery_responses, which is an EventMachine::Channel.  This lets you subscribe
+to the responses and do what you want with them.
+
+== Requirements
+
+* Ruby
+  * 1.9.3
+* Gems
+  * builder
+  * eventmachine
+  * log_switch
+  * nokogiri
+  * nori
+  * uuid
+* Gems (development)
+  * bundler
+  * rake
+  * rspec
+  * simplecov
+  * simplecov-rcov
+  * yard
+
+== Install
+
+  $ gem install ws_discovery
+
+== THANKS
+
+The initial core of this gem came from https://github.com/turboladen/upnp due to
+the similarities in how SSDP and WS-Discovery searches are performed.
+
+The WSDiscovery::Response class reuses parts of https://github.com/savonrb/savon.
+It made sense to me that WSDiscovery::Responses would behave similarly to
+Savon::SOAP::Responses.

data/Rakefile

@@ -0,0 +1,16 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'yard'
+
+YARD::Rake::YardocTask.new
+RSpec::Core::RakeTask.new
+
+RSpec::Core::RakeTask.new(:rcov) do |spec|
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task default: :install
+
+# Alias for rubygems-test
+task test: :spec

data/lib/ws_discovery/core_ext/socket_patch.rb

@@ -0,0 +1,16 @@
+require 'socket'
+
+# Workaround for missing constants on Windows
+module Socket::Constants
+  IP_ADD_MEMBERSHIP = 12 unless defined? IP_ADD_MEMBERSHIP
+  IP_MULTICAST_LOOP = 11 unless defined? IP_MULTICAST_LOOP
+  IP_MULTICAST_TTL  = 10 unless defined? IP_MULTICAST_TTL
+  IP_TTL            =  4 unless defined? IP_TTL
+end
+
+class Socket
+  IP_ADD_MEMBERSHIP = 12 unless defined? IP_ADD_MEMBERSHIP
+  IP_MULTICAST_LOOP = 11 unless defined? IP_MULTICAST_LOOP
+  IP_MULTICAST_TTL  = 10 unless defined? IP_MULTICAST_TTL
+  IP_TTL            =  4 unless defined? IP_TTL
+end

data/lib/ws_discovery/error.rb

@@ -0,0 +1,4 @@
+module WSDiscovery
+  class Error < StandardError
+  end
+end

data/lib/ws_discovery/multicast_connection.rb

@@ -0,0 +1,77 @@
+require_relative 'core_ext/socket_patch'
+require_relative 'network_constants'
+require_relative 'error'
+require 'ipaddr'
+require 'socket'
+require 'eventmachine'
+
+module WSDiscovery
+  class MulticastConnection < EventMachine::Connection
+    include WSDiscovery::NetworkConstants
+
+    # @param [Fixnum] ttl The TTL value to use when opening the UDP socket
+    #   required for WSDiscovery actions.
+    def initialize ttl=TTL
+      @ttl = ttl
+      @discovery_responses = EM::Channel.new
+
+      setup_multicast_socket
+    end
+
+    private
+
+    # Gets the IP and port from the peer that just sent data.
+    #
+    # @return [Array<String,Fixnum>] The IP and port.
+    def peer_info
+      peer_bytes = get_peername[2, 6].unpack("nC4")
+      port = peer_bytes.first.to_i
+      ip = peer_bytes[1, 4].join(".")
+
+      [ip, port]
+    end
+
+    # Sets Socket options to allow for multicasting.  If ENV["RUBY_TESTING_ENV"]
+    # is equal to "testing", then it doesn't turn off multicast looping.
+    def setup_multicast_socket
+      set_membership(IPAddr.new(MULTICAST_IP).hton + IPAddr.new('0.0.0.0').hton)
+      set_multicast_ttl(@ttl)
+      set_ttl(@ttl)
+
+      unless ENV["RUBY_TESTING_ENV"] == "testing"
+        switch_multicast_loop :off
+      end
+    end
+
+    # @param [String] membership The network byte ordered String that represents
+    #   the IP(s) that should join the membership group.
+    def set_membership(membership)
+      set_sock_opt(Socket::IPPROTO_IP, Socket::IP_ADD_MEMBERSHIP, membership)
+    end
+
+    # @param [Fixnum] ttl TTL to set IP_MULTICAST_TTL to.
+    def set_multicast_ttl(ttl)
+      set_sock_opt(Socket::IPPROTO_IP, Socket::IP_MULTICAST_TTL, [ttl].pack('i'))
+    end
+
+    # @param [Fixnum] ttl TTL to set IP_TTL to.
+    def set_ttl(ttl)
+      set_sock_opt(Socket::IPPROTO_IP, Socket::IP_TTL, [ttl].pack('i'))
+    end
+
+    # @param [Symbol] on_off Turn on/off multicast looping.  Supply :on or :off.
+    # @raise [WSDiscovery::Error] If invalid option is given.
+    def switch_multicast_loop(on_off)
+      hex_value = case on_off
+      when :on, "\001"
+        "\001"
+      when :off, "\000"
+        "\000"
+      else
+        raise WSDiscovery::Error, "Can't switch IP_MULTICAST_LOOP to '#{on_off}'"
+      end
+
+      set_sock_opt(Socket::IPPROTO_IP, Socket::IP_MULTICAST_LOOP, hex_value)
+    end
+  end
+end

data/lib/ws_discovery/network_constants.rb

@@ -0,0 +1,13 @@
+module WSDiscovery
+  module NetworkConstants
+
+    # Default multicast IP address
+    MULTICAST_IP = '239.255.255.250'
+
+    # Default multicast port
+    MULTICAST_PORT = 3702
+
+    # Default TTL
+    TTL = 1
+  end
+end

data/lib/ws_discovery/response.rb

@@ -0,0 +1,95 @@
+require 'nokogiri'
+require 'nori'
+require_relative 'error'
+
+Nori.configure do |config|
+  config.strip_namespaces = true
+  config.convert_tags_to { |tag| tag.snakecase.to_sym }
+end
+
+module WSDiscovery
+
+  # Represents the probe response.
+  class Response
+
+    attr_accessor :response
+
+    # @param [String] response Text of the response to a WSDiscovery probe.
+    def initialize(response)
+      @response = response
+    end
+
+    # Shortcut accessor for the SOAP response body Hash.
+    #
+    # @param [Symbol] key The key to access in the body Hash.
+    # @return [Hash,String] The accessed value.
+    def [](key)
+      body[key]
+    end
+
+    # Returns the SOAP response header as a Hash.
+    #
+    # @return [Hash] SOAP response header.
+    # @raise [WSDiscovery::Error] If unable to parse response.
+    def header
+      unless hash.has_key? :envelope
+        raise WSDiscovery::Error, "Unable to parse response body '#{to_xml}'"
+      end
+
+      hash[:envelope][:header]
+    end
+
+    # Returns the SOAP response body as a Hash.
+    #
+    # @return [Hash] SOAP response body.
+    # @raise [WSDiscovery::Error] If unable to parse response.
+    def body
+      unless hash.has_key? :envelope
+        raise WSDiscovery::Error, "Unable to parse response body '#{to_xml}'"
+      end
+
+      hash[:envelope][:body]
+    end
+
+    alias to_hash body
+
+    # Returns the complete SOAP response XML without normalization.
+    #
+    # @return [Hash] Complete SOAP response Hash.
+    def hash
+      @hash ||= Nori.parse(to_xml)
+    end
+
+    # Returns the SOAP response XML.
+    #
+    # @return [String] Raw SOAP response XML.
+    def to_xml
+      response
+    end
+
+    # Returns a Nokogiri::XML::Document for the SOAP response XML.
+    #
+    # @return [Nokogiri::XML::Document] Document for the SOAP response.
+    def doc
+      @doc ||= Nokogiri::XML(to_xml)
+    end
+
+    # Returns an Array of Nokogiri::XML::Node objects retrieved with the given +path+.
+    # Automatically adds all of the document's namespaces unless a +namespaces+ hash is provided.
+    #
+    # @param [String] path XPath to search.
+    # @param [Hash<String>] namespaces Namespaces to append.
+    def xpath(path, namespaces = nil)
+      doc.xpath(path, namespaces || xml_namespaces)
+    end
+
+    private
+
+    # XML Namespaces from the Document.
+    #
+    # @return [Hash] Namespaces from the Document.
+    def xml_namespaces
+      @xml_namespaces ||= doc.collect_namespaces
+    end
+  end
+end

data/lib/ws_discovery/searcher.rb

@@ -0,0 +1,91 @@
+require_relative 'multicast_connection'
+require_relative 'response'
+require 'builder'
+require 'log_switch'
+require 'uuid'
+
+class WSDiscovery::Searcher < WSDiscovery::MulticastConnection
+  extend LogSwitch
+  self.logger.datetime_format = "%Y-%m-%d %H:%M:%S "
+
+  # @return [EventMachine::Channel] Provides subscribers with responses from
+  #   their search request.
+  attr_reader :discovery_responses
+
+  # @param [Hash] options The options for the probe.
+  # @option options [Hash<String>] :env_namespaces Additional envelope namespaces.
+  # @option options [Hash<String>] :type_attributes Type attributes.
+  # @option options [String] :types Types.
+  # @option options [Hash<String>] :scope_attributes Scope attributes.
+  # @option options [String] :scopes Scopes.
+  # @option options [Fixnum] :ttl TTL for the probe.
+  def initialize(options={})
+    options[:ttl] ||= TTL
+
+    @search = probe(options)
+
+    super options[:ttl]
+  end
+
+  # This is the callback called by EventMachine when it receives data on the
+  # socket that's been opened for this connection.  In this case, the method
+  # parses the probe matches into WSDiscovery::Responses and adds them to the
+  # appropriate EventMachine::Channel (provided as accessor methods).  This
+  # effectively means that in each Channel, you get a WSDiscovery::Response
+  # for each response that comes in on the socket.
+  #
+  # @param [String] response The data received on this connection's socket.
+  def receive_data(response)
+    ip, port = peer_info
+    WSDiscovery::Searcher.log "<#{self.class}> Response from #{ip}:#{port}:\n#{response}\n"
+    parsed_response = parse(response)
+    @discovery_responses << parsed_response
+  end
+
+  # Converts the headers to a set of key-value pairs.
+  #
+  # @param [String] data The data to convert.
+  # @return [WSDiscovery::Response] The converted data.
+  def parse(data)
+    WSDiscovery::Response.new(data)
+  end
+
+  # Sends the probe that was built during init.  Logs what was sent if the
+  # send was successful.
+  def post_init
+    if send_datagram(@search, MULTICAST_IP, MULTICAST_PORT) > 0
+      WSDiscovery::Searcher.log("Sent datagram search:\n#{@search}")
+    end
+  end
+
+  # Probe for target services supporting WS-Discovery.
+  #
+  # @param [Hash] options The options for the probe.
+  # @option options [Hash<String>] :env_namespaces Additional envelope namespaces.
+  # @option options [Hash<String>] :type_attributes Type attributes.
+  # @option options [String] :types Types.
+  # @option options [Hash<String>] :scope_attributes Scope attributes.
+  # @option options [String] :scopes Scopes.
+  # @return [String] Probe SOAP message.
+  def probe(options={})
+    namespaces = {
+      'xmlns:a' => 'http://schemas.xmlsoap.org/ws/2004/08/addressing',
+      'xmlns:d' => 'http://schemas.xmlsoap.org/ws/2005/04/discovery',
+      'xmlns:s' => 'http://www.w3.org/2003/05/soap-envelope'
+    }
+    namespaces.merge options[:env_namespaces] if options[:env_namespaces]
+
+    Builder::XmlMarkup.new.s(:Envelope, namespaces) do |xml|
+      xml.s(:Header) do |xml|
+        xml.a(:Action, 'http://schemas.xmlsoap.org/ws/2005/04/discovery/Probe')
+        xml.a(:MessageID, "uuid:#{UUID.generate}")
+        xml.a(:To, 'urn:schemas-xmlsoap-org:ws:2005:04:discovery')
+      end
+
+      xml.s(:Body) do |xml|
+        xml.d(:Types, options[:type_attributes], options[:types])
+        xml.d(:Scopes, options[:scope_attributes], options[:scopes])
+      end
+    end
+  end
+end

data/lib/ws_discovery/version.rb

@@ -0,0 +1,3 @@
+module WSDiscovery
+  VERSION = '0.0.1'
+end

data/lib/ws_discovery.rb

@@ -0,0 +1,61 @@
+require_relative 'ws_discovery/core_ext/socket_patch'
+require 'eventmachine'
+
+require_relative 'ws_discovery/error'
+require_relative 'ws_discovery/network_constants'
+require_relative 'ws_discovery/searcher'
+
+module WSDiscovery
+  include NetworkConstants
+
+  DEFAULT_WAIT_TIME = 5
+
+  # Opens a UDP socket on 0.0.0.0, on an ephemeral port, has WSDiscovery::Searcher
+  # build and send the search request, then receives the responses.  The search
+  # will stop after +response_wait_time+.
+  #
+  # @param [Hash] options The options for the probe.
+  # @option options [Hash<String>] :env_namespaces Additional envelope namespaces.
+  # @option options [Hash<String>] :type_attributes Type attributes.
+  # @option options [String] :types Types.
+  # @option options [Hash<String>] :scope_attributes Scope attributes.
+  # @option options [String] :scopes Scopes.
+  # @return [Array<WSDiscovery::Response>,WSDiscovery::Searcher] Returns an
+  #   Array of probe responses. If the reactor is already running this will return
+  #   a WSDiscovery::Searcher which will make its accessors available so you can
+  #   get responses in real time.
+  def self.search(options={})
+    response_wait_time = options[:response_wait_time] || DEFAULT_WAIT_TIME
+    responses = []
+
+    multicast_searcher = proc do
+      EM.open_datagram_socket('0.0.0.0', 0, WSDiscovery::Searcher, options)
+    end
+
+    if EM.reactor_running?
+      return multicast_searcher.call
+    else
+      EM.run do
+        ms = multicast_searcher.call
+
+        ms.discovery_responses.subscribe do |notification|
+          responses << notification
+        end
+
+        EM.add_timer(response_wait_time) { EM.stop }
+        trap_signals
+      end
+    end
+
+    responses.flatten
+  end
+
+  private
+
+  # Traps INT, TERM, and HUP signals and stops the reactor.
+  def self.trap_signals
+    trap('INT') { EM.stop }
+    trap('TERM') { EM.stop }
+    trap('HUP') { EM.stop } if RUBY_PLATFORM !~ /mswin|mingw/
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,26 @@
+require 'simplecov'
+require 'simplecov-rcov'
+
+class SimpleCov::Formatter::MergedFormatter
+  def format(result)
+    SimpleCov::Formatter::HTMLFormatter.new.format(result)
+    SimpleCov::Formatter::RcovFormatter.new.format(result)
+  end
+end
+
+SimpleCov.formatter = SimpleCov::Formatter::MergedFormatter
+
+SimpleCov.start do
+  add_filter "/spec"
+  add_filter "/lib/deps"
+end
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'rspec'
+
+# Requires supporting files with custom matchers and macros, etc,
+# in ./support/ and its subdirectories.
+Dir["#{File.dirname(__FILE__)}/support/**/*.rb"].each { |file| require file }
+
+ENV["RUBY_TESTING_ENV"] = "testing"