hooks-ruby 0.0.5 → 0.0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 20afc330ce2c974fa7cb50950e261e0ed8bfb01a9e65aa615f1d1fc4aeff3b90
-  data.tar.gz: 2e561e403eab068f75cce3f41b48ba0642d4fd5f81124d9bea66d563f1472ff4
+  metadata.gz: ee95e33a4d74875095dd510623500145b7cd5af0c7727ec0a56232fc5e28260f
+  data.tar.gz: 4aa8d3e0484bcd27da118d86ba8b36ea87b9d198d9287fc6d14caac61ae041fe
 SHA512:
-  metadata.gz: 1152f3eef93d6c1d872b13dc59154584229f3bfed17a46c2cc748c0f8d1bd9847441dbe96ca2d084bdb6ed6f30077bcf0b49515c8e46bf668c355c8bdb5d52b0
-  data.tar.gz: '038523ad1ed72fc0f27fad4172a15b316c02d52b95936951a3f9f9efbdc2034dc074847665ee43524d7af93f6432ddd91c0ac97b2a0dbafa0f10deea8238fd67'
+  metadata.gz: 10192508ea9438ef5bdd8c5c9b4c522cec0ec5b8e76e8584d21756e87b5560579172141ea11f02b5920c33fcc4d10aa8d9ad9d2d86dabe36585a859be74321e2
+  data.tar.gz: 33a76e31f51eaad74c9a91db2b1e2427dfeae29614acfb31e21cb7c7ac4c8d5f997a4f249f79e2f08e176d2ab8fa1eb0a8bfcbb429218d5a8f7ebf9e3179482c

data/README.md

@@ -153,17 +153,22 @@ This example will assume the following directory structure:
 
 ```text
 ├── config/
-│   ├── hooks.yml                 # global hooks config
-│   ├── puma.rb                   # puma config
+│   ├── hooks.yml                    # global hooks config
+│   ├── puma.rb                      # puma config
 │   └── endpoints/
 │       ├── hello.yml
 │       └── goodbye.yml
 └── plugins/
-    ├── handlers/                 # custom handler plugins
+    ├── handlers/                    # custom handler plugins
     │   ├── hello_handler.rb
     │   └── goodbye_handler.rb
+    ├── lifecycle/                   # custom lifecycle plugins (optional)
+    │   └── my_lifecycle_plugin.rb   # custom lifecycle plugin (optional)
+    ├── instruments/                 # custom instrument plugins (optional)
+    │   ├── stats.rb                 # a custom stats instrument plugin (optional)
+    │   └── failbot.rb               # a custom error notifier instrument plugin (optional)
     └── auth/
-        └── goodbye_auth.rb       # custom auth plugin (optional)
+        └── goodbye_auth.rb          # custom auth plugin (optional)
 ```
 
 Let's go through each step in detail.
@@ -174,8 +179,10 @@ First, create a `hooks.yml` file in the `config` directory. This file will defin
 
 ```yaml
 # file: config/hooks.yml
-handler_plugin_dir: ./plugins/handlers
-auth_plugin_dir: ./plugins/auth
+handler_plugin_dir: ./plugins/handlers # Directory for handler plugins
+auth_plugin_dir: ./plugins/auth # Directory for authentication plugins (optional)
+lifecycle_plugin_dir: ./plugins/lifecycle # Directory for lifecycle plugins (optional)
+instruments_plugin_dir: ./plugins/instruments # Directory for instrument plugins (optional)
 
 # Available endpoints
 # Each endpoint configuration file should be placed in the endpoints directory
@@ -213,6 +220,10 @@ auth:
   type: Goodbye # This is a custom authentication plugin you would define in the plugins/auth
   secret_env_key: GOODBYE_API_KEY # the name of the environment variable containing the secret
   header: Authorization
+
+# Optional additional options for the endpoint (can be anything you want)
+opts:
+  foo: bar
 ```
 
 #### 3. Implement your handler plugins
@@ -251,6 +262,8 @@ class GoodbyeHandler < Hooks::Plugins::Handlers::Base
 end
 ```
 
+See the [Handler Plugins](docs/handler_plugins.md) documentation for more information on how to create your own custom handler plugins and what the values of `payload`, `headers`, and `config` are when the `call` method is invoked.
+
 #### 4. Implement authentication plugins (optional)
 
 If you want to secure your webhook endpoints, you can create custom authentication plugins in the `plugins/auth` directory. Here is an example of a simple authentication plugin for the `/goodbye` endpoint:
@@ -268,7 +281,7 @@ module Hooks
           secret = fetch_secret(config, secret_env_key_name: :secret_env_key)
 
           # check if the Authorization header matches the secret
-          auth_header = headers[config[:header]]
+          auth_header = headers[config[:auth][:header]]
           return false unless auth_header
 
           # compare the Authorization header with the secret
@@ -280,6 +293,8 @@ module Hooks
 end
 ```
 
+To learn more about how you can create your own custom authentication plugins, see the [Auth Plugins](docs/auth_plugins.md) documentation.
+
 #### Summary
 
 What these steps have done is set up a Hooks server that listens for incoming webhook requests at `/webhooks/hello` and `/webhooks/goodbye`. The `/hello` endpoint will respond with a success message without any authentication, while the `/goodbye` endpoint will require a valid `Authorization` header that matches the secret defined in the environment variable `GOODBYE_API_KEY`. Before the `/goodbye` endpoint enters the defined handler, it will first check the authentication plugin to ensure the request is valid.

data/lib/hooks/app/api.rb

@@ -102,14 +102,13 @@ module Hooks
                     validate_auth!(raw_body, headers, endpoint_config, config)
                   end
 
-                  payload = parse_payload(raw_body, headers, symbolize: config[:symbolize_payload])
+                  payload = parse_payload(raw_body, headers, symbolize: false)
                   handler = load_handler(handler_class_name)
-                  normalized_headers = config[:normalize_headers] ? Hooks::Utils::Normalize.headers(headers) : headers
-                  symbolized_headers = config[:symbolize_headers] ? Hooks::Utils::Normalize.symbolize_headers(normalized_headers) : normalized_headers
+                  processed_headers = config[:normalize_headers] ? Hooks::Utils::Normalize.headers(headers) : headers
 
                   response = handler.call(
                     payload:,
-                    headers: symbolized_headers,
+                    headers: processed_headers,
                     config: endpoint_config
                   )
 

data/lib/hooks/app/helpers.rb

@@ -44,9 +44,9 @@ module Hooks
       #
       # @param raw_body [String] The raw request body
       # @param headers [Hash] The request headers
-      # @param symbolize [Boolean] Whether to symbolize keys in parsed JSON (default: true)
-      # @return [Hash, String] Parsed JSON as Hash (optionally symbolized), or raw body if not JSON
-      def parse_payload(raw_body, headers, symbolize: true)
+      # @param symbolize [Boolean] Whether to symbolize keys in parsed JSON (default: false)
+      # @return [Hash, String] Parsed JSON as Hash with string keys, or raw body if not JSON
+      def parse_payload(raw_body, headers, symbolize: false)
         # Optimized content type check - check most common header first
         content_type = headers["Content-Type"] || headers["CONTENT_TYPE"] || headers["content-type"] || headers["HTTP_CONTENT_TYPE"]
 
@@ -55,6 +55,7 @@ module Hooks
           begin
             # Security: Limit JSON parsing depth and complexity to prevent JSON bombs
             parsed_payload = safe_json_parse(raw_body)
+            # Note: symbolize parameter is kept for backward compatibility but defaults to false
             parsed_payload = parsed_payload.transform_keys(&:to_sym) if symbolize && parsed_payload.is_a?(Hash)
             return parsed_payload
           rescue JSON::ParserError, ArgumentError => e

data/lib/hooks/core/config_loader.rb

@@ -20,9 +20,7 @@ module Hooks
         production: true,
         endpoints_dir: "./config/endpoints",
         use_catchall_route: false,
-        symbolize_payload: true,
-        normalize_headers: true,
-        symbolize_headers: true
+        normalize_headers: true
       }.freeze
 
       SILENCE_CONFIG_LOADER_MESSAGES = ENV.fetch(
@@ -142,9 +140,7 @@ module Hooks
           "HOOKS_ENVIRONMENT" => :environment,
           "HOOKS_ENDPOINTS_DIR" => :endpoints_dir,
           "HOOKS_USE_CATCHALL_ROUTE" => :use_catchall_route,
-          "HOOKS_SYMBOLIZE_PAYLOAD" => :symbolize_payload,
           "HOOKS_NORMALIZE_HEADERS" => :normalize_headers,
-          "HOOKS_SYMBOLIZE_HEADERS" => :symbolize_headers,
           "HOOKS_SOME_STRING_VAR" => :some_string_var # Added for test
         }
 
@@ -156,7 +152,7 @@ module Hooks
           case config_key
           when :request_limit, :request_timeout
             env_config[config_key] = value.to_i
-          when :use_catchall_route, :symbolize_payload, :normalize_headers, :symbolize_headers
+          when :use_catchall_route, :normalize_headers
             # Convert string to boolean
             env_config[config_key] = %w[true 1 yes on].include?(value.downcase)
           else

data/lib/hooks/core/config_validator.rb

@@ -26,7 +26,6 @@ module Hooks
         optional(:environment).filled(:string, included_in?: %w[development production])
         optional(:endpoints_dir).filled(:string)
         optional(:use_catchall_route).filled(:bool)
-        optional(:symbolize_payload).filled(:bool)
         optional(:normalize_headers).filled(:bool)
       end
 

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

@@ -43,11 +43,30 @@ module Hooks
           secret = ENV[secret_env_key]
 
           if secret.nil? || !secret.is_a?(String) || secret.strip.empty?
-            raise StandardError, "authentication configuration incomplete: missing secret value bound to #{secret_env_key_name}"
+            raise StandardError, "authentication configuration incomplete: missing secret value for environment variable"
           end
 
           return secret.strip
         end
+
+        # Find a header value by name with case-insensitive matching
+        #
+        # @param headers [Hash] HTTP headers from the request
+        # @param header_name [String] Name of the header to find
+        # @return [String, nil] The header value if found, nil otherwise
+        # @note This method performs case-insensitive header matching
+        def self.find_header_value(headers, header_name)
+          return nil unless headers.respond_to?(:each)
+          return nil if header_name.nil? || header_name.strip.empty?
+
+          target_header = header_name.downcase
+          headers.each do |key, value|
+            if key.to_s.downcase == target_header
+              return value.to_s
+            end
+          end
+          nil
+        end
       end
     end
   end

data/lib/hooks/plugins/auth/hmac.rb

@@ -92,26 +92,32 @@ module Hooks
           validator_config = build_config(config)
 
           # Security: Check raw headers BEFORE normalization to detect tampering
-          return false unless headers.respond_to?(:each)
+          unless headers.respond_to?(:each)
+            log.warn("Auth::HMAC validation failed: Invalid headers object")
+            return false
+          end
 
           signature_header = validator_config[:header]
 
-          # Find the signature header with case-insensitive matching but preserve original value
-          raw_signature = nil
-          headers.each do |key, value|
-            if key.to_s.downcase == signature_header.downcase
-              raw_signature = value.to_s
-              break
-            end
-          end
+          # Find the signature header with case-insensitive matching
+          raw_signature = find_header_value(headers, signature_header)
 
-          return false if raw_signature.nil? || raw_signature.empty?
+          if raw_signature.nil? || raw_signature.empty?
+            log.warn("Auth::HMAC validation failed: Missing or empty signature header '#{signature_header}'")
+            return false
+          end
 
           # Security: Reject signatures with leading/trailing whitespace
-          return false if raw_signature != raw_signature.strip
+          if raw_signature != raw_signature.strip
+            log.warn("Auth::HMAC validation failed: Signature contains leading/trailing whitespace")
+            return false
+          end
 
           # Security: Reject signatures containing null bytes or other control characters
