userpattern 0.2.0

data/lib/userpattern/anonymizer.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require 'openssl'
+
+module UserPattern
+  # Produces a one-way anonymous session identifier that:
+  # - Is consistent within a single session/token lifetime (for per-session stats)
+  # - Rotates daily via a date-scoped salt (prevents cross-day correlation)
+  # - Cannot be reversed to recover user identity or session ID
+  class Anonymizer
+    DIGEST = 'SHA256'
+    TRUNCATE_LENGTH = 16
+
+    def self.anonymize(request)
+      raw = session_fingerprint(request)
+      daily_salt = "#{UserPattern.configuration.anonymous_salt}:#{Date.current.iso8601}"
+      OpenSSL::HMAC.hexdigest(DIGEST, daily_salt, raw)[0, TRUNCATE_LENGTH]
+    end
+
+    class << self
+      private
+
+      def session_fingerprint(request)
+        detection = UserPattern.configuration.session_detection
+
+        case detection
+        when :auto, nil then auto_detect(request)
+        when :session   then session_based(request)
+        when :header    then header_based(request)
+        when Proc       then detection.call(request).to_s
+        end
+      end
+
+      def auto_detect(request)
+        if request.headers['Authorization'].present?
+          header_based(request)
+        elsif request.respond_to?(:session) && request.session.respond_to?(:id) && request.session.id.present?
+          session_based(request)
+        else
+          request.remote_ip.to_s
+        end
+      end
+
+      def session_based(request)
+        request.session.id.to_s
+      end
+
+      def header_based(request)
+        request.headers['Authorization'].to_s
+      end
+    end
+  end
+end

data/lib/userpattern/buffer.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require 'concurrent'
+
+module UserPattern
+  # Thread-safe in-memory buffer that batches request events before flushing
+  # to the database. Minimizes per-request overhead to a single array push.
+  class Buffer
+    MAX_DRAIN = 1_000
+
+    def initialize
+      @queue = Concurrent::Array.new
+      @flushing = Concurrent::AtomicBoolean.new(false)
+      start_timer
+    end
+
+    def push(event)
+      @queue << event
+      flush_async if @queue.size >= UserPattern.configuration.buffer_size
+    end
+
+    def flush
+      return if @queue.empty?
+      return unless @flushing.make_true
+
+      persist_events
+    ensure
+      @flushing.make_false
+    end
+
+    def shutdown
+      @timer&.shutdown
+      flush
+    end
+
+    def size
+      @queue.size
+    end
+
+    private
+
+    def persist_events
+      events = drain_queue
+      return if events.empty?
+
+      now = Time.current
+      rows = events.map { |e| e.merge(created_at: now) }
+      UserPattern::RequestEvent.insert_all(rows)
+    rescue StandardError => e
+      Rails.logger.error("[UserPattern] Flush error: #{e.message}")
+    end
+
+    def drain_queue
+      events = []
+      events << @queue.shift until @queue.empty? || events.size >= MAX_DRAIN
+      events
+    end
+
+    def flush_async
+      Thread.new { flush }
+    end
+
+    def start_timer
+      @timer = Concurrent::TimerTask.new(
+        execution_interval: UserPattern.configuration.flush_interval
+      ) { flush }
+      @timer.execute
+    end
+  end
+end

