hawk-ruby 0.1.1 → 0.1.2

data/lib/hawk/configuration.rb

@@ -2,16 +2,193 @@
 
 module Hawk
   # Settings are validated before clients install handlers or start delivery.
+  # Configure settings before calling {Hawk.init} or {Client.build}.
+  # @see file:docs/configuration.md Configuration guide
   class Configuration
-    attr_accessor :token, :endpoint, :environment, :enabled_environments, :release, :detect_release,
-                  :sample_rate, :delivery_mode, :queue_capacity, :source_roots, :send_source,
-                  :connect_timeout, :read_timeout, :write_timeout, :flush_timeout, :limit_cooldown,
-                  :context, :user, :ignored_exceptions, :filter_parameters, :integrations, :global_errors,
-                  :before_send, :before_breadcrumb, :framework_filter, :diagnostic_callback, :diagnostic_logger,
-                  :propagate_job_context,
-                  :include_request_body, :include_job_arguments, :include_headers, :include_cookies,
-                  :breadcrumbs_logger, :breadcrumbs_http, :breadcrumbs_rails, :logger_error_level
+    # Project integration token. Defaults to ENV["HAWK_TOKEN"]; nil or empty disables capture.
+    #
+    # @return [String, nil]
+    attr_accessor :token
 
+    # Collector URL override. Defaults to the token-derived endpoint; permits HTTPS or loopback HTTP.
+    #
+    # @return [String, nil]
+    attr_accessor :endpoint
+
+    # Event environment. Defaults to RAILS_ENV, RACK_ENV, or "development", in that order.
+    #
+    # @return [String]
+    attr_accessor :environment
+
+    # Environments that permit capture. Defaults to nil, which permits all environments.
+    #
+    # @return [Array<String>, nil]
+    attr_accessor :enabled_environments
+
+    # Application revision. Defaults to HAWK_RELEASE or REVISION.
+    #
+    # @return [String, nil]
+    attr_accessor :release
+
+    # Detect the Git revision at initialization when release is unset. Defaults to false.
+    #
+    # @return [Boolean]
+    attr_accessor :detect_release
+
+    # Capture probability from 0.0 through 1.0. Defaults to 1.0.
+    #
+    # @return [Float]
+    attr_accessor :sample_rate
+
+    # Delivery policy: :async queues events; :sync sends in the caller. Defaults to :async.
+    #
+    # @return [Symbol]
+    attr_accessor :delivery_mode
+
+    # Maximum waiting events, as a positive integer. Defaults to 100.
+    #
+    # @return [Integer]
+    attr_accessor :queue_capacity
+
+    # Allowed roots for source snippets. Defaults to [Dir.pwd].
+    #
+    # @return [Array<String>]
+    attr_accessor :source_roots
+
+    # Include bounded source snippets from source_roots. Defaults to true.
+    #
+    # @return [Boolean]
+    attr_accessor :send_source
+
+    # Nonnegative connection timeout in seconds. Defaults to 1.0.
+    #
+    # @return [Numeric]
+    attr_accessor :connect_timeout
+
+    # Nonnegative socket read timeout in seconds. Defaults to 2.0.
+    #
+    # @return [Numeric]
+    attr_accessor :read_timeout
+
+    # Nonnegative socket write timeout in seconds. Defaults to 2.0.
+    #
+    # @return [Numeric]
+    attr_accessor :write_timeout
+
+    # Nonnegative flush and close deadline in seconds. Defaults to 5.0.
+    #
+    # @return [Numeric]
+    attr_accessor :flush_timeout
+
+    # Nonnegative fallback cooldown after collector limits, in seconds. Defaults to 60.0.
+    #
+    # @return [Numeric]
+    attr_accessor :limit_cooldown
+
+    # Initial context for execution scopes. Defaults to an empty hash.
+    #
+    # @return [Hash{String, Symbol => Object}]
+    attr_accessor :context
+
+    # Initial user data, preferably with an :id. Defaults to nil.
+    #
+    # @return [Hash{String, Symbol => Object}, nil]
+    attr_accessor :user
+
+    # Exception ancestor names excluded from capture. Defaults to an empty array.
+    #
+    # @return [Array<String>]
+    attr_accessor :ignored_exceptions
+
+    # Sensitive key patterns added to built-in filters. Defaults to an empty array.
+    #
+    # @return [Array<String, Regexp>]
+    attr_accessor :filter_parameters
+
+    # Integration switches. Unspecified integrations are enabled; defaults to an empty hash.
+    #
+    # @return [Hash{Symbol => Boolean}]
+    attr_accessor :integrations
+
+    # Install uncaught main-process exception capture and exit draining. Defaults to true.
+    #
+    # @return [Boolean]
+    attr_accessor :global_errors
+
+    # Receives a detached, filtered event hash without the token. Returns a hash to send or nil to
+    # drop. Defaults to nil.
+    #
+    # @return [#call, nil]
+    attr_accessor :before_send
+
+    # Receives a detached, filtered breadcrumb hash. Returns a hash to retain or nil to drop.
+    # Defaults to nil.
+    #
+    # @return [#call, nil]
+    attr_accessor :before_breadcrumb
+
+    # Framework filter receiving a payload hash and returning a hash or nil. Defaults to nil.
+    #
+    # @return [#call, nil]
+    attr_accessor :framework_filter
+
+    # Receives counter snapshots as `Hash{Symbol => Integer}`. Defaults to nil; return values are
+    # ignored.
+    #
+    # @return [#call, nil]
+    attr_accessor :diagnostic_callback
+
+    # Receives sanitized warnings containing counters without event data. Defaults to nil.
+    #
+    # @return [#warn, nil]
+    attr_accessor :diagnostic_logger
+
+    # Propagate explicit context and user through supported job adapters. Defaults to true.
+    #
+    # @return [Boolean]
+    attr_accessor :propagate_job_context
+
+    # Include already available request bodies without reading the input stream. Defaults to false.
+    #
+    # @return [Boolean]
+    attr_accessor :include_request_body
+
+    # Include job arguments in captured metadata. Defaults to false.
+    #
+    # @return [Boolean]
+    attr_accessor :include_job_arguments
+
+    # Include request headers, excluding cookies. Defaults to false.
+    #
+    # @return [Boolean]
+    attr_accessor :include_headers
+
+    # Include request cookies in their dedicated field. Defaults to false.
+    #
+    # @return [Boolean]
+    attr_accessor :include_cookies
+
+    # Install automatic Logger breadcrumbs. Defaults to false.
+    #
+    # @return [Boolean]
+    attr_accessor :breadcrumbs_logger
+
+    # Install automatic Net::HTTP breadcrumbs. Defaults to false.
+    #
+    # @return [Boolean]
+    attr_accessor :breadcrumbs_http
+
+    # Enable Rails notification breadcrumbs when Rails is active. Defaults to true.
+    #
+    # @return [Boolean]
+    attr_accessor :breadcrumbs_rails
+
+    # Minimum Logger severity converted into events. Defaults to nil, which disables conversion.
+    #
+    # @return [Integer, nil]
+    attr_accessor :logger_error_level
+
+    # Creates settings with environment-derived identity and bounded delivery defaults.
     def initialize
       initialize_identity
       initialize_delivery
@@ -19,6 +196,10 @@ module Hawk
       initialize_hooks
     end
 
+    # Validates token, collector URL, delivery limits, sampling, and callable hooks.
+    #
+    # @return [nil]
+    # @raise [ConfigurationError] if a checked setting is invalid
     def validate!
       value = @token
       Token.decode(value) if value && !value.empty?
@@ -32,12 +213,18 @@ module Hawk
       nil
     end
 
+    # @return [Boolean] whether a nonempty token and the environment permit capture
+    # @note This check does not validate the token.
     def enabled?
       value = @token
       environments = @enabled_environments
       !!(value && !value.empty? && (environments.nil? || environments.include?(@environment)))
     end
 
+    # Resolves the configured collector URL or derives one from the token.
+    #
+    # @return [URI::HTTP, URI::HTTPS] collector URI
+    # @raise [ConfigurationError] if the token or URL is invalid
     def collector_uri
       override = @endpoint
       return Token.decode(@token || "").endpoint unless override
@@ -50,6 +237,8 @@ module Hawk
       raise ConfigurationError, "Invalid collector endpoint"
     end
 
+    # @param name [Symbol] integration key, such as :rack or :sidekiq
+    # @return [Boolean] configured switch, or true when unspecified
     def integration_enabled?(name)
       @integrations.fetch(name, true)
     end

