sentiero 1.0.0.alpha1

data/lib/sentiero/web/dashboard_app.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+require_relative "base_app"
+require_relative "analytics_app"
+require_relative "monitoring_app"
+
+module Sentiero
+  module Web
+    class DashboardApp < BaseApp
+      def initialize
+        super
+        BaseApp.warn_unauthenticated_once
+      end
+
+      def call(env)
+        # Rack::Builder#map "/sentiero" leaves PATH_INFO empty (not "/") for a
+        # request to the bare mount point; treat it as the index.
+        path = env["PATH_INFO"]
+        path = "/" if path.nil? || path.empty?
+        method = env["REQUEST_METHOD"]
+
+        # Static assets are served before auth: they carry no session data, and
+        # the standalone AssetsApp endpoint serves the same files unauthenticated.
+        if (asset_path = path[%r{\A/assets/(.+)\z}, 1])
+          return handle_asset(asset_path)
+        end
+
+        # Stable alias for the content-hashed recorder bundle, so pages outside
+        # the Ruby helpers (static HTML) can hardcode one URL that survives
+        # rebuilds. Sibling of the /events mount, so the recorder's
+        # currentScript fallback derives eventsUrl correctly from it.
+        return handle_recorder_alias if path == "/recorder.js"
+
+        return unauthorized_response unless authorized?(env)
+
+        case path
+        when "/"
+          handle_index(env)
+        when %r{\A/sessions/([^/]+)/windows/([^/]+)\z}
+          sid, wid = $1, $2
+          guard(sid, wid) ||
+            (delete_request?(method, env) ? handle_delete_window(env, sid, wid) : handle_show(env, sid, wid))
+        when %r{\A/api/sessions/([^/]+)/windows/([^/]+)/events\z}
+          sid, wid = $1, $2
+          guard(sid, wid) || handle_events_api(env, sid, wid)
+        when "/sessions/bulk_delete"
+          post_only(method) || handle_bulk_delete(env)
+        when %r{\A/sessions/([^/]+)\z}
+          sid = $1
+          # The delete branch keys off delete_request? (DELETE, or POST with
+          # ?_method=delete), so the id guard nests inside the method dispatch
+          # rather than using the get_only/post_only combinators.
+          if method == "GET"
+            guard(sid) || handle_session_redirect(env, sid)
+          elsif delete_request?(method, env)
+            guard(sid) || handle_delete(env, sid)
+          else
+            not_found
+          end
+        when %r{\A/custom-events(?:/.*)?\z}
+          Sentiero::Web::MonitoringApp.new.call(env)
+        when %r{\A/issues(?:/.*)?\z}
+          Sentiero::Web::MonitoringApp.new.call(env)
+        when %r{\A/analytics(?:/.*)?\z}
+          Sentiero::Web::AnalyticsApp.new.call(env)
+        else
+          not_found
+        end
+      end
+
+      private
+
+      def handle_recorder_alias
+        filename = Manifest.manifest["recorder"]
+        return not_found unless filename
+
+        status, headers, body = handle_asset(filename)
+        # The alias serves new bundle contents after an upgrade, so it must not
+        # inherit the fingerprinted file's year-long immutable cache.
+        headers["cache-control"] = "public, max-age=300" if status == 200
+        [status, headers, body]
+      end
+
+      def qs_url(path, env)
+        qs = env["QUERY_STRING"]
+        (qs && !qs.empty?) ? "#{path}?#{qs}" : path
+      end
+
+      def handle_index(env)
+        params = query_params(env)
+        page, per_page, offset = paginate(params, default: 20, max: 100)
+
+        since, until_time = parse_range_params(params)
+        sort_by = %w[updated_at created_at event_count].include?(params["sort_by"]) ? params["sort_by"] : nil
+        search = params["search"]&.strip
+        search = nil if search&.empty?
+        has_errors_filter = params["has_errors"] == "true"
+
+        sessions = fetch_sessions(
+          has_errors_filter: has_errors_filter,
+          per_page: per_page,
+          offset: offset,
+          since: since,
+          until_time: until_time,
+          sort_by: sort_by,
+          search: search
+        )
+
+        sessions, has_next = take_page(sessions, per_page)
+
+        audit!(env, action: :list_sessions)
+
+        render_page(env, Views::SessionsIndexView.new(
+          sessions: sessions,
+          page: page,
+          per_page: per_page,
+          has_next: has_next,
+          search: search || "",
+          sort_by: sort_by || "updated_at",
+          since: params["since"] || "",
+          until_param: params["until"] || "",
+          has_errors: has_errors_filter
+        ))
+      end
+
+      def fetch_sessions(has_errors_filter:, per_page:, offset:, since:, until_time:, sort_by:, search:)
+        unless has_errors_filter
+          return Sentiero.store.list_sessions(
+            limit: per_page + 1,
+            offset: offset,
+            since: since,
+            until_time: until_time,
+            sort_by: sort_by,
+            search: search
+          )
+        end
+
+        # The store has no has_errors index, so filter compute-on-read: scan up to
+        # analytics_max_scan_sessions matching sessions, then slice the requested
+        # page. Very large session counts make this a full scan.
+        scan_cap = Sentiero.store.limits.analytics_max_scan_sessions
+        all_matching = Sentiero.store.list_sessions(
+          limit: scan_cap,
+          offset: 0,
+          since: since,
+          until_time: until_time,
+          sort_by: sort_by,
+          search: search
+        ).select { |s| s[:metadata] && s[:metadata]["has_errors"] }
+
+        all_matching.slice(offset, per_page + 1) || []
+      end
+
+      def handle_session_redirect(env, session_id)
+        session = Sentiero.store.get_session(session_id)
+        return [404, {"content-type" => "text/plain"}, ["Session not found"]] unless session
+
+        windows = session[:windows] || []
+        return [404, {"content-type" => "text/plain"}, ["No windows found"]] if windows.empty?
+
+        best = windows.max_by { |w| w[:last_event_at] || 0 }
+        redirect("#{base_path(env)}/sessions/#{session_id}/windows/#{best[:window_id]}")
+      end
+
+      def handle_show(env, session_id, window_id)
+        session = Sentiero.store.get_session(session_id)
+        return [404, {"content-type" => "text/plain"}, ["Session not found"]] unless session
+
+        audit!(env, action: :view_session, session_id: session_id, window_id: window_id)
+
+        occ = Sentiero.store.occurrences_for_session(session_id, limit: 100)
+        evs = Sentiero.store.server_events_for_session(session_id, limit: 100)
+        server_activity = (
+          occ.map { |o| {kind: "exception", timestamp: o["timestamp"].to_f, occurrence: o} } +
+          evs.map { |e| {kind: "event", timestamp: e["timestamp"].to_f, event: e} }
+        ).sort_by { |item| -item[:timestamp] }
+
+        render_page(env, Views::SessionShowView.new(
+          session: session,
+          session_id: session_id,
+          window_id: window_id,
+          shareable_replays: Sentiero.configuration.shareable_replays,
+          server_activity: server_activity
+        ))
+      end
+
+      def handle_events_api(env, session_id, window_id)
+        params = query_params(env)
+        after = params["after"]
+        limit = Sentiero.configuration.max_events_per_page
+
+        events = Sentiero.store.get_events(Sentiero::WindowRef.new(session_id, window_id), after: after, limit: limit)
+
+        audit!(env, action: :view_session, session_id: session_id, window_id: window_id)
+
+        [200, json_headers, [JSON.generate(events)]]
+      end
+
+      def handle_delete(env, session_id)
+        verify_csrf(env) || begin
+          audit!(env, action: :delete_session, session_id: session_id)
+          Sentiero.store.delete_session(session_id)
+          redirect("#{base_path(env)}/")
+        end
+      end
+
+      def handle_delete_window(env, session_id, window_id)
+        verify_csrf(env) || begin
+          audit!(env, action: :delete_session, session_id: session_id, window_id: window_id)
+          Sentiero.store.delete_window(Sentiero::WindowRef.new(session_id, window_id))
+
+          # Deleting the last window removes the session
+          session = Sentiero.store.get_session(session_id)
+          if session && session[:windows] && !session[:windows].empty?
+            best = session[:windows].max_by { |w| w[:last_event_at] || 0 }
+            redirect("#{base_path(env)}/sessions/#{session_id}/windows/#{best[:window_id]}")
+          else
+            redirect("#{base_path(env)}/")
+          end
+        end
+      end
+
+      def handle_bulk_delete(env)
+        verify_csrf(env) || begin
+          Array(Rack::Request.new(env).POST["session_ids"]).each do |sid|
+            next unless valid_id?(sid)
+
+            audit!(env, action: :delete_session, session_id: sid)
+            Sentiero.store.delete_session(sid)
+          end
+          redirect("#{base_path(env)}/")
+        end
+      end
+    end
+  end
+end

data/lib/sentiero/web/errors_app.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require_relative "ingest_app"
+require_relative "../fingerprint"
+require_relative "../redaction"
+require_relative "../ip_anonymizer"
+
+module Sentiero
+  module Web
+    # Server-lane ingest for exceptions. Computes the grouping fingerprint
+    # server-side, then persists via Sentiero.store.save_occurrence.
+    class ErrorsApp < IngestApp
+      MAX_BACKTRACE_FRAMES = 100
+      MAX_MESSAGE_LENGTH = 4000
+      MAX_CONTEXT_BYTES = 16_384
+
+      private
+
+      def handle(env, project, data)
+        exception_class = data["exception_class"]
+        message = data["message"]
+
+        unless exception_class.is_a?(String) && !exception_class.empty?
+          return json_response(400, {error: "exception_class is required"})
+        end
+        unless message.is_a?(String) && !message.empty?
+          return json_response(400, {error: "message is required"})
+        end
+
+        session_id = data["session_id"]
+        window_id = data["window_id"]
+        if session_id && !valid_optional_id?(session_id)
+          return json_response(400, {error: "invalid session_id"})
+        end
+        if window_id && !valid_optional_id?(window_id)
+          return json_response(400, {error: "invalid window_id"})
+        end
+
+        backtrace = data["backtrace"]
+        backtrace = backtrace.is_a?(Array) ? backtrace.first(MAX_BACKTRACE_FRAMES).map(&:to_s) : nil
+
+        # Redact before fingerprinting so grouping is stable whether or not the
+        # client already redacted.
+        redaction = Sentiero.configuration.redaction
+        message = Redaction.redact_text(message, redaction)
+        backtrace &&= backtrace.map { |frame| Redaction.redact_text(frame, redaction) }
+
+        timestamp = numeric_timestamp(data["timestamp"])
+
+        fingerprint = Fingerprint.compute(
+          exception_class: exception_class,
+          backtrace: backtrace,
+          project: project
+        )
+
+        occurrence = {
+          "fingerprint" => fingerprint,
+          "project" => project,
+          "exception_class" => exception_class,
+          "message" => message[0, MAX_MESSAGE_LENGTH],
+          "timestamp" => timestamp
+        }
+        occurrence["backtrace"] = backtrace if backtrace
+        if data["context"].is_a?(Hash)
+          context = Redaction.deep_redact_strings(capped_context(data["context"]), redaction)
+          occurrence["context"] = anonymize_request_ip(context)
+        end
+        occurrence["session_id"] = session_id if session_id
+        occurrence["window_id"] = window_id if window_id
+
+        begin
+          Sentiero.store.save_occurrence(occurrence)
+        rescue ArgumentError => e
+          return json_response(400, {error: e.message})
+        end
+
+        json_response(200, {status: "ok", fingerprint: fingerprint})
+      end
+
+      def capped_context(context)
+        (JSON.generate(context).bytesize <= MAX_CONTEXT_BYTES) ? context : {"_truncated" => true}
+      end
+
+      # Backstop for reporters that don't (or can't) honor anonymize_ip
+      # themselves: mirrors Reporter::Middleware#client_ip's truncation so a
+      # server configured with anonymize_ip: true never persists a raw IP.
+      def anonymize_request_ip(context)
+        return context unless Sentiero.configuration.anonymize_ip
+
+        request = context["request"]
+        return context unless request.is_a?(Hash) && request["ip"].is_a?(String)
+
+        context.merge("request" => request.merge("ip" => IpAnonymizer.anonymize(request["ip"])))
+      end
+    end
+  end
+end

