hawk-ruby 0.1.0

data/lib/hawk/rails/action_cable.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Hawk
+  module Rails
+    # These wrappers match Rails 7.2, 8.0, and 8.1 lifecycle methods.
+    module ActionCable
+      def self.install
+        return if @installed || !::Rails.version.match?(/\A(?:7\.2|8\.[01])\./)
+
+        ActiveSupport.on_load(:action_cable_channel) do |base|
+          base.prepend(ChannelMethods)
+          base.prepend(RescueMethods)
+        end
+        ActiveSupport.on_load(:action_cable_connection) do |base|
+          base.prepend(ConnectionMethods)
+          base.prepend(RescueMethods)
+        end
+        @installed = true
+      end
+
+      def self.client
+        Rails.integration_client(:action_cable)
+      end
+
+      def self.run(owner, operation, &)
+        client = self.client
+        return yield unless client
+
+        metadata = { "cable" => { "class" => owner.class.name, "operation" => operation } }
+        Boundary.run(client, kind: :cable, metadata: metadata, &)
+      end
+
+      def self.report(error, handled:)
+        client = self.client
+        return unless client
+        return if client.consume_escape(error)
+
+        client.report(error, mechanism: "action_cable", handled: handled)
+      end
+
+      # Channel entry points establish per-operation scopes.
+      module ChannelMethods
+        def perform_action(data)
+          ActionCable.run(self, "perform_action") { super }
+        end
+
+        def subscribe_to_channel
+          ActionCable.run(self, "subscribe_to_channel") { super }
+        end
+
+        def unsubscribe_from_channel
+          ActionCable.run(self, "unsubscribe_from_channel") { super }
+        end
+      end
+
+      # Connection lifecycle callbacks run on reusable Cable workers.
+      module ConnectionMethods
+        private
+
+        def handle_open
+          ActionCable.run(self, "handle_open") { super }
+        end
+
+        def handle_close
+          ActionCable.run(self, "handle_close") { super }
+        end
+      end
+
+      # Observe consumed errors without replacing application rescue handlers.
+      module RescueMethods
+        def rescue_with_handler(exception)
+          result = super
+          ActionCable.report(exception, handled: !result.nil?)
+          result
+        end
+      end
+    end
+  end
+end

data/lib/hawk/rails/active_job.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Hawk
+  module Rails
+    # Active Job owns retry decisions; Hawk observes escaping and terminal errors.
+    module ActiveJob
+      def self.install
+        return if @installed || !::Rails.version.match?(/\A(?:7\.2|8\.[01])\./)
+
+        ActiveSupport.on_load(:active_job) do
+          ::ActiveJob::Base.singleton_class.prepend(ClassMethods)
+          ::ActiveJob::Base.prepend(InstanceMethods)
+          ::ActiveJob::Base.after_discard do |_job, error|
+            Hawk::Rails::ActiveJob.client&.report(error, mechanism: "active_job.discard", handled: true)
+          end
+        end
+        @installed = true
+      end
+
+      def self.client
+        Rails.integration_client(:active_job)
+      end
+
+      def self.run(data, context, &block)
+        client = self.client
+        return yield unless client
+
+        Boundary.run(client, kind: :active_job, metadata: { "job" => metadata(client, data) }) do
+          JobContext.apply(client, context)
+          block.call
+        end
+      end
+
+      def self.metadata(client, data)
+        result = JSONValue.object(data.slice("job_class", "job_id", "queue_name", "executions"))
+        result["arguments"] = JSONValue.normalize(data["arguments"]) if client.configuration.include_job_arguments
+        result
+      end
+
+      # Wrap deserialization failures as well as normal job execution.
+      module ClassMethods
+        def execute(job_data)
+          ActiveJob.run(job_data, job_data["hawk"]) { super }
+        end
+      end
+
+      # Serialization keeps application arguments and backend retry data intact.
+      module InstanceMethods
+        def serialize
+          data = super
+          client = ActiveJob.client
+          context = JobContext.dump(client) if client
+          data["hawk"] = context if context
+          data
+        end
+
+        def deserialize(job_data)
+          @hawk_context = JobContext.load(job_data["hawk"])
+          super
+        end
+
+        def perform_now
+          client = ActiveJob.client
+          return super unless client
+
+          data = { "job_class" => self.class.name, "job_id" => job_id, "queue_name" => queue_name,
+                   "executions" => executions, "arguments" => arguments }
+          context = @hawk_context || JobContext.dump(client)
+          ActiveJob.run(data, context) { super }
+        end
+      end
+    end
+  end
+end

