active_cached_resource 0.0.1.pre

data/lib/active_cached_resource/caching.rb

@@ -0,0 +1,176 @@
+module ActiveCachedResource
+  module Caching
+    GLOBAL_PREFIX = "acr"
+    RELOAD_PARAM = :_acr_reload
+
+    extend ActiveSupport::Concern
+
+    included do
+      class << self
+        alias_method :find_without_cache, :find
+        alias_method :find, :find_with_cache
+      end
+    end
+
+    module ClassMethods
+      def find_with_cache(*orig_args)
+        args = orig_args.deep_dup # Avoid mutating original arguments
+        options = extract_options(*args)
+
+        should_reload = options.delete(:reload) || !cached_resource.enabled
+
+        # When bypassing cache, include the reload option as a query parameter for collection requests.
+        # Hacky but this way ActiveResource::Collection#request_resources! can access it
+        if should_reload && args.first == :all
+          options[:params] = {} if options[:params].blank?
+          options[:params][RELOAD_PARAM] = should_reload
+          args << options
+        end
+
+        if args.first == :all
+          # Let ActiveResource::Collection handle the caching so that lazy loading is more effective
+          return find_via_reload(*args)
+        end
+
+        should_reload ? find_via_reload(*args) : find_via_cache(*args)
+      end
+
+      # Clear the cache.
+      def clear
+        cached_resource.cache.clear("#{cache_key_prefix}/")
+      end
+
+      private
+
+      def cache_read(*)
+        key = cache_key(*)
+        json_string = nil
+        begin
+          json_string = cached_resource.cache.read(key)
+        rescue => e
+          cached_resource.logger.error("[KEY:#{key}] Failed to read from cache: #{e.message} #{e.backtrace.join(" | ")}")
+          json_string = nil
+        end
+
+        return nil if json_string.nil?
+
+        cached_resource.logger.debug("[KEY:#{key}] Cache hit")
+        json_to_object(json_string)
+      end
+
+      def cache_write(object, *)
+        cache_options = {expires_in: cached_resource.ttl}
+        cache_value = object_to_json(object, *)
+        key = cache_key(*)
+
+        begin
+          cached_resource.cache.write(key, cache_value, cache_options)
+          true
+        rescue => e
+          cached_resource.logger.error("[KEY:#{key}] Failed to write to cache: #{e.message} #{e.backtrace.join(" | ")}")
+          false
+        end
+      end
+
+      def find_via_cache(*)
+        cache_read(*) || find_via_reload(*)
+      end
+
+      def find_via_reload(*)
+        object = find_without_cache(*)
+        return object unless should_cache?(object)
+
+        cache_write(object, *)
+        object
+      end
+
+      # Determines if the given object should be cached.
+      #
+      # @param object [Object, ActiveResource::Collection] The object to check for caching eligibility.
+      # @return [Boolean] Returns true if the object should be cached, false otherwise.
+      def should_cache?(object)
+        return false unless cached_resource.enabled
+
+        # Calling `present?` on the `collection_parser`, an instance or descendent of
+        # `ActiveResource::Collection` will trigger a request.
+        # Checking if `requested?` first, will prevent an unnecessary network request when calling `present?`.
+        case object
+        when ActiveResource::Collection
+          object.requested? && object.present?
+        else
+          object.present?
+        end
+      end
+
+      def cache_key(*args)
+        "#{name_key}/#{args.join("/")}".downcase.delete(" ")
+      end
+
+      def name_key
+        # `cache_key_prefix` is separated from key parts with a dash to easily distinguish the prefix
+        "#{cache_key_prefix}-" + name.parameterize.tr("-", "/")
+      end
+
+      def cache_key_prefix
+        prefix = cached_resource.cache_key_prefix
+
+        if prefix.respond_to?(:call)
+          result = prefix.call
+          if !result.is_a?(String) || result.empty?
+            raise ArgumentError, "cache_key_prefix must return a non-empty String"
+          end
+          "#{GLOBAL_PREFIX}/#{result}"
+        else
+          "#{GLOBAL_PREFIX}/#{prefix}"
+        end
+      end
+
+      def json_to_object(json_string)
+        object = ActiveSupport::JSON.decode(json_string)
+        resource = object["resource"]
+
+        case resource
+        when Array
+          resource.map do |attrs|
+            new(attrs["object"], attrs["persistence"]).tap do |r|
+              r.prefix_options = object["prefix_options"]
+            end
+          end
+        else
+          new(resource["object"], resource["persistence"]).tap do |r|
+            r.prefix_options = object["prefix_options"]
+          end
+        end
+      end
+
+      def object_to_json(object, *)
+        options = extract_options(*)
+        params = options.fetch(:params, {})
+        prefix_options, query_options = split_options(params)
+        json_object = if object.is_a? Enumerable
+          {
+            resource: object.map { |o| {object: o, persistence: o.persisted?} },
+            prefix_options: prefix_options,
+            path_params: params,
+            query_params: query_options
+          }
+        else
+          {
+            resource: {object: object, persistence: object.persisted?},
+            prefix_options: prefix_options
+          }
+        end
+        ActiveSupport::JSON.encode(json_object)
+      end
+
+      # Extract options without mutating the original arguments.
+      def extract_options(*args)
+        if (last = args.last) && last.try(:extractable_options?)
+          last
+        else
+          {}
+        end
+      end
+    end
+  end
+end

