@cubis/foundry 0.3.82 → 0.3.84

package/workflows/skills/go-fiber/references/middleware.md

@@ -1,245 +0,0 @@
-# Fiber v3 Middleware
-
-## Middleware Fundamentals
-
-Fiber middleware is any `fiber.Handler` that calls `c.Next()` to pass control downstream. Middleware registered with `app.Use()` runs for every request. Group-level middleware runs only for routes within that group.
-
-```go
-// Basic middleware signature
-func myMiddleware(c fiber.Ctx) error {
-    // Pre-processing (before handler)
-    start := time.Now()
-
-    // Continue to next middleware or handler
-    err := c.Next()
-
-    // Post-processing (after handler)
-    duration := time.Since(start)
-    log.Printf("Request took %v", duration)
-
-    return err
-}
-
-app.Use(myMiddleware)
-```
-
-## Middleware Execution Order
-
-Middleware runs in registration order. Place middleware that must wrap all requests first.
-
-```go
-// Correct order for production
-app.Use(recover.New())          // 1. Catch panics (outermost)
-app.Use(requestid.New())        // 2. Assign request IDs
-app.Use(logger.New())           // 3. Log all requests
-app.Use(cors.New(corsConfig))   // 4. Handle CORS preflight
-app.Use(helmet.New())           // 5. Security headers
-app.Use(limiter.New(limConfig)) // 6. Rate limiting
-
-// Group-level middleware runs after app-level
-api := app.Group("/api")
-api.Use(jwtAuthMiddleware)      // 7. Auth only for API routes
-```
-
-## Built-in Middleware
-
-### Recover
-
-Catches panics and converts them to 500 responses.
-
-```go
-import "github.com/gofiber/fiber/v3/middleware/recover"
-
-app.Use(recover.New(recover.Config{
-    EnableStackTrace: true, // Include stack in error handler
-    StackTraceHandler: func(c fiber.Ctx, e interface{}) {
-        log.Printf("PANIC: %v\n%s", e, debug.Stack())
-    },
-}))
-```
-
-### Request ID
-
-Generates unique request identifiers for tracing.
-
-```go
-import "github.com/gofiber/fiber/v3/middleware/requestid"
-
-app.Use(requestid.New(requestid.Config{
-    Header: "X-Request-Id",
-    Generator: func() string {
-        return uuid.New().String()
-    },
-}))
-
-// Access in handler
-func handler(c fiber.Ctx) error {
-    reqID := c.Locals("requestid").(string)
-    return c.JSON(fiber.Map{"request_id": reqID})
-}
-```
-
-### CORS
-
-Configures Cross-Origin Resource Sharing headers.
-
-```go
-import "github.com/gofiber/fiber/v3/middleware/cors"
-
-app.Use(cors.New(cors.Config{
-    AllowOrigins:     "https://app.example.com, https://admin.example.com",
-    AllowMethods:     "GET,POST,PUT,DELETE,OPTIONS",
-    AllowHeaders:     "Origin, Content-Type, Authorization",
-    AllowCredentials: true,
-    MaxAge:           3600,
-}))
-```
-
-### Helmet
-
-Sets security-related HTTP headers.
-
-```go
-import "github.com/gofiber/fiber/v3/middleware/helmet"
-
-app.Use(helmet.New(helmet.Config{
-    XSSProtection:         "1; mode=block",
-    ContentTypeNosniff:    "nosniff",
-    XFrameOptions:         "DENY",
-    ReferrerPolicy:        "strict-origin-when-cross-origin",
-    CrossOriginEmbedderPolicy: "require-corp",
-    CrossOriginOpenerPolicy:   "same-origin",
-    CrossOriginResourcePolicy: "same-origin",
-    ContentSecurityPolicy: "default-src 'self'; script-src 'self'",
-}))
-```
-
-### Rate Limiter
-
-Limits request rate per client.
-
-```go
-import "github.com/gofiber/fiber/v3/middleware/limiter"
-
-app.Use(limiter.New(limiter.Config{
-    Max:        100,
-    Expiration: 1 * time.Minute,
-    KeyGenerator: func(c fiber.Ctx) string {
-        return c.IP() // Rate limit per IP
-    },
-    LimitReached: func(c fiber.Ctx) error {
-        return c.Status(429).JSON(fiber.Map{
-            "code":    "RATE_LIMIT_EXCEEDED",
-            "message": "Too many requests, please try again later",
-        })
-    },
-    Storage: redisStorage, // Use Redis for distributed deployments
-}))
-```
-
-### Logger
-
-Structured request logging.
-
-```go
-import "github.com/gofiber/fiber/v3/middleware/logger"
-
-app.Use(logger.New(logger.Config{
-    Format:     "${time} | ${status} | ${latency} | ${ip} | ${method} ${path}\n",
-    TimeFormat: time.RFC3339,
-    TimeZone:   "UTC",
-    Output:     os.Stdout,
-}))
-```
-
-## Custom Middleware Patterns
-
-### Authentication Middleware
-
-```go
-func jwtAuthMiddleware(c fiber.Ctx) error {
-    header := c.Get("Authorization")
-    if !strings.HasPrefix(header, "Bearer ") {
-        return fiber.NewError(fiber.StatusUnauthorized, "Missing or invalid token")
-    }
-
-    token := strings.TrimPrefix(header, "Bearer ")
-    claims, err := validateJWT(token)
-    if err != nil {
-        return fiber.NewError(fiber.StatusUnauthorized, "Invalid token")
-    }
-
-    c.Locals("user", claims)
-    return c.Next()
-}
-```
-
-### Timing Middleware
-
-```go
-func timingMiddleware(c fiber.Ctx) error {
-    start := time.Now()
-    err := c.Next()
-    duration := time.Since(start)
-    c.Set("X-Response-Time", duration.String())
-    return err
-}
-```
-
-### Conditional Middleware
-
-```go
-func skipForHealthCheck(handler fiber.Handler) fiber.Handler {
-    return func(c fiber.Ctx) error {
-        if c.Path() == "/health" {
-            return c.Next()
-        }
-        return handler(c)
-    }
-}
-
-app.Use(skipForHealthCheck(jwtAuthMiddleware))
-```
-
-## Middleware with Configuration
-
-Follow the config-pattern convention used by official Fiber middleware.
-
-```go
-type RateLimitConfig struct {
-    Max        int
-    Window     time.Duration
-    KeyFunc    func(fiber.Ctx) string
-    SkipFunc   func(fiber.Ctx) bool
-}
-
-func NewRateLimit(config ...RateLimitConfig) fiber.Handler {
-    cfg := RateLimitConfig{
-        Max:    100,
-        Window: time.Minute,
-        KeyFunc: func(c fiber.Ctx) string { return c.IP() },
-    }
-    if len(config) > 0 {
-        cfg = config[0]
-    }
-
-    return func(c fiber.Ctx) error {
-        if cfg.SkipFunc != nil && cfg.SkipFunc(c) {
-            return c.Next()
-        }
-        key := cfg.KeyFunc(c)
-        // Rate limiting logic using key...
-        return c.Next()
-    }
-}
-```
-
-## Common Mistakes
-
-| Mistake | Fix |
-| --- | --- |
-| Forgetting `c.Next()` | Middleware must call `c.Next()` or return a response |
-| Recovery not first | Place `recover.New()` before all other middleware |
-| Global auth middleware | Apply auth at the group level, not app level |
-| Ignoring `c.Next()` error | Check and return the error from `c.Next()` |
-| Modifying response after send | Check if response has been committed before writing |

