http 5.3.1 → 6.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b6053cab7210860d3464e9441746186b46c7ac1dc5716ea59cc69dff0d4ef460
-  data.tar.gz: 49f6d6c66a674e792208f1c17fff2c5dd8fdda330c6bdbabbaddec1f69eebac8
+  metadata.gz: 96efa876d9e4c3e5bb5100ab7862338a66b435d02a93e19075f2755a396acd7b
+  data.tar.gz: 3d91fccfe7a3e616dcb892fe416b6d1cffbadea286c492f524093ba1bfbdcdeb
 SHA512:
-  metadata.gz: 11585d59c45a6e762e6df8792e30107ec1011440ddc4597ad63f4ab5951f0e5c3fd801153bdb32bf74cae90c8ca716368003b3fb59cd98d8dc28c595899be177
-  data.tar.gz: 481d4f96d65e80226f505b93ff0da954ee4d0c3ee443d6dd4b72711cd0b44ae95c150eeb82d24442a34105dbb75013cb689f4b2ee0a2272d8320b473d91fc72d
+  metadata.gz: de74b67fced0df2fc1093d4eb6969edddd43d2f7da5dec73d1ee54bff44712ac173ac3141e909c0f061ab3323820b9498028e5cebc11b74282feab70ef730d33
+  data.tar.gz: 361e27f92a887ccf3bd220188e60e9feed23cf750b4e13f8acb2085f0b9beddc381f504f3fa7c4bfe1ddb8dada2f0014141a3a3e2cf575681f39e23f39d8ef66

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2011-2022 Tony Arcieri, Erik Michaels-Ober, Alexey V. Zapparov, Zachary Anker
+Copyright (c) 2011-2026 Tony Arcieri, Erik Berlin, Alexey V. Zapparov, Zachary Anker
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -2,8 +2,11 @@
 
 [![Gem Version][gem-image]][gem-link]
 [![MIT licensed][license-image]][license-link]
-[![Build Status][build-image]][build-link]
-[![Code Climate][codeclimate-image]][codeclimate-link]
+[![Docs][docs-image]][docs-link]
+[![Lint][lint-image]][lint-link]
+[![Mutant][mutant-image]][mutant-link]
+[![Test][test-image]][test-link]
+[![Typecheck][typecheck-image]][typecheck-link]
 
 [Documentation]
 
