@mytechtoday/augment-extensions 1.4.0 → 1.5.0

package/augment-extensions/coding-standards/go/rules/categories/cloud-native/health-checks.md

@@ -0,0 +1,231 @@
+# Health Check and Readiness Rules
+
+## Overview
+
+Best practices for implementing health checks, readiness probes, and liveness probes in cloud-native Go applications.
+
+## Rules
+
+### 1. Implement Separate Health and Readiness Endpoints
+
+**Rule**: Provide separate `/health` (liveness) and `/ready` (readiness) endpoints.
+
+**Rationale**: Liveness checks determine if the app should be restarted; readiness checks determine if it can receive traffic.
+
+**Good Example**:
+```go
+func healthHandler(w http.ResponseWriter, r *http.Request) {
+    w.WriteHeader(http.StatusOK)
+    w.Write([]byte("OK"))
+}
+
+func readinessHandler(db *sql.DB) http.HandlerFunc {
+    return func(w http.ResponseWriter, r *http.Request) {
+        // Check database connection
+        ctx, cancel := context.WithTimeout(r.Context(), 2*time.Second)
+        defer cancel()
+        
+        if err := db.PingContext(ctx); err != nil {
+            w.WriteHeader(http.StatusServiceUnavailable)
+            w.Write([]byte("Database unavailable"))
+            return
+        }
+        
+        w.WriteHeader(http.StatusOK)
+        w.Write([]byte("Ready"))
+    }
+}
+
+func main() {
+    db, _ := sql.Open("postgres", dsn)
+    
+    http.HandleFunc("/health", healthHandler)
+    http.HandleFunc("/ready", readinessHandler(db))
+    
+    log.Fatal(http.ListenAndServe(":8080", nil))
+}
+```
+
+### 2. Keep Health Checks Lightweight
+
+**Rule**: Health checks should be fast (<1s) and not perform expensive operations.
+
+**Good Example**:
+```go
+type HealthChecker struct {
+    checks map[string]HealthCheck
+}
+
+type HealthCheck func(context.Context) error
+
+func (hc *HealthChecker) AddCheck(name string, check HealthCheck) {
+    hc.checks[name] = check
+}
+
+func (hc *HealthChecker) Check(ctx context.Context) (map[string]string, error) {
+    results := make(map[string]string)
+    var hasError bool
+    
+    for name, check := range hc.checks {
+        checkCtx, cancel := context.WithTimeout(ctx, 1*time.Second)
+        defer cancel()
+        
+        if err := check(checkCtx); err != nil {
+            results[name] = fmt.Sprintf("FAIL: %v", err)
+            hasError = true
+        } else {
+            results[name] = "OK"
+        }
+    }
+    
+    if hasError {
+        return results, fmt.Errorf("health check failed")
+    }
+    
+    return results, nil
+}
+```
+
+### 3. Include Dependency Checks in Readiness
+
+**Rule**: Readiness probes should verify all critical dependencies are available.
+
+**Good Example**:
+```go
+func NewReadinessChecker(db *sql.DB, cache *redis.Client) *HealthChecker {
+    hc := &HealthChecker{checks: make(map[string]HealthCheck)}
+    
+    // Database check
+    hc.AddCheck("database", func(ctx context.Context) error {
+        return db.PingContext(ctx)
+    })
+    
+    // Cache check
+    hc.AddCheck("cache", func(ctx context.Context) error {
+        return cache.Ping(ctx).Err()
+    })
+    
+    // External API check (optional)
+    hc.AddCheck("external_api", func(ctx context.Context) error {
+        req, _ := http.NewRequestWithContext(ctx, "GET", "https://api.example.com/health", nil)
+        resp, err := http.DefaultClient.Do(req)
+        if err != nil {
+            return err
+        }
+        defer resp.Body.Close()
+        
+        if resp.StatusCode != http.StatusOK {
+            return fmt.Errorf("unexpected status: %d", resp.StatusCode)
+        }
+        return nil
+    })
+    
+    return hc
+}
+```
+
+### 4. Return Detailed Status Information
+
+**Rule**: Return structured health check responses with component-level details.
+
+**Good Example**:
+```go
+type HealthResponse struct {
+    Status     string            `json:"status"`
+    Timestamp  time.Time         `json:"timestamp"`
+    Components map[string]string `json:"components"`
+}
+
+func healthCheckHandler(checker *HealthChecker) http.HandlerFunc {
+    return func(w http.ResponseWriter, r *http.Request) {
+        ctx, cancel := context.WithTimeout(r.Context(), 5*time.Second)
+        defer cancel()
+        
+        components, err := checker.Check(ctx)
+        
+        response := HealthResponse{
+            Timestamp:  time.Now(),
+            Components: components,
+        }
+        
+        if err != nil {
+            response.Status = "unhealthy"
+            w.WriteHeader(http.StatusServiceUnavailable)
+        } else {
+            response.Status = "healthy"
+            w.WriteHeader(http.StatusOK)
+        }
+        
+        w.Header().Set("Content-Type", "application/json")
+        json.NewEncoder(w).Encode(response)
+    }
+}
+```
+
+### 5. Implement Graceful Degradation
+
+**Rule**: Allow the application to continue running with degraded functionality when non-critical dependencies fail.
+
+**Good Example**:
+```go
+type ServiceHealth struct {
+    mu              sync.RWMutex
+    cacheAvailable  bool
+    searchAvailable bool
+}
+
+func (sh *ServiceHealth) SetCacheAvailable(available bool) {
+    sh.mu.Lock()
+    defer sh.mu.Unlock()
+    sh.cacheAvailable = available
+}
+
+func (sh *ServiceHealth) IsCacheAvailable() bool {
+    sh.mu.RLock()
+    defer sh.mu.RUnlock()
+    return sh.cacheAvailable
+}
+
+func (sh *ServiceHealth) MonitorDependencies(ctx context.Context, cache *redis.Client) {
+    ticker := time.NewTicker(10 * time.Second)
+    defer ticker.Stop()
+    
+    for {
+        select {
+        case <-ctx.Done():
+            return
+        case <-ticker.C:
+            checkCtx, cancel := context.WithTimeout(ctx, 2*time.Second)
+            err := cache.Ping(checkCtx).Err()
+            cancel()
+            
+            sh.SetCacheAvailable(err == nil)
+            
+            if err != nil {
+                log.Printf("Cache unavailable: %v (degraded mode)", err)
+            }
+        }
+    }
+}
+
+func getData(sh *ServiceHealth, cache *redis.Client, db *sql.DB, key string) (string, error) {
+    // Try cache first if available
+    if sh.IsCacheAvailable() {
+        val, err := cache.Get(context.Background(), key).Result()
+        if err == nil {
+            return val, nil
+        }
+    }
+    
+    // Fallback to database
+    var value string
+    err := db.QueryRow("SELECT value FROM data WHERE key = $1", key).Scan(&value)
+    return value, err
+}
+```
+
+## References
+
+- [Kubernetes Liveness and Readiness Probes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/)
+- [Health Check Response Format for HTTP APIs](https://tools.ietf.org/id/draft-inadarei-api-health-check-06.html)
+

package/augment-extensions/coding-standards/go/rules/categories/cloud-native/kubernetes.md

@@ -0,0 +1,180 @@
+# Kubernetes Integration Rules
+
+## Overview
+
+Best practices for building Kubernetes-native Go applications including client-go usage, custom controllers, operators, and resource management.
+
+## Rules
+
+### 1. Use Official Kubernetes Client Libraries
+
+**Rule**: Always use `k8s.io/client-go` for Kubernetes API interactions.
+
+**Rationale**: Official client libraries provide type-safe, versioned access to Kubernetes APIs with proper error handling and retry logic.
+
+**Good Example**:
+```go
+import (
+    "k8s.io/client-go/kubernetes"
+    "k8s.io/client-go/rest"
+    "k8s.io/client-go/tools/clientcmd"
+)
+
+func NewK8sClient() (*kubernetes.Clientset, error) {
+    config, err := rest.InClusterConfig()
+    if err != nil {
+        // Fallback to kubeconfig for local development
+        config, err = clientcmd.BuildConfigFromFlags("", kubeconfig)
+        if err != nil {
+            return nil, fmt.Errorf("failed to build config: %w", err)
+        }
+    }
+    
+    clientset, err := kubernetes.NewForConfig(config)
+    if err != nil {
+        return nil, fmt.Errorf("failed to create clientset: %w", err)
+    }
+    
+    return clientset, nil
+}
+```
+
+### 2. Implement Proper Resource Watching
+
+**Rule**: Use informers and listers for efficient resource watching instead of polling.
+
+**Rationale**: Informers provide efficient, cached access to Kubernetes resources with automatic updates.
+
+**Good Example**:
+```go
+import (
+    "k8s.io/client-go/informers"
+    "k8s.io/client-go/tools/cache"
+)
+
+func WatchPods(clientset *kubernetes.Clientset) {
+    factory := informers.NewSharedInformerFactory(clientset, 30*time.Second)
+    podInformer := factory.Core().V1().Pods().Informer()
+    
+    podInformer.AddEventHandler(cache.ResourceEventHandlerFuncs{
+        AddFunc: func(obj interface{}) {
+            pod := obj.(*corev1.Pod)
+            log.Printf("Pod added: %s/%s", pod.Namespace, pod.Name)
+        },
+        UpdateFunc: func(oldObj, newObj interface{}) {
+            pod := newObj.(*corev1.Pod)
+            log.Printf("Pod updated: %s/%s", pod.Namespace, pod.Name)
+        },
+        DeleteFunc: func(obj interface{}) {
+            pod := obj.(*corev1.Pod)
+            log.Printf("Pod deleted: %s/%s", pod.Namespace, pod.Name)
+        },
+    })
+    
+    stopCh := make(chan struct{})
+    defer close(stopCh)
+    
+    factory.Start(stopCh)
+    factory.WaitForCacheSync(stopCh)
+    
+    <-stopCh
+}
+```
+
+### 3. Handle API Errors Gracefully
+
+**Rule**: Check for specific Kubernetes API errors using `apierrors` package.
+
+**Good Example**:
+```go
+import "k8s.io/apimachinery/pkg/api/errors"
+
+func GetPod(clientset *kubernetes.Clientset, namespace, name string) (*corev1.Pod, error) {
+    pod, err := clientset.CoreV1().Pods(namespace).Get(context.TODO(), name, metav1.GetOptions{})
+    if err != nil {
+        if errors.IsNotFound(err) {
+            return nil, fmt.Errorf("pod %s/%s not found", namespace, name)
+        }
+        if errors.IsUnauthorized(err) {
+            return nil, fmt.Errorf("unauthorized to access pod: %w", err)
+        }
+        return nil, fmt.Errorf("failed to get pod: %w", err)
+    }
+    return pod, nil
+}
+```
+
+### 4. Use Controller Runtime for Custom Controllers
+
+**Rule**: Use `sigs.k8s.io/controller-runtime` for building custom controllers and operators.
+
+**Good Example**:
+```go
+import (
+    ctrl "sigs.k8s.io/controller-runtime"
+    "sigs.k8s.io/controller-runtime/pkg/client"
+)
+
+type PodReconciler struct {
+    client.Client
+    Scheme *runtime.Scheme
+}
+
+func (r *PodReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
+    var pod corev1.Pod
+    if err := r.Get(ctx, req.NamespacedName, &pod); err != nil {
+        if errors.IsNotFound(err) {
+            return ctrl.Result{}, nil
+        }
+        return ctrl.Result{}, err
+    }
+    
+    // Reconciliation logic here
+    
+    return ctrl.Result{}, nil
+}
+```
+
+### 5. Implement Leader Election for High Availability
+
+**Rule**: Use leader election for controllers running in multiple replicas.
+
+**Good Example**:
+```go
+import "k8s.io/client-go/tools/leaderelection"
+
+func RunWithLeaderElection(ctx context.Context, clientset *kubernetes.Clientset) {
+    lock := &resourcelock.LeaseLock{
+        LeaseMeta: metav1.ObjectMeta{
+            Name:      "my-controller",
+            Namespace: "default",
+        },
+        Client: clientset.CoordinationV1(),
+        LockConfig: resourcelock.ResourceLockConfig{
+            Identity: os.Getenv("POD_NAME"),
+        },
+    }
+    
+    leaderelection.RunOrDie(ctx, leaderelection.LeaderElectionConfig{
+        Lock:          lock,
+        LeaseDuration: 15 * time.Second,
+        RenewDeadline: 10 * time.Second,
+        RetryPeriod:   2 * time.Second,
+        Callbacks: leaderelection.LeaderCallbacks{
+            OnStartedLeading: func(ctx context.Context) {
+                // Start controller logic
+            },
+            OnStoppedLeading: func() {
+                log.Fatal("lost leadership")
+            },
+        },
+    })
+}
+```
+
+## References
+
+- [Kubernetes Client-Go](https://github.com/kubernetes/client-go)
+- [Controller Runtime](https://github.com/kubernetes-sigs/controller-runtime)
+- [Kubebuilder Book](https://book.kubebuilder.io/)
+

package/augment-extensions/coding-standards/go/rules/categories/devops-tooling/automation.md

@@ -0,0 +1,179 @@
+# DevOps Automation Rules
+
+## Overview
+
+Best practices for building DevOps automation tools in Go including CLI tools, deployment automation, and infrastructure management.
+
+## Rules
+
+### 1. Use Cobra for CLI Applications
+
+**Rule**: Use Cobra framework for building command-line tools with subcommands.
+
+**Good Example**:
+```go
+import "github.com/spf13/cobra"
+
+var rootCmd = &cobra.Command{
+    Use:   "devops-tool",
+    Short: "A DevOps automation tool",
+    Long:  `A comprehensive DevOps automation tool for deployment and infrastructure management.`,
+}
+
+var deployCmd = &cobra.Command{
+    Use:   "deploy [environment]",
+    Short: "Deploy application to environment",
+    Args:  cobra.ExactArgs(1),
+    RunE: func(cmd *cobra.Command, args []string) error {
+        environment := args[0]
+        return deployToEnvironment(environment)
+    },
+}
+
+func init() {
+    deployCmd.Flags().StringP("version", "v", "latest", "Version to deploy")
+    deployCmd.Flags().BoolP("dry-run", "d", false, "Perform dry run")
+    rootCmd.AddCommand(deployCmd)
+}
+```
+
+### 2. Implement Idempotent Operations
+
+**Rule**: All automation operations should be idempotent and safe to retry.
+
+**Good Example**:
+```go
+func EnsureDeployment(ctx context.Context, config *DeploymentConfig) error {
+    // Check if deployment already exists
+    existing, err := getDeployment(ctx, config.Name)
+    if err != nil && !isNotFoundError(err) {
+        return err
+    }
+    
+    if existing != nil {
+        // Update existing deployment
+        if deploymentMatches(existing, config) {
+            log.Printf("Deployment %s already up to date", config.Name)
+            return nil
+        }
+        return updateDeployment(ctx, config)
+    }
+    
+    // Create new deployment
+    return createDeployment(ctx, config)
+}
+```
+
+### 3. Provide Detailed Progress Feedback
+
+**Rule**: Show progress for long-running operations with clear status updates.
+
+**Good Example**:
+```go
+import "github.com/schollz/progressbar/v3"
+
+func DeployWithProgress(ctx context.Context, steps []DeploymentStep) error {
+    bar := progressbar.NewOptions(len(steps),
+        progressbar.OptionSetDescription("Deploying..."),
+        progressbar.OptionShowCount(),
+        progressbar.OptionSetWidth(40),
+    )
+    
+    for i, step := range steps {
+        bar.Describe(step.Description)
+        
+        if err := step.Execute(ctx); err != nil {
+            return fmt.Errorf("step %d failed: %w", i+1, err)
+        }
+        
+        bar.Add(1)
+    }
+    
+    return nil
+}
+```
+
+### 4. Support Dry-Run Mode
+
+**Rule**: Implement dry-run mode for all destructive operations.
+
+**Good Example**:
+```go
+type DeploymentOptions struct {
+    DryRun  bool
+    Verbose bool
+}
+
+func Deploy(ctx context.Context, config *DeploymentConfig, opts *DeploymentOptions) error {
+    steps := []DeploymentStep{
+        {Name: "Validate config", Fn: validateConfig},
+        {Name: "Build image", Fn: buildImage},
+        {Name: "Push image", Fn: pushImage},
+        {Name: "Update deployment", Fn: updateDeployment},
+    }
+    
+    for _, step := range steps {
+        if opts.Verbose {
+            log.Printf("Executing: %s", step.Name)
+        }
+        
+        if opts.DryRun {
+            log.Printf("[DRY RUN] Would execute: %s", step.Name)
+            continue
+        }
+        
+        if err := step.Fn(ctx, config); err != nil {
+            return fmt.Errorf("%s failed: %w", step.Name, err)
+        }
+    }
+    
+    return nil
+}
+```
+
+### 5. Implement Rollback Capability
+
+**Rule**: Provide rollback functionality for failed deployments.
+
+**Good Example**:
+```go
+type DeploymentHistory struct {
+    Deployments []DeploymentRecord
+}
+
+type DeploymentRecord struct {
+    Version   string
+    Timestamp time.Time
+    Config    *DeploymentConfig
+}
+
+func DeployWithRollback(ctx context.Context, config *DeploymentConfig) error {
+    // Save current state
+    currentState, err := captureCurrentState(ctx)
+    if err != nil {
+        return err
+    }
+    
+    // Attempt deployment
+    if err := deploy(ctx, config); err != nil {
+        log.Printf("Deployment failed: %v, rolling back...", err)
+        
+        if rollbackErr := rollback(ctx, currentState); rollbackErr != nil {
+            return fmt.Errorf("deployment failed and rollback failed: %v, %v", err, rollbackErr)
+        }
+        
+        return fmt.Errorf("deployment failed (rolled back): %w", err)
+    }
+    
+    // Save successful deployment to history
+    saveDeploymentHistory(ctx, config)
+    
+    return nil
+}
+```
+
+## References
+
+- [Cobra CLI Framework](https://github.com/spf13/cobra)
+- [The Twelve-Factor App](https://12factor.net/)
+