fastapi-forge-cli 0.1.0__py3-none-any.whl

fastapi_forge/templates/with_rbac/app/services/audit.py

@@ -0,0 +1,58 @@
+from typing import Optional
+from uuid import UUID
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.core.logging import get_logger
+from app.db.models.audit_log import AuditLog
+
+logger = get_logger(__name__)
+
+
+class AuditService:
+    def __init__(self, session: AsyncSession):
+        self.session = session
+
+    async def log(
+        self,
+        action: str,
+        resource: str,
+        resource_id: Optional[str] = None,
+        user_id: Optional[str | UUID] = None,
+        user_email: Optional[str] = None,
+        old_values: Optional[dict] = None,
+        new_values: Optional[dict] = None,
+        metadata: Optional[dict] = None,
+        ip_address: Optional[str] = None,
+        user_agent: Optional[str] = None,
+        request_id: Optional[str] = None,
+    ) -> AuditLog:
+        """
+        Append a single audit log entry. All arguments are optional except
+        action and resource so callers can provide as much or as little
+        context as they have.
+        """
+        entry = AuditLog(
+            action=action,
+            resource=resource,
+            resource_id=resource_id,
+            user_id=UUID(str(user_id)) if user_id else None,
+            user_email=user_email,
+            old_values=old_values,
+            new_values=new_values,
+            log_metadata=metadata,
+            ip_address=ip_address,
+            user_agent=user_agent,
+            request_id=request_id,
+        )
+        self.session.add(entry)
+        await self.session.flush()
+
+        logger.debug(
+            "Audit log written",
+            action=action,
+            resource=resource,
+            resource_id=resource_id,
+            user_id=str(user_id) if user_id else None,
+        )
+        return entry

fastapi_forge/templates/with_rbac/app/services/email.py

@@ -0,0 +1,118 @@
+from pathlib import Path
+from typing import Any, Dict, List
+from uuid import UUID
+
+from fastapi_mail import ConnectionConfig, FastMail, MessageSchema, MessageType
+from pydantic import EmailStr
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.core.config import settings
+from app.core.logging import get_logger
+
+logger = get_logger(__name__)
+
+# ── FastMail configuration ───────────────────────────────────────
+_mail_config = ConnectionConfig(
+    MAIL_USERNAME=settings.mail_username,
+    MAIL_PASSWORD=settings.mail_password,
+    MAIL_FROM=settings.mail_from,
+    MAIL_PORT=settings.mail_port,
+    MAIL_SERVER=settings.mail_server,
+    MAIL_STARTTLS=settings.mail_starttls,
+    MAIL_SSL_TLS=settings.mail_ssl_tls,
+    MAIL_FROM_NAME=settings.mail_from_name,
+    TEMPLATE_FOLDER=Path(__file__).parent.parent / "templates" / "email",
+    USE_CREDENTIALS=True,
+    VALIDATE_CERTS=True,
+)
+
+_fast_mail = FastMail(_mail_config)
+
+
+class EmailService:
+    async def _send(
+        self,
+        recipients: List[EmailStr],
+        subject: str,
+        template_name: str,
+        template_body: Dict[str, Any],
+    ) -> None:
+        message = MessageSchema(
+            subject=subject,
+            recipients=recipients,
+            template_body=template_body,
+            subtype=MessageType.html,
+        )
+        try:
+            await _fast_mail.send_message(message, template_name=template_name)
+            logger.info("Email sent", subject=subject, recipients=recipients)
+        except Exception as exc:
+            logger.error("Email send failed", subject=subject, error=str(exc))
+            raise
+
+    # ── Public send helpers ──────────────────────────────────────
+    async def send_welcome_email(self, to_email: str, full_name: str) -> None:
+        await self._send(
+            recipients=[to_email],
+            subject=f"Welcome to {settings.APP_NAME}!",
+            template_name="welcome.html",
+            template_body={"full_name": full_name, "app_name": settings.APP_NAME},
+        )
+
+    async def send_password_reset_email(self, to_email: str, reset_link: str) -> None:
+        await self._send(
+            recipients=[to_email],
+            subject="Reset your password",
+            template_name="password_reset.html",
+            template_body={"reset_link": reset_link, "app_name": settings.APP_NAME},
+        )
+
+    async def send_email_verification(self, to_email: str, verify_link: str) -> None:
+        await self._send(
+            recipients=[to_email],
+            subject="Verify your email address",
+            template_name="verify_email.html",
+            template_body={"verify_link": verify_link, "app_name": settings.APP_NAME},
+        )
+
+    async def send_notification_email(
+        self,
+        to_user_id: UUID,
+        subject: str,
+        body: str,
+        session: AsyncSession,
+    ) -> None:
+        from app.db.models.user import User
+
+        user = await session.get(User, to_user_id)
+        if not user:
+            logger.warning(
+                "Cannot send notification email — user not found",
+                user_id=str(to_user_id),
+            )
+            return
+        await self._send(
+            recipients=[user.email],
+            subject=subject,
+            template_name="notification.html",
+            template_body={
+                "full_name": user.full_name,
+                "body": body,
+                "app_name": settings.APP_NAME,
+            },
+        )
+
+    async def send_generic(
+        self,
+        to_email: str,
+        subject: str,
+        body_html: str,
+    ) -> None:
+        """Send a one-off HTML email without a template file."""
+        message = MessageSchema(
+            subject=subject,
+            recipients=[to_email],
+            body=body_html,
+            subtype=MessageType.html,
+        )
+        await _fast_mail.send_message(message)

