duel-rails 0.1.0

data/lib/generators/duel/install/templates/benchmark.rb.tt

@@ -0,0 +1,27 @@
+# The environment Duel benchmarks the app in (see .duel.rb): production's,
+# run locally, without what needs a deployment (SSL, a real secret, other
+# databases) and without logging.
+require_relative "production"
+
+Rails.application.configure do
+  config.secret_key_base = "duel-benchmark" * 4
+  config.require_master_key = false
+
+  config.logger = ActiveSupport::Logger.new(nil)
+  config.log_level = :fatal
+
+  # Requests come from Duel, without a server in front.
+  config.force_ssl = false
+  config.assume_ssl = false
+  config.hosts.clear
+  config.action_controller.allow_forgery_protection = false
+  config.public_file_server.enabled = true
+
+  # Each worker has one database of its own (DATABASE_URL): the cache and
+  # jobs stay in the worker. (While a benchmark runs, duel-rails performs
+  # the jobs it enqueues, and measures them with it: see .duel.rb.)
+  config.cache_store = :memory_store
+  config.active_job.queue_adapter = :test if config.respond_to?(:active_job)
+  config.solid_queue.connects_to = nil if config.respond_to?(:solid_queue)
+  config.action_mailer.delivery_method = :test if config.respond_to?(:action_mailer)
+end

data/lib/generators/duel/install/templates/boot_duel.rb.tt

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# How long the app takes to boot, in the benchmark environment: every run
+# is a fresh `bin/rails runner`, and each sample the fastest of a few runs
+# of each version (one, for a boot that takes a second or more), judged on
+# its CPU time (its children's too) and its peak memory. It boots without a
+# database of its own, so it measures boot alone: if your app's boot
+# queries the database, leave this benchmark out.
+duel_process "boot: the app", "bin/rails", "runner", "1"

data/lib/generators/duel/install/templates/duel.rb.tt

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# Duel compares this app's benchmarks (duel/) on two versions of it, each
+# booted in the benchmark environment (config/environments/benchmark.rb),
+# with a bundle of its own and a database of its own, which its schema
+# (and data) is loaded into. See
+# https://github.com/sferik/duel-ruby/tree/main/plugins/rails.
+Duel.configure do |c|
+<% if version_file? -%>
+  # Each version runs on the Ruby that its own .ruby-version names, so a
+  # change that upgrades Ruby is compared too. Each Ruby must be
+  # installed, with rbenv, chruby, mise or asdf, or be the one running
+  # Duel.
+  c.ruby = :version_file
+<% end -%>
+<% if fixtures? -%>
+  c.use :rails, database: <%= database ? ":#{database}" : "nil" %>, fixtures: :all
+<% else -%>
+  # To load test/fixtures, or db/seeds.rb, into each worker's database:
+  # fixtures: :all, or seeds: true.
+  c.use :rails, database: <%= database ? ":#{database}" : "nil" %>
+<% end -%>
+end

data/lib/generators/duel/install/templates/perf.yml.tt

@@ -0,0 +1,109 @@
+name: Perf
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+  schedule:
+    - cron: "0 4 * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pull-requests: write # to comment on a pull request with the report
+
+jobs:
+  duel:
+    name: Duel
+    runs-on: ubuntu-latest
+<% if working_directory -%>
+    # The app is in a subdirectory of the repository: Duel runs there, and
+    # checks out the whole repository for the baseline.
+    defaults:
+      run:
+        working-directory: <%= working_directory %>
+<% end -%>
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0 # the baseline comes from history, tags included
+<% if database == "postgresql" -%>
+      # Each worker starts a PostgreSQL server of its own (duel-postgresql).
+      - run: sudo apt-get install -y postgresql libpq-dev
+<% elsif %w[mysql2 trilogy].include?(database) -%>
+      # Each worker starts a MySQL server of its own (duel-mysql), with its
+      # data in a directory AppArmor would keep Ubuntu's mysqld out of.
+      - run: sudo apt-get install -y mysql-server
+      - run: |
+          if [ -f /etc/apparmor.d/usr.sbin.mysqld ]; then
+            sudo ln -sf /etc/apparmor.d/usr.sbin.mysqld /etc/apparmor.d/disable/
+            sudo apparmor_parser -R /etc/apparmor.d/usr.sbin.mysqld
+          fi
+<% end -%>
+<% if version_file? -%>
+      # Each version runs on the Ruby its own .ruby-version names (see
+      # .duel.rb): for a pull request that upgrades Ruby, the main branch's
+      # too, linked where Duel finds it (as chruby would). It's set up
+      # before the app's own Ruby, which runs Duel.
+      - name: Find the baseline's Ruby
+        id: baseline
+        if: github.event_name == 'pull_request'
+        run: echo "ruby=$(git show "origin/$GITHUB_BASE_REF:./.ruby-version" 2>/dev/null)" >> "$GITHUB_OUTPUT"
+      - uses: ruby/setup-ruby@v1
+        id: baseline-ruby
+        if: steps.baseline.outputs.ruby != ''
+        with:
+          ruby-version: ${{ steps.baseline.outputs.ruby }}
+      - name: Link the baseline's Ruby where Duel finds it
+        if: steps.baseline.outputs.ruby != ''
+        run: |
+          prefix="${{ steps.baseline-ruby.outputs.ruby-prefix }}"
+          mkdir -p ~/.rubies
+          ln -sfn "$prefix" ~/.rubies/ruby-"$("$prefix/bin/ruby" -e 'print RUBY_VERSION')"
+<% end -%>
+      - uses: ruby/setup-ruby@v1
+        with:
+<% if working_directory -%>
+          working-directory: <%= working_directory %>
+<% end -%>
+<% if ruby_version -%>
+          ruby-version: "<%= ruby_version %>"
+<% end -%>
+          bundler-cache: true
+      # Against the main branch for a pull request, what was there before
+      # for a push, and the last release on a schedule (slow creep). Duel
+      # adds its report to the job's summary, and writes it to duel.md for
+      # the comment.
+      - name: Compare
+        env:
+          DUEL_BASE: ${{ github.event_name == 'schedule' && 'last-release' || github.event_name == 'push' && github.event.before || '' }}
+          # (Run by hand, it compares anyway: with nothing changed, the code
+          # with itself, which checks the setup.)
+          DUEL_FORCE: ${{ github.event_name == 'workflow_dispatch' && '1' || '' }}
+        run: |
+          # (A branch's first push, or one that rewrote history, has no
+          # commit before it here to compare against.)
+          if [ "$GITHUB_EVENT_NAME" = push ] && ! git cat-file -e "$DUEL_BASE^{commit}" 2>/dev/null; then
+            echo "::notice::No commit before this push to compare against"
+            exit 0
+          fi
+          bundle exec duel --markdown "$RUNNER_TEMP/duel.md"
+      # The report, as a comment on the pull request: one comment, updated
+      # on every push. (A pull request from a fork gets no comment, as its
+      # token can't write one: the job's summary has the report.)
+      - name: Comment on the pull request
+        if: ${{ !cancelled() && github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository }}
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PR: ${{ github.event.pull_request.number }}
+        run: |
+          [ -f "$RUNNER_TEMP/duel.md" ] || exit 0
+          marker="<!-- duel<%= " #{working_directory}" if working_directory %> -->"
+          { echo "$marker"; cat "$RUNNER_TEMP/duel.md"; } > "$RUNNER_TEMP/comment.md"
+          ids=$(gh api --paginate "repos/$GITHUB_REPOSITORY/issues/$PR/comments" \
+            --jq ".[] | select(.user.login == \"github-actions[bot]\" and (.body | startswith(\"$marker\"))) | .id")
+          if [ -n "$ids" ]; then
+            gh api --method PATCH "repos/$GITHUB_REPOSITORY/issues/comments/${ids%%$'\n'*}" -F body=@"$RUNNER_TEMP/comment.md" > /dev/null
+          else
+            gh api --method POST "repos/$GITHUB_REPOSITORY/issues/$PR/comments" -F body=@"$RUNNER_TEMP/comment.md" > /dev/null
+          fi

data/lib/generators/duel/install/templates/requests_duel.rb.tt

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# Benchmarks of the app's requests. Each sends its request through the
+# whole Rack stack, performs the jobs it enqueued, and rolls back what it
+# wrote. A version fails that's slower at any of them, or that queries
+# the database, renders views or allocates more. Add the requests that
+# matter most, with what they send:
+#
+#   duel_request "posts: create", "POST /posts", params: {post: {title: "Hi"}}
+<% routes.each do |name, request| -%>
+
+duel_request <%= name.inspect %>, <%= request.inspect %>
+<% end -%>

data/sig/duel/rails.rbs

