hooks-ruby 0.0.2 → 0.0.4

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

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Hooks
+  module Plugins
+    module Auth
+      # Validates and parses timestamps for webhook authentication
+      #
+      # This class provides secure timestamp validation supporting both
+      # ISO 8601 UTC format and Unix timestamp format. It includes
+      # strict validation to prevent various injection attacks.
+      #
+      # @example Basic usage
+      #   validator = TimestampValidator.new
+      #   validator.valid?("1609459200", 300)  # => true/false
+      #   validator.parse("2021-01-01T00:00:00Z")  # => 1609459200
+      #
+      # @api private
+      class TimestampValidator
+        # Validate timestamp against current time with tolerance
+        #
+        # @param timestamp_value [String] The timestamp string to validate
+        # @param tolerance [Integer] Maximum age in seconds (default: 300)
+        # @return [Boolean] true if timestamp is valid and within tolerance
+        def valid?(timestamp_value, tolerance = 300)
+          return false if timestamp_value.nil? || timestamp_value.strip.empty?
+
+          parsed_timestamp = parse(timestamp_value.strip)
+          return false unless parsed_timestamp.is_a?(Integer)
+
+          now = Time.now.utc.to_i
+          (now - parsed_timestamp).abs <= tolerance
+        end
+
+        # Parse timestamp value supporting both ISO 8601 UTC and Unix formats
+        #
+        # @param timestamp_value [String] The timestamp string to parse
+        # @return [Integer, nil] Epoch seconds if parsing succeeds, nil otherwise
+        # @note Security: Strict validation prevents various injection attacks
+        def parse(timestamp_value)
+          return nil if invalid_characters?(timestamp_value)
+
+          parse_iso8601_timestamp(timestamp_value) || parse_unix_timestamp(timestamp_value)
+        end
+
+        private
+
+        # Check for control characters, whitespace, or null bytes
+        #
+        # @param timestamp_value [String] The timestamp to check
+        # @return [Boolean] true if contains invalid characters
+        def invalid_characters?(timestamp_value)
+          if timestamp_value =~ /[\u0000-\u001F\u007F-\u009F]/
+            log_warning("Timestamp contains invalid characters")
+            true
+          else
+            false
+          end
+        end
+
+        # Parse ISO 8601 UTC timestamp string (must have UTC indicator)
+        #
+        # @param timestamp_value [String] ISO 8601 timestamp string
+        # @return [Integer, nil] Epoch seconds if parsing succeeds, nil otherwise
+        def parse_iso8601_timestamp(timestamp_value)
+          # Handle space-separated format and convert to standard ISO format
+          if timestamp_value =~ /\A(\d{4}-\d{2}-\d{2}) (\d{2}:\d{2}:\d{2}(?:\.\d+)?)(?: )\+0000\z/
+            timestamp_value = "#{$1}T#{$2}+00:00"
+          end
+
+          # Ensure the timestamp explicitly includes a UTC indicator
+          return nil unless timestamp_value =~ /(Z|\+00:00|\+0000)\z/
+          return nil unless iso8601_format?(timestamp_value)
+
+          parsed_time = parse_time_safely(timestamp_value)
+          return nil unless parsed_time&.utc_offset&.zero?
+
+          parsed_time.to_i
+        end
+
+        # Parse Unix timestamp string (must be positive integer, no leading zeros except for "0")
+        #
+        # @param timestamp_value [String] Unix timestamp string
+        # @return [Integer, nil] Epoch seconds if parsing succeeds, nil otherwise
+        def parse_unix_timestamp(timestamp_value)
+          return nil unless unix_format?(timestamp_value)
+
+          ts = timestamp_value.to_i
+          return nil if ts <= 0
+
+          ts
+        end
+
+        # Check if timestamp string looks like ISO 8601 format
+        #
+        # @param timestamp_value [String] The timestamp string to check
+        # @return [Boolean] true if it appears to be ISO 8601 format
+        def iso8601_format?(timestamp_value)
+          !!(timestamp_value =~ /\A\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}(?:\.\d+)?(Z|\+00:00|\+0000)?\z/)
+        end
+
+        # Check if timestamp string looks like Unix timestamp format
+        #
+        # @param timestamp_value [String] The timestamp string to check
+        # @return [Boolean] true if it appears to be Unix timestamp format
+        def unix_format?(timestamp_value)
+          return true if timestamp_value == "0"
+          !!(timestamp_value =~ /\A[1-9]\d*\z/)
+        end
+
+        # Safely parse time string with error handling
+        #
+        # @param timestamp_value [String] The timestamp string to parse
+        # @return [Time, nil] Parsed time object or nil if parsing fails
+        def parse_time_safely(timestamp_value)
+          Time.parse(timestamp_value)
+        rescue ArgumentError
+          nil
+        end
+
+        # Log warning message
+        #
+        # @param message [String] Warning message to log
+        def log_warning(message)
+          return unless defined?(Hooks::Log) && Hooks::Log.instance
+
+          Hooks::Log.instance.warn("Auth::TimestampValidator validation failed: #{message}")
+        end
+      end
+    end
+  end
+end

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

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require_relative "../../core/global_components"
+require_relative "../../core/component_access"
+
 module Hooks
   module Plugins
     module Handlers
