dirigent-client 0.9.0__py3-none-any.whl

dirigent_client/errors.py

@@ -0,0 +1,140 @@
+"""One exception class per condition a caller has to handle differently."""
+
+from typing import Any, Final, cast
+
+from dirigent_client.schemas import Problem
+
+#: The header a dirigent server puts on every response, including its errors.
+VERSION_HEADER: Final = "X-Dirigent-Version"
+
+
+class DirigentError(Exception):
+    """A call against a dirigent instance did not produce a result."""
+
+    def __init__(self, message: str, *, status: int = 0, url: str = "", problem: Problem | None = None) -> None:
+        """Carry the message, the status, the URL, and the problem the server sent."""
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.url = url
+        self.problem = problem
+
+    @property
+    def problems(self) -> list[str]:
+        """List the individual failures, when the refusal was a list of them rather than one."""
+        return list(self.problem.problems) if self.problem else []
+
+
+class TransportError(DirigentError):
+    """The server could not be reached, or the connection failed mid-request."""
+
+    def __init__(self, url: str, error: Exception) -> None:
+        """Name the URL that could not be reached."""
+        super().__init__(f"cannot reach {url}: {type(error).__name__}: {error}", url=url)
+        self.cause = error
+
+
+class NotDirigent(DirigentError):
+    """Something answered, but it was not a dirigent instance."""
+
+    def __init__(self, base_url: str, url: str, content_type: str) -> None:
+        """Say what answered and where."""
+        described = content_type.split(";")[0].strip() or "no content type"
+        super().__init__(
+            f"the server at {base_url} does not look like a dirigent instance (got {described} from {url})",
+            url=url,
+        )
+        self.base_url = base_url
+        self.content_type = content_type
+
+
+class Unauthorized(DirigentError):
+    """The request carried no credential, or one the instance does not accept."""
+
+
+class Forbidden(DirigentError):
+    """The credential is valid and does not permit this."""
+
+
+class NotFound(DirigentError):
+    """This instance holds no such thing."""
+
+
+class Conflict(DirigentError):
+    """The instance's current state does not allow this."""
+
+
+class ValidationFailed(DirigentError):
+    """The request was well formed and its content was refused, field by field."""
+
+
+class RateLimited(DirigentError):
+    """The instance is refusing this caller for now."""
+
+    def __init__(
+        self, message: str, *, status: int, url: str, problem: Problem | None, retry_after: float | None
+    ) -> None:
+        """Carry how long the server asked the caller to wait, when it said."""
+        super().__init__(message, status=status, url=url, problem=problem)
+        self.retry_after = retry_after
+
+
+class ServerError(DirigentError):
+    """The instance failed to handle the request; its own log has the detail."""
+
+
+class WaitTimeout(DirigentError):
+    """A run was still running when the caller's patience ran out; it was not cancelled."""
+
+
+_BY_STATUS: Final[dict[int, type[DirigentError]]] = {
+    401: Unauthorized,
+    403: Forbidden,
+    404: NotFound,
+    409: Conflict,
+    422: ValidationFailed,
+}
+
+
+def parse_problem(payload: object) -> Problem | None:
+    """Read an error body as the problem shape, or nothing when it is not one."""
+    if not isinstance(payload, dict):
+        return None
+    mapping = cast("dict[str, Any]", payload)
+    try:
+        return Problem.model_validate(mapping)
+    except ValueError:
+        return _loose(mapping)
+
+
+def _loose(mapping: "dict[str, Any]") -> Problem | None:
+    """Read a body that carries a detail but not the whole envelope, such as a bare 404."""
+    detail = mapping.get("detail")
+    if isinstance(detail, str):
+        return Problem(status=0, title="Error", detail=detail)
+    if isinstance(detail, list):
+        rendered = [_one(item) for item in cast("list[object]", detail)]
+        return Problem(status=0, title="Error", detail="; ".join(rendered), problems=rendered)
+    return None
+
+
+def _one(item: object) -> str:
+    """Render one entry of a problem list, whether it is a string or a pydantic error."""
+    if isinstance(item, str):
+        return item
+    if isinstance(item, dict):
+        mapping = cast("dict[str, Any]", item)
+        location = ".".join(str(part) for part in mapping.get("loc", []))
+        message = str(mapping.get("msg", mapping))
+        return f"{location}: {message}" if location else message
+    return str(item)
+
+
+def error_for(status: int, url: str, problem: Problem | None, *, retry_after: float | None = None) -> DirigentError:
+    """Build the exception a refusal deserves, from its status and whatever body it carried."""
+    detail = problem.detail if problem and problem.detail else f"HTTP {status}"
+    if status == 429:
+        return RateLimited(detail, status=status, url=url, problem=problem, retry_after=retry_after)
+    if status >= 500:
+        return ServerError(detail, status=status, url=url, problem=problem)
+    return _BY_STATUS.get(status, DirigentError)(detail, status=status, url=url, problem=problem)

