ruby-http-session 1.0.1

data/lib/http/session/cache/cache_control.rb

@@ -0,0 +1,196 @@
+class HTTP::Session
+  class Cache
+    # Parses a cache-control header and exposes the directives as a Hash.
+    # Directives that do not have values are set to +true+.
+    #
+    # Mostly borrowed from [rack-cache/lib/rack/cache/cache_control.rb](https://github.com/rack/rack-cache/blob/main/lib/rack/cache/cache_control.rb)
+    class CacheControl < Hash
+      def initialize(value = nil)
+        parse(value)
+      end
+
+      # Indicates that the response MAY be cached by any cache, even if it
+      # would normally be non-cacheable or cacheable only within a non-
+      # shared cache.
+      #
+      # A response may be considered public without this directive if the
+      # private directive is not set and the request does not include an
+      # Authorization header.
+      def public?
+        self["public"]
+      end
+
+      # Indicates that all or part of the response message is intended for
+      # a single user and MUST NOT be cached by a shared cache. This
+      # allows an origin server to state that the specified parts of the
+      # response are intended for only one user and are not a valid
+      # response for requests by other users. A private (non-shared) cache
+      # MAY cache the response.
+      #
+      # Note: This usage of the word private only controls where the
+      # response may be cached, and cannot ensure the privacy of the
+      # message content.
+      def private?
+        self["private"]
+      end
+
+      # When set in a response, a cache MUST NOT use the response to satisfy a
+      # subsequent request without successful revalidation with the origin
+      # server. This allows an origin server to prevent caching even by caches
+      # that have been configured to return stale responses to client requests.
+      #
+      # Note that this does not necessary imply that the response may not be
+      # stored by the cache, only that the cache cannot serve it without first
+      # making a conditional GET request with the origin server.
+      #
+      # When set in a request, the server MUST NOT use a cached copy for its
+      # response. This has quite different semantics compared to the no-cache
+      # directive on responses. When the client specifies no-cache, it causes
+      # an end-to-end reload, forcing each cache to update their cached copies.
+      def no_cache?
+        self["no-cache"]
+      end
+
+      # Indicates that the response MUST NOT be stored under any circumstances.
+      #
+      # The purpose of the no-store directive is to prevent the
+      # inadvertent release or retention of sensitive information (for
+      # example, on backup tapes). The no-store directive applies to the
+      # entire message, and MAY be sent either in a response or in a
+      # request. If sent in a request, a cache MUST NOT store any part of
+      # either this request or any response to it. If sent in a response,
+      # a cache MUST NOT store any part of either this response or the
+      # request that elicited it. This directive applies to both non-
+      # shared and shared caches. "MUST NOT store" in this context means
+      # that the cache MUST NOT intentionally store the information in
+      # non-volatile storage, and MUST make a best-effort attempt to
+      # remove the information from volatile storage as promptly as
+      # possible after forwarding it.
+      #
+      # The purpose of this directive is to meet the stated requirements
+      # of certain users and service authors who are concerned about
+      # accidental releases of information via unanticipated accesses to
+      # cache data structures. While the use of this directive might
+      # improve privacy in some cases, we caution that it is NOT in any
+      # way a reliable or sufficient mechanism for ensuring privacy. In
+      # particular, malicious or compromised caches might not recognize or
+      # obey this directive, and communications networks might be
+      # vulnerable to eavesdropping.
+      def no_store?
+        self["no-store"]
+      end
+
+      # The expiration time of an entity MAY be specified by the origin
+      # server using the expires header (see section 14.21). Alternatively,
+      # it MAY be specified using the max-age directive in a response. When
+      # the max-age cache-control directive is present in a cached response,
+      # the response is stale if its current age is greater than the age
+      # value given (in seconds) at the time of a new request for that
+      # resource. The max-age directive on a response implies that the
+      # response is cacheable (i.e., "public") unless some other, more
+      # restrictive cache directive is also present.
+      #
+      # If a response includes both an expires header and a max-age
+      # directive, the max-age directive overrides the expires header, even
+      # if the expires header is more restrictive. This rule allows an origin
+      # server to provide, for a given response, a longer expiration time to
+      # an HTTP/1.1 (or later) cache than to an HTTP/1.0 cache. This might be
+      # useful if certain HTTP/1.0 caches improperly calculate ages or
+      # expiration times, perhaps due to desynchronized clocks.
+      #
+      # Many HTTP/1.0 cache implementations will treat an expires value that
+      # is less than or equal to the response Date value as being equivalent
+      # to the cache-control response directive "no-cache". If an HTTP/1.1
+      # cache receives such a response, and the response does not include a
+      # cache-control header field, it SHOULD consider the response to be
+      # non-cacheable in order to retain compatibility with HTTP/1.0 servers.
+      #
+      # When the max-age directive is included in the request, it indicates
+      # that the client is willing to accept a response whose age is no
+      # greater than the specified time in seconds.
+      def max_age
+        self["max-age"].to_i if key?("max-age")
+      end
+
+      # If a response includes an s-maxage directive, then for a shared
+      # cache (but not for a private cache), the maximum age specified by
+      # this directive overrides the maximum age specified by either the
+      # max-age directive or the expires header. The s-maxage directive
+      # also implies the semantics of the proxy-revalidate directive. i.e.,
+      # that the shared cache must not use the entry after it becomes stale
+      # to respond to a subsequent request without first revalidating it with
+      # the origin server. The s-maxage directive is always ignored by a
+      # private cache.
+      def shared_max_age
+        self["s-maxage"].to_i if key?("s-maxage")
+      end
+      alias_method :s_maxage, :shared_max_age
+
+      # Because a cache MAY be configured to ignore a server's specified
+      # expiration time, and because a client request MAY include a max-
+      # stale directive (which has a similar effect), the protocol also
+      # includes a mechanism for the origin server to require revalidation
+      # of a cache entry on any subsequent use. When the must-revalidate
+      # directive is present in a response received by a cache, that cache
+      # MUST NOT use the entry after it becomes stale to respond to a
+      # subsequent request without first revalidating it with the origin
+      # server. (I.e., the cache MUST do an end-to-end revalidation every
+      # time, if, based solely on the origin server's expires or max-age
+      # value, the cached response is stale.)
+      #
+      # The must-revalidate directive is necessary to support reliable
+      # operation for certain protocol features. In all circumstances an
+      # HTTP/1.1 cache MUST obey the must-revalidate directive; in
+      # particular, if the cache cannot reach the origin server for any
+      # reason, it MUST generate a 504 (Gateway Timeout) response.
+      #
+      # Servers SHOULD send the must-revalidate directive if and only if
+      # failure to revalidate a request on the entity could result in
+      # incorrect operation, such as a silently unexecuted financial
+      # transaction. Recipients MUST NOT take any automated action that
+      # violates this directive, and MUST NOT automatically provide an
+      # unvalidated copy of the entity if revalidation fails.
+      def must_revalidate?
+        self["must-revalidate"]
+      end
+
+      # The proxy-revalidate directive has the same meaning as the must-
+      # revalidate directive, except that it does not apply to non-shared
+      # user agent caches. It can be used on a response to an
+      # authenticated request to permit the user's cache to store and
+      # later return the response without needing to revalidate it (since
+      # it has already been authenticated once by that user), while still
+      # requiring proxies that service many users to revalidate each time
+      # (in order to make sure that each user has been authenticated).
+      # Note that such authenticated responses also need the public cache
+      # control directive in order to allow them to be cached at all.
+      def proxy_revalidate?
+        self["proxy-revalidate"]
+      end
+
+      def to_s
+        bools, vals = [], []
+        each do |key, value|
+          if value == true
+            bools << key
+          elsif value
+            vals << "#{key}=#{value}"
+          end
+        end
+        (bools.sort + vals.sort).join(", ")
+      end
+
+      private
+
+      def parse(value)
+        return if value.nil? || value.empty?
+        value.delete(" ").split(",").each do |part|
+          next if part.empty?
+          name, value = part.split("=", 2)
+          self[name.downcase] = (value || true) unless name.empty?
+        end
+        self
+      end
+    end
+  end
+end

