hooks-ruby 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7588a4a6fdf58e7c927dc4b20b9fa330db86db672f5c779a4c46d51e7e41f386
-  data.tar.gz: 02bdb939c52fd501387856f432a11a82f842d25053d9e73ef3967eb12be03c7a
+  metadata.gz: cc9f23a8b74aef04b7a0016673a9dd835cef5f56eecb316e58b7cb3d19936f0d
+  data.tar.gz: '05290bf35da3f0aa73e5a0b9e0661d2986df03733862f6cd85c19248257f5b09'
 SHA512:
-  metadata.gz: f11eddcaf09095e1d68bcfeeeba3660eab7e3a9bf42744d780987bfb4b54db7cfa6691c4cc435c5dbda4eb3ee60065a6f3c6239df87bf5b5587f638bb3c8d094
-  data.tar.gz: af806e9c8144ed2da97e723c3a4dfcb54f2fd8db85970e806aa3f2f56e6ef8ca665ae157066f1456126804c2bba8ba573d5f59f717de0249148d81d11f9e848d
+  metadata.gz: a4462d77b184ac3be6b4a0f7ac4466dace8b5d146c722205ca7f97f455dc523de2168a71e2fe61b4a0946efdb7e9b8e4b61dc1e9940c8d14fdbaebebcb8fb497
+  data.tar.gz: bc2023bf7a08efd872e69603dd81dbbb2a4798deb4b4c98db37d65f8544ba57cfbdf36b82f2b48b33250d2429eb39946a71d65d7fbdf7c2d5e0a6b724e79a9cb

data/README.md

@@ -72,7 +72,7 @@ Here is a very high-level overview of how Hooks works:
     end
     ```
 
-That is pretty much it! Below you will find more detailed instructions on how to install and use Hooks, as well as how to create your own plugins. This high-level overview should give you a good idea of how Hooks works and how you can use it to handle webhooks in your applications. You may also be interested in using your own custom authentication plugins to secure your webhook endpoints, which is covered in the [Authentication](#authentication) section below.
+That is pretty much it! Below you will find more detailed instructions on how to install and use Hooks, as well as how to create your own plugins. This high-level overview should give you a good idea of how Hooks works and how you can use it to handle webhooks in your applications. You may also be interested in using your own custom authentication plugins to secure your webhook endpoints, which is covered in the [Authentication](#authentication-plugins) section below.
 
 ## Installation 💎
 
@@ -102,7 +102,7 @@ First, create a `config.ru` file:
 
 ```ruby
 # file: config.ru
-require "hooks-ruby"
+require "hooks"
 
 # See the config documentation below for the full list of available options
 # For this example, we will just set use_catchall_route to true
@@ -286,10 +286,22 @@ What these steps have done is set up a Hooks server that listens for incoming we
 
 To see a live working version of this example, check out the [`spec/acceptance/`](spec/acceptance/) directory in this repository, which is used for acceptance testing the Hooks framework. It contains a complete example of how to set up a Hooks server with custom plugins, authentication, and more.
 
-### Authentication
+### Authentication Plugins
 
 See the [Auth Plugins](docs/auth_plugins.md) documentation for even more information on how to create your own custom authentication plugins.
 
+### Handler Plugins
+
+See the [Handler Plugins](docs/handler_plugins.md) documentation for in-depth information about handler plugins and how you can create your own to extend the functionality of the Hooks framework for your own deployment.
+
+### Lifecycle Plugins
+
+See the [Lifecycle Plugins](docs/lifecycle_plugins.md) documentation for information on how to create lifecycle plugins that can hook into the request/response/error lifecycle of the Hooks framework, allowing you to add custom behavior at various stages of processing webhook requests.
+
+### Instrument Plugins
+
+See the [Instrument Plugins](docs/instrument_plugins.md) documentation for information on how to create instrument plugins that can be used to collect metrics or report exceptions during webhook processing. These plugins can be used to integrate with monitoring and alerting systems.
+
 ## Contributing 🤝
 
 See the [Contributing](CONTRIBUTING.md) document for information on how to contribute to the Hooks project, including setting up your development environment, running tests, and releasing new versions.

data/hooks.gemspec

@@ -22,7 +22,6 @@ Gem::Specification.new do |spec|
   spec.add_dependency "retryable", "~> 3.0", ">= 3.0.5"
   spec.add_dependency "dry-schema", "~> 1.14", ">= 1.14.1"
   spec.add_dependency "grape", "~> 2.3"
-  spec.add_dependency "grape-swagger", "~> 2.1", ">= 2.1.2"
   spec.add_dependency "puma", "~> 6.6"
 
   spec.required_ruby_version = Gem::Requirement.new(">= 3.2.2")

data/lib/hooks/app/api.rb

