familia 1.0.0.pre.rc3 → 1.0.0.pre.rc4

data/lib/familia/utils.rb

@@ -7,61 +7,116 @@ module Familia
 
   module Utils
 
-    def debug?
-      @debug == true
-    end
+  # Checks if debug mode is enabled
+  #
+  # e.g. Familia.debug = true
+  #
+  # @return [Boolean] true if debug mode is on, false otherwise
+  def debug?
+    @debug == true
+  end
 
-    def generate_id
-      input = SecureRandom.hex(32)  # 16=128 bits, 32=256 bits
-      Digest::SHA256.hexdigest(input).to_i(16).to_s(36) # base-36 encoding
-    end
+  # Generates a unique ID using SHA256 and base-36 encoding
+  # @param length [Integer] length of the random input in bytes (default: 32)
+  # @param encoding [Integer] base encoding for the output (default: 36)
+  # @return [String] a unique identifier
+  #
+  # @example Generate a default ID
+  #   Familia.generate_id
+  #   # => "kuk79w6uxg81tk0kn5hsl6pr7ic16e9p6evjifzozkda9el6z"
+  #
+  # @example Generate a shorter ID with 16 bytes input
+  #   Familia.generate_id(length: 16)
+  #   # => "z6gqw1b7ftzpvapydkt0iah0h0bev5hkhrs4mkf1gq4nq5csa"
+  #
+  # @example Generate an ID with hexadecimal encoding
+  #   Familia.generate_id(encoding: 16)
+  #   # => "d06a2a70cba543cd2bbd352c925bc30b0a9029ca79e72d6556f8d6d8603d5716"
+  #
+  # @example Generate a shorter ID with custom encoding
+  #   Familia.generate_id(length: 8, encoding: 32)
+  #   # => "193tosc85k3u513do2mtmibchpd2ruh5l3nsp6dnl0ov1i91h7m7"
+  #
+  def generate_id(length: 32, encoding: 36)
+    raise ArgumentError, "Encoding must be between 2 and 32" unless (1..32).include?(encoding)
+
+    input = SecureRandom.hex(length)
+    Digest::SHA256.hexdigest(input).to_i(16).to_s(encoding)
+  end
 
-    def join(*val)
-      val.compact.join(Familia.delim)
-    end
+  # Joins array elements with Familia delimiter
+  # @param val [Array] elements to join
+  # @return [String] joined string
+  def join(*val)
+    val.compact.join(Familia.delim)
+  end
 
-    def split(val)
-      val.split(Familia.delim)
-    end
+  # Splits a string using Familia delimiter
+  # @param val [String] string to split
+  # @return [Array] split elements
+  def split(val)
+    val.split(Familia.delim)
+  end
 
-    def rediskey(*val)
-      join(*val)
-    end
+  # Creates a Redis key from given values
+  # @param val [Array] elements to join for the key
+  # @return [String] Redis key
+  def rediskey(*val)
+    join(*val)
+  end
 
-    def redisuri(uri)
-      generic_uri = URI.parse(uri.to_s)
-
-      # Create a new URI::Redis object
-      redis_uri = URI::Redis.build(
-        scheme: generic_uri.scheme,
-        userinfo: generic_uri.userinfo,
-        host: generic_uri.host,
-        port: generic_uri.port,
-        path: generic_uri.path,
-        query: generic_uri.query,
-        fragment: generic_uri.fragment
-      )
-
-      redis_uri
-    end
+  # Converts a generic URI to a Redis URI
+  # @param uri [String, URI] URI to convert
+  # @return [URI::Redis] Redis URI object
+  def redisuri(uri)
+    generic_uri = URI.parse(uri.to_s)
+
+    # Create a new URI::Redis object
+    URI::Redis.build(
+      scheme: generic_uri.scheme,
+      userinfo: generic_uri.userinfo,
+      host: generic_uri.host,
+      port: generic_uri.port,
+      path: generic_uri.path,
+      query: generic_uri.query,
+      fragment: generic_uri.fragment
+    )
+  end
+
+  # Returns current time in UTC as a float
+  # @param name [Time] time object (default: current time)
+  # @return [Float] time in seconds since epoch
+  def Familia.now(name = Time.now)
+    name.utc.to_f
+  end
 