data/lib/hawk/rails/error_subscriber.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Hawk
+  module Rails
+    # Rails owns subscriber lifetime; each report resolves the current client.
+    class ErrorSubscriber
+      def self.install
+        return if @installed
+
+        ::Rails.error.subscribe(new)
+        @installed = true
+      end
+
+      def report(error, handled:, severity:, context:, source: nil)
+        client = Rails.integration_client(:rails_error)
+        return unless client
+        return if request_owned?(client, error, source)
+
+        client.with_scope do |scope|
+          scope.addons["rails_source"] = source
+          client.report(error, mechanism: "rails.error", context: JSONValue.object(context),
+                               level: severity, handled: handled)
+        end
+        nil
+      rescue StandardError
+        nil
+      end
+
+      private
+
+      def request_owned?(client, error, source)
+        return false unless source == "application.action_dispatch"
+
+        client.current_scope.addons["boundary"] == "request" || client.consume_escape(error)
+      end
+    end
+  end
+end

data/lib/hawk/rails/integration.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative "../rack"
+require "active_support/parameter_filter"
+require_relative "payload_filter"
+require_relative "error_subscriber"
+require_relative "action_cable"
+require_relative "active_job"
+require_relative "../breadcrumbs/rails"
+
+module Hawk
+  # Framework filtering is injected without changing the user's before_send hook.
+  module Rails
+    def self.configure(configuration)
+      return unless configuration.integration_enabled?(:rails)
+
+      application = ::Rails.application
+      return unless application
+
+      filter = PayloadFilter.new(ActiveSupport::ParameterFilter.new(application.config.filter_parameters))
+      configuration.framework_filter = ->(payload) { filter.call(payload) }
+      activate_integrations(configuration)
+      nil
+    end
+
+    def self.integration_client(integration)
+      client = Hawk.client
+      return unless client&.enabled? && client.configuration.integration_enabled?(:rails)
+
+      client if client.configuration.integration_enabled?(integration)
+    end
+
+    def self.activate_integrations(configuration)
+      ErrorSubscriber.install
+      ActionCable.install
+      ActiveJob.install
+      Breadcrumbs::Rails.install if configuration.breadcrumbs_rails
+      require_relative "../sidekiq" if defined?(::Sidekiq)
+      require_relative "../resque" if defined?(::Resque)
+      require_relative "../delayed_job" if defined?(::Delayed::Worker)
+      nil
+    end
+  end
+
+  # Rails constructs this middleware before its stack is frozen.
+  class Railtie < ::Rails::Railtie
+    initializer "hawk.middleware", after: :load_config_initializers do |application|
+      application.middleware.insert_after(ActionDispatch::DebugExceptions, Hawk::Rack, integration: :rails)
+    end
+  end
+end

data/lib/hawk/rails/payload_filter.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Hawk
+  module Rails
+    # Rails deep filters and original-params blocks need each logical tree root.
+    class PayloadFilter
+      PATHS = [%w[context], %w[user], %w[data], %w[addons request params],
+               %w[addons request body], %w[addons request headers], %w[addons job arguments]].freeze
+
+      def initialize(filter)
+        @filter = filter
+      end
+
+      def call(payload)
+        fields = FilteredFields.new(payload, PATHS, containers_only: true)
+        fields.restore(filter(payload)) { |key, value| filter_tree(key, value) }
+      end
+
+      private
+
+      def filter(payload)
+        JSONValue.object(@filter.filter(payload))
+      end
+
+      def filter_tree(key, value)
+        case value
+        when Hash then filter(value)
+        when Array then value.map { |item| filter_tree(key, item) }
+        else filter({ key => value })[key]
+        end
+      end
+    end
+  end
+end

data/lib/hawk/rails.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative "../hawk"
+require "rails/railtie"
+require_relative "rails/integration"

data/lib/hawk/rake.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "../hawk"
+require "rake"
+
+module Hawk
+  # Optional task capture delegates execution and preserves application errors.
+  module Rake
+    # Prepended to tasks without replacing their original execute implementation.
+    module TaskMethods
+      def execute(args = nil)
+        client = Hawk.client
+        return super unless client
+        return super unless client.configuration.integration_enabled?(:rake)
+
+        Boundary.run(client, kind: :rake, metadata: { "rake" => { "task" => name } }) { super }
+      end
+    end
+
+    def self.install
+      return unless ::Rake::VERSION.start_with?("13.")
+
+      ::Rake::Task.prepend(TaskMethods) unless ::Rake::Task.ancestors.include?(TaskMethods)
+      nil
+    end
+  end
+end
+
+Hawk::Rake.install

data/lib/hawk/release.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Hawk
+  # Git is consulted only during explicit initialization-time detection.
+  module Release
+    def self.detect(configuration)
+      return configuration.release if configuration.release
+      return unless configuration.detect_release
+
+      git_revision
+    end
+
+    def self.git_revision
+      Open3.popen3("git", "rev-parse", "HEAD") do |input, output, _error, waiter|
+        input.close
+        unless waiter.join(1.0)
+          Process.kill("KILL", waiter.pid)
+          waiter.join
+          return nil
+        end
+
+        revision = output.read(128)
+        revision&.strip if waiter.value.success?
+      end
+    rescue SystemCallError, IOError
+      nil
+    end
+  end
+end

