random-port 0.7.6 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 19a3b6d51277760ad0638f741ef63bf1fbc8a4b77663b41569da4c34e251353a
-  data.tar.gz: 96e0c4061b43248cbf091e318b9e6645371a7fd11189a43cd1cadccf23b9704d
+  metadata.gz: 2c6250d7a7a9a68ca737b299b7cef6b4816e35a6fe9452b78633c2df1132bd41
+  data.tar.gz: 9ec96d9ae9ce5e2f58c4bd3821f24877cfbc7a88913005d21a32c90d8f465b77
 SHA512:
-  metadata.gz: 6ac6711969efbcd97a534391cff9b3bb3e4244a5fe0a4518d7cbb3644a6b849507db8025af1491fac615c1aa9f3edf4db7d7bd9e42faf5619304191c1265afa0
-  data.tar.gz: f01a9a30993fcc100fd5946290a8f8b60d94cb8a19db6ab8b918527ca48086f92cff89723391d99302f79fc264ed9f4d76a2225bfdfa24819e3af51ec8971396
+  metadata.gz: da1f7e7b9daeaf7a60fd935cbc8b0c578a352c558683a85f7c6d66c4a7ef391586a02b389107516c270d2a38215979aa8f4f6cdba5b70f7f128515cc21058a8c
+  data.tar.gz: bf6db1f8503993e5388b4cb48909f2684a0618eb26e4f5bc5677fe92b248c67a22e11f9ad8e9f5405223718d7f7287dc51ea50ffe47def18b6b8561ea3dab582

data/Gemfile

@@ -1,12 +1,15 @@
 # frozen_string_literal: true
 
-# SPDX-FileCopyrightText: Copyright (c) 2018-2025 Yegor Bugayenko
+# SPDX-FileCopyrightText: Copyright (c) 2018-2026 Yegor Bugayenko
 # SPDX-License-Identifier: MIT
 
 source 'https://rubygems.org'
 gemspec
 
-gem 'minitest', '~>5.25', require: false
+gem 'minitest', '~>6.0', require: false
+gem 'minitest-mock', '~>5.27', require: false
+gem 'minitest-reporters', '~>1.7', require: false
+gem 'os', '~> 1.1', require: false
 gem 'qbash', '~>0.2', require: false
 gem 'rake', '~>13.2', require: false
 gem 'rubocop', '~>1.75', require: false
@@ -15,5 +18,6 @@ gem 'rubocop-performance', '~>1.25', require: false
 gem 'rubocop-rake', '~>0.7', require: false
 gem 'rubocop-rspec', '~> 3.7', require: false
 gem 'simplecov', '~>0.22', require: false
+gem 'simplecov-cobertura', '~>3.0', require: false
 gem 'threads', '~>0.4', require: false
 gem 'yard', '~>0.9', require: false

data/Gemfile.lock

@@ -7,35 +7,48 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
+    ansi (1.5.0)
     ast (2.4.3)
     backtrace (0.4.1)
-    concurrent-ruby (1.3.5)
+    builder (3.3.0)
+    concurrent-ruby (1.3.6)
     docile (1.4.1)
-    elapsed (0.2.0)
+    elapsed (0.3.1)
       loog (~> 0.6)
       tago (~> 0.1)
-    json (2.15.0)
+    ellipsized (0.3.0)
+    json (2.18.1)
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
     logger (1.7.0)
-    loog (0.6.1)
+    loog (0.8.0)
+      ellipsized
       logger (~> 1.0)
-    minitest (5.25.5)
+    minitest (6.0.1)
+      prism (~> 1.5)
+    minitest-mock (5.27.0)
+    minitest-reporters (1.7.1)
+      ansi
+      builder
+      minitest (>= 5.0)
+      ruby-progressbar
+    os (1.1.4)
     parallel (1.27.0)
-    parser (3.3.9.0)
+    parser (3.3.10.1)
       ast (~> 2.4.1)
       racc
-    prism (1.5.1)
-    qbash (0.4.5)
+    prism (1.9.0)
+    qbash (0.7.2)
       backtrace (> 0)
       elapsed (> 0)
       loog (> 0)
       tago (> 0)
     racc (1.8.1)
     rainbow (3.1.1)
-    rake (13.3.0)
+    rake (13.3.1)
     regexp_parser (2.11.3)
-    rubocop (1.80.2)
+    rexml (3.4.4)
+    rubocop (1.84.1)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
@@ -43,41 +56,44 @@ GEM
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 2.9.3, < 3.0)
-      rubocop-ast (>= 1.46.0, < 2.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.47.1)
+    rubocop-ast (1.49.0)
       parser (>= 3.3.7.2)
-      prism (~> 1.4)
+      prism (~> 1.7)
     rubocop-minitest (0.38.2)
       lint_roller (~> 1.1)
       rubocop (>= 1.75.0, < 2.0)
       rubocop-ast (>= 1.38.0, < 2.0)
-    rubocop-performance (1.26.0)
+    rubocop-performance (1.26.1)
       lint_roller (~> 1.1)
       rubocop (>= 1.75.0, < 2.0)
-      rubocop-ast (>= 1.44.0, < 2.0)
+      rubocop-ast (>= 1.47.1, < 2.0)
     rubocop-rake (0.7.1)
       lint_roller (~> 1.1)
       rubocop (>= 1.72.1)
-    rubocop-rspec (3.7.0)
+    rubocop-rspec (3.9.0)
       lint_roller (~> 1.1)
-      rubocop (~> 1.72, >= 1.72.1)
+      rubocop (~> 1.81)
     ruby-progressbar (1.13.0)
     simplecov (0.22.0)
       docile (~> 1.1)
       simplecov-html (~> 0.11)
       simplecov_json_formatter (~> 0.1)
+    simplecov-cobertura (3.1.0)
+      rexml
+      simplecov (~> 0.19)
     simplecov-html (0.13.2)
     simplecov_json_formatter (0.1.4)
-    tago (0.2.0)
-    threads (0.4.1)
+    tago (0.7.0)
+    threads (0.5.0)
       backtrace (~> 0)
       concurrent-ruby (~> 1.0)
     unicode-display_width (3.2.0)
       unicode-emoji (~> 4.1)
-    unicode-emoji (4.1.0)
-    yard (0.9.37)
+    unicode-emoji (4.2.0)
+    yard (0.9.38)
 
 PLATFORMS
   arm64-darwin-22
@@ -87,7 +103,10 @@ PLATFORMS
   x86_64-linux
 
 DEPENDENCIES
-  minitest (~> 5.25)
+  minitest (~> 6.0)
+  minitest-mock (~> 5.27)
+  minitest-reporters (~> 1.7)
+  os (~> 1.1)
   qbash (~> 0.2)
   rake (~> 13.2)
   random-port!
@@ -97,6 +116,7 @@ DEPENDENCIES
   rubocop-rake (~> 0.7)
   rubocop-rspec (~> 3.7)
   simplecov (~> 0.22)
+  simplecov-cobertura (~> 3.0)
   threads (~> 0.4)
   yard (~> 0.9)
 

data/LICENSE.txt

@@ -1,6 +1,6 @@
 (The MIT License)
 
-Copyright (c) 2018-2025 Yegor Bugayenko
+Copyright (c) 2018-2026 Yegor Bugayenko
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the 'Software'), to deal

data/LICENSES/MIT.txt

@@ -1,6 +1,6 @@
 (The MIT License)
 
-Copyright (c) 2018-2025 Yegor Bugayenko
+Copyright (c) 2018-2026 Yegor Bugayenko
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the 'Software'), to deal

data/README.md

@@ -5,11 +5,10 @@
 
 [![rake](https://github.com/yegor256/random-port/actions/workflows/rake.yml/badge.svg)](https://github.com/yegor256/random-port/actions/workflows/rake.yml)
 [![Gem Version](https://badge.fury.io/rb/random-port.svg)](https://badge.fury.io/rb/random-port)
-[![Maintainability](https://api.codeclimate.com/v1/badges/349b8c31884d3b34d926/maintainability)](https://codeclimate.com/github/yegor256/random-port/maintainability)
 [![Yard Docs](https://img.shields.io/badge/yard-docs-blue.svg)](https://rubydoc.info/github/yegor256/random-port/master/frames)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/yegor256/random-port/blob/master/LICENSE.txt)
 [![Test Coverage](https://img.shields.io/codecov/c/github/yegor256/random-port.svg)](https://codecov.io/github/yegor256/random-port?branch=master)
-[![Hits-of-Code](https://hitsofcode.com/github/yegor256/random-port)](https://hitsofcode.com/view/github/random-port/mailanes)
+[![Hits-of-Code](https://hitsofcode.com/github/yegor256/random-port)](https://hitsofcode.com/view/github/yegor256/random-port)
 
 It's a simple Ruby gem to get a random TCP port.
 
@@ -52,6 +51,15 @@ RandomPort::Pool::SINGLETON.acquire do |port|
 end
 ```
 
+Or use shortened version, all methods called in `RandomPort`
+will be delegated to `Pool::SINGLETON`:
+
+```ruby
+RandomPort.acquire do |port|
+  # Use it here...
+end
+```
+
 The pool is thread-safe by default.
 You can configure it to be
 not-thread-safe, using optional `sync` argument of the constructor.
@@ -62,7 +70,7 @@ Read
 [these guidelines](https://www.yegor256.com/2014/04/15/github-guidelines.html).
 Make sure your build is green before you contribute
 your pull request. You will need to have
-[Ruby](https://www.ruby-lang.org/en/) 2.3+ and
+[Ruby](https://www.ruby-lang.org/en/) 3.3+ and
 [Bundler](https://bundler.io/) installed. Then:
 
 ```bash

data/Rakefile

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
-# SPDX-FileCopyrightText: Copyright (c) 2018-2025 Yegor Bugayenko
+# SPDX-FileCopyrightText: Copyright (c) 2018-2026 Yegor Bugayenko
 # SPDX-License-Identifier: MIT
 
+require 'os'
+require 'qbash'
 require 'rubygems'
 require 'rake'
 require 'rake/clean'
+require 'shellwords'
 
 CLEAN << 'coverage'
 
@@ -17,7 +20,7 @@ def version
   Gem::Specification.load(Dir['*.gemspec'].first).version
 end
 
-task default: %i[clean test yard rubocop]
+task default: %i[clean test picks yard rubocop]
 
 require 'rake/testtask'
 desc 'Run all unit tests'
@@ -27,6 +30,16 @@ Rake::TestTask.new(:test) do |test|
   test.verbose = false
 end
 
+desc 'Run them via Ruby, one by one'
+task :picks do
+  next if OS.windows?
+  %w[test lib].each do |d|
+    Dir["#{d}/**/*.rb"].each do |f|
+      qbash("bundle exec ruby #{Shellwords.escape(f)}", stdout: $stdout, env: { 'PICKS' => 'yes' })
+    end
+  end
+end
+
 require 'rubocop/rake_task'
 desc 'Run RuboCop on all directories'
 RuboCop::RakeTask.new(:rubocop) do |task|
@@ -37,4 +50,5 @@ require 'yard'
 desc 'Build Yard documentation'
 YARD::Rake::YardocTask.new do |t|
   t.files = ['lib/**/*.rb']
+  t.options = ['--fail-on-warning']
 end

data/lib/random-port/module.rb

@@ -1,12 +1,22 @@
 # frozen_string_literal: true
 
-# SPDX-FileCopyrightText: Copyright (c) 2018-2025 Yegor Bugayenko
+# SPDX-FileCopyrightText: Copyright (c) 2018-2026 Yegor Bugayenko
 # SPDX-License-Identifier: MIT
 
-# The module for all classes.
+require 'forwardable'
+
+# Main module that contains all RandomPort classes and utilities.
+#
+# This module provides a simple way to acquire random TCP ports
+# that are guaranteed to be available for use. It includes a Pool
+# class that manages port allocation and ensures thread safety.
 #
 # Author:: Yegor Bugayenko (yegor256@gmail.com)
-# Copyright:: Copyright (c) 2018-2025 Yegor Bugayenko
+# Copyright:: Copyright (c) 2018-2026 Yegor Bugayenko
 # License:: MIT
 module RandomPort
+  extend Forwardable
+
+  def_delegators :'RandomPort::Pool::SINGLETON', :acquire, :release, :count, :size, :empty?
+  module_function :acquire, :release, :count, :size, :empty?
 end

data/lib/random-port/pool.rb

@@ -1,14 +1,15 @@
 # frozen_string_literal: true
 
-# SPDX-FileCopyrightText: Copyright (c) 2018-2025 Yegor Bugayenko
+# SPDX-FileCopyrightText: Copyright (c) 2018-2026 Yegor Bugayenko
 # SPDX-License-Identifier: MIT
 
+require 'minitest/mock'
 require 'monitor'
 require 'socket'
 require 'tago'
 require_relative 'module'
 
-# Pool of TPC ports.
+# Pool of TCP ports.
 #
 # Use it like this:
 #
@@ -17,26 +18,27 @@ require_relative 'module'
 #    # to the pool afterwards.
 #  end
 #
-# You can specify the maximum amount of ports to acquire, using +limit+.
-# If more acquiring requests will arrive, an exception will be raised.
+# You can specify the maximum number of ports to acquire using +limit+.
+# If more acquisition requests arrive, an exception will be raised.
 #
-# The class is thread-safe, by default. You can configure it to be
-# not-thread-safe, using optional +sync+ argument of the constructor,
+# The class is thread-safe by default. You can configure it to be
+# non-thread-safe using the optional +sync+ argument of the constructor,
 # passing <tt>FALSE</tt>.
 #
 # Author:: Yegor Bugayenko (yegor256@gmail.com)
-# Copyright:: Copyright (c) 2018-2025 Yegor Bugayenko
+# Copyright:: Copyright (c) 2018-2026 Yegor Bugayenko
 # License:: MIT
 class RandomPort::Pool
-  # If can't acquire by time out.
+  # Raised when a port cannot be acquired within the timeout period.
   class Timeout < StandardError; end
 
+  # @return [Integer] The maximum number of ports that can be acquired from this pool
   attr_reader :limit
 
-  # Ctor.
-  # @param [Boolean] sync Set it to FALSE if you want this pool to be NOT thread-safe
-  # @param [Integer] limit Set the maximum number of ports in the pool
-  # @param [Integer] start The next port to try
+  # Constructor.
+  # @param [Boolean] sync Set to FALSE if you want this pool to be non-thread-safe
+  # @param [Integer] limit The maximum number of ports that can be acquired from the pool
+  # @param [Integer] start The first port number to try when acquiring
   def initialize(sync: true, limit: 65_536, start: 1025)
     @ports = []
     @sync = sync
@@ -45,27 +47,33 @@ class RandomPort::Pool
     @next = start
   end
 
-  # Application wide pool of ports
+  # Application-wide singleton pool of ports.
   SINGLETON = RandomPort::Pool.new
 
-  # How many ports acquired now?
+  # Returns the number of ports currently acquired from the pool.
+  # @return [Integer] The count of acquired ports
   def count
     @ports.count
   end
   alias size count
 
-  # Is it empty?
+  # Checks if the pool is empty (no ports are currently acquired).
+  # @return [Boolean] TRUE if no ports are acquired, FALSE otherwise
   def empty?
     @ports.empty?
   end
 
-  # Acquire a new random TCP port.
+  # Acquires one or more available TCP ports from the pool.
   #
   # You can specify the number of ports to acquire. If it's more than one,
-  # an array will be returned.
+  # an array will be returned. If a block is given, the port(s) will be
+  # automatically released after the block execution.
   #
-  # You can specify the amount of seconds to wait until a new port
-  # is available.
+  # @param [Integer] total The number of ports to acquire (default: 1)
+  # @param [Integer] timeout The maximum seconds to wait for port availability
+  # @yield [Integer|Array<Integer>] The acquired port(s)
+  # @return [Integer|Array<Integer>] The acquired port(s) if no block given
+  # @raise [Timeout] If ports cannot be acquired within the timeout period
   def acquire(total = 1, timeout: 4)
     start = Time.now
     attempt = 0
@@ -77,7 +85,7 @@ class RandomPort::Pool
           "(#{@ports.size} already occupied) " \
           "for #{total} port(s), after #{attempt} attempts in #{start.ago}"
       end
-      attempt +=  1
+      attempt += 1
       opts = safe { group(total) }
       if opts.nil?
         @next += 1
@@ -96,9 +104,9 @@ class RandomPort::Pool
     end
   end
 
-  # Return it/them back to the pool.
-  # @param [Integer] port TCP port number to release
-  # @return nil
+  # Releases one or more ports back to the pool.
+  # @param [Integer|Array<Integer>] port The TCP port number(s) to release
+  # @return [nil]
   def release(port)
     safe do
       if port.is_a?(Array)
@@ -111,12 +119,12 @@ class RandomPort::Pool
 
   private
 
-  # Take a group of ports, if possible.
-  # @param [Integer] total How many ports to take
-  # @return [Array<Integer>|nil] Ports found or NIL if impossible now
+  # Attempts to acquire a contiguous group of ports.
+  # @param [Integer] total The number of ports to acquire
+  # @return [Array<Integer>|nil] An array of port numbers if successful, nil otherwise
   def group(total)
     return nil if @ports.count + total > @limit
-    opts = Array.new(0, total)
+    opts = Array.new(total, 0)
     begin
       (0..(total - 1)).each do |i|
         port = i.zero? ? @next : opts[i - 1] + 1
@@ -127,31 +135,35 @@ class RandomPort::Pool
     end
     return nil if opts.any? { |p| @ports.include?(p) }
     d = total * (total - 1) / 2
-    return nil unless opts.inject(&:+) - (total * opts.min) == d
+    return nil unless opts.sum - (total * opts.min) == d
     @ports += opts
     opts
   end
 
-  # Find one possible TCP port or raise exception if this port can't be used.
+  # Verifies that a specific TCP port is available for use.
   #
-  # If port is occupied, this method raises an error (+Errno::EADDRINUSE+).
+  # Attempts to bind to the port on various interfaces to ensure availability.
+  # If the port is occupied, this method raises an error (+Errno::EADDRINUSE+).
   #
-  # @param [Integer] port Suggested port number
-  # @return [Integer] The same port number
+  # @param [Integer] port The port number to verify
+  # @return [Integer] The same port number if available
+  # @raise [Errno::EADDRINUSE] If the port is already in use
+  # @raise [SocketError] If there's a socket-related error
   def take(port)
     ['127.0.0.1', '::1', '0.0.0.0', 'localhost'].each do |host|
-      begin
-        TCPServer.new(host, port).close
-      rescue Errno::EADDRNOTAVAIL
-        next
-      end
+      TCPServer.new(host, port).close
+    rescue Errno::EADDRNOTAVAIL
+      next
     end
     port
   end
 
-  def safe(&block)
+  # Executes a block of code with or without thread synchronization.
+  # @yield The block of code to execute
+  # @return The result of the block execution
+  def safe(&)
     if @sync
-      @monitor.synchronize(&block)
+      @monitor.synchronize(&)
     else
       yield
     end

data/lib/random-port.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# SPDX-FileCopyrightText: Copyright (c) 2018-2025 Yegor Bugayenko
+# SPDX-FileCopyrightText: Copyright (c) 2018-2026 Yegor Bugayenko
 # SPDX-License-Identifier: MIT
 
 require_relative 'random-port/module'

data/random-port.gemspec

@@ -1,14 +1,14 @@
 # frozen_string_literal: true
 
-# SPDX-FileCopyrightText: Copyright (c) 2018-2025 Yegor Bugayenko
+# SPDX-FileCopyrightText: Copyright (c) 2018-2026 Yegor Bugayenko
 # SPDX-License-Identifier: MIT
 
 require 'English'
 Gem::Specification.new do |s|
   s.required_rubygems_version = Gem::Requirement.new('>= 0') if s.respond_to? :required_rubygems_version=
-  s.required_ruby_version = '>=2.3'
+  s.required_ruby_version = '>=3.3'
   s.name = 'random-port'
-  s.version = '0.7.6'
+  s.version = '0.8.1'
   s.license = 'MIT'
   s.summary = 'Random TCP port'
   s.description = 'Reserves a random TCP port'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: random-port
 version: !ruby/object:Gem::Version
-  version: 0.7.6
+  version: 0.8.1
 platform: ruby
 authors:
 - Yegor Bugayenko
@@ -54,7 +54,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.3'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="