fractal-ruby 0.1.0

data/lib/fractal/scrubber.rb

@@ -0,0 +1,253 @@
+# frozen_string_literal: true
+
+module Fractal
+  # Removes secrets and PII from everything the error reporter sends. Pure: no I/O, no global
+  # state beyond what the constructor reads, so it can be specced exhaustively. It is a second
+  # layer: EventBuilder builds payloads from an allowlist of fields and never passes params,
+  # headers, cookies, session, ENV or job arguments here in the first place.
+  #
+  # Anything that raises propagates. The reporter treats that as "drop the event", never "send it
+  # unscrubbed".
+  class Scrubber
+    FILTERED = "[FILTERED]"
+
+    # Keys Rails' own filter_parameters does not cover by default.
+    EXTRA_KEYS = %w[authorization cookie session csrf credit_card stripe].freeze
+
+    # Exception classes whose message quotes the input that failed to parse, e.g. a request body.
+    # Matched by name so a class that is not loaded in this process is simply never matched.
+    INPUT_ECHOING = %w[
+      JSON::ParserError Psych::SyntaxError CSV::MalformedCSVError URI::InvalidURIError
+      ActionDispatch::Http::Parameters::ParseError Rack::QueryParser::ParameterTypeError
+      Rack::QueryParser::InvalidParameterError
+    ].freeze
+
+    MAX_CAUSES = 10
+    MAX_MESSAGE_CHARS = 1_000
+    MAX_FRAMES = 100
+    MAX_DEPTH = 8
+    MIN_ENV_VALUE_LENGTH = 8
+
+    # Order matters: URL userinfo and credentials go before the email pattern, which would
+    # otherwise eat the tail of `user:pass@host.com`.
+    VALUE_PATTERNS = [
+      [ %r{(\b[a-z][a-z0-9+.\-]*://)[^\s/:@]+:[^\s/@]+@}i, "\\1#{FILTERED}@" ],
+      [ /\b(?:Bearer|Basic)\s+[A-Za-z0-9._~+\/=\-]{8,}/, FILTERED ],
+      [ /\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]*/, FILTERED ],
+      [ /\b(?:sk|rk|pk|whsec)_[A-Za-z0-9_]{8,}/, FILTERED ],
+      [ /[A-Za-z0-9._%+\-]+@[A-Za-z0-9\-]+(?:\.[A-Za-z0-9\-]+)*\.[A-Za-z]{2,}/, FILTERED ],
+      [ /\b\h{32,}\b/, FILTERED ]
+    ].freeze
+
+    GEM_FRAME = %r{\A.*/gems/([^/]+)/(.*)\z}
+    STDLIB_FRAME = %r{\A.*/lib/ruby/\d+\.\d+\.\d+/(.*)\z}
+    ABSOLUTE_DIRS = %r{\A/(?:[^/:]*/)*}
+    # Ruby 3.3+ eval frames: "(eval at /abs/x.rb:3):1:in 'm'". The wrapper carries the host path.
+    EVAL_FRAME = /\A\(eval at (.+):\d+\):(\d+:in .*)\z/m
+
+    # The gem's own source: lib/fractal.rb, lib/fractal-ruby.rb and lib/fractal/**.
+    OWN_PREFIX = "#{File.expand_path('..', __dir__)}/fractal".freeze
+
+    def initialize(filter_parameters:, root:, env: ENV, extra_keys: [], message_filters: [], own_prefix: OWN_PREFIX)
+      @key_filter = KeyFilter.build(Array(filter_parameters) + EXTRA_KEYS + Array(extra_keys).map(&:to_s))
+      @env_values = secret_env_regexp(env)
+      @root_prefix = "#{root.to_s.chomp('/')}/"
+      @own_prefix = own_prefix
+      @message_filters = Array(message_filters)
+    end
+
+    # Deep-scrubs hashes, arrays and strings. Keys are stringified. Anything that is not a plain
+    # scalar is reduced to its class name, never inspected.
+    def scrub(value)
+      walk(@key_filter.filter(value), 0)
+    end
+
+    def message(exception)
+      chain = cause_chain(exception)
+      raw = custom_message(exception) || builtin_message(exception, chain)
+      return "#{exception.class.name} (message withheld)" if chain.any? { |e| input_echoing?(e) }
+
+      text = scrub_string(raw.to_s)[0, MAX_MESSAGE_CHARS]
+      text.empty? ? exception.class.name.to_s : text
+    end
+
+    # For capture_message: the caller's own text, scrubbed and capped like an exception message.
+    def text(raw)
+      scrub_string(raw.to_s)[0, MAX_MESSAGE_CHARS]
+    end
+
+    # Frames only, with no message header: the collector's fingerprint falls back to the first
+    # line, which must be a frame, never the (variable) message. The gem's own frames are dropped:
+    # its middleware is on every trace and would otherwise be picked as the first frame for errors
+    # raised outside any app code.
+    def backtrace(exception)
+      frames(exception.backtrace || [])
+    end
+
+    def frames(lines)
+      kept = lines.reject { |frame| frame.start_with?(@own_prefix) }.first(MAX_FRAMES)
+      kept.map { |frame| scrub_string(rewrite_frame(frame)) }.join("\n")
+    end
+
+    private
+
+    def walk(value, depth)
+      return "[TRUNCATED]" if depth > MAX_DEPTH
+
+      case value
+      when Hash then value.to_h { |k, v| [ k.to_s, walk(v, depth + 1) ] }
+      when Array then value.map { |v| walk(v, depth + 1) }
+      when String then scrub_string(value)
+      when Symbol then scrub_string(value.to_s)
+      when Integer, Float, true, false, nil then value
+      when Time then value.iso8601
+      else
+        return value.iso8601 if value.respond_to?(:iso8601) && value.class.name.to_s.match?(/\ADate(Time)?\z/)
+
+        value.class.name || "Object"
+      end
+    end
+
+    def scrub_string(string)
+      text = string.encoding == Encoding::BINARY ? string.dup.force_encoding(Encoding::UTF_8) : string
+      text = text.scrub("?")
+      text = text.gsub(@env_values, FILTERED) if @env_values
+      VALUE_PATTERNS.reduce(text) { |acc, (pattern, replacement)| acc.gsub(pattern, replacement) }
+    end
+
+    # The exception and its causes, outermost first. Wrappers such as ActionView::Template::Error
+    # copy their cause's message, so the checks on what a message may carry look at the whole chain.
+    def cause_chain(exception)
+      chain = [ exception ]
+      chain << chain.last.cause while chain.last.cause && chain.size < MAX_CAUSES
+      chain
+    end
+
+    # The app's own rules (config.message_filters) go first: they know their database adapters.
+    def custom_message(exception)
+      raw = exception.message.to_s
+      @message_filters.each do |filter|
+        replacement = filter.call(exception, raw)
+        return replacement.to_s unless replacement.nil?
+      end
+      nil
+    end
+
+    # Invariant: a database error contributes no free text, only codes and names. The fingerprint
+    # hashes the message, so a quoted value would also split one bug into a group per value.
+    def builtin_message(exception, chain)
+      raw = exception.message.to_s
+      if (pg_error = chain.find { |e| postgres_error?(e) })
+        postgres_message(pg_error)
+      elsif chain.any? { |e| active_record_error?(e) }
+        raw.lines.first.to_s.chomp
+      else
+        raw
+      end
+    end
+
+    def postgres_error?(error) = defined?(::PG::Error) && error.is_a?(::PG::Error)
+
+    def active_record_error?(error) = defined?(::ActiveRecord::ActiveRecordError) && error.is_a?(::ActiveRecord::ActiveRecordError)
+
+    # Postgres: structured fields only, "<PG class> <SQLSTATE> <constraint>", read from the
+    # PG::Result and never parsed out of the message text. The result is nil for connection
+    # failures and may already be cleared; either way the class name alone is sent.
+    def postgres_message(error)
+      result = error.result
+      fields = result ? [ ::PG::Result::PG_DIAG_SQLSTATE, ::PG::Result::PG_DIAG_CONSTRAINT_NAME ].map { |f| result.error_field(f) } : []
+      [ error.class.name, *fields ].reject { |f| f.nil? || f.to_s.empty? }.join(" ")
+    rescue ::PG::Error
+      error.class.name.to_s
+    end
+
+    def input_echoing?(exception)
+      exception.class.ancestors.any? { |klass| INPUT_ECHOING.include?(klass.name) }
+    end
+
+    # Gem and stdlib frames first: a gem vendored under the app root must not read as an app frame.
+    # An eval frame is rewritten as its origin file, so it reads as an ordinary Ruby frame: no host
+    # path, and no " at " for the collector's JS detector to claim.
+    def rewrite_frame(frame)
+      if (match = EVAL_FRAME.match(frame))
+        rewrite_frame("#{match[1]}:#{match[2]}")
+      elsif (match = GEM_FRAME.match(frame))
+        "[gem] #{match[1]}/#{match[2]}"
+      elsif (match = STDLIB_FRAME.match(frame))
+        "[ruby] #{match[1]}"
+      elsif frame.start_with?(@root_prefix)
+        frame.delete_prefix(@root_prefix)
+      elsif frame.start_with?("/")
+        "[other] #{frame.sub(ABSOLUTE_DIRS, '')}"
+      else
+        frame
+      end
+    end
+
+    # Exact values of denylisted variables. The length floor stops a flag like SECRET_FLAG=1 from
+    # replacing every "1" in every message.
+    def secret_env_regexp(env)
+      values = env.filter_map do |name, value|
+        next unless value.to_s.length >= MIN_ENV_VALUE_LENGTH
+        next unless @key_filter.filtered_key?(name)
+
+        value.to_s
+      end
+      values.empty? ? nil : Regexp.union(values.sort_by { |v| -v.length })
+    end
+  end
+
+  # Masks values whose key matches the filter list. Uses ActiveSupport::ParameterFilter when it is
+  # loaded, so a Rails app's filter_parameters (strings, regexps, procs, dotted keys) mean exactly
+  # what they mean to Rails' own log filtering. Without ActiveSupport, strings and symbols match as
+  # case-insensitive substrings and regexps as given.
+  class KeyFilter
+    def self.build(list)
+      if parameter_filter_available?
+        new(::ActiveSupport::ParameterFilter.new(list, mask: Scrubber::FILTERED))
+      else
+        new(PlainFilter.new(list))
+      end
+    end
+
+    def self.parameter_filter_available?
+      return true if defined?(::ActiveSupport::ParameterFilter)
+
+      require "active_support/parameter_filter"
+      true
+    rescue LoadError
+      false
+    end
+
+    def initialize(filter)
+      @filter = filter
+    end
+
+    def filter(value) = @filter.filter(payload: value)[:payload]
+
+    def filtered_key?(name) = @filter.filter(name.to_s => "x")[name.to_s] == Scrubber::FILTERED
+
+    class PlainFilter
+      def initialize(list)
+        @patterns = list.filter_map do |item|
+          case item
+          when Regexp then item
+          when String, Symbol then Regexp.new(Regexp.escape(item.to_s), Regexp::IGNORECASE)
+          end
+        end
+      end
+
+      def filter(hash) = walk(hash)
+
+      private
+
+      def walk(value)
+        case value
+        when Hash then value.to_h { |k, v| [ k, @patterns.any? { |p| p.match?(k.to_s) } ? Scrubber::FILTERED : walk(v) ] }
+        when Array then value.map { |v| walk(v) }
+        else value
+        end
+      end
+    end
+  end
+end

data/lib/fractal/transport.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+
+module Fractal
+  # One POST to the collector. Raises on any network failure; the caller counts that against the
+  # circuit breaker.
+  class Transport
+    Response = Data.define(:code, :body)
+
+    TIMEOUT = 2
+
+    def post(endpoint, api_key, json)
+      uri = URI.parse(endpoint)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = http.read_timeout = http.write_timeout = self.class::TIMEOUT
+      request = Net::HTTP::Post.new(uri.request_uri, "Content-Type" => "application/json", "X-API-Key" => api_key)
+      request.body = json
+      response = http.request(request)
+      Response.new(code: response.code.to_i, body: response.body.to_s)
+    end
+  end
+end

data/lib/fractal/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Fractal
+  # Kept in step with sdks/ruby/VERSION by ci/check_version_sync.sh.
+  VERSION = "0.1.0"
+end

data/lib/fractal-ruby.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Bundler requires a gem by its name; the library itself is `require "fractal"`.
+require_relative "fractal"

data/lib/fractal.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+
+require_relative "fractal/version"
+require_relative "fractal/scope"
+require_relative "fractal/configuration"
+require_relative "fractal/identity"
+require_relative "fractal/fingerprint"
+require_relative "fractal/scrubber"
+require_relative "fractal/event_builder"
+require_relative "fractal/transport"
+require_relative "fractal/breaker"
+require_relative "fractal/error_reporter"
+require_relative "fractal/analytics"
+require_relative "fractal/client"
+
+# Error tracking and server-side analytics for Ruby backends, reporting to Fractal. The facade
+# matches the JavaScript, Godot and LÖVE SDKs: Fractal.configure, Fractal.errors.capture_error,
+# Fractal.analytics.track, Fractal.flush and Fractal.shutdown. A subsystem that is off is a set of
+# no-ops, never nil.
+#
+#   Fractal.configure do |c|
+#     c.api_key = ENV["FRACTAL_API_KEY"]
+#     c.app_version = ENV["GIT_SHA"]
+#   end
+#   Fractal.analytics.track("checkout_completed", { "total_cents" => 1299 })
+module Fractal
+  class << self
+    def configure
+      config = Configuration.new
+      yield config if block_given?
+      config.validate!
+      install(Client.new(config))
+    end
+
+    # Swaps the active client, shutting the old one down so its queued events are delivered.
+    def install(client)
+      previous = @client
+      @client = client
+      previous&.shutdown
+      client.register_at_exit
+      client
+    end
+
+    def client = @client || NULL_CLIENT
+
+    def configured? = !@client.nil?
+
+    def errors = client.errors
+
+    def analytics = client.analytics
+
+    def flush = client.flush
+
+    def shutdown = client.shutdown
+
+    # Request-scoped context, shared by errors and analytics events. Never global: each request
+    # and job has its own (see Fractal::Scope).
+
+    def set_user(player_id)
+      Scope.current.user = player_id.nil? || player_id.to_s.empty? ? nil : player_id.to_s
+    end
+
+    def set_tag(key, value)
+      Scope.current.set_tag(key, value)
+    end
+
+    def add_breadcrumb(message, category: "default", level: "info", data: nil)
+      crumb = { "timestamp" => Time.now.utc.iso8601(3), "category" => category.to_s, "message" => message.to_s, "level" => level.to_s }
+      crumb["data"] = data if data
+      Scope.current.add_breadcrumb(crumb)
+    end
+
+    # The session for the rest of this request, e.g. a game client's own session token passed
+    # through to the server, in place of the default (the hashed web session id).
+    def set_session(token)
+      Scope.current.session_token = token.nil? || token.to_s.empty? ? nil : token.to_s
+    end
+
+    # Links what happened before sign-in to the user: tracks `identify` in the current (pre-login)
+    # session under player_id, then attributes the rest of the request to player_id. The Railtie
+    # calls this from Warden's sign-in hook when identify_on_login is on.
+    def identify(player_id)
+      player_id = player_id.to_s
+      return if player_id.empty?
+
+      scope = Scope.current
+      # The scope's user or the bucket, never the user_resolver: by the time Warden's sign-in hook
+      # runs, a resolver reading current_user already names the user who just signed in.
+      previous = scope.user.to_s
+      previous = Identity.new(client.config).bucket(scope: scope, controller: ExecutionContext.current[:controller]) if previous.empty?
+      analytics.identify(player_id, previous_player_id: previous) unless previous == player_id
+      scope.user = player_id
+    end
+
+    # Runs the block in a fresh scope (a unit of work outside Rails' request and job hooks).
+    def with_scope(env = nil, &) = Scope.isolated(env, &)
+
+    def sdk_version = "fractal-ruby/#{VERSION}"
+
+    # For tests: forget the active client without delivering anything.
+    def reset!
+      @client = nil
+      Scope.clear
+    end
+  end
+end
+
+require_relative "fractal/rails/railtie" if defined?(Rails::Railtie)

metadata

@@ -0,0 +1,63 @@
+--- !ruby/object:Gem::Specification
+name: fractal-ruby
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Fractal
+bindir: bin
+cert_chain: []
+date: 2026-10-12 00:00:00.000000000 Z
+dependencies: []
+description: Reports a Rails app's exceptions to Fractal's /v1/errors and sends server-side
+  analytics events to /v1/batch, from a background thread that never slows a request.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- VERSION
+- lib/fractal-ruby.rb
+- lib/fractal.rb
+- lib/fractal/analytics.rb
+- lib/fractal/breaker.rb
+- lib/fractal/client.rb
+- lib/fractal/configuration.rb
+- lib/fractal/error_reporter.rb
+- lib/fractal/event_builder.rb
+- lib/fractal/fingerprint.rb
+- lib/fractal/identity.rb
+- lib/fractal/rails/error_subscriber.rb
+- lib/fractal/rails/middleware.rb
+- lib/fractal/rails/railtie.rb
+- lib/fractal/rails/warden_hooks.rb
+- lib/fractal/scope.rb
+- lib/fractal/scrubber.rb
+- lib/fractal/transport.rb
+- lib/fractal/version.rb
+homepage: https://getfractal.dev
+licenses:
+- MIT
+metadata:
+  documentation_uri: https://getfractal.dev/help/sdk-integration/ruby
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Error tracking and analytics for Ruby on Rails backends, reporting to Fractal.
+test_files: []