sentiero 1.0.0.alpha1

data/lib/sentiero/reporter/scrubber.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative "../redaction"
+
+module Sentiero
+  module Reporter
+    # Replaces values whose key matches a sensitive pattern with "[FILTERED]",
+    # before data leaves the host app, so secrets never traverse the network.
+    # Matching is case-insensitive and substring based ("user_password" matches "password").
+    class Scrubber
+      FILTERED = "[FILTERED]"
+      # Superset of Redaction::BUILTIN_DENYLIST (the browser-lane URL param
+      # denylist) plus a few extras (credit card/SSN) the query-string lane
+      # doesn't need to cover. Keeping this as a union rather than a hand
+      # copy means the two lanes can't drift apart again.
+      DEFAULT_KEYS = (%w[
+        password passwd secret token api_key apikey authorization
+        access_token refresh_token secret_key private_key
+        credit_card card_number cvv ssn
+      ] + Redaction::BUILTIN_DENYLIST).uniq.freeze
+
+      def initialize(keys = DEFAULT_KEYS)
+        @patterns = Array(keys).map { |k| k.to_s.downcase }
+      end
+
+      def scrub(obj)
+        case obj
+        when Hash
+          obj.each_with_object(obj.class.new) do |(k, v), acc|
+            acc[k] = sensitive?(k) ? FILTERED : scrub(v)
+          end
+        when Array
+          obj.map { |v| scrub(v) }
+        else
+          obj
+        end
+      end
+
+      private
+
+      def sensitive?(key)
+        down = key.to_s.downcase
+        @patterns.any? { |pattern| down.include?(pattern) }
+      end
+    end
+  end
+end

data/lib/sentiero/reporter/test_helper.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "test_transport"
+
+module Sentiero
+  module Reporter
+    # Test-suite support for asserting what the reporter would have sent.
+    # Not loaded by default: require "sentiero/reporter/test_helper".
+    module TestHelper
+      extend self
+
+      # Runs the block with a synchronous in-memory transport, restores the
+      # previous transport, and returns deliveries as [path, payload] pairs.
+      def capture_notifications
+        recorder = TestTransport.new
+        previous_transport = Reporter.configuration.transport
+        previous_async = Reporter.configuration.async
+        Reporter.configure do |c|
+          c.transport = recorder
+          c.async = false
+        end
+        yield
+        recorder.deliveries
+      ensure
+        Reporter.configure do |c|
+          c.transport = previous_transport
+          c.async = previous_async
+        end
+      end
+    end
+  end
+end

data/lib/sentiero/reporter/test_transport.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Sentiero
+  module Reporter
+    # Transport that records every delivery in memory so host-app tests can
+    # assert what the reporter would have sent.
+    class TestTransport
+      attr_reader :deliveries
+
+      def initialize
+        @deliveries = []
+      end
+
+      def post(path, payload)
+        @deliveries << [path, payload]
+        nil
+      end
+
+      def payloads_for(path)
+        @deliveries.select { |p, _| p == path }.map(&:last)
+      end
+
+      def clear
+        @deliveries.clear
+      end
+    end
+  end
+end

data/lib/sentiero/reporter.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "redaction"
+require_relative "reporter/configuration"
+require_relative "reporter/normalizer"
+require_relative "reporter/context"
+require_relative "reporter/report_context"
+require_relative "reporter/scrubber"
+require_relative "reporter/dispatcher"
+require_relative "reporter/http_transport"
+require_relative "reporter/null_transport"
+require_relative "reporter/log_transport"
+require_relative "reporter/test_transport"
+
+module Sentiero
+  # Client SDK for reporting exceptions and custom events to a (remote) Sentiero
+  # ingest. Every public method is fail-safe: it never raises into the host app.
+  module Reporter
+    # Guards lazy creation/teardown of the shared dispatcher (which spawns a
+    # background thread + queue) so a concurrent cold start can't build two.
+    RUNTIME_LOCK = Mutex.new
+
+    class << self
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      def configure
+        yield(configuration)
+        reset_runtime!
+        configuration
+      end
+
+      def reset!
+        RUNTIME_LOCK.synchronize do
+          shutdown
+          @configuration = Configuration.new
+          @dispatcher = nil
+          @scrubber = nil
+        end
+      end
+
+      def notify(exception, context: {})
+        return unless configuration.active?
+        return if ignored?(exception)
+
+        payload = run_before_notify(build_error_payload(exception, build_report_context(context)))
+        return if payload.nil?
+
+        dispatcher.enqueue("errors", payload)
+        nil
+      rescue => e
+        warn "[Sentiero::Reporter] notify failed: #{e.class}: #{e.message}"
+        nil
+      end
+
+      def track(name, level: "info", session_id: nil, **payload)
+        return unless configuration.active?
+
+        dispatcher.enqueue("track", build_track_event(name, level, session_id, payload))
+        nil
+      rescue => e
+        warn "[Sentiero::Reporter] track failed: #{e.class}: #{e.message}"
+        nil
+      end
+
+      # Per-thread context. Stored as a Context (string-keyed by construction)
+      # so readback is consistently string-keyed.
+      def context
+        context_store.to_h
+      end
+
+      def add_context(hash)
+        self.fiber_local_context = context_store.merge(hash)
+      end
+
+      def with_context(hash)
+        previous = context_store
+        self.fiber_local_context = context_store.merge(hash)
+        yield
+      ensure
+        self.fiber_local_context = previous
+      end
+
+      def clear_context
+        self.fiber_local_context = Context.new
+      end
+
+      def flush
+        @dispatcher&.flush
+      end
+
+      def shutdown
+        @dispatcher&.shutdown
+      end
+
+      private
+
+      def context_key
+        :sentiero_reporter_context
+      end
+
+      def fiber_local_context
+        Thread.current[context_key]
+      end
+
+      def fiber_local_context=(value)
+        Thread.current[context_key] = value
+      end
+
+      def context_store
+        self.fiber_local_context ||= Context.new
+      end
+
+      # ignore_exceptions entries are matched as Class (is_a?) or String class-name.
+      def ignored?(exception)
+        configuration.ignore_exceptions.any? do |matcher|
+          case matcher
+          when Module
+            exception.is_a?(matcher)
+          when String
+            exception.class.ancestors.any? { |a| a.name == matcher }
+          else
+            false
+          end
+        end
+      rescue => e
+        warn "[Sentiero::Reporter] ignore_exceptions check failed: #{e.class}: #{e.message}"
+        false
+      end
+
+      def build_report_context(context)
+        report_ctx = ReportContext.new(context_store.merge(context))
+        meta = report_ctx.metadata
+        meta["environment"] = configuration.environment if configuration.environment
+        meta["release"] = configuration.release if configuration.release
+        report_ctx
+      end
+
+      def build_error_payload(exception, report_ctx)
+        config = redaction_config
+        payload = {
+          "exception_class" => exception.class.name,
+          "message" => Redaction.redact_text(exception.message.to_s, config),
+          "backtrace" => Array(exception.backtrace).map { |frame| Redaction.redact_text(frame.to_s, config) },
+          "context" => Redaction.deep_redact_strings(scrubber.scrub(report_ctx.metadata), config),
+          "timestamp" => Time.now.to_f
+        }
+        payload["session_id"] = report_ctx.session_id if report_ctx.session_id
+        payload["window_id"] = report_ctx.window_id if report_ctx.window_id
+        payload
+      end
+
+      # An explicit session_id wins; otherwise fall back to the thread context.
+      def build_track_event(name, level, session_id, payload)
+        scrubbed = scrubber.scrub(Normalizer.stringify_shallow(payload))
+        event = {
+          "name" => name.to_s,
+          "level" => level.to_s,
+          "payload" => Redaction.deep_redact_strings(scrubbed, redaction_config),
+          "timestamp" => Time.now.to_f
+        }
+        session_id ||= context_store["session_id"]
+        event["session_id"] = session_id if session_id
+        event
+      end
+
+      # Returns the (possibly mutated) report, or nil to drop it when the hook
+      # returns false/nil.
+      def run_before_notify(payload)
+        hook = configuration.before_notify
+        return payload unless hook
+
+        result = hook.call(payload)
+        return if result == false || result.nil?
+        result.is_a?(Hash) ? result : payload
+      rescue => e
+        warn "[Sentiero::Reporter] before_notify failed: #{e.class}: #{e.message}"
+        payload
+      end
+
+      def scrubber
+        @scrubber || RUNTIME_LOCK.synchronize { @scrubber ||= Scrubber.new(configuration.default_filter_keys + configuration.filter_keys) }
+      end
+
+      # Defaults when core isn't loaded, so a standalone reporter client still redacts.
+      def redaction_config
+        Sentiero.respond_to?(:configuration) ? Sentiero.configuration.redaction : Redaction::Config.new
+      end
+
+      def dispatcher
+        @dispatcher || RUNTIME_LOCK.synchronize { @dispatcher ||= Dispatcher.new(transport, async: configuration.async, max_queue: configuration.max_queue) }
+      end
+
+      def transport
+        configuration.transport || HttpTransport.new(
+          endpoint: configuration.endpoint,
+          ingest_key: configuration.ingest_key,
+          open_timeout: configuration.open_timeout,
+          read_timeout: configuration.read_timeout
+        )
+      end
+
+      def reset_runtime!
+        RUNTIME_LOCK.synchronize do
+          shutdown
+          @dispatcher = nil
+          @scrubber = nil
+        end
+      end
+    end
+  end
+end

