haveapi 0.30.0 → 0.30.2

data/spec/client_examples/profiles_spec.rb

@@ -3,22 +3,46 @@ require 'tmpdir'
 
 describe HaveAPI::ClientExample::Profiles do
   let(:profiles) { described_class.new }
+  let(:adapter) do
+    Class.new do
+      def resolve(**); end
+      def render(**); end
+    end.new
+  end
   let(:directory) { Dir.mktmpdir('haveapi-doc-profiles-') }
-  let(:description_path) { File.join(directory, 'description.json') }
-  let(:go_config) do
-    { import_path: 'example.test/widget/client', module_version: 'v1.2.3', description_path:, generator_version: '0.30.0' }
+  let(:description) { { resources: {}, authentication: {}, meta: { namespace: '_meta' } } }
+  let(:server) { instance_double(HaveAPI::Server, versions: [1], root: '/', describe_version: description) }
+
+  def description_path
+    File.join(directory, 'description.json')
+  end
+
+  def config_path
+    File.join(directory, 'generator.toml')
+  end
+
+  def go_config
+    { import_path: 'example.test/widget/client', module_version: 'v1.2.3', description_path:, generator_version: HaveAPI::VERSION }
+  end
+
+  def rust_config
+    { snapshot_path: description_path, generator_config_path: config_path, generator_version: HaveAPI::VERSION }
+  end
+
+  def generator_config
+    { 'crate_name' => 'widget-client', 'crate_version' => '1.2.3' }
   end
-  let(:adapter) { Object.new }
 
   before do
-    File.write(description_path, JSON.generate({ resources: {} }))
+    File.write(description_path, JSON.generate(description))
+    File.write(config_path, 'fixture config')
   end
 
   after { FileUtils.remove_entry(directory) }
 
-  def install_go_adapter
+  def install_go_adapter(version: HaveAPI::VERSION)
     generator = Module.new
-    generator.const_set(:VERSION, '0.30.0')
+    generator.const_set(:VERSION, version)
     documentation = Class.new
     generator.const_set(:Documentation, documentation)
     stub_const('HaveAPI::GoClient', generator)
@@ -27,32 +51,89 @@ describe HaveAPI::ClientExample::Profiles do
     documentation
   end
 
-  it 'needs no optional generator when profiles are absent' do
-    allow(profiles).to receive(:require).and_raise('Unexpected optional dependency')
+  def install_rust_adapter(factories: true)
+    generator = Module.new
+    generator.const_set(:VERSION, HaveAPI::VERSION)
+    documentation = Class.new
+    generator.const_set(:Documentation, documentation)
+    generator.const_set(:Generator, Class.new)
+    generator.const_set(:Model, Module.new)
+    generator.const_set(:Snapshot, Class.new)
+    stub_const('HaveAPI::RustClient', generator)
+    stub_const('Tomlrb', Module.new)
+    allow(Tomlrb).to receive(:load_file).with(config_path).and_return(generator_config)
+    allow(profiles).to receive(:require).with('haveapi/rust_client/documentation').and_return(true)
+    allow(documentation).to receive(:new).and_return(adapter)
+    if factories
+      allow(documentation).to receive_messages(from_description: adapter, from_snapshot: adapter)
+      allow(documentation).to receive(:validate_source) { |source| source }
+      allow(HaveAPI::RustClient::Generator).to receive(:validate_config)
+      allow(HaveAPI::RustClient::Model).to receive(:validate_package)
+    end
+    documentation
+  end
+
+  def finalize
     profiles.mount([1])
+    profiles.finalize(server)
+  end
+
+  it 'needs no optional generator or schema when profiles are absent' do
+    allow(profiles).to receive(:require).and_raise('Unexpected optional dependency')
+    finalize
     expect(profiles).not_to have_received(:require)
+    expect(server).not_to have_received(:describe_version)
     expect(profiles.for_version(1)).to eq({})
     expect(profiles.for_version(1)).to be_frozen
   end
 
-  it 'loads a matching configured adapter once and keeps schema paths out of the public profile' do
+  it 'loads an explicit saved adapter once without rereading it during finalization' do
     documentation = install_go_adapter
     profiles.register(1, go: go_config)
-    profiles.mount([1])
+    expect(profiles.for_version(1)).to be_empty
     File.unlink(description_path)
+    finalize
     profile = profiles.for_version(1).fetch(:go)
     expect(profile).to have_attributes(language: :go, package_name: 'example.test/widget/client', package_version: 'v1.2.3')
     expect(profile).to be_frozen
     expect(profile.adapter).to equal(adapter)
-    expect(documentation).to have_received(:new).once.with(description: { 'resources' => {} }, import_path: 'example.test/widget/client', module_version: 'v1.2.3')
+    expect(documentation).to have_received(:new).once.with(description: JSON.parse(JSON.generate(description)), import_path: 'example.test/widget/client', module_version: 'v1.2.3')
+    expect(server).not_to have_received(:describe_version)
     expect(profile).not_to respond_to(:description_path)
   end
 
+  it 'defaults the generator version and defers automatic Go without inventing an SDK version' do
+    documentation = install_go_adapter
+    config = { import_path: 'example.test/widget/client' }
+    profiles.register(1, go: config)
+    config[:import_path].replace('changed.test/client')
+    expect(documentation).not_to have_received(:new)
+    finalize
+    profile = profiles.for_version(1).fetch(:go)
+    expect(profile.package_name).to eq('example.test/widget/client')
+    expect(profile.package_version).to be_nil
+    expect(documentation).to have_received(:new).with(description: JSON.parse(JSON.generate(description)), import_path: 'example.test/widget/client', module_version: nil)
+    expect(server).to have_received(:describe_version).once
+  end
+
+  it 'permits nil SDK versions and retains explicitly pinned generator versions' do
+    documentation = install_go_adapter(version: '0.29.0')
+    profiles.register(1, go: go_config.merge(module_version: nil, generator_version: '0.29.0'))
+    finalize
+    expect(profiles.for_version(1).fetch(:go).package_version).to be_nil
+    expect(documentation).to have_received(:new).with(description: anything, import_path: anything, module_version: nil)
+  end
+
   it 'rejects unknown languages, malformed fields and unsafe package configuration' do
     expect { profiles.register(1, python: {}) }.to raise_error(described_class::Invalid, /Unknown/)
     expect { profiles.register(1, go: go_config.merge(unexpected: 'value')) }.to raise_error(described_class::Invalid, /fields/)
     expect { profiles.register(1, go: go_config.merge(import_path: "example.test/\nsource")) }.to raise_error(described_class::Invalid, /package/)
-    expect { profiles.register(1, go: go_config.merge(module_version: 'latest')) }.to raise_error(described_class::Invalid, /package/)
+    ['latest', '', 1, false].each do |value|
+      expect { profiles.register(1, go: go_config.merge(module_version: value)) }.to raise_error(described_class::Invalid, /package/)
+    end
+    expect { profiles.register(1, go: go_config.merge(generator_version: nil)) }.to raise_error(described_class::Invalid)
+    expect { profiles.register(1, go: go_config.merge(generator_version: 'latest')) }.to raise_error(described_class::Invalid, /generator version/)
+    expect { profiles.register(1, go: {}) }.to raise_error(described_class::Invalid, /package/)
   end
 
   it 'rejects missing adapters, mismatched generator versions and missing files at registration' do
@@ -63,33 +144,122 @@ describe HaveAPI::ClientExample::Profiles do
     expect { profiles.register(1, go: go_config.merge(description_path: 'relative.json')) }.to raise_error(described_class::Invalid, /absolute local/)
   end
 
-  it 'rejects duplicate profiles, unselected versions and registration after mount' do
+  it 'checks the configured adapter interface' do
+    documentation = install_go_adapter
+    allow(documentation).to receive(:new).and_return(Object.new)
+    expect { profiles.register(1, go: go_config) }.to raise_error(described_class::Invalid, /adapter interface/)
+  end
+
+  it 'does not leave a partially registered language set after an invalid second profile' do
+    install_go_adapter
+    expect { profiles.register(1, go: go_config, rust: { unknown: 'field' }) }.to raise_error(described_class::Invalid)
+    profiles.register(1, go: go_config)
+    finalize
+    expect(profiles.for_version(1).keys).to eq([:go])
+  end
+
+  it 'rejects duplicates and registration after mounting starts' do
     install_go_adapter
     profiles.register(1, go: go_config)
     expect { profiles.register('1', go: go_config) }.to raise_error(described_class::Invalid, /Duplicate/)
-    expect { profiles.mount([2]) }.to raise_error(described_class::Invalid, /unavailable API version/)
     profiles.mount([1])
     expect { profiles.register(2, go: go_config) }.to raise_error(described_class::Invalid, /already mounted/)
+    profiles.finalize(server)
+    expect { profiles.finalize(server) }.to raise_error(described_class::Invalid, /not ready/)
   end
 
-  it 'loads Rust TOML configuration and rejects a snapshot bound to another API version at mount' do
-    generator = Module.new
-    generator.const_set(:VERSION, '0.30.0')
-    documentation = Class.new
-    generator.const_set(:Documentation, documentation)
-    stub_const('HaveAPI::RustClient', generator)
-    toml = Module.new
-    stub_const('Tomlrb', toml)
-    config_path = File.join(directory, 'generator.toml')
-    File.write(config_path, 'fixture config')
-    File.write(description_path, JSON.generate({ api_version: '2' }))
-    config = { 'crate_name' => 'widget-client', 'crate_version' => '1.2.3' }
-    allow(toml).to receive(:load_file).with(config_path).and_return(config)
-    allow(profiles).to receive(:require).with('haveapi/rust_client/documentation').and_return(true)
-    allow(documentation).to receive(:new).and_return(adapter)
-    profiles.register(1, rust: { snapshot_path: description_path, generator_config_path: config_path, generator_version: '0.30.0' })
-    expect(documentation).to have_received(:new).with(snapshot: { 'api_version' => '2' }, config:)
+  it 'rejects profiles for an unavailable version' do
+    install_go_adapter
+    profiles.register(1, go: go_config)
+    expect { profiles.mount([2]) }.to raise_error(described_class::Invalid, /unavailable API version/)
+    expect(profiles.for_version(1)).to be_empty
+  end
+
+  it 'preserves legacy Rust construction even without the new factories' do
+    documentation = install_rust_adapter(factories: false)
+    File.write(description_path, JSON.generate({ api_version: '1' }))
+    profiles.register(1, rust: rust_config)
+    finalize
+    expect(documentation).to have_received(:new).with(snapshot: { 'api_version' => '1' }, config: generator_config)
     expect(profiles.for_version(1).fetch(:rust)).to have_attributes(package_name: 'widget-client', package_version: '1.2.3')
+  end
+
+  it 'rejects a saved Rust snapshot for a different selected API version at mount' do
+    install_rust_adapter
+    File.write(description_path, JSON.generate({ api_version: '2' }))
+    profiles.register(1, rust: rust_config)
     expect { profiles.mount([1]) }.to raise_error(described_class::Invalid, /snapshot API version mismatch/)
+    expect(profiles.for_version(1)).to be_empty
+  end
+
+  it 'validates inline Rust identity and source before building from the mounted description' do
+    documentation = install_rust_adapter
+    source = { git: 'https://example.test/widget-client', rev: 'a' * 40 }
+    profiles.register(1, rust: { crate_name: 'widget-client', source: })
+    expect(HaveAPI::RustClient::Model).to have_received(:validate_package).with(crate_name: 'widget-client', crate_version: nil)
+    expect(documentation).to have_received(:validate_source).with(source)
+    expect(documentation).not_to have_received(:from_description)
+    finalize
+    expect(documentation).to have_received(:from_description).with(description: anything, api_version: '1', protocol_version: HaveAPI::PROTOCOL_VERSION,
+                                                                   mount_path: '/', crate_name: 'widget-client', crate_version: nil, source:)
+    expect(profiles.for_version(1).fetch(:rust).package_version).to be_nil
+  end
+
+  it 'supports an inline Rust identity with a saved snapshot and optional explicit SDK version' do
+    documentation = install_rust_adapter
+    snapshot = { 'api_version' => '1' }
+    File.write(description_path, JSON.generate(snapshot))
+    profiles.register(1, rust: { snapshot_path: description_path, crate_name: 'widget-client', crate_version: '1.2.3' })
+    finalize
+    expect(documentation).to have_received(:from_snapshot).with(snapshot:, crate_name: 'widget-client', crate_version: '1.2.3', source: nil)
+    expect(server).not_to have_received(:describe_version)
+  end
+
+  it 'validates full legacy TOML before using it with an automatic Rust description' do
+    documentation = install_rust_adapter
+    snapshot = { 'api_version' => '1' }
+    allow(HaveAPI::RustClient::Snapshot).to receive(:from_description).and_return(snapshot)
+    profiles.register(1, rust: { generator_config_path: config_path })
+    expect(HaveAPI::RustClient::Generator).to have_received(:validate_config).with(generator_config)
+    finalize
+    expect(HaveAPI::RustClient::Snapshot).to have_received(:from_description).with(description: anything, api_version: '1', protocol_version: HaveAPI::PROTOCOL_VERSION,
+                                                                                   mount_path: '/', source_url: 'https://haveapi.invalid/v1/', profile: 'server-documentation')
+    expect(documentation).to have_received(:new).with(snapshot:, config: generator_config)
+  end
+
+  it 'rejects automatic and inline modes when an older Rust generator lacks their factories' do
+    install_rust_adapter(factories: false)
+    expect { profiles.register(1, rust: { generator_config_path: config_path }) }.to raise_error(described_class::Invalid, /does not support/)
+    expect { profiles.register(1, rust: { crate_name: 'widget-client', snapshot_path: description_path }) }.to raise_error(described_class::Invalid, /does not support/)
+  end
+
+  it 'rejects conflicting Rust identities and unknown source profile fields' do
+    install_rust_adapter
+    expect { profiles.register(1, rust: rust_config.merge(crate_name: 'widget-client')) }.to raise_error(described_class::Invalid, /Conflicting/)
+    expect { profiles.register(1, rust: rust_config.merge(crate_version: nil)) }.to raise_error(described_class::Invalid, /Conflicting/)
+    expect { profiles.register(1, rust: { crate_name: 'widget-client', branch: 'main' }) }.to raise_error(described_class::Invalid, /fields/)
+  end
+
+  it 'captures one private structural schema per version shared by automatic profiles' do
+    go = install_go_adapter
+    rust = install_rust_adapter
+    profiles.register(1, go: { import_path: 'example.test/client' }, rust: { crate_name: 'widget-client' })
+    finalize
+    expect(server).to have_received(:describe_version).once do |context|
+      expect(context).to have_attributes(server:, version: 1, current_user: nil, endpoint: false, doc: true)
+    end
+    expect(go).to have_received(:new).with(description: anything, import_path: anything, module_version: nil)
+    expect(rust).to have_received(:from_description).with(description: anything, api_version: '1', protocol_version: anything, mount_path: '/', crate_name: anything, crate_version: nil, source: nil)
+  end
+
+  it 'publishes no partial profiles and hides private diagnostics when finalization fails' do
+    install_go_adapter
+    rust = install_rust_adapter
+    allow(rust).to receive(:from_description).and_raise('HIDDEN_SCHEMA_DEFAULT')
+    profiles.register(1, go: { import_path: 'example.test/client' }, rust: { crate_name: 'widget-client' })
+    profiles.mount([1])
+    expect { profiles.finalize(server) }.to raise_error(described_class::Invalid, 'Configured documentation client schema or configuration is invalid')
+    expect(profiles.for_version(1)).to be_empty
+    expect { profiles.register(1, go: go_config) }.to raise_error(described_class::Invalid, /already mounted/)
   end
 end

data/spec/client_examples/structural_schema_spec.rb

@@ -0,0 +1,48 @@
+require 'spec_helper'
+
+describe HaveAPI::ClientExample::Profiles do
+  let(:schema) { HaveAPI::ClientExample.const_get(:StructuralSchema) }
+  let(:data) { { description: 'data description', default: { examples: ['data example'] }, message: 'data message' } }
+  let(:parameter) do
+    { type: 'Custom', default: data, description: 'private prose', label: 'private label',
+      validators: { include: { values: [data], message: 'private validation message' }, custom: data }, format: data }
+  end
+  let(:description) do
+    action = { path: '/v1/widgets/', input: { layout: :hash, parameters: { default: parameter } },
+               output: { parameters: {} }, meta: { global: { input: { parameters: { example: parameter } } } },
+               description: 'private action prose', examples: [{ request: data }] }
+    resource = { description: 'private resource prose', actions: { index: action }, resources: {} }
+    { resources: { widget: resource }, authentication: { token: { description: 'private auth prose', resources: { token: resource } } } }
+  end
+
+  it 'copies structural locations and strips defaults and prose without changing the server description' do
+    before = JSON.generate(description)
+    result = schema.copy(description)
+    action = result.dig('resources', 'widget', 'actions', 'index')
+    expect(action).not_to have_key('description')
+    expect(action).not_to have_key('examples')
+    expect(result.dig('resources', 'widget')).not_to have_key('description')
+    expect(result.dig('authentication', 'token')).not_to have_key('description')
+    expect(action.dig('input', 'parameters', 'default')).not_to have_key('default')
+    expect(action.dig('meta', 'global', 'input', 'parameters', 'example')).not_to have_key('default')
+    expect(result.dig('authentication', 'token', 'resources', 'token', 'actions', 'index')).not_to have_key('examples')
+    expect(JSON.generate(description)).to eq(before)
+    expect(description).not_to be_frozen
+    expect(result).to be_frozen
+    expect(action.dig('input', 'parameters', 'default')).to be_frozen
+  end
+
+  it 'retains parameter names, layouts, associations and arbitrary validator/Custom data verbatim' do
+    parameter[:resource] = %w[widget]
+    parameter[:choices] = { path: '/v1/widgets/', method: 'GET' }
+    result = schema.copy(description)
+    copied = result.dig('resources', 'widget', 'actions', 'index', 'input', 'parameters', 'default')
+    expect(copied).to include('type' => 'Custom', 'resource' => ['widget'], 'choices' => { 'path' => '/v1/widgets/', 'method' => 'GET' })
+    expect(copied['format']).to eq(JSON.parse(JSON.generate(data)))
+    expect(copied.dig('validators', 'include', 'values')).to eq([JSON.parse(JSON.generate(data))])
+    expect(copied.dig('validators', 'custom')).to eq(JSON.parse(JSON.generate(data)))
+    expect(copied.dig('validators', 'include')).not_to have_key('message')
+    expect(result.dig('resources', 'widget', 'actions', 'index', 'input', 'layout')).to eq('hash')
+    expect(result.dig('resources', 'widget', 'actions', 'index', 'path')).to eq('/v1/widgets/')
+  end
+end

data/spec/documentation/client_examples_spec.rb

@@ -79,4 +79,14 @@ describe HaveAPI::ClientExample do
     expect(selected.description[:resources]).to have_key('widget')
     expect(selected.sample[:response]).to eq(name: 'documented widget')
   end
+
+  it 'prints a package identity without inventing an omitted version and escapes it once' do
+    profile = HaveAPI::ClientExample::Profile.new(language: :go, package_name: 'example.test/<client>&', package_version: nil, adapter: Object.new)
+    allow(app.settings.api_server).to receive(:documentation_client_profiles).and_return({ go: profile })
+    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).not_to include('example.test/<client>', '&amp;lt;', 'version = "latest"')
+  end
 end

data/spec/documentation/performance_spec.rb

@@ -0,0 +1,79 @@
+require 'spec_helper'
+require 'base64'
+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)
+  end
+  let(:contexts) { [] }
+  let(:help_inputs) { [] }
+
+  before do
+    HaveAPI::ClientExample.clients.each do |client|
+      allow(client).to receive(:render).and_wrap_original do |original, kind, context:, **arguments|
+        contexts << context
+        original.call(kind, context:, **arguments)
+      end
+    end
+    allow(server).to receive(:describe_version).and_wrap_original do |original, *arguments|
+      original.call(*arguments).tap do |help|
+        help_inputs << [help, Marshal.dump(help)]
+      end
+    end
+  end
+
+  def request_as(user)
+    contexts.clear
+    Rack::MockRequest.new(server.app).get(
+      '/benchmark/api/v1/', 'HTTP_HOST' => 'example.test',
+                            'HTTP_AUTHORIZATION' => "Basic #{Base64.strict_encode64("#{user}:fixture-only")}"
+    )
+  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')
+    expect(contexts.length).to be > 20
+    description = contexts.first.description
+    contexts.each { |context| expect(context.description).to equal(description) }
+    expect(description).to be_frozen
+    description
+  end
+
+  it 'shares one description across real panels and isolates sequential admin/member/admin requests' do
+    first_admin = request_as('admin')
+    admin_description = expect_shared_request(first_admin)
+    privileged_markers = %w[ADMIN_ONLY_ACTION ADMIN_ONLY_DEFAULT ADMIN_ONLY_REQUEST ADMIN_ONLY_RESPONSE
+                            ADMIN_ONLY_ACTION_SAMPLE admin_field admin_only]
+    privileged_markers.each { |marker| expect(first_admin.body).to include(marker) }
+
+    member = request_as('member')
+    member_description = expect_shared_request(member)
+    expect(member_description).not_to equal(admin_description)
+    privileged_markers.each { |marker| expect(member.body).not_to include(marker) }
+    expect(JSON.generate(contexts.map { |context| [context.description, context.action, context.sample] }))
+      .not_to match(/ADMIN_ONLY_|admin_field|admin_only/)
+    expect(member_description[:resources]['resource0'][:actions]).not_to have_key('admin_only')
+    selected = contexts.find { |context| context.action_name == 'action0' }
+    expect(selected.action[:input][:parameters]).not_to have_key(:admin_field)
+    expect(selected.sample[:request]).to include(enabled: false, count: 0, nullable: nil, value0: '')
+
+    last_admin = request_as('admin')
+    restored_description = expect_shared_request(last_admin)
+    expect(restored_description).not_to equal(admin_description)
+    expect(restored_description).not_to equal(member_description)
+    expect(restored_description).to eq(admin_description)
+    privileged_markers.each { |marker| expect(last_admin.body).to include(marker) }
+
+    help_inputs.each do |help, original|
+      expect(Marshal.dump(help)).to eq(original)
+      expect(help).not_to be_frozen
+      expect(help[:resources]).not_to be_frozen
+      expect(help[:resources]['resource0'][:actions]['action0'][:examples].first[:request]).not_to be_frozen
+    end
+  end
+end