queueflow 0.1.0__tar.gz → 0.2.0__tar.gz

{queueflow-0.1.0 → queueflow-0.2.0}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: queueflow
-Version: 0.1.0
+Version: 0.2.0
 Summary: QueueFlow API
-Home-page: https://github.com/queueflow/queueflow-sdk-python
+Home-page: https://github.com/elision-labs/queueflow-sdk-python
 Author: QueueFlow
 Author-email: team@queueflow.dev
 License: MIT

{queueflow-0.1.0 → queueflow-0.2.0}/README.md

@@ -4,7 +4,7 @@ REST API for QueueFlow, a PostgreSQL-native distributed job queue and workflow e
 This Python package is automatically generated by the [OpenAPI Generator](https://openapi-generator.tech) project:
 
 - API version: 1.0.0
-- Package version: 0.1.0
+- Package version: 0.2.0
 - Generator version: 7.10.0
 - Build package: org.openapitools.codegen.languages.PythonClientCodegen
 For more information, please visit [https://queueflow.dev](https://queueflow.dev)

{queueflow-0.1.0 → queueflow-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "queueflow"
-version = "0.1.0"
+version = "0.2.0"
 description = "QueueFlow API"
 authors = ["QueueFlow"]
 license = "MIT"

{queueflow-0.1.0 → queueflow-0.2.0}/queueflow/__init__.py

@@ -14,7 +14,7 @@
 """  # noqa: E501
 
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"
 
 # import apis into sdk package
 from queueflow.api.cron_api import CronApi

{queueflow-0.1.0 → queueflow-0.2.0}/queueflow/api_client.py

@@ -90,7 +90,7 @@ class ApiClient:
             self.default_headers[header_name] = header_value
         self.cookie = cookie
         # Set default User-Agent.
-        self.user_agent = 'OpenAPI-Generator/0.1.0/python'
+        self.user_agent = 'OpenAPI-Generator/0.2.0/python'
         self.client_side_validation = configuration.client_side_validation
 
     def __enter__(self):

{queueflow-0.1.0 → queueflow-0.2.0}/queueflow/configuration.py

@@ -504,7 +504,7 @@ class Configuration:
                "OS: {env}\n"\
                "Python Version: {pyversion}\n"\
                "Version of the API: 1.0.0\n"\
-               "SDK Package Version: 0.1.0".\
+               "SDK Package Version: 0.2.0".\
                format(env=sys.platform, pyversion=sys.version)
 
     def get_host_settings(self) -> List[HostSetting]:

{queueflow-0.1.0 → queueflow-0.2.0}/queueflow/facade.py

@@ -8,8 +8,11 @@ the per-tag api clients come from the generated modules and are never edited.
 
 from __future__ import annotations
 
+import inspect
+import logging
+import threading
 import time
-from typing import Any, Dict, List, Optional
+from typing import Any, Callable, Dict, List, Optional
 
 from .api_client import ApiClient
 from .configuration import Configuration
@@ -20,7 +23,12 @@ from .api.system_api import SystemApi
 from .api.health_api import HealthApi
 from .api.cron_api import CronApi
 from .api.dlq_api import DlqApi
+from .exceptions import ApiException
+from .models.complete_job_request import CompleteJobRequest
 from .models.create_job_request import CreateJobRequest
+from .models.fail_job_request import FailJobRequest
+from .models.heartbeat_request import HeartbeatRequest
+from .models.lease_jobs_request import LeaseJobsRequest
 from .models.job_config_request import JobConfigRequest
 from .models.create_workflow_request import CreateWorkflowRequest
 from .models.create_cron_request import CreateCronRequest
@@ -40,6 +48,35 @@ class WorkflowValidationError(ValueError):
     """Raised by WorkflowBuilder.build() for a structurally invalid DAG."""
 
 
+class NonRetryableError(Exception):
+    """Raise from a worker handler to mark the failure PERMANENT: the job
+    skips its remaining retries and dead-letters immediately (e.g. invalid
+    input). Any raised exception carrying ``retryable = False`` behaves the
+    same; this class is the convenient spelling."""
+
+    retryable = False
+
+
+class WorkerContext:
+    """Per-job context handed to two-argument worker handlers.
+
+    ``cancelled`` flips to True when the job's lease is lost (the job was
+    cancelled mid-run, or the lease expired and was reclaimed). From then on
+    the server owns the outcome: long handlers should check it periodically
+    and stop, because any further work is discarded.
+    """
+
+    def __init__(self) -> None:
+        self._lost = threading.Event()
+
+    @property
+    def cancelled(self) -> bool:
+        return self._lost.is_set()
+
+
+_logger = logging.getLogger("queueflow.worker")
+
+
 class QueueFlow:
     """Ergonomic client wrapping the generated api clients.
 
@@ -159,6 +196,179 @@ class QueueFlow:
         replayed = self.dlq.replay_dead_letter(dead_letter_id)
         return self.jobs.get_job(replayed.job_id)
 
+    # --- worker runtime -------------------------------------------------------
+
+    def run_worker(
+        self,
+        queue: str,
+        handlers: Dict[str, Callable[..., Optional[Dict[str, Any]]]],
+        lease_secs: int = 30,
+        wait_secs: int = 20,
+        stop: Optional["threading.Event"] = None,
+        on_error: Optional[Callable[[Exception], None]] = None,
+    ) -> None:
+        """Run a worker loop: lease jobs from ``queue``, dispatch to
+        ``handlers`` by task name, heartbeat while a handler runs, and report
+        the outcome. The engine owns retries, backoff, the dead-letter queue,
+        and workflow advancement.
+
+        Semantics (matching the Node SDK's ``qf.worker.run``):
+
+        * Delivery is **at-least-once** — make handlers idempotent.
+        * A handler returns the job's result dict (or None for ``{}``).
+          Raising fails the job through the engine's retry policy; raise
+          :class:`NonRetryableError` (or any exception with
+          ``retryable = False``) to dead-letter immediately.
+        * Each in-flight job is heartbeated at half the lease interval. A
+          heartbeat showing the job is no longer running (cancelled mid-run,
+          or the lease was reclaimed) abandons reporting — the server owns
+          the outcome — and flips ``ctx.cancelled`` so a two-argument handler
+          ``(job, ctx)`` can stop early.
+        * A failed *report* is never re-reported as a job failure: the lease
+          expires and the engine redelivers.
+        * Lease errors with HTTP 401/403 raise (a wrong or missing
+          ``worker_token`` cannot heal by retrying); other lease errors go to
+          ``on_error`` (or a throttled log) with a 1s backoff.
+
+        Blocks until ``stop`` (a ``threading.Event``) is set.
+        """
+        _logger.info("worker leasing %r (tasks: %s)", queue, ", ".join(sorted(handlers)))
+        failures = 0
+        while stop is None or not stop.is_set():
+            try:
+                leased = self.worker.lease_jobs(
+                    queue,
+                    LeaseJobsRequest(max_jobs=1, lease_secs=lease_secs, wait_secs=wait_secs),
+                ).jobs
+                failures = 0
+            except ApiException as err:
+                if err.status in (401, 403):
+                    raise
+                failures += 1
+                self._lease_failed(err, failures, on_error)
+                if self._sleep_interruptibly(1.0, stop):
+                    break
+                continue
+            except Exception as err:  # noqa: BLE001 - transport-level failure
+                failures += 1
+                self._lease_failed(err, failures, on_error)
+                if self._sleep_interruptibly(1.0, stop):
+                    break
+                continue
+            for lease in leased:
+                self._run_one(lease, handlers, lease_secs)
+        _logger.info("worker stopped")
+
+    def _lease_failed(self, err, failures, on_error) -> None:
+        if on_error is not None:
+            on_error(err)
+        elif failures == 1 or failures % 30 == 0:
+            _logger.warning("lease failed (%d consecutive): %s", failures, err)
+
+    @staticmethod
+    def _sleep_interruptibly(seconds: float, stop: Optional["threading.Event"]) -> bool:
+        """Sleep; returns True if ``stop`` fired."""
+        if stop is None:
+            time.sleep(seconds)
+            return False
+        return stop.wait(seconds)
+
+    def _run_one(self, lease, handlers, lease_secs: int) -> None:
+        job = lease.job
+        handler = handlers.get(job.task_name)
+        if handler is None:
+            self._report(
+                job.id,
+                FailJobRequest(
+                    lease_token=lease.lease_token,
+                    error="no worker handler for task '" + job.task_name + "'",
+                    retryable=False,
+                ),
+            )
+            return
+
+        ctx = WorkerContext()
+        hb_done = threading.Event()
+        hb = threading.Thread(
+            target=self._heartbeat_loop,
+            args=(job.id, lease.lease_token, lease_secs, ctx, hb_done),
+            daemon=True,
+        )
+        hb.start()
+
+        # Handler outcome and outcome *reporting* are separate concerns: a
+        # reporting error must never be re-reported as a job failure.
+        outcome_error: Optional[BaseException] = None
+        result: Dict[str, Any] = {}
+        try:
+            result = self._call_handler(handler, job, ctx) or {}
+        except Exception as err:  # noqa: BLE001 - the engine applies policy
+            outcome_error = err
+        finally:
+            hb_done.set()
+            hb.join(timeout=5)
+
+        if ctx.cancelled:
+            return  # the server owns the outcome
+
+        if outcome_error is None:
+            self._report(job.id, CompleteJobRequest(lease_token=lease.lease_token, result=result))
+        else:
+            retryable = getattr(outcome_error, "retryable", True) is not False
+            self._report(
+                job.id,
+                FailJobRequest(
+                    lease_token=lease.lease_token,
+                    error=str(outcome_error) or type(outcome_error).__name__,
+                    retryable=retryable,
+                ),
+            )
+
+    @staticmethod
+    def _call_handler(handler, job, ctx):
+        """Call ``handler(job)`` or ``handler(job, ctx)`` by arity."""
+        try:
+            params = [
+                p
+                for p in inspect.signature(handler).parameters.values()
+                if p.kind in (p.POSITIONAL_ONLY, p.POSITIONAL_OR_KEYWORD)
+            ]
+            wants_ctx = len(params) >= 2
+        except (TypeError, ValueError):
+            wants_ctx = False
+        return handler(job, ctx) if wants_ctx else handler(job)
+
+    def _report(self, job_id: str, request) -> None:
+        try:
+            if isinstance(request, CompleteJobRequest):
+                self.worker.complete_job(job_id, request)
+            else:
+                self.worker.fail_job(job_id, request)
+        except Exception as err:  # noqa: BLE001 - lease expiry redelivers
+            _logger.warning(
+                "failed to report job %s outcome; the lease will expire and the engine redelivers: %s",
+                job_id,
+                err,
+            )
+
+    def _heartbeat_loop(self, job_id, lease_token, lease_secs, ctx, done) -> None:
+        interval = max(1.0, lease_secs / 2.0)
+        while not done.wait(interval):
+            try:
+                status = self.worker.heartbeat_job(
+                    job_id,
+                    HeartbeatRequest(lease_token=lease_token, extend_secs=lease_secs),
+                ).status
+                if status != "running":
+                    ctx._lost.set()
+                    return
+            except ApiException as err:
+                if err.status == 409:
+                    ctx._lost.set()
+                    return
+            except Exception:  # noqa: BLE001 - transient; next tick retries
+                pass
+
     # --- internal -----------------------------------------------------------
 
     @staticmethod

{queueflow-0.1.0 → queueflow-0.2.0}/queueflow.egg-info/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: queueflow
-Version: 0.1.0
+Version: 0.2.0
 Summary: QueueFlow API
-Home-page: https://github.com/queueflow/queueflow-sdk-python
+Home-page: https://github.com/elision-labs/queueflow-sdk-python
 Author: QueueFlow
 Author-email: team@queueflow.dev
 License: MIT

{queueflow-0.1.0 → queueflow-0.2.0}/setup.py

@@ -21,7 +21,7 @@ from setuptools import setup, find_packages  # noqa: H301
 # prerequisite: setuptools
 # http://pypi.python.org/pypi/setuptools
 NAME = "queueflow"
-VERSION = "0.1.0"
+VERSION = "0.2.0"
 PYTHON_REQUIRES = ">= 3.8"
 REQUIRES = [
     "urllib3 >= 1.25.3, < 3.0.0",
@@ -36,7 +36,7 @@ setup(
     description="QueueFlow API",
     author="QueueFlow",
     author_email="team@queueflow.dev",
-    url="https://github.com/queueflow/queueflow-sdk-python",
+    url="https://github.com/elision-labs/queueflow-sdk-python",
     keywords=["OpenAPI", "OpenAPI-Generator", "QueueFlow API"],
     install_requires=REQUIRES,
     packages=find_packages(exclude=["test", "tests"]),

{queueflow-0.1.0 → queueflow-0.2.0}/test/test_facade.py

@@ -265,3 +265,162 @@ class TestWorkflows(unittest.TestCase):
 
 if __name__ == "__main__":
     unittest.main()
+
+
+# --- worker runtime ----------------------------------------------------------
+
+import threading
+import time as _time
+
+from queueflow.exceptions import ApiException
+from queueflow.facade import NonRetryableError
+
+
+def lease(task: str = "echo", job_id: str = "j1", token: str = "tok-1") -> SimpleNamespace:
+    return SimpleNamespace(
+        job=SimpleNamespace(id=job_id, task_name=task, payload={}), lease_token=token
+    )
+
+
+class FakeWorkerApi:
+    """Serves a scripted list of leases, then sets `stop` so run_worker exits."""
+
+    def __init__(
+        self,
+        leases: Optional[List[SimpleNamespace]] = None,
+        heartbeat_status: str = "running",
+        lease_error: Optional[Exception] = None,
+        complete_error: Optional[Exception] = None,
+    ) -> None:
+        self.pending = list(leases or [])
+        self.heartbeat_status = heartbeat_status
+        self.lease_error = lease_error
+        self.complete_error = complete_error
+        self.completes: List[Any] = []
+        self.fails: List[Any] = []
+        self.heartbeats = 0
+        self.stop = threading.Event()
+
+    def lease_jobs(self, queue: str, req: Any) -> Any:
+        if self.lease_error is not None:
+            err, self.lease_error = self.lease_error, None
+            raise err
+        if not self.pending:
+            self.stop.set()
+            return SimpleNamespace(jobs=[])
+        return SimpleNamespace(jobs=[self.pending.pop(0)])
+
+    def heartbeat_job(self, job_id: str, req: Any) -> Any:
+        self.heartbeats += 1
+        return SimpleNamespace(status=self.heartbeat_status)
+
+    def complete_job(self, job_id: str, req: Any) -> None:
+        if self.complete_error is not None:
+            raise self.complete_error
+        self.completes.append((job_id, req))
+
+    def fail_job(self, job_id: str, req: Any) -> None:
+        self.fails.append((job_id, req))
+
+
+def worker_client(api: FakeWorkerApi) -> QueueFlow:
+    qf = QueueFlow("http://qf.test", "test-token")
+    qf.worker = api
+    return qf
+
+
+class TestWorkerRuntime(unittest.TestCase):
+    def run_until_drained(self, api: FakeWorkerApi, handlers: Dict[str, Any], **kw: Any) -> None:
+        worker_client(api).run_worker("q", handlers, stop=api.stop, wait_secs=0, **kw)
+
+    def test_happy_path_completes_with_the_handler_result(self) -> None:
+        api = FakeWorkerApi([lease()])
+        self.run_until_drained(api, {"echo": lambda job: {"ok": job.id}})
+        self.assertEqual(len(api.completes), 1)
+        job_id, req = api.completes[0]
+        self.assertEqual(job_id, "j1")
+        self.assertEqual(req.lease_token, "tok-1")
+        self.assertEqual(req.result, {"ok": "j1"})
+        self.assertEqual(api.fails, [])
+
+    def test_none_result_becomes_an_empty_dict(self) -> None:
+        api = FakeWorkerApi([lease()])
+        self.run_until_drained(api, {"echo": lambda job: None})
+        self.assertEqual(api.completes[0][1].result, {})
+
+    def test_a_raising_handler_fails_retryably(self) -> None:
+        def boom(job):
+            raise RuntimeError("gateway 503")
+
+        api = FakeWorkerApi([lease()])
+        self.run_until_drained(api, {"echo": boom})
+        self.assertEqual(api.completes, [])
+        _, req = api.fails[0]
+        self.assertIn("gateway 503", req.error)
+        self.assertNotEqual(req.retryable, False)
+
+    def test_non_retryable_error_dead_letters(self) -> None:
+        def reject(job):
+            raise NonRetryableError("fraud")
+
+        api = FakeWorkerApi([lease()])
+        self.run_until_drained(api, {"echo": reject})
+        _, req = api.fails[0]
+        self.assertEqual(req.retryable, False)
+
+    def test_unknown_task_fails_non_retryably(self) -> None:
+        api = FakeWorkerApi([lease(task="ghost")])
+        self.run_until_drained(api, {"echo": lambda job: {}})
+        _, req = api.fails[0]
+        self.assertEqual(req.retryable, False)
+        self.assertIn("ghost", req.error)
+
+    def test_auth_errors_raise_instead_of_spinning(self) -> None:
+        api = FakeWorkerApi(lease_error=ApiException(status=403, reason="forbidden"))
+        with self.assertRaises(ApiException):
+            self.run_until_drained(api, {})
+
+    def test_transient_lease_errors_back_off_and_continue(self) -> None:
+        api = FakeWorkerApi([lease()], lease_error=RuntimeError("connection reset"))
+        seen: List[Exception] = []
+        self.run_until_drained(api, {"echo": lambda job: {}}, on_error=seen.append)
+        self.assertEqual(len(seen), 1)
+        self.assertEqual(len(api.completes), 1)
+
+    def test_two_argument_handlers_receive_a_context(self) -> None:
+        contexts: List[Any] = []
+
+        def handler(job, ctx):
+            contexts.append(ctx)
+            return {}
+
+        api = FakeWorkerApi([lease()])
+        self.run_until_drained(api, {"echo": handler})
+        self.assertEqual(len(contexts), 1)
+        self.assertFalse(contexts[0].cancelled)
+
+    def test_lost_lease_abandons_reporting_and_cancels_the_context(self) -> None:
+        observed = {"cancelled_seen": False}
+
+        def slow(job, ctx):
+            # Outlive one 1s heartbeat tick (lease_secs=2); the fake reports
+            # the job cancelled, which must flip ctx.cancelled.
+            deadline = _time.monotonic() + 4.0
+            while _time.monotonic() < deadline:
+                if ctx.cancelled:
+                    observed["cancelled_seen"] = True
+                    return {}
+                _time.sleep(0.05)
+            return {}
+
+        api = FakeWorkerApi([lease()], heartbeat_status="cancelled")
+        self.run_until_drained(api, {"echo": slow}, lease_secs=2)
+        self.assertTrue(observed["cancelled_seen"])
+        self.assertGreaterEqual(api.heartbeats, 1)
+        self.assertEqual(api.completes, [])
+        self.assertEqual(api.fails, [])
+
+    def test_a_failed_report_is_never_converted_into_a_job_failure(self) -> None:
+        api = FakeWorkerApi([lease()], complete_error=RuntimeError("engine restarting"))
+        self.run_until_drained(api, {"echo": lambda job: {"ok": True}})
+        self.assertEqual(api.fails, [])  # lease expiry redelivers; no fail() call