dcpmessage 1.2.2__py3-none-any.whl

dcpmessage/__init__.py

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

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/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/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

dcpmessage/ldds_client.py

@@ -0,0 +1,240 @@
+import socket
+from datetime import datetime, timezone
+from typing import Union
+
+from .credentials import Credentials, Sha1, Sha256
+from .ldds_message import LddsMessage, LddsMessageConstants, LddsMessageIds
+from .logs import get_logger
+from .search_criteria import SearchCriteria
+
+logger = get_logger()
+
+
+class BasicClient:
+    """
+    A class for managing basic socket connections to a remote server.
+
+    :param host: The hostname or IP address of the remote server.
+    :param port: The port number to connect to on the remote server.
+    :param timeout: The timeout duration for the socket connection in seconds.
+    """
+
+    def __init__(self, host: str, port: int, timeout: Union[float, int]):
+        """
+        Initialize the BasicClient with the provided host, port, and timeout.
+
+        :param host: The hostname or IP address of the remote server.
+        :param port: The port number to connect to on the remote server.
+        :param timeout: The timeout duration for the socket connection in seconds.
+        """
+        self.host = host
+        self.port = port
+        self.timeout = timeout
+        self.socket = None
+
+    def connect(self):
+        """
+        Establish a socket connection to the server using the provided host and port.
+        Sets the socket to blocking mode and applies the specified timeout.
+
+        :raises IOError: If the connection attempt times out or fails for any reason.
+        :return: None
+        """
+        try:
+            logger.info(f"Connecting to {self.host}:{self.port}")
+            self.socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+            self.socket.settimeout(self.timeout)
+            self.socket.connect((self.host, self.port))
+            logger.info(f"Successfully connected to {self.host}:{self.port}")
+        except socket.timeout as ex:
+            raise IOError(f"Connection to {self.host}:{self.port} timed out") from ex
+        except socket.error as ex:
+            raise IOError(f"Cannot connect to {self.host}:{self.port}") from ex
+
+    def disconnect(self):
+        """
+        Close the established socket connection.
+
+        :return: None
+        """
+        try:
+            if self.socket:
+                self.socket.close()
+                logger.debug("Closed socket")
+        except IOError as ex:
+            logger.debug(f"Error during disconnect: {ex}")
+        finally:
+            self.socket = None
+
+    def send_data(
+        self,
+        data: bytes,
+    ):
+        """
+        Send data over the established socket connection.
+
+        :param data: The byte data to send over the socket.
+        :raises IOError: If the socket is not connected.
+        :return: None
+        """
+        if self.socket is None:
+            raise IOError("BasicClient socket closed.")
+        self.socket.sendall(data)
+
+
+class LddsClient(BasicClient):
+    """
+    A client for communicating with an LDDS (Low Data Rate Demodulation System) server.
+    Inherits from BasicClient and adds LDDS-specific functionality.
+    """
+
+    def __init__(self, host: str, port: int, timeout: Union[float, int]):
+        """
+        Initialize the LddsClient with the provided host, port, and timeout.
+
+        :param host: The hostname or IP address of the LDDS server.
+        :param port: The port number to connect to on the LDDS server.
+        :param timeout: The timeout duration for the socket connection in seconds.
+        """
+        super().__init__(host=host, port=port, timeout=timeout)
+
+    def receive_data(
+        self,
+        buffer_size: int = 1024,
+    ) -> bytes:
+        """
+        Receive data from the socket.
+
+        :param buffer_size: The size of the buffer to use when receiving data.
+        :return: The received byte data.
+        :raises IOError: If the socket is not connected.
+        """
+        if self.socket is None:
+            raise IOError("BasicClient socket closed.")
+
+        data = self.socket.recv(buffer_size)
+        if len(data) == 0:
+            raise IOError("BasicClient socket closed.")
+
+        ldds_message_length = LddsMessage.get_total_length(data)
+        while len(data) < ldds_message_length:
+            data += self.socket.recv(buffer_size)
+
+        return data
+
+    def authenticate_user(
+        self,
+        user_name: str = "user",
+        password: str = "pass",
+    ):
+        """
+        Authenticate a user with the LDDS server using the provided username and password.
+
+        :param user_name: The username to authenticate with.
+        :param password: The password to authenticate with.
+        :raises Exception: If authentication fails.
+        :return: None
+        """
+        msg_id = LddsMessageIds.auth_hello
+        credentials = Credentials(username=user_name, password=password)
+
+        is_authenticated = False
+        for hash_algo in [Sha1, Sha256]:
+            auth_str = credentials.get_authenticated_hello(
+                datetime.now(timezone.utc), hash_algo()
+            )
+            logger.debug(auth_str)
+            ldds_message = self.request_dcp_message(msg_id, auth_str)
+            server_error = ldds_message.server_error
+            if server_error is not None:
+                logger.debug(str(server_error))
+            else:
+                is_authenticated = True
+
+        if is_authenticated:
+            logger.info("Successfully authenticated user")
+        else:
+            raise Exception(
+                f"Could not authenticate for user:{user_name}\n{server_error}"
+            )
+
+    def request_dcp_message(
+        self,
+        message_id,
+        message_data: Union[str, bytes, bytearray] = "",
+    ) -> LddsMessage:
+        """
+        Request a DCP (Data Collection Platform) message from the LDDS server.
+
+        :param message_id: The ID of the message to request.
+        :param message_data: The data to include in the message request.
+        :return: The response from the server as bytes.
+        """
+        if isinstance(message_data, str):
+            message_data = message_data.encode()
+        message = LddsMessage.create(message_id=message_id, message_data=message_data)
+        message_bytes = message.to_bytes()
+        self.send_data(message_bytes)
+        server_response = self.receive_data()
+        return LddsMessage.parse(server_response)
+
+    def send_search_criteria(
+        self,
+        search_criteria: SearchCriteria,
+    ):
+        """
+        Send search criteria to the LDDS server.
+
+        :param search_criteria: The search criteria to send.
+        :return: None
+        """
+        data_to_send = bytearray(50) + bytes(search_criteria)
+        logger.debug(f"Sending criteria message (filesize = {len(data_to_send)} bytes)")
+        ldds_message = self.request_dcp_message(
+            LddsMessageIds.search_criteria, data_to_send
+        )
+
+        server_error = ldds_message.server_error
+        if server_error is not None:
+            server_error.raise_exception()
+        else:
+            logger.info("Search criteria sent successfully.")
+
+    def request_dcp_blocks(
+        self,
+    ) -> list[LddsMessage]:
+        """
+        Request a block of DCP messages from the LDDS server.
+
+        :return: The received DCP block as bytearray.
+        """
+        msg_id = LddsMessageIds.dcp_block
+        max_data_length = LddsMessageConstants.MAX_DATA_LENGTH
+        dcp_messages = []
+        try:
+            while True:
+                response = self.request_dcp_message(msg_id)
+                server_error = response.server_error
+                if server_error is not None:
+                    if server_error.is_end_of_message:
+                        logger.info(server_error.description)
+                        break
+                    else:
+                        server_error.raise_exception()
+                dcp_messages.append(response)
+
+            return dcp_messages
+        except Exception as err:
+            logger.debug(f"Error receiving data: {err}")
+            raise err
+
+    def send_goodbye(self):
+        """
+        Send a goodbye message to the LDDS server to terminate the session.
+
+        :return: None
+        """
+        message_id = LddsMessageIds.goodbye
+        ldds_message = self.request_dcp_message(message_id, "")
+        server_error = ldds_message.server_error
+        logger.debug(ldds_message.to_bytes())

