haveapi 0.31.1 → 0.32.0

data/spec/documentation/canonical_routes_spec.rb

@@ -0,0 +1,89 @@
+require 'spec_helper'
+
+describe HaveAPI::Server, '#mount' do
+  api do
+    define_resource(:Ping) do
+      version :all
+      auth false
+      define_action(:Show) do
+        route 'ping'
+        http_method :get
+        output(:hash) { string :value }
+        authorize { allow }
+        def exec
+          { value: 'pong' }
+        end
+      end
+    end
+  end
+
+  def server_at(mount = '/')
+    server = HaveAPI::Server.new(get_opt(:api_module))
+    server.use_version([1, '7.0'])
+    server.mount(mount)
+    server
+  end
+
+  def request(server, method, path, **env)
+    Rack::MockRequest.new(server.app).request(method, path, { 'HTTP_HOST' => 'example.test' }.merge(env))
+  end
+
+  it 'redirects only declared slashless GET/HEAD roots with raw query bytes and no loop' do
+    server = server_at
+    %w[GET HEAD].product(%w[1 7.0]).each do |method, version|
+      query = 'page=resources&q=a+b%2f%2F&raw=%2520'
+      response = request(server, method, "/v#{version}?#{query}")
+      expect(response.status).to eq(308)
+      expect(response['Location']).to eq("/v#{version}/?#{query}")
+      expect(response['Cache-Control']).to eq('private, no-store')
+      canonical = request(server, method, "/v#{version}/")
+      expect(canonical.status).to eq(200)
+      expect(canonical['Location']).to be_nil
+    end
+  end
+
+  it 'includes Rack SCRIPT_NAME exactly once under the API mount' do
+    server = server_at('/mounted/api/')
+    response = request(server, 'GET', '/mounted/api/v7.0?resource=ping', 'SCRIPT_NAME' => '/rack')
+    expect(response.status).to eq(308)
+    expect(response['Location']).to eq('/rack/mounted/api/v7.0/?resource=ping')
+  end
+
+  it 'does not reinterpret unknown versions, action paths, OPTIONS or mutations as documentation redirects' do
+    server = server_at
+    [['GET', '/v2'], ['GET', '/v1/pings'], ['OPTIONS', '/v1'], ['POST', '/v1'], ['PUT', '/v1'], ['DELETE', '/v1']].each do |method, path|
+      expect(request(server, method, path).status).not_to eq(308), "#{method} #{path}"
+    end
+    expect(request(server, 'GET', '/v1/pings/ping').status).to eq(200)
+    expect(request(server, 'OPTIONS', '/v1/').status).to eq(200)
+  end
+
+  it 'rejects literal header controls but preserves their encoded query representation' do
+    server = server_at
+    ["a\rX: value", "a\n", "a\0", "a\x7f"].each do |query|
+      response = request(server, 'GET', '/v1', 'QUERY_STRING' => query)
+      expect(response.status).to eq(400)
+      expect(response['Location']).to be_nil
+      expect(response['Cache-Control']).to eq('private, no-store')
+    end
+    response = request(server, 'GET', '/v1?q=%0D%0A')
+    expect(response.status).to eq(308)
+    expect(response['Location']).to eq('/v1/?q=%0D%0A')
+  end
+
+  it 'keeps legacy login/logout as credential-free default-overview redirects' do
+    server = server_at('/mounted/api/')
+    allow(server.auth_chain).to receive(:authenticate).and_call_original
+    %w[_login _logout].product(%w[GET HEAD]).each do |path, method|
+      response = request(server, method, "/mounted/api/#{path}?back=https://foreign.example/", 'SCRIPT_NAME' => '/rack',
+                                                                                               'HTTP_REFERER' => 'https://foreign.example/',
+                                                                                               'HTTP_AUTHORIZATION' => 'Basic malformed')
+      expect(response.status).to eq(303)
+      expect(response['Location']).to eq('/rack/mounted/api/v7.0/')
+      expect(response['Cache-Control']).to eq('private, no-store')
+      expect(response['WWW-Authenticate']).to be_nil
+      expect(response['Set-Cookie']).to be_nil
+    end
+    expect(server.auth_chain).not_to have_received(:authenticate)
+  end
+end

data/spec/documentation/client_examples_spec.rb

@@ -21,6 +21,17 @@ describe HaveAPI::ClientExample do
           path_params 1
           response({ name: 'documented widget' })
         end
+
+        example 'hostile success transcript' do
+          path_params 1
+          response({ name: "$(echo unsafe)\r\n; echo '<unsafe>'\rtrailing\\" })
+        end
+
+        example 'hostile failure transcript' do
+          path_params 1
+          status false
+          message "$(echo unsafe)\r\n; echo '<unsafe>'\rtrailing\\"
+        end
         # rubocop:enable RSpec/NoExpectationExample
       end
     end
@@ -39,7 +50,7 @@ describe HaveAPI::ClientExample do
 
     expect(last_response.status).to eq(200)
     expect(last_response.body).not_to include('File system', 'haveapi-fs', 'FUSE-based file system')
-    expect(last_response.body).to include('Initialization', '<h4>Ruby</h4>', '<h4>PHP</h4>', '<h4>curl</h4>')
+    expect(last_response.body).to include('Initialization', '<summary>Ruby', '<summary>PHP', '<summary>curl')
   end
 
   it 'hides unconfigured generated SDKs in overview, initialization, authentication and actions' do
@@ -47,6 +58,7 @@ describe HaveAPI::ClientExample do
     expect(last_response.status).to eq(200)
     expect(last_response.body).not_to include('clients/go', 'clients/rust', 'init-go', 'init-rust', 'typescript-generated', '>Go</h', '>Rust (')
     expect(last_response.body).to include('init-javascript-callback', 'init-typescript-async', 'init-python-sync')
+    get '/v1/?resource=widget'
     expect(last_response.body).to include('example-widget-show-0-javascript-callback')
   end
 
@@ -56,13 +68,18 @@ describe HaveAPI::ClientExample do
     allow(HaveAPI::ClientExamples::GoClient).to receive(:render).and_return({ status: :limitation, reason: 'Unsupported <sample> & value' }.freeze)
     get '/v1/'
     expect(last_response.status).to eq(200)
-    expect(last_response.body).to include('clients/go', 'init-go', 'example-widget-show-0-go', 'Unsupported &lt;sample&gt; &amp; value')
+    expect(last_response.body).to include('clients/go', 'init-go', 'Unsupported &lt;sample&gt; &amp; value')
     expect(last_response.body).not_to include('Unsupported <sample>', 'clients/rust', 'init-rust')
+    get '/v1/?resource=widget'
+    expect(last_response.body).to include('example-widget-show-0-go', 'Unsupported &lt;sample&gt; &amp; value')
   end
 
   it 'passes mounted version-aware URLs and stable canonical action data into renderers' do
     contexts = []
-    allow(HaveAPI::ClientExamples::GoClient).to receive(:available?).and_return(true)
+    allow(HaveAPI::ClientExamples::GoClient).to receive_messages(
+      available?: true,
+      detail_levels_for: HaveAPI::ClientExamples::GoClient.detail_levels
+    )
     allow(HaveAPI::ClientExamples::GoClient).to receive(:render) do |kind, context:, **_kwargs|
       contexts << [kind, context]
       { status: :code, code: context.version_url }
@@ -70,7 +87,7 @@ describe HaveAPI::ClientExample 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/', 'HTTP_HOST' => 'example.org')
+    response = Rack::MockRequest.new(server.app).get('/mounted/api/v1/?resource=widget', 'HTTP_HOST' => 'example.org')
     expect(response.status).to eq(200)
     selected = contexts.find { |kind, ctx| kind == :example && ctx.action_name == 'show' }.last
     expect(selected.base_url).to eq('http://example.org/mounted/api/')
@@ -86,7 +103,24 @@ describe HaveAPI::ClientExample do
     allow(HaveAPI::ClientExamples::GoClient).to receive(:render).and_return({ status: :code, code: 'example' })
     get '/v1/'
     expect(last_response.status).to eq(200)
-    expect(last_response.body).to include('<code>example.test/&lt;client&gt;&amp;</code></li>')
+    expect(last_response.body).to include('<code>example.test/&lt;client&gt;&amp;</code>')
     expect(last_response.body).not_to include('example.test/<client>', '&amp;lt;', 'version = "latest"')
   end
+
+  it 'preserves inert shell response comments in actual HTML after entity and physical-line decoding' do
+    get '/v1/?resource=widget'
+    expect(last_response.status).to eq(200)
+    panels = last_response.body.scan(%r{<details\b[^>]*id="(example-widget-show-[12]-[35])"[^>]*>.*?<code[^>]*>(.*?)</code>}m).to_h
+    expect(panels.keys).to contain_exactly('example-widget-show-1-3', 'example-widget-show-1-5',
+                                           'example-widget-show-2-3', 'example-widget-show-2-5')
+    panels.each do |id, html|
+      source = CGI.unescapeHTML(html.gsub(/\r\n?/, "\n"))
+      expect(source).to start_with('$ ')
+      expect(source).to include('$(echo unsafe)', '<unsafe>', 'trailing')
+      response = source.split("\n# ", 2).fetch(1)
+      expect("# #{response}".lines).to all(start_with('# '))
+      expect(source).not_to include("\n; echo", "\ntrailing")
+      expect(source).to include('# Action failed:') if id == 'example-widget-show-2-3'
+    end
+  end
 end

data/spec/documentation/client_overview_spec.rb

@@ -0,0 +1,145 @@
+require 'spec_helper'
+
+describe HaveAPI::DocumentationHelpers, '#render_version_documentation' do
+  empty_api
+  use_version 1
+
+  def overview(response = last_response)
+    expect(response.status).to eq(200)
+    response.body.match(%r{<section id="client-libraries">(.*?)</section>}m).to_a.fetch(1)
+  end
+
+  def library_entries(body)
+    body.scan(%r{<li>(.*?)</li>}m).flatten.map { |entry| CGI.unescapeHTML(entry.gsub(/<[^>]*>/, '')).strip }
+  end
+
+  def profile(language, name, version = nil)
+    adapter = Object.new
+    def adapter.render(**)
+      { status: :limitation, reason: 'Fixture API client sample is unavailable.' }
+    end
+    HaveAPI::ClientExample::Profile.new(language:, package_name: name, package_version: version, adapter:)
+  end
+
+  def use_profiles(profiles)
+    allow(app.settings.api_server).to receive(:documentation_client_profiles).and_return(profiles)
+  end
+
+  it 'links every available maintained dynamic client and both execution styles to its guide' do
+    get '/v1/'
+    body = overview
+    {
+      'clients/ruby#client-library' => 'library',
+      'clients/ruby#cli' => 'CLI',
+      'clients/js#javascript-with-callbacks' => 'callback',
+      'clients/js#javascript-with-async-await' => 'async',
+      'clients/js#typescript-with-callbacks' => 'callback',
+      'clients/js#typescript-with-async-await' => 'async',
+      'clients/python#synchronous-client' => 'sync',
+      'clients/python#asynchronous-client' => 'async',
+      'clients/php' => 'PHP'
+    }.each do |path, label|
+      expect(body).to include("href=\"https://github.com/vpsfreecz/haveapi/tree/master/#{path}\">#{label}</a>")
+    end
+    expect(library_entries(body)).to eq(['Ruby (library and CLI)', 'JavaScript (callback and async)',
+                                         'TypeScript (callback and async)', 'Python (sync and async)', 'PHP'])
+    expect(body).not_to include('clients/go', 'clients/rust', 'clients/typescript', 'Elixir', 'File system')
+  end
+
+  it 'shows configured API client identities and only their explicitly configured versions' do
+    use_profiles(go: profile(:go, 'example.test/widget/client', 'v2.3.4'),
+                 rust: profile(:rust, 'widget-client'),
+                 typescript: profile(:typescript, '@example/widget', '1.2.3'))
+    get '/v1/'
+    body = overview
+    expect(body).to include('clients/go', 'example.test/widget/client', 'v2.3.4', 'clients/rust', 'widget-client',
+                            'clients/typescript', '@example/widget', '1.2.3')
+    expect(body.scan('@example/widget').length).to eq(1)
+    expect(body.scan('widget-client').length).to eq(1)
+    expect(body.scan('example.test/widget/client').length).to eq(1)
+    expect(body.scan('v2.3.4').length).to eq(1)
+    expect(body.scan('1.2.3').length).to eq(1)
+    expect(body).not_to include('latest', '0.0.0')
+    entries = library_entries(body)
+    expect(entries.length).to eq(7)
+    expect(entries.grep(/\ATypeScript/)).to eq(['TypeScript (callback, async and API client): @example/widget 1.2.3'])
+    expect(entries.grep(/\ARust/)).to eq(['Rust (async and blocking): widget-client'])
+  end
+
+  it 'does not advertise unavailable API client renderers or unsupported profiles' do
+    use_profiles(go: profile(:go, 'HIDDEN_SDK_IDENTITY'), elixir: profile(:elixir, 'UNSUPPORTED_SDK_IDENTITY'))
+    allow(HaveAPI::ClientExamples::GoClient).to receive(:available?).and_return(false)
+    get '/v1/'
+    body = overview
+    expect(body).not_to include('HIDDEN_SDK_IDENTITY', 'UNSUPPORTED_SDK_IDENTITY', 'clients/go', 'clients/elixir')
+    expect(body).to include('Ruby', 'Python (')
+  end
+
+  it 'filters dynamic client links through the same availability contract' do
+    allow(HaveAPI::ClientExamples::PythonAsyncClient).to receive(:available?).and_return(false)
+    get '/v1/'
+    expect(library_entries(overview)).to include('Python (sync)')
+    expect(overview).not_to include('#asynchronous-client')
+  end
+
+  it 'omits unavailable generated variants without hiding their remaining language choices' do
+    use_profiles(rust: profile(:rust, 'visible-rust-sdk'), typescript: profile(:typescript, 'HIDDEN_TYPESCRIPT_SDK'))
+    allow(HaveAPI::ClientExamples::TsGeneratedClient).to receive(:available?).and_return(false)
+    allow(HaveAPI::ClientExamples::RustBlockingClient).to receive(:available?).and_return(false)
+    get '/v1/'
+    body = overview
+    entries = library_entries(body)
+    expect(entries.grep(/\ATypeScript/)).to eq(['TypeScript (callback and async)'])
+    expect(entries.grep(/\ARust/)).to eq(['Rust (async): visible-rust-sdk'])
+    expect(body).not_to include('HIDDEN_TYPESCRIPT_SDK', 'clients/typescript', '>blocking</a>')
+    expect(body.scan('visible-rust-sdk').length).to eq(1)
+  end
+
+  it 'keeps Ruby and CLI independently discoverable when only one is available' do
+    allow(HaveAPI::ClientExamples::RubyClient).to receive(:available?).and_return(false)
+    get '/v1/'
+    entries = library_entries(overview)
+    expect(entries).to include('CLI')
+    expect(entries.grep(/\ARuby/)).to be_empty
+    allow(HaveAPI::ClientExamples::RubyClient).to receive(:available?).and_return(true)
+    allow(HaveAPI::ClientExamples::RubyCli).to receive(:available?).and_return(false)
+    get '/v1/'
+    entries = library_entries(overview)
+    expect(entries).to include('Ruby')
+    expect(entries).not_to include('CLI', 'Ruby (library and CLI)')
+  end
+
+  it 'escapes renderer labels and configured API client identities and versions' do
+    payload = '<script>injected</script> & "quoted"'
+    use_profiles(go: profile(:go, payload, payload))
+    allow(HaveAPI::ClientExamples::GoClient).to receive(:language_label).and_return(payload)
+    allow(HaveAPI::ClientExamples::RubyClient).to receive(:language_label).and_return(payload)
+    allow(HaveAPI::ClientExamples::PythonAsyncClient).to receive(:variant).and_return(payload)
+    get '/v1/'
+    body = overview
+    expect(body).not_to include(payload, '<script>', 'href="javascript:')
+    expect(body).to include('&lt;script&gt;injected&lt;/script&gt; &amp; &quot;quoted&quot;')
+    expect(body).to include('href="https://github.com/vpsfreecz/haveapi/tree/master/clients/go"')
+  end
+
+  it 'makes curl and raw HTTP examples discoverable without claiming client packages' do
+    get '/v1/'
+    body = overview
+    expect(body).to include('href="/v1/?page=resources">curl</a>', 'href="/v1/?page=resources">HTTP</a>',
+                            'request examples are available on resource pages.')
+    expect(body).not_to include('clients/curl', 'clients/http')
+  end
+
+  it 'keeps local discovery links within the mounted API and Rack prefix' do
+    server = HaveAPI::Server.new(get_opt(:api_module))
+    server.use_version(1)
+    server.default_version = 1
+    server.mount('/mounted/api/')
+    response = Rack::MockRequest.new(server.app).get('/mounted/api/v1/',
+                                                     'HTTP_HOST' => 'example.test', 'SCRIPT_NAME' => '/rack')
+    body = overview(response)
+    expect(body).to include('href="/rack/mounted/api/v1/?page=resources">curl</a>')
+    expect(body).to include('href="/rack/mounted/api/v1/?page=resources">HTTP</a>')
+    expect(body).to include('href="https://github.com/vpsfreecz/haveapi/tree/master/clients/ruby#client-library">library</a>')
+  end
+end

