Module: Familia::Horreum::ManagementMethods

Includes:
AuditMethods, RelatedFieldsManagement, RepairMethods
Defined in:
lib/familia/horreum/management.rb

Overview

ManagementMethods - Class-level methods for Horreum model management

This module is extended into classes that include Familia::Horreum, providing class methods for database operations and object management (e.g., Customer.create, Customer.find_by_id)

Key features:

  • Includes RelatedFieldsManagement for DataType field handling
  • Includes AuditMethods for proactive consistency detection
  • Includes RepairMethods for repair and rebuild operations
  • Provides utility methods for working with Database objects

Constant Summary

Constants included from AuditMethods

AuditMethods::PARTICIPATION_KEY_TYPES

Instance Method Summary collapse

Methods included from RepairMethods

#rebuild_instances, #repair_all!, #repair_indexes!, #repair_instances!, #repair_multi_indexes!, #repair_participations!, #repair_related_fields!, #scan_keys

Methods included from AuditMethods

#audit_cross_references, #audit_instances, #audit_multi_indexes, #audit_participations, #audit_related_fields, #audit_unique_indexes, #health_check

Methods included from RelatedFieldsManagement

#attach_class_related_field, #attach_instance_related_field, #configure_related_field

Instance Method Details

#all(suffix = nil) ⇒ Array<Familia::Horreum>

Loads every object of this class whose key ends in +suffix+.

This method uses the KEYS command, which blocks Redis while it scans every key in the database, so like #keys_count it is not meant for production use.

Examples:

User.all  # Loads the objects of every key matching user:*:object

Parameters:

  • suffix (String, Symbol, nil) (defaults to: nil) —

    The literal key suffix (default: class suffix). Unlike the #find_keys argument it is not a glob: it is escaped like the class prefix and delimiter (see #dbkey_pattern), because every matching key is loaded as an object hash.

Returns:

  • (Array<Familia::Horreum>) —

    The loaded objects. Keys that cannot be loaded are left out, and so are matching keys that do not hold a hash (see OBJECT_KEY_TYPE).



812
813
814
815
816
817
# File 'lib/familia/horreum/management.rb', line 812

def all(suffix = nil)
  Familia.assert_replies_available!("#{self}.all")
  suffix ||= self.suffix
  # objects that could not be parsed will be nil
  object_keys(dbclient.keys(dbkey_pattern('*', suffix))).filter_map { |k| find_by_key(k) }
end

#any? ⇒ Boolean, Redis::Future

Note:

For authoritative check, use #scan_any? (production-safe) or #keys_any? (blocking)

Checks if any tracked instances exist (fast, from instances sorted set).

This method provides O(1) performance by querying the instances sorted set. However, objects deleted outside Familia may leave stale entries.

Examples:

User.create(email: 'test@example.com')
User.any?  #=> true

Returns:

  • (Boolean, Redis::Future) —

    true if instances sorted set is non-empty. Inside a transaction or pipeline, the ZCARD Future.

See Also:



926
927
928
# File 'lib/familia/horreum/management.rb', line 926

def any?
  Familia.positive?(count)
end

#build {|instance| ... } ⇒ Horreum

Builds, populates, and atomically persists a new instance in one step.

This is a factory wrapper around Horreum#atomic_write for the common case of "create an object, set up its collections, and save -- all at once". The block receives the freshly-built (but not-yet-persisted) instance. Scalar assignments and collection mutations made inside the block are all committed in a single MULTI/EXEC when the block exits:

  • Scalar setters (+u.name = ...+) stay in memory until the implicit save queues the HMSET inside the transaction.
  • Collection mutations (+u.tags.add(...)+) auto-route into the open transaction because +DataType#dbclient+ honours +Fiber[:familia_transaction]+.

Nothing reaches the database until the block exits, so a factory no longer has to choose between sequencing +save+ before collection writes or reaching for +atomic_write+ directly.

Persistence semantics

+build+ has create-only semantics: it raises RecordExistsError if an object with the same identifier already exists. This follows the principle of least astonishment -- a factory helper should not silently overwrite existing records. Use Persistence#save or Persistence#save_with_collections when you explicitly want overwrite/upsert behaviour.

Concurrency: both paths use a WATCH + MULTI/EXEC optimistic lock on a single connection for race-safe duplicate detection (not a server-side atomic check). Without a block, +build+ delegates to Persistence#save_if_not_exists!. With a block, +atomic_write+ is called with +watch_keys:+ and +pre_check:+ so the existence check runs between WATCH and MULTI -- if the key is created by another client in that window, Redis aborts the transaction and the method retries with exponential backoff (up to 3 attempts). See issue #288.

Without a block

When called without a block there are no collection operations to fold in, so +build+ uses +save_if_not_exists!+ and returns the instance.

Positional and keyword arguments are forwarded to new. The block is NOT forwarded to the constructor -- it is invoked here, after building, with the new instance.

Examples:

Factory/fixture creation with collections (issue #279)

user = User.build(email: 'alice@example.com') do |u|
  u.tags.add('admin')
  u.sessions.push('abc123')
end
# HMSET + SADD + RPUSH all fire in one MULTI/EXEC at block exit

Without a block (plain save)

user = User.build(email: 'bob@example.com')

Yields:

  • (instance) —

    The newly built instance, for scalar/collection setup.

Yield Parameters:

  • instance (Horreum) —

    The not-yet-persisted instance.

Returns:

  • (Horreum) —

    The built and persisted instance.

Raises:

See Also:



178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
# File 'lib/familia/horreum/management.rb', line 178

def build(*, **)
  # Forward only positional/keyword args to the constructor; the block is
  # a post-build callback, so it must not leak into new/initialize.
  instance = new(*, **)

  if block_given?
    instance.atomic_write(
      watch_keys: [instance.dbkey],
      pre_check: -> { raise Familia::RecordExistsError, instance.dbkey if instance.exists? }
    ) { yield instance }
  else
    # No block means no collection ops to fold in, so we can use the
    # WATCH-guarded save_if_not_exists! directly — race-safe.
    instance.save_if_not_exists!
  end

  instance
end

#cleanup_stale_instance_entry(objkey) ⇒ void

This method returns an undefined value.

Removes a stale entry from the instances sorted set.

Call this explicitly when you detect that an object no longer exists and want to prune its ghost entry from the instances timeline. Finder methods (find_by_dbkey, find_by_id, load) are read-only and will not call this automatically.

Parameters:

  • objkey (String) —

    The full database key (prefix:identifier:suffix)



335
336
337
338
339
340
341
342
343
344
345
# File 'lib/familia/horreum/management.rb', line 335

def cleanup_stale_instance_entry(objkey)
  return unless respond_to?(:instances)

  # Key format is prefix:identifier:suffix. Use extract_identifier_from_key
  # to correctly handle compound identifiers containing the delimiter.
  identifier = extract_identifier_from_key(objkey)
  return if identifier.nil? || identifier.empty?

  instances.remove(identifier)
  Familia.debug "[cleanup_stale_instance_entry] Removed stale entry: #{identifier}"
end

#config_name ⇒ String

Converts the class name into a string that can be used to look up configuration values. This is particularly useful when mapping familia models with specific database numbers in the configuration.

Familia::Horreum::DefinitionMethods#config_name

Examples:

V2::Session.config_name => 'session'

Returns:

  • (String) —

    The underscored class name as a string



225
226
227
228
229
# File 'lib/familia/horreum/management.rb', line 225

def config_name
  return nil if name.nil?

  name.demodularize.snake_case
end

#count ⇒ Integer, Redis::Future Also known as: size, length

Note:

For authoritative count, use #scan_count (production-safe) or #keys_count (blocking)

Returns the number of tracked instances (fast, from instances sorted set).

This method provides O(1) performance by querying the instances sorted set, which is automatically maintained when objects are created/destroyed through Familia. However, objects deleted outside Familia (e.g., direct Redis commands) may leave stale entries.

Examples:

User.create(email: 'test@example.com')
User.count  #=> 1

Returns:

  • (Integer, Redis::Future) —

    Number of instances in the instances sorted set. Inside a transaction or pipeline, the ZCARD Future.

See Also:



838
839
840
# File 'lib/familia/horreum/management.rb', line 838

def count
  instances.count
end

#create! {|hobj| ... } ⇒ Object

Note:

The behavior of this method depends on the implementation of #new,

exists?, and #save in the class and its superclasses.

Creates and persists a new instance of the class.

This method serves as a factory method for creating and persisting new instances of the class. It combines object instantiation, existence checking, and persistence in a single operation.

The method is flexible in accepting both positional and keyword arguments:

  • Positional arguments (*args) are passed directly to the constructor.
  • Keyword arguments (**kwargs) are passed as a hash to the constructor.

After instantiation, the method checks if an object with the same identifier already exists. If it does, a Familia::RecordExistsError exception is raised to prevent overwriting existing data.

Concurrency: the duplicate check is race-safe via optimistic locking. It routes through Persistence#save_if_not_exists!, which uses WATCH + MULTI/EXEC on a single connection to abort if the key appears between the check and the write. This is an effective optimistic lock, though not a server-side atomic check (e.g. Lua). See Persistence#save_if_not_exists!.

Finally, the method saves the new instance returns it.

Examples:

Creating an object with keyword arguments

User.create(name: "John", age: 30)

Creating an object with positional and keyword arguments (not recommended)

Product.create("SKU123", name: "Widget", price: 9.99)

Post-creation callback

User.create!(email: "alice@example.com") do |user|
  user.sessions.push(SecureRandom.uuid)
  AuditLog.record(:user_created, user.identifier)
end

Parameters:

  • args (Array) —

    Variable number of positional arguments to be passed to the constructor.

  • kwargs (Hash) —

    Keyword arguments to be passed to the constructor.

Yields:

  • (hobj) —

    Yields the persisted instance after a successful save. The block is skipped entirely if +save_if_not_exists!+ raises (e.g. RecordExistsError), so code inside the block can safely assume the object exists in the database.

Yield Parameters:

  • hobj (Horreum) —

    The newly created and persisted instance.

Yield Returns:

  • (void) —

    The block's return value is ignored; +create!+ always returns the created instance.

Returns:

  • (Object) —

    The newly created and persisted instance.

Raises:

See Also:



94
95
96
97
98
99
100
101
102
103
104
105
# File 'lib/familia/horreum/management.rb', line 94

def create!(...)
  hobj = new(...)
  # Race-safe duplicate guard: WATCH + MULTI/EXEC optimistic lock on one
  # connection (not a server-side atomic check).
  hobj.save_if_not_exists!

  # If a block is given, yield the created object
  # This allows for additional operations on successful creation
  yield hobj if block_given?

  hobj
end

#dbkey(identifier, suffix = self.suffix) ⇒ Object



786
787
788
789
790
791
792
793
# File 'lib/familia/horreum/management.rb', line 786

def dbkey(identifier, suffix = self.suffix)
  if identifier.to_s.empty?
    raise NoIdentifier, "#{self} requires non-empty identifier, got: #{identifier.inspect}"
  end

  identifier &&= identifier.to_s
  Familia.dbkey(prefix, identifier, suffix)
end

#dbkey_pattern(identifier_glob = '*', key_suffix = suffix) ⇒ String

Returns a KEYS or SCAN MATCH pattern for this class's keys.

+identifier_glob+ is used as given, so it may contain glob wildcards. The class prefix, the delimiter and +key_suffix+ are escaped with Familia.escape_glob so they match only themselves: a class whose prefix is "app[1]" does not match the keys of a class whose prefix is "app1".

Examples:

User.dbkey_pattern               #=> "user:*:object"
User.dbkey_pattern('a*')         #=> "user:a*:object"
User.dbkey_pattern('*', :tags)   #=> "user:*:tags"

Parameters:

  • identifier_glob (String) (defaults to: '*') —

    Glob for the identifier part (default: '*')

  • key_suffix (String, Symbol, nil) (defaults to: suffix) —

    Literal suffix (default: class suffix). nil leaves the suffix out, as it does for #dbkey.

Returns:

  • (String) —

    The pattern (e.g., "customer:*:object")

Raises:



742
743
744
745
746
747
748
749
750
# File 'lib/familia/horreum/management.rb', line 742

def dbkey_pattern(identifier_glob = '*', key_suffix = suffix)
  if identifier_glob.to_s.empty?
    raise NoIdentifier, "#{self} requires non-empty identifier pattern, got: #{identifier_glob.inspect}"
  end

  parts = [Familia.escape_glob(prefix), identifier_glob.to_s]
  parts << Familia.escape_glob(key_suffix) unless key_suffix.nil?
  parts.join(Familia.escape_glob(Familia.delim))
end

#destroy!(identifier, suffix = nil) ⇒ Boolean

Destroys an object in Database with the given identifier.

Deletes the main hash key, all related fields, and removes the identifier from the +instances+ sorted set. This is the class-level counterpart to the instance method of the same name.

This method is part of Familia's high-level object lifecycle management. While delete! operates directly on dbkeys, destroy! operates at the object level and is used for ORM-style operations. Use destroy! when removing complete objects from the system, and delete! when working directly with dbkeys.

Examples:

User.destroy!(123)  # Removes user:123:object from Valkey/Redis

Parameters:

  • identifier (String, Integer) —

    The unique identifier for the object to destroy.

  • suffix (Symbol, nil) (defaults to: nil) —

    The suffix to use in the dbkey (default: class suffix).

Returns:

  • (Boolean) —

    true if the object was successfully destroyed, false otherwise.

Raises:



614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
# File 'lib/familia/horreum/management.rb', line 614

def destroy!(identifier, suffix = nil)
  # Loads the record first (to clean its class indexes), which needs replies.
  Familia.assert_replies_available!("#{self}.destroy!")
  suffix ||= self.suffix
  raise Familia::NoIdentifier, "#{self} requires non-empty identifier" if identifier.to_s.empty?

  objkey = dbkey identifier, suffix

  # Load the object BEFORE the transaction so its field values are available
  # for class-level index cleanup. Removing a unique-index entry needs the
  # field value (e.g. email) to HDEL the right mapping, and reads cannot run
  # inside MULTI/EXEC. If the hash is already gone (nil) we skip index
  # cleanup -- without the field values the entries to remove are unknowable.
  # This mirrors the instance #destroy! (which calls remove_from_class_indexes!)
  # so both destroy paths leave indexes consistent (see issue #241).
  loaded = find_by_dbkey(objkey, check_exists: false)

  # Execute all deletion operations within a transaction
  transaction do |conn|
    # Clean up related fields first to avoid orphaned keys
    if relations?
      fields = related_fields_snapshot
      Familia.trace :DESTROY_RELATIONS!, nil, "#{self} has relations: #{fields.keys}" if Familia.debug?

      # Create a temporary instance to access related fields.
      # Pass identifier in constructor so init() sees it and can set dependent fields.
      identifier_field_name = self.identifier_field
      temp_instance = identifier_field_name ? new(identifier_field_name => identifier.to_s) : new

      fields.each do |name, _definition|
        obj = temp_instance.send(name)
        if Familia.debug?
          Familia.trace :DESTROY_RELATION!, name,
                        "Deleting related field #{name} (#{Familia.loggable_text(obj.dbkey)})"
        end
        conn.del(obj.dbkey)
      end
    end

    # Delete the main object key
    ret = conn.del(objkey)
    Familia.trace :DESTROY!, nil, "#{objkey} #{ret.inspect}" if Familia.debug?

    # Clean up class-level index entries (same as instance #destroy!).
    # Routes its HDELs into this open transaction via Fiber[:familia_transaction].
    loaded&.send(:remove_from_class_indexes!)

    # Remove from instances collection to avoid ghost entries
    instances.remove(identifier) if respond_to?(:instances)
  end
end

#exists?(identifier, suffix = nil) ⇒ Boolean, Redis::Future

Checks if an object with the given identifier exists in the database.

This method constructs the full dbkey using the provided identifier and suffix, then checks if the key exists in the database.

Examples:

User.exists?(123)  # Returns true if user:123:object exists in Valkey/Redis

Parameters:

  • identifier (String, Integer) —

    The unique identifier for the object.

  • suffix (Symbol, nil) (defaults to: nil) —

    The suffix to use in the dbkey (default: class suffix).

Returns:

  • (Boolean, Redis::Future) —

    true if the object exists, false otherwise. Inside a transaction or pipeline, the EXISTS Future (resolves to the key count).

Raises:



578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
# File 'lib/familia/horreum/management.rb', line 578

def exists?(identifier, suffix = nil)
  raise NoIdentifier, 'Empty identifier' if identifier.to_s.empty?

  suffix ||= self.suffix

  objkey = dbkey identifier, suffix

  ret = dbclient.exists objkey
  Familia.trace :EXISTS, nil, "#{objkey} #{ret.inspect}" if Familia.debug?

  # Handle Redis::Future objects during transactions
  return ret if ret.is_a?(Redis::Future)

  ret.positive? # differs from Valkey API but I think it's okay bc `exists?` is a predicate method.
end

#extract_identifier_from_key(key, key_suffix = suffix) ⇒ String?

Extracts the identifier from a full Redis key by stripping the known prefix and suffix.

This is safe for compound identifiers that contain the delimiter character (e.g., "mymodel:foo:bar:object" where the identifier is "foo:bar"). A naive split on the delimiter would truncate these.

The key is compared and sliced as bytes. The client returns a key that is not valid UTF-8 as a binary String, and comparing such a key with a prefix that holds non-ASCII characters as Strings raises Encoding::CompatibilityError. The identifier keeps the key's encoding, as the members of the instances sorted set do, so the identifiers of one record compare equal.

Examples:

User.extract_identifier_from_key("user:alice:object")       #=> "alice"
User.extract_identifier_from_key("user:foo:bar:object")    #=> "foo:bar"

Parameters:

  • key (String) —

    Full Redis key (e.g., "user:alice:object")

  • key_suffix (String) (defaults to: suffix) —

    The suffix to strip (default: class suffix)

Returns:

  • (String, nil) —

    The extracted identifier, or nil if the key does not match the expected prefix/suffix structure



774
775
776
777
778
779
780
781
782
783
784
# File 'lib/familia/horreum/management.rb', line 774

def extract_identifier_from_key(key, key_suffix = suffix)
  d = Familia.delim
  pfx = "#{prefix}#{d}"
  sfx = "#{d}#{key_suffix}"
  bkey = key.b
  size = bkey.bytesize - pfx.bytesize - sfx.bytesize

  return nil unless size >= 0 && bkey.start_with?(pfx.b) && bkey.end_with?(sfx.b)

  bkey.byteslice(pfx.bytesize, size).force_encoding(key.encoding)
end

#familia_name ⇒ Object

Familia::Horreum::DefinitionMethods#familia_name

Examples:

V2::Session.config_name => 'Session'



235
236
237
238
239
# File 'lib/familia/horreum/management.rb', line 235

def familia_name
  return nil if name.nil?

  name.demodularize
end

#find_by_dbkey(objkey, check_exists: true) ⇒ Object? Also known as: find_by_key

Note:

This method is read-only. Ghost entries (identifiers lingering in +instances+ after their hash key expires) are not cleaned up here. Use +cleanup_stale_instance_entry+ explicitly when cleanup is desired.

Note:

When check_exists: false, HGETALL on non-existent keys returns {} which we detect and return nil (not an empty object instance).

Retrieves and instantiates an object from Database using the full object key.

This method can operate in two modes:

Safe mode (check_exists: true, default):

  1. First checks if the key exists with EXISTS command
  2. Returns nil immediately if key doesn't exist
  3. If exists, retrieves data with HGETALL and instantiates object
  4. Best for: Single object lookups, defensive code
  5. Commands: 2 per object (EXISTS + HGETALL)

Optimized mode (check_exists: false):

  1. Directly calls HGETALL without EXISTS check
  2. Returns nil if HGETALL returns empty hash (key doesn't exist)
  3. Otherwise instantiates object with returned data
  4. Best for: Bulk operations, performance-critical paths, when keys likely exist
  5. Commands: 1 per object (HGETALL only)
  6. Reduction: 50% fewer Redis commands

Examples:

Safe mode (default)

User.find_by_key("user:123")  # 2 commands: EXISTS + HGETALL

Optimized mode (skip existence check)

User.find_by_key("user:123", check_exists: false)  # 1 command: HGETALL

Parameters:

  • objkey (String) —

    The full dbkey for the object.

  • check_exists (Boolean) (defaults to: true) —

    Whether to check key existence before HGETALL (default: true). When false, skips EXISTS check for better performance but still returns nil for non-existent keys (detected via empty hash).

Returns:

  • (Object, nil) —

    An instance of the class if the key exists, nil otherwise.

Raises:

  • (ArgumentError) —

    If the provided key is empty.

  • (Familia::OperationModeError) —

    inside a transaction or pipeline, where the replies needed to decide existence and build the object are not available until the block completes.



285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
# File 'lib/familia/horreum/management.rb', line 285

def find_by_dbkey(objkey, check_exists: true)
  Familia.assert_replies_available!("#{self}.find_by_dbkey")
  raise ArgumentError, 'Empty key' if objkey.to_s.empty?

  if check_exists
    # Safe mode: Check existence first (original behavior)
    # We use a lower-level method here b/c we're working with the
    # full key and not just the identifier.
    does_exist = Familia.positive?(dbclient.exists(objkey))

    if Familia.debug?
      Familia.debug "[find_by_key] #{self} from key #{Familia.loggable_text(objkey)} (exists: #{does_exist})"
      Familia.trace :FIND_BY_DBKEY_KEY, nil, objkey
    end

    # This is the reason for calling exists first. We want to definitively
    # and without any ambiguity know if the object exists in the database. If it
    # doesn't, we return nil. If it does, we proceed to load the object.
    # Otherwise, hgetall will return an empty hash, which will be passed to
    # the constructor, which will then be annoying to debug.
    return nil unless does_exist
  else
    # Optimized mode: Skip existence check
    if Familia.debug?
      Familia.debug "[find_by_key] #{self} from key #{Familia.loggable_text(objkey)} (check_exists: false)"
      Familia.trace :FIND_BY_DBKEY_KEY, nil, objkey
    end
  end

  obj = dbclient.hgetall(objkey) # horreum objects are persisted as database hashes
  Familia.trace :FIND_BY_DBKEY_INSPECT, nil, "#{Familia.loggable_text(objkey)}: #{obj.inspect}" if Familia.debug?

  # Always check for empty hash to handle race conditions where the key
  # expires between EXISTS check and HGETALL (when check_exists: true),
  # or simply doesn't exist (when check_exists: false).
  return nil if obj.empty?

  # Create instance and deserialize fields using shared helper method
  instantiate_from_hash(obj, dbkey: objkey)
end

#find_by_identifier(identifier, suffix: nil, check_exists: true) ⇒ Object? Also known as: find_by_id

Retrieves and instantiates an object from Database using its identifier.

Returns a fully-hydrated instance if the key exists, or +nil+ if it does not. This method never returns a "shell" object with empty fields. If you need an in-memory placeholder without loading from the database, use +new(identifier)+ instead -- but be aware that such an object has no persisted field values and will overwrite existing data if saved.

This method constructs the full dbkey using the provided identifier and suffix, then delegates to find_by_key for the actual retrieval and instantiation.

It's a higher-level method that abstracts away the key construction, making it easier to retrieve objects when you only have their identifier.

Examples:

Safe mode (default)

user = User.find_by_id(123)  # 2 commands: EXISTS + HGETALL
user  # => #<User ...> or nil

Optimized mode

User.find_by_id(123, check_exists: false)  # 1 command: HGETALL

Custom suffix

Session.find_by_id('abc', suffix: :session)

Common pitfall: new() vs load()

User.load('nonexistent')  # => nil (key does not exist)
User.new('nonexistent')   # => #<User> (in-memory shell, no DB data)

Parameters:

  • identifier (String, Integer) —

    The unique identifier for the object.

  • suffix (Symbol, nil) (defaults to: nil) —

    The suffix to use in the dbkey (default: class suffix). Keyword parameter for consistency with check_exists.

  • check_exists (Boolean) (defaults to: true) —

    Whether to check key existence before HGETALL (default: true). See find_by_dbkey for details.

Returns:

  • (Object, nil) —

    An instance of the class if found, +nil+ if the key does not exist in the database.

Raises:

See Also:



392
393
394
395
396
397
398
399
400
401
402
403
404
# File 'lib/familia/horreum/management.rb', line 392

def find_by_identifier(identifier, suffix: nil, check_exists: true)
  Familia.assert_replies_available!("#{self}.find_by_identifier")
  suffix ||= self.suffix
  return nil if identifier.to_s.empty?

  objkey = dbkey(identifier, suffix)

  if Familia.debug?
    Familia.debug "[find_by_id] #{self} from key #{Familia.loggable_text(objkey)})"
    Familia.trace :FIND_BY_ID, nil, objkey
  end
  find_by_dbkey objkey, check_exists: check_exists
end

#find_keys(suffix = '*') ⇒ Array<String>

Finds all keys in Database matching the given suffix pattern.

Examples:

User.find_keys            # Returns all keys matching user:*:*
User.find_keys('active')  # Returns all keys matching user:*:active

Parameters:

  • suffix (String) (defaults to: '*') —

    The suffix pattern to match (default: '*'). It is used as given, so it may contain glob wildcards. The class prefix and the delimiter are escaped (see #dbkey_pattern).

Returns:

  • (Array<String>) —

    An array of matching dbkeys.



677
678
679
680
681
# File 'lib/familia/horreum/management.rb', line 677

def find_keys(suffix = '*')
  delim = Familia.escape_glob(Familia.delim)
  pattern = [Familia.escape_glob(prefix), '*', suffix].compact.join(delim)
  dbclient.keys(pattern) || []
end

#in_instances?(identifier) ⇒ Boolean, Redis::Future

Checks whether the given identifier appears in the +instances+ sorted set.

This is a fast O(log N) ZRANK lookup (SortedSet#member?). It does NOT verify that the underlying hash key still exists in the database -- use #exists? for that. A true result means the object was persisted through Familia at some point and has not been removed from instances since.

Examples:

Quick instances check without hitting HGETALL

User.in_instances?('cust_abc123')  # => true

Parameters:

  • identifier (String, Integer) —

    The unique identifier to check.

Returns:

  • (Boolean, Redis::Future) —

    true if the identifier is present in the instances sorted set, false otherwise. Inside a transaction or pipeline, the ZRANK Future (resolves to the rank, or nil when absent; the Future itself is always truthy).

See Also:



558
559
560
561
562
# File 'lib/familia/horreum/management.rb', line 558

def in_instances?(identifier)
  return false if identifier.to_s.empty?

  instances.member?(identifier)
end

#instantiate_from_hash(obj_hash, dbkey: nil) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Note:

This method:

  1. Allocates a new instance without calling initialize
  2. Initializes related DataType fields
  3. Deserializes and assigns field values from the hash

Instantiates an object from a hash of field values.

This is an internal helper method used by find_by_dbkey, load_multi, and load_multi_by_keys to eliminate code duplication. Not intended for direct use.

Parameters:

  • obj_hash (Hash) —

    Hash of field names to serialized values from Redis

  • dbkey (String, nil) (defaults to: nil) —

    the key obj_hash was read from, named in the log entry for a value that is not JSON

Returns:

  • (Object) —

    Instantiated object with deserialized fields



1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
# File 'lib/familia/horreum/management.rb', line 1007

def instantiate_from_hash(obj_hash, dbkey: nil)
  instance = allocate
  instance.instance_variable_set(:@dirty_fields, Concurrent::Map.new)
  instance.instance_variable_set(:@warned_dirty_signatures, Concurrent::Map.new)
  instance.send(:initialize_relatives)
  values = instance.send(:deserialize_stored_fields, obj_hash, dbkey: dbkey)
  instance.send(:initialize_with_keyword_args, **values)
  # Object was just loaded from Redis, so it matches DB state exactly.
  # Clear dirty flags set during field assignment above, as
  # Horreum#initialize and Horreum#refresh! also do.
  #
  # refresh! assigns stored values to an existing object and is meant to
  # leave it in the state this method produces: unstored fields nil, and
  # setters that see nil as the old value. It gets there differently. It
  # deserializes before clearing the fields, then assigns with
  # initialize_with_keyword_args, and restores the object if an
  # assignment raises. A change to how stored values are assigned here
  # likely needs the same change there.
  instance.send(:clear_dirty!)
  instance
end

#key_prefix ⇒ String

Returns the key prefix for this class including the delimiter.

Centralizes key prefix generation to prevent bugs from manual string interpolation across the codebase.

Examples:

User.key_prefix  #=> "user:"

Returns:

  • (String) —

    The prefix with delimiter (e.g., "customer:")



704
705
706
# File 'lib/familia/horreum/management.rb', line 704

def key_prefix
  "#{prefix}#{Familia.delim}"
end

#keys_any?(filter = '*') ⇒ Boolean

Note:

For production-safe authoritative check, use #scan_any?

Checks if any objects exist using blocking KEYS command (production-dangerous).

⚠️ WARNING: This method uses the KEYS command which blocks Redis during execution. It scans ALL keys in the database and should NEVER be used in production. #scan_any? uses SCAN with a TYPE filter instead and is the production-safe choice.

Examples:

User.keys_any?       #=> true  (any User objects)
User.keys_any?('a*') #=> true  (Users with IDs starting with 'a')

Parameters:

  • filter (String) (defaults to: '*') —

    Glob for the identifier part (default: '*'). The class prefix and suffix are escaped; see #dbkey_pattern.

Returns:

  • (Boolean) —

    true if a matching key that holds a hash exists (see OBJECT_KEY_TYPE)

Raises:

See Also:



951
952
953
# File 'lib/familia/horreum/management.rb', line 951

def keys_any?(filter = '*')
  Familia.positive?(keys_count(filter))
end

#keys_count(filter = '*') ⇒ Integer

Note:

For production-safe authoritative count, use #scan_count

Returns authoritative count using blocking KEYS command (production-dangerous).

⚠️ WARNING: This method uses the KEYS command which blocks Redis during execution. It scans ALL keys in the database and should NEVER be used in production. #scan_count uses SCAN with a TYPE filter instead and is the production-safe choice.

Examples:

User.keys_count       #=> 1  (all User objects)
User.keys_count('a*') #=> 1  (Users with IDs starting with 'a')

Parameters:

  • filter (String) (defaults to: '*') —

    Glob for the identifier part (default: '*'). The class prefix and suffix are escaped; see #dbkey_pattern.

Returns:

  • (Integer) —

    Number of matching keys that hold a hash (see OBJECT_KEY_TYPE)

Raises:

  • (Familia::OperationModeError) —

    inside a transaction or pipeline, where the KEYS reply the type filter needs is not available until the block completes

See Also:



866
867
868
869
870
# File 'lib/familia/horreum/management.rb', line 866

def keys_count(filter = '*')
  Familia.assert_replies_available!("#{self}.keys_count")

  object_keys(dbclient.keys(dbkey_pattern(filter)).compact).size
end

#load_multi(identifiers, suffix = nil) ⇒ Array<Object> Also known as: load_batch

Note:

Returns nil for non-existent keys (maintains same contract as find_by_id)

Note:

Objects are returned in the same order as input identifiers

Note:

Empty/nil identifiers are skipped and return nil in result array

Loads multiple objects by their identifiers using pipelined HGETALL commands.

This method provides significant performance improvements for bulk loading by:

  1. Batching all HGETALL commands into a single Redis pipeline
  2. Eliminating network round-trip overhead
  3. Skipping individual EXISTS checks (like check_exists: false)

Performance characteristics:

  • Standard approach: N objects × 2 commands (EXISTS + HGETALL) = 2N round trips
  • check_exists: false: N objects × 1 command (HGETALL) = N round trips
  • load_multi: 1 pipeline with N commands = 1 round trip
  • Improvement: Up to 2N× faster for bulk operations

Examples:

Load multiple users efficiently

users = User.load_multi([123, 456, 789])
# 1 pipeline with 3 HGETALL commands instead of 6 individual commands

Filter out nils

existing_users = User.load_multi(ids).compact

Parameters:

  • identifiers (Array<String, Integer>) —

    Array of identifiers to load

  • suffix (Symbol, nil) (defaults to: nil) —

    The suffix to use in dbkeys (default: class suffix)

Returns:

  • (Array<Object>) —

    Array of instantiated objects (nils for non-existent)

Raises:

  • (Familia::OperationModeError) —

    inside a transaction or pipeline, where the HGETALL replies are not available until the block completes



439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
# File 'lib/familia/horreum/management.rb', line 439

def load_multi(identifiers, suffix = nil)
  Familia.assert_replies_available!("#{self}.load_multi")
  suffix ||= self.suffix
  return [] if identifiers.empty?

  # Build list of valid keys and track their original positions
  valid_keys = []
  valid_positions = []

  identifiers.each_with_index do |identifier, idx|
    next if identifier.to_s.empty?

    valid_keys << dbkey(identifier, suffix)
    valid_positions << idx
  end

  Familia.trace :LOAD_MULTI, nil, "Loading #{identifiers.size} objects" if Familia.debug?

  # Pipeline all HGETALL commands
  multi_result = pipelined do |pipeline|
    valid_keys.each do |objkey|
      pipeline.hgetall(objkey)
    end
  end

  # Extract results array from MultiResult
  results = multi_result.results

  # Map results back to original positions
  objects = Array.new(identifiers.size)
  valid_positions.each_with_index do |pos, result_idx|
    obj_hash = results[result_idx]

    # Skip empty hashes (non-existent keys)
    next if obj_hash.nil? || obj_hash.empty?

    # Instantiate object using shared helper method
    objects[pos] = instantiate_from_hash(obj_hash, dbkey: valid_keys[result_idx])
  end

  objects
end

#load_multi_by_keys(objkeys) ⇒ Array<Object>

Note:

Returns nil for empty/nil keys, maintaining position alignment with input array

Loads multiple objects by their full dbkeys using pipelined HGETALL commands.

This is a lower-level variant of load_multi that works directly with dbkeys instead of identifiers. Useful when you already have the full keys.

Examples:

Load objects by full keys

keys = ["user:123:object", "user:456:object"]
users = User.load_multi_by_keys(keys)

Parameters:

  • objkeys (Array<String>) —

    Array of full dbkeys to load

Returns:

  • (Array<Object>) —

    Array of instantiated objects (nils for non-existent)

Raises:

See Also:



500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
# File 'lib/familia/horreum/management.rb', line 500

def load_multi_by_keys(objkeys)
  Familia.assert_replies_available!("#{self}.load_multi_by_keys")
  return [] if objkeys.empty?

  Familia.trace :LOAD_MULTI_BY_KEYS, nil, "Loading #{objkeys.size} objects" if Familia.debug?

  # Track which positions have valid keys to maintain result array alignment
  valid_positions = []
  objkeys.each_with_index do |objkey, idx|
    valid_positions << idx unless objkey.to_s.empty?
  end

  # Pipeline all HGETALL commands for valid keys
  multi_result = pipelined do |pipeline|
    objkeys.each do |objkey|
      next if objkey.to_s.empty?
      pipeline.hgetall(objkey)
    end
  end

  # Extract results array from MultiResult
  results = multi_result.results

  # Map results back to original positions
  objects = Array.new(objkeys.size)
  valid_positions.each_with_index do |pos, result_idx|
    obj_hash = results[result_idx]

    # Skip empty hashes (non-existent keys)
    next if obj_hash.nil? || obj_hash.empty?

    # Instantiate object using shared helper method
    objects[pos] = instantiate_from_hash(obj_hash, dbkey: objkeys[pos])
  end

  objects
end

#multiget ⇒ Array, Redis::Future

Reads each identifier's key with MGET and parses the stored JSON.

Returns:

  • (Array, Redis::Future) —

    the parsed values, skipping missing keys. Inside a transaction or pipeline, the MGET Future (resolves to the raw values).



202
203
204
205
206
# File 'lib/familia/horreum/management.rb', line 202

def multiget(...)
  Familia.transform_reply(rawmultiget(...)) do |values|
    values.filter_map { |json| Familia::JsonSerializer.parse(json) }
  end
end

#rawmultiget(*hids) ⇒ Object



208
209
210
211
212
213
214
# File 'lib/familia/horreum/management.rb', line 208

def rawmultiget(*hids)
  hids.collect! { |hobjid| dbkey(hobjid) }
  return [] if hids.compact.empty?

  Familia.trace :MULTIGET, nil, "#{hids.size}: #{hids}" if Familia.debug?
  dbclient.mget(*hids)
end

#scan_any?(filter = '*') ⇒ Boolean Also known as: any!

Note:

For fast check (potentially stale), use #any?

Checks if any objects exist using non-blocking SCAN command (production-safe).

This method uses cursor-based SCAN iteration to check for matching keys without blocking Redis. Safe for production use and returns early on first match.

Examples:

User.scan_any?       #=> true  (any User objects)
User.scan_any?('a*') #=> true  (Users with IDs starting with 'a')

Parameters:

  • filter (String) (defaults to: '*') —

    Glob for the identifier part (default: '*'). The class prefix and suffix are escaped; see #dbkey_pattern.

Returns:

  • (Boolean) —

    true if a matching key that holds a hash exists (see OBJECT_KEY_TYPE)

Raises:

See Also:



975
976
977
978
979
980
981
982
983
984
985
986
987
988
# File 'lib/familia/horreum/management.rb', line 975

def scan_any?(filter = '*')
  Familia.assert_replies_available!("#{self}.scan_any?")

  pattern = dbkey_pattern(filter)
  cursor = "0"

  loop do
    cursor, keys = dbclient.scan(cursor, match: pattern, count: 100, type: OBJECT_KEY_TYPE)
    return true unless keys.empty?
    break if cursor == "0"
  end

  false
end

#scan_count(filter = '*') ⇒ Integer Also known as: count!

Note:

For fast count (potentially stale), use #count

Returns authoritative count using non-blocking SCAN command (production-safe).

This method uses cursor-based SCAN iteration to count matching keys without blocking Redis. Safe for production use as it processes keys in chunks.

Examples:

User.scan_count       #=> 1  (all User objects)
User.scan_count('a*') #=> 1  (Users with IDs starting with 'a')

Parameters:

  • filter (String) (defaults to: '*') —

    Glob for the identifier part (default: '*'). The class prefix and suffix are escaped; see #dbkey_pattern.

Returns:

  • (Integer) —

    Number of matching keys that hold a hash (see OBJECT_KEY_TYPE)

Raises:

See Also:



892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
# File 'lib/familia/horreum/management.rb', line 892

def scan_count(filter = '*')
  Familia.assert_replies_available!("#{self}.scan_count")

  pattern = dbkey_pattern(filter)
  count = 0
  cursor = "0"

  loop do
    cursor, keys = dbclient.scan(cursor, match: pattern, count: 1000, type: OBJECT_KEY_TYPE)
    count += keys.size
    break if cursor == "0"
  end

  count
end

#scan_pattern(match_suffix = suffix) ⇒ String

Returns the SCAN pattern for finding all objects of this class.

Centralizes SCAN pattern generation to ensure consistency across rebuild strategies and other key enumeration operations.

Examples:

User.scan_pattern           #=> "user:*:object"
User.scan_pattern('active') #=> "user:*:active"

Parameters:

  • match_suffix (String) (defaults to: suffix) —

    The literal suffix to match (default: class suffix). It is escaped like the prefix; see #dbkey_pattern.

Returns:

  • (String) —

    The SCAN pattern (e.g., "customer:*:object")



720
721
722
# File 'lib/familia/horreum/management.rb', line 720

def scan_pattern(match_suffix = suffix)
  dbkey_pattern('*', match_suffix)
end

#storage_inspect(identifier_or_key) ⇒ Hash{String => Hash}, ...

Decodes raw HGETALL output for debugging purposes.

When inspecting data from redis-cli, field values appear as raw JSON-encoded strings (e.g. +"\"UK\""+ for the string +"UK"+). This method retrieves the hash, deserializes each value, and returns a diagnostic hash showing the raw stored form, decoded Ruby value, and Ruby type for every field.

Accepts either an identifier (resolved via +dbkey+) or a full database key (detected by the presence of the class delimiter).

Examples:

Inspect a stored object by identifier

Customer.storage_inspect('cust_abc123')
# => {"email" => {raw: "\"test@example.com\"", decoded: "test@example.com", type: "String"},
#     "plan_id" => {raw: "42", decoded: 42, type: "Integer"}}

Inspect by full key

Customer.storage_inspect('customer:cust_abc123:object')

Parameters:

  • identifier_or_key (String) —

    An identifier or full database key

Returns:

  • (Hash{String => Hash}) —

    Diagnostic hash per field:

    • +:raw+ [String] The raw string stored in Redis
    • +:decoded+ [Object] The deserialized Ruby value
    • +:type+ [String] The Ruby class name of the decoded value
  • (nil) —

    If the key does not exist

  • (Redis::Future) —

    Inside a transaction or pipeline, the HGETALL Future (resolves to the raw field hash)

See Also:



1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
# File 'lib/familia/horreum/management.rb', line 1059

def storage_inspect(identifier_or_key)
  # Determine if this is a full key or an identifier
  objkey = if identifier_or_key.to_s.include?(Familia.delim)
    identifier_or_key.to_s
  else
    dbkey(identifier_or_key)
  end

  Familia.transform_reply(dbclient.hgetall(objkey)) do |raw_hash|
    next nil if raw_hash.empty?

    # Use a temporary instance for deserialization (needs serialize_value/deserialize_value)
    temp = allocate
    temp.instance_variable_set(:@dirty_fields, Concurrent::Map.new)
    temp.instance_variable_set(:@warned_dirty_signatures, Concurrent::Map.new)
    temp.send(:initialize_relatives)

    pass_dbkey = temp.send(:deserialize_value_takes_dbkey?)
    raw_hash.each_with_object({}) do |(field, raw_val), result|
      decoded = if pass_dbkey
        temp.send(:deserialize_value, raw_val, field_name: field.to_sym, dbkey: objkey)
      else
        temp.send(:deserialize_value, raw_val, field_name: field.to_sym)
      end
      result[field] = {
        raw: raw_val,
        decoded: decoded,
        type: decoded.class.name
      }
    end
  end
end