jenkins_node: Add set offline message (#9084)

* jenkins_node: Add set offline message

* Implement offline_message parameter for updating a Jenkins node
  offline cause reason when the state is "disabled" (offline).

* Fix enabled, disable and absent node state redirect authorization
  issues, same as was present for present.

* Add unit tests for redirect authorization workarounds.

* * Make docs clearer re: offline_message behaviour

* Exit with fail_json() instead of raising when
  create/delete/enable/disable node fail.

* * Add changelog fragment

* Update changelog fragments.

---------

Co-authored-by: Felix Fontein <felix@fontein.de>

tests/unit/plugins/modules/test_jenkins_node.py

@@ -207,6 +207,47 @@ def test_state_present_when_absent_check_mode(get_instance, instance, state):
     assert result.value["changed"] is True
 
 
+@mark.parametrize(["state"], [param(state) for state in PRESENT_STATES])
+def test_state_present_when_absent_redirect_auth_error_handled(
+    get_instance, instance, state
+):
+    instance.node_exists.side_effect = [False, True]
+    instance.get_node_config.return_value = "<slave />"
+    instance.create_node.side_effect = jenkins.JenkinsException
+
+    set_module_args({
+        "name": "my-node",
+        "state": state,
+    })
+
+    with raises(AnsibleExitJson) as result:
+        jenkins_node.main()
+
+    assert instance.create_node.call_args == call("my-node", launcher=jenkins.LAUNCHER_SSH)
+
+    assert result.value["created"] is True
+    assert result.value["changed"] is True
+
+
+@mark.parametrize(["state"], [param(state) for state in PRESENT_STATES])
+def test_state_present_when_absent_other_error_raised(get_instance, instance, state):
+    instance.node_exists.side_effect = [False, False]
+    instance.get_node_config.return_value = "<slave />"
+    instance.create_node.side_effect = jenkins.JenkinsException
+
+    set_module_args({
+        "name": "my-node",
+        "state": state,
+    })
+
+    with raises(AnsibleFailJson) as result:
+        jenkins_node.main()
+
+    assert instance.create_node.call_args == call("my-node", launcher=jenkins.LAUNCHER_SSH)
+
+    assert "Create node failed" in str(result.value)
+
+
 def test_state_present_when_present(get_instance, instance):
     instance.node_exists.return_value = True
     instance.get_node_config.return_value = "<slave />"
@@ -262,6 +303,43 @@ def test_state_absent_when_present_check_mode(get_instance, instance):
     assert result.value["changed"] is True
 
 
+def test_state_absent_when_present_redirect_auth_error_handled(get_instance, instance):
+    instance.node_exists.side_effect = [True, False]
+    instance.get_node_config.return_value = "<slave />"
+    instance.delete_node.side_effect = jenkins.JenkinsException
+
+    set_module_args({
+        "name": "my-node",
+        "state": "absent",
+    })
+
+    with raises(AnsibleExitJson) as result:
+        jenkins_node.main()
+
+    assert instance.delete_node.call_args == call("my-node")
+
+    assert result.value["deleted"] is True
+    assert result.value["changed"] is True
+
+
+def test_state_absent_when_present_other_error_raised(get_instance, instance):
+    instance.node_exists.side_effect = [True, True]
+    instance.get_node_config.return_value = "<slave />"
+    instance.delete_node.side_effect = jenkins.JenkinsException
+
+    set_module_args({
+        "name": "my-node",
+        "state": "absent",
+    })
+
+    with raises(AnsibleFailJson) as result:
+        jenkins_node.main()
+
+    assert instance.delete_node.call_args == call("my-node")
+
+    assert "Delete node failed" in str(result.value)
+
+
 def test_state_absent_when_absent(get_instance, instance):
     instance.node_exists.return_value = False
     instance.get_node_config.return_value = "<slave />"
@@ -319,6 +397,45 @@ def test_state_enabled_when_offline_check_mode(get_instance, instance):
     assert result.value["changed"] is True
 
 
+def test_state_enabled_when_offline_redirect_auth_error_handled(get_instance, instance):
+    instance.node_exists.return_value = True
+    instance.get_node_config.return_value = "<slave />"
+    instance.get_node_info.side_effect = [{"offline": True}, {"offline": False}]
+    instance.enable_node.side_effect = jenkins.JenkinsException
+
+    set_module_args({
+        "name": "my-node",
+        "state": "enabled",
+    })
+
+    with raises(AnsibleExitJson) as result:
+        jenkins_node.main()
+
+    assert instance.enable_node.call_args == call("my-node")
+
+    assert result.value["enabled"] is True
+    assert result.value["changed"] is True
+
+
+def test_state_enabled_when_offline_other_error_raised(get_instance, instance):
+    instance.node_exists.return_value = True
+    instance.get_node_config.return_value = "<slave />"
+    instance.get_node_info.side_effect = [{"offline": True}, {"offline": True}]
+    instance.enable_node.side_effect = jenkins.JenkinsException
+
+    set_module_args({
+        "name": "my-node",
+        "state": "enabled",
+    })
+
+    with raises(AnsibleFailJson) as result:
+        jenkins_node.main()
+
+    assert instance.enable_node.call_args == call("my-node")
+
+    assert "Enable node failed" in str(result.value)
+
+
 def test_state_enabled_when_not_offline(get_instance, instance):
     instance.node_exists.return_value = True
     instance.get_node_config.return_value = "<slave />"
@@ -341,7 +458,10 @@ def test_state_enabled_when_not_offline(get_instance, instance):
 def test_state_disabled_when_not_offline(get_instance, instance):
     instance.node_exists.return_value = True
     instance.get_node_config.return_value = "<slave />"
-    instance.get_node_info.return_value = {"offline": False}
+    instance.get_node_info.return_value = {
+        "offline": False,
+        "offlineCauseReason": "",
+    }
 
     set_module_args({
         "name": "my-node",
@@ -351,16 +471,78 @@ def test_state_disabled_when_not_offline(get_instance, instance):
     with raises(AnsibleExitJson) as result:
         jenkins_node.main()
 
-    assert instance.disable_node.call_args == call("my-node")
+    assert instance.disable_node.call_args == call("my-node", "")
 
     assert result.value["disabled"] is True
     assert result.value["changed"] is True
 
 
+def test_state_disabled_when_not_offline_redirect_auth_error_handled(
+    get_instance, instance
+):
+    instance.node_exists.return_value = True
+    instance.get_node_config.return_value = "<slave />"
+    instance.get_node_info.side_effect = [
+        {
+            "offline": False,
+            "offlineCauseReason": "",
+        },
+        {
+            "offline": True,
+            "offlineCauseReason": "",
+        },
+    ]
+    instance.disable_node.side_effect = jenkins.JenkinsException
+
+    set_module_args({
+        "name": "my-node",
+        "state": "disabled",
+    })
+
+    with raises(AnsibleExitJson) as result:
+        jenkins_node.main()
+
+    assert instance.disable_node.call_args == call("my-node", "")
+
+    assert result.value["disabled"] is True
+    assert result.value["changed"] is True
+
+
+def test_state_disabled_when_not_offline_other_error_raised(get_instance, instance):
+    instance.node_exists.return_value = True
+    instance.get_node_config.return_value = "<slave />"
+    instance.get_node_info.side_effect = [
+        {
+            "offline": False,
+            "offlineCauseReason": "",
+        },
+        {
+            "offline": False,
+            "offlineCauseReason": "",
+        },
+    ]
+    instance.disable_node.side_effect = jenkins.JenkinsException
+
+    set_module_args({
+        "name": "my-node",
+        "state": "disabled",
+    })
+
+    with raises(AnsibleFailJson) as result:
+        jenkins_node.main()
+
+    assert instance.disable_node.call_args == call("my-node", "")
+
+    assert "Disable node failed" in str(result.value)
+
+
 def test_state_disabled_when_not_offline_check_mode(get_instance, instance):
     instance.node_exists.return_value = True
     instance.get_node_config.return_value = "<slave />"
-    instance.get_node_info.return_value = {"offline": False}
+    instance.get_node_info.return_value = {
+        "offline": False,
+        "offlineCauseReason": "",
+    }
 
     set_module_args({
         "name": "my-node",
@@ -380,7 +562,10 @@ def test_state_disabled_when_not_offline_check_mode(get_instance, instance):
 def test_state_disabled_when_offline(get_instance, instance):
     instance.node_exists.return_value = True
     instance.get_node_config.return_value = "<slave />"
-    instance.get_node_info.return_value = {"offline": True}
+    instance.get_node_info.return_value = {
+        "offline": True,
+        "offlineCauseReason": "",
+    }
 
     set_module_args({
         "name": "my-node",
@@ -573,3 +758,86 @@ def test_configure_labels_fail_when_contains_space(get_instance, instance):
         jenkins_node.main()
 
     assert not instance.reconfig_node.called
+
+
+@mark.parametrize(["state"], [param(state) for state in ["enabled", "present", "absent"]])
+def test_raises_error_if_offline_message_when_state_not_disabled(get_instance, instance, state):
+    set_module_args({
+        "name": "my-node",
+        "state": state,
+        "offline_message": "This is a message...",
+    })
+
+    with raises(AnsibleFailJson):
+        jenkins_node.main()
+
+    assert not instance.disable_node.called
+
+
+def test_set_offline_message_when_equal(get_instance, instance):
+    instance.node_exists.return_value = True
+    instance.get_node_config.return_value = "<slave />"
+    instance.get_node_info.return_value = {
+        "offline": True,
+        "offlineCauseReason": "This is an old message...",
+    }
+
+    set_module_args({
+        "name": "my-node",
+        "state": "disabled",
+        "offline_message": "This is an old message...",
+    })
+
+    with raises(AnsibleExitJson) as result:
+        jenkins_node.main()
+
+    assert not instance.disable_node.called
+
+    assert result.value["changed"] is False
+
+
+def test_set_offline_message_when_not_equal_not_offline(get_instance, instance):
+    instance.node_exists.return_value = True
+    instance.get_node_config.return_value = "<slave />"
+    instance.get_node_info.return_value = {
+        "offline": False,
+        "offlineCauseReason": "This is an old message...",
+    }
+
+    set_module_args({
+        "name": "my-node",
+        "state": "disabled",
+        "offline_message": "This is a new message...",
+    })
+
+    with raises(AnsibleExitJson) as result:
+        jenkins_node.main()
+
+    assert instance.disable_node.call_args == call("my-node", "This is a new message...")
+
+    assert result.value["changed"] is True
+
+
+# Not calling disable_node when already offline seems like a sensible thing to do.
+# However, we need to call disable_node to set the offline message, so check that
+# we do even when already offline.
+def test_set_offline_message_when_not_equal_offline(get_instance, instance):
+    instance.node_exists.return_value = True
+    instance.get_node_config.return_value = "<slave />"
+    instance.get_node_info.return_value = {
+        "offline": True,
+        "offlineCauseReason": "This is an old message...",
+    }
+
+    set_module_args({
+        "name": "my-node",
+        "state": "disabled",
+        "offline_message": "This is a new message...",
+    })
+
+    with raises(AnsibleExitJson) as result:
+        jenkins_node.main()
+
+    assert not instance.disable_node.called
+
+    assert result.value["changed"] is False