dirigent-server 0.9.0__py3-none-any.whl

dirigent_server/routes/alerts.py

@@ -0,0 +1,289 @@
+"""Alert rules, and the notification queue they deliver through."""
+
+from datetime import timedelta
+from typing import Annotated
+from uuid import UUID
+
+from fastapi import APIRouter, HTTPException, Query, Response, status
+
+from dirigent_client.enums import NotificationStatus
+from dirigent_client.schemas import (
+    AlertRuleIn,
+    AlertRuleOut,
+    AlertRuleUpdate,
+    NotificationOut,
+    Page,
+    TestQueued,
+    TestRequest,
+)
+from dirigent_common.durations import format_duration
+from dirigent_core.alerting import (
+    AlertError,
+    AlertRuleRequest,
+    create_rule,
+    delete_rule,
+    find_notification,
+    find_rule,
+    list_notifications,
+    list_rules,
+    queue_test_message,
+    retry_notification,
+    set_paused,
+)
+from dirigent_core.models import AlertRule, Connection, Notification, Pipeline, Run
+from dirigent_server.dependencies import ServicesDep, SessionDep
+from dirigent_server.pagination import DEFAULT_PAGE, AfterParam, LimitParam, clip, uuid_cursor
+from dirigent_server.security import OperatorDep, PrincipalDep
+from dirigent_server.transactions import Transactional
+
+router = APIRouter(route_class=Transactional, tags=["alerts"])
+
+
+def render(rule: AlertRule, pipeline: str | None, connection: str | None = None) -> AlertRuleOut:
+    """Render an alert rule, writing its throttle back as the humane duration it was."""
+    return AlertRuleOut(
+        id=rule.id,
+        code=rule.code,
+        name=rule.name,
+        description=rule.description,
+        event=rule.event,
+        scope=rule.scope,
+        pipeline=pipeline,
+        notifier=rule.notifier,
+        connection=connection,
+        template=rule.template,
+        throttle=format_duration(timedelta(seconds=rule.throttle_seconds)),
+        active=rule.active,
+        paused=rule.paused,
+        last_sent_at=rule.last_sent_at,
+        created_at=rule.created_at,
+    )
+
+
+@router.get(
+    "/alert-rules",
+    operation_id="listAlertRules",
+    summary="List alert rules",
+    response_model=Page[AlertRuleOut],
+)
+async def rules(
+    session: SessionDep,
+    principal: PrincipalDep,
+    after: AfterParam = None,
+    limit: LimitParam = DEFAULT_PAGE,
+) -> Page[AlertRuleOut]:
+    """List every alert rule, with the pipeline each one watches when it is scoped."""
+    rows = await list_rules(session, after=uuid_cursor(after), limit=limit + 1)
+    found = [
+        render(rule, await _pipeline_code(session, rule), await _connection_code(session, rule.connection_id))
+        for rule in rows
+    ]
+    items, following = clip(found, limit, lambda row: row.id)
+    return Page(items=items, next=following)
+
+
+@router.post(
+    "/alert-rules",
+    operation_id="createAlertRule",
+    summary="Declare an alert rule",
+    response_model=AlertRuleOut,
+    status_code=status.HTTP_201_CREATED,
+)
+async def add_rule(
+    payload: AlertRuleIn, session: SessionDep, services: ServicesDep, principal: OperatorDep
+) -> AlertRuleOut:
+    """Declare an alert rule, refusing a notifier or a pipeline this instance does not have."""
+    try:
+        rule = await create_rule(
+            session,
+            services,
+            AlertRuleRequest(
+                code=payload.code,
+                name=payload.name,
+                description=payload.description,
+                event=payload.event,
+                notifier=payload.notifier,
+                scope=payload.scope,
+                pipeline=payload.pipeline,
+                connection=payload.connection,
+                template=payload.template,
+                throttle=payload.throttle,
+            ),
+        )
+    except AlertError as error:
+        raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_CONTENT, detail=str(error)) from error
+    return render(rule, payload.pipeline, payload.connection)
+
+
+@router.patch(
+    "/alert-rules/{code}",
+    operation_id="updateAlertRule",
+    summary="Pause or resume an alert rule",
+    response_model=AlertRuleOut,
+)
+async def change_rule(code: str, payload: AlertRuleUpdate, session: SessionDep, principal: OperatorDep) -> AlertRuleOut:
+    """Hold a rule's deliveries, or let them resume.
+
+    Pausing is instance state on the row rather than something the rule declares, so a rule an
+    operator held keeps holding when the document that declared it is applied again.
+    """
+    rule = await _rule_or_404(session, code)
+    await set_paused(session, rule, paused=payload.paused)
+    return render(rule, await _pipeline_code(session, rule), await _connection_code(session, rule.connection_id))
+
+
+@router.delete(
+    "/alert-rules/{code}",
+    operation_id="deleteAlertRule",
+    summary="Delete an alert rule",
+    status_code=status.HTTP_204_NO_CONTENT,
+)
+async def remove_rule(code: str, session: SessionDep, principal: OperatorDep) -> Response:
+    """Remove an alert rule; the notifications it already raised are kept."""
+    await delete_rule(session, await _rule_or_404(session, code))
+    return Response(status_code=status.HTTP_204_NO_CONTENT)
+
+
+@router.post(
+    "/alert-rules/$test",
+    operation_id="testNotifier",
+    summary="Send a test message through a notifier",
+    response_model=TestQueued,
+    status_code=status.HTTP_202_ACCEPTED,
+)
+async def test_notifier(
+    payload: TestRequest, session: SessionDep, services: ServicesDep, principal: OperatorDep
+) -> TestQueued:
+    """Queue one message through a channel, on the same path a real alert takes."""
+    try:
+        notification = await queue_test_message(
+            session,
+            services,
+            notifier=payload.notifier,
+            connection=payload.connection,
+            subject=payload.subject,
+            body=payload.body,
+        )
+    except AlertError as error:
+        raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_CONTENT, detail=str(error)) from error
+    return TestQueued(notification_id=notification.id, notifier=notification.notifier)
+
+
+@router.get(
+    "/notifications",
+    operation_id="listNotifications",
+    summary="List queued and delivered alerts",
+    response_model=Page[NotificationOut],
+)
+async def notifications(
+    session: SessionDep,
+    services: ServicesDep,
+    principal: PrincipalDep,
+    run_id: Annotated[UUID | None, Query(description="Only this run's notifications.")] = None,
+    notification_status: Annotated[
+        NotificationStatus | None, Query(alias="status", description="Only rows in this state.")
+    ] = None,
+    notifier: Annotated[str | None, Query(description="Only rows this channel delivers.")] = None,
+    after: AfterParam = None,
+    limit: LimitParam = DEFAULT_PAGE,
+) -> Page[NotificationOut]:
+    """Read the alert queue, newest first."""
+    rows = await list_notifications(
+        session,
+        run_id=run_id,
+        notification_status=notification_status,
+        notifier=notifier,
+        after=uuid_cursor(after),
+        limit=limit + 1,
+    )
+    found = [await _notification(session, services, row) for row in rows]
+    items, following = clip(found, limit, lambda row: row.id)
+    return Page(items=items, next=following)
+
+
+@router.get(
+    "/notifications/{notification_id}",
+    operation_id="getNotification",
+    summary="Read one queued or delivered alert",
+    response_model=NotificationOut,
+)
+async def notification(
+    notification_id: UUID, session: SessionDep, services: ServicesDep, principal: PrincipalDep
+) -> NotificationOut:
+    """Read one notification, which is how a caller watches a delivery it just queued."""
+    return await _notification(session, services, await _notification_or_404(session, notification_id))
+
+
+@router.post(
+    "/notifications/{notification_id}/$retry",
+    operation_id="retryNotification",
+    summary="Put a notification back on the queue",
+    response_model=NotificationOut,
+)
+async def retry(
+    notification_id: UUID, session: SessionDep, services: ServicesDep, principal: OperatorDep
+) -> NotificationOut:
+    """Make one notification due now, so a worker takes it on its next pass."""
+    row = await _notification_or_404(session, notification_id)
+    try:
+        await retry_notification(session, row)
+    except AlertError as error:
+        raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail=str(error)) from error
+    return await _notification(session, services, row)
+
+
+async def _notification(session: SessionDep, services: ServicesDep, row: Notification) -> NotificationOut:
+    """Render one notification row, naming the run by its pipeline rather than by its id."""
+    run = await session.get(Run, row.run_id) if row.run_id else None
+    pipeline = await session.get(Pipeline, run.pipeline_id) if run else None
+    rule = await session.get(AlertRule, row.alert_rule_id) if row.alert_rule_id else None
+    return NotificationOut(
+        id=row.id,
+        event=row.event,
+        rule=rule.code if rule else None,
+        notifier=row.notifier,
+        connection=await _connection_code(session, row.connection_id),
+        subject=row.subject,
+        status=row.status,
+        attempt=row.attempt,
+        max_attempts=services.settings.notification_max_attempts,
+        run_id=row.run_id,
+        run_pipeline=pipeline.code if pipeline else None,
+        run_started_at=run.started_at if run else None,
+        available_at=row.available_at,
+        sent_at=row.sent_at,
+        error=row.error,
+        created_at=row.created_at,
+    )
+
+
+async def _notification_or_404(session: SessionDep, notification_id: UUID) -> Notification:
+    """Find one notification, or refuse with the id that named nothing."""
+    row = await find_notification(session, notification_id)
+    if row is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"no notification {notification_id}")
+    return row
+
+
+async def _rule_or_404(session: SessionDep, code: str) -> AlertRule:
+    """Find one alert rule, or refuse with the code that named nothing."""
+    rule = await find_rule(session, code)
+    if rule is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"no alert rule coded {code!r}")
+    return rule
+
+
+async def _pipeline_code(session: SessionDep, rule: AlertRule) -> str | None:
+    """Resolve the code of the pipeline a scoped rule watches."""
+    if rule.pipeline_id is None:
+        return None
+    pipeline = await session.get(Pipeline, rule.pipeline_id)
+    return pipeline.code if pipeline else None
+
+
+async def _connection_code(session: SessionDep, connection_id: UUID | None) -> str | None:
+    """Resolve the code of the connection a channel delivers through."""
+    if connection_id is None:
+        return None
+    connection = await session.get(Connection, connection_id)
+    return connection.code if connection else None

