hooks-ruby 0.0.2

data/lib/hooks/core/builder.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require_relative "config_loader"
+require_relative "config_validator"
+require_relative "logger_factory"
+require_relative "plugin_loader"
+require_relative "../app/api"
+
+module Hooks
+  module Core
+    # Main builder that orchestrates the webhook server setup
+    class Builder
+      # Initialize builder with configuration options
+      #
+      # @param config [String, Hash] Path to config file or config hash
+      # @param log [Logger] Custom logger instance
+      def initialize(config: nil, log: nil)
+        @log = log
+        @config_input = config
+      end
+
+      # Build and return Rack-compatible application
+      #
+      # @return [Object] Rack-compatible application
+      def build
+        # Load and validate configuration
+        config = load_and_validate_config
+
+        # Create logger unless a custom logger is provided
+        if @log.nil?
+          @log = LoggerFactory.create(
+            log_level: config[:log_level],
+            custom_logger: @custom_logger
+          )
+        end
+
+        # Load all plugins at boot time
+        load_plugins(config)
+
+        # Load endpoints
+        endpoints = load_endpoints(config)
+
+        # Log startup
+        @log.info "starting hooks server v#{Hooks::VERSION}"
+        @log.info "config: #{endpoints.size} endpoints loaded"
+        @log.info "environment: #{config[:environment]}"
+        @log.info "available endpoints: #{endpoints.map { |e| e[:path] }.join(', ')}"
+
+        # Build and return Grape API class
+        Hooks::App::API.create(
+          config:,
+          endpoints:,
+          log: @log
+        )
+      end
+
+      private
+
+      # Load and validate all configuration
+      #
+      # @return [Hash] Validated global configuration
+      def load_and_validate_config
+        # Load base config from file/hash and environment
+        config = ConfigLoader.load(config_path: @config_input)
+
+        # Validate global configuration
+        ConfigValidator.validate_global_config(config)
+      rescue ConfigValidator::ValidationError => e
+        raise ConfigurationError, "Configuration validation failed: #{e.message}"
+      end
+
+      # Load and validate endpoint configurations
+      #
+      # @param config [Hash] Global configuration
+      # @return [Array<Hash>] Array of validated endpoint configurations
+      def load_endpoints(config)
+        endpoints = ConfigLoader.load_endpoints(config[:endpoints_dir])
+        ConfigValidator.validate_endpoints(endpoints)
+      rescue ConfigValidator::ValidationError => e
+        raise ConfigurationError, "Endpoint validation failed: #{e.message}"
+      end
+
+      # Load all plugins at boot time
+      #
+      # @param config [Hash] Global configuration
+      # @return [void]
+      def load_plugins(config)
+        PluginLoader.load_all_plugins(config)
+      rescue => e
+        raise ConfigurationError, "Plugin loading failed: #{e.message}"
+      end
+    end
+
+    # Configuration error
+    class ConfigurationError < StandardError; end
+  end
+end

data/lib/hooks/core/config_loader.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "json"
+
+module Hooks
+  module Core
+    # Loads and merges configuration from files and environment variables
+    class ConfigLoader
+      DEFAULT_CONFIG = {
+        handler_plugin_dir: "./plugins/handlers",
+        auth_plugin_dir: "./plugins/auth",
+        log_level: "info",
+        request_limit: 1_048_576,
+        request_timeout: 30,
+        root_path: "/webhooks",
+        health_path: "/health",
+        version_path: "/version",
+        environment: "production",
+        production: true,
+        endpoints_dir: "./config/endpoints",
+        use_catchall_route: false,
+        symbolize_payload: true,
+        normalize_headers: 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
+
+        # 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)
+        end
+
+        # Override with environment variables
+        config.merge!(load_env_config)
+
+        # Convert string keys to symbols for consistency
+        config = symbolize_keys(config)
+
+        if config[:environment] == "production"
+          config[:production] = true
+        else
+          config[:production] = false
+        end
+
+        return config
+      end
+
+      # Load endpoint configurations from directory
+      #
+      # @param endpoints_dir [String] Directory containing endpoint config files
+      # @return [Array<Hash>] Array of endpoint configurations
+      def self.load_endpoints(endpoints_dir)
+        return [] unless endpoints_dir && Dir.exist?(endpoints_dir)
+
+        endpoints = []
+        files = Dir.glob(File.join(endpoints_dir, "*.{yml,yaml,json}"))
+
+        files.each do |file|
+          endpoint_config = load_config_file(file)
+          if endpoint_config
+            endpoints << symbolize_keys(endpoint_config)
+          end
+        end
+
+        endpoints
+      end
+
+      private
+
+      # Load configuration from YAML or JSON file
+      #
+      # @param file_path [String] Path to config file
+      # @return [Hash, nil] Parsed configuration or nil if error
+      def self.load_config_file(file_path)
+        content = File.read(file_path)
+
+        result = case File.extname(file_path).downcase
+        when ".json"
+          JSON.parse(content)
+        when ".yml", ".yaml"
+          YAML.safe_load(content, permitted_classes: [Symbol])
+        else
+          nil
+        end
+
+        result
+      rescue => _e
+        # In production, we'd log this error
+        nil
+      end
+
+      # Load configuration from environment variables
+      #
+      # @return [Hash] Configuration from ENV vars
+      def self.load_env_config
+        env_config = {}
+
+        env_mappings = {
+          "HOOKS_HANDLER_PLUGIN_DIR" => :handler_plugin_dir,
+          "HOOKS_AUTH_PLUGIN_DIR" => :auth_plugin_dir,
+          "HOOKS_LOG_LEVEL" => :log_level,
+          "HOOKS_REQUEST_LIMIT" => :request_limit,
+          "HOOKS_REQUEST_TIMEOUT" => :request_timeout,
+          "HOOKS_ROOT_PATH" => :root_path,
+          "HOOKS_HEALTH_PATH" => :health_path,
+          "HOOKS_VERSION_PATH" => :version_path,
+          "HOOKS_ENVIRONMENT" => :environment,
+          "HOOKS_ENDPOINTS_DIR" => :endpoints_dir
+        }
+
+        env_mappings.each do |env_key, config_key|
+          value = ENV[env_key]
+          next unless value
+
+          # Convert numeric values
+          case config_key
+          when :request_limit, :request_timeout
+            env_config[config_key] = value.to_i
+          else
+            env_config[config_key] = value
+          end
+        end
+
+        env_config
+      end
+
+      # Recursively convert string keys to symbols
+      #
+      # @param obj [Hash, Array, Object] Object to convert
+      # @return [Hash, Array, Object] Converted object
+      def self.symbolize_keys(obj)
+        case obj
+        when Hash
+          obj.transform_keys(&:to_sym).transform_values { |v| symbolize_keys(v) }
+        when Array
+          obj.map { |v| symbolize_keys(v) }
+        else
+          obj
+        end
+      end
+    end
+  end
+end

data/lib/hooks/core/config_validator.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require "dry-schema"
+require_relative "../security"
+
+module Hooks
+  module Core
+    # Validates configuration using Dry::Schema
+    class ConfigValidator
+      # Custom validation error
+      class ValidationError < StandardError; end
+
+      # Global configuration schema
+      GLOBAL_CONFIG_SCHEMA = Dry::Schema.Params do
+        optional(:handler_dir).filled(:string)  # For backward compatibility
+        optional(:handler_plugin_dir).filled(:string)
+        optional(:auth_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)
+        optional(:root_path).filled(:string)
+        optional(:health_path).filled(:string)
+        optional(:version_path).filled(:string)
+        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
+
+      # Endpoint configuration schema
+      ENDPOINT_CONFIG_SCHEMA = Dry::Schema.Params do
+        required(:path).filled(:string)
+        required(:handler).filled(:string)
+
+        optional(:auth).hash do
+          required(:type).filled(:string)
+          optional(:secret_env_key).filled(:string)
+          optional(:header).filled(:string)
+          optional(:algorithm).filled(:string)
+          optional(:timestamp_header).filled(:string)
+          optional(:timestamp_tolerance).filled(:integer, gt?: 0)
+          optional(:format).filled(:string)
+          optional(:version_prefix).filled(:string)
+          optional(:payload_template).filled(:string)
+        end
+
+        optional(:opts).hash
+      end
+
+      # Validate global configuration
+      #
+      # @param config [Hash] Configuration to validate
+      # @return [Hash] Validated configuration
+      # @raise [ValidationError] if validation fails
+      def self.validate_global_config(config)
+        result = GLOBAL_CONFIG_SCHEMA.call(config)
+
+        if result.failure?
+          raise ValidationError, "Invalid global configuration: #{result.errors.to_h}"
+        end
+
+        result.to_h
+      end
+
+      # Validate endpoint configuration with additional security checks
+      #
+      # @param config [Hash] Endpoint configuration to validate
+      # @return [Hash] Validated configuration
+      # @raise [ValidationError] if validation fails
+      def self.validate_endpoint_config(config)
+        result = ENDPOINT_CONFIG_SCHEMA.call(config)
+
+        if result.failure?
+          raise ValidationError, "Invalid endpoint configuration: #{result.errors.to_h}"
+        end
+
+        validated_config = result.to_h
+
+        # Security: Additional validation for handler name
+        handler_name = validated_config[:handler]
+        unless valid_handler_name?(handler_name)
+          raise ValidationError, "Invalid handler name: #{handler_name}"
+        end
+
+        validated_config
+      end
+
+      # Validate array of endpoint configurations
+      #
+      # @param endpoints [Array<Hash>] Array of endpoint configurations
+      # @return [Array<Hash>] Array of validated configurations
+      # @raise [ValidationError] if any validation fails
+      def self.validate_endpoints(endpoints)
+        validated_endpoints = []
+
+        endpoints.each_with_index do |endpoint, index|
+          begin
+            validated_endpoints << validate_endpoint_config(endpoint)
+          rescue ValidationError => e
+            raise ValidationError, "Endpoint #{index}: #{e.message}"
+          end
+        end
+
+        validated_endpoints
+      end
+
+      private
+
+      # Validate that a handler name is safe
+      #
+      # @param handler_name [String] The handler name to validate
+      # @return [Boolean] true if the handler name is safe, false otherwise
+      def self.valid_handler_name?(handler_name)
+        # Must be a string
+        return false unless handler_name.is_a?(String)
+
+        # Must not be empty or only whitespace
+        return false if handler_name.strip.empty?
+
+        # Must match a safe pattern: alphanumeric + underscore, starting with uppercase
+        return false unless handler_name.match?(/\A[A-Z][a-zA-Z0-9_]*\z/)
+
+        # Must not be a system/built-in class name
+        return false if Hooks::Security::DANGEROUS_CLASSES.include?(handler_name)
+
+        true
+      end
+    end
+  end
+end

data/lib/hooks/core/log.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Hooks
+  module Log
+    class << self
+      attr_accessor :instance
+    end
+  end
+end

data/lib/hooks/core/logger_factory.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "redacting_logger"
+require "logger"
+require "json"
+require "securerandom"
+
+module Hooks
+  module Core
+    # Factory for creating structured JSON loggers
+    class LoggerFactory
+      # Create a structured JSON logger
+      #
+      # @param log_level [String] Log level (debug, info, warn, error)
+      # @param custom_logger [Logger] Custom logger instance (optional)
+      # @return [Logger] Configured logger instance
+      def self.create(log_level: "info", custom_logger: nil)
+        return custom_logger if custom_logger
+
+        $stdout.sync = true # don't buffer - flush immediately
+
+        # Create a new logger
+        logger = RedactingLogger.new(
+          $stdout, # The device to log to (defaults to $stdout if not provided)
+          redact_patterns: [], # An array of Regexp patterns to redact from the logs
+          level: parse_log_level(log_level), # The log level to use
+          redacted_msg: "[REDACTED]", # The message to replace the redacted patterns with
+          use_default_patterns: true # Whether to use the default built-in patterns or not
+        )
+
+        logger.formatter = json_formatter
+        logger
+      end
+
+      private
+
+      # Parse string log level to Logger constant
+      #
+      # @param level [String] Log level string
+      # @return [Integer] Logger level constant
+      def self.parse_log_level(level)
+        case level.to_s.downcase
+        when "debug" then Logger::DEBUG
+        when "info" then Logger::INFO
+        when "warn" then Logger::WARN
+        when "error" then Logger::ERROR
+        else Logger::INFO
+        end
+      end
+
+      # JSON formatter for structured logging
+      #
+      # @return [Proc] Formatter procedure
+      def self.json_formatter
+        proc do |severity, datetime, progname, msg|
+          log_entry = {
+            timestamp: datetime.iso8601,
+            level: severity.downcase,
+            message: msg
+          }
+
+          # Add request context if available in thread local storage
+          if Thread.current[:hooks_request_context]
+            log_entry.merge!(Thread.current[:hooks_request_context])
+          end
+
+          "#{log_entry.to_json}\n"
+        end
+      end
+    end
+
+    # Helper for setting request context in logs
+    module LogContext
+      # Set request context for current thread
+      #
+      # @param context [Hash] Request context data
+      def self.set(context)
+        Thread.current[:hooks_request_context] = context
+      end
+
+      # Clear request context for current thread
+      def self.clear
+        Thread.current[:hooks_request_context] = nil
+      end
+
+      # Execute block with request context
+      #
+      # @param context [Hash] Request context data
+      # @yield Block to execute with context
+      def self.with(context)
+        old_context = Thread.current[:hooks_request_context]
+        Thread.current[:hooks_request_context] = context
+        yield
+      ensure
+        Thread.current[:hooks_request_context] = old_context
+      end
+    end
+  end
+end