Controller info endpoint and API integration examples (#75)

* Controller API: introduce controller's information endpoint

* Prevent generation of empty events after channel closure

* Allow events to be buffered in the events channel

* Controller API: introduce controller's information endpoint[1]

* IntegrationGuide.md: a couple of Python and Golang examples

* Rephrase a sentence

Co-authored-by: Fedor Korotkov <fedor.korotkov@gmail.com>

---------

Co-authored-by: Fedor Korotkov <fedor.korotkov@gmail.com>

internal/controller/api.go

@@ -30,7 +30,8 @@ func (controller *Controller) initAPI() *gin.Engine {
 	// Auth
 	v1.Use(controller.authenticateMiddleware)
 
-	// A way to for the clients to check that the API is working
+	// OpenAPI docs/spec (if enabled) and a way to for the clients
+	// to check that the API is working
 	v1.GET("/", func(c *gin.Context) {
 		if controller.enableSwaggerDocs {
 			middleware.SwaggerUI(middleware.SwaggerUIOpts{
@@ -41,13 +42,17 @@ func (controller *Controller) initAPI() *gin.Engine {
 			c.Status(http.StatusOK)
 		}
 	})
-
 	if controller.enableSwaggerDocs {
 		v1.GET("/openapi.yaml", func(c *gin.Context) {
 			c.Data(200, "text/yaml", api.Spec)
 		})
 	}
 
+	// Controller information
+	v1.GET("/controller/info", func(c *gin.Context) {
+		controller.controllerInfo(c).Respond(c)
+	})
+
 	// Service accounts
 	v1.POST("/service-accounts", func(c *gin.Context) {
 		controller.createServiceAccount(c).Respond(c)

internal/controller/api_controller.go

@@ -0,0 +1,22 @@
+package controller
+
+import (
+	"github.com/cirruslabs/orchard/internal/responder"
+	"github.com/cirruslabs/orchard/internal/version"
+	v1pkg "github.com/cirruslabs/orchard/pkg/resource/v1"
+	"github.com/gin-gonic/gin"
+	"net/http"
+)
+
+func (controller *Controller) controllerInfo(ctx *gin.Context) responder.Responder {
+	// Only require the service account to be valid,
+	// no roles are needed to query this endpoint
+	if responder := controller.authorize(ctx); responder != nil {
+		return responder
+	}
+
+	return responder.JSON(http.StatusOK, &v1pkg.ControllerInfo{
+		Version: version.Version,
+		Commit:  version.Commit,
+	})
+}

internal/controller/api_vms.go

@@ -161,6 +161,7 @@ func (controller *Controller) deleteVM(ctx *gin.Context) responder.Responder {
 		return responder.Code(http.StatusOK)
 	})
 }
+
 func (controller *Controller) appendVMEvents(ctx *gin.Context) responder.Responder {
 	if responder := controller.authorize(ctx, v1.ServiceAccountRoleComputeWrite); responder != nil {
 		return responder