object-cache 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: b329bb499b49a3b608f4ba5a756e09a246228c28
+  data.tar.gz: e5bf39f2fd0025bd30568d4fe87aaf29eb2e077b
+SHA512:
+  metadata.gz: e14b55bf9cf2fa92ca9d307740ad8d31df097616a8f0642e362b4b1398ac7eef4480646df252e3abfdf154de5f9b06610406426fdcffa61bc32bef2007114a71
+  data.tar.gz: 4ab4b813991e17132477fa97531636d8a04778eeb14ef221a85afbe0503061e85671e6b195f80bca42f6962cf1b60d297c7672a683bc28528273375721b73276

data/.gitignore

@@ -0,0 +1,4 @@
+/.bundle/
+/.wercker/
+/Gemfile.lock
+/pkg/

data/.rubocop.yml

@@ -0,0 +1,10 @@
+AllCops:
+  TargetRubyVersion: 2.3
+  Exclude:
+    - '.wercker/**/*'
+
+Metrics/MethodLength:
+  Max: 15
+
+Metrics/LineLength:
+  Max: 100

data/.wercker.yml

@@ -0,0 +1,7 @@
+box: ruby:2.3
+build:
+  steps:
+  - bundle-install
+  - script:
+    name: tests
+    code: bundle exec rake

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,49 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, and in the interest of
+fostering an open and welcoming community, we pledge to respect all people who
+contribute through reporting issues, posting feature requests, updating
+documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free
+experience for everyone, regardless of level of experience, gender, gender
+identity and expression, sexual orientation, disability, personal appearance,
+body size, race, ethnicity, age, religion, or nationality.
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery
+* Personal attacks
+* Trolling or insulting/derogatory comments
+* Public or private harassment
+* Publishing other's private information, such as physical or electronic
+  addresses, without explicit permission
+* Other unethical or unprofessional conduct
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+By adopting this Code of Conduct, project maintainers commit themselves to
+fairly and consistently applying these principles to every aspect of managing
+this project. Project maintainers who do not follow or enforce the Code of
+Conduct may be permanently removed from the project team.
+
+This code of conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting a project maintainer at jean@blendle.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. Maintainers are
+obligated to maintain confidentiality with regard to the reporter of an
+incident.
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 1.3.0, available at
+[http://contributor-covenant.org/version/1/3/0/][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/3/0/

data/Gemfile

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+source 'https://rubygems.org'
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Blendle
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,162 @@
+# Object::Cache [![wercker status](https://app.wercker.com/status/8f5b16e230784fd4bd75f267d5d62e85/s/master "wercker status")](https://app.wercker.com/project/bykey/8f5b16e230784fd4bd75f267d5d62e85)
+
+Easy caching of Ruby objects, using [Redis](http://redis.io) as a backend store.
+
+* [Installation](#installation)
+* [Quick Start](#quick-start)
+* [Usage](#usage)
+  * [marshaling data](#marshaling-data)
+  * [ttl](#ttl)
+  * [namespaced keys](#namespaced-keys)
+  * [redis replicas](#redis-replicas)
+  * [core extension](#core-extension)
+* [License](#license)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'object-cache'
+```
+
+And then execute:
+
+```shell
+bundle
+```
+
+Or install it yourself as:
+
+```shell
+gem install object-cache
+```
+
+## Quick Start
+
+```ruby
+# require the proper libraries in your project
+require 'redis'
+require 'object/cache'
+
+# set the backend to a new Redis instance
+Cache.backend = Redis.new
+
+# wrap your object in a `Cache.new` block to store the object on first usage,
+# and retrieve it again on subsequent usages
+Cache.new { 'hello world' }
+
+# add the core extension for easier access
+require 'object/cache/core_extension'
+cache { 'hello world' }
+```
+
+## Usage
+
+Using `Object::Cache`, you can cache objects in Ruby that have a heavy cost
+attached to initializing them, and then replay the recorded object on any
+subsequent requests.
+
+For example, database query results can be cached, or HTTP requests to other
+services within your infrastructure.
+
+Caching an object is as easy as wrapping that object in a `Cache.new` block:
+
+```ruby
+Cache.new { 'hello world' }
+```
+
+Here, the object is of type `String`, but it can be any type of object that can
+be marshalled using the Ruby [`Marshal`][marshal] library.
+
+#### marshaling data
+
+You can only marshal _data_, not _code_, so anything that produces code that is
+executed later to return data (like Procs) cannot be cached. You can still wrap
+those in a `Cache.new` block, and the block will return the Proc as expected,
+but no caching will occur, so there's no point in doing so.
+
+#### ttl
+
+By default, a cached object has a `ttl` (time to live) of one week. This means
+that every request after the first request uses the value from the cached
+object. After one week, the cached value becomes stale, and the first request
+after that will again store the (possibly changed) object in the cache store.
+
+You can easily modify the `ttl` using the keyword argument by that same name:
+
+```ruby
+Cache.new(ttl: 60) { 'remember me for 60 seconds!' }
+```
+
+Or, if you want the cached object to never go stale, disable the TTL entirely:
+
+```ruby
+Cache.new(ttl: nil) { 'I am forever in your cache!' }
+Cache.new(ttl: 0) { 'me too!' }
+```
+
+#### namespaced keys
+
+When storing the key/value object into Redis, the key name is based on the file
+name and line number where the cache was initiated. This allows you to cache
+objects without specifying any namespacing yourself.
+
+If however, you are storing an object that changes based on input, you need to
+add a unique namespace to the cache, to make sure the correct object is returned
+from cache:
+
+```ruby
+Cache.new(email) { User.find(email: email) }
+```
+
+In the above case, we use the customer's email to correctly namespace the
+returned object in the cache store. The provided namespace argument is still
+merged together with the file name and line number of the cache request, so you
+can re-use that same `email` namespace in different locations, without worrying
+about any naming collisions.
+
+#### redis replicas
+
+Before, we used the following setup to connect `Object::Cache` to a redis
+backend:
+
+```ruby
+Cache.backend = Redis.new
+```
+
+The Ruby Redis library has primary/replicas support [buit-in using Redis
+Sentinel][sentinel].
+
+If however, you have your own setup, and want the writes and reads to be
+separated between different Redis instances, you can pass in a hash to the
+backend config, with a `primary` and `replicas` key:
+
+```ruby
+Cache.backend = { primary: Redis.new, replicas: [Redis.new, Redis.new] }
+```
+
+The above example obiously only works if the replicas receive the written data
+from the primary instance.
+
+#### core extension
+
+Finally, if you want, you can extend `Object` with a `cache` method, for
+convenient access to the cache object:
+
+```ruby
+require 'object/cache/core_extension'
+
+# these are the same:
+cache('hello', ttl: 60) { 'hello world' }
+Cache.new('hello', ttl: 60) { 'hello world' }
+```
+
+That's it!
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+
+[marshal]: http://ruby-doc.org/core-2.3.0/Marshal.html
+[sentinel]: https://github.com/redis/redis-rb#sentinel-support

data/Rakefile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new do |t|
+  t.options = %w(--display-cop-names --extra-details --display-style-guide)
+end
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.libs << 'lib'
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+task default: %i(test rubocop)

data/lib/object/cache.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require 'digest/sha1'
+require 'object/cache/version'
+
+# Caching of objects in a Redis store
+class Cache
+  DEFAULT_TTL = (7 * 24 * 60 * 60) # 1 week
+
+  class << self
+    attr_accessor :backend
+
+    # new
+    #
+    # Finds the correct value (based on the provided key) in the cache store, or
+    # calls the original code, and stores the result in cache.
+    #
+    # The TTL of the cached content is provided with the optional `ttl` named
+    # argument. If left blank, the `DEFAULT_TTL` ttl value will be used.
+    #
+    # The caching key will be determined by creating a SHA digest of the
+    # original code's file location and line number within that file. This makes
+    # it easier to provide short caching keys like uid's, or ids, and still
+    # receive a unique caching key under which the data is stored.
+    #
+    # The cache key can optionally be left blank. This should **only be done**
+    # if the provided data by the method will never changes based on some form
+    # of input.
+    #
+    # For example: caching an `Item` should _always_ be done by providing a
+    # unique item identifier as the caching key, otherwise the cache will return
+    # the same item every time, even if a different one is stored the second
+    # time.
+    #
+    # good:
+    #
+    #   Cache.new { 'hello world' } # stored object is always the same
+    #   Cache.new(item.id) { item } # stored item is namespaced using its id
+    #
+    # bad:
+    #
+    #   Cache.new { item } # item is only stored once, and then always
+    #                      # retrieved, even if it is a different item
+    #
+    def new(key = nil, ttl: DEFAULT_TTL)
+      return yield unless replica
+
+      key = Digest::SHA1.hexdigest([key, Proc.new.source_location].flatten.join)[0..5]
+
+      if (cached_value = replica.get(key)).nil?
+        yield.tap { |value| update_cache(key, value, ttl: ttl) }
+      else
+        Marshal.load(cached_value)
+      end
+    rescue TypeError
+      # if `TypeError` is raised, the data could not be Marshal dumped. In that
+      # case, delete anything left in the cache store, and get the data without
+      # caching.
+      #
+      delete(key)
+      yield
+    rescue
+      yield
+    end
+
+    def include?(key)
+      replica.exists(key)
+    rescue
+      false
+    end
+
+    def delete(key)
+      return false unless include?(key)
+
+      primary.del(key)
+      true
+    end
+
+    def update_cache(key, value, ttl: DEFAULT_TTL)
+      return unless primary && (value = Marshal.dump(value))
+
+      ttl.to_i.zero? ? primary.set(key, value) : primary.setex(key, ttl.to_i, value)
+    end
+
+    def primary
+      backend.is_a?(Hash) ? backend[:primary] : backend
+    end
+
+    def replicas
+      [backend.is_a?(Hash) ? backend[:replicas] : backend].flatten
+    end
+
+    def replica
+      replicas.sample
+    end
+  end
+end

data/lib/object/cache/core_extension.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# :no-doc:
+class Object
+  def cache(key = nil, **options, &block)
+    Cache.new(key, **options, &block)
+  end
+end

data/lib/object/cache/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class Cache
+  VERSION = '0.0.1'
+end

data/object-cache.gemspec

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+# encoding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'object/cache'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'object-cache'
+  spec.version       = Cache::VERSION
+  spec.authors       = %w(Jean Mertz)
+  spec.email         = %w(jean@mertz.fm)
+
+  spec.summary       = 'Caching of objects, using a Redis store.'
+  spec.description   = 'Easily cache objects in Ruby, using a Redis store backend'
+  spec.homepage      = 'https://github.com/blendle/object-cache'
+  spec.license       = 'MIT'
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.require_paths = %w(lib)
+
+  spec.add_development_dependency 'bundler', '~> 1.12'
+  spec.add_development_dependency 'm', '~> 1.5'
+  spec.add_development_dependency 'minitest', '~> 5.0'
+  spec.add_development_dependency 'mock_redis', '~> 0.16'
+  spec.add_development_dependency 'pry', '~> 0.10'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rubocop', '~> 0.40'
+end

data/test/cache_test.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+$LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
+
+require 'mock_redis'
+require 'object/cache'
+require 'minitest/autorun'
+
+# :no-doc:
+class CacheTest < Minitest::Test
+  def setup
+    Cache.backend = MockRedis.new
+  end
+
+  def redis
+    Cache.primary
+  end
+
+  def key_to_value(key)
+    Marshal.load(redis.get(key))
+  end
+
+  def test_cache_returns_object
+    assert_equal 'hello world', Cache.new { 'hello world' }
+  end
+
+  def test_cache_stores_object
+    Cache.new { 'hello world' }
+    assert redis.keys.one?
+  end
+
+  def test_cache_stores_correct_value
+    assert_equal Cache.new { 'hello world' }, key_to_value(redis.keys.first)
+  end
+
+  def test_does_not_cache_non_marshalable_objects
+    Cache.new { -> { 'hello world' } }
+    assert redis.keys.empty?
+  end
+
+  def test_return_original_value_for_non_marshalable_objects
+    assert_equal 'hello world', Cache.new { -> { 'hello world' } }.call
+  end
+
+  def test_returns_cache_on_same_file_line_without_custom_key
+    Cache.new { 'hello world' } && Cache.new { 'hello universe' }
+    assert_equal 'hello world', key_to_value(redis.keys.first)
+  end
+
+  def test_store_multiple_objects_cached_in_same_file_but_different_lines
+    Cache.new { 'hello world' }
+    Cache.new { 'hello universe' }
+
+    assert_equal 'hello world', key_to_value(redis.keys.first)
+    assert_equal 'hello universe', key_to_value(redis.keys.last)
+  end
+
+  def test_custom_cache_key_on_same_file_and_line
+    Cache.new('hello') { 'world' } && Cache.new('hi') { 'world' }
+    assert_equal 2, redis.keys.count
+  end
+
+  def test_custom_cache_key_on_same_file_but_different_lines
+    Cache.new('hello') { 'world' }
+    Cache.new('hi') { 'world' }
+    assert_equal 2, redis.keys.count
+  end
+
+  def test_cache_without_ttl
+    Cache.new(ttl: nil) { 'hello world' }
+    assert_equal(-1, redis.ttl(redis.keys.first))
+  end
+
+  def test_cache_without_ttl_using_zero
+    Cache.new(ttl: 0) { 'hello world' }
+    assert_equal(-1, redis.ttl(redis.keys.first))
+  end
+
+  def test_cache_default_ttl
+    Cache.new { 'hello world' }
+    assert_equal Cache::DEFAULT_TTL, redis.ttl(redis.keys.first)
+  end
+
+  def test_cache_with_ttl
+    Cache.new(ttl: 60) { 'hello world' }
+    assert_equal 60, redis.ttl(redis.keys.first)
+  end
+
+  def test_core_extension
+    load 'object/cache/core_extension.rb'
+    assert_equal 'hello world', cache { 'hello world' }
+    assert Object.send(:remove_method, :cache)
+  end
+
+  def test_core_extension_options
+    load 'object/cache/core_extension.rb'
+    cache(ttl: 60) { 'hello world' }
+    assert_equal 60, redis.ttl(redis.keys.first)
+    assert Object.send(:remove_method, :cache)
+  end
+
+  def test_backend_with_replicas
+    Cache.backend = { primary: redis, replicas: [redis, redis] }
+
+    Cache.new { 'hello world' } && assert_equal('hello world', Cache.new { 'hello world' })
+  end
+
+  def test_backend_with_primary_without_replicas
+    Cache.backend = { primary: MockRedis.new }
+
+    Cache.new { 'hello world' } && assert_equal('hello world', Cache.new { 'hello world' })
+  end
+
+  def test_backend_with_primary_and_single_replica
+    redis = MockRedis.new
+    Cache.backend = { primary: redis, replicas: redis }
+
+    Cache.new { 'hello world' } && assert_equal('hello world', Cache.new { 'hello world' })
+  end
+
+  def test_backend_with_replicas_not_having_primary_data
+    primary = MockRedis.new
+    replica = MockRedis.new
+    Cache.backend = { primary: primary, replicas: replica }
+
+    Cache.new { 'hello world' } && Cache.new { 'hello world' }
+
+    assert_equal 1, primary.keys.count
+    assert_equal 0, replica.keys.count
+  end
+end

metadata

@@ -0,0 +1,157 @@
+--- !ruby/object:Gem::Specification
+name: object-cache
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Jean
+- Mertz
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-05-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.12'
+- !ruby/object:Gem::Dependency
+  name: m
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: mock_redis
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.16'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.16'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.10'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.40'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.40'
+description: Easily cache objects in Ruby, using a Redis store backend
+email:
+- jean@mertz.fm
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rubocop.yml"
+- ".wercker.yml"
+- CODE_OF_CONDUCT.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/object/cache.rb
+- lib/object/cache/core_extension.rb
+- lib/object/cache/version.rb
+- object-cache.gemspec
+- test/cache_test.rb
+homepage: https://github.com/blendle/object-cache
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.4
+signing_key: 
+specification_version: 4
+summary: Caching of objects, using a Redis store.
+test_files: []
+has_rdoc: