@cubis/foundry 0.3.82 → 0.3.84

package/workflows/skills/gin-golang/examples/01-crud-api-with-validation.md

@@ -1,219 +0,0 @@
-# Example: CRUD API with Validation
-
-## Prompt
-
-> Build a Gin CRUD API for an inventory service with products under /api/v1/products. Include validation with struct binding tags, a custom slug validator, and structured error responses. Use gin.New() with explicit middleware.
-
-## Expected Output
-
-The skill should produce a complete Gin application with validation and structured errors:
-
-### Application Bootstrap
-
-```go
-package main
-
-import (
-    "net/http"
-    "os"
-    "os/signal"
-    "syscall"
-    "time"
-
-    "github.com/gin-gonic/gin"
-    "github.com/gin-gonic/gin/binding"
-    "github.com/go-playground/validator/v10"
-)
-
-func main() {
-    if os.Getenv("GIN_MODE") == "release" {
-        gin.SetMode(gin.ReleaseMode)
-    }
-
-    router := gin.New()
-    router.SetTrustedProxies([]string{"10.0.0.0/8", "172.16.0.0/12"})
-
-    // Register custom validators
-    if v, ok := binding.Validator.Engine().(*validator.Validate); ok {
-        v.RegisterValidation("slug", validateSlug)
-    }
-
-    // Explicit middleware stack
-    router.Use(gin.CustomRecoveryWithWriter(os.Stderr, recoveryHandler))
-    router.Use(requestIDMiddleware())
-    router.Use(structuredLoggerMiddleware())
-
-    // Public routes
-    router.GET("/health", healthHandler)
-
-    // Protected API group
-    api := router.Group("/api/v1")
-    api.Use(jwtAuthMiddleware())
-    {
-        api.GET("/products", listProducts)
-        api.POST("/products", createProduct)
-        api.GET("/products/:id", getProduct)
-        api.PUT("/products/:id", updateProduct)
-        api.DELETE("/products/:id", deleteProduct)
-    }
-
-    // Graceful shutdown
-    srv := &http.Server{
-        Addr:         ":8080",
-        Handler:      router,
-        ReadTimeout:  10 * time.Second,
-        WriteTimeout: 10 * time.Second,
-        IdleTimeout:  120 * time.Second,
-    }
-
-    go func() {
-        if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
-            log.Fatalf("listen: %s\n", err)
-        }
-    }()
-
-    quit := make(chan os.Signal, 1)
-    signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
-    <-quit
-
-    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
-    defer cancel()
-    srv.Shutdown(ctx)
-}
-```
-
-### Request Structs with Binding Tags
-
-```go
-type CreateProductRequest struct {
-    Name     string  `json:"name" binding:"required,min=1,max=200"`
-    Slug     string  `json:"slug" binding:"required,slug"`
-    Price    float64 `json:"price" binding:"required,gt=0,lte=999999"`
-    Category string  `json:"category" binding:"required,oneof=electronics books clothing food"`
-    SKU      string  `json:"sku" binding:"required,len=10"`
-}
-
-type UpdateProductRequest struct {
-    Name     *string  `json:"name" binding:"omitempty,min=1,max=200"`
-    Price    *float64 `json:"price" binding:"omitempty,gt=0,lte=999999"`
-    Category *string  `json:"category" binding:"omitempty,oneof=electronics books clothing food"`
-}
-
-// Custom slug validator
-func validateSlug(fl validator.FieldLevel) bool {
-    slug := fl.Field().String()
-    matched, _ := regexp.MatchString(`^[a-z0-9]+(?:-[a-z0-9]+)*$`, slug)
-    return matched
-}
-```
-
-### Handler with Structured Error Response
-
-```go
-func createProduct(c *gin.Context) {
-    var req CreateProductRequest
-    if err := c.ShouldBindJSON(&req); err != nil {
-        handleValidationError(c, err)
-        return
-    }
-
-    product, err := productService.Create(c.Request.Context(), req)
-    if err != nil {
-        handleError(c, err)
-        return
-    }
-
-    c.JSON(http.StatusCreated, product)
-}
-
-func handleValidationError(c *gin.Context, err error) {
-    var ve validator.ValidationErrors
-    if errors.As(err, &ve) {
-        fields := make([]FieldError, len(ve))
-        for i, fe := range ve {
-            fields[i] = FieldError{
-                Field:   fe.Field(),
-                Tag:     fe.Tag(),
-                Message: fieldErrorMessage(fe),
-            }
-        }
-        c.JSON(http.StatusBadRequest, ErrorResponse{
-            Code:    "VALIDATION_ERROR",
-            Message: "Request validation failed",
-            Details: fields,
-        })
-        return
-    }
-    c.JSON(http.StatusBadRequest, ErrorResponse{
-        Code:    "BAD_REQUEST",
-        Message: err.Error(),
-    })
-}
-```
-
-### Table-Driven Tests
-
-```go
-func TestCreateProduct(t *testing.T) {
-    router := setupTestRouter()
-
-    tests := []struct {
-        name       string
-        body       interface{}
-        wantStatus int
-        wantCode   string
-    }{
-        {
-            name: "valid product",
-            body: CreateProductRequest{
-                Name: "Widget", Slug: "widget-pro",
-                Price: 29.99, Category: "electronics", SKU: "ABCDEFGHIJ",
-            },
-            wantStatus: 201,
-        },
-        {
-            name:       "missing required fields",
-            body:       map[string]string{"name": "Widget"},
-            wantStatus: 400,
-            wantCode:   "VALIDATION_ERROR",
-        },
-        {
-            name: "invalid slug format",
-            body: map[string]interface{}{
-                "name": "Widget", "slug": "INVALID SLUG!",
-                "price": 29.99, "category": "electronics", "sku": "ABCDEFGHIJ",
-            },
-            wantStatus: 400,
-            wantCode:   "VALIDATION_ERROR",
-        },
-    }
-
-    for _, tt := range tests {
-        t.Run(tt.name, func(t *testing.T) {
-            body, _ := json.Marshal(tt.body)
-            w := httptest.NewRecorder()
-            req := httptest.NewRequest("POST", "/api/v1/products", bytes.NewReader(body))
-            req.Header.Set("Content-Type", "application/json")
-            req.Header.Set("Authorization", "Bearer "+testToken)
-
-            router.ServeHTTP(w, req)
-
-            assert.Equal(t, tt.wantStatus, w.Code)
-            if tt.wantCode != "" {
-                var resp ErrorResponse
-                json.Unmarshal(w.Body.Bytes(), &resp)
-                assert.Equal(t, tt.wantCode, resp.Code)
-            }
-        })
-    }
-}
-```
-
-## Key Observations
-
-- `gin.New()` is used instead of `gin.Default()` for explicit middleware control.
-- Custom slug validator is registered through `binding.Validator.Engine()`.
-- `ShouldBindJSON` is used instead of `BindJSON` to retain error handling control.
-- Update struct uses pointer fields for partial update support.
-- Graceful shutdown wraps Gin in `http.Server` for timeout and signal handling.
-- Tests are table-driven with subtests covering valid, missing, and invalid inputs.

