@mytechtoday/augment-extensions 1.4.0 → 1.5.0

package/augment-extensions/coding-standards/go/examples/web/http-server.go

@@ -0,0 +1,224 @@
+// Package main demonstrates a production-ready HTTP server with best practices
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"log/slog"
+	"net/http"
+	"os"
+	"os/signal"
+	"strconv"
+	"syscall"
+	"time"
+
+	"github.com/go-chi/chi/v5"
+	"github.com/go-chi/chi/v5/middleware"
+)
+
+// User represents a user in the system
+type User struct {
+	ID        int64     `json:"id"`
+	Name      string    `json:"name"`
+	Email     string    `json:"email"`
+	CreatedAt time.Time `json:"created_at"`
+}
+
+// UserService handles user operations
+type UserService struct {
+	logger *slog.Logger
+	users  map[int64]*User // In-memory store for demo
+	nextID int64
+}
+
+// NewUserService creates a new user service
+func NewUserService(logger *slog.Logger) *UserService {
+	return &UserService{
+		logger: logger,
+		users:  make(map[int64]*User),
+		nextID: 1,
+	}
+}
+
+// GetUser retrieves a user by ID
+func (s *UserService) GetUser(ctx context.Context, id int64) (*User, error) {
+	user, ok := s.users[id]
+	if !ok {
+		return nil, errors.New("user not found")
+	}
+	return user, nil
+}
+
+// CreateUser creates a new user
+func (s *UserService) CreateUser(ctx context.Context, name, email string) (*User, error) {
+	user := &User{
+		ID:        s.nextID,
+		Name:      name,
+		Email:     email,
+		CreatedAt: time.Now(),
+	}
+	s.users[s.nextID] = user
+	s.nextID++
+	return user, nil
+}
+
+// Server represents the HTTP server
+type Server struct {
+	http        *http.Server
+	userService *UserService
+	logger      *slog.Logger
+}
+
+// NewServer creates a new HTTP server
+func NewServer(addr string, logger *slog.Logger) *Server {
+	userService := NewUserService(logger)
+	
+	s := &Server{
+		userService: userService,
+		logger:      logger,
+	}
+	
+	s.http = &http.Server{
+		Addr:         addr,
+		Handler:      s.routes(),
+		ReadTimeout:  15 * time.Second,
+		WriteTimeout: 15 * time.Second,
+		IdleTimeout:  60 * time.Second,
+	}
+	
+	return s
+}
+
+// routes sets up the HTTP routes
+func (s *Server) routes() http.Handler {
+	r := chi.NewRouter()
+	
+	// Middleware
+	r.Use(middleware.RequestID)
+	r.Use(middleware.RealIP)
+	r.Use(middleware.Logger)
+	r.Use(middleware.Recoverer)
+	r.Use(middleware.Timeout(30 * time.Second))
+	
+	// Health check
+	r.Get("/health", s.handleHealth)
+	
+	// API routes
+	r.Route("/api/v1", func(r chi.Router) {
+		r.Route("/users", func(r chi.Router) {
+			r.Get("/{id}", s.handleGetUser)
+			r.Post("/", s.handleCreateUser)
+		})
+	})
+	
+	return r
+}
+
+// handleHealth handles health check requests
+func (s *Server) handleHealth(w http.ResponseWriter, r *http.Request) {
+	w.WriteHeader(http.StatusOK)
+	json.NewEncoder(w).Encode(map[string]string{"status": "healthy"})
+}
+
+// handleGetUser handles GET /api/v1/users/{id}
+func (s *Server) handleGetUser(w http.ResponseWriter, r *http.Request) {
+	ctx := r.Context()
+	
+	// Extract and validate ID
+	idStr := chi.URLParam(r, "id")
+	id, err := strconv.ParseInt(idStr, 10, 64)
+	if err != nil {
+		http.Error(w, "Invalid user ID", http.StatusBadRequest)
+		return
+	}
+	
+	// Get user
+	user, err := s.userService.GetUser(ctx, id)
+	if err != nil {
+		http.Error(w, "User not found", http.StatusNotFound)
+		return
+	}
+	
+	// Return user
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(user)
+}
+
+// CreateUserRequest represents the request body for creating a user
+type CreateUserRequest struct {
+	Name  string `json:"name"`
+	Email string `json:"email"`
+}
+
+// handleCreateUser handles POST /api/v1/users
+func (s *Server) handleCreateUser(w http.ResponseWriter, r *http.Request) {
+	ctx := r.Context()
+	
+	// Parse request body
+	var req CreateUserRequest
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		http.Error(w, "Invalid request body", http.StatusBadRequest)
+		return
+	}
+	
+	// Validate input
+	if req.Name == "" || req.Email == "" {
+		http.Error(w, "Name and email are required", http.StatusBadRequest)
+		return
+	}
+	
+	// Create user
+	user, err := s.userService.CreateUser(ctx, req.Name, req.Email)
+	if err != nil {
+		http.Error(w, "Failed to create user", http.StatusInternalServerError)
+		return
+	}
+	
+	// Return created user
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(http.StatusCreated)
+	json.NewEncoder(w).Encode(user)
+}
+
+// Shutdown gracefully shuts down the server
+func (s *Server) Shutdown(ctx context.Context) error {
+	s.logger.Info("Starting graceful shutdown")
+	return s.http.Shutdown(ctx)
+}
+
+func main() {
+	// Create logger
+	logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
+	
+	// Create server
+	srv := NewServer(":8080", logger)
+	
+	// Start server in goroutine
+	go func() {
+		logger.Info("Server starting", "addr", srv.http.Addr)
+		if err := srv.http.ListenAndServe(); err != nil && err != http.ErrServerClosed {
+			logger.Error("Server failed", "error", err)
+			os.Exit(1)
+		}
+	}()
+	
+	// Wait for interrupt signal
+	quit := make(chan os.Signal, 1)
+	signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
+	<-quit
+	
+	logger.Info("Shutdown signal received")
+	
+	// Graceful shutdown with timeout
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	defer cancel()
+	
+	if err := srv.Shutdown(ctx); err != nil {
+		logger.Error("Shutdown error", "error", err)
+		os.Exit(1)
+	}
+	
+	logger.Info("Server stopped")
+}
+