dcpmessage/ldds_message.py

@@ -0,0 +1,232 @@
+from dataclasses import dataclass
+
+from .exceptions import LddsMessageError, ProtocolError, ServerError, ServerErrorCode
+
+
+@dataclass
+class LddsMessageConstants:
+    """Constants related to LDDS messages."""
+
+    VALID_HEADER_LENGTH: int = 10
+    SYNC_LENGTH: int = 4
+    VALID_SYNC_CODE: bytes = b"FAF0"
+    MAX_DATA_LENGTH: int = 99000
+    VALID_IDS: frozenset[str] = frozenset(
+        (
+            "a",
+            "b",
+            "c",
+            "d",
+            "e",
+            "f",
+            "g",
+            "h",
+            "i",
+            "j",
+            "k",
+            "l",
+            "m",
+            "n",
+            "o",
+            "p",
+            "q",
+            "r",
+            "s",
+            "t",
+            "u",
+        )
+    )
+
+
+@dataclass
+class LddsMessageIds:
+    """
+    Ids associated with LDDS messages.
+    """
+
+    hello: str = "a"
+    goodbye: str = "b"
+    status: str = "c"
+    start: str = "d"
+    stop: str = "e"
+    dcp: str = "f"
+    search_criteria: str = "g"
+    get_outages: str = "h"
+    idle: str = "i"
+    put_netlist: str = "j"
+    get_netlist: str = "k"
+    assert_outages: str = "l"
+    auth_hello: str = "m"
+    dcp_block: str = "n"
+    events: str = "o"
+    ret_config: str = "p"
+    inst_config: str = "q"
+    dcp_block_ext: str = "r"
+    unused_6: str = "s"
+    unused_7: str = "t"
+    user: str = "u"
+
+
+class LddsMessage:
+    def __init__(
+        self,
+        message_id: str = None,
+        message_length: int = None,
+        message_data: bytes = None,
+        header: bytes = None,
+    ):
+        """
+        Initialize a LddsMessage instance.
+
+        :param message_id: The ID of the message.
+        :param message_length: The length of the message data.
+        :param message_data: The message data in bytes.
+        :param header: The header of the message in bytes.
+        """
+        self.message_id = message_id
+        self.message_length = message_length
+        self.message_data = message_data
+        self.header = header
+        self.server_error: ServerError = None
+        self.error: LddsMessageError = None
+
+    def check_server_errors(self):
+        if self.message_data.startswith(b"?"):
+            self.server_error = ServerError.parse(self.message_data)
+
+    def check_other_errors(self):
+        if self.message_length != len(self.message_data):
+            self.error = LddsMessageError("Inconsistent LDDS message length")
+        # TODO: add other errors
+
+    @staticmethod
+    def parse(
+        message: bytes,
+    ):
+        """
+        Parse bytes into an LddsMessage instance.
+
+        :param message: The message in bytes to parse.
+        :return: A tuple containing an LddsMessage instance and a ServerError if any.
+        :raises ProtocolError: If there is an issue with the message header.
+        """
+        header_length = LddsMessageConstants.VALID_HEADER_LENGTH
+        assert len(message) >= header_length, (
+            f"Invalid LDDS message - length={len(message)}"
+        )
+        header = message[:header_length]
+
+        sync_length = LddsMessageConstants.SYNC_LENGTH
+        sync = header[:sync_length]
+        assert sync == LddsMessageConstants.VALID_SYNC_CODE, (
+            f"Invalid LDDS message header - bad sync '{sync}'"
+        )
+
+        message_id = header.decode()[4]
+        assert message_id in LddsMessageConstants.VALID_IDS, (
+            f"Invalid LDDS message header - ID = '{message_id}'"
+        )
+
+        message_length = LddsMessage.get_message_length(header)
+        message_data = message[header_length:]
+
+        ldds_message = LddsMessage(
+            message_id=message_id,
+            message_length=message_length,
+            message_data=message_data,
+            header=header,
+        )
+        ldds_message.check_other_errors()
+        ldds_message.check_server_errors()
+
+        return ldds_message
+
+    @staticmethod
+    def get_message_length(
+        message: bytes,
+    ) -> int:
+        message_length_str = message[5:10].decode().replace(" ", "0")
+        try:
+            message_length = int(message_length_str)
+        except ValueError:
+            raise ProtocolError(
+                f"Invalid LDDS message header - bad length field = '{message_length_str}'"
+            )
+        return message_length
+
+    @staticmethod
+    def get_total_length(
+        message: bytes,
+    ) -> int:
+        return (
+            LddsMessage.get_message_length(message)
+            + LddsMessageConstants.VALID_HEADER_LENGTH
+        )
+
+    @staticmethod
+    def create(message_id: str, message_data: bytes = b""):
+        """
+        Create a LDDS message from scratch.
+
+        :param message_id: The ID of the message.
+        :param message_data: The data of the message in bytes.
+        :return: A new LddsMessage instance.
+        """
+        message_length = len(message_data)
+        ldds_message = LddsMessage(
+            message_id=message_id,
+            message_length=message_length,
+            message_data=message_data,
+        )
+        ldds_message.__make_header()
+        return ldds_message
+
+    def __make_header(self):
+        """
+        Generate the header for the LDDS message.
+        """
+        header = bytearray(LddsMessageConstants.VALID_HEADER_LENGTH)
+        header[:4] = LddsMessageConstants.VALID_SYNC_CODE
+        header[4] = ord(self.message_id)
+
+        message_length_str = f"{self.message_length:05d}"
+        header[5:10] = (
+            message_length_str.encode()
+        )  # Set the message length in the header
+        self.header = header
+
+    def to_bytes(self):
+        """
+        Convert the LDDS message to bytes.
+
+        :return: The message in bytes.
+        """
+        return self.header + self.message_data
+
+    def __eq__(self, other):
+        """
+        Check equality with another LddsMessage instance.
+
+        :param other: Another LddsMessage instance to compare with.
+        :return: True if equal, False otherwise.
+        """
+        return (
+            self.message_length == other.message_length
+            and self.message_id == other.message_id
+            and self.message_data == other.message_data
+        )
+
+    def is_end_of_message(self):
+        server_error = ServerError.parse(self.message_data)
+        if server_error.server_code_no in (
+            ServerErrorCode.DUNTIL.value,
+            ServerErrorCode.DUNTILDRS.value,
+        ):
+            return True
+        return False
+
+    def is_success(self):
+        server_error = ServerError.parse(self.message_data)
+        if server_error.server_code_no == 0 and server_error.system_code_no == 0:
+            return True
+        return False

