haveapi 0.31.1 → 0.32.0

data/spec/documentation/validators_spec.rb

@@ -0,0 +1,123 @@
+require 'spec_helper'
+require 'haveapi/documentation_validators'
+
+describe HaveAPI::DocumentationValidators do
+  def render(name, options, type: nil)
+    described_class.render({ name => options }, type:)
+  end
+
+  it 'keeps every rule in a semantic subtable with scoped row headers' do
+    html = described_class.render({ present: { empty: false }, include: { values: [false, 0, ''] } })
+    expect(html).to include('<div class="docs-validators"><table class="docs-validator-table"><caption>Validation rules</caption>',
+                            '<th scope="col">Rule</th><th scope="col">Details</th>',
+                            '<tr class="docs-validator"><th scope="row">Present</th><td>',
+                            '<tr class="docs-validator"><th scope="row">Include</th><td>')
+    expect(html.scan('<table').length).to eq(1)
+    expect(html.scan('<tr class="docs-validator">').length).to eq(2)
+    expect(html).not_to include('<h5>')
+    expect(described_class.render({})).to eq('')
+    expect(described_class.render(nil)).to eq('')
+  end
+
+  it 'explains required presence and its distinct empty-value modes' do
+    strict = render(:present, { empty: false, message: 'Required value' })
+    expect(strict).to include('Must be supplied and cannot be null.', 'Must not be empty;', 'non-whitespace', 'Required value')
+    expect(render(:present, { empty: true })).to include('Empty values are allowed.')
+  end
+
+  it 'renders inclusion choices as typed machine values with separate localized labels' do
+    values = { 'active' => 'Aktivní', 0 => 'Zero', false => 'Disabled', nil => 'Unset' }
+    html = render(:include, { values:, message: 'Select one' })
+    expect(html).to include('Allowed values:', '<code>active</code>: Aktivní', '<code>0</code>: Zero',
+                            '<code>false</code>: Disabled', '<code>null</code>: Unset', 'Select one')
+    expect(html).not_to include('=&gt;', '{&quot;active&quot;')
+    expect(html.index('Aktivní')).to be < html.index('Zero')
+  end
+
+  it 'lists array alternatives, reserved exclusions and empty sets honestly' do
+    expect(render(:include, { values: ['', false, 0] })).to include('<code></code>', '<code>false</code>', '<code>0</code>')
+    expect(render(:exclude, { values: ['root'] })).to include('Disallowed values:', '<code>root</code>')
+    expect(render(:exclude, { values: ['root'] })).not_to include('Allowed values:')
+    expect(render(:include, { values: [] })).to include('The set is empty.')
+    expect(render(:include, { values: {} })).to include('The set is empty.')
+  end
+
+  %i[include exclude].each do |rule|
+    it "keeps #{rule} string contents including quotes and Unicode without adding presentation quotes" do
+      html = render(rule, { values: ['<tag>&"Žluťoučký"', "'quoted'", '', 'false', '0', 'null'] })
+      expect(html).to include('<ul class="docs-validator-values">', '<li><code>&lt;tag&gt;&amp;&quot;Žluťoučký&quot;</code></li>',
+                              '<li><code>&#39;quoted&#39;</code></li>', '<li><code></code></li>',
+                              '<li><code>false</code></li>', '<li><code>0</code></li>', '<li><code>null</code></li>')
+      expect(html).not_to include('<tag>', '&amp;lt;', 'The set is empty.', '<code>&quot;')
+    end
+
+    it "retains #{rule} nonstring types and nested JSON quoting" do
+      html = render(rule, { values: [true, false, 0, 1.5, nil, ['a"b', ''], { 'nested' => ['<tag>', nil] }] })
+      expect(html).to include('<li><code>true</code></li>', '<li><code>false</code></li>', '<li><code>0</code></li>',
+                              '<li><code>1.5</code></li>', '<li><code>null</code></li>',
+                              '<li><code>[&quot;a\&quot;b&quot;,&quot;&quot;]</code></li>',
+                              '<li><code>{&quot;nested&quot;:[&quot;&lt;tag&gt;&quot;,null]}</code></li>')
+    end
+  end
+
+  it 'keeps inclusion hash labels and empty string keys separate from empty sets' do
+    html = render(:include, { values: { '' => 'Empty label <&>', '"quoted"' => false, 'žluťoučký' => ['nested'] } })
+    expect(html).to include('<li><code></code>: Empty label &lt;&amp;&gt;</li>',
+                            '<li><code>&quot;quoted&quot;</code>: <code>false</code></li>',
+                            '<li><code>žluťoučký</code>: <code>[&quot;nested&quot;]</code></li>')
+    expect(html).not_to include('The set is empty.', 'Empty label <&>', '&amp;lt;')
+  end
+
+  it 'keeps acceptance and confirmation values distinct without coercion' do
+    [nil, false, 0, '0'].each do |value|
+      expect(render(:accept, { value: })).to include("Must equal <code>#{CGI.escapeHTML(JSON.generate(value))}</code>")
+    end
+    expect(render(:confirm, { parameter: :password, equal: true })).to include('Must equal parameter <code>password</code>')
+    expect(render(:confirm, { parameter: 'password', equal: false })).to include('Must differ from parameter <code>password</code>')
+  end
+
+  it 'explains inclusive bounds, step origin, modulo and parity separately' do
+    html = render(:number, { min: 3, max: 10, step: 2, mod: 5, odd: true })
+    expect(html).to include('Minimum: <code>3</code> (inclusive)', 'Maximum: <code>10</code> (inclusive)',
+                            'Step: <code>2</code>, measured from <code>3</code>',
+                            'multiple of <code>5</code>, measured from zero', 'Must be odd.', 'Must be a number after parameter type conversion.')
+    expect(render(:number, { step: 2, even: true, odd: false })).to include('measured from <code>0</code>', 'Must be even.', 'Odd-only restriction: disabled.')
+  end
+
+  it 'describes character length for text and neutral length for unknown types' do
+    expect(render(:length, { min: 0, max: 12 }, type: 'String')).to include('Minimum length: <code>0</code> characters', 'Maximum length: <code>12</code> characters')
+    expect(render(:length, { equals: 2 }, type: 'Custom')).to include('Length must equal <code>2</code>.')
+    expect(render(:length, { equals: 2 }, type: 'Array')).to include('<code>2</code> items')
+    expect(render(:length, { equals: 2 }, type: 'Text')).not_to include('bytes')
+  end
+
+  it 'shows regex source, negation and descriptions without inventing flags' do
+    html = render(:format, { rx: '^[a-z]+$', match: false, description: 'Reserved spelling', message: 'Invalid spelling' })
+    expect(html).to include('Must not match this regular expression:', '<code>^[a-z]+$</code>', 'Reserved spelling', 'Validation error message:', 'Invalid spelling')
+  end
+
+  it 'labels application-specific rules without claiming generic enforcement' do
+    expect(render(:custom, 'Verified by the application')).to include('Application-specific rule: Verified by the application')
+    expect(render(:custom, 'Verified by the application')).not_to include('Must pass', 'automatically')
+  end
+
+  it 'preserves unknown fields and unexpected shapes with a labelled lossless fallback' do
+    html = render('X-Extension', { 'nested' => { 'zero' => 0, 'false' => false, 'empty' => '', 'null' => nil } })
+    expect(html).to include('X-Extension', 'JSON:', '&quot;zero&quot;: 0', '&quot;false&quot;: false', '&quot;empty&quot;: &quot;&quot;', '&quot;null&quot;: null')
+    expect(render(:include, { values: 'unexpected', message: 'Kept' })).to include('Supplied validator metadata:', 'unexpected', 'Kept')
+    expect(render(:number, { min: 'not numeric', message: 'Kept' })).to include('Supplied validator metadata:', 'not numeric', 'Kept')
+    expect(render(:include, { values: [], extra: false })).to include('Additional details', CGI.escapeHTML({ extra: false }.inspect), 'Ruby value:')
+    expect(render(:include, { values: [:symbol] })).to include('Ruby value:', ':symbol')
+  end
+
+  it 'escapes source labels messages and structured options once without mutation' do
+    payload = '<script>&"'
+    options = { values: { payload => payload }, message: payload, extra: { 'nested' => payload } }
+    before = Marshal.dump(options)
+    html = render(:include, options)
+    expect(html).not_to include('<script>', '&amp;lt;')
+    expect(html).to include('&lt;script&gt;&amp;', 'Validation error message:', 'Additional details')
+    expect(render(payload, { 'extra' => payload })).to include('<th scope="row">&lt;script&gt;&amp;&quot;</th>')
+    expect(Marshal.dump(options)).to eq(before)
+  end
+end