package/workflows/skills/gin-golang/examples/02-middleware-integration-testing.md

@@ -1,192 +0,0 @@
-# Example: Middleware Integration Testing
-
-## Prompt
-
-> Write integration tests for a Gin middleware stack: request ID, structured logging with slog, JWT auth, and rate limiting. Verify middleware execution order and that logging captures correct status codes from downstream errors.
-
-## Expected Output
-
-The skill should produce a complete middleware test suite:
-
-### Request ID Middleware
-
-```go
-func requestIDMiddleware() gin.HandlerFunc {
-    return func(c *gin.Context) {
-        id := c.GetHeader("X-Request-Id")
-        if id == "" {
-            id = uuid.New().String()
-        }
-        c.Set("requestID", id)
-        c.Header("X-Request-Id", id)
-        c.Next()
-    }
-}
-```
-
-### Structured Logging Middleware
-
-```go
-func loggingMiddleware(logger *slog.Logger) gin.HandlerFunc {
-    return func(c *gin.Context) {
-        start := time.Now()
-        path := c.Request.URL.Path
-
-        c.Next()
-
-        // Capture status AFTER handler execution
-        status := c.Writer.Status()
-        latency := time.Since(start)
-        reqID, _ := c.Get("requestID")
-
-        logger.Info("request",
-            "method", c.Request.Method,
-            "path", path,
-            "status", status,
-            "latency_ms", latency.Milliseconds(),
-            "request_id", reqID,
-            "client_ip", c.ClientIP(),
-        )
-    }
-}
-```
-
-### Integration Tests
-
-```go
-func TestRequestIDPropagation(t *testing.T) {
-    router := gin.New()
-    router.Use(requestIDMiddleware())
-    router.GET("/test", func(c *gin.Context) {
-        id, _ := c.Get("requestID")
-        c.JSON(200, gin.H{"request_id": id})
-    })
-
-    w := httptest.NewRecorder()
-    req := httptest.NewRequest("GET", "/test", nil)
-    router.ServeHTTP(w, req)
-
-    assert.Equal(t, 200, w.Code)
-
-    // Verify header is a valid UUID
-    headerID := w.Header().Get("X-Request-Id")
-    assert.NotEmpty(t, headerID)
-    _, err := uuid.Parse(headerID)
-    assert.NoError(t, err, "X-Request-Id should be a valid UUID")
-
-    // Verify handler received the same ID
-    var body map[string]string
-    json.Unmarshal(w.Body.Bytes(), &body)
-    assert.Equal(t, headerID, body["request_id"])
-}
-
-func TestRequestIDPreservedFromClient(t *testing.T) {
-    router := gin.New()
-    router.Use(requestIDMiddleware())
-    router.GET("/test", func(c *gin.Context) {
-        c.Status(200)
-    })
-
-    clientID := "client-supplied-id-123"
-    w := httptest.NewRecorder()
-    req := httptest.NewRequest("GET", "/test", nil)
-    req.Header.Set("X-Request-Id", clientID)
-    router.ServeHTTP(w, req)
-
-    assert.Equal(t, clientID, w.Header().Get("X-Request-Id"))
-}
-
-func TestAuthMiddlewareRejectsInvalidToken(t *testing.T) {
-    router := gin.New()
-    router.Use(requestIDMiddleware())
-    router.Use(authMiddleware(testSecret))
-    router.GET("/protected", func(c *gin.Context) {
-        c.JSON(200, gin.H{"ok": true})
-    })
-
-    tests := []struct {
-        name       string
-        authHeader string
-        wantStatus int
-        wantCode   string
-    }{
-        {"missing header", "", 401, "UNAUTHORIZED"},
-        {"invalid format", "NotBearer xyz", 401, "UNAUTHORIZED"},
-        {"expired token", "Bearer " + expiredToken, 401, "TOKEN_EXPIRED"},
-        {"valid token", "Bearer " + validToken, 200, ""},
-    }
-
-    for _, tt := range tests {
-        t.Run(tt.name, func(t *testing.T) {
-            w := httptest.NewRecorder()
-            req := httptest.NewRequest("GET", "/protected", nil)
-            if tt.authHeader != "" {
-                req.Header.Set("Authorization", tt.authHeader)
-            }
-            router.ServeHTTP(w, req)
-
-            assert.Equal(t, tt.wantStatus, w.Code)
-            if tt.wantCode != "" {
-                var resp ErrorResponse
-                json.Unmarshal(w.Body.Bytes(), &resp)
-                assert.Equal(t, tt.wantCode, resp.Code)
-            }
-            // Request ID header should always be present
-            assert.NotEmpty(t, w.Header().Get("X-Request-Id"))
-        })
-    }
-}
-
-func TestRateLimiterTriggersAfterThreshold(t *testing.T) {
-    router := gin.New()
-    router.Use(rateLimitMiddleware(3, time.Minute)) // 3 requests per minute
-    router.GET("/limited", func(c *gin.Context) {
-        c.JSON(200, gin.H{"ok": true})
-    })
-
-    for i := 0; i < 3; i++ {
-        w := httptest.NewRecorder()
-        req := httptest.NewRequest("GET", "/limited", nil)
-        req.RemoteAddr = "192.168.1.1:1234"
-        router.ServeHTTP(w, req)
-        assert.Equal(t, 200, w.Code, "request %d should succeed", i+1)
-    }
-
-    // 4th request should be rate limited
-    w := httptest.NewRecorder()
-    req := httptest.NewRequest("GET", "/limited", nil)
-    req.RemoteAddr = "192.168.1.1:1234"
-    router.ServeHTTP(w, req)
-    assert.Equal(t, 429, w.Code)
-}
-
-func TestLoggingCapturesErrorStatus(t *testing.T) {
-    var buf bytes.Buffer
-    logger := slog.New(slog.NewJSONHandler(&buf, nil))
-
-    router := gin.New()
-    router.Use(loggingMiddleware(logger))
-    router.GET("/not-found", func(c *gin.Context) {
-        c.JSON(404, gin.H{"error": "not found"})
-    })
-
-    w := httptest.NewRecorder()
-    req := httptest.NewRequest("GET", "/not-found", nil)
-    router.ServeHTTP(w, req)
-
-    assert.Equal(t, 404, w.Code)
-
-    // Verify the log entry captured status 404, not 200
-    logOutput := buf.String()
-    assert.Contains(t, logOutput, `"status":404`)
-}
-```
-
-## Key Observations
-
-- Request ID middleware runs before logging so the logger can include the ID.
-- Auth middleware runs after request ID so rejected requests still have traceability.
-- Logging middleware captures `c.Writer.Status()` AFTER `c.Next()` so it reflects the actual response status.
-- Rate limiter test sends requests in sequence and verifies the threshold transition.
-- All tests use `httptest.NewRecorder` with `router.ServeHTTP` for full-stack integration.
-- The logging status test catches the common bug of logging status before the handler sets it.

