forktex-flow 0.1.0__py3-none-any.whl

forktex_flow/__init__.py

@@ -0,0 +1,106 @@
+# Copyright (C) 2026 FORKTEX S.R.L.
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later OR LicenseRef-ForkTex-Commercial
+#
+# This file is part of ForkTex Flow.
+#
+# For commercial licensing -- including use in proprietary products, SaaS
+# deployments, or any context where AGPL obligations cannot be met -- you
+# MUST obtain a commercial license from FORKTEX S.R.L. (info@forktex.com).
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+"""Postgres-native durable workflow execution, built on the ``forktex`` substrate.
+
+A workflow is an ordered list of steps. Declare one of two ways::
+
+    flow = Flow(database_url="postgresql+asyncpg://...")
+
+    @flow.scheduled("cloud.backup.create", version=1, cron="0 2 * * *", state=BackupState)
+    async def backup_create(ctx: Ctx, state: BackupState) -> dict: ...
+
+    @flow.pipeline("cloud.deploy.apply", version=4, state=DeployState)
+    class DeployApply:
+        steps = [load_manifest, provision, step(dns_setup, when=lambda s: s["dns_enabled"])]
+
+Dispatch and read::
+
+    instance = await flow.run("cloud.deploy.apply", state={...}, metadata={...})
+    page = await flow.query().workflow("cloud.deploy.apply").status("running").fetch()
+
+A step is ``async def fn(ctx: Ctx, state: dict) -> dict`` and returns the *delta*
+it wants merged, not the whole state. How a delta merges is declared on the
+state class::
+
+    class DeployState(TypedDict):
+        logs: Annotated[list[str], operator.add]   # accumulates across steps
+        server_id: str                             # last write wins
+
+Every step is memoised on ``(run_id, step, input state)``, so a run picked up
+after a crash re-executes from the top and skips straight past the work that
+already happened.
+"""
+
+from forktex_flow.domain.config import RuntimeConfig
+from forktex_flow.domain.node import StepSpec, step
+from forktex_flow.domain.state import apply_state_update, extract_reducers
+from forktex_flow.domain.types import (
+    TERMINAL_STATUSES,
+    RunInfo,
+    RunStatus,
+    RunSummary,
+    StepRunInfo,
+    StepStatus,
+)
+from forktex_flow.errors import FlowError, StepFailed, WorkflowCancelled, WorkflowFailed
+from forktex_flow.extension import FlowExtension
+from forktex_flow.flow import Flow
+from forktex_flow.persist.migrations import apply_migrations
+from forktex_flow.read.instance import (
+    InstancePage,
+    InstanceQuery,
+    NodeInstance,
+    WorkflowInstance,
+)
+from forktex_flow.runtime.ctx import Ctx
+from forktex_flow.testing import isolated_flow, make_ctx, run_to_completion
+
+__all__ = [
+    "TERMINAL_STATUSES",
+    "Ctx",
+    "Flow",
+    "FlowError",
+    "FlowExtension",
+    "InstancePage",
+    "InstanceQuery",
+    "NodeInstance",
+    "RunInfo",
+    "RunStatus",
+    "RunSummary",
+    "RuntimeConfig",
+    "StepFailed",
+    "StepRunInfo",
+    "StepSpec",
+    "StepStatus",
+    "WorkflowCancelled",
+    "WorkflowFailed",
+    "WorkflowInstance",
+    "apply_migrations",
+    "apply_state_update",
+    "extract_reducers",
+    "isolated_flow",
+    "make_ctx",
+    "run_to_completion",
+    "step",
+]

forktex_flow/domain/__init__.py