@@ -9,6 +9,7 @@ require_relative "../plugins/handlers/base"
 require_relative "../plugins/handlers/default"
 require_relative "../core/logger_factory"
 require_relative "../core/log"
+require_relative "../core/plugin_loader"
 
 # Import all core endpoint classes dynamically
 Dir[File.join(__dir__, "endpoints/**/*.rb")].sort.each { |file| require file }
@@ -21,14 +22,12 @@ module Hooks
       include Hooks::App::Auth
 
       class << self
-        attr_reader :start_time
+        attr_reader :server_start_time
       end
 
       # Create a new configured API class
       def self.create(config:, endpoints:, log:)
-        @start_time = Time.now
-
-        Hooks::Log.instance = log
+        @server_start_time = Time.now
 
         api_class = Class.new(Grape::API) do
           content_type :json, "application/json"
@@ -51,20 +50,53 @@ module Hooks
 
             post(full_path) do
               request_id = uuid
+              start_time = Time.now
+
               request_context = {
                 request_id:,
                 path: full_path,
                 handler: handler_class_name
               }
 
+              # everything wrapped in the log context has access to the request context and includes it in log messages
+              # ex: Hooks::Log.info("message") will include request_id, path, handler, etc
               Core::LogContext.with(request_context) do
                 begin
+                  # Build Rack environment for lifecycle hooks
+                  rack_env = {
+                    "REQUEST_METHOD" => request.request_method,
+                    "PATH_INFO" => request.path_info,
+                    "QUERY_STRING" => request.query_string,
+                    "HTTP_VERSION" => request.env["HTTP_VERSION"],
+                    "REQUEST_URI" => request.url,
+                    "SERVER_NAME" => request.env["SERVER_NAME"],
+                    "SERVER_PORT" => request.env["SERVER_PORT"],
+                    "CONTENT_TYPE" => request.content_type,
+                    "CONTENT_LENGTH" => request.content_length,
+                    "REMOTE_ADDR" => request.env["REMOTE_ADDR"],
+                    "hooks.request_id" => request_id,
+                    "hooks.handler" => handler_class_name,
+                    "hooks.endpoint_config" => endpoint_config,
+                    "hooks.start_time" => start_time.iso8601,
+                    "hooks.full_path" => full_path
+                  }
+
+                  # Add HTTP headers to environment
+                  headers.each do |key, value|
+                    env_key = "HTTP_#{key.upcase.tr('-', '_')}"
+                    rack_env[env_key] = value
+                  end
+
+                  # Call lifecycle hooks: on_request
+                  Core::PluginLoader.lifecycle_plugins.each do |plugin|
+                    plugin.on_request(rack_env)
+                  end
+
                   enforce_request_limits(config)
                   request.body.rewind
                   raw_body = request.body.read
 
                   if endpoint_config[:auth]
-                    log.info "validating request (id: #{request_id}, handler: #{handler_class_name})"
                     validate_auth!(raw_body, headers, endpoint_config, config)
                   end
 
@@ -78,16 +110,29 @@ module Hooks
                     config: endpoint_config
                   )
 
-                  log.info "request processed successfully (id: #{request_id}, handler: #{handler_class_name})"
+                  # Call lifecycle hooks: on_response
+                  Core::PluginLoader.lifecycle_plugins.each do |plugin|
+                    plugin.on_response(rack_env, response)
+                  end
+
+                  log.info("successfully processed webhook event with handler: #{handler_class_name}")
+                  log.debug("processing duration: #{Time.now - start_time}s")
                   status 200
                   content_type "application/json"
-                  (response || { status: "ok" }).to_json
-                rescue => e
-                  log.error "request failed: #{e.message} (id: #{request_id}, handler: #{handler_class_name})"
+                  response.to_json
+                rescue StandardError => e
+                  # Call lifecycle hooks: on_error
+                  if defined?(rack_env)
+                    Core::PluginLoader.lifecycle_plugins.each do |plugin|
+                      plugin.on_error(e, rack_env)
+                    end
+                  end
+
+                  log.error("an error occuring during the processing of a webhook event - #{e.message}")
                   error_response = {
                     error: e.message,
                     code: determine_error_code(e),
-                    request_id: request_id
+                    request_id:
                   }
                   error_response[:backtrace] = e.backtrace unless config[:production]
                   status error_response[:code]

data/lib/hooks/app/auth/auth.rb

@@ -22,7 +22,7 @@ module Hooks
       def validate_auth!(payload, headers, endpoint_config, global_config = {})
         auth_config = endpoint_config[:auth]
 
-        # Security: Ensure auth type is present and valid
+        # Ensure auth type is present and valid
         auth_type = auth_config&.dig(:type)
         unless auth_type&.is_a?(String) && !auth_type.strip.empty?
           error!("authentication configuration missing or invalid", 500)
