add functionality for capability to send out messages, rename 'IntersectClientMessageParams' to 'DirectMessageParams'

Signed-off-by: Lance Drane <dranelt@ornl.gov>

Author: Lance-Drane

examples/1_hello_world/hello_client.py

@@ -2,10 +2,10 @@
 
 from intersect_sdk import (
     INTERSECT_JSON_VALUE,
+    DirectMessageParams,
     IntersectClient,
     IntersectClientCallback,
     IntersectClientConfig,
-    IntersectClientMessageParams,
     default_intersect_lifecycle_loop,
 )
 
@@ -74,7 +74,7 @@ def simple_client_callback(
       you'll get a message back.
     """
     initial_messages = [
-        IntersectClientMessageParams(
+        DirectMessageParams(
             destination='hello-organization.hello-facility.hello-system.hello-subsystem.hello-service',
             operation='HelloExample.say_hello_to_name',
             payload='hello_client',

examples/1_hello_world_amqp/hello_client.py

@@ -2,10 +2,10 @@
 
 from intersect_sdk import (
     INTERSECT_JSON_VALUE,
+    DirectMessageParams,
     IntersectClient,
     IntersectClientCallback,
     IntersectClientConfig,
-    IntersectClientMessageParams,
     default_intersect_lifecycle_loop,
 )
 
@@ -76,7 +76,7 @@ def simple_client_callback(
       you'll get a message back.
     """
     initial_messages = [
-        IntersectClientMessageParams(
+        DirectMessageParams(
             destination='hello-organization.hello-facility.hello-system.hello-subsystem.hello-service',
             operation='HelloExample.say_hello_to_name',
             payload='hello_client',

examples/1_hello_world_events/hello_client.py

@@ -2,10 +2,10 @@
 
 from intersect_sdk import (
     INTERSECT_JSON_VALUE,
+    DirectMessageParams,
     IntersectClient,
     IntersectClientCallback,
     IntersectClientConfig,
-    IntersectClientMessageParams,
     default_intersect_lifecycle_loop,
 )
 
@@ -95,7 +95,7 @@ def simple_event_callback(
       you'll get a message back.
     """
     initial_messages = [
-        IntersectClientMessageParams(
+        DirectMessageParams(
             destination='hello-organization.hello-facility.hello-system.hello-subsystem.hello-service',
             operation='HelloExample.say_hello_to_name',
             payload='hello_client',

examples/2_counting/counting_client.py

@@ -4,10 +4,10 @@
 
 from intersect_sdk import (
     INTERSECT_JSON_VALUE,
+    DirectMessageParams,
     IntersectClient,
     IntersectClientCallback,
     IntersectClientConfig,
-    IntersectClientMessageParams,
     default_intersect_lifecycle_loop,
 )
 
@@ -38,7 +38,7 @@ def __init__(self) -> None:
         self.message_stack = [
             # wait 5 seconds before stopping the counter. "Count" in response will be approx. 6
             (
-                IntersectClientMessageParams(
+                DirectMessageParams(
                     destination='counting-organization.counting-facility.counting-system.counting-subsystem.counting-service',
                     operation='CountingExample.stop_count',
                     payload=None,
@@ -47,7 +47,7 @@ def __init__(self) -> None:
             ),
             # start the counter up again - it will not be 0 at this point! "Count" in response will be approx. 7
             (
-                IntersectClientMessageParams(
+                DirectMessageParams(
                     destination='counting-organization.counting-facility.counting-system.counting-subsystem.counting-service',
                     operation='CountingExample.start_count',
                     payload=None,
@@ -56,7 +56,7 @@ def __init__(self) -> None:
             ),
             # reset the counter, but have it immediately start running again. "Count" in response will be approx. 10
             (
-                IntersectClientMessageParams(
+                DirectMessageParams(
                     destination='counting-organization.counting-facility.counting-system.counting-subsystem.counting-service',
                     operation='CountingExample.reset_count',
                     payload=True,
@@ -65,7 +65,7 @@ def __init__(self) -> None:
             ),
             # reset the counter, but don't have it run again. "Count" in response will be approx. 6
             (
-                IntersectClientMessageParams(
+                DirectMessageParams(
                     destination='counting-organization.counting-facility.counting-system.counting-subsystem.counting-service',
                     operation='CountingExample.reset_count',
                     payload=False,
@@ -74,7 +74,7 @@ def __init__(self) -> None:
             ),
             # start the counter back up. "Count" in response will be approx. 1
             (
-                IntersectClientMessageParams(
+                DirectMessageParams(
                     destination='counting-organization.counting-facility.counting-system.counting-subsystem.counting-service',
                     operation='CountingExample.start_count',
                     payload=None,
@@ -83,7 +83,7 @@ def __init__(self) -> None:
             ),
             # finally, stop the counter one last time. "Count" in response will be approx. 4
             (
-                IntersectClientMessageParams(
+                DirectMessageParams(
                     destination='counting-organization.counting-facility.counting-system.counting-subsystem.counting-service',
                     operation='CountingExample.stop_count',
                     payload=None,
@@ -158,7 +158,7 @@ def client_callback(
     # The counter will start after the initial message.
     # If the service is already active and counting, this may do nothing.
     initial_messages = [
-        IntersectClientMessageParams(
+        DirectMessageParams(
             destination='counting-organization.counting-facility.counting-system.counting-subsystem.counting-service',
             operation='CountingExample.start_count',
             payload=None,

src/intersect_sdk/__init__.py

@@ -13,9 +13,7 @@
 from .client_callback_definitions import (
     INTERSECT_CLIENT_EVENT_CALLBACK_TYPE,
     INTERSECT_CLIENT_RESPONSE_CALLBACK_TYPE,
-    INTERSECT_JSON_VALUE,
     IntersectClientCallback,
-    IntersectClientMessageParams,
 )
 from .config.client import IntersectClientConfig
 from .config.service import IntersectServiceConfig
@@ -28,12 +26,19 @@
 from .core_definitions import IntersectDataHandler, IntersectMimeType
 from .schema import get_schema_from_capability_implementation
 from .service import IntersectService
+from .service_callback_definitions import (
+    INTERSECT_SERVICE_RESPONSE_CALLBACK_TYPE,
+)
 from .service_definitions import (
     IntersectEventDefinition,
     intersect_event,
     intersect_message,
     intersect_status,
 )
+from .shared_callback_definitions import (
+    INTERSECT_JSON_VALUE,
+    DirectMessageParams,
+)
 from .version import __version__, version_info, version_string
 
 __all__ = [
@@ -47,10 +52,11 @@
     'IntersectService',
     'IntersectClient',
     'IntersectClientCallback',
-    'IntersectClientMessageParams',
+    'DirectMessageParams',
     'INTERSECT_CLIENT_RESPONSE_CALLBACK_TYPE',
     'INTERSECT_CLIENT_EVENT_CALLBACK_TYPE',
     'INTERSECT_JSON_VALUE',
+    'INTERSECT_SERVICE_RESPONSE_CALLBACK_TYPE',
     'IntersectBaseCapabilityImplementation',
     'default_intersect_lifecycle_loop',
     'IntersectClientConfig',

src/intersect_sdk/_internal/interfaces.py

@@ -1,5 +1,17 @@
+from __future__ import annotations
+
 from abc import ABC, abstractmethod
-from typing import Any
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from uuid import UUID
+
+    from ..service_callback_definitions import (
+        INTERSECT_SERVICE_RESPONSE_CALLBACK_TYPE,
+    )
+    from ..shared_callback_definitions import (
+        DirectMessageParams,
+    )
 
 
 class IntersectEventObserver(ABC):
@@ -18,3 +30,20 @@ def _on_observe_event(self, event_name: str, event_value: Any, operation: str) -
             operation: The source of the event (generally the function name, not directly invoked by application devs)
         """
         ...
+
+    @abstractmethod
+    def create_external_request(
+        self,
+        request: DirectMessageParams,
+        response_handler: INTERSECT_SERVICE_RESPONSE_CALLBACK_TYPE | None = None,
+    ) -> UUID:
+        """Observed entity (capabilitiy) tells observer (i.e. service) to send an external request.
+
+        Params:
+          - request: the request we want to send out, encapsulated as an IntersectClientMessageParams object
+          - response_handler: optional callback for how we want to handle the response from this request.
+
+        Returns:
+          - generated RequestID associated with your request
+        """
+        ...

src/intersect_sdk/_internal/messages/userspace.py

@@ -2,6 +2,13 @@
 
 This module is internal-facing and should not be used directly by users.
 
+Services have two associated channels which handle userspace messages: their request channel
+and their response channel. Services always CONSUME messages from these channels, but never PRODUCE messages
+on these channels. (A message is always sent in the receiver's namespace).
+
+The response channel is how the service handles external requests, the request channel is used when this service itself
+needs to make external requests through INTERSECT.
+
 Services should ALWAYS be CONSUMING from their userspace channel.
 They should NEVER be PRODUCING messages on their userspace channel.
 

src/intersect_sdk/capability/base.py

@@ -11,7 +11,15 @@
 from .._internal.logger import logger
 
 if TYPE_CHECKING:
+    from uuid import UUID
+
     from .._internal.interfaces import IntersectEventObserver
+    from ..service_callback_definitions import (
+        INTERSECT_SERVICE_RESPONSE_CALLBACK_TYPE,
+    )
+    from ..shared_callback_definitions import (
+        DirectMessageParams,
+    )
 
 
 class IntersectBaseCapabilityImplementation:
@@ -39,14 +47,20 @@ def __init__(self) -> None:
         """
 
     def __init_subclass__(cls) -> None:
-        """This prevents users from overriding a few key functions."""
+        """This prevents users from overriding a few key functions.
+
+        General rule of thumb is that any function which starts with "intersect_sdk_" is a protected namespace for defining
+        the INTERSECT-SDK public API between a capability and its observers.
+        """
         if (
             cls._intersect_sdk_register_observer
             is not IntersectBaseCapabilityImplementation._intersect_sdk_register_observer
             or cls.intersect_sdk_emit_event
             is not IntersectBaseCapabilityImplementation.intersect_sdk_emit_event
+            or cls.intersect_sdk_call_service
+            is not IntersectBaseCapabilityImplementation.intersect_sdk_call_service
         ):
-            msg = f"{cls.__name__}: Cannot override functions '_intersect_sdk_register_observer' or 'intersect_sdk_emit_event'"
+            msg = f"{cls.__name__}: Attempted to override a reserved INTERSECT-SDK function (don't start your function names with '_intersect_sdk_' or 'intersect_sdk_')"
             raise RuntimeError(msg)
 
     @property
@@ -113,3 +127,27 @@ def intersect_sdk_emit_event(self, event_name: str, event_value: Any) -> None:
             return
         for observer in self.__intersect_sdk_observers__:
             observer._on_observe_event(event_name, event_value, annotated_operation)  # noqa: SLF001 (private for application devs, NOT for base implementation)
+
+    @final
+    def intersect_sdk_call_service(
+        self,
+        request: DirectMessageParams,
+        response_handler: INTERSECT_SERVICE_RESPONSE_CALLBACK_TYPE | None = None,
+    ) -> list[UUID]:
+        """Create an external request that we'll send to a different Service.
+
+        Params:
+          - request: the request we want to send out, encapsulated as an IntersectClientMessageParams object
+          - response_handler: optional callback for how we want to handle the response from this request.
+
+        Returns:
+          - list of generated RequestIDs associated with your request. Note that for almost all use cases,
+            this list will have only one associated RequestID.
+
+        Raises:
+          - pydantic.ValidationError - if the request parameter isn't valid
+        """
+        return [
+            observer.create_external_request(request, response_handler)
+            for observer in self.__intersect_sdk_observers__
+        ]

src/intersect_sdk/client.py

@@ -40,7 +40,6 @@
 from ._internal.version_resolver import resolve_user_version
 from .client_callback_definitions import (
     IntersectClientCallback,
-    IntersectClientMessageParams,
 )
 from .config.client import IntersectClientConfig
 from .config.shared import HierarchyConfig
@@ -50,6 +49,7 @@
         INTERSECT_CLIENT_EVENT_CALLBACK_TYPE,
         INTERSECT_CLIENT_RESPONSE_CALLBACK_TYPE,
     )
+    from .shared_callback_definitions import DirectMessageParams
 
 
 @final
@@ -425,7 +425,7 @@ def _handle_client_callback(self, user_value: IntersectClientCallback | None) ->
         for message in validated_result.messages_to_send:
             self._send_userspace_message(message)
 
-    def _send_userspace_message(self, params: IntersectClientMessageParams) -> None:
+    def _send_userspace_message(self, params: DirectMessageParams) -> None:
         """Send a userspace message, be it an initial message from the user or from the user's callback function."""
         # ONE: SERIALIZE FUNCTION RESULTS
         # (function input should already be validated at this point)

src/intersect_sdk/client_callback_definitions.py

@@ -1,52 +1,15 @@
-"""Data types used in regard to client callbacks. Only relevant for Client authors."""
+"""Data types used in regard to client callbacks. Only relevant for Client authors.
 
-from typing import Any, Callable, Dict, List, Optional, Union
+See shared_callback_definitions for additional typings which are also shared by service authors.
+"""
+
+from typing import Callable, Dict, List, Optional, Union
 
 from pydantic import BaseModel, ConfigDict, Field
 from typing_extensions import Annotated, TypeAlias, final
 
 from .constants import SYSTEM_OF_SYSTEM_REGEX
-from .core_definitions import IntersectDataHandler, IntersectMimeType
-
-
-class IntersectClientMessageParams(BaseModel):
-    """The user implementing the IntersectClient class will need to return this object in order to send a message to another Service."""
-
-    destination: Annotated[str, Field(pattern=SYSTEM_OF_SYSTEM_REGEX)]
-    """
-    The destination string. You'll need to know the system-of-system representation of the Service.
-
-    Note that this should match what you would see in the schema.
-    """
-
-    operation: str
-    """
-    The name of the operation you want to call from the Service - this should be represented as it is in the Service's schema.
-    """
-
-    payload: Any
-    """
-    The raw Python object you want to have serialized as the payload.
-
-    If you want to just use the service's default value for a request (assuming it has a default value for a request), you may set this as None.
-    """
-
-    content_type: IntersectMimeType = IntersectMimeType.JSON
-    """
-    The IntersectMimeType of your message. You'll want this to match with the ContentType of the function from the schema.
-
-    default: IntersectMimeType.JSON
-    """
-
-    data_handler: IntersectDataHandler = IntersectDataHandler.MESSAGE
-    """
-    The IntersectDataHandler you want to use (most people can just use IntersectDataHandler.MESSAGE here, unless your data is very large)
-
-    default: IntersectDataHandler.MESSAGE
-    """
-
-    # pydantic config
-    model_config = ConfigDict(revalidate_instances='always')
+from .shared_callback_definitions import DirectMessageParams
 
 
 @final
@@ -56,7 +19,7 @@ class IntersectClientCallback(BaseModel):
     If you do not return a value of this type (or None), this will be treated as an Exception and will break the pub-sub loop.
     """
 
-    messages_to_send: List[IntersectClientMessageParams] = []  # noqa: FA100 (runtime annotation)
+    messages_to_send: List[DirectMessageParams] = []  # noqa: FA100 (runtime annotation)
     """
     Messages to send as a result of an event or a response from a Service.
     """