@malamute/ai-rules 1.0.0 → 1.2.0

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

@@ -0,0 +1,251 @@
+---
+paths:
+  - "tests/**/*.py"
+  - "**/test_*.py"
+---
+
+# FastAPI Testing Patterns
+
+## Test Client Setup
+
+```python
+import pytest
+from httpx import AsyncClient, ASGITransport
+from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession
+from sqlalchemy.orm import sessionmaker
+
+from app.main import app
+from app.database import Base, get_db
+
+TEST_DATABASE_URL = "sqlite+aiosqlite:///./test.db"
+
+@pytest.fixture(scope="session")
+def event_loop():
+    import asyncio
+    loop = asyncio.new_event_loop()
+    yield loop
+    loop.close()
+
+@pytest.fixture(scope="session")
+async def engine():
+    engine = create_async_engine(TEST_DATABASE_URL)
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+    yield engine
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.drop_all)
+    await engine.dispose()
+
+@pytest.fixture
+async def db_session(engine):
+    async_session = sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)
+    async with async_session() as session:
+        yield session
+        await session.rollback()
+
+@pytest.fixture
+async def client(db_session):
+    async def override_get_db():
+        yield db_session
+
+    app.dependency_overrides[get_db] = override_get_db
+
+    async with AsyncClient(
+        transport=ASGITransport(app=app),
+        base_url="http://test",
+    ) as client:
+        yield client
+
+    app.dependency_overrides.clear()
+```
+
+## API Tests
+
+```python
+class TestUsersAPI:
+    async def test_create_user(self, client: AsyncClient):
+        response = await client.post("/api/v1/users", json={
+            "email": "test@example.com",
+            "password": "password123",
+            "name": "Test User",
+        })
+
+        assert response.status_code == 201
+        data = response.json()
+        assert data["email"] == "test@example.com"
+        assert "id" in data
+        assert "password" not in data
+
+    async def test_create_user_duplicate_email(self, client: AsyncClient, db_session):
+        # Create existing user
+        user = User(email="existing@example.com", name="Existing")
+        db_session.add(user)
+        await db_session.commit()
+
+        response = await client.post("/api/v1/users", json={
+            "email": "existing@example.com",
+            "password": "password123",
+            "name": "New User",
+        })
+
+        assert response.status_code == 409
+        assert "already exists" in response.json()["detail"]
+
+    async def test_get_user_not_found(self, client: AsyncClient):
+        response = await client.get("/api/v1/users/99999")
+
+        assert response.status_code == 404
+
+    async def test_list_users_pagination(self, client: AsyncClient, db_session):
+        # Create users
+        for i in range(25):
+            db_session.add(User(email=f"user{i}@example.com", name=f"User {i}"))
+        await db_session.commit()
+
+        response = await client.get("/api/v1/users?page=2&size=10")
+
+        assert response.status_code == 200
+        data = response.json()
+        assert len(data["items"]) == 10
+        assert data["total"] == 25
+        assert data["page"] == 2
+```
+
+## Authentication Tests
+
+```python
+@pytest.fixture
+async def auth_headers(client: AsyncClient, db_session):
+    # Create user
+    user = User(email="auth@example.com", name="Auth User")
+    user.set_password("password123")
+    db_session.add(user)
+    await db_session.commit()
+
+    # Get token
+    response = await client.post("/api/v1/auth/login", data={
+        "username": "auth@example.com",
+        "password": "password123",
+    })
+    token = response.json()["access_token"]
+
+    return {"Authorization": f"Bearer {token}"}
+
+class TestAuthenticatedEndpoints:
+    async def test_get_me_unauthorized(self, client: AsyncClient):
+        response = await client.get("/api/v1/users/me")
+        assert response.status_code == 401
+
+    async def test_get_me_authorized(self, client: AsyncClient, auth_headers):
+        response = await client.get("/api/v1/users/me", headers=auth_headers)
+        assert response.status_code == 200
+        assert response.json()["email"] == "auth@example.com"
+```
+
+## Dependency Override
+
+```python
+from unittest.mock import AsyncMock
+
+@pytest.fixture
+def mock_email_service():
+    return AsyncMock()
+
+async def test_signup_sends_email(client: AsyncClient, mock_email_service):
+    app.dependency_overrides[get_email_service] = lambda: mock_email_service
+
+    response = await client.post("/api/v1/auth/signup", json={
+        "email": "new@example.com",
+        "password": "password123",
+        "name": "New User",
+    })
+
+    assert response.status_code == 201
+    mock_email_service.send_welcome.assert_called_once_with("new@example.com")
+
+    app.dependency_overrides.clear()
+```
+
+## WebSocket Tests
+
+```python
+from httpx_ws import aconnect_ws
+
+async def test_websocket_echo(client: AsyncClient):
+    async with aconnect_ws("http://test/ws", client) as ws:
+        await ws.send_text("Hello")
+        response = await ws.receive_text()
+        assert response == "Echo: Hello"
+
+async def test_websocket_auth_required():
+    async with AsyncClient(
+        transport=ASGITransport(app=app),
+        base_url="http://test",
+    ) as client:
+        with pytest.raises(Exception):
+            async with aconnect_ws("http://test/ws", client) as ws:
+                pass  # Should fail without token
+```
+
+## File Upload Tests
+
+```python
+async def test_file_upload(client: AsyncClient, auth_headers):
+    files = {"file": ("test.txt", b"file content", "text/plain")}
+
+    response = await client.post(
+        "/api/v1/files/upload",
+        files=files,
+        headers=auth_headers,
+    )
+
+    assert response.status_code == 201
+    assert response.json()["filename"] == "test.txt"
+```
+
+## Parametrized Tests
+
+```python
+@pytest.mark.parametrize("email,expected_valid", [
+    ("valid@example.com", True),
+    ("also.valid@example.co.uk", True),
+    ("invalid", False),
+    ("missing@", False),
+    ("@nodomain.com", False),
+])
+async def test_email_validation(client: AsyncClient, email: str, expected_valid: bool):
+    response = await client.post("/api/v1/users", json={
+        "email": email,
+        "password": "password123",
+        "name": "Test",
+    })
+
+    if expected_valid:
+        assert response.status_code in (201, 409)  # Created or duplicate
+    else:
+        assert response.status_code == 422
+```
+
+## Test Markers
+
+```python
+# pyproject.toml
+[tool.pytest.ini_options]
+markers = [
+    "slow: marks tests as slow",
+    "integration: requires database",
+]
+
+# Usage
+@pytest.mark.slow
+async def test_heavy_computation():
+    ...
+
+@pytest.mark.integration
+async def test_database_query():
+    ...
+
+# Run specific markers
+# pytest -m "not slow"
+# pytest -m integration
+```

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

