hawk-ruby 0.1.1 → 0.1.2

data/lib/hawk.rb

@@ -22,12 +22,34 @@ require_relative "hawk/transport"
 require_relative "hawk/delivery"
 require_relative "hawk/process_hooks"
 
-# The default client offers the same capture API as independent project clients.
+# Error reporting through a process-wide default {Client}.
+#
+# Initialize before starting application workers. Scope data belongs to the
+# current thread and fiber. Capture IDs confirm local acceptance, not delivery.
+#
+# @example Configure and report
+#   Hawk.init { |config| config.token = ENV.fetch("HAWK_TOKEN") }
+#   Hawk.capture_message("Checkout completed", context: { order_id: "42" })
+#   Hawk.flush(timeout: 5.0)
+# @see Client For independent project clients.
 module Hawk
+  autoload :Rack, File.expand_path("hawk/rack", __dir__.to_s)
+
   class << self
+    # @return [Client, nil] default client, or nil before initialization or after close
     attr_reader :client
 
+    # Configures and replaces the default client, closing the previous client.
+    #
+    # A missing or empty token disables capture. Loaded Rails integrations can
+    # adjust configuration before validation. Initialize before concurrent use.
+    #
+    # @yield [configuration] configuration to customize
+    # @yieldparam configuration [Configuration]
+    # @return [Client] replacement client
+    # @raise [ConfigurationError] if configuration is invalid
     def init
+      Integrations.load
       configuration = Configuration.new
       yield configuration
       Rails.configure(configuration) if defined?(Hawk::Rails)
@@ -39,41 +61,67 @@ module Hawk
       replacement
     end
 
+    # (see Client#capture_exception)
+    # @note Returns nil when no default client exists.
     def capture_exception(exception, context: {}, user: nil, level: :error)
       @client&.capture_exception(exception, context: context, user: user, level: level)
     end
 
+    # (see Client#capture_message)
+    # @note Returns nil when no default client exists.
     def capture_message(message, context: {}, user: nil, level: :info)
       @client&.capture_message(message, context: context, user: user, level: level)
     end
 
+    # (see Client#set_context)
+    # @note Has no effect when no default client exists.
     def set_context(context)
       @client&.set_context(context)
     end
 
+    # (see Client#add_breadcrumb)
+    # @note Has no effect when no default client exists.
     def add_breadcrumb(entry)
       @client&.add_breadcrumb(entry)
     end
 
+    # (see Client#set_user)
+    # @note Has no effect when no default client exists.
     def set_user(user)
       @client&.set_user(user)
     end
 
+    # (see Client#with_scope)
+    # @note Without a default client, yields a temporary scope without storing it.
     def with_scope(&)
       client = @client
       client ? client.with_scope(&) : yield(Scope.new)
     end
 
+    # (see Client#capture)
+    # @note Without a default client, runs the block without reporting.
     def capture(&)
       client = @client
       client ? client.capture(&) : yield
     end
 
+    # Waits for pending delivery attempts on the default client.
+    #
+    # @param timeout [Numeric, nil] deadline in seconds; nil uses Configuration#flush_timeout
+    # @return [Boolean] true if attempts finished or no client exists;
+    #   false on timeout or failure
+    # @note Success does not confirm receipt by Hawk.
     def flush(timeout: nil)
       client = @client
       client ? client.flush(timeout: timeout || client.configuration.flush_timeout) : true
     end
 
+    # Removes the default client and stops its delivery worker.
+    #
+    # @param timeout [Numeric, nil] deadline in seconds; nil uses Configuration#flush_timeout
+    # @return [Boolean] true if shutdown finished or no client exists;
+    #   false on timeout or failure
+    # @note The default client is removed even when shutdown times out.
     def close(timeout: nil)
       previous = @client
       @client = nil
@@ -82,4 +130,5 @@ module Hawk
   end
 end
 
-require_relative "hawk/rails/integration" if defined?(Rails::Railtie)
+require_relative "hawk/integrations"
+Hawk::Integrations.load

data/sig/hawk/integrations.rbs

@@ -0,0 +1,3 @@
+module Hawk::Integrations
+  def self.load: () -> void
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hawk-ruby
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Leonid Svyatov
@@ -119,11 +119,13 @@ files:
 - CHANGELOG.md
 - LICENSE
 - README.md
+- docs/api.md
 - docs/configuration.md
 - docs/integrations.md
 - docs/public-api.md
 - docs/releasing.md
 - docs/verification.md
+- lib/hawk-ruby.rb
 - lib/hawk.rb
 - lib/hawk/boundary.rb
 - lib/hawk/breadcrumbs.rb
@@ -140,6 +142,7 @@ files:
 - lib/hawk/filtered_fields.rb
 - lib/hawk/framework_filter.rb
 - lib/hawk/hook.rb
+- lib/hawk/integrations.rb
 - lib/hawk/job_context.rb
 - lib/hawk/json_value.rb
 - lib/hawk/process_hooks.rb
@@ -177,6 +180,7 @@ files:
 - sig/hawk/filtered_fields.rbs
 - sig/hawk/framework_filter.rbs
 - sig/hawk/hook.rbs
+- sig/hawk/integrations.rbs
 - sig/hawk/job_context.rbs
 - sig/hawk/json_value.rbs
 - sig/hawk/process_hooks.rbs