net-ping 2.2.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cde6d53c546914dc2150eb754a1d0b79ca1391b8a4c10be31ef161ff1d94a13d
-  data.tar.gz: b8cad0dbe1bd739e4407c03fdd72aa05e6a5152bed56fe8c0d7b450f0bf84b59
+  metadata.gz: 615dc26b8e3f3946e27edd9d77a5db989cd7dc61acef84347ffa9bce3608bb4c
+  data.tar.gz: 067abe30201a7b58b738f1f6bf2a594c71a16489f4d4cace8bfa750e9c0e192a
 SHA512:
-  metadata.gz: 324fb64066295878e20c61bd2dd4bfefd82d6171a1ede99bead3c407cd9388012673e4d99245591ed188b48a59b2d6371dc15b0d9c8db549affcdf870a67adfe
-  data.tar.gz: c6fdb6bd7c15ef6ae6c3fcdf78e8bf55ca9d2f6c95b6373a9c2eb9dee22ea7b220eccf92c4ad023809d84425fe06e8b18fd54b60918152199536dc26c7ca612c
+  metadata.gz: '0049c0226fb551554f816c8a824a8784107ed62af88ce5b7d00491db35505b21f0e62226afbcfcfa92d6fab58768f46c12289beeca9ff1a6b91941bf1c748ff0'
+  data.tar.gz: b4ca3000e0abb199a2209985d745708c35f62cfef2ca18ca0071b3d880c3e81160d99bb26af9b4f296934b343c889f09e6fa192ffa303da12fbd0f10e4469cfa

data/CHANGES

@@ -1,3 +1,19 @@
+== 3.0.0 - 01-Nov-2026
+* Raise the minimum supported Ruby version from 1.9.3 to 2.7, matching the
+  lowest version covered by CI. This is a breaking change for users on
+  older Rubies [#53](https://github.com/eitoball/net-ping/pull/53).
+* Add JRuby support: fix TCP ping's handling of refused connections, make
+  UDP ping's timeout work on JRuby, and use win32ole-ffi for WMI pings on
+  JRuby. JRuby 10.0/10.1 are now covered by CI
+  [#53](https://github.com/eitoball/net-ping/pull/53).
+* `require 'net/ping'` on Windows now warns instead of raising when
+  win32ole or win32-security is missing
+  [#53](https://github.com/eitoball/net-ping/pull/53).
+* Drop pry-byebug from the gem's development dependencies
+  [#53](https://github.com/eitoball/net-ping/pull/53).
+* Add RBS type definitions under sig/
+  [#54](https://github.com/eitoball/net-ping/pull/54).
+
 == 2.2.0 - 22-Sep-2026
 * Add support for HTTP to ping URLs requiring a query parameter, carrying
   forward #25 by Kenneth Perry (@thothonegan)

data/Gemfile

@@ -2,7 +2,21 @@ source 'https://rubygems.org'
 gemspec
 gem 'win32-security', '>= 0.2.0' if Gem.win_platform?
 
-# No longer a default gem as of Ruby 4.0. Used by the WMI ping class.
-gem 'win32ole', '>= 1.8.8' if Gem.win_platform?
+# Used by the WMI ping class. No longer a default gem as of Ruby 4.0, and
+# win32ole's C extension does not build on JRuby, so use the pure-Ruby
+# win32ole-ffi gem there instead.
+if Gem.win_platform?
+  if RUBY_ENGINE == 'jruby'
+    gem 'win32ole-ffi', '>= 0.1.0'
+  else
+    gem 'win32ole', '>= 1.8.8'
+  end
+end
 
 gem 'cap2', '>= 0.2.2' if RUBY_PLATFORM =~ /linux/i
+
+# byebug's C extension does not build on JRuby.
+gem 'pry-byebug', '>= 0' unless RUBY_ENGINE == 'jruby'
+
+# Validates sig/**/*.rbs. Requires Ruby >= 3.2.
+gem 'rbs', '>= 3', require: false if RUBY_VERSION >= '3.2'

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    net-ping (2.2.0)
+    net-ping (3.0.0)
 
 GEM
   remote: https://rubygems.org/
@@ -17,8 +17,10 @@ GEM
       rexml
     hashdiff (1.2.1)
     io-console (0.8.2)
+    logger (1.7.0)
     method_source (1.1.0)
     power_assert (3.0.1)
+    prism (1.9.0)
     pry (0.16.0)
       coderay (~> 1.1)
       method_source (~> 1.0)
@@ -28,11 +30,16 @@ GEM
       pry (>= 0.13, < 0.17)
     public_suffix (7.0.5)
     rake (13.4.2)
+    rbs (4.2.0)
+      logger
+      prism (>= 1.6.0)
+      tsort
     reline (0.6.3)
       io-console (~> 0.5)
     rexml (3.4.4)
     test-unit (3.7.8)
       power_assert
+    tsort (0.2.0)
     webmock (3.26.2)
       addressable (>= 2.8.0)
       crack (>= 0.3.2)
@@ -46,6 +53,7 @@ DEPENDENCIES
   net-ping!
   pry-byebug
   rake
+  rbs (>= 3)
   test-unit
   webmock
 

data/README.md

@@ -4,13 +4,14 @@ A collection of classes that provide different ways to ping computers.
 ## Prerequisites
   * ffi
   * win32-security (installed from the Windows gem artifact)
-  * win32ole (installed from the Windows gem artifact)
+  * win32ole (installed from the Windows gem artifact), or win32ole-ffi on JRuby
   * cap2 (installed from the Linux gem artifact)
   * webmock (test only)
   * test-unit (test only)
 
-  Ruby users should use Ruby 1.9.3 or later.
-  JRuby users should use JRuby 1.6.7 or later.
+  CI covers the following versions:
+  * Ruby: 4.0, 3.4, 3.3, 3.2, 3.1, 3.0, 2.7
+  * JRuby: 10.1, 10.0
 
 ## Installation
   ```gem install net-ping```
@@ -47,6 +48,14 @@ A collection of classes that provide different ways to ping computers.
   ICMP pings will not work with JRuby without some sort of third-party
   library support for raw sockets in Java, such as RockSaw.
 
+  WMI pings will not work on JRuby unless you separately `gem install
+  win32ole-ffi`. Without it, `require 'net/ping'` prints a warning and
+  leaves `Net::Ping::WMI` undefined, rather than raising. The published
+  net-ping gem can't declare this automatically: RubyGems' JRuby platform
+  tag doesn't distinguish Windows from other OSes, so there's no
+  platform-specific gemspec to attach a
+  Windows-only dependency to.
+
 ## License
   Artistic 2.0
 

data/Rakefile

@@ -180,4 +180,11 @@ namespace 'test' do
   end
 end
 
+namespace 'sig' do
+  desc 'Validate the RBS type signatures under sig/'
+  task :validate do
+    sh 'bundle exec rbs -I sig -r socket -r timeout -r open3 -r uri -r net-http -r openssl validate'
+  end
+end
+
 task :default => :test

data/lib/net/ping/icmp.rb

@@ -1,7 +1,11 @@
 require File.join(File.dirname(__FILE__), 'ping')
 
 if File::ALT_SEPARATOR
-  require 'win32/security'
+  begin
+    require 'win32/security'
+  rescue LoadError => err
+    warn "Elevated-privilege detection is unavailable (#{err.message}). Run `gem install win32-security` to enable it."
+  end
 end
 
 # The Net module serves as a namespace only.
@@ -45,6 +49,10 @@ module Net
       end
 
       if File::ALT_SEPARATOR
+        unless defined?(Win32::Security)
+          raise LoadError, 'win32-security is required for elevated-privilege detection on Windows; run `gem install win32-security`'
+        end
+
         unless Win32::Security.elevated_security?
           raise 'requires elevated security'
         end

data/lib/net/ping/tcp.rb

@@ -67,31 +67,47 @@ module Net
           return false
         end
 
-        resp = IO.select(nil, [sock], nil, timeout)
-
-        if resp.nil? # Assume ECONNREFUSED if nil
-          if @@service_check
-            bool = true
-          else
-            bool = false
-            @exception = Errno::ECONNREFUSED
-          end
-        else
-          sockopt = sock.getsockopt(Socket::SOL_SOCKET, Socket::SO_ERROR)
+        begin
+          resp = IO.select(nil, [sock], nil, timeout)
 
-          if sockopt.int != 0
-            if @@service_check && sockopt.int == Errno::ECONNREFUSED::Errno
+          if resp.nil? # Assume ECONNREFUSED if nil
+            if @@service_check
               bool = true
             else
               bool = false
-              @exception = SystemCallError.new(sockopt.int)
+              @exception = Errno::ECONNREFUSED
             end
           else
+            sockopt = sock.getsockopt(Socket::SOL_SOCKET, Socket::SO_ERROR)
+
+            if sockopt.int != 0
+              if @@service_check && sockopt.int == Errno::ECONNREFUSED::Errno
+                bool = true
+              else
+                bool = false
+                @exception = SystemCallError.new(sockopt.int)
+              end
+            else
+              bool = true
+            end
+          end
+        rescue SystemCallError, IOError => err
+          # JRuby raises directly out of IO.select when the connection
+          # is refused, instead of surfacing it via SO_ERROR like MRI does.
+          if @@service_check && err.is_a?(Errno::ECONNREFUSED)
             bool = true
+          else
+            bool = false
+            @exception = err
           end
         end
       ensure
-        sock.close if sock
+        # JRuby invalidates the socket's file descriptor as a side effect
+        # of the IO.select error above, so a subsequent close raises EBADF.
+        begin
+          sock.close if sock
+        rescue Errno::EBADF, IOError
+        end
       end
 
       # There is no duration if the ping failed

data/lib/net/ping/udp.rb

@@ -85,12 +85,33 @@ module Net
 
       start_time = Time.now
 
+      # Process.clock_gettime(Process::CLOCK_MONOTONIC), rather than
+      # Time.now, so a wall-clock adjustment mid-ping can't shorten or
+      # extend the deadline. Matches Timeout.timeout's own treatment of
+      # nil/0 as "no timeout".
+      if @timeout && !@timeout.zero?
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + @timeout
+      end
+
       begin
-        Timeout.timeout(@timeout){
-          udp.connect(host, @port)
-          udp.send(@data, 0)
-          array = udp.recvfrom(MAX_DATA)
-        }
+        udp.connect(host, @port)
+        udp.send(@data, 0)
+
+        # Timeout.timeout relies on interrupting the blocking recvfrom
+        # call, which JRuby does not honor. Wait for readability with
+        # select instead, which enforces the timeout at the OS level.
+        # The remaining time (rather than the full @timeout) is used so
+        # that time already spent on connect/send still counts against
+        # the deadline.
+        if deadline
+          remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          raise Timeout::Error if remaining <= 0
+          raise Timeout::Error unless select([udp], nil, nil, remaining)
+        else
+          select([udp])
+        end
+
+        array = udp.recvfrom(MAX_DATA)
       rescue Errno::ECONNREFUSED, Errno::ECONNRESET => err
         if @@service_check
           @exception = err

data/lib/net/ping/version.rb

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

data/lib/net/ping/wmi.rb

@@ -1,5 +1,12 @@
 require File.join(File.dirname(__FILE__), 'ping')
-require 'win32ole'
+
+# win32ole's C extension does not build on JRuby, so use the pure-Ruby
+# win32ole-ffi gem there instead.
+if RUBY_ENGINE == 'jruby'
+   require 'win32ole/ffi'
+else
+   require 'win32ole'
+end
 
 # The Net module serves as a namespace only.
 #

data/lib/net/ping.rb

@@ -20,5 +20,10 @@ rescue Errno::ENOENT
 end
 
 if File::ALT_SEPARATOR
-  require_relative 'ping/wmi'
+  begin
+    require_relative 'ping/wmi'
+  rescue LoadError => err
+    gem_name = RUBY_ENGINE == 'jruby' ? 'win32ole-ffi' : 'win32ole'
+    warn "Net::Ping::WMI is unavailable (#{err.message}). Run `gem install #{gem_name}` to enable it."
+  end
 end

data/net-ping.gemspec

@@ -22,13 +22,12 @@ Gem::Specification.new do |spec|
 
   spec.extra_rdoc_files  = ['README.md', 'CHANGES', 'doc/ping.txt']
 
-  # The TCP Ping class requires this for non-blocking sockets.
-  spec.required_ruby_version = ">= 1.9.3"
+  # Matches the lowest Ruby version covered by CI.
+  spec.required_ruby_version = ">= 2.7"
 
   spec.add_development_dependency('test-unit', '>= 0')
   spec.add_development_dependency('webmock', '>= 0')
   spec.add_development_dependency('rake', '>= 0')
-  spec.add_development_dependency('pry-byebug', '>= 0')
 
   spec.description = <<-EOF
     The net-ping library provides a ping interface for Ruby. It includes

data/sig/net/ping/external.rbs

@@ -0,0 +1,13 @@
+module Net
+  class Ping
+    class External < Ping
+      def ping: (?String? host, ?Integer count, ?Numeric interval, ?Numeric timeout) -> bool
+
+      def ping6: (?String? host, ?Integer count, ?Numeric interval, ?Numeric timeout) -> bool
+
+      alias ping? ping
+
+      alias pingecho ping
+    end
+  end
+end

data/sig/net/ping/http.rbs

@@ -0,0 +1,41 @@
+module Net
+  class Ping
+    class HTTP < Ping
+      attr_accessor follow_redirect: bool
+
+      attr_accessor redirect_limit: Integer
+
+      attr_accessor user_agent: String?
+
+      attr_accessor ssl_verify_mode: Integer
+
+      attr_accessor get_request: bool
+
+      attr_accessor proxied: bool?
+
+      attr_reader code: String?
+
+      # Narrower than the inherited `(Integer | String)?`: `ping` calls `port.to_i`
+      # on this value (lib/net/ping/http.rb:89-90), so a service-name string such as
+      # "https" silently becomes port 0 instead of being resolved, unlike TCP/UDP/ICMP
+      # which pass the port through to socket APIs that resolve service names.
+      attr_accessor port: Integer?
+
+      def initialize: (?String? uri, ?Integer? port, ?Numeric? timeout) ?{ (self) -> void } -> void
+
+      def ping: (?String? host) -> bool
+
+      alias follow_redirect? follow_redirect
+
+      alias uri host
+
+      alias uri= host=
+
+      private
+
+      def redirect?: (Net::HTTPResponse? response) -> bool?
+
+      def do_ping: (URI::Generic uri, Integer? port) -> Net::HTTPResponse?
+    end
+  end
+end

data/sig/net/ping/icmp.rbs

@@ -0,0 +1,28 @@
+module Net
+  class Ping
+    class ICMP < Ping
+      ICMP_ECHOREPLY: Integer
+
+      ICMP_ECHO: Integer
+
+      ICMP_SUBCODE: Integer
+
+      attr_reader data_size: Integer
+
+      def data_size=: (Integer size) -> Integer
+
+      def bind: (String host, ?Integer port) -> Integer
+
+      def ping: (?String? host) -> (Float | false | nil)
+
+      # Always raises NoMethodError: `undef_method :port=` in lib/net/ping/icmp.rb
+      # removes the writer inherited from Ping. RBS has no syntax to un-declare an
+      # inherited method, so this override documents the call as unreachable.
+      def port=: ((Integer | String)?) -> bot
+
+      private
+
+      def checksum: (String msg) -> Integer
+    end
+  end
+end

data/sig/net/ping/ping.rbs

@@ -0,0 +1,25 @@
+module Net
+  class Ping
+    attr_accessor host: String?
+
+    attr_accessor port: (Integer | String)?
+
+    attr_accessor timeout: Numeric?
+
+    attr_reader exception: (Exception | String | singleton(Errno::ECONNREFUSED))?
+
+    attr_reader warning: String?
+
+    attr_reader duration: Float?
+
+    def initialize: (?String? host, ?(Integer | String)? port, ?Numeric? timeout) ?{ (self) -> void } -> void
+
+    def ping: (?String? host) -> void
+
+    def ping6: (?String? host) -> void
+
+    def ping?: (?String? host) -> bool
+
+    alias pingecho ping
+  end
+end

data/sig/net/ping/tcp.rbs

@@ -0,0 +1,19 @@
+module Net
+  class Ping
+    class TCP < Ping
+      def self.service_check: () -> bool
+
+      def self.service_check=: (bool) -> bool
+
+      def ping: (?String? host) -> (Float | false | nil)
+
+      def self.econnrefused: () -> bool
+
+      def self.econnrefused=: (bool) -> bool
+
+      def self.ecr: () -> bool
+
+      def self.ecr=: (bool) -> bool
+    end
+  end
+end

data/sig/net/ping/udp.rbs

@@ -0,0 +1,19 @@
+module Net
+  class Ping
+    class UDP < Ping
+      MAX_DATA: Integer
+
+      attr_reader data: String
+
+      def self.service_check: () -> bool
+
+      def self.service_check=: (bool) -> bool
+
+      def data=: (String string) -> String
+
+      def bind: (String host, Integer port) -> Integer
+
+      def ping: (?String? host) -> bool
+    end
+  end
+end

data/sig/net/ping/version.rbs

@@ -0,0 +1,5 @@
+module Net
+  class Ping
+    VERSION: String
+  end
+end

data/sig/net/ping/wmi.rbs

@@ -0,0 +1,63 @@
+class Struct::PingStatus < Struct[untyped]
+  attr_accessor address: untyped
+
+  attr_accessor buffer_size: untyped
+
+  attr_accessor no_fragmentation: untyped
+
+  attr_accessor primary_address_resolution_status: untyped
+
+  attr_accessor protocol_address: untyped
+
+  attr_accessor protocol_address_resolved: untyped
+
+  attr_accessor record_route: untyped
+
+  attr_accessor reply_inconsistency: untyped
+
+  attr_accessor reply_size: untyped
+
+  attr_accessor resolve_address_names: untyped
+
+  attr_accessor response_time: untyped
+
+  attr_accessor response_time_to_live: untyped
+
+  attr_accessor route_record: untyped
+
+  attr_accessor route_record_resolved: untyped
+
+  attr_accessor source_route: untyped
+
+  attr_accessor source_route_type: untyped
+
+  attr_accessor status_code: untyped
+
+  attr_accessor timeout: untyped
+
+  attr_accessor timestamp_record: untyped
+
+  attr_accessor timestamp_record_address: untyped
+
+  attr_accessor timestamp_record_address_resolved: untyped
+
+  attr_accessor timestamp_route: untyped
+
+  attr_accessor time_to_live: untyped
+
+  attr_accessor type_of_service: untyped
+end
+
+module Net
+  class Ping
+    class WMI < Ping
+      # `PingStatus = Struct.new('PingStatus', ...)` both creates ::Struct::PingStatus
+      # (from the string name) and assigns it to this constant in the enclosing scope.
+      PingStatus: singleton(::Struct::PingStatus)
+
+      def ping: (?String? host, ?Hash[Symbol | String, untyped] options) -> Struct::PingStatus
+
+      def ping?: (?String? host, ?Hash[Symbol | String, untyped] options) -> bool
+    end
+  end
+end

data/test/test_net_ping.rb

@@ -7,6 +7,7 @@
 require 'test_net_ping_external'
 require 'test_net_ping_gem_packaging'
 require 'test_net_ping_http'
+require 'test_net_ping_lib'
 require 'test_net_ping_tcp'
 require 'test_net_ping_udp'
 

data/test/test_net_ping_lib.rb

@@ -0,0 +1,28 @@
+#######################################################################
+# test_net_ping_lib.rb
+#
+# Test case for the lib/net/ping.rb aggregator require.
+#######################################################################
+require 'open3'
+require 'test-unit'
+
+class TestNetPingLib < Test::Unit::TestCase
+  ROOT = File.expand_path('..', __dir__)
+
+  def test_require_tolerates_a_missing_wmi_dependency_on_windows
+    omit_if(File::ALT_SEPARATOR, 'win32ole/win32ole-ffi may genuinely be installed here')
+
+    script = <<~'RUBY'
+      File.send(:remove_const, :ALT_SEPARATOR)
+      File.const_set(:ALT_SEPARATOR, '\\')
+      require 'net/ping'
+      puts defined?(Net::Ping::WMI).inspect
+    RUBY
+
+    out, err, status = Open3.capture3(Gem.ruby, '-Ilib', '-e', script, chdir: ROOT)
+
+    assert_true(status.success?, err)
+    assert_equal('nil', out.strip)
+    assert_match(/win32ole/, err)
+  end
+end

data/test/test_net_ping_udp.rb

@@ -70,6 +70,33 @@ class TC_Net_Ping_UDP < Test::Unit::TestCase
     assert_equal(5, @udp.timeout)
   end
 
+  test "a nil timeout disables the timeout instead of raising" do
+    @udp.timeout = nil
+    assert_nothing_raised{ @udp.ping? }
+  end
+
+  test "a zero timeout disables the timeout instead of failing immediately" do
+    @udp.timeout = 0
+    assert_true(@udp.ping?)
+  end
+
+  test "ping times out when the remote port never replies" do
+    silent_peer = UDPSocket.new
+    silent_peer.bind('127.0.0.1', 0)
+    port = silent_peer.addr[1]
+
+    udp = Net::Ping::UDP.new('127.0.0.1', port, 1)
+    start = Time.now
+    assert_false(udp.ping?)
+    elapsed = Time.now - start
+
+    assert_true(elapsed < 2.5, "Actual elapsed: #{elapsed}")
+    assert_kind_of(Timeout::Error, udp.exception)
+    assert_nil(udp.duration)
+  ensure
+    silent_peer.close if silent_peer
+  end
+
   test "exception basic functionality" do
     assert_respond_to(@udp, :exception)
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: net-ping
 version: !ruby/object:Gem::Version
-  version: 2.2.0
+  version: 3.0.0
 platform: ruby
 authors:
 - Chris Chernesky
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-22 00:00:00.000000000 Z
+date: 2026-11-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: test-unit
@@ -52,20 +52,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-- !ruby/object:Gem::Dependency
-  name: pry-byebug
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
 description: |2
       The net-ping library provides a ping interface for Ruby. It includes
       separate TCP, HTTP, LDAP, ICMP, UDP, WMI (for Windows) and external ping
@@ -102,11 +88,20 @@ files:
 - net-ping-universal-linux.gemspec
 - net-ping-universal-mingw-ucrt.gemspec
 - net-ping.gemspec
+- sig/net/ping/external.rbs
+- sig/net/ping/http.rbs
+- sig/net/ping/icmp.rbs
+- sig/net/ping/ping.rbs
+- sig/net/ping/tcp.rbs
+- sig/net/ping/udp.rbs
+- sig/net/ping/version.rbs
+- sig/net/ping/wmi.rbs
 - test/test_net_ping.rb
 - test/test_net_ping_external.rb
 - test/test_net_ping_gem_packaging.rb
 - test/test_net_ping_http.rb
 - test/test_net_ping_icmp.rb
+- test/test_net_ping_lib.rb
 - test/test_net_ping_tcp.rb
 - test/test_net_ping_udp.rb
 - test/test_net_ping_wmi.rb
@@ -127,7 +122,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 1.9.3
+      version: '2.7'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="