Make addressable a soft dependency, lazy-loaded for non-ASCII URIs

Move addressable from a runtime dependency to a development/optional
dependency. It is now lazy-loaded via require_addressable only when
parsing non-ASCII (IRI) URI strings or encoding internationalized
hostnames via IDNA. ASCII-only URIs use Ruby's stdlib URI parser
exclusively, with no addressable require at load time.

Author: sferik

.mutant.yml

@@ -29,3 +29,5 @@ matcher:
     - HTTP::Base64*
   ignore:
     - HTTP::URI.parse_with_addressable
+    - HTTP::URI.require_addressable
+    - HTTP::URI.idna_to_ascii

CHANGELOG.md

@@ -18,11 +18,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `Response.new`, `Redirector.new`, `Retriable::Performer.new`,
   `Retriable::DelayCalculator.new`, and `Timeout::Null.new` (and subclasses).
   `HTTP::URI.new` also no longer accepts `Addressable::URI` objects.
-- Reimplement `HTTP::URI` with native component storage instead of delegating
-  to `Addressable::URI`. ASCII URIs are now parsed with Ruby's stdlib `URI`,
-  with Addressable used only as a fallback for non-ASCII (IRI) strings. This
-  removes most of the runtime dependency on the `addressable` gem while
-  preserving full URI functionality.
+- **BREAKING** `addressable` is no longer a runtime dependency. It is now
+  lazy-loaded only when parsing non-ASCII (IRI) URIs or normalizing
+  internationalized hostnames. Install the `addressable` gem if you need
+  non-ASCII URI support. ASCII-only URIs use Ruby's stdlib `URI` parser
+  exclusively.
 - **BREAKING** Extract request building into `HTTP::Request::Builder`. The
   `build_request` method has been removed from `Client`, `Session`, and the
   top-level `HTTP` module. Use `HTTP::Request::Builder.new(options).build(verb, uri)`

Gemfile

@@ -12,6 +12,7 @@ group :development do
 end
 
 group :test do
+  gem "addressable", "~> 2.8"
   gem "logger"
 
   gem "rubocop",             "~> 1.85"

http.gemspec

@@ -36,7 +36,6 @@ Gem::Specification.new do |spec|
 
   spec.required_ruby_version = ">= 3.2"
 
-  spec.add_dependency "addressable",    "~> 2.8"
   spec.add_dependency "http-cookie",    "~> 1.0"
   spec.add_dependency "http-form_data", "~> 2.2"
 

lib/http/uri.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require "addressable/uri"
 require "uri"
 
 module HTTP
@@ -260,7 +259,7 @@ def port
     # @api public
     # @return [Integer, nil] default port or nil for unknown schemes
     def default_port
-      DEFAULT_PORTS[@scheme&.downcase] # steep:ignore
+      DEFAULT_PORTS[@scheme&.downcase]
     end
 
     # The origin (scheme + host + port) per RFC 6454
@@ -387,14 +386,14 @@ def dup
     def to_s # rubocop:disable Metrics/CyclomaticComplexity,Metrics/MethodLength
       str = +""
       str << "#{@scheme}:" if @scheme
-      if @raw_host
+      if (raw_host = @raw_host)
         str << "//"
-        if @user
-          str << @user # steep:ignore
+        if (user = @user)
+          str << user
           str << ":#{@password}" if @password
           str << "@"
         end
-        str << @raw_host # steep:ignore
+        str << raw_host
         str << ":#{@port}" if @port
       end
       str << @path
@@ -429,6 +428,30 @@ def deconstruct_keys(keys)
       keys ? hash.slice(*keys) : hash
     end
 
+    # Loads the addressable gem on first use
+    #
+    # @api private
+    # @return [void]
+    # @raise [LoadError] if addressable gem is not installed
+    def self.require_addressable
+      return if defined?(@addressable_loaded)
+
+      require "addressable/uri"
+      @addressable_loaded = true
+    end
+
+    # Convert a hostname to ASCII via IDNA (requires addressable)
+    #
+    # @param [String] host hostname to encode
+    # @api private
+    # @return [String] ASCII-encoded hostname
+    def self.idna_to_ascii(host)
+      return host if host.ascii_only?
+
+      require_addressable
+      Addressable::IDNA.to_ascii(host) # steep:ignore
+    end
+
     private
 
     # Adds or removes IPv6 brackets from a host
@@ -463,10 +486,10 @@ def process_ipv6_brackets(raw_host, brackets: false)
     def normalize_host(host)
       return nil unless host
 
-      h = host.gsub(/%(\h{2})/) { Regexp.last_match(1).to_i(16).chr } # steep:ignore
+      h = host.gsub(/%\h{2}/) { |match| match.delete_prefix("%").to_i(16).chr }
       h = h.delete_suffix(".")
       h = h.downcase
-      Addressable::IDNA.to_ascii(h) # steep:ignore
+      self.class.idna_to_ascii(h)
     end
 
     # Parse a URI string into component parts
@@ -507,11 +530,12 @@ def normalize_host(host)
     # @api private
     # @return [Hash] URI components
     private_class_method def self.parse_with_addressable(uri_string)
