US02-03: Execute Jobs with Leases, Locks, and Recovery (#56)

photo_pipeline/jobs/handlers.py

@@ -0,0 +1,54 @@
+"""Job-type handler dispatch.
+
+A handler processes one item of a job: ``handler(item_key, ctx)`` and either
+returns (success), raises ``Cancelled`` (cooperative stop, resumable), or raises
+any other exception (item failure). Handlers must be idempotent — at-least-once
+delivery means the same item can run again after an interrupted attempt.
+
+Domain handlers (safety scoring, analysis, …) register here in later stories; the
+registry ships empty so the worker engine can be built and tested independently.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Callable
+
+if TYPE_CHECKING:
+    from photo_pipeline.services.jobs import JobService
+
+Handler = Callable[[str, "JobContext"], None]
+
+
+class Cancelled(Exception):
+    """Raised by a handler that observed cancellation and stopped cleanly."""
+
+
+@dataclass
+class JobContext:
+    """What a handler needs from the coordinator: cancellation checks and heartbeats."""
+
+    job_id: str
+    worker_id: str
+    fencing_token: int
+    service: "JobService"
+
+    def cancelled(self) -> bool:
+        from photo_pipeline.services.jobs import JobState
+
+        snapshot = self.service.get(self.job_id)
+        return snapshot is None or snapshot["state"] in (
+            JobState.CANCELLING,
+            JobState.CANCELLED,
+        )
+
+    def heartbeat(self, *, lease_seconds: int = 60) -> bool:
+        return self.service.heartbeat(self.job_id, self.worker_id, lease_seconds=lease_seconds)
+
+
+# Populated by domain stories via register(); empty for now.
+REGISTRY: dict[str, Handler] = {}
+
+
+def register(job_type: str, handler: Handler) -> None:
+    REGISTRY[job_type] = handler