@@ -7,6 +10,8 @@ module Hooks
       #
       # All custom handlers must inherit from this class and implement the #call method
       class Base
+        include Hooks::Core::ComponentAccess
+
         # Process a webhook request
         #
         # @param payload [Hash, String] Parsed request body (JSON Hash) or raw string
@@ -17,18 +22,6 @@ module Hooks
         def call(payload:, headers:, config:)
           raise NotImplementedError, "Handler must implement #call method"
         end
-
-        # Short logger accessor for all subclasses
-        # @return [Hooks::Log] Logger instance
-        #
-        # Provides a convenient way for handlers to log messages without needing
-        # to reference the full Hooks::Log namespace.
-        #
-        # @example Logging an error in an inherited class
-        #   log.error("oh no an error occured")
-        def log
-          Hooks::Log.instance
-        end
       end
     end
   end

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

@@ -1,8 +1,37 @@
 # frozen_string_literal: true
 
-# Default handler when no custom handler is found
-# This handler simply acknowledges receipt of the webhook and shows a few of the built-in features
+# Default webhook handler implementation
+#
+# This handler provides a basic webhook processing implementation that can be used
+# as a fallback when no custom handler is configured for an endpoint. It demonstrates
+# the standard handler interface and provides basic logging functionality.
+#
+# @example Usage in endpoint configuration
+#   handler:
+#     type: DefaultHandler
+#
+# @see Hooks::Plugins::Handlers::Base
 class DefaultHandler < Hooks::Plugins::Handlers::Base
+  # Process a webhook request with basic acknowledgment
+  #
+  # Provides a simple webhook processing implementation that logs the request
+  # and returns a standard acknowledgment response. This is useful for testing
+  # webhook endpoints or as a placeholder during development.
+  #
+  # @param payload [Hash, String] The webhook payload (parsed JSON or raw string)
+  # @param headers [Hash<String, String>] HTTP headers from the webhook request
+  # @param config [Hash] Endpoint configuration containing handler options
+  # @return [Hash] Response indicating successful processing
+  # @option config [Hash] :opts Additional handler-specific configuration options
+  #
+  # @example Basic usage
+  #   handler = DefaultHandler.new
+  #   response = handler.call(
+  #     payload: { "event" => "push" },
+  #     headers: { "Content-Type" => "application/json" },
+  #     config: { opts: {} }
+  #   )
+  #   # => { message: "webhook processed successfully", handler: "DefaultHandler", timestamp: "..." }
   def call(payload:, headers:, config:)
 
     log.info("🔔 Default handler invoked for webhook 🔔")
@@ -15,7 +44,7 @@ class DefaultHandler < Hooks::Plugins::Handlers::Base
     {
       message: "webhook processed successfully",
       handler: "DefaultHandler",
-      timestamp: Time.now.iso8601
+      timestamp: Time.now.utc.iso8601
     }
   end
 end

