taskferry-celery 0.1.0__tar.gz

taskferry_celery-0.1.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_celery-0.1.0/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog — taskferry-celery
+
+Follows [Semantic Versioning](https://semver.org/); versions independently of the
+rest of the family.
+
+## [0.1.0]
+
+### Added
+
+- `CeleryTaskBackend` — sends Taskferry tasks to a Celery app via `send_task`,
+  translating `TaskSpec` (queue, priority, delay) out and Celery task state back.
+- Honest capabilities: submit, state, cancel, delay, priority, retry.
+  `result` and `deduplication` are deliberately not advertised.
+- Engine-owned retries via the dispatcher's `self.retry`.
+- `register_dispatcher` + `execute_message` worker side, with an optional
+  `FunctionRegistry` import allowlist.
+- Pure `map_state` status mapping and the shared JSON envelope.
+- `taskferry.backends` entry point (`celery`). Contract-tested with a fake app;
+  neither Celery nor a broker is required to run the tests.

taskferry_celery-0.1.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_celery-0.1.0/PKG-INFO

@@ -0,0 +1,87 @@
+Metadata-Version: 2.5
+Name: taskferry-celery
+Version: 0.1.0
+Summary: Celery task backend for Taskferry — enqueue Taskferry tasks onto a Celery app.
+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: celery,queue,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: celery
+Requires-Dist: celery>=5.3; extra == 'celery'
+Description-Content-Type: text/markdown
+
+# taskferry-celery
+
+A **Celery** task backend for [Taskferry](https://taskferry.dev). Enqueue Taskferry
+tasks onto a Celery app you already run; Taskferry supplies no worker and
+reimplements none of Celery.
+
+```bash
+pip install taskferry-celery[celery]
+```
+
+## Submitting
+
+```python
+from taskferry import Taskferry
+
+runtime = Taskferry.from_mapping(
+    {
+        "backends": {"cel": {"factory": "celery", "app": "myapp.celery:app"}},
+        "defaults": {"task": "cel"},
+    }
+)
+runtime.tasks.submit("myapp.tasks:refresh", 42, queue="metadata")
+```
+
+## Executing (worker)
+
+Register the dispatcher once, then run Celery's own worker:
+
+```python
+from celery import Celery
+from taskferry_celery import register_dispatcher
+from taskferry.functions import FunctionRegistry
+
+app = Celery("myapp", broker="redis://localhost:6379/0")
+register_dispatcher(app, registry=FunctionRegistry(allowed_modules=["myapp"]))
+```
+
+```bash
+celery -A myapp worker
+```
+
+## Capabilities (honest)
+
+| Advertised | Not advertised | Why not |
+| --- | --- | --- |
+| submit, state, cancel, delay, priority, retry | `result` | needs a configured result backend Taskferry can't see |
+| | `deduplication` | Celery has no native mechanism — an `idempotency_key` is rejected, not ignored |
+
+Retries are the **engine's**: the dispatcher raises Celery's own `self.retry`, so
+a failed task is genuinely re-queued with the requested countdown. Taskferry never
+loops in-process pretending to retry.
+
+`state` maps Celery's `PENDING/STARTED/SUCCESS/FAILURE/RETRY/REVOKED` onto the
+portable states. Note Celery reports `PENDING` for both a queued task and an
+unknown id; without a result backend the two are indistinguishable, and this
+adapter says so rather than guessing.
+
+Only JSON-safe arguments and a `"module:function"` name cross the wire — never a
+pickled callable.
+
+## License
+
+Apache-2.0.

taskferry_celery-0.1.0/README.md

@@ -0,0 +1,63 @@
+# taskferry-celery
+
+A **Celery** task backend for [Taskferry](https://taskferry.dev). Enqueue Taskferry
+tasks onto a Celery app you already run; Taskferry supplies no worker and
+reimplements none of Celery.
+
+```bash
+pip install taskferry-celery[celery]
+```
+
+## Submitting
+
+```python
+from taskferry import Taskferry
+
+runtime = Taskferry.from_mapping(
+    {
+        "backends": {"cel": {"factory": "celery", "app": "myapp.celery:app"}},
+        "defaults": {"task": "cel"},
+    }
+)
+runtime.tasks.submit("myapp.tasks:refresh", 42, queue="metadata")
+```
+
+## Executing (worker)
+
+Register the dispatcher once, then run Celery's own worker:
+
+```python
+from celery import Celery
+from taskferry_celery import register_dispatcher
+from taskferry.functions import FunctionRegistry
+
+app = Celery("myapp", broker="redis://localhost:6379/0")
+register_dispatcher(app, registry=FunctionRegistry(allowed_modules=["myapp"]))
+```
+
+```bash
+celery -A myapp worker
+```
+
+## Capabilities (honest)
+
+| Advertised | Not advertised | Why not |
+| --- | --- | --- |
+| submit, state, cancel, delay, priority, retry | `result` | needs a configured result backend Taskferry can't see |
+| | `deduplication` | Celery has no native mechanism — an `idempotency_key` is rejected, not ignored |
+
+Retries are the **engine's**: the dispatcher raises Celery's own `self.retry`, so
+a failed task is genuinely re-queued with the requested countdown. Taskferry never
+loops in-process pretending to retry.
+
+`state` maps Celery's `PENDING/STARTED/SUCCESS/FAILURE/RETRY/REVOKED` onto the
+portable states. Note Celery reports `PENDING` for both a queued task and an
+unknown id; without a result backend the two are indistinguishable, and this
+adapter says so rather than guessing.
+
+Only JSON-safe arguments and a `"module:function"` name cross the wire — never a
+pickled callable.
+
+## License
+
+Apache-2.0.

taskferry_celery-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "taskferry-celery"
+version = "0.1.0"
+description = "Celery task backend for Taskferry — enqueue Taskferry tasks onto a Celery app."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+authors = [{ name = "Taskferry authors" }]
+keywords = ["taskferry", "celery", "tasks", "queue"]
+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]
+celery = ["celery>=5.3"]
+
+[project.entry-points."taskferry.backends"]
+celery = "taskferry_celery: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_celery"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "README.md", "CHANGELOG.md", "LICENSE"]

taskferry_celery-0.1.0/src/taskferry_celery/__init__.py

@@ -0,0 +1,72 @@
+"""Taskferry on Celery — enqueue Taskferry tasks onto a Celery app.
+
+```mermaid
+flowchart LR
+    APP["Application"]
+    TP["Taskferry"]
+    AD["taskferry_celery"]
+    CEL["Celery"]
+    BRK["broker (Redis / RabbitMQ)"]
+
+    APP --> TP --> AD --> CEL --> BRK
+```
+
+Celery already solves the durable broker, the worker, prefetch and retries.
+Taskferry does not reimplement any of it: this adapter translates a
+:class:`~taskferry.specs.TaskSpec` into a Celery task and Celery's state back.
+``taskferry`` itself never imports ``celery`` — an architectural test enforces it —
+so Celery becomes a dependency of your deployment only when this adapter is
+selected.
+
+Two sides
+---------
+
+**Submitting** (web process, CLI, anything)::
+
+    from taskferry import Taskferry
+
+    runtime = Taskferry.from_mapping({
+        "backends": {"cel": {"factory": "celery", "app": "myapp.celery:app"}},
+        "defaults": {"task": "cel"},
+    })
+    runtime.tasks.submit("myapp.tasks:refresh", 42, queue="metadata")
+
+**Executing** (worker process) — register the dispatcher once on your app::
+
+    from celery import Celery
+    from taskferry_celery import register_dispatcher
+
+    app = Celery("myapp", broker="redis://localhost:6379/0")
+    register_dispatcher(app)
+
+then run Celery's own worker (``celery -A myapp worker``). Taskferry supplies no
+worker; that is exactly the sort of thing it delegates.
+
+What crosses the wire is the portable envelope — a ``"package.module:function"``
+name plus JSON arguments — never a pickled callable. See :mod:`taskferry.envelope`.
+"""
+
+from __future__ import annotations
+
+from .backend import (
+    CELERY_CAPABILITIES,
+    DEFAULT_DISPATCH_TASK,
+    CeleryTaskBackend,
+    make_backend,
+    map_state,
+)
+from .worker import build_message, execute_message, register_dispatcher
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "CELERY_CAPABILITIES",
+    "DEFAULT_DISPATCH_TASK",
+    "CeleryTaskBackend",
+    "__version__",
+    "build_message",
+    "execute_message",
+    "make_backend",
+    "map_state",
+    "register_dispatcher",
+]

