hooks-ruby 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2a1dfcc57a6bae5c2e5bd01f7e6165218220f04258ac8fab3ab256b685454bb6
-  data.tar.gz: 724dbe5463d5bf223ef9652e566b448f38a4270d0131446e302236685ba43710
+  metadata.gz: ae1757617b84df588de7eb343799b93d1dfc6326c3d54ab1a2d578aa2d3e3b8e
+  data.tar.gz: a39cfa8162346d536ab5a543dfcf7517162282ba3a74098cd276bc76c636a41c
 SHA512:
-  metadata.gz: d21c5cce4267f7d5209e495415c90b21375686e1f8d65d9d2080d3d3aa2677344a48cbc1167e4e83bff6a27223e6f12d891a6416ad122b54ee0d36832dd08311
-  data.tar.gz: 8b0fd57ee957d8eb8d58d3556f7f4ab145a7eb5cac82286c2cefd439a77bc28f6e03abe38484154b308b59b3b30e69bd749fec968fe053ebb0b4f9560ae0eb17
+  metadata.gz: da5353fda88b8d348e7b743e155642376ad886b5e77a38cb08148a9a6fbb5bece88c099125bb4738d41a09e3d3e0b5c29bd317bafa3789caa595d02f1c7217a2
+  data.tar.gz: 0ba9c613e80a889da7b1fd7b6b4b84b53190aae6db27184d7caa0a90806c3d266f0fff06c4bff1cef702c0879f772056fde5c1b697d817852130167eb0724ebd

data/README.md

@@ -58,7 +58,7 @@ Here is a very high-level overview of how Hooks works:
     ```ruby
     # file: plugins/handlers/my_custom_handler.rb
     class MyCustomHandler < Hooks::Plugins::Handlers::Base
-      def call(payload:, headers:, config:)
+      def call(payload:, headers:, env:, config:)
         # Process the incoming webhook - optionally use the payload and headers
         # to perform some action or validation
         # For this example, we will just return a success message
@@ -233,7 +233,7 @@ Create custom handler plugins in the `plugins/handlers` directory to process inc
 ```ruby
 # file: plugins/handlers/hello_handler.rb
 class HelloHandler < Hooks::Plugins::Handlers::Base
-  def call(payload:, headers:, config:)
+  def call(payload:, headers:, env:, config:)
     # Process the incoming webhook - optionally use the payload and headers
     # to perform some action or validation
     # For this example, we will just return a success message
