client: prepare option-structs for multiple platforms

Some methods currently support a single platform only, but we may
be able to support multiple platforms.

This patch prepares the option-structs for multi-platform support,
but (for now) returning an error if multiple options are provided.

We need a similar check on the daemon-side, but still need to check
on the client, as older daemons will ignore multiple platforms, which
may be unexpected.

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

client/image_build.go

@@ -8,8 +8,8 @@ import (
 	"net/http"
 	"net/url"
 	"strconv"
-	"strings"
 
+	cerrdefs "github.com/containerd/errdefs"
 	"github.com/moby/moby/api/types/container"
 	"github.com/moby/moby/api/types/network"
 )
@@ -154,8 +154,12 @@ func (cli *Client) imageBuildOptionsToQuery(_ context.Context, options ImageBuil
 	if options.SessionID != "" {
 		query.Set("session", options.SessionID)
 	}
-	if options.Platform != "" {
-		query.Set("platform", strings.ToLower(options.Platform))
+	if len(options.Platforms) > 0 {
+		if len(options.Platforms) > 1 {
+			// TODO(thaJeztah): update API spec and add equivalent check on the daemon. We need this still for older daemons, which would ignore it.
+			return query, cerrdefs.ErrInvalidArgument.WithMessage("specifying multiple platforms is not yet supported")
+		}
+		query.Set("platform", formatPlatform(options.Platforms[0]))
 	}
 	if options.BuildID != "" {
 		query.Set("buildid", options.BuildID)

client/image_build_opts.go

@@ -6,6 +6,7 @@ import (
 	"github.com/moby/moby/api/types/build"
 	"github.com/moby/moby/api/types/container"
 	"github.com/moby/moby/api/types/registry"
+	ocispec "github.com/opencontainers/image-spec/specs-go/v1"
 )
 
 // ImageBuildOptions holds the information
@@ -50,7 +51,9 @@ type ImageBuildOptions struct {
 	ExtraHosts  []string // List of extra hosts
 	Target      string
 	SessionID   string
-	Platform    string
+	// Platforms selects the platforms to build the image for. Multiple platforms
+	// can be provided if the daemon supports multi-platform builds.
+	Platforms []ocispec.Platform
 	// Version specifies the version of the underlying builder to use
 	Version build.BuilderVersion
 	// BuildID is an optional identifier that can be passed together with the

client/image_create.go

@@ -4,8 +4,8 @@ import (
 	"context"
 	"net/http"
 	"net/url"
-	"strings"
 
+	cerrdefs "github.com/containerd/errdefs"
 	"github.com/distribution/reference"
 	"github.com/moby/moby/api/types/registry"
 )
@@ -21,8 +21,12 @@ func (cli *Client) ImageCreate(ctx context.Context, parentReference string, opti
 	query := url.Values{}
 	query.Set("fromImage", ref.Name())
 	query.Set("tag", getAPITagFromNamedRef(ref))
-	if options.Platform != "" {
-		query.Set("platform", strings.ToLower(options.Platform))
+	if len(options.Platforms) > 0 {
+		if len(options.Platforms) > 1 {
+			// TODO(thaJeztah): update API spec and add equivalent check on the daemon. We need this still for older daemons, which would ignore it.
+			return ImageCreateResult{}, cerrdefs.ErrInvalidArgument.WithMessage("specifying multiple platforms is not yet supported")
+		}
+		query.Set("platform", formatPlatform(options.Platforms[0]))
 	}
 	resp, err := cli.tryImageCreate(ctx, query, staticAuth(options.RegistryAuth))
 	if err != nil {

client/image_create_opts.go

@@ -1,11 +1,18 @@
 package client
 
-import "io"
+import (
+	"io"
+
+	ocispec "github.com/opencontainers/image-spec/specs-go/v1"
+)
 
 // ImageCreateOptions holds information to create images.
 type ImageCreateOptions struct {
 	RegistryAuth string // RegistryAuth is the base64 encoded credentials for the registry.
-	Platform     string // Platform is the target platform of the image if it needs to be pulled from the registry.
+	// Platforms specifies the platforms to platform of the image if it needs
+	// to be pulled from the registry. Multiple platforms can be provided
+	// if the daemon supports multi-platform pulls.
+	Platforms []ocispec.Platform
 }
 
 // ImageCreateResult holds the response body returned by the daemon for image create.

client/image_import.go

@@ -3,7 +3,6 @@ package client
 import (
 	"context"
 	"net/url"
-	"strings"
 
 	"github.com/distribution/reference"
 )
@@ -31,8 +30,9 @@ func (cli *Client) ImageImport(ctx context.Context, source ImageImportSource, re
 	if options.Message != "" {
 		query.Set("message", options.Message)
 	}
-	if options.Platform != "" {
-		query.Set("platform", strings.ToLower(options.Platform))
+	if p := formatPlatform(options.Platform); p != "unknown" {
+		// TODO(thaJeztah): would we ever support mutiple platforms here? (would require multiple rootfs tars as well?)
+		query.Set("platform", p)
 	}
 	for _, change := range options.Changes {
 		query.Add("changes", change)

client/image_import_opts.go

@@ -2,6 +2,8 @@ package client
 
 import (
 	"io"
+
+	ocispec "github.com/opencontainers/image-spec/specs-go/v1"
 )
 
 // ImageImportSource holds source information for ImageImport
@@ -12,10 +14,10 @@ type ImageImportSource struct {
 
 // ImageImportOptions holds information to import images from the client host.
 type ImageImportOptions struct {
-	Tag      string   // Tag is the name to tag this image with. This attribute is deprecated.
-	Message  string   // Message is the message to tag the image with
-	Changes  []string // Changes are the raw changes to apply to this image
-	Platform string   // Platform is the target platform of the image
+	Tag      string           // Tag is the name to tag this image with. This attribute is deprecated.
+	Message  string           // Message is the message to tag the image with
+	Changes  []string         // Changes are the raw changes to apply to this image
+	Platform ocispec.Platform // Platform is the target platform of the image
 }
 
 // ImageImportResult holds the response body returned by the daemon for image import.

client/image_import_test.go

@@ -9,6 +9,7 @@ import (
 	"testing"
 
 	cerrdefs "github.com/containerd/errdefs"
+	ocispec "github.com/opencontainers/image-spec/specs-go/v1"
 	"gotest.tools/v3/assert"
 	is "gotest.tools/v3/assert/cmp"
 )
@@ -55,7 +56,10 @@ func TestImageImport(t *testing.T) {
 		{
 			doc: "with platform",
 			options: ImageImportOptions{
-				Platform: "linux/amd64",
+				Platform: ocispec.Platform{
+					Architecture: "amd64",
+					OS:           "linux",
+				},
 			},
 			expectedQueryParams: url.Values{
 				"fromSrc":  {"image_source"},

client/image_pull.go

@@ -5,7 +5,6 @@ import (
 	"io"
 	"iter"
 	"net/url"
-	"strings"
 
 	cerrdefs "github.com/containerd/errdefs"
 	"github.com/distribution/reference"
@@ -44,10 +43,13 @@ func (cli *Client) ImagePull(ctx context.Context, refStr string, options ImagePu
 	if !options.All {
 		query.Set("tag", getAPITagFromNamedRef(ref))
 	}
-	if options.Platform != "" {
-		query.Set("platform", strings.ToLower(options.Platform))
+	if len(options.Platforms) > 0 {
+		if len(options.Platforms) > 1 {
+			// TODO(thaJeztah): update API spec and add equivalent check on the daemon. We need this still for older daemons, which would ignore it.
+			return nil, cerrdefs.ErrInvalidArgument.WithMessage("specifying multiple platforms is not yet supported")
+		}
+		query.Set("platform", formatPlatform(options.Platforms[0]))
 	}
-
 	resp, err := cli.tryImageCreate(ctx, query, staticAuth(options.RegistryAuth))
 	if cerrdefs.IsUnauthorized(err) && options.PrivilegeFunc != nil {
 		resp, err = cli.tryImageCreate(ctx, query, options.PrivilegeFunc)

client/image_pull_opts.go

@@ -2,6 +2,8 @@ package client
 
 import (
 	"context"
+
+	ocispec "github.com/opencontainers/image-spec/specs-go/v1"
 )
 
 // ImagePullOptions holds information to pull images.
@@ -16,5 +18,8 @@ type ImagePullOptions struct {
 	//
 	// For details, refer to [github.com/moby/moby/api/types/registry.RequestAuthConfig].
 	PrivilegeFunc func(context.Context) (string, error)
-	Platform      string
+
+	// Platforms selects the platforms to pull. Multiple platforms can be
+	// specified if the image ia a multi-platform image.
+	Platforms []ocispec.Platform
 }