hawk-ruby 0.1.0

data/lib/hawk/diagnostics.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Hawk
+  # Counters and callbacks contain no event data or collector credentials.
+  class Diagnostics
+    def initialize(callback = nil, logger: nil)
+      @callback = callback
+      @logger = logger
+      reset
+    end
+
+    def increment(name)
+      reset if @pid != Process.pid
+      @mutex.synchronize { @counts[name] = @counts.fetch(name, 0) + 1 }
+      notify
+      nil
+    end
+
+    def snapshot
+      reset if @pid != Process.pid
+      @mutex.synchronize { @counts.dup }
+    end
+
+    private
+
+    def notify
+      callback = @callback
+      logger = @logger
+      return unless callback || logger
+
+      acquired = @mutex.synchronize { !@notifying && (@notifying = true) }
+      return unless acquired
+
+      emit
+    ensure
+      @mutex.synchronize { @notifying = false } if acquired
+    end
+
+    def emit
+      Hook.call do
+        @callback&.call(snapshot)
+        @logger&.warn("Hawk delivery counters: #{JSON.generate(snapshot)}")
+      end
+    end
+
+    def reset
+      @pid = Process.pid
+      @mutex = Mutex.new
+      @counts = {}
+      @notifying = false
+    end
+  end
+end

data/lib/hawk/event.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module Hawk
+  # Builds the native protocol payload; hooks never receive integration tokens.
+  class Event
+    def initialize(configuration:, id:, exception: nil, message: nil, context: {}, user: nil,
+                   breadcrumbs: [], addons: {}, level: :error, filtered_paths: [])
+      @configuration = configuration
+      @filtered_paths = filtered_paths
+      @addons = metadata(id, level).merge(JSONValue.object(addons))
+      @payload = {
+        "title" => exception ? title(exception) : (message || "Message"),
+        "type" => exception ? exception.class.name.to_s : "Message",
+        "catcherVersion" => VERSION,
+        "context" => JSONValue.normalize(context),
+        "breadcrumbs" => JSONValue.normalize(breadcrumbs),
+        "user" => JSONValue.normalize(user),
+        "release" => configuration.release,
+        "addons" => @addons
+      }.compact
+      attach_exception(exception) if exception
+    end
+
+    def encode
+      payload = filtered_payload
+      return unless payload
+
+      hook = @configuration.before_send
+      if hook
+        case result = Hook.call { hook.call(payload) }
+        when Hash then payload = JSONValue.object(result)
+        else return nil
+        end
+      end
+      return unless valid_payload?(payload)
+
+      bounded_envelope(payload)
+    rescue StandardError
+      nil
+    end
+
+    private
+
+    def filtered_payload
+      payload = JSONValue.object(Filter.new(@configuration).call(@payload))
+      FrameworkFilter.call(@configuration, payload, @filtered_paths)
+    end
+
+    def title(exception)
+      JSONValue.normalize(exception.message).to_s
+    rescue StandardError
+      exception.class.name.to_s
+    end
+
+    def metadata(id, level)
+      { "event_id" => id, "level" => level.to_s, "environment" => @configuration.environment,
+        "ruby" => { "version" => RUBY_VERSION, "platform" => RUBY_PLATFORM, "engine" => RUBY_ENGINE } }
+    end
+
+    def attach_exception(exception)
+      @payload["backtrace"] = Source.new(@configuration).frames(exception)
+      chain = causes(exception)
+      @addons["causes"] = chain unless chain.empty?
+    end
+
+    def causes(exception)
+      # @type var result: Array[payload]
+      result = []
+      # @type var seen: Hash[Exception, bool]
+      seen = {}
+      seen.compare_by_identity
+      current = exception.cause
+      while current && result.size < 10 && !seen[current]
+        seen[current] = true
+        result << { "type" => current.class.name.to_s, "title" => title(current),
+                    "backtrace" => Source.new(@configuration).frames(current) }
+        current = current.cause
+      end
+      result
+    rescue StandardError
+      result
+    end
+
+    def valid_payload?(payload)
+      case value = payload["title"]
+      when String then !value.empty?
+      else false
+      end
+    end
+
+    def envelope(payload)
+      JSON.generate("token" => @configuration.token, "catcherType" => "errors/ruby", "payload" => payload)
+    end
+
+    def bounded_envelope(payload)
+      %i[sources breadcrumbs causes context addons frames].each do |phase|
+        encoded = envelope(payload)
+        return encoded if encoded.bytesize <= 262_144
+
+        trim(payload, phase)
+      end
+      encoded = envelope(payload)
+      encoded if encoded.bytesize <= 262_144
+    end
+
+    def trim(payload, phase)
+      case phase
+      when :sources then trim_sources(payload)
+      when :breadcrumbs then keep_first(payload, "breadcrumbs", newest: true)
+      when :causes
+        case addons = payload["addons"]
+        when Hash then keep_first(addons, "causes")
+        end
+      when :context, :addons then payload.delete(phase.to_s)
+      else keep_first(payload, "backtrace")
+      end
+    end
+
+    def trim_sources(payload)
+      case frames = payload["backtrace"]
+      when Array
+        frames.each do |frame|
+          case frame
+          when Hash then frame.delete("sourceCode")
+          end
+        end
+      end
+    end
+
+    def keep_first(payload, key, newest: false)
+      case items = payload[key]
+      when Array then payload[key] = newest ? items.last(1) : items.take(1)
+      end
+    end
+  end
+end