fastapi_forge/templates/with_rbac/app/services/notification.py

@@ -0,0 +1,82 @@
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+from uuid import UUID
+
+from sqlalchemy import update
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.core.logging import get_logger
+from app.db.models.notification import Notification
+
+logger = get_logger(__name__)
+
+
+class NotificationService:
+    def __init__(self, session: AsyncSession):
+        self.session = session
+
+    async def send(
+        self,
+        user_id: UUID,
+        title: str,
+        body: str,
+        notification_type: str = "info",
+        channel: str = "in_app",
+        payload: Optional[Dict[str, Any]] = None,
+    ) -> Notification:
+        notification = Notification(
+            user_id=user_id,
+            title=title,
+            body=body,
+            notification_type=notification_type,
+            channel=channel,
+            payload=payload,
+        )
+        self.session.add(notification)
+        await self.session.flush()
+
+        logger.debug(
+            "Notification created",
+            user_id=str(user_id),
+            type=notification_type,
+            channel=channel,
+        )
+
+        # ── Channel-specific dispatch ──────────────────────────
+        if channel == "email":
+            # Lazy import to avoid circular dependency
+            from app.services.email import EmailService
+
+            email_svc = EmailService()
+            # Fire-and-forget; failures are logged, not raised
+            try:
+                await email_svc.send_notification_email(
+                    to_user_id=user_id,
+                    subject=title,
+                    body=body,
+                    session=self.session,
+                )
+            except Exception as exc:
+                logger.warning("Email dispatch failed", error=str(exc))
+
+        return notification
+
+    async def bulk_send(self, user_ids: List[UUID], **kwargs) -> List[Notification]:
+        """Send the same notification to multiple users."""
+        results = []
+        for uid in user_ids:
+            n = await self.send(user_id=uid, **kwargs)
+            results.append(n)
+        return results
+
+    async def mark_all_read(self, user_id: UUID) -> int:
+        result = await self.session.execute(
+            update(Notification)
+            .where(
+                Notification.user_id == user_id,
+                Notification.is_read == False,
+                Notification.is_deleted == False,
+            )
+            .values(is_read=True, read_at=datetime.now(timezone.utc))
+        )
+        return result.rowcount

fastapi_forge/templates/with_rbac/app/templates/email/notification.html

@@ -0,0 +1,7 @@
+<!doctype html>
+<html>
+  <body>
+    <p>Hello {{ full_name }},</p>
+    <div>{{ body }}</div>
+  </body>
+</html>

fastapi_forge/templates/with_rbac/app/templates/email/password_reset.html

@@ -0,0 +1,7 @@
+<!doctype html>
+<html>
+  <body>
+    <p>Use the link below to reset your {{ app_name }} password:</p>
+    <p><a href="{{ reset_link }}">Reset password</a></p>
+  </body>
+</html>

fastapi_forge/templates/with_rbac/app/templates/email/verify_email.html

@@ -0,0 +1,7 @@
+<!doctype html>
+<html>
+  <body>
+    <p>Use the link below to verify your {{ app_name }} email address:</p>
+    <p><a href="{{ verify_link }}">Verify email</a></p>
+  </body>
+</html>