package/workflows/skills/gin-golang/references/deployment.md

@@ -1,295 +0,0 @@
-# Gin Deployment
-
-## Graceful Shutdown
-
-Never use `router.Run()` in production. Wrap the Gin engine in an `http.Server` for proper shutdown support.
-
-```go
-package main
-
-import (
-    "context"
-    "log"
-    "net/http"
-    "os"
-    "os/signal"
-    "syscall"
-    "time"
-
-    "github.com/gin-gonic/gin"
-)
-
-func main() {
-    gin.SetMode(gin.ReleaseMode)
-    router := setupRouter()
-
-    srv := &http.Server{
-        Addr:              ":8080",
-        Handler:           router,
-        ReadTimeout:       10 * time.Second,
-        ReadHeaderTimeout: 5 * time.Second,
-        WriteTimeout:      10 * time.Second,
-        IdleTimeout:       120 * time.Second,
-        MaxHeaderBytes:    1 << 20, // 1MB
-    }
-
-    // Start server in goroutine
-    go func() {
-        log.Printf("Starting server on %s", srv.Addr)
-        if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
-            log.Fatalf("Server error: %v", err)
-        }
-    }()
-
-    // Wait for interrupt signal
-    quit := make(chan os.Signal, 1)
-    signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
-    sig := <-quit
-    log.Printf("Received signal: %v, shutting down...", sig)
-
-    // Shutdown with timeout
-    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
-    defer cancel()
-
-    if err := srv.Shutdown(ctx); err != nil {
-        log.Fatalf("Forced shutdown: %v", err)
-    }
-
-    // Close database connections, flush logs, etc.
-    cleanup()
-
-    log.Println("Server stopped")
-}
-```
-
-## Health Checks
-
-Implement health and readiness endpoints for orchestrators like Kubernetes.
-
-```go
-func setupHealthRoutes(router *gin.Engine, db *sql.DB) {
-    // Liveness: is the process alive?
-    router.GET("/healthz", func(c *gin.Context) {
-        c.JSON(200, gin.H{"status": "alive"})
-    })
-
-    // Readiness: can the process handle traffic?
-    router.GET("/readyz", func(c *gin.Context) {
-        ctx, cancel := context.WithTimeout(c.Request.Context(), 2*time.Second)
-        defer cancel()
-
-        if err := db.PingContext(ctx); err != nil {
-            c.JSON(503, gin.H{
-                "status": "not ready",
-                "reason": "database unavailable",
-            })
-            return
-        }
-
-        c.JSON(200, gin.H{"status": "ready"})
-    })
-
-    // Startup probe (for slow-starting apps)
-    router.GET("/startupz", func(c *gin.Context) {
-        if !appReady.Load() {
-            c.Status(503)
-            return
-        }
-        c.Status(200)
-    })
-}
-```
-
-## Trusted Proxies
-
-Configure trusted proxies to prevent IP spoofing.
-
-```go
-// Trust specific CIDR ranges (e.g., internal load balancers)
-router.SetTrustedProxies([]string{
-    "10.0.0.0/8",
-    "172.16.0.0/12",
-    "192.168.0.0/16",
-})
-
-// Trust no proxies (direct connections only)
-router.SetTrustedProxies(nil)
-
-// Trust the platform header
-router.TrustedPlatform = gin.PlatformCloudflare    // CF-Connecting-IP
-router.TrustedPlatform = gin.PlatformGoogleAppEngine // X-Appengine-Remote-Addr
-router.TrustedPlatform = "X-Real-Ip"                // Custom header
-```
-
-## Docker Multi-Stage Build
-
-```dockerfile
-# Build stage
-FROM golang:1.22-alpine AS builder
-
-WORKDIR /app
-COPY go.mod go.sum ./
-RUN go mod download
-
-COPY . .
-RUN CGO_ENABLED=0 GOOS=linux go build -trimpath -ldflags='-s -w' -o /server ./cmd/server
-
-# Runtime stage
-FROM alpine:3.19
-
-RUN apk --no-cache add ca-certificates tzdata
-RUN adduser -D -g '' appuser
-
-COPY --from=builder /server /server
-
-USER appuser
-
-EXPOSE 8080
-
-HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
-    CMD wget --no-verbose --tries=1 --spider http://localhost:8080/healthz || exit 1
-
-ENTRYPOINT ["/server"]
-```
-
-## Environment Configuration
-
-```go
-type Config struct {
-    Port         string `env:"PORT" envDefault:"8080"`
-    GinMode      string `env:"GIN_MODE" envDefault:"release"`
-    DatabaseURL  string `env:"DATABASE_URL,required"`
-    JWTSecret    string `env:"JWT_SECRET,required"`
-    CORSOrigins  string `env:"CORS_ORIGINS" envDefault:""`
-    ReadTimeout  int    `env:"READ_TIMEOUT_SECS" envDefault:"10"`
-    WriteTimeout int    `env:"WRITE_TIMEOUT_SECS" envDefault:"10"`
-    RateLimit    int    `env:"RATE_LIMIT_RPM" envDefault:"100"`
-}
-
-func loadConfig() (*Config, error) {
-    cfg := &Config{}
-    if err := env.Parse(cfg); err != nil {
-        return nil, fmt.Errorf("parse config: %w", err)
-    }
-    return cfg, nil
-}
-
-func main() {
-    cfg, err := loadConfig()
-    if err != nil {
-        log.Fatalf("Failed to load config: %v", err)
-    }
-
-    gin.SetMode(cfg.GinMode)
-    router := setupRouter(cfg)
-
-    srv := &http.Server{
-        Addr:         ":" + cfg.Port,
-        Handler:      router,
-        ReadTimeout:  time.Duration(cfg.ReadTimeout) * time.Second,
-        WriteTimeout: time.Duration(cfg.WriteTimeout) * time.Second,
-    }
-    // ...
-}
-```
-
-## Reverse Proxy Configuration
-
-### Nginx
-
-```nginx
-upstream gin_app {
-    server 127.0.0.1:8080;
-    keepalive 32;
-}
-
-server {
-    listen 443 ssl http2;
-    server_name api.example.com;
-
-    ssl_certificate     /etc/ssl/certs/api.pem;
-    ssl_certificate_key /etc/ssl/private/api.key;
-
-    location / {
-        proxy_pass http://gin_app;
-        proxy_http_version 1.1;
-        proxy_set_header Connection "";
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header X-Forwarded-Proto $scheme;
-        proxy_set_header X-Request-ID $request_id;
-
-        proxy_read_timeout 30s;
-        proxy_send_timeout 30s;
-        proxy_connect_timeout 5s;
-    }
-}
-```
-
-## Kubernetes Deployment
-
-```yaml
-apiVersion: apps/v1
-kind: Deployment
-metadata:
-  name: gin-api
-spec:
-  replicas: 3
-  selector:
-    matchLabels:
-      app: gin-api
-  template:
-    metadata:
-      labels:
-        app: gin-api
-    spec:
-      containers:
-        - name: gin-api
-          image: registry.example.com/gin-api:latest
-          ports:
-            - containerPort: 8080
-          env:
-            - name: GIN_MODE
-              value: release
-            - name: DATABASE_URL
-              valueFrom:
-                secretKeyRef:
-                  name: gin-api-secrets
-                  key: database-url
-          livenessProbe:
-            httpGet:
-              path: /healthz
-              port: 8080
-            initialDelaySeconds: 5
-            periodSeconds: 10
-          readinessProbe:
-            httpGet:
-              path: /readyz
-              port: 8080
-            initialDelaySeconds: 5
-            periodSeconds: 5
-          resources:
-            requests:
-              cpu: 100m
-              memory: 128Mi
-            limits:
-              cpu: 500m
-              memory: 256Mi
-      terminationGracePeriodSeconds: 30
-```
-
-## Production Checklist
-
-| Area | Check |
-| --- | --- |
-| Mode | `gin.SetMode(gin.ReleaseMode)` |
-| Timeouts | ReadTimeout, WriteTimeout, IdleTimeout set |
-| Shutdown | Graceful shutdown with signal handling |
-| Proxies | `SetTrustedProxies` configured |
-| Health | `/healthz` and `/readyz` endpoints |
-| Secrets | Environment variables, not config files |
-| Logging | Structured JSON, no debug logs |
-| Docker | Multi-stage build, non-root user |
-| Limits | MaxHeaderBytes, body size limits |
-| TLS | Terminated at proxy or with `RunTLS` |