data/lib/sentiero/web/escaping.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "cgi/escape"
+require "json"
+
+module Sentiero
+  module Web
+    # HTML and JavaScript escaping for safe template rendering using only stdlib.
+    module Escaping
+      # Chars safe in JSON but unsafe in HTML <script>: prevents </script>
+      # breakout and HTML entity interpretation (mirrors ERB::Util.json_escape).
+      HTML_UNSAFE_IN_SCRIPT = {
+        "<" => '\u003c',
+        ">" => '\u003e',
+        "&" => '\u0026',
+        "\u2028" => '\u2028',
+        "\u2029" => '\u2029'
+      }.freeze
+
+      HTML_UNSAFE_IN_SCRIPT_PATTERN = Regexp.union(HTML_UNSAFE_IN_SCRIPT.keys).freeze
+
+      def escape_html(text)
+        CGI.escapeHTML(text.to_s)
+      end
+
+      # Escapes for embedding in a JS string literal; returns content WITHOUT surrounding quotes.
+      def escape_js_string(text)
+        json = JSON.generate(text.to_s)
+        json[1..-2].gsub(HTML_UNSAFE_IN_SCRIPT_PATTERN, HTML_UNSAFE_IN_SCRIPT)
+      end
+
+      def escape_json(json_string)
+        json_string.gsub(HTML_UNSAFE_IN_SCRIPT_PATTERN, HTML_UNSAFE_IN_SCRIPT)
+      end
+    end
+  end
+end

