Class: Familia::Horreum

Inherits:
Object
  • Object
show all
Includes:
Base, Commands, Serialization, Settings, Utils
Defined in:
lib/familia/horreum.rb,
lib/familia/horreum/utils.rb,
lib/familia/horreum/commands.rb,
lib/familia/horreum/settings.rb,
lib/familia/horreum/class_methods.rb,
lib/familia/horreum/serialization.rb,
lib/familia/horreum/relations_management.rb

Overview

Familia::Horreum

Defined Under Namespace

Modules: ClassMethods, Commands, RelationsManagement, Serialization, Settings, Utils Classes: MultiResult

Class Attribute Summary collapse

Attributes included from Serialization

#redis

Attributes included from Settings

#dump_method, #load_method, #suffix

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Serialization

#apply_fields, #batch_update, #clear_fields!, #commit_fields, #deserialize_value, #destroy!, #refresh, #refresh!, #save, #serialize_value, #to_a, #to_h, #transaction

Methods included from Settings

#db, #db=, #opts, #redisdetails

Methods included from Commands

#decr, #decrby, #delete!, #exists?, #expire, #field_count, #hget, #hgetall, #hkeys, #hmset, #hset, #hstrlen, #hvals, #incr, #incrby, #incrbyfloat, #key?, #move, #prefix, #realttl, #redistype, #remove_field, #rename

Methods included from Utils

#join, #rediskey, #redisuri

Methods included from Base

add_feature, #generate_id, #update_expiration, #uuid

Constructor Details

#initialize(*args, **kwargs) ⇒ Horreum

Instance initialization This method sets up the object’s state, including Redis-related data.

Usage:

Session.new("abc123", "user456")                   # positional (brittle)
Session.new(sessid: "abc123", custid: "user456")   # hash (robust)
Session.new({sessid: "abc123", custid: "user456"}) # legacy hash (robust)



83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
 
# File 'lib/familia/horreum.rb', line 83

def initialize(*args, **kwargs)
  Familia.ld "[Horreum] Initializing #{self.class}"
  initialize_relatives

  # Automatically add a 'key' field if it's not already defined. This ensures
  # that every object horreum class has a unique identifier field. Ideally
  # this logic would live somewhere else b/c we only need to call it once
  # per class definition. Here it gets called every time an instance is
  # instantiated.
  unless self.class.fields.include?(:key)
    # Define the 'key' field for this class
    # This approach allows flexibility in how identifiers are generated
    # while ensuring each object has a consistent way to be referenced
    self.class.field :key
  end

  # Detect if first argument is a hash (legacy support)
  if args.size == 1 && args.first.is_a?(Hash) && kwargs.empty?
    kwargs = args.first
    args = []
  end

  # Initialize object with arguments using one of three strategies:
  #
  # 1. **Keyword Arguments** (Recommended): Order-independent field assignment
  #    Example: Customer.new(name: "John", email: "[email protected]")
  #    - Robust against field reordering
  #    - Self-documenting
  #    - Only sets provided fields
  #
  # 2. **Positional Arguments** (Legacy): Field assignment by definition order
  #    Example: Customer.new("[email protected]", "password123")
  #    - Brittle: breaks if field order changes
  #    - Compact syntax
  #    - Maps to fields in class definition order
  #
  # 3. **No Arguments**: Object created with all fields as nil
  #    - Minimal memory footprint in Redis
  #    - Fields set on-demand via accessors or save()
  #    - Avoids default value conflicts with nil-skipping serialization
  #
  # Note: We iterate over self.class.fields (not kwargs) to ensure only
  # defined fields are set, preventing typos from creating undefined attributes.
  #
  if kwargs.any?
    initialize_with_keyword_args(**kwargs)
  elsif args.any?
    initialize_with_positional_args(*args)
  else
    Familia.ld "[Horreum] #{self.class} initialized with no arguments"
    # Default values are intentionally NOT set here to:
    # - Maintain Redis memory efficiency (only store non-nil values)
    # - Avoid conflicts with nil-skipping serialization logic
    # - Preserve consistent exists? behavior (empty vs default-filled objects)
    # - Keep initialization lightweight for unused fields
  end

  # Implementing classes can define an init method to do any
  # additional initialization. Notice that this is called
  # after the fields are set.
  init if respond_to?(:init)
end

Class Attribute Details

.dump_method=(value) ⇒ Object (writeonly)

Sets the attribute dump_method

Parameters:

  • value —

    the value to set the attribute dump_method to.



58
59
60
 
# File 'lib/familia/horreum.rb', line 58

def dump_method=(value)
  @dump_method = value
end

.has_relations ⇒ Object (readonly)

Returns the value of attribute has_relations.



59
60
61
 
# File 'lib/familia/horreum.rb', line 59

def has_relations
  @has_relations
end

.load_method=(value) ⇒ Object (writeonly)

Sets the attribute load_method

Parameters:

  • value —

    the value to set the attribute load_method to.



58
59
60
 
# File 'lib/familia/horreum.rb', line 58

def load_method=(value)
  @load_method = value
end

.parent ⇒ Object

Returns the value of attribute parent.



57
58
59
 
# File 'lib/familia/horreum.rb', line 57

def parent
  @parent
end

.redis=(value) ⇒ Object (writeonly)

Sets the attribute redis

Parameters:

  • value —

    the value to set the attribute redis to.



58
59
60
 
# File 'lib/familia/horreum.rb', line 58

def redis=(value)
  @redis = value
end

.valid_command_return_values ⇒ Object

Returns the value of attribute valid_command_return_values.



32
33
34
 
# File 'lib/familia/horreum/serialization.rb', line 32

def valid_command_return_values
  @valid_command_return_values
end

Class Method Details

.inherited(member) ⇒ Object

Extends ClassMethods to subclasses and tracks Familia members



62
63
64
65
66
67
68
69
70
71
 
# File 'lib/familia/horreum.rb', line 62

def inherited(member)
  Familia.trace :HORREUM, nil, "Welcome #{member} to the family", caller(1..1) if Familia.debug?
  member.extend(ClassMethods)
  member.extend(Features)

  # Tracks all the classes/modules that include Familia. It's
  # 10pm, do you know where you Familia members are?
  Familia.members << member
  super
end

Instance Method Details

#identifier ⇒ Object

Determines the unique identifier for the instance This method is used to generate Redis keys for the object

Raises:



259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
 
# File 'lib/familia/horreum.rb', line 259

def identifier
  definition = self.class.identifier # e.g.
  # When definition is a symbol or string, assume it's an instance method
  # to call on the object to get the unique identifier. When it's a callable
  # object, call it with the object as the argument. When it's an array,
  # call each method in turn and join the results. When it's nil, raise
  # an error
  unique_id = case definition
              when Symbol, String
                send(definition)
              when Proc
                definition.call(self)
              when Array
                Familia.join(definition.map { |method| send(method) })
              else
                raise Problem, "Invalid identifier definition: #{definition.inspect}"
              end

  # If the unique_id is nil, raise an error
  raise Problem, "Identifier is nil for #{self.class} #{rediskey}" if unique_id.nil?
  raise Problem, 'Identifier is empty' if unique_id.empty?

  unique_id
end

#initialize_relatives ⇒ Object

Sets up related Redis objects for the instance This method is crucial for establishing Redis-based relationships

This needs to be called in the initialize method.



151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
 
# File 'lib/familia/horreum.rb', line 151

def initialize_relatives
  # Generate instances of each RedisType. These need to be
  # unique for each instance of this class so they can piggyback
  # on the specifc index of this instance.
  #
  # i.e.
  #     familia_object.rediskey              == v1:bone:INDEXVALUE:object
  #     familia_object.redis_type.rediskey == v1:bone:INDEXVALUE:name
  #
  # See RedisType.install_redis_type
  self.class.redis_types.each_pair do |name, redis_type_definition|
    klass = redis_type_definition.klass
    opts = redis_type_definition.opts
    Familia.ld "[#{self.class}] initialize_relatives #{name} => #{klass} #{opts.keys}"

    # As a subclass of Familia::Horreum, we add ourselves as the parent
    # automatically. This is what determines the rediskey for RedisType
    # instance and which redis connection.
    #
    #   e.g. If the parent's rediskey is `customer:customer_id:object`
    #     then the rediskey for this RedisType instance will be
    #     `customer:customer_id:name`.
    #
    opts[:parent] = self # unless opts.key(:parent)

    suffix_override = opts.fetch(:suffix, name)

    # Instantiate the RedisType object and below we store it in
    # an instance variable.
    redis_type = klass.new suffix_override, opts

    # Freezes the redis_type, making it immutable.
    # This ensures the object's state remains consistent and prevents any modifications,
    # safeguarding its integrity and making it thread-safe.
    # Any attempts to change the object after this will raise a FrozenError.
    redis_type.freeze

    # e.g. customer.name  #=> `#<Familia::HashKey:0x0000...>`
    instance_variable_set :"@#{name}", redis_type
  end
end

#initialize_with_keyword_args_from_redis(**fields) ⇒ Object 



233
234
235
236
237
 
# File 'lib/familia/horreum.rb', line 233

def initialize_with_keyword_args_from_redis(**fields)
  # Deserialize Redis string values back to their original types
  deserialized_fields = fields.transform_values { |value| deserialize_value(value) }
  initialize_with_keyword_args(**deserialized_fields)
end

#optimistic_refresh(**fields) ⇒ Array

A thin wrapper around the private initialize method that accepts a field hash and refreshes the existing object.

This method is part of horreum.rb rather than serialization.rb because it operates solely on the provided values and doesn’t query Redis or other external sources. That’s why it’s called “optimistic” refresh: it assumes the provided values are correct and updates the object accordingly.

Parameters:

  • fields (Hash) —

    A hash of field names and their new values to update the object with.

Returns:

  • (Array) —

    The list of field names that were updated.

See Also:



252
253
254
255
 
# File 'lib/familia/horreum.rb', line 252

def optimistic_refresh(**fields)
  Familia.ld "[optimistic_refresh] #{self.class} #{rediskey} #{fields.keys}"
  initialize_with_keyword_args_from_redis(**fields)
end

#to_s ⇒ Object

The principle is: **If Familia objects have ‘to_s`, then they should work everywhere strings are expected**, including as Redis hash field names.



286
287
288
289
290
291
292
293
294
295
 
# File 'lib/familia/horreum.rb', line 286

def to_s
  # Enable polymorphic string usage for Familia objects
  # This allows passing Familia objects directly where strings are expected
  # without requiring explicit .identifier calls
  identifier.to_s
rescue => e
  # Fallback for cases where identifier might fail
  Familia.ld "[#{self.class}#to_s] Failed to get identifier: #{e.message}"
  "#<#{self.class}:0x#{object_id.to_s(16)}>"
end