data/lib/hawk/filter.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Hawk
+  # Filters detached JSON data before hooks or transmission can observe it.
+  class Filter
+    SENSITIVE = /password|secret|passwd|api_?key|access_token|auth|credentials|mysql_pwd|stripetoken|card/i
+
+    def initialize(configuration)
+      @patterns = configuration.filter_parameters.map do |pattern|
+        case pattern
+        when String then Regexp.new(Regexp.escape(pattern), Regexp::IGNORECASE)
+        else pattern
+        end
+      end
+    end
+
+    def call(value)
+      filter(JSONValue.normalize(value))
+    end
+
+    private
+
+    def filter(value)
+      case value
+      when Hash
+        value.to_h { |key, item| [key, sensitive?(key) ? "[FILTERED]" : filter(item)] }
+      when Array then value.map { |item| filter(item) }
+      else value
+      end
+    end
+
+    def sensitive?(key)
+      SENSITIVE.match?(key) || @patterns.any? { |pattern| pattern.match?(key) }
+    end
+  end
+end

data/lib/hawk/filtered_fields.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Hawk
+  # Empty placeholders retain parent/key masking while excluding saved contents.
+  class FilteredFields
+    def initialize(payload, paths, containers_only: false)
+      @entries = []
+      paths.each { |path| extract(payload, path, containers_only) }
+    end
+
+    def restore(payload)
+      @entries.each do |path, key, value|
+        parent = parent_at(payload, path)
+        next unless parent
+
+        case placeholder = parent[key]
+        when Hash then parent[key] = yield(key, value) if placeholder.empty?
+        end
+      end
+      payload
+    end
+
+    private
+
+    def extract(payload, path, containers_only)
+      key = path.fetch(-1)
+      parent_path = path.take(path.size - 1)
+      parent = parent_at(payload, parent_path)
+      return unless parent&.key?(key)
+
+      value = parent[key]
+      return if containers_only && !container?(value)
+
+      @entries << [parent_path, key, value]
+      parent[key] = {}
+    end
+
+    def container?(value)
+      case value
+      when Hash, Array then true
+      else false
+      end
+    end
+
+    def parent_at(payload, path)
+      current = payload
+      path.each do |key|
+        case child = current[key]
+        when Hash then current = child
+        else return nil
+        end
+      end
+      current
+    end
+  end
+end

data/lib/hawk/framework_filter.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Hawk
+  # Previously filtered fields cross later boundaries without another transform.
+  module FrameworkFilter
+    def self.call(configuration, payload, filtered_paths = [])
+      filter = configuration.framework_filter
+      return payload unless filter
+
+      saved = FilteredFields.new(payload, filtered_paths)
+      case result = Hook.call { filter.call(payload) }
+      when Hash then saved.restore(JSONValue.object(result)) { |_key, value| value }
+      end
+    end
+  end
+end

data/lib/hawk/hook.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Hawk
+  # User callbacks must not change application control flow or stop delivery.
+  module Hook
+    def self.call(&)
+      Breadcrumbs.guard(:sdk, &)
+    rescue Exception # rubocop:disable Lint/RescueException -- Isolate every exception raised by a user hook.
+      nil
+    end
+  end
+end