data/lib/sentiero/web/events_app.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+require "json"
+require "rack/utils"
+require_relative "body_reader"
+require_relative "../analytics/events"
+require_relative "../redaction"
+require_relative "../store"
+
+module Sentiero
+  module Web
+    class EventsApp
+      def call(env)
+        method = env["REQUEST_METHOD"]
+
+        case method
+        when "POST"
+          handle_post(env)
+        when "OPTIONS"
+          handle_options(env)
+        else
+          with_cors(env, [405, {"content-type" => "application/json"}, ['{"error":"method not allowed"}']])
+        end
+      end
+
+      private
+
+      def handle_post(env)
+        # Drop the batch (silently, 204, same as the opt-out path so clients
+        # treat it as success and don't retry) when the user opted out via
+        # cookie, or sent Sec-GPC and the server is configured to honor it.
+        # This backstops the client, which is expected to not even start
+        # recording for GPC users, but a stale bundle or non-Sentiero caller
+        # could still POST here.
+        return dropped(env) if opted_out?(env) || gpc_signaled?(env)
+
+        raw_body, error = BodyReader.read(env)
+        if error
+          status, message = BodyReader::ERRORS[error]
+          return cors_error(env, status, message)
+        end
+
+        begin
+          data = JSON.parse(raw_body)
+        rescue JSON::ParserError
+          return cors_error(env, 400, "invalid JSON body")
+        end
+
+        session_id = data["sessionId"]
+        window_id = data["windowId"]
+        events = data["events"]
+
+        unless session_id.is_a?(String) && session_id.match?(Store::VALID_ID)
+          return cors_error(env, 400, "sessionId must be 1-128 alphanumeric, hyphen, or underscore characters")
+        end
+
+        unless window_id.is_a?(String) && window_id.match?(Store::VALID_ID)
+          return cors_error(env, 400, "windowId must be 1-128 alphanumeric, hyphen, or underscore characters")
+        end
+
+        unless events.is_a?(Array) && !events.empty? && events.all? { |e| e.is_a?(Hash) }
+          return cors_error(env, 400, "events must be a non-empty array of objects")
+        end
+
+        max_per_request = Sentiero.configuration.max_events_per_request
+        if max_per_request && events.size > max_per_request
+          return cors_error(env, 400, "too many events (max #{max_per_request})")
+        end
+
+        events, error = normalize_timestamps(env, events)
+        return error if error
+
+        events = redact_events(events)
+
+        Sentiero.store.save_events(Sentiero::WindowRef.new(session_id, window_id), events)
+
+        # Save optional session metadata if present, plus a monotonic has_errors
+        # flag computed from the incoming batch when error capture is enabled.
+        metadata = data["metadata"]
+        metadata = {} unless metadata.is_a?(Hash)
+
+        if Sentiero.configuration.capture_errors && batch_has_errors?(events)
+          metadata = metadata.merge("has_errors" => true)
+        end
+
+        unless metadata.empty?
+          metadata = Sentiero::Redaction.redact_metadata(metadata, Sentiero.configuration.redaction)
+          Sentiero.store.save_metadata(session_id, metadata)
+        end
+
+        with_cors(env, [200, {"content-type" => "application/json"}, ['{"status":"ok"}']])
+      end
+
+      def normalize_timestamps(env, events)
+        events.each do |event|
+          next unless event.key?("timestamp")
+
+          raw = event["timestamp"]
+          begin
+            ts = raw.is_a?(Numeric) ? raw.to_f : Float(raw)
+          rescue ArgumentError, TypeError
+            return [nil, cors_error(env, 400, "invalid timestamp value")]
+          end
+          return [nil, cors_error(env, 400, "invalid timestamp value")] unless ts.finite?
+
+          event["timestamp"] = ts
+        end
+
+        [events, nil]
+      end
+
+      # Field-aware redaction (defense-in-depth; the client already redacts) plus
+      # the optional Ruby-only server_proc. A raising or nil/false server_proc
+      # drops the event (we never store unsanitized data).
+      def redact_events(events)
+        config = Sentiero.configuration.redaction
+        proc = config.server_proc
+
+        events.filter_map do |event|
+          redacted = Sentiero::Redaction.redact_event(event, config)
+          next redacted unless proc.respond_to?(:call)
+
+          begin
+            proc.call(redacted)
+          rescue => e
+            warn "[Sentiero] redaction server_proc raised #{e.class}: #{e.message}; dropping event"
+            nil
+          end
+        end
+      end
+
+      def opted_out?(env)
+        config = Sentiero.configuration
+        return false unless config.user_opt_out
+
+        cookies = Rack::Utils.parse_cookies(env)
+        value = cookies[config.opt_out_cookie_name]
+        !value.nil? && !value.empty? && value != "0" && value != "false"
+      end
+
+      def gpc_signaled?(env)
+        Sentiero.configuration.respect_gpc && env["HTTP_SEC_GPC"] == "1"
+      end
+
+      def dropped(env)
+        with_cors(env, [204, {"content-type" => "application/json"}, []])
+      end
+
+      # rrweb custom events arrive as { type: 5, data: { tag, payload } }; the
+      # recorder tags error events "error", so a batch "has errors" when any
+      # custom event carries that tag.
+      def batch_has_errors?(events)
+        events.any? do |event|
+          event["type"] == Sentiero::Analytics::Events::CUSTOM &&
+            event["data"].is_a?(Hash) && event["data"]["tag"] == "error"
+        end
+      end
+
+      def handle_options(env)
+        headers = {
+          "access-control-allow-methods" => "POST",
+          "access-control-allow-headers" => "Content-Type, Content-Encoding",
+          "access-control-max-age" => "86400",
+          "content-type" => "text/plain"
+        }
+
+        with_cors(env, [204, headers, []])
+      end
+
+      def with_cors(env, response)
+        status, headers, body = response
+        headers["x-content-type-options"] = "nosniff"
+        origins = Sentiero.configuration.cors_origins
+
+        if origins && !origins.empty?
+          request_origin = env["HTTP_ORIGIN"]
+
+          if request_origin && origins.include?(request_origin)
+            headers["access-control-allow-origin"] = request_origin
+            headers["vary"] = "Origin"
+          end
+        end
+
+        [status, headers, body]
+      end
+
+      def cors_error(env, status, message)
+        with_cors(env, [status, {"content-type" => "application/json"}, [json_error(message)]])
+      end
+
+      def json_error(message)
+        JSON.generate({error: message})
+      end
+    end
+  end
+end

