Enhance documentation across storage and service layers

Added detailed comments for functions, methods, and structs in storage implementations (CouchDB, MongoDB, In-Memory) and gRPC server. Improved clarity on parameter usage, return values, and overall design choices to facilitate better understanding and maintainability.

Author: starichkov

app.go

@@ -1,3 +1,4 @@
+// Package main contains the core application logic for the Notes API.
 package main
 
 import (
@@ -18,129 +19,180 @@ import (
 	"github.com/go-chi/chi/v5/middleware"
 )
 
-// App represents the main application
+// App represents the main application that coordinates all components:
+// - Storage backend (in-memory, CouchDB, or MongoDB)
+// - REST API server
+// - gRPC API server
+// It handles initialization, running, and graceful shutdown of these components.
 type App struct {
-	storage    storage.NoteStorage
-	restServer *http.Server
-	grpcServer *grpc.Server
-	config     *Config
+	storage    storage.NoteStorage // Interface for storing and retrieving notes
+	restServer *http.Server        // HTTP server for REST API
+	grpcServer *grpc.Server        // gRPC server for gRPC API
+	config     *Config             // Application configuration
 }
 
-// NewApp creates a new App instance
+// NewApp creates a new App instance with the provided configuration.
+// It only initializes the App struct with the configuration; actual component
+// initialization happens in the Initialize method.
 func NewApp(config *Config) *App {
 	return &App{
 		config: config,
 	}
 }
 
-// Initialize sets up the application components
+// Initialize sets up the application components in the following order:
+// 1. Initializes the appropriate storage backend based on configuration
+// 2. Sets up the REST server with routes
+// 3. Sets up the gRPC server
+// This method must be called before Run.
 func (a *App) Initialize(ctx context.Context) error {
-	// Initialize storage
+	// Initialize storage backend (in-memory, CouchDB, or MongoDB)
+	// based on the configuration
 	storage, err := a.initializeStorage(ctx)
 	if err != nil {
 		return fmt.Errorf("failed to initialize storage: %w", err)
 	}
 	a.storage = storage
 
-	// Setup servers
+	// Setup the REST and gRPC servers with the initialized storage
 	a.restServer = a.setupRESTServer()
 	a.grpcServer = a.setupGRPCServer()
 
 	return nil
 }
 
-// Run starts the application servers
+// Run starts the application servers and performs the following steps:
+// 1. Starts the REST and gRPC servers in separate goroutines
+// 2. Creates sample notes in the storage
+// 3. Waits for a shutdown signal (e.g., Ctrl+C)
+// This method blocks until the application is shut down.
 func (a *App) Run(ctx context.Context) error {
-	// Start servers
+	// Start the REST and gRPC servers in separate goroutines
 	if err := a.startServers(ctx); err != nil {
 		return fmt.Errorf("failed to start servers: %w", err)
 	}
 
-	// Create sample notes
+	// Create sample notes in the storage for demonstration purposes
 	if err := a.createSampleNotes(ctx); err != nil {
 		return fmt.Errorf("failed to create sample notes: %w", err)
 	}
 
-	// Wait for shutdown signal
+	// Wait for shutdown signal (context cancellation)
+	// This blocks until the context is canceled (e.g., by Ctrl+C)
 	return a.waitForShutdown(ctx)
 }
 
-// initializeStorage initializes the storage based on configuration
+// initializeStorage initializes the storage backend based on the configuration.
+// It supports three types of storage:
+// - "couchdb": Uses CouchDB as the storage backend
+// - "mongodb": Uses MongoDB as the storage backend
+// - Any other value (default): Uses in-memory storage
+//
+// If connecting to CouchDB or MongoDB fails, it falls back to in-memory storage
+// to ensure the application can still run.
 func (a *App) initializeStorage(ctx context.Context) (storage.NoteStorage, error) {
 	var noteStorage storage.NoteStorage
 	var err error
 
+	// Choose the storage backend based on the configuration
 	switch a.config.StorageType {
 	case "couchdb":
+		// Try to connect to CouchDB
 		log.Printf("Connecting to CouchDB at %s, database: %s", a.config.CouchDBURL, a.config.CouchDBName)
 		noteStorage, err = storage.NewCouchDBStorage(a.config.CouchDBURL, a.config.CouchDBName)
 		if err != nil {
+			// If connection fails, log the error and fall back to in-memory storage
 			log.Printf("Failed to connect to CouchDB: %v, falling back to in-memory storage", err)
 			noteStorage = storage.NewInMemoryStorage()
 		} else {
 			log.Println("Successfully connected to CouchDB")
 		}
 	case "mongodb":
+		// Try to connect to MongoDB
 		log.Printf("Connecting to MongoDB at %s, database: %s, collection: %s",
 			a.config.MongoDBURI, a.config.MongoDBName, a.config.MongoDBCollection)
 		noteStorage, err = storage.NewMongoDBStorage(a.config.MongoDBURI, a.config.MongoDBName, a.config.MongoDBCollection)
 		if err != nil {
+			// If connection fails, log the error and fall back to in-memory storage
 			log.Printf("Failed to connect to MongoDB: %v, falling back to in-memory storage", err)
 			noteStorage = storage.NewInMemoryStorage()
 		} else {
 			log.Println("Successfully connected to MongoDB")
 		}
 	default:
+		// Use in-memory storage by default
 		log.Println("Using in-memory storage")
 		noteStorage = storage.NewInMemoryStorage()
 	}
 
 	return noteStorage, nil
 }
 
-// setupRESTServer creates and configures the REST server
+// setupRESTServer creates and configures the REST API server.
+// It sets up:
+// 1. A new REST handler with the storage backend
+// 2. A Chi router with middleware for logging and panic recovery
+// 3. Routes for the REST API endpoints
+// 4. An HTTP server with the configured port
 func (a *App) setupRESTServer() *http.Server {
+	// Create a new REST handler with the storage backend
 	restHandler := rest.NewHandler(a.storage)
+
+	// Create a new Chi router
+	// Chi is a lightweight, idiomatic and composable router for Go HTTP services
 	r := chi.NewRouter()
 
-	// Middleware
-	r.Use(middleware.Logger)
-	r.Use(middleware.Recoverer)
+	// Add middleware to the router
+	r.Use(middleware.Logger)    // Log all HTTP requests
+	r.Use(middleware.Recoverer) // Recover from panics without crashing the server
 
+	// Register the API routes with the router
+	// This sets up endpoints like GET /api/notes, POST /api/notes, etc.
 	restHandler.RegisterRoutes(r)
 
+	// Create and return an HTTP server with the configured port and router
 	return &http.Server{
-		Addr:    a.config.RESTPort,
-		Handler: r,
+		Addr:    a.config.RESTPort, // Port to listen on (e.g., ":8080")
+		Handler: r,                 // The router that handles requests
 	}
 }
 
-// setupGRPCServer creates and configures the gRPC server
+// setupGRPCServer creates and configures the gRPC server.
+// It extracts the port number from the configuration and creates a new gRPC server
+// with the storage backend and port.
 func (a *App) setupGRPCServer() *grpc.Server {
-	// Remove the colon prefix and convert to int
-	port := 8081 // Default port
+	// Extract the port number from the configuration
+	// The port might be in the format ":8081", so we need to remove the colon prefix
+	port := 8081 // Default port if parsing fails
 	if a.config.GRPCPort != "" {
 		portStr := strings.TrimPrefix(a.config.GRPCPort, ":")
 		if p, err := strconv.Atoi(portStr); err == nil {
 			port = p
 		}
 	}
+
+	// Create and return a new gRPC server with the storage backend and port
 	return grpc.NewServer(a.storage, port)
 }
 
-// startServers starts the REST and gRPC servers in separate goroutines
+// startServers starts the REST and gRPC servers in separate goroutines.
+// This method doesn't block; it returns immediately after starting the servers.
+// Each server runs in its own goroutine (a lightweight thread) to allow them to run concurrently.
 func (a *App) startServers(ctx context.Context) error {
-	// Start REST server
+	// Start REST server in a separate goroutine
 	go func() {
 		log.Printf("Starting REST server on %s", a.config.RESTPort)
+		// ListenAndServe blocks until the server is stopped or encounters an error
 		if err := a.restServer.ListenAndServe(); err != nil && err != http.ErrServerClosed {
+			// Log any error that isn't just the server being closed normally
 			log.Printf("REST server failed: %v", err)
 		}
 	}()
 
-	// Start gRPC server
+	// Start gRPC server in a separate goroutine
 	go func() {
 		log.Printf("Starting gRPC server on %s", a.config.GRPCPort)
+		// Start blocks until the server is stopped or encounters an error
 		if err := a.grpcServer.Start(); err != nil {
 			log.Printf("gRPC server failed: %v", err)
 		}
@@ -149,31 +201,40 @@ func (a *App) startServers(ctx context.Context) error {
 	return nil
 }
 
-// waitForShutdown waits for interrupt signal and gracefully shuts down the servers
+// waitForShutdown waits for the context to be canceled (e.g., by an interrupt signal)
+// and then gracefully shuts down the servers.
+// This method blocks until the context is canceled and the servers are shut down.
 func (a *App) waitForShutdown(ctx context.Context) error {
+	// Block until the context is canceled (e.g., by Ctrl+C)
 	<-ctx.Done()
 	log.Println("Shutting down servers...")
 
-	// Create a new context with timeout for shutdown
+	// Create a new context with a 5-second timeout for the shutdown process
+	// This ensures that shutdown doesn't hang indefinitely
 	shutdownCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
-	defer cancel()
+	defer cancel() // Ensure the context is canceled when the function returns
 
-	// Shutdown the REST server
+	// Gracefully shut down the REST server
+	// This allows in-flight requests to complete before shutting down
 	if err := a.restServer.Shutdown(shutdownCtx); err != nil {
 		log.Printf("REST server shutdown failed: %v", err)
 	}
 
-	// Close the storage
+	// Close the storage connection
+	// This ensures any database connections are properly closed
 	if err := a.storage.Close(shutdownCtx); err != nil {
 		log.Printf("Storage shutdown failed: %v", err)
 	}
 
 	log.Println("Servers stopped")
+	// Return the original context's error (typically context.Canceled)
 	return ctx.Err()
 }
 
-// createSampleNotes creates some sample notes in the storage
+// createSampleNotes creates some sample notes in the storage for demonstration purposes.
+// This provides initial data for users to see when they first access the API.
 func (a *App) createSampleNotes(ctx context.Context) error {
+	// Define a list of sample notes to create
 	notes := []struct {
 		title   string
 		content string
@@ -192,41 +253,60 @@ func (a *App) createSampleNotes(ctx context.Context) error {
 		},
 	}
 
+	// Create each sample note in the storage
 	for _, note := range notes {
+		// Create a new Note object with the title and content
 		n := model.NewNote(note.title, note.content)
+
+		// Try to save the note to the storage
 		err := a.storage.Create(ctx, n)
 		if err != nil {
-			// Ignore duplicate key errors (MongoDB error code 11000)
+			// If the note already exists (duplicate key error), skip it and continue
 			if isDuplicateKeyError(err) {
 				continue
 			}
+			// For any other error, return it
 			return fmt.Errorf("failed to create sample note: %w", err)
 		}
-		// Add a small delay to ensure unique IDs when using timestamp-based ID generation
+
+		// Add a small delay between creating notes
+		// This ensures unique IDs when using timestamp-based ID generation
+		// (since our ID generation uses the current timestamp)
 		time.Sleep(1 * time.Millisecond)
 	}
 
 	return nil
 }
 
-// isDuplicateKeyError checks if the error is a duplicate key error
+// isDuplicateKeyError checks if the error is a duplicate key error from any of the
+// supported storage backends (MongoDB, CouchDB, or in-memory).
+//
+// Different databases return different error messages for duplicate key errors,
+// so this function normalizes them to a single boolean result.
 func isDuplicateKeyError(err error) bool {
 	if err == nil {
 		return false
 	}
 	errStr := err.Error()
 
-	// MongoDB duplicate key error
+	// Check for MongoDB duplicate key error
+	// MongoDB returns error code E11000 for duplicate key errors
 	if strings.Contains(errStr, "E11000 duplicate key error") {
 		return true
 	}
-	// CouchDB duplicate key error
+
+	// Check for CouchDB duplicate key error
+	// CouchDB returns "conflict" or "Document update conflict" for duplicate key errors
 	if strings.Contains(errStr, "conflict") || strings.Contains(errStr, "Document update conflict") {
 		return true
 	}
-	// In-memory storage duplicate key error
+
+	// Check for in-memory storage duplicate key error
+	// Our in-memory implementation returns "note already exists" for duplicate key errors
 	if strings.Contains(errStr, "note already exists") {
 		return true
 	}
+
+	// If none of the above patterns match, it's not a duplicate key error
 	return false
 }