Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions RELEASES.md
Original file line number Diff line number Diff line change
Expand Up @@ -142,6 +142,17 @@ new field; runtimes that previously loaded all `@2` mixin guidance inline
need the matching draft implementation, even when the field is omitted.
`agent-context@1` and `schemaVersion` are unchanged.

The authored-only `providesFrom` field
([SPEC-v3 §9.7](docs/spec/SPEC-v3.md#97-provides-stated-from-a-path))
is a top-level addition made in place under the same draft-stage
latitude, approved by maintainer @cdupuis's instruction to implement it.
Publishing replaces the field with ordinary `provides` entries and
drops it, so published descriptors keep their shape: readers of
published Kits, runtimes included, need no change. A frontend or other
reader of authored descriptors built before the field refuses a
descriptor that uses it. `schemaVersion` and every capability version
are unchanged.

The exception ends with the first stable specification release. After
that, changes to shipped capability meanings, defaults, permitted
values, reconciliation, or persistent-state transitions require a new
Expand Down
35 changes: 35 additions & 0 deletions cmd/frontend/build.go
Original file line number Diff line number Diff line change
Expand Up @@ -106,6 +106,13 @@ func Build(ctx context.Context, c gwclient.Client) (*gwclient.Result, error) {
if err != nil {
return nil, withYAMLSource(err, filename, src.descriptor)
}
// providesFrom is an instruction to this build, kept on d until the
// filesystems it names exist. The published form never carries it
// (§9.7), so it leaves here, before anything judges that form.
published, err = spec.WithoutProvidesFrom(published)
if err != nil {
return nil, withYAMLSource(err, filename, src.descriptor)
}

content := commentContent
switch {
Expand Down Expand Up @@ -243,6 +250,12 @@ func Build(ctx context.Context, c gwclient.Client) (*gwclient.Result, error) {
if err := spec.RequireAuthoredProvides(pd); err != nil {
return nil, withYAMLSource(err, filename, src.descriptor)
}
// On the expanded form for the same reason: a provides entry
// whose name came out of an arg can only now be seen to state
// a capability providesFrom states too.
if err := spec.RequireDistinctProvidesFrom(pd, d.ProvidesFrom); err != nil {
return nil, withYAMLSource(err, filename, src.descriptor)
}
}

res := gwclient.NewResult()
Expand Down Expand Up @@ -308,6 +321,13 @@ func Build(ctx context.Context, c gwclient.Client) (*gwclient.Result, error) {
if err != nil {
return nil, err
}
// What the author asked for by name stands ahead of the
// inventory nobody asked for entry by entry.
stated, err := statedProvides(ctx, d.ProvidesFrom, builds)
if err != nil {
return nil, withYAMLSource(err, filename, src.descriptor)
}
derived = append(stated, derived...)
Comment thread
cdupuis marked this conversation as resolved.
Resolved
if len(derived) > 0 {
published, pd, err = withDerivedProvides(published, derived)
if err != nil {
Expand Down Expand Up @@ -1029,6 +1049,21 @@ func withDerivedProvides(published []byte, derived []string) ([]byte, *spec.Desc
// A kit that declared none still carries what its filesystem
// holds, so the field is created rather than skipped.
provides = &yaml.Node{Kind: yaml.SequenceNode, Tag: "!!seq"}
// No key on the root is not the same as no entries: a merge
// key can hand the root a provides list from another mapping,
// and a key created here would override that list rather than
// extend it. So the new list starts from what the descriptor
// decodes to, which is the author's entries wherever they were
// written — and leaves the merged mapping alone, since
// something else may share it.
inherited, err := spec.Decode(published)
if err != nil {
return nil, nil, fmt.Errorf("published descriptor no longer decodes: %w", err)
}
for _, entry := range inherited.Provides {
provides.Content = append(provides.Content,
&yaml.Node{Kind: yaml.ScalarNode, Tag: "!!str", Value: entry})
}
root.Content = append(root.Content,
&yaml.Node{Kind: yaml.ScalarNode, Tag: "!!str", Value: "provides"}, provides)
case provides.Kind == yaml.ScalarNode && provides.Tag == "!!null":
Expand Down
51 changes: 51 additions & 0 deletions cmd/frontend/packages.go
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,9 @@ import (
"bytes"
"context"
"fmt"
"os"

"github.com/containerd/platforms"
gwclient "github.com/moby/buildkit/frontend/gateway/client"

"github.com/docker/sandbox-kit-spec/v3/spec"
Expand Down Expand Up @@ -53,3 +55,52 @@ func derivedProvides(ctx context.Context, refs []gwclient.Reference) ([]string,
}
return out, nil
}

// statedProvides resolves the kit's providesFrom declaration against
// every platform's filesystem (§9.7): each path to the installed package
// that owns it, and each name to that package's version.
func statedProvides(ctx context.Context, from map[string]string, builds []platformBuild) ([]string, error) {
if len(from) == 0 {
return nil, nil
}
files := make([]spec.PlatformFiles, 0, len(builds))
for _, b := range builds {
p := spec.PlatformFiles{Platform: platforms.FormatAll(platformOrDefault(b.platform))}
if b.ref != nil {
p.Files = imageFiles{ref: b.ref}
}
files = append(files, p)
}
return spec.ProvidesFromPaths(ctx, from, files)
}

// imageFiles reads a solved filesystem for the spec package, which
// knows what to look for and not what a BuildKit reference is.
type imageFiles struct{ ref gwclient.Reference }

func (f imageFiles) ReadFile(ctx context.Context, name string) ([]byte, bool, error) {
return readImageFile(ctx, f.ref, name)
}

// ReadDir lists a directory through the gateway, which walks it without
// following its entries: a symbolic link arrives with its target, which
// is the one thing StatFile cannot say — it resolves the whole path and
// answers for wherever that ends.
func (f imageFiles) ReadDir(ctx context.Context, name string) ([]spec.ImageEntry, bool, error) {
stats, err := f.ref.ReadDir(ctx, gwclient.ReadDirRequest{Path: name})
if err != nil {
if isNotExist(err) {
return nil, false, nil
}
return nil, false, err
}
entries := make([]spec.ImageEntry, 0, len(stats))
for _, st := range stats {
entries = append(entries, spec.ImageEntry{
Name: st.Path,
Dir: os.FileMode(st.Mode).IsDir(),
Link: st.Linkname,
})
}
return entries, true, nil
}
118 changes: 118 additions & 0 deletions cmd/frontend/provides_from_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,118 @@
package main

import (
"context"
"io/fs"
"os"
"path"
"strings"
"testing"

gwclient "github.com/moby/buildkit/frontend/gateway/client"
ocispecs "github.com/opencontainers/image-spec/specs-go/v1"
"github.com/stretchr/testify/require"
fstypes "github.com/tonistiigi/fsutil/types"

"github.com/docker/sandbox-kit-spec/v3/spec"
)

// packagedReference is a solved filesystem as the gateway presents one:
// files read by name, and a directory listed with each entry's own
// stat, so a symbolic link arrives as a link with its target.
type packagedReference struct {
fakeReference
files map[string]string
links map[string]string
}

func (r packagedReference) ReadFile(_ context.Context, req gwclient.ReadRequest) ([]byte, error) {
body, ok := r.files[req.Filename]
if !ok {
return nil, fs.ErrNotExist
}
return []byte(body), nil
}

func (r packagedReference) ReadDir(_ context.Context, req gwclient.ReadDirRequest) ([]*fstypes.Stat, error) {
seen := map[string]*fstypes.Stat{}
for name := range r.files {
if path.Dir(name) == req.Path {
seen[path.Base(name)] = &fstypes.Stat{Path: path.Base(name), Mode: 0o755}
} else if rest, under := strings.CutPrefix(name, strings.TrimSuffix(req.Path, "/")+"/"); under {
top, _, _ := strings.Cut(rest, "/")
seen[top] = &fstypes.Stat{Path: top, Mode: uint32(os.ModeDir | 0o755)}
}
}
for name, target := range r.links {
if path.Dir(name) == req.Path {
seen[path.Base(name)] = &fstypes.Stat{Path: path.Base(name), Mode: uint32(os.ModeSymlink | 0o777), Linkname: target}
}
}
if len(seen) == 0 {
return nil, fs.ErrNotExist
}
out := make([]*fstypes.Stat, 0, len(seen))
for _, st := range seen {
out = append(out, st)
}
return out, nil
}

func debianReference(sshVersion string) packagedReference {
return packagedReference{
files: map[string]string{
spec.DpkgStatusPath: "Package: openssh-client\nStatus: install ok installed\nVersion: " + sshVersion + "\n\n" +
"Package: python-3.14-minimal\nStatus: install ok installed\nVersion: 3.14.10-6\n",
spec.DpkgInfoDir + "/openssh-client.list": "/usr/bin/ssh\n",
spec.DpkgInfoDir + "/python-3.14-minimal.list": "/usr/bin/python3.14\n/usr/bin/python3\n",
"/usr/bin/ssh": "elf",
"/usr/bin/python3.14": "elf",
},
links: map[string]string{
"/bin": "usr/bin",
"/usr/bin/python3": "python3.14",
},
}
}

// The spec package decides what a path resolves to; this is the half
// that only the frontend can get wrong — reading a directory through the
// gateway so that a link is seen as one, and naming each platform.
func TestStatedProvidesReadEveryPlatformThroughTheGateway(t *testing.T) {
from := map[string]string{"python": "/usr/bin/python3", "ssh": "/bin/ssh"}
arm := &ocispecs.Platform{OS: "linux", Architecture: "arm64"}
amd := &ocispecs.Platform{OS: "linux", Architecture: "amd64"}

got, err := statedProvides(t.Context(), from, []platformBuild{
{platform: arm, ref: debianReference("1:10.0p1-7+deb13u4")},
{platform: amd, ref: debianReference("1:10.0p1-7+deb13u4")},
})
require.NoError(t, err)
require.Equal(t, []string{"python@3.14.10", "ssh@10.0"}, got)

_, err = statedProvides(t.Context(), from, []platformBuild{
{platform: arm, ref: debianReference("1:10.0p1-7+deb13u4")},
{platform: amd, ref: debianReference("1:10.1p1-1")},
})
require.ErrorContains(t, err, "providesFrom.ssh: /bin/ssh is at 10.0 on linux/arm64 and 10.1 on linux/amd64")

// Nothing asked for, nothing read: a kit without the field never
// pays for the file lists.
got, err = statedProvides(t.Context(), nil, []platformBuild{{platform: arm}})
require.NoError(t, err)
require.Empty(t, got)
}

// A directory that is not there is an absence, not a failure: the spec
// package turns it into the diagnostic that names the missing database.
func TestImageFilesReportAMissingDirectoryAsAbsent(t *testing.T) {
files := imageFiles{ref: packagedReference{}}
entries, present, err := files.ReadDir(context.Background(), spec.DpkgInfoDir)
require.NoError(t, err)
require.False(t, present)
require.Empty(t, entries)

_, present, err = files.ReadFile(context.Background(), spec.DpkgStatusPath)
require.NoError(t, err)
require.False(t, present)
}
37 changes: 37 additions & 0 deletions cmd/frontend/rewrite_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -172,3 +172,40 @@ capabilities:
require.Equal(t, "./always.md", d.Capabilities[0].Config["contentFile"])
require.Equal(t, "/staged/maybe.md", d.Capabilities[1].Group.Capabilities[0].Config["contentFile"])
}

// A merge key can supply provides, and then the root mapping has no
// provides key of its own. Creating one for the derived entries would
// override the inherited list, so the author's entries are carried into
// the list that is created.
func TestDerivedProvidesKeepWhatAMergeKeyProvides(t *testing.T) {
published := []byte(`schemaVersion: "3"
kind: workload
version: "1.0.0"
<<: {provides: ["agent@1.0.0"], displayName: Merged}
`)

out, pd, err := withDerivedProvides(published, []string{"python@3.14.10", "deb/bash@5.2.37"})
require.NoError(t, err)
require.Equal(t, []string{"agent@1.0.0", "python@3.14.10", "deb/bash@5.2.37"}, pd.Provides)
require.Equal(t, "Merged", pd.DisplayName, "the rest of what was merged is untouched")

fromBytes, err := spec.Decode(out)
require.NoError(t, err)
require.Equal(t, pd.Provides, fromBytes.Provides)

// An anchored mapping merged by alias is not edited: whatever else
// refers to it still sees the list it had.
shared := []byte(`schemaVersion: "3"
kind: workload
version: "1.0.0"
capabilities:
- type: com.example/thing@1
config: &shared
provides: ["agent@1.0.0"]
<<: *shared
`)
_, pd, err = withDerivedProvides(shared, []string{"deb/bash@5.2.37"})
require.NoError(t, err)
require.Equal(t, []string{"agent@1.0.0", "deb/bash@5.2.37"}, pd.Provides)
require.Equal(t, map[string]any{"provides": []any{"agent@1.0.0"}}, pd.Capabilities[0].Config)
}
Loading