data/lib/hooks/plugins/instruments/failbot.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "failbot_base"
+
+module Hooks
+  module Plugins
+    module Instruments
+      # Default failbot instrument implementation
+      #
+      # This is a no-op implementation that provides the error reporting interface
+      # without actually sending errors anywhere. It serves as a safe default when
+      # no custom error reporting implementation is configured.
+      #
+      # Users should replace this with their own implementation for services
+      # like Sentry, Rollbar, Honeybadger, etc.
+      #
+      # @example Replacing with a custom implementation
+      #   # In your application initialization:
+      #   custom_failbot = MySentryFailbotImplementation.new
+      #   Hooks::Core::GlobalComponents.failbot = custom_failbot
+      #
+      # @see Hooks::Plugins::Instruments::FailbotBase
+      # @see Hooks::Core::GlobalComponents
+      class Failbot < FailbotBase
+        # Inherit from FailbotBase to provide a default no-op implementation
+        # of the error reporting instrument interface.
+        #
+        # All methods from FailbotBase are inherited and provide safe no-op behavior.
+      end
+    end
+  end
+end

data/lib/hooks/plugins/instruments/failbot_base.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require_relative "../../core/component_access"
+
+module Hooks
+  module Plugins
+    module Instruments
+      # Base class for all failbot instrument plugins
+      #
+      # This class provides the foundation for implementing custom error reporting
+      # instruments. Subclasses should implement specific methods for their target
+      # error reporting service (Sentry, Rollbar, Honeybadger, etc.).
+      #
+      # @abstract Subclass and implement service-specific error reporting methods
+      # @example Implementing a custom failbot instrument
+      #   class MySentryFailbot < Hooks::Plugins::Instruments::FailbotBase
+      #     def report(error_or_message, context = {})
+      #       case error_or_message
+      #       when Exception
+      #         Sentry.capture_exception(error_or_message, extra: context)
+      #       else
+      #         Sentry.capture_message(error_or_message.to_s, extra: context)
+      #       end
+      #       log.debug("Reported error to Sentry")
+      #     end
+      #   end
+      #
+      # @see Hooks::Plugins::Instruments::Failbot
+      class FailbotBase
+        include Hooks::Core::ComponentAccess
+
+        # Report an error or message to the error tracking service
+        #
+        # This is a no-op implementation that subclasses should override
+        # to provide actual error reporting functionality.
+        #
+        # @param error_or_message [Exception, String] The error to report or message string
+        # @param context [Hash] Additional context information about the error
+        # @return [void]
+        # @note Subclasses should implement this method for their specific service
+        # @example Override in subclass
+        #   def report(error_or_message, context = {})
+        #     if error_or_message.is_a?(Exception)
+        #       ErrorService.report_exception(error_or_message, context)
+        #     else
+        #       ErrorService.report_message(error_or_message, context)
+        #     end
+        #   end
+        def report(error_or_message, context = {})
+          # No-op implementation for base class
+        end
+
+        # Report a warning-level message
+        #
+        # This is a no-op implementation that subclasses should override
+        # to provide actual warning reporting functionality.
+        #
+        # @param message [String] Warning message to report
+        # @param context [Hash] Additional context information
+        # @return [void]
+        # @note Subclasses should implement this method for their specific service
+        # @example Override in subclass
+        #   def warn(message, context = {})
+        #     ErrorService.report_warning(message, context)
+        #   end
+        def warn(message, context = {})
+          # No-op implementation for base class
+        end
+      end
+    end
+  end
+end

data/lib/hooks/plugins/instruments/stats.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "stats_base"
+
+module Hooks
+  module Plugins
+    module Instruments
+      # Default stats instrument implementation
+      #
+      # This is a no-op implementation that provides the stats interface without
+      # actually sending metrics anywhere. It serves as a safe default when no
+      # custom stats implementation is configured.
+      #
+      # Users should replace this with their own implementation for services
+      # like DataDog, New Relic, StatsD, etc.
+      #
+      # @example Replacing with a custom implementation
+      #   # In your application initialization:
+      #   custom_stats = MyCustomStatsImplementation.new
+      #   Hooks::Core::GlobalComponents.stats = custom_stats
+      #
+      # @see Hooks::Plugins::Instruments::StatsBase
+      # @see Hooks::Core::GlobalComponents
+      class Stats < StatsBase
+        # Inherit from StatsBase to provide a default no-op implementation
+        # of the stats instrument interface.
+        #
+        # All methods from StatsBase are inherited and provide safe no-op behavior.
+      end
+    end
+  end
+end

data/lib/hooks/plugins/instruments/stats_base.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require_relative "../../core/component_access"
+
+module Hooks
+  module Plugins
+    module Instruments
+      # Base class for all stats instrument plugins
+      #
+      # This class provides the foundation for implementing custom metrics reporting
+      # instruments. Subclasses should implement specific methods for their target
+      # metrics service (DataDog, New Relic, StatsD, etc.).
+      #
+      # @abstract Subclass and implement service-specific metrics methods
+      # @example Implementing a custom stats instrument
+      #   class MyStatsImplementation < Hooks::Plugins::Instruments::StatsBase
+      #     def increment(metric_name, tags = {})
+      #       # Send increment metric to your service
+      #       MyMetricsService.increment(metric_name, tags)
+      #       log.debug("Sent increment metric: #{metric_name}")
+      #     end
+      #
+      #     def timing(metric_name, duration, tags = {})
+      #       # Send timing metric to your service
+      #       MyMetricsService.timing(metric_name, duration, tags)
+      #     end
+      #   end
+      #
+      # @see Hooks::Plugins::Instruments::Stats
+      class StatsBase
+        include Hooks::Core::ComponentAccess
+
+        # Record an increment metric
+        #
+        # This is a no-op implementation that subclasses should override
+        # to provide actual metrics reporting functionality.
+        #
+        # @param metric_name [String] Name of the metric to increment
+        # @param tags [Hash] Optional tags/labels for the metric
+        # @return [void]
+        # @note Subclasses should implement this method for their specific service
+        # @example Override in subclass
+        #   def increment(metric_name, tags = {})
+        #     statsd.increment(metric_name, tags: tags)
+        #   end
+        def increment(metric_name, tags = {})
+          # No-op implementation for base class
+        end
+
+        # Record a timing/duration metric
+        #
+        # This is a no-op implementation that subclasses should override
+        # to provide actual metrics reporting functionality.
+        #
+        # @param metric_name [String] Name of the timing metric
+        # @param duration [Numeric] Duration value (typically in milliseconds)
+        # @param tags [Hash] Optional tags/labels for the metric
+        # @return [void]
+        # @note Subclasses should implement this method for their specific service
+        # @example Override in subclass
+        #   def timing(metric_name, duration, tags = {})
+        #     statsd.timing(metric_name, duration, tags: tags)
+        #   end
+        def timing(metric_name, duration, tags = {})
+          # No-op implementation for base class
+        end
+
+        # Record a gauge metric
+        #
+        # This is a no-op implementation that subclasses should override
+        # to provide actual metrics reporting functionality.
+        #
+        # @param metric_name [String] Name of the gauge metric
+        # @param value [Numeric] Current value for the gauge
+        # @param tags [Hash] Optional tags/labels for the metric
+        # @return [void]
+        # @note Subclasses should implement this method for their specific service
+        # @example Override in subclass
+        #   def gauge(metric_name, value, tags = {})
+        #     statsd.gauge(metric_name, value, tags: tags)
+        #   end
+        def gauge(metric_name, value, tags = {})
+          # No-op implementation for base class
+        end
+      end
+    end
+  end
+end

data/lib/hooks/plugins/lifecycle.rb

@@ -1,11 +1,16 @@
 # frozen_string_literal: true
 
+require_relative "../core/global_components"
+require_relative "../core/component_access"
+
 module Hooks
   module Plugins
     # Base class for global lifecycle plugins
     #
     # Plugins can hook into request/response/error lifecycle events
     class Lifecycle
+      include Hooks::Core::ComponentAccess
+
       # Called before handler execution
       #
       # @param env [Hash] Rack environment

data/lib/hooks/utils/retry.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "retryable"
+
+# Utility module for retry functionality
+module Retry
+  # This method should be called as early as possible in the startup of your application
+  # It sets up the Retryable gem with custom contexts and passes through a few options
+  # Should the number of retries be reached without success, the last exception will be raised
+  #
+  # @param log [Logger] The logger to use for retryable logging
+  # @raise [ArgumentError] If no logger is provided
+  # @return [void]
+  def self.setup!(log: nil, log_retries: ENV.fetch("RETRY_LOG_RETRIES", "true") == "true")
+    raise ArgumentError, "a logger must be provided" if log.nil?
+
+    log_method = lambda do |retries, exception|
+      # :nocov:
+      if log_retries
+        log.debug("[retry ##{retries}] #{exception.class}: #{exception.message} - #{exception.backtrace.join("\n")}")
+      end
+      # :nocov:
+    end
+
+    ######## Retryable Configuration ########
+    # All defaults available here:
+    # https://github.com/nfedyashev/retryable/blob/6a04027e61607de559e15e48f281f3ccaa9750e8/lib/retryable/configuration.rb#L22-L33
+    Retryable.configure do |config|
+      config.contexts[:default] = {
+        on: [StandardError],
+        sleep: ENV.fetch("DEFAULT_RETRY_SLEEP", "1").to_i,
+        tries: ENV.fetch("DEFAULT_RETRY_TRIES", "10").to_i,
+        log_method:
+      }
+    end
+  end
+end

