Add brick api-docs, and examples (#499)

Co-authored-by: mirkoCrobu <mirkocrobu@NB-0531.localdomain>
Co-authored-by: Alessio Perugini <alessio@perugini.xyz>

Author: 3 people

internal/api/docs/openapi.yaml

@@ -976,10 +976,17 @@ components:
       type: object
     BrickDetailsResult:
       properties:
+        api_docs_path:
+          type: string
         author:
           type: string
         category:
           type: string
+        code_examples:
+          items:
+            $ref: '#/components/schemas/CodeExample'
+          nullable: true
+          type: array
         description:
           type: string
         id:
@@ -1073,6 +1080,11 @@ components:
           nullable: true
           type: string
       type: object
+    CodeExample:
+      properties:
+        path:
+          type: string
+      type: object
     ConfigDirectories:
       properties:
         apps:

internal/api/handlers/bricks.go

@@ -236,15 +236,15 @@ func HandleBrickDelete(
 		if err != nil {
 			switch {
 			case errors.Is(err, bricks.ErrBrickNotFound):
-				details := fmt.Sprintf("brick not found for id %q", id)
-				render.EncodeResponse(w, http.StatusNotFound, models.ErrorResponse{Details: details})
+				slog.Error("brick not found", "id", id, "error", err)
+				render.EncodeResponse(w, http.StatusNotFound, models.ErrorResponse{Details: "brick not found"})
 
 			case errors.Is(err, bricks.ErrCannotSaveBrick):
-				log.Printf("Internal error saving brick instance %s: %v", id, err)
+				slog.Error("Internal error saving brick instance", "id", id, "error", err)
 				render.EncodeResponse(w, http.StatusInternalServerError, models.ErrorResponse{Details: "unable to delete the app"})
 
 			default:
-				log.Printf("Unexpected error deleting brick %s: %v", id, err)
+				slog.Error("Unexpected error deleting brick", "id", id, "error", err)
 				render.EncodeResponse(w, http.StatusInternalServerError, models.ErrorResponse{Details: "A server error occurred while finalizing the deletion."})
 			}
 			return

internal/e2e/client/client.gen.go

@@ -6,6 +6,7 @@ import (
 	"maps"
 	"slices"
 
+	"github.com/arduino/go-paths-helper"
 	"go.bug.st/f"
 
 	"github.com/bcmi-labs/orchestrator/internal/orchestrator/app"
@@ -129,15 +130,32 @@ func (s *Service) BricksDetails(id string) (BrickDetailsResult, error) {
 		return BrickDetailsResult{}, fmt.Errorf("cannot open docs for brick %s: %w", id, err)
 	}
 
+	apiDocsPath, err := s.staticStore.GetBrickApiDocPathFromID(brick.ID)
+	if err != nil {
+		return BrickDetailsResult{}, fmt.Errorf("cannot open api-docs for brick %s: %w", id, err)
+	}
+
+	examplePaths, err := s.staticStore.GetBrickCodeExamplesPathFromID(brick.ID)
+	if err != nil {
+		return BrickDetailsResult{}, fmt.Errorf("cannot open code examples for brick %s: %w", id, err)
+	}
+	codeExamples := f.Map(examplePaths, func(p *paths.Path) CodeExample {
+		return CodeExample{
+			Path: p.String(),
+		}
+	})
+
 	return BrickDetailsResult{
-		ID:          id,
-		Name:        brick.Name,
-		Author:      "Arduino", // TODO: for now we only support our bricks
-		Description: brick.Description,
-		Category:    brick.Category,
-		Status:      "installed", // For now every Arduino brick are installed
-		Variables:   variables,
-		Readme:      readme,
+		ID:           id,
+		Name:         brick.Name,
+		Author:       "Arduino", // TODO: for now we only support our bricks
+		Description:  brick.Description,
+		Category:     brick.Category,
+		Status:       "installed", // For now every Arduino brick are installed
+		Variables:    variables,
+		Readme:       readme,
+		ApiDocsPath:  apiDocsPath,
+		CodeExamples: codeExamples,
 	}, nil
 }
 

internal/orchestrator/bricks/bricks.go

@@ -34,20 +34,25 @@ type BrickVariable struct {
 	Required     bool   `json:"required"`
 }
 
+type CodeExample struct {
+	Path string `json:"path"`
+}
 type AppReference struct {
 	ID   string `json:"id"`
 	Name string `json:"name"`
 	Icon string `json:"icon"`
 }
 
 type BrickDetailsResult struct {
-	ID          string                   `json:"id"`
-	Name        string                   `json:"name"`
-	Author      string                   `json:"author"`
-	Description string                   `json:"description"`
-	Category    string                   `json:"category"`
-	Status      string                   `json:"status"`
-	Variables   map[string]BrickVariable `json:"variables,omitempty"`
-	Readme      string                   `json:"readme"`
-	UsedByApps  []AppReference           `json:"used_by_apps"`
+	ID           string                   `json:"id"`
+	Name         string                   `json:"name"`
+	Author       string                   `json:"author"`
+	Description  string                   `json:"description"`
+	Category     string                   `json:"category"`
+	Status       string                   `json:"status"`
+	Variables    map[string]BrickVariable `json:"variables,omitempty"`
+	Readme       string                   `json:"readme"`
+	ApiDocsPath  string                   `json:"api_docs_path"`
+	CodeExamples []CodeExample            `json:"code_examples"`
+	UsedByApps   []AppReference           `json:"used_by_apps"`
 }

internal/orchestrator/bricks/types.go

@@ -11,18 +11,22 @@ import (
 )
 
 type StaticStore struct {
-	baseDir     string
-	composePath string
-	docsPath    string
-	assetsPath  *paths.Path
+	baseDir          string
+	composePath      string
+	docsPath         string
+	assetsPath       *paths.Path
+	apiDocsPath      string
+	codeExamplesPath string
 }
 
 func NewStaticStore(baseDir string) *StaticStore {
 	return &StaticStore{
-		baseDir:     baseDir,
-		composePath: filepath.Join(baseDir, "compose"),
-		docsPath:    filepath.Join(baseDir, "docs"),
-		assetsPath:  paths.New(baseDir),
+		baseDir:          baseDir,
+		composePath:      filepath.Join(baseDir, "compose"),
+		docsPath:         filepath.Join(baseDir, "docs"),
+		apiDocsPath:      filepath.Join(baseDir, "api-docs"),
+		codeExamplesPath: filepath.Join(baseDir, "examples"),
+		assetsPath:       paths.New(baseDir),
 	}
 }
 
@@ -63,3 +67,24 @@ func (s *StaticStore) GetBrickComposeFilePathFromID(brickID string) (*paths.Path
 	}
 	return paths.New(s.composePath, namespace, brickName, "brick_compose.yaml"), nil
 }
+
+func (s *StaticStore) GetBrickApiDocPathFromID(brickID string) (string, error) {
+	namespace, brickName, ok := strings.Cut(brickID, ":")
+	if !ok {
+		return "", errors.New("invalid ID")
+	}
+	return filepath.Join(s.apiDocsPath, namespace, "app_bricks", brickName, "API.md"), nil
+}
+
+func (s *StaticStore) GetBrickCodeExamplesPathFromID(brickID string) (paths.PathList, error) {
+	namespace, brickName, ok := strings.Cut(brickID, ":")
+	if !ok {
+		return nil, errors.New("invalid ID")
+	}
+	targetDir := paths.New(s.codeExamplesPath, namespace, brickName)
+	dirEntries, err := targetDir.ReadDir()
+	if err != nil {
+		return nil, fmt.Errorf("cannot read examples directory %q: %w", targetDir, err)
+	}
+	return dirEntries, nil
+}

internal/store/store.go

@@ -8,10 +8,26 @@ import (
 
 var s = NewStaticStore("0.1.16")
 
-func BenchmarkNew(b *testing.B) {
+func BenchmarkGetBrickReadmeFromID(b *testing.B) {
 	for b.Loop() {
 		x, err := s.GetBrickReadmeFromID("arduino:dbstorage_sqlstore")
 		require.NoError(b, err)
 		require.NotEmpty(b, x)
 	}
 }
+
+func BenchmarkGetBrickApiDocsPathFromID(b *testing.B) {
+	for b.Loop() {
+		x, err := s.GetBrickApiDocPathFromID("arduino:dbstorage_sqlstore")
+		require.NoError(b, err)
+		require.NotEmpty(b, x)
+	}
+}
+
+func BenchmarkGetBrickCodeExamplesPathFromID(b *testing.B) {
+	for b.Loop() {
+		x, err := s.GetBrickCodeExamplesPathFromID("arduino:weather_forecast")
+		require.NoError(b, err)
+		require.NotEmpty(b, x)
+	}
+}