intersect-sdk-common 0.0.0a0__py3-none-any.whl

intersect_sdk_common/__init__.py

@@ -0,0 +1,72 @@
+"""Common definitions shared across ALL INTERSECT services, be they domain science microservices or INTERSECT core services.
+
+You can use the base package as the public API, no need to import from submodules.
+
+IMPORTANT: If you are building a scientific microservice, do NOT import from this package. Instead, import from intersect-sdk, which is the public-facing library intended for you. Relevant definitions from this package will be re-exported there.
+"""
+
+from importlib import import_module
+from typing import TYPE_CHECKING
+
+# import everything eagerly for IDEs/LSPs
+if TYPE_CHECKING:
+    from .config import (
+        ControlPlaneConfig,
+        ControlProvider,
+        DataStoreConfig,
+        DataStoreConfigMap,
+        HierarchyConfig,
+    )
+    from .control_plane.control_plane_manager import ControlPlaneManager
+    from .control_plane.definitions import MessageCallback
+    from .core_definitions import IntersectDataHandler, IntersectMimeType
+    from .data_plane.data_plane_manager import DataPlaneManager
+    from .version import __version__, intersect_sdk_version_info, intersect_sdk_version_string
+
+__all__ = (
+    'ControlPlaneConfig',
+    'ControlPlaneManager',
+    'ControlProvider',
+    'DataPlaneManager',
+    'DataStoreConfig',
+    'DataStoreConfigMap',
+    'HierarchyConfig',
+    'IntersectDataHandler',
+    'IntersectMimeType',
+    'MessageCallback',
+    '__version__',
+    'intersect_sdk_version_info',
+    'intersect_sdk_version_string',
+)
+
+# PEP 562 stuff: do lazy imports for people who just want to import from the top-level module
+
+__lazy_imports = {
+    'ControlPlaneConfig': '.config',
+    'ControlProvider': '.config',
+    'DataStoreConfig': '.config',
+    'DataStoreConfigMap': '.config',
+    'HierarchyConfig': '.config',
+    'ControlPlaneManager': '.control_plane.control_plane_manager',
+    'MessageCallback': '.control_plane.definitions',
+    'IntersectDataHandler': '.core_definitions',
+    'IntersectMimeType': '.core_definitions',
+    'DataPlaneManager': '.data_plane.data_plane_manager',
+    '__version__': '.version',
+    'intersect_sdk_version_info': '.version',
+    'intersect_sdk_version_string': '.version',
+}
+
+
+def __getattr__(attr_name: str) -> object:
+    attr_module = __lazy_imports.get(attr_name)
+    if attr_module:
+        module = import_module(attr_module, package=__spec__.parent)
+        return getattr(module, attr_name)
+
+    msg = f'module {__name__!r} has no attribute {attr_name!r}'
+    raise AttributeError(msg)
+
+
+def __dir__() -> list[str]:
+    return list(__all__)

intersect_sdk_common/config.py

@@ -0,0 +1,168 @@
+"""Configuration types shared across both Clients and Services."""
+
+from dataclasses import dataclass, field
+from typing import Annotated, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, PositiveInt
+
+from .core_definitions import IntersectDataHandler
+
+HIERARCHY_REGEX = r'^[a-z]((?!--)[a-z0-9-]){2,62}$'
+"""
+The hierarchy regex needs to be fairly restricted due to the number of different
+systems we want to be compatible with. The rules:
+
+- Only allow unreserved characters (alphanumeric and .-~_): https://datatracker.ietf.org/doc/html/rfc3986#section-2.3
+- Require lowercase letters to avoid incompatibilities with case-insensitive systems.
+- MinIO has been found to forbid _ and ~ characters
+- MinIO requires an alphanumeric character at the start of the string
+- No adjacent non-alphanumeric characters allowed
+- Range should be from 3-63 characters
+
+The following commit tracks several issues with MINIO: https://code.ornl.gov/intersect/additive-manufacturing/ros-intersect-adapter/-/commit/fa71b791be0ccf1a5884910b5be3b5239cf9896f
+"""
+
+ControlProvider = Literal['mqtt5.0', 'amqp0.9.1']
+"""The type of broker we connect to."""
+
+
+class HierarchyConfig(BaseModel):
+    """Configuration for registering this service in a system-of-system architecture."""
+
+    service: Annotated[str, Field(pattern=HIERARCHY_REGEX)]
+    """
+    The name of this application - should be unique within an INTERSECT system
+    """
+
+    subsystem: str | None = Field(default=None, pattern=HIERARCHY_REGEX)
+    """
+    An associated subsystem / service-grouping of the system (should be unique within an INTERSECT system)
+    """
+
+    system: Annotated[str, Field(pattern=HIERARCHY_REGEX)]
+    """
+    Name of the "system", could also be thought of as a "device" (should be unique within a facility)
+    """
+
+    facility: Annotated[str, Field(pattern=HIERARCHY_REGEX)]
+    """
+    Name of the facility (an ORNL institutional designation, i.e. 'neutrons') (NOT abbreviated, should be unique within an organization)
+    """
+
+    organization: Annotated[str, Field(pattern=HIERARCHY_REGEX)]
+    """
+    Name of the organization (i.e. 'ornl') (NOT abbreviated) (should be unique in an INTERSECT cluster)
+    """
+
+    def hierarchy_string(self, join_str: str = '') -> str:
+        """Get the full hierarchy string. This is mostly used internally, but if you're developing a client, it could potentially be helpful.
+
+        Params
+          join_str: String used to separate different hierarchy parts in the full string (default: empty string).
+
+        Returns:
+          Single string, which will contain all system-of-system parts. For optional parts not configured (i.e. - no subsystem), they will be represented by a "-" character.
+        """
+        if not self.subsystem:
+            return join_str.join([self.organization, self.facility, self.system, '-', self.service])
+        return join_str.join(
+            [
+                self.organization,
+                self.facility,
+                self.system,
+                self.subsystem,
+                self.service,
+            ]
+        )
+
+    # we need to use the Python regex engine instead of the Rust regex engine here, because Rust's does not support lookaheads
+    model_config = ConfigDict(regex_engine='python-re')
+
+
+@dataclass
+class ControlPlaneConfig:
+    """Configuration for interacting with a broker."""
+
+    protocol: ControlProvider
+    """
+    The protocol of the broker you'd like to use (i.e. AMQP, MQTT...)
+    """
+    # TODO - support more protocols and protocol versions as needed - see https://www.asyncapi.com/docs/reference/specification/v2.6.0#serverObject
+
+    username: Annotated[str, Field(min_length=1)]
+    """
+    Username credentials for broker connection.
+    """
+
+    password: Annotated[str, Field(min_length=1)]
+    """
+    Password credentials for broker connection.
+    """
+
+    host: Annotated[str, Field(min_length=1)] = '127.0.0.1'
+    """
+    Broker hostname (default: 127.0.0.1)
+    """
+
+    port: PositiveInt | None = None
+    """
+    Broker port. List of common ports:
+
+    - 1883 (MQTT)
+    - 4222 (NATS default port)
+    - 5222 (XMPP)
+    - 5223 (XMPP over TLS)
+    - 5671 (AMQP over TLS)
+    - 5672 (AMQP)
+    - 7400 (DDS Discovery)
+    - 7401 (DDS User traffic)
+    - 8883 (MQTT over TLS)
+    - 61613 (RabbitMQ STOMP - WARNING: ephemeral port)
+
+    NOTE: INTERSECT currently only supports AMQP and MQTT.
+    """
+
+
+@dataclass
+class DataStoreConfig:
+    """Configuration for interacting with a data store."""
+
+    username: Annotated[str, Field(min_length=1)]
+    """
+    Username credentials for data store connection.
+    """
+
+    password: Annotated[str, Field(min_length=1)]
+    """
+    Password credentials for data store connection.
+    """
+
+    host: Annotated[str, Field(min_length=1)] = '127.0.0.1'
+    """
+    Data store hostname (default: 127.0.0.1)
+    """
+
+    port: PositiveInt | None = None
+    """
+    Data store port
+    """
+
+
+@dataclass
+class DataStoreConfigMap:
+    """Configurations for any data stores the application should talk to."""
+
+    minio: list[DataStoreConfig] = field(default_factory=list)
+    """
+    minio configurations
+    """
+
+    def get_missing_data_store_types(self) -> set[IntersectDataHandler]:
+        """Return a set of IntersectDataHandlers which will not be permitted, due to a configuration type missing.
+
+        If all data configurations exist, returns an empty set
+        """
+        missing = set()
+        if not self.minio:
+            missing.add(IntersectDataHandler.MINIO)
+        return missing

intersect_sdk_common/constants.py

@@ -0,0 +1,28 @@
+"""These are miscellaneous constants used in INTERSECT which SDK users may obtain value from knowing about."""
+
+SYSTEM_OF_SYSTEM_REGEX = r'^[a-z0-9][-a-z0-9.]*[-a-z0-9]$'
+"""
+This is the regex used as a representation of a source/destination.
+This is only needed externally if you are building a client, services can ignore this.
+
+NOTE: for future compatibility reasons, we are NOT specifying the number of "parts" (separated by a '.') in this regex. All that matters is that you don't start or end with a period, or start with a hyphen.
+"""
+
+# see the internal schema file for full validation details
+CAPABILITY_REGEX = r'^[a-zA-Z0-9]\w*$'
+"""
+This is the regex used for representing capabilities and event keys. Capabilities should start with an alphanumeric character, and not be longer than 255 characters.
+
+This regex applies to namespacing local to a Service, so does not have to be unique across the ecosystem.
+"""
+
+MIME_TYPE_REGEX = r'\w+/[-+.\w]+'
+"""
+Regex used for validating Content Types.
+
+References can be found at:
+
+- https://www.iana.org/assignments/media-types/media-types.xhtml
+
+- https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types
+"""

intersect_sdk_common/control_plane/__init__.py

@@ -0,0 +1 @@
+"""Logic associated with the control plane."""

intersect_sdk_common/control_plane/brokers/__init__.py

@@ -0,0 +1,4 @@
+"""Common logic for interacting with brokers on the protocol level.
+
+These classes should be kept internal to the common library.
+"""