data/lib/hooks/version.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+# Main Hooks module containing version information
 module Hooks
-  VERSION = "0.0.2"
+  # Current version of the Hooks webhook framework
+  # @return [String] The version string following semantic versioning
+  VERSION = "0.0.4".freeze
 end

data/lib/hooks.rb

@@ -2,16 +2,29 @@
 
 require_relative "hooks/version"
 require_relative "hooks/core/builder"
-
-# Load all plugins (auth plugins, handler plugins, lifecycle hooks, etc.)
-Dir[File.join(__dir__, "hooks/plugins/**/*.rb")].sort.each do |file|
-  require file
-end
-
-# Load all utils
-Dir[File.join(__dir__, "hooks/utils/**/*.rb")].sort.each do |file|
-  require file
-end
+require_relative "hooks/core/config_loader"
+require_relative "hooks/core/config_validator"
+require_relative "hooks/core/logger_factory"
+require_relative "hooks/core/plugin_loader"
+require_relative "hooks/core/global_components"
+require_relative "hooks/core/component_access"
+require_relative "hooks/core/log"
+require_relative "hooks/core/failbot"
+require_relative "hooks/core/stats"
+require_relative "hooks/plugins/auth/base"
+require_relative "hooks/plugins/auth/hmac"
+require_relative "hooks/plugins/auth/shared_secret"
+require_relative "hooks/plugins/handlers/base"
+require_relative "hooks/plugins/handlers/default"
+require_relative "hooks/plugins/lifecycle"
+require_relative "hooks/plugins/instruments/stats_base"
+require_relative "hooks/plugins/instruments/failbot_base"
+require_relative "hooks/plugins/instruments/stats"
+require_relative "hooks/plugins/instruments/failbot"
+require_relative "hooks/utils/normalize"
+require_relative "hooks/utils/retry"
+require_relative "hooks/security"
+require_relative "hooks/version"
 
 # Main module for the Hooks webhook server framework
 module Hooks

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hooks-ruby
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.4
 platform: ruby
 authors:
 - github
@@ -78,26 +78,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.3'
-- !ruby/object:Gem::Dependency
-  name: grape-swagger
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.1'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 2.1.2
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.1'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 2.1.2
 - !ruby/object:Gem::Dependency
   name: puma
   requirement: !ruby/object:Gem::Requirement
@@ -150,19 +130,29 @@ files:
 - lib/hooks/app/endpoints/version.rb
 - lib/hooks/app/helpers.rb
 - lib/hooks/core/builder.rb
+- lib/hooks/core/component_access.rb
 - lib/hooks/core/config_loader.rb
 - lib/hooks/core/config_validator.rb
+- lib/hooks/core/failbot.rb
+- lib/hooks/core/global_components.rb
 - lib/hooks/core/log.rb
 - lib/hooks/core/logger_factory.rb
 - lib/hooks/core/plugin_loader.rb
+- lib/hooks/core/stats.rb
 - lib/hooks/plugins/auth/base.rb
 - lib/hooks/plugins/auth/hmac.rb
 - lib/hooks/plugins/auth/shared_secret.rb
+- lib/hooks/plugins/auth/timestamp_validator.rb
 - lib/hooks/plugins/handlers/base.rb
 - lib/hooks/plugins/handlers/default.rb
+- lib/hooks/plugins/instruments/failbot.rb
+- lib/hooks/plugins/instruments/failbot_base.rb
+- lib/hooks/plugins/instruments/stats.rb
+- lib/hooks/plugins/instruments/stats_base.rb
 - lib/hooks/plugins/lifecycle.rb
 - lib/hooks/security.rb
 - lib/hooks/utils/normalize.rb
+- lib/hooks/utils/retry.rb
 - lib/hooks/version.rb
 homepage: https://github.com/github/hooks
 licenses: