csrd-utils 0.3.97__tar.gz → 0.3.100__tar.gz

{csrd_utils-0.3.97 → csrd_utils-0.3.100}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: csrd-utils
-Version: 0.3.97
+Version: 0.3.100
 Summary: CLI utilities for csrd service generation and feature augmentation
 Project-URL: Repository, https://github.com/csrd-api/fastapi-common
 Project-URL: Documentation, https://github.com/csrd-api/fastapi-common/tree/main/packages/utils

{csrd_utils-0.3.97 → csrd_utils-0.3.100}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "csrd-utils"
-version = "0.3.97"
+version = "0.3.100"
 description = "CLI utilities for csrd service generation and feature augmentation"
 license = { text = "MIT" }
 requires-python = ">=3.12"

{csrd_utils-0.3.97 → csrd_utils-0.3.100}/src/csrd_utils/v2/compose/augments.py

@@ -13,6 +13,44 @@ from dataclasses import dataclass, field
 from typing import Literal
 
 
+@dataclass(frozen=True)
+class RouterDescriptor:
+    """Describes a router contributed by an augment.
+
+    Parameters
+    ----------
+    import_path
+        Dot-path relative to the service package, e.g.
+        ``".views.auth_passthrough_view"``.
+    attr
+        Name of the router attribute in the module, e.g. ``"router"``.
+    alias
+        Import alias used in ``__init__.py``, e.g.
+        ``"auth_passthrough_router"``.
+    """
+
+    import_path: str
+    attr: str = "router"
+    alias: str = ""
+
+
+@dataclass(frozen=True)
+class MiddlewareDescriptor:
+    """Describes middleware contributed by an augment."""
+
+    import_path: str
+    class_name: str
+
+
+@dataclass(frozen=True)
+class ExceptionHandlerDescriptor:
+    """Describes an exception handler contributed by an augment."""
+
+    import_path: str
+    handler_name: str
+    exception_class: str = "Exception"
+
+
 @dataclass(frozen=True)
 class AugmentDescriptor:
     """Complete description of an augment capability.
@@ -81,6 +119,15 @@ class AugmentDescriptor:
     # service with this role.  ``None`` means no scaffolding.
     applies_to_role: str | None = None
 
+    # Routers to wire into __init__.py via include_router
+    routers: list[RouterDescriptor] = field(default_factory=list)
+
+    # Middleware to add to the app
+    middleware: list[MiddlewareDescriptor] = field(default_factory=list)
+
+    # Exception handlers to register on the app
+    exception_handlers: list[ExceptionHandlerDescriptor] = field(default_factory=list)
+
 
 # ---------------------------------------------------------------------------
 # Registry
@@ -102,6 +149,20 @@ AUGMENT_REGISTRY: dict[str, AugmentDescriptor] = {
         ],
         template_dir="jwt-auth-provider",
         applies_to_role="auth",
+        routers=[
+            RouterDescriptor(
+                import_path=".views.auth_view",
+                alias="auth_router",
+            ),
+            RouterDescriptor(
+                import_path=".views.users_view",
+                alias="users_router",
+            ),
+            RouterDescriptor(
+                import_path=".views.jwks_view",
+                alias="jwks_router",
+            ),
+        ],
     ),
     # ── Service-scope ──────────────────────────────────────────────
     "db-config": AugmentDescriptor(
@@ -138,7 +199,12 @@ AUGMENT_REGISTRY: dict[str, AugmentDescriptor] = {
         requires_workspace_augment="jwt-auth-provider",
         packages=["csrd-delegate", "csrd-models"],
         template_dir="auth-passthrough",
-        # compose_env, compose_depends_on, settings_fields resolved from spec
+        routers=[
+            RouterDescriptor(
+                import_path=".views.auth_passthrough_view",
+                alias="auth_passthrough_router",
+            ),
+        ],
     ),
     "context-logging": AugmentDescriptor(
         name="context-logging",
@@ -146,6 +212,12 @@ AUGMENT_REGISTRY: dict[str, AugmentDescriptor] = {
         description="Request context middleware and structured logging",
         packages=["csrd-logging", "csrd-context"],
         template_dir="context-logging",
+        middleware=[
+            MiddlewareDescriptor(
+                import_path="csrd.context.middleware",
+                class_name="RequestContextMiddleware",
+            ),
+        ],
     ),
     "service-layer": AugmentDescriptor(
         name="service-layer",
@@ -153,6 +225,20 @@ AUGMENT_REGISTRY: dict[str, AugmentDescriptor] = {
         description="BaseService + ServiceError hierarchy + exception handler",
         packages=["csrd-service", "csrd-models"],
         template_dir="service-layer",
+        exception_handlers=[
+            ExceptionHandlerDescriptor(
+                import_path="csrd.service",
+                handler_name="service_exception_handler",
+            ),
+        ],
+    ),
+    "crud-scaffold": AugmentDescriptor(
+        name="crud-scaffold",
+        scope="service",
+        description="CRUD endpoints for a named entity with token-guarded views",
+        packages=[],  # db-config + jwt-auth-consumer cover dependencies
+        template_dir="crud-scaffold",
+        routers=[],  # routers are dynamic per entity — wired via options
     ),
 }
 

{csrd_utils-0.3.97 → csrd_utils-0.3.100}/src/csrd_utils/v2/compose/presets.py

@@ -35,6 +35,10 @@ PRESET_REGISTRY: dict[str, PresetDefinition] = {
                     ServiceAugment(name="jwt-auth-consumer"),
                     ServiceAugment(name="auth-passthrough"),
                     ServiceAugment(name="db-config"),
+                    ServiceAugment(
+                        name="crud-scaffold",
+                        options={"entity_name": "item"},
+                    ),
                 ],
             ),
             ServiceNode(

{csrd_utils-0.3.97 → csrd_utils-0.3.100}/src/csrd_utils/v2/compose/scaffolder.py

@@ -139,6 +139,33 @@ def _augment_template_vars(
         "port": str(service.port),
     }
 
+    # Auto-pass augment options as template variables
+    for key, value in augment.options.items():
+        if isinstance(value, str):
+            variables[key] = value
+
+    # Derive entity name variants for crud-scaffold
+    if augment.name == "crud-scaffold":
+        entity_raw = augment.options.get("entity_name", "item")
+        entity = entity_raw if isinstance(entity_raw, str) else entity_raw[0]
+        snake = entity.replace("-", "_").lower()
+        pascal = "".join(w.capitalize() for w in snake.split("_"))
+        plural_raw = augment.options.get("entity_name_plural", snake + "s")
+        plural = plural_raw if isinstance(plural_raw, str) else plural_raw[0]
+        variables["entity_name"] = entity
+        variables["entity_name_snake"] = snake
+        variables["entity_name_pascal"] = pascal
+        variables["entity_name_plural"] = plural
+
+        # SQL dialect for migration (same logic as db-config)
+        db = detect_configured_db({n.type for n in spec.infra})
+        if db == "postgres":
+            variables["sql_auto_id"] = "SERIAL PRIMARY KEY"
+        elif db == "mariadb":
+            variables["sql_auto_id"] = "INTEGER PRIMARY KEY AUTO_INCREMENT"
+        else:
+            variables["sql_auto_id"] = "INTEGER PRIMARY KEY AUTOINCREMENT"
+
     # Database adapter variables — shared by db-config and jwt-auth-provider
     if augment.name in ("db-config", "jwt-auth-provider"):
         db = detect_configured_db({n.type for n in spec.infra})
@@ -258,6 +285,8 @@ def scaffold_augment(
             continue
 
         relative = template_file.relative_to(template_dir)
+        # Apply template substitution to file path (e.g. $entity_name_snake.py → item.py)
+        relative = Path(Template(str(relative)).safe_substitute(variables))
         dest = svc_dest / relative
 
         # Strip .template suffix so e.g. db.py.template → db.py

{csrd_utils-0.3.97 → csrd_utils-0.3.100}/src/csrd_utils/v2/compose/service_renderers.py

@@ -8,7 +8,7 @@ separate scaffolded files (views, repositories, services, dependencies).
 import re
 
 from ..models import ComposeSpec, ServiceNode
-from .augments import AUGMENT_REGISTRY
+from .augments import AUGMENT_REGISTRY, AugmentDescriptor
 from .infra import INFRA_REGISTRY, detect_configured_db
 
 # Pattern to extract default from docker-compose interpolation: ${VAR:-default}
@@ -254,11 +254,21 @@ def render_settings(svc: ServiceNode, spec: ComposeSpec) -> str:
 
 def render_init(svc: ServiceNode, spec: ComposeSpec) -> str:
     """Render ``__init__.py`` with ``build_app()`` + augment middleware/handlers."""
-    augment_names = {a.name for a in svc.augments}
-    ws_augment_names = {a.name for a in spec.workspace.augments}
 
-    # Check if this service is the auth provider target
-    is_auth_provider = "jwt-auth-provider" in ws_augment_names and svc.role == "auth"
+    # Collect all augment descriptors that apply to this service
+    descriptors: list[tuple[str, AugmentDescriptor]] = []
+
+    # Workspace augments targeting this service's role
+    for ws_aug in spec.workspace.augments:
+        desc = AUGMENT_REGISTRY.get(ws_aug.name)
+        if desc is not None and desc.applies_to_role == svc.role:
+            descriptors.append((ws_aug.name, desc))
+
+    # Service-scope augments
+    for augment in svc.augments:
+        desc = AUGMENT_REGISTRY.get(augment.name)
+        if desc is not None:
+            descriptors.append((augment.name, desc))
 
     # Collect imports
     imports = [
@@ -275,26 +285,39 @@ def render_init(svc: ServiceNode, spec: ComposeSpec) -> str:
         "from .views import app as unversioned_app",
     ]
 
-    if is_auth_provider:
-        imports.extend(
-            [
-                "from .views.auth_view import router as auth_router",
-                "from .views.users_view import router as users_router",
-                "from .views.jwks_view import router as jwks_router",
-            ]
-        )
-
-    if "context-logging" in augment_names:
-        imports.append("")
-        imports.append("from csrd.context.middleware import RequestContextMiddleware")
-
-    if "auth-passthrough" in augment_names:
-        imports.append("")
-        imports.append("from .views.auth_passthrough_view import router as auth_passthrough_router")
+    # Router imports (from descriptors)
+    router_aliases: list[str] = []
+    for _name, desc in descriptors:
+        for r in desc.routers:
+            alias = r.alias or r.import_path.rsplit(".", 1)[-1] + "_router"
+            imports.append(f"from {r.import_path} import {r.attr} as {alias}")
+            router_aliases.append(alias)
 
-    if "service-layer" in augment_names:
-        imports.append("")
-        imports.append("from csrd.service import service_exception_handler")
+    # Dynamic routers from crud-scaffold augments (entity-name-based)
+    for augment in svc.augments:
+        if augment.name == "crud-scaffold":
+            entity_raw = augment.options.get("entity_name", "item")
+            entity = entity_raw if isinstance(entity_raw, str) else entity_raw[0]
+            snake = entity.replace("-", "_").lower()
+            alias = f"{snake}_router"
+            imports.append(f"from .views.{snake}_view import router as {alias}")
+            router_aliases.append(alias)
+
+    # Middleware imports
+    middleware_classes: list[str] = []
+    for _name, desc in descriptors:
+        for m in desc.middleware:
+            imports.append("")
+            imports.append(f"from {m.import_path} import {m.class_name}")
+            middleware_classes.append(m.class_name)
+
+    # Exception handler imports
+    handler_pairs: list[tuple[str, str]] = []  # (exception_class, handler_name)
+    for _name, desc in descriptors:
+        for eh in desc.exception_handlers:
+            imports.append("")
+            imports.append(f"from {eh.import_path} import {eh.handler_name}")
+            handler_pairs.append((eh.exception_class, eh.handler_name))
 
     # Build app body
     body = [
@@ -303,14 +326,10 @@ def render_init(svc: ServiceNode, spec: ComposeSpec) -> str:
         "def build_app() -> FastAPI:",
     ]
 
-    if is_auth_provider:
-        body.append("    unversioned_app.include_router(auth_router)")
-        body.append("    unversioned_app.include_router(users_router)")
-        body.append("    unversioned_app.include_router(jwks_router)")
-        body.append("")
-
-    if "auth-passthrough" in augment_names:
-        body.append("    unversioned_app.include_router(auth_passthrough_router)")
+    # Wire routers
+    if router_aliases:
+        for alias in router_aliases:
+            body.append(f"    unversioned_app.include_router({alias})")
         body.append("")
 
     body.extend(
@@ -329,13 +348,15 @@ def render_init(svc: ServiceNode, spec: ComposeSpec) -> str:
         ]
     )
 
-    if "context-logging" in augment_names:
+    # Wire middleware
+    for cls in middleware_classes:
         body.append("")
-        body.append("    app.add_middleware(RequestContextMiddleware)")
+        body.append(f"    app.add_middleware({cls})")
 
-    if "service-layer" in augment_names:
+    # Wire exception handlers
+    for exc_cls, handler in handler_pairs:
         body.append("")
-        body.append("    app.add_exception_handler(Exception, service_exception_handler)")
+        body.append(f"    app.add_exception_handler({exc_cls}, {handler})")
 
     body.extend(
         [

csrd_utils-0.3.100/src/csrd_utils/v2/templates/augments/crud-scaffold/dependencies/${entity_name_snake}_repository.py.template

@@ -0,0 +1,21 @@
+"""${entity_name_pascal} repository dependency.
+
+This file is scaffolded once and never overwritten.
+"""
+
+from typing import Annotated
+
+from fastapi import Depends
+
+from ..repositories.${entity_name_snake}_repository import ${entity_name_pascal}Repository
+from .db import Adapter
+
+
+def _${entity_name_snake}_repository_factory(adapter: Adapter) -> ${entity_name_pascal}Repository:
+    """Create a ``${entity_name_pascal}Repository`` backed by the database adapter."""
+    return ${entity_name_pascal}Repository(adapter)
+
+
+${entity_name_pascal}Repo = Annotated[${entity_name_pascal}Repository, Depends(_${entity_name_snake}_repository_factory)]
+
+__all__ = ("${entity_name_pascal}Repo",)

csrd_utils-0.3.100/src/csrd_utils/v2/templates/augments/crud-scaffold/migrations_${entity_name_snake}.py.template

@@ -0,0 +1,26 @@
+"""Migration for the ${entity_name_plural} table.
+
+Import this into your ``migrations.py`` and append to the migrations list:
+
+    from .migrations_${entity_name_snake} import ${entity_name_snake}_migration
+    migrations.append(${entity_name_snake}_migration)
+
+This file is scaffolded once and never overwritten.
+"""
+
+from csrd.migration import Migration
+
+${entity_name_snake}_migration = Migration(
+    version="${entity_name_snake}_001",
+    description="Create ${entity_name_plural} table",
+    up=(
+        "CREATE TABLE IF NOT EXISTS ${entity_name_plural} ("
+        "    id TEXT PRIMARY KEY,"
+        "    name TEXT NOT NULL,"
+        "    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP"
+        ")"
+    ),
+    down="DROP TABLE IF EXISTS ${entity_name_plural}",
+)
+
+__all__ = ("${entity_name_snake}_migration",)

csrd_utils-0.3.100/src/csrd_utils/v2/templates/augments/crud-scaffold/models/${entity_name_snake}.py.template

@@ -0,0 +1,28 @@
+"""${entity_name_pascal} models for CRUD operations."""
+
+from csrd.models import BaseModel
+
+
+class Create${entity_name_pascal}Request(BaseModel):
+    """Request body for creating a new ${entity_name}."""
+
+    name: str
+
+
+class Update${entity_name_pascal}Request(BaseModel):
+    """Request body for updating an existing ${entity_name}."""
+
+    name: str
+
+
+class ${entity_name_pascal}Response(BaseModel):
+    """Response model for a single ${entity_name}."""
+
+    id: str
+    name: str
+
+
+class ${entity_name_pascal}ListResponse(BaseModel):
+    """Response model for a list of ${entity_name_plural}."""
+
+    items: list[${entity_name_pascal}Response]

csrd_utils-0.3.100/src/csrd_utils/v2/templates/augments/crud-scaffold/repositories/${entity_name_snake}_repository.py.template

@@ -0,0 +1,65 @@
+"""${entity_name_pascal} repository — CRUD operations.
+
+This file is scaffolded once and never overwritten.
+"""
+
+import uuid
+
+from fastapi import HTTPException
+
+from csrd.repository import BaseRepository
+
+from ..models.${entity_name_snake} import (
+    ${entity_name_pascal}ListResponse,
+    ${entity_name_pascal}Response,
+)
+
+
+class ${entity_name_pascal}Repository(BaseRepository):
+    """CRUD storage for ${entity_name_plural}."""
+
+    async def create(self, name: str) -> ${entity_name_pascal}Response:
+        """Create a new ${entity_name}."""
+        entity_id = str(uuid.uuid4())
+        await self.execute(
+            "INSERT INTO ${entity_name_plural} (id, name) VALUES (:id, :name)",
+            {"id": entity_id, "name": name},
+        )
+        return ${entity_name_pascal}Response(id=entity_id, name=name)
+
+    async def get_by_id(self, entity_id: str) -> ${entity_name_pascal}Response:
+        """Get a ${entity_name} by ID. Raises 404 if not found."""
+        return await self.require_one(
+            "SELECT id, name FROM ${entity_name_plural} WHERE id = :id",
+            {"id": entity_id},
+            model=${entity_name_pascal}Response,
+            detail="${entity_name_pascal} not found",
+        )
+
+    async def list_all(self) -> ${entity_name_pascal}ListResponse:
+        """List all ${entity_name_plural}."""
+        rows = await self.fetch_all(
+            "SELECT id, name FROM ${entity_name_plural} ORDER BY name",
+        )
+        items = [self.apply_model(row, model=${entity_name_pascal}Response) for row in rows]
+        return ${entity_name_pascal}ListResponse(items=items)
+
+    async def update(self, entity_id: str, name: str) -> ${entity_name_pascal}Response:
+        """Update a ${entity_name}. Raises 404 if not found."""
+        await self.get_by_id(entity_id)  # ensures exists
+        await self.execute(
+            "UPDATE ${entity_name_plural} SET name = :name WHERE id = :id",
+            {"id": entity_id, "name": name},
+        )
+        return ${entity_name_pascal}Response(id=entity_id, name=name)
+
+    async def delete(self, entity_id: str) -> None:
+        """Delete a ${entity_name}. Raises 404 if not found."""
+        await self.get_by_id(entity_id)  # ensures exists
+        await self.execute(
+            "DELETE FROM ${entity_name_plural} WHERE id = :id",
+            {"id": entity_id},
+        )
+
+
+__all__ = ("${entity_name_pascal}Repository",)

csrd_utils-0.3.100/src/csrd_utils/v2/templates/augments/crud-scaffold/views/${entity_name_snake}_view.py.template

@@ -0,0 +1,67 @@
+"""${entity_name_pascal} CRUD endpoints — token-guarded.
+
+This file is scaffolded once and never overwritten.
+"""
+
+from fastapi import APIRouter, Security
+
+from ..dependencies.auth import auth_dep
+from ..dependencies.${entity_name_snake}_repository import ${entity_name_pascal}Repo
+from ..models.${entity_name_snake} import (
+    Create${entity_name_pascal}Request,
+    ${entity_name_pascal}ListResponse,
+    ${entity_name_pascal}Response,
+    Update${entity_name_pascal}Request,
+)
+
+router = APIRouter(prefix="/api/${entity_name_plural}", tags=["${entity_name_plural}"])
+
+
+@router.get("", response_model=${entity_name_pascal}ListResponse)
+async def list_${entity_name_plural}(
+    repo: ${entity_name_pascal}Repo,
+    _claims=Security(auth_dep),
+) -> ${entity_name_pascal}ListResponse:
+    """List all ${entity_name_plural}."""
+    return await repo.list_all()
+
+
+@router.get("/{entity_id}", response_model=${entity_name_pascal}Response)
+async def get_${entity_name_snake}(
+    entity_id: str,
+    repo: ${entity_name_pascal}Repo,
+    _claims=Security(auth_dep),
+) -> ${entity_name_pascal}Response:
+    """Get a ${entity_name} by ID."""
+    return await repo.get_by_id(entity_id)
+
+
+@router.post("", status_code=201, response_model=${entity_name_pascal}Response)
+async def create_${entity_name_snake}(
+    body: Create${entity_name_pascal}Request,
+    repo: ${entity_name_pascal}Repo,
+    _claims=Security(auth_dep),
+) -> ${entity_name_pascal}Response:
+    """Create a new ${entity_name}."""
+    return await repo.create(body.name)
+
+
+@router.put("/{entity_id}", response_model=${entity_name_pascal}Response)
+async def update_${entity_name_snake}(
+    entity_id: str,
+    body: Update${entity_name_pascal}Request,
+    repo: ${entity_name_pascal}Repo,
+    _claims=Security(auth_dep),
+) -> ${entity_name_pascal}Response:
+    """Update an existing ${entity_name}."""
+    return await repo.update(entity_id, body.name)
+
+
+@router.delete("/{entity_id}", status_code=204)
+async def delete_${entity_name_snake}(
+    entity_id: str,
+    repo: ${entity_name_pascal}Repo,
+    _claims=Security(auth_dep),
+) -> None:
+    """Delete a ${entity_name}."""
+    await repo.delete(entity_id)

{csrd_utils-0.3.97 → csrd_utils-0.3.100}/src/csrd_utils/v2/templates/augments/jwt-auth-provider/dependencies/db.py.template

@@ -1,4 +1,4 @@
-"""Database and repository dependencies for the auth service.
+"""Database, repository, and key ring dependencies for the auth service.
 
 This file is scaffolded once and never overwritten.
 """