data/lib/active_cached_resource/caching_strategies/active_support_cache.rb

@@ -0,0 +1,31 @@
+require_relative "base"
+
+module ActiveCachedResource
+  module CachingStrategies
+    class ActiveSupportCache < Base
+      def initialize(cache_store)
+        super()
+        @cache_store = cache_store
+      end
+
+      protected
+
+      def read_raw(key)
+        @cache_store.read(key)
+      end
+
+      def write_raw(key, compressed_value, options)
+        @cache_store.write(key, compressed_value, options)
+      end
+
+      def clear_raw(pattern)
+        if @cache_store.respond_to?(:delete_matched)
+          @cache_store.delete_matched("#{pattern}*")
+          true
+        else
+          false
+        end
+      end
+    end
+  end
+end

data/lib/active_cached_resource/caching_strategies/base.rb

@@ -0,0 +1,114 @@
+require "msgpack"
+module ActiveCachedResource
+  module CachingStrategies
+    class Base
+      # Reads the value associated with the given key from the cache.
+      #
+      # @param key [String, Symbol] the key to read from the cache.
+      #
+      # @return [Object, nil] the decompressed value associated with the key, or nil if the key is not found.
+      def read(key)
+        raise ArgumentError, "key must be a String or Symbol" unless key.is_a?(String) || key.is_a?(Symbol)
+        raw_value = read_raw(hash_key(key))
+        raw_value && decompress(raw_value)
+      end
+
+      # Writes an object to the cache with the specified key and options.
+      #
+      # @param key [String, Symbol] The key used to store the object in the cache.
+      # @param value [String] The value to be stored in the cache.
+      # @param options [Hash] Options for the cache write operation. Must include `:expires_in`.
+      # @option options [Integer] :expires_in The expiration time in seconds for the cached object. (required)
+      #
+      # @raise [ArgumentError] If the `:expires_in` option is missing.
+      #
+      # @return [Boolean] `true` if the object was successfully written to the cache, `false` otherwise.
+      def write(key, value, options)
+        raise ArgumentError, "`expires_in` option is required" unless options[:expires_in]
+
+        write_raw(hash_key(key), compress(value), options)
+      end
+
+      # Clears the cache based on the given pattern.
+      #
+      # @param pattern [String] the pattern to match cache keys that need to be cleared.
+      #
+      # @return [Boolean] `true` if the cache was successfully cleared, `false` otherwise.
+      def clear(pattern)
+        clear_raw(pattern)
+      end
+
+      protected
+
+      # Reads the value associated with the given key from the cache.
+      #
+      # @param key [Object] the key to read from the cache.
+      #
+      # @note This method must be implemented by the subclass.
+      #
+      # @return [Object, nil] the decompressed value associated with the key, or nil if the key is not found.
+      def read_raw(key)
+        raise NotImplementedError, "#{self.class} must implement `read_raw`"
+      end
+
+      # Writes an object to the cache with the specified key and options.
+      #
+      # @param key [String, Symbol] The key used to store the object in the cache.
+      # @param value [String] The value to be stored in the cache.
+      # @param options [Hash] Options for the cache write operation. Must include `:expires_in`.
+      # @option options [Integer] :expires_in The expiration time in seconds for the cached object. (required)
+      #
+      # @note This method must be implemented by the subclass.
+      #
+      # @return [Boolean] `true` if the object was successfully written to the cache, `false` otherwise.
+      def write_raw(key, value, options)
+        raise NotImplementedError, "#{self.class} must implement `write_raw`"
+      end
+
+      # Clears cache entry for the given pattern.
+      #
+      # @param pattern [String, nil] The pattern representing the cache entry to be cleared.
+      #
+      # @note This method must be implemented by the subclass.
+      #
+      # @return [Boolean] `true` if the cache was successfully cleared, `false` otherwise.
+      def clear_raw(pattern)
+        raise NotImplementedError, "#{self.class} must implement `clear_raw`"
+      end
+
+      private
+
+      # Generates a hashed key for caching purposes.
+      #
+      # The method splits the provided key into a prefix and the remaining part,
+      # then combines the prefix with a SHA256 hash of the remaining part.
+      # The resulting key is prefixed with a global prefix defined in the
+      # ActiveCachedResource::Caching module.
+      #
+      # @example Hashing a key
+      #  hash_key("prefix-key") #=> "acr/prefix/Digest::SHA256.hexdigest(key)"
+      #
+      # @param key [String] the original key to be hashed. It is expected to have a prefix and the key separated by a dash.
+      # @return [String] the generated hashed key with the global prefix and the prefix from the original key.
+      def hash_key(key)
+        # Prefix of keys are expected to be the first part of key separated by a dash.
+        prefix, k = key.split("-", 2)
+        if prefix.nil? || k.nil?
+          raise ArgumentError, "Key must have a prefix and a key separated by a dash"
+        end
+
+        "#{prefix}/" + Digest::SHA256.hexdigest(k)
+      end
+
+      def compress(value)
+        MessagePack.pack(value)
+      end
+
+      def decompress(value)
+        MessagePack.unpack(value)
+      rescue MessagePack::UnpackError
+        nil
+      end
+    end
+  end
+end

data/lib/active_cached_resource/caching_strategies/sql_cache.rb

@@ -0,0 +1,32 @@
+require_relative "base"
+
+module ActiveCachedResource
+  module CachingStrategies
+    class SQLCache < Base
+      def initialize(model, options = {})
+        super()
+        @model = model
+        @batch_clear_size = options.fetch(:batch_clear_size, 1000)
+      end
+
+      protected
+
+      def read_raw(key)
+        record = @model.where(key: key).where(@model.arel_table[:expires_at].gt(Time.current)).first
+        record&.value
+      end
+
+      def write_raw(key, value, options = {})
+        expires_at = Time.current + options.fetch(:expires_in)
+
+        @model.create({key: key, value: value, expires_at: expires_at})
+      end
+
+      def clear_raw(pattern)
+        @model.where(@model.arel_table[:key].matches("#{pattern}%")).in_batches(of: @batch_clear_size) do |batch|
+          batch.delete_all
+        end
+      end
+    end
+  end
+end

data/lib/active_cached_resource/configuration.rb

@@ -0,0 +1,50 @@
+require "ostruct"
+require_relative "logger"
+require_relative "caching_strategies/sql_cache"
+require_relative "caching_strategies/active_support_cache"
+require_relative "caching_strategies/base"
+
+module ActiveCachedResource
+  class Configuration < OpenStruct
+    CACHING_STRATEGIES = {
+      active_record: ActiveCachedResource::CachingStrategies::SQLCache,
+      active_support: ActiveCachedResource::CachingStrategies::ActiveSupportCache
+    }
+
+    OPTIONS = %i[cache_key_prefix logger enabled ttl]
+
+    def initialize(model, options = {})
+      super(
+        {
+          cache: determine_cache_strategy(options[:cache_store], options[:cache_strategy]),
+          cache_key_prefix: model.name.underscore,
+          logger: ActiveCachedResource::Logger.new(model.name),
+          enabled: true,
+          ttl: 86400
+        }.merge(options.slice(*OPTIONS))
+      )
+    end
+
+    def on!
+      self.enabled = true
+    end
+
+    def off!
+      self.enabled = false
+    end
+
+    private
+
+    def determine_cache_strategy(cache_store, cache_strategy)
+      if cache_store.is_a?(CachingStrategies::Base)
+        cache_store
+      elsif cache_strategy
+        CACHING_STRATEGIES.fetch(cache_strategy).new(cache_store)
+      else
+        raise ArgumentError, "cache_store must be a CachingStrategies::Base or cache_strategy must be provided"
+      end
+    rescue KeyError
+      raise ArgumentError, "Invalid cache strategy: #{cache_strategy}"
+    end
+  end
+end

data/lib/active_cached_resource/logger.rb

@@ -0,0 +1,22 @@
+require "logger"
+
+module ActiveCachedResource
+  class Logger < ::Logger
+    COLORS = {
+      debug: "\e[36m",   # Blue
+      info: "\e[0m",     # Default
+      warn: "\e[33m",    # Yellow
+      error: "\e[31m",   # Red
+      fatal: "\e[31m",   # Red
+      reset: "\e[0m"     # Reset
+    }
+
+    def initialize(model_name)
+      super($stdout)
+      @model_name = model_name
+      self.formatter = proc do |severity, datetime, _progname, msg|
+        "#{COLORS[severity.downcase.to_sym]}#{datetime} -- #{severity} [CACHE][ACR][#{model_name}] #{msg}#{COLORS[:reset]}\n"
+      end
+    end
+  end
+end

data/lib/active_cached_resource/model.rb

@@ -0,0 +1,33 @@
+require "active_support/concern"
+
+require_relative "caching"
+require_relative "configuration"
+
+module ActiveCachedResource
+  module Model
+    extend ActiveSupport::Concern
+
+    included do
+      class << self
+        attr_accessor :cached_resource
+
+        def cached_resource(options = {})
+          @cached_resource || setup_cached_resource!(options)
+        end
+
+        def setup_cached_resource!(options)
+          @cached_resource = ActiveCachedResource::Configuration.new(self, options)
+          include ActiveCachedResource::Caching
+          @cached_resource
+        end
+      end
+    end
+
+    module ClassMethods
+      def inherited(child)
+        child.cached_resource = cached_resource if defined?(@cached_resource)
+        super
+      end
+    end
+  end
+end

data/lib/active_cached_resource/version.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module ActiveCachedResource
+  module VERSION
+    MAJOR = 0
+    MINOR = 0
+    TINY = 1
+    PRE = "pre"
+
+    STRING = [MAJOR, MINOR, TINY, PRE].compact.join(".")
+  end
+end

data/lib/active_cached_resource.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require_relative "activeresource/lib/activeresource"
+
+require_relative "active_cached_resource/model"
+require_relative "active_cached_resource/version"
+
+module ActiveCachedResource
+end
+
+module ActiveResource
+  class Base
+    include ActiveCachedResource::Model
+  end
+
+  class Collection
+    private
+
+    # Monkey patch ActiveResource::Collection to handle caching
+    # @see lib/activeresource/lib/active_resource/collection.rb
+    def request_resources!
+      return @elements if requested?
+
+      # MONKEY PATCH
+      # Delete the reload param from query params.
+      # This is drilled down via `params` option to determine if the collection should be reloaded
+      should_reload = query_params.delete(ActiveCachedResource::Caching::RELOAD_PARAM)
+      if !should_reload
+        from_cache = resource_class.send(:cache_read, from, path_params, query_params, prefix_options)
+        @elements = from_cache
+        return @elements if @elements
+      end
+      # MONKEY PATCH
+
+      response =
+        case from
+        when Symbol
+          resource_class.get(from, path_params)
+        when String
+          path = "#{from}#{query_string(query_params)}"
+          resource_class.format.decode(resource_class.connection.get(path, resource_class.headers).body)
+        else
+          path = resource_class.collection_path(prefix_options, query_params)
+          resource_class.format.decode(resource_class.connection.get(path, resource_class.headers).body)
+        end
+
+      # Update the elements
+      parse_response(response)
+      @elements.map! { |e| resource_class.instantiate_record(e, prefix_options) }
+
+      # MONKEY PATCH
+      # Write cache
+      resource_class.send(:cache_write, @elements, from, path_params, query_params, prefix_options)
+      @elements
+      # MONKEY PATCH
+    rescue ActiveResource::ResourceNotFound
+      # Swallowing ResourceNotFound exceptions and return nothing - as per ActiveRecord.
+      # Needs to be empty array as Array methods are delegated
+      []
+    ensure
+      @requested = true
+    end
+  end
+end

data/lib/activeresource/.gitignore

@@ -0,0 +1,15 @@
+# Don't put *.swp, *.bak, etc here; those belong in a global ~/.gitignore.
+# Check out http://help.github.com/ignore-files/ for how to set that up.
+
+debug.log
+.Gemfile
+/.bundle
+/.ruby-version
+*.lock
+/pkg
+/dist
+/doc/rdoc
+/*/doc
+/*/test/tmp
+/RDOC_MAIN.rdoc
+.rubocop-http*