@malamute/ai-rules 1.0.0 → 1.3.0

package/configs/fastapi/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/settings.json

@@ -0,0 +1,35 @@
+{
+  "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(git push *)",
+      "Bash(git push)",
+      "Bash(rm -rf *)",
+      "Read(.env)",
+      "Read(.env.*)",
+      "Read(**/secrets/**)",
+      "Read(**/*.pem)"
+    ]
+  },
+  "env": {
+    "PYTHONDONTWRITEBYTECODE": "1",
+    "PYTHONUNBUFFERED": "1"
+  }
+}

package/configs/flask/CLAUDE.md

@@ -0,0 +1,166 @@
+# Flask Project Guidelines
+
+@../_shared/CLAUDE.md
+
+## Stack
+
+- Python 3.12+
+- Flask 3.0+
+- SQLAlchemy 2.0+ (sync or async)
+- Marshmallow for validation
+- pytest for testing
+- uv or poetry for dependencies
+
+## Architecture
+
+```
+src/app/
+├── __init__.py          # App factory
+├── config.py            # Configuration classes
+├── extensions.py        # Flask extensions (db, migrate, etc.)
+├── [domain]/            # Feature blueprints
+│   ├── __init__.py      # Blueprint registration
+│   ├── routes.py        # Route handlers
+│   ├── schemas.py       # Marshmallow schemas
+│   ├── models.py        # SQLAlchemy models
+│   ├── services.py      # Business logic
+│   └── repository.py    # Data access
+├── core/                # Shared utilities
+│   ├── exceptions.py
+│   └── security.py
+└── common/
+    ├── models.py        # Base models
+    └── schemas.py       # Shared schemas
+```
+
+## Flask Patterns
+
+### Application Factory
+
+```python
+from flask import Flask
+from app.extensions import db, migrate
+from app.config import config
+
+def create_app(config_name: str = "development") -> Flask:
+    app = Flask(__name__)
+    app.config.from_object(config[config_name])
+
+    # Initialize extensions
+    db.init_app(app)
+    migrate.init_app(app, db)
+
+    # Register blueprints
+    from app.users import users_bp
+    app.register_blueprint(users_bp, url_prefix="/api/v1/users")
+
+    # Register error handlers
+    register_error_handlers(app)
+
+    return app
+```
+
+### Blueprints
+
+```python
+from flask import Blueprint, request, jsonify
+from app.users.schemas import UserCreateSchema, UserResponseSchema
+from app.users.services import UserService
+
+users_bp = Blueprint("users", __name__)
+
+@users_bp.route("/", methods=["POST"])
+def create_user():
+    schema = UserCreateSchema()
+    data = schema.load(request.get_json())
+
+    user = UserService.create(data)
+
+    return jsonify(UserResponseSchema().dump(user)), 201
+
+@users_bp.route("/<int:user_id>")
+def get_user(user_id: int):
+    user = UserService.get_by_id(user_id)
+    if not user:
+        return jsonify({"error": "User not found"}), 404
+    return jsonify(UserResponseSchema().dump(user))
+```
+
+### Extensions
+
+```python
+# extensions.py
+from flask_sqlalchemy import SQLAlchemy
+from flask_migrate import Migrate
+from flask_jwt_extended import JWTManager
+
+db = SQLAlchemy()
+migrate = Migrate()
+jwt = JWTManager()
+```
+
+## Marshmallow Schemas
+
+```python
+from marshmallow import Schema, fields, validate, post_load
+
+class UserCreateSchema(Schema):
+    email = fields.Email(required=True)
+    password = fields.Str(required=True, validate=validate.Length(min=8))
+    name = fields.Str(required=True, validate=validate.Length(min=1, max=100))
+
+class UserResponseSchema(Schema):
+    id = fields.Int(dump_only=True)
+    email = fields.Email()
+    name = fields.Str()
+    created_at = fields.DateTime(dump_only=True)
+```
+
+## SQLAlchemy 2.0
+
+```python
+from sqlalchemy.orm import Mapped, mapped_column
+from app.extensions import db
+
+class User(db.Model):
+    __tablename__ = "users"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    email: Mapped[str] = mapped_column(unique=True, index=True)
+    hashed_password: Mapped[str]
+    name: Mapped[str] = mapped_column(db.String(100))
+    is_active: Mapped[bool] = mapped_column(default=True)
+```
+
+## Error Handling
+
+```python
+from flask import jsonify
+from werkzeug.exceptions import HTTPException
+
+def register_error_handlers(app):
+    @app.errorhandler(HTTPException)
+    def handle_http_error(error):
+        return jsonify({
+            "error": error.name,
+            "message": error.description,
+        }), error.code
+
+    @app.errorhandler(ValidationError)
+    def handle_validation_error(error):
+        return jsonify({
+            "error": "Validation Error",
+            "details": error.messages,
+        }), 400
+```
+
+## Commands
+
+```bash
+flask run                         # Dev server
+flask db upgrade                  # Run migrations
+flask db migrate -m "message"     # Generate migration
+pytest                            # Run tests
+pytest --cov=app                  # Coverage
+ruff check . && ruff format .    # Lint + format
+```

package/configs/flask/rules/blueprints.md

