hooks-ruby 0.5.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 71eaa47f9861440469e4356da0f891a4f274e5ee2a638b856ac4c27e00e2ddba
-  data.tar.gz: 3e9cf71cac5846098ec371c39831c91cb2f1dba13f5e44937153168a9b7aee5a
+  metadata.gz: 001f3c92a2c07552f4293bc9b5d078e720a6d3ee601ffee80ca83ef1cf9425a5
+  data.tar.gz: 51e7307ad34ea50049dcc2f148e7650626f332854f9f4e409fdf461f0c699547
 SHA512:
-  metadata.gz: c93e5f9cf308dd37cb6a8b064637399e5f4746a85a9967ddea2e6305775e1809eaa59d3944fed1dc0406f801c2a58cd8c0542c3d0453e9dadc34002c4c17bcc5
-  data.tar.gz: fa67425558654ac6e9cfa421d5a7286682bc517a35a2a2a62ef54b51b8c7a589fbcd5f8083b61b45101b4e44b31daab482f21b564852d4ab38b2d1001f6ef852
+  metadata.gz: d36cbea00db3a9752a4acd20732bcb3c61072fb64593345a3b947110fbe29fbeb2b21afe47fb8821546679f003276561ba63caf79eba15838b9a185ea062afc6
+  data.tar.gz: 2c7252c823b0e004a9877fb4c30c57e51ac2322fcf8e503485da526ad504f3345c3aaf08db37736ba9b04df653bf5fe901b6070e9bb92e0aa14d76f9f7a00f22

data/README.md

@@ -140,6 +140,8 @@ Congratulations! You have successfully set up a basic Hooks server which will li
 
 Keep reading to learn how to customize your Hooks server with different plugins for handlers, authentication, and more.
 
+For an in-depth flow diagram of how the Hooks server processes incoming requests, see the [Architecture Flow](docs/architecture_flow.md) documentation.
+
 ### Advanced
 
 This section will go into a more advanced and detailed example of how to setup a Hooks server with custom plugins, authentication, and more. This section also assumes you already have the `hooks-ruby` gem installed via a bundler Gemfile as shown in the [Installation](#installation-) section above.

data/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

data/lib/hooks/core/builder.rb

@@ -15,9 +15,11 @@ module Hooks
       #
       # @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 @@ module Hooks
 
         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)
 

data/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 Hooks
     #       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 @@ module Hooks
       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

data/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 @@ module Hooks
       # 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

data/lib/hooks/version.rb

@@ -4,5 +4,5 @@
 module Hooks
   # Current version of the Hooks webhook framework
   # @return [String] The version string following semantic versioning
-  VERSION = "0.5.1".freeze
+  VERSION = "0.6.0".freeze
 end

data/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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hooks-ruby
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.6.0
 platform: ruby
 authors:
 - github