net-ping 1.1.1 → 1.2.0

data/CHANGES

@@ -1,3 +1,26 @@
+== 1.2.0 - 5-Dec-2006
+* Internal reorganization - each class now lives in its own file.
+* Added the Ping::ICMP class.  Thanks go to Jos Backus for contributing a 
+  large part of the code.
+* The host argument is now optional in the constructor.  You can now specify
+  it in the ping method instead.  Note that it must be specified in one place
+  or the other.
+* Each PingXXX class is now Ping::XXX instead.  However, class name aliases
+  have been setup for backwards compatibility for now.
+* The constructor for each Ping types now yields self.
+* Added the pingecho alias for the ping method for each Ping type.
+* Added the Ping::HTTP#follow_redirect accessor.
+* The Ping::HTTP#ping method now honors the timeout value.
+* The Ping::HTTP class now follows redirects automatically, though this is
+  configurable with the follow_redirect accessor.
+* The Ping::TCP.ecr and Ping::TCP.ecr= methods are now true class method
+  aliases (they were just wrappers previously).
+* The Ping::UDP class now enforces a 64 character limit on data that can be
+  sent on a udp ping.
+* Updated the gemspec.  Specifically, MS Windows now has a dependency on
+  the win32-open3 package.
+* Added inline rdoc.
+
 == 1.1.1 - 15-Jun-2006
 * Fixed a bug in PingTCP (bad variable name).  Thanks go to Anoop Chandran
   for the spot.

data/MANIFEST

@@ -3,15 +3,23 @@ CHANGES
 README
 test.rb
 install.rb
+net-ping.gemspec
 
 examples/test_pingexternal.rb
 examples/test_pinghttp.rb
 examples/test_pingtcp.rb
 examples/test_pingudp.rb
 
-net/pingsimple.rb
+lib/net/ping.rb
+lib/net/ping/icmp.rb
+lib/net/ping/tcp.rb
+lib/net/ping/udp.rb
+lib/net/ping/http.rb
+lib/net/ping/external.rb
 
 test/tc_pingexternal.rb
+test/tc_pinghttp.rb
+test/tc_pingicmp.rb
 test/tc_pingtcp.rb
 test/tc_pingudp.rb
-test/tc_pinghttp.rb
+test/ts_ping.rb

data/README

@@ -3,7 +3,8 @@
 
 == Prerequisites
    * Ruby 1.8.0 or later
-   * The win32/open3 package is required for Win32 systems.
+   * The win32/open3 package is required for Win32 systems when using the
+     Net::Ping::External class.
 
 == Installation
 === Manual Installation
@@ -18,3 +19,17 @@
    pertaining to ECONNREFUSED with regards to TCP pings.
 
    Also note the documentation regarding down hosts.
+
+== How to require net-ping
+   You can do either this:
+
+   require 'net/ping'
+
+   In which case you will get Net::Ping and all of its subclasses.  Or,
+   you can load individual subclasses like this:
+
+   require 'net/ping/tcp'
+
+   The former has the advantage of being easier to remember and all inclusive,
+   not to mention backwards compatible.  The latter has the advantage of
+   reducing your memory footprint.

data/doc/ping.txt

@@ -1,16 +1,16 @@
-== Description
+= Description
    A simple Ruby interface to the 'ping' command.
 
-== Synopsis
+= Synopsis
    require "net/ping"
    include Net
 
-   PingTCP.econnrefused = true
+   Ping::TCP.econnrefused = true
 
-   pt = Net::PingTCP.new(host)
-   pu = Net::PingUDP.new(host)
-   pe = Net::PingExternal.new(host)
-   ph = Net::PingHTTP.new(uri)
+   pt = Net::Ping::TCP.new(host)
+   pu = Net::Ping::UDP.new(host)
+   pe = Net::Ping::External.new(host)
+   ph = Net::Ping::HTTP.new(uri)
 
    if pt.ping
       puts "TCP ping successful"
@@ -36,109 +36,125 @@
       puts "HTTP ping unsuccessful: " + ph.exception
    end
 
-== Ping Classes
-   * PingTCP
-   * PingUDP
-   * PingExternal
-   * PingHTTP
+= Ping Classes
+   * Ping::TCP
+   * Ping::UDP
+   * Ping::External
+   * Ping::HTTP
+   * Ping::ICMP
 
    All Ping classes are children of the Ping parent class (which should
    never be instantiated directly).
 
-=== PingTCP
-PingTCP.new(host, port=7, timeout=5)
-	Creates and returns a new PingTCP object.
+   The Ping::ICMP class requires root privileges on UNIX systems.
+
+== Net::Ping
+Net::Ping.new(host=nil, port=7, timeout=5)
+   Creates and returns a new Ping object.  If the host is not specified
+   in the constructor then it must be specified in the ping method.
+
+== Net::Ping::TCP
+Ping::TCP.econnrefused
+   Returns the setting for how ECONNREFUSED is handled.  By default, this is
+   set to false, i.e. an ECONNREFUSED error is considered a failed ping.
+
+Ping::TCP.econnrefused=(bool)
+   Sets the behavior for how ECONNREFUSED is handled.  By default, this is
+   set to false, i.e. an ECONNREFUSED error is considered a failed ping.
+
+Ping::TCP#ping(host=nil)
+   Attempts to open a connection using TCPSocket with a +host+ specified
+   either here or in the constructor.  A successful open means the ping was
+   successful and true is returned.  Otherwise, false is returned.
+
+== Net::Ping::UDP
+Ping::UDP#ping
+   Attempts to open a connection using UDPSocket and sends the value of
+   Ping::UDP#data as a string across the socket.  If the return string matches,
+   then the ping was successful and true is returned.  Otherwise, false is
+   returned.
 	
-PingTCP.econnrefused
-	Returns the setting for how ECONNREFUSED is handled.  By default, this is
-	set to false, i.e. an ECONNREFUSED error is considered a failed ping.
+Ping::UDP#data
+   Returns the string that is sent across the UDP socket.
 	
-PingTCP.econnrefused=(bool)
-	Sets the behavior for how ECONNREFUSED is handled.  By default, this is
-	set to false, i.e. an ECONNREFUSED error is considered a failed ping.
-	
-PingTCP#ping
-PingTCP#ping?
-	Attempts to open a connection using TCPSocket.  A successful open means
-	the ping was successful and true is returned.  Otherwise, false is returned.
-
-=== PingUDP
-PingUDP.new(host, port=7, timeout=5)
-	Creates and returns a new PingUDP object.
-	
-PingUDP#ping
-PingUDP#ping?
-	Attempts to open a connection using UDPSocket and sends the value of
-	PingUDP#data as a string across the socket.  If the return string matches,
-	then the ping was successful and true is returned.  Otherwise, false is
-	returned.
-	
-PingUDP#data
-	Returns the string that is sent across the UDP socket.
-	
-PingUDP#data=(string)
-	Sets the string that is sent across the UDP socket.  The default is "ping"
+Ping::UDP#data=(string)
+   Sets the string that is sent across the UDP socket.  The default is "ping".
+   Note that the +string+ cannot be larger than MAX_DATA (64 characters).
 
-=== PingExternal
-PingExternal.new(host, port=7, timeout=5)
-	Creates and returns a new PingExternal object.
-	
-PingExternal#ping
-PingExternal#ping?
-	Uses the 'open3' module and calls your system's local 'ping' command with
-	various options, depending on platform.  If nothing is sent to stderr, the
-	ping was successful and true is returned.  Otherwise, false is returned.
-	
-=== PingHTTP
-PingHTTP.new(uri, port=80, timeout=5)
-	Creates and returns a new PingHTTP object.
+== Net::Ping::External
+Ping::External#ping
+   Uses the 'open3' module and calls your system's local 'ping' command with
+   various options, depending on platform.  If nothing is sent to stderr, the
+   ping was successful and true is returned.  Otherwise, false is returned.
+
+   The MS Windows platform requires the 'win32-open3' package.
 	
-PingHTTP#ping
-PingHTTP#ping?
-	Checks for a response against +uri+.  As long as a Net::HTTPSuccess or
-	Net::HTTPOK response is returned, the ping is successful and true is
-	returned.  Otherwise, false is returned and PingHTTP#exception is set to
-	the error message.
+== Ping::HTTP
+Ping::HTTP.new(uri=nil, port=80, timeout=5)
+   Identical to Net::Ping.new except that, instead of a host, the first
+   argument is a URI.
 	
-PingHTTP#uri
-	An alias for PingHTTP#host.
+Ping::HTTP#ping
+   Checks for a response against +uri+.  As long as kind of Net::HTTPSuccess
+   response is returned, the ping is successful and true is returned.
+   Otherwise, false is returned and Ping::HTTP#exception is set to the error
+   message.
+
+   Note that redirects are automatically followed unless the
+   Ping::HTTP#follow_redirects method is set to false.
+
+Ping::HTTP#follow_redirect
+   Indicates whether or not a redirect should be followed in a ping attempt.
+   By default this is set to true.
+
+Ping::HTTP#follow_redirect=(bool)
+   Sets whether or not a redirect should be followed in a ping attempt.  If
+   set to false, then any redirect is considered a failed ping.
+
+Ping::HTTP#uri
+   An alias for Ping::HTTP#host.
 	
-PingHTTP#uri=(uri)
-	An alias for PingHTTP#host=.
+Ping::HTTP#uri=(uri)
+   An alias for Ping::HTTP#host=.
+
+== Ping::ICMP
+Ping::ICMP#duration
+   The time it took to ping the host.  Not a precise value but a good estimate.
 
-== Instance Methods
+= Common Instance Methods
 Ping#exception
-	Returns the error string that was set if a ping call failed.  If an exception
-	is raised, it is caught and stored in this attribute.  It is not raised in
-	your code.
+   Returns the error string that was set if a ping call failed.  If an exception
+   is raised, it is caught and stored in this attribute.  It is not raised in
+   your code.
 	
-	This should be nil if the ping succeeded.
+   This should be nil if the ping succeeded.
 
 Ping#host
-	Returns the host name that ping attempts will ping against.
+   Returns the host name that ping attempts will ping against.
 
 Ping#host=(hostname)
-	Sets the host name that ping attempts will ping against.
+   Sets the host name that ping attempts will ping against.
 
 Ping#port
-	Returns the port number that ping attempts will use.
+   Returns the port number that ping attempts will use.
 	
 Ping#port=(port)
-	Set the port number to open socket connections on.  The default is 7 (or
-	whatever your 'echo' port is set to).  Note that you can also specify a
-	string, such as "http".
+   Set the port number to open socket connections on.  The default is 7 (or
+   whatever your 'echo' port is set to).  Note that you can also specify a
+   string, such as "http".
 
 Ping#timeout
-	Returns the amount of time before the timeout module raises a TimeoutError
-	during connection attempts.  The default is 5 seconds.
+   Returns the amount of time before the timeout module raises a TimeoutError
+   during connection attempts.  The default is 5 seconds.
 	
 Ping#timeout=(time)
-	Sets the amount of time before the timeout module raises a TimeoutError.
-	during connection attempts.
+   Sets the amount of time before the timeout module raises a TimeoutError.
+   during connection attempts.
 	
 Ping#warning
-	Returns a warning string that was returned during the ping attempt.  This
-	typically occurs only in the PingExternal class.
+   Returns a warning string that was returned during the ping attempt.  This
+   typically occurs only in the Ping::External class, or the Ping::HTTP class
+   if a redirect occurred.
 
 == Notes
    If a host is down *IT IS CONSIDERED A FAILED PING*, and the 'no answer from
@@ -146,7 +162,7 @@ Ping#warning
    this behavior, in which case you need merely check the exception attribute
    against a regex as a simple workaround.
 
-== FAQ
+== Pre-emptive FAQ
    Q: "Why don't you return exceptions if a connection fails?"
 
    A: Because ping is only meant to return one of two things - success or
@@ -158,7 +174,7 @@ Ping#warning
 
    A: It's possible that the echo port has been disabled on the remote
       host for security reasons.  Your best best is to specify a different port
-      or to use PingExternal instead.
+      or to use Ping::ICMP or Ping::External instead.
 
    Q: "Why does TCP ping return false when I know it should return true?"
 
@@ -177,29 +193,33 @@ Ping#warning
    A: I *could* but I won't so don't bug me about it.  It's far more effort than
       it's worth.
 
-== Known Bugs
+= Known Bugs
    You may see a test failure from the tc_pingtcp test case.  You can ignore
    this.
 
    Please report any bugs on the project page at
    http://www.rubyforge.org/projects/shards.
 
-== Future Plans
-   Add an PingICMP class (help wanted)
-   (Though see arton's icmpping package on the RAA)
+= Acknowledgements
+   The Ping::ICMP#ping method is based largely on the identical method from
+   the Net::Ping Perl module by Rob Brown.  Much of the code was ported by
+   Jos Backus on ruby-talk.
+
+= Future Plans
+   Add a bind method.
 
-== License
+= License
    Ruby's
 
-== Copyright
-   (C) 2003-2005 Daniel J. Berger, All Rights Reserved
+= Copyright
+   (C) 2003-2006 Daniel J. Berger, All Rights Reserved
 
-== Warranty
+= Warranty
    This package is provided "as is" and without any express or
    implied warranties, including, without limitation, the implied
    warranties of merchantability and fitness for a particular purpose.
 
-== Author
+= Author
    Daniel J. Berger
    djberg96 at gmail dot com
    imperator on IRC (irc.freenode.net)

data/lib/net/ping.rb

@@ -1,237 +1,11 @@
-require "socket"
-require "timeout"
-
-module Net
-   # An abstract base class.  Do not instantiate directly.
-   class Ping
-      VERSION = "1.1.1"
-      attr_accessor :host, :port, :timeout
-      attr_reader :exception, :warning
-      
-      def initialize(host, port=nil, timeout=5)
-         @host    = host
-         @port    = port || Socket.getservbyname("echo") || 7
-         @timeout = timeout
-         @data    = "ping"
-         @exception = nil
-         @warning   = nil
-      end
-      
-      def ping
-         @exception = nil
-         @warning   = nil
-      end
-   end
-
-   ##########################################################################
-   # With a TCP ping, simply try to open a connection.  If we are successful,
-   # assume success.  In either case, close the connection to be polite.
-   ##########################################################################
-   class PingTCP < Ping
-      @@econnrefused = false
-
-      # Returns whether or not ECONNREFUSED error is to be considered a
-      # successful ping.  The default is false.
-      def self.econnrefused
-         @@econnrefused
-      end
-
-      # An alias for PingTCP.econnrefused
-      def self.ecr
-         self.econnrefused
-      end
-
-      # Sets whether or not an ECONNREFUSED error should be considered a
-      # successful ping.
-      def self.econnrefused=(bool)
-         unless bool.kind_of?(TrueClass) || bool.kind_of?(FalseClass)
-            raise ArgumentError, "argument must be true or false"
-         end
-         @@econnrefused = bool
-      end
-
-      # An alias for PingTCP.econnrefused=
-      def self.ecr=(bool)
-         self.econnrefused = bool
-      end
-
-      # This method attempts to ping a host and port using a TCPSocket with
-      # the host and port values passed to the constructor. 
-      def ping
-         super
-         success = false
-         tcp = nil
-         begin
-            Timeout.timeout(@timeout){
-               begin
-                  tcp = TCPSocket.new(@host,@port)
-               rescue Errno::ECONNREFUSED => err
-                  if @@econnrefused == true
-                     success = true
-                  else
-                     @exception = err
-                  end
-               rescue Exception => err
-                  @exception = err
-               else
-                  success = true
-               end
-            }
-         rescue Timeout::Error => err
-            @exception = err
-         ensure
-            tcp.close if tcp
-         end
-         success
-      end
-      
-      alias ping? ping
-   end
-   
-   ##########################################################################
-   # With a UDP ping, send a simple text string and check the return string.
-   # If they match, assume success.
-   ##########################################################################
-   class PingUDP < Ping
-      attr_accessor :data
-
-      # Sends a simple text string and checks the return string.  If they
-      # match, the ping was successful.
-      def ping
-         super
-         success = false
-         udp = UDPSocket.open
-         a = []
-         begin
-            Timeout.timeout(@timeout){
-               udp.connect(@host, @port)
-               udp.send(@data, 0)
-               a = udp.recvfrom(64)
-            }
-         rescue Exception => err
-            @exception = err
-         else
-            if a[0] == @data
-               success = true
-            end
-         ensure
-            udp.close if udp
-         end
-         success
-      end
-      
-      alias ping? ping
-   end
-   
-   ##################################
-   # Use your system's ping command
-   ##################################
-   class PingExternal < Ping
-
-      # Pings the host using your system's ping utility and checks for any
-      # errors or warnings.
-      def ping
-         super
-         input, output, error = ""
-         pstring = "ping "
-         success = false
-         
-         case PLATFORM
-            when /linux|bsd/i
-               pstring += "-c 1 #{@host}"
-            when /solaris|sunos/i
-               pstring += "#{@host} 1"
-            when /hpux/i
-               pstring += "#{@host} -n 1"
-            when /win32|windows/i
-               pstring += "-n 1 #{@host}"
-            else
-               pstring += "#{@host}"
-         end
-         
-         if File::ALT_SEPARATOR
-            require "win32/open3"           
-         else
-            require "open3"            
-         end
-         
-         Timeout.timeout(@timeout){
-            input, output, error = Open3.popen3(pstring)
-         }
-
-         e = error.gets # Can't chomp yet, might be nil
-
-         input.close
-         error.close
-        
-         unless e.nil?
-            if e =~ /warning/i
-               @warning = e.chomp
-               success = true
-            else
-               @exception = e.chomp
-            end
-         # The "no answer" response goes to stdout, not stderr, so check it
-         else
-            lines = output.readlines
-            output.close
-            if lines.nil? || lines.empty?
-               success = true
-            else
-               regexp = /no answer|host unreachable|could not find host/i
-               lines.each{ |e|
-                  if regexp.match(e)
-                     @exception = e.chomp
-                  end
-               }
-               success = true
-            end
-         end
-         success
-      end
-      
-      alias ping? ping
-   end
-
-   # For this class, +host+ is actually a URI.
-   class PingHTTP < Ping
-      require "net/http"
-      require "uri"
-      include Net
-      
-      # Creates and returns a new PingHTTP object.
-      #--
-      # Defined separately in order to set the default port to 80.
-      def initialize(host, port=80, timeout=5)
-         super(host, port, timeout)
-      end
-
-      # Looks for an HTTP response from the URI passed to the constructor.
-      # If the result is HTTPSuccess or HTTPOK, the ping was successful.
-      def ping
-         super
-         success = false
-         uri = URI.parse(@host)
-
-         begin
-            resp = HTTP.get_response(uri.host, uri.path, @port)
-         rescue Exception => err
-            @exception = err
-         else
-            case resp
-               when Net::HTTPSuccess, Net::HTTPOK
-                  success = true
-               else
-                  @exception = resp.message
-            end
-         end
-
-         success
-      end
-
-      alias ping? ping
-      alias uri host
-      alias uri= host=
-   end
-
-end # Net
+# By doing a "require 'net/ping'" you are requiring every subclass.  If you
+# want to require a specific ping type only, do "require 'net/ping/tcp'",
+# for example.
+#
+$LOAD_PATH.unshift File.dirname(__FILE__)
+
+require 'ping/tcp'
+require 'ping/udp'
+require 'ping/icmp'
+require 'ping/external'
+require 'ping/http'