Migrating refresh and refresh! callers

Horreum#refresh!, Horreum#refresh, HashKey#refresh! and HashKey#refresh changed behavior in #443 and in the follow-up changes described below. Code that refreshes records it has just saved or loaded needs no change.

Check your code if it does any of the following:

  • refreshes a record that may not be saved yet, or may have expired or been deleted
  • expects a field to keep its in-memory value through refresh! when nothing is stored for it
  • refreshes records whose stored hash may hold a different identifier than its key, or lack a field the identifier reads
  • rescues Redis::CommandError around a HashKey refresh
  • reads the return value of HashKey#refresh!
  • relies on HashKey#refresh! to extend the key's TTL

Breaking Changes

Horreum#refresh! raises Familia::KeyNotFoundError for a missing key (#443)

The method was documented to raise Familia::KeyNotFoundError when the key does not exist, but it returned normally (refresh! returned []), kept the in-memory field values, including an objid generated to build the key, reset transient fields to nil and cleared dirty tracking. It now raises, and the object is left as it was. Horreum#refresh behaves the same way.

user = User.new(email: "alice@example.com")  # never saved

# Before: returned, and user.dirty? was false afterwards
# After: raises Familia::KeyNotFoundError
user.refresh!

When the record may not exist, load it instead. find_by_id and load return nil for a missing key:

user = User.find_by_id("alice@example.com")

Or rescue the error where a missing record is expected:

begin
  user.refresh!
rescue Familia::KeyNotFoundError
  # not saved yet, expired or deleted
end

Calling exists? first does not replace the rescue. The two calls are separate commands, and the key can expire or be deleted between them.

Horreum#refresh! sets fields that are not stored to nil

Familia stores a nil field by leaving it out of the hash. refresh! assigned only the fields present in the stored hash, so a field with nothing stored kept whatever value the object held in memory, and dirty tracking was cleared anyway. It now sets every persistent field that is not stored to nil, which is what load and find_by_id give. A Symbol or String identifier field that is not stored keeps its value. That includes a field declared with as: and named by its accessor (field :user_id, as: :uid with identifier_field :uid). A Proc identifier, or an identifier_field that names a method rather than a field, has no identifier field: the fields it reads are set from the stored hash like any other field. If that leaves no identifier, or one that names another key, refresh! raises instead (see the next section). Horreum#refresh behaves the same way.

This affects values set in memory and never saved, fields another writer removed, and defaults assigned by an init hook to an object built with new:

class User < Familia::Horreum
  identifier_field :email
  field :email
  field :status

  def init
    @status ||= "active"
  end
end

user = User.new(email: "alice@example.com")  # init sets status to "active"
# The stored hash for alice@example.com has no status field.
user.refresh!

# Before: "active"
# After: nil, the same as User.load("alice@example.com").status
user.status

If code depends on a default surviving refresh!, apply the default where the value is read (user.status || "active") or save it so that it is stored.

The same applies to an objid or extid that was generated on first read and never saved: refresh! discards it, and the next read generates a different value. If the generated value has already been shared, for example in a URL, save before calling refresh!:

class User < Familia::Horreum
  feature :object_identifier
  feature :external_identifier
  identifier_field :email
  field :email
end

user = User.load("alice@example.com")  # the stored hash has no objid or extid
link_id = user.extid                    # generates an objid and derives the extid from it
user.save                               # without this, user.extid differs from link_id after refresh!
user.refresh!
user.extid == link_id  # => true

Horreum#refresh! raises Familia::IdentifierMismatchError instead of changing the object's identity

refresh! never changes which record an object is. After it assigns the stored values it computes the identifier again. If there is none, or it names a key other than the one refresh! read, it raises Familia::IdentifierMismatchError and leaves the object as it was, so a later save writes to the key the object had. Horreum#refresh behaves the same way.

Two kinds of stored hash cause this, for example after a raw HSET or HDEL, a migration, or another application writing the hash:

  • The stored identifier field, or a stored field that a Proc or method identifier reads, holds a value that names a different key than the one it is stored under. refresh! used to assign it, so the object pointed at the other key, and a later save wrote this object's fields there, into another record or a new one.
  • A field that a Proc or method identifier reads is missing from the stored hash. refresh! used to keep the in-memory value, so the identity did not change. Now that refresh! sets fields that are not stored to nil (see the previous section), the identifier would be gone, or with feature :object_identifier a new objid would be generated, so it raises instead.
class User < Familia::Horreum
  identifier_field :email
  field :email
  field :name
end

user = User.new(email: "alice@example.com")
# The stored hash for alice@example.com holds email "bob@example.com".

# Before: user.email became "bob@example.com", and user.save wrote to Bob's record
# After: raises Familia::IdentifierMismatchError; user.email is still "alice@example.com"
user.refresh!