@@ -0,0 +1,76 @@
+# Copyright (C) 2026 FORKTEX S.R.L.
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later OR LicenseRef-ForkTex-Commercial
+#
+# This file is part of ForkTex Flow.
+#
+# For commercial licensing -- including use in proprietary products, SaaS
+# deployments, or any context where AGPL obligations cannot be met -- you
+# MUST obtain a commercial license from FORKTEX S.R.L. (info@forktex.com).
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+"""Flow's vocabulary: frozen value objects and the declarative workflow shapes.
+
+The bottom of the package's DAG — nothing here imports anything else from
+`forktex_flow`, and nothing here performs I/O. A reader can learn what a workflow
+*is* from this layer alone, without meeting a session or an engine.
+
+Four modules, split by what they describe: `types` the run/step row shapes and
+statuses, `definition` the compiled workflow (an ordered list of steps), `node`
+the authoring decorator, and `state` the reducer that merges a step's partial
+update into the run state.
+"""
+
+from forktex_flow.domain.definition import (
+    NodeDef,
+    NodeFn,
+    WhenFn,
+    WorkflowDefinition,
+)
+from forktex_flow.domain.node import (
+    StepMeta,
+    StepSpec,
+    has_step_meta,
+    step,
+    step_meta,
+)
+from forktex_flow.domain.state import ReducerFn, apply_state_update, extract_reducers
+from forktex_flow.domain.types import (
+    TERMINAL_STATUSES,
+    RunInfo,
+    RunStatus,
+    StepRunInfo,
+    StepStatus,
+)
+
+__all__ = [
+    "TERMINAL_STATUSES",
+    "NodeDef",
+    "NodeFn",
+    "ReducerFn",
+    "RunInfo",
+    "RunStatus",
+    "StepMeta",
+    "StepRunInfo",
+    "StepSpec",
+    "StepStatus",
+    "WhenFn",
+    "WorkflowDefinition",
+    "apply_state_update",
+    "extract_reducers",
+    "has_step_meta",
+    "step",
+    "step_meta",
+]

forktex_flow/domain/config.py

@@ -0,0 +1,88 @@
+# Copyright (C) 2026 FORKTEX S.R.L.
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later OR LicenseRef-ForkTex-Commercial
+#
+# This file is part of ForkTex Flow.
+#
+# For commercial licensing -- including use in proprietary products, SaaS
+# deployments, or any context where AGPL obligations cannot be met -- you
+# MUST obtain a commercial license from FORKTEX S.R.L. (info@forktex.com).
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+"""Execution tuning — the knobs the driver and executor read.
+
+A frozen value object rather than attributes on ``Flow``, because it is the
+whole reason the lower layers used to take the facade: they needed a handful of
+numbers and took the entire engine to get them. Pure data, no I/O, so it sits at the
+bottom of the DAG where every layer can read it.
+"""
+
+from __future__ import annotations
+
+from forktex.error import BadRequestError
+from forktex.types import BaseValueObject
+from pydantic import model_validator
+
+
+class RuntimeConfig(BaseValueObject):
+    """How hard the driver polls, and how patient it is with a stalled step.
+
+    Attributes:
+        poll_interval:      Seconds between driver ticks when it holds the lock.
+        election_interval:  Seconds a worker waits before standing for election
+                            again after losing one. Bounds how long a takeover
+                            takes after the leader dies: too long and work sits
+                            idle, too short and every worker polls the lock.
+        heartbeat_interval: Seconds between heartbeat writes on a running step.
+        stale_threshold:    Seconds without a heartbeat after which a step is
+                            considered abandoned and may be reclaimed. Must
+                            exceed ``heartbeat_interval``, or a healthy step
+                            gets reclaimed out from under itself.
+        max_attempts:       Default attempts per step, when ``@step`` does not
+                            override it.
+        backoff:            Default per-attempt delay in seconds; the last entry
+                            is reused once attempts run past its length.
+        leader_lock_key:    The advisory-lock key the driver competes on.
+    """
+
+    poll_interval: float = 1.0
+    election_interval: float = 2.0
+    heartbeat_interval: float = 10.0
+    stale_threshold: float = 60.0
+    max_attempts: int = 3
+    backoff: tuple[float, ...] = (30.0, 120.0, 300.0)
+    leader_lock_key: int = 0
+
+    @model_validator(mode="after")
+    def _check(self) -> RuntimeConfig:
+        if self.max_attempts < 1:
+            raise BadRequestError("max_attempts must be >= 1")
+        if not self.backoff:
+            raise BadRequestError("backoff must be a non-empty tuple")
+        if self.poll_interval <= 0:
+            raise BadRequestError("poll_interval must be > 0")
+        if self.election_interval <= 0:
+            raise BadRequestError("election_interval must be > 0")
+        if self.stale_threshold <= self.heartbeat_interval:
+            # Otherwise the reclaim scan finds a step whose heartbeat is merely
+            # *due* and hands it to a second worker, which is how one step body
+            # ends up running twice.
+            raise BadRequestError(
+                f"stale_threshold ({self.stale_threshold}) must exceed heartbeat_interval ({self.heartbeat_interval})"
+            )
+        return self
+
+
+__all__ = ["RuntimeConfig"]

forktex_flow/domain/definition.py

@@ -0,0 +1,125 @@
+# Copyright (C) 2026 FORKTEX S.R.L.
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later OR LicenseRef-ForkTex-Commercial
+#
+# This file is part of ForkTex Flow.
+#
+# For commercial licensing -- including use in proprietary products, SaaS
+# deployments, or any context where AGPL obligations cannot be met -- you
+# MUST obtain a commercial license from FORKTEX S.R.L. (info@forktex.com).
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+"""WorkflowDefinition — the internal model every decorator compiles to.
+
+A workflow is an **ordered list of steps**. That is the whole topology: there is
+no edge set, no router, no START/END sentinel and no reachability analysis,
+because a pipeline's order *is* its graph and a scheduled workflow is a pipeline
+of one. Branching is expressed by a step's ``when_fn`` — a pure predicate over
+the state dict, evaluated immediately before dispatch — which is strictly weaker
+than a router and strictly easier to reason about: a run visits every node once,
+in order, executing the ones whose guard passes.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from forktex.error import BadRequestError
+from forktex.types import BaseValueObject
+from pydantic import BaseModel, Field, model_validator
+
+from forktex_flow.domain.state import ReducerFn
+
+#: ``async def fn(ctx: Ctx, state: dict[str, Any]) -> dict[str, Any]`` — a step
+#: returns the *delta* it wants merged into state, not the whole state.
+NodeFn = Callable[[Any, dict[str, Any]], Awaitable[dict[str, Any]]]
+
+#: A guard evaluated against the current state before a node is dispatched.
+WhenFn = Callable[[dict[str, Any]], bool]
+
+
+class NodeDef(BaseValueObject):
+    """One step in the workflow.
+
+    ``when_fn`` is evaluated against the current state dict before the node is
+    dispatched; ``None`` means "always execute".
+    """
+
+    name: str
+    fn: NodeFn
+    max_attempts: int
+    backoff: tuple[float, ...]
+    when_fn: WhenFn | None = None
+
+
+class WorkflowDefinition(BaseModel):
+    """Complete, validated description of a workflow.
+
+    Every decorator compiles to this, and the executor reads only from here —
+    so ``@pipeline`` and ``@scheduled`` differ by exactly one field
+    (``schedule``) rather than by an execution path.
+
+    Attributes:
+        name:      Workflow identifier, unique per version.
+        version:   Bumped when the step list changes shape.
+        state_cls: The TypedDict defining the state schema. ``None`` for
+                   workflows that carry an untyped ``dict`` state.
+        nodes:     The steps, **in execution order**.
+        reducers:  ``field_name -> merge function``, extracted from the
+                   ``Annotated`` hints on ``state_cls``. A field with no
+                   reducer is last-write-wins.
+        schedule:  Cron expression, or ``None`` for on-demand workflows.
+    """
+
+    name: str
+    version: int
+    state_cls: type | None
+    nodes: tuple[NodeDef, ...] = ()
+    reducers: dict[str, ReducerFn] = Field(default_factory=dict)
+    schedule: str | None = None
+
+    @model_validator(mode="after")
+    def _check_topology(self) -> WorkflowDefinition:
+        """Reject a definition that cannot run, at declaration time.
+
+        A model validator rather than a method a caller must remember to call:
+        the previous shape had a ``validate()`` each compiler had to invoke, and
+        one forgetting it produced a workflow that failed on its first dispatch
+        in production rather than at import.
+        """
+        if not self.nodes:
+            raise BadRequestError(f"workflow {self.name!r} v{self.version} has no steps")
+        seen: set[str] = set()
+        for node in self.nodes:
+            if node.name in seen:
+                raise BadRequestError(
+                    f"workflow {self.name!r} v{self.version}: duplicate step name {node.name!r} — "
+                    "step names identify rows in step_run and must be unique within a workflow"
+                )
+            seen.add(node.name)
+        return self
+
+    def node_names(self) -> tuple[str, ...]:
+        """Step names in execution order."""
+        return tuple(node.name for node in self.nodes)
+
+
+__all__ = [
+    "NodeDef",
+    "NodeFn",
+    "WhenFn",
+    "WorkflowDefinition",
+]

forktex_flow/domain/filter.py

@@ -0,0 +1,71 @@
+# Copyright (C) 2026 FORKTEX S.R.L.
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later OR LicenseRef-ForkTex-Commercial
+#
+# This file is part of ForkTex Flow.
+#
+# For commercial licensing -- including use in proprietary products, SaaS
+# deployments, or any context where AGPL obligations cannot be met -- you
+# MUST obtain a commercial license from FORKTEX S.R.L. (info@forktex.com).
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+"""``RunFilter`` — what a caller is asking for, without any SQL.
+
+Extracted so the read layer compiles a value object instead of reaching into a
+query builder's private attributes, and so the same filter set can be applied to
+the page query, the count and the summary. It previously could not be: each of
+the three built its own ``where`` list, and the summary's list was missing the
+metadata, state and current-node filters — so ``.metadata(k=v).summary()``
+silently aggregated over every run in the table.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from forktex.types import BaseValueObject
+from pydantic import Field
+
+
+class RunFilter(BaseValueObject):
+    """The predicate half of a run query. Frozen, and free of I/O.
+
+    Every field is optional; an empty ``RunFilter`` matches every run.
+
+    Attributes:
+        workflow_name:    Exact match on the workflow's name.
+        workflow_version: Exact match on its version. Only meaningful with a name.
+        statuses:         Any-of match on run status.
+        metadata_filter:  JSONB containment against ``run.metadata``.
+        state_filter:     JSONB containment against ``run.input``.
+        current_nodes:    Runs whose currently-running step is one of these.
+        since:            ``started_at >= since``.
+        until:            ``started_at < until``.
+        triggered_by:     Any-of match on the trigger label.
+    """
+
+    workflow_name: str | None = None
+    workflow_version: int | None = None
+    statuses: tuple[str, ...] = ()
+    metadata_filter: dict[str, Any] = Field(default_factory=dict)
+    state_filter: dict[str, Any] = Field(default_factory=dict)
+    current_nodes: tuple[str, ...] = ()
+    since: datetime | None = None
+    until: datetime | None = None
+    triggered_by: tuple[str, ...] = ()
+
+
+__all__ = ["RunFilter"]

forktex_flow/domain/node.py

@@ -0,0 +1,137 @@
+# Copyright (C) 2026 FORKTEX S.R.L.
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later OR LicenseRef-ForkTex-Commercial
+#
+# This file is part of ForkTex Flow.
+#
+# For commercial licensing -- including use in proprietary products, SaaS
+# deployments, or any context where AGPL obligations cannot be met -- you
+# MUST obtain a commercial license from FORKTEX S.R.L. (info@forktex.com).
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+"""The ``@step`` decorator and the spec it produces.
+
+``step`` is deliberately dual-mode. Bare ``@step`` attaches a retry contract to
+the function and returns it unchanged, so a step is still an ordinary callable a
+test can await directly. ``step(fn, when=...)`` instead returns a
+:class:`StepSpec` for use inside a pipeline's ``steps`` list. The two forms
+cannot be confused because the second requires ``fn`` positionally.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from forktex.error import BadRequestError
+from forktex.types import BaseValueObject
+
+from forktex_flow.domain.config import RuntimeConfig
+
+# Attribute the @step decorator attaches to a function to carry its retry
+# contract. Named here once so call sites read it via ``step_meta`` rather
+# than repeating the dunder string.
+_STEP_META_ATTR = "__forktex_step_meta__"
+
+#: The retry contract a bare `@step` gets. Read from `RuntimeConfig`'s own
+#: defaults rather than restated here: the same two numbers written in three
+#: places is how a consumer sets `RuntimeConfig(max_attempts=7)` and every step
+#: still gets 3.
+_DEFAULTS = RuntimeConfig()
+
+
+class StepMeta(BaseValueObject):
+    """Retry + backoff configuration stored on the function itself.
+
+    The executor reads it via :func:`step_meta` at dispatch time. Storing it on
+    the function rather than in a registry means the function carries its own
+    durability contract and works with any ``Flow`` without prior registration.
+    """
+
+    max_attempts: int
+    backoff: tuple[float, ...]
+
+
+class StepSpec(BaseValueObject):
+    """Returned by ``step(fn, when=...)`` for use in a pipeline's ``steps`` list."""
+
+    fn: Callable[..., Any]
+    when: Callable[[dict[str, Any]], bool] | None = None
+    max_attempts: int | None = None
+    backoff: tuple[float, ...] | None = None
+
+
+def step_meta(fn: object) -> StepMeta | None:
+    """Return the :class:`StepMeta` attached by :func:`step`, or ``None``.
+
+    ``None`` is a legitimate result, not a broken invariant: the compilers
+    accept bare, undecorated callables and fall back to the default retry
+    config. The typed accessor centralises the attribute name and gives call
+    sites a precise return type without a per-site ``type: ignore``.
+    """
+    meta = getattr(fn, _STEP_META_ATTR, None)
+    return meta if isinstance(meta, StepMeta) else None
+
+
+def has_step_meta(fn: object) -> bool:
+    """True if ``fn`` was decorated with :func:`step`."""
+    return isinstance(getattr(fn, _STEP_META_ATTR, None), StepMeta)
+
+
+def step(
+    fn: Callable[..., Any] | None = None,
+    /,
+    *,
+    max_attempts: int | None = None,
+    backoff: tuple[float, ...] | None = None,
+    when: Callable[[dict[str, Any]], bool] | None = None,
+) -> Callable[..., Any] | StepSpec:
+    """Attach a retry contract to a step, or build a guarded pipeline entry.
+
+    As a decorator — ``@step`` or ``@step(max_attempts=5)`` — attaches
+    :class:`StepMeta` and returns ``fn`` unchanged.
+
+    As a pipeline entry — ``step(fn, when=predicate)`` — returns a
+    :class:`StepSpec`. ``fn`` must be positional.
+    """
+    resolved_max_attempts = max_attempts if max_attempts is not None else _DEFAULTS.max_attempts
+    resolved_backoff = backoff if backoff is not None else _DEFAULTS.backoff
+
+    def _attach_meta(target: Callable[..., Any]) -> Callable[..., Any]:
+        meta = StepMeta(max_attempts=resolved_max_attempts, backoff=resolved_backoff)
+        setattr(target, _STEP_META_ATTR, meta)
+        return target
+
+    if fn is None:
+        if when is not None:
+            # `when` selects a step *within a pipeline*, so it is meaningless
+            # without the function it guards. Raising here turns a silently
+            # ignored guard into an error at import time.
+            raise BadRequestError("step(when=...) requires fn as a positional argument")
+        return _attach_meta
+
+    if when is not None or max_attempts is not None or backoff is not None:
+        return StepSpec(fn=fn, when=when, max_attempts=max_attempts, backoff=backoff)
+
+    return _attach_meta(fn)
+
+
+__all__ = [
+    "StepMeta",
+    "StepSpec",
+    "has_step_meta",
+    "step",
+    "step_meta",
+]