familia 0.10.2 → 1.0.0.pre.rc1

data/lib/familia/core_ext.rb

@@ -1,140 +1,135 @@
-# encoding: utf-8
-class Symbol
-  unless method_defined?(:to_proc)
-    def to_proc
-      proc { |obj, *args| obj.send(self, *args) }
-    end
-  end
-end
+# frozen_string_literal: true
 
-class Hash
-  unless method_defined?(:to_json)
-    def to_json
-      MultiJson.encode self
-    end
-    def self.from_json str
-      MultiJson.decode str
-    end
-  end
-end
-class Array
-  unless method_defined?(:to_json)
-    def to_json
-      MultiJson.encode self
-    end
-    def self.from_json str
-      MultiJson.decode str
-    end
-  end
-end
-
-# Assumes Time::Units and Numeric mixins are available. 
+# Extends the String class with time-related functionality
+#
+# This implementaton assumes Time::Units and Numeric mixins are available.
+#
 class String
+  # Converts a string representation of time to seconds
+  #
+  # @example
+  #   "60m".in_seconds #=> 3600.0
+  #
+  # @return [Float, nil] The time in seconds, or nil if the string is invalid
   def in_seconds
-    # "60m" => ["60", "m"]
-    q,u = self.scan(/([\d\.]+)([s,m,h])?/).flatten
+    q, u = scan(/([\d.]+)([smh])?/).flatten
     q &&= q.to_f and u ||= 's'
-    q &&= q.in_seconds(u)
+    q&.in_seconds(u)
   end
 end
 
-unless defined?(Time::Units)
-  class Time
-    module Units
-      PER_MICROSECOND = 0.000001.freeze
-      PER_MILLISECOND = 0.001.freeze
-      PER_MINUTE = 60.0.freeze
-      PER_HOUR = 3600.0.freeze
-      PER_DAY = 86400.0.freeze
-    
-      def microseconds()    seconds * PER_MICROSECOND     end
-      def milliseconds()    seconds * PER_MILLISECOND    end
-      def seconds()         self                         end
-      def minutes()         seconds * PER_MINUTE          end
-      def hours()           seconds * PER_HOUR             end
-      def days()            seconds * PER_DAY               end
-      def weeks()           seconds * PER_DAY * 7           end
-      def years()           seconds * PER_DAY * 365        end 
-            
-      def in_years()        seconds / PER_DAY / 365      end
-      def in_weeks()        seconds / PER_DAY / 7       end
-      def in_days()         seconds / PER_DAY          end
-      def in_hours()        seconds / PER_HOUR          end
-      def in_minutes()      seconds / PER_MINUTE         end
-      def in_milliseconds() seconds / PER_MILLISECOND    end
-      def in_microseconds() seconds / PER_MICROSECOND   end
-    
-      def in_time
-        Time.at(self).utc
-      end
-    
-      def in_seconds(u=nil)
-        case u.to_s
-        when /\A(y)|(years?)\z/
-          years
-        when /\A(w)|(weeks?)\z/
-          weeks
-        when /\A(d)|(days?)\z/
-          days
-        when /\A(h)|(hours?)\z/
-          hours
-        when /\A(m)|(minutes?)\z/
-          minutes
-        when /\A(ms)|(milliseconds?)\z/
-          milliseconds
-        when /\A(us)|(microseconds?)|(μs)\z/
-          microseconds
-        else
-          self
-        end
-      end
-    
-      ## JRuby doesn't like using instance_methods.select here. 
-      ## It could be a bug or something quirky with Attic 
-      ## (although it works in 1.8 and 1.9). The error:
-      ##  
-      ##  lib/attic.rb:32:in `select': yield called out of block (LocalJumpError)
-      ##  lib/stella/mixins/numeric.rb:24
-      ##
-      ## Create singular methods, like hour and day. 
-      # instance_methods.select.each do |plural|
-      #   singular = plural.to_s.chop
-      #   alias_method singular, plural
-      # end
-    
-      alias_method :ms, :milliseconds
-      alias_method :'μs', :microseconds
-      alias_method :second, :seconds
-      alias_method :minute, :minutes
-      alias_method :hour, :hours
-      alias_method :day, :days
-      alias_method :week, :weeks
-      alias_method :year, :years
+# Extends the Time class with additional time unit functionality
+class Time
+  # Provides methods for working with various time units
+  module Units
+    # rubocop:disable Style/SingleLineMethods, Layout/ExtraSpacing
 
