httpx 1.0.2 → 1.1.1

data/lib/httpx/response.rb

@@ -7,24 +7,48 @@ require "fileutils"
 require "forwardable"
 
 module HTTPX
+  # Defines a HTTP response is handled internally, with a few properties exposed as attributes,
+  # implements (indirectly, via the +body+) the IO write protocol to internally buffer payloads,
+  # implements the IO reader protocol in order for users to buffer/stream it, acts as an enumerable
+  # (of payload chunks).
   class Response
     extend Forwardable
     include Callbacks
 
-    attr_reader :status, :headers, :body, :version
+    # the HTTP response status code
+    attr_reader :status
 
+    # an HTTPX::Headers object containing the response HTTP headers.
+    attr_reader :headers
+
+    # a HTTPX::Response::Body object wrapping the response body.
+    attr_reader  :body
+
+    # The HTTP protocol version used to fetch the response.
+    attr_reader  :version
+
+    # returns the response body buffered in a string.
     def_delegator :@body, :to_s
 
     def_delegator :@body, :to_str
 
+    # implements the IO reader +#read+ interface.
     def_delegator :@body, :read
 
+    # copies the response body to a different location.
     def_delegator :@body, :copy_to
 
+    # closes the body.
     def_delegator :@body, :close
 
+    # the corresponding request uri.
     def_delegator :@request, :uri
 
+    # the IP address of the peer server.
+    def_delegator :@request, :peer_address
+
+    # inits the instance with the corresponding +request+ to this response, an the
+    # response HTTP +status+, +version+ and HTTPX::Headers instance of +headers+.
     def initialize(request, status, version, headers)
       @request = request
       @options = request.options
@@ -33,32 +57,49 @@ module HTTPX
       @headers = @options.headers_class.new(headers)
       @body = @options.response_body_class.new(self, @options)
       @finished = complete?
+      @content_type = nil
     end
 
+    # merges headers defined in +h+ into the response headers.
     def merge_headers(h)
       @headers = @headers.merge(h)
     end
 
+    # writes +data+ chunk into the response body.
     def <<(data)
       @body.write(data)
     end
 
+    # returns the response mime type, as per what's declared in the content-type header.
+    #
+    #   response.content_type #=> "text/plain"
     def content_type
       @content_type ||= ContentType.new(@headers["content-type"])
     end
 
+    # returns whether the response has been fully fetched.
     def finished?
       @finished
     end
 
+    # marks the response as finished, freezes the headers.
     def finish!
       @finished = true
       @headers.freeze
     end
 
+    # returns whether the response contains body payload.
     def bodyless?
       @request.verb == "HEAD" ||
-        no_data?
+        @status < 200 || # informational response
+        @status == 204 ||
+        @status == 205 ||
+        @status == 304 || begin
+          content_length = @headers["content-length"]
+          return false if content_length.nil?
+
+          content_length == "0"
+        end
     end
 
     def complete?
@@ -75,32 +116,53 @@ module HTTPX
     end
     # :nocov:
 
+    # returns an instance of HTTPX::HTTPError if the response has a 4xx or 5xx
+    # status code, or nothing.
+    #
+    #   ok_response.error #=> nil
+    #   not_found_response.error #=> HTTPX::HTTPError instance, status 404
     def error
       return if @status < 400
 
       HTTPError.new(self)
     end
 
+    # it raises the exception returned by +error+, or itself otherwise.
+    #
+    #   ok_response.raise_for_status #=> ok_response
+    #   not_found_response.raise_for_status #=> raises HTTPX::HTTPError exception
     def raise_for_status
       return self unless (err = error)
 
       raise err
     end
 
+    # decodes the response payload into a ruby object **if** the payload is valid json.
+    #
+    #   response.json #≈> { "foo" => "bar" } for "{\"foo\":\"bar\"}" payload
+    #   response.json(symbolize_names: true) #≈> { foo: "bar" } for "{\"foo\":\"bar\"}" payload
     def json(*args)
       decode(Transcoder::JSON, *args)
     end
 
+    # decodes the response payload into a ruby object **if** the payload is valid
+    # "application/x-www-urlencoded" or "multipart/form-data".
     def form
       decode(Transcoder::Form)
     end
 
+    # decodes the response payload into a Nokogiri::XML::Node object **if** the payload is valid
+    # "application/xml" (requires the "nokogiri" gem).
     def xml
       decode(Transcoder::Xml)
     end
 
     private
 
