permission_forge 0.14.1

data/lib/permission_forge/audit/subscribers.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Audit
+    # The notification subscribers the engine installs once configuration is
+    # final (Audit.install!). Each installer is a callable that receives the
+    # configuration and returns the subscriber it installed, or nil when its
+    # option is off:
+    #
+    #   Audit::Subscribers.register(:log, ->(config) {
+    #     ActiveSupport::Notifications.subscribe(/\.permission_forge\z/) { |event| ... } if config.audit_log_subscriber
+    #   })
+    #
+    # The log subscriber (config.audit_log_subscriber), the store subscriber
+    # and the adapters for the legacy on_rule_bypass / on_field_filtered hooks
+    # live in lib/permission_forge/audit/subscribers/ and register here.
+    #
+    # @api private
+    module Subscribers
+      @installers = {}
+      @installed = {}
+
+      class << self
+        def register(name, installer)
+          @installers[name.to_sym] = installer
+        end
+
+        # Idempotent: an installer whose subscriber is in place is not called again.
+        def install!(configuration = PermissionForge.configuration)
+          @installers.each do |name, installer|
+            next if @installed.key?(name)
+
+            subscriber = installer.call(configuration)
+            @installed[name] = subscriber if subscriber
+          end
+        end
+
+        def installed?(name)
+          @installed.key?(name.to_sym)
+        end
+
+        def uninstall!(name)
+          subscriber = @installed.delete(name.to_sym)
+          ActiveSupport::Notifications.unsubscribe(subscriber) if subscriber
+        end
+
+        # Removes every installed subscriber (tests; a configuration change).
+        def reset!
+          uninstall!(@installed.keys.first) until @installed.empty?
+        end
+
+        def names
+          @installers.keys
+        end
+      end
+    end
+  end
+end

data/lib/permission_forge/audit.rb

