skadi 0.4.0.beta.1

data/lib/skadi/configuration.rb

@@ -0,0 +1,232 @@
+module Skadi
+  class Configuration
+    class Error < StandardError; end
+
+    def initialize
+      validators.each do |attribute, validator_configuration|
+        send("#{attribute}=", validator_configuration[:default])
+      end
+    end
+
+    cattr_accessor :validators
+    self.validators = {}
+
+    def self.validates(attribute, expecting, default:, &block)
+      validators[attribute] = { expecting: expecting, default: default, validator: block }
+    end
+
+    # When enabled, users will automatically be tracked by their anonymity set.
+    # An anonymity set keeps track of a user using a hash of their IP address and User Agent. A cryptographic pepper is added to the hash, which, when discarded, makes the generated token no longer able to be used to track the user.
+    # When disabled, views and events will not be linked to a visitor without explicit consent to use anonymity sets or tracking cookies.
+    # This option defined the default behaviour for using anonymity sets, but the consent cookie, if it exists, will always take precedence over this configuration option.
+    # Defaults to false.
+    # @return [Boolean]
+    attr_accessor :use_anonymity_sets
+    validates(:use_anonymity_sets, "boolean", default: false) { |it| it == true || it == false }
+
+    # When enabled, visits will be tracked by using the logged in user. See the :user_model and :user_controller_method configuration options.
+    # When disabled, users will not be saved to visits without explicit consent.
+    # This option defined the default behaviour for tracking users, but the consent cookie, if it exists, will always take precedence over this configuration option.
+    # Defaults to false.
+    # @return [Boolean]
+    attr_accessor :track_users
+    validates(:track_users, "boolean", default: false) { |it| it == true || it == false }
+
+    attr_accessor :anonymity_set_cache_key
+    validates(:anonymity_set_cache_key, "string", default: "skadi/anonymity_set_pepper") { |it| it.is_a?(String) && it.present? }
+
+    # How long an anonymity set should last before expiring. Defaults to 1 day.
+    # @return [ActiveSupport::Duration]
+    attr_accessor :anonymity_set_duration
+    validates(:anonymity_set_duration, "ActiveSupport::Duration", default: 1.day) { |it| it.is_a?(ActiveSupport::Duration) }
+
+    # Set the hour of the day to reset the anonymity set. Set to false to strictly use the set duration. Defaults to 3 (3am).
+    # @return [Integer, false]
+    attr_accessor :anonymity_set_reset_hour
+    validates(:anonymity_set_reset_hour, "Integer or false", default: 3) do |it|
+      next true if it == false
+
+      it.is_a?(Integer) && it >= 0 && it <= 23
+    end
+
+    # How long a visit should last before expiring. Note: visits that cross anonymity set boundaries will be counted as two visits. Defaults to 2 hours.
+    # @return [ActiveSupport::Duration]
+    attr_accessor :visit_duration
+    validates(:visit_duration, "ActiveSupport::Duration", default: 2.hours) { |it| it.is_a?(ActiveSupport::Duration) }
+
+    # The parent app's User class, used to link visits to users
+    # @return [Class, nil]
+    attr_accessor :user_model
+    validates(:user_model, "string or nil", default: nil) do |it, configuration|
+      next true if it.nil?
+      next false unless it.is_a?(String)
+
+      klass = it.constantize
+
+      next false unless klass.is_a?(Class) && klass < ActiveRecord::Base
+
+      # Update the user_model ref to the actual class rather than the string
+      configuration.user_model = klass
+
+      true
+    end
+
+    # Method in the host application's ApplicationController that returns the current logged-in user. An AR Model or nil should be returned. Used to track users; if this is nil or set to a non-existent method, user tracking is disabled. Defaults to nil (disabled).
+    # @return [Symbol, nil]
+    attr_accessor :user_controller_method
+    validates(:user_controller_method, "Symbol or nil", default: nil) { |it| it.nil? || it.is_a?(Symbol) }
+
+    # Enable filtering of query parameters to prevent sensitive data being exposed. Defaults to true.
+    # @return [Boolean]
+    attr_accessor :use_query_param_whitelist
+    validates(:use_query_param_whitelist, "boolean", default: true) { |it| it == true || it == false }
+
+    # An array of query parameter keys to whitelist for storage in URLs.
+    # @return [Array<Symbol>]
+    attr_accessor :query_param_whitelist
+    validates(:query_param_whitelist, "Array<Symbol>", default: []) { |it| it.is_a?(Array) && it.all?(Symbol) }
+
+    # Maximum length of the referrer and exit page URLs. Defaults to 2048.
+    # @return [Integer]
+    attr_accessor :max_url_length
+    validates(:max_url_length, "Integer", default: 2048) { |it| it.is_a?(Integer) && it >= 0 }
+
+    # The database connection to use for Skadi models
+    # @see ActiveRecord::ConnectionHandling.connects_to
+    # @return [Hash, nil]
+    attr_accessor :db_connects_to
+    validates(:db_connects_to, "Hash compatible with ActiveRecord::ConnectionHandling#connects_to", default: nil) do |it|
+      next true if it.nil?
+
+      allowed_keys = [ :database, :shards ].freeze
+      it.is_a?(Hash) && !it.empty? && it.keys.all? { |key| allowed_keys.include?(key) }
+    end
+
+    # Whether to store the domain when tracking views. Can be useful when using multiple domains or subdomains. Defaults to false.
+    # @return [Boolean]
+    attr_accessor :store_domain_in_views
+    validates(:store_domain_in_views, "boolean", default: false) { |it| it == true || it == false }
+
+    # Sets a limit on the size of the tracking beacon. Defaults to 1KB.
+    # @return [Integer]
+    attr_accessor :max_tracking_payload_size
+    validates(:max_tracking_payload_size, "integer", default: 1_024) { |it| it.is_a?(Integer) && it > 0 }
+
+    # The domain to use when setting cookies. Set to include subdomains. Defaults to nil, which will not specify a domain when setting a cookie.
+    # @return [String, nil]
+    attr_accessor :cookie_domain
+    validates(:cookie_domain, "string or nil", default: nil) { |it| it.nil? || (it.present? && it.is_a?(String)) }
+
+    # Whether to track visits by suspected bots, detected via the browser user agent. Defaults to `Rails.env.local?` (true
+    # for development and testing environments, and false for production/other environments).
+    attr_accessor :track_bots
+    validates(:track_bots, "boolean", default: Rails.env.local?) { |it| it == true || it == false }
+
+    # Helper method to return the inverse of :track_bots
+    def do_not_track_bots? = !@track_bots
+
+    ###########################
+    # Dashboard configuration #
+    ###########################
+
+    # Method in the host application's ApplicationController that returns true if the current request is allowed to view the Skadi dashboard. Defaults to nil (disabled).
+    # @return [Symbol, nil]
+    attr_accessor :dashboard_view_controller_method
+    validates(:dashboard_view_controller_method, "Symbol or nil", default: nil) { |it| it.nil? || it.is_a?(Symbol) }
+
+    # Method in the host application's ApplicationController that returns true if the current request is allowed to edit Skadi dashboards. Defaults to nil (disabled).
+    # @return [Symbol, nil]
+    attr_accessor :dashboard_edit_controller_method
+    validates(:dashboard_edit_controller_method, "Symbol or nil", default: nil) { |it| it.nil? || it.is_a?(Symbol) }
+
+    # Method in the host application's ApplicationController that returns true if the current request is allowed to edit raw SQL in the Skadi dashboard. Note that exposing SQL to users is dangerous and could lead to data loss. Defaults to nil (disabled).
+    # @return [Symbol, nil]
+    attr_accessor :dashboard_dangerously_use_sql_controller_method
+    validates(:dashboard_dangerously_use_sql_controller_method, "Symbol or nil", default: nil) { |it| it.nil? || it.is_a?(Symbol) }
+
+    # Use this to add custom fields to the events dataset in the dashboard. This should be set to a hash with values of the format:
+    #   {
+    #     label: The label to show in the front end,
+    #     type: The datatype, one of :date, :string, :number, :boolean. Defaults to :string if omitted.
+    #     filter: `true` if this field can be filtered
+    #     split: `true` if this field can be split
+    #     sql: The SQL expression used to get this value for derived fields
+    #     options: An array of possible values
+    #     description: used in the front end as help text for this field
+    #   }
+    # For example,
+    #   {clicks: {type: :number, filter: true, split: true, sql: "properties->>'clicks'"}}
+    # See Skadi::Schema for reference
+    # @return [Array<Hash>, nil]
+    attr_accessor :dashboard_custom_event_fields
+    validates(:dashboard_custom_event_fields, "Hash or nil", default: nil) do |it|
+      next true if it.nil?
+      next false unless it.is_a?(Hash)
+
+      next it.all? do |_key, item|
+        item.is_a?(Hash) && (item.keys.map(&:to_s) - %w[label type filter split sql option description]).empty?
+      end
+    end
+
+    # Use this to add custom database tables to the Skadi dashboard. See Skadi::Schema for reference.
+    attr_accessor :dashboard_custom_schema
+    validates(:dashboard_custom_schema, "a valid schema or nil", default: nil) do |it|
+      next true if it.nil?
+      unless it.is_a?(Hash)
+        error! "Skadi.configuration.dashboard_custom_schema must be a hash"
+        next false
+      end
+
+      tables_valid = it.all? do |_table_name, table_schema|
+        unless table_schema.is_a?(Hash)
+          error! "Skadi.configuration.dashboard_custom_schema values must be a hash"
+          next false
+        end
+
+        unless table_schema[:model].is_a?(String)
+          error! "Skadi.configuration.dashboard_custom_schema hash values must have a :model key"
+          next false
+        end
+
+        klass = table_schema[:model].constantize
+        unless klass.is_a?(Class) && klass < ActiveRecord::Base
+          error! "Skadi.configuration.dashboard_custom_schema hash values model key must be the name of a valid model"
+          next false
+        end
+
+        table_schema[:model] = klass
+
+        unless table_schema[:fields].is_a?(Hash)
+          error! "Skadi.configuration.dashboard_custom_schema fields must be a hash"
+        end
+
+        next true
+      end
+
+      next tables_valid
+    end
+
+
+    def validate!
+      validators.each do |attribute, validator_configuration|
+        validator = validator_configuration[:validator]
+        expecting = validator_configuration[:expecting]
+        value = send(attribute)
+
+        if validator.call(value, self)
+          next
+        end
+
+        error! "Skadi.configuration.#{attribute} error! Expecting a #{expecting}, but got a #{value.class}"
+      end
+    end
+
+    private def error!(error)
+      if Rails.env.local?
+        raise Error.new(error)
+      else
+        Rails.logger.error error
+      end
+    end
+  end
+end

data/lib/skadi/controller_delegate.rb

@@ -0,0 +1,322 @@
+module Skadi
+  class ControllerDelegate
+    # The controller that instantiated us
+    # @return [ActionController::Base]
+    attr_reader :controller
+
+    attr_reader :view, :visit, :events, :demographics
+
+    # The parsed user agent
+    # @return [Skadi::UserAgent]
+    def user_agent = @_user_agent ||= UserAgent.new(request.user_agent || "")
+
+    # Whether the current request has recorded a new visit
+    # @return [TrueClass, FalseClass]
+    def new_visit? = @new_visit
+
+    # The current request
+    # @return [ActionDispatch::Request]
+    private def request = controller.request
+
+    # The skadi cookie manager for the current request
+    # @return [Skadi::CookieManager]
+    private def cookie_manager = @_skadi_cookies ||= Skadi::CookieManager.new(controller.request)
+
+    # @param [ActionController::Base] controller
+    def initialize(controller, bot_protection: true)
+      @controller = controller
+
+      @events = []
+      @demographics = []
+
+      @do_not_track = bot_protection && Skadi.configuration.do_not_track_bots? && user_agent.bot?
+      @new_visit = false
+    end
+
+    # Internal. Performs the before-action tasks: build the visit and view, and process user agent
+    # info.
+    def _prepare
+      return if do_not_track?
+
+      build_visit
+      build_view
+      queue_user_agent_demographics
+    rescue => e
+      # Analytics must not interfere with the host app's request on failure
+      Rails.logger.error("Skadi: failed to prepare analytics for #{controller.controller_name}##{controller.action_name} (visit: #{@visit.try(:id).inspect}, view: #{@view.try(:id).inspect}, events: #{@events.count}, demographics: #{@demographics.count}): #{e.class}, #{e.message}; Line: #{e.backtrace&.first}")
+
+      # Ensure errors are visible in test and development
+      raise if Rails.env.local?
+    end
+
+    # Internal. Manually set the view and visit for the current request.
+    def _attach(view: nil, visit: nil)
+      @visit = visit
+      @view = view
+    end
+
+    # Internal. Saves the visit, view and any events or demographics after the controller action.
+    def _persist
+      return if do_not_track?
+
+      @visit&.save
+      if @view
+        @view.visit = @visit
+        @view.save
+      end
+
+      if @events.any?
+        Skadi::Event.redact_and_insert(@events, visit: @visit, view: @view)
+      end
+
+      if @demographics.any?
+        Demographic.create_or_increment_all(@demographics)
+      end
+
+      cookie_manager.renew!
+    rescue => e
+      # Analytics must not interfere with the host app's request on failure
+      Rails.logger.error("Skadi: failed to persist analytics for #{controller.controller_name}##{controller.action_name} (visit: #{@visit.try(:id).inspect}, view: #{@view.try(:id).inspect}, events: #{@events.count}, demographics: #{@demographics.count}): #{e.class}, #{e.message}; Line: #{e.backtrace&.first}")
+
+      # Ensure errors are visible in test and development
+      raise if Rails.env.local?
+    end
+
+    # Whether Skadi tracking has been disabled for the current request
+    # @return [Boolean]
+    def do_not_track?
+      @do_not_track
+    end
+
+    # Disable tracking for the current request
+    def do_not_track!
+      @do_not_track = true
+    end
+
+    # Create or increment a demographic with a given name or value. If the action_specific parameter
+    # is set to true, the demographic is linked specifically to the current action. Demographics are
+    # not linked to any other individual data. E.g:
+    #
+    #   skadi.demographic("browser", "Chrome")
+    #   skadi.demographic("branch", "A", action_specific: true)
+    #
+    # If the name/value/action combination doesn't exist for the current date, a new row is added to
+    # the database with count set to 1. If it does, the existing record's count is incremented.
+    #
+    # @param [String] name
+    # @param [String] value
+    # @param [TrueClass, FalseClass] action_specific
+    def demographic(name, value, action_specific: false, uri: nil)
+      raise ArgumentError.new "Skadi::ControllerDelegate.demographic expects String as first parameter, got #{name.is_a?(String) ? "empty string" : name.class.name}" unless name.is_a?(String) && name.present?
+      raise ArgumentError.new "Skadi::ControllerDelegate.demographic expects String as second parameter, got #{value.is_a?(String) ? "empty string" : value.class.name}" unless value.is_a?(String) && value.present?
+
+      demographic = { name:, value:, uri: action_specific ? (uri || request.route_uri_pattern) : nil }
+
+      @demographics << demographic
+    end
+
+    # Create an event with the given name and properties. By default, events are linked to the
+    # current visit and view, but if the sensitive parameter is set to true, the event is not linked
+    # to the visit and view, and the time of the event is set to the start of the current day.
+    #
+    # @param [String] name
+    # @param [Hash] properties
+    # @param [TrueClass, FalseClass] sensitive
+    def event(name, properties = {}, sensitive: false)
+      raise ArgumentError.new "Skadi::ControllerDelegate.event expects String as first parameter, got #{name.is_a?(String) ? "empty string" : name.class.name}" unless name.is_a?(String) && name.present?
+      raise ArgumentError.new "Skadi::ControllerDelegate.event expects Hash as second parameter, got #{properties.class.name}" unless properties.is_a?(Hash)
+
+      event = { name:, properties:, sensitive: }
+
+      @events << event
+    end
+
+    # Set consent for tracking by anonymity set
+    # @param [TrueClass, FalseClass] consent
+    def anonymity_set_consent!(consent)
+      anonymity_set = AnonymitySet.calculate(request.remote_ip, request.user_agent)
+
+      if consent
+        cookie_manager.use_anonymity_sets = true
+
+        # If a visit is attached to the request, we update it with the anonymity set token
+        if @visit
+          @visit.tracking_token ||= anonymity_set
+        else
+          # Build the visit without the request, because the current request is likely not the original first request
+          @visit = Visit.build_from(anonymity_set)
+          @view.visit = @visit if @view
+        end
+      else
+        cookie_manager.use_anonymity_sets = false
+
+        return if @visit.nil?
+
+        # Check to see if the currrent visit is using an anonymity set
+        if @visit&.tracking_token && !@visit.cookies_enabled
+          # If so, delete it from the db so existing data is anonymised instantly
+          # Note: this needs to be a DB update because there may be other visits outside the visit limit
+          Skadi::Visit.where(tracking_token: anonymity_set).update_all(tracking_token: nil)
+
+          # Update the local instance of the visit if it uses anonymity sets so it doesn't get re-set when saved
+          @visit.tracking_token = nil if @visit.tracking_token == anonymity_set
+        end
+      end
+    end
+
+    def anonymity_set_consent?
+      cookie_value = cookie_manager.use_anonymity_sets
+      return cookie_value unless cookie_value.nil?
+
+      # There is no explicit consent or opt-out, so we use the configured default value
+      return Skadi.configuration.use_anonymity_sets
+    end
+
+    # Set consent for tracking by cookie
+    # @param [TrueClass, FalseClass] consent
+    def cookie_consent!(consent)
+      if consent
+        return unless cookie_manager.tracking_token.nil?
+
+        # Re-use an existing cookie-based token
+        tracking_token = @visit&.tracking_token if @visit&.cookies_enabled
+        tracking_token ||= ::SecureRandom.uuid_v7
+
+        cookie_manager.tracking_token = tracking_token
+
+        # Update the existing visit with the tracking token if we've generated a new one
+        if @visit
+          @visit.tracking_token = tracking_token
+          @visit.cookies_enabled = true
+        else
+          @visit = Visit.build_from(tracking_token, cookies_enabled: true)
+          @view.visit = @visit if @view
+        end
+      else
+        cookie_manager.tracking_token = nil
+
+        return if @visit.nil?
+
+        # No need to anonymise existing sessions here because there is no way to link to the user once the tracking token is deleted.
+        @visit.cookies_enabled = false
+
+        # If the user has opted in for anonymity sets
+        if cookie_manager.use_anonymity_sets == true || (Skadi.configuration.use_anonymity_sets && cookie_manager.use_anonymity_sets != false)
+          @visit.tracking_token = AnonymitySet.calculate(request.remote_ip, request.user_agent)
+        end
+      end
+    end
+
+    def cookie_consent? = cookie_manager.tracking_token.present?
+
+    # Set consent for tracking by logged in user
+    # @param [TrueClass, FalseClass] consent
+    def user_consent!(consent)
+      tracked_user_id = @visit&.user_id || logged_in_user&.id
+
+      if consent
+        cookie_manager.track_users = true
+
+        unless tracked_user_id.nil?
+          if @visit
+            @visit.user_id = tracked_user_id
+          else
+            # Build the visit without the request, because the current request is likely not the original first request
+            @visit = Visit.build_from(nil, tracked_user_id)
+            @view.visit = @visit if @view
+          end
+        end
+      else
+        cookie_manager.track_users = false
+
+        # If there is a logged in user, we delete the user id from any rows that match
+        unless tracked_user_id.nil?
+          # Note: this needs a DB update because there may be other visits outside the visit limit
+          Skadi::Visit.where(user_id: tracked_user_id).update_all(user_id: nil)
+
+          # Update the local instance of the current visit so it doesn't get re-set when saved
+          @visit.user_id = nil if @visit
+        end
+      end
+    end
+
+    def user_consent?
+      cookie_value = cookie_manager.track_users
+      return cookie_value unless cookie_value.nil?
+
+      # There is no explicit consent or opt-out, so we use the configured default value
+      return Skadi.configuration.track_users
+    end
+
+    private def build_visit
+      user, has_utm_params, has_external_referrer = nil
+
+      tracking_token = cookie_manager.tracking_token
+
+      if tracking_token.nil? && anonymity_set_consent?
+        tracking_token = AnonymitySet.calculate(request.remote_ip, request.user_agent)
+      end
+
+      if user_consent?
+        user = logged_in_user
+      end
+
+      @visit = Visit.find_active_visit_for(tracking_token, user)
+
+      if @visit
+        # Update the user if the user has logged in since the last view
+        @visit.user_id = user.id if user && @visit.user_id.nil?
+
+        # Ensure the cookie consent status is up to date
+        @visit.cookies_enabled = cookie_consent?
+
+        return
+      end
+
+      unless tracking_token || user
+        has_utm_params = request.query_parameters.keys.any? { |it| it.to_s.start_with?("utm_") }
+        has_external_referrer = request.referrer.present? && controller.url_from(request.referrer).nil?
+      end
+
+      # Only create a visit if we have some useful data or way of tracking users across pages
+      return unless tracking_token || user || has_utm_params || has_external_referrer
+
+      @visit = Visit.build_from(tracking_token, user&.id, request)
+      @new_visit = true
+    end
+
+    private def build_view
+      @view = View.new(
+        view_token: SecureRandom.uuid_v7,
+        verified: false,
+        controller: controller.controller_name,
+        action: controller.action_name,
+        verb: request.request_method,
+        path: Url.view_path_from_request(request),
+        query_params: Url.whitelist_query_params(request.query_parameters),
+      )
+    end
+
+    private def queue_user_agent_demographics
+      # Only track the user agent data when we are recording a new visit so we don't duplicate the data
+      return unless new_visit?
+
+      demographic "Browser", user_agent.browser
+      demographic "Browser version", "#{user_agent.browser} #{user_agent.browser_version}"
+      demographic "Browser engine", user_agent.engine
+      demographic "Browser engine version", "#{user_agent.engine} #{user_agent.engine_version}"
+      demographic "Operating system", user_agent.os
+    end
+
+    private def logged_in_user
+      return @logged_in_user if defined?(@logged_in_user)
+
+      return nil if Skadi.configuration.user_controller_method.nil?
+      return nil unless controller.respond_to?(Skadi.configuration.user_controller_method, true)
+
+      @logged_in_user = controller.send(Skadi.configuration.user_controller_method)
+
+      return @logged_in_user
+    end
+  end
+end

