cli/command/context: deprecate exported types and functions

These functions and types are shallow wrappers around the context
store and were intended for internal use as implementation for the
CLI itself.

They were exported in 3126920af1 to be
used by plugins and Docker Desktop. However, there's currently no public
uses of this, and Docker Desktop does not use these functions.

This patch deprecates the exported functions as they were meant to be
implementation specific for the CLI. If there's a need to provide
utilities for manipulating the context-store other than through the
CLI itself, we can consider creating an SDK for that purpose.

This deprecates:

- `RunCreate` and `CreateOptions`
- `RunExport` and `ExportOptions`
- `RunImport`
- `RunRemove` and `RemoveOptions`
- `RunUpdate` and `UpdateOptions`
- `RunUse`

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

cli/command/context/create.go

@@ -19,6 +19,8 @@ import (
 )
 
 // CreateOptions are the options used for creating a context
+//
+// Deprecated: this type was for internal use and will be removed in the next release.
 type CreateOptions struct {
 	Name        string
 	Description string
@@ -30,6 +32,18 @@ type CreateOptions struct {
 	metaData map[string]any
 }
 
+// createOptions are the options used for creating a context
+type createOptions struct {
+	name        string
+	description string
+	endpoint    map[string]string
+	from        string
+
+	// Additional Metadata to store in the context. This option is not
+	// currently exposed to the user.
+	metaData map[string]any
+}
+
 func longCreateDescription() string {
 	buf := bytes.NewBuffer(nil)
 	buf.WriteString("Create a context\n\nDocker endpoint config:\n\n")
@@ -44,52 +58,68 @@ func longCreateDescription() string {
 }
 
 func newCreateCommand(dockerCLI command.Cli) *cobra.Command {
-	opts := &CreateOptions{}
+	opts := createOptions{}
 	cmd := &cobra.Command{
 		Use:   "create [OPTIONS] CONTEXT",
 		Short: "Create a context",
 		Args:  cli.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
-			opts.Name = args[0]
-			return RunCreate(dockerCLI, opts)
+			opts.name = args[0]
+			return runCreate(dockerCLI, &opts)
 		},
 		Long:              longCreateDescription(),
 		ValidArgsFunction: completion.NoComplete,
 	}
 	flags := cmd.Flags()
-	flags.StringVar(&opts.Description, "description", "", "Description of the context")
-	flags.StringToStringVar(&opts.Docker, "docker", nil, "set the docker endpoint")
-	flags.StringVar(&opts.From, "from", "", "create context from a named context")
+	flags.StringVar(&opts.description, "description", "", "Description of the context")
+	flags.StringToStringVar(&opts.endpoint, "docker", nil, "set the docker endpoint")
+	flags.StringVar(&opts.from, "from", "", "create context from a named context")
 	return cmd
 }
 
 // RunCreate creates a Docker context
+
+// Deprecated: this function was for internal use and will be removed in the next release.
 func RunCreate(dockerCLI command.Cli, o *CreateOptions) error {
+	if o == nil {
+		o = &CreateOptions{}
+	}
+
+	return runCreate(dockerCLI, &createOptions{
+		name:        o.Name,
+		description: o.Description,
+		endpoint:    o.Docker,
+		metaData:    o.metaData,
+	})
+}
+
+// runCreate creates a Docker context
+func runCreate(dockerCLI command.Cli, opts *createOptions) error {
 	s := dockerCLI.ContextStore()
-	err := checkContextNameForCreation(s, o.Name)
+	err := checkContextNameForCreation(s, opts.name)
 	if err != nil {
 		return err
 	}
 	switch {
-	case o.From == "" && o.Docker == nil:
-		err = createFromExistingContext(s, dockerCLI.CurrentContext(), o)
-	case o.From != "":
-		err = createFromExistingContext(s, o.From, o)
+	case opts.from == "" && opts.endpoint == nil:
+		err = createFromExistingContext(s, dockerCLI.CurrentContext(), opts)
+	case opts.from != "":
+		err = createFromExistingContext(s, opts.from, opts)
 	default:
-		err = createNewContext(s, o)
+		err = createNewContext(s, opts)
 	}
 	if err == nil {
-		_, _ = fmt.Fprintln(dockerCLI.Out(), o.Name)
-		_, _ = fmt.Fprintf(dockerCLI.Err(), "Successfully created context %q\n", o.Name)
+		_, _ = fmt.Fprintln(dockerCLI.Out(), opts.name)
+		_, _ = fmt.Fprintf(dockerCLI.Err(), "Successfully created context %q\n", opts.name)
 	}
 	return err
 }
 
-func createNewContext(contextStore store.ReaderWriter, o *CreateOptions) error {
-	if o.Docker == nil {
+func createNewContext(contextStore store.ReaderWriter, opts *createOptions) error {
+	if opts.endpoint == nil {
 		return errors.New("docker endpoint configuration is required")
 	}
-	dockerEP, dockerTLS, err := getDockerEndpointMetadataAndTLS(contextStore, o.Docker)
+	dockerEP, dockerTLS, err := getDockerEndpointMetadataAndTLS(contextStore, opts.endpoint)
 	if err != nil {
 		return fmt.Errorf("unable to create docker endpoint config: %w", err)
 	}
@@ -98,10 +128,10 @@ func createNewContext(contextStore store.ReaderWriter, o *CreateOptions) error {
 			docker.DockerEndpoint: dockerEP,
 		},
 		Metadata: command.DockerContext{
-			Description:      o.Description,
-			AdditionalFields: o.metaData,
+			Description:      opts.description,
+			AdditionalFields: opts.metaData,
 		},
-		Name: o.Name,
+		Name: opts.name,
 	}
 	contextTLSData := store.ContextTLSData{}
 	if dockerTLS != nil {
@@ -115,7 +145,7 @@ func createNewContext(contextStore store.ReaderWriter, o *CreateOptions) error {
 	if err := contextStore.CreateOrUpdate(contextMetadata); err != nil {
 		return err
 	}
-	return contextStore.ResetTLSMaterial(o.Name, &contextTLSData)
+	return contextStore.ResetTLSMaterial(opts.name, &contextTLSData)
 }
 
 func checkContextNameForCreation(s store.Reader, name string) error {
@@ -131,16 +161,16 @@ func checkContextNameForCreation(s store.Reader, name string) error {
 	return nil
 }
 
-func createFromExistingContext(s store.ReaderWriter, fromContextName string, o *CreateOptions) error {
-	if len(o.Docker) != 0 {
+func createFromExistingContext(s store.ReaderWriter, fromContextName string, opts *createOptions) error {
+	if len(opts.endpoint) != 0 {
 		return errors.New("cannot use --docker flag when --from is set")
 	}
 	reader := store.Export(fromContextName, &descriptionDecorator{
 		Reader:      s,
-		description: o.Description,
+		description: opts.description,
 	})
 	defer reader.Close()
-	return store.Import(o.Name, s, reader)
+	return store.Import(opts.name, s, reader)
 }
 
 type descriptionDecorator struct {