@@ -0,0 +1,302 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  # The one emitter of audit events.
+  #
+  #   PermissionForge::Audit.record('assignment.revoked', record: assignment, reason: 'left the team')
+  #   PermissionForge::Audit.instrument('access.denied') { { data: { 'model' => 'Customer', 'id' => 42 } } }
+  #
+  # `record` stores a change, admin or system event (when auditing is on) and
+  # publishes it as the "<event>.permission_forge" notification once the
+  # transaction it was recorded in has committed. `instrument` publishes a
+  # runtime (access) event and stores it only when its group is listed in
+  # `config.audit_runtime_events`; when nobody subscribes and the group is not
+  # stored it returns before building anything.
+  #
+  # Who, where and why come from the audit context (Audit::Context, set by
+  # `PermissionForge.with_audit_actor`, `Audit::Context.with` and the
+  # controllers), the record (Concerns::RecordsAuditEvents#audit_reference)
+  # and the payload (Audit::Recorder lists the keys).
+  #
+  # What happens when an event cannot be built or stored:
+  #   - `record` follows config.audit_change_failure_strategy. Under :raise
+  #     (default) an EventNotRecordedError is raised — out of the change's
+  #     callback, so the change rolls back — and the open transaction is made
+  #     to fail at commit (OpenTransaction#before_commit), so a caller that
+  #     rescues the error inside its own transaction cannot commit the change
+  #     without its record. Under :report / :log the event is written in a
+  #     savepoint (a failed INSERT must not abort the caller's transaction on
+  #     PostgreSQL), the failure is reported and the change goes through.
+  #   - `instrument` follows config.audit_hook_failure_strategy, always in a
+  #     savepoint: a denial is never allowed to break the request that was
+  #     denied.
+  #
+  # @api public
+  module Audit
+    # A change could not be recorded (audit_change_failure_strategy = :raise).
+    # `cause` is what building or storing the event raised. Raised twice at
+    # most: out of the change, and again at the commit of a transaction that
+    # rescued it.
+    #
+    # @api public
+    class EventNotRecordedError < StandardError
+      # @return [String, nil] the name of the event that could not be written
+      attr_reader :event
+
+      def initialize(message = nil, event: nil, at_commit: false)
+        @event = event
+        super(message || default_message(event, at_commit))
+      end
+
+      private
+
+      def default_message(event, at_commit)
+        if at_commit
+          "the transaction was rolled back at commit: the audit event #{event} of a change inside it could not be written"
+        else
+          "the audit event #{event} could not be written, so the change was not made"
+        end
+      end
+    end
+
+    # How long a missing table is believed before it is looked for again:
+    # a worker that started before the migration records once it has run.
+    MISSING_TABLE_RECHECK = 60
+
+    TABLE_CHECK_MUTEX = Mutex.new
+    FAILED = Object.new.freeze
+    private_constant :FAILED
+
+    @table_checks = {}
+    @warned_tables = {}
+    @missing_table_recheck = MISSING_TABLE_RECHECK
+
+    extend RuntimeEmission
+
+    class << self
+      # Seconds a missing table is believed before it is looked for again.
+      attr_accessor :missing_table_recheck
+
+      # @param event [String] a name from the catalogue (not an access event)
+      # @param payload [Hash] see Audit::Recorder
+      # @return [AuditEvent, nil] the stored event; nil when auditing is off
+      #   or the write failed under a non-raising audit_change_failure_strategy
+      # @raise [EventCatalog::UnknownEventError, ArgumentError, EventNotRecordedError]
+      def record(event, **payload)
+        entry = EventCatalog.fetch(event)
+        raise ArgumentError, "#{entry.name} is an access event: publish it with Audit.instrument" if entry.runtime?
+
+        emit(Recorder.new(entry, payload), store: enabled?, strategy: configuration.audit_change_failure_strategy, change: true)
+      end
+
+      # @param event [String] an access event of the catalogue
+      # @param payload [Hash] see Audit::Recorder; source defaults to 'runtime'
+      # @yieldreturn [Hash] more payload, built only when the event is stored
+      #   or someone listens — for hot paths:
+      #     Audit.instrument('field.access') { { record: record, data: { 'hidden' => hidden } } }
+      # @return [AuditEvent, nil] the stored event, when its group is stored
+      #
+      # Published at once, stored now or when the open transaction has ended
+      # (committed or rolled back); nothing while this thread is already
+      # emitting a runtime event. See Audit::RuntimeEmission.
+      def instrument(event, **payload, &)
+        entry = EventCatalog.fetch(event)
+        raise ArgumentError, "#{entry.name} is a #{entry.category} event: store it with Audit.record" unless entry.runtime?
+
+        light = Gate.for(entry.name).direct_listeners
+        return instrument_light(entry, light, payload, &) if light
+
+        storing, listening = runtime_plan(entry)
+        return unless storing || listening
+
+        instrument_runtime(entry, payload, store: storing, &)
+      end
+
+      # Whether instrumenting this event would do anything right now: its
+      # group is stored, or someone listens — and this thread is not already
+      # emitting one. For callers whose payload is expensive to gather.
+      #
+      # @param event [String] an access event of the catalogue
+      # @return [Boolean]
+      def instrument?(event)
+        entry = EventCatalog.fetch(event)
+        entry.runtime? && Gate.for(entry.name).open? && !emitting? &&
+          ((configuration.store_runtime_group?(entry.runtime_group) && enabled?) || listening?(entry))
+      end
+
+      # Whether events are stored: config.audit_events, and under :auto
+      # whether the table exists. A table that exists is remembered for the
+      # process; one that does not is looked for again after
+      # MISSING_TABLE_RECHECK seconds (reset! forgets at once).
+      #
+      # @param configuration [Configuration]
+      # @return [Boolean]
+      def enabled?(configuration = PermissionForge.configuration)
+        case configuration.audit_events
+        when true then true
+        when false then false
+        else table_available?
+        end
+      end
+
+      # Gives every event inside the block one correlation id (an outer block's
+      # id, else `id`, else a new one).
+      #
+      #   PermissionForge::Audit.correlate { change_set.apply! }
+      #
+      # @return the value of the block
+      def correlate(id = nil, &)
+        Context.with(correlation_id: Context[:correlation_id] || id || new_id, &)
+      end
+
+      # Logs the boot warning when :auto finds no table. Called by the engine
+      # once the database is reachable.
+      def verify_table!
+        enabled? if configuration.audit_events == :auto
+      end
+
+      # Forgets the table check and empties the context of this thread (tests,
+      # after a migration in the same process).
+      def reset!
+        TABLE_CHECK_MUTEX.synchronize do
+          @table_checks = {}
+          @warned_tables = {}
+        end
+        Context.reset!
+        Runtime.reset!
+      end
+
+      # Installs the notification subscribers and the executor hook of the
+      # gem's execution state (ExecutionState.install!): at the end of every
+      # executor run (request, job) whatever the run added to the audit
+      # context, to what runtime events remember for one request (Runtime)
+      # and to every block-scoped slot is removed — a request or a job ends
+      # with them empty. Called by the engine once configuration is final.
+      def install!(app)
+        Gate.install!
+        Subscribers.install!(configuration)
+        ExecutionState.install!(app)
+      end
+
+      # @return [String] a fresh id from `config.uuid_generator`
+      # @api private
+      def new_id
+        configuration.uuid_generator.call
+      end
+
+      # @param entry [EventCatalog::Entry]
+      # @return [Boolean] whether anyone subscribes to the event's notification
+      def listening?(entry)
+        ActiveSupport::Notifications.notifier.listening?(entry.notification)
+      end
+
+      private
+
+      def configuration
+        PermissionForge.configuration
+      end
+
+      # [whether the event is stored, whether anyone listens]. The cheap
+      # answers first; the table is consulted only for a group that is stored.
+      def runtime_plan(entry)
+        return [false, false] unless Gate.for(entry.name).open?
+
+        storing = configuration.store_runtime_group?(entry.runtime_group)
+        listening = listening?(entry)
+        return [false, false] unless storing || listening
+
+        [storing && enabled?, listening]
+      end
+
+      def emit(recorder, store:, strategy:, change:)
+        stored = write(recorder, store: store, strategy: strategy, change: change)
+        return if stored.equal?(FAILED)
+
+        publish(recorder, stored)
+        stored
+      end
+
+      # Builds the event once and stores it, in a savepoint: a failed INSERT
+      # aborts the transaction it ran in on PostgreSQL, and the caller's
+      # transaction must stay usable — to go on under :report / :log, and to
+      # fail at its commit under :raise rather than at its next statement.
+      # Whatever fails here — resolving the actor, a payload that cannot be
+      # read, the INSERT — follows `strategy`.
+      #
+      # @return [AuditEvent, nil, FAILED]
+      def write(recorder, store:, strategy:, change:)
+        recorder.attributes
+        return nil unless store
+
+        PermissionForge::AuditEvent.transaction(requires_new: true) { recorder.store! }
+      rescue StandardError => e
+        raise_not_recorded(recorder, e) if change && strategy == :raise
+
+        Failure.handle(e, strategy: strategy, operation: :store, event: recorder.name)
+        FAILED
+      end
+
+      # The change must not be committed: raise out of its callback, and make
+      # the transaction it runs in fail at commit for a caller that rescues.
+      def raise_not_recorded(recorder, error)
+        OpenTransaction.current&.before_commit do
+          raise EventNotRecordedError.new(event: recorder.name, at_commit: true), cause: error
+        end
+        raise EventNotRecordedError.new(event: recorder.name)
+      end
+
+      # After the open transaction commits (never after a rollback), else now.
+      def publish(recorder, stored)
+        return unless listening?(recorder.entry)
+
+        payload = recorder.notification_payload(stored)
+        transaction = OpenTransaction.current
+        if transaction
+          transaction.after_commit { notify(recorder.entry, payload) }
+        else
+          notify(recorder.entry, payload)
+        end
+      end
+
+      def notify(entry, payload)
+        ActiveSupport::Notifications.instrument(entry.notification, payload)
+      rescue StandardError => e
+        Failure.handle(e, strategy: configuration.audit_hook_failure_strategy, operation: :publish, event: entry.name)
+      end
+
+      # A table that was found is remembered without taking the lock. A
+      # missing one is believed for MISSING_TABLE_RECHECK seconds; a database
+      # that cannot be reached counts as no table and is asked again next time.
+      def table_available?
+        name = PermissionForge::AuditEvent.table_name
+        return true if @table_checks[name] == true
+
+        TABLE_CHECK_MUTEX.synchronize do
+          cached = @table_checks[name]
+          return true if cached == true
+          return false if cached.is_a?(Numeric) && Process.clock_gettime(Process::CLOCK_MONOTONIC) - cached < missing_table_recheck
+
+          check_table(name)
+        end
+      end
+
+      def check_table(name)
+        if PermissionForge::AuditEvent.table_exists?
+          @table_checks[name] = true
+        else
+          @table_checks[name] = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          warn_missing_table(name) unless @warned_tables[name]
+          @warned_tables[name] = true
+          false
+        end
+      rescue ActiveRecord::NoDatabaseError, ActiveRecord::ConnectionNotEstablished => e
+        Rails.logger&.warn("[PermissionForge] cannot check for the audit table '#{name}': #{e.class}") if defined?(Rails)
+        false
+      end
+
+      def warn_missing_table(name)
+        Rails.logger.warn(BootWarnings.missing_table(name)) if defined?(Rails) && Rails.logger
+      end
+    end
+  end
+end