-    def now(name = Time.now)
-      name.utc.to_f
-    end
 
     # A quantized timestamp
-    # e.g. 12:32 -> 12:30
     #
-    def qnow(quantum = 10.minutes, now = Familia.now)
-      rounded = now - (now % quantum)
-      Time.at(rounded).utc.to_i
-    end
+    # @param quantum [Integer] The time quantum in seconds (default: 10 minutes).
+    # @param pattern [String, nil] The strftime pattern to format the timestamp.
+    # @param time [Integer, Float, Time, nil] A specific time to quantize (default: current time).
+    # @return [Integer, String] A unix timestamp or formatted timestamp string.
+    #
+    # @example
+    #   Familia.qstamp  # Returns an integer timestamp rounded to the nearest 10 minutes
+    #   Familia.qstamp(1.hour)  # Uses 1 hour quantum
+    #   Familia.qstamp(10.minutes, pattern: '%H:%M')  # Returns a formatted string like "12:30"
+    #   Familia.qstamp(10.minutes, time: 1302468980)  # Quantizes the given Unix timestamp
+    #   Familia.qstamp(10.minutes, time: Time.now)  # Quantizes the given Time object
+    #   Familia.qstamp(10.minutes, pattern: '%H:%M', time: 1302468980)  # Formats a specific time
+    #
+    def qstamp(quantum = 10.minutes, pattern: nil, time: nil)
+      time ||= Familia.now
+      time = time.to_f if time.is_a?(Time)
+
+      rounded = time - (time % quantum)
 
-    def qstamp(quantum = nil, pattern = nil, now = Familia.now)
-      quantum ||= ttl || 10.minutes
-      pattern ||= '%H%M'
-      rounded = now - (now % quantum)
-      Time.at(rounded).utc.strftime(pattern)
+      if pattern
+        Time.at(rounded).utc.strftime(pattern)
+      else
+        Time.at(rounded).utc.to_i
+      end
     end
 
     def generate_sha_hash(*elements)
@@ -80,13 +135,13 @@ module Familia
     def distinguisher(value_to_distinguish, strict_values = true)
       case value_to_distinguish
       when ::Symbol, ::String, ::Integer, ::Float
-        Familia.trace :TOREDIS_DISTINGUISHER, redis, "string", caller(1..1) if Familia.debug?
+        #Familia.trace :TOREDIS_DISTINGUISHER, redis, "string", caller(1..1) if Familia.debug?
         # Symbols and numerics are naturally serializable to strings
         # so it's a relatively low risk operation.
         value_to_distinguish.to_s
 
       when ::TrueClass, ::FalseClass, ::NilClass
-        Familia.trace :TOREDIS_DISTINGUISHER, redis, "true/false/nil", caller(1..1) if Familia.debug?
+        #Familia.trace :TOREDIS_DISTINGUISHER, redis, "true/false/nil", caller(1..1) if Familia.debug?
         # TrueClass, FalseClass, and NilClass are high risk because we can't
         # reliably determine the original type of the value from the serialized
         # string. This can lead to unexpected behavior when deserializing. For
@@ -99,7 +154,7 @@ module Familia
         value_to_distinguish.to_s #=> "true", "false", ""
 
       when Familia::Base, Class
-        Familia.trace :TOREDIS_DISTINGUISHER, redis, "base", caller(1..1) if Familia.debug?
+        #Familia.trace :TOREDIS_DISTINGUISHER, redis, "base", caller(1..1) if Familia.debug?
         if value_to_distinguish.is_a?(Class)
           value_to_distinguish.name
         else
@@ -107,14 +162,14 @@ module Familia
         end
 
       else
-        Familia.trace :TOREDIS_DISTINGUISHER, redis, "else1 #{strict_values}", caller(1..1) if Familia.debug?
+        #Familia.trace :TOREDIS_DISTINGUISHER, redis, "else1 #{strict_values}", caller(1..1) if Familia.debug?
 
         if value_to_distinguish.class.ancestors.member?(Familia::Base)
-          Familia.trace :TOREDIS_DISTINGUISHER, redis, "isabase", caller(1..1) if Familia.debug?
+          #Familia.trace :TOREDIS_DISTINGUISHER, redis, "isabase", caller(1..1) if Familia.debug?
           value_to_distinguish.identifier
 
         else
-          Familia.trace :TOREDIS_DISTINGUISHER, redis, "else2 #{strict_values}", caller(1..1) if Familia.debug?
+          #Familia.trace :TOREDIS_DISTINGUISHER, redis, "else2 #{strict_values}", caller(1..1) if Familia.debug?
           raise Familia::HighRiskFactor, value_to_distinguish if strict_values
           nil
         end

data/lib/familia/version.rb

@@ -1,4 +1,4 @@
-# rubocop:disable all
+# frozen_string_literal: true
 
 require 'yaml'
 
@@ -7,7 +7,7 @@ module Familia
     def self.to_s
       load_config
       version = [@version[:MAJOR], @version[:MINOR], @version[:PATCH]].join('.')
-      version += "-#{@version[:PRE]}" if @version[:PRE]
+      version = "#{version}-#{@version[:PRE]}" if @version[:PRE]
       version
     end
     alias inspect to_s

data/try/10_familia_try.rb

@@ -44,14 +44,14 @@ parsed_time = Familia.now(Time.parse('2011-04-10 20:56:20 UTC').utc)
 #=> [1302468980.0, true, true]
 
 ## Familia.qnow
-Familia.qnow 10.minutes, 1302468980
+Familia.qstamp 10.minutes, time: 1302468980
 #=> 1302468600
 
 ## Familia::Object.qstamp
-Limiter.qstamp 10.minutes, '%H:%M', 1302468980
+Limiter.qstamp(10.minutes, pattern: '%H:%M', time: 1302468980)
 #=> '20:50'
 
 ## Familia::Object#qstamp
 limiter = Limiter.new :request
-limiter.qstamp 10.minutes, '%H:%M', 1302468980
-##=> '20:50'
+limiter.qstamp(10.minutes, pattern: '%H:%M', time: 1302468980)
+#=> '20:50'

data/try/20_redis_type_try.rb

@@ -1,9 +1,7 @@
 
 require_relative '../lib/familia'
-require_relative '../lib/familia/features/quantizer'
 require_relative './test_helpers'
 
-#Familia.apiversion = 'v1'
 
 @limiter1 = Limiter.new :requests
 
@@ -24,7 +22,6 @@ p [@a.name, @b.name]
 @a.owners.frozen?
 #=> true
 
-
 ## Limiter#qstamp
 @limiter1.counter.qstamp(10.minutes, '%H:%M', 1302468980)
 ##=> '20:50'
@@ -35,8 +32,10 @@ p [@a.name, @b.name]
 
 ## Limiter#qstamp as a number
 @limiter2 = Limiter.new :requests
-@limiter2.counter.qstamp(10.minutes, pattern=nil, now=1302468980)
-##=> 1302468600
+p [@limiter1.ttl, @limiter2.ttl]
+p [@limiter1.counter.parent.ttl, @limiter2.counter.parent.ttl]
+@limiter2.counter.qstamp(10.minutes, pattern: nil, time: 1302468980)
+#=> 1302468600
 
 ## Redis Types can be stored to quantized numeric suffix. This
 ## tryouts is disabled b/c `RedisType#rediskey` takes no args
@@ -51,10 +50,14 @@ p [@a.name, @b.name]
 @limiter1.counter.increment
 #=> 1
 
-## Check ttl
+## Check counter ttl
 @limiter1.counter.ttl
 #=> 3600.0
 
+## Check limiter ttl
+@limiter1.ttl
+#=> 1800.0
+
 ## Check ttl for a different instance
 ## (this exists to make sure options are cloned for each instance)
 @limiter3 = Limiter.new :requests

data/try/26_redis_bool_try.rb

@@ -1,7 +1,7 @@
 require_relative '../lib/familia'
 require_relative './test_helpers'
 
-Familia.debug = true
+Familia.debug = false
 
 @hashkey = Familia::HashKey.new 'key'
 

data/try/27_redis_horreum_try.rb

@@ -1,7 +1,7 @@
 require_relative '../lib/familia'
 require_relative './test_helpers'
 
-Familia.debug = true
+Familia.debug = false
 
 @identifier = 'tryouts-27@onetimesecret.com'
 @customer = Customer.new @identifier

data/try/30_familia_object_try.rb

@@ -1,6 +1,7 @@
 require_relative '../lib/familia'
 require_relative './test_helpers'
-#Familia.apiversion = 'v1'
+
+Familia.debug = false
 
 @a = Bone.new 'atoken', 'akey'
 
@@ -36,7 +37,7 @@ Customer.values.all.collect(&:custid)
 ##=> ['delano']
 
 ## Familia.from_redis
-obj = Customer.from_redis :delano
+obj = Customer.from_identifier :delano
 [obj.class, obj.custid]
 #=> [Customer, 'delano']
 

data/try/40_customer_try.rb

@@ -18,7 +18,7 @@ require_relative './test_helpers'
 #=> true
 
 ## Customer can be retrieved by identifier
-retrieved_customer = Customer.from_redis("test@example.com")
+retrieved_customer = Customer.from_identifier("test@example.com")
 retrieved_customer.custid
 #=> "test@example.com"
 
@@ -35,7 +35,7 @@ retrieved_customer.custid
 @customer.planid = "premium"
 @customer.save
 ident = @customer.identifier
-Customer.from_redis(ident).planid
+Customer.from_identifier(ident).planid
 #=> "premium"
 
 ## Customer can increment secrets_created counter
@@ -90,7 +90,7 @@ Customer.instances.member?(@customer)
 
 ## Customer can be destroyed
 ret = @customer.destroy!
-cust = Customer.from_redis("test@example.com")
+cust = Customer.from_identifier("test@example.com")
 exists = Customer.exists?("test@example.com")
 [ret, cust.nil?, exists]
 #=> [true, true, false]

data/try/test_helpers.rb

@@ -3,8 +3,7 @@
 require 'digest'
 require_relative '../lib/familia'
 
-# ENV['FAMILIA_TRACE'] = '1'
-#Familia.debug = true
+Familia.debug = false # also # ENV['FAMILIA_TRACE'] = '1'
 Familia.enable_redis_logging = true
 Familia.enable_redis_counter = true
 
@@ -33,6 +32,7 @@ class Customer < Familia::Horreum
   ttl 5.years
 
   feature :safe_dump
+  #feature :expiration
   #feature :api_version
 
   # NOTE: The SafeDump mixin caches the safe_dump_field_map so updating this list
@@ -144,10 +144,13 @@ end
 
 class CustomDomain < Familia::Horreum
 
+  feature :expiration
+
   class_sorted_set :values, key: 'onetime:customdomain:values'
 
   identifier :derive_id
 
+
   field :display_domain
   field :custid
   field :base_domain
@@ -182,6 +185,10 @@ end
 
 class Limiter < Familia::Horreum
 
+  feature :expiration
+  feature :quantization
+
+  ttl 30.minutes
   identifier :name
   field :name
   # No :key field (so we can test hte behaviour in Horreum#initialize)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: familia
 version: !ruby/object:Gem::Version
-  version: 1.0.0.pre.rc3
+  version: 1.0.0.pre.rc4
 platform: ruby
 authors:
 - Delano Mandelbaum
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-08-17 00:00:00.000000000 Z
+date: 2024-08-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis
@@ -82,9 +82,8 @@ files:
 - lib/familia/core_ext.rb
 - lib/familia/errors.rb
 - lib/familia/features.rb
-- lib/familia/features/api_version.rb
-- lib/familia/features/atomic_saves.rb
-- lib/familia/features/quantizer.rb
+- lib/familia/features/expiration.rb
+- lib/familia/features/quantization.rb
 - lib/familia/features/safe_dump.rb
 - lib/familia/horreum.rb
 - lib/familia/horreum/class_methods.rb
@@ -99,6 +98,7 @@ files:
 - lib/familia/redistype/serialization.rb
 - lib/familia/refinements.rb
 - lib/familia/settings.rb
+- lib/familia/tools.rb
 - lib/familia/types/hashkey.rb
 - lib/familia/types/list.rb
 - lib/familia/types/sorted_set.rb

data/lib/familia/features/api_version.rb

@@ -1,19 +0,0 @@
-# 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

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

data/lib/familia/features/quantizer.rb

@@ -1,35 +0,0 @@
-# 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