low_card_tables 1.0.0

data/lib/low_card_tables/low_card_table/cache.rb

@@ -0,0 +1,214 @@
+module LowCardTables
+  module LowCardTable
+    # This class is responsible for caching all the rows for a given low-card table, and then returning various subsets
+    # of those rows on demand.
+    #
+    # This class is actually pretty simple, and it's largely for one big reason: our cache is very simple -- we cache
+    # the entire contents of the table, in memory, and the only way we update it is to throw out the entire cache and
+    # create a brand-new one. As such, from the inside, this class has no mechanisms whatsoever for updating the cache
+    # (as this object is thrown away and a whole new Cache object created when the cache is invalidated) nor are there
+    # any methods for worrying about what should be in cache, doing a LRU, or anything like that.
+    class Cache
+      # Creates a new Cache for the given +model_class+, which must be an ActiveRecord::Base subclass that has declared
+      # +is_low_card_table+.
+      #
+      # +options+ can contain:
+      #
+      # [:max_row_count] By default, the cache will raise a fatal error if trying to cache a low-card table that contains
+      #                  more than DEFAULT_MAX_ROW_COUNT (5,000) rows. This is provided so that we detect early on if you
+      #                  start storing data via the low-card system that is not, in fact, of low cardinality. However,
+      #                  if you really are using a low-card table properly and just happen to have more than 5,000
+      #                  distinct combinations of values, you can increase this limit via this option.
+      def initialize(model_class, options = { })
+        unless model_class.respond_to?(:is_low_card_table?) && model_class.is_low_card_table?
+          raise ArgumentError, "You must supply a class that is a model class for a low-card table, not #{model_class.inspect}."
+        end
+
+        @model_class = model_class
+        @options = options
+
+        fill!
+      end
+
+      # At what time was this cache loaded? This is used (in conjunction with a cache-expiration policy object) to
+      # determine if the cache is stale or not.
+      def loaded_at
+        @rows_read_at
+      end
+
+      # This behaves identically to #rows_matching, except that, everywhere a low-card model object would be returned,
+      # a simple integer ID is returned instead.
+      def ids_matching(hash_or_hashes = nil, &block)
+        matching = rows_matching(hash_or_hashes, &block)
+
+        out = case matching
+        when Array then matching.map(&:id)
+        when Hash then
+          h = { }
+          matching.each { |k,v| h[k] = v.map(&:id) }
+          h
+        when nil then nil
+        else raise "Unknown return value from #rows_matching; this should never happen: #{matching.inspect}"
+        end
+
+        out
+      end
+
+      # Returns an Array of all models of the low-card table in the cache. The order is undefined.
+      def all_rows
+        @rows_by_id.values
+      end
+
+      # Given a single numeric ID of a low-card row, returns that low-card model object.
+      #
+      # Given an Array of one or more IDs of low-card rows, returns a Hash mapping each of those IDs to the
+      # corresponding low-card model object.
+      #
+      # Raises LowCardTables::Errors::LowCardIdNotFoundError if any of the supplied IDs are not found in the cache.
+      # (It is up to calling code -- in our case, the RowManager -- to flush the cache and try again, if desired.)
+      def rows_for_ids(id_or_ids)
+        ids = Array(id_or_ids)
+
+        missing_ids = [ ]
+        out = { }
+
+        ids.each do |id|
+          r = @rows_by_id[id]
+          if r
+            out[id] = r
+          else
+            missing_ids << id
+          end
+        end
+
+        unless missing_ids.length == 0
+          raise LowCardTables::Errors::LowCardIdNotFoundError.new("Can't find IDs for low-card table #{@model_class.table_name}: #{missing_ids.join(", ")}", missing_ids)
+        end
+
+        if id_or_ids.kind_of?(Array)
+          out
+        else
+          out[id_or_ids]
+        end
+      end
+
+      # Returns a subset of rows in the cache that match a specified set of conditions. (This can be all rows or no
+      # rows, depending on the conditions, or any set in between.)
+      #
+      # You can specify conditions in the following ways:
+      #
+      # * A single Hash, passed as an argument. The return value will be an Array that contains zero or more instances
+      #   of the low-card model class. Only instances that have columns matching the specified Hash will be returned.
+      # * An array of one or more Hashes, passed as an argument. The return value will be a Hash; as keys, it will have
+      #   exactly the Hashes you passed in. The value for each key will be an array of zero or more instances of the
+      #   low-card model class, each of which matches the corresponding key.
+      # * A block, passed to the method as a normal Ruby block. The return value will be an Array that contains zero
+      #   or more instances of the low-card model class. The block will be invoked with every instance of the low-card
+      #   model class, and only those instances where the block returns a value that evaluates to true will be included.
+      #
+      # In the form where you pass in an array of one or more Hashes, it is possible for the same low-card row to show
+      # up in multiple values in the returned Hash, if it matches more than one of the supplied Hashes.
+      #
+      # Note that all matching is done via LowCardTables::LowCardTable::Base#_low_card_row_matches_any_hash?. See that
+      # method for more documentation -- by overriding it, you can change the behavior of this method.
+      def rows_matching(hash_or_hashes = nil, &block)
+        hashes = hash_or_hashes || [ ]
+        hashes = [ hashes ] unless hashes.kind_of?(Array)
+        hashes.each { |h| raise ArgumentError, "You must supply Hashes, not: #{h.inspect}" unless h.kind_of?(Hash) }
+
+        if block && hashes.length > 0
+          raise ArgumentError, "You can supply either one or more Hashes to match against OR a block, but not both. Hashes: #{hashes.inspect}; block: #{block.inspect}"
+        elsif (! block) && hashes.length == 0
+          raise ArgumentError, "You must supply either one or more Hashes to match against or a block; you supplied neither."
+        end
+
+
+        if hashes.length > 0
+          out = { }
+
+          hashes.each { |h| out[h] = [ ] }
+
+          @rows_by_id.each do |id,r|
+            hashes.each do |h|
+              out[h] << r if r._low_card_row_matches_any_hash?([ h.with_indifferent_access ])
+            end
+          end
+
+          if hash_or_hashes.kind_of?(Array)
+            out
+          else
+            out[hash_or_hashes]
+          end
+        else
+          @rows_by_id.values.select { |r| r._low_card_row_matches_block?(block) }
+        end
+      end
+
+      private
+      # Fills the cache. This can only ever be called once.
+      def fill!
+        # Explode if we don't have a unique index on the underlying table -- because then we have no way of
+        # guaranteeing that we won't create duplicate rows. (I am of the opinion that you'll never *truly* be certain
+        # that your data obeys rules unless they're in the database, as constraints; application code can be as
+        # careful as it wants to be, but, somehow, things always slip by unless you define constraints at the
+        # database layer.)
+        @model_class.low_card_ensure_has_unique_index!
+
+        raise "Cannot fill: we already have values!" if @rows_by_id
+
+        # We grab the time before we have fired off the query; this makes sure we don't create a race condition where
+        # we think the cache is just a tiny bit newer than it actually is.
+        read_rows_time = current_time
+
+        # We ask for one more than the number of rows we are willing to accept here; this is so that if we have
+        # too many rows, we can detect it, but we still won't do something crazy like try to load one million
+        # rows into memory.
+        raw_rows = @model_class.order("#{@model_class.primary_key} ASC").limit(max_row_count + 1).to_a
+        raise_too_many_rows_error if raw_rows.length > max_row_count
+
+        # Yes, we should never have duplicate IDs here -- it should be a primary key. But if it isn't for some reason,
+        # we want to explode right away, rather than failing in strange, unpredicatable, and awful ways later.
+        out = { }
+        raw_rows.each do |raw_row|
+          id = raw_row.id
+          raise_duplicate_id_error(id, out[id], raw_row) if out[id]
+          out[id] = raw_row
+        end
+
+        @rows_by_id = out
+        @rows_read_at = read_rows_time
+      end
+
+      # This is broken out into a separate method merely for ease of testing.
+      def current_time
+        Time.now
+      end
+
+      DEFAULT_MAX_ROW_COUNT = 5_000
+
+      def max_row_count
+        @options[:max_row_count] || DEFAULT_MAX_ROW_COUNT
+      end
+
+      def raise_too_many_rows_error
+        raise LowCardTables::Errors::LowCardTooManyRowsError, %{We tried to read in all the rows for low-card table '#{@model_class.table_name}', but there were
+more rows that we are willing to handle -- there are at least #{max_row_count + 1}.
+Most likely, something has gone horribly wrong with your low-card table (such as you
+starting to store data that is not, in fact, low-cardinality at all). Alternatively,
+perhaps you need to declare :max_row_count => (some larger value) in your
+is_low_card_table declaration.}
+      end
+
+      def raise_duplicate_id_error(id, row_one, row_two)
+        raise %{Duplicate ID in low-card table for class #{@model_class}!
+We have at least two rows with ID #{id.inspect}:
+
+#{row_one}
+
+and
+
+#{row_two}}
+      end
+    end
+  end
+end

data/lib/low_card_tables/low_card_table/cache_expiration/exponential_cache_expiration_policy.rb

@@ -0,0 +1,151 @@
+require 'active_support/time'
+
+module LowCardTables
+  module LowCardTable
+    module CacheExpiration
+      # If you don't understand the low-card cache and why cache-expiration policies are interesting and important,
+      # please read the Github Wiki page at https://github.com/ageweke/low_card_tables/wiki/Caching for more
+      # background first.
+      #
+      # An ExponentialCacheExpirationPolicy is by far the most sophisticated cache-expiration policy allowed. It breaks
+      # apart the cache-expiration time into three separate regions. In order, they are:
+      #
+      # * <b>Zero Floor</b>, an intitial period of time (which can be zero in length) during which the cache expires
+      #   immediately -- effectively meaning there is no cache;
+      # * <b>Exponential Increase</b>, where the cache-expiration time starts at a given minimum, and increases by
+      #   some geometric factor at each expiration thereafter;
+      # * <b>Maximum</b>, where the cache-expiration time tops out at a particular value.
+      #
+      # The idea is that, in any system with a significant amount of production traffic, the stable state has basically
+      # no new low-cardinality values being created at all -- any combination that can be created, will have already
+      # been created. (This is true for a very large number of systems; but, of course, it all depends on _your_
+      # particular system. It's possible you have a very "long-tailed" set of low-card values.)
+      #
+      # As such, it's safe to cache low-card tables for very long periods of time in the steady state. However, after
+      # a deploy that introduces code that can create never-before-seen combinations of low-card values, there will be
+      # new values created relatively rapidly, with the creation rate tapering off over time until we reach a steady
+      # state where no new values are created at all. This fits exactly the model of the
+      # ExponentialCacheExpirationPolicy.
+      #
+      # A word about measured timings:
+      #
+      # Measured timings are completely deterministic and do not depend on when the cache is actually accessed. That is,
+      # one way of implementing this class would be to only check and advance what period we're in when someone calls
+      # #stale? on it. However, this would mean that thinking about how the class works is very difficult: what time
+      # period we're in depends on how often someone has asked us whether we're stale or not.
+      #
+      # Instead, the start time of this object (that is, the time when the +:zero_floor+ begins) is passed in to the
+      # constructor, as +:start_time+. All time periods involved start from this point and are measured back-to-back --
+      # that is, the first exponential time period begins immediately upon completion of the +:zero_floor+ period, the
+      # next one immediately after that, and so on. (No, this doesn't happen in real time; there's no thread waiting
+      # around just to update this object. Rather, when needed, we determine which period we're in on-demand.)
+      class ExponentialCacheExpirationPolicy
+        # Creates a new instance. +options+ must be a Hash that can must contain:
+        #
+        # * +:start_time+: The time at which this caching policy should start -- _i.e._, the start time for the
+        #   zero floor. This must be a Time object.
+        #
+        # ...and can contain any of the following:
+        #
+        # * +:zero_floor_time+: The amount of time at the start that the cache will not cache anything; default is
+        #   three minutes.
+        # * +:min_time+: Once the zero floor has completed, the initial period during which the cache will be valid;
+        #   default is ten seconds.
+        # * +:exponent+: Once the initial +:min_time+ period has passed, subsequent periods will each geometrically
+        #   increase by this exponent. (For example, if :+min_time+ is 3.0, and +:exponent+ is 1.5, then the first
+        #   period will be 3.0 seconds; the second will be 3.0 * 1.5 = 4.5 seconds; the third will be 4.5 * 1.5 = 6.75
+        #   seconds; and so on.) Default is 2.0, meaning the validity time doubles.
+        # * +:max_time+: Once the cache validity period reaches +:max_time+ seconds, it is pinned at this value, and
+        #   will not increase further. Default is one hour.
+        def initialize(options)
+          options.assert_valid_keys(:zero_floor_time, :min_time, :exponent, :max_time, :start_time)
+
+          @start_time = options[:start_time]
+          raise ArgumentError, "start_time cannot be #{@start_time.inspect}" unless @start_time && @start_time.kind_of?(::Time)
+
+          @zero_floor = options[:zero_floor_time] || 3.minutes
+          @min_time = options[:min_time] || 10.seconds
+          @exponent = options[:exponent] || 2.0
+          @max_time = options[:max_time] || 1.hour
+
+          raise ArgumentError, "zero_floor_time cannot be #{@zero_floor.inspect}" unless @zero_floor.kind_of?(Numeric) && @zero_floor >= 0.0
+          raise ArgumentError, "min_time cannot be #{@min_time.inspect}" unless @min_time.kind_of?(Numeric) && @min_time > 1.0
+          raise ArgumentError, "exponent cannoot be #{@exponent.inspect}" unless @exponent.kind_of?(Numeric) && @exponent > 1.0
+          raise ArgumentError, "max_time cannot be #{@max_time.inspect}" unless @max_time.kind_of?(Numeric) && @max_time > 0.0 && @max_time > @min_time
+
+          # @segment_start_time is the time at which the current segment started.
+          # @segment_end_time is the time at which the current segment ends.
+          # @segment_expiration_time is the time at which the current cache will expire (absolute time, not relative);
+          #   typically this will be the same as @segment_end_time, but it's different (zero) during the initial
+          #   @min_time period.
+          @segment_start_time = @start_time
+
+          if @zero_floor > 0
+            @segment_end_time = @segment_start_time + @zero_floor
+            @segment_expiration_time = 0
+          else
+            @segment_end_time = @segment_start_time + @min_time
+            @segment_expiration_time = @min_time
+          end
+
+          # Let's just make sure the clock doesn't run backwards, shall we?
+          @last_seen_time = @start_time
+        end
+
+        attr_reader :zero_floor, :min_time, :exponent, :max_time
+
+        # Called by LowCardTables::LowCardTable::Cache; this indicates whether the cache is stale or not. In order to
+        # make testing easier, the time at which the cache was read (+cache_time+) and the current time (+current_time+)
+        # are passed in, rather than implied using +Time.now+.
+        #
+        # It is an error to call this method with a +current_time+ that is before a previously-seen +current_time+.
+        # (In other words, no, the clock can't run backwards.)
+        def stale?(cache_time, current_time)
+          if current_time < @last_seen_time
+            raise ArgumentError, "Our clock is running backwards?!? We have previously seen a time of #{@last_seen_time.to_f}, and now it's #{current_time.to_f}?"
+          elsif current_time > @last_seen_time
+            @last_seen_time = current_time
+          end
+
+          next_segment! until within_current_segment?(current_time)
+
+          out = if cache_time < @segment_start_time
+            true
+          else
+            (current_time - cache_time) >= @segment_expiration_time
+          end
+
+          out
+        end
+
+        private
+        attr_reader :start_time
+
+        # Are we within the current segment, according to @segment_start_time and @segment_end_time?
+        def within_current_segment?(cache_time)
+          cache_time < @segment_end_time
+        end
+
+        # Advances @segment_start_time, @segment_end_time, and @segment_expiration_time to the next segment.
+        def next_segment!
+          if @segment_expiration_time == 0
+            # We're in the initial @min_time segment -- advance to the first exponential.
+            @segment_start_time += @zero_floor
+            @segment_end_time = @segment_start_time + @min_time
+            @segment_expiration_time = @min_time
+          elsif @segment_expiration_time >= @max_time
+            # We're in the final @max_time -- simply create another period of that duration.
+            @segment_start_time = @segment_end_time
+            @segment_end_time = @segment_start_time + @max_time
+            @segment_expiration_time = @max_time
+          else
+            # We're in the exponential-increase period -- move to the next, longer, period.
+            @segment_start_time = @segment_end_time
+            @segment_expiration_time = [ @segment_expiration_time * @exponent, @max_time ].min
+            @segment_end_time = @segment_start_time + @segment_expiration_time
+          end
+        end
+      end
+    end
+  end
+end

data/lib/low_card_tables/low_card_table/cache_expiration/fixed_cache_expiration_policy.rb

@@ -0,0 +1,23 @@
+module LowCardTables
+  module LowCardTable
+    module CacheExpiration
+      # A FixedCacheExpirationPolicy is a very simple kind of cache-expiration policy: the cache expires a certain
+      # amount of time after it is filled, every time.
+      class FixedCacheExpirationPolicy
+        def initialize(expiration_time)
+          unless expiration_time && expiration_time.kind_of?(Numeric) && expiration_time >= 0.0
+            raise ArgumentError, "Expiration time must be a nonnegative number, not: #{expiration_time.inspect}"
+          end
+
+          @expiration_time = expiration_time
+        end
+
+        def stale?(cache_time, current_time)
+          (current_time - cache_time) >= @expiration_time
+        end
+
+        attr_reader :expiration_time
+      end
+    end
+  end
+end

data/lib/low_card_tables/low_card_table/cache_expiration/has_cache_expiration.rb

@@ -0,0 +1,100 @@
+require File.join(File.dirname(__FILE__), 'exponential_cache_expiration_policy')
+require File.join(File.dirname(__FILE__), 'fixed_cache_expiration_policy')
+require File.join(File.dirname(__FILE__), 'unlimited_cache_expiration_policy')
+require File.join(File.dirname(__FILE__), 'no_caching_expiration_policy')
+
+module LowCardTables
+  module LowCardTable
+    module CacheExpiration
+      # This is a module that gets mixed in to LowCardTables::LowCardTable::Base. It provides the class it gets mixed
+      # into with a #low_card_cache_expiration method that can be called with various values (a number, zero, +:unlimited+,
+      # or +:exponential+ with options) to set the cache-expiration policy, or called with no arguments to return the
+      # cache-expiration policy as one of those same values.
+      #
+      # The value is stored on a class-by-class basis, and is inherited. This provides the behavior we want: if you set
+      # a policy on LowCardTables::LowCardTable::Base, it will be applied to all low-card tables; if you set a policy
+      # on an individual table, it will apply to only that table and will override any policy applied to the base.
+      module HasCacheExpiration
+        extend ActiveSupport::Concern
+
+        module ClassMethods
+          # Sets the cache-expiration policy of this class. You can pass:
+          #
+          # * A positive number -- sets the cache-expiration policy to be that many seconds.
+          # * Zero -- turns off caching entirely.
+          # * +:unlimited+ -- makes the cache last forever.
+          # * :+exponential+, optionally with an options hash as the second argument -- sets the cache-expiration policy
+          #   to be exponential; see ExponentialCacheExpirationPolicy for more details.
+          #
+          # If you pass no arguments at all, you're returned the current cache-expiration policy.
+          #
+          # If you do not call this method at all, the cache-expiration policy will be undefined. You should always either
+          # call this method, or set up an inheritance chain using #low_card_cache_policy_inherits_from, to a class
+          # that does have it defined.
+          def low_card_cache_expiration(type_or_number = nil, options = { })
+            if type_or_number.nil?
+              @_low_card_cache_expiration_return_value || low_card_cache_expiration_inherited
+            else
+              if type_or_number == 0
+                @_low_card_cache_expiration_policy_object = LowCardTables::LowCardTable::CacheExpiration::NoCachingExpirationPolicy.new
+                @_low_card_cache_expiration_return_value = 0
+              elsif type_or_number.kind_of?(Numeric)
+                @_low_card_cache_expiration_policy_object = LowCardTables::LowCardTable::CacheExpiration::FixedCacheExpirationPolicy.new(type_or_number)
+                @_low_card_cache_expiration_return_value = type_or_number
+              elsif type_or_number == :unlimited
+                @_low_card_cache_expiration_policy_object = LowCardTables::LowCardTable::CacheExpiration::UnlimitedCacheExpirationPolicy.new
+                @_low_card_cache_expiration_return_value = :unlimited
+              elsif type_or_number == :exponential
+                @_low_card_cache_expiration_policy_object = LowCardTables::LowCardTable::CacheExpiration::ExponentialCacheExpirationPolicy.new(options.merge(:start_time => low_card_current_time))
+                if options.size > 0
+                  @_low_card_cache_expiration_return_value = [ :exponential, options ]
+                else
+                  @_low_card_cache_expiration_return_value = :exponential
+                end
+              else
+                raise ArgumentError, "Invalid cache expiration time argumnet '#{type_or_number.inspect}'; you must pass a number, :unlimited, or :exponential."
+              end
+            end
+          end
+
+          # For +low_card_tables+ internal use only. Returns the current cache-expiration policy object -- e.g., an
+          # instance of LowCardTables::LowCardTable::CacheExpiration::FixedCacheExpirationPolicy.
+          def low_card_cache_expiration_policy_object
+            @_low_card_cache_expiration_policy_object || low_card_cache_expiration_policy_object_inherited
+          end
+
+          # Declares that this class should inherit its cache-expiration policy from the specified other class, which
+          # must be a class that has had this module included in it (directly or indirectly) too. In other words, if
+          # you don't set a policy on this class, but have specified that it inherits its policy from the given other
+          # class, then it will use whatever policy the other class has set.
+          #
+          # We use this because low-card tables' classes all inherit directly from ::ActiveRecord::Base; they don't
+          # inherit from some parent "it's a low-card table" class. (This is because inheritance in ActiveRecord is
+          # used to denote data in common via STI, not what we're trying to do here.) So we use this to set up the
+          # default policy directly on the ::LowCardTables root module, and 'inherit' it into individual low-card tables
+          # (via the +included+ block on LowCardTables::LowCardTable::Base) this way.
+          def low_card_cache_policy_inherits_from(other_class)
+            @_low_card_cache_policy_inherits_from = other_class
+          end
+
+          private
+          # We break this into a separate method simply for ease of testing -- some of our specs override it.
+          def low_card_current_time
+            Time.now
+          end
+
+          # Returns the proper return value for #low_card_cache_expiration from the 'inherited' class, if there is one.
+          def low_card_cache_expiration_inherited
+            @_low_card_cache_policy_inherits_from.low_card_cache_expiration if @_low_card_cache_policy_inherits_from
+          end
+
+          # Returns the proper return value for #low_card_cache_expiration_policy_object from the 'inherited' class,
+          # if there is one.
+          def low_card_cache_expiration_policy_object_inherited
+            @_low_card_cache_policy_inherits_from.low_card_cache_expiration_policy_object if @_low_card_cache_policy_inherits_from
+          end
+        end
+      end
+    end
+  end
+end