data/lib/sentiero/web/formatting.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "../user_agent"
+
+module Sentiero
+  module Web
+    # Small presentation formatters shared by the Rack apps and the view layer.
+    module Formatting
+      def parse_device(user_agent)
+        Sentiero::UserAgent.device(user_agent)
+      end
+
+      def parse_browser(user_agent)
+        Sentiero::UserAgent.browser(user_agent)
+      end
+
+      # CLS is a unitless ratio (3 decimals); the other Web Vitals are millisecond durations.
+      def format_vital(metric, value)
+        (metric == "CLS") ? format("%.3f", value) : "#{value.round} ms"
+      end
+
+      def format_duration(first_event_at, last_event_at)
+        return "N/A" unless first_event_at && last_event_at
+
+        # Event timestamps are in milliseconds
+        total_ms = (last_event_at - first_event_at).abs
+        total_seconds = (total_ms / 1000.0).round
+
+        if total_seconds < 60
+          "#{total_seconds}s"
+        elsif total_seconds < 3600
+          minutes = total_seconds / 60
+          seconds = total_seconds % 60
+          (seconds > 0) ? "#{minutes}m #{seconds}s" : "#{minutes}m"
+        else
+          hours = total_seconds / 3600
+          minutes = (total_seconds % 3600) / 60
+          (minutes > 0) ? "#{hours}h #{minutes}m" : "#{hours}h"
+        end
+      end
+    end
+  end
+end