haveapi-go-client 0.29.12 → 0.30.0

data/spec/documentation_acceptance.rb

@@ -0,0 +1,271 @@
+# Run after committed-deliverable review; this generates, compiles and executes SDKs.
+require 'json'
+require 'open3'
+require 'tmpdir'
+require 'tempfile'
+require 'webrick'
+
+require 'haveapi/go_client/documentation'
+require 'haveapi/documentation_clients'
+require 'haveapi/client_examples/go_client'
+require_relative 'support/documentation_fixture'
+
+class GoDocumentationAcceptance
+  def self.build_command(destination)
+    # The disposable consumer has no source history to stamp into its binaries.
+    ['go', 'build', '-buildvcs=false', '-o', destination, './cmd/...']
+  end
+
+  def self.expected_cases
+    # The SDK emits an empty metadata envelope for this metadata-bearing action.
+    object_body = { 'widget' => { 'name' => nil, 'enabled' => false, 'count' => 0 }, '_meta' => {} }
+    {
+      init: {}, basic: {}, token: {}, oauth2: {},
+      object: { body: object_body, output: '123' },
+      empty: { body: { 'widget' => {} } }, omitted: { body: { 'widget' => {} } },
+      list: { output: "1\n2" }, fail: { output: 'fixture failure' },
+      association: { output: '9' },
+      # The SDK encodes false/true query booleans as 0/1.
+      query: { query: { 'widget[name]' => '', 'widget[enabled]' => '0', 'widget[count]' => '0' } },
+      operation: { state: true },
+      basic_call: { body: object_body, auth: { authorization: "Basic #{['fixture-user:fixture-password'].pack('m0')}" } },
+      token_call: { body: object_body, auth: { token: 'fixture-token' } },
+      oauth2_call: { body: object_body, auth: { oauth2: 'fixture-access-token' } },
+      hostile: { body: { 'widget' => { 'name' => "quote\"\\\n雪</script>" }, '_meta' => {} }, output: '123' }
+    }
+  end
+
+  def self.run!
+    check_environment!
+    new.run!
+  end
+
+  # The same optional gems must be visible to Bundler and the product loader.
+  # This preflight performs no generation, compilation or server startup.
+  def self.check_environment!
+    %w[haveapi haveapi-go-client].each do |name|
+      raise "#{name} is absent from the acceptance bundle" unless Gem.loaded_specs.has_key?(name)
+    end
+    unless Gem.loaded_specs.fetch('haveapi-go-client').version.to_s == HaveAPI::GoClient::VERSION
+      raise 'activated Go generator specification does not match its loaded version'
+    end
+
+    Tempfile.create(['haveapi-go-documentation-profile-', '.json']) do |file|
+      file.write(JSON.generate(GoDocumentationFixture.description))
+      file.flush
+      profiles = HaveAPI::ClientExample::Profiles.new
+      profiles.register('7', go: {
+        import_path: 'example.test/sdk/client', module_version: 'v1.2.3', description_path: file.path,
+        generator_version: Gem.loaded_specs.fetch('haveapi-go-client').version.to_s
+      })
+      profiles.mount(['7'])
+      raise 'configured Go profile is unavailable' unless profiles.for_version('7').fetch(:go).language == :go
+    end
+  end
+
+  def initialize
+    @requests = Queue.new
+    @server = WEBrick::HTTPServer.new(
+      BindAddress: '127.0.0.1', Port: 0, AccessLog: [], Logger: WEBrick::Log.new(File::NULL)
+    )
+    @server.mount_proc('/') { |request, response| serve(request, response) }
+  end
+
+  def run!
+    thread = Thread.new { @server.start }
+    Dir.mktmpdir('haveapi-go-documentation-') do |dir|
+      prepare_sdk(dir)
+      prepare_programs(dir)
+      command('gofmt', '-w', File.join(dir, 'consumer'))
+      command(*self.class.build_command(File.join(dir, 'bin')), chdir: File.join(dir, 'consumer'))
+      @cases.each do |name, expected|
+        stdout = command(File.join(dir, 'bin', name.to_s), env: {
+          'HAVEAPI_USER' => 'fixture-user', 'HAVEAPI_PASSWORD' => 'fixture-password',
+          'HAVEAPI_TOKEN' => 'fixture-token', 'HAVEAPI_ACCESS_TOKEN' => 'fixture-access-token'
+        })
+        verify(name, expected, stdout)
+      end
+    end
+    # This is a standalone acceptance runner, not an RSpec example.
+    $stdout.write("Go documentation acceptance: #{@cases.length} rendered programs compiled and executed\n") # rubocop:disable RSpec/Output
+  ensure
+    @server.shutdown
+    thread&.join
+  end
+
+  private
+
+  def prepare_sdk(dir)
+    @description = GoDocumentationFixture.description
+    @description[:resources][:client][:resources][:child][:actions].merge!(
+      empty: GoDocumentationFixture.action(path: '/mounted/v7/empty', input: input),
+      omitted: GoDocumentationFixture.action(path: '/mounted/v7/omitted', input: input),
+      list: GoDocumentationFixture.action(path: '/mounted/v7/list', method: 'GET', output: output(layout: 'hash_list')),
+      association: GoDocumentationFixture.action(
+        path: '/mounted/v7/association', method: 'GET',
+        output: GoDocumentationFixture.io({ owner: { type: 'Resource', resource: ['owner'], value_id: 'id', value_label: 'label' } })
+      ),
+      fail: GoDocumentationFixture.action(path: '/mounted/v7/fail', method: 'GET'),
+      query: GoDocumentationFixture.action(path: '/mounted/v7/query', method: 'GET', input: input),
+      operation: GoDocumentationFixture.action(
+        path: '/mounted/v7/operation', method: 'GET', blocking: true,
+        meta: { global: { output: GoDocumentationFixture.io({ action_state_id: { type: 'Integer' } }, namespace: false) } }
+      )
+    )
+    # This exact local JSON is both generator input and the configured profile.
+    description_path = File.join(dir, 'sdk-description.json')
+    File.write(description_path, JSON.pretty_generate(@description))
+    saved = JSON.parse(File.read(description_path), symbolize_names: true)
+    generator = HaveAPI::GoClient::Generator.from_description(saved, File.join(dir, 'sdk'),
+                                                              module: 'example.test/sdk', package: 'client')
+    generator.generate
+    profiles = HaveAPI::ClientExample::Profiles.new
+    profiles.register('7', go: {
+      import_path: 'example.test/sdk/client', module_version: 'v1.2.3', description_path:,
+      generator_version: HaveAPI::GoClient::VERSION
+    })
+    profiles.mount(['7'])
+    @profile = profiles.for_version('7').fetch(:go)
+    FileUtils.mkdir_p(File.join(dir, 'consumer'))
+    FileUtils.mkdir_p(File.join(dir, 'bin'))
+    File.write(File.join(dir, 'consumer/go.mod'), <<~MOD)
+      module example.test/documentation-consumer
+
+      go 1.20
+
+      require example.test/sdk v1.2.3
+      replace example.test/sdk => ../sdk
+    MOD
+  end
+
+  def prepare_programs(dir)
+    @cases = self.class.expected_cases
+    @cases.each_key do |name|
+      kind = if name == :init
+               :init
+             else
+               (%i[basic token oauth2].include?(name) ? :auth : :example)
+             end
+      action_name = %i[object basic_call token_call oauth2_call hostile].include?(name) ? :client : name
+      action = @description.dig(:resources, :client, :resources, :child, :actions, action_name)
+      sample = case name
+               when :object, :basic_call, :token_call, :oauth2_call then GoDocumentationFixture.sample
+               when :hostile then GoDocumentationFixture.sample.merge(request: { name: "quote\"\\\n雪</script>" })
+               when :empty then { request: {}, response: {}, status: true }
+               when :omitted then { response: {}, status: true }
+               when :list then { response: [{ id: 1 }, { id: 2 }], status: true }
+               when :association then { response: { owner: { id: 9 } }, status: true }
+               when :fail then { status: false }
+               when :query then { request: { name: nil, enabled: false, count: 0 }, status: true }
+               else { status: true }
+               end
+      context = HaveAPI::ClientExample::Context.new(
+        version: '7', host: '127.0.0.1', base_url: "http://127.0.0.1:#{@server.config[:Port]}/mounted/",
+        version_url: "http://127.0.0.1:#{@server.config[:Port]}/mounted/v7/", description: @description,
+        resource_path: %w[client child], action_name:, action:, sample:, profile: @profile
+      )
+      result = HaveAPI::ClientExamples::GoClient.render(kind, context:, auth_method: name, auth_description: {})
+      raise "#{name}: unexpected limitation: #{result[:reason]}" unless result[:status] == :code
+
+      path = File.join(dir, 'consumer/cmd', name.to_s)
+      FileUtils.mkdir_p(path)
+      # The complete program is the actual renderer result, without replacements.
+      source = result.fetch(:code)
+      if name.to_s.end_with?('_call')
+        auth = HaveAPI::ClientExamples::GoClient.render(:auth, context:, auth_method: name.to_s.delete_suffix('_call').to_sym, auth_description: {})
+        raise "#{name}: authentication limitation" unless auth[:status] == :code
+
+        source = compose(auth.fetch(:code), source)
+      end
+      File.write(File.join(path, 'main.go'), source)
+    end
+  end
+
+  def input
+    GoDocumentationFixture.io({ name: { type: 'String', nullable: true }, enabled: { type: 'Boolean' },
+                                count: { type: 'Integer' }, unused: { type: 'String' } })
+  end
+
+  def output(layout: 'hash')
+    GoDocumentationFixture.io({ id: { type: 'Integer' }, name: { type: 'String', nullable: true } }, layout:)
+  end
+
+  def serve(request, response)
+    @requests << { path: request.path, query: request.query, raw_query: request.query_string, body: request.body,
+                   auth: { authorization: request['Authorization'], token: request['X-Token'], oauth2: request['X-OAuth'] } }
+    response['Content-Type'] = 'application/json'
+    result = case request.path
+             when '/mounted/v7/fail'
+               { status: false, message: 'fixture failure', errors: { name: ['invalid'] } }
+             when '/mounted/v7/list'
+               { status: true, response: { widget: [{ id: 1 }, { id: 2 }] } }
+             when '/mounted/v7/association'
+               { status: true, response: { widget: { owner: { id: 9 } } } }
+             when '/mounted/v7/operation'
+               { status: true, response: { _meta: { action_state_id: 55 } } }
+             when '/mounted/v7/action_states/55'
+               { status: true, response: { action_state: { id: 55 } } }
+             else
+               { status: true, response: { widget: { id: 123 } } }
+             end
+    response.body = JSON.generate(result)
+  end
+
+  def verify(name, expected, stdout)
+    if %i[init basic token oauth2].include?(name)
+      raise "#{name}: initialization performed a request" unless @requests.empty?
+
+      return
+    end
+
+    request = @requests.pop(true)
+    expected_path = %i[object basic_call token_call oauth2_call hostile].include?(name) ? '/mounted/v7/clients/42/children/a/b' : "/mounted/v7/#{name}"
+    raise "#{name}: unexpected mounted/versioned path #{request[:path]}" unless request[:path] == expected_path
+    if expected[:body] && JSON.parse(request[:body]) != expected[:body]
+      raise "#{name}: supplied input or omission was not preserved: #{request[:body]}"
+    end
+
+    if expected[:query] && request[:query] != expected[:query]
+      raise "#{name}: query values were not preserved: expected #{expected[:query].inspect}, " \
+            "got #{request[:query].inspect}; raw query #{request[:raw_query].inspect}"
+    end
+
+    if expected[:auth] && !expected[:auth].all? { |key, value| request[:auth][key] == value }
+      raise "#{name}: rendered authentication did not reach the fixture"
+    end
+    raise "#{name}: unexpected rendered output #{stdout.inspect}" if expected[:output] && !stdout.include?(expected[:output])
+
+    if expected[:state]
+      state = @requests.pop(true)
+      raise 'operation: generated helper used the wrong route' unless state[:path] == '/mounted/v7/action_states/55'
+    end
+    raise "#{name}: unexpected extra request" unless @requests.empty?
+  end
+
+  # Compose exact rendered sections, deduplicating their shared initialization.
+  def compose(auth, action)
+    imports = [auth, action].flat_map { |source| source.match(/^import \(\n(.*?)\n\)/m)[1].lines(chomp: true) }.uniq
+    auth_body = auth.match(/^func main\(\) \{\n(.*)\n\}\n/m)[1].lines
+    action_body = action.match(/^func main\(\) \{\n(.*)\n\}\n/m)[1].lines
+    raise 'rendered initialization differs across sections' unless auth_body.first == action_body.first
+
+    [auth.split('import (', 2).first, "import (\n", imports.join("\n"), "\n)\n\nfunc main() {\n",
+     auth_body.join, "\n", action_body.drop(1).join, "\n}\n"].join
+  end
+
+  def command(*args, chdir: nil, env: {})
+    environment = { 'GOWORK' => 'off', 'GOPROXY' => 'off', 'GOSUMDB' => 'off', 'GOTOOLCHAIN' => 'local' }.merge(env)
+    stdout, stderr, status = Open3.capture3(environment, *args, **(chdir ? { chdir: } : {}))
+    raise "#{args.first} failed: #{stdout}\n#{stderr}" unless status.success?
+
+    stdout
+  end
+end
+
+if $0 == __FILE__
+  case ARGV
+  when [] then GoDocumentationAcceptance.run!
+  when ['--check-environment'] then GoDocumentationAcceptance.check_environment!
+  else raise ArgumentError, 'usage: documentation_acceptance.rb [--check-environment]'
+  end
+end

data/spec/documentation_build_check.rb

@@ -0,0 +1,31 @@
+# Native dry-run regression: no compiler, listener or generated SDK is started.
+require_relative 'documentation_acceptance'
+
+class GoDocumentationBuildCheck
+  def self.run!
+    Dir.mktmpdir('haveapi-go-documentation-build-') do |root|
+      # Own this invalid ancestor marker; never rely on or alter ambient Git state.
+      Dir.mkdir(File.join(root, '.git'))
+      consumer = File.join(root, 'consumer')
+      FileUtils.mkdir_p(File.join(consumer, 'cmd/probe'))
+      File.write(File.join(consumer, 'go.mod'), "module example.test/documentation-consumer\n\ngo 1.20\n")
+      File.write(File.join(consumer, 'cmd/probe/main.go'), "package main\nfunc main() {}\n")
+      command = GoDocumentationAcceptance.build_command(File.join(root, 'bin')).insert(2, '-n', '-x')
+      environment = { 'GOWORK' => 'off', 'GOPROXY' => 'off', 'GOSUMDB' => 'off', 'GOTOOLCHAIN' => 'local' }
+      _output, error, status = Open3.capture3(environment, *command, chdir: consumer)
+      raise "documentation build plan failed: #{error}" unless status.success?
+      raise 'documentation build unexpectedly queried Git status' if error.include?('git status --porcelain')
+
+      # Prove the regression condition with the same command minus its policy flag.
+      control = command.reject { |argument| argument == '-buildvcs=false' }
+      _output, error, status = Open3.capture3(environment, *control, chdir: consumer)
+      unless !status.success? && error.include?('error obtaining VCS status') &&
+             error.include?("cd #{root}\n") && error.include?('git status --porcelain')
+        raise "unflagged control did not reproduce owned ancestor VCS discovery: #{error}"
+      end
+    end
+    $stdout.write("Go documentation build dry-run and unflagged VCS control passed\n") # rubocop:disable RSpec/Output
+  end
+end
+
+GoDocumentationBuildCheck.run! if $0 == __FILE__

data/spec/documentation_wire_check.rb

@@ -0,0 +1,94 @@
+# Pure verifier regression: no generator, compiler or listener is started.
+require 'stringio'
+require 'uri'
+require_relative 'documentation_acceptance'
+
+class GoDocumentationWireCheck
+  OBJECT_BODY = JSON.parse('{"widget":{"count":0,"enabled":false,"name":null},"_meta":{}}').freeze
+  OBJECT_CASES = %i[object basic_call token_call oauth2_call].freeze
+
+  def self.run!
+    OBJECT_CASES.each do |name|
+      verify(name, OBJECT_BODY)
+      reject_change(name) { |body| body['_meta'] = { 'includes' => 'unrequested' } }
+      reject_change(name) { |body| body['_meta'] = nil }
+      reject_change(name) { |body| body.delete('_meta') }
+      reject_change(name) { |body| body['extra'] = 'unrequested' }
+      reject_change(name) { |body| body['widget']['unused'] = '' }
+      reject_change(name) { |body| body['widget']['enabled'] = true }
+      reject_change(name) { |body| body['widget']['count'] = 1 }
+      reject_change(name) { |body| body['widget']['name'] = '' }
+      %w[name enabled count].each do |field|
+        reject_change(name) { |body| body['widget'].delete(field) }
+      end
+    end
+
+    hostile = { 'widget' => { 'name' => "quote\"\\\n雪</script>" }, '_meta' => {} }
+    verify(:hostile, hostile)
+    reject_change(:hostile, hostile) { |body| body['_meta']['includes'] = 'unrequested' }
+    reject_change(:hostile, hostile) { |body| body['widget']['unused'] = '' }
+
+    %i[empty omitted].each do |name|
+      body = { 'widget' => {} }
+      verify(name, body)
+      reject_change(name, body) { |changed| changed['_meta'] = {} }
+      reject_change(name, body) { |changed| changed['widget']['unused'] = '' }
+      reject_change(name, body) { |changed| changed.delete('widget') }
+    end
+    check_query
+    $stdout.write("Go documentation wire verifier: 7 accepted bodies and 52 rejected mutations\n") # rubocop:disable RSpec/Output
+    $stdout.write("Go documentation query verifier: 1 accepted query and 8 rejected mutations\n") # rubocop:disable RSpec/Output
+  end
+
+  def self.check_query
+    verify_query('widget%5Bcount%5D=0&widget%5Benabled%5D=0&widget%5Bname%5D=')
+    original = { 'widget[name]' => '', 'widget[enabled]' => '0', 'widget[count]' => '0' }
+    [
+      original.merge('widget[enabled]' => 'false'),
+      original.merge('widget[enabled]' => '1'),
+      original.merge('widget[count]' => '1'),
+      original.merge('widget[name]' => 'null'),
+      *original.keys.map { |key| original.reject { |name, _value| name == key } },
+      original.merge('widget[unused]' => '')
+    ].each { |query| reject_query(URI.encode_www_form(query)) }
+  end
+
+  def self.verify_query(raw_query)
+    request = WEBrick::HTTPRequest.new(WEBrick::Config::HTTP)
+    request.parse(StringIO.new("GET /mounted/v7/query?#{raw_query} HTTP/1.1\r\nHost: fixture.invalid\r\n\r\n"))
+    response = WEBrick::HTTPResponse.new(WEBrick::Config::HTTP)
+    runner = GoDocumentationAcceptance.allocate
+    runner.instance_variable_set(:@requests, Queue.new)
+    runner.send(:serve, request, response)
+    runner.send(:verify, :query, GoDocumentationAcceptance.expected_cases.fetch(:query), '')
+  end
+
+  def self.reject_query(raw_query)
+    verify_query(raw_query)
+    raise 'query: verifier accepted an unexpected query'
+  rescue RuntimeError => e
+    raise unless e.message.start_with?('query: query values were not preserved: expected ') &&
+                 e.message.include?('got ') && e.message.include?("raw query #{raw_query.inspect}")
+  end
+
+  def self.verify(name, body)
+    expected = GoDocumentationAcceptance.expected_cases.fetch(name)
+    runner = GoDocumentationAcceptance.allocate
+    requests = Queue.new
+    path = %i[empty omitted].include?(name) ? "/mounted/v7/#{name}" : '/mounted/v7/clients/42/children/a/b'
+    requests << { path:, body: JSON.generate(body), auth: expected.fetch(:auth, {}) }
+    runner.instance_variable_set(:@requests, requests)
+    runner.send(:verify, name, expected, expected.fetch(:output, ''))
+  end
+
+  def self.reject_change(name, original = OBJECT_BODY)
+    body = Marshal.load(Marshal.dump(original))
+    yield(body)
+    verify(name, body)
+    raise "#{name}: verifier accepted an unexpected body"
+  rescue RuntimeError => e
+    raise unless e.message.start_with?("#{name}: supplied input or omission was not preserved:")
+  end
+end
+
+GoDocumentationWireCheck.run! if $0 == __FILE__

data/spec/support/documentation_fixture.rb

@@ -0,0 +1,70 @@
+# Saved SDK schema fixture. Generated Go source is always produced by Generator.
+module GoDocumentationFixture
+  def self.io(parameters, layout: 'hash', namespace: 'widget')
+    { layout:, namespace:, parameters: }
+  end
+
+  def self.action(path: '/mounted/v7/widgets', method: 'POST', input: nil, output: nil, aliases: [], blocking: false, meta: {})
+    { path:, method:, input:, output:, aliases:, blocking:, meta: }
+  end
+
+  def self.token
+    output = io({ complete: { type: 'Boolean' }, token: { type: 'String' }, next_action: { type: 'String' } }, namespace: 'token')
+    {
+      http_header: 'X-Token', query_parameter: 'token',
+      resources: {
+        token: {
+          resources: {},
+          actions: {
+            request: action(path: '/mounted/v7/tokens', input: io({ user: { type: 'String' }, password: { type: 'String' },
+                                                                    lifetime: { type: 'String' }, interval: { type: 'Integer' } }), output:),
+            challenge: action(path: '/mounted/v7/tokens/challenge', input: io({ token: { type: 'String' }, code: { type: 'String' } }), output:),
+            revoke: action(path: '/mounted/v7/tokens/revoke')
+          }
+        }
+      }
+    }
+  end
+
+  def self.description
+    state = {
+      resources: {},
+      actions: {
+        show: action(path: '/mounted/v7/action_states/{action_state_id}', method: 'GET',
+                     output: io({ id: { type: 'Integer' } }, namespace: 'action_state')),
+        poll: action(path: '/mounted/v7/action_states/{action_state_id}/poll', method: 'GET',
+                     input: io({ timeout: { type: 'Float' }, update_in: { type: 'Float' },
+                                 status: { type: 'String' }, current: { type: 'Integer' }, total: { type: 'Integer' } }),
+                     output: io({ finished: { type: 'Boolean' }, status: { type: 'String' },
+                                  current: { type: 'Integer' }, total: { type: 'Integer' } }, namespace: 'action_state')),
+        cancel: action(path: '/mounted/v7/action_states/{action_state_id}/cancel', method: 'POST')
+      }
+    }
+    run = action(
+      path: '/mounted/v7/clients/{client_id}/children/{child_id}', aliases: ['perform'],
+      input: io({ name: { type: 'String', nullable: true }, enabled: { type: 'Boolean' },
+                  count: { type: 'Integer' }, unused: { type: 'String' } }),
+      output: io({ id: { type: 'Integer' }, name: { type: 'String', nullable: true } }),
+      meta: { global: { input: io({ includes: { type: 'Custom' } }, namespace: false) } }
+    )
+    {
+      authentication: { basic: {}, token: token, oauth2: { http_header: 'X-OAuth', revoke_url: '/revoke' } },
+      meta: { namespace: '_meta' },
+      resources: {
+        action_state: state,
+        owner: { resources: {}, actions: {
+          show: action(path: '/mounted/v7/owners/{owner_id}', method: 'GET',
+                       output: io({ id: { type: 'Integer' }, label: { type: 'String' } }, namespace: 'owner'))
+        } },
+        client: { resources: { child: { resources: {}, actions: { client: run } } }, actions: {} },
+        authentication: { resources: {}, actions: {} },
+        hidden: { resources: {}, actions: { secret: action } }
+      }
+    }
+  end
+
+  def self.sample
+    { path_params: [42, 'a/b'], request: { name: nil, enabled: false, count: 0 },
+      response: { id: 1 }, status: true }
+  end
+end

data/spec/support/test_server.rb

@@ -20,7 +20,7 @@ class ClientTestServer
   def start
     return if @wait_thr
 
-    env = { 'BUNDLE_GEMFILE' => @gemfile }
+    env = { 'BUNDLE_GEMFILE' => @gemfile, 'BUNDLE_LOCKFILE' => "#{@gemfile}.lock" }
     cmd = ['bundle', 'exec', 'ruby', @server_script, '--port', '0']
     @stdin, @stdout, @wait_thr = Open3.popen2e(env, *cmd, chdir: @cwd)