data/lib/http/session/cache/entry.rb

@@ -0,0 +1,71 @@
+class HTTP::Session
+  class Cache
+    class Entry
+      class << self
+        # Deserializes from a JSON primitive type.
+        def deserialize(h)
+          req = h[:req]
+          req = HTTP::Session::Request.new(HTTP::Request.new(req))
+
+          res = h[:res]
+          res[:request] = req
+          res[:body] = HTTP::Session::Response::StringBody.new(res[:body])
+          res = HTTP::Session::Response.new(HTTP::Response.new(res))
+
+          new(req, res)
+        end
+      end
+
+      # @!attribute [r] request
+      #   @return [Request]
+      attr_reader :request
+
+      # @!attribute [r] response
+      #   @return [Response]
+      attr_reader :response
+
+      # Returns a new instance of Entry.
+      def initialize(req, res)
+        @request = req
+        @response = res
+      end
+
+      # @param [Request] req                                                 │
+      # @return [Response]
+      def to_response(req)
+        h = serialize_response
+        h[:request] = req
+        h[:body] = HTTP::Session::Response::StringBody.new(h[:body])
+        HTTP::Session::Response.new(HTTP::Response.new(h))
+      end
+
+      # Serializes to a JSON primitive type.
+      def serialize
+        {
+          req: serialize_request,
+          res: serialize_response
+        }
+      end
+
+      private
+
+      def serialize_request
+        {
+          verb: @request.verb,
+          uri: @request.uri.to_s,
+          headers: @request.headers.to_h
+        }
+      end
+
+      def serialize_response
+        {
+          status: @response.status.code,
+          version: @response.version,
+          headers: @response.headers.to_h,
+          proxy_headers: @response.proxy_headers.to_h,
+          body: @response.body.to_s
+        }
+      end
+    end
+  end
+end

