Metadata-Version: 2.5
Name: taskferry-sqs
Version: 0.2.0
Summary: AWS SQS task backend for Taskferry — pull-based task delivery.
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: aws,queue,sqs,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: aws
Requires-Dist: boto3>=1.34; extra == 'aws'
Description-Content-Type: text/markdown

# taskferry-sqs

Run [Taskferry](https://github.com/xiidigital/taskferry) tasks on **AWS SQS** —
pull-based delivery, consumed by a Lambda, an ECS service, or your own loop.

```mermaid
flowchart LR
    APP["Application"] --> TP["Taskferry"] --> AD["taskferry-sqs"] --> Q["SQS queue"] --> C["Lambda · ECS · Fargate"]
```

```bash
pip install 'taskferry-sqs[aws]'
```

## Sending

```python
runtime = Taskferry.from_mapping(
    {
        "backends": {
            "sqs": {
                "factory": "sqs",
                "queue_url": "https://sqs.eu-west-1.amazonaws.com/123456789/tasks",
            }
        },
        "defaults": {"task": "sqs"},
    }
)

runtime.tasks.submit("myapp.tasks:send_email", 42, queue="email")
```

## Consuming

**AWS Lambda**, with partial batch responses enabled:

```python
from taskferry import FunctionRegistry
from taskferry_sqs import process_event

REGISTRY = FunctionRegistry(allowed_modules=["myapp"])


def handler(event, context):
    return process_event(event, registry=REGISTRY)
```

**ECS / Fargate / a plain process:**

```python
import boto3
from taskferry_sqs import poll_forever

poll_forever(boto3.client("sqs"), QUEUE_URL, registry=REGISTRY)
```

`poll_forever` long-polls, deletes on success, leaves failures for SQS's own
redrive policy, and stops cleanly on SIGTERM. It is forty lines and deliberately
not a worker framework — SQS already solves visibility timeouts and dead-lettering.

## Capabilities

| Capability | Standard queue | FIFO queue | Why |
| --- | :---: | :---: | --- |
| `SUBMIT` | yes | yes | `send_message` |
| `DELAY` | yes | **no** | FIFO delay is queue-level, not per message |
| `DEDUPLICATION` | **no** | yes | `MessageDeduplicationId` |
| `RETRY` | yes | yes | the queue's redrive policy |
| `STATE` · `RESULT` · `CANCEL` | **no** | **no** | SQS cannot look up or revoke one message |

The capability set is computed **per queue**, because a `.fifo` queue genuinely
differs from a standard one and one class serving both must say which it is.

Two limits are enforced rather than clamped:

- **900 seconds of delay, maximum.** A longer delay raises with the limit named,
  instead of arriving 15 minutes from now when you asked for tomorrow.
- **FIFO queues refuse per-message delay** rather than dropping it silently.

## Testing

The client is injectable, so the suite runs with no AWS account:

```python
SQSTaskBackend(queue_url="https://sqs.eu-west-1.amazonaws.com/1/q", client=FakeSQS())
```

## License

Apache-2.0.
