familia 1.0.0.pre.rc2 → 1.0.0.pre.rc4

data/lib/familia/tools.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Familia
+  module Tools
+    extend self
+    def move_keys(filter, source_uri, target_uri, &each_key)
+      raise "Source and target are the same (#{target_uri})" if target_uri == source_uri
+
+      Familia.connect target_uri
+      source_keys = Familia.redis(source_uri).keys(filter)
+      puts "Moving #{source_keys.size} keys from #{source_uri} to #{target_uri} (filter: #{filter})"
+      source_keys.each_with_index do |key, idx|
+        type = Familia.redis(source_uri).type key
+        ttl = Familia.redis(source_uri).ttl key
+        if source_uri.host == target_uri.host && source_uri.port == target_uri.port
+          Familia.redis(source_uri).move key, target_uri.db
+        else
+          case type
+          when 'string'
+            Familia.redis(source_uri).get key
+          when 'list'
+            Familia.redis(source_uri).lrange key, 0, -1
+          when 'set'
+            Familia.redis(source_uri).smembers key
+          else
+            raise Familia::Problem, "unknown key type: #{type}"
+          end
+          raise 'Not implemented'
+        end
+        yield(idx, type, key, ttl) unless each_key.nil?
+      end
+    end
+
+    # Use the return value from each_key as the new key name
+    def rename(filter, source_uri, target_uri = nil, &each_key)
+      target_uri ||= source_uri
+      move_keys filter, source_uri, target_uri if source_uri != target_uri
+      source_keys = Familia.redis(source_uri).keys(filter)
+      puts "Renaming #{source_keys.size} keys from #{source_uri} (filter: #{filter})"
+      source_keys.each_with_index do |key, idx|
+        Familia.trace :RENAME1, Familia.redis(source_uri), "#{key}", ''
+        type = Familia.redis(source_uri).type key
+        ttl = Familia.redis(source_uri).ttl key
+        newkey = yield(idx, type, key, ttl) unless each_key.nil?
+        Familia.trace :RENAME2, Familia.redis(source_uri), "#{key} -> #{newkey}", caller(1..1).first
+        Familia.redis(source_uri).renamenx key, newkey
+      end
+    end
+
+    def get_any(keyname, uri = nil)
+      type = Familia.redis(uri).type keyname
+      case type
+      when 'string'
+        Familia.redis(uri).get keyname
+      when 'list'
+        Familia.redis(uri).lrange(keyname, 0, -1) || []
+      when 'set'
+        Familia.redis(uri).smembers(keyname) || []
+      when 'zset'
+        Familia.redis(uri).zrange(keyname, 0, -1) || []
+      when 'hash'
+        Familia.redis(uri).hgetall(keyname) || {}
+      else
+        nil
+      end
+    end
+  end
+end

data/lib/familia/types/hashkey.rb

@@ -49,22 +49,23 @@ module Familia
     end
 
     def values
-      el = redis.hvals(rediskey)
-      multi_from_redis(*el)
+      elements = redis.hvals(rediskey)
+      multi_from_redis(*elements)
     end
 
     def hgetall
-      # TODO: Use from_redis. Also name `all` is confusing with
+      # TODO: Use from_redis. Also alias `all` is confusing with
       # Onetime::Customer.all which returns all customers.
       redis.hgetall rediskey
     end
     alias all hgetall
 
-    def has_key?(field)
+    def key?(field)
       redis.hexists rediskey, field
     end
-    alias include? has_key?
-    alias member? has_key?
+    alias has_key? key?
+    alias include? key?
+    alias member? key?
 
     def delete(field)
       redis.hdel rediskey, field
@@ -97,8 +98,8 @@ module Familia
     alias merge! update
 
     def values_at *fields
-      el = redis.hmget(rediskey, *fields.flatten.compact)
-      multi_from_redis(*el)
+      elements = redis.hmget(rediskey, *fields.flatten.compact)
+      multi_from_redis(*elements)
     end
 
     Familia::RedisType.register self, :hash # legacy, deprecated

data/lib/familia/types/list.rb

@@ -18,6 +18,7 @@ module Familia
       update_expiration
       self
     end
+    alias append push
 
     def <<(val)
       push val
@@ -31,6 +32,7 @@ module Familia
       update_expiration
       self
     end
+    alias prepend unshift
 
     def pop
       from_redis redis.rpop(rediskey)
@@ -63,8 +65,8 @@ module Familia
     alias del delete
 
     def range(sidx = 0, eidx = -1)
-      el = rangeraw sidx, eidx
-      multi_from_redis(*el)
+      elements = rangeraw sidx, eidx
+      multi_from_redis(*elements)
     end
 
     def rangeraw(sidx = 0, eidx = -1)

data/lib/familia/types/sorted_set.rb

@@ -75,8 +75,8 @@ module Familia
 
     def members(count = -1, opts = {})
       count -= 1 if count.positive?
-      el = membersraw count, opts
-      multi_from_redis(*el)
+      elements = membersraw count, opts
+      multi_from_redis(*elements)
     end
     alias to_a members
     alias all members
@@ -88,8 +88,8 @@ module Familia
 
     def revmembers(count = -1, opts = {})
       count -= 1 if count.positive?
-      el = revmembersraw count, opts
-      multi_from_redis(*el)
+      elements = revmembersraw count, opts
+      multi_from_redis(*elements)
     end
 
     def revmembersraw(count = -1, opts = {})
@@ -131,8 +131,8 @@ module Familia
 
     def range(sidx, eidx, opts = {})
       echo :range, caller(1..1).first if Familia.debug
-      el = rangeraw(sidx, eidx, opts)
-      multi_from_redis(*el)
+      elements = rangeraw(sidx, eidx, opts)
+      multi_from_redis(*elements)
     end
 
     def rangeraw(sidx, eidx, opts = {})
@@ -148,8 +148,8 @@ module Familia
 
     def revrange(sidx, eidx, opts = {})
       echo :revrange, caller(1..1).first if Familia.debug
-      el = revrangeraw(sidx, eidx, opts)
-      multi_from_redis(*el)
+      elements = revrangeraw(sidx, eidx, opts)
+      multi_from_redis(*elements)
     end
 
     def revrangeraw(sidx, eidx, opts = {})
@@ -159,8 +159,8 @@ module Familia
     # e.g. obj.metrics.rangebyscore (now-12.hours), now, :limit => [0, 10]
     def rangebyscore(sscore, escore, opts = {})
       echo :rangebyscore, caller(1..1).first if Familia.debug
-      el = rangebyscoreraw(sscore, escore, opts)
-      multi_from_redis(*el)
+      elements = rangebyscoreraw(sscore, escore, opts)
+      multi_from_redis(*elements)
     end
 
     def rangebyscoreraw(sscore, escore, opts = {})
@@ -171,8 +171,8 @@ module Familia
     # e.g. obj.metrics.revrangebyscore (now-12.hours), now, :limit => [0, 10]
     def revrangebyscore(sscore, escore, opts = {})
       echo :revrangebyscore, caller(1..1).first if Familia.debug
-      el = revrangebyscoreraw(sscore, escore, opts)
-      multi_from_redis(*el)
+      elements = revrangebyscoreraw(sscore, escore, opts)
+      multi_from_redis(*elements)
     end
 
     def revrangebyscoreraw(sscore, escore, opts = {})

data/lib/familia/types/string.rb

@@ -14,7 +14,7 @@ module Familia
     end
 
     def value
-      echo :value, caller[0..0] if Familia.debug
+      echo :value, caller(0..0) if Familia.debug
       redis.setnx rediskey, @opts[:default] if @opts[:default]
       from_redis redis.get(rediskey)
     end

data/lib/familia/types/unsorted_set.rb

@@ -23,8 +23,8 @@ module Familia
 
     def members
       echo :members, caller(1..1).first if Familia.debug
-      el = membersraw
-      multi_from_redis(*el)
+      elements = membersraw
+      multi_from_redis(*elements)
     end
     alias all members
     alias to_a members

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.rc2
+  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