startback 0.19.0 → 0.19.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8d8442d4dcacbab7c562a5656fce452ecb45907458cba4dd88e617ec56007dfd
-  data.tar.gz: c01bfdc67f1dc66cf6e0e4173495b5102623b5a5dce5e9023d616432ecbe042f
+  metadata.gz: a46ae64f74d522af60d8efac5d0ea966587c556a12d791a4817c77a27b4eb74b
+  data.tar.gz: 528fd26764c05ae46e88c4009dcfe801ad8c8fa95b57eb3ae158ae205b26be49
 SHA512:
-  metadata.gz: 02a69c56aa4ca38c959e5879de04045576fa992e281b398a71e08478919ff7a97f6d85e083259d540e4e555d095158c131867d7466ef923eabc8a3924b4d2cb2
-  data.tar.gz: b9aadd2aaf265655d398e112775384da9f52c8a058830cffcbf93f69f2cd13312710fbef91e64c9c5ac20d1f502195627022b405616dd30092ced479d9d117b1
+  metadata.gz: e64ba6da11affe1a7639cd1c5bec8ff9b1088c74eaad3f08f70e7280c95a5af624bcd1bd3d9ca965aec844aaaae3957ada94bcb4ac55ebd0a133b6f0154a99b4
+  data.tar.gz: 405daa018fb688b1f00a2b814881cd7f30e7f43892d91d27ef4fbf0367579c160866674130ee5ac187002f0b36e978c840a9329721f9dd7b36668be1345cfd9e

data/lib/startback/audit/prometheus.rb

@@ -7,7 +7,8 @@ module Startback
     # Prometheus exporter abstraction, that can be registered as an around
     # hook on OperationRunner and as a prometheus client on Context instances.
     #
-    # The exporter uses the ruby client for prometheus to expose metrics regarding Operation runs.
+    # The exporter uses the ruby client for prometheus to expose metrics
+    # regarding Operation runs.
     #
     # The following metrics are exported:
     #

data/lib/startback/caching/entity_cache.rb

@@ -1,3 +1,7 @@
+# For backward compatibility, may be removed in next released
+require_relative 'listeners'
+require_relative 'logger'
+
 module Startback
   module Caching
     #
@@ -22,12 +26,15 @@ module Startback
     # An EntityCache takes an actual store at construction. The object must meet the
     # specification writtern in Store. The 'cache' ruby gem can be used in practice.
     #
-    # Cache hits, outdated and miss are logged in debug, info, and info severity.
-    # The `cache_hit`, `cache_outdated`, `cache_miss` protected methods MAY be
-    # overriden to change that behavior.
+    # This class supports listeners to track cache hits, misses, outdates and
+    # failures. Listeners can be provided at construction via the options, or by
+    # overriding the `default_listeners` method. The default implementation simply
+    # logs.
+    #
+    # By default, this class raises an error if something goes wrong with the cache.
+    # You can disable this by using the `raise_on_cache_fail` option.
     #
     class EntityCache
-      include Support::Robustness
 
       class << self
 
@@ -40,9 +47,22 @@ module Startback
 
       end # class DSL
 
-      def initialize(store, context = nil)
+      DEFAULT_OPTIONS = {
+
+        # Whether a cache fail raises an exception or not
+        raise_on_cache_fail: true,
+
+        # Default listeners to use, if any. When nil is used, `default_listener`
+        # method is used to create them.
+        listeners: nil,
+
+      }
+
+      def initialize(store, context = nil, options = {})
         @store = store
         @context = context
+        @options = DEFAULT_OPTIONS.merge(options)
+        @options[:listeners] ||= default_listeners
       end
       attr_reader :store, :context
 
@@ -66,6 +86,10 @@ module Startback
         load_entity(pkey).tap{|to_cache|
           store.set(cache_key, to_cache, caching_options)
         }
+      rescue => ex
+        cache_fail(pkey, ex)
+        raise if raise_on_cache_fail?
+        load_entity(pkey)
       end
 
       # Invalidates the cache under a given key.
@@ -75,18 +99,33 @@ module Startback
         store.delete(cache_key)
       end
 
+    protected
+
+      def raise_on_cache_fail?
+        @options[:raise_on_cache_fail]
+      end
+
+      def register(listener)
+        @options[:listeners].register(listener)
+        self
+      end
+
     protected
 
       def cache_hit(pkey, cached)
-        log(:debug, self, "cache_hit", context, op_data: pkey)
+        @options[:listeners].cache_hit(self, context, pkey, cached)
       end
 
       def cache_outdated(pkey, cached)
-        log(:info, self, "cache_outdated", context, op_data: pkey)
+        @options[:listeners].cache_outdated(self, context, pkey, cached)
       end
 
       def cache_miss(pkey)
-        log(:info, self, "cache_miss", context, op_data: pkey)
+        @options[:listeners].cache_miss(self, context, pkey)
+      end
+
+      def cache_fail(pkey, ex)
+        @options[:listeners].cache_fail(self, context, pkey, ex)
       end
 
       def default_caching_options
@@ -152,6 +191,12 @@ module Startback
         raise NotImplementedError, "#{self.class.name}#load_entity"
       end
 
+    protected
+
+      def default_listeners
+        Listeners.new << Logger.new
+      end
+
     end # class EntityCache
   end # module Caching
 end # module Startback

data/lib/startback/caching/listeners.rb

@@ -0,0 +1,41 @@
+module Startback
+  module Caching
+    class Listeners
+
+      def initialize
+        @listeners = []
+      end
+
+      def register(listener)
+        @listeners << listener
+        self
+      end
+      alias :<< :register
+
+      def cache_hit(*args, &bl)
+        @listeners.each do |l|
+          l.cache_hit(*args, &bl)
+        end
+      end
+
+      def cache_outdated(*args, &bl)
+        @listeners.each do |l|
+          l.cache_outdated(*args, &bl)
+        end
+      end
+
+      def cache_miss(*args, &bl)
+        @listeners.each do |l|
+          l.cache_miss(*args, &bl)
+        end
+      end
+
+      def cache_fail(*args, &bl)
+        @listeners.each do |l|
+          l.cache_fail(*args, &bl)
+        end
+      end
+
+    end # class Listeners
+  end # module Caching
+end # module Startback

data/lib/startback/caching/logger.rb

@@ -0,0 +1,24 @@
+module Startback
+  module Caching
+    class Logger
+      include Support::Robustness
+
+      def cache_hit(entity_cache, context, pkey, cached)
+        log(:debug, entity_cache, "cache_hit", context, op_data: pkey)
+      end
+
+      def cache_outdated(entity_cache, context, pkey, cached)
+        log(:info, entity_cache, "cache_outdated", context, op_data: pkey)
+      end
+
+      def cache_miss(entity_cache, context, pkey)
+        log(:info, entity_cache, "cache_miss", context, op_data: pkey)
+      end
+
+      def cache_fail(entity_cache, context, pkey, ex)
+        log(:error, entity_cache, "cache_fail", context, op_data: pkey, error: ex)
+      end
+
+    end # class Logger
+  end # module Caching
+end # module Startback

data/lib/startback/caching/prometheus.rb

@@ -0,0 +1,53 @@
+require 'prometheus/client'
+
+module Startback
+  module Caching
+    class Prometheus
+
+      def initialize
+        @cache_hit_counter = cache_counter('hit')
+        @cache_outdated_counter = cache_counter('outdated')
+        @cache_miss_counter = cache_counter('miss')
+        @cache_fail_counter = cache_counter('fail')
+      end
+
+      def cache_hit(entity_cache, *args, &bl)
+        @cache_hit_counter.increment(labels: {
+          entity_cache: entity_cache.class.name,
+        })
+      end
+
+      def cache_outdated(entity_cache, *args, &bl)
+        @cache_outdated_counter.increment(labels: {
+          entity_cache: entity_cache.class.name,
+        })
+      end
+
+      def cache_miss(entity_cache, *args, &bl)
+        @cache_miss_counter.increment(labels: {
+          entity_cache: entity_cache.class.name,
+        })
+      end
+
+      def cache_fail(entity_cache, *args, &bl)
+        @cache_fail_counter.increment(labels: {
+          entity_cache: entity_cache.class.name,
+        })
+      end
+
+    private
+
+      def cache_counter(what)
+        name = "entity_cache_#{what}".to_sym
+        ::Prometheus::Client::Counter.new(
+          name,
+          docstring: "A counter of EntityCache #{what}",
+          labels: [:entity_cache],
+        ).tap do |counter|
+          ::Prometheus::Client.registry.register(counter)
+        end
+      end
+
+    end # class Prometheus
+  end # module Caching
+end # module Startback

data/lib/startback/caching.rb

@@ -0,0 +1,6 @@
+require_relative 'caching/store'
+require_relative 'caching/no_store'
+require_relative 'caching/listeners'
+require_relative 'caching/logger'
+require_relative 'caching/prometheus'
+require_relative 'caching/entity_cache'

data/lib/startback/support/env.rb

@@ -36,6 +36,21 @@ module Startback
       end
       module_function :env
 