+    # decodes the response payload using the given +transcoder+, which implements the decoding logic.
+    #
+    # +transcoder+ must implement the internal transcoder API, i.e. respond to <tt>decode(HTTPX::Response response)</tt>,
+    # which returns a decoder which responds to <tt>call(HTTPX::Response response, **kwargs)</tt>
     def decode(transcoder, *args)
       # TODO: check if content-type is a valid format, i.e. "application/json" for json parsing
 
@@ -112,20 +174,9 @@ module HTTPX
 
       decoder.call(self, *args)
     end
-
-    def no_data?
-      @status < 200 || # informational response
-        @status == 204 ||
-        @status == 205 ||
-        @status == 304 || begin
-          content_length = @headers["content-length"]
-          return false if content_length.nil?
-
-          content_length == "0"
-        end
-    end
   end
 
+  # Helper class which decodes the HTTP "content-type" header.
   class ContentType
     MIME_TYPE_RE = %r{^([^/]+/[^;]+)(?:$|;)}.freeze
     CHARSET_RE   = /;\s*charset=([^;]+)/i.freeze
@@ -134,6 +185,9 @@ module HTTPX
       @header_value = header_value
     end
 
+    # returns the mime type declared in the header.
+    #
+    #   ContentType.new("application/json; charset=utf-8").mime_type #=> "application/json"
     def mime_type
       return @mime_type if defined?(@mime_type)
 
@@ -141,6 +195,10 @@ module HTTPX
       m && @mime_type = m.strip.downcase
     end
 
+    # returns the charset declared in the header.
+    #
+    #   ContentType.new("application/json; charset=utf-8").charset #=> "utf-8"
+    #   ContentType.new("text/plain").charset #=> nil
     def charset
       return @charset if defined?(@charset)
 
@@ -149,14 +207,31 @@ module HTTPX
     end
   end
 
+  # Wraps an error which has happened while processing an HTTP Request. It has partial
+  # public API parity with HTTPX::Response, so users should rely on it to infer whether
+  # the returned response is one or the other.
+  #
+  #   response = HTTPX.get("https://some-domain/path") #=> response is HTTPX::Response or HTTPX::ErrorResponse
+  #   response.raise_for_status #=> raises if it wraps an error
   class ErrorResponse
     include Loggable
     extend Forwardable
 
-    attr_reader :request, :response, :error
+    # the corresponding HTTPX::Request instance.
+    attr_reader :request
 
+    # the HTTPX::Response instance, when there is one (i.e. error happens fetching the response).
+    attr_reader :response
+
+    # the wrapped exception.
+    attr_reader :error
+
+    # the request uri
     def_delegator :@request, :uri
 
+    # the IP address of the peer server.
+    def_delegator :@request, :peer_address
+
     def initialize(request, error, options)
       @request = request
       @response = request.response if request.response.is_a?(Response)
@@ -165,18 +240,22 @@ module HTTPX
       log_exception(@error)
     end
 
+    # returns the exception full message.
     def to_s
       @error.full_message(highlight: false)
     end
 
+    # closes the error resources.
     def close
-      @response.close if @response.respond_to?(:close)
+      @response.close if @response && @response.respond_to?(:close)
     end
 
+    # always true for error responses.
     def finished?
       true
     end
 
+    # raises the wrapped exception.
     def raise_for_status
       raise @error
     end

data/lib/httpx/selector.rb

@@ -73,7 +73,7 @@ class HTTPX::Selector
       readers, writers = IO.select(r, w, nil, interval)
 
       if readers.nil? && writers.nil? && interval
-        [*r, *w].each { |io| io.raise_timeout_error(interval) }
+        [*r, *w].each { |io| io.handle_socket_timeout(interval) }
         return
       end
     rescue IOError, SystemCallError
@@ -110,7 +110,7 @@ class HTTPX::Selector
     end
 
     unless result || interval.nil?
-      io.raise_timeout_error(interval)
+      io.handle_socket_timeout(interval)
       return
     end
     # raise HTTPX::TimeoutError.new(interval, "timed out while waiting on select")

data/lib/httpx/session.rb

@@ -1,6 +1,10 @@
 # frozen_string_literal: true
 
 module HTTPX
+  # Class implementing the APIs being used publicly.
+  #
+  #   HTTPX.get(..) #=> delegating to an internal HTTPX::Session object.
+  #   HTTPX.plugin(..).get(..) #=> creating an intermediate HTTPX::Session with plugin, then sending the GET request
   class Session
     include Loggable
     include Chainable
@@ -8,6 +12,10 @@ module HTTPX
 
     EMPTY_HASH = {}.freeze
 