@@ -32,9 +32,12 @@ module Hooks
         begin
           auth_class = Core::PluginLoader.get_auth_plugin(auth_type)
         rescue => e
+          log.error("failed to load auth plugin '#{auth_type}': #{e.message}")
           error!("unsupported auth type '#{auth_type}'", 400)
         end
 
+        log.debug("validating auth for request with auth_class: #{auth_class.name}")
+
         unless auth_class.valid?(
           payload:,
           headers:,
@@ -43,6 +46,16 @@ module Hooks
           error!("authentication failed", 401)
         end
       end
+
+      private
+
+      # Short logger accessor for auth module
+      # @return [Hooks::Log] Logger instance
+      #
+      # Provides access to the application logger for authentication operations.
+      def log
+        Hooks::Log.instance
+      end
     end
   end
 end

data/lib/hooks/app/endpoints/catchall.rb

@@ -1,5 +1,13 @@
 # frozen_string_literal: true
 
+# !!! IMPORTANT !!!
+# This file handles the catchall endpoint for the Hooks application.
+# You should not be using catchall endpoints in production.
+# This is mainly for development, testing, and demo purposes.
+# The logging is limited, lifecycle hooks are not called,
+# and it does not support plugins or instruments.
+# Use with caution!
+
 require "grape"
 require_relative "../../plugins/handlers/default"
 require_relative "../helpers"
@@ -10,10 +18,13 @@ module Hooks
       include Hooks::App::Helpers
 
       def self.mount_path(config)
+        # :nocov:
         "#{config[:root_path]}/*path"
+        # :nocov:
       end
 
       def self.route_block(captured_config, captured_logger)
+        # :nocov:
         proc do
           request_id = uuid
 
@@ -23,7 +34,7 @@ module Hooks
 
           # Set request context for logging
           request_context = {
-            request_id: request_id,
+            request_id:,
             path: "/#{params[:path]}",
             handler: "DefaultHandler"
           }
@@ -45,8 +56,8 @@ module Hooks
 
               # Call handler
               response = handler.call(
-                payload: payload,
-                headers: headers,
+                payload:,
+                headers:,
                 config: {}
               )
 
@@ -78,6 +89,7 @@ module Hooks
             end
           end
         end
+        # :nocov:
       end
     end
   end

data/lib/hooks/app/endpoints/health.rb

@@ -12,7 +12,7 @@ module Hooks
           status: "healthy",
           timestamp: Time.now.iso8601,
           version: Hooks::VERSION,
-          uptime_seconds: (Time.now - Hooks::App::API.start_time).to_i
+          uptime_seconds: (Time.now - Hooks::App::API.server_start_time).to_i
         }.to_json
       end
     end

data/lib/hooks/core/builder.rb

@@ -5,6 +5,7 @@ require_relative "config_validator"
 require_relative "logger_factory"
 require_relative "plugin_loader"
 require_relative "../app/api"
+require_relative "../utils/retry"
 
 module Hooks
   module Core
@@ -34,6 +35,11 @@ module Hooks
           )
         end
 
+        Hooks::Log.instance = @log
+
+        # Hydrate our Retryable instance
+        Retry.setup!(log: @log)
+
         # Load all plugins at boot time
         load_plugins(config)
 

data/lib/hooks/core/config_validator.rb

@@ -15,6 +15,8 @@ module Hooks
         optional(:handler_dir).filled(:string)  # For backward compatibility
         optional(:handler_plugin_dir).filled(:string)
         optional(:auth_plugin_dir).maybe(:string)
+        optional(:lifecycle_plugin_dir).maybe(:string)
+        optional(:instruments_plugin_dir).maybe(:string)
         optional(:log_level).filled(:string, included_in?: %w[debug info warn error])
         optional(:request_limit).filled(:integer, gt?: 0)
         optional(:request_timeout).filled(:integer, gt?: 0)

data/lib/hooks/core/failbot.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Hooks
+  module Core
+    # Global failbot component for error reporting
+    #
+    # This is a stub implementation that does nothing by default.
+    # Users can replace this with their own implementation for services
+    # like Sentry, Rollbar, etc.
+    class Failbot
+      # Report an error or exception
+      #
+      # @param error_or_message [Exception, String] Exception object or error message
+      # @param context [Hash] Optional context information
+      # @return [void]
+      def report(error_or_message, context = {})
+        # Override in subclass for actual error reporting
+      end
+
+      # Report a critical error
+      #
+      # @param error_or_message [Exception, String] Exception object or error message
+      # @param context [Hash] Optional context information
+      # @return [void]
+      def critical(error_or_message, context = {})
+        # Override in subclass for actual error reporting
+      end
+
+      # Report a warning
+      #
+      # @param message [String] Warning message
+      # @param context [Hash] Optional context information
+      # @return [void]
+      def warning(message, context = {})
+        # Override in subclass for actual warning reporting
+      end
+
+      # Capture an exception during block execution
+      #
+      # @param context [Hash] Optional context information
+      # @return [Object] Return value of the block
+      def capture(context = {})
+        yield
+      rescue => e
+        report(e, context)
+        raise
+      end
+    end
+  end
+end

