taskflow-meter 1.0.0__py3-none-any.whl

taskflow_meter/api/sse.py

@@ -0,0 +1,222 @@
+#    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.
+
+"""Server-sent events: framing, and the cursor that drives a stream.
+
+The framing is shared by both adapters.  The cursor is deliberately
+synchronous and pull-based -- it answers "what is new since the last
+call?" -- so the ASGI adapter can drive it from an event loop and the
+WSGI one from a thread without either owning the logic.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import time
+from collections.abc import AsyncIterator
+from collections.abc import Iterator
+from dataclasses import dataclass
+from dataclasses import field
+
+from taskflow_meter.api import serializers
+from taskflow_meter.datasource.base import DataSource
+from taskflow_meter.events import Event
+
+#: Note the absence of ``connection: keep-alive``.  It is a hop-by-hop
+#: header, which PEP 3333 forbids an application from emitting -- and
+#: wsgiref rightly refuses to send.  Connection persistence is the
+#: server's business, not ours.
+SSE_HEADERS: tuple[tuple[str, str], ...] = (
+    ("content-type", "text/event-stream; charset=utf-8"),
+    ("cache-control", "no-cache"),
+    # nginx buffers proxied responses by default, which turns a live
+    # stream into one long silence followed by everything at once.
+    ("x-accel-buffering", "no"),
+)
+
+#: Sent once, telling a browser how long to wait before reconnecting.
+DEFAULT_RETRY_MS = 3000
+
+
+def frame(
+    data: str,
+    *,
+    event: str | None = None,
+    event_id: int | str | None = None,
+    retry: int | None = None,
+) -> bytes:
+    """Render one SSE frame.
+
+    Multi-line data is split across ``data:`` lines, as the protocol
+    requires -- a raw newline would end the frame early and truncate
+    whatever followed it.
+    """
+    lines: list[str] = []
+    if event is not None:
+        lines.append(f"event: {event}")
+    if event_id is not None:
+        lines.append(f"id: {event_id}")
+    if retry is not None:
+        lines.append(f"retry: {retry}")
+    lines.extend(f"data: {line}" for line in data.split("\n"))
+    return ("\n".join(lines) + "\n\n").encode()
+
+
+def comment(text: str = "") -> bytes:
+    """A frame clients ignore, used to keep the connection alive."""
+    return f": {text}\n\n".encode()
+
+
+@dataclass(slots=True)
+class EventCursor:
+    """Tracks one client's position in one run's event stream."""
+
+    reader: DataSource
+    run_id: str
+    since_seq: int = 0
+    batch_limit: int = 200
+    #: Set once the flow has finished and its events have been drained.
+    complete: bool = field(default=False, init=False)
+
+    def opening(self) -> bytes:
+        """The first bytes on the wire.
+
+        A retry hint plus a comment, so proxies that wait for output
+        before forwarding headers let the response through immediately.
+        """
+        return frame("", retry=DEFAULT_RETRY_MS) + comment("stream open")
+
+    def poll(self) -> list[bytes]:
+        """Return frames for everything new since the last call."""
+        page = self.reader.events_since(
+            self.run_id, since_seq=self.since_seq, limit=self.batch_limit
+        )
+        frames: list[bytes] = []
+
+        if page.truncated:
+            # The client's next event was evicted before it got here.
+            # Telling it beats letting it stitch a gap into a history it
+            # believes is continuous.
+            frames.append(
+                frame(
+                    json.dumps(
+                        {
+                            "reason": "events_evicted",
+                            "resume_from": page.oldest_seq,
+                        },
+                        separators=(",", ":"),
+                    ),
+                    event="gap",
+                )
+            )
+
+        for item in page.events:
+            frames.append(self._event_frame(item))
+        self.since_seq = page.next_seq
+
+        if not page.events and self._flow_finished():
+            frames.append(frame("{}", event="end"))
+            self.complete = True
+        return frames
+
+    def heartbeat(self) -> bytes:
+        return comment("keep-alive")
+
+    def _event_frame(self, item: Event) -> bytes:
+        return frame(
+            json.dumps(serializers.event(item), separators=(",", ":")),
+            event=str(item.kind),
+            event_id=item.seq,
+        )
+
+    def _flow_finished(self) -> bool:
+        snapshot = self.reader.get_flow(self.run_id)
+        return snapshot is not None and snapshot.is_finished
+
+
+@dataclass(frozen=True, slots=True)
+class StreamResponse:
+    """A response an adapter drives, rather than one it just writes.
+
+    Carries the headers and the cursor; how the polling loop is run is
+    the adapter's business, because an event loop and a worker thread
+    want to do it differently.
+    """
+
+    cursor: EventCursor
+    status: int = 200
+    headers: tuple[tuple[str, str], ...] = SSE_HEADERS
+
+
+def iter_frames(
+    cursor: EventCursor,
+    *,
+    interval: float,
+    heartbeat: float,
+) -> Iterator[bytes]:
+    """Drive a cursor synchronously, for WSGI and its descendants.
+
+    A generator, so the server closing the iterable lands a
+    ``GeneratorExit`` here and the loop stops rather than polling a
+    datasource nobody is listening to.
+    """
+    quiet = 0.0
+    yield cursor.opening()
+    while True:
+        frames = cursor.poll()
+        yield from frames
+        if cursor.complete:
+            return
+        quiet = 0.0 if frames else quiet + interval
+        if quiet >= heartbeat:
+            yield cursor.heartbeat()
+            quiet = 0.0
+        time.sleep(interval)
+
+
+async def aiter_frames(
+    cursor: EventCursor,
+    *,
+    interval: float,
+    heartbeat: float,
+    stop: asyncio.Event | None = None,
+) -> AsyncIterator[bytes]:
+    """Drive a cursor from an event loop, for ASGI and its descendants.
+
+    The polling itself is handed to a thread: a datasource read is
+    blocking, and doing it inline would stall every other request the
+    loop is serving.
+    """
+    quiet = 0.0
+    yield cursor.opening()
+    while stop is None or not stop.is_set():
+        frames = await asyncio.to_thread(cursor.poll)
+        for chunk in frames:
+            if stop is not None and stop.is_set():
+                return
+            yield chunk
+        if cursor.complete:
+            return
+
+        quiet = 0.0 if frames else quiet + interval
+        if quiet >= heartbeat:
+            yield cursor.heartbeat()
+            quiet = 0.0
+
+        if stop is None:
+            await asyncio.sleep(interval)
+        else:
+            # Sleep, but wake immediately if the client leaves.
+            with contextlib.suppress(TimeoutError):
+                await asyncio.wait_for(stop.wait(), interval)

taskflow_meter/api/wsgi.py

@@ -0,0 +1,145 @@
+#    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 WSGI callable, mountable anywhere.
+
+The same service and dispatcher the ASGI app uses, so the two cannot
+answer the same request differently -- a parity suite compares them byte
+for byte.
+
+Mount handling is simpler here than under ASGI: WSGI has always split
+``SCRIPT_NAME`` from ``PATH_INFO``, so there is one convention rather
+than three.  Streaming is the harder half.  A synchronous worker holds
+one thread for as long as an SSE response stays open, so a deployment
+serving streams from this callable wants gevent or eventlet workers --
+or should let clients poll ``/events?since_seq=`` instead, which costs
+nothing while idle.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+from collections.abc import Iterable
+from collections.abc import Iterator
+from http import HTTPStatus
+from typing import Any
+
+from taskflow_meter.api.dispatch import Dispatcher
+from taskflow_meter.api.http import MeterRequest
+from taskflow_meter.api.service import MeterService
+from taskflow_meter.api.sse import StreamResponse
+from taskflow_meter.api.sse import iter_frames
+from taskflow_meter.meter import Meter
+
+LOG = logging.getLogger(__name__)
+
+Environ = dict[str, Any]
+StartResponse = Callable[[str, list[tuple[str, str]]], Any]
+
+DEFAULT_STREAM_INTERVAL = 1.0
+DEFAULT_HEARTBEAT = 15.0
+
+#: Honoured when a reverse proxy strips a prefix the app never sees.
+PREFIX_HEADER = "HTTP_X_FORWARDED_PREFIX"
+
+
+class WSGIApp:
+    """Serves the meter over WSGI, 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
+
+    def __call__(
+        self, environ: Environ, start_response: StartResponse
+    ) -> Iterable[bytes]:
+        # WSGI has no lifespan at all, so the first request is the only
+        # place to notice that nobody started the meter.
+        self.meter.ensure_started()
+
+        result = self.dispatcher.dispatch(build_request(environ))
+        if isinstance(result, StreamResponse):
+            return self._stream(result, start_response)
+
+        start_response(status_line(result.status), list(result.headers))
+        return [result.body]
+
+    def _stream(
+        self, stream: StreamResponse, start_response: StartResponse
+    ) -> Iterator[bytes]:
+        start_response(status_line(stream.status), list(stream.headers))
+        return self._frames(stream)
+
+    def _frames(self, stream: StreamResponse) -> Iterator[bytes]:
+        """Yield frames until the flow ends or the client goes away."""
+        try:
+            yield from iter_frames(
+                stream.cursor,
+                interval=self.stream_interval,
+                heartbeat=self.heartbeat,
+            )
+        except GeneratorExit:
+            LOG.debug(
+                "client closed the stream for run %s", stream.cursor.run_id
+            )
+            raise
+
+
+def status_line(status: int) -> str:
+    """Render ``200`` as ``"200 OK"``, which is what WSGI expects."""
+    try:
+        return f"{status} {HTTPStatus(status).phrase}"
+    except ValueError:  # pragma: no cover - defensive
+        return f"{status} Unknown"
+
+
+def build_request(environ: Environ) -> MeterRequest:
+    """Turn a WSGI environ into a framework-neutral request."""
+    # The server split these for us; PATH_INFO is empty when the request
+    # lands exactly on the mount point.
+    script_name = environ.get("SCRIPT_NAME", "")
+    path = environ.get("PATH_INFO", "") or "/"
+    return MeterRequest.from_query_string(
+        environ.get("QUERY_STRING", ""),
+        method=environ.get("REQUEST_METHOD", "GET"),
+        path=path,
+        prefix=environ.get(PREFIX_HEADER, "") + script_name,
+        headers=request_headers(environ),
+    )
+
+
+def request_headers(environ: Environ) -> dict[str, str]:
+    """Recover header names from the CGI-style keys WSGI hands over."""
+    headers = {
+        key[5:].replace("_", "-").lower(): value
+        for key, value in environ.items()
+        if key.startswith("HTTP_")
+    }
+    for key, name in (
+        ("CONTENT_TYPE", "content-type"),
+        ("CONTENT_LENGTH", "content-length"),
+    ):
+        # These two lose their HTTP_ prefix on the way into WSGI.
+        if key in environ:
+            headers[name] = environ[key]
+    return headers

taskflow_meter/cli.py

@@ -0,0 +1,287 @@
+#    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.
+
+"""Command line entry point for ``taskflow-meter``.
+
+Three commands, which between them cover both deployments:
+
+``serve``
+    The API.  Runs on :mod:`wsgiref`, which is in the standard library,
+    so a monitoring server costs no dependency at all.  It is a
+    development server: fine for a laptop, a container sidecar or a
+    look at a staging logbook, but a real deployment should put the
+    same callable behind gunicorn or mount it in a service it runs.
+
+``collect``
+    The other half of a multi-process deployment: consume events from a
+    broker and write them to a shared store, so the flows publish once
+    and any number of API workers read without polling anything.
+
+``upgrade``
+    Bring that store's schema up to date.
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import socketserver
+from collections.abc import Sequence
+from typing import Any
+from wsgiref.simple_server import WSGIRequestHandler
+from wsgiref.simple_server import WSGIServer
+from wsgiref.simple_server import make_server
+
+from taskflow_meter import __version__
+from taskflow_meter.api.wsgi import WSGIApp
+from taskflow_meter.datasource.persistence import PersistenceDataSource
+from taskflow_meter.meter import Meter
+from taskflow_meter.poller import DEFAULT_INTERVAL
+
+LOG = logging.getLogger(__name__)
+
+#: Localhost by default: a monitoring API exposes flow names, atom
+#: names and failure detail, none of which belongs on 0.0.0.0 by
+#: accident.
+DEFAULT_HOST = "127.0.0.1"
+DEFAULT_PORT = 8080
+
+
+class ThreadingWSGIServer(socketserver.ThreadingMixIn, WSGIServer):
+    """One thread per connection.
+
+    The single-threaded default would let one open SSE stream block
+    every other request for as long as it stayed connected.
+    """
+
+    daemon_threads = True
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="taskflow-meter",
+        description="Monitor OpenStack TaskFlow flow execution progress.",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+    subcommands = parser.add_subparsers(dest="command")
+
+    serve = subcommands.add_parser(
+        "serve",
+        help="serve the monitoring API over HTTP",
+        description=(
+            "Read a taskflow persistence backend and serve the "
+            "monitoring API.  A development server; put the WSGI "
+            "callable behind a real one for anything else."
+        ),
+    )
+    serve.add_argument(
+        "--connection",
+        metavar="URL",
+        help=(
+            "taskflow persistence connection, as the flows themselves "
+            "use it (for example sqlite:///taskflow.db)"
+        ),
+    )
+    serve.add_argument("--host", default=DEFAULT_HOST)
+    serve.add_argument("--port", type=int, default=DEFAULT_PORT)
+    serve.add_argument(
+        "--interval",
+        type=float,
+        default=DEFAULT_INTERVAL,
+        help="seconds between polls of the backend",
+    )
+    serve.add_argument(
+        "--no-poll",
+        action="store_true",
+        help=(
+            "read the backend directly instead of polling it; no event "
+            "history, and the stream endpoints report 501"
+        ),
+    )
+    serve.add_argument(
+        "--store-url",
+        metavar="URL",
+        help=(
+            "read the meter's own database instead, as filled by a "
+            "collect process; implies no polling"
+        ),
+    )
+    serve.set_defaults(handler=serve_command)
+
+    collect = subcommands.add_parser(
+        "collect",
+        help="consume events from a broker into the meter's database",
+        description=(
+            "The collector half of a multi-process deployment. Flows "
+            "publish events to a broker; this writes them to a store "
+            "the API workers read."
+        ),
+    )
+    collect.add_argument(
+        "--amqp-url",
+        required=True,
+        metavar="URL",
+        help="broker to consume from, for example amqp://host//",
+    )
+    collect.add_argument(
+        "--store-url",
+        required=True,
+        metavar="URL",
+        help="the meter's own database to write to",
+    )
+    collect.add_argument(
+        "--create-schema",
+        action="store_true",
+        help="create the tables if missing, instead of migrating",
+    )
+    collect.add_argument(
+        "--once",
+        action="store_true",
+        help="drain whatever is queued and exit, rather than looping",
+    )
+    collect.add_argument(
+        "--timeout",
+        type=float,
+        default=1.0,
+        help="seconds to wait for a batch before looking again",
+    )
+    collect.set_defaults(handler=collect_command)
+
+    upgrade = subcommands.add_parser(
+        "upgrade",
+        help="bring the meter's own database up to date",
+    )
+    upgrade.add_argument("--store-url", required=True, metavar="URL")
+    upgrade.set_defaults(handler=upgrade_command)
+    return parser
+
+
+def build_app(
+    connection: str | None = None,
+    *,
+    poll: bool = True,
+    interval: float = DEFAULT_INTERVAL,
+    store_url: str | None = None,
+) -> WSGIApp:
+    """Build the callable for whichever deployment was asked for.
+
+    With ``store_url`` the meter reads a store a collector fills, and
+    polls nothing.  Otherwise it watches a taskflow backend directly.
+    """
+    if store_url is not None:
+        return WSGIApp(Meter(build_store(store_url), poll=False))
+    if connection is None:
+        msg = "pass --connection or --store-url"
+        raise ValueError(msg)
+    source = PersistenceDataSource(conf={"connection": connection})
+    return WSGIApp(Meter(source, poll=poll, interval=interval))
+
+
+def build_store(url: str, *, create_schema: bool = False) -> Any:
+    """Open the meter's own database.
+
+    Imported here rather than at module scope: SQLAlchemy is an extra,
+    and `taskflow-meter serve` against a taskflow backend must not
+    require it.
+    """
+    from taskflow_meter.datasource.sqlalchemy import SQLADataSource
+
+    return SQLADataSource(url, create_schema=create_schema)
+
+
+def serve_command(args: argparse.Namespace) -> int:
+    logging.basicConfig(
+        level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s"
+    )
+    app = build_app(
+        args.connection,
+        poll=not args.no_poll,
+        interval=args.interval,
+        store_url=args.store_url,
+    )
+    with (
+        app.meter,
+        make_server(
+            args.host,
+            args.port,
+            app,
+            server_class=ThreadingWSGIServer,
+            handler_class=WSGIRequestHandler,
+        ) as server,
+    ):
+        host, port = server.server_address[:2]
+        LOG.info("serving on http://%s:%s", host, port)
+        try:
+            server.serve_forever()
+        except KeyboardInterrupt:
+            LOG.info("shutting down")
+    return 0
+
+
+def collect_command(args: argparse.Namespace) -> int:
+    """Consume from the broker until interrupted."""
+    logging.basicConfig(
+        level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s"
+    )
+    from taskflow_meter.transports.amqp import AMQPSubscriber
+
+    store = build_store(args.store_url, create_schema=args.create_schema)
+    subscriber = AMQPSubscriber(args.amqp_url)
+    total = 0
+
+    with store, subscriber:
+        LOG.info("collecting from %s", args.amqp_url)
+        try:
+            while True:
+                received = subscriber.consume(
+                    store.apply_many, timeout=args.timeout
+                )
+                total += received
+                if received:
+                    LOG.info("stored %d events (%d total)", received, total)
+                if args.once:
+                    break
+        except KeyboardInterrupt:
+            LOG.info("shutting down after %d events", total)
+    return 0
+
+
+def upgrade_command(args: argparse.Namespace) -> int:
+    """Run the migrations against the meter's own database."""
+    logging.basicConfig(level=logging.INFO)
+    from taskflow_meter.datasource.sqlalchemy import upgrade
+
+    upgrade(args.store_url)
+    LOG.info("schema is up to date")
+    return 0
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    handler = getattr(args, "handler", None)
+    if handler is None:
+        parser.print_help()
+        return 0
+    if args.command == "serve" and not (args.connection or args.store_url):
+        # Neither source given: a usage error, not a traceback.
+        parser.error("serve needs --connection or --store-url")
+    result: int = handler(args)
+    return result
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

taskflow_meter/collect/__init__.py

@@ -0,0 +1,31 @@
+#    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 emit side: watch an engine as it runs."""
+
+from __future__ import annotations
+
+from taskflow_meter.collect.attachment import Attachment
+from taskflow_meter.collect.attachment import attach
+from taskflow_meter.collect.attachment import describe_graph
+from taskflow_meter.collect.listener import MeterListener
+from taskflow_meter.collect.pipeline import EventPipeline
+from taskflow_meter.collect.progress import ProgressTap
+
+__all__ = [
+    "Attachment",
+    "EventPipeline",
+    "MeterListener",
+    "ProgressTap",
+    "attach",
+    "describe_graph",
+]