@@ -105,18 +108,91 @@ and call `#readpartial` on it repeatedly until it returns `nil`:
 => nil
 ```
 
+### Pattern Matching
+
+Response objects support Ruby's pattern matching:
+
+```ruby
+case HTTP.get("https://api.example.com/users")
+in { status: 200..299, body: body }
+  JSON.parse(body.to_s)
+in { status: 404 }
+  nil
+in { status: 400.. }
+  raise "request failed"
+end
+```
+
+Pattern matching is also supported on `HTTP::Response::Status`, `HTTP::Headers`,
+`HTTP::ContentType`, and `HTTP::URI`.
+
+### Base URI
+
+Set a base URI to avoid repeating the scheme and host in every request:
+
+```ruby
+api = HTTP.base_uri("https://api.example.com/v1")
+api.get("users")       # GET https://api.example.com/v1/users
+api.get("users/1")     # GET https://api.example.com/v1/users/1
+```
+
+Relative paths are resolved per [RFC 3986](https://www.rfc-editor.org/rfc/rfc3986#section-5).
+Combine with `persistent` to reuse the connection:
+
+```ruby
+HTTP.base_uri("https://api.example.com/v1").persistent do |http|
+  http.get("users")
+  http.get("posts")
+end
+```
+
+### Thread Safety
+
+Configured sessions are safe to share across threads:
+
+```ruby
+# Build a session once, use it from any thread
+session = HTTP.headers("Accept" => "application/json")
+              .timeout(10)
+              .auth("Bearer token")
+
+threads = 10.times.map do
+  Thread.new { session.get("https://example.com/api/data") }
+end
+threads.each(&:join)
+```
+
+Chainable configuration methods (`.headers`, `.timeout`, `.auth`, etc.) return
+an `HTTP::Session`, which creates a fresh `HTTP::Client` for every request.
+
+Persistent connections (`HTTP.persistent`) return an `HTTP::Session` that pools
+one `HTTP::Client` per origin. The session itself is **not** thread-safe. For
+thread-safe persistent connections, use the
+[connection_pool](https://rubygems.org/gems/connection_pool) gem:
+
+```ruby
+pool = ConnectionPool.new(size: 5) { HTTP.persistent("https://example.com") }
+pool.with { |http| http.get("/path") }
+```
+
+Cross-origin redirects are handled transparently — the session opens a separate
+persistent connection for each origin encountered during a redirect chain:
+
+```ruby
+HTTP.persistent("https://example.com").follow do |http|
+  http.get("/moved-to-other-domain")  # follows redirect across origins
+end
+```
+
 ## Supported Ruby Versions
 
 This library aims to support and is [tested against][build-link]
 the following Ruby  versions:
 
-- JRuby 9.3
-- Ruby 2.6
-- Ruby 2.7
-- Ruby 3.0
-- Ruby 3.1
 - Ruby 3.2
 - Ruby 3.3
+- Ruby 3.4
+- Ruby 4.0
 
 If something doesn't work on one of these versions, it's a bug.
 
@@ -132,8 +208,20 @@ exist at the time of a major release, support for that Ruby version may be
 dropped.
 
 
+## Upgrading
+
+See [UPGRADING.md] for a detailed migration guide between major versions.
+
+
+## Security
+
+See [SECURITY.md] for reporting vulnerabilities.
+
+
 ## Contributing to http.rb
 
+See [CONTRIBUTING.md] for guidelines, or the quick version:
+
 - Fork http.rb on GitHub
 - Make your changes
 - Ensure all tests pass (`bundle exec rake`)
@@ -144,7 +232,7 @@ dropped.
 
 ## Copyright
 
-Copyright © 2011-2022 Tony Arcieri, Alexey V. Zapparov, Erik Michaels-Ober, Zachary Anker.
+Copyright © 2011-2026 Tony Arcieri, Erik Berlin, Alexey V. Zapparov, Zachary Anker.
 See LICENSE.txt for further details.
 
 
@@ -154,13 +242,22 @@ See LICENSE.txt for further details.
 [gem-link]: https://rubygems.org/gems/http
 [license-image]: https://img.shields.io/badge/license-MIT-blue.svg
 [license-link]: https://github.com/httprb/http/blob/main/LICENSE.txt
-[build-image]: https://github.com/httprb/http/workflows/CI/badge.svg
-[build-link]: https://github.com/httprb/http/actions/workflows/ci.yml
-[codeclimate-image]: https://codeclimate.com/github/httprb/http.svg?branch=main
-[codeclimate-link]: https://codeclimate.com/github/httprb/http
+[docs-image]: https://github.com/httprb/http/actions/workflows/docs.yml/badge.svg
+[docs-link]: https://github.com/httprb/http/actions/workflows/docs.yml
+[lint-image]: https://github.com/httprb/http/actions/workflows/lint.yml/badge.svg
+[lint-link]: https://github.com/httprb/http/actions/workflows/lint.yml
+[mutant-image]: https://github.com/httprb/http/actions/workflows/mutant.yml/badge.svg
+[mutant-link]: https://github.com/httprb/http/actions/workflows/mutant.yml
+[test-image]: https://github.com/httprb/http/actions/workflows/test.yml/badge.svg
+[test-link]: https://github.com/httprb/http/actions/workflows/test.yml
+[typecheck-image]: https://github.com/httprb/http/actions/workflows/typecheck.yml/badge.svg
+[typecheck-link]: https://github.com/httprb/http/actions/workflows/typecheck.yml
 
 [//]: # (links)
 
+[contributing.md]: https://github.com/httprb/http/blob/main/CONTRIBUTING.md
 [documentation]: https://github.com/httprb/http/wiki
-[requests]: https://docs.python-requests.org/en/latest/
 [llhttp]: https://llhttp.org/
+[requests]: https://docs.python-requests.org/en/latest/
+[security.md]: https://github.com/httprb/http/blob/main/SECURITY.md
+[upgrading.md]: https://github.com/httprb/http/blob/main/UPGRADING.md

data/http.gemspec

@@ -1,45 +1,48 @@
 # frozen_string_literal: true
 
-lib = File.expand_path("lib", __dir__)
-$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require "http/version"
+require_relative "lib/http/version"
 
-Gem::Specification.new do |gem|
-  gem.authors       = ["Tony Arcieri", "Erik Michaels-Ober", "Alexey V. Zapparov", "Zachary Anker"]
-  gem.email         = ["bascule@gmail.com"]
+Gem::Specification.new do |spec|
+  spec.name          = "http"
+  spec.version       = HTTP::VERSION
+  spec.authors       = ["Tony Arcieri", "Erik Berlin", "Alexey V. Zapparov", "Zachary Anker"]
+  spec.email         = ["bascule@gmail.com"]
 
-  gem.description   = <<-DESCRIPTION.strip.gsub(/\s+/, " ")
+  spec.summary       = "HTTP should be easy"
+  spec.homepage      = "https://github.com/httprb/http"
+  spec.license       = "MIT"
+
+  spec.description   = <<~DESCRIPTION.strip.gsub(/\s+/, " ")
     An easy-to-use client library for making requests from Ruby.
     It uses a simple method chaining system for building requests,
     similar to Python's Requests.
   DESCRIPTION
 
-  gem.summary       = "HTTP should be easy"
-  gem.homepage      = "https://github.com/httprb/http"
-  gem.licenses      = ["MIT"]
+  spec.metadata["homepage_uri"]          = spec.homepage
+  spec.metadata["source_code_uri"]       = "#{spec.homepage}/tree/v#{spec.version}"
+  spec.metadata["bug_tracker_uri"]       = "#{spec.homepage}/issues"
+  spec.metadata["changelog_uri"]         = "#{spec.homepage}/blob/v#{spec.version}/CHANGELOG.md"
+  spec.metadata["documentation_uri"]     = "https://www.rubydoc.info/gems/http/#{spec.version}"
+  spec.metadata["rubygems_mfa_required"] = "true"
 
-  gem.executables   = `git ls-files -- bin/*`.split("\n").map { |f| File.basename(f) }
-  gem.files         = `git ls-files`.split("\n")
-  gem.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
-  gem.name          = "http"
-  gem.require_paths = ["lib"]
-  gem.version       = HTTP::VERSION
+  spec.files = IO.popen(%w[git ls-files -z], chdir: __dir__, err: IO::NULL) do |ls|
+    extras = %w[LICENSE.txt README.md sig/http.rbs] << File.basename(__FILE__)
 
-  gem.required_ruby_version = ">= 2.6"
+    ls.readlines("\x0", chomp: true).select do |f|
+      f.start_with?("lib/") || extras.include?(f)
+    end
+  end
 
-  gem.add_runtime_dependency "addressable",    "~> 2.8"
-  gem.add_runtime_dependency "http-cookie",    "~> 1.0"
-  gem.add_runtime_dependency "http-form_data", "~> 2.2"
+  spec.require_paths = ["lib"]
 
-  gem.add_runtime_dependency "llhttp-ffi", "~> 0.5.0"
+  spec.required_ruby_version = ">= 3.2"
 
-  gem.add_development_dependency "bundler", "~> 2.0"
+  spec.add_dependency "http-cookie", "~> 1.0"
 
-  gem.metadata = {
-    "source_code_uri"       => "https://github.com/httprb/http",
-    "wiki_uri"              => "https://github.com/httprb/http/wiki",
-    "bug_tracker_uri"       => "https://github.com/httprb/http/issues",
-    "changelog_uri"         => "https://github.com/httprb/http/blob/v#{HTTP::VERSION}/CHANGELOG.md",
-    "rubygems_mfa_required" => "true"
-  }
+  if RUBY_ENGINE == "jruby"
+    spec.platform = "java" if ENV["HTTP_PLATFORM"] == "java"
+    spec.add_dependency "llhttp-ffi", "~> 0.5.1"
+  else
+    spec.add_dependency "llhttp", "~> 0.6.1"
+  end
 end

data/lib/http/base64.rb

@@ -1,10 +1,20 @@
 # frozen_string_literal: true
 
 module HTTP
+  # Strict Base64 encoding utilities
   module Base64
     module_function
 
-    # Equivalent to Base64.strict_encode64
+    # Encode data using strict Base64 encoding
+    #
+    # @example
+    #   HTTP::Base64.encode64("hello")
+    #
+    # @param input [String] data to encode
+    #
+    # @return [String]
+    #
+    # @api private
     def encode64(input)
       [input].pack("m0")
     end

data/lib/http/chainable/helpers.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module HTTP
+  # HTTP verb methods and client configuration DSL
+  module Chainable
+    # Mapping of proxy argument positions to hash keys and expected types
+    PROXY_ARG_MAP = [
+      [:proxy_address,  0, String],
+      [:proxy_port,     1, Integer],
+      [:proxy_username, 2, String],
+      [:proxy_password, 3, String],
+      [:proxy_headers,  2, Hash],
+      [:proxy_headers,  4, Hash]
+    ].freeze
+
+    private
+
+    # Build proxy configuration hash from positional arguments
+    #
+    # @param [Array] proxy positional proxy arguments
+    # @return [Hash] proxy configuration
+    # @api private
+    def build_proxy_hash(proxy)
+      result = {} #: Hash[Symbol, untyped]
+      PROXY_ARG_MAP.each do |key, index, type|
+        result[key] = proxy[index] if proxy[index].is_a?(type)
+      end
+      result
+    end
+
+    # Resolve a timeout hash into a timeout class and normalized options
+    #
+    # @example
+    #   resolve_timeout_hash(global: 60, read: 30)
+    #
+    # @param [Hash] options timeout options
+    # @return [Array(Class, Hash)] timeout class and normalized options
+    # @raise [ArgumentError] if options are invalid
+    # @api private
+    def resolve_timeout_hash(options)
+      remaining = options.dup
+      global = HTTP::Timeout::PerOperation.send(:extract_global_timeout!, remaining)
+
+      return resolve_global_only(global) if remaining.empty?
+
+      per_op = HTTP::Timeout::PerOperation.normalize_options(remaining)
+      global ? [HTTP::Timeout::Global, per_op.merge(global_timeout: global)] : [HTTP::Timeout::PerOperation, per_op]
+    end
+
+    # Build options for a global-only timeout from a hash
+    #
+    # @param [Numeric, nil] global the global timeout value
+    # @return [Array(Class, Hash)] timeout class and options
+    # @raise [ArgumentError] if no global timeout given
+    # @api private
+    def resolve_global_only(global)
+      raise ArgumentError, "no timeout options given" unless global
+
+      [HTTP::Timeout::Global, { global_timeout: global }]
+    end
+  end
+end

data/lib/http/chainable/verbs.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module HTTP
+  module Chainable
+    # HTTP verb shortcut methods
+    #
+    # Each method delegates to {Chainable#request} with the appropriate verb.
+    module Verbs
+      # Request a get sans response body
+      #
+      # @example
+      #   HTTP.head("http://example.com")
+      #
+      # @param [String, URI] uri URI to request
+      # @param options [Hash] request options
+      # @yieldparam response [HTTP::Response] the response
+      # @return [HTTP::Response, Object] the response, or block return value
+      # @api public
+      def head(uri, **, &)
+        request(:head, uri, **, &) # steep:ignore
+      end
+
+      # Get a resource
+      #
+      # @example
+      #   HTTP.get("http://example.com")
+      #
+      # @param [String, URI] uri URI to request
+      # @param options [Hash] request options
+      # @yieldparam response [HTTP::Response] the response
+      # @return [HTTP::Response, Object] the response, or block return value
+      # @api public
+      def get(uri, **, &)
+        request(:get, uri, **, &) # steep:ignore
+      end
+
+      # Post to a resource
+      #
+      # @example
+      #   HTTP.post("http://example.com", body: "data")
+      #
+      # @param [String, URI] uri URI to request
+      # @param options [Hash] request options
+      # @yieldparam response [HTTP::Response] the response
+      # @return [HTTP::Response, Object] the response, or block return value
+      # @api public
+      def post(uri, **, &)
+        request(:post, uri, **, &) # steep:ignore
+      end
+
+      # Put to a resource
+      #
+      # @example
+      #   HTTP.put("http://example.com", body: "data")
+      #
+      # @param [String, URI] uri URI to request
+      # @param options [Hash] request options
+      # @yieldparam response [HTTP::Response] the response
+      # @return [HTTP::Response, Object] the response, or block return value
+      # @api public
+      def put(uri, **, &)
+        request(:put, uri, **, &) # steep:ignore
+      end
+
+      # Delete a resource
+      #
+      # @example
+      #   HTTP.delete("http://example.com/resource")
+      #
+      # @param [String, URI] uri URI to request
+      # @param options [Hash] request options
+      # @yieldparam response [HTTP::Response] the response
+      # @return [HTTP::Response, Object] the response, or block return value
+      # @api public
+      def delete(uri, **, &)
+        request(:delete, uri, **, &) # steep:ignore
+      end
+
+      # Echo the request back to the client
+      #
+      # @example
+      #   HTTP.trace("http://example.com")
+      #
+      # @param [String, URI] uri URI to request
+      # @param options [Hash] request options
+      # @yieldparam response [HTTP::Response] the response
+      # @return [HTTP::Response, Object] the response, or block return value
+      # @api public
+      def trace(uri, **, &)
+        request(:trace, uri, **, &) # steep:ignore
+      end
+
+      # Return the methods supported on the given URI
+      #
+      # @example
+      #   HTTP.options("http://example.com")
+      #
+      # @param [String, URI] uri URI to request
+      # @param options [Hash] request options
+      # @yieldparam response [HTTP::Response] the response
+      # @return [HTTP::Response, Object] the response, or block return value
+      # @api public
+      def options(uri, **, &)
+        request(:options, uri, **, &) # steep:ignore
+      end
+
+      # Convert to a transparent TCP/IP tunnel
+      #
+      # @example
+      #   HTTP.connect("http://example.com")
+      #
+      # @param [String, URI] uri URI to request
+      # @param options [Hash] request options
+      # @yieldparam response [HTTP::Response] the response
+      # @return [HTTP::Response, Object] the response, or block return value
+      # @api public
+      def connect(uri, **, &)
+        request(:connect, uri, **, &) # steep:ignore
+      end
+
+      # Apply partial modifications to a resource
+      #
+      # @example
+      #   HTTP.patch("http://example.com/resource", body: "data")
+      #
+      # @param [String, URI] uri URI to request
+      # @param options [Hash] request options
+      # @yieldparam response [HTTP::Response] the response
+      # @return [HTTP::Response, Object] the response, or block return value
+      # @api public
+      def patch(uri, **, &)
+        request(:patch, uri, **, &) # steep:ignore
+      end
+    end
+  end
+end