data/spec/documentation_spec.rb

@@ -174,7 +174,7 @@ describe 'Documentation' do
     expect(last_response.headers['Content-Type']).to include('text/html')
 
     # servers/ruby/doc/index.md contains this heading
-    expect(last_response.body).to include('HaveAPI documentation')
+    expect(last_response.body).to include('HaveAPI internals')
   end
 
   it 'has online index doc page without a sidebar template' do
@@ -182,11 +182,11 @@ describe 'Documentation' do
 
     expect(last_response.status).to eq(200)
     expect(last_response.headers['Content-Type']).to include('text/html')
-    expect(last_response.body).to include('HaveAPI documentation')
+    expect(last_response.body).to include('HaveAPI internals')
   end
 
   it 'has online doc for every version' do
-    get '/v1/'
+    get '/v1/?resource=user'
     expect(last_response.status).to eq(200)
     expect(last_response.headers['Content-Type']).to include('text/html')
     expect(last_response.body).to include('verified by MFA backend')

data/spec/packaging_spec.rb

@@ -55,6 +55,8 @@ describe HaveAPI::Server do
       end
       %w[
         lib/haveapi/documentation_context.rb lib/haveapi/documentation_clients.rb
+        lib/haveapi/shared_documentation_helpers.rb
+        lib/haveapi/views/shared_sidebar.erb lib/haveapi/views/shared_documentation.erb
         lib/haveapi/views/version_page/client_result.erb
         lib/haveapi/public/js/highlight.pack.js lib/haveapi/public/js/highlight-LICENSE
       ].each do |name|
