http 6.0.0-java

data/lib/http/headers.rb

@@ -0,0 +1,343 @@
+# frozen_string_literal: true
+
+require "forwardable"
+
+require "http/errors"
+require "http/headers/normalizer"
+require "http/headers/known"
+
+module HTTP
+  # HTTP Headers container.
+  class Headers
+    extend Forwardable
+    include Enumerable
+
+    class << self
+      # Coerces given object into Headers
+      #
+      # @example
+      #   headers = HTTP::Headers.coerce("Content-Type" => "text/plain")
+      #
+      # @raise [Error] if object can't be coerced
+      # @param [#to_hash, #to_h, #to_a] object
+      # @return [Headers]
+      # @api public
+      def coerce(object)
+        object = if    object.respond_to?(:to_hash) then object.to_hash
+                 elsif object.respond_to?(:to_h)    then object.to_h
+                 elsif object.respond_to?(:to_a)    then object.to_a
+                 else raise Error, "Can't coerce #{object.inspect} to Headers"
+                 end
+
+        headers = new
+        object.each { |k, v| headers.add k, v }
+        headers
+      end
+      # @!method [](object)
+      #   Coerces given object into Headers
+      #
+      #   @example
+      #     headers = HTTP::Headers["Content-Type" => "text/plain"]
+      #
+      #   @see .coerce
+      #   @return [Headers]
+      #   @api public
+      alias [] coerce
+
+      # Returns the shared normalizer instance
+      #
+      # @example
+      #   HTTP::Headers.normalizer
+      #
+      # @return [Headers::Normalizer]
+      # @api public
+      def normalizer
+        @normalizer ||= Normalizer.new #: Headers::Normalizer
+      end
+    end
+
+    # Creates a new empty headers container
+    #
+    # @example
+    #   headers = HTTP::Headers.new
+    #
+    # @return [Headers]
+    # @api public
+    def initialize
+      # The @pile stores each header value using a three element array:
+      #  0 - the normalized header key, used for lookup
+      #  1 - the header key as it will be sent with a request
+      #  2 - the value
+      @pile = []
+    end
+
+    # Sets header, replacing any existing values
+    #
+    # @example
+    #   headers.set("Content-Type", "text/plain")
+    #
+    # @param (see #add)
+    # @return [void]
+    # @api public
+    def set(name, value)
+      delete(name)
+      add(name, value)
+    end
+    # @!method []=(name, value)
+    #   Sets header, replacing any existing values
+    #
+    #   @example
+    #     headers["Content-Type"] = "text/plain"
+    #
+    #   @see #set
+    #   @return [void]
+    #   @api public
+    alias []= set
+
+    # Removes header with the given name
+    #
+    # @example
+    #   headers.delete("Content-Type")
+    #
+    # @param [#to_s] name header name
+    # @return [void]
+    # @api public
+    def delete(name)
+      name = normalize_header name
+      @pile.delete_if { |k, _| k.eql?(name) }
+    end
+
+    # Appends header value(s) to the given name
+    #
+    # @example
+    #   headers.add("Accept", "text/html")
+    #
+    # @param [String, Symbol] name header name. When specified as a string, the
+    #   name is sent as-is. When specified as a symbol, the name is converted
+    #   to a string of capitalized words separated by a dash. Word boundaries
+    #   are determined by an underscore (`_`) or a dash (`-`).
+    #   Ex: `:content_type` is sent as `"Content-Type"`, and `"auth_key"` (string)
+    #   is sent as `"auth_key"`.
+    # @param [Array<#to_s>, #to_s] value header value(s) to be appended
+    # @return [void]
+    # @api public
+    def add(name, value)
+      lookup_name = normalize_header(name)
+      wire_name = wire_name_for(name, lookup_name)
+
+      Array(value).each do |v|
+        @pile << [
+          lookup_name,
+          wire_name,
+          validate_value(v)
+        ]
+      end
+    end
+
+    # Returns list of header values if any
+    #
+    # @example
+    #   headers.get("Content-Type")
+    #
+    # @return [Array<String>]
+    # @api public
+    def get(name)
+      name = normalize_header name
+      @pile.filter_map { |k, _, v| v if k.eql?(name) }
+    end
+
+    # Smart version of {#get}
+    #
+    # @example
+    #   headers["Content-Type"]
+    #
+    # @return [nil] if header was not set
+    # @return [String] if header has exactly one value
+    # @return [Array<String>] if header has more than one value
+    # @api public
+    def [](name)
+      values = get(name)
+      return if values.empty?
+
+      return values unless values.one?
+
+      values.join
+    end
+
+    # Tells whether header with given name is set
+    #
+    # @example
+    #   headers.include?("Content-Type")
+    #
+    # @return [Boolean]
+    # @api public
+    def include?(name)
+      name = normalize_header name
+      @pile.any? { |k, _| k.eql?(name) }
+    end
+
+    # Returns Rack-compatible headers Hash
+    #
+    # @example
+    #   headers.to_h
+    #
+    # @return [Hash]
+    # @api public
+    def to_h
+      keys.to_h { |k| [k, self[k]] }
+    end
+    # @!method to_hash
+    #   @see #to_h
+    #   @return [Hash]
+    alias to_hash to_h
+
+    # Pattern matching interface
+    #
+    # @example
+    #   headers.deconstruct_keys(%i[content_type])
+    #
+    # @param keys [Array<Symbol>, nil] keys to extract, or nil for all
+    # @return [Hash{Symbol => Object}]
+    # @api public
+    def deconstruct_keys(keys)
+      hash = @pile.map { |_, k, _| k }.to_h { |k| [k.tr("A-Z-", "a-z_").to_sym, self[k]] }
+      keys ? hash.slice(*keys) : hash
+    end
+
+    # Returns human-readable representation of self instance
+    #
+    # @example
+    #   headers.inspect
+    #
+    # @return [String]
+    # @api public
+    def inspect = "#<#{self.class}>"
+
+    # Returns list of header names
+    #
+    # @example
+    #   headers.keys
+    #
+    # @return [Array<String>]
+    # @api public
+    def keys
+      @pile.map { |_, k, _| k }.uniq
+    end
+
+    # Compares headers to another Headers or Array of pairs
+    #
+    # @example
+    #   headers == other_headers
+    #
+    # @return [Boolean]
+    # @api public
+    def ==(other)
+      return false unless other.respond_to? :to_a
+
+      to_a.eql?(other.to_a)
+    end
+
+    # Calls the given block once for each key/value pair
+    #
+    # @example
+    #   headers.each { |name, value| puts "#{name}: #{value}" }
+    #
+    # @return [Enumerator] if no block given
+    # @return [Headers] self-reference
+    # @api public
+    def each
+      return to_enum unless block_given?
+
+      @pile.each { |item| yield(item.drop(1)) }
+      self
+    end
+
+    # @!method empty?
+    #   Returns true if self has no key/value pairs
+    #
+    #   @example
+    #     headers.empty?
+    #
+    #   @return [Boolean]
+    #   @api public
+    def_delegator :@pile, :empty?
+
+    # @!method hash
+    #   Computes a hash-code for this headers container
+    #
+    #   @example
+    #     headers.hash
+    #
+    #   @see http://www.ruby-doc.org/core/Object.html#method-i-hash
+    #   @return [Fixnum]
+    #   @api public
+    def_delegator :@pile, :hash
+
+    # Properly clones internal key/value storage
+    #
+    # @return [void]
+    # @api private
+    def initialize_copy(_orig)
+      @pile = @pile.map(&:dup)
+    end
+
+    # Merges other headers into self
+    #
+    # @example
+    #   headers.merge!("Accept" => "text/html")
+    #
+    # @see #merge
+    # @return [void]
+    # @api public
+    def merge!(other)
+      coerced = self.class.coerce(other)
+      names = coerced.keys
+      names.each { |name| set name, coerced.get(name) }
+    end
+
+    # Returns new instance with other headers merged in
+    #
+    # @example
+    #   new_headers = headers.merge("Accept" => "text/html")
+    #
+    # @see #merge!
+    # @return [Headers]
+    # @api public
+    def merge(other)
+      dup.tap { |dupped| dupped.merge! other }
+    end
+
+    private
+
+    # Returns the wire name for a header
+    #
+    # @return [String]
+    # @api private
+    def wire_name_for(name, lookup_name)
+      case name
+      when String then name
+      when Symbol then lookup_name
+      else raise HeaderError, "HTTP header must be a String or Symbol: #{name.inspect}"
+      end
+    end
+
+    # Transforms name to canonical HTTP header capitalization
+    #
+    # @return [String]
+    # @api private
+    def normalize_header(name) = self.class.normalizer.call(name)
+
+    # Ensures there is no new line character in the header value
+    #
+    # @param [String] value
+    # @raise [HeaderError] if value includes new line character
+    # @return [String] stringified header value
+    # @api private
+    def validate_value(value)
+      v = value.to_s
+      return v unless v.include?("\n") || v.include?("\r")
+
+      raise HeaderError, "Invalid HTTP header field value: #{v.inspect}"
+    end
+  end
+end

