webhukhs 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ac61cd0cbe0da35c7a6ad5f2be48cfff0dae74f712ce215eee4e3577fb3ce864
-  data.tar.gz: a27c3a7d108b70ddf72a073fba8333641e14530d9afea09e720c54b2ffd41867
+  metadata.gz: cae5927b7426085a8e140f6bdb4565423d43d1b72c65b65c9602b72bd81a1338
+  data.tar.gz: e77b5321fbd8b814b3d6265da104ec9b4e77ffc36a2d0b0c62e67ae1c1f3ff05
 SHA512:
-  metadata.gz: b09a61434f3b2b92edd9d5774363f29556f790963bd31e6e93684284cd03395685f1d61f5cb2477bf268168d31ce1cb6ab95da5b6c234e28d98a010fa14cebb9
-  data.tar.gz: ebb82e8c71c7e449a76bbf87e0db2c3c8350ae7ad85f2ba13708af3cef6554805d1e759310c46da9f78e08db49441e991740d9eb301155eee5b9a33c12768e5d
+  metadata.gz: 40519e7b2ca3b8c8e4bbf924f78d86269f6f4b68b1a72f3a7f963ec87fde656f49db69c6268de76f19b22ec762e3e14078c9839f44e080b41bc1e99131ecb449
+  data.tar.gz: 2a8e469254e9f76b46068a9b06001157f570f33a6cab931c2ee23cada3c13eadbff765c368cba58e6a62a1d657db8d142a2f89d2b8fe94b4034eb76f45cb4e6c

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,296 @@
+# 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'
+    - 'lib/webhukhs/engine.rb'
+    - '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,56 @@
+You are working in a Ruby project that uses mutation testing, but also tracks line and branch coverage.
+
+## Goal
+
+Achieve 100% line, branch and mutation coverage. Verify with:
+
+```
+SIMPLECOV=1 bundle exec rspec
+```
+
+```
+bundle exec mutant run
+```
+
+When iterating mutant coverage, prefer `--fail-fast` so you address one surviving
+mutant at a time:
+
+```
+bundle exec mutant run --fail-fast
+```
+
+## When you find coverage issue
+
+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
+
+- 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 coverage requirement.
+- 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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-appraise "rails-7.1" do
-  gem "rails", "~> 7.1.0"
+appraise "rails-7.2" do
+  gem "rails", "~> 7.2.0"
 end
 
 appraise "rails-8.1" do
@@ -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,6 +5,26 @@ This format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 
 ## Unreleased
 
+## 0.8.0
+## Added
+- An optional, read-only admin engine (`require "webhukhs/admin"`, mount `Webhukhs::Admin::Engine`) to list,
+  sort, filter and inspect received webhooks
+- `bin/dev`, which runs the `example` app - now with the admin mounted, more handlers and seed data
+
+## Fixed
+- Form-encoded webhooks were stored with an empty body: Rails had already read the body stream to parse
+  the params by the time Webhukhs got to it
+
+## Changed
+- Rails 7.2 or newer is now required (and with it Ruby 3.1), and the test matrix runs Rails 7.2 instead of 7.1
+
+## 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

data/README.md

@@ -19,30 +19,116 @@ Generate migrations and initializer file.
 
 `bin/rails g webhukhs:install`
 
