haveapi 0.31.2 → 0.32.1

data/spec/documentation/oauth_transport_spec.rb

@@ -0,0 +1,45 @@
+require 'spec_helper'
+
+describe HaveAPI::DocumentationOAuth::Transport do
+  let(:uri) { URI('https://issuer.example/token') }
+  let(:http) { instance_double(Net::HTTP) }
+  let(:response) { instance_double(Net::HTTPOK, code: '200') }
+
+  before do
+    allow(Net::HTTP).to receive(:start).and_yield(http)
+    allow(http).to receive(:max_retries=)
+    allow(http).to receive(:request).and_yield(response)
+    allow(response).to receive(:read_body).and_yield('{}')
+  end
+
+  it 'requires verified HTTPS with bounded timeouts and sends credentials only in the body' do
+    expect(described_class.new.post(uri, 'client_secret' => 'private')).to eq('{}')
+    expect(Net::HTTP).to have_received(:start).with('issuer.example', 443,
+                                                    use_ssl: true, verify_mode: OpenSSL::SSL::VERIFY_PEER,
+                                                    open_timeout: 5, read_timeout: 10, write_timeout: 10)
+    expect(http).to have_received(:max_retries=).with(0)
+    expect(http).to have_received(:request) do |request|
+      expect(request.uri.to_s).to eq('https://issuer.example/token')
+      expect(request.body).to eq('client_secret=private')
+    end
+  end
+
+  it 'rejects redirects without following them or exposing their body' do
+    allow(response).to receive(:code).and_return('302')
+    allow(response).to receive(:read_body).and_yield('PRIVATE_PROVIDER_BODY')
+    expect { described_class.new.post(uri, {}) }.to raise_error(HaveAPI::DocumentationOAuth::Failure, 'Documentation OAuth request failed')
+    expect(http).to have_received(:request).once
+  end
+
+  it 'bounds the body while streaming rather than reading an unbounded response' do
+    allow(response).to receive(:read_body).and_yield('x' * 8192).and_yield('x' * 8193)
+    expect { described_class.new.post(uri, {}) }.to raise_error(HaveAPI::DocumentationOAuth::Failure)
+  end
+
+  it 'converts TLS and DNS failures into generic authentication failure' do
+    [OpenSSL::SSL::SSLError.new('PRIVATE_TLS_DETAIL'), SocketError.new('PRIVATE_DNS_DETAIL')].each do |error|
+      allow(Net::HTTP).to receive(:start).and_raise(error)
+      expect { described_class.new.post(uri, {}) }.to raise_error(HaveAPI::DocumentationOAuth::Failure, 'Documentation OAuth request failed')
+    end
+  end
+end

data/spec/documentation/performance_spec.rb

@@ -4,10 +4,24 @@ require_relative '../../test_support/documentation_performance_fixture'
 
 describe HaveAPI::Server, '#mount' do
   let(:server) do
-    HaveAPI::DocumentationPerformanceFixture.build(resource_count: 3, actions_per_resource: 2)
+    HaveAPI::DocumentationPerformanceFixture.build(resource_count: 3, actions_per_resource: 2, documentation_oauth: true)
   end
   let(:contexts) { [] }
   let(:help_inputs) { [] }
+  let(:resource_derivations) { [] }
+
+  around do |example|
+    trace = TracePoint.new(:call) do |call|
+      next unless call.defined_class == HaveAPI::ClientExample::Context && call.method_id == :normalize
+      next unless call.binding.local_variable_get(:field) == :resource
+
+      value = call.binding.local_variable_get(:value)
+      resource_derivations << value if value
+    end
+    trace.enable { example.run }
+  ensure
+    trace&.disable
+  end
 
   before do
     HaveAPI::ClientExample.clients.each do |client|
@@ -25,19 +39,24 @@ describe HaveAPI::Server, '#mount' do
 
   def request_as(user)
     contexts.clear