+      def staging?
+        ENV['RACK_ENV'] == 'staging'
+      end
+      module_function :staging?
+
+      def production?
+        ENV['RACK_ENV'] =~ /^prod/
+      end
+      module_function :production?
+
+      def development?
+        ENV['RACK_ENV'] =~ /^dev/
+      end
+      module_function :development?
+
     end # module Env
   end # module Support
 end # module Startback

data/lib/startback/support/log_formatter.rb

@@ -49,7 +49,7 @@ module Startback
     private
 
       def auto_pretty_print
-        ENV['RACK_ENV'] == 'development'
+        development?
       end
 
     end # class LogFormatter

data/lib/startback/support/robustness.rb

@@ -43,7 +43,10 @@ module Startback
           @@default_logger ||= begin
             l = ::Logger.new(STDOUT)
             l.formatter = LogFormatter.new
-            l.warn(op: "#{self}", op_data: { msg: "Using default logger to STDOUT" })
+            l.warn(op: "#{self}", op_data: {
+              msg: "Using default logger to STDOUT",
+              caller: caller
+            })
             @@default_logger = l
           end
           @@default_logger

data/lib/startback/version.rb

@@ -2,7 +2,7 @@ module Startback
   module Version
     MAJOR = 0
     MINOR = 19
-    TINY  = 0
+    TINY  = 3
   end
   VERSION = "#{Version::MAJOR}.#{Version::MINOR}.#{Version::TINY}"
 end

data/spec/unit/caching/test_entity_cache.rb

@@ -1,14 +1,13 @@
 require 'spec_helper'
-require 'startback/caching/entity_cache'
-require 'startback/caching/store'
+require 'startback/caching'
 module Startback
   module Caching
     describe EntityCache do
 
       class BaseCache < EntityCache
 
-        def initialize(context = nil)
-          super(Store.new, context)
+        def initialize(options = {})
+          super(Store.new, context, options)
           @called = 0
           @last_key = nil
         end
@@ -76,9 +75,9 @@ module Startback
 
       describe "get" do
 
-        subject{
+        subject do
           cache.get("a key")
-        }
+        end
 
         it 'yields to load_raw_data only once with the short key' do
           expect(subject).to eql("a value")
@@ -87,6 +86,13 @@ module Startback
           expect(cache.last_key).to eql("a key")
         end
 
+        it 'raises when an error occurs' do
+          expect_any_instance_of(Store).to receive(:exist?).and_raise("Cache failed")
+          expect {
+            subject
+          }.to raise_error(/Cache failed/)
+        end
+
       end
 
       describe "primary_key" do
@@ -131,6 +137,48 @@ module Startback
 
       end
 
+      describe 'when disabling error raising' do
+        let(:cache) do
+          BaseCache.new(:raise_on_cache_fail => false)
+        end
+
+        subject do
+          cache.get("a key")
+        end
+
+        it 'yields to load_raw_data only once with the short key' do
+          expect(subject).to eql("a value")
+        end
+
+        it 'does not raise when an error occurs' do
+          expect_any_instance_of(Store).to receive(:exist?).and_raise("Cache failed")
+          expect_any_instance_of(Caching::Logger).to receive(:cache_fail)
+          expect(subject).to eql("a value")
+        end
+      end
+
+      describe "with prometheus listener too" do
+
+        let(:listener) do
+          Caching::Prometheus.new
+        end
+
+        let(:cache) do
+          BaseCache.new.send(:register, listener)
+        end
+
+        before do
+          expect(listener).to receive(:cache_miss)
+          expect(listener).to receive(:cache_hit)
+        end
+
+        it 'yields to load_raw_data only once with the extend key' do
+          expect(cache.get("a key")).to eql("a value")
+          expect(cache.get("a key")).to eql("a value")
+        end
+
+      end
+
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: startback
 version: !ruby/object:Gem::Version
-  version: 0.19.0
+  version: 0.19.3
 platform: ruby
 authors:
 - Bernard Lambeau
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-05-26 00:00:00.000000000 Z
+date: 2023-06-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -150,7 +150,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '2.1'
     - - "<"
       - !ruby/object:Gem::Version
         version: '3.0'
@@ -160,7 +160,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '2.1'
     - - "<"
       - !ruby/object:Gem::Version
         version: '3.0'
@@ -392,8 +392,12 @@ files:
 - lib/startback/audit/span.rb
 - lib/startback/audit/trace_logger.rb
 - lib/startback/audit/tracer.rb
+- lib/startback/caching.rb
 - lib/startback/caching/entity_cache.rb
+- lib/startback/caching/listeners.rb
+- lib/startback/caching/logger.rb
 - lib/startback/caching/no_store.rb
+- lib/startback/caching/prometheus.rb
 - lib/startback/caching/store.rb
 - lib/startback/context.rb
 - lib/startback/context/h_factory.rb