Module: Cybertrain::Cache

Defined in:
cybertrain/cache.rb

Overview

Cybertrain::Cache – a cache store in the application’s own SQLite database: “keep this answer for a while, so the next request does not ask the slow API again”.

require “cybertrain/cache” # bin/.rb, or a file it requires

text = Cybertrain::Cache.fetch(“defillama/tvl”, expires_in: 21_600, race_condition_ttl: 30) do client.get(“https://api.llama.fi/tvl”).body end data = Cybertrain::Cache.fetch_hash(“prices/eth”, expires_in: 60) { { “usd” => price } } Cybertrain::Cache.write(“import-lock”, “1”, expires_in: 300, unless_exist: true) # true when written

Values are Strings (Cache.fetch_hash, Cache.fetch_array and Cache.fetch_int store JSON or Integer text and parse it back). Times are epoch seconds from Cache.now. expires_in: 0, the default, never expires; a row with expires_at E is live up to and including second E and expired from E + 1 on.

The rows live in cybertrain_cache, which the framework creates itself (CREATE TABLE IF NOT EXISTS, on first use) and leaves out of db/schema.rb, like cybertrain_jobs. Every write takes the application’s SQLite writer lock, which requests writing their own rows wait for: cache what the jobs produce rather than in request paths that write often. Nothing is kept in memory: every read is a SELECT, which SQLite answers from its page cache. The expired rows are deleted every Cybertrain::Config#cache_prune_interval seconds (Cache.prune): with require "cybertrain/jobs", by the scheduled task "cybertrain cache prune" (requiring both registers it); without jobs, by the writes (Cache.write, Cache.increment): the first of the process and the first once that interval has passed, at most 1000 rows per write (Cache.prune_if_due).

Class Method Summary collapse

Class Method Details

.clear ⇒ nil

Removes every row.

Returns:

  • (nil)

Raises:

  • (Cybertrain::DB::Error) —

    when the database is not reachable



360
361
362
363
364
# File 'cybertrain/cache.rb', line 360

def self.clear
  ensure_installed
  DB.with { |c| c.execute("DELETE FROM cybertrain_cache") }
  nil
end

.delete(key) ⇒ Boolean

Removes the row of key, live or expired.

Parameters:

  • key (String)

Returns:

  • (Boolean) —

    true when there was a row

Raises:

  • (Cybertrain::DB::Error) —

    when the database is not reachable



310
311
312
313
314
315
316
317
318
# File 'cybertrain/cache.rb', line 310

def self.delete(key)
  ensure_installed
  changed = 0
  DB.with do |c|
    c.execute("DELETE FROM cybertrain_cache WHERE key = ?", [key])
    changed = c.changes
  end
  changed > 0
end

.exist?(key) ⇒ Boolean

Whether a live row is stored under key.

Parameters:

  • key (String)

Returns:

  • (Boolean)

Raises:

  • (Cybertrain::DB::Error) —

    when the database is not reachable



325
326
327
# File 'cybertrain/cache.rb', line 325

def self.exist?(key)
  !live_value(key, Cache.now).nil?
end

.fetch(key, expires_in: 0, race_condition_ttl: 0) { ... } ⇒ String

The value stored under key, or the block’s value, which is then stored. A live row is answered without running the block. On a miss (no row, or an expired one) the block runs and its value, a String (anything else is stored as its to_s), is written with expires_in.

With race_condition_ttl: n, a caller that finds the row expired first extends it by n seconds; only the caller whose extension changed the row runs the block, and the others answer the stale value meanwhile (Rails’ semantics). When that block raises, nothing is written and the exception propagates: the stale value is served until the extension runs out. Without it, every caller of an expired key runs the block. A missing row is always computed.

Parameters:

  • key (String)
  • expires_in (Integer) (defaults to: 0) —

    seconds the value stays live; 0 (the default) never expires (Rails’ nil: an Integer keyword takes 0)

  • race_condition_ttl (Integer) (defaults to: 0) —

    seconds to serve an expired value while one caller recomputes it; 0 for none

Yields:

  • on a miss

Yield Returns:

  • (String) —

    the value to store

Returns:

  • (String)

Raises:

  • (Cybertrain::DB::Error) —

    when the database is not reachable



155
156
157
158
159
160
161
162
163
164
165
166
# File 'cybertrain/cache.rb', line 155

def self.fetch(key, expires_in: 0, race_condition_ttl: 0)
  hit = fetch_hit(key, race_condition_ttl)
  return hit.to_s unless hit.nil?

  # The block's value in a local first: an argument expression may be
  # evaluated once per branch of the inlined cast, running the block
  # twice.
  computed = yield
  value = Cast.str(computed)
  write(key, value, expires_in: expires_in)
  value
end

.fetch_array(key, expires_in: 0, race_condition_ttl: 0) { ... } ⇒ Array<Object>

fetch for an Array, stored as JSON and parsed back with Cybertrain::Cast.array: a corrupt cell (not a JSON array) reads as [] until it expires and the block runs again.

Parameters:

  • key (String)
  • expires_in (Integer) (defaults to: 0) —

    as fetch’s; 0 never expires

  • race_condition_ttl (Integer) (defaults to: 0) —

    as fetch’s

Yields:

  • on a miss

Yield Returns:

  • (Array) —

    the value to store

Returns:

  • (Array<Object>)

Raises:

  • (Cybertrain::DB::Error) —

    when the database is not reachable



200
201
202
203
204
205
206
207
208
# File 'cybertrain/cache.rb', line 200

def self.fetch_array(key, expires_in: 0, race_condition_ttl: 0)
  hit = fetch_hit(key, race_condition_ttl)
  return Cast.array(Cast.parse_json(hit.to_s)) unless hit.nil?

  computed = yield
  text = JSON.generate(computed)
  write(key, text, expires_in: expires_in)
  Cast.array(Cast.parse_json(text))
end

.fetch_hash(key, expires_in: 0, race_condition_ttl: 0) { ... } ⇒ Hash{String => Object}

fetch for a Hash, stored as JSON and parsed back with Cybertrain::Cast.json_hash: a corrupt cell (not a JSON object) reads as {} until it expires and the block runs again.

Parameters:

  • key (String)
  • expires_in (Integer) (defaults to: 0) —

    as fetch’s; 0 never expires

  • race_condition_ttl (Integer) (defaults to: 0) —

    as fetch’s

Yields:

  • on a miss

Yield Returns:

  • (Hash) —

    the value to store

Returns:

  • (Hash{String => Object})

Raises:

  • (Cybertrain::DB::Error) —

    when the database is not reachable



179
180
181
182
183
184
185
186
187
# File 'cybertrain/cache.rb', line 179

def self.fetch_hash(key, expires_in: 0, race_condition_ttl: 0)
  hit = fetch_hit(key, race_condition_ttl)
  return Cast.json_hash(hit.to_s) unless hit.nil?

  computed = yield
  text = JSON.generate(computed)
  write(key, text, expires_in: expires_in)
  Cast.json_hash(text)
end

.fetch_int(key, expires_in: 0, race_condition_ttl: 0) { ... } ⇒ Integer

fetch for an Integer, stored as its decimal text: a corrupt cell (not an integer, or one too long to be one) reads as 0 until it expires and the block runs again.

Parameters:

  • key (String)
  • expires_in (Integer) (defaults to: 0) —

    as fetch’s; 0 never expires

  • race_condition_ttl (Integer) (defaults to: 0) —

    as fetch’s

Yields:

  • on a miss

Yield Returns:

Returns:

Raises:

  • (Cybertrain::DB::Error) —

    when the database is not reachable



221
222
223
224
225
226
227
228
229
# File 'cybertrain/cache.rb', line 221

def self.fetch_int(key, expires_in: 0, race_condition_ttl: 0)
  hit = fetch_hit(key, race_condition_ttl)
  return Params.parse_int(hit.to_s, 0) unless hit.nil?

  computed = yield
  value = Cast.int(computed)
  write(key, value.to_s, expires_in: expires_in)
  value
end

.increment(key, by: 1, expires_in: 0) ⇒ Integer

Adds by to the Integer stored under key in one statement, and answers the sum. A missing or expired row starts at by; a value that is not a number counts as 0. expires_in sets the expiry of a new or expired row, and of a live row that has none; a live row that has one keeps it, so the counter’s window is fixed from its first increment (as Rails’ stores do) and does not slide with every call.

Examples:

A counter for the current minute

Cybertrain::Cache.increment("hits/#{ip}", expires_in: 60)

Parameters:

  • key (String)
  • by (Integer) (defaults to: 1) —

    may be negative

  • expires_in (Integer) (defaults to: 0) —

    seconds the value stays live from the counter’s start; 0 (the default) leaves the expiry as it is (a new row never expires)

Returns:

Raises:

  • (Cybertrain::DB::Error) —

    when the database is not reachable



345
346
347
348
349
350
351
352
353
354
# File 'cybertrain/cache.rb', line 345

def self.increment(key, by: 1, expires_in: 0)
  ensure_installed
  now = Cache.now
  prune_if_due(now)
  expires_at = expires_in > 0 ? now + expires_in : 0
  rows = DB.with { |c| c.execute(INCREMENT_SQL, Cast.binds(key, by, expires_at, now)) }
  return 0 if rows.empty?

  Cast.int(rows[0]["n"])
end

.install! ⇒ nil

Creates the table if it is missing. Every other method calls it once per connected database; call it yourself only to create the table ahead of time.

Returns:

  • (nil)


109
110
111
112
113
114
115
116
# File 'cybertrain/cache.rb', line 109

def self.install!
  DB.with { |c| c.exec_script(TABLE_SQL) }
  # A CREATE inside a transaction that rolls back is undone, so only one
  # outside a transaction is remembered (as Job.install! does).
  pool = DB.pool
  @installed_generation = DB.generation if !pool.nil? && pool.held_index < 0
  nil
end

.now ⇒ Integer

The current time as the cache sees it: Cybertrain::Clock.now in epoch seconds, so a test moves it with travel_to / travel instead of sleeping.

Returns:



128
129
130
# File 'cybertrain/cache.rb', line 128

def self.now
  Clock.now.to_i
end

.prune(now) ⇒ Integer

Deletes the rows expired at now (an expires_at before it), at most 1000 per statement so the writer lock is released between batches. The scheduled task "cybertrain cache prune" calls it with now.

Parameters:

Returns:

  • (Integer) —

    how many rows were deleted

Raises:

  • (Cybertrain::DB::Error) —

    when the database is not reachable



374
375
376
377
378
379
380
381
382
383
# File 'cybertrain/cache.rb', line 374

def self.prune(now)
  ensure_installed
  total = 0
  batch = PRUNE_BATCH
  while batch == PRUNE_BATCH
    batch = prune_batch(now)
    total += batch
  end
  total
end

.read(key) ⇒ String?

The live value stored under key; nil when there is none or it has expired.

Parameters:

  • key (String)

Returns:

  • (String, nil)

Raises:

  • (Cybertrain::DB::Error) —

    when the database is not reachable



272
273
274
# File 'cybertrain/cache.rb', line 272

def self.read(key)
  live_value(key, Cache.now)
end

.register_prune_task ⇒ nil

Registers the scheduled task "cybertrain cache prune", every prune_interval seconds, when cybertrain/jobs is loaded and no task of that name is registered already (Features.schedule_all_periodic: JobsFeature takes on CacheFeature’s periodic hook). Requiring this file and cybertrain/jobs, in either order, registers it; calling it again adds nothing.

Returns:

  • (nil)


465
466
467
468
# File 'cybertrain/cache.rb', line 465

def self.register_prune_task
  Features.schedule_all_periodic
  nil
end

.write(key, value, expires_in: 0, unless_exist: false) ⇒ Boolean

Stores value under key, replacing any row. With unless_exist: true a live row is left alone and the answer is false (an expired one is replaced): a lock for expires_in seconds that one process gets.

Parameters:

  • key (String)
  • value (String)
  • expires_in (Integer) (defaults to: 0) —

    seconds the value stays live; 0 (the default) never expires (Rails’ nil: an Integer keyword takes 0)

  • unless_exist (Boolean) (defaults to: false) —

    keep a live row instead of replacing it

Returns:

  • (Boolean) —

    true when written; false only when unless_exist found a live row

Raises:

  • (Cybertrain::DB::Error) —

    when the database is not reachable



289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
# File 'cybertrain/cache.rb', line 289

def self.write(key, value, expires_in: 0, unless_exist: false)
  ensure_installed
  now = Cache.now
  prune_if_due(now)
  expires_at = expires_in > 0 ? now + expires_in : 0
  sql = unless_exist ? ADD_SQL : WRITE_SQL
  binds = Cast.binds(key, value, expires_at, now)
  binds << now if unless_exist
  changed = 0
  DB.with do |c|
    c.execute(sql, binds)
    changed = c.changes
  end
  changed > 0
end