fastapi_forge/templates/with_rbac/app/templates/email/welcome.html

@@ -0,0 +1,6 @@
+<!doctype html>
+<html>
+  <body>
+    <p>Welcome {{ full_name }} to {{ app_name }}.</p>
+  </body>
+</html>

fastapi_forge/templates/with_rbac/app/utils/casing.py

@@ -0,0 +1,31 @@
+from collections.abc import Mapping
+from typing import Any
+
+from fastapi.encoders import jsonable_encoder
+from pydantic.alias_generators import to_camel
+from pydantic import BaseModel, ConfigDict
+
+
+class CamelModel(BaseModel):
+    model_config = ConfigDict(
+        alias_generator=to_camel,
+        populate_by_name=True,
+        from_attributes=True,
+    )
+
+
+def keys_to_camel(value: Any) -> Any:
+    if value is None or isinstance(value, (str, int, float, bool)):
+        return value
+    if isinstance(value, BaseModel):
+        return value.model_dump(by_alias=True)
+    if isinstance(value, Mapping):
+        return {to_camel(str(key)): keys_to_camel(item) for key, item in value.items()}
+    if isinstance(value, list):
+        return [keys_to_camel(item) for item in value]
+    if isinstance(value, tuple):
+        return tuple(keys_to_camel(item) for item in value)
+    encoded = jsonable_encoder(value)
+    if encoded is not value:
+        return keys_to_camel(encoded)
+    return value

fastapi_forge/templates/with_rbac/compose.yaml

@@ -0,0 +1,33 @@
+services:
+  db:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_DB: project_name
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres -d project_name"]
+      interval: 5s
+      timeout: 5s
+      retries: 10
+    volumes:
+      - postgres-data:/var/lib/postgresql/data
+
+  api:
+    build: .
+    env_file: .env
+    environment:
+      PG_HOST: db
+      PG_SSLMODE: disable
+    command: ["sh", "-c", "alembic upgrade head && uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload"]
+    depends_on:
+      db:
+        condition: service_healthy
+    ports:
+      - "8000:8000"
+    volumes:
+      - .:/app
+
+volumes:
+  postgres-data:
+

fastapi_forge/templates/with_rbac/pyproject.toml

@@ -0,0 +1,14 @@
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+pythonpath = ["."]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E9", "F63", "F7", "F82"]
+
+[tool.ruff.lint.per-file-ignores]
+"app/db/models/*.py" = ["F821"]

fastapi_forge/templates/with_rbac/requirements-dev.txt

@@ -0,0 +1,5 @@
+-r requirements.txt
+pytest>=8.0,<9.0
+pytest-asyncio>=0.23,<1.0
+ruff>=0.8,<1.0
+

fastapi_forge/templates/with_rbac/requirements.txt

@@ -0,0 +1,16 @@
+alembic>=1.13.0
+fastapi>=0.111.0
+asyncpg>=0.30.0
+psycopg[binary]>=3.2.0
+pydantic-settings>=2.0.0
+pydantic[email]>=2.0.0
+uvicorn[standard]>=0.29.0
+SQLAlchemy>=2.0.30
+python-jose[cryptography]>=3.3.0
+passlib[bcrypt]>=1.7.4
+bcrypt==4.0.1
+python-multipart>=0.0.9
+slowapi>=0.1.9
+redis>=5.0.0
+fastapi-mail>=1.4.1
+structlog>=24.0.0

fastapi_forge/templates/with_rbac/sample.env