dirigent_server/routes/auth.py

@@ -0,0 +1,218 @@
+"""Logging in, logging out, and asking who you are."""
+
+from fastapi import APIRouter, HTTPException, Request, Response, status
+
+from dirigent_client.enums import TokenKind
+from dirigent_client.schemas import (
+    Identity,
+    IssuedTokenOut,
+    LoginRequest,
+    Page,
+    PasswordChangeRequest,
+    TokenOut,
+    TokenRequest,
+)
+from dirigent_core.auth import (
+    SESSION_LIFETIME,
+    Principal,
+    WeakPassword,
+    WrongPassword,
+    authenticate,
+    change_password,
+    issue_token,
+    list_tokens,
+    revoke_session,
+    revoke_token,
+)
+from dirigent_core.auth import find_user as find_user_row
+from dirigent_core.models import User
+from dirigent_core.ratelimit import TokenBucket
+from dirigent_server.dependencies import SessionDep, SettingsDep
+from dirigent_server.logging import get_logger
+from dirigent_server.pagination import DEFAULT_PAGE, AfterParam, LimitParam, clip, uuid_cursor
+from dirigent_server.security import (
+    AdminDep,
+    PrincipalDep,
+    clear_session_cookie,
+    presented_secret,
+    set_session_cookie,
+)
+from dirigent_server.transactions import Transactional
+
+router = APIRouter(route_class=Transactional, tags=["auth"])
+
+_logger = get_logger("auth")
+
+#: Mounted outside the principal dependency; login is the only unauthenticated route.
+public_router = APIRouter(route_class=Transactional, tags=["auth"])
+
+
+LOGIN_BUCKETS = TokenBucket()
+
+
+@public_router.post(
+    "/auth/login",
+    operation_id="login",
+    summary="Log in and receive a session cookie",
+    response_model=Identity,
+    responses={429: {"description": "Too many login attempts from this address or for this account."}},
+)
+async def login(
+    payload: LoginRequest,
+    request: Request,
+    response: Response,
+    session: SessionDep,
+    settings: SettingsDep,
+) -> Identity:
+    """Verify a username and password, and set an http-only session cookie."""
+    _limit_login(request, payload.username, per_minute=settings.login_rate_per_minute)
+    user = await authenticate(session, payload.username, payload.password.get_secret_value())
+    if user is None:
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="invalid username or password")
+    issued = await issue_token(session, user, name="session", kind=TokenKind.SESSION, lifetime=SESSION_LIFETIME)
+    set_session_cookie(
+        response,
+        issued.secret.get_secret_value(),
+        max_age=int(SESSION_LIFETIME.total_seconds()),
+        secure=settings.environment != "local",
+    )
+    return Identity(user_id=user.id, username=user.username, role=user.role, via=TokenKind.SESSION)
+
+
+def _limit_login(request: Request, username: str, *, per_minute: int) -> None:
+    """Refuse a caller attempting logins faster than the instance is willing to hash.
+
+    Login is unauthenticated and runs Argon2id, so an unlimited caller can spend the whole
+    process's memory and CPU. Both keys have to pass: the address bound stops one machine
+    from flooding the process, and the username bound stops a stuffing run spread across
+    many addresses from concentrating on one account. Refusal must stay ahead of the hash.
+    """
+    address = request.client.host if request.client else "unknown"
+    for scope, key in (("address", f"address:{address}"), ("account", f"user:{username}")):
+        if not LOGIN_BUCKETS.allow(key, per_minute=per_minute):
+            _logger.warning("login rate limited", scope=scope, address=address, limit=per_minute)
+            raise HTTPException(
+                status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+                detail=f"too many login attempts; this instance accepts {per_minute} a minute",
+                headers={"Retry-After": "60"},
+            )
+
+
+@router.post("/auth/logout", operation_id="logout", summary="Log out", status_code=status.HTTP_204_NO_CONTENT)
+async def logout(request: Request, session: SessionDep, principal: PrincipalDep) -> Response:
+    """Revoke the presented session and clear its cookie.
+
+    The cookie is cleared on the response this returns. Clearing it on the injected one and
+    returning another discards the header, because a route that returns a Response returns
+    that Response and nothing is merged into it.
+    """
+    secret = presented_secret(request)
+    if secret is not None and principal.via is TokenKind.SESSION:
+        await revoke_session(session, secret)
+    response = Response(status_code=status.HTTP_204_NO_CONTENT)
+    clear_session_cookie(response)
+    return response
+
+
+@router.post(
+    "/auth/password",
+    operation_id="changePassword",
+    summary="Change your own password",
+    status_code=status.HTTP_204_NO_CONTENT,
+)
+async def change_own_password(
+    payload: PasswordChangeRequest,
+    session: SessionDep,
+    principal: PrincipalDep,
+) -> Response:
+    """Replace the caller's own password, ending every other session the account holds.
+
+    The credential this request arrived on survives, so the change does not log the person
+    out of the page they made it from. An API token is not a session and is untouched.
+    """
+    user = await _require_user(session, principal.username)
+    try:
+        await change_password(
+            session,
+            user,
+            payload.current_password.get_secret_value(),
+            payload.new_password.get_secret_value(),
+            keep=principal.token_id,
+        )
+    except WrongPassword as error:
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail=str(error)) from error
+    except WeakPassword as error:
+        raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_CONTENT, detail=str(error)) from error
+    return Response(status_code=status.HTTP_204_NO_CONTENT)
+
+
+@router.get("/auth/me", operation_id="whoami", summary="Describe the authenticated caller", response_model=Identity)
+async def whoami(principal: PrincipalDep) -> Identity:
+    """Report who this request is acting as, and which credential said so."""
+    return identity_of(principal)
+
+
+def identity_of(principal: Principal) -> Identity:
+    """Render a principal for the API, which never exposes the credential itself."""
+    return Identity(
+        user_id=principal.user_id,
+        username=principal.username,
+        role=principal.role,
+        via=principal.via,
+        token_name=principal.token_name,
+    )
+
+
+@router.get("/tokens", operation_id="listTokens", summary="List API tokens", response_model=Page[TokenOut])
+async def list_api_tokens(
+    session: SessionDep,
+    principal: AdminDep,
+    after: AfterParam = None,
+    limit: LimitParam = DEFAULT_PAGE,
+) -> Page[TokenOut]:
+    """List every API token, without its secret; sessions are not listed."""
+    rows = await list_tokens(session, after=uuid_cursor(after), limit=limit + 1)
+    found = [TokenOut.model_validate(token, from_attributes=True) for token in rows]
+    items, following = clip(found, limit, lambda row: row.id)
+    return Page(items=items, next=following)
+
+
+@router.post(
+    "/tokens",
+    operation_id="createToken",
+    summary="Create an API token",
+    response_model=IssuedTokenOut,
+    status_code=status.HTTP_201_CREATED,
+)
+async def create_api_token(payload: TokenRequest, session: SessionDep, principal: AdminDep) -> IssuedTokenOut:
+    """Mint a bearer token for automation and return its secret exactly once."""
+    user = await _require_user(session, principal.username)
+    issued = await issue_token(session, user, name=payload.name)
+    return IssuedTokenOut(
+        id=issued.id,
+        name=issued.name,
+        username=issued.username,
+        prefix=issued.prefix,
+        token=issued.secret.get_secret_value(),
+    )
+
+
+@router.delete(
+    "/tokens/{name}",
+    operation_id="revokeToken",
+    summary="Revoke one of your own API tokens",
+    status_code=status.HTTP_204_NO_CONTENT,
+)
+async def revoke_api_token(name: str, session: SessionDep, principal: AdminDep) -> Response:
+    """Revoke the caller's live tokens of the given name."""
+    if not await revoke_token(session, user_id=principal.user_id, name=name):
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"no live token named {name!r}")
+    return Response(status_code=status.HTTP_204_NO_CONTENT)
+
+
+async def _require_user(session: SessionDep, username: str) -> User:
+    """Read the account a principal names."""
+    user = await find_user_row(session, username)
+    if user is None:  # pragma: no cover - a resolved principal always has its row
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="the authenticated account is gone")
+    return user

