api/types: move RequestPrivilegeFunc to api/types/registry

Move the definition, but mostly keep it for documentation purposes, to prevent having to import the registry package in all places. Signed-off-by: Sebastiaan van Stijn <[email protected]>
thaJeztah · Aug 30, 2024 · bb899c6 · bb899c6
1 parent 04b0e61
commit bb899c6
Show file tree

Hide file tree

Showing 5 changed files with 42 additions and 19 deletions.
diff --git a/api/types/client.go b/api/types/client.go
@@ -129,14 +129,6 @@ type ImageBuildResponse struct {
 	OSType string
 }
 
-// RequestPrivilegeFunc is a function interface that
-// clients can supply to retry operations after
-// getting an authorization error.
-// This function returns the registry authentication
-// header value in base 64 format, or an error
-// if the privilege request fails.
-type RequestPrivilegeFunc func(context.Context) (string, error)
-
 // NodeListOptions holds parameters to list nodes with.
 type NodeListOptions struct {
 	Filters filters.Args
@@ -235,11 +227,18 @@ type PluginDisableOptions struct {
 
 // PluginInstallOptions holds parameters to install a plugin.
 type PluginInstallOptions struct {
-	Disabled              bool
-	AcceptAllPermissions  bool
-	RegistryAuth          string // RegistryAuth is the base64 encoded credentials for the registry
-	RemoteRef             string // RemoteRef is the plugin name on the registry
-	PrivilegeFunc         RequestPrivilegeFunc
+	Disabled             bool
+	AcceptAllPermissions bool
+	RegistryAuth         string // RegistryAuth is the base64 encoded credentials for the registry
+	RemoteRef            string // RemoteRef is the plugin name on the registry
+
+	// PrivilegeFunc is a function that clients can supply to retry operations
+	// after getting an authorization error. This function returns the registry
+	// authentication header value in base64 encoded format, or an error if the
+	// privilege request fails.
+	//
+	// For details, refer to [github.com/docker/docker/api/types/registry.RequestAuthConfig].
+	PrivilegeFunc         func(context.Context) (string, error)
 	AcceptPermissionsFunc func(context.Context, PluginPrivileges) (bool, error)
 	Args                  []string
 }

diff --git a/api/types/image/opts.go b/api/types/image/opts.go
@@ -38,7 +38,7 @@ type PullOptions struct {
 	// authentication header value in base64 encoded format, or an error if the
 	// privilege request fails.
 	//
-	// Also see [github.com/docker/docker/api/types.RequestPrivilegeFunc].
+	// For details, refer to [github.com/docker/docker/api/types/registry.RequestAuthConfig].
 	PrivilegeFunc func(context.Context) (string, error)
 	Platform      string
 }
@@ -53,7 +53,7 @@ type PushOptions struct {
 	// authentication header value in base64 encoded format, or an error if the
 	// privilege request fails.
 	//
-	// Also see [github.com/docker/docker/api/types.RequestPrivilegeFunc].
+	// For details, refer to [github.com/docker/docker/api/types/registry.RequestAuthConfig].
 	PrivilegeFunc func(context.Context) (string, error)
 
 	// Platform is an optional field that selects a specific platform to push

diff --git a/api/types/registry/authconfig.go b/api/types/registry/authconfig.go
@@ -1,5 +1,6 @@
 package registry // import "github.com/docker/docker/api/types/registry"
 import (
+	"context"
 	"encoding/base64"
 	"encoding/json"
 	"io"
@@ -12,6 +13,18 @@ import (
 // authorization credentials for registry operations (push/pull).
 const AuthHeader = "X-Registry-Auth"
 
+// RequestAuthConfig is a function interface that clients can supply
+// to retry operations after getting an authorization error.
+//
+// The function must return the [AuthHeader] value ([AuthConfig]), encoded
+// in base64url format ([RFC4648, section 5]), which can be decoded by
+// [DecodeAuthConfig].
+//
+// It must return an error if the privilege request fails.
+//
+// [RFC4648, section 5]: https://tools.ietf.org/html/rfc4648#section-5
+type RequestAuthConfig func(context.Context) (string, error)
+
 // AuthConfig contains authorization information for connecting to a Registry.
 type AuthConfig struct {
 	Username string `json:"username,omitempty"`

diff --git a/api/types/registry/search.go b/api/types/registry/search.go
@@ -10,11 +10,12 @@ import (
 type SearchOptions struct {
 	RegistryAuth string
 
-	// PrivilegeFunc is a [types.RequestPrivilegeFunc] the client can
-	// supply to retry operations after getting an authorization error.
+	// PrivilegeFunc is a function that clients can supply to retry operations
+	// after getting an authorization error. This function returns the registry
+	// authentication header value in base64 encoded format, or an error if the
+	// privilege request fails.
 	//
-	// It must return the registry authentication header value in base64
-	// format, or an error if the privilege request fails.
+	// For details, refer to [github.com/docker/docker/api/types/registry.RequestAuthConfig].
 	PrivilegeFunc func(context.Context) (string, error)
 	Filters       filters.Args
 	Limit         int

diff --git a/api/types/types_deprecated.go b/api/types/types_deprecated.go
@@ -1,6 +1,8 @@
 package types
 
 import (
+	"context"
+
 	"github.com/docker/docker/api/types/container"
 	"github.com/docker/docker/api/types/image"
 	"github.com/docker/docker/api/types/storage"
@@ -97,3 +99,11 @@ type RootFS = image.RootFS
 //
 // Deprecated: use [image.InspectResponse].
 type ImageInspect = image.InspectResponse
+
+// RequestPrivilegeFunc is a function interface that clients can supply to
+// retry operations after getting an authorization error.
+// This function returns the registry authentication header value in base64
+// format, or an error if the privilege request fails.
+//
+// Deprecated: moved to [github.com/docker/docker/api/types/registry.RequestAuthConfig].
+type RequestPrivilegeFunc func(context.Context) (string, error)