haveapi 0.29.12 → 0.30.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8f9214742c7d4ef64a37a4a0891ebe1dc492d551f06ce0956e0b2993e432dad6
-  data.tar.gz: f1a203af566678c875c2fa347d9a3fbfcc131024bf8ec7f9fc95c46dad79a186
+  metadata.gz: 3d58d9e427d490d025fec95d60739ea4aa17b4e86cc3fb9978b7c00b751e6e75
+  data.tar.gz: e0b958ac9924d4cacaf75513d79690c3ed2519d6b5d1522a0433d92285742887
 SHA512:
-  metadata.gz: 63418943311b0f40e2b74060976a04c309141c9496d68dca6fe41607ece1beecc19a4309213666b1d427aae0670e4b1c5a77c4bed0482da96b2c52e6a218426b
-  data.tar.gz: b4dfa50972de0704f29f49c4d1f964643da27982e6123d7361ad3475e28441b139da3099d4aa9db53051e4cc1a95bd697be06e616f365a06bd9c1677efd42978
+  metadata.gz: 78980868da2569146dccf39ce14309e27b97d51b4a266b7709813faafb191577520f31408dd6ebf1e5310b37bd43197e9b4e838503cd60c5d8b480607e8c5f6d
+  data.tar.gz: 5a2a6ad3e686e3d77b86fb83e7e27b5eaf5e2ac573013fa938255b203405fdabe899a605f71cea8088769e81f323b6678be00272889c56d629757356d9170d87

data/.gitignore

@@ -1,4 +1,5 @@
 doc/protocol.*
 doc/create-client.md
 doc/typed-input-validation.md
+doc/client-examples.md
 doc/json-schema.html

data/Rakefile

@@ -13,6 +13,7 @@ task :check_doc do
     doc/protocol.md
     doc/create-client.md
     doc/typed-input-validation.md
+    doc/client-examples.md
     doc/protocol.png
   ]
   missing = required.reject { |path| File.file?(path) && File.size?(path) }

data/doc/client-examples.md

@@ -0,0 +1,198 @@
+# Client examples in API documentation
+
+The Ruby server renders examples from the current user's API description.
+JavaScript and TypeScript examples cover callback and async clients; Python
+examples cover sync and async clients. These clients need no server configuration.
+Ruby, PHP, CLI, curl and HTTP examples are also available. A sample
+that a client cannot represent shows a limitation instead of dropping input or
+inventing a successful result.
+
+Go and Rust tabs require a profile for a generated SDK. Their package versions
+are independent of HaveAPI and the API version. Without a profile, the server
+hides those clients from the overview and all initialization, authentication and
+action panels. Install the matching generator gem only when configuring its
+profile; ordinary servers do not depend on either generator.
+
+## Configure a generated SDK
+
+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',
+  go: {
+    import_path: 'example.org/widget/client',
+    module_version: 'v1.2.3',
+    description_path: '/srv/widget-sdk/api-1.0.json',
+    generator_version: '0.30.0'
+  },
+  rust: {
+    snapshot_path: '/srv/widget-sdk/api-1.0.snapshot.json',
+    generator_config_path: '/srv/widget-sdk/generator.toml',
+    generator_version: '0.30.0'
+  }
+)
+```
+
+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
+
+Existing renderer positional constructors and `init`, `auth(method, desc)` and
+`example(sample)` or `request(sample)`/`response(sample)` methods still work.
+The registry binds a request-local `HaveAPI::ClientExample::Context` through
+`with_context`. It holds the selected version, URLs including the API mount,
+the filtered description, and the current resource, action and sample.
+`context.with(...)` creates another frozen copy without freezing the server's
+shared description.
+
+Renderers may return a String or nil through their existing methods. New
+renderers return either `{status: :code, code: source}` or
+`{status: :limitation, reason: text}`. Source and limitation text are plain
+strings, escaped once by the templates. A stable class `id` identifies a
+variant; `code` selects its syntax language. `available?(context)` controls the
+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
+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
+
+`make test-documentation` checks renderers, contexts, profiles, rendered HTML and
+local assets. Prepare the component bundles and JavaScript development
+dependencies with `make release-deps` first. The target builds the JavaScript
+package before compiling TypeScript examples against its public declarations;
+the Ruby server CI uses the same order.
+
+`make test-documentation-python` additionally checks the Python renderer limits
+against the real request encoder. It requires the locked Python environment
+prepared by `make release-deps` and is included in `make test`. The ordinary
+Ruby renderer checks run without the Python package environment.
+
+Each client also has acceptance commands that check executable snippets against
+installed packages or a generated SDK. These use
+rendered source against disposable fixtures; syntax checks alone do not
+establish that client calls or authentication work. See each client's
+development documentation for its test environment. Highlighter rebuilding is
+described in [utils/highlight](../utils/highlight/README.md).

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.29.12'
+  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/client_example.rb

@@ -33,6 +33,47 @@ module HaveAPI
         @order
       end
 
+      def id(value = nil)
+        @id = value.to_s.freeze unless value.nil?
+        return @id if @id
+
+        # Preserve the anchors of the retained built-in formats.
+        { 'RubyClient' => '0', 'PhpClient' => '2', 'RubyCli' => '3', 'Curl' => '5', 'Http' => '6' }[name.to_s.split('::').last] ||
+          name.to_s.gsub('::', '-').downcase
+      end
+
+      def available?(_context)
+        true
+      end
+
+      def render(kind, context:, auth_method: nil, auth_description: nil)
+        arguments = [context.host, context.base_url, context.version]
+        arguments.push(context.resource_path, context.resource, context.action_name, context.action) if kind == :example
+        renderer = new(*arguments)
+        renderer.with_context(context)
+        result = case kind
+                 when :init then renderer.init
+                 when :auth then renderer.auth(auth_method, auth_description)
+                 when :example
+                   if renderer.respond_to?(:example)
+                     renderer.example(context.sample)
+                   else
+                     [renderer.request(context.sample), renderer.response(context.sample)].compact.join("\n\n")
+                   end
+                 else raise ArgumentError, "Unknown client example kind: #{kind}"
+                 end
+        return if result.nil?
+        return { status: :code, code: result.dup.freeze }.freeze if result.is_a?(String)
+
+        if result.is_a?(Hash) && result[:status] == :code && result[:code].is_a?(String)
+          { status: :code, code: result[:code].dup.freeze }.freeze
+        elsif result.is_a?(Hash) && result[:status] == :limitation && result[:reason].is_a?(String)
+          { status: :limitation, reason: result[:reason].dup.freeze }.freeze
+        else
+          raise ArgumentError, 'Invalid client example result'
+        end
+      end
+
       def register(klass)
         @clients ||= []
         @clients << klass
@@ -59,7 +100,7 @@ module HaveAPI
       end
     end
 
-    attr_reader :resource_path, :resource, :action_name, :action, :host, :base_url, :version
+    attr_reader :resource_path, :resource, :action_name, :action, :host, :base_url, :version, :context
 
     def initialize(host, base_url, version, *args)
       @host = host
@@ -72,6 +113,11 @@ module HaveAPI
 
     def auth(method, desc); end
 
+    def with_context(value)
+      @context = value
+      self
+    end
+
     def version_url
       File.join(base_url, "v#{version}", '/')
     end

data/lib/haveapi/client_examples/dynamic_helpers.rb

@@ -0,0 +1,129 @@
+require 'json'
+require 'haveapi/client_example'
+
+module HaveAPI::ClientExamples
+  module DynamicHelpers
+    class Unsupported < StandardError; end
+
+    def field(value, name, default = nil)
+      return default unless value.is_a?(Hash)
+
+      value.fetch(name) { value.fetch(name.to_s, default) }
+    end
+
+    def code_result
+      { status: :code, code: yield.freeze }.freeze
+    rescue Unsupported, JSON::GeneratorError => e
+      { status: :limitation, reason: e.message.freeze }.freeze
+    end
+
+    def limitation(reason)
+      { status: :limitation, reason: reason.freeze }.freeze
+    end
+
+    def api_base
+      context ? context.base_url : base_url
+    end
+
+    def api_version
+      context ? context.version : version.to_s
+    end
+
+    def current_action
+      context&.action || action
+    end
+
+    def current_resource_path
+      context&.resource_path || resource_path
+    end
+
+    def current_action_name
+      context&.action_name || action_name
+    end
+
+    def json_data(value)
+      case value
+      when Hash
+        result = {}
+        value.each do |key, entry|
+          unless key.is_a?(String) || key.is_a?(Symbol)
+            raise Unsupported, 'This sample has a non-string object key.'
+          end
+          raise Unsupported, 'This sample has duplicate serialized object keys.' if result.has_key?(key.to_s)
+
+          result[key.to_s] = json_data(entry)
+        end
+        result
+      when Array
+        value.map { |entry| json_data(entry) }
+      when String, Integer, TrueClass, FalseClass, NilClass
+        value
+      when Float
+        raise Unsupported, 'This sample has a non-finite number.' unless value.finite?
+
+        value
+      else
+        raise Unsupported, 'This sample contains a value without a supported literal representation.'
+      end
+    end
+
+    def structured_sample(sample)
+      unless sample.is_a?(Hash) && (!field(sample, :request).nil? || !field(sample, :response).nil?)
+        raise Unsupported, 'This example contains prose only; no executable request is supplied.'
+      end
+
+      %i[global object].each do |scope|
+        next if scope == :object && field(current_action, :input).nil?
+
+        input = field(field(field(current_action, :meta), scope), :input)
+        if field(input, :parameters, {}).values.any? { |parameter| field(parameter, :required) }
+          raise Unsupported, 'This action requires input metadata that the sample format cannot supply.'
+        end
+      end
+
+      placeholders = field(current_action, :path, '').scan(/\{([a-zA-Z0-9_-]+)\}/).flatten
+      values = field(sample, :path_params, []) || []
+      unless values.is_a?(Array) && values.length == placeholders.length
+        raise Unsupported, 'The sample does not supply every action path argument.'
+      end
+      unless values.all? { |value| value.is_a?(String) || value.is_a?(Integer) }
+        raise Unsupported, 'Action path arguments must be strings or integers.'
+      end
+
+      request = field(sample, :request)
+      input = field(current_action, :input)
+      if !request.nil? && input.nil? && request != {}
+        raise Unsupported, 'The sample supplies input for an action without an input description.'
+      end
+
+      if request.is_a?(Hash) && input
+        known = field(input, :parameters, {}).keys.map(&:to_s)
+        unless (request.keys.map(&:to_s) - known).empty?
+          raise Unsupported, 'The sample contains input parameters absent from the visible description.'
+        end
+      end
+      [placeholders.zip(values).to_h, json_data(request)]
+    end
+
+    def supported_auth?(method)
+      %i[basic token oauth2].include?(method.to_sym) &&
+        (!context || field(context.description, :authentication, {}).keys.map(&:to_s).include?(method.to_s))
+    end
+
+    def token_request_fields(description)
+      token = field(field(description, :resources, {}), :token, {})
+      request = field(field(token, :actions, {}), :request, {})
+      field(field(request, :input, {}), :parameters, {})
+    end
+
+    def token_login_fields(description)
+      token_request_fields(description).reject do |name, _|
+        %w[token lifetime interval].include?(name.to_s)
+      end
+    end
+
+    def indent(source, spaces = 2)
+      source.lines.map { |line| line.strip.empty? ? line : "#{' ' * spaces}#{line}" }.join
+    end
+  end
+end

data/lib/haveapi/client_examples/go_client.rb

@@ -0,0 +1,37 @@
+require 'haveapi/client_example'
+
+module HaveAPI::ClientExamples
+  class GoClient < HaveAPI::ClientExample
+    label 'Go'
+    id 'go'
+    code :go
+    order 16
+
+    def self.available?(context)
+      context.profile && context.profile.language == :go
+    end
+
+    def init
+      render_documentation(:init)
+    end
+
+    def auth(method, desc)
+      render_documentation(:auth, auth_method: method, auth_description: desc)
+    end
+
+    def example(sample)
+      render_documentation(:example, sample:)
+    end
+
+    protected
+
+    def render_documentation(kind, sample: nil, **)
+      unless context && self.class.available?(context)
+        return { status: :limitation, reason: 'A Go SDK profile is required.' }.freeze
+      end
+
+      selected = kind == :example ? context.with(sample:) : context
+      context.profile.adapter.render(kind:, context: selected, mode: :sync, **)
+    end
+  end
+end

data/lib/haveapi/client_examples/js_async_client.rb

@@ -0,0 +1,14 @@
+require 'haveapi/client_examples/js_client'
+
+module HaveAPI::ClientExamples
+  class JsAsyncClient < JsClient
+    label 'JavaScript (async)'
+    id 'javascript-async'
+    code :javascript
+    order 11
+
+    def asynchronous?
+      true
+    end
+  end
+end