taskferry-cloudtasks 0.2.0__tar.gz

taskferry_cloudtasks-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_cloudtasks-0.2.0/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+All notable changes to `taskferry-cloudtasks` 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_cloudtasks-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_cloudtasks-0.2.0/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.5
+Name: taskferry-cloudtasks
+Version: 0.2.0
+Summary: Google Cloud Tasks backend for Taskferry — push-based serverless tasks.
+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: cloud-tasks,gcp,serverless,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: gcp
+Requires-Dist: google-cloud-tasks>=2.16; extra == 'gcp'
+Description-Content-Type: text/markdown
+
+# taskferry-cloudtasks
+
+Run [Taskferry](https://github.com/xiidigital/taskferry) tasks on **Google Cloud
+Tasks** — push-based, serverless, no worker process.
+
+```mermaid
+sequenceDiagram
+    participant App
+    participant TP as Taskferry
+    participant CT as Cloud Tasks
+    participant SVC as your service
+
+    App->>TP: tasks.submit("myapp:send_email", 42)
+    TP->>CT: create_task(http_request)
+    CT->>SVC: POST /_taskferry/execute
+    SVC->>SVC: handle_request(body)
+```
+
+Cloud Tasks is architecturally the opposite of Procrastinate — nothing polls, no
+worker exists, Google pushes an HTTP request at your service. The application
+code does not change:
+
+```python
+runtime.tasks.submit("myapp.tasks:send_email", 42, queue="email")
+```
+
+## Install
+
+```bash
+pip install 'taskferry-cloudtasks[gcp]'
+```
+
+## Configure
+
+```python
+runtime = Taskferry.from_mapping(
+    {
+        "backends": {
+            "push": {
+                "factory": "cloudtasks",
+                "project": "my-project",
+                "location": "europe-west1",
+                "url": "https://my-service.run.app/_taskferry/execute",
+                "service_account_email": "runner@my-project.iam.gserviceaccount.com",
+            }
+        },
+        "defaults": {"task": "push"},
+    }
+)
+```
+
+## Receive
+
+`handle_request` takes bytes, so it works with any framework:
+
+```python
+# Django
+from taskferry import FunctionRegistry
+from taskferry_cloudtasks import handle_request
+
+REGISTRY = FunctionRegistry(allowed_modules=["myapp"])
+
+
+def taskferry_execute(request):
+    handle_request(request.body, dict(request.headers), registry=REGISTRY)
+    return HttpResponse(status=204)
+```
+
+```python
+# FastAPI
+@app.post("/_taskferry/execute")
+async def execute(request: Request):
+    handle_request(await request.body(), dict(request.headers), registry=REGISTRY)
+    return Response(status_code=204)
+```
+
+**Authenticate the endpoint.** Verify the OIDC token Cloud Tasks sends, or put
+the service behind IAM. Taskferry never sees your framework's request object —
+that is what makes it portable, and it is why this part is yours.
+
+**Be idempotent.** Cloud Tasks delivery is at-least-once.
+
+## Capabilities
+
+| Capability | Supported | Why |
+| ---------- | :-------: | --- |
+| `SUBMIT` · `DELAY` · `RETRY` | yes | `create_task`, `schedule_time`, queue retry config |
+| `DEDUPLICATION` | yes | task names are unique per queue for a bounded window |
+| `STATE` · `RESULT` | **no** | Cloud Tasks reports nothing per task after creation |
+
+A handle refuses `status()` here instead of returning a plausible `UNKNOWN`
+forever. Record what you need in your own database, where it is actually true.
+
+## License
+
+Apache-2.0.

taskferry_cloudtasks-0.2.0/README.md

@@ -0,0 +1,96 @@
+# taskferry-cloudtasks
+
+Run [Taskferry](https://github.com/xiidigital/taskferry) tasks on **Google Cloud
+Tasks** — push-based, serverless, no worker process.
+
+```mermaid
+sequenceDiagram
+    participant App
+    participant TP as Taskferry
+    participant CT as Cloud Tasks
+    participant SVC as your service
+
+    App->>TP: tasks.submit("myapp:send_email", 42)
+    TP->>CT: create_task(http_request)
+    CT->>SVC: POST /_taskferry/execute
+    SVC->>SVC: handle_request(body)
+```
+
+Cloud Tasks is architecturally the opposite of Procrastinate — nothing polls, no
+worker exists, Google pushes an HTTP request at your service. The application
+code does not change:
+
+```python
+runtime.tasks.submit("myapp.tasks:send_email", 42, queue="email")
+```
+
+## Install
+
+```bash
+pip install 'taskferry-cloudtasks[gcp]'
+```
+
+## Configure
+
+```python
+runtime = Taskferry.from_mapping(
+    {
+        "backends": {
+            "push": {
+                "factory": "cloudtasks",
+                "project": "my-project",
+                "location": "europe-west1",
+                "url": "https://my-service.run.app/_taskferry/execute",
+                "service_account_email": "runner@my-project.iam.gserviceaccount.com",
+            }
+        },
+        "defaults": {"task": "push"},
+    }
+)
+```
+
+## Receive
+
+`handle_request` takes bytes, so it works with any framework:
+
+```python
+# Django
+from taskferry import FunctionRegistry
+from taskferry_cloudtasks import handle_request
+
+REGISTRY = FunctionRegistry(allowed_modules=["myapp"])
+
+
+def taskferry_execute(request):
+    handle_request(request.body, dict(request.headers), registry=REGISTRY)
+    return HttpResponse(status=204)
+```
+
+```python
+# FastAPI
+@app.post("/_taskferry/execute")
+async def execute(request: Request):
+    handle_request(await request.body(), dict(request.headers), registry=REGISTRY)
+    return Response(status_code=204)
+```
+
+**Authenticate the endpoint.** Verify the OIDC token Cloud Tasks sends, or put
+the service behind IAM. Taskferry never sees your framework's request object —
+that is what makes it portable, and it is why this part is yours.
+
+**Be idempotent.** Cloud Tasks delivery is at-least-once.
+
+## Capabilities
+
+| Capability | Supported | Why |
+| ---------- | :-------: | --- |
+| `SUBMIT` · `DELAY` · `RETRY` | yes | `create_task`, `schedule_time`, queue retry config |
+| `DEDUPLICATION` | yes | task names are unique per queue for a bounded window |
+| `STATE` · `RESULT` | **no** | Cloud Tasks reports nothing per task after creation |
+
+A handle refuses `status()` here instead of returning a plausible `UNKNOWN`
+forever. Record what you need in your own database, where it is actually true.
+
+## License
+
+Apache-2.0.

taskferry_cloudtasks-0.2.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "taskferry-cloudtasks"
+version = "0.2.0"
+description = "Google Cloud Tasks backend for Taskferry — push-based serverless tasks."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+authors = [{ name = "Taskferry authors" }]
+keywords = ["taskferry", "gcp", "cloud-tasks", "tasks", "serverless"]
+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]
+gcp = ["google-cloud-tasks>=2.16"]
+
+[project.entry-points."taskferry.backends"]
+cloudtasks = "taskferry_cloudtasks: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_cloudtasks"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "README.md", "CHANGELOG.md", "LICENSE"]