data/lib/skadi/cookie_manager.rb

@@ -0,0 +1,81 @@
+module Skadi
+  class CookieManager
+    ANONYMITY_SET_KEY = "skadi_anonymity_set"
+    TRACKING_TOKEN_KEY = "skadi_id"
+    TRACK_USER_KEY = "skadi_track_user"
+    UUID_REGEX = /\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/
+
+    # @return [ActionDispatch::Cookies::CookieJar]
+    attr_reader :cookies, :request
+
+    def initialize(request)
+      @request = request
+      @cookies = request.cookie_jar
+    end
+
+    def renew!
+      set_cookie ANONYMITY_SET_KEY, cookies[ANONYMITY_SET_KEY] if [ "1", "0" ].include?(cookies[ANONYMITY_SET_KEY])
+      set_cookie TRACK_USER_KEY, cookies[TRACK_USER_KEY] if [ "1", "0" ].include?(cookies[TRACK_USER_KEY])
+
+      if cookies.has_key? TRACKING_TOKEN_KEY
+        token = tracking_token
+        if token
+          set_cookie TRACKING_TOKEN_KEY, token
+        else
+          # If the key is set, but the token returned by `tracking_token()` is nil, then the cookie is malformed and we delete it
+          delete_cookie TRACKING_TOKEN_KEY
+        end
+      end
+    end
+
+    def use_anonymity_sets
+      return true if cookies[ANONYMITY_SET_KEY] == "1"
+      return false if cookies[ANONYMITY_SET_KEY] == "0"
+    end
+
+    def use_anonymity_sets=(new_value)
+      set_cookie ANONYMITY_SET_KEY, new_value ? "1" : "0"
+    end
+
+    def track_users
+      return true if cookies[TRACK_USER_KEY] == "1"
+      return false if cookies[TRACK_USER_KEY] == "0"
+    end
+
+    def track_users=(new_value)
+      set_cookie TRACK_USER_KEY, new_value ? "1" : "0"
+    end
+
+    def tracking_token
+      token = cookies[TRACKING_TOKEN_KEY]
+
+      # The cookie is user input, so we ensure the cookie is a UUID as expected
+      token&.match(UUID_REGEX) ? token : nil
+    end
+
+    def tracking_token=(new_value)
+      if new_value.nil?
+        delete_cookie(TRACKING_TOKEN_KEY)
+
+        return
+      end
+
+      set_cookie TRACKING_TOKEN_KEY, new_value
+    end
+
+    private def set_cookie(name, value)
+      cookies[name] = {
+        value:,
+        domain: Skadi.configuration.cookie_domain,
+        httponly: true,
+        secure: Rails.env.production? || request.ssl?,
+        same_site: :lax,
+        expires: 1.year.from_now,
+      }
+    end
+
+    private def delete_cookie(name)
+      cookies.delete(name, domain: Skadi.configuration.cookie_domain)
+    end
+  end
+end

