permission_forge 0.14.1

data/lib/permission_forge/cache/invalidation.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Cache
+    # One invalidation of a user's cached permission hashes — or of the
+    # managed-actions index (ControllerActions::ManagedIndex): leaves a fresh
+    # stamp, then removes the keys — and checks what the store answers.
+    #
+    # The stamp is written BEFORE the keys are removed. A rebuild that read its
+    # rows before the commit is only dangerous when it stores its hash after
+    # the removal; it re-reads the stamp after storing, so with this order the
+    # new stamp is already there for it to see. Removing first would leave a
+    # gap: remove, the stale hash is stored, the rebuild sees the old stamp,
+    # and only then is the new stamp written — nothing would notice. (A rebuild
+    # that stores before the removal loses its entry to it; either way no
+    # pre-commit hash survives.) The keys are removed even when the stamp could
+    # not be written.
+    #
+    # A store that is unreachable does not raise: it answers false or nil. So every
+    # answer is checked, and an invalidation the store did not confirm is tried
+    # again, ATTEMPTS times in all. When it still fails it is reported
+    # (Cache::Failure) and not raised: the entry may then outlive the change
+    # until cache_ttl, and somebody has to know.
+    #
+    # A store that is down fails every call, and each one may wait for a
+    # timeout. After a failed invalidation the next ones therefore make a
+    # single attempt for RETRY_PAUSE seconds, which keeps a commit that
+    # invalidates many users from waiting three times as long for nothing.
+    #
+    # An invalidation that failed for good is still owed: it is put on the
+    # process's Backlog and made when the store answers again.
+    #
+    # @api private
+    class Invalidation
+      ATTEMPTS = 3
+      RETRY_PAUSE = 5
+
+      class << self
+        def call(...) = new(...).call
+
+        # @return [Boolean] whether a recent invalidation failed for good
+        def store_failing?
+          until_time = @failing_until
+          !until_time.nil? && now < until_time
+        end
+
+        def store_failed!
+          @failing_until = now + RETRY_PAUSE
+        end
+
+        def store_answered!
+          @failing_until = nil
+        end
+
+        # @return [Backlog] the invalidations this process still owes the store
+        def backlog
+          @backlog ||= Backlog.new
+        end
+
+        # Notes an invalidation the store did not confirm, to be made later.
+        #
+        # @return [Boolean] false when exactly this was owed already
+        def owe(user_id:, stamp_key:, keys:)
+          backlog.add(user_id: user_id, stamp_key: stamp_key, keys: keys)
+        end
+
+        # Whether an invalidation is still owed, after one more try to make
+        # the owed ones. Costs nothing while nothing is owed.
+        #
+        # @param stamp_key [String] the stamp key of the invalidation (one per
+        #   user, one for the managed-actions index)
+        # @return [Boolean]
+        def owed?(stamp_key)
+          owed = backlog
+          return false if owed.empty?
+
+          retry_owed
+          owed.include?(stamp_key)
+        end
+
+        # Tries the owed invalidations once each. Not while the store has just
+        # failed one: an outage must not add a failing call to every request.
+        # And not from inside an open database transaction: a store that
+        # shares the connection (Solid Cache in the application's database)
+        # would take the removals back if the transaction rolled back.
+        #
+        # @return [void]
+        def retry_owed
+          owed = backlog
+          return if owed.empty? || store_failing? || PermissionForge::OpenTransaction.current
+
+          owed.try_again { |entry| new(**entry).try_again }
+        end
+
+        # For tests, and for a cache store that has been replaced: what was
+        # owed to the old one is not owed to the new one.
+        def reset!
+          store_answered!
+          backlog.clear
+        end
+
+        private
+
+        def now
+          Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        end
+      end
+
+      # @param user_id [Object, nil] whose hashes are invalidated (for the
+      #   report; nil for an entry that belongs to no user)
+      # @param stamp_key [String] where the user's invalidation stamp lives
+      # @param keys [Array<String>] the cache keys to remove
+      def initialize(user_id:, stamp_key:, keys:, cache: PermissionForge.cache)
+        @user_id = user_id
+        @stamp_key = stamp_key
+        @keys = keys
+        @cache = cache
+        @error = nil
+      end
+
+      # @return [Boolean] whether the store confirmed the stamp and every removal
+      def call
+        attempts = self.class.store_failing? ? 1 : ATTEMPTS
+        confirmed = attempts.times.any? { attempt }
+        confirmed ? succeeded : failed(attempts)
+        confirmed
+      end
+
+      # One more try at an invalidation that failed for good. Without the
+      # stamp nothing is removed this time: every key was tried when it failed.
+      #
+      # @return [Boolean] whether the store confirmed the stamp and every removal
+      def try_again
+        stamp && @keys.all? { |key| answered? { @cache.expunge(key) } }
+      end
+
+      private
+
+      def attempt
+        stamped = stamp
+        # every key is tried, whatever happened to the stamp and to the keys before it
+        removed = @keys.map { |key| answered? { remove(key, confirm: stamped) } }
+        stamped && removed.all?
+      end
+
+      def stamp
+        answered? { @cache.write(@stamp_key, SecureRandom.hex(8), ttl: PermissionForge.configuration.cache_ttl) }
+      end
+
+      # Without the stamp the attempt has failed already: the key is deleted
+      # all the same, but not paid for a second time to confirm it.
+      def remove(key, confirm:)
+        return @cache.expunge(key) if confirm
+
+        @cache.delete(key)
+        false
+      end
+
+      def answered?
+        yield
+      rescue StandardError => e
+        @error = e
+        false
+      end
+
+      # The store answers: what is owed from before can be made now.
+      def succeeded
+        self.class.store_answered!
+        self.class.retry_owed
+      end
+
+      def failed(attempts)
+        invalidation = self.class
+        invalidation.store_failed!
+        invalidation.owe(user_id: @user_id, stamp_key: @stamp_key, keys: @keys)
+        Failure.report(operation: :invalidate, user_id: @user_id, keys: @keys, error: @error, attempts: attempts)
+      end
+    end
+  end
+end

