hooks-ruby 0.0.2

data/bin/rdoc

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'rdoc' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+
+bundle_binstub = File.expand_path("bundle", __dir__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300).include?("This file was generated by Bundler")
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("rdoc", "rdoc")

data/bin/ri

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'ri' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+
+bundle_binstub = File.expand_path("bundle", __dir__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300).include?("This file was generated by Bundler")
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("rdoc", "ri")

data/bin/rspec

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'rspec' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+
+bundle_binstub = File.expand_path("bundle", __dir__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300).include?("This file was generated by Bundler")
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("rspec-core", "rspec")

data/bin/rubocop

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'rubocop' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+
+bundle_binstub = File.expand_path("bundle", __dir__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300).include?("This file was generated by Bundler")
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("rubocop", "rubocop")

data/bin/ruby-parse

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'ruby-parse' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+
+bundle_binstub = File.expand_path("bundle", __dir__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300).include?("This file was generated by Bundler")
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("parser", "ruby-parse")

data/bin/ruby-rewrite

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'ruby-rewrite' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+
+bundle_binstub = File.expand_path("bundle", __dir__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300).include?("This file was generated by Bundler")
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("parser", "ruby-rewrite")

data/bin/rubygems-await

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'rubygems-await' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+
+bundle_binstub = File.expand_path("bundle", __dir__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300).include?("This file was generated by Bundler")
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("rubygems-await", "rubygems-await")

data/bin/sigstore-cli

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'sigstore-cli' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+
+bundle_binstub = File.expand_path("bundle", __dir__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300).include?("This file was generated by Bundler")
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("sigstore-cli", "sigstore-cli")

data/bin/thor

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'thor' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+
+bundle_binstub = File.expand_path("bundle", __dir__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300).include?("This file was generated by Bundler")
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("thor", "thor")

data/config.ru

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative "lib/hooks"
+
+app = Hooks.build(config: "./spec/acceptance/config/hooks.yaml")
+run app

data/hooks.gemspec

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "lib/hooks/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "hooks-ruby"
+  spec.version       = Hooks::VERSION
+  spec.authors       = ["github", "GrantBirki"]
+  spec.license       = "MIT"
+
+  spec.summary       = "A Pluggable Webhook Server Framework written in Ruby"
+  spec.description   = <<~SPEC_DESC
+    A Pluggable Webhook Server Framework written in Ruby
+  SPEC_DESC
+
+  spec.homepage = "https://github.com/github/hooks"
+  spec.metadata = {
+    "bug_tracker_uri" => "https://github.com/github/hooks/issues"
+  }
+
+  spec.add_dependency "redacting-logger", "~> 1.5"
+  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")
+
+  spec.files = %w[LICENSE README.md hooks.gemspec config.ru]
+  spec.files += Dir.glob("lib/**/*.rb")
+  spec.files += Dir.glob("bin/*")
+  spec.bindir = "bin"
+  spec.executables = ["hooks"]
+  spec.require_paths = ["lib"]
+end

data/lib/hooks/app/api.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "grape"
+require "json"
+require "securerandom"
+require_relative "helpers"
+require_relative "auth/auth"
+require_relative "../plugins/handlers/base"
+require_relative "../plugins/handlers/default"
+require_relative "../core/logger_factory"
+require_relative "../core/log"
+
+# Import all core endpoint classes dynamically
+Dir[File.join(__dir__, "endpoints/**/*.rb")].sort.each { |file| require file }
+
+module Hooks
+  module App
+    # Factory for creating configured Grape API classes
+    class API
+      include Hooks::App::Helpers
+      include Hooks::App::Auth
+
+      class << self
+        attr_reader :start_time
+      end
+
+      # Create a new configured API class
+      def self.create(config:, endpoints:, log:)
+        @start_time = Time.now
+
+        Hooks::Log.instance = log
+
+        api_class = Class.new(Grape::API) do
+          content_type :json, "application/json"
+          content_type :txt, "text/plain"
+          content_type :xml, "application/xml"
+          content_type :any, "*/*"
+          format :txt
+          default_format :txt
+        end
+
+        api_class.class_eval do
+          helpers Helpers, Auth
+
+          mount Hooks::App::HealthEndpoint => config[:health_path]
+          mount Hooks::App::VersionEndpoint => config[:version_path]
+
+          endpoints.each do |endpoint_config|
+            full_path = "#{config[:root_path]}#{endpoint_config[:path]}"
+            handler_class_name = endpoint_config[:handler]
+
+            post(full_path) do
+              request_id = uuid
+              request_context = {
+                request_id:,
+                path: full_path,
+                handler: handler_class_name
+              }
+
+              Core::LogContext.with(request_context) do
+                begin
+                  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
+
+                  payload = parse_payload(raw_body, headers, symbolize: config[:symbolize_payload])
+                  handler = load_handler(handler_class_name)
+                  normalized_headers = config[:normalize_headers] ? Hooks::Utils::Normalize.headers(headers) : headers
+
+                  response = handler.call(
+                    payload:,
+                    headers: normalized_headers,
+                    config: endpoint_config
+                  )
+
+                  log.info "request processed successfully (id: #{request_id}, handler: #{handler_class_name})"
+                  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})"
+                  error_response = {
+                    error: e.message,
+                    code: determine_error_code(e),
+                    request_id: request_id
+                  }
+                  error_response[:backtrace] = e.backtrace unless config[:production]
+                  status error_response[:code]
+                  content_type "application/json"
+                  error_response.to_json
+                end
+              end
+            end
+          end
+
+          if config[:use_catchall_route]
+            route_path = Hooks::App::CatchallEndpoint.mount_path(config)
+            route_block = Hooks::App::CatchallEndpoint.route_block(config, log)
+            post(route_path, &route_block)
+          end
+        end
+
+        api_class
+      end
+    end
+  end
+end

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

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative "../../core/plugin_loader"
+
+module Hooks
+  module App
+    # Provides authentication helpers for verifying incoming requests.
+    #
+    # @example Usage
+    #   include Hooks::App::Auth
+    #   validate_auth!(payload, headers, endpoint_config)
+    module Auth
+      # Verifies the incoming request using the configured authentication method.
+      #
+      # @param payload [String, Hash] The request payload to authenticate.
+      # @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).
+      # @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 = {})
+        auth_config = endpoint_config[:auth]
+
+        # Security: 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)
+        end
+
+        # Get auth plugin from loaded plugins registry (boot-time loaded only)
+        begin
+          auth_class = Core::PluginLoader.get_auth_plugin(auth_type)
+        rescue => e
+          error!("unsupported auth type '#{auth_type}'", 400)
+        end
+
+        unless auth_class.valid?(
+          payload:,
+          headers:,
+          config: endpoint_config
+        )
+          error!("authentication failed", 401)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "grape"
+require_relative "../../plugins/handlers/default"
+require_relative "../helpers"
+
+module Hooks
+  module App
+    class CatchallEndpoint < Grape::API
+      include Hooks::App::Helpers
+
+      def self.mount_path(config)
+        "#{config[:root_path]}/*path"
+      end
+
+      def self.route_block(captured_config, captured_logger)
+        proc do
+          request_id = uuid
+
+          # Use captured values
+          config = captured_config
+          log = captured_logger
+
+          # Set request context for logging
+          request_context = {
+            request_id: request_id,
+            path: "/#{params[:path]}",
+            handler: "DefaultHandler"
+          }
+
+          Hooks::Core::LogContext.with(request_context) do
+            begin
+              # Enforce request limits
+              enforce_request_limits(config)
+
+              # Get raw body for payload parsing
+              request.body.rewind
+              raw_body = request.body.read
+
+              # Parse payload
+              payload = parse_payload(raw_body, headers)
+
+              # Use default handler
+              handler = DefaultHandler.new
+
+              # Call handler
+              response = handler.call(
+                payload: payload,
+                headers: headers,
+                config: {}
+              )
+
+              log.info "request processed successfully with default handler (id: #{request_id})"
+
+              # Return response as JSON string when using txt format
+              status 200
+              content_type "application/json"
+              (response || { status: "ok" }).to_json
+
+            rescue StandardError => e
+              log.error "request failed: #{e.message} (id: #{request_id})"
+
+              # Return error response
+              error_response = {
+                error: e.message,
+                code: determine_error_code(e),
+                request_id: request_id
+              }
+
+              # Add backtrace in all environments except production
+              unless config[:production] == true
+                error_response[:backtrace] = e.backtrace
+              end
+
+              status error_response[:code]
+              content_type "application/json"
+              error_response.to_json
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "grape"
+require_relative "../../version"
+
+module Hooks
+  module App
+    class HealthEndpoint < Grape::API
+      get do
+        content_type "application/json"
+        {
+          status: "healthy",
+          timestamp: Time.now.iso8601,
+          version: Hooks::VERSION,
+          uptime_seconds: (Time.now - Hooks::App::API.start_time).to_i
+        }.to_json
+      end
+    end
+  end
+end

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

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "grape"
+require_relative "../../version"
+
+module Hooks
+  module App
+    class VersionEndpoint < Grape::API
+      get do
+        content_type "application/json"
+        {
+          version: Hooks::VERSION,
+          timestamp: Time.now.iso8601
+        }.to_json
+      end
+    end
+  end
+end

data/lib/hooks/app/helpers.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require_relative "../security"
+require_relative "../core/plugin_loader"
+
+module Hooks
+  module App
+    module Helpers
+      # Generate a unique identifier (UUID)
+      #
+      # @return [String] a new UUID string
+      def uuid
+        SecureRandom.uuid
+      end
+
+      # Enforce request size and timeout limits
+      #
+      # @param config [Hash] The configuration hash, must include :request_limit
+      # @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)
+        # 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"]
+
+        # Also try to get from request object directly
+        content_length ||= request.content_length if respond_to?(:request) && request.respond_to?(:content_length)
+
+        content_length = content_length&.to_i
+
+        if content_length && content_length > config[:request_limit]
+          error!("request body too large", 413)
+        end
+
+        # Note: Timeout enforcement would typically be handled at the server level (Puma, etc.)
+      end
+
+      # Parse request payload
+      #
+      # @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)
+        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)
+            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
+          end
+        end
+
+        # Return raw body for all other cases
+        raw_body
+      end
+
+      # Load handler class
+      #
+      # @param handler_class_name [String] The name of the handler class to load
+      # @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
+      end
+
+      private
+
+      # Determine HTTP error code from exception
+      #
+      # @param exception [Exception] The exception to map to an HTTP status code
+      # @return [Integer] The HTTP status code (400, 501, or 500)
+      def determine_error_code(exception)
+        case exception
+        when ArgumentError then 400
+        when NotImplementedError then 501
+        else 500
+        end
+      end
+    end
+  end
+end