codegen: generate go clients for custom resource routes (#1283)

## What Changed? Why?

Previously, the SDK only generated Go clients for individual resource
kinds
(CRUD operations + kind-level custom routes). However, manifest versions
can
also define custom routes at the routes.namespaced and routes.cluster
level —
scoped to a Group/Version rather than a specific kind — and no client
was
generated for those.

This PR adds codegen support for Group/Version-level custom route
clients.
When a manifest version defines routes in routes.namespaced or
routes.cluster,
   a CustomRouteClient is now generated in the version package (e.g.
pkg/generated/v1alpha1/client_gen.go) with typed methods for each route.

### Key Changes
- codegen/jennies/goclients.go: Split Generate into
generateResourceClients
(existing per-kind clients) and generateCustomRouteClients (new GV-level
clients). The new generator iterates over manifest versions and emits a
client
   file if any namespaced or clustered routes are present.
- codegen/templates/client.tmpl: New template for the CustomRouteClient
struct, with typed *Request/*Response wrapper methods for namespaced and
clustered routes. Uses NewCustomRouteClientFromGenerator to construct
the
  client from a resource.ClientGenerator.
- resource/client.go: Added CustomRouteClient interface
(NamespacedRequest /
  ClusteredRequest) and extended ClientGenerator with
  GetCustomRouteClient(schema.GroupVersion, string).
- k8s/custom_route_client.go: Concrete CustomRouteClient implementation
backed
   by the existing groupVersionClient.
- k8s/client_registry.go: Wired GetCustomRouteClient into the registry
so
  callers can obtain a CustomRouteClient for any registered GV.

Addresses Issue #1277

### How was it tested?
 - Codegen golden file tests
  - Local generation against example apiserver kinds
  - Manual client setup and live requests to the example apiserver

Author: amalavet

app/definitions/app-manifest-manifest.json

@@ -6,7 +6,7 @@
     },
     "spec": {
         "appName": "app-manifest",
-        "appDisplayName": "",
+        "appDisplayName": "app-manifest",
         "group": "apps.grafana.app",
         "versions": [
             {

app/manifestdata/appmanifest_manifest.go

@@ -31,6 +31,7 @@ var (
 
 var appManifestData = app.ManifestData{
 	AppName:          "app-manifest",
+	AppDisplayName:   "app-manifest",
 	Group:            "apps.grafana.app",
 	PreferredVersion: "v1alpha2",
 	Versions: []app.ManifestVersion{

benchmark/benchmark_mocks_test.go

@@ -294,3 +294,7 @@ func (m *mockClientGeneratorWithK8sClient) ClientFor(kind resource.Kind) (resour
 		k8s.DefaultClientConfig(),
 	)
 }
+
+func (m *mockClientGeneratorWithK8sClient) GetCustomRouteClient(gv schema.GroupVersion, defaultNamespace string) (resource.CustomRouteClient, error) {
+	return nil, nil
+}

codegen/cuekind/generators.go

@@ -178,7 +178,7 @@ func ManifestGoGenerator(pkg string, includeSchemas bool, projectRepo, goGenPath
 				return apiserver.ToOpenAPIName(path)
 			},
 		},
-		&jennies.ResourceClientJenny{
+		&jennies.ClientJenny{
 			GroupByKind: !groupKinds,
 		})
 	return g

codegen/cuekind/generators_test.go

@@ -132,8 +132,8 @@ func TestManifestGoGenerator(t *testing.T) {
 		files, err := ManifestGoGenerator("manifestdata", true, "codegen-tests", "pkg/generated", "manifestdata", true).Generate(kinds...)
 		require.NoError(t, err)
 		// Check number of files generated
-		// 14 -> manifest file (1), then the custom route response+query+body for reconcile (3), response body and wrapper+query+body for search in v3 (4), request, response, and wrapper for /foobar in v3 (3), +1 client per version (3)
-		require.Len(t, files, 14, "should be 14 files generated, got %d", len(files))
+		// 15 -> manifest file (1), then the custom route response+query+body for reconcile (3), response body and wrapper+query+body for search in v3 (4), request, response, and wrapper for /foobar in v3 (3), the resource clients for v1-v3 (3), and the version-level client for v3 routes (1)
+		require.Len(t, files, 15, "should be 15 files generated, got %d", len(files))
 		// Check content against the golden files
 		for _, file := range files {
 			compareToGolden(t, codejen.Files{file}, "go/groupbygroup")

codegen/jennies/goclients.go

@@ -2,6 +2,7 @@ package jennies
 
 import (
 	"bytes"
+	"errors"
 	"fmt"
 	"go/format"
 	"path/filepath"
@@ -15,19 +16,37 @@ import (
 	"github.com/grafana/grafana-app-sdk/codegen/templates"
 )
 
-type ResourceClientJenny struct {
+type ClientJenny struct {
 	// GroupByKind determines whether kinds are grouped by GroupVersionKind or just GroupVersion.
 	// If GroupByKind is true, generated paths are <kind>/<version>/<file>, instead of the default <version>/<file>.
 	// When GroupByKind is false, subresource types (such as spec and status) are prefixed with the kind name,
 	// i.e. generating FooSpec instead of Spec for kind.Name() = "Foo" and Depth=1
 	GroupByKind bool
 }
 
-func (*ResourceClientJenny) JennyName() string {
-	return "ResourceClientJenny"
+func (*ClientJenny) JennyName() string {
+	return "ClientJenny"
 }
 
-func (r *ResourceClientJenny) Generate(appManifest codegen.AppManifest) (codejen.Files, error) {
+func (r *ClientJenny) Generate(appManifest codegen.AppManifest) (codejen.Files, error) {
+	files := make(codejen.Files, 0)
+
+	groupVersionFiles, err := r.generateCustomRouteClients(appManifest)
+	if err != nil {
+		return nil, err
+	}
+	files = append(files, groupVersionFiles...)
+
+	resourceFiles, err := r.generateResourceClients(appManifest)
+	if err != nil {
+		return nil, err
+	}
+	files = append(files, resourceFiles...)
+
+	return files, nil
+}
+
+func (r *ClientJenny) generateResourceClients(appManifest codegen.AppManifest) (codejen.Files, error) {
 	files := make(codejen.Files, 0)
 	for version, kind := range codegen.VersionedKinds(appManifest) {
 		if !kind.Codegen.Go.Enabled {
@@ -61,23 +80,13 @@ func (r *ResourceClientJenny) Generate(appManifest codegen.AppManifest) (codejen
 			KindName:     exportField(kind.Kind),
 			KindPrefix:   prefix,
 			Subresources: subresources,
-			CustomRoutes: make([]templates.GoResourceClientCustomRoute, 0),
-		}
-		for cpath, methods := range kind.Routes {
-			for method, route := range methods {
-				if route.Name == "" {
-					route.Name = defaultRouteName(method, cpath)
-				}
-				crmd, err := r.getCustomRouteInfo(route)
-				if err != nil {
-					return nil, err
-				}
-				crmd.Path = cpath
-				crmd.Method = method
-				md.CustomRoutes = append(md.CustomRoutes, crmd)
-			}
 		}
-		slices.SortFunc(md.CustomRoutes, func(a, b templates.GoResourceClientCustomRoute) int {
+
+		md.CustomRoutes, err = getCustomRoutes(kind.Routes)
+		if err != nil {
+			return nil, fmt.Errorf("getting custom routes for kind %s: %w", kind.Kind, err)
+		}
+		slices.SortFunc(md.CustomRoutes, func(a, b templates.GoClientCustomRoute) int {
 			return strings.Compare(a.TypeName, b.TypeName)
 		})
 
@@ -105,24 +114,93 @@ func (r *ResourceClientJenny) Generate(appManifest codegen.AppManifest) (codejen
 	return files, nil
 }
 
-func (*ResourceClientJenny) getCustomRouteInfo(customRoute codegen.CustomRoute) (templates.GoResourceClientCustomRoute, error) {
-	md := templates.GoResourceClientCustomRoute{
+func (r *ClientJenny) generateCustomRouteClients(appManifest codegen.AppManifest) (codejen.Files, error) {
+	files := make(codejen.Files, 0)
+	for _, version := range appManifest.Versions() {
+		md := templates.GoCustomRouteClientMetadata{
+			PackageName: ToPackageName(version.Name()),
+			Group:       appManifest.Properties().FullGroup,
+			Version:     version.Name(),
+		}
+
+		var err error
+		md.NamespacedRoutes, err = getCustomRoutes(version.Routes().Namespaced)
+		if err != nil {
+			return nil, err
+		}
+
+		md.ClusterRoutes, err = getCustomRoutes(version.Routes().Cluster)
+		if err != nil {
+			return nil, err
+		}
+
+		if len(md.NamespacedRoutes) == 0 && len(md.ClusterRoutes) == 0 {
+			continue
+		}
+
+		b := bytes.Buffer{}
+		err = templates.WriteGoCustomRouteClient(md, &b)
+		if err != nil {
+			return nil, err
+		}
+		formatted, err := format.Source(b.Bytes())
+		if err != nil {
+			return nil, err
+		}
+		formatted, err = imports.Process("", formatted, &imports.Options{
+			Comments: true,
+		})
+		if err != nil {
+			return nil, err
+		}
+		files = append(files, codejen.File{
+			RelativePath: filepath.Join(ToPackageName(appManifest.Properties().Group), ToPackageName(version.Name()), "client_gen.go"),
+			Data:         formatted,
+			From:         []codejen.NamedJenny{r},
+		})
+	}
+	return files, nil
+}
+
+func getCustomRouteInfo(customRoute codegen.CustomRoute) (templates.GoClientCustomRoute, error) {
+	md := templates.GoClientCustomRoute{
 		TypeName:  toExportedFieldName(customRoute.Name),
 		HasParams: customRoute.Request.Query.Exists(),
 		HasBody:   customRoute.Request.Body.Exists(),
 	}
 	if md.HasParams {
-		md.ParamValues = make([]templates.GoResourceClientParamValues, 0)
+		md.ParamValues = make([]templates.GoCustomRouteParamValues, 0)
 		it, err := customRoute.Request.Query.Fields()
 		if err != nil {
 			return md, err
 		}
 		for it.Next() {
-			md.ParamValues = append(md.ParamValues, templates.GoResourceClientParamValues{
+			md.ParamValues = append(md.ParamValues, templates.GoCustomRouteParamValues{
 				Key:       it.Selector().String(),
 				FieldName: exportField(it.Selector().String()),
 			})
 		}
 	}
 	return md, nil
 }
+
+func getCustomRoutes(routeMap map[string]map[string]codegen.CustomRoute) ([]templates.GoClientCustomRoute, error) {
+	var errs error
+	routes := make([]templates.GoClientCustomRoute, 0)
+	for cpath, methods := range routeMap {
+		for method, route := range methods {
+			if route.Name == "" {
+				route.Name = defaultRouteName(method, cpath)
+			}
+			crmd, err := getCustomRouteInfo(route)
+			if err != nil {
+				errs = errors.Join(errs, err)
+				continue
+			}
+			crmd.Path = cpath
+			crmd.Method = method
+			routes = append(routes, crmd)
+		}
+	}
+	return routes, errs
+}

codegen/templates/client.tmpl

@@ -0,0 +1,96 @@
+package {{.PackageName}}
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+
+    "k8s.io/apimachinery/pkg/runtime/schema"
+	"github.com/grafana/grafana-app-sdk/resource"
+)
+
+type CustomRouteClient struct {
+	 resource.CustomRouteClient
+}
+
+func NewCustomRouteClient(client resource.CustomRouteClient) *CustomRouteClient {
+	return &CustomRouteClient{client}
+}
+
+func NewCustomRouteClientFromGenerator(generator resource.ClientGenerator, defaultNamespace string) (*CustomRouteClient, error) {
+	client, err := generator.GetCustomRouteClient(schema.GroupVersion{
+		Group:   "{{.Group}}",
+		Version: "{{.Version}}",
+	}, defaultNamespace)
+	if err != nil {
+		return nil, err
+	}
+	return NewCustomRouteClient(client), nil
+}
+{{ range .NamespacedRoutes }}
+type {{.TypeName}}Request struct { {{ if .HasParams }}
+	Params {{.TypeName}}RequestParams{{ end }}{{ if .HasBody }}
+	Body {{.TypeName}}RequestBody{{ end }}
+	Headers http.Header
+}
+
+func (c *CustomRouteClient) {{.TypeName}}(ctx context.Context, namespace string, request {{.TypeName}}Request) (*{{.TypeName}}Response, error) { {{ if .HasParams }}
+	params := url.Values{}{{ range .ParamValues }}
+	params.Set("{{.Key}}", fmt.Sprintf("%v", request.Params.{{.FieldName}})){{ end }}{{ end }}{{ if .HasBody }}
+	body, err := json.Marshal(request.Body)
+	if err != nil {
+		return nil, fmt.Errorf("unable to marshal body to JSON: %w", err)
+	}{{ end }}
+	resp, err := c.NamespacedRequest(ctx, namespace, resource.CustomRouteRequestOptions{
+		Path:    "{{.Path}}",
+		Verb:    "{{.Method}}",{{ if .HasParams }}
+		Query:   params,{{ end }}{{ if .HasBody }}
+		Body:    io.NopCloser(bytes.NewReader(body)),{{ end }}
+		Headers: request.Headers,
+	})
+	if err != nil {
+		return nil, err
+	}
+	cast := {{.TypeName}}Response{}
+	err = json.Unmarshal(resp, &cast)
+	if err != nil {
+		return nil, fmt.Errorf("unable to unmarshal response bytes into {{.TypeName}}Response: %w", err)
+	}
+	return &cast, nil
+}
+{{ end }}{{ range .ClusterRoutes }}
+type {{.TypeName}}Request struct { {{ if .HasParams }}
+	Params {{.TypeName}}RequestParams{{ end }}{{ if .HasBody }}
+	Body {{.TypeName}}RequestBody{{ end }}
+	Headers http.Header
+}
+
+func (c *CustomRouteClient) {{.TypeName}}(ctx context.Context, request {{.TypeName}}Request) (*{{.TypeName}}Response, error) { {{ if .HasParams }}
+	params := url.Values{}{{ range .ParamValues }}
+	params.Set("{{.Key}}", fmt.Sprintf("%v", request.Params.{{.FieldName}})){{ end }}{{ end }}{{ if .HasBody }}
+	body, err := json.Marshal(request.Body)
+	if err != nil {
+		return nil, fmt.Errorf("unable to marshal body to JSON: %w", err)
+	}{{ end }}
+	resp, err := c.ClusteredRequest(ctx, resource.CustomRouteRequestOptions{
+		Path:    "{{.Path}}",
+		Verb:    "{{.Method}}",{{ if .HasParams }}
+		Query:   params,{{ end }}{{ if .HasBody }}
+		Body:    io.NopCloser(bytes.NewReader(body)),{{ end }}
+		Headers: request.Headers,
+	})
+	if err != nil {
+		return nil, err
+	}
+	cast := {{.TypeName}}Response{}
+	err = json.Unmarshal(resp, &cast)
+	if err != nil {
+		return nil, fmt.Errorf("unable to unmarshal response bytes into {{.TypeName}}Response: %w", err)
+	}
+	return &cast, nil
+}
+{{ end }}