@@ -251,7 +251,7 @@ And another handler plugin for the `/goodbye` endpoint:
 ```ruby
 # file: plugins/handlers/goodbye_handler.rb
 class GoodbyeHandler < Hooks::Plugins::Handlers::Base
-  def call(payload:, headers:, config:)
+  def call(payload:, headers:, env:, config:)
     # Ditto for the goodbye endpoint
     {
       message: "goodbye webhook processed successfully",

data/lib/hooks/app/api.rb

@@ -5,7 +5,9 @@ require "json"
 require "securerandom"
 require_relative "helpers"
 require_relative "auth/auth"
+require_relative "rack_env_builder"
 require_relative "../plugins/handlers/base"
+require_relative "../plugins/handlers/error"
 require_relative "../plugins/handlers/default"
 require_relative "../core/logger_factory"
 require_relative "../core/log"
@@ -65,41 +67,27 @@ module Hooks
               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
+                  rack_env_builder = RackEnvBuilder.new(
+                    request,
+                    headers,
+                    request_context,
+                    endpoint_config,
+                    start_time,
+                    full_path
+                  )
+                  rack_env = rack_env_builder.build
 
                   # Call lifecycle hooks: on_request
                   Core::PluginLoader.lifecycle_plugins.each do |plugin|
                     plugin.on_request(rack_env)
                   end
 
-                  enforce_request_limits(config)
+                  enforce_request_limits(config, request_context)
                   request.body.rewind
                   raw_body = request.body.read
 
                   if endpoint_config[:auth]
-                    validate_auth!(raw_body, headers, endpoint_config, config)
+                    validate_auth!(raw_body, headers, endpoint_config, config, request_context)
                   end
 
                   payload = parse_payload(raw_body, headers, symbolize: false)
@@ -109,6 +97,7 @@ module Hooks
                   response = handler.call(
                     payload:,
                     headers: processed_headers,
+                    env: rack_env,
                     config: endpoint_config
                   )
 
@@ -122,22 +111,50 @@ module Hooks
                   status 200
                   content_type "application/json"
                   response.to_json
+                rescue Hooks::Plugins::Handlers::Error => e
+                  # Handler called error! method - immediately return error response and exit the request
+                  log.debug("handler #{handler_class_name} called `error!` method")
+
+                  error_response = nil
+
+                  status e.status
+                  case e.body
+                  when String
+                    content_type "text/plain"
+                    error_response = e.body
+                  else
+                    content_type "application/json"
+                    error_response = e.body.to_json
+                  end
+
+                  return error_response
                 rescue StandardError => e
-                  # Call lifecycle hooks: on_error
+                  err_msg = "Error processing webhook event with handler: #{handler_class_name} - #{e.message} " \
+                    "- request_id: #{request_id} - path: #{full_path} - method: #{http_method} - " \
+                    "backtrace: #{e.backtrace.join("\n")}"
+                  log.error(err_msg)
+
+                  # call lifecycle hooks: on_error if the rack_env is available
+                  # if the rack_env is not available, it means the error occurred before we could build it
                   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}")
+                  # construct a standardized error response
                   error_response = {
-                    error: e.message,
-                    code: determine_error_code(e),
+                    error: "server_error",
+                    message: "an unexpected error occurred while processing the request",
                     request_id:
                   }
-                  error_response[:backtrace] = e.backtrace unless config[:production]
-                  status error_response[:code]
+
+                  # enrich the error response with details if not in production
+                  error_response[:backtrace] = e.backtrace.join("\n") unless config[:production]
+                  error_response[:message] = e.message unless config[:production]
+                  error_response[:handler] = handler_class_name unless config[:production]
+
+                  status determine_error_code(e)
                   content_type "application/json"
                   error_response.to_json
                 end

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

@@ -16,30 +16,45 @@ module Hooks
       # @param headers [Hash] The request headers.
       # @param endpoint_config [Hash] The endpoint configuration, must include :auth key.
       # @param global_config [Hash] The global configuration (optional, for compatibility).
+      # @param request_context [Hash] Context for the request, e.g. request ID, path, handler (optional).
       # @raise [StandardError] Raises error if authentication fails or is misconfigured.
       # @return [void]
       # @note This method will halt execution with an error if authentication fails.
-      def validate_auth!(payload, headers, endpoint_config, global_config = {})
+      def validate_auth!(payload, headers, endpoint_config, global_config = {}, request_context = {})
         auth_config = endpoint_config[:auth]
+        request_id = request_context&.dig(:request_id)
 
         # 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)
+          log.error("authentication configuration missing or invalid - request_id: #{request_id}")
+          error!({
+            error: "authentication_configuration_error",
+            message: "authentication configuration missing or invalid",
+            request_id:
+          }, 500)
         end
 
         # Get auth plugin from loaded plugins registry (boot-time loaded only)
         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)
+          log.error("failed to load auth plugin '#{auth_type}': #{e.message} - request_id: #{request_id}")
+          error!({
+            error: "authentication_plugin_error",
+            message: "unsupported auth type '#{auth_type}'",
+            request_id:
+          }, 400)
         end
 
         log.debug("validating auth for request with auth_class: #{auth_class.name}")
         unless auth_class.valid?(payload:, headers:, config: endpoint_config)
-          log.warn("authentication failed for request with auth_class: #{auth_class.name}")
-          error!("authentication failed", 401)
+          log.warn("authentication failed for request with auth_class: #{auth_class.name} - request_id: #{request_id}")
+          error!({
+            error: "authentication_failed",
+            message: "authentication failed",
+            request_id:
+          }, 401)
         end
       end
 

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

@@ -27,20 +27,36 @@ module Hooks
         # :nocov:
         proc do
           request_id = uuid
+          start_time = Time.now
 
           # Use captured values
           config = captured_config
           log = captured_logger
 
+          full_path = "#{config[:root_path]}/#{params[:path]}"
+
+          handler_class_name = "DefaultHandler"
+          http_method = "post"
+
           # Set request context for logging
           request_context = {
             request_id:,
-            path: "/#{params[:path]}",
-            handler: "DefaultHandler"
+            path: full_path,
+            handler: handler_class_name
           }
 
           Hooks::Core::LogContext.with(request_context) do
             begin
+              rack_env_builder = RackEnvBuilder.new(
+                request,
+                headers,
+                request_context,
+                config,
+                start_time,
+                full_path
+              )
+              rack_env = rack_env_builder.build
+
               # Enforce request limits
               enforce_request_limits(config)
 
@@ -58,32 +74,34 @@ module Hooks
               response = handler.call(
                 payload:,
                 headers:,
+                env: rack_env,
                 config: {}
               )
 
-              log.info "request processed successfully with default handler (id: #{request_id})"
-
-              # Return response as JSON string when using txt format
+              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
-
+              response.to_json
             rescue StandardError => e
-              log.error "request failed: #{e.message} (id: #{request_id})"
+              err_msg = "Error processing webhook event with handler: #{handler_class_name} - #{e.message} " \
+                "- request_id: #{request_id} - path: #{full_path} - method: #{http_method} - " \
+                "backtrace: #{e.backtrace.join("\n")}"
+              log.error(err_msg)
 
-              # Return error response
+              # construct a standardized error response
               error_response = {
-                error: e.message,
-                code: determine_error_code(e),
-                request_id: request_id
+                error: "server_error",
+                message: "an unexpected error occurred while processing the request",
+                request_id:
               }
 
-              # Add backtrace in all environments except production
-              unless config[:production] == true
-                error_response[:backtrace] = e.backtrace
-              end
+              # enrich the error response with details if not in production
+              error_response[:backtrace] = e.backtrace.join("\n") unless config[:production]
+              error_response[:message] = e.message unless config[:production]
+              error_response[:handler] = handler_class_name unless config[:production]
 
-              status error_response[:code]
+              status determine_error_code(e)
               content_type "application/json"
               error_response.to_json
             end

data/lib/hooks/app/helpers.rb

@@ -17,10 +17,11 @@ module Hooks
       # Enforce request size and timeout limits
       #
       # @param config [Hash] The configuration hash, must include :request_limit
+      # @param request_context [Hash] Context for the request, e.g. request ID (optional)
       # @raise [StandardError] Halts with error if request body is too large
       # @return [void]
       # @note Timeout enforcement should be handled at the server level (e.g., Puma)
-      def enforce_request_limits(config)
+      def enforce_request_limits(config, request_context = {})
         # Optimized content length check - check most common sources first
         content_length = request.content_length if respond_to?(:request) && request.respond_to?(:content_length)
 
@@ -34,7 +35,8 @@ module Hooks
         content_length = content_length&.to_i
 
         if content_length && content_length > config[:request_limit]
-          error!("request body too large", 413)
+          request_id = request_context&.dig(:request_id)
+          error!({ error: "request_body_too_large", message: "request body too large", request_id: }, 413)
         end
 
         # Note: Timeout enforcement would typically be handled at the server level (Puma, etc.)
@@ -76,13 +78,14 @@ module Hooks
       # @return [Object] An instance of the loaded handler class
       # @raise [StandardError] If handler cannot be found
       def load_handler(handler_class_name)
-        # Get handler class from loaded plugins registry (boot-time loaded only)
-        begin
-          handler_class = Core::PluginLoader.get_handler_plugin(handler_class_name)
-          return handler_class.new
-        rescue => e
-          error!("failed to get handler '#{handler_class_name}': #{e.message}", 500)
-        end
+        # Get handler class from loaded plugins registry (the registry is populated at boot time)
+        # NOTE: We create a new instance per request (not reuse boot-time instances) because:
+        # - Security: Prevents state pollution and information leakage between requests
+        # - Thread Safety: Avoids race conditions from shared instance state
+        # - Performance: Handler instantiation is fast; reusing instances provides minimal gain
+        # - Memory: Allows garbage collection of short-lived objects (Ruby GC optimization)
+        handler_class = Core::PluginLoader.get_handler_plugin(handler_class_name)
+        return handler_class.new
       end
 
       private

data/lib/hooks/app/rack_env_builder.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Hooks
+  module App
+    # Builds Rack environment hash for lifecycle hooks and handler processing
+    #
+    # This class centralizes the construction of the Rack environment that gets
+    # passed to lifecycle hooks and handlers, ensuring consistency and making
+    # it easy to reference the environment structure.
+    #
+    # @example Building a Rack environment
+    #   builder = RackEnvBuilder.new(request, headers, request_context)
+    #   rack_env = builder.build
+    #
+    class RackEnvBuilder
+      # Initialize the builder with required components
+      #
+      # @param request [Grape::Request] The Grape request object
+      # @param headers [Hash] Request headers hash
+      # @param request_context [Hash] Request context containing metadata
+      # @option request_context [String] :request_id Unique request identifier
+      # @option request_context [String] :handler Handler class name
+      # @param endpoint_config [Hash] Endpoint configuration
+      # @param start_time [Time] Request start time
+      # @param full_path [String] Full request path including root path
+      def initialize(request, headers, request_context, endpoint_config, start_time, full_path)
+        @request = request
+        @headers = headers
+        @request_context = request_context
+        @endpoint_config = endpoint_config
+        @start_time = start_time
+        @full_path = full_path
+      end
+
+      # Build the Rack environment hash
+      #
+      # Constructs a hash containing standard Rack environment variables
+      # plus Hooks-specific extensions for lifecycle hooks and handlers.
+      #
+      # @return [Hash] Complete Rack environment hash
+      def build
+        rack_env = build_base_environment
+        add_http_headers(rack_env)
+        rack_env
+      end
+
+      private
+
+      # Build the base Rack environment with standard and Hooks-specific variables
+      # This pretty much creates everything plus the kitchen sink. It will be very rich in information
+      # and will be used by lifecycle hooks and handlers to access request metadata.
+      #
+      # @return [Hash] Base environment hash
+      def build_base_environment
+        {
+          "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_context[:request_id],
+          "hooks.handler" => @request_context[:handler],
+          "hooks.endpoint_config" => @endpoint_config,
+          "hooks.start_time" => @start_time.iso8601,
+          "hooks.full_path" => @full_path
+        }
+      end
+
+      # Add HTTP headers to the environment with proper Rack naming convention
+      #
+      # @param rack_env [Hash] Environment hash to modify
+      def add_http_headers(rack_env)
+        @headers.each do |key, value|
+          env_key = "HTTP_#{key.upcase.tr('-', '_')}"
+          rack_env[env_key] = value
+        end
+      end
+    end
+  end
+end

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

@@ -2,6 +2,7 @@
 
 require_relative "../../core/global_components"
 require_relative "../../core/component_access"
+require_relative "error"
 
 module Hooks
   module Plugins
@@ -16,12 +17,35 @@ module Hooks
         #
         # @param payload [Hash, String] Parsed request body (JSON Hash) or raw string
         # @param headers [Hash] HTTP headers (string keys, optionally normalized - default is normalized)
+        # @param env [Hash] Rack environment (contains the request context, headers, etc - very rich context)
         # @param config [Hash] Merged endpoint configuration including opts section (symbolized keys)
         # @return [Hash, String, nil] Response body (will be auto-converted to JSON)
         # @raise [NotImplementedError] if not implemented by subclass
-        def call(payload:, headers:, config:)
+        def call(payload:, headers:, env:, config:)
           raise NotImplementedError, "Handler must implement #call method"
         end
+
+        # Terminate request processing with a custom error response
+        #
+        # This method provides the same interface as Grape's `error!` method,
+        # allowing handlers to immediately stop processing and return a specific
+        # error response to the client.
+        #
+        # @param body [Object] The error body/data to return to the client
+        # @param status [Integer] The HTTP status code to return (default: 500)
+        # @raise [Hooks::Plugins::Handlers::Error] Always raises to terminate processing
+        #
+        # @example Return a custom error with status 400
+        #   error!({ error: "validation_failed", message: "Invalid payload" }, 400)
+        #
+        # @example Return a simple string error with status 401
+        #   error!("Unauthorized", 401)
+        #
+        # @example Return an error with default 500 status
+        #   error!({ error: "internal_error", message: "Something went wrong" })
+        def error!(body, status = 500)
+          raise Error.new(body, status)
+        end
       end
     end
   end

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

@@ -20,6 +20,7 @@ class DefaultHandler < Hooks::Plugins::Handlers::Base
   #
   # @param payload [Hash, String] The webhook payload (parsed JSON or raw string)
   # @param headers [Hash<String, String>] HTTP headers from the webhook request
+  # @param env [Hash] Rack environment (contains the request context, headers, config, etc - very rich context)
   # @param config [Hash] Endpoint configuration containing handler options
   # @return [Hash] Response indicating successful processing
   # @option config [Hash] :opts Additional handler-specific configuration options
@@ -29,10 +30,11 @@ class DefaultHandler < Hooks::Plugins::Handlers::Base
   #   response = handler.call(
   #     payload: { "event" => "push" },
   #     headers: { "Content-Type" => "application/json" },
+  #     env: { "REQUEST_METHOD" => "POST", "hooks.request_id" => "12345" },
   #     config: { opts: {} }
   #   )
   #   # => { message: "webhook processed successfully", handler: "DefaultHandler", timestamp: "..." }
-  def call(payload:, headers:, config:)
+  def call(payload:, headers:, env:, config:)
 
     log.info("🔔 Default handler invoked for webhook 🔔")
 
@@ -41,6 +43,10 @@ class DefaultHandler < Hooks::Plugins::Handlers::Base
       log.debug("received payload: #{payload.inspect}")
     end
 
+    if env
+      log.debug("default handler got a request with the following request_id: #{env['hooks.request_id']}")
+    end
+
     {
       message: "webhook processed successfully",
       handler: "DefaultHandler",

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Hooks
+  module Plugins
+    module Handlers
+      # Custom exception class for handler errors
+      #
+      # This exception is used when handlers call the `error!` method to
+      # immediately terminate request processing and return a specific error response.
+      # It carries the error details back to the Grape API context where it can be
+      # properly formatted and returned to the client.
+      #
+      # @example Usage in handler
+      #   error!({ error: "validation_failed", message: "Invalid payload" }, 400)
+      #
+      # @see Hooks::Plugins::Handlers::Base#error!
+      class Error < StandardError
+        # @return [Object] The error body/data to return to the client
+        attr_reader :body
+
+        # @return [Integer] The HTTP status code to return
+        attr_reader :status
+
+        # Initialize a new handler error
+        #
+        # @param body [Object] The error body/data to return to the client
+        # @param status [Integer] The HTTP status code to return (default: 500)
+        def initialize(body, status = 500)
+          @body = body
+          @status = status.to_i
+          super("Handler error: #{status} - #{body}")
+        end
+      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.1.0".freeze
+  VERSION = "0.2.0".freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hooks-ruby
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - github
@@ -129,6 +129,7 @@ files:
 - lib/hooks/app/endpoints/health.rb
 - lib/hooks/app/endpoints/version.rb
 - lib/hooks/app/helpers.rb
+- lib/hooks/app/rack_env_builder.rb
 - lib/hooks/core/builder.rb
 - lib/hooks/core/component_access.rb
 - lib/hooks/core/config_loader.rb
@@ -145,6 +146,7 @@ files:
 - lib/hooks/plugins/auth/timestamp_validator.rb
 - lib/hooks/plugins/handlers/base.rb
 - lib/hooks/plugins/handlers/default.rb
+- lib/hooks/plugins/handlers/error.rb
 - lib/hooks/plugins/instruments/failbot.rb
 - lib/hooks/plugins/instruments/failbot_base.rb
 - lib/hooks/plugins/instruments/stats.rb