kasket 4.13.0 → 4.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0c1c83230c5c06c292c4dd62d839372d06a54a763ed7dfd0ea5ed339fb57913a
-  data.tar.gz: 96df87b7c7ee9f8f19e593b3bc3bcbad257d928e0cdc4e0b3f5b22afed00b9c6
+  metadata.gz: a6e7fba4b86593d0f6df819b8e4af5417db71843ca84f6aa713688fad70af03d
+  data.tar.gz: d0b55338667baf18f1f85b74eb6063e1c2c216fb66bcc6f66c8f0c72a8233b58
 SHA512:
-  metadata.gz: 1ced9df5e050870ed7446bcf1b2e469fa2954ce1e7afcd67b799b14bb25a7323690242ca5ebb097c8d7df7f5c0c70317a72f292c202bebcc189b7afb64e905d1
-  data.tar.gz: aef1d32b14c4d6c3526b2b9093fec72f2c1998c04bebcf40861a30a1226234e4a70976168e605358fb452ed9152e49a7d69564c2fd7583541056c66cbe7fc8f0
+  metadata.gz: 258485dd05909a3741841bac6ef9c1fbf41ac37c8978f9efa2284cf0caa3a05dbc38ba76c7f74b8ee033ff6106ddbbcd9a0b86943323e08e4e2dd8d95ee86a99
+  data.tar.gz: bf59e003102eef756e49977f99441e4f0930c0032bce7dc183f47e27b2e0887f5d682bdb1b34cd5e3892136e9ebf21d18dbe9ad5c685d3daaf8271b2d5c4c2a1

data/README.md

@@ -48,6 +48,19 @@ semantics instead. In this mode, the model will be updated in the cache as well
 Kasket.setup(write_through: true)
 ```
 
+#### Events Callback
+
+You can configure a callable object to listen to events. This can be useful to emit metrics and observe Kasket's behaviour.
+
+```ruby
+Kasket.setup(events_callback: -> (event, ar_klass) do
+  MyMetrics.increase_some_counter("kasket.#{event}", tags: ["table:#{ar_klass.table_name}"])
+end)
+```
+
+The following events are emitted:
+* `"cache_hit"`, when Kasket has found some record's data in the cache, which can be returned.
+
 ## Configuring caching of your models
 
 You can configure Kasket for any ActiveRecord model, and subclasses will automatically inherit the caching

data/lib/kasket/events.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Kasket
+  # Interface to the internal instrumentation event.
+  module Events
+    class << self
+      # Invokes the configured events callback, if provided.
+      #
+      # The callback behaves like a listener, and receives the same arguments
+      # that are passed to this `report` method.
+      #
+      # @param [String] event the type of event being instrumented.
+      # @param [class] ar_klass the ActiveRecord::Base subclass that the event
+      #   refers to.
+      #
+      # @return [nil]
+      #
+      def report(event, ar_klass)
+        return unless fn
+
+        fn.call(event, ar_klass)
+        nil
+      end
+
+      private
+
+      def fn
+        return @fn if defined?(@fn)
+
+        @fn = Kasket::CONFIGURATION[:events_callback]
+      end
+    end
+  end
+end

data/lib/kasket/read_mixin.rb

@@ -36,8 +36,15 @@ module Kasket
             result_set = if value.is_a?(TrueClass)
               find_by_sql_without_kasket(sql, binds, *restargs, **kwargs, &blk)
             elsif value.is_a?(Array)
+              # The data from the Kasket cache is a list of keys to other Kasket entries.
+              # This usually happens when we're trying to load a collection association,
+              # e.g. a list of comments using their post_id in the query.
+              # Do not report a cache hit yet, and defer it until we've verified that at
+              # least one of the retrieved keys is actually in the cache.
               filter_pending_records(find_by_sql_with_kasket_on_id_array(value))
             else
+              # Direct cache hit for the key.
+              Events.report("cache_hit", self)
               filter_pending_records(Array.wrap(value).collect { |record| instantiate(record.dup, &blk) })
             end
 
@@ -60,6 +67,9 @@ module Kasket
       key_attributes_map = Kasket.cache.read_multi(*keys)
 
       found_keys, missing_keys = keys.partition {|k| key_attributes_map[k] }
+      # Only report a cache hit if at least some keys were found in the cache.
+      Events.report("cache_hit", self) if found_keys.any?
+
       found_keys.each {|k| key_attributes_map[k] = instantiate(key_attributes_map[k].dup, &blk) }
       key_attributes_map.merge!(missing_records_from_db(missing_keys))
 

data/lib/kasket/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 module Kasket
-  VERSION = '4.13.0'
+  VERSION = '4.14.0'
   class Version
     MAJOR = Kasket::VERSION.split('.')[0]
     MINOR = Kasket::VERSION.split('.')[1]

data/lib/kasket.rb

@@ -14,21 +14,35 @@ module Kasket
   autoload :Visitor,                'kasket/visitor'
   autoload :SelectManagerMixin,     'kasket/select_manager_mixin'
   autoload :RelationMixin,          'kasket/relation_mixin'
+  autoload :Events,                 'kasket/events'
 
   CONFIGURATION = { # rubocop:disable Style/MutableConstant
     max_collection_size: 100,
     write_through: false,
-    default_expires_in: nil
+    default_expires_in: nil,
+    events_callback: nil,
   }
 
   module_function
 
+  # Configure Kasket.
+  #
+  # @param [Hash] options the configuration options for Kasket.
+  # @option options [Integer] :max_collection_size max size limit for a cacheable
+  #   collection of records.
+  # @option options [Boolean] :write_through
+  # @option options [Integer, nil] :default_expires_in the cache TTL.
+  # @option options [#call] :events_callback a callable object used to instrument
+  #   Kasket operations. It is invoked with two arguments: the name of the event,
+  #   as a String, and the Klass of the ActiveRecord model the event is about.
+  #
   def setup(options = {})
     return if ActiveRecord::Base.respond_to?(:has_kasket)
 
     CONFIGURATION[:max_collection_size] = options[:max_collection_size] if options[:max_collection_size]
     CONFIGURATION[:write_through]       = options[:write_through]       if options[:write_through]
     CONFIGURATION[:default_expires_in]  = options[:default_expires_in]  if options[:default_expires_in]
+    CONFIGURATION[:events_callback]     = options[:events_callback]     if options[:events_callback]
 
     ActiveRecord::Base.extend(Kasket::ConfigurationMixin)
     ActiveRecord::Relation.include(Kasket::RelationMixin)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kasket
 version: !ruby/object:Gem::Version
-  version: 4.13.0
+  version: 4.14.0
 platform: ruby
 authors:
 - Mick Staugaard
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-04-21 00:00:00.000000000 Z
+date: 2024-01-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -42,6 +42,7 @@ files:
 - lib/kasket.rb
 - lib/kasket/configuration_mixin.rb
 - lib/kasket/dirty_mixin.rb
+- lib/kasket/events.rb
 - lib/kasket/query_parser.rb
 - lib/kasket/read_mixin.rb
 - lib/kasket/relation_mixin.rb
@@ -68,7 +69,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3.1
+rubygems_version: 3.5.3
 signing_key: 
 specification_version: 4
 summary: A write back caching layer on active record