data/lib/hooks/core/global_components.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Hooks
+  module Core
+    # Global registry for shared components accessible throughout the application
+    class GlobalComponents
+      @test_stats = nil
+      @test_failbot = nil
+
+      # Get the global stats instance
+      # @return [Hooks::Plugins::Instruments::StatsBase] Stats instance for metrics reporting
+      def self.stats
+        @test_stats || PluginLoader.get_instrument_plugin(:stats)
+      end
+
+      # Get the global failbot instance
+      # @return [Hooks::Plugins::Instruments::FailbotBase] Failbot instance for error reporting
+      def self.failbot
+        @test_failbot || PluginLoader.get_instrument_plugin(:failbot)
+      end
+
+      # Set a custom stats instance (for testing)
+      # @param stats_instance [Object] Custom stats instance
+      def self.stats=(stats_instance)
+        @test_stats = stats_instance
+      end
+
+      # Set a custom failbot instance (for testing)
+      # @param failbot_instance [Object] Custom failbot instance
+      def self.failbot=(failbot_instance)
+        @test_failbot = failbot_instance
+      end
+
+      # Reset components to default instances (for testing)
+      #
+      # @return [void]
+      def self.reset
+        @test_stats = nil
+        @test_failbot = nil
+        # Clear and reload default instruments
+        PluginLoader.clear_plugins
+        require_relative "../plugins/instruments/stats"
+        require_relative "../plugins/instruments/failbot"
+        PluginLoader.instance_variable_set(:@instrument_plugins, {
+          stats: Hooks::Plugins::Instruments::Stats.new,
+          failbot: Hooks::Plugins::Instruments::Failbot.new
+        })
+      end
+    end
+  end
+end

data/lib/hooks/core/plugin_loader.rb

@@ -5,14 +5,16 @@ require_relative "../security"
 
 module Hooks
   module Core
-    # Loads and caches all plugins (auth + handlers) at boot time
+    # Loads and caches all plugins (auth + handlers + lifecycle + instruments) at boot time
     class PluginLoader
       # Class-level registries for loaded plugins
       @auth_plugins = {}
       @handler_plugins = {}
+      @lifecycle_plugins = []
+      @instrument_plugins = { stats: nil, failbot: nil }
 
       class << self
-        attr_reader :auth_plugins, :handler_plugins
+        attr_reader :auth_plugins, :handler_plugins, :lifecycle_plugins, :instrument_plugins
 
         # Load all plugins at boot time
         #
@@ -22,6 +24,8 @@ module Hooks
           # Clear existing registries
           @auth_plugins = {}
           @handler_plugins = {}
+          @lifecycle_plugins = []
+          @instrument_plugins = { stats: nil, failbot: nil }
 
           # Load built-in plugins first
           load_builtin_plugins
@@ -29,6 +33,11 @@ module Hooks
           # Load custom plugins if directories are configured
           load_custom_auth_plugins(config[:auth_plugin_dir]) if config[:auth_plugin_dir]
           load_custom_handler_plugins(config[:handler_plugin_dir]) if config[:handler_plugin_dir]
+          load_custom_lifecycle_plugins(config[:lifecycle_plugin_dir]) if config[:lifecycle_plugin_dir]
+          load_custom_instrument_plugins(config[:instruments_plugin_dir]) if config[:instruments_plugin_dir]
+
+          # Load default instruments if no custom ones were loaded
+          load_default_instruments
 
           # Log loaded plugins
           log_loaded_plugins
@@ -65,12 +74,29 @@ module Hooks
           plugin_class
         end
 
+        # Get instrument plugin instance by type
+        #
+        # @param instrument_type [Symbol] Type of instrument (:stats or :failbot)
+        # @return [Object] The instrument plugin instance
+        # @raise [StandardError] if instrument not found
+        def get_instrument_plugin(instrument_type)
+          instrument_instance = @instrument_plugins[instrument_type]
+
+          unless instrument_instance
+            raise StandardError, "Instrument plugin '#{instrument_type}' not found"
+          end
+
+          instrument_instance
+        end
+
         # Clear all loaded plugins (for testing purposes)
         #
         # @return [void]
         def clear_plugins
           @auth_plugins = {}
           @handler_plugins = {}
+          @lifecycle_plugins = []
+          @instrument_plugins = { stats: nil, failbot: nil }
         end
 
         private
@@ -119,6 +145,38 @@ module Hooks
           end
         end
 