@@ -0,0 +1,298 @@
+---
+paths:
+  - "**/*.py"
+---
+
+# FastAPI WebSocket Patterns
+
+## Basic WebSocket
+
+```python
+from fastapi import WebSocket, WebSocketDisconnect
+
+@app.websocket("/ws")
+async def websocket_endpoint(websocket: WebSocket):
+    await websocket.accept()
+
+    try:
+        while True:
+            data = await websocket.receive_text()
+            await websocket.send_text(f"Echo: {data}")
+    except WebSocketDisconnect:
+        print("Client disconnected")
+```
+
+## Connection Manager
+
+```python
+from typing import List
+
+class ConnectionManager:
+    def __init__(self):
+        self.active_connections: list[WebSocket] = []
+
+    async def connect(self, websocket: WebSocket):
+        await websocket.accept()
+        self.active_connections.append(websocket)
+
+    def disconnect(self, websocket: WebSocket):
+        self.active_connections.remove(websocket)
+
+    async def send_personal_message(self, message: str, websocket: WebSocket):
+        await websocket.send_text(message)
+
+    async def broadcast(self, message: str):
+        for connection in self.active_connections:
+            await connection.send_text(message)
+
+manager = ConnectionManager()
+
+@app.websocket("/ws/{client_id}")
+async def websocket_endpoint(websocket: WebSocket, client_id: str):
+    await manager.connect(websocket)
+
+    try:
+        while True:
+            data = await websocket.receive_text()
+            await manager.broadcast(f"Client {client_id}: {data}")
+    except WebSocketDisconnect:
+        manager.disconnect(websocket)
+        await manager.broadcast(f"Client {client_id} left")
+```
+
+## Room-Based Connections
+
+```python
+from collections import defaultdict
+
+class RoomManager:
+    def __init__(self):
+        self.rooms: dict[str, list[WebSocket]] = defaultdict(list)
+
+    async def join_room(self, room: str, websocket: WebSocket):
+        await websocket.accept()
+        self.rooms[room].append(websocket)
+
+    def leave_room(self, room: str, websocket: WebSocket):
+        if websocket in self.rooms[room]:
+            self.rooms[room].remove(websocket)
+        if not self.rooms[room]:
+            del self.rooms[room]
+
+    async def broadcast_to_room(self, room: str, message: str, exclude: WebSocket = None):
+        for connection in self.rooms[room]:
+            if connection != exclude:
+                await connection.send_text(message)
+
+room_manager = RoomManager()
+
+@app.websocket("/ws/room/{room_id}")
+async def room_websocket(websocket: WebSocket, room_id: str):
+    await room_manager.join_room(room_id, websocket)
+
+    try:
+        while True:
+            data = await websocket.receive_text()
+            await room_manager.broadcast_to_room(room_id, data, exclude=websocket)
+    except WebSocketDisconnect:
+        room_manager.leave_room(room_id, websocket)
+```
+
+## Authentication
+
+```python
+from fastapi import Query, status
+
+async def get_user_from_token(token: str) -> User | None:
+    # Verify JWT token
+    try:
+        payload = jwt.decode(token, SECRET_KEY, algorithms=["HS256"])
+        return await get_user(payload["sub"])
+    except JWTError:
+        return None
+
+@app.websocket("/ws")
+async def websocket_endpoint(
+    websocket: WebSocket,
+    token: str = Query(...),
+):
+    user = await get_user_from_token(token)
+
+    if not user:
+        await websocket.close(code=status.WS_1008_POLICY_VIOLATION)
+        return
+
+    await websocket.accept()
+
+    try:
+        while True:
+            data = await websocket.receive_text()
+            await websocket.send_text(f"Hello {user.name}: {data}")
+    except WebSocketDisconnect:
+        pass
+```
+
+## JSON Messages
+
+```python
+from pydantic import BaseModel
+
+class WSMessage(BaseModel):
+    type: str
+    payload: dict
+
+class WSResponse(BaseModel):
+    type: str
+    data: dict
+
+@app.websocket("/ws")
+async def websocket_endpoint(websocket: WebSocket):
+    await websocket.accept()
+
+    try:
+        while True:
+            raw_data = await websocket.receive_json()
+            message = WSMessage(**raw_data)
+
+            if message.type == "ping":
+                response = WSResponse(type="pong", data={})
+            elif message.type == "subscribe":
+                # Handle subscription
+                response = WSResponse(type="subscribed", data=message.payload)
+            else:
+                response = WSResponse(type="error", data={"message": "Unknown type"})
+
+            await websocket.send_json(response.model_dump())
+    except WebSocketDisconnect:
+        pass
+```
+
+## Pub/Sub with Redis
+
+```python
+import aioredis
+import asyncio
+
+class PubSubManager:
+    def __init__(self, redis_url: str):
+        self.redis_url = redis_url
+        self.pubsub = None
+        self.redis = None
+
+    async def connect(self):
+        self.redis = await aioredis.from_url(self.redis_url)
+        self.pubsub = self.redis.pubsub()
+
+    async def subscribe(self, channel: str):
+        await self.pubsub.subscribe(channel)
+
+    async def publish(self, channel: str, message: str):
+        await self.redis.publish(channel, message)
+
+    async def listen(self):
+        async for message in self.pubsub.listen():
+            if message["type"] == "message":
+                yield message["data"].decode()
+
+pubsub = PubSubManager("redis://localhost")
+
+@app.websocket("/ws/subscribe/{channel}")
+async def subscribe_websocket(websocket: WebSocket, channel: str):
+    await websocket.accept()
+    await pubsub.connect()
+    await pubsub.subscribe(channel)
+
+    try:
+        # Task to receive from WebSocket
+        async def receive():
+            while True:
+                data = await websocket.receive_text()
+                await pubsub.publish(channel, data)
+
+        # Task to send from Redis
+        async def send():
+            async for message in pubsub.listen():
+                await websocket.send_text(message)
+
+        await asyncio.gather(receive(), send())
+    except WebSocketDisconnect:
+        pass
+```
+
+## Heartbeat / Keep-Alive
+
+```python
+import asyncio
+
+@app.websocket("/ws")
+async def websocket_endpoint(websocket: WebSocket):
+    await websocket.accept()
+
+    async def send_heartbeat():
+        while True:
+            try:
+                await asyncio.sleep(30)
+                await websocket.send_json({"type": "ping"})
+            except:
+                break
+
+    heartbeat_task = asyncio.create_task(send_heartbeat())
+
+    try:
+        while True:
+            data = await websocket.receive_json()
+
+            if data.get("type") == "pong":
+                continue  # Heartbeat response
+
+            # Handle other messages
+            await process_message(data)
+    except WebSocketDisconnect:
+        heartbeat_task.cancel()
+```
+
+## Rate Limiting WebSocket
+
+```python
+from collections import defaultdict
+import time
+
+class WebSocketRateLimiter:
+    def __init__(self, max_messages: int = 10, window: int = 1):
+        self.max_messages = max_messages
+        self.window = window
+        self.messages: dict[WebSocket, list[float]] = defaultdict(list)
+
+    def is_allowed(self, websocket: WebSocket) -> bool:
+        now = time.time()
+
+        # Clean old messages
+        self.messages[websocket] = [
+            t for t in self.messages[websocket]
+            if now - t < self.window
+        ]
+
+        if len(self.messages[websocket]) >= self.max_messages:
+            return False
+
+        self.messages[websocket].append(now)
+        return True
+
+rate_limiter = WebSocketRateLimiter(max_messages=10, window=1)
+
+@app.websocket("/ws")
+async def websocket_endpoint(websocket: WebSocket):
+    await websocket.accept()
+
+    try:
+        while True:
+            data = await websocket.receive_text()
+
+            if not rate_limiter.is_allowed(websocket):
+                await websocket.send_json({"error": "Rate limit exceeded"})
+                continue
+
+            await process_and_respond(websocket, data)
+    except WebSocketDisconnect:
+        pass
+```

package/configs/fastapi/.claude/settings.json

@@ -0,0 +1,33 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(python *)",
+      "Bash(python3 *)",
+      "Bash(uvicorn *)",
+      "Bash(gunicorn *)",
+      "Bash(fastapi *)",
+      "Bash(pytest *)",
+      "Bash(ruff *)",
+      "Bash(mypy *)",
+      "Bash(alembic *)",
+      "Bash(uv *)",
+      "Bash(poetry *)",
+      "Bash(pip *)",
+      "Bash(pip3 *)",
+      "Read",
+      "Edit",
+      "Write"
+    ],
+    "deny": [
+      "Bash(rm -rf *)",
+      "Read(.env)",
+      "Read(.env.*)",
+      "Read(**/secrets/**)",
+      "Read(**/*.pem)"
+    ]
+  },
+  "env": {
+    "PYTHONDONTWRITEBYTECODE": "1",
+    "PYTHONUNBUFFERED": "1"
+  }
+}