milvaion-worker 1.0.0__tar.gz

milvaion_worker-1.0.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+build/
+.pytest_cache/

milvaion_worker-1.0.0/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.5
+Name: milvaion-worker
+Version: 1.0.0
+Summary: Python worker SDK for the Milvaion job scheduler
+Project-URL: Homepage, https://github.com/Milvasoft/milvaion
+Project-URL: Source, https://github.com/Milvasoft/milvaion/tree/master/sdks/python/milvaion-worker
+License-Expression: Apache-2.0
+Keywords: cron,job-scheduler,milvaion,rabbitmq,worker
+Classifier: Framework :: AsyncIO
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: aio-pika>=9.4
+Requires-Dist: redis>=5.0
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# Milvaion Python Worker SDK
+
+Run [Milvaion](https://github.com/Milvasoft/milvaion) jobs in Python. A Python worker shows up in the dashboard like a .NET worker. The scheduler dispatches jobs to it, and the dashboard shows its live logs, status, retries, cancellation and timeouts.
+
+```bash
+pip install milvaion-worker
+```
+
+It requires Python 3.10 or later, and connects to the same RabbitMQ and Redis instances as your Milvaion API.
+
+## Quick start
+
+```python
+from milvaion import JobContext, PermanentJobError, Worker
+
+worker = Worker(
+    worker_id="report-worker",
+    rabbitmq_url="amqp://guest:guest@localhost:5672/",
+    redis_url="redis://localhost:6379",
+)
+
+
+@worker.job("BuildReportJob", max_retries=3, execution_timeout=600)
+async def build_report(ctx: JobContext) -> dict:
+    data = ctx.data or {}
+
+    if "month" not in data:
+        raise PermanentJobError('Job data needs "month".')  # no retries, straight to the DLQ
+
+    ctx.log(f"Building the report for {data['month']}")
+    rows = await fetch_rows(data["month"])  # cancelled if the job is cancelled or times out
+
+    return {"rows": len(rows)}  # shown as the occurrence result
+
+
+@worker.job("CleanupJob")
+def cleanup(ctx: JobContext) -> None:  # plain functions run in a thread
+    for path in old_files():
+        ctx.raise_if_aborted()  # threads cannot be stopped from outside; check in long loops
+        path.unlink()
+
+
+if __name__ == "__main__":
+    worker.run()  # blocks; SIGINT/SIGTERM shut down gracefully
+```
+
+Then create a job in the dashboard: pick the worker `report-worker` and the job `BuildReportJob`, and set a schedule.
+
+To run the worker inside your own event loop, call `await worker.start()` and `await worker.stop()` instead of `run()`.
+
+## Jobs
+
+`@worker.job(name, **options)` or `worker.add_job(name, handler, JobOptions(...))` registers a handler under the name the dashboard dispatches it by. Names are unique within a worker and matched case-insensitively.
+
+Handlers can be `async def` or plain functions. A plain function runs in a thread, so blocking code does not stall other jobs.
+
+The handler receives a `JobContext`:
+
+| Member | Description |
+|---|---|
+| `ctx.data` | Parsed job data, or `None`. Data that is not valid JSON fails the job permanently. |
+| `ctx.raw_data` | Job data as the raw JSON string. |
+| `ctx.occurrence_id` | Id of this execution. It stays the same across retries and redeliveries, so you can use it as an idempotency key. |
+| `ctx.retry_count` | `0` on the first attempt, then `1`, `2` and so on. |
+| `ctx.is_aborted`, `ctx.abort_reason`, `ctx.raise_if_aborted()` | Whether the job was cancelled, timed out or interrupted by shutdown. |
+| `ctx.log` / `debug` / `warn` / `error(message, error=None, data=None)` | Write to the occurrence log in the dashboard. |
+| `ctx.job` | The scheduled job as the API sent it. |
+
+How the handler ends decides the outcome:
+
+| The handler... | Outcome |
+|---|---|
+| returns a value | `Completed`. A string is stored as-is; anything else is stored as JSON. |
+| raises | Retried with exponential backoff. After `max_retries`, the occurrence is `Failed` and the job goes to the dead letter queue. |
+| raises `PermanentJobError` | `Failed` without retrying, and the job goes to the dead letter queue. |
+| runs past its timeout | `TimedOut` |
+| is cancelled from the dashboard | `Cancelled` |
+| is still running when the worker stops | The job goes back to the queue and runs again. |
+
+When a job is aborted, an `async` handler is cancelled, so it gets `asyncio.CancelledError` at its next `await`. A plain function cannot be stopped from outside. The occurrence still settles right away, but the thread keeps running until the function returns, so check `ctx.raise_if_aborted()` in long loops.
+
+### Job options
+
+| Option | Default | Description |
+|---|---|---|
+| `max_parallel_jobs` | min(10, worker `max_parallel_jobs`) | Jobs of this type that may run at once on this instance |
+| `execution_timeout` | worker default (3600 s) | Seconds. `0` disables the timeout. A timeout set on the job in the dashboard takes precedence. |
+| `max_retries` | 3 | Retries after the first failure |
+| `base_retry_delay` | 5 | Retry *n* waits `base × 2^(n-1)` seconds |
+| `data_schema` | none | JSON Schema of the job data, as a dict or string. The dashboard builds the job data form from it; with Pydantic, use `Model.model_json_schema()`. |
+| `result_schema` | none | JSON Schema of the result |
+| `routing_pattern` | `{worker_id}.{name without "Job"}.*` | RabbitMQ routing pattern |
+| `consumer_id` | `{name without "Job"}-consumer` | Shown in the dashboard |
+
+## Worker options
+
+Pass these to `Worker(...)` or `WorkerOptions(...)`:
+
+| Option | Default | Description |
+|---|---|---|
+| `worker_id` | required | Identifies the worker application. Use the same value on every replica. |
+| `rabbitmq_url` | `amqp://guest:guest@localhost:5672/` | |
+| `queue_type` | `classic` | Must match the API's `MilvaionConfig:RabbitMQ:QueueType` |
+| `redis_url` | `redis://localhost:6379` | Redis only carries cancellation requests. `None` disables them. |
+| `redis_key_prefix` | `Milvaion:JobScheduler:` | Must match the API's `MilvaionConfig:Redis:KeyPrefix` |
+| `max_parallel_jobs` | CPU count × 2 | Capacity reported for this instance |
+| `execution_timeout` | 3600 | Default job timeout in seconds |
+| `heartbeat_interval` | 30 | |
+| `job_heartbeat_interval` | 60 | Keeps long jobs from being flagged as zombies |
+| `shutdown_timeout` | 30 | How long `stop()` lets running jobs finish |
+| `startup_timeout` | 30 | How long `start()` waits for RabbitMQ and Redis |
+| `version` | `1.0.0` | Shown in the dashboard |
+| `logger` | `logging.getLogger("milvaion")` | |
+
+For containers, `Worker(WorkerOptions.from_env())` reads the following variables:
+
+- `MILVAION_WORKER_ID`
+- `MILVAION_RABBITMQ_URL`
+- `MILVAION_RABBITMQ_QUEUE_TYPE`
+- `MILVAION_REDIS_URL` (`false` disables Redis)
+- `MILVAION_REDIS_KEY_PREFIX`
+- `MILVAION_MAX_PARALLEL_JOBS`
+- `MILVAION_EXECUTION_TIMEOUT_SECONDS`
+- `MILVAION_HEARTBEAT_INTERVAL_SECONDS`
+
+## Reliability
+
+- **Reconnects.** If RabbitMQ goes away, the connection is restored with its queues and consumers, and the worker registers again. The Redis listener reconnects and resubscribes.
+- **At-least-once delivery.** A message is acknowledged only after its outcome has been reported, so a crash makes the job run again. Make handlers idempotent; `ctx.occurrence_id` helps with that.
+- **Graceful shutdown.** `stop()` does the following in order:
+  1. Stops taking new jobs.
+  2. Waits up to `shutdown_timeout` for running jobs to finish.
+  3. Returns the jobs that are still running to the queue.
+  4. Flushes logs and tells the API the instance has left.
+
+## How it works
+
+The SDK implements the language-neutral [worker protocol](https://github.com/Milvasoft/milvaion/blob/master/docs/githubdocs/WORKER-PROTOCOL.md): the RabbitMQ queues and message formats the .NET SDK uses.
+
+## Development
+
+```bash
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[test]"
+pytest
+python examples/basic_worker.py   # configure with MILVAION_* variables
+```

milvaion_worker-1.0.0/README.md

@@ -0,0 +1,147 @@
+# Milvaion Python Worker SDK
+
+Run [Milvaion](https://github.com/Milvasoft/milvaion) jobs in Python. A Python worker shows up in the dashboard like a .NET worker. The scheduler dispatches jobs to it, and the dashboard shows its live logs, status, retries, cancellation and timeouts.
+
+```bash
+pip install milvaion-worker
+```
+
+It requires Python 3.10 or later, and connects to the same RabbitMQ and Redis instances as your Milvaion API.
+
+## Quick start
+
+```python
+from milvaion import JobContext, PermanentJobError, Worker
+
+worker = Worker(
+    worker_id="report-worker",
+    rabbitmq_url="amqp://guest:guest@localhost:5672/",
+    redis_url="redis://localhost:6379",
+)
+
+
+@worker.job("BuildReportJob", max_retries=3, execution_timeout=600)
+async def build_report(ctx: JobContext) -> dict:
+    data = ctx.data or {}
+
+    if "month" not in data:
+        raise PermanentJobError('Job data needs "month".')  # no retries, straight to the DLQ
+
+    ctx.log(f"Building the report for {data['month']}")
+    rows = await fetch_rows(data["month"])  # cancelled if the job is cancelled or times out
+
+    return {"rows": len(rows)}  # shown as the occurrence result
+
+
+@worker.job("CleanupJob")
+def cleanup(ctx: JobContext) -> None:  # plain functions run in a thread
+    for path in old_files():
+        ctx.raise_if_aborted()  # threads cannot be stopped from outside; check in long loops
+        path.unlink()
+
+
+if __name__ == "__main__":
+    worker.run()  # blocks; SIGINT/SIGTERM shut down gracefully
+```
+
+Then create a job in the dashboard: pick the worker `report-worker` and the job `BuildReportJob`, and set a schedule.
+
+To run the worker inside your own event loop, call `await worker.start()` and `await worker.stop()` instead of `run()`.
+
+## Jobs
+
+`@worker.job(name, **options)` or `worker.add_job(name, handler, JobOptions(...))` registers a handler under the name the dashboard dispatches it by. Names are unique within a worker and matched case-insensitively.
+
+Handlers can be `async def` or plain functions. A plain function runs in a thread, so blocking code does not stall other jobs.
+
+The handler receives a `JobContext`:
+
+| Member | Description |
+|---|---|
+| `ctx.data` | Parsed job data, or `None`. Data that is not valid JSON fails the job permanently. |
+| `ctx.raw_data` | Job data as the raw JSON string. |
+| `ctx.occurrence_id` | Id of this execution. It stays the same across retries and redeliveries, so you can use it as an idempotency key. |
+| `ctx.retry_count` | `0` on the first attempt, then `1`, `2` and so on. |
+| `ctx.is_aborted`, `ctx.abort_reason`, `ctx.raise_if_aborted()` | Whether the job was cancelled, timed out or interrupted by shutdown. |
+| `ctx.log` / `debug` / `warn` / `error(message, error=None, data=None)` | Write to the occurrence log in the dashboard. |
+| `ctx.job` | The scheduled job as the API sent it. |
+
+How the handler ends decides the outcome:
+
+| The handler... | Outcome |
+|---|---|
+| returns a value | `Completed`. A string is stored as-is; anything else is stored as JSON. |
+| raises | Retried with exponential backoff. After `max_retries`, the occurrence is `Failed` and the job goes to the dead letter queue. |
+| raises `PermanentJobError` | `Failed` without retrying, and the job goes to the dead letter queue. |
+| runs past its timeout | `TimedOut` |
+| is cancelled from the dashboard | `Cancelled` |
+| is still running when the worker stops | The job goes back to the queue and runs again. |
+
+When a job is aborted, an `async` handler is cancelled, so it gets `asyncio.CancelledError` at its next `await`. A plain function cannot be stopped from outside. The occurrence still settles right away, but the thread keeps running until the function returns, so check `ctx.raise_if_aborted()` in long loops.
+
+### Job options
+
+| Option | Default | Description |
+|---|---|---|
+| `max_parallel_jobs` | min(10, worker `max_parallel_jobs`) | Jobs of this type that may run at once on this instance |
+| `execution_timeout` | worker default (3600 s) | Seconds. `0` disables the timeout. A timeout set on the job in the dashboard takes precedence. |
+| `max_retries` | 3 | Retries after the first failure |
+| `base_retry_delay` | 5 | Retry *n* waits `base × 2^(n-1)` seconds |
+| `data_schema` | none | JSON Schema of the job data, as a dict or string. The dashboard builds the job data form from it; with Pydantic, use `Model.model_json_schema()`. |
+| `result_schema` | none | JSON Schema of the result |
+| `routing_pattern` | `{worker_id}.{name without "Job"}.*` | RabbitMQ routing pattern |
+| `consumer_id` | `{name without "Job"}-consumer` | Shown in the dashboard |
+
+## Worker options
+
+Pass these to `Worker(...)` or `WorkerOptions(...)`:
+
+| Option | Default | Description |
+|---|---|---|
+| `worker_id` | required | Identifies the worker application. Use the same value on every replica. |
+| `rabbitmq_url` | `amqp://guest:guest@localhost:5672/` | |
+| `queue_type` | `classic` | Must match the API's `MilvaionConfig:RabbitMQ:QueueType` |
+| `redis_url` | `redis://localhost:6379` | Redis only carries cancellation requests. `None` disables them. |
+| `redis_key_prefix` | `Milvaion:JobScheduler:` | Must match the API's `MilvaionConfig:Redis:KeyPrefix` |
+| `max_parallel_jobs` | CPU count × 2 | Capacity reported for this instance |
+| `execution_timeout` | 3600 | Default job timeout in seconds |
+| `heartbeat_interval` | 30 | |
+| `job_heartbeat_interval` | 60 | Keeps long jobs from being flagged as zombies |
+| `shutdown_timeout` | 30 | How long `stop()` lets running jobs finish |
+| `startup_timeout` | 30 | How long `start()` waits for RabbitMQ and Redis |
+| `version` | `1.0.0` | Shown in the dashboard |
+| `logger` | `logging.getLogger("milvaion")` | |
+
+For containers, `Worker(WorkerOptions.from_env())` reads the following variables:
+
+- `MILVAION_WORKER_ID`
+- `MILVAION_RABBITMQ_URL`
+- `MILVAION_RABBITMQ_QUEUE_TYPE`
+- `MILVAION_REDIS_URL` (`false` disables Redis)
+- `MILVAION_REDIS_KEY_PREFIX`
+- `MILVAION_MAX_PARALLEL_JOBS`
+- `MILVAION_EXECUTION_TIMEOUT_SECONDS`
+- `MILVAION_HEARTBEAT_INTERVAL_SECONDS`
+
+## Reliability
+
+- **Reconnects.** If RabbitMQ goes away, the connection is restored with its queues and consumers, and the worker registers again. The Redis listener reconnects and resubscribes.
+- **At-least-once delivery.** A message is acknowledged only after its outcome has been reported, so a crash makes the job run again. Make handlers idempotent; `ctx.occurrence_id` helps with that.
+- **Graceful shutdown.** `stop()` does the following in order:
+  1. Stops taking new jobs.
+  2. Waits up to `shutdown_timeout` for running jobs to finish.
+  3. Returns the jobs that are still running to the queue.
+  4. Flushes logs and tells the API the instance has left.
+
+## How it works
+
+The SDK implements the language-neutral [worker protocol](https://github.com/Milvasoft/milvaion/blob/master/docs/githubdocs/WORKER-PROTOCOL.md): the RabbitMQ queues and message formats the .NET SDK uses.
+
+## Development
+
+```bash
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[test]"
+pytest
+python examples/basic_worker.py   # configure with MILVAION_* variables
+```

milvaion_worker-1.0.0/examples/basic_worker.py

@@ -0,0 +1,61 @@
+"""Sample Milvaion worker.
+
+    MILVAION_WORKER_ID=py-sample-worker \
+    MILVAION_RABBITMQ_URL=amqp://guest:guest@localhost:5672 \
+    MILVAION_REDIS_URL=redis://localhost:6379 \
+    python examples/basic_worker.py
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+
+from milvaion import JobContext, PermanentJobError, Worker, WorkerOptions
+
+logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(name)s: %(message)s")
+
+worker = Worker(WorkerOptions.from_env(
+    worker_id=os.environ.get("MILVAION_WORKER_ID", "py-sample-worker"),
+    heartbeat_interval=5,
+))
+
+
+@worker.job(
+    "GreetJob",
+    execution_timeout=60,
+    data_schema={
+        "type": "object",
+        "properties": {
+            "name": {"type": "string", "description": "Who to greet"},
+            "delayMs": {"type": "integer", "description": "How long the job takes"},
+        },
+        "required": ["name"],
+    },
+)
+async def greet(ctx: JobContext) -> dict:
+    data = ctx.data or {}
+
+    if not data.get("name"):
+        raise PermanentJobError('Job data needs a "name".')
+
+    ctx.log(f"Greeting {data['name']}", {"attempt": ctx.retry_count + 1})
+
+    # Cancelled from the dashboard or by a timeout: asyncio cancels this await.
+    await asyncio.sleep(data.get("delayMs", 1000) / 1000)
+
+    return {"greeting": f"Hello, {data['name']}!"}
+
+
+@worker.job("FlakyJob", max_retries=2, base_retry_delay=2)
+def flaky(ctx: JobContext) -> None:
+    # A plain function runs in a thread. Fails on the first attempt to show retries in the dashboard.
+    if ctx.retry_count == 0:
+        raise RuntimeError("Simulated transient failure")
+
+    ctx.log("Succeeded on retry")
+
+
+if __name__ == "__main__":
+    worker.run()

milvaion_worker-1.0.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "milvaion-worker"
+version = "1.0.0"
+description = "Python worker SDK for the Milvaion job scheduler"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.10"
+keywords = ["milvaion", "job-scheduler", "worker", "rabbitmq", "cron"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Framework :: AsyncIO",
+    "Typing :: Typed",
+]
+dependencies = [
+    "aio-pika>=9.4",
+    "redis>=5.0",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=8", "pytest-asyncio>=0.23"]
+
+[project.urls]
+Homepage = "https://github.com/Milvasoft/milvaion"
+Source = "https://github.com/Milvasoft/milvaion/tree/master/sdks/python/milvaion-worker"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/milvaion"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]
+pythonpath = ["src"]

milvaion_worker-1.0.0/src/milvaion/__init__.py

@@ -0,0 +1,22 @@
+"""Python worker SDK for the Milvaion job scheduler."""
+
+from .context import JobContext
+from .errors import AbortReason, JobAborted, PermanentJobError
+from .options import JobOptions, WorkerOptions, generate_routing_pattern, queue_name_for_pattern
+from .protocol import SDK_VERSION, Status
+from .worker import Worker
+
+__all__ = [
+    "AbortReason",
+    "JobAborted",
+    "JobContext",
+    "JobOptions",
+    "PermanentJobError",
+    "Status",
+    "Worker",
+    "WorkerOptions",
+    "generate_routing_pattern",
+    "queue_name_for_pattern",
+]
+
+__version__ = SDK_VERSION

milvaion_worker-1.0.0/src/milvaion/cancellation.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import logging
+from typing import Any
+
+from redis import asyncio as aioredis
+
+from .processor import CancellationRegistry
+
+
+class CancellationListener:
+    """Receives the cancellation requests the API publishes on Redis."""
+
+    def __init__(self, url: str, channel: str, registry: CancellationRegistry, logger: logging.Logger) -> None:
+        self._url = url
+        self._channel = channel
+        self._registry = registry
+        self._logger = logger
+        self._client: Any = None
+        self._task: asyncio.Task[None] | None = None
+
+    async def start(self) -> None:
+        self._client = aioredis.from_url(self._url, decode_responses=True, health_check_interval=30)
+        await self._client.ping()
+
+        pubsub = self._client.pubsub(ignore_subscribe_messages=True)
+        await pubsub.subscribe(self._channel)
+
+        self._task = asyncio.get_running_loop().create_task(self._listen(pubsub))
+        self._logger.info("Listening for cancellations on %s", self._channel)
+
+    async def _listen(self, pubsub: Any) -> None:
+        while True:
+            try:
+                async for message in pubsub.listen():
+                    if message.get("type") == "message":
+                        self._on_message(message.get("data"))
+            except asyncio.CancelledError:
+                with contextlib.suppress(Exception):
+                    await pubsub.aclose()
+                raise
+            except Exception as error:  # noqa: BLE001 - reconnect and resubscribe
+                self._logger.warning("Redis cancellation listener error: %s. Reconnecting...", error)
+                await asyncio.sleep(2)
+
+                with contextlib.suppress(Exception):
+                    await pubsub.subscribe(self._channel)
+
+    def _on_message(self, payload: Any) -> None:
+        try:
+            request = json.loads(payload)
+        except (TypeError, ValueError):
+            self._logger.debug("Ignored a cancellation message that is not JSON.")
+            return
+
+        if not isinstance(request, dict):
+            return
+
+        occurrence_id = request.get("CorrelationId") or request.get("OccurrenceId")
+
+        if occurrence_id and self._registry.cancel(occurrence_id, request.get("Reason")):
+            self._logger.info("Cancelling occurrence %s: %s", occurrence_id, request.get("Reason") or "no reason given")
+
+    async def stop(self) -> None:
+        if self._task is not None:
+            self._task.cancel()
+
+            with contextlib.suppress(BaseException):
+                await self._task
+
+        if self._client is not None:
+            with contextlib.suppress(Exception):
+                await self._client.aclose()

milvaion_worker-1.0.0/src/milvaion/context.py

@@ -0,0 +1,152 @@
+from __future__ import annotations
+
+import json
+import threading
+from collections.abc import Callable
+from datetime import datetime, timezone
+from typing import Any
+
+from .errors import AbortReason, JobAborted, PermanentJobError, _type_name, format_error
+
+
+def utc_now() -> str:
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+class _Abort:
+    """Abort state of one execution. Readable from handler threads."""
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self.reason: AbortReason | None = None
+        self.message = ""
+        self._listeners: list[Callable[[], None]] = []
+
+    def trigger(self, reason: AbortReason, message: str) -> bool:
+        with self._lock:
+            if self.reason is not None:
+                return False
+
+            self.reason, self.message = reason, message
+            listeners = list(self._listeners)
+
+        for listener in listeners:
+            listener()
+
+        return True
+
+    def on_abort(self, listener: Callable[[], None]) -> None:
+        with self._lock:
+            if self.reason is None:
+                self._listeners.append(listener)
+                return
+
+        listener()
+
+
+class JobContext:
+    """What a job handler receives."""
+
+    def __init__(
+        self,
+        *,
+        occurrence_id: str,
+        job: dict[str, Any],
+        retry_count: int,
+        instance_id: str,
+        abort: _Abort,
+        sink: Callable[[dict[str, Any]], None],
+    ) -> None:
+        self.occurrence_id = occurrence_id
+        """Id of this execution. Stable across retries and redeliveries, so it works as an idempotency key."""
+        self.retry_count = retry_count
+        """0 on the first attempt, then 1, 2, ..."""
+        self.instance_id = instance_id
+        """Instance id of this worker process."""
+        self.job = job
+        """The scheduled job as the API sent it."""
+        self._abort = abort
+        self._sink = sink
+        self._data: Any = None
+        self._parsed = False
+
+    @property
+    def job_id(self) -> str:
+        return self.job["id"]
+
+    @property
+    def job_name(self) -> str:
+        return self.job["jobNameInWorker"]
+
+    @property
+    def raw_data(self) -> str | None:
+        """Job data as the raw JSON string, or None."""
+        return self.job.get("jobData")
+
+    @property
+    def data(self) -> Any:
+        """Parsed job data, or None when the job has none. Invalid JSON fails the job permanently."""
+        if not self._parsed:
+            raw = (self.raw_data or "").strip()
+
+            try:
+                self._data = json.loads(raw) if raw else None
+            except json.JSONDecodeError as error:
+                raise PermanentJobError("Job data is not valid JSON.") from error
+
+            self._parsed = True
+
+        return self._data
+
+    @property
+    def is_aborted(self) -> bool:
+        """True once the job has been cancelled, has timed out or the worker is shutting down.
+
+        Async handlers are also cancelled (they get ``asyncio.CancelledError``); synchronous handlers
+        run in a thread and should check this in long loops."""
+        return self._abort.reason is not None
+
+    @property
+    def abort_reason(self) -> AbortReason | None:
+        return self._abort.reason
+
+    def raise_if_aborted(self) -> None:
+        """Raises JobAborted if the job has been aborted."""
+        if self._abort.reason is not None:
+            raise JobAborted(self._abort.reason, self._abort.message)
+
+    def log(self, message: str, data: dict[str, Any] | None = None) -> None:
+        """Writes an Information entry to the occurrence log."""
+        self._write("Information", message, data)
+
+    def debug(self, message: str, data: dict[str, Any] | None = None) -> None:
+        self._write("Debug", message, data)
+
+    def warn(self, message: str, data: dict[str, Any] | None = None) -> None:
+        self._write("Warning", message, data)
+
+    def error(self, message: str, error: BaseException | None = None, data: dict[str, Any] | None = None) -> None:
+        """Writes an Error entry, with the details of ``error`` when given."""
+        details = dict(data or {})
+        exception_type = None
+
+        if error is not None:
+            exception_type = _type_name(error)
+            details["ExceptionType"] = exception_type
+            details["StackTrace"] = format_error(error)
+            inner = error.__cause__ or error.__context__
+
+            if inner is not None:
+                details["InnerException"] = str(inner)
+
+        self._write("Error", message, details, "UserDefined", exception_type)
+
+    def _write(self, level: str, message: str, data: dict[str, Any] | None, category: str = "UserCode", exception_type: str | None = None) -> None:
+        self._sink({
+            "timestamp": utc_now(),
+            "level": level,
+            "message": message,
+            "data": data,
+            "category": category,
+            "exceptionType": exception_type,
+        })