data/lib/userpattern/configuration.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module UserPattern
+  class Configuration
+    attr_reader :tracked_models
+
+    attr_accessor :flush_interval, :buffer_size,
+                  :retention_period, :anonymous_salt,
+                  :session_detection, :enabled, :ignored_paths,
+                  :mode, :threshold_multiplier, :threshold_refresh_interval,
+                  :block_unknown_endpoints, :on_threshold_exceeded,
+                  :violation_actions, :logout_method, :rate_limiter_store
+
+    attr_writer :dashboard_auth
+
+    def initialize
+      @tracked_models = [{ name: 'User', current_method: :current_user }]
+      @flush_interval = 30
+      @buffer_size = 100
+      @retention_period = 30
+      @dashboard_auth = nil
+      @anonymous_salt = nil
+      @session_detection = :auto
+      @enabled = true
+      @ignored_paths = []
+      initialize_alert_defaults
+    end
+
+    def alert_mode?
+      @mode == :alert
+    end
+
+    def dashboard_auth
+      @dashboard_auth || default_dashboard_auth
+    end
+
+    def tracked_models=(list)
+      @tracked_models = list.map do |entry|
+        name = entry[:name].to_s
+        method = entry[:current_method] || :"current_#{name.underscore}"
+        { name: name, current_method: method }
+      end
+    end
+
+    def ignored?(path)
+      ignored_paths.any? do |pattern|
+        case pattern
+        when Regexp then pattern.match?(path)
+        when String then pattern == path
+        end
+      end
+    end
+
+    private
+
+    def initialize_alert_defaults
+      @mode = :collection
+      @threshold_multiplier = 1.5
+      @threshold_refresh_interval = 300
+      @block_unknown_endpoints = false
+      @on_threshold_exceeded = nil
+      @violation_actions = [:raise]
+      @logout_method = nil
+      @rate_limiter_store = nil
+    end
+
+    def default_dashboard_auth
+      user = ENV.fetch('USERPATTERN_DASHBOARD_USER', nil)
+      pass = ENV.fetch('USERPATTERN_DASHBOARD_PASSWORD', nil)
+      return locked_dashboard_auth unless user && pass
+
+      basic_auth_lambda(user, pass)
+    end
+
+    def locked_dashboard_auth
+      lambda {
+        render plain: 'Dashboard locked. Set USERPATTERN_DASHBOARD_USER and ' \
+                      'USERPATTERN_DASHBOARD_PASSWORD environment variables, ' \
+                      'or configure a custom dashboard_auth.',
+               status: :forbidden
+      }
+    end
+
+    def basic_auth_lambda(user, pass)
+      lambda {
+        authenticate_or_request_with_http_basic('UserPattern') do |provided_user, provided_pass|
+          ActiveSupport::SecurityUtils.secure_compare(provided_user, user) &
+            ActiveSupport::SecurityUtils.secure_compare(provided_pass, pass)
+        end
+      }
+    end
+  end
+end

data/lib/userpattern/controller_tracking.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require 'userpattern/anonymizer'
+require 'userpattern/path_normalizer'
+
+module UserPattern
+  module ControllerTracking
+    extend ActiveSupport::Concern
+
+    included do
+      before_action :_userpattern_check_rate_limit
+      after_action :_userpattern_track_request
+    end
+
+    private
+
+    def _userpattern_check_rate_limit
+      return unless _userpattern_should_check_rate_limit?
+
+      _userpattern_enforce_limits
+    rescue UserPattern::ThresholdExceeded => e
+      _userpattern_handle_violation(e)
+    end
+
+    def _userpattern_should_check_rate_limit?
+      UserPattern.enabled? &&
+        UserPattern.configuration.alert_mode? &&
+        !_userpattern_internal_request? &&
+        !_userpattern_ignored_path? &&
+        UserPattern.rate_limiter
+    end
+
+    def _userpattern_enforce_limits
+      endpoint = "#{request.method} #{UserPattern::PathNormalizer.normalize(request.fullpath)}"
+
+      UserPattern.configuration.tracked_models.each do |model_config|
+        user = _userpattern_resolve(model_config[:current_method])
+        next unless user
+
+        UserPattern.rate_limiter.check_and_increment!(user.id, model_config[:name], endpoint)
+      end
+    end
+
+    def _userpattern_handle_violation(violation)
+      actions = UserPattern.configuration.violation_actions
+
+      _userpattern_log_violation(violation) if actions.include?(:log)
+      _userpattern_record_violation(violation) if actions.include?(:record)
+      UserPattern.configuration.on_threshold_exceeded&.call(violation)
+      UserPattern.configuration.logout_method&.call(self) if actions.include?(:logout)
+
+      raise violation if actions.include?(:raise)
+    end
+
+    def _userpattern_log_violation(violation)
+      Rails.logger.warn("[UserPattern] #{violation.message}")
+    end
+
+    def _userpattern_record_violation(violation)
+      require 'userpattern/violation_recorder'
+      UserPattern::ViolationRecorder.record!(violation)
+    end
+
+    def _userpattern_track_request
+      return unless UserPattern.enabled?
+      return if _userpattern_internal_request?
+      return if _userpattern_ignored_path?
+
+      _userpattern_record_matching_models
+    end
+
+    def _userpattern_record_matching_models
+      UserPattern.configuration.tracked_models.each do |model_config|
+        user = _userpattern_resolve(model_config[:current_method])
+        next unless user
+
+        UserPattern.buffer.push(
+          model_type: model_config[:name],
+          endpoint: "#{request.method} #{UserPattern::PathNormalizer.normalize(request.fullpath)}",
+          anonymous_session_id: UserPattern::Anonymizer.anonymize(request),
+          recorded_at: Time.current
+        )
+      end
+    end
+
+    def _userpattern_resolve(method_name)
+      return nil unless respond_to?(method_name, true)
+
+      send(method_name)
+    rescue StandardError
+      nil
+    end
+
+    def _userpattern_internal_request?
+      self.class.name.to_s.start_with?('UserPattern::')
+    end
+
+    def _userpattern_ignored_path?
+      UserPattern.configuration.ignored?(request.path)
+    end
+  end
+end

