hawk-ruby 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a9a71442090adcd7b76fdf5ea4de73e23c32dd4fd1d2c16320b6bea56cb8f729
-  data.tar.gz: 3a5be0475ee73759a6413a7ab1883892a08562c2f683bd1f5973276aab542207
+  metadata.gz: 6567a3e5fc62ed4b72b2b03e1510158c6647018a5cf76e5ed3c1e4c500ff79b4
+  data.tar.gz: 5f75aa16ce1cff05c46fd68f0f0e315572c8924dabd9be8816d883ed0056ce22
 SHA512:
-  metadata.gz: 7eb5a415bc25de6ecbb8febc98d950dcc1a7af93efaf62d54ca3b00edd9a18933c8b0b4a5f0de3631c80f362df19704d48f23770f738e0576e4223ff8bad62d2
-  data.tar.gz: 9fd1d563a3e681d6919d18cc505b755a0b9469d8fc90fc2e66bc97f8a7466e4a145da2a1e2678c305f444a8cb6f433390115bc58bed3524e3c4a24c68496d276
+  metadata.gz: 800b94ebf049946ee15db9436f7297d971113d7976eb57eeda80ba3a2aeebeab8f20d219edc5dac1d19816753737f23cfc2f32227df69925bcd25f88f3de0763
+  data.tar.gz: 163ff6fc81f90b47ff0cb8431dbfd4dbe2249bcde6e6f2824e94de7afa9ef0d39b365afa0ee816a6ff37cbdcba0cf20f5202fa7a8ae9a6bcf3c5e4f6fc926ed3

data/CHANGELOG.md

@@ -6,6 +6,13 @@ Versions follow [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html)
 
 ## [Unreleased]
 
+## [0.1.2] - 2026-10-30
+
+### Added
+
+- Support standard Bundler loading without a custom `require:` option.
+- Detect loaded Rails, Rake, Sidekiq, Resque, and Delayed Job integrations during startup.
+
 ## [0.1.1] - 2026-10-29
 
 ### Added
@@ -30,6 +37,7 @@ Initial release of the Hawk Ruby error reporting gem.
 - Provide bounded asynchronous delivery, execution-local scopes, duplicate suppression, fork recovery, privacy filters, and event hooks.
 - Ship RBS signatures and enforce complete type coverage, 100% line and branch coverage, and measured CRAP scores no greater than 10.
 
-[Unreleased]: https://github.com/svyatov/hawk.ruby/compare/v0.1.1...HEAD
+[Unreleased]: https://github.com/svyatov/hawk.ruby/compare/v0.1.2...HEAD
+[0.1.2]: https://github.com/svyatov/hawk.ruby/compare/v0.1.1...v0.1.2
 [0.1.1]: https://github.com/svyatov/hawk.ruby/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/svyatov/hawk.ruby/releases/tag/v0.1.0

data/README.md

