haveapi 0.31.1 → 0.32.0

data/spec/documentation/identity_context_spec.rb

@@ -0,0 +1,180 @@
+require 'spec_helper'
+
+module DocumentationIdentityContextSpec
+  User = Struct.new(:login)
+
+  class Provider < HaveAPI::Authentication::Basic::Provider
+    protected
+
+    def find_user(_request, username, password)
+      User.new(username) if password == 'pass'
+    end
+  end
+end
+
+describe DocumentationIdentityContextSpec do
+  api do
+    define_resource(:Widget) do
+      version :all
+      auth false
+      define_action(:Show) do
+        route '{widget_id}'
+        http_method :get
+        output(:hash) { string :value }
+        authorize { allow }
+        def exec
+          { value: 'unchanged' }
+        end
+      end
+    end
+  end
+  default_version 1
+  use_version 1
+  auth_chain DocumentationIdentityContextSpec::Provider
+
+  def configured_server(name: nil, versions: [1], mount: '/')
+    server = HaveAPI::Server.new(get_opt(:api_module))
+    server.use_version(versions)
+    server.default_version = 1
+    server.documentation_name = name
+    server.auth_chain << DocumentationIdentityContextSpec::Provider
+    server.mount(mount)
+    server
+  end
+
+  def request(server, path, host: 'example.test', **env)
+    Rack::MockRequest.new(server.app).get(path, { 'HTTP_HOST' => host }.merge(env))
+  end
+
+  it 'copies and freezes the trimmed display name without assigning any URL semantics' do
+    server = HaveAPI::Server.new(get_opt(:api_module))
+    original = '  <My API> & reference  '
+    server.documentation_name = original
+    original.replace('mutated')
+    expect(server.documentation_name).to eq('<My API> & reference')
+    expect(server.documentation_name).to be_frozen
+    server.documentation_name = nil
+    expect(server.documentation_name).to be_nil
+  end
+
+  it 'rejects empty, overlong, malformed and control-bearing names without replacing a valid name' do
+    server = HaveAPI::Server.new(get_opt(:api_module))
+    server.documentation_name = 'Valid'
+    ['', '   ', 'x' * 257, "bad\nname", "\tbad", "bad\u007f", "\xff".b, :name, false].each do |value|
+      expect { server.documentation_name = value }.to raise_error(ArgumentError)
+      expect(server.documentation_name).to eq('Valid')
+    end
+    server.documentation_name = 'ž' * 128
+    expect(server.documentation_name.bytesize).to eq(256)
+    expect { server.documentation_name = 'ž' * 129 }.to raise_error(ArgumentError)
+  end
+
+  it 'escapes a long configured identity across mounted titles and brands while retaining API routes' do
+    name = "<Example> & #{('long ' * 35).strip}"
+    server = configured_server(name:, mount: '/api/')
+    response = request(server, '/api/v1/?resource=widget')
+    expect(response.status).to eq(200)
+    expect(response.body).to include('<title>widget · API v1 · &lt;Example&gt; &amp;',
+                                     '<a href="/api/">&lt;Example&gt; &amp;', '<small class="docs-api-version">API v1</small>')
+    expect(response.body).not_to include('<Example>', 'api.vpsfree.cz')
+    expect { server.documentation_name = nil }.to raise_error(ArgumentError, /before mount/)
+    action = request(server, '/api/v1/widgets/1')
+    expect(action.status).to eq(200)
+    expect(JSON.parse(action.body).fetch('response').fetch('widget').fetch('value')).to eq('unchanged')
+  end
+
+  it 'uses the request host and nondefault port as fallback without inventing a canonical domain' do
+    server = configured_server
+    response = request(server, '/v1/', host: 'preview.example:8443')
+    expect(response.status).to eq(200)
+    expect(response.body).to include('<a href="/">preview.example:8443</a>', 'Overview · API v1 · preview.example:8443')
+    response = request(server, '/v1/', host: 'preview.example:80')
+    expect(response.body).to include('<a href="/">preview.example</a>')
+  end
+
+  it 'keeps explicit API credentials out of the sole-version documentation identity and describes once' do
+    app
+    server = instance_variable_get(:@api)
+    allow(server.auth_chain).to receive(:authenticate).and_call_original
+    allow(server).to receive(:describe).and_call_original
+    events = []
+    server.connect_hook(:post_authenticated) do |ret, user|
+      events << user
+      ret
+    end
+    login('<actual>&', 'pass')
+    get '/'
+    expect(last_response).to be_ok
+    expect(last_response.body).to include('<h1>API versions</h1>', 'Showing all resources, actions and parameters.')
+    expect(last_response.body).not_to include('docs-identity', 'docs-sign-in', 'API description', 'Available versions:')
+    expect(server.auth_chain).not_to have_received(:authenticate)
+    expect(server).to have_received(:describe).once.with(have_attributes(current_user: nil, auth_users_by_version: { 1 => nil }))
+    expect(events).to eq([nil])
+    expect(last_response.headers['Cache-Control']).to eq('private, no-store')
+  end
+
+  it 'keeps anonymous root search lazy without authentication or extraction' do
+    app
+    server = instance_variable_get(:@api)
+    allow(server.auth_chain).to receive(:authenticate).and_call_original
+    allow(server).to receive(:describe).and_call_original
+    allow(HaveAPI::DocumentationSearch::Index).to receive(:new).and_call_original
+    get '/'
+    expect(last_response).to be_ok
+    expect(last_response.body).to include('Showing all resources, actions and parameters.')
+    expect(last_response.body).not_to include('docs-identity', 'class="authentication"')
+    expect(server.auth_chain).not_to have_received(:authenticate)
+    expect(server).to have_received(:describe).once
+    expect(HaveAPI::DocumentationSearch::Index).not_to have_received(:new)
+  end
+
+  it 'resolves each multiversion documentation identity anonymously without borrowing API credentials' do
+    server = configured_server(versions: [1, 2])
+    allow(server.auth_chain).to receive(:authenticate).and_call_original
+    allow(server).to receive(:describe).and_call_original
+    events = []
+    server.connect_hook(:post_authenticated) do |ret, user|
+      events << user
+      ret
+    end
+    response = request(server, '/', 'HTTP_AUTHORIZATION' => "Basic #{['member:pass'].pack('m0')}")
+    expect(response.status).to eq(200)
+    expect(response.body).to include('Version 1', 'Version 2')
+    expect(response.body).not_to include('docs-identity', 'docs-visibility-note', 'class="docs-sign-in', 'class="docs-account-link')
+    expect(server.auth_chain).not_to have_received(:authenticate)
+    expect(server).to have_received(:describe).once.with(have_attributes(current_user: nil, auth_users_by_version: { 1 => nil, 2 => nil }))
+    expect(events).to eq([nil, nil])
+  end
+
+  it 'keeps one settings disclosure with direct theme choices and no account actions when OAuth is absent' do
+    server = configured_server(mount: '/api/')
+    response = request(server, '/api/', 'SCRIPT_NAME' => '/rack')
+    expect(response.status).to eq(200)
+    expect(response.body).to include('href="/rack/api/"', 'href="/rack/api/v1/"', 'data-documentation-menu',
+                                     'data-documentation-menu-content', 'aria-label="Documentation settings"')
+    expect(response.body.scan('<details data-documentation-menu>').length).to eq(1)
+    expect(response.body).not_to include('data-account-menu', 'data-theme-menu', 'docs-sign-in', 'docs-account-link', '_logout')
+  end
+
+  it 'keeps the documentation authentication boundary out of root OPTIONS and API actions' do
+    app.helpers do
+      def documentation_authenticated?(_version)
+        raise 'Documentation-only authentication used for an API request'
+      end
+    end
+    call_api(:options, '/')
+    expect(last_response).to be_ok
+    expect(api_response.response).to have_key(:versions)
+    get '/v1/widgets/1'
+    expect(last_response).to be_ok
+    expect(api_response[:widget][:value]).to eq('unchanged')
+  end
+
+  it 'forwards renderer capabilities without pruning either panel detail level' do
+    get '/v1/'
+    clients = JSON.parse(last_response.body.match(%r{data-documentation-clients>(.*?)</script>}m)[1])
+    expect(clients.find { |client| client['language'] == 'http' }.fetch('details')).to eq(['simple'])
+    expect(clients.find { |client| client['id'] == 'javascript-async' }.fetch('details')).to eq(%w[simple thorough])
+    expect(last_response.body).to include('data-detail-control', 'data-detail="simple"', 'data-detail="thorough"')
+  end
+end

data/spec/documentation/navigation_spec.rb

@@ -0,0 +1,296 @@
+require 'spec_helper'
+
+module DocumentationNavigationSpec
+  User = Struct.new(:login)
+
+  class Provider < HaveAPI::Authentication::Basic::Provider
+    protected
+
+    def find_user(_request, username, password)
+      User.new(username) if password == 'pass'
+    end
+  end
+end
+
+module DocumentationNavigationSpec
+  API = Module.new do
+    def self.define_resource(name, &block)
+      klass = Class.new(HaveAPI::Resource)
+      const_set(name, klass)
+      klass.class_exec(&block)
+      klass
+    end
+    widget = define_resource(:Widget) do
+      version 1
+      auth false
+      desc 'Parent resource description'
+
+      define_action(:Index, superclass: HaveAPI::Actions::Default::Index) do
+        input(:hash) do
+          bool :enabled, default: false
+          integer :count, default: 0
+          string :empty, default: ''
+          string :nullable, nullable: true, default: nil
+          string :lifetime, validate: 'At least one hour, at most one week'
+        end
+        output(:hash) do
+          integer :id
+          string :label
+        end
+        authorize { allow }
+      end
+
+      define_action(:Show) do
+        route '{widget_id}'
+        http_method :get
+        output(:hash) do
+          integer :id
+          string :label
+          string :name
+        end
+        authorize { allow }
+
+        # rubocop:disable RSpec/NoExpectationExample
+        example 'parent sample' do
+          path_params 1
+          response(name: 'PARENT_SAMPLE')
+        end
+        # rubocop:enable RSpec/NoExpectationExample
+
+        def exec
+          { name: 'parent' }
+        end
+      end
+
+      define_resource(:Child) do
+        desc 'Nested resource description'
+        define_action(:Show) do
+          route '{child_id}'
+          http_method :get
+          output(:hash) { string :name }
+          authorize { allow }
+
+          # rubocop:disable RSpec/NoExpectationExample
+          example 'child sample' do
+            path_params 2
+            response(name: 'CHILD_SAMPLE')
+          end
+          # rubocop:enable RSpec/NoExpectationExample
+        end
+      end
+    end
+
+    define_resource(:Reference) do
+      version 1
+      auth false
+      define_action(:Show) do
+        route '{reference_id}'
+        http_method :get
+        output(:hash) { resource widget }
+        authorize { allow }
+      end
+    end
+
+    define_resource(:Hidden) do
+      version 1
+      auth false
+      desc 'HIDDEN_RESOURCE_DESCRIPTION'
+      define_action(:Show) do
+        route '{hidden_id}'
+        http_method :get
+        output(:hash) { string :secret }
+        authorize { |user| user.login == 'admin' ? allow : deny }
+      end
+    end
+  end
+end
+
+describe DocumentationNavigationSpec do
+  api DocumentationNavigationSpec::API
+  default_version 1
+  auth_chain DocumentationNavigationSpec::Provider
+
+  let(:documentation_server) { HaveAPI::Server.new(get_opt(:api_module)) }
+  let(:docs_fixture) do
+    require_relative '../../test_support/documentation_oauth_fixture'
+    server = documentation_server
+    server.use_version(1)
+    server.auth_chain << DocumentationNavigationSpec::Provider
+    users = %w[member admin].to_h { |name| [name, DocumentationNavigationSpec::User.new(name)] }
+    fixture = DocumentationOAuthFixture.configure(server, users: { 1 => users })
+    server.mount('/')
+    @api = server
+    fixture
+  end
+
+  def request_as(user, path)
+    fixture = docs_fixture
+    get "#{fixture.origin}#{path}", {}, 'HTTP_COOKIE' => fixture.header_for(documentation_server, version: 1, token: user)
+  end
+
+  def json_element(attribute)
+    JSON.parse(last_response.body.match(%r{<script[^>]*#{attribute}[^>]*>(.*?)</script>}m)[1])
+  end
+
+  it 'renders an overview without resource actions and supplies visible legacy destinations' do
+    request_as('member', '/v1/')
+    expect(last_response).to be_ok
+    expect(last_response.headers['Cache-Control']).to eq('private, no-store')
+    expect(last_response.body).to include('data-page="overview"', 'init-0', '?resource=widget.child')
+    expect(last_response.body).not_to include('PARENT_SAMPLE', 'CHILD_SAMPLE', 'HIDDEN_RESOURCE_DESCRIPTION')
+    expect(json_element('data-legacy-anchors')).to include(
+      'root-widget-show' => '/v1/?resource=widget',
+      'root-widget-child-show' => '/v1/?resource=widget.child',
+      'example-widget.child-show-' => '/v1/?resource=widget.child',
+      'auth-basic' => '/v1/?page=authentication',
+      'auth-basic-javascript-async' => '/v1/?page=authentication'
+    )
+    expect(json_element('data-legacy-anchors').keys.join).not_to include('hidden')
+  end
+
+  it 'renders only the selected resource actions and preserves stable example IDs' do
+    get '/v1/?resource=widget'
+    expect(last_response).to be_ok
+    expect(last_response.body).to include('data-page="resource"', '<h1 class="resource" id="root-widget">widget<a class="docs-permalink"', 'id="root-widget-show"',
+                                          'id="example-widget-show-0-0"', 'data-example-details', 'PARENT_SAMPLE')
+    expect(last_response.body).not_to include('CHILD_SAMPLE', 'init-examples')
+    expect(last_response.body).to include('data-resource-breadcrumbs', '<li aria-current="page">Widget</li>')
+    expect(last_response.body).not_to include('data-resource-nav', 'class="docs-header"')
+  end
+
+  it 'renders nested resources on their own page with same-page action links' do
+    get '/v1/?resource=widget.child'
+    expect(last_response).to be_ok
+    expect(last_response.body).to include('id="root-widget-child-show"', 'href="#root-widget-child-show"', 'CHILD_SAMPLE')
+    expect(last_response.body).not_to include('PARENT_SAMPLE')
+    sidebar = last_response.body.match(%r{<aside[^>]*>(.*?)</aside>}m)[1]
+    expect(sidebar).to include('<p data-current-resource><a href="/v1/?resource=widget.child"><strong>widget.child</strong></a></p>')
+    expect(sidebar).not_to include('<h2>Resource</h2>', '<code>widget.child</code>')
+    expect(sidebar.index('data-current-resource')).to be < sidebar.index('aria-label="Actions on this resource"')
+  end
+
+  it 'keeps authentication content separate from the overview' do
+    get '/v1/?page=authentication'
+    expect(last_response).to be_ok
+    expect(last_response.body).to include('data-page="authentication"', 'id="auth-basic"')
+    expect(last_response.body).not_to include('PARENT_SAMPLE', 'init-examples')
+  end
+
+  it 'returns the same missing response for inaccessible and absent resources' do
+    request_as('member', '/v1/?resource=hidden')
+    expect(last_response.status).to eq(404)
+    hidden_body = last_response.body
+    request_as('member', '/v1/?resource=absent')
+    expect(last_response.status).to eq(404)
+    expect(last_response.body).to eq(hidden_body)
+    expect(last_response.body).not_to include('HIDDEN_RESOURCE_DESCRIPTION')
+  end
+
+  it 'rejects malformed, duplicate, nested and ambiguous HTML selection' do
+    %w[resource= resource=widget..child resource=../widget resource[]=widget resource[x]=widget
+       resource=widget&resource=reference page=unknown page=authentication&resource=widget
+       page=overview&page=authentication resource=%00].each do |query|
+      get "/v1/?#{query}"
+      expect(last_response.status).to eq(400), query
+    end
+  end
+
+  it 'does not reinterpret selection on OPTIONS descriptions or action endpoints' do
+    call_api(:options, '/v1/?resource=absent&page=unknown')
+    expect(last_response).to be_ok
+    expect(api_response[:resources]).to have_key(:widget)
+    get '/v1/widgets/1?resource=absent&page=unknown'
+    expect(last_response).to be_ok
+    expect(api_response[:widget][:name]).to eq('parent')
+  end
+
+  it 'qualifies resource parameter links with the selected resource page' do
+    get '/v1/?resource=reference'
+    expect(last_response).to be_ok
+    expect(last_response.body).to include('href="/v1/?resource=widget#root-widget-show"')
+  end
+
+  it 'preserves root version listing while supporting default-version selection' do
+    get '/'
+    expect(last_response.body).to include('<h1>API versions</h1>')
+    get '/?resource=widget.child'
+    expect(last_response).to be_ok
+    expect(last_response.body).to include('CHILD_SAMPLE', 'href="/v1/?resource=widget"')
+  end
+
+  it 'keeps the complete authorized resource hierarchy on a separate directory page' do
+    request_as('member', '/v1/?page=resources')
+    expect(last_response).to be_ok
+    expect(last_response.body).to include('data-page="resources"', 'data-resource-nav', 'data-documentation-search',
+                                          'data-resource-link="widget.child"', 'data-search-query')
+    expect(last_response.body).not_to include('PARENT_SAMPLE', 'CHILD_SAMPLE', 'data-resource-link="hidden"')
+    get '/v1/'
+    expect(last_response.body).to include('data-resource-directory-link', '?page=resources')
+    expect(last_response.body).not_to include('data-resource-nav', 'data-resource-link="widget"')
+    expect(json_element('data-legacy-anchors')['resources']).to eq('/v1/?page=resources')
+  end
+
+  it 'links nested resource breadcrumbs to the directory and each real parent' do
+    get '/v1/?resource=widget.child'
+    breadcrumb = last_response.body.match(%r{<nav aria-label="Breadcrumb" data-resource-breadcrumbs>(.*?)</nav>}m)[1]
+    expect(breadcrumb).to include('href="/v1/?page=resources"', 'href="/v1/?resource=widget"',
+                                  '<li aria-current="page">Child</li>')
+    expect(last_response.body.index('data-action-nav')).to be < last_response.body.index('docs-preferences')
+    expect(last_response.body).to include('data-theme-choice="auto"', 'data-theme-choice="light"', 'data-theme-choice="dark"')
+    expect(last_response.body).not_to include('data-theme-select')
+  end
+
+  it 'keeps parameter values and validators readable in semantic compact tables' do
+    get '/v1/?resource=widget'
+    input = last_response.body.match(%r{<table class="docs-input-parameters">(.*?)</table>\s*</div>\s*<h\d[^>]*>Output parameters}m)[1]
+    output = last_response.body.match(%r{<table class="docs-output-parameters">(.*?)</table>}m)[1]
+    expect(input.scan('<th>').length).to eq(4)
+    expect(output.scan('<th>').length).to eq(3)
+    expect(input).to include('docs-param-details', 'Default:</strong> <code>false</code>',
+                             'Default:</strong> <code>0</code>', 'Default:</strong> <code>&quot;&quot;</code>',
+                             'Default:</strong> <code>null</code>', '<table class="docs-validator-table">',
+                             '<caption>Validation rules</caption>', '<th scope="row">Custom</th>', 'At least one hour, at most one week')
+    expect(last_response.body).to include('class="docs-table-scroll" tabindex="0" role="region" aria-label="Input parameters"')
+    expect(input).not_to include('<dl>')
+  end
+
+  it 'keeps client presentation metadata safe in JSON script text' do
+    payload = '</script><script>window.injected = true</script>'
+    client = HaveAPI::ClientExample.clients.first
+    allow(client).to receive(:language_label).and_return(payload)
+    get '/v1/'
+    expect(last_response.body).not_to include(payload)
+    expect(json_element('data-documentation-clients').first.fetch('language_label')).to eq(payload)
+  end
+
+  it 'rejects malformed raw percent escapes before describing the version' do
+    response = Rack::MockRequest.new(app).get('/v1/',
+                                              'HTTP_HOST' => 'example.test', 'QUERY_STRING' => 'resource=%ZZ')
+    expect(response.status).to eq(400)
+  end
+
+  it 'resolves documentation assets and the highlighter under a Rack mount' do
+    response = Rack::MockRequest.new(app).get('/v1/?resource=widget',
+                                              'HTTP_HOST' => 'example.test', 'SCRIPT_NAME' => '/rack')
+    expect(response.status).to eq(200)
+    expect(response.body).to include('src="/rack/js/documentation.js"',
+                                     'data-highlighter-url="/rack/js/highlighter.js"',
+                                     'href="/rack/css/documentation.css"',
+                                     'href="/rack/v1/?page=resources"')
+  end
+
+  it 'uses mounted canonical navigation and keeps shared documentation on its layout' do
+    server = HaveAPI::Server.new(get_opt(:api_module))
+    server.use_version(1)
+    server.mount('/mounted/api/')
+    response = Rack::MockRequest.new(server.app).get('/mounted/api/v1/?resource=reference', 'HTTP_HOST' => 'example.test')
+    expect(response.status).to eq(200)
+    expect(response.body).to include('href="/mounted/api/v1/?resource=widget#root-widget-show"', '/js/documentation.js')
+    expect(response.body).not_to include('href="/mounted/api/doc/protocol"')
+    expect(response.body).not_to include('/js/nojs-tabs.js', '/js/main.js')
+    get '/doc/protocol'
+    expect(last_response).to be_ok
+    expect(last_response.body).to include('/js/documentation.js', 'data-page="guide"')
+    expect(last_response.body).not_to include('/js/main.js')
+  end
+end

data/spec/documentation/oauth_fixture_spec.rb

@@ -0,0 +1,39 @@
+require 'spec_helper'
+require_relative '../../test_support/documentation_oauth_fixture'
+
+describe DocumentationOAuthFixture do
+  api do
+    define_resource(:Widget) do
+      version 1
+      define_action(:Index, superclass: HaveAPI::Actions::Default::Index) do
+        output(:hash) { string :value }
+        authorize { |user| user&.login == 'admin' ? allow : deny }
+      end
+    end
+  end
+
+  it 'issues real mounted cookies outside requests and validates role, crypto and lookup on every page' do
+    user = Struct.new(:login)
+    server = HaveAPI::Server.new(self.class::ApiModule)
+    server.use_version(1)
+    users = { 1 => { 'admin-token' => user.new('admin'), 'member-token' => user.new('member') } }
+    fixture = described_class.configure(server, users:, origin: 'https://fixture.example', mount_path: '/api/')
+    server.mount('/api/')
+    headers = %w[admin-token member-token].to_h { |token| [token, fixture.header_for(server, version: 1, token:)] }
+    expect(fixture.lookups).to be_empty
+    expect(headers.values.join).not_to include('admin-token', 'member-token')
+    allow(server.documentation_oauth).to receive(:read_cookie).and_call_original
+    client = Rack::MockRequest.new(server.app)
+    url = "#{fixture.origin}/api/v1/?resource=widget"
+
+    first = client.get(url, 'HTTP_HOST' => 'fixture.example', 'HTTP_COOKIE' => headers.fetch('admin-token'))
+    second = client.get(url, 'HTTP_HOST' => 'fixture.example', 'HTTP_COOKIE' => headers.fetch('admin-token'))
+    expect(first.status).to eq(200)
+    expect(second.body).to eq(first.body)
+    expect(first.body).to include('admin', 'name="csrf"')
+    member = client.get(url, 'HTTP_HOST' => 'fixture.example', 'HTTP_COOKIE' => headers.fetch('member-token'))
+    expect(member.status).to eq(404)
+    expect(fixture.lookups).to eq([[1, 'admin-token'], [1, 'admin-token'], [1, 'member-token']])
+    expect(server.documentation_oauth).to have_received(:read_cookie).exactly(3).times
+  end
+end