httpx 1.0.2 → 1.1.0

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
@@ -216,11 +268,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 +291,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 +345,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,25 @@ 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
+
+      interval
     end
 
     def wait_interval
@@ -41,11 +46,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 +54,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 +79,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.0"
 end

data/sig/connection/http1.rbs

@@ -53,7 +53,7 @@ module HTTPX
 
     def ping: () -> void
 
-    def timeout: () -> Numeric
+    def timeout: () -> Numeric?
 
     private
 

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

data/sig/request.rbs

@@ -15,6 +15,10 @@ module HTTPX
     attr_reader response: response?
     attr_reader drain_error: StandardError?
 
+    attr_accessor peer_address: ipaddr?
+
+    attr_writer persistent: bool
+
     @trailers: Headers?
     @informational_status: Integer?
     @query: String?
@@ -50,11 +54,13 @@ module HTTPX
 
     def trailers?: () -> boolish
 
-    def read_timeout: () -> Numeric
+    def persistent?: () -> bool
+
+    def read_timeout: () -> Numeric?
 
-    def write_timeout: () -> Numeric
+    def write_timeout: () -> Numeric?
 
-    def request_timeout: () -> Numeric
+    def request_timeout: () -> Numeric?
 
     private
 

data/sig/resolver/native.rbs

@@ -34,7 +34,7 @@ module HTTPX
 
       def timeout: () -> Numeric?
 
-      def raise_timeout_error: (Numeric interval) -> void
+      def handle_socket_timeout: (Numeric interval) -> void
 
       private
 

data/sig/resolver.rbs

@@ -2,7 +2,7 @@ module HTTPX
   type ipaddr = IPAddr | String
 
   module Resolver
-    RESOLVE_TIMEOUT: Integer | Float
+    RESOLVE_TIMEOUT: Integer
 
     @lookup_mutex: Thread::Mutex
 

data/sig/response/body.rbs

@@ -11,7 +11,6 @@ module HTTPX
     @headers: Headers
     @options: Options
     @state: :idle | :memory | :buffer | :closed
-    @threshold_size: Integer
     @window_size: Integer
     @length: Integer
     @buffer: StringIO | Tempfile | nil

data/sig/response.rbs

@@ -25,22 +25,28 @@ module HTTPX
     @content_type: ContentType
 
     def copy_to: (_ToPath | _Writer destination) -> void
+
     def close: () -> void
+
     def uri: () -> URI::Generic
 
+    def peer_address: () -> ipaddr?
+
     def merge_headers: (_Each[[String, headers_value]]) -> void
+
     def bodyless?: () -> bool
+
     def content_type: () -> ContentType
+
     def complete?: () -> bool
 
     def json: (?json_options opts) -> untyped
 
     def form: () -> Hash[String, untyped]
 
-    private
+    def initialize: (Request request, String | Integer status, String version, headers?) -> void
 
-    def initialize: (Request request, String | Integer status, String version, headers?) -> untyped
-    def no_data?: () -> bool
+    private
 
     def decode:(Transcoder::_Decode transcoder, ?untyped options) -> untyped
   end
@@ -78,6 +84,8 @@ module HTTPX
 
     def uri: () -> URI::Generic
 
+    def peer_address: () -> ipaddr?
+
     def close: () -> void
 
     private

data/sig/timers.rbs

@@ -3,30 +3,40 @@ module HTTPX
     @intervals: Array[Interval]
     @next_interval_at: Float
 
-    def after: (Numeric interval_in_secs) { () -> void } -> void
+    def after: (Numeric interval_in_secs, ^() -> void) -> Interval
+             | (Numeric interval_in_secs) { () -> void } -> Interval
 
     def wait_interval: () -> Numeric?
 
     def fire: (?TimeoutError error) -> void
 
-    def cancel: () -> void
-
-    private
-
     def initialize: () -> void
 
     class Interval
       include Comparable
 
+      type callback = ^() -> void
+
       attr_reader interval: Numeric
 
-      @callbacks: Array[^() -> void]
+      @callbacks: Array[callback]
+      @on_empty: callback?
+
+
+      def on_empty: () { () -> void } -> void
 
       def to_f: () -> Float
 
-      def <<: (^() -> void) -> void
+      def <<: (callback) -> void
+
+      def delete: (callback) -> void
 
       def elapse: (Numeric elapsed) -> Numeric
+
+      def elapsed?: () -> bool
+
+      def no_callbacks?: () -> bool
+
       private
 
       def initialize: (Numeric interval) -> void

data/sig/transcoder/utils/inflater.rbs

@@ -0,0 +1,12 @@
+module HTTPX
+  module Transcoder
+    class Inflater
+      @inflater: Zlib::Inflate
+      @bytesize: Integer
+
+      def initialize: (Integer | Float bytesize) -> void
+
+      def call: (String chunk) -> String
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: httpx
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.1.0
 platform: ruby
 authors:
 - Tiago Cardoso
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-10-13 00:00:00.000000000 Z
+date: 2023-10-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: http-2-next
@@ -131,6 +131,7 @@ extra_rdoc_files:
 - doc/release_notes/1_0_0.md
 - doc/release_notes/1_0_1.md
 - doc/release_notes/1_0_2.md
+- doc/release_notes/1_1_0.md
 files:
 - LICENSE.txt
 - README.md
@@ -233,6 +234,7 @@ files:
 - doc/release_notes/1_0_0.md
 - doc/release_notes/1_0_1.md
 - doc/release_notes/1_0_2.md
+- doc/release_notes/1_1_0.md
 - lib/httpx.rb
 - lib/httpx/adapters/datadog.rb
 - lib/httpx/adapters/faraday.rb
@@ -334,6 +336,7 @@ files:
 - lib/httpx/transcoder/multipart/part.rb
 - lib/httpx/transcoder/utils/body_reader.rb
 - lib/httpx/transcoder/utils/deflater.rb
+- lib/httpx/transcoder/utils/inflater.rb
 - lib/httpx/transcoder/xml.rb
 - lib/httpx/utils.rb
 - lib/httpx/version.rb
@@ -416,6 +419,7 @@ files:
 - sig/transcoder/multipart.rbs
 - sig/transcoder/utils/body_reader.rbs
 - sig/transcoder/utils/deflater.rbs
+- sig/transcoder/utils/inflater.rbs
 - sig/transcoder/xml.rbs
 - sig/utils.rbs
 homepage: https://gitlab.com/os85/httpx