frontend: make route registration spec-aware

Change RouteProvider.Routes() to accept (prefix, ctx, client) so that
providers can load the spec at registration time. This enables:

- SpecDefined annotation on each route (whether the target key appears
  in spec.Targets), used by the target list API
- Per-request NewRouter(ctx, client) in the BuildFunc, since route
  registration now needs the gateway client
- LoadSpecFromClient() helper in frontend/router.go for providers
- Each distro registers as a separate RouteProvider via
  RegisterRouteProvider()
- Bare distro prefix routes (e.g. "mariner2") as hidden aliases for
  the default container handler
- Hidden field on frontend.Target to exclude alias routes from the
  target list while keeping them dispatchable
- DebugRoutes now registers individual sub-routes (buildroot, sources,
  spec) instead of a single prefix handler
- gen-doc-targets uses a stub gwclient.Client to set up routes for
  documentation generation

Signed-off-by: Brian Goff <cpuguy83@gmail.com>

Author: cpuguy83

cmd/frontend/main.go

@@ -1,11 +1,13 @@
 package main
 
 import (
+	"context"
 	_ "embed"
 	"flag"
 	"fmt"
 	"os"
 
+	gwclient "github.com/moby/buildkit/frontend/gateway/client"
 	"github.com/moby/buildkit/frontend/gateway/grpcclient"
 	"github.com/moby/buildkit/util/appcontext"
 	"github.com/moby/buildkit/util/bklog"
@@ -65,12 +67,14 @@ func main() {
 
 func dalecMain() {
 	ctx := appcontext.Context()
-	r, err := frontendapi.NewRouter(ctx)
-	if err != nil {
-		bklog.L.WithError(err).Fatal("error creating frontend router")
-	}
 
-	if err := grpcclient.RunFromEnvironment(ctx, r.Handler(frontend.WithTargetForwardingHandler)); err != nil {
+	if err := grpcclient.RunFromEnvironment(ctx, func(ctx context.Context, client gwclient.Client) (*gwclient.Result, error) {
+		r, err := frontendapi.NewRouter(ctx, client)
+		if err != nil {
+			return nil, err
+		}
+		return r.Handler(frontend.WithTargetForwardingHandler)(ctx, client)
+	}); err != nil {
 		bklog.L.WithError(err).Fatal("error running frontend")
 		os.Exit(70) // 70 is EX_SOFTWARE, meaning internal software error occurred
 	}

cmd/gen-doc-targets/main.go

@@ -25,16 +25,16 @@ func main() {
 	bklog.L.Logger.SetLevel(logrus.ErrorLevel)
 	ctx := appcontext.Context()
 
-	r, err := frontendapi.NewRouter(ctx)
+	client := &targetPrintClient{}
+	r, err := frontendapi.NewRouter(ctx, client)
 	if err != nil {
 		bklog.L.Fatal(err)
 	}
 
-	var client gwclient.Client = &targetPrintClient{}
 	res, err := r.Handle(ctx, client)
 	if err != nil {
 		fmt.Fprintln(os.Stderr, err)
-		os.Exit(1)
+		os.Exit(2)
 	}
 
 	dt, ok := res.Metadata["result.txt"]
@@ -66,6 +66,8 @@ func main() {
 	}
 }
 
+// targetPrintClient embeds gwclient.Client and overrides methods needed
+// to load an empty spec during route setup and trigger the targets subrequest.
 type targetPrintClient struct {
 	gwclient.Client
 }
@@ -92,8 +94,8 @@ func (t *targetPrintClient) Solve(_ context.Context, _ gwclient.SolveRequest) (*
 	return res, nil
 }
 
-// emptySpecRef implements gwclient.Reference and returns an empty YAML object
-// from ReadFile, which LoadSpec interprets as an empty dalec.Spec.
+// emptySpecRef embeds gwclient.Reference and overrides ReadFile to return
+// an empty YAML object, which LoadSpec interprets as an empty dalec.Spec.
 type emptySpecRef struct {
 	gwclient.Reference
 }

cmd/worker-img-matrix/main.go

@@ -11,6 +11,10 @@ import (
 	"strings"
 
 	"github.com/containerd/plugin"
+	"github.com/moby/buildkit/client/llb"
+	gwclient "github.com/moby/buildkit/frontend/gateway/client"
+	"github.com/moby/buildkit/frontend/subrequests/targets"
+	"github.com/moby/buildkit/solver/pb"
 	"github.com/project-dalec/dalec/internal/plugins"
 	_ "github.com/project-dalec/dalec/targets/plugin"
 )
@@ -47,6 +51,7 @@ func main() {
 	}
 
 	ctx := context.Background()
+	client := &stubClient{}
 	set := plugin.NewPluginSet()
 
 	var out []Info
@@ -64,7 +69,11 @@ func main() {
 		}
 
 		provider := v.(plugins.RouteProvider)
-		for _, route := range provider.Routes() {
+		routes, err := provider.Routes(ctx, client)
+		if err != nil {
+			panic(fmt.Errorf("failed to get routes for plugin %s: %w", reg.ID, err))
+		}
+		for _, route := range routes {
 			_, suffix, ok := strings.Cut(route.FullPath, "/")
 			if ok && suffix == "worker" {
 				out = append(out, Info{Target: route.FullPath})
@@ -83,3 +92,35 @@ func main() {
 		panic(fmt.Errorf("failed to write output: %w", err))
 	}
 }
+
+// stubClient provides just enough gwclient.Client implementation for
+// spec-aware route registration to load an empty spec.
+type stubClient struct {
+	gwclient.Client
+}
+
+func (s *stubClient) BuildOpts() gwclient.BuildOpts {
+	return gwclient.BuildOpts{
+		Opts:    map[string]string{"requestid": targets.SubrequestsTargetsDefinition.Name},
+		LLBCaps: pb.Caps.CapSet(pb.Caps.All()),
+		Caps:    pb.Caps.CapSet(pb.Caps.All()),
+	}
+}
+
+func (s *stubClient) Inputs(_ context.Context) (map[string]llb.State, error) {
+	return map[string]llb.State{"dockerfile": llb.Scratch()}, nil
+}
+
+func (s *stubClient) Solve(_ context.Context, _ gwclient.SolveRequest) (*gwclient.Result, error) {
+	res := gwclient.NewResult()
+	res.SetRef(&emptySpecRef{})
+	return res, nil
+}
+
+type emptySpecRef struct {
+	gwclient.Reference
+}
+
+func (r *emptySpecRef) ReadFile(_ context.Context, _ gwclient.ReadRequest) ([]byte, error) {
+	return []byte("{}"), nil
+}

frontend/debug/handler.go

@@ -8,6 +8,7 @@ import (
 const DebugRoute = "debug"
 
 // Routes returns the flat routes for the debug handler, prefixed with the given prefix.
+// Debug routes are never spec-defined since no spec would have a "debug" target key.
 func Routes(prefix string) []frontend.Route {
 	return []frontend.Route{
 		{

frontend/router.go

@@ -31,6 +31,12 @@ type Target struct {
 	// appears in spec.Targets. When spec.Targets is empty (no explicit
 	// target filtering), this field is false for all targets.
 	SpecDefined bool `json:"specDefined,omitempty"`
+
+	// Hidden indicates that this route should not appear in the target
+	// list but is still dispatchable. This is used for routes like bare
+	// distro names (e.g. "mariner2") that act as aliases for a default
+	// sub-route (e.g. "mariner2/container").
+	Hidden bool `json:"hidden,omitempty"`
 }
 
 // TargetList is the dalec-extended target list response.
@@ -54,9 +60,6 @@ type Route struct {
 // It replaces the hierarchical BuildMux with a simpler dispatch model.
 type Router struct {
 	routes map[string]Route
-
-	// cached spec so we don't have to load it every time its needed
-	spec *dalec.Spec
 }
 
 // Add registers a route. If a route with the same FullPath already exists
@@ -105,11 +108,6 @@ func (r *Router) Handle(ctx context.Context, client gwclient.Client) (_ *gwclien
 		if retErr != nil {
 			if _, ok := opts[keyTopLevelTarget]; !ok {
 				retErr = errors.Wrapf(retErr, "error handling requested build target %q", target)
-
-				spec, _ := r.loadSpec(ctx, client)
-				if spec != nil && spec.Name != "" {
-					retErr = errors.Wrapf(retErr, "spec: %s", spec.Name)
-				}
 			}
 		}
 	}()
@@ -201,17 +199,9 @@ func (r *Router) describe() (*gwclient.Result, error) {
 }
 
 // list returns the target list. All route metadata is available directly —
-// no handler invocation needed. Targets are annotated with SpecDefined
-// based on the loaded spec.
+// no handler invocation needed. SpecDefined is set by providers at
+// route registration time.
 func (r *Router) list(ctx context.Context, client gwclient.Client, target string) (*gwclient.Result, error) {
-	spec, err := r.loadSpec(ctx, client)
-	if err != nil {
-		bklog.G(ctx).WithError(err).Warn("Could not load spec for target list annotation")
-		// Continue without spec — targets just won't have SpecDefined set.
-	}
-
-	hasSpecTargets := spec != nil && len(spec.Targets) > 0
-
 	var ls TargetList
 
 	keys := maps.Keys(r.routes)
@@ -225,15 +215,12 @@ func (r *Router) list(ctx context.Context, client gwclient.Client, target string
 			continue
 		}
 
-		dt := route.Info
-		if hasSpecTargets {
-			tlk := topLevelKey(key)
-			if _, ok := spec.Targets[tlk]; ok {
-				dt.SpecDefined = true
-			}
+		// Hidden routes are dispatchable but excluded from the target list.
+		if route.Info.Hidden {
+			continue
 		}
 
-		ls.Targets = append(ls.Targets, dt)
+		ls.Targets = append(ls.Targets, route.Info)
 	}
 
 	return dalecTargetListToResult(ls)
@@ -320,32 +307,27 @@ func (r *Router) lookupTarget(ctx context.Context, target string) (matchedPath s
 	return "", nil, handlerNotFound(target, maps.Keys(r.routes))
 }
 
-func (r *Router) loadSpec(ctx context.Context, client gwclient.Client) (*dalec.Spec, error) {
-	if r.spec != nil {
-		return r.spec, nil
+// topLevelKey returns the first path segment of a route path.
+// e.g. "azlinux3/container/depsonly" → "azlinux3"
+func topLevelKey(routePath string) string {
+	if i := strings.IndexByte(routePath, '/'); i >= 0 {
+		return routePath[:i]
 	}
+	return routePath
+}
+
+// LoadSpecFromClient loads a dalec spec from the gateway client's build
+// context. Build args are substituted with WithAllowAnyArg so that
+// unresolved args don't cause errors during route setup.
+func LoadSpecFromClient(ctx context.Context, client gwclient.Client) (*dalec.Spec, error) {
 	dc, err := dockerui.NewClient(client)
 	if err != nil {
 		return nil, err
 	}
 
-	spec, err := LoadSpec(ctx, dc, nil, func(cfg *LoadConfig) {
+	return LoadSpec(ctx, dc, nil, func(cfg *LoadConfig) {
 		cfg.SubstituteOpts = append(cfg.SubstituteOpts, dalec.WithAllowAnyArg)
 	})
-	if err != nil {
-		return nil, err
-	}
-	r.spec = spec
-	return spec, nil
-}
-
-// topLevelKey returns the first path segment of a route path.
-// e.g. "azlinux3/container/depsonly" → "azlinux3"
-func topLevelKey(routePath string) string {
-	if i := strings.IndexByte(routePath, '/'); i >= 0 {
-		return routePath[:i]
-	}
-	return routePath
 }
 
 // WithTargetForwardingHandler registers a forwarding handler for each
@@ -355,7 +337,7 @@ func WithTargetForwardingHandler(ctx context.Context, client gwclient.Client, r
 	if k := GetTargetKey(client); k != "" {
 		return fmt.Errorf("target forwarding requested but target is already forwarded: this is a bug in the frontend for %q", k)
 	}
-	spec, err := r.loadSpec(ctx, client)
+	spec, err := LoadSpecFromClient(ctx, client)
 	if err != nil {
 		return err
 	}

internal/frontendapi/router.go

@@ -5,14 +5,15 @@ import (
 	"fmt"
 
 	"github.com/containerd/plugin"
+	gwclient "github.com/moby/buildkit/frontend/gateway/client"
 	"github.com/project-dalec/dalec/frontend"
 	"github.com/project-dalec/dalec/frontend/debug"
 	"github.com/project-dalec/dalec/internal/plugins"
 	_ "github.com/project-dalec/dalec/targets/plugin"
 )
 
 // NewRouter creates a flat Router with all routes registered eagerly.
-func NewRouter(ctx context.Context) (*frontend.Router, error) {
+func NewRouter(ctx context.Context, client gwclient.Client) (*frontend.Router, error) {
 	r := &frontend.Router{}
 
 	// Register debug routes.
@@ -21,14 +22,14 @@ func NewRouter(ctx context.Context) (*frontend.Router, error) {
 	}
 
 	// Load route providers from the plugin registry.
-	if err := loadRouteProviders(ctx, r); err != nil {
+	if err := loadRouteProviders(ctx, client, r); err != nil {
 		return nil, err
 	}
 
 	return r, nil
 }
 
-func loadRouteProviders(ctx context.Context, r *frontend.Router) error {
+func loadRouteProviders(ctx context.Context, client gwclient.Client, r *frontend.Router) error {
 	set := plugin.NewPluginSet()
 
 	filter := func(reg *plugins.Registration) bool {
@@ -55,7 +56,11 @@ func loadRouteProviders(ctx context.Context, r *frontend.Router) error {
 		if !ok {
 			return fmt.Errorf("plugin %T does not implement RouteProvider", v)
 		}
-		for _, route := range provider.Routes() {
+		routes, err := provider.Routes(ctx, client)
+		if err != nil {
+			return err
+		}
+		for _, route := range routes {
 			r.Add(ctx, route)
 		}
 	}

internal/plugins/types.go

@@ -1,6 +1,9 @@
 package plugins
 
 import (
+	"context"
+
+	gwclient "github.com/moby/buildkit/frontend/gateway/client"
 	"github.com/project-dalec/dalec/frontend"
 )
 
@@ -12,12 +15,12 @@ const (
 
 // RouteProvider is implemented by plugins that supply flat routes for the Router.
 type RouteProvider interface {
-	Routes() []frontend.Route
+	Routes(ctx context.Context, client gwclient.Client) ([]frontend.Route, error)
 }
 
 // RouteProviderFunc is a convenience adapter for RouteProvider.
-type RouteProviderFunc func() []frontend.Route
+type RouteProviderFunc func(ctx context.Context, client gwclient.Client) ([]frontend.Route, error)
 
-func (f RouteProviderFunc) Routes() []frontend.Route {
-	return f()
+func (f RouteProviderFunc) Routes(ctx context.Context, client gwclient.Client) ([]frontend.Route, error) {
+	return f(ctx, client)
 }