data/lib/userpattern/engine.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module UserPattern
+  class Engine < ::Rails::Engine
+    isolate_namespace UserPattern
+
+    initializer 'userpattern.controller_tracking' do
+      ActiveSupport.on_load(:action_controller_base) do
+        require 'userpattern/controller_tracking'
+        include UserPattern::ControllerTracking
+      end
+
+      ActiveSupport.on_load(:action_controller_api) do
+        require 'userpattern/controller_tracking'
+        include UserPattern::ControllerTracking
+      end
+    end
+
+    # :nocov:
+    initializer 'userpattern.default_salt' do
+      config.after_initialize do
+        UserPattern.configuration.anonymous_salt ||=
+          Rails.application.secret_key_base&.byteslice(0, 32) || SecureRandom.hex(16)
+      end
+    end
+
+    initializer 'userpattern.alert_mode' do
+      config.after_initialize do
+        UserPattern.start_alert_mode! if UserPattern.configuration.alert_mode?
+      end
+    end
+
+    initializer 'userpattern.cleanup_task' do
+      config.after_initialize do
+        load File.expand_path('../tasks/userpattern.rake', __dir__) if defined?(Rake)
+      end
+    end
+    # :nocov:
+  end
+end

data/lib/userpattern/path_normalizer.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module UserPattern
+  # Normalizes request paths so that URLs differing only by dynamic segments
+  # (numeric IDs, UUIDs) are aggregated into a single endpoint pattern.
+  # Also redacts identifiable values from query strings.
+  module PathNormalizer
+    NUMERIC_ID = /\A\d+\z/
+    UUID = /\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/i
+    HEX_TOKEN = /\A[0-9a-f]{16,}\z/i
+
+    ID_PLACEHOLDER = ':id'
+    REDACTED_VALUE = ':xxx'
+
+    class << self
+      def normalize(path)
+        uri_path, query = path.split('?', 2)
+        normalized = normalize_path(uri_path)
+        normalized = "#{normalized}?#{normalize_query(query)}" if query
+        normalized
+      end
+
+      private
+
+      def normalize_path(path)
+        return path if path == '/'
+
+        segments = path.split('/')
+        segments.map { |seg| dynamic_segment?(seg) ? ID_PLACEHOLDER : seg }.join('/')
+      end
+
+      def normalize_query(query)
+        query.split('&').map { |pair| redact_pair(pair) }.sort.join('&')
+      end
+
+      def redact_pair(pair)
+        key, value = pair.split('=', 2)
+        return pair unless value
+
+        if dynamic_value?(value)
+          "#{key}=#{REDACTED_VALUE}"
+        else
+          pair
+        end
+      end
+
+      def dynamic_segment?(segment)
+        return false if segment.empty?
+
+        segment.match?(NUMERIC_ID) || segment.match?(UUID) || segment.match?(HEX_TOKEN)
+      end
+
+      def dynamic_value?(value)
+        return false if value.empty?
+
+        value.match?(NUMERIC_ID) || value.match?(UUID) || value.match?(HEX_TOKEN)
+      end
+    end
+  end
+end

