hooks-ruby 0.0.2 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7588a4a6fdf58e7c927dc4b20b9fa330db86db672f5c779a4c46d51e7e41f386
-  data.tar.gz: 02bdb939c52fd501387856f432a11a82f842d25053d9e73ef3967eb12be03c7a
+  metadata.gz: 2cab1bf1a1f61011d053be5beb9d48738bd439303b87743e41e10df0b4b9d65c
+  data.tar.gz: 9b9abc62fff8f0f2f77ad94949bc7e067fff5a2f072bbf73f8e6e55c03865714
 SHA512:
-  metadata.gz: f11eddcaf09095e1d68bcfeeeba3660eab7e3a9bf42744d780987bfb4b54db7cfa6691c4cc435c5dbda4eb3ee60065a6f3c6239df87bf5b5587f638bb3c8d094
-  data.tar.gz: af806e9c8144ed2da97e723c3a4dfcb54f2fd8db85970e806aa3f2f56e6ef8ca665ae157066f1456126804c2bba8ba573d5f59f717de0249148d81d11f9e848d
+  metadata.gz: 40f769a697bd61c6c851eef217fadc66387c49d37c19639a283dd770ca8be8889a13eeba2785a41c53edcdef29327231527405a9de21b2b4620416196da792c2
+  data.tar.gz: 119a371d927f240aefe4e74c822b48318032250e7cbf060a9bd077b1375823137b419f7d1e2d27d775e6468d38843afb45ec9c8cd8a71a22d82226160c66043e

data/README.md

@@ -66,13 +66,13 @@ Here is a very high-level overview of how Hooks works:
           status: "success",
           handler: "MyCustomHandler",
           payload_received: payload,
-          timestamp: Time.now.iso8601
+          timestamp: Time.now.utc.iso8601
         }
       end
     end
     ```
 
-That is pretty much it! Below you will find more detailed instructions on how to install and use Hooks, as well as how to create your own plugins. This high-level overview should give you a good idea of how Hooks works and how you can use it to handle webhooks in your applications. You may also be interested in using your own custom authentication plugins to secure your webhook endpoints, which is covered in the [Authentication](#authentication) section below.
+That is pretty much it! Below you will find more detailed instructions on how to install and use Hooks, as well as how to create your own plugins. This high-level overview should give you a good idea of how Hooks works and how you can use it to handle webhooks in your applications. You may also be interested in using your own custom authentication plugins to secure your webhook endpoints, which is covered in the [Authentication](#authentication-plugins) section below.
 
 ## Installation 💎
 
@@ -102,7 +102,7 @@ First, create a `config.ru` file:
 
 ```ruby
 # file: config.ru
-require "hooks-ruby"
+require "hooks"
 
 # See the config documentation below for the full list of available options
 # For this example, we will just set use_catchall_route to true
@@ -229,7 +229,7 @@ class HelloHandler < Hooks::Plugins::Handlers::Base
     {
       message: "webhook processed successfully",
       handler: "HelloHandler",
-      timestamp: Time.now.iso8601
+      timestamp: Time.now.utc.iso8601
     }
   end
 end
@@ -245,7 +245,7 @@ class GoodbyeHandler < Hooks::Plugins::Handlers::Base
     {
       message: "goodbye webhook processed successfully",
       handler: "GoodbyeHandler",
-      timestamp: Time.now.iso8601
+      timestamp: Time.now.utc.iso8601
     }
   end
 end
@@ -286,10 +286,26 @@ What these steps have done is set up a Hooks server that listens for incoming we
 
 To see a live working version of this example, check out the [`spec/acceptance/`](spec/acceptance/) directory in this repository, which is used for acceptance testing the Hooks framework. It contains a complete example of how to set up a Hooks server with custom plugins, authentication, and more.
 
-### Authentication
+### Authentication Plugins
 
 See the [Auth Plugins](docs/auth_plugins.md) documentation for even more information on how to create your own custom authentication plugins.
 
+### Handler Plugins
+
+See the [Handler Plugins](docs/handler_plugins.md) documentation for in-depth information about handler plugins and how you can create your own to extend the functionality of the Hooks framework for your own deployment.
+
+### Lifecycle Plugins
+
+See the [Lifecycle Plugins](docs/lifecycle_plugins.md) documentation for information on how to create lifecycle plugins that can hook into the request/response/error lifecycle of the Hooks framework, allowing you to add custom behavior at various stages of processing webhook requests.
+
+### Instrument Plugins
+
+See the [Instrument Plugins](docs/instrument_plugins.md) documentation for information on how to create instrument plugins that can be used to collect metrics or report exceptions during webhook processing. These plugins can be used to integrate with monitoring and alerting systems.
+
+### Configuration
+
+See the [Configuration](docs/configuration.md) documentation for detailed information on how to configure your Hooks server, including global options, endpoint options, and more.
+
 ## Contributing 🤝
 
 See the [Contributing](CONTRIBUTING.md) document for information on how to contribute to the Hooks project, including setting up your development environment, running tests, and releasing new versions.