+    # initializes the session with a set of +options+, which will be shared by all
+    # requests sent from it.
+    #
+    # When pass a block, it'll yield itself to it, then closes after the block is evaluated.
     def initialize(options = EMPTY_HASH, &blk)
       @options = self.class.default_options.merge(options)
       @responses = {}
@@ -15,6 +23,11 @@ module HTTPX
       wrap(&blk) if blk
     end
 
+    # Yields itself the block, then closes it after the block is evaluated.
+    #
+    #   session.wrap do |http|
+    #     http.get("https://wikipedia.com")
+    #   end # wikipedia connection closes here
     def wrap
       begin
         prev_persistent = @persistent
@@ -26,10 +39,31 @@ module HTTPX
       end
     end
 
+    # closes all the active connections from the session
     def close(*args)
       pool.close(*args)
     end
 
+    # performs one, or multple requests; it accepts:
+    #
+    # 1. one or multiple HTTPX::Request objects;
+    # 2. an HTTP verb, then a sequence of URIs or URI/options tuples;
+    # 3. one or multiple HTTP verb / uri / (optional) options tuples;
+    #
+    # when present, the set of +options+ kwargs is applied to all of the
+    # sent requests.
+    #
+    # respectively returns a single HTTPX::Response response, or all of them in an Array, in the same order.
+    #
+    #  resp1 = session.request(req1)
+    #  resp1, resp2 = session.request(req1, req2)
+    #  resp1 = session.request("GET", "https://server.org/a")
+    #  resp1, resp2 = session.request("GET", ["https://server.org/a", "https://server.org/b"])
+    #  resp1, resp2 = session.request(["GET", "https://server.org/a"], ["GET", "https://server.org/b"])
+    #  resp1 = session.request("POST", "https://server.org/a", form: { "foo" => "bar" })
+    #  resp1, resp2 = session.request(["POST", "https://server.org/a", form: { "foo" => "bar" }], ["GET", "https://server.org/b"])
+    #  resp1, resp2 = session.request("GET", ["https://server.org/a", "https://server.org/b"], headers: { "x-api-token" => "TOKEN" })
+    #
     def request(*args, **options)
       raise ArgumentError, "must perform at least one request" if args.empty?
 
@@ -40,10 +74,17 @@ module HTTPX
       responses
     end
 
+    # returns a HTTP::Request instance built from the HTTP +verb+, the request +uri+, and
+    # the optional set of request-specific +options+. This request **must** be sent through
+    # the same session it was built from.
+    #
+    #   req = session.build_request("GET", "https://server.com")
+    #   resp = session.request(req)
     def build_request(verb, uri, options = EMPTY_HASH)
       rklass = @options.request_class
       options = @options.merge(options) unless options.is_a?(Options)
-      request = rklass.new(verb, uri, options.merge(persistent: @persistent))
+      request = rklass.new(verb, uri, options)
+      request.persistent = @persistent
       request.on(:response, &method(:on_response).curry(2)[request])
       request.on(:promise, &method(:on_promise))
 
@@ -76,23 +117,29 @@ module HTTPX
 
     private
 
+    # returns the HTTPX::Pool object which manages the networking required to
+    # perform requests.
     def pool
       Thread.current[:httpx_connection_pool] ||= Pool.new
     end
 
+    # callback executed when a response for a given request has been received.
     def on_response(request, response)
       @responses[request] = response
     end
 
+    # callback executed when an HTTP/2 promise frame has been received.
     def on_promise(_, stream)
       log(level: 2) { "#{stream.id}: refusing stream!" }
       stream.refuse
     end
 
+    # returns the corresponding HTTP::Response to the given +request+ if it has been received.
     def fetch_response(request, _, _)
       @responses.delete(request)
     end
 
+    # returns the HTTPX::Connection through which the +request+ should be sent through.
     def find_connection(request, connections, options)
       uri = request.uri
 
@@ -104,6 +151,8 @@ module HTTPX
       connection
     end
 
+    # sets the callbacks on the +connection+ required to process certain specific
+    # connection lifecycle events which deal with request rerouting.
     def set_connection_callbacks(connection, connections, options)
       connection.only(:misdirected) do |misdirected_request|
         other_connection = connection.create_idle(ssl: { alpn_protocols: %w[http/1.1] })
@@ -131,6 +180,7 @@ module HTTPX
       end
     end
 
+    # returns an HTTPX::Connection for the negotiated Alternative Service (or none).
     def build_altsvc_connection(existing_connection, connections, alt_origin, origin, alt_params, options)
       # do not allow security downgrades on altsvc negotiation
       return if existing_connection.origin.scheme == "https" && alt_origin.scheme != "https"
