taskflow-meter 1.0.0__py3-none-any.whl

taskflow_meter/meter.py

@@ -0,0 +1,255 @@
+#    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 handle everything else hangs off.
+
+A :class:`Meter` owns a source, optionally a store and a poller, and the
+lifecycle that ties them together.  The API layer holds one of these and
+nothing else, which is what lets the same object serve an embedded
+single-process dashboard and a worker reading a shared store.
+
+Lifecycle deserves its own note, because the obvious mechanism does not
+work.  **A mounted ASGI app never receives the lifespan scope** -- the
+host router handles it at the root and does not forward it to a mounted
+sub-application -- so startup cannot hang off lifespan alone.  Hence
+three ways in, all safe to combine:
+
+1. :meth:`start` / :meth:`stop`, or the context manager.  What a host
+   application should call from its own lifespan or ``AppConfig.ready``.
+2. :meth:`lifespan`, for when our ASGI app *is* the root application.
+3. :meth:`ensure_started`, the lazy fallback a first request can call.
+
+:meth:`start` and :meth:`stop` are reference counted, so a host that
+starts the meter and a first request that also touches it do not fight:
+the poller stops when the last holder lets go.  :meth:`ensure_started`
+deliberately takes no reference -- it has no paired release.
+"""
+
+from __future__ import annotations
+
+import atexit
+import contextlib
+import logging
+import threading
+from collections.abc import AsyncIterator
+from types import TracebackType
+from typing import Self
+
+from taskflow_meter.datasource.base import DEFAULT_EVENT_LIMIT
+from taskflow_meter.datasource.base import DEFAULT_FLOW_LIMIT
+from taskflow_meter.datasource.base import DataSource
+from taskflow_meter.datasource.base import EventPage
+from taskflow_meter.datasource.base import FlowPage
+from taskflow_meter.datasource.base import WritableDataSource
+from taskflow_meter.datasource.memory import MemoryDataSource
+from taskflow_meter.models import AtomSnapshot
+from taskflow_meter.models import FlowSnapshot
+from taskflow_meter.poller import DEFAULT_INTERVAL
+from taskflow_meter.poller import Poller
+
+LOG = logging.getLogger(__name__)
+
+
+class Meter:
+    """Owns a source, a store, a poller, and their lifecycle."""
+
+    def __init__(
+        self,
+        source: DataSource,
+        *,
+        store: WritableDataSource | None = None,
+        poll: bool = True,
+        interval: float = DEFAULT_INTERVAL,
+    ) -> None:
+        """Watch ``source``, keeping what is observed in ``store``.
+
+        With ``poll`` set, a store is required and defaults to an
+        in-memory one.  Without it there is no poller and no thread: the
+        meter is a read-through to ``source``, or to ``store`` when one
+        is supplied -- which is the shape an API worker takes when a
+        separate collector process keeps the store warm.
+        """
+        self.source = source
+        self.store = (
+            store
+            if store is not None
+            else (MemoryDataSource() if poll else None)
+        )
+        self._poller: Poller | None = None
+        if poll:
+            assert self.store is not None
+            self._poller = Poller(source, self.store, interval=interval)
+
+        self._lock = threading.RLock()
+        self._holders = 0
+        self._started = False
+
+    # -- what to read from -----------------------------------------------
+
+    @property
+    def reader(self) -> DataSource:
+        """Where queries are answered from.
+
+        The store wins when there is one, even though the source may be
+        fresher.  Serving snapshots from the source while serving events
+        from the store would let a client see a snapshot newer than the
+        stream it is resuming, and silently miss the difference.
+        """
+        return self.store if self.store is not None else self.source
+
+    @property
+    def poller(self) -> Poller | None:
+        return self._poller
+
+    @property
+    def running(self) -> bool:
+        with self._lock:
+            return self._started
+
+    # -- lifecycle -------------------------------------------------------
+
+    def start(self) -> None:
+        """Take a reference, starting everything on the first one."""
+        with self._lock:
+            self._holders += 1
+            self._start_locked()
+
+    def stop(self) -> None:
+        """Release a reference, stopping when the last one goes.
+
+        Extra calls are harmless: the count floors at zero rather than
+        going negative and leaving the meter unstoppable.
+        """
+        with self._lock:
+            if self._holders > 0:
+                self._holders -= 1
+            if self._holders == 0:
+                self._stop_locked()
+
+    def ensure_started(self) -> None:
+        """Start if not already running, without taking a reference.
+
+        For the lazy path: a first request can call this without owing a
+        matching :meth:`stop`.
+        """
+        with self._lock:
+            self._start_locked()
+
+    def _start_locked(self) -> None:
+        if self._started:
+            return
+        self.source.start()
+        if self.store is not None:
+            self.store.start()
+        if self._poller is not None:
+            self._poller.start()
+        # Registered once per start cycle: _start_locked returns early
+        # when already started, so this cannot stack up.
+        atexit.register(self._atexit_stop)
+        self._started = True
+
+    def _stop_locked(self) -> None:
+        if not self._started:
+            return
+        self._started = False
+        if self._poller is not None:
+            self._poller.stop()
+        # Shutdown must not be abandoned halfway because one component
+        # objected, or the rest leak.
+        for closing in (self.store, self.source):
+            if closing is None:
+                continue
+            try:
+                closing.stop()
+            except Exception:
+                LOG.exception("failed stopping %r", closing)
+        # A no-op when it was never registered.
+        atexit.unregister(self._atexit_stop)
+
+    def _atexit_stop(self) -> None:
+        with self._lock:
+            self._holders = 0
+            self._stop_locked()
+
+    def __enter__(self) -> Self:
+        self.start()
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self.stop()
+
+    @contextlib.asynccontextmanager
+    async def lifespan(
+        self,
+        app: object = None,  # noqa: ARG002 - ASGI hands the app over
+    ) -> AsyncIterator[None]:
+        """ASGI lifespan handler, for when our app is the root one.
+
+        Useless on a *mounted* app -- see the module docstring -- so this
+        is a convenience, never the only way in.
+        """
+        self.start()
+        try:
+            yield
+        finally:
+            self.stop()
+
+    # -- queries ---------------------------------------------------------
+
+    @property
+    def supports_events(self) -> bool:
+        return self.reader.supports_events
+
+    def list_flows(
+        self,
+        *,
+        state: str | None = None,
+        book_id: str | None = None,
+        limit: int = DEFAULT_FLOW_LIMIT,
+        marker: str | None = None,
+    ) -> FlowPage:
+        return self.reader.list_flows(
+            state=state, book_id=book_id, limit=limit, marker=marker
+        )
+
+    def get_flow(self, run_id: str) -> FlowSnapshot | None:
+        return self.reader.get_flow(run_id)
+
+    def get_atoms(self, run_id: str) -> tuple[AtomSnapshot, ...] | None:
+        return self.reader.get_atoms(run_id)
+
+    def events_since(
+        self,
+        run_id: str,
+        *,
+        since_seq: int = 0,
+        limit: int = DEFAULT_EVENT_LIMIT,
+    ) -> EventPage:
+        return self.reader.events_since(
+            run_id, since_seq=since_seq, limit=limit
+        )
+
+    def poll_once(self) -> int:
+        """Run one poll on the calling thread.
+
+        Lets a caller drive the meter deterministically instead of
+        waiting on the interval.
+        """
+        if self._poller is None:
+            msg = "this meter has no poller (poll=False)"
+            raise RuntimeError(msg)
+        return self._poller.poll_once()

taskflow_meter/models.py

@@ -0,0 +1,143 @@
+#    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.
+
+"""Point-in-time view of a flow and its atoms.
+
+These are the types the API serialises and the diff engine compares.  They
+are deliberately plain: adapters translate taskflow's persistence models or
+notifier callbacks *into* these, so nothing downstream needs to know which
+producer it is talking to.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from dataclasses import field
+from typing import Any
+
+from taskflow_meter import states
+
+TASK = "task"
+RETRY = "retry"
+
+
+@dataclass(frozen=True, slots=True)
+class AtomSnapshot:
+    """What is known about a single atom at one moment."""
+
+    name: str
+    uuid: str | None = None
+    atom_type: str = TASK
+    state: str | None = None
+    intention: str | None = None
+    progress: float = 0.0
+    progress_details: dict[str, Any] | None = None
+    failure: dict[str, Any] | None = None
+    revert_failure: dict[str, Any] | None = None
+    has_result: bool = False
+    meta: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def is_finished(self) -> bool:
+        return self.state in states.ATOM_FINISH_STATES
+
+    @property
+    def is_running(self) -> bool:
+        return self.state in states.ATOM_RUNNING_STATES
+
+    @property
+    def completion(self) -> float:
+        """This atom's contribution to flow completion, in ``[0, 1]``.
+
+        Reported progress is only trusted while the atom is running.  A
+        finished atom's stored progress cannot be taken at face value:
+        taskflow sets it to 1.0 on both ``SUCCESS`` and ``REVERTED``, and
+        leaves it untouched on ``FAILURE``, so it would otherwise report a
+        reverted or failed atom as complete.
+        """
+        if self.state in states.ATOM_COMPLETE_STATES:
+            return 1.0
+        if self.is_running:
+            return _clamp(self.progress)
+        return 0.0
+
+
+@dataclass(frozen=True, slots=True)
+class FlowSnapshot:
+    """What is known about one flow run at one moment.
+
+    ``observed_at`` is when *we* looked, not when the flow actually changed:
+    taskflow records no timestamps below the logbook, so nothing else is
+    available.  For the live listener that is close enough to be the same
+    thing; for the poller it is only accurate to the poll interval.
+    """
+
+    run_id: str
+    name: str = ""
+    state: str | None = None
+    book_id: str | None = None
+    book_name: str | None = None
+    observed_at: float = 0.0
+    meta: dict[str, Any] = field(default_factory=dict)
+    atoms: dict[str, AtomSnapshot] = field(default_factory=dict)
+
+    @property
+    def is_finished(self) -> bool:
+        return self.state in states.FLOW_FINISH_STATES
+
+    @property
+    def atom_names(self) -> tuple[str, ...]:
+        """Atom names in a stable order, so output never reshuffles."""
+        return tuple(sorted(self.atoms))
+
+    def atom(self, name: str) -> AtomSnapshot | None:
+        return self.atoms.get(name)
+
+    @property
+    def running_atoms(self) -> tuple[AtomSnapshot, ...]:
+        """The atoms executing right now, in name order.
+
+        The answer to "what is it doing?".  A plural, because taskflow
+        runs unordered and graph flows in parallel, so there is often
+        more than one -- and none at all between two atoms, or once the
+        flow has finished.
+        """
+        return tuple(
+            self.atoms[name]
+            for name in self.atom_names
+            if self.atoms[name].is_running
+        )
+
+    @property
+    def state_counts(self) -> dict[str, int]:
+        counts: dict[str, int] = {}
+        for atom in self.atoms.values():
+            key = atom.state if atom.state is not None else "UNKNOWN"
+            counts[key] = counts.get(key, 0) + 1
+        return counts
+
+    @property
+    def completion(self) -> float:
+        """Unweighted mean of the atoms' completion, in ``[0, 1]``.
+
+        Every atom counts the same because taskflow gives us nothing to
+        weight them by -- no durations, no cost hints.  Treat it as a rough
+        indicator, not an estimate of time remaining.
+        """
+        if not self.atoms:
+            return 0.0
+        total = sum(atom.completion for atom in self.atoms.values())
+        return total / len(self.atoms)
+
+
+def _clamp(value: float, low: float = 0.0, high: float = 1.0) -> float:
+    return max(low, min(high, value))

