startback 0.5.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 492399cde5cbfe2861575824a32c7788fc16137902d5a4194b3662e5306a5968
-  data.tar.gz: 192d23a34d668bb3ce495c0bb3c724ef58c4e7857bf8e0ed63d5948a76b43f49
+  metadata.gz: 61d4c08ece5a3e956448ef53ca8bfa1a0e4e3b5e9280eb39e705858b9939b708
+  data.tar.gz: 3c481e062a5ab699d8c72ba9625f7528f41b94f075177df284f238d9117cacce
 SHA512:
-  metadata.gz: 54ff69ead9f9b90eccbc9700a46229621cdfe31eb7b887207f6c69c0f755735ae80fc6257ff9ca6e3430d9fc75a2e04fd7b9ea4ecf6744557cb79d418e1ac3b4
-  data.tar.gz: 71de967d2ebee0cd0596b51532d91a1abc1197cd69d1b6db528fcf6bcd00977c484067a83ba266e37e8d807c3c2bba8efc3b67f822b0540eef9fea3c9578fc5b
+  metadata.gz: cc079a6ced8d0cbec9a23b552056d06a4ebc139a5afb54cbc4eadb7c416ca390263e3c3c29c47009e53954db8176305a398fb8ceaddb3696a676bf6d414f0a45
+  data.tar.gz: 6ed71d2a2b742a0634cb3fca8c92e1e0b9a835bbf55f9ada5a9144f40184d01338065ce587d98035e6409a31424ef2a01818e566f5a1cb56e618962f7ac360df

data/lib/startback/audit/trailer.rb

@@ -52,6 +52,7 @@ module Startback
 
         def call(severity, time, progname, msg)
           if msg[:error] && msg[:error].respond_to?(:message, true)
+            msg[:backtrace] = msg[:error].backtrace[0..25] if severity == "FATAL"
             msg[:error] = msg[:error].message
           end
           {

data/lib/startback/caching/entity_cache.rb

@@ -5,16 +5,29 @@ module Startback
     #
     # This class MUST be overriden:
     #
-    # * the `load_raw_data` protected method MUST be implemented.
-    # * the `full_key` protected method MAY be overriden to provide specific caching
-    #   keys, e.g. by using the context.
+    # * the `load_entity` protected method MUST be implemented to load data from
+    #   a primary & context unaware key.
+    #
+    # * the `primary_key` protected method MAY be implemented to convert candidate
+    #   keys (received from ultimate callers) to primary keys. The method is also
+    #   a good place to check and/or log the keys actually used by callers.
+    #
+    # * the `context_free_key` protected method MAY be overriden to provide
+    #   domain unrelated caching keys from primary keys, e.g. by encoding the
+    #   context into the caching key itself, if needed.
+    #
     # * the `valid?` protected method MAY be overriden to check validity of data
-    #   extracted from the cache.
+    #   extracted from the cache and force a refresh even if found.
     #
     # 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.
+    #
     class EntityCache
+      include Support::Robustness
 
       class << self
 
@@ -37,42 +50,106 @@ module Startback
       #
       # If the entity is not in cache, loads it and puts it in cache using
       # the caching options passed as second parameter.
-      def get(short_key, caching_options = default_caching_options)
-        cache_key = encode_key(full_key(short_key))
+      def get(candidate_key, caching_options = default_caching_options)
+        pkey = primary_key(candidate_key)
+        cache_key = encode_key(context_free_key(pkey))
         if store.exist?(cache_key)
           cached = store.get(cache_key)
-          return cached if valid?(cache_key, cached)
+          if valid?(pkey, cached)
+            cache_hit(pkey, cached)
+            return cached
+          else
+            cache_outdated(pkey, cached)
+          end
         end
-        load_raw_data(short_key).tap{|to_cache|
+        cache_miss(pkey)
+        load_entity(pkey).tap{|to_cache|
           store.set(cache_key, to_cache, caching_options)
         }
       end
 
       # Invalidates the cache under a given key.
-      def invalidate(key)
-        store.delete(encode_key(full_key(key)))
+      def invalidate(candidate_key)
+        pkey = primary_key(candidate_key)
+        cache_key = encode_key(context_free_key(pkey))
+        store.delete(cache_key)
       end
 
     protected
 
-      def encode_key(key)
-        JSON.fast_generate(key)
+      def cache_hit(pkey, cached)
+        log(:debug, self, "cache_hit", op_data: pkey)
+      end
+
+      def cache_outdated(pkey, cached)
+        log(:info, self, "cache_outdated", op_data: pkey)
+      end
+
+      def cache_miss(pkey)
+        log(:info, self, "cache_miss", op_data: pkey)
       end
 
       def default_caching_options
         { ttl: self.class.default_ttl }
       end
 
-      def valid?(cache_key, cached)
+      # Converts a candidate key to a primary key, so as to prevent
+      # cache duplicates if callers are allowed to request an entity
+      # through various keys.
+      #
+      # The default implementation returns the candidate key and MAY
+      # be overriden.
+      def primary_key(candidate_key)
+        candidate_key
+      end
+
+      # Encodes a context free key to an actual cache key.
+      #
+      # Default implementation uses JSON.fast_generate but MAY be
+      # overriden.
+      def encode_key(context_free_key)
+        JSON.fast_generate(context_free_key)
+      end
+
+      # Returns whether `cached` entity seems fresh enough to
+      # be returned as a cache hit.
+      #
+      # This method provides a way to check freshness using, e.g.
+      # `updated_at` or `etag` kind of entity fields. The default
+      # implementation returns true and MAY be overriden.
+      def valid?(primary_key, cached)
         true
       end
 
-      def full_key(key)
-        key
+      # Converts a primary_key to a context_free_key, using the
+      # context (instance variable) to encode the context itself
+      # into the actual cache key.
+      #
+      # The default implementation simply returns the primary key
+      # and MAY be overriden.
+      def context_free_key(primary_key)
+        full_key(primary_key)
+      end
+
+      # Deprecated, will be removed in 0.6.0. Use context_free_key
+      # instead.
+      def full_key(primary_key)
+        primary_key
+      end
+
+      # Actually loads the entity using the given primary key, and
+      # possibly the cache context.
+      #
+      # This method MUST be implemented and raises a NotImplementedError
+      # by default.
+      def load_entity(primary_key)
+        load_raw_data(primary_key)
       end
 
-      def load_raw_data(short_key)
-        raise NotImplementedError, "#{self.class.name}#load_raw_data"
+      # Deprecated, will be removed in 0.6.0. Use load_entity
+      # instead.
+      def load_raw_data(*args, &bl)
+        raise NotImplementedError, "#{self.class.name}#load_entity"
       end
 
     end # class EntityCache

data/lib/startback/support/robustness.rb

@@ -24,12 +24,13 @@ module Startback
     #
     # Examples:
     #
-    #     log(op: "hello", op_data: {foo: 12}) => logged as such on STDOUT
-    #     log("A simple message")              => { op: "A simple message" } on STDOUT
-    #     log(Startback, "hello")              => { op: "Startback#hello"  } on STDOUT
-    #     log(Event.new, "hello")              => { op: "Event#hello" }      on STDOUT
-    #     log(self, context)                   => { op: "..." } on context's logger or STDOUT
-    #     log(self, event)                     => { op: "..." } on event context's logger or STDOUT
+    #     log(:info, op: "hello", op_data: {foo: 12})    => logged as such on STDOUT
+    #     log(:info, "A simple message")                 => { op: "A simple message" } on STDOUT
+    #     log(:info, Startback, "hello")                 => { op: "Startback#hello"  } on STDOUT
+    #     log(:info, Event.new, "hello")                 => { op: "Event#hello" }      on STDOUT
+    #     log(:info, Event.new, "hello", "hello world")  => { op: "Event#hello", op_data: { message: "hello world" } } on STDOUT
+    #     log(:info, self, context)                      => { op: "..." } on context's logger or STDOUT
+    #     log(:info, self, event)                        => { op: "..." } on event context's logger or STDOUT
     #     ...
     #
     module Robustness
@@ -41,7 +42,6 @@ module Startback
         def default_logger
           @@default_logger ||= ::Logger.new(STDOUT)
           from = caller.reject{|x| x =~ /lib\/startback/ }.first
-          @@default_logger.debug("Watch out, using default logger from: #{from}")
           @@default_logger
         end
         module_function :default_logger
@@ -56,7 +56,8 @@ module Startback
 
         def parse_args(log_msg, method = nil, context = nil, extra = nil)
           method, context, extra = nil, method, context unless method.is_a?(String)
-          context, extra = nil, context if context.is_a?(Hash) && extra.nil?
+          context, extra = nil, context if context.is_a?(Hash) || context.is_a?(String) && extra.nil?
+          extra = { op_data: { message: extra } } if extra.is_a?(String)
           logger = logger_for(context) || logger_for(log_msg)
           log_msg = if log_msg.is_a?(Hash)
             log_msg.dup
@@ -98,10 +99,9 @@ module Startback
         took = Benchmark.realtime {
           result = bl.call
         }
-        Tools.debug(args, op_took: took)
+        Tools.info(args, op_took: took)
         result
       rescue => ex
-        Tools.error(args, error: ex)
         raise
       end
 
@@ -117,7 +117,7 @@ module Startback
         }
         result
       rescue => ex
-        Tools.error(args, op_took: took, error: ex)
+        Tools.fatal(args, op_took: took, error: ex)
         nil
       end
 

data/lib/startback/version.rb

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

data/lib/startback/web/catch_all.rb

@@ -33,7 +33,6 @@ module Startback
       self.body FATAL_ERROR
 
       self.ensure(true) do |ex|
-        STDERR.puts(ex.message)
         context = env[Context::Middleware::RACK_ENV_KEY]
         begin
           if context && context.respond_to?(:error_handler, true) && context.error_handler

data/spec/unit/caching/test_entity_cache.rb

@@ -16,6 +16,18 @@ module Startback
 
       protected
 
+        def primary_key(ckey)
+          case ckey
+          when Integer then "a key"
+          when String then ckey
+          else
+            raise "Invalid key `#{ckey}`"
+          end
+        end
+
+        # We use the deprecated methods below to test
+        # backward compatibility with 0.5.0.
+
         def full_key(key)
           { k: key }
         end
@@ -77,6 +89,21 @@ module Startback
 
       end
 
+      describe "primary_key" do
+
+        subject{
+          cache.get(12)
+        }
+
+        it 'allows using candidate keys' do
+          expect(subject).to eql("a value")
+          expect(subject).to eql("a value")
+          expect(cache.called).to eql(1)
+          expect(cache.last_key).to eql("a key")
+        end
+
+      end
+
       describe "invalidate" do
 
         it 'strips the key on the store, yielding a cache miss' do

data/spec/unit/support/test_robusteness.rb

@@ -61,7 +61,7 @@ module Startback
               seen += 1
               raise "Test"
             end
-          }.to raise_error
+          }.to raise_error("Test")
           expect(seen).to eql(2)
           expect(the_logger.last_msg.keys).to eql([:op, :op_took, :error])
         end
@@ -116,6 +116,16 @@ module Startback
           expect(logger).to be_a(::Logger)
         end
 
+        it 'works fine with an string, a method name, and a message' do
+          expected = {
+            op: "AClass#method",
+            op_data: { message: "Hello world" }
+          }
+          log_msg, logger = parse_args("AClass", "method", "Hello world")
+          expect(log_msg).to eql(expected)
+          expect(logger).to be_a(::Logger)
+        end
+
         it 'works fine with a string only' do
           expected = {
             op: "a message"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: startback
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.5.1
 platform: ruby
 authors:
 - Bernard Lambeau
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-10-16 00:00:00.000000000 Z
+date: 2019-10-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake