fractal-ruby 0.1.0

data/lib/fractal/event_builder.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Fractal
+  # Turns an exception plus Rails' error context into one /v1/errors event. Allowlist, not
+  # blocklist: the event is assembled from named safe fields, and never from params, headers,
+  # cookies, session, ENV or job arguments. The Scrubber is a second layer over what is left.
+  #
+  # Reads only what is already in memory (the controller and job instances in the execution
+  # context, and the scope). It must never touch the database: the database is frequently the
+  # very thing that is down when an error needs reporting.
+  class EventBuilder
+    Built = Data.define(:player_id, :fingerprint, :event)
+
+    def initialize(config:, scrubber:, identity: Identity.new(config))
+      @config = config
+      @scrubber = scrubber
+      @identity = identity
+    end
+
+    def build(exception, handled:, severity:, source:, context:, scope: Scope.current)
+      error_type = exception.class.name || "AnonymousError"
+      event(error_type, @scrubber.message(exception), @scrubber.backtrace(exception),
+            handled: handled, severity: severity, source: source, context: context, scope: scope)
+    end
+
+    # capture_message: no exception, so the stack is where the message was captured from.
+    def build_message(message, severity:, frames:, context:, scope: Scope.current)
+      text = @scrubber.text(message)
+      text = "(empty message)" if text.empty?
+      event("Message", text, @scrubber.frames(frames),
+            handled: true, severity: severity, source: "fractal.capture_message", context: context, scope: scope)
+    end
+
+    private
+
+    def event(error_type, message, stack_trace, handled:, severity:, source:, context:, scope:)
+      controller = context[:controller]
+      job = context[:job]
+      player_id = utf8(@identity.player_id(scope: scope, controller: controller))
+
+      event = {
+        "error_type" => error_type,
+        "message" => message,
+        "stack_trace" => stack_trace,
+        "severity" => severity.to_s,
+        "handled" => handled,
+        "tags" => @scrubber.scrub(tags(source, controller, job).merge(scope.tags)),
+        "extra" => @scrubber.scrub(extra(controller, job)),
+        "breadcrumbs" => @scrubber.scrub(scope.breadcrumbs),
+        "user" => { "id" => player_id },
+        "runtime" => { "name" => "ruby", "version" => RUBY_VERSION },
+        "release" => @config.app_version.to_s,
+        "environment" => @config.environment
+      }
+      event.delete("breadcrumbs") if scope.breadcrumbs.empty?
+      Built.new(
+        player_id: player_id,
+        fingerprint: Fingerprint.generate_fingerprint(error_type, message, stack_trace),
+        event: event
+      )
+    end
+
+    # The id is the one string here the Scrubber does not pass over. Invalid bytes are replaced,
+    # not refused: the error is worth more than the exact id.
+    def utf8(id)
+      text = id.to_s
+      text = text.dup.force_encoding(Encoding::UTF_8) if text.encoding == Encoding::BINARY
+      text.scrub("?")
+    end
+
+    # environment rides in tags until the collector stores it (#485).
+    def tags(source, controller, job)
+      tags = { "environment" => @config.environment, "source" => source.to_s }
+      tags["controller_action"] = "#{controller.controller_path}##{controller.action_name}" if controller.respond_to?(:controller_path)
+      tags["job"] = job.class.name if job
+      tags
+    end
+
+    # Fixed scalar keys only.
+    def extra(controller, job)
+      extra = {}
+      if controller.respond_to?(:request) && (request = controller.request)
+        extra["request_id"] = request.request_id if request.respond_to?(:request_id)
+        extra["method"] = request.request_method if request.respond_to?(:request_method)
+        extra["route"] = request.route_uri_pattern if request.respond_to?(:route_uri_pattern)
+      end
+      if job
+        extra["job_id"] = job.job_id if job.respond_to?(:job_id)
+        extra["queue"] = job.queue_name if job.respond_to?(:queue_name)
+        extra["executions"] = job.executions if job.respond_to?(:executions)
+      end
+      extra.compact
+    end
+  end
+end

data/lib/fractal/fingerprint.rb

@@ -0,0 +1,287 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Fractal
+  # The collector's error-fingerprint grouping (collector/internal/ingest/fingerprint.go,
+  # frame_extract.go), ported so the reporter can coalesce repeats of one error into one event
+  # with an occurrence_count before sending. The key only has to agree with the collector's for
+  # coalescing to match its grouping, so it is pinned to Go's own output by the shared vectors in
+  # collector/internal/ingest/fingerprint_vectors.json (spec/fractal/fingerprint_spec.rb).
+  #
+  # Fractal's app keeps its own copy (app/services/concerns/error_fingerprint.rb) for the
+  # backfill services, which also need the pre-normalization v1 hash.
+  module Fingerprint
+    # Multi-run constructs: each requires literal delimiter characters (@, <,
+    # #, >, -, T, :, Z) that plain alphanumeric identifiers can't contain, so
+    # matching them directly (no lookaround needed) can't false-positive on a
+    # bare identifier like "Node2D".
+    GODOT_RESOURCE_PATTERN = /<[A-Za-z_][A-Za-z0-9_]*#-?\d+>/
+    GODOT_NODE_PATTERN     = /@[A-Za-z_][A-Za-z0-9_]*@\d+/
+    ISO_DATE_PATTERN       = /\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:?\d{2})?/
+    UUID_PATTERN           = /[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}/
+
+    # Single-run token classes: classified against the *whole* token, so a
+    # mixed token like "Node2D" never partially matches.
+    WORD_RUN_PATTERN   = /[A-Za-z0-9_]+/
+    HEX_PREFIX_PATTERN = /\A0[xX][0-9a-fA-F]+\z/
+    BARE_HEX_PATTERN   = /\A[0-9a-fA-F]+\z/
+    HEX_LETTER_PATTERN = /[a-fA-F]/
+    INT_PATTERN        = /\A[0-9]+\z/
+
+    # Mirrors Sentry's MAX_INPUT_LENGTH: above this, skip parameterization
+    # entirely rather than pay for regex passes over an arbitrarily large
+    # message.
+    MAX_NORMALIZE_INPUT_LEN = 8192
+
+    # \z, not $ — Ruby's $ (unlike Go's) matches before a trailing "\n" at the
+    # end of the string, which would silently mis-strip a frame line whose
+    # source had a trailing newline. See fingerprint_vectors.json's
+    # "js_frame_with_trailing_newline" vector.
+    LINE_COL_PATTERN         = /:\d+(?::\d+)?(\)?)\z/
+    GOROUTINE_HEADER_PATTERN = /\Agoroutine \d+ \[[^\]]+\]:\z/
+    GO_FILE_LINE_PATTERN     = /\A(.+\.go):\d+(\s+\+0x[0-9a-fA-F]+)?\z/
+    LUA_MID_LINE_COL_PATTERN = /:\d+:/
+
+    # Ruby frames read "path.rb:NN:in 'Class#method'" (backtick-quoted before Ruby 3.4). The optional
+    # [gem]/[ruby]/[other] prefix is how Fractal::Scrubber rewrites non-app paths, so an in-app
+    # frame is always a bare app/ or lib/ path.
+    #
+    # ERB frames read "app/views/x.html.erb:12:in '_app_views_x_html_erb___123'": the label is a
+    # compiled-method id that changes per process, so the whole ":NN:in ..." tail is dropped.
+    RUBY_FRAME_PATTERN    = /\A(?:\[(?:gem|ruby|other)\] )?\S+\.(?:rb|erb):\d+:in /
+    RUBY_LINE_PATTERN     = /\A((?:\[(?:gem|ruby|other)\] )?\S+\.rb):\d+(:in )/
+    RUBY_ERB_LINE_PATTERN = /\A((?:\[(?:gem|ruby|other)\] )?\S+\.erb):\d+:in .*\z/
+
+    module_function
+
+    # generate_fingerprint is the SHA256 fingerprint used to group errors,
+    # normalizing both the message and the in-app stack frame first.
+    def generate_fingerprint(error_type, message, stack_trace)
+      raw = "#{error_type}\x00#{normalize_message(message)}\x00#{normalize_top_frame(stack_trace)}"
+      Digest::SHA256.hexdigest(raw)
+    end
+
+    def normalize_message(message)
+      return message if message.bytesize > MAX_NORMALIZE_INPUT_LEN
+
+      s = message.gsub(GODOT_RESOURCE_PATTERN, "<resource>")
+      s = s.gsub(GODOT_NODE_PATTERN, "<node>")
+      s = s.gsub(ISO_DATE_PATTERN, "<date>")
+      s = s.gsub(UUID_PATTERN, "<uuid>")
+
+      tokenize_and_normalize(s)
+    end
+
+    # Walks s once, classifying each whole run of [A-Za-z0-9_] characters.
+    # Separator runs (including the "." that joins two digit runs into a
+    # float) pass through untouched.
+    def tokenize_and_normalize(s)
+      matches = []
+      s.scan(WORD_RUN_PATTERN) { matches << Regexp.last_match }
+      return s if matches.empty?
+
+      out = +""
+      pos = 0
+      i = 0
+      while i < matches.length
+        m = matches[i]
+        start_idx = m.begin(0)
+        end_idx = m.end(0)
+        out << s[pos...start_idx]
+        token = m[0]
+
+        if i + 1 < matches.length && INT_PATTERN.match?(token)
+          next_m = matches[i + 1]
+          if s[end_idx...next_m.begin(0)] == "." && INT_PATTERN.match?(next_m[0])
+            out << "<float>"
+            pos = next_m.end(0)
+            i += 2
+            next
+          end
+        end
+
+        out << if HEX_PREFIX_PATTERN.match?(token)
+          "<hex>"
+        elsif token.length >= 8 && BARE_HEX_PATTERN.match?(token) && HEX_LETTER_PATTERN.match?(token)
+          # Bare hex must contain a letter — a pure digit run of any length is
+          # <int>, not <hex>.
+          "<hex>"
+        elsif INT_PATTERN.match?(token)
+          "<int>"
+        else
+          token
+        end
+        pos = end_idx
+        i += 1
+      end
+      out << s[pos..]
+      out
+    end
+
+    # Extracts and normalizes the in-app frame of a stack trace. Tries each
+    # engine-specific extractor in turn; an unrecognized or future format
+    # falls through to normalize_top_frame_legacy unchanged. See
+    # sdks/shared/CRASH_PROTOCOL.md for the frame-format contract.
+    def normalize_top_frame(stack_trace)
+      return "" if stack_trace.nil? || stack_trace.empty?
+
+      # ruby_frame precedes js_frame: js_stack_trace? fires on any " at ", which a Ruby 3.3+ eval frame
+      # ("(eval at app/x.rb:3):1:in 'm'") contains. Keep in sync with frameExtractors in Go.
+      %i[godot_frame ruby_frame js_frame go_frame lua_frame].each do |extractor|
+        frame, matched = send(extractor, stack_trace)
+        return frame if matched
+      end
+      normalize_top_frame_legacy(stack_trace)
+    end
+
+    # Byte-for-byte the pre-extractor-chain behavior: prefer a JS-style "at"
+    # line, else fall back to the first non-empty line.
+    def normalize_top_frame_legacy(stack_trace)
+      return "" if stack_trace.nil? || stack_trace.empty?
+
+      lines = stack_trace.strip.split("\n")
+      lines.each do |line|
+        line = line.strip
+        next if line.empty?
+        return strip_line_col(line) if line.start_with?("at ") || line.include?(" at ")
+      end
+      lines.each do |line|
+        line = line.strip
+        return strip_line_col(line) unless line.empty?
+      end
+      ""
+    end
+
+    def godot_stack_trace?(stack_trace)
+      stack_trace.include?("GDScript backtrace") || stack_trace.include?("res://")
+    end
+
+    # Prefers the first res:// (game script) line over any engine C++ frame
+    # that precedes it, skipping res://test/ so the SDK's own test-suite
+    # frames don't win.
+    def godot_frame(stack_trace)
+      return [ "", false ] unless godot_stack_trace?(stack_trace)
+
+      stack_trace.split("\n").each do |line|
+        trimmed = line.strip
+        next if trimmed.empty?
+        if trimmed.include?("res://") && !trimmed.include?("res://test/")
+          return [ strip_line_col(trimmed), true ]
+        end
+      end
+      [ "", false ]
+    end
+
+    def js_stack_trace?(stack_trace)
+      stack_trace.split("\n").any? do |line|
+        t = line.strip
+        t.start_with?("at ") || t.include?(" at ")
+      end
+    end
+
+    # Prefers the first "at fn (file:line:col)" frame that isn't <anonymous>
+    # or under node_modules.
+    def js_frame(stack_trace)
+      return [ "", false ] unless js_stack_trace?(stack_trace)
+
+      stack_trace.split("\n").each do |line|
+        t = line.strip
+        next if t.empty?
+        next unless t.start_with?("at ") || t.include?(" at ")
+        next if t.include?("<anonymous>") || t.include?("node_modules")
+        return [ strip_line_col(t), true ]
+      end
+      [ "", false ]
+    end
+
+    def go_stack_trace?(stack_trace)
+      stack_trace.split("\n").any? { |line| GOROUTINE_HEADER_PATTERN.match?(line.strip) }
+    end
+
+    # Walks the alternating function-name / file:line(+offset) pairs a Go
+    # panic trace prints, preferring the first file:line frame whose function
+    # line isn't in the "runtime." package.
+    def go_frame(stack_trace)
+      return [ "", false ] unless go_stack_trace?(stack_trace)
+
+      last_func = ""
+      stack_trace.split("\n").each do |raw|
+        trimmed = raw.strip
+        next if trimmed.empty?
+        next if GOROUTINE_HEADER_PATTERN.match?(trimmed)
+
+        unless raw.start_with?("\t") || raw.start_with?(" ")
+          last_func = trimmed
+          next
+        end
+        next unless GO_FILE_LINE_PATTERN.match?(trimmed)
+        next if last_func.start_with?("runtime.")
+
+        m = GO_FILE_LINE_PATTERN.match(trimmed)
+        return [ m[1], true ]
+      end
+      [ "", false ]
+    end
+
+    def lua_stack_trace?(stack_trace)
+      stack_trace.include?("stack traceback:")
+    end
+
+    # Prefers the first traceback line that isn't a "[C]:" native frame, and
+    # strips the line number out of its *middle* — Lua frames read
+    # "path.lua:NN: in function 'x'", so the trailing-anchored LINE_COL_PATTERN
+    # can't touch it.
+    def lua_frame(stack_trace)
+      return [ "", false ] unless lua_stack_trace?(stack_trace)
+
+      in_traceback = false
+      stack_trace.split("\n").each do |line|
+        trimmed = line.strip
+        next if trimmed.empty?
+        if trimmed.start_with?("stack traceback:")
+          in_traceback = true
+          next
+        end
+        next unless in_traceback
+        next if trimmed.start_with?("[C]:")
+
+        m = LUA_MID_LINE_COL_PATTERN.match(trimmed)
+        return [ trimmed, true ] if m.nil?
+
+        return [ trimmed[0...m.begin(0)] + ":" + trimmed[m.end(0)..], true ]
+      end
+      [ "", false ]
+    end
+
+    def ruby_stack_trace?(stack_trace)
+      stack_trace.split("\n").any? { |line| RUBY_FRAME_PATTERN.match?(line.strip) }
+    end
+
+    # Prefers the first frame under app/ or lib/ over a [gem]/[ruby]/[other] frame and strips the
+    # line number out of its middle. A trace with no in-app frame still matches: the first frame is
+    # returned with its line stripped.
+    def ruby_frame(stack_trace)
+      return [ "", false ] unless ruby_stack_trace?(stack_trace)
+
+      first = nil
+      stack_trace.split("\n").each do |line|
+        trimmed = line.strip
+        next unless RUBY_FRAME_PATTERN.match?(trimmed)
+
+        frame = if RUBY_ERB_LINE_PATTERN.match?(trimmed)
+          trimmed.sub(RUBY_ERB_LINE_PATTERN) { $1 }
+        else
+          trimmed.sub(RUBY_LINE_PATTERN) { "#{$1}#{$2}" }
+        end
+        first ||= frame
+        return [ frame, true ] if frame.start_with?("app/") || frame.start_with?("lib/")
+      end
+      [ first, true ]
+    end
+
+    def strip_line_col(line)
+      line.sub(LINE_COL_PATTERN) { $1 }
+    end
+  end
+end

data/lib/fractal/identity.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Fractal
+  # Decides which player an error or event belongs to. In order: the user the app (or the Warden
+  # hook) put on the scope, then the configured user_resolver for the request's controller, then
+  # a fixed bucket: anonymous_player_id inside a request, system_player_id outside any (jobs,
+  # rake tasks, boot).
+  class Identity
+    def initialize(config)
+      @config = config
+    end
+
+    def player_id(scope:, controller: nil)
+      user = scope.user.to_s
+      return user unless user.empty?
+
+      resolve(controller) || bucket(scope: scope, controller: controller)
+    end
+
+    # Who the work belongs to when no user is known: anonymous inside a request, system outside.
+    def bucket(scope:, controller: nil)
+      controller || scope.request? ? @config.anonymous_player_id : @config.system_player_id
+    end
+
+    private
+
+    # Must never break the request or job it runs in, and must never touch the database: the
+    # resolver reads what the controller already loaded. A resolver that raises is a bug in the
+    # app's configuration, so it is logged at error level, and the event goes to the anonymous
+    # bucket rather than being lost.
+    def resolve(controller)
+      return nil unless controller && @config.user_resolver
+
+      id = @config.user_resolver.call(controller)
+      id.nil? || id.to_s.empty? ? nil : id.to_s
+    rescue StandardError => e
+      @config.logger.error("[fractal] user_resolver raised #{e.class}; using the anonymous player")
+      nil
+    end
+  end
+
+  # Rails' execution context (controller, job) for the work in progress, or {} outside Rails.
+  module ExecutionContext
+    module_function
+
+    def current
+      return {} unless defined?(::ActiveSupport::ExecutionContext)
+
+      ::ActiveSupport::ExecutionContext.to_h
+    end
+  end
+end

