mail-swarms 1.3.2__py3-none-any.whl

mail/net/server_utils.py

@@ -0,0 +1,114 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2025 Addison Kline
+
+import asyncio
+import logging
+
+from mail.api import MAILSwarm, MAILSwarmTemplate
+from mail.config import ServerConfig
+from mail.net.registry import SwarmRegistry
+
+logger = logging.getLogger(__name__)
+
+
+def compute_external_base_url(cfg: ServerConfig) -> str:
+    """
+    Derive an externally-reachable base URL from the server config.
+    """
+
+    host = cfg.host
+    port = cfg.port
+
+    if host in {"0.0.0.0", "::"}:
+        # 0.0.0.0/:: listen on all interfaces; default to localhost for callbacks
+        host_for_url = "localhost"
+    else:
+        host_for_url = host
+
+    return f"http://{host_for_url}:{port}"
+
+
+def get_default_persistent_swarm(
+    cfg: ServerConfig,
+) -> MAILSwarmTemplate:
+    """
+    Get the default persistent swarm template from the server config.
+    """
+    swarm_name = cfg.swarm.name
+    swarm_json_file = cfg.swarm.source
+
+    return MAILSwarmTemplate.from_swarm_json_file(
+        swarm_name=swarm_name,
+        json_filepath=swarm_json_file,
+    )
+
+
+def init_mail_instances_dict() -> dict[str, MAILSwarm]:
+    """
+    Initialize the mail instances dictionary for a given role.
+    Should always be empty on startup.
+    """
+    return {}
+
+
+def init_mail_tasks_dict() -> dict[str, asyncio.Task]:
+    """
+    Initialize the mail tasks dictionary for a given role.
+    Should always be empty on startup.
+    """
+    return {}
+
+
+def get_default_swarm_registry(
+    cfg: ServerConfig, swarm: MAILSwarmTemplate
+) -> SwarmRegistry:
+    """
+    Get the default swarm registry from the server config.
+    """
+    swarm_name = swarm.name
+    swarm_registry_file = cfg.swarm.registry_file
+    local_base_url = get_default_base_url(cfg)
+
+    return SwarmRegistry(
+        local_swarm_name=swarm_name,
+        local_base_url=local_base_url,
+        persistence_file=swarm_registry_file,
+        local_swarm_description=swarm.description,
+        local_swarm_keywords=swarm.keywords,
+        local_swarm_public=swarm.public,
+    )
+
+
+def get_default_swarm_name(
+    cfg: ServerConfig,
+) -> str:
+    """
+    Get the default swarm name from the server config.
+    """
+    return cfg.swarm.name
+
+
+def get_default_base_url(
+    cfg: ServerConfig,
+) -> str:
+    """
+    Get the default base URL from the server config.
+    """
+    return compute_external_base_url(cfg)
+
+
+def get_default_entrypoint_agent(
+    swarm_template: MAILSwarmTemplate,
+) -> str:
+    """
+    Get the default entrypoint agent from the swarm template.
+    """
+    return swarm_template.entrypoint
+
+
+def init_task_bindings_dict() -> dict[str, dict[str, str]]:
+    """
+    Initialize the task bindings dictionary.
+    Should always be empty on startup.
+    """
+    return {}

mail/net/types.py