taskferry_cloudtasks-0.2.0/src/taskferry_cloudtasks/__init__.py

@@ -0,0 +1,54 @@
+"""Taskferry on Google Cloud Tasks — push-based, serverless task execution.
+
+```mermaid
+sequenceDiagram
+    participant App
+    participant TP as Taskferry
+    participant AD as taskferry_cloudtasks
+    participant CT as Cloud Tasks
+    participant SVC as your HTTP service
+
+    App->>TP: tasks.submit("myapp:send_email", 42)
+    TP->>AD: TaskSpec
+    AD->>CT: create_task(http_request)
+    CT->>SVC: POST /_taskferry/execute
+    SVC->>AD: handle_request(body)
+    AD->>SVC: run the function
+```
+
+The second task engine, and the reason the first one had to be an adapter. Cloud
+Tasks is architecturally the opposite of Procrastinate — nothing polls, no worker
+process exists, Google pushes an HTTP request at your service and scale-to-zero
+is the normal state — and the *application code does not change*:
+
+    runtime.tasks.submit("myapp.tasks:send_email", 42, queue="email")
+
+The queue moves from PostgreSQL to Cloud Tasks by editing configuration. That is
+the entire promise of a portability layer, and this package is where it either
+holds or does not.
+
+What genuinely differs, and is therefore visible in the capabilities: Cloud Tasks
+does not report per-task state after creation and stores no results, so ``STATE``
+and ``RESULT`` are not advertised and a handle refuses to fake them. It does
+support scheduling and native retries, and those are advertised.
+
+The receiving side is framework-agnostic — :func:`handle_request` takes bytes and
+returns whatever the task returned, so it plugs into Django, FastAPI, Flask or a
+bare WSGI app in four lines. See :mod:`taskferry_cloudtasks.receiver`.
+"""
+
+from __future__ import annotations
+
+from .backend import CLOUD_TASKS_CAPABILITIES, CloudTasksBackend, make_backend
+from .receiver import handle_request, parse_request
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "CLOUD_TASKS_CAPABILITIES",
+    "CloudTasksBackend",
+    "__version__",
+    "handle_request",
+    "make_backend",
+    "parse_request",
+]