data/hooks.gemspec

@@ -22,7 +22,6 @@ Gem::Specification.new do |spec|
   spec.add_dependency "retryable", "~> 3.0", ">= 3.0.5"
   spec.add_dependency "dry-schema", "~> 1.14", ">= 1.14.1"
   spec.add_dependency "grape", "~> 2.3"
-  spec.add_dependency "grape-swagger", "~> 2.1", ">= 2.1.2"
   spec.add_dependency "puma", "~> 6.6"
 
   spec.required_ruby_version = Gem::Requirement.new(">= 3.2.2")

data/lib/hooks/app/api.rb

@@ -9,6 +9,7 @@ require_relative "../plugins/handlers/base"
 require_relative "../plugins/handlers/default"
 require_relative "../core/logger_factory"
 require_relative "../core/log"
+require_relative "../core/plugin_loader"
 
 # Import all core endpoint classes dynamically
 Dir[File.join(__dir__, "endpoints/**/*.rb")].sort.each { |file| require file }
@@ -21,14 +22,13 @@ module Hooks
       include Hooks::App::Auth
 
       class << self
-        attr_reader :start_time
+        attr_reader :server_start_time
       end
 
       # Create a new configured API class
       def self.create(config:, endpoints:, log:)
-        @start_time = Time.now
-
-        Hooks::Log.instance = log
+        # :nocov:
+        @server_start_time = Time.now
 
         api_class = Class.new(Grape::API) do
           content_type :json, "application/json"
@@ -48,23 +48,57 @@ module Hooks
           endpoints.each do |endpoint_config|
             full_path = "#{config[:root_path]}#{endpoint_config[:path]}"
             handler_class_name = endpoint_config[:handler]
+            http_method = (endpoint_config[:method] || "post").downcase.to_sym
 
-            post(full_path) do
+            send(http_method, full_path) do
               request_id = uuid
+              start_time = Time.now
+
               request_context = {
                 request_id:,
                 path: full_path,
                 handler: handler_class_name
               }
 
+              # everything wrapped in the log context has access to the request context and includes it in log messages
+              # ex: Hooks::Log.info("message") will include request_id, path, handler, etc
               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
+
+                  # Call lifecycle hooks: on_request
+                  Core::PluginLoader.lifecycle_plugins.each do |plugin|
+                    plugin.on_request(rack_env)
+                  end
+
                   enforce_request_limits(config)
                   request.body.rewind
                   raw_body = request.body.read
 
                   if endpoint_config[:auth]
-                    log.info "validating request (id: #{request_id}, handler: #{handler_class_name})"
                     validate_auth!(raw_body, headers, endpoint_config, config)
                   end
 
@@ -78,16 +112,29 @@ module Hooks
                     config: endpoint_config
                   )
 
-                  log.info "request processed successfully (id: #{request_id}, handler: #{handler_class_name})"
+                  # Call lifecycle hooks: on_response
+                  Core::PluginLoader.lifecycle_plugins.each do |plugin|
+                    plugin.on_response(rack_env, response)
+                  end
+
+                  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
-                rescue => e
-                  log.error "request failed: #{e.message} (id: #{request_id}, handler: #{handler_class_name})"
+                  response.to_json
+                rescue StandardError => e
+                  # Call lifecycle hooks: on_error
+                  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}")
                   error_response = {
                     error: e.message,
                     code: determine_error_code(e),
-                    request_id: request_id
+                    request_id:
                   }
                   error_response[:backtrace] = e.backtrace unless config[:production]
                   status error_response[:code]
@@ -106,6 +153,7 @@ module Hooks
         end
 
         api_class
+        # :nocov:
       end
     end
   end

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

@@ -22,7 +22,7 @@ module Hooks
       def validate_auth!(payload, headers, endpoint_config, global_config = {})
         auth_config = endpoint_config[:auth]
 
-        # Security: Ensure auth type is present and valid
+        # 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)
@@ -32,17 +32,26 @@ module Hooks
         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)
         end
 
-        unless auth_class.valid?(
-          payload:,
-          headers:,
-          config: endpoint_config
-        )
+        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)
         end
       end
+
+      private
+
+      # Short logger accessor for auth module
+      # @return [Hooks::Log] Logger instance
+      #
+      # Provides access to the application logger for authentication operations.
+      def log
+        Hooks::Log.instance
+      end
     end
   end
 end

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

@@ -1,5 +1,13 @@
 # frozen_string_literal: true
 
+# !!! IMPORTANT !!!
+# This file handles the catchall endpoint for the Hooks application.
+# You should not be using catchall endpoints in production.
+# This is mainly for development, testing, and demo purposes.
+# The logging is limited, lifecycle hooks are not called,
+# and it does not support plugins or instruments.
+# Use with caution!
+
 require "grape"
 require_relative "../../plugins/handlers/default"
 require_relative "../helpers"
@@ -10,10 +18,13 @@ module Hooks
       include Hooks::App::Helpers
 
       def self.mount_path(config)
+        # :nocov:
         "#{config[:root_path]}/*path"
+        # :nocov:
       end
 
       def self.route_block(captured_config, captured_logger)
+        # :nocov:
         proc do
           request_id = uuid
 
@@ -23,7 +34,7 @@ module Hooks
 
           # Set request context for logging
           request_context = {
-            request_id: request_id,
+            request_id:,
             path: "/#{params[:path]}",
             handler: "DefaultHandler"
           }
@@ -45,8 +56,8 @@ module Hooks
 
               # Call handler
               response = handler.call(
-                payload: payload,
-                headers: headers,
+                payload:,
+                headers:,
                 config: {}
               )
 
@@ -78,6 +89,7 @@ module Hooks
             end
           end
         end
+        # :nocov:
       end
     end
   end

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

@@ -10,9 +10,9 @@ module Hooks
         content_type "application/json"
         {
           status: "healthy",
-          timestamp: Time.now.iso8601,
+          timestamp: Time.now.utc.iso8601,
           version: Hooks::VERSION,
-          uptime_seconds: (Time.now - Hooks::App::API.start_time).to_i
+          uptime_seconds: (Time.now - Hooks::App::API.server_start_time).to_i
         }.to_json
       end
     end

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

@@ -10,7 +10,7 @@ module Hooks
         content_type "application/json"
         {
           version: Hooks::VERSION,
-          timestamp: Time.now.iso8601
+          timestamp: Time.now.utc.iso8601
         }.to_json
       end
     end

data/lib/hooks/app/helpers.rb

@@ -21,13 +21,15 @@ module Hooks
       # @return [void]
       # @note Timeout enforcement should be handled at the server level (e.g., Puma)
       def enforce_request_limits(config)
-        # Check content length (handle different header formats and sources)
-        content_length = headers["Content-Length"] || headers["CONTENT_LENGTH"] ||
-                        headers["content-length"] || headers["HTTP_CONTENT_LENGTH"] ||
-                        env["CONTENT_LENGTH"] || env["HTTP_CONTENT_LENGTH"]
+        # Optimized content length check - check most common sources first
+        content_length = request.content_length if respond_to?(:request) && request.respond_to?(:content_length)
 
-        # Also try to get from request object directly
-        content_length ||= request.content_length if respond_to?(:request) && request.respond_to?(:content_length)
+        content_length ||= headers["Content-Length"] ||
+                          headers["CONTENT_LENGTH"] ||
+                          headers["content-length"] ||
+                          headers["HTTP_CONTENT_LENGTH"] ||
+                          env["CONTENT_LENGTH"] ||
+                          env["HTTP_CONTENT_LENGTH"]
 
         content_length = content_length&.to_i
 
@@ -45,16 +47,21 @@ module Hooks
       # @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)
+        # Optimized content type check - check most common header first
         content_type = headers["Content-Type"] || headers["CONTENT_TYPE"] || headers["content-type"] || headers["HTTP_CONTENT_TYPE"]
 
         # Try to parse as JSON if content type suggests it or if it looks like JSON
         if content_type&.include?("application/json") || (raw_body.strip.start_with?("{", "[") rescue false)
           begin
-            parsed_payload = JSON.parse(raw_body)
+            # Security: Limit JSON parsing depth and complexity to prevent JSON bombs
+            parsed_payload = safe_json_parse(raw_body)
             parsed_payload = parsed_payload.transform_keys(&:to_sym) if symbolize && parsed_payload.is_a?(Hash)
             return parsed_payload
-          rescue JSON::ParserError
-            # If JSON parsing fails, return raw body
+          rescue JSON::ParserError, ArgumentError => e
+            # If JSON parsing fails or security limits exceeded, return raw body
+            if e.message.include?("nesting") || e.message.include?("depth")
+              log.warn("JSON parsing limit exceeded: #{e.message}")
+            end
           end
         end
 
@@ -79,6 +86,29 @@ module Hooks
 
       private
 
+      # Safely parse JSON
+      #
+      # @param json_string [String] The JSON string to parse
+      # @return [Hash, Array] Parsed JSON object
+      # @raise [JSON::ParserError] If JSON is invalid
+      # @raise [ArgumentError] If security limits are exceeded
+      def safe_json_parse(json_string)
+        # Security limits for JSON parsing
+        max_nesting = ENV.fetch("JSON_MAX_NESTING", "20").to_i
+
+        # Additional size check before parsing
+        if json_string.length > ENV.fetch("JSON_MAX_SIZE", "10485760").to_i # 10MB default
+          raise ArgumentError, "JSON payload too large for parsing"
+        end
+
+        JSON.parse(json_string, {
+          max_nesting: max_nesting,
+          create_additions: false,  # Security: Disable object creation from JSON
+          object_class: Hash,       # Use plain Hash instead of custom classes
+          array_class: Array        # Use plain Array instead of custom classes
+        })
+      end
+
       # Determine HTTP error code from exception
       #
       # @param exception [Exception] The exception to map to an HTTP status code

data/lib/hooks/core/builder.rb

@@ -5,6 +5,7 @@ require_relative "config_validator"
 require_relative "logger_factory"
 require_relative "plugin_loader"
 require_relative "../app/api"
+require_relative "../utils/retry"
 
 module Hooks
   module Core
@@ -34,6 +35,11 @@ module Hooks
           )
         end
 
+        Hooks::Log.instance = @log
+
+        # Hydrate our Retryable instance
+        Retry.setup!(log: @log)
+
         # Load all plugins at boot time
         load_plugins(config)
 

data/lib/hooks/core/component_access.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Hooks
+  module Core
+    # Shared module providing access to global components (logger, stats, failbot)
+    #
+    # This module provides a consistent interface for accessing global components
+    # across all plugin types, eliminating code duplication and ensuring consistent
+    # behavior throughout the application.
+    #
+    # @example Usage in a class that needs instance methods
+    #   class MyHandler
+    #     include Hooks::Core::ComponentAccess
+    #
+    #     def process
+    #       log.info("Processing request")
+    #       stats.increment("requests.processed")
+    #       failbot.report("Error occurred") if error?
+    #     end
+    #   end
+    #
+    # @example Usage in a class that needs class methods
+    #   class MyValidator
+    #     extend Hooks::Core::ComponentAccess
+    #
+    #     def self.validate
+    #       log.info("Validating request")
+    #       stats.increment("requests.validated")
+    #     end
+    #   end
+    module ComponentAccess
+      # Short logger accessor
+      # @return [Hooks::Log] Logger instance for logging messages
+      #
+      # Provides a convenient way to log messages without needing
+      # to reference the full Hooks::Log namespace.
+      #
+      # @example Logging an error
+      #   log.error("Something went wrong")
+      def log
+        Hooks::Log.instance
+      end
+
+      # Global stats component accessor
+      # @return [Hooks::Plugins::Instruments::Stats] Stats instance for metrics reporting
+      #
+      # Provides access to the global stats component for reporting metrics
+      # to services like DataDog, New Relic, etc.
+      #
+      # @example Recording a metric
+      #   stats.increment("webhook.processed", { handler: "MyHandler" })
+      def stats
+        Hooks::Core::GlobalComponents.stats
+      end
+
+      # Global failbot component accessor
+      # @return [Hooks::Plugins::Instruments::Failbot] Failbot instance for error reporting
+      #
+      # Provides access to the global failbot component for reporting errors
+      # to services like Sentry, Rollbar, etc.
+      #
+      # @example Reporting an error
+      #   failbot.report("Something went wrong", { context: "additional info" })
+      def failbot
+        Hooks::Core::GlobalComponents.failbot
+      end
+    end
+  end
+end

data/lib/hooks/core/config_loader.rb

@@ -24,23 +24,39 @@ module Hooks
         normalize_headers: true
       }.freeze
 
+      SILENCE_CONFIG_LOADER_MESSAGES = ENV.fetch(
+        "HOOKS_SILENCE_CONFIG_LOADER_MESSAGES", "false"
+      ).downcase == "true".freeze
+
       # Load and merge configuration from various sources
       #
       # @param config_path [String, Hash] Path to config file or config hash
       # @return [Hash] Merged configuration
       def self.load(config_path: nil)
         config = DEFAULT_CONFIG.dup
