httpx 0.20.0 → 1.3.1

data/lib/httpx/request/body.rb

@@ -0,0 +1,154 @@
+# 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, body: nil, **params)
+        if body.is_a?(self)
+          # request derives its options from body
+          body.options = options.merge(params)
+          return body
+        end
+
+        super
+      end
+    end
+
+    attr_accessor :options
+
+    # inits the instance with the request +headers+, +options+ and +params+, which contain the payload definition.
+    # it wraps the given body with the appropriate encoder on initialization.
+    #
+    #   ..., 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(headers, options, body: nil, form: nil, json: nil, xml: nil, **params)
+      @headers = headers
+      @options = options.merge(params)
+
+      @body = if body
+        Transcoder::Body.encode(body)
+      elsif form
+        Transcoder::Form.encode(form)
+      elsif json
+        Transcoder::JSON.encode(json)
+      elsif xml
+        Transcoder::Xml.encode(xml)
+      end
+
+      if @body
+        if @options.compress_request_body && @headers.key?("content-encoding")
+
+          @headers.get("content-encoding").each do |encoding|
+            @body = self.class.initialize_deflater_body(@body, encoding)
+          end
+        end
+
+        @headers["content-type"] ||= @body.content_type
+        @headers["content-length"] = @body.bytesize unless unbounded_body?
+      end
+
+      super(@body)
+    end
+
+    # consumes and yields the request payload in chunks.
+    def each(&block)
+      return enum_for(__method__) unless block
+      return if @body.nil?
+
+      body = stream(@body)
+      if body.respond_to?(:read)
+        ::IO.copy_stream(body, ProcIO.new(block))
+      elsif body.respond_to?(:each)
+        body.each(&block)
+      else
+        block[body.to_s]
+      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?
+
+      @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)
+      return body unless chunked?
+
+      Transcoder::Chunker.encode(body.enum_for(:each))
+    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
+
+    # :nocov:
+    def inspect
+      "#<HTTPX::Request::Body:#{object_id} " \
+        "#{unbounded_body? ? "stream" : "@bytesize=#{bytesize}"}>"
+    end
+    # :nocov:
+
+    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"
+          Transcoder::GZIP.encode(body)
+        when "deflate"
+          Transcoder::Deflate.encode(body)
+        when "identity"
+          body
+        else
+          body
+        end
+      end
+    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
+    end
+  end
+end

data/lib/httpx/request.rb

@@ -4,47 +4,85 @@ require "delegate"
 require "forwardable"
 
 module HTTPX
+  # Defines how an HTTP request is handled internally, both in terms of making attributes accessible,
+  # as well as maintaining the state machine which manages streaming the request onto the wire.
   class Request
     extend Forwardable
     include Callbacks
     using URIExtensions
 
-    METHODS = [
-      # RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1
-      :options, :get, :head, :post, :put, :delete, :trace, :connect,
-
-      # RFC 2518: HTTP Extensions for Distributed Authoring -- WEBDAV
-      :propfind, :proppatch, :mkcol, :copy, :move, :lock, :unlock,
+    # default value used for "user-agent" header, when not overridden.
+    USER_AGENT = "httpx.rb/#{VERSION}"
 
-      # RFC 3648: WebDAV Ordered Collections Protocol
-      :orderpatch,
+    # the upcased string HTTP verb for this request.
+    attr_reader :verb
 
-      # RFC 3744: WebDAV Access Control Protocol
-      :acl,
+    # the absolute URI object for this request.
+    attr_reader :uri
 
-      # RFC 6352: vCard Extensions to WebDAV -- CardDAV
-      :report,
+    # an HTTPX::Headers object containing the request HTTP headers.
+    attr_reader :headers
 
-      # RFC 5789: PATCH Method for HTTP
-      :patch,
+    # an HTTPX::Request::Body object containing the request body payload (or +nil+, whenn there is none).
+    attr_reader :body
 
-      # draft-reschke-webdav-search: WebDAV Search
-      :search
-    ].freeze
+    # a symbol describing which frame is currently being flushed.
+    attr_reader :state
 
-    USER_AGENT = "httpx.rb/#{VERSION}"
+    # an HTTPX::Options object containing request options.
+    attr_reader :options
 
-    attr_reader :verb, :uri, :headers, :body, :state, :options, :response
+    # the corresponding HTTPX::Response object, when there is one.
+    attr_reader :response
 
-    # Exception raised during enumerable body writes
+    # Exception raised during enumerable body writes.
     attr_reader :drain_error
 
+    # The IP address from the peer server.
+    attr_accessor :peer_address
+
+    attr_writer :persistent
+
+    # will be +true+ when request body has been completely flushed.
     def_delegator :@body, :empty?
 
-    def initialize(verb, uri, options = {})
-      @verb    = verb.to_s.downcase.to_sym
-      @options = Options.new(options)
+    # initializes the instance with the given +verb+ (an upppercase String, ex. 'GEt'),
+    # an absolute or relative +uri+ (either as String or URI::HTTP object), the
+    # request +options+ (instance of HTTPX::Options) and an optional Hash of +params+.
+    #
+    # Besides any of the options documented in HTTPX::Options (which would override or merge with what
+    # +options+ sets), it accepts also the following:
+    #
+    # :params :: hash or array of key-values which will be encoded and set in the query string of request uris.
+    # :body :: to be encoded in the request body payload. can be a String, an IO object (i.e. a File), or an Enumerable.
+    # :form :: hash of array of key-values which will be form-urlencoded- 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.
+    #
+    # :body, :form, :json and :xml are all mutually exclusive, i.e. only one of them gets picked up.
+    def initialize(verb, uri, options, params = EMPTY_HASH)
+      @verb    = verb.to_s.upcase
       @uri     = Utils.to_uri(uri)
+
+      @headers = options.headers.dup
+      merge_headers(params.delete(:headers)) if params.key?(:headers)
+
+      @headers["user-agent"] ||= USER_AGENT
+      @headers["accept"]     ||= "*/*"
+
+      # forego compression in the Range request case
+      if @headers.key?("range")
+        @headers.delete("accept-encoding")
+      else
+        @headers["accept-encoding"] ||= options.supported_compression_formats
+      end
+
+      @query_params = params.delete(:params) if params.key?(:params)
+
+      @body = options.request_body_class.new(@headers, options, **params)
+
+      @options = @body.options
+
       if @uri.relative?
         origin = @options.origin
         raise(Error, "invalid URI: #{@uri}") unless origin
@@ -54,92 +92,131 @@ module HTTPX
         @uri = origin.merge("#{base_path}#{@uri}")
       end
 
-      raise(Error, "unknown method: #{verb}") unless METHODS.include?(@verb)
+      @state = :idle
+      @response = nil
+      @peer_address = nil
+      @persistent = @options.persistent
+    end
 
-      @headers = @options.headers_class.new(@options.headers)
-      @headers["user-agent"] ||= USER_AGENT
-      @headers["accept"]     ||= "*/*"
+    # the read timeout defined for this requet.
+    def read_timeout
+      @options.timeout[:read_timeout]
+    end
 
-      @body = @options.request_body_class.new(@headers, @options)
-      @state = :idle
+    # the write timeout defined for this requet.
+    def write_timeout
+      @options.timeout[:write_timeout]
     end
 
+    # the request timeout defined for this requet.
+    def request_timeout
+      @options.timeout[:request_timeout]
+    end
+
+    def persistent?
+      @persistent
+    end
+
+    # if the request contains trailer headers
     def trailers?
       defined?(@trailers)
     end
 
+    # returns an instance of HTTPX::Headers containing the trailer headers
     def trailers
       @trailers ||= @options.headers_class.new
     end
 
+    # returns +:r+ or +:w+, depending on whether the request is waiting for a response or flushing.
     def interests
       return :r if @state == :done || @state == :expect
 
       :w
     end
 
-    if RUBY_VERSION < "2.2"
-      URIParser = URI::DEFAULT_PARSER
-
-      def initialize_with_escape(verb, uri, options = {})
-        initialize_without_escape(verb, URIParser.escape(uri.to_s), options)
-      end
-      alias_method :initialize_without_escape, :initialize
-      alias_method :initialize, :initialize_with_escape
-    end
-
+    # merges +h+ into the instance of HTTPX::Headers of the request.
     def merge_headers(h)
       @headers = @headers.merge(h)
     end
 
+    # the URI scheme of the request +uri+.
     def scheme
       @uri.scheme
     end
 
+    # sets the +response+ on this request.
     def response=(response)
       return unless response
 
-      if response.is_a?(Response) && response.status == 100
-        @informational_status = response.status
-        return
+      if response.is_a?(Response) && response.status < 200
+        # deal with informational responses
+
+        if response.status == 100 && @headers.key?("expect")
+          @informational_status = response.status
+          return
+        end
+
+        # 103 Early Hints advertises resources in document to browsers.
+        # not very relevant for an HTTP client, discard.
+        return if response.status >= 103
       end
+
       @response = response
+
+      emit(:response_started, response)
     end
 
+    # returnns the URI path of the request +uri+.
     def path
       path = uri.path.dup
+      path =  +"" if path.nil?
       path << "/" if path.empty?
       path << "?#{query}" unless query.empty?
       path
     end
 
-    # https://bugs.ruby-lang.org/issues/15278
+    # returs the URI authority of the request.
+    #
+    #   session.build_request("GET", "https://google.com/query").authority #=> "google.com"
+    #   session.build_request("GET", "http://internal:3182/a").authority #=> "internal:3182"
     def authority
       @uri.authority
     end
 
-    # https://bugs.ruby-lang.org/issues/15278
+    # returs the URI origin of the request.
+    #
+    #   session.build_request("GET", "https://google.com/query").authority #=> "https://google.com"
+    #   session.build_request("GET", "http://internal:3182/a").authority #=> "http://internal:3182"
     def origin
       @uri.origin
     end
 
+    # returs the URI query string of the request (when available).
+    #
+    #   session.build_request("GET", "https://search.com").query #=> ""
+    #   session.build_request("GET", "https://search.com?q=a").query #=> "q=a"
+    #   session.build_request("GET", "https://search.com", params: { q: "a"}).query #=> "q=a"
+    #   session.build_request("GET", "https://search.com?q=a", params: { foo: "bar"}).query #=> "q=a&foo&bar"
     def query
       return @query if defined?(@query)
 
       query = []
-      if (q = @options.params)
-        query << Transcoder.registry("form").encode(q)
+      if (q = @query_params)
+        query << Transcoder::Form.encode(q)
       end
       query << @uri.query if @uri.query
       @query = query.join("&")
     end
 
+    # consumes and returns the next available chunk of request body that can be sent
     def drain_body
       return nil if @body.nil?
 
       @drainer ||= @body.each
-      chunk = @drainer.next
-      chunk.dup
+      chunk = @drainer.next.dup
+
+      emit(:body_chunk, chunk)
+      chunk
     rescue StopIteration
       nil
     rescue StandardError => e
@@ -150,99 +227,14 @@ module HTTPX
     # :nocov:
     def inspect
       "#<HTTPX::Request:#{object_id} " \
-        "#{@verb.to_s.upcase} " \
+        "#{@verb} " \
         "#{uri} " \
         "@headers=#{@headers} " \
         "@body=#{@body}>"
     end
     # :nocov:
 
-    class Body < SimpleDelegator
-      class << self
-        def new(_, options)
-          return options.body if options.body.is_a?(self)
-
-          super
-        end
-      end
-
-      def initialize(headers, options)
-        @headers = headers
-        @body = if options.body
-          Transcoder.registry("body").encode(options.body)
-        elsif options.form
-          Transcoder.registry("form").encode(options.form)
-        elsif options.json
-          Transcoder.registry("json").encode(options.json)
-        end
-        return if @body.nil?
-
-        @headers["content-type"] ||= @body.content_type
-        @headers["content-length"] = @body.bytesize unless unbounded_body?
-        super(@body)
-      end
-
-      def each(&block)
-        return enum_for(__method__) unless block
-        return if @body.nil?
-
-        body = stream(@body)
-        if body.respond_to?(:read)
-          ::IO.copy_stream(body, ProcIO.new(block))
-        elsif body.respond_to?(:each)
-          body.each(&block)
-        else
-          block[body.to_s]
-        end
-      end
-
-      def rewind
-        return if empty?
-
-        @body.rewind if @body.respond_to?(:rewind)
-      end
-
-      def empty?
-        return true if @body.nil?
-        return false if chunked?
-
-        @body.bytesize.zero?
-      end
-
-      def bytesize
-        return 0 if @body.nil?
-
-        @body.bytesize
-      end
-
-      def stream(body)
-        encoded = body
-        encoded = Transcoder.registry("chunker").encode(body.enum_for(:each)) if chunked?
-        encoded
-      end
-
-      def unbounded_body?
-        return @unbounded_body if defined?(@unbounded_body)
-
-        @unbounded_body = !@body.nil? && (chunked? || @body.bytesize == Float::INFINITY)
-      end
-
-      def chunked?
-        @headers["transfer-encoding"] == "chunked"
-      end
-
-      def chunk!
-        @headers.add("transfer-encoding", "chunked")
-      end
-
-      # :nocov:
-      def inspect
-        "#<HTTPX::Request::Body:#{object_id} " \
-          "#{unbounded_body? ? "stream" : "@bytesize=#{bytesize}"}>"
-      end
-      # :nocov:
-    end
-
+    # moves on to the +nextstate+ of the request state machine (when all preconditions are met)
     def transition(nextstate)
       case nextstate
       when :idle
@@ -277,19 +269,11 @@ module HTTPX
       nil
     end
 
+    # whether the request supports the 100-continue handshake and already processed the 100 response.
     def expects?
       @headers["expect"] == "100-continue" && @informational_status == 100 && !@response
     end
-
-    class ProcIO
-      def initialize(block)
-        @block = block
-      end
-
-      def write(data)
-        @block.call(data.dup)
-        data.bytesize
-      end
-    end
   end
 end
+
+require_relative "request/body"