@mytechtoday/augment-extensions 1.4.0 → 1.5.0

package/augment-extensions/coding-standards/go/rules/categories/devops-tooling/ci-cd-integration.md

@@ -0,0 +1,147 @@
+# CI/CD Integration Rules
+
+## Overview
+
+Best practices for integrating Go applications with CI/CD pipelines including GitHub Actions, GitLab CI, and Jenkins.
+
+## Rules
+
+### 1. Provide Exit Codes for CI/CD
+
+**Rule**: Return appropriate exit codes for CI/CD pipeline integration.
+
+**Good Example**:
+```go
+func main() {
+    if err := run(); err != nil {
+        fmt.Fprintf(os.Stderr, "Error: %v\n", err)
+        
+        // Return specific exit codes
+        switch err.(type) {
+        case *ValidationError:
+            os.Exit(2) // Configuration error
+        case *DeploymentError:
+            os.Exit(3) // Deployment error
+        default:
+            os.Exit(1) // General error
+        }
+    }
+    
+    os.Exit(0) // Success
+}
+```
+
+### 2. Support Environment-Based Configuration
+
+**Rule**: Configure behavior through environment variables for CI/CD compatibility.
+
+**Good Example**:
+```go
+type CIConfig struct {
+    CI            bool   `envconfig:"CI" default:"false"`
+    Branch        string `envconfig:"CI_COMMIT_BRANCH"`
+    CommitSHA     string `envconfig:"CI_COMMIT_SHA"`
+    PipelineID    string `envconfig:"CI_PIPELINE_ID"`
+    BuildNumber   string `envconfig:"BUILD_NUMBER"`
+    ArtifactPath  string `envconfig:"ARTIFACT_PATH" default:"./artifacts"`
+}
+
+func LoadCIConfig() (*CIConfig, error) {
+    var cfg CIConfig
+    if err := envconfig.Process("", &cfg); err != nil {
+        return nil, err
+    }
+    return &cfg, nil
+}
+```
+
+### 3. Generate Machine-Readable Output
+
+**Rule**: Support JSON output for CI/CD pipeline consumption.
+
+**Good Example**:
+```go
+type TestResult struct {
+    Status   string        `json:"status"`
+    Duration time.Duration `json:"duration"`
+    Tests    []TestCase    `json:"tests"`
+    Coverage float64       `json:"coverage"`
+}
+
+func RunTests(outputFormat string) error {
+    result := executeTests()
+    
+    switch outputFormat {
+    case "json":
+        return json.NewEncoder(os.Stdout).Encode(result)
+    case "junit":
+        return writeJUnitXML(result)
+    default:
+        return writeHumanReadable(result)
+    }
+}
+```
+
+### 4. Implement Artifact Publishing
+
+**Rule**: Publish build artifacts with proper versioning and metadata.
+
+**Good Example**:
+```go
+type Artifact struct {
+    Name     string            `json:"name"`
+    Version  string            `json:"version"`
+    Path     string            `json:"path"`
+    Checksum string            `json:"checksum"`
+    Metadata map[string]string `json:"metadata"`
+}
+
+func PublishArtifact(ctx context.Context, artifact *Artifact) error {
+    // Calculate checksum
+    checksum, err := calculateSHA256(artifact.Path)
+    if err != nil {
+        return err
+    }
+    artifact.Checksum = checksum
+    
+    // Add build metadata
+    artifact.Metadata = map[string]string{
+        "build_time":   time.Now().Format(time.RFC3339),
+        "commit_sha":   os.Getenv("CI_COMMIT_SHA"),
+        "pipeline_id":  os.Getenv("CI_PIPELINE_ID"),
+    }
+    
+    // Upload to artifact repository
+    return uploadArtifact(ctx, artifact)
+}
+```
+
+### 5. Implement Health Checks for Deployment Verification
+
+**Rule**: Provide health check endpoints for deployment verification in CI/CD.
+
+**Good Example**:
+```go
+func WaitForDeployment(ctx context.Context, url string, timeout time.Duration) error {
+    deadline := time.Now().Add(timeout)
+    
+    for time.Now().Before(deadline) {
+        resp, err := http.Get(url + "/health")
+        if err == nil && resp.StatusCode == http.StatusOK {
+            log.Println("Deployment healthy")
+            return nil
+        }
+        
+        log.Printf("Waiting for deployment... (status: %v)", err)
+        time.Sleep(5 * time.Second)
+    }
+    
+    return fmt.Errorf("deployment did not become healthy within %v", timeout)
+}
+```
+
+## References
+
+- [GitHub Actions](https://docs.github.com/en/actions)
+- [GitLab CI/CD](https://docs.gitlab.com/ee/ci/)
+

package/augment-extensions/coding-standards/go/rules/categories/devops-tooling/infrastructure-as-code.md

@@ -0,0 +1,231 @@
+# Infrastructure as Code Rules
+
+## Overview
+
+Best practices for implementing Infrastructure as Code (IaC) tools in Go including Terraform providers, Pulumi programs, and custom IaC solutions.
+
+## Rules
+
+### 1. Implement Declarative Configuration
+
+**Rule**: Use declarative configuration for infrastructure definitions.
+
+**Good Example**:
+```go
+type InfrastructureConfig struct {
+    Resources []Resource `yaml:"resources"`
+    Variables map[string]string `yaml:"variables"`
+}
+
+type Resource struct {
+    Type       string                 `yaml:"type"`
+    Name       string                 `yaml:"name"`
+    Properties map[string]interface{} `yaml:"properties"`
+    DependsOn  []string               `yaml:"depends_on,omitempty"`
+}
+
+func LoadConfig(path string) (*InfrastructureConfig, error) {
+    data, err := os.ReadFile(path)
+    if err != nil {
+        return nil, err
+    }
+    
+    var config InfrastructureConfig
+    if err := yaml.Unmarshal(data, &config); err != nil {
+        return nil, err
+    }
+    
+    return &config, nil
+}
+```
+
+### 2. Implement State Management
+
+**Rule**: Track infrastructure state to enable updates and drift detection.
+
+**Good Example**:
+```go
+type StateManager struct {
+    backend StateBackend
+}
+
+type State struct {
+    Version   int                    `json:"version"`
+    Resources map[string]ResourceState `json:"resources"`
+    Outputs   map[string]string      `json:"outputs"`
+    UpdatedAt time.Time              `json:"updated_at"`
+}
+
+func (sm *StateManager) SaveState(ctx context.Context, state *State) error {
+    state.UpdatedAt = time.Now()
+    state.Version++
+    
+    data, err := json.Marshal(state)
+    if err != nil {
+        return err
+    }
+    
+    return sm.backend.Write(ctx, data)
+}
+
+func (sm *StateManager) LoadState(ctx context.Context) (*State, error) {
+    data, err := sm.backend.Read(ctx)
+    if err != nil {
+        return nil, err
+    }
+    
+    var state State
+    if err := json.Unmarshal(data, &state); err != nil {
+        return nil, err
+    }
+    
+    return &state, nil
+}
+```
+
+### 3. Implement Dependency Resolution
+
+**Rule**: Resolve resource dependencies and apply in correct order.
+
+**Good Example**:
+```go
+func ResolveDependencies(resources []Resource) ([]Resource, error) {
+    graph := make(map[string][]string)
+    
+    for _, res := range resources {
+        graph[res.Name] = res.DependsOn
+    }
+    
+    sorted, err := topologicalSort(graph)
+    if err != nil {
+        return nil, err
+    }
+    
+    result := make([]Resource, 0, len(resources))
+    for _, name := range sorted {
+        for _, res := range resources {
+            if res.Name == name {
+                result = append(result, res)
+                break
+            }
+        }
+    }
+    
+    return result, nil
+}
+```
+
+### 4. Implement Drift Detection
+
+**Rule**: Detect configuration drift between desired and actual state.
+
+**Good Example**:
+```go
+type DriftDetector struct {
+    provider ResourceProvider
+}
+
+type DriftResult struct {
+    Resource string
+    Expected interface{}
+    Actual   interface{}
+    Drifted  bool
+}
+
+func (dd *DriftDetector) DetectDrift(ctx context.Context, state *State) ([]DriftResult, error) {
+    var results []DriftResult
+    
+    for name, expected := range state.Resources {
+        actual, err := dd.provider.GetResource(ctx, name)
+        if err != nil {
+            return nil, err
+        }
+        
+        drifted := !reflect.DeepEqual(expected, actual)
+        
+        results = append(results, DriftResult{
+            Resource: name,
+            Expected: expected,
+            Actual:   actual,
+            Drifted:  drifted,
+        })
+    }
+    
+    return results, nil
+}
+```
+
+### 5. Support Plan and Apply Workflow
+
+**Rule**: Implement plan phase to preview changes before applying.
+
+**Good Example**:
+```go
+type Plan struct {
+    ToCreate []Resource
+    ToUpdate []Resource
+    ToDelete []Resource
+}
+
+func GeneratePlan(ctx context.Context, config *InfrastructureConfig, state *State) (*Plan, error) {
+    plan := &Plan{}
+    
+    // Determine resources to create, update, or delete
+    for _, res := range config.Resources {
+        if existing, ok := state.Resources[res.Name]; ok {
+            if !resourceMatches(res, existing) {
+                plan.ToUpdate = append(plan.ToUpdate, res)
+            }
+        } else {
+            plan.ToCreate = append(plan.ToCreate, res)
+        }
+    }
+    
+    for name := range state.Resources {
+        found := false
+        for _, res := range config.Resources {
+            if res.Name == name {
+                found = true
+                break
+            }
+        }
+        if !found {
+            plan.ToDelete = append(plan.ToDelete, Resource{Name: name})
+        }
+    }
+    
+    return plan, nil
+}
+
+func ApplyPlan(ctx context.Context, plan *Plan, provider ResourceProvider) error {
+    // Delete resources
+    for _, res := range plan.ToDelete {
+        if err := provider.DeleteResource(ctx, res.Name); err != nil {
+            return err
+        }
+    }
+    
+    // Create resources
+    for _, res := range plan.ToCreate {
+        if err := provider.CreateResource(ctx, &res); err != nil {
+            return err
+        }
+    }
+    
+    // Update resources
+    for _, res := range plan.ToUpdate {
+        if err := provider.UpdateResource(ctx, &res); err != nil {
+            return err
+        }
+    }
+    
+    return nil
+}
+```
+
+## References
+
+- [Terraform](https://www.terraform.io/)
+- [Pulumi](https://www.pulumi.com/)
+- [Infrastructure as Code Principles](https://www.hashicorp.com/resources/what-is-infrastructure-as-code)
+

package/augment-extensions/coding-standards/go/rules/categories/distributed-systems/caching.md

@@ -0,0 +1,150 @@
+# Distributed Caching Rules
+
+## Overview
+
+Best practices for implementing distributed caching in Go applications using Redis, Memcached, and other caching solutions.
+
+## Rules
+
+### 1. Use Cache-Aside Pattern
+
+**Rule**: Implement cache-aside (lazy loading) pattern for most use cases.
+
+**Good Example**:
+```go
+func GetUser(ctx context.Context, cache *redis.Client, db *sql.DB, userID string) (*User, error) {
+    // Try cache first
+    cacheKey := fmt.Sprintf("user:%s", userID)
+    cached, err := cache.Get(ctx, cacheKey).Result()
+    if err == nil {
+        var user User
+        if err := json.Unmarshal([]byte(cached), &user); err == nil {
+            return &user, nil
+        }
+    }
+    
+    // Cache miss - load from database
+    user, err := loadUserFromDB(ctx, db, userID)
+    if err != nil {
+        return nil, err
+    }
+    
+    // Store in cache
+    data, _ := json.Marshal(user)
+    cache.Set(ctx, cacheKey, data, 1*time.Hour)
+    
+    return user, nil
+}
+```
+
+### 2. Set Appropriate TTLs
+
+**Rule**: Always set TTL on cached items to prevent stale data.
+
+**Good Example**:
+```go
+const (
+    UserCacheTTL     = 1 * time.Hour
+    SessionCacheTTL  = 15 * time.Minute
+    ConfigCacheTTL   = 5 * time.Minute
+)
+
+func CacheUser(ctx context.Context, cache *redis.Client, user *User) error {
+    data, err := json.Marshal(user)
+    if err != nil {
+        return err
+    }
+    
+    key := fmt.Sprintf("user:%s", user.ID)
+    return cache.Set(ctx, key, data, UserCacheTTL).Err()
+}
+```
+
+### 3. Handle Cache Failures Gracefully
+
+**Rule**: Application should continue working if cache is unavailable.
+
+**Good Example**:
+```go
+func GetUserWithFallback(ctx context.Context, cache *redis.Client, db *sql.DB, userID string) (*User, error) {
+    // Try cache
+    if cache != nil {
+        if user, err := getUserFromCache(ctx, cache, userID); err == nil {
+            return user, nil
+        }
+        // Log cache error but continue
+        log.Printf("Cache error: %v, falling back to database", err)
+    }
+    
+    // Fallback to database
+    return loadUserFromDB(ctx, db, userID)
+}
+```
+
+### 4. Implement Cache Invalidation Strategy
+
+**Rule**: Invalidate cache entries when data changes.
+
+**Good Example**:
+```go
+func UpdateUser(ctx context.Context, cache *redis.Client, db *sql.DB, user *User) error {
+    // Update database
+    if err := updateUserInDB(ctx, db, user); err != nil {
+        return err
+    }
+    
+    // Invalidate cache
+    cacheKey := fmt.Sprintf("user:%s", user.ID)
+    if err := cache.Del(ctx, cacheKey).Err(); err != nil {
+        log.Printf("Failed to invalidate cache: %v", err)
+        // Don't fail the operation if cache invalidation fails
+    }
+    
+    return nil
+}
+```
+
+### 5. Use Pipelining for Batch Operations
+
+**Rule**: Use pipelining to reduce network round trips for multiple cache operations.
+
+**Good Example**:
+```go
+func GetMultipleUsers(ctx context.Context, cache *redis.Client, userIDs []string) (map[string]*User, error) {
+    pipe := cache.Pipeline()
+    
+    cmds := make(map[string]*redis.StringCmd)
+    for _, userID := range userIDs {
+        key := fmt.Sprintf("user:%s", userID)
+        cmds[userID] = pipe.Get(ctx, key)
+    }
+    
+    if _, err := pipe.Exec(ctx); err != nil && err != redis.Nil {
+        return nil, err
+    }
+    
+    users := make(map[string]*User)
+    for userID, cmd := range cmds {
+        val, err := cmd.Result()
+        if err == redis.Nil {
+            continue
+        }
+        if err != nil {
+            return nil, err
+        }
+        
+        var user User
+        if err := json.Unmarshal([]byte(val), &user); err == nil {
+            users[userID] = &user
+        }
+    }
+    
+    return users, nil
+}
+```
+
+## References
+
+- [Redis Best Practices](https://redis.io/docs/manual/patterns/)
+- [Caching Strategies](https://docs.aws.amazon.com/AmazonElastiCache/latest/mem-ug/Strategies.html)
+

package/augment-extensions/coding-standards/go/rules/categories/distributed-systems/consensus.md

@@ -0,0 +1,187 @@
+# Consensus and Distributed Coordination Rules
+
+## Overview
+
+Best practices for implementing consensus algorithms and distributed coordination in Go applications using Raft, etcd, and other consensus protocols.
+
+## Rules
+
+### 1. Use Proven Consensus Libraries
+
+**Rule**: Use established consensus libraries like etcd/raft or HashiCorp Raft instead of implementing your own.
+
+**Good Example**:
+```go
+import (
+    "github.com/hashicorp/raft"
+    raftboltdb "github.com/hashicorp/raft-boltdb"
+)
+
+func NewRaftNode(nodeID, raftDir, raftBind string) (*raft.Raft, error) {
+    config := raft.DefaultConfig()
+    config.LocalID = raft.ServerID(nodeID)
+    
+    store, err := raftboltdb.NewBoltStore(filepath.Join(raftDir, "raft.db"))
+    if err != nil {
+        return nil, fmt.Errorf("failed to create bolt store: %w", err)
+    }
+    
+    snapshots, err := raft.NewFileSnapshotStore(raftDir, 2, os.Stderr)
+    if err != nil {
+        return nil, fmt.Errorf("failed to create snapshot store: %w", err)
+    }
+    
+    transport, err := raft.NewTCPTransport(raftBind, nil, 3, 10*time.Second, os.Stderr)
+    if err != nil {
+        return nil, fmt.Errorf("failed to create transport: %w", err)
+    }
+    
+    r, err := raft.NewRaft(config, (*fsm)(s), store, store, snapshots, transport)
+    if err != nil {
+        return nil, fmt.Errorf("failed to create raft: %w", err)
+    }
+    
+    return r, nil
+}
+```
+
+### 2. Implement Finite State Machine Correctly
+
+**Rule**: Implement FSM with deterministic apply logic and proper snapshot/restore.
+
+**Good Example**:
+```go
+type FSM struct {
+    mu   sync.RWMutex
+    data map[string]string
+}
+
+func (f *FSM) Apply(log *raft.Log) interface{} {
+    f.mu.Lock()
+    defer f.mu.Unlock()
+    
+    var cmd Command
+    if err := json.Unmarshal(log.Data, &cmd); err != nil {
+        return err
+    }
+    
+    switch cmd.Op {
+    case "set":
+        f.data[cmd.Key] = cmd.Value
+    case "delete":
+        delete(f.data, cmd.Key)
+    }
+    
+    return nil
+}
+
+func (f *FSM) Snapshot() (raft.FSMSnapshot, error) {
+    f.mu.RLock()
+    defer f.mu.RUnlock()
+    
+    data := make(map[string]string)
+    for k, v := range f.data {
+        data[k] = v
+    }
+    
+    return &fsmSnapshot{data: data}, nil
+}
+
+func (f *FSM) Restore(rc io.ReadCloser) error {
+    f.mu.Lock()
+    defer f.mu.Unlock()
+    
+    decoder := json.NewDecoder(rc)
+    return decoder.Decode(&f.data)
+}
+```
+
+### 3. Handle Leader Election Properly
+
+**Rule**: Always check if node is leader before accepting writes.
+
+**Good Example**:
+```go
+func (s *Store) Set(key, value string) error {
+    if s.raft.State() != raft.Leader {
+        return fmt.Errorf("not leader")
+    }
+    
+    cmd := Command{
+        Op:    "set",
+        Key:   key,
+        Value: value,
+    }
+    
+    data, err := json.Marshal(cmd)
+    if err != nil {
+        return err
+    }
+    
+    future := s.raft.Apply(data, 10*time.Second)
+    return future.Error()
+}
+```
+
+### 4. Implement Read Consistency Levels
+
+**Rule**: Provide different read consistency levels (strong, eventual).
+
+**Good Example**:
+```go
+func (s *Store) Get(key string, consistent bool) (string, error) {
+    if consistent {
+        // Strong consistency: verify leadership
+        if err := s.raft.VerifyLeader().Error(); err != nil {
+            return "", err
+        }
+    }
+    
+    s.mu.RLock()
+    defer s.mu.RUnlock()
+    
+    value, ok := s.data[key]
+    if !ok {
+        return "", fmt.Errorf("key not found")
+    }
+    
+    return value, nil
+}
+```
+
+### 5. Handle Network Partitions Gracefully
+
+**Rule**: Implement proper timeout and retry logic for network partitions.
+
+**Good Example**:
+```go
+func (s *Store) SetWithRetry(key, value string, maxRetries int) error {
+    var lastErr error
+    
+    for i := 0; i < maxRetries; i++ {
+        err := s.Set(key, value)
+        if err == nil {
+            return nil
+        }
+        
+        lastErr = err
+        
+        if err.Error() == "not leader" {
+            // Wait for leader election
+            time.Sleep(time.Duration(i+1) * 100 * time.Millisecond)
+            continue
+        }
+        
+        return err
+    }
+    
+    return fmt.Errorf("failed after %d retries: %w", maxRetries, lastErr)
+}
+```
+
+## References
+
+- [HashiCorp Raft](https://github.com/hashicorp/raft)
+- [etcd Raft Library](https://github.com/etcd-io/etcd/tree/main/raft)
+- [Raft Consensus Algorithm](https://raft.github.io/)
+