feat(api): add daemon version endpoint client and version comparison

Add GetDaemonVersion to query the /version endpoint exposed by the
engine, returning a DaemonVersion (name + version) or
ErrVersionNotSupported when the daemon predates the version API.

Add Compare(a, b Version) for semver ordering, enabling callers to
gate feature use on the daemon version.

Signed-off-by: Alano Terblanche <18033717+Benehiko@users.noreply.github.com>

Author: Benehiko

client/client.go

@@ -32,9 +32,10 @@ import (
 )
 
 type (
-	Envelope = secrets.Envelope
-	ID       = secrets.ID
-	Pattern  = secrets.Pattern
+	Envelope      = secrets.Envelope
+	ID            = secrets.ID
+	Pattern       = secrets.Pattern
+	DaemonVersion = api.DaemonVersion
 )
 
 var (
@@ -118,6 +119,7 @@ type config struct {
 }
 
 type client struct {
+	httpClient     *http.Client
 	resolverClient secrets.Resolver
 	listClient     resolverv1connect.ListServiceClient
 }
@@ -133,9 +135,21 @@ func (c client) GetSecrets(ctx context.Context, pattern secrets.Pattern) ([]secr
 	return envelopes, nil
 }
 
+func (c client) Version(ctx context.Context) (DaemonVersion, error) {
+	dv, err := api.GetDaemonVersion(ctx, c.httpClient)
+	if isDialError(err) {
+		return DaemonVersion{}, fmt.Errorf("%w: %w", ErrSecretsEngineNotAvailable, err)
+	}
+	return dv, err
+}
+
+// Client is the interface for interacting with the secrets engine daemon.
 type Client interface {
 	secrets.Resolver
 
+	// Version returns the name and version reported by the daemon.
+	Version(ctx context.Context) (DaemonVersion, error)
+
 	ListPlugins(ctx context.Context) ([]PluginInfo, error)
 }
 
@@ -185,6 +199,7 @@ func New(options ...Option) (Client, error) {
 		Timeout: cfg.requestTimeout,
 	}
 	return &client{
+		httpClient:     c,
 		resolverClient: resolver.NewResolverClient(c),
 		listClient:     resolverv1connect.NewListServiceClient(c, "http://unix"),
 	}, nil

x/api/daemon.go

@@ -0,0 +1,71 @@
+// Copyright 2025-2026 Docker, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package api
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/http"
+)
+
+// ErrVersionNotSupported is returned when the daemon does not expose a version
+// endpoint (i.e. it predates the version API).
+var ErrVersionNotSupported = errors.New("daemon does not support version endpoint")
+
+// DaemonVersion holds the name and version reported by the daemon.
+type DaemonVersion struct {
+	Name    string
+	Version Version
+}
+
+// GetDaemonVersion fetches the daemon version from the /version endpoint using
+// the provided HTTP client. The client must be configured to dial the engine
+// unix socket.
+func GetDaemonVersion(ctx context.Context, httpClient *http.Client) (DaemonVersion, error) {
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, "http://unix/version", nil)
+	if err != nil {
+		return DaemonVersion{}, fmt.Errorf("building version request: %w", err)
+	}
+
+	resp, err := httpClient.Do(req)
+	if err != nil {
+		return DaemonVersion{}, err
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode == http.StatusNotFound {
+		return DaemonVersion{}, ErrVersionNotSupported
+	}
+	if resp.StatusCode != http.StatusOK {
+		return DaemonVersion{}, fmt.Errorf("unexpected status from /version: %d", resp.StatusCode)
+	}
+
+	var body struct {
+		Name    string `json:"name"`
+		Version string `json:"version"`
+	}
+	if err := json.NewDecoder(resp.Body).Decode(&body); err != nil {
+		return DaemonVersion{}, fmt.Errorf("decoding version response: %w", err)
+	}
+
+	v, err := NewVersion(body.Version)
+	if err != nil {
+		return DaemonVersion{}, fmt.Errorf("parsing daemon version %q: %w", body.Version, err)
+	}
+
+	return DaemonVersion{Name: body.Name, Version: v}, nil
+}

x/api/version.go

@@ -59,6 +59,13 @@ func MustNewVersion(s string) Version {
 	return v
 }
 
+// Compare returns an integer comparing two versions according to semantic versioning.
+// The result will be 0 if a == b, -1 if a < b, or +1 if a > b.
+// An invalid semver string is considered less than a valid one.
+func Compare(a, b Version) int {
+	return semver.Compare(a.String(), b.String())
+}
+
 func valid(s string) error {
 	if len(s) > 0 && s[0] != 'v' {
 		return ErrVPrefix