package/workflows/skills/go-fiber/references/performance.md

@@ -1,228 +0,0 @@
-# Fiber v3 Performance
-
-## Why Fiber is Fast
-
-Fiber is built on `fasthttp`, which avoids the per-request allocations that `net/http` makes. Key differences include object reuse through sync.Pool, zero-copy request parsing, and a radix tree router with no allocations on matched routes.
-
-## App Configuration for Performance
-
-```go
-app := fiber.New(fiber.Config{
-    // Prefork spawns multiple processes for multi-core utilization
-    Prefork: false, // Enable only for pure HTTP workloads without shared state
-
-    // Server tuning
-    ReadTimeout:           10 * time.Second,
-    WriteTimeout:          10 * time.Second,
-    IdleTimeout:           120 * time.Second,
-    ReadBufferSize:        8192,  // Increase for large headers
-    WriteBufferSize:       4096,
-    BodyLimit:             4 * 1024 * 1024, // 4MB
-    Concurrency:           256 * 1024,      // Max concurrent connections
-    DisableStartupMessage: true,            // Reduce log noise in production
-
-    // Reduce allocations
-    DisableDefaultContentType: true,  // Don't set Content-Type on every response
-    StreamRequestBody:         true,  // Stream large uploads instead of buffering
-    ReduceMemoryUsage:         false, // Only enable if memory-constrained
-})
-```
-
-## Prefork Mode
-
-Prefork spawns one process per CPU core. Each process has its own event loop and does not share memory with others.
-
-```go
-app := fiber.New(fiber.Config{
-    Prefork: true,
-})
-```
-
-**When to use prefork:**
-- CPU-bound workloads with minimal shared state
-- Static file serving at scale
-- Stateless API endpoints
-
-**When NOT to use prefork:**
-- WebSocket applications (connections are per-process)
-- In-memory caching (each process has its own cache)
-- Applications with shared mutable state
-
-## Response Optimization
-
-### Avoid unnecessary allocations
-
-```go
-// Bad: allocates a new map every request
-func handler(c fiber.Ctx) error {
-    return c.JSON(map[string]interface{}{
-        "status": "ok",
-        "data":   result,
-    })
-}
-
-// Better: use fiber.Map (type alias, but still allocates)
-func handler(c fiber.Ctx) error {
-    return c.JSON(fiber.Map{"status": "ok", "data": result})
-}
-
-// Best for static responses: pre-serialize
-var healthResponse = []byte(`{"status":"ok"}`)
-
-func healthHandler(c fiber.Ctx) error {
-    c.Set("Content-Type", "application/json")
-    return c.Send(healthResponse)
-}
-```
-
-### Use SendString for text responses
-
-```go
-// Slower: SendString converts to bytes internally
-func handler(c fiber.Ctx) error {
-    return c.SendString("OK")
-}
-
-// For high-throughput text endpoints, pre-convert
-var okBytes = []byte("OK")
-
-func handler(c fiber.Ctx) error {
-    return c.Send(okBytes)
-}
-```
-
-## JSON Serialization
-
-### Use a fast JSON library
-
-```go
-import "github.com/goccy/go-json"
-
-app := fiber.New(fiber.Config{
-    JSONEncoder: gojson.Marshal,
-    JSONDecoder: gojson.Unmarshal,
-})
-```
-
-Benchmarks show `goccy/go-json` and `bytedance/sonic` can be 2-3x faster than `encoding/json` for large payloads.
-
-## Middleware Performance
-
-### Skip unnecessary middleware
-
-```go
-// Skip auth for public endpoints
-app.Use(limiter.New(limiter.Config{
-    Next: func(c fiber.Ctx) bool {
-        return c.Path() == "/health" || c.Path() == "/metrics"
-    },
-    Max:        100,
-    Expiration: time.Minute,
-}))
-```
-
-### Minimize middleware per request
-
-Each middleware adds function call overhead. For hot paths, consider:
-- Using the `Next` function to skip middleware conditionally
-- Combining related middleware into one (e.g., auth + rate limit)
-- Placing expensive middleware only on routes that need it
-
-## Connection Pooling
-
-### Database connections
-
-```go
-db, err := sql.Open("postgres", dsn)
-db.SetMaxOpenConns(25)          // Match expected concurrency
-db.SetMaxIdleConns(25)          // Keep all connections warm
-db.SetConnMaxLifetime(5 * time.Minute) // Rotate connections
-db.SetConnMaxIdleTime(1 * time.Minute) // Close idle connections
-```
-
-### HTTP client reuse
-
-```go
-// Bad: creates a new client per request
-func handler(c fiber.Ctx) error {
-    resp, _ := http.Get("https://api.example.com/data")
-    // ...
-}
-
-// Good: reuse client with connection pooling
-var httpClient = &http.Client{
-    Transport: &http.Transport{
-        MaxIdleConns:        100,
-        MaxIdleConnsPerHost: 10,
-        IdleConnTimeout:     90 * time.Second,
-    },
-    Timeout: 10 * time.Second,
-}
-```
-
-## Profiling with pprof
-
-```go
-import "github.com/gofiber/fiber/v3/middleware/pprof"
-
-// Only enable in non-production or behind admin auth
-if os.Getenv("ENABLE_PPROF") == "true" {
-    app.Use(pprof.New())
-}
-```
-
-Access profiles at:
-- `/debug/pprof/` -- Index
-- `/debug/pprof/heap` -- Heap allocations
-- `/debug/pprof/goroutine` -- Goroutine stacks
-- `/debug/pprof/profile?seconds=30` -- CPU profile
-
-### Analyzing with go tool pprof
-
-```bash
-# CPU profile
-go tool pprof http://localhost:8080/debug/pprof/profile?seconds=30
-
-# Heap profile
-go tool pprof http://localhost:8080/debug/pprof/heap
-
-# Goroutine dump
-go tool pprof http://localhost:8080/debug/pprof/goroutine
-```
-
-## Benchmark Comparison
-
-Run benchmarks to compare implementations:
-
-```go
-func BenchmarkJSONResponse(b *testing.B) {
-    app := fiber.New(fiber.Config{
-        JSONEncoder: gojson.Marshal,
-    })
-    app.Get("/bench", func(c fiber.Ctx) error {
-        return c.JSON(testPayload)
-    })
-
-    req := httptest.NewRequest("GET", "/bench", nil)
-
-    b.ReportAllocs()
-    b.ResetTimer()
-    for i := 0; i < b.N; i++ {
-        app.Test(req, fiber.TestConfig{Timeout: 0})
-    }
-}
-```
-
-## Performance Checklist
-
-| Area | Check |
-| --- | --- |
-| App config | Timeouts, body limits, concurrency set |
-| JSON | Using goccy/go-json or sonic |
-| Middleware | Minimal chain, skip where possible |
-| Database | Connection pool sized to concurrency |
-| HTTP client | Reused with transport pool |
-| Static | Compression and cache headers enabled |
-| Profiling | pprof available in staging |
-| Benchmarks | b.ReportAllocs on critical paths |
-| Memory | No goroutine leaks, bounded workers |