data/lib/http/mime_type/adapter.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "forwardable"
+require "singleton"
+
+module HTTP
+  module MimeType
+    # Base encode/decode MIME type adapter
+    class Adapter
+      include Singleton
+
+      class << self
+        extend Forwardable
+
+        def_delegators :instance, :encode, :decode # steep:ignore
+      end
+
+      # Encodes data into the MIME type format
+      #
+      # @example
+      #   adapter.encode("foo" => "bar")
+      #
+      # @return [String] encoded representation
+      # @raise [Error] if not implemented by subclass
+      # @api public
+      def encode(*)
+        raise Error, "#{self.class} does not supports #encode"
+      end
+
+      # Decodes data from the MIME type format
+      #
+      # @example
+      #   adapter.decode("{\"foo\":\"bar\"}")
+      #
+      # @return [Object] decoded data
+      # @raise [Error] if not implemented by subclass
+      # @api public
+      def decode(*)
+        raise Error, "#{self.class} does not supports #decode"
+      end
+    end
+  end
+end

data/lib/http/mime_type/json.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "json"
+require "http/mime_type/adapter"
+
+module HTTP
+  # MIME type registry and adapter interface
+  module MimeType
+    # JSON encode/decode MIME type adapter
+    class JSON < Adapter
+      # Encodes object to JSON
+      #
+      # @example
+      #   adapter = HTTP::MimeType::JSON.new
+      #   adapter.encode(foo: "bar")
+      #
+      # @param [Object] obj object to encode
+      # @api public
+      # @return [String]
+      def encode(obj)
+        obj.to_json
+      end
+
+      # Decodes JSON string into Ruby object
+      #
+      # @example
+      #   adapter = HTTP::MimeType::JSON.new
+      #   adapter.decode('{"foo":"bar"}')
+      #
+      # @param [String] str JSON string to decode
+      # @api public
+      # @return [Object]
+      def decode(str)
+        ::JSON.parse str
+      end
+    end
+
+    register_adapter "application/json", JSON
+    register_alias   "application/json", :json
+  end
+end

data/lib/http/mime_type.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "http/errors"
+
+module HTTP
+  # MIME type encode/decode adapters
+  module MimeType
+    class << self
+      # Associate MIME type with adapter
+      #
+      # @example
+      #
+      #   module JsonAdapter
+      #     class << self
+      #       def encode(obj)
+      #         # encode logic here
+      #       end
+      #
+      #       def decode(str)
+      #         # decode logic here
+      #       end
+      #     end
+      #   end
+      #
+      #   HTTP::MimeType.register_adapter 'application/json', MyJsonAdapter
+      #
+      # @param [#to_s] type
+      # @param [#encode, #decode] adapter
+      # @api public
+      # @return [void]
+      def register_adapter(type, adapter)
+        adapters[type.to_s] = adapter
+      end
+
+      # Returns adapter associated with MIME type
+      #
+      # @example
+      #   HTTP::MimeType["application/json"]
+      #
+      # @param [#to_s] type
+      # @raise [Error] if no adapter found
+      # @api public
+      # @return [Class]
+      def [](type)
+        adapters[normalize type] || raise(UnsupportedMimeTypeError, "Unknown MIME type: #{type}")
+      end
+
+      # Register a shortcut for MIME type
+      #
+      # @example
+      #
+      #   HTTP::MimeType.register_alias 'application/json', :json
+      #
+      # @param [#to_s] type
+      # @param [#to_sym] shortcut
+      # @api public
+      # @return [void]
+      def register_alias(type, shortcut)
+        aliases[shortcut.to_sym] = type.to_s
+      end
+
+      # Resolves type by shortcut if possible
+      #
+      # @example
+      #   HTTP::MimeType.normalize(:json)
+      #
+      # @param [#to_s] type
+      # @api public
+      # @return [String]
+      def normalize(type)
+        aliases.fetch type, type.to_s
+      end
+
+      private
+
+      # Returns the adapters registry hash
+      #
+      # @api private
+      # @return [Hash]
+      def adapters
+        @adapters ||= {}
+      end
+
+      # Returns the aliases registry hash
+      #
+      # @api private
+      # @return [Hash]
+      def aliases
+        @aliases ||= {}
+      end
+    end
+  end
+end
+
+# built-in mime types
+require "http/mime_type/json"

data/lib/http/options/definitions.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+module HTTP
+  # Configuration options for HTTP requests and clients
+  class Options
+    def_option :headers do |new_headers|
+      headers.merge(new_headers) # steep:ignore
+    end
+
+    def_option :encoding do |encoding|
+      self.encoding = Encoding.find(encoding) # steep:ignore
+    end
+
+    def_option :features, reader_only: true do |new_features|
+      # Normalize features from:
+      #
+      #     [{feature_one: {opt: 'val'}}, :feature_two]
+      #
+      # into:
+      #
+      #     {feature_one: {opt: 'val'}, feature_two: {}}
+      acc = {} #: Hash[untyped, untyped]
+      normalized_features = new_features.each_with_object(acc) do |feature, h|
+        if feature.is_a?(Hash)
+          h.merge!(feature)
+        else
+          h[feature] = {} # steep:ignore
+        end
+      end
+
+      features.merge(normalized_features) # steep:ignore
+    end
+
+    # Sets and normalizes features hash
+    #
+    # @param [Hash] features
+    # @api private
+    # @return [Hash]
+    def features=(features)
+      result = {} #: Hash[Symbol, Feature]
+      @features = features.each_with_object(result) do |(name, opts_or_feature), h|
+        h[name] = if opts_or_feature.is_a?(Feature)
+                    opts_or_feature
+                  else
+                    unless (feature = self.class.available_features[name])
+                      argument_error! "Unsupported feature: #{name}"
+                    end
+                    feature.new(**opts_or_feature) # steep:ignore
+                  end
+      end
+    end
+
+    %w[
+      proxy params form json body response
+      socket_class nodelay ssl_socket_class ssl_context ssl
+      keep_alive_timeout timeout_class timeout_options
+    ].each do |method_name|
+      def_option method_name
+    end
+
+    def_option :follow, reader_only: true
+
+    # Sets follow redirect options
+    #
+    # @param [Boolean, Hash, nil] value
+    # @api private
+    # @return [Hash, nil]
+    def follow=(value)
+      @follow =
+        if    !value                    then nil
+        elsif true == value             then {} #: Hash[untyped, untyped]
+        elsif value.respond_to?(:fetch) then value
+        else argument_error! "Unsupported follow options: #{value}"
+        end
+    end
+
+    def_option :retriable, reader_only: true
+
+    # Sets retriable options
+    #
+    # @param [Boolean, Hash, nil] value
+    # @api private
+    # @return [Hash, nil]
+    def retriable=(value)
+      @retriable =
+        if    !value                    then nil
+        elsif true == value             then {} #: Hash[untyped, untyped]
+        elsif value.respond_to?(:fetch) then value
+        else argument_error! "Unsupported retriable options: #{value}"
+        end
+    end
+
+    def_option :base_uri, reader_only: true
+
+    # Sets the base URI for resolving relative request paths
+    #
+    # @param [String, HTTP::URI, nil] value
+    # @api private
+    # @return [HTTP::URI, nil]
+    def base_uri=(value)
+      @base_uri = value ? parse_base_uri(value) : nil
+      validate_base_uri_and_persistent!
+    end
+
+    # Checks whether a base URI is set
+    #
+    # @example
+    #   opts = HTTP::Options.new(base_uri: "https://example.com")
+    #   opts.base_uri?
+    #
+    # @api public
+    # @return [Boolean]
+    def base_uri?
+      !base_uri.nil?
+    end
+
+    def_option :persistent, reader_only: true
+
+    # Sets persistent connection origin
+    #
+    # @param [String, nil] value
+    # @api private
+    # @return [String, nil]
+    def persistent=(value)
+      @persistent = value ? URI.parse(value).origin : nil
+      validate_base_uri_and_persistent!
+    end
+
+    # Checks whether persistent connection is enabled
+    #
+    # @example
+    #   opts = HTTP::Options.new(persistent: "http://example.com")
+    #   opts.persistent?
+    #
+    # @api public
+    # @return [Boolean]
+    def persistent?
+      !persistent.nil?
+    end
+
+    private
+
+    # Parses and validates a base URI value
+    #
+    # @param [String, HTTP::URI] value the base URI to parse
+    # @api private
+    # @return [HTTP::URI]
+    def parse_base_uri(value)
+      uri = URI.parse(value)
+
+      base = @base_uri
+      return resolve_base_uri(base, uri) if base
+
+      argument_error!(format("Invalid base URI: %s", value)) unless uri.scheme
+      uri
+    end
+
+    # Resolves a relative URI against an existing base URI
+    #
+    # @param [HTTP::URI] base the existing base URI
+    # @param [HTTP::URI] relative the URI to join
+    # @api private
+    # @return [HTTP::URI]
+    def resolve_base_uri(base, relative)
+      unless base.path.end_with?("/")
+        base = base.dup
+        base.path = "#{base.path}/"
+      end
+
+      URI.parse(base.join(relative))
+    end
+
+    # Validates that base URI and persistent origin are compatible
+    #
+    # @api private
+    # @return [void]
+    def validate_base_uri_and_persistent!
+      base = @base_uri
+      persistent = @persistent
+      return unless base && persistent
+      return if base.origin.eql?(persistent)
+
+      argument_error!(
+        format("Persistence origin (%s) conflicts with base URI origin (%s)",
+               persistent, base.origin)
+      )
+    end
+  end
+end