taskflow-meter 1.0.0__py3-none-any.whl

taskflow_meter/__init__.py

@@ -0,0 +1,47 @@
+#    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.
+
+"""Monitoring interfaces for OpenStack TaskFlow flow execution progress.
+
+See ``docs/PLAN.md`` for the design this package is being built out against.
+"""
+
+from __future__ import annotations
+
+__all__ = ["__version__"]
+
+
+def _detect_version() -> str:
+    """Resolve the distribution version.
+
+    ``_version.py`` is generated at build time by hatch-vcs and is therefore
+    absent from a source checkout that has never been built.  Fall back to the
+    installed distribution metadata, then to a sentinel, so importing the
+    package never fails just because of version plumbing.
+    """
+    try:
+        from taskflow_meter._version import __version__ as version
+    except ImportError:
+        pass
+    else:
+        return str(version)
+
+    from importlib.metadata import PackageNotFoundError
+    from importlib.metadata import version as _version
+
+    try:
+        return _version("taskflow-meter")
+    except PackageNotFoundError:
+        return "0.0.0.dev0"
+
+
+__version__: str = _detect_version()

taskflow_meter/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '1.0.0'
+__version_tuple__ = version_tuple = (1, 0, 0)
+
+__commit_id__ = commit_id = None

taskflow_meter/api/__init__.py

@@ -0,0 +1,35 @@
+#    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.
+
+"""The HTTP API: a service, a route table, and adapters over both."""
+
+from __future__ import annotations
+
+from taskflow_meter.api.asgi import ASGIApp
+from taskflow_meter.api.http import ApiError
+from taskflow_meter.api.http import MeterRequest
+from taskflow_meter.api.http import MeterResponse
+from taskflow_meter.api.router import Route
+from taskflow_meter.api.router import Router
+from taskflow_meter.api.service import MeterService
+from taskflow_meter.api.wsgi import WSGIApp
+
+__all__ = [
+    "ASGIApp",
+    "ApiError",
+    "MeterRequest",
+    "MeterResponse",
+    "MeterService",
+    "Route",
+    "Router",
+    "WSGIApp",
+]

taskflow_meter/api/asgi.py