dirigent_client/resources/__init__.py

@@ -0,0 +1 @@
+"""One accessor per API resource, each bound to the connection its calls go over."""

dirigent_client/resources/alerts.py

@@ -0,0 +1,97 @@
+"""Alert rules, and the notification queue they deliver through."""
+
+from datetime import timedelta
+from uuid import UUID
+
+from dirigent_client.enums import AlertEvent, AlertScope
+from dirigent_client.resources.base import Resource, query, request_body
+from dirigent_client.schemas import (
+    AlertRuleIn,
+    AlertRuleOut,
+    AlertRuleUpdate,
+    NotificationOut,
+    Page,
+    TestQueued,
+    TestRequest,
+)
+from dirigent_common import to_timedelta
+
+
+class Alerts(Resource):
+    """Declare and remove alert rules, send a test message, and read the queue."""
+
+    async def rules(self, *, after: str | None = None, limit: int | None = None) -> Page[AlertRuleOut]:
+        """List every alert rule, with the pipeline each one watches when it is scoped."""
+        return await self._many(AlertRuleOut, "GET", "/alert-rules", params=query(after=after, limit=limit))
+
+    async def create_rule(
+        self,
+        code: str,
+        *,
+        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 = None,
+        throttle: timedelta | str = timedelta(0),
+    ) -> AlertRuleOut:
+        """Declare an alert rule, refusing a notifier or a pipeline this instance does not have."""
+        payload = AlertRuleIn(
+            code=code,
+            name=name,
+            description=description,
+            event=event,
+            notifier=notifier,
+            scope=scope,
+            pipeline=pipeline,
+            connection=connection,
+            template=template,
+            throttle=to_timedelta(throttle),
+        )
+        return await self._one(AlertRuleOut, "POST", "/alert-rules", json=request_body(payload))
+
+    async def set_rule_paused(self, code: str, *, paused: bool) -> AlertRuleOut:
+        """Hold a rule's deliveries, or let them resume."""
+        payload = AlertRuleUpdate(paused=paused)
+        return await self._one(AlertRuleOut, "PATCH", f"/alert-rules/{code}", json=request_body(payload))
+
+    async def delete_rule(self, code: str) -> None:
+        """Remove an alert rule; the notifications it already raised are kept."""
+        await self._transport.request("DELETE", f"/alert-rules/{code}")
+
+    async def test(
+        self,
+        *,
+        notifier: str,
+        connection: str | None = None,
+        subject: str | None = None,
+        body: str | None = None,
+    ) -> TestQueued:
+        """Queue one message through a channel, on the same path a real alert takes."""
+        declared = TestRequest(notifier=notifier, connection=connection)
+        payload = declared.model_copy(
+            update=query(subject=subject, body=body),
+        )
+        return await self._one(TestQueued, "POST", "/alert-rules/$test", json=request_body(payload))
+
+    async def notification(self, notification_id: UUID | str) -> NotificationOut:
+        """Read one notification, which is how a caller watches a delivery it just queued."""
+        return await self._one(NotificationOut, "GET", f"/notifications/{notification_id}")
+
+    async def retry(self, notification_id: UUID | str) -> NotificationOut:
+        """Put one notification back on the queue, due now."""
+        return await self._one(NotificationOut, "POST", f"/notifications/{notification_id}/$retry")
+
+    async def notifications(
+        self, *, run_id: UUID | str | None = None, after: str | None = None, limit: int | None = None
+    ) -> Page[NotificationOut]:
+        """Read the alert queue newest first, which is where an undelivered alert is visible."""
+        return await self._many(
+            NotificationOut,
+            "GET",
+            "/notifications",
+            params=query(run_id=str(run_id) if run_id else None, after=after, limit=limit),
+        )

dirigent_client/resources/auth.py

@@ -0,0 +1,155 @@
+"""Logging in, logging out, asking who you are, and the accounts and tokens an admin manages."""
+
+from pydantic import SecretStr
+
+from dirigent_client.enums import UserRole
+from dirigent_client.resources.base import Resource, query, request_body
+from dirigent_client.schemas import (
+    Identity,
+    IssuedTokenOut,
+    LoginRequest,
+    Page,
+    PasswordChangeRequest,
+    PasswordResetRequest,
+    TokenOut,
+    TokenRequest,
+    UserIn,
+    UserOut,
+    UserUpdate,
+)
+from dirigent_client.transport import Transport
+
+
+class Auth(Resource):
+    """Exchange a password for a session, end one, and describe the caller."""
+
+    #: What the instance names the session cookie it sets.
+    SESSION_COOKIE = "dirigent_session"
+
+    async def login(self, username: str, password: str) -> Identity:
+        """Verify a username and password, and hold the session the instance answers with.
+
+        The session is presented as a bearer token from here on, so the rest of this
+        connection is authenticated whether or not a cookie could be sent back.
+        """
+        payload = LoginRequest(username=username, password=SecretStr(password))
+        identity = await self._one(Identity, "POST", "/auth/login", json=request_body(payload))
+        session = self._transport.session_cookie(self.SESSION_COOKIE)
+        if session is not None:
+            self._transport.present(session)
+        return identity
+
+    async def logout(self) -> None:
+        """Revoke the presented session."""
+        await self._transport.request("POST", "/auth/logout")
+
+    async def whoami(self) -> Identity:
+        """Report who this connection is acting as, and which credential said so."""
+        return await self._one(Identity, "GET", "/auth/me")
+
+    async def change_password(self, current: str, new: str) -> None:
+        """Replace this account's own password, ending every other session it holds."""
+        payload = PasswordChangeRequest(current_password=SecretStr(current), new_password=SecretStr(new))
+        await self._transport.request("POST", "/auth/password", json=request_body(payload))
+
+
+class Users(Resource):
+    """The local accounts an instance holds."""
+
+    async def list(self, *, after: str | None = None, limit: int | None = None) -> Page[UserOut]:
+        """List every account."""
+        return await self._many(UserOut, "GET", "/users", params=query(after=after, limit=limit))
+
+    async def create(
+        self,
+        username: str,
+        password: str,
+        *,
+        role: UserRole,
+        name: str | None = None,
+        email: str | None = None,
+    ) -> UserOut:
+        """Create an account with an Argon2id password hash."""
+        declared = UserIn(
+            username=username,
+            password=SecretStr(password),
+            role=role,
+            name=name,
+            email=email,
+        )
+        return await self._one(UserOut, "POST", "/users", json=request_body(declared))
+
+    async def update(
+        self,
+        username: str,
+        *,
+        name: str | None = None,
+        role: UserRole | None = None,
+        email: str | None = None,
+    ) -> UserOut:
+        """Change an account's display name, email or role, leaving out whatever was not named.
+
+        A field this call was not given is absent from the body, which is how the endpoint
+        tells "leave it alone" from "clear it".
+        """
+        named: dict[str, object] = {}
+        if name is not None:
+            named["name"] = name
+        if email is not None:
+            named["email"] = email
+        if role is not None:
+            named["role"] = role
+        body = UserUpdate.model_validate(named).model_dump(mode="json", exclude_unset=True)
+        return await self._one(UserOut, "PATCH", f"/users/{username}", json=body)
+
+    async def deactivate(self, username: str) -> UserOut:
+        """Bar an account from logging in and revoke the sessions it already holds."""
+        return await self._one(UserOut, "POST", f"/users/{username}/$deactivate")
+
+    async def activate(self, username: str) -> UserOut:
+        """Let an account log in again; the sessions it lost are not restored."""
+        return await self._one(UserOut, "POST", f"/users/{username}/$activate")
+
+    async def reset_password(self, username: str, password: str) -> None:
+        """Set an account's password without its old one, ending every session it holds."""
+        payload = PasswordResetRequest(password=SecretStr(password))
+        await self._transport.request("POST", f"/users/{username}/$reset-password", json=request_body(payload))
+
+    async def tokens(self, username: str, *, after: str | None = None, limit: int | None = None) -> Page[TokenOut]:
+        """List the API tokens one account holds, without their secrets."""
+        return await self._many(TokenOut, "GET", f"/users/{username}/tokens", params=query(after=after, limit=limit))
+
+    async def create_token(self, username: str, name: str) -> IssuedTokenOut:
+        """Mint a bearer token for another account; its secret is returned exactly once."""
+        payload = TokenRequest(name=name)
+        return await self._one(IssuedTokenOut, "POST", f"/users/{username}/tokens", json=request_body(payload))
+
+    async def revoke_token(self, username: str, name: str) -> None:
+        """Revoke that account's live tokens of the given name."""
+        await self._transport.request("DELETE", f"/users/{username}/tokens/{name}")
+
+
+class Tokens(Resource):
+    """The bearer tokens automation authenticates with."""
+
+    async def list(self, *, after: str | None = None, limit: int | None = None) -> Page[TokenOut]:
+        """List every account's API tokens, without their secrets; sessions are not listed."""
+        return await self._many(TokenOut, "GET", "/tokens", params=query(after=after, limit=limit))
+
+    async def create(self, name: str) -> IssuedTokenOut:
+        """Mint a bearer token for this account; its secret is returned exactly once."""
+        payload = TokenRequest(name=name)
+        return await self._one(IssuedTokenOut, "POST", "/tokens", json=request_body(payload))
+
+    async def revoke(self, name: str) -> None:
+        """Revoke this account's own live tokens of the given name."""
+        await self._transport.request("DELETE", f"/tokens/{name}")
+
+
+class Admin:
+    """The account and token surfaces, which only an admin principal may call."""
+
+    def __init__(self, transport: Transport) -> None:
+        """Bind both admin surfaces to the instance their calls go to."""
+        self.users = Users(transport)
+        self.tokens = Tokens(transport)

dirigent_client/resources/base.py

@@ -0,0 +1,52 @@
+"""What every namespaced accessor shares: the transport, and the parsing of a response."""
+
+from typing import Any
+
+from pydantic import BaseModel, SecretStr
+
+from dirigent_client.schemas import Page
+from dirigent_client.transport import Transport
+
+
+class Resource:
+    """One group of endpoints, bound to the connection they are called over."""
+
+    def __init__(self, transport: Transport) -> None:
+        """Bind the accessor to the instance its calls go to."""
+        self._transport = transport
+
+    async def _one[T: BaseModel](self, model: type[T], method: str, path: str, **kwargs: Any) -> T:
+        """Make one request and read its body as the schema the endpoint answers with."""
+        return model.model_validate(await self._transport.json(method, path, **kwargs))
+
+    async def _many[T: BaseModel](self, model: type[T], method: str, path: str, **kwargs: Any) -> Page[T]:
+        """Make one request and read its body as one page of the schema it answers with."""
+        payload: dict[str, Any] = await self._transport.json(method, path, **kwargs)
+        return Page(items=[model.model_validate(row) for row in payload["items"]], next=payload.get("next"))
+
+
+def query(**values: object) -> dict[str, Any]:
+    """Build a query string from the arguments a caller actually supplied."""
+    return {name: value for name, value in values.items() if value is not None}
+
+
+def request_body(schema: BaseModel) -> dict[str, Any]:
+    """Render a request schema as the JSON body it is sent as.
+
+    A field's wire spelling is its alias where it has one, which is how a body can carry a
+    key that is a Python keyword. A secret field serialises to its mask everywhere else; this
+    is the one place the value itself has to travel, so it is put back.
+    """
+    rendered = schema.model_dump(mode="json", by_alias=True)
+    for name, value in schema:
+        if isinstance(value, SecretStr):
+            rendered[_wire_name(schema, name)] = value.get_secret_value()
+    return rendered
+
+
+def _wire_name(schema: BaseModel, name: str) -> str:
+    """Name a field the way the body spells it."""
+    field = type(schema).model_fields.get(name)
+    if field is None:  # pragma: no cover - the name came from iterating the model itself
+        return name
+    return field.serialization_alias or field.alias or name

dirigent_client/resources/blocks.py

@@ -0,0 +1,16 @@
+"""The block catalog: what this instance can run, and the schemas a form is built from."""
+
+from dirigent_client.resources.base import Resource, query
+from dirigent_client.schemas import BlockEntry, BlockKind, Catalog
+
+
+class Blocks(Resource):
+    """Read the merged catalog every installed plugin contributes to."""
+
+    async def catalog(self, *, kind: BlockKind | None = None) -> Catalog:
+        """Read every contributed operator, sensor, storage scheme, notifier, and connection kind."""
+        return await self._one(Catalog, "GET", "/blocks", params=query(kind=kind.value if kind else None))
+
+    async def get(self, block_id: str) -> BlockEntry:
+        """Read one catalog entry, which is what a step's configuration form is built from."""
+        return await self._one(BlockEntry, "GET", f"/blocks/{block_id}")

dirigent_client/resources/connections.py

@@ -0,0 +1,50 @@
+"""Connections: coded credential records of a contributed kind, redacted in every response."""
+
+from dirigent_client.resources.base import Resource, query, request_body
+from dirigent_client.schemas import ConnectionIn, ConnectionOut, ConnectionUpdate, Page
+from dirigent_common import HealthReport, JsonMap
+
+
+class Connections(Resource):
+    """Create, read, edit, check, and remove the credential records an instance holds."""
+
+    async def list(self, *, after: str | None = None, limit: int | None = None) -> Page[ConnectionOut]:
+        """List every stored credential record, with its secrets redacted."""
+        return await self._many(ConnectionOut, "GET", "/connections", params=query(after=after, limit=limit))
+
+    async def get(self, code: str) -> ConnectionOut:
+        """Read one credential record, with its secrets redacted."""
+        return await self._one(ConnectionOut, "GET", f"/connections/{code}")
+
+    async def create(
+        self,
+        code: str,
+        *,
+        kind: str,
+        config: JsonMap | None = None,
+        name: str | None = None,
+        description: str | None = None,
+    ) -> ConnectionOut:
+        """Validate a credential against its kind, seal its secret half, and store it."""
+        payload = ConnectionIn(code=code, name=name, kind=kind, description=description, config=config or {})
+        return await self._one(ConnectionOut, "POST", "/connections", json=request_body(payload))
+
+    async def update(
+        self,
+        code: str,
+        *,
+        config: JsonMap | None = None,
+        name: str | None = None,
+        description: str | None = None,
+    ) -> ConnectionOut:
+        """Replace a connection's settings; the config is sent whole, not merged field by field."""
+        payload = ConnectionUpdate(name=name, description=description, config=config)
+        return await self._one(ConnectionOut, "PATCH", f"/connections/{code}", json=request_body(payload))
+
+    async def delete(self, code: str) -> None:
+        """Remove a credential record."""
+        await self._transport.request("DELETE", f"/connections/{code}")
+
+    async def check(self, code: str) -> HealthReport:
+        """Open the credential and ask its kind whether the external system answers."""
+        return await self._one(HealthReport, "POST", f"/connections/{code}/$check")