package/workflows/skills/go-fiber/references/routing.md

@@ -1,180 +0,0 @@
-# Fiber v3 Routing
-
-## Route Registration
-
-Fiber uses an Express-inspired API for route registration. Routes are matched in registration order against a radix tree for zero-allocation lookups.
-
-```go
-app := fiber.New()
-
-// Basic routes
-app.Get("/", homeHandler)
-app.Post("/users", createUser)
-app.Put("/users/:id", updateUser)
-app.Delete("/users/:id", deleteUser)
-app.Patch("/users/:id", patchUser)
-
-// All methods
-app.All("/fallback", catchAllHandler)
-
-// Custom method
-app.Add("PURGE", "/cache/:key", purgeCache)
-```
-
-## Route Parameters
-
-Parameters are extracted from the URL path using `:name` syntax. Optional parameters use `:name?`. Wildcard catches everything with `*`.
-
-```go
-// Required parameter
-app.Get("/users/:id", func(c fiber.Ctx) error {
-    id := c.Params("id") // string
-    return c.SendString("User: " + id)
-})
-
-// Integer parameter with built-in constraint
-app.Get("/posts/:id<int>", func(c fiber.Ctx) error {
-    id, err := c.ParamsInt("id")
-    if err != nil {
-        return fiber.NewError(fiber.StatusBadRequest, "Invalid ID")
-    }
-    return c.JSON(fiber.Map{"id": id})
-})
-
-// Optional parameter
-app.Get("/files/:name?", func(c fiber.Ctx) error {
-    name := c.Params("name", "index.html") // default value
-    return c.SendString(name)
-})
-
-// Wildcard
-app.Get("/assets/*", func(c fiber.Ctx) error {
-    path := c.Params("*") // everything after /assets/
-    return c.SendFile("./public/" + path)
-})
-```
-
-## Route Groups
-
-Groups share a common prefix and middleware. Nested groups inherit parent middleware.
-
-```go
-// API version group
-api := app.Group("/api")
-api.Use(requestIDMiddleware)
-
-// v1 group inherits /api prefix and requestID middleware
-v1 := api.Group("/v1")
-v1.Use(jwtAuthMiddleware)
-
-// Nested resource
-users := v1.Group("/users")
-users.Get("/", listUsers)         // GET /api/v1/users
-users.Post("/", createUser)       // POST /api/v1/users
-users.Get("/:id", getUser)        // GET /api/v1/users/:id
-users.Put("/:id", updateUser)     // PUT /api/v1/users/:id
-users.Delete("/:id", deleteUser)  // DELETE /api/v1/users/:id
-
-// Admin group with additional middleware
-admin := v1.Group("/admin")
-admin.Use(adminOnlyMiddleware)
-admin.Get("/stats", adminStats)   // GET /api/v1/admin/stats
-```
-
-## Route Naming and URL Generation
-
-Named routes allow URL generation without hardcoding paths.
-
-```go
-app.Get("/users/:id", getUser).Name("user.show")
-app.Post("/users", createUser).Name("user.create")
-
-// Build URL from name
-url, err := app.GetRoute("user.show").Params("id", "42")
-// url = "/users/42"
-```
-
-## Query Parameters
-
-```go
-app.Get("/search", func(c fiber.Ctx) error {
-    q := c.Query("q")                        // string
-    page := c.QueryInt("page", 1)            // int with default
-    limit := c.QueryInt("limit", 20)         // int with default
-
-    // Parse all query params into a struct
-    var filter SearchFilter
-    if err := c.QueryParser(&filter); err != nil {
-        return fiber.NewError(fiber.StatusBadRequest, "Invalid query parameters")
-    }
-
-    return c.JSON(results)
-})
-
-type SearchFilter struct {
-    Query    string   `query:"q"`
-    Page     int      `query:"page"`
-    Limit    int      `query:"limit"`
-    Tags     []string `query:"tags"`
-    SortBy   string   `query:"sort_by"`
-}
-```
-
-## Route Constraints
-
-Fiber supports built-in route constraints that validate parameters at the routing level.
-
-```go
-app.Get("/users/:id<int>", handler)          // integers only
-app.Get("/files/:name<alpha>", handler)      // alphabetic only
-app.Get("/posts/:slug<regex(^[a-z-]+$)>", handler)  // custom regex
-app.Get("/date/:date<datetime(2006-01-02)>", handler) // date format
-
-// Multiple constraints
-app.Get("/items/:id<int;min(1);max(9999)>", handler)
-```
-
-## Mount Sub-Applications
-
-Mount separate Fiber apps for modular architectures.
-
-```go
-// users/app.go
-func NewUsersApp() *fiber.App {
-    app := fiber.New()
-    app.Get("/", listUsers)
-    app.Post("/", createUser)
-    return app
-}
-
-// main.go
-usersApp := users.NewUsersApp()
-app.Mount("/api/v1/users", usersApp)
-```
-
-## Static File Serving
-
-```go
-// Serve directory
-app.Static("/assets", "./public", fiber.Static{
-    Compress:      true,
-    ByteRange:     true,
-    Browse:        false,
-    CacheDuration: 24 * time.Hour,
-    MaxAge:        86400,
-})
-
-// Single file
-app.Static("/favicon.ico", "./public/favicon.ico")
-```
-
-## Route Patterns Summary
-
-| Pattern | Example | Matches |
-| --- | --- | --- |
-| `/literal` | `/users` | Exact match |
-| `/:param` | `/users/:id` | Single segment |
-| `/:param?` | `/users/:id?` | Optional segment |
-| `/*` | `/files/*` | All remaining segments |
-| `/:param<int>` | `/users/:id<int>` | Integer only |
-| `/:param<regex(...)>` | `/slug/:s<regex(^[a-z-]+$)>` | Regex match |