data/lib/permission_forge/cache/memory_cache.rb

@@ -0,0 +1,77 @@
+module PermissionForge
+  module Cache
+    # In-process hash-backed cache. Intended for development, tests, and
+    # single-process deployments. Thread-safe via a Mutex so concurrent Puma
+    # threads can't corrupt the store, but still PROCESS-LOCAL: in a multi-worker
+    # deployment each worker has its own copy, so prefer :rails_cache (Redis,
+    # Memcached, SolidCache) in production. The engine logs a warning at boot if
+    # this backend is used in Rails.env.production?.
+    #
+    # @api public
+    class MemoryCache < Base
+      def initialize(prefix: 'pf')
+        super
+        @store = {}
+        @mutex = Mutex.new
+      end
+
+      def process_local?
+        true
+      end
+
+      # The entry under `key` (a deep copy, keys symbolized); nil when there
+      # is none or it has expired.
+      #
+      # @return [Object, nil]
+      def read(key)
+        entry = @mutex.synchronize { @store[prefixed_key(key)] }
+        return nil if entry.nil?
+
+        if entry.is_a?(Hash) && entry[:__expires_at__]
+          if Time.now >= entry[:__expires_at__]
+            @mutex.synchronize { @store.delete(prefixed_key(key)) }
+            return nil
+          end
+          value = entry[:__value__]
+        else
+          value = entry
+        end
+
+        # deep_dup for deep copy — callers can't mutate the cached object.
+        deep_symbolize(value.deep_dup)
+      end
+
+      # Stores a deep copy of `value`, expiring after `ttl` seconds (never
+      # without one).
+      #
+      # @return [Object] the value
+      def write(key, value, ttl: nil)
+        # dup on write too, so a caller mutating the object after write can't
+        # corrupt the stored copy.
+        stored = value.deep_dup
+        entry = ttl ? { __value__: stored, __expires_at__: Time.now + ttl } : stored
+        @mutex.synchronize { @store[prefixed_key(key)] = entry }
+        value
+      end
+
+      # @return [Object, nil] the entry removed, nil when there was none
+      def delete(key)
+        @mutex.synchronize { @store.delete(prefixed_key(key)) }
+      end
+
+      # Removes every entry of this process's store.
+      #
+      # @return [void]
+      def clear
+        @mutex.synchronize { @store.clear }
+      end
+
+      # rubocop:disable-next Naming/PredicateMethod -- removes the entries; the answer is whether the store could
+      def purge_entries(namespace)
+        regexp, = UserKeys.entry_patterns(namespace, prefix: prefix)
+        @mutex.synchronize { @store.delete_if { |key, _entry| key.match?(regexp) } }
+        true
+      end
+    end
+  end
+end