@@ -166,6 +216,7 @@ module HTTPX
       nil
     end
 
+    # returns a set of HTTPX::Request objects built from the given +args+ and +options+.
     def build_requests(*args, options)
       request_options = @options.merge(options)
 
@@ -189,6 +240,7 @@ module HTTPX
       requests
     end
 
+    # returns a new HTTPX::Connection object for the given +uri+ and set of +options+.
     def build_connection(uri, options)
       type = options.transport || begin
         case uri.scheme
@@ -208,7 +260,9 @@ module HTTPX
       connection.on(:open) do
         emit(:connection_opened, connection.origin, connection.io.socket)
         # only run close callback if it opened
-        connection.on(:close) { emit(:connection_closed, connection.origin, connection.io.socket) }
+      end
+      connection.on(:close) do
+        emit(:connection_closed, connection.origin, connection.io.socket) if connection.used?
       end
       catch(:coalesced) do
         pool.init_connection(connection, options)
@@ -216,11 +270,13 @@ module HTTPX
       end
     end
 
+    # sends an array of HTTPX::Request +requests+, returns the respective array of HTTPX::Response objects.
     def send_requests(*requests)
       connections = _send_requests(requests)
       receive_requests(requests, connections)
     end
 
+    # sends an array of HTTPX::Request objects
     def _send_requests(requests)
       connections = []
 
@@ -237,6 +293,7 @@ module HTTPX
       connections
     end
 
+    # returns the array of HTTPX::Response objects corresponding to the array of HTTPX::Request +requests+.
     def receive_requests(requests, connections)
       # @type var responses: Array[response]
       responses = []
@@ -290,6 +347,11 @@ module HTTPX
         klass.instance_variable_set(:@callbacks, @callbacks.dup)
       end
 
+      # returns a new HTTPX::Session instance, with the plugin pointed by +pl+ loaded.
+      #
+      #   session_with_retries = session.plugin(:retries)
+      #   session_with_custom = session.plugin(CustomPlugin)
+      #
       def plugin(pl, options = nil, &block)
         # raise Error, "Cannot add a plugin to a frozen config" if frozen?
         pl = Plugins.load_plugin(pl) if pl.is_a?(Symbol)

data/lib/httpx/timers.rb

@@ -6,20 +6,27 @@ module HTTPX
       @intervals = []
     end
 
-    def after(interval_in_secs, &blk)
+    def after(interval_in_secs, cb = nil, &blk)
       return unless interval_in_secs
 
+      callback = cb || blk
+
       # I'm assuming here that most requests will have the same
       # request timeout, as in most cases they share common set of
       # options. A user setting different request timeouts for 100s of
       # requests will already have a hard time dealing with that.
-      unless (interval = @intervals.find { |t| t == interval_in_secs })
+      unless (interval = @intervals.find { |t| t.interval == interval_in_secs })
         interval = Interval.new(interval_in_secs)
+        interval.on_empty { @intervals.delete(interval) }
         @intervals << interval
         @intervals.sort!
       end
 
-      interval << blk
+      interval << callback
+
+      @next_interval_at = nil
+
+      interval
     end
 
     def wait_interval
@@ -41,11 +48,6 @@ module HTTPX
       @next_interval_at = nil if @intervals.empty?
     end
 
-    def cancel
-      @next_interval_at = nil
-      @intervals.clear
-    end
-
     class Interval
       include Comparable
 
@@ -54,6 +56,11 @@ module HTTPX
       def initialize(interval)
         @interval = interval
         @callbacks = []
+        @on_empty = nil
+      end
+
+      def on_empty(&blk)
+        @on_empty = blk
       end
 
       def <=>(other)
@@ -74,6 +81,26 @@ module HTTPX
         @callbacks << callback
       end
 
+      if RUBY_ENGINE == "jruby" && JRUBY_VERSION < "9.4.5.0"
+        # https://github.com/jruby/jruby/issues/7976
+        def delete(callback)
+          @callbacks.delete(callback)
+        end
+      else
+        def delete(callback)
+          @callbacks.delete(callback)
+          @on_empty.call if @callbacks.empty?
+        end
+      end
+
+      def no_callbacks?
+        @callbacks.empty?
+      end
+
+      def elapsed?
+        @interval <= 0
+      end
+
       def elapse(elapsed)
         @interval -= elapsed
 

data/lib/httpx/transcoder/json.rb

