familia 0.10.2 → 1.0.0.pre.rc1

data/lib/redis_middleware.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+# RedisLogger is RedisClient middleware.
+#
+# This middleware addresses the need for detailed Redis command logging, which
+# was removed from the redis-rb gem due to performance concerns. However, in
+# many development and debugging scenarios, the ability to log Redis commands
+# can be invaluable.
+#
+# @example Enable Redis command logging
+#   RedisLogger.logger = Logger.new(STDOUT)
+#   RedisClient.register(RedisLogger)
+#
+# @see https://github.com/redis-rb/redis-client?tab=readme-ov-file#instrumentation-and-middlewares
+#
+# @note While there were concerns about the performance impact of logging in
+#   the redis-rb gem, this middleware is designed to be optional and can be
+#   easily enabled or disabled as needed. The performance impact is minimal
+#   when logging is disabled, and the benefits during development and debugging
+#   often outweigh the slight performance cost when enabled.
+module RedisLogger
+  @logger = nil
+
+  class << self
+    # Gets/sets the logger instance used by RedisLogger.
+    # @return [Logger, nil] The current logger instance or nil if not set.
+    attr_accessor :logger
+  end
+
+  # Logs the Redis command and its execution time.
+  #
+  # This method is called for each Redis command when the middleware is active.
+  # It logs the command and its execution time only if a logger is set.
+  #
+  # @param command [Array] The Redis command and its arguments.
+  # @param redis_config [Hash] The configuration options for the Redis
+  #   connection.
+  # @return [Object] The result of the Redis command execution.
+  #
+  # @note The performance impact of this logging is negligible when no logger
+  #   is set, as it quickly returns control to the Redis client. When a logger
+  #   is set, the minimal overhead is often offset by the valuable insights
+  #   gained during development and debugging.
+  def call(command, redis_config)
+    return yield unless RedisLogger.logger
+
+    start = Process.clock_gettime(Process::CLOCK_MONOTONIC, :microsecond)
+    result = yield
+    duration = Process.clock_gettime(Process::CLOCK_MONOTONIC, :microsecond) - start
+    RedisLogger.logger.debug("Redis: #{command.inspect} (#{duration}µs)")
+    result
+  end
+end
+
+# RedisCommandCounter is RedisClient middleware.
+#
+# This middleware counts the number of Redis commands executed. It can be
+# useful for performance monitoring and debugging, allowing you to track
+# the volume of Redis operations in your application.
+#
+# @example Enable Redis command counting
+#   RedisCommandCounter.reset
+#   RedisClient.register(RedisCommandCounter)
+#
+# @see https://github.com/redis-rb/redis-client?tab=readme-ov-file#instrumentation-and-middlewares
+module RedisCommandCounter
+  @count = 0
+  @mutex = Mutex.new
+
+  class << self
+    # Gets the current count of Redis commands executed.
+    # @return [Integer] The number of Redis commands executed.
+    attr_reader :count
+
+    # Resets the command count to zero.
+    # This method is thread-safe.
+    # @return [Integer] The reset count (always 0).
+    def reset
+      @mutex.synchronize { @count = 0 }
+    end
+
+    # Increments the command count.
+    # This method is thread-safe.
+    # @return [Integer] The new count after incrementing.
+    def increment
+      @mutex.synchronize { @count += 1 }
+    end
+
+    def count_commands
+      start_count = count
+      yield
+      end_count = count
+      end_count - start_count
+    end
+  end
+
+  # Counts the Redis command and delegates its execution.
+  #
+  # This method is called for each Redis command when the middleware is active.
+  # It increments the command count and then yields to execute the actual command.
+  #
+  # @param command [Array] The Redis command and its arguments.
+  # @param redis_config [Hash] The configuration options for the Redis connection.
+  # @return [Object] The result of the Redis command execution.
+  def call(command, redis_config)
+    RedisCommandCounter.increment
+    yield
+  end
+end

data/try/00_familia_try.rb

@@ -1,11 +1,12 @@
-require 'familia'
-require 'familia/test_helpers'
 
-Familia.apiversion = 'v1'
+require_relative '../lib/familia'
+require_relative './test_helpers'
+
+#Familia.apiversion = 'v1'
 
 
 ## Check for help class
-Bone.redis_objects.keys # consistent b/c hashes are ordered
+Bone.redis_types.keys # consistent b/c hashes are ordered
 #=> [:owners, :tags, :metrics, :props, :value]
 
 ## Familia has a uri

data/try/10_familia_try.rb

@@ -1,25 +1,28 @@
-require 'familia'
-require 'familia/test_helpers'
 
-## Has all redis objects
-redis_objects = Familia::RedisObject.registration.keys
-redis_objects.collect(&:to_s).sort
-#=> ["hash", "list", "set", "string", "zset"]
+require 'time'
 
-## Familia created class methods for redis object class
-Familia::ClassMethods.public_method_defined? :list?
+require_relative '../lib/familia'
+require_relative './test_helpers'
+
+## Has all redistype relativess
+registered_types = Familia::RedisType.registered_types.keys
+registered_types.collect(&:to_s).sort
+#=> ["counter", "hash", "hashkey", "list", "lock", "set", "sorted_set", "string", "zset"]
+
+## Familia created class methods for redistype list class
+Familia::Horreum::ClassMethods.public_method_defined? :list?
 #=> true
 
-## Familia created class methods for redis object class
-Familia::ClassMethods.public_method_defined? :list
+## Familia created class methods for redistype list class
+Familia::Horreum::ClassMethods.public_method_defined? :list
 #=> true
 
-## Familia created class methods for redis object class
-Familia::ClassMethods.public_method_defined? :lists
+## Familia created class methods for redistype list class
+Familia::Horreum::ClassMethods.public_method_defined? :lists
 #=> true
 
-## A Familia object knows its redis objects
-Bone.redis_objects.is_a?(Hash) && Bone.redis_objects.has_key?(:owners)
+## A Familia object knows its redistype relativess
+Bone.redis_types.is_a?(Hash) && Bone.redis_types.has_key?(:owners)
 #=> true
 
 ## A Familia object knows its lists
@@ -30,14 +33,15 @@ Bone.lists.size
 Bone.list? :owners
 #=> true
 
-## A Familia object can get a specific redis object def
+## A Familia object can get a specific redistype relatives def
 definition = Bone.list :owners
 definition.klass
 #=> Familia::List
 
 ## Familia.now
-Familia.now Time.parse('2011-04-10 20:56:20 UTC').utc
-#=> 1302468980
+parsed_time = Familia.now(Time.parse('2011-04-10 20:56:20 UTC').utc)
+[parsed_time, parsed_time.is_a?(Numeric), parsed_time.is_a?(Float)]
+#=> [1302468980.0, true, true]
 
 ## Familia.qnow
 Familia.qnow 10.minutes, 1302468980

data/try/20_redis_type_try.rb

@@ -0,0 +1,67 @@
+
+require_relative '../lib/familia'
+require_relative '../lib/familia/features/quantizer'
+require_relative './test_helpers'
+
+#Familia.apiversion = 'v1'
+
+@limiter1 = Limiter.new :requests
+
+
+## Redis Types are unique per instance of a Familia class
+@a = Bone.new 'atoken1', :name1
+@b = Bone.new 'atoken2', :name2
+p [@a.object_id, @b.object_id]
+p [@a.owners.parent.class, @b.owners.parent.class]
+p [@a.owners.parent.object_id, @b.owners.parent.object_id]
+p [@a.owners.rediskey, @b.owners.rediskey]
+p [@a.token, @b.token]
+p [@a.name, @b.name]
+@a.owners.rediskey.eql?(@b.owners.rediskey)
+#=> false
+
+## Redis Types are frozen
+@a.owners.frozen?
+#=> true
+
+
+## Limiter#qstamp
+@limiter1.counter.qstamp(10.minutes, '%H:%M', 1302468980)
+##=> '20:50'
+
+## Redis Types can be stored to quantized stamp suffix
+@limiter1.counter.rediskey
+##=> "v1:limiter:requests:counter:20:50"
+
+## Limiter#qstamp as a number
+@limiter2 = Limiter.new :requests
+@limiter2.counter.qstamp(10.minutes, pattern=nil, now=1302468980)
+##=> 1302468600
+
+## Redis Types can be stored to quantized numeric suffix. This
+## tryouts is disabled b/c `RedisType#rediskey` takes no args
+## and relies on the `class Limiter` definition in test_helpers.rb
+## for the `:quantize` option. The quantized suffix for the Limiter
+## class is `'%H:%M'` so its redis keys will always look like that.
+@limiter2.counter.rediskey
+##=> "v1:limiter:requests:counter:1302468600"
+
+## Increment counter
+@limiter1.counter.clear
+@limiter1.counter.increment
+#=> 1
+
+## Check ttl
+@limiter1.counter.ttl
+#=> 3600.0
+
+## Check ttl for a different instance
+## (this exists to make sure options are cloned for each instance)
+@limiter3 = Limiter.new :requests
+@limiter3.counter.ttl
+#=> 3600.0
+
+## Check realttl
+sleep 1 # Redis ttls are in seconds so we can't wait any less time than this (without mocking)
+@limiter1.counter.realttl
+#=> 3600-1

data/try/{21_redis_object_zset_try.rb → 21_redis_type_zset_try.rb}

@@ -1,5 +1,5 @@
-require 'familia'
-require 'familia/test_helpers'
+require_relative '../lib/familia'
+require_relative './test_helpers'
 
 # Familia.debug = true
 

data/try/{22_redis_object_set_try.rb → 22_redis_type_set_try.rb}

@@ -1,6 +1,6 @@
 
-require 'familia'
-require 'familia/test_helpers'
+require_relative '../lib/familia'
+require_relative './test_helpers'
 
 @a = Bone.new 'atoken', 'akey'
 

data/try/{23_redis_object_list_try.rb → 23_redis_type_list_try.rb}

@@ -1,6 +1,6 @@
 
-require 'familia'
-require 'familia/test_helpers'
+require_relative '../lib/familia'
+require_relative './test_helpers'
 
 @a = Bone.new 'atoken', 'akey'
 

data/try/{24_redis_object_string_try.rb → 24_redis_type_string_try.rb}

@@ -1,13 +1,13 @@
-require 'familia'
-require 'familia/test_helpers'
+require_relative '../lib/familia'
+require_relative './test_helpers'
 
-Familia.apiversion = 'v1'
+#Familia.apiversion = 'v1'
 
 @a = Bone.new 'atoken2', 'akey'
 
 ## Bone#rediskey
 @a.rediskey
-#=> 'v1:bone:atoken2:akey:object'
+#=> 'bone:atoken2:akey:object'
 
 ## Familia::String#value should give default value
 @a.value.value
@@ -39,7 +39,7 @@ Familia.apiversion = 'v1'
 #=> '1000'
 
 ## Familia::String#increment
-@ret.increment 
+@ret.increment
 #=> 1001
 
 ## Familia::String#incrementby
@@ -47,7 +47,7 @@ Familia.apiversion = 'v1'
 #=> 1100
 
 ## Familia::String#decrement
-@ret.decrement 
+@ret.decrement
 #=> 1099
 
 ## Familia::String#decrementby

data/try/{25_redis_object_hash_try.rb → 25_redis_type_hash_try.rb}

@@ -1,5 +1,5 @@
-require 'familia'
-require 'familia/test_helpers'
+require_relative '../lib/familia'
+require_relative './test_helpers'
 
 @a = Bone.new 'atoken', 'akey'
 
@@ -21,7 +21,7 @@ require 'familia/test_helpers'
 @a.props.has_key? 'fieldA'
 #=> true
 
-## Familia::HashKey#all 
+## Familia::HashKey#all
 @a.props.all.class
 #=> Hash
 

data/try/26_redis_bool_try.rb

@@ -1,5 +1,5 @@
-require 'familia'
-require 'familia/test_helpers'
+require_relative '../lib/familia'
+require_relative './test_helpers'
 
 Familia.debug = true
 
@@ -17,10 +17,10 @@ Familia.debug = true
 ## Trying to store a boolean value to a hash key raises an exception
 begin
   @hashkey["test"] = true
-rescue TypeError => e
+rescue Familia::HighRiskFactor => e
   e.message
 end
-#=> "Cannot store test => true (TrueClass) in key"
+#=> "High risk factor for serialization bugs: true<TrueClass>"
 
 ## Boolean values are returned as strings
 @hashkey["test"]
@@ -29,11 +29,15 @@ end
 ## Trying to store a nil value to a hash key raises an exception
 begin
   @hashkey["test"] = nil
-rescue TypeError => e
+rescue Familia::HighRiskFactor => e
   e.message
 end
-#=> "Cannot store test => nil (NilClass) in key"
+#=> "High risk factor for serialization bugs: <NilClass>"
 
 ## The exceptions prevented the hash from being updated
 @hashkey["test"]
 #=> "true"
+
+## Clear the hash key
+@hashkey.clear
+#=> 1

data/try/27_redis_horreum_try.rb

@@ -0,0 +1,40 @@
+require_relative '../lib/familia'
+require_relative './test_helpers'
+
+Familia.debug = true
+
+@identifier = 'tryouts-27@onetimesecret.com'
+@customer = Customer.new @identifier
+@hashkey = Familia::HashKey.new 'tryouts-27'
+
+## Customer passed as value is returned as string identifier, on assignment as string
+@hashkey["test1"] = @customer.identifier
+#=> @identifier
+
+## Customer passed as value is returned as string identifier
+@hashkey["test1"]
+#=> @identifier
+
+## Trying to store a customer to a hash key implicitly converts it to string identifier
+## we can't tell from the return value this way either. Here the store method return value
+## is either 1 (if the key is new) or 0 (if the key already exists).
+@hashkey.store "test2", @customer
+#=> 1
+
+## Trying to store a customer to a hash key implicitly converts it to string identifier
+## but we can't tell that from the return value. Here the hash syntax return value
+## is the value that is being assigned.
+@hashkey["test2"] = @customer
+#=> @customer
+
+## Trying store again with the same key returns 0
+@hashkey.store "test2", @customer
+#=> 0
+
+## Customer passed as value is returned as string identifier
+@hashkey["test2"]
+#=> @identifier
+
+## Remove the key
+@hashkey.clear
+#=> 1

data/try/30_familia_object_try.rb

@@ -1,6 +1,6 @@
-require 'familia'
-require 'familia/test_helpers'
-Familia.apiversion = 'v1'
+require_relative '../lib/familia'
+require_relative './test_helpers'
+#Familia.apiversion = 'v1'
 
 @a = Bone.new 'atoken', 'akey'
 
@@ -8,8 +8,8 @@ Familia.apiversion = 'v1'
 Bone.prefix
 #=> :bone
 
-## Familia#index
-@a.index
+## Familia#identifier
+@a.identifier
 #=> 'atoken:akey'
 
 ## Familia.suffix
@@ -18,32 +18,34 @@ Bone.suffix
 
 ## Familia#rediskey
 @a.rediskey
-#=> 'v1:bone:atoken:akey:object'
+#=> 'bone:atoken:akey:object'
 
 ## Familia#rediskey
 @a.rediskey
-#=> 'v1:bone:atoken:akey:object'
+#=> 'bone:atoken:akey:object'
 
 ## Familia#save
 @cust = Customer.new :delano, "Delano Mandelbaum"
 @cust.save
 #=> true
 
-## Customer.instances
-Customer.instances.all.collect(&:custid)
-#=> [:delano]
+## Customer.values (Updateing this sorted set of instance IDs is a Onetime
+# Secret feature. Disabled here b/c there's no code in Familia or the test
+# helpers that replicates this behaviour.) Leaving this here for reference.
+Customer.values.all.collect(&:custid)
+##=> ['delano']
 
 ## Familia.from_redis
 obj = Customer.from_redis :delano
-obj.custid
-#=> :delano
+[obj.class, obj.custid]
+#=> [Customer, 'delano']
 
 ## Customer.destroy
 @cust.destroy!
-#=> 1
+#=> true
 
 ## Customer.instances
-Customer.instances.size
+Customer.values.size
 #=> 0
 
 ## Familia#save with an object that expires
@@ -57,7 +59,7 @@ Customer.customers.class
 
 ## Familia class rediskey
 Customer.customers.rediskey
-#=> 'v1:customer:customers'
+#=> 'customer:customers'
 
 ## Familia.class_list
 Customer.customers << :delano << :tucker << :morton
@@ -69,19 +71,18 @@ Customer.customers.clear
 #=> 1
 
 
-## Familia class replace 1
+## Familia class replace 1 of 4
 Customer.message.value = "msg1"
 #=> "msg1"
 
-## Familia class replace 2
+## Familia class replace 2 of 4
 Customer.message.value
 #=> "msg1"
 
-## Familia class replace 3
+## Familia class replace 3 of 4
 Customer.message = "msg2"
 #=> "msg2"
 
-## Familia class replace 4
+## Familia class replace 4 of 4
 Customer.message.value
 #=> "msg2"
-

data/try/35_feature_safedump_try.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+# These tryouts test the safe dumping functionality.
+
+require_relative '../lib/familia'
+require_relative './test_helpers'
+
+## By default Familia::Base has no safe_dump_fields method
+Familia::Base.respond_to?(:safe_dump_fields)
+#=> false
+
+## Implementing models like Customer can define safe dump fields
+Customer.safe_dump_fields
+#=> [:custid, :role, :verified, :updated, :created, :secrets_created, :active]
+
+## Implementing models like Customer can safely dump their fields
+@cust = Customer.new
+@cust.custid = "test@example.com"
+@cust.role = "user"
+@cust.verified = true
+@cust.created = Time.now.to_i
+@cust.updated = Time.now.to_i
+@safe_dump = @cust.safe_dump
+@safe_dump.keys.sort
+#=> [:active, :created, :custid, :role, :secrets_created, :updated, :verified]
+
+## Implementing models like Customer do have other fields
+## that are by default considered not safe to dump.
+@cust1 = Customer.new
+@cust1.email = "test@example.com"
+
+@all_non_safe_fields = @cust1.instance_variables.map { |el|
+  el.to_s[1..-1].to_sym # slice off the leading @
+}.sort
+
+(@all_non_safe_fields - Customer.safe_dump_fields).sort
+#=> [:custom_domains, :email, :password_reset, :sessions, :stripe_customer, :timeline]
+
+## Implementing models like Customer can rest assured knowing
+## any other field not in the safe list will not be dumped.
+@cust2 = Customer.new
+@cust2.email = "test@example.com"
+@cust2.custid = "test@example.com"
+@all_safe_fields = @cust2.safe_dump.keys.sort
+
+@all_non_safe_fields = @cust2.instance_variables.map { |el|
+  el.to_s[1..-1].to_sym # slice off the leading @
+}.sort
+p [1, all_non_safe_fields: @all_non_safe_fields]
+# Check if any of the non-safe fields are in the safe dump
+(@all_non_safe_fields & @all_safe_fields) - [:custid, :role, :verified, :updated, :created, :secrets_created]
+#=> []
+
+## Bone does not have safe_dump feature enabled
+Bone.respond_to?(:safe_dump_fields)
+#=> false
+
+## Bone instances do not have safe_dump method
+@bone = Bone.new(name: "Rex", age: 3)
+@bone.respond_to?(:safe_dump)
+#=> false
+
+## Blone has safe_dump feature enabled
+Blone.respond_to?(:safe_dump_fields)
+#=> true
+
+## Blone has empty safe_dump_fields
+Blone.safe_dump_fields
+#=> []
+
+## Blone instances have safe_dump method
+@blone = Blone.new(name: "Fido", age: 5)
+@blone.respond_to?(:safe_dump)
+#=> true
+
+## Blone safe_dump returns an empty hash
+@blone.safe_dump
+#=> {}
+
+# Teardown
+@cust2.destroy!
+@bone = nil
+@blone = nil