@mytechtoday/augment-extensions 1.4.0 → 1.5.0

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

@@ -0,0 +1,209 @@
+# Rate Limiting Rules
+
+## Overview
+
+Best practices for implementing rate limiting in Go REST APIs to prevent abuse and ensure fair resource usage.
+
+## Rules
+
+### 1. Implement Token Bucket Algorithm
+
+**Rule**: Use token bucket algorithm for smooth rate limiting.
+
+**Good Example**:
+```go
+import "golang.org/x/time/rate"
+
+type RateLimiter struct {
+    limiters map[string]*rate.Limiter
+    mu       sync.RWMutex
+    rate     rate.Limit
+    burst    int
+}
+
+func NewRateLimiter(r rate.Limit, b int) *RateLimiter {
+    return &RateLimiter{
+        limiters: make(map[string]*rate.Limiter),
+        rate:     r,
+        burst:    b,
+    }
+}
+
+func (rl *RateLimiter) GetLimiter(key string) *rate.Limiter {
+    rl.mu.Lock()
+    defer rl.mu.Unlock()
+    
+    limiter, exists := rl.limiters[key]
+    if !exists {
+        limiter = rate.NewLimiter(rl.rate, rl.burst)
+        rl.limiters[key] = limiter
+    }
+    
+    return limiter
+}
+```
+
+### 2. Return Rate Limit Headers
+
+**Rule**: Include rate limit information in response headers.
+
+**Good Example**:
+```go
+func RateLimitMiddleware(limiter *RateLimiter) func(http.Handler) http.Handler {
+    return func(next http.Handler) http.Handler {
+        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+            key := getClientKey(r) // IP or API key
+            
+            l := limiter.GetLimiter(key)
+            
+            if !l.Allow() {
+                w.Header().Set("X-RateLimit-Limit", fmt.Sprintf("%d", limiter.burst))
+                w.Header().Set("X-RateLimit-Remaining", "0")
+                w.Header().Set("X-RateLimit-Reset", fmt.Sprintf("%d", time.Now().Add(time.Minute).Unix()))
+                w.Header().Set("Retry-After", "60")
+                
+                writeError(w, http.StatusTooManyRequests, "Rate limit exceeded")
+                return
+            }
+            
+            // Add rate limit headers
+            w.Header().Set("X-RateLimit-Limit", fmt.Sprintf("%d", limiter.burst))
+            w.Header().Set("X-RateLimit-Remaining", fmt.Sprintf("%d", l.Tokens()))
+            
+            next.ServeHTTP(w, r)
+        })
+    }
+}
+```
+
+### 3. Implement Different Limits for Different Endpoints
+
+**Rule**: Apply different rate limits based on endpoint sensitivity.
+
+**Good Example**:
+```go
+type EndpointLimits struct {
+    limiters map[string]*RateLimiter
+}
+
+func NewEndpointLimits() *EndpointLimits {
+    return &EndpointLimits{
+        limiters: map[string]*RateLimiter{
+            "/api/v1/auth/login":    NewRateLimiter(rate.Limit(5), 10),   // 5 req/sec
+            "/api/v1/users":         NewRateLimiter(rate.Limit(100), 200), // 100 req/sec
+            "/api/v1/search":        NewRateLimiter(rate.Limit(10), 20),   // 10 req/sec
+        },
+    }
+}
+
+func (el *EndpointLimits) GetLimiter(path string) *RateLimiter {
+    if limiter, ok := el.limiters[path]; ok {
+        return limiter
+    }
+    // Default limiter
+    return NewRateLimiter(rate.Limit(50), 100)
+}
+```
+
+### 4. Support API Key-Based Rate Limiting
+
+**Rule**: Implement per-API-key rate limiting for authenticated requests.
+
+**Good Example**:
+```go
+type APIKeyLimiter struct {
+    limiters map[string]*rate.Limiter
+    mu       sync.RWMutex
+    tiers    map[string]RateLimitTier
+}
+
+type RateLimitTier struct {
+    Rate  rate.Limit
+    Burst int
+}
+
+func NewAPIKeyLimiter() *APIKeyLimiter {
+    return &APIKeyLimiter{
+        limiters: make(map[string]*rate.Limiter),
+        tiers: map[string]RateLimitTier{
+            "free":       {Rate: rate.Limit(10), Burst: 20},
+            "basic":      {Rate: rate.Limit(100), Burst: 200},
+            "premium":    {Rate: rate.Limit(1000), Burst: 2000},
+            "enterprise": {Rate: rate.Limit(10000), Burst: 20000},
+        },
+    }
+}
+
+func (akl *APIKeyLimiter) GetLimiter(apiKey string, tier string) *rate.Limiter {
+    akl.mu.Lock()
+    defer akl.mu.Unlock()
+    
+    key := fmt.Sprintf("%s:%s", tier, apiKey)
+    
+    limiter, exists := akl.limiters[key]
+    if !exists {
+        tierConfig := akl.tiers[tier]
+        limiter = rate.NewLimiter(tierConfig.Rate, tierConfig.Burst)
+        akl.limiters[key] = limiter
+    }
+    
+    return limiter
+}
+```
+
+### 5. Implement Distributed Rate Limiting
+
+**Rule**: Use Redis for rate limiting across multiple servers.
+
+**Good Example**:
+```go
+type RedisRateLimiter struct {
+    client *redis.Client
+    limit  int
+    window time.Duration
+}
+
+func NewRedisRateLimiter(client *redis.Client, limit int, window time.Duration) *RedisRateLimiter {
+    return &RedisRateLimiter{
+        client: client,
+        limit:  limit,
+        window: window,
+    }
+}
+
+func (rrl *RedisRateLimiter) Allow(ctx context.Context, key string) (bool, error) {
+    now := time.Now().Unix()
+    windowStart := now - int64(rrl.window.Seconds())
+    
+    pipe := rrl.client.Pipeline()
+    
+    // Remove old entries
+    pipe.ZRemRangeByScore(ctx, key, "0", fmt.Sprintf("%d", windowStart))
+    
+    // Count current requests
+    countCmd := pipe.ZCard(ctx, key)
+    
+    // Add current request
+    pipe.ZAdd(ctx, key, &redis.Z{
+        Score:  float64(now),
+        Member: fmt.Sprintf("%d", now),
+    })
+    
+    // Set expiration
+    pipe.Expire(ctx, key, rrl.window)
+    
+    _, err := pipe.Exec(ctx)
+    if err != nil {
+        return false, err
+    }
+    
+    count := countCmd.Val()
+    return count < int64(rrl.limit), nil
+}
+```
+
+## References
+
+- [Rate Limiting Algorithms](https://en.wikipedia.org/wiki/Rate_limiting)
+- [golang.org/x/time/rate](https://pkg.go.dev/golang.org/x/time/rate)
+

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

@@ -0,0 +1,183 @@
+# REST API Design Rules
+
+## Overview
+
+Best practices for designing RESTful APIs in Go including resource modeling, HTTP methods, status codes, and response formats.
+
+## Rules
+
+### 1. Use Proper HTTP Methods
+
+**Rule**: Use appropriate HTTP methods for different operations.
+
+**Good Example**:
+```go
+func SetupRoutes(r *mux.Router) {
+    // Collection operations
+    r.HandleFunc("/api/v1/users", CreateUser).Methods("POST")
+    r.HandleFunc("/api/v1/users", ListUsers).Methods("GET")
+    
+    // Resource operations
+    r.HandleFunc("/api/v1/users/{id}", GetUser).Methods("GET")
+    r.HandleFunc("/api/v1/users/{id}", UpdateUser).Methods("PUT")
+    r.HandleFunc("/api/v1/users/{id}", PatchUser).Methods("PATCH")
+    r.HandleFunc("/api/v1/users/{id}", DeleteUser).Methods("DELETE")
+}
+```
+
+### 2. Return Appropriate Status Codes
+
+**Rule**: Use correct HTTP status codes for different scenarios.
+
+**Good Example**:
+```go
+func CreateUser(w http.ResponseWriter, r *http.Request) {
+    var user User
+    if err := json.NewDecoder(r.Body).Decode(&user); err != nil {
+        writeError(w, http.StatusBadRequest, "Invalid request body")
+        return
+    }
+    
+    if err := validateUser(&user); err != nil {
+        writeError(w, http.StatusUnprocessableEntity, err.Error())
+        return
+    }
+    
+    if err := db.CreateUser(&user); err != nil {
+        if isDuplicateError(err) {
+            writeError(w, http.StatusConflict, "User already exists")
+            return
+        }
+        writeError(w, http.StatusInternalServerError, "Failed to create user")
+        return
+    }
+    
+    writeJSON(w, http.StatusCreated, user)
+}
+```
+
+### 3. Implement Consistent Error Responses
+
+**Rule**: Return structured error responses with consistent format.
+
+**Good Example**:
+```go
+type ErrorResponse struct {
+    Error   string            `json:"error"`
+    Message string            `json:"message"`
+    Code    string            `json:"code,omitempty"`
+    Details map[string]string `json:"details,omitempty"`
+}
+
+func writeError(w http.ResponseWriter, status int, message string) {
+    response := ErrorResponse{
+        Error:   http.StatusText(status),
+        Message: message,
+    }
+    
+    w.Header().Set("Content-Type", "application/json")
+    w.WriteHeader(status)
+    json.NewEncoder(w).Encode(response)
+}
+```
+
+### 4. Support Pagination for Collections
+
+**Rule**: Implement pagination for list endpoints.
+
+**Good Example**:
+```go
+type PaginationParams struct {
+    Page     int `json:"page"`
+    PageSize int `json:"page_size"`
+}
+
+type PaginatedResponse struct {
+    Data       interface{} `json:"data"`
+    Page       int         `json:"page"`
+    PageSize   int         `json:"page_size"`
+    TotalItems int         `json:"total_items"`
+    TotalPages int         `json:"total_pages"`
+}
+
+func ListUsers(w http.ResponseWriter, r *http.Request) {
+    page, _ := strconv.Atoi(r.URL.Query().Get("page"))
+    if page < 1 {
+        page = 1
+    }
+    
+    pageSize, _ := strconv.Atoi(r.URL.Query().Get("page_size"))
+    if pageSize < 1 || pageSize > 100 {
+        pageSize = 20
+    }
+    
+    users, total, err := db.ListUsers(page, pageSize)
+    if err != nil {
+        writeError(w, http.StatusInternalServerError, "Failed to list users")
+        return
+    }
+    
+    response := PaginatedResponse{
+        Data:       users,
+        Page:       page,
+        PageSize:   pageSize,
+        TotalItems: total,
+        TotalPages: (total + pageSize - 1) / pageSize,
+    }
+    
+    writeJSON(w, http.StatusOK, response)
+}
+```
+
+### 5. Implement Filtering and Sorting
+
+**Rule**: Support filtering and sorting query parameters.
+
+**Good Example**:
+```go
+type QueryParams struct {
+    Filters map[string]string
+    SortBy  string
+    Order   string
+}
+
+func ParseQueryParams(r *http.Request) *QueryParams {
+    params := &QueryParams{
+        Filters: make(map[string]string),
+        SortBy:  r.URL.Query().Get("sort_by"),
+        Order:   r.URL.Query().Get("order"),
+    }
+    
+    // Parse filter parameters
+    for key, values := range r.URL.Query() {
+        if strings.HasPrefix(key, "filter_") {
+            filterKey := strings.TrimPrefix(key, "filter_")
+            params.Filters[filterKey] = values[0]
+        }
+    }
+    
+    if params.Order != "asc" && params.Order != "desc" {
+        params.Order = "asc"
+    }
+    
+    return params
+}
+
+func ListUsersWithFilters(w http.ResponseWriter, r *http.Request) {
+    params := ParseQueryParams(r)
+    
+    users, err := db.QueryUsers(params)
+    if err != nil {
+        writeError(w, http.StatusInternalServerError, "Failed to query users")
+        return
+    }
+    
+    writeJSON(w, http.StatusOK, users)
+}
+```
+
+## References
+
+- [REST API Design Best Practices](https://restfulapi.net/)
+- [HTTP Status Codes](https://httpstatuses.com/)
+

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

@@ -0,0 +1,193 @@
+# Cloud Configuration Management Rules
+
+## Overview
+
+Best practices for managing configuration in cloud-native Go applications including environment variables, config maps, secrets, and external configuration services.
+
+## Rules
+
+### 1. Use Environment Variables for Configuration
+
+**Rule**: Use environment variables for runtime configuration with sensible defaults.
+
+**Rationale**: Environment variables are the standard way to configure cloud-native applications across different platforms.
+
+**Good Example**:
+```go
+import "github.com/kelseyhightower/envconfig"
+
+type Config struct {
+    Port          int    `envconfig:"PORT" default:"8080"`
+    DatabaseURL   string `envconfig:"DATABASE_URL" required:"true"`
+    LogLevel      string `envconfig:"LOG_LEVEL" default:"info"`
+    EnableMetrics bool   `envconfig:"ENABLE_METRICS" default:"true"`
+}
+
+func LoadConfig() (*Config, error) {
+    var cfg Config
+    if err := envconfig.Process("", &cfg); err != nil {
+        return nil, fmt.Errorf("failed to load config: %w", err)
+    }
+    return &cfg, nil
+}
+```
+
+### 2. Never Hardcode Secrets
+
+**Rule**: Load secrets from environment variables or secret management systems, never hardcode them.
+
+**Good Example**:
+```go
+type DatabaseConfig struct {
+    Host     string `envconfig:"DB_HOST" required:"true"`
+    Port     int    `envconfig:"DB_PORT" default:"5432"`
+    User     string `envconfig:"DB_USER" required:"true"`
+    Password string `envconfig:"DB_PASSWORD" required:"true"` // From secret
+    Database string `envconfig:"DB_NAME" required:"true"`
+}
+
+func ConnectDatabase(cfg *DatabaseConfig) (*sql.DB, error) {
+    dsn := fmt.Sprintf("host=%s port=%d user=%s password=%s dbname=%s sslmode=require",
+        cfg.Host, cfg.Port, cfg.User, cfg.Password, cfg.Database)
+    
+    db, err := sql.Open("postgres", dsn)
+    if err != nil {
+        return nil, fmt.Errorf("failed to connect to database: %w", err)
+    }
+    
+    return db, nil
+}
+```
+
+### 3. Support Multiple Configuration Sources
+
+**Rule**: Support loading configuration from multiple sources with proper precedence.
+
+**Good Example**:
+```go
+import "github.com/spf13/viper"
+
+func LoadConfigWithViper() (*Config, error) {
+    viper.SetConfigName("config")
+    viper.SetConfigType("yaml")
+    viper.AddConfigPath("/etc/myapp/")
+    viper.AddConfigPath("$HOME/.myapp")
+    viper.AddConfigPath(".")
+    
+    // Environment variables take precedence
+    viper.AutomaticEnv()
+    viper.SetEnvPrefix("MYAPP")
+    
+    if err := viper.ReadInConfig(); err != nil {
+        if _, ok := err.(viper.ConfigFileNotFoundError); !ok {
+            return nil, fmt.Errorf("failed to read config: %w", err)
+        }
+        // Config file not found; using env vars and defaults
+    }
+    
+    var cfg Config
+    if err := viper.Unmarshal(&cfg); err != nil {
+        return nil, fmt.Errorf("failed to unmarshal config: %w", err)
+    }
+    
+    return &cfg, nil
+}
+```
+
+### 4. Validate Configuration on Startup
+
+**Rule**: Validate all required configuration values on application startup.
+
+**Good Example**:
+```go
+func (c *Config) Validate() error {
+    if c.Port < 1 || c.Port > 65535 {
+        return fmt.Errorf("invalid port: %d", c.Port)
+    }
+    
+    if c.DatabaseURL == "" {
+        return fmt.Errorf("DATABASE_URL is required")
+    }
+    
+    validLogLevels := map[string]bool{
+        "debug": true, "info": true, "warn": true, "error": true,
+    }
+    if !validLogLevels[c.LogLevel] {
+        return fmt.Errorf("invalid log level: %s", c.LogLevel)
+    }
+    
+    return nil
+}
+
+func main() {
+    cfg, err := LoadConfig()
+    if err != nil {
+        log.Fatalf("Failed to load config: %v", err)
+    }
+    
+    if err := cfg.Validate(); err != nil {
+        log.Fatalf("Invalid configuration: %v", err)
+    }
+    
+    // Start application
+}
+```
+
+### 5. Support Hot Reloading for Non-Critical Config
+
+**Rule**: Implement hot reloading for configuration that can be changed without restart.
+
+**Good Example**:
+```go
+type ConfigManager struct {
+    mu     sync.RWMutex
+    config *Config
+}
+
+func (cm *ConfigManager) Get() *Config {
+    cm.mu.RLock()
+    defer cm.mu.RUnlock()
+    return cm.config
+}
+
+func (cm *ConfigManager) Reload() error {
+    newConfig, err := LoadConfig()
+    if err != nil {
+        return fmt.Errorf("failed to reload config: %w", err)
+    }
+    
+    if err := newConfig.Validate(); err != nil {
+        return fmt.Errorf("invalid config: %w", err)
+    }
+    
+    cm.mu.Lock()
+    cm.config = newConfig
+    cm.mu.Unlock()
+    
+    log.Println("Configuration reloaded successfully")
+    return nil
+}
+
+func (cm *ConfigManager) WatchForChanges(ctx context.Context) {
+    ticker := time.NewTicker(30 * time.Second)
+    defer ticker.Stop()
+    
+    for {
+        select {
+        case <-ctx.Done():
+            return
+        case <-ticker.C:
+            if err := cm.Reload(); err != nil {
+                log.Printf("Failed to reload config: %v", err)
+            }
+        }
+    }
+}
+```
+
+## References
+
+- [The Twelve-Factor App - Config](https://12factor.net/config)
+- [Viper Configuration Library](https://github.com/spf13/viper)
+- [Envconfig](https://github.com/kelseyhightower/envconfig)
+