sdk: negotiate API version

Author: charludo

e2e/coordinator/coordinator_test.go

@@ -205,7 +205,7 @@ func TestCoordinator(t *testing.T) {
 		nonce := [32]byte{}
 		var report []byte
 		require.NoError(ct.Kubeclient.WithForwardedPort(ctx, ct.Namespace, "port-forwarder-coordinator-ready", apitypes.Port, func(addr string) error {
-			r, err := client.GetAttestation(ctx, fmt.Sprintf("http://%s/attest", addr), nonce[:])
+			r, err := client.WithBaseURL(fmt.Sprintf("http://%s", addr)).GetAttestation(ctx, nonce[:])
 			if err != nil {
 				return err
 			}

e2e/internal/contrasttest/contrasttest.go

@@ -400,8 +400,7 @@ func (ct *ContrastTest) RunVerify(ctx context.Context) error {
 	}
 	var serializedAttestation []byte
 	err = ct.Kubeclient.WithForwardedPort(ctx, ct.Namespace, "port-forwarder-coordinator", apitypes.Port, func(addr string) error {
-		url := fmt.Sprintf("http://%s/attest", addr)
-		resp, err := client.GetAttestation(ctx, url, nonce)
+		resp, err := client.WithBaseURL(fmt.Sprintf("http://%s", addr)).GetAttestation(ctx, nonce)
 		if err != nil {
 			return fmt.Errorf("getting attestation: %w", err)
 		}

sdk/apiv1/apiv1.go

@@ -0,0 +1,29 @@
+// Copyright 2026 Edgeless Systems GmbH
+// SPDX-License-Identifier: BUSL-1.1
+
+//go:build contrast_unstable_api
+
+// Package apiv1 implements version v1 of the Contrast HTTP API.
+//
+// Obtain an [API] from the SDK client via its V1 method, rather than constructing one
+// directly. Use this package to pin calls to v1; the SDK's top-level methods always speak
+// the newest API version the Coordinator supports.
+package apiv1
+
+import (
+	"github.com/edgelesssys/contrast/apitypes"
+	"github.com/edgelesssys/contrast/sdk/internal/transport"
+)
+
+// Version is the API version implemented by this package.
+const Version = apitypes.APIVersionV1
+
+// API calls version v1 of the Coordinator's HTTP API.
+type API struct {
+	transport *transport.Client
+}
+
+// New returns an [API] using the given transport.
+func New(t *transport.Client) *API {
+	return &API{transport: t}
+}

sdk/capabilities.go

@@ -0,0 +1,69 @@
+// Copyright 2026 Edgeless Systems GmbH
+// SPDX-License-Identifier: BUSL-1.1
+
+//go:build contrast_unstable_api
+
+package sdk
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"slices"
+	"sync"
+
+	"github.com/edgelesssys/contrast/apitypes"
+	"github.com/edgelesssys/contrast/sdk/apiv1"
+)
+
+// capabilitiesPath is the path of the Coordinator's capabilities endpoint.
+//
+// This endpoint is deliberately unversioned. It's how clients discover which versions
+// exist, so it must be reachable without knowing a version first.
+const capabilitiesPath = "/capabilities"
+
+// supportedAPIVersions are the API versions this SDK can speak, newest first.
+var supportedAPIVersions = []string{apiv1.Version}
+
+// negotiation caches the result of API version negotiation.
+//
+// It's held behind a pointer so that copying a [Client] doesn't copy the mutex.
+type negotiation struct {
+	mu      sync.Mutex
+	version string
+}
+
+// NegotiateAPIVersion returns the newest API version supported by both this SDK and the Coordinator.
+//
+// The result is cached, so this costs at most one request per [Client].
+func (c Client) NegotiateAPIVersion(ctx context.Context) (string, error) {
+	c.negotiated.mu.Lock()
+	defer c.negotiated.mu.Unlock()
+	if c.negotiated.version != "" {
+		return c.negotiated.version, nil
+	}
+
+	body, err := c.transport.DoJSON(ctx, http.MethodGet, capabilitiesPath, nil)
+	if err != nil {
+		return "", fmt.Errorf("getting capabilities: %w", err)
+	}
+	var caps apitypes.CapabilitiesResponse
+	if err := json.Unmarshal(body, &caps); err != nil {
+		return "", fmt.Errorf("unmarshalling capabilities: %w", err)
+	}
+
+	// supportedAPIVersions is ordered newest first, so the first match is the best one.
+	for _, version := range supportedAPIVersions {
+		if slices.Contains(caps.APIVersions, version) {
+			c.negotiated.version = version
+			return version, nil
+		}
+	}
+	return "", fmt.Errorf("no common API version: Coordinator supports %v, SDK supports %v", caps.APIVersions, supportedAPIVersions)
+}
+
+// V1 returns a client for version v1 of the Coordinator's HTTP API.
+func (c Client) V1() *apiv1.API {
+	return apiv1.New(c.transport)
+}

sdk/capabilities_test.go

@@ -0,0 +1,150 @@
+// Copyright 2026 Edgeless Systems GmbH
+// SPDX-License-Identifier: BUSL-1.1
+
+//go:build contrast_unstable_api
+
+package sdk
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"sync/atomic"
+	"testing"
+
+	"github.com/edgelesssys/contrast/apitypes"
+	"github.com/edgelesssys/contrast/sdk/apiv1"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestNegotiateAPIVersion(t *testing.T) {
+	for name, tc := range map[string]struct {
+		coordinatorVersions []string
+		handler             http.Handler
+
+		wantVersion string
+		wantErr     string
+	}{
+		"coordinator supports v1": {
+			coordinatorVersions: []string{apiv1.Version},
+			wantVersion:         apiv1.Version,
+		},
+		"coordinator supports a newer version, too": {
+			coordinatorVersions: []string{apiv1.Version, "v2"},
+			wantVersion:         apiv1.Version,
+		},
+		"no common version": {
+			coordinatorVersions: []string{"v99"},
+			wantErr:             "no common API version",
+		},
+		"coordinator has no capabilities endpoint": {
+			handler: http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+				w.WriteHeader(http.StatusNotFound)
+			}),
+			wantErr: "getting capabilities",
+		},
+		"capabilities response is malformed": {
+			handler: http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+				_, _ = w.Write([]byte("not json"))
+			}),
+			wantErr: "unmarshalling capabilities",
+		},
+	} {
+		t.Run(name, func(t *testing.T) {
+			require := require.New(t)
+			assert := assert.New(t)
+
+			handler := tc.handler
+			if handler == nil {
+				handler = capabilitiesHandler(tc.coordinatorVersions)
+			}
+			srv := httptest.NewServer(handler)
+			t.Cleanup(srv.Close)
+
+			version, err := New().WithBaseURL(srv.URL).NegotiateAPIVersion(t.Context())
+
+			if tc.wantErr != "" {
+				require.Error(err)
+				assert.Contains(err.Error(), tc.wantErr)
+				return
+			}
+			require.NoError(err)
+			assert.Equal(tc.wantVersion, version)
+		})
+	}
+}
+
+// TestNegotiateAPIVersionCaching ensures the Coordinator is only asked once per Client.
+func TestNegotiateAPIVersionCaching(t *testing.T) {
+	require := require.New(t)
+	assert := assert.New(t)
+
+	var calls atomic.Int32
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		calls.Add(1)
+		capabilitiesHandler([]string{apiv1.Version}).ServeHTTP(w, r)
+	}))
+	t.Cleanup(srv.Close)
+
+	client := New().WithBaseURL(srv.URL)
+	for range 3 {
+		version, err := client.NegotiateAPIVersion(t.Context())
+		require.NoError(err)
+		assert.Equal(apiv1.Version, version)
+	}
+	assert.Equal(int32(1), calls.Load())
+}
+
+// TestNegotiateAPIVersionErrorNotCached ensures a transient failure doesn't poison the Client.
+func TestNegotiateAPIVersionErrorNotCached(t *testing.T) {
+	require := require.New(t)
+
+	var fail atomic.Bool
+	fail.Store(true)
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if fail.Load() {
+			w.WriteHeader(http.StatusServiceUnavailable)
+			return
+		}
+		capabilitiesHandler([]string{apiv1.Version}).ServeHTTP(w, r)
+	}))
+	t.Cleanup(srv.Close)
+
+	client := New().WithBaseURL(srv.URL)
+	_, err := client.NegotiateAPIVersion(t.Context())
+	require.Error(err)
+
+	fail.Store(false)
+	version, err := client.NegotiateAPIVersion(t.Context())
+	require.NoError(err)
+	require.Equal(apiv1.Version, version)
+}
+
+// TestWithAPIVersionSkipsNegotiation ensures a pinned version doesn't contact the Coordinator.
+func TestWithAPIVersionSkipsNegotiation(t *testing.T) {
+	require := require.New(t)
+
+	var contacted atomic.Bool
+	srv := httptest.NewServer(http.HandlerFunc(func(_ http.ResponseWriter, _ *http.Request) {
+		contacted.Store(true)
+	}))
+	t.Cleanup(srv.Close)
+
+	version, err := New().WithBaseURL(srv.URL).WithAPIVersion(apiv1.Version).NegotiateAPIVersion(t.Context())
+	require.NoError(err)
+	require.Equal(apiv1.Version, version)
+	require.False(contacted.Load(), "Coordinator must not be contacted for a pinned API version")
+}
+
+func capabilitiesHandler(versions []string) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != capabilitiesPath || r.Method != http.MethodGet {
+			w.WriteHeader(http.StatusNotFound)
+			return
+		}
+		if err := json.NewEncoder(w).Encode(apitypes.CapabilitiesResponse{APIVersions: versions}); err != nil {
+			panic(err)
+		}
+	})
+}

sdk/internal/transport/transport.go

@@ -0,0 +1,114 @@
+// Copyright 2026 Edgeless Systems GmbH
+// SPDX-License-Identifier: BUSL-1.1
+
+//go:build contrast_unstable_api
+
+// Package transport implements the HTTP plumbing shared by the SDK's API versions.
+//
+// It's internal so that the versioned API packages can share one connection setup
+// without exposing it as part of the SDK's public surface.
+package transport
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"log/slog"
+	"net/http"
+	"net/url"
+	"strings"
+
+	"github.com/edgelesssys/contrast/apitypes"
+)
+
+// ErrBaseURLUnset is returned when a request is attempted without a base URL.
+var ErrBaseURLUnset = errors.New("no base URL set, use WithBaseURL")
+
+// Client performs JSON requests against the Coordinator's HTTP API.
+type Client struct {
+	// HTTPClient is used to contact the Coordinator.
+	HTTPClient *http.Client
+	// BaseURL is the Coordinator's HTTP API root, e.g. "http://coordinator:1314".
+	BaseURL string
+	// Log receives diagnostics that aren't part of a returned error.
+	Log *slog.Logger
+}
+
+// URL resolves an API path like "/v1/manifest" against the client's base URL.
+func (c *Client) URL(path string) (string, error) {
+	if c.BaseURL == "" {
+		return "", ErrBaseURLUnset
+	}
+	base, err := url.Parse(c.BaseURL)
+	if err != nil {
+		return "", fmt.Errorf("parsing base URL %q: %w", c.BaseURL, err)
+	}
+	ref, err := url.Parse(path)
+	if err != nil {
+		return "", fmt.Errorf("parsing path %q: %w", path, err)
+	}
+	// Ensure a base URL with a path prefix, as used by reverse proxies, keeps that
+	// prefix: "https://proxy/contrast" + "/v1/manifest" resolves to
+	// "https://proxy/contrast/v1/manifest".
+	base.Path = strings.TrimSuffix(base.Path, "/") + ref.EscapedPath()
+	base.RawQuery = ref.RawQuery
+	return base.String(), nil
+}
+
+// DoJSON sends reqBody JSON-encoded to the given API path and returns the raw response body.
+//
+// If the Coordinator responds with a non-OK status, the body is parsed as an
+// [apitypes.APIError] and returned as an error.
+func (c *Client) DoJSON(ctx context.Context, method, path string, reqBody any) ([]byte, error) {
+	url, err := c.URL(path)
+	if err != nil {
+		return nil, err
+	}
+
+	var bodyReader io.Reader
+	if reqBody != nil {
+		body, err := json.Marshal(reqBody)
+		if err != nil {
+			return nil, fmt.Errorf("creating request body: %w", err)
+		}
+		bodyReader = bytes.NewBuffer(body)
+	}
+
+	req, err := http.NewRequestWithContext(ctx, method, url, bodyReader)
+	if err != nil {
+		return nil, fmt.Errorf("constructing HTTP request: %w", err)
+	}
+	if reqBody != nil {
+		req.Header.Set("Content-Type", "application/json")
+	}
+
+	httpResp, err := c.HTTPClient.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("http request failed: %w", err)
+	}
+	defer httpResp.Body.Close()
+
+	if httpResp.StatusCode != http.StatusOK {
+		errBody, err := io.ReadAll(httpResp.Body)
+		if err != nil {
+			return nil, fmt.Errorf("reading response (status code %d): %w", httpResp.StatusCode, err)
+		}
+		details := httpResp.Status
+		var apiErr apitypes.APIError
+		if err := json.Unmarshal(errBody, &apiErr); err == nil {
+			details = apiErr.Err
+		} else {
+			c.Log.Error("parsing error response", "err", err, "response", string(errBody))
+		}
+		return nil, fmt.Errorf("HTTP API call failed with %d (%s): %s", httpResp.StatusCode, http.StatusText(httpResp.StatusCode), details)
+	}
+
+	resp, err := io.ReadAll(httpResp.Body)
+	if err != nil {
+		return nil, fmt.Errorf("reading HTTP response body: %w", err)
+	}
+	return resp, nil
+}