feat: add bulletin_rest_client module to manage global Splunk messages (

#369)

**Issue
number:[ADDON-70528](https://splunk.atlassian.net/browse/ADDON-70528)**

## Summary

Create REST client to manage bulletin messages in splunk.

### Changes

* add bulletin_rest_client module with basic methods: CREATE, GET, GET
ALL, DELETE

### User experience

The user can better manage events in add-on by creating specific
messages in the Splunk bulletin. Every message has 3 severity levels:
info, warn, error. The user can also delete or read those messages at
code lvl with the use of REST client.

## Checklist

If your change doesn't seem to apply, please leave them unchecked.

* [x] I have performed a self-review of this change
* [x] Changes have been tested
* [x] Changes are documented
* [x] PR title follows [conventional commit
semantics](https://www.conventionalcommits.org/en/v1.0.0/)

---------

Co-authored-by: Artem Rys <rysartem@gmail.com>

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,151 @@
+#
+# 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 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,
+        app: str,
+        **context: dict,
+    ):
+        """Initializes BulletinRestClient.
+            When creating a new bulletin message, you must provide a name, which is a kind of ID.
+            If you try to create another message with the same name (ID), the API will not add another message
+            to the bulletin, but it will overwrite the existing one. Similar behaviour applies to deletion.
+            To delete a message, you must indicate the name (ID) of the message.
+            To provide better and easier control over bulletin messages, this client works in such a way
+            that there is one instance responsible for handling one specific 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.
+            app: App name of namespace.
+            context: Other configurations for Splunk rest client.
+        """
+
+        self.message_name = message_name
+        self.session_key = session_key
+        self.app = app
+
+        self._rest_client = rest_client.SplunkRestClient(
+            self.session_key, app=self.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 (
+            self.Severity.INFO,
+            self.Severity.WARNING,
+            self.Severity.ERROR,
+        ):
+            raise ValueError(
+                "Severity must be one of ("
+                "'BulletinRestClient.Severity.INFO', "
+                "'BulletinRestClient.Severity.WARNING', "
+                "'BulletinRestClient.Severity.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."
+            )
+
+        self._rest_client.post(self.MESSAGES_ENDPOINT, body=body, headers=self.headers)
+
+    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,108 @@
+#
+# 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,64 @@
+#
+# 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],
+        )