dirigent-server 0.18.4__tar.gz → 0.19.0__tar.gz

{dirigent_server-0.18.4 → dirigent_server-0.19.0}/PKG-INFO

@@ -1,16 +1,16 @@
 Metadata-Version: 2.4
 Name: dirigent-server
-Version: 0.18.4
+Version: 0.19.0
 Summary: Dirigent FastAPI server: the REST API, its authentication, and the health probes.
 License-Expression: LicenseRef-Proprietary
 License-File: LICENSE
 License-File: THIRD_PARTY_NOTICES.md
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.13
-Requires-Dist: dirigent-client==0.18.4
-Requires-Dist: dirigent-common==0.18.4
-Requires-Dist: dirigent-core==0.18.4
-Requires-Dist: dirigent-examples==0.18.4
+Requires-Dist: dirigent-client==0.19.0
+Requires-Dist: dirigent-common==0.19.0
+Requires-Dist: dirigent-core==0.19.0
+Requires-Dist: dirigent-examples==0.19.0
 Requires-Dist: fastapi>=0.141.1
 Requires-Python: >=3.13
 Description-Content-Type: text/markdown

{dirigent_server-0.18.4 → dirigent_server-0.19.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "dirigent-server"
-version = "0.18.4"
+version = "0.19.0"
 description = "Dirigent FastAPI server: the REST API, its authentication, and the health probes."
 readme = "README.md"
 requires-python = ">=3.13"
@@ -14,10 +14,10 @@ classifiers = [
     "Programming Language :: Python :: 3.13",
 ]
 dependencies = [
-    "dirigent-client==0.18.4",
-    "dirigent-common==0.18.4",
-    "dirigent-core==0.18.4",
-    "dirigent-examples==0.18.4",
+    "dirigent-client==0.19.0",
+    "dirigent-common==0.19.0",
+    "dirigent-core==0.19.0",
+    "dirigent-examples==0.19.0",
     "fastapi>=0.141.1",
 ]
 

{dirigent_server-0.18.4 → dirigent_server-0.19.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "dirigent-server"
-version = "0.18.4"
+version = "0.19.0"
 description = "Dirigent FastAPI server: the REST API, its authentication, and the health probes."
 readme = "README.md"
 requires-python = ">=3.13"
@@ -11,10 +11,10 @@ classifiers = [
     "Programming Language :: Python :: 3.13",
 ]
 dependencies = [
-    "dirigent-client==0.18.4",
-    "dirigent-common==0.18.4",
-    "dirigent-core==0.18.4",
-    "dirigent-examples==0.18.4",
+    "dirigent-client==0.19.0",
+    "dirigent-common==0.19.0",
+    "dirigent-core==0.19.0",
+    "dirigent-examples==0.19.0",
     "fastapi>=0.141.1",
 ]
 

{dirigent_server-0.18.4 → dirigent_server-0.19.0}/src/dirigent_server/app.py

@@ -29,9 +29,14 @@ A generic pipeline orchestrator. Pipelines are data, composed from pluggable bui
 blocks and executed as a DAG on a durable engine.
 
 Every endpoint under `/api/v1` requires authentication: a bearer token for automation, or
-the session cookie `POST /api/v1/auth/login` sets for a browser. The probes under `/health`
-and this document itself are the only exceptions. `POST /hooks/{token}` is outside the
-versioned API and authenticates with its own per-trigger token.
+the session cookie `POST /api/v1/auth/login` sets for a browser. The probes under `/health`,
+this document itself, and the playground under `/api/v1/playground` are the exceptions.
+`POST /hooks/{token}` is outside the versioned API and authenticates with its own
+per-trigger token.
+
+The playground serves generated data and chosen behaviour to documents that need something
+to happen: it needs no credential, opens no database session, and reads no instance data.
+`DIRIGENT_PLAYGROUND_ENABLED=false` unmounts it.
 """
 
 _logger = get_logger("server")
@@ -99,7 +104,7 @@ def create_app(
     mount_ui_assets(app, resolved)
     app.include_router(health_router)
     app.include_router(build_hooks_router())
-    app.include_router(build_router(), prefix=resolved.api_prefix)
+    app.include_router(build_router(resolved), prefix=resolved.api_prefix)
     mount_ui_shell(app, resolved)
     instrument_fastapi(app)
     return app

{dirigent_server-0.18.4 → dirigent_server-0.19.0}/src/dirigent_server/messages.py

@@ -97,3 +97,23 @@ TOO_MANY_TAILS = SERVER.define("too_many_tails", "you already have {maximum} str
 NO_ICON = SERVER.define("no_icon", "this bundle carries no icon")
 
 BAD_CURSOR = SERVER.define("bad_cursor", "{name}={after} is not a cursor this listing gave out")
+
+PLAYGROUND_BAD_KNOB = SERVER.define("playground_bad_knob", "{detail}")
+
+PLAYGROUND_HEADER_REFUSED = SERVER.define(
+    "playground_header_refused",
+    "the playground will not set {header} on itself: a header that plants a cookie, opens "
+    "this origin to another site, or weakens what a browser enforces here teaches nothing",
+)
+
+PLAYGROUND_OFF_INSTANCE = SERVER.define(
+    "playground_off_instance",
+    "{to} is not a path on this instance, and the playground redirects nowhere else: an "
+    "open redirect is a phishing tool wearing this instance's own domain",
+)
+
+PLAYGROUND_UNAUTHENTICATED = SERVER.define(
+    "playground_unauthenticated",
+    "this route wants a credential: the basic pair {username}/{username}, or the documented "
+    "bearer token. Both are public constants and guard nothing",
+)

{dirigent_server-0.18.4 → dirigent_server-0.19.0}/src/dirigent_server/routes/__init__.py

@@ -7,6 +7,7 @@ rather than as a person, so it is mounted at the application root instead.
 
 from fastapi import APIRouter, Depends
 
+from dirigent_core.config import Settings
 from dirigent_server.routes import (
     alerts,
     auth,
@@ -15,6 +16,7 @@ from dirigent_server.routes import (
     examples,
     hooks,
     pipelines,
+    playground,
     runs,
     schema,
     schemas,
@@ -43,13 +45,23 @@ TAGS: list[dict[str, str]] = [
     {"name": "users", "description": "Local accounts."},
     {"name": "system", "description": "What this instance is, and whether it is well."},
     {"name": "health", "description": "Liveness and readiness."},
+    {
+        "name": "playground",
+        "description": "Generated data and chosen behaviour, for examples and tests. No credential.",
+    },
 ]
 
 
-def build_router() -> APIRouter:
-    """Assemble the versioned API: the login route, then everything behind authentication."""
+def build_router(settings: Settings | None = None) -> APIRouter:
+    """Assemble the versioned API: the open routes, then everything behind authentication.
+
+    The playground is mounted only when the instance serves it, so turning it off is not a
+    route that refuses but a route that is not there.
+    """
     router = APIRouter(route_class=Transactional)
     router.include_router(auth.public_router)
+    if settings is None or settings.playground_enabled:
+        router.include_router(playground.router)
     guarded = APIRouter(dependencies=[Depends(require_principal)], route_class=Transactional)
     for module in (
         auth,

dirigent_server-0.19.0/src/dirigent_server/routes/playground.py

@@ -0,0 +1,483 @@
+"""The playground: a request-and-response service the instance serves itself.
+
+Unauthenticated, because a pipeline step calling its own instance's playground must not need
+a token, and because there is nothing here to protect: no database session is opened, no
+instance data is read, and nothing is remembered between requests.
+
+Every route answers the same envelope. ``kind`` names the answer, ``request`` holds what
+arrived verbatim, and every other key is what the route decided -- the knobs resolved, after
+defaults and after a seed was drawn. So ``request.args.rows`` is the string that was sent
+and ``rows`` is the number that was used.
+"""
+
+import asyncio
+import base64
+import binascii
+import json
+import secrets
+from datetime import timedelta
+from typing import Annotated, Final
+from urllib.parse import unquote_plus, urlencode
+
+from fastapi import APIRouter, Query, Request, Response
+from fastapi import status as http_status
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel, JsonValue
+
+from dirigent_common import Duration
+from dirigent_server.errors import Refusal
+from dirigent_server.messages import (
+    PLAYGROUND_BAD_KNOB,
+    PLAYGROUND_HEADER_REFUSED,
+    PLAYGROUND_OFF_INSTANCE,
+    PLAYGROUND_UNAUTHENTICATED,
+)
+
+router = APIRouter(tags=["playground"])
+
+PREFIX: Final = "/playground"
+
+#: Reflected as this rather than repeated, so a page on this origin cannot read a session
+#: cookie back out of the playground that ``httponly`` exists to keep from it.
+REDACTED: Final = "<redacted>"
+
+#: Request headers whose value is never reflected, only their presence.
+SECRET_HEADERS: Final = frozenset({"authorization", "cookie", "proxy-authorization"})
+
+#: Statuses that carry no body, so the reflection has nowhere to go.
+BODYLESS: Final = frozenset({204, 304})
+
+#: The redirect statuses the playground will issue. A 304 is not a redirect and carries no
+#: body, and no other 3xx is one a client follows.
+REDIRECTS: Final = frozenset({301, 302, 303, 307, 308})
+
+#: The longest redirect chain one call may ask for.
+MAX_HOPS: Final = 10
+
+#: The longest a call may be asked to take before answering. The same ceiling the
+#: ``playground.generate`` node puts on its own ``delay``.
+MAX_DELAY: Final = timedelta(seconds=30)
+
+#: Response headers the playground will not set on itself, because each one would make this
+#: origin do something for a caller that is not teaching anything: plant a cookie, open the
+#: origin to another site, or weaken what a browser enforces here.
+FORBIDDEN_HEADERS: Final = frozenset(
+    {
+        "connection",
+        "content-length",
+        "content-security-policy",
+        "set-cookie",
+        "set-cookie2",
+        "strict-transport-security",
+        "transfer-encoding",
+        "upgrade",
+        "x-frame-options",
+    }
+)
+
+#: Query names the routes read as knobs, so ``response-headers`` never sets one as a header.
+RESERVED_ARGS: Final = frozenset({"delay", "status"})
+
+#: The credential ``/playground/auth`` accepts. Public constants, documented as such: they
+#: protect nothing and unlock nothing but this one route's 200.
+BASIC_USERNAME: Final = "playground"
+BASIC_PASSWORD: Final = "playground"
+BEARER_TOKEN: Final = "playground-token"
+
+
+class RequestFacts(BaseModel):
+    """What arrived, verbatim: the same shape on every playground answer."""
+
+    method: str
+    """The HTTP method the call was made with."""
+
+    url: str
+    """The whole URL as this instance saw it, query string included."""
+
+    path: str
+    """The path alone, without the query."""
+
+    args: dict[str, JsonValue]
+    """The query arguments as strings, with a repeated name arriving as a list."""
+
+    headers: dict[str, str]
+    """The request headers, lowercased. A credential's presence is shown, never its value."""
+
+    body: JsonValue = None
+    """The body, decoded the way ``body_kind`` says. Null when there was none."""
+
+    body_kind: str = "none"
+    """How the body was read: ``none``, ``json``, ``form`` or ``text``. A body appears once."""
+
+    body_bytes: int = 0
+    """How large the body was, in bytes."""
+
+    content_type: str | None = None
+    """The content type the body arrived under, as the header spelled it."""
+
+
+class Answer(BaseModel):
+    """The envelope every playground route answers with."""
+
+    kind: str
+    """What this answer is, which is what a reader dispatches on."""
+
+    request: RequestFacts
+    """What the call arrived as."""
+
+
+class Reflection(Answer):
+    """A call reflected back, with nothing added."""
+
+    status: int
+    """The status this answer was given."""
+
+
+class Redirect(Answer):
+    """One hop of a redirect chain."""
+
+    status: int
+    """The redirect status this hop answered with."""
+
+    location: str
+    """Where this hop points, which is the next hop or the destination."""
+
+    hops: int
+    """How many hops remain after this one."""
+
+
+class Unreliable(Answer):
+    """A call that fails while the attempt it names is inside the failing window."""
+
+    status: int
+    """The status this answer was given."""
+
+    attempt: int
+    """Which attempt the caller said this is."""
+
+    fail_until: int
+    """How many attempts fail before one succeeds."""
+
+    outcome: str
+    """``failed`` while the window lasts, then ``succeeded``."""
+
+
+class SetHeaders(Answer):
+    """The headers the playground set on the way back."""
+
+    status: int
+    """The status this answer was given."""
+
+    headers: dict[str, str]
+    """Every header this answer set, exactly as it was asked to."""
+
+
+class Credential(Answer):
+    """A call that presented a credential the playground accepts."""
+
+    status: int
+    """The status this answer was given."""
+
+    authenticated: bool
+    """Always true: a call that was not authenticated is refused rather than answered."""
+
+    scheme: str
+    """Which HTTP authentication scheme the accepted credential used."""
+
+
+def _args(request: Request) -> dict[str, JsonValue]:
+    """The query string as the playground reports it: one value a string, a repeated one a list."""
+    gathered: dict[str, list[str]] = {}
+    for name, value in request.query_params.multi_items():
+        gathered.setdefault(name, []).append(value)
+    return {name: values[0] if len(values) == 1 else list(values) for name, values in gathered.items()}
+
+
+def _headers(request: Request) -> dict[str, str]:
+    """The request headers, lowercased, with every credential's value replaced."""
+    return {
+        name.lower(): REDACTED if name.lower() in SECRET_HEADERS else value for name, value in request.headers.items()
+    }
+
+
+def _body(raw: bytes, content_type: str | None) -> tuple[JsonValue, str]:
+    """Decode a body once, and say how it was decoded."""
+    if not raw:
+        return None, "none"
+    media = (content_type or "").split(";")[0].strip().lower()
+    text = raw.decode("utf-8", errors="replace")
+    if media == "application/json":
+        try:
+            return json.loads(text), "json"
+        except json.JSONDecodeError:
+            return text, "text"
+    if media == "application/x-www-form-urlencoded":
+        gathered: dict[str, JsonValue] = {}
+        for pair in text.split("&"):
+            if not pair:
+                continue
+            name, _, value = pair.partition("=")
+            gathered[unquote_plus(name)] = unquote_plus(value)
+        return gathered, "form"
+    return text, "text"
+
+
+async def _facts(request: Request) -> RequestFacts:
+    """Gather what arrived, for the envelope every route shares."""
+    raw = await request.body()
+    content_type = request.headers.get("content-type")
+    body, body_kind = _body(raw, content_type)
+    return RequestFacts(
+        method=request.method,
+        url=str(request.url),
+        path=request.url.path,
+        args=_args(request),
+        headers=_headers(request),
+        body=body,
+        body_kind=body_kind,
+        body_bytes=len(raw),
+        content_type=content_type,
+    )
+
+
+def _answer(model: BaseModel, code: int, headers: dict[str, str] | None = None) -> Response:
+    """Send one answer, leaving out the body where the status cannot carry one."""
+    if code in BODYLESS or code < 200:
+        return Response(status_code=code, headers=headers)
+    return JSONResponse(model.model_dump(mode="json"), status_code=code, headers=headers)
+
+
+def _bad_knob(detail: str) -> Refusal:
+    """Refuse a knob the playground could not honour, naming what was wrong with it."""
+    return Refusal(PLAYGROUND_BAD_KNOB, status=http_status.HTTP_422_UNPROCESSABLE_CONTENT, detail=detail)
+
+
+async def _delayed(delay: timedelta) -> None:
+    """Take as long as the delay asks for, refusing one longer than the playground allows."""
+    if delay < timedelta(0) or delay > MAX_DELAY:
+        raise _bad_knob(f"a delay is between 0 and {int(MAX_DELAY.total_seconds())}s")
+    if delay > timedelta(0):
+        await asyncio.sleep(delay.total_seconds())
+
+
+StatusArg = Annotated[int, Query(ge=100, le=599, description="The status to answer with.")]
+DelayArg = Annotated[Duration, Query(description="How long to take before answering, as `250ms` or `2s`.")]
+
+
+@router.api_route(
+    f"{PREFIX}/request",
+    methods=["GET"],
+    operation_id="playgroundRequestGet",
+    summary="Reflect a GET back",
+    response_model=Reflection,
+)
+@router.api_route(
+    f"{PREFIX}/request",
+    methods=["POST"],
+    operation_id="playgroundRequestPost",
+    summary="Reflect a POST and its body back",
+    response_model=Reflection,
+)
+@router.api_route(
+    f"{PREFIX}/request",
+    methods=["PUT"],
+    operation_id="playgroundRequestPut",
+    summary="Reflect a PUT and its body back",
+    response_model=Reflection,
+)
+@router.api_route(
+    f"{PREFIX}/request",
+    methods=["PATCH"],
+    operation_id="playgroundRequestPatch",
+    summary="Reflect a PATCH and its body back",
+    response_model=Reflection,
+)
+@router.api_route(
+    f"{PREFIX}/request",
+    methods=["DELETE"],
+    operation_id="playgroundRequestDelete",
+    summary="Reflect a DELETE back",
+    response_model=Reflection,
+)
+async def reflect(request: Request, status: StatusArg = 200, delay: DelayArg = timedelta(0)) -> Response:
+    """Answer with what arrived, under the status that was asked for.
+
+    The degenerate route: every other one reflects too, and adds an answer of its own.
+    """
+    await _delayed(delay)
+    return _answer(Reflection(kind="request", request=await _facts(request), status=status), status)
+
+
+@router.get(
+    f"{PREFIX}/redirect",
+    operation_id="playgroundRedirect",
+    summary="Issue a redirect, or a chain of them",
+    response_model=Redirect,
+    status_code=http_status.HTTP_302_FOUND,
+    responses={422: {"description": "A status that is not a redirect, or a destination off this instance."}},
+)
+async def redirect(
+    request: Request,
+    hops: Annotated[int, Query(ge=1, le=MAX_HOPS, description="How many redirects to issue before arriving.")] = 1,
+    to: Annotated[
+        str | None,
+        Query(description="Where the last hop points, as a path on this instance. Defaults to the reflection route."),
+    ] = None,
+    status: Annotated[int, Query(description="The redirect status each hop answers with.")] = 302,
+    delay: DelayArg = timedelta(0),
+) -> Response:
+    """Point at the next hop, or at the destination when this is the last one.
+
+    The destination is a path on this instance and never an absolute URL: an open redirect
+    is a phishing tool wearing the instance's own domain, and there is nothing to teach
+    that needs one.
+    """
+    if status not in REDIRECTS:
+        raise _bad_knob(f"{status} is not a redirect status; use one of {sorted(REDIRECTS)}")
+    destination = _destination(request, to)
+    await _delayed(delay)
+    location = destination if hops <= 1 else _next_hop(request, hops - 1, to, status)
+    answer = Redirect(
+        kind="redirect",
+        request=await _facts(request),
+        status=status,
+        location=location,
+        hops=hops - 1,
+    )
+    return _answer(answer, status, headers={"location": location})
+
+
+def _destination(request: Request, to: str | None) -> str:
+    """Where the chain ends: a path on this instance, defaulting to the reflection route."""
+    if to is None:
+        return f"{request.url.path.removesuffix('/redirect')}/request"
+    if not to.startswith("/") or to.startswith("//"):
+        raise Refusal(
+            PLAYGROUND_OFF_INSTANCE,
+            status=http_status.HTTP_422_UNPROCESSABLE_CONTENT,
+            to=to,
+        )
+    return to
+
+
+def _next_hop(request: Request, hops: int, to: str | None, status: int) -> str:
+    """The same route again with one fewer hop, so a chain walks itself down to the destination."""
+    query = {"hops": str(hops), "status": str(status)}
+    if to is not None:
+        query["to"] = to
+    return f"{request.url.path}?{urlencode(query)}"
+
+
+@router.get(
+    f"{PREFIX}/unreliable",
+    operation_id="playgroundUnreliable",
+    summary="Fail until a given attempt, then succeed",
+    response_model=Unreliable,
+)
+async def unreliable(
+    request: Request,
+    attempt: Annotated[int, Query(ge=1, description="Which attempt the caller says this is.")] = 1,
+    fail_until: Annotated[int, Query(ge=0, description="How many attempts fail before one succeeds.")] = 1,
+    status: Annotated[int, Query(ge=100, le=599, description="The status answered while failing.")] = 503,
+    delay: DelayArg = timedelta(0),
+) -> Response:
+    """Answer the failing status while the attempt is inside the window, and 200 after it.
+
+    The window is driven by the attempt the caller names, because the playground remembers
+    nothing between requests and an answer that depended on what it remembered could not be
+    reproduced.
+    """
+    await _delayed(delay)
+    failing = attempt <= fail_until
+    code = status if failing else http_status.HTTP_200_OK
+    answer = Unreliable(
+        kind="unreliable",
+        request=await _facts(request),
+        status=code,
+        attempt=attempt,
+        fail_until=fail_until,
+        outcome="failed" if failing else "succeeded",
+    )
+    return _answer(answer, code)
+
+
+@router.get(
+    f"{PREFIX}/response-headers",
+    operation_id="playgroundResponseHeaders",
+    summary="Set the query's pairs as response headers",
+    response_model=SetHeaders,
+    responses={422: {"description": "A header this origin will not set on itself."}},
+)
+async def response_headers(request: Request, status: StatusArg = 200, delay: DelayArg = timedelta(0)) -> Response:
+    """Set each query argument as a response header, so a client's header handling has something to read."""
+    await _delayed(delay)
+    chosen: dict[str, str] = {}
+    for name, value in request.query_params.multi_items():
+        if name in RESERVED_ARGS:
+            continue
+        if name.lower() in FORBIDDEN_HEADERS:
+            raise Refusal(
+                PLAYGROUND_HEADER_REFUSED,
+                status=http_status.HTTP_422_UNPROCESSABLE_CONTENT,
+                header=name,
+            )
+        chosen[name] = value
+    answer = SetHeaders(kind="headers", request=await _facts(request), status=status, headers=chosen)
+    return _answer(answer, status, headers=chosen)
+
+
+@router.get(
+    f"{PREFIX}/auth",
+    operation_id="playgroundAuth",
+    summary="Require a credential the playground documents",
+    response_model=Credential,
+    responses={401: {"description": "No credential, or one the playground does not accept."}},
+)
+async def auth(request: Request, status: StatusArg = 200, delay: DelayArg = timedelta(0)) -> Response:
+    """Accept the documented basic pair or the documented bearer token, and refuse anything else.
+
+    The credential is a public constant. It guards nothing: it exists so a document can be
+    seen presenting one, and so the reflection can be seen redacting it.
+    """
+    await _delayed(delay)
+    scheme = _scheme(request.headers.get("authorization"))
+    if scheme is None:
+        raise Refusal(
+            PLAYGROUND_UNAUTHENTICATED,
+            status=http_status.HTTP_401_UNAUTHORIZED,
+            headers={"WWW-Authenticate": 'Basic realm="playground"'},
+            username=BASIC_USERNAME,
+        )
+    answer = Credential(
+        kind="auth",
+        request=await _facts(request),
+        status=status,
+        authenticated=True,
+        scheme=scheme,
+    )
+    return _answer(answer, status)
+
+
+def _scheme(header: str | None) -> str | None:
+    """Which scheme an acceptable credential used, or None when there was not one."""
+    if not header:
+        return None
+    kind, _, presented = header.partition(" ")
+    lowered = kind.lower()
+    if lowered == "bearer" and secrets.compare_digest(presented.strip(), BEARER_TOKEN):
+        return "bearer"
+    if lowered == "basic" and _basic(presented.strip()):
+        return "basic"
+    return None
+
+
+def _basic(presented: str) -> bool:
+    """Whether a base64 basic credential is the documented pair."""
+    try:
+        decoded = base64.b64decode(presented, validate=True).decode("utf-8")
+    except (binascii.Error, UnicodeDecodeError, ValueError):
+        return False
+    return secrets.compare_digest(decoded, f"{BASIC_USERNAME}:{BASIC_PASSWORD}")
+
+
+__all__ = ["PREFIX", "router"]