@@ -0,0 +1,245 @@
+module Duel
+  # Duel for a Rails app: each version booted in the benchmark
+  # environment, with a bundle and a database of its own, and benchmarks
+  # of requests (DSL#duel_request), with the jobs they enqueue.
+  module Rails
+    VERSION: String
+
+    # What .configure gave .reset_data to load again, or nil (no database).
+    self.@data: {fixtures: Array[Symbol | String] | :all, seeds: bool, seed: Integer}?
+
+    # What a change must touch to be compared.
+    WATCH: Array[String]
+
+    # The environment each version boots in.
+    ENVIRONMENT: String
+
+    # What random numbers are seeded with in each worker.
+    SEED: Integer
+
+    # An around_iteration hook: each iteration rolled back after it.
+    ROLLBACK: ^(Iteration iteration) -> untyped
+
+    # Configures Duel for the app, c.use :rails (see the README for the
+    # options).
+    def self.configure: (Config config, ?database: Symbol?, ?environment: String, ?bundle: bool,
+                       ?fixtures: Array[Symbol | String] | :all, ?seeds: bool, ?seed: Integer, ?reset: bool, ?jobs: bool,
+                       ?active_record: bool, ?query_time: bool, **untyped database_options) -> Counter
+
+    # Boots the version at +root+ in +environment+, from its own tree.
+    def self.boot: (String root, String environment) -> bool
+
+    # Loads the worker's data: the schema, fixtures, and seeds.
+    def self.load_worker_data: (fixtures: Array[Symbol | String] | :all, seeds: bool, seed: Integer) -> void
+
+    # Loads fixtures and seeds, with random numbers seeded.
+    def self.load_data: (fixtures: Array[Symbol | String] | :all, seeds: bool, seed: Integer) -> void
+
+    # Empties every table, and loads its fixtures and seeds again.
+    def self.reset_data: () -> void
+
+    # Runs the block with what it writes to the database rolled back.
+    def self.rolled_back: [T] () { () -> T } -> T
+
+    # Seeds Ruby's random numbers, and Faker's.
+    def self.seed_random: (Integer seed) -> void
+
+    # Each version runs its own bundle.
+    module Bundle
+      def self.configure: (Config config) -> void
+
+      # The environment for the bundle of the version, installed first.
+      def self.environment: (Resource version) -> Hash[String, String?]
+
+      # What a bundle installed for a lockfile, on a Ruby, is kept as.
+      def self.key: (String lockfile, String ruby) -> String
+
+      # The runner's environment without Bundler's part.
+      def self.unbundled: () -> Hash[String, String?]
+    end
+
+    # Each worker's own database, with its version's schema and data.
+    module Database
+      # The plugin that gives each worker a server, by database.
+      SERVERS: Hash[Symbol, Symbol]
+
+      # The URL's scheme, by database, where the plugin's own isn't it.
+      SCHEMES: Hash[Symbol, String]
+
+      def self.configure: (Config config, Symbol database, **untyped options) -> untyped
+
+      # Loads the version's schema into the worker's database.
+      def self.load_schema: () -> void
+
+      # Empties every table of the worker's database.
+      def self.clear: () -> void
+
+      # Loads fixtures, by name, or every one.
+      def self.load_fixtures: (Array[Symbol | String] | :all names, ?path: path) -> void
+    end
+
+    # A request a benchmark sends the app, through its whole Rack stack.
+    class Request
+      METHODS: Array[String]
+
+      # The statuses a request is expected to answer with, unless told.
+      OK: Range[Integer]
+
+      @options: Hash[untyped, untyped]
+      @status: Integer | Range[Integer]
+      @rollback: bool
+
+      attr_reader verb: String
+      attr_reader path: String
+
+      def initialize: (String request, ?params: Hash[untyped, untyped]?, ?json: untyped, ?headers: Hash[String | Symbol, String],
+                       ?status: Integer | Range[Integer], ?rollback: bool) -> void
+
+      # A fresh Rack environment for the request.
+      def env: () -> Hash[String, untyped]
+
+      # Sends the request; fails unless its status is as expected.
+      def call: (?Hash[String, untyped] rack_env) -> Integer
+
+      # Its benchmark's own hooks: ROLLBACK, unless it isn't rolled back.
+      def hooks: () -> Hash[Symbol, untyped]
+
+      # Defines a benchmark of the request, on a file of benchmarks' DSL.
+      def self.duel: (::Duel::DSL dsl, String name, String request, ?only: only?, ?peak_memory: bool, **untyped options) ?{ (Hash[String, untyped] env) [self: untyped] -> void } -> void
+
+      private
+
+      def respond: (Hash[String, untyped] env) -> Integer
+
+      def header: (String | Symbol name) -> String
+    end
+
+    # What files of benchmarks get, as .duel.rb uses the plugin.
+    module DSL : ::Duel::DSL
+      # Defines a benchmark of a request to the app.
+      def duel_request: (String name, ?String request, **untyped options) ?{ (Hash[String, untyped] env) [self: untyped] -> void } -> void
+    end
+
+    # What the app's views and its cache did for each benchmark.
+    class Counter
+      # A notification's payload, as Rails gives it.
+      type payload = Hash[Symbol, untyped]
+
+      MEASURES: Hash[String, Metric::settings]
+
+      # What each event it subscribes to is.
+      EVENTS: Hash[String, Symbol]
+
+      # The most views shown, explaining a regression.
+      SHOWN: Integer
+
+      @views: Integer
+      @reads: Integer
+      @misses: Integer
+      @writes: Integer
+      @rendered: Hash[String?, Integer]
+      @subscriptions: Array[untyped]
+      @root: String
+
+      def self.configure: (Config config) -> Counter
+
+      def initialize: () -> void
+
+      def subscribe: () -> void
+
+      def unsubscribe: () -> void
+
+      # The totals so far, by name.
+      def totals: () -> Hash[String, Integer]
+
+      # Each view rendered so far, by its template's path.
+      def views: () -> Hash[String?, Integer]
+
+      # What explains the views a sample rendered, or nil.
+      def details: (Array[[Snapshot::Reading[Integer, Hash[String?, Integer]], Snapshot::Reading[Integer, Hash[String?, Integer]]]] stretches,
+                    Integer n) -> Hash[String, String]?
+
+      def start: (String name, String id, payload payload) -> nil
+
+      def finish: (String name, String id, payload payload) -> void
+
+      private
+
+      def view: (payload payload, Integer count) -> void
+
+      def read: (Integer keys, Integer hits) -> void
+    end
+  end
+
+  module Rails
+    # Active Job's queue while benchmarking: jobs performed after the
+    # iterations (an after_iterations hook).
+    class Jobs
+      @queue: Array[Hash[String, untyped]]
+
+      def self.configure: (Config config) -> Jobs
+
+      def initialize: () -> void
+
+      # Makes it Active Job's queue adapter, if the app has Active Job.
+      def use: () -> void
+
+      def enqueue: (untyped job) -> void
+
+      def enqueue_at: (untyped job, untyped timestamp) -> void
+
+      def enqueue_after_transaction_commit?: () -> true
+
+      def stopping?: () -> false
+
+      # The jobs waiting to be performed.
+      def size: () -> Integer
+
+      # Performs the jobs waiting, and those they enqueue.
+      def perform: () -> void
+
+      # Forgets the jobs waiting.
+      def clear: () -> void
+    end
+  end
+
+  module Rails
+    # In the app: `rake duel`.
+    class Railtie < ::Rails::Railtie
+      # Defines `rake duel`, unless there's one.
+      def self.define_task: () -> void
+    end
+  end
+
+  module Generators
+    # `rails generate duel:install`.
+    class InstallGenerator < ::Rails::Generators::Base
+      ADAPTERS: Hash[String, String]
+      PLUGINS: Hash[String, String]
+      ROUTES: Integer
+      FRAMEWORK: Regexp
+
+      def create_config: () -> void
+      def create_environment: () -> void
+      def create_benchmarks: () -> void
+      def create_boot_benchmark: () -> void
+      def create_workflow: () -> void
+      def add_plugin: () -> void
+      def add_stackprof: () -> void
+
+      private
+
+      # The app's Gemfile.
+      def gemfile: () -> String
+
+      def database: () -> String?
+      def adapter: () -> String?
+      def routes: () -> Array[[String, String]]
+      def fixtures?: () -> bool
+      def version_file?: () -> bool
+      def ruby_version: () -> String?
+      def repository: () -> String
+      def working_directory: () -> String?
+    end
+  end
+end