data/lib/permission_forge/boot_checks.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  # What the engine checks while the host app boots: run (from
+  # config.after_initialize) and ensure_tenancy_gem! (from an initializer).
+  #
+  # The configuration checks need nothing. The database steps are advisory
+  # warnings or idempotent work, and they must never abort a boot: a Docker
+  # build precompiles assets with no database, a worker can start while the
+  # database fails over. The database is pinged once (db_available?); a step
+  # that loses it midway is skipped (DATABASE_STEP_ERRORS) and the next step
+  # runs. Anything else a step raises (a ConfigurationError) still stops the
+  # boot.
+  #
+  # @api private
+  module BootChecks
+    # Errors that mean "the database is not there (yet)": gone, refused, not
+    # created, not migrated.
+    DATABASE_STEP_ERRORS = [ActiveRecord::ConnectionNotEstablished, ActiveRecord::StatementInvalid].freeze
+
+    # The boot steps that read the database, in order. Each runs on its
+    # own: one that loses the database is skipped (database_step).
+    DATABASE_STEPS = {
+      unmasked_gdpr_fields: ->(config) { warn_unmasked_gdpr_fields(config) unless config.gdpr_defaults },
+      conditional_sets: ->(config) { warn_conditional_sets_without_context(config) },
+      join_rules: ->(config) { QueryScopingWarnings.warn_join_rules_not_auto_scoped(config) },
+      row_level_security: ->(config) { QueryScopingWarnings.warn_rls_misconfiguration(config) },
+      # The missing-table warning, auditing switched off, one shared login.
+      audit: ->(config) { Audit::BootWarnings.call(config) },
+      # The audit settings in force, when they differ from the last recorded
+      # ones. Never in the test environment (it is invoked directly there).
+      audit_settings: ->(_config) { Audit::SettingsObserver.call unless Rails.env.test? },
+      # Auto-applied masking (MaskedModels), kept in step by MaskingSync.
+      masked_attributes: ->(_config) { MaskingSync.boot! }
+    }.freeze
+
+    class << self
+      # @param config [Configuration]
+      def run(config)
+        config.validate_gdpr_explicit_choice!
+        warn_configuration(config)
+        return database_unreachable unless db_available?
+
+        DATABASE_STEPS.each { |name, step| database_step(name) { step.call(config) } }
+      end
+
+      # HasTenantScoping silently skips the scope when the gem is absent,
+      # which would leave every tenant's permission data visible to every
+      # other tenant — refuse to boot instead.
+      #
+      # @param config [Configuration]
+      # @raise [ConfigurationError]
+      def ensure_tenancy_gem!(config)
+        return unless config.tenant_enabled?
+        return if defined?(::ActsAsTenant)
+
+        raise PermissionForge::ConfigurationError,
+              "config.tenant_model is set to '#{config.tenant_model}' but the acts_as_tenant gem is not loaded. " \
+              'Add `gem "acts_as_tenant"` to your Gemfile, or set config.tenant_model = nil.'
+      end
+
+      # Conditional permission sets (session flag / IP / login hours) with a
+      # request_context_resolver that returns an empty context evaluate as
+      # unconditional (always active) unless conditional_sets_strict_mode is on.
+      def warn_conditional_sets_without_context(config)
+        # Strict mode denies conditional sets under blank context (fail closed),
+        # so the always-active footgun doesn't apply — no warning needed.
+        return if config.conditional_sets_strict_mode
+
+        conditional_sets = PermissionForge::PermissionSet.conditional
+        return unless conditional_sets.exists?
+        return unless resolved_context(config).empty?
+
+        Rails.logger.warn '[PermissionForge] SECURITY warning: ' \
+                          "#{conditional_sets.count} permission set(s) use activation conditions " \
+                          '(session flag, allowed_ips, or login hours) but request_context_resolver ' \
+                          'returns empty context. These sets will evaluate as unconditional ' \
+                          '(ALWAYS ACTIVE) — IP/hours/consent restrictions are NOT enforced. ' \
+                          'Configure config.request_context_resolver, or set ' \
+                          'config.conditional_sets_strict_mode = true to fail closed.'
+      rescue ActiveRecord::StatementInvalid
+        # Tables don't exist yet (pre-migration)
+      end
+
+      def warn_api_authorization_gap(config)
+        return unless config.api_enabled
+        return if config.api_require_authorization
+        return if config.api_action_authorization && config.api_assignment_authorization
+
+        Rails.logger&.warn '[PermissionForge] SECURITY warning: API is enabled, ' \
+                           'config.api_require_authorization is false and ' \
+                           'api_action_authorization / api_assignment_authorization is not set. ' \
+                           'api_auth only proves identity — any authenticated caller can create ' \
+                           'permission sets and assign them (privilege escalation). Configure both ' \
+                           'authorization lambdas, or remove api_require_authorization = false ' \
+                           '(the default, true, denies mutations until they are set).'
+      end
+
+      # One query for the distinct unmasked names (no record is built), and
+      # one more for the resource of the first match.
+      def warn_unmasked_gdpr_fields(config)
+        patterns = config.gdpr_field_patterns
+        return if patterns.blank?
+
+        unmasked = PermissionForge::ResourceField.where(mask_access: false)
+        name = unmasked.distinct.pluck(:name).find { |field_name| gdpr_match?(field_name, patterns) }
+        return unless name
+
+        resource = unmasked.where(name: name).first&.resource
+        Rails.logger.warn "[PermissionForge] GDPR warning: field '#{name}' on resource " \
+                          "'#{resource&.name}' matches GDPR pattern but is not masked. " \
+                          'Consider enabling gdpr_defaults or masking this field manually.'
+      rescue ActiveRecord::StatementInvalid
+        # Table doesn't exist yet (pre-migration)
+      end
+
+      private
+
+      # Connects and pings. `ActiveRecord::Base.connection` alone is not enough:
+      # since Rails 7.2 it hands back a connection that has not connected yet,
+      # so an unreachable database looked available.
+      def db_available?
+        PermissionForge::PermissionSet.connection_pool.with_connection(&:verify!)
+        true
+      rescue ActiveRecord::ActiveRecordError
+        false
+      end
+
+      def database_step(name)
+        yield
+      rescue *DATABASE_STEP_ERRORS => e
+        Rails.logger&.warn "[PermissionForge] Boot check #{name} skipped: the database could not be read (#{e.class})."
+      end
+
+      # The boot step did not run: the first request or job that reaches the
+      # database applies auto-applied masking (MaskingSync).
+      def database_unreachable
+        MaskingSync.reset!
+        Rails.logger&.warn '[PermissionForge] The database could not be reached at boot; the boot checks that ' \
+                           'read it (security warnings) were skipped. Auto-applied masking is applied at the first ' \
+                           'request or job that reaches the database.'
+      end
+
+      # The boot warnings that only read the configuration.
+      def warn_configuration(config)
+        warn_memory_cache_in_production(config)
+        warn_basic_auth_without_credentials(config)
+        warn_api_authorization_gap(config)
+        config.tenantless_admin_warning&.then { |message| Rails.logger&.warn(message) }
+        QueryScopingWarnings.warn_unscoped_detection_raise_in_production(config)
+      end
+
+      def warn_memory_cache_in_production(config)
+        return unless Rails.env.production? && config.cache_backend == :memory
+
+        Rails.logger&.warn '[PermissionForge] WARNING: Using in-process MemoryCache in production. ' \
+                           'Permissions will be inconsistent across Puma workers. ' \
+                           'Configure config.cache_backend = :rails_cache with Redis, Memcached, or SolidCache.'
+      end
+
+      def warn_basic_auth_without_credentials(config)
+        return unless config.http_basic_auth_enabled
+        return if config.http_basic_auth_user.present? && config.http_basic_auth_password.present?
+
+        Rails.logger&.warn '[PermissionForge] HTTP Basic Auth is enabled but credentials are not configured. ' \
+                           'The admin UI will return 401 for all requests. ' \
+                           'Set config.http_basic_auth_user and config.http_basic_auth_password.'
+      end
+
+      def gdpr_match?(field_name, patterns)
+        patterns.any? { |regex, _| field_name.match?(regex) }
+      end
+
+      # Taken as the per-read selection takes it: a Hash, or anything with
+      # #to_h (a Struct; nil is blank). A resolver that raises gives none.
+      def resolved_context(config)
+        resolved = config.request_context_resolver.call
+        resolved.is_a?(Hash) ? resolved : resolved.to_h
+      rescue StandardError
+        {}
+      end
+    end
+  end
+end