@@ -0,0 +1,42 @@
+APP_NAME=__PROJECT_NAME__
+APP_VERSION=1.0.0
+APP_ENV=development
+APP_DEBUG=false
+SECRET_KEY=replace-with-a-long-random-secret
+
+PG_HOST=localhost
+PG_PORT=5432
+PG_DATABASE=project_name
+PG_USER=postgres
+PG_PASSWORD=postgres
+PG_SSLMODE=prefer
+
+ACCESS_TOKEN_EXPIRE_MINUTES=30
+REFRESH_TOKEN_EXPIRE_DAYS=7
+PASSWORD_RESET_TOKEN_EXPIRE_MINUTES=15
+ALGORITHM=HS256
+
+ALLOWED_ORIGINS=http://localhost:3000
+ALLOWED_HOSTS=localhost,127.0.0.1
+
+USE_REDIS=false
+REDIS_URL=
+RATE_LIMIT_PER_MINUTE=60
+LOG_DIR=logs
+LOG_TO_FILES=false
+
+# Database pool tuning
+DATABASE_POOL_SIZE=10
+DATABASE_MAX_OVERFLOW=20
+DATABASE_POOL_TIMEOUT=30
+DATABASE_DEBUG=false
+
+MAIL_USERNAME=
+MAIL_PASSWORD=
+MAIL_FROM=noreply@example.com
+MAIL_PORT=587
+MAIL_SERVER=smtp.example.com
+MAIL_STARTTLS=true
+MAIL_SSL_TLS=false
+MAIL_FROM_NAME=__PROJECT_NAME__
+FRONTEND_URL=http://localhost:3000

fastapi_forge/templates/with_rbac/scripts/seed_first_user.py

@@ -0,0 +1,166 @@
+import argparse
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+if str(PROJECT_ROOT) not in sys.path:
+    sys.path.insert(0, str(PROJECT_ROOT))
+
+from sqlalchemy import select
+from sqlalchemy.orm import selectinload
+
+from app.core.security import hash_password
+from app.db.models import Permission, Role, User
+from app.db.session import SyncSessionLocal
+
+
+@dataclass(frozen=True)
+class PermissionSeed:
+    code: str
+    name: str
+    description: str
+
+
+PERMISSIONS = [
+    PermissionSeed("admin:write", "Manage administration", "Full administration access."),
+    PermissionSeed("users:create", "Create users", "Create user accounts."),
+    PermissionSeed("users:read", "View users", "View user accounts."),
+    PermissionSeed("users:update", "Update users", "Update user accounts."),
+    PermissionSeed("users:soft_delete", "Soft delete users", "Soft delete user accounts."),
+    PermissionSeed("users:hard_delete", "Hard delete users", "Permanently delete user accounts."),
+    PermissionSeed("roles:create", "Create roles", "Create roles."),
+    PermissionSeed("roles:read", "View roles", "View roles."),
+    PermissionSeed("roles:update", "Update roles", "Update and assign roles."),
+    PermissionSeed("roles:soft_delete", "Soft delete roles", "Soft delete roles."),
+    PermissionSeed("roles:hard_delete", "Hard delete roles", "Permanently delete roles."),
+    PermissionSeed("permissions:create", "Create permissions", "Create permissions."),
+    PermissionSeed("permissions:read", "View permissions", "View permissions."),
+    PermissionSeed("permissions:update", "Update permissions", "Update and assign permissions."),
+    PermissionSeed(
+        "permissions:soft_delete",
+        "Soft delete permissions",
+        "Soft delete permissions.",
+    ),
+    PermissionSeed(
+        "permissions:hard_delete",
+        "Hard delete permissions",
+        "Permanently delete permissions.",
+    ),
+    PermissionSeed("audit_logs:read", "View audit logs", "View immutable audit history."),
+]
+
+ROLE_DEFINITIONS = {
+    "SUPER ADMIN": {
+        "description": "Full access to every permission.",
+        "permissions": [item.code for item in PERMISSIONS],
+    },
+    "ADMIN": {
+        "description": "Manage users and view RBAC configuration.",
+        "permissions": [
+            "users:create",
+            "users:read",
+            "users:update",
+            "roles:read",
+            "permissions:read",
+            "audit_logs:read",
+        ],
+    },
+    "USER": {
+        "description": "Standard authenticated user.",
+        "permissions": [],
+    },
+}
+
+
+def username_from_email(email: str) -> str:
+    return email.split("@", 1)[0].replace(".", "_").replace("-", "_").lower()
+
+
+def seed_permissions(session):
+    by_code = {}
+    for item in PERMISSIONS:
+        permission = session.scalar(
+            select(Permission).where(Permission.code == item.code)
+        )
+        if permission is None:
+            permission = Permission(code=item.code)
+            session.add(permission)
+        permission.name = item.name
+        permission.description = item.description
+        permission.is_active = True
+        permission.restore()
+        by_code[item.code] = permission
+    session.flush()
+    return by_code
+
+
+def seed_roles(session, permissions_by_code):
+    by_name = {}
+    for name, data in ROLE_DEFINITIONS.items():
+        role = session.scalar(
+            select(Role)
+            .where(Role.name == name)
+            .options(selectinload(Role.permissions))
+        )
+        if role is None:
+            role = Role(name=name)
+            session.add(role)
+        role.description = data["description"]
+        role.is_active = True
+        role.restore()
+        role.permissions = [permissions_by_code[code] for code in data["permissions"]]
+        by_name[name] = role
+    session.flush()
+    by_name["SUPER ADMIN"].parent_role_id = None
+    by_name["ADMIN"].parent_role_id = by_name["SUPER ADMIN"].id
+    by_name["USER"].parent_role_id = by_name["ADMIN"].id
+    session.flush()
+    return by_name
+
+
+def seed_first_user(session, email: str, password: str, full_name: str, role: Role):
+    user = session.scalar(
+        select(User)
+        .where(User.email == email.lower(), User.is_deleted == False)
+        .options(selectinload(User.roles))
+    )
+    if user is None:
+        user = User(
+            email=email.lower(),
+            username=username_from_email(email),
+            full_name=full_name,
+            hashed_password=hash_password(password),
+        )
+        session.add(user)
+    user.full_name = full_name
+    user.hashed_password = hash_password(password)
+    user.is_active = True
+    user.is_superuser = True
+    user.is_verified = True
+    user.restore()
+    user.roles = [role]
+    session.flush()
+    return user
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Seed RBAC and the first administrator.")
+    parser.add_argument("--email", required=True)
+    parser.add_argument("--password", required=True)
+    parser.add_argument("--full-name", required=True)
+    args = parser.parse_args()
+
+    with SyncSessionLocal() as session:
+        permissions = seed_permissions(session)
+        roles = seed_roles(session, permissions)
+        user = seed_first_user(
+            session, args.email, args.password, args.full_name, roles["SUPER ADMIN"]
+        )
+        session.commit()
+        print(f"Seeded {len(permissions)} permissions and {len(roles)} roles.")
+        print(f"SUPER ADMIN ready: {user.email}")
+
+
+if __name__ == "__main__":
+    main()