data/lib/http/session/cache/status.rb

@@ -0,0 +1,20 @@
+class HTTP::Session
+  class Cache
+    class Status
+      # rubocop:disable Layout/ExtraSpacing
+      HEADER_NAME = "X-Httprb-Cache-Status"
+      HIT         = "HIT"         # found in cache
+      REVALIDATED = "REVALIDATED" # found in cache but stale, revalidated success
+      EXPIRED     = "EXPIRED"     # found in cache but stale, revalidated failure, served from the origin server
+      MISS        = "MISS"        # not found in cache, served from the origin server
+      UNCACHEABLE = "UNCACHEABLE" # the request can not use cached response
+      # rubocop:enable Layout/ExtraSpacing
+
+      class << self
+        def HIT?(v)
+          v == HIT || v == REVALIDATED
+        end
+      end
+    end
+  end
+end

data/lib/http/session/cache.rb

@@ -0,0 +1,95 @@
+class HTTP::Session
+  class Cache
+    include MonitorMixin
+
+    # @param [Options::CacheOption] options
+    def initialize(options)
+      super()
+
+      @options = options
+    end
+
+    # Read an entry from cache.
+    #
+    # @param [Request] req
+    # @return [Entry]
+    def read(req)
+      synchronize do
+        key = cache_key_for(req)
+        entries = read_entries(key)
+        entries.find { |e| entry_matched?(e, req) }
+      end
+    end
+
+    # Write an entry to cache.
+    #
+    # @param [Request] req
+    # @param [Response] res
+    # @return [void]
+    def write(req, res)
+      synchronize do
+        key = cache_key_for(req)
+        entries = read_entries(key)
+        entries = entries.reject { |e| entry_matched?(e, req) }
+        entry = HTTP::Session::Cache::Entry.new(req, res)
+        entries << entry
+        write_entries(key, entries)
+      end
+    end
+
+    # True when it is a shared cache.
+    def shared?
+      @options.shared_cache?
+    end
+
+    # True when it is a private cache.
+    def private?
+      @options.private_cache?
+    end
+
+    # @!visibility private
+    def store
+      @options.store
+    end
+
+    private
+
+    def entry_matched?(entry, req)
+      entry_matched_by_verb?(entry, req) &&
+        entry_matched_by_headers?(entry, req)
+    end
+
+    def entry_matched_by_verb?(entry, req)
+      entry.request.verb == req.verb
+    end
+
+    def entry_matched_by_headers?(entry, req)
+      vary = entry.response.headers[HTTP::Headers::VARY]
+      return true if vary.nil? || vary == ""
+
+      vary != "*" && vary.split(",").map(&:strip).all? do |name|
+        entry.request.headers[name] == req.headers[name]
+      end
+    end
+
+    def read_entries(key)
+      entrie = store.read(key) || []
+      entrie.map do |e|
+        Entry.deserialize(e)
+      end
+    end
+
+    def write_entries(key, entries)
+      entries = entries.map do |e|
+        e = e.serialize
+        e[:res][:headers].delete(HTTP::Headers::AGE)
+        e
+      end
+      store.write(key, entries)
+    end
+
+    def cache_key_for(req)
+      Digest::SHA256.hexdigest(req.uri)
+    end
+  end
+end