@@ -6,7 +6,7 @@ module HTTPX::Transcoder
   module JSON
     module_function
 
-    JSON_REGEX = %r{\bapplication/(?:vnd\.api\+)?json\b}i.freeze
+    JSON_REGEX = %r{\bapplication/(?:vnd\.api\+|hal\+)?json\b}i.freeze
 
     class Encoder
       extend Forwardable

data/lib/httpx/transcoder/utils/inflater.rb

@@ -0,0 +1,19 @@
+module HTTPX
+  module Transcoder
+    class Inflater
+      def initialize(bytesize)
+        @bytesize = bytesize
+      end
+
+      def call(chunk)
+        buffer = @inflater.inflate(chunk)
+        @bytesize -= chunk.bytesize
+        if @bytesize <= 0
+          buffer << @inflater.finish
+          @inflater.close
+        end
+        buffer
+      end
+    end
+  end
+end

data/lib/httpx/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module HTTPX
-  VERSION = "1.0.2"
+  VERSION = "1.1.1"
 end

data/sig/connection/http1.rbs

@@ -53,19 +53,19 @@ module HTTPX
 
     def ping: () -> void
 
-    def timeout: () -> Numeric
+    def timeout: () -> Numeric?
 
     private
 
     def initialize: (Buffer, options) -> untyped
 
-    def manage_connection: (Response) -> void
+    def manage_connection: (Request request, Response response) -> void
 
     def disable: () -> void
 
     def disable_pipelining: () -> void
 
-    def set_protocol_headers: (Request) -> _Each[[String, String]]
+    def set_protocol_headers: (Request request) -> _Each[[String, String]]
 
     def handle: (Request request) -> void
 

data/sig/connection/http2.rbs

@@ -38,7 +38,7 @@ module HTTPX
 
     alias reset init_connection
 
-    def timeout: () -> Numeric
+    def timeout: () -> Numeric?
 
     private
 

data/sig/connection.rbs

@@ -40,6 +40,7 @@ module HTTPX
     @parser: HTTP1 | HTTP2 | _Parser
     @connected_at: Float
     @response_received_at: Float
+    @intervals: Array[Timers::Interval]
 
     def addresses: () -> Array[ipaddr]?
 
@@ -89,7 +90,7 @@ module HTTPX
 
     def open?: () -> bool
 
-    def raise_timeout_error: (Numeric interval) -> void
+    def handle_socket_timeout: (Numeric interval) -> void
 
     private
 
@@ -129,6 +130,8 @@ module HTTPX
 
     def read_timeout_callback: (Request request, Numeric read_timeout, ?singleton(RequestTimeoutError) error_type) -> void
 
+    def set_request_timeout: (Request request, Numeric timeout, Symbol start_event, Symbol | Array[Symbol] finish_events) { () -> void } -> void
+
     def self.parser_type: (String protocol) -> (singleton(HTTP1) | singleton(HTTP2))
   end
 end

data/sig/io/tcp.rbs

@@ -2,7 +2,7 @@ module HTTPX
   class TCP
     include Loggable
 
-    attr_reader ip: IPAddr?
+    attr_reader ip: ipaddr?
 
     attr_reader port: Integer
 

data/sig/options.rbs

@@ -12,7 +12,7 @@ module HTTPX
     DEFAULT_OPTIONS: Hash[Symbol, untyped]
 
     type timeout_type = :connect_timeout | :settings_timeout | :operation_timeout | :keep_alive_timeout | :read_timeout | :write_timeout | :request_timeout
-    type timeout = Hash[timeout_type, Numeric]
+    type timeout = Hash[timeout_type, Numeric?]
 
     def self.new: (?options) -> instance
 
@@ -32,7 +32,7 @@ module HTTPX
     attr_reader max_concurrent_requests: Integer?
 
     # max_requests
-    attr_reader max_requests: Integer?
+    attr_reader max_requests: Numeric?
 
     # window_size
     attr_reader window_size: Integer

data/sig/pool.rbs

@@ -45,7 +45,7 @@ module HTTPX
 
     def coalesce_connections: (Connection coalescable, Connection coalescing) -> void
 
-    def next_timeout: () -> (Integer | Float | nil)
+    def next_timeout: () -> Numeric?
 
     def find_resolver_for: (Connection) { (Resolver::Resolver resolver) -> void } -> resolver_manager
   end

data/sig/request/body.rbs

@@ -1,7 +1,5 @@
 module HTTPX
   class Request::Body
-    attr_reader threshold_size: Integer?
-
     @headers: Headers
     @body: body_encoder?
     @unbounded_body: bool