taskferry_cloudtasks-0.2.0/src/taskferry_cloudtasks/backend.py

@@ -0,0 +1,250 @@
+"""The Cloud Tasks `TaskBackend`.
+
+Capabilities, and the two that are missing
+------------------------------------------
+
+Advertised: ``SUBMIT``, ``DELAY`` (``schedule_time``), ``RETRY`` (the queue's own
+retry configuration), ``DEDUPLICATION`` (a task *name* is unique per queue, which
+is real deduplication with a documented window).
+
+Not advertised: ``STATE`` and ``RESULT``. Cloud Tasks is fire-and-forget — once a
+task is created there is no per-task status to read and no place a return value
+is kept. A handle from this backend therefore raises
+:class:`~taskferry.errors.UnsupportedCapability` on ``status()`` rather than
+returning a plausible-looking ``UNKNOWN`` forever, and an application that needs
+to know whether the work happened records that itself, in its own database, where
+it is actually true.
+
+That asymmetry with Procrastinate is not a defect in the abstraction; it is the
+abstraction working. Both engines run the same task code, and the difference in
+what you can *ask* afterwards is visible, checkable and impossible to trip over
+by accident.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import UTC, datetime
+from typing import Any
+
+from taskferry.capabilities import Capability, CapabilitySet
+from taskferry.core.correlation import Correlation
+from taskferry.core.provider import ProviderMetadata
+from taskferry.envelope import ENVELOPE_VERSION, Envelope, build_envelope
+from taskferry.errors import ConfigurationError, SubmissionError
+from taskferry.execution import (
+    Execution,
+    ExecutionKind,
+    ExecutionState,
+    new_execution_id,
+)
+from taskferry.ports import BaseBackend
+from taskferry.specs import ExecutionSpec, TaskSpec
+
+MESSAGE_VERSION = ENVELOPE_VERSION
+"""Alias of the shared envelope version; the format is the core's, not ours."""
+
+CLOUD_TASKS_CAPABILITIES = frozenset(
+    {
+        Capability.SUBMIT,
+        Capability.DELAY,
+        Capability.RETRY,
+        Capability.DEDUPLICATION,
+    }
+)
+
+
+CloudTasksMessage = Envelope
+"""The JSON body Cloud Tasks POSTs to your service — the shared envelope."""
+
+build_message = build_envelope
+"""Serialize a spec into the HTTP body the receiver will decode."""
+
+
+class CloudTasksBackend(BaseBackend):
+    """Creates HTTP-target tasks on a Cloud Tasks queue.
+
+    Args:
+        project: GCP project id.
+        location: Queue region.
+        queue: Default queue name. ``TaskSpec.queue`` overrides it, which is what
+            makes ``queue="email"`` mean a real Cloud Tasks queue.
+        url: The endpoint Cloud Tasks will POST to. Your service routes it to
+            :func:`taskferry_cloudtasks.handle_request`.
+        service_account_email: Identity for the OIDC token, so the endpoint can
+            require authentication instead of being open to the internet.
+        audience: OIDC audience, when it differs from ``url``.
+        client: Injected ``tasks_v2.CloudTasksClient`` for testing.
+
+    Backend options, under the ``"cloudtasks"`` namespace: ``dispatch_deadline``,
+    ``headers``, and ``queue`` for a one-off override.
+    """
+
+    def __init__(
+        self,
+        *,
+        project: str | None = None,
+        location: str | None = None,
+        queue: str = "default",
+        url: str | None = None,
+        service_account_email: str | None = None,
+        audience: str | None = None,
+        client: Any = None,
+        name: str = "cloudtasks",
+    ) -> None:
+        missing = [
+            key
+            for key, value in (("project", project), ("location", location), ("url", url))
+            if not value
+        ]
+        if missing:
+            raise ConfigurationError(
+                f"CloudTasksBackend needs {', '.join(missing)}; 'url' is the endpoint in your "
+                "service that Cloud Tasks will POST each task to"
+            )
+        assert project and location and url  # narrowed by the check above
+        self._project = project
+        self._location = location
+        self._queue = queue
+        self._url = url
+        self._service_account_email = service_account_email
+        self._audience = audience
+        self._client = client
+        self._name = name
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    @property
+    def kind(self) -> ExecutionKind:
+        return ExecutionKind.TASK
+
+    @property
+    def capabilities(self) -> CapabilitySet:
+        return CapabilitySet(CLOUD_TASKS_CAPABILITIES, provider=self._name)
+
+    def _tasks(self) -> Any:
+        if self._client is None:
+            try:
+                from google.cloud import tasks_v2
+            except ImportError as exc:  # pragma: no cover - depends on the environment
+                raise ConfigurationError(
+                    "the Cloud Tasks backend needs the Google SDK: "
+                    "pip install 'taskferry-cloudtasks[gcp]'"
+                ) from exc
+            self._client = tasks_v2.CloudTasksClient()
+        return self._client
+
+    def queue_path(self, queue: str) -> str:
+        client = self._tasks()
+        builder = getattr(client, "queue_path", None)
+        if callable(builder):
+            return str(builder(self._project, self._location, queue))
+        return f"projects/{self._project}/locations/{self._location}/queues/{queue}"
+
+    # -- submission -------------------------------------------------------------- #
+    def _submit(self, spec: ExecutionSpec) -> Execution:
+        assert isinstance(spec, TaskSpec)
+        options = spec.options_for("cloudtasks")
+        queue = str(options.get("queue") or spec.queue or self._queue)
+
+        http_request: dict[str, Any] = {
+            "http_method": "POST",
+            "url": self._url,
+            "headers": {
+                "Content-Type": "application/json",
+                **self._correlation_headers(spec.correlation),
+                **dict(options.get("headers") or {}),  # type: ignore[arg-type]
+            },
+            "body": json.dumps(build_message(spec)).encode("utf-8"),
+        }
+        if self._service_account_email:
+            oidc: dict[str, str] = {"service_account_email": self._service_account_email}
+            if self._audience or self._url:
+                oidc["audience"] = self._audience or self._url
+            http_request["oidc_token"] = oidc
+
+        task: dict[str, Any] = {"http_request": http_request}
+        scheduled_for = spec.scheduled_for()
+        if scheduled_for is not None:
+            task["schedule_time"] = scheduled_for
+        if "dispatch_deadline" in options:
+            task["dispatch_deadline"] = options["dispatch_deadline"]
+        if spec.idempotency_key is not None:
+            # A named task is refused if the name was used recently — Cloud Tasks'
+            # own, real, time-bounded deduplication. The window is Google's, not
+            # ours, and this is not an exactly-once promise.
+            task["name"] = f"{self.queue_path(queue)}/tasks/{_safe_name(spec.idempotency_key)}"
+
+        try:
+            created = self._tasks().create_task(
+                request={"parent": self.queue_path(queue), "task": task}
+            )
+        except Exception as exc:
+            raise SubmissionError(
+                f"Cloud Tasks could not create a task for {spec.task!r} on queue {queue!r}: {exc}",
+                backend=self._name,
+            ) from exc
+
+        external_id = getattr(created, "name", None)
+        return Execution(
+            id=new_execution_id(ExecutionKind.TASK),
+            kind=ExecutionKind.TASK,
+            backend=self._name,
+            # QUEUED is the last thing this backend can honestly observe: Cloud
+            # Tasks will not tell us anything after creation.
+            state=ExecutionState.QUEUED,
+            name=spec.name,
+            created_at=datetime.now(UTC),
+            external_id=str(external_id) if external_id else None,
+            correlation=spec.correlation,
+            provider_metadata=ProviderMetadata(
+                provider="gcp",
+                provider_id=str(external_id) if external_id else None,
+                region=self._location,
+                resource=self.queue_path(queue),
+                labels=dict(spec.labels),
+            ),
+            metadata={"queue": queue, "url": self._url},
+        )
+
+    @staticmethod
+    def _correlation_headers(correlation: Correlation | None) -> dict[str, str]:
+        """Propagate correlation and trace context as HTTP headers.
+
+        This is how a trace survives the hop through Google's infrastructure: the
+        receiver rebuilds the correlation from these headers, so one flow stays
+        followable from the web request through the queue into the task.
+        """
+        return correlation.to_headers() if correlation is not None else {}
+
+
+def _safe_name(key: str) -> str:
+    """Reduce an idempotency key to the characters Cloud Tasks allows in a name."""
+    cleaned = "".join(char if char.isalnum() or char in "-_" else "-" for char in key)
+    return cleaned[:500] or "taskferry"
+
+
+def make_backend(**options: Any) -> CloudTasksBackend:
+    """Entry point for ``{"factory": "cloudtasks", ...}`` configuration."""
+    return CloudTasksBackend(
+        project=options.get("project"),
+        location=options.get("location"),
+        queue=str(options.get("queue", "default")),
+        url=options.get("url"),
+        service_account_email=options.get("service_account_email"),
+        audience=options.get("audience"),
+        client=options.get("client"),
+        name=str(options.get("name", "cloudtasks")),
+    )
+
+
+__all__ = [
+    "CLOUD_TASKS_CAPABILITIES",
+    "MESSAGE_VERSION",
+    "CloudTasksBackend",
+    "CloudTasksMessage",
+    "build_message",
+    "make_backend",
+]

