@cubis/foundry 0.3.82 → 0.3.84

package/workflows/workflows/agent-environment-setup/platforms/antigravity/skills/gin-golang/references/routing.md

@@ -1,245 +0,0 @@
-# Gin Routing
-
-## Route Registration
-
-Gin uses a radix tree router for fast path matching. Routes are registered with method-specific functions on the engine or a router group.
-
-```go
-router := gin.New()
-
-// Method-specific routes
-router.GET("/users", listUsers)
-router.POST("/users", createUser)
-router.GET("/users/:id", getUser)
-router.PUT("/users/:id", updateUser)
-router.DELETE("/users/:id", deleteUser)
-router.PATCH("/users/:id", patchUser)
-router.OPTIONS("/users", corsOptions)
-router.HEAD("/users", headUsers)
-
-// Any method
-router.Any("/fallback", fallbackHandler)
-
-// Handle specific methods
-router.Handle("PURGE", "/cache/:key", purgeCache)
-```
-
-## Path Parameters
-
-Parameters use `:name` for single segments and `*name` for wildcard catch-all.
-
-```go
-// Required parameter
-router.GET("/users/:id", func(c *gin.Context) {
-    id := c.Param("id") // string, always present
-    c.JSON(200, gin.H{"id": id})
-})
-
-// Multiple parameters
-router.GET("/orgs/:orgID/repos/:repoID", func(c *gin.Context) {
-    orgID := c.Param("orgID")
-    repoID := c.Param("repoID")
-    c.JSON(200, gin.H{"org": orgID, "repo": repoID})
-})
-
-// Wildcard catch-all (must be last segment)
-router.GET("/files/*filepath", func(c *gin.Context) {
-    path := c.Param("filepath") // includes leading /
-    c.String(200, "Serving: %s", path)
-})
-
-// NOTE: Gin does not support optional parameters.
-// Use separate routes or query parameters instead.
-```
-
-## Route Groups
-
-Groups share a prefix and middleware. Nested groups inherit from parents.
-
-```go
-// Public routes
-public := router.Group("/")
-{
-    public.GET("/health", healthHandler)
-    public.GET("/version", versionHandler)
-}
-
-// API v1 with auth
-v1 := router.Group("/api/v1")
-v1.Use(authMiddleware())
-{
-    // Users resource
-    users := v1.Group("/users")
-    {
-        users.GET("", listUsers)
-        users.POST("", createUser)
-        users.GET("/:id", getUser)
-        users.PUT("/:id", updateUser)
-        users.DELETE("/:id", deleteUser)
-    }
-
-    // Products resource
-    products := v1.Group("/products")
-    products.Use(rateLimitMiddleware()) // Additional middleware
-    {
-        products.GET("", listProducts)
-        products.POST("", createProduct)
-        products.GET("/:id", getProduct)
-    }
-}
-
-// Admin routes with stricter auth
-admin := router.Group("/admin")
-admin.Use(authMiddleware(), adminOnlyMiddleware())
-{
-    admin.GET("/stats", adminStats)
-    admin.POST("/settings", updateSettings)
-}
-```
-
-## Query Parameters
-
-```go
-router.GET("/search", func(c *gin.Context) {
-    // Single value with default
-    q := c.DefaultQuery("q", "")
-    page := c.DefaultQuery("page", "1")
-
-    // Required value (returns "" if missing)
-    sort := c.Query("sort")
-
-    // Array values: /search?tag=go&tag=fiber
-    tags := c.QueryArray("tag")
-
-    // Map values: /search?filter[status]=active&filter[type]=post
-    filters := c.QueryMap("filter")
-
-    // Parse into struct
-    var params SearchParams
-    if err := c.ShouldBindQuery(&params); err != nil {
-        c.JSON(400, gin.H{"error": err.Error()})
-        return
-    }
-})
-
-type SearchParams struct {
-    Query  string `form:"q" binding:"required"`
-    Page   int    `form:"page" binding:"min=1"`
-    Limit  int    `form:"limit" binding:"min=1,max=100"`
-    SortBy string `form:"sort_by" binding:"oneof=created_at updated_at name"`
-}
-```
-
-## Request Body Binding
-
-Gin binds request bodies based on Content-Type header.
-
-```go
-// JSON body
-func createUser(c *gin.Context) {
-    var req CreateUserRequest
-    if err := c.ShouldBindJSON(&req); err != nil {
-        handleValidationError(c, err)
-        return
-    }
-    // req is populated and validated
-}
-
-// Form data
-func uploadFile(c *gin.Context) {
-    var form UploadForm
-    if err := c.ShouldBind(&form); err != nil { // Auto-detects content type
-        handleValidationError(c, err)
-        return
-    }
-}
-
-// URI parameters
-func getUser(c *gin.Context) {
-    var uri UserURI
-    if err := c.ShouldBindUri(&uri); err != nil {
-        c.JSON(400, gin.H{"error": "Invalid ID"})
-        return
-    }
-}
-
-type UserURI struct {
-    ID string `uri:"id" binding:"required,uuid"`
-}
-```
-
-## Response Methods
-
-```go
-// JSON response
-c.JSON(200, gin.H{"message": "ok"})
-c.JSON(200, user) // struct serialization
-
-// String response
-c.String(200, "Hello %s", name)
-
-// Data response
-c.Data(200, "application/octet-stream", binaryData)
-
-// File response
-c.File("/path/to/file.pdf")
-c.FileAttachment("/path/to/file.pdf", "download.pdf")
-
-// Redirect
-c.Redirect(301, "/new-location")
-
-// Stream
-c.Stream(func(w io.Writer) bool {
-    fmt.Fprintf(w, "data: %s\n\n", event)
-    return keepStreaming
-})
-
-// No content
-c.Status(204)
-
-// Set headers before response
-c.Header("X-Custom", "value")
-c.Header("Cache-Control", "no-store")
-```
-
-## Static Files
-
-```go
-// Serve directory
-router.Static("/assets", "./public")
-
-// Serve single file
-router.StaticFile("/favicon.ico", "./resources/favicon.ico")
-
-// Serve filesystem
-router.StaticFS("/more_static", http.Dir("my_file_system"))
-```
-
-## NoRoute and NoMethod Handlers
-
-```go
-// Custom 404 handler
-router.NoRoute(func(c *gin.Context) {
-    c.JSON(404, gin.H{
-        "code":    "NOT_FOUND",
-        "message": fmt.Sprintf("Route %s %s not found", c.Request.Method, c.Request.URL.Path),
-    })
-})
-
-// Custom 405 handler
-router.NoMethod(func(c *gin.Context) {
-    c.JSON(405, gin.H{
-        "code":    "METHOD_NOT_ALLOWED",
-        "message": fmt.Sprintf("Method %s not allowed", c.Request.Method),
-    })
-})
-```
-
-## Route Patterns Summary
-
-| Pattern | Example | Match | No Match |
-| --- | --- | --- | --- |
-| `/literal` | `/users` | `/users` | `/users/` |
-| `/:param` | `/users/:id` | `/users/42` | `/users/` |
-| `/*wildcard` | `/files/*path` | `/files/a/b/c` | `/files` |
-| Group prefix | `v1.Group("/users")` | `/api/v1/users` | `/users` |

package/workflows/workflows/agent-environment-setup/platforms/antigravity/skills/gin-golang/references/testing.md

@@ -1,338 +0,0 @@
-# Gin Testing
-
-## Testing Approaches
-
-Gin supports two testing styles: integration tests with `httptest.NewRecorder` and `router.ServeHTTP`, and unit tests with `gin.CreateTestContext`. Use integration tests for full-stack behavior and unit tests for isolated handler logic.
-
-## Integration Tests with httptest
-
-The standard approach registers routes on a test engine and calls `ServeHTTP`.
-
-```go
-func setupTestRouter() *gin.Engine {
-    gin.SetMode(gin.TestMode)
-    router := gin.New()
-    router.Use(gin.Recovery())
-
-    // Register the same middleware and routes as production
-    api := router.Group("/api/v1")
-    api.Use(authMiddleware())
-    {
-        api.GET("/products", listProducts)
-        api.POST("/products", createProduct)
-        api.GET("/products/:id", getProduct)
-        api.PUT("/products/:id", updateProduct)
-        api.DELETE("/products/:id", deleteProduct)
-    }
-
-    return router
-}
-
-func TestListProducts(t *testing.T) {
-    router := setupTestRouter()
-
-    w := httptest.NewRecorder()
-    req := httptest.NewRequest("GET", "/api/v1/products", nil)
-    req.Header.Set("Authorization", "Bearer "+testToken)
-
-    router.ServeHTTP(w, req)
-
-    assert.Equal(t, 200, w.Code)
-
-    var products []Product
-    err := json.Unmarshal(w.Body.Bytes(), &products)
-    require.NoError(t, err)
-    assert.GreaterOrEqual(t, len(products), 0)
-}
-```
-
-## Table-Driven Tests
-
-Cover multiple scenarios with shared setup.
-
-```go
-func TestCreateProduct(t *testing.T) {
-    router := setupTestRouter()
-
-    tests := []struct {
-        name       string
-        body       interface{}
-        token      string
-        wantStatus int
-        wantCode   string
-        wantFields []string // expected validation error fields
-    }{
-        {
-            name: "valid product",
-            body: CreateProductRequest{
-                Name:     "Widget Pro",
-                Slug:     "widget-pro",
-                Price:    29.99,
-                Category: "electronics",
-                SKU:      "ABCDEFGHIJ",
-            },
-            token:      validToken,
-            wantStatus: 201,
-        },
-        {
-            name:       "missing required fields",
-            body:       map[string]string{},
-            token:      validToken,
-            wantStatus: 400,
-            wantCode:   "VALIDATION_ERROR",
-            wantFields: []string{"name", "slug", "price", "category", "sku"},
-        },
-        {
-            name: "invalid slug format",
-            body: map[string]interface{}{
-                "name": "Widget", "slug": "BAD SLUG!",
-                "price": 10, "category": "electronics", "sku": "ABCDEFGHIJ",
-            },
-            token:      validToken,
-            wantStatus: 400,
-            wantCode:   "VALIDATION_ERROR",
-            wantFields: []string{"slug"},
-        },
-        {
-            name: "price out of range",
-            body: map[string]interface{}{
-                "name": "Widget", "slug": "widget",
-                "price": -5, "category": "electronics", "sku": "ABCDEFGHIJ",
-            },
-            token:      validToken,
-            wantStatus: 400,
-            wantCode:   "VALIDATION_ERROR",
-            wantFields: []string{"price"},
-        },
-        {
-            name: "invalid category",
-            body: map[string]interface{}{
-                "name": "Widget", "slug": "widget",
-                "price": 10, "category": "invalid", "sku": "ABCDEFGHIJ",
-            },
-            token:      validToken,
-            wantStatus: 400,
-            wantCode:   "VALIDATION_ERROR",
-            wantFields: []string{"category"},
-        },
-        {
-            name:       "no auth token",
-            body:       CreateProductRequest{Name: "Widget"},
-            token:      "",
-            wantStatus: 401,
-            wantCode:   "UNAUTHORIZED",
-        },
-    }
-
-    for _, tt := range tests {
-        t.Run(tt.name, func(t *testing.T) {
-            bodyBytes, _ := json.Marshal(tt.body)
-            w := httptest.NewRecorder()
-            req := httptest.NewRequest("POST", "/api/v1/products",
-                bytes.NewReader(bodyBytes))
-            req.Header.Set("Content-Type", "application/json")
-            if tt.token != "" {
-                req.Header.Set("Authorization", "Bearer "+tt.token)
-            }
-
-            router.ServeHTTP(w, req)
-
-            assert.Equal(t, tt.wantStatus, w.Code)
-
-            if tt.wantCode != "" {
-                var resp ErrorResponse
-                require.NoError(t, json.Unmarshal(w.Body.Bytes(), &resp))
-                assert.Equal(t, tt.wantCode, resp.Code)
-
-                if len(tt.wantFields) > 0 {
-                    respFields := make([]string, len(resp.Details))
-                    for i, d := range resp.Details {
-                        respFields[i] = d.Field
-                    }
-                    for _, f := range tt.wantFields {
-                        assert.Contains(t, respFields, f, "expected field error for %s", f)
-                    }
-                }
-            }
-        })
-    }
-}
-```
-
-## Unit Tests with gin.CreateTestContext
-
-For testing handlers in isolation without routing.
-
-```go
-func TestGetProductHandler(t *testing.T) {
-    w := httptest.NewRecorder()
-    c, _ := gin.CreateTestContext(w)
-
-    // Set up the context as if the router had parsed the request
-    c.Params = gin.Params{{Key: "id", Value: "42"}}
-    c.Request = httptest.NewRequest("GET", "/api/v1/products/42", nil)
-
-    // Set user in context (as if auth middleware had run)
-    c.Set("user", &UserClaims{ID: "user-1", Role: "admin"})
-
-    // Call handler directly
-    getProduct(c)
-
-    assert.Equal(t, 200, w.Code)
-
-    var product Product
-    require.NoError(t, json.Unmarshal(w.Body.Bytes(), &product))
-    assert.Equal(t, "42", product.ID)
-}
-```
-
-## Testing Middleware
-
-Test middleware in isolation to verify behavior independently of handlers.
-
-```go
-func TestAuthMiddleware(t *testing.T) {
-    gin.SetMode(gin.TestMode)
-
-    tests := []struct {
-        name       string
-        auth       string
-        wantStatus int
-        wantAbort  bool
-    }{
-        {"valid token", "Bearer " + validToken, 200, false},
-        {"missing header", "", 401, true},
-        {"wrong prefix", "Token " + validToken, 401, true},
-        {"expired token", "Bearer " + expiredToken, 401, true},
-        {"malformed token", "Bearer not.a.jwt", 401, true},
-    }
-
-    for _, tt := range tests {
-        t.Run(tt.name, func(t *testing.T) {
-            w := httptest.NewRecorder()
-            c, engine := gin.CreateTestContext(w)
-            c.Request = httptest.NewRequest("GET", "/test", nil)
-            if tt.auth != "" {
-                c.Request.Header.Set("Authorization", tt.auth)
-            }
-
-            handlerCalled := false
-            engine.Use(authMiddleware())
-            engine.GET("/test", func(c *gin.Context) {
-                handlerCalled = true
-                c.Status(200)
-            })
-
-            engine.ServeHTTP(w, c.Request)
-
-            assert.Equal(t, tt.wantStatus, w.Code)
-            if tt.wantAbort {
-                assert.False(t, handlerCalled, "handler should not be called")
-            } else {
-                assert.True(t, handlerCalled, "handler should be called")
-            }
-        })
-    }
-}
-```
-
-## Testing with Database
-
-```go
-func setupTestDB(t *testing.T) *sql.DB {
-    t.Helper()
-    db, err := sql.Open("sqlite3", ":memory:")
-    require.NoError(t, err)
-
-    // Run migrations
-    _, err = db.Exec(schema)
-    require.NoError(t, err)
-
-    t.Cleanup(func() { db.Close() })
-    return db
-}
-
-func setupTestRouterWithDB(t *testing.T) *gin.Engine {
-    db := setupTestDB(t)
-    svc := NewProductService(db)
-
-    gin.SetMode(gin.TestMode)
-    router := gin.New()
-    RegisterProductRoutes(router, svc)
-    return router
-}
-```
-
-## Benchmark Tests
-
-```go
-func BenchmarkListProducts(b *testing.B) {
-    gin.SetMode(gin.ReleaseMode)
-    router := setupBenchRouter()
-
-    req := httptest.NewRequest("GET", "/api/v1/products", nil)
-    req.Header.Set("Authorization", "Bearer "+benchToken)
-
-    b.ReportAllocs()
-    b.ResetTimer()
-
-    for i := 0; i < b.N; i++ {
-        w := httptest.NewRecorder()
-        router.ServeHTTP(w, req)
-    }
-}
-```
-
-## Test Helpers
-
-```go
-// performRequest is a reusable test helper
-func performRequest(t *testing.T, router *gin.Engine, method, path string, body interface{}, token string) *httptest.ResponseRecorder {
-    t.Helper()
-
-    var bodyReader io.Reader
-    if body != nil {
-        b, err := json.Marshal(body)
-        require.NoError(t, err)
-        bodyReader = bytes.NewReader(b)
-    }
-
-    w := httptest.NewRecorder()
-    req := httptest.NewRequest(method, path, bodyReader)
-    req.Header.Set("Content-Type", "application/json")
-    if token != "" {
-        req.Header.Set("Authorization", "Bearer "+token)
-    }
-
-    router.ServeHTTP(w, req)
-    return w
-}
-
-// decodeResponse is a generic JSON decoder for test responses
-func decodeResponse[T any](t *testing.T, w *httptest.ResponseRecorder) T {
-    t.Helper()
-    var result T
-    require.NoError(t, json.Unmarshal(w.Body.Bytes(), &result))
-    return result
-}
-
-// assertError checks error response shape
-func assertError(t *testing.T, w *httptest.ResponseRecorder, status int, code string) {
-    t.Helper()
-    assert.Equal(t, status, w.Code)
-    var resp ErrorResponse
-    require.NoError(t, json.Unmarshal(w.Body.Bytes(), &resp))
-    assert.Equal(t, code, resp.Code)
-}
-```
-
-## Test Mode
-
-Always set Gin to test mode in tests to suppress debug output.
-
-```go
-func TestMain(m *testing.M) {
-    gin.SetMode(gin.TestMode)
-    os.Exit(m.Run())
-}
-```