slim-bindings 0.7.1__cp313-cp313-win_amd64.whl

slim_bindings/errors.py

@@ -0,0 +1,52 @@
+# Copyright AGNTCY Contributors (https://github.com/agntcy)
+# SPDX-License-Identifier: Apache-2.0
+
+from asyncio import TimeoutError
+
+
+class SLIMTimeoutError(TimeoutError):
+    """
+    Exception raised for SLIM timeout errors.
+
+    This exception is raised when an operation in an SLIM session times out.
+    It encapsulates detailed information about the timeout event, including the
+    ID of the message that caused the timeout and the session identifier. An
+    optional underlying exception can also be provided to offer additional context.
+
+    Attributes:
+        message_id (int): The identifier associated with the message triggering the timeout.
+        session_id (int): The identifier of the session where the timeout occurred.
+        message (str): A brief description of the timeout error.
+        original_exception (Exception, optional): The underlying exception that caused the timeout, if any.
+
+    The string representation of the exception (via __str__) returns a full message that
+    includes the custom message, session ID, and message ID, as well as details of the
+    original exception (if present). This provides a richer context when the exception is logged
+    or printed.
+    """
+
+    def __init__(
+        self,
+        message_id: int,
+        session_id: int,
+        message: str = "SLIM timeout error",
+        original_exception: Exception | None = None,
+    ):
+        self.message_id = message_id
+        self.session_id = session_id
+        self.message = message
+        self.original_exception = original_exception
+        full_message = f"{message} for session {session_id} and message {message_id}"
+        if original_exception:
+            full_message = f"{full_message}. Caused by: {original_exception!r}"
+        super().__init__(full_message)
+
+    def __str__(self):
+        return self.args[0]
+
+    def __repr__(self):
+        return (
+            f"{self.__class__.__name__}(session_id={self.session_id!r}, "
+            f"message_id={self.message_id!r}, "
+            f"message={self.message!r}, original_exception={self.original_exception!r})"
+        )

slim_bindings/session.py

