feat(sdk): make the unsuffixed client name the v1 surface in python and go

Author: kvinwang

sdk/go/README.md

@@ -189,30 +189,25 @@ const (
 // The methods here mirror the unversioned paths (`/GetKey`, equivalently
 // `/v0/GetKey`), which the agent serves unchanged for pre-0.6 clients and will
 // never extend. New capability lives on DstackClientV1.
+//
+// Deprecated: legacy surface, frozen at v0.5.11 and never extended. New code
+// should use DstackClient, which is DstackClientV1. Reaching for the explicit
+// V0 name is the deliberate way to stay on the frozen surface.
 type DstackClientV0 struct {
 	transport
 }
 
-// DstackClient is the pre-0.6 name for DstackClientV0.
-//
-// Deprecated: use DstackClientV0, or DstackClientV1 for the current API.
-type DstackClient = DstackClientV0
-
 // Creates a new DstackClientV0 instance based on the provided endpoint.
 // If the endpoint is empty, it will use the simulator endpoint if it is
 // set in the environment through DSTACK_SIMULATOR_ENDPOINT. Otherwise, it
 // will use the default endpoint at /var/run/dstack.sock.
+//
+// Deprecated: constructs a client for the frozen v0.5.11 surface. New code
+// should use NewDstackClient, which returns a v1 client.
 func NewDstackClientV0(opts ...DstackClientOption) *DstackClientV0 {
 	return &DstackClientV0{transport: newTransport(opts)}
 }
 
-// NewDstackClient is the pre-0.6 name for NewDstackClientV0.
-//
-// Deprecated: use NewDstackClientV0, or NewDstackClientV1 for the current API.
-func NewDstackClient(opts ...DstackClientOption) *DstackClient {
-	return NewDstackClientV0(opts...)
-}
-
 // TlsKeyOption defines a function type for TLS key options
 type TlsKeyOption func(*tlsKeyOptions)
 
@@ -591,10 +586,14 @@ func (c *DstackClientV0) TdxQuote(ctx context.Context, reportData []byte, hashAl
 	return c.GetQuote(ctx, reportData)
 }
 
-// TappdClient is a deprecated wrapper around DstackClient for backward compatibility.
+// TappdClient is a deprecated wrapper around DstackClientV0 for backward
+// compatibility. It wraps v0 and not v1 because tappd predates both: its
+// callers expect the v0.5.11 method set, and v1 has no equivalent for the
+// tappd-era methods overridden below.
+//
 // Deprecated: Use DstackClient instead.
 type TappdClient struct {
-	*DstackClient
+	*DstackClientV0
 }
 
 // NewTappdClient creates a new deprecated TappdClient.
@@ -618,11 +617,11 @@ func NewTappdClient(opts ...DstackClientOption) *TappdClient {
 	// Add user-provided options
 	tappdOpts = append(tappdOpts, opts...)
 
-	client := NewDstackClient(tappdOpts...)
+	client := NewDstackClientV0(tappdOpts...)
 	client.logger.Warn("TappdClient is deprecated, please use DstackClient instead")
 
 	return &TappdClient{
-		DstackClient: client,
+		DstackClientV0: client,
 	}
 }
 

sdk/go/dstack/client.go

@@ -21,7 +21,7 @@ import (
 )
 
 func TestGetKey(t *testing.T) {
-	client := dstack.NewDstackClient()
+	client := dstack.NewDstackClientV0()
 	resp, err := client.GetKey(context.Background(), "/", "test", "ed25519")
 	if err != nil {
 		t.Fatal(err)
@@ -37,7 +37,7 @@ func TestGetKey(t *testing.T) {
 }
 
 func TestGetQuote(t *testing.T) {
-	client := dstack.NewDstackClient()
+	client := dstack.NewDstackClientV0()
 	resp, err := client.GetQuote(context.Background(), []byte("test"))
 	if err != nil {
 		t.Fatal(err)
@@ -59,7 +59,7 @@ func TestGetQuote(t *testing.T) {
 }
 
 func TestAttest(t *testing.T) {
-	client := dstack.NewDstackClient()
+	client := dstack.NewDstackClientV0()
 	resp, err := client.Attest(context.Background(), []byte("test"))
 	if err != nil {
 		t.Fatal(err)
@@ -111,7 +111,7 @@ func TestAttestRequestIsFrozenAtV0(t *testing.T) {
 }
 
 func TestGetTlsKey(t *testing.T) {
-	client := dstack.NewDstackClient()
+	client := dstack.NewDstackClientV0()
 	altNames := []string{"localhost"}
 	resp, err := client.GetTlsKey(
 		context.Background(),
@@ -177,7 +177,7 @@ func TestGetTlsKey(t *testing.T) {
 }
 
 func TestGetTlsKeyMinimalOptions(t *testing.T) {
-	client := dstack.NewDstackClient()
+	client := dstack.NewDstackClientV0()
 	// Test with minimal options (just subject)
 	resp, err := client.GetTlsKey(
 		context.Background(),
@@ -217,7 +217,7 @@ func TestGetTlsKeyMinimalOptions(t *testing.T) {
 }
 
 func TestGetTlsKeyServerOnly(t *testing.T) {
-	client := dstack.NewDstackClient()
+	client := dstack.NewDstackClientV0()
 	// Test with server auth only
 	resp, err := client.GetTlsKey(
 		context.Background(),
@@ -269,7 +269,7 @@ func TestGetTlsKeyServerOnly(t *testing.T) {
 }
 
 func TestGetTlsKeyClientOnly(t *testing.T) {
-	client := dstack.NewDstackClient()
+	client := dstack.NewDstackClientV0()
 	// Test with client auth only
 	resp, err := client.GetTlsKey(
 		context.Background(),
@@ -321,7 +321,7 @@ func TestGetTlsKeyClientOnly(t *testing.T) {
 }
 
 func TestGetTlsKeyWithMultipleAltNames(t *testing.T) {
-	client := dstack.NewDstackClient()
+	client := dstack.NewDstackClientV0()
 	// Test with multiple alternative names
 	altNames := []string{"example.com", "test.example.com"}
 	resp, err := client.GetTlsKey(
@@ -385,7 +385,7 @@ func parseCertificate(pemCert string) (*x509.Certificate, error) {
 }
 
 func TestInfo(t *testing.T) {
-	client := dstack.NewDstackClient()
+	client := dstack.NewDstackClientV0()
 	resp, err := client.Info(context.Background())
 	if err != nil {
 		t.Fatal(err)
@@ -443,7 +443,7 @@ func TestInfo(t *testing.T) {
 }
 
 func TestSignAndVerifyEd25519(t *testing.T) {
-	client := dstack.NewDstackClient()
+	client := dstack.NewDstackClientV0()
 	dataToSign := []byte("test message for ed25519")
 	algorithm := "ed25519"
 
@@ -486,7 +486,7 @@ func TestSignAndVerifyEd25519(t *testing.T) {
 }
 
 func TestSignAndVerifySecp256k1(t *testing.T) {
-	client := dstack.NewDstackClient()
+	client := dstack.NewDstackClientV0()
 	dataToSign := []byte("test message for secp256k1")
 	algorithm := "secp256k1"
 
@@ -522,7 +522,7 @@ func TestSignAndVerifySecp256k1(t *testing.T) {
 }
 
 func TestSignAndVerifySecp256k1Prehashed(t *testing.T) {
-	client := dstack.NewDstackClient()
+	client := dstack.NewDstackClientV0()
 	dataToSign := []byte("test message for secp256k1 prehashed")
 	digest := sha256.Sum256(dataToSign)
 	algorithm := "secp256k1_prehashed"
@@ -567,7 +567,7 @@ func TestSignAndVerifySecp256k1Prehashed(t *testing.T) {
 }
 
 func TestGetVersion(t *testing.T) {
-	client := dstack.NewDstackClient()
+	client := dstack.NewDstackClientV0()
 	resp, err := client.GetVersion(context.Background())
 	if err != nil {
 		t.Fatal(err)
@@ -579,7 +579,7 @@ func TestGetVersion(t *testing.T) {
 }
 
 func TestGetKeyK256Alias(t *testing.T) {
-	client := dstack.NewDstackClient()
+	client := dstack.NewDstackClientV0()
 
 	respK256, err := client.GetKey(context.Background(), "/test", "purpose", "k256")
 	if err != nil {
@@ -598,23 +598,23 @@ func TestGetKeyK256Alias(t *testing.T) {
 }
 
 func TestGetKeyUnsupportedAlgorithm(t *testing.T) {
-	client := dstack.NewDstackClient()
+	client := dstack.NewDstackClientV0()
 	_, err := client.GetKey(context.Background(), "/test", "purpose", "rsa")
 	if err == nil {
 		t.Fatal("expected error for unsupported algorithm")
 	}
 }
 
 func TestGetKeySecp256k1PrehashedRejected(t *testing.T) {
-	client := dstack.NewDstackClient()
+	client := dstack.NewDstackClientV0()
 	_, err := client.GetKey(context.Background(), "/test", "purpose", "secp256k1_prehashed")
 	if err == nil {
 		t.Fatal("expected error for secp256k1_prehashed in GetKey")
 	}
 }
 
 func TestGetKeyAlgorithmValidation(t *testing.T) {
-	client := dstack.NewDstackClient()
+	client := dstack.NewDstackClientV0()
 
 	// ed25519 should succeed (Version RPC is available on the simulator)
 	resp, err := client.GetKey(context.Background(), "/test", "purpose", "ed25519")
@@ -646,12 +646,11 @@ func TestEmitEventSurfacesTheRemovalMessage(t *testing.T) {
 	}
 }
 
-// NewDstackClient is kept as a deprecated alias for NewDstackClientV0, so code
-// written against the pre-0.6 SDK keeps compiling and keeps talking to the same
-// frozen surface.
-func TestDeprecatedAliasIsTheV0Client(t *testing.T) {
-	var client *dstack.DstackClientV0 = dstack.NewDstackClient()
+// The frozen surface stays reachable, but only under its explicit name now that
+// the unsuffixed client means v1.
+func TestV0RemainsAvailableUnderItsExplicitName(t *testing.T) {
+	var client *dstack.DstackClientV0 = dstack.NewDstackClientV0()
 	if !client.IsReachable(context.Background()) {
-		t.Error("expected the aliased client to reach the simulator")
+		t.Error("expected the v0 client to reach the simulator")
 	}
 }

sdk/go/dstack/client_test.go

@@ -132,13 +132,27 @@ type DstackClientV1 struct {
 	transport
 }
 
+// DstackClient is the recommended client, and it is v1: the unsuffixed name
+// tracks the current API rather than pinning the surface a caller happened to
+// start on. Code that used it for v0 fails to compile after the upgrade,
+// because the v1 signatures differ -- which is the point. A silent switch would
+// hand back different key material under the same call.
+type DstackClient = DstackClientV1
+
 // Creates a new DstackClientV1 instance based on the provided endpoint.
 // Endpoint resolution is identical to NewDstackClientV0 -- the two surfaces
 // share one socket and differ only in the URL path.
 func NewDstackClientV1(opts ...DstackClientOption) *DstackClientV1 {
 	return &DstackClientV1{transport: newTransport(opts)}
 }
 
+// NewDstackClient creates a client for the current API, which is v1. Use it
+// unless you specifically need the frozen v0.5.11 surface, in which case name
+// NewDstackClientV0 explicitly.
+func NewDstackClient(opts ...DstackClientOption) *DstackClient {
+	return NewDstackClientV1(opts...)
+}
+
 // decodeHexField decodes one hex-encoded protobuf `bytes` field, naming the
 // field so a malformed response says which one was wrong.
 func decodeHexField(name string, value string) ([]byte, error) {

sdk/go/dstack/client_v1.go

@@ -445,6 +445,29 @@ func TestV1MethodsPostUnderTheV1Prefix(t *testing.T) {
 	}
 }
 
+// The unsuffixed names are v1. The assignments below are half the assertion --
+// they do not compile if DstackClient is anything else -- and the round trip is
+// the other half: the default constructor must actually post under /v1.
+func TestUnsuffixedClientIsV1(t *testing.T) {
+	var _ *dstack.DstackClientV1 = (*dstack.DstackClient)(nil)
+
+	path := make(chan string, 1)
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		path <- r.URL.Path
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"version":"0.6.0","rev":"test"}`))
+	}))
+	defer server.Close()
+
+	client := dstack.NewDstackClient(dstack.WithEndpoint(server.URL))
+	if _, err := client.Version(context.Background()); err != nil {
+		t.Fatal(err)
+	}
+	if got := <-path; got != "/v1/Version" {
+		t.Errorf("expected the default client to speak v1, got %s", got)
+	}
+}
+
 // An agent that predates v1 has no /v1 mount, so it answers with a plain 404
 // rather than a prpc error. The client surfaces that rather than masking it.
 func TestV1AgainstAnAgentWithoutV1(t *testing.T) {

sdk/go/dstack/client_v1_test.go

@@ -24,7 +24,7 @@ func TestGetKeySignatureVerification(t *testing.T) {
 	expectedAppPubkey, _ := hex.DecodeString("02818494263695e8839122dbd88e281d7380622999df4e60a14befa0f2d096fc7c")
 	expectedKmsPubkey, _ := hex.DecodeString("0321529e458424ab1f710a3a57ec4dad2fb195ddca572f7469242ba6c7563085b6")
 
-	client := dstack.NewDstackClient()
+	client := dstack.NewDstackClientV0()
 	path := "/test/path"
 	purpose := "test-purpose"
 	resp, err := client.GetKey(context.Background(), path, purpose, "secp256k1")

sdk/go/dstack/client_web3_test.go

@@ -30,8 +30,9 @@ const sdkVersion = "0.6.0"
 
 // clientOptions holds what a caller may set at construction.
 //
-// Both NewDstackClientV0 and NewDstackClientV1 take the same options: a caller
-// moving to v1 changes the constructor and nothing else.
+// Every constructor -- NewDstackClient, NewDstackClientV1 and NewDstackClientV0
+// -- takes the same options, so a caller moving between surfaces changes the
+// constructor and nothing else.
 type clientOptions struct {
 	endpoint string
 	logger   *slog.Logger