haveapi 0.30.1 → 0.31.0

data/spec/performance/sqlite_spec.rb

@@ -0,0 +1,194 @@
+require 'spec_helper'
+require_relative '../../test_support/performance_sqlite_fixture'
+require_relative '../../benchmarks/endpoints'
+
+describe HaveAPI::PerformanceFixtures::SQLite do
+  def with_scenario(id: 'sqlite.includes', **dimensions)
+    scenario = described_class.build(id:, dimensions:)
+    yield scenario
+  ensure
+    scenario&.close
+  end
+
+  def run_operations(scenario, count = 2)
+    scenario.reset!(iterations: count)
+    responses = Array.new(count) { scenario.call }
+    responses.each_with_index { |response, index| scenario.validate!(response, index:) }
+    [responses, scenario.counters.fetch(:operations)]
+  end
+
+  it 'reuses only SQLite body semantics while checking every query, authorization and called index' do
+    with_scenario(rows: 32, include_depth: 2, user: 'member') do |scenario|
+      allow(scenario).to receive(:validate_body!).and_call_original
+      worker = HaveAPI::Performance::Worker.new({})
+      result = worker.measure(scenario, 4)
+      expect(result[:bodies].length).to eq(1)
+      expect(scenario).to have_received(:validate_body!).once
+      %i[queries authorizations executions].each do |counter|
+        calls = 0
+        allow(scenario).to receive(:call).and_wrap_original do |call|
+          response = call.call
+          calls += 1
+          scenario.instance_variable_get(:@operations)[1][counter] += 1 if calls == 2
+          response
+        end
+        expect { worker.measure(scenario, 3) }.to raise_error(/operation counters/)
+      end
+      scenario.reset!(iterations: 2)
+      response = scenario.call
+      expect { scenario.validate!(response, index: 1) { raise 'body validator must not run' } }.to raise_error(ArgumentError, /uncalled/)
+    end
+  end
+
+  it 'exposes unique stable quick/weekly cases and rejects unsupported shapes' do
+    quick = described_class.cases
+    expect(quick).to eq([{ id: 'sqlite.page', dimensions: { rows: 128, page_size: 32 } },
+                         { id: 'sqlite.includes', dimensions: { rows: 32, include_depth: 2 } }])
+    weekly = described_class.cases(profile: 'weekly')
+    expect(weekly.uniq).to eq(weekly)
+    expect(weekly).to include(id: 'sqlite.includes', dimensions: { rows: 1024, include_depth: 2, user: 'member' })
+    expect { described_class.cases(profile: 'missing') }.to raise_error(ArgumentError)
+    expect { described_class.build(id: 'missing', dimensions: { rows: 1 }) }.to raise_error(ArgumentError)
+    expect { described_class.build(id: 'sqlite.page', dimensions: { rows: 1024, page_size: 1024 }) }.to raise_error(ArgumentError)
+  end
+
+  [32, 128, 1024].each do |rows|
+    it "keeps a fixed 32-row page at one real uncached query over #{rows} rows" do
+      with_scenario(id: 'sqlite.page', rows:, page_size: 32) do |scenario|
+        responses, counts = run_operations(scenario)
+        expect(counts).to eq(Array.new(2) { { queries: 1, authorizations: 1, executions: 1 } })
+        values = JSON.parse(responses.first.body).fetch('response').fetch('items')
+        expect(values.map { |item| item.fetch('id') }).to eq((1..32).to_a)
+        expect(values.first).to include('label' => '', 'enabled' => false, 'count' => 0, 'note' => nil)
+      end
+    end
+  end
+
+  [1, 32, 128].product([1, 2]).each do |rows, depth|
+    it "bounds explicit depth #{depth} includes to #{depth + 1} queries for #{rows} rows while retaining row authorization" do
+      with_scenario(rows:, include_depth: depth) do |scenario|
+        responses, counts = run_operations(scenario)
+        expected = { queries: depth + 1, authorizations: 1 + (rows * depth), executions: 1 }
+        expect(counts).to eq([expected, expected])
+        groups = JSON.parse(responses.first.body).fetch('response').fetch('items').map { |item| item.fetch('group') }
+        expect(groups).to all(include('_meta' => include('resolved' => true)))
+        expect(groups.first).to have_key('account') if depth == 2
+        expect(groups.first).not_to have_key('account') if depth == 1
+      end
+    end
+  end
+
+  it 'applies the real ascending cursor before the fixed page limit' do
+    with_scenario(id: 'sqlite.page', rows: 128, page_size: 32) do |scenario|
+      path = scenario.instance_variable_get(:@path)
+      scenario.instance_variable_set(:@path, path.sub('from_id%5D=0', 'from_id%5D=32'))
+      response = scenario.call
+      expect(response.status).to eq(200)
+      body = JSON.parse(response.body)
+      expect(body.fetch('status')).to be(true)
+      expect(body.fetch('response').fetch('items').map { |item| item.fetch('id') }).to eq((33..64).to_a)
+      expect(scenario.counters.fetch(:operations)).to eq([{ queries: 1, authorizations: 1, executions: 1 }])
+    end
+  end
+
+  it 'keeps fixed-page allocation work independent of unreturned table rows' do
+    allocations = [32, 1024].map do |rows|
+      with_scenario(id: 'sqlite.page', rows:, page_size: 32) do |scenario|
+        2.times { run_operations(scenario, 1) }
+        3.times.map do
+          scenario.reset!(iterations: 3)
+          responses = Array.new(3)
+          GC.start
+          before = GC.stat(:total_allocated_objects)
+          3.times { |index| responses[index] = scenario.call }
+          count = GC.stat(:total_allocated_objects) - before
+          responses.each_with_index { |response, index| scenario.validate!(response, index:) }
+          count
+        end.min
+      end
+    end
+    # Ruby 3.4.11 calibration observed 2620 objects/request at every table size.
+    # Fixed slack accommodates VM bookkeeping while rejecting table-sized work.
+    expect(allocations.last - allocations.first).to be <= (128 * 3)
+  end
+
+  it 'serializes 1024 rows without passing an invalid pagination limit' do
+    with_scenario(rows: 1024, include_depth: 2) do |scenario|
+      responses, counts = run_operations(scenario, 1)
+      expect(JSON.parse(responses.first.body).fetch('response').fetch('items').length).to eq(1024)
+      expect(counts).to eq([{ queries: 3, authorizations: 2049, executions: 1 }])
+    end
+  end
+
+  it 'keeps member association decisions and hidden values isolated between administrator requests' do
+    with_scenario(rows: 32, include_depth: 2, user: 'admin') do |admin|
+      with_scenario(rows: 32, include_depth: 2, user: 'member') do |member|
+        first, = run_operations(admin, 1)
+        restricted, counts = run_operations(member, 1)
+        restored, = run_operations(admin, 1)
+        expect(restored.first.body).to eq(first.first.body)
+        expect(first.first.body).to include('GROUP_SECRET_2', 'ACCOUNT_SECRET_3')
+        expect(restricted.first.body).not_to include('GROUP_SECRET', 'ACCOUNT_SECRET', '"label":"group2"', '"label":"account3"')
+        items = JSON.parse(restricted.first.body).fetch('response').fetch('items')
+        denied = { '_meta' => { 'resolved' => false, 'authorized' => false } }
+        expect(items[1].fetch('group')).to eq(denied)
+        expect(items[2].fetch('group').fetch('account')).to eq(denied)
+        expect(counts).to eq([{ queries: 3, authorizations: 49, executions: 1 }])
+      end
+    end
+  end
+
+  it 'rechecks administrator/member permissions on one app and pool across repeated requests' do
+    with_scenario(rows: 32, include_depth: 2) do |scenario|
+      results = %w[admin member admin].map do |user|
+        scenario.instance_variable_set(:@user, user)
+        scenario.instance_variable_get(:@headers)['HTTP_AUTHORIZATION'] =
+          "Basic #{Base64.strict_encode64("#{user}:fixture-only")}"
+        run_operations(scenario, 1).first.first
+      end
+      expect(results.last.body).to eq(results.first.body)
+      expect(results[1].body).not_to include('GROUP_SECRET', 'ACCOUNT_SECRET')
+    end
+  end
+
+  it 'resets operation records, validates every response and rejects incomplete/extra calls' do
+    with_scenario(rows: 1, include_depth: 2) do |scenario|
+      scenario.reset!(iterations: 2)
+      first = scenario.call
+      expect { scenario.counters }.to raise_error(/incomplete/)
+      second = scenario.call
+      expect(scenario.validate!(first, index: 0)[:body_sha256]).to eq(Digest::SHA256.hexdigest(first.body))
+      expect(scenario.validate!(second, index: 1)[:canonical_body]).to eq(JSON.parse(second.body))
+      expect { scenario.validate!(first, index: -1) }.to raise_error(ArgumentError)
+      expect { scenario.call }.to raise_error(/beyond/)
+      scenario.reset!(iterations: 1)
+      expect { scenario.validate!(first, index: 0) }.to raise_error(ArgumentError, /uncalled/)
+      response = scenario.call
+      scenario.validate!(response, index: 0)
+      wrong = response.dup
+      allow(wrong).to receive(:body).and_return(response.body.sub('group1', 'wrong!'))
+      expect { scenario.validate!(wrong, index: 0) }.to raise_error(/rows or values/)
+      expect { scenario.reset!(iterations: 0) }.to raise_error(ArgumentError)
+    end
+  end
+
+  it 'owns a separate connection without changing the global ActiveRecord base or another scenario' do
+    original_connected = ActiveRecord::Base.connected?
+    original_pool = ActiveRecord::Base.connection_pool if original_connected
+    first = described_class.build(id: 'sqlite.includes', dimensions: { rows: 1, include_depth: 2 })
+    second = described_class.build(id: 'sqlite.includes', dimensions: { rows: 32, include_depth: 2 })
+    first_pool = first.instance_variable_get(:@base).connection_pool
+    second_pool = second.instance_variable_get(:@base).connection_pool
+    expect(first_pool).not_to equal(second_pool)
+    expect(ActiveRecord::Base.connected?).to eq(original_connected)
+    expect(ActiveRecord::Base.connection_pool).to equal(original_pool) if original_pool
+    first.close
+    expect(first_pool.connected?).to be(false)
+    expect { first.call }.to raise_error(/closed/)
+    _responses, counts = run_operations(second, 1)
+    expect(counts.first).to eq(queries: 3, authorizations: 65, executions: 1)
+  ensure
+    first&.close
+    second&.close
+  end
+end

data/spec/performance/support/live_worker.rb

@@ -0,0 +1,44 @@
+# Isolated positive controls. No defect switch enters the benchmark CLI/runtime.
+require_relative '../../../benchmarks/endpoints'
+
+control = ARGV.fetch(0)
+spec = if %w[query sqlite-clean].include?(control)
+         { id: 'sqlite.page', dimensions: { rows: 128, page_size: 32 } }
+       else
+         { id: 'api.public_get', dimensions: {} }
+       end
+HaveAPI::Performance::Worker.define_singleton_method(:inventory) { |_profile| [spec] }
+# These test-only fault controls use the actual resolved server bundle from
+# ordinary RSpec CI. The production worker's root/component input contract is
+# unchanged and is tested separately; it has no optional lock fallback.
+HaveAPI::Performance::Worker.define_singleton_method(:inputs) do |source, _profile|
+  { manifests: { 'servers/ruby/Gemfile' => Digest::SHA256.file(File.join(source, 'servers/ruby/Gemfile')).hexdigest },
+    locks: { 'servers/ruby/Gemfile.lock' => Digest::SHA256.file(File.join(HaveAPI::Performance::ROOT, 'servers/ruby/Gemfile.lock')).hexdigest } }
+end
+HaveAPI::Performance::Worker.singleton_class.prepend(Module.new do
+  define_method(:build) do |selected|
+    super(selected).tap do |scenario|
+      if control == 'query'
+        scenario.singleton_class.prepend(Module.new do
+          def execute_record
+            super
+            @base.connection.select_value('SELECT 1')
+          end
+        end)
+      elsif %w[allocation wrong-output].include?(control)
+        scenario.singleton_class.prepend(Module.new do
+          define_method(:call) do
+            Array.new(4000) { Object.new } if control == 'allocation'
+            response = super()
+            if control == 'wrong-output'
+              Rack::MockResponse.new(200, response.headers, response.body.sub('item-1', 'wrong-item'))
+            else
+              response
+            end
+          end
+        end)
+      end
+    end
+  end
+end)
+exit HaveAPI::Performance::CLI.new(['worker']).execute

data/spec/performance/support/samples.rb

@@ -0,0 +1,72 @@
+require 'json'
+require 'digest'
+require_relative '../../../benchmarks/performance_compare'
+
+module PerformanceSamples
+  def self.fixture(profile: 'quick', zero: 0)
+    identity = HaveAPI::Performance::Identity
+    policy = HaveAPI::Performance::PROFILES.fetch(profile)
+    baseline_sha = profile == 'weekly' ? HaveAPI::Performance::REFERENCE : 'a' * 40
+    body = JSON.generate(status: true, response: { zero:, no: false, empty: '', null: nil })
+    digest = Digest::SHA256.hexdigest(body)
+    output = { 'http_status' => 200, 'envelope_status' => true, 'body_bytes' => body.bytesize,
+               'body_sha256' => digest, 'canonical_sha256' => identity.digest(JSON.parse(body)), 'count' => 1 }
+    sample = { 'operations' => 1, 'wall_seconds' => 2.0, 'cpu_seconds' => 2.0, 'allocated_objects' => 100,
+               'outputs' => [output], 'bodies' => { digest => { 'body' => body, 'canonical_body' => JSON.parse(body) } },
+               'counters' => { 'operations' => 1, 'record' => { 'queries' => 0, 'authorizations' => 1, 'executions' => 1 } } }
+    spec = { 'id' => 'api.public_get', 'dimensions' => {} }
+    environment = { 'ruby' => { 'version' => 'controlled-detector-trace' }, 'gems' => { 'test' => 'controlled' } }
+    fixtures = { 'controlled' => 'f' * 64 }
+    preparation = HaveAPI::Performance::Release.json_preparation(HaveAPI::Performance::Release::JSON_GEMFILES.to_h { |path| [path, "source 'https://rubygems.org'\n"] })
+    inputs = { 'locks' => { 'Gemfile.lock' => 'a' * 64 }, 'manifests' => preparation.fetch('normalized_sha256'), 'json_preparation' => preparation }
+    sources = %w[baseline candidate].each_with_index.to_h do |role, index|
+      [role, { 'root' => "/controlled/#{role}", 'sha' => index == 0 ? baseline_sha : 'b' * 40,
+               'tree' => 'c' * 40, 'tracked_files' => 1, 'files_sha256' => { 'server.rb' => 'd' * 64 }.merge(preparation.fetch('raw_sha256')) }]
+    end
+    observations = sources.flat_map do |role, source|
+      %w[forward reverse].map do |order|
+        [order == 'forward' ? role : "#{role}-reverse",
+         { 'source' => source.merge('loaded_sources' => { 'server.rb' => 'd' * 64 }),
+           'environment' => environment, 'fixture_sha256' => fixtures, 'inputs' => inputs,
+           'runtime_policy' => HaveAPI::Performance::RUNTIME_POLICY, 'workload_order' => order,
+           'host' => { 'hostname' => 'controlled', 'os' => 'controlled', 'cpu' => 'controlled' } }]
+      end
+    end
+    observations = observations.to_h
+    pair = lambda do |index, self_pair|
+      { 'order' => if self_pair
+                     %w[baseline baseline]
+                   else
+                     (index.even? ? %w[baseline candidate] : %w[candidate baseline])
+                   end,
+        'workload_order' => index.even? ? 'forward' : 'reverse',
+        'baseline' => sample.merge('observation' => index.even? ? 'baseline' : 'baseline-reverse'),
+        'candidate' => sample.merge('observation' => "#{self_pair ? 'baseline' : 'candidate'}#{'-reverse' unless index.even?}") }
+    end
+    budget = { 'schema_version' => 1, 'reference_sha' => HaveAPI::Performance::REFERENCE, 'environment' => { profile => environment, 'weekly' => environment },
+               'calibration' => { profile => { 'source_sha' => HaveAPI::Performance::REFERENCE, 'raw_sha256' => 'f' * 64,
+                                               'warmup_batches' => 2, 'iterations' => 1, 'fixture_sha256' => fixtures, 'inputs' => inputs } },
+               'profiles' => { profile => [spec.merge('reference_allocations' => 100, 'allocation_ceiling' => 157,
+                                                      'counters' => sample['counters']['record'])] } }
+    budget_json = JSON.generate(budget)
+    samples = { 'schema_version' => HaveAPI::Performance::SAMPLE_SCHEMA, 'profile' => profile, 'baseline_sha' => baseline_sha, 'candidate_sha' => 'b' * 40,
+                'harness_sha256' => 'e' * 64, 'fixture_sha256' => fixtures,
+                'budget_sha256' => Digest::SHA256.hexdigest(budget_json), 'environment' => environment,
+                'inputs' => HaveAPI::Performance::Release.graph(inputs), 'sources' => sources, 'observations' => observations, 'inventory' => [spec],
+                'cases' => [spec.merge('iterations' => 1, 'self_pairs' => Array.new(policy[:self_pairs]) { |i| pair.call(i, true) },
+                                       'pairs' => Array.new(policy[:pairs]) { |i| pair.call(i, false) })] }
+    HaveAPI::Performance.complex_cases(profile).each do |complex|
+      samples['inventory'] << complex
+      entry = Marshal.load(Marshal.dump(samples['cases'].first.merge(complex)))
+      (entry['self_pairs'] + entry['pairs']).each do |pair|
+        %w[baseline candidate].each do |role|
+          record = pair[role]['counters']['record']
+          record['executions'] = 0
+          record['authorizations'] = (complex['dimensions']['resources'] * complex['dimensions']['actions']) + 1
+        end
+      end
+      samples['cases'] << entry
+    end
+    [JSON.parse(JSON.generate(samples)), budget_json]
+  end
+end

data/test_support/documentation_performance_fixture.rb

@@ -0,0 +1,106 @@
+require 'haveapi'
+
+module HaveAPI
+  # Shared by deterministic specs and the opt-in documentation benchmark.
+  module DocumentationPerformanceFixture
+    User = Struct.new(:login)
+
+    class BasicProvider < HaveAPI::Authentication::Basic::Provider
+      protected
+
+      def find_user(_request, username, password)
+        User.new(username) if %w[admin member].include?(username) && password == 'fixture-only'
+      end
+    end
+
+    def self.build(resource_count: 4, actions_per_resource: 2, samples_per_action: 1,
+                   parameters_per_action: 2, rust: 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'
+      end
+
+      resources = Module.new
+      resource_count.times do |index|
+        resource = Class.new(HaveAPI::Resource)
+        resources.const_set("Resource#{index}", resource)
+        resource.resource_name = "Resource#{index}"
+        resource.version 1
+        resource.route "resources#{index}"
+        resource.desc "Synthetic resource #{index}"
+        actions_per_resource.times do |action_index|
+          add_action(resource, action_index, samples_per_action, parameters_per_action)
+        end
+        add_admin_action(resource) if index == 0
+      end
+
+      server = HaveAPI::Server.new(resources)
+      server.use_version(1)
+      server.default_version = 1
+      server.auth_chain << BasicProvider
+      if rust
+        server.documentation_clients(1, rust: { crate_name: 'documentation_performance_client' })
+      end
+      server.mount('/benchmark/api/')
+      server
+    end
+
+    def self.add_action(resource, index, samples, parameters)
+      resource.define_action("Action#{index}") do
+        route "actions#{index}"
+        http_method :post
+        auth true
+        desc "Synthetic action #{index}"
+        input(:hash) do
+          parameters.times { |i| string :"value#{i}" }
+          custom :payload
+          bool :enabled
+          integer :count
+          string :nullable, nullable: true
+          string :admin_field, default: 'ADMIN_ONLY_DEFAULT'
+        end
+        output(:hash) do
+          string :marker
+          custom :payload
+          string :admin_field
+        end
+        authorize do |user|
+          if user && user.login != 'admin'
+            input blacklist: [:admin_field]
+            output blacklist: [:admin_field]
+          end
+          allow
+        end
+
+        samples.times do |sample_index|
+          example "Public sample #{sample_index}" do
+            request({ value0: '', enabled: false, count: 0, nullable: nil,
+                      payload: { 'nested' => [{ 'values' => [0, false, '', nil] }] } })
+            response({ marker: "PUBLIC_SAMPLE_#{sample_index}", payload: { 'items' => [false, 0, nil, ''] } })
+          end
+        end
+        example 'Admin sample' do
+          authorize { |user| user.login == 'admin' }
+          request({ admin_field: 'ADMIN_ONLY_REQUEST' })
+          response({ admin_field: 'ADMIN_ONLY_RESPONSE' })
+        end
+      end
+    end
+    private_class_method :add_action
+
+    def self.add_admin_action(resource)
+      resource.define_action(:AdminOnly) do
+        route 'admin-only'
+        http_method :get
+        auth true
+        desc 'ADMIN_ONLY_ACTION'
+        output(:hash) { string :admin_result }
+        authorize { |user| user && user.login == 'admin' ? allow : deny }
+        example 'Admin action sample' do
+          response({ admin_result: 'ADMIN_ONLY_ACTION_SAMPLE' })
+        end
+      end
+    end
+    private_class_method :add_admin_action
+  end
+end