Merge pull request #92 from strausmann/feat/hangar-integration-phase-1

feat(api): Hub batch print endpoint + slug + hangar templates for Hangar integration

Author: strausmann

backend/alembic/versions/a0516c04278c_add_print_batches_table.py

@@ -0,0 +1,66 @@
+"""add print_batches table
+
+Revision ID: a0516c04278c
+Revises: da865401716d
+Create Date: 2026-05-30 15:18:58.348408
+
+"""
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+import sqlmodel
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "a0516c04278c"
+down_revision: str | Sequence[str] | None = "da865401716d"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_table(
+        "print_batches",
+        sa.Column("id", sa.Uuid(), nullable=False),
+        sa.Column("printer_id", sa.Uuid(), nullable=False),
+        sa.Column("job_ids", sa.JSON(), nullable=True),
+        sa.Column("created_by", sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
+        sa.ForeignKeyConstraint(
+            ["printer_id"],
+            ["printers.id"],
+        ),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_index(
+        op.f("ix_print_batches_created_at"),
+        "print_batches",
+        ["created_at"],
+        unique=False,
+    )
+    op.create_index(
+        op.f("ix_print_batches_created_by"),
+        "print_batches",
+        ["created_by"],
+        unique=False,
+    )
+    op.create_index(
+        op.f("ix_print_batches_printer_id"),
+        "print_batches",
+        ["printer_id"],
+        unique=False,
+    )
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_index(op.f("ix_print_batches_printer_id"), table_name="print_batches")
+    op.drop_index(op.f("ix_print_batches_created_by"), table_name="print_batches")
+    op.drop_index(op.f("ix_print_batches_created_at"), table_name="print_batches")
+    op.drop_table("print_batches")
+    # ### end Alembic commands ###

backend/alembic/versions/da865401716d_add_printer_slug_column.py

@@ -0,0 +1,41 @@
+"""add printer slug column
+
+Revision ID: da865401716d
+Revises: 20260518_phase7c_pat_prefix
+Create Date: 2026-05-30 15:03:06.420359
+
+"""
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+import sqlmodel
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "da865401716d"
+down_revision: str | Sequence[str] | None = "20260518_phase7c_pat_prefix"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    op.add_column(
+        "printers",
+        sa.Column(
+            "slug",
+            sqlmodel.sql.sqltypes.AutoString(),
+            nullable=False,
+            server_default="",
+        ),
+    )
+    # Backfill aus name: existierende Drucker erhalten einen slug
+    op.execute("UPDATE printers SET slug = LOWER(REPLACE(name, ' ', '-')) WHERE slug = ''")
+    op.create_index(op.f("ix_printers_slug"), "printers", ["slug"], unique=True)
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    op.drop_index(op.f("ix_printers_slug"), table_name="printers")
+    op.drop_column("printers", "slug")

backend/app/api/routes/batch.py

@@ -0,0 +1,114 @@
+"""POST /api/print/{printer_key}/batch — best-effort batch print."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, HTTPException, Path, Request, status
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.auth.dependencies import AuthContext, check_printer_access
+from app.auth.scope_deps import require_print
+from app.db.session import get_session
+from app.models.print_batch import PrintBatch
+from app.printer_backends.exceptions import (
+    PrinterCoverOpenError,
+    PrinterOfflineError,
+    SnmpQueryError,
+)
+from app.repositories import print_batches as batches_repo
+from app.repositories import printers as printers_repo
+from app.schemas.print_batch import BatchRequest, BatchResponse
+from app.services.batch_dispatch import dispatch_batch
+
+# SessionDep locally — Hub has no central app/api/deps.py module.
+SessionDep = Annotated[AsyncSession, Depends(get_session)]
+
+# prefix=/api → POST /api/print/{...}/batch. print.py has no prefix
+# (POST /print), so this is a clean separation.
+router = APIRouter(prefix="/api")
+
+_SYNC_ERROR_MAP: dict[type[Exception], str] = {
+    PrinterOfflineError: "printer_offline",
+    PrinterCoverOpenError: "printer_cover_open",
+    SnmpQueryError: "snmp_error",
+}
+
+
+@router.post(
+    "/print/{printer_key}/batch",
+    status_code=status.HTTP_202_ACCEPTED,
+    response_model=BatchResponse,
+    tags=["print"],
+    summary="Submit a batch of print jobs",
+    description=(
+        "Best-effort batch print. Validates each item individually and "
+        "returns per-item errors. Hardware preconditions (printer_offline, "
+        "cover_open) reject the entire batch with 409."
+    ),
+)
+async def create_batch(
+    printer_key: Annotated[str, Path(description="Printer slug or UUID")],
+    body: BatchRequest,
+    http: Request,
+    session: SessionDep,
+    auth: Annotated[AuthContext, Depends(require_print)],
+) -> BatchResponse:
+    # 1. Resolve printer (404 if unknown slug/uuid)
+    printer = await printers_repo.resolve_by_slug_or_uuid(session, printer_key)
+    if printer is None:
+        raise HTTPException(404, detail={"error_code": "printer_not_found"})
+
+    # 2. ACL: api-key may be restricted to a subset of printer_ids
+    check_printer_access(auth, printer.id)
+
+    # 3. Verify the resolved printer matches the singleton wired into
+    # app.state.print_service. The Hub is currently single-printer at
+    # startup (main.py wires PrintService to app.state.printer_id).
+    # If the URL slug points to a different printer row, the dispatch
+    # would silently route to the wrong device. Reject explicitly.
+    seeded_printer_id = getattr(http.app.state, "printer_id", None)
+    if seeded_printer_id is not None and printer.id != seeded_printer_id:
+        raise HTTPException(
+            404,
+            detail={
+                "error_code": "printer_not_active",
+                "error_message": (
+                    "Resolved printer is not the currently-seeded device. "
+                    "Hub is single-printer at startup; multi-printer routing "
+                    "is a future enhancement."
+                ),
+            },
+        )
+
+    # 4. Best-effort dispatch
+    service = http.app.state.print_service
+    try:
+        job_ids, errors = await dispatch_batch(service, body.items)
+    except (PrinterOfflineError, PrinterCoverOpenError, SnmpQueryError) as exc:
+        raise HTTPException(
+            409,
+            detail={
+                "error_code": _SYNC_ERROR_MAP[type(exc)],
+                "error_message": str(exc),
+            },
+        ) from exc
+
+    # 5. Persist tracking row
+    # auth.subject_id does NOT exist — use api_key_id or source
+    created_by = str(auth.api_key_id) if auth.api_key_id else auth.source
+    batch_row = PrintBatch(
+        printer_id=printer.id,
+        job_ids=job_ids,
+        created_by=created_by,
+    )
+    await batches_repo.create(session, batch_row)
+
+    return BatchResponse(
+        batch_id=batch_row.id,
+        printer_id=printer.id,
+        queued_at=datetime.now(UTC).isoformat().replace("+00:00", "Z"),
+        job_ids=job_ids,
+        errors=errors,
+    )

backend/app/api/routes/printers.py

@@ -28,7 +28,7 @@
 from typing import Annotated, Any
 from uuid import UUID
 
-from fastapi import APIRouter, Depends, HTTPException, status
+from fastapi import APIRouter, Depends, HTTPException, Query, status
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.auth.dependencies import AuthContext, check_printer_access
@@ -80,12 +80,30 @@ async def _get_printer_or_404(session: AsyncSession, printer_id: UUID) -> Any:
     summary="List all printers",
     description=(
         "Returns every registered printer.  The ``paused`` flag is joined "
-        "from ``printer_state``; it is ``false`` when no state row exists yet."
+        "from ``printer_state``; it is ``false`` when no state row exists yet.  "
+        "Pass ``?slug=<slug>`` to filter to a single printer by exact slug match "
+        "(returns 404 when no printer with that slug exists)."
     ),
 )
-async def list_printers(session: SessionDep, _auth: ReadAuthDep) -> list[PrinterRead]:
-    """List all printers with their pause state."""
-    printers = await printers_repo.list_all(session)
+async def list_printers(
+    session: SessionDep,
+    _auth: ReadAuthDep,
+    slug: Annotated[str | None, Query(description="Filter by exact slug")] = None,
+) -> list[PrinterRead]:
+    """List all printers with their pause state, optionally filtered by slug."""
+    if slug is not None:
+        printer = await printers_repo.get_by_slug(session, slug)
+        if printer is None:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail={
+                    "error_code": "printer_not_found",
+                    "error_message": f"slug={slug!r} not found",
+                },
+            )
+        printers = [printer]
+    else:
+        printers = await printers_repo.list_all(session)
     result: list[PrinterRead] = []
     for p in printers:
         state = await printer_state_repo.get(session, p.id)
@@ -94,6 +112,7 @@ async def list_printers(session: SessionDep, _auth: ReadAuthDep) -> list[Printer
             PrinterRead(
                 id=p.id,
                 name=p.name,
+                slug=p.slug,
                 model=p.model,
                 backend=p.backend,
                 connection=dict(p.connection),

backend/app/main.py

@@ -75,6 +75,7 @@
 import app.integrations as _integrations_init  # triggers integration plugin discovery
 from app import __version__
 from app.api.error_handlers import register_error_handlers
+from app.api.routes import batch as batch_routes
 from app.api.routes import events as events_routes
 from app.api.routes import jobs as jobs_routes
 from app.api.routes import lookup as lookup_routes
@@ -595,6 +596,7 @@ async def readiness(
 
     register_error_handlers(app)
     app.include_router(print_router)
+    app.include_router(batch_routes.router)
     app.include_router(events_routes.router)
     app.include_router(printers_routes.router)
     app.include_router(templates_routes.router)

backend/app/models/__init__.py

@@ -7,6 +7,7 @@
 from app.models.api_key import ApiKey
 from app.models.job import Job, JobState
 from app.models.preset import Preset
+from app.models.print_batch import PrintBatch
 from app.models.printer import Printer
 from app.models.printer_state import PrinterState
 from app.models.printer_status_cache import PrinterStatusCache
@@ -17,6 +18,7 @@
     "Job",
     "JobState",
     "Preset",
+    "PrintBatch",
     "Printer",
     "PrinterState",
     "PrinterStatusCache",

backend/app/models/print_batch.py

@@ -0,0 +1,22 @@
+"""SQLModel table für print_batches — Tracking-Aggregat für Batch-Druckaufträge."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from uuid import UUID, uuid4
+
+from sqlalchemy import JSON, DateTime
+from sqlmodel import Column, Field, SQLModel
+
+
+class PrintBatch(SQLModel, table=True):
+    __tablename__ = "print_batches"
+
+    id: UUID = Field(default_factory=uuid4, primary_key=True)
+    printer_id: UUID = Field(index=True, foreign_key="printers.id")
+    job_ids: list[str] = Field(default_factory=list, sa_column=Column(JSON))
+    created_by: str = Field(index=True, description="SSO-Email oder API-Key-ID")
+    created_at: datetime = Field(
+        default_factory=lambda: datetime.now(UTC),
+        sa_column=Column(DateTime(timezone=True), nullable=False, index=True),
+    )

backend/app/models/printer.py

@@ -15,6 +15,13 @@ class Printer(SQLModel, table=True):
 
     id: UUID = Field(default_factory=uuid4, primary_key=True)
     name: str = Field(index=True, unique=True)
+    slug: str = Field(
+        default="",
+        index=True,
+        unique=True,
+        description="Stable URL-safe identifier (e.g., 'brother-p750w'). "
+        "Defaults to slugified name on init.",
+    )
     model: str
     backend: str
     connection: dict[str, Any] = Field(default_factory=dict, sa_column=Column(JSON))

backend/app/repositories/print_batches.py

@@ -0,0 +1,43 @@
+"""CRUD für PrintBatch-Aggregat."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime, timedelta
+from uuid import UUID
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlmodel import col
+
+from app.models.print_batch import PrintBatch
+
+
+async def create(session: AsyncSession, batch: PrintBatch) -> PrintBatch:
+    session.add(batch)
+    await session.commit()
+    await session.refresh(batch)
+    return batch
+
+
+async def get(session: AsyncSession, batch_id: UUID) -> PrintBatch | None:
+    return await session.get(PrintBatch, batch_id)
+
+
+async def list_recent(session: AsyncSession, hours: int = 24) -> list[PrintBatch]:
+    since = datetime.now(UTC) - timedelta(hours=hours)
+    result = await session.execute(
+        select(PrintBatch)
+        .where(col(PrintBatch.created_at) >= since)
+        .order_by(col(PrintBatch.created_at).desc())
+    )
+    return list(result.scalars())
+
+
+async def prune_older_than(session: AsyncSession, hours: int = 24) -> int:
+    cutoff = datetime.now(UTC) - timedelta(hours=hours)
+    result = await session.execute(select(PrintBatch).where(col(PrintBatch.created_at) < cutoff))
+    rows = list(result.scalars())
+    for row in rows:
+        await session.delete(row)
+    await session.commit()
+    return len(rows)