haveapi-go-client 0.30.2 → 0.31.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6d7b665ff9866f57fd844908a8ee6d8ce83bf784578949ade2a057e465f50a0c
-  data.tar.gz: 549ecd828535d2a740758805ba7e04494e963a1e67acdf7c76a05eaaa2dcb6eb
+  metadata.gz: 0d4316e27400e3f4ef8ea4be0a7ea2cce84e55eb6c8db05b0ac42d0f2ca1631f
+  data.tar.gz: 5c010035b496b01576000055f63af17770f24255ca2bfa67364f1cb2e854eb78
 SHA512:
-  metadata.gz: ae6a2f23d846e821d03ab0b9aa6c9cd64680d35db0c4996df2a1cbeea432a499cee1f6be57e86700282a297a73d82863e811e02d9216bfbbba0d868b2750255a
-  data.tar.gz: 39db10f2394870b215d28ad44a142318694d5ff295810c38e4407dda43677f73907e90c969dfb08228ba698096cc7cd9a3aa624a5b7839b8fe69db239224ce4e
+  metadata.gz: 445d8c7cf7d9e5271d81c6d05a39502c7b50c38668bb974657b1b7a8710540212cb5780cb0483ba1a6b7be2b364007f0b4d7bb92ee73983e42542e167dda5bf0
+  data.tar.gz: 918c4cba48ad68f3c3cb79c298fcff7520384499757714036d737e116f42f451f8c77befd0178c0924ef47b83ee13fac6ff8017f1a23450dc5381c9baeac70bf

data/README.md

@@ -1,85 +1,132 @@
-HaveAPI Client Generator For Go
--------------------------------
-HaveAPI-Go-Client generates a client library for accessing selected APIs built
-with the [HaveAPI framework](https://github.com/vpsfreecz/haveapi).
+# Go client generator
 
-## Installation
+Generate a Go client for one API version from a saved [HaveAPI](https://github.com/vpsfreecz/haveapi)
+protocol 2 description. Capture the schema once, review it, then generate offline.
+The resulting client has fixed resource names and routes; it does not discover
+API changes at runtime.
 
-    $ gem install 'haveapi-go-client'
+## Prepare the source tools
 
-## CLI
-The generator is run against an API server that the resulting client should be
-able to work with. The generated client uses one selected API version. When
-the API server changes, the client has to be regenerated.
+From the HaveAPI checkout root, enter its Nix environment and prepare the Go
+component's Ruby dependencies:
 
+```sh
+nix develop
+BUNDLE_GEMFILE="$PWD/clients/go/Gemfile" bundle install
 ```
-$ haveapi-go-client -h
-Usage: haveapi-go-client [options] <api url> <destination>
-        --version VERSION            Use specified API version
-        --module MODULE              Name of the generated Go module
-        --package PKG                Name of the generated Go package
-```
 
-For example:
+Keep that checkout and resolved component lock with your generation inputs.
+The component bundle uses the Ruby client from the same checkout. Go must also
+be on `PATH` for `go fmt`.
+
+## Fetch, save and generate
+
+The examples assume an API at `https://example.test/v1.0/` with a `Widget#Show`
+action at `/v1.0/widgets/{widget_id}` and a string `name` output. Replace the
+example URL, version and resource names with those of your API.
+
+From the HaveAPI root:
 
+```sh
+mkdir -p /path/to/widget-client/schema
+BUNDLE_GEMFILE="$PWD/clients/go/Gemfile" bundle exec ruby \
+  clients/go/bin/haveapi-go-client fetch https://example.test/v1.0/ \
+  --api-version 1.0 --profile public \
+  --output /path/to/widget-client/schema/api.json
+BUNDLE_GEMFILE="$PWD/clients/go/Gemfile" bundle exec ruby \
+  clients/go/bin/haveapi-go-client generate \
+  --schema /path/to/widget-client/schema/api.json --api-version 1.0 \
+  --output /path/to/widget-client --module example.test/widget-client --package client
 ```
-$ haveapi-go-client https://api.vpsfree.cz ~/go/src/foo/client
+
+The output directory for the saved schema must already exist. Fetch sends OPTIONS
+at the exact version URL, including any mount prefix; it never selects a server
+default. Generation reads the saved schema, uses the existing Go emitter and
+runs `go fmt`. It does not contact the API or install dependencies. The generated
+module contains the `client` package; keep handwritten application files elsewhere.
+
+Public capture is the default. For Basic authentication, set `WIDGET_PASSWORD`
+in your environment, then run:
+
+```sh
+BUNDLE_GEMFILE="$PWD/clients/go/Gemfile" bundle exec ruby \
+  clients/go/bin/haveapi-go-client fetch https://example.test/v1.0/ \
+  --api-version 1.0 --profile basic-user --basic-user demo \
+  --basic-password-env WIDGET_PASSWORD \
+  --output /path/to/widget-client/schema/api.json
 ```
 
-## Usage
-The generated library can then be imported in your projects. For example,
-in a project with the following `go.mod`:
+For an existing HaveAPI token, set `WIDGET_TOKEN` and use:
 
+```sh
+BUNDLE_GEMFILE="$PWD/clients/go/Gemfile" bundle exec ruby \
+  clients/go/bin/haveapi-go-client fetch https://example.test/v1.0/ \
+  --api-version 1.0 --profile token-user --token-env WIDGET_TOKEN \
+  --output /path/to/widget-client/schema/api.json
 ```
-module foo
-```
 
-The client could be imported and used as:
+The two authentication choices are mutually exclusive. Token capture first reads
+anonymous discovery at the same version URL, then uses the advertised token
+header. Supply a token you have already acquired. `--profile` labels the capture;
+it does not change authentication. A snapshot covers the resources visible during
+capture, which depend on permissions and enabled plugins.
+Review saved defaults and data before sharing the schema. Credentials and tokens
+must stay out of snapshots. Failed capture preserves an existing output file.
+
+## Use the generated client
+
+In a separate application, use the generated module locally:
+
+```sh
+go mod init example.test/widget-app
+go mod edit -require=example.test/widget-client@v0.0.0
+go mod edit -replace=example.test/widget-client=/path/to/widget-client
+```
 
 ```go
 package main
 
 import (
-	"fmt"
-	"foo/client"
+    "fmt"
+    "log"
+    "example.test/widget-client/client"
 )
 
 func main() {
-	api := client.New("https://api.vpsfree.cz")
-	api.SetLanguage("cs")
-	api.SetBasicAuthentication("admin", "secret")
-
-	action := api.Cluster.PublicStats.Prepare()
-	resp, err := action.Call()
-
-	if err != nil {
-		fmt.Println(err)
-		return
-	}
-
-	fmt.Printf("%+v\n", resp)
-	fmt.Printf("%+v\n", resp.Response)
-	fmt.Printf("%+v\n", resp.Response.Cluster)
-	fmt.Printf("%+v\n", resp.Output)
+    api := client.New("https://example.test")
+    action := api.Widget.Show.Prepare().SetPathParamInt("widget_id", 1)
+    resp, err := action.Call()
+    if err != nil {
+        log.Fatal(err)
+    }
+    if !resp.Status {
+        log.Fatal(resp.Message)
+    }
+    if resp.Output != nil {
+        fmt.Println(resp.Output.Name)
+    }
 }
 ```
 
-## Localization
+Give `client.New` only the API origin, such as `https://example.test`, without
+a trailing slash. Generated action paths already contain the mount prefix and
+API version. Authentication helpers
+are emitted for advertised providers; a matching schema can use
+`SetBasicAuthentication(user, password)` or `SetExistingTokenAuth(token)`.
+Permissions and server validation still apply. `resp` retains the response
+envelope; `resp.Output` provides the action output directly.
 
-Generated clients include bundled HaveAPI client translations. Set the
-language before making requests:
-
-```go
-api := client.New("https://api.vpsfree.cz")
-api.SetLanguage("cs")
-```
+Set `api.SetLanguage("cs")` to send `Accept-Language`.
+`SetLanguageHeader("X-Language")` selects a custom header; `GetLanguage()` and
+`GetLanguageHeader()` return the configured values.
 
-The value is sent in `Accept-Language` by default. Use
-`SetLanguageHeader("X-Language")` when the API is configured with a custom
-language header. Read the configured values with `GetLanguage()` and
-`GetLanguageHeader()`.
+## Legacy invocation
 
-## API documentation examples
+The positional `haveapi-go-client [options] URL DESTINATION` command remains
+available. Its optional `--version` still defaults to the server's default
+version; `--basic-user` and raw `--basic-password` retain their old meaning.
+Use the saved-schema workflow above for explicit, repeatable generation and
+secrets supplied through environment variables.
 
-The Ruby server can render examples against a configured generated Go SDK.
-See [profile configuration, supported samples and verification](docs/documentation.md).
+The Ruby server can render examples for configured generated clients; see
+[documentation profiles](docs/documentation.md).

data/bin/haveapi-go-client

@@ -1,3 +1,3 @@
 #!/usr/bin/env ruby
 require 'haveapi/go_client/cli'
-HaveAPI::GoClient::Cli.run
+exit HaveAPI::GoClient::Cli.run

data/haveapi-go-client.gemspec

@@ -18,5 +18,5 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  spec.add_dependency 'haveapi-client', '~> 0.30.2'
+  spec.add_dependency 'haveapi-client', '~> 0.31.0'
 end

data/lib/haveapi/go_client/cli.rb

@@ -1,48 +1,90 @@
-require 'haveapi/go_client'
 require 'optparse'
 
-module HaveAPI::GoClient
-  class Cli
-    def self.run
-      options = {
-        package: 'client'
-      }
+module HaveAPI
+  module GoClient
+    class Cli
+      def self.run(argv = ARGV, out: $stdout, err: $stderr)
+        argv = argv.dup
+        if %w[fetch generate].include?(argv.first)
+          require_shared_schema
+          return HaveAPI::Schema::FetchCommand.run(argv.drop(1), out:, err:, command_name: 'haveapi-go-client') if argv.first == 'fetch'
 
-      parser = OptionParser.new do |opts|
-        opts.banner = "Usage: #{$0} [options] <api url> <destination>"
-
-        opts.on('--version VERSION', 'Use specified API version') do |v|
-          options[:version] = v
+          generate_saved(argv.drop(1), out:)
+        else
+          legacy(argv, out:)
         end
+        0
+      rescue OptionParser::ParseError, SystemCallError, ArgumentError => e
+        err.puts("haveapi-go-client: #{e.message}")
+        1
+      rescue StandardError => e
+        raise unless defined?(HaveAPI::Schema::Error) && e.is_a?(HaveAPI::Schema::Error)
 
-        opts.on('--module MODULE', 'Name of the generated Go module') do |v|
-          options[:module] = v
-        end
+        err.puts("haveapi-go-client: #{e.message}")
+        1
+      end
 
-        opts.on('--package PKG', 'Name of the generated Go package') do |v|
-          options[:package] = v
-        end
+      def self.require_shared_schema
+        require 'haveapi/schema'
+        return if defined?(HaveAPI::Schema::Snapshot) && defined?(HaveAPI::Schema::FetchCommand)
 
-        opts.on('--basic-user USER', 'Basic auth username for API description') do |v|
-          options[:basic_user] = v
-        end
+        raise ArgumentError, 'loaded haveapi-client does not provide the required shared schema API'
+      rescue LoadError
+        raise ArgumentError, 'shared haveapi-client schema API is unavailable; prepare the component bundle from this source release'
+      end
 
-        opts.on('--basic-password PASSWORD', 'Basic auth password for API description') do |v|
-          options[:basic_password] = v
+      def self.generate_saved(argv, out:)
+        options = { package: 'client' }
+        parser = OptionParser.new do |opts|
+          opts.banner = 'Usage: haveapi-go-client generate --schema FILE --api-version VERSION --output DIR [--module MODULE] [--package NAME]'
+          opts.on('--schema FILE') { |value| options[:schema] = value }
+          opts.on('--api-version VERSION') { |value| options[:version] = value }
+          opts.on('--output DIR') { |value| options[:output] = value }
+          opts.on('--module MODULE') { |value| options[:module] = value }
+          opts.on('--package NAME') { |value| options[:package] = value }
+          opts.on('-h', '--help') do
+            out.puts(opts)
+            return 0
+          end
         end
-      end
+        parser.parse!(argv)
+        raise ArgumentError, 'generate requires --schema, --output and no positional arguments' unless argv.empty? && options[:schema] && options[:output]
 
-      parser.parse!
+        HaveAPI::Schema::Snapshot.version!(options[:version])
+        snapshot = HaveAPI::Schema::Snapshot.load(options[:schema])
+        raise ArgumentError, 'requested API version differs from snapshot' unless snapshot.fetch('api_version') == options[:version]
 
-      if ARGV.length != 2
-        warn 'Invalid arguments'
-        puts @global_opt.help
-        exit(false)
+        require 'haveapi/go_client'
+        # The existing generator consumes the symbol-key JSON representation used
+        # by the dynamic Ruby communicator, including nested validator/Custom keys.
+        description = JSON.parse(JSON.generate(snapshot.fetch('description')), symbolize_names: true)
+        generator = Generator.from_description(description, options[:output], options)
+        generator.generate
+        generator.go_fmt
       end
 
-      g = Generator.new(ARGV[0], ARGV[1], options)
-      g.generate
-      g.go_fmt
+      def self.legacy(argv, out:)
+        options = { package: 'client' }
+        parser = OptionParser.new do |opts|
+          opts.banner = 'Usage: haveapi-go-client [options] <api url> <destination>'
+          opts.on('--version VERSION', 'Use specified API version (otherwise server default)') { |value| options[:version] = value }
+          opts.on('--module MODULE') { |value| options[:module] = value }
+          opts.on('--package PKG') { |value| options[:package] = value }
+          opts.on('--basic-user USER') { |value| options[:basic_user] = value }
+          opts.on('--basic-password PASSWORD') { |value| options[:basic_password] = value }
+          opts.on('-h', '--help') do
+            out.puts(opts)
+            return 0
+          end
+        end
+        parser.parse!(argv)
+        raise ArgumentError, 'legacy mode requires an API URL and destination' unless argv.length == 2
+
+        require 'haveapi/go_client'
+        generator = Generator.new(argv[0], argv[1], options)
+        generator.generate
+        generator.go_fmt
+      end
     end
   end
 end

data/lib/haveapi/go_client/version.rb

@@ -1,5 +1,5 @@
 module HaveAPI
   module GoClient
-    VERSION = '0.30.2'.freeze
+    VERSION = '0.31.0'.freeze
   end
 end

data/spec/spec_helper.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'bundler/setup'
+$:.unshift(File.expand_path('../../ruby/lib', __dir__))
 require 'open3'
 require 'tmpdir'
 require 'haveapi/go_client'

data/spec/unit/cli_spec.rb

@@ -0,0 +1,83 @@
+# Deliberately avoid the component spec_helper: offline CLI checks need no server.
+require 'stringio'
+require 'tmpdir'
+require 'haveapi/schema'
+require 'haveapi/go_client/cli'
+
+RSpec.describe HaveAPI::GoClient::Cli do
+  let(:err) { StringIO.new }
+  let(:generator) { double(generate: true, go_fmt: true) }
+  let(:generator_class) { Class.new }
+  let(:snapshot) do
+    HaveAPI::Schema::Snapshot.from_description(
+      api_version: '1.0', protocol_version: '2.0', source_url: 'https://example.test/v1.0/', profile: 'fixture',
+      description: {
+        'help' => '/v1.0/', 'meta' => { 'namespace' => '_meta' }, 'authentication' => {},
+        'resources' => { 'widget' => { 'actions' => { 'show' => {
+          'path' => '/v1.0/widgets/{widget_id}', 'method' => 'GET', 'aliases' => [], 'auth' => false,
+          'input' => { 'parameters' => {}, 'namespace' => 'widget', 'layout' => 'object' },
+          'output' => { 'parameters' => { 'name' => { 'type' => 'String' } }, 'namespace' => 'widget', 'layout' => 'object' },
+          'meta' => { 'global' => nil, 'object' => nil }
+        } }, 'resources' => {} } }
+      }
+    )
+  end
+
+  before do
+    stub_const('HaveAPI::GoClient::Generator', generator_class)
+    allow(described_class).to receive(:require).with('haveapi/schema').and_call_original
+    allow(described_class).to receive(:require).with('haveapi/go_client').and_return(true)
+    allow(generator_class).to receive_messages(new: generator, from_description: generator)
+  end
+
+  it 'delegates fetch options and status unchanged' do
+    args = ['https://example.test/v1.0/', '--api-version', '1.0', '--profile', 'public', '--output', 'schema.json']
+    out = StringIO.new
+    allow(HaveAPI::Schema::FetchCommand).to receive(:run).and_return(1)
+    expect(described_class.run(['fetch', *args], out:, err:)).to eq(1)
+    expect(HaveAPI::Schema::FetchCommand).to have_received(:run).with(args, out:, err:, command_name: 'haveapi-go-client')
+  end
+
+  it 'rejects missing and mismatched versions before generation or output mutation' do
+    Dir.mktmpdir do |root|
+      path = File.join(root, 'schema.json')
+      File.write(path, HaveAPI::Schema::Snapshot.canonical(snapshot))
+      args = ['generate', '--schema', path, '--output', File.join(root, 'out')]
+      expect(described_class.run(args, err:)).to eq(1)
+      expect(err.string).to include('explicit numeric API version')
+      expect(described_class.run(args + ['--api-version', '2.0'], err:)).to eq(1)
+      expect(err.string).to include('differs from snapshot')
+      expect(generator_class).not_to have_received(:from_description)
+      expect(Dir.children(root)).to eq(['schema.json'])
+    end
+  end
+
+  it 'passes recursively symbolized saved description to the existing generator then formats' do
+    Dir.mktmpdir do |root|
+      path = File.join(root, 'schema.json')
+      output = File.join(root, 'out')
+      File.write(path, HaveAPI::Schema::Snapshot.canonical(snapshot))
+      args = ['generate', '--schema', path, '--api-version', '1.0', '--output', output, '--module', 'example.test/widget', '--package', 'widgets']
+      expected = JSON.parse(JSON.generate(snapshot.fetch('description')), symbolize_names: true)
+      expect(described_class.run(args, err:)).to eq(0)
+      expect(generator_class).to have_received(:from_description).with(expected, output, hash_including(version: '1.0', module: 'example.test/widget', package: 'widgets'))
+      expect(generator).to have_received(:generate)
+      expect(generator).to have_received(:go_fmt)
+      expect(args.first).to eq('generate')
+    end
+  end
+
+  it 'retains positional legacy default-version and raw Basic options' do
+    expect(described_class.run(['--basic-user', 'demo', '--basic-password', 'test-only', 'https://example.test/', 'out'], err:)).to eq(0)
+    expect(generator_class).to have_received(:new).with('https://example.test/', 'out', { package: 'client', basic_user: 'demo', basic_password: 'test-only' })
+    expect(generator).to have_received(:generate)
+    expect(generator).to have_received(:go_fmt)
+  end
+
+  it 'retains the explicit legacy version and rejects raw password in saved mode' do
+    expect(described_class.run(['--version', '1.0', 'https://example.test/', 'out'], err:)).to eq(0)
+    expect(generator_class).to have_received(:new).with('https://example.test/', 'out', { package: 'client', version: '1.0' })
+    expect(described_class.run(['generate', '--basic-password', 'test-only'], err:)).to eq(1)
+    expect(err.string).to include('invalid option')
+  end
+end

data/spec/unit/generation_spec.rb

@@ -0,0 +1,51 @@
+# Exercise the real emitter offline without the component's live-server helper.
+require 'tmpdir'
+require 'stringio'
+require 'haveapi/schema'
+require 'haveapi/go_client'
+
+RSpec.describe HaveAPI::GoClient::Generator do
+  it 'matches existing from_description bytes, formats Go and never describes a live API' do
+    description = {
+      'help' => '/v1.0/', 'meta' => { 'namespace' => '_meta' }, 'authentication' => {},
+      'resources' => { 'widget' => { 'actions' => { 'show' => {
+        'path' => '/v1.0/widgets/{widget_id}', 'method' => 'GET', 'aliases' => [], 'auth' => false,
+        'input' => { 'parameters' => {}, 'namespace' => 'widget', 'layout' => 'object' },
+        'output' => { 'parameters' => { 'name' => { 'type' => 'String' } }, 'namespace' => 'widget', 'layout' => 'object' },
+        'meta' => { 'global' => nil, 'object' => nil }
+      } }, 'resources' => {} } }
+    }
+    schema = HaveAPI::Schema::Snapshot.from_description(
+      description:, api_version: '1.0', protocol_version: '2.0', source_url: 'https://example.test/v1.0/', profile: 'fixture'
+    )
+    allow(HaveAPI::Client::Communicator).to receive(:new).and_raise('offline generation attempted discovery')
+    Dir.mktmpdir('haveapi-go-saved-') do |root|
+      path = File.join(root, 'schema.json')
+      File.write(path, HaveAPI::Schema::Snapshot.canonical(schema))
+      cli_output = File.join(root, 'cli')
+      direct_output = File.join(root, 'direct')
+      err = StringIO.new
+      status = HaveAPI::GoClient::Cli.run([
+                                            'generate', '--schema', path, '--api-version', '1.0', '--output', cli_output,
+                                            '--module', 'example.test/widget-client', '--package', 'client'
+                                          ], err:)
+      expect(status).to eq(0), err.string
+      direct = described_class.from_description(
+        JSON.parse(JSON.generate(description), symbolize_names: true), direct_output,
+        module: 'example.test/widget-client', package: 'client'
+      )
+      direct.generate
+      direct.go_fmt
+      expect(file_bytes(cli_output)).to eq(file_bytes(direct_output))
+      sources = file_bytes(cli_output).values.join
+      expect(sources).to include('Widget *ResourceWidget', 'Show *ActionWidgetShow', 'func (inv *ActionWidgetShowInvocation) SetPathParamInt', 'Name string')
+      expect(HaveAPI::Client::Communicator).not_to have_received(:new)
+    end
+  end
+
+  def file_bytes(root)
+    Dir.glob('**/*', base: root).select { |path| File.file?(File.join(root, path)) }.to_h do |path|
+      [path, File.binread(File.join(root, path))]
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: haveapi-go-client
 version: !ruby/object:Gem::Version
-  version: 0.30.2
+  version: 0.31.0
 platform: ruby
 authors:
 - Jakub Skokan
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.30.2
+        version: 0.31.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.30.2
+        version: 0.31.0
 description: Go client generator
 email:
 - jakub.skokan@vpsfree.cz
@@ -73,7 +73,9 @@ files:
 - spec/support/documentation_fixture.rb
 - spec/support/documentation_profile_fixture.rb
 - spec/support/test_server.rb
+- spec/unit/cli_spec.rb
 - spec/unit/documentation_spec.rb
+- spec/unit/generation_spec.rb
 - template/action.go.erb
 - template/authentication.go.erb
 - template/authentication/basic.go.erb