data/lib/hawk/resque.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require_relative "../hawk"
+require "resque"
+require "resque/failure"
+
+module Hawk
+  # Resque 2.7 delegates failures to its existing backend without payload changes.
+  module Resque
+    def self.install
+      return unless ::Resque::VERSION == "2.7.0"
+
+      ::Resque::Job.prepend(JobMethods) unless ::Resque::Job.ancestors.include?(JobMethods)
+      singleton = ::Resque::Failure.singleton_class
+      singleton.prepend(FailureMethods) unless singleton.ancestors.include?(FailureMethods)
+    end
+
+    def self.client
+      client = Hawk.client
+      client if client&.enabled? && client.configuration.integration_enabled?(:resque)
+    end
+
+    def self.metadata(client, payload, queue)
+      data = JSONValue.object(payload.slice("class"))
+      data["queue"] = JSONValue.normalize(queue)
+      data["arguments"] = JSONValue.normalize(payload["args"]) if client.configuration.include_job_arguments
+      { "job" => data }
+    end
+
+    def self.run(payload, queue, &)
+      # @type var client: Client?
+      client = self.client
+      return yield unless client
+
+      Boundary.run(client, kind: :resque, metadata: metadata(client, payload, queue), &)
+    ensure
+      client&.flush
+    end
+
+    def self.report_failure(options)
+      client = self.client
+      return unless client
+
+      case error = options[:exception]
+      when Exception
+        return if client.consume_escape(error)
+
+        client.with_boundary(kind: :resque,
+                             metadata: metadata(client, JSONValue.object(options[:payload]), options[:queue])) do
+          client.report(error, mechanism: "resque.backend")
+        end
+      end
+      nil
+    rescue StandardError
+      nil
+    end
+
+    # Flush every completed attempt because Resque may exit children with exit!.
+    module JobMethods
+      def perform
+        Resque.run(payload, queue) { super }
+      end
+    end
+
+    # Failures before perform still reach the configured Resque failure backend.
+    module FailureMethods
+      def create(options = {})
+        Resque.report_failure(options)
+        super
+      ensure
+        Resque.client&.flush
+      end
+    end
+  end
+end
+
+Hawk::Resque.install

data/lib/hawk/scope.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Hawk
+  # Execution data is copied at scope boundaries and before event delivery.
+  class Scope
+    # Identity comparison avoids invoking application exception equality methods.
+    class Ledger
+      def initialize
+        @errors = {}
+        @errors.compare_by_identity
+      end
+
+      def accept(exception, evict: false)
+        return :duplicate if @errors[exception]
+
+        if @errors.size >= 256
+          return :overflow unless evict
+
+          @errors.shift
+        end
+
+        @errors[exception] = true
+        :accepted
+      end
+    end
+
+    attr_reader :context, :user, :anonymous_id
+    attr_accessor :addons, :breadcrumbs, :ledger, :boundary, :request_metadata
+
+    def initialize(context: {}, user: nil, anonymous_id: SecureRandom.uuid)
+      @context = JSONValue.object(context)
+      @user = user ? JSONValue.object(user) : nil
+      @anonymous_id = anonymous_id
+      @addons = {}
+      @breadcrumbs = []
+      @ledger = Ledger.new
+      @boundary = false
+      @request_metadata = nil
+      @filtered_context_keys = {}
+      @filtered_user = false
+    end
+
+    def set_context(context)
+      update_context(context, false)
+    end
+
+    def set_user(user)
+      update_user(user, false)
+    end
+
+    def restore_filtered(context, user)
+      update_context(context, true)
+      update_user(user, true) if user
+      nil
+    end
+
+    def filtered_paths(except_context: [], user_override: false)
+      paths = (@filtered_context_keys.keys - except_context).map { |key| ["context", key] }
+      paths << ["user"] if @filtered_user && !user_override
+      paths << ["breadcrumbs"]
+      paths
+    end
+
+    def event_addons
+      reader = @request_metadata
+      reader ? @addons.merge("request" => reader.call) : @addons
+    end
+
+    def event_data(context, user, default_user, addons)
+      context = JSONValue.object(context)
+      value = JSONValue.object(user || @user || default_user || {})
+      value["id"] ||= @anonymous_id
+      { context: @context.merge(context), user: value, breadcrumbs: @breadcrumbs, addons: event_addons.merge(addons),
+        filtered_paths: filtered_paths(except_context: context.keys, user_override: !user.nil?) }
+    end
+
+    def copy
+      duplicate = Scope.new(context: @context, user: @user, anonymous_id: @anonymous_id)
+      duplicate.addons = JSONValue.object(@addons)
+      duplicate.breadcrumbs = @breadcrumbs.map { |item| JSONValue.object(item) }
+      duplicate.ledger = @ledger
+      duplicate.boundary = @boundary
+      duplicate.request_metadata = @request_metadata
+      duplicate.restore_filtered(@context.slice(*@filtered_context_keys.keys), @filtered_user ? @user : nil)
+      duplicate
+    end
+
+    private
+
+    def update_context(context, filtered)
+      values = JSONValue.object(context)
+      values.each_key do |key|
+        @filtered_context_keys.delete(key)
+        @filtered_context_keys[key] = true if filtered
+      end
+      @context.merge!(values)
+      nil
+    end
+
+    def update_user(user, filtered)
+      @user = user ? JSONValue.object(user) : nil
+      @filtered_user = filtered
+      nil
+    end
+  end
+end

