hitnmiss 2.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 16113a952ba4f6e13da3988202b5293f7b29883e
+  data.tar.gz: e47681d3d3de77dc028ace05d8ca89c6c44d4cc0
+SHA512:
+  metadata.gz: 063cac92539361cd38cbf1cf6defd69d83ab9406c5e0f65e3639b7ad708f3ecee452cd6b2313383c6e0658baaaec4cf71ffc9eeddd79d61ec2fa65c0d4cb2828
+  data.tar.gz: f2495525eb2431776aaf631766e61d17f0ff712a7e98b9e9ad71c216eedeb8df4f542a76c14ccb24b203af5b8d3bbd702782fc1ee0e843e0a65630570e011303

data/.codeclimate.yml

@@ -0,0 +1,9 @@
+---
+engines:
+  fixme:
+    enabled: true
+  rubcop:
+    enabled: true
+ratings:
+  paths:
+  - "lib/**/*"

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - 2.2.3
+before_install: gem install bundler -v 1.11.2

data/CHANGELOG.md

@@ -0,0 +1,69 @@
+# ChangeLog
+
+The following are lists of the notable changes included with each release.
+This is intended to help keep people informed about notable changes between
+versions, as well as provide a rough history.
+
+#### Next Release
+
+#### v2.1.0
+
+* Changed: Documentation for open sourcing
+
+#### v2.0.0
+
+* Added: `BackgroundRefreshRepository` module
+* Changed: Extract cache management into separate module
+* Added: fingerprint, last\_modified, and updated\_at
+* Changed: driver interface to receive a `Hitnmiss::Entity`
+* Fixed: Correct typo in UnregisteredDriver
+* Changed: Extract key generation concerns into separate module
+* Changed: Extract `Fetcher` interface into separate module
+
+#### v1.0.0
+
+* Changed version to 1.0 since the api is stable
+
+#### v0.4.0
+
+* Changed `InMemoryDriver` to return `Hitnmiss::Driver::Hit` and
+  `Hitnmiss::Driver::Miss` instances.
+* Changed driver interface to require `<#driver instance>.get` method to return a
+  `Hitnmiss::Driver::Hit` instance or a `Hitnmiss::Driver::Miss` instance
+* Added `Hitnmiss::Driver::Miss` class
+* Added `Hitnmiss::Driver::Hit` class
+* Changed private methods `get`, `get_all` to `fetch` & `fetch_all`
+* Changed public API method `fetch(*args)` to `get(*args)`
+
+#### v0.3.0
+
+* Changed class style interface to object style interface
+* Fixed `InMemoryDriver#all` to return values not hash of value & expiration
+* Added return values to Public API Documentation examples
+
+#### v0.2.0
+
+* Changed `Repository.prime_cache` to `Repository.prime`
+* Added `Repository.prime_all` to prime entire repository
+* Changed `Repository.perform` to `Repository.get`
+* Added `Repository.get_all` for `Repository.prime_all`
+* Added `Repository.all` to get all cached values
+* Added `Repository.delete` to delete a cached value
+* Added `Repository.clear` to clear all cached values
+* Added `Driver#all` interface to get all cached values
+* Added `Driver#delete` interface to delete a cached value
+* Added `Driver#clear` interface to clear all cached values
+* Changed `InMemoryDriver` to implement `#all`, `#delete`, and `#clear`
+
+#### v0.1.2
+
+* Fixed fetching cached boolean `false` value
+
+#### v0.1.1
+
+* Changed the InMemoryDriver to be threadsafe
+
+#### v0.1.0
+
+* Added driver registry to centrally manage instantiated drivers
+* Added initial Minimum Viable Product version of the library

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 oss@acorns.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/CONTRIBUTING.md

