Enhance Hooks framework to support user-defined components

- Added ExamplePublisher class to demonstrate custom component usage.
- Updated Hooks.build method to accept arbitrary user-defined components.
- Enhanced GlobalComponents for registration and retrieval of user components.
- Improved ComponentAccess module to allow dynamic access to user-defined components.
- Added tests for user component registration and access in various contexts.
- Introduced new acceptance tests for /webhooks/hello endpoint.

Author: GrantBirki

config.ru

@@ -1,6 +1,36 @@
 # frozen_string_literal: true
 
+# An example file that is a part of the acceptance tests for the Hooks framework.
+# This can be used as a reference point as it is a working implementation of a Hooks application.
+
 require_relative "lib/hooks"
 
-app = Hooks.build(config: "./spec/acceptance/config/hooks.yaml")
+# Example publisher class that simulates publishing messages
+# This class could be literally anything and it is used here to demonstrate how to pass in custom kwargs...
+# ... to the Hooks application which later become available in Handlers throughout the application.
+class ExamplePublisher
+  def initialize
+    @published_messages = []
+  end
+
+  def call(data)
+    @published_messages << data
+    puts "Published: #{data.inspect}"
+    "Message published successfully"
+  end
+
+  def publish(data)
+    call(data)
+  end
+
+  def messages
+    @published_messages
+  end
+end
+
+# Create publisher instance
+publisher = ExamplePublisher.new
+
+# Create and run the hooks application with custom publisher
+app = Hooks.build(config: "./spec/acceptance/config/hooks.yaml", publisher:)
 run app

lib/hooks.rb

@@ -32,11 +32,13 @@ module Hooks
   #
   # @param config [String, Hash] Path to config file or config hash
   # @param log [Logger] Custom logger instance (optional)
+  # @param **extra_components [Hash] Arbitrary user-defined components to make available to handlers
   # @return [Object] Rack-compatible application
-  def self.build(config: nil, log: nil)
+  def self.build(config: nil, log: nil, **extra_components)
     Core::Builder.new(
       config:,
       log:,
+      **extra_components
     ).build
   end
 end

lib/hooks/core/builder.rb

@@ -15,9 +15,11 @@ class Builder
       #
       # @param config [String, Hash] Path to config file or config hash
       # @param log [Logger] Custom logger instance
-      def initialize(config: nil, log: nil)
+      # @param **extra_components [Hash] Arbitrary user-defined components to make available to handlers
+      def initialize(config: nil, log: nil, **extra_components)
         @log = log
         @config_input = config
+        @extra_components = extra_components
       end
 
       # Build and return Rack-compatible application
@@ -37,6 +39,9 @@ def build
 
         Hooks::Log.instance = @log
 
+        # Register user-defined components globally
+        Hooks::Core::GlobalComponents.register_extra_components(@extra_components)
+
         # Hydrate our Retryable instance
         Retry.setup!(log: @log)
 

lib/hooks/core/component_access.rb

@@ -2,12 +2,15 @@
 
 module Hooks
   module Core
-    # Shared module providing access to global components (logger, stats, failbot)
+    # Shared module providing access to global components (logger, stats, failbot, and user-defined components)
     #
     # This module provides a consistent interface for accessing global components
     # across all plugin types, eliminating code duplication and ensuring consistent
     # behavior throughout the application.
     #
+    # In addition to built-in components (log, stats, failbot), this module provides
+    # dynamic access to any user-defined components passed to Hooks.build().
+    #
     # @example Usage in a class that needs instance methods
     #   class MyHandler
     #     include Hooks::Core::ComponentAccess
@@ -28,6 +31,33 @@ module Core
     #       stats.increment("requests.validated")
     #     end
     #   end
+    #
+    # @example Using user-defined components
+    #   # Application setup
+    #   publisher = KafkaPublisher.new
+    #   email_service = EmailService.new
+    #   app = Hooks.build(
+    #     config: "config.yaml",
+    #     publisher: publisher,
+    #     email_service: email_service
+    #   )
+    #
+    #   # Handler implementation
+    #   class WebhookHandler < Hooks::Plugins::Handlers::Base
+    #     include Hooks::Core::ComponentAccess
+    #
+    #     def call(payload:, headers:, env:, config:)
+    #       # Use built-in components
+    #       log.info("Processing webhook")
+    #       stats.increment("webhooks.received")
+    #
+    #       # Use user-defined components
+    #       publisher.send_message(payload, topic: "webhooks")
+    #       email_service.send_notification(payload['email'], "Webhook processed")
+    #
+    #       { status: "success" }
+    #     end
+    #   end
     module ComponentAccess
       # Short logger accessor
       # @return [Hooks::Log] Logger instance for logging messages
@@ -64,6 +94,130 @@ def stats
       def failbot
         Hooks::Core::GlobalComponents.failbot
       end
+
+      # Dynamic method access for user-defined components
+      #
+      # This method enables handlers to call user-defined components as methods.
+      # For example, if a user registers a 'publisher' component, handlers can
+      # call `publisher` or `publisher.some_method` directly.
+      #
+      # The method supports multiple usage patterns:
+      # - Direct access: Returns the component instance for further method calls
+      # - Callable access: If the component responds to #call, invokes it with provided arguments
+      # - Method chaining: Allows fluent interface patterns with registered components
+      #
+      # @param method_name [Symbol] The method name being called
+      # @param args [Array] Arguments passed to the method
+      # @param kwargs [Hash] Keyword arguments passed to the method
+      # @param block [Proc] Block passed to the method
+      # @return [Object] The user component or result of method call
+      # @raise [NoMethodError] If component doesn't exist and no super method available
+      #
+      # @example Accessing a publisher component directly
+      #   # Given: Hooks.build(publisher: MyKafkaPublisher.new)
+      #   class MyHandler < Hooks::Plugins::Handlers::Base
+      #     def call(payload:, headers:, env:, config:)
+      #       publisher.send_message(payload, topic: "webhooks")
+      #       { status: "published" }
+      #     end
+      #   end
+      #
+      # @example Using a callable component (Proc/Lambda)
+      #   # Given: Hooks.build(notifier: ->(msg) { puts "Notification: #{msg}" })
+      #   class MyHandler < Hooks::Plugins::Handlers::Base
+      #     def call(payload:, headers:, env:, config:)
+      #       notifier.call("New webhook received")
+      #       # Or use the shorthand syntax:
+      #       notifier("Processing webhook for #{payload['user_id']}")
+      #       { status: "notified" }
+      #     end
+      #   end
+      #
+      # @example Using a service object
+      #   # Given: Hooks.build(email_service: EmailService.new(api_key: "..."))
+      #   class MyHandler < Hooks::Plugins::Handlers::Base
+      #     def call(payload:, headers:, env:, config:)
+      #       email_service.send_notification(
+      #         to: payload['email'],
+      #         subject: "Webhook Processed",
+      #         body: "Your webhook has been successfully processed"
+      #       )
+      #       { status: "email_sent" }
+      #     end
+      #   end
+      #
+      # @example Passing blocks to components
+      #   # Given: Hooks.build(batch_processor: BatchProcessor.new)
+      #   class MyHandler < Hooks::Plugins::Handlers::Base
+      #     def call(payload:, headers:, env:, config:)
+      #       batch_processor.process_with_callback(payload) do |result|
+      #         log.info("Batch processing completed: #{result}")
+      #       end
+      #       { status: "batch_queued" }
+      #     end
+      #   end
+      def method_missing(method_name, *args, **kwargs, &block)
+        component = Hooks::Core::GlobalComponents.get_extra_component(method_name)
+
+        if component
+          # If called with arguments or block, try to call the component as a method
+          if args.any? || kwargs.any? || block
+            component.call(*args, **kwargs, &block)
+          else
+            # Otherwise return the component itself
+            component
+          end
+        else
+          # Fall back to normal method_missing behavior
+          super
+        end
+      end
+
+      # Respond to user-defined component names
+      #
+      # This method ensures that handlers properly respond to user-defined component
+      # names, enabling proper method introspection and duck typing support.
+      #
+      # @param method_name [Symbol] The method name being checked
+      # @param include_private [Boolean] Whether to include private methods
+      # @return [Boolean] True if method exists or is a user component
+      #
+      # @example Checking if a component is available
+      #   class MyHandler < Hooks::Plugins::Handlers::Base
+      #     def call(payload:, headers:, env:, config:)
+      #       if respond_to?(:publisher)
+      #         publisher.send_message(payload)
+      #         { status: "published" }
+      #       else
+      #         log.warn("Publisher not available, skipping message send")
+      #         { status: "skipped" }
+      #       end
+      #     end
+      #   end
+      #
+      # @example Conditional component usage
+      #   class MyHandler < Hooks::Plugins::Handlers::Base
+      #     def call(payload:, headers:, env:, config:)
+      #       results = { status: "processed" }
+      #
+      #       # Only use analytics if available
+      #       if respond_to?(:analytics)
+      #         analytics.track_event("webhook_processed", payload)
+      #         results[:analytics] = "tracked"
+      #       end
+      #
+      #       # Only send notifications if notifier is available
+      #       if respond_to?(:notifier)
+      #         notifier.call("Webhook processed: #{payload['id']}")
+      #         results[:notification] = "sent"
+      #       end
+      #
+      #       results
+      #     end
+      #   end
+      def respond_to_missing?(method_name, include_private = false)
+        Hooks::Core::GlobalComponents.extra_component_exists?(method_name) || super
+      end
     end
   end
 end

