net-ping 2.0.8 → 2.1.0

data/docs/superpowers/specs/2026-07-25-platform-specific-gems-design.md

@@ -0,0 +1,71 @@
+# Platform-specific gem dependencies
+
+## Goal
+
+Resolve issue #31 by publishing platform-specific `net-ping` gems whose
+runtime dependencies accurately describe the requirements for ICMP support.
+The solution also corrects the equivalent Linux `cap2` metadata omission.
+
+## Scope
+
+The release produces three gems with the same name and version:
+
+| Gem platform | Additional runtime dependency |
+| --- | --- |
+| `ruby` | None |
+| `universal-linux` | `cap2 (>= 0.2.2)` |
+| `universal-mingw-ucrt` | `win32-security (>= 0.2.0)` |
+
+Only the current RubyInstaller `mingw-ucrt` platform is supported for Windows.
+Legacy `mingw32` is out of scope.
+
+The CI workflow builds and validates these gems, but does not publish them.
+The existing release process remains responsible for pushing all three files
+to RubyGems.
+
+## Design
+
+`net-ping.gemspec` becomes the OS-independent Ruby gemspec. It must not
+inspect the host OS or add OS-specific runtime dependencies.
+
+`net-ping-universal-linux.gemspec` loads the base specification, changes its
+platform to `universal-linux`, and adds `cap2`. The platform is intentionally
+CPU-independent so RubyGems can select it for supported Linux CPU variants.
+
+`net-ping-universal-mingw-ucrt.gemspec` loads the same base specification,
+changes its platform to `universal-mingw-ucrt`, and adds `win32-security`.
+
+The Rake gem namespace explicitly enumerates the three gemspecs. `gem:create`
+cleans old gem artifacts and builds all three. `gem:install` selects the
+specific generated specification compatible with the local platform, falling
+back to the Ruby specification when no platform-specific specification
+matches, then installs its artifact.
+
+## Verification
+
+Add `gem:check`, which reads each generated gem through RubyGems and fails
+when its platform or runtime dependencies differ from this specification:
+
+- Ruby gem: platform `ruby`; neither `cap2` nor `win32-security`.
+- Linux gem: platform `universal-linux`; includes `cap2`.
+- Windows gem: platform `universal-mingw-ucrt`; includes `win32-security`.
+
+The existing GitHub Actions matrix continues to run the test suite. It also
+runs `gem:create` and `gem:check` on both Ubuntu and Windows. A missing,
+malformed, or incorrectly attributed dependency causes the job to fail.
+
+## Documentation
+
+Update the prerequisite/install documentation to state that RubyGems chooses
+the platform-specific package and installs the Linux or Windows ICMP
+dependency automatically.
+
+Add a `CHANGES` entry describing the corrected platform-specific dependency
+metadata.
+
+## Non-goals
+
+- Publishing gems from CI.
+- Supporting legacy `mingw32`.
+- Changing ICMP runtime behavior.
+- Altering non-ICMP protocol implementations or tests.

data/lib/net/ping/external.rb

@@ -66,7 +66,7 @@ module Net
                 bool = true  # Success, at least one response.
               end
 
-              if err & (err =~ /warning/i)
+              if err && (err =~ /warning/i)
                 @warning = err.chomp
               end
             when 2
@@ -116,8 +116,10 @@ module Net
           pcmd += ['-i', interval.to_s] unless RbConfig::CONFIG['busybox']
         when /aix/i
           pcmd += ['-c', count.to_s, '-w', timeout.to_s, host]
+        when /freebsd/i
+          pcmd += ['-c', count.to_s, '-x', timeout.to_s, host]
         when /bsd|osx|mach|darwin/i
-          pcmd += ['-c', count.to_s, '-t', timeout.to_s, host]
+          pcmd += ['-c', count.to_s, '-i', interval.to_s, host]
         when /solaris|sunos/i
           pcmd += [host, timeout.to_s]
         when /hpux/i
@@ -147,7 +149,7 @@ module Net
                 bool = true  # Success, at least one response.
               end
 
