duel-rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6bcc25c75b990e312e5fb3a458f5e3eace8b5dbbe02fcb8c50f0ca0df01d8f54
+  data.tar.gz: a6b29676404b6e35d14321d05f428d902d230d169f084abd65afd7104081fed1
+SHA512:
+  metadata.gz: 85ed8cb50f379354f0ba9a5769688fbcc1608bb4ee8dfff8e7586e2f736ed4db193bb99d82c7d76a37b6177175cb010364e60e0e83e6a6aec4fc11539ec30767
+  data.tar.gz: a514a4ddd962ac4b5c5711ec829ccb14a95d9e46cd1be6fc4a289d0bae2518995e49216f57c15e0e6d321832951f611c49e5db4563a5af580475f573f1fae682

data/CHANGELOG.md

@@ -0,0 +1,99 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/2.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-24
+
+The first release. duel-rails is a Duel plugin for Rails apps, open
+source under the MIT license. It needs Duel 0.1, duel-activerecord 0.1,
+Rails 7.2 or later, and Ruby 3.4 or later.
+
+### Added
+
+- `c.use :rails`: each version of the app boots in the
+  `benchmark` environment, from its own tree, and Duel compares a change
+  to `app/`, `config/`, `db/`, `lib/`, `Gemfile`, `Gemfile.lock`, or
+  `.ruby-version`.
+- Each version's workers run its own bundle: its `Gemfile.lock`,
+  installed once for the run, before its workers start (Duel's
+  `c.prepare(:version)`), on the version's Ruby, and kept installed for
+  each lockfile and Ruby. Duel puts its own gems and its plugins' ahead
+  of the bundle.
+- Each worker's own database (`database:`): a SQLite file, or a
+  PostgreSQL or MySQL server from duel-postgresql or duel-mysql. Each
+  worker loads its version's schema into it, then the fixtures
+  (`fixtures:`) and seeds (`seeds:`) asked for, with Ruby's random
+  numbers, and Faker's, seeded first (`seed:`). duel-rails uses
+  duel-activerecord, and the database server's plugin, with `c.use`, so
+  an app that uses one of them itself first, with options of its own,
+  keeps them.
+- `duel_request`: a benchmark of a request, sent through the app's whole
+  Rack stack without a server, with `params:`, `json:`, and `headers:`,
+  and a block to change its Rack environment. It fails on a status
+  other than the one expected (`status:`, `200..399` by default). It
+  takes Duel's hooks (`setup:`, `before_sample:`, and the rest), as
+  `duel` does, and gets its file's hooks, as a benchmark that the file
+  defines with `duel` does.
+- `Duel::Rails::ROLLBACK`, an `around_iteration` hook that rolls back
+  each iteration: for one benchmark
+  (`around_iteration: Duel::Rails::ROLLBACK`), a file, or every
+  benchmark (`c.around_iteration(&Duel::Rails::ROLLBACK)`). What a
+  request writes is rolled back with it, so pinning the connections and
+  rolling back aren't measured, and the rollback transaction doesn't
+  count in `active_record_transactions`. `rollback: false` sends the
+  request without it.
+- With a server's database (`database: :postgresql`, `:mysql2`, or
+  `:trilogy`), a request benchmark reads the server's statistics only
+  as each sample starts and stops, not around every request, because
+  the server's plugin says its metrics are costly to read. What pinning
+  and rolling back add is learned in each worker and subtracted.
+- Jobs that a benchmark enqueues are performed in an `after_iterations`
+  hook, and measured with it: after each request, before it's rolled
+  back, or after each sample's iterations otherwise. duel-rails's own
+  queue is Active Job's adapter while benchmarking, on Rails 7.2, 8.0,
+  and 8.1. `jobs: false` leaves jobs out.
+- `reset: true` empties every table, and loads the fixtures and seeds
+  again, before every sample (Duel's `c.before_sample`), for benchmarks
+  that write without rolling back. `Duel::Rails.reset_data` does the
+  same from a file's `before_sample` block.
+- The `rails_views`, `rails_cache_reads`, `rails_cache_misses`, and
+  `rails_cache_writes` metrics, from Rails's notifications, subscribed
+  to as each worker opens them and unsubscribed from as it closes them.
+  Where the views regressed, the views each version rendered most.
+  Active Record's metrics too, from duel-activerecord (`active_record:`,
+  `query_time:`).
+- `rails generate duel:install`: `.duel.rb`, the `benchmark`
+  environment, benchmarks of the app's requests (one for each action,
+  however many paths reach it), `duel/boot_duel.rb`, a benchmark of the
+  app's boot (`duel_process "boot: the app", "bin/rails", "runner",
+  "1"`, whose processes run in the version's `RAILS_ENV`), a GitHub
+  Actions workflow, and, in the `Gemfile`'s `development` group,
+  `gem "stackprof", platforms: :mri` (for profiles of regressions,
+  unless the `Gemfile` has StackProf) and the database server's plugin.
+  The `benchmark` environment sets Active Job's queue adapter only in an
+  app with Active Job.
+- The generated workflow writes Duel's report in Markdown
+  (`duel --markdown`) and comments on each pull request with it,
+  updating one comment on every push. Duel adds the report to the job's
+  summary too. The workflow asks for the `pull-requests: write`
+  permission, and an app in a subdirectory of its repository gets a
+  comment of its own.
+- For an app with a `.ruby-version`, the generated `.duel.rb` sets
+  `c.ruby = :version_file`, so each version runs on its own Ruby, and the
+  generated workflow also installs the main branch's Ruby for a pull
+  request.
+- An app in a subdirectory of its repository (a monorepo's): the
+  generator writes its workflow at the repository's root, named for the
+  app's directory, and run there (`working-directory`).
+- `rake duel`, in the app.
+- Mutation tested: mutant kills every change to the plugin's code, in
+  CI.
+- RBS signatures in sig/, checked with Steep.
+
+[Unreleased]: https://github.com/sferik/duel-ruby/compare/duel-rails-v0.1.0...HEAD
+[0.1.0]: https://github.com/sferik/duel-ruby/releases/tag/duel-rails-v0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Erik Berlin
+
+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,456 @@
+# duel-rails
+
+[![Duel](https://raw.githubusercontent.com/sferik/duel-ruby/main/assets/badge.svg)](https://github.com/sferik/duel-ruby)
+[![duel-rails](https://github.com/sferik/duel-ruby/actions/workflows/plugin-rails.yml/badge.svg)](https://github.com/sferik/duel-ruby/actions/workflows/plugin-rails.yml)
+[![Gem Version](https://badge.fury.io/rb/duel-rails.svg)](https://rubygems.org/gems/duel-rails)
+
+A [Duel](https://github.com/sferik/duel-ruby) plugin for Rails apps. It
+fails a pull request that makes your app's requests slower, or makes
+them query the database, render views, or allocate more.
+
+```sh
+$ bin/rake duel
+Comparing 3 benchmarks, 2 at a time: baseline /src/.8e2f1c4 against candidate /src/my_app (slower: a 99.0% interval above 1.02)
+  posts: index        2.7s n=4   cpu 1.004 [0.991, 1.018] same  active_record_queries 1→2  rails_views 4→7  allocations 988→1530
+...
+REGRESSION posts: index: worse active_record_queries, rails_views, allocations in every measurement
+  active_record_queries: 1 query → 2 queries an iteration
+  active_record_queries (candidate): an iteration: 1× SELECT "posts".* FROM "posts"; 1× SELECT COUNT(*) FROM "posts"
+  rails_views (candidate): an iteration: 6× posts/_post.html.erb; 1× posts/index.html.erb; 1× layouts/application.html.erb
+```
+
+duel-rails sets Duel up so that each version of your app runs the way
+production does, with everything of its own:
+
+- **Booted like production.** Each version boots in a `benchmark`
+  environment that's based on your production environment, with eager
+  loading and YJIT, but without SSL, logging, or other databases.
+- **Its own bundle and Ruby.** Each version runs its own `Gemfile.lock`,
+  on the Ruby that its own `.ruby-version` names, so a pull request that
+  upgrades a gem, Rails, or Ruby itself is compared too.
+- **Its own database.** Each worker gets a database of its own, with its
+  version's schema and your fixtures or seeds loaded into it.
+- **Requests, through the whole stack.** A benchmark sends a request
+  through your app's middleware, routing, controller, and views, without
+  a server, performs the jobs that the request enqueued, and rolls back
+  what it wrote. Only the request and its jobs are measured.
+- **More than time.** Besides CPU time and allocations, each request is
+  judged on its queries (with
+  [duel-activerecord](https://github.com/sferik/duel-ruby/tree/main/plugins/activerecord)), the
+  views it rendered, and its cache reads, misses, and writes.
+- **Boot time.** A benchmark of your app's boot guards how long a fresh
+  process takes to start.
+
+## Install duel-rails
+
+1. Add duel-rails to the `development` group of your `Gemfile`:
+
+   ```ruby
+   # Gemfile
+   group :development do
+     gem "duel-rails"
+   end
+   ```
+
+2. Run `bundle install`.
+
+3. Run the generator:
+
+   ```sh
+   bin/rails generate duel:install
+   ```
+
+   The generator makes the following files:
+
+   | File | What it is |
+   |---|---|
+   | `.duel.rb` | Duel's configuration: `c.use :rails`, with your database, and your fixtures if you have any. If your app has a `.ruby-version`, also `c.ruby = :version_file`. See [Its own Ruby](#its-own-ruby). |
+   | `config/environments/benchmark.rb` | The environment that each version boots in, based on production. |
+   | `duel/requests_duel.rb` | A benchmark of each of your app's first 10 routes that a GET reaches without parameters. |
+   | `duel/boot_duel.rb` | A benchmark of your app's boot. See [Benchmark your app's boot](#benchmark-your-apps-boot). |
+   | `.github/workflows/perf.yml` | A GitHub Actions workflow that runs Duel on pull requests, on pushes to `main`, and nightly against your last release, and comments on each pull request with Duel's report, updating one comment on every push. See [Report on a pull request](https://github.com/sferik/duel-ruby#report-on-a-pull-request). For an app in a subdirectory of its repository, the workflow is at the repository's root. See [An app in a monorepo](#an-app-in-a-monorepo). |
+
+   The generator also adds `gem "stackprof", platforms: :mri` to your
+   `Gemfile`'s `development` group, unless it has StackProf already, so
+   Duel can show where a regression spent its extra time. StackProf runs
+   on CRuby only, so the gem isn't installed on JRuby or TruffleRuby. If
+   your database is PostgreSQL or MySQL, the generator adds
+   [duel-postgresql](https://github.com/sferik/duel-ruby/tree/main/plugins/postgresql) or
+   [duel-mysql](https://github.com/sferik/duel-ruby/tree/main/plugins/mysql) too.
+   Run `bundle install` again.
+
+4. Review the generated files, and commit them.
+
+5. Run the benchmarks against your main branch:
+
+   ```sh
+   bin/rake duel
+   ```
+
+   To compare your code with itself, which checks that the setup works,
+   run `bin/rake duel DUEL_FORCE=1`.
+
+The `rake duel` task comes with duel-rails. You can also run `bundle exec
+duel`, with any of [Duel's options](https://github.com/sferik/duel-ruby#run-duel).
+
+## Benchmark requests
+
+Benchmarks go in files named `*_duel.rb` in `duel/`. To benchmark a
+request, use `duel_request` with a name and the request's method and
+path:
+
+```ruby
+# duel/requests_duel.rb
+duel_request "posts: index", "GET /posts"
+duel_request "posts: page 2", "GET /posts?page=2"
+duel_request "posts: create", "POST /posts", params: {post: {title: "Hi"}}
+duel_request "api: search", "POST /api/search", json: {q: "duel"}, headers: {"Accept" => "application/json"}
+```
+
+Each iteration sends the request once, through the whole Rack stack,
+and then performs the jobs that the request enqueued. See
+[Measure the jobs that a request enqueues](#measure-the-jobs-that-a-request-enqueues).
+After each iteration, duel-rails rolls back what the request and its
+jobs wrote to the database, so every request finds the same data.
+
+duel-rails rolls back with an `around_iteration` hook,
+`Duel::Rails::ROLLBACK`, so the rollback isn't measured. Before each
+iteration, the hook pins each database connection that Active Record
+writes through, in a transaction, and after the iteration it rolls the
+transaction back, the way that Rails's transactional tests do. Duel
+measures only the iteration: the request, its jobs, and the
+transactions that they open, which become savepoints.
+
+To leave the rollback out of what it measures, Duel pauses every metric
+after each iteration, and resumes it before the next. A metric that
+reads a server, such as duel-postgresql's statistics, is costly to read,
+so Duel doesn't pause it: it reads the server only when a sample starts
+and stops, and subtracts what pinning and rolling back add, which it
+learns in each worker. Pausing the other metrics still takes a little
+time per iteration. To measure a request without the rollback, and
+without the pauses, pass `rollback: false`.
+
+`duel_request` takes the following options:
+
+| Option | Description |
+|---|---|
+| `params:` | Form parameters. For a GET, they go in the query string. |
+| `json:` | A body, sent as JSON with a `Content-Type` of `application/json`. Use either `params:` or `json:`, not both. |
+| `headers:` | Request headers, by name, for example `{"Accept" => "text/csv"}`. |
+| `status:` | The status that the response must have: an Integer, or a Range. The default is `200..399`. Any other status fails the benchmark, because it's measuring an error page. |
+| `rollback:` | `false` to keep what the request writes, and to run its iterations without pausing the metrics between them. The default is `true`. To start each sample with the same data anyway, see [Start every sample with the same data](#start-every-sample-with-the-same-data). |
+| `only:`, `peak_memory:` | Duel's options for what the benchmark is judged on. See [Choose what a benchmark is judged on](https://github.com/sferik/duel-ruby/blob/main/docs/benchmarks.md#choose-what-a-benchmark-is-judged-on). |
+| `setup:`, `teardown:`, `before_sample:`, `around_iteration:`, `after_iterations:` | The benchmark's own hooks, as `duel` takes them. See [Run code around a benchmark](https://github.com/sferik/duel-ruby/blob/main/docs/benchmarks.md#run-code-around-a-benchmark). An `around_iteration:` hook would replace the rollback, so it raises an `ArgumentError` unless you also pass `rollback: false`. To run a hook around the rollback, give it to the whole file instead. |
+
+To change the request before it's sent, pass a block. The block
+receives the request's Rack environment, and runs in the benchmark's
+context, so it can use what the file's `setup` hooks set. For example,
+to send a session cookie that a file's `setup` hook made, with a helper
+of your own in `duel/duel_helper.rb`:
+
+```ruby
+setup { @cookie = session_cookie_for(User.find_by!(admin: true)) }
+
+duel_request "admin: dashboard", "GET /admin" do |env|
+  env["HTTP_COOKIE"] = @cookie
+end
+```
+
+`duel_request` is a `duel`, so the hooks of its file and of `.duel.rb`
+apply to it, and you can mix it with plain benchmarks of your models and
+services:
+
+```ruby
+duel "invoice: totals for 100 lines" do
+  once { @invoice = Invoice.includes(:lines).first }
+  @invoice.recalculate_totals
+end
+```
+
+### Roll back any benchmark
+
+A plain `duel` that writes to the database, such as one that creates a
+record, can roll back each iteration the way that a request does. Give
+`Duel::Rails::ROLLBACK` as an `around_iteration` hook, at any level:
+
+```ruby
+# For one benchmark
+duel "posts: create", around_iteration: Duel::Rails::ROLLBACK do
+  Post.create!(title: "Hi")
+end
+
+# For every benchmark in a file, at its top
+around_iteration(&Duel::Rails::ROLLBACK)
+
+# For every benchmark, in .duel.rb
+Duel.configure do |c|
+  c.use :rails, fixtures: :all
+  c.around_iteration(&Duel::Rails::ROLLBACK)
+end
+```
+
+A `duel_request` already rolls back. Under a file's or `.duel.rb`'s
+hook, its own rollback runs inside the outer one, which costs a little
+more and changes nothing. A benchmark whose block takes the number of
+iterations (`|n|`) can't run inside an `around_iteration` hook, so
+don't give `.duel.rb` one if you have such benchmarks.
+
+### Measure the jobs that a request enqueues
+
+Some of a request's work runs later, in a job that it enqueues, such as
+an email that it sends with `deliver_later`. So that a regression in
+that work fails too, duel-rails performs the jobs that a benchmark
+enqueues, and Duel measures them with the benchmark:
+
+- In a request's benchmark, or any benchmark that's rolled back,
+  duel-rails performs the jobs after each iteration, before it rolls
+  back what the iteration wrote, so the jobs find its data.
+- In any other benchmark, duel-rails performs the jobs after the
+  iterations of each sample.
+
+duel-rails performs them in an `after_iterations` hook, which Duel
+measures with the iterations. For more information, see
+[Run code around a benchmark](https://github.com/sferik/duel-ruby/blob/main/docs/benchmarks.md#run-code-around-a-benchmark).
+
+duel-rails performs the jobs in order, along with any jobs that they
+enqueue, and a job that's scheduled for later too. It discards the jobs
+that were enqueued before a sample, such as by your seeds.
+
+While Duel benchmarks your app, duel-rails's own queue is Active Job's
+queue adapter, in place of the one that
+`config/environments/benchmark.rb` sets. A job class that sets its own
+`queue_adapter` keeps that adapter, so duel-rails doesn't perform its
+jobs.
+
+duel-rails performs jobs on Rails 7.2, 8.0, and 8.1 alike. In each,
+a job that's enqueued inside a transaction can wait for the transaction
+to commit, as Active Job decides: Rails 7.2 asks the adapter, and
+duel-rails's says to wait, as Active Job's own adapters do. Rails 8.0
+and later ask the job, with its `enqueue_after_transaction_commit`. The
+transaction that duel-rails rolls each request back in doesn't count:
+a job that waits is enqueued when the request's own transaction
+commits.
+
+To leave jobs out, and measure only what the request does itself, pass
+`jobs: false` to `c.use :rails`.
+
+### Start every sample with the same data
+
+A benchmark that writes to the database without rolling back, such as a
+`duel_request` with `rollback: false` or a plain `duel` that creates
+records, leaves its writes for the samples after it. To start every
+sample with the data that each worker loaded, pass `reset: true`:
+
+```ruby
+# .duel.rb
+Duel.configure do |c|
+  c.use :rails, fixtures: :all, reset: true
+end
+```
+
+Before every sample of every benchmark, duel-rails then empties every
+table, and loads your fixtures and seeds again. Duel doesn't measure
+it, but it makes each run slower.
+
+To reset only before the samples of one file's benchmarks, call
+`Duel::Rails.reset_data` in the file's `before_sample` block:
+
+```ruby
+# duel/imports_duel.rb
+before_sample { Duel::Rails.reset_data } # not measured
+
+duel_request "imports: create", "POST /imports", params: {import: {rows: 100}}, rollback: false
+```
+
+### Benchmark your app's boot
+
+The generator adds a benchmark of how long your app takes to boot:
+
+```ruby
+# duel/boot_duel.rb
+duel_process "boot: the app", "bin/rails", "runner", "1"
+```
+
+Each sample runs `bin/rails runner` in a fresh process, for each
+version, in turn. Duel judges it on its CPU time, including that of the
+processes that it starts, and on its peak memory. For more information,
+see Duel's [Benchmark a whole process](https://github.com/sferik/duel-ruby/blob/main/docs/benchmarks.md#benchmark-a-whole-process).
+
+Each sample boots your app once for each version, so this benchmark
+takes longer than a request's, from tens of seconds to a few minutes.
+
+Each version's process runs with that version's bundle, in the
+`benchmark` environment (`RAILS_ENV`). It doesn't get a database of its
+own, so it measures your app's boot alone. If your app queries the
+database as it boots, remove the benchmark.
+
+## Each version's own
+
+### The benchmark environment
+
+Each version boots in the `benchmark` environment, from
+`config/environments/benchmark.rb`. The generated file starts from your
+production environment, and turns off what needs a deployment:
+
+- SSL, host authorization, and forgery protection, because Duel sends
+  requests without a server in front.
+- Logging.
+- Other databases: the cache uses memory, and Active Job uses its test
+  adapter, so neither needs a database of its own.
+
+Change it as your app needs, for example to stub a service that your
+app calls over the network.
+
+### Its own bundle
+
+Each version runs its own `Gemfile` and `Gemfile.lock`. Before a
+version's workers start, duel-rails installs its `Gemfile.lock`, on the
+version's Ruby, once for each lockfile and Ruby, and keeps it installed
+for later runs. So a pull request that upgrades a gem is measured with
+the upgrade, and its baseline without it.
+
+Duel loads itself, and every Duel plugin that the runner loaded,
+duel-rails included, ahead of each version's bundle. That way, a
+baseline from before you added Duel can still run, and both versions
+are measured with the same Duel.
+
+### Its own Ruby
+
+If your app has a `.ruby-version`, the generated `.duel.rb` sets
+`c.ruby = :version_file`. Each version then runs on the Ruby that its
+own `.ruby-version` names, so a pull request that upgrades Ruby is
+measured on the new Ruby, and its baseline on the old one. duel-rails
+installs each version's bundle for its Ruby.
+
+Each Ruby must be installed where Duel finds it: with rbenv, chruby,
+mise, or asdf, or as the Ruby that runs Duel. For more information, see
+Duel's [Run each version on its own Ruby](https://github.com/sferik/duel-ruby/blob/main/docs/configuration.md#run-each-version-on-its-own-ruby).
+On GitHub Actions, the generated workflow installs your app's Ruby, and,
+for a pull request, also the main branch's, so a pull request that
+upgrades Ruby works there too.
+
+To run both versions on the Ruby that runs Duel, remove
+`c.ruby = :version_file`.
+
+### Its own database
+
+Each worker gets a database of its own, set in `DATABASE_URL`, which
+Rails prefers to `config/database.yml`. Choose the database with
+`database:`:
+
+| `database:` | Each worker's database | Plugin |
+|---|---|---|
+| `:sqlite` (default) | A SQLite file in the worker's directory | None |
+| `:postgresql` | A PostgreSQL server | [duel-postgresql](https://github.com/sferik/duel-ruby/tree/main/plugins/postgresql) |
+| `:mysql2` or `:trilogy` | A MySQL server, through that adapter | [duel-mysql](https://github.com/sferik/duel-ruby/tree/main/plugins/mysql) |
+| `nil` | None | None |
+
+A database server's plugin also judges each request on what the server
+did for it, by statement.
+
+Each worker loads its version's schema into its database, from
+`db/schema.rb` or `db/structure.sql`. So a pull request with a migration
+is measured with its new schema, and its baseline with the old one.
+
+### Its own data
+
+Each worker then loads the data that you ask for. Its random numbers are
+seeded first, and Faker's too if it's loaded, so both versions get the
+same data:
+
+```ruby
+# .duel.rb
+Duel.configure do |c|
+  c.use :rails, database: :postgresql, fixtures: :all, seeds: true
+end
+```
+
+Load data that every benchmark shares here. For data that one benchmark
+needs, use a `setup` hook in its file, or a `once` block in the
+benchmark.
+
+> [!IMPORTANT]
+> Duel loads the benchmark files before each worker's data, so don't
+> query your database at the top level of a benchmark file. Do it in a
+> `setup` hook or a `once` block.
+
+## What each request is judged on
+
+Besides Duel's own metrics (CPU time, instructions, and allocations),
+each request is judged on the following:
+
+| Metric | What it is | A regression |
+|---|---|---|
+| `active_record_queries` and the rest | Queries, cached queries, transactions, and records. See [duel-activerecord](https://github.com/sferik/duel-ruby/tree/main/plugins/activerecord). | Any increase |
+| `rails_views` | Templates, partials, and layouts rendered. Each of a collection's partials counts. | Any increase |
+| `rails_cache_reads` | Keys read from the cache | Any increase |
+| `rails_cache_misses` | Keys read that weren't in the cache | Any increase |
+| `rails_cache_writes` | Keys written to the cache | Any increase |
+
+A regression in views shows which views a sample rendered most, as in
+the example at the top of this page.
+
+The transaction that duel-rails rolls each request back in isn't
+measured, so it doesn't count in `active_record_transactions`, and the
+queries that a request's jobs make count as the request's.
+
+## Options
+
+`c.use :rails` takes the following options:
+
+| Option | Description |
+|---|---|
+| `database:` | Each worker's database. See [Its own database](#its-own-database). The default is `:sqlite`. |
+| `fixtures:` | Fixtures from `test/fixtures` to load into each worker's database, by name, or `:all`. The default is none. |
+| `seeds:` | `true` to run `db/seeds.rb` in each worker, after the fixtures. |
+| `seed:` | What random numbers are seeded with. The default is 42. |
+| `reset:` | `true` to empty every table, and load the fixtures and seeds again, before every sample. See [Start every sample with the same data](#start-every-sample-with-the-same-data). |
+| `jobs:` | `false` to leave out the jobs that benchmarks enqueue. See [Measure the jobs that a request enqueues](#measure-the-jobs-that-a-request-enqueues). |
+| `environment:` | The environment that each version boots in, and its processes run in. The default is `"benchmark"`. |
+| `bundle:` | `false` to run every version with the runner's bundle. |
+| `active_record:` | `false` to leave out Active Record's metrics, for an app without Active Record. |
+| `query_time:` | `true` to also judge how long queries took. See [duel-activerecord](https://github.com/sferik/duel-ruby/tree/main/plugins/activerecord). |
+
+Any other option goes to the database server's plugin, for example
+`args:` or `setup:` for duel-mysql.
+
+duel-rails uses duel-activerecord, and the database server's plugin,
+with `c.use`. To give one of them options of its own, use it yourself,
+before `c.use :rails`. duel-rails then uses the plugin that you
+configured:
+
+```ruby
+# .duel.rb
+Duel.configure do |c|
+  c.use :activerecord, ignore: ->(payload) { payload[:sql].include?("pg_catalog") }
+  c.use :rails, database: :postgresql, fixtures: :all
+end
+```
+
+duel-rails also tells Duel to compare a change to `app/`, `config/`,
+`db/`, `lib/`, `Gemfile`, `Gemfile.lock`, or `.ruby-version`.
+
+## An app in a monorepo
+
+Your app can be in a subdirectory of its repository, such as
+`apps/blog`. Run the generator and `bin/rake duel` in the app's
+directory, as usual. Duel checks out the whole repository for the
+baseline, and compares the same subdirectory of it. The paths that
+duel-rails watches are in the app's directory.
+
+The generator writes the workflow at the repository's root, because
+that's where GitHub Actions looks for it, and names it for the app's
+directory, such as `.github/workflows/perf-apps-blog.yml`, so that
+each app can have its own. The workflow runs Duel, and sets up Ruby
+and the bundle, in the app's directory (`working-directory`).
+
+## YJIT
+
+Rails 7.2 and later turn YJIT on as the app boots. When YJIT is on,
+Duel warms each benchmark up for two seconds before it measures it, so
+that YJIT has compiled your app's code first.
+
+## Requirements
+
+duel-rails needs Rails 7.2 or later, and Ruby 3.4 or later. It doesn't
+run on JRuby, whose Rails needs JDBC adapters.

data/lib/duel/rails/bundle.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "bundler"
+require "digest"
+
+module Duel
+  module Rails
+    # Each version runs its own bundle: its Gemfile and its Gemfile.lock,
+    # installed once for the run (Config#prepare(:version)) on the version's
+    # Ruby, and kept installed for later runs (Resource#cached), so a
+    # change that upgrades a gem (Rails itself, say) is compared too.
+    #
+    # (Duel puts its own gems, and its plugins', this one too, ahead of
+    # the version's bundle in each worker: a version from before the app
+    # added Duel still has them, and both versions are measured with the
+    # same.)
+    module Bundle
+      # Gives each version its own bundle (see .environment).
+      def self.configure(config) = config.prepare(:version) { |v| environment(v) }
+
+      # The environment for the bundle of the version (a Resource for it),
+      # installed first, on its Ruby: nothing for a version without a
+      # Gemfile.lock.
+      def self.environment(version)
+        gemfile = File.join(version.root, "Gemfile")
+        lockfile = "#{gemfile}.lock"
+        return {} unless File.exist?(lockfile)
+
+        version.cached(key(lockfile, version.ruby)) do
+          version.run(unbundled.merge(version.env, "BUNDLE_GEMFILE" => gemfile), "bundle", "install", log: "bundle",
+            chdir: version.root, unsetenv_others: true)
+        end
+        {"BUNDLE_GEMFILE" => gemfile, "BUNDLE_LOCKFILE" => lockfile}
+      end
+
+      # What a bundle installed is kept as: its lockfile's, for the Ruby
+      # (its path) it's installed for, which has gems of its own.
+      def self.key(lockfile, ruby) = "bundle-#{Digest::SHA256.hexdigest("#{File.read(lockfile)}\0#{ruby}")[0, 16]}"
+
+      # The runner's environment without Bundler's part (the bundle it
+      # runs in is the candidate's), for installing another.
+      def self.unbundled = Bundler.unbundled_env
+    end
+  end
+end