data/lib/permission_forge/cache/backlog.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Cache
+    # The invalidations this process could not get the store to confirm, kept
+    # so they can be made when the store answers again. An entry is listed by
+    # its stamp key: one per user (PermissionCacheAccessor), one for the
+    # managed-actions index (ControllerActions::ManagedIndex).
+    #
+    # Without it, an entry that should have been removed while the store was
+    # unreachable is a cache hit again as soon as the store is back, and
+    # stays one until cache_ttl. With it:
+    #
+    #   - a user listed here is not served from the store by this process:
+    #     the hash is rebuilt (PermissionCacheAccessor#pf_read_shared_permissions);
+    #     neither is the managed-actions index while it is listed;
+    #   - the listed invalidations are tried again after the next one the
+    #     store confirms, and before a hash is read from the store while the
+    #     list is not empty (Invalidation.retry_owed).
+    #
+    # This is extra effort on top of the failure report, not a guarantee. The
+    # list lives in this process: another process serves the entry as before,
+    # a restart forgets the list, and it holds LIMIT entries — the one owed
+    # longest is dropped for a new one. An edit to a set whose holders the
+    # store fails to invalidate (HolderInvalidation, during an outage) owes
+    # one entry per holder: past LIMIT holders only the last LIMIT are kept.
+    # For all of those cache_ttl remains the backstop, and every failure was
+    # reported when it happened.
+    #
+    # A pass over the list must not turn an outage — or the recovery from
+    # one — into a delay for one request: it tries PER_PASS entries at most
+    # (the next confirmed invalidation or store read goes on with the rest),
+    # it stops after GIVE_UP_AFTER failed tries, and after a failed try the
+    # next pass waits PAUSE seconds. A try that failed moves to the end of the
+    # list, so an entry whose key keeps failing cannot hold up the others.
+    #
+    # @api private
+    class Backlog
+      LIMIT = 500
+      PER_PASS = 25
+      GIVE_UP_AFTER = 3
+      PAUSE = 5
+
+      MONOTONIC = -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+
+      # @param clock [#call] seconds, monotonic
+      def initialize(clock: MONOTONIC)
+        @clock = clock
+        @entries = {}
+        @mutex = Mutex.new
+        @pass = Mutex.new
+        @paused_until = nil
+      end
+
+      # @return [Boolean] lock-free, for the path of every permission read
+      def empty?
+        @entries.empty?
+      end
+
+      # @param stamp_key [String] e.g. "user_1_invalidation"
+      # @return [Boolean]
+      def include?(stamp_key)
+        @mutex.synchronize { @entries.key?(stamp_key) }
+      end
+
+      # @param user_id [Object, nil] whose invalidation is owed (for the
+      #   report; nil for the managed-actions index)
+      # @param stamp_key [String] where its invalidation stamp lives: what the
+      #   entry is listed by
+      # @param keys [Array<String>] the cache keys that may still hold an entry
+      # @return [Boolean] whether this is news: false when the entry was listed
+      #   with all of these keys already
+      def add(user_id:, stamp_key:, keys:)
+        @mutex.synchronize do
+          known = @entries.delete(stamp_key)
+          keys |= known[:keys] if known
+          @entries[stamp_key] = { user_id: user_id, stamp_key: stamp_key, keys: keys }.freeze
+          @entries.shift while @entries.size > LIMIT
+          known.nil? || keys.size > known[:keys].size
+        end
+      end
+
+      # One pass over the list, unless one is running or the last one failed
+      # less than PAUSE seconds ago.
+      #
+      # @yieldparam entry [Hash] user_id:, stamp_key:, keys:
+      # @yieldreturn [Boolean] whether the store confirmed the invalidation
+      # @return [void]
+      def try_again(&)
+        return if paused? || !@pass.try_lock
+
+        begin
+          pause if pass(&).positive?
+        ensure
+          @pass.unlock
+        end
+      end
+
+      # @return [void]
+      def clear
+        @mutex.synchronize { @entries.clear }
+        @paused_until = nil
+      end
+
+      private
+
+      # @return [Integer] the tries that failed
+      def pass
+        failures = 0
+        @mutex.synchronize { @entries.values.first(PER_PASS) }.each do |entry|
+          break if failures >= GIVE_UP_AFTER
+
+          confirmed = yield(entry)
+          failures += 1 unless confirmed
+          settle(entry, confirmed)
+        end
+        failures
+      end
+
+      # Takes a confirmed entry off the list and moves a failed one to its
+      # end — unless a new failure of the same entry has replaced it meanwhile.
+      def settle(entry, confirmed)
+        stamp_key = entry[:stamp_key]
+        @mutex.synchronize do
+          next unless @entries[stamp_key].equal?(entry)
+
+          @entries.delete(stamp_key)
+          @entries[stamp_key] = entry unless confirmed
+        end
+      end
+
+      def paused?
+        paused_until = @paused_until
+        !paused_until.nil? && @clock.call < paused_until
+      end
+
+      def pause
+        @paused_until = @clock.call + PAUSE
+      end
+    end
+  end
+end