data/lib/fractal/rails/error_subscriber.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Fractal
+  # Registered with Rails.error.subscribe. Reports everything it is given: Rails already leaves
+  # out the rescue-responded request errors (404s and the like), and an unfiltered job failure
+  # such as a RecordNotFound is a genuine bug. Needs Rails 7.1+, which passes `source:`.
+  class ErrorSubscriber
+    def report(error, handled:, severity:, context:, source:)
+      Fractal.errors.report(error, handled: handled, severity: severity, context: context, source: source)
+    rescue Exception => e # rubocop:disable Lint/RescueException
+      Fractal.client.config.logger&.error("[fractal] subscriber failed: #{e.class}")
+    end
+  end
+end

data/lib/fractal/rails/middleware.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Fractal
+  # Outermost Rack middleware. It starts the request's scope (so the session and the client
+  # address can be read lazily from the env) and reports what happens outside
+  # ActionDispatch::Executor: Rack::Cors, HostAuthorization, Sendfile, Static, Propshaft, plus
+  # anything that propagates out when show_exceptions is off. The Executor already reports
+  # everything from ShowExceptions inward via Rails.error, and Rails.error.report is idempotent
+  # per exception, so nothing is sent twice. It re-raises the original exception untouched.
+  class RackMiddleware
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      Fractal::Scope.start(env)
+      @app.call(env)
+    rescue Exception => error # rubocop:disable Lint/RescueException
+      capture(error, env)
+      raise
+    ensure
+      Fractal::Scope.clear
+    end
+
+    private
+
+    def capture(error, env)
+      return if rescue_response?(error, env)
+
+      ::Rails.error.report(error, handled: false, source: "fractal.middleware")
+    rescue Exception => e # rubocop:disable Lint/RescueException
+      Fractal.client.config.logger&.error("[fractal] middleware failed: #{e.class}")
+    end
+
+    # Rails skips these for requests (a 404 is not a bug). It has not made that call yet for an
+    # exception that never reached ShowExceptions, so apply it here.
+    def rescue_response?(error, env)
+      ActionDispatch::ExceptionWrapper.new(env["action_dispatch.backtrace_cleaner"], error).rescue_response?
+    end
+  end
+end

