munster 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 11f34eb8fe918df292345851086c9190018d344bf73373125a1caec2e34984c8
-  data.tar.gz: 51741866e336befe8d663cb27e225f8f9adff3552f3247437a11b3d0d966557d
+  metadata.gz: 2b1a49a264687c05fd36a4331d73d98218d8ff6fcf8f972384fe26db3182a2c5
+  data.tar.gz: 75102940fdd3d31b317f16fbe05ff8d9135aeed8229c45fb20445348719e7ccd
 SHA512:
-  metadata.gz: 565266df3f8b518248b20ba6e5d7f12e420ee3cce7755f1d775a69c8ff3f99ef22db9d016051f23670f2b2e3326e72d17b28f0152641b052bf0a25daa4d04c12
-  data.tar.gz: cc689a7151f3dcf888efd826f87697c7cd552d6804b1e082242abffb6d83c2e4285e51feec3c97761ff1e6c6a30ff58d28d7762239af30ea6d6264c2934cb291
+  metadata.gz: f61d40aa299eeed7a67f2998ed346f1655da7c2be4b87f3e2f7d4470b2e0c5eadee345a6fca3f98a2aa85d573ca079e8306b9b97dc2b96f260703159ac7e587c
+  data.tar.gz: d41554221b5c68ef67e8136bdf7904c6392466a79cf5d0f377e7f5bb8df37ae0b9311d0cbf34bdc5f44876c7e21cecb03e9311fac202d4b98b43a553e91f5e99

data/.rubocop.yml

@@ -0,0 +1,9 @@
+require: standard
+
+AllCops:
+  TargetRubyVersion: 3.0
+
+inherit_gem:
+  standard: config/base.yml
+# Don't define any actual rubocop config here - this file is only used for
+# proper editor support, and not used on CI, formatters, nor anywhere else.

data/CHANGELOG.md

@@ -1,3 +1,10 @@
+## 0.2.0
+
+- Handler methods are now defined as instance methods for simplicity.
+- Define service_id in initializer with active_handlers, instead of handler class.
+- Use ruby 3.0 as a base for standard/rubocop, format all code according to it.
+- Introduce Rails common error reporter ( https://guides.rubyonrails.org/error_reporting.html )
+
 ## 0.1.0
 
 - Initial release

data/README.md

@@ -1,4 +1,5 @@
 # Munster
+
 Munster is a Rails engine that provides a webhook endpoint for receiving and processing webhooks from various services. Engine stores received webhook first and later processes webhook in a separete async process.
 
 Source code is extracted from https://cheddar.me/ main service to be used in internal microservices. Code here could be a subject to change while we flesh out details.
@@ -16,6 +17,7 @@ If bundler is not being used to manage dependencies, install the gem by executin
     $ gem install munster
 
 ## Usage
+
 Generate migrations and initializer file.
 
 `munster:install`
@@ -24,6 +26,24 @@ Mount munster engine in your routes.
 
 `mount Munster::Engine, at: "/webhooks"`
 
+## Requirements
+
+This project depends on two dependencies:
+
+- Ruby >= 3.0
+- Rails >= 7.0
+
+## Error reporter
+
+This gem uses [Rails common error reporter](https://guides.rubyonrails.org/error_reporting.html) to report any possible error to services like Honeybadger, Appsignal, Sentry and etc. Most of those services already support this common interface, if not - it's not that hard to add this support on your own.
+
+It's possible to provide additional context for every error. e.g.
+```
+Munster.configure do |config|
+  config.error_context = { appsignal: { namespace: "webhooks" } }
+end
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/example/Gemfile

@@ -6,7 +6,7 @@ git_source(:github) { |repo| "https://github.com/#{repo}.git" }
 ruby "3.2.2"
 
 # Bundle edge Rails instead: gem "rails", github: "rails/rails", branch: "main"
-gem "rails", "~> 7.0.8", ">= 7.0.8.1"
+gem "rails", ">= 7.0.8.1"
 
 # The modern asset pipeline for Rails [https://github.com/rails/propshaft]
 gem "propshaft"

data/example/Gemfile.lock

@@ -2,83 +2,96 @@ PATH
   remote: ..
   specs:
     munster (0.1.0)
-      rails (~> 7.0)
+      rails (~> 7.1)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    actioncable (7.0.8.1)
-      actionpack (= 7.0.8.1)
-      activesupport (= 7.0.8.1)
+    actioncable (7.1.3.3)
+      actionpack (= 7.1.3.3)
+      activesupport (= 7.1.3.3)
       nio4r (~> 2.0)
       websocket-driver (>= 0.6.1)
-    actionmailbox (7.0.8.1)
-      actionpack (= 7.0.8.1)
-      activejob (= 7.0.8.1)
-      activerecord (= 7.0.8.1)
-      activestorage (= 7.0.8.1)
-      activesupport (= 7.0.8.1)
+      zeitwerk (~> 2.6)
+    actionmailbox (7.1.3.3)
+      actionpack (= 7.1.3.3)
+      activejob (= 7.1.3.3)
+      activerecord (= 7.1.3.3)
+      activestorage (= 7.1.3.3)
+      activesupport (= 7.1.3.3)
       mail (>= 2.7.1)
       net-imap
       net-pop
       net-smtp
-    actionmailer (7.0.8.1)
-      actionpack (= 7.0.8.1)
-      actionview (= 7.0.8.1)
-      activejob (= 7.0.8.1)
-      activesupport (= 7.0.8.1)
+    actionmailer (7.1.3.3)
+      actionpack (= 7.1.3.3)
+      actionview (= 7.1.3.3)
+      activejob (= 7.1.3.3)
+      activesupport (= 7.1.3.3)
       mail (~> 2.5, >= 2.5.4)
       net-imap
       net-pop
       net-smtp
-      rails-dom-testing (~> 2.0)
-    actionpack (7.0.8.1)
-      actionview (= 7.0.8.1)
-      activesupport (= 7.0.8.1)
-      rack (~> 2.0, >= 2.2.4)
+      rails-dom-testing (~> 2.2)
+    actionpack (7.1.3.3)
+      actionview (= 7.1.3.3)
+      activesupport (= 7.1.3.3)
+      nokogiri (>= 1.8.5)
+      racc
+      rack (>= 2.2.4)
+      rack-session (>= 1.0.1)
       rack-test (>= 0.6.3)
-      rails-dom-testing (~> 2.0)
-      rails-html-sanitizer (~> 1.0, >= 1.2.0)
-    actiontext (7.0.8.1)
-      actionpack (= 7.0.8.1)
-      activerecord (= 7.0.8.1)
-      activestorage (= 7.0.8.1)
-      activesupport (= 7.0.8.1)
+      rails-dom-testing (~> 2.2)
+      rails-html-sanitizer (~> 1.6)
+    actiontext (7.1.3.3)
+      actionpack (= 7.1.3.3)
+      activerecord (= 7.1.3.3)
+      activestorage (= 7.1.3.3)
+      activesupport (= 7.1.3.3)
       globalid (>= 0.6.0)
       nokogiri (>= 1.8.5)
-    actionview (7.0.8.1)
-      activesupport (= 7.0.8.1)
+    actionview (7.1.3.3)
+      activesupport (= 7.1.3.3)
       builder (~> 3.1)
-      erubi (~> 1.4)
-      rails-dom-testing (~> 2.0)
-      rails-html-sanitizer (~> 1.1, >= 1.2.0)
-    activejob (7.0.8.1)
-      activesupport (= 7.0.8.1)
+      erubi (~> 1.11)
+      rails-dom-testing (~> 2.2)
+      rails-html-sanitizer (~> 1.6)
+    activejob (7.1.3.3)
+      activesupport (= 7.1.3.3)
       globalid (>= 0.3.6)
-    activemodel (7.0.8.1)
-      activesupport (= 7.0.8.1)
-    activerecord (7.0.8.1)
-      activemodel (= 7.0.8.1)
-      activesupport (= 7.0.8.1)
-    activestorage (7.0.8.1)
-      actionpack (= 7.0.8.1)
-      activejob (= 7.0.8.1)
-      activerecord (= 7.0.8.1)
-      activesupport (= 7.0.8.1)
+    activemodel (7.1.3.3)
+      activesupport (= 7.1.3.3)
+    activerecord (7.1.3.3)
+      activemodel (= 7.1.3.3)
+      activesupport (= 7.1.3.3)
+      timeout (>= 0.4.0)
+    activestorage (7.1.3.3)
+      actionpack (= 7.1.3.3)
+      activejob (= 7.1.3.3)
+      activerecord (= 7.1.3.3)
+      activesupport (= 7.1.3.3)
       marcel (~> 1.0)
-      mini_mime (>= 1.1.0)
-    activesupport (7.0.8.1)
+    activesupport (7.1.3.3)
+      base64
+      bigdecimal
       concurrent-ruby (~> 1.0, >= 1.0.2)
+      connection_pool (>= 2.2.5)
+      drb
       i18n (>= 1.6, < 2)
       minitest (>= 5.1)
+      mutex_m
       tzinfo (~> 2.0)
+    base64 (0.2.0)
+    bigdecimal (3.1.8)
     builder (3.2.4)
     concurrent-ruby (1.2.3)
+    connection_pool (2.4.1)
     crass (1.0.6)
     date (3.3.4)
     debug (1.9.2)
       irb (~> 1.10)
       reline (>= 0.3.8)
+    drb (2.2.1)
     erubi (1.12.0)
     globalid (1.2.1)
       activesupport (>= 6.1)
@@ -97,9 +110,9 @@ GEM
       net-pop
       net-smtp
     marcel (1.0.4)
-    method_source (1.1.0)
     mini_mime (1.1.5)
     minitest (5.22.3)
+    mutex_m (0.2.0)
     net-imap (0.4.11)
       date
       net-protocol
@@ -133,22 +146,27 @@ GEM
       nio4r (~> 2.0)
     racc (1.7.3)
     rack (2.2.9)
+    rack-session (1.0.2)
+      rack (< 3)
     rack-test (2.1.0)
       rack (>= 1.3)
-    rails (7.0.8.1)
-      actioncable (= 7.0.8.1)
-      actionmailbox (= 7.0.8.1)
-      actionmailer (= 7.0.8.1)
-      actionpack (= 7.0.8.1)
-      actiontext (= 7.0.8.1)
-      actionview (= 7.0.8.1)
-      activejob (= 7.0.8.1)
-      activemodel (= 7.0.8.1)
-      activerecord (= 7.0.8.1)
-      activestorage (= 7.0.8.1)
-      activesupport (= 7.0.8.1)
+    rackup (1.0.0)
+      rack (< 3)
+      webrick
+    rails (7.1.3.3)
+      actioncable (= 7.1.3.3)
+      actionmailbox (= 7.1.3.3)
+      actionmailer (= 7.1.3.3)
+      actionpack (= 7.1.3.3)
+      actiontext (= 7.1.3.3)
+      actionview (= 7.1.3.3)
+      activejob (= 7.1.3.3)
+      activemodel (= 7.1.3.3)
+      activerecord (= 7.1.3.3)
+      activestorage (= 7.1.3.3)
+      activesupport (= 7.1.3.3)
       bundler (>= 1.15.0)
-      railties (= 7.0.8.1)
+      railties (= 7.1.3.3)
     rails-dom-testing (2.2.0)
       activesupport (>= 5.0.0)
       minitest
@@ -156,13 +174,14 @@ GEM
     rails-html-sanitizer (1.6.0)
       loofah (~> 2.21)
       nokogiri (~> 1.14)
-    railties (7.0.8.1)
-      actionpack (= 7.0.8.1)
-      activesupport (= 7.0.8.1)
-      method_source
+    railties (7.1.3.3)
+      actionpack (= 7.1.3.3)
+      activesupport (= 7.1.3.3)
+      irb
+      rackup (>= 1.0.0)
       rake (>= 12.2)
-      thor (~> 1.0)
-      zeitwerk (~> 2.5)
+      thor (~> 1.0, >= 1.2.2)
+      zeitwerk (~> 2.6)
     rake (13.2.1)
     rdoc (6.6.3.1)
       psych (>= 4.0.0)
@@ -179,6 +198,7 @@ GEM
     timeout (0.4.1)
     tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
+    webrick (1.8.1)
     websocket-driver (0.7.6)
       websocket-extensions (>= 0.1.0)
     websocket-extensions (0.1.5)
@@ -197,7 +217,7 @@ DEPENDENCIES
   munster!
   propshaft
   puma (~> 5.0)
-  rails (~> 7.0.8, >= 7.0.8.1)
+  rails (>= 7.0.8.1)
   sqlite3 (~> 1.4)
   tzinfo-data
 

data/example/app/webhooks/{test_handler.rb → webhook_test_handler.rb}

@@ -4,25 +4,16 @@
 # if a banking provider test fails, indicating that the bank might be having an incident
 
 class WebhookTestHandler < Munster::BaseHandler
-  def self.valid?(request)
-    true
-  end
+  def valid?(request) = true
 
-  def self.process(webhook)
+  def process(webhook)
     return unless webhook.received?
     webhook.update!(status: "processing")
-    wait(5)
     webhook.update!(status: "processed")
   rescue
-    webhook.update!(status: "received")
+    webhook.update!(status: "error")
     raise
   end
 
-  def self.service_id
-    :test
-  end
-
-  def self.expose_errors_to_sender?
-    true
-  end
+  def expose_errors_to_sender? = true
 end

data/example/config/environments/production.rb

@@ -61,7 +61,7 @@ Rails.application.configure do
   # config.logger = ActiveSupport::TaggedLogging.new(Syslog::Logger.new "app-name")
 
   if ENV["RAILS_LOG_TO_STDOUT"].present?
-    logger = ActiveSupport::Logger.new(STDOUT)
+    logger = ActiveSupport::Logger.new($stdout)
     logger.formatter = config.log_formatter
     config.logger = ActiveSupport::TaggedLogging.new(logger)
   end

data/example/config/initializers/munster.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "../../app/webhooks/test_handler"
+require_relative "../../app/webhooks/webhook_test_handler"
 
 Munster.configure do |config|
   config.active_handlers = [WebhookTestHandler]

data/example/config/routes.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 Rails.application.routes.draw do
-  mount Munster::Engine, at: "/webhooks"
+  mount Munster::Engine, at: "/webhooks", as: "webhooks"
 end

data/lib/munster/base_handler.rb

@@ -4,64 +4,59 @@ require_relative "jobs/processing_job"
 
 module Munster
   class BaseHandler
-    class << self
-      # Reimplement this method, it's being used in WebhooksController to store incoming webhook.
-      # Also que for processing in the end.
-      # @return [void]
-      def handle(action_dispatch_request)
-        binary_body_str = action_dispatch_request.body.read.force_encoding(Encoding::BINARY)
-        attrs = {
-          body: binary_body_str,
-          handler_module_name: name,
-          handler_event_id: extract_event_id_from_request(action_dispatch_request)
-        }
-        webhook = Munster::ReceivedWebhook.create!(**attrs)
-
-        Munster.configuration.processing_job_class.perform_later(webhook)
-      rescue ActiveRecord::RecordNotUnique # Deduplicated
-        nil
-      end
+    # Gets called from the background job
+    def self.process(...)
+      new.process(...)
+    end
 
-      # This method will be used to process webhook by async worker.
-      def process(received_webhook)
-      end
+    # Reimplement this method, it's being used in WebhooksController to store incoming webhook.
+    # Also que for processing in the end.
+    # @return [void]
+    def handle(action_dispatch_request)
+      binary_body_str = action_dispatch_request.body.read.force_encoding(Encoding::BINARY)
+      attrs = {
+        body: binary_body_str,
+        handler_module_name: self.class.name,
+        handler_event_id: extract_event_id_from_request(action_dispatch_request)
+      }
+      webhook = Munster::ReceivedWebhook.create!(**attrs)
+
+      Munster.configuration.processing_job_class.perform_later(webhook)
+    rescue ActiveRecord::RecordNotUnique # Deduplicated
+      nil
+    end
 
-      # This should be defined for each webhook handler and should be unique.
-      # Otherwise controller will never pick up, that this handler exists.
-      #
-      # Please consider that this will be used in url, so don't use underscores or any other symbols that are not used in URL.
-      def service_id
-        :base
-      end
+    # This method will be used to process webhook by async worker.
+    def process(received_webhook)
+    end
 
-      # This method verifies that request actually comes from provider:
-      # signature validation, HTTP authentication, IP whitelisting and the like
-      def valid?(action_dispatch_request)
-        true
-      end
+    # This method verifies that request actually comes from provider:
+    # signature validation, HTTP authentication, IP whitelisting and the like
+    def valid?(action_dispatch_request)
+      true
+    end
 
-      # Default implementation just generates UUID, but if the webhook sender sends us
-      # an event ID we use it for deduplication.
-      def extract_event_id_from_request(action_dispatch_request)
-        SecureRandom.uuid
-      end
+    # Default implementation just generates UUID, but if the webhook sender sends us
+    # an event ID we use it for deduplication.
+    def extract_event_id_from_request(action_dispatch_request)
+      SecureRandom.uuid
+    end
 
-      # Webhook senders have varying retry behaviors, and often you want to "pretend"
-      # everything is fine even though there is an error so that they keep sending you
-      # data and do not disable your endpoint forcibly. We allow this to be configured
-      # on a per-handler basis - a better webhooks sender will be able to make out
-      # some sense of the errors.
-      def expose_errors_to_sender?
-        false
-      end
+    # Webhook senders have varying retry behaviors, and often you want to "pretend"
+    # everything is fine even though there is an error so that they keep sending you
+    # data and do not disable your endpoint forcibly. We allow this to be configured
+    # on a per-handler basis - a better webhooks sender will be able to make out
+    # some sense of the errors.
+    def expose_errors_to_sender?
+      false
+    end
 
-      # Tells the controller whether this handler is active or not. This can be used
-      # to deactivate a particular handler via feature flags for example, or use other
-      # logic to determine whether the handler may be used to create new received webhooks
-      # in the system. This is primarily needed for load shedding.
-      def active?
-        true
-      end
+    # Tells the controller whether this handler is active or not. This can be used
+    # to deactivate a particular handler via feature flags for example, or use other
+    # logic to determine whether the handler may be used to create new received webhooks
+    # in the system. This is primarily needed for load shedding.
+    def active?
+      true
     end
   end
 end

data/lib/munster/controllers/receive_webhooks_controller.rb

@@ -5,22 +5,22 @@ module Munster
     class HandlerRefused < StandardError
     end
 
+    class HandlerInactive < StandardError
+    end
+
     def create
-      handler = lookup_handler(params[:service_id])
-      return render_error("Webhook handler is inactive", :service_unavailable) unless handler.active?
+      handler = lookup_handler(params[:service_id]).new
 
+      raise HandlerInactive unless handler.active?
       raise HandlerRefused unless handler.valid?(request)
 
-      # FIXME: Duplicated webhook will be overwritten here and processing job will be quite for second time.
-      # This will generate a following error in this case:
-      #    Error performing Munster::ProcessingJob (Job ID: b40f3f28-81be-4c99-bce8-9ad879ec9754) from Async(default) in 9.95ms: ActiveRecord::RecordInvalid (Validation failed: Status Invalid transition from processing to received):
-      #
-      # This should be handled properly.
       handler.handle(request)
       head :ok
+    rescue KeyError # handler was not found, so we return generic 404 error.
+      render_error("Required parameters were not present in the request", :not_found)
     rescue => e
-      # TODO: add exception handler here
-      # Appsignal.add_exception(e)
+      Rails.error.set_context(**Munster.configuration.error_context)
+      Rails.error.report(e)
 
       if handler&.expose_errors_to_sender?
         error_for_sender_from_exception(e)
@@ -33,8 +33,10 @@ module Munster
       case e
       when HandlerRefused
         render_error("Webhook handler did not validate the request (signature or authentication may be invalid)", :forbidden)
-      when JSON::ParserError, KeyError
-        render_error("Required parameters were not present in the request or the request body was not valid JSON", :bad_request)
+      when HandlerInactive
+        render_error("Webhook handler is inactive", :service_unavailable)
+      when JSON::ParserError
+        render_error("Request body is not a valid JSON", :bad_request)
       else
         render_error("Internal error", :internal_server_error)
       end
@@ -42,11 +44,11 @@ module Munster
 
     def render_error(message_str, status_sym)
       json = {error: message_str}.to_json
-      render(json:, status: status_sym)
+      render(json: json, status: status_sym)
     end
 
     def lookup_handler(service_id_str)
-      Munster.configuration.active_handlers.index_by(&:service_id).fetch(service_id_str.to_sym)
+      Munster.configuration.active_handlers.with_indifferent_access.fetch(service_id_str)
     end
   end
 end

data/lib/munster/templates/munster.rb

@@ -1,4 +1,28 @@
 Munster.configure do |config|
-  config.active_handlers = []
-  config.processing_job_class = Munster::ProcessingJob
+  # Active Handlers are defined as hash with key as a service_id and handler class  that would handle webhook request.
+  # Example:
+  #   {:test => TestHandler, :inactive => InactiveHandler}
+  config.active_handlers = {}
+
+  # It's possible to overwrite default processing job to enahance it. As example if you want to add proper locking or retry mechanism.
+  #
+  # Example:
+  #
+  # class WebhookProcessingJob < Munster::ProcessingJob
+  #   def perform(webhook)
+  #     TokenLock.with(name: "webhook-processing-#{webhook.id}") do
+  #       super(webhook)
+  #     end
+  #   end
+  #
+  # This is how you can change processing job:
+  #
+  # config.processing_job_class = WebhookProcessingJob
+
+  # We're using a common interface for error reporting provided by Rails, e.g Rails.error.report. In some cases
+  # you want to enhance those errors with additional context. As example to provide a namespace:
+  #
+  # { appsignal: { namespace: "webhooks" } }
+  #
+  # config.error_context = { appsignal: { namespace: "webhooks" } }
 end

data/lib/munster/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Munster
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/munster.rb

@@ -2,8 +2,8 @@
 
 require_relative "munster/version"
 require_relative "munster/engine"
-require "active_support/configurable"
 require_relative "munster/jobs/processing_job"
+require "active_support/configurable"
 
 module Munster
   def self.configuration
@@ -20,4 +20,5 @@ class Munster::Configuration
 
   config_accessor(:processing_job_class) { Munster::ProcessingJob }
   config_accessor(:active_handlers) { [] }
+  config_accessor(:error_context) { {} }
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: munster
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Stanislav Katkov
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-06-03 00:00:00.000000000 Z
+date: 2024-06-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -88,6 +88,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".editorconfig"
+- ".rubocop.yml"
 - ".standard.yml"
 - CHANGELOG.md
 - LICENSE
@@ -110,7 +111,7 @@ files:
 - example/app/models/application_record.rb
 - example/app/models/concerns/.keep
 - example/app/views/layouts/application.html.erb
-- example/app/webhooks/test_handler.rb
+- example/app/webhooks/webhook_test_handler.rb
 - example/bin/bundle
 - example/bin/rails
 - example/bin/rake