taskflow_meter/poller.py

@@ -0,0 +1,191 @@
+#    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.
+
+"""Turn a state-only datasource into an event stream, by watching it.
+
+The poller is the second producer.  It reads whatever a source can see,
+diffs each flow against what it saw last time, and feeds the resulting
+events to a sink -- which is how a deployment whose persistence records
+only current state ends up with a resumable stream.
+
+What it cannot do is see between polls.  A state a flow passed through
+and left within one interval was never observable, and no amount of
+diffing invents it.  Shorter intervals narrow that window at the cost of
+load; the in-process listener closes it entirely.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+from collections.abc import Callable
+from dataclasses import dataclass
+from dataclasses import field
+
+from taskflow_meter.datasource.base import DEFAULT_FLOW_LIMIT
+from taskflow_meter.datasource.base import DataSource
+from taskflow_meter.datasource.base import WritableDataSource
+from taskflow_meter.diff import diff_flow
+from taskflow_meter.events import SequenceAllocator
+from taskflow_meter.models import FlowSnapshot
+
+LOG = logging.getLogger(__name__)
+
+#: Seconds between polls, when nothing says otherwise.
+DEFAULT_INTERVAL = 2.0
+
+
+@dataclass(slots=True)
+class PollStats:
+    """Counters worth exposing on a health endpoint."""
+
+    polls: int = 0
+    events: int = 0
+    errors: int = 0
+    flows_seen: int = 0
+    last_error: str | None = field(default=None)
+
+
+class Poller:
+    """Watches ``source``, feeding what changes into ``sink``."""
+
+    def __init__(
+        self,
+        source: DataSource,
+        sink: WritableDataSource,
+        *,
+        interval: float = DEFAULT_INTERVAL,
+        allocator: SequenceAllocator | None = None,
+        page_size: int = DEFAULT_FLOW_LIMIT,
+        on_error: Callable[[Exception], None] | None = None,
+    ) -> None:
+        if interval <= 0:
+            msg = "interval must be positive"
+            raise ValueError(msg)
+        if page_size < 1:
+            msg = "page_size must be at least 1"
+            raise ValueError(msg)
+
+        self.source = source
+        self.sink = sink
+        self.interval = interval
+        self.stats = PollStats()
+
+        self._allocator = allocator or SequenceAllocator()
+        self._page_size = page_size
+        self._on_error = on_error
+        # Every flow the source still reports, as last seen.  Finished
+        # flows stay here on purpose: dropping one whose events were
+        # already emitted would make the next poll rediscover it and
+        # replay its whole history.
+        self._previous: dict[str, FlowSnapshot] = {}
+        self._lock = threading.Lock()
+        self._thread: threading.Thread | None = None
+        self._stopping = threading.Event()
+
+    @property
+    def allocator(self) -> SequenceAllocator:
+        return self._allocator
+
+    @property
+    def running(self) -> bool:
+        with self._lock:
+            return self._thread is not None and self._thread.is_alive()
+
+    # -- one pass --------------------------------------------------------
+
+    def poll_once(self) -> int:
+        """Read, diff, emit.  Returns how many events were produced.
+
+        Raises whatever the source or sink raises; the background loop is
+        what turns that into a counted, logged error.
+        """
+        seen: dict[str, FlowSnapshot] = {}
+        emitted = 0
+
+        for snapshot in self._read_all():
+            seen[snapshot.run_id] = snapshot
+            previous = self._previous.get(snapshot.run_id)
+            events = diff_flow(
+                previous,
+                snapshot,
+                allocator=self._allocator,
+                ts=snapshot.observed_at,
+            )
+            if events:
+                self.sink.apply_many(events)
+                emitted += len(events)
+
+        for run_id in self._previous.keys() - seen.keys():
+            # The source stopped reporting it -- the logbook was deleted,
+            # or retention expired it.  Forget it rather than pretend.
+            LOG.debug("run %s is no longer reported by the source", run_id)
+
+        self._previous = seen
+        self.stats.polls += 1
+        self.stats.events += emitted
+        self.stats.flows_seen = len(seen)
+        return emitted
+
+    def _read_all(self) -> list[FlowSnapshot]:
+        """Walk every page the source offers."""
+        flows: list[FlowSnapshot] = []
+        marker: str | None = None
+        while True:
+            page = self.source.list_flows(limit=self._page_size, marker=marker)
+            flows.extend(page.items)
+            if not page.has_more:
+                return flows
+            marker = page.next_marker
+
+    # -- background loop -------------------------------------------------
+
+    def start(self) -> None:
+        """Begin polling on a daemon thread.  Idempotent."""
+        with self._lock:
+            if self._thread is not None and self._thread.is_alive():
+                return
+            self._stopping.clear()
+            self._thread = threading.Thread(
+                target=self._loop,
+                name="taskflow-meter-poller",
+                daemon=True,
+            )
+            self._thread.start()
+
+    def stop(self, timeout: float | None = 5.0) -> None:
+        """Ask the loop to finish and wait for it.  Idempotent."""
+        with self._lock:
+            thread = self._thread
+            self._thread = None
+        self._stopping.set()
+        if thread is not None and thread.is_alive():
+            thread.join(timeout)
+            if thread.is_alive():
+                LOG.warning("poller thread did not stop within %.1fs", timeout)
+
+    def _loop(self) -> None:
+        while not self._stopping.is_set():
+            try:
+                self.poll_once()
+            except Exception as exc:
+                # A monitoring loop that dies on one bad read stops
+                # monitoring silently, which is worse than a noisy one.
+                self.stats.errors += 1
+                self.stats.last_error = repr(exc)
+                LOG.exception("poll failed")
+                if self._on_error is not None:
+                    try:
+                        self._on_error(exc)
+                    except Exception:
+                        LOG.exception("poller error handler failed")
+            self._stopping.wait(self.interval)

taskflow_meter/states.py

@@ -0,0 +1,60 @@
+#    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.
+
+"""State vocabulary, derived from taskflow rather than duplicated.
+
+Importing the values from :mod:`taskflow.states` keeps us from drifting if
+upstream ever renames one, and keeps the groupings in a single place.
+"""
+
+from __future__ import annotations
+
+from taskflow import states as _tf
+
+#: Flow states after which no further atom activity is expected.
+FLOW_FINISH_STATES: frozenset[str] = frozenset(
+    {_tf.SUCCESS, _tf.FAILURE, _tf.REVERTED, _tf.SUSPENDED}
+)
+
+#: Atom states in which a result (or failure) is available.  Mirrors
+#: ``taskflow.listeners.base.FINISH_STATES``.
+ATOM_FINISH_STATES: frozenset[str] = frozenset(
+    {_tf.SUCCESS, _tf.FAILURE, _tf.REVERTED, _tf.REVERT_FAILURE}
+)
+
+#: Atom states during which reported progress is meaningful.
+ATOM_RUNNING_STATES: frozenset[str] = frozenset(
+    {_tf.RUNNING, _tf.REVERTING, _tf.RETRYING}
+)
+
+#: Atom states that contribute a completed unit of forward work.
+#:
+#: ``IGNORE`` counts because a decider has ruled the atom out: it will never
+#: run, so treating it as outstanding would leave the flow permanently short
+#: of 100%.  ``REVERTED`` deliberately does *not* count -- taskflow sets an
+#: atom's progress back to 1.0 when its revert finishes, which says the
+#: revert completed, not that the work did.
+ATOM_COMPLETE_STATES: frozenset[str] = frozenset({_tf.SUCCESS, _tf.IGNORE})
+
+SUCCESS: str = _tf.SUCCESS
+FAILURE: str = _tf.FAILURE
+PENDING: str = _tf.PENDING
+RUNNING: str = _tf.RUNNING
+REVERTING: str = _tf.REVERTING
+REVERTED: str = _tf.REVERTED
+REVERT_FAILURE: str = _tf.REVERT_FAILURE
+RETRYING: str = _tf.RETRYING
+IGNORE: str = _tf.IGNORE
+SUSPENDED: str = _tf.SUSPENDED
+
+EXECUTE: str = _tf.EXECUTE
+REVERT: str = _tf.REVERT

taskflow_meter/transports/__init__.py

@@ -0,0 +1,21 @@
+#    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.
+
+"""Transports: where events go once produced."""
+
+from __future__ import annotations
+
+from taskflow_meter.transports.base import Publisher
+from taskflow_meter.transports.memory import DataSourcePublisher
+from taskflow_meter.transports.memory import MemoryTransport
+
+__all__ = ["DataSourcePublisher", "MemoryTransport", "Publisher"]