@@ -7,6 +7,8 @@ from typing import Annotated
 
 from fastapi import Depends
 
+from csrd.auth import KeyRingManager
+
 $db_adapter_import
 
 from ..repositories.user_repository import UserRepository
@@ -43,4 +45,20 @@ def _user_repository_factory(adapter: Adapter) -> UserRepository:
 
 UserRepo = Annotated[UserRepository, Depends(_user_repository_factory)]
 
-__all__ = ("Adapter", "UserRepo")
+
+async def _key_ring_factory(adapter: Adapter, settings: Settings) -> KeyRingManager:
+    """Create and initialize a ``KeyRingManager`` for JWT signing."""
+    key_ring = KeyRingManager(
+        adapter=adapter,
+        key_size=settings.jwt_key_size,
+        rotation_interval=settings.jwt_key_rotation_interval,
+        retention_period=settings.jwt_key_retention_period,
+        token_ttl=settings.jwt_ttl_seconds,
+    )
+    await key_ring.initialize()
+    return key_ring
+
+
+KeyRing = Annotated[KeyRingManager, Depends(_key_ring_factory)]
+
+__all__ = ("Adapter", "KeyRing", "UserRepo")

csrd_utils-0.3.100/src/csrd_utils/v2/templates/augments/jwt-auth-provider/dependencies/token_service.py

