aionetx 0.1.0__py3-none-any.whl

aionetx/__init__.py

@@ -0,0 +1,65 @@
+"""
+aionetx — asyncio-first transport library for TCP and UDP networking.
+
+This package exposes a curated, stable public API via :data:`PUBLIC_API`.
+The recommended entry point for application code is
+:class:`AsyncioNetworkFactory`, which produces managed TCP/UDP transports
+driven by dataclass-based settings (``TcpClientSettings``, ``TcpServerSettings``,
+``UdpReceiverSettings``, ``UdpSenderSettings``, ``MulticastReceiverSettings``).
+
+Advanced event-handler composition helpers live alongside the factory
+(``BaseNetworkEventHandler``, ``NetworkEvent``, ``BytesReceivedEvent``).
+Transport-protocol interfaces, concrete event subclasses, and additional
+errors are available from :mod:`aionetx.api` for users who need the full
+curated surface. Anything under :mod:`aionetx.implementations` is internal.
+"""
+
+from importlib.metadata import version as _metadata_version
+
+try:
+    __version__: str = _metadata_version("aionetx")
+except Exception:  # pragma: no cover — package not installed in editable mode rarely
+    __version__ = "0.0.0.dev0"
+
+from aionetx.api import (
+    BaseNetworkEventHandler,
+    BytesReceivedEvent,
+    ComponentLifecycleState,
+    EventDeliverySettings,
+    HeartbeatConfigurationError,
+    HeartbeatProviderProtocol,
+    MulticastReceiverSettings,
+    NetworkEvent,
+    TcpHeartbeatSettings,
+    TcpReconnectSettings,
+    TcpClientSettings,
+    TcpServerSettings,
+    UdpReceiverSettings,
+    UdpSenderSettings,
+)
+from aionetx.factories import AsyncioNetworkFactory
+
+# Public API governance:
+# - `__all__` is the canonical curated export list for this module.
+# - `PUBLIC_API` is derived from `__all__` for downstream introspection/testing.
+# - `aionetx.implementations.*` remains internal/advanced and may change.
+__all__ = (
+    "__version__",
+    "AsyncioNetworkFactory",
+    "BaseNetworkEventHandler",
+    "BytesReceivedEvent",
+    "ComponentLifecycleState",
+    "EventDeliverySettings",
+    "HeartbeatConfigurationError",
+    "HeartbeatProviderProtocol",
+    "TcpHeartbeatSettings",
+    "MulticastReceiverSettings",
+    "NetworkEvent",
+    "TcpReconnectSettings",
+    "TcpClientSettings",
+    "TcpServerSettings",
+    "UdpReceiverSettings",
+    "UdpSenderSettings",
+)
+
+PUBLIC_API = tuple(__all__)

aionetx/api/__init__.py

