httpx 1.0.2 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a0f330c17658b6d488b83008df23e73eb276c04fb93f6e72093224a1a6e1d839
-  data.tar.gz: 75fea2fe69162c00d371ca83f121883d435be3d7d0749f1f2dce71332c6f18d2
+  metadata.gz: 7ef9f0a027f7a313547ca11bce6cf2c5a3eb72075b2cee0be13448d4aa7ec2b6
+  data.tar.gz: 0021a6c5e4968dd68cb23a157c5ce0dd84021bf134eb6c8227c5b145772e5812
 SHA512:
-  metadata.gz: 4c3bf06316177777f8802fc7662021e565ddc19590a2cad092ab3e05759fa778e7edd4f9b6ee9359b582d8828f669236be517129af57a12d17cfe71cde7adf06
-  data.tar.gz: 66ef58dbd0c3f4681bbde3e211afaaa7272d88aa4aa70e5791636147439a5bacb2bf85f89d0b33a792ddcf6444ae14e3c64685436b9cb849cb7fad30f3db1ef1
+  metadata.gz: 14687b4930aff7fef833058a27d5b26e4a9c327fcbf779f88d3b2b7766a861a26845285054ccde501a5a8296fdfc3c87a5f7e56eafc58fabeecd383512d36e8c
+  data.tar.gz: 95ee1b01958d2c680e194baa2f3136464c775038e9cd87d7d712d88998f48bbd385d6f3cc1173d2bda023102c4ca4661221aabd03d0d8a0a62e3006a79694851

data/README.md

@@ -108,8 +108,8 @@ HTTPX.get(
 ```ruby
 response = HTTPX.get("https://www.google.com", params: { q: "me" })
 response = HTTPX.post("https://www.nghttp2.org/httpbin/post", form: {name: "John", age: "22"})
-response = HTTPX.plugin(:basic_authentication)
-                .basic_authentication("user", "pass")
+response = HTTPX.plugin(:basic_auth)
+                .basic_auth("user", "pass")
                 .get("https://www.google.com")
 
 # more complex client objects can be cached, and are thread-safe

data/doc/release_notes/1_1_0.md

@@ -0,0 +1,32 @@
+# 1.1.0
+
+## Features
+
+A function, `#peer_address`, was added to the response object, which returns the IP (either a string or an `IPAddr` object) from the socket used to get the response from.
+
+```ruby
+response = HTTPX.get("https://example.com")
+response.peer_address #=> #<IPAddr: IPv4:93.184.216.34/255.255.255.255>
+```
+
+error responses will also expose an IP address via `#peer_address` as long a connection happened before the error.
+
+## Improvements
+
+* A performance regression involving the new default timeouts has been fixed, which could cause significant overhead in "multiple requests in sequence" scenarios, and was clearly visible in benchmarks.
+  * this regression will still be seen in jruby due to a bug, which fix will be released in jruby 9.4.5.0.
+* HTTP/1.1 connections are now set to handle as many requests as they can by default (instead of the past default of max 200, at which point they'd be recycled).
+* tolerate the inexistence of `openssl` in the installed ruby, like `net-http` does.
+* `on_connection_opened` and `on_connection_closed` will yield the `OpenSSL::SSL::SSLSocket` instance for `https` backed origins (instead of always the `Socket` instance).
+
+## Bugfixes
+
+* when using the `:native` resolver (default option), a default of 1 for ndots is set, for systems which do not set one.
+* replaced usage of `Float::INFINITY` with `nil` for timeout defaults, as the former can't be used in IO wait functions.
+* `faraday` adapter timeout setup now maps to `:read_timeout` and `:write_timeout` options from `httpx`.
+* fixed HTTP/1.1 connection recycling on number of max requests exhausted.
+* `response.json` will now work when "content-type" header is set to "application/hal+json".
+
+## Chore
+
+* when using the `:cookies` plugin, a warning message to install the idnx message will only be emitted if the cookie domain is an IDN (this message was being shown all the time since v1 release).

data/lib/httpx/adapters/faraday.rb

@@ -69,38 +69,47 @@ module Faraday
           timeout_options = {}
           req_opts = env.request
           if (sec = request_timeout(:read, req_opts))
-            timeout_options[:operation_timeout] = sec
+            timeout_options[:read_timeout] = sec
           end
 
           if (sec = request_timeout(:write, req_opts))
-            timeout_options[:operation_timeout] = sec
+            timeout_options[:write_timeout] = sec
           end
 
           if (sec = request_timeout(:open, req_opts))
             timeout_options[:connect_timeout] = sec
           end
 
-          ssl_options = {}
-
-          unless env.ssl.verify.nil?
-            ssl_options[:verify_mode] = env.ssl.verify ? OpenSSL::SSL::VERIFY_PEER : OpenSSL::SSL::VERIFY_NONE
-          end
-
-          ssl_options[:ca_file] = env.ssl.ca_file if env.ssl.ca_file
-          ssl_options[:ca_path] = env.ssl.ca_path if env.ssl.ca_path
-          ssl_options[:cert_store] = env.ssl.cert_store if env.ssl.cert_store
-          ssl_options[:cert] = env.ssl.client_cert if env.ssl.client_cert
-          ssl_options[:key] = env.ssl.client_key if env.ssl.client_key
-          ssl_options[:ssl_version] = env.ssl.version if env.ssl.version
-          ssl_options[:verify_depth] = env.ssl.verify_depth if env.ssl.verify_depth
-          ssl_options[:min_version] = env.ssl.min_version if env.ssl.min_version
-          ssl_options[:max_version] = env.ssl.max_version if env.ssl.max_version
-
           {
-            ssl: ssl_options,
+            ssl: ssl_options_from_env(env),
             timeout: timeout_options,
           }
         end
+
+        if defined?(::OpenSSL)
+          def ssl_options_from_env(env)
+            ssl_options = {}
+
+            unless env.ssl.verify.nil?
+              ssl_options[:verify_mode] = env.ssl.verify ? OpenSSL::SSL::VERIFY_PEER : OpenSSL::SSL::VERIFY_NONE
+            end
+
+            ssl_options[:ca_file] = env.ssl.ca_file if env.ssl.ca_file
+            ssl_options[:ca_path] = env.ssl.ca_path if env.ssl.ca_path
+            ssl_options[:cert_store] = env.ssl.cert_store if env.ssl.cert_store
+            ssl_options[:cert] = env.ssl.client_cert if env.ssl.client_cert
+            ssl_options[:key] = env.ssl.client_key if env.ssl.client_key
+            ssl_options[:ssl_version] = env.ssl.version if env.ssl.version
+            ssl_options[:verify_depth] = env.ssl.verify_depth if env.ssl.verify_depth
+            ssl_options[:min_version] = env.ssl.min_version if env.ssl.min_version
+            ssl_options[:max_version] = env.ssl.max_version if env.ssl.max_version
+            ssl_options
+          end
+        else
+          def ssl_options_from_env(*)
+            {}
+          end
+        end
       end
 
       include RequestMixin

data/lib/httpx/connection/http1.rb

@@ -15,7 +15,7 @@ module HTTPX
     def initialize(buffer, options)
       @options = Options.new(options)
       @max_concurrent_requests = @options.max_concurrent_requests || MAX_REQUESTS
-      @max_requests = @options.max_requests || MAX_REQUESTS
+      @max_requests = @options.max_requests
       @parser = Parser::HTTP1.new(self)
       @buffer = buffer
       @version = [1, 1]
@@ -184,7 +184,14 @@ module HTTPX
         manage_connection(response)
       end
 
-      send(@pending.shift) unless @pending.empty?
+      if exhausted?
+        @pending.concat(@requests)
+        @requests.clear
+
+        emit(:exhausted)
+      else
+        send(@pending.shift) unless @pending.empty?
+      end
     end
 
     def handle_error(ex)
@@ -287,7 +294,7 @@ module HTTPX
 
       connection = request.headers["connection"]
 
-      connection ||= if request.options.persistent
+      connection ||= if request.persistent?
         # when in a persistent connection, the request can't be at
         # the edge of a renegotiation
         if @requests.index(request) + 1 < @max_requests

data/lib/httpx/connection/http2.rb

@@ -35,7 +35,7 @@ module HTTPX
       @handshake_completed = false
       @wait_for_handshake = @settings.key?(:wait_for_handshake) ? @settings.delete(:wait_for_handshake) : true
       @max_concurrent_requests = @options.max_concurrent_requests || MAX_CONCURRENT_REQUESTS
-      @max_requests = @options.max_requests || Float::INFINITY
+      @max_requests = @options.max_requests
       init_connection
     end
 

data/lib/httpx/connection.rb

@@ -70,6 +70,8 @@ module HTTPX
       @inflight = 0
       @keep_alive_timeout = @options.timeout[:keep_alive_timeout]
 
+      @intervals = []
+
       self.addresses = @options.addresses if @options.addresses
     end
 
@@ -213,6 +215,9 @@ module HTTPX
 
     def call
       case @state
+      when :idle
+        connect
+        consume
       when :closed
         return
       when :closing
@@ -294,7 +299,15 @@ module HTTPX
       @state == :open || @state == :inactive
     end
 
-    def raise_timeout_error(interval)
+    def handle_socket_timeout(interval)
+      @intervals.delete_if(&:elapsed?)
+
+      unless @intervals.empty?
+        # remove the intervals which will elapse
+
+        return
+      end
+
       error = HTTPX::TimeoutError.new(interval, "timed out while waiting on select")
       error.set_backtrace(caller)
       on_error(error)
@@ -449,6 +462,7 @@ module HTTPX
 
     def send_request_to_parser(request)
       @inflight += 1
+      request.peer_address = @io.ip
       parser.send(request)
 
       set_request_timeouts(request)
@@ -655,19 +669,26 @@ module HTTPX
 
     def set_request_timeouts(request)
       write_timeout = request.write_timeout
-      request.once(:headers) do
-        @timers.after(write_timeout) { write_timeout_callback(request, write_timeout) }
-      end unless write_timeout.nil? || write_timeout.infinite?
-
       read_timeout = request.read_timeout
-      request.once(:done) do
-        @timers.after(read_timeout) { read_timeout_callback(request, read_timeout) }
-      end unless read_timeout.nil? || read_timeout.infinite?
-
       request_timeout = request.request_timeout
-      request.once(:headers) do
-        @timers.after(request_timeout) { read_timeout_callback(request, request_timeout, RequestTimeoutError) }
-      end unless request_timeout.nil? || request_timeout.infinite?
+
+      unless write_timeout.nil? || write_timeout.infinite?
+        set_request_timeout(request, write_timeout, :headers, %i[done response]) do
+          write_timeout_callback(request, write_timeout)
+        end
+      end
+
+      unless read_timeout.nil? || read_timeout.infinite?
+        set_request_timeout(request, read_timeout, :done, :response) do
+          read_timeout_callback(request, read_timeout)
+        end
+      end
+
+      return if request_timeout.nil? || request_timeout.infinite?
+
+      set_request_timeout(request, request_timeout, :headers, :response) do
+        read_timeout_callback(request, request_timeout, RequestTimeoutError)
+      end
     end
 
     def write_timeout_callback(request, write_timeout)
@@ -688,6 +709,24 @@ module HTTPX
       on_error(error)
     end
 
+    def set_request_timeout(request, timeout, start_event, finish_events, &callback)
+      request.once(start_event) do
+        interval = @timers.after(timeout, callback)
+
+        Array(finish_events).each do |event|
+          # clean up reques timeouts if the connection errors out
+          request.once(event) do
+            if @intervals.include?(interval)
+              interval.delete(callback)
+              @intervals.delete(interval) if interval.no_callbacks?
+            end
+          end
+        end
+
+        @intervals << interval
+      end
+    end
+
     class << self
       def parser_type(protocol)
         case protocol

data/lib/httpx/domain_name.rb

@@ -61,8 +61,12 @@ module HTTPX
       # Normalizes a _domain_ using the Punycode algorithm as necessary.
       # The result will be a downcased, ASCII-only string.
       def normalize(domain)
-        domain = domain.chomp(".").unicode_normalize(:nfc) unless domain.ascii_only?
-        Punycode.encode_hostname(domain).downcase
+        unless domain.ascii_only?
+          domain = domain.chomp(".").unicode_normalize(:nfc)
+          domain = Punycode.encode_hostname(domain)
+        end
+
+        domain.downcase
       end
     end
 

data/lib/httpx/errors.rb

@@ -1,20 +1,27 @@
 # frozen_string_literal: true
 
 module HTTPX
+  # the default exception class for exceptions raised by HTTPX.
   class Error < StandardError; end
 
   class UnsupportedSchemeError < Error; end
 
   class ConnectionError < Error; end
 
+  # Error raised when there was a timeout. Its subclasses allow for finer-grained
+  # control of which timeout happened.
   class TimeoutError < Error
+    # The timeout value which caused this error to be raised.
     attr_reader :timeout
 
+    # initializes the timeout exception with the +timeout+ causing the error, and the
+    # error +message+ for it.
     def initialize(timeout, message)
       @timeout = timeout
       super(message)
     end
 
+    # clones this error into a HTTPX::ConnectionTimeoutError.
     def to_connection_error
       ex = ConnectTimeoutError.new(@timeout, message)
       ex.set_backtrace(backtrace)
@@ -22,11 +29,19 @@ module HTTPX
     end
   end
 
+  # Error raised when there was a timeout establishing the connection to a server.
+  # This may be raised due to timeouts during TCP and TLS (when applicable) connection
+  # establishment.
   class ConnectTimeoutError < TimeoutError; end
 
+  # Error raised when there was a timeout while sending a request, or receiving a response
+  # from the server.
   class RequestTimeoutError < TimeoutError
+    # The HTTPX::Request request object this exception refers to.
     attr_reader :request
 
+    # initializes the exception with the +request+ and +response+ it refers to, and the
+    # +timeout+ causing the error, and the
     def initialize(request, response, timeout)
       @request = request
       @response = response
@@ -38,19 +53,28 @@ module HTTPX
     end
   end
 
+  # Error raised when there was a timeout while receiving a response from the server.
   class ReadTimeoutError < RequestTimeoutError; end
 
+  # Error raised when there was a timeout while sending a request from the server.
   class WriteTimeoutError < RequestTimeoutError; end
 
+  # Error raised when there was a timeout while waiting for the HTTP/2 settings frame from the server.
   class SettingsTimeoutError < TimeoutError; end
 
+  # Error raised when there was a timeout while resolving a domain to an IP.
   class ResolveTimeoutError < TimeoutError; end
 
+  # Error raised when there was an error while resolving a domain to an IP.
   class ResolveError < Error; end
 
+  # Error raised when there was an error while resolving a domain to an IP
+  # using a HTTPX::Resolver::Native resolver.
   class NativeResolveError < ResolveError
     attr_reader :connection, :host
 
+    # initializes the exception with the +connection+ it refers to, the +host+ domain
+    # which failed to resolve, and the error +message+.
     def initialize(connection, host, message = "Can't resolve #{host}")
       @connection = connection
       @host = host
@@ -58,18 +82,26 @@ module HTTPX
     end
   end
 
+  # The exception class for HTTP responses with 4xx or 5xx status.
   class HTTPError < Error
+    # The HTTPX::Response response object this exception refers to.
     attr_reader :response
 
+    # Creates the instance and assigns the HTTPX::Response +response+.
     def initialize(response)
       @response = response
       super("HTTP Error: #{@response.status} #{@response.headers}\n#{@response.body}")
     end
 
+    # The HTTP response status.
+    #
+    #   error.status #=> 404
     def status
       @response.status
     end
   end
 
+  # error raised when a request was sent a server which can't reproduce a response, and
+  # has therefore returned an HTTP response using the 421 status code.
   class MisdirectedRequestError < HTTPError; end
 end

data/lib/httpx/io/ssl.rb

@@ -114,7 +114,9 @@ module HTTPX
     end
 
     def try_ssl_connect
-      case @io.connect_nonblock(exception: false)
+      ret = @io.connect_nonblock(exception: false)
+      log(level: 3, color: :cyan) { "TLS CONNECT: #{ret}..." }
+      case ret
       when :wait_readable
         @interests = :r
         return

data/lib/httpx/io/tcp.rb

@@ -41,7 +41,7 @@ module HTTPX
     end
 
     def socket
-      @io.to_io
+      @io
     end
 
     def add_addresses(addrs)
@@ -95,7 +95,9 @@ module HTTPX
     end
 
     def try_connect
-      case @io.connect_nonblock(Socket.sockaddr_in(@port, @ip.to_s), exception: false)
+      ret = @io.connect_nonblock(Socket.sockaddr_in(@port, @ip.to_s), exception: false)
+      log(level: 3, color: :cyan) { "TCP CONNECT: #{ret}..." }
+      case ret
       when :wait_readable
         @interests = :r
         return

data/lib/httpx/io.rb

@@ -4,4 +4,8 @@ require "socket"
 require "httpx/io/udp"
 require "httpx/io/tcp"
 require "httpx/io/unix"
-require "httpx/io/ssl"
+
+begin
+  require "httpx/io/ssl"
+rescue LoadError
+end

data/lib/httpx/options.rb

@@ -3,6 +3,8 @@
 require "socket"
 
 module HTTPX
+  # Contains a set of options which are passed and shared across from session to its requests or
+  # responses.
   class Options
     BUFFER_SIZE = 1 << 14
     WINDOW_SIZE = 1 << 14 # 16K
@@ -10,7 +12,7 @@ module HTTPX
     KEEP_ALIVE_TIMEOUT = 20
     SETTINGS_TIMEOUT = 10
     CONNECT_TIMEOUT = READ_TIMEOUT = WRITE_TIMEOUT = 60
-    REQUEST_TIMEOUT = OPERATION_TIMEOUT = Float::INFINITY
+    REQUEST_TIMEOUT = OPERATION_TIMEOUT = nil
 
     # https://github.com/ruby/resolv/blob/095f1c003f6073730500f02acbdbc55f83d70987/lib/resolv.rb#L408
     ip_address_families = begin
@@ -25,6 +27,7 @@ module HTTPX
     end
 
     DEFAULT_OPTIONS = {
+      :max_requests => Float::INFINITY,
       :debug => ENV.key?("HTTPX_DEBUG") ? $stderr : nil,
       :debug_level => (ENV["HTTPX_DEBUG"] || 1).to_i,
       :ssl => {},
@@ -81,6 +84,50 @@ module HTTPX
       end
     end
 
+    # creates a new options instance from a given hash, which optionally define the following:
+    #
+    # :debug :: an object which log messages are written to (must respond to <tt><<</tt>)
+    # :debug_level :: the log level of messages (can be 1, 2, or 3).
+    # :ssl :: a hash of options which can be set as params of OpenSSL::SSL::SSLContext (see HTTPX::IO::SSL)
+    # :http2_settings :: a hash of options to be passed to a HTTP2Next::Connection (ex: <tt>{ max_concurrent_streams: 2 }</tt>)
+    # :fallback_protocol :: version of HTTP protocol to use by default in the absence of protocol negotiation
+    #                       like ALPN (defaults to <tt>"http/1.1"</tt>)
+    # :supported_compression_formats :: list of compressions supported by the transcoder layer (defaults to <tt>%w[gzip deflate]</tt>).
+    # :decompress_response_body :: whether to auto-decompress response body (defaults to <tt>true</tt>).
+    # :compress_request_body :: whether to auto-decompress response body (defaults to <tt>true</tt>)
+    # :timeout :: hash of timeout configurations (supports <tt>:connect_timeout</tt>, <tt>:settings_timeout</tt>,
+    #             <tt>:operation_timeout</tt>, <tt>:keep_alive_timeout</tt>,  <tt>:read_timeout</tt>,  <tt>:write_timeout</tt>
+    #            and <tt>:request_timeout</tt>
+    # :headers :: hash of HTTP headers (ex: <tt>{ "x-custom-foo" => "bar" }</tt>)
+    # :window_size :: number of bytes to read from a socket
+    # :buffer_size :: internal read and write buffer size in bytes
+    # :body_threshold_size :: maximum size in bytes of response payload that is buffered in memory.
+    # :request_class :: class used to instantiate a request
+    # :response_class :: class used to instantiate a response
+    # :headers_class :: class used to instantiate headers
+    # :request_body_class :: class used to instantiate a request body
+    # :response_body_class :: class used to instantiate a response body
+    # :connection_class :: class used to instantiate connections
+    # :options_class :: class used to instantiate options
+    # :transport :: type of transport to use (set to "unix" for UNIX sockets)
+    # :addresses :: bucket of peer addresses (can be a list of IP addresses, a hash of domain to list of adddresses;
+    #               paths should be used for UNIX sockets instead)
+    # :io :: open socket, or domain/ip-to-socket hash, which requests should be sent to
+    # :persistent :: whether to persist connections in between requests (defaults to <tt>true</tt>)
+    # :resolver_class :: which resolver to use (defaults to <tt>:native</tt>, can also be <tt>:system<tt> for
+    #                    using getaddrinfo or <tt>:https</tt> for DoH resolver, or a custom class)
+    # :resolver_options :: hash of options passed to the resolver
+    # :ip_families :: which socket families are supported (system-dependent)
+    # :origin :: HTTP origin to set on requests with relative path (ex: "https://api.serv.com")
+    # :base_path :: path to prefix given relative paths with (ex: "/v2")
+    # :max_concurrent_requests :: max number of requests which can be set concurrently
+    # :max_requests :: max number of requests which can be made on socket before it reconnects.
+    # :params :: hash or array of key-values which will be encoded and set in the query string of request uris.
+    # :form :: hash of array of key-values which will be form-or-multipart-encoded in requests body payload.
+    # :json :: hash of array of key-values which will be JSON-encoded in requests body payload.
+    # :xml :: Nokogiri XML nodes which will be encoded in requests body payload.
+    #
+    # This list of options are enhanced with each loaded plugin, see the plugin docs for details.
     def initialize(options = {})
       do_initialize(options)
       freeze

data/lib/httpx/plugins/expect.rb

@@ -75,14 +75,16 @@ module HTTPX
 
           return unless request.headers["expect"] == "100-continue"
 
-          request.once(:expect) do
-            @timers.after(request.options.expect_timeout) do
-              # expect timeout expired
-              if request.state == :expect && !request.expects?
-                Expect.no_expect_store << request.origin
-                request.headers.delete("expect")
-                consume
-              end
+          expect_timeout = request.options.expect_timeout
+
+          return if expect_timeout.nil? || expect_timeout.infinite?
+
+          set_request_timeout(request, expect_timeout, :expect, %i[body response]) do
+            # expect timeout expired
+            if request.state == :expect && !request.expects?
+              Expect.no_expect_store << request.origin
+              request.headers.delete("expect")
+              consume
             end
           end
         end

data/lib/httpx/pool.rb

@@ -52,7 +52,6 @@ module HTTPX
     def close(connections = @connections)
       return if connections.empty?
 
-      @timers.cancel
       @eden_connections.clear
       connections = connections.reject(&:inflight?)
       connections.each(&:close)

data/lib/httpx/request/body.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module HTTPX
+  # Implementation of the HTTP Request body as a delegator which iterates (responds to +each+) payload chunks.
   class Request::Body < SimpleDelegator
     class << self
       def new(_, options)
@@ -10,13 +11,11 @@ module HTTPX
       end
     end
 
-    attr_reader :threshold_size
-
+    # inits the instance with the request +headers+ and +options+, which contain the payload definition.
     def initialize(headers, options)
       @headers = headers
-      @threshold_size = options.body_threshold_size
 
-      # forego compression in the Range cases
+      # forego compression in the Range request case
       if @headers.key?("range")
         @headers.delete("accept-encoding")
       else
@@ -32,6 +31,7 @@ module HTTPX
       super(@body)
     end
 
+    # consumes and yields the request payload in chunks.
     def each(&block)
       return enum_for(__method__) unless block
       return if @body.nil?
@@ -46,12 +46,14 @@ module HTTPX
       end
     end
 
+    # if the +@body+ is rewindable, it rewinnds it.
     def rewind
       return if empty?
 
       @body.rewind if @body.respond_to?(:rewind)
     end
 
+    # return +true+ if the +body+ has been fully drained (or does nnot exist).
     def empty?
       return true if @body.nil?
       return false if chunked?
@@ -59,28 +61,33 @@ module HTTPX
       @body.bytesize.zero?
     end
 
+    # returns the +@body+ payload size in bytes.
     def bytesize
       return 0 if @body.nil?
 
       @body.bytesize
     end
 
+    # sets the body to yield using chunked trannsfer encoding format.
     def stream(body)
       encoded = body
       encoded = Transcoder::Chunker.encode(body.enum_for(:each)) if chunked?
       encoded
     end
 
+    # returns whether the body yields infinitely.
     def unbounded_body?
       return @unbounded_body if defined?(@unbounded_body)
 
       @unbounded_body = !@body.nil? && (chunked? || @body.bytesize == Float::INFINITY)
     end
 
+    # returns whether the chunked transfer encoding header is set.
     def chunked?
       @headers["transfer-encoding"] == "chunked"
     end
 
+    # sets the chunked transfer encoding header.
     def chunk!
       @headers.add("transfer-encoding", "chunked")
     end
@@ -94,6 +101,13 @@ module HTTPX
 
     private
 
+    # wraps the given body with the appropriate encoder.
+    #
+    #   ..., json: { foo: "bar" }) #=> json encoder
+    #   ..., form: { foo: "bar" }) #=> form urlencoded encoder
+    #   ..., form: { foo: Pathname.open("path/to/file") }) #=> multipart urlencoded encoder
+    #   ..., form: { foo: File.open("path/to/file") }) #=> multipart urlencoded encoder
+    #   ..., form: { body: "bla") }) #=> raw data encoder
     def initialize_body(options)
       @body = if options.body
         Transcoder::Body.encode(options.body)
@@ -105,11 +119,7 @@ module HTTPX
         Transcoder::Xml.encode(options.xml)
       end
 
-      return unless @body
-
-      return unless options.compress_request_body
-
-      return unless @headers.key?("content-encoding")
+      return unless @body && options.compress_request_body && @headers.key?("content-encoding")
 
       @headers.get("content-encoding").each do |encoding|
         @body = self.class.initialize_deflater_body(@body, encoding)
@@ -117,6 +127,7 @@ module HTTPX
     end
 
     class << self
+      # returns the +body+ wrapped with the correct deflater accordinng to the given +encodisng+.
       def initialize_deflater_body(body, encoding)
         case encoding
         when "gzip"
@@ -132,11 +143,13 @@ module HTTPX
     end
   end
 
+  # Wrapper yielder which can be used with functions which expect an IO writer.
   class ProcIO
     def initialize(block)
       @block = block
     end
 
+    # Implementation the IO write protocol, which yield the given chunk to +@block+.
     def write(data)
       @block.call(data.dup)
       data.bytesize