io-metrics 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ff485ebbe44dc9bae2117fa771ed89e7b2e42e3270d93094bae2fa4808405a5d
-  data.tar.gz: e724a731428b1c7d5219f6abcb518b99cddd572efcf0d9de02eff1d30f90400e
+  metadata.gz: d3e42882ce221e2e9f10808ed4de4ea6a72b3490662a014727e40b49fe8826ab
+  data.tar.gz: da5595f41dfe59f91dc3355ebe6538bac4ca0bc70e1c1040c6cc6e911c977498
 SHA512:
-  metadata.gz: 27ef4c0c0f75b3933bbd7cf6815997bf62d3d3cc05c6dbe0ca9e75a3db143f6fb122153d4d7b967fd2b04781b0c12dc1158a7998178cee6bc954d7c7e576a3b6
-  data.tar.gz: c1bfed9052fb9fbf92f25bf9952eb83d3dc0759bb55746cca68068942d772a145c43659888045315b58ba9b7c4b4209ce196889b21d0c0d17c4b7cd6cacff5b4
+  metadata.gz: cee9a635c1df4b7bfc18497e835add923739f5656737126bdc86cae1bca17a8074925243240eed1b802f741e8956d63b18c434af7f8d29853e3750aa3f55b5f7
+  data.tar.gz: 512a4e960252f726b0a50348d7ceab9f6bbc13247aab649f17a48d9d3d1b58cf489141b9095b24cebabd0d39546196a5bf454e3e8f51389b652b485e16218a6b

data/lib/io/metrics/listener/darwin.rb

@@ -3,6 +3,8 @@
 # Released under the MIT License.
 # Copyright, 2026, by Samuel Williams.
 
+require "socket"
+
 class IO
 	module Metrics
 		# Darwin (macOS) implementation of listener statistics using netstat -L.
@@ -14,31 +16,43 @@ class IO
 				File.executable?(NETSTAT)
 			end
 			
-			# Parse an address from netstat format to "ip:port" format.
+			# Parse an address from netstat format to Addrinfo (TCP, numeric port).
 			# @parameter address [String] Address string from netstat, e.g. "127.0.0.1.50876" or "*.63703".
-			# @returns [String] Address in "ip:port" format, e.g. "127.0.0.1:50876" or "0.0.0.0:63703".
+			# @returns [Addrinfo | Nil] Addrinfo for the listener, or nil if the line cannot be parsed.
 			def self.parse_address(address)
 				# Handle wildcard addresses: *.port -> 0.0.0.0:port
 				if address.start_with?("*.")
-					port = address[2..-1]
-					return "0.0.0.0:#{port}"
+					port = address[2..-1].to_i
+					return Addrinfo.tcp("0.0.0.0", port)
 				end
 				
 				# Handle IPv4 addresses: ip.port -> ip:port
 				if address =~ /^([0-9.]+)\.(\d+)$/
 					ip = $1
-					port = $2
-					return "#{ip}:#{port}"
+					port = $2.to_i
+					return Addrinfo.tcp(ip, port)
 				end
 				
-				# Handle IPv6 addresses (if present in future)
-				# For now, return as-is
-				return address
+				# Handle IPv6 or other formats: best-effort via Addrinfo.parse
+				begin
+					Addrinfo.parse(address)
+				rescue ArgumentError, SocketError
+					nil
+				end
+			end
+			
+			# Build a stable string key for TCP listener filter matching (same style as Linux / user filters).
+			def self.tcp_listener_key(addrinfo)
+				if addrinfo.ipv6?
+					"[#{addrinfo.ip_address}]:#{addrinfo.ip_port}"
+				else
+					"#{addrinfo.ip_address}:#{addrinfo.ip_port}"
+				end
 			end
 			
 			# Parse netstat -L output and extract listener statistics.
 			# @parameter addresses [Array(String) | Nil] Optional filter for specific addresses.
-			# @returns [Hash(String, Listener)] Hash mapping "ip:port" to Listener.
+			# @returns [Array(Listener)] One entry per listening socket reported by netstat.
 			def self.capture_tcp(addresses = nil)
 				listeners = {}
 				address_filter = addresses ? addresses.map{|address| address.downcase}.to_set : nil
@@ -62,36 +76,32 @@ class IO
 							# incomplete_queue_length = $2.to_i  # incomplete connections (SYN_RECV)
 							# maximum_queue_length = $3.to_i  # maximum queue size
 							
-							# Parse address
-							address = parse_address(local_address_raw)
+							addrinfo = parse_address(local_address_raw)
+							next unless addrinfo
 							
+							key = tcp_listener_key(addrinfo)
 							# Apply filter if specified
-							next if address_filter && !address_filter.include?(address)
+							next if address_filter && !address_filter.include?(key.downcase)
 							