data/lib/sentiero/roda.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "sentiero"
+
+class Roda
+  module RodaPlugins
+    module Sentiero
+      def self.configure(_app, **opts)
+        config = ::Sentiero.configuration
+        opts.each do |key, value|
+          setter = :"#{key}="
+          config.public_send(setter, value) if config.respond_to?(setter)
+        end
+      end
+
+      module RequestMethods
+        def sentiero_events
+          run ::Sentiero::Web::EventsApp.new
+        end
+
+        def sentiero_assets
+          run ::Sentiero::Web::AssetsApp.new
+        end
+
+        def sentiero_dashboard
+          run ::Sentiero::Web::DashboardApp.new
+        end
+
+        def sentiero_analytics
+          run ::Sentiero::Web::AnalyticsApp.new
+        end
+
+        def sentiero_monitoring
+          run ::Sentiero::Web::MonitoringApp.new
+        end
+      end
+
+      module InstanceMethods
+        def sentiero_script_tag(events_url:, recorder_url: nil)
+          ::Sentiero::Web::ScriptTag.render(events_url: events_url, recorder_url: recorder_url)
+        end
+      end
+    end
+
+    register_plugin(:sentiero, Sentiero)
+  end
+end

data/lib/sentiero/store/error_store.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+module Sentiero
+  class Store
+    # The error-tracking store contract: problems, occurrences, and server events.
+    #
+    # Keying convention: raw stored records (occurrences, server events) are
+    # string-keyed Hashes, exactly as they arrived from JSON; computed
+    # summaries (problems) are symbol-keyed.
+    module ErrorStore
+      # Records the occurrence and upserts its Problem (keyed by "fingerprint"):
+      # bump count, extend last_seen, preserve first_seen, refresh message,
+      # reopen if "resolved". Returns the problem id (== fingerprint).
+      def save_occurrence(occurrence)
+        raise NoMethodError, "#{self.class}#save_occurrence not implemented"
+      end
+
+      # since/until_time (epoch seconds) bound the listing by each problem's
+      # last_seen, inclusive on both ends.
+      def list_problems(project:, limit:, offset: 0, status: nil, sort_by: nil, search: nil, since: nil, until_time: nil)
+        raise NoMethodError, "#{self.class}#list_problems not implemented"
+      end
+
+      # Returns the symbol-keyed problem summary, or nil when unknown.
+      def get_problem(problem_id)
+        raise NoMethodError, "#{self.class}#get_problem not implemented"
+      end
+
+      # Returns string-keyed occurrence records as stored (plus assigned "id"),
+      # ascending by timestamp; `after` is an exclusive timestamp cursor.
+      def get_occurrences(problem_id, after: nil, limit: nil)
+        raise NoMethodError, "#{self.class}#get_occurrences not implemented"
+      end
+
+      # Default materializes rows via get_occurrences so custom stores keep
+      # working; built-in backends override with direct counts.
+      def count_occurrences(problem_id, after: nil)
+        get_occurrences(problem_id, after: after).size
+      end
+
+      def update_problem_status(problem_id, status)
+        raise NoMethodError, "#{self.class}#update_problem_status not implemented"
+      end
+
+      def save_server_event(event)
+        raise NoMethodError, "#{self.class}#save_server_event not implemented"
+      end
+
+      # Returns string-keyed server-event records as stored (plus assigned
+      # "id"), ascending by timestamp; `after` is an exclusive timestamp cursor.
+      def list_server_events(project:, limit:, name: nil, level: nil, session_id: nil, after: nil)
+        raise NoMethodError, "#{self.class}#list_server_events not implemented"
+      end
+
+      def get_server_event(event_id)
+        raise NoMethodError, "#{self.class}#get_server_event not implemented"
+      end
+
+      def occurrences_for_session(session_id, limit: nil)
+        raise NoMethodError, "#{self.class}#occurrences_for_session not implemented"
+      end
+
+      def server_events_for_session(session_id, limit: nil)
+        raise NoMethodError, "#{self.class}#server_events_for_session not implemented"
+      end
+
+      def session_ids_for_problem(problem_id, limit: nil)
+        raise NoMethodError, "#{self.class}#session_ids_for_problem not implemented"
+      end
+
+      private
+
+      # Shared problem bookkeeping: the semantic source of truth for problem
+      # lifecycle rules, which SQLite and the Rails store re-express natively.
+
+      # The list_problems filter/sort/paginate pipeline over symbol-keyed problem
+      # hashes; since/until_time bounds on last_seen are inclusive. Returns dups
+      # so callers can't mutate stored problems through the result.
+      def filter_and_page_problems(items, project:, status:, since:, until_time:, search:, sort_by:, offset:, limit:)
+        items = items.select { |p| p[:project] == project } unless project.nil?
+        items = items.select { |p| p[:status] == status } if status
+        items = items.select { |p| p[:last_seen] >= since.to_f } if since
+        items = items.select { |p| p[:last_seen] <= until_time.to_f } if until_time
+        if search && !search.empty?
+          term = search.downcase
+          items = items.select { |p|
+            p[:title].downcase.include?(term) || p[:exception_class].downcase.include?(term)
+          }
+        end
+        items = case sort_by
+        when "first_seen" then items.sort_by { |p| -p[:first_seen] }
+        when "count" then items.sort_by { |p| -p[:count] }
+        else items.sort_by { |p| -p[:last_seen] }
+        end
+        (items.slice(offset, limit) || []).map(&:dup)
+      end
+
+      def new_problem_attrs(occurrence, ts)
+        {
+          id: occurrence["fingerprint"],
+          project: occurrence["project"],
+          exception_class: occurrence["exception_class"],
+          title: build_problem_title(occurrence),
+          message: occurrence["message"],
+          count: 1,
+          status: "open",
+          first_seen: ts,
+          last_seen: ts,
+          resolved_at: nil
+        }
+      end
+
+      # Upsert rule for a repeat occurrence: reopens the problem if resolved.
+      def touched_problem_attrs(existing, occurrence, ts)
+        reopening = existing[:status] == "resolved"
+        existing.merge(
+          count: existing[:count] + 1,
+          first_seen: [existing[:first_seen], ts].min,
+          last_seen: [existing[:last_seen], ts].max,
+          message: occurrence["message"],
+          status: reopening ? "open" : existing[:status],
+          resolved_at: reopening ? nil : existing[:resolved_at]
+        )
+      end
+
+      def build_problem_title(occurrence)
+        "#{occurrence["exception_class"]}: #{occurrence["message"]}"[0, PROBLEM_TITLE_MAX]
+      end
+
+      # Maps a string-keyed stored problem record to the symbol-keyed shape.
+      def problem_from_strings(h)
+        {
+          id: h["id"],
+          project: h["project"],
+          exception_class: h["exception_class"],
+          title: h["title"],
+          message: h["message"],
+          count: h["count"],
+          status: h["status"],
+          first_seen: h["first_seen"],
+          last_seen: h["last_seen"],
+          resolved_at: h["resolved_at"]
+        }
+      end
+
+      # Shared in-memory error-data read/purge layer for backends holding whole
+      # collections in Ruby (Memory, File, Redis). The mutating helpers
+      # (!-suffixed) must receive the live collections, inside whatever
+      # synchronization the caller owns. Works on plain Hash/Array and their
+      # concurrent-ruby counterparts.
+
+      # list_server_events filter pipeline; `after` is an exclusive cursor.
+      def filter_server_events(events, project:, name:, level:, session_id:, after:, limit:)
+        items = events
+        items = items.select { |e| e["project"] == project } unless project.nil?
+        items = items.select { |e| e["name"] == name } if name
+        items = items.select { |e| e["level"] == level } if level
+        items = items.select { |e| e["session_id"] == session_id } if session_id
+        items = items.select { |e| e["timestamp"].to_f > after.to_f } if after
+        items = items.sort_by { |e| e["timestamp"].to_f }
+        items.first(limit)
+      end
+
+      def rows_for_session(rows, session_id, limit:)
+        result = rows
+          .select { |row| row["session_id"] == session_id }
+          .sort_by { |row| row["timestamp"].to_f }
+        limit ? result.first(limit) : result
+      end
+
+      # Distinct session ids across an occurrence list, most recently seen first
+      # (by each session's latest occurrence). Occurrences without a session_id
+      # are skipped.
+      def latest_session_ids(occurrences, limit:)
+        latest_by_session = {}
+        occurrences.each do |occ|
+          sid = occ["session_id"]
+          next unless sid
+          ts = occ["timestamp"].to_f
+          latest_by_session[sid] = [latest_by_session[sid] || ts, ts].max
+        end
+        ids = latest_by_session.sort_by { |_sid, ts| -ts }.map(&:first)
+        limit ? ids.first(limit) : ids
+      end
+
+      # Ages out error data older than the cutoff, in place: server events and
+      # occurrence rows by timestamp, then problems whose last_seen is stale
+      # (along with their remaining occurrences).
+      def purge_error_collections!(problems, occurrences, server_events, cutoff)
+        server_events.reject! { |event| event["timestamp"].to_f < cutoff }
+
+        occurrences.each_pair do |_fp, list|
+          list.reject! { |occ| occ["timestamp"].to_f < cutoff }
+        end
+
+        stale_fps = problems.each_pair.filter_map { |fp, problem| fp if problem[:last_seen] < cutoff }
+        stale_fps.each do |fp|
+          problems.delete(fp)
+          occurrences.delete(fp)
+        end
+      end
+
+      # Evicts the least-recently-seen problems (and their occurrences), in
+      # place, until at most `max` remain. No-op when max is nil.
+      def evict_oldest_problems!(problems, occurrences, max)
+        return unless max && problems.size > max
+
+        to_evict = problems.size - max
+        oldest_fps = problems.each_pair
+          .sort_by { |_fp, problem| problem[:last_seen] }
+          .first(to_evict)
+          .map(&:first)
+        oldest_fps.each do |fp|
+          problems.delete(fp)
+          occurrences.delete(fp)
+        end
+      end
+    end
+  end
+end

data/lib/sentiero/store/limits.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Sentiero
+  class Store
+    # Eviction/scan caps for a store, held by the store itself instead of read
+    # from the global Sentiero.configuration. Build one explicitly, or derive the
+    # configured defaults at the composition root with .from_configuration.
+    class Limits
+      DEFAULTS = {
+        max_events_per_session: nil,
+        max_sessions: nil,
+        max_problems: 5_000,
+        max_server_events: 50_000,
+        analytics_max_scan_sessions: 5_000
+      }.freeze
+
+      def self.from_configuration(config = Sentiero.configuration)
+        new(**DEFAULTS.keys.to_h { |attr| [attr, config.public_send(attr)] })
+      end
+
+      attr_reader(*DEFAULTS.keys)
+
+      def initialize(**overrides)
+        unknown = overrides.keys - DEFAULTS.keys
+        raise ArgumentError, "unknown limit(s): #{unknown.join(", ")}" unless unknown.empty?
+
+        DEFAULTS.merge(overrides).each { |attr, value| instance_variable_set(:"@#{attr}", value) }
+      end
+    end
+  end
+end