atomic_cache 0.1.0.rc1

data/lib/atomic_cache/concerns/global_lmt_cache_concern.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/object'
+require 'active_support/concern'
+require_relative '../atomic_cache_client'
+require_relative '../default_config'
+
+module AtomicCache
+
+  # this concern provides a single LMT for the whole model
+  module GlobalLMTCacheConcern
+    extend ActiveSupport::Concern
+
+    ATOMIC_CACHE_CONCERN_MUTEX = Mutex.new
+
+    class_methods do
+
+      def AtomicCache
+        init_atomic_cache
+        @atomic_cache
+      end
+
+      def cache_version(version)
+        ATOMIC_CACHE_CONCERN_MUTEX.synchronize do
+          @atomic_cache_version = version
+        end
+      end
+
+      def cache_class(kls)
+        ATOMIC_CACHE_CONCERN_MUTEX.synchronize do
+          @atomic_cache_class = kls
+        end
+      end
+
+      def cache_key_storage(storage)
+        ATOMIC_CACHE_CONCERN_MUTEX.synchronize do
+          @atomic_cache_key_storage = storage
+        end
+      end
+
+      def cache_value_storage(storage)
+        ATOMIC_CACHE_CONCERN_MUTEX.synchronize do
+          @atomic_cache_value_storage = storage
+        end
+      end
+
+      def default_cache_class
+        self.to_s.downcase
+      end
+
+      def cache_keyspace(*ks)
+        init_atomic_cache
+        @default_cache_keyspace.child(ks)
+      end
+
+      def expire_cache(at=Time.now)
+        init_atomic_cache
+        @timestamp_manager.last_modified_time = at
+      end
+
+      def last_modified_time
+        init_atomic_cache
+        @timestamp_manager.last_modified_time
+      end
+
+      private
+
+      def init_atomic_cache
+        return if @atomic_cache.present?
+        ATOMIC_CACHE_CONCERN_MUTEX.synchronize do
+          cache_class = @atomic_cache_class || default_cache_class
+          prefix = [cache_class]
+          prefix.unshift(DefaultConfig.instance.namespace) if DefaultConfig.instance.namespace.present?
+          prefix.push("v#{@atomic_cache_version}") if @atomic_cache_version.present?
+          @default_cache_keyspace = Keyspace.new(namespace: prefix, root: cache_class)
+
+          @timestamp_manager = LastModTimeKeyManager.new(
+            keyspace: @default_cache_keyspace,
+            storage: @atomic_cache_key_storage || DefaultConfig.instance.key_storage,
+            timestamp_formatter: DefaultConfig.instance.timestamp_formatter,
+          )
+
+          @atomic_cache = AtomicCacheClient.new(
+            default_options: DefaultConfig.instance.default_options,
+            logger: DefaultConfig.instance.logger,
+            metrics: DefaultConfig.instance.metrics,
+            timestamp_manager: @timestamp_manager,
+            storage: @atomic_cache_value_storage || DefaultConfig.instance.cache_storage
+          )
+        end
+      end
+    end
+
+    def AtomicCache
+      self.class.AtomicCache
+    end
+
+    def cache_keyspace(ns)
+      self.class.cache_keyspace(ns)
+    end
+
+    def expire_cache(at=Time.now)
+      self.class.expire_cache(ns)
+    end
+
+    def last_modified_time
+      self.class.last_modified_time
+    end
+
+  end
+end

data/lib/atomic_cache/default_config.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require 'singleton'
+
+module AtomicCache
+  class DefaultConfig
+    include Singleton
+
+    CONFIG_MUTEX = Mutex.new
+
+    FLOAT_TIME_FORMATTER = Proc.new { |time| time.to_f }
+    TIMESTAMP_SEC_FORMATTER = Proc.new { |time| time.to_i }
+    TIMESTAMP_MS_FORMATTER = Proc.new { |time| (time.to_f * 1000).to_i }
+    ISO8601_FORMATTER = Proc.new { |time| time.iso8601 }
+    DEFAULT_TIME_FORMATTER = FLOAT_TIME_FORMATTER
+    DEFAULT_SEPARATOR = ':'
+
+    # [required] config
+    attr_accessor :key_storage # storage adapter instance for keys
+    attr_accessor :cache_storage # storage adapter instance for cached values
+
+    # [optional] config
+    attr_accessor :default_options # default options for all fetch requests
+    attr_accessor :namespace
+    attr_accessor :logger
+    attr_accessor :metrics
+    attr_accessor :timestamp_formatter
+    attr_accessor :separator
+
+    def initialize
+      reset
+    end
+
+    # Change all configured values back to default
+    def reset
+      @cache_client = nil
+      @default_options = {}
+      @namespace = nil
+      @logger = nil
+      @metrics = nil
+      @timestamp_formatter = DEFAULT_TIME_FORMATTER
+      @separator = DEFAULT_SEPARATOR
+    end
+
+    # Change all configured values back to default
+    def self.reset
+      self.instance.reset
+    end
+
+    # Quickly configure config singleton instance
+    # @yield mutate config
+    # @yieldparam [AtomicCache::DefaultConfig] config instance
+    def self.configure
+      if block_given?
+        manager = self.instance
+        CONFIG_MUTEX.synchronize do
+          yield(manager)
+        end
+      end
+    end
+  end
+end

data/lib/atomic_cache/key/keyspace.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require 'murmurhash3'
+require 'active_support/concern'
+require 'active_support/core_ext/object'
+require 'active_support/core_ext/hash'
+require_relative '../default_config'
+
+module AtomicCache
+  class Keyspace
+
+    DEFAULT_SEPARATOR = ':'
+    LOCK_VALUE = 1
+    PRIMITIVE_CLASSES = [Numeric, String, Symbol]
+
+    attr_reader :namespace, :root
+
+    # @param namespace [Object, Array<Object>] segment(s) with which to prefix the keyspace
+    # @param root [Object] logical 'root' or primary identifier for this keyspace
+    # @param separator [String] character or string to separate keyspace segments
+    # @param timestamp_formatter [Proc] function to turn Time -> String
+    def initialize(namespace:, root: nil, separator: nil, timestamp_formatter: nil)
+      @namespace = []
+      @namespace = normalize_segments(namespace) if namespace.present?
+      @separator = separator || DefaultConfig.instance.separator
+      @timestamp_formatter = timestamp_formatter || DefaultConfig.instance.timestamp_formatter
+      @root = root || namespace.last
+    end
+
+    # Create a new Keyspace, extending the namespace with the given segments and
+    # retaining this keyspace's root and separator
+    #
+    # @param namespace [Array<Object>] segments to concat onto this keyspace
+    # @return [AtomicCache::Keyspace] child keyspace
+    def child(namespace)
+      throw ArgumentError.new("Prefix must be an Array but was #{namespace.class}") unless namespace.is_a?(Array)
+      joined_namespacees = @namespace.clone.concat(namespace)
+      self.class.new(namespace: joined_namespacees)
+    end
+
+    # Get a string key for this keyspace, optionally suffixed by the given value
+    #
+    # @param suffix [String, Symbol, Numeric] an optional suffix
+    # @return [String] a key
+    def key(suffix=nil)
+      flattened_key(suffix)
+    end
+
+    def last_mod_time_key
+      @last_mod_time_key ||= flattened_key('lmt')
+    end
+
+    def lock_key
+      @lock_key ||= flattened_key('lock')
+    end
+
+    # the key the last_known_key is stored at, thus key key.
+    def last_known_key_key
+      @last_known_key ||= flattened_key('lkk')
+    end
+
+    protected
+
+    def flattened_key(suffix=nil)
+      segments = @namespace
+      segments = @namespace.clone.push(suffix) if suffix.present?
+      segments.join(@separator)
+    end
+
+    def normalize_segments(segments)
+      if segments.is_a? Array
+        segments.map { |seg| expand_segment(seg) }
+      elsif sgs.nil?
+        []
+      else
+        [expand_segment(segments)]
+      end
+    end
+
+    def expand_segment(segment)
+      case segment
+        when Symbol, String, Numeric
+          segment
+        when DateTime, Time
+          @timestamp_formatter.call(segment)
+        else
+          hexhash(segment)
+      end
+    end
+
+    def hexhash(segment)
+      # if the segment is sortable, sort it before hashing so that collections
+      # come out with the same hash
+      segment = segment.sort if segment.respond_to?(:sort)
+      MurmurHash3::V128.str_hash(Marshal.dump(segment)).pack('L*').unpack('H*').first
+    end
+  end
+end

data/lib/atomic_cache/key/last_mod_time_key_manager.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/object'
+require 'active_support/core_ext/hash'
+
+module AtomicCache
+  class LastModTimeKeyManager
+    extend Forwardable
+
+    LOCK_VALUE = 1
+
+    # @param keyspace [AtomicCache::Keyspace] keyspace to store timestamp info at
+    # @param storage [Object] cache storage adapter
+    # @param timestamp_formatter [Proc] function to turn Time -> String
+    def initialize(keyspace: nil, storage: nil, timestamp_formatter: nil)
+      @timestamp_keyspace = keyspace
+      @storage = storage || DefaultConfig.instance.key_storage
+      @timestamp_formatter = timestamp_formatter || DefaultConfig.instance.timestamp_formatter
+
+      raise ArgumentError.new("`storage` required but none given") unless @storage.present?
+      raise ArgumentError.new("`root_keyspace` required but none given") unless @storage.present?
+    end
+
+    # get the key at the given keyspace, suffixed by the current timestamp
+    #
+    # @param keyspace [AtomicCache::Keyspace] keyspace to namespace this key with
+    # @return [String] a timestamped key
+    def current_key(keyspace)
+      keyspace.key(last_modified_time)
+    end
+
+    # get a key at the given keyspace, suffixed by given timestamp
+    #
+    # @param keyspace [AtomicCache::Keyspace] keyspace to namespace this key with
+    # @param timestamp [String, Numeric, Time] timestamp
+    # @return [String] a timestamped key
+    def next_key(keyspace, timestamp)
+      keyspace.key(self.format(timestamp))
+    end
+
+    # promote a key and timestamp after a successful re-generation of a cache keyspace
+    #
+    # @param keyspace [AtomicCache::Keyspace] keyspace to promote within
+    # @param last_known_key [String] a key with a known value to refer other processes to
+    # @param timestamp [String, Numeric, Time] the timestamp with which the last_known_key was updated at
+    def promote(keyspace, last_known_key:, timestamp:)
+      key = keyspace.last_known_key_key
+      @storage.set(key, last_known_key)
+      @storage.set(last_modified_time_key, self.format(timestamp))
+    end
+
+    # prevent other processes from modifying the given keyspace
+    #
+    # @param keyspace [AtomicCache::Keyspace] keyspace to lock
+    # @param ttl [Numeric] the duration in ms to lock (auto expires after duration is up)
+    # @param options [Hash] options to pass to the storage adapter
+    def lock(keyspace, ttl, options=nil)
+      @storage.add(keyspace.lock_key, LOCK_VALUE, ttl, options)
+    end
+
+    # remove existing lock to allow other processes to update keyspace
+    #
+    # @param keyspace [AtomicCache::Keyspace] keyspace to lock
+    def unlock(keyspace)
+      @storage.delete(keyspace.lock_key)
+    end
+
+    def last_known_key(keyspace)
+      @storage.read(keyspace.last_known_key_key)
+    end
+
+    def last_modified_time_key
+      @lmtk ||= @timestamp_keyspace.key('lmt')
+    end
+
+    def last_modified_time
+      @storage.read(last_modified_time_key)
+    end
+
+    def last_modified_time=(timestamp=Time.now)
+      @storage.set(last_modified_time_key, self.format(timestamp))
+    end
+
+    protected
+
+    def format(time)
+      if time.is_a?(Time)
+        @timestamp_formatter.call(time)
+      else
+        time
+      end
+    end
+
+  end
+end

data/lib/atomic_cache/storage/dalli.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+require_relative 'store'
+
+module AtomicCache
+  module Storage
+
+    # A light wrapper over the Dalli client
+    class Dalli < Store
+      extend Forwardable
+
+      ADD_SUCCESS = 'STORED'
+      ADD_UNSUCCESSFUL = 'NOT_STORED'
+      ADD_EXISTS = 'EXISTS'
+
+      def_delegators :@dalli_client, :delete
+
+      def initialize(dalli_client)
+        @dalli_client = dalli_client
+      end
+
+      def add(key, new_value, ttl, user_options=nil)
+        opts = user_options&.clone || {}
+        opts[:raw] = true
+
+        # dalli expects time in seconds
+        # https://github.com/petergoldstein/dalli/blob/b8f4afe165fb3e07294c36fb1c63901b0ed9ce10/lib/dalli/client.rb#L27
+        # TODO: verify this unit is being treated correctly through the system
+        response = @dalli_client.add(key, new_value, ttl, opts)
+        response.start_with?(ADD_SUCCESS)
+      end
+
+      def read(key, user_options=nil)
+        user_options ||= {}
+        @dalli_client.read(key, user_options)
+      end
+
+      def set(key, value, user_options=nil)
+        user_options ||= {}
+        @dalli_client.set(key, value, user_options)
+      end
+
+    end
+  end
+end

data/lib/atomic_cache/storage/instance_memory.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative 'memory'
+
+module AtomicCache
+  module Storage
+
+    # A storage adapter which keeps all values in memory, private to the instance
+    class InstanceMemory < Memory
+
+      def initialize(*args)
+        reset
+        super(*args)
+      end
+
+      def reset
+        @store = {}
+      end
+
+      def store
+        @store
+      end
+
+      def store_op(key, user_options=nil)
+        if !key.present?
+          desc = if key.nil? then 'Nil' else 'Empty' end
+          raise ArgumentError.new("#{desc} key given for storage operation") unless key.present?
+        end
+
+        normalized_key = key.to_sym
+        user_options ||= {}
+        yield(normalized_key, user_options)
+      end
+
+    end
+  end
+end