dcpmessage/logs.py

@@ -0,0 +1,9 @@
+import logging
+
+
+def get_logger():
+    logger_ = logging.getLogger(__name__)
+    return logger_
+
+
+logger = get_logger()

dcpmessage/search_criteria.py

@@ -0,0 +1,207 @@
+import json
+import os
+from dataclasses import dataclass
+from enum import UNIQUE, Enum, verify
+
+from .logs import get_logger
+
+logger = get_logger()
+
+
+@verify(UNIQUE)
+class DcpMessageSource(Enum):
+    """
+    Enumeration for DCP message sources with unique values.
+
+
+    :param GOES: Represents a standard GOES message source.
+    :param GOES_SELFTIMED: Represents a self-timed GOES message source.
+    :param GOES_RANDOM: Represents a random GOES message source.
+    """
+
+    GOES = 0x00000000
+    GOES_SELFTIMED = 0x00010000
+    GOES_RANDOM = 0x00020000
+
+
+@dataclass
+class SearchCriteriaConstants:
+    """
+    Constants used in SearchCriteria.
+
+
+    :param max_sources: The maximum number of sources that can be added to the search criteria.
+    """
+
+    max_sources: int = 12
+
+
+class DcpAddress:
+    """
+    Class representing a DCP address.
+
+
+    :param address: (str) The DCP address, which must be 8 characters long.
+    """
+
+    def __init__(self, address: str):
+        """
+        Initialize the DcpAddress with a given address.
+
+        :param address: The address string, which must be exactly 8 characters long.
+        :raises AssertionError: If the address is not 8 characters long.
+        """
+        assert len(address) == 8
+        self.address = address
+
+    def __eq__(self, other):
+        """
+        Compare two DcpAddress objects for equality.
+
+        :param other: The other DcpAddress object to compare with.
+        :return: True if the addresses are the same, False otherwise.
+        """
+        return self.address == other.address
+
+
+class SearchCriteria:
+    def __init__(
+        self,
+        lrgs_since: str,
+        lrgs_until: str,
+        dcp_address: list[DcpAddress],
+        sources: list[int],
+    ):
+        """
+        Initialize the SearchCriteria with provided parameters.
+
+        :param lrgs_since: The start time for the search criteria.
+        :param lrgs_until: The end time for the search criteria.
+        :param dcp_address: A list of DCP addresses to search for.
+        :param sources: A list of sources to include in the search.
+        """
+        self.lrgs_since = lrgs_since
+        self.lrgs_until = lrgs_until
+        self.dcp_address = dcp_address
+        self.sources = [0 for _ in range(SearchCriteriaConstants.max_sources)]
+        self.num_sources = 0
+        for source in sources:
+            self.__add_source(source)
+
+    @classmethod
+    def from_file(
+        cls,
+        file: str,
+    ) -> "SearchCriteria":
+        """
+        Create a SearchCriteria object from a JSON file.
+
+        :param file: Path to the JSON file containing search criteria.
+        :return: A SearchCriteria object.
+        :raises Exception: If there is an issue parsing the JSON file.
+        """
+        with open(file, "r") as json_file:
+            json_data = json.load(json_file)
+        return cls.from_dict(json_data)
+
+    @classmethod
+    def from_dict(
+        cls,
+        data: dict,
+    ) -> "SearchCriteria":
+        """
+        Create a SearchCriteria object from a dict.
+
+        :param data: dict containing search criteria data.
+        :return: A SearchCriteria object.
+        :raises Exception: If there is an issue parsing the JSON file.
+        """
+
+        lrgs_since, lrgs_until, dcp_addresses, sources = "last", "now", [], []
+        try:
+            for key_word_, data in data.items():
+                match key_word_:
+                    case "DRS_SINCE":
+                        lrgs_since = data
+                    case "DRS_UNTIL":
+                        lrgs_until = data
+                    case "DCP_ADDRESS":
+                        data = list(set(data))
+                        dcp_addresses = [DcpAddress(x) for x in data]
+                    case "SOURCE":
+                        data = list(set(data))
+                        sources = [DcpMessageSource[x].value for x in data]
+                    case _:
+                        logger.debug(
+                            f"Unrecognized key word {key_word_} in Search Criteria. Will be ignored."
+                        )
+            search_criteria = cls(lrgs_since, lrgs_until, dcp_addresses, sources)
+            logger.debug(str(search_criteria))
+            return search_criteria
+        except Exception as ex:
+            raise Exception(f"Unexpected exception parsing search-criteria: {ex}")
+
+    def __add_source(
+        self,
+        source: int,
+    ):
+        """
+        Add a source to the search criteria if not already present.
+
+        :param source: The source identifier to add.
+        """
+        if self.num_sources >= SearchCriteriaConstants.max_sources:
+            return
+        if source not in self.sources:
+            self.sources[self.num_sources] = source
+            self.num_sources += 1
+
+    def __str__(self) -> str:
+        """
+        Convert the SearchCriteria to a string format for easy readability.
+
+        :return: A string representation of the search criteria.
+        """
+        line_separator = os.linesep
+
+        ret = ["#\n# LRGS Search Criteria\n#\n"]
+
+        if self.lrgs_since:
+            ret.append(f"DRS_SINCE: {self.lrgs_since}{line_separator}")
+        if self.lrgs_until:
+            ret.append(f"DRS_UNTIL: {self.lrgs_until}{line_separator}")
+        for dcp_address_ in self.dcp_address:
+            ret.append(f"DCP_ADDRESS: {dcp_address_.address}{line_separator}")
+
+        for i in range(self.num_sources):
+            source_name = DcpMessageSource(self.sources[i]).name
+            ret.append(f"SOURCE: {source_name}{line_separator}")
+
+        return "".join(ret)
+
+    def __bytes__(self) -> bytes:
+        """
+        Convert the SearchCriteria object to a bytes format for network transmission.
+
+        :return: A bytes representation of the search criteria.
+        """
+        return self.__str__().encode("utf-8")
+
+    def __eq__(self, other) -> bool:
+        """
+        Compare two SearchCriteria objects for equality.
+
+        :param other: The other SearchCriteria object to compare with.
+        :return: True if the criteria are the same, False otherwise.
+        """
+        if self.lrgs_since != other.lrgs_since or self.lrgs_until != other.lrgs_until:
+            return False
+
+        if len(self.dcp_address) != len(other.dcp_address):
+            return False
+
+        for explicit_dcp_address in self.dcp_address:
+            if explicit_dcp_address not in other.dcp_address:
+                return False
+
+        return True

dcpmessage/utils.py

@@ -0,0 +1,29 @@
+from binascii import hexlify
+from typing import Union
+
+
+class ByteUtil:
+    @staticmethod
+    def extract_string(b: Union[bytes, bytearray], offset: int = 0) -> str:
+        """
+        Pull a null-terminated string out of a byte array starting at given offset.
+
+        :param b: The byte array to extract string from.
+        :param offset: The offset to start reading from. Default is 0.
+        :return: The extracted string.
+        """
+        end = b.find(b"\x00", offset)
+        if end == -1:
+            return b[offset:].decode()
+        else:
+            return b[offset:end].decode()
+
+    @staticmethod
+    def to_hex_string(b: Union[bytes, bytearray]):
+        """
+        Convert byte array to hex string.
+
+        :param b: The byte array to convert to hex string.
+        :return: Hex string of byte array.
+        """
+        return hexlify(b).decode("utf-8").upper()  # Use uppercase hexadecimal

dcpmessage-1.2.2.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,13 @@
+dcpmessage/__init__.py,sha256=-y3OO-k0JChl6mStbgLMgDZ-HMyu9h9Zn7MC5q58UBA,36
+dcpmessage/credentials.py,sha256=A3dmT0StQJDRKZVWFlpwqZrj3I76NM4DDnPsgscPDo8,4516
+dcpmessage/dcp_message.py,sha256=SQgK6e1FLOLjBTTAdhwURUY0_j_DQo7Gwlk7mdzfxjc,4155
+dcpmessage/exceptions.py,sha256=qbkQNZ7bVoJh-2-jeUpZZkKFit3lbkovHWtTiyW9HxE,5943
+dcpmessage/ldds_client.py,sha256=MmSuotfA7vhGX7j7peKmu8cQKApjYlS-0xfJmpNfyfI,8319
+dcpmessage/ldds_message.py,sha256=75nipjgSHDLYWCeO4YtX-aR9NpsYidsyz3BGonEfFoI,6640
+dcpmessage/logs.py,sha256=3Dj0CyalYxgQN1vwjsLT3xqojA3D9losGzDLiKgOmV8,120
+dcpmessage/search_criteria.py,sha256=qgK-Cmj_oAStB3DzoqHSfGa87Mr4zspzEU2aiHDw-wU,6461
+dcpmessage/utils.py,sha256=U6RFrjkh5Nkz1tS6nis60yUnCu4T6jXkKUDwlYgmQkU,915
+dcpmessage-1.2.2.dist-info/METADATA,sha256=N6wS4u1DTbHXIY9NxDR3bYsU83GyMxwjA7L0TuBz33Q,2105
+dcpmessage-1.2.2.dist-info/WHEEL,sha256=CmyFI0kx5cdEMTLiONQRbGQwjIoR1aIYB7eCAQ4KPJ0,91
+dcpmessage-1.2.2.dist-info/top_level.txt,sha256=EMzYCEnuoZVsSJ6FL4C2py9r3SG7tpO4HEkDCTSLU4E,11
+dcpmessage-1.2.2.dist-info/RECORD,,

dcpmessage-1.2.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (78.1.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

dcpmessage-1.2.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+dcpmessage