net-ping 2.1.0-universal-linux

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

@@ -0,0 +1,317 @@
+# Platform-specific Gem Dependencies Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Build and validate RubyGems artifacts that install `cap2` on Linux and `win32-security` on current Windows RubyInstaller systems.
+
+**Architecture:** Keep `net-ping.gemspec` OS-independent and create two small gemspec overlays for Linux and `mingw-ucrt`. Centralize artifact generation and metadata validation in the Rake gem namespace, then run that validation in the existing Linux/Windows CI matrix.
+
+**Tech Stack:** Ruby, RubyGems (`Gem::Specification`, `Gem::Package`, `Gem::Platform`), Rake, test-unit, GitHub Actions.
+
+## Global Constraints
+
+- Produce exactly three same-version `net-ping` gems: `ruby`, `universal-linux`, and `universal-mingw-ucrt`.
+- `universal-linux` must add `cap2 (>= 0.2.2)`; `universal-mingw-ucrt` must add `win32-security (>= 0.2.0)`.
+- The Ruby gem must not contain either OS-specific runtime dependency.
+- Support `mingw-ucrt` only; legacy `mingw32` is out of scope.
+- CI builds and validates artifacts but never publishes them.
+- Do not create git commits for this work.
+
+---
+
+## File Structure
+
+| File | Responsibility |
+| --- | --- |
+| `net-ping.gemspec` | Define the OS-independent Ruby artifact and common metadata. |
+| `net-ping-universal-linux.gemspec` | Overlay `universal-linux` and the `cap2` runtime dependency. |
+| `net-ping-universal-mingw-ucrt.gemspec` | Overlay `universal-mingw-ucrt` and the `win32-security` runtime dependency. |
+| `Rakefile` | Build, inspect, and locally install the platform-appropriate artifact. |
+| `test/test_net_ping_gem_packaging.rb` | Build temporary artifacts and assert their platform/dependency metadata. |
+| `test/test_net_ping.rb` | Load the packaging test in the aggregate suite. |
+| `.github/workflows/test.yml` | Run gem artifact checks on Linux and Windows. |
+| `README.md` | Explain automatic platform-specific dependency installation. |
+| `CHANGES` | Record the metadata correction for the next release. |
+
+### Task 1: Define and test platform gem specifications
+
+**Files:**
+- Create: `net-ping-universal-linux.gemspec`
+- Create: `net-ping-universal-mingw-ucrt.gemspec`
+- Create: `test/test_net_ping_gem_packaging.rb`
+- Modify: `net-ping.gemspec:1-40`
+- Modify: `test/test_net_ping.rb`
+
+**Interfaces:**
+- Consumes: `net-ping.gemspec`, which supplies the shared `Gem::Specification`.
+- Produces: three loadable gemspecs whose `platform` and `runtime_dependencies` describe their target platform.
+
+- [ ] **Step 1: Write the failing package-metadata test**
+
+Create `test/test_net_ping_gem_packaging.rb`. Load every gemspec before building any artifact so `spec.files` cannot include an artifact created for an earlier specification. Build the loaded specifications into temporary `.gem` files, open each using `Gem::Package`, and assert the platform and runtime dependencies:
+
+```ruby
+require 'rubygems/package'
+require 'test/unit'
+
+class TestNetPingGemPackaging < Test::Unit::TestCase
+  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'}
+    ]
+  }.freeze
+
+  def setup
+    @specifications = EXPECTATIONS.keys.map do |path|
+      [path, Gem::Specification.load(path)]
+    end
+    @gem_files = @specifications.map { |_, spec| Gem::Package.build(spec) }
+  end
+
+  def teardown
+    @gem_files.each { |path| File.delete(path) if File.exist?(path) }
+  end
+
+  def test_platforms_and_runtime_dependencies
+    @specifications.each do |path, spec|
+      expected_platform, expected_dependencies = EXPECTATIONS.fetch(path)
+      packaged_spec = Gem::Package.new(spec.file_name).spec
+      dependencies = packaged_spec.runtime_dependencies.to_h do |dependency|
+        [dependency.name, dependency.requirement.to_s]
+      end
+
+      assert_equal(expected_platform, packaged_spec.platform.to_s, path)
+      assert_equal(expected_dependencies, dependencies, path)
+    end
+  end
+end
+```
+
+Add `require 'test_net_ping_gem_packaging'` to `test/test_net_ping.rb`.
+
+- [ ] **Step 2: Run the new test to verify it fails**
+
+Run:
+
+```sh
+bundle exec ruby -Itest test/test_net_ping_gem_packaging.rb
+```
+
+Expected: failure because the Linux and Windows overlay gemspec files do not exist.
+
+- [ ] **Step 3: Make the base gemspec OS-independent and add overlays**
+
+Remove the `File::ALT_SEPARATOR`, `RbConfig`, and `RUBY_PLATFORM` conditional runtime dependency logic from `net-ping.gemspec`; leave only shared metadata and development dependencies.
+
+Create `net-ping-universal-linux.gemspec`:
+
+```ruby
+spec = Gem::Specification.load('net-ping.gemspec')
+spec.platform = Gem::Platform.new(['universal', 'linux'])
+spec.add_dependency('cap2', '>= 0.2.2')
+spec
+```
+
+Create `net-ping-universal-mingw-ucrt.gemspec`:
+
+```ruby
+spec = Gem::Specification.load('net-ping.gemspec')
+spec.platform = Gem::Platform.new(['universal', 'mingw-ucrt'])
+spec.add_dependency('win32-security', '>= 0.2.0')
+spec
+```
+
+Use the project’s existing block-style `Gem::Specification.new` format for the base gemspec. Verify the installed RubyGems version accepts the two platform strings with `Gem::Platform.new`.
+
+- [ ] **Step 4: Run the package-metadata test to verify it passes**
+
+Run:
+
+```sh
+bundle exec ruby -Itest test/test_net_ping_gem_packaging.rb
+```
+
+Expected: PASS; all three artifacts have the expected platform and exactly the expected runtime dependencies.
+
+- [ ] **Step 5: Run the aggregate test suite**
+
+Run:
+
+```sh
+bundle exec rake test
+```
+
+Expected: PASS.
+
+### Task 2: Make Rake build, validate, and install platform artifacts deterministically
+
+**Files:**
+- Modify: `Rakefile:6-29`
+
+**Interfaces:**
+- Consumes: the three gemspec paths from Task 1.
+- Produces: `gem:create` builds all artifacts; `gem:check` aborts on invalid artifact metadata; `gem:install` installs the local platform’s specific artifact or the Ruby fallback.
+
+- [ ] **Step 1: Add a failing artifact-validation command**
+
+Add `gem:check` to the `gem` namespace. It must load the three expected gem files with `Gem::Package`, map each runtime dependency to `name => requirement.to_s`, and abort if the platform or dependency hash differs from:
+
+```ruby
+{
+  'ruby' => {},
+  'universal-linux' => {'cap2' => '>= 0.2.2'},
+  'universal-mingw-ucrt' => {'win32-security' => '>= 0.2.0'}
+}
+```
+
+Run it before changing `gem:create`:
+
+```sh
+bundle exec rake clean gem:create gem:check
+```
+
+Expected: FAIL because `gem:create` still builds only one artifact.
+
+- [ ] **Step 2: Implement deterministic specification loading and artifact creation**
+
+Define the shared list once in `Rakefile`:
+
+```ruby
+GEMSPEC_FILES = %w[
+  net-ping.gemspec
+  net-ping-universal-linux.gemspec
+  net-ping-universal-mingw-ucrt.gemspec
+].freeze
+```
+
+Update `gem:create` to load all files before it builds any artifact:
+
+```ruby
+specifications = GEMSPEC_FILES.map { |path| Gem::Specification.load(path) }
+specifications.each { |spec| Gem::Package.build(spec) }
+```
+
+Retain the existing RubyGems pre-2.0 builder branch if support for it is still required. In either branch, load every specification before beginning the build loop.
+
+Implement `gem:check` using `Gem::Package.new(file).spec`; use `abort` with the artifact filename and expected/actual values when a check fails.
+
+Update `gem:install` to load the same specification list and select:
+
+```ruby
+specific = specifications.find do |spec|
+  spec.platform != Gem::Platform::RUBY && Gem::Platform.installable?(spec)
+end
+spec = specific || specifications.find { |item| item.platform == Gem::Platform::RUBY }
+```
+
+Install `spec.file_name`, not `Dir['*.gem'].first`; abort when no Ruby fallback specification is found.
+
+- [ ] **Step 3: Run artifact validation to verify it passes**
+
+Run:
+
+```sh
+bundle exec rake gem:create gem:check
+```
+
+Expected: PASS and creation of `net-ping-<version>.gem`,
+`net-ping-<version>-universal-linux.gem`, and
+`net-ping-<version>-universal-mingw-ucrt.gem`.
+
+- [ ] **Step 4: Verify local artifact selection**
+
+Run:
+
+```sh
+bundle exec rake gem:install
+gem specification net-ping platform
+```
+
+Expected on Linux: `universal-linux`; on Windows: `universal-mingw-ucrt`; on
+other platforms: `ruby`.
+
+- [ ] **Step 5: Re-run tests**
+
+Run:
+
+```sh
+bundle exec rake test
+```
+
+Expected: PASS.
+
+### Task 3: Enforce packaging in CI and document the behavior
+
+**Files:**
+- Modify: `.github/workflows/test.yml:19-28`
+- Modify: `README.md:4-15`
+- Modify: `CHANGES:1-13`
+
+**Interfaces:**
+- Consumes: `gem:create` and `gem:check` from Task 2.
+- Produces: CI verification on both matrix operating systems and accurate end-user dependency documentation.
+
+- [ ] **Step 1: Add the CI packaging verification step**
+
+After the existing `bundle exec rake test` step, add:
+
+```yaml
+      - run: bundle exec rake gem:create gem:check
+```
+
+Do not add RubyGems credentials, publishing actions, or tag triggers.
+
+- [ ] **Step 2: Document platform-specific dependency resolution**
+
+Replace the prerequisite list’s unconditional `win32-security (MS Windows
+only)` wording with text that states RubyGems installs `win32-security` from
+the Windows artifact and `cap2` from the Linux artifact when installing
+`net-ping`. Keep the installation command `gem install net-ping`.
+
+At the beginning of `CHANGES`, add:
+
+```text
+== Next Release
+* Publish platform-specific gem metadata so Linux installs cap2 and current
+  Windows RubyInstaller installs win32-security for ICMP support.
+```
+
+- [ ] **Step 3: Run targeted packaging and full test verification**
+
+Run:
+
+```sh
+bundle exec rake gem:create gem:check
+bundle exec rake test
+```
+
+Expected: both commands PASS.
+
+- [ ] **Step 4: Inspect the final diff without committing**
+
+Run:
+
+```sh
+git diff --check
+git diff -- net-ping.gemspec net-ping-universal-linux.gemspec \
+  net-ping-universal-mingw-ucrt.gemspec Rakefile \
+  test/test_net_ping_gem_packaging.rb test/test_net_ping.rb \
+  .github/workflows/test.yml README.md CHANGES
+```
+
+Expected: only the planned packaging, CI, test, and documentation changes;
+no whitespace errors and no git commit.
+
+## Plan Self-Review
+
+- **Spec coverage:** Task 1 creates the three required artifacts and assigns
+  their dependencies; Task 2 validates metadata and selects a local artifact;
+  Task 3 runs validation in CI and documents the behavior. CI publishing,
+  legacy `mingw32`, and runtime protocol changes are excluded.
+- **Placeholder scan:** No unresolved item, unspecified test, or ambiguous
+  implementation step remains.
+- **Consistency:** The gemspec filenames, platform names, dependency
+  versions, and Rake task names are identical across all tasks.

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/examples/example_pingexternal.rb