-              if err & err =~ /warning/i
+              if err && (err =~ /warning/i)
                 @warning = err.chomp
               end
             when 2

data/lib/net/ping/ping.rb

@@ -1,6 +1,8 @@
 require 'socket'
 require 'timeout'
 
+require_relative 'version'
+
 # The Net module serves as a namespace only.
 #
 module Net
@@ -9,9 +11,6 @@ module Net
    # types. You should not instantiate this class directly.
    #
    class Ping
-      # The version of the net-ping library.
-      VERSION = '1.7.6'
-
       # The host to ping. In the case of Ping::HTTP, this is the URI.
       attr_accessor :host
 

data/lib/net/ping/version.rb

@@ -0,0 +1,6 @@
+module Net
+  class Ping
+    # The version of the net-ping library.
+    VERSION = '2.1.0'
+  end
+end

data/net-ping-universal-linux.gemspec

@@ -0,0 +1,4 @@
+spec = Gem::Specification.load('net-ping.gemspec').dup
+spec.platform = Gem::Platform.new(['universal', 'linux'])
+spec.add_dependency('cap2', '>= 0.2.2')
+spec

data/net-ping-universal-mingw-ucrt.gemspec

@@ -0,0 +1,7 @@
+spec = Gem::Specification.load('net-ping.gemspec').dup
+spec.platform = Gem::Platform.new(['universal', 'mingw-ucrt'])
+spec.add_dependency('win32-security', '>= 0.2.0')
+
+# No longer a default gem as of Ruby 4.0. Used by the WMI ping class.
+spec.add_dependency('win32ole', '>= 1.8.8')
+spec

data/net-ping.gemspec

@@ -1,16 +1,15 @@
-require 'rubygems'
-require 'rbconfig'
+require_relative "lib/net/ping/version"
 
 Gem::Specification.new do |spec|
   spec.name      = 'net-ping'
-  spec.version   = '2.0.8'
+  spec.version   = Net::Ping::VERSION
   spec.license   = 'Artistic 2.0'
   spec.author    = 'Chris Chernesky'
   spec.email     = 'chris.netping@tinderglow.com'
   spec.homepage  = 'https://github.com/chernesk/net-ping'
   spec.summary   = 'A ping interface for Ruby.'
   spec.test_file = 'test/test_net_ping.rb'
-  spec.files     = Dir['**/*'].reject{ |f| f.include?('git') }
+  spec.files     = Dir['**/*'].reject { |f| f.include?('git') || File.extname(f) == '.gem' }
   spec.metadata = {
     'bug_tracker_uri' => "#{spec.homepage}/issues",
     'changelog_uri' => "#{spec.homepage}/blob/master/CHANGES",
@@ -25,21 +24,10 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = ">= 1.9.3"
 
   spec.add_development_dependency('test-unit', '>= 0')
-  spec.add_development_dependency('fakeweb', '>= 0')
+  spec.add_development_dependency('webmock', '>= 0')
   spec.add_development_dependency('rake', '>= 0')
   spec.add_development_dependency('pry-byebug', '>= 0')
 
-  if File::ALT_SEPARATOR
-    require 'rbconfig'
-    arch = RbConfig::CONFIG['build_os'] || 'mingw32' # JRuby
-    spec.platform = Gem::Platform.new(['universal', arch])
-    spec.platform.version = nil
-
-    # Used for icmp pings.
-    spec.add_dependency('win32-security', '>= 0.2.0')
-    spec.add_dependency('cap2', '>= 0.2.2')
-  end
-
   spec.description = <<-EOF
     The net-ping library provides a ping interface for Ruby. It includes
     separate TCP, HTTP, LDAP, ICMP, UDP, WMI (for Windows) and external ping

data/test/test_net_ping.rb

@@ -5,10 +5,10 @@
 # class test won't be run unless this is run as a privileged process.
 ######################################################################
 require 'test_net_ping_external'
+require 'test_net_ping_gem_packaging'
 require 'test_net_ping_http'
 require 'test_net_ping_tcp'
 require 'test_net_ping_udp'
-require 'fakeweb'
 
 if File::ALT_SEPARATOR
   require 'win32/security'
@@ -39,8 +39,6 @@ end
 
 class TC_Net_Ping < Test::Unit::TestCase
   def test_net_ping_version
-    assert_equal('1.7.6', Net::Ping::VERSION)
+    assert_equal(Gem::Specification.load('net-ping.gemspec').version.to_s, Net::Ping::VERSION)
   end
 end
-
-FakeWeb.allow_net_connect = false

data/test/test_net_ping_external.rb

@@ -10,6 +10,8 @@
 #########################################################################
 require 'test-unit'
 require 'net/ping/external'
+require 'mkmf'
+require 'stringio'
 
 class TC_Net_Ping_External < Test::Unit::TestCase
   def setup
@@ -47,6 +49,7 @@ class TC_Net_Ping_External < Test::Unit::TestCase
   end
 
   test "pinging a good host returns true" do
+    omit_if(find_executable0('ping').nil?)
     assert_true(@pe.ping?)
   end
 
@@ -55,12 +58,14 @@ class TC_Net_Ping_External < Test::Unit::TestCase
   end
 
   test "duration basic functionality" do
+    omit_if(find_executable0('ping').nil?)
     assert_nothing_raised{ @pe.ping }
     assert_respond_to(@pe, :duration)
     assert_kind_of(Float, @pe.duration)
   end
 
   test "duration is unset if a bad ping follows a good ping" do
+    omit_if(find_executable0('ping').nil?)
     assert_nothing_raised{ @pe.ping }
     assert_not_nil(@pe.duration)
     assert_false(@pe.ping?(@bogus))
@@ -111,6 +116,7 @@ class TC_Net_Ping_External < Test::Unit::TestCase
   end
 
   test "pinging a good host results in no exception data" do
+    omit_if(find_executable0('ping').nil?)
     assert_nothing_raised{ @pe.ping }
     assert_nil(@pe.exception)
   end
@@ -134,6 +140,89 @@ class TC_Net_Ping_External < Test::Unit::TestCase
     assert_false(@bad.ping?)
   end
 
+  test "ping6 uses timeout for FreeBSD" do
+    command = nil
+    original_os = RbConfig::CONFIG['host_os']
+    original_popen3 = Open3.method(:popen3)
+
+    RbConfig::CONFIG['host_os'] = 'freebsd'
+    Open3.define_singleton_method(:popen3) do |*args, &block|
+      command = args
+      stdin = StringIO.new
+      stdout = StringIO.new
+      stderr = StringIO.new
+      status = Struct.new(:exitstatus).new(0)
+      thread = Struct.new(:value).new(status)
+      block.call(stdin, stdout, stderr, thread)
+    end
+
+    @pe.ping6('example.test', 2, 3, 4)
+
+    assert_equal(['ping6', '-c', '2', '-x', '4', 'example.test'], command)
+  ensure
+    RbConfig::CONFIG['host_os'] = original_os
+    Open3.define_singleton_method(:popen3, original_popen3)
+  end
+
+  test "ping6 uses interval for macOS" do
+    command = nil
+    original_os = RbConfig::CONFIG['host_os']
+    original_popen3 = Open3.method(:popen3)
+
+    RbConfig::CONFIG['host_os'] = 'darwin'
+    Open3.define_singleton_method(:popen3) do |*args, &block|
+      command = args
+      stdin = StringIO.new
+      stdout = StringIO.new
+      stderr = StringIO.new
+      status = Struct.new(:exitstatus).new(0)
+      thread = Struct.new(:value).new(status)
+      block.call(stdin, stdout, stderr, thread)
+    end
+
+    @pe.ping6('example.test', 2, 3, 4)
+
+    assert_equal(['ping6', '-c', '2', '-i', '3', 'example.test'], command)
+  ensure
+    RbConfig::CONFIG['host_os'] = original_os
+    Open3.define_singleton_method(:popen3, original_popen3)
+  end
+
+  test "ping6 succeeds without an exception when stderr is empty" do
+    stdin = StringIO.new
+    stdout = StringIO.new('64 bytes from ::1')
+    stderr = StringIO.new
+    status = Struct.new(:exitstatus).new(0)
+    thread = Struct.new(:value).new(status)
+    popen3 = Open3.method(:popen3)
+    nil_match = NilClass.instance_method(:=~) if NilClass.instance_methods(false).include?(:=~)
+    false_match = FalseClass.instance_method(:=~) if FalseClass.instance_methods(false).include?(:=~)
+
+    Open3.singleton_class.send(:define_method, :popen3) do |*args, &block|
+      block.call(stdin, stdout, stderr, thread)
+    end
+    [NilClass, FalseClass].each do |klass|
+      klass.send(:define_method, :=~) do |*args|
+        raise NoMethodError, "undefined method '=~' for #{self.inspect}"
+      end
+    end
+
+    assert_true(@pe.ping6('::1'))
+    assert_nil(@pe.exception)
+  ensure
+    Open3.singleton_class.send(:define_method, :popen3, popen3) if popen3
+    if nil_match
+      NilClass.send(:define_method, :=~, nil_match)
+    else
+      NilClass.send(:remove_method, :=~)
+    end
+    if false_match
+      FalseClass.send(:define_method, :=~, false_match)
+    else
+      FalseClass.send(:remove_method, :=~)
+    end
+  end
+
   def teardown
     @host  = nil
     @bogus = nil

data/test/test_net_ping_gem_packaging.rb

@@ -0,0 +1,333 @@
+require 'open3'
+require 'rake'
+require 'rubygems/package'
+require 'test/unit'
+
+class TestNetPingGemPackaging < Test::Unit::TestCase
+  GemfileRecorder = Struct.new(:dependencies) do
+    def initialize
+      super({})
+    end
+
+    def source(*); end
+    def gemspec(*); end
+
+    def gem(name, *requirements)
+      dependencies[name] = requirements
+    end
+  end
+
+  EXPECTATIONS = {
+    '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
+  ROOT = File.expand_path('..', __dir__)
+
+  def test_platforms_and_runtime_dependencies
+    gem_files = nil
+    specifications = load_specifications
+
+    Dir.chdir(ROOT) do
+      gem_files = specifications.map { |_, spec| Gem::Package.build(spec) }
+    end
+
+    specifications.each do |path, spec|
+      expected_platform, expected_dependencies = EXPECTATIONS.fetch(path)
+      packaged_spec = Gem::Package.new(File.join(ROOT, spec.file_name)).spec
+      dependencies = packaged_spec.runtime_dependencies.each_with_object({}) do |dependency, memo|
+        memo[dependency.name] = dependency.requirement.to_s
+      end
+
+      assert_equal(expected_dependencies, dependencies, path)
+
+      if platform_round_trips_for_test?(expected_platform)
+        assert_equal(expected_platform, packaged_spec.platform.to_s, path)
+      else
+        omit("this RubyGems (#{Gem::VERSION}) cannot round-trip the #{expected_platform.inspect} platform string")
+      end
+    end
+  ensure
+    delete_files(gem_files)
+  end
+
+  def test_rake_create_builds_all_expected_artifacts_and_validates_them
+    stdout, stderr, status = run_rake('clean', 'gem:create', 'gem:check')
+
+    assert(status.success?, [stdout, stderr].join)
+    assert_equal(expected_gem_files, built_gem_files)
+  ensure
+    delete_files(built_gem_files)
+  end
+
+  def test_gem_create_excludes_generated_artifacts_from_spec_files_and_keeps_bundle_exec_usable
+    stdout, stderr, status = run_rake('clean', 'gem:create')
+
+    assert(status.success?, [stdout, stderr].join)
+    load_specifications.each do |path, spec|
+      assert_equal([], spec.files.grep(/\.gem$/).sort, path)
+    end
+
+    stdout, stderr, status = run_bundle_exec('ruby', '-e', 'puts :bundle_exec_after_gem_create')
+    assert(status.success?, [stdout, stderr].join)
+    assert_equal("bundle_exec_after_gem_create\n", stdout)
+  ensure
+    delete_files(built_gem_files)
+  end
+
+  def test_gem_check_uses_fixed_expectations_instead_of_loaded_specifications
+    stdout, stderr, status = run_rake('clean', 'gem:create')
+
+    assert(status.success?, [stdout, stderr].join)
+
+    specifications = load_specifications.map do |path, spec|
+      if path == 'net-ping-universal-linux.gemspec'
+        [path, specification_with_reported_platform(spec, Gem::Platform::RUBY)]
+      else
+        [path, spec]
+      end
+    end
+
+    with_rakefile do |application|
+      with_stubbed_load_gem_specifications(specifications.map(&:last)) do
+        assert_nothing_raised { application['gem:check'].invoke }
+      end
+    end
+  ensure
+    delete_files(built_gem_files)
+  end
+
+  def test_gem_install_selects_local_compatible_specification
+    with_rakefile do
+      assert_equal(expected_install_platform, select_install_specification.platform.to_s)
+    end
+  end
+
+  def test_gemfile_adds_win32_security_only_for_windows_development
+    assert_nil(gemfile_dependencies_for(win_platform: false)['win32-security'])
+    assert_equal(
+      ['>= 0.2.0'],
+      gemfile_dependencies_for(win_platform: true)['win32-security']
+    )
+  end
+
+  def test_with_unbundled_env_prefers_with_unbundled_env_when_available
+    calls = []
+
+    with_rakefile do
+      with_stubbed_bundler_methods(
+        :with_unbundled_env => proc do |&block|
+          calls << :with_unbundled_env
+          block.call
+        end,
+        :with_clean_env => proc do |&block|
+          calls << :with_clean_env
+          block.call
+        end
+      ) do
+        assert_equal(:ran, with_unbundled_env { calls << :block; :ran })
+      end
+    end
+
+    assert_equal([:with_unbundled_env, :block], calls)
+  end
+
+  def test_with_unbundled_env_falls_back_to_with_clean_env
+    calls = []
+
+    with_rakefile do
+      with_stubbed_bundler_methods(
+        :with_clean_env => proc do |&block|
+          calls << :with_clean_env
+          block.call
+        end
+      ) do
+        assert_equal(:ran, with_unbundled_env { calls << :block; :ran })
+      end
+    end
+
+    assert_equal([:with_clean_env, :block], calls)
+  end
+
+  def test_platform_installable_prefers_installable_when_available
+    spec = Struct.new(:platform).new(:preferred_platform)
+    calls = []
+
+    with_rakefile do
+      with_stubbed_platform_methods(
+        :installable? => proc do |candidate|
+          calls << [:installable?, candidate.platform]
+          true
+        end,
+        :match => proc do |platform|
+          calls << [:match, platform]
+          false
+        end
+      ) do
+        assert_equal(true, platform_installable?(spec))
+      end
+    end
+
+    assert_equal([[:installable?, :preferred_platform]], calls)
+  end
+
+  def test_platform_installable_falls_back_to_match
+    spec = Struct.new(:platform).new(:fallback_platform)
+    calls = []
+
+    with_rakefile do
+      with_stubbed_platform_methods(
+        :match => proc do |platform|
+          calls << [:match, platform]
+          true
+        end
+      ) do
+        assert_equal(true, platform_installable?(spec))
+      end
+    end
+
+    assert_equal([[:match, :fallback_platform]], calls)
+  end
+
+  private
+
+  def load_specifications
+    Dir.chdir(ROOT) do
+      EXPECTATIONS.keys.map do |path|
+        assert(File.exist?(path), "#{path} does not exist")
+
+        loaded_spec = Gem::Specification.load(path)
+        spec = loaded_spec ? loaded_spec.dup : nil
+        assert_not_nil(spec, "expected #{path} to load")
+
+        [path, spec]
+      end
+    end
+  end
+
+  def expected_gem_files
+    load_specifications.map { |_, spec| spec.file_name }.sort
+  end
+
+  def built_gem_files
+    Dir.chdir(ROOT) { Dir['net-ping-*.gem'].sort }
+  end
+
+  def expected_install_platform
+    specifications = load_specifications.map(&:last)
+    specific = specifications.find do |spec|
+      spec.platform != Gem::Platform::RUBY && platform_installable_for_test?(spec)
+    end
+    (specific || specifications.find { |spec| spec.platform == Gem::Platform::RUBY }).platform.to_s
+  end
+
+  def run_rake(*tasks, env: {})
+    Open3.capture3(env, Gem.ruby, '-S', 'bundle', 'exec', 'rake', *tasks, chdir: ROOT)
+  end
+
+  def run_bundle_exec(*command, env: {})
+    Open3.capture3(env, Gem.ruby, '-S', 'bundle', 'exec', *command, chdir: ROOT)
+  end
+
+  def with_rakefile
+    original = Rake.application
+    application = Rake::Application.new
+    Rake.application = application
+
+    Dir.chdir(ROOT) do
+      load File.join(ROOT, 'Rakefile')
+      yield(application)
+    end
+  ensure
+    Rake.application = original
+  end
+
+  def gemfile_dependencies_for(win_platform:)
+    recorder = GemfileRecorder.new
+    singleton_class = class << Gem; self; end
+    original = singleton_class.instance_method(:win_platform?)
+    singleton_class.send(:define_method, :win_platform?) { win_platform }
+    recorder.instance_eval(File.read(File.join(ROOT, 'Gemfile')), File.join(ROOT, 'Gemfile'))
+
+    recorder.dependencies
+  ensure
+    singleton_class.send(:define_method, :win_platform?, original) if singleton_class && original
+  end
+
+  def delete_files(paths)
+    Array(paths).each do |path|
+      file = File.join(ROOT, path)
+      File.delete(file) if File.exist?(file)
+    end
+  end
+
+  def specification_with_reported_platform(spec, platform)
+    file_name = spec.file_name
+    mutated = spec.dup
+    mutated.platform = platform
+    mutated.define_singleton_method(:file_name) { file_name }
+    mutated
+  end
+
+  def with_stubbed_load_gem_specifications(specifications)
+    original = Object.instance_method(:load_gem_specifications)
+    Object.send(:remove_method, :load_gem_specifications)
+    Object.send(:define_method, :load_gem_specifications) { specifications }
+    Object.send(:private, :load_gem_specifications)
+    yield
+  ensure
+    Object.send(:remove_method, :load_gem_specifications)
+    Object.send(:define_method, :load_gem_specifications, original)
+    Object.send(:private, :load_gem_specifications)
+  end
+
+  def with_stubbed_bundler_methods(methods)
+    bundler = Module.new
+    methods.each do |name, implementation|
+      bundler.define_singleton_method(name, &implementation)
+    end
+
+    with_replaced_constant(Object, :Bundler, bundler) do
+      yield
+    end
+  end
+
+  def with_stubbed_platform_methods(methods)
+    platform = Module.new
+    methods.each do |name, implementation|
+      platform.define_singleton_method(name, &implementation)
+    end
+    platform.const_set(:RUBY, Gem::Platform::RUBY)
+
+    with_replaced_constant(Gem, :Platform, platform) do
+      yield
+    end
+  end
+
+  def with_replaced_constant(container, name, replacement)
+    original = container.const_get(name) if container.const_defined?(name, false)
+    container.send(:remove_const, name) if container.const_defined?(name, false)
+    container.const_set(name, replacement)
+    yield
+  ensure
+    container.send(:remove_const, name) if container.const_defined?(name, false)
+    if original
+      container.const_set(name, original)
+    end
+  end
+
+  def platform_round_trips_for_test?(platform_string)
+    Gem::Platform.new(platform_string).to_s == platform_string
+  end
+
+  def platform_installable_for_test?(spec)
+    if Gem::Platform.respond_to?(:installable?)
+      Gem::Platform.installable?(spec)
+    else
+      Gem::Platform.match(spec.platform)
+    end
+  end
+end