haveapi 0.29.12 → 0.30.0

data/spec/client_examples/profiles_spec.rb

@@ -0,0 +1,95 @@
+require 'spec_helper'
+require 'tmpdir'
+
+describe HaveAPI::ClientExample::Profiles do
+  let(:profiles) { described_class.new }
+  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' }
+  end
+  let(:adapter) { Object.new }
+
+  before do
+    File.write(description_path, JSON.generate({ resources: {} }))
+  end
+
+  after { FileUtils.remove_entry(directory) }
+
+  def install_go_adapter
+    generator = Module.new
+    generator.const_set(:VERSION, '0.30.0')
+    documentation = Class.new
+    generator.const_set(:Documentation, documentation)
+    stub_const('HaveAPI::GoClient', generator)
+    allow(profiles).to receive(:require).with('haveapi/go_client/documentation').and_return(true)
+    allow(documentation).to receive(:new).and_return(adapter)
+    documentation
+  end
+
+  it 'needs no optional generator when profiles are absent' do
+    allow(profiles).to receive(:require).and_raise('Unexpected optional dependency')
+    profiles.mount([1])
+    expect(profiles).not_to have_received(:require)
+    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
+    documentation = install_go_adapter
+    profiles.register(1, go: go_config)
+    profiles.mount([1])
+    File.unlink(description_path)
+    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(profile).not_to respond_to(:description_path)
+  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/)
+  end
+
+  it 'rejects missing adapters, mismatched generator versions and missing files at registration' do
+    allow(profiles).to receive(:require).and_raise(LoadError)
+    expect { profiles.register(1, go: go_config) }.to raise_error(described_class::Invalid, /not installed/)
+    install_go_adapter
+    expect { profiles.register(1, go: go_config.merge(generator_version: '0.29.0')) }.to raise_error(described_class::Invalid, /version mismatch/)
+    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
+    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/)
+  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:)
+    expect(profiles.for_version(1).fetch(:rust)).to have_attributes(package_name: 'widget-client', package_version: '1.2.3')
+    expect { profiles.mount([1]) }.to raise_error(described_class::Invalid, /snapshot API version mismatch/)
+  end
+end

data/spec/client_examples/rust_client_spec.rb

@@ -0,0 +1,75 @@
+require 'spec_helper'
+require 'haveapi/documentation_context'
+require 'haveapi/client_examples/rust_client'
+
+class RustDocumentationAdapterFixture
+  def render(kind:, context:, mode:, auth_method: nil, auth_description: nil); end
+end
+
+describe HaveAPI::ClientExamples::RustClient do
+  let(:adapter) { instance_spy(RustDocumentationAdapterFixture) }
+  let(:profile) { Struct.new(:language, :adapter).new(:rust, adapter).freeze }
+  let(:context) do
+    HaveAPI::ClientExample::Context.new(
+      version: '1.0', host: 'example.test', base_url: 'https://example.test/mount/',
+      version_url: 'https://example.test/mount/v1.0/', description: {},
+      resource_path: ['widget'], action_name: 'update', action: {}, sample: { request: {} }, profile:
+    )
+  end
+  let(:code) { { status: :code, code: 'generated Rust' }.freeze }
+
+  it 'registers separate stable variants sharing the Rust grammar' do
+    expect(HaveAPI::ClientExamples::RustAsyncClient.id).to eq('rust-async')
+    expect(HaveAPI::ClientExamples::RustBlockingClient.id).to eq('rust-blocking')
+    expect(HaveAPI::ClientExamples::RustAsyncClient.code).to eq(:rust)
+    expect(HaveAPI::ClientExamples::RustBlockingClient.code).to eq(:rust)
+    expect(HaveAPI::ClientExamples::RustAsyncClient.order).to eq(17)
+    expect(HaveAPI::ClientExamples::RustBlockingClient.order).to eq(18)
+  end
+
+  it 'hides all Rust variants without the matching configured profile' do
+    [HaveAPI::ClientExamples::RustAsyncClient, HaveAPI::ClientExamples::RustBlockingClient].each do |renderer|
+      expect(renderer.available?(context.with(profile: nil))).to be(false)
+      expect(renderer.available?(context.with(profile: Struct.new(:language).new(:go)))).to be(false)
+      expect(renderer.available?(context)).to be(true)
+    end
+  end
+
+  it 'passes immutable authorized init context to the pure adapter' do
+    allow(adapter).to receive(:render).and_return(code)
+    expect(HaveAPI::ClientExamples::RustAsyncClient.render(:init, context:)).to eq(code)
+    expect(adapter).to have_received(:render).with(kind: :init, context:, mode: :async)
+  end
+
+  it 'keeps authentication provider and description exact for blocking rendering' do
+    allow(adapter).to receive(:render).and_return(code)
+    expect(HaveAPI::ClientExamples::RustBlockingClient.render(
+             :auth, context:, auth_method: :token, auth_description: { http_header: 'X-Token' }
+           )).to eq(code)
+    expect(adapter).to have_received(:render).with(kind: :auth, context:, mode: :blocking,
+                                                   auth_method: :token, auth_description: { http_header: 'X-Token' })
+  end
+
+  it 'binds the exact filtered sample when using the retained positional API' do
+    sample = { request: { name: 'authorized' } }
+    renderer = HaveAPI::ClientExamples::RustAsyncClient.new('example.test', 'https://example.test/', '1.0')
+    renderer.with_context(context)
+    allow(adapter).to receive(:render).and_return(code)
+    expect(renderer.example(sample)).to eq(code)
+    expect(adapter).to have_received(:render).with(kind: :example, mode: :async, context: have_attributes(sample: sample))
+    expect(renderer.context.sample).to be_frozen
+  end
+
+  it 'preserves a concise adapter limitation without fabricating source' do
+    result = { status: :limitation, reason: 'This sample needs an unsupported SDK capability.' }.freeze
+    allow(adapter).to receive(:render).and_return(result)
+    expect(HaveAPI::ClientExamples::RustAsyncClient.render(:example, context:)).to eq(result)
+  end
+
+  it 'retains callable legacy constructor methods even without a profile' do
+    renderer = HaveAPI::ClientExamples::RustAsyncClient.new('example.test', 'https://example.test/', '1.0')
+    expect(renderer.init).to include(status: :limitation)
+    expect(renderer.auth(:basic, {})).to include(status: :limitation)
+    expect(renderer.example({})).to include(status: :limitation)
+  end
+end

data/spec/client_examples/syntax_spec.rb

@@ -71,7 +71,8 @@ describe HaveAPI::ClientExamples do
   end
 
   it 'generates valid JavaScript' do
-    source = HaveAPI::ClientExamples::JsClient.new(*client_args).example(sample)
+    result = HaveAPI::ClientExamples::JsClient.new(*client_args).example(sample)
+    source = result.is_a?(Hash) ? result.fetch(:code) : result
     status, output = syntax_check(%w[node --check], source, '.mjs')
 
     expect(status).to be_success, output

data/spec/documentation/auth_filtering_spec.rb

@@ -276,6 +276,18 @@ describe DocAuthFilteringSpec do
       expect(examples.size).to eq(1)
       expect(examples.first[:response][:msg]).to eq('ADMIN_ONLY_RESULT')
     end
+
+    it 'does not retain privileged sample data across HTML documentation requests' do
+      login('admin', 'pass')
+      get '/v1/'
+      expect(last_response.status).to eq(200)
+      expect(last_response.body).to include('ADMIN_ONLY_RESULT')
+
+      login('user', 'pass')
+      get '/v1/'
+      expect(last_response.status).to eq(200)
+      expect(last_response.body).not_to include('ADMIN_ONLY_RESULT')
+    end
   end
 end
 

data/spec/documentation/client_examples_spec.rb

@@ -0,0 +1,82 @@
+require 'spec_helper'
+
+describe HaveAPI::ClientExample do
+  api do
+    define_resource(:Widget) do
+      version 1
+      auth false
+
+      define_action(:Index, superclass: HaveAPI::Actions::Default::Index) do
+        authorize { allow }
+      end
+
+      define_action(:Show) do
+        route '{widget_id}'
+        http_method :get
+        output(:hash) { string :name }
+        authorize { allow }
+
+        # rubocop:disable RSpec/NoExpectationExample
+        example 'sample' do
+          path_params 1
+          response({ name: 'documented widget' })
+        end
+        # rubocop:enable RSpec/NoExpectationExample
+      end
+    end
+  end
+
+  default_version 1
+
+  it 'keeps maintained renderers registered and removes File system' do
+    labels = described_class.clients.map(&:label)
+    expect(labels).to include('Ruby', 'PHP', 'CLI', 'curl', 'HTTP')
+    expect(labels).not_to include('File system')
+  end
+
+  it 'omits the unmaintained client tab and overview link from generated HTML' do
+    get '/v1/'
+
+    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>')
+  end
+
+  it 'hides unconfigured Go and Rust SDKs in overview, initialization, authentication and actions' do
+    get '/v1/'
+    expect(last_response.status).to eq(200)
+    expect(last_response.body).not_to include('clients/go', 'clients/rust', 'init-go', 'init-rust', '>Go</h', '>Rust (')
+    expect(last_response.body).to include('init-javascript-callback', 'init-typescript-async', 'init-python-sync')
+    expect(last_response.body).to include('example-widget-show-0-javascript-callback')
+  end
+
+  it 'uses the configured profile consistently for every panel and escapes limitations once' do
+    profiles = { go: HaveAPI::ClientExample::Profile.new(language: :go, package_name: 'example.test/client', package_version: 'v1.2.3', adapter: Object.new) }
+    allow(app.settings.api_server).to receive(:documentation_client_profiles).and_return(profiles)
+    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).not_to include('Unsupported <sample>', 'clients/rust', 'init-rust')
+  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(:render) do |kind, context:, **_kwargs|
+      contexts << [kind, context]
+      { status: :code, code: context.version_url }
+    end
+    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')
+    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/')
+    expect(selected.version_url).to eq('http://example.org/mounted/api/v1/')
+    expect(selected.resource_path).to eq(['widget'])
+    expect(selected.description[:resources]).to have_key('widget')
+    expect(selected.sample[:response]).to eq(name: 'documented widget')
+  end
+end

data/spec/packaging_spec.rb

@@ -9,7 +9,7 @@ require 'tmpdir'
 
 describe HaveAPI::Server do
   def required_docs
-    %w[json-schema.html protocol.md create-client.md typed-input-validation.md protocol.png]
+    %w[json-schema.html protocol.md create-client.md typed-input-validation.md client-examples.md protocol.png]
   end
 
   before(:context) do
@@ -53,6 +53,13 @@ describe HaveAPI::Server do
       required_docs.each do |name|
         expect(File.read(File.join(dir, 'doc', name))).not_to be_empty
       end
+      %w[
+        lib/haveapi/documentation_context.rb lib/haveapi/documentation_clients.rb
+        lib/haveapi/views/version_page/client_result.erb
+        lib/haveapi/public/js/highlight.pack.js lib/haveapi/public/js/highlight-LICENSE
+      ].each do |name|
+        expect(File.size?(File.join(dir, name))).not_to be_nil
+      end
 
       script = <<~RUBY
         require 'haveapi'
@@ -76,7 +83,7 @@ describe HaveAPI::Server do
         server.use_version(1)
         server.mount('/')
         request = Rack::MockRequest.new(server.app)
-        responses = %w[/doc/json-schema /doc/protocol.md /doc/create-client.md].to_h do |path|
+        responses = %w[/doc/json-schema /doc/protocol.md /doc/create-client.md /doc/client-examples.md /js/highlight-LICENSE].to_h do |path|
           response = request.get(path, 'HTTP_HOST' => 'localhost')
           [path, { status: response.status, type: response.content_type, body: response.body }]
         end
@@ -112,11 +119,13 @@ describe HaveAPI::Server do
       {
         '/doc/json-schema' => 'Envelope',
         '/doc/protocol.md' => 'Protocol definition',
-        '/doc/create-client.md' => 'Client definition'
+        '/doc/create-client.md' => 'Client definition',
+        '/doc/client-examples.md' => 'Client examples',
+        '/js/highlight-LICENSE' => 'Copyright'
       }.each do |path, heading|
         response = result.fetch('responses').fetch(path)
         expect(response.fetch('status')).to eq(200), "Packaged route failed: #{path}"
-        expect(response.fetch('type')).to include('text/html')
+        expect(response.fetch('type')).to include('text/html') unless path == '/js/highlight-LICENSE'
         expect(response.fetch('body')).to include(heading)
       end
     end

data/test_support/dynamic_documentation_api.rb

@@ -0,0 +1,171 @@
+require 'json'
+require_relative '../lib/haveapi'
+
+module DynamicDocumentationAPI
+  PAYLOAD = { 'text' => "DOC_LITERAL žluťoučký \"quote\"\\\n</script>",
+              '__proto__' => { 'constructor' => [false, 0, nil, ''] } }.freeze
+  def self.receipts
+    @receipts ||= []
+  end
+  User = Struct.new(:login)
+
+  class RequestTrace
+    def initialize(app, output: $stderr)
+      @app = app
+      @output = output
+    end
+
+    def call(env)
+      status, headers, body = @app.call(env)
+      @output.puts("DYNAMIC_DOCUMENTATION_REQUEST #{JSON.generate({ method: env['REQUEST_METHOD'], path: env['PATH_INFO'], status: })}")
+      [status, headers, body]
+    end
+  end
+
+  class BasicProvider < HaveAPI::Authentication::Basic::Provider
+    protected
+
+    def find_user(_request, username, password)
+      User.new(username) if username == 'fixture-user' && password == 'fixture-password'
+    end
+  end
+
+  class TokenConfig < HaveAPI::Authentication::Token::Config
+    request do
+      handle do |request, result|
+        if request.input[:user] == 'fixture-user' && request.input[:password] == 'fixture-password'
+          result.token = 'fixture-challenge'
+          result.next_action = 'verify'
+          result.complete = false
+          result.valid_to = Time.now + 3600
+          result.ok
+        else
+          result.error = 'Invalid fixture credentials'
+          result
+        end
+      end
+    end
+
+    action :verify do
+      input { string :code, required: true }
+      handle do |request, result|
+        if request.token == 'fixture-challenge' && request.input[:code] == '123456'
+          result.token = 'fixture-token'
+          result.complete = true
+          result.valid_to = Time.now + 3600
+          result.ok
+        else
+          result.error = 'Invalid fixture challenge'
+          result
+        end
+      end
+    end
+
+    renew { handle { |_request, result| result.ok } }
+    revoke { handle { |_request, result| result.ok } }
+
+    def find_user_by_token(_request, token)
+      User.new('fixture-user') if token == 'fixture-token'
+    end
+  end
+
+  TokenProvider = HaveAPI::Authentication::Token.with_config(TokenConfig)
+
+  class OAuth2Provider < HaveAPI::Authentication::Base
+    auth_method :oauth2
+
+    def describe
+      { http_header: 'X-Fixture-OAuth2' }
+    end
+
+    def authenticate(request)
+      value = request.env['HTTP_X_FIXTURE_OAUTH2'] || request.env['HTTP_AUTHORIZATION']&.delete_prefix('Bearer ')
+      User.new('fixture-user') if value == 'fixture-access-token'
+    end
+  end
+
+  module Resources
+    class Constructor < HaveAPI::Resource
+      version '2'
+      route 'parents'
+
+      class Resources < HaveAPI::Resource
+        route '{parent_id}/children'
+
+        class New < HaveAPI::Action
+          route '{widget_id}'
+          http_method :post
+          auth true
+          authorize { |user| user ? allow : deny }
+
+          input(:hash, namespace: :widget) do
+            string :name
+            bool :enabled
+            integer :count
+            string :nullable, nullable: true
+            string :omitted
+            custom :payload
+          end
+
+          output(:hash, namespace: :widget) do
+            string :marker
+            custom :payload
+          end
+
+          example 'literal success' do
+            path_params 7, 'name with space'
+            request(name: '', enabled: false, count: 0, nullable: nil, payload: DynamicDocumentationAPI::PAYLOAD)
+            response(marker: 'DOC_SUCCESS', payload: DynamicDocumentationAPI::PAYLOAD)
+          end
+
+          example 'literal failure' do
+            path_params 7, 'name with space'
+            request(name: '', enabled: false, count: -1, nullable: nil, payload: DynamicDocumentationAPI::PAYLOAD)
+            status false
+            message 'DOC_FAILURE'
+            errors count: ['DOC_FAILURE']
+          end
+          def exec
+            DynamicDocumentationAPI.receipts << { path: path_params.values_at('parent_id', 'widget_id'), input: }
+            error!('DOC_FAILURE', { count: ['DOC_FAILURE'] }, http_status: 400) if input[:count] < 0
+
+            { marker: 'DOC_SUCCESS', payload: input[:payload] }
+          end
+        end
+      end
+    end
+  end
+
+  def self.build
+    HaveAPI.implicit_version = '2'
+    api = HaveAPI::Server.new(Resources)
+    api.use_version('2')
+    api.default_version = '2'
+    api.auth_chain << BasicProvider
+    api.auth_chain << TokenProvider
+    api.auth_chain << OAuth2Provider
+    api.connect_hook(:pre_mount) do |ret, _server, sinatra|
+      sinatra.get '/__acceptance_receipts' do
+        content_type 'application/json'
+        JSON.generate(DynamicDocumentationAPI.receipts)
+      end
+      ret
+    end
+    api.mount('/mount/')
+    api
+  end
+end
+
+if $0 == __FILE__
+  require 'webrick'
+  require 'rackup'
+  server = nil
+  trap('TERM') { server&.shutdown }
+  app = DynamicDocumentationAPI::RequestTrace.new(DynamicDocumentationAPI.build.app)
+  Rackup::Handler::WEBrick.run(app, Host: '127.0.0.1', Port: 0,
+                                    AccessLog: [], Logger: WEBrick::Log.new($stderr, WEBrick::Log::WARN)) do |instance|
+    server = instance
+    puts "DYNAMIC_DOCUMENTATION_READY http://127.0.0.1:#{server.listeners.first.addr[1]}"
+    $stdout.flush
+  end
+end

data/test_support/dynamic_protocol_spec.rb

@@ -0,0 +1,133 @@
+require 'spec_helper'
+require 'open3'
+require_relative '../spec/client_examples/dynamic_fixture'
+
+RSpec.describe HaveAPI::ClientExamples::PythonClient do
+  include DynamicExampleFixture
+
+  let(:renderers) { [described_class, HaveAPI::ClientExamples::PythonAsyncClient] }
+
+  def python_request(action, params)
+    root = File.expand_path('../../..', __dir__)
+    source = <<~PY
+      import json
+      import sys
+      from haveapi_client import HaveAPIError
+      from haveapi_client._protocol import CallContext, build_request, lookup_action, parse_description
+
+      fixture = json.load(sys.stdin)
+      try:
+          description = parse_description({
+              "status": True, "version": "2.0",
+              "response": {"resources": {"widget": {"actions": {"show": fixture["action"]}}}}
+          })
+          action = lookup_action(description, ("widget",), "show")
+          context = CallContext(action, (), dict(zip(action.path_parameters, fixture["path_params"])), 1)
+          result = build_request(description, context, base_url="https://api.example.test/", params=fixture["params"])
+          print(json.dumps({"query": result.query, "body": json.loads(result.content) if result.content else None}))
+      except HaveAPIError as error:
+          print(json.dumps({"error": type(error).__name__, "message": str(error)}))
+    PY
+    output, status = Open3.capture2e(
+      { 'PYTHONPATH' => File.join(root, 'clients/python/src'), 'PYTHONDONTWRITEBYTECODE' => '1' },
+      File.join(root, 'clients/python/.venv/bin/python'), '-c', source,
+      stdin_data: JSON.generate({ action:, params:, path_params: dynamic_sample[:path_params] })
+    )
+    expect(status).to be_success, output
+    JSON.parse(output)
+  end
+
+  it 'limits GET Custom structures rejected by the real Python request builder in both modes' do
+    action = dynamic_action.merge(method: 'GET', input: {
+      layout: :hash, namespace: :widget, parameters: { payload: { type: 'Custom' } }
+    })
+    [{ enabled: false, count: 0 }, [], {}, { nested: [] }, [{ a: 'one' }, { b: 'two' }], false, 0].each do |value|
+      sample = dynamic_sample.merge(request: { payload: value })
+      expect(python_request(action, sample[:request])).to include('error' => 'ValidationError')
+      renderers.each do |renderer|
+        result = renderer.render(:example, context: dynamic_context(action:, sample:))
+        expect(result[:status]).to eq(:limitation)
+        expect(result[:reason]).to include('Python GET', 'flat scalar')
+      end
+    end
+  end
+
+  it 'preserves flat GET scalars and nullable Custom values supported by the real builder' do
+    action = dynamic_action.merge(method: 'GET', input: {
+      layout: :hash, namespace: :widget,
+      parameters: { name: { type: 'String' }, enabled: { type: 'Boolean' }, count: { type: 'Integer' },
+                    nullable: { type: 'String', nullable: true }, payload: { type: 'Custom', nullable: true } }
+    })
+    [nil, ''].each do |payload|
+      params = { name: 'a&ž', enabled: false, count: 0, nullable: nil, payload: }
+      expect(python_request(action, params)).to include('query' => [
+                                                          ['widget[name]', 'a&ž'], ['widget[enabled]', 'false'], ['widget[count]', '0'],
+                                                          ['widget[nullable]', ''], ['widget[payload]', '']
+                                                        ])
+      renderers.each do |renderer|
+        result = renderer.render(:example, context: dynamic_context(action:, sample: dynamic_sample.merge(request: params)))
+        expect(result[:status]).to eq(:code), result.inspect
+        expect(result[:code]).to include('"enabled": False', '"count": 0', '"nullable": None')
+      end
+    end
+  end
+
+  it 'documents a conservative GET subset and rejects ambiguous query key components' do
+    cases = [
+      [{ payload: { nested: 'supported by client' } }, :widget, { payload: { type: 'Custom' } }, false],
+      [{ payload: ['supported by client'] }, :widget, { payload: { type: 'Custom' } }, false],
+      [{ payload: 'text' }, 'bad[name]', { payload: { type: 'String' } }, true],
+      [{ 'bad[name]' => 'text' }, :widget, { 'bad[name]' => { type: 'String' } }, true],
+      [{ '' => 'text' }, :widget, { '' => { type: 'String' } }, true]
+    ]
+    cases.each do |params, namespace, parameters, rejected|
+      action = dynamic_action.merge(method: 'GET', input: { layout: :hash, namespace:, parameters: })
+      expect(python_request(action, params).has_key?('error')).to eq(rejected)
+      renderers.each do |renderer|
+        expect(renderer.render(:example, context: dynamic_context(action:, sample: dynamic_sample.merge(request: params)))[:status]).to eq(:limitation)
+      end
+    end
+  end
+
+  it 'leaves JSON methods intact and limits HEAD and OPTIONS as the real parser does' do
+    %w[POST PUT DELETE HEAD OPTIONS].each do |method|
+      action = dynamic_action.merge(method:)
+      result = python_request(action, dynamic_sample[:request])
+      supported = %w[POST PUT DELETE].include?(method)
+      if supported
+        expect(result.fetch('body').fetch('widget')).to eq(JSON.parse(JSON.generate(dynamic_sample[:request])))
+      else
+        expect(result).to include('error' => 'ProtocolError', 'message' => "unsupported action method: #{method}")
+      end
+      renderers.each do |renderer|
+        example = renderer.render(:example, context: dynamic_context(action:))
+        expect(example[:status]).to eq(supported ? :code : :limitation)
+      end
+    end
+  end
+
+  it 'cross-checks missing global and per-object metadata against the real Python builder' do
+    %i[global object].each do |scope|
+      %i[hash hash_list].each do |layout|
+        [true, false].each do |required|
+          action = dynamic_action.merge(input: { layout:, namespace: :widget, parameters: {} }, meta: {
+            scope => { input: { layout: :hash, namespace: false, parameters: { confirm: { type: 'Boolean', required: } } } }
+          })
+          params = layout == :hash ? {} : [{}]
+          native = python_request(action, params)
+          if required
+            expect(native).to include('error' => 'ValidationError', 'message' => 'input parameters are not valid')
+          else
+            expect(native).not_to have_key('error')
+          end
+          [true, false].each do |status|
+            renderers.each do |renderer|
+              result = renderer.render(:example, context: dynamic_context(action:, sample: dynamic_sample.merge(request: params, status:)))
+              expect(result[:status]).to eq(required ? :limitation : :code), result.inspect
+            end
+          end
+        end
+      end
+    end
+  end
+end