-    end
-  end
+    PER_MICROSECOND = 0.000001
+    PER_MILLISECOND = 0.001
+    PER_MINUTE = 60.0
+    PER_HOUR = 3600.0
+    PER_DAY = 86_400.0
+
+    # Conversion methods
+    #
+    # From other time units -> seconds
+    #
+    def microseconds()    seconds * PER_MICROSECOND     end
+    def milliseconds()    seconds * PER_MILLISECOND    end
+    def seconds()         self                         end
+    def minutes()         seconds * PER_MINUTE          end
+    def hours()           seconds * PER_HOUR             end
+    def days()            seconds * PER_DAY               end
+    def weeks()           seconds * PER_DAY * 7           end
+    def years()           seconds * PER_DAY * 365        end
 
-  class Numeric
-    include Time::Units
+    # From seconds -> other time units
+    #
+    def in_years()        seconds / PER_DAY / 365      end
+    def in_weeks()        seconds / PER_DAY / 7       end
+    def in_days()         seconds / PER_DAY          end
+    def in_hours()        seconds / PER_HOUR          end
+    def in_minutes()      seconds / PER_MINUTE         end
+    def in_milliseconds() seconds / PER_MILLISECOND    end
+    def in_microseconds() seconds / PER_MICROSECOND   end
 
-    def to_ms
-      (self*1000.to_f)
+    #
+    # Converts seconds to a Time object
+    #
+    # @return [Time] A Time object representing the seconds
+    def in_time
+      Time.at(self).utc
     end
-  
-    # TODO: Use 1024?
-    def to_bytes
-      args = case self.abs.to_i
-      when (1000)..(1000**2)
-        '%3.2f%s' % [(self / 1000.to_f).to_s, 'KB']
-      when (1000**2)..(1000**3)
-        '%3.2f%s' % [(self / (1000**2).to_f).to_s, 'MB']
-      when (1000**3)..(1000**4)
-        '%3.2f%s' % [(self / (1000**3).to_f).to_s, 'GB']
-      when (1000**4)..(1000**6)
-        '%3.2f%s' % [(self / (1000**4).to_f).to_s, 'TB']
+
+    # Converts seconds to the specified time unit
+    #
+    # @param u [String, Symbol] The unit to convert to (e.g., 'y', 'w', 'd', 'h', 'm', 'ms', 'us')
+    # @return [Float] The converted time value
+    def in_seconds(u = nil)
+      case u.to_s
+      when /\A(y)|(years?)\z/
+        years
+      when /\A(w)|(weeks?)\z/
+        weeks
+      when /\A(d)|(days?)\z/
+        days
+      when /\A(h)|(hours?)\z/
+        hours
+      when /\A(m)|(minutes?)\z/
+        minutes
+      when /\A(ms)|(milliseconds?)\z/
+        milliseconds
+      when /\A(us)|(microseconds?)|(μs)\z/
+        microseconds
       else
-        [self.to_i, 'B'].join
+        self
       end
     end
+
+    # Starring Jennifer Garner, Victor Garber, and Carl Lumbly
+    alias ms milliseconds
+    alias μs microseconds
+    alias second seconds
+    alias minute minutes
+    alias hour hours
+    alias day days
+    alias week weeks
+    alias year years
+
+    # rubocop:enable Style/SingleLineMethods, Layout/ExtraSpacing
+  end
+end
+
+# Extends the Numeric class with time unit and byte conversion functionality
+class Numeric
+  include Time::Units
+
+  # Converts the number to milliseconds
+  #
+  # @return [Float] The number in milliseconds
+  def to_ms
+    (self * 1000.to_f)
+  end
+
+  # Converts the number to a human-readable byte representation using binary units
+  #
+  # @return [String] A string representing the number in bytes, KiB, MiB, GiB, or TiB
+  #
+  # @example
+  #   1024.to_bytes      #=> "1.00 KiB"
+  #   2_097_152.to_bytes #=> "2.00 MiB"
+  #   3_221_225_472.to_bytes #=> "3.00 GiB"
+  #
+  def to_bytes
+    units = %w[B KiB MiB GiB TiB]
+    size = abs.to_f
+    unit = 0
+
+    while size > 1024 && unit < units.length - 1
+      size /= 1024
+      unit += 1
+    end
+
+    format('%3.2f %s', size, units[unit])
   end
 end

data/lib/familia/errors.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Familia
+  class Problem < RuntimeError; end
+  class NoIdentifier < Problem; end
+  class NonUniqueKey < Problem; end
+
+  class HighRiskFactor < Problem
+    attr_reader :value
+
+    def initialize(value)
+      @value = value
+      super
+    end
+
+    def message
+      "High risk factor for serialization bugs: #{value}<#{value.class}>"
+    end
+  end
+
+  class NotConnected < Problem
+    attr_reader :uri
+
+    def initialize(uri)
+      @uri = uri
+      super
+    end
+
+    def message
+      "No client for #{uri.serverid}"
+    end
+  end
+end

