bake retryable into the project

Author: GrantBirki

docs/handler_plugins.md

@@ -0,0 +1,43 @@
+# Handler Plugins
+
+This document provides 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.
+
+## Built-in Features
+
+This section goes into details on the built-in features that exist in all handler plugins that extend the `Hooks::Plugins::Handlers::Base` class.
+
+### `#log`
+
+The `log.debug`, `log.info`, `log.warn`, and `log.error` methods are available in all handler plugins. They are used to log messages at different levels of severity.
+
+### `#Retryable.with_context(:default)`
+
+This method uses a default `Retryable` context to handle retries. It is used to wrap the execution of a block of code that may need to be retried in case of failure.
+
+Here is how it can be used in a handler plugin:
+
+```ruby
+class Example < Hooks::Plugins::Handlers::Base
+  # Example webhook handler
+  #
+  # @param payload [Hash, String] Webhook payload
+  # @param headers [Hash<String, String>] HTTP headers
+  # @param config [Hash] Endpoint configuration
+  # @return [Hash] Response data
+  def call(payload:, headers:, config:)
+    result = Retryable.with_context(:default) do
+      some_operation_that_might_fail()
+    end
+
+    log.debug("operation result: #{result}")
+
+    return {
+      status: "success"
+    }
+  end
+end
+```
+
+> If `Retryable.with_context(:default)` fails after all retries, it will re-raise the last exception encountered.
+
+See the source code at `lib/hooks/utils/retry.rb` for more details on how `Retryable.with_context(:default)` works.

lib/hooks/core/builder.rb

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

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

spec/acceptance/docker-compose.yml

@@ -11,6 +11,8 @@ services:
       GITHUB_WEBHOOK_SECRET: "octoawesome-secret"
       ALT_WEBHOOK_SECRET: "octoawesome-too-secret"
       SHARED_SECRET: "octoawesome-shared-secret"
+      DEFAULT_RETRY_SLEEP: 0
+      RETRY_LOG_RETRIES: "false"
     command: ["script/server"]
     healthcheck:
       test: ["CMD", "curl", "-f", "http://0.0.0.0:8080/health"]

spec/acceptance/plugins/handlers/team1_handler.rb

@@ -9,6 +9,20 @@ class Team1Handler < Hooks::Plugins::Handlers::Base
   # @param config [Hash] Endpoint configuration
   # @return [Hash] Response data
   def call(payload:, headers:, config:)
+    log.debug("got a call to #{self.class.name} with payload: #{payload.inspect}")
+
+    # demo the global retryable instance is a kinda silly way
+    fail_on_first_time = true
+    foo = Retryable.with_context(:default) do
+      if fail_on_first_time
+        fail_on_first_time = false
+        raise StandardError, "This is a demo error to show retryable in action"
+      end
+
+      "bar"
+    end
+    log.debug("we got back the value of foo: #{foo}")
+
     # Process the payload based on type
     if payload.is_a?(Hash)
       event_type = payload[:event_type] || "unknown"