data/lib/hawk/job_context.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Hawk
+  # Only explicit, filtered JSON context crosses a queue boundary.
+  module JobContext
+    def self.dump(client)
+      return unless client.configuration.propagate_job_context
+
+      scope = client.current_scope
+      data = { "version" => 1, "context" => scope.context, "user" => scope.user }
+      data = Filter.new(client.configuration).call(data)
+      load(FrameworkFilter.call(client.configuration, JSONValue.object(data), scope.filtered_paths))
+    rescue StandardError
+      nil
+    end
+
+    def self.load(raw)
+      return unless valid?(raw, 0, { remaining: 1024 })
+
+      data = JSONValue.object(raw)
+      return unless valid_header?(data) && JSON.generate(data).bytesize <= 8192
+
+      data.slice("version", "context", "user")
+    rescue StandardError
+      nil
+    end
+
+    def self.apply(client, raw)
+      return unless client.configuration.propagate_job_context
+
+      data = load(raw)
+      return unless data
+
+      user = JSONValue.object(data["user"]) if data["user"]
+      client.current_scope.restore_filtered(JSONValue.object(data["context"]), user)
+    end
+
+    def self.valid_header?(data)
+      case version = data["version"]
+      when Integer then version == 1 && object?(data["context"]) && object?(data["user"], optional: true)
+      else false
+      end
+    end
+
+    def self.object?(value, optional: false)
+      case value
+      when Hash then true
+      when nil then optional
+      else false
+      end
+    end
+
+    def self.valid?(value, depth, budget)
+      budget[:remaining] = budget.fetch(:remaining) - 1
+      return false if depth > 6 || budget.fetch(:remaining).negative?
+
+      case value
+      when Hash then valid_object?(value, depth, budget)
+      when Array then valid_array?(value, depth, budget)
+      when String then valid_key?(value)
+      else valid_scalar?(value)
+      end
+    end
+
+    def self.valid_scalar?(value)
+      case value
+      when Float then value.finite?
+      when Integer, true, false, nil then true
+      else false
+      end
+    end
+
+    def self.valid_key?(value)
+      case value
+      when String then value.valid_encoding? && value.encoding.ascii_compatible? && value.bytesize <= 8192
+      else false
+      end
+    end
+
+    def self.valid_object?(value, depth, budget)
+      value.size <= 100 && value.all? { |key, item| valid_key?(key) && valid?(item, depth + 1, budget) }
+    end
+
+    def self.valid_array?(value, depth, budget)
+      value.size <= 100 && value.all? { |item| valid?(item, depth + 1, budget) }
+    end
+    private_class_method :valid?, :valid_header?, :object?, :valid_scalar?, :valid_key?, :valid_object?, :valid_array?
+  end
+end

data/lib/hawk/json_value.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Hawk
+  # Copies boundary data into a bounded JSON tree without custom serializers.
+  class JSONValue
+    def self.normalize(value)
+      new.visit(value, 0)
+    end
+
+    def self.object(value)
+      case result = normalize(value)
+      when Hash then result
+      else {}
+      end
+    end
+
+    def initialize
+      @seen = {}
+      @seen.compare_by_identity
+      @remaining = 5000
+    end
+
+    def visit(value, depth)
+      @remaining -= 1
+      return "[Truncated]" if depth > 10 || @remaining.negative?
+
+      case value
+      when String then text(value)
+      when Array, Hash then container(value, depth)
+      else scalar(value)
+      end
+    rescue StandardError
+      "[Unavailable]"
+    end
+
+    private
+
+    def scalar(value)
+      case value
+      when NilClass, TrueClass, FalseClass, Integer then value
+      when Float then value.finite? ? value : nil
+      when Object then "[#{value.class.name || 'Object'}]"
+      else "[Unsupported]"
+      end
+    end
+
+    def text(value)
+      value.encode(Encoding::UTF_8, invalid: :replace, undef: :replace).byteslice(0, 8192).to_s.scrub("")
+    end
+
+    def container(value, depth)
+      entered = false
+      return "[Circular]" if @seen[value]
+
+      @seen[value] = true
+      entered = true
+      case value
+      when Array then value.take(100).map { |item| visit(item, depth + 1) }
+      else mapping(value, depth)
+      end
+    ensure
+      @seen.delete(value) if entered
+    end
+
+    def mapping(value, depth)
+      # @type var result: payload
+      result = {}
+      value.first(100).each do |key, item|
+        case key
+        when String, Symbol
+          result[text(key.to_s)] = visit(item, depth + 1)
+        end
+      end
+      result
+    end
+  end
+end

data/lib/hawk/process_hooks.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Hawk
+  # Resolving the client at shutdown keeps repeated initialization idempotent.
+  module ProcessHooks
+    def self.install
+      return if @installed
+
+      @installed = true
+      at_exit { report_exit($!) }
+      nil
+    end
+
+    def self.report_exit(exception)
+      client = Hawk.client
+      return unless client
+      return unless client.configuration.global_errors
+
+      client.report(exception, mechanism: "at_exit", level: :fatal) if exception && !client.consume_escape(exception)
+      client.close
+      nil
+    end
+  end
+end

data/lib/hawk/rack/body.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Hawk
+  class Rack
+    # Guards establish each foreign protocol before its type is narrowed.
+    class Body
+      def self.wrap(body, client:, scope:)
+        if body.respond_to?(:each)
+          if body.respond_to?(:to_path)
+            file_body = body #: _RackFileBody
+            return FileBody.new(file_body, client: client, scope: scope)
+          end
+          enumerable = body #: _RackEnumerableBody
+          return new(enumerable, client: client, scope: scope)
+        end
+        if body.respond_to?(:call)
+          callable = body #: _RackCallableBody
+          return CallableBody.new(callable, client: client, scope: scope)
+        end
+
+        body
+      end
+
+      def initialize(body, client:, scope:)
+        @body = body
+        @client = client
+        @scope = scope
+      end
+
+      def each(&block)
+        return enum_for(:each) unless block_given?
+
+        Boundary.resume(@client, @scope) { @body.each(&block) }
+      end
+
+      def close
+        return unless @body.respond_to?(:close)
+
+        body = @body #: _RackClosableBody
+        Boundary.resume(@client, @scope) { body.close }
+      end
+    end
+
+    # File responses retain the path API used by Rack sendfile middleware.
+    class FileBody < Body
+      def initialize(body, client:, scope:)
+        super
+        @file_body = body
+      end
+
+      def to_path
+        Boundary.resume(@client, @scope) { @file_body.to_path }
+      end
+    end
+
+    # Rack 3 can stream by calling a body with the server's stream object.
+    class CallableBody
+      def initialize(body, client:, scope:)
+        @body = body
+        @client = client
+        @scope = scope
+      end
+
+      def call(stream)
+        Boundary.resume(@client, @scope) { @body.call(stream) }
+      end
+
+      def close
+        return unless @body.respond_to?(:close)
+
+        body = @body #: _RackClosableBody
+        Boundary.resume(@client, @scope) { body.close }
+      end
+    end
+  end
+end

data/lib/hawk/rack.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative "../hawk"
+
+module Hawk
+  # Request scope covers application calls and the deferred response body.
+  class Rack
+    def initialize(app, client: nil, integration: :rack)
+      @app = app
+      @client = client
+      @integration = integration
+    end
+
+    def call(env)
+      client = active_client
+      return @app.call(env) unless client
+
+      Boundary.run(client, kind: :request, metadata: {}) do
+        status, headers, body = invoke(client, env)
+        [status, headers, Body.wrap(body, client: client, scope: client.current_scope.copy)]
+      end
+    end
+
+    private
+
+    def active_client
+      client = @client || Hawk.client
+      client if client&.enabled? && client.configuration.integration_enabled?(@integration)
+    end
+
+    def invoke(client, env)
+      scope = client.current_scope
+      scope.request_metadata = -> { metadata(env) }
+      begin
+        @app.call(env)
+      ensure
+        scope.request_metadata = nil
+        scope.addons["request"] = metadata(env)
+      end
+    end
+
+    def metadata(env)
+      data = JSONValue.object(env.slice("REQUEST_METHOD", "PATH_INFO", "action_dispatch.request_id"))
+      result = { "method" => data["REQUEST_METHOD"], "path" => data["PATH_INFO"],
+                 "request_id" => data["action_dispatch.request_id"] }
+      params = JSONValue.object(env["action_dispatch.request.parameters"] || env["rack.request.query_hash"])
+      path = JSONValue.object(env["action_dispatch.request.path_parameters"])
+      result.merge!("params" => params, "controller" => path["controller"], "action" => path["action"])
+      optional_metadata(result, env)
+    rescue StandardError
+      {}
+    end
+
+    def optional_metadata(result, env)
+      client = active_client
+      return result unless client
+
+      config = client.configuration
+      result["headers"] = headers(env) if config.include_headers
+      result["cookies"] = JSONValue.normalize(env["HTTP_COOKIE"]) if config.include_cookies
+      result["body"] = JSONValue.normalize(env["RAW_POST_DATA"]) if config.include_request_body
+      result
+    end
+
+    def headers(env)
+      JSONValue.object(env.select { |key, _value| key.start_with?("HTTP_") && key != "HTTP_COOKIE" })
+    end
+  end
+end
+
+require_relative "rack/body"