ruby-http-session 1.0.1

data/lib/http/session/configurable.rb

@@ -0,0 +1,143 @@
+class HTTP::Session
+  # Provides the same configure API interfaces as HTTP::Client.
+  #
+  # Mostly borrowed from [http/lib/http/chainable.rb](https://github.com/httprb/http/blob/main/lib/http/chainable.rb)
+  module Configurable
+    # Set timeout on request.
+    #
+    # @overload timeout(options = {})
+    #   Adds per operation timeouts to the request.
+    #   @param [Hash] options
+    #   @option options [Float] :read Read timeout
+    #   @option options [Float] :write Write timeout
+    #   @option options [Float] :connect Connect timeout
+    #   @return [Session]
+    #
+    # @overload timeout(global_timeout)
+    #   Adds a global timeout to the full request.
+    #   @param [Numeric] global_timeout
+    #   @return [Session]
+    def timeout(options)
+      klass, options =
+        case options
+        when Numeric then [HTTP::Timeout::Global, {global: options}]
+        when Hash then [HTTP::Timeout::PerOperation, options.dup]
+        when :null then [HTTP::Timeout::Null, {}]
+        else raise ArgumentError, "Use `.timeout(global_timeout_in_seconds)` or `.timeout(connect: x, write: y, read: z)`."
+        end
+
+      %i[global read write connect].each do |k|
+        next unless options.key? k
+        options["#{k}_timeout".to_sym] = options.delete k
+      end
+
+      branch default_options.merge(
+        timeout_class: klass,
+        timeout_options: options
+      )
+    end
+
+    # Make a request through an HTTP proxy.
+    #
+    # @param [Array] proxy
+    # @return [Session]
+    def via(*proxy)
+      proxy_hash = {}
+      proxy_hash[:proxy_address] = proxy[0] if proxy[0].is_a?(String)
+      proxy_hash[:proxy_port] = proxy[1] if proxy[1].is_a?(Integer)
+      proxy_hash[:proxy_username] = proxy[2] if proxy[2].is_a?(String)
+      proxy_hash[:proxy_password] = proxy[3] if proxy[3].is_a?(String)
+      proxy_hash[:proxy_headers] = proxy[2] if proxy[2].is_a?(Hash)
+      proxy_hash[:proxy_headers] = proxy[4] if proxy[4].is_a?(Hash)
+      raise ArgumentError, "invalid HTTP proxy: #{proxy_hash}" unless (2..5).cover?(proxy_hash.keys.size)
+
+      branch default_options.with_proxy(proxy_hash)
+    end
+    alias_method :through, :via
+
+    # Make client follow redirects.
+    #
+    # @param options
+    # @return [Session]
+    def follow(options = {})
+      branch default_options.with_follow options
+    end
+
+    # Make a request with the given headers.
+    #
+    # @param headers
+    # @return [Session]
+    def headers(headers)
+      branch default_options.with_headers(headers)
+    end
+
+    # Make a request with the given cookies.
+    #
+    # @param cookies
+    # @return [Session]
+    def cookies(cookies)
+      branch default_options.with_cookies(cookies)
+    end
+
+    # Force a specific encoding for response body.
+    #
+    # @param encoding
+    # @return [Session]
+    def encoding(encoding)
+      branch default_options.with_encoding(encoding)
+    end
+
+    # Accept the given MIME type(s).
+    #
+    # @param type
+    # @return [Session]
+    def accept(type)
+      headers HTTP::Headers::ACCEPT => HTTP::MimeType.normalize(type)
+    end
+
+    # Make a request with the given Authorization header.
+    #
+    # @param [#to_s] value Authorization header value
+    # @return [Session]
+    def auth(value)
+      headers HTTP::Headers::AUTHORIZATION => value.to_s
+    end
+
+    # Make a request with the given Basic authorization header.
+    #
+    # @see https://datatracker.ietf.org/doc/html/rfc2617
+    # @param [#fetch] opts
+    # @option opts [#to_s] :user
+    # @option opts [#to_s] :pass
+    # @return [Session]
+    def basic_auth(opts)
+      user = opts.fetch(:user)
+      pass = opts.fetch(:pass)
+      creds = "#{user}:#{pass}"
+
+      auth("Basic #{Base64.strict_encode64(creds)}")
+    end
+
+    # Set TCP_NODELAY on the socket.
+    #
+    # @return [Session]
+    def nodelay
+      branch default_options.with_nodelay(true)
+    end
+
+    # Turn on given features.
+    #
+    # @return [Session]
+    def use(*features)
+      branch default_options.with_features(features)
+    end
+
+    private
+
+    # :nodoc:
+    def branch(default_options)
+      raise FrozenError, "can't modify frozen #{self.class.name}" if frozen?
+      self
+    end
+  end
+end