data/lib/hawk/delayed_job.rb

@@ -1,11 +1,12 @@
 # frozen_string_literal: true
 
-require_relative "../hawk"
+require_relative "../hawk" unless defined?(Hawk.init)
 require "delayed_job"
 require "delayed/plugin"
 
 module Hawk
   # Native lifecycle callbacks retain retries, payloads, and failure storage.
+  # @api private
   module DelayedJob
     def self.install
       return unless supported_version?

data/lib/hawk/delivery.rb

@@ -2,6 +2,7 @@
 
 module Hawk
   # Queue capacity never blocks capture; flush and close have explicit deadlines.
+  # @api private
   class Delivery
     def initialize(configuration, transport:, diagnostics:)
       @configuration = configuration

data/lib/hawk/diagnostics.rb

@@ -3,12 +3,14 @@
 module Hawk
   # Counters and callbacks contain no event data or collector credentials.
   class Diagnostics
+    # @api private
     def initialize(callback = nil, logger: nil)
       @callback = callback
       @logger = logger
       reset
     end
 
+    # @api private
     def increment(name)
       reset if @pid != Process.pid
       @mutex.synchronize { @counts[name] = @counts.fetch(name, 0) + 1 }
@@ -16,6 +18,12 @@ module Hawk
       nil
     end
 
+    # Returns a thread-safe copy of observed counters.
+    #
+    # Absent counters have not been incremented. Forked children start fresh counts.
+    #
+    # @return [Hash{Symbol => Integer}] counts such as :sent, :failed, :overflow,
+    #   :filtered, and :duplicate_overflow
     def snapshot
       reset if @pid != Process.pid
       @mutex.synchronize { @counts.dup }

data/lib/hawk/event.rb

@@ -2,6 +2,7 @@
 
 module Hawk
   # Builds the native protocol payload; hooks never receive integration tokens.
+  # @api private
   class Event
     def initialize(configuration:, id:, exception: nil, message: nil, context: {}, user: nil,
                    breadcrumbs: [], addons: {}, level: :error, filtered_paths: [])

data/lib/hawk/filter.rb

@@ -2,6 +2,7 @@
 
 module Hawk
   # Filters detached JSON data before hooks or transmission can observe it.
+  # @api private
   class Filter
     SENSITIVE = /password|secret|passwd|api_?key|access_token|auth|credentials|mysql_pwd|stripetoken|card/i
 

data/lib/hawk/filtered_fields.rb

@@ -2,6 +2,7 @@
 
 module Hawk
   # Empty placeholders retain parent/key masking while excluding saved contents.
+  # @api private
   class FilteredFields
     def initialize(payload, paths, containers_only: false)
       @entries = []

data/lib/hawk/framework_filter.rb

@@ -2,6 +2,7 @@
 
 module Hawk
   # Previously filtered fields cross later boundaries without another transform.
+  # @api private
   module FrameworkFilter
     def self.call(configuration, payload, filtered_paths = [])
       filter = configuration.framework_filter

data/lib/hawk/hook.rb

@@ -2,6 +2,7 @@
 
 module Hawk
   # User callbacks must not change application control flow or stop delivery.
+  # @api private
   module Hook
     def self.call(&)
       Breadcrumbs.guard(:sdk, &)

data/lib/hawk/integrations.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Hawk
+  # Discovers frameworks already loaded by the application during startup.
+  # @api private
+  module Integrations
+    def self.load
+      require_relative "rails/integration" if defined?(::Rails::Railtie)
+      require_relative "sidekiq" if defined?(::Sidekiq)
+      require_relative "resque" if defined?(::Resque)
+      require_relative "delayed_job" if defined?(::Delayed::Worker)
+      require_relative "rake" if defined?(::Rake::Task)
+      nil
+    end
+  end
+end

data/lib/hawk/job_context.rb

@@ -2,6 +2,7 @@
 
 module Hawk
   # Only explicit, filtered JSON context crosses a queue boundary.
+  # @api private
   module JobContext
     def self.dump(client)
       return unless client.configuration.propagate_job_context

data/lib/hawk/json_value.rb