@@ -0,0 +1,247 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2025 Addison Kline
+
+import datetime
+from typing import Any, TypedDict
+
+from sse_starlette import ServerSentEvent
+
+from mail.core.message import MAILMessage
+
+
+class SwarmEndpoint(TypedDict):
+    """
+    Represents a swarm endpoint for interswarm communication.
+    """
+
+    swarm_name: str
+    """The name of the swarm."""
+    base_url: str
+    """The base URL of the swarm (e.g., https://swarm1.example.com)."""
+    version: str
+    """The version of the swarm."""
+    health_check_url: str
+    """The health check endpoint URL."""
+    auth_token_ref: str | None
+    """Authentication token reference (environment variable or actual token)."""
+    last_seen: datetime.datetime | None
+    """When this swarm was last seen/heard from."""
+    is_active: bool
+    """Whether this swarm is currently active."""
+    latency: float | None
+    """The latency of the swarm in seconds."""
+    swarm_description: str
+    """The description of the swarm."""
+    keywords: list[str]
+    """The keywords of the swarm."""
+    metadata: dict[str, Any] | None
+    """Additional metadata about the swarm."""
+    public: bool
+    """Whether this swarm is publicly accessible."""
+    volatile: bool
+    """Whether this swarm is volatile (will be removed from the registry when the server shuts down)."""
+
+
+class SwarmEndpointCleaned(TypedDict):
+    """
+    Represents a swarm endpoint for interswarm communication.
+    """
+
+    swarm_name: str
+    """The name of the swarm."""
+    base_url: str
+    """The base URL of the swarm (e.g., https://swarm1.example.com)."""
+    version: str
+    """The protocol version of the swarm."""
+    last_seen: datetime.datetime | None
+    """When this swarm was last seen/heard from."""
+    is_active: bool
+    """Whether this swarm is currently active."""
+    latency: float | None
+    """The latency of the swarm in seconds."""
+    swarm_description: str
+    """The description of the swarm."""
+    keywords: list[str]
+    """The keywords of the swarm."""
+    metadata: dict[str, Any] | None
+    """Additional metadata about the swarm."""
+
+
+class SwarmInfo(TypedDict):
+    """
+    Information about the current swarm.
+    """
+
+    name: str
+    """The name of the swarm."""
+    version: str
+    """The protocol version of the swarm."""
+    description: str
+    """The description of the swarm."""
+    entrypoint: str
+    """The default entrypoint of the swarm."""
+    keywords: list[str]
+    """The keywords of the swarm."""
+    public: bool
+    """Whether this swarm is publicly accessible."""
+
+
+class SwarmStatus(TypedDict):
+    """
+    The status of a swarm.
+    """
+
+    name: str | None
+    """The name of the swarm."""
+    status: str
+    """The status of the swarm."""
+
+
+class GetRootResponse(TypedDict):
+    """
+    Response for the MAIL server endpoint `GET /`.
+    """
+
+    name: str
+    """The name of the service; should always be `mail`."""
+    protocol_version: str
+    """The version of the MAIL protocol that is being used."""
+    swarm: SwarmInfo
+    """Information about the swarm that is running."""
+    status: str
+    """The status of the service; should always be `running`."""
+    uptime: float
+    """The uptime of the service in seconds."""
+
+
+class GetWhoamiResponse(TypedDict):
+    """
+    Response for the MAIL server endpoint `GET /whoami`.
+    """
+
+    id: str
+    """The ID of the caller."""
+    role: str
+    """The role of the caller."""
+
+
+class GetStatusResponse(TypedDict):
+    """
+    Response for the MAIL server endpoint `GET /status`.
+    """
+
+    swarm: SwarmStatus
+    """The swarm that is running."""
+    active_users: int
+    """The number of active users."""
+    user_mail_ready: bool
+    """Whether the user MAIL instance is ready."""
+    user_task_running: bool
+    """Whether the user MAIL instance task is running."""
+
+
+class PostMessageResponse(TypedDict):
+    """
+    Response for the MAIL server endpoint `POST /message`.
+    """
+
+    response: str
+    """The response from the MAIL instance."""
+    events: list[ServerSentEvent] | None
+    """The events from the MAIL instance."""
+
+
+class GetHealthResponse(TypedDict):
+    """
+    Response for the MAIL server endpoint `GET /health`.
+    """
+
+    status: str
+    """The status of the MAIL instance."""
+    swarm_name: str
+    """The name of the swarm."""
+    timestamp: str
+    """The timestamp of the response."""
+
+
+class GetSwarmsResponse(TypedDict):
+    """
+    Response for the MAIL server endpoint `GET /swarms`.
+    """
+
+    swarms: list[SwarmEndpointCleaned]
+    """The swarms that are running."""
+
+
+class PostSwarmsResponse(TypedDict):
+    """
+    Response for the MAIL server endpoint `POST /swarms`.
+    """
+
+    status: str
+    """The status of the response."""
+    swarm_name: str
+    """The name of the swarm."""
+
+
+class GetSwarmsDumpResponse(TypedDict):
+    """
+    Response for the MAIL server endpoint `GET /swarms/dump`.
+    """
+
+    status: str
+    """The status of the response."""
+    swarm_name: str
+    """The name of the swarm."""
+
+
+class PostInterswarmMessageResponse(TypedDict):
+    """
+    Response for the MAIL server endpoint `POST /interswarm/message`.
+    """
+
+    response: MAILMessage
+    """The response from the MAIL instance."""
+    events: list[ServerSentEvent] | None
+    """The events from the MAIL instance."""
+
+
+class PostInterswarmForwardResponse(TypedDict):
+    """
+    Response for the MAIL server endpoint `POST /interswarm/forward`.
+    """
+
+    swarm: str
+    """The name of the swarm."""
+    task_id: str
+    """The task ID of the interswarm message."""
+    status: str
+    """The status of the response."""
+    local_runner: str
+    """The local runner of the swarm (role:id@swarm)."""
+
+
+class PostInterswarmBackResponse(TypedDict):
+    """
+    Response for the MAIL server endpoint `POST /interswarm/back`.
+    """
+
+    swarm: str
+    """The name of the swarm."""
+    task_id: str
+    """The task ID of the interswarm message."""
+    status: str
+    """The status of the response."""
+    local_runner: str
+    """The local runner of the swarm (role:id@swarm)."""
+
+
+class PostSwarmsLoadResponse(TypedDict):
+    """
+    Response for the MAIL server endpoint `POST /swarms/load`.
+    """
+
+    status: str
+    """The status of the response."""
+    swarm_name: str
+    """The name of the swarm."""