httparty-cache 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ff16750de74919a4428091908be24f05775deded7885af69960c38265ee1679b
+  data.tar.gz: 12ccabffc3f4d24dfeef6327a3ac5649560b275051840826f31c3482e2075b2d
+SHA512:
+  metadata.gz: f2d9b8a53ed1ef26b0ab22dc64108ea69cecfc76c13505b4d184e2df0823ddb78857ccf815152bc1adf202a94a0b1a3010af4c7714012842f675ee3428c6109e
+  data.tar.gz: 5b33148ca9f3d650218f66ca59964c04c91e87dfa730f8cd997aaad87fe36d19decdf1833463512ecc3f457cbe1bb8b5fbe7c5f4527325fe686cde1718b335e7

data/README.md

@@ -0,0 +1,82 @@
+# HTTParty cache
+
+Implements [HTTP caching][] support to [HTTParty][] requests by following
+servers' headers such as [Cache-Control][], specifically the `max-age`,
+`must-revalidate` and`no-cache` directives, [Vary][], [ETag][],
+[Last-Modified][] to perform response [validation][].
+
+[HTTP caching]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Caching
+[Cache-Control]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/cache-control
+[Vary]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/vary
+[ETag]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/etag
+[Last-Modified]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/last-modified
+[validation]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Caching#validation
+[HTTParty]: https://github.com/jnunemaker/httparty
+
+## Use
+
+Add this gem to your `Gemfile` and install dependencies.
+
+Configure your `HTTParty` client to use a cache store and perform
+caching:
+
+```ruby
+require 'httparty'
+require 'httparty/cache'
+
+class Client
+  include HTTParty
+  include HTTParty::Cache
+
+  caching true
+  cache_store :memory
+end
+```
+
+### Cache stores
+
+#### Redis
+
+If you want to use Redis as a cache store:
+
+1. Add `redis-client` and optionally `hiredis-client` gems to your
+   `Gemfile`.
+
+2. Set the environment variable `REDIS_URL` with the server URL, or
+   initialize the cache store with a custom URL.
+
+   ```ruby
+   require 'httparty'
+   require 'httparty/cache'
+   require 'httparty/cache/store/redis'
+
+   class Client
+     include HTTParty
+     include HTTParty::Cache
+
+     caching true
+     cache_store :redis
+     # or
+     cache_store HTTParty::Cache::Store::Redis.new(redis_url: 'redis://redis.provider:6379')
+   end
+   ```
+
+#### Jekyll
+
+If you want to use Jekyll as a cache store, for instance while writing
+a plugin using HTTParty:
+
+```ruby
+require 'httparty'
+require 'httparty/cache'
+require 'httparty/cache/store/jekyll'
+
+class Client
+    include HTTParty
+    include HTTParty::Cache
+
+    caching true
+    cache_store :jekyll
+    # or
+    cache_store HTTParty::Cache::Store::Jekyll.new(name: 'My::Jekyll::Cache')
+end

data/lib/httparty/cache/request.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module HTTParty
+  module Cache
+    # Extends HTTParty::Request with caching methods
+    #
+    # @see {https://developer.mozilla.org/en-US/docs/Web/HTTP/Caching}
+    module Request
+      CACHE_REVALIDATION_HEADERS = {
+        'ETag' => 'If-None-Match',
+        'Last-Modified' => 'If-Modified-Since'
+      }.freeze
+
+      # Calculates a cache key from URI + query string + headers
+      #
+      # @return [String]
+      def cache_key
+        @cache_key ||= "request:#{uri}##{URI.encode_www_form(options[:headers] || {})}"
+      end
+
+      def validate
+        super
+
+        raise ArgumentError, 'Caching is enabled but store was not provided' if caching? && cache_store.nil?
+      end
+
+      # Patch HTTParty::Request#perform to provide caching for GET
+      # requests
+      #
+      # @return [HTTParty::Response]
+      def perform(&block)
+        return super(&block) unless caching? && http_method == Net::HTTP::Get
+
+        if cached?
+          handle_revalidation
+        else
+          super(&block).tap do |response|
+            # Point current request to cached response
+            cache_store.set(response.cache_key, response)
+            cache_store.set(cache_key, response.cache_key)
+          end
+        end
+      end
+
+      # When the request is performed for the first time or has been
+      # evicted from cache or is corrupted
+      #
+      # @return [Bool]
+      def cached?
+        cache_store.key?(cache_key) &&
+          cache_store.key?(cache_store.get(cache_key)) &&
+          cache_store.get(cache_store.get(cache_key)).is_a?(HTTParty::Response)
+      end
+
+      def caching?
+        !!options[:caching]
+      end
+
+      private
+
+      # Revalidates request
+      #
+      # @return [HTTParty::Response]
+      def handle_revalidation
+        cached_response = cache_store.get(cache_store.get(cache_key))
+
+        if cached_response.revalidate? || cached_response.stale?
+          self.http_method = Net::HTTP::Head
+          options[:cached_response] = cached_response
+
+          add_cache_revalidation_headers
+
+          response = perform
+
+          if response.not_modified?
+            cached_response.headers['date'] = response.headers['date']
+            response = cached_response
+          else
+            self.http_method = Net::HTTP::Get
+            # Remove from cache so we can perform the request, otherwise
+            # we produce an infinite loop
+            cache_store.delete(cache_key)
+            response = perform
+          end
+
+          cache_store.set(response.cache_key, response)
+          response
+        else
+          cached_response
+        end
+      end
+
+      # Just a shortcut
+      def cache_store
+        options[:cache_store]
+      end
+
+      # Adds revalidation headers unless they're already present
+      #
+      # @return [nil]
+      def add_cache_revalidation_headers
+        options[:headers] ||= {}
+
+        CACHE_REVALIDATION_HEADERS.each_pair do |original_header, revalidation_header|
+          next if (value = options[:cached_response].headers[original_header]).nil?
+
+          options[:headers][revalidation_header] ||= value
+        end
+      end
+    end
+  end
+end
+
+# Patch HTTParty::Request
+HTTParty::Request.class_eval do
+  prepend HTTParty::Cache::Request
+end

data/lib/httparty/cache/response.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module HTTParty
+  module Cache
+    # Extends HTTParty::Response with caching methods
+    #
+    # @see {https://developer.mozilla.org/en-US/docs/Web/HTTP/Caching}
+    module Response
+      # Detects if response is cached
+      def cached?
+        code == 304
+      end
+
+      # Parses Cache-Control headers
+      #
+      # @see {https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/cache-control}
+      # @return [Hash]
+      def cache_control
+        @cache_control ||= headers['Cache-Control'].to_s.downcase.split(',').map(&:strip).map do |c|
+          k, v = c.split('=', 2).map(&:strip)
+
+          [k.tr('-', '_').to_sym, (v ? Integer(v) : true)]
+        end.to_h
+      end
+
+      # Returns the request date
+      #
+      # @return [Time]
+      def date
+        Time.parse(headers['date'])
+      rescue TypeError, ArgumentError
+        raise HTTParty::ResponseError, response
+      end
+
+      # Returns the current age of the request in seconds
+      #
+      # @return [Integer]
+      def age
+        (Time.now - date).to_i
+      rescue HTTParty::ResponseError
+        0
+      end
+
+      # The response is stale when it has been cached for more than the
+      # allowed max age
+      #
+      # @return [Bool]
+      def stale?
+        !cache_control[:max_age].nil? && age > cache_control[:max_age]
+      end
+
+      # Detects if the response must be revalidated even if still fresh.
+      #
+      # @see {https://developer.mozilla.org/en-US/docs/Web/HTTP/Caching#force_revalidation}
+      # @return [Bool]
+      def revalidate?
+        !!(cache_control[:no_cache] || (cache_control[:max_age]&.zero? && cache_control[:must_revalidate]))
+      end
+
+      # Returns the request headers that vary responses
+      #
+      # @return [Hash]
+      def vary
+        @vary ||= request.options[:headers].to_h.slice(*headers['Vary'].to_s.split(',').map(&:strip).sort)
+      end
+
+      # Generates a cache key
+      #
+      # @return [String]
+      def cache_key
+        @cache_key ||= "response:#{request.uri}##{URI.encode_www_form vary}"
+      end
+    end
+  end
+end
+
+# Patch HTTParty::Response
+HTTParty::Response.include HTTParty::Cache::Response

data/lib/httparty/cache/store/abstract.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module HTTParty
+  module Cache
+    module Store
+      # Cache store
+      class Abstract
+        # @return [Hash]
+        attr_reader :options
+
+        # @param :key [String]
+        # @return [Response,nil]
+        def get(key)
+          raise NotImplementedError
+        end
+
+        # @param :key [String]
+        # @param :response [Response]
+        # @return [Response]
+        def set(key, response)
+          raise NotImplementedError
+        end
+
+        # @param :key [String]
+        # @return nil
+        def delete(key)
+          raise NotImplementedError
+        end
+
+        # @param :key [String]
+        # @yield
+        def getset(key, &block)
+          raise NotImplementedError
+        end
+
+        # @param :key [String]
+        # @return [Boolean]
+        def key?(key)
+          raise NotImplementedError
+        end
+
+        def clear
+          raise NotImplementedError
+        end
+
+        def marshal_dump
+          [
+            self.class.name,
+            options || {}
+          ]
+        end
+
+        def marshal_load(array)
+          Object.const_get(array.first).new(**array.last)
+        end
+      end
+    end
+  end
+end

data/lib/httparty/cache/store/jekyll.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative 'abstract'
+require 'jekyll/cache'
+
+module HTTParty
+  module Cache
+    module Store
+      class Jekyll < Abstract
+        extend Forwardable
+
+        def_delegators :@store, :key?, :delete, :clear, :getset
+
+        # @return [Hash]
+        attr_reader :options
+
+        # @param :name [String]
+        def initialize(name: self.class.name)
+          @options = {}
+          @options[:name] = name
+          @store = ::Jekyll::Cache.new(name)
+        end
+
+        def set(key, response)
+          @store[key] = response
+          response
+        end
+
+        def get(key)
+          @store[key]
+        rescue RuntimeError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/httparty/cache/store/memory.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative 'abstract'
+
+module HTTParty
+  module Cache
+    module Store
+      class Memory < Abstract
+        extend Forwardable
+
+        attr_reader :store
+
+        def_delegator :@store, :[], :get
+        def_delegator :@store, :[]=, :set
+
+        def_delegators :@store, :key?, :delete
+
+        def initialize(**)
+          clear
+        end
+
+        def getset(key)
+          store[key] ||= yield
+        end
+
+        def clear
+          @store = {}
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/httparty/cache/store/redis.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require_relative 'abstract'
+require 'redis-client'
+
+begin
+  require 'hiredis-client'
+  RedisClient.default_driver = :hiredis
+rescue LoadError
+end
+
+module HTTParty
+  module Cache
+    module Store
+      class Redis < Abstract
+        # A Marshaled `nil` value
+        NIL = "\x04\b0"
+
+        # @return [Hash]
+        attr_reader :options
+
+        # @param :redis_url [String]
+        def initialize(redis_url: nil)
+          @options = {}
+          @options[:redis_url] = redis_url || ENV['REDIS_URL']
+          @config = RedisClient.config(url: @options[:redis_url])
+          @redis = @config.new_pool(size: 2)
+          @redis.call('PING')
+        end
+
+        # Retrieves a key
+        #
+        # @param :key [String]
+        # @return [Response,nil]
+        def get(key)
+          Marshal.load(redis('GET', key) || NIL)
+        end
+
+        # Stores a Marshaled value indexed by a key.
+        #
+        # @param :key [String]
+        # @param :response [Response]
+        # @return [Response]
+        def set(key, response)
+          redis('SET', key, Marshal.dump(response))
+          response
+        end
+
+        # Returns a key or set its value to a block result
+        #
+        # @param :key [String]
+        # @return [Response,nil]
+        def getset(key)
+          return get(key) if key?(key)
+
+          set(key, yield)
+        end
+
+        # Removes a key from Redis
+        #
+        # @param :key [String]
+        # @return [nil]
+        def delete(key)
+          redis('DEL', key)
+          nil
+        end
+
+        # Discovers if a key exists
+        #
+        # @param :key [String]
+        # @return [Boolean]
+        def key?(key)
+          redis('EXISTS', key).positive?
+        end
+
+        def clear
+          redis('FLUSHALL', 'SYNC')
+          nil
+        end
+
+        private
+
+        # Execs Redis commands and collects stats
+        def redis(*args)
+          @redis.call(*args)
+        end
+      end
+    end
+  end
+end

data/lib/httparty/cache/store.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module HTTParty
+  module Cache
+    module Store
+    end
+  end
+end

data/lib/httparty/cache.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module HTTParty
+  # HTTParty plugin to manage cache
+  module Cache
+    def self.included(base)
+      base.extend ClassMethods
+
+      require_relative 'cache/response'
+      require_relative 'cache/request'
+    end
+
+    module ClassMethods
+      # This is both a setter and a getter...
+      #
+      # @param :cache_store [Symbol,HTTParty::Cache::Store::Abstract]
+      # @return [HTTParty::Cache::Store::Abstract]
+      def cache_store(cache_store = nil)
+        case cache_store
+        when NilClass
+          return default_options[:cache_store]
+        when Symbol
+          require_relative "cache/store/#{cache_store}"
+
+          class_name = cache_store.to_s.split('_').map(&:capitalize).join
+          cache_store = Object.const_get("HTTParty::Cache::Store::#{class_name}").new
+        end
+
+        default_options[:cache_store] = cache_store
+      end
+
+      # Toggle caching
+      #
+      # @param :caching [Bool]
+      # @return [Bool]
+      def caching(caching)
+        default_options[:caching] = caching
+      end
+
+      # Sets cache_control
+      def cache_control(cache_control)
+        default_options[:cache_control] = cache_control
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,259 @@
+--- !ruby/object:Gem::Specification
+name: httparty-cache
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- f
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-01-31 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.18'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.18'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: factory_bot
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.6'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.6.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.6'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.6.0
+- !ruby/object:Gem::Dependency
+  name: rspec-tap-formatters
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: hiredis-client
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.14.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.14.0
+- !ruby/object:Gem::Dependency
+  name: redis-client
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.14.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.14.0
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: timecop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: jekyll
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.24'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.24.3
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.24'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.24.3
+description: A cache manager for HTTParty
+email:
+- f@sutty.nl
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+files:
+- README.md
+- lib/httparty/cache.rb
+- lib/httparty/cache/request.rb
+- lib/httparty/cache/response.rb
+- lib/httparty/cache/store.rb
+- lib/httparty/cache/store/abstract.rb
+- lib/httparty/cache/store/jekyll.rb
+- lib/httparty/cache/store/memory.rb
+- lib/httparty/cache/store/redis.rb
+homepage: https://0xacab.org/sutty/httparty-cache
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://0xacab.org/sutty/httparty-cache/issues
+  homepage_uri: https://0xacab.org/sutty/httparty-cache
+  source_code_uri: https://0xacab.org/sutty/httparty-cache
+  changelog_uri: https://0xacab.org/sutty/httparty-cache/-/blob/master/CHANGELOG.md
+  documentation_uri: https://rubydoc.info/gems/httparty-cache
+post_install_message:
+rdoc_options:
+- "--title"
+- httparty-cache - HTTParty cache
+- "--main"
+- README.md
+- "--line-numbers"
+- "--inline-source"
+- "--quiet"
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.26
+signing_key:
+specification_version: 4
+summary: HTTParty cache
+test_files: []