data/lib/fractal/rails/railtie.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "middleware"
+require_relative "error_subscriber"
+require_relative "warden_hooks"
+
+module Fractal
+  # Wires the gem into a Rails app (7.1 or later): the outermost middleware, the Rails.error
+  # subscriber, scope cleanup after every request and job, and Warden's sign-in hooks when
+  # Warden (Devise) is loaded. Configuration stays in the app's own initializer.
+  #
+  # Nothing in the gem is named Fractal::Rails: an app whose own module is Fractal (Fractal's app
+  # is) declares `class Application < Rails::Application` inside `module Fractal`, where such a
+  # constant would shadow ::Rails and break the boot.
+  class Railtie < ::Rails::Railtie
+    # After the app's own initializers: one of them may also insert at 0 (Rack::Cors usually
+    # does), and the gem's middleware has to end up outside everything.
+    initializer "fractal.middleware", after: :load_config_initializers do |app|
+      app.config.middleware.insert_before 0, Fractal::RackMiddleware
+    end
+
+    initializer "fractal.error_subscriber" do
+      ::Rails.error.subscribe(Fractal::ErrorSubscriber.new)
+    end
+
+    # The executor wraps every request and every job. Its error report runs before completion,
+    # so a job's set_user and tags are still on the scope when its failure is captured.
+    initializer "fractal.scope_cleanup" do |app|
+      app.executor.to_complete { Fractal::Scope.clear }
+    end
+
+    config.after_initialize do
+      Fractal::WardenHooks.install if defined?(::Warden::Manager)
+    end
+  end
+end