@@ -0,0 +1,16 @@
+########################################################################
+# example_pingexternal.rb
+#
+# A short sample program demonstrating an external ping. You can run
+# this program via the example:external task. Modify as you see fit.
+########################################################################
+require 'net/ping'
+
+good = 'www.rubyforge.org'
+bad  = 'foo.bar.baz'
+
+p1 = Net::Ping::External.new(good)
+p p1.ping?
+
+p2 = Net::Ping::External.new(bad)
+p p2.ping?

data/examples/example_pinghttp.rb

@@ -0,0 +1,22 @@
+########################################################################
+# example_pinghttp.rb
+#
+# A short sample program demonstrating an http ping. You can run
+# this program via the example:http task. Modify as you see fit.
+########################################################################
+require 'net/ping'
+
+good = 'http://www.google.com/index.html'
+bad  = 'http://www.ruby-lang.org/index.html'
+
+puts "== Good ping, no redirect"
+
+p1 = Net::Ping::HTTP.new(good)
+p p1.ping?
+
+puts "== Bad ping"
+
+p2 = Net::Ping::HTTP.new(bad)
+p p2.ping?
+p p2.warning
+p p2.exception

data/examples/example_pingtcp.rb

@@ -0,0 +1,16 @@
+########################################################################
+# example_pingtcp.rb
+#
+# A short sample program demonstrating a tcp ping. You can run
+# this program via the example:tcp task. Modify as you see fit.
+########################################################################
+require 'net/ping'
+
+good = 'www.google.com'
+bad  = 'foo.bar.baz'
+
+p1 = Net::Ping::TCP.new(good, 'http')
+p p1.ping?
+
+p2 = Net::Ping::TCP.new(bad)
+p p2.ping?

data/examples/example_pingudp.rb

@@ -0,0 +1,12 @@
+########################################################################
+# example_pingudp.rb
+#
+# A short sample program demonstrating a UDP ping. You can run
+# this program via the example:udp task. Modify as you see fit.
+########################################################################
+require 'net/ping'
+
+host = 'www.google.com'
+
+u = Net::Ping::UDP.new(host)
+p u.ping?

data/lib/net/ping/external.rb

@@ -0,0 +1,185 @@
+require 'open3'
+require 'rbconfig'
+
+require File.join(File.dirname(__FILE__), 'ping')
+
+# The Net module serves as a namespace only.
+module Net
+
+  # The Ping::External class encapsulates methods for external (system) pings.
+  class Ping::External < Ping
+    # Pings the host using your system's ping utility and checks for any
+    # errors or warnings. Returns true if successful, or false if not.
+    #
+    # If the ping failed then the Ping::External#exception method should
+    # contain a string indicating what went wrong. If the ping succeeded then
+    # the Ping::External#warning method may or may not contain a value.
+    #
+    def ping(host = @host, count = 1, interval = 1, timeout = @timeout)
+
+      raise "Count must be an integer" unless count.is_a? Integer
+      raise "Timeout must be a number" unless timeout.is_a? Numeric
+
+      unless interval.is_a?(Numeric) && interval >= 0.2
+        raise "Interval must be a decimal greater than or equal to 0.2"
+      end
+
+      super(host)
+
+      pcmd = ['ping']
+      bool = false
+
+      case RbConfig::CONFIG['host_os']
+        when /linux/i
+          pcmd += ['-c', count.to_s, '-W', timeout.to_s, host]
+          pcmd += ['-i', interval.to_s] unless RbConfig::CONFIG['busybox']
+        when /aix/i
+          pcmd += ['-c', count.to_s, '-w', timeout.to_s, host]
+        when /bsd|osx|mach|darwin/i
+          pcmd += ['-c', count.to_s, '-t', timeout.to_s, host]
+        when /solaris|sunos/i
+          pcmd += [host, timeout.to_s]
+        when /hpux/i
+          pcmd += [host, "-n#{count.to_s}", '-m', timeout.to_s]
+        when /win32|windows|msdos|mswin|cygwin|mingw/i
+          pcmd += ['-n', count.to_s, '-w', (timeout * 1000).to_s, host]
+        else
+          pcmd += [host]
+      end
+
+      start_time = Time.now
+
+      begin
+        err = nil
+
+        Open3.popen3(*pcmd) do |stdin, stdout, stderr, thread|
+          stdin.close
+          err = stderr.gets # Can't chomp yet, might be nil
+
+          case thread.value.exitstatus
+            when 0
+              info = stdout.read
+              if info =~ /unreachable/ix # Windows
+                bool = false
+                @exception = "host unreachable"
+              else
+                bool = true  # Success, at least one response.
+              end
+
+              if err && (err =~ /warning/i)
+                @warning = err.chomp
+              end
+            when 2
+              bool = false # Transmission successful, no response.
+              @exception = err.chomp if err
+            else
+              bool = false # An error occurred
+              if err
+                @exception = err.chomp
+              else
+                stdout.each_line do |line|
+                  if line =~ /(timed out|could not find host|packet loss)/i
+                    @exception = line.chomp
+                    break
+                  end
+                end
+              end
+          end
+        end
+      rescue Exception => error
+        @exception = error.message
+      end
+
+      # There is no duration if the ping failed
+      @duration = Time.now - start_time if bool
+
+      bool
+    end
+
+    def ping6(host = @host, count = 1, interval = 1, timeout = @timeout)
+
+      raise "Count must be an integer" unless count.is_a? Integer
+      raise "Timeout must be a number" unless timeout.is_a? Numeric
+
+      unless interval.is_a?(Numeric) && interval >= 0.2
+        raise "Interval must be a decimal greater than or equal to 0.2"
+      end
+
+      super(host)
+
+      pcmd = ['ping6']
+      bool = false
+
+      case RbConfig::CONFIG['host_os']
+        when /linux/i
+          pcmd += ['-c', count.to_s, '-W', timeout.to_s, host]
+          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, '-i', interval.to_s, host]
+        when /solaris|sunos/i
+          pcmd += [host, timeout.to_s]
+        when /hpux/i
+          pcmd += [host, "-n#{count.to_s}", '-m', timeout.to_s]
+        when /win32|windows|msdos|mswin|cygwin|mingw/i
+          pcmd += ['-n', count.to_s, '-w', (timeout * 1000).to_s, host]
+        else
+          pcmd += [host]
+      end
+
+      start_time = Time.now
+
+      begin
+        err = nil
+
+        Open3.popen3(*pcmd) do |stdin, stdout, stderr, thread|
+          stdin.close
+          err = stderr.gets # Can't chomp yet, might be nil
+
+          case thread.value.exitstatus
+            when 0
+              info = stdout.read
+              if info =~ /unreachable/ix # Windows
+                bool = false
+                @exception = "host unreachable"
+              else
+                bool = true  # Success, at least one response.
+              end
+
+              if err && (err =~ /warning/i)
+                @warning = err.chomp
+              end
+            when 2
+              bool = false # Transmission successful, no response.
+              @exception = err.chomp if err
+            else
+              bool = false # An error occurred
+              if err
+                @exception = err.chomp
+              else
+                stdout.each_line do |line|
+                  if line =~ /(timed out|could not find host|packet loss)/i
+                    @exception = line.chomp
+                    break
+                  end
+                end
+              end
+          end
+        end
+      rescue Exception => error
+        @exception = error.message
+      end
+
+      # There is no duration if the ping failed
+      @duration = Time.now - start_time if bool
+
+      bool
+    end
+
+    alias ping? ping
+    alias pingecho ping
+  end
+end