Implement a "settings" (key-value) API (#685)

Co-authored-by: mirkoCrobu <mirkocrobu@NB-0531.localdomain>
Co-authored-by: lucarin91 <lucarin@protonmail.com>

Author: 3 people

cmd/gendoc/docs.go

@@ -15,6 +15,7 @@ import (
 	"golang.org/x/text/language"
 
 	"github.com/bcmi-labs/orchestrator/internal/api/handlers"
+	"github.com/bcmi-labs/orchestrator/internal/api/models"
 	"github.com/bcmi-labs/orchestrator/internal/orchestrator"
 	"github.com/bcmi-labs/orchestrator/internal/orchestrator/app"
 	"github.com/bcmi-labs/orchestrator/internal/orchestrator/bricks"
@@ -28,6 +29,7 @@ const (
 	BrickTag       Tag = "Brick"
 	AIModelsTag    Tag = "AIModels"
 	SystemTag      Tag = "System"
+	Property       Tag = "Property"
 )
 
 var validTags = []Tag{ApplicationTag, BrickTag, AIModelsTag, SystemTag}
@@ -187,6 +189,7 @@ func NewOpenApiGenerator(version string) *Generator {
 	// to manually remove the pkg prefix.
 	reflector.DefaultOptions = append(reflector.DefaultOptions,
 		jsonschema.InterceptSchema(func(params jsonschema.InterceptSchemaParams) (stop bool, err error) {
+
 			if params.Value.Type() == reflect.TypeOf(orchestrator.Status("")) {
 				params.Schema.WithRef("#/components/schemas/Status")
 				return true, nil
@@ -249,6 +252,90 @@ type ErrorResponse struct {
 func (g *Generator) InitOperations() {
 
 	operations := []OperationConfig{
+		{
+			OperationId: "DeleteProperty",
+			Method:      http.MethodDelete,
+			Path:        "/v1/properties/{key}",
+			Request: (*struct {
+				ID string `path:"key" description:"property key."`
+			})(nil),
+			CustomSuccessResponse: &CustomResponseDef{
+				ContentType:   "application/json",
+				DataStructure: nil,
+				Description:   "Successful response",
+				StatusCode:    http.StatusNoContent,
+			},
+			Description: "Delete the property by the provided key.",
+			Summary:     "Delete property by key",
+			Tags:        []Tag{Property},
+			PossibleErrors: []ErrorResponse{
+				{StatusCode: http.StatusNotFound, Reference: "#/components/responses/NotFound"},
+				{StatusCode: http.StatusBadRequest, Reference: "#/components/responses/BadRequest"},
+				{StatusCode: http.StatusInternalServerError, Reference: "#/components/responses/InternalServerError"},
+			},
+		},
+		{
+			OperationId: "UpdateProperty",
+			Method:      http.MethodPut,
+			Path:        "/v1/properties/{key}",
+			Parameters: (*struct {
+				ID string `path:"key" description:"property key."`
+			})(nil),
+			Request: []byte{},
+			CustomSuccessResponse: &CustomResponseDef{
+				ContentType:   "application/octet-stream",
+				DataStructure: []byte{},
+				Description:   "Successful response",
+				StatusCode:    http.StatusOK,
+			},
+			Description: "Update or create a new property.",
+			Summary:     "Upsert property",
+			Tags:        []Tag{Property},
+			PossibleErrors: []ErrorResponse{
+				{StatusCode: http.StatusNotFound, Reference: "#/components/responses/NotFound"},
+				{StatusCode: http.StatusBadRequest, Reference: "#/components/responses/BadRequest"},
+				{StatusCode: http.StatusInternalServerError, Reference: "#/components/responses/InternalServerError"},
+			},
+		},
+		{
+			OperationId: "GetProperty",
+			Method:      http.MethodGet,
+			Path:        "/v1/properties/{key}",
+			Parameters: (*struct {
+				ID string `path:"key" description:"property key."`
+			})(nil),
+			CustomSuccessResponse: &CustomResponseDef{
+				ContentType:   "application/octet-stream",
+				DataStructure: []byte{},
+				Description:   "Successful response",
+				StatusCode:    http.StatusOK,
+			},
+			Description: "Return a single property by the provided key.",
+			Summary:     "Get property by key",
+			Tags:        []Tag{Property},
+			PossibleErrors: []ErrorResponse{
+				{StatusCode: http.StatusNotFound, Reference: "#/components/responses/NotFound"},
+				{StatusCode: http.StatusBadRequest, Reference: "#/components/responses/BadRequest"},
+				{StatusCode: http.StatusInternalServerError, Reference: "#/components/responses/InternalServerError"},
+			},
+		},
+		{
+			OperationId: "GetPropertyKeys",
+			Method:      http.MethodGet,
+			Path:        "/v1/properties",
+			CustomSuccessResponse: &CustomResponseDef{
+				ContentType:   "application/json",
+				DataStructure: models.PropertyKeysResponse{},
+				Description:   "Successful response",
+				StatusCode:    http.StatusOK,
+			},
+			Description: "Return the list of system properties.",
+			Summary:     "Get system properties",
+			Tags:        []Tag{Property},
+			PossibleErrors: []ErrorResponse{
+				{StatusCode: http.StatusInternalServerError, Reference: "#/components/responses/InternalServerError"},
+			},
+		},
 		{
 			OperationId: "getAppPorts",
 			Method:      http.MethodGet,

go.mod

@@ -30,6 +30,7 @@ require (
 	github.com/fatih/color v1.18.0
 	github.com/fsnotify/fsnotify v1.9.0
 	github.com/goccy/go-yaml v1.18.0
+	github.com/gofrs/flock v0.12.1
 	github.com/google/go-cmp v0.7.0
 	github.com/google/renameio/v2 v2.0.0
 	github.com/gorilla/websocket v1.5.0
@@ -131,7 +132,6 @@ require (
 	github.com/go-openapi/jsonreference v0.20.2 // indirect
 	github.com/go-openapi/swag v0.23.0 // indirect
 	github.com/go-viper/mapstructure/v2 v2.3.0 // indirect
-	github.com/gofrs/flock v0.12.1 // indirect
 	github.com/gofrs/uuid/v5 v5.3.2 // indirect
 	github.com/gogo/protobuf v1.3.2 // indirect
 	github.com/golang-jwt/jwt/v5 v5.2.2 // indirect

internal/api/api.go

@@ -43,6 +43,11 @@ func NewHTTPRouter(
 	mux.Handle("GET /v1/bricks", handlers.HandleBrickList(brickService))
 	mux.Handle("GET /v1/bricks/{brickID}", handlers.HandleBrickDetails(brickService))
 
+	mux.Handle("GET /v1/properties", handlers.HandlePropertyKeys(cfg))
+	mux.Handle("GET /v1/properties/{key}", handlers.HandlePropertyGet(cfg))
+	mux.Handle("PUT /v1/properties/{key}", handlers.HandlePropertyUpsert(cfg))
+	mux.Handle("DELETE /v1/properties/{key}", handlers.HandlePropertyDelete(cfg))
+
 	mux.Handle("GET /v1/system/update/check", handlers.HandleCheckUpgradable(updater))
 	mux.Handle("GET /v1/system/update/events", handlers.HandleUpdateEvents(updater))
 	mux.Handle("PUT /v1/system/update/apply", handlers.HandleUpdateApply(updater))

internal/api/docs/openapi.yaml

@@ -651,6 +651,112 @@ paths:
       summary: Get AI model details
       tags:
       - AIModels
+  /v1/properties:
+    get:
+      description: Return the list of system properties.
+      operationId: GetPropertyKeys
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PropertyKeysResponse'
+          description: Successful response
+        "500":
+          $ref: '#/components/responses/InternalServerError'
+      summary: Get system properties
+      tags:
+      - Property
+  /v1/properties/{key}:
+    delete:
+      description: Delete the property by the provided key.
+      operationId: DeleteProperty
+      parameters:
+      - description: property key.
+        in: path
+        name: key
+        required: true
+        schema:
+          description: property key.
+          type: string
+      responses:
+        "204":
+          content:
+            application/json:
+              schema:
+                type: string
+          description: Successful response
+        "400":
+          $ref: '#/components/responses/BadRequest'
+        "404":
+          $ref: '#/components/responses/NotFound'
+        "500":
+          $ref: '#/components/responses/InternalServerError'
+      summary: Delete property by key
+      tags:
+      - Property
+    get:
+      description: Return a single property by the provided key.
+      operationId: GetProperty
+      parameters:
+      - description: property key.
+        in: path
+        name: key
+        required: true
+        schema:
+          description: property key.
+          type: string
+      responses:
+        "200":
+          content:
+            application/octet-stream:
+              schema:
+                format: base64
+                type: string
+          description: Successful response
+        "400":
+          $ref: '#/components/responses/BadRequest'
+        "404":
+          $ref: '#/components/responses/NotFound'
+        "500":
+          $ref: '#/components/responses/InternalServerError'
+      summary: Get property by key
+      tags:
+      - Property
+    put:
+      description: Update or create a new property.
+      operationId: UpdateProperty
+      parameters:
+      - description: property key.
+        in: path
+        name: key
+        required: true
+        schema:
+          description: property key.
+          type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              format: base64
+              type: string
+      responses:
+        "200":
+          content:
+            application/octet-stream:
+              schema:
+                format: base64
+                type: string
+          description: Successful response
+        "400":
+          $ref: '#/components/responses/BadRequest'
+        "404":
+          $ref: '#/components/responses/NotFound'
+        "500":
+          $ref: '#/components/responses/InternalServerError'
+      summary: Upsert property
+      tags:
+      - Property
   /v1/system/resources:
     get:
       description: Returns the system resources usage, such as memory, disk and CPU.
@@ -1172,6 +1278,14 @@ components:
           example: brick:data-storage
           type: string
       type: object
+    PropertyKeysResponse:
+      properties:
+        keys:
+          items:
+            type: string
+          nullable: true
+          type: array
+      type: object
     Status:
       description: Application status
       enum:

internal/api/handlers/properties.go

@@ -0,0 +1,100 @@
+package handlers
+
+import (
+	"errors"
+	"io"
+	"log/slog"
+	"net/http"
+
+	"github.com/bcmi-labs/orchestrator/internal/api/models"
+	"github.com/bcmi-labs/orchestrator/internal/orchestrator/config"
+	properties "github.com/bcmi-labs/orchestrator/internal/orchestrator/system_properties"
+	"github.com/bcmi-labs/orchestrator/pkg/render"
+)
+
+func HandlePropertyKeys(cfg config.Configuration) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		propertyList, err := properties.ReadPropertyKeys(cfg.DataDir().Join("properties.msgpack").String())
+		if err != nil {
+			slog.Error("Unable to retrieve list", slog.String("error", err.Error()))
+			render.EncodeResponse(w, http.StatusInternalServerError, models.ErrorResponse{Details: "unable to find the list"})
+			return
+		}
+		render.EncodeResponse(w, http.StatusOK, models.PropertyKeysResponse{Keys: propertyList})
+	}
+}
+
+func HandlePropertyGet(cfg config.Configuration) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		key := r.PathValue("key")
+
+		property, found, err := properties.GetProperty(cfg.DataDir().Join("properties.msgpack").String(), key)
+		if err != nil {
+			if errors.Is(err, properties.ErrInvalidKey) {
+				render.EncodeResponse(w, http.StatusBadRequest, models.ErrorResponse{Details: err.Error()})
+				return
+			}
+			slog.Error("Unable to retrieve property", "key", key, "error", err.Error())
+			render.EncodeResponse(w, http.StatusInternalServerError, models.ErrorResponse{Details: "Unable to retrieve property"})
+			return
+		}
+
+		if !found {
+			render.EncodeResponse(w, http.StatusNotFound, nil)
+			return
+		}
+
+		render.EncodeByteResponse(w, http.StatusOK, property)
+	}
+}
+
+func HandlePropertyUpsert(cfg config.Configuration) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		key := r.PathValue("key")
+
+		reqBody, err := io.ReadAll(r.Body)
+		if err != nil {
+			slog.Warn("Failed to read request body", "error", err.Error())
+			render.EncodeResponse(w, http.StatusBadRequest, models.ErrorResponse{Details: "invalid body"})
+			return
+		}
+		defer r.Body.Close()
+		if len(reqBody) == 0 {
+			render.EncodeResponse(w, http.StatusBadRequest, models.ErrorResponse{Details: "body cannot be empty"})
+			return
+		}
+
+		err = properties.UpsertProperty(cfg.DataDir().Join("properties.msgpack").String(), key, reqBody)
+		if err != nil {
+			if errors.Is(err, properties.ErrInvalidKey) {
+				render.EncodeResponse(w, http.StatusBadRequest, models.ErrorResponse{Details: err.Error()})
+				return
+			}
+			slog.Error("Failed to upsert property", "key", key, "error", err.Error())
+			render.EncodeResponse(w, http.StatusInternalServerError, models.ErrorResponse{Details: "failed to update property"})
+			return
+		}
+		render.EncodeByteResponse(w, http.StatusOK, reqBody)
+	}
+}
+
+func HandlePropertyDelete(cfg config.Configuration) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		key := r.PathValue("key")
+		found, err := properties.DeleteProperty(cfg.DataDir().Join("properties.msgpack").String(), key)
+		if err != nil {
+			if errors.Is(err, properties.ErrInvalidKey) {
+				render.EncodeResponse(w, http.StatusBadRequest, models.ErrorResponse{Details: err.Error()})
+				return
+			}
+			slog.Error("Failed to delete property", "key", key, "error", err.Error())
+			render.EncodeResponse(w, http.StatusInternalServerError, models.ErrorResponse{Details: "failed to delete property"})
+			return
+		}
+		if !found {
+			render.EncodeResponse(w, http.StatusNotFound, nil)
+			return
+		}
+		render.EncodeResponse(w, http.StatusNoContent, nil)
+	}
+}

internal/api/models/properties.go

@@ -0,0 +1,5 @@
+package models
+
+type PropertyKeysResponse struct {
+	Keys []string `json:"keys"`
+}