data/lib/fractal/rails/warden_hooks.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Fractal
+  # Warden (and so Devise) tells us who the user is as soon as the app asks, with the user
+  # already loaded: no extra query, nothing for the app to wire. Every set_user puts the user's
+  # player id on the scope; a sign-in also tracks `identify`, which links the pre-login session to
+  # the user (see Fractal.identify). A sign-in is a set_user that is not a :fetch and is stored in
+  # the session: a stateless strategy (token or HTTP auth) authenticates with store: false on
+  # every request, and is not a sign-in.
+  #
+  # The hooks run inside the app's authentication, so they must never raise into it.
+  module WardenHooks
+    module_function
+
+    def install
+      return if @installed
+
+      @installed = true
+      ::Warden::Manager.after_set_user { |user, _auth, opts| on_set_user(user, opts) }
+      ::Warden::Manager.before_logout { |_user, _auth, _opts| Fractal.set_user(nil) }
+    end
+
+    def on_set_user(user, opts)
+      return unless Fractal.configured? && user
+
+      config = Fractal.client.config
+      player_id = config.player_id_for_user.call(user).to_s
+      return if player_id.empty?
+
+      if opts && opts[:event] != :fetch && opts[:store] != false && config.identify_on_login
+        Fractal.identify(player_id)
+      else
+        Fractal.set_user(player_id)
+      end
+    rescue Exception => e # rubocop:disable Lint/RescueException
+      Fractal.client.config.logger&.error("[fractal] warden hook failed: #{e.class}")
+    end
+  end
+end

data/lib/fractal/scope.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Fractal
+  # What is known about the unit of work in progress (one request or one job): who the user is,
+  # tags, breadcrumbs, the session and the Rack env. Shared by errors and analytics events, and
+  # never global: it lives in fiber-local storage, set up at the start of a request by the
+  # middleware and cleared when the request or job completes.
+  #
+  # Code outside any request or job gets a scope too (created on first use), so Fractal.set_tag in
+  # a rake task still reaches that task's errors; nothing clears it but the next Scope.clear.
+  class Scope
+    KEY = :__fractal_scope
+    MAX_BREADCRUMBS = 50
+    MAX_TAGS = 50
+
+    attr_reader :env, :tags, :breadcrumbs
+    attr_accessor :user, :session_token, :client_ip
+
+    class << self
+      def current
+        Thread.current[KEY] ||= new
+      end
+
+      # Starts a fresh scope for a request. env is the Rack env, read lazily for the session and
+      # the client address.
+      def start(env = nil)
+        Thread.current[KEY] = new(env)
+      end
+
+      def clear
+        Thread.current[KEY] = nil
+      end
+
+      # Runs the block in a fresh scope and restores the previous one afterwards.
+      def isolated(env = nil)
+        previous = Thread.current[KEY]
+        Thread.current[KEY] = new(env)
+        yield
+      ensure
+        Thread.current[KEY] = previous
+      end
+    end
+
+    def initialize(env = nil)
+      @env = env
+      @tags = {}
+      @breadcrumbs = []
+      @user = nil
+      @session_token = nil
+      @client_ip = nil
+    end
+
+    def request? = !@env.nil?
+
+    def set_tag(key, value)
+      key = key.to_s
+      return if !@tags.key?(key) && @tags.size >= MAX_TAGS
+
+      @tags[key] = value
+    end
+
+    def add_breadcrumb(crumb)
+      @breadcrumbs << crumb
+      @breadcrumbs.shift while @breadcrumbs.size > MAX_BREADCRUMBS
+    end
+  end
+
+  # The default `session_resolver`: a hash of the Rack session id, so one browser session is one
+  # Fractal session. Warden and Devise give the session a new id at sign-in and sign-out, so the
+  # logged-out and logged-in halves of a visit are two sessions, joined by the `identify` event.
+  #
+  # Reads a session only when the request already has one. Loading an absent session would make a
+  # cookie store issue a Set-Cookie on the customer's response, for a visitor who had none.
+  module SessionResolver
+    module_function
+
+    def from_rack_session(env)
+      session = env && env["rack.session"]
+      return nil unless session
+      return nil unless loaded?(session) || exists?(session)
+
+      id = session.respond_to?(:id) ? session.id : nil
+      id = id.public_id if id.respond_to?(:public_id)
+      return nil if id.nil? || id.to_s.empty?
+
+      "web_#{Digest::SHA256.hexdigest(id.to_s)[0, 32]}"
+    end
+
+    def loaded?(session) = session.respond_to?(:loaded?) && session.loaded?
+
+    def exists?(session) = session.respond_to?(:exists?) && session.exists?
+  end
+end