familia 1.0.0.pre.rc4 → 1.0.0.pre.rc5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b514a58bc45692f39123cce853a679078eccd78362a78facc397a1df6d94629d
-  data.tar.gz: d29686d172bec525bee366ab54ad4e81a5903547a9a2d98c68df8ca81853c7dc
+  metadata.gz: 3218c877946104986176b606caef17360ba262e22372dd61597982f9b97661db
+  data.tar.gz: b699a7b951ccf64c3421c9f79e29f927d3df0a36a0caa005575e118ae8ad000c
 SHA512:
-  metadata.gz: cd750e1ee120eb666563e9c8c552f721926ccceaa032cd0cefcf4fad7920225ab1edc4961cf3a5a7c38d81ecab3c21b446e91a75347d51a4bc196c14f5ed94fd
-  data.tar.gz: 6c52919952e7ce8232cf1023fafe567655580a73e4d36dd0a38b8842cb618387272db6950380f71efa01797439d9542303d3addd8c94e841255923998b93589f
+  metadata.gz: a19eca2cdcf6fe40e2c4109199938f95c02af3e3f6f4dda247720c983e6340ed725143a350f72b00a7c0c8d16bdab7dfb82ac4314a4d786249381f34fcb2da35
+  data.tar.gz: 2a9b815eed8437ea6514a7d29288ecf151c371ed2013495a5eaa6e2294bf61f75c07c9946c28dbf75fcdd0df7fdc1b5890ab0d83a9354f951c0f43e7718f0df8

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    familia (1.0.0.pre.rc4)
+    familia (1.0.0.pre.rc5)
       redis (>= 4.8.1, < 6.0)
       uri-redis (~> 1.3)
 

data/README.md

@@ -1,4 +1,4 @@
-# Familia - 1.0.0-rc4 (August 2024)
+# Familia - 1.0.0-rc5 (August 2024)
 
 **Organize and store Ruby objects in Redis. A powerful Ruby ORM (of sorts) for Redis.**
 

data/VERSION.yml

@@ -2,4 +2,4 @@
 :MAJOR: 1
 :MINOR: 0
 :PATCH: 0
-:PRE: rc4
+:PRE: rc5

data/lib/familia/features/expiration.rb

@@ -3,7 +3,7 @@
 
 
 module Familia::Features
-  #
+
   module Expiration
     @ttl = nil
 
@@ -57,7 +57,7 @@ module Familia::Features
     # @raise [Familia::Problem] If you try to feed it non-numbers or time-travel
     #   (negative numbers). It's strict, but fair!
     #
-    def update_expiration(ttl = nil)
+  def update_expiration(ttl = nil)
       ttl ||= self.ttl
       # It's important to raise exceptions here and not just log warnings. We
       # don't want to silently fail at setting expirations and cause data
@@ -67,14 +67,15 @@ module Familia::Features
       # good reason for the ttl to not be set in the first place. If the
       # class doesn't have a ttl, the default comes from Familia.ttl (which
       # is 0).
-      raise Familia::Problem, "TTL must be a number (#{ttl.class})" unless ttl.is_a?(Numeric)
-      raise Familia::Problem, "TTL must be positive (#{ttl})" unless ttl.is_a?(Numeric)
+      unless ttl.is_a?(Numeric)
+        raise Familia::Problem, "TTL must be a number (#{ttl.class} in #{self.class})"
+      end
 
       if ttl.zero?
         return Familia.ld "[update_expiration] No expiration for #{self.class} (#{rediskey})"
       end
 
-      Familia.info "[update_expiration] Expires #{rediskey} in #{ttl} seconds"
+      Familia.ld "[update_expiration] Expires #{rediskey} in #{ttl} seconds"
 
       # Redis' EXPIRE command returns 1 if the timeout was set, 0 if key does
       # not exist or the timeout could not be set. Via redis-rb here, it's

data/lib/familia/horreum/serialization.rb

@@ -6,6 +6,24 @@ module Familia
   # Familia::Horreum
   #
   class Horreum
+    # List of valid return values for Redis commands.
+    # This includes:
+    # - "OK": Indicates successful execution of a command.
+    # - true: Indicates a successful boolean response.
+    # - 1: Indicates success for commands that return a count of affected items.
+    # - 0: Indicates success for commands that return a count of affected items, but no items were affected.
+    # - nil: Indicates the absence of a value, which can be considered a valid outcome in some contexts.
+    #
+    # This list is used to validate the return values of multiple Redis commands executed within methods.
+    # Methods that run multiple Redis commands will check if all return values are included in this list
+    # to determine overall success. If any return value is not in this list, it is considered unexpected
+    # and may be logged or handled accordingly.
+    @valid_command_return_values = ["OK", true, 1, 0, nil]
+
+    class << self
+      attr_accessor :valid_command_return_values
+    end
+
     # Serialization: Where Objects Go to Become Strings (and Vice Versa)!
     #
     # This module is chock-full of methods that'll make your head spin (in a
@@ -108,12 +126,12 @@ module Familia
         self.created ||= Familia.now.to_i
 
         # Commit our tale to the Redis chronicles
-        ret = commit_fields # e.g. ["OK"]
+        ret = commit_fields # e.g. MultiResult.new(true, ["OK", "OK"])
 
         Familia.ld "[save] #{self.class} #{rediskey} #{ret}"
 
         # Did Redis accept our offering?
-        ret.uniq.all? { |value| ["OK", true].include?(value) }
+        ret.successful?
       end
 
       # Apply a smattering of fields to this object like fairy dust.
@@ -126,10 +144,10 @@ module Familia
       #   fresh attributes.
       #
       # @example Giving your object a makeover
-      #   dragon.apply_fields(name: "Puff", breathes: "fire", loves: "little boys
+      #   dragon.apply_fields(name: "Puff", breathes: "fire", loves: "Toys
       #   named Jackie")
       #   # => #<Dragon:0x007f8a1c8b0a28 @name="Puff", @breathes="fire",
-      #   @loves="little boys named Jackie">
+      #   @loves="Toys named Jackie">
       #
       def apply_fields(**fields)
         fields.each do |field, value|
@@ -143,23 +161,48 @@ module Familia
       #
       # This method performs a sacred ritual, sending our cherished attributes
       # on a journey through the ethernet to find their resting place in Redis.
+      # It executes a transaction that includes setting field values and,
+      # if applicable, updating the expiration time.
+      #
+      # @return [MultiResult] A mystical object containing:
+      #   - success: A boolean indicating if all Redis commands succeeded
+      #   - results: An array of strings, cryptic messages from the Redis gods
       #
-      # @return [Array<String>] A mystical array of strings, cryptic messages
-      #   from the Redis gods.
+      # The MultiResult object responds to:
+      #   - successful?: Returns the boolean success value
+      #   - results: Returns the array of command return values
       #
       # @note Be warned, young programmer! This method dabbles in the arcane
       #   art of transactions. Side effects may include data persistence and a
-      #   slight tingling sensation.
+      #   slight tingling sensation. The method does not raise exceptions for
+      #   unexpected Redis responses, but logs warnings and returns a failure status.
       #
       # @example Offering your changes to the Redis deities
       #   unicorn.name = "Charlie"
       #   unicorn.horn_length = "magnificent"
-      #   unicorn.commit_fields
-      #   # => ["OK", "OK"] (The Redis gods are pleased with your offering)
+      #   result = unicorn.commit_fields
+      #   if result.successful?
+      #     puts "The Redis gods are pleased with your offering"
+      #     p result.results  # => ["OK", "OK"]
+      #   else
+      #     puts "The Redis gods frown upon your offering"
+      #     p result.results  # Examine the unexpected values
+      #   end
+      #
+      # @see Familia::Horreum.valid_command_return_values for the list of
+      #   acceptable Redis command return values.
+      #
+      # @note This method performs logging at various levels:
+      #   - Debug: Logs the object's class, Redis key, and current state before committing
+      #   - Warn: Logs any unexpected return values from Redis commands
+      #   - Debug: Logs the final result, including success status and all return values
+      #
+      # @note The expiration update is only performed for classes that have
+      #   the expiration feature enabled. For others, it's a no-op.
       #
       def commit_fields
         Familia.ld "[commit_fields] #{self.class} #{rediskey} #{to_h}"
-        transaction do |conn|
+        command_return_values = transaction do |conn|
           hmset
 
           # Only classes that have the expiration ferature enabled will
@@ -167,6 +210,26 @@ module Familia
           # this will be a no-op.
           update_expiration
         end
+
+        # The acceptable redis command return values are defined in the
+        # Horreum class. This is to ensure that all commands return values
+        # are validated against a consistent set of values.
+        acceptable_values = Familia::Horreum.valid_command_return_values
+
+        # Check if all return values are valid
+        summary_boolean = command_return_values.uniq.all? { |value|
+          acceptable_values.include?(value)
+        }
+
+        # Log the unexpected
+        unless summary_boolean
+          unexpected_values = command_return_values.reject { |value| acceptable_values.include?(value) }
+          Familia.warn "[commit_fields] Unexpected return values: #{unexpected_values}"
+        end
+
+        Familia.ld "[commit_fields] #{self.class} #{rediskey} #{summary_boolean}: #{command_return_values}"
+
+        MultiResult.new(summary_boolean, command_return_values)
       end
 
       # Dramatically vanquish this object from the face of Redis! (ed: delete it)
@@ -313,6 +376,71 @@ module Familia
     end
     # End of Serialization module
 
+    # Represents the result of a multiple Redis commands.
+    #
+    # This class encapsulates the outcome of a Redis "transaction",
+    # providing both a success indicator and the raw results from
+    # the Redis commands executed during the transaction ("MULTI").
+    #
+    # @attr_reader success [Boolean] Indicates whether all Redis commands
+    #   in the transaction were successful.
+    # @attr_reader results [Array<String>] An array of return values from
+    #   the Redis commands executed in the transaction.
+    #
+    # @example Creating a MultiResult
+    #   result = MultiResult.new(true, ["OK", "OK"])
+    #
+    # @example Checking the success of a commit
+    #   if result.successful?
+    #     puts "All commands succeeded"
+    #   else
+    #     puts "Some commands failed"
+    #   end
+    #
+    # @example Accessing raw results
+    #   result.results.each_with_index do |value, index|
+    #     puts "Command #{index + 1} returned: #{value}"
+    #   end
+    class MultiResult
+      # @return [Boolean] true if all commands in the transaction succeeded,
+      #   false otherwise
+      attr_reader :success
+
+      # @return [Array<String>] The raw return values from the Redis commands
+      attr_reader :results
+
+      # Creates a new MultiResult instance.
+      #
+      # @param success [Boolean] Whether all commands succeeded
+      # @param results [Array<String>] The raw results from Redis commands
+      def initialize(success, results)
+        @success = success
+        @results = results
+      end
+
+      # Returns a tuple representing the result of the transaction.
+      #
+      # @return [Array] A tuple containing the success status and the raw results.
+      #   The success status is a boolean indicating if all commands succeeded.
+      #   The raw results is an array of return values from the Redis commands.
+      #
+      # @example
+      #   [true, ["OK", true, 1]]
+      #
+      def tuple
+        [successful?, results]
+      end
+
+      # Convenient method to check if the commit was successful.
+      #
+      # @return [Boolean] true if all commands succeeded, false otherwise
+      def successful?
+        @success
+      end
+      alias success? successful?
+    end
+    # End of MultiResult class
+
     include Serialization # these become Horreum instance methods
   end
 end

data/lib/familia/horreum.rb

@@ -233,7 +233,7 @@ module Familia
                   end
 
       # If the unique_id is nil, raise an error
-      raise Problem, "Identifier is nil for #{self.class}" if unique_id.nil?
+      raise Problem, "Identifier is nil for #{self.class} #{rediskey}" if unique_id.nil?
       raise Problem, 'Identifier is empty' if unique_id.empty?
 
       unique_id

data/lib/familia/redistype.rb

@@ -102,7 +102,12 @@ module Familia
 
       # Apply the options to instance method setters of the same name
       @opts.each do |k, v|
-        Familia.ld " [setting] #{k} #{v}"
+        # Bewarde logging :parent instance here implicitly calls #to_s which for
+        # some classes could include the identifier which could still be nil at
+        # this point. This would result in a Familia::Problem being raised. So
+        # to be on the safe-side here until we have a better understanding of
+        # the issue, we'll just log the class name for each key-value pair.
+        Familia.ld " [setting] #{k} #{v.class}"
         send(:"#{k}=", v) if respond_to? :"#{k}="
       end
 

data/lib/familia/utils.rb

@@ -38,7 +38,7 @@ module Familia
   #   # => "193tosc85k3u513do2mtmibchpd2ruh5l3nsp6dnl0ov1i91h7m7"
   #
   def generate_id(length: 32, encoding: 36)
-    raise ArgumentError, "Encoding must be between 2 and 32" unless (1..32).include?(encoding)
+    raise ArgumentError, "Encoding must be between 2 and 36" unless (1..36).include?(encoding)
 
     input = SecureRandom.hex(length)
     Digest::SHA256.hexdigest(input).to_i(16).to_s(encoding)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: familia
 version: !ruby/object:Gem::Version
-  version: 1.0.0.pre.rc4
+  version: 1.0.0.pre.rc5
 platform: ruby
 authors:
 - Delano Mandelbaum