APIVersion: Add API Version to protobuf (#911)

ryantxu · web-flow · commit 878555a0c4af · 2024-05-08T17:01:47.000+03:00
diff --git a/backend/common.go b/backend/common.go
@@ -37,6 +37,10 @@ type AppInstanceSettings struct {
 
 	// Updated is the last time this plugin instance's configuration was updated.
 	Updated time.Time
+
+	// The API Version when settings were saved
+	// NOTE: this may be older than the current version
+	APIVersion string
 }
 
 // HTTPClientOptions creates httpclient.Options based on settings.
@@ -57,7 +61,7 @@ func (s *AppInstanceSettings) HTTPClientOptions(_ context.Context) (httpclient.O
 // In Grafana a data source instance is a data source plugin of certain
 // type that have been configured and created in a Grafana organization.
 type DataSourceInstanceSettings struct {
-	// ID is the Grafana assigned numeric identifier of the the data source instance.
+	// Deprecated ID is the Grafana assigned numeric identifier of the the data source instance.
 	ID int64
 
 	// UID is the Grafana assigned string identifier of the the data source instance.
@@ -98,6 +102,10 @@ type DataSourceInstanceSettings struct {
 
 	// Updated is the last time the configuration for the data source instance was updated.
 	Updated time.Time
+
+	// The API Version when settings were saved
+	// NOTE: this may be older than the current version
+	APIVersion string
 }
 
 // HTTPClientOptions creates httpclient.Options based on settings.
@@ -178,6 +186,9 @@ type PluginContext struct {
 	// UserAgent is the user agent of the Grafana server that initiated the gRPC request.
 	// Will only be set if request is made from Grafana v10.2.0 or later.
 	UserAgent *useragent.UserAgent
+
+	// The requested API version
+	APIVersion string
 }
 
 func setCustomOptionsFromHTTPSettings(opts *httpclient.Options, httpSettings *HTTPSettings) {
diff --git a/backend/convert_from_protobuf.go b/backend/convert_from_protobuf.go
@@ -46,6 +46,7 @@ func (f ConvertFromProtobuf) AppInstanceSettings(proto *pluginv2.AppInstanceSett
 		JSONData:                proto.JsonData,
 		DecryptedSecureJSONData: proto.DecryptedSecureJsonData,
 		Updated:                 time.Unix(0, proto.LastUpdatedMS*int64(time.Millisecond)),
+		APIVersion:              proto.ApiVersion,
 	}
 }
 
@@ -68,6 +69,7 @@ func (f ConvertFromProtobuf) DataSourceInstanceSettings(proto *pluginv2.DataSour
 		JSONData:                proto.JsonData,
 		DecryptedSecureJSONData: proto.DecryptedSecureJsonData,
 		Updated:                 time.Unix(0, proto.LastUpdatedMS*int64(time.Millisecond)),
+		APIVersion:              proto.ApiVersion,
 	}
 }
 
@@ -89,6 +91,7 @@ func (f ConvertFromProtobuf) PluginContext(proto *pluginv2.PluginContext) Plugin
 		OrgID:                      proto.OrgId,
 		PluginID:                   proto.PluginId,
 		PluginVersion:              proto.PluginVersion,
+		APIVersion:                 proto.ApiVersion,
 		User:                       f.User(proto.User),
 		AppInstanceSettings:        f.AppInstanceSettings(proto.AppInstanceSettings),
 		DataSourceInstanceSettings: f.DataSourceInstanceSettings(proto.DataSourceInstanceSettings, proto.PluginId),
diff --git a/backend/convert_from_protobuf_test.go b/backend/convert_from_protobuf_test.go
@@ -106,6 +106,7 @@ var protoAppInstanceSettings = &pluginv2.AppInstanceSettings{
 	JsonData:                []byte(`{ "foo": "gpp"`),
 	DecryptedSecureJsonData: map[string]string{"secret": "quiet"},
 	LastUpdatedMS:           lastUpdatedMS,
+	ApiVersion:              "v1beta2",
 }
 
 func TestConvertFromProtobufAppInstanceSettings(t *testing.T) {
@@ -135,6 +136,7 @@ func TestConvertFromProtobufAppInstanceSettings(t *testing.T) {
 	requireCounter.Equal(t, json.RawMessage(protoAIS.JsonData), sdkAIS.JSONData)
 	requireCounter.Equal(t, map[string]string{"secret": "quiet"}, sdkAIS.DecryptedSecureJSONData)
 	requireCounter.Equal(t, lastUpdatedTime, sdkAIS.Updated)
+	requireCounter.Equal(t, protoAIS.ApiVersion, sdkAIS.APIVersion)
 
 	require.Equal(t, requireCounter.Count, sdkWalker.FieldCount, "untested fields in conversion")
 }
@@ -151,6 +153,7 @@ var protoDataSourceInstanceSettings = &pluginv2.DataSourceInstanceSettings{
 	JsonData:                []byte(`{ "foo": "gpp"`),
 	DecryptedSecureJsonData: map[string]string{"secret": "quiet"},
 	LastUpdatedMS:           lastUpdatedMS,
+	ApiVersion:              "v0alpha3",
 }
 
 func TestConvertFromProtobufDataSourceInstanceSettings(t *testing.T) {
@@ -189,6 +192,7 @@ func TestConvertFromProtobufDataSourceInstanceSettings(t *testing.T) {
 	requireCounter.Equal(t, json.RawMessage(protoDSIS.JsonData), sdkDSIS.JSONData)
 	requireCounter.Equal(t, map[string]string{"secret": "quiet"}, sdkDSIS.DecryptedSecureJSONData)
 	requireCounter.Equal(t, lastUpdatedTime, sdkDSIS.Updated)
+	requireCounter.Equal(t, protoDSIS.ApiVersion, sdkDSIS.APIVersion)
 
 	require.Equal(t, requireCounter.Count, sdkWalker.FieldCount, "untested fields in conversion")
 }
@@ -208,7 +212,8 @@ var protoPluginContext = &pluginv2.PluginContext{
 	GrafanaConfig: map[string]string{
 		"foo": "bar",
 	},
-	UserAgent: "Grafana/10.0.0 (linux; amd64)",
+	UserAgent:  "Grafana/10.0.0 (linux; amd64)",
+	ApiVersion: "v0alpha1",
 }
 
 func TestConvertFromProtobufPluginContext(t *testing.T) {
@@ -248,13 +253,16 @@ func TestConvertFromProtobufPluginContext(t *testing.T) {
 	requireCounter.Equal(t, json.RawMessage(protoCtx.AppInstanceSettings.JsonData), sdkCtx.AppInstanceSettings.JSONData)
 	requireCounter.Equal(t, map[string]string{"secret": "quiet"}, sdkCtx.AppInstanceSettings.DecryptedSecureJSONData)
 	requireCounter.Equal(t, time.Unix(0, 86400*2*1e9), sdkCtx.AppInstanceSettings.Updated)
+	requireCounter.Equal(t, protoCtx.AppInstanceSettings.ApiVersion, sdkCtx.AppInstanceSettings.APIVersion)
 
 	// Datasource Instance Settings
 	requireCounter.Equal(t, protoCtx.DataSourceInstanceSettings.Name, sdkCtx.DataSourceInstanceSettings.Name)
 	requireCounter.Equal(t, protoCtx.DataSourceInstanceSettings.Id, sdkCtx.DataSourceInstanceSettings.ID)
 	requireCounter.Equal(t, protoCtx.DataSourceInstanceSettings.Uid, sdkCtx.DataSourceInstanceSettings.UID)
+	requireCounter.Equal(t, protoCtx.DataSourceInstanceSettings.ApiVersion, sdkCtx.DataSourceInstanceSettings.APIVersion)
 	requireCounter.Equal(t, protoCtx.PluginId, sdkCtx.DataSourceInstanceSettings.Type)
 	requireCounter.Equal(t, protoCtx.PluginVersion, sdkCtx.PluginVersion)
+	requireCounter.Equal(t, protoCtx.ApiVersion, sdkCtx.APIVersion)
 	requireCounter.Equal(t, protoCtx.DataSourceInstanceSettings.Url, sdkCtx.DataSourceInstanceSettings.URL)
 	requireCounter.Equal(t, protoCtx.DataSourceInstanceSettings.User, sdkCtx.DataSourceInstanceSettings.User)
 	requireCounter.Equal(t, protoCtx.DataSourceInstanceSettings.Database, sdkCtx.DataSourceInstanceSettings.Database)
@@ -396,6 +404,7 @@ func TestConvertFromProtobufQueryDataRequest(t *testing.T) {
 	// PluginContext
 	requireCounter.Equal(t, protoQDR.PluginContext.OrgId, sdkQDR.PluginContext.OrgID)
 	requireCounter.Equal(t, protoQDR.PluginContext.PluginId, sdkQDR.PluginContext.PluginID)
+	requireCounter.Equal(t, protoQDR.PluginContext.ApiVersion, sdkQDR.PluginContext.APIVersion)
 	// User
 	requireCounter.Equal(t, protoQDR.PluginContext.User.Login, sdkQDR.PluginContext.User.Login)
 	requireCounter.Equal(t, protoQDR.PluginContext.User.Name, sdkQDR.PluginContext.User.Name)
@@ -406,11 +415,13 @@ func TestConvertFromProtobufQueryDataRequest(t *testing.T) {
 	requireCounter.Equal(t, json.RawMessage(protoQDR.PluginContext.AppInstanceSettings.JsonData), sdkQDR.PluginContext.AppInstanceSettings.JSONData)
 	requireCounter.Equal(t, map[string]string{"secret": "quiet"}, sdkQDR.PluginContext.AppInstanceSettings.DecryptedSecureJSONData)
 	requireCounter.Equal(t, time.Unix(0, 86400*2*1e9), sdkQDR.PluginContext.AppInstanceSettings.Updated)
+	requireCounter.Equal(t, protoQDR.PluginContext.AppInstanceSettings.ApiVersion, sdkQDR.PluginContext.AppInstanceSettings.APIVersion)
 
 	// Datasource Instance Settings
 	requireCounter.Equal(t, protoQDR.PluginContext.DataSourceInstanceSettings.Name, sdkQDR.PluginContext.DataSourceInstanceSettings.Name)
 	requireCounter.Equal(t, protoQDR.PluginContext.DataSourceInstanceSettings.Id, sdkQDR.PluginContext.DataSourceInstanceSettings.ID)
 	requireCounter.Equal(t, protoQDR.PluginContext.DataSourceInstanceSettings.Uid, sdkQDR.PluginContext.DataSourceInstanceSettings.UID)
+	requireCounter.Equal(t, protoQDR.PluginContext.DataSourceInstanceSettings.ApiVersion, sdkQDR.PluginContext.DataSourceInstanceSettings.APIVersion)
 	requireCounter.Equal(t, protoQDR.PluginContext.PluginId, sdkQDR.PluginContext.DataSourceInstanceSettings.Type)
 	requireCounter.Equal(t, protoQDR.PluginContext.PluginVersion, sdkQDR.PluginContext.PluginVersion)
 	requireCounter.Equal(t, protoQDR.PluginContext.DataSourceInstanceSettings.Url, sdkQDR.PluginContext.DataSourceInstanceSettings.URL)
diff --git a/backend/convert_to_protobuf.go b/backend/convert_to_protobuf.go
@@ -45,6 +45,7 @@ func (t ConvertToProtobuf) AppInstanceSettings(s *AppInstanceSettings) *pluginv2
 		JsonData:                s.JSONData,
 		DecryptedSecureJsonData: s.DecryptedSecureJSONData,
 		LastUpdatedMS:           s.Updated.UnixNano() / int64(time.Millisecond),
+		ApiVersion:              s.APIVersion,
 	}
 }
 
@@ -66,6 +67,7 @@ func (t ConvertToProtobuf) DataSourceInstanceSettings(s *DataSourceInstanceSetti
 		JsonData:                s.JSONData,
 		DecryptedSecureJsonData: s.DecryptedSecureJSONData,
 		LastUpdatedMS:           s.Updated.UnixNano() / int64(time.Millisecond),
+		ApiVersion:              s.APIVersion,
 	}
 }
 
@@ -84,6 +86,7 @@ func (t ConvertToProtobuf) PluginContext(pluginCtx PluginContext) *pluginv2.Plug
 		OrgId:                      pluginCtx.OrgID,
 		PluginId:                   pluginCtx.PluginID,
 		PluginVersion:              pluginCtx.PluginVersion,
+		ApiVersion:                 pluginCtx.APIVersion,
 		User:                       t.User(pluginCtx.User),
 		AppInstanceSettings:        t.AppInstanceSettings(pluginCtx.AppInstanceSettings),
 		DataSourceInstanceSettings: t.DataSourceInstanceSettings(pluginCtx.DataSourceInstanceSettings),
diff --git a/genproto/pluginv2/backend.pb.go b/genproto/pluginv2/backend.pb.go
diff --git a/proto/backend.proto b/proto/backend.proto
@@ -11,9 +11,14 @@ message AppInstanceSettings {
   bytes jsonData = 3;
   map<string,string> decryptedSecureJsonData = 4;
   int64 lastUpdatedMS = 5;
+
+  // The API version when the settings were saved
+  // NOTE: this may be an older version than the current apiVersion
+  string apiVersion = 6;
 }
 
 message DataSourceInstanceSettings {
+  // Deprecatd: Internal ID, do not use this for anythign important
   int64 id = 1;
   string name = 2;
   string url = 3;
@@ -23,8 +28,16 @@ message DataSourceInstanceSettings {
   string basicAuthUser = 7;
   bytes jsonData = 8;
   map<string,string> decryptedSecureJsonData = 9;
+
+  // timestamp when the settings where last changed
   int64 lastUpdatedMS = 10;
+
+  // Datasoruce unique ID (within an org/stack namespace)
   string uid = 11;
+
+  // The API version when the settings were saved.
+  // NOTE: this may be an older version than the current apiVersion
+  string apiVersion = 12;
 }
 
 message User {
@@ -68,6 +81,9 @@ message PluginContext {
 
   // The user agent of the Grafana server that initiated the gRPC request.
   string userAgent = 8;
+
+  // The API version that initiated a request
+  string apiVersion = 9;
 }
 
 //---------------------------------------------------------

Original file line number	Diff line number	Diff line change
`@@ -46,6 +46,7 @@ func (f ConvertFromProtobuf) AppInstanceSettings(proto *pluginv2.AppInstanceSett`
`46`	`46`	`JSONData: proto.JsonData,`
`47`	`47`	`DecryptedSecureJSONData: proto.DecryptedSecureJsonData,`
`48`	`48`	`Updated: time.Unix(0, proto.LastUpdatedMS*int64(time.Millisecond)),`
	`49`	`+ APIVersion: proto.ApiVersion,`
`49`	`50`	`}`
`50`	`51`	`}`
`51`	`52`
`@@ -68,6 +69,7 @@ func (f ConvertFromProtobuf) DataSourceInstanceSettings(proto *pluginv2.DataSour`
`68`	`69`	`JSONData: proto.JsonData,`
`69`	`70`	`DecryptedSecureJSONData: proto.DecryptedSecureJsonData,`
`70`	`71`	`Updated: time.Unix(0, proto.LastUpdatedMS*int64(time.Millisecond)),`
	`72`	`+ APIVersion: proto.ApiVersion,`
`71`	`73`	`}`
`72`	`74`	`}`
`73`	`75`
`@@ -89,6 +91,7 @@ func (f ConvertFromProtobuf) PluginContext(proto *pluginv2.PluginContext) Plugin`
`89`	`91`	`OrgID: proto.OrgId,`
`90`	`92`	`PluginID: proto.PluginId,`
`91`	`93`	`PluginVersion: proto.PluginVersion,`
	`94`	`+ APIVersion: proto.ApiVersion,`
`92`	`95`	`User: f.User(proto.User),`
`93`	`96`	`AppInstanceSettings: f.AppInstanceSettings(proto.AppInstanceSettings),`
`94`	`97`	`DataSourceInstanceSettings: f.DataSourceInstanceSettings(proto.DataSourceInstanceSettings, proto.PluginId),`
Original file line number	Diff line number	Diff line change
`@@ -45,6 +45,7 @@ func (t ConvertToProtobuf) AppInstanceSettings(s AppInstanceSettings) pluginv2`
`45`	`45`	`JsonData: s.JSONData,`
`46`	`46`	`DecryptedSecureJsonData: s.DecryptedSecureJSONData,`
`47`	`47`	`LastUpdatedMS: s.Updated.UnixNano() / int64(time.Millisecond),`
	`48`	`+ ApiVersion: s.APIVersion,`
`48`	`49`	`}`
`49`	`50`	`}`
`50`	`51`
`@@ -66,6 +67,7 @@ func (t ConvertToProtobuf) DataSourceInstanceSettings(s *DataSourceInstanceSetti`
`66`	`67`	`JsonData: s.JSONData,`
`67`	`68`	`DecryptedSecureJsonData: s.DecryptedSecureJSONData,`
`68`	`69`	`LastUpdatedMS: s.Updated.UnixNano() / int64(time.Millisecond),`
	`70`	`+ ApiVersion: s.APIVersion,`
`69`	`71`	`}`
`70`	`72`	`}`
`71`	`73`
`@@ -84,6 +86,7 @@ func (t ConvertToProtobuf) PluginContext(pluginCtx PluginContext) *pluginv2.Plug`
`84`	`86`	`OrgId: pluginCtx.OrgID,`
`85`	`87`	`PluginId: pluginCtx.PluginID,`
`86`	`88`	`PluginVersion: pluginCtx.PluginVersion,`
	`89`	`+ ApiVersion: pluginCtx.APIVersion,`
`87`	`90`	`User: t.User(pluginCtx.User),`
`88`	`91`	`AppInstanceSettings: t.AppInstanceSettings(pluginCtx.AppInstanceSettings),`
`89`	`92`	`DataSourceInstanceSettings: t.DataSourceInstanceSettings(pluginCtx.DataSourceInstanceSettings),`