metadata

@@ -0,0 +1,106 @@
+--- !ruby/object:Gem::Specification
+name: duel-rails
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Erik Berlin
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: duel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: duel-activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+description: 'A Duel plugin for Rails apps: each version of the app booted like production,
+  with its own bundle and database, and benchmarks of its requests, judged on time,
+  allocations, queries, views and cache use.'
+email:
+- sferik@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/duel/rails.rb
+- lib/duel/rails/bundle.rb
+- lib/duel/rails/counter.rb
+- lib/duel/rails/database.rb
+- lib/duel/rails/jobs.rb
+- lib/duel/rails/railtie.rb
+- lib/duel/rails/request.rb
+- lib/duel/rails/version.rb
+- lib/generators/duel/install/install_generator.rb
+- lib/generators/duel/install/templates/benchmark.rb.tt
+- lib/generators/duel/install/templates/boot_duel.rb.tt
+- lib/generators/duel/install/templates/duel.rb.tt
+- lib/generators/duel/install/templates/perf.yml.tt
+- lib/generators/duel/install/templates/requests_duel.rb.tt
+- sig/duel/rails.rbs
+homepage: https://github.com/sferik/duel-ruby/tree/main/plugins/rails
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/sferik/duel-ruby/tree/main/plugins/rails
+  changelog_uri: https://github.com/sferik/duel-ruby/blob/main/plugins/rails/CHANGELOG.md
+  bug_tracker_uri: https://github.com/sferik/duel-ruby/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.23
+specification_version: 4
+summary: Performance regression guards for Rails apps, with Duel
+test_files: []