-      parsed = Addressable::URI.parse(uri_string)
+      require_addressable
+      parsed = Addressable::URI.parse(uri_string) # steep:ignore
       { scheme: parsed.scheme, user: parsed.user, password: parsed.password,
         host: parsed.host, port: parsed.port, path: parsed.path,
         query: parsed.query, fragment: parsed.fragment }
-    rescue Addressable::URI::InvalidURIError
+    rescue Addressable::URI::InvalidURIError # steep:ignore
       raise InvalidError, "invalid URI: #{uri_string.inspect}"
     end
   end

sig/http.rbs

@@ -56,7 +56,7 @@ module HTTP
       ?body: untyped,
       ?follow: bool | Hash[Symbol, untyped],
       ?retriable: bool | Hash[Symbol, untyped],
-      ?base_uri: String | URI | nil,
+      ?base_uri: String | URI?,
       ?persistent: String?,
       ?ssl_context: OpenSSL::SSL::SSLContext?
     ) -> Response
@@ -118,7 +118,7 @@ module HTTP
       ?body: untyped,
       ?follow: bool | Hash[Symbol, untyped],
       ?retriable: bool | Hash[Symbol, untyped],
-      ?base_uri: String | URI | nil,
+      ?base_uri: String | URI?,
       ?persistent: String?,
       ?ssl_context: OpenSSL::SSL::SSLContext?
     ) -> Response
@@ -167,7 +167,7 @@ module HTTP
       ?body: untyped,
       ?follow: bool | Hash[Symbol, untyped],
       ?retriable: bool | Hash[Symbol, untyped],
-      ?base_uri: String | URI | nil,
+      ?base_uri: String | URI?,
       ?persistent: String?,
       ?ssl_context: OpenSSL::SSL::SSLContext?
     ) -> Response
@@ -222,11 +222,11 @@ module HTTP
     def delete: (String | Symbol name) -> void
     def add: (String | Symbol name, String | Array[String] value) -> void
     def get: (String | Symbol name) -> Array[String]
-    def []: (String | Symbol name) -> (String | Array[String] | nil)
+    def []: (String | Symbol name) -> (String | Array[String]?)
     def include?: (String | Symbol name) -> bool
-    def to_h: () -> Hash[String, String | Array[String] | nil]
+    def to_h: () -> Hash[String, String | Array[String]?]
     alias to_hash to_h
-    def deconstruct_keys: (Array[Symbol]? keys) -> Hash[Symbol, String | Array[String] | nil]
+    def deconstruct_keys: (Array[Symbol]? keys) -> Hash[Symbol, String | Array[String]?]
     def to_a: () -> Array[Array[String]]
     def inspect: () -> String
     def keys: () -> Array[String]
@@ -491,7 +491,7 @@ module HTTP
       ?body: untyped,
       ?follow: bool | Hash[Symbol, untyped],
       ?retriable: bool | Hash[Symbol, untyped],
-      ?base_uri: String | URI | nil,
+      ?base_uri: String | URI?,
       ?persistent: String?,
       ?ssl_context: OpenSSL::SSL::SSLContext?
     ) -> void
@@ -501,7 +501,7 @@ module HTTP
 
     def follow=: (bool value) -> void
     def retriable=: (bool value) -> void
-    def base_uri=: (String | URI | nil value) -> void
+    def base_uri=: (String | URI? value) -> void
     def base_uri?: () -> bool
     def persistent=: (String? value) -> String?
     def persistent?: () -> bool
@@ -569,6 +569,7 @@ module HTTP
 
     @raw_host: String?
     @hash: Integer
+    self.@addressable_loaded: bool
     @scheme: String?
     @user: String?
     @password: String?
@@ -592,7 +593,7 @@ module HTTP
     HTTPS_SCHEME: String
     PERCENT_ENCODE: Regexp
     NEEDS_ADDRESSABLE: Regexp
-    DEFAULT_PORTS: Hash[String, Integer]
+    DEFAULT_PORTS: Hash[String?, Integer]
     NORMALIZER: ^(String | URI) -> URI
 
     DOT_SEGMENTS: Array[String]
@@ -632,6 +633,8 @@ module HTTP
     def self.parse_components: (String uri_string) -> Hash[Symbol, untyped]
     def self.parse_with_stdlib: (String uri_string) -> Hash[Symbol, untyped]?
     def self.parse_with_addressable: (String uri_string) -> Hash[Symbol, untyped]
+    def self.require_addressable: () -> void
+    def self.idna_to_ascii: (String host) -> String
   end
 
   # Supported HTTP method verbs
@@ -802,7 +805,7 @@ module HTTP
     def readpartial: (?Integer size, ?String? outbuf) -> String
     def connection: () -> Connection?
     def uri: () -> URI
-    def to_a: () -> [Integer, Hash[String, String | Array[String] | nil], String]
+    def to_a: () -> [Integer, Hash[String, String | Array[String]?], String]
     alias deconstruct to_a
     def deconstruct_keys: (Array[Symbol]? keys) -> Hash[Symbol, Status | String | Headers | Body | Request?]
     def flush: () -> Response

test/http/uri_test.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "test_helper"
+require "addressable/uri"
 
 describe HTTP::URI do
   cover "HTTP::URI*"