@@ -0,0 +1,236 @@
+#    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 plain ASGI 3 callable, mountable anywhere.
+
+Nothing here is Starlette-aware beyond one rule it also follows: the
+path to route on is ``scope["path"]`` with ``root_path`` removed *only
+when it is genuinely a prefix*.  That covers modern Starlette (which
+extends ``root_path`` and leaves ``path`` whole), older versions (which
+stripped ``path`` instead), and a server given ``--root-path`` where the
+prefix never appears in ``path`` at all.
+
+Startup is the other thing a mounted app has to get right.  **A mounted
+ASGI app never receives the lifespan scope** -- the host router handles
+it at the root and does not forward it -- so the meter is started
+lazily on the first request as well as from lifespan, and neither path
+minds the other having gone first.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import Awaitable
+from collections.abc import Callable
+from collections.abc import Iterable
+from typing import Any
+
+from taskflow_meter.api.dispatch import Dispatcher
+from taskflow_meter.api.http import MeterRequest
+from taskflow_meter.api.http import MeterResponse
+from taskflow_meter.api.http import split_path
+from taskflow_meter.api.service import MeterService
+from taskflow_meter.api.sse import StreamResponse
+from taskflow_meter.api.sse import aiter_frames
+from taskflow_meter.meter import Meter
+
+LOG = logging.getLogger(__name__)
+
+Scope = dict[str, Any]
+Receive = Callable[[], Awaitable[dict[str, Any]]]
+Send = Callable[[dict[str, Any]], Awaitable[None]]
+
+#: How often a live stream looks for new events.
+DEFAULT_STREAM_INTERVAL = 1.0
+
+#: How long a quiet stream waits before sending a keep-alive comment.
+DEFAULT_HEARTBEAT = 15.0
+
+#: Honoured when a reverse proxy strips a prefix the app never sees.
+PREFIX_HEADER = "x-forwarded-prefix"
+
+
+class ASGIApp:
+    """Serves the meter over ASGI, standalone or mounted."""
+
+    def __init__(
+        self,
+        meter: Meter,
+        *,
+        service: MeterService | None = None,
+        stream_interval: float = DEFAULT_STREAM_INTERVAL,
+        heartbeat: float = DEFAULT_HEARTBEAT,
+    ) -> None:
+        self.meter = meter
+        self.service = service or MeterService(meter)
+        self.dispatcher = Dispatcher(self.service)
+        self.stream_interval = stream_interval
+        self.heartbeat = heartbeat
+
+    async def __call__(
+        self, scope: Scope, receive: Receive, send: Send
+    ) -> None:
+        kind = scope["type"]
+        if kind == "lifespan":
+            await self._lifespan(receive, send)
+            return
+        if kind == "http":
+            await self._http(scope, receive, send)
+            return
+        if kind == "websocket":
+            # Declining cleanly beats leaving the handshake hanging.
+            await send({"type": "websocket.close", "code": 1000})
+            return
+        msg = f"unsupported ASGI scope: {kind!r}"
+        raise RuntimeError(msg)
+
+    # -- lifespan --------------------------------------------------------
+
+    async def _lifespan(self, receive: Receive, send: Send) -> None:
+        """Run the meter for as long as the server is up.
+
+        Only ever reached when this app is the root one; a mount never
+        sees these messages.
+        """
+        while True:
+            message = await receive()
+            if message["type"] == "lifespan.startup":
+                try:
+                    await asyncio.to_thread(self.meter.start)
+                except Exception as exc:
+                    LOG.exception("meter failed to start")
+                    await send(
+                        {
+                            "type": "lifespan.startup.failed",
+                            "message": repr(exc),
+                        }
+                    )
+                    return
+                await send({"type": "lifespan.startup.complete"})
+            elif message["type"] == "lifespan.shutdown":
+                try:
+                    await asyncio.to_thread(self.meter.stop)
+                except Exception as exc:  # pragma: no cover - defensive
+                    await send(
+                        {
+                            "type": "lifespan.shutdown.failed",
+                            "message": repr(exc),
+                        }
+                    )
+                    return
+                await send({"type": "lifespan.shutdown.complete"})
+                return
+
+    # -- requests --------------------------------------------------------
+
+    async def _http(self, scope: Scope, receive: Receive, send: Send) -> None:
+        # The lazy half of the lifecycle: a mounted app is never told
+        # when the server started, so the first request says so.
+        await asyncio.to_thread(self.meter.ensure_started)
+
+        request = build_request(scope)
+        result = await asyncio.to_thread(self.dispatcher.dispatch, request)
+
+        if isinstance(result, StreamResponse):
+            await self._stream(result, receive, send)
+            return
+        await send_response(send, result)
+
+    # -- streaming -------------------------------------------------------
+
+    async def _stream(
+        self, stream: StreamResponse, receive: Receive, send: Send
+    ) -> None:
+        await send(
+            {
+                "type": "http.response.start",
+                "status": stream.status,
+                "headers": encode_headers(stream.headers),
+            }
+        )
+        cursor = stream.cursor
+        disconnected = asyncio.Event()
+        watcher = asyncio.create_task(watch_disconnect(receive, disconnected))
+        try:
+            async for chunk in aiter_frames(
+                cursor,
+                interval=self.stream_interval,
+                heartbeat=self.heartbeat,
+                stop=disconnected,
+            ):
+                await send_chunk(send, chunk)
+        finally:
+            watcher.cancel()
+            if not disconnected.is_set():
+                # An empty final chunk is what tells the server the
+                # response is over; without it the client waits forever.
+                await send({"type": "http.response.body", "body": b""})
+
+
+async def watch_disconnect(
+    receive: Receive, disconnected: asyncio.Event
+) -> None:
+    """Set ``disconnected`` when the client goes away."""
+    try:
+        while True:
+            message = await receive()
+            if message["type"] == "http.disconnect":
+                disconnected.set()
+                return
+    except asyncio.CancelledError:  # pragma: no cover - shutdown path
+        raise
+
+
+async def send_chunk(send: Send, body: bytes) -> None:
+    await send({"type": "http.response.body", "body": body, "more_body": True})
+
+
+async def send_response(send: Send, response: MeterResponse) -> None:
+    await send(
+        {
+            "type": "http.response.start",
+            "status": response.status,
+            "headers": encode_headers(response.headers),
+        }
+    )
+    await send({"type": "http.response.body", "body": response.body})
+
+
+def encode_headers(
+    headers: tuple[tuple[str, str], ...],
+) -> list[tuple[bytes, bytes]]:
+    return [(key.encode(), value.encode()) for key, value in headers]
+
+
+def decode_headers(
+    raw: Iterable[tuple[bytes, bytes]] | None,
+) -> dict[str, str]:
+    return {
+        key.decode("latin-1").lower(): value.decode("latin-1")
+        for key, value in raw or ()
+    }
+
+
+def build_request(scope: Scope) -> MeterRequest:
+    """Turn an ASGI scope into a framework-neutral request."""
+    root_path = scope.get("root_path", "")
+    path = scope.get("path", "/")
+    headers = decode_headers(scope.get("headers"))
+    query_string = scope.get("query_string", b"").decode("latin-1")
+    return MeterRequest.from_query_string(
+        query_string,
+        method=scope.get("method", "GET"),
+        path=split_path(path, root_path),
+        prefix=headers.get(PREFIX_HEADER, "") + root_path,
+        headers=headers,
+    )

taskflow_meter/api/dispatch.py

@@ -0,0 +1,128 @@
+#    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.
+
+"""Routing and error rendering, shared by every adapter.
+
+Whatever carries the bytes -- ASGI, WSGI, or a host framework's own
+router -- the decision of which handler runs, what a wrong verb gets
+back, and how an error is rendered belongs here.  Two adapters that each
+made those decisions themselves would drift apart, and the difference
+would only show up in whichever one had fewer tests.
+"""
+
+from __future__ import annotations
+
+from dataclasses import replace
+
+from taskflow_meter.api import routes as route_table
+from taskflow_meter.api.http import ApiError
+from taskflow_meter.api.http import MeterRequest
+from taskflow_meter.api.http import MeterResponse
+from taskflow_meter.api.http import MethodNotAllowedError
+from taskflow_meter.api.http import NotFoundError
+from taskflow_meter.api.router import Outcome
+from taskflow_meter.api.router import Route
+from taskflow_meter.api.router import Router
+from taskflow_meter.api.service import MeterService
+from taskflow_meter.api.sse import StreamResponse
+
+Result = MeterResponse | StreamResponse
+
+
+class Dispatcher:
+    """Turns a request into a response, or an error into one."""
+
+    def __init__(
+        self, service: MeterService, *, router: Router | None = None
+    ) -> None:
+        self.service = service
+        self.router = router or Router(route_table.build_routes(service))
+
+    def dispatch(self, request: MeterRequest) -> Result:
+        """Route and run, rendering our own errors as JSON.
+
+        Only :class:`ApiError` is caught.  Anything else is a bug, and
+        belongs to whoever is hosting us -- swallowing it here would
+        turn our crash into a puzzling 500 with no traceback.
+        """
+        try:
+            return self._dispatch(request)
+        except ApiError as error:
+            return MeterResponse.from_error(error)
+
+    def run(self, route: Route, request: MeterRequest) -> Result:
+        """Invoke a handler the *host* has already matched.
+
+        The contrib adapters register our routes in the host's router,
+        so the host does the matching -- but a 404 for an unknown flow
+        is still ours to shape.  Without this each adapter would
+        re-implement the error rendering, and each would get it subtly
+        different.
+        """
+        try:
+            return self._invoke(route, request)
+        except ApiError as error:
+            return MeterResponse.from_error(error)
+
+    def _invoke(self, route: Route, request: MeterRequest) -> Result:
+        result: Result = route.handler(request)
+        if request.method == "HEAD" and isinstance(result, MeterResponse):
+            # Same headers, including content-length: a HEAD that
+            # reported zero would misdescribe the GET.
+            return replace(result, body=b"")
+        return result
+
+    def _dispatch(self, request: MeterRequest) -> Result:
+        if request.method == "OPTIONS":
+            return self._options(request)
+
+        # HEAD is a GET whose body is thrown away, which is what makes a
+        # health check with curl -I report the truth.
+        wanted = "GET" if request.method == "HEAD" else request.method
+        match = self.router.match(wanted, request.path)
+
+        if match.outcome is Outcome.MATCHED:
+            assert match.route is not None
+            return self._invoke(
+                match.route, replace(request, path_params=match.params)
+            )
+
+        if match.outcome is Outcome.METHOD_NOT_ALLOWED:
+            raise MethodNotAllowedError(
+                f"{request.method} is not allowed here",
+                headers=(("allow", self._allow(match.allowed)),),
+            )
+
+        # Unknown paths under our prefix are ours to answer.  Raising
+        # into the host application would turn a wrong URL into someone
+        # else's 500.
+        raise NotFoundError(f"no such endpoint: {request.path}")
+
+    def _options(self, request: MeterRequest) -> MeterResponse:
+        allowed: list[str] = []
+        for route in self.router.routes:
+            if self.router.match(route.method, request.path).outcome is (
+                Outcome.MATCHED
+            ):
+                allowed.append(route.method)
+        if not allowed:
+            raise NotFoundError(f"no such endpoint: {request.path}")
+        return MeterResponse(
+            status=204,
+            headers=(("allow", self._allow(tuple(allowed))),),
+        )
+
+    @staticmethod
+    def _allow(methods: tuple[str, ...]) -> str:
+        # HEAD and OPTIONS are handled here rather than by a route, so
+        # they would otherwise be missing from what we advertise.
+        return ", ".join(sorted({*methods, "HEAD", "OPTIONS"}))