taskferry_cloudtasks-0.2.0/src/taskferry_cloudtasks/receiver.py

@@ -0,0 +1,126 @@
+"""The receiving side — bytes in, task executed.
+
+Cloud Tasks pushes an HTTP request; something in your service has to turn that
+back into a function call. That something is :func:`handle_request`, and it takes
+**bytes**, not a Django ``HttpRequest``, not a Starlette ``Request``.
+
+```mermaid
+flowchart LR
+    CT["Cloud Tasks"]
+    V["your view / route<br/>(4 lines, any framework)"]
+    H["handle_request(body, headers)"]
+    FN["package.module:function"]
+
+    CT -->|"POST JSON"| V --> H --> FN
+```
+
+Django::
+
+    from django.http import HttpResponse
+    from taskferry_cloudtasks import handle_request
+
+    def taskferry_execute(request):
+        handle_request(request.body, dict(request.headers), registry=REGISTRY)
+        return HttpResponse(status=204)
+
+FastAPI::
+
+    @app.post("/_taskferry/execute")
+    async def execute(request: Request):
+        handle_request(await request.body(), dict(request.headers), registry=REGISTRY)
+        return Response(status_code=204)
+
+Keeping the framework out of this module is what lets one adapter serve all of
+them, and is why ``taskferry-cloudtasks`` depends on neither Django nor FastAPI.
+
+Two things your endpoint must do
+--------------------------------
+
+**Authenticate.** Anyone who finds the URL can POST to it. Require the OIDC token
+Cloud Tasks sends (verify it with ``google.oauth2.id_token``), or put the service
+behind IAM. Taskferry cannot do this for you: it never sees your framework's
+request object, which is the same reason it is portable.
+
+**Be idempotent.** Cloud Tasks retries, so a task can arrive more than once.
+Delivery is at-least-once; nothing here changes that and nothing can.
+
+Returning 2xx acknowledges the task; raising (or returning 5xx) tells Cloud Tasks
+to retry according to the queue's retry configuration. Let exceptions propagate
+and the queue does the right thing.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from typing import Any
+
+from taskferry.core.correlation import Correlation, use_correlation
+from taskferry.envelope import read_envelope
+from taskferry.errors import SerializationError
+from taskferry.functions import FunctionRegistry, is_async_callable
+
+from .backend import CloudTasksMessage
+
+
+def parse_request(body: bytes | str) -> CloudTasksMessage:
+    """Decode and validate the request body.
+
+    Raises:
+        SerializationError: when the body is not a Taskferry message of a version
+            this code understands. Failing loudly is deliberate: a malformed body
+            means a misconfigured endpoint or a version skew, and quietly doing
+            nothing would hide both.
+    """
+    try:
+        payload = json.loads(body)
+    except (ValueError, UnicodeDecodeError) as exc:
+        raise SerializationError(f"Cloud Tasks body is not valid JSON: {exc}") from exc
+    return read_envelope(payload)
+
+
+def handle_request(
+    body: bytes | str,
+    headers: Mapping[str, str] | None = None,
+    *,
+    registry: FunctionRegistry | None = None,
+) -> Any:
+    """Run the task described by a Cloud Tasks push request.
+
+    Args:
+        body: The raw request body.
+        headers: Request headers, used to restore correlation and trace context
+            so the task's spans join the flow that enqueued it.
+        registry: Where task names resolve. **Give it an allowlist**: the task
+            name arrives over the network, and an unrestricted resolver on a
+            public endpoint is a remote-import primitive.
+
+    Returns:
+        Whatever the task returned. Cloud Tasks discards it; it is returned so
+        the value is available to your view for logging or a response body.
+    """
+    message = parse_request(body)
+    resolver = registry if registry is not None else FunctionRegistry()
+    func = resolver.resolve(str(message["task"]))
+    args = list(message.get("args") or [])
+    kwargs = dict(message.get("kwargs") or {})
+
+    with use_correlation(_correlation_from(message, headers)):
+        if is_async_callable(func):
+            import asyncio
+
+            return asyncio.run(func(*args, **kwargs))
+        return func(*args, **kwargs)
+
+
+def _correlation_from(message: CloudTasksMessage, headers: Mapping[str, str] | None) -> Correlation:
+    """Prefer the headers (they carry live trace context), fall back to the body."""
+    if headers:
+        normalised = {key.lower(): value for key, value in headers.items()}
+        if "taskferry-correlation-id" in normalised:
+            return Correlation.from_headers(normalised)
+    embedded = message.get("correlation")
+    return Correlation.from_headers(embedded) if embedded else Correlation.start()
+
+
+__all__ = ["handle_request", "parse_request"]