+        # Load custom lifecycle plugins from directory
+        #
+        # @param lifecycle_plugin_dir [String] Directory containing custom lifecycle plugins
+        # @return [void]
+        def load_custom_lifecycle_plugins(lifecycle_plugin_dir)
+          return unless lifecycle_plugin_dir && Dir.exist?(lifecycle_plugin_dir)
+
+          Dir.glob(File.join(lifecycle_plugin_dir, "*.rb")).sort.each do |file_path|
+            begin
+              load_custom_lifecycle_plugin(file_path, lifecycle_plugin_dir)
+            rescue => e
+              raise StandardError, "Failed to load lifecycle plugin from #{file_path}: #{e.message}"
+            end
+          end
+        end
+
+        # Load custom instrument plugins from directory
+        #
+        # @param instruments_plugin_dir [String] Directory containing custom instrument plugins
+        # @return [void]
+        def load_custom_instrument_plugins(instruments_plugin_dir)
+          return unless instruments_plugin_dir && Dir.exist?(instruments_plugin_dir)
+
+          Dir.glob(File.join(instruments_plugin_dir, "*.rb")).sort.each do |file_path|
+            begin
+              load_custom_instrument_plugin(file_path, instruments_plugin_dir)
+            rescue => e
+              raise StandardError, "Failed to load instrument plugin from #{file_path}: #{e.message}"
+            end
+          end
+        end
+
         # Load a single custom auth plugin file
         #
         # @param file_path [String] Path to the auth plugin file
@@ -189,6 +247,90 @@ module Hooks
           @handler_plugins[class_name] = handler_class
         end
 
+        # Load a single custom lifecycle plugin file
+        #
+        # @param file_path [String] Path to the lifecycle plugin file
+        # @param lifecycle_plugin_dir [String] Base directory for lifecycle plugins
+        # @return [void]
+        def load_custom_lifecycle_plugin(file_path, lifecycle_plugin_dir)
+          # Security: Ensure the file path doesn't escape the lifecycle plugin directory
+          normalized_lifecycle_dir = Pathname.new(File.expand_path(lifecycle_plugin_dir))
+          normalized_file_path = Pathname.new(File.expand_path(file_path))
+          unless normalized_file_path.descend.any? { |path| path == normalized_lifecycle_dir }
+            raise SecurityError, "Lifecycle plugin path outside of lifecycle plugin directory: #{file_path}"
+          end
+
+          # Extract class name from file (e.g., logging_lifecycle.rb -> LoggingLifecycle)
+          file_name = File.basename(file_path, ".rb")
+          class_name = file_name.split("_").map(&:capitalize).join("")
+
+          # Security: Validate class name
+          unless valid_lifecycle_class_name?(class_name)
+            raise StandardError, "Invalid lifecycle plugin class name: #{class_name}"
+          end
+
+          # Load the file
+          require file_path
+
+          # Get the class and validate it
+          lifecycle_class = Object.const_get(class_name)
+          unless lifecycle_class < Hooks::Plugins::Lifecycle
+            raise StandardError, "Lifecycle plugin class must inherit from Hooks::Plugins::Lifecycle: #{class_name}"
+          end
+
+          # Register the plugin instance
+          @lifecycle_plugins << lifecycle_class.new
+        end
+
+        # Load a single custom instrument plugin file
+        #
+        # @param file_path [String] Path to the instrument plugin file
+        # @param instruments_plugin_dir [String] Base directory for instrument plugins
+        # @return [void]
+        def load_custom_instrument_plugin(file_path, instruments_plugin_dir)
+          # Security: Ensure the file path doesn't escape the instruments plugin directory
+          normalized_instruments_dir = Pathname.new(File.expand_path(instruments_plugin_dir))
+          normalized_file_path = Pathname.new(File.expand_path(file_path))
+          unless normalized_file_path.descend.any? { |path| path == normalized_instruments_dir }
+            raise SecurityError, "Instrument plugin path outside of instruments plugin directory: #{file_path}"
+          end
+
+          # Extract class name from file (e.g., custom_stats.rb -> CustomStats)
+          file_name = File.basename(file_path, ".rb")
+          class_name = file_name.split("_").map(&:capitalize).join("")
+
+          # Security: Validate class name
+          unless valid_instrument_class_name?(class_name)
+            raise StandardError, "Invalid instrument plugin class name: #{class_name}"
+          end
+
+          # Load the file
+          require file_path
+
+          # Get the class and validate it
+          instrument_class = Object.const_get(class_name)
+
+          # Determine instrument type based on inheritance
+          if instrument_class < Hooks::Plugins::Instruments::StatsBase
+            @instrument_plugins[:stats] = instrument_class.new
+          elsif instrument_class < Hooks::Plugins::Instruments::FailbotBase
+            @instrument_plugins[:failbot] = instrument_class.new
+          else
+            raise StandardError, "Instrument plugin class must inherit from StatsBase or FailbotBase: #{class_name}"
+          end
+        end
+
+        # Load default instrument implementations if no custom ones were loaded
+        #
+        # @return [void]
+        def load_default_instruments
+          require_relative "../plugins/instruments/stats"
+          require_relative "../plugins/instruments/failbot"
+
+          @instrument_plugins[:stats] ||= Hooks::Plugins::Instruments::Stats.new
+          @instrument_plugins[:failbot] ||= Hooks::Plugins::Instruments::Failbot.new
+        end
+
         # Log summary of loaded plugins
         #
         # @return [void]
