haveapi 0.29.12 → 0.30.1

data/spec/client_examples/dynamic_acceptance.rb

@@ -0,0 +1,151 @@
+# Run after committed-deliverable review, with built npm and Python artifacts.
+# The only code executed below comes from the real server's rendered HTML.
+require 'cgi'
+require 'fileutils'
+require 'json'
+require 'net/http'
+require 'open3'
+require 'tmpdir'
+require 'timeout'
+require_relative '../../test_support/dynamic_documentation_api'
+
+module DynamicDocumentationAcceptance
+  VARIANTS = %w[javascript-callback javascript-async typescript-callback typescript-async python-sync python-async].freeze
+
+  def self.run!(*command, chdir:, env: {}, log_path: nil)
+    output, status = Open3.capture2e(env, *command, chdir:)
+    File.write(log_path, output) if log_path
+    raise "#{command.first} failed (#{status.exitstatus}):\n#{output}" unless status.success?
+
+    output
+  end
+
+  def self.request(url)
+    uri = URI(url)
+    response = Net::HTTP.start(uri.host, uri.port, open_timeout: 10, read_timeout: 30) { |http| http.get(uri.request_uri) }
+    raise "Fixture HTTP #{response.code}: #{response.body[0, 200]}" unless response.is_a?(Net::HTTPSuccess)
+
+    response.body
+  end
+
+  def self.extract(html)
+    html.scan(%r{<div id="([^"]+)">\s*<h[46]>[^<]*</h[46]>\s*<pre><code class="([^"]+)">(.*?)</code></pre>}m).filter_map do |id, language, escaped|
+      variant = VARIANTS.find { |name| id.end_with?("-#{name}") }
+      next unless variant
+
+      { id:, variant:, language:, source: CGI.unescapeHTML(escaped) }
+    end
+  end
+
+  def self.run(npm_artifact:, python_artifact:, typescript:, node_types:, output:)
+    root = File.expand_path('../../../..', __dir__)
+    FileUtils.mkdir_p(output)
+    tools = { typescript: File.expand_path(typescript), node_types: File.expand_path(node_types) }
+    npm_artifact = File.expand_path(npm_artifact)
+    python_artifact = File.expand_path(python_artifact)
+    Dir.mktmpdir('haveapi-dynamic-acceptance-') do |consumer|
+      File.write(File.join(consumer, 'package.json'), JSON.generate({ private: true, type: 'module' }))
+      run!('npm', 'install', '--ignore-scripts', '--no-audit', '--no-fund', npm_artifact, chdir: consumer,
+                                                                                          env: { 'NODE_PATH' => nil })
+      run!('uv', 'venv', '--python', '3.11', 'venv', chdir: consumer)
+      python = File.join(consumer, 'venv/bin/python')
+      run!('uv', 'pip', 'install', '--python', python, python_artifact, chdir: consumer)
+      server_script = File.join(root, 'servers/ruby/test_support/dynamic_documentation_api.rb')
+      Open3.popen2e('ruby', server_script, chdir: File.join(root, 'servers/ruby')) do |stdin, server_output, wait|
+        stdin.close
+        reader = nil
+        begin
+          base = Timeout.timeout(30) do
+            loop do
+              line = server_output.gets
+              raise 'Documentation fixture exited before readiness' unless line
+              break line.split.last if line.start_with?('DYNAMIC_DOCUMENTATION_READY ')
+            end
+          end
+          reader = Thread.new { File.write(File.join(output, 'fixture.log'), server_output.read) }
+          html = request("#{base}/mount/v2/")
+          File.write(File.join(output, 'documentation.html'), html)
+          panels = extract(html)
+          raise 'No actual HTML code panels extracted' if panels.empty?
+
+          VARIANTS.each do |variant|
+            selected = panels.select { |panel| panel[:variant] == variant }
+            raise "Incomplete rendered coverage for #{variant}" unless selected.length >= 4 &&
+                                                                       selected.any? { |panel| panel[:id].start_with?('init-') } &&
+                                                                       selected.any? { |panel| panel[:id].start_with?('auth-basic-') } &&
+                                                                       selected.count { |panel| panel[:id].start_with?('example-') } >= 2
+          end
+          panels.each_with_index do |panel, index|
+            extension = { 'typescript' => '.ts', 'javascript' => '.mjs', 'python' => '.py' }.fetch(panel[:language])
+            name = "example-#{index}#{extension}"
+            path = File.join(consumer, name)
+            File.write(path, panel[:source])
+            File.write(File.join(output, name), panel[:source])
+            env = { 'NODE_PATH' => nil, 'PYTHONPATH' => nil, 'PYTHONHOME' => nil,
+                    'HAVEAPI_USER' => 'fixture-user', 'HAVEAPI_PASSWORD' => 'fixture-password',
+                    'HAVEAPI_TOKEN' => 'fixture-token', 'HAVEAPI_ACCESS_TOKEN' => 'fixture-access-token',
+                    'HAVEAPI_AUTH_user' => JSON.generate('fixture-user'),
+                    'HAVEAPI_AUTH_password' => JSON.generate('fixture-password'),
+                    'HAVEAPI_AUTH_lifetime' => JSON.generate('fixed'),
+                    'HAVEAPI_AUTH_scope' => JSON.generate('all'), 'HAVEAPI_CHALLENGE_code' => JSON.generate('123456') }
+            if extension == '.ts'
+              config = {
+                compilerOptions: { target: 'ES2022', module: 'NodeNext', moduleResolution: 'NodeNext', strict: true,
+                                   types: ['node'], typeRoots: [tools[:node_types]], outDir: 'compiled', skipLibCheck: false },
+                files: [name]
+              }
+              File.write(File.join(consumer, 'tsconfig.json'), JSON.generate(config))
+              file_list = run!('node', tools[:typescript], '-p', 'tsconfig.json', '--listFiles', chdir: consumer)
+              raise 'Checkout HaveAPI declarations leaked into installed-package check' if file_list.lines.any? do |line|
+                line.include?('/clients/js/src/') || (line.include?('haveapi.d.ts') && !line.start_with?(consumer))
+              end
+
+              path = File.join(consumer, 'compiled', "example-#{index}.js")
+            end
+            before = JSON.parse(request("#{base}/__acceptance_receipts"))
+            command = panel[:language] == 'python' ? [python, path] : ['node', path]
+            result = run!(*command, chdir: consumer, env:, log_path: File.join(output, "example-#{index}.log"))
+            if panel[:id].start_with?('auth-token-')
+              challenge_result = run!(*command, chdir: consumer, env: env.merge('HAVEAPI_TOKEN' => nil),
+                                                log_path: File.join(output, "example-#{index}-challenge.log"))
+              raise "Token challenge did not complete: #{panel[:id]}\n#{challenge_result}" unless challenge_result.include?('Authenticated')
+            end
+            after = JSON.parse(request("#{base}/__acceptance_receipts"))
+            if panel[:id].start_with?('example-')
+              raise "Rendered action did not execute: #{panel[:id]}\n#{result}" unless after.length == before.length + 1
+
+              receipt = after.last
+              expected = { 'name' => '', 'enabled' => false, 'nullable' => nil, 'payload' => DynamicDocumentationAPI::PAYLOAD }
+              raise "Changed request values: #{receipt.inspect}" unless receipt['input'].except('count') == expected
+              raise 'Changed mounted path arguments' unless receipt['path'].map(&:to_s) == ['7', 'name with space']
+
+              marker = receipt['input']['count'] < 0 ? 'DOC_FAILURE' : 'DOC_SUCCESS'
+              raise "Wrong result/error handling: #{panel[:id]}\n#{result}" unless result.include?(marker)
+            else
+              marker = panel[:id].start_with?('init-') ? 'Discovery complete' : 'Authenticated'
+              raise "Discovery/authentication did not complete: #{panel[:id]}\n#{result}" unless result.include?(marker)
+            end
+          end
+          File.write(File.join(output, 'result.json'), JSON.pretty_generate({ panels: panels.length, variants: VARIANTS, status: 'passed' }))
+        ensure
+          Process.kill('TERM', wait.pid) if wait.alive?
+          wait.value
+          reader&.join
+        end
+      end
+    end
+  end
+end
+
+if $0 == __FILE__
+  require 'optparse'
+  options = {}
+  OptionParser.new do |parser|
+    %i[npm_artifact python_artifact typescript node_types output].each do |key|
+      parser.on("--#{key.to_s.tr('_', '-')} PATH") { |path| options[key] = path }
+    end
+  end.parse!
+  raise 'Supply --npm-artifact, --python-artifact, --typescript, --node-types and --output' unless options.length == 5
+
+  DynamicDocumentationAcceptance.run(**options)
+end

data/spec/client_examples/dynamic_acceptance_spec.rb

@@ -0,0 +1,76 @@
+require 'spec_helper'
+require 'rack/mock'
+require_relative 'dynamic_acceptance'
+
+RSpec.describe DynamicDocumentationAcceptance do
+  it 'extracts actual six-language HTML panels from the mounted fixture' do
+    request = Rack::MockRequest.new(DynamicDocumentationAPI.build.app)
+    response = request.get('http://example.test/mount/v2/', 'HTTP_HOST' => 'example.test')
+    expect(response.status).to eq(200), response.body
+    panels = described_class.extract(response.body)
+    described_class::VARIANTS.each do |variant|
+      selected = panels.select { |panel| panel[:variant] == variant }
+      expect(selected.map { |panel| panel[:id].split('-').first }).to include('init', 'auth', 'example')
+      expect(selected.count { |panel| panel[:id].start_with?('example-') }).to eq(2)
+      expect(selected.last[:source]).to include('http://example.test/mount/')
+      expect(selected.last[:source]).not_to include('"')
+    end
+  end
+
+  it 'records real success and failure request values without source rewriting' do
+    request = Rack::MockRequest.new(DynamicDocumentationAPI.build.app)
+    payload = { widget: { name: '', enabled: false, count: 0, nullable: nil, payload: DynamicDocumentationAPI::PAYLOAD } }
+    headers = {
+      'CONTENT_TYPE' => 'application/json',
+      'HTTP_AUTHORIZATION' => "Basic #{['fixture-user:fixture-password'].pack('m0')}",
+      input: JSON.generate(payload)
+    }
+    path = 'http://example.test/mount/v2/parents/7/children/name%20with%20space'
+    response = request.post(path, headers)
+    expect(response.status).to eq(200), response.body
+    expect(JSON.parse(response.body).fetch('status')).to be(true)
+    expect(DynamicDocumentationAPI.receipts.last[:input][:payload]).to eq(DynamicDocumentationAPI::PAYLOAD)
+    payload[:widget][:count] = -1
+    response = request.post(path, headers.merge(input: JSON.generate(payload)))
+    expect(response.status).to eq(400), response.body
+    expect(JSON.parse(response.body).fetch('message')).to eq('DOC_FAILURE')
+  end
+
+  it 'preserves subprocess output before reporting a nonzero execution failure' do
+    Dir.mktmpdir('haveapi-doc-output-') do |directory|
+      path = File.join(directory, 'example-12.log')
+      expect do
+        described_class.run!('ruby', '-e', 'warn "Discovery or authentication failed"; exit 1', chdir: directory, log_path: path)
+      end.to raise_error(RuntimeError, /Discovery or authentication failed/)
+      expect(File.read(path)).to include('Discovery or authentication failed')
+    end
+  end
+
+  it 'preserves separate existing-token and challenge output before completion assertions' do
+    Dir.mktmpdir('haveapi-doc-output-') do |directory|
+      command = ['ruby', '-e', 'puts ENV.key?("HAVEAPI_TOKEN") ? "Authenticated" : "Discovery or authentication failed"']
+      path = File.join(directory, 'example-12.log')
+      challenge_path = File.join(directory, 'example-12-challenge.log')
+      result = described_class.run!(*command, chdir: directory, env: { 'HAVEAPI_TOKEN' => 'fixture-token' }, log_path: path)
+      challenge = described_class.run!(*command, chdir: directory, env: { 'HAVEAPI_TOKEN' => nil }, log_path: challenge_path)
+      expect(File.read(path)).to eq(result)
+      expect(File.read(challenge_path)).to eq(challenge)
+      expect(result).to include('Authenticated')
+      expect(challenge).to include('Discovery or authentication failed')
+    end
+  end
+
+  it 'traces failed mounted routes without headers, query strings or request bodies' do
+    output = StringIO.new
+    app = DynamicDocumentationAPI::RequestTrace.new(DynamicDocumentationAPI.build.app, output:)
+    request = Rack::MockRequest.new(app)
+    response = request.post('http://example.test/mount/mount/_auth/token/tokens?credential=query-secret',
+                            'HTTP_AUTHORIZATION' => 'Bearer header-secret', 'CONTENT_TYPE' => 'application/json',
+                            input: JSON.generate({ password: 'body-secret' }))
+    expect(response.status).to eq(404)
+    prefix = 'DYNAMIC_DOCUMENTATION_REQUEST '
+    trace = JSON.parse(output.string.delete_prefix(prefix))
+    expect(trace).to eq('method' => 'POST', 'path' => '/mount/mount/_auth/token/tokens', 'status' => 404)
+    expect(output.string).not_to include('secret', 'credential', 'password', 'Bearer')
+  end
+end

data/spec/client_examples/dynamic_fixture.rb

@@ -0,0 +1,36 @@
+module DynamicExampleFixture
+  def dynamic_action
+    {
+      method: 'POST', path: '/mount/v2/parents/{parent_id}/widgets/{widget_id}',
+      input: { layout: :hash, namespace: :widget,
+               parameters: { name: { type: 'String' }, enabled: { type: 'Boolean' }, count: { type: 'Integer' },
+                             nullable: { type: 'String', nullable: true }, metadata: { type: 'Custom' } } },
+      output: { layout: :hash, namespace: :widget, parameters: { id: { type: 'Integer' } } }
+    }
+  end
+
+  def dynamic_sample
+    {
+      path_params: [7, 'name/with space'],
+      request: { name: "Unicode žluťoučký \"quote\"\\\n</script>", enabled: false, count: 0,
+                 nullable: nil, metadata: { '__proto__' => { 'constructor' => [false, 0, nil, ''] } } },
+      response: { id: 0 }, status: true
+    }
+  end
+
+  def dynamic_context(**changes)
+    HaveAPI::ClientExample::Context.new(
+      version: '2', host: 'api.example.test', base_url: 'https://api.example.test/mount/',
+      version_url: 'https://api.example.test/mount/v2/',
+      description: { authentication: { basic: {}, token: {}, oauth2: {} }, resources: {} },
+      resource_path: %w[constructor resources], resource: {}, action_name: "new\"\n</script>",
+      action: dynamic_action, sample: dynamic_sample, **changes
+    )
+  end
+
+  def token_description
+    { resources: { token: { actions: { 'request' => { input: { parameters: {
+      'login-name' => { type: 'String' }, password: { type: 'String' }, lifetime: { type: 'String' }
+    } } } } } } }
+  end
+end

data/spec/client_examples/dynamic_js_spec.rb

@@ -0,0 +1,196 @@
+require 'spec_helper'
+require 'open3'
+require 'tempfile'
+require_relative 'dynamic_fixture'
+
+RSpec.describe HaveAPI::ClientExamples::JsClient do
+  include DynamicExampleFixture
+
+  let(:renderers) do
+    [described_class, HaveAPI::ClientExamples::JsAsyncClient,
+     HaveAPI::ClientExamples::TsClient, HaveAPI::ClientExamples::TsAsyncClient]
+  end
+
+  def syntax(renderer, source)
+    if renderer.code == :typescript
+      compiler = File.expand_path('../../../../clients/js/node_modules/typescript', __dir__)
+      script = <<~'JS'
+        const ts = require(process.argv[1]);
+        const source = require('fs').readFileSync(0, 'utf8');
+        const result = ts.transpileModule(source, {reportDiagnostics: true, compilerOptions: {target: ts.ScriptTarget.ES2020}});
+        for (const diagnostic of result.diagnostics || []) console.error(ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n'));
+        process.exit((result.diagnostics || []).length ? 1 : 0);
+      JS
+      Open3.capture2e('node', '-e', script, compiler, stdin_data: source)
+    else
+      Tempfile.create(['haveapi-doc-js-', '.mjs']) do |file|
+        file.write(source)
+        file.flush
+        Open3.capture2e('node', '--check', file.path)
+      end
+    end
+  end
+
+  it 'keeps all four stable dynamic variants available without profiles' do
+    expect(renderers.map(&:id)).to eq(%w[javascript-callback javascript-async typescript-callback typescript-async])
+    expect(renderers.map(&:order)).to eq([10, 11, 12, 13])
+    expect(renderers).to all(be_available(dynamic_context))
+  end
+
+  it 'renders complete syntax-valid initialization, authentication and hostile action programs' do
+    renderers.each do |renderer|
+      results = [renderer.render(:init, context: dynamic_context), renderer.render(:example, context: dynamic_context)]
+      %i[basic token oauth2].each do |method|
+        results << renderer.render(:auth, context: dynamic_context, auth_method: method, auth_description: token_description)
+      end
+      results.each do |result|
+        expect(result[:status]).to eq(:code), result.inspect
+        expect(result).to be_frozen
+        expect(result[:code]).to include('https://api.example.test/mount/', 'version: "2"')
+        output, status = syntax(renderer, result[:code])
+        expect(status).to be_success, output
+        expect(result[:code]).not_to match(/\bas any\b|\bas unknown\b|\._private|api\.constructor/)
+      end
+    end
+  end
+
+  it 'uses exact public lookups and retains false, zero, null and hostile Custom keys' do
+    renderers.each do |renderer|
+      source = renderer.render(:example, context: dynamic_context).fetch(:code)
+      expect(source).to include('["enabled"]: false', '["count"]: 0', '["nullable"]: null', '["__proto__"]:')
+      expect(source).to include('new\\"\\n</script>')
+      if renderer.id.end_with?('-async')
+        expect(source).to include('.resource("constructor").resource("resources").action(', 'result.value', 'result.response.meta')
+      else
+        expect(source).to include('CallbackClient.findResource', 'CallbackClient.findAction', 'action.directInvoke', 'reply.message()', 'reply.envelope.errors')
+      end
+    end
+  end
+
+  it 'checks TypeScript examples against the real emitted public declarations with strict types' do
+    root = File.expand_path('../../../..', __dir__)
+    Dir.mktmpdir('haveapi-ts-docs-') do |directory|
+      files = []
+      [HaveAPI::ClientExamples::TsClient, HaveAPI::ClientExamples::TsAsyncClient].each_with_index do |renderer, index|
+        results = [renderer.render(:init, context: dynamic_context), renderer.render(:example, context: dynamic_context)]
+        %i[basic token oauth2].each do |method|
+          results << renderer.render(:auth, context: dynamic_context, auth_method: method, auth_description: token_description)
+        end
+        results.each_with_index do |result, number|
+          path = File.join(directory, "#{index}-#{number}.ts")
+          File.write(path, result.fetch(:code))
+          files << path
+        end
+      end
+      options = { strict: true, noEmit: true, target: 'ES2020', module: 'ESNext', moduleResolution: 'node',
+                  ignoreDeprecations: '6.0',
+                  typeRoots: [File.join(root, 'clients/js/node_modules/@types')], types: ['node'],
+                  baseUrl: directory, paths: { 'haveapi-client' => [File.join(root, 'clients/js/dist/types/haveapi')] } }
+      config = File.join(directory, 'tsconfig.json')
+      File.write(config, JSON.generate({ compilerOptions: options, files: }))
+      output, status = Open3.capture2e('node', File.join(root, 'clients/js/node_modules/typescript/bin/tsc'), '-p', config)
+      expect(status).to be_success, output
+    end
+  end
+
+  it 'never drops list input, unknown fields or unresolved path arguments' do
+    invalid = [
+      dynamic_context(sample: dynamic_sample.merge(request: [{ name: 'row' }])),
+      dynamic_context(sample: dynamic_sample.merge(request: { hidden: 'not visible' })),
+      dynamic_context(sample: dynamic_sample.merge(path_params: [7])),
+      dynamic_context(sample: dynamic_sample.merge(request: { count: 9_007_199_254_740_992 })),
+      dynamic_context(sample: { request: nil, response: nil, comment: 'prose only' })
+    ]
+    renderers.each do |renderer|
+      invalid.each do |context|
+        result = renderer.render(:example, context:)
+        expect(result[:status]).to eq(:limitation)
+        expect(result[:reason]).not_to be_empty
+        expect(result).not_to have_key(:code)
+      end
+    end
+  end
+
+  it 'limits unsupported or unadvertised authentication instead of inventing a flow' do
+    renderers.each do |renderer|
+      result = renderer.render(:auth, context: dynamic_context(description: { authentication: {} }), auth_method: :basic, auth_description: {})
+      expect(result[:status]).to eq(:limitation)
+      result = renderer.render(:auth, context: dynamic_context, auth_method: :custom, auth_description: {})
+      expect(result[:status]).to eq(:limitation)
+    end
+  end
+
+  it 'uses actual operation completion support only for the async client' do
+    renderers.each do |renderer|
+      source = renderer.render(:example, context: dynamic_context(action: dynamic_action.merge(blocking: true))).fetch(:code)
+      if renderer.id.end_with?('-async')
+        expect(source).to include('await api.waitForCompletion(result, {timeoutMs: 300000})')
+      else
+        expect(source).not_to include('waitForCompletion(')
+        expect(source).to include('initial response')
+      end
+    end
+  end
+
+  it 'limits nested GET and OPTIONS query input while preserving scalar queries and HEAD bodies' do
+    renderers.each do |renderer|
+      %w[GET OPTIONS HEAD].each do |method|
+        action = dynamic_action.merge(method:)
+        result = renderer.render(:example, context: dynamic_context(action:))
+        expect(result[:status]).to eq(method == 'HEAD' ? :code : :limitation)
+        params = { name: '', enabled: false, count: 0, nullable: nil }
+        scalar = renderer.render(:example, context: dynamic_context(action:, sample: dynamic_sample.merge(request: params)))
+        expect(scalar[:status]).to eq(:code), scalar.inspect
+        expect(scalar[:code]).to include('["enabled"]: false', '["count"]: 0', '["nullable"]: null')
+      end
+    end
+  end
+
+  it 'cross-checks query loss and HEAD bodies against both native JavaScript clients' do
+    helper = File.expand_path('../../../../clients/js/test/helpers/async_bundle.cjs', __dir__)
+    script = <<~JS
+      const assert = require('node:assert/strict');
+      const {harness, action, description} = require(process.argv[1]);
+      async function check() {
+        for (const method of ['GET', 'OPTIONS', 'HEAD']) {
+          for (const params of [{payload: {enabled: false, count: 0}}, {enabled: false, count: 0, nullable: null}]) {
+            const {HaveAPI, requests} = harness();
+            const callback = new HaveAPI.CallbackClient('https://api.example.test');
+            const model = description();
+            model.resources.widgets.actions.validate = action({payload: {type: 'Custom'}, enabled: {type: 'Boolean'},
+              count: {type: 'Integer'}, nullable: {type: 'String', nullable: true}}, {method});
+            callback.setup((api, ready) => {
+              assert.equal(ready, true);
+              const resource = HaveAPI.CallbackClient.findResource(api, ['widgets']);
+              HaveAPI.CallbackClient.findAction(resource, 'validate').directInvoke({params});
+            });
+            requests[0].respond({status: true, version: '2.0', response: model});
+            const asyncClient = new HaveAPI.AsyncClient('https://api.example.test');
+            const pending = asyncClient.request({method, path: '/v1/validate', inputNamespace: 'widget', params});
+            assert.equal(callback.sendAsQueryParams(method), method !== 'HEAD');
+            for (const wire of requests.slice(1)) {
+              if (method === 'HEAD') {
+                assert.deepEqual(JSON.parse(wire.body), {widget: params});
+                assert.equal(new URL(wire.url).search, '');
+              } else {
+                const query = new URL(wire.url).searchParams;
+                assert.equal(wire.body, undefined);
+                if (params.payload) assert.equal(query.get('widget[payload]'), '[object Object]');
+                else {
+                  assert.equal(query.get('widget[enabled]'), 'false');
+                  assert.equal(query.get('widget[count]'), '0');
+                  assert.equal(query.get('widget[nullable]'), '');
+                }
+              }
+              wire.respond({status: true, response: {}});
+            }
+            await pending;
+          }
+        }
+      }
+      check().catch(error => { console.error(error); process.exitCode = 1; });
+    JS
+    output, status = Open3.capture2e('node', '-e', script, helper)
+    expect(status).to be_success, output
+  end
+end

data/spec/client_examples/dynamic_metadata_spec.rb

@@ -0,0 +1,52 @@
+require 'spec_helper'
+require_relative 'dynamic_fixture'
+
+RSpec.describe HaveAPI::ClientExamples::DynamicHelpers do
+  include DynamicExampleFixture
+
+  let(:renderers) do
+    [HaveAPI::ClientExamples::JsClient, HaveAPI::ClientExamples::JsAsyncClient,
+     HaveAPI::ClientExamples::TsClient, HaveAPI::ClientExamples::TsAsyncClient,
+     HaveAPI::ClientExamples::PythonClient, HaveAPI::ClientExamples::PythonAsyncClient]
+  end
+
+  it 'limits all sample outcomes that need required global or object input metadata' do
+    %i[global object].each do |scope|
+      metadata = { scope => { input: { layout: :hash, namespace: false,
+                                       parameters: { private_confirmation: { type: 'Boolean', required: true, default: false } } } } }
+      action = dynamic_action.merge(meta: metadata)
+      [true, false].each do |status|
+        renderers.each do |renderer|
+          result = renderer.render(:example, context: dynamic_context(action:, sample: dynamic_sample.merge(status:)))
+          expect(result[:status]).to eq(:limitation)
+          expect(result[:reason]).to eq('This action requires input metadata that the sample format cannot supply.')
+          expect(result[:reason]).not_to include('private_confirmation', 'default')
+          expect(result).not_to have_key(:code)
+        end
+      end
+    end
+  end
+
+  it 'keeps absent, optional and output-only metadata executable without invented values' do
+    [nil, {}, { global: { input: { parameters: { optional: { type: 'Boolean', required: false } } } } },
+     { object: { input: { parameters: { optional: { type: 'Boolean' } } } } },
+     { global: { output: { parameters: { required_output: { type: 'String', required: true } } } } }].each do |meta|
+      renderers.each do |renderer|
+        result = renderer.render(:example, context: dynamic_context(action: dynamic_action.merge(meta:)))
+        expect(result[:status]).to eq(:code), result.inspect
+        expect(result[:code]).not_to include('optional', 'required_output')
+      end
+    end
+  end
+
+  it 'checks string-keyed metadata and does not apply object metadata without action input' do
+    action = dynamic_action.merge(meta: { 'object' => { 'input' => { 'parameters' => {
+      'confirmation' => { 'type' => 'Boolean', 'required' => true }
+    } } } })
+    renderers.each do |renderer|
+      expect(renderer.render(:example, context: dynamic_context(action:))[:status]).to eq(:limitation)
+      context = dynamic_context(action: action.merge(input: nil), sample: dynamic_sample.merge(request: {}))
+      expect(renderer.render(:example, context:)[:status]).to eq(:code)
+    end
+  end
+end

data/spec/client_examples/dynamic_mounted_paths_spec.rb

@@ -0,0 +1,65 @@
+require 'spec_helper'
+require 'open3'
+require 'rack/mock'
+require_relative '../../test_support/dynamic_documentation_api'
+
+RSpec.describe DynamicDocumentationAPI do
+  it 'uses real mounted descriptor routes for callback and async token challenges and nested actions' do
+    request = Rack::MockRequest.new(described_class.build.app)
+    headers = { 'HTTP_AUTHORIZATION' => "Basic #{['fixture-user:fixture-password'].pack('m0')}" }
+    envelope = JSON.parse(request.options('http://example.test/mount/v2/', headers).body)
+    model = envelope.fetch('response')
+    token = model.fetch('authentication').fetch('token').fetch('resources').fetch('token').fetch('actions')
+    action = model.fetch('resources').fetch('constructor').fetch('resources').fetch('resources').fetch('actions').fetch('new')
+    expect(token.fetch('request').fetch('path')).to eq('/mount/_auth/token/tokens')
+    expect(action.fetch('path')).to eq('/mount/v2/parents/{parent_id}/children/{widget_id}')
+    params = action.fetch('examples').first.fetch('request')
+    post = lambda do |path, body, extra = {}|
+      response = request.post("http://example.test#{path}", extra.merge('CONTENT_TYPE' => 'application/json', input: JSON.generate(body)))
+      expect(response.status).to eq(200), response.body
+      JSON.parse(response.body)
+    end
+    challenge = post.call(token.fetch('request').fetch('path'), { token: {
+      user: 'fixture-user', password: 'fixture-password', scope: 'all', lifetime: 'renewable_auto'
+    } })
+    completed = post.call(token.fetch('verify').fetch('path'), { token: { token: 'fixture-challenge', code: '123456' } })
+    action_path = action.fetch('path').sub('{parent_id}', '7').sub('{widget_id}', 'name%20with%20space')
+    result = post.call(action_path, { widget: params }, { 'HTTP_X_HAVEAPI_AUTH_TOKEN' => 'fixture-token' })
+    data = { envelope:, challenge:, completed:, result:, params:, action_path: }
+    script = <<~JS
+      const assert = require('node:assert/strict');
+      const {harness, tick} = require(process.argv[1]);
+      const {HaveAPI, requests} = harness();
+      const data = JSON.parse(require('node:fs').readFileSync(0, 'utf8'));
+      const model = data.envelope.response;
+      const auth = model.authentication.token.resources.token.actions;
+      async function check() {
+        const callback = new HaveAPI.CallbackClient('http://example.test/mount/', {version:'2'});
+        let ready = false;
+        callback.authenticate('token', {user:'fixture-user', password:'fixture-password', scope:'all', callback: () => ({code:'123456'})},
+          (_, ok) => { ready = ok; });
+        // Parse actual discovery JSON inside the bundle's VM, matching the real XHR boundary.
+        assert.equal(requests[0].url, 'http://example.test/mount/v2/'); requests[0].respond(data.envelope);
+        assert.equal(requests[1].url, 'http://example.test' + auth.request.path); requests[1].respond(data.challenge);
+        assert.equal(requests[2].url, 'http://example.test' + auth.verify.path); requests[2].respond(data.completed);
+        assert.equal(requests[3].url, 'http://example.test/mount/v2/'); requests[3].respond(data.envelope); assert.equal(ready, true);
+        const resource = HaveAPI.CallbackClient.findResource(callback, ['constructor','resources']);
+        HaveAPI.CallbackClient.findAction(resource, 'new').directInvoke(7, 'name with space', {params:data.params});
+        assert.equal(requests[4].url, 'http://example.test' + data.action_path); requests[4].respond(data.result);
+        const api = new HaveAPI.AsyncClient('http://example.test/mount/', {version:'2'}); api.useDescription(model);
+        const authenticating = api.authenticate('token', {user:'fixture-user', password:'fixture-password', scope:'all', onChallenge: () => ({code:'123456'})});
+        await tick(); assert.equal(requests[5].url, 'http://example.test' + auth.request.path); requests[5].respond(data.challenge);
+        await tick(); assert.equal(requests[6].url, 'http://example.test' + auth.verify.path); requests[6].respond(data.completed);
+        await tick(); assert.equal(requests[7].url, 'http://example.test/mount/v2/'); requests[7].respond(data.envelope); await authenticating;
+        const invoked = api.resource('constructor').resource('resources').action('new')(7, 'name with space', {params:data.params});
+        assert.equal(requests[8].url, 'http://example.test' + data.action_path); requests[8].respond(data.result);
+        assert.equal((await invoked).value.marker, 'DOC_SUCCESS');
+        assert.equal(requests.length, 9);
+      }
+      check().catch(error => {console.error(error); process.exitCode = 1;});
+    JS
+    helper = File.expand_path('../../../../clients/js/test/helpers/async_bundle.cjs', __dir__)
+    output, status = Open3.capture2e('node', '-e', script, helper, stdin_data: JSON.generate(data))
+    expect(status).to be_success, output
+  end
+end