data/lib/permission_forge/cache/null_cache.rb

@@ -0,0 +1,40 @@
+module PermissionForge
+  module Cache
+    # A backend that stores nothing (config.cache_backend = :null): every read misses, so every
+    # permission check rebuilds its hash. For tests and debugging.
+    #
+    # @api public
+    class NullCache < Base
+      def initialize(prefix: 'pf')
+        super
+      end
+
+      # @return [nil] always a miss
+      def read(_key)
+        nil
+      end
+
+      # Nothing is kept, on purpose: that is not a failed write (false or nil
+      # would say so — see Base#write).
+      def write(_key, value, **)
+        value
+      end
+
+      # @return [nil] there is nothing to remove
+      def delete(_key)
+        nil
+      end
+
+      # @return [nil] there is nothing to remove
+      def clear
+        nil
+      end
+
+      # Nothing is kept: nothing is left either.
+      # rubocop:disable-next Naming/PredicateMethod -- removes the entries; the answer is whether the store could
+      def clear_entries(_namespace)
+        true
+      end
+    end
+  end
+end

data/lib/permission_forge/cache/rails_cache.rb

@@ -0,0 +1,231 @@
+module PermissionForge
+  module Cache
+    # Wraps any ActiveSupport::Cache::Store backend.
+    # Works with every cache store Rails supports out of the box:
+    #   - :memory_store
+    #   - :file_store
+    #   - :mem_cache_store (Memcached)
+    #   - :redis_cache_store (Redis)
+    #   - :solid_cache_store (SolidCache / Rails 8)
+    #   - :null_store
+    #   - Any custom ActiveSupport::Cache::Store subclass
+    #
+    # By default, uses Rails.cache. You can also pass a specific store instance.
+    #
+    # @api public
+    class RailsCache < Base
+      # Seconds the empty entry written by #expunge lives.
+      EMPTY_ENTRY_TTL = 1
+
+      # @return [Hash{String => Object}] the entries found, by prefixed key, symbolized as #read does
+      def read_multi(keys)
+        cache_store.read_multi(*keys.map { |key| prefixed_key(key) }).transform_values { |value| deep_symbolize(value) }
+      end
+
+      # Whether the store writes many entries in one call of its own, rather
+      # than ActiveSupport's default loop (which ignores each write's answer).
+      # Anything that is not an ActiveSupport store (a wrapper) is written key
+      # by key through its #write.
+      def self.multi_write?(store)
+        store.is_a?(ActiveSupport::Cache::Store) &&
+          store.class.instance_method(:write_multi_entries).owner != ActiveSupport::Cache::Store
+      end
+
+      def initialize(prefix: 'pf', store: nil)
+        super(prefix: prefix)
+        @store = store
+      end
+
+      # The entry under `key` in the Rails store, keys symbolized; nil for a
+      # miss (also what a store that failed the read answers).
+      #
+      # @return [Object, nil]
+      def read(key)
+        value = cache_store.read(prefixed_key(key))
+        return nil if value.nil?
+
+        deep_symbolize(value)
+      end
+
+      # Redis, Memcached and Solid Cache stores (and others built on
+      # ActiveSupport's LocalCache strategy) remember every read of a request,
+      # misses included. A nested local cache starts empty, so the read inside
+      # it reaches the store; what the request remembers is left as it is.
+      def read_fresh(key)
+        store = cache_store
+        return read(key) unless store.respond_to?(:with_local_cache)
+
+        store.with_local_cache { read(key) }
+      end
+
+      # One round trip for all the keys (read_multi), past the request's
+      # local copies as #read_fresh reads: a nested local cache starts empty.
+      def read_many(keys)
+        return {} if keys.empty?
+
+        store = cache_store
+        found = store.respond_to?(:with_local_cache) ? store.with_local_cache { read_multi(keys) } : read_multi(keys)
+        keys.to_h { |key| [key, found[prefixed_key(key)]] }
+      end
+
+      # Writes `value` under `key`, expiring after `ttl` seconds (the store's
+      # default expiry without one).
+      #
+      # @return [Boolean] the store's answer: false when it did not take it
+      def write(key, value, ttl: nil)
+        options = {}
+        options[:expires_in] = ttl if ttl
+        cache_store.write(prefixed_key(key), value, **options)
+      end
+
+      # Rails' :memory_store lives in each process.
+      def process_local?
+        cache_store.is_a?(ActiveSupport::Cache::MemoryStore)
+      end
+
+      # An explicit `expires_in: nil` overrides the store's default expiry.
+      def write_permanent(key, value)
+        cache_store.write(prefixed_key(key), value, expires_in: nil)
+      end
+
+      # @return [Boolean] the store's answer: false when there was nothing
+      #   to remove, or the delete failed (see #expunge)
+      def delete(key)
+        cache_store.delete(prefixed_key(key))
+      end
+
+      # A delete that reports true removed the entry. One that reports false
+      # either found nothing or failed (Redis, Memcached and Solid Cache stores
+      # rescue their errors), so the key is overwritten with an empty entry
+      # that expires at once: a write says plainly whether it succeeded, and a
+      # read of that entry is a miss like any other.
+      # rubocop:disable-next Naming/PredicateMethod -- removes the key; the answer is whether the store confirmed it
+      def expunge(key)
+        name = prefixed_key(key)
+        store = cache_store
+        return true if store.delete(name)
+
+        store.write(name, nil, expires_in: EMPTY_ENTRY_TTL) ? true : false
+      end
+
+      # One round trip for all the entries when the store sends them together
+      # (Redis pipelines them, Solid Cache writes them in one statement): its
+      # answer is then the answer for every key. Any other store (memory,
+      # file, Memcached, null) is written one key at a time through #write,
+      # as Base does.
+      def write_many(entries, ttl: nil, &)
+        return super unless multi_write?
+        return {} if entries.empty?
+
+        written = write_multi(entries, ttl, &)
+        entries.transform_values { written }
+      end
+
+      # Overwrites the keys with empty entries that expire at once (as
+      # #expunge does when a delete reports nothing), in one #write_many: a
+      # write says plainly whether it succeeded, where a multi-delete only
+      # counts what it removed. It also replaces the request's local copy of
+      # each entry, which ActiveSupport's LocalCache leaves in place for a
+      # multi-delete (it only hooks single deletes): a later read in the same
+      # request would still find the entry. A read of an empty entry is a
+      # miss like any other.
+      def expunge_many(keys, &)
+        return super unless multi_write?
+
+        write_many(keys.to_h { |key| [key, nil] }, ttl: EMPTY_ENTRY_TTL, &)
+      end
+
+      # Where the store writes many entries in one call, the keys are
+      # overwritten in that one call (#expunge_many — whose answer is not
+      # needed here); else one delete per key, as Base does.
+      def delete_many(keys, &)
+        return super unless multi_write?
+
+        expunge_many(keys, &)
+        nil
+      end
+
+      # Removes every entry under the prefix — where the store can match
+      # keys: Redis, memory and file stores. Solid Cache and Memcached stores
+      # have no delete_matched, so there this removes nothing and says so in
+      # the log (it answers false). On those, invalidate the users instead
+      # (User#invalidate_permissions), or change config.cache_key_prefix,
+      # which leaves the old entries to expire.
+      def clear
+        cache_store.delete_matched(prefix_matcher)
+      rescue NotImplementedError, ArgumentError
+        # Log loudly rather than silently no-op, so a "revoke everyone now"
+        # call isn't mistaken for success.
+        Rails.logger&.warn(
+          "[PermissionForge] cache clear removed nothing: #{cache_store.class} does not support " \
+          'delete_matched (Solid Cache and Memcached stores do not). Invalidate the users instead ' \
+          '(User#invalidate_permissions), or change config.cache_key_prefix and let the old entries expire.'
+        )
+        false
+      end
+
+      # Through the store's delete_matched: a Redis store takes a glob (its
+      # only form; the stamps go with the bare keys), the memory and file
+      # stores a Regexp (exact; the store's own namespace is put in front by
+      # ActiveSupport). A store that has no delete_matched (Memcached, Solid
+      # Cache) or refuses the matcher answers false. Whether the removal
+      # reached the keys is checked by Base#clear_entries.
+      def purge_entries(namespace)
+        entry_matchers(namespace).each { |matcher| cache_store.delete_matched(matcher) }
+        true
+      rescue NotImplementedError, ArgumentError
+        false
+      end
+
+      private
+
+      # A Redis store takes globs (its only form); the memory and file stores a Regexp (exact).
+      def entry_matchers(namespace)
+        regexp, globs = UserKeys.entry_patterns(namespace, prefix: prefix)
+        redis_store? ? globs : [regexp]
+      end
+
+      # Every key under the prefix: a glob for Redis; for the memory and file
+      # stores a Regexp anchored with `^` (the anchor ActiveSupport keeps when
+      # it puts the store's own namespace in front). A String there would be
+      # read as an unanchored Regexp ("pf:*" matches any key containing "pf")
+      # and raises on a namespaced store.
+      def prefix_matcher
+        redis_store? ? "#{prefix}:*" : /^#{Regexp.escape(prefix)}:/
+      end
+
+      def redis_store?
+        cache_store.class.name.to_s.include?('Redis')
+      end
+
+      def cache_store
+        @store || rails_cache
+      end
+
+      def multi_write?
+        self.class.multi_write?(cache_store)
+      end
+
+      # Whether the store took all the entries (HandledErrors.written); the
+      # error it handed its error handler, or raised, is yielded.
+      def write_multi(entries, ttl)
+        options = ttl ? { expires_in: ttl } : {}
+        store = cache_store
+        written, error = HandledErrors.written(store) do
+          store.write_multi(entries.transform_keys { |key| prefixed_key(key) }, options)
+        end
+        yield error if error && block_given?
+        written
+      rescue StandardError => e
+        yield e if block_given?
+        false
+      end
+
+      def rails_cache
+        raise 'Rails.cache is not available. Pass a store: option or ensure Rails is loaded.' unless defined?(Rails) && Rails.respond_to?(:cache)
+
+        Rails.cache
+      end
+    end
+  end
+end

data/lib/permission_forge/cache/rebuild.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Cache
+    # Stores a freshly built permission hash — or managed-actions index
+    # (ControllerActions::ManagedIndex) — unless it may have been built across
+    # an invalidation, in which case it is not left in the shared cache.
+    #
+    # The race: a rebuild reads the permission rows, a commit invalidates the
+    # user, and only then does the rebuild store what it read. Every
+    # invalidation leaves a per-user stamp (Cache::Invalidation); a rebuild
+    # reads the stamp before it builds and again after it stored. Only when
+    # both reads return the same stamp is the entry kept:
+    #
+    #   - the stamp changed: the entry is removed at once (the repeat may take
+    #     long, or raise) and the hash is built once more, ATTEMPTS times in all;
+    #   - there is no stamp: the rebuild writes one first and reads it back. A
+    #     missing stamp and a stamp that could not be read look the same, so a
+    #     rebuild never concludes anything from two empty reads;
+    #   - the store cannot keep a stamp (it is down, or it stores nothing): the
+    #     hash is built once and not stored;
+    #   - a store call raises (a store without a failsafe): taken as the
+    #     answer an ActiveSupport store gives instead — nothing read, nothing
+    #     written — so the request still gets the hash it built;
+    #   - anything raises along the way: the entry is removed.
+    #
+    # The caller gets the hash it built in every case. Whether the shared cache
+    # kept it is the second value.
+    #
+    # A hash that must not be shared at all — it was built inside a database
+    # transaction that reads from a snapshot (OpenTransaction.withholding) —
+    # is built without a single call to the store (#withhold).
+    #
+    # @api private
+    class Rebuild
+      # A rebuild that raced an invalidation is repeated once. Racing a second
+      # one is rare (two commits within two rebuilds), and repeating without a
+      # limit could keep a request busy for as long as records are being saved.
+      ATTEMPTS = 2
+
+      def self.call(...) = new(...).call
+
+      # @param key [String] the cache key of the hash
+      # @param stamp_key [String] where the user's invalidation stamp lives
+      # @param user_id [Object, nil] for the failure report
+      # @param build [#call] returns [hash, ttl]; reads the rows — past
+      #   ActiveRecord's query cache, or a repeat reads what the first build read
+      def initialize(key:, stamp_key:, user_id:, build:, cache: PermissionForge.cache)
+        @key = key
+        @stamp_key = stamp_key
+        @user_id = user_id
+        @build = build
+        @cache = cache
+      end
+
+      # @yieldreturn [Boolean] when a block is given, called after the stamp
+      #   was read and before the entry is written: false keeps the entry out
+      #   of the store (a variant whose index entry was not written)
+      # @return [Array(Hash, Boolean)] the hash as built, and whether the shared
+      #   cache kept it
+      def call(&before_write)
+        @before_write = before_write
+        hash = nil
+        ATTEMPTS.times do
+          hash, outcome = attempt(current_stamp)
+          return [hash, true] if outcome == :kept
+          break unless outcome == :overtaken
+        end
+        [hash, false]
+      end
+
+      # Builds and leaves the store alone: no read, no write, no removal. An
+      # entry that is there stays there — it holds committed rows, and
+      # whoever changes them invalidates it after the commit.
+      #
+      # @return [Hash] the hash as built
+      def withhold
+        @build.call.first
+      end
+
+      private
+
+      # The stamp to check against: the one in the store, or a new one when
+      # there is none — nil when the store does not give it back.
+      def current_stamp
+        stamp = answered { @cache.read_fresh(@stamp_key) }
+        return stamp if stamp
+
+        stamp = SecureRandom.hex(8)
+        written = answered { @cache.write(@stamp_key, stamp, ttl: PermissionForge.configuration.cache_ttl) }
+        stamp if written && answered { @cache.read_fresh(@stamp_key) } == stamp
+      end
+
+      # @return [Array(Hash, Symbol)] the hash and what became of it:
+      #   :kept, :overtaken (an invalidation happened meanwhile — worth another
+      #   attempt) or :not_stored (the store did not take it — repeating the
+      #   build would change nothing)
+      def attempt(stamp)
+        hash, ttl = @build.call
+        stored = stamp && ready_to_write? && answered { @cache.write(@key, hash, ttl: ttl) }
+        outcome = stored ? verify(stamp) : :not_stored
+        [hash, outcome]
+      ensure
+        # Without a stamp nothing was written. With one, a write was sent:
+        # also one the store said it did not take may have been applied.
+        discard if stamp && outcome != :kept
+      end
+
+      # What must happen before the entry is written, after the stamp was
+      # read (the block given to #call): an invalidation from then on either
+      # finds what it wrote or makes the verification fail.
+      def ready_to_write?
+        @before_write.nil? || answered { @before_write.call } ? true : false
+      end
+
+      # A stamp that cannot be read back is not verified, and not worth a
+      # second build either.
+      def verify(stamp)
+        current = answered { @cache.read_fresh(@stamp_key) }
+        return :not_stored if current.nil?
+
+        current == stamp ? :kept : :overtaken
+      end
+
+      # The store's answer; nil when the call raised.
+      def answered
+        yield
+      rescue StandardError
+        nil
+      end
+
+      # An entry this rebuild wrote and could not verify must not stay. When
+      # the store does not confirm its removal either, the removal is owed
+      # like an invalidation that failed (Backlog), and somebody has to know —
+      # once: while it is owed, the rebuilds that follow fail the same way.
+      def discard
+        removed = begin
+          @cache.expunge(@key)
+        rescue StandardError => e
+          error = e
+          false
+        end
+        return if removed || !Invalidation.owe(user_id: @user_id, stamp_key: @stamp_key, keys: [@key])
+
+        Failure.report(operation: :discard, user_id: @user_id, keys: [@key], error: error)
+      end
+    end
+  end
+end