@@ -201,6 +343,8 @@ module Hooks
 
           log.info "Loaded #{@auth_plugins.size} auth plugins: #{@auth_plugins.keys.join(', ')}"
           log.info "Loaded #{@handler_plugins.size} handler plugins: #{@handler_plugins.keys.join(', ')}"
+          log.info "Loaded #{@lifecycle_plugins.size} lifecycle plugins"
+          log.info "Loaded instruments: #{@instrument_plugins.keys.select { |k| @instrument_plugins[k] }.join(', ')}"
         end
 
         # Validate that an auth plugin class name is safe to load
@@ -244,6 +388,48 @@ module Hooks
 
           true
         end
+
+        # Validate that a lifecycle plugin class name is safe to load
+        #
+        # @param class_name [String] The class name to validate
+        # @return [Boolean] true if the class name is safe, false otherwise
+        def valid_lifecycle_class_name?(class_name)
+          # Must be a string
+          return false unless class_name.is_a?(String)
+
+          # Must not be empty or only whitespace
+          return false if class_name.strip.empty?
+
+          # Must match a safe pattern: alphanumeric + underscore, starting with uppercase
+          # Examples: LoggingLifecycle, MetricsLifecycle, CustomLifecycle
+          return false unless class_name.match?(/\A[A-Z][a-zA-Z0-9_]*\z/)
+
+          # Must not be a system/built-in class name
+          return false if Hooks::Security::DANGEROUS_CLASSES.include?(class_name)
+
+          true
+        end
+
+        # Validate that an instrument plugin class name is safe to load
+        #
+        # @param class_name [String] The class name to validate
+        # @return [Boolean] true if the class name is safe, false otherwise
+        def valid_instrument_class_name?(class_name)
+          # Must be a string
+          return false unless class_name.is_a?(String)
+
+          # Must not be empty or only whitespace
+          return false if class_name.strip.empty?
+
+          # Must match a safe pattern: alphanumeric + underscore, starting with uppercase
+          # Examples: CustomStats, CustomFailbot, DatadogStats
+          return false unless class_name.match?(/\A[A-Z][a-zA-Z0-9_]*\z/)
+
+          # Must not be a system/built-in class name
+          return false if Hooks::Security::DANGEROUS_CLASSES.include?(class_name)
+
+          true
+        end
       end
     end
   end

data/lib/hooks/core/stats.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Hooks
+  module Core
+    # Global stats component for metrics reporting
+    #
+    # This is a stub implementation that does nothing by default.
+    # Users can replace this with their own implementation for services
+    # like DataDog, New Relic, etc.
+    class Stats
+      # Record a metric
+      #
+      # @param metric_name [String] Name of the metric
+      # @param value [Numeric] Value to record
+      # @param tags [Hash] Optional tags/labels for the metric
+      # @return [void]
+      def record(metric_name, value, tags = {})
+        # Override in subclass for actual metrics reporting
+      end
+
+      # Increment a counter
+      #
+      # @param metric_name [String] Name of the counter
+      # @param tags [Hash] Optional tags/labels for the metric
+      # @return [void]
+      def increment(metric_name, tags = {})
+        # Override in subclass for actual metrics reporting
+      end
+
+      # Record a timing metric
+      #
+      # @param metric_name [String] Name of the timing metric
+      # @param duration [Numeric] Duration in seconds
+      # @param tags [Hash] Optional tags/labels for the metric
+      # @return [void]
+      def timing(metric_name, duration, tags = {})
+        # Override in subclass for actual metrics reporting
+      end
+
+      # Measure execution time of a block
+      #
+      # @param metric_name [String] Name of the timing metric
+      # @param tags [Hash] Optional tags/labels for the metric
+      # @return [Object] Return value of the block
+      def measure(metric_name, tags = {})
+        start_time = Time.now
+        result = yield
+        duration = Time.now - start_time
+        timing(metric_name, duration, tags)
+        result
+      end
+    end
+  end
+end

data/lib/hooks/plugins/auth/base.rb

@@ -2,6 +2,7 @@
 
 require "rack/utils"
 require_relative "../../core/log"
+require_relative "../../core/global_components"
 
 module Hooks
   module Plugins
@@ -33,6 +34,30 @@ module Hooks
           Hooks::Log.instance
         end
 
