Bring back the transactional server

[rosston]

Summary

0.8.0 removed CYPRESS_RAILS_TRANSACTIONAL_SERVER and told apps to reset their own test data with database_cleaner. That was a mistake. The setup the README recommended doesn't reliably reset data under cypress-rails' multi-threaded Puma server, so data can leak from one test into the next.

This PR restores the transactional server, built this time on a stable Rails contract instead of copied Rails internals, and makes the reset endpoint finish its work before responding. For apps on Rails 7.1 or newer, the public API is back to exactly what 0.7.1 had.

This is stacked on #187, #188, and #190.

Why 0.8.0's reasoning was wrong

The commit that removed the transactional server gave three reasons:

It breaks on Rails 7.2+ (NoMethodError on ConnectionPool#lock_thread=) and
chasing further Rails internals changes isn't sustainable - cypress-rails has
no special knowledge of an app's database, and dedicated gems like
database_cleaner already do this well and stay current with Rails.

Each of those turned out to be wrong, or right about the problem but wrong about the fix.

"cypress-rails has no special knowledge of an app's database"

cypress-rails doesn't need to know anything about an app's schema or data, but it does own the thing that decides how the database gets used: the server. cypress-rails boots the app under Puma with multiple threads, and each thread can use its own database connection. Whether test data resets cleanly depends on how those connections share, or don't share, a transaction. That's a consequence of running the server, so it's cypress-rails' concern, not something each app can reasonably solve on its own.

"database_cleaner already does this well"

database_cleaner is built for tests that run in the same thread as the code they exercise. Its :transaction strategy opens a transaction on one database connection and rolls it back later. Under cypress-rails' server, a request handled by another Puma thread uses a different connection, outside that transaction. Its writes commit for real and survive the reset, and data written inside the transaction is invisible to it. On SQLite, the open transaction also makes other connections' writes fail with "database is locked".

The README's example made this worse in a way that's easy to miss. It set DatabaseCleaner.strategy = :transaction at the top of an initializer. If ActiveRecord hasn't loaded yet when that line runs, as in the example app, the assignment is silently ignored, and database_cleaner falls back to its default, which is also :transaction. So the example appeared to work as written, but anyone who changed it to a strategy that does work in this setup, like :truncation, could silently end up with :transaction anyway.

The strategies that do work, truncation and deletion, wipe all data on every reset, so every app has to rebuild its fixtures and seed data in the hook, with its own tradeoffs. Recommending database_cleaner handed a hard concurrency problem to every user, along with guidance that didn't work.

"chasing Rails internals isn't sustainable"

This part was true: the old implementation copied connection-pinning code from Rails, and Rails 7.2 changed it (lock_thread= became pin_connection!). But the fix was to stop copying internals, not to drop the feature.

Rails already has a stable contract for exactly this problem. ActiveRecord::TestFixtures wraps each test in a transaction shared across threads, and it's driven through its before_setup and after_teardown hooks. Minitest's ActiveSupport::TestCase calls those hooks, and rspec-rails has called them around every example since at least 3.5.0 (2016). They've been essentially unchanged from Rails 6.0 through Rails' main branch, and Rails picks the right pinning mechanism for each version behind them. Rails can't change that contract without breaking both test frameworks, so it's a far safer foundation than the code 0.7.1 copied.

Why it looked fine at first

After 0.8.0, CI on main stayed green, which made the change look safe. The reason was luck: Rails' connection pool hands out the most recently returned connection first, so as long as the example app's requests never overlapped, each one reused the connection holding database_cleaner's transaction.

Changing request timing was enough to break that. After the example app moved to shakapacker (#187), the Rails 7.1 jobs started failing intermittently with "database is locked". After it moved to Postgres (#188), the real symptom showed up: an edit from one test survived into the next. Locally, it failed 3 of 5 and 6 of 8 runs on Rails 7.1. Apps with more concurrent requests, such as XHR on page load, Turbo frames, or ActiveStorage images, are far more likely to hit this than the example app was.

What this PR does

• Restores CYPRESS_RAILS_TRANSACTIONAL_SERVER (on by default), CypressRails::Config#transactional_server, the after_transaction_start hook, and the after_state_reset hook name, all exactly as they were in 0.7.1.
• Rebuilds ManagesTransactions on ActiveRecord::TestFixtures' lifecycle hooks. A dedicated thread owns the transaction, because on Rails 7.1 a Puma thread's end-of-request cleanup would hand the shared connection back to the pool.
• Makes /cypress_rails_reset_state finish the reset before responding, and return a 500 with the error when a hook raises. It used to defer the reset to whichever request came next.
• Requires Rails 7.1 or newer, which is what CI covers.
• Updates the README, including when and how to turn the transactional server off, and the database_cleaner pitfalls above.
• Adds CI jobs that run the example app with the transactional server off, so that documented setup can't silently break.

Why the reset endpoint is synchronous now

Deferring the reset to the next request isn't what caused the flaky resets. Bringing back the shared transaction fixes that. But the deferred design had problems of its own:

• A failing hook cascaded. The failure landed on whatever request came next, and since the "reset needed" flag stayed set, every later request re-ran the failing hook. Now the cy.request that asked for the reset fails, with the exception message, and the next reset starts clean.
• Concurrent requests could race the reset. Every request checked an unsynchronized flag, and nothing made other requests wait while one of them performed the reset. Now the reset runs in its own request, one at a time, and Cypress waits for it before the test continues.
• Reset work ran inside unrelated app requests, affecting their logging, timing, and error reporting.

The deferred design existed so the old rollback could run on a request thread where the pinned connection lived. With a dedicated thread owning the transaction, that reason is gone.

Compatibility

Relative to 0.7.1, the only breaking change is the Rails 7.1 minimum. The reset endpoint's behavior change is compatible with the documented usage. Relative to 0.8.0, this reverses 0.8.0's breaking changes, which is breaking for apps that adopted it. For example, after_reset_requested is gone, so an initializer still calling it raises at boot. The full comparison is in docs/changes-in-0.9.0.md.

How this was verified

• Unit tests cover ManagesTransactions against a real SQLite database on ActiveRecord 7.1, 7.2, 8.0, and 8.1: other threads see the shared transaction, rollback undoes every thread's writes, and repeated resets stay pinned. They also cover reset ordering and concurrent resets. I deliberately broke the code three ways (removing the reset lock, getting the TestFixtures include order wrong, and skipping a connection release), and each time the test meant to catch it failed.
• The example app passed locally on Postgres across Ruby 3.2, 3.3, 3.4, and 4.0 with Rails 7.1, 7.2, and 8.0, with the transactional server on and off, including repeated runs on Rails 7.1, where it used to fail most often. It also passed on SQLite on Rails 7.1 through 8.1 in both modes.
• Failure behavior was checked with temporary specs: a raising reset hook returns a 500 and the next reset recovers, a failing test's writes are still rolled back at exit, and before_server_stop still runs even if that rollback raises.
• CI passed on two consecutive runs.

Related issues

• Incompatible with Rails 7.2 #164: Rails 7.2 incompatibility, the original reason for removing the transactional server. The new implementation works on Rails 7.2 and newer.
• before_server_stop hook not invoked when CYPRESS_RAILS_TRANSACTIONAL_SERVER=true #161: before_server_stop not running with the transactional server. I couldn't reproduce the hang with this implementation, and before_server_stop now runs even if the final rollback raises, but I haven't confirmed the original cause, so this PR doesn't close it.
• after_server_start hooks run once per boot poll instead of once #186: after_server_start runs once per boot poll. Pre-existing; fixed separately.