chore: consistency across modules (#76)

* chore(client): do not expose NewClientOption

* chore: automatically add the SDK labels in the Create operations

* fix(client): do not allow altering the SDK labels

* chore(network): rename for consistency

Prefer FindBy over GetBy

* fix: handle nil maps when adding SDK labels

Author: mdelapenya

client/client.container.go

@@ -21,6 +21,9 @@ func (c *Client) ContainerCreate(ctx context.Context, config *container.Config,
 		return container.CreateResponse{}, fmt.Errorf("docker client: %w", err)
 	}
 
+	// Add the labels that identify this as a container created by the SDK.
+	AddSDKLabels(config.Labels)
+
 	return dockerClient.ContainerCreate(ctx, config, hostConfig, networkingConfig, platform, name)
 }
 

client/client.image.go

@@ -22,6 +22,9 @@ func (c *Client) ImageBuild(ctx context.Context, options build.ImageBuildOptions
 		return build.ImageBuildResponse{}, errors.New("build context is nil")
 	}
 
+	// Add client labels
+	AddSDKLabels(options.Labels)
+
 	return dockerClient.ImageBuild(ctx, options.Context, options)
 }
 

client/client.network.go

@@ -24,6 +24,9 @@ func (c *Client) NetworkCreate(ctx context.Context, name string, options network
 		return network.CreateResponse{}, fmt.Errorf("docker client: %w", err)
 	}
 
+	// Add the labels that identify this as a network created by the SDK.
+	AddSDKLabels(options.Labels)
+
 	return dockerClient.NetworkCreate(ctx, name, options)
 }
 

client/client.volume.go

@@ -14,6 +14,9 @@ func (c *Client) VolumeCreate(ctx context.Context, options volume.CreateOptions)
 		return volume.Volume{}, fmt.Errorf("docker client: %w", err)
 	}
 
+	// Add the labels that identify this as a volume created by the SDK.
+	AddSDKLabels(options.Labels)
+
 	return dockerClient.VolumeCreate(ctx, options)
 }
 

client/client_test.go

@@ -2,7 +2,6 @@ package client_test
 
 import (
 	"context"
-	"errors"
 	"path/filepath"
 	"sync"
 	"testing"
@@ -88,19 +87,6 @@ func TestNew(t *testing.T) {
 		require.Nil(t, cli)
 	})
 
-	t.Run("error/apply-option", func(t *testing.T) {
-		// custom option that always fails to apply
-		customOpt := func() client.ClientOption {
-			return client.NewClientOption(func(_ *client.Client) error {
-				return errors.New("apply option")
-			})
-		}
-
-		cli, err := client.New(context.Background(), customOpt())
-		require.ErrorContains(t, err, "apply option")
-		require.Nil(t, cli)
-	})
-
 	t.Run("healthcheck/nil", func(t *testing.T) {
 		cli, err := client.New(context.Background(), client.WithHealthCheck(nil))
 		require.ErrorContains(t, err, "health check is nil")

client/client_unit_test.go

@@ -150,4 +150,17 @@ func TestNew_internal_state(t *testing.T) {
 		require.ErrorContains(t, err, "docker host from context")
 		require.Nil(t, client)
 	})
+
+	t.Run("error/apply-option", func(t *testing.T) {
+		// custom option that always fails to apply
+		customOpt := func() ClientOption {
+			return newClientOption(func(_ *Client) error {
+				return errors.New("apply option")
+			})
+		}
+
+		cli, err := New(context.Background(), customOpt())
+		require.ErrorContains(t, err, "apply option")
+		require.Nil(t, cli)
+	})
 }

client/labels.go

@@ -13,15 +13,28 @@ const (
 	LabelVersion = LabelBase + ".version"
 )
 
-// SDKLabels returns a map of labels that can be used to identify resources
+// sdkLabels is a map of labels that can be used to identify resources
 // created by this library.
-var SDKLabels = map[string]string{
+var sdkLabels = map[string]string{
 	LabelBase:    "true",
 	LabelLang:    "go",
 	LabelVersion: Version(),
 }
 
 // AddSDKLabels adds the SDK labels to target.
 func AddSDKLabels(target map[string]string) {
-	maps.Copy(target, SDKLabels)
+	if target == nil {
+		target = make(map[string]string)
+	}
+	maps.Copy(target, sdkLabels)
+}
+
+// SDKLabels returns a map of labels that can be used to identify resources
+// created by this library.
+func SDKLabels() map[string]string {
+	return map[string]string{
+		LabelBase:    "true",
+		LabelLang:    "go",
+		LabelVersion: Version(),
+	}
 }

client/labels_test.go

@@ -15,4 +15,14 @@ func TestAddSDKLabels(t *testing.T) {
 	require.Contains(t, labels, client.LabelBase)
 	require.Contains(t, labels, client.LabelLang)
 	require.Contains(t, labels, client.LabelVersion)
+
+	t.Run("idempotent", func(t *testing.T) {
+		sdkLabels := client.SDKLabels()
+		sdkLabels["foo"] = "bar"
+
+		labels := make(map[string]string)
+		client.AddSDKLabels(labels)
+		require.NotEqual(t, sdkLabels, labels)
+		require.NotContains(t, labels, "foo")
+	})
 }

client/options.go

@@ -40,14 +40,14 @@ func (f funcOpt) Apply(c *Client) error {
 	return f(c)
 }
 
-// NewClientOption creates a new ClientOption from a function
-func NewClientOption(f func(*Client) error) ClientOption {
+// newClientOption creates a new ClientOption from a function
+func newClientOption(f func(*Client) error) ClientOption {
 	return funcOpt(f)
 }
 
 // WithDockerHost returns a client option that sets the docker host for the client.
 func WithDockerHost(dockerHost string) ClientOption {
-	return NewClientOption(func(c *Client) error {
+	return newClientOption(func(c *Client) error {
 		c.dockerHost = dockerHost
 		return nil
 	})
@@ -57,15 +57,15 @@ func WithDockerHost(dockerHost string) ClientOption {
 // If set, the client will use the docker context to determine the docker host.
 // If used in combination with [WithDockerHost], the host in the context will take precedence.
 func WithDockerContext(dockerContext string) ClientOption {
-	return NewClientOption(func(c *Client) error {
+	return newClientOption(func(c *Client) error {
 		c.dockerContext = dockerContext
 		return nil
 	})
 }
 
 // WithExtraHeaders returns a client option that sets the extra headers for the client.
 func WithExtraHeaders(headers map[string]string) ClientOption {
-	return NewClientOption(func(c *Client) error {
+	return newClientOption(func(c *Client) error {
 		c.extraHeaders = headers
 		return nil
 	})
@@ -75,7 +75,7 @@ func WithExtraHeaders(headers map[string]string) ClientOption {
 // If not set, the default health check will be used, which retries the ping to the
 // docker daemon until it is ready, three times, or the context is done.
 func WithHealthCheck(healthCheck func(ctx context.Context) func(c *Client) error) ClientOption {
-	return NewClientOption(func(c *Client) error {
+	return newClientOption(func(c *Client) error {
 		if healthCheck == nil {
 			return errors.New("health check is nil")
 		}
@@ -87,7 +87,7 @@ func WithHealthCheck(healthCheck func(ctx context.Context) func(c *Client) error
 
 // WithLogger returns a client option that sets the logger for the client.
 func WithLogger(log *slog.Logger) ClientOption {
-	return NewClientOption(func(c *Client) error {
+	return newClientOption(func(c *Client) error {
 		c.log = log
 		return nil
 	})

container/container.run.go

@@ -99,14 +99,13 @@ func Run(ctx context.Context, opts ...ContainerCustomizer) (*Container, error) {
 		}
 	}
 
-	// Add the labels that identify this as a container created by the SDK.
-	client.AddSDKLabels(def.labels)
+	def.labels[moduleLabel] = Version()
 
 	dockerInput := &container.Config{
 		Entrypoint: def.entrypoint,
 		Image:      def.image,
 		Env:        env,
-		Labels:     def.labels,
+		Labels:     def.labels, // the Client will add the SDK labels automatically
 		Cmd:        def.cmd,
 	}