data/lib/userpattern/rate_limiter.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require 'userpattern/threshold_exceeded'
+
+module UserPattern
+  # Checks per-user request rates against the limits from ThresholdCache.
+  # Counters are stored in an ActiveSupport::Cache::Store (same interface
+  # as Rack::Attack), giving multi-process support via Redis/Memcached.
+  class RateLimiter
+    PERIODS = {
+      minute: { format: '%Y-%m-%dT%H:%M', ttl: 120 },
+      hour: { format: '%Y-%m-%dT%H', ttl: 7_200 },
+      day: { format: '%Y-%m-%d', ttl: 172_800 }
+    }.freeze
+
+    def initialize(store:, threshold_cache:)
+      @store = store
+      @threshold_cache = threshold_cache
+    end
+
+    def check_and_increment!(user_id, model_type, endpoint)
+      limits = @threshold_cache.limits_for(model_type, endpoint)
+
+      if limits.nil?
+        return unless UserPattern.configuration.block_unknown_endpoints
+
+        raise_threshold_exceeded(endpoint, user_id, model_type, 'unknown', 1, 0)
+      end
+
+      PERIODS.each do |period, config|
+        check_period!(user_id, model_type, endpoint, period, config[:format], limits)
+      end
+    end
+
+    private
+
+    def check_period!(user_id, model_type, endpoint, period, time_format, limits)
+      limit = limits[:"per_#{period}"]
+      return unless limit&.positive?
+
+      key = cache_key(user_id, endpoint, period, Time.current.strftime(time_format))
+      count = increment_counter(key, PERIODS[period][:ttl])
+
+      return unless count > limit
+
+      raise_threshold_exceeded(endpoint, user_id, model_type, period.to_s, count, limit)
+    end
+
+    def raise_threshold_exceeded(endpoint, user_id, model_type, period, count, limit)
+      raise ThresholdExceeded.new(
+        endpoint: endpoint, user_id: user_id, model_type: model_type,
+        period: period, count: count, limit: limit
+      )
+    end
+
+    def increment_counter(key, ttl)
+      count = @store.increment(key, 1, expires_in: ttl)
+      return count if count
+
+      @store.write(key, 1, expires_in: ttl)
+      1
+    end
+
+    def cache_key(user_id, endpoint, period, bucket)
+      "userpattern:#{user_id}:#{endpoint}:#{period}:#{bucket}"
+    end
+  end
+end

data/lib/userpattern/request_event_cleanup.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module UserPattern
+  module RequestEventCleanup
+    def self.run!
+      cutoff = UserPattern.configuration.retention_period.days.ago
+      UserPattern::RequestEvent.where('recorded_at < ?', cutoff).delete_all
+    end
+  end
+end

data/lib/userpattern/stats_calculator.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module UserPattern
+  class StatsCalculator
+    def self.compute_all
+      new.compute_all
+    end
+
+    def compute_all
+      load_groups
+        .reject { |row| ignored_endpoint?(row[1]) }
+        .map { |row| build_stat(row) }
+    end
+
+    private
+
+    def ignored_endpoint?(endpoint)
+      # endpoint format: "VERB /path" — match only against the path part
+      path = endpoint.split(' ', 2).last.to_s
+      UserPattern.configuration.ignored?(path)
+    end
+
+    def load_groups
+      RequestEvent
+        .group(:model_type, :endpoint)
+        .pluck(
+          :model_type,
+          :endpoint,
+          Arel.sql('COUNT(*)'),
+          Arel.sql('COUNT(DISTINCT anonymous_session_id)'),
+          Arel.sql('MIN(recorded_at)'),
+          Arel.sql('MAX(recorded_at)')
+        )
+    end
+
+    def build_stat(row)
+      model_type, endpoint, total, sessions, first_seen, last_seen = row
+      span = time_span_seconds(first_seen, last_seen)
+
+      {
+        model_type: model_type,
+        endpoint: endpoint,
+        total_requests: total,
+        total_sessions: sessions,
+        avg_per_session: safe_divide(total, sessions),
+        avg_per_minute: avg_rate(total, span, 60),
+        max_per_minute: max_per_bucket(model_type, endpoint, :minute),
+        max_per_hour: max_per_bucket(model_type, endpoint, :hour),
+        max_per_day: max_per_bucket(model_type, endpoint, :day),
+        first_seen_at: first_seen,
+        last_seen_at: last_seen
+      }
+    end
+
+    def max_per_bucket(model_type, endpoint, period)
+      RequestEvent
+        .where(model_type: model_type, endpoint: endpoint)
+        .group(Arel.sql(bucket_expression(period)))
+        .count
+        .values
+        .max || 0
+    end
+
+    def bucket_expression(period)
+      case connection_adapter
+      when /postgres/
+        pg_period = { minute: 'minute', hour: 'hour', day: 'day' }[period]
+        "date_trunc('#{pg_period}', recorded_at)"
+      when /mysql/
+        fmt = { minute: '%Y-%m-%d %H:%i', hour: '%Y-%m-%d %H', day: '%Y-%m-%d' }[period]
+        "DATE_FORMAT(recorded_at, '#{fmt}')"
+      else
+        fmt = { minute: '%Y-%m-%d %H:%M', hour: '%Y-%m-%d %H', day: '%Y-%m-%d' }[period]
+        "strftime('#{fmt}', recorded_at)"
+      end
+    end
+
+    def connection_adapter
+      ActiveRecord::Base.connection.adapter_name.downcase
+    end
+
+    def time_span_seconds(first, last)
+      return 1.0 if first.nil? || last.nil?
+
+      span = (last.to_time - first.to_time).to_f
+      span.positive? ? span : 1.0
+    end
+
+    def safe_divide(numerator, denominator)
+      return 0.0 if denominator.nil? || denominator.zero?
+
+      (numerator.to_f / denominator).round(2)
+    end
+
+    def avg_rate(total, span_seconds, period_seconds)
+      periods = span_seconds / period_seconds.to_f
+      return total.to_f.round(2) if periods < 1
+
+      (total / periods).round(2)
+    end
+  end
+end