@@ -0,0 +1,22 @@
+"""Token service dependency for the auth service.
+
+This file is scaffolded once and never overwritten.
+"""
+
+from typing import Annotated
+
+from fastapi import Depends
+
+from ..services.token_service import TokenService
+from . import Settings
+from .db import KeyRing
+
+
+def _token_service_factory(key_ring: KeyRing, settings: Settings) -> TokenService:
+    """Create a ``TokenService`` with the key ring and settings."""
+    return TokenService(key_ring, settings)
+
+
+TokenSvc = Annotated[TokenService, Depends(_token_service_factory)]
+
+__all__ = ("TokenSvc",)

{csrd_utils-0.3.97 → csrd_utils-0.3.100}/src/csrd_utils/v2/templates/augments/jwt-auth-provider/repositories/user_repository.py

@@ -21,7 +21,11 @@ class UserRepository(BaseRepository):
     # ── User CRUD ────────────────────────────────────────────────────
 
     async def create_user(self, username: str, password: str) -> UserResponse:
-        """Create a new user with hashed credentials."""
+        """Create a new user with hashed credentials. Raises 409 if exists."""
+        existing = await self.get_user_by_username(username)
+        if existing is not None:
+            raise HTTPException(status_code=409, detail="Username already taken")
+
         user_id = str(uuid.uuid4())
         await self.execute(
             "INSERT INTO users (id, username) VALUES (:id, :username)",