@@ -12,13 +12,13 @@ Ruby error reporting for [Hawk](https://hawk.so), with optional Rails and backgr
 Run this command from your application's directory, which must contain a Gemfile:
 
 ```sh
-bundle add hawk-ruby --version "~> 0.1.1" --require hawk
+bundle add hawk-ruby --version "~> 0.1.2"
 ```
 
 Copy the integration token from your Hawk project into `HAWK_TOKEN`. Save this example as `report.rb`:
 
 ```ruby
-require "hawk"
+require "hawk-ruby"
 
 Hawk.init do |config|
   config.token = ENV.fetch("HAWK_TOKEN")
@@ -47,24 +47,24 @@ A missing or empty token disables reporting. A malformed nonempty token raises `
 
 ## Rails and background jobs
 
-Use `require: "hawk/rails"` in your Gemfile for Rails. Initialize Hawk in `config/initializers/hawk.rb` before workers start.
-
-Rails enables request capture, `Rails.error`, Action Cable, Active Job, and safe notification breadcrumbs. Solid Queue works through Active Job.
-
-Add the relevant adapter requires to your application's startup file:
+Use the standard Gemfile entry without a `require:` option. Initialize Hawk in `config/initializers/hawk.rb` before workers start:
 
 ```ruby
-require "hawk/rack"
-require "hawk/rake"
-require "hawk/sidekiq"
-require "hawk/resque"
-require "hawk/delayed_job"
+Hawk.init do |config|
+  config.token = ENV.fetch("HAWK_TOKEN")
+end
 ```
 
-Rails also detects loaded job backends during initialization. The adapters preserve native retries, arguments, and failure storage.
+Rails enables request capture, `Rails.error`, Action Cable, Active Job, and safe notification breadcrumbs. Solid Queue works through Active Job.
+
+Hawk automatically detects loaded Rails, Rake, Sidekiq, Resque, and Delayed Job integrations during startup. Load application dependencies before calling `Hawk.init`. No adapter requires are needed.
+
+For a standalone Rack application, add `use Hawk::Rack` to `config.ru`. Rails inserts this middleware automatically. The adapters preserve native retries, arguments, and failure storage.
 
 See [integrations](docs/integrations.md) for placement, supported versions, propagation limits, and exclusions.
 
+See [configuration](docs/configuration.md) for settings and [API documentation](CONTRIBUTING.md#api-documentation) to build the YARD reference.
+
 ## Delivery and privacy
 
 The default client uses one background thread and a queue of 100 events. Capture never waits for queue space. Each delivery makes one bounded HTTP attempt.
@@ -79,6 +79,7 @@ Source snippets are enabled within configured source roots. Set `send_source = f
 
 ```sh
 bundle exec rake check:fast
+bundle exec rake check:docs
 bundle exec rake check:coverage
 bundle exec rake check:crap
 bundle exec rake check:audit

data/docs/api.md

@@ -0,0 +1,25 @@
+# Hawk Ruby API
+
+Hawk Ruby reports exceptions and messages to Hawk. Start with {Hawk} for the default client or {Hawk::Client} for independent project clients.
+
+```ruby
+require "hawk"
+
+Hawk.init { |config| config.token = ENV.fetch("HAWK_TOKEN") }
+Hawk.capture_message("Checkout completed", context: { order_id: "42" })
+Hawk.close(timeout: 5.0)
+```
+
+Capture IDs confirm local acceptance. They do not confirm receipt by Hawk. Flush and close wait for delivery attempts, including failed attempts.
+
+## Reference
+
+- {Hawk::Configuration} documents settings, types, and defaults.
+- {Hawk::Scope} holds context and user data for an execution.
+- {Hawk::Diagnostics} exposes delivery and filtering counters.
+- {Hawk::Rack} captures request and response-body exceptions.
+- {Hawk::ConfigurationError} identifies invalid configuration.
+
+See the {file:docs/configuration.md configuration guide} for privacy, delivery, and hook behavior. See the {file:docs/integrations.md integration guide} for Rails and background jobs.
+
+Methods marked `@api private` support the implementation and are omitted from this reference. Their Ruby visibility does not make them supported extension points.

data/docs/integrations.md

@@ -1,6 +1,10 @@
 # Integrations
 
-Load optional adapters before workers start. Keep their framework gems in the application's Gemfile.
+Keep framework gems in the application's Gemfile. Hawk detects loaded frameworks when it loads and when you call `Hawk.init`.
+
+Load application dependencies before initializing Hawk, and initialize before workers start. Frameworks loaded after initialization are not automatically detected. Hawk does not load unused frameworks.
+
+Use `gem "hawk-ruby"` without a `require:` option. Explicit `require "hawk"` and adapter-specific requires remain supported for existing applications.
 
 ## Supported versions
 
@@ -22,7 +26,7 @@ The adapters guard their supported framework versions. Resque activation require
 ## Rack
 
 ```ruby
-require "hawk/rack"
+require "hawk-ruby"
 
 Hawk.init { |config| config.token = ENV.fetch("HAWK_TOKEN") }
 use Hawk::Rack
@@ -39,7 +43,7 @@ Use `Hawk::Rack.new(app, client: other_client)` for an independent project clien
 
 ## Rails requests and framework reports
 
-Use `require: "hawk/rails"` in your Gemfile. The Railtie inserts Hawk inside `ActionDispatch::DebugExceptions`.
+Rails loads Hawk through Bundler without a custom `require:` option. The Railtie inserts Hawk inside `ActionDispatch::DebugExceptions`.
 
 ```ruby
 # config/initializers/hawk.rb
@@ -50,7 +54,7 @@ Hawk.init do |config|
 end
 ```
 
-If Rails is already loaded, requiring `hawk` also discovers its Railtie. Rails filtering runs before the application's `before_send` hook.
+Load Hawk during Rails boot, before application initialization. Rails filtering runs before the application's `before_send` hook.
 
 The subscriber records explicit `Rails.error.report` calls, including handled errors and severity. Request dispatch reports share ownership with middleware to prevent duplicates.
 
@@ -92,9 +96,7 @@ Solid Queue uses this same Active Job contract. Tests exercise its database-back
 
 ## Sidekiq
 
-```ruby
-require "hawk/sidekiq"
-```
+Hawk automatically activates the adapter when Sidekiq is loaded before Hawk initialization.
 
 Client middleware adds versioned context under a separate top-level `hawk` field. Server middleware starts an execution scope.
 
@@ -106,9 +108,7 @@ The adapter retains native payload arguments and retry behavior. Raw arguments r
 
 ## Resque
 
-```ruby
-require "hawk/resque"
-```
+Hawk automatically activates the adapter when Resque is loaded before Hawk initialization.
 
 The adapter wraps job execution and delegates failure creation to the configured backend. Failed constantization and other failures before execution reach that backend path.
 
@@ -120,11 +120,7 @@ Active Job wrappers retain their own serialized context. Raw direct arguments re
 
 ## Delayed Job
 
-```ruby
-require "hawk/delayed_job"
-```
-
-Load the adapter before starting a worker. Its plugin observes perform, error, and failure callbacks, including handler deserialization failures.
+Hawk automatically activates the adapter when Delayed Job is loaded before Hawk initialization. Its plugin observes perform, error, and failure callbacks, including handler deserialization failures.
 
 Native attempts, retry times, and terminal failure state remain unchanged. Direct job YAML and database columns remain unchanged.
 
@@ -132,11 +128,7 @@ Active Job wrappers carry their own versioned context. Direct jobs start fresh s
 
 ## Rake and process shutdown
 
-```ruby
-require "hawk/rake"
-```
-
-The Rake adapter reports escaping task failures and retains original task behavior. Nested task failures share automatic-report ownership.
+Hawk automatically activates the adapter when Rake is loaded before Hawk initialization. The adapter reports escaping task failures and retains original task behavior. Nested task failures share automatic-report ownership.
 
 Core initialization installs one process exit hook when `global_errors` is enabled. It reports eligible uncaught main-process errors and attempts a bounded drain.
 

data/docs/releasing.md

@@ -9,11 +9,11 @@ The workflow builds the gem once, inventories its packaged files and external ru
 To cut a version:
 
 1. Update the version, changelog, and installation example. Run the checks and merge to `main`.
-2. Create a signed version tag, for example `git tag -s v0.1.1 -m 'Release 0.1.1'`.
-3. Push the tag with `git push origin v0.1.1` and monitor the Release workflow.
+2. Create a signed version tag, for example `git tag -s v0.1.2 -m 'Release 0.1.2'`.
+3. Push the tag with `git push origin v0.1.2` and monitor the Release workflow.
 4. Review the successful build and approve the `release` environment deployment.
 
-To verify downloaded release assets, run `gh attestation verify hawk-ruby-0.1.1.gem --repo svyatov/hawk.ruby --signer-workflow svyatov/hawk.ruby/.github/workflows/release.yml`, then repeat for `sbom.cdx.json`. Run `sha256sum --check SHA256SUMS` from the download directory. RubyGems serves its gem attestation at `https://rubygems.org/api/v1/attestations/hawk-ruby-0.1.1.json`.
+To verify downloaded release assets, run `gh attestation verify hawk-ruby-0.1.2.gem --repo svyatov/hawk.ruby --signer-workflow svyatov/hawk.ruby/.github/workflows/release.yml`, then repeat for `sbom.cdx.json`. Run `sha256sum --check SHA256SUMS` from the download directory. RubyGems serves its gem attestation at `https://rubygems.org/api/v1/attestations/hawk-ruby-0.1.2.json`.
 
 ## Recover a partial publication
 

data/lib/hawk/boundary.rb

@@ -2,6 +2,7 @@
 
 module Hawk
   # Adapters share report ownership while retaining their own execution scopes.
+  # @api private
   module Boundary
     def self.run(client, kind:, metadata:, inherit: false, &block)
       client.with_boundary(kind: kind, metadata: metadata, inherit: inherit) do

data/lib/hawk/breadcrumbs/logger.rb

@@ -3,6 +3,7 @@
 require "logger"
 
 module Hawk
+  # @api private
   module Breadcrumbs
     # Logger keeps control of level filtering and lazy block evaluation.
     module Logger

data/lib/hawk/breadcrumbs/net_http.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Hawk
+  # @api private
   module Breadcrumbs
     # Guard Net::HTTP's internal recursion while retaining the response block API.
     module NetHTTP

data/lib/hawk/breadcrumbs/rails.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Hawk
+  # @api private
   module Breadcrumbs
     # Notification payloads are intentionally excluded from automatic breadcrumbs.
     module Rails

data/lib/hawk/breadcrumbs.rb

@@ -2,6 +2,7 @@
 
 module Hawk
   # Breadcrumb buffers belong to scopes; instrumentation guards belong to fibers.
+  # @api private
   module Breadcrumbs
     def self.install(configuration)
       if configuration.breadcrumbs_logger || configuration.logger_error_level

data/lib/hawk/client.rb

@@ -1,16 +1,36 @@
 # frozen_string_literal: true
 
 module Hawk
-  # Owns policy and scope state; delivery receives detached JSON strings.
+  # Reports events for one project with independent delivery and execution scopes.
+  #
+  # Use {.build} to construct a client with the standard transport.
+  # Capture methods isolate reporting failures from application control flow.
+  #
+  # @example Report to another project
+  #   config = Hawk::Configuration.new
+  #   config.token = ENV.fetch("OTHER_HAWK_TOKEN")
+  #   client = Hawk::Client.build(config)
+  #   client.capture_message("Import completed")
+  #   client.close
   class Client
-    attr_reader :configuration, :diagnostics
+    # @return [Configuration] validated settings; configure before building the client
+    attr_reader :configuration
 
+    # @return [Diagnostics] delivery and filtering counters
+    attr_reader :diagnostics
+
+    # Builds a client with the standard HTTP transport and delivery queue.
+    #
+    # @param configuration [Configuration] settings to validate and retain
+    # @return [Client]
+    # @raise [ConfigurationError] if configuration is invalid
     def self.build(configuration)
       diagnostics = Diagnostics.new(configuration.diagnostic_callback, logger: configuration.diagnostic_logger)
       delivery = Delivery.new(configuration, transport: Transport.new(configuration), diagnostics: diagnostics)
       new(configuration, delivery: delivery, diagnostics: diagnostics)
     end
 
+    # @api private
     def initialize(configuration, delivery:, diagnostics: nil)
       configuration.validate!
       configuration.release = Release.detect(configuration)
@@ -22,22 +42,47 @@ module Hawk
       @closed = false
     end
 
+    # @return [Scope] mutable scope for this client, thread, and fiber
     def current_scope
       @store.current
     end
 
+    # @return [Boolean] whether the client is open and enabled for this environment
     def enabled?
       !@closed && @configuration.enabled?
     end
 
+    # Merges values into the current scope, replacing matching top-level keys.
+    #
+    # Values are copied into bounded JSON data without calling custom serializers.
+    #
+    # @param context [Hash{String, Symbol => Object}] application context
+    # @return [void]
     def set_context(context)
       current_scope.set_context(context)
     end
 
+    # Replaces the current scope's user. A nil value clears the scoped user.
+    #
+    # @param user [Hash{String, Symbol => Object}, nil] user data; include an :id when available
+    # @return [void]
     def set_user(user)
       current_scope.set_user(user)
     end
 
+    # Runs a block with a copy of the current scope and restores its parent.
+    #
+    # Restoration also occurs when the block raises an exception.
+    #
+    # @yield [scope] temporary scope for this execution
+    # @yieldparam scope [Scope]
+    # @yieldreturn [Object] application result
+    # @return [Object] the block's result
+    # @example Attach temporary context
+    #   client.with_scope do |scope|
+    #     scope.set_context(order_id: "42")
+    #     client.capture_message("Order accepted")
+    #   end
     def with_scope
       previous = current_scope
       @store.replace(previous.copy)
@@ -48,6 +93,7 @@ module Hawk
       end
     end
 
+    # @api private
     def using_scope(scope)
       previous = current_scope
       @store.replace(scope.copy)
@@ -58,6 +104,7 @@ module Hawk
       end
     end
 
+    # @api private
     def with_boundary(kind:, metadata:, inherit: false)
       previous = current_scope
       @store.clear_escape unless previous.boundary
@@ -70,24 +117,59 @@ module Hawk
       end
     end
 
+    # Reports an exception with the current scope and per-event overrides.
+    #
+    # Manual calls can report the same exception more than once. Filtering,
+    # sampling, disabled capture, or delivery rejection can discard the event.
+    #
+    # @param exception [Exception] exception to report
+    # @param context [Hash{String, Symbol => Object}] values merged over scoped context
+    # @param user [Hash{String, Symbol => Object}, nil] per-event user; nil uses scope or configuration
+    # @param level [Symbol] severity attached to the event, normally :error
+    # @return [String, nil] local capture ID, or nil when the event is not accepted
+    # @note A capture ID does not confirm receipt by Hawk.
     def capture_exception(exception, context: {}, user: nil, level: :error)
       identifier = dispatch(exception: exception, context: context, user: user, level: level)
       current_scope.ledger.accept(exception, evict: !current_scope.boundary) if identifier
       identifier
     end
 
+    # Reports a message with the current scope and per-event overrides.
+    #
+    # @param message [String] event title
+    # @param context [Hash{String, Symbol => Object}] values merged over scoped context
+    # @param user [Hash{String, Symbol => Object}, nil] per-event user; nil uses scope or configuration
+    # @param level [Symbol] severity attached to the event, normally :info
+    # @return [String, nil] local capture ID, or nil when the event is not accepted
+    # @note A capture ID does not confirm receipt by Hawk.
     def capture_message(message, context: {}, user: nil, level: :info)
       dispatch(message: message, context: context, user: user, level: level)
     end
 
+    # Adds a filtered, timestamped breadcrumb to the current scope.
+    #
+    # Retains the most recent 50 entries. Hook failures discard the entry.
+    #
+    # @param entry [Hash{String, Symbol => Object}] fields such as :message and :category
+    # @return [void]
     def add_breadcrumb(entry)
       Breadcrumbs.add(self, entry)
     end
 
+    # Reports exceptions escaping a block and raises the same exception again.
+    #
+    # Inherits the current scope. Automatic reporting excludes normal process
+    # termination, including SystemExit, SignalException, and Interrupt.
+    #
+    # @yield application work to monitor
+    # @yieldreturn [Object] application result
+    # @return [Object] the block's result
+    # @raise [Exception] any exception raised by the block, after reporting when eligible
     def capture(&)
       Boundary.run(self, kind: :capture, metadata: {}, inherit: true, &)
     end
 
+    # @api private
     def report(exception, mechanism:, context: {}, level: :error, handled: false)
       return if normal_termination?(exception)
       return if mechanism == "request" && expected_request_error?(exception)
@@ -102,20 +184,32 @@ module Hawk
                addons: { "mechanism" => mechanism, "handled" => handled })
     end
 
+    # @api private
     def remember_escape(exception)
       @store.remember_escape(exception)
     end
 
+    # @api private
     def consume_escape(exception)
       @store.consume_escape(exception)
     end
 
+    # Waits for pending attempts, including attempts that fail.
+    #
+    # @param timeout [Numeric] deadline in seconds
+    # @return [Boolean] true if pending attempts finished; false on timeout or failure
+    # @note Success does not confirm receipt by Hawk.
     def flush(timeout: @configuration.flush_timeout)
       @delivery.flush(timeout: timeout)
     rescue StandardError
       false
     end
 
+    # Stops accepting events, clears this execution's scope, and drains delivery.
+    #
+    # @param timeout [Numeric] deadline in seconds
+    # @return [Boolean] true if shutdown finished; false on timeout or failure
+    # @note The client remains closed if shutdown times out.
     def close(timeout: @configuration.flush_timeout)
       @closed = true
       @store.clear