+        overrides = []
 
         # Load from file if path provided
         if config_path.is_a?(String) && File.exist?(config_path)
           file_config = load_config_file(config_path)
-          config.merge!(file_config) if file_config
-        elsif config_path.is_a?(Hash)
-          config.merge!(config_path)
+          if file_config
+            overrides << "file config"
+            config.merge!(file_config)
+          end
         end
 
-        # Override with environment variables
-        config.merge!(load_env_config)
+        # Override with environment variables (before programmatic config)
+        env_config = load_env_config
+        if env_config.any?
+          overrides << "environment variables"
+          config.merge!(env_config)
+        end
+
+        # Programmatic config has highest priority
+        if config_path.is_a?(Hash)
+          overrides << "programmatic config"
+          config.merge!(config_path)
+        end
 
         # Convert string keys to symbols for consistency
         config = symbolize_keys(config)
@@ -51,6 +67,11 @@ module Hooks
           config[:production] = false
         end
 
+        # Log overrides if any were made
+        if overrides.any?
+          puts "INFO: Configuration overrides applied from: #{overrides.join(', ')}" unless SILENCE_CONFIG_LOADER_MESSAGES
+        end
+
         return config
       end
 
@@ -93,8 +114,9 @@ module Hooks
         end
 
         result
-      rescue => _e
-        # In production, we'd log this error
+      rescue => e
+        # Log this error with meaningful information
+        puts "ERROR: Failed to load config file '#{file_path}': #{e.message}" unless SILENCE_CONFIG_LOADER_MESSAGES
         nil
       end
 
@@ -105,8 +127,11 @@ module Hooks
         env_config = {}
 
         env_mappings = {
+          "HOOKS_HANDLER_DIR" => :handler_dir,
           "HOOKS_HANDLER_PLUGIN_DIR" => :handler_plugin_dir,
           "HOOKS_AUTH_PLUGIN_DIR" => :auth_plugin_dir,
+          "HOOKS_LIFECYCLE_PLUGIN_DIR" => :lifecycle_plugin_dir,
+          "HOOKS_INSTRUMENTS_PLUGIN_DIR" => :instruments_plugin_dir,
           "HOOKS_LOG_LEVEL" => :log_level,
           "HOOKS_REQUEST_LIMIT" => :request_limit,
           "HOOKS_REQUEST_TIMEOUT" => :request_timeout,
@@ -114,17 +139,24 @@ module Hooks
           "HOOKS_HEALTH_PATH" => :health_path,
           "HOOKS_VERSION_PATH" => :version_path,
           "HOOKS_ENVIRONMENT" => :environment,
-          "HOOKS_ENDPOINTS_DIR" => :endpoints_dir
+          "HOOKS_ENDPOINTS_DIR" => :endpoints_dir,
+          "HOOKS_USE_CATCHALL_ROUTE" => :use_catchall_route,
+          "HOOKS_SYMBOLIZE_PAYLOAD" => :symbolize_payload,
+          "HOOKS_NORMALIZE_HEADERS" => :normalize_headers,
+          "HOOKS_SOME_STRING_VAR" => :some_string_var # Added for test
         }
 
         env_mappings.each do |env_key, config_key|
           value = ENV[env_key]
           next unless value
 
-          # Convert numeric values
+          # Convert values to appropriate types
           case config_key
           when :request_limit, :request_timeout
             env_config[config_key] = value.to_i
+          when :use_catchall_route, :symbolize_payload, :normalize_headers
+            # Convert string to boolean
+            env_config[config_key] = %w[true 1 yes on].include?(value.downcase)
           else
             env_config[config_key] = value
           end

data/lib/hooks/core/config_validator.rb

@@ -15,6 +15,8 @@ module Hooks
         optional(:handler_dir).filled(:string)  # For backward compatibility
         optional(:handler_plugin_dir).filled(:string)
         optional(:auth_plugin_dir).maybe(:string)
+        optional(:lifecycle_plugin_dir).maybe(:string)
+        optional(:instruments_plugin_dir).maybe(:string)
         optional(:log_level).filled(:string, included_in?: %w[debug info warn error])
         optional(:request_limit).filled(:integer, gt?: 0)
         optional(:request_timeout).filled(:integer, gt?: 0)
@@ -32,6 +34,7 @@ module Hooks
       ENDPOINT_CONFIG_SCHEMA = Dry::Schema.Params do
         required(:path).filled(:string)
         required(:handler).filled(:string)
+        optional(:method).filled(:string, included_in?: %w[get post put patch delete head options])
 
         optional(:auth).hash do
           required(:type).filled(:string)