data/lib/userpattern/threshold_cache.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require 'concurrent'
+require 'userpattern/stats_calculator'
+
+module UserPattern
+  # Periodically loads observed max frequencies from the DB and builds
+  # an in-memory lookup of limits (max * multiplier) per (model_type, endpoint).
+  #
+  # A Hash is used rather than a Set because we need associated limit values
+  # per key — Hash#key? is already O(1), same as Set#include?.
+  class ThresholdCache
+    def initialize
+      @limits = {}
+      @mutex = Mutex.new
+      safe_refresh
+      start_refresh_timer
+    end
+
+    def limits_for(model_type, endpoint)
+      @limits[[model_type, endpoint]]
+    end
+
+    def known_endpoint?(model_type, endpoint)
+      @limits.key?([model_type, endpoint])
+    end
+
+    def all_limits
+      @limits.dup
+    end
+
+    def refresh!
+      new_limits = build_limits
+      @mutex.synchronize { @limits = new_limits }
+    end
+
+    def shutdown
+      @timer&.shutdown
+    end
+
+    private
+
+    def build_limits
+      multiplier = UserPattern.configuration.threshold_multiplier
+
+      StatsCalculator.compute_all.each_with_object({}) do |stat, hash|
+        key = [stat[:model_type], stat[:endpoint]]
+        hash[key] = {
+          per_minute: (stat[:max_per_minute] * multiplier).ceil,
+          per_hour: (stat[:max_per_hour] * multiplier).ceil,
+          per_day: (stat[:max_per_day] * multiplier).ceil
+        }
+      end
+    end
+
+    def safe_refresh
+      refresh!
+    rescue StandardError => e
+      # :nocov:
+      Rails.logger&.error("[UserPattern] Threshold refresh error: #{e.message}")
+      # :nocov:
+    end
+
+    # :nocov:
+    def start_refresh_timer
+      @timer = Concurrent::TimerTask.new(
+        execution_interval: UserPattern.configuration.threshold_refresh_interval
+      ) { safe_refresh }
+      @timer.execute
+    end
+    # :nocov:
+  end
+end

data/lib/userpattern/threshold_exceeded.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module UserPattern
+  class ThresholdExceeded < StandardError
+    attr_reader :endpoint, :user_id, :model_type, :period, :count, :limit
+
+    def initialize(endpoint:, user_id:, model_type:, period:, count:, limit:)
+      @endpoint = endpoint
+      @user_id = user_id
+      @model_type = model_type
+      @period = period
+      @count = count
+      @limit = limit
+      super(build_message)
+    end
+
+    private
+
+    def build_message
+      "Rate limit exceeded: #{endpoint} — " \
+        "#{count}/#{period} (max: #{limit}) " \
+        "by #{model_type}##{user_id}"
+    end
+  end
+end