async-task-api-worker 0.1.0rc2__tar.gz

async_task_api_worker-0.1.0rc2/.gitignore

@@ -0,0 +1,61 @@
+.venv
+.env
+.coverage
+.pytest_cache/
+__pycache__
+htmlcov/
+nodemodules/
+junit.xml
+.vscode
+.ruff_cache
+node_modules/
+package-lock.json
+*.egg-info/
+dist/
+build/
+*.log
+*.pot
+*.pyc
+# charts/ intentionnellement pour ArgoCD (pas d'accès aux repos externes)
+.DS_Store
+demo.db
+junit.xml
+coverage.xml
+
+# Sorties locales sensibles (audit, homologation, tests d'intrusion) — ne pas committer
+private/
+
+# Dépôt de fixtures de la boucle de révision, monté par docker-compose.revision.yml et
+# reconstruit par `revision-ui/recette/bout_en_bout.py --racine`. Contient des vignettes
+# générées et des jetons signés : produit, jamais source.
+revision-ui/.fixtures/
+
+# Secrets et matériel cryptographique
+.env.*
+!.env.example
+*.pem
+*.key
+*.p12
+*.pfx
+id_rsa*
+id_ed25519*
+*.kubeconfig
+kubeconfig*
+*.tfstate
+*.tfstate.*
+secrets/
+*.secret
+
+# Dumps et sauvegardes
+*.sql.gz
+*.dump
+*.bak-*
+
+# Console d'exemple : secrets locaux et fragment Keycloak rempli. Le `.gitignore` couvre
+# déjà `.env` et `.env.*` à toute profondeur — ces lignes sont EXPLICITES parce qu'un secret
+# protégé par accident cesse de l'être à la première réécriture du fichier.
+exemple-front/.env
+exemple-front/keycloak/*.local.json
+
+# Captures du smoke navigateur : régénérées à chaque exécution.
+exemple-front/recette/captures/

async_task_api_worker-0.1.0rc2/CHANGELOG.md

@@ -0,0 +1,63 @@
+# Changelog
+
+## [0.1.0-rc.2](https://github.com/IA-Generative/async-api/compare/async-task-api-worker-v0.1.0-rc.1...async-task-api-worker-v0.1.0-rc.2) (2026-10-23)
+
+
+### Features
+
+* **sdk:** add a harness to run a worker's task in memory ([27a0ca7](https://github.com/IA-Generative/async-api/commit/27a0ca7558f15b5f7f589e84feb391ba152ddbde))
+* **sdk:** add context factories to unit-test a handler directly ([0429cc7](https://github.com/IA-Generative/async-api/commit/0429cc78e70c2d9de9966c350d50b95d5f2e2af5))
+
+
+### Bug Fixes
+
+* **sdk:** close the channels before the connection so the last ack is not lost ([1118516](https://github.com/IA-Generative/async-api/commit/1118516300c9d56e0ff023a8cecc5af6994fefbd))
+
+
+### Documentation
+
+* **sdk:** add a Testing your worker section ([77284da](https://github.com/IA-Generative/async-api/commit/77284dafdae038357ca33cf1cb1dca8cef2f0f76))
+
+## 0.1.0-rc.1 (2026-10-23)
+
+
+### Features
+
+* **sdk:** add a transport on aio-pika ([89f90d2](https://github.com/IA-Generative/async-api/commit/89f90d293fcd12e9ec893adc17f7fe138c1f5bee))
+* **sdk:** add JSON logging ([c02fbf9](https://github.com/IA-Generative/async-api/commit/c02fbf905e7eb6372bffb645da1119ff34d130d3))
+* **sdk:** add the delivery engine and the Worker definition API ([99b9636](https://github.com/IA-Generative/async-api/commit/99b96365fedcace29b4e5cbbea6e90860138e73d))
+* **sdk:** add the probe and metrics HTTP server ([4694871](https://github.com/IA-Generative/async-api/commit/4694871a673b1526ea260bf4fdb786996f013e91))
+* **sdk:** add the process lifecycle, Worker.run and the run command ([38c93da](https://github.com/IA-Generative/async-api/commit/38c93da62f4446c8a001352a76e5d8f9dc39a70c))
+* **sdk:** add the Prometheus metrics and the event loop lag probe ([ae1b82c](https://github.com/IA-Generative/async-api/commit/ae1b82c2b3ef8f8d71faf5e28d2f1e235e77b14a))
+* **sdk:** add the RabbitMQ transport and the queue declaration ([709d1f3](https://github.com/IA-Generative/async-api/commit/709d1f3fbab892009ff7a9d4dec7c007dadaffda))
+* **sdk:** add the runtime transport contract, retry backoff and in-flight registry ([03a65f8](https://github.com/IA-Generative/async-api/commit/03a65f858d7816223b93ec63a02a5bf7ecca733c))
+* **sdk:** add the task contexts and the sync handler bridge ([3e50261](https://github.com/IA-Generative/async-api/commit/3e502617fd8ca50f4d0a5254b268f58d814b50a5))
+* **sdk:** add the time-based progress throttle ([7d85fe1](https://github.com/IA-Generative/async-api/commit/7d85fe11496890d4dbd3580b130b82bcfd0905f1))
+* **sdk:** add WORKER_MODE settings and force a prefetch of 1 in job mode ([94703d0](https://github.com/IA-Generative/async-api/commit/94703d05bd450717cd914784fcf75abadd4ce660))
+* **sdk:** let a transport report whether the broker connection is up ([82338fa](https://github.com/IA-Generative/async-api/commit/82338fae6a0c988647fa2a47fd1aadb54fb0311e))
+* **sdk:** log one decision line per settled delivery ([162467a](https://github.com/IA-Generative/async-api/commit/162467abeead6776973c1bd72137d067e0137923))
+* **sdk:** run the lifecycle as a one-shot job when WORKER_MODE=job ([82f9034](https://github.com/IA-Generative/async-api/commit/82f90345341f40bf080aa3df44a371e5a2fab63b))
+* **sdk:** serve the probes and the metrics from the lifecycle ([6df9b75](https://github.com/IA-Generative/async-api/commit/6df9b7584922b48c756cdc0f5c1fd64d2586e93f))
+
+
+### Bug Fixes
+
+* **sdk:** abort the probe clients when the server stops ([0ad2dd4](https://github.com/IA-Generative/async-api/commit/0ad2dd4fa1862d2175076f2ff6f5ddb61c9a5e80))
+* **sdk:** bound the shutdown tail and stop a startup on a signal ([0ce9e19](https://github.com/IA-Generative/async-api/commit/0ce9e1993ed830261146bd7b3b7a3785c97cc679))
+* **sdk:** cancel the consumer before the subscriber stops accepting deliveries ([a5959a3](https://github.com/IA-Generative/async-api/commit/a5959a30356a5b960902aa4bc01510a2dc13c1cb))
+* **sdk:** do not wait for default-executor threads at exit ([f5a2f1e](https://github.com/IA-Generative/async-api/commit/f5a2f1e643364b1d9f05d544998e55b394ec5a3c))
+* **sdk:** harden the encoder, the decoder and the settings ([7f91e23](https://github.com/IA-Generative/async-api/commit/7f91e2393094da9a272cc19c400547313d9a5936))
+* **sdk:** log the reconnect errors of aio-pika as warnings ([591526d](https://github.com/IA-Generative/async-api/commit/591526df2c17c99c7b12ea72f3941e4308ba98bd))
+* **sdk:** retry a raw connect timeout in service mode ([d6d1fcd](https://github.com/IA-Generative/async-api/commit/d6d1fcd5876c2031800163ea9a15b4f789651875))
+* **sdk:** ship only the sources in the sdist and polish messages ([e6e6ee1](https://github.com/IA-Generative/async-api/commit/e6e6ee128d231a8bb942215ab746122929719362))
+
+
+### Documentation
+
+* **sdk:** describe the protocol itself in the packaged sources ([67cd9f0](https://github.com/IA-Generative/async-api/commit/67cd9f02ddc730c388128d53b214c7e13f841280))
+* **sdk:** document the deployment or job modes ([5e94fb9](https://github.com/IA-Generative/async-api/commit/5e94fb9a36958fd29a449138e7286a9ece47cc5d))
+* **sdk:** document the probes, the metrics and the logs ([29c22ca](https://github.com/IA-Generative/async-api/commit/29c22cae66498201cc02b0b0087f54513e58b51b))
+* **sdk:** document the worker definition and progress rules ([9a1b710](https://github.com/IA-Generative/async-api/commit/9a1b71052fe47c18ea7c8d09e779e20d78bb4d91))
+* **sdk:** leave the changelog to release-please ([f7cb380](https://github.com/IA-Generative/async-api/commit/f7cb380912601fb2bbb59636f5bbe1ce98b06fb8))
+
+## Changelog

async_task_api_worker-0.1.0rc2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 IA-Generative
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

async_task_api_worker-0.1.0rc2/PKG-INFO

@@ -0,0 +1,269 @@
+Metadata-Version: 2.5
+Name: async-task-api-worker
+Version: 0.1.0-rc.2
+Summary: SDK to write workers for the AsyncTaskAPI platform: protocol models, runtime and conformance kit.
+Project-URL: Repository, https://github.com/IA-Generative/async-api
+License: MIT
+License-File: LICENSE
+Keywords: async-api,rabbitmq,sdk,worker
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: aio-pika>=9.5.5
+Requires-Dist: prometheus-client>=0.22.1
+Requires-Dist: pydantic-settings>=2.10.1
+Requires-Dist: pydantic>=2.10
+Description-Content-Type: text/markdown
+
+# async-task-api-worker
+
+SDK to write workers for the AsyncTaskAPI platform.
+
+This is a work in progress: the package ships the protocol models (inbound envelope decoder and the byte-exact
+outbound message encoder), the error types, the settings, the runtime engine with the `Worker` definition API, the
+RabbitMQ transport, the process lifecycle (graceful drain), the probes, the metrics and the JSON logs. The conformance
+kit and the extras land in later releases.
+
+## Declaring a worker
+
+```python
+from pydantic import BaseModel, Field
+
+from async_task_api_worker import TaskContext, Worker
+
+
+class Input(BaseModel):
+    text: str = Field(min_length=1, max_length=100_000)
+
+
+class Output(BaseModel):
+    words: int
+
+
+worker = Worker("count-words")
+
+
+@worker.task(timeout=30.0)
+async def handle(task_input: Input, ctx: TaskContext) -> Output:
+    await ctx.progress(0.5)
+    return Output(words=len(task_input.text.split()))
+```
+
+- `async def` handlers run on the event loop; `def` handlers (with a `SyncTaskContext`) run in a thread pool. The
+  context parameter must be annotated exactly `TaskContext` or `SyncTaskContext` (an identity check: no subclass or
+  `Annotated` wrapper). Hooks and probes (`on_startup`, `on_shutdown`, `readiness_probe`) must be `async def`.
+- The input and output models are read from the annotations. Exactly one task per worker.
+- Raise `FatalError(code, message)` to fail a task with a code the client can match, `RetryableError` for a
+  transient failure. Any other exception is reported as `INTERNAL_ERROR` without its text.
+- `ctx.progress(fraction, payload)` reports the **latest state** of the task, not an event stream: updates are
+  throttled (at most one per `WORKER_PROGRESS_MIN_INTERVAL_S`, default 1 s), a newer update replaces a held one,
+  `fraction` is in `[0, 1)` and never goes back. The terminal success or failure message is the 100%.
+
+## Running a worker
+
+```bash
+export BROKER_URL=amqp://user:password@broker:5672/ IN_QUEUE_NAME=count-words_queue_in OUT_QUEUE_NAME=count-words_queue_out
+async-task-api-worker run my_module:worker      # or: python -m async_task_api_worker run my_module:worker
+```
+
+`my_module:worker` is a `Worker`, or a zero-argument factory function returning one; modules in the current directory can
+be imported. A definition error in the module exits with code 2 and one line. From code, `worker.run()` blocks until the
+process is stopped and `await worker.serve()` serves from an existing event loop.
+
+- The settings are read and validated first: an invalid configuration, or a task timeout that does not fit under the
+  broker's consumer timeout (`task timeout + WORKER_RETRY_BACKOFF_MAX_S + 60 s < WORKER_CONSUMER_TIMEOUT_S`), exits with
+  code 2 before any connection. Exit codes: 0 clean stop, 1 failure, 2 configuration or usage error.
+- The queues are declared durable and with no arguments (the broker decides their type and policies), and consumed with
+  manual acknowledgements: a task is acked only after its result is published.
+- SIGTERM or SIGINT stops consuming, lets the in-flight tasks finish within `WORKER_SHUTDOWN_GRACE_S` (default 25 s),
+  requeues the ones that did not, closes the connection and exits 0. A second signal skips the rest of the grace period.
+  A `def` handler whose thread is still running after the drain, or an `async def` handler whose `asyncio.to_thread`
+  thread is (given 2 s after the drain), is logged and the process exits at once with code 1 (only for `run`, never for
+  `serve()`). The whole shutdown is bounded: the process exits at most
+  `max(WORKER_SHUTDOWN_GRACE_S, 5)` + 17 s after the signal (5 s for the nacks of the cancelled tasks, 5 s to close the
+  connection, and 5 s in total, `WORKER_SHUTDOWN_HOOKS_TIMEOUT_S`, for all the shutdown hooks together, each getting what is
+  left). Set a pod's `terminationGracePeriodSeconds` to at least that. A signal during startup does not wait for it: the
+  connection attempt and the startup hooks are cancelled and the process exits 0 (a hook that blocks the event loop
+  cannot be interrupted).
+- **Retries and crash-loop protection need quorum queues** (the broker's default queue type, as in the platform's
+  chart). A classic queue gives no delivery counter: there, a `RetryableError` gets one retry, then concludes with its
+  own code, and a warning says so.
+- Refused broker credentials exit with code 2 right away instead of being retried.
+- The attempt number of a delivery (`ctx.attempt`) counts every time the broker handed the message out. A
+  `RetryableError` requeues until attempt `WORKER_DELIVERY_LIMIT`, then concludes with its own code. A delivery past
+  that limit (a crash loop) is concluded with `TASK_ABANDONED_AFTER_REDELIVERIES` without running the handler.
+
+## Probes, metrics and logs
+
+A small HTTP server runs on `HEALTH_CHECK_HOST:HEALTH_CHECK_PORT` (default `0.0.0.0:8083`) in both modes, from the very
+start of the process until the end of the shutdown.
+
+| Path | Answer |
+|---|---|
+| `GET /health` | Liveness. 200 `{"status": "ok"}`, or 503 `TASK_OVERRUN` when a `def` handler is still running `WORKER_TASK_OVERRUN_GRACE_S` after its deadline. It consults no dependency. |
+| `GET /ready` | Readiness. 200 with a `components` map, or 503 `DEPENDENCIES_NOT_READY` (with the same `components` in `error`) when the broker is disconnected, the worker is draining, or one of the probes registered with `@worker.readiness_probe("name")` raises or exceeds `WORKER_PROBE_TIMEOUT_S` (3 s). Probes run in parallel. A `ProbeError` message is shown as the detail; any other exception only by its class name. |
+| `GET /metrics`, `GET /internal/metrics` | Prometheus text exposition. |
+| `GET /__version__` | `/app/version.json` of the image, or a `dev` document. |
+
+Errors use the platform's format, `{"status": "error", "error": {"code", "message"}}` (404 `NOT_FOUND`, 405
+`METHOD_NOT_ALLOWED`, 500 `PROBE_FAILED`). `broker` and `draining` are reserved component names. `/ready` is also 503 in
+job mode once the quota is reached and the consumer cancelled.
+
+The server is bounded: at most 32 connections are served at once (the others are closed at once), reading the request,
+writing the answer and closing each take at most 5 s, and concurrent `/ready` requests share a single evaluation of the
+probes.
+
+**Startup.** `/health` answers while the startup hooks run, but only as long as the event loop is free: a hook that loads a
+model or a large file synchronously blocks it, `/health` stops answering and the kubelet restarts the pod in a loop. Run
+heavy loading in `asyncio.to_thread`, or give the container a `startupProbe`.
+
+Metrics have no task, client or service label (the scrape adds the pod and service): `worker_tasks_total{status}`,
+`worker_task_duration_seconds`, `worker_messages_published_total{message_type}`, `event_loop_lag_seconds{component}`,
+`worker_task_failures_total{code}`, `worker_task_retries_total`, `worker_poison_messages_total{reason}`,
+`worker_publish_failures_total{message_type}`, `worker_ack_failures_total`, `worker_tasks_in_flight`,
+`worker_shutdown_requeued_total`, `worker_progress_dropped_total{reason}` and `worker_sdk_info`, plus the process, platform
+and GC collectors.
+
+Logs are one JSON object per line on stdout (`ts`, `level`, `logger`, `msg`, and `task_id`, `service`, `attempt` when
+bound; `ctx.logger` carries them, and so do the records of any library logging inside a handler, on the SDK's handler).
+`LOG_LEVEL` sets the level. If the application configured the root logger before running the worker, its handlers are
+kept and the SDK adds none (no line is printed twice): the format is then the application's, and so is the level of
+the `aio_pika.tools` logger, whose two ERROR lines on a dropped connection the SDK otherwise logs as warnings (the
+connection then reconnects by itself). To still get the task fields on your own handler, chain a record factory:
+
+```python
+import logging
+from async_task_api_worker.observability.logging import TaskContextFilter
+
+task_fields = TaskContextFilter()
+previous_factory = logging.getLogRecordFactory()
+
+
+def factory(*args, **kwargs):
+    record = previous_factory(*args, **kwargs)
+    task_fields.filter(record)
+    return record
+
+
+logging.setLogRecordFactory(factory)
+```
+
+Every delivery ends with exactly one INFO decision line, for instance `Delivery settled: outcome=failure action=conclude
+code=NOT_ALLOWED attempt=1/5`, with the fields `task_id`, `attempt`, `delivery_limit`, `outcome` (`success`, `failure`,
+`poison`, `retry`, `publish_failed`, `shutdown_requeued`, `cancelled`, `engine_error`), `action` (`ack`, `conclude`,
+`nack-requeue`) and `code`: `grep <task_id>`
+tells the whole story of a task. Payloads and secrets are never logged.
+
+## Deployment or Job
+
+The same worker code and image run as a long-lived consumer (a Kubernetes Deployment) or as a one-shot process (a
+Job, for instance one started per message by KEDA's `ScaledJob`). The deployment picks the mode with `WORKER_MODE`; the
+`Worker` definition does not change.
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `WORKER_MODE` | `service` | `service` consumes until SIGTERM; `job` is one-shot. Any other value exits with code 2. |
+| `WORKER_JOB_MAX_TASKS` | `1` | Job mode: stop consuming at this many deliveries, finish them, and exit. |
+| `WORKER_JOB_IDLE_TIMEOUT_S` | `10` | Job mode: exit when no delivery is in hand and none arrives for this long (another pod probably took the message). |
+| `WORKER_JOB_CONNECT_TIMEOUT_S` | `30` | Job mode: give up and exit 1 when the broker stays unreachable for this long. Service mode retries forever. |
+
+In job mode the prefetch is forced to 1, whatever `WORKER_CONCURRENCY` says (it then only sizes the handler semaphore
+and the thread pool). The quota counts deliveries **on arrival**: any delivery counts, poison ones and redeliveries past
+the limit included, and consuming stops as soon as the last one is in hand. The exit code reports the **pod**, not the
+task: a task that succeeds, fails (`FatalError`, timeout, invalid input), or is requeued (`RetryableError`) all exit 0,
+and so does an idle exit, because a failed task is a business outcome already published to the client. Exit 1 (an
+infrastructure failure such as a broker unreachable for `WORKER_JOB_CONNECT_TIMEOUT_S`, or a `def` handler stuck after
+the drain) and 2 (invalid configuration) stay non-zero, so the Job's `backoffLimit` applies to them. SIGTERM and
+`activeDeadlineSeconds` drain exactly as in service mode.
+
+## Testing your worker
+
+`async_task_api_worker.testing` runs your task in memory through the real engine (decoding, time limit, retries, error
+mapping, acknowledgements), with no broker and no Docker:
+
+```python
+from pydantic import BaseModel
+
+from async_task_api_worker import FatalError, TaskContext, Worker
+from async_task_api_worker.testing import Outcome, ProgressRecorder, WorkerHarness, make_task_context
+
+
+class Input(BaseModel):
+    text: str
+
+
+class Output(BaseModel):
+    words: int
+
+
+worker = Worker("count-words")
+
+
+@worker.task(timeout=30.0)
+async def handle(task_input: Input, ctx: TaskContext) -> Output:
+    if not task_input.text.strip():
+        raise FatalError("EMPTY_TEXT", "There is nothing to count.")
+    await ctx.progress(0.5)
+    return Output(words=len(task_input.text.split()))
+
+
+async def test_counts_the_words() -> None:
+    async with WorkerHarness(worker) as harness:
+        run = await harness.submit({"text": "hello big world"})
+
+    run.assert_succeeded()
+    assert run.response == {"words": 3}
+    assert run.message_types == ("started", "progress", "success")
+
+
+async def test_an_empty_text_fails_with_its_code() -> None:
+    async with WorkerHarness(worker) as harness:
+        run = await harness.submit({"text": "  "})
+
+    run.assert_failed(code="EMPTY_TEXT")
+    assert run.outcome is Outcome.ACKED
+
+
+async def test_the_handler_alone_with_a_context_you_build() -> None:
+    recorder = ProgressRecorder()
+    ctx = make_task_context(recorder=recorder)
+
+    assert await handle(Input(text="a b"), ctx) == Output(words=2)
+    assert [update.fraction for update in recorder.updates] == [0.5]
+```
+
+- `harness.submit(body, client_id=..., input_refs=..., delivery_count=...)` builds the envelope the API publishes;
+  `submit_raw(bytes)` sends bytes as they are (a poison message). The result is a `TaskRun`: `messages` (decoded) and
+  `raw` (the published bytes), `message_types` (all three are tuples), `outcome` (`ACKED`, `NACKED_REQUEUE`), `response`,
+  `error`, and the two assertions. `task_id` is the envelope's, or `None` for bytes that do not carry one.
+- `delivery_count` is the broker's `x-delivery-count`: pass `0`, then `delivery_count=n` to see a `RetryableError`
+  requeue until the last attempt (`worker_delivery_limit`), which concludes with the error's own code. Retry backoffs are
+  a millisecond; every other setting is the production default (progress throttling included).
+- `settings_overrides={"worker_task_timeout_s": 0.1, ...}` takes `WorkerSettings` field names; no environment variable is
+  read, and the time budget is checked as at startup. `harness.fail_next_publish("success")` makes the next publish (of
+  that message type, or of any) fail once, to test the requeue. Use `async with` (or `await harness.aclose()`).
+- `make_task_context` and `make_sync_task_context` build the context of an `async def` and of a `def` handler, to call
+  the handler directly; `ProgressRecorder` collects what it reports.
+
+## Development
+
+From this directory:
+
+```bash
+uv sync --locked --all-extras
+uv run ruff check . && uv run ruff format --check .
+uv run ty check src
+uv run pytest -m "not integration" -q --cov=async_task_api_worker --cov-branch --cov-fail-under=95
+```
+
+The integration tests need Docker (they start RabbitMQ with the platform's policy through testcontainers):
+
+```bash
+uv run pytest -m integration -q
+```
+
+Add dependencies with `uv add` from this directory, never by editing `pyproject.toml`.

async_task_api_worker-0.1.0rc2/README.md

@@ -0,0 +1,248 @@
+# async-task-api-worker
+
+SDK to write workers for the AsyncTaskAPI platform.
+
+This is a work in progress: the package ships the protocol models (inbound envelope decoder and the byte-exact
+outbound message encoder), the error types, the settings, the runtime engine with the `Worker` definition API, the
+RabbitMQ transport, the process lifecycle (graceful drain), the probes, the metrics and the JSON logs. The conformance
+kit and the extras land in later releases.
+
+## Declaring a worker
+
+```python
+from pydantic import BaseModel, Field
+
+from async_task_api_worker import TaskContext, Worker
+
+
+class Input(BaseModel):
+    text: str = Field(min_length=1, max_length=100_000)
+
+
+class Output(BaseModel):
+    words: int
+
+
+worker = Worker("count-words")
+
+
+@worker.task(timeout=30.0)
+async def handle(task_input: Input, ctx: TaskContext) -> Output:
+    await ctx.progress(0.5)
+    return Output(words=len(task_input.text.split()))
+```
+
+- `async def` handlers run on the event loop; `def` handlers (with a `SyncTaskContext`) run in a thread pool. The
+  context parameter must be annotated exactly `TaskContext` or `SyncTaskContext` (an identity check: no subclass or
+  `Annotated` wrapper). Hooks and probes (`on_startup`, `on_shutdown`, `readiness_probe`) must be `async def`.
+- The input and output models are read from the annotations. Exactly one task per worker.
+- Raise `FatalError(code, message)` to fail a task with a code the client can match, `RetryableError` for a
+  transient failure. Any other exception is reported as `INTERNAL_ERROR` without its text.
+- `ctx.progress(fraction, payload)` reports the **latest state** of the task, not an event stream: updates are
+  throttled (at most one per `WORKER_PROGRESS_MIN_INTERVAL_S`, default 1 s), a newer update replaces a held one,
+  `fraction` is in `[0, 1)` and never goes back. The terminal success or failure message is the 100%.
+
+## Running a worker
+
+```bash
+export BROKER_URL=amqp://user:password@broker:5672/ IN_QUEUE_NAME=count-words_queue_in OUT_QUEUE_NAME=count-words_queue_out
+async-task-api-worker run my_module:worker      # or: python -m async_task_api_worker run my_module:worker
+```
+
+`my_module:worker` is a `Worker`, or a zero-argument factory function returning one; modules in the current directory can
+be imported. A definition error in the module exits with code 2 and one line. From code, `worker.run()` blocks until the
+process is stopped and `await worker.serve()` serves from an existing event loop.
+
+- The settings are read and validated first: an invalid configuration, or a task timeout that does not fit under the
+  broker's consumer timeout (`task timeout + WORKER_RETRY_BACKOFF_MAX_S + 60 s < WORKER_CONSUMER_TIMEOUT_S`), exits with
+  code 2 before any connection. Exit codes: 0 clean stop, 1 failure, 2 configuration or usage error.
+- The queues are declared durable and with no arguments (the broker decides their type and policies), and consumed with
+  manual acknowledgements: a task is acked only after its result is published.
+- SIGTERM or SIGINT stops consuming, lets the in-flight tasks finish within `WORKER_SHUTDOWN_GRACE_S` (default 25 s),
+  requeues the ones that did not, closes the connection and exits 0. A second signal skips the rest of the grace period.
+  A `def` handler whose thread is still running after the drain, or an `async def` handler whose `asyncio.to_thread`
+  thread is (given 2 s after the drain), is logged and the process exits at once with code 1 (only for `run`, never for
+  `serve()`). The whole shutdown is bounded: the process exits at most
+  `max(WORKER_SHUTDOWN_GRACE_S, 5)` + 17 s after the signal (5 s for the nacks of the cancelled tasks, 5 s to close the
+  connection, and 5 s in total, `WORKER_SHUTDOWN_HOOKS_TIMEOUT_S`, for all the shutdown hooks together, each getting what is
+  left). Set a pod's `terminationGracePeriodSeconds` to at least that. A signal during startup does not wait for it: the
+  connection attempt and the startup hooks are cancelled and the process exits 0 (a hook that blocks the event loop
+  cannot be interrupted).
+- **Retries and crash-loop protection need quorum queues** (the broker's default queue type, as in the platform's
+  chart). A classic queue gives no delivery counter: there, a `RetryableError` gets one retry, then concludes with its
+  own code, and a warning says so.
+- Refused broker credentials exit with code 2 right away instead of being retried.
+- The attempt number of a delivery (`ctx.attempt`) counts every time the broker handed the message out. A
+  `RetryableError` requeues until attempt `WORKER_DELIVERY_LIMIT`, then concludes with its own code. A delivery past
+  that limit (a crash loop) is concluded with `TASK_ABANDONED_AFTER_REDELIVERIES` without running the handler.
+
+## Probes, metrics and logs
+
+A small HTTP server runs on `HEALTH_CHECK_HOST:HEALTH_CHECK_PORT` (default `0.0.0.0:8083`) in both modes, from the very
+start of the process until the end of the shutdown.
+
+| Path | Answer |
+|---|---|
+| `GET /health` | Liveness. 200 `{"status": "ok"}`, or 503 `TASK_OVERRUN` when a `def` handler is still running `WORKER_TASK_OVERRUN_GRACE_S` after its deadline. It consults no dependency. |
+| `GET /ready` | Readiness. 200 with a `components` map, or 503 `DEPENDENCIES_NOT_READY` (with the same `components` in `error`) when the broker is disconnected, the worker is draining, or one of the probes registered with `@worker.readiness_probe("name")` raises or exceeds `WORKER_PROBE_TIMEOUT_S` (3 s). Probes run in parallel. A `ProbeError` message is shown as the detail; any other exception only by its class name. |
+| `GET /metrics`, `GET /internal/metrics` | Prometheus text exposition. |
+| `GET /__version__` | `/app/version.json` of the image, or a `dev` document. |
+
+Errors use the platform's format, `{"status": "error", "error": {"code", "message"}}` (404 `NOT_FOUND`, 405
+`METHOD_NOT_ALLOWED`, 500 `PROBE_FAILED`). `broker` and `draining` are reserved component names. `/ready` is also 503 in
+job mode once the quota is reached and the consumer cancelled.
+
+The server is bounded: at most 32 connections are served at once (the others are closed at once), reading the request,
+writing the answer and closing each take at most 5 s, and concurrent `/ready` requests share a single evaluation of the
+probes.
+
+**Startup.** `/health` answers while the startup hooks run, but only as long as the event loop is free: a hook that loads a
+model or a large file synchronously blocks it, `/health` stops answering and the kubelet restarts the pod in a loop. Run
+heavy loading in `asyncio.to_thread`, or give the container a `startupProbe`.
+
+Metrics have no task, client or service label (the scrape adds the pod and service): `worker_tasks_total{status}`,
+`worker_task_duration_seconds`, `worker_messages_published_total{message_type}`, `event_loop_lag_seconds{component}`,
+`worker_task_failures_total{code}`, `worker_task_retries_total`, `worker_poison_messages_total{reason}`,
+`worker_publish_failures_total{message_type}`, `worker_ack_failures_total`, `worker_tasks_in_flight`,
+`worker_shutdown_requeued_total`, `worker_progress_dropped_total{reason}` and `worker_sdk_info`, plus the process, platform
+and GC collectors.
+
+Logs are one JSON object per line on stdout (`ts`, `level`, `logger`, `msg`, and `task_id`, `service`, `attempt` when
+bound; `ctx.logger` carries them, and so do the records of any library logging inside a handler, on the SDK's handler).
+`LOG_LEVEL` sets the level. If the application configured the root logger before running the worker, its handlers are
+kept and the SDK adds none (no line is printed twice): the format is then the application's, and so is the level of
+the `aio_pika.tools` logger, whose two ERROR lines on a dropped connection the SDK otherwise logs as warnings (the
+connection then reconnects by itself). To still get the task fields on your own handler, chain a record factory:
+
+```python
+import logging
+from async_task_api_worker.observability.logging import TaskContextFilter
+
+task_fields = TaskContextFilter()
+previous_factory = logging.getLogRecordFactory()
+
+
+def factory(*args, **kwargs):
+    record = previous_factory(*args, **kwargs)
+    task_fields.filter(record)
+    return record
+
+
+logging.setLogRecordFactory(factory)
+```
+
+Every delivery ends with exactly one INFO decision line, for instance `Delivery settled: outcome=failure action=conclude
+code=NOT_ALLOWED attempt=1/5`, with the fields `task_id`, `attempt`, `delivery_limit`, `outcome` (`success`, `failure`,
+`poison`, `retry`, `publish_failed`, `shutdown_requeued`, `cancelled`, `engine_error`), `action` (`ack`, `conclude`,
+`nack-requeue`) and `code`: `grep <task_id>`
+tells the whole story of a task. Payloads and secrets are never logged.
+
+## Deployment or Job
+
+The same worker code and image run as a long-lived consumer (a Kubernetes Deployment) or as a one-shot process (a
+Job, for instance one started per message by KEDA's `ScaledJob`). The deployment picks the mode with `WORKER_MODE`; the
+`Worker` definition does not change.
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `WORKER_MODE` | `service` | `service` consumes until SIGTERM; `job` is one-shot. Any other value exits with code 2. |
+| `WORKER_JOB_MAX_TASKS` | `1` | Job mode: stop consuming at this many deliveries, finish them, and exit. |
+| `WORKER_JOB_IDLE_TIMEOUT_S` | `10` | Job mode: exit when no delivery is in hand and none arrives for this long (another pod probably took the message). |
+| `WORKER_JOB_CONNECT_TIMEOUT_S` | `30` | Job mode: give up and exit 1 when the broker stays unreachable for this long. Service mode retries forever. |
+
+In job mode the prefetch is forced to 1, whatever `WORKER_CONCURRENCY` says (it then only sizes the handler semaphore
+and the thread pool). The quota counts deliveries **on arrival**: any delivery counts, poison ones and redeliveries past
+the limit included, and consuming stops as soon as the last one is in hand. The exit code reports the **pod**, not the
+task: a task that succeeds, fails (`FatalError`, timeout, invalid input), or is requeued (`RetryableError`) all exit 0,
+and so does an idle exit, because a failed task is a business outcome already published to the client. Exit 1 (an
+infrastructure failure such as a broker unreachable for `WORKER_JOB_CONNECT_TIMEOUT_S`, or a `def` handler stuck after
+the drain) and 2 (invalid configuration) stay non-zero, so the Job's `backoffLimit` applies to them. SIGTERM and
+`activeDeadlineSeconds` drain exactly as in service mode.
+
+## Testing your worker
+
+`async_task_api_worker.testing` runs your task in memory through the real engine (decoding, time limit, retries, error
+mapping, acknowledgements), with no broker and no Docker:
+
+```python
+from pydantic import BaseModel
+
+from async_task_api_worker import FatalError, TaskContext, Worker
+from async_task_api_worker.testing import Outcome, ProgressRecorder, WorkerHarness, make_task_context
+
+
+class Input(BaseModel):
+    text: str
+
+
+class Output(BaseModel):
+    words: int
+
+
+worker = Worker("count-words")
+
+
+@worker.task(timeout=30.0)
+async def handle(task_input: Input, ctx: TaskContext) -> Output:
+    if not task_input.text.strip():
+        raise FatalError("EMPTY_TEXT", "There is nothing to count.")
+    await ctx.progress(0.5)
+    return Output(words=len(task_input.text.split()))
+
+
+async def test_counts_the_words() -> None:
+    async with WorkerHarness(worker) as harness:
+        run = await harness.submit({"text": "hello big world"})
+
+    run.assert_succeeded()
+    assert run.response == {"words": 3}
+    assert run.message_types == ("started", "progress", "success")
+
+
+async def test_an_empty_text_fails_with_its_code() -> None:
+    async with WorkerHarness(worker) as harness:
+        run = await harness.submit({"text": "  "})
+
+    run.assert_failed(code="EMPTY_TEXT")
+    assert run.outcome is Outcome.ACKED
+
+
+async def test_the_handler_alone_with_a_context_you_build() -> None:
+    recorder = ProgressRecorder()
+    ctx = make_task_context(recorder=recorder)
+
+    assert await handle(Input(text="a b"), ctx) == Output(words=2)
+    assert [update.fraction for update in recorder.updates] == [0.5]
+```
+
+- `harness.submit(body, client_id=..., input_refs=..., delivery_count=...)` builds the envelope the API publishes;
+  `submit_raw(bytes)` sends bytes as they are (a poison message). The result is a `TaskRun`: `messages` (decoded) and
+  `raw` (the published bytes), `message_types` (all three are tuples), `outcome` (`ACKED`, `NACKED_REQUEUE`), `response`,
+  `error`, and the two assertions. `task_id` is the envelope's, or `None` for bytes that do not carry one.
+- `delivery_count` is the broker's `x-delivery-count`: pass `0`, then `delivery_count=n` to see a `RetryableError`
+  requeue until the last attempt (`worker_delivery_limit`), which concludes with the error's own code. Retry backoffs are
+  a millisecond; every other setting is the production default (progress throttling included).
+- `settings_overrides={"worker_task_timeout_s": 0.1, ...}` takes `WorkerSettings` field names; no environment variable is
+  read, and the time budget is checked as at startup. `harness.fail_next_publish("success")` makes the next publish (of
+  that message type, or of any) fail once, to test the requeue. Use `async with` (or `await harness.aclose()`).
+- `make_task_context` and `make_sync_task_context` build the context of an `async def` and of a `def` handler, to call
+  the handler directly; `ProgressRecorder` collects what it reports.
+
+## Development
+
+From this directory:
+
+```bash
+uv sync --locked --all-extras
+uv run ruff check . && uv run ruff format --check .
+uv run ty check src
+uv run pytest -m "not integration" -q --cov=async_task_api_worker --cov-branch --cov-fail-under=95
+```
+
+The integration tests need Docker (they start RabbitMQ with the platform's policy through testcontainers):
+
+```bash
+uv run pytest -m integration -q
+```
+
+Add dependencies with `uv add` from this directory, never by editing `pyproject.toml`.