lib/hooks/core/global_components.rb

@@ -1,11 +1,48 @@
 # frozen_string_literal: true
 
+require "monitor"
+
 module Hooks
   module Core
     # Global registry for shared components accessible throughout the application
     class GlobalComponents
       @test_stats = nil
       @test_failbot = nil
+      @extra_components = {}
+      @mutex = Monitor.new
+
+      # Register arbitrary user-defined components. This method is called on application startup
+      #
+      # @param components [Hash] Hash of component name => component instance
+      # @return [void]
+      def self.register_extra_components(components)
+        @mutex.synchronize do
+          @extra_components = components.dup.freeze
+        end
+      end
+
+      # Get a user-defined component by name
+      #
+      # @param name [Symbol, String] Component name
+      # @return [Object, nil] Component instance or nil if not found
+      def self.get_extra_component(name)
+        @extra_components[name.to_sym] || @extra_components[name.to_s]
+      end
+
+      # Get all registered user component names
+      #
+      # @return [Array<Symbol>] Array of component names
+      def self.extra_component_names
+        @extra_components.keys.map(&:to_sym)
+      end
+
+      # Check if a user component exists
+      #
+      # @param name [Symbol, String] Component name
+      # @return [Boolean] True if component exists
+      def self.extra_component_exists?(name)
+        @extra_components.key?(name.to_sym) || @extra_components.key?(name.to_s)
+      end
 
       # Get the global stats instance
       # @return [Hooks::Plugins::Instruments::StatsBase] Stats instance for metrics reporting
@@ -22,29 +59,36 @@ def self.failbot
       # Set a custom stats instance (for testing)
       # @param stats_instance [Object] Custom stats instance
       def self.stats=(stats_instance)
-        @test_stats = stats_instance
+        @mutex.synchronize do
+          @test_stats = stats_instance
+        end
       end
 
       # Set a custom failbot instance (for testing)
       # @param failbot_instance [Object] Custom failbot instance
       def self.failbot=(failbot_instance)
-        @test_failbot = failbot_instance
+        @mutex.synchronize do
+          @test_failbot = failbot_instance
+        end
       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
-        })
+        @mutex.synchronize do
+          @test_stats = nil
+          @test_failbot = nil
+          @extra_components = {}.freeze
+          # 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

spec/acceptance/acceptance_tests.rb

@@ -680,5 +680,22 @@ def expired_unix_timestamp(seconds_ago = 600)
         expect(body["status"]).to eq("success")
       end
     end
+
+    describe "hello" do
+      it "responds to the /webhooks/hello endpoint with a simple message" do
+        payload = {}.to_json
+        headers = { "Content-Type" => "application/json" }
+        response = make_request(:post, "/webhooks/hello", payload, headers)
+
+        expect_response(response, Net::HTTPSuccess)
+        body = parse_json_response(response)
+        expect(body["status"]).to eq("success")
+        expect(body["handler"]).to eq("Hello")
+        expect(body).to have_key("timestamp")
+        expect(body["timestamp"]).to be_a(String)
+        expect(body["messages"]).to be_a(Array)
+        expect(body["messages"]).to include("hello")
+      end
+    end
   end
 end

spec/acceptance/plugins/handlers/hello.rb

@@ -2,10 +2,13 @@
 
 class Hello < Hooks::Plugins::Handlers::Base
   def call(payload:, headers:, env:, config:)
+    publisher.publish("hello")
+
     {
       status: "success",
       handler: self.class.name,
-      timestamp: Time.now.utc.iso8601
+      timestamp: Time.now.utc.iso8601,
+      messages: publisher.messages,
     }
   end
 end