webhukhs 0.5.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a3649db576ac151f62fa71f5e929d9b62f9a7dcbbff4c9b831e67fc4141e6524
+  data.tar.gz: 6d1fa28e296c7449e1c5a55b7f0758f043ff1b3c66098cd16c0e9a55db9d3f16
+SHA512:
+  metadata.gz: 2c05c1b968a0ac107f3366e9d07903a460da24c1d835c9d60e94948e7cd46946d9f067c733433c18fc092a80c2bf0c1eabee4c6d161a6ec2779bc5ccc30214a9
+  data.tar.gz: 211a266f0ff4951265f2d568427c034010f9367c5a9a0cf653d767457fa9a57b2da0c45b98c2b534015a2e58900e8592d71342accfd247b888060f4f8e54f8c0

data/.editorconfig

@@ -0,0 +1,14 @@
+# top-most EditorConfig file
+root = true
+
+# Unix-style newlines with a newline ending every file
+# Two spaces for indenting
+[*]
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 2
+charset = utf-8
+trim_trailing_whitespace = true
+max_line_length = 120
+

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/.standard.yml

@@ -0,0 +1,3 @@
+# For available configuration options, see:
+#   https://github.com/standardrb/standard
+ruby_version: 3.0

data/Appraisals

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+appraise "rails-7.1" do
+  gem "rails", "~> 7.1.0"
+end
+
+appraise "rails-8.1" do
+  gem "rails", "~> 8.1"
+end
+
+appraise "rails-8.0" do
+  gem "rails", "~> 8.0"
+end

data/CHANGELOG.md

@@ -0,0 +1,54 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+This format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## Unreleased
+
+## 0.5.0
+
+- Forked from [munster](https://github.com/cheddar-me/munster) and renamed to webhukhs
+- Changed GitHub repository to https://github.com/skatkov/webhukhs
+- Testing against rails 7.1, rails 8.0 and rails 8.1
+- Ruby 3.4 used as a default testing target
+- Replaced deprecated `ActiveSupport::Configurable` with `class_attribute`
+
+## 0.4.2
+
+- When processing a webhook, print messages to the ActiveJob logger. This allows for quicker debugging if the app does not have an error tracking service set up
+
+## 0.4.1
+
+- Webhook processor now requires `active_job/railtie`, instead of `active_job`. It requires GlobalID to work and that get's required only with railtie.
+- Adding a state transition from `error` to `received`. Proccessing job will be enqueued automatic after this transition was executed.
+
+## 0.4.0
+
+- Limit's size of request body, since otherwise there can be a large attack vector where random senders can spam the database with data and cause a denial of service. With background validation, this is one of few cases where we want to reject the payload without persisting it.
+- Manage's `state` of `ReceivedWebhook` from background job itself. This frees up the handler to actually do the work associated with processing only. The job will manage the rest.
+- Use's `valid?` in background job instead of the controller. Most common configuration issue is an incorrectly specified signing secret, or an incorrectly implemented input validation. When these happen, it is better to allow the webhook to be reprocessed
+- Use's instance methods in handlers instead of class methods, as they are shorter to define. Assume a handler module supports `.new` - with a module using singleton methods it may return `self` from `new`.
+- In config, allow handlers specified as strings. Module resolution in Rails happens after config gets loaded, because config may alter to Zeitwerk load paths. To allow config to get loaded and to allow handlers to be autoloaded using Zeitwerk, handler modules have to be resolved lazily. This also permits handlers to be reloadable, like any module under Rails' autoloading control.
+- Simplify's the Rails app used in tests to be small and keep it in a single file
+- If a handler is willing to expose errors to the caller, let Rails rescue the error and display an error page or do whatever else is configured for Rails globally.
+- Store's request headers with received webhook to allow for async validation. Run `bin/rails g webhukhs:install` to add the required migration.
+
+## 0.3.1
+
+- BaseHandler#expose_errors_to_sender? defaults to true now.
+
+## 0.3.0
+
+- state_machine_enum library was moved into its own library/gem.
+- Provide handled: true attribute for Rails.error.report method, because it is required in Rails 7.0.
+
+## 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.
+- Use Rails common error reporter ( https://guides.rubyonrails.org/error_reporting.html )
+
+## 0.1.0
+
+- Initial release

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Cheddar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,71 @@
+# Webhukhs
+
+Webhukhs is a Rails engine for processing webhooks from various services. Engine saves webhook in database first and later processes webhook in async process.
+
+This is a fork of [cheddar-me/munster](https://github.com/cheddar-me/munster). Original project became unmaintained, so I continued it.
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add webhukhs
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+    $ gem install webhukhs
+
+## Usage
+
+Generate migrations and initializer file.
+
+`bin/rails g webhukhs:install`
+
+Mount webhukhs engine in your routes.
+
+```ruby
+mount Webhukhs::Engine, at: "/webhooks"
+```
+
+Define a class for your first handler (let's call it `ExampleHandler`) and inherit it from `Webhukhs::BaseHandler`. Place it somewhere where Rails autoloading can find it, and add it to your `webhukhs.rb` config file:
+
+```ruby
+config.active_handlers = {
+  "example" => "ExampleHandler"
+}
+```
+
+## Example handlers
+
+We provide a number of webhook handlers which demonstrate certain features of Webhukhs. You will find them in `handler-examples`.
+
+## 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.
+
+```ruby
+Webhukhs.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.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/skatkov/webhukhs.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "rake/testtask"
+require "bundler/gem_tasks"
+require "standard/rake"
+
+task :format do
+  `bundle exec standardrb --fix`
+  `bundle exec magic_frozen_string_literal .`
+end
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+
+  file_name = ARGV[1]
+
+  t.test_files = if file_name
+    [file_name]
+  else
+    FileList["test/**/*_test.rb"]
+  end
+end
+
+task default: [:test, :standard]

data/config/routes.rb

@@ -0,0 +1,3 @@
+Webhukhs::Engine.routes.draw do
+  post "/:service_id", to: "receive_webhooks#create", namespace: "webhukhs"
+end

data/example/.gitattributes

@@ -0,0 +1,7 @@
+# See https://git-scm.com/docs/gitattributes for more about git attribute files.
+
+# Mark the database schema as having been generated.
+db/schema.rb linguist-generated
+
+# Mark any vendored files as having been vendored.
+vendor/* linguist-vendored

data/example/.gitignore

@@ -0,0 +1,29 @@
+# See https://help.github.com/articles/ignoring-files for more about ignoring files.
+#
+# If you find yourself ignoring temporary files generated by your text editor
+# or operating system, you probably want to add a global ignore instead:
+#   git config --global core.excludesfile '~/.gitignore_global'
+
+# Ignore bundler config.
+/.bundle
+
+# Ignore the default SQLite database.
+/db/*.sqlite3
+/db/*.sqlite3-*
+
+# Ignore all logfiles and tempfiles.
+/log/*
+/tmp/*
+!/log/.keep
+!/tmp/.keep
+
+# Ignore pidfiles, but keep the directory.
+/tmp/pids/*
+!/tmp/pids/
+!/tmp/pids/.keep
+
+
+/public/assets
+
+# Ignore master key for decrypting credentials and more.
+/config/master.key

data/example/.ruby-version

@@ -0,0 +1 @@
+ruby-3.2.2

data/example/Gemfile

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+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.1"
+
+# The modern asset pipeline for Rails [https://github.com/rails/propshaft]
+gem "propshaft"
+
+# Use sqlite3 as the database for Active Record
+gem "sqlite3", "~> 1.4"
+
+# Use the Puma web server [https://github.com/puma/puma]
+gem "puma", "~> 5.0"
+
+# Windows does not include zoneinfo files, so bundle the tzinfo-data gem
+gem "tzinfo-data", platforms: %i[mingw mswin x64_mingw jruby]
+gem "webhukhs", path: "../"
+
+group :development, :test do
+  # See https://guides.rubyonrails.org/debugging_rails_applications.html#debugging-with-the-debug-gem
+  gem "debug", platforms: %i[mri mingw x64_mingw]
+end
+
+group :development do
+  # Speed up commands on slow machines / big apps [https://github.com/rails/spring]
+  # gem "spring"
+end

data/example/Gemfile.lock

@@ -0,0 +1,228 @@
+PATH
+  remote: ..
+  specs:
+    munster (0.1.0)
+      rails (~> 7.1)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    actioncable (7.1.3.3)
+      actionpack (= 7.1.3.3)
+      activesupport (= 7.1.3.3)
+      nio4r (~> 2.0)
+      websocket-driver (>= 0.6.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.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.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.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.1.3.3)
+      activesupport (= 7.1.3.3)
+      builder (~> 3.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.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)
+    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)
+    i18n (1.14.5)
+      concurrent-ruby (~> 1.0)
+    io-console (0.7.2)
+    irb (1.13.1)
+      rdoc (>= 4.0.0)
+      reline (>= 0.4.2)
+    loofah (2.22.0)
+      crass (~> 1.0.2)
+      nokogiri (>= 1.12.0)
+    mail (2.8.1)
+      mini_mime (>= 0.1.1)
+      net-imap
+      net-pop
+      net-smtp
+    marcel (1.0.4)
+    mini_mime (1.1.5)
+    minitest (5.22.3)
+    mutex_m (0.2.0)
+    net-imap (0.4.11)
+      date
+      net-protocol
+    net-pop (0.1.2)
+      net-protocol
+    net-protocol (0.2.2)
+      timeout
+    net-smtp (0.5.0)
+      net-protocol
+    nio4r (2.7.3)
+    nokogiri (1.16.5-aarch64-linux)
+      racc (~> 1.4)
+    nokogiri (1.16.5-arm-linux)
+      racc (~> 1.4)
+    nokogiri (1.16.5-arm64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.16.5-x86-linux)
+      racc (~> 1.4)
+    nokogiri (1.16.5-x86_64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.16.5-x86_64-linux)
+      racc (~> 1.4)
+    propshaft (0.8.0)
+      actionpack (>= 7.0.0)
+      activesupport (>= 7.0.0)
+      rack
+      railties (>= 7.0.0)
+    psych (5.1.2)
+      stringio
+    puma (5.6.8)
+      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)
+    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.1.3.3)
+    rails-dom-testing (2.2.0)
+      activesupport (>= 5.0.0)
+      minitest
+      nokogiri (>= 1.6)
+    rails-html-sanitizer (1.6.0)
+      loofah (~> 2.21)
+      nokogiri (~> 1.14)
+    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, >= 1.2.2)
+      zeitwerk (~> 2.6)
+    rake (13.2.1)
+    rdoc (6.6.3.1)
+      psych (>= 4.0.0)
+    reline (0.5.7)
+      io-console (~> 0.5)
+    sqlite3 (1.7.3-aarch64-linux)
+    sqlite3 (1.7.3-arm-linux)
+    sqlite3 (1.7.3-arm64-darwin)
+    sqlite3 (1.7.3-x86-linux)
+    sqlite3 (1.7.3-x86_64-darwin)
+    sqlite3 (1.7.3-x86_64-linux)
+    stringio (3.1.0)
+    thor (1.3.1)
+    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)
+    zeitwerk (2.6.14)
+
+PLATFORMS
+  aarch64-linux
+  arm-linux
+  arm64-darwin
+  x86-linux
+  x86_64-darwin
+  x86_64-linux
+
+DEPENDENCIES
+  debug
+  munster!
+  propshaft
+  puma (~> 5.0)
+  rails (>= 7.0.8.1)
+  sqlite3 (~> 1.4)
+  tzinfo-data
+
+RUBY VERSION
+   ruby 3.2.2p53
+
+BUNDLED WITH
+   2.5.6

data/example/README.md

@@ -0,0 +1,24 @@
+# README
+
+This README would normally document whatever steps are necessary to get the
+application up and running.
+
+Things you may want to cover:
+
+* Ruby version
+
+* System dependencies
+
+* Configuration
+
+* Database creation
+
+* Database initialization
+
+* How to run the test suite
+
+* Services (job queues, cache servers, search engines, etc.)
+
+* Deployment instructions
+
+* ...

data/example/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# Add your own tasks in files placed in lib/tasks ending in .rake,
+# for example lib/tasks/capistrano.rake, and they will automatically be available to Rake.
+
+require_relative "config/application"
+
+Rails.application.load_tasks

data/example/app/assets/stylesheets/application.css

@@ -0,0 +1 @@
+/* Application styles */

data/example/app/controllers/application_controller.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+class ApplicationController < ActionController::Base
+end

data/example/app/helpers/application_helper.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+module ApplicationHelper
+end

data/example/app/models/application_record.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class ApplicationRecord < ActiveRecord::Base
+  primary_abstract_class
+end

data/example/app/views/layouts/application.html.erb

@@ -0,0 +1,15 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Example</title>
+    <meta name="viewport" content="width=device-width,initial-scale=1">
+    <%= csrf_meta_tags %>
+    <%= csp_meta_tag %>
+
+    <%= stylesheet_link_tag "application" %>
+  </head>
+
+  <body>
+    <%= yield %>
+  </body>
+</html>

data/example/app/webhooks/webhook_test_handler.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# This handler accepts webhooks from our integration tests. This webhook gets dispatched
+# if a banking provider test fails, indicating that the bank might be having an incident
+class WebhookTestHandler < Webhukhs::BaseHandler
+  def valid?(request) = true
+
+  def process(webhook)
+    Rails.logger.info { webhook.request.params.fetch(:payment_id) }
+  end
+
+  def expose_errors_to_sender? = true
+end