webhukhs 0.7.0 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 83faf212a808c37ee8d293dc4e1d74d82d8ce0a7fb653d3850ee01ff9da7000b
-  data.tar.gz: 4d599377df025e4bd52c885efd5067127e50876eef1be8a9ee3117960d8bcf14
+  metadata.gz: 99b94333e5ec2959d8096f909a5370fccc5b68b9388e0a7028584a5cb334d660
+  data.tar.gz: 85c0dfd6138967c9c9f0fca36666ed07f7a9b714a608c34b13ed725d73dff67f
 SHA512:
-  metadata.gz: a0834f112be61de4bf50a6a99d8eee1ebd439e11c2a4ab26fe2e178d4ba70baeee4c62a06ea13fac44f2797bf5d7db40689249f7252cc3e5038d76f4997fdac2
-  data.tar.gz: 4070b8ad54761f7a888659c52a5284b660f86e729f645a8b1cc2658193b408b1852a4c6551147bd4ffe07f2c55f37dfb7b5aa8401388af44a2f762f1af973ccc
+  metadata.gz: 1ee87b2fb85e85a69493977d30cc21bbba0831d5b69973d560d4229260fdd7357a1a343c7da3634b503817827632e7f6ab8c1f5b92cd081030f11c68a8086053
+  data.tar.gz: e2820a7337b24bf51cc85e400889969f4744102c3ddc3948df9ae051d2baa96af6a8ae6ffad329cac90952f9d32362232ee2cd2a812dd7059fb04b9fabcb5ed1

data/.yard-lint.yml

@@ -11,6 +11,7 @@ AllValidators:
   # Global file exclusion patterns
   Exclude:
     - '\.git'
+    - 'lib/webhukhs/engine.rb'
     - 'vendor/**/*'
     - 'node_modules/**/*'
     - 'spec/**/*'

data/AGENTS.md

@@ -1,21 +1,25 @@
-You are working in a Ruby project that uses mutation testing.
+You are working in a Ruby project that uses mutation testing, but also tracks line and branch coverage.
 
 ## Goal
 
-Achieve 100% mutation coverage. Verify with:
+Achieve 100% line, branch and mutation coverage. Verify with:
+
+```
+SIMPLECOV=1 bundle exec rspec
+```
 
 ```
 bundle exec mutant run
 ```
 
-When iterating, prefer `--fail-fast` so you address one surviving
+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 an alive mutation
+## When you find coverage issue
 
 Decide which bucket it falls into:
 
@@ -28,24 +32,12 @@ Decide which bucket it falls into:
 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.
+  in tests just to satisfy coverage requirement.
 - You may not stub or mock the system under test (`Age`).
 
 ## Done

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

data/CHANGELOG.md

@@ -5,6 +5,24 @@ This format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 
 ## Unreleased
 
+## 0.8.1
+
+### Fixed
+- Sort the admin listing by ID by default to avoid a full-table sort.
+
+## 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

data/README.md

@@ -19,32 +19,124 @@ 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`. We recommend `app/webhooks`, but any place known to autoloading will do. Add these to your `webhukhs.rb` config file:
+Advanced mounting approach (all webhooks paths will be shown in `rails routes`)
+
+```ruby
+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
+```
+
+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.
+
+```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
+```
+
+Add the handler to your `webhukhs.rb` config file:
 
 ```ruby
 Webhukhs.configure do |config|
   config.active_handlers = {
-    "test-handler" => "WebhookTestHandler"
+    "example" => "ExampleHandler"
   }
 end
 ```
 
-## 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`. 
+Now you will be able to accept webhooks on `/webhooks/example` path.
 
-## Requirements
+## 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"]
+```
 
-This project depends on two dependencies:
+and mount it:
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  mount Webhukhs::Admin::Engine, at: "/admin/webhooks"
+end
+```
 
-- Ruby >= 3.0
-- Rails >= 7.0
+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:
+
+```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.
+
+The list defaults to descending ID order using the existing primary-key index; no extra migration is
+needed. Click **Received** to sort by timestamp instead.
+
+**We strongly recommend against UUIDv4 primary keys.** Use UUIDv7 or auto-incrementing integer IDs
+instead. UUIDv4 IDs are random, so sorting by ID does not reflect creation time, and inserts have
+poorer index locality. Webhukhs generates UUIDv7 when Ruby supports it, but falls back to UUIDv4
+otherwise; use a Ruby with UUIDv7 support if you need UUID primary keys.
+
+## 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
 
@@ -64,6 +156,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/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