uncaught 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f39344c92b50ad3308911adcf49713a5d94595c90f878af2272dff89b4a7b9ab
+  data.tar.gz: '029a359e0db5aa4184b5ae341949bd86e657d0704a5cee6086b18c0acbc13455'
+SHA512:
+  metadata.gz: d425228bc633b44e6d919bbb2192944f9e089716c8bb1637a2e45e4bcfac2b862ec0357885a3957709a3a6bd12b517a09fc583d6b81bba5fe1987b637f5d5a7c
+  data.tar.gz: d4cfb32ae1122dedd164eee47262b609befc4b68a4a2e1600bfc448c1423c4dd55e748b9795c5b00da8943615947a3e53b4da6dd23b8b4df23d688887973e7b4

data/lib/uncaught/breadcrumbs.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Uncaught
+  # Thread-safe ring buffer for breadcrumbs.
+  #
+  # - O(1) add
+  # - Oldest entries are silently overwritten when capacity is reached.
+  # - Returned arrays are always copies -- callers cannot mutate internal state.
+  class BreadcrumbStore
+    # @param capacity [Integer] Maximum breadcrumbs retained. Defaults to 20.
+    def initialize(capacity = 20)
+      @capacity = [capacity, 1].max
+      @buffer = Array.new(@capacity)
+      @head = 0
+      @size = 0
+      @mutex = Mutex.new
+    end
+
+    # Append a breadcrumb (auto-timestamps).
+    #
+    # @param type     [String]
+    # @param category [String]
+    # @param message  [String]
+    # @param data     [Hash, nil]
+    # @param level    [String, nil]
+    def add(type:, category:, message:, data: nil, level: nil)
+      entry = Breadcrumb.new(
+        type: type,
+        category: category,
+        message: message,
+        timestamp: Time.now.utc.iso8601(3),
+        data: data,
+        level: level
+      )
+
+      @mutex.synchronize do
+        @buffer[@head] = entry
+        @head = (@head + 1) % @capacity
+        @size = [@size + 1, @capacity].min
+      end
+    end
+
+    # Return all stored breadcrumbs in chronological order (copies).
+    #
+    # @return [Array<Breadcrumb>]
+    def get_all
+      @mutex.synchronize do
+        return [] if @size == 0
+
+        result = []
+        start = (@head - @size + @capacity) % @capacity
+        @size.times do |i|
+          idx = (start + i) % @capacity
+          entry = @buffer[idx]
+          result << entry.dup if entry
+        end
+        result
+      end
+    end
+
+    # Return the most recent n breadcrumbs (copies).
+    #
+    # @param n [Integer]
+    # @return [Array<Breadcrumb>]
+    def get_last(n)
+      @mutex.synchronize do
+        return [] if n <= 0 || @size == 0
+
+        count = [n, @size].min
+        result = []
+        count.times do |i|
+          idx = (@head - 1 - i + @capacity) % @capacity
+          entry = @buffer[idx]
+          result.unshift(entry.dup) if entry
+        end
+        result
+      end
+    end
+
+    # Empty the buffer.
+    def clear
+      @mutex.synchronize do
+        @buffer = Array.new(@capacity)
+        @head = 0
+        @size = 0
+      end
+    end
+
+    # @return [Integer]
+    def size
+      @mutex.synchronize { @size }
+    end
+  end
+end