data/spec/documentation/current_user_html_escaping_spec.rb

@@ -34,8 +34,13 @@ describe CurrentUserHtmlEscapingSpec do
   it 'escapes the authenticated login in HTML documentation' do
     payload = '<script>window.__haveapi_xss = 1</script>'
 
-    login(payload, 'pass')
-    get '/v1/'
+    require_relative '../../test_support/documentation_oauth_fixture'
+    server = HaveAPI::Server.new(get_opt(:api_module))
+    server.use_version(1)
+    fixture = DocumentationOAuthFixture.configure(server, users: { 1 => { 'escaped-user' => CurrentUserHtmlEscapingSpec::User.new(1, payload) } })
+    server.mount('/')
+    @api = server
+    get "#{fixture.origin}/v1/", {}, 'HTTP_COOKIE' => fixture.header_for(server, version: 1, token: 'escaped-user')
 
     expect(last_response.status).to eq(200)
     expect(last_response.headers['Content-Type']).to include('text/html')

data/spec/documentation/example_variants_spec.rb

@@ -0,0 +1,93 @@
+require 'spec_helper'
+
+RSpec.describe HaveAPI::Server::ServerHelpers, '#documentation_example_variants' do
+  let(:context) do
+    HaveAPI::ClientExample::Context.new(version: 1, host: 'example.test', base_url: 'https://example.test/',
+                                        version_url: 'https://example.test/v1/', description: { resources: {}, authentication: {} })
+  end
+  let(:view) { Object.new.extend(described_class).extend(HaveAPI::DocumentationHelpers) }
+  let(:client) do
+    Class.new(HaveAPI::ClientExample) do
+      id 'custom'
+      def self.render(kind, context:, **)
+        return { status: :limitation, reason: 'Simple limitation' }.freeze if kind == :init && context.detail == :simple
+
+        { status: :code, code: "#{kind}:#{context.detail}" }.freeze
+      end
+    end
+  end
+
+  before do
+    allow(view).to receive(:documentation_clients).and_return([client])
+    allow(view).to receive(:documentation_context) { |_client, **changes| context.with(**changes) }
+  end
+
+  it 'renders Simple once and only declared Thorough while preserving custom limitation behavior' do
+    allow(client).to receive(:render).and_call_original
+    allow(client).to receive(:detail_levels_for).and_call_original
+    variants = view.documentation_example_variants(:init)
+    expect(variants.map { |_client, detail, result| [detail, result[:status]] }).to eq([%i[simple limitation], %i[thorough code]])
+    expect(client).to have_received(:render).with(:init, context: have_attributes(detail: :simple), auth_method: nil, auth_description: nil).once
+    expect(client).to have_received(:render).with(:init, context: have_attributes(detail: :thorough), auth_method: nil, auth_description: nil).once
+    expect(client).to have_received(:detail_levels_for).with(:init, context: have_attributes(detail: :simple),
+                                                                    result: variants.first.last, auth_method: nil, auth_description: nil).once
+    expect(view.documentation_client_metadata.first[:details]).to eq(%w[simple thorough])
+    expect(context.detail).to eq(:simple)
+    expect(context.description).to eq(resources: {}, authentication: {})
+  end
+
+  it 'collects an ordered page union without a prepass or speculative rendering' do
+    allow(client).to receive(:detail_levels_for) { |kind, **| kind == :init ? [:simple].freeze : %i[simple thorough].freeze }
+    allow(client).to receive(:render).and_call_original
+    expect(view.documentation_client_metadata.first[:details]).to eq(['simple'])
+    expect(client).not_to have_received(:render)
+    expect(view.documentation_example_variants(:init).map { |_client, detail, _result| detail }).to eq([:simple])
+    expect(view.documentation_client_metadata.first[:details]).to eq(['simple'])
+    expect(view.documentation_example_variants(:example).map { |_client, detail, _result| detail }).to eq(%i[simple thorough])
+    expect(view.documentation_client_metadata.first[:details]).to eq(%w[simple thorough])
+    expect(view.documentation_example_variants(:init).length).to eq(1)
+    expect(view.documentation_client_metadata.first[:details]).to eq(%w[simple thorough])
+  end
+
+  it 'keeps absent results absent without querying capabilities or advertising a group' do
+    allow(client).to receive(:render).and_return(nil)
+    allow(client).to receive(:detail_levels_for).and_call_original
+    expect(view.documentation_example_variants(:init)).to be_empty
+    expect(client).not_to have_received(:detail_levels_for)
+    expect(view.documentation_client_metadata.first[:details]).to eq(['simple'])
+  end
+
+  it 'rejects malformed custom capability returns rather than inventing a fallback' do
+    [nil, [], [:thorough], ['simple'], %i[thorough simple], %i[simple simple]].each do |levels|
+      allow(client).to receive(:detail_levels_for).and_return(levels)
+      expect { view.documentation_example_variants(:init) }.to raise_error(ArgumentError, 'Invalid documentation example detail levels')
+    end
+  end
+
+  it 'preserves legacy adapter HTML panels when its Simple limitation has distinct Thorough output' do
+    adapter = Object.new
+    def adapter.resolve(**)
+      nil
+    end
+
+    def adapter.render(kind:, context:, **)
+      return { status: :limitation, reason: 'Legacy Simple limitation' } if context.detail == :simple
+
+      { status: :code, code: "legacy #{kind} thorough" }
+    end
+    profile = HaveAPI::ClientExample::Profile.new(language: :typescript, package_name: 'legacy-client', package_version: nil, adapter:)
+    server = HaveAPI::Server.new(Module.new)
+    server.use_version(1)
+    allow(server).to receive(:documentation_client_profiles).and_return(typescript: profile)
+    server.mount('/')
+    response = Rack::MockRequest.new(server.app).get('/v1/', 'HTTP_HOST' => 'example.test')
+    expect(response.status).to eq(200)
+    group = response.body.match(%r{data-example-details="([^"]*)" id="init-examples">(.*?)</div>}m)
+    expect(JSON.parse(CGI.unescapeHTML(group[1])).fetch('typescript-generated')).to eq(%w[simple thorough])
+    expect(group[2]).to include('id="init-typescript-generated"', 'Legacy Simple limitation',
+                                'id="init-typescript-generated-thorough"', 'legacy init thorough')
+    panels = group[2].scan(/data-client="typescript-generated"[^>]*data-detail="([^"]+)"/).flatten
+    expect(panels).to eq(%w[simple thorough])
+    expect(adapter).not_to respond_to(:detail_levels_for)
+  end
+end