haveapi 0.30.0 → 0.30.2

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_context.rb

@@ -10,26 +10,56 @@ module HaveAPI
       def initialize(version:, host:, base_url:, version_url:, description:,
                      resource_path: [], resource: nil, action_name: nil, action: nil,
                      sample: nil, profile: nil)
-        @version = version.to_s.dup.freeze
-        @host = host.to_s.dup.freeze
-        @base_url = base_url.to_s.dup.freeze
-        @version_url = version_url.to_s.dup.freeze
-        @description = copy(description)
-        @resource_path = copy(resource_path.map(&:to_s))
-        @resource = copy(resource)
-        @action_name = action_name.nil? ? nil : action_name.to_s.dup.freeze
-        @action = copy(action)
-        @sample = copy(sample)
-        @profile = profile
+        @version = normalize(:version, version)
+        @host = normalize(:host, host)
+        @base_url = normalize(:base_url, base_url)
+        @version_url = normalize(:version_url, version_url)
+        @description = normalize(:description, description)
+        @resource_path = normalize(:resource_path, resource_path)
+        @resource = normalize(:resource, resource)
+        @action_name = normalize(:action_name, action_name)
+        @action = normalize(:action, action)
+        @sample = normalize(:sample, sample)
+        @profile = normalize(:profile, profile)
         freeze
       end
 
       def with(**changes)
-        self.class.new(**FIELDS.to_h { |field| [field, public_send(field)] }, **changes)
+        unless instance_of?(Context)
+          return self.class.new(**FIELDS.to_h { |field| [field, public_send(field)] }, **changes)
+        end
+
+        unknown = changes.keys - FIELDS
+        unless unknown.empty?
+          raise ArgumentError, "unknown keyword#{'s' if unknown.length > 1}: #{unknown.map(&:inspect).join(', ')}"
+        end
+
+        # Unchanged fields are already owned snapshots; caller-supplied values
+        # must still cross the same ownership boundary as initial construction.
+        derived = dup
+        changes.each do |field, value|
+          derived.instance_variable_set("@#{field}", normalize(field, value))
+        end
+        derived.freeze
       end
 
       private
 
+      def normalize(field, value)
+        case field
+        when :version, :host, :base_url, :version_url
+          value.to_s.dup.freeze
+        when :resource_path
+          copy(value.map(&:to_s))
+        when :action_name
+          value.nil? ? nil : value.to_s.dup.freeze
+        when :profile
+          value
+        else
+          copy(value)
+        end
+      end
+
       def copy(value)
         case value
         when Hash

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.2'.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/context_performance_spec.rb

@@ -0,0 +1,72 @@
+require 'spec_helper'
+
+describe HaveAPI::ClientExample::Context, '#with' do
+  let(:sample) { { request: { payload: { 'items' => [0, false, '', nil] } } } }
+  let(:profile) { Object.new.freeze }
+
+  def parent_context(resource_count)
+    action = { input: { parameters: { payload: { type: 'Custom' } } }, examples: [sample] }
+    description = {
+      resources: resource_count.times.to_h do |index|
+        ["resource#{index}", { description: "Resource #{index}", actions: { 'show' => action } }]
+      end
+    }
+    described_class.new(version: '1', host: 'example.test', base_url: 'http://example.test/benchmark/api/',
+                        version_url: 'http://example.test/benchmark/api/v1/', description:,
+                        resource_path: ['resource0'], resource: description[:resources]['resource0'],
+                        action_name: 'show', action:, sample:)
+  end
+
+  def allocated_derivations(parent, changes, count: 40)
+    # Taking the minimum of repeated batches avoids incidental VM bookkeeping
+    # spikes. Expectations and fixture construction stay outside this loop.
+    Array.new(3) do
+      before = GC.stat(:total_allocated_objects)
+      count.times { parent.with(**changes) }
+      GC.stat(:total_allocated_objects) - before
+    end.min
+  end
+
+  it 'shares every unchanged field and owns a different snapshot for a new request' do
+    parent = parent_context(8)
+    other_request = parent_context(8)
+    children = [parent.with(profile:), parent.with(sample:)]
+    fields = %i[version host base_url version_url description resource_path resource action_name action sample profile]
+
+    children.each_with_index do |child, index|
+      changed = index == 0 ? :profile : :sample
+      (fields - [changed]).each do |field|
+        expect(child.public_send(field)).to equal(parent.public_send(field))
+      end
+      expect(child).to be_frozen
+    end
+    expect(other_request.description).to eq(parent.description)
+    expect(other_request.description).not_to equal(parent.description)
+    expect(other_request.description[:resources]).not_to equal(parent.description[:resources])
+    replacement = parent.with(description: parent.description)
+    expect(replacement.description).to eq(parent.description)
+    expect(replacement.description).not_to equal(parent.description)
+  end
+
+  it 'keeps allocations independent of unrelated description size for small changes' do
+    small = parent_context(8)
+    large = parent_context(128)
+    changes = [{ profile: }, { sample: }]
+    [small, large].each do |parent|
+      changes.each { |change| 80.times { parent.with(**change) } }
+    end
+
+    changes.each do |change|
+      small_allocations = allocated_derivations(small, change)
+      large_allocations = allocated_derivations(large, change)
+      # CRuby 3.4 allocates 200/200 objects for profile changes and 560/560 for
+      # samples at these sizes. The original constructor path grows from 12,560
+      # to 151,760. Allow 32 extra objects per derivation for VM bookkeeping;
+      # identity assertions independently forbid whole-description copies.
+      expect(large_allocations).to be <= small_allocations + (40 * 32)
+      [small, large].each do |parent|
+        expect(parent.with(**change).description).to equal(parent.description)
+      end
+    end
+  end
+end