Replace **options with explicit keyword arguments

Convert all methods that accepted arbitrary **options or **opts to
restricted keyword argument lists, preventing silent acceptance of
misspelled or unknown option keys.

Author: sferik

CHANGELOG.md

@@ -9,15 +9,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
-- **BREAKING** `HTTP::URI.new` no longer accepts `Addressable::URI` objects;
-  pass a component Hash instead (e.g., `HTTP::URI.new(scheme: "http", host: "example.com")`)
-- **BREAKING** Convert options hash parameters to keyword arguments across the
-  public API. Methods like `HTTP.get(url, body: "data")` continue to work, but
-  passing an explicit hash (e.g., `HTTP.get(url, {body: "data"})`) is no longer
-  supported. Affected methods: all HTTP verb methods (`get`, `post`, etc.),
-  `request`, `follow`, `Request.new`, `Response.new`, `Redirector.new`,
-  `Retriable::Performer.new`, `Retriable::DelayCalculator.new`, and
-  `Timeout::Null.new` (and subclasses)
+- **BREAKING** Convert options hash parameters to explicit keyword arguments
+  across the public API. Methods like `HTTP.get(url, body: "data")` continue to
+  work, but passing an explicit hash (e.g., `HTTP.get(url, {body: "data"})`) is
+  no longer supported, and unrecognized keyword arguments now raise
+  `ArgumentError`. Affected methods: all HTTP verb methods (`get`, `post`,
+  etc.), `request`, `follow`, `retriable`, `URI.new`, `Request.new`,
+  `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.
 - **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)`

lib/http/chainable.rb

@@ -157,12 +157,15 @@ def via(*proxy)
     # @example
     #   HTTP.follow.get("http://example.com")
     #
-    # @param options [Hash] redirect options
+    # @param [Boolean] strict (true) redirector hops policy
+    # @param [Integer] max_hops (5) maximum allowed redirect hops
+    # @param [#call, nil] on_redirect optional redirect callback
     # @return [HTTP::Session]
     # @see Redirector#initialize
     # @api public
-    def follow(**options)
-      branch default_options.with_follow(options)
+    def follow(strict: nil, max_hops: nil, on_redirect: nil)
+      opts = { strict: strict, max_hops: max_hops, on_redirect: on_redirect }.compact
+      branch default_options.with_follow(opts)
     end
 
     # Make a request with the given headers
@@ -313,8 +316,11 @@ def use(*features)
     # @param (see Performer#initialize)
     # @return [HTTP::Session]
     # @api public
-    def retriable(**options)
-      branch default_options.with_retriable(options.empty? || options)
+    def retriable(tries: nil, delay: nil, exceptions: nil, retry_statuses: nil,
+                  on_retry: nil, max_delay: nil, should_retry: nil)
+      opts = { tries: tries, delay: delay, exceptions: exceptions, retry_statuses: retry_statuses,
+               on_retry: on_retry, max_delay: max_delay, should_retry: should_retry }.compact
+      branch default_options.with_retriable(opts.empty? || opts)
     end
 
     private

lib/http/client.rb

@@ -40,11 +40,21 @@ def initialize(default_options = nil, **)
     #
     # @param verb [Symbol] the HTTP method
     # @param uri [#to_s] the URI to request
-    # @param opts [Hash] request options
     # @return [HTTP::Response] the response
     # @api public
-    def request(verb, uri, **opts)
-      opts    = @default_options.merge(opts)
+    def request(verb, uri,
+                headers: nil, params: nil, form: nil, json: nil, body: nil,
+                response: nil, encoding: nil, follow: nil, ssl: nil, ssl_context: nil,
+                proxy: nil, nodelay: nil, features: nil, retriable: nil,
+                socket_class: nil, ssl_socket_class: nil, timeout_class: nil,
+                timeout_options: nil, keep_alive_timeout: nil, base_uri: nil, persistent: nil)
+      opts = { headers: headers, params: params, form: form, json: json, body: body,
+               response: response, encoding: encoding, follow: follow, ssl: ssl,
+               ssl_context: ssl_context, proxy: proxy, nodelay: nodelay, features: features,
+               retriable: retriable, socket_class: socket_class, ssl_socket_class: ssl_socket_class,
+               timeout_class: timeout_class, timeout_options: timeout_options,
+               keep_alive_timeout: keep_alive_timeout, base_uri: base_uri, persistent: persistent }.compact
+      opts = @default_options.merge(opts)
       builder = Request::Builder.new(opts)
       req     = builder.build(verb, uri)
       res     = perform(req, opts)