+    resource_derivations.clear
     Rack::MockRequest.new(server.app).get(
-      '/benchmark/api/v1/', 'HTTP_HOST' => 'example.test',
-                            'HTTP_AUTHORIZATION' => "Basic #{Base64.strict_encode64("#{user}:fixture-only")}"
+      "#{server.fixture_documentation_oauth.origin}/benchmark/api/v1/?resource=resource0", 'HTTP_HOST' => 'example.test',
+                                                                                           'HTTP_COOKIE' => server.fixture_documentation_cookie(user)
     )
   end
 
   def expect_shared_request(response)
     expect(response.status).to eq(200)
     expect(response.body).to include('PUBLIC_SAMPLE_0', 'example-resource0-action0-0',
-                                     'init-javascript-callback', 'init-javascript-async',
-                                     'init-typescript-callback', 'init-typescript-async',
-                                     'init-python-sync', 'init-python-async')
+                                     'data-client="javascript-callback"', 'data-client="javascript-async"',
+                                     'data-client="typescript-callback"', 'data-client="typescript-async"',
+                                     'data-client="python-sync"', 'data-client="python-async"')
+    expect(response.body).not_to include('id="example-resource1-', 'id="example-resource2-', 'init-examples')
     expect(contexts.length).to be > 20
+    expect(contexts.map(&:resource_path).uniq).to eq([['resource0']])
+    expect(contexts.map { |context| context.resource.__id__ }.uniq.length).to eq(1)
+    expect(resource_derivations.length).to eq(1)
     description = contexts.first.description
     contexts.each { |context| expect(context.description).to equal(description) }
     expect(description).to be_frozen
@@ -76,4 +95,26 @@ describe HaveAPI::Server, '#mount' do
       expect(help[:resources]['resource0'][:actions]['action0'][:examples].first[:request]).not_to be_frozen
     end
   end
+
+  it 'does not alias distinct raw resources at the same canonical path' do
+    helper = Object.new
+    helper.extend(HaveAPI::Server::ServerHelpers)
+    parent = HaveAPI::ClientExample::Context.new(version: 1, host: 'example.test',
+                                                 base_url: 'http://example.test/', version_url: 'http://example.test/v1/',
+                                                 description: {})
+    helper.instance_variable_set(:@documentation_context, parent)
+    first = { actions: { 'show' => { description: 'first' } }, resources: {} }
+    second = { actions: { 'show' => { description: 'second' } }, resources: {} }
+    before = Marshal.dump([first, second])
+    a = helper.documentation_context(resource_path: [:widget], resource: first)
+    b = helper.documentation_context(resource_path: ['widget'], resource: first, detail: :thorough)
+    c = helper.documentation_context(resource_path: ['widget'], resource: second)
+    expect(a.resource).to equal(b.resource)
+    expect(a.resource).not_to equal(c.resource)
+    expect(a.resource).not_to equal(first)
+    expect(a.description).to equal(c.description)
+    expect(a.resource[:actions]['show'][:description]).to eq('first')
+    expect(c.resource[:actions]['show'][:description]).to eq('second')
+    expect(Marshal.dump([first, second])).to eq(before)
+  end
 end

data/spec/documentation/reference_headings_spec.rb

@@ -0,0 +1,190 @@
+require 'spec_helper'
+
+module DocumentationReferenceSpec
+  module AuthenticationResources
+    class Session < HaveAPI::Resource
+      version :all
+      auth false
+      class Show < HaveAPI::Action
+        route ''
+        http_method :get
+        input(:hash) { string :token }
+        output(:hash) { string :token }
+        authorize { allow }
+        # rubocop:disable RSpec/NoExpectationExample
+        example 'provider sample' do
+          request(token: 'visible')
+          response(token: 'visible')
+        end
+        # rubocop:enable RSpec/NoExpectationExample
+      end
+    end
+  end
+
+  class FirstProvider < HaveAPI::Authentication::Base
+    auth_method :first
+    def register_routes(_sinatra, _prefix)
+      @server.routes[@version] ||= { authentication: {} }
+      @server.routes[@version][:authentication][name] = { resources: {} }
+    end
+
+    def resource_module
+      AuthenticationResources
+    end
+  end
+
+  class SecondProvider < FirstProvider
+    auth_method :second
+    def resource_module
+      AuthenticationResources
+    end
+  end
+end
+
+describe HaveAPI::DocumentationHelpers, '#render_version_documentation' do
+  api do
+    define_resource(:Parent) do
+      version 1
+      auth false
+      define_action(:Index) do
+        route ''
+        http_method :get
+        authorize { allow }
+      end
+      define_action(:Show) do
+        route '{parent_id}'
+        http_method :get
+        output(:hash) { string :value }
+        authorize { allow }
+        # rubocop:disable RSpec/NoExpectationExample
+        example '<Example>&' do
+          path_params 1
+          response(value: 'visible')
+        end
+        # rubocop:enable RSpec/NoExpectationExample
+      end
+      define_resource(:Child) do
+        define_action(:Show) do
+          route '{child_id}'
+          http_method :get
+          authorize { allow }
+        end
+        define_resource(:Grandchild) do
+          define_action(:Show) do
+            route '{grandchild_id}'
+            http_method :get
+            authorize { allow }
+          end
+        end
+      end
+    end
+  end
+  default_version 1
+
+  def ids(body)
+    body.scan(/\sid="([^"]+)"/).flatten
+  end
+
+  def assert_fragments(body)
+    body.scan(/<a[^>]*\shref="#([^"]+)"/).flatten.each do |target|
+      expect(ids(body).count(target)).to eq(1), target
+    end
+  end
+
+  def reference(**options)
+    Object.new.extend(described_class).documentation_reference_anchor(**options)
+  end
+
+  it 'encodes typed provider/resource/action/section/example tuples without delimiter collisions' do
+    arguments = { resource_path: %w[a-b c], action_name: 'show', section: :input }
+    target = reference(**arguments)
+    expect(target).to eq(reference(**arguments))
+    expect(JSON.parse([target.delete_prefix('reference-')].pack('H*'))).to eq([nil, %w[a-b c], 'show', 'input', nil])
+    alternatives = [reference(**arguments, authentication: :first), reference(**arguments, authentication: :second),
+                    reference(**arguments, resource_path: %w[a b-c]), reference(**arguments, section: :output),
+                    reference(**arguments, example_index: 0), reference(**arguments, example_index: 1)]
+    expect([target, *alternatives].uniq.length).to eq(7)
+    expect(reference(resource_path: ['žluťoučký'], section: :examples)).to match(/\Areference-[0-9a-f]+\z/)
+  end
+
+  it 'provides native per-action sections including empty input/output and titled examples' do
+    get '/v1/?resource=parent'
+    expect(last_response).to be_ok
+    body = last_response.body
+    expect(body).to include('data-doc-nav-owner="root-parent-index"', 'data-doc-primary href="#root-parent-index"',
+                            'data-doc-subnav="root-parent-index"', 'data-doc-subsection', 'No parameters.',
+                            'aria-label="Link to Input parameters"', '&lt;Example&gt;&amp;')
+    index_menu = body.match(%r{<ul data-doc-subnav="root-parent-index">(.*?)</ul>}m)[1]
+    expect(index_menu).to include('Input parameters', 'Output parameters')
+    expect(index_menu).not_to include('Examples')
+    expect(body).to include('id="example-parent-show-0-examples"', 'id="example-parent-show-0-0"')
+    expect(body).not_to include('data-doc-subnav="root-parent-index" hidden')
+    assert_fragments(body)
+    File.write(File.join(ENV['HAVEAPI_REFERENCE_FIXTURES'], 'resource.html'), body) if ENV['HAVEAPI_REFERENCE_FIXTURES']
+  end
+
+  it 'emits one panel per group declaration and page metadata from actual rendered groups' do
+    ['/v1/', '/v1/?resource=parent', '/v1/?page=resources'].each do |path|
+      get path
+      body = last_response.body
+      groups = body.scan(%r{<div class="docs-example" data-example data-example-details="([^"]*)" id="([^"]*)">(.*?)</div>}m)
+      union = {}
+      groups.each do |json, base, html|
+        levels = JSON.parse(CGI.unescapeHTML(json))
+        panels = html.scan(/data-client="([^"]+)"[^>]*data-detail="([^"]+)"/)
+        expect(panels.sort).to eq(levels.flat_map { |client, details| details.map { |detail| [client, detail] } }.sort)
+        expect(panels.uniq).to eq(panels)
+        levels.each do |client, details|
+          union[client] = (union.fetch(client, []) | details)
+          if details == ['simple']
+            expect(ids(body)).to include("#{base.delete_suffix('-examples')}-#{client}-thorough")
+          end
+        end
+      end
+      clients = JSON.parse(body.match(%r{data-documentation-clients>(.*?)</script>}m)[1])
+      clients.each { |client| expect(client['details']).to eq(union.fetch(client['id'], ['simple'])) }
+      expect(clients.find { |client| client['id'] == '0' }.fetch('details')).to eq(path == '/v1/?page=resources' ? ['simple'] : %w[simple thorough])
+    end
+  end
+
+  it 'lists direct subresources with full dotted identities and reuses existing reference targets' do
+    get '/v1/?resource=parent'
+    sidebar = last_response.body.match(%r{<nav aria-label="Subresources">(.*?)</nav>}m)[1]
+    expect(sidebar).to include('href="/v1/?resource=parent.child"', '>parent.child</a>')
+    expect(sidebar).not_to include('grandchild')
+    expect(last_response.body).to include('aria-label="Link to Subresources"', 'aria-label="Link to parent"')
+    get '/v1/?resource=parent.child'
+    expect(last_response.body).to include('>parent.child.grandchild</a>')
+    get '/v1/'
+    expect(last_response.body).to include('aria-label="Link to Initialization"', 'aria-label="Link to Client libraries"',
+                                          'aria-label="Link to Using this reference"', 'aria-label="Documentation settings"')
+    expect(last_response.body).not_to include('M4 6h16', 'Generated SDKs')
+    assert_fragments(last_response.body)
+  end
+
+  it 'scopes duplicate authentication resource/action targets while keeping legacy aliases once' do
+    server = HaveAPI::Server.new(get_opt(:api_module))
+    server.use_version(1)
+    server.auth_chain << DocumentationReferenceSpec::FirstProvider
+    server.auth_chain << DocumentationReferenceSpec::SecondProvider
+    server.mount('/')
+    body = Rack::MockRequest.new(server.app).get('/v1/?page=authentication', 'HTTP_HOST' => 'example.test').body
+    %i[first second].each do |provider|
+      action = Object.new.extend(described_class).documentation_resource_target(resource_path: ['session'], action_name: :show, authentication: provider)
+      expect(body).to include("data-doc-nav-owner=\"auth-#{provider}\"", "data-doc-subnav=\"auth-#{provider}\"", "href=\"##{action}\"")
+      expect(ids(body).count(action)).to eq(1)
+      %i[input output].each do |section|
+        expect(body).to include("href=\"##{reference(resource_path: ['session'], action_name: :show, authentication: provider, section:)}\"")
+      end
+    end
+    expect(ids(body).uniq.length).to eq(ids(body).length)
+    %w[example-session-show-0-examples example-session-show-0-0 example-session-show-0-0-thorough].each do |legacy|
+      expect(ids(body).count(legacy)).to eq(1)
+    end
+    expect(ids(body).count('root-session')).to eq(1)
+    expect(ids(body).count('root-session-show')).to eq(1)
+    expect(body.index('id="root-session-show"')).to be < body.index('id="auth-second"')
+    assert_fragments(body)
+    File.write(File.join(ENV['HAVEAPI_REFERENCE_FIXTURES'], 'authentication.html'), body) if ENV['HAVEAPI_REFERENCE_FIXTURES']
+  end
+end

data/spec/documentation/search_index_routes_spec.rb

@@ -0,0 +1,202 @@
+require 'spec_helper'
+require 'rack/mock'
+
+module DocumentationSearchIndexSpec
+  User = Struct.new(:login)
+  class << self
+    attr_accessor :private_visible
+  end
+
+  class Provider < HaveAPI::Authentication::Basic::Provider
+    protected
+
+    def find_user(_request, username, password)
+      User.new(username) if password == 'pass'
+    end
+  end
+
+  module API
+    class Widget < HaveAPI::Resource
+      version 1
+      auth false
+      class Show < HaveAPI::Actions::Default::Show
+        authorize do |user|
+          input blacklist: [:private_ticket] unless user.login == 'admin' || DocumentationSearchIndexSpec.private_visible
+          allow
+        end
+        input(:hash) do
+          string :name, label: 'Name </script> & <markup>'
+          string :private_ticket
+        end
+        output(:hash) { string :label }
+      end
+    end
+  end
+end
+
+RSpec.describe HaveAPI::DocumentationSearch::Helpers do
+  before { DocumentationSearchIndexSpec.private_visible = false }
+
+  def server
+    @server ||= HaveAPI::Server.new(DocumentationSearchIndexSpec::API).tap do |api|
+      api.use_version(1)
+      api.auth_chain << DocumentationSearchIndexSpec::Provider
+      api.locale_header = 'X-Language'
+      api.connect_hook(:pre_mount) do |ret, _server, sinatra|
+        sinatra.before { response.set_cookie('fixture', 'changed') if request.env['HTTP_X_SET_COOKIE'] }
+        ret
+      end
+      api.mount('/api/')
+    end
+  end
+
+  def request(path, **headers)
+    environment = { 'HTTP_HOST' => 'example.test' }.merge(headers)
+    Rack::MockRequest.new(server.app).get("/api/v1/#{path}", environment)
+  end
+
+  def page_key(**headers)
+    response = request('', **headers)
+    expect(response.status).to eq(200)
+    response.body.match(/data-search-view-key="([0-9a-f]{64})"/)[1]
+  end
+
+  def envelope(response)
+    body = response.body.match(%r{\A<script type="application/json" data-documentation-search-index>(.*?)</script>\s*\z}m)[1]
+    JSON.parse(body)
+  end
+
+  it 'builds one projection from one description for the version sidebar form' do
+    allow(server).to receive(:describe_version).and_call_original
+    allow(HaveAPI::DocumentationSearch::Index).to receive(:new).and_call_original
+    response = request('?page=resources')
+    keys = response.body.scan(/data-search-view-key="([0-9a-f]{64})"/).flatten
+    expect(keys.length).to eq(1)
+    expect(keys.uniq.length).to eq(1)
+    expect(server).to have_received(:describe_version).once
+    expect(HaveAPI::DocumentationSearch::Index).to have_received(:new).once
+    expect(response['cache-control']).to eq('private, no-store')
+    expect(response.body).not_to include('data-documentation-search-index')
+  end
+
+  it 'serves only an escaped inert envelope for matching keys with private cache headers and merged Vary' do
+    key = page_key
+    response = request("?page=resources&search_index=#{key}")
+    expect(response.status).to eq(200)
+    expect(response.content_type).to match(%r{\Atext/html;\s*charset=utf-8\z})
+    expect(response['cache-control']).to eq('private, max-age=86400, immutable')
+    expect(response['etag']).to eq(%("#{key}"))
+    expect(response['vary'].split(/,\s*/)).to contain_exactly('X-Language', 'Cookie', 'Authorization')
+    expect(envelope(response)).to include('key' => key)
+    expect(response.body).to include('\\u003c/script\\u003e', '\\u0026')
+    expect(response.body).not_to include('<!DOCTYPE', 'docs-sidebar', '<script src=', 'fixture')
+  end
+
+  it 'keeps bootstrap output, mismatches and Set-Cookie changes no-store without conditional success' do
+    key = page_key
+    bootstrap = request('?page=resources&search_index=current', 'HTTP_IF_NONE_MATCH' => '*')
+    expect(bootstrap.status).to eq(200)
+    expect(bootstrap['cache-control']).to eq('private, no-store')
+    expect(bootstrap['etag']).to be_nil
+    expect(envelope(bootstrap)['key']).to eq(key)
+    mismatch = request("?page=resources&search_index=#{'0' * 64}", 'HTTP_IF_NONE_MATCH' => '*')
+    expect(mismatch.status).to eq(409)
+    expect(mismatch['cache-control']).to eq('private, no-store')
+    expect(mismatch.body).not_to include('data-documentation-search-index', 'private_ticket')
+    cookie = request("?page=resources&search_index=#{key}", 'HTTP_X_SET_COOKIE' => '1', 'HTTP_IF_NONE_MATCH' => '*')
+    expect(cookie.status).to eq(200)
+    expect(cookie['set-cookie']).not_to be_nil
+    expect(cookie['cache-control']).to eq('private, no-store')
+    expect(cookie['etag']).to be_nil
+  end
+
+  it 'rejects malformed selectors and conflicting query/page fields before describing while OPTIONS stays unchanged' do
+    allow(server).to receive(:describe_version).and_call_original
+    ["search_index=#{'A' * 64}", 'search_index=short', 'search_index[]=current',
+     'search_index=current&search_index=current', 'page=overview&search_index=current',
+     'page=resources&q=&search_index=current', 'page=resources&resource=widget&search_index=current'].each do |query|
+      expect(request("?#{query}").status).to eq(400), query
+    end
+    expect(server).not_to have_received(:describe_version)
+    response = Rack::MockRequest.new(server.app).options('/api/v1/?search_index[]=current', 'HTTP_HOST' => 'example.test')
+    expect(response.status).to eq(200)
+  end
+
+  it 'keeps neutral pages index-free and validates root default-version representations' do
+    allow(HaveAPI::DocumentationSearch::Index).to receive(:new).and_call_original
+    client = Rack::MockRequest.new(server.app)
+    %w[/api/ /api/doc/protocol].each do |path|
+      page = client.get(path, 'HTTP_HOST' => 'example.test')
+      expect(page.status).to eq(200)
+      expect(page.body).to include('data-search-view-key=""', 'search_index=current')
+    end
+    expect(HaveAPI::DocumentationSearch::Index).not_to have_received(:new)
+    invalid = client.get('/api/?search_index=current', 'HTTP_HOST' => 'example.test')
+    expect(invalid.status).to eq(400)
+    expect(invalid['cache-control']).to eq('private, no-store')
+    current = client.get('/api/?page=resources&search_index=current', 'HTTP_HOST' => 'example.test')
+    expect(current.status).to eq(200)
+    expect(envelope(current)['index']).to include('version' => '1', 'base_path' => '/api/v1/')
+  end
+
+  it 'binds the projection to resolved locale and canonical Rack/API mounts' do
+    server.available_locales = %i[en cs]
+    english = envelope(request('?page=resources&search_index=current', 'HTTP_X_LANGUAGE' => 'en'))
+    czech = envelope(request('?page=resources&search_index=current', 'HTTP_X_LANGUAGE' => 'cs'))
+    expect(english['key']).not_to eq(czech['key'])
+    expect(czech['index']['locale']).to eq('cs')
+    mounted = envelope(request('?page=resources&search_index=current', 'SCRIPT_NAME' => '/rack'))
+    expect(mounted['index']['base_path']).to eq('/rack/api/v1/')
+    expect(mounted['key']).not_to eq(english['key'])
+  end
+
+  context 'with OAuth documentation sessions' do
+    let(:documentation_server) do
+      HaveAPI::Server.new(DocumentationSearchIndexSpec::API).tap do |api|
+        api.use_version(1)
+        api.auth_chain << DocumentationSearchIndexSpec::Provider
+      end
+    end
+    let(:documentation_fixture) do
+      require_relative '../../test_support/documentation_oauth_fixture'
+      DocumentationOAuthFixture.configure(documentation_server, users: {
+        1 => { 'member-token' => DocumentationSearchIndexSpec::User.new('member'),
+               'admin-token' => DocumentationSearchIndexSpec::User.new('admin') }
+      }, mount_path: '/api/')
+    end
+
+    before do
+      documentation_fixture
+      server.mount('/api/')
+    end
+
+    def server
+      documentation_server
+    end
+
+    def request(path, user: nil, **headers)
+      environment = { 'HTTP_HOST' => URI(documentation_fixture.origin).host }.merge(headers)
+      environment['HTTP_COOKIE'] = documentation_fixture.header_for(server, version: 1, token: "#{user}-token") if user
+      Rack::MockRequest.new(server.app).get("#{documentation_fixture.origin}/api/v1/#{path}", environment)
+    end
+
+    it 'rechecks cookie authentication and permission changes before any 304 response' do
+      member = page_key(user: 'member')
+      admin = page_key(user: 'admin')
+      anonymous = page_key
+      expect([member, admin, anonymous].uniq.length).to eq(3)
+      original = request("?page=resources&search_index=#{member}", user: 'member')
+      expect(envelope(original)['index']['parameters'].map { |parameter| parameter['name'] }).not_to include('private_ticket')
+      expect(request("?page=resources&search_index=#{admin}", user: 'member', 'HTTP_IF_NONE_MATCH' => '*').status).to eq(409)
+      documentation_fixture.lookups.clear
+      expect(request("?page=resources&search_index=#{member}", user: 'member', 'HTTP_IF_NONE_MATCH' => %("#{member}")).status).to eq(304)
+      expect(documentation_fixture.lookups).to eq([[1, 'member-token']])
+      DocumentationSearchIndexSpec.private_visible = true
+      changed = page_key(user: 'member')
+      expect(changed).not_to eq(member)
+      stale = request("?page=resources&search_index=#{member}", user: 'member', 'HTTP_IF_NONE_MATCH' => '*')
+      expect(stale.status).to eq(409)
+      expect(stale.body).not_to include('data-documentation-search-index')
+    end
+  end
+end

data/spec/documentation/search_index_spec.rb

@@ -0,0 +1,85 @@
+require 'spec_helper'
+
+RSpec.describe HaveAPI::DocumentationSearch::Index do
+  let(:description) do
+    { resources: { widget: { label: 'Widget label', resources: {}, actions: {
+      show: { method: 'GET', path: '/v1/widgets/{id}', aliases: ['find'], label: 'Show widget',
+              input: { parameters: { name: { type: 'String', label: 'Name' } } },
+              output: { parameters: { id: { type: 'Integer', label: 'Identifier' } } } }
+    } } }, authentication: {} }
+  end
+  let(:options) { { base_path: '/v1/', version: '1', locale: 'en', visibility: 'anonymous' } }
+
+  def index(source = description, **changes)
+    described_class.new(description: source, **options, **changes)
+  end
+
+  it 'fingerprints deterministic owned payload bytes and preserves parent references without source mutation' do
+    before = Marshal.dump(description)
+    first = index
+    serialized = JSON.parse(JSON.generate(description))
+    expect(index(serialized).payload).to eq(first.payload)
+    expect(index(serialized).key).to eq(first.key)
+    expect(first.key).to eq(Digest::SHA256.hexdigest(JSON.generate(first.payload)))
+    expect(first.payload).to be_frozen
+    expect(first.payload[:parameters]).to all(be_frozen)
+    expect(first.payload[:actions].first[:resource]).to eq(0)
+    expect(first.payload[:parameters].map { |parameter| parameter[:action] }).to eq([0, 0])
+    expect(Marshal.dump(description)).to eq(before)
+    expect(description[:resources][:widget][:label]).not_to be_frozen
+  end
+
+  it 'sorts each metadata collection independently of the caller hash order' do
+    source = Marshal.load(Marshal.dump(description))
+    source[:resources][:another] = { actions: {}, resources: {} }
+    reversed = source.merge(resources: source[:resources].to_a.reverse.to_h)
+    expect(index(source).key).to eq(index(reversed).key)
+  end
+
+  it 'changes keys for every supported visible input and version, mount, locale or visibility boundary' do
+    original = index.key
+    mutations = [
+      ->(source) { source[:resources][:extra] = { actions: {} } },
+      ->(source) { source[:resources][:widget][:label] = 'Changed label' },
+      ->(source) { source[:resources][:widget][:actions][:extra] = { method: 'POST' } },
+      ->(source) { source[:resources][:widget][:actions][:show][:aliases] = ['lookup'] },
+      ->(source) { source[:resources][:widget][:actions][:show][:path] = '/changed' },
+      ->(source) { source[:resources][:widget][:actions][:show][:input][:parameters][:extra] = { type: 'Boolean' } },
+      ->(source) { source[:resources][:widget][:actions][:show][:output][:parameters][:id][:label] = 'Changed identifier' }
+    ]
+    mutations.each do |mutate|
+      source = Marshal.load(Marshal.dump(description))
+      mutate.call(source)
+      expect(index(source).key).not_to eq(original)
+    end
+    [{ version: '2' }, { base_path: '/mounted/v1/' }, { locale: 'cs' }, { visibility: 'authenticated' }].each do |change|
+      expect(index(**change).key).not_to eq(original)
+    end
+  end
+
+  it 'projects only whitelisted strings and no prose, defaults, examples, validator values, identities or private fields' do
+    source = Marshal.load(Marshal.dump(description))
+    source[:private_generator_model] = 'PRIVATE'
+    source[:current_user] = { login: 'ACCOUNT' }
+    source[:csrf] = 'CSRF'
+    source[:resources][:widget][:description] = 'PROSE'
+    action = source[:resources][:widget][:actions][:show]
+    action[:examples] = [{ request: 'EXAMPLE' }]
+    action[:input][:parameters][:name].merge!(default: 'DEFAULT', validators: { include: { values: ['VALIDATOR'] } })
+    expect(index(source).key).to eq(index.key)
+    expect(JSON.generate(index(source).payload)).not_to include('PRIVATE', 'ACCOUNT', 'CSRF', 'PROSE', 'EXAMPLE', 'DEFAULT', 'VALIDATOR')
+  end
+
+  it 'keeps the full index beyond the result cap and produces the shared Ruby/browser ordering fixture' do
+    fixture = JSON.parse(File.read(File.join(__dir__, 'fixtures/search_index.json')))
+    expect(fixture.fetch('index').fetch('parameters').length).to be > 20
+    fixture.fetch('queries').each do |query|
+      result = HaveAPI::DocumentationSearch.new(index: fixture.fetch('index'), query: query.fetch('query')).call
+      identities = result[:results].map do |record|
+        [record[:kind], record[:authentication], record[:resource_path].join('.'), record[:action_name], record[:direction], record[:name]].join(':')
+      end
+      expect(identities).to eq(query.fetch('expected'))
+      expect(result[:more]).to eq(query.fetch('more'))
+    end
+  end
+end