taskflow_meter/api/http.py

@@ -0,0 +1,210 @@
+#    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.
+
+"""Requests and responses, with no web framework in sight.
+
+Handlers take a :class:`MeterRequest` and return a :class:`MeterResponse`,
+so the same handler serves an ASGI mount, a WSGI mount, or a host
+framework's own router.  Neither adapter is the source of truth.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from dataclasses import dataclass
+from dataclasses import field
+from typing import Any
+from urllib.parse import parse_qs
+from urllib.parse import urlencode
+
+JSON_CONTENT_TYPE = "application/json"
+
+
+class ApiError(Exception):
+    """An error with an HTTP shape.
+
+    Raised by handlers and rendered by the adapters.  Deliberately not a
+    global exception handler: we catch our own and let anything else
+    reach the host application, which knows what to do with it.
+    """
+
+    status = 500
+    title = "Internal Server Error"
+
+    def __init__(
+        self,
+        detail: str,
+        *,
+        headers: tuple[tuple[str, str], ...] = (),
+    ) -> None:
+        super().__init__(detail)
+        self.detail = detail
+        self.headers = headers
+
+
+class BadRequestError(ApiError):
+    status = 400
+    title = "Bad Request"
+
+
+class NotFoundError(ApiError):
+    status = 404
+    title = "Not Found"
+
+
+class MethodNotAllowedError(ApiError):
+    status = 405
+    title = "Method Not Allowed"
+
+
+class UnsupportedError(ApiError):
+    """The datasource in use cannot answer this at all."""
+
+    status = 501
+    title = "Not Implemented"
+
+
+def split_path(path: str, root_path: str) -> str:
+    """Return the path to route on, given a mount prefix.
+
+    Mirrors what Starlette's own ``get_route_path`` does, and for the
+    same reason: since 0.33 ``Mount`` extends ``root_path`` and leaves
+    ``scope["path"]`` whole, while older versions stripped ``path``
+    instead, and a server given ``--root-path`` may report a prefix that
+    never appears in ``path`` at all.  Stripping only when the prefix is
+    genuinely there covers all three.
+    """
+    if not root_path or not path.startswith(root_path):
+        return path
+    return path[len(root_path) :] or "/"
+
+
+def mount_prefix(full_path: str, sub_path: str) -> str:
+    """Return the part of ``full_path`` that precedes ``sub_path``.
+
+    How an adapter recovers where it was mounted when the host routed by
+    consuming path segments rather than by rewriting the path: the
+    difference between the two is the prefix.  Every generated link is
+    built from it, so guessing would produce links to nowhere -- hence
+    the empty string when the two do not line up.
+    """
+    if sub_path in ("", "/"):
+        return full_path.rstrip("/")
+    if not full_path.endswith(sub_path):
+        return ""
+    return full_path[: -len(sub_path)]
+
+
+@dataclass(frozen=True, slots=True)
+class MeterRequest:
+    """One inbound request, reduced to what a handler needs."""
+
+    method: str = "GET"
+    path: str = "/"
+    #: Where this app is mounted.  Every generated link starts here.
+    prefix: str = ""
+    query: dict[str, list[str]] = field(default_factory=dict)
+    headers: dict[str, str] = field(default_factory=dict)
+    path_params: dict[str, str] = field(default_factory=dict)
+
+    @classmethod
+    def from_query_string(
+        cls, query_string: str, **kwargs: Any
+    ) -> MeterRequest:
+        return cls(
+            query=parse_qs(query_string, keep_blank_values=True), **kwargs
+        )
+
+    def param(self, name: str) -> str:
+        try:
+            return self.path_params[name]
+        except KeyError:  # pragma: no cover - a routing bug, not input
+            msg = f"no such path parameter: {name}"
+            raise LookupError(msg) from None
+
+    def get(self, name: str, default: str | None = None) -> str | None:
+        values = self.query.get(name)
+        return values[0] if values else default
+
+    def get_int(self, name: str, default: int) -> int:
+        raw = self.get(name)
+        if raw is None or raw == "":
+            return default
+        try:
+            return int(raw)
+        except ValueError:
+            msg = f"{name} must be an integer, got {raw!r}"
+            raise BadRequestError(msg) from None
+
+    def url(self, path: str, **query: Any) -> str:
+        """Build a link back into this app, under its mount prefix."""
+        full = f"{self.prefix}{path}"
+        pairs = [(k, v) for k, v in query.items() if v is not None]
+        return f"{full}?{urlencode(pairs)}" if pairs else full
+
+
+@dataclass(frozen=True, slots=True)
+class MeterResponse:
+    """A complete, already-rendered response."""
+
+    status: int = 200
+    body: bytes = b""
+    headers: tuple[tuple[str, str], ...] = ()
+
+    @classmethod
+    def json(
+        cls,
+        payload: Any,
+        *,
+        status: int = 200,
+        headers: tuple[tuple[str, str], ...] = (),
+    ) -> MeterResponse:
+        # Separators are pinned so two adapters serving the same handler
+        # produce byte-identical output, which is what the conformance
+        # suite compares.
+        body = json.dumps(payload, separators=(",", ":")).encode()
+        return cls(
+            status=status,
+            body=body,
+            headers=(
+                ("content-type", JSON_CONTENT_TYPE),
+                ("content-length", str(len(body))),
+                *headers,
+            ),
+        )
+
+    @classmethod
+    def from_error(cls, error: ApiError) -> MeterResponse:
+        return cls.json(
+            {
+                "error": {
+                    "status": error.status,
+                    "title": error.title,
+                    "detail": error.detail,
+                }
+            },
+            status=error.status,
+            headers=error.headers,
+        )
+
+    def header(self, name: str) -> str | None:
+        wanted = name.lower()
+        for key, value in self.headers:
+            if key.lower() == wanted:
+                return value
+        return None
+
+
+def normalise_headers(raw: Mapping[str, str]) -> dict[str, str]:
+    """Lowercase header names, so lookups do not depend on the server."""
+    return {key.lower(): value for key, value in raw.items()}