data/lib/http/session/client/perform.rb

@@ -0,0 +1,143 @@
+class HTTP::Session
+  class Client
+    # Make an HTTP request without any HTTP::Features.
+    #
+    # Mostly borrowed from [http/lib/http/client.rb](https://github.com/httprb/http/blob/main/lib/http/client.rb)
+    module Perform
+      HTTP_OR_HTTPS_RE = %r{^https?://}i
+
+      attr_reader :default_options
+
+      def httprb_initialize(default_options)
+        @default_options = HTTP::Options.new(default_options)
+        @connection = nil
+        @state = :clean
+      end
+
+      def httprb_perform(req, options)
+        verify_connection!(req.uri)
+
+        @state = :dirty
+        begin
+          @connection ||= HTTP::Connection.new(req, options)
+          unless @connection.failed_proxy_connect?
+            @connection.send_request(req)
+            @connection.read_headers!
+          end
+        rescue HTTP::Error => e
+          options.features.each_value do |feature|
+            feature.on_error(req, e)
+          end
+          raise
+        end
+
+        res = build_response(req, options)
+        @connection.finish_response if req.verb == :head
+        @state = :clean
+        res
+      rescue
+        close
+        raise
+      end
+
+      private
+
+      def verify_connection!(uri)
+        if default_options.persistent? && uri.origin != default_options.persistent
+          raise HTTP::StateError, "Persistence is enabled for #{default_options.persistent}, but we got #{uri.origin}"
+        end
+        return close if @connection && (!@connection.keep_alive? || @connection.expired?)
+        close if @state == :dirty
+      end
+
+      def close
+        @connection&.close
+        @connection = nil
+        @state = :clean
+      end
+
+      def build_response(req, options)
+        res = HTTP::Response.new(
+          status: @connection.status_code,
+          version: @connection.http_version,
+          headers: @connection.headers,
+          proxy_headers: @connection.proxy_response_headers,
+          connection: @connection,
+          encoding: options.encoding,
+          request: req
+        )
+        HTTP::Session::Response.new(res)
+      end
+
+      def wrap_response(res, opts)
+        opts.features.to_a.reverse.to_h.inject(res) do |response, (_name, feature)|
+          response = feature.wrap_response(response)
+          HTTP::Session::Response.new(response)
+        end
+      end
+
+      def build_request(verb, uri, opts = {})
+        opts = @default_options.merge(opts)
+        uri = make_request_uri(uri, opts)
+        headers = make_request_headers(opts)
+        body = make_request_body(opts, headers)
+        req = HTTP::Request.new(
+          verb: verb,
+          uri: uri,
+          uri_normalizer: opts.feature(:normalize_uri)&.normalizer,
+          proxy: opts.proxy,
+          headers: headers,
+          body: body
+        )
+        HTTP::Session::Request.new(req)
+      end
+
+      def wrap_request(req, opts)
+        opts.features.inject(req) do |request, (_name, feature)|
+          request = feature.wrap_request(request)
+          HTTP::Session::Request.new(request)
+        end
+      end
+
+      def make_request_uri(uri, opts)
+        uri = uri.to_s
+        uri = "#{default_options.persistent}#{uri}" if default_options.persistent? && uri !~ HTTP_OR_HTTPS_RE
+        uri = HTTP::URI.parse uri
+        uri.query_values = uri.query_values(Array).to_a.concat(opts.params.to_a) if opts.params && !opts.params.empty?
+        uri.path = "/" if uri.path.empty?
+        uri
+      end
+
+      def make_request_headers(opts)
+        headers = opts.headers
+        headers[HTTP::Headers::CONNECTION] = default_options.persistent? ? HTTP::Connection::KEEP_ALIVE : HTTP::Connection::CLOSE
+        cookies = opts.cookies.values
+        unless cookies.empty?
+          cookies = opts.headers.get(HTTP::Headers::COOKIE).concat(cookies).join("; ")
+          headers[HTTP::Headers::COOKIE] = cookies
+        end
+        headers
+      end
+
+      def make_request_body(opts, headers)
+        if opts.body
+          opts.body
+        elsif opts.form
+          form = make_form_data(opts.form)
+          headers[HTTP::Headers::CONTENT_TYPE] ||= form.content_type
+          form
+        elsif opts.json
+          body = HTTP::MimeType[:json].encode opts.json
+          headers[HTTP::Headers::CONTENT_TYPE] ||= "application/json; charset=#{body.encoding.name.downcase}"
+          body
+        end
+      end
+
+      def make_form_data(form)
+        return form if form.is_a? HTTP::FormData::Multipart
+        return form if form.is_a? HTTP::FormData::Urlencoded
+        HTTP::FormData.create(form)
+      end
+    end
+  end
+end

data/lib/http/session/client.rb

@@ -0,0 +1,157 @@
+class HTTP::Session
+  class Client
+    include HTTP::Session::Client::Perform
+
+    # @param [Hash] default_options
+    # @param [Session] session
+    def initialize(default_options, session)
+      httprb_initialize(default_options)
+      @session = session
+    end
+
+    # @param verb
+    # @param uri
+    # @param [Hash] opts
+    # @return [Response]
+    def request(verb, uri, opts)
+      data = @session.make_http_request_data
+      hist = []
+
+      opts = @default_options.merge(opts)
+      opts = _hs_handle_http_request_options_cookies(opts, data[:cookies])
+      opts = _hs_handle_http_request_options_follow(opts, hist)
+
+      req = build_request(verb, uri, opts)
+      res = perform(req, opts)
+      return res unless opts.follow
+
+      HTTP::Redirector.new(opts.follow).perform(req, res) do |request|
+        request = HTTP::Session::Request.new(request)
+        perform(request, opts)
+      end.tap do |res|
+        res.history = hist
+      end
+    end
+
+    private
+
+    # Make an HTTP request.
+    #
+    # @param [Request] req
+    # @param [HTTP::Options] opts
+    # @return [Response]
+    def perform(req, opts)
+      req = wrap_request(req, opts)
+      wrap_response(_hs_perform(req, opts), opts)
+    end
+
+    # Add session cookie to the request's :cookies.
+    def _hs_handle_http_request_options_cookies(opts, cookies)
+      return opts if cookies.nil?
+      opts.with_cookies(cookies)
+    end
+
+    # Wrap the :on_redirect method in the request's :follow.
+    def _hs_handle_http_request_options_follow(opts, hist)
+      return opts unless opts.follow
+
+      follow = (opts.follow == true) ? {} : opts.follow
+      opts.with_follow(follow.merge(
+        on_redirect: _hs_handle_http_request_options_follow_hijack(follow[:on_redirect], hist)
+      ))
+    end
+
+    # Wrap the :on_redirect method.
+    def _hs_handle_http_request_options_follow_hijack(fn, hist)
+      lambda do |res, req|
+        hist << res
+        fn.call(res, req) if fn.respond_to?(:call)
+      end
+    end
+
+    # Make an HTTP request using cache.
+    def _hs_perform(req, opts)
+      if @session.default_options.cache.enabled?
+        req.cacheable? ? _hs_cache_lookup(req, opts) : _hs_cache_pass(req, opts)
+      else
+        _hs_forward(req, opts)
+      end
+    end
+
+    # Try to serve the response from cache.
+    #
+    #   * When a matching cache entry is found and is fresh, use it as the response
+    #     without forwarding any request to the backend.
+    #   * When a matching cache entry is found but is stale, attempt to validate the
+    #     entry with the backend using conditional GET.
+    #   * When no matching cache entry is found, trigger miss processing.
+    def _hs_cache_lookup(req, opts)
+      entry = @session.cache.read(req)
+      if entry.nil?
+        _hs_cache_fetch(req, opts)
+      elsif entry.response.fresh?(shared: @session.cache.shared?) &&
+          !entry.response.no_cache? &&
+          !req.no_cache?
+        _hs_cache_reuse(req, opts, entry)
+      else
+        _hs_cache_validate(req, opts, entry)
+      end
+    end
+
+    # The cache entry is missing. Forward the request to the backend and determine
+    # whether the response should be stored.
+    def _hs_cache_fetch(req, opts)
+      res = _hs_forward(req, opts)
+      _hs_cache_entry_store(req, res)
+
+      res.headers[HTTP::Session::Cache::Status::HEADER_NAME] = HTTP::Session::Cache::Status::MISS
+      res
+    end
+
+    # The cache entry is fresh, reuse it.
+    def _hs_cache_reuse(req, opts, entry)
+      res = entry.to_response(req)
+      res.headers[HTTP::Headers::AGE] = [(res.now - res.date).to_i, 0].max.to_s
+      res.headers[HTTP::Session::Cache::Status::HEADER_NAME] = HTTP::Session::Cache::Status::HIT
+      res
+    end
+
+    # The cache entry is stale, revalidate it. The original request is used
+    # as a template for a conditional GET request with the backend.
+    def _hs_cache_validate(req, opts, entry)
+      req.headers[HTTP::Headers::IF_MODIFIED_SINCE] = entry.response.last_modified if entry.response.last_modified
+      req.headers[HTTP::Headers::IF_NONE_MATCH] = entry.response.etag if entry.response.etag
+
+      res = _hs_forward(req, opts)
+      if res.status.not_modified?
+        res = entry.to_response(req)
+        res.headers[HTTP::Session::Cache::Status::HEADER_NAME] = HTTP::Session::Cache::Status::REVALIDATED
+        return res
+      end
+
+      _hs_cache_entry_store(req, res)
+      res.headers[HTTP::Session::Cache::Status::HEADER_NAME] = HTTP::Session::Cache::Status::EXPIRED
+      res
+    end
+
+    # The request is not cacheable. So the request is sent to the backend, and the
+    # backend's response is sent to the client, but is not entered into the cache.
+    def _hs_cache_pass(req, opts)
+      res = _hs_forward(req, opts)
+      res.headers[HTTP::Session::Cache::Status::HEADER_NAME] = HTTP::Session::Cache::Status::UNCACHEABLE
+      res
+    end
+
+    # Store the response to cache.
+    def _hs_cache_entry_store(req, res)
+      if res.cacheable?(shared: @session.cache.shared?, req: req)
+        @session.cache.write(req, res)
+      end
+    end
+
+    # Delegate the request to the backend and create the response.
+    def _hs_forward(req, opts)
+      httprb_perform(req, opts)
+    end
+  end
+end