+        # Global stats component accessor
+        # @return [Hooks::Core::Stats] Stats instance for metrics reporting
+        #
+        # Provides access to the global stats component for reporting metrics
+        # to services like DataDog, New Relic, etc.
+        #
+        # @example Recording a metric in an inherited class
+        #   stats.increment("auth.validation", { plugin: "hmac" })
+        def self.stats
+          Hooks::Core::GlobalComponents.stats
+        end
+
+        # Global failbot component accessor
+        # @return [Hooks::Core::Failbot] Failbot instance for error reporting
+        #
+        # Provides access to the global failbot component for reporting errors
+        # to services like Sentry, Rollbar, etc.
+        #
+        # @example Reporting an error in an inherited class
+        #   failbot.report("Auth validation failed", { plugin: "hmac" })
+        def self.failbot
+          Hooks::Core::GlobalComponents.failbot
+        end
+
         # Retrieve the secret from the environment variable based on the key set in the configuration
         #
         # Note: This method is intended to be used by subclasses

data/lib/hooks/plugins/handlers/base.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../../core/global_components"
+
 module Hooks
   module Plugins
     module Handlers
@@ -29,6 +31,30 @@ module Hooks
         def log
           Hooks::Log.instance
         end
+
+        # Global stats component accessor
+        # @return [Hooks::Core::Stats] Stats instance for metrics reporting
+        #
+        # Provides access to the global stats component for reporting metrics
+        # to services like DataDog, New Relic, etc.
+        #
+        # @example Recording a metric in an inherited class
+        #   stats.increment("webhook.processed", { handler: "MyHandler" })
+        def stats
+          Hooks::Core::GlobalComponents.stats
+        end
+
+        # Global failbot component accessor
+        # @return [Hooks::Core::Failbot] Failbot instance for error reporting
+        #
+        # Provides access to the global failbot component for reporting errors
+        # to services like Sentry, Rollbar, etc.
+        #
+        # @example Reporting an error in an inherited class
+        #   failbot.report("Something went wrong", { handler: "MyHandler" })
+        def failbot
+          Hooks::Core::GlobalComponents.failbot
+        end
       end
     end
   end

data/lib/hooks/plugins/instruments/failbot.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative "failbot_base"
+
+module Hooks
+  module Plugins
+    module Instruments
+      # Default failbot instrument implementation
+      #
+      # This is a stub implementation that does nothing by default.
+      # Users can replace this with their own implementation for services
+      # like Sentry, Rollbar, etc.
+      class Failbot < FailbotBase
+        # Inherit from FailbotBase to provide a default implementation of the failbot instrument.
+      end
+    end
+  end
+end

data/lib/hooks/plugins/instruments/failbot_base.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Hooks
+  module Plugins
+    module Instruments
+      # Base class for all failbot instrument plugins
+      #
+      # All custom failbot implementations must inherit from this class and implement
+      # the required methods for error reporting.
+      class FailbotBase
+        # Short logger accessor for all subclasses
+        # @return [Hooks::Log] Logger instance
+        #
+        # Provides a convenient way for instruments to log messages without needing
+        # to reference the full Hooks::Log namespace.
+        #
+        # @example Logging debug info in an inherited class
+        #   log.debug("Sending error to external service")
+        def log
+          Hooks::Log.instance
+        end
+      end
+    end
+  end
+end

data/lib/hooks/plugins/instruments/stats.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative "stats_base"
+
+module Hooks
+  module Plugins
+    module Instruments
+      # Default stats instrument implementation
+      #
+      # This is a stub implementation that does nothing by default.
+      # Users can replace this with their own implementation for services
+      # like DataDog, New Relic, etc.
+      class Stats < StatsBase
+        # Inherit from StatsBase to provide a default implementation of the stats instrument.
+      end
+    end
+  end
+end

data/lib/hooks/plugins/instruments/stats_base.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Hooks
+  module Plugins
+    module Instruments
+      # Base class for all stats instrument plugins
+      #
+      # All custom stats implementations must inherit from this class and implement
+      # the required methods for metrics reporting.
+      class StatsBase
+        # Short logger accessor for all subclasses
+        # @return [Hooks::Log] Logger instance
+        #
+        # Provides a convenient way for instruments to log messages without needing
+        # to reference the full Hooks::Log namespace.
+        #
+        # @example Logging an error in an inherited class
+        #   log.error("Failed to send metric to external service")
+        def log
+          Hooks::Log.instance
+        end
+      end
+    end
+  end
+end

data/lib/hooks/plugins/lifecycle.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../core/global_components"
+
 module Hooks
   module Plugins
     # Base class for global lifecycle plugins
@@ -28,6 +30,42 @@ module Hooks
       def on_error(exception, env)
         # Override in subclass for error handling logic
       end
