atomic_cache 0.1.0.rc1 → 0.2.1.rc2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: a6de69eb6ef0c02cbe647a36487ee3e5ef051c63
-  data.tar.gz: 140e5dacb3a85b7e67259b9789599f8d73c9d9d0
+SHA256:
+  metadata.gz: 89d82475dddde4fb324d6f2187d47122916dc381883fedcfec2ff00204035e08
+  data.tar.gz: 34d5d998acee788561e3e49019d5983fed4226e4cf88ba7cb0d8fe7cb2bd5a3b
 SHA512:
-  metadata.gz: 604b436749bba999493381af064d0011a6cd5197bc191267873415370e8f8484e523780ca89ad5ed302ab40bf96b784f6df505bb0ffb14a40a72e17377f049ca
-  data.tar.gz: 3abb13a75e2fb3f426ac8ea9907ca7591692f7e8219b3516009522da6f5a044fe75a360a5ac876d68c45c26e8842f6326a1a90d5b38dbd4ac1bff1b3bc23cb75
+  metadata.gz: e19f7c43629d01ebeceba040c818a8ae75f183245e9171d3ab39a3d302388769f263292ae04d39c1dcc01137190181f27f5628b3f091a26808c1767ce85ba24e
+  data.tar.gz: b5d0036456849d3d882227231908da8e885e1e6772f4e0b1a4b121a3690e34acd0f0b4ce5a67816c5fc62b5e053100d8c93980b0e8252f693f8737e42bed60e7

data/README.md

@@ -1,5 +1,6 @@
 # atomic_cache Gem
-[![Build Status](https://travis-ci.org/Ibotta/atomic_cache.svg?branch=master)](https://travis-ci.org/Ibotta/atomic_cache)
+[![Gem Version](https://badge.fury.io/rb/atomic_cache.svg)](https://badge.fury.io/rb/atomic_cache)
+[![Build Status](https://travis-ci.com/Ibotta/atomic_cache.svg?branch=main)](https://travis-ci.com/Ibotta/atomic_cache)
 [![Test Coverage](https://api.codeclimate.com/v1/badges/790faad5866d2a00ca6c/test_coverage)](https://codeclimate.com/github/Ibotta/atomic_cache/test_coverage)
 
 ## User Documentation
@@ -27,7 +28,7 @@ class Foo < ActiveRecord::Base
 
   def active_foos(ids)
     keyspace = cache_keyspace(:activeids, ids)
-    AtomicCache.fetch(keyspace, expires_in: 5.minutes) do
+    atomic_cache.fetch(keyspace, expires_in: 5.minutes) do
       Foo.active.where(id: ids.uniq)
     end
 
@@ -42,8 +43,15 @@ For further details and examples see [Usage & Testing](docs/USAGE.md)
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
-
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/ibotta/atomic_cache
+
+## Releasing
+
+Releases are automatically handled via the Travis CI build. When a version greater than
+the version published on rubygems.org is pushed to the `main` branch, Travis will:
+
+- re-generate the CHANGELOG file
+- tag the release with GitHub
+- release to rubygems.org

data/docs/PROJECT_SETUP.md

@@ -1,7 +1,4 @@
 ## Gem Installation
-
-You will need to ensure you have the correct deploy credentials
-
 Add this line to your application's Gemfile:
 
 ```ruby
@@ -22,18 +19,24 @@ require 'datadog/statsd'
 require 'atomic_cache'
 
 AtomicCache::DefaultConfig.configure do |config|
-  config.logger    = Rails.logger
-  config.metrics   = Datadog::Statsd.new('localhost', 8125, namespace: 'cache.atomic')
-  config.namespace = 'atom'
+  config.logger  = Rails.logger
+  config.metrics = Datadog::Statsd.new('localhost', 8125, namespace: 'cache.atomic')
+
+  # note: these values can also be set in an env file for env-specific settings
+  config.namespace      = 'atom'
+  config.cache_storage  = AtomicCache::Storage::SharedMemory.new
+  config.key_storage    = AtomicCache::Storage::SharedMemory.new
 end
 ```
 
+Note that `Datadog::Statsd` is not _required_.  Adding it, however, will enable metrics support.
+
 #### Required
   * `cache_storage` - Storage adapter for cache (see below)
   * `key_storage` - Storage adapter for key manager (see below)
 
 #### Optional
-  * `default_options` - Default options for every fetch call.  See [options](TODO: LINK).
+  * `default_options` - Default options for every fetch call.  See [fetch options](/Ibotta/atomic_cache/blob/main/docs/USAGE.md#fetch).
   * `logger` - Logger instance.  Used for debug and warn logs. Defaults to nil.
   * `timestamp_formatter` - Proc to format last modified time for storage. Defaults to timestamp (`Time.to_i`)
   * `metrics` - Metrics instance. Defaults to nil.

data/docs/USAGE.md

@@ -11,10 +11,10 @@ expire_cache(Time.now - 100) # an optional time can be given
 The concern makes a `last_modified_time` method available both on the class and on the instance.
 
 ### Fetch
-The concern makes a `AtomicCache` object available both on the class and on the instance.
+The concern makes a `atomic_cache` object available both on the class and on the instance.
 
 ```ruby
-AtomicCache.fetch(options) do
+atomic_cache.fetch(options) do
   # generate block
 end
 ```
@@ -39,7 +39,7 @@ The danger with `quick_retry_ms` is that when enabled it applies a delay to all
 
 `quick_retry_ms` is most effective for caches that are quick to generate but whose values are slow to change.  `quick_retry_ms` is least effective for caches that are slow to update but quick to change.
 
-![quick_retry_ms graph](img/quick_retry_ms_graph.png)
+![quick_retry_ms graph](https://github.com/Ibotta/atomic_cache/raw/ca473f28e179da8c24f638eeeeb48750bc8cbe64/docs/img/quick_retry_graph.png)
 
 #### `max_retries` & `backoff_duration_ms`
 _`max_retries` defaults to 5._

data/lib/atomic_cache/atomic_cache_client.rb

@@ -37,8 +37,7 @@ module AtomicCache
     # @option options [Numeric] :max_retries (5) Max times to rety in waiting case
     # @option options [Numeric] :backoff_duration_ms (50) Duration in ms to wait between retries
     # @yield Generates a new value when cache is expired
-    def fetch(keyspace, options=nil)
-      options ||= {}
+    def fetch(keyspace, options={})
       key = @timestamp_manager.current_key(keyspace)
       tags = ["cache_keyspace:#{keyspace.root}"]
 

data/lib/atomic_cache/concerns/global_lmt_cache_concern.rb

@@ -15,7 +15,7 @@ module AtomicCache
 
     class_methods do
 
-      def AtomicCache
+      def atomic_cache
         init_atomic_cache
         @atomic_cache
       end
@@ -91,8 +91,8 @@ module AtomicCache
       end
     end
 
-    def AtomicCache
-      self.class.AtomicCache
+    def atomic_cache
+      self.class.atomic_cache
     end
 
     def cache_keyspace(ns)
@@ -100,7 +100,7 @@ module AtomicCache
     end
 
     def expire_cache(at=Time.now)
-      self.class.expire_cache(ns)
+      self.class.expire_cache(at)
     end
 
     def last_modified_time

data/lib/atomic_cache/key/keyspace.rb

@@ -20,11 +20,11 @@ module AtomicCache
     # @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)
+      @timestamp_formatter = timestamp_formatter || DefaultConfig.instance.timestamp_formatter
+      @separator = separator || DefaultConfig.instance.separator
       @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
+      @root = root || @namespace.last
     end
 
     # Create a new Keyspace, extending the namespace with the given segments and
@@ -70,7 +70,7 @@ module AtomicCache
     def normalize_segments(segments)
       if segments.is_a? Array
         segments.map { |seg| expand_segment(seg) }
-      elsif sgs.nil?
+      elsif segments.nil?
         []
       else
         [expand_segment(segments)]

data/lib/atomic_cache/key/last_mod_time_key_manager.rb

@@ -54,7 +54,8 @@ module AtomicCache
     # @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)
+    def lock(keyspace, ttl, options={})
+      # returns false if the key already exists
       @storage.add(keyspace.lock_key, LOCK_VALUE, ttl, options)
     end
 

data/lib/atomic_cache/storage/dalli.rb

@@ -20,8 +20,8 @@ module AtomicCache
         @dalli_client = dalli_client
       end
 
-      def add(key, new_value, ttl, user_options=nil)
-        opts = user_options&.clone || {}
+      def add(key, new_value, ttl, user_options={})
+        opts = user_options.clone
         opts[:raw] = true
 
         # dalli expects time in seconds
@@ -31,13 +31,11 @@ module AtomicCache
         response.start_with?(ADD_SUCCESS)
       end
 
-      def read(key, user_options=nil)
-        user_options ||= {}
+      def read(key, user_options={})
         @dalli_client.read(key, user_options)
       end
 
-      def set(key, value, user_options=nil)
-        user_options ||= {}
+      def set(key, value, user_options={})
         @dalli_client.set(key, value, user_options)
       end
 

data/lib/atomic_cache/storage/instance_memory.rb

@@ -21,14 +21,13 @@ module AtomicCache
         @store
       end
 
-      def store_op(key, user_options=nil)
+      def store_op(key, user_options={})
         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
 

data/lib/atomic_cache/storage/memory.rb

@@ -12,35 +12,36 @@ module AtomicCache
       def store; raise NotImplementedError end
 
       # @abstract implement performing an operation on the store
-      def store_op(key, user_options=nil); raise NotImplementedError end
+      def store_op(key, user_options={}); raise NotImplementedError end
 
-      def add(raw_key, new_value, ttl, user_options=nil)
+      def add(raw_key, new_value, ttl, user_options={})
         store_op(raw_key, user_options) do |key, options|
           return false if store.has_key?(key)
-          write(key, new_value, ttl)
+          write(key, new_value, ttl, user_options)
         end
       end
 
-      def read(raw_key, user_options=nil)
+      def read(raw_key, user_options={})
         store_op(raw_key, user_options) do |key, options|
           entry = store[key]
           return nil unless entry.present?
 
-          return entry[:value] if entry[:ttl].nil? or entry[:ttl] == false
+          unmarshaled = unmarshal(entry[:value], user_options)
+          return unmarshaled if entry[:ttl].nil? or entry[:ttl] == false
 
           life = Time.now - entry[:written_at]
           if (life >= entry[:ttl])
             store.delete(key)
             nil
           else
-            entry[:value]
+            unmarshaled
           end
         end
       end
 
-      def set(raw_key, new_value, user_options=nil)
+      def set(raw_key, new_value, user_options={})
         store_op(raw_key, user_options) do |key, options|
-          write(key, new_value, options[:expires_in])
+          write(key, new_value, options[:expires_in], user_options)
         end
       end
 
@@ -51,12 +52,11 @@ module AtomicCache
         end
       end
 
-      def write(key, value, ttl=nil)
-        stored_value = value.to_s
-        stored_value = nil if value.nil?
+      protected
 
+      def write(key, value, ttl=nil, user_options)
         store[key] = {
-          value: stored_value,
+          value: marshal(value, user_options),
           ttl: ttl || false,
           written_at: Time.now
         }

data/lib/atomic_cache/storage/shared_memory.rb

@@ -26,10 +26,8 @@ module AtomicCache
         STORE
       end
 
-      def store_op(key, user_options=nil)
+      def store_op(key, user_options={})
         normalized_key = key.to_sym
-        user_options ||= {}
-
         SEMAPHORE.synchronize do
           yield(normalized_key, user_options)
         end

data/lib/atomic_cache/storage/store.rb

@@ -26,6 +26,18 @@ module AtomicCache
       # returns true if it succeeds; false otherwise
       def delete(key, user_options); raise NotImplementedError end
 
+      protected
+
+      def marshal(value, user_options={})
+        return value if user_options[:raw]
+        Marshal.dump(value)
+      end
+
+      def unmarshal(value, user_options={})
+        return value if user_options[:raw]
+        Marshal.load(value)
+      end
+
     end
   end
 end

data/lib/atomic_cache/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AtomicCache
-  VERSION = "0.1.0.rc1"
+  VERSION = "0.2.1.rc2"
 end

data/spec/atomic_cache/atomic_cache_client_spec.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'AtomicCacheClient' do
+  subject { AtomicCache::AtomicCacheClient.new(storage: cache_storage, timestamp_manager: timestamp_manager) }
+
+  let(:formatter) { Proc.new { |time| time.to_i } }
+  let(:keyspace) { AtomicCache::Keyspace.new(namespace: ['foo', 'bar'], root: 'bar') }
+  let(:key_storage) { AtomicCache::Storage::InstanceMemory.new }
+  let(:cache_storage) { AtomicCache::Storage::InstanceMemory.new }
+
+  let(:timestamp_manager) do
+    AtomicCache::LastModTimeKeyManager.new(
+      keyspace: keyspace,
+      storage: key_storage,
+      timestamp_formatter: formatter,
+    )
+  end
+
+  before(:each) do
+    AtomicCache::DefaultConfig.reset
+  end
+
+  describe '#fetch' do
+
+    context 'when the value is present' do
+      before(:each) do
+        timestamp_manager.last_modified_time = 1420090000
+      end
+
+      it 'returns the cached value' do
+        cache_storage.set(timestamp_manager.current_key(keyspace), 'value')
+        expect(subject.fetch(keyspace)).to eq('value')
+      end
+
+      it 'returns 0 as a cached value' do
+        cache_storage.set(timestamp_manager.current_key(keyspace), '0')
+        expect(subject.fetch(keyspace)).to eq('0')
+      end
+
+      it 'returns empty strings as a cached value' do
+        cache_storage.set(timestamp_manager.current_key(keyspace), '')
+        expect(subject.fetch(keyspace)).to eq('')
+      end
+    end
+
+    context 'when the value is NOT present' do
+      context 'and when a block is given' do
+        context 'and when another thread is NOT generating,' do
+
+          it 'returns the new value' do
+            result = subject.fetch(keyspace) { 'value from block' }
+            expect(result).to eq('value from block')
+          end
+
+          it 'returns the new value when it is an empty string' do
+            result = subject.fetch(keyspace) { '' }
+            expect(result).to eq('')
+          end
+
+          it 'does not store the value if the generator returns nil' do
+            # create a fallback value to make sure we don't use the value from the block
+            key_storage.set(keyspace.last_known_key_key, 'foo_value')
+            cache_storage.set('foo', 'last known value')
+
+            timestamp_manager.promote(keyspace, last_known_key: 'foo', timestamp: Time.now)
+            subject.fetch(keyspace) { nil }
+            expect(subject.fetch(keyspace)).to eq('last known value')
+          end
+
+          it 'unlocks if the generate block returns nil' do
+            subject.fetch(keyspace) { nil }
+            expect(key_storage.store).to_not have_key(:'foo:bar:lock')
+          end
+
+          it 'stores the new value' do
+            subject.fetch(keyspace) { 'value from block' }
+            expect(subject.fetch(keyspace)).to eq('value from block')
+          end
+
+          it 'stores the updated last mod time' do
+            time = Time.local(2018, 1, 1, 15, 30, 0)
+            timestamp_manager.promote(keyspace, timestamp: (time - 10).to_i, last_known_key: 'lkk')
+
+            Timecop.freeze(time) do
+              subject.fetch(keyspace) { 'value from block' }
+              lmt = key_storage.read(timestamp_manager.last_modified_time_key)
+              expect(lmt).to eq(time.to_i)
+            end
+          end
+
+          it 'stores the current key as the last known key' do
+            time = Time.local(2018, 1, 1, 15, 30, 0)
+            timestamp_manager.promote(keyspace, last_known_key: "test:#{(time - 10).to_i}", timestamp: time.to_i)
+
+            Timecop.freeze(time) do
+              subject.fetch(keyspace) { 'value from block' }
+              lkk = key_storage.read(keyspace.last_known_key_key)
+              new_key = timestamp_manager.next_key(keyspace, time)
+              expect(lkk).to eq(new_key)
+            end
+          end
+
+          it 'sets a TTL on the build key when a TTL is not explicitly given' do
+            subject.fetch(keyspace) { 'value from block' }
+            lock_entry = key_storage.store[keyspace.lock_key.to_sym]
+            expect(lock_entry[:ttl]).to eq(30)
+          end
+
+          it 'sets a TTL on the build key when a TTL is given at fetch time' do
+            subject.fetch(keyspace, generate_ttl_ms: 1100) { 'value from block' }
+            lock_entry = key_storage.store[keyspace.lock_key.to_sym]
+            expect(lock_entry[:ttl]).to eq(1.1)
+          end
+
+          it 'sets a TTL on the build key when a value less than a second is given' do
+            subject.fetch(keyspace, generate_ttl_ms: 500) { 'value from block' }
+            lock_entry = key_storage.store[keyspace.lock_key.to_sym]
+            expect(lock_entry[:ttl]).to eq(0.5)
+          end
+
+          it 'sets a TTL on the build key when there is a TTL in the default options' do
+            subject = AtomicCache::AtomicCacheClient.new(
+              storage: cache_storage,
+              timestamp_manager: timestamp_manager,
+              default_options: { generate_ttl_ms: 600 }
+            )
+
+            subject.fetch(keyspace) { 'value from block' }
+            lock_entry = key_storage.store[keyspace.lock_key.to_sym]
+            expect(lock_entry[:ttl]).to eq(0.6)
+          end
+        end
+
+        context 'and when another thread is generating the new value,' do
+          before(:each) do
+            timestamp_manager.lock(keyspace, 100)
+          end
+
+          it 'waits for a short duration to see if the other thread generated the value' do
+            timestamp_manager.promote(keyspace, last_known_key: 'lkk', timestamp: 1420090000)
+            key_storage.set('lkk', 'old:value')
+            new_value = 'value from another thread'
+            allow(cache_storage).to receive(:read)
+              .with(timestamp_manager.current_key(keyspace), anything)
+              .and_return(nil, new_value)
+
+            expect(subject.fetch(keyspace, quick_retry_ms: 5) { 'value' }).to eq(new_value)
+          end
+
+          context 'when the last known value is present' do
+            it 'returns the last known value' do
+              timestamp_manager.promote(keyspace, last_known_key: 'lkk', timestamp: 1420090000)
+              cache_storage.set('lkk', 'old value')
+
+              result = subject.fetch(keyspace, backoff_duration_ms: 5) { 'value from generate' }
+              expect(result).to eq('old value')
+            end
+          end
+
+          context 'when the last known value is NOT present' do
+            it 'waits for another thread to generate the new value' do
+              key_storage.set(timestamp_manager.last_modified_time_key, '1420090000')
+              new_value = 'value from another thread'
+
+              # multiple returned values here are faking what it would look like to
+              # the client if another thread suddenly wrote a value into the cache
+              allow(cache_storage).to receive(:read)
+                .with(timestamp_manager.current_key(keyspace), anything)
+                .and_return(nil, nil, nil, nil, new_value)
+
+              result = subject.fetch(keyspace, backoff_duration_ms: 5) { 'value from generate' }
+              expect(result).to eq(new_value)
+            end
+
+            it 'stops waiting when the max retry count is reached' do
+              timestamp_manager.promote(keyspace, last_known_key: 'asdf', timestamp: 1420090000)
+              result = subject.fetch(keyspace, backoff_duration_ms: 5) { 'value from generate' }
+              expect(result).to eq(nil)
+            end
+
+            it 'deletes the last known key' do
+              key_storage.set(keyspace.last_known_key_key, :oldkey)
+              cache_storage.set(:oldkey, nil)
+              subject.fetch(keyspace, backoff_duration_ms: 5) { 'value from generate' }
+              expect(cache_storage.store).to_not have_key(:oldkey)
+            end
+          end
+        end
+      end
+
+      context 'and when a block is NOT given' do
+        it 'waits for a short duration to see if the other thread generated the value' do
+          timestamp_manager.promote(keyspace, last_known_key: 'asdf', timestamp: 1420090000)
+          new_value = 'value from another thread'
+          allow(cache_storage).to receive(:read)
+            .with(timestamp_manager.current_key(keyspace), anything)
+            .and_return(nil, new_value)
+
+          result = subject.fetch(keyspace, quick_retry_ms: 50)
+          expect(result).to eq(new_value)
+        end
+
+        it 'returns nil if nothing is present' do
+          expect(subject.fetch(keyspace)).to eq(nil)
+        end
+      end
+    end
+
+  end
+
+end