haveapi 0.30.0 → 0.30.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4d308a5a5e69e262ce771a7ec707783c63af02c38726df08c8d5c2f68bae18d3
-  data.tar.gz: b70e5a101d631bae5e90d999f50d621643f511fef3a61a45b78f35369e0528c6
+  metadata.gz: 3d58d9e427d490d025fec95d60739ea4aa17b4e86cc3fb9978b7c00b751e6e75
+  data.tar.gz: e0b958ac9924d4cacaf75513d79690c3ed2519d6b5d1522a0433d92285742887
 SHA512:
-  metadata.gz: f3081d61476f4ddeb15b44028ff40a9073587520c13bf776f6e675ebcb41439d236c2f463029c969f589e6342e8ca13c550b3d6ab6c1a6dfb639b1bc6a99a940
-  data.tar.gz: 6523e8942f1fa7ef18c4fbdab85ea073b1e6df14249c948f270b573c3193de3c8d39046440ca132d9f4f30f9d94393392cedc9170310f419a2be8607bac07d0a
+  metadata.gz: 78980868da2569146dccf39ce14309e27b97d51b4a266b7709813faafb191577520f31408dd6ebf1e5310b37bd43197e9b4e838503cd60c5d8b480607e8c5f6d
+  data.tar.gz: 5a2a6ad3e686e3d77b86fb83e7e27b5eaf5e2ac573013fa938255b203405fdabe899a605f71cea8088769e81f323b6678be00272889c56d629757356d9170d87

data/doc/client-examples.md

@@ -15,9 +15,96 @@ profile; ordinary servers do not depend on either generator.
 
 ## Configure a generated SDK
 
-Register profiles before mounting the server. Paths must name trusted absolute
-local files. Keep the SDK's saved description and generator configuration;
-the server does not fetch descriptions or regenerate SDKs while serving docs.
+Register profiles before mounting the server. For an SDK that matches the current
+API, configure its package identity:
+
+```ruby
+api.documentation_clients('1.0',
+  go: {
+    import_path: 'example.org/widget/client'
+  },
+  rust: {
+    crate_name: 'widget-client'
+  }
+)
+api.mount('/api/')
+```
+
+`generator_version` defaults to the server's `HaveAPI::VERSION`. Install the
+optional `haveapi-go-client` or `haveapi-rust-client` generator gem at that
+version. An explicit `generator_version` requires the installed generator to
+report that version; it never downloads one. It is independent of the SDK and
+API versions.
+
+At the end of mount, the server builds one private structural model per configured
+API version. The model includes authentication resources, routes and changes from
+post-mount hooks, so canonical names and parent arguments use the complete API
+declaration. The private copy excludes examples, prose and parameter defaults.
+HTML requests use the current user's authorized description, fields and samples;
+they never expose the private model or its initialization diagnostics. Without
+a configured profile, the server loads no optional generator and shows no Go or
+Rust panels.
+
+Automatic profiles assume that the installed SDK matches the current server's
+generation contract. A package name or version does not prove its contents.
+An older SDK can lack new actions or use different names after a collision or
+route change. Check actual SDK compatibility before advertising it; use a saved
+schema override below when the SDK represents an older or restricted API.
+
+### Optional SDK versions and sources
+
+Set `module_version: 'v1.2.3'` for Go or `crate_version: '1.2.3'` for Rust when a
+specific package version is needed. Omit the field or use nil to let the user's
+package manager select a release. The server does not query a registry or claim
+to have resolved a version. Omitted versions produce these installation hints:
+
+```sh
+go get example.org/widget/client@latest
+cargo add widget-client
+# Blocking Rust variant:
+cargo add widget-client --features blocking
+```
+
+Go resolves `@latest` by its normal rules. Cargo selects a compatible release
+according to its resolver, manifest and toolchain; existing lockfiles still
+apply. Explicit Cargo versions remain version requirements, without an added
+exact `=` pin. Latest selection can change over time; supply a version to control
+the selection. Cargo never receives a literal `version = "latest"`. Rust
+examples also show their Tokio and serde_json requirements.
+
+For an unpublished Rust SDK, supply an HTTPS Git URL and a full commit SHA:
+
+```ruby
+api.documentation_clients('7.0',
+  rust: {
+    crate_name: 'vpsadmin-client',
+    source: {
+      git: 'https://github.com/vpsfreecz/vpsadmin-rust-client',
+      rev: 'ff876abe17e3301da62c1b6afbda055ec89db9d2'
+    }
+  }
+)
+```
+
+The dependency hint uses that source instead of a registry release:
+
+```toml
+# Cargo.toml
+vpsadmin-client = { git = "https://github.com/vpsfreecz/vpsadmin-rust-client", rev = "ff876abe17e3301da62c1b6afbda055ec89db9d2" }
+# The blocking variant also sets features = ["blocking"].
+```
+
+`source` accepts only `git` and `rev`. URLs must be absolute HTTPS without
+credentials, query strings, fragments or control characters; revisions must be
+40 hexadecimal characters. Branches, tags, local paths and custom registries are
+not supported. An explicit crate version additionally constrains the selected
+source package. The server never fetches the repository or runs these user
+installation commands. These settings do not regenerate or publish an SDK and
+do not establish that this particular SDK matches a given API surface.
+
+### Saved-schema overrides
+
+The existing file-based profiles remain supported:
 
 ```ruby
 api.documentation_clients('1.0',
@@ -33,24 +120,39 @@ api.documentation_clients('1.0',
     generator_version: '0.30.0'
   }
 )
-api.mount('/api/')
 ```
 
-Use the SDK's published package name and version. The Rust crate name and
-version come from the generator TOML configuration, which also records the
-formatter and language requirements. Go uses the import alias `client`. The
-installed generator version must match the profile. Missing files or adapters,
-unknown fields, duplicate profiles and invalid SDK schemas or configurations
-cause startup to fail. Mounting also rejects profiles for unselected API
-versions and Rust snapshots bound to another API version.
-
-An SDK profile can still serve examples after unrelated additions to the live
-API. Each example is checked against the SDK's saved action, route, layout and
-parameter contract. An unsupported or stale sample produces a limitation.
-Profiles do not expose actions, fields, defaults or samples hidden from the
-current user. The full SDK schema and local paths stay private; request
-contexts use only the current user's filtered description and the selected
-sample.
+Paths name trusted absolute local files. `description_path` is Go's saved
+machine-readable description, not HTML. `snapshot_path` is Rust's saved schema
+and capture metadata. They select an exact SDK shape in place of the current
+server declaration. Keep the files private and retain them with the SDK release.
+
+Rust's legacy `generator_config_path` supplies the crate name/version and full
+packaging configuration. It is mutually exclusive with inline `crate_name` and
+`crate_version`, and can be paired with either a saved snapshot or automatic
+schema. A saved snapshot can instead use inline crate identity. `source` works
+with either identity form. The server validates the full legacy TOML; normal
+inline documentation needs no license, compiler or formatter settings.
+
+Saved files are read and validated during registration. Automatic models are
+initialized at the end of mount. Missing files or generators, actual generator
+version mismatches, unknown fields, conflicting identities and invalid schemas
+fail startup. Mounting also rejects unavailable API versions and mismatched Rust
+snapshot versions. Failed mounting publishes no profiles and leaves no usable
+server application. An older explicitly pinned generator can serve a suitable
+legacy file profile, but automatic/inline Rust mode requires the new factory
+interface and never guesses a fallback.
+
+A saved SDK can still serve examples after unrelated live additions. Each sample
+must match its saved route, layout and supplied parameter contracts; unavailable
+or stale samples show a limitation. Hidden actions, fields, defaults and samples
+remain hidden from the current user. The server never fetches descriptions,
+regenerates packages or runs a compiler/formatter during an HTML request.
+
+Old profile settings work on the new server. Inline settings require the new
+server code; rolling back that code also requires restoring compatible settings.
+Mixed server workers can show different documentation examples without changing
+wire requests or persisted data.
 
 ## Renderer extensions
 
@@ -71,8 +173,8 @@ overview and every panel before rendering.
 
 Generated-client adapters belong to their generator gems and consume context
 readers without depending on the server gem. They resolve names using the
-saved generator schema and never run a compiler, formatter or generator in an
-HTML request. Keep adapter rendering read-only: configured adapters are frozen
+complete private generator model and never run a compiler, formatter or generator
+in an HTML request. Keep adapter rendering read-only: configured adapters are frozen
 and shared, while filtered contexts are copied per request.
 
 ## Verification

data/haveapi.gemspec

@@ -15,7 +15,7 @@ Gem::Specification.new do |s|
   s.required_ruby_version = ">= #{File.read('../../.ruby-version').strip}"
 
   s.add_dependency 'activesupport', '>= 7.1'
-  s.add_dependency 'haveapi-client', '~> 0.30.0'
+  s.add_dependency 'haveapi-client', '~> 0.30.1'
   s.add_dependency 'i18n', '>= 1.6', '< 2'
   s.add_dependency 'json'
   s.add_dependency 'mail'

data/lib/haveapi/documentation_clients.rb

@@ -1,5 +1,6 @@
 require 'json'
 require 'haveapi/documentation_context'
+require 'haveapi/documentation_schema'
 
 module HaveAPI
   class ClientExample
@@ -9,7 +10,7 @@ module HaveAPI
       def initialize(language:, package_name:, package_version:, adapter:)
         @language = language
         @package_name = package_name.dup.freeze
-        @package_version = package_version.dup.freeze
+        @package_version = package_version&.dup&.freeze
         @adapter = adapter.freeze
         freeze
       end
@@ -20,64 +21,116 @@ module HaveAPI
 
       KEYS = {
         go: %i[import_path module_version description_path generator_version],
-        rust: %i[snapshot_path generator_config_path generator_version]
+        rust: %i[crate_name crate_version source snapshot_path generator_config_path generator_version]
       }.freeze
 
       def initialize
-        @versions = {}
-        @rust_versions = {}
+        @registrations = {}
+        @profiles = {}.freeze
       end
 
       def register(version, **languages)
-        raise Invalid, 'Documentation client profiles are already mounted' if @mounted
+        raise Invalid, 'Documentation client profiles are already mounted' if @closed
         raise Invalid, 'Unknown documentation client language' unless (languages.keys - KEYS.keys).empty?
 
-        selected = @versions[version.to_s] ||= {}
+        selected = @registrations.fetch(version.to_s, {})
+        additions = {}
         languages.each do |language, config|
           next if config.nil?
           raise Invalid, 'Duplicate documentation client profile' if selected.has_key?(language)
 
-          selected[language] = load_profile(language, config, version.to_s)
+          additions[language] = load_profile(language, config)
         end
+        @registrations[version.to_s] = selected.merge(additions)
       end
 
       def mount(versions)
-        unknown = @versions.keys - Array(versions).map(&:to_s)
+        raise Invalid, 'Documentation client profiles are already mounted' if @closed
+
+        @closed = true
+        unknown = @registrations.keys - Array(versions).map(&:to_s)
         raise Invalid, 'Documentation client profile selects an unavailable API version' unless unknown.empty?
-        unless @rust_versions.all? { |version, saved| version == saved }
-          raise Invalid, 'Documentation Rust snapshot API version mismatch'
+
+        @registrations.each do |version, languages|
+          snapshot = languages.dig(:rust, :snapshot)
+          if snapshot && snapshot.fetch('api_version').to_s != version
+            raise Invalid, 'Documentation Rust snapshot API version mismatch'
+          end
         end
+      end
 
-        @versions.each_value(&:freeze)
-        @versions.freeze
-        @mounted = true
+      # Publish only after every adapter succeeds, using the complete mounted DSL.
+      def finalize(server)
+        raise Invalid, 'Documentation client profiles are not ready to finalize' unless @closed && !@finalized
+
+        completed = @registrations.to_h do |version, languages|
+          description = if languages.any? { |_language, config| !config[:profile] }
+                          safely do
+                            context = HaveAPI::Context.new(
+                              server, version: server.versions.find { |v| v.to_s == version }, user: nil, endpoint: false, doc: true
+                            )
+                            StructuralSchema.copy(server.describe_version(context))
+                          end
+                        end
+          profiles = languages.to_h do |language, config|
+            profile = config[:profile] || safely { build_profile(language, config, description, server, version) }
+            [language, profile]
+          end
+          [version, profiles.freeze]
+        end
+        @profiles = completed.freeze
+        @registrations = nil
+        @finalized = true
+      rescue StandardError
+        abort_mount
+        raise
+      end
+
+      def abort_mount
+        @profiles = {}.freeze
+        @registrations = nil
+        @closed = true
+        @finalized = true
       end
 
       def for_version(version)
-        @versions.fetch(version.to_s, {}).dup.freeze
+        @profiles.fetch(version.to_s, {}).dup.freeze
       end
 
       private
 
       def validate_config(language, config)
-        unless config.is_a?(Hash) && config.keys.sort == KEYS.fetch(language).sort &&
-               config.values.all? { |value| value.is_a?(String) && !value.strip.empty? }
+        unless config.is_a?(Hash) && (config.keys - KEYS.fetch(language)).empty? &&
+               config.all? { |key, value| %i[source module_version crate_version].include?(key) || nonempty_string?(value) }
           raise Invalid, 'Invalid documentation client profile fields'
         end
-        return if config.fetch(:generator_version).match?(/\A\d+\.\d+\.\d+(?:[-+][\w.-]+)?\z/)
+
+        config = config.dup
+        config[:generator_version] = config.fetch(:generator_version, HaveAPI::VERSION)
+        return config if config[:generator_version].match?(/\A\d+\.\d+\.\d+(?:[-+][\w.-]+)?\z/)
 
         raise Invalid, 'Invalid documentation generator version'
       end
 
+      def nonempty_string?(value)
+        value.is_a?(String) && !value.strip.empty?
+      end
+
       def local_file(path)
         raise Invalid, 'Documentation profiles require absolute local files' unless path.start_with?('/') && File.file?(path)
 
         path
       end
 
-      def load_profile(language, config, version)
-        validate_config(language, config)
-        language == :go ? load_go(config) : load_rust(config, version)
+      def load_profile(language, config)
+        safely do
+          config = validate_config(language, config)
+          language == :go ? load_go(config) : load_rust(config)
+        end
+      end
+
+      def safely
+        yield
       rescue LoadError
         raise Invalid, 'Configured documentation client generator is not installed'
       rescue JSON::ParserError, SystemCallError
@@ -89,11 +142,11 @@ module HaveAPI
       end
 
       def load_go(config)
-        name = config.fetch(:import_path)
-        version = config.fetch(:module_version)
-        unless name.match?(%r{\A[a-zA-Z0-9][a-zA-Z0-9._~/-]*\z}) &&
+        name = config[:import_path]
+        version = config[:module_version]
+        unless nonempty_string?(name) && name.match?(%r{\A[a-zA-Z0-9][a-zA-Z0-9._~/-]*\z}) &&
                name.split('/').none? { |part| part.empty? || %w[. ..].include?(part) } &&
-               version.match?(/\Av\d+\.\d+\.\d+(?:[-+][\w.-]+)?\z/)
+               (version.nil? || (version.is_a?(String) && version.match?(/\Av\d+\.\d+\.\d+(?:[-+][\w.-]+)?\z/)))
           raise Invalid, 'Invalid Go documentation client package'
         end
 
@@ -102,24 +155,94 @@ module HaveAPI
           raise Invalid, 'Documentation Go generator version mismatch'
         end
 
-        description = JSON.parse(File.read(local_file(config.fetch(:description_path))))
-        adapter = HaveAPI::GoClient::Documentation.new(description:, import_path: name, module_version: version)
-        Profile.new(language: :go, package_name: name, package_version: version, adapter:)
+        prepared = { name: name.dup.freeze, version: version&.dup&.freeze }.freeze
+        return prepared unless config.has_key?(:description_path)
+
+        description = JSON.parse(File.read(local_file(config[:description_path])))
+        { profile: go_profile(prepared, description) }.freeze
+      end
+
+      def go_profile(config, description)
+        adapter = HaveAPI::GoClient::Documentation.new(description:, import_path: config[:name], module_version: config[:version])
+        profile(:go, config, adapter)
       end
 
-      def load_rust(config, api_version)
+      def load_rust(config)
         require 'haveapi/rust_client/documentation'
         unless config.fetch(:generator_version) == HaveAPI::RustClient::VERSION
           raise Invalid, 'Documentation Rust generator version mismatch'
         end
 
-        snapshot = JSON.parse(File.read(local_file(config.fetch(:snapshot_path))))
-        @rust_versions[api_version] = snapshot.fetch('api_version').to_s
-        generator_config = Tomlrb.load_file(local_file(config.fetch(:generator_config_path)))
-        name = generator_config.fetch('crate_name')
-        version = generator_config.fetch('crate_version')
-        adapter = HaveAPI::RustClient::Documentation.new(snapshot:, config: generator_config)
-        Profile.new(language: :rust, package_name: name, package_version: version, adapter:)
+        legacy = config.has_key?(:generator_config_path)
+        if legacy && (config.has_key?(:crate_name) || config.has_key?(:crate_version))
+          raise Invalid, 'Conflicting Rust documentation client identities'
+        end
+
+        documentation = HaveAPI::RustClient::Documentation
+        snapshot = JSON.parse(File.read(local_file(config[:snapshot_path]))) if config.has_key?(:snapshot_path)
+        if (!legacy || !snapshot) && !(documentation.respond_to?(:from_description) && documentation.respond_to?(:from_snapshot))
+          raise Invalid, 'Documentation Rust generator does not support automatic or inline profiles'
+        end
+
+        source = if config.has_key?(:source)
+                   raise Invalid, 'Documentation Rust generator does not support source metadata' unless documentation.respond_to?(:validate_source)
+
+                   documentation.validate_source(config[:source])
+                 end
+        generator_config = Tomlrb.load_file(local_file(config[:generator_config_path])) if legacy
+        if legacy
+          HaveAPI::RustClient::Generator.validate_config(generator_config) unless snapshot
+          name = generator_config.fetch('crate_name')
+          version = generator_config.fetch('crate_version')
+        else
+          name = config[:crate_name]
+          version = config[:crate_version]
+          HaveAPI::RustClient::Model.validate_package(crate_name: name, crate_version: version)
+        end
+        prepared = { name: name.dup.freeze, version: version&.dup&.freeze,
+                     snapshot:, generator_config:, source: }.freeze
+        return prepared unless snapshot
+
+        prepared.merge(profile: rust_profile(prepared, snapshot:)).freeze
+      end
+
+      def build_profile(language, config, description, server, version)
+        return go_profile(config, description) if language == :go
+
+        arguments = { description:, api_version: version, protocol_version: HaveAPI::PROTOCOL_VERSION,
+                      mount_path: server.root }
+        if config[:generator_config]
+          snapshot = HaveAPI::RustClient::Snapshot.from_description(
+            **arguments, source_url: "https://haveapi.invalid#{server.root}v#{version}/", profile: 'server-documentation'
+          )
+          return rust_profile(config, snapshot:)
+        end
+
+        adapter = HaveAPI::RustClient::Documentation.from_description(
+          **arguments, crate_name: config[:name], crate_version: config[:version], source: config[:source]
+        )
+        profile(:rust, config, adapter)
+      end
+
+      def rust_profile(config, snapshot:)
+        adapter = if config[:generator_config]
+                    arguments = { snapshot:, config: config[:generator_config] }
+                    arguments[:source] = config[:source] if config[:source]
+                    HaveAPI::RustClient::Documentation.new(**arguments)
+                  else
+                    HaveAPI::RustClient::Documentation.from_snapshot(
+                      snapshot:, crate_name: config[:name], crate_version: config[:version], source: config[:source]
+                    )
+                  end
+        profile(:rust, config, adapter)
+      end
+
+      def profile(language, config, adapter)
+        unless adapter.respond_to?(:resolve) && adapter.respond_to?(:render)
+          raise Invalid, 'Documentation client generator has an incompatible adapter interface'
+        end
+
+        Profile.new(language:, package_name: config[:name], package_version: config[:version], adapter:)
       end
     end
   end

data/lib/haveapi/documentation_schema.rb

@@ -0,0 +1,73 @@
+require 'json'
+
+module HaveAPI
+  class ClientExample
+    # Private naming/type input, never a request's authorized help or samples.
+    module StructuralSchema
+      BUILTIN_VALIDATORS = %w[present number include exclude format length confirm accept].freeze
+
+      def self.copy(description)
+        result = JSON.parse(JSON.generate(description))
+        resources(result['resources'])
+        result.fetch('authentication', {}).each_value do |provider|
+          prose(provider)
+          resources(provider['resources'])
+        end
+        freeze_data(result)
+      end
+
+      def self.resources(map)
+        return unless map
+
+        map.each_value do |resource|
+          prose(resource)
+          resource.fetch('actions', {}).each_value do |action|
+            prose(action)
+            action.delete('examples')
+            parameters(action['input'])
+            parameters(action['output'])
+            action.fetch('meta', nil)&.each_value do |metadata|
+              next unless metadata
+
+              parameters(metadata['input'])
+              parameters(metadata['output'])
+            end
+          end
+          resources(resource['resources'])
+        end
+      end
+
+      def self.parameters(group)
+        return unless group
+
+        group.fetch('parameters', {}).each_value do |parameter|
+          prose(parameter)
+          parameter.delete('default')
+          parameter.fetch('validators', {}).each do |name, validator|
+            prose(validator) if BUILTIN_VALIDATORS.include?(name) && validator.is_a?(Hash)
+          end
+        end
+      end
+
+      def self.prose(object)
+        %w[label description message].each { |key| object.delete(key) }
+      end
+
+      def self.freeze_data(value)
+        case value
+        when Hash
+          value.each do |key, item|
+            freeze_data(key)
+            freeze_data(item)
+          end
+        when Array
+          value.each { |item| freeze_data(item) }
+        end
+        value.freeze
+      end
+
+      private_class_method :resources, :parameters, :prose, :freeze_data
+    end
+    private_constant :StructuralSchema
+  end
+end

data/lib/haveapi/server.rb

@@ -622,6 +622,11 @@ module HaveAPI
       end
 
       call_hooks_for(:post_mount, args: [self, @sinatra])
+      @documentation_clients.finalize(self)
+    rescue StandardError
+      @documentation_clients.abort_mount
+      @sinatra = nil
+      raise
     end
 
     def mount_version(prefix, v)

data/lib/haveapi/version.rb

@@ -1,4 +1,4 @@
 module HaveAPI
   PROTOCOL_VERSION = '2.0'.freeze
-  VERSION = '0.30.0'.freeze
+  VERSION = '0.30.1'.freeze
 end

data/lib/haveapi/views/version_page.erb

@@ -20,7 +20,7 @@
   <li><a href="https://github.com/vpsfreecz/haveapi/tree/master/clients/js" target="_blank" rel="noopener">JavaScript and TypeScript (callback and async)</a></li>
   <li><a href="https://github.com/vpsfreecz/haveapi/tree/master/clients/python" target="_blank" rel="noopener">Python (sync and async)</a></li>
   <% settings.api_server.documentation_client_profiles(@v).each do |language, profile| %>
-    <li><a href="https://github.com/vpsfreecz/haveapi/tree/master/clients/<%= escape_html(language) %>" target="_blank" rel="noopener"><%= language == :go ? 'Go' : 'Rust (async and blocking)' %></a>: <code><%= escape_html(profile.package_name) %></code> <%= escape_html(profile.package_version) %></li>
+    <li><a href="https://github.com/vpsfreecz/haveapi/tree/master/clients/<%= escape_html(language) %>" target="_blank" rel="noopener"><%= language == :go ? 'Go' : 'Rust (async and blocking)' %></a>: <code><%= escape_html(profile.package_name) %></code><% if profile.package_version %> <%= escape_html(profile.package_version) %><% end %></li>
   <% end %>
   <li><a href="https://github.com/vpsfreecz/haveapi/tree/master/clients/php" target="_blank" rel="noopener">PHP</a></li>
   <li>
@@ -32,7 +32,7 @@
 <p>
   These examples target API v<%= escape_html(@v) %>. The framework and dynamic
   clients share HaveAPI package versions. Generated Go and Rust SDKs use their
-  own package versions and a saved description of the API.
+  own package versions. Their configured SDKs are expected to match this API.
 </p>
 
 <h2>Initialization</h2>

data/spec/client_examples/dynamic_js_spec.rb

@@ -83,6 +83,7 @@ RSpec.describe HaveAPI::ClientExamples::JsClient do
         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')

data/spec/client_examples/profile_mount_spec.rb

@@ -0,0 +1,215 @@
+require 'spec_helper'
+require 'base64'
+
+module ProfileMountSpec
+  User = Struct.new(:login)
+
+  module AuthenticationResources
+    class Session < HaveAPI::Resource
+      auth false
+      version :all
+
+      class Show < HaveAPI::Action
+        route ''
+        http_method :get
+        output(:hash) { string :id }
+        authorize { allow }
+      end
+    end
+  end
+
+  class Provider < HaveAPI::Authentication::Basic::Provider
+    def resource_module
+      AuthenticationResources
+    end
+
+    protected
+
+    def find_user(_request, username, password)
+      User.new(username) if %w[member admin].include?(username) && password == 'pass'
+    end
+  end
+
+  class Added < HaveAPI::Resource
+    auth false
+    version :all
+
+    class Index < HaveAPI::Action
+      route ''
+      http_method :get
+      output(:hash) { string :late }
+      authorize { allow }
+    end
+  end
+end
+
+describe HaveAPI::Server, '#mount' do
+  api do
+    define_resource(:Widget) do
+      version :all
+      auth false
+
+      define_action(:Show) do
+        route '{widget_id}'
+        http_method :get
+        desc HaveAPI.message('profile_mount_spec.action')
+        input(:hash) do
+          string :visible
+          string :secret, default: 'PRIVATE_DEFAULT'
+        end
+        output(:hash) do
+          string :visible
+          string :secret
+        end
+        authorize do |user|
+          unless user.login == 'admin'
+            input blacklist: [:secret]
+            output blacklist: [:secret]
+          end
+          allow
+        end
+
+        # rubocop:disable RSpec/NoExpectationExample
+        example 'visible sample' do
+          path_params 7
+          request({ visible: 'public sample' })
+          response({ visible: 'public response' })
+        end
+
+        example 'privileged sample' do
+          authorize { |user| user.login == 'admin' }
+          path_params 7
+          request({ secret: 'PRIVATE_SAMPLE' })
+          response({ secret: 'PRIVATE_RESPONSE' })
+        end
+        # rubocop:enable RSpec/NoExpectationExample
+      end
+
+      define_action(:Secret) do
+        route 'secret'
+        http_method :get
+        output(:hash) { string :admin_only }
+        authorize { |user| user.login == 'admin' ? allow : deny }
+      end
+    end
+  end
+
+  let(:server) { described_class.new(get_opt(:api_module)) }
+  let(:descriptions) { [] }
+  let(:contexts) { [] }
+  let(:documentation) { Class.new }
+  let(:adapter) do
+    selected_contexts = contexts
+    Class.new do
+      define_method(:resolve) { |**| nil }
+      define_method(:render) do |kind:, context:, **|
+        selected_contexts << context
+        { status: :code, code: JSON.generate(kind == :example ? context.sample : { url: context.version_url }) }
+      end
+    end.new
+  end
+
+  before do
+    generator = Module.new
+    generator.const_set(:VERSION, HaveAPI::VERSION)
+    generator.const_set(:Documentation, documentation)
+    stub_const('HaveAPI::GoClient', generator)
+    allow(registry).to receive(:require).with('haveapi/go_client/documentation').and_return(true)
+    allow(documentation).to receive(:new) do |description:, **|
+      descriptions << description
+      adapter
+    end
+    server.use_version([1, 2])
+    server.default_version = 1
+    server.auth_chain << ProfileMountSpec::Provider
+  end
+
+  def registry
+    server.instance_variable_get(:@documentation_clients)
+  end
+
+  def register(version = 1)
+    server.documentation_clients(version, go: { import_path: 'example.test/widget/client' })
+  end
+
+  def request_as(user, locale)
+    Rack::MockRequest.new(server.app).get(
+      '/mounted/api/v1/', 'HTTP_HOST' => 'example.org', 'HTTP_ACCEPT_LANGUAGE' => locale,
+                          'HTTP_AUTHORIZATION' => "Basic #{Base64.strict_encode64("#{user}:pass")}"
+    )
+  end
+
+  it 'captures the complete selected version after auth, action-state and post-mount routes exist' do
+    register
+    server.action_state = Object.new
+    server.connect_hook(:post_mount) do |_ret, api_server, _sinatra|
+      expect(api_server.documentation_client_profiles(1)).to be_empty
+      api_server.mount_resource('/mounted/api/v1/', 1, ProfileMountSpec::Added, api_server.routes[1][:resources])
+      {}
+    end
+    allow(server).to receive(:describe_version).and_call_original
+    server.mount('/mounted/api/')
+    expect(server).to have_received(:describe_version).once
+    expect(descriptions.size).to eq(1)
+    private_schema = descriptions.first
+    expect(private_schema['help']).to eq('/mounted/api/v1/')
+    expect(private_schema['resources'].keys).to include('widget', 'action_state', 'added')
+    expect(private_schema.dig('resources', 'widget', 'actions').keys).to include('show', 'secret')
+    expect(private_schema.dig('authentication', 'basic', 'resources')).to have_key('session')
+    expect(private_schema.dig('resources', 'widget', 'actions', 'show', 'input', 'parameters')).to have_key('secret')
+    expect(JSON.generate(private_schema)).not_to include('PRIVATE_DEFAULT', 'PRIVATE_SAMPLE', 'PRIVATE_RESPONSE')
+    expect(server.documentation_client_profiles(1).fetch(:go).package_version).to be_nil
+    expect(server.documentation_client_profiles(2)).to be_empty
+  end
+
+  it 'captures each configured version once and does not initialize from requests' do
+    register(1)
+    register(2)
+    server.mount('/mounted/api/')
+    expect(descriptions.map { |description| description['help'] }).to eq(['/mounted/api/v1/', '/mounted/api/v2/'])
+    request_as('member', 'en')
+    request_as('admin', 'cs')
+    expect(descriptions.size).to eq(2)
+    expect { register }.to raise_error(HaveAPI::ClientExample::Profiles::Invalid, /already mounted/)
+  end
+
+  it 'keeps private schema separate from sequential users, locales, HTML and samples' do
+    register
+    server.available_locales = %i[en cs]
+    ::I18n.backend.store_translations(:en, profile_mount_spec: { action: 'Visible English action' })
+    ::I18n.backend.store_translations(:cs, profile_mount_spec: { action: 'Viditelna ceska akce' })
+    server.mount('/mounted/api/')
+    privileged = request_as('admin', 'en')
+    expect(privileged.status).to eq(200)
+    expect(privileged.body).to include('PRIVATE_SAMPLE', 'Visible English action')
+    contexts.clear
+    public_response = request_as('member', 'cs')
+    expect(public_response.status).to eq(200)
+    expect(public_response.body).to include('Viditelna ceska akce', 'init-go', 'example.test/widget/client')
+    expect(public_response.body).not_to include('PRIVATE_DEFAULT', 'PRIVATE_SAMPLE', 'PRIVATE_RESPONSE', 'admin_only', 'haveapi.invalid', 'StructuralSchema')
+    selected = contexts.find { |context| context.action_name == 'show' }
+    expect(selected.action.dig(:input, :parameters).keys.map(&:to_s)).to eq(['visible'])
+    expect(selected.description[:resources]['widget'][:actions]).not_to have_key('secret')
+    expect(selected.sample[:request]).to eq(visible: 'public sample')
+    expect(selected.action[:description]).to eq('Viditelna ceska akce')
+    expect(request_as('member', 'en').body).to include('Visible English action')
+    expect(descriptions.size).to eq(1)
+  end
+
+  it 'makes the server unusable and publishes no profiles after an adapter failure' do
+    register
+    allow(documentation).to receive(:new).and_raise('PRIVATE_SCHEMA_DIAGNOSTIC')
+    expect { server.mount('/') }.to raise_error(HaveAPI::ClientExample::Profiles::Invalid, 'Configured documentation client schema or configuration is invalid')
+    expect(server.app).to be_nil
+    expect(server.documentation_client_profiles(1)).to be_empty
+  end
+
+  it 'makes the server unusable when a post-mount hook fails before finalization' do
+    register
+    server.connect_hook(:post_mount) { raise 'fixture mount failure' }
+    expect { server.mount('/') }.to raise_error(RuntimeError, 'fixture mount failure')
+    expect(documentation).not_to have_received(:new)
+    expect(server.app).to be_nil
+    expect(server.documentation_client_profiles(1)).to be_empty
+  end
+end

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: haveapi
 version: !ruby/object:Gem::Version
-  version: 0.30.0
+  version: 0.30.1
 platform: ruby
 authors:
 - Jakub Skokan
@@ -29,14 +29,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.30.0
+        version: 0.30.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.30.0
+        version: 0.30.1
 - !ruby/object:Gem::Dependency
   name: i18n
   requirement: !ruby/object:Gem::Requirement
@@ -258,6 +258,7 @@ files:
 - lib/haveapi/context.rb
 - lib/haveapi/documentation_clients.rb
 - lib/haveapi/documentation_context.rb
+- lib/haveapi/documentation_schema.rb
 - lib/haveapi/example.rb
 - lib/haveapi/example_list.rb
 - lib/haveapi/exceptions.rb
@@ -354,8 +355,10 @@ files:
 - spec/client_examples/dynamic_mounted_paths_spec.rb
 - spec/client_examples/dynamic_python_spec.rb
 - spec/client_examples/go_spec.rb
+- spec/client_examples/profile_mount_spec.rb
 - spec/client_examples/profiles_spec.rb
 - spec/client_examples/rust_client_spec.rb
+- spec/client_examples/structural_schema_spec.rb
 - spec/client_examples/syntax_spec.rb
 - spec/common_spec.rb
 - spec/documentation/auth_filtering_spec.rb