data/lib/uncaught/client.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "time"
+
+module Uncaught
+  SDK_NAME = "uncaught-ruby"
+
+  # The main SDK client. Captures errors and sends them through the transport
+  # pipeline.
+  class Client
+    attr_reader :config
+
+    # @param config [Configuration]
+    def initialize(config)
+      @config = config
+      @breadcrumbs = BreadcrumbStore.new(config.max_breadcrumbs || 20)
+      @transport = Uncaught.create_transport(config)
+      @rate_limiter = RateLimiter.new(
+        global_max: config.max_events_per_minute || 30
+      )
+      @session_id = SecureRandom.uuid
+      @seen_fingerprints = Set.new
+      @user = nil
+      @mutex = Mutex.new
+    end
+
+    # Capture an error and send it through the transport pipeline.
+    #
+    # @param error   [Exception, String, Hash] The error to capture.
+    # @param request [RequestInfo, nil]
+    # @param operation [OperationInfo, nil]
+    # @param component_stack [String, nil]
+    # @param level [String] Severity level. Defaults to "error".
+    # @return [String, nil] The event ID, or nil if the event was dropped.
+    def capture_error(error, request: nil, operation: nil, component_stack: nil, level: "error")
+      return nil unless @config.enabled
+
+      # --- Normalise error ---
+      error_info = normalise_error(error)
+      error_info.component_stack = component_stack if component_stack
+
+      # --- Check ignoreErrors ---
+      if should_ignore?(error_info.message)
+        debug_log("Event ignored by ignoreErrors filter")
+        return nil
+      end
+
+      # --- Fingerprint ---
+      fingerprint = Fingerprint.generate(
+        type: error_info.type,
+        message: error_info.message,
+        stack: error_info.stack
+      )
+
+      # --- Rate limit ---
+      unless @rate_limiter.should_allow?(fingerprint)
+        debug_log("Rate-limited: #{fingerprint}")
+        return nil
+      end
+
+      # --- Collect breadcrumbs ---
+      crumbs = @breadcrumbs.get_all
+
+      # --- Detect environment ---
+      environment = EnvDetector.detect
+
+      # Attach deployment environment from config
+      environment.deploy = @config.environment if @config.environment
+      environment.framework = @config.framework if @config.framework
+      environment.framework_version = @config.framework_version if @config.framework_version
+
+      # --- Build event ---
+      event_id = SecureRandom.uuid
+      event = UncaughtEvent.new(
+        event_id: event_id,
+        timestamp: Time.now.utc.iso8601(3),
+        project_key: @config.project_key,
+        level: level,
+        fingerprint: fingerprint,
+        release: @config.release,
+        error: error_info,
+        breadcrumbs: crumbs,
+        request: request,
+        operation: operation,
+        environment: environment,
+        user: build_user_info,
+        fix_prompt: "",
+        sdk: SdkInfo.new(name: SDK_NAME, version: VERSION)
+      )
+
+      # --- Sanitise ---
+      event = Sanitizer.sanitize(event, @config.sanitize_keys)
+
+      # --- Build fix prompt ---
+      event.fix_prompt = PromptBuilder.build(event)
+
+      # --- beforeSend hook ---
+      if @config.before_send
+        result = @config.before_send.call(event)
+        if result.nil?
+          debug_log("Event dropped by beforeSend")
+          return nil
+        end
+        event = result
+      end
+
+      # --- Send ---
+      @transport.send_event(event)
+      debug_log("Captured event: #{event_id} (#{fingerprint})")
+
+      # --- Track seen fingerprints ---
+      @mutex.synchronize do
+        @seen_fingerprints.add(fingerprint)
+      end
+
+      event_id
+    rescue => e
+      debug_log("capture_error failed: #{e.message}")
+      nil
+    end
+
+    # Capture a plain message (not backed by an Exception instance).
+    #
+    # @param message [String]
+    # @param level   [String] Defaults to "info".
+    # @return [String, nil] The event ID, or nil if the event was dropped.
+    def capture_message(message, level: "info")
+      capture_error(RuntimeError.new(message), level: level)
+    rescue => e
+      debug_log("capture_message failed: #{e.message}")
+      nil
+    end
+
+    # Add a breadcrumb to the ring buffer.
+    #
+    # @param type     [String]
+    # @param category [String]
+    # @param message  [String]
+    # @param data     [Hash, nil]
+    # @param level    [String, nil]
+    def add_breadcrumb(type:, category:, message:, data: nil, level: nil)
+      return unless @config.enabled
+
+      @breadcrumbs.add(
+        type: type,
+        category: category,
+        message: message,
+        data: data,
+        level: level
+      )
+    rescue => e
+      debug_log("add_breadcrumb failed: #{e.message}")
+    end
+
+    # Set user context that will be attached to subsequent events.
+    #
+    # @param user [UserInfo, Hash, nil]
+    def set_user(user)
+      @mutex.synchronize do
+        if user.nil?
+          @user = nil
+        elsif user.is_a?(UserInfo)
+          @user = user.dup
+        elsif user.is_a?(Hash)
+          @user = UserInfo.new(
+            id: user[:id] || user["id"],
+            email: user[:email] || user["email"],
+            username: user[:username] || user["username"]
+          )
+        end
+      end
+    rescue => e
+      debug_log("set_user failed: #{e.message}")
+    end
+
+    # Flush all queued events to the transport.
+    def flush
+      @transport.flush
+    rescue => e
+      debug_log("flush failed: #{e.message}")
+    end
+
+    private
+
+    def normalise_error(error)
+      case error
+      when Exception
+        ErrorInfo.new(
+          message: error.message || error.to_s,
+          type: error.class.name || "Error",
+          stack: (error.backtrace || []).join("\n")
+        )
+      when String
+        ErrorInfo.new(
+          message: error,
+          type: "StringError",
+          stack: caller.join("\n")
+        )
+      when Hash
+        ErrorInfo.new(
+          message: (error[:message] || error["message"] || error.to_s).to_s,
+          type: (error[:type] || error["type"] || "HashError").to_s,
+          stack: (error[:stack] || error["stack"] || "").to_s
+        )
+      else
+        ErrorInfo.new(
+          message: error.to_s,
+          type: "UnknownError"
+        )
+      end
+    end
+
+    def should_ignore?(message)
+      return false unless @config.ignore_errors && !@config.ignore_errors.empty?
+
+      @config.ignore_errors.any? do |pattern|
+        case pattern
+        when String
+          message.include?(pattern)
+        when Regexp
+          pattern.match?(message)
+        else
+          false
+        end
+      end
+    end
+
+    def build_user_info
+      @mutex.synchronize do
+        if @user
+          UserInfo.new(
+            id: @user.id,
+            email: @user.email,
+            username: @user.username,
+            session_id: @session_id
+          )
+        else
+          UserInfo.new(session_id: @session_id)
+        end
+      end
+    end
+
+    def debug_log(msg)
+      $stderr.puts("[uncaught] #{msg}") if @config.debug
+    end
+  end
+end

data/lib/uncaught/env_detector.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Uncaught
+  module EnvDetector
+    module_function
+
+    # Detect the current runtime environment.
+    #
+    # @return [EnvironmentInfo]
+    def detect
+      info = EnvironmentInfo.new
+
+      info.runtime = "ruby"
+      info.runtime_version = RUBY_VERSION
+      info.platform = RUBY_PLATFORM
+      info.os = detect_os
+
+      # Detect framework
+      detect_framework(info)
+
+      # Detect hosting platform
+      detect_platform(info)
+
+      info
+    end
+
+    # -------------------------------------------------------------------------
+    # Internal helpers
+    # -------------------------------------------------------------------------
+
+    def detect_os
+      case RUBY_PLATFORM
+      when /darwin/i
+        "macOS"
+      when /mswin|mingw|cygwin/i
+        "Windows"
+      when /linux/i
+        "Linux"
+      when /freebsd/i
+        "FreeBSD"
+      else
+        RUBY_PLATFORM
+      end
+    end
+
+    def detect_framework(info)
+      # Rails
+      if defined?(::Rails)
+        info.framework = "Rails"
+        info.framework_version = ::Rails::VERSION::STRING if defined?(::Rails::VERSION::STRING)
+        return
+      end
+
+      # Sinatra
+      if defined?(::Sinatra)
+        info.framework = "Sinatra"
+        info.framework_version = ::Sinatra::VERSION if defined?(::Sinatra::VERSION)
+        return
+      end
+
+      # Hanami
+      if defined?(::Hanami)
+        info.framework = "Hanami"
+        info.framework_version = ::Hanami::VERSION if defined?(::Hanami::VERSION)
+        return
+      end
+
+      # Grape
+      if defined?(::Grape)
+        info.framework = "Grape"
+        info.framework_version = ::Grape::VERSION if defined?(::Grape::VERSION)
+        return
+      end
+
+      # Roda
+      if defined?(::Roda)
+        info.framework = "Roda"
+        return
+      end
+    end
+
+    def detect_platform(info)
+      if ENV["HEROKU_APP_NAME"]
+        info.platform = "heroku"
+      elsif ENV["VERCEL"]
+        info.platform = "vercel"
+      elsif ENV["RAILWAY_PROJECT_ID"]
+        info.platform = "railway"
+      elsif ENV["FLY_APP_NAME"]
+        info.platform = "fly"
+      elsif ENV["AWS_LAMBDA_FUNCTION_NAME"]
+        info.platform = "aws-lambda"
+      elsif ENV["GOOGLE_CLOUD_PROJECT"]
+        info.platform = "gcp"
+      elsif ENV["RENDER_SERVICE_ID"]
+        info.platform = "render"
+      end
+    end
+
+    private_class_method :detect_os, :detect_framework, :detect_platform
+  end
+end