@@ -0,0 +1,178 @@
+# Copyright AGNTCY Contributors (https://github.com/agntcy)
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import datetime
+
+from ._slim_bindings import (
+    CompletionHandle,
+    MessageContext,
+    Name,
+    SessionConfiguration,
+    SessionContext,
+    SessionType,
+)
+
+
+class Session:
+    """High level Python wrapper around a `SessionContext`.
+
+    This object provides a Pythonic façade over the lower-level Rust session
+    context. It retains a reference to the owning `App` so the existing
+    service-level binding functions (publish, invite, remove, get_message,
+    delete_session) can be invoked without duplicating logic on the Rust side.
+
+    Threading / Concurrency:
+        The methods are all async (where network / I/O is involved) and are
+        safe to await concurrently.
+
+    Lifecycle:
+        A `Session` is typically obtained from `Slim.create_session(...)`
+        or `Slim.listen_for_session(...)`. Call `delete()`to release
+        server-side resources.
+
+    Attributes (properties):
+        id (int): Unique numeric session identifier.
+        metadata (dict[str, str]): Free-form key/value metadata attached
+            to the current session configuration.
+        session_type (SessionType): PointToPoint / Group classification.
+        session_config (SessionConfiguration): Current effective configuration.
+        src (Name): Source name (creator / initiator of the session).
+        dst (Name): Destination name (PointToPoint), Channel name (group)
+    """
+
+    def __init__(self, ctx: SessionContext):
+        self._ctx = ctx
+
+    @property
+    def id(self) -> int:
+        """Return the unique numeric identifier for this session."""
+        return self._ctx.id  # exposed by SessionContext
+
+    @property
+    def metadata(self) -> dict[str, str]:
+        """Return a copy of the session metadata mapping (string keys/values)."""
+        return self._ctx.metadata
+
+    @property
+    def session_type(self) -> SessionType:
+        """Return the type of this session (PointToPoint / Group)."""
+        return self._ctx.session_type
+
+    @property
+    def session_config(self) -> SessionConfiguration:
+        """Return the current effective session configuration enum variant."""
+        return self._ctx.session_config
+
+    @property
+    def src(self) -> Name:
+        """Return the source name of this session."""
+        return self._ctx.src
+
+    @property
+    def dst(self) -> Name | None:
+        """Return the destination name"""
+        return self._ctx.dst
+
+    async def publish(
+        self,
+        msg: bytes,
+        payload_type: str | None = None,
+        metadata: dict | None = None,
+    ) -> CompletionHandle:
+        """
+        Publish a message on the current session.
+
+        Args:
+            msg (bytes): The message payload to publish.
+            payload_type (str, optional): The type of the payload, if applicable.
+            metadata (dict, optional): Additional metadata to include with the
+                message.
+
+        Returns:
+            None
+        """
+
+        return await self._ctx.publish(
+            1,
+            msg,
+            message_ctx=None,
+            name=None,
+            payload_type=payload_type,
+            metadata=metadata,
+        )
+
+    async def publish_to(
+        self,
+        message_ctx: MessageContext,
+        msg: bytes,
+        payload_type: str | None = None,
+        metadata: dict | None = None,
+    ) -> CompletionHandle:
+        """
+        Publish a message directly back to the originator associated with the
+        supplied `message_ctx` (reply semantics).
+
+        Args:
+            message_ctx: The context previously received with a message from
+                `get_message()` / `recv()`. Provides addressing info.
+            msg: Raw bytes payload to send as the reply.
+            payload_type: Optional content-type / discriminator.
+            metadata: Optional message-scoped metadata.
+
+        Notes:
+            The explicit `dest` parameter is not required because the routing
+            information is derived from `message_ctx`.
+
+        Raises:
+            RuntimeError (wrapped) if sending fails or the session is closed.
+        """
+
+        return await self._ctx.publish_to(
+            message_ctx,
+            msg,
+            payload_type=payload_type,
+            metadata=metadata,
+        )
+
+    async def invite(self, name: Name) -> CompletionHandle:
+        """Invite (add) a participant to this session. Only works for Group.
+
+        Args:
+            name: Name of the participant to invite.
+
+        Raises:
+            RuntimeError (wrapped) if the invite fails.
+        """
+        return await self._ctx.invite(name)
+
+    async def remove(self, name: Name) -> CompletionHandle:
+        """Remove (eject) a participant from this session. Only works for Group.
+
+        Args:
+            name: Name of the participant to remove.
+
+        Raises:
+            RuntimeError (wrapped) if removal fails.
+        """
+        return await self._ctx.remove(name)
+
+    async def get_message(
+        self, timeout: datetime.timedelta | None = None
+    ) -> tuple[MessageContext, bytes]:  # MessageContext, blob
+        """Wait for and return the next inbound message.
+
+        Returns:
+            (MessageContext, bytes): A tuple containing the message context
+            (routing / origin metadata) and the raw payload bytes.
+
+        Raises:
+            RuntimeError (wrapped) if the session is closed or receive fails.
+        """
+        return await self._ctx.get_message(timeout)
+
+
+__all__ = [
+    "Session",
+]

slim_bindings/slim.py

@@ -0,0 +1,325 @@
+# Copyright AGNTCY Contributors (https://github.com/agntcy)
+# SPDX-License-Identifier: Apache-2.0
+
+from datetime import timedelta
+
+from slim_bindings._slim_bindings import (
+    App,
+    CompletionHandle,
+    IdentityProvider,
+    IdentityVerifier,
+    Name,
+    SessionConfiguration,
+    SessionContext,
+)
+
+from .session import Session
+
+
+class Slim:
+    """
+    High-level façade over the underlying Service (Rust core) providing a
+    Pythonic API for:
+      * Service initialization & authentication
+      * Client connections to remote Slim services (connect / disconnect)
+      * Server lifecycle management (run_server / stop_server)
+      * Subscription & routing management (subscribe / unsubscribe / set_route / remove_route)
+      * Session lifecycle (create_session / delete_session / listen_for_session)
+
+    Core Concepts:
+      - Name: Fully-qualified name of the app (org / namespace / app-or-channel). Used for
+        routing, subscriptions.
+      - Session: Logical communication context. Types supported include:
+          * PointToPoint  : Point-to-point with a fixed, stable destination (sticky).
+          * Group: Many-to-many via a named channel/topic.
+      - Default Session Configuration: A fallback used when inbound sessions are created
+        towards this service (set via set_default_session_config).
+
+    Typical Lifecycle (Client):
+      1. slim = Slim(local_name, identity_provider, identity_verifier)
+      2. await slim.connect({"endpoint": "...", "tls": {"insecure": True}})
+      3. await slim.set_route(remote_name)
+      4. session = await slim.create_session(SessionConfiguration.PointToPoint(peer_name=remote_name, ...))
+      5. await session.publish(b"payload")
+      6. await slim.delete_session(session)
+      7. await slim.disconnect("endpoint-string")
+
+    Typical Lifecycle (Server):
+      1. slim = Slim(local_name, provider, verifier)
+      2. await slim.run_server({"endpoint": "127.0.0.1:12345", "tls": {"insecure": True}})
+      3. inbound = await slim.listen_for_session()
+      4. msg_ctx, data = await inbound.get_message()
+      5. await inbound.publish_to(msg_ctx, b"reply")
+      6. await slim.stop_server("127.0.0.1:12345")
+
+    Threading / Concurrency:
+      - All network / I/O operations are async and awaitable.
+      - A single Slim instance can service multiple concurrent awaiters.
+
+    Error Handling:
+      - Methods propagate underlying exceptions (e.g., invalid routing, closed sessions).
+      - connect / run_server may raise if the endpoint is unreachable or already bound.
+
+    Performance Notes:
+      - Route changes are lightweight but may take a short time to propagate remotely.
+      - listen_for_session can be long-lived; provide a timeout if you need bounded wait.
+
+    Security Notes:
+      - Identity provider & verifier determine trust model (e.g. shared secret vs JWT).
+      - For production, prefer asymmetric keys / JWT over shared secrets.
+
+    """
+
+    def __init__(
+        self,
+        name: Name,
+        provider: IdentityProvider,
+        verifier: IdentityVerifier,
+        local_service: bool = False,
+    ):
+        """
+        Primary constructor for initializing a Slim instance.
+
+        Creates a Slim instance with the provided identity components and initializes
+        the underlying service handle.
+
+        Args:
+            name (Name): Fully qualified local name (org/namespace/app).
+            provider (IdentityProvider): Identity provider for authentication.
+            verifier (IdentityVerifier): Identity verifier for validating peers.
+            local_service (bool): Whether this is a local service. Defaults to False.
+
+        Note: Service initialization happens here via PyApp construction.
+        """
+
+        # Initialize service
+        self._app = App(
+            name,
+            provider,
+            verifier,
+            local_service=local_service,
+        )
+
+        # Create connection ID map
+        self.conn_ids: dict[str, int] = {}
+
+        # For the moment we manage one connection only
+        self.conn_id: int | None = None
+
+    @property
+    def id(self) -> int:
+        """Unique numeric identifier of the underlying app instance.
+
+        Returns:
+            int: Service ID allocated by the native layer.
+        """
+        return self._app.id
+
+    @property
+    def id_str(self) -> str:
+        """String representation of the unique identifier of the underlying app instance.
+
+        Returns:
+            str: String representation of the Service ID allocated by the native layer.
+        """
+
+        components_string = self.local_name.components_strings()
+
+        return f"{components_string[0]}/{components_string[1]}/{components_string[2]}/{self._app.id}"
+
+    @property
+    def local_name(self) -> Name:
+        """Local fully-qualified Name (org/namespace/app) for this app.
+
+        Returns:
+            Name: Immutable name used for routing, subscriptions, etc.
+        """
+        return self._app.name
+
+    async def create_session(
+        self,
+        destination: Name,
+        session_config: SessionConfiguration,
+    ) -> tuple[Session, CompletionHandle]:
+        """Create a new session and return its high-level Session wrapper.
+
+        Args:
+            destination (Name): Target peer or channel name.
+            session_config (SessionConfiguration): Parameters controlling creation.
+
+        Returns:
+            Session: Wrapper exposing high-level async operations for the session.
+        """
+        ctx, completion_handle = await self._app.create_session(
+            destination, session_config
+        )
+        return Session(ctx), completion_handle
+
+    async def delete_session(self, session: Session) -> CompletionHandle:
+        """
+        Terminate and remove an existing session.
+
+        Args:
+            session (Session): Session wrapper previously returned by create_session.
+
+        Returns:
+            None
+
+        Notes:
+            Underlying errors from delete_session are propagated.
+        """
+
+        # Remove the session from SLIM
+        return await self._app.delete_session(session._ctx)
+
+    async def run_server(self, config: dict):
+        """
+        Start a GRPC server component with the supplied config.
+        This allocates network resources (e.g. binds listening sockets).
+
+        Args:
+            config (dict): Server configuration parameters (check SLIM configuration for examples).
+
+        Returns:
+            None
+        """
+
+        await self._app.run_server(config)
+
+    async def stop_server(self, endpoint: str):
+        """
+        Stop the server component listening at the specified endpoint.
+
+        Args:
+            endpoint (str): Endpoint identifier / address previously passed to run_server.
+
+        Returns:
+            None
+        """
+
+        await self._app.stop_server(endpoint)
+
+    async def connect(self, client_config: dict) -> int:
+        """
+        Establish an outbound connection to a remote SLIM service.
+        Awaits completion until the connection is fully established and subscribed.
+
+        Args:
+            client_config (dict): Dial parameters; must include 'endpoint'.
+
+        Returns:
+            int: Numeric connection identifier assigned by the service.
+        """
+
+        conn_id = await self._app.connect(client_config)
+
+        # Save the connection ID
+        self.conn_ids[client_config["endpoint"]] = conn_id
+
+        # For the moment we manage one connection only
+        self.conn_id = conn_id
+
+        # Subscribe to the local name
+        await self._app.subscribe(
+            self._app.name,
+            conn_id,
+        )
+
+        # return the connection ID
+        return conn_id
+
+    async def disconnect(self, endpoint: str):
+        """
+        Disconnect from a previously established remote connection.
+        Awaits completion; underlying resources are released before return.
+
+        Args:
+            endpoint (str): The endpoint string used when connect() was invoked.
+
+        Returns:
+            None
+
+        """
+        conn = self.conn_ids[endpoint]
+        await self._app.disconnect(conn)
+
+    async def set_route(
+        self,
+        name: Name,
+    ):
+        """
+        Add (or update) an explicit routing rule for outbound messages.
+
+        Args:
+            name (Name): Destination app/channel name to route traffic toward.
+
+        Returns:
+            None
+        """
+
+        if self.conn_id is None:
+            raise RuntimeError("No active connection. Please connect first.")
+
+        await self._app.set_route(
+            name,
+            self.conn_id,
+        )
+
+    async def remove_route(
+        self,
+        name: Name,
+    ):
+        """
+        Remove a previously established outbound routing rule.
+
+        Args:
+            name (Name): Destination app/channel whose route should be removed.
+
+        Returns:
+            None
+        """
+
+        if self.conn_id is None:
+            raise RuntimeError("No active connection. Please connect first.")
+
+        await self._app.remove_route(
+            name,
+            self.conn_id,
+        )
+
+    async def subscribe(self, name: Name):
+        """
+        Subscribe to inbound messages addressed to the specified name.
+
+        Args:
+            name (Name): App or channel name to subscribe for deliveries.
+
+        Returns:
+            None
+        """
+
+        await self._app.subscribe(name, self.conn_id)
+
+    async def unsubscribe(self, name: Name):
+        """
+        Cancel a previous subscription for the specified name.
+
+        Args:
+            name (Name): App or channel name whose subscription is removed.
+
+        Returns:
+            None
+        """
+
+        await self._app.unsubscribe(name, self.conn_id)
+
+    async def listen_for_session(self, timeout: timedelta | None = None) -> Session:
+        """
+        Await the next inbound session (optionally bounded by timeout).
+
+        Returns:
+            Session: Wrapper for the accepted session context.
+        """
+
+        ctx: SessionContext = await self._app.listen_for_session(timeout)
+        return Session(ctx)

slim_bindings/version.py

@@ -0,0 +1,38 @@
+# Copyright AGNTCY Contributors (https://github.com/agntcy)
+# SPDX-License-Identifier: Apache-2.0
+
+from slim_bindings._slim_bindings import (  # type: ignore[attr-defined]
+    __version__,
+    build_info,
+    build_profile,
+)
+
+
+def get_version():
+    """
+    Get the version of the SLIM bindings.
+
+    Returns:
+        str: The version of the SLIM bindings.
+    """
+    return __version__
+
+
+def get_build_profile():
+    """
+    Get the build profile of the SLIM bindings.
+
+    Returns:
+        str: The build profile of the SLIM bindings.
+    """
+    return build_profile
+
+
+def get_build_info():
+    """
+    Get the build information of the SLIM bindings.
+
+    Returns:
+        str: The build information of the SLIM bindings.
+    """
+    return build_info