-							listeners[address] ||= Listener.zero
-							listeners[address].queue_size = queue_length
+							listeners[key] ||= Listener.new(addrinfo, 0, 0)
+							listeners[key].queue_size = queue_length
 							# active_connections set to 0 (can't reliably count per listener)
-							listeners[address].active_connections = 0
+							listeners[key].active_connections = 0
 						end
 					end
 				end
 				
-				return listeners
+				return listeners.values
 			rescue Errno::ENOENT, Errno::EACCES
-				return {}
+				return []
 			end
 			
 			# Capture listener listeners for TCP sockets.
 			# @parameter addresses [Array(String) | Nil] TCP address(es) to capture, e.g. ["0.0.0.0:80"]. If nil, captures all.
 			# @parameter paths [Array(String) | Nil] Unix socket path(s) to capture (not supported on Darwin).
-			# @returns [Hash(String, Listener)] Hash mapping addresses to Listener.
+			# @returns [Array(Listener)] TCP listeners from netstat.
 			def self.capture(addresses: nil, paths: nil)
-				listeners = {}
-				
-				# Capture TCP listeners (Unix sockets not supported on Darwin via netstat)
-				listeners.merge!(capture_tcp(addresses))
-				
-				return listeners
+				capture_tcp(addresses)
 			end
 		end
 	end
@@ -109,7 +119,7 @@ if IO::Metrics::Listener::Darwin.supported?
 		# Capture listener listeners for the given address(es).
 		# @parameter addresses [Array(String) | Nil] TCP address(es) to capture, e.g. ["0.0.0.0:80"]. If nil, captures all listening TCP sockets.
 		# @parameter paths [Array(String) | Nil] Unix socket path(s) to capture (not supported on Darwin).
-		# @returns [Hash(String, Listener) | Nil] A hash mapping addresses to Listener, or nil if not supported.
+		# @returns [Array(Listener) | Nil] Captured listeners, or nil if not supported.
 		def capture(**options)
 			IO::Metrics::Listener::Darwin.capture(**options)
 		end

data/lib/io/metrics/listener/linux.rb

@@ -103,7 +103,7 @@ class IO
 			
 			# Find the best matching listener for an ESTABLISHED connection.
 			# @parameter local_address [String] Local address in "ip:port" or "[ipv6]:port" format.
-			# @parameter listeners [Hash(String, Listener)] Hash of listener addresses to Listener objects.
+			# @parameter listeners [Hash(String, Listener)] Internal map from display address string to Listener.
 			# @returns [String | Nil] The address of the matching listener, or nil if no match.
 			def self.find_matching_listener(local_address, listeners)
 				# Try exact match first
@@ -149,8 +149,15 @@ class IO
 			# @parameter file [String] Path to /proc/net/tcp or /proc/net/tcp6.
 			# @parameter addresses [Array(String) | Nil] Optional filter for specific addresses.
 			# @parameter ipv6 [Boolean] Whether parsing IPv6 addresses.
-			# @returns [Hash(String, Listener)] Hash mapping "ip:port" or "[ipv6]:port" to Listener.
+			# @returns [Array(Listener)] One entry per listening socket.
 			def self.capture_tcp_file(file, addresses = nil, ipv6: false)
+				gather_tcp_file(file, addresses, ipv6: ipv6).values
+			rescue Errno::ENOENT, Errno::EACCES
+				return []
+			end
+			
+			# Internal: same as capture_tcp_file but returns a Hash keyed by display address for merging and connection matching.
+			def self.gather_tcp_file(file, addresses = nil, ipv6: false)
 				listeners = {}
 				address_filter = addresses ? addresses.map{|address| address.downcase}.to_set : nil
 				connections = []
@@ -174,7 +181,8 @@ class IO
 						if state == :listen
 							if ipv6
 								local_ip = parse_ipv6(local_ip_hex)
-								local_address = "[#{local_ip}]:#{parse_port(local_port_hex)}"
+								local_port = parse_port(local_port_hex)
+								local_address = "[#{local_ip}]:#{local_port}"
 							else
 								local_ip = parse_ipv4(local_ip_hex)
 								local_port = parse_port(local_port_hex)
@@ -182,9 +190,9 @@ class IO
 							end
 							
 							# Apply filter if specified
-							next if address_filter && !address_filter.include?(local_address)
+							next if address_filter && !address_filter.include?(local_address.downcase)
 							
-							listeners[local_address] ||= Listener.zero
+							listeners[local_address] ||= Listener.new(Addrinfo.tcp(local_ip, local_port), 0, 0)
 							# rx_queue shows number of connections waiting to be accepted
 							listeners[local_address].queue_size = rx_queue_hex.to_i(16)
 							listeners[local_address].active_connections = 0
