APIVersion: Add API Version to protobuf (#911)

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) {

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),

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)

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),

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;
 }
 
 //---------------------------------------------------------