@@ -2,6 +2,7 @@
 
 module Hawk
   # Copies boundary data into a bounded JSON tree without custom serializers.
+  # @api private
   class JSONValue
     def self.normalize(value)
       new.visit(value, 0)

data/lib/hawk/process_hooks.rb

@@ -2,6 +2,7 @@
 
 module Hawk
   # Resolving the client at shutdown keeps repeated initialization idempotent.
+  # @api private
   module ProcessHooks
     def self.install
       return if @installed

data/lib/hawk/rack/body.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Hawk
+  # @api private
   class Rack
     # Guards establish each foreign protocol before its type is narrowed.
     class Body

data/lib/hawk/rack.rb

@@ -1,16 +1,30 @@
 # frozen_string_literal: true
 
-require_relative "../hawk"
+require_relative "../hawk" unless defined?(Hawk.init)
 
 module Hawk
   # Request scope covers application calls and the deferred response body.
+  # Rack middleware reporting application and deferred response-body errors.
+  #
+  # @example Add to config.ru
+  #   require "hawk-ruby"
+  #   use Hawk::Rack
+  #   run app
   class Rack
+    # @param app [#call] downstream Rack application
+    # @param client [Client, nil] explicit client; nil uses Hawk.client for each request
+    # @param integration [Symbol] configuration switch controlling capture
     def initialize(app, client: nil, integration: :rack)
       @app = app
       @client = client
       @integration = integration
     end
 
+    # Runs the application in a fresh request scope when capture is enabled.
+    #
+    # @param env [Hash{String => Object}] Rack request environment
+    # @return [Array(Integer, Hash, #each)] Rack response with a monitored body
+    # @raise [Exception] application exceptions, after reporting when eligible
     def call(env)
       client = active_client
       return @app.call(env) unless client

data/lib/hawk/rails/action_cable.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Hawk
+  # @api private
   module Rails
     # These wrappers match Rails 7.2, 8.0, and 8.1 lifecycle methods.
     module ActionCable

data/lib/hawk/rails/active_job.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Hawk
+  # @api private
   module Rails
     # Active Job owns retry decisions; Hawk observes escaping and terminal errors.
     module ActiveJob

data/lib/hawk/rails/error_subscriber.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Hawk
+  # @api private
   module Rails
     # Rails owns subscriber lifetime; each report resolves the current client.
     class ErrorSubscriber

data/lib/hawk/rails/integration.rb

@@ -10,6 +10,7 @@ require_relative "../breadcrumbs/rails"
 
 module Hawk
   # Framework filtering is injected without changing the user's before_send hook.
+  # @api private
   module Rails
     def self.configure(configuration)
       return unless configuration.integration_enabled?(:rails)
@@ -35,9 +36,6 @@ module Hawk
       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

data/lib/hawk/rails/payload_filter.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Hawk
+  # @api private
   module Rails
     # Rails deep filters and original-params blocks need each logical tree root.
     class PayloadFilter

data/lib/hawk/rake.rb

@@ -1,10 +1,11 @@
 # frozen_string_literal: true
 
-require_relative "../hawk"
+require_relative "../hawk" unless defined?(Hawk.init)
 require "rake"
 
 module Hawk
   # Optional task capture delegates execution and preserves application errors.
+  # @api private
   module Rake
     # Prepended to tasks without replacing their original execute implementation.
     module TaskMethods

data/lib/hawk/release.rb

@@ -4,6 +4,7 @@ require "open3"
 
 module Hawk
   # Git is consulted only during explicit initialization-time detection.
+  # @api private
   module Release
     def self.detect(configuration)
       return configuration.release if configuration.release

data/lib/hawk/resque.rb

@@ -1,11 +1,12 @@
 # frozen_string_literal: true
 
-require_relative "../hawk"
+require_relative "../hawk" unless defined?(Hawk.init)
 require "resque"
 require "resque/failure"
 
 module Hawk
   # Resque 2.7 delegates failures to its existing backend without payload changes.
+  # @api private
   module Resque
     def self.install
       return unless ::Resque::VERSION == "2.7.0"

data/lib/hawk/scope.rb

@@ -4,8 +4,10 @@ require "securerandom"
 
 module Hawk
   # Execution data is copied at scope boundaries and before event delivery.
