Implement global lifecycle hooks and stats/failbot components

Co-authored-by: GrantBirki <[email protected]>

Author: Copilot

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

lib/hooks/app/api.rb

@@ -9,6 +9,7 @@
 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 }
@@ -63,6 +64,34 @@ def self.create(config:, endpoints:, log:)
               # 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
+                  }
+
+                  # 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
@@ -81,12 +110,24 @@ def self.create(config:, endpoints:, log:)
                     config: endpoint_config
                   )
 
+                  # Call lifecycle hooks: on_response
+                  Core::PluginLoader.lifecycle_plugins.each do |plugin|
+                    plugin.on_response(rack_env, response)
+                  end
+
                   log.info "request processed successfully by handler: #{handler_class_name}"
                   log.debug "request duration: #{Time.now - start_time}s"
                   status 200
                   content_type "application/json"
                   response.to_json
                 rescue => 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 "request failed: #{e.message}"
                   error_response = {
                     error: e.message,

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

lib/hooks/core/global_components.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "stats"
+require_relative "failbot"
+
+module Hooks
+  module Core
+    # Global registry for shared components accessible throughout the application
+    class GlobalComponents
+      @stats = Stats.new
+      @failbot = Failbot.new
+
+      class << self
+        attr_accessor :stats, :failbot
+
+      end
+
+      # Reset components to default instances (for testing)
+      #
+      # @return [void]
+      def self.reset
+        @stats = Stats.new
+        @failbot = Failbot.new
+      end
+    end
+  end
+end

lib/hooks/core/plugin_loader.rb

@@ -5,14 +5,15 @@
 
 module Hooks
   module Core
-    # Loads and caches all plugins (auth + handlers) at boot time
+    # Loads and caches all plugins (auth + handlers + lifecycle) at boot time
     class PluginLoader
       # Class-level registries for loaded plugins
       @auth_plugins = {}
       @handler_plugins = {}
+      @lifecycle_plugins = []
 
       class << self
-        attr_reader :auth_plugins, :handler_plugins
+        attr_reader :auth_plugins, :handler_plugins, :lifecycle_plugins
 
         # Load all plugins at boot time
         #
@@ -22,13 +23,15 @@ def load_all_plugins(config)
           # Clear existing registries
           @auth_plugins = {}
           @handler_plugins = {}
+          @lifecycle_plugins = []
 
           # Load built-in plugins first
           load_builtin_plugins
 
           # 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]
 
           # Log loaded plugins
           log_loaded_plugins
@@ -71,6 +74,7 @@ def get_handler_plugin(handler_name)
         def clear_plugins
           @auth_plugins = {}
           @handler_plugins = {}
+          @lifecycle_plugins = []
         end
 
         private
@@ -119,6 +123,22 @@ def load_custom_handler_plugins(handler_plugin_dir)
           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 a single custom auth plugin file
         #
         # @param file_path [String] Path to the auth plugin file
@@ -189,6 +209,41 @@ def load_custom_handler_plugin(file_path, handler_plugin_dir)
           @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
+
         # Log summary of loaded plugins
         #
         # @return [void]
@@ -201,6 +256,7 @@ def log_loaded_plugins
 
           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"
         end
 
         # Validate that an auth plugin class name is safe to load
@@ -244,6 +300,27 @@ def valid_handler_class_name?(class_name)
 
           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
       end
     end
   end

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

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 @@ def self.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("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