-Mount webhukhs engine in your routes.
+Mount webhukhs engine in `config/routes.rb` file (simple approach, with only one dynamic route showing up in `rails 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:
+Advanced mounting approach (all webhooks paths will be shown in `rails routes`)
 
 ```ruby
-config.active_handlers = {
-  "example" => "ExampleHandler"
-}
+Webhukhs.configuration.active_handlers.each_key do |service_id|
+  post "/webhooks/#{service_id}",
+    to: "webhukhs/receive_webhooks#create",
+    defaults: { service_id: service_id },
+    as: :"#{service_id.tr('-', '_')}_webhook"
+end
 ```
 
-## Example handlers
+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.
 
-We provide a number of webhook handlers which demonstrate certain features of Webhukhs. You will find them in `handler-examples`.
+```ruby
+# app/webhooks/example_handler.rb
+class ExampleHandler < Webhukhs::BaseHandler
+  # Called asynchronously to process a stored webhook.
+  def process(received_webhook)
+    payload = JSON.parse(received_webhook.body, symbolize_names: true)
+    # handle payload...
+  end
+
+  # Optional: verify the request signature before processing.
+  # Return false to mark the webhook as failed_validation.
+  def valid?(action_dispatch_request)
+    action_dispatch_request.headers["X-Secret-Token"] == ENV["EXAMPLE_WEBHOOK_SECRET"]
+  end
+
+  # Optional: use a sender-supplied ID for deduplication.
+  def extract_event_id_from_request(action_dispatch_request)
+    action_dispatch_request.headers["X-Event-Id"] || SecureRandom.uuid
+  end
+end
+```
 
-## Requirements
+Add the handler to your `webhukhs.rb` config file:
+
+```ruby
+Webhukhs.configure do |config|
+  config.active_handlers = {
+    "example" => "ExampleHandler"
+  }
+end
+```
+
+Now you will be able to accept webhooks on `/webhooks/example` path.
+
+## Admin
+
+Webhukhs comes with a read-only admin for looking at the webhooks you have received: a sortable,
+filterable list, and a page per webhook with its body (pretty-printed when it is JSON) and the
+request headers it arrived with. It is not loaded by default - require it in your Gemfile (it has to be
+loaded before the app boots, so `config/routes.rb` is too late):
+
+```ruby
+gem "webhukhs", require: ["webhukhs", "webhukhs/admin"]
+```
+
+and mount it:
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  mount Webhukhs::Admin::Engine, at: "/admin/webhooks"
+end
+```
+
+The admin does no authentication of its own, and webhook bodies tend to carry personal data and
+secrets - so mount it behind whatever guards the rest of your admin. For example, with Devise:
+
+```ruby
+authenticate :user, ->(user) { user.admin? } do
+  mount Webhukhs::Admin::Engine, at: "/admin/webhooks"
+end
+```
+
+or with HTTP basic auth:
 
-This project depends on two dependencies:
+```ruby
+webhukhs_admin = Rack::Builder.new do
+  use Rack::Auth::Basic do |username, password|
+    ActiveSupport::SecurityUtils.secure_compare(username, ENV.fetch("ADMIN_USER")) &
+      ActiveSupport::SecurityUtils.secure_compare(password, ENV.fetch("ADMIN_PASSWORD"))
+  end
+  run Webhukhs::Admin::Engine
+end
+mount webhukhs_admin, at: "/admin/webhooks"
+```
+
+The admin brings its own CSS and JS, served by [Assiette](https://github.com/julik/assiette) from
+inside the engine - it does not touch your asset pipeline (Propshaft, Sprockets or anything else) and needs
+no build step.
+
+To try it out, run `bin/dev` from a checkout of this repository. It starts the app in `example`
+with some webhooks seeded, and the admin at http://localhost:3000/admin/webhukhs.
 
-- Ruby >= 3.0
-- Rails >= 7.0
+## More Examples
+- `example` folder contains a demo app with the engine and the admin fully configured - run it with `bin/dev`.
+- We provide a number of webhook handlers which demonstrate certain features of Webhukhs. You will find them in `handler-examples`.
+
+## Requirements
+
+- Ruby >= 3.1
+- Rails >= 7.2
 
 ## Error reporter
 
@@ -62,6 +148,10 @@ After checking out the repo, run `bin/setup` to install dependencies. Then, run
 
 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).
 
+The admin also has a click-through test in a real (headless) Chrome, which `rake test` leaves out.
+Run it with `bundle exec rake test:browser` - it needs Chrome or Chromium installed, and finds it
+by itself or through `BROWSER_PATH`.
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/skatkov/webhukhs.

data/Rakefile

@@ -23,4 +23,11 @@ Rake::TestTask.new(:test) do |t|
   end
 end
 
+# Needs Chrome, so it stays out of the default task
+Rake::TestTask.new("test:browser") do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/browser/**/*.rb"]
+end
+
 task default: [:test, :standard]

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/example/Gemfile

@@ -3,23 +3,22 @@
 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"
+gem "rails", ">= 7.2"
 
 # 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"
+gem "sqlite3", ">= 2.1"
 
 # Use the Puma web server [https://github.com/puma/puma]
-gem "puma", "~> 5.0"
+gem "puma", ">= 6.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: "../"
+# The admin is optional, and has to be required before the app boots
+gem "webhukhs", path: "../", require: ["webhukhs", "webhukhs/admin"]
 
 group :development, :test do
   # See https://guides.rubyonrails.org/debugging_rails_applications.html#debugging-with-the-debug-gem