feat(client): generate the Go types and typed clients from the OpenAPI spec

.golangci.yml

@@ -100,6 +100,11 @@ linters:
         linters:
           - forbidigo
         text: one HTTP client
+      # The generator downloads the API docs in a go:generate run, where no front end exists.
+      - path: client/openapi/generator/main\.go
+        linters:
+          - forbidigo
+        text: user agent of the front end
       # The fake clock is a test's; production code waits on the real one.
       - path-except: _test\.go
         linters:

client/client.go

@@ -3,7 +3,10 @@ package client
 import (
 	"context"
 
-	"github.com/meshcloud/meshstack-cli/client/internal"
+	"github.com/meshcloud/meshstack-cli/client/meshapi"
+	"github.com/meshcloud/meshstack-cli/client/meshbuildingblock/v2"
+	"github.com/meshcloud/meshstack-cli/client/meshbuildingblockrun/v1"
+	"github.com/meshcloud/meshstack-cli/client/meshworkspace/v2"
 	"github.com/meshcloud/meshstack-cli/client/types/xurl"
 	"github.com/meshcloud/meshstack-cli/internal/http"
 	"github.com/meshcloud/meshstack-cli/internal/version"
@@ -46,12 +49,19 @@ type Client struct {
 	WorkspaceUserBinding           MeshWorkspaceUserBindingClient
 	Raw                            *RawClient
 
+	// The generated clients, one per kind in one API version.
+	MeshWorkspace        meshworkspace.Client
+	MeshBuildingBlock    meshbuildingblock.Client
+	MeshBuildingBlockRun meshbuildingblockrun.Client
+	// HttpClient is what the NewClient of a package that another module generates takes.
+	HttpClient meshapi.HttpClient
+
 	// Endpoint is read by the Terraform provider's meshstack_instance data source.
 	Endpoint xurl.URL
 }
 
 func New(ctx context.Context, endpoint xurl.URL, client http.Client, auth Authorization) Client {
-	authorizedClient := internal.HttpClient{
+	authorizedClient := meshapi.HttpClient{
 		AuthorizedClient: client.WithAuthorization(auth),
 		EndpointUrl:      endpoint,
 	}
@@ -60,6 +70,9 @@ func New(ctx context.Context, endpoint xurl.URL, client http.Client, auth Author
 	buildingBlockDefinitionVersion := newBuildingBlockDefinitionVersionClient(ctx, authorizedClient)
 	buildingBlockRun := newBuildingBlockRunClient(ctx, authorizedClient)
 	workspace := newWorkspaceClient(ctx, authorizedClient)
+	generatedWorkspace := meshworkspace.NewClient(authorizedClient)
+	generatedBuildingBlock := meshbuildingblock.NewClient(authorizedClient)
+	generatedBuildingBlockRun := meshbuildingblockrun.NewClient(authorizedClient)
 	return Client{
 		ApiKey:                         newApiKeyClient(ctx, authorizedClient),
 		BuildingBlock:                  newBuildingBlockClient(ctx, authorizedClient),
@@ -91,7 +104,14 @@ func New(ctx context.Context, endpoint xurl.URL, client http.Client, auth Author
 			with(buildingBlockRun.meshObject).
 			with(buildingBlockDefinition.meshObject).
 			withOwnOrder(buildingBlockDefinitionVersion.meshObject).
-			with(newEventLogMeshObject(ctx, authorizedClient)),
+			with(newEventLogMeshObject(ctx, authorizedClient)).
+			withApi[meshworkspace.Response](generatedWorkspace.Api()).
+			withApi[meshbuildingblock.Response](generatedBuildingBlock.Api()).
+			withApi[meshbuildingblockrun.Response](generatedBuildingBlockRun.Api()),
+		MeshWorkspace:        generatedWorkspace,
+		MeshBuildingBlock:    generatedBuildingBlock,
+		MeshBuildingBlockRun: generatedBuildingBlockRun,
+		HttpClient:           authorizedClient,
 
 		Endpoint: endpoint,
 	}

client/generate.go

@@ -0,0 +1,3 @@
+package client
+
+//go:generate go run ./internal/generate

client/internal/generate/main.go

@@ -0,0 +1,33 @@
+// Command generate writes the packages of the meshObject kinds below client/.
+package main
+
+import (
+	"github.com/meshcloud/meshstack-cli/client/openapi"
+	"github.com/meshcloud/meshstack-cli/client/openapi/generator"
+)
+
+func main() {
+	generator.Main(generator.Config{
+		Module: "github.com/meshcloud/meshstack-cli/client",
+		Shared: "meshobject",
+		Packages: []generator.Package{
+			{Kind: "meshWorkspace", ApiVersion: "v2", Actions: []string{"list", "show", "create", "update", "delete"}},
+			{Kind: "meshBuildingBlock", ApiVersion: "v2-preview", Actions: []string{"list", "show", "create", "update", "delete", "purge", "trigger-run"}},
+			{Kind: "meshBuildingBlockRun", ApiVersion: "v1", Actions: []string{"list", "show", "logs"}},
+		},
+		MapType: mapType,
+	})
+}
+
+const typesImport = "github.com/meshcloud/meshstack-cli/client/types"
+
+func mapType(at generator.Location, _ *openapi.Schema) (generator.GoType, bool) {
+	switch at {
+	case generator.Location{Schema: "MeshBuildingBlockInput", Property: "value"}:
+		return generator.GoType{Expr: "types.SecretOrAny", Import: typesImport, Container: true}, true
+	case generator.Location{Schema: "MeshBuildingBlockOutput", Property: "value"},
+		generator.Location{Schema: "MeshBuildingBlockRun.MeshBuildingBlockRunSpec.MeshBuildingBlockInputsForRun", Property: "value"}:
+		return generator.GoType{Expr: "any", Container: true}, true
+	}
+	return generator.GoType{}, false
+}

client/internal/mesh_object.go

@@ -13,15 +13,11 @@ import (
 	"strings"
 	"unicode"
 
-	"github.com/meshcloud/meshstack-cli/client/types/xurl"
+	"github.com/meshcloud/meshstack-cli/client/meshapi"
 	"github.com/meshcloud/meshstack-cli/internal/http"
 )
 
-type HttpClient struct {
-	http.AuthorizedClient
-
-	EndpointUrl xurl.URL
-}
+type HttpClient = meshapi.HttpClient
 
 // MeshObjectApi is the API of one meshObject kind, in one version, with no Go type for its objects:
 // the requests and the paging they share, for a caller that decodes the answers itself.

client/meshapi/api.go

@@ -0,0 +1,173 @@
+// Package meshapi sends the requests of the clients that client/openapi/generator writes. It is
+// public so that another module can generate clients of its own.
+package meshapi
+
+import (
+	"context"
+	"encoding/json/jsontext"
+	"encoding/json/v2"
+	"errors"
+	"fmt"
+	"iter"
+	"net/url"
+	"reflect"
+	"strings"
+
+	"github.com/meshcloud/meshstack-cli/client/openapi"
+	"github.com/meshcloud/meshstack-cli/client/types/xurl"
+	"github.com/meshcloud/meshstack-cli/internal/http"
+	internaljson "github.com/meshcloud/meshstack-cli/internal/json"
+)
+
+// HttpClient sends requests to one meshStack, authorized.
+type HttpClient struct {
+	http.AuthorizedClient
+
+	EndpointUrl xurl.URL
+}
+
+// Api is one version of a meshObject kind as the generated clients call it.
+type Api struct {
+	HttpClient
+
+	Kind       string
+	ApiVersion string
+	MediaType  string
+	// Path is that of the kind's collection, such as /api/meshobjects/meshworkspaces.
+	Path string
+	// EmbeddedRel names the objects in a page of the listing.
+	EmbeddedRel string
+}
+
+// Call is one request of a generated client.
+type Call struct {
+	Method string
+	Path   string
+	Query  any
+	// SendsMeshObject and AnswersMeshObject mark a body and an answer that carry the kind and
+	// apiVersion, which the generated types leave out.
+	SendsMeshObject   bool
+	AnswersMeshObject bool
+}
+
+// Path fills the parameters of the template in their order.
+func Path(template string, values ...string) string {
+	var path strings.Builder
+	rest := template
+	for _, value := range values {
+		before, after, ok := strings.Cut(rest, "{")
+		_, after, closed := strings.Cut(after, "}")
+		if !ok || !closed {
+			panic(fmt.Sprintf("%s has fewer parameters than %d", template, len(values)))
+		}
+		path.WriteString(before + url.PathEscape(value))
+		rest = after
+	}
+	return path.String() + rest
+}
+
+// Do answers a zero R for an empty answer, which only an R of type any expects.
+func (a Api) Do[R any](ctx context.Context, call Call, body any, options ...http.RequestOption) (R, error) {
+	var result R
+	options = append(options, http.WithAccept(a.MediaType))
+	if call.Query != nil {
+		options = append(options, http.WithUrlQuery(call.Query))
+	}
+	if call.Method == http.MethodPut || call.Method == http.MethodDelete {
+		options = append(options, http.Retryable())
+	}
+	if body != nil {
+		payload, err := a.payload(body, call.SendsMeshObject)
+		if err != nil {
+			return result, err
+		}
+		options = append(options, http.WithJsonPayload(payload, a.MediaType))
+	}
+	answer, err := a.DoRequest[[]byte](ctx, call.Method, a.EndpointUrl.JoinPath(call.Path), options...)
+	if err != nil {
+		return result, err
+	}
+	if len(answer) == 0 {
+		if t := reflect.TypeFor[R](); t.Kind() == reflect.Interface && t.NumMethod() == 0 {
+			return result, nil
+		}
+		return result, fmt.Errorf("unexpected empty response body from %s %s", call.Method, call.Path)
+	}
+	return result, a.decode(answer, call.AnswersMeshObject, &result)
+}
+
+type page struct {
+	Embedded map[string][]jsontext.Value `json:"_embedded"`
+	Page     struct {
+		TotalElements int `json:"totalElements"`
+		TotalPages    int `json:"totalPages"`
+		Number        int `json:"number"`
+	} `json:"page"`
+}
+
+// List pages through the objects that call lists.
+func (a Api) List[T any](ctx context.Context, call Call) iter.Seq2[T, error] {
+	return func(yield func(T, error) bool) {
+		var noItem T
+		for pageNumber := 0; ; pageNumber++ {
+			response, err := a.Do[page](ctx, Call{Method: call.Method, Path: call.Path, Query: call.Query}, nil,
+				http.WithUrlQuery(map[string]any{"page": pageNumber}))
+			if err != nil && pageNumber > 0 {
+				err = fmt.Errorf("cannot read page %d of the list: %w", pageNumber, err)
+			}
+			if err != nil {
+				yield(noItem, err)
+				return
+			}
+			items, ok := response.Embedded[a.EmbeddedRel]
+			if !ok && response.Page.TotalElements > 0 {
+				yield(noItem, fmt.Errorf("embedded key %s not found in paginated response", a.EmbeddedRel))
+				return
+			}
+			for _, raw := range items {
+				var item T
+				if err := a.decode(raw, call.AnswersMeshObject, &item); err != nil {
+					yield(noItem, err)
+					return
+				}
+				if !yield(item, nil) {
+					return
+				}
+			}
+			if response.Page.Number >= response.Page.TotalPages-1 {
+				return
+			}
+		}
+	}
+}
+
+func (a Api) payload(body any, meshObject bool) (jsontext.Value, error) {
+	encoded, err := internaljson.Marshal(body)
+	if err != nil || !meshObject {
+		return encoded, err
+	}
+	version, err := openapi.ParseApiVersion(a.ApiVersion)
+	if err != nil {
+		return nil, err
+	}
+	return openapi.MediaType{Name: a.MediaType, Kind: a.Kind, ApiVersion: version}.WithKindAndApiVersion(encoded)
+}
+
+func (a Api) decode(answer []byte, meshObject bool, target any) error {
+	if meshObject {
+		var header struct {
+			Kind       string `json:"kind"`
+			ApiVersion string `json:"apiVersion"`
+		}
+		if err := json.Unmarshal(answer, &header); err != nil {
+			return fmt.Errorf("parsing response body as JSON failed: %w", err)
+		}
+		if header.Kind != a.Kind || header.ApiVersion != a.ApiVersion {
+			return errors.New("meshStack answered " + header.Kind + " " + header.ApiVersion + " for " + a.Kind + " " + a.ApiVersion)
+		}
+	}
+	if err := json.Unmarshal(answer, target); err != nil {
+		return fmt.Errorf("parsing response body as JSON failed: %w", err)
+	}
+	return nil
+}