litenetlib-0952 1.0.0__py3-none-any.whl

litenetlib/core/constants.py

@@ -0,0 +1,186 @@
+"""
+LiteNetLib 网络常量和枚举 / Network constants and enumerations for LiteNetLib v0.9.5.2
+
+本模块定义了所有网络通信中使用的常量和枚举类型。
+This module defines all constants and enumeration types used in network communication.
+
+与 C# LiteNetLib v0.9.5.2 完全兼容 / Fully compatible with C# LiteNetLib v0.9.5.2.
+"""
+
+from enum import IntEnum
+from typing import List
+
+
+class PacketProperty(IntEnum):
+    """
+    数据包属性类型 / Packet property types stored in the first byte of packet header
+
+    v0.9.5.2 版本枚举值（无 ReliableMerged）
+    v0.9.5.2 enum values (no ReliableMerged)
+    """
+    UNRELIABLE = 0
+    CHANNELED = 1
+    ACK = 2
+    PING = 3
+    PONG = 4
+    CONNECT_REQUEST = 5
+    CONNECT_ACCEPT = 6
+    DISCONNECT = 7
+    UNCONNECTED_MESSAGE = 8
+    MTU_CHECK = 9
+    MTU_OK = 10
+    BROADCAST = 11
+    MERGED = 12
+    SHUTDOWN_OK = 13
+    PEER_NOT_FOUND = 14
+    INVALID_PROTOCOL = 15
+    NAT_MESSAGE = 16
+    EMPTY = 17
+    # Total is implicit (18)
+
+
+class DeliveryMethod(IntEnum):
+    """
+    数据传输方法 / Sending method type
+
+    定义数据包如何被传输到对等端。
+    Defines how packets are delivered to the peer.
+
+    传输方法说明 / Delivery method details:
+    - UNRELIABLE (不可靠): 可丢包、可重复、无序 / Can be dropped, duplicated, arrive out of order
+    - RELIABLE_UNORDERED (可靠无序): 不丢包、不重复、无序 / Won't be dropped/duplicated, can arrive out of order
+    - SEQUENCED (有序): 可丢包、不重复、有序 / Can be dropped, won't be duplicated, arrives in order
+    - RELIABLE_ORDERED (可靠有序): 不丢包、不重复、有序 / Won't be dropped/duplicated, arrives in order
+    - RELIABLE_SEQUENCED (可靠序列): 仅最后一个包可靠 / Only last packet reliable, cannot be fragmented
+
+    ⚠️ 重要 / IMPORTANT:
+    枚举值必须与 C# LiteNetLib v0.9.5.2 的 DeliveryMethod 枚举完全匹配以实现互操作性。
+    Values MUST match C# LiteNetLib v0.9.5.2 DeliveryMethod enum for interoperability.
+
+    C# 参考代码 / C# Reference (NetConstants.cs):
+        Unreliable = 4
+        ReliableUnordered = 0
+        Sequenced = 1
+        ReliableOrdered = 2
+        ReliableSequenced = 3
+    """
+    UNRELIABLE = 4
+    RELIABLE_UNORDERED = 0
+    SEQUENCED = 1
+    RELIABLE_ORDERED = 2
+    RELIABLE_SEQUENCED = 3
+
+
+class DisconnectReason(IntEnum):
+    """
+    断开连接的原因 / Reason for peer disconnection
+
+    定义对等端断开连接时的原因代码。
+    Defines the reason code when a peer disconnects.
+    """
+    CONNECTION_FAILED = 0
+    TIMEOUT = 1
+    HOST_UNREACHABLE = 2
+    NETWORK_UNREACHABLE = 3
+    REMOTE_CONNECTION_CLOSE = 4
+    DISCONNECT_PEER_CALLED = 5
+    CONNECTION_REJECTED = 6
+    INVALID_PROTOCOL = 7
+    UNKNOWN_HOST = 8
+    RECONNECT = 9
+    PEER_TO_PEER_CONNECTION = 10
+    PEER_NOT_FOUND = 11
+
+
+class UnconnectedMessageType(IntEnum):
+    """
+    无连接消息类型 / Type of unconnected message
+
+    定义未连接状态下发送的消息类型。
+    Defines the type of message sent in unconnected state.
+    """
+    BASIC_MESSAGE = 0
+    BROADCAST = 1
+
+
+class NetConstants:
+    """
+    网络常量和配置值 / Network constants and configuration values
+
+    包含所有网络通信中使用的常量配置。
+    Contains all constant configurations used in network communication.
+
+    v0.9.5.2 特定值 / v0.9.5.2 specific values:
+    - ProtocolId = 11
+    - PossibleMtu has 7 options
+    """
+
+    # 可调优参数 / Can be tuned
+    DEFAULT_WINDOW_SIZE: int = 64
+    SOCKET_BUFFER_SIZE: int = 1024 * 1024  # 1 MB
+    SOCKET_TTL: int = 255
+
+    # Packet headers
+    HEADER_SIZE: int = 1
+    CHANNELED_HEADER_SIZE: int = 4
+    FRAGMENT_HEADER_SIZE: int = 6
+    FRAGMENTED_HEADER_TOTAL_SIZE: int = CHANNELED_HEADER_SIZE + FRAGMENT_HEADER_SIZE
+
+    # Sequence numbers
+    MAX_SEQUENCE: int = 32768
+    HALF_MAX_SEQUENCE: int = MAX_SEQUENCE // 2
+
+    # Protocol
+    PROTOCOL_ID: int = 11  # v0.9.5.2 uses ProtocolId = 11
+    MAX_UDP_HEADER_SIZE: int = 68
+
+    # Possible MTU values (v0.9.5.2 has 7 options)
+    POSSIBLE_MTU: List[int] = [
+        576 - MAX_UDP_HEADER_SIZE,   # Minimal (RFC 1191)
+        1024,                        # Most games standard
+        1232 - MAX_UDP_HEADER_SIZE,  #
+        1460 - MAX_UDP_HEADER_SIZE,  # Google Cloud
+        1472 - MAX_UDP_HEADER_SIZE,  # VPN
+        1492 - MAX_UDP_HEADER_SIZE,  # Ethernet with LLC and SNAP, PPPoE (RFC 1042)
+        1500 - MAX_UDP_HEADER_SIZE,  # Ethernet II (RFC 1191)
+    ]
+
+    # Max possible single packet size
+    INITIAL_MTU: int = POSSIBLE_MTU[0]
+    MAX_PACKET_SIZE: int = POSSIBLE_MTU[-1]
+    MAX_UNRELIABLE_DATA_SIZE: int = MAX_PACKET_SIZE - HEADER_SIZE
+
+    # Peer specific
+    MAX_CONNECTION_NUMBER: int = 4
+
+    # Packet pool
+    PACKET_POOL_SIZE: int = 1000
+
+
+# Header sizes for each packet property
+# Must match C# NetPacket.cs HeaderSizes exactly for v0.9.5.2
+_HEADER_SIZES = {
+    PacketProperty.UNRELIABLE: NetConstants.HEADER_SIZE,
+    PacketProperty.CHANNELED: NetConstants.CHANNELED_HEADER_SIZE,
+    PacketProperty.ACK: NetConstants.CHANNELED_HEADER_SIZE,
+    PacketProperty.PING: NetConstants.HEADER_SIZE + 2,
+    PacketProperty.PONG: NetConstants.HEADER_SIZE + 10,
+    PacketProperty.CONNECT_REQUEST: 18,  # NetConnectRequestPacket.HeaderSize
+    PacketProperty.CONNECT_ACCEPT: 15,   # NetConnectAcceptPacket.Size
+    PacketProperty.DISCONNECT: NetConstants.HEADER_SIZE + 8,
+    PacketProperty.UNCONNECTED_MESSAGE: NetConstants.HEADER_SIZE,
+    PacketProperty.MTU_CHECK: NetConstants.HEADER_SIZE + 2,
+    PacketProperty.MTU_OK: NetConstants.HEADER_SIZE,
+    PacketProperty.BROADCAST: NetConstants.HEADER_SIZE,
+    PacketProperty.MERGED: NetConstants.HEADER_SIZE,
+    PacketProperty.SHUTDOWN_OK: NetConstants.HEADER_SIZE,
+    PacketProperty.PEER_NOT_FOUND: NetConstants.HEADER_SIZE,
+    PacketProperty.INVALID_PROTOCOL: NetConstants.HEADER_SIZE,
+    PacketProperty.NAT_MESSAGE: NetConstants.HEADER_SIZE,
+    PacketProperty.EMPTY: NetConstants.HEADER_SIZE,
+}
+
+
+def get_header_size(prop: PacketProperty) -> int:
+    """Get header size for a specific packet property."""
+    return _HEADER_SIZES.get(prop, NetConstants.HEADER_SIZE)