@@ -218,7 +226,7 @@ class IO
 			# Parse /proc/net/unix and extract listener statistics for Unix domain sockets.
 			# @parameter paths [Array(String) | Nil] Optional filter for specific socket paths.
 			# @parameter file [String] Optional path to Unix socket file (defaults to "/proc/net/unix").
-			# @returns [Hash(String, Listener)] Hash mapping socket path to Listener.
+			# @returns [Array(Listener)] One entry per socket path with any matching activity.
 			def self.capture_unix(paths = nil, file: "/proc/net/unix")
 				listeners = {}
 				path_filter = paths ? paths.to_set : nil
@@ -246,7 +254,7 @@ class IO
 					
 					state = state_hex.to_i(16)
 					
-					listeners[path] ||= Listener.zero
+					listeners[path] ||= Listener.new(Addrinfo.unix(path), 0, 0)
 					
 					case state
 					when SS_CONNECTING # Queued connections
@@ -256,37 +264,37 @@ class IO
 					end
 				end
 				
-				return listeners
+				return listeners.values
 			rescue Errno::ENOENT, Errno::EACCES
-				return {}
+				return []
 			end
 			
 			# Parse /proc/net/tcp and /proc/net/tcp6 and extract listener statistics.
 			# @parameter addresses [Array(String) | Nil] Optional filter for specific addresses.
-			# @returns [Hash(String, Listener)] Hash mapping "ip:port" or "[ipv6]:port" to Listener.
+			# @returns [Array(Listener)] TCP listeners from both stacks.
 			def self.capture_tcp(addresses = nil)
 				listeners = {}
 				
 				# Capture IPv4 listeners and connections
 				if File.readable?("/proc/net/tcp")
-					listeners.merge!(capture_tcp_file("/proc/net/tcp", addresses, ipv6: false))
+					listeners.merge!(gather_tcp_file("/proc/net/tcp", addresses, ipv6: false))
 				end
 				
 				# Capture IPv6 listeners and connections
 				if File.readable?("/proc/net/tcp6")
-					listeners.merge!(capture_tcp_file("/proc/net/tcp6", addresses, ipv6: true))
+					listeners.merge!(gather_tcp_file("/proc/net/tcp6", addresses, ipv6: true))
 				end
 				
-				return listeners
+				return listeners.values
 			end
 			
 			# Capture listener listeners for TCP and/or Unix domain sockets.
 			# @parameter addresses [Array(String) | Nil] TCP address(es) to capture, e.g. ["0.0.0.0:80"]. If nil and paths is nil, captures all. If nil but paths specified, captures none.
 			# @parameter paths [Array(String) | Nil] Unix socket path(s) to capture. If nil and addresses is nil, captures all. If nil but addresses specified, captures none.
 			# @parameter unix_file [String] Optional path to Unix socket file (defaults to "/proc/net/unix").
-			# @returns [Hash(String, Listener)] Hash mapping addresses/paths to Listener.
+			# @returns [Array(Listener)] All matching listeners (TCP and/or Unix).
 			def self.capture(addresses: nil, paths: nil, unix_file: "/proc/net/unix")
-				listeners = {}
+				result = []
 				
 				# If addresses are specified but paths is nil, don't capture Unix sockets
 				# Only capture Unix sockets if paths is explicitly provided or addresses is nil
@@ -294,12 +302,12 @@ class IO
 				unix_paths = paths.nil? && !addresses.nil? ? :skip : paths
 				
 				# Capture TCP listeners (only if not skipped)
-				listeners.merge!(capture_tcp(tcp_addresses)) unless tcp_addresses == :skip
+				result.concat(capture_tcp(tcp_addresses)) unless tcp_addresses == :skip
 				
 				# Capture Unix domain socket listeners (only if not skipped)
-				listeners.merge!(capture_unix(unix_paths, file: unix_file)) unless unix_paths == :skip
+				result.concat(capture_unix(unix_paths, file: unix_file)) unless unix_paths == :skip
 				
-				return listeners
+				return result
 			end
 		end
 	end
@@ -317,7 +325,7 @@ if IO::Metrics::Listener::Linux.supported?
 		# Capture listener listeners for the given address(es).
 		# @parameter addresses [Array(String) | Nil] TCP address(es) to capture, e.g. ["0.0.0.0:80"]. If nil, captures all listening TCP sockets.
 		# @parameter paths [Array(String) | Nil] Unix socket path(s) to capture. If nil and addresses is nil, captures all. If nil but addresses specified, captures none.
-		# @returns [Hash(String, Listener) | Nil] A hash mapping addresses/paths to Listener, or nil if not supported.
+		# @returns [Array(Listener) | Nil] Captured listeners, or nil if not supported.
 		def capture(**options)
 			IO::Metrics::Listener::Linux.capture(**options)
 		end