data/lib/hawk/scope_store.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Hawk
+  # Thread#[] stores values per fiber, including fibers sharing one thread.
+  class ScopeStore
+    def initialize(configuration, anonymous_id)
+      @configuration = configuration
+      @anonymous_id = anonymous_id
+      @scope_key = "hawk.scope.#{anonymous_id}"
+      @escape_key = "hawk.escape.#{anonymous_id}"
+    end
+
+    def current
+      # @type var value: top
+      value = Thread.current[@scope_key]
+      case value
+      when Scope then value
+      else
+        scope = Scope.new(context: @configuration.context, user: @configuration.user, anonymous_id: @anonymous_id)
+        replace(scope)
+        scope
+      end
+    end
+
+    def replace(scope)
+      Thread.current[@scope_key] = scope
+      nil
+    end
+
+    def remember_escape(exception)
+      Thread.current[@escape_key] = exception
+      nil
+    end
+
+    def consume_escape(exception)
+      # @type var value: top
+      value = Thread.current[@escape_key]
+      clear_escape
+      case value
+      when Exception then value.equal?(exception)
+      else false
+      end
+    end
+
+    def clear_escape
+      Thread.current[@escape_key] = nil
+      nil
+    end
+
+    def clear
+      Thread.current[@scope_key] = nil
+      clear_escape
+    end
+  end
+end

data/lib/hawk/sidekiq.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require_relative "../hawk"
+require "sidekiq"
+
+module Hawk
+  # Native middleware covers each backend attempt, including pre-execution errors.
+  module Sidekiq
+    def self.install
+      return unless ::Sidekiq::VERSION.match?(/\A[78]\./)
+
+      ::Sidekiq.configure_client { |config| register_client(config) }
+      ::Sidekiq.configure_server { |config| register(config) }
+    end
+
+    def self.register_client(config)
+      config.client_middleware { |chain| chain.add(ClientMiddleware) }
+    end
+
+    def self.register(config)
+      register_client(config)
+      config.server_middleware { |chain| chain.add(ServerMiddleware) }
+      config.error_handlers << ERROR_HANDLER unless config.error_handlers.include?(ERROR_HANDLER)
+    end
+
+    def self.client
+      client = Hawk.client
+      client if client&.enabled? && client.configuration.integration_enabled?(:sidekiq)
+    end
+
+    def self.metadata(client, job)
+      result = JSONValue.object(job.slice("class", "jid", "queue", "retry_count"))
+      result["arguments"] = JSONValue.normalize(job["args"]) if client.configuration.include_job_arguments
+      result
+    end
+
+    # Enqueue context uses Sidekiq's supported top-level metadata channel.
+    class ClientMiddleware
+      def call(_worker, job, _queue, _redis_pool = nil)
+        client = Sidekiq.client
+        context = JobContext.dump(client) if client
+        job["hawk"] = context if context
+        yield
+      end
+    end
+
+    # Middleware delegates retries and acknowledgement to Sidekiq.
+    class ServerMiddleware
+      def call(_worker, job, _queue)
+        client = Sidekiq.client
+        return yield unless client
+
+        Boundary.run(client, kind: :sidekiq, metadata: { "job" => Sidekiq.metadata(client, job) }) do
+          JobContext.apply(client, job["hawk"])
+          yield
+        end
+      end
+    end
+
+    # The execution marker is consumed only by this client's outer error handler.
+    class ErrorHandler
+      def call(error, context, _config = nil)
+        client = Sidekiq.client
+        return unless client
+        return if client.consume_escape(error)
+
+        job = JSONValue.object(context[:job])
+        client.with_boundary(kind: :sidekiq, metadata: { "job" => Sidekiq.metadata(client, job) }) do
+          JobContext.apply(client, job["hawk"])
+          client.report(error, mechanism: "sidekiq.backend")
+        end
+        nil
+      end
+    end
+
+    ERROR_HANDLER = ErrorHandler.new
+  end
+end
+
+Hawk::Sidekiq.install