feat(tasks): implement atomic claims and leases

backend-api/internal/usecase/lifecycle_errors.go

@@ -0,0 +1,69 @@
+package usecase
+
+import "errors"
+
+var (
+	ErrDeviceNotReady      = errors.New("device readiness is missing or stale")
+	ErrDeviceActiveTask    = errors.New("device already has an active task")
+	ErrClaimInvalid        = errors.New("task claim is invalid")
+	ErrClaimExpired        = errors.New("task claim lease expired")
+	ErrClaimReplayExpired  = errors.New("claim idempotency replay is stale")
+	ErrTaskVersionConflict = errors.New("task version conflict")
+	ErrExecutionMismatch   = errors.New("task execution does not match")
+)
+
+func wrapLifecycleRepositoryError(err error) error {
+	switch {
+	case errors.Is(err, ErrDeviceNotReady):
+		return newError(
+			ErrorKindConflict,
+			"DEVICE_NOT_READY",
+			"device is not ready to claim a task",
+			err,
+		)
+	case errors.Is(err, ErrDeviceActiveTask):
+		return newError(
+			ErrorKindConflict,
+			"DEVICE_ACTIVE_TASK",
+			"device already has an active task",
+			err,
+		)
+	case errors.Is(err, ErrClaimInvalid):
+		return newError(
+			ErrorKindForbidden,
+			"TASK_CLAIM_INVALID",
+			"task claim is invalid",
+			err,
+		)
+	case errors.Is(err, ErrClaimExpired):
+		return newError(
+			ErrorKindConflict,
+			"TASK_LEASE_EXPIRED",
+			"task claim lease expired",
+			err,
+		)
+	case errors.Is(err, ErrClaimReplayExpired):
+		return newError(
+			ErrorKindConflict,
+			"CLAIM_REPLAY_EXPIRED",
+			"claim replay is no longer active",
+			err,
+		)
+	case errors.Is(err, ErrTaskVersionConflict):
+		return newError(
+			ErrorKindConflict,
+			"TASK_VERSION_CONFLICT",
+			"task version has changed",
+			err,
+		)
+	case errors.Is(err, ErrExecutionMismatch):
+		return newError(
+			ErrorKindConflict,
+			"TASK_EXECUTION_CONFLICT",
+			"task execution does not match",
+			err,
+		)
+	default:
+		return wrapRepositoryError(err)
+	}
+}