taskflow-meter 1.0.0__py3-none-any.whl

taskflow_meter/api/router.py

@@ -0,0 +1,113 @@
+#    Licensed under the Apache License, Version 2.0 (the "License"); you may
+#    not use this file except in compliance with the License. You may obtain
+#    a copy of the License at
+#
+#         http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+#    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+#    License for the specific language governing permissions and limitations
+#    under the License.
+
+"""A path-template router small enough to read in one sitting.
+
+Exists so the route table is data rather than decorators: the same table
+drives our own ASGI and WSGI callables and can be walked by an adapter
+that registers the routes in a host framework's router instead.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+from collections.abc import Iterable
+from dataclasses import dataclass
+from dataclasses import field
+from enum import Enum
+from typing import Any
+
+from taskflow_meter.api.http import MeterRequest
+
+#: A handler takes the request and returns a response, or a stream.
+Handler = Callable[[MeterRequest], Any]
+
+_PARAM = re.compile(r"\{([a-zA-Z_][a-zA-Z0-9_]*)\}")
+
+
+@dataclass(frozen=True, slots=True)
+class Route:
+    """One method and path template, bound to a handler."""
+
+    method: str
+    template: str
+    handler: Handler
+    name: str
+
+    def compile(self) -> re.Pattern[str]:
+        """Build the matcher for this template.
+
+        The literal spans are escaped and the parameters are not, which
+        is why this walks the template instead of substituting into an
+        already-escaped string -- ``re.escape`` escapes the braces too,
+        leaving nothing for a substitution to find.
+        """
+        parts: list[str] = []
+        cursor = 0
+        for found in _PARAM.finditer(self.template):
+            parts.append(re.escape(self.template[cursor : found.start()]))
+            parts.append(f"(?P<{found.group(1)}>[^/]+)")
+            cursor = found.end()
+        parts.append(re.escape(self.template[cursor:]))
+        return re.compile(f"^{''.join(parts)}$")
+
+
+class Outcome(Enum):
+    """Why a match did or did not happen."""
+
+    MATCHED = "matched"
+    NOT_FOUND = "not_found"
+    METHOD_NOT_ALLOWED = "method_not_allowed"
+
+
+@dataclass(frozen=True, slots=True)
+class Match:
+    outcome: Outcome
+    route: Route | None = None
+    params: dict[str, str] = field(default_factory=dict)
+    allowed: tuple[str, ...] = ()
+
+
+class Router:
+    """Matches a method and path against a fixed table of routes."""
+
+    def __init__(self, routes: Iterable[Route]) -> None:
+        self.routes = tuple(routes)
+        self._compiled = tuple(
+            (route, route.compile()) for route in self.routes
+        )
+        self._by_name = {route.name: route for route in self.routes}
+
+    def match(self, method: str, path: str) -> Match:
+        allowed: list[str] = []
+        for route, pattern in self._compiled:
+            found = pattern.match(path)
+            if found is None:
+                continue
+            if route.method == method:
+                return Match(
+                    Outcome.MATCHED, route=route, params=found.groupdict()
+                )
+            allowed.append(route.method)
+
+        if allowed:
+            # The path exists, the verb does not.  Saying so beats a 404
+            # that sends a client hunting for a typo in the URL.
+            return Match(
+                Outcome.METHOD_NOT_ALLOWED,
+                allowed=tuple(sorted(set(allowed))),
+            )
+        return Match(Outcome.NOT_FOUND)
+
+    def template_for(self, name: str) -> str:
+        return self._by_name[name].template

taskflow_meter/api/routes.py

@@ -0,0 +1,53 @@
+#    Licensed under the Apache License, Version 2.0 (the "License"); you may
+#    not use this file except in compliance with the License. You may obtain
+#    a copy of the License at
+#
+#         http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+#    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+#    License for the specific language governing permissions and limitations
+#    under the License.
+
+"""Path templates, in one place so links and routes cannot drift apart.
+
+The serialisers build links from the same constants the router matches
+on, so a renamed route cannot leave the payloads pointing somewhere that
+no longer exists.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import TYPE_CHECKING
+
+from taskflow_meter.api.router import Route
+
+if TYPE_CHECKING:
+    # Imported for typing only: service imports serializers, which
+    # imports these templates, so a real import would close the loop.
+    from taskflow_meter.api.service import MeterService
+
+HEALTH = "/healthz"
+FLOWS = "/api/v1/flows"
+FLOW = "/api/v1/flows/{run_id}"
+ATOMS = "/api/v1/flows/{run_id}/atoms"
+EVENTS = "/api/v1/flows/{run_id}/events"
+STREAM = "/api/v1/flows/{run_id}/stream"
+
+
+def build_routes(service: MeterService) -> tuple[Route, ...]:
+    """Bind the templates to a service's handlers."""
+    return (
+        Route("GET", HEALTH, service.health, name="health"),
+        Route("GET", FLOWS, service.list_flows, name="flows"),
+        Route("GET", FLOW, service.get_flow, name="flow"),
+        Route("GET", ATOMS, service.get_atoms, name="atoms"),
+        Route("GET", EVENTS, service.get_events, name="events"),
+        Route("GET", STREAM, service.stream, name="stream"),
+    )
+
+
+def templates() -> Iterable[str]:
+    return (HEALTH, FLOWS, FLOW, ATOMS, EVENTS, STREAM)

taskflow_meter/api/serializers.py

@@ -0,0 +1,137 @@
+#    Licensed under the Apache License, Version 2.0 (the "License"); you may
+#    not use this file except in compliance with the License. You may obtain
+#    a copy of the License at
+#
+#         http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+#    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+#    License for the specific language governing permissions and limitations
+#    under the License.
+
+"""Snapshots and events, rendered as JSON-ready dictionaries.
+
+Every payload carries the links that reach the rest of the API, built
+from the request's mount prefix rather than a hard-coded path, so the
+same handler is correct at ``/`` and at ``/deep/prefix``.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from taskflow_meter.api import routes
+from taskflow_meter.api.http import MeterRequest
+from taskflow_meter.datasource.base import EventPage
+from taskflow_meter.datasource.base import FlowPage
+from taskflow_meter.events import Event
+from taskflow_meter.models import AtomSnapshot
+from taskflow_meter.models import FlowSnapshot
+
+
+def atom(snapshot: AtomSnapshot) -> dict[str, Any]:
+    return {
+        "name": snapshot.name,
+        "uuid": snapshot.uuid,
+        "type": snapshot.atom_type,
+        "state": snapshot.state,
+        "intention": snapshot.intention,
+        "progress": snapshot.progress,
+        "progress_details": snapshot.progress_details,
+        "completion": snapshot.completion,
+        "finished": snapshot.is_finished,
+        "running": snapshot.is_running,
+        "has_result": snapshot.has_result,
+        "failure": snapshot.failure,
+        "revert_failure": snapshot.revert_failure,
+    }
+
+
+def flow(
+    snapshot: FlowSnapshot,
+    request: MeterRequest,
+    *,
+    with_atoms: bool = False,
+    with_events: bool = True,
+) -> dict[str, Any]:
+    """Render a flow.
+
+    ``with_events`` is false when the datasource keeps no history, so
+    the payload does not advertise a stream that would answer every
+    request with silence.
+    """
+    run_id = snapshot.run_id
+    links = {
+        "self": request.url(routes.FLOW.format(run_id=run_id)),
+        "atoms": request.url(routes.ATOMS.format(run_id=run_id)),
+    }
+    if with_events:
+        links["events"] = request.url(routes.EVENTS.format(run_id=run_id))
+        links["stream"] = request.url(routes.STREAM.format(run_id=run_id))
+
+    payload: dict[str, Any] = {
+        "run_id": run_id,
+        "name": snapshot.name,
+        "state": snapshot.state,
+        "book_id": snapshot.book_id,
+        "book_name": snapshot.book_name,
+        "observed_at": snapshot.observed_at,
+        "finished": snapshot.is_finished,
+        # An unweighted mean of the atoms: taskflow offers nothing to
+        # weight them by, so this indicates rather than estimates.
+        "completion": snapshot.completion,
+        "atom_count": len(snapshot.atoms),
+        # What it is doing right now: a list, because parallel flows run
+        # several at once and a flow between atoms is running none.
+        #
+        # Not named `atom`: this module has a function by that name, and
+        # under PEP 709 comprehension inlining (broken in CPython 3.12.0
+        # and 3.12.1) the loop target shadows it for the whole function.
+        "running_atoms": [running.name for running in snapshot.running_atoms],
+        "state_counts": snapshot.state_counts,
+        "meta": snapshot.meta,
+        "links": links,
+    }
+    if with_atoms:
+        payload["atoms"] = [
+            atom(snapshot.atoms[name]) for name in snapshot.atom_names
+        ]
+    return payload
+
+
+def flow_page(
+    page: FlowPage, request: MeterRequest, *, with_events: bool = True
+) -> dict[str, Any]:
+    links = {"self": request.url(routes.FLOWS)}
+    if page.next_marker is not None:
+        links["next"] = request.url(routes.FLOWS, marker=page.next_marker)
+    return {
+        "flows": [
+            flow(item, request, with_events=with_events) for item in page.items
+        ],
+        "next_marker": page.next_marker,
+        "links": links,
+    }
+
+
+def event(item: Event) -> dict[str, Any]:
+    return item.to_dict()
+
+
+def event_page(
+    page: EventPage, run_id: str, request: MeterRequest
+) -> dict[str, Any]:
+    template = routes.EVENTS.format(run_id=run_id)
+    return {
+        "events": [event(item) for item in page.events],
+        "next_seq": page.next_seq,
+        "oldest_seq": page.oldest_seq,
+        # True means the caller's next expected event was already
+        # evicted: there is a hole, and the snapshot must be re-read.
+        "truncated": page.truncated,
+        "links": {
+            "self": request.url(template),
+            "next": request.url(template, since_seq=page.next_seq),
+        },
+    }

taskflow_meter/api/service.py

@@ -0,0 +1,189 @@
+#    Licensed under the Apache License, Version 2.0 (the "License"); you may
+#    not use this file except in compliance with the License. You may obtain
+#    a copy of the License at
+#
+#         http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+#    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+#    License for the specific language governing permissions and limitations
+#    under the License.
+
+"""Every query the API can answer, with no HTTP machinery attached.
+
+This is the source of truth.  The ASGI and WSGI callables are adapters
+over it, and a host framework's own router can call the same handlers,
+so the three can never disagree about what an endpoint returns.
+"""
+
+from __future__ import annotations
+
+from taskflow_meter import __version__
+from taskflow_meter.api import serializers
+from taskflow_meter.api.http import BadRequestError
+from taskflow_meter.api.http import MeterRequest
+from taskflow_meter.api.http import MeterResponse
+from taskflow_meter.api.http import NotFoundError
+from taskflow_meter.api.http import UnsupportedError
+from taskflow_meter.api.sse import EventCursor
+from taskflow_meter.api.sse import StreamResponse
+from taskflow_meter.datasource.base import UnknownMarkerError
+from taskflow_meter.meter import Meter
+from taskflow_meter.models import FlowSnapshot
+
+#: Refuse to serve more than this in one page, however much is asked
+#: for: an unbounded limit is a full table scan someone can request.
+MAX_LIMIT = 500
+
+DEFAULT_FLOW_LIMIT = 50
+DEFAULT_EVENT_LIMIT = 200
+
+
+class MeterService:
+    """Answers requests from a :class:`~taskflow_meter.meter.Meter`."""
+
+    def __init__(self, meter: Meter, *, max_limit: int = MAX_LIMIT) -> None:
+        self.meter = meter
+        self.max_limit = max_limit
+
+    # -- endpoints -------------------------------------------------------
+
+    def health(
+        self,
+        request: MeterRequest,  # noqa: ARG002 - every handler takes one
+    ) -> MeterResponse:
+        poller = self.meter.poller
+        return MeterResponse.json(
+            {
+                "status": "ok",
+                "version": __version__,
+                "running": self.meter.running,
+                "supports_events": self.meter.supports_events,
+                "poller": None
+                if poller is None
+                else {
+                    "polls": poller.stats.polls,
+                    "events": poller.stats.events,
+                    "errors": poller.stats.errors,
+                    "flows_seen": poller.stats.flows_seen,
+                    "last_error": poller.stats.last_error,
+                },
+            }
+        )
+
+    def list_flows(self, request: MeterRequest) -> MeterResponse:
+        limit = self._limit(request, DEFAULT_FLOW_LIMIT)
+        try:
+            page = self.meter.list_flows(
+                state=request.get("state"),
+                book_id=request.get("book_id"),
+                limit=limit,
+                marker=request.get("marker"),
+            )
+        except UnknownMarkerError as exc:
+            # The run it named expired between pages.  A 400 tells the
+            # client to restart the walk; silently starting over would
+            # loop it through the first page forever.
+            raise BadRequestError(str(exc)) from exc
+
+        return MeterResponse.json(
+            serializers.flow_page(
+                page, request, with_events=self.meter.supports_events
+            )
+        )
+
+    def get_flow(self, request: MeterRequest) -> MeterResponse:
+        run_id = request.param("run_id")
+        snapshot = self._flow_or_404(run_id)
+        return MeterResponse.json(
+            serializers.flow(
+                snapshot,
+                request,
+                with_atoms=True,
+                with_events=self.meter.supports_events,
+            )
+        )
+
+    def get_atoms(self, request: MeterRequest) -> MeterResponse:
+        run_id = request.param("run_id")
+        atoms = self.meter.get_atoms(run_id)
+        if atoms is None:
+            raise NotFoundError(f"no flow with run id {run_id!r}")
+        return MeterResponse.json(
+            {
+                "atoms": [serializers.atom(item) for item in atoms],
+                "links": {"self": request.url(request.path)},
+            }
+        )
+
+    def get_events(self, request: MeterRequest) -> MeterResponse:
+        run_id = request.param("run_id")
+        self._require_events()
+        self._flow_or_404(run_id)
+        page = self.meter.events_since(
+            run_id,
+            since_seq=request.get_int("since_seq", 0),
+            limit=self._limit(request, DEFAULT_EVENT_LIMIT),
+        )
+        return MeterResponse.json(
+            serializers.event_page(page, run_id, request)
+        )
+
+    def stream(self, request: MeterRequest) -> StreamResponse:
+        run_id = request.param("run_id")
+        self._require_events()
+        self._flow_or_404(run_id)
+        return StreamResponse(
+            cursor=EventCursor(
+                reader=self.meter.reader,
+                run_id=run_id,
+                since_seq=self._resume_point(request),
+                batch_limit=self._limit(request, DEFAULT_EVENT_LIMIT),
+            )
+        )
+
+    # -- shared checks ---------------------------------------------------
+
+    def _flow_or_404(self, run_id: str) -> FlowSnapshot:
+        snapshot = self.meter.get_flow(run_id)
+        if snapshot is None:
+            raise NotFoundError(f"no flow with run id {run_id!r}")
+        return snapshot
+
+    def _require_events(self) -> None:
+        if not self.meter.supports_events:
+            msg = (
+                "this datasource keeps current state, not a history; "
+                "pair it with a poller feeding a writable datasource "
+                "to stream events"
+            )
+            raise UnsupportedError(msg)
+
+    def _limit(self, request: MeterRequest, default: int) -> int:
+        limit = request.get_int("limit", default)
+        if limit < 1:
+            msg = f"limit must be at least 1, got {limit}"
+            raise BadRequestError(msg)
+        return min(limit, self.max_limit)
+
+    def _resume_point(self, request: MeterRequest) -> int:
+        """Where to resume a stream from.
+
+        ``Last-Event-ID`` is what a browser's EventSource sends by itself
+        on reconnect, so honouring it is what makes a dropped connection
+        recoverable rather than a hole in the client's history.  An
+        explicit query parameter wins, for clients driving it by hand.
+        """
+        explicit = request.get("since_seq")
+        if explicit is not None:
+            return request.get_int("since_seq", 0)
+
+        header = request.headers.get("last-event-id")
+        if header is None:
+            return 0
+        try:
+            return int(header)
+        except ValueError:
+            msg = f"Last-Event-ID must be an integer, got {header!r}"
+            raise BadRequestError(msg) from None