lib/http/features/logging.rb

@@ -118,7 +118,7 @@ def log_request_details(request)
         headers = stringify_headers(request.headers)
         if request.body.loggable?
           source = request.body.source
-          body = source.encoding == Encoding::BINARY ? format_binary(source) : source # steep:ignore
+          body = source.encoding == Encoding::BINARY ? format_binary(source) : source
           logger.debug { "#{headers}\n\n#{body}" }
         else
           logger.debug { headers }
@@ -131,7 +131,7 @@ def log_request_details(request)
       def log_response_body_inline(response)
         body    = response.body
         headers = stringify_headers(response.headers)
-        if body.respond_to?(:encoding) && body.encoding == Encoding::BINARY # steep:ignore
+        if body.respond_to?(:encoding) && body.encoding == Encoding::BINARY
           logger.debug { "#{headers}\n\n#{format_binary(body)}" } # steep:ignore
         else
           logger.debug { "#{headers}\n\n#{body}" }

lib/http/session.rb

@@ -64,12 +64,23 @@ def initialize(default_options = nil, **)
     #
     # @param verb [Symbol] the HTTP method
     # @param uri [#to_s] the URI to request
-    # @param opts [Hash] request options
     # @return [HTTP::Response] the response
     # @api public
-    def request(verb, uri, **opts)
+    def request(verb, uri,
+                headers: nil, params: nil, form: nil, json: nil, body: nil,
+                response: nil, encoding: nil, follow: nil, ssl: nil, ssl_context: nil,
+                proxy: nil, nodelay: nil, features: nil, retriable: nil,
+                socket_class: nil, ssl_socket_class: nil, timeout_class: nil,
+                timeout_options: nil, keep_alive_timeout: nil, base_uri: nil, persistent: nil)
       cookie_jar = CookieJar.new
-      merged  = default_options.merge(opts)
+      merged = default_options.merge(
+        { headers: headers, params: params, form: form, json: json, body: body,
+          response: response, encoding: encoding, follow: follow, ssl: ssl,
+          ssl_context: ssl_context, proxy: proxy, nodelay: nodelay, features: features,
+          retriable: retriable, socket_class: socket_class, ssl_socket_class: ssl_socket_class,
+          timeout_class: timeout_class, timeout_options: timeout_options,
+          keep_alive_timeout: keep_alive_timeout, base_uri: base_uri, persistent: persistent }.compact
+      )
       builder = Request::Builder.new(merged)
       client  = make_client(default_options)
 

lib/http/timeout/null.rb

@@ -30,11 +30,15 @@ class Null
       # @example
       #   HTTP::Timeout::Null.new(read_timeout: 5)
       #
-      # @param options [Hash] timeout options
+      # @param [Numeric, nil] read_timeout Read timeout in seconds
+      # @param [Numeric, nil] write_timeout Write timeout in seconds
+      # @param [Numeric, nil] connect_timeout Connect timeout in seconds
+      # @param [Numeric, nil] global_timeout Global timeout in seconds
       # @api public
       # @return [HTTP::Timeout::Null]
-      def initialize(**options)
-        @options = options
+      def initialize(read_timeout: nil, write_timeout: nil, connect_timeout: nil, global_timeout: nil)
+        @options = { read_timeout: read_timeout, write_timeout: write_timeout,
+                     connect_timeout: connect_timeout, global_timeout: global_timeout }.compact
       end
 
       # Connects to a socket

lib/http/uri.rb

@@ -94,28 +94,28 @@ def self.percent_encode(string)
       end
     end
 
-    # Creates an HTTP::URI instance from the given options
+    # Creates an HTTP::URI instance from the given keyword arguments
     #
     # @example
     #   HTTP::URI.new(scheme: "http", host: "example.com")
     #
-    # @param [Hash] options component hash
-    #
-    # @option options [String, #to_str] :scheme URI scheme
-    # @option options [String, #to_str] :user for basic authentication
-    # @option options [String, #to_str] :password for basic authentication
-    # @option options [String, #to_str] :host name component
-    # @option options [String, #to_str] :port network port to connect to
-    # @option options [String, #to_str] :path component to request
-    # @option options [String, #to_str] :query component distinct from path
-    # @option options [String, #to_str] :fragment component at the end of the URI
+    # @param [String, #to_str] scheme URI scheme
+    # @param [String, #to_str] user for basic authentication
+    # @param [String, #to_str] password for basic authentication
+    # @param [String, #to_str] host name component
+    # @param [Integer, #to_i] port network port to connect to
+    # @param [String, #to_str] path component to request
+    # @param [String, #to_str] query component distinct from path
+    # @param [String, #to_str] fragment component at the end of the URI
     #
     # @api public
     # @return [HTTP::URI] new URI instance
-    def initialize(options = {})
-      raise TypeError, "expected Hash for options, got #{options.class}" unless options.is_a?(Hash)
-
-      @uri = Addressable::URI.new(options)
+    def initialize(scheme: nil, user: nil, password: nil, host: nil,
+                   port: nil, path: nil, query: nil, fragment: nil)
+      @uri = Addressable::URI.new(
+        scheme: scheme, user: user, password: password, host: host,
+        port: port, path: path, query: query, fragment: fragment
+      )
       @host = process_ipv6_brackets(@uri.host)
       @normalized_host = process_ipv6_brackets(@uri.normalized_host)
     end
@@ -218,8 +218,8 @@ def request_uri
     # @return [HTTP::URI] new URI without the specified components
     def omit(*components)
       self.class.new(
-        { scheme: scheme, user: user, password: password, host: @uri.host,
-          port: @uri.port, path: path, query: query, fragment: fragment }.except(*components)
+        **{ scheme: scheme, user: user, password: password, host: @uri.host,
+            port: @uri.port, path: path, query: query, fragment: fragment }.except(*components)
       )
     end
 
@@ -235,7 +235,7 @@ def omit(*components)
     def join(other)
       base = self.class.percent_encode(String(self))
       ref  = self.class.percent_encode(String(other))
-      self.class.parse(::URI.join(base, ref)) # steep:ignore
+      self.class.parse(::URI.join(base, ref))
     end
 
     # Checks whether the URI scheme is HTTP

sig/http.rbs

@@ -54,8 +54,8 @@ module HTTP
       ?form: untyped,
       ?json: untyped,
       ?body: untyped,
-      ?follow: bool,
-      ?retriable: bool,
+      ?follow: bool | Hash[Symbol, untyped],
+      ?retriable: bool | Hash[Symbol, untyped],
       ?base_uri: String | URI | nil,
       ?persistent: String?,
       ?ssl_context: OpenSSL::SSL::SSLContext?
@@ -77,7 +77,7 @@ module HTTP
     def default_options=: (Hash[Symbol, untyped] | Options opts) -> Options
     def nodelay: () -> Session
     def use: (*(Symbol | Hash[Symbol, Hash[Symbol, untyped]]) features) -> Session
-    def retriable: (**untyped options) -> Session
+    def retriable: (?tries: Integer?, ?delay: (Numeric | ^(Integer) -> Numeric)?, ?exceptions: Array[singleton(Exception)]?, ?retry_statuses: untyped, ?on_retry: (^(Request, Exception?, Response?) -> void)?, ?max_delay: Numeric?, ?should_retry: (^(Request, Exception?, Response?, Integer) -> bool)?) -> Session
 
     private
 
@@ -116,8 +116,8 @@ module HTTP
       ?form: untyped,
       ?json: untyped,
       ?body: untyped,
-      ?follow: bool,
-      ?retriable: bool,
+      ?follow: bool | Hash[Symbol, untyped],
+      ?retriable: bool | Hash[Symbol, untyped],
       ?base_uri: String | URI | nil,
       ?persistent: String?,
       ?ssl_context: OpenSSL::SSL::SSLContext?
@@ -165,8 +165,8 @@ module HTTP
       ?form: untyped,
       ?json: untyped,
       ?body: untyped,
-      ?follow: bool,
-      ?retriable: bool,
+      ?follow: bool | Hash[Symbol, untyped],
+      ?retriable: bool | Hash[Symbol, untyped],
       ?base_uri: String | URI | nil,
       ?persistent: String?,
       ?ssl_context: OpenSSL::SSL::SSLContext?
@@ -489,8 +489,8 @@ module HTTP
       ?form: untyped,
       ?json: untyped,
       ?body: untyped,
-      ?follow: bool,
-      ?retriable: bool,
+      ?follow: bool | Hash[Symbol, untyped],
+      ?retriable: bool | Hash[Symbol, untyped],
       ?base_uri: String | URI | nil,
       ?persistent: String?,
       ?ssl_context: OpenSSL::SSL::SSLContext?
@@ -586,9 +586,10 @@ module HTTP
 
     def self.parse: (untyped uri) -> URI
     def self.form_encode: (untyped form_values, ?sort: bool) -> String
-    def self.percent_encode: (String? string) -> String?
+    def self.percent_encode: (String string) -> String
+                           | (String? string) -> String?
 
-    def initialize: (?Hash[Symbol, untyped] options) -> void
+    def initialize: (?scheme: String?, ?user: String?, ?password: String?, ?host: String?, ?port: Integer?, ?path: String?, ?query: String?, ?fragment: String?) -> void
     def ==: (untyped other) -> bool
     def eql?: (untyped other) -> bool
     def hash: () -> Integer
@@ -620,7 +621,7 @@ module HTTP
 
     private
 
-    def process_ipv6_brackets: (untyped raw_host, ?brackets: bool) -> untyped
+    def process_ipv6_brackets: (untyped raw_host, ?brackets: bool) -> String?
   end
 
   # Supported HTTP method verbs
@@ -1119,7 +1120,7 @@ module HTTP
       attr_reader options: Hash[Symbol, Numeric]
       attr_reader socket: untyped
 
-      def initialize: (**Numeric) -> void
+      def initialize: (?read_timeout: Numeric?, ?write_timeout: Numeric?, ?connect_timeout: Numeric?, ?global_timeout: Numeric?) -> void
       def connect: (untyped socket_class, String host, Integer port, ?nodelay: bool) -> void
       def connect_ssl: () -> void
       def close: () -> void

test/http/uri_test.rb

@@ -75,9 +75,8 @@
   end
 
   describe "#initialize" do
-    it "raises TypeError for invalid argument" do
-      err = assert_raises(TypeError) { HTTP::URI.new(42) }
-      assert_match(/expected Hash/, err.message)
+    it "raises ArgumentError for positional argument" do
+      assert_raises(ArgumentError) { HTTP::URI.new(42) }
     end
   end
 
@@ -676,37 +675,28 @@ def remove_dot_segments(path)
   end
 
   describe "#initialize" do
-    it "accepts a Hash of options" do
+    it "accepts keyword arguments" do
       uri = HTTP::URI.new(scheme: "http", host: "example.com")
 
       assert_equal "http", uri.scheme
       assert_equal "example.com", uri.host
     end
 
-    it "raises TypeError for an Addressable::URI" do
+    it "raises ArgumentError for an Addressable::URI" do
       addr_uri = Addressable::URI.parse("http://example.com")
 
-      assert_raises(TypeError) { HTTP::URI.new(addr_uri) }
+      assert_raises(ArgumentError) { HTTP::URI.new(addr_uri) }
     end
 
-    it "includes the class name in TypeError message" do
-      err = assert_raises(TypeError) { HTTP::URI.new(42) }
-      assert_includes err.message, "Integer"
+    it "raises ArgumentError for a positional argument" do
+      assert_raises(ArgumentError) { HTTP::URI.new(42) }
     end
 
-    it "works with no arguments (default empty Hash)" do
+    it "works with no arguments" do
       uri = HTTP::URI.new
 
       assert_instance_of HTTP::URI, uri
     end
-
-    it "accepts a Hash subclass" do
-      subclass = Class.new(Hash)
-      opts = subclass[scheme: "http", host: "example.com"]
-      uri = HTTP::URI.new(opts)
-
-      assert_equal "http://example.com", uri.to_s
-    end
   end
 
   describe "#deconstruct_keys" do