Skip to content

Commit

Permalink
Update readme
Browse files Browse the repository at this point in the history
  • Loading branch information
@jlurena
jlurena committed Jul 11, 2024
1 parent ed4239d commit 60df81c
Showing 1 changed file with 31 additions and 85 deletions.
116 changes: 31 additions & 85 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# CachedResource ![Tests](https://github.com/mhgbrown/cached_resource/actions/workflows/ruby.yml/badge.svg)

CachedResource is a Ruby gem whose goal is to increase the performance of interacting with web services via ActiveResource by caching responses based on request parameters. It can help reduce the lag created by making repeated requests across a network.
CachedResource is a Ruby gem designed to enhance the performance of web service interactions through ActiveResource by caching responses based on request parameters. By reducing the need for repeated network requests, it minimizes latency and optimizes the efficiency of your application's data retrieval processes.

## Installation

Expand All @@ -12,115 +12,61 @@ gem install cached_resource

CachedResource is designed to be framework agnostic, but will hook into Rails for caching and logging if available. CachedResource supports the following ActiveSupport/Rails (right) and Ruby (down) version combinations:

| | 🛤️ 4.2 | 🛤️ 5.0 | 🛤️ 5.1 | 🛤️ 6.0 | 🛤️ 6.1 | 🛤️ 7.0 | 🛤️ 7.1 |
|-------|-----|-----|-----|-----|-----|-----|-----|
| 💎 2.3 | ✅ | ✅ | ✅ | | | | |
| 💎 2.4 | ✅ | ✅ | ✅ | | | | |
| 💎 2.5 | ✅ | ✅ | ✅ | ✅ | ✅ | | |
| 💎 2.6 | ✅ | ✅ | ✅ | ✅ | ✅ | |
| 💎 2.7 | | ✅ | ✅ | ✅ | ✅ | ✅ |✅ |
| 💎 3.0 | | | | ✅ | ✅ | ✅ | ✅ |
| 💎 3.1 | | | | ✅ | ✅ | ✅ | ✅ |
| 💎 3.2 | | | | ✅ | ✅ | ✅ | ✅ |
| 💎 3.3 | | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |

## Limitations

The following are limitations for ActiveResource/Rails versions

| ActiveSupport Version | Limitation |
|---------------------- | ----------------------------------------------------------------------- |
| 🛤️ 4.X | You cannot chain calls. Ie `Thing.where(fn: 'foo').where(ln: 'bar')`. <br> However, you can still access `original_params` and the `resource_class` and replicate it with <br>`call1 = Thing.where(fn: 'foo')`<br>`call1.resource_class.where(call1.original_params.merge(ln: 'bar'))` |
| | 🛤️ 6.1 | 🛤️ 7.0 | 🛤️ 7.1 |
|----------|:------:|:------:|:------:|
| 💎 3.0 | ✅ | ✅ | ✅ |
| 💎 3.1 | ✅ | ✅ | ✅ |
| 💎 3.2 | ✅ | ✅ | ✅ |

## Configuration

**Set up CachedResource across all ActiveResources:**

```ruby
class ActiveResource::Base
cached_resource
cached_resource(options)
end
```

Or set up CachedResource for a single class:

```ruby
class MyActiveResource < ActiveResource::Base
cached_resource
cached_resource(options)
end
```

### Options
CachedResource accepts the following options:

* `:enabled` Default: `true`
* `:cache_collections` Set to false to always remake a request for collections. Default: `true`
* `:cache` The cache store that CacheResource should use. Default: The `Rails.cache` if available, or an `ActiveSupport::Cache::MemoryStore`
* `:collection_arguments` The arguments that identify the principal collection request. Default: `[:all]`
* `:collection_synchronize` Use collections to generate cache entries for individuals. Update the existing cached principal collection when retrieving subsets of the principal collection or individuals. Default: `false`
* `:concurrent_write` Set to true to make concurrent writes to cache after successful API response. Default: `false`
* Requires the [concurrent-ruby](https://rubygems.org/gems/concurrent-ruby) gem
* `:logger` The logger to which CachedResource messages should be written. Default: The `Rails.logger` if available, or an `ActiveSupport::Logger`
* `:race_condition_ttl` The race condition ttl, to prevent [dog pile effect](https://en.wikipedia.org/wiki/Cache_stampede) or [cache stampede](https://en.wikipedia.org/wiki/Cache_stampede). Default: 86400
* `:ttl_randomization_scale` A Range from which a random value will be selected to scale the ttl. Default: `1..2`
* `:ttl_randomization` Enable ttl randomization. Default: `false`
* `:ttl` The time in seconds until the cache should expire. Default: `604800`

You can set them like this:

CachedResource accepts the following options as a hash:

| Option | Description | Default |
|----------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------|
| `:enabled` | Enables or disables caching. | `true` |
| `:cache_collections` | Set to false to always remake a request for collections. | `true` |
| `:cache` | The cache store that CacheResource should use. | The `Rails.cache` if available, or an `ActiveSupport::Cache::MemoryStore` |
| `:cache_key_prefix` | A prefix to be added to the cache keys. | `nil` |
| `:collection_arguments` | The arguments that identify the principal collection request. | `[:all]` |
| `:collection_synchronize` | Use collections to generate cache entries for individuals. Update the existing cached principal collection when retrieving subsets of the principal collection or individuals. | `false` |
| `:concurrent_write` | Set to true to make concurrent writes to cache after successful API response. <br>Requires the [concurrent-ruby](https://rubygems.org/gems/concurrent-ruby) gem | `false` |
| `:logger` | The logger to which CachedResource messages should be written. | The `Rails.logger` if available, or an `ActiveSupport::Logger` |
| `:race_condition_ttl` | The race condition ttl, to prevent [dog pile effect](https://en.wikipedia.org/wiki/Cache_stampede) or [cache stampede](https://en.wikipedia.org/wiki/Cache_stampede). | `86400` |
| `:ttl_randomization_scale` | A Range from which a random value will be selected to scale the ttl. | `1..2` |
| `:ttl_randomization` | Enable ttl randomization. | `false` |
| `:ttl` | The time in seconds until the cache should expire. | `604800` |

For example:
```ruby
cached_resource :cache => MyCacheStore.new, :ttl => 60, :collection_synchronize => true, :logger => MyLogger.new
```

You can also change them on the fly.

Turn CachedResource off. This will cause all responses to be retrieved normally (i.e. via the network). All responses will still be cached.

```ruby
MyActiveResource.cached_resource.off!
```

Turn CachedResource on.
```ruby
MyActiveResource.cached_resource.on!
```

Set the cache expiry time to 60 seconds.

```ruby
MyActiveResource.cached_resource.ttl = 60
```

Enable cache expiry time randomization, allowing it to fall randomly between 60 and 120 seconds.
#### You can also change them dynamically. Simply:

```ruby
MyActiveResource.cached_resource.ttl_randomization = true
MyActiveResource.cached_resource.option = option_value
```

Change the cache expiry time randomization scale so that the cache expiry time falls randomly between 30 and 180 seconds.

For example, to turn CachedResource off
```ruby
MyActiveResource.cached_resource.ttl_randomization_scale = 0.5..3
```
Enable collection synchronization. This will cause a call to `MyActiveResource.all` to also create cache entries for each of its members. So, for example, a later call to `MyActiveResource.find(1)` will be read from the cache instead of requested from the remote service.

```ruby
MyActiveResource.cached_resource.collection_synchronize = true
```
Change the arguments that identify the principal collection request. If for some reason you are concerned with a collection that is retrieved at a "non-standard" URL, you may specify the Ruby arguments that produce that URL. When `collection_synchronize` is `true`, the collection returned from a request that matches these arguments will be cached and later updated when one of its members or a subset is retrieved.

```ruby
MyActiveResource.cached_resource.collection_arguments = [:all, :params => {:name => "Bob"}]
```
Set a different logger.

```ruby
MyActiveResource.cached_resource.logger = MyLogger.new
```
Set a different cache store.

```ruby
MyActiveResource.cached_resource.cache = MyCacheStore.new
MyActiveResource.cached_resource.off!
```

### Caveats
Expand All @@ -134,7 +80,7 @@ end

```ruby
class MyActiveResource < ActiveResource::Base
self.cached_resource = CachedResource::Configuration.new(:collection_synchronize => true)
self.cached_resource = CachedResource::Configuration.new(:collection_synchronize: true)
end
```
## Usage
Expand Down

0 comments on commit 60df81c

Please sign in to comment.