fastapi_forge/templates/with_rbac/tests/test_audit.py

@@ -0,0 +1,42 @@
+from uuid import uuid4
+
+import pytest
+
+from app.db.models.audit_log import AuditLog
+from app.services.audit import AuditService
+
+
+class FakeSession:
+    def __init__(self):
+        self.added = []
+        self.flushed = False
+
+    def add(self, value):
+        self.added.append(value)
+
+    async def flush(self):
+        self.flushed = True
+
+
+@pytest.mark.asyncio
+async def test_audit_service_persists_context():
+    session = FakeSession()
+    user_id = uuid4()
+
+    entry = await AuditService(session).log(
+        action="users.update",
+        resource="users",
+        resource_id="target-user",
+        user_id=user_id,
+        old_values={"is_active": True},
+        new_values={"is_active": False},
+        metadata={"reason": "offboarding"},
+        request_id="request-123",
+    )
+
+    assert isinstance(entry, AuditLog)
+    assert entry.user_id == user_id
+    assert entry.log_metadata == {"reason": "offboarding"}
+    assert entry.request_id == "request-123"
+    assert session.added == [entry]
+    assert session.flushed

fastapi_forge/templates/with_rbac/tests/test_config.py

@@ -0,0 +1,27 @@
+import pytest
+from pydantic import ValidationError
+
+from app.core.config import Settings
+
+
+def test_database_urls_escape_credentials_and_enable_tls():
+    configured = Settings(pg_password="p@ss", pg_sslmode="require")
+
+    assert "%40" in configured.postgres_url
+    assert "ssl=require" in configured.postgres_async_url
+
+
+def test_production_rejects_unsafe_defaults():
+    with pytest.raises(ValidationError):
+        Settings(APP_ENV="production", _env_file=None)
+
+
+def test_production_accepts_explicit_secure_settings():
+    Settings(
+        APP_ENV="production",
+        SECRET_KEY="x" * 48,
+        ALLOWED_HOSTS=["api.example.com"],
+        ALLOWED_ORIGINS=["https://example.com"],
+        pg_sslmode="verify-full",
+        _env_file=None,
+    )