@@ -0,0 +1,137 @@
+"""
+Curated advanced API surface for ``aionetx``.
+
+This package groups public event types, lifecycle models, protocols, settings,
+and selected exceptions for users who want more control than the package-root
+imports provide.
+"""
+
+from aionetx.api.events import (
+    BaseNetworkEventHandler,
+    BytesReceivedEvent,
+    ComponentLifecycleChangedEvent,
+    ConnectionClosedEvent,
+    ConnectionOpenedEvent,
+    ConnectionRejectedEvent,
+    HandlerFailurePolicyStopEvent,
+    NetworkErrorEvent,
+    NetworkEvent,
+    ReconnectAttemptFailedEvent,
+    ReconnectAttemptStartedEvent,
+    ReconnectScheduledEvent,
+)
+from aionetx.api.lifecycle import (
+    ComponentLifecycleState,
+    ConnectionMetadata,
+    ConnectionRole,
+    ConnectionState,
+)
+from aionetx.api.diagnostics import DispatcherRuntimeStats
+from aionetx.api.errors import (
+    ConnectionClosedError,
+    HeartbeatConfigurationError,
+    InvalidNetworkConfigurationError,
+    NetworkConfigurationError,
+    NetworkLayerError,
+    NetworkRuntimeError,
+)
+from aionetx.api.heartbeat import HeartbeatRequest, HeartbeatResult, TcpHeartbeatSettings
+from aionetx.api.network_event_handler_protocol import NetworkEventHandlerProtocol
+from aionetx.api.policies import (
+    ErrorPolicy,
+    EventBackpressurePolicy,
+    EventDeliverySettings,
+    EventDispatchMode,
+    EventHandlerFailurePolicy,
+    ReconnectJitter,
+)
+from aionetx.api.protocols import (
+    ByteSenderProtocol,
+    BytesLike,
+    ConnectionProtocol,
+    HeartbeatProviderProtocol,
+    ManagedTransportProtocol,
+    MulticastReceiverProtocol,
+    NetworkFactory,
+    TcpClientProtocol,
+    TcpServerProtocol,
+    UdpReceiverProtocol,
+    UdpSenderProtocol,
+)
+from aionetx.api.settings import (
+    MulticastReceiverSettings,
+    TcpClientSettings,
+    TcpReconnectSettings,
+    TcpServerSettings,
+    UdpReceiverSettings,
+    UdpSenderSettings,
+)
+from aionetx.api.udp import (
+    UdpInvalidTargetError,
+    UdpSenderStoppedError,
+)
+from aionetx.api.typed_event_router import TypedEventRouter
+
+# Public API governance:
+# - ``__all__`` is the canonical curated export list for this module.
+# - ``PUBLIC_API`` mirrors that list for tests and introspection helpers.
+# - Underscore-prefixed modules remain internal unless explicitly promoted here.
+# - Any type reachable from a public signature should be importable from this
+#   curated API surface so callers do not need to reach into internal modules.
+__all__ = (
+    "BaseNetworkEventHandler",
+    "ByteSenderProtocol",
+    "BytesLike",
+    "BytesReceivedEvent",
+    "ComponentLifecycleChangedEvent",
+    "ComponentLifecycleState",
+    "ConnectionClosedError",
+    "ConnectionClosedEvent",
+    "ConnectionMetadata",
+    "ConnectionOpenedEvent",
+    "ConnectionRejectedEvent",
+    "ConnectionProtocol",
+    "ConnectionRole",
+    "ConnectionState",
+    "DispatcherRuntimeStats",
+    "ErrorPolicy",
+    "EventBackpressurePolicy",
+    "EventDeliverySettings",
+    "EventDispatchMode",
+    "EventHandlerFailurePolicy",
+    "HandlerFailurePolicyStopEvent",
+    "HeartbeatConfigurationError",
+    "HeartbeatProviderProtocol",
+    "HeartbeatRequest",
+    "HeartbeatResult",
+    "TcpHeartbeatSettings",
+    "InvalidNetworkConfigurationError",
+    "ManagedTransportProtocol",
+    "MulticastReceiverProtocol",
+    "MulticastReceiverSettings",
+    "NetworkConfigurationError",
+    "NetworkFactory",
+    "NetworkErrorEvent",
+    "NetworkEvent",
+    "NetworkEventHandlerProtocol",
+    "NetworkLayerError",
+    "NetworkRuntimeError",
+    "ReconnectAttemptFailedEvent",
+    "ReconnectAttemptStartedEvent",
+    "ReconnectJitter",
+    "ReconnectScheduledEvent",
+    "TcpReconnectSettings",
+    "TcpClientProtocol",
+    "TcpClientSettings",
+    "TcpServerProtocol",
+    "TcpServerSettings",
+    "TypedEventRouter",
+    "UdpInvalidTargetError",
+    "UdpReceiverProtocol",
+    "UdpReceiverSettings",
+    "UdpSenderProtocol",
+    "UdpSenderSettings",
+    "UdpSenderStoppedError",
+)
+
+PUBLIC_API = tuple(__all__)

aionetx/api/_event_registry.py

