@malamute/ai-rules 1.0.0 → 1.2.0

package/configs/fastapi/.claude/rules/middleware.md

@@ -0,0 +1,229 @@
+---
+paths:
+  - "**/*.py"
+---
+
+# FastAPI Middleware Patterns
+
+## Custom Middleware
+
+```python
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import Response
+import time
+
+class TimingMiddleware(BaseHTTPMiddleware):
+    async def dispatch(self, request: Request, call_next) -> Response:
+        start_time = time.perf_counter()
+
+        response = await call_next(request)
+
+        process_time = time.perf_counter() - start_time
+        response.headers["X-Process-Time"] = f"{process_time:.4f}"
+
+        return response
+
+app.add_middleware(TimingMiddleware)
+```
+
+## Request ID Middleware
+
+```python
+import uuid
+from contextvars import ContextVar
+
+request_id_ctx: ContextVar[str] = ContextVar("request_id", default="")
+
+class RequestIDMiddleware(BaseHTTPMiddleware):
+    async def dispatch(self, request: Request, call_next) -> Response:
+        request_id = request.headers.get("X-Request-ID", str(uuid.uuid4()))
+        request_id_ctx.set(request_id)
+
+        response = await call_next(request)
+        response.headers["X-Request-ID"] = request_id
+
+        return response
+
+def get_request_id() -> str:
+    return request_id_ctx.get()
+```
+
+## Logging Middleware
+
+```python
+import logging
+from typing import Callable
+
+logger = logging.getLogger(__name__)
+
+class LoggingMiddleware(BaseHTTPMiddleware):
+    async def dispatch(self, request: Request, call_next) -> Response:
+        # Log request
+        logger.info(
+            "Request started",
+            extra={
+                "method": request.method,
+                "path": request.url.path,
+                "client_ip": request.client.host,
+                "request_id": get_request_id(),
+            },
+        )
+
+        start_time = time.perf_counter()
+
+        try:
+            response = await call_next(request)
+        except Exception as e:
+            logger.exception(
+                "Request failed",
+                extra={
+                    "path": request.url.path,
+                    "error": str(e),
+                    "request_id": get_request_id(),
+                },
+            )
+            raise
+
+        duration = time.perf_counter() - start_time
+
+        # Log response
+        logger.info(
+            "Request completed",
+            extra={
+                "method": request.method,
+                "path": request.url.path,
+                "status_code": response.status_code,
+                "duration": f"{duration:.4f}s",
+                "request_id": get_request_id(),
+            },
+        )
+
+        return response
+```
+
+## Error Handling Middleware
+
+```python
+from fastapi.responses import JSONResponse
+
+class ErrorHandlingMiddleware(BaseHTTPMiddleware):
+    async def dispatch(self, request: Request, call_next) -> Response:
+        try:
+            return await call_next(request)
+        except ValueError as e:
+            return JSONResponse(
+                status_code=400,
+                content={"error": "Bad Request", "detail": str(e)},
+            )
+        except PermissionError as e:
+            return JSONResponse(
+                status_code=403,
+                content={"error": "Forbidden", "detail": str(e)},
+            )
+        except Exception as e:
+            logger.exception("Unhandled exception")
+            return JSONResponse(
+                status_code=500,
+                content={"error": "Internal Server Error"},
+            )
+```
+
+## Pure ASGI Middleware
+
+```python
+# More performant than BaseHTTPMiddleware
+class PureASGIMiddleware:
+    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
+
+        # Before request
+        start_time = time.perf_counter()
+
+        async def send_wrapper(message):
+            if message["type"] == "http.response.start":
+                # Add headers
+                headers = list(message.get("headers", []))
+                duration = time.perf_counter() - start_time
+                headers.append((b"x-process-time", f"{duration:.4f}".encode()))
+                message["headers"] = headers
+            await send(message)
+
+        await self.app(scope, receive, send_wrapper)
+
+app.add_middleware(PureASGIMiddleware)
+```
+
+## Database Session Middleware
+
+```python
+from contextvars import ContextVar
+
+db_session_ctx: ContextVar[AsyncSession | None] = ContextVar("db_session", default=None)
+
+class DatabaseSessionMiddleware(BaseHTTPMiddleware):
+    async def dispatch(self, request: Request, call_next) -> Response:
+        async with async_session() as session:
+            db_session_ctx.set(session)
+            try:
+                response = await call_next(request)
+                await session.commit()
+            except Exception:
+                await session.rollback()
+                raise
+            finally:
+                db_session_ctx.set(None)
+
+        return response
+
+def get_db() -> AsyncSession:
+    session = db_session_ctx.get()
+    if session is None:
+        raise RuntimeError("No database session available")
+    return session
+```
+
+## Middleware Order
+
+```python
+# Order matters! Last added = first executed
+# Request flow: A -> B -> C -> Handler -> C -> B -> A
+
+app.add_middleware(ErrorHandlingMiddleware)    # 3rd (innermost)
+app.add_middleware(LoggingMiddleware)          # 2nd
+app.add_middleware(RequestIDMiddleware)        # 1st (outermost)
+```
+
+## Built-in Middleware
+
+```python
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.middleware.trustedhost import TrustedHostMiddleware
+from fastapi.middleware.gzip import GZipMiddleware
+from fastapi.middleware.httpsredirect import HTTPSRedirectMiddleware
+
+# HTTPS redirect
+app.add_middleware(HTTPSRedirectMiddleware)
+
+# Trusted hosts
+app.add_middleware(
+    TrustedHostMiddleware,
+    allowed_hosts=["example.com", "*.example.com"],
+)
+
+# GZip compression
+app.add_middleware(GZipMiddleware, minimum_size=1000)
+
+# CORS
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["https://example.com"],
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+```

package/configs/fastapi/.claude/rules/pydantic.md

@@ -0,0 +1,433 @@
+---
+paths:
+  - "**/schemas/**/*.py"
+  - "**/models/**/*.py"
+  - "**/*_schema.py"
+  - "**/*_model.py"
+---
+
+# Python Validation (Pydantic)
+
+## Basic Models
+
+```python
+# schemas/user.py
+from datetime import datetime
+from typing import Optional
+from pydantic import BaseModel, EmailStr, Field, field_validator
+from uuid import UUID
+
+
+class UserBase(BaseModel):
+    email: EmailStr
+    name: str = Field(..., min_length=2, max_length=100)
+
+
+class UserCreate(UserBase):
+    password: str = Field(..., min_length=8)
+
+    @field_validator("password")
+    @classmethod
+    def validate_password(cls, v: str) -> str:
+        if not any(c.isupper() for c in v):
+            raise ValueError("Password must contain uppercase letter")
+        if not any(c.islower() for c in v):
+            raise ValueError("Password must contain lowercase letter")
+        if not any(c.isdigit() for c in v):
+            raise ValueError("Password must contain digit")
+        if not any(c in "!@#$%^&*" for c in v):
+            raise ValueError("Password must contain special character")
+        return v
+
+
+class UserUpdate(BaseModel):
+    name: Optional[str] = Field(None, min_length=2, max_length=100)
+    phone: Optional[str] = None
+
+
+class UserResponse(UserBase):
+    id: UUID
+    is_active: bool
+    created_at: datetime
+
+    model_config = {"from_attributes": True}
+```
+
+## Nested Models
+
+```python
+# schemas/order.py
+from pydantic import BaseModel, Field, model_validator
+from typing import List
+from decimal import Decimal
+
+
+class OrderItem(BaseModel):
+    product_id: UUID
+    quantity: int = Field(..., gt=0, le=100)
+    price: Decimal = Field(..., gt=0, decimal_places=2)
+
+
+class OrderCreate(BaseModel):
+    items: List[OrderItem] = Field(..., min_length=1)
+    shipping_address: str = Field(..., min_length=10)
+    notes: Optional[str] = None
+
+    @model_validator(mode="after")
+    def validate_order(self) -> "OrderCreate":
+        total_items = sum(item.quantity for item in self.items)
+        if total_items > 100:
+            raise ValueError("Maximum 100 items per order")
+        return self
+
+
+class OrderResponse(BaseModel):
+    id: UUID
+    items: List[OrderItem]
+    total: Decimal
+    status: str
+    created_at: datetime
+
+    model_config = {"from_attributes": True}
+```
+
+## Custom Types
+
+```python
+# schemas/types.py
+from typing import Annotated
+from pydantic import AfterValidator, BeforeValidator
+import re
+
+
+def validate_phone(v: str) -> str:
+    pattern = r"^\+?[1-9]\d{1,14}$"
+    if not re.match(pattern, v):
+        raise ValueError("Invalid phone number format")
+    return v
+
+
+def validate_slug(v: str) -> str:
+    pattern = r"^[a-z0-9]+(?:-[a-z0-9]+)*$"
+    if not re.match(pattern, v):
+        raise ValueError("Invalid slug format")
+    return v
+
+
+def normalize_email(v: str) -> str:
+    return v.lower().strip()
+
+
+PhoneNumber = Annotated[str, AfterValidator(validate_phone)]
+Slug = Annotated[str, AfterValidator(validate_slug)]
+NormalizedEmail = Annotated[str, BeforeValidator(normalize_email)]
+
+
+# Usage
+class UserCreate(BaseModel):
+    email: NormalizedEmail
+    phone: Optional[PhoneNumber] = None
+
+
+class PostCreate(BaseModel):
+    title: str
+    slug: Slug
+```
+
+## Enum Validation
+
+```python
+# schemas/enums.py
+from enum import Enum
+
+
+class UserRole(str, Enum):
+    USER = "user"
+    ADMIN = "admin"
+    MODERATOR = "moderator"
+
+
+class OrderStatus(str, Enum):
+    PENDING = "pending"
+    PROCESSING = "processing"
+    SHIPPED = "shipped"
+    DELIVERED = "delivered"
+    CANCELLED = "cancelled"
+
+
+# Usage
+class UserCreate(BaseModel):
+    email: EmailStr
+    role: UserRole = UserRole.USER
+
+
+class OrderUpdate(BaseModel):
+    status: OrderStatus
+```
+
+## Computed Fields
+
+```python
+# schemas/product.py
+from pydantic import BaseModel, computed_field
+from decimal import Decimal
+
+
+class Product(BaseModel):
+    name: str
+    price: Decimal
+    discount_percent: int = 0
+
+    @computed_field
+    @property
+    def discounted_price(self) -> Decimal:
+        discount = self.price * self.discount_percent / 100
+        return self.price - discount
+
+    @computed_field
+    @property
+    def display_name(self) -> str:
+        if self.discount_percent > 0:
+            return f"{self.name} ({self.discount_percent}% off)"
+        return self.name
+```
+
+## Conditional Validation
+
+```python
+# schemas/payment.py
+from pydantic import BaseModel, model_validator
+from typing import Optional
+
+
+class PaymentMethod(str, Enum):
+    CREDIT_CARD = "credit_card"
+    BANK_TRANSFER = "bank_transfer"
+    PAYPAL = "paypal"
+
+
+class PaymentCreate(BaseModel):
+    method: PaymentMethod
+    amount: Decimal
+
+    # Credit card fields
+    card_number: Optional[str] = None
+    expiry_date: Optional[str] = None
+    cvv: Optional[str] = None
+
+    # Bank transfer fields
+    bank_account: Optional[str] = None
+    routing_number: Optional[str] = None
+
+    # PayPal fields
+    paypal_email: Optional[EmailStr] = None
+
+    @model_validator(mode="after")
+    def validate_payment_details(self) -> "PaymentCreate":
+        if self.method == PaymentMethod.CREDIT_CARD:
+            if not all([self.card_number, self.expiry_date, self.cvv]):
+                raise ValueError("Card details required for credit card payment")
+
+        elif self.method == PaymentMethod.BANK_TRANSFER:
+            if not all([self.bank_account, self.routing_number]):
+                raise ValueError("Bank details required for bank transfer")
+
+        elif self.method == PaymentMethod.PAYPAL:
+            if not self.paypal_email:
+                raise ValueError("PayPal email required")
+
+        return self
+```
+
+## Generic Pagination
+
+```python
+# schemas/pagination.py
+from typing import Generic, TypeVar, List
+from pydantic import BaseModel
+
+T = TypeVar("T")
+
+
+class PaginatedResponse(BaseModel, Generic[T]):
+    items: List[T]
+    total: int
+    page: int
+    size: int
+    pages: int
+
+    @classmethod
+    def create(
+        cls,
+        items: List[T],
+        total: int,
+        page: int,
+        size: int,
+    ) -> "PaginatedResponse[T]":
+        return cls(
+            items=items,
+            total=total,
+            page=page,
+            size=size,
+            pages=(total + size - 1) // size,
+        )
+
+
+class PaginationParams(BaseModel):
+    page: int = Field(1, ge=1)
+    size: int = Field(10, ge=1, le=100)
+
+    @property
+    def offset(self) -> int:
+        return (self.page - 1) * self.size
+
+
+# Usage
+# PaginatedResponse[UserResponse]
+```
+
+## FastAPI Integration
+
+```python
+# api/users.py
+from fastapi import APIRouter, HTTPException, Depends, Query
+from pydantic import ValidationError
+
+router = APIRouter(prefix="/users", tags=["users"])
+
+
+@router.post("/", response_model=UserResponse, status_code=201)
+async def create_user(
+    user: UserCreate,
+    db: AsyncSession = Depends(get_db),
+) -> UserResponse:
+    # Validation already done by Pydantic
+    existing = await db.execute(
+        select(User).where(User.email == user.email)
+    )
+    if existing.scalar_one_or_none():
+        raise HTTPException(status_code=409, detail="Email already registered")
+
+    new_user = User(**user.model_dump())
+    db.add(new_user)
+    await db.commit()
+    await db.refresh(new_user)
+
+    return UserResponse.model_validate(new_user)
+
+
+@router.get("/", response_model=PaginatedResponse[UserResponse])
+async def list_users(
+    pagination: PaginationParams = Depends(),
+    search: Optional[str] = Query(None, min_length=1),
+    db: AsyncSession = Depends(get_db),
+) -> PaginatedResponse[UserResponse]:
+    query = select(User)
+
+    if search:
+        query = query.where(User.name.ilike(f"%{search}%"))
+
+    total = await db.scalar(select(func.count()).select_from(query.subquery()))
+    users = await db.scalars(
+        query.offset(pagination.offset).limit(pagination.size)
+    )
+
+    return PaginatedResponse.create(
+        items=[UserResponse.model_validate(u) for u in users],
+        total=total,
+        page=pagination.page,
+        size=pagination.size,
+    )
+```
+
+## Custom Error Messages
+
+```python
+# schemas/user.py
+from pydantic import BaseModel, Field
+
+
+class UserCreate(BaseModel):
+    email: EmailStr = Field(
+        ...,
+        description="User email address",
+        json_schema_extra={"example": "user@example.com"},
+    )
+    password: str = Field(
+        ...,
+        min_length=8,
+        max_length=100,
+        description="User password (min 8 characters)",
+    )
+
+    model_config = {
+        "json_schema_extra": {
+            "examples": [
+                {
+                    "email": "john@example.com",
+                    "password": "SecurePass123!",
+                }
+            ]
+        }
+    }
+```
+
+## Anti-patterns
+
+```python
+# BAD: Using dict instead of Pydantic model
+@router.post("/users")
+async def create_user(data: dict):  # No validation!
+    email = data.get("email")
+
+
+# GOOD: Use Pydantic models
+@router.post("/users")
+async def create_user(data: UserCreate):
+    email = data.email  # Validated and typed
+
+
+# BAD: Manual validation
+class UserCreate(BaseModel):
+    email: str
+
+    def validate_email(self):
+        if "@" not in self.email:
+            raise ValueError("Invalid email")
+
+
+# GOOD: Use built-in validators
+class UserCreate(BaseModel):
+    email: EmailStr  # Automatic validation
+
+
+# BAD: Catching all exceptions
+try:
+    user = UserCreate(**data)
+except Exception as e:
+    return {"error": str(e)}
+
+
+# GOOD: Catch specific validation errors
+from pydantic import ValidationError
+
+try:
+    user = UserCreate(**data)
+except ValidationError as e:
+    return {"errors": e.errors()}
+
+
+# BAD: Not using model_config for ORM
+class UserResponse(BaseModel):
+    id: UUID
+    name: str
+    # This won't work with SQLAlchemy objects
+
+
+# GOOD: Enable from_attributes
+class UserResponse(BaseModel):
+    id: UUID
+    name: str
+
+    model_config = {"from_attributes": True}
+```