data/lib/familia/features/api_version.rb

@@ -0,0 +1,19 @@
+# rubocop:disable all
+#
+module Familia::Features
+  module ApiVersion
+
+    def apiversion(val = nil, &blk)
+      if blk.nil?
+        @apiversion = val if val
+      else
+        tmp = @apiversion
+        @apiversion = val
+        yield
+        @apiversion = tmp
+      end
+      @apiversion
+    end
+
+  end
+end

data/lib/familia/features/atomic_saves.rb

@@ -0,0 +1,8 @@
+# rubocop:disable all
+
+module Familia::Features
+  module AtomicSaves
+
+
+  end
+end

data/lib/familia/features/quantizer.rb

@@ -0,0 +1,35 @@
+# rubocop:disable all
+
+module Familia::Features
+
+  module Quantizer
+
+    # From Familia::RedisType
+    #
+    def qstamp(quantum = nil, pattern = nil, now = Familia.now)
+      quantum ||= @opts[:quantize] || ttl || 10.minutes
+      case quantum
+      when Numeric
+        # Handle numeric quantum (e.g., seconds, minutes)
+      when Array
+        quantum, pattern = *quantum
+      end
+      now ||= Familia.now
+      rounded = now - (now % quantum)
+
+      if pattern.nil?
+        Time.at(rounded).utc.to_i # 3605 -> 3600
+      else
+        Time.at(rounded).utc.strftime(pattern || '%H%M') # 3605 -> '1:00'
+      end
+
+    end
+
+    # From Familia::Horreum::InstanceMethods:
+    #
+    #def qstamp(_quantum = nil, pattern = nil, now = Familia.now)
+    #  self.class.qstamp ttl, pattern, now
+    #end
+
+  end
+end

data/lib/familia/features/safe_dump.rb

