webhukhs 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a3649db576ac151f62fa71f5e929d9b62f9a7dcbbff4c9b831e67fc4141e6524
-  data.tar.gz: 6d1fa28e296c7449e1c5a55b7f0758f043ff1b3c66098cd16c0e9a55db9d3f16
+  metadata.gz: 83faf212a808c37ee8d293dc4e1d74d82d8ce0a7fb653d3850ee01ff9da7000b
+  data.tar.gz: 4d599377df025e4bd52c885efd5067127e50876eef1be8a9ee3117960d8bcf14
 SHA512:
-  metadata.gz: 2c05c1b968a0ac107f3366e9d07903a460da24c1d835c9d60e94948e7cd46946d9f067c733433c18fc092a80c2bf0c1eabee4c6d161a6ec2779bc5ccc30214a9
-  data.tar.gz: 211a266f0ff4951265f2d568427c034010f9367c5a9a0cf653d767457fa9a57b2da0c45b98c2b534015a2e58900e8592d71342accfd247b888060f4f8e54f8c0
+  metadata.gz: a0834f112be61de4bf50a6a99d8eee1ebd439e11c2a4ab26fe2e178d4ba70baeee4c62a06ea13fac44f2797bf5d7db40689249f7252cc3e5038d76f4997fdac2
+  data.tar.gz: 4070b8ad54761f7a888659c52a5284b660f86e729f645a8b1cc2658193b408b1852a4c6551147bd4ffe07f2c55f37dfb7b5aa8401388af44a2f762f1af973ccc

data/.standard.yml

@@ -1,3 +1,5 @@
 # For available configuration options, see:
 #   https://github.com/standardrb/standard
 ruby_version: 3.0
+ignore:
+  - 'gemfiles/**/*'

data/.yard-lint.yml

@@ -0,0 +1,295 @@
+# YARD-Lint Configuration
+# See https://github.com/mensfeld/yard-lint for documentation
+
+# Global settings for all validators
+AllValidators:
+  # YARD command-line options (applied to all validators by default)
+  YardOptions:
+    - --private
+    - --protected
+
+  # Global file exclusion patterns
+  Exclude:
+    - '\.git'
+    - 'vendor/**/*'
+    - 'node_modules/**/*'
+    - 'spec/**/*'
+    - 'test/**/*'
+    - 'handler-examples/**/*'
+    - 'example/**/*'
+
+  # Exit code behavior (error, warning, convention, never)
+  FailOnSeverity: warning
+
+  # Minimum documentation coverage percentage (0-100)
+  # Fails if coverage is below this threshold
+  # MinCoverage: 80.0
+
+  # Diff mode settings
+  DiffMode:
+    # Default base ref for --diff (auto-detects main/master if not specified)
+    DefaultBaseRef: ~
+
+# Documentation validators
+Documentation/UndocumentedObjects:
+  Description: 'Checks for classes, modules, and methods without documentation.'
+  Enabled: true
+  Severity: warning
+  ExcludedMethods:
+    - 'initialize/0'  # Exclude parameter-less initialize
+    - '/^_/'          # Exclude private methods (by convention)
+
+Documentation/UndocumentedMethodArguments:
+  Description: 'Checks for method parameters without @param tags.'
+  Enabled: true
+  Severity: warning
+
+Documentation/UndocumentedBooleanMethods:
+  Description: 'Checks that question mark methods document their boolean return.'
+  Enabled: true
+  Severity: warning
+
+Documentation/UndocumentedOptions:
+  Description: 'Detects methods with options hash parameters but no @option tags.'
+  Enabled: true
+  Severity: warning
+
+Documentation/MarkdownSyntax:
+  Description: 'Detects common markdown syntax errors in documentation.'
+  Enabled: true
+  Severity: warning
+
+Documentation/EmptyCommentLine:
+  Description: 'Detects empty comment lines at the start or end of documentation blocks.'
+  Enabled: true
+  Severity: convention
+  EnabledPatterns:
+    Leading: true
+    Trailing: true
+
+Documentation/BlankLineBeforeDefinition:
+  Description: 'Detects blank lines between YARD documentation and method definition.'
+  Enabled: true
+  Severity: convention
+  OrphanedSeverity: convention
+  EnabledPatterns:
+    SingleBlankLine: true
+    OrphanedDocs: true
+
+# Tags validators
+Tags/Order:
+  Description: 'Enforces consistent ordering of YARD tags.'
+  Enabled: true
+  Severity: convention
+  EnforcedOrder:
+    - param
+    - option
+    - yield
+    - yieldparam
+    - yieldreturn
+    - return
+    - raise
+    - see
+    - example
+    - note
+    - todo
+
+Tags/InvalidTypes:
+  Description: 'Validates type definitions in @param, @return, @option tags.'
+  Enabled: true
+  Severity: warning
+  ValidatedTags:
+    - param
+    - option
+    - return
+
+Tags/TypeSyntax:
+  Description: 'Validates YARD type syntax using YARD parser.'
+  Enabled: true
+  Severity: warning
+  ValidatedTags:
+    - param
+    - option
+    - return
+    - yieldreturn
+
+Tags/MeaninglessTag:
+  Description: 'Detects @param/@option tags on classes, modules, or constants.'
+  Enabled: true
+  Severity: warning
+  CheckedTags:
+    - param
+    - option
+  InvalidObjectTypes:
+    - class
+    - module
+    - constant
+
+Tags/CollectionType:
+  Description: 'Validates Hash collection syntax consistency.'
+  Enabled: true
+  Severity: convention
+  EnforcedStyle: long  # 'long' for Hash{K => V} (YARD standard), 'short' for {K => V}
+  ValidatedTags:
+    - param
+    - option
+    - return
+    - yieldreturn
+
+Tags/TagTypePosition:
+  Description: 'Validates type annotation position in tags.'
+  Enabled: true
+  Severity: convention
+  CheckedTags:
+    - param
+    - option
+  # EnforcedStyle: 'type_after_name' (YARD standard: @param name [Type])
+  #                or 'type_first' (@param [Type] name)
+  EnforcedStyle: type_after_name
+
+Tags/ApiTags:
+  Description: 'Enforces @api tags on public objects.'
+  Enabled: false  # Opt-in validator
+  Severity: warning
+  AllowedApis:
+    - public
+    - private
+    - internal
+
+Tags/OptionTags:
+  Description: 'Requires @option tags for methods with options parameters.'
+  Enabled: true
+  Severity: warning
+
+Tags/ExampleSyntax:
+  Description: 'Validates Ruby syntax in @example tags.'
+  Enabled: true
+  Severity: warning
+
+Tags/RedundantParamDescription:
+  Description: 'Detects meaningless parameter descriptions that add no value.'
+  Enabled: true
+  Severity: convention
+  CheckedTags:
+    - param
+    - option
+  Articles:
+    - The
+    - the
+    - A
+    - a
+    - An
+    - an
+  MaxRedundantWords: 6
+  GenericTerms:
+    - object
+    - instance
+    - value
+    - data
+    - item
+    - element
+  EnabledPatterns:
+    ArticleParam: true
+    PossessiveParam: true
+    TypeRestatement: true
+    ParamToVerb: true
+    IdPattern: true
+    DirectionalDate: true
+    TypeGeneric: true
+
+Tags/InformalNotation:
+  Description: 'Detects informal tag notation patterns like "Note:" instead of @note.'
+  Enabled: true
+  Severity: warning
+  CaseSensitive: false
+  RequireStartOfLine: true
+  Patterns:
+    Note: '@note'
+    Todo: '@todo'
+    TODO: '@todo'
+    FIXME: '@todo'
+    See: '@see'
+    See also: '@see'
+    Warning: '@deprecated'
+    Deprecated: '@deprecated'
+    Author: '@author'
+    Version: '@version'
+    Since: '@since'
+    Returns: '@return'
+    Raises: '@raise'
+    Example: '@example'
+
+Tags/NonAsciiType:
+  Description: 'Detects non-ASCII characters in type annotations.'
+  Enabled: true
+  Severity: warning
+  ValidatedTags:
+    - param
+    - option
+    - return
+    - yieldreturn
+    - yieldparam
+
+Tags/TagGroupSeparator:
+  Description: 'Enforces blank line separators between different YARD tag groups.'
+  Enabled: false  # Opt-in validator
+  Severity: convention
+  TagGroups:
+    param: [param, option]
+    return: [return]
+    error: [raise, throws]
+    example: [example]
+    meta: [see, note, todo, deprecated, since, version, api]
+    yield: [yield, yieldparam, yieldreturn]
+  RequireAfterDescription: false
+
+Tags/ForbiddenTags:
+  Description: 'Detects forbidden tag and type combinations.'
+  Enabled: false  # Opt-in validator
+  Severity: convention
+  ForbiddenPatterns: []
+  # Example patterns:
+  # - Tag: return
+  #   Types:
+  #     - void
+  # - Tag: param
+  #   Types:
+  #     - Object
+  # - Tag: api  # Forbids @api tag entirely (no Types = any occurrence)
+
+# Warnings validators - catches YARD parser errors
+Warnings/UnknownTag:
+  Description: 'Detects unknown YARD tags.'
+  Enabled: true
+  Severity: error
+
+Warnings/UnknownDirective:
+  Description: 'Detects unknown YARD directives.'
+  Enabled: true
+  Severity: error
+
+Warnings/InvalidTagFormat:
+  Description: 'Detects malformed tag syntax.'
+  Enabled: true
+  Severity: error
+
+Warnings/InvalidDirectiveFormat:
+  Description: 'Detects malformed directive syntax.'
+  Enabled: true
+  Severity: error
+
+Warnings/DuplicatedParameterName:
+  Description: 'Detects duplicate @param tags.'
+  Enabled: true
+  Severity: error
+
+Warnings/UnknownParameterName:
+  Description: 'Detects @param tags for non-existent parameters.'
+  Enabled: true
+  Severity: error
+
+# Semantic validators
+Semantic/AbstractMethods:
+  Description: 'Ensures @abstract methods do not have real implementations.'
+  Enabled: true
+  Severity: warning

data/AGENTS.md

@@ -0,0 +1,58 @@
+You are working in a Ruby project that uses mutation testing.
+
+## Goal
+
+Achieve 100% mutation coverage. Verify with:
+
+```
+bundle exec mutant run
+```
+
+When iterating, prefer `--fail-fast` so you address one surviving
+mutant at a time:
+
+```
+bundle exec mutant run --fail-fast
+```
+
+## When you find an alive mutation
+
+Decide which bucket it falls into:
+
+- **A) The code does too much** for what the tests ask for. The
+  surviving mutation reveals behavior that no test requires. The
+  fix is to simplify the implementation.
+- **B) A test is missing.** The behavior is intentional but no test
+  observes it. The fix is to add a test.
+
+Decide between A) and B) before changing anything. If unsure, ask
+the user.
+
+## What you may change
+
+- `lib/age.rb` -- the implementation. Multiple designs are valid.
+- `spec/age_spec.rb` -- the tests. Some existing tests are bad and
+  may be rewritten or replaced.
+
+## Constraints
+
+- Line coverage must stay at 100%. Verify with:
+
+  ```
+  SIMPLECOV=1 bundle exec rspec
+  ```
+
+- You may not skip mutants by configuring mutant to ignore them.
+  No `expressions:` filters, no `coverage_criteria:` tweaks.
+- You may not use `send` or `__send__` to invoke private methods
+  in tests just to satisfy mutant.
+- You may not stub or mock the system under test (`Age`).
+
+## Done
+
+You are done when both of these are green:
+
+```
+SIMPLECOV=1 bundle exec rspec
+bundle exec mutant run
+```

data/Appraisals

@@ -11,3 +11,7 @@ end
 appraise "rails-8.0" do
   gem "rails", "~> 8.0"
 end
+
+appraise "rails-master" do
+  gem "rails", github: "rails/rails", branch: "main"
+end

data/CHANGELOG.md

@@ -5,8 +5,23 @@ This format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 
 ## Unreleased
 
+## 0.7.0
+## Added
+- Codebase is fully mutant tested now and test coverage increased
+
+## Changed
+- Codebase was simplified according to mutants
+
+## 0.6.0
+
+### Changed
+- ProcessingJob to discard job and report an error on DeserializationError
+- ProcessingJob to handle nil or wrong class argument gracefully
+- Ensure that ID is always generated for ReceivedWebhook model
+
 ## 0.5.0
 
+### Changed
 - 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

data/README.md

@@ -25,17 +25,19 @@ Mount webhukhs engine in your routes.
 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:
+Define a class for your first handler (let's call it `ExampleHandler`) and inherit it from `Webhukhs::BaseHandler`. We recommend `app/webhooks`, but any place known to autoloading will do. Add these to your `webhukhs.rb` config file:
 
 ```ruby
-config.active_handlers = {
-  "example" => "ExampleHandler"
-}
+Webhukhs.configure do |config|
+  config.active_handlers = {
+    "test-handler" => "WebhookTestHandler"
+  }
+end
 ```
 
-## Example handlers
-
-We provide a number of webhook handlers which demonstrate certain features of Webhukhs. You will find them in `handler-examples`.
+## Examples
+- `example` folder contains a demo app with engine fully configured.
+- We provide a number of webhook handlers which demonstrate certain features of Webhukhs. You will find them in `handler-examples`. 
 
 ## Requirements
 

data/config/mutant.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+project_root = File.expand_path("..", __dir__)
+template_database = File.expand_path("test/development.sqlite3", project_root)
+worker_database_dir = File.expand_path("tmp/mutant", project_root)
+
+disconnect_database = lambda do
+  next unless defined?(ActiveRecord::Base)
+  next unless ActiveRecord::Base.connected?
+
+  ActiveRecord::Base.connection_pool.disconnect!
+end
+
+isolate_database = lambda do |index:|
+  disconnect_database.call
+  FileUtils.mkdir_p(worker_database_dir)
+
+  database = File.join(worker_database_dir, "worker-#{index}-#{Process.pid}.sqlite3")
+  FileUtils.cp(template_database, database)
+
+  ENV["DATABASE_URL"] = "sqlite3:#{database}"
+  ActiveRecord::Base.establish_connection(adapter: "sqlite3", database: database)
+end
+
+hooks.register(:setup_integration_post) do
+  disconnect_database.call
+end
+
+hooks.register(:test_worker_process_start) do |index:|
+  isolate_database.call(index: index)
+end
+
+hooks.register(:mutation_worker_process_start) do |index:|
+  isolate_database.call(index: index)
+end

data/config/mutant.yml

@@ -0,0 +1,25 @@
+usage: opensource
+
+integration:
+  name: minitest
+
+includes:
+  - lib
+  - test
+
+environment_variables:
+  RAILS_ENV: test
+
+requires:
+  - ./test/test_app.rb
+
+matcher:
+  subjects:
+    - Webhukhs*
+
+coverage_criteria:
+  timeout: true
+  process_abort: true
+
+hooks:
+- ./config/mutant.rb

data/gemfiles/rails_master.gemfile

@@ -0,0 +1,10 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "sqlite3"
+gem "sprockets-rails"
+gem "appraisal"
+gem "rails", github: "rails/rails", branch: "main"
+
+gemspec path: "../"

data/lib/webhukhs/base_handler.rb

@@ -2,18 +2,20 @@
 
 require_relative "jobs/processing_job"
 
+# Namespace for webhook ingestion and processing classes.
 module Webhukhs
+  # Base class for webhook handlers.
   class BaseHandler
     # `handle` accepts the ActionDispatch HTTP request and saves the webhook for later processing. It then
     # enqueues an ActiveJob which will perform the processing using `process`.
     #
-    # @param action_dispatch_request[ActionDispatch::Request] the request from the controller
+    # @param action_dispatch_request [ActionDispatch::Request] request from the controller
     # @return [void]
     def handle(action_dispatch_request)
-      handler_module_name = is_a?(Webhukhs::BaseHandler) ? self.class.name : to_s
+      handler_module_name = self.class.name
       handler_event_id = extract_event_id_from_request(action_dispatch_request)
 
-      webhook = Webhukhs::ReceivedWebhook.new(request: action_dispatch_request, handler_event_id: handler_event_id, handler_module_name: handler_module_name)
+      webhook = ReceivedWebhook.new(request: action_dispatch_request, handler_event_id: handler_event_id, handler_module_name: handler_module_name)
       webhook.save!
 
       enqueue(webhook)
@@ -42,7 +44,7 @@ module Webhukhs
     # body of the webhook request, but also the full (as-full-as-possible) clone of the original ActionDispatch::Request
     # that you can use.
     #
-    # @param received_webhook[Webhukhs::ReceivedWebhook]
+    # @param received_webhook [Webhukhs::ReceivedWebhook] persisted webhook to process
     # @return [void]
     def process(received_webhook)
     end
@@ -60,9 +62,9 @@ module Webhukhs
     # If this method returns `false`, the webhook will be marked as `failed_validation` in the database. If this
     # method returns `true`, the `process` method of the handler is going to be called.
     #
-    # @see Webhukhs::ReceivedWebhook#request
-    # @param action_dispatch_request[ActionDispatch::Request] the reconstructed request from the controller
+    # @param action_dispatch_request [ActionDispatch::Request] reconstructed request from the stored webhook
     # @return [Boolean]
+    # @see Webhukhs::ReceivedWebhook#request
     def valid?(action_dispatch_request)
       true
     end
@@ -71,6 +73,7 @@ module Webhukhs
     # an event ID we use it for deduplication. A duplicate webhook is not going to be
     # stored in the database if it is already present there.
     #
+    # @param action_dispatch_request [ActionDispatch::Request] request used to derive a stable event identifier
     # @return [String]
     def extract_event_id_from_request(action_dispatch_request)
       SecureRandom.uuid

data/lib/webhukhs/controllers/receive_webhooks_controller.rb

@@ -1,13 +1,19 @@
 # frozen_string_literal: true
 
 module Webhukhs
+  # Receives incoming webhook HTTP requests and dispatches handlers.
   class ReceiveWebhooksController < ActionController::API
+    # Raised when a configured handler exists but is currently inactive.
     class HandlerInactive < StandardError
     end
 
+    # Raised when no handler is configured for the service id.
     class UnknownHandler < StandardError
     end
 
+    # Persists and schedules processing for an incoming webhook request.
+    #
+    # @return [void]
     def create
       Rails.error.set_context(**Webhukhs.configuration.error_context)
       handler = lookup_handler(service_id)
@@ -15,27 +21,40 @@ module Webhukhs
       handler.handle(request)
       render(json: {ok: true, error: nil})
     rescue UnknownHandler => e
-      Rails.error.report(e, handled: true, severity: :error)
+      Rails.error.report(e, severity: :error)
       render_error_with_status("No handler found for #{service_id.inspect}", status: :not_found)
     rescue HandlerInactive => e
-      Rails.error.report(e, handled: true, severity: :error)
+      Rails.error.report(e, severity: :error)
       render_error_with_status("Webhook handler #{service_id.inspect} is inactive", status: :service_unavailable)
     rescue => e
-      raise e unless handler
-      raise e if handler.expose_errors_to_sender?
-      Rails.error.report(e, handled: true, severity: :error)
+      raise unless handler
+      raise if handler.expose_errors_to_sender?
+      Rails.error.report(e, severity: :error)
       render_error_with_status("Internal error (#{e})")
     end
 
+    # Extracts webhook service identifier from route parameters.
+    #
+    # @return [String]
     def service_id
       params.require(:service_id)
     end
 
-    def render_error_with_status(message_str, status: :ok)
-      json = {ok: false, error: message_str}.to_json
+    # Renders standardized error response payload.
+    #
+    # @param message_str [String] human-readable error message
+    # @param status [Symbol] HTTP response status
+    # @return [void]
+    def render_error_with_status(message_str, status: nil)
+      json = {ok: false, error: message_str}
       render(json: json, status: status)
     end
 
+    # Resolves a handler class from configuration for a service id.
+    #
+    # @param service_id_str [String] service identifier from request path
+    # @return [Webhukhs::BaseHandler]
+    # @raise [UnknownHandler] when no active handler is configured for service id
     def lookup_handler(service_id_str)
       active_handlers = Webhukhs.configuration.active_handlers.with_indifferent_access
       # The config can specify a mapping of:

data/lib/webhukhs/engine.rb

@@ -6,6 +6,7 @@ require_relative "models/received_webhook"
 require_relative "base_handler"
 
 module Webhukhs
+  # Rails engine wiring routes, autoloading and generators for Webhukhs.
   class Engine < ::Rails::Engine
     isolate_namespace Webhukhs
 

data/lib/webhukhs/install_generator.rb

@@ -4,26 +4,33 @@ require "rails/generators"
 require "rails/generators/active_record"
 
 module Webhukhs
-  #
   # Rails generator used for setting up Webhukhs in a Rails application.
   # Run it with +bin/rails g webhukhs:install+ in your console.
-  #
   class InstallGenerator < Rails::Generators::Base
     include ActiveRecord::Generators::Migration
 
     source_root File.expand_path("../templates", __FILE__)
 
+    # Creates migration files required by Webhukhs tables.
+    #
+    # @return [void]
     def create_migration_file
       migration_template "create_webhukhs_tables.rb.erb", File.join(db_migrate_path, "create_webhukhs_tables.rb")
       migration_template "add_headers_to_webhukhs_webhooks.rb.erb", File.join(db_migrate_path, "add_headers_to_webhukhs_webhooks.rb")
     end
 
+    # Copies initializer file into host application.
+    #
+    # @return [void]
     def copy_files
       template "webhukhs.rb", File.join("config", "initializers", "webhukhs.rb")
     end
 
     private
 
+    # Declares ActiveRecord migration version.
+    #
+    # @return [String]
     def migration_version
       "[#{ActiveRecord::VERSION::STRING.to_f}]"
     end