net-ping 2.1.0-universal-linux

data/Rakefile

@@ -0,0 +1,183 @@
+require 'rake'
+require 'rake/clean'
+require 'rake/testtask'
+include Object.const_defined?(:RbConfig) ? RbConfig : Config
+
+CLEAN.include("**/*.gem", "**/*.rbc")
+
+GEMSPEC_FILES = %w[
+  net-ping.gemspec
+  net-ping-universal-linux.gemspec
+  net-ping-universal-mingw-ucrt.gemspec
+].freeze
+
+EXPECTED_GEM_METADATA = {
+  'net-ping.gemspec' => ['ruby', {}],
+  'net-ping-universal-linux.gemspec' => ['universal-linux', {'cap2' => '>= 0.2.2'}],
+  'net-ping-universal-mingw-ucrt.gemspec' => [
+    'universal-mingw-ucrt',
+    {'win32-security' => '>= 0.2.0', 'win32ole' => '>= 1.8.8'}
+  ]
+}.freeze
+
+def load_gem_specifications
+  GEMSPEC_FILES.map do |path|
+    spec = Gem::Specification.load(path)
+    abort("Unable to load #{path}") unless spec
+    spec
+  end
+end
+
+def with_unbundled_env
+  if defined?(Bundler) && Bundler.respond_to?(:with_unbundled_env)
+    Bundler.with_unbundled_env { yield }
+  elsif defined?(Bundler) && Bundler.respond_to?(:with_clean_env)
+    Bundler.with_clean_env { yield }
+  else
+    yield
+  end
+end
+
+def platform_round_trips?(platform_string)
+  Gem::Platform.new(platform_string).to_s == platform_string
+end
+
+def platform_installable?(spec)
+  if Gem::Platform.respond_to?(:installable?)
+    Gem::Platform.installable?(spec)
+  else
+    Gem::Platform.match(spec.platform)
+  end
+end
+
+def select_install_specification(specifications = load_gem_specifications)
+  specific = specifications.find do |spec|
+    spec.platform != Gem::Platform::RUBY && platform_installable?(spec)
+  end
+  spec = specific || specifications.find { |item| item.platform == Gem::Platform::RUBY }
+  abort('Unable to find a Ruby fallback gem specification') unless spec
+  spec
+end
+
+namespace 'gem' do
+  desc 'Create the net-ping gem artifacts (ruby, universal-linux, universal-mingw-ucrt)'
+  task :create => [:clean] do
+    specifications = load_gem_specifications
+    if Gem::VERSION.to_f < 2.0
+      specifications.each do |spec|
+        Gem::Builder.new(spec).build
+      end
+    else
+      require 'rubygems/package'
+      specifications.each do |spec|
+        Gem::Package.build(spec)
+      end
+    end
+  end
+
+  desc 'Validate the net-ping gem artifacts'
+  task :check do
+    require 'rubygems/package'
+
+    EXPECTED_GEM_METADATA.each do |path, expectation|
+      expected_platform, expected_dependencies = expectation
+      artifact = Gem::Specification.load(path).file_name
+      packaged_spec = Gem::Package.new(artifact).spec
+      actual_dependencies = packaged_spec.runtime_dependencies.each_with_object({}) do |dependency, memo|
+        memo[dependency.name] = dependency.requirement.to_s
+      end
+
+      if platform_round_trips?(expected_platform) && packaged_spec.platform.to_s != expected_platform
+        abort("#{artifact}: expected platform #{expected_platform.inspect}, got #{packaged_spec.platform.to_s.inspect}")
+      end
+
+      if actual_dependencies != expected_dependencies
+        abort("#{artifact}: expected dependencies #{expected_dependencies.inspect}, got #{actual_dependencies.inspect}")
+      end
+    end
+  end
+
+  desc 'Install the net-ping gem'
+  task :install => [:create] do
+    spec = select_install_specification
+
+    install_command = if RUBY_PLATFORM == 'java'
+      ['jruby', '-S', 'gem', 'install', '-l', spec.file_name]
+    else
+      ['gem', 'install', '-l', spec.file_name]
+    end
+
+    with_unbundled_env do
+      sh(*install_command)
+    end
+  end
+end
+
+namespace 'example' do
+  desc 'Run the external ping example program'
+  task :external do
+     ruby '-Ilib examples/example_pingexternal.rb'
+  end
+
+  desc 'Run the http ping example program'
+  task :http do
+     ruby '-Ilib examples/example_pinghttp.rb'
+  end
+
+  desc 'Run the tcp ping example program'
+  task :tcp do
+     ruby '-Ilib examples/example_pingtcp.rb'
+  end
+
+  desc 'Run the udp ping example program'
+  task :udp do
+     ruby '-Ilib examples/example_pingudp.rb'
+  end
+end
+
+Rake::TestTask.new do |t|
+   t.libs << 'test'
+   t.warning = true
+   t.verbose = true
+   t.test_files = FileList['test/test_net_ping.rb']
+end
+
+namespace 'test' do
+  Rake::TestTask.new('external') do |t|
+     t.warning = true
+     t.verbose = true
+     t.test_files = FileList['test/test_net_ping_external.rb']
+  end
+
+  Rake::TestTask.new('http') do |t|
+     t.warning = true
+     t.verbose = true
+     t.test_files = FileList['test/test_net_ping_http.rb']
+  end
+
+  Rake::TestTask.new('icmp') do |t|
+     t.warning = true
+     t.verbose = true
+     t.test_files = FileList['test/test_net_ping_icmp.rb']
+  end
+
+  Rake::TestTask.new('tcp') do |t|
+     t.warning = true
+     t.verbose = true
+     t.test_files = FileList['test/test_net_ping_tcp.rb']
+  end
+
+  Rake::TestTask.new('udp') do |t|
+     t.warning = true
+     t.verbose = true
+     t.test_files = FileList['test/test_net_ping_udp.rb']
+  end
+
+  Rake::TestTask.new('wmi') do |t|
+     t.warning = true
+     t.verbose = true
+     t.test_files = FileList['test/test_net_ping_wmi.rb']
+  end
+end
+
+task :default => :test

data/doc/ping.txt

@@ -0,0 +1,246 @@
+= Description
+   A simple Ruby interface to the 'ping' command.
+
+= Synopsis
+   require 'net/ping'
+   include Net
+
+   Ping::TCP.service_check = true
+
+   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"
+   else
+      puts "TCP ping unsuccessful: " +  pt.exception
+   end
+
+   if pu.ping
+      puts "UDP ping successful"
+   else
+      puts "UDP ping unsuccessful: " +  pu.exception
+   end
+
+   if pe.ping
+      puts "External ping successful"
+   else
+      puts "External ping unsuccessful: " +  pe.exception
+   end
+
+   if ph.ping?
+      puts "HTTP ping successful"
+   else
+      puts "HTTP ping unsuccessful: " + ph.exception
+   end
+
+= Ping Classes
+   * Ping::TCP
+   * Ping::UDP
+   * Ping::External
+   * Ping::HTTP
+   * Ping::ICMP
+   * Ping::WMI
+   * Ping::LDAP
+
+   All Ping classes are children of the Ping parent class (which should
+   never be instantiated directly).
+
+   The Ping::ICMP class requires root/administrative privileges.
+
+   The Ping::WMI class only works on MS Windows.
+
+== 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.service_check
+   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.service_check=(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.
+	
+Ping::UDP#data
+   Returns the string that is sent across the UDP socket.
+	
+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).
+
+== 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.
+	
+== 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.
+	
+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.
+	
+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.
+
+== Ping::WMI
+Ping::WMI#ping(host, options={})
+   Unlike other Ping classes, this method returns a PingStatus struct that
+   contains various bits of information about the ping itself. The PingStatus
+   struct is a wrapper for the Win32_PingStatus WMI class.
+
+   In addition, you can pass options that will be interpreted as WQL parameters.
+
+Ping::WMI#ping?(host, options={})
+   Returns whether or not the ping succeeded.
+
+= 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.
+	
+   This should be nil if the ping succeeded.
+
+Ping#host
+   Returns the host name that ping attempts will ping against.
+
+Ping#host=(hostname)
+   Sets the host name that ping attempts will ping against.
+
+Ping#port
+   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".
+
+Ping#timeout
+   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.
+	
+Ping#warning
+   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
+   +host+' text is assigned to the 'exception' attribute.  You may disagree with
+   this behavior, in which case you need merely check the exception attribute
+   against a regex as a simple workaround.
+
+== 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
+      failure. It's very simple. If you want to find out *why* the ping
+      failed, you can check the 'exception' attribute.
+
+   Q: "I know the host is alive, but a TCP or UDP ping tells me otherwise. What
+      gives?"
+
+   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 Ping::ICMP or Ping::External instead.
+      
+      In the case of UDP pings, they are often actively refused. It may be
+      more pragmatic to set Ping::UDP.service_check = false.
+
+   Q: "Why does a TCP ping return false when I know it should return true?"
+
+   A: By default ECONNREFUSED errors will return a value of false. This is
+      contrary to what most other folks do for TCP pings. The problem with
+      their philosophy is that you can get false positives if a firewall blocks
+      the route to the host. The problem with my philosophy is that you can
+      get false negatives if there is no firewall (or it's not blocking the
+      route). Given the alternatives I chose the latter.
+
+      You can always change the default behavior by using the +service_check+
+      class method.
+      
+      A similar situation is true for UDP pings.
+
+   Q: "Couldn't you use traceroute information to tell for sure?"
+
+   A: I could but I won't so don't bug me about it. It's far more effort than
+      it's worth. If you want something like that, please port the
+      Net::Traceroute Perl module by Daniel Hagerty.
+
+= Known Bugs
+   You may see a test failure from the test_net_ping_tcp test case. You can
+   ignore these.
+   
+   UDP pings may not work with older versions of Ruby 1.9.x.
+
+   Please report any bugs on the project page at
+   https://github.com/djberg96/net-ping
+
+= 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 support for syn pings.
+
+= License
+   Artistic 2.0
+
+= Copyright
+   (C) 2003-2014 Daniel J. Berger, All Rights Reserved
+
+= 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
+   Daniel J. Berger