@@ -0,0 +1,182 @@
+"""
+Internal taxonomy registry for all emitted network event types.
+
+The registry in this module is the single source of truth for the open
+``NetworkEvent`` union, typed hook names, and recording bucket names used by
+testing helpers.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from collections.abc import Awaitable, Callable
+from typing import Any, TypeAlias, get_args
+
+from aionetx.api.bytes_received_event import BytesReceivedEvent
+from aionetx.api.component_lifecycle_changed_event import ComponentLifecycleChangedEvent
+from aionetx.api.connection_events import (
+    ConnectionClosedEvent,
+    ConnectionOpenedEvent,
+    ConnectionRejectedEvent,
+)
+from aionetx.api.handler_failure_policy_stop_event import HandlerFailurePolicyStopEvent
+from aionetx.api.network_error_event import NetworkErrorEvent
+from aionetx.api.reconnect_events import (
+    ReconnectAttemptFailedEvent,
+    ReconnectAttemptStartedEvent,
+    ReconnectScheduledEvent,
+)
+
+NetworkEvent: TypeAlias = (
+    ConnectionOpenedEvent
+    | ConnectionRejectedEvent
+    | ConnectionClosedEvent
+    | BytesReceivedEvent
+    | NetworkErrorEvent
+    | HandlerFailurePolicyStopEvent
+    | ComponentLifecycleChangedEvent
+    | ReconnectAttemptStartedEvent
+    | ReconnectAttemptFailedEvent
+    | ReconnectScheduledEvent
+)
+EventType: TypeAlias = type[NetworkEvent]
+EventHandlerMethod: TypeAlias = Callable[[Any], Awaitable[None]]
+
+
+@dataclass(frozen=True)
+class EventRegistryEntry:
+    """Canonical taxonomy entry for one network event type."""
+
+    event_type: EventType
+    handler_method_name: str
+    recording_bucket_name: str
+
+
+NETWORK_EVENT_REGISTRY: tuple[EventRegistryEntry, ...] = (
+    EventRegistryEntry(
+        event_type=ConnectionOpenedEvent,
+        handler_method_name="on_connection_opened",
+        recording_bucket_name="opened_events",
+    ),
+    EventRegistryEntry(
+        event_type=ConnectionRejectedEvent,
+        handler_method_name="on_connection_rejected",
+        recording_bucket_name="rejected_events",
+    ),
+    EventRegistryEntry(
+        event_type=ConnectionClosedEvent,
+        handler_method_name="on_connection_closed",
+        recording_bucket_name="closed_events",
+    ),
+    EventRegistryEntry(
+        event_type=BytesReceivedEvent,
+        handler_method_name="on_bytes_received",
+        recording_bucket_name="received_events",
+    ),
+    EventRegistryEntry(
+        event_type=NetworkErrorEvent,
+        handler_method_name="on_error",
+        recording_bucket_name="error_events",
+    ),
+    EventRegistryEntry(
+        event_type=HandlerFailurePolicyStopEvent,
+        handler_method_name="on_handler_failure_policy_stop",
+        recording_bucket_name="handler_failure_policy_stop_events",
+    ),
+    EventRegistryEntry(
+        event_type=ComponentLifecycleChangedEvent,
+        handler_method_name="on_component_lifecycle_changed",
+        recording_bucket_name="lifecycle_events",
+    ),
+    EventRegistryEntry(
+        event_type=ReconnectAttemptStartedEvent,
+        handler_method_name="on_reconnect_attempt_started",
+        recording_bucket_name="reconnect_attempt_started_events",
+    ),
+    EventRegistryEntry(
+        event_type=ReconnectAttemptFailedEvent,
+        handler_method_name="on_reconnect_attempt_failed",
+        recording_bucket_name="reconnect_attempt_failed_events",
+    ),
+    EventRegistryEntry(
+        event_type=ReconnectScheduledEvent,
+        handler_method_name="on_reconnect_scheduled",
+        recording_bucket_name="reconnect_scheduled_events",
+    ),
+)
+
+# Keep ``NETWORK_EVENT_REGISTRY`` as the taxonomy source of truth. Conformance
+# checks below ensure that the open ``NetworkEvent`` union, typed event hooks,
+# and testing collectors stay aligned with the same event set.
+
+NETWORK_EVENT_TYPES: tuple[EventType, ...] = tuple(
+    entry.event_type for entry in NETWORK_EVENT_REGISTRY
+)
+NETWORK_EVENT_HANDLER_METHODS: dict[EventType, str] = {
+    entry.event_type: entry.handler_method_name for entry in NETWORK_EVENT_REGISTRY
+}
+NETWORK_EVENT_RECORDING_BUCKETS: dict[EventType, str] = {
+    entry.event_type: entry.recording_bucket_name for entry in NETWORK_EVENT_REGISTRY
+}
+
+
+def validate_network_event_registry_conformance(
+    network_event_union: object,
+    registry: tuple[EventRegistryEntry, ...],
+) -> None:
+    """
+    Validate that the event union and taxonomy registry describe the same types.
+
+    Args:
+        network_event_union: Union object representing the public event taxonomy.
+        registry: Registry entries that define hook names and recording buckets.
+
+    Raises:
+        RuntimeError: If the union and registry have drifted apart.
+    """
+    union_event_types = tuple(get_args(network_event_union))
+    registry_event_types = tuple(entry.event_type for entry in registry)
+
+    missing_from_registry = [
+        event_type.__name__
+        for event_type in union_event_types
+        if event_type not in registry_event_types
+    ]
+    extra_in_registry = [
+        event_type.__name__
+        for event_type in registry_event_types
+        if event_type not in union_event_types
+    ]
+
+    if not missing_from_registry and not extra_in_registry:
+        return
+
+    message_parts: list[str] = [
+        "Network event registry drift detected.",
+        "Update `NetworkEvent` and `NETWORK_EVENT_REGISTRY` together.",
+    ]
+    if missing_from_registry:
+        message_parts.append(
+            f"Missing registry entries for: {', '.join(sorted(missing_from_registry))}."
+        )
+    if extra_in_registry:
+        message_parts.append(
+            f"Registry contains events missing from the union: {', '.join(sorted(extra_in_registry))}."
+        )
+
+    raise RuntimeError(" ".join(message_parts))
+
+
+validate_network_event_registry_conformance(NetworkEvent, NETWORK_EVENT_REGISTRY)
+
+__all__ = (
+    "EventHandlerMethod",
+    "EventRegistryEntry",
+    "EventType",
+    "NETWORK_EVENT_HANDLER_METHODS",
+    "NETWORK_EVENT_RECORDING_BUCKETS",
+    "NETWORK_EVENT_REGISTRY",
+    "NETWORK_EVENT_TYPES",
+    "NetworkEvent",
+    "validate_network_event_registry_conformance",
+)

aionetx/api/_validation.py

@@ -0,0 +1,104 @@
+"""Internal validation helpers for public settings dataclasses."""
+
+from __future__ import annotations
+
+import math
+from enum import Enum
+from numbers import Real
+from typing import TypeVar
+
+from aionetx.api.errors import InvalidNetworkConfigurationError
+
+_TEnum = TypeVar("_TEnum", bound=Enum)
+_ErrorType = type[Exception]
+
+
+def require_bool(
+    *, field_name: str, value: object, error_type: _ErrorType = InvalidNetworkConfigurationError
+) -> bool:
+    if type(value) is not bool:
+        raise error_type(f"{field_name} must be a bool.")
+    return value
+
+
+def require_non_empty_str(
+    *, field_name: str, value: object, error_type: _ErrorType = InvalidNetworkConfigurationError
+) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise error_type(f"{field_name} must not be empty or whitespace-only.")
+    return value
+
+
+def require_optional_non_empty_str(
+    *, field_name: str, value: object, error_type: _ErrorType = InvalidNetworkConfigurationError
+) -> str | None:
+    if value is None:
+        return None
+    return require_non_empty_str(field_name=field_name, value=value, error_type=error_type)
+
+
+def require_int_range(
+    *,
+    field_name: str,
+    value: object,
+    min_value: int,
+    max_value: int,
+    error_type: _ErrorType = InvalidNetworkConfigurationError,
+) -> int:
+    if type(value) is not int or not (min_value <= value <= max_value):
+        raise error_type(f"{field_name} must be between {min_value} and {max_value}.")
+    return value
+
+
+def require_positive_int(
+    *, field_name: str, value: object, error_type: _ErrorType = InvalidNetworkConfigurationError
+) -> int:
+    if type(value) is not int or value <= 0:
+        raise error_type(f"{field_name} must be > 0.")
+    return value
+
+
+def require_positive_finite_number(
+    *, field_name: str, value: object, error_type: _ErrorType = InvalidNetworkConfigurationError
+) -> float:
+    if isinstance(value, bool) or not isinstance(value, Real):
+        raise error_type(f"{field_name} must be a finite number > 0.")
+    number = float(value)
+    if not math.isfinite(number) or number <= 0:
+        raise error_type(f"{field_name} must be a finite number > 0.")
+    return number
+
+
+def require_optional_positive_finite_number(
+    *, field_name: str, value: object, error_type: _ErrorType = InvalidNetworkConfigurationError
+) -> float | None:
+    if value is None:
+        return None
+    return require_positive_finite_number(field_name=field_name, value=value, error_type=error_type)
+
+
+def require_finite_number_at_least(
+    *,
+    field_name: str,
+    value: object,
+    minimum: float,
+    error_type: _ErrorType = InvalidNetworkConfigurationError,
+) -> float:
+    if isinstance(value, bool) or not isinstance(value, Real):
+        raise error_type(f"{field_name} must be a finite number >= {minimum}.")
+    number = float(value)
+    if not math.isfinite(number) or number < minimum:
+        raise error_type(f"{field_name} must be a finite number >= {minimum}.")
+    return number
+
+
+def require_enum_member(
+    *,
+    field_name: str,
+    value: object,
+    enum_type: type[_TEnum],
+    error_type: _ErrorType = InvalidNetworkConfigurationError,
+) -> _TEnum:
+    if not isinstance(value, enum_type):
+        raise error_type(f"{field_name} must be a {enum_type.__name__} value.")
+    return value

aionetx/api/base_network_event_handler.py

@@ -0,0 +1,113 @@
+"""
+Typed hook dispatch helpers for unified network event handling.
+
+This module exposes :class:`BaseNetworkEventHandler`, a convenience base class
+that keeps the single ``on_event(event)`` callback contract while letting
+applications override per-event async hooks instead of writing their own
+``isinstance`` dispatch ladder.
+"""
+
+from __future__ import annotations
+
+from typing import cast
+
+from aionetx.api.bytes_received_event import BytesReceivedEvent
+from aionetx.api.component_lifecycle_changed_event import ComponentLifecycleChangedEvent
+from aionetx.api.connection_events import (
+    ConnectionClosedEvent,
+    ConnectionOpenedEvent,
+    ConnectionRejectedEvent,
+)
+from aionetx.api.network_error_event import NetworkErrorEvent
+from aionetx.api.handler_failure_policy_stop_event import HandlerFailurePolicyStopEvent
+from aionetx.api._event_registry import EventHandlerMethod, NETWORK_EVENT_HANDLER_METHODS
+from aionetx.api.network_event import NetworkEvent
+from aionetx.api.network_event_handler_protocol import NetworkEventHandlerProtocol
+from aionetx.api.reconnect_events import (
+    ReconnectAttemptFailedEvent,
+    ReconnectAttemptStartedEvent,
+    ReconnectScheduledEvent,
+)
+
+
+class BaseNetworkEventHandler(NetworkEventHandlerProtocol):
+    """
+    Convenience base class with typed no-op hooks.
+
+    `NetworkEventHandlerProtocol` stays unified as `on_event(event)`.
+    This class keeps that contract but provides optional typed hooks so users can
+    implement readable per-event handlers without writing isinstance chains.
+    """
+
+    async def on_event(self, event: NetworkEvent) -> None:
+        """
+        Route one network event to the matching typed hook.
+
+        Args:
+            event: Event instance emitted by a transport or component.
+        """
+        for event_type, handler_name in NETWORK_EVENT_HANDLER_METHODS.items():
+            if isinstance(event, event_type):
+                handler = cast(EventHandlerMethod, getattr(self, handler_name))
+                await handler(event)
+                break
+        return None
+
+    async def on_connection_opened(self, event: ConnectionOpenedEvent) -> None:
+        """Handle ``ConnectionOpenedEvent`` with a default no-op implementation."""
+        del event
+        return None
+
+    async def on_connection_closed(self, event: ConnectionClosedEvent) -> None:
+        """Handle ``ConnectionClosedEvent`` with a default no-op implementation."""
+        del event
+        return None
+
+    async def on_connection_rejected(self, event: ConnectionRejectedEvent) -> None:
+        """Handle ``ConnectionRejectedEvent`` with a default no-op implementation."""
+        del event
+        return None
+
+    async def on_bytes_received(self, event: BytesReceivedEvent) -> None:
+        """Handle ``BytesReceivedEvent`` with a default no-op implementation."""
+        del event
+        return None
+
+    async def on_error(self, event: NetworkErrorEvent) -> None:
+        """Handle ``NetworkErrorEvent`` with a default no-op implementation."""
+        del event
+        return None
+
+    async def on_handler_failure_policy_stop(self, event: HandlerFailurePolicyStopEvent) -> None:
+        """Handle ``HandlerFailurePolicyStopEvent`` with a default no-op implementation."""
+        del event
+        return None
+
+    async def on_component_lifecycle_changed(
+        self,
+        event: ComponentLifecycleChangedEvent,
+    ) -> None:
+        """Handle ``ComponentLifecycleChangedEvent`` with a default no-op implementation."""
+        del event
+        return None
+
+    async def on_reconnect_attempt_started(
+        self,
+        event: ReconnectAttemptStartedEvent,
+    ) -> None:
+        """Handle ``ReconnectAttemptStartedEvent`` with a default no-op implementation."""
+        del event
+        return None
+
+    async def on_reconnect_attempt_failed(
+        self,
+        event: ReconnectAttemptFailedEvent,
+    ) -> None:
+        """Handle ``ReconnectAttemptFailedEvent`` with a default no-op implementation."""
+        del event
+        return None
+
+    async def on_reconnect_scheduled(self, event: ReconnectScheduledEvent) -> None:
+        """Handle ``ReconnectScheduledEvent`` with a default no-op implementation."""
+        del event
+        return None

aionetx/api/byte_sender_protocol.py

@@ -0,0 +1,35 @@
+"""
+Shared capability protocol for bytes-like send operations.
+
+This module defines the narrowest send contract used across stream and
+datagram transports. Role-specific protocols layer lifecycle, addressing, and
+connection semantics on top of this capability.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+from aionetx.api.bytes_like import BytesLike
+
+
+class ByteSenderProtocol(Protocol):
+    """
+    Capability protocol for components that can send raw bytes-like payloads.
+
+    This capability means only: "can send bytes-like payloads". It does not
+    imply shared addressing semantics (connected stream vs datagram target),
+    shared lifecycle model, or shared connection supervision behavior.
+    Use role-specific protocols when you need transport-specific guarantees.
+    """
+
+    async def send(self, data: BytesLike) -> None:
+        """
+        Send raw bytes-like payload.
+
+        Implementations may differ in lifecycle, addressing, and transport
+        failure semantics. A successful return means the payload was accepted
+        by the local transport path; it does not guarantee remote delivery.
+        Role-specific protocols document their concrete exceptions.
+        """
+        raise NotImplementedError