@@ -83,9 +85,9 @@ describe HaveAPI::Server do
         server.use_version(1)
         server.mount('/')
         request = Rack::MockRequest.new(server.app)
-        responses = %w[/doc/json-schema /doc/protocol.md /doc/create-client.md /doc/client-examples.md /js/highlight-LICENSE].to_h do |path|
+        responses = %w[/ /doc /doc/index /doc/index.md /doc/readme /doc/json-schema /doc/protocol.md /doc/create-client.md /doc/client-examples.md /js/highlight-LICENSE].to_h do |path|
           response = request.get(path, 'HTTP_HOST' => 'localhost')
-          [path, { status: response.status, type: response.content_type, body: response.body }]
+          [path, { status: response.status, type: response.content_type, cache_control: response['Cache-Control'], body: response.body }]
         end
         puts JSON.generate({
           framework: HaveAPI::Server.instance_method(:mount).source_location.first,
@@ -117,6 +119,11 @@ describe HaveAPI::Server do
       expect(File.realpath(result.fetch('framework'))).to eq(File.join(dir, 'lib/haveapi/server.rb'))
 
       {
+        '/' => 'API versions',
+        '/doc' => 'Server-side implementation',
+        '/doc/index' => 'Server-side implementation',
+        '/doc/index.md' => 'Server-side implementation',
+        '/doc/readme' => 'Server-side implementation',
         '/doc/json-schema' => 'Envelope',
         '/doc/protocol.md' => 'Protocol definition',
         '/doc/create-client.md' => 'Client definition',
@@ -127,6 +134,18 @@ describe HaveAPI::Server do
         expect(response.fetch('status')).to eq(200), "Packaged route failed: #{path}"
         expect(response.fetch('type')).to include('text/html') unless path == '/js/highlight-LICENSE'
         expect(response.fetch('body')).to include(heading)
+        next if path == '/js/highlight-LICENSE'
+
+        expect(response.fetch('cache_control')).to eq('private, no-store')
+        expect(response.fetch('body')).to include('data-docs', '/js/documentation.js', '/css/documentation.css')
+        expect(response.fetch('body')).not_to include('/js/main.js', '/css/bootstrap')
+      end
+      %w[/doc /doc/index /doc/index.md /doc/readme].each do |path|
+        body = result.fetch('responses').fetch(path).fetch('body')
+        expect(body).to include('<title>HaveAPI internals · ', 'Server framework features',
+                                '<pre><code class="ruby">', 'class User &lt; ActiveRecord::Base')
+        menu = body.match(%r{<nav aria-label="Shared documentation">(.*?)</nav>}m)[1]
+        expect(menu).not_to include('href="/doc/readme"')
       end
     end
   end

data/spec/performance/documentation_identity_fixture_spec.rb

@@ -0,0 +1,47 @@
+require 'spec_helper'
+require_relative '../../benchmarks/endpoints'
+require_relative '../../test_support/documentation_performance_fixture'
+
+describe HaveAPI::Performance::DocumentationScenario, '#call' do
+  def scenario(id, user = 'admin')
+    HaveAPI::Performance::DocumentationScenario.new(id:, dimensions: { size: 1, user: })
+  end
+
+  it 'validates a real cookie token on every HTML page with stable role-specific bodies and counters' do
+    page = scenario('docs.html_resources')
+    page.reset!(iterations: 3)
+    responses = 3.times.map { page.call }
+    responses.each_with_index { |response, index| expect(page.validate!(response, index:)[:http_status]).to eq(200) }
+    expect(responses.map(&:body).uniq.length).to eq(1)
+    expect(responses.first.body).to include('<span class="docs-identity">admin</span>', 'name="csrf"')
+    fixture = page.instance_variable_get(:@server).fixture_documentation_oauth
+    expect(fixture.lookups).to eq(Array.new(3) { [1, 'documentation-admin'] })
+    expect(page.documentation_identity).to eq(mode: 'documentation_oauth_cookie', role: 'admin')
+    expect(page.counters[:operations]).to eq(Array.new(3) { { queries: 0, authorizations: 2, executions: 0 } })
+  end
+
+  it 'keeps member role filtering and independent CSRF without accepting an admin overview' do
+    admin = scenario('docs.html_resources')
+    member = scenario('docs.html_resources', 'member')
+    [admin, member].each { |page| page.reset!(iterations: 1) }
+    administrative = admin.call
+    restricted = member.call
+    expect(member.validate!(restricted, index: 0)[:http_status]).to eq(200)
+    expect(restricted.body).to include('<span class="docs-identity">member</span>')
+    expect(restricted.body).not_to include('root-resource0-admin_only')
+    expect { member.validate_body!(administrative) }.to raise_error(HaveAPI::Performance::ContractError, /authorization/)
+    nonce = ->(response) { response.body.match(/name="csrf" value="([^"]+)"/)[1] }
+    expect(nonce.call(restricted)).not_to eq(nonce.call(administrative))
+  end
+
+  it 'retains ordinary Basic setup and counter behavior for documentation OPTIONS' do
+    page = scenario('docs.options')
+    page.reset!(iterations: 1)
+    response = page.call
+    expect(page.validate!(response, index: 0)[:http_status]).to eq(200)
+    expect(page.documentation_identity).to eq(mode: 'basic', role: 'admin')
+    expect(page.instance_variable_get(:@headers)).to include('HTTP_AUTHORIZATION')
+    expect(page.instance_variable_get(:@headers)).not_to include('HTTP_COOKIE')
+    expect(page.instance_variable_get(:@server)).not_to respond_to(:fixture_documentation_oauth)
+  end
+end

data/spec/performance/documentation_shapes_spec.rb

@@ -0,0 +1,97 @@
+require 'spec_helper'
+require_relative '../../benchmarks/endpoints'
+require_relative '../../benchmarks/documentation'
+require_relative '../../test_support/documentation_performance_fixture'
+
+describe HaveAPI::Performance::DocumentationScenario do
+  let(:scenario) { described_class.new(id: 'docs.html_resources', dimensions: { size: 2, user: 'admin' }) }
+  let(:overview) do
+    scenario.reset!(iterations: 1)
+    scenario.call
+  end
+  let(:error) { HaveAPI::Performance::ContractError }
+
+  def response_with(body)
+    Rack::MockResponse.new(200, { 'content-type' => 'text/html' }, body)
+  end
+
+  def replace_map(body)
+    body.sub(%r{(<script\b[^>]*data-legacy-anchors[^>]*>)(.*?)(</script>)}m) do
+      before, json, after = Regexp.last_match.captures
+      values = JSON.parse(json)
+      yield(values)
+      "#{before}#{JSON.generate(values)}#{after}"
+    end
+  end
+
+  it 'accepts the actual overview and preserves authorization counters and raw identity' do
+    identity = scenario.validate!(overview, index: 0)
+    expect(identity[:page]).to include(shape: 'overview', actual_examples: 0, resources: 2, actions: 3)
+    expect(identity[:body_sha256]).to eq(Digest::SHA256.hexdigest(overview.body))
+    expect(overview.body).not_to include('PUBLIC_SAMPLE_', 'ADMIN_ONLY_REQUEST')
+  end
+
+  it 'accepts the strict legacy full-page contract without accepting an empty third shape' do
+    legacy = response_with('init-python-sync init-examples PUBLIC_SAMPLE_0 ADMIN_ONLY_REQUEST')
+    expect(scenario.validate_body!(legacy)[:page]).to include(shape: 'monolithic')
+    expect { scenario.validate_body!(response_with('<h1>Empty</h1>')) }.to raise_error(error, /panels/)
+  end
+
+  it 'requires directory navigation, canonical targets and real initialization code' do
+    bodies = [
+      overview.body.gsub('data-resource-directory-link', 'data-missing-directory-link'),
+      overview.body.sub('href="/benchmark/api/v1/?page=resources"', 'href="https://foreign.example/"'),
+      overview.body.sub('id="init-python-sync"', 'id="missing-python-sync"'),
+      overview.body.sub('id="init-python-sync-thorough"', 'id="missing-python-thorough"'),
+      overview.body.sub('id="init-javascript-async"', 'id="missing-javascript-async"')
+    ]
+    bodies.each do |body|
+      expect { scenario.validate_body!(response_with(body)) }.to raise_error(error, /navigation|initialization/)
+    end
+  end
+
+  it 'rejects duplicate, malformed, wrong and mixed overview representations' do
+    bodies = [
+      overview.body.sub('data-page="overview"', 'data-page="resource"'),
+      overview.body.sub('data-docs data-page=', 'data-docs data-docs data-page='),
+      "#{overview.body}<div data-docs data-page=\"overview\"></div>",
+      overview.body.sub('data-page="overview"', 'data-page="overview" data-page="resource"'),
+      "#{overview.body}<div id=\"example-resource0-action0-0-examples\">PUBLIC_SAMPLE_0</div>"
+    ]
+    bodies.each { |body| expect { scenario.validate_body!(response_with(body)) }.to raise_error(error, /overview/) }
+  end
+
+  it 'rejects missing, wrong or foreign legacy destinations and wrong authorization roles' do
+    maps = [
+      ->(values) { values.delete('root-resource1-action0') },
+      ->(values) { values['root-resource1'] = '/benchmark/api/v1/?resource=resource0' },
+      ->(values) { values['example-resource0-action0-'] = 'https://foreign.example/' },
+      ->(values) { values.delete('root-resource0-admin_only') },
+      ->(values) { values['auth-basic'] = 'https://foreign.example/' }
+    ]
+    maps.each do |mutate|
+      body = replace_map(overview.body, &mutate)
+      expect { scenario.validate_body!(response_with(body)) }.to raise_error(error, /authorization|targets/)
+    end
+    member = described_class.new(id: 'docs.html_resources', dimensions: { size: 2, user: 'member' })
+    expect { member.validate_body!(overview) }.to raise_error(error, /authorization/)
+  end
+
+  it 'rejects malformed legacy JSON and private parameter or sample data in either role' do
+    body = overview.body.sub(%r{(<script[^>]*data-legacy-anchors[^>]*>).*?(</script>)}m, '\1[\2')
+    expect { scenario.validate_body!(response_with(body)) }.to raise_error(error, /map/)
+    %w[PUBLIC_SAMPLE_0 ADMIN_ONLY_DEFAULT ADMIN_ONLY_REQUEST ADMIN_ONLY_RESPONSE admin_field].each do |marker|
+      expect { scenario.validate_body!(response_with("#{overview.body}<p>#{marker}</p>")) }.to raise_error(error, /action data/)
+    end
+  end
+
+  it 'retains the optional benchmark root HTML lane for both explicit representations' do
+    benchmark = HaveAPI::DocumentationBenchmark.new([])
+    dimensions = { resource_count: 2 }
+    expect(benchmark.send(:html_output, overview, dimensions)[:status]).to eq(200)
+    legacy = response_with('init-examples PUBLIC_SAMPLE_0')
+    expect(benchmark.send(:html_output, legacy, dimensions)[:status]).to eq(200)
+    malformed = response_with(overview.body.sub('data-page="overview"', 'data-page="resource"'))
+    expect { benchmark.send(:html_output, malformed, dimensions) }.to raise_error(HaveAPI::DocumentationBenchmark::InvalidOutput)
+  end
+end

data/spec/performance/json_activation_spec.rb

@@ -29,6 +29,83 @@ describe HaveAPI::Performance do
     end
   end
 
+  def with_console_versions(pinned: true)
+    with_newer_json do |directory, environment|
+      (pinned ? %w[0.9.4 99.0.0] : ['99.0.0']).each do |version|
+        library = File.join(directory, "gems/io-console-#{version}/lib/io")
+        FileUtils.mkdir_p(library)
+        File.write(File.join(library, 'console.rb'), "CONSOLE_ACTIVATION_CONTROL = #{version.inspect}\n")
+        spec = Gem::Specification.new do |gem|
+          gem.name = 'io-console'
+          gem.version = version
+          gem.summary = 'Owned worker activation control'
+          gem.authors = ['Fixture']
+        end
+        File.write(File.join(directory, "specifications/io-console-#{version}.gemspec"), spec.to_ruby)
+      end
+      yield directory, environment
+    end
+  end
+
+  it 'activates the exact frozen console before source loading despite a newer visible version' do
+    with_console_versions do |_directory, environment|
+      program = <<~RUBY
+        require #{File.join(root, 'servers/ruby/benchmarks/endpoints.rb').inspect}
+        visible = Gem::Specification.find_all_by_name('io-console').map { |spec| spec.version.to_s }
+        begin
+          HaveAPI::Performance::Worker.new('benchmark' => true, 'source_root' => '/missing-worker-source').run
+        rescue Errno::ENOENT
+          puts JSON.generate(visible: visible, loaded: Gem.loaded_specs.fetch('io-console').version.to_s,
+                             required: CONSOLE_ACTIVATION_CONTROL, pp_loaded: $LOADED_FEATURES.any? { |path| path.end_with?('/pp.rb') })
+        end
+      RUBY
+      output, errors, status = Open3.capture3(environment, RbConfig.ruby, '-e', program)
+      expect(status).to be_success, errors
+      result = JSON.parse(output)
+      expect(result.fetch('visible')).to include('99.0.0')
+      expect(result).to include('loaded' => '0.9.4', 'required' => '0.9.4', 'pp_loaded' => false)
+      budgets = JSON.parse(File.read(File.join(root, 'servers/ruby/benchmarks/performance_budgets.json')))
+      expect(budgets.fetch('environment').values.map { |value| value.fetch('gems').fetch('io-console').fetch('version') })
+        .to all(eq(result.fetch('loaded')))
+      lock = Bundler::LockfileParser.new(File.read(File.join(root, 'servers/ruby/benchmarks/Gemfile.lock')))
+      expect(lock.specs.find { |spec| spec.name == 'io-console' }.version.to_s).to eq(result.fetch('loaded'))
+    end
+  end
+
+  it 'leaves ordinary and non-Boolean worker console activation unchanged' do
+    with_console_versions(pinned: false) do |_directory, environment|
+      program = <<~RUBY
+        require #{File.join(root, 'servers/ruby/benchmarks/endpoints.rb').inspect}
+        before = Gem.loaded_specs['io-console']&.version&.to_s
+        [nil, false, 'true', 1].each do |flag|
+          HaveAPI::Performance::Worker.new('benchmark' => flag).send(:activate_benchmark_console)
+        end
+        puts JSON.generate(before: before, after: Gem.loaded_specs['io-console']&.version&.to_s,
+                           required: defined?(CONSOLE_ACTIVATION_CONTROL))
+      RUBY
+      output, errors, status = Open3.capture3(environment, RbConfig.ruby, '-e', program)
+      expect(status).to be_success, errors
+      expect(JSON.parse(output)).to include('before' => nil, 'after' => nil, 'required' => nil)
+    end
+  end
+
+  it 'fails frozen workers clearly when the console version is missing or already conflicting' do
+    %w[missing conflicting].each do |control|
+      with_console_versions(pinned: control == 'conflicting') do |directory, environment|
+        program = <<~RUBY
+          require #{File.join(root, 'servers/ruby/benchmarks/endpoints.rb').inspect}
+          Gem.use_paths(#{directory.inspect}, [#{directory.inspect}])
+          gem 'io-console', '= 99.0.0' if #{control.inspect} == 'conflicting'
+          HaveAPI::Performance::Worker.new('benchmark' => true).send(:activate_benchmark_console)
+        RUBY
+        _output, errors, status = Open3.capture3(environment, RbConfig.ruby, '-e', program)
+        expect(status).not_to be_success
+        expect(errors).to include('io-console', '0.9.4')
+        expect(errors).to include(control == 'missing' ? 'Could not find' : 'already activated io-console-99.0.0')
+      end
+    end
+  end
+
   it 'loads the native calibrated version in each public entry despite a newer visible gem' do
     with_newer_json do |_directory, environment|
       [comparison, File.join(root, 'utils/performance_ci.rb'), File.join(root, 'servers/ruby/benchmarks/endpoints.rb')].each do |entry|
@@ -76,7 +153,7 @@ describe HaveAPI::Performance do
       _output, errors, status = Open3.capture3(environment, RbConfig.ruby, '-e', program)
       expect(status).not_to be_success
       expect(errors).to include('json', '2.21.2', '3.1.0')
-      expect(errors).to match(/Could not find/)
+      expect(errors).to include('Could not find')
     end
   end
 

data/spec/performance/release_lineage_spec.rb

@@ -236,6 +236,7 @@ describe HaveAPI::Performance::Release do
       File.write(File.join(harness, 'servers/ruby/Gemfile.lock'), "controlled server lock\n")
       FileUtils.mkdir_p(File.join(harness, 'clients/rust'))
       File.write(File.join(harness, 'clients/rust/Gemfile.lock'), "controlled Rust lock\n")
+      stub_const('HaveAPI::RustClient::VERSION', HaveAPI::VERSION) unless defined?(HaveAPI::RustClient::VERSION)
       stub_const('HaveAPI::Performance::ROOT', harness)
       ordinary = JSON.parse(JSON.generate(HaveAPI::Performance::Worker.inputs(root, 'quick')))
       preparation = ordinary.fetch('json_preparation')
@@ -278,9 +279,9 @@ describe HaveAPI::Performance::Release do
   end
 
   def served_html
-    server = HaveAPI::DocumentationPerformanceFixture.build(resource_count: 1, actions_per_resource: 1)
-    response = Rack::MockRequest.new(server.app).get('http://example.test/benchmark/api/v1/',
-                                                     'HTTP_HOST' => 'example.test', 'HTTP_AUTHORIZATION' => "Basic #{Base64.strict_encode64('admin:fixture-only')}")
+    server = HaveAPI::DocumentationPerformanceFixture.build(resource_count: 1, actions_per_resource: 1, documentation_oauth: true)
+    response = Rack::MockRequest.new(server.app).get("#{server.fixture_documentation_oauth.origin}/benchmark/api/v1/",
+                                                     'HTTP_HOST' => 'example.test', 'HTTP_COOKIE' => server.fixture_documentation_cookie('admin'))
     expect(response.status).to eq(200)
     response.body
   end

data/spec/performance/runner_spec.rb

@@ -467,6 +467,7 @@ describe HaveAPI::Performance::Worker do
         expect(retained['cases'].map { |item| item['iterations'] }).to all(eq(expensive ? 1 : 4))
         expect(retained['cases'].map { |item| item['pilot']['baseline_batch_seconds'] }).to all(eq(expensive ? 2.0 : 1.0))
         requests.each do |label, request|
+          expect(request['benchmark']).to be(true)
           next if %w[pilot calibration].include?(label)
 
           expect(request['counts'].values).to all(eq(expensive ? 1 : 4))

data/test_support/all_client_performance_fixture.rb

@@ -9,13 +9,7 @@ module HaveAPI
       query_parameter '_auth_token'
     end
 
-    class OAuthConfig < Authentication::OAuth2::Config
-      def base_url
-        'http://example.test'
-      end
-    end
-
-    def self.build(resources:)
+    def self.build(resources:, actions: 2)
       definitions = Module.new
       resources.times do |index|
         resource = Class.new(HaveAPI::Resource)
@@ -23,7 +17,8 @@ module HaveAPI
         resource.resource_name = "Resource#{index}"
         resource.version 1
         resource.route "resources#{index}"
-        %w[Public Protected].each { |name| add_action(resource, name) }
+        names = %w[Public Protected] + (2...actions).map { |i| "Action#{i}" }
+        names.each { |name| add_action(resource, name) }
         DocumentationPerformanceFixture.send(:add_admin_action, resource) if index == 0
       end
       server = HaveAPI::Server.new(definitions)
@@ -31,12 +26,13 @@ module HaveAPI
       server.default_version = 1
       server.auth_chain << DocumentationPerformanceFixture::BasicProvider
       server.auth_chain << Authentication::Token.with_config(TokenConfig)
-      server.auth_chain << Authentication::OAuth2.with_config(OAuthConfig)
+      fixture = DocumentationPerformanceFixture.configure_documentation_oauth(server)
       server.documentation_clients(1,
                                    go: { import_path: 'example.test/performance/client' },
                                    rust: { crate_name: 'performance_client' },
                                    typescript: { package_name: 'performance-client' })
       server.mount('/benchmark/api/')
+      DocumentationPerformanceFixture.attach_documentation_headers(server, fixture)
       server
     end
 
@@ -44,7 +40,7 @@ module HaveAPI
       resource.define_action(name) do
         route name.downcase
         http_method :post
-        auth name == 'Protected'
+        auth name != 'Public'
         input(:hash) do
           string :value
           bool :enabled

data/test_support/documentation_oauth_fixture.rb

@@ -0,0 +1,54 @@
+require 'digest'
+require 'rack/response'
+require 'haveapi'
+
+# Real documentation cookies and provider lookup for specs and benchmarks.
+class DocumentationOAuthFixture
+  CookieHandler = Struct.new(:response)
+
+  attr_reader :origin, :lookups
+
+  def self.configure(server, users:, origin: 'https://example.org', mount_path: '/')
+    fixture = new(users, origin)
+    fixture.configure(server, mount_path)
+    fixture
+  end
+
+  def initialize(users, origin)
+    @users = users
+    @origin = origin
+    @lookups = []
+    @expires_at = Time.now.to_f + 3600
+  end
+
+  def configure(server, mount_path)
+    fixture = self
+    config = Class.new(HaveAPI::Authentication::OAuth2::Config) do
+      define_method(:base_url) { fixture.origin }
+      define_method(:find_user_by_access_token) do |request, token|
+        fixture.find_user(@version, request, token)
+      end
+    end
+    server.auth_chain << HaveAPI::Authentication::OAuth2.with_config(config)
+    server.documentation_oauth(
+      client_id: 'documentation-fixture', client_secret: 'documentation-fixture-client-secret',
+      session_secret: 'documentation-fixture-session-secret-' * 3,
+      redirect_uri: "#{origin}#{mount_path.chomp('/')}/_documentation/oauth/callback"
+    )
+  end
+
+  def find_user(version, _request, token)
+    @lookups << [version, token]
+    @users.fetch(version, {})[token]
+  end
+
+  def header_for(server, version:, token:)
+    @users.fetch(version).fetch(token)
+    handler = CookieHandler.new(Rack::Response.new)
+    server.documentation_oauth.send(:write_cookie, handler, 'session', {
+                                     'token' => token, 'expires' => @expires_at,
+                                     'csrf' => Digest::SHA256.hexdigest("documentation-fixture-csrf:#{token}")
+                                   })
+    Array(handler.response.headers['set-cookie']).fetch(0).split(';', 2).first
+  end
+end

data/test_support/documentation_performance_fixture.rb

@@ -14,7 +14,7 @@ module HaveAPI
     end
 
     def self.build(resource_count: 4, actions_per_resource: 2, samples_per_action: 1,
-                   parameters_per_action: 2, rust: false)
+                   parameters_per_action: 2, rust: false, documentation_oauth: false)
       dimensions = [resource_count, actions_per_resource, samples_per_action, parameters_per_action]
       unless dimensions.all? { |value| value.is_a?(Integer) && value > 0 }
         raise ArgumentError, 'Fixture dimensions must be positive integers'
@@ -41,10 +41,28 @@ module HaveAPI
       if rust
         server.documentation_clients(1, rust: { crate_name: 'documentation_performance_client' })
       end
+      fixture = configure_documentation_oauth(server) if documentation_oauth
       server.mount('/benchmark/api/')
+      attach_documentation_headers(server, fixture) if fixture
       server
     end
 
+    def self.configure_documentation_oauth(server)
+      require_relative 'documentation_oauth_fixture'
+      users = %w[admin member].to_h { |role| ["documentation-#{role}", User.new(role)] }
+      DocumentationOAuthFixture.configure(server, users: { 1 => users }, origin: 'https://example.test', mount_path: '/benchmark/api/')
+    end
+
+    def self.attach_documentation_headers(server, fixture)
+      # Mint once during setup. Each page still decrypts and validates the real
+      # token; deterministic per-role CSRF preserves repeated HTML body proof.
+      cookies = %w[admin member].to_h do |role|
+        [role, fixture.header_for(server, version: 1, token: "documentation-#{role}")]
+      end
+      server.define_singleton_method(:fixture_documentation_oauth) { fixture }
+      server.define_singleton_method(:fixture_documentation_cookie) { |role| cookies.fetch(role) }
+    end
+
     def self.add_action(resource, index, samples, parameters)
       resource.define_action("Action#{index}") do
         route "actions#{index}"