dirigent_server/routes/blocks.py

@@ -0,0 +1,39 @@
+"""The block catalog every installed plugin contributes to."""
+
+from typing import Annotated
+
+from fastapi import APIRouter, HTTPException, Query, status
+
+from dirigent_client.schemas import BlockEntry, BlockKind, Catalog
+from dirigent_server.dependencies import ServicesDep
+from dirigent_server.security import PrincipalDep
+from dirigent_server.transactions import Transactional
+
+router = APIRouter(route_class=Transactional, tags=["blocks"])
+
+
+@router.get("/blocks", operation_id="getCatalog", summary="The block catalog", response_model=Catalog)
+async def get_catalog(
+    services: ServicesDep,
+    principal: PrincipalDep,
+    kind: Annotated[BlockKind | None, Query(description="Return only operators, or only sensors.")] = None,
+) -> Catalog:
+    """Serve every contributed operator, sensor, storage scheme, notifier, and connection kind."""
+    catalog = services.host.catalog()
+    if kind is None:
+        return catalog
+    return catalog.model_copy(update={"blocks": [block for block in catalog.blocks if block.kind is kind]})
+
+
+@router.get(
+    "/blocks/{block_id}",
+    operation_id="getBlock",
+    summary="One block's schemas",
+    response_model=BlockEntry,
+)
+async def get_block(block_id: str, services: ServicesDep, principal: PrincipalDep) -> BlockEntry:
+    """Serve one catalog entry."""
+    entry = services.host.catalog().block(block_id)
+    if entry is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"no block {block_id!r} is installed")
+    return entry