data/lib/skadi/engine.rb

@@ -0,0 +1,38 @@
+module Skadi
+  class Engine < ::Rails::Engine
+    isolate_namespace Skadi
+
+    config.after_initialize do
+      # Validate the configuration and output any errors to the Rails log
+      Skadi.configuration.validate!
+
+      validate_cache_store!
+
+      if Skadi.configuration.db_connects_to
+        Skadi::ApplicationRecord.connects_to(**Skadi.configuration.db_connects_to)
+      end
+
+      if Skadi.configuration.user_model
+        Skadi::Visit.belongs_to :user, class_name: Skadi.configuration.user_model.to_s, optional: true
+      end
+    end
+
+    def self.validate_cache_store!
+      # Only the anonymity sets uses the cache
+      return unless Skadi.configuration.use_anonymity_sets
+
+      # A different cache store is common for development and testing
+      return if Rails.env.local?
+
+      if Rails.cache.is_a?(ActiveSupport::Cache::NullStore)
+        Rails.logger.warn("Skadi: anonymity sets are enabled but Rails.cache is a ActiveSupport::Cache::NullStore. The pepper won't be saved so anonymity sets have been disabled.")
+
+        Skadi.configuration.use_anonymity_sets = false
+      end
+
+      if Rails.cache.is_a?(ActiveSupport::Cache::MemoryStore)
+        Rails.logger.warn("Skadi: anonymity sets are enabled but Rails.cache is a ActiveSupport::Cache::MemoryStore. If Rails is running across multiple processes or servers, the pepper won't be shared across processes, breaking anonymity-set grouping. Use a shared store (SolidCache/Redis/Memcached).")
+      end
+    end
+  end
+end