aionetx/api/bytes_like.py

@@ -0,0 +1,14 @@
+"""
+Shared bytes-like payload alias used across transport APIs.
+
+``BytesLike`` intentionally matches the payload types accepted by Python's
+socket and stream APIs: ``bytes``, ``bytearray``, and ``memoryview``.
+"""
+
+from __future__ import annotations
+
+from typing import TypeAlias
+
+BytesLike: TypeAlias = bytes | bytearray | memoryview
+
+__all__ = ("BytesLike",)

aionetx/api/bytes_received_event.py

@@ -0,0 +1,30 @@
+"""
+Event type for raw transport payload delivery.
+
+The dataclass in this module is emitted by stream, UDP, and multicast receivers
+whenever bytes are read from the underlying transport.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class BytesReceivedEvent:
+    """
+    Event emitted when raw bytes are read from a transport.
+
+    Attributes:
+        resource_id: Identifier of the transport/source stream.
+        data: Raw transport payload bytes with no framing/parsing.
+        remote_host: Optional remote sender host metadata (typically present for
+            UDP/multicast datagrams, may be None for stream transports).
+        remote_port: Optional remote sender port metadata (typically present for
+            UDP/multicast datagrams, may be None for stream transports).
+    """
+
+    resource_id: str
+    data: bytes
+    remote_host: str | None = None
+    remote_port: int | None = None