data/lib/uncaught/fingerprint.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module Uncaught
+  module Fingerprint
+    module_function
+
+    # Generate a stable fingerprint for an error so that duplicate occurrences
+    # of the same bug are grouped together.
+    #
+    # The fingerprint is an 8-character hex string derived from:
+    #   1. The error type (or "Error" if absent).
+    #   2. The normalised error message (volatile parts stripped).
+    #   3. The top 3 stack frames (file + function name, no line/col numbers).
+    #
+    # @param type    [String, nil] Error class name.
+    # @param message [String, nil] Error message.
+    # @param stack   [String, nil] Stack trace string.
+    # @return [String] 8-character lowercase hex fingerprint.
+    def generate(type: nil, message: nil, stack: nil)
+      normalised_message = normalise_message(message || "")
+      frames = extract_top_frames(stack || "", 3)
+      input = [type || "Error", normalised_message, *frames].join("\n")
+      djb2(input)
+    end
+
+    # -------------------------------------------------------------------------
+    # DJB2 hash -> 8-character lowercase hex string.
+    #
+    # Matches the TypeScript implementation exactly:
+    #   let hash = 5381;
+    #   hash = ((hash << 5) + hash + charCode) | 0;   // signed 32-bit
+    #   return (hash >>> 0).toString(16).padStart(8, '0');
+    #
+    # Ruby integers are arbitrary precision, so we must mask to 32 bits after
+    # every operation to emulate JavaScript's `| 0` (signed 32-bit) and
+    # `>>> 0` (unsigned 32-bit) semantics.
+    # -------------------------------------------------------------------------
+    def djb2(str)
+      hash = 5381
+      # JavaScript's charCodeAt() returns UTF-16 code units, not UTF-8 bytes.
+      # For BMP characters (U+0000..U+FFFF), the code unit equals the code point.
+      # For characters above U+FFFF, JavaScript uses surrogate pairs (two 16-bit
+      # code units). We replicate this by encoding to UTF-16LE and reading pairs.
+      utf16_bytes = str.encode("UTF-16LE").bytes
+      i = 0
+      while i < utf16_bytes.length
+        # Read a 16-bit little-endian code unit (matches JS charCodeAt)
+        code_unit = utf16_bytes[i] | (utf16_bytes[i + 1] << 8)
+        # hash * 33 + code_unit, then truncate to signed 32-bit via `| 0`
+        hash = (((hash << 5) + hash) + code_unit) & 0xFFFFFFFF
+        hash = to_signed32(hash)
+        i += 2
+      end
+      # Emulate JavaScript `>>> 0` (convert to unsigned 32-bit)
+      unsigned = hash & 0xFFFFFFFF
+      unsigned.to_s(16).rjust(8, "0")
+    end
+
+    # -------------------------------------------------------------------------
+    # Internal helpers
+    # -------------------------------------------------------------------------
+
+    # Strip volatile substrings from an error message so that trivially-different
+    # occurrences of the same bug hash identically.
+    def normalise_message(msg)
+      result = msg.dup
+      # UUIDs (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)
+      result.gsub!(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i, "<UUID>")
+      # Hex strings (8+ hex chars in a row, word-bounded)
+      result.gsub!(/\b[0-9a-f]{8,}\b/i, "<HEX>")
+      # Numbers longer than 3 digits
+      result.gsub!(/\b\d{4,}\b/, "<NUM>")
+      # ISO timestamps
+      result.gsub!(/\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}[.\d]*Z?/, "<TIMESTAMP>")
+      # Hashed file paths
+      result.gsub!(%r{([/\\])[a-zA-Z0-9_-]+[-.]([a-f0-9]{6,})\.(js|ts|mjs|cjs|jsx|tsx)}, '\1<FILE>.\3')
+      result.strip
+    end
+
+    # Extract the top N stack frames as normalised "file:function" strings.
+    # Supports V8, SpiderMonkey, and Ruby stack trace formats.
+    def extract_top_frames(stack, count)
+      return [] if stack.nil? || stack.empty?
+
+      frames = []
+      stack.split("\n").each do |line|
+        break if frames.size >= count
+
+        trimmed = line.strip
+
+        # V8 format: "    at FunctionName (file:line:col)"
+        # or         "    at file:line:col"
+        if (v8_match = trimmed.match(/at\s+(?:(.+?)\s+\()?(?:(.+?):\d+:\d+)\)?/))
+          fn = v8_match[1] || "<anonymous>"
+          file = normalise_path(v8_match[2] || "<unknown>")
+          frames << "#{file}:#{fn}"
+          next
+        end
+
+        # SpiderMonkey / JavaScriptCore: "functionName@file:line:col"
+        if (sm_match = trimmed.match(/^(.+?)@(.+?):\d+:\d+/))
+          fn = sm_match[1] || "<anonymous>"
+          file = normalise_path(sm_match[2] || "<unknown>")
+          frames << "#{file}:#{fn}"
+          next
+        end
+
+        # Ruby format: "/path/to/file.rb:42:in `method_name'"
+        if (rb_match = trimmed.match(%r{(.+?):(\d+):in\s+[`'](.+?)'}))
+          file = normalise_path(rb_match[1])
+          fn = rb_match[3]
+          frames << "#{file}:#{fn}"
+          next
+        end
+      end
+
+      frames
+    end
+
+    # Normalise a file path by stripping query strings / hashes and collapsing
+    # absolute filesystem prefixes.
+    def normalise_path(path)
+      result = path.dup
+      # Strip query / hash
+      result.sub!(/[?#].*$/, "")
+      # Collapse node_modules deep paths
+      result.sub!(/^.*\/node_modules\//, "node_modules/")
+      # Strip origin in URLs
+      result.sub!(%r{^https?://[^/]+}, "")
+      # Keep only filename
+      result.sub!(%r{^.*[/\\]}, "")
+      result
+    end
+
+    # Convert unsigned 32-bit integer to signed 32-bit integer
+    # (emulating JavaScript's `| 0` operator).
+    def to_signed32(val)
+      val = val & 0xFFFFFFFF
+      val >= 0x80000000 ? val - 0x100000000 : val
+    end
+
+    private_class_method :normalise_message, :extract_top_frames, :normalise_path, :to_signed32
+  end
+end

data/lib/uncaught/integrations/rails.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Uncaught
+  if defined?(::Rails::Railtie)
+    class Railtie < ::Rails::Railtie
+      initializer "uncaught.configure" do |app|
+        app.middleware.use Uncaught::Middleware
+      end
+
+      config.after_initialize do
+        Uncaught.configure do |c|
+          c.environment = Rails.env
+          c.framework = "Rails"
+          c.framework_version = Rails::VERSION::STRING
+        end
+      end
+    end
+  end
+
+  # Rack middleware for Rails / Rack applications.
+  #
+  # - Adds an HTTP breadcrumb for every request.
+  # - Captures unhandled exceptions and re-raises them.
+  class Middleware
+    def initialize(app)
+      @app = app
+      @client = Uncaught.client
+    end
+
+    def call(env)
+      # Refresh client reference in case it was reconfigured.
+      @client = Uncaught.client if @client.nil?
+
+      if @client
+        @client.add_breadcrumb(
+          type: "api_call",
+          category: "http",
+          message: "#{env['REQUEST_METHOD']} #{env['PATH_INFO']}"
+        )
+      end
+
+      @app.call(env)
+    rescue => e
+      if @client
+        request_info = RequestInfo.new(
+          method: env["REQUEST_METHOD"],
+          url: env["REQUEST_URI"] || env["PATH_INFO"]
+        )
+        @client.capture_error(e, request: request_info)
+      end
+      raise
+    end
+  end
+end

data/lib/uncaught/integrations/sinatra.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Uncaught
+  # Sinatra extension for Uncaught error monitoring.
+  #
+  # Usage in a Sinatra app:
+  #
+  #   require "uncaught"
+  #   require "uncaught/integrations/sinatra"
+  #
+  #   class MyApp < Sinatra::Base
+  #     register Uncaught::Sinatra
+  #   end
+  #
+  # Or in a modular app:
+  #
+  #   Sinatra::Application.register Uncaught::Sinatra
+  #
+  module SinatraIntegration
+    def self.registered(app)
+      # Configure Uncaught for Sinatra
+      Uncaught.configure do |c|
+        c.framework = "Sinatra"
+        c.framework_version = ::Sinatra::VERSION if defined?(::Sinatra::VERSION)
+      end
+
+      # Add before filter for breadcrumbs
+      app.before do
+        client = Uncaught.client
+        if client
+          client.add_breadcrumb(
+            type: "api_call",
+            category: "http",
+            message: "#{request.request_method} #{request.path_info}"
+          )
+        end
+      end
+
+      # Add error handler
+      app.error do
+        client = Uncaught.client
+        error = env["sinatra.error"]
+
+        if client && error
+          request_info = Uncaught::RequestInfo.new(
+            method: request.request_method,
+            url: request.url
+          )
+          client.capture_error(error, request: request_info)
+        end
+      end
+    end
+  end
+
+  # Alias for convenient registration: `register Uncaught::Sinatra`
+  Sinatra = SinatraIntegration
+end