-          return false if raw_signature.match?(/[\u0000-\u001f\u007f-\u009f]/)
+          if raw_signature.match?(/[\u0000-\u001f\u007f-\u009f]/)
+            log.warn("Auth::HMAC validation failed: Signature contains control characters")
+            return false
+          end
 
           # Now we can safely normalize headers for the rest of the validation
           normalized_headers = normalize_headers(headers)
@@ -134,7 +140,13 @@ module Hooks
           )
 
           # Use secure comparison to prevent timing attacks
-          Rack::Utils.secure_compare(computed_signature, provided_signature)
+          result = Rack::Utils.secure_compare(computed_signature, provided_signature)
+          if result
+            log.debug("Auth::HMAC validation successful for header '#{signature_header}'")
+          else
+            log.warn("Auth::HMAC validation failed: Signature mismatch")
+          end
+          result
         rescue StandardError => e
           log.error("Auth::HMAC validation failed: #{e.message}")
           false

data/lib/hooks/plugins/auth/shared_secret.rb

@@ -62,37 +62,56 @@ module Hooks
           validator_config = build_config(config)
 
           # Security: Check raw headers BEFORE normalization to detect tampering
-          return false unless headers.respond_to?(:each)
+          unless headers.respond_to?(:each)
+            log.warn("Auth::SharedSecret validation failed: Invalid headers object")
+            return false
+          end
 
           secret_header = validator_config[:header]
 
-          # Find the secret header with case-insensitive matching but preserve original value
-          raw_secret = nil
-          headers.each do |key, value|
-            if key.to_s.downcase == secret_header.downcase
-              raw_secret = value.to_s
-              break
-            end
-          end
+          # Find the secret header with case-insensitive matching
+          raw_secret = find_header_value(headers, secret_header)
 
-          return false if raw_secret.nil? || raw_secret.empty?
+          if raw_secret.nil? || raw_secret.empty?
+            log.warn("Auth::SharedSecret validation failed: Missing or empty secret header '#{secret_header}'")
+            return false
+          end
 
           stripped_secret = raw_secret.strip
 
           # Security: Reject secrets with leading/trailing whitespace
-          return false if raw_secret != stripped_secret
+          if raw_secret != stripped_secret
+            log.warn("Auth::SharedSecret validation failed: Secret contains leading/trailing whitespace")
+            return false
+          end
 
           # Security: Reject secrets containing null bytes or other control characters
-          return false if raw_secret.match?(/[\u0000-\u001f\u007f-\u009f]/)
+          if raw_secret.match?(/[\u0000-\u001f\u007f-\u009f]/)
+            log.warn("Auth::SharedSecret validation failed: Secret contains control characters")
+            return false
+          end
 
           # Use secure comparison to prevent timing attacks
-          Rack::Utils.secure_compare(secret, stripped_secret)
-        rescue StandardError => _e
+          result = Rack::Utils.secure_compare(secret, stripped_secret)
+          if result
+            log.debug("Auth::SharedSecret validation successful for header '#{secret_header}'")
+          else
+            log.warn("Auth::SharedSecret validation failed: Signature mismatch")
+          end
+          result
+        rescue StandardError => e
+          log.error("Auth::SharedSecret validation failed: #{e.message}")
           false
         end
 
         private
 
+        # Short logger accessor for auth module
+        # @return [Hooks::Log] Logger instance
+        def self.log
+          Hooks::Log.instance
+        end
+
         # Build final configuration by merging defaults with provided config
         #
         # Combines default configuration values with user-provided settings,

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

@@ -15,7 +15,7 @@ module Hooks
         # Process a webhook request
         #
         # @param payload [Hash, String] Parsed request body (JSON Hash) or raw string
-        # @param headers [Hash] HTTP headers (symbolized keys by default)
+        # @param headers [Hash] HTTP headers (string keys, optionally normalized - default is normalized)
         # @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

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.0.5".freeze
+  VERSION = "0.0.7".freeze
 end

metadata

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