Depends on #1269
Fixes #751

Edit:

This PR introduces the ability to essentially marshal and unmarshal between llb.State and pb.Definition. In addition, it also allows using previously solved client.Result to be used as an input to a new build graph.

For example, we can do some parallel solve requests, and then use their results in a new graph:

eg, ctx := errgroup.WithContext(ctx)

inputs := []llb.State{
	llb.Scratch().File(llb.Mkfile("/out", 0600, []byte("foo"))),
	llb.Scratch().File(llb.Mkfile("/out", 0600, []byte("bar"))),
}

var mu sync.Mutex
outputs := make([]llb.State, len(inputs))

for i, st := range inputs {
	i, st := i, st
	eg.Go(func() error {
		def, err := st.Marshal()
		if err != nil {
			return err
		}

		res, err := c.Solve(ctx, client.SolveRequest{
			Definition: def.ToPB(),
		})
		if err != nil {
			return err
		}

		ref, err := res.SingleRef()
		if err != nil {
			return err
		}

		output, err := ref.ToState()
		if err != nil {
			return err
		}

		mu.Lock()
		outputs[i] = output
		mu.Unlock()
		return nil
	})
}

err := eg.Wait()
if err != nil {
	return err
}

output := llb.Scratch()

for i, output := range outputs {
	output = output.File(
		llb.Copy(output, "/out", "/out"+i),
	)
}

def, err := output.Marshal()
if err != nil {
	return err
}

res, err := c.Solve(ctx, client.SolveRequest{
	Definition: def.ToPB(),
})

// ...

In order for previous solve results (client.Result).SingleRef to be used as an argument for llb.NewState, client.Reference must implement llb.Output. However, there is an import cycle related to gw.ResolveImageConfigOpt which I moved to the llb package. Let me know if you prefer this as a separate PR.

client.Reference implements llb.Output with the help of the pb.Definition of the previous solve. When the new solve references an Op from a previous solve, it must still traverse the graph so the marshaled definitions responsible for the previous solve's result must be included in the new one. We implemented in a way such that users are not exposed to this detail.

Questions

1. When the *llbBridge handles a definition-based solve, it loads an edge from the definition:

   buildkit/solver/llbsolver/bridge.go

   Lines 97 to 100 in 9257b28

   	edge, err := Load(req.Definition, dpc.Load, ValidateEntitlements(ent), WithCacheSources(cms), RuntimePlatforms(b.platforms), WithValidateCaps())
   	if err != nil {
   	return nil, errors.Wrap(err, "failed to load LLB")
   	}

Definitions end with an empty op ((pb.Op).Op == nil) with a single input pointing to the last Op. The Load function returns the edge referencing this last Op:

Which is eventually built by a solver.Job:

The result that gets returned is the llb.Vertex we want to return, and we need it to also carry the full definition up to that vertex. It seems to only make sense to plumb the definition on the final result so I added req.Definition to the frontend.Result. Does this make sense? I'm not sure how this interplays with multi-result arrays.

2. I think part of my confusion is I don't understand multi-result arrays too well. What is an example of a solve that returns multiple results? And how can it be utilized?

Todo

• Forward definition of frontend-based solves
• Tests
• Handle validation and constraints correctly