haveapi 0.29.9 → 0.30.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d432ecb79a2fef09f812f5282c0d23425c31f58452d4da814b6fe2ef65ac6414
-  data.tar.gz: abb6bc99854b4eddb61bd94fffaaf1db7dbaa51db8a4732801517f6ea620b001
+  metadata.gz: 4d308a5a5e69e262ce771a7ec707783c63af02c38726df08c8d5c2f68bae18d3
+  data.tar.gz: b70e5a101d631bae5e90d999f50d621643f511fef3a61a45b78f35369e0528c6
 SHA512:
-  metadata.gz: bde834ad60060ad0e61b21070518c4f3ba7252684d5bd2d595b256b0c15f84d70d4a25efbd30666d7bb2e69b162ab6e8ff2b3ad420b8574bb275d7453f339659
-  data.tar.gz: bf305ce254ba7824812dd8755bc2f061b54ebc5b6a74d40cf0e91976048f6d257c34b4b6098ff49e6ad331b8aae612f91e521aea39af5f22f83abfb4eebbec11
+  metadata.gz: f3081d61476f4ddeb15b44028ff40a9073587520c13bf776f6e675ebcb41439d236c2f463029c969f589e6342e8ca13c550b3d6ab6c1a6dfb639b1bc6a99a940
+  data.tar.gz: 6523e8942f1fa7ef18c4fbdab85ea073b1e6df14249c948f270b573c3193de3c8d39046440ca132d9f4f30f9d94393392cedc9170310f419a2be8607bac07d0a

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,96 @@
+# 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. 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.
+
+```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'
+  }
+)
+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.
+
+## 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
+saved generator schema 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.9'
+  s.add_dependency 'haveapi-client', '~> 0.30.0'
   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