+  # Mutable execution data yielded by {Hawk.with_scope} and {Client#with_scope}.
   class Scope
     # Identity comparison avoids invoking application exception equality methods.
+    # @api private
     class Ledger
       def initialize
         @errors = {}
@@ -26,9 +28,18 @@ module Hawk
       end
     end
 
-    attr_reader :context, :user, :anonymous_id
+    # @return [Hash{String => Object}] copied context for this execution
+    attr_reader :context
+
+    # @return [Hash{String => Object}, nil] copied user data for this execution
+    attr_reader :user
+
+    # @return [String] fallback user identifier retained across copies of this scope
+    attr_reader :anonymous_id
+    # @api private
     attr_accessor :addons, :breadcrumbs, :ledger, :boundary, :request_metadata
 
+    # @api private
     def initialize(context: {}, user: nil, anonymous_id: SecureRandom.uuid)
       @context = JSONValue.object(context)
       @user = user ? JSONValue.object(user) : nil
@@ -42,20 +53,30 @@ module Hawk
       @filtered_user = false
     end
 
+    # Merges copied context, replacing matching top-level keys.
+    #
+    # @param context [Hash{String, Symbol => Object}] application context
+    # @return [void]
     def set_context(context)
       update_context(context, false)
     end
 
+    # Replaces the scoped user with copied data; nil clears it.
+    #
+    # @param user [Hash{String, Symbol => Object}, nil] user data
+    # @return [void]
     def set_user(user)
       update_user(user, false)
     end
 
+    # @api private
     def restore_filtered(context, user)
       update_context(context, true)
       update_user(user, true) if user
       nil
     end
 
+    # @api private
     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
@@ -63,11 +84,13 @@ module Hawk
       paths
     end
 
+    # @api private
     def event_addons
       reader = @request_metadata
       reader ? @addons.merge("request" => reader.call) : @addons
     end
 
+    # @api private
     def event_data(context, user, default_user, addons)
       context = JSONValue.object(context)
       value = JSONValue.object(user || @user || default_user || {})
@@ -76,6 +99,7 @@ module Hawk
         filtered_paths: filtered_paths(except_context: context.keys, user_override: !user.nil?) }
     end
 
+    # @api private
     def copy
       duplicate = Scope.new(context: @context, user: @user, anonymous_id: @anonymous_id)
       duplicate.addons = JSONValue.object(@addons)

data/lib/hawk/scope_store.rb

@@ -2,6 +2,7 @@
 
 module Hawk
   # Thread#[] stores values per fiber, including fibers sharing one thread.
+  # @api private
   class ScopeStore
     def initialize(configuration, anonymous_id)
       @configuration = configuration

data/lib/hawk/sidekiq.rb

@@ -1,10 +1,11 @@
 # frozen_string_literal: true
 
-require_relative "../hawk"
+require_relative "../hawk" unless defined?(Hawk.init)
 require "sidekiq"
 
 module Hawk
   # Native middleware covers each backend attempt, including pre-execution errors.
+  # @api private
   module Sidekiq
     def self.install
       return unless ::Sidekiq::VERSION.match?(/\A[78]\./)

data/lib/hawk/source.rb

@@ -2,6 +2,7 @@
 
 module Hawk
   # Backtraces remain useful when source files are unavailable or excluded.
+  # @api private
   class Source
     def initialize(configuration)
       @enabled = configuration.send_source

data/lib/hawk/token.rb

@@ -5,9 +5,11 @@ require "json"
 require "uri"
 
 module Hawk
+  # Raised when client configuration or its integration token is invalid.
   class ConfigurationError < ArgumentError; end
 
   # Resolves collector identity without exposing the integration secret.
+  # @api private
   class Token
     LABEL = /\A[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\z/i
 

data/lib/hawk/transport.rb

@@ -6,6 +6,7 @@ require "time"
 
 module Hawk
   # Every send performs at most one POST, with a bounded response and deadline.
+  # @api private
   class Transport
     class ResponseTooLarge < StandardError; end
 

data/lib/hawk/version.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
 module Hawk
-  VERSION = "0.1.1"
+  # Gem release version.
+  # @return [String]
+  VERSION = "0.1.2"
 end

data/lib/hawk-ruby.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "hawk"