dcpmessage 1.2.2__tar.gz

dcpmessage-1.2.2/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: dcpmessage
+Version: 1.2.2
+Summary: package for retrieving GOES DCS message data from LRGS servers.
+Author: dcpmessage authors
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# Introduction
+
+The `dcpmessage` package is a Python library designed for retrieving GOES DCS message data from LRGS servers. Initially
+developed for deployment as an AWS Lambda function, its primary purpose is to execute periodic data retrieval for
+specified Data Collection Platforms (DCPs). The decoding, processing, or archiving the received DCP messages should
+be handled by other processes as this tool is intended only for retrieving the messages.
+
+## Installation
+
+Download the latest `.tar.gz` from [releases page](https://github.com/dcspy/dcspy/releases) and install it using `pip`
+
+```shell
+pip install dcpmessage-#.#.#.tar.gz 
+```
+
+## Usage
+
+```python
+from dcpmessage import DcpMessage
+
+msg = DcpMessage.get(username="<USERNAME>",
+                     password="<PASSWORD>",
+                     search_criteria="<PATH TO SEARCH CRITERIA>",
+                     host="<HOST>",
+                     )
+print("\n".join(msg))
+```
+
+## Search Criteria
+
+Path to Search Criteria file should be passed when getting dcp messages. Search Criteria file should be `json`. An
+example is provided below.
+
+```json
+{
+  "DRS_SINCE": "now - 1 hour",
+  "DRS_UNTIL": "now",
+  "SOURCE": [
+    "GOES_SELFTIMED",
+    "GOES_RANDOM"
+  ],
+  "DCP_ADDRESS": [
+    "address1",
+    "address2"
+  ]
+}
+```
+
+- NOTE THAT, only following keywords are supported by `dcpmessage` at this point:
+    - `DRS_SINCE`: string
+    - `DRS_UNTIL`: string
+    - `SOURCE` (can be `GOES_SELFTIMED` or `GOES_RANDOM`, or both) : list of strings
+    - `DCP_ADDRESS` (can add multiple dcp addresses): list of strings
+- All other keywords will be ignored.
+- For more information about search criteria, check [opendcs
+  docs](https://opendcs-env.readthedocs.io/en/stable/legacy-lrgs-userguide.html#search-criteria-file-format).
+
+## Contributors
+
+- [Manoj Kotteda](https://github.com/orgs/dcspy/people/manojkotteda)
+- Darshan Baral

dcpmessage-1.2.2/README.md

@@ -0,0 +1,61 @@
+# Introduction
+
+The `dcpmessage` package is a Python library designed for retrieving GOES DCS message data from LRGS servers. Initially
+developed for deployment as an AWS Lambda function, its primary purpose is to execute periodic data retrieval for
+specified Data Collection Platforms (DCPs). The decoding, processing, or archiving the received DCP messages should
+be handled by other processes as this tool is intended only for retrieving the messages.
+
+## Installation
+
+Download the latest `.tar.gz` from [releases page](https://github.com/dcspy/dcspy/releases) and install it using `pip`
+
+```shell
+pip install dcpmessage-#.#.#.tar.gz 
+```
+
+## Usage
+
+```python
+from dcpmessage import DcpMessage
+
+msg = DcpMessage.get(username="<USERNAME>",
+                     password="<PASSWORD>",
+                     search_criteria="<PATH TO SEARCH CRITERIA>",
+                     host="<HOST>",
+                     )
+print("\n".join(msg))
+```
+
+## Search Criteria
+
+Path to Search Criteria file should be passed when getting dcp messages. Search Criteria file should be `json`. An
+example is provided below.
+
+```json
+{
+  "DRS_SINCE": "now - 1 hour",
+  "DRS_UNTIL": "now",
+  "SOURCE": [
+    "GOES_SELFTIMED",
+    "GOES_RANDOM"
+  ],
+  "DCP_ADDRESS": [
+    "address1",
+    "address2"
+  ]
+}
+```
+
+- NOTE THAT, only following keywords are supported by `dcpmessage` at this point:
+    - `DRS_SINCE`: string
+    - `DRS_UNTIL`: string
+    - `SOURCE` (can be `GOES_SELFTIMED` or `GOES_RANDOM`, or both) : list of strings
+    - `DCP_ADDRESS` (can add multiple dcp addresses): list of strings
+- All other keywords will be ignored.
+- For more information about search criteria, check [opendcs
+  docs](https://opendcs-env.readthedocs.io/en/stable/legacy-lrgs-userguide.html#search-criteria-file-format).
+
+## Contributors
+
+- [Manoj Kotteda](https://github.com/orgs/dcspy/people/manojkotteda)
+- Darshan Baral

dcpmessage-1.2.2/dcpmessage/__init__.py

@@ -0,0 +1 @@
+from .dcp_message import DcpMessage

dcpmessage-1.2.2/dcpmessage/credentials.py

@@ -0,0 +1,139 @@
+import hashlib
+from datetime import datetime
+
+from dcpmessage.utils import ByteUtil
+
+
+class HashAlgo:
+    """
+    A class representing a hashing algorithm.
+
+    This class serves as a base class for different hashing algorithms,
+    such as SHA-1 and SHA-256, providing a common interface to initialize
+    and create new hash objects.
+
+    Attributes:
+        algorithm (str): The name of the hashing algorithm.
+    """
+
+    def __init__(self, algorithm):
+        """
+        Initialize the HashAlgo with a specific hashing algorithm.
+
+        :param algorithm: The name of the hashing algorithm (e.g., "sha1", "sha256").
+        """
+        assert algorithm in {"sha1", "sha256"}, (
+            f"{algorithm} is not a supported hash algorithm"
+        )
+        self.algorithm = algorithm
+
+    def new(self):
+        """
+        Create a new hash object using the specified algorithm.
+
+        :return: A new hash object from the hashlib library.
+        """
+        return hashlib.new(self.algorithm)
+
+
+class Sha1(HashAlgo):
+    """
+    A class representing the SHA-1 hashing algorithm.
+
+    Inherits from the HashAlgo class and is pre-configured with the "sha1" algorithm.
+    """
+
+    def __init__(self):
+        """
+        Initialize the Sha1 class with the "sha1" algorithm.
+        """
+        super().__init__("sha1")
+
+
+class Sha256(HashAlgo):
+    """
+    A class representing the SHA-256 hashing algorithm.
+
+    Inherits from the HashAlgo class and is pre-configured with the "sha256" algorithm.
+    """
+
+    def __init__(self):
+        """
+        Initialize the Sha256 class with the "sha256" algorithm.
+        """
+        super().__init__("sha256")
+
+
+class Credentials:
+    def __init__(self, username: str = None, password: str = None):
+        """
+        Initialize the Credentials with a username and password.
+
+        :param username: The username of the user.
+        :param password: The password of the user.
+        """
+        self.username = username
+        self.preliminary_hash = self.get_preliminary_hash(password)
+
+    def get_preliminary_hash(self, password: str) -> bytes:
+        """
+        Generate the preliminary hash for the password.
+
+        This method creates a hash by combining the username and password multiple times.
+
+        :param password: The password to hash.
+        :return: The resulting hash as bytes.
+        """
+        username_b = self.username.encode("utf-8")
+        password_b = password.encode("utf-8")
+        md = Sha1().new()
+        md.update(username_b)
+        md.update(password_b)
+        md.update(username_b)
+        md.update(password_b)
+        return md.digest()
+
+    def get_authenticator_hash(self, time: datetime, hash_algo: HashAlgo) -> str:
+        """
+        Generate an authenticator hash using a specified hash algorithm.
+
+        This hash is used for authenticating the user based on the current time and the user's credentials.
+
+        :param time: The current time as a datetime object.
+        :param hash_algo: The hashing algorithm to use (e.g., Sha1, Sha256).
+        :return: The authenticator hash as a hexadecimal string.
+        """
+        time_t = int(time.timestamp())
+        time_b = time_t.to_bytes(length=4, byteorder="big")
+        username_b = self.username.encode("utf-8")
+
+        """Create an authenticator."""
+        md = hash_algo.new()
+        md.update(username_b)
+        md.update(self.preliminary_hash)
+        md.update(time_b)
+        md.update(username_b)
+        md.update(self.preliminary_hash)
+        md.update(time_b)
+        authenticator_bytes = md.digest()
+        return ByteUtil.to_hex_string(authenticator_bytes)
+
+    def get_authenticated_hello(self, time: datetime, hash_algo: HashAlgo):
+        """
+        Create an authenticated hello message for the user.
+
+        This method combines the username, current time, authenticator hash, and protocol version
+        into a single string used for authentication with the server.
+
+        :param time: The current time as a datetime object.
+        :param hash_algo: The hashing algorithm to use for the authenticator hash (e.g., Sha1, Sha256).
+        :return: The authenticated hello message as a string.
+        """
+        authenticator_hash = self.get_authenticator_hash(time, hash_algo)
+        time_str = time.strftime("%y%j%H%M%S")
+        protocol_version = 14
+
+        authenticated_hello = (
+            f"{self.username} {time_str} {authenticator_hash} {protocol_version}"
+        )
+        return authenticated_hello

dcpmessage-1.2.2/dcpmessage/dcp_message.py

@@ -0,0 +1,118 @@
+from pathlib import Path
+from typing import Union
+
+from .ldds_client import LddsClient
+from .ldds_message import LddsMessage
+from .logs import get_logger
+from .search_criteria import SearchCriteria
+
+logger = get_logger()
+
+
+class DcpMessage:
+    """
+    Class for handling DCP messages, including fetching and processing them
+    from a remote server using the LDDS protocol.
+
+
+    :param DATA_LENGTH: Standard length of the data field in a DCP message.
+    :param: HEADER_LENGTH: Standard length of the header in a DCP message.
+    """
+
+    DATA_LENGTH = 32
+    HEADER_LENGTH = 37
+
+    @staticmethod
+    def get(
+        username: str,
+        password: str,
+        search_criteria: Union[dict, str, Path],
+        host: str,
+        port: int = 16003,
+        timeout: int = 30,
+    ):
+        """
+        Fetches DCP messages from a server based on provided search criteria.
+
+        This method handles the complete process of connecting to the server,
+        authenticating, sending search criteria, retrieving DCP messages, and
+        finally disconnecting.
+
+        :param username: Username for server authentication.
+        :param password: Password for server authentication.
+        :param search_criteria: File path to search criteria or search criteria as a string.
+        :param host: Hostname or IP address of the server.
+        :param port: Port number for server connection (default: 16003).
+        :param timeout: Connection timeout in seconds (default: 30 seconds).
+            Will be passed to `socket.settimeout <https://docs.python.org/3/library/socket.html#socket.socket.settimeout>`_
+        :return: List of DCP messages retrieved from the server.
+        """
+
+        client = LddsClient(host=host, port=port, timeout=timeout)
+
+        try:
+            client.connect()
+        except Exception as e:
+            logger.error("Failed to connect to server.")
+            raise e
+
+        try:
+            client.authenticate_user(username, password)
+        except Exception as e:
+            logger.error("Failed to authenticate user.")
+            client.disconnect()
+            raise e
+
+        match search_criteria:
+            case str() | Path():
+                criteria = SearchCriteria.from_file(search_criteria)
+            case dict():
+                criteria = SearchCriteria.from_dict(search_criteria)
+            case _:
+                raise TypeError("search_criteria must be a filepath or a dict.")
+
+        try:
+            client.send_search_criteria(criteria)
+        except Exception as e:
+            logger.error("Failed to send search criteria.")
+            client.disconnect()
+            raise e
+
+        # Retrieve the DCP block and process it into individual messages
+        dcp_blocks = client.request_dcp_blocks()
+        dcp_messages = DcpMessage.explode(dcp_blocks)
+
+        client.send_goodbye()
+        client.disconnect()
+        return dcp_messages
+
+    @staticmethod
+    def explode(
+        message_blocks: list[LddsMessage],
+    ) -> list[str]:
+        """
+        Splits a message block bytes containing multiple DCP messages into individual messages.
+
+        :param message_blocks: message block (concatenated response from the server).
+        :return: A list of individual DCP messages.
+        """
+
+        data_length = DcpMessage.DATA_LENGTH
+        header_length = DcpMessage.HEADER_LENGTH
+        dcp_messages = []
+
+        for ldds_message in message_blocks:
+            message = ldds_message.message_data.decode()
+            start_index = 0
+            while start_index < ldds_message.message_length:
+                # Extract the length of the current message
+                message_length = int(
+                    message[(start_index + data_length) : (start_index + header_length)]
+                )
+                # Extract the entire message using the determined length
+                end_index = start_index + header_length + message_length
+                dcp_message = message[start_index:end_index]
+                dcp_messages.append(dcp_message)
+                start_index += DcpMessage.HEADER_LENGTH + message_length
+
+        return dcp_messages

dcpmessage-1.2.2/dcpmessage/exceptions.py

@@ -0,0 +1,152 @@
+from enum import UNIQUE, Enum, verify
+
+from .utils import ByteUtil
+
+
+@verify(UNIQUE)
+class ServerErrorCode(Enum):
+    DSUCCESS = 0, "Success."
+    DNOFLAG = 1, "Could not find start of message flag."
+    DDUMMY = 2, "Message found (and loaded) but it's a dummy."
+    DLONGLIST = 3, "Network list was too long to upload."
+    DARCERROR = 4, "Error reading archive file."
+    DNOCONFIG = 5, "Cannot attach to configuration shared memory"
+    DNOSRCHSHM = 6, "Cannot attach to search shared memory"
+    DNODIRLOCK = 7, "Could not get ID of directory lock semaphore"
+    DNODIRFILE = 8, "Could not open message directory file"
+    DNOMSGFILE = 9, "Could not open message storage file"
+    DDIRSEMERR = 10, "Error on directory lock semaphore"
+    DMSGTIMEOUT = 11, "Timeout waiting for new messages"
+    DNONETLIST = 12, "Could not open network list file"
+    DNOSRCHCRIT = 13, "Could not open search criteria file"
+    DBADSINCE = 14, "Bad since time in search criteria file"
+    DBADUNTIL = 15, "Bad until time in search criteria file"
+    DBADNLIST = 16, "Bad network list in search criteria file"
+    DBADADDR = 17, "Bad DCP address in search criteria file"
+    DBADEMAIL = 18, "Bad electronic mail value in search criteria file"
+    DBADRTRAN = 19, "Bad retransmitted value in search criteria file"
+    DNLISTXCD = 20, "Number of network lists exceeded"
+    DADDRXCD = 21, "Number of DCP addresses exceeded"
+    DNOLRGSLAST = 22, "Could not open last read access file"
+    DWRONGMSG = 23, "Message doesn't correspond with directory entry"
+    DNOMOREPROC = 24, "Can't attach: No more processes allowed"
+    DBADDAPSSTAT = 25, "Bad DAPS status specified in search criteria."
+    DBADTIMEOUT = 26, "Bad TIMEOUT value in search crit file."
+    DCANTIOCTL = 27, "Cannot ioctl() the open serial port."
+    DUNTILDRS = 28, "Specified 'until' time reached"
+    DBADCHANNEL = 29, "Bad GOES channel number specified in search crit"
+    DCANTOPENSER = 30, "Can't open specified serial port."
+    DBADDCPNAME = 31, "Unrecognized DCP name in search criteria"
+    DNONAMELIST = 32, "Cannot attach to name list shared memory."
+    DIDXFILEIO = 33, "Index file I/O error"
+    # DNOSRCHSEM = 34, "Bad search-criteria data"
+    DBADSEARCHCRIT = 34, "Bad search-criteria data"
+    DUNTIL = 35, "Specified 'until' time reached"
+    DJAVAIF = 36, "Error in Java - Native Interface"
+    DNOTATTACHED = 37, "Not attached to LRGS native interface"
+    DBADKEYWORD = 38, "Bad keyword"
+    DPARSEERROR = 39, "Error parsing input file"
+    DNONAMELISTSEM = 40, "Cannot attach to name list semaphore."
+    DBADINPUTFILE = 41, "Cannot open or read specified input file"
+    DARCFILEIO = 42, "Archive file I/O error"
+    DNOARCFILE = 43, "Archive file not opened"
+    DICPIOCTL = 44, "Error on ICP188 ioctl call"
+    DICPIOERR = 45, "Error on ICP188 I/O call"
+    DINVALIDUSER = 46, "Invalid DDS User"
+    DDDSAUTHFAILED = 47, "DDS Authentication failed"
+    DDDSINTERNAL = 48, "DDS Internal Error (connection will close)"
+    DDDSFATAL = 49, "DDS Fatal Server Error (retry later)"
+    DNOSUCHSOURCE = 50, "No such data source"
+    DALREADYATTACHED = 51, "User already attached (mult disallowed)"
+    DNOSUCHFILE = 52, "No such file"
+    DTOOMANYDCPS = 53, "Too many DCPs for real-time stream"
+    DBADPASSWORD = 54, "Password does not meet local requirements."
+    DSTRONGREQUIRED = 55, "Server requires strong encryption algorithm"
+
+    def __new__(cls, *args, **kwargs):
+        obj = object.__new__(cls)
+        obj._value_ = args[0]
+        return obj
+
+    # ignore the first param since it's already set by __new__
+    def __init__(self, _: str, description: str = None):
+        self.__description = description
+
+    def __str__(self):
+        return self.value
+
+    @property
+    def description(self):
+        return self.__description
+
+
+class ServerError:
+    def __init__(self, message: str, server_code_no: int = 0, system_code_no: int = 0):
+        """
+
+        :param message:
+        :param server_code_no:
+        :param system_code_no:
+        """
+
+        self.message = message
+        self.server_code_no = server_code_no
+        self.system_code_no = system_code_no
+        self.is_end_of_message = self.is_end_of_message()
+
+    def is_end_of_message(self):
+        if self.server_code_no in (
+            ServerErrorCode.DUNTIL.value,
+            ServerErrorCode.DUNTILDRS.value,
+        ):
+            return True
+        return False
+
+    @property
+    def description(self):
+        return ServerErrorCode(self.server_code_no).description
+
+    @staticmethod
+    def parse(message: bytes):
+        """
+        Parse ServerError from error_string
+
+        :param message: bytes response returned from server
+        :return: object of ServerError class
+        """
+        if not message.startswith(b"?"):
+            # Not a server error
+            return ServerError("")
+        error_string = ByteUtil.extract_string(message)
+        split_error_string = error_string[1:].split(",", maxsplit=2)
+        sever_code_no, system_code_no, error_string = [
+            x.strip() for x in split_error_string
+        ]
+        return ServerError(error_string, int(sever_code_no), int(system_code_no))
+
+    def raise_exception(self):
+        raise ProtocolError(self.__str__())
+
+    def __str__(self):
+        if self.system_code_no == 0 and self.server_code_no == 0:
+            return "No Server Error"
+
+        server_error_code = ServerErrorCode(self.server_code_no)
+        r = f"System Code #{self.system_code_no}; "
+        r += f"Server Code #{server_error_code.value} - {self.message} ({server_error_code.description})"
+        return r
+
+    def __eq__(self, other):
+        return (
+            self.server_code_no == other.server_code_no
+            and self.system_code_no == other.system_code_no
+            and self.message == other.message
+        )
+
+
+class ProtocolError(Exception):
+    pass
+
+
+class LddsMessageError(Exception):
+    pass