feat: add bulletin_rest_client module to manage global Splunk messages

docs/bulletin_rest_client.md

@@ -0,0 +1 @@
+::: solnlib.bulletin_rest_client

mkdocs.yml

@@ -41,6 +41,7 @@ nav:
       - "pattern.py": pattern.md
       - "server_info.py": server_info.md
       - "splunk_rest_client.py": splunk_rest_client.md
+      - "bulletin_rest_client.py": bulletin_rest_client.md
       - "splunkenv.py": splunkenv.md
       - "time_parser.py": time_parser.md
       - "timer_queue.py": timer_queue.md

solnlib/__init__.py

@@ -18,6 +18,7 @@
 
 from . import (
     acl,
+    bulletin_rest_client,
     conf_manager,
     credentials,
     file_monitor,
@@ -37,6 +38,7 @@
 
 __all__ = [
     "acl",
+    "bulletin_rest_client",
     "conf_manager",
     "credentials",
     "file_monitor",

solnlib/bulletin_rest_client.py

@@ -0,0 +1,140 @@
+#
+# Copyright 2024 Splunk Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+from solnlib import splunk_rest_client as rest_client
+from splunklib import binding
+from typing import Optional, List
+import json
+
+__all__ = ["BulletinRestClient"]
+
+
+class BulletinRestClient:
+    """REST client for handling Bulletin messages."""
+
+    MESSAGES_ENDPOINT = "/services/messages"
+
+    headers = [("Content-Type", "application/json")]
+
+    class Severity:
+        INFO = "info"
+        WARNING = "warn"
+        ERROR = "error"
+
+    def __init__(
+        self,
+        message_name: str,
+        session_key: str,
+        **context: dict,
+    ):
+        """Initializes BulletinRestClient.
+
+            One instance is responsible for handling one, particular message.
+            If you need to add another message to bulletin create another instance
+            with a different 'message_name'
+            e.g.
+            msg_1 = BulletinRestClient("message_1", "<some session key>")
+            msg_2 = BulletinRestClient("message_2", "<some session key>")
+
+        Arguments:
+            message_name: Name of the message in the splunk's bulletin.
+            session_key: Splunk access token.
+            context: Other configurations for Splunk rest client.
+        """
+
+        self.message_name = message_name
+        self.session_key = session_key
+
+        self._rest_client = rest_client.SplunkRestClient(
+            self.session_key, app="-", **context
+        )
+
+    def create_message(
+        self,
+        msg: str,
+        severity: Severity = Severity.WARNING,
+        capabilities: Optional[List[str]] = None,
+        roles: Optional[List] = None,
+    ):
+        """Creates a message in the splunk's bulletin.' Calling this method
+        multiple times for the same instance will overwrite existing message.
+
+        Arguments:
+            msg: The message which will be displayed in the splunk's bulletin'
+            severity: Severity level of the message. It has to be one of: 'info', 'warn', 'error'.
+            If wrong severity is given, ValueError will be raised.
+            capabilities: One or more capabilities that users must have to view the message.
+                Capability names are validated.
+                This argument should be provided as a list of string/s e.g. capabilities=['one', 'two'].
+                If a non-existent capability is used, HTTP 400 BAD REQUEST exception will be raised.
+                If argument is not a List[str] ValueError will be raised.
+            roles: One or more roles that users must have to view the message. Role names are validated.
+                This argument should be provided as a list of string/s e.g. roles=['user', 'admin'].
+                If a non-existent role is used, HTTP 400 BAD REQUEST exception will be raised.
+                If argument is not a List[str] ValueError will be raised.
+        """
+        body = {
+            "name": self.message_name,
+            "value": msg,
+            "severity": severity,
+            "capability": [],
+            "role": [],
+        }
+
+        if severity not in ("info", "warn", "error"):
+            raise ValueError("Severity must be one of ('info', 'warn', 'error').")
+
+        if capabilities:
+            body["capability"] = self._validate_and_get_body_value(
+                capabilities, "Capabilities must be a list of strings."
+            )
+
+        if roles:
+            body["role"] = self._validate_and_get_body_value(
+                roles, "Roles must be a list of strings."
+            )
+
+        try:
+            self._rest_client.post(
+                self.MESSAGES_ENDPOINT, body=body, headers=self.headers
+            )
+        except binding.HTTPError:
+            raise
+
+    def get_message(self):
+        """Get specific message created by this instance."""
+        endpoint = f"{self.MESSAGES_ENDPOINT}/{self.message_name}"
+        response = self._rest_client.get(endpoint, output_mode="json").body.read()
+        return json.loads(response)
+
+    def get_all_messages(self):
+        """Get all messages in the bulletin."""
+        response = self._rest_client.get(
+            self.MESSAGES_ENDPOINT, output_mode="json"
+        ).body.read()
+        return json.loads(response)
+
+    def delete_message(self):
+        """Delete specific message created by this instance."""
+        endpoint = f"{self.MESSAGES_ENDPOINT}/{self.message_name}"
+        self._rest_client.delete(endpoint)
+
+    @staticmethod
+    def _validate_and_get_body_value(arg, error_msg) -> List:
+        if type(arg) is list and (all(isinstance(el, str) for el in arg)):
+            return [el for el in arg]
+        else:
+            raise ValueError(error_msg)

tests/integration/test_bulletin_rest_client.py

@@ -0,0 +1,107 @@
+#
+# Copyright 2024 Splunk Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+import context
+from splunklib import binding
+import pytest
+from solnlib import bulletin_rest_client as brc
+
+
+def _build_bulletin_manager(msg_name, session_key: str) -> brc.BulletinRestClient:
+    return brc.BulletinRestClient(
+        msg_name,
+        session_key,
+        owner=context.owner,
+        scheme=context.scheme,
+        host=context.host,
+        port=context.port,
+    )
+
+
+def test_create_message():
+    session_key = context.get_session_key()
+    bulletin_client = _build_bulletin_manager("msg_name", session_key)
+
+    with pytest.raises(binding.HTTPError) as e:
+        bulletin_client.create_message(
+            "new message to bulletin",
+            capabilities=["apps_restore", "unknown_cap"],
+            roles=["admin"],
+        )
+    assert str(e.value.status) == "400"
+
+    with pytest.raises(binding.HTTPError) as e:
+        bulletin_client.create_message(
+            "new message to bulletin", roles=["unknown_role"]
+        )
+    assert str(e.value.status) == "400"
+
+
+def test_bulletin_rest_api():
+    session_key = context.get_session_key()
+    bulletin_client_1 = _build_bulletin_manager("msg_name_1", session_key)
+    bulletin_client_2 = _build_bulletin_manager("msg_name_2", session_key)
+
+    bulletin_client_1.create_message(
+        "new message to bulletin",
+        capabilities=["apps_restore", "delete_messages"],
+        roles=["admin"],
+    )
+
+    get_msg_1 = bulletin_client_1.get_message()
+    assert get_msg_1["entry"][0]["content"]["message"] == "new message to bulletin"
+    assert get_msg_1["entry"][0]["content"]["severity"] == "warn"
+
+    bulletin_client_1.create_message(
+        "new message to bulletin", bulletin_client_1.Severity.INFO
+    )
+    get_msg_1 = bulletin_client_1.get_message()
+    assert get_msg_1["entry"][0]["content"]["severity"] == "info"
+
+    bulletin_client_1.create_message(
+        "new message to bulletin", bulletin_client_1.Severity.ERROR
+    )
+    get_msg_1 = bulletin_client_1.get_message()
+    assert get_msg_1["entry"][0]["content"]["severity"] == "error"
+
+    get_all_msg = bulletin_client_1.get_all_messages()
+    assert len(get_all_msg["entry"]) == 1
+
+    bulletin_client_2.create_message("new message to bulletin 2")
+
+    get_msg_2 = bulletin_client_2.get_message()
+    assert get_msg_2["entry"][0]["content"]["message"] == "new message to bulletin 2"
+
+    get_all_msg = bulletin_client_1.get_all_messages()
+    assert len(get_all_msg["entry"]) == 2
+
+    bulletin_client_1.delete_message()
+
+    with pytest.raises(binding.HTTPError) as e:
+        bulletin_client_1.get_message()
+    assert str(e.value.status) == "404"
+
+    with pytest.raises(binding.HTTPError) as e:
+        bulletin_client_1.delete_message()
+    assert str(e.value.status) == "404"
+
+    get_all_msg = bulletin_client_1.get_all_messages()
+    assert len(get_all_msg["entry"]) == 1
+
+    bulletin_client_2.delete_message()
+
+    get_all_msg = bulletin_client_1.get_all_messages()
+    assert len(get_all_msg["entry"]) == 0

tests/unit/test_bulletin_rest_client.py

@@ -0,0 +1,63 @@
+#
+# Copyright 2024 Splunk Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+import pytest
+from solnlib.bulletin_rest_client import BulletinRestClient
+
+
+context = {"owner": "nobody", "scheme": "https", "host": "localhost", "port": 8089}
+
+
+def test_create_message(monkeypatch):
+    session_key = "123"
+    bulletin_client = BulletinRestClient(
+        "msg_name_1",
+        session_key,
+        **context,
+    )
+
+    def new_post(*args, **kwargs) -> str:
+        return "ok"
+
+    monkeypatch.setattr(bulletin_client._rest_client, "post", new_post)
+
+    bulletin_client.create_message(
+        "new message to bulletin",
+        capabilities=["apps_restore", "delete_messages"],
+        roles=["admin"],
+    )
+
+    with pytest.raises(ValueError, match="Severity must be one of"):
+        bulletin_client.create_message(
+            "new message to bulletin",
+            severity="debug",
+            capabilities=["apps_restore", "delete_messages", 1],
+            roles=["admin"],
+        )
+
+    with pytest.raises(ValueError, match="Capabilities must be a list of strings."):
+        bulletin_client.create_message(
+            "new message to bulletin",
+            capabilities=["apps_restore", "delete_messages", 1],
+            roles=["admin"],
+        )
+
+    with pytest.raises(ValueError, match="Roles must be a list of strings."):
+        bulletin_client.create_message(
+            "new message to bulletin",
+            capabilities=["apps_restore", "delete_messages"],
+            roles=["admin", 1],
+        )