howdy_cache

An application cache for howdy apps: keep the result of expensive work for a while, and throw it away when the data it came from changes. Entries live in this node’s memory or in the app’s database, PostgreSQL or SQLite, or anywhere a store can reach.

Add it to your project:

gleam add howdy_cache@1

Fetch or compute

import howdy/cache
import howdy/cache/memory
import howdy/codec

// In main, once:
let app_cache = cache.new(memory.new(max_entries: 50_000))

// Anywhere:
pub fn find(id: Int) -> service.Result(Note) {
  let entry =
    cache.entry("note:" <> int.to_string(id), ttl: 300)
    |> cache.tags(["note:" <> int.to_string(id)])
  use <- cache.fetch(app_cache, entry, note_codec())
  notes.find(db, id)
}

// When the note changes, inside its transaction or not:
cache.invalidate(app_cache, ["note:" <> int.to_string(id)])

• fetch stores Ok results only, so a failed query is retried.
• Values are JSON, through a howdy/codec codec, in every store. One that no longer decodes after a deploy counts as missing.
• Tags have versions, read before the value is computed, so a value built from data that changed meanwhile is never served.
• Inside a howdy/database transaction, invalidate and delete wait for it to end, put deletes the key then instead of storing, and fetch skips the cache.
• A store that fails makes fetch compute instead, with a warning.
• Concurrent misses on one node compute once and share the result or error.

Stores

• howdy/cache/memory: ETS on this node, bounded by max_entries. Each node has its own entries and invalidations.
• howdy/cache/database: shared by every node using the database, one query per read, UNLOGGED tables on PostgreSQL. Run cache_database.schema() with howdy/migration first.
• Your own: cache.store from seven functions.

See the caching docs for the details, and howdy/conditional in the core package for answering 304 Not Modified.

Development

The tests run against the memory store and a SQLite database. Set HOWDY_CACHE_TEST_POSTGRES_URL to run the database store against PostgreSQL too; the tests drop and recreate the package’s tables there.

HOWDY_CACHE_TEST_POSTGRES_URL=postgres://howdy_cache_test@localhost/postgres gleam test