Implement error! method for handler subclasses

Co-authored-by: GrantBirki <[email protected]>

Author: Copilot

lib/hooks/app/api.rb

@@ -7,6 +7,7 @@
 require_relative "auth/auth"
 require_relative "rack_env_builder"
 require_relative "../plugins/handlers/base"
+require_relative "../plugins/handlers/error"
 require_relative "../plugins/handlers/default"
 require_relative "../core/logger_factory"
 require_relative "../core/log"
@@ -110,6 +111,25 @@ def self.create(config:, endpoints:, log:)
                   status 200
                   content_type "application/json"
                   response.to_json
+                rescue Hooks::Plugins::Handlers::Error => e
+                  # Handler called error! method - return the specified error response
+                  log.info("handler returned error response: #{handler_class_name} - status: #{e.status} - body: #{e.body}")
+
+                  # Call lifecycle hooks: on_response (treating error! as a valid response)
+                  if defined?(rack_env)
+                    Core::PluginLoader.lifecycle_plugins.each do |plugin|
+                      plugin.on_response(rack_env, e.body)
+                    end
+                  end
+
+                  status e.status
+                  content_type "application/json"
+                  case e.body
+                  when String
+                    e.body
+                  else
+                    e.body.to_json
+                  end
                 rescue StandardError => e
                   err_msg = "Error processing webhook event with handler: #{handler_class_name} - #{e.message} " \
                     "- request_id: #{request_id} - path: #{full_path} - method: #{http_method} - " \

lib/hooks/plugins/handlers/base.rb

@@ -2,6 +2,7 @@
 
 require_relative "../../core/global_components"
 require_relative "../../core/component_access"
+require_relative "error"
 
 module Hooks
   module Plugins
@@ -23,6 +24,28 @@ class Base
         def call(payload:, headers:, env:, config:)
           raise NotImplementedError, "Handler must implement #call method"
         end
+
+        # Terminate request processing with a custom error response
+        #
+        # This method provides the same interface as Grape's `error!` method,
+        # allowing handlers to immediately stop processing and return a specific
+        # error response to the client.
+        #
+        # @param body [Object] The error body/data to return to the client
+        # @param status [Integer] The HTTP status code to return (default: 500)
+        # @raise [Hooks::Plugins::Handlers::Error] Always raises to terminate processing
+        #
+        # @example Return a custom error with status 400
+        #   error!({ error: "validation_failed", message: "Invalid payload" }, 400)
+        #
+        # @example Return a simple string error with status 401
+        #   error!("Unauthorized", 401)
+        #
+        # @example Return an error with default 500 status
+        #   error!({ error: "internal_error", message: "Something went wrong" })
+        def error!(body, status = 500)
+          raise Error.new(body, status)
+        end
       end
     end
   end

lib/hooks/plugins/handlers/error.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Hooks
+  module Plugins
+    module Handlers
+      # Custom exception class for handler errors
+      #
+      # This exception is used when handlers call the `error!` method to
+      # immediately terminate request processing and return a specific error response.
+      # It carries the error details back to the Grape API context where it can be
+      # properly formatted and returned to the client.
+      #
+      # @example Usage in handler
+      #   error!({ error: "validation_failed", message: "Invalid payload" }, 400)
+      #
+      # @see Hooks::Plugins::Handlers::Base#error!
+      class Error < StandardError
+        # @return [Object] The error body/data to return to the client
+        attr_reader :body
+
+        # @return [Integer] The HTTP status code to return
+        attr_reader :status
+
+        # Initialize a new handler error
+        #
+        # @param body [Object] The error body/data to return to the client
+        # @param status [Integer] The HTTP status code to return (default: 500)
+        def initialize(body, status = 500)
+          @body = body
+          @status = status.to_i
+          super("Handler error: #{status} - #{body}")
+        end
+      end
+    end
+  end
+end

spec/acceptance/acceptance_tests.rb

@@ -496,26 +496,15 @@ def expired_unix_timestamp(seconds_ago = 600)
       end
 
       it "sends a POST request to the /webhooks/boomtown_with_error endpoint and it explodes" do
-        # TODO: Fix this acceptance test - the current error looks like this:
-        # 1) Hooks endpoints boomtown_with_error sends a POST request to the /webhooks/boomtown_with_error endpoint and it explodes
-          # Failure/Error: expect(response.body).to include(expected_body_content) if expected_body_content
-            #expected "{\"error\":\"server_error\",\"message\":\"undefined method 'error!' for an instance of BoomtownWithE...thread_pool.rb:167:in 'block in #Puma::ThreadPool#spawn_thread'\",\"handler\":\"BoomtownWithError\"}" to include "the payload triggered a boomtown error"
-          # ./spec/acceptance/acceptance_tests.rb:28:in 'RSpec::ExampleGroups::Hooks#expect_response'
-          # ./spec/acceptance/acceptance_tests.rb:501:in 'block (4 levels) in <top (required)>'
-
-        # payload = { boom: true }.to_json
-        # response = make_request(:post, "/webhooks/boomtown_with_error", payload, json_headers)
-        # expect_response(response, Net::HTTPInternalServerError, "the payload triggered a boomtown error")
-
-        # body = parse_json_response(response)
-        # expect(body["error"]).to eq("server_error")
-        # expect(body["message"]).to eq("the payload triggered a boomtown error")
-        # expect(body).to have_key("backtrace")
-        # expect(body["backtrace"]).to be_a(String)
-        # expect(body).to have_key("request_id")
-        # expect(body["request_id"]).to be_a(String)
-        # expect(body).to have_key("handler")
-        # expect(body["handler"]).to eq("BoomtownWithError")
+        payload = { boom: true }.to_json
+        response = make_request(:post, "/webhooks/boomtown_with_error", payload, json_headers)
+        expect_response(response, Net::HTTPInternalServerError, "the payload triggered a boomtown error")
+
+        body = parse_json_response(response)
+        expect(body["error"]).to eq("boomtown_with_error")
+        expect(body["message"]).to eq("the payload triggered a boomtown error")
+        expect(body).to have_key("request_id")
+        expect(body["request_id"]).to be_a(String)
       end
     end
   end

spec/unit/lib/hooks/handlers/base_spec.rb

@@ -250,4 +250,42 @@ def report(error_or_message, context = {})
       end
     end
   end
+
+  describe "#error!" do
+    let(:handler) { described_class.new }
+
+    it "raises a handler error with default status 500" do
+      expect {
+        handler.error!("Something went wrong")
+      }.to raise_error(Hooks::Plugins::Handlers::Error) do |error|
+        expect(error.body).to eq("Something went wrong")
+        expect(error.status).to eq(500)
+      end
+    end
+
+    it "raises a handler error with custom status" do
+      expect {
+        handler.error!({ error: "validation_failed", message: "Invalid input" }, 400)
+      }.to raise_error(Hooks::Plugins::Handlers::Error) do |error|
+        expect(error.body).to eq({ error: "validation_failed", message: "Invalid input" })
+        expect(error.status).to eq(400)
+      end
+    end
+
+    it "can be called from subclasses" do
+      test_handler = Class.new(described_class) do
+        def call(payload:, headers:, env:, config:)
+          error!("Custom error from subclass", 422)
+        end
+      end
+
+      handler = test_handler.new
+      expect {
+        handler.call(payload: {}, headers: {}, env: {}, config: {})
+      }.to raise_error(Hooks::Plugins::Handlers::Error) do |error|
+        expect(error.body).to eq("Custom error from subclass")
+        expect(error.status).to eq(422)
+      end
+    end
+  end
 end

spec/unit/lib/hooks/handlers/error_spec.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+describe Hooks::Plugins::Handlers::Error do
+  describe "#initialize" do
+    it "creates an error with default status 500" do
+      error = described_class.new("test error")
+      expect(error.body).to eq("test error")
+      expect(error.status).to eq(500)
+      expect(error.message).to eq("Handler error: 500 - test error")
+    end
+
+    it "creates an error with custom status" do
+      error = described_class.new({ error: "validation_failed" }, 400)
+      expect(error.body).to eq({ error: "validation_failed" })
+      expect(error.status).to eq(400)
+      expect(error.message).to eq("Handler error: 400 - {error: \"validation_failed\"}")
+    end
+
+    it "converts status to integer" do
+      error = described_class.new("test", "404")
+      expect(error.status).to eq(404)
+    end
+  end
+
+  describe "inheritance" do
+    it "inherits from StandardError" do
+      expect(described_class.ancestors).to include(StandardError)
+    end
+  end
+end