taskferry-procrastinate 0.2.0__tar.gz

taskferry_procrastinate-0.2.0/.gitignore

@@ -0,0 +1,34 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+
+# Build artifacts
+dist/
+build/
+*.whl
+*.tar.gz
+
+# Environments
+.venv/
+.venv-*/
+.env
+
+# Tooling caches
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+coverage.xml
+node_modules/
+
+# uv
+uv.lock
+
+# OS / editors
+.DS_Store
+.idea/
+.vscode/
+site/

taskferry_procrastinate-0.2.0/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+All notable changes to `taskferry-procrastinate` are documented here.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
+this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [0.2.0] — 2026-07-26
+
+### Added
+
+- Initial release, extracted from the Django-coupled backends of `taskferry-django` 0.1
+  and rebuilt against the framework-agnostic Taskferry ports.

taskferry_procrastinate-0.2.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   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.

taskferry_procrastinate-0.2.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.5
+Name: taskferry-procrastinate
+Version: 0.2.0
+Summary: Procrastinate task backend for Taskferry — PostgreSQL-backed task execution.
+Project-URL: Homepage, https://github.com/xiidigital/taskferry
+Project-URL: Documentation, https://taskferry.dev
+Project-URL: Source, https://github.com/xiidigital/taskferry
+Author: Taskferry authors
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: postgresql,procrastinate,taskferry,tasks
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: taskferry<0.3,>=0.2
+Provides-Extra: procrastinate
+Requires-Dist: procrastinate>=2.0; extra == 'procrastinate'
+Description-Content-Type: text/markdown
+
+# taskferry-procrastinate
+
+Run [Taskferry](https://github.com/xiidigital/taskferry) tasks on
+[Procrastinate](https://procrastinate.readthedocs.io) — a durable, PostgreSQL-backed
+task engine.
+
+```mermaid
+flowchart LR
+    APP["Application"]
+    TP["Taskferry"]
+    AD["taskferry-procrastinate"]
+    PRO["Procrastinate"]
+    PG["PostgreSQL"]
+
+    APP --> TP --> AD --> PRO --> PG
+```
+
+Taskferry does not implement a queue, a worker, job reservation or retries.
+Procrastinate already does all of that, correctly, on PostgreSQL. This package is
+the translation layer between the two — and nothing else.
+
+## Install
+
+```bash
+pip install 'taskferry-procrastinate[procrastinate]'
+```
+
+PostgreSQL becomes a dependency of your deployment only once you select this
+backend. `taskferry` itself has no dependencies at all.
+
+## Submitting
+
+```python
+from taskferry import Taskferry
+
+runtime = Taskferry.from_mapping(
+    {
+        "backends": {"pg": {"factory": "procrastinate", "app": "myapp.tasks:app"}},
+        "defaults": {"task": "pg"},
+    }
+)
+
+runtime.tasks.submit("myapp.tasks:refresh_metadata", 42, queue="metadata")
+```
+
+## Executing
+
+Register the dispatcher once, then run Procrastinate's own worker:
+
+```python
+# myapp/tasks.py
+from procrastinate import App, PsycopgConnector
+from taskferry import FunctionRegistry
+from taskferry_procrastinate import register_dispatcher
+
+app = App(connector=PsycopgConnector(conninfo="postgresql://..."))
+
+# An allowlist matters: task names arrive from the queue.
+register_dispatcher(app, registry=FunctionRegistry(allowed_modules=["myapp"]))
+```
+
+```bash
+procrastinate --app=myapp.tasks.app worker
+```
+
+## Capabilities
+
+| Capability | Supported | How |
+| ---------- | :-------: | --- |
+| `SUBMIT` | yes | `defer()` |
+| `STATE` | yes | job manager |
+| `CANCEL` | yes | `cancel_job_by_id` |
+| `DELAY` | yes | `schedule_at` |
+| `PRIORITY` | yes | native job priority |
+| `RETRY` | yes | engine-owned, via the retry signal |
+| `DEDUPLICATION` | yes | `queueing_lock` |
+| `RESULT` | **no** | Procrastinate stores no return values |
+
+`RESULT` is absent because Procrastinate genuinely does not keep results.
+Taskferry raises `UnsupportedCapability` rather than inventing a results table —
+building queue features is precisely what this project exists not to do.
+
+## Backend options
+
+```python
+TaskSpec(
+    task="myapp.tasks:reindex",
+    backend_options=BackendOptions(
+        {
+            "procrastinate": {
+                "lock": "reindex-42",  # serialise jobs against a key
+                "queueing_lock": "reindex",  # refuse a duplicate while one is pending
+            }
+        }
+    ),
+)
+```
+
+## License
+
+Apache-2.0.

taskferry_procrastinate-0.2.0/README.md

@@ -0,0 +1,101 @@
+# taskferry-procrastinate
+
+Run [Taskferry](https://github.com/xiidigital/taskferry) tasks on
+[Procrastinate](https://procrastinate.readthedocs.io) — a durable, PostgreSQL-backed
+task engine.
+
+```mermaid
+flowchart LR
+    APP["Application"]
+    TP["Taskferry"]
+    AD["taskferry-procrastinate"]
+    PRO["Procrastinate"]
+    PG["PostgreSQL"]
+
+    APP --> TP --> AD --> PRO --> PG
+```
+
+Taskferry does not implement a queue, a worker, job reservation or retries.
+Procrastinate already does all of that, correctly, on PostgreSQL. This package is
+the translation layer between the two — and nothing else.
+
+## Install
+
+```bash
+pip install 'taskferry-procrastinate[procrastinate]'
+```
+
+PostgreSQL becomes a dependency of your deployment only once you select this
+backend. `taskferry` itself has no dependencies at all.
+
+## Submitting
+
+```python
+from taskferry import Taskferry
+
+runtime = Taskferry.from_mapping(
+    {
+        "backends": {"pg": {"factory": "procrastinate", "app": "myapp.tasks:app"}},
+        "defaults": {"task": "pg"},
+    }
+)
+
+runtime.tasks.submit("myapp.tasks:refresh_metadata", 42, queue="metadata")
+```
+
+## Executing
+
+Register the dispatcher once, then run Procrastinate's own worker:
+
+```python
+# myapp/tasks.py
+from procrastinate import App, PsycopgConnector
+from taskferry import FunctionRegistry
+from taskferry_procrastinate import register_dispatcher
+
+app = App(connector=PsycopgConnector(conninfo="postgresql://..."))
+
+# An allowlist matters: task names arrive from the queue.
+register_dispatcher(app, registry=FunctionRegistry(allowed_modules=["myapp"]))
+```
+
+```bash
+procrastinate --app=myapp.tasks.app worker
+```
+
+## Capabilities
+
+| Capability | Supported | How |
+| ---------- | :-------: | --- |
+| `SUBMIT` | yes | `defer()` |
+| `STATE` | yes | job manager |
+| `CANCEL` | yes | `cancel_job_by_id` |
+| `DELAY` | yes | `schedule_at` |
+| `PRIORITY` | yes | native job priority |
+| `RETRY` | yes | engine-owned, via the retry signal |
+| `DEDUPLICATION` | yes | `queueing_lock` |
+| `RESULT` | **no** | Procrastinate stores no return values |
+
+`RESULT` is absent because Procrastinate genuinely does not keep results.
+Taskferry raises `UnsupportedCapability` rather than inventing a results table —
+building queue features is precisely what this project exists not to do.
+
+## Backend options
+
+```python
+TaskSpec(
+    task="myapp.tasks:reindex",
+    backend_options=BackendOptions(
+        {
+            "procrastinate": {
+                "lock": "reindex-42",  # serialise jobs against a key
+                "queueing_lock": "reindex",  # refuse a duplicate while one is pending
+            }
+        }
+    ),
+)
+```
+
+## License
+
+Apache-2.0.

taskferry_procrastinate-0.2.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "taskferry-procrastinate"
+version = "0.2.0"
+description = "Procrastinate task backend for Taskferry — PostgreSQL-backed task execution."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+authors = [{ name = "Taskferry authors" }]
+keywords = ["taskferry", "procrastinate", "postgresql", "tasks"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = ["taskferry>=0.2,<0.3"]
+
+[project.optional-dependencies]
+procrastinate = ["procrastinate>=2.0"]
+
+[project.entry-points."taskferry.backends"]
+procrastinate = "taskferry_procrastinate:make_backend"
+
+[project.urls]
+Homepage = "https://github.com/xiidigital/taskferry"
+Documentation = "https://taskferry.dev"
+Source = "https://github.com/xiidigital/taskferry"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/taskferry_procrastinate"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "README.md", "CHANGELOG.md", "LICENSE"]

taskferry_procrastinate-0.2.0/src/taskferry_procrastinate/__init__.py

@@ -0,0 +1,74 @@
+"""Taskferry on Procrastinate — a PostgreSQL-backed task engine.
+
+```mermaid
+flowchart LR
+    APP["Application"]
+    TP["Taskferry"]
+    AD["taskferry_procrastinate"]
+    PRO["Procrastinate"]
+    PG["PostgreSQL"]
+
+    APP --> TP --> AD --> PRO --> PG
+```
+
+Procrastinate already solves the hard parts — a durable PostgreSQL queue, worker
+processes, job reservation with `FOR UPDATE SKIP LOCKED`, retries, periodic
+tasks. Taskferry does not reimplement any of that and does not want to. This
+adapter translates a :class:`~taskferry.specs.TaskSpec` into a deferred
+Procrastinate job and translates Procrastinate's states back.
+
+PostgreSQL becomes a dependency of your deployment only when this adapter is
+selected. ``taskferry`` itself never imports ``procrastinate`` or a database
+driver, and an architectural test enforces that.
+
+Two sides
+---------
+
+**Submitting** (web process, CLI, anything)::
+
+    from taskferry import Taskferry
+
+    runtime = Taskferry.from_mapping({
+        "backends": {"pg": {"factory": "procrastinate", "app": "myapp.tasks:app"}},
+        "defaults": {"task": "pg"},
+    })
+    runtime.tasks.submit("myapp.tasks:refresh_metadata", 42, queue="metadata")
+
+**Executing** (worker process) — register the dispatcher once on your app::
+
+    from procrastinate import App, PsycopgConnector
+    from taskferry_procrastinate import register_dispatcher
+
+    app = App(connector=PsycopgConnector(...))
+    register_dispatcher(app)
+
+then run Procrastinate's own worker (``procrastinate worker``). Taskferry does not
+supply a worker: that is exactly the sort of thing it delegates.
+
+What crosses the wire is the portable message — a ``"package.module:function"``
+name plus JSON arguments — never a pickled callable. See
+:mod:`taskferry.functions`.
+"""
+
+from __future__ import annotations
+
+from .backend import (
+    DEFAULT_DISPATCH_TASK,
+    ProcrastinateTaskBackend,
+    make_backend,
+    map_status,
+)
+from .worker import build_message, execute_message, register_dispatcher
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "DEFAULT_DISPATCH_TASK",
+    "ProcrastinateTaskBackend",
+    "__version__",
+    "build_message",
+    "execute_message",
+    "make_backend",
+    "map_status",
+    "register_dispatcher",
+]

taskferry_procrastinate-0.2.0/src/taskferry_procrastinate/backend.py

@@ -0,0 +1,336 @@
+"""The Procrastinate `TaskBackend`.
+
+Translation, in both directions, and nothing else.
+
+```mermaid
+flowchart LR
+    subgraph Taskferry
+        TS["TaskSpec<br/>queue · priority · delay · retry · idempotency_key"]
+        EX["Execution<br/>ExecutionState"]
+    end
+
+    subgraph Procrastinate
+        DEF["configure_task(...).defer()"]
+        JOB["job status<br/>todo · doing · succeeded · failed · cancelled"]
+    end
+
+    TS --> DEF
+    JOB --> EX
+```
+
+Capabilities are advertised from what Procrastinate genuinely does:
+
+* ``DELAY`` — ``schedule_at`` / ``schedule_in``;
+* ``PRIORITY`` — native job priority;
+* ``RETRY`` — the engine owns retries. The portable policy travels in the
+  message and the dispatcher turns a failure into Procrastinate's own retry
+  signal, so the job is genuinely re-queued by Procrastinate with the requested
+  delay. Taskferry never loops in-process pretending to retry;
+* ``DEDUPLICATION`` — via ``queueing_lock``, which really does refuse a second
+  job while the first is pending;
+* ``STATE`` — through the job manager.
+
+``RESULT`` is **not** advertised. Procrastinate is fire-and-forget by design: it
+does not store a job's return value. Claiming otherwise here would mean inventing
+a results table, which is a queue feature, and building queue features is the
+thing this project exists not to do. Applications that need results write them
+where they belong — the database row the task updated, an object store, a cache.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Any
+
+from taskferry.capabilities import Capability, CapabilitySet
+from taskferry.core.provider import ProviderMetadata
+from taskferry.errors import ConfigurationError, ExecutionNotFound, SubmissionError
+from taskferry.execution import (
+    Execution,
+    ExecutionId,
+    ExecutionKind,
+    ExecutionState,
+    new_execution_id,
+)
+from taskferry.ports import BaseBackend
+from taskferry.specs import ExecutionSpec, TaskSpec
+from taskferry.tracking import ExternalIdIndex, is_digits
+
+from .message import build_message
+
+DEFAULT_DISPATCH_TASK = "taskferry:dispatch"
+"""Name of the single Procrastinate task that runs every Taskferry message."""
+
+PROCRASTINATE_CAPABILITIES = frozenset(
+    {
+        Capability.SUBMIT,
+        Capability.STATE,
+        Capability.CANCEL,
+        Capability.DELAY,
+        Capability.PRIORITY,
+        Capability.RETRY,
+        Capability.DEDUPLICATION,
+    }
+)
+
+#: Procrastinate job status -> portable state. ``aborting``/``aborted`` appear in
+#: newer releases; both map to the Taskferry state that describes what an operator
+#: actually sees, not the internal step.
+_STATUS_MAP: dict[str, ExecutionState] = {
+    "todo": ExecutionState.QUEUED,
+    "doing": ExecutionState.RUNNING,
+    "succeeded": ExecutionState.SUCCEEDED,
+    "failed": ExecutionState.FAILED,
+    "cancelled": ExecutionState.CANCELLED,
+    "aborting": ExecutionState.RUNNING,
+    "aborted": ExecutionState.CANCELLED,
+}
+
+
+def map_status(status: object) -> ExecutionState:
+    """Map a Procrastinate job status to a portable state.
+
+    Pure, so it is unit-testable without a database. An unrecognised status maps
+    to ``UNKNOWN`` rather than to a guess — a new Procrastinate release adding a
+    status must not make Taskferry report something false.
+    """
+    if status is None:
+        return ExecutionState.UNKNOWN
+    key = getattr(status, "value", status)
+    return _STATUS_MAP.get(str(key).lower(), ExecutionState.UNKNOWN)
+
+
+class ProcrastinateTaskBackend(BaseBackend):
+    """Defers Taskferry tasks as Procrastinate jobs.
+
+    Args:
+        app: A ``procrastinate.App``, or a ``"module:attribute"`` string resolved
+            on first use. A string keeps this backend constructible in a process
+            that has not yet configured its database connection.
+        dispatch_task: Name of the registered dispatcher task. Only change it if
+            you registered the dispatcher under a different name.
+        default_lock: ``lock`` applied when a spec does not set one. Procrastinate
+            serialises jobs sharing a lock, which is how you stop two workers
+            touching the same row.
+
+    Backend options, under the ``"procrastinate"`` namespace::
+
+        TaskSpec(
+            task="myapp.tasks:reindex",
+            backend_options=BackendOptions({"procrastinate": {
+                "lock": "reindex-42",        # serialise against this key
+                "queueing_lock": "reindex",  # refuse a duplicate while pending
+            }}),
+        )
+
+    Thread-safe once constructed: it holds a Procrastinate ``App``, which is
+    designed to be shared, and no mutable state of its own.
+    """
+
+    def __init__(
+        self,
+        *,
+        app: Any = None,
+        dispatch_task: str = DEFAULT_DISPATCH_TASK,
+        default_lock: str | None = None,
+        name: str = "procrastinate",
+        tracked_ids: int = 10_000,
+    ) -> None:
+        self._app = app
+        self._dispatch_task = dispatch_task
+        self._default_lock = default_lock
+        self._name = name
+        # Procrastinate knows nothing about Taskferry ids, so remember the
+        # pairing for the executions this process submitted; a bare numeric id
+        # from a dashboard is accepted too.
+        self._ids = ExternalIdIndex(capacity=tracked_ids, recognises=is_digits)
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    @property
+    def kind(self) -> ExecutionKind:
+        return ExecutionKind.TASK
+
+    @property
+    def capabilities(self) -> CapabilitySet:
+        return CapabilitySet(PROCRASTINATE_CAPABILITIES, provider=self._name)
+
+    # -- the app ---------------------------------------------------------------- #
+    def app(self) -> Any:
+        """The Procrastinate ``App``, resolving a dotted path on first use."""
+        if self._app is None:
+            raise ConfigurationError(
+                f"{self._name!r} needs a procrastinate App: pass app=<App> or "
+                "app='myapp.tasks:app' in the backend options"
+            )
+        if isinstance(self._app, str):
+            self._app = _import_attribute(self._app)
+        return self._app
+
+    # -- submission --------------------------------------------------------------- #
+    def _submit(self, spec: ExecutionSpec) -> Execution:
+        assert isinstance(spec, TaskSpec)
+        # Resolve the app first, outside the try below. A missing or unresolvable
+        # App is a ConfigurationError and must stay one — reporting it as "the
+        # engine refused the submission" sends whoever is debugging to look at
+        # PostgreSQL when the problem is a settings file.
+        app = self.app()
+        options = spec.options_for("procrastinate")
+        deferrer_kwargs: dict[str, Any] = {
+            "name": self._dispatch_task,
+            "queue": spec.queue,
+            "priority": spec.priority,
+            "schedule_at": spec.scheduled_for(),
+        }
+
+        lock = options.get("lock", self._default_lock)
+        if lock is not None:
+            deferrer_kwargs["lock"] = str(lock)
+
+        # An idempotency key maps onto queueing_lock, which is Procrastinate's
+        # real mechanism for "do not enqueue this twice while one is pending".
+        # It is honest deduplication, not an exactly-once promise.
+        queueing_lock = options.get("queueing_lock", spec.idempotency_key)
+        if queueing_lock is not None:
+            deferrer_kwargs["queueing_lock"] = str(queueing_lock)
+
+        for key, value in options.items():
+            if key not in {"lock", "queueing_lock"}:
+                deferrer_kwargs[key] = value
+
+        message = build_message(spec)
+        try:
+            deferrer = app.configure_task(**deferrer_kwargs)
+            job_id = deferrer.defer(message=message)
+        except Exception as exc:
+            raise SubmissionError(
+                f"procrastinate could not defer {spec.task!r} on queue {spec.queue!r}: {exc}",
+                backend=self._name,
+            ) from exc
+
+        now = datetime.now(UTC)
+        execution_id = new_execution_id(ExecutionKind.TASK)
+        self._ids.remember(str(execution_id), str(job_id))
+        return Execution(
+            id=execution_id,
+            kind=ExecutionKind.TASK,
+            backend=self._name,
+            state=ExecutionState.QUEUED,
+            name=spec.name,
+            created_at=now,
+            external_id=str(job_id),
+            correlation=spec.correlation,
+            provider_metadata=ProviderMetadata(
+                provider="postgres",
+                provider_id=str(job_id),
+                resource=f"queue:{spec.queue}",
+                labels=dict(spec.labels),
+            ),
+            metadata={"queue": spec.queue, "procrastinate_job_id": str(job_id)},
+        )
+
+    # -- observation ---------------------------------------------------------------- #
+    def _get(self, execution_id: ExecutionId) -> Execution:
+        """Look the job up by the Procrastinate id recorded at submission.
+
+        Taskferry ids are Taskferry's; Procrastinate never sees one. So ``get``
+        accepts either — a Taskferry id when this process submitted it, or the
+        engine's own numeric id, which is what an operator reads off a dashboard.
+        """
+        job = self._find_job(str(execution_id))
+        if job is None:
+            raise ExecutionNotFound(
+                f"procrastinate has no job {execution_id!r}; pass the procrastinate job id "
+                "when the execution was submitted by another process",
+                backend=self._name,
+            )
+        return self._execution_from_job(job, execution_id)
+
+    def _find_job(self, execution_id: str) -> Any:
+        numeric = self._ids.resolve(execution_id)
+        if numeric is None:
+            return None
+        manager = getattr(self.app(), "job_manager", None)
+        if manager is None:  # pragma: no cover - very old procrastinate
+            raise ExecutionNotFound(
+                "this procrastinate App has no job_manager, so state cannot be read",
+                backend=self._name,
+            )
+        jobs = list(manager.list_jobs(id=int(numeric)))
+        return jobs[0] if jobs else None
+
+    def _execution_from_job(self, job: Any, execution_id: ExecutionId) -> Execution:
+        return Execution(
+            id=execution_id,
+            kind=ExecutionKind.TASK,
+            backend=self._name,
+            state=map_status(getattr(job, "status", None)),
+            name=str(getattr(job, "task_name", "") or ""),
+            external_id=str(getattr(job, "id", "")),
+            attempt=int(getattr(job, "attempts", 0) or 0) + 1,
+            provider_metadata=ProviderMetadata(
+                provider="postgres",
+                provider_id=str(getattr(job, "id", "")),
+                resource=f"queue:{getattr(job, 'queue_name', '')}",
+            ),
+            metadata={"queue": str(getattr(job, "queue_name", "") or "")},
+        )
+
+    def _cancel(self, execution_id: ExecutionId) -> Execution:
+        """Cancel through Procrastinate's own job manager.
+
+        A job that has already been picked up cannot be un-run; Procrastinate
+        reports that by refusing, and the refreshed state says what really
+        happened rather than claiming success.
+        """
+        numeric = self._ids.resolve(str(execution_id))
+        if numeric is None:
+            raise ExecutionNotFound(
+                f"{execution_id!r} was not submitted by this backend instance; pass the "
+                "procrastinate job id to cancel it from another process",
+                backend=self._name,
+            )
+        manager = self.app().job_manager
+        try:
+            manager.cancel_job_by_id(int(numeric))
+        except Exception as exc:
+            raise SubmissionError(
+                f"procrastinate could not cancel job {numeric}: {exc}", backend=self._name
+            ) from exc
+        return self._get(execution_id)
+
+
+def _import_attribute(path: str) -> Any:
+    import importlib
+
+    module_path, sep, attr = path.partition(":")
+    if not sep:
+        module_path, _, attr = path.rpartition(".")
+    if not module_path or not attr:
+        raise ConfigurationError(f"invalid app reference {path!r}; expected 'module:attribute'")
+    try:
+        return getattr(importlib.import_module(module_path), attr)
+    except (ImportError, AttributeError) as exc:
+        raise ConfigurationError(f"cannot resolve procrastinate app {path!r}: {exc}") from exc
+
+
+def make_backend(**options: Any) -> ProcrastinateTaskBackend:
+    """Entry point for ``{"factory": "procrastinate", ...}`` configuration."""
+    return ProcrastinateTaskBackend(
+        app=options.get("app"),
+        dispatch_task=str(options.get("dispatch_task", DEFAULT_DISPATCH_TASK)),
+        default_lock=options.get("default_lock"),
+        name=str(options.get("name", "procrastinate")),
+        tracked_ids=int(options.get("tracked_ids", 10_000)),
+    )
+
+
+__all__ = [
+    "DEFAULT_DISPATCH_TASK",
+    "PROCRASTINATE_CAPABILITIES",
+    "ProcrastinateTaskBackend",
+    "make_backend",
+    "map_status",
+]

taskferry_procrastinate-0.2.0/src/taskferry_procrastinate/message.py

@@ -0,0 +1,60 @@
+"""The wire envelope, re-exported from the core.
+
+Every Taskferry transport carries the same JSON envelope — one function name, JSON
+arguments, correlation, retry intent. It lives in :mod:`taskferry.envelope` so
+that Procrastinate, Cloud Tasks, SQS, Service Bus and Dramatiq cannot drift apart
+on the format a worker has to understand.
+
+This module stays as the import path the adapter's own tests and docs use, and as
+the place to put anything genuinely Procrastinate-specific about the payload.
+There is currently nothing, which is the point.
+"""
+
+from __future__ import annotations
+
+from taskferry.envelope import (
+    ENVELOPE_VERSION,
+    Envelope,
+    build_envelope,
+    decode_retry,
+    encode_retry,
+    read_correlation,
+    read_envelope,
+)
+
+#: Historical aliases: this adapter shipped them before the envelope moved into
+#: the core. Kept so 0.2 adapter code and tests keep working.
+MESSAGE_VERSION = ENVELOPE_VERSION
+TaskferryMessage = Envelope
+build_message = build_envelope
+
+
+def check_version(message: object) -> None:
+    """Reject an envelope this worker does not understand.
+
+    Thin wrapper over :func:`taskferry.envelope.read_envelope` that raises
+    ``ValueError`` rather than ``SerializationError``, because a Procrastinate
+    worker treats any exception the same way and the narrower type reads better
+    in this adapter's own tests.
+    """
+    from taskferry.errors import SerializationError
+
+    try:
+        read_envelope(message)
+    except SerializationError as exc:
+        raise ValueError(str(exc)) from exc
+
+
+__all__ = [
+    "ENVELOPE_VERSION",
+    "MESSAGE_VERSION",
+    "Envelope",
+    "TaskferryMessage",
+    "build_envelope",
+    "build_message",
+    "check_version",
+    "decode_retry",
+    "encode_retry",
+    "read_correlation",
+    "read_envelope",
+]

taskferry_procrastinate-0.2.0/src/taskferry_procrastinate/worker.py

@@ -0,0 +1,156 @@
+"""The worker side — one Procrastinate task that runs every Taskferry message.
+
+```mermaid
+sequenceDiagram
+    participant PG as PostgreSQL
+    participant W as procrastinate worker
+    participant D as taskferry:dispatch
+    participant REG as FunctionRegistry
+    participant FN as your function
+
+    PG->>W: reserve job
+    W->>D: dispatch(message)
+    D->>REG: resolve "package.module:function"
+    REG-->>D: callable
+    D->>FN: call(*args, **kwargs)
+    FN-->>D: value (discarded — see below)
+    D-->>W: done
+    W->>PG: mark succeeded
+```
+
+Taskferry supplies **no worker**. You run ``procrastinate worker``; this module
+only registers the function that worker calls. Reservation, concurrency,
+shutdown, heartbeats and the listen/notify loop are Procrastinate's, and
+rebuilding any of them here would be exactly the mistake this project is
+organised to avoid.
+
+Security
+--------
+
+The dispatcher resolves a task *name* that arrived from the queue. If untrusted
+input can reach your queue, that resolution is an arbitrary-import primitive, so
+pass a :class:`~taskferry.functions.FunctionRegistry` configured with an
+allowlist::
+
+    registry = FunctionRegistry(allowed_modules=["myapp.tasks"])
+    register_dispatcher(app, registry=registry)
+
+With no registry the dispatcher builds a permissive one — convenient in
+development, and documented as something to tighten before production.
+
+Return values
+-------------
+
+The dispatcher returns whatever the task returned, but Procrastinate does not
+store it, and the backend does not advertise ``RESULT``. Write results where they
+belong instead of expecting the queue to keep them.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from taskferry.envelope import execute_envelope
+from taskferry.functions import FunctionRegistry
+from taskferry.retry import RetryPolicy
+
+from .message import TaskferryMessage, build_message, check_version, decode_retry
+
+logger = logging.getLogger("taskferry.procrastinate")
+
+DEFAULT_DISPATCH_TASK = "taskferry:dispatch"
+
+
+def execute_message(
+    message: TaskferryMessage,
+    *,
+    registry: FunctionRegistry | None = None,
+) -> Any:
+    """Resolve and run one Taskferry message. Pure of Procrastinate.
+
+    Kept independent of the engine so it can be unit-tested with a plain dict,
+    and reused by any other adapter that carries the same envelope.
+    """
+    check_version(message)
+    return execute_envelope(message, registry=registry)
+
+
+def register_dispatcher(
+    app: Any,
+    *,
+    name: str = DEFAULT_DISPATCH_TASK,
+    registry: FunctionRegistry | None = None,
+    **task_options: Any,
+) -> Any:
+    """Register the Taskferry dispatcher on a Procrastinate ``App``.
+
+    Call once, at import time, in the module your worker loads::
+
+        app = App(connector=PsycopgConnector(...))
+        register_dispatcher(app, registry=FunctionRegistry(allowed_modules=["myapp"]))
+
+    Args:
+        app: The Procrastinate ``App``.
+        name: Task name. Must match the backend's ``dispatch_task``.
+        registry: Where task names resolve. Give it an allowlist in production.
+        task_options: Forwarded to ``@app.task`` (``pass_context``, ``retry``...).
+
+    Returns:
+        The registered Procrastinate task.
+    """
+    task_options.setdefault("pass_context", True)
+
+    # The App is deliberately typed Any: procrastinate must not be a hard
+    # dependency of this package, so its decorator is untyped here.
+    @app.task(name=name, **task_options)  # type: ignore[untyped-decorator]
+    def _taskferry_dispatch(context: Any = None, *, message: TaskferryMessage) -> Any:
+        policy = decode_retry(message)
+        try:
+            return execute_message(message, registry=registry)
+        except Exception as exc:
+            attempt = _attempt_number(context)
+            if policy.should_retry(exc, attempt):
+                _request_engine_retry(policy, attempt, exc)
+            raise
+
+    return _taskferry_dispatch
+
+
+def _attempt_number(context: Any) -> int:
+    """1-based attempt count, read from the Procrastinate job context."""
+    job = getattr(context, "job", None)
+    attempts = getattr(job, "attempts", None)
+    return int(attempts) + 1 if isinstance(attempts, int) else 1
+
+
+def _request_engine_retry(policy: RetryPolicy, attempt: int, exc: Exception) -> None:
+    """Ask Procrastinate to re-queue this job, with the delay the policy asks for.
+
+    Raising Procrastinate's own retry exception means *Procrastinate* performs
+    the retry — a real re-queue with a real schedule — rather than this function
+    looping in the worker and holding a slot while it sleeps. That is the whole
+    point of :class:`~taskferry.retry.RetryOwner`: exactly one layer retries, and
+    here it is the engine.
+
+    If the installed Procrastinate does not expose the exception (very old, or a
+    future rename), the original error propagates and Procrastinate applies
+    whatever retry strategy the task was registered with. Guessing would be
+    worse than falling back to the engine's own default.
+    """
+    delay = policy.delay_for(attempt + 1)
+    try:
+        from procrastinate.exceptions import JobRetry
+    except ImportError:  # pragma: no cover - depends on the installed version
+        logger.debug("procrastinate.exceptions.JobRetry unavailable; leaving retry to the engine")
+        return
+    logger.info("requesting retry of attempt %d in %.1fs after %s", attempt, delay, exc)
+    raise JobRetry(delay) from exc
+
+
+__all__ = [
+    "DEFAULT_DISPATCH_TASK",
+    "build_message",
+    "execute_message",
+    "register_dispatcher",
+]