@mytechtoday/augment-extensions 1.4.0 → 1.5.0

package/augment-extensions/coding-standards/go/rules/web/graceful-shutdown.md

@@ -0,0 +1,249 @@
+# Go Web Services - Graceful Shutdown
+
+## Overview
+
+Graceful shutdown ensures that a web service stops accepting new requests while completing in-flight requests before terminating. This document defines best practices for implementing graceful shutdown in Go web services.
+
+## Core Principles
+
+1. **Signal Handling**: Listen for OS signals (SIGINT, SIGTERM)
+2. **Connection Draining**: Complete in-flight requests before shutdown
+3. **Timeout Management**: Set reasonable shutdown timeouts
+4. **Resource Cleanup**: Close database connections, file handles, etc.
+5. **Health Check Updates**: Mark service as unhealthy during shutdown
+
+## Rules
+
+### GOL.3.1.4.1: Implement Signal-Based Shutdown
+
+**Rule**: Always implement graceful shutdown using OS signal handling.
+
+**Severity**: ERROR
+
+**Rationale**: Prevents data loss and ensures clean termination in production environments.
+
+**✅ Good**:
+```go
+func main() {
+    // Create server
+    srv := &http.Server{
+        Addr:    ":8080",
+        Handler: setupRoutes(),
+    }
+    
+    // Start server in goroutine
+    go func() {
+        log.Println("Server starting on :8080")
+        if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
+            log.Fatalf("Server failed: %v", err)
+        }
+    }()
+    
+    // Wait for interrupt signal
+    quit := make(chan os.Signal, 1)
+    signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
+    <-quit
+    
+    log.Println("Server shutting down...")
+    
+    // Create shutdown context with timeout
+    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+    defer cancel()
+    
+    // Attempt graceful shutdown
+    if err := srv.Shutdown(ctx); err != nil {
+        log.Fatalf("Server forced to shutdown: %v", err)
+    }
+    
+    log.Println("Server exited")
+}
+```
+
+**❌ Bad**:
+```go
+func main() {
+    // No graceful shutdown - server terminates immediately on Ctrl+C
+    http.ListenAndServe(":8080", setupRoutes())
+}
+```
+
+### GOL.3.1.4.2: Set Appropriate Shutdown Timeout
+
+**Rule**: Configure shutdown timeout based on expected request duration.
+
+**Severity**: WARNING
+
+**Rationale**: Too short causes request failures; too long delays deployment.
+
+**✅ Good**:
+```go
+const (
+    shutdownTimeout = 30 * time.Second  // For typical web services
+    // shutdownTimeout = 5 * time.Minute  // For long-running operations
+)
+
+func gracefulShutdown(srv *http.Server) error {
+    quit := make(chan os.Signal, 1)
+    signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
+    <-quit
+    
+    log.Println("Shutdown signal received")
+    
+    ctx, cancel := context.WithTimeout(context.Background(), shutdownTimeout)
+    defer cancel()
+    
+    return srv.Shutdown(ctx)
+}
+```
+
+### GOL.3.1.4.3: Clean Up Resources During Shutdown
+
+**Rule**: Close all resources (database connections, file handles) during shutdown.
+
+**Severity**: ERROR
+
+**Rationale**: Prevents resource leaks and ensures data consistency.
+
+**✅ Good**:
+```go
+type Server struct {
+    http   *http.Server
+    db     *sql.DB
+    cache  *redis.Client
+    logger *slog.Logger
+}
+
+func (s *Server) Shutdown(ctx context.Context) error {
+    s.logger.Info("Starting graceful shutdown")
+    
+    // Stop accepting new requests
+    if err := s.http.Shutdown(ctx); err != nil {
+        s.logger.Error("HTTP server shutdown error", "error", err)
+        return err
+    }
+    
+    // Close database connections
+    if err := s.db.Close(); err != nil {
+        s.logger.Error("Database close error", "error", err)
+    }
+    
+    // Close cache connections
+    if err := s.cache.Close(); err != nil {
+        s.logger.Error("Cache close error", "error", err)
+    }
+    
+    s.logger.Info("Shutdown complete")
+    return nil
+}
+
+func main() {
+    srv := NewServer()
+    
+    // Start server
+    go func() {
+        if err := srv.http.ListenAndServe(); err != nil && err != http.ErrServerClosed {
+            log.Fatal(err)
+        }
+    }()
+    
+    // Wait for signal
+    quit := make(chan os.Signal, 1)
+    signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
+    <-quit
+    
+    // Graceful shutdown
+    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+    defer cancel()
+    
+    if err := srv.Shutdown(ctx); err != nil {
+        log.Fatal(err)
+    }
+}
+```
+
+### GOL.3.1.4.4: Update Health Checks During Shutdown
+
+**Rule**: Mark service as unhealthy when shutdown begins.
+
+**Severity**: WARNING
+
+**Rationale**: Prevents load balancers from sending new requests during shutdown.
+
+**✅ Good**:
+```go
+type HealthChecker struct {
+    mu       sync.RWMutex
+    healthy  bool
+    shutdown bool
+}
+
+func (h *HealthChecker) SetHealthy(healthy bool) {
+    h.mu.Lock()
+    defer h.mu.Unlock()
+    h.healthy = healthy
+}
+
+func (h *HealthChecker) SetShutdown() {
+    h.mu.Lock()
+    defer h.mu.Unlock()
+    h.shutdown = true
+}
+
+func (h *HealthChecker) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+    h.mu.RLock()
+    defer h.mu.RUnlock()
+    
+    if h.shutdown {
+        w.WriteHeader(http.StatusServiceUnavailable)
+        json.NewEncoder(w).Encode(map[string]string{
+            "status": "shutting_down",
+        })
+        return
+    }
+    
+    if !h.healthy {
+        w.WriteHeader(http.StatusServiceUnavailable)
+        json.NewEncoder(w).Encode(map[string]string{
+            "status": "unhealthy",
+        })
+        return
+    }
+    
+    w.WriteHeader(http.StatusOK)
+    json.NewEncoder(w).Encode(map[string]string{
+        "status": "healthy",
+    })
+}
+
+func main() {
+    health := &HealthChecker{healthy: true}
+    
+    http.Handle("/health", health)
+    http.Handle("/api/", apiHandler)
+    
+    srv := &http.Server{Addr: ":8080"}
+    
+    go srv.ListenAndServe()
+    
+    quit := make(chan os.Signal, 1)
+    signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
+    <-quit
+    
+    // Mark as shutting down
+    health.SetShutdown()
+    
+    // Wait for load balancer to detect unhealthy status
+    time.Sleep(5 * time.Second)
+    
+    // Proceed with shutdown
+    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+    defer cancel()
+    srv.Shutdown(ctx)
+}
+```
+
+## References
+
+- [Go HTTP Server Shutdown](https://pkg.go.dev/net/http#Server.Shutdown)
+- [Graceful Shutdown Patterns](https://medium.com/honestbee-tw-engineer/gracefully-shutdown-in-go-http-server-5f5e6b83da5a)
+

package/augment-extensions/coding-standards/go/rules/web/http-handlers.md

@@ -0,0 +1,164 @@
+# Go Web Services - HTTP Handlers
+
+## Overview
+
+HTTP handlers are the core of web services in Go. This document defines best practices for implementing HTTP handlers that are robust, maintainable, and idiomatic.
+
+## Core Principles
+
+1. **Context Usage**: Always use `context.Context` for request-scoped values and cancellation
+2. **Error Handling**: Return errors explicitly, use `http.Error` for client errors
+3. **Status Codes**: Use appropriate HTTP status codes (2xx, 4xx, 5xx)
+4. **Request Validation**: Validate all inputs before processing
+5. **Response Formatting**: Use consistent response formats (JSON, XML, etc.)
+
+## Rules
+
+### GOL.3.1.1: Use Standard Handler Interfaces
+
+**Rule**: Implement handlers using `http.Handler` or `http.HandlerFunc` interfaces.
+
+**Severity**: ERROR
+
+**Rationale**: Standard interfaces ensure compatibility with middleware and routing libraries.
+
+**✅ Good**:
+```go
+// Using http.HandlerFunc
+func handleUser(w http.ResponseWriter, r *http.Request) {
+    ctx := r.Context()
+    userID := r.URL.Query().Get("id")
+    
+    user, err := getUserByID(ctx, userID)
+    if err != nil {
+        http.Error(w, "User not found", http.StatusNotFound)
+        return
+    }
+    
+    json.NewEncoder(w).Encode(user)
+}
+
+// Using http.Handler
+type UserHandler struct {
+    db *sql.DB
+}
+
+func (h *UserHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+    // Handler implementation
+}
+```
+
+**❌ Bad**:
+```go
+// Non-standard signature
+func handleUser(userID string) (User, error) {
+    // Cannot be used directly with http.ServeMux
+}
+```
+
+### GOL.3.1.2: Always Use Context for Request-Scoped Values
+
+**Rule**: Use `r.Context()` for request-scoped values, timeouts, and cancellation.
+
+**Severity**: ERROR
+
+**Rationale**: Context enables proper timeout handling, cancellation propagation, and request tracing.
+
+**✅ Good**:
+```go
+func handleCreateUser(w http.ResponseWriter, r *http.Request) {
+    ctx := r.Context()
+    
+    // Add timeout to context
+    ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
+    defer cancel()
+    
+    var user User
+    if err := json.NewDecoder(r.Body).Decode(&user); err != nil {
+        http.Error(w, "Invalid request body", http.StatusBadRequest)
+        return
+    }
+    
+    // Pass context to database operations
+    if err := createUser(ctx, &user); err != nil {
+        if errors.Is(err, context.DeadlineExceeded) {
+            http.Error(w, "Request timeout", http.StatusRequestTimeout)
+            return
+        }
+        http.Error(w, "Internal server error", http.StatusInternalServerError)
+        return
+    }
+    
+    w.WriteHeader(http.StatusCreated)
+    json.NewEncoder(w).Encode(user)
+}
+```
+
+**❌ Bad**:
+```go
+func handleCreateUser(w http.ResponseWriter, r *http.Request) {
+    // Not using context - no timeout or cancellation support
+    var user User
+    json.NewDecoder(r.Body).Decode(&user)
+    createUser(&user) // No context passed
+    json.NewEncoder(w).Encode(user)
+}
+```
+
+### GOL.3.1.3: Use Appropriate HTTP Status Codes
+
+**Rule**: Return correct HTTP status codes for different scenarios.
+
+**Severity**: WARNING
+
+**Rationale**: Proper status codes enable clients to handle responses correctly.
+
+**Status Code Guidelines**:
+- `200 OK`: Successful GET, PUT, PATCH
+- `201 Created`: Successful POST creating a resource
+- `204 No Content`: Successful DELETE
+- `400 Bad Request`: Invalid client input
+- `401 Unauthorized`: Authentication required
+- `403 Forbidden`: Authenticated but not authorized
+- `404 Not Found`: Resource doesn't exist
+- `409 Conflict`: Resource conflict (e.g., duplicate)
+- `422 Unprocessable Entity`: Validation errors
+- `500 Internal Server Error`: Server-side errors
+- `503 Service Unavailable`: Temporary unavailability
+
+**✅ Good**:
+```go
+func handleUpdateUser(w http.ResponseWriter, r *http.Request) {
+    ctx := r.Context()
+    userID := chi.URLParam(r, "id")
+    
+    var updates UserUpdate
+    if err := json.NewDecoder(r.Body).Decode(&updates); err != nil {
+        http.Error(w, "Invalid JSON", http.StatusBadRequest)
+        return
+    }
+    
+    user, err := updateUser(ctx, userID, updates)
+    if err != nil {
+        switch {
+        case errors.Is(err, ErrUserNotFound):
+            http.Error(w, "User not found", http.StatusNotFound)
+        case errors.Is(err, ErrValidation):
+            http.Error(w, err.Error(), http.StatusUnprocessableEntity)
+        default:
+            http.Error(w, "Internal error", http.StatusInternalServerError)
+        }
+        return
+    }
+    
+    w.WriteHeader(http.StatusOK)
+    json.NewEncoder(w).Encode(user)
+}
+```
+
+## References
+
+- [Effective Go - Web Servers](https://golang.org/doc/effective_go#web_server)
+- [Go net/http package](https://pkg.go.dev/net/http)
+- [HTTP Status Codes](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status)
+

package/augment-extensions/coding-standards/go/rules/web/middleware.md

@@ -0,0 +1,234 @@
+# Go Web Services - Middleware Patterns
+
+## Overview
+
+Middleware provides a powerful way to add cross-cutting concerns to HTTP handlers. This document defines best practices for implementing and using middleware in Go web services.
+
+## Core Principles
+
+1. **Composability**: Middleware should be composable and chainable
+2. **Single Responsibility**: Each middleware should do one thing well
+3. **Context Propagation**: Use context to pass values between middleware
+4. **Error Handling**: Handle errors gracefully and consistently
+5. **Performance**: Minimize overhead in hot paths
+
+## Rules
+
+### GOL.3.1.2.1: Use Standard Middleware Pattern
+
+**Rule**: Implement middleware using the standard `func(http.Handler) http.Handler` pattern.
+
+**Severity**: ERROR
+
+**Rationale**: Standard pattern ensures compatibility with all routing libraries and middleware chains.
+
+**✅ Good**:
+```go
+// Standard middleware signature
+func loggingMiddleware(next http.Handler) http.Handler {
+    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+        start := time.Now()
+        
+        // Call next handler
+        next.ServeHTTP(w, r)
+        
+        // Log after handler completes
+        log.Printf("%s %s %v", r.Method, r.URL.Path, time.Since(start))
+    })
+}
+
+// Usage
+http.Handle("/api/", loggingMiddleware(apiHandler))
+```
+
+**❌ Bad**:
+```go
+// Non-standard signature - not composable
+func loggingMiddleware(w http.ResponseWriter, r *http.Request, handler http.Handler) {
+    start := time.Now()
+    handler.ServeHTTP(w, r)
+    log.Printf("%s %s %v", r.Method, r.URL.Path, time.Since(start))
+}
+```
+
+### GOL.3.1.2.2: Authentication Middleware
+
+**Rule**: Implement authentication middleware that validates credentials and adds user context.
+
+**Severity**: ERROR
+
+**Rationale**: Centralized authentication ensures consistent security across all protected endpoints.
+
+**✅ Good**:
+```go
+type contextKey string
+
+const userContextKey contextKey = "user"
+
+func authMiddleware(next http.Handler) http.Handler {
+    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+        token := r.Header.Get("Authorization")
+        if token == "" {
+            http.Error(w, "Unauthorized", http.StatusUnauthorized)
+            return
+        }
+        
+        // Validate token
+        user, err := validateToken(r.Context(), token)
+        if err != nil {
+            http.Error(w, "Invalid token", http.StatusUnauthorized)
+            return
+        }
+        
+        // Add user to context
+        ctx := context.WithValue(r.Context(), userContextKey, user)
+        next.ServeHTTP(w, r.WithContext(ctx))
+    })
+}
+
+// Helper to extract user from context
+func getUserFromContext(ctx context.Context) (*User, bool) {
+    user, ok := ctx.Value(userContextKey).(*User)
+    return user, ok
+}
+```
+
+### GOL.3.1.2.3: Request Logging Middleware
+
+**Rule**: Log all requests with method, path, status code, duration, and request ID.
+
+**Severity**: WARNING
+
+**Rationale**: Comprehensive logging enables debugging, monitoring, and audit trails.
+
+**✅ Good**:
+```go
+type responseWriter struct {
+    http.ResponseWriter
+    statusCode int
+    written    int64
+}
+
+func (rw *responseWriter) WriteHeader(code int) {
+    rw.statusCode = code
+    rw.ResponseWriter.WriteHeader(code)
+}
+
+func (rw *responseWriter) Write(b []byte) (int, error) {
+    n, err := rw.ResponseWriter.Write(b)
+    rw.written += int64(n)
+    return n, err
+}
+
+func requestLoggingMiddleware(logger *slog.Logger) func(http.Handler) http.Handler {
+    return func(next http.Handler) http.Handler {
+        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+            start := time.Now()
+            requestID := uuid.New().String()
+            
+            // Add request ID to context
+            ctx := context.WithValue(r.Context(), "request_id", requestID)
+            
+            // Wrap response writer to capture status code
+            rw := &responseWriter{
+                ResponseWriter: w,
+                statusCode:     http.StatusOK,
+            }
+            
+            // Call next handler
+            next.ServeHTTP(rw, r.WithContext(ctx))
+            
+            // Log request details
+            logger.Info("request completed",
+                "request_id", requestID,
+                "method", r.Method,
+                "path", r.URL.Path,
+                "status", rw.statusCode,
+                "duration_ms", time.Since(start).Milliseconds(),
+                "bytes_written", rw.written,
+                "remote_addr", r.RemoteAddr,
+            )
+        })
+    }
+}
+```
+
+### GOL.3.1.2.4: Panic Recovery Middleware
+
+**Rule**: Always include panic recovery middleware to prevent server crashes.
+
+**Severity**: ERROR
+
+**Rationale**: Unhandled panics crash the entire server; recovery middleware ensures graceful error handling.
+
+**✅ Good**:
+```go
+func recoveryMiddleware(logger *slog.Logger) func(http.Handler) http.Handler {
+    return func(next http.Handler) http.Handler {
+        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+            defer func() {
+                if err := recover(); err != nil {
+                    // Log panic with stack trace
+                    logger.Error("panic recovered",
+                        "error", err,
+                        "path", r.URL.Path,
+                        "stack", string(debug.Stack()),
+                    )
+                    
+                    // Return 500 to client
+                    http.Error(w, "Internal Server Error", http.StatusInternalServerError)
+                }
+            }()
+            
+            next.ServeHTTP(w, r)
+        })
+    }
+}
+```
+
+### GOL.3.1.2.5: Metrics Middleware
+
+**Rule**: Instrument HTTP handlers with Prometheus metrics for monitoring.
+
+**Severity**: WARNING
+
+**✅ Good**:
+```go
+var (
+    httpRequestsTotal = promauto.NewCounterVec(
+        prometheus.CounterOpts{
+            Name: "http_requests_total",
+            Help: "Total number of HTTP requests",
+        },
+        []string{"method", "path", "status"},
+    )
+    
+    httpRequestDuration = promauto.NewHistogramVec(
+        prometheus.HistogramOpts{
+            Name:    "http_request_duration_seconds",
+            Help:    "HTTP request duration in seconds",
+            Buckets: prometheus.DefBuckets,
+        },
+        []string{"method", "path"},
+    )
+)
+
+func metricsMiddleware(next http.Handler) http.Handler {
+    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+        start := time.Now()
+        rw := &responseWriter{ResponseWriter: w, statusCode: http.StatusOK}
+        
+        next.ServeHTTP(rw, r)
+        
+        duration := time.Since(start).Seconds()
+        httpRequestsTotal.WithLabelValues(r.Method, r.URL.Path, strconv.Itoa(rw.statusCode)).Inc()
+        httpRequestDuration.WithLabelValues(r.Method, r.URL.Path).Observe(duration)
+    })
+}
+```
+
+## References
+
+- [Go Middleware Patterns](https://www.alexedwards.net/blog/making-and-using-middleware)
+- [Effective Go - Web Servers](https://golang.org/doc/effective_go#web_server)
+