thermos 2.0.0 → 2.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 37303ec15144f7b0a1aa69e53a80ea8bc7586b7af91e4ae7e4133aca8fa3ce8d
-  data.tar.gz: 5e5e22860067239168af1171502b880d534ba85e50e38c5a1c5c785c05987924
+  metadata.gz: 96c092c9b446b9147dca86d7f6b655dcb8f6f00191a8260b0dbb6bd15bea56c1
+  data.tar.gz: e7b19005dffe9c4fbec290576e0d9094fb1d04021fd037e3148dc7bb57d99179
 SHA512:
-  metadata.gz: 848351bdfa6ef208f1b285d4fd5e0000ba0fe61d1ce842961cbfb8a721adcbb7b61070dd96af3ef452006aa0632381537c7d8b81d183c7ac1db4d9d7ddb96bad
-  data.tar.gz: d29bea390a0cf22f754cc21d6b199fa1e507d79f5f71fcb455ecbd05ed92ed1fa3410fa306d94ddcc721407606e9fb8b8682a0802a54d88dbe2c9d2ead3f17f9
+  metadata.gz: 5484c23bf0c7ff96d75158c37bc399cf06a45a25447347c2a56ffc0bc8d026742042655019dbfb3518fbb3ea9765431963db334973692e3ad4f9cf272c78710e
+  data.tar.gz: 39f11866f8de933f2e6f68174f43d4c4b88fc48b25c472bee5799447cdcc6d91c568eb31173bf004a41cccf0d0b882cd0368d299287b6487d2c6f7d99bccac8c

data/README.md