The error carries the key that was read (key) and the key the stored values name (resolved_key, nil when they give no identifier). A Proc identifier that raises on the stored values, for example by calling a method on a missing field, also counts as giving no identifier, and its error is the cause. find_by_id and load build a new object from the stored hash and do not raise, so use them to inspect such a record. The identifiers are compared through the key, so a stored 42 and an in-memory "42" name the same record.

HashKey#refresh! raises Familia::KeyNotFoundError instead of Redis::CommandError (#443)

For a missing hash, HashKey#refresh! and HashKey#refresh raised Redis::CommandError (ERR wrong number of arguments for 'hmset' command). They now raise Familia::KeyNotFoundError, which is also raised for a hash whose last field was removed. Update rescue clauses:

# Before
begin
  user.settings.refresh!
rescue Redis::CommandError
  # ...
end

# After
begin
  user.settings.refresh!
rescue Familia::KeyNotFoundError
  # ...
end

HashKey#refresh! and HashKey#refresh no longer write

A HashKey keeps no field values in memory, so there is nothing to reload. refresh! read the hash with HGETALL, then sent HMSET with the values it had just read and reset the key's expiration. It now sends only the HGETALL. Check the following.

Return value. refresh! returns the fields it read, as hgetall returns them. It used to return the HMSET reply, "OK". refresh still returns the HashKey itself.

user.settings.refresh!  # Before: "OK"
                        # After:  {"theme" => "dark", "lang" => "en"}

Expiration. The old refresh! called update_expiration, which sends EXPIRE with the default expiration when one is configured. The Valkey EXPIRE documentation (https://valkey.io/commands/expire/) says: "It is possible to call EXPIRE using as argument a key that already has an existing expire set. In this case the time to live of a key is updated to the new value." A refresh therefore extended the TTL. It no longer does. If you relied on that, extend it explicitly:

user.settings.refresh!
user.settings.update_expiration

Writes by other clients. The Valkey HMSET documentation (https://valkey.io/commands/hmset/) says: "This command overwrites any specified fields already existing in the hash." The old refresh! sent every field it had read, so a value another client wrote between the HGETALL and the HMSET was replaced by the value read before it. The old refresh! also serialized each value again before writing it, so a value stored without JSON encoding (for example not-json written with redis-cli HSET) was stored back as the JSON string "not-json". Both writes are gone, and no change is needed on your side.

Dirty-write check. The old refresh! ran the check that collection writes run (warn_if_dirty! in lib/familia/data_type.rb). It did nothing when the parent had no unsaved field changes or when the resolved dirty_write_warnings mode was :off. Otherwise it raised Familia::Problem when Familia.strict_write_order was true, under dirty_write_warnings :strict, or when the parent's hash did not exist and Familia.raise_on_unsaved_parent_write was true (the default). In every other case it warned: on every call under :warn, and once per set of unsaved fields under :once (the default). It no longer runs the check. Writes through the same HashKey still do.

Other changes

No action is needed for these.

Refreshing inside a transaction or pipeline raises Familia::OperationModeError

All four methods need the HGETALL reply, which is a Redis::Future inside transaction, pipelined or atomic_write. Such code already failed: the methods raised NoMethodError on the Redis::Future. They now raise Familia::OperationModeError before sending anything, and the message says to refresh before opening the block:

# Before: NoMethodError. After: Familia::OperationModeError
user.atomic_write do
  user.refresh!
  user.name = "Alice"
end

# Instead
user.refresh!
user.atomic_write do
  user.name = "Alice"
end

Horreum#refresh! no longer removes lookup entries

Horreum#refresh! no longer sends HDEL to the objid_lookup or extid_lookup hash. The objid and extid setters (lib/familia/features/object_identifier.rb and lib/familia/features/external_identifier.rb) remove the lookup entry of the value they replace when the new value differs, and refresh! used to call them with the in-memory value still in place. On an object built from another record's attributes, that removed the other record's lookup entry. With identifier_field :objid (or :extid) and a stored value that differs from the key, it removed the object's own lookup entry and the object took the stored identifier. That case now raises Familia::IdentifierMismatchError without touching the lookup hash, as described under "Horreum#refresh! raises Familia::IdentifierMismatchError instead of changing the object's identity" above. refresh! now sends only HGETALL.

A failed Horreum#refresh! leaves the object as it was

If a field setter raises while refresh! assigns the stored values, refresh! now puts the object back as it was before re-raising: field values, transient fields and dirty tracking. An example is Familia::EncryptionError for an encrypted field whose stored envelope names an algorithm that is not available. It used to leave the fields before the failing one assigned, transient fields reset, and the assigned fields marked dirty.