data/lib/io/metrics/listener.rb

@@ -8,20 +8,28 @@ require "json"
 class IO
 	module Metrics
 		# Represents a network listener socket with its queue statistics.
+		# @attribute address [Addrinfo | Nil] Listening endpoint from capture; nil only for {Listener.zero} placeholders.
 		# @attribute queue_size [Integer] Number of connections waiting to be accepted (queued).
 		# @attribute active_connections [Integer] Number of active connections (already accepted).
-		class Listener < Struct.new(:queue_size, :active_connections)
-			alias as_json to_h
+		class Listener < Struct.new(:address, :queue_size, :active_connections)
+			# Serialize for JSON; address uses Addrinfo#inspect_sockaddr.
+			def as_json(*)
+				{
+					address: address&.inspect_sockaddr,
+					queue_size: queue_size,
+					active_connections: active_connections,
+				}
+			end
 			
 			# Convert the object to a JSON string.
 			def to_json(*arguments)
 				as_json.to_json(*arguments)
 			end
 			
-			# Create a zero-initialized Listener instance.
-			# @returns [Listener] A new Listener object with all fields set to zero.
+			# Create a zero-initialized Listener instance (no endpoint; for tests or templates).
+			# @returns [Listener] Counters zero; {#address} is nil.
 			def self.zero
-				self.new(0, 0)
+				new(nil, 0, 0)
 			end
 			
 			# Whether listener stats can be captured on this system.
@@ -32,7 +40,7 @@ class IO
 			# Capture listener stats for the given address(es).
 			# @parameter addresses [Array(String) | Nil] TCP address(es) to capture, e.g. ["0.0.0.0:80"]. If nil, captures all listening TCP sockets.
 			# @parameter paths [Array(String) | Nil] Unix socket path(s) to capture. If nil and addresses is nil, captures all. If nil but addresses specified, captures none.
-			# @returns [Hash(String, Listener) | Nil] A hash mapping addresses/paths to Listener, or nil if not supported.
+			# @returns [Array(Listener) | Nil] Captured listeners, or nil if not supported.
 			def self.capture(**options)
 				return nil
 			end

data/lib/io/metrics/version.rb

@@ -7,6 +7,6 @@
 class IO
 	# @namespace
 	module Metrics
-		VERSION = "0.1.0"
+		VERSION = "0.2.0"
 	end
 end

data/readme.md

@@ -10,6 +10,15 @@ Please see the [project documentation](https://socketry.github.io/io-metrics/) f
 
   - [Getting Started](https://socketry.github.io/io-metrics/guides/getting-started/index) - This guide explains how to use `io-metrics` to capture listener queue statistics from the host operating system.
 
+## Releases
+
+Please see the [project releases](https://socketry.github.io/io-metrics/releases/index) for all releases.
+
+### v0.2.0
+
+  - **Breaking** `IO::Metrics::Listener.capture` returns an `Array` of `Listener` rows instead of a `Hash` keyed by address string.
+  - Each `Listener` has `address` (`Addrinfo` for TCP or Unix), `queue_size`, and `active_connections`. `Listener.zero` sets `address` to `nil`. JSON uses `Addrinfo#inspect_sockaddr` for `address`, or `null` when absent.
+
 ## Contributing
 
 We welcome contributions to this project.
@@ -20,6 +29,22 @@ We welcome contributions to this project.
 4.  Push to the branch (`git push origin my-new-feature`).
 5.  Create new Pull Request.
 
+### Running Tests
+
+To run the test suite:
+
+``` shell
+bundle exec sus
+```
+
+### Making Releases
+
+To make a new release:
+
+``` shell
+bundle exec bake gem:release:patch # or minor or major
+```
+
 ### Developer Certificate of Origin
 
 In order to protect users of this project, we require all contributors to comply with the [Developer Certificate of Origin](https://developercertificate.org/). This ensures that all contributions are properly licensed and attributed.

data/releases.md

@@ -0,0 +1,6 @@
+# Releases
+
+## v0.2.0
+
+  - **Breaking** `IO::Metrics::Listener.capture` returns an `Array` of `Listener` rows instead of a `Hash` keyed by address string.
+  - Each `Listener` has `address` (`Addrinfo` for TCP or Unix), `queue_size`, and `active_connections`. `Listener.zero` sets `address` to `nil`. JSON uses `Addrinfo#inspect_sockaddr` for `address`, or `null` when absent.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: io-metrics
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -77,6 +77,7 @@ files:
 - lib/io/metrics/version.rb
 - license.md
 - readme.md
+- releases.md
 homepage: https://github.com/socketry/io-metrics
 licenses:
 - MIT
@@ -91,14 +92,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.2'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.6
 specification_version: 4
 summary: Extract I/O metrics from the host system.
 test_files: []