@@ -0,0 +1,213 @@
+# Thermos
+
+**Always-warm Rails caching that automatically rebuilds when your models change.**
+
+[![Gem Version](https://badge.fury.io/rb/thermos.svg)](https://badge.fury.io/rb/thermos)
+[![Code Climate](https://codeclimate.com/github/athal7/thermos/badges/gpa.svg)](https://codeclimate.com/github/athal7/thermos)
+![Build Status](https://img.shields.io/github/actions/workflow/status/athal7/thermos/CI.yml?branch=main)
+
+Thermos is a Rails caching library that keeps your cache always warm by rebuilding it in the background whenever ActiveRecord models change. No more stale data, no more cold cache penalties, no more `touch: true` on all your associations.
+
+## Features
+
+- **Always-warm cache** — Cache is rebuilt in the background when models change
+- **No stale data** — Unlike TTL-based caching, data is only as stale as your job queue latency
+- **No cold cache penalties** — Cache is pre-warmed, so users never wait for expensive queries
+- **No `touch` callbacks needed** — Thermos watches model dependencies automatically
+- **Works with any backend** — Sidekiq, Solid Queue, Resque, or any ActiveJob adapter
+- **Works with any cache store** — Redis, Memcached, Solid Cache, or any Rails cache store
+- **ETag support** — Works seamlessly with HTTP caching for browser and CDN caching
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'thermos'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Quick Start
+
+```ruby
+# In a controller - cache is automatically rebuilt when Category or its products change
+json = Thermos.keep_warm(key: "category", model: Category, id: params[:id], deps: [:products]) do |id|
+  Category.includes(:products).find(id).to_json
+end
+
+render json: json
+```
+
+That's it! When any `Category` or associated `Product` is created, updated, or destroyed, Thermos automatically rebuilds the cache in the background.
+
+## Why Thermos?
+
+Most cache strategies have significant downsides:
+
+| Strategy | Problem |
+|----------|---------|
+| **TTL-based** (expires_in) | Stale data until expiration |
+| **Key-based** (cache_key) | Cold cache on first request after any change |
+| **Touch callbacks** | Extra database writes on every association change |
+
+Thermos solves all of these by rebuilding caches proactively in background jobs.
+
+> "I just want to Thermos everything now!! Unbelievable improvement. It's like every dev's dream come true" — [@jono-booth](https://github.com/jono-booth)
+
+## Prerequisites
+
+Configure a [Rails Cache Store](https://guides.rubyonrails.org/caching_with_rails.html#configuration) that supports shared access across processes (Redis, Memcached, Solid Cache — not MemoryStore).
+
+Thermos works with any ActiveJob adapter, including Rails 8's [Solid Queue](https://github.com/rails/solid_queue) and [Solid Cache](https://github.com/rails/solid_cache).
+
+## Usage
+
+### keep_warm (Simple)
+
+With `keep_warm`, the cached content is defined along with the cache block and dependencies definition. This is the simplest implementation, *but is only compatible with the [Active Job Inline Adapter](https://api.rubyonrails.org/classes/ActiveJob/QueueAdapters/InlineAdapter.html)*. See the next section about fill/drink for compatibility with other Active Job Adapters.
+
+*API Controller*
+
+```ruby
+json = Thermos.keep_warm(key: "api_categories_show", model: Category, id: params[:id], deps: [:category_items, :products]) do |id|
+  Category.find(id).to_json
+end
+
+render json: json
+```
+
+*Frontend Controller*
+
+```ruby
+rendered_template = Thermos.keep_warm(key: "frontend_categories_show", model: Category, id: params[:id], deps: [:category_items, :products]) do |id|
+  @category = Category.includes(category_items: :product).find(id)
+  render_to_string :show
+end
+
+render rendered_template
+```
+
+### fill / drink (Advanced)
+
+For more control, define your cache once with `fill` and read it anywhere with `drink`. This is ideal for sharing cached data across multiple controllers or when using background job adapters other than inline.
+
+*Rails Initializer*
+
+```ruby
+Thermos.fill(key: "api_categories_show", model: Category, deps: [:category_items, :products]) do |id|
+  Category.find(id).to_json
+end
+```
+
+*API Controller*
+
+```ruby
+json = Thermos.drink(key: "api_categories_show", id: params[:id])
+render json: json
+```
+
+## Options
+
+### lookup_key
+
+If you want to be able to lookup by a key other than `id` (e.g. you use a slug in the params), you can specify the `lookup_key` as an argument to `keep_warm` or `fill`:
+
+```ruby
+Thermos.keep_warm(key: "api_categories_show", model: Category, id: params[:slug], lookup_key: :slug) do |slug|
+  Category.find_by(slug: slug).to_json
+end
+```
+
+or
+
+```ruby
+Thermos.fill(key: "api_categories_show", model: Category, lookup_key: :slug) do |slug|
+  Category.find_by(slug: slug).to_json
+end
+```
+
+### queue
+
+If you want to specify a queue for the refill jobs to run other than the default queue, you can provide it to either way of using Thermos:
+
+```ruby
+Thermos.keep_warm(key: "api_categories_show", model: Category, queue: "low_priority") do |id|
+  Category.find(id).to_json
+end
+```
+
+or
+
+```ruby
+Thermos.fill(key: "api_categories_show", model: Category, queue: "low_priority") do |id|
+  Category.find(id).to_json
+end
+
+Thermos.drink(key: "api_categories_show", id: params[:slug])
+```
+
+### Indirect Relationships
+
+You can specify indirect relationships as dependencies as well. For example, if `Store has_many categories`, and `Category has_many products`, but there is no relationship specified on the `Store` model to `Product`:
+
+```ruby
+Thermos.keep_warm(key: "api_stores_show", model: Store, id: params[:id], deps: [categories: [:products]]) do |id|
+  Store.find(id).to_json
+end
+```
+
+*NOTE* in this example, a change to any model in the association chain will trigger a refill of the cache.
+
+### filter
+
+You can provide a filter to restrict whether a record gets rebuilt on model changes:
+
+```ruby
+filter = ->(model) { model.name.match("ball") }
+Thermos.keep_warm(key: "api_categories_show", model: Category, id: params[:id], filter: filter) do |id|
+  Category.find(id).to_json
+end
+```
+
+## Using with ETags
+
+Thermos works seamlessly with Rails' HTTP caching via ETags, enabling browser and CDN caching of your responses. Since Thermos keeps your cache always warm and rebuilds it when models change, the cached value's digest will naturally change when the underlying data changes.
+
+Use Rails' `stale?` helper with the cached value to enable conditional GET requests:
+
+```ruby
+def show
+  json = Thermos.drink(key: "api_categories_show", id: params[:id])
+
+  if stale?(etag: json)
+    render json: json
+  end
+end
+```
+
+When the cached value changes (triggered by model updates), the ETag will change, and clients will receive the new content. When the value hasn't changed, clients with a matching ETag will receive a `304 Not Modified` response.
+
+This enables caching at multiple layers:
+- **Browser cache**: Browsers store responses and revalidate with the server using the ETag, avoiding re-downloads of unchanged content
+- **CDN cache**: CDNs can cache responses and serve them directly to users, only revalidating with your server when needed
+
+Combined with Thermos, you get:
+- **Always-warm application cache** (no cold cache penalties)
+- **Reduced server load** (304 responses skip rendering)
+- **Reduced bandwidth** (browsers and CDNs serve cached content)
+- **Faster responses** (CDN edge locations serve content closer to users)
+
+## Contributors
+
+<a href="https://github.com/athal7/thermos/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=athal7/thermos" />
+</a>
+
+## License
+
+This project uses MIT-LICENSE.

data/lib/thermos/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Thermos
-  VERSION = "2.0.0"
+  VERSION = "2.0.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: thermos
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.0.1
 platform: ruby
 authors:
 - Andrew Thal
@@ -87,8 +87,12 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 description: |
-  Thermos is a library for caching in rails that re-warms caches
-  in the background based on model changes.
+  Thermos is a Rails caching library that keeps your cache always warm by
+  automatically rebuilding it in the background when ActiveRecord models change.
+  No more stale data from TTL expiration, no more slow cold cache hits, and no
+  need to 'touch' associated models. Works with any ActiveJob backend (Sidekiq,
+  Solid Queue, etc.) and any cache store (Redis, Memcached, Solid Cache, etc.).
+  Perfect for API responses, JSON serialization, and view caching.
 email:
 - athal7@me.com
 executables: []
@@ -96,6 +100,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - MIT-LICENSE
+- README.md
 - Rakefile
 - lib/thermos.rb
 - lib/thermos/beverage.rb
@@ -160,7 +165,11 @@ files:
 homepage: https://github.com/athal7/thermos
 licenses:
 - MIT
-metadata: {}
+metadata:
+  homepage_uri: https://github.com/athal7/thermos
+  source_code_uri: https://github.com/athal7/thermos
+  changelog_uri: https://github.com/athal7/thermos/releases
+  rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -179,7 +188,8 @@ requirements: []
 rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
-summary: Always-warm, auto-rebuilding rails caching without timers or touching.
+summary: Always-warm, auto-rebuilding Rails cache that updates in the background when
+  models change.
 test_files:
 - test/dependencies_test.rb
 - test/dummy/README.rdoc