@@ -0,0 +1,208 @@
+---
+paths:
+  - "**/*.py"
+---
+
+# Flask Blueprint Patterns
+
+## Basic Blueprint
+
+```python
+# GOOD - organized blueprint
+from flask import Blueprint, request, jsonify
+
+users_bp = Blueprint("users", __name__)
+
+@users_bp.route("/", methods=["GET"])
+def list_users():
+    """List all users."""
+    users = UserService.get_all()
+    return jsonify(UserSchema(many=True).dump(users))
+
+@users_bp.route("/", methods=["POST"])
+def create_user():
+    """Create a new user."""
+    schema = UserCreateSchema()
+    data = schema.load(request.get_json())
+    user = UserService.create(data)
+    return jsonify(UserSchema().dump(user)), 201
+
+@users_bp.route("/<int:user_id>")
+def get_user(user_id: int):
+    """Get user by ID."""
+    user = UserService.get_by_id(user_id)
+    if not user:
+        return jsonify({"error": "User not found"}), 404
+    return jsonify(UserSchema().dump(user))
+```
+
+## Blueprint Registration
+
+```python
+# app/__init__.py
+from flask import Flask
+
+def create_app(config_name: str = "development") -> Flask:
+    app = Flask(__name__)
+    app.config.from_object(config[config_name])
+
+    # Register blueprints
+    from app.users import users_bp
+    from app.auth import auth_bp
+    from app.products import products_bp
+
+    app.register_blueprint(users_bp, url_prefix="/api/v1/users")
+    app.register_blueprint(auth_bp, url_prefix="/api/v1/auth")
+    app.register_blueprint(products_bp, url_prefix="/api/v1/products")
+
+    return app
+```
+
+## Blueprint with Resources
+
+```python
+# app/users/__init__.py
+from flask import Blueprint
+
+users_bp = Blueprint("users", __name__)
+
+# Import routes after blueprint creation to avoid circular imports
+from app.users import routes  # noqa: E402, F401
+```
+
+```python
+# app/users/routes.py
+from app.users import users_bp
+from app.users.schemas import UserSchema, UserCreateSchema
+from app.users.services import UserService
+
+@users_bp.route("/", methods=["GET"])
+def list_users():
+    ...
+```
+
+## Nested Blueprints
+
+```python
+# API versioning with nested blueprints
+api_v1 = Blueprint("api_v1", __name__, url_prefix="/api/v1")
+api_v2 = Blueprint("api_v2", __name__, url_prefix="/api/v2")
+
+# Register child blueprints
+api_v1.register_blueprint(users_bp, url_prefix="/users")
+api_v1.register_blueprint(products_bp, url_prefix="/products")
+
+api_v2.register_blueprint(users_v2_bp, url_prefix="/users")
+
+# Register with app
+app.register_blueprint(api_v1)
+app.register_blueprint(api_v2)
+```
+
+## Blueprint-Specific Error Handlers
+
+```python
+users_bp = Blueprint("users", __name__)
+
+@users_bp.errorhandler(404)
+def user_not_found(error):
+    return jsonify({"error": "User not found"}), 404
+
+@users_bp.errorhandler(ValidationError)
+def validation_error(error):
+    return jsonify({"error": "Validation failed", "details": error.messages}), 400
+```
+
+## Blueprint Hooks
+
+```python
+users_bp = Blueprint("users", __name__)
+
+@users_bp.before_request
+def before_user_request():
+    """Run before every request to this blueprint."""
+    # Verify API key, log request, etc.
+    if not verify_api_key(request.headers.get("X-API-Key")):
+        return jsonify({"error": "Invalid API key"}), 401
+
+@users_bp.after_request
+def after_user_request(response):
+    """Run after every request to this blueprint."""
+    response.headers["X-Blueprint"] = "users"
+    return response
+```
+
+## Blueprint URL Builders
+
+```python
+from flask import url_for
+
+# Build URL for blueprint route
+url = url_for("users.get_user", user_id=1)  # /api/v1/users/1
+
+# With external URL
+url = url_for("users.get_user", user_id=1, _external=True)
+# https://example.com/api/v1/users/1
+```
+
+## Blueprint Templates
+
+```python
+# Blueprint with templates
+users_bp = Blueprint(
+    "users",
+    __name__,
+    template_folder="templates",
+    static_folder="static",
+)
+
+@users_bp.route("/profile")
+def profile():
+    return render_template("users/profile.html")  # From blueprint's templates/
+```
+
+## Blueprint Context Processor
+
+```python
+@users_bp.context_processor
+def user_context():
+    """Add variables to all templates rendered by this blueprint."""
+    return {
+        "current_user": get_current_user(),
+        "user_count": User.query.count(),
+    }
+```
+
+## Class-Based Views with Blueprints
+
+```python
+from flask.views import MethodView
+
+class UserAPI(MethodView):
+    def get(self, user_id: int | None = None):
+        if user_id is None:
+            return jsonify(UserSchema(many=True).dump(User.query.all()))
+        user = User.query.get_or_404(user_id)
+        return jsonify(UserSchema().dump(user))
+
+    def post(self):
+        data = UserCreateSchema().load(request.get_json())
+        user = UserService.create(data)
+        return jsonify(UserSchema().dump(user)), 201
+
+    def put(self, user_id: int):
+        user = User.query.get_or_404(user_id)
+        data = UserUpdateSchema().load(request.get_json())
+        user = UserService.update(user, data)
+        return jsonify(UserSchema().dump(user))
+
+    def delete(self, user_id: int):
+        user = User.query.get_or_404(user_id)
+        UserService.delete(user)
+        return "", 204
+
+# Register view
+user_view = UserAPI.as_view("user_api")
+users_bp.add_url_rule("/", view_func=user_view, methods=["GET", "POST"])
+users_bp.add_url_rule("/<int:user_id>", view_func=user_view, methods=["GET", "PUT", "DELETE"])
+```