move utils to its own dir

Author: GrantBirki

lib/hooks.rb

@@ -9,6 +9,11 @@
   require file
 end
 
+# Load all utils
+Dir[File.join(__dir__, "hooks/utils/**/*.rb")].sort.each do |file|
+  require file
+end
+
 # Main module for the Hooks webhook server framework
 module Hooks
   # Build a Rack-compatible webhook server application

lib/hooks/app/api.rb

@@ -206,7 +206,7 @@ def determine_error_code(exception)
                   handler = load_handler(handler_class_name, config[:handler_dir])
 
                   # Normalize the headers based on the endpoint configuration (normalization is the default)
-                  headers = Hooks::Plugins::Utils::Normalize.headers(headers) if config[:normalize_headers]
+                  headers = Hooks::Utils::Normalize.headers(headers) if config[:normalize_headers]
 
                   # Call handler
                   response = handler.call(

lib/hooks/plugins/request_validator/github_webhooks.rb

@@ -26,8 +26,8 @@ def self.valid?(payload:, headers:, secret:, config:)
           signature_header = config.dig(:request_validator, :header) || "X-Hub-Signature-256"
           algorithm = config.dig(:request_validator, :algorithm) || "sha256"
 
-          signature_header = Utils::Normalize.header(signature_header)
-          headers = Utils::Normalize.headers(headers)
+          signature_header = Hooks::Utils::Normalize.header(signature_header)
+          headers = Hooks::Utils::Normalize.headers(headers)
 
           provided_signature = headers[signature_header]
           return false if provided_signature.nil? || provided_signature.empty?

lib/hooks/plugins/utils/normalize.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Hooks
+  module Utils
+    # Utility class for normalizing HTTP headers
+    #
+    # Provides a robust method to consistently format HTTP headers
+    # across the application, handling various edge cases and formats.
+    class Normalize
+      # Normalize a hash of HTTP headers
+      #
+      # @param headers [Hash, #each] Headers hash or hash-like object
+      # @return [Hash] Normalized headers hash with downcased keys and trimmed values
+      #
+      # @example Hash of headers normalization
+      #   headers = { "Content-Type" => "  application/json  ", "X-GitHub-Event" => "push" }
+      #   normalized = Normalize.headers(headers)
+      #   # => { "content-type" => "application/json", "x-github-event" => "push" }
+      #
+      # @example Handle various input types
+      #   Normalize.headers(nil)                    # => nil
+      #   Normalize.headers({})                     # => {}
+      #   Normalize.headers({ "KEY" => ["a", "b"] }) # => { "key" => "a" }
+      #   Normalize.headers({ "Key" => 123 })       # => { "key" => "123" }
+      def self.headers(headers)
+        # Handle nil input
+        return nil if headers.nil?
+
+        # Fast path for non-enumerable inputs (numbers, etc.)
+        return {} unless headers.respond_to?(:each)
+
+        normalized = {}
+
+        headers.each do |key, value|
+          # Skip nil keys or values entirely
+          next if key.nil? || value.nil?
+
+          # Convert key to string, downcase, and strip in one operation
+          normalized_key = key.to_s.downcase.strip
+          next if normalized_key.empty?
+
+          # Handle different value types efficiently
+          normalized_value = case value
+                             when String
+                               value.strip
+                             when Array
+                               # Take first non-empty element for multi-value headers
+                               first_valid = value.find { |v| v && !v.to_s.strip.empty? }
+                               first_valid ? first_valid.to_s.strip : nil
+                             else
+                               value.to_s.strip
+                             end
+
+          # Only add if we have a non-empty value
+          normalized[normalized_key] = normalized_value if normalized_value && !normalized_value.empty?
+        end
+
+        normalized
+      end
+
+      # Normalize a single HTTP header name
+      #
+      # @param header [String] Header name to normalize
+      # @return [String, nil] Normalized header name (downcased and trimmed), or nil if input is nil
+      #
+      # @example Single header normalization
+      #   Normalize.header("  Content-Type  ")  # => "content-type"
+      #   Normalize.header("X-GitHub-Event")    # => "x-github-event"
+      #   Normalize.header("")                  # => ""
+      #   Normalize.header(nil)                 # => nil
+      #
+      # @raise [ArgumentError] If input is not a String or nil
+      def self.header(header)
+        return nil if header.nil?
+        if header.is_a?(String)
+          header.downcase.strip
+        else
+          raise ArgumentError, "Expected a String for header normalization"
+        end
+      end
+    end
+  end
+end

lib/hooks/utils/normalize.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-describe Hooks::Plugins::Utils::Normalize do
+describe Hooks::Utils::Normalize do
   describe ".header" do
     context "when input is a single string" do
       it "normalizes header name to lowercase and trims whitespace" do