package/augment-extensions/coding-standards/go/module.json

@@ -0,0 +1,139 @@
+{
+  "name": "go-coding-standards",
+  "version": "1.0.0",
+  "description": "Professional Go coding standards for Augment Code AI covering web services, microservices, CLI tools, cloud-native applications, distributed systems, DevOps tooling, and API development",
+  "displayName": "Go Coding Standards",
+  "type": "coding-standards",
+  "author": "MyTech Today",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mytech-today-now/augment-extensions"
+  },
+  "keywords": [
+    "go",
+    "golang",
+    "coding-standards",
+    "best-practices",
+    "style-guide",
+    "web-services",
+    "microservices",
+    "cli",
+    "cloud-native",
+    "distributed-systems",
+    "devops",
+    "api-development"
+  ],
+  "categories": [
+    {
+      "id": "web",
+      "name": "Web Services",
+      "description": "HTTP server development, middleware patterns, request/response handling, routing (net/http, gorilla/mux, chi), graceful shutdown, TLS configuration"
+    },
+    {
+      "id": "microservices",
+      "name": "Microservices",
+      "description": "Service discovery, health checks, circuit breakers, distributed tracing (OpenTelemetry), metrics (Prometheus), gRPC communication, service mesh integration"
+    },
+    {
+      "id": "cli",
+      "name": "CLI Tools",
+      "description": "Command-line parsing (cobra, urfave/cli), flag handling, configuration management (viper), output formatting, exit codes, cross-platform compatibility"
+    },
+    {
+      "id": "cloud",
+      "name": "Cloud-Native Applications",
+      "description": "Containerization (Docker), Kubernetes operators, cloud provider SDKs (AWS, GCP, Azure), 12-factor app principles, environment-based configuration"
+    },
+    {
+      "id": "distributed",
+      "name": "Distributed Systems",
+      "description": "Consensus algorithms, event sourcing, CQRS patterns, message queues (NATS, Kafka, RabbitMQ), distributed locks, eventual consistency"
+    },
+    {
+      "id": "devops",
+      "name": "DevOps Tooling",
+      "description": "Infrastructure automation, CI/CD pipelines, configuration management, monitoring agents, log aggregation, GitOps workflows"
+    },
+    {
+      "id": "api",
+      "name": "API Development",
+      "description": "RESTful API design, GraphQL servers, API versioning, authentication/authorization (JWT, OAuth2), rate limiting, OpenAPI/Swagger documentation"
+    }
+  ],
+  "tags": [
+    "go1.18+",
+    "effective-go",
+    "uber-style-guide",
+    "google-style-guide",
+    "golangci-lint",
+    "staticcheck",
+    "concurrency",
+    "error-handling",
+    "testing",
+    "performance"
+  ],
+  "dependencies": {
+    "augment-extensions": "^1.4.0"
+  },
+  "peerDependencies": {
+    "go": ">=1.18.0"
+  },
+  "engines": {
+    "node": ">=14.0.0",
+    "augment": ">=1.0.0"
+  },
+  "compatibility": {
+    "go": {
+      "minimum": "1.18.0",
+      "recommended": "1.21.0",
+      "features": {
+        "generics": "1.18.0",
+        "fuzzing": "1.18.0",
+        "workspace": "1.18.0"
+      }
+    }
+  },
+  "configSchema": "./config/schema.json",
+  "configuration": {
+    "defaults": {
+      "categories": ["web"],
+      "rules": {
+        "enabled": true,
+        "severity": "error"
+      },
+      "staticAnalysis": {
+        "golangci-lint": true,
+        "staticcheck": true,
+        "govet": true,
+        "gosec": true
+      }
+    },
+    "options": {
+      "categories": "Array of category IDs to enable (web, microservices, cli, cloud, distributed, devops, api)",
+      "rules.enabled": "Enable/disable all rules (boolean)",
+      "rules.severity": "Default severity level (error, warning, info)",
+      "staticAnalysis": "Enable/disable static analysis tools"
+    }
+  },
+  "metrics": {
+    "characterCount": 270991,
+    "characterCountByCategory": {
+      "core": 12500,
+      "rules": 80000,
+      "templates": 50000,
+      "examples": 60000,
+      "documentation": 30000,
+      "tests": 40000
+    },
+    "files": {
+      "total": 50,
+      "rules": 14,
+      "templates": 7,
+      "examples": 10,
+      "tests": 10,
+      "documentation": 9
+    }
+  }
+}
+

package/augment-extensions/coding-standards/go/rules/categories/api-development/api-versioning.md

@@ -0,0 +1,149 @@
+# API Versioning Rules
+
+## Overview
+
+Best practices for versioning REST APIs in Go including URL versioning, header versioning, and backward compatibility.
+
+## Rules
+
+### 1. Use URL Path Versioning
+
+**Rule**: Include API version in the URL path for clarity.
+
+**Good Example**:
+```go
+func SetupVersionedRoutes(r *mux.Router) {
+    // Version 1
+    v1 := r.PathPrefix("/api/v1").Subrouter()
+    v1.HandleFunc("/users", v1.ListUsers).Methods("GET")
+    v1.HandleFunc("/users/{id}", v1.GetUser).Methods("GET")
+    
+    // Version 2
+    v2 := r.PathPrefix("/api/v2").Subrouter()
+    v2.HandleFunc("/users", v2.ListUsers).Methods("GET")
+    v2.HandleFunc("/users/{id}", v2.GetUser).Methods("GET")
+}
+```
+
+### 2. Maintain Backward Compatibility
+
+**Rule**: Keep old API versions functional while introducing new versions.
+
+**Good Example**:
+```go
+// V1 User structure
+type UserV1 struct {
+    ID    string `json:"id"`
+    Name  string `json:"name"`
+    Email string `json:"email"`
+}
+
+// V2 User structure with additional fields
+type UserV2 struct {
+    ID        string    `json:"id"`
+    FirstName string    `json:"first_name"`
+    LastName  string    `json:"last_name"`
+    Email     string    `json:"email"`
+    CreatedAt time.Time `json:"created_at"`
+}
+
+// Convert internal model to V1
+func toUserV1(user *User) *UserV1 {
+    return &UserV1{
+        ID:    user.ID,
+        Name:  user.FirstName + " " + user.LastName,
+        Email: user.Email,
+    }
+}
+
+// Convert internal model to V2
+func toUserV2(user *User) *UserV2 {
+    return &UserV2{
+        ID:        user.ID,
+        FirstName: user.FirstName,
+        LastName:  user.LastName,
+        Email:     user.Email,
+        CreatedAt: user.CreatedAt,
+    }
+}
+```
+
+### 3. Document Version Deprecation
+
+**Rule**: Clearly communicate version deprecation timelines.
+
+**Good Example**:
+```go
+func DeprecationMiddleware(version string, sunsetDate time.Time) func(http.Handler) http.Handler {
+    return func(next http.Handler) http.Handler {
+        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+            w.Header().Set("Deprecation", "true")
+            w.Header().Set("Sunset", sunsetDate.Format(time.RFC1123))
+            w.Header().Set("Link", fmt.Sprintf("</api/%s>; rel=\"successor-version\"", version))
+            
+            next.ServeHTTP(w, r)
+        })
+    }
+}
+
+// Apply to deprecated version
+v1Router.Use(DeprecationMiddleware("v2", time.Date(2026, 12, 31, 0, 0, 0, 0, time.UTC)))
+```
+
+### 4. Support Content Negotiation
+
+**Rule**: Allow clients to specify version via Accept header as alternative.
+
+**Good Example**:
+```go
+func VersionMiddleware(next http.Handler) http.Handler {
+    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+        version := "v1" // default
+        
+        // Check Accept header
+        accept := r.Header.Get("Accept")
+        if strings.Contains(accept, "application/vnd.api.v2+json") {
+            version = "v2"
+        } else if strings.Contains(accept, "application/vnd.api.v1+json") {
+            version = "v1"
+        }
+        
+        // Store version in context
+        ctx := context.WithValue(r.Context(), "api_version", version)
+        next.ServeHTTP(w, r.WithContext(ctx))
+    })
+}
+```
+
+### 5. Version Breaking Changes Only
+
+**Rule**: Only increment version for breaking changes, not additions.
+
+**Good Example**:
+```go
+// V1 - Original
+type CreateUserRequestV1 struct {
+    Name  string `json:"name"`
+    Email string `json:"email"`
+}
+
+// V1.1 - Added optional field (backward compatible, no version bump)
+type CreateUserRequestV1 struct {
+    Name     string  `json:"name"`
+    Email    string  `json:"email"`
+    Phone    *string `json:"phone,omitempty"` // Optional, backward compatible
+}
+
+// V2 - Breaking change (required field changed)
+type CreateUserRequestV2 struct {
+    FirstName string `json:"first_name"` // Breaking: split name field
+    LastName  string `json:"last_name"`  // Breaking: split name field
+    Email     string `json:"email"`
+}
+```
+
+## References
+
+- [API Versioning Best Practices](https://www.freecodecamp.org/news/how-to-version-a-rest-api/)
+- [Semantic Versioning](https://semver.org/)
+