@@ -0,0 +1,175 @@
+# rubocop:disable all
+# frozen_string_literal: true
+
+
+module Familia::Features
+  # SafeDump is a mixin that allows models to define a list of fields that are
+  # safe to dump. This is useful for serializing objects to JSON or other
+  # formats where you want to ensure that only certain fields are exposed.
+  #
+  # To use SafeDump, include it in your model and define a list of fields that
+  # are safe to dump. The fields can be either symbols or hashes. If a field is
+  # a symbol, the method with the same name will be called on the object to
+  # retrieve the value. If the field is a hash, the key is the field name and
+  # the value is a lambda that will be called with the object as an argument.
+  # the hash syntax allows you to:
+  #   * define a field name that is different from the method name
+  #   * define a field that requires some computation on-the-fly
+  #   * define a field that is not a method on the object
+  #
+  # Example:
+  #
+  #   @safe_dump_fields = [
+  #     :objid,
+  #     :updated,
+  #     :created,
+  #     { :active => ->(obj) { obj.active? } }
+  #   ]
+  #
+  # Internally, all fields are normalized to the hash syntax and store in
+  # @safe_dump_field_map. `SafeDump.safe_dump_fields` returns only the list
+  # of symbols in the order they were defined. From the example above, it would
+  # return `[:objid, :updated, :created, :active]`.
+  #
+  module SafeDump
+    @dump_method = :to_json
+    @load_method = :from_json
+
+    @safe_dump_fields = []
+    @safe_dump_field_map = {}
+
+    module ClassMethods
+      def set_safe_dump_fields(*fields)
+        @safe_dump_fields = fields
+      end
+
+      # `SafeDump.safe_dump_fields` returns only the list
+      # of symbols in the order they were defined.
+      def safe_dump_fields
+        @safe_dump_fields.map do |field|
+          field.is_a?(Symbol) ? field : field.keys.first
+        end
+      end
+
+      # `SafeDump.safe_dump_field_map` returns the field map
+      # that is used to dump the fields. The keys are the
+      # field names and the values are callables that will
+      # expect to receive the instance object as an argument.
+      #
+      # The map is cached on the first call to this method.
+      #
+      def safe_dump_field_map
+        return @safe_dump_field_map if @safe_dump_field_map.any?
+
+        # Operate directly on the @safe_dump_fields array to
+        # build the map. This way we'll get the elements defined
+        # in the hash syntax (i.e. since the safe_dump_fields getter
+        # method returns only the symbols).
+        @safe_dump_field_map = @safe_dump_fields.each_with_object({}) do |el, map|
+          if el.is_a?(Symbol)
+            field_name = el
+            callable = lambda { |obj|
+              if obj.respond_to?(:[]) && obj[field_name]
+                obj[field_name] # Familia::RedisType classes
+              elsif obj.respond_to?(field_name)
+                obj.send(field_name) # Onetime::Models::RedisHash classes via method_missing 😩
+              end
+            }
+          else
+            field_name = el.keys.first
+            callable = el.values.first
+          end
+          map[field_name] = callable
+        end
+      end
+    end
+
+    def self.included base
+      Familia.ld "[Feature] Enabling SafeDump for #{base})"
+      base.extend ClassMethods
+
+      # Optionally define safe_dump_fields in the class to make
+      # sure we always have an array to work with.
+      unless base.instance_variable_defined?(:@safe_dump_fields)
+        base.instance_variable_set(:@safe_dump_fields, [])
+      end
+
+      # Ditto for the field map
+      unless base.instance_variable_defined?(:@safe_dump_field_map)
+        base.instance_variable_set(:@safe_dump_field_map, {})
+      end
+    end
+
+    # Returns a hash of safe fields and their values. This method
+    # calls the callables defined in the safe_dump_field_map with
+    # the instance object as an argument.
+    #
+    # The return values are not cached, so if you call this method
+    # multiple times, the callables will be called each time.
+    #
+    # Example:
+    #
+    #   class Customer < Familia::HashKey
+    #     include SafeDump
+    #     @safe_dump_fields = [
+    #       :name,
+    #       { :active => ->(cust) { cust.active? } }
+    #     ]
+    #
+    #     def active?
+    #       true # or false
+    #     end
+    #
+    #     cust = Customer.new :name => 'Lucy'
+    #     cust.safe_dump
+    #     #=> { :name => 'Lucy', :active => true }
+    #
+    def safe_dump
+      self.class.safe_dump_field_map.transform_values do |callable|
+        transformed_value = callable.call(self)
+
+        # If the value is a relative ancestor of SafeDump we can
+        # call safe_dump on it, otherwise we'll just return the value as-is.
+        if transformed_value.is_a?(SafeDump)
+          transformed_value.safe_dump
+        else
+          transformed_value
+        end
+      end
+    end
+
+    extend ClassMethods
+
+    Familia::Base.add_feature self, :safe_dump
+  end
+
+end
+
+
+__END__
+
+if value_to_distunguish.is_a?(Familia::Horreum)
+  Familia.trace :DISTINGUISHER, redis, "horreum", caller(1..1) if Familia.debug?
+  value_to_distunguish.identifier
+elsif dump_method && value_to_distunguish.respond_to?(dump_method)
+  Familia.trace :DISTINGUISHER, redis, "#{value_to_distunguish.class}##{dump_method}", caller(1..1) if Familia.debug?
+  value_to_distunguish.send(dump_method)
+else
+  if dump_method
+    msg = if dump_method.to_s.empty?
+      "No dump_method available for #{value_to_distunguish.class}"
+    else
+      "No such method: #{value_to_distunguish.class}##{dump_method}"
+    end
+    raise Familia::Problem, msg
+  else
+    Familia.trace :DISTINGUISHER, redis, "else", caller(1..1) if Familia.debug?
+    nil
+  end
+end
+
+
+if ret.nil? && dump_method && val.respond_to?(dump_method)
+  Familia.trace :TOREDIS, redis, "#{val.class}##{dump_method}", caller(1..1) if Familia.debug?
+  val.send dump_method
+end

data/lib/familia/features.rb

@@ -0,0 +1,51 @@
+# rubocop:disable all
+
+module Familia
+
+  @features_enabled = nil
+
+  module Features
+
+    attr_reader :features_enabled
+
+    def feature(val = nil)
+      @features_enabled ||= []
+
+      Familia.ld "[Familia::Settings] feature: #{val.inspect}"
+
+      # If there's a value provied check that it's a valid feature
+      if val
+        val = val.to_sym
+        raise Familia::Problem, "Unsupported feature: #{val}" unless Familia::Base.features.key?(val)
+
+        # If the feature is already enabled, do nothing but log about it
+        if @features_enabled.member?(val)
+          Familia.warn "[Familia::Settings] feature already enabled: #{val}"
+          return
+        end
+
+        klass = Familia::Base.features[val]
+
+        # Extend the Familia::Base subclass (e.g. Customer) with the feature module
+        include klass
+
+        # NOTE: We may also want to extend Familia::RedisType here so that we can
+        # call safe_dump on relations fields (e.g. list, set, zset, hashkey). Or
+        # maybe that only makes sense for hashk/object relations.
+        #
+        # We'd need to avoid it getting included multiple times (i.e. once for each
+        # Familia::Horreum subclass that includes the feature).
+
+        # Now that the feature is loaded successfully, add it to the list
+        # enabled features for Familia::Base classes.
+        @features_enabled << val
+      end
+
+      features_enabled
+    end
+
+  end
+
+end
+
+require_relative 'features/safe_dump'