+
+      # Short logger accessor for all subclasses
+      # @return [Hooks::Log] Logger instance
+      #
+      # Provides a convenient way for lifecycle plugins to log messages without needing
+      # to reference the full Hooks::Log namespace.
+      #
+      # @example Logging an error in an inherited class
+      #   log.error("oh no an error occured")
+      def log
+        Hooks::Log.instance
+      end
+
+      # Global stats component accessor
+      # @return [Hooks::Core::Stats] Stats instance for metrics reporting
+      #
+      # Provides access to the global stats component for reporting metrics
+      # to services like DataDog, New Relic, etc.
+      #
+      # @example Recording a metric in an inherited class
+      #   stats.increment("lifecycle.request_processed")
+      def stats
+        Hooks::Core::GlobalComponents.stats
+      end
+
+      # Global failbot component accessor
+      # @return [Hooks::Core::Failbot] Failbot instance for error reporting
+      #
+      # Provides access to the global failbot component for reporting errors
+      # to services like Sentry, Rollbar, etc.
+      #
+      # @example Reporting an error in an inherited class
+      #   failbot.report("Lifecycle hook failed")
+      def failbot
+        Hooks::Core::GlobalComponents.failbot
+      end
     end
   end
 end

data/lib/hooks/utils/retry.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "retryable"
+
+# Utility module for retry functionality
+module Retry
+  # This method should be called as early as possible in the startup of your application
+  # It sets up the Retryable gem with custom contexts and passes through a few options
+  # Should the number of retries be reached without success, the last exception will be raised
+  #
+  # @param log [Logger] The logger to use for retryable logging
+  # @raise [ArgumentError] If no logger is provided
+  # @return [void]
+  def self.setup!(log: nil, log_retries: ENV.fetch("RETRY_LOG_RETRIES", "true") == "true")
+    raise ArgumentError, "a logger must be provided" if log.nil?
+
+    log_method = lambda do |retries, exception|
+      # :nocov:
+      if log_retries
+        log.debug("[retry ##{retries}] #{exception.class}: #{exception.message} - #{exception.backtrace.join("\n")}")
+      end
+      # :nocov:
+    end
+
+    ######## Retryable Configuration ########
+    # All defaults available here:
+    # https://github.com/nfedyashev/retryable/blob/6a04027e61607de559e15e48f281f3ccaa9750e8/lib/retryable/configuration.rb#L22-L33
+    Retryable.configure do |config|
+      config.contexts[:default] = {
+        on: [StandardError],
+        sleep: ENV.fetch("DEFAULT_RETRY_SLEEP", "1").to_i,
+        tries: ENV.fetch("DEFAULT_RETRY_TRIES", "10").to_i,
+        log_method:
+      }
+    end
+  end
+end

data/lib/hooks/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Hooks
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end

data/lib/hooks.rb

@@ -3,6 +3,11 @@
 require_relative "hooks/version"
 require_relative "hooks/core/builder"
 
+# Load all core components
+Dir[File.join(__dir__, "hooks/core/**/*.rb")].sort.each do |file|
+  require file
+end
+
 # Load all plugins (auth plugins, handler plugins, lifecycle hooks, etc.)
 Dir[File.join(__dir__, "hooks/plugins/**/*.rb")].sort.each do |file|
   require file

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hooks-ruby
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - github
@@ -78,26 +78,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.3'
-- !ruby/object:Gem::Dependency
-  name: grape-swagger
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.1'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 2.1.2
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.1'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 2.1.2
 - !ruby/object:Gem::Dependency
   name: puma
   requirement: !ruby/object:Gem::Requirement
@@ -152,17 +132,25 @@ files:
 - lib/hooks/core/builder.rb
 - lib/hooks/core/config_loader.rb
 - lib/hooks/core/config_validator.rb
+- lib/hooks/core/failbot.rb
+- lib/hooks/core/global_components.rb
 - lib/hooks/core/log.rb
 - lib/hooks/core/logger_factory.rb
 - lib/hooks/core/plugin_loader.rb
+- lib/hooks/core/stats.rb
 - lib/hooks/plugins/auth/base.rb
 - lib/hooks/plugins/auth/hmac.rb
 - lib/hooks/plugins/auth/shared_secret.rb
 - lib/hooks/plugins/handlers/base.rb
 - lib/hooks/plugins/handlers/default.rb
+- lib/hooks/plugins/instruments/failbot.rb
+- lib/hooks/plugins/instruments/failbot_base.rb
+- lib/hooks/plugins/instruments/stats.rb
+- lib/hooks/plugins/instruments/stats_base.rb
 - lib/hooks/plugins/lifecycle.rb
 - lib/hooks/security.rb
 - lib/hooks/utils/normalize.rb
+- lib/hooks/utils/retry.rb
 - lib/hooks/version.rb
 homepage: https://github.com/github/hooks
 licenses: