sentiero-rails 1.0.0.alpha1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 01ce313521ddbc812513032b99f9167f18888958bce23cae2ca040910fd9a16e
+  data.tar.gz: 3395c38e3db3cc713116c59963509bafc619f30ce83701aca67e051daa50a6a5
+SHA512:
+  metadata.gz: 77e8e9577a6428b5ec1c913755ffa0a7410349ad87f0bdd0bfc38246aafc2d1cdd9b38a4d1609331ad2e0e649818e3e04cc30b46d0f23118cd1ade7e25c28ad4
+  data.tar.gz: 4a9a082240b101a0466cf36bca3a28535e895937926045e53ddf1956edf23e883f9cf1bdf3667dc866be961f1fa0fab3c704e746866f568b17e7c9bedc283d5f

data/LICENSE.txt

@@ -0,0 +1,7 @@
+Copyright 2026 Stephen Ierodiaconou
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/lib/sentiero/rails/configuration.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Sentiero
+  module Rails
+    class Configuration
+      attr_accessor :events_url, :reporter_middleware
+
+      def initialize
+        @events_url = "/sentiero/events"
+        @reporter_middleware = true
+      end
+    end
+
+    class << self
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      def configure
+        yield(configuration)
+      end
+
+      def reset_configuration!
+        @configuration = Configuration.new
+      end
+    end
+  end
+end

data/lib/sentiero/rails/engine.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require_relative "helpers/script_tag_helper"
+require_relative "../reporter"
+require_relative "../reporter/middleware"
+
+module Sentiero
+  module Rails
+    class Engine < ::Rails::Engine
+      initializer "sentiero.helpers" do
+        ActiveSupport.on_load(:action_view) do
+          include Sentiero::Rails::Helpers::ScriptTagHelper
+        end
+      end
+
+      # Reports unhandled exceptions, then re-raises them.
+      initializer "sentiero.reporter_middleware" do |app|
+        Sentiero::Rails::Engine.insert_reporter_middleware(app)
+      end
+
+      def self.insert_reporter_middleware(app)
+        return false unless reporter_middleware_enabled?
+
+        # Install whenever opted in — not gated on Reporter.active? at boot, since
+        # the user's Reporter.configure runs in an initializer after this one. The
+        # middleware is a cheap pass-through and Reporter.notify guards on active?
+        # at request time, so an unconfigured reporter just does nothing.
+        app.middleware.use Sentiero::Reporter::Middleware
+        true
+      rescue => e
+        warn "[Sentiero::Reporter] middleware auto-install failed: #{e.class}: #{e.message}"
+        false
+      end
+
+      def self.reporter_middleware_enabled?
+        flag = Sentiero::Rails.configuration.reporter_middleware
+        return true if flag.nil?
+        flag
+      end
+
+      initializer "sentiero.default_store" do
+        config.after_initialize do
+          if Sentiero.configuration.store.nil?
+            require_relative "store"
+            Sentiero.configuration.store = Sentiero::Rails::Store.new
+          end
+        end
+      end
+
+      rake_tasks do
+        load File.expand_path("tasks/sentiero.rake", __dir__)
+      end
+    end
+  end
+end

data/lib/sentiero/rails/generators/sentiero/install_generator.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+require "securerandom"
+
+module Sentiero
+  module Generators
+    class InstallGenerator < ::Rails::Generators::Base
+      include ::Rails::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates a Sentiero initializer and migration for ActiveRecord storage."
+
+      def self.next_migration_number(dirname)
+        Time.now.utc.strftime("%Y%m%d%H%M%S")
+      end
+
+      def create_migration_file
+        migration_template "create_sentiero_tables.rb.erb",
+          "db/migrate/create_sentiero_tables.rb"
+      end
+
+      def create_initializer
+        template "initializer.rb", "config/initializers/sentiero.rb"
+      end
+
+      def show_route_instructions
+        say ""
+        say "Sentiero installed successfully!", :green
+        say ""
+        say "Next steps:", :yellow
+        say "  1. Run migrations:  rails db:migrate"
+        say "  2. Mount the Rack apps in config/routes.rb:"
+        say ""
+        say "    # config/routes.rb"
+        say '    mount Sentiero::Web::EventsApp.new, at: "/sentiero/events"'
+        say '    mount Sentiero::Web::DashboardApp.new, at: "/sentiero"'
+        say ""
+        say "  3. Add the script tag to your layout:"
+        say "    <%= sentiero_script_tag %>"
+        say ""
+        password = SecureRandom.urlsafe_base64(12)
+        say "Dashboard auth is ENABLED by default (HTTP Basic, user \"admin\").", :yellow
+        say "Set this generated password in your environment:"
+        say ""
+        say "    export SENTIERO_DASHBOARD_PASSWORD=#{password}"
+        say ""
+        say "The dashboard refuses to load until SENTIERO_DASHBOARD_PASSWORD is set."
+        say "To disable auth, comment out config.basic_auth in config/initializers/sentiero.rb."
+        say ""
+      end
+    end
+  end
+end

data/lib/sentiero/rails/generators/sentiero/templates/create_sentiero_tables.rb.erb

@@ -0,0 +1,74 @@
+class CreateSentieroTables < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :sentiero_sessions do |t|
+      t.string :session_id, null: false
+      t.json :metadata
+      t.timestamps
+    end
+
+    add_index :sentiero_sessions, :session_id, unique: true
+
+    create_table :sentiero_events do |t|
+      t.string :session_id, null: false
+      t.string :window_id, null: false
+      t.float :timestamp
+      t.json :data
+      t.datetime :created_at, null: false
+    end
+
+    add_index :sentiero_events, [:session_id, :window_id, :timestamp],
+      name: "index_sentiero_events_on_session_window_timestamp"
+    add_index :sentiero_events, :session_id
+
+    create_table :sentiero_problems do |t|
+      t.string :fingerprint, null: false
+      t.string :project, null: false
+      t.string :exception_class, null: false
+      t.string :title, null: false
+      t.string :message
+      t.integer :count, null: false, default: 0
+      t.string :status, null: false, default: "open"
+      t.float :first_seen, null: false
+      t.float :last_seen, null: false
+      t.float :resolved_at
+    end
+
+    add_index :sentiero_problems, :fingerprint, unique: true
+    add_index :sentiero_problems, :project
+    add_index :sentiero_problems, :status
+    add_index :sentiero_problems, :last_seen
+
+    create_table :sentiero_occurrences do |t|
+      t.string :occurrence_id, null: false
+      t.string :fingerprint, null: false
+      t.string :session_id
+      t.float :timestamp, null: false
+      t.json :data, null: false
+    end
+
+    add_index :sentiero_occurrences, [:fingerprint, :timestamp],
+      name: "index_sentiero_occurrences_on_fingerprint_timestamp"
+    add_index :sentiero_occurrences, :session_id
+    add_index :sentiero_occurrences, :occurrence_id, unique: true
+
+    create_table :sentiero_server_events do |t|
+      t.string :event_id, null: false
+      t.string :project, null: false
+      t.string :name, null: false
+      t.string :level
+      t.string :session_id
+      t.float :timestamp, null: false
+      t.json :data, null: false
+    end
+
+    add_index :sentiero_server_events, :project
+    add_index :sentiero_server_events, :session_id
+    add_index :sentiero_server_events, :event_id, unique: true
+
+    add_check_constraint :sentiero_problems, "status IN ('open', 'resolved', 'ignored')",
+      name: "sentiero_problems_status_check"
+
+    add_foreign_key :sentiero_events, :sentiero_sessions,
+      column: :session_id, primary_key: :session_id, on_delete: :cascade
+  end
+end

data/lib/sentiero/rails/generators/sentiero/templates/initializer.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+# Sentiero configuration
+#
+# For full documentation, see: https://github.com/stevegeek/sentiero
+
+Sentiero.configure do |config|
+  # Store: defaults to ActiveRecord (Sentiero::Rails::Store) when using sentiero-rails.
+  # You can switch to Redis or Memory stores if preferred:
+  #   config.store = Sentiero::Stores::Memory.new
+  #   config.store = Sentiero::Stores::Redis.new(redis: Redis.new)
+  # config.store = Sentiero::Rails::Store.new
+
+  # CORS origins: list of allowed origins for the events endpoint.
+  # Required if your frontend is on a different domain.
+  # config.cors_origins = ["https://yourapp.com"]
+
+  # Maximum events accepted per single POST request (default: nil = unlimited).
+  # config.max_events_per_request = 500
+
+  # Maximum total events stored per session (oldest dropped when exceeded).
+  # Enforced by the ActiveRecord, Memory, File, and SQLite stores. The Redis
+  # store ignores it; cap session size there with the store's :ttl option.
+  # config.max_events_per_session = 10_000
+
+  # Maximum sessions stored (oldest evicted when exceeded).
+  # Enforced by the ActiveRecord, Memory, File, and SQLite stores. The Redis
+  # store ignores it; cap retention there with the store's :ttl option.
+  # config.max_sessions = 1_000
+
+  # Data retention: automatically purge sessions older than a given period.
+  # Set the period in seconds, then schedule `rake sentiero:purge` from cron
+  # or a job scheduler (e.g. Sidekiq::Cron, Clockwork, whenever).
+  # config.retention_period = 90 * 24 * 3600 # 90 days
+
+  # Recorder flush settings (milliseconds / event count).
+  # config.flush_interval_ms = 10_000
+  # config.flush_event_threshold = 50
+
+  # Dashboard authentication (HTTP Basic).
+  #
+  # Enabled by default. Set the password in your environment:
+  #   export SENTIERO_DASHBOARD_PASSWORD=...
+  # The dashboard refuses to load (raises) until a non-blank password is set.
+  # With no auth configured the dashboard fails closed (403); to serve it
+  # unauthenticated anyway, remove this block and set
+  # `config.allow_insecure_dashboard = true`.
+  config.basic_auth = {
+    user: "admin",
+    password: ENV["SENTIERO_DASHBOARD_PASSWORD"]
+  }
+
+  # Alternative: app-session-based auth instead of HTTP Basic. Comment out
+  # config.basic_auth above and set a callback returning true/false:
+  #
+  # config.auth_callback = ->(env) {
+  #   env["warden"]&.user&.admin? || false
+  # }
+end
+
+# Rails-specific configuration
+# Sentiero::Rails.configure do |config|
+#   # The URL where EventsApp is mounted (used by the sentiero_script_tag helper).
+#   # config.events_url = "/sentiero/events"
+#
+#   # Server-side error reporter middleware is auto-inserted when the reporter is
+#   # configured below. Set to false to opt out of the auto-install.
+#   # config.reporter_middleware = true
+# end
+
+# Server-side Error Tracking (reporter)
+#
+# The reporter sends unhandled exceptions and custom events to a Sentiero
+# ingest endpoint. When configured, the Rack middleware is auto-inserted into
+# your app's middleware stack (zero-config capture). It also links server-side
+# errors to front-end session replay via the sentiero_sid / sentiero_wid
+# cookies. Uncomment and fill in to enable:
+#
+# Sentiero::Reporter.configure do |r|
+#   r.endpoint = ENV["SENTIERO_ENDPOINT"]      # e.g. "https://sentiero.example.com"
+#   r.ingest_key = ENV["SENTIERO_INGEST_KEY"]  # server-issued ingest key
+#   r.project = "my-app"                        # project identifier
+#   r.environment = Rails.env                   # "production", "staging", ...
+#   r.release = ENV["GIT_SHA"]                  # optional release/version
+#
+#   # Don't report these (Class or "String" class-names; ancestors match too):
+#   # r.ignore_exceptions = [ActiveRecord::RecordNotFound, "ActionController::RoutingError"]
+#
+#   # Mutate or drop a report before it is sent (return false/nil to drop):
+#   # r.before_notify = ->(report) {
+#   #   report["context"].delete("secret")
+#   #   report
+#   # }
+#
+#   # Redact context/payload keys before sending. Matching is case-insensitive
+#   # and substring-based. filter_keys is added on top of the built-in defaults:
+#   # r.filter_keys = [:api_secret, :otp]
+#   #
+#   # The built-in defaults (password, token, ssn, ...) seed default_filter_keys,
+#   # which you can edit to relax the floor:
+#   # r.default_filter_keys -= ["ssn"]
+#
+#   # Use a non-network transport in development/test:
+#   # r.transport = Sentiero::Reporter::LogTransport.new   # logs would-be sends
+#   # r.transport = Sentiero::Reporter::NullTransport.new  # drops everything
+# end

data/lib/sentiero/rails/helpers/script_tag_helper.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Sentiero
+  module Rails
+    module Helpers
+      module ScriptTagHelper
+        def sentiero_script_tag(events_url: nil, recorder_url: nil)
+          events_url ||= Sentiero::Rails.configuration.events_url
+          Sentiero::Web::ScriptTag.render(events_url: events_url, recorder_url: recorder_url).html_safe
+        end
+      end
+    end
+  end
+end

data/lib/sentiero/rails/models/event.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Sentiero
+  module Rails
+    class Event < ::ActiveRecord::Base
+      self.table_name = "sentiero_events"
+
+      belongs_to :session,
+        class_name: "Sentiero::Rails::Session",
+        primary_key: :session_id,
+        inverse_of: false
+
+      validates :session_id, :window_id, presence: true
+    end
+  end
+end

data/lib/sentiero/rails/models/occurrence.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Sentiero
+  module Rails
+    class Occurrence < ::ActiveRecord::Base
+      self.table_name = "sentiero_occurrences"
+
+      validates :occurrence_id, presence: true, uniqueness: true
+      validates :fingerprint, presence: true, format: {with: Sentiero::Store::VALID_ID}
+      validates :timestamp, presence: true
+      validates :data, presence: true
+    end
+  end
+end

data/lib/sentiero/rails/models/problem.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Sentiero
+  module Rails
+    class Problem < ::ActiveRecord::Base
+      self.table_name = "sentiero_problems"
+
+      validates :fingerprint, presence: true, uniqueness: true,
+        format: {with: Sentiero::Store::VALID_ID}
+      validates :project, presence: true, format: {with: Sentiero::Store::VALID_ID}
+      validates :exception_class, presence: true
+      validates :title, presence: true, length: {maximum: Sentiero::Store::PROBLEM_TITLE_MAX}
+      validates :status, inclusion: {in: Sentiero::Store::VALID_STATUS}
+      validates :count, numericality: {only_integer: true, greater_than_or_equal_to: 0}
+      validates :first_seen, :last_seen, presence: true
+    end
+  end
+end

data/lib/sentiero/rails/models/server_event.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Sentiero
+  module Rails
+    class ServerEvent < ::ActiveRecord::Base
+      self.table_name = "sentiero_server_events"
+
+      validates :event_id, presence: true, uniqueness: true
+      validates :project, presence: true, format: {with: Sentiero::Store::VALID_ID}
+      validates :name, presence: true
+      validates :timestamp, presence: true
+      validates :data, presence: true
+    end
+  end
+end

data/lib/sentiero/rails/models/session.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Sentiero
+  module Rails
+    class Session < ::ActiveRecord::Base
+      self.table_name = "sentiero_sessions"
+
+      has_many :events,
+        class_name: "Sentiero::Rails::Event",
+        primary_key: :session_id,
+        dependent: :delete_all,
+        inverse_of: false
+
+      validates :session_id, presence: true, uniqueness: true
+    end
+  end
+end

data/lib/sentiero/rails/store.rb

@@ -0,0 +1,534 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require_relative "models/session"
+require_relative "models/event"
+require_relative "models/problem"
+require_relative "models/occurrence"
+require_relative "models/server_event"
+
+module Sentiero
+  module Rails
+    class Store < Sentiero::Store
+      def initialize(limits: nil)
+        @limits = limits
+      end
+
+      def save_events(ref, events)
+        return if events.nil? || events.empty?
+        session_id, window_id = ref.session_id, ref.window_id
+
+        now = Time.now
+
+        Session.transaction do
+          session = find_or_create_session!(session_id, now)
+          session.update_column(:updated_at, now) unless session.previously_new_record?
+
+          rows = events.map { |event|
+            {
+              session_id: session_id,
+              window_id: window_id,
+              timestamp: event["timestamp"]&.to_f,
+              data: event,
+              created_at: now
+            }
+          }
+          Event.insert_all(rows)
+
+          enforce_max_events_per_session(session_id)
+          enforce_max_sessions(session_id)
+        end
+
+        nil
+      end
+
+      # Batched scan: one events query for the whole session page instead of the
+      # base's get_session + get_events per window.
+      def each_session_events(limit: nil, since: nil, until_time: nil)
+        return enum_for(:each_session_events, limit: limit, since: since, until_time: until_time) unless block_given?
+
+        cap = limit || limits.analytics_max_scan_sessions
+        summaries = list_sessions(limit: cap, since: since, until_time: until_time)
+        return if summaries.empty?
+
+        events = events_by_session_window(summaries.map { |summary| summary[:session_id] })
+        summaries.each do |summary|
+          (events[summary[:session_id]] || {}).each do |window_id, window_events|
+            yield summary, window_id, window_events
+          end
+        end
+      end
+
+      def list_sessions(limit:, offset: 0, since: nil, until_time: nil, sort_by: nil, search: nil)
+        scope = filtered_session_scope(since:, until_time:, search:)
+        scope = ordered_session_scope(scope, sort_by)
+
+        sessions = scope.offset(offset).limit(limit).to_a
+        return [] if sessions.empty?
+
+        sids = sessions.map(&:session_id)
+        window_ids_by_session = window_ids_for(sids)
+        counts_by_session = event_counts_for(sids)
+        timestamp_ranges = timestamp_ranges_for(sids)
+
+        sessions.map { |session|
+          session_summary(session, window_ids_by_session, counts_by_session, timestamp_ranges)
+        }
+      end
+
+      def get_session(session_id)
+        validate_id!(session_id)
+        session = Session.find_by(session_id: session_id)
+        return nil unless session
+
+        window_stats = Event.where(session_id: session_id)
+          .group(:window_id)
+          .pluck(:window_id, Arel.sql("COUNT(*)"), Arel.sql("MIN(timestamp)"), Arel.sql("MAX(timestamp)"))
+
+        window_data = window_stats.map { |wid, count, first_ts, last_ts|
+          entry = {window_id: wid, event_count: count}
+          entry[:first_event_at] = first_ts.to_f if first_ts
+          entry[:last_event_at] = last_ts.to_f if last_ts
+          entry
+        }
+
+        timestamps = Event.where(session_id: session_id)
+          .pick(Arel.sql("MIN(timestamp)"), Arel.sql("MAX(timestamp)"))
+
+        result = {
+          session_id: session.session_id,
+          windows: window_data,
+          created_at: session.created_at.to_f,
+          updated_at: session.updated_at.to_f,
+          first_event_at: timestamps&.first&.to_f,
+          last_event_at: timestamps&.last&.to_f
+        }
+        if metadata_column? && session.metadata.present?
+          result[:metadata] = session.metadata
+        end
+        result
+      end
+
+      def get_events(ref, after: nil, limit: nil)
+        validate_window_ref!(ref)
+        session_id, window_id = ref.session_id, ref.window_id
+        scope = Event.where(session_id: session_id, window_id: window_id)
+          .order(timestamp: :asc)
+
+        scope = scope.where("timestamp > ?", after.to_f) if after
+        scope = scope.limit(limit) if limit
+
+        scope.map(&:data)
+      end
+
+      def save_metadata(session_id, metadata)
+        return unless metadata.is_a?(Hash) && !metadata.empty?
+        return unless metadata_column?
+        validate_metadata!(metadata)
+
+        session = Session.find_by(session_id: session_id)
+        return unless session
+
+        # Locked reload-merge-save, mirroring save_occurrence's Problem.lock:
+        # an unlocked read-modify-write here drops keys from a concurrent
+        # merge (e.g. this same method called for "has_errors" from
+        # save_occurrence racing a client-supplied metadata update).
+        session.with_lock do
+          existing = session.metadata || {}
+          session.update_column(:metadata, existing.merge(metadata.transform_keys(&:to_s)))
+        end
+        nil
+      end
+
+      def delete_session(session_id)
+        validate_id!(session_id)
+        Session.transaction do
+          destroy_session_data(session_id)
+        end
+        nil
+      end
+
+      def delete_window(ref)
+        validate_window_ref!(ref)
+        session_id, window_id = ref.session_id, ref.window_id
+        Session.transaction do
+          Event.where(session_id: session_id, window_id: window_id).delete_all
+
+          remaining = Event.where(session_id: session_id).exists?
+          unless remaining
+            Session.where(session_id: session_id).delete_all
+          end
+        end
+        nil
+      end
+
+      # Subquery-based DELETEs avoid loading stale ids into Ruby and large IN (...) lists.
+      def purge_older_than(seconds)
+        cutoff = Time.at(Time.now.to_f - seconds)
+        cutoff_f = cutoff.to_f
+        session_count = nil
+
+        Session.transaction do
+          stale = Session.where("updated_at < ?", cutoff)
+          Event.where(session_id: stale.select(:session_id)).delete_all
+          session_count = stale.delete_all
+
+          ServerEvent.where("timestamp < ?", cutoff_f).delete_all
+          Occurrence.where("timestamp < ?", cutoff_f).delete_all
+          stale_fps = Problem.where("last_seen < ?", cutoff_f).pluck(:fingerprint)
+          unless stale_fps.empty?
+            Occurrence.where(fingerprint: stale_fps).delete_all
+            Problem.where(fingerprint: stale_fps).delete_all
+          end
+        end
+
+        session_count
+      end
+
+      def save_occurrence(occurrence)
+        validate_occurrence!(occurrence)
+        fp = occurrence["fingerprint"]
+        ts = occurrence["timestamp"].to_f
+        occ_id = SecureRandom.uuid
+        stored = occurrence.merge("id" => occ_id)
+
+        # On a concurrent insert of a new fingerprint one writer's save! raises
+        # (RecordInvalid from the uniqueness validator, or RecordNotUnique from the
+        # DB index); retry so the loser re-runs and takes the "existing" branch.
+        attempts = 0
+        begin
+          Problem.transaction do
+            # SELECT ... FOR UPDATE so the count+1 / last_seen read-modify-write is
+            # serialized; an unlocked find lost concurrent updates under READ COMMITTED.
+            problem = Problem.lock.find_by(fingerprint: fp)
+            if problem
+              reopening = problem.status == "resolved"
+              problem.count += 1
+              problem.first_seen = [problem.first_seen, ts].min
+              problem.last_seen = [problem.last_seen, ts].max
+              problem.message = occurrence["message"]
+              if reopening
+                problem.status = "open"
+                problem.resolved_at = nil
+              end
+            else
+              problem = Problem.new(fingerprint: fp)
+              problem.project = occurrence["project"]
+              problem.exception_class = occurrence["exception_class"]
+              problem.title = build_problem_title(occurrence)
+              problem.message = occurrence["message"]
+              problem.count = 1
+              problem.status = "open"
+              problem.first_seen = ts
+              problem.last_seen = ts
+              problem.resolved_at = nil
+            end
+            problem.save!
+
+            Occurrence.create!(
+              occurrence_id: occ_id,
+              fingerprint: fp,
+              session_id: occurrence["session_id"],
+              timestamp: ts,
+              data: stored
+            )
+
+            enforce_max_problems
+          end
+        rescue ::ActiveRecord::RecordNotUnique
+          attempts += 1
+          retry if attempts < 2
+          raise
+        rescue ::ActiveRecord::RecordInvalid => e
+          raise unless e.record.errors[:fingerprint].any?
+          attempts += 1
+          retry if attempts < 2
+          raise
+        end
+
+        save_metadata(occurrence["session_id"], {"has_errors" => true}) if occurrence["session_id"]
+        fp
+      end
+
+      def list_problems(project:, limit:, offset: 0, status: nil, sort_by: nil, search: nil, since: nil, until_time: nil)
+        scope = Problem.all
+        scope = scope.where(project: project) unless project.nil?
+        scope = scope.where(status: status) if status
+        scope = scope.where("last_seen >= ?", since.to_f) if since
+        scope = scope.where("last_seen <= ?", until_time.to_f) if until_time
+        if search && !search.empty?
+          pattern = "%#{search}%"
+          scope = scope.where("title LIKE ? OR exception_class LIKE ?", pattern, pattern)
+        end
+        scope = case sort_by
+        when "first_seen" then scope.order(first_seen: :desc)
+        when "count" then scope.order(count: :desc)
+        else scope.order(last_seen: :desc)
+        end
+        scope.offset(offset).limit(limit).map { |p| problem_to_hash(p) }
+      end
+
+      def get_problem(problem_id)
+        validate_id!(problem_id)
+        problem = Problem.find_by(fingerprint: problem_id)
+        problem ? problem_to_hash(problem) : nil
+      end
+
+      def get_occurrences(problem_id, after: nil, limit: nil)
+        validate_id!(problem_id)
+        scope = Occurrence.where(fingerprint: problem_id).order(timestamp: :asc)
+        scope = scope.where("timestamp > ?", after.to_f) if after
+        scope = scope.limit(limit) if limit
+        scope.map(&:data)
+      end
+
+      # COUNT in SQL instead of materializing every row.
+      def count_occurrences(problem_id, after: nil)
+        validate_id!(problem_id)
+        scope = Occurrence.where(fingerprint: problem_id)
+        scope = scope.where("timestamp > ?", after.to_f) if after
+        scope.count
+      end
+
+      def update_problem_status(problem_id, status)
+        validate_id!(problem_id)
+        validate_status!(status)
+        resolved_at = (status == "resolved") ? Time.now.to_f : nil
+        Problem.where(fingerprint: problem_id).update_all(status: status, resolved_at: resolved_at)
+        nil
+      end
+
+      def save_server_event(event)
+        validate_server_event!(event)
+        ev_id = SecureRandom.uuid
+        stored = event.merge("id" => ev_id)
+        ServerEvent.transaction do
+          ServerEvent.create!(
+            event_id: ev_id,
+            project: event["project"],
+            name: event["name"],
+            level: event["level"],
+            session_id: event["session_id"],
+            timestamp: event["timestamp"].to_f,
+            data: stored
+          )
+          enforce_max_server_events
+        end
+        nil
+      end
+
+      def get_server_event(event_id)
+        validate_id!(event_id)
+        ServerEvent.find_by(event_id: event_id)&.data
+      end
+
+      def list_server_events(project:, limit:, name: nil, level: nil, session_id: nil, after: nil)
+        scope = ServerEvent.all
+        scope = scope.where(project: project) unless project.nil?
+        scope = scope.order(timestamp: :asc)
+        scope = scope.where(name: name) if name
+        scope = scope.where(level: level) if level
+        scope = scope.where(session_id: session_id) if session_id
+        scope = scope.where("timestamp > ?", after.to_f) if after
+        scope.limit(limit).map(&:data)
+      end
+
+      def occurrences_for_session(session_id, limit: nil)
+        validate_id!(session_id)
+        scope = Occurrence.where(session_id: session_id).order(timestamp: :asc)
+        scope = scope.limit(limit) if limit
+        scope.map(&:data)
+      end
+
+      def server_events_for_session(session_id, limit: nil)
+        validate_id!(session_id)
+        scope = ServerEvent.where(session_id: session_id).order(timestamp: :asc)
+        scope = scope.limit(limit) if limit
+        scope.map(&:data)
+      end
+
+      def session_ids_for_problem(problem_id, limit: nil)
+        validate_id!(problem_id)
+        scope = Occurrence.where(fingerprint: problem_id)
+          .where.not(session_id: nil)
+          .group(:session_id)
+          .order(Arel.sql("MAX(timestamp) DESC"))
+          .pluck(:session_id)
+        limit ? scope.first(limit) : scope
+      end
+
+      private
+
+      def metadata_column?
+        Session.column_names.include?("metadata")
+      end
+
+      def filtered_session_scope(since:, until_time:, search:)
+        scope = Session.all
+        scope = scope.where("updated_at >= ?", Time.at(since.to_f)) if since
+        scope = scope.where("updated_at <= ?", Time.at(until_time.to_f)) if until_time
+
+        if search && !search.empty?
+          pattern = "%#{search}%"
+          scope = if metadata_column?
+            scope.where("session_id LIKE ? OR CAST(metadata AS TEXT) LIKE ?", pattern, pattern)
+          else
+            scope.where("session_id LIKE ?", pattern)
+          end
+        end
+
+        scope
+      end
+
+      def ordered_session_scope(scope, sort_by)
+        if sort_by == "event_count"
+          scope
+            .joins("LEFT JOIN #{Event.table_name} ON #{Event.table_name}.session_id = #{Session.table_name}.session_id")
+            .group("#{Session.table_name}.id")
+            .order(Arel.sql("COUNT(#{Event.table_name}.id) DESC"))
+        else
+          sort_column = case sort_by
+          when "created_at" then :created_at
+          else :updated_at
+          end
+          scope.order(sort_column => :desc)
+        end
+      end
+
+      def window_ids_for(session_ids)
+        Event.where(session_id: session_ids)
+          .distinct.pluck(:session_id, :window_id)
+          .group_by(&:first)
+          .transform_values { |pairs| pairs.map(&:last) }
+      end
+
+      def events_by_session_window(session_ids)
+        grouped = Hash.new { |h, sid| h[sid] = {} }
+        Event.where(session_id: session_ids).order(:timestamp).each do |event|
+          (grouped[event.session_id][event.window_id] ||= []) << event.data
+        end
+        grouped
+      end
+
+      def event_counts_for(session_ids)
+        Event.where(session_id: session_ids)
+          .group(:session_id).count
+      end
+
+      def timestamp_ranges_for(session_ids)
+        Event.where(session_id: session_ids)
+          .group(:session_id)
+          .pluck(:session_id, Arel.sql("MIN(timestamp)"), Arel.sql("MAX(timestamp)"))
+          .to_h { |sid, min_ts, max_ts| [sid, {first: min_ts&.to_f, last: max_ts&.to_f}] }
+      end
+
+      def session_summary(session, window_ids_by_session, counts_by_session, timestamp_ranges)
+        range = timestamp_ranges[session.session_id]
+        summary_hash(
+          session_id: session.session_id,
+          window_ids: window_ids_by_session[session.session_id] || [],
+          event_count: counts_by_session[session.session_id] || 0,
+          created_at: session.created_at.to_f,
+          updated_at: session.updated_at.to_f,
+          first_event_at: range&.dig(:first),
+          last_event_at: range&.dig(:last),
+          metadata: metadata_column? ? session.metadata : nil
+        )
+      end
+
+      def find_or_create_session!(session_id, now)
+        Session.find_or_create_by!(session_id: session_id) do |s|
+          s.created_at = now
+          s.updated_at = now
+        end
+      rescue ::ActiveRecord::RecordNotUnique
+        Session.find_by!(session_id: session_id)
+      end
+
+      def enforce_max_events_per_session(session_id)
+        max_events = limits.max_events_per_session
+        return unless max_events
+
+        total = Event.where(session_id: session_id).count
+        return unless total > max_events
+
+        excess = total - max_events
+        oldest_ids = Event.where(session_id: session_id)
+          .order(timestamp: :asc)
+          .limit(excess)
+          .pluck(:id)
+        Event.where(id: oldest_ids).delete_all
+      end
+
+      def enforce_max_sessions(protected_session_id)
+        max_sessions = limits.max_sessions
+        return unless max_sessions
+
+        total = Session.count
+        return unless total > max_sessions
+
+        to_evict = total - max_sessions
+        oldest = Session.where.not(session_id: protected_session_id)
+          .order(updated_at: :asc)
+          .limit(to_evict)
+          .pluck(:session_id)
+
+        return if oldest.empty?
+
+        Event.where(session_id: oldest).delete_all
+        Session.where(session_id: oldest).delete_all
+      end
+
+      def destroy_session_data(session_id)
+        Event.where(session_id: session_id).delete_all
+        Session.where(session_id: session_id).delete_all
+        # GDPR erasure of session-scoped rows. The Problem aggregate is retained,
+        # though its title/message may still hold PII — a known erasure residue.
+        Occurrence.where(session_id: session_id).delete_all
+        ServerEvent.where(session_id: session_id).delete_all
+      end
+
+      def problem_to_hash(problem)
+        {
+          id: problem.fingerprint,
+          project: problem.project,
+          exception_class: problem.exception_class,
+          title: problem.title,
+          message: problem.message,
+          count: problem.count,
+          status: problem.status,
+          first_seen: problem.first_seen,
+          last_seen: problem.last_seen,
+          resolved_at: problem.resolved_at
+        }
+      end
+
+      def enforce_max_problems
+        max = limits.max_problems
+        return unless max
+
+        total = Problem.count
+        return unless total > max
+
+        excess = total - max
+        oldest_fps = Problem.order(last_seen: :asc).limit(excess).pluck(:fingerprint)
+        return if oldest_fps.empty?
+
+        Occurrence.where(fingerprint: oldest_fps).delete_all
+        Problem.where(fingerprint: oldest_fps).delete_all
+      end
+
+      def enforce_max_server_events
+        max = limits.max_server_events
+        return unless max
+
+        total = ServerEvent.count
+        return unless total > max
+
+        excess = total - max
+        oldest_ids = ServerEvent.order(timestamp: :asc).limit(excess).pluck(:id)
+        ServerEvent.where(id: oldest_ids).delete_all
+      end
+    end
+  end
+end

data/lib/sentiero/rails/tasks/sentiero.rake

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "time"
+
+namespace :sentiero do
+  desc "Purge sessions older than config.retention_period (destructive, irreversible)"
+  task purge: :environment do
+    deleted = Sentiero.purge_expired!
+    if deleted.nil?
+      puts "Sentiero: retention_period not configured; nothing purged."
+    else
+      puts "Sentiero: purged #{deleted} session(s)."
+    end
+  end
+
+  desc "Erase sessions by ID or time range (GDPR Art. 17; destructive, irreversible)"
+  task erase: :environment do
+    ids_env = ENV["SESSION_IDS"] || ENV["SESSION_ID"]
+    if ids_env
+      deleted = Sentiero.erase_sessions(ids_env.split(","))
+      puts "Sentiero: erased #{deleted} session(s)."
+    elsif ENV["SINCE"] || ENV["UNTIL"]
+      since = ENV["SINCE"] ? Time.parse(ENV["SINCE"]) : nil
+      until_time = ENV["UNTIL"] ? Time.parse(ENV["UNTIL"]) : nil
+      deleted = Sentiero.erase_where(since: since, until_time: until_time)
+      puts "Sentiero: erased #{deleted} session(s)."
+    else
+      abort "Usage: rake sentiero:erase SESSION_IDS=id1,id2  OR  SINCE=YYYY-MM-DD UNTIL=YYYY-MM-DD"
+    end
+  end
+end

data/lib/sentiero/rails/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "sentiero/version"
+
+module Sentiero
+  module Rails
+    VERSION = Sentiero::VERSION
+  end
+end

data/lib/sentiero/rails.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require "sentiero"
+require_relative "rails/version"
+require_relative "rails/configuration"
+require_relative "rails/engine"

metadata

@@ -0,0 +1,114 @@
+--- !ruby/object:Gem::Specification
+name: sentiero-rails
+version: !ruby/object:Gem::Version
+  version: 1.0.0.alpha1
+platform: ruby
+authors:
+- Stephen Ierodiaconou
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: sentiero
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.0.0.alpha1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.0.0.alpha1
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+description: Rails engine providing ActiveRecord storage, view helpers, and generators
+  for the Sentiero session recording gem.
+email:
+- stevegeek@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- lib/sentiero/rails.rb
+- lib/sentiero/rails/configuration.rb
+- lib/sentiero/rails/engine.rb
+- lib/sentiero/rails/generators/sentiero/install_generator.rb
+- lib/sentiero/rails/generators/sentiero/templates/create_sentiero_tables.rb.erb
+- lib/sentiero/rails/generators/sentiero/templates/initializer.rb
+- lib/sentiero/rails/helpers/script_tag_helper.rb
+- lib/sentiero/rails/models/event.rb
+- lib/sentiero/rails/models/occurrence.rb
+- lib/sentiero/rails/models/problem.rb
+- lib/sentiero/rails/models/server_event.rb
+- lib/sentiero/rails/models/session.rb
+- lib/sentiero/rails/store.rb
+- lib/sentiero/rails/tasks/sentiero.rake
+- lib/sentiero/rails/version.rb
+homepage: https://github.com/stevegeek/sentiero
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/stevegeek/sentiero
+  source_code_uri: https://github.com/stevegeek/sentiero
+  bug_tracker_uri: https://github.com/stevegeek/sentiero/issues
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Rails integration for Sentiero browser session recording
+test_files: []