dirigent-server 0.9.0__py3-none-any.whl

dirigent_server/routes/schema.py

@@ -0,0 +1,27 @@
+"""The machine-readable shape of a document, for anything that edits one."""
+
+from fastapi import APIRouter
+
+from dirigent_common import JsonMap
+from dirigent_core.documentschema import document_schema
+from dirigent_server.dependencies import ServicesDep
+from dirigent_server.security import PrincipalDep
+from dirigent_server.transactions import Transactional
+
+router = APIRouter(route_class=Transactional, tags=["schema"])
+
+
+@router.get(
+    "/schema/document",
+    operation_id="getDocumentSchema",
+    summary="The JSON Schema a pipeline document is written against",
+    response_model=JsonMap,
+)
+async def get_document_schema(services: ServicesDep, principal: PrincipalDep) -> JsonMap:
+    """Serve ``dirigent/v1`` composed with this instance's block config schemas.
+
+    Each installed block contributes an ``if``/``then`` case on a step, so a config key the
+    named block does not take is wrong in an editor for the same reason an apply refuses it.
+    An instance with a plugin another instance lacks therefore answers with a different schema.
+    """
+    return document_schema(services.host.catalog())

dirigent_server/routes/schemas.py

@@ -0,0 +1,127 @@
+"""Schemas: named JSON Schemas an instance holds, addressable by code and referenced by name.
+
+A schema is locally authored, exactly like a pipeline or a connection: a person writes the
+shape they expect a payload to have and applies it. Nothing here fetches or introspects a
+schema from anywhere. Because a schema is a JSON Schema in its own right, its identity is
+read from its own keywords -- ``$id`` for the code, ``title`` for the name, ``description``
+for the description -- when a write does not give one, so what is stored is a portable
+schema rather than a wrapper around one. A stored body is checked to be a valid JSON Schema
+(Draft 2020-12) before anything lands.
+"""
+
+import sqlalchemy as sa
+from fastapi import APIRouter, HTTPException, Response, status
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from dirigent_client.schemas import Page, SchemaIn, SchemaOut, SchemaUpdate
+from dirigent_core.models import Schema
+from dirigent_core.schemas import SchemaRefused, check_valid_schema, resolve_identity
+from dirigent_server.dependencies import SessionDep
+from dirigent_server.pagination import DEFAULT_PAGE, AfterParam, LimitParam, clip
+from dirigent_server.security import AdminDep, PrincipalDep
+from dirigent_server.transactions import Transactional
+
+router = APIRouter(route_class=Transactional, tags=["schemas"])
+
+
+def render(row: Schema) -> SchemaOut:
+    """Render a stored schema for a response."""
+    return SchemaOut(
+        id=row.id,
+        code=row.code,
+        name=row.name,
+        description=row.description,
+        body=row.body,
+        created_at=row.created_at,
+        updated_at=row.updated_at,
+    )
+
+
+async def find(session: AsyncSession, code: str) -> Schema:
+    """Read one stored schema by code, or 404."""
+    row = (await session.execute(sa.select(Schema).where(Schema.code == code))).scalar_one_or_none()
+    if row is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"no schema coded {code!r}")
+    return row
+
+
+@router.get("/schemas", operation_id="listSchemas", summary="List schemas", response_model=Page[SchemaOut])
+async def list_schemas(
+    session: SessionDep,
+    principal: PrincipalDep,
+    after: AfterParam = None,
+    limit: LimitParam = DEFAULT_PAGE,
+) -> Page[SchemaOut]:
+    """List every schema the instance holds."""
+    statement = sa.select(Schema).order_by(Schema.code).limit(limit + 1)
+    if after is not None:
+        statement = statement.where(Schema.code > after)
+    rows = await session.execute(statement)
+    found = [render(row) for row in rows.scalars()]
+    items, following = clip(found, limit, lambda row: row.code)
+    return Page(items=items, next=following)
+
+
+@router.post(
+    "/schemas",
+    operation_id="createSchema",
+    summary="Store a schema",
+    response_model=SchemaOut,
+    status_code=status.HTTP_201_CREATED,
+)
+async def create_schema(payload: SchemaIn, session: SessionDep, principal: AdminDep) -> SchemaOut:
+    """Store a JSON Schema, taking its identity from its own keywords when the write gives none."""
+    try:
+        check_valid_schema(payload.body)
+        code, name, description = resolve_identity(
+            payload.body, code=payload.code, name=payload.name, description=payload.description
+        )
+    except SchemaRefused as error:
+        raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_CONTENT, detail=str(error)) from error
+    existing = (await session.execute(sa.select(Schema).where(Schema.code == code))).scalar_one_or_none()
+    if existing is not None:
+        raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail=f"a schema coded {code!r} exists")
+    row = Schema(code=code, name=name, description=description, body=payload.body)
+    session.add(row)
+    await session.flush()
+    return render(row)
+
+
+@router.get("/schemas/{code}", operation_id="getSchema", summary="Read a schema", response_model=SchemaOut)
+async def get_schema(code: str, session: SessionDep, principal: PrincipalDep) -> SchemaOut:
+    """Read one schema by its code."""
+    return render(await find(session, code))
+
+
+@router.patch("/schemas/{code}", operation_id="updateSchema", summary="Update a schema", response_model=SchemaOut)
+async def update_schema(code: str, payload: SchemaUpdate, session: SessionDep, principal: AdminDep) -> SchemaOut:
+    """Replace a schema's body or its labels; the code is fixed once minted.
+
+    A field left out is left alone; a name or description sent as null is cleared. A body
+    sent replaces the stored schema and is checked the same way a create's is.
+    """
+    row = await find(session, code)
+    if payload.changing("name"):
+        row.name = payload.name
+    if payload.changing("description"):
+        row.description = payload.description
+    if payload.body is not None:
+        try:
+            check_valid_schema(payload.body)
+        except SchemaRefused as error:
+            raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_CONTENT, detail=str(error)) from error
+        row.body = payload.body
+    await session.flush()
+    return render(row)
+
+
+@router.delete(
+    "/schemas/{code}",
+    operation_id="deleteSchema",
+    summary="Delete a schema",
+    status_code=status.HTTP_204_NO_CONTENT,
+)
+async def delete_schema(code: str, session: SessionDep, principal: AdminDep) -> Response:
+    """Remove a schema."""
+    await session.delete(await find(session, code))
+    return Response(status_code=status.HTTP_204_NO_CONTENT)

dirigent_server/routes/system.py

@@ -0,0 +1,63 @@
+"""What this instance is, and whether everything it depends on is answering."""
+
+import asyncio
+
+import sqlalchemy as sa
+from fastapi import APIRouter
+
+from dirigent_client.schemas import ConnectionHealth, SystemInfo
+from dirigent_core import __version__
+from dirigent_core.models import Connection, Worker, utcnow
+from dirigent_core.registry import STALE_AFTER
+from dirigent_server.dependencies import ServicesDep, SessionDep, SettingsDep
+from dirigent_server.routes.connections import check
+from dirigent_server.security import PrincipalDep
+from dirigent_server.transactions import Transactional
+
+router = APIRouter(route_class=Transactional, tags=["system"])
+
+
+@router.get(
+    "/system/info",
+    operation_id="getSystemInfo",
+    summary="Describe the instance and check every connection",
+    response_model=SystemInfo,
+)
+async def system_info(
+    session: SessionDep,
+    services: ServicesDep,
+    settings: SettingsDep,
+    principal: PrincipalDep,
+) -> SystemInfo:
+    """Describe the instance, and fan out over every connection's own health check."""
+    catalog = services.host.catalog()
+    rows = list((await session.execute(sa.select(Connection).order_by(Connection.code))).scalars())
+    reports = await asyncio.gather(*(check(row, services) for row in rows))
+    live = await session.execute(
+        sa.select(sa.func.count()).select_from(Worker).where(Worker.last_seen_at >= utcnow() - STALE_AFTER)
+    )
+    return SystemInfo(
+        version=__version__,
+        environment=settings.environment,
+        database="sqlite" if settings.is_sqlite else "postgresql",
+        checked_at=utcnow(),
+        plugins=catalog.plugins,
+        blocks=len(catalog.blocks),
+        storage_schemes=services.storage.schemes,
+        notifiers=[entry.id for entry in catalog.notifiers],
+        connection_kinds=[entry.id for entry in catalog.connection_kinds],
+        workers_live=int(live.scalar_one()),
+        unsafe_blocks_enabled=list(settings.enabled_unsafe_blocks),
+        secrets_configured=services.secrets.available,
+        connections=[
+            ConnectionHealth(
+                code=row.code,
+                name=row.name,
+                kind=row.kind,
+                connected=report.healthy,
+                detail=report.detail,
+                version=report.version,
+            )
+            for row, report in zip(rows, reports, strict=True)
+        ],
+    )

dirigent_server/routes/trigger_documents.py

@@ -0,0 +1,109 @@
+"""Triggers documents: the clocks and webhooks one document declares for another's pipeline.
+
+A document is applied through ``POST /pipelines/$apply`` like any other; what is here is
+reading the ones the instance holds, and removing one with the rows it owns.
+"""
+
+import sqlalchemy as sa
+from fastapi import APIRouter, HTTPException, Response, status
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from dirigent_client.schemas import Page, TriggerDocumentDetail, TriggerDocumentOut
+from dirigent_core.models import Pipeline, TriggerDocument
+from dirigent_core.trigger_documents import (
+    delete_trigger_document,
+    find_trigger_document,
+    list_trigger_documents,
+    owned_codes,
+)
+from dirigent_server.dependencies import SessionDep
+from dirigent_server.pagination import DEFAULT_PAGE, AfterParam, LimitParam, clip
+from dirigent_server.security import OperatorDep, PrincipalDep
+from dirigent_server.transactions import Transactional
+
+router = APIRouter(route_class=Transactional, tags=["triggers"])
+
+
+def render(row: TriggerDocument, pipeline: str) -> TriggerDocumentOut:
+    """Render a triggers document row beside the code of the pipeline it fires."""
+    return TriggerDocumentOut(
+        id=row.id,
+        code=row.code,
+        name=row.name,
+        description=row.description,
+        pipeline=pipeline,
+        digest=row.digest,
+        provenance_source=row.provenance_source,
+        provenance_ref=row.provenance_ref,
+        applied_by=row.applied_by,
+        created_at=row.created_at,
+        updated_at=row.updated_at,
+    )
+
+
+@router.get(
+    "/trigger-documents",
+    operation_id="listTriggerDocuments",
+    summary="List triggers documents",
+    response_model=Page[TriggerDocumentOut],
+)
+async def list_all(
+    session: SessionDep,
+    principal: PrincipalDep,
+    after: AfterParam = None,
+    limit: LimitParam = DEFAULT_PAGE,
+) -> Page[TriggerDocumentOut]:
+    """List every triggers document, in code order, with the pipeline each one fires."""
+    rows = await list_trigger_documents(session, after=after, limit=limit + 1)
+    found = [render(row, await _pipeline_code(session, row)) for row in rows]
+    items, following = clip(found, limit, lambda row: row.code)
+    return Page(items=items, next=following)
+
+
+@router.get(
+    "/trigger-documents/{code}",
+    operation_id="getTriggerDocument",
+    summary="Read a triggers document",
+    response_model=TriggerDocumentDetail,
+)
+async def get_one(code: str, session: SessionDep, principal: PrincipalDep) -> TriggerDocumentDetail:
+    """Read one triggers document, the document itself, and the rows it owns."""
+    row = await _require(session, code)
+    schedules, webhooks = await owned_codes(session, row.id)
+    base = render(row, await _pipeline_code(session, row))
+    return TriggerDocumentDetail(
+        **base.model_dump(),
+        document=dict(row.document),
+        schedules=schedules,
+        webhooks=webhooks,
+    )
+
+
+@router.delete(
+    "/trigger-documents/{code}",
+    operation_id="deleteTriggerDocument",
+    summary="Delete a triggers document and its rows",
+    status_code=status.HTTP_204_NO_CONTENT,
+)
+async def delete(code: str, session: SessionDep, principal: OperatorDep) -> Response:
+    """Remove a triggers document, and with it every schedule and webhook it declared.
+
+    The pipeline it named is untouched, and so is anything the pipeline's own document or an
+    operator declared on it.
+    """
+    await delete_trigger_document(session, await _require(session, code))
+    return Response(status_code=status.HTTP_204_NO_CONTENT)
+
+
+async def _require(session: AsyncSession, code: str) -> TriggerDocument:
+    """Read a triggers document by code, translating "no such thing" into a 404."""
+    row = await find_trigger_document(session, code)
+    if row is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"no triggers document coded {code!r}")
+    return row
+
+
+async def _pipeline_code(session: AsyncSession, row: TriggerDocument) -> str:
+    """Name the pipeline a triggers document fires; the cascade guarantees it is there."""
+    found = await session.execute(sa.select(Pipeline.code).where(Pipeline.id == row.pipeline_id))
+    return str(found.scalar_one())