taskferry_celery-0.1.0/src/taskferry_celery/backend.py

@@ -0,0 +1,278 @@
+"""The Celery ``TaskBackend``.
+
+Translation, in both directions, and nothing else. A :class:`~taskferry.specs.TaskSpec`
+becomes a Celery task sent to the ``taskferry:dispatch`` task; Celery's task state
+is translated back to a portable :class:`~taskferry.execution.ExecutionState`.
+
+```mermaid
+flowchart LR
+    subgraph Taskferry
+        TS["TaskSpec<br/>queue · priority · delay · retry"]
+        EX["Execution<br/>ExecutionState"]
+    end
+    subgraph Celery
+        SEND["app.send_task('taskferry:dispatch', ...)"]
+        ST["AsyncResult.state<br/>PENDING · STARTED · SUCCESS · FAILURE · RETRY · REVOKED"]
+    end
+    TS --> SEND
+    ST --> EX
+```
+
+Capabilities are advertised from what Celery genuinely does out of the box:
+
+* ``DELAY`` — ``eta`` / ``countdown``;
+* ``PRIORITY`` — native message priority (broker-dependent, but real);
+* ``RETRY`` — the engine owns retries; the dispatcher turns a failure into
+  Celery's own ``self.retry`` so the task is genuinely re-queued;
+* ``STATE`` — through ``AsyncResult``;
+* ``CANCEL`` — ``AsyncResult.revoke``.
+
+``RESULT`` is **not** advertised. Celery *can* store results, but only when a
+result backend is configured, and Taskferry will not claim a capability that
+depends on optional infrastructure it cannot see. ``DEDUPLICATION`` is not
+advertised either: Celery has no native mechanism for it, so a spec carrying an
+``idempotency_key`` is rejected here rather than accepted and ignored.
+
+A note on Celery's ``PENDING``: Celery reports ``PENDING`` both for a task that is
+genuinely queued *and* for a task id it has never heard of. Taskferry maps
+``PENDING`` to ``QUEUED`` and documents that it cannot distinguish the two without
+a result backend — an honest limitation, not a guess.
+"""
+
+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
+
+from .message import build_message
+
+DEFAULT_DISPATCH_TASK = "taskferry:dispatch"
+"""Name of the single Celery task that runs every Taskferry message."""
+
+CELERY_CAPABILITIES = frozenset(
+    {
+        Capability.SUBMIT,
+        Capability.STATE,
+        Capability.CANCEL,
+        Capability.DELAY,
+        Capability.PRIORITY,
+        Capability.RETRY,
+    }
+)
+
+#: Celery task state -> portable state. See the ``PENDING`` note in the module
+#: docstring. ``RETRY`` is a task waiting to be re-attempted by the engine, which
+#: an operator sees as still running.
+_STATE_MAP: dict[str, ExecutionState] = {
+    "PENDING": ExecutionState.QUEUED,
+    "RECEIVED": ExecutionState.QUEUED,
+    "STARTED": ExecutionState.RUNNING,
+    "RETRY": ExecutionState.RUNNING,
+    "SUCCESS": ExecutionState.SUCCEEDED,
+    "FAILURE": ExecutionState.FAILED,
+    "REVOKED": ExecutionState.CANCELLED,
+}
+
+
+def map_state(state: object) -> ExecutionState:
+    """Map a Celery task state to a portable state. Pure, unit-testable.
+
+    An unrecognised state maps to ``UNKNOWN`` rather than to a guess — a future
+    Celery state must not make Taskferry report something false.
+    """
+    if state is None:
+        return ExecutionState.UNKNOWN
+    return _STATE_MAP.get(str(state).upper(), ExecutionState.UNKNOWN)
+
+
+def _looks_like_celery_id(value: str) -> bool:
+    """Recognise a Celery task id (a uuid4 string) copied from a dashboard."""
+    parts = value.split("-")
+    return len(parts) == 5 and all(c in "0123456789abcdef-" for c in value.lower())
+
+
+class CeleryTaskBackend(BaseBackend):
+    """Sends Taskferry tasks to a Celery app.
+
+    Args:
+        app: A ``celery.Celery`` instance, or a ``"module:attribute"`` string
+            resolved on first use so the backend is constructible before the
+            broker connection is configured.
+        dispatch_task: Name of the registered dispatcher task. Must match the name
+            passed to :func:`~taskferry_celery.register_dispatcher`.
+        name: Backend name used in metadata and errors.
+
+    Backend options, under the ``"celery"`` namespace, pass straight to
+    ``send_task``::
+
+        TaskSpec(
+            task="myapp.tasks:reindex",
+            backend_options=BackendOptions({"celery": {"expires": 300}}),
+        )
+
+    Thread-safe once constructed: a Celery ``app`` is designed to be shared and
+    this backend keeps no mutable state beyond the id index.
+    """
+
+    def __init__(
+        self,
+        *,
+        app: Any = None,
+        dispatch_task: str = DEFAULT_DISPATCH_TASK,
+        name: str = "celery",
+        tracked_ids: int = 10_000,
+    ) -> None:
+        self._app = app
+        self._dispatch_task = dispatch_task
+        self._name = name
+        self._ids = ExternalIdIndex(capacity=tracked_ids, recognises=_looks_like_celery_id)
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    @property
+    def kind(self) -> ExecutionKind:
+        return ExecutionKind.TASK
+
+    @property
+    def capabilities(self) -> CapabilitySet:
+        return CapabilitySet(CELERY_CAPABILITIES, provider=self._name)
+
+    # -- the app ---------------------------------------------------------------- #
+    def app(self) -> Any:
+        """The Celery app, resolving a dotted path on first use."""
+        if self._app is None:
+            raise ConfigurationError(
+                f"{self._name!r} needs a celery app: pass app=<Celery> or "
+                "app='myapp.celery: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)
+        app = self.app()
+        options: dict[str, Any] = {
+            "queue": spec.queue,
+            "priority": spec.priority,
+        }
+        eta = spec.scheduled_for()
+        if eta is not None:
+            options["eta"] = eta
+        # Any celery-namespaced option passes straight through to send_task.
+        options.update(spec.options_for("celery"))
+
+        message = build_message(spec)
+        try:
+            async_result = app.send_task(
+                self._dispatch_task, kwargs={"message": message}, **options
+            )
+        except Exception as exc:
+            raise SubmissionError(
+                f"celery could not send {spec.task!r} on queue {spec.queue!r}: {exc}",
+                backend=self._name,
+            ) from exc
+
+        task_id = str(getattr(async_result, "id", "") or "")
+        execution_id = new_execution_id(ExecutionKind.TASK)
+        self._ids.remember(str(execution_id), task_id)
+        return Execution(
+            id=execution_id,
+            kind=ExecutionKind.TASK,
+            backend=self._name,
+            state=ExecutionState.QUEUED,
+            name=spec.name,
+            created_at=datetime.now(UTC),
+            external_id=task_id,
+            correlation=spec.correlation,
+            provider_metadata=ProviderMetadata(
+                provider="celery",
+                provider_id=task_id,
+                resource=f"queue:{spec.queue}",
+                labels=dict(spec.labels),
+            ),
+            metadata={"queue": spec.queue, "celery_task_id": task_id},
+        )
+
+    # -- observation ------------------------------------------------------------ #
+    def _result_handle(self, execution_id: ExecutionId) -> Any:
+        task_id = self._ids.resolve(str(execution_id))
+        if task_id is None:
+            raise ExecutionNotFound(
+                f"celery has no task {execution_id!r}; pass the celery task id when the "
+                "execution was submitted by another process",
+                backend=self._name,
+            )
+        return self.app().AsyncResult(task_id)
+
+    def _get(self, execution_id: ExecutionId) -> Execution:
+        async_result = self._result_handle(execution_id)
+        task_id = str(getattr(async_result, "id", "") or self._ids.resolve(str(execution_id)) or "")
+        return Execution(
+            id=execution_id,
+            kind=ExecutionKind.TASK,
+            backend=self._name,
+            state=map_state(getattr(async_result, "state", None)),
+            external_id=task_id,
+            provider_metadata=ProviderMetadata(provider="celery", provider_id=task_id),
+        )
+
+    def _cancel(self, execution_id: ExecutionId) -> Execution:
+        async_result = self._result_handle(execution_id)
+        try:
+            async_result.revoke()
+        except Exception as exc:
+            raise SubmissionError(
+                f"celery could not revoke {execution_id!r}: {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 celery app {path!r}: {exc}") from exc
+
+
+def make_backend(**options: Any) -> CeleryTaskBackend:
+    """Entry point for ``{"factory": "celery", ...}`` configuration."""
+    return CeleryTaskBackend(
+        app=options.get("app"),
+        dispatch_task=str(options.get("dispatch_task", DEFAULT_DISPATCH_TASK)),
+        name=str(options.get("name", "celery")),
+        tracked_ids=int(options.get("tracked_ids", 10_000)),
+    )
+
+
+__all__ = [
+    "CELERY_CAPABILITIES",
+    "DEFAULT_DISPATCH_TASK",
+    "CeleryTaskBackend",
+    "make_backend",
+    "map_state",
+]

taskferry_celery-0.1.0/src/taskferry_celery/message.py

@@ -0,0 +1,50 @@
+"""The wire envelope, re-exported from the core.
+
+Every Taskferry transport carries the same JSON envelope — one function name, JSON
+arguments, correlation, retry intent — defined once in :mod:`taskferry.envelope`
+so Celery, Procrastinate, Cloud Tasks, SQS and the rest cannot drift apart on the
+format a worker must understand. There is nothing Celery-specific to add, which is
+the point; this module exists as the stable import path for the adapter's own
+tests and docs.
+"""
+
+from __future__ import annotations
+
+from taskferry.envelope import (
+    ENVELOPE_VERSION,
+    Envelope,
+    build_envelope,
+    decode_retry,
+    encode_retry,
+    read_correlation,
+    read_envelope,
+)
+
+MESSAGE_VERSION = ENVELOPE_VERSION
+TaskferryMessage = Envelope
+build_message = build_envelope
+
+
+def check_version(message: object) -> None:
+    """Reject an envelope this worker does not understand, as ``ValueError``."""
+    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_celery-0.1.0/src/taskferry_celery/worker.py

@@ -0,0 +1,121 @@
+"""The worker side — one Celery task that runs every Taskferry message.
+
+```mermaid
+sequenceDiagram
+    participant B as broker
+    participant W as celery worker
+    participant D as taskferry:dispatch
+    participant REG as FunctionRegistry
+    participant FN as your function
+
+    B->>W: deliver task
+    W->>D: dispatch(message)
+    D->>REG: resolve "package.module:function"
+    REG-->>D: callable
+    D->>FN: call(*args, **kwargs)
+    FN-->>D: value
+    D-->>W: done
+```
+
+Taskferry supplies **no worker**. You run ``celery -A myapp worker``; this module
+only registers the function that worker calls. Reservation, concurrency, prefetch,
+acks and shutdown are Celery's.
+
+Security
+--------
+
+The dispatcher resolves a task *name* that arrived from the broker. If untrusted
+input can reach your broker, that resolution is an arbitrary-import primitive, so
+pass a :class:`~taskferry.functions.FunctionRegistry` with an allowlist::
+
+    registry = FunctionRegistry(allowed_modules=["myapp.tasks"])
+    register_dispatcher(app, registry=registry)
+
+Return values
+-------------
+
+The dispatcher returns whatever the task returned. Celery stores it only if a
+result backend is configured, and this adapter does not advertise ``RESULT``.
+Write results where they belong instead of relying on 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 .message import TaskferryMessage, build_message, check_version, decode_retry
+
+logger = logging.getLogger("taskferry.celery")
+
+DEFAULT_DISPATCH_TASK = "taskferry:dispatch"
+
+
+def execute_message(
+    message: TaskferryMessage,
+    *,
+    registry: FunctionRegistry | None = None,
+) -> Any:
+    """Resolve and run one Taskferry message. Pure of Celery, so unit-testable."""
+    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 Celery ``app``.
+
+    Call once in the module your worker loads::
+
+        from celery import Celery
+        from taskferry_celery import register_dispatcher
+
+        app = Celery("myapp", broker="redis://localhost:6379/0")
+        register_dispatcher(app, registry=FunctionRegistry(allowed_modules=["myapp"]))
+
+    Args:
+        app: The Celery 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`` (``max_retries``, ``acks_late``…).
+
+    Returns:
+        The registered Celery task.
+    """
+    task_options.setdefault("bind", True)
+
+    # app is typed Any: celery 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(self: Any, message: TaskferryMessage) -> Any:
+        policy = decode_retry(message)
+        try:
+            return execute_message(message, registry=registry)
+        except Exception as exc:
+            attempt = int(getattr(getattr(self, "request", None), "retries", 0) or 0) + 1
+            if policy.should_retry(exc, attempt):
+                # Celery owns the retry — a real re-queue with a real countdown —
+                # rather than this function looping and holding a worker slot.
+                # RetryOwner: exactly one layer retries, and here it is the engine.
+                delay = policy.delay_for(attempt + 1)
+                logger.info("requesting celery retry of attempt %d in %.1fs", attempt, delay)
+                raise self.retry(exc=exc, countdown=delay) from exc
+            raise
+
+    return _taskferry_dispatch
+
+
+__all__ = [
+    "DEFAULT_DISPATCH_TASK",
+    "build_message",
+    "execute_message",
+    "register_dispatcher",
+]