codeforge-dev 1.4.0

package/.devcontainer/plugins/devs-marketplace/plugins/codedirective-skills/skills/fastapi/SKILL.md

@@ -0,0 +1,344 @@
+---
+name: fastapi
+description: >-
+  This skill should be used when the user asks to "build a FastAPI app",
+  "create a REST API with FastAPI", "add SSE streaming to FastAPI",
+  "use dependency injection in FastAPI", "define Pydantic models for an API",
+  "stream LLM responses with FastAPI", "add middleware to FastAPI",
+  "handle background tasks in FastAPI", or discusses FastAPI routing,
+  Pydantic v2 models, dependency injection, server-sent events,
+  or ASGI middleware.
+version: 0.1.0
+---
+
+# FastAPI Development
+
+## Mental Model
+
+FastAPI is a type-driven API framework where **path function signatures define the entire contract**. The function's parameters declare what the endpoint accepts (path params, query params, request body, dependencies); the return type annotation and `response_model` declare what it produces. Pydantic validates all input and output automatically -- there is no separate validation layer to configure.
+
+Dependency injection wires shared resources (database sessions, auth checks, config) into handlers without global state. Dependencies compose and nest, forming a directed graph resolved at request time.
+
+FastAPI runs on ASGI (Starlette), making every handler natively async-capable. This matters most for streaming -- SSE and chunked responses use async generators that yield data as it becomes available, keeping connections open without blocking worker threads.
+
+Assume FastAPI 0.100+ with Pydantic v2 for all new code. When modifying an existing codebase using Pydantic v1 patterns, ask whether to migrate or preserve the existing style.
+
+---
+
+## Routing and Path Operations
+
+Declare endpoints with HTTP method decorators on a FastAPI app or APIRouter. The decorator configures the operation; the function signature defines the contract:
+
+```python
+from fastapi import FastAPI, APIRouter, status
+from pydantic import BaseModel
+
+app = FastAPI()
+router = APIRouter(prefix="/items", tags=["items"])
+
+class ItemCreate(BaseModel):
+    name: str
+    price: float
+
+class ItemResponse(BaseModel):
+    id: int
+    name: str
+    price: float
+
+@router.post("/", status_code=status.HTTP_201_CREATED, response_model=ItemResponse)
+async def create_item(item: ItemCreate):
+    record = await save_to_db(item)
+    return record
+
+@router.get("/{item_id}")
+async def get_item(item_id: int, include_deleted: bool = False):
+    return await fetch_item(item_id, include_deleted)
+
+app.include_router(router)
+```
+
+Path parameters are extracted from the URL pattern and validated against the type annotation. Query parameters are any function parameters not found in the path. A parameter typed as a Pydantic model is parsed from the request body.
+
+Use `APIRouter` to organize endpoints by domain. Each router gets its own prefix and tags, then mounts onto the app with `include_router`. Keep one router per domain module.
+
+> **Deep dive:** See `references/routing-and-dependencies.md` for APIRouter organization, path operation configuration, WebSocket endpoints, nested/overridden dependencies, and testing patterns.
+
+---
+
+## Dependency Injection
+
+Dependencies are callables (functions or classes) declared with `Depends()`. FastAPI resolves them per-request, injecting the result into the handler parameter:
+
+```python
+from typing import Annotated
+from fastapi import Depends
+
+async def get_db():
+    db = SessionLocal()
+    try:
+        yield db
+    finally:
+        await db.close()
+
+DB = Annotated[AsyncSession, Depends(get_db)]
+
+@router.get("/items/{item_id}")
+async def get_item(item_id: int, db: DB):
+    return await db.get(Item, item_id)
+```
+
+Generator dependencies (using `yield`) provide setup/teardown semantics -- the code before `yield` runs at request start, after `yield` at request end. This replaces middleware for resource lifecycle management.
+
+Dependencies can depend on other dependencies, forming a graph. FastAPI resolves each unique dependency once per request (cached by default). Use `Annotated` type aliases to avoid repeating `Depends()` declarations across handlers.
+
+---
+
+## Request and Response Models
+
+Pydantic v2 models define the shape of request bodies, response payloads, and query parameter groups. Separate input and output schemas to control what clients send versus what they receive:
+
+```python
+from pydantic import BaseModel, Field, field_validator
+from datetime import datetime
+
+class UserCreate(BaseModel):
+    email: str
+    password: str = Field(min_length=8)
+    display_name: str | None = None
+
+    @field_validator("email")
+    @classmethod
+    def validate_email(cls, v: str) -> str:
+        if "@" not in v:
+            raise ValueError("invalid email format")
+        return v.lower()
+
+class UserResponse(BaseModel):
+    model_config = {"from_attributes": True}
+
+    id: int
+    email: str
+    display_name: str | None
+    created_at: datetime
+```
+
+Set `from_attributes = True` in model config to enable construction from ORM objects (replaces Pydantic v1's `orm_mode`). Use `Field()` for constraints (min/max length, regex, ge/le). Use `field_validator` for custom validation logic.
+
+For polymorphic responses, use discriminated unions with a literal type field:
+
+```python
+from typing import Literal, Union
+from pydantic import BaseModel
+
+class TextMessage(BaseModel):
+    type: Literal["text"] = "text"
+    content: str
+
+class ImageMessage(BaseModel):
+    type: Literal["image"] = "image"
+    url: str
+
+Message = Union[TextMessage, ImageMessage]
+```
+
+> **Deep dive:** See `references/pydantic-models.md` for computed fields, model inheritance, custom JSON encoders, discriminated union patterns, and BaseSettings for configuration.
+
+---
+
+## Error Handling
+
+Raise `HTTPException` for expected error conditions. FastAPI converts it to a JSON response with the specified status code:
+
+```python
+from fastapi import HTTPException, status
+
+@router.get("/items/{item_id}")
+async def get_item(item_id: int):
+    item = await fetch_item(item_id)
+    if not item:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Item not found",
+        )
+    return item
+```
+
+Register custom exception handlers for domain exceptions and validation errors:
+
+```python
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+
+@app.exception_handler(RequestValidationError)
+async def validation_handler(request, exc):
+    return JSONResponse(status_code=422, content={"errors": exc.errors()})
+```
+
+---
+
+## Server-Sent Events
+
+SSE provides a persistent HTTP connection for server-to-client streaming. FastAPI handles SSE through `sse-starlette`, which wraps an async generator into a compliant event stream with proper `text/event-stream` headers, keep-alive, and reconnection support.
+
+### Basic SSE Pattern
+
+```python
+from sse_starlette.sse import EventSourceResponse
+
+async def event_generator():
+    while True:
+        event = await get_next_event()
+        if event is None:
+            break
+        yield {"event": "update", "data": event.json(), "id": str(event.id)}
+
+@app.get("/events")
+async def stream_events():
+    return EventSourceResponse(event_generator())
+```
+
+Each yielded dict maps to SSE fields: `data` (required), `event` (event type), `id` (last-event ID for reconnection), and `retry` (reconnection interval in ms). Yield a plain string to send a data-only event.
+
+### LLM Streaming Pattern
+
+Stream token-by-token responses from an LLM, forwarding chunks as they arrive:
+
+```python
+import json
+
+async def stream_llm_response(prompt: str):
+    response = await llm_client.chat.completions.create(
+        model="claude-sonnet-4-20250514",
+        messages=[{"role": "user", "content": prompt}],
+        stream=True,
+    )
+    async for chunk in response:
+        delta = chunk.choices[0].delta
+        if delta.content:
+            yield {"event": "token", "data": delta.content}
+    yield {"event": "done", "data": ""}
+
+@app.post("/chat")
+async def chat(prompt: str):
+    return EventSourceResponse(stream_llm_response(prompt))
+```
+
+### Reconnection and Backpressure
+
+Clients reconnect automatically using the `Last-Event-ID` header. Accept this header in the generator to resume from the correct position:
+
+```python
+from fastapi import Request
+
+async def resumable_generator(request: Request):
+    last_id = request.headers.get("last-event-id")
+    offset = int(last_id) + 1 if last_id else 0
+    async for event in fetch_events_from(offset):
+        if await request.is_disconnected():
+            break
+        yield {"data": event.json(), "id": str(event.id)}
+
+@app.get("/events")
+async def stream(request: Request):
+    return EventSourceResponse(resumable_generator(request))
+```
+
+Check `request.is_disconnected()` periodically to detect dropped clients and stop generating events. For high-throughput scenarios, use a bounded `asyncio.Queue` to apply backpressure -- producers block when the queue is full rather than accumulating unbounded memory.
+
+> **Deep dive:** See `references/sse-and-streaming.md` for the full SSE protocol, sse-starlette configuration, heartbeat keep-alive, disconnect detection patterns, bounded queue backpressure, LLM streaming with tool calls, and testing SSE endpoints.
+
+---
+
+## Middleware and Lifespan
+
+### HTTP Middleware
+
+Middleware wraps the entire request/response cycle. Use `@app.middleware("http")` for simple cases or subclass `BaseHTTPMiddleware` for complex logic:
+
+```python
+import time
+
+@app.middleware("http")
+async def add_timing_header(request, call_next):
+    start = time.perf_counter()
+    response = await call_next(request)
+    response.headers["X-Process-Time"] = str(time.perf_counter() - start)
+    return response
+```
+
+Add CORS support with the built-in middleware:
+
+```python
+from fastapi.middleware.cors import CORSMiddleware
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["https://example.com"],
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+```
+
+### Lifespan
+
+The lifespan context manager replaces `on_startup`/`on_shutdown` events. Resources created during startup are available to all handlers through the `app.state` object:
+
+```python
+from contextlib import asynccontextmanager
+
+@asynccontextmanager
+async def lifespan(app):
+    pool = await create_db_pool()
+    app.state.db_pool = pool
+    yield
+    await pool.close()
+
+app = FastAPI(lifespan=lifespan)
+```
+
+> **Deep dive:** See `references/middleware-and-lifespan.md` for custom middleware patterns, GZip compression, trusted host middleware, lifespan resource sharing, and exception handling in middleware.
+
+---
+
+## Background Tasks
+
+Declare a `BackgroundTasks` parameter to schedule work that runs after the response is sent. Background tasks share the same process -- they are not distributed workers:
+
+```python
+from fastapi import BackgroundTasks
+
+async def send_notification(email: str, message: str):
+    await email_service.send(email, message)
+
+@router.post("/orders")
+async def create_order(order: OrderCreate, tasks: BackgroundTasks):
+    record = await save_order(order)
+    tasks.add_task(send_notification, order.email, "Order confirmed")
+    return record
+```
+
+Background tasks are fire-and-forget. For work requiring reliability guarantees (retries, dead-letter queues), use a task queue like Celery or arq instead.
+
+---
+
+## Ambiguity Policy
+
+These defaults apply when the user does not specify a preference. State the assumption when making a choice so the user can override:
+
+- **Async vs sync handlers:** Default to `async def`. Use plain `def` only when calling blocking libraries that lack async support.
+- **Pydantic version:** Default to Pydantic v2. Do not use v1 field definitions (`Field(...)` with `schema_extra`) or v1 validators (`@validator`).
+- **Server:** Default to uvicorn for development, uvicorn with `--workers` for production.
+- **SSE library:** Default to `sse-starlette` over raw `StreamingResponse` for SSE. Use `StreamingResponse` only for non-SSE streaming (file downloads, binary data).
+- **Dependency style:** Default to `Annotated[Type, Depends()]` over bare `Depends()` in function signatures.
+- **Project structure:** Default to one router per domain module with a central `app.include_router()` registration.
+
+---
+
+## Reference Files
+
+| File | Contents |
+|------|----------|
+| `references/routing-and-dependencies.md` | APIRouter organization, path operation config, nested/overridden dependencies, WebSocket basics, testing endpoints |
+| `references/pydantic-models.md` | Computed fields, model inheritance, custom encoders, discriminated unions, BaseSettings configuration |
+| `references/sse-and-streaming.md` | Full SSE protocol, sse-starlette API, reconnection with Last-Event-ID, backpressure with bounded queues, heartbeats, disconnect detection, LLM streaming with tool calls, testing SSE |
+| `references/middleware-and-lifespan.md` | Custom middleware patterns, CORS configuration, GZip, trusted hosts, lifespan resource management, exception handling in middleware |

package/.devcontainer/plugins/devs-marketplace/plugins/codedirective-skills/skills/fastapi/references/middleware-and-lifespan.md

@@ -0,0 +1,254 @@
+# Middleware and Lifespan -- Deep Dive
+
+## 1. Custom Middleware Patterns
+
+### Function-Based Middleware
+
+The simplest middleware form intercepts every request and response:
+
+```python
+import time
+from fastapi import Request
+
+@app.middleware("http")
+async def timing_middleware(request: Request, call_next):
+    start = time.perf_counter()
+    response = await call_next(request)
+    duration = time.perf_counter() - start
+    response.headers["X-Process-Time"] = f"{duration:.4f}"
+    return response
+```
+
+### Class-Based Middleware
+
+For middleware with configuration or shared state, subclass `BaseHTTPMiddleware`:
+
+```python
+from starlette.middleware.base import BaseHTTPMiddleware
+
+class RequestIDMiddleware(BaseHTTPMiddleware):
+    async def dispatch(self, request: Request, call_next):
+        request_id = request.headers.get("X-Request-ID", str(uuid.uuid4()))
+        request.state.request_id = request_id
+        response = await call_next(request)
+        response.headers["X-Request-ID"] = request_id
+        return response
+
+app.add_middleware(RequestIDMiddleware)
+```
+
+### Pure ASGI Middleware
+
+For performance-critical middleware or when `BaseHTTPMiddleware` limitations apply (streaming response issues), write raw ASGI middleware:
+
+```python
+class RawTimingMiddleware:
+    def __init__(self, app):
+        self.app = app
+
+    async def __call__(self, scope, receive, send):
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+
+        start = time.perf_counter()
+
+        async def send_wrapper(message):
+            if message["type"] == "http.response.start":
+                headers = dict(message.get("headers", []))
+                duration = time.perf_counter() - start
+                headers[b"x-process-time"] = str(duration).encode()
+                message["headers"] = list(headers.items())
+            await send(message)
+
+        await self.app(scope, receive, send_wrapper)
+
+app.add_middleware(RawTimingMiddleware)
+```
+
+Raw ASGI middleware avoids the `BaseHTTPMiddleware` limitation where the entire response body is consumed before the middleware can modify headers. This matters for streaming responses.
+
+---
+
+## 2. CORS Configuration
+
+### Development Setup
+
+```python
+from fastapi.middleware.cors import CORSMiddleware
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["http://localhost:3000", "http://localhost:5173"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+```
+
+### Production Setup
+
+Restrict origins to known domains. Avoid `allow_origins=["*"]` when `allow_credentials=True` -- the CORS specification forbids this combination:
+
+```python
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["https://app.example.com", "https://admin.example.com"],
+    allow_credentials=True,
+    allow_methods=["GET", "POST", "PUT", "DELETE", "PATCH"],
+    allow_headers=["Authorization", "Content-Type"],
+    expose_headers=["X-Request-ID", "X-Process-Time"],
+    max_age=600,  # preflight cache duration in seconds
+)
+```
+
+### CORS with SSE
+
+SSE connections use `GET` requests with `text/event-stream` accept headers. CORS applies normally. Ensure the SSE endpoint's origin is in `allow_origins` and that `expose_headers` includes any custom headers the client needs to read.
+
+---
+
+## 3. GZip Compression
+
+```python
+from fastapi.middleware.gzip import GZipMiddleware
+
+app.add_middleware(GZipMiddleware, minimum_size=1000)
+```
+
+The `minimum_size` parameter (in bytes) prevents compressing small responses where the overhead exceeds the benefit. Default to 500-1000 bytes.
+
+GZip middleware does not compress streaming responses (`StreamingResponse`, `EventSourceResponse`). SSE connections are already efficient for small, frequent messages.
+
+---
+
+## 4. Trusted Host Middleware
+
+Prevent host header attacks by restricting accepted hostnames:
+
+```python
+from starlette.middleware.trustedhost import TrustedHostMiddleware
+
+app.add_middleware(
+    TrustedHostMiddleware,
+    allowed_hosts=["example.com", "*.example.com"],
+)
+```
+
+Requests with unrecognized `Host` headers receive a 400 response. Include `localhost` during development or use a separate middleware configuration per environment.
+
+---
+
+## 5. Middleware Ordering
+
+Middleware executes in reverse registration order (last registered runs first, closest to the application). Register in this order for typical applications:
+
+```python
+# Outermost (runs first on request, last on response)
+app.add_middleware(TrustedHostMiddleware, allowed_hosts=["example.com"])
+app.add_middleware(CORSMiddleware, allow_origins=["https://app.example.com"])
+app.add_middleware(GZipMiddleware, minimum_size=1000)
+app.add_middleware(RequestIDMiddleware)
+# Innermost (runs last on request, first on response)
+```
+
+The CORS middleware must run before any middleware that might reject the request, so it can handle preflight `OPTIONS` requests. GZip should run after CORS to compress all responses including CORS headers.
+
+---
+
+## 6. Lifespan Resource Management
+
+The lifespan context manager replaces deprecated `on_startup` and `on_shutdown` events. Resources created during startup are shared across all requests:
+
+```python
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Startup: create shared resources
+    app.state.db_pool = await create_pool(DATABASE_URL)
+    app.state.redis = await aioredis.from_url(REDIS_URL)
+    app.state.http_client = httpx.AsyncClient()
+
+    yield  # Application runs
+
+    # Shutdown: clean up resources
+    await app.state.http_client.aclose()
+    await app.state.redis.close()
+    await app.state.db_pool.close()
+
+app = FastAPI(lifespan=lifespan)
+```
+
+### Accessing Lifespan Resources
+
+Access shared resources through `request.app.state` in handlers or dependencies:
+
+```python
+async def get_db_pool(request: Request):
+    return request.app.state.db_pool
+
+@app.get("/items")
+async def list_items(pool = Depends(get_db_pool)):
+    async with pool.acquire() as conn:
+        return await conn.fetch("SELECT * FROM items")
+```
+
+### Multiple Resource Groups
+
+For complex applications, compose lifespan from multiple context managers:
+
+```python
+from contextlib import asynccontextmanager, AsyncExitStack
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    async with AsyncExitStack() as stack:
+        app.state.db = await stack.enter_async_context(create_db_pool())
+        app.state.cache = await stack.enter_async_context(create_cache())
+        app.state.bus = await stack.enter_async_context(create_event_bus())
+        yield
+```
+
+`AsyncExitStack` ensures all resources are cleaned up in reverse order, even if one cleanup raises an exception.
+
+---
+
+## 7. Exception Handling in Middleware
+
+### Catching Exceptions in Middleware
+
+Middleware can catch and transform exceptions before they reach the default handler:
+
+```python
+@app.middleware("http")
+async def error_handling_middleware(request: Request, call_next):
+    try:
+        response = await call_next(request)
+        return response
+    except Exception as exc:
+        logger.exception("Unhandled error", extra={"path": request.url.path})
+        return JSONResponse(
+            status_code=500,
+            content={"detail": "Internal server error"},
+        )
+```
+
+### Exception Handlers vs Middleware
+
+Use exception handlers (`@app.exception_handler`) for converting known exception types to HTTP responses. Use middleware for cross-cutting concerns (logging, timing, request modification) that apply to all requests regardless of outcome.
+
+```python
+class RateLimitExceeded(Exception):
+    def __init__(self, retry_after: int):
+        self.retry_after = retry_after
+
+@app.exception_handler(RateLimitExceeded)
+async def rate_limit_handler(request: Request, exc: RateLimitExceeded):
+    return JSONResponse(
+        status_code=429,
+        content={"detail": "Rate limit exceeded"},
+        headers={"Retry-After": str(exc.retry_after)},
+    )
+```