litenetlib/core/events.py

@@ -0,0 +1,336 @@
+"""
+Event system for LiteNetLib.
+
+Defines event listeners and related types for handling network events.
+"""
+
+from typing import Optional, Callable, Any
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from litenetlib.core.constants import DisconnectReason, UnconnectedMessageType, DeliveryMethod
+from litenetlib.utils.data_reader import NetDataReader
+
+
+@dataclass
+class DisconnectInfo:
+    """
+    Additional information about disconnection.
+
+    Attributes:
+        reason: The reason for disconnection
+        socket_error: Socket error code (if applicable)
+        additional_data: Additional data received with disconnect (only for RemoteConnectionClose)
+    """
+    reason: DisconnectReason
+    socket_error: Optional[int] = None
+    additional_data: Optional[NetDataReader] = None
+
+    def __repr__(self) -> str:
+        return f"DisconnectInfo(reason={self.reason.name}, socket_error={self.socket_error})"
+
+
+class INetEventListener(ABC):
+    """
+    Interface for implementing network event listener.
+
+    Implement this interface to handle network events.
+    This is more efficient than using EventBasedNetListener.
+    """
+
+    @abstractmethod
+    def on_peer_connected(self, peer) -> None:
+        """
+        Called when a new peer connects.
+
+        Args:
+            peer: The connected peer object
+        """
+        pass
+
+    @abstractmethod
+    def on_peer_disconnected(self, peer, disconnect_info: DisconnectInfo) -> None:
+        """
+        Called when a peer disconnects.
+
+        Args:
+            peer: The disconnected peer
+            disconnect_info: Additional information about the disconnection
+        """
+        pass
+
+    def on_network_error(self, address: Optional[tuple], socket_error: int) -> None:
+        """
+        Called when a network error occurs.
+
+        Args:
+            address: Remote address (can be None)
+            socket_error: Socket error code
+        """
+        pass
+
+    @abstractmethod
+    def on_network_receive(
+        self,
+        peer,
+        reader: NetDataReader,
+        channel_number: int,
+        delivery_method: DeliveryMethod
+    ) -> None:
+        """
+        Called when data is received from a peer.
+
+        Args:
+            peer: The peer that sent the data
+            reader: Data reader containing received data
+            channel_number: Channel number the data was received on
+            delivery_method: Delivery method of the received packet
+        """
+        pass
+
+    def on_network_receive_unconnected(
+        self,
+        remote_address: tuple,
+        reader: NetDataReader,
+        message_type: UnconnectedMessageType
+    ) -> None:
+        """
+        Called when an unconnected message is received.
+
+        Args:
+            remote_address: Remote endpoint (host, port)
+            reader: Data reader containing message data
+            message_type: Type of unconnected message
+        """
+        pass
+
+    def on_network_latency_update(self, peer, latency: int) -> None:
+        """
+        Called when latency information is updated.
+
+        Args:
+            peer: The peer with updated latency
+            latency: Latency value in milliseconds
+        """
+        pass
+
+    @abstractmethod
+    def on_connection_request(self, request) -> None:
+        """
+        Called when a connection request is received.
+
+        Args:
+            request: Connection request information
+        """
+        pass
+
+    def on_message_delivered(self, peer, user_data: Any) -> None:
+        """
+        Called when a reliable message is delivered.
+
+        Args:
+            peer: The peer the message was delivered to
+            user_data: User data attached to the message
+        """
+        pass
+
+    def on_peer_address_changed(self, peer, previous_address: tuple) -> None:
+        """
+        Called when a peer's address changes.
+
+        Args:
+            peer: The peer with new address
+            previous_address: The previous address
+        """
+        pass
+
+
+class EventBasedNetListener(INetEventListener):
+    """
+    Event-based listener using Python callbacks.
+
+    Simpler to use than implementing INetEventListener directly,
+    but slightly less efficient due to callback overhead.
+    """
+
+    def __init__(self):
+        self._peer_connected_callback: Optional[Callable] = None
+        self._peer_disconnected_callback: Optional[Callable] = None
+        self._network_error_callback: Optional[Callable] = None
+        self._network_receive_callback: Optional[Callable] = None
+        self._network_receive_unconnected_callback: Optional[Callable] = None
+        self._network_latency_update_callback: Optional[Callable] = None
+        self._connection_request_callback: Optional[Callable] = None
+        self._message_delivered_callback: Optional[Callable] = None
+        self._peer_address_changed_callback: Optional[Callable] = None
+
+    # Callback setters
+
+    def set_peer_connected_callback(self, callback: Callable) -> 'EventBasedNetListener':
+        """Set callback for peer connected event."""
+        self._peer_connected_callback = callback
+        return self
+
+    def set_peer_disconnected_callback(self, callback: Callable) -> 'EventBasedNetListener':
+        """Set callback for peer disconnected event."""
+        self._peer_disconnected_callback = callback
+        return self
+
+    def set_network_error_callback(self, callback: Callable) -> 'EventBasedNetListener':
+        """Set callback for network error event."""
+        self._network_error_callback = callback
+        return self
+
+    def set_network_receive_callback(self, callback: Callable) -> 'EventBasedNetListener':
+        """Set callback for data received event."""
+        self._network_receive_callback = callback
+        return self
+
+    def set_network_receive_unconnected_callback(self, callback: Callable) -> 'EventBasedNetListener':
+        """Set callback for unconnected message received event."""
+        self._network_receive_unconnected_callback = callback
+        return self
+
+    def set_network_latency_update_callback(self, callback: Callable) -> 'EventBasedNetListener':
+        """Set callback for latency update event."""
+        self._network_latency_update_callback = callback
+        return self
+
+    def set_connection_request_callback(self, callback: Callable) -> 'EventBasedNetListener':
+        """Set callback for connection request event."""
+        self._connection_request_callback = callback
+        return self
+
+    def set_message_delivered_callback(self, callback: Callable) -> 'EventBasedNetListener':
+        """Set callback for message delivered event."""
+        self._message_delivered_callback = callback
+        return self
+
+    def set_peer_address_changed_callback(self, callback: Callable) -> 'EventBasedNetListener':
+        """Set callback for peer address changed event."""
+        self._peer_address_changed_callback = callback
+        return self
+
+    # Clear callbacks
+
+    def clear_all_callbacks(self) -> None:
+        """Clear all registered callbacks."""
+        self._peer_connected_callback = None
+        self._peer_disconnected_callback = None
+        self._network_error_callback = None
+        self._network_receive_callback = None
+        self._network_receive_unconnected_callback = None
+        self._network_latency_update_callback = None
+        self._connection_request_callback = None
+        self._message_delivered_callback = None
+        self._peer_address_changed_callback = None
+
+    # INetEventListener implementation
+
+    def on_peer_connected(self, peer) -> None:
+        if self._peer_connected_callback:
+            self._peer_connected_callback(peer)
+
+    def on_peer_disconnected(self, peer, disconnect_info: DisconnectInfo) -> None:
+        if self._peer_disconnected_callback:
+            self._peer_disconnected_callback(peer, disconnect_info)
+
+    def on_network_error(self, address: Optional[tuple], socket_error: int) -> None:
+        if self._network_error_callback:
+            self._network_error_callback(address, socket_error)
+
+    def on_network_receive(
+        self,
+        peer,
+        reader: NetDataReader,
+        channel_number: int,
+        delivery_method: DeliveryMethod
+    ) -> None:
+        if self._network_receive_callback:
+            self._network_receive_callback(peer, reader, channel_number, delivery_method)
+
+    def on_network_receive_unconnected(
+        self,
+        remote_address: tuple,
+        reader: NetDataReader,
+        message_type: UnconnectedMessageType
+    ) -> None:
+        if self._network_receive_unconnected_callback:
+            self._network_receive_unconnected_callback(remote_address, reader, message_type)
+
+    def on_network_latency_update(self, peer, latency: int) -> None:
+        if self._network_latency_update_callback:
+            self._network_latency_update_callback(peer, latency)
+
+    def on_connection_request(self, request) -> None:
+        if self._connection_request_callback:
+            self._connection_request_callback(request)
+
+    def on_message_delivered(self, peer, user_data: Any) -> None:
+        if self._message_delivered_callback:
+            self._message_delivered_callback(peer, user_data)
+
+    def on_peer_address_changed(self, peer, previous_address: tuple) -> None:
+        if self._peer_address_changed_callback:
+            self._peer_address_changed_callback(peer, previous_address)
+
+
+class ConnectionRequest:
+    """
+    Represents an incoming connection request.
+
+    Provides methods to accept or reject the connection.
+    """
+
+    def __init__(self, remote_address: tuple, data: Optional[bytes] = None):
+        """
+        Create a new connection request.
+
+        Args:
+            remote_address: Remote endpoint (host, port)
+            data: Additional data sent with request
+        """
+        self._remote_address = remote_address
+        self._data = data
+        self._accepted = False
+        self._rejected = False
+
+    @property
+    def remote_address(self) -> tuple:
+        """Get remote endpoint address."""
+        return self._remote_address
+
+    @property
+    def data(self) -> Optional[bytes]:
+        """Get additional request data."""
+        return self._data
+
+    def accept(self) -> None:
+        """Accept the connection request."""
+        if self._rejected:
+            raise RuntimeError("Cannot accept: request already rejected")
+        self._accepted = True
+
+    def reject(self, reject_data: Optional[bytes] = None) -> None:
+        """
+        Reject the connection request.
+
+        Args:
+            reject_data: Optional data to send with rejection
+        """
+        if self._accepted:
+            raise RuntimeError("Cannot reject: request already accepted")
+        self._rejected = True
+        self._reject_data = reject_data
+
+    @property
+    def is_accepted(self) -> bool:
+        """Check if request was accepted."""
+        return self._accepted
+
+    @property
+    def is_rejected(self) -> bool:
+        """Check if request was rejected."""
+        return self._rejected
+
+    def __repr__(self) -> str:
+        return f"ConnectionRequest(address={self._remote_address})"