dirigent-client 0.9.0__py3-none-any.whl

dirigent_client/resources/trigger_documents.py

@@ -0,0 +1,20 @@
+"""Triggers documents: the clocks and webhooks one document declares for another's pipeline."""
+
+from dirigent_client.resources.base import Resource, query
+from dirigent_client.schemas import Page, TriggerDocumentDetail, TriggerDocumentOut
+
+
+class TriggerDocuments(Resource):
+    """Read and remove the ``kind: triggers`` documents this instance holds."""
+
+    async def list(self, *, after: str | None = None, limit: int | None = None) -> Page[TriggerDocumentOut]:
+        """List every triggers document, in code order."""
+        return await self._many(TriggerDocumentOut, "GET", "/trigger-documents", params=query(after=after, limit=limit))
+
+    async def get(self, code: str) -> TriggerDocumentDetail:
+        """Read one triggers document, with the rows it owns."""
+        return await self._one(TriggerDocumentDetail, "GET", f"/trigger-documents/{code}")
+
+    async def delete(self, code: str) -> None:
+        """Remove a triggers document and every schedule and webhook it owns."""
+        await self._transport.request("DELETE", f"/trigger-documents/{code}")

dirigent_client/resources/webhooks.py

@@ -0,0 +1,80 @@
+"""A pipeline's inbound webhooks: their mapping, their token, and what has arrived."""
+
+from pydantic import SecretStr
+
+from dirigent_client.enums import RunPriority
+from dirigent_client.resources.base import Resource, query, request_body
+from dirigent_client.schemas import DeliveryOut, Page, WebhookIn, WebhookOut, WebhookTokenOut
+
+
+class Webhooks(Resource):
+    """Declare, enable, rotate, and read the webhooks hanging from a pipeline."""
+
+    async def list(self, pipeline: str, *, after: str | None = None, limit: int | None = None) -> Page[WebhookOut]:
+        """List every webhook on a pipeline, with its mapping but never its token."""
+        return await self._many(
+            WebhookOut,
+            "GET",
+            f"/pipelines/{pipeline}/triggers/webhooks",
+            params=query(after=after, limit=limit),
+        )
+
+    async def get(self, pipeline: str, code: str) -> WebhookOut:
+        """Read one webhook by code, with its mapping but never its token."""
+        return await self._one(WebhookOut, "GET", f"/pipelines/{pipeline}/triggers/webhooks/{code}")
+
+    async def create(
+        self,
+        pipeline: str,
+        code: str,
+        *,
+        name: str | None = None,
+        description: str | None = None,
+        params_from_payload: dict[str, str] | None = None,
+        hmac_secret: str | None = None,
+        rate_limit_per_minute: int = 60,
+        priority: RunPriority | None = None,
+    ) -> WebhookTokenOut:
+        """Declare a webhook and return its token, which is shown here and nowhere else again."""
+        payload = WebhookIn(
+            code=code,
+            name=name,
+            description=description,
+            params_from_payload=params_from_payload or {},
+            hmac_secret=SecretStr(hmac_secret) if hmac_secret else None,
+            rate_limit_per_minute=rate_limit_per_minute,
+            priority=priority,
+        )
+        return await self._one(
+            WebhookTokenOut,
+            "POST",
+            f"/pipelines/{pipeline}/triggers/webhooks",
+            json=request_body(payload),
+        )
+
+    async def rotate_token(self, pipeline: str, code: str) -> WebhookTokenOut:
+        """Mint a new token and forget the old one immediately; callers must be updated."""
+        return await self._one(WebhookTokenOut, "POST", f"/pipelines/{pipeline}/triggers/webhooks/{code}/$rotate-token")
+
+    async def enable(self, pipeline: str, code: str) -> WebhookOut:
+        """Accept deliveries again on the token that was already issued."""
+        return await self._one(WebhookOut, "POST", f"/pipelines/{pipeline}/triggers/webhooks/{code}/$enable")
+
+    async def disable(self, pipeline: str, code: str) -> WebhookOut:
+        """Refuse deliveries without rotating or losing the token."""
+        return await self._one(WebhookOut, "POST", f"/pipelines/{pipeline}/triggers/webhooks/{code}/$disable")
+
+    async def delete(self, pipeline: str, code: str) -> None:
+        """Remove a webhook, its token, and its delivery history."""
+        await self._transport.request("DELETE", f"/pipelines/{pipeline}/triggers/webhooks/{code}")
+
+    async def deliveries(
+        self, pipeline: str, code: str, *, after: str | None = None, limit: int | None = None
+    ) -> Page[DeliveryOut]:
+        """Read what has arrived, newest first, refusals included."""
+        return await self._many(
+            DeliveryOut,
+            "GET",
+            f"/pipelines/{pipeline}/triggers/webhooks/{code}/deliveries",
+            params=query(after=after, limit=limit),
+        )

dirigent_client/schemas/__init__.py

@@ -0,0 +1,164 @@
+"""The wire schemas: one definition of every shape the REST API accepts and answers with."""
+
+from dirigent_client.schemas.alerts import (
+    AlertRuleIn,
+    AlertRuleOut,
+    AlertRuleUpdate,
+    NotificationOut,
+    TestQueued,
+    TestRequest,
+)
+from dirigent_client.schemas.auth import (
+    Identity,
+    IssuedTokenOut,
+    LoginRequest,
+    PasswordChangeRequest,
+    PasswordResetRequest,
+    TokenOut,
+    TokenRequest,
+    UserIn,
+    UserOut,
+    UserUpdate,
+)
+from dirigent_client.schemas.catalog import BlockEntry, BlockKind, Catalog, SurfaceEntry
+from dirigent_client.schemas.common import Page, Problem
+from dirigent_client.schemas.connections import ConnectionIn, ConnectionOut, ConnectionUpdate
+from dirigent_client.schemas.pipelines import (
+    ApplyRequest,
+    ApplyResult,
+    BackfillAccepted,
+    BackfilledRun,
+    BackfillRequest,
+    DiffSummary,
+    LastRun,
+    Materialized,
+    PipelineDetail,
+    PipelineOut,
+    PipelinePlan,
+    PipelineVersionOut,
+    PlanAction,
+    PruneRequest,
+    PruneResult,
+    RunAccepted,
+    RunRequest,
+    ValidationIssue,
+)
+from dirigent_client.schemas.runs import (
+    TERMINAL_RUN_STATUSES,
+    AttemptEvent,
+    AttemptOut,
+    DagNode,
+    DagView,
+    ItemOut,
+    LogEntryOut,
+    RunDetail,
+    RunOut,
+    RunReport,
+    StepReport,
+)
+from dirigent_client.schemas.schemas import SchemaIn, SchemaOut, SchemaUpdate
+from dirigent_client.schemas.system import (
+    CheckResult,
+    CheckStatus,
+    ConnectionHealth,
+    Health,
+    Readiness,
+    SystemInfo,
+    WorkerOut,
+)
+from dirigent_client.schemas.triggers import (
+    DeliveryOut,
+    FiringOut,
+    HookAccepted,
+    ScheduleIn,
+    ScheduleOut,
+    SchedulePreview,
+    SchedulePreviewRequest,
+    TriggerDocumentDetail,
+    TriggerDocumentOut,
+    WebhookIn,
+    WebhookOut,
+    WebhookTokenOut,
+)
+from dirigent_common import JsonList, JsonMap
+
+__all__ = [
+    "TERMINAL_RUN_STATUSES",
+    "AlertRuleIn",
+    "AlertRuleOut",
+    "AlertRuleUpdate",
+    "ApplyRequest",
+    "ApplyResult",
+    "PruneRequest",
+    "PruneResult",
+    "BackfillAccepted",
+    "BackfillRequest",
+    "BackfilledRun",
+    "AttemptEvent",
+    "AttemptOut",
+    "BlockEntry",
+    "BlockKind",
+    "Catalog",
+    "CheckResult",
+    "CheckStatus",
+    "ConnectionHealth",
+    "ConnectionIn",
+    "ConnectionOut",
+    "ConnectionUpdate",
+    "SchemaIn",
+    "SchemaOut",
+    "SchemaUpdate",
+    "DagNode",
+    "DagView",
+    "DeliveryOut",
+    "DiffSummary",
+    "FiringOut",
+    "Health",
+    "HookAccepted",
+    "Identity",
+    "IssuedTokenOut",
+    "ItemOut",
+    "JsonList",
+    "JsonMap",
+    "LastRun",
+    "LogEntryOut",
+    "LoginRequest",
+    "Materialized",
+    "NotificationOut",
+    "Page",
+    "PasswordChangeRequest",
+    "PasswordResetRequest",
+    "PipelineDetail",
+    "PipelineOut",
+    "PipelinePlan",
+    "PipelineVersionOut",
+    "PlanAction",
+    "Problem",
+    "Readiness",
+    "RunAccepted",
+    "RunDetail",
+    "RunOut",
+    "RunReport",
+    "RunRequest",
+    "ScheduleIn",
+    "ScheduleOut",
+    "SchedulePreview",
+    "SchedulePreviewRequest",
+    "StepReport",
+    "SurfaceEntry",
+    "SystemInfo",
+    "TestQueued",
+    "TestRequest",
+    "TokenOut",
+    "TokenRequest",
+    "TriggerDocumentDetail",
+    "TriggerDocumentOut",
+    "UserIn",
+    "UserOut",
+    "UserUpdate",
+    "ValidationIssue",
+    "WebhookIn",
+    "WebhookOut",
+    "WebhookTokenOut",
+    "WorkerOut",
+]

dirigent_client/schemas/alerts.py

@@ -0,0 +1,90 @@
+"""Alert rules, and the notification queue they deliver through."""
+
+from datetime import datetime, timedelta
+from uuid import UUID
+
+from pydantic import BaseModel, Field
+
+from dirigent_client.enums import AlertEvent, AlertScope, NotificationStatus
+from dirigent_client.schemas.common import WireModel
+from dirigent_common import EntityName
+from dirigent_common.durations import Duration
+
+
+class AlertRuleIn(BaseModel):
+    """An alert rule as a caller declares it."""
+
+    code: EntityName
+    name: str | None = None
+    description: str | None = None
+    event: AlertEvent
+    notifier: str
+    scope: AlertScope = AlertScope.GLOBAL
+    pipeline: str | None = None
+    connection: str | None = None
+    template: str | None = Field(default=None, description="Message subject, reading ${run.*}.")
+    throttle: Duration = timedelta(0)
+
+
+class AlertRuleOut(WireModel):
+    """An alert rule as a listing shows it."""
+
+    id: UUID
+    code: str
+    name: str | None = None
+    description: str | None = None
+    event: AlertEvent
+    scope: AlertScope
+    pipeline: str | None = None
+    notifier: str
+    connection: str | None = None
+    template: str | None = None
+    throttle: str
+    active: bool
+    paused: bool = False
+    last_sent_at: datetime | None = None
+    created_at: datetime
+
+
+class AlertRuleUpdate(BaseModel):
+    """What a PATCH may change about an alert rule, which is whether it is paused."""
+
+    paused: bool
+
+
+class NotificationOut(WireModel):
+    """One queued or delivered alert."""
+
+    id: UUID
+    event: AlertEvent
+    rule: str | None = Field(default=None, description="The rule that raised it; null for a test.")
+    notifier: str
+    connection: str | None = None
+    subject: str
+    status: NotificationStatus
+    attempt: int
+    max_attempts: int
+    run_id: UUID | None = None
+    run_pipeline: str | None = None
+    run_started_at: datetime | None = None
+    available_at: datetime
+    sent_at: datetime | None = None
+    error: str | None = None
+    created_at: datetime
+
+
+class TestRequest(BaseModel):
+    """Which channel to send a test message through, and what to say."""
+
+    notifier: str
+    connection: str | None = None
+    subject: str = "dirigent test alert"
+    body: str = "This is a test message sent through the notifier surface."
+
+
+class TestQueued(WireModel):
+    """What a test message queued."""
+
+    notification_id: UUID
+    notifier: str
+    detail: str = "queued; a worker delivers it on its next pass"

dirigent_client/schemas/auth.py

@@ -0,0 +1,115 @@
+"""Who the caller is, the accounts an instance holds, and the tokens automation uses."""
+
+from datetime import datetime
+from uuid import UUID
+
+from pydantic import BaseModel, Field, SecretStr
+
+from dirigent_client.enums import TokenKind, UserRole
+from dirigent_client.schemas.common import WireModel
+from dirigent_common import Email, EntityName
+
+
+class LoginRequest(BaseModel):
+    """What a login presents."""
+
+    username: str = Field(min_length=1)
+    password: SecretStr
+
+
+class Identity(WireModel):
+    """Who the caller is."""
+
+    user_id: UUID
+    username: str
+    role: UserRole
+    via: TokenKind | None = None
+    token_name: str | None = None
+
+
+class TokenOut(WireModel):
+    """An API token as a listing shows it: everything except the secret."""
+
+    id: UUID
+    name: str
+    username: str
+    prefix: str
+    created_at: datetime
+    last_used_at: datetime | None = None
+    expires_at: datetime | None = None
+    revoked_at: datetime | None = None
+
+
+class TokenRequest(BaseModel):
+    """What creating an API token asks for."""
+
+    name: EntityName
+    """The token's name, which is how it is revoked and how it reads in an audit trail.
+
+    An entity name like every other named thing an instance holds: it appears in a REST
+    path (``DELETE /users/{username}/tokens/{name}`` and ``DELETE /tokens/{name}``), so a
+    name with a slash or a space in it is a token nobody can revoke."""
+
+
+class IssuedTokenOut(WireModel):
+    """A freshly minted token: the one and only time its secret is returned."""
+
+    id: UUID
+    name: str
+    username: str
+    prefix: str
+    token: str
+    """The secret. It is not stored and cannot be shown again."""
+
+
+class UserOut(WireModel):
+    """An account as a listing shows it; the password hash is never rendered."""
+
+    id: UUID
+    username: str
+    name: str | None = None
+    email: str | None = None
+    role: UserRole
+    active: bool
+    last_login_at: datetime | None = None
+    created_at: datetime
+
+
+class UserIn(BaseModel):
+    """What creating an account asks for."""
+
+    username: str = Field(min_length=1, max_length=200)
+    password: SecretStr
+    name: str | None = None
+    email: Email | None = None
+    role: UserRole
+
+
+class UserUpdate(BaseModel):
+    """What editing an account may change; the username and the password are not among them.
+
+    A field left out is left alone, and ``name`` or ``email`` sent as null is cleared. Those
+    are different requests, so they are told apart by what the body contained rather than by
+    the value landing as ``None`` either way. A role is never cleared, only replaced.
+    """
+
+    name: str | None = None
+    email: Email | None = None
+    role: UserRole | None = None
+
+    def changing(self, field: str) -> bool:
+        """Report whether the request said anything about this field at all."""
+        return field in self.model_fields_set
+
+
+class PasswordChangeRequest(BaseModel):
+    """What a person changing their own password presents."""
+
+    current_password: SecretStr
+    new_password: SecretStr
+
+
+class PasswordResetRequest(BaseModel):
+    """What an admin resetting another account's password presents."""
+
+    password: SecretStr

dirigent_client/schemas/catalog.py

@@ -0,0 +1,66 @@
+"""The block catalog: what an instance can run, and the schemas a form is built from."""
+
+import hashlib
+import json
+from enum import StrEnum
+
+from pydantic import BaseModel, Field
+
+from dirigent_common import API_VERSION, JsonMap
+
+
+class BlockKind(StrEnum):
+    """Which block surface a catalog entry describes."""
+
+    OPERATOR = "operator"
+    """Does work; may finish synchronously or return a remote handle."""
+
+    SENSOR = "sensor"
+    """Waits for the world through durable, scheduled pokes."""
+
+
+class BlockEntry(BaseModel):
+    """One block in the catalog, with the schemas a form is built from."""
+
+    id: str
+    kind: BlockKind
+    summary: str
+    group: str
+    plugin: str
+    idempotent: bool = False
+    local_execution: bool = False
+    default_poll_seconds: float | None = None
+    default_deadline_seconds: float | None = None
+    config_schema: JsonMap = Field(default_factory=dict)
+    output_schema: JsonMap = Field(default_factory=dict)
+
+
+class SurfaceEntry(BaseModel):
+    """One catalog entry for a non-block surface: a scheme, a notifier, a connection kind."""
+
+    id: str
+    plugin: str
+    config_schema: JsonMap = Field(default_factory=dict)
+    secret_fields: list[str] = Field(default_factory=list[str])
+    """Which config fields this surface declares secret, so a form draws them write-only."""
+
+
+class Catalog(BaseModel):
+    """The host's merged view of every contribution."""
+
+    api_version: int = API_VERSION
+    plugins: list[str] = Field(default_factory=list[str])
+    blocks: list[BlockEntry] = Field(default_factory=list[BlockEntry])
+    storage_schemes: list[SurfaceEntry] = Field(default_factory=list[SurfaceEntry])
+    notifiers: list[SurfaceEntry] = Field(default_factory=list[SurfaceEntry])
+    connection_kinds: list[SurfaceEntry] = Field(default_factory=list[SurfaceEntry])
+
+    def block(self, block_id: str) -> BlockEntry | None:
+        """Find one catalog entry by block id."""
+        return next((entry for entry in self.blocks if entry.id == block_id), None)
+
+    @property
+    def digest(self) -> str:
+        """Hash the catalog, so a worker registry row can prove code parity across nodes."""
+        payload = json.dumps(self.model_dump(mode="json"), sort_keys=True, separators=(",", ":")).encode()
+        return f"sha256:{hashlib.sha256(payload).hexdigest()}"

dirigent_client/schemas/common.py

@@ -0,0 +1,38 @@
+"""What every other wire model is built out of: the base itself, one refusal, and one page."""
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class WireModel(BaseModel):
+    """A frozen shape that crosses the wire."""
+
+    model_config = ConfigDict(frozen=True)
+
+
+class Problem(WireModel):
+    """One refusal, in the one shape every error response takes."""
+
+    status: int
+    """The HTTP status, repeated in the body so a logged payload is self-contained."""
+
+    title: str
+    """The short, stable name of the condition: the status phrase."""
+
+    detail: str
+    """One sentence a person can act on."""
+
+    problems: list[str] = Field(default_factory=list[str])
+    """The individual failures, when the refusal is a list of them rather than one."""
+
+    instance: str | None = None
+    """The path that was asked for, redacted of any credential it carried."""
+
+
+class Page[T](WireModel):
+    """One page of a listing, and the cursor that continues it."""
+
+    items: list[T]
+    """The rows of this page, in the listing's own order."""
+
+    next: str | None = None
+    """The opaque cursor a caller passes as ``after`` to continue, or nothing at the end."""

dirigent_client/schemas/connections.py

@@ -0,0 +1,56 @@
+"""Connections: coded credential records of a contributed kind, redacted in every response."""
+
+from datetime import datetime
+from uuid import UUID
+
+from pydantic import BaseModel, Field
+
+from dirigent_client.schemas.common import WireModel
+from dirigent_common import EntityName, JsonMap
+
+
+class ConnectionIn(BaseModel):
+    """What creating or replacing a connection sends; secret fields are write-only."""
+
+    code: EntityName
+    name: str | None = None
+    kind: str = Field(min_length=1, max_length=100)
+    description: str | None = None
+    config: JsonMap = Field(default_factory=dict)
+    """The kind's own config, validated against its published model before anything is stored."""
+
+
+class ConnectionUpdate(BaseModel):
+    """What editing a connection may change; the kind and code are fixed once minted.
+
+    A field left out is left alone, and a field sent as null is cleared. Those are different
+    requests, so they are told apart by what the body contained rather than by the value
+    landing as ``None`` either way.
+    """
+
+    name: str | None = None
+    description: str | None = None
+    config: JsonMap | None = None
+
+    def changing(self, field: str) -> bool:
+        """Report whether the request said anything about this field at all."""
+        return field in self.model_fields_set
+
+
+class ConnectionOut(WireModel):
+    """A connection as every response shows it: settings visible, secrets redacted."""
+
+    id: UUID
+    code: str
+    name: str | None = None
+    kind: str
+    description: str | None = None
+    config: JsonMap
+    secret_fields: list[str] = Field(default_factory=list[str])
+    """Which fields the kind declares secret, so a form knows what to render as a password."""
+
+    last_check_at: datetime | None = None
+    last_check_healthy: bool | None = None
+    last_check_detail: str | None = None
+    created_at: datetime
+    updated_at: datetime