@@ -0,0 +1,56 @@
+# Where should I start?
+
+We recommend first starting to learn about Hitnmiss by reading the
+[README](https://github.com/Acornsgrow/hitnmiss/blob/master/README.md). Beyond
+that you can explore the sections below to identify the path that best fits you.
+**Note:** This project follows a contribution [code of
+conduct](https://github.com/Acornsgrow/hitnmiss/blob/master/CODE_OF_CONDUCT.md).
+
+## How can I help?
+
+There are a number of ways you can help.
+
+- Report Bugs
+- Add Feature Requests
+- Add/Update Documentation
+- Triage Bugs
+- Code Contributions
+
+### Report Bugs
+
+As a user a relatively easy way to contribute is to report bugs that you run
+into. Generally, this should be done via our
+[ISSUES](https://github.com/Acornsgrow/hitnmiss/issues) page. However, if it is
+a security issue please send an e-mail directly to one of the core authors found
+in the
+[gemspec](https://github.com/Acornsgrow/hitnmiss/blob/master/hitnmiss.gemspec#L10)
+rather than creating a public issue for it. This will give us some time to
+review it and resolve it before people can abuse the security flaw.
+
+### Add Feature Requests
+
+One simple way to get involved after starting to use the project is to
+contribute by adding feature requests for things that you see as gaps for the
+project. This can be done by creating an issue or our
+[ISSUES](https://github.com/Acornsgrow/hitnmiss/issues) page.
+
+### Add/Update Documentation
+
+You can also contribute by correcting, updating, or adding additional
+documentation. This can be done by making a pull request for documentation in
+any of our top level markdown files.
+
+### Triage Bugs
+
+Triaging bugs is also very important. This is the practice of the reviewing
+[ISSUES](https://github.com/Acornsgrow/hitnmiss/issues), making sure that the
+submitter provided necessary information to review the bugs, and classify them
+appropriately.
+
+### Code Contributions
+
+The most involved type of contribution you can make is to actually submit code
+to implement features, fix bugs, etc. This is done by submitting a pull request.
+See
+[DEVELOPING](https://github.com/Acornsgrow/hitnmiss/blob/master/DEVELOPMENT.md)
+for further details on getting started with a code contribution.

data/DEVELOPMENT.md

@@ -0,0 +1,7 @@
+# Development
+
+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`.

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in hitnmiss.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Acorns Grow Inc.
+
+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,397 @@
+[![Build Status](https://travis-ci.com/Acornsgrow/hitnmiss.svg?token=GGEgqzL4zt7sa3zVgspU&branch=master)](https://travis-ci.com/Acornsgrow/hitnmiss)
+[![Code Climate](https://codeclimate.com/repos/567a3c30bd3f3b63510017dd/badges/e979a32e79ec12d35896/gpa.svg)](https://codeclimate.com/repos/567a3c30bd3f3b63510017dd/feed)
+[![Test Coverage](https://codeclimate.com/repos/567a3c30bd3f3b63510017dd/badges/e979a32e79ec12d35896/coverage.svg)](https://codeclimate.com/repos/567a3c30bd3f3b63510017dd/coverage)
+[![Issue Count](https://codeclimate.com/repos/567a3c30bd3f3b63510017dd/badges/e979a32e79ec12d35896/issue_count.svg)](https://codeclimate.com/repos/567a3c30bd3f3b63510017dd/feed)
+
+# Hitnmiss
+
+Hitnmiss is a Ruby gem that provides support for using the Repository
+pattern for read-through, write-behind caching in a thread-safe way. It
+is built heavily around using POROs (Plain Old Ruby Objects). This means
+it is intended to be used with all kinds of Ruby applications from plain
+Ruby command line tools, to framework (Rails, Sinatra, Rack, Hanami,
+etc.) based web apps, etc.
+
+Having defined repositories for accessing your caches aids in a number of ways.
+First, it centralizes cache key generation.  Secondly, it centralizes &
+standardizes access to the cache rather than having code spread across your app
+duplicating key generation and access. Third, it provides clean separation
+between the cache persistence layer and the business representation.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'hitnmiss'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install hitnmiss
+
+## Define/Mixin a Repository
+
+Before you can use Hitnmiss to manage cache you first need to define a
+cache repository. This is done by defining a class for your repository
+and mixing the appropriate repository module in using `include`.
+
+Below, are explanations of the **Standard Repository** and the **Background
+Refresh Repository** so that you can decide which one fits your needs as well as
+learn how to use them.
+
+### Standard Repository
+
+The standard repository module, `Hitnmiss::Repository`, fits the most common
+caching use case, the "Expiration Model". The "Expiration Model" is a caching
+model where a value gets cached with an associated expiration and when that
+expiration is reached that value is no longer cached. This affects the app
+behavior by having it pay the caching cost when it tries to get a value and it
+has expired. The following is an example of creating a `MostRecentPrice` cache
+repository for the "Expiration Model".
+
+```ruby
+class MostRecentPrice
+  include Hitnmiss::Repository
+
+  default_expiration 134 # expiration in seconds from when value cached
+end
+```
+
+More often than not your caching use case will have a static/known
+expiration that you want to use for all values that get cached. This is handled
+for you by setting the `default_expiration` as seen in the example above.
+**Note:** Hitnmiss also supports being able to have different expirations for
+each cached value. You can learn more about this in the "Set Cache Source based
+Expiration" section.
+
+### Background Refresh Repository
+
+Sometimes you don't have an expiration value and don't want cached values to
+disappear. In these scenarios you want something to update the cache for you
+based on some defined interval. When you use the
+`Hitnmiss::BackgroundRefreshRepository` module and set the `refresh_interval`
+as seen below, it prepares your repository to handle this scenario. This changes
+the behavior where the app never experiences the caching cost as it is
+continually managed for the app in the background based on the
+`refresh_interval`.
+
+```ruby
+class MostRecentPrice
+  include Hitnmiss::BackgroundRefreshRepository
+
+  refresh_interval 60*5 # refresh interval in seconds
+end
+```
+
+Once you have defined your Background Refresh Repository in order to get the
+background process to update your cache you have to kick it off using the
+`background_refresh(*args, swallow_exceptions: [])` method as seen in the
+example below. The optional keyword argument `swallow_exceptions` defaults to
+`[]`. If enabled it will prevent the specified exceptions, raised in the
+`fetch(*args)` or `stale?(*args)` methods you defined, from killing the
+background thread, and prevent the exceptions from making their way up to the
+application. This is useful in scenarios where you want it to absorb say timeout
+exceptions, etc. and continue trucking along. **Note:** Any other exceptions not
+covered by the exceptions listed in the `swallow_exceptions` array will still be
+raised up into the application.
+
+```ruby
+repository = MostRecentPrice.new
+repository.background_refresh(store_id)
+```
+
+This model also has the added benefit that the priming of the cache in the
+background refresh process is non-blocking. This means if you use this model the
+consumer will not experience the priming of the cache like they would with the
+Standard Repository's Expiration Model.
+
+#### Staleness Checking
+
+The Background Refresh Repository model introduces a new concept, Staleness
+Checking. Staleness is checked during the background refresh process. The way it
+works is if the cache is identified to be stale, then it primes the cache in the
+background, if the cache is identified to NOT be stale, then it sleeps for
+another `refresh_interval`.
+
+The stale checker, `stale?(*args)`, defaults to an always stale value of `true`.
+This causes the background refresh process to prime the cache every
+`refresh_interval`.
+
+If you want your cache implementation to be smarter and say validate a
+fingerprint or last modified value against the source, you can do it simply by
+overwriting the `stale?(*args)` method with your own staleness checking logic.
+The following is an example of this.
+
+```ruby
+class MostRecentPrice
+  include Hitnmiss::BackgroundRefreshRepository
+
+  refresh_interval 60*5 # refresh interval in seconds
+
+  def initialize
+    @client = HTTPClient.new
+  end
+
+  def stale?(*args)
+    hit_or_miss = get_from_cache(*args)
+    if hit_or_miss.is_a?(Hitnmiss::Driver::Miss)
+      return true
+    elsif hit_or_miss.is_a?(Hitnmiss::Driver::Hit)
+      url = "https://someresource.example.com/#{args[0]}/#{args[1]}/digest.json"
+      res = @client.head(url)
+      fingerprint = res.header['ETag'].first
+      return false if fingerprint == hit_or_miss.fingerprint
+      return true
+    else
+      raise Hitnmiss::Repository::UnsupportedDriverResponse.new("Driver '#{self.class.driver.inspect}' did not return an object of the support types (Hitnmiss::Driver::Hit, Hitnmiss::Driver::Miss)")
+    end
+  end
+end
+```
+
+### Set a Repositories Cache Driver
+
+Hitnmiss defaults to the provided `Hitnmiss::InMemoryDriver`, but if an alternate
+driver is needed a new driver can be registered as seen below.
+
+```ruby
+# config/hitnmiss.rb
+Hitnmiss.register_driver(:my_driver, SomeAlternativeDriver.new)
+```
+
+Once you have registered the new driver you can tell `Hitnmiss` what
+driver to use for this particular repository. The following is an example
+of how one would accomplish setting the repository driver to the driver
+that was just registered.
+
+```ruby
+class MostRecentPrice
+  include Hitnmiss::Repository
+
+  driver :my_driver
+end
+```
+
+This works exactly the same with the `Hitnmiss::BackgroundRefreshRepository`.
+
+### Define Fetcher Methods
+
+You may be asking yourself, "How does the cache value get set?" Well,
+the answer is one of two ways.
+
+* Fetching an individual cacheable entity
+* Fetching all of the repository's cacheable entities
+
+Both of these scenarios are supported by defining the `fetch(*args)`
+method or the `fetch_all(keyspace)` method respectively in your cache
+repository class. See the following example.
+
+```ruby
+class MostRecentPrice
+  include Hitnmiss::Repository
+
+  default_expiration 134
+
+  private
+
+  def fetch(*args)
+    # - do whatever to get the value you want to cache
+    # - construct a Hitnmiss::Entity with the value
+    Hitnmiss::Entity.new('some value')
+  end
+
+  def fetch_all(keyspace)
+    # - do whatever to get the values you want to cache
+    # - construct a collection of arguments and Hitnmiss entities
+    [
+      { args: ['a', 'b'], entity: Hitnmiss::Entity.new('some value') },
+      { args: ['x', 'y'], entity: Hitnmiss::Entity.new('other value') }
+    ]
+  end
+end
+```
+
+The `fetch(*args)` method is responsible for obtaining the value that you want
+to cache by whatever means necessary and returning a `Hitnmiss::Entity`
+containing the value, and optionally an `expiration`, `fingerprint`, and
+`last_modified`. **Note:** The `*args` passed into the `fetch(*args)` method
+originate as the arguments that are passed into `prime` and `get` methods when
+they are called. For more context on `prime` and `get` please so [Priming an
+Entity](#priming-an-entity) and [Getting a Value](#getting-a-value)
+respectively. Defining the `fetch(*args)` method is **required** if you want to
+be able to cache values or get cached values using the `prime` or `get` methods.
+
+If you wish to support [priming the cache for an entire
+repository](#priming-the-entire-repository) using the `prime_all` method, you
+**must** define the `fetch_all(keyspace)` method on the repository class. This
+method **must** return a collection of hashes describing the `args` that would
+be used to get an entity and the corresponding `Hitnmiss::Entity`. See example
+above.
+
+#### Set Cache Source based Expiration
+
+In some cases you might need to set the expiration to be a different
+value for each cached value. This is generally needed when you get
+information back from a remote entity in the `fetch(*args)` method and you
+use it to compute the expiration. This for example could be via the `Expiration`
+header in an HTTP response. Once you have the expiration for that
+value you can set it by passing the expiration into the
+`Hitnmiss::Entity` constructor as seen below. **Note:** The expiration
+in the `Hitnmiss::Entity` will take precedence over the
+`default_expiration`.
+
+```ruby
+class MostRecentPrice
+  include Hitnmiss::Repository
+
+  default_expiration 134
+
+  private
+
+  def fetch(*args)
+    # - do whatever to get the value you want to cache
+    # - construct a Hitnmiss::Entity with the value and optionally a
+    #   result based expiration. If no result based expiration is
+    #   provided it will use the default_expiration.
+    Hitnmiss::Entity.new('some value', expiration: 235)
+  end
+end
+```
+
+#### Set Cache Source based Fingerprint
+
+In some cases you might want to set the fingerprint for the cached value. Doing
+so provides more flexibility to `Hitnmiss` in terms of determining staleness of
+cache. A very common example of this would be if you are fetching something over
+HTTP from the remote and the remote includes the `ETag` header. If you take the
+value of the `ETag` header (a fingerprint) and you set it in the
+`Hitnmiss::Entity` it can be used later on by `Hitnmiss` to aid in identifying
+staleness. Once you have obtained the fingerprint by whatever means you can set
+it by passing the fingerprint into the `Hitnmiss::Entity` constructor as seen
+below.
+
+```ruby
+class MostRecentPrice
+  include Hitnmiss::Repository
+
+  default_expiration 134
+
+  private
+
+  def fetch(*args)
+    # - do whatever to get the value you want to cache
+    # - do whatever to get the fingerprint of the value you want to cache
+    # - construct a Hitnmiss::Entity with the value and optionally a
+    #   fingerprint.
+    Hitnmiss::Entity.new('some value',
+                         fingerprint: "63478adce0dd0fbc82ef4bb1f1d64193")
+  end
+end
+```
+
+#### Set Cache Source based Last Modified
+
+In some cases you might want to set the `last_modified` value for a cached
+value. Doing this provides more felxibility to `Hitnmiss` when trying to
+determine staleness of a cached item. A common example of this would be if you
+are fetching somthing over HTTP from a remote server and it includes the
+`Last-Modified` entity header in the response. If you took the value of the
+`Last-Modified` header and you set it in the `Hitnmiss::Entity` it can be used
+later on by `Hitnmiss` to aid in identifying staleness. Once you have obtained
+the `Last-Modified` value by whatever means you can set it by passing the
+`last_modified` option into the `Hitnmiss::Entity` constructor as seen below.
+
+```ruby
+class MostRecentPrice
+  include Hitnmiss::Repository
+
+  default_expiration 134
+
+  private
+
+  def fetch(*args)
+    # - do whatever to get the value you want to cache
+    # - do whatever to get the last modified of the value you want to cache
+    # - construct a Hitnmiss::Entity with the value and optionally a
+    #   last_modified value.
+    Hitnmiss::Entity.new('some value',
+                         last_modified: "2016-04-15T13:00:00Z")
+  end
+end
+```
+
+## Usage
+
+The following is a light breakdown of the various pieces of Hitnmiss and
+how to get going with them after defining your cache repository.
+
+### Priming an entity
+
+Once you have defined the `fetch(*args)` method you can construct an
+instance of your cache repository and use it. One way you might want to
+use it is to force the repository to cache a value. This can be done
+using the `prime` method as seen below.
+
+```ruby
+repository = MostRecentPrice.new
+repository.prime(current_user.id) # => cached_value
+```
+
+### Priming the entire repository
+
+You can use the `prime_all` method to prime the entire repository. **Note:**
+The repository class must define the `fetch_all(keyspace)` method for this
+to work. See the "Define Fetcher Methods" section above for details.
+
+```ruby
+repository = MostRecentPrice.new
+repository.prime_all # => [cached values, ...]
+```
+
+### Getting a value
+
+You can also use your cache repository to get a particular cached
+value by doing the following.
+
+```ruby
+repository = MostRecentPrice.new
+repository.get(current_user.id) # => cached_value
+```
+
+### Deleting a cached value
+
+You can delete a cached value by calling the `delete` method with the
+same arguments used to get it.
+
+```ruby
+repository = MostRecentPrice.new
+# cache some values ex: repository.prime(current_user.id)
+repository.delete(current_user.id)
+```
+
+### Clearing a repository
+
+You can clear the entire repository of cached values by calling the
+`clear` method.
+
+```ruby
+repository = MostRecentPrice.new
+# cache some values ex: repository.prime(current_user.id)
+repository.clear
+```
+
+## Contributing
+
+If you are interested in contributing to Hitnmiss. There is a guide (both code
+and general help) over in
+[CONTRIBUTING](https://github.com/Acornsgrow/hitnmiss/blob/master/CONTRIBUTING.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT
+License](http://opensource.org/licenses/MIT).