data/lib/http/session/features/auto_inflate.rb

@@ -0,0 +1,60 @@
+require "set"
+
+class HTTP::Session
+  module Features
+    class AutoInflate < HTTP::Feature
+      def initialize(br: false)
+        load_dependencies if br
+
+        @supported_encoding = Set.new(%w[deflate gzip x-gzip])
+        @supported_encoding.add("br") if br
+        @supported_encoding.freeze
+      end
+
+      def wrap_response(response)
+        content_encoding = response.headers.get(HTTP::Headers::CONTENT_ENCODING).first
+        return response unless content_encoding && @supported_encoding.include?(content_encoding)
+
+        content =
+          case content_encoding
+          when "br" then brotli_inflate(response.body)
+          else inflate(response.body)
+          end
+        response.headers.delete(HTTP::Headers::CONTENT_ENCODING)
+        response.headers[HTTP::Headers::CONTENT_LENGTH] = content.length
+
+        options = {
+          status: response.status,
+          version: response.version,
+          headers: response.headers,
+          proxy_headers: response.proxy_headers,
+          body: HTTP::Session::Response::StringBody.new(content),
+          request: response.request
+        }
+        HTTP::Response.new(options)
+      end
+
+      private
+
+      def load_dependencies
+        require "brotli"
+      rescue LoadError
+        raise LoadError,
+          "Specified 'brotli' for inflate, but the gem is not loaded. Add `gem 'brotli'` to your Gemfile."
+      end
+
+      def brotli_inflate(body)
+        Brotli.inflate(body)
+      end
+
+      def inflate(body)
+        zstream = Zlib::Inflate.new(32 + Zlib::MAX_WBITS)
+        zstream.inflate(body)
+      ensure
+        zstream.close
+      end
+
+      HTTP::Options.register_feature(:hsf_auto_inflate, self)
+    end
+  end
+end

data/lib/http/session/options/cache_option.rb

@@ -0,0 +1,83 @@
+class HTTP::Session
+  class Options
+    class CacheOption
+      # @!attribute [r] store
+      #   @return [ActiveSupport::Cache::Store]
+      attr_reader :store
+
+      # @param [Hash] options
+      # @option options [Boolean] :private set true if it is a private cache
+      # @option options [Boolean] :shared set true if it is a shared cache
+      # @option options [ActiveSupport::Cache::Store] :store
+      def initialize(options)
+        options =
+          case options
+          when nil, false then {enabled: false}
+          when true then {enabled: true}
+          else options
+          end
+
+        # Enabled / Disabled
+        @enabled = options.fetch(:enabled, true)
+
+        # Shared Cache / Private Cache
+        @shared =
+          if options.key?(:shared)
+            raise ArgumentError, ":shared and :private cannot be used at the same time" if options.key?(:private)
+            !!options[:shared]
+          elsif options.key?(:private)
+            !options[:private]
+          else
+            true
+          end
+
+        # Cache Store
+        @store =
+          if @enabled
+            store = options[:store]
+            if store.respond_to?(:read) && store.respond_to?(:write)
+              store
+            else
+              lookup_store(store)
+            end
+          end
+      end
+
+      # Indicates whether or not the session cache feature is enabled.
+      def enabled?
+        @enabled
+      end
+
+      # True when it is a shared cache.
+      #
+      # Shared Cache that exists between the origin server and clients (e.g. Proxy, CDN).
+      # It stores a single response and reuses it with multiple users
+      def shared_cache?
+        @shared
+      end
+
+      # True when it is a private cache.
+      #
+      # Private Cache that exists in the client. It is also called local cache or browser cache.
+      # It can store and reuse personalized content for a single user.
+      def private_cache?
+        !shared_cache?
+      end
+
+      private
+
+      def lookup_store(store)
+        load_dependencies
+        ActiveSupport::Cache.lookup_store(store)
+      end
+
+      def load_dependencies
+        require "active_support/cache"
+        require "active_support/notifications"
+      rescue LoadError
+        raise LoadError,
+          "Specified 'active_support' for caching, but the gem is not loaded. Add `gem 'active_support'` to your Gemfile."
+      end
+    end
+  end
+end

data/lib/http/session/options/cookies_option.rb

@@ -0,0 +1,22 @@
+class HTTP::Session
+  class Options
+    class CookiesOption
+      # @param [Hash] options
+      def initialize(options)
+        options =
+          case options
+          when nil, false then {enabled: false}
+          when true then {enabled: true}
+          else options
+          end
+
+        @enabled = options.fetch(:enabled, true)
+      end
+
+      # Indicates whether or not the session cookie feature is enabled.
+      def enabled?
+        @enabled
+      end
+    end
+  end
+end

data/lib/http/session/options.rb

@@ -0,0 +1,80 @@
+class HTTP::Session
+  class Options
+    # @!attribute [r] cookies
+    #   @return [CookiesOption]
+    attr_reader :cookies
+
+    # @!attribute [r] cache
+    #   @return [CacheOption]
+    attr_reader :cache
+
+    # @!attribute [r] http
+    #   @return [HTTP::Options]
+    attr_reader :http
+
+    # @param [Hash] options
+    def initialize(options)
+      @cookies = HTTP::Session::Options::CookiesOption.new(options.fetch(:cookies, false))
+      @cache = HTTP::Session::Options::CacheOption.new(options.fetch(:cache, false))
+      @http = HTTP::Options.new(
+        options.fetch(:http, {}).slice(
+          :cookies,
+          :encoding,
+          :features,
+          :follow,
+          :headers,
+          :keep_alive_timeout,
+          :nodelay,
+          :proxy,
+          :response,
+          :ssl,
+          :ssl_socket_class,
+          :socket_class,
+          :timeout_class,
+          :timeout_options
+        )
+      )
+    end
+
+    # @return [Options]
+    def merge(other)
+      tap { @http = @http.merge(other) }
+    end
+
+    # @return [Options]
+    def with_cookies(cookies)
+      tap { @http = @http.with_cookies(cookies) }
+    end
+
+    # @return [Options]
+    def with_encoding(encoding)
+      tap { @http = @http.with_encoding(encoding) }
+    end
+
+    # @return [Options]
+    def with_features(features)
+      raise ArgumentError, "feature :auto_inflate is not supported, use :hsf_auto_inflate instead" if features.include?(:auto_inflate)
+      tap { @http = @http.with_features(features) }
+    end
+
+    # @return [Options]
+    def with_follow(follow)
+      tap { @http = @http.with_follow(follow) }
+    end
+
+    # @return [Options]
+    def with_headers(headers)
+      tap { @http = @http.with_headers(headers) }
+    end
+
+    # @return [Options]
+    def with_nodelay(nodelay)
+      tap { @http = @http.with_nodelay(nodelay) }
+    end
+
+    # @return [Options]
+    def with_proxy(proxy)
+      tap { @http = @http.with_proxy(proxy) }
+    end
+  end
+end

data/lib/http/session/request.rb

@@ -0,0 +1,31 @@
+class HTTP::Session
+  # Provides access to the HTTP request.
+  #
+  # Mostly borrowed from [rack-cache/lib/rack/cache/request.rb](https://github.com/rack/rack-cache/blob/main/lib/rack/cache/request.rb)
+  class Request < SimpleDelegator
+    class << self
+      def new(*args)
+        args[0].is_a?(self) ? args[0] : super
+      end
+    end
+
+    # A CacheControl instance based on the request's cache-control header.
+    #
+    # @return [Cache::CacheControl]
+    def cache_control
+      @cache_control ||= HTTP::Session::Cache::CacheControl.new(headers[HTTP::Headers::CACHE_CONTROL])
+    end
+
+    # True when the cache-control/no-cache directive is present.
+    def no_cache?
+      cache_control.no_cache?
+    end
+
+    # Determine if the request is worth caching under any circumstance.
+    def cacheable?
+      return false if verb != :get && verb != :head
+      return false if cache_control.no_store?
+      true
+    end
+  end
+end

data/lib/http/session/requestable.rb

@@ -0,0 +1,87 @@
+class HTTP::Session
+  # Provides the same request API interfaces as HTTP::Client.
+  #
+  # Mostly borrowed from [http/lib/http/chainable.rb](https://github.com/httprb/http/blob/main/lib/http/chainable.rb)
+  module Requestable
+    # Request a get sans response body.
+    #
+    # @param uri
+    # @option [Hash] options
+    # @return [Response]
+    def head(uri, options = {})
+      request :head, uri, options
+    end
+
+    # Get a resource.
+    #
+    # @param uri
+    # @option [Hash] options
+    # @return [Response]
+    def get(uri, options = {})
+      request :get, uri, options
+    end
+
+    # Post to a resource.
+    #
+    # @param uri
+    # @option [Hash] options
+    # @return [Response]
+    def post(uri, options = {})
+      request :post, uri, options
+    end
+
+    # Put to a resource.
+    #
+    # @param uri
+    # @option [Hash] options
+    # @return [Response]
+    def put(uri, options = {})
+      request :put, uri, options
+    end
+
+    # Delete a resource.
+    #
+    # @param uri
+    # @option [Hash] options
+    # @return [Response]
+    def delete(uri, options = {})
+      request :delete, uri, options
+    end
+
+    # Echo the request back to the client.
+    #
+    # @param uri
+    # @option [Hash] options
+    # @return [Response]
+    def trace(uri, options = {})
+      request :trace, uri, options
+    end
+
+    # Return the methods supported on the given URI.
+    #
+    # @param uri
+    # @option [Hash] options
+    # @return [Response]
+    def options(uri, options = {})
+      request :options, uri, options
+    end
+
+    # Convert to a transparent TCP/IP tunnel.
+    #
+    # @param uri
+    # @option [Hash] options
+    # @return [Response]
+    def connect(uri, options = {})
+      request :connect, uri, options
+    end
+
+    # Apply partial modifications to a resource.
+    #
+    # @param uri
+    # @option [Hash] options
+    # @return [Response]
+    def patch(uri, options = {})
+      request :patch, uri, options
+    end
+  end
+end

data/lib/http/session/response/string_body.rb

@@ -0,0 +1,20 @@
+require "forwardable"
+
+class HTTP::Session
+  class Response < SimpleDelegator
+    class StringBody
+      extend Forwardable
+
+      def_delegator :to_s, :empty?
+
+      def initialize(contents)
+        @contents = contents
+      end
+
+      def to_s
+        @contents
+      end
+      alias_method :to_str, :to_s
+    end
+  end
+end

data/lib/http/session/response.rb

@@ -0,0 +1,176 @@
+class HTTP::Session
+  # Provides access to the HTTP response.
+  #
+  # Mostly borrowed from [rack-cache/lib/rack/cache/response.rb](https://github.com/rack/rack-cache/blob/main/lib/rack/cache/response.rb)
+  class Response < SimpleDelegator
+    class << self
+      def new(*args)
+        args[0].is_a?(self) ? args[0] : super
+      end
+    end
+
+    # Status codes of responses that MAY be stored by a cache or used in reply
+    # to a subsequent request.
+    #
+    # https://datatracker.ietf.org/doc/html/rfc9110#section-15.1
+    CACHEABLE_RESPONSE_CODES = [
+      200, # OK
+      203, # Non-Authoritative Information
+      204, # No Content
+      206, # Partial Content
+      300, # Multiple Choices
+      301, # Moved Permanently
+      308, # Permanent Redirect
+      404, # Not Found
+      405, # Method Not Allowed
+      410, # Gone
+      414, # URI Too Long
+      501  # Not Implemented
+    ].to_set
+
+    # @!attribute [rw] history
+    #   @return [Array<Response>] a list of response objects holding the history of the redirection
+    attr_accessor :history
+
+    # Returns a new instance of Response.
+    def initialize(*args)
+      super
+
+      _hs_ensure_header_date
+      @history = []
+    end
+
+    # Determine if the response is served from cache.
+    def from_cache?
+      v = headers[HTTP::Session::Cache::Status::HEADER_NAME]
+      HTTP::Session::Cache::Status.HIT?(v)
+    end
+
+    # A CacheControl instance based on the response's cache-control header.
+    #
+    # @return [Cache::CacheControl]
+    def cache_control
+      @cache_control ||= HTTP::Session::Cache::CacheControl.new(headers[HTTP::Headers::CACHE_CONTROL])
+    end
+
+    # True when the cache-control/no-cache directive is present.
+    def no_cache?
+      cache_control.no_cache?
+    end
+
+    # Determine if the response is worth caching under any circumstance.
+    #
+    # https://datatracker.ietf.org/doc/html/rfc9111#section-3
+    def cacheable?(shared:, req:)
+      # the response status code is final (see Section 15 of [HTTP])
+      return false unless CACHEABLE_RESPONSE_CODES.include?(status)
+
+      # the no-store cache directive is not present in the response (see Section 5.2.2.5)
+      return false if cache_control.no_store?
+
+      # if the cache is shared
+      if shared
+        # the private response directive is either not present or allows a shared cache
+        # to store a modified response; see Section 5.2.2.7)
+        return false if cache_control.private?
+
+        # the Authorization header field is not present in the request (see Section 11.6.2
+        # of [HTTP]) or a response directive is present that explicitly allows shared
+        # caching (see Section 3.5)
+        return false if req.headers[HTTP::Headers::AUTHORIZATION] &&
+          (!cache_control.public? && !cache_control.shared_max_age)
+      end
+
+      # responses with neither a freshness lifetime (expires, max-age) nor cache validator
+      # (last-modified, etag) are considered uncacheable
+      validateable? || fresh?(shared: shared)
+    end
+
+    # Determine if the response includes headers that can be used to validate
+    # the response with the origin using a conditional GET request.
+    def validateable?
+      headers.include?(HTTP::Headers::LAST_MODIFIED) || headers.include?(HTTP::Headers::ETAG)
+    end
+
+    # Determine if the response is "fresh". Fresh responses may be served from
+    # cache without any interaction with the origin. A response is considered
+    # fresh when it includes a cache-control/max-age indicator or Expiration
+    # header and the calculated age is less than the freshness lifetime.
+    def fresh?(shared:)
+      ttl(shared: shared) && ttl(shared: shared) > 0
+    end
+
+    # The response's time-to-live in seconds, or nil when no freshness
+    # information is present in the response. When the responses #ttl
+    # is <= 0, the response may not be served from cache without first
+    # revalidating with the origin.
+    #
+    # @return [Numeric]
+    def ttl(shared:)
+      max_age(shared: shared) - age if max_age(shared: shared)
+    end
+
+    # The number of seconds after the time specified in the response's Date
+    # header when the the response should no longer be considered fresh. First
+    # check for a r-maxage directive, then a s-maxage directive, then a max-age
+    # directive, and then fall back on an expires header; return nil when no
+    # maximum age can be established.
+    #
+    # @return [Numeric]
+    def max_age(shared:)
+      (shared && cache_control.shared_max_age) ||
+        cache_control.max_age ||
+        (expires && (expires - date))
+    end
+
+    # The value of the expires header as a Time object.
+    #
+    # @return [Time]
+    def expires
+      headers[HTTP::Headers::EXPIRES] && Time.httpdate(headers[HTTP::Headers::EXPIRES])
+    rescue
+      nil
+    end
+
+    # The date of the response.
+    #
+    # @return [Time]
+    def date
+      Time.httpdate(headers[HTTP::Headers::DATE])
+    end
+
+    # The age of the response.
+    #
+    # @return [Numeric]
+    def age
+      (headers[HTTP::Headers::AGE] || [(now - date).to_i, 0].max).to_i
+    end
+
+    # The literal value of ETag HTTP header or nil if no etag is specified.
+    def etag
+      headers[HTTP::Headers::ETAG]
+    end
+
+    # The String value of the Last-Modified header exactly as it appears
+    # in the response (i.e., no date parsing / conversion is performed).
+    def last_modified
+      headers[HTTP::Headers::LAST_MODIFIED]
+    end
+
+    # The current time.
+    #
+    # @return [Time]
+    def now
+      Time.now
+    end
+
+    private
+
+    # When no Date header is present or is unparseable, set the Date header to Time.now.
+    def _hs_ensure_header_date
+      date
+    rescue
+      headers[HTTP::Headers::DATE] = now.httpdate
+    end
+  end
+end