pyPhotonRealtime 0.0.1__py3-none-any.whl

pyphotonrealtime/__init__.py

@@ -0,0 +1,30 @@
+"""Pure-Python client for games running on Photon Realtime.
+
+Layers, bottom to top:
+
+* :mod:`pyphotonrealtime.protocol`  -- wire format: parameter (de)serialization,
+  packet framing, encryption primitives.
+* :mod:`pyphotonrealtime.transport` -- byte transports (TCP now; UDP/WebSocket later).
+* :mod:`pyphotonrealtime.peer`      -- ``PhotonPeer``: one connection to one server,
+  operation/event/response queues, keep-alive, timeouts, encryption.
+* :mod:`pyphotonrealtime.realtime`  -- ``RealtimeClient``: Name Server -> Master
+  Server -> Game Server workflow, matchmaking, rooms, players, callbacks.
+"""
+
+from pyphotonrealtime.peer import PeerState, PhotonPeer
+from pyphotonrealtime.realtime import (
+    AppSettings,
+    ClientState,
+    RealtimeClient,
+)
+
+__version__ = "0.0.1"
+
+__all__ = [
+    "AppSettings",
+    "ClientState",
+    "PeerState",
+    "PhotonPeer",
+    "RealtimeClient",
+    "__version__",
+]

pyphotonrealtime/peer.py

@@ -0,0 +1,192 @@
+"""``PhotonPeer``: a single connection to a single Photon server.
+
+Mirrors the official SDKs' service loop: nothing happens on the network unless
+the application calls :meth:`PhotonPeer.service` (or the two halves,
+:meth:`PhotonPeer.dispatch_incoming_commands` and
+:meth:`PhotonPeer.send_outgoing_commands`) regularly, typically 10-50 times per
+second, from a single thread.
+
+Callbacks to the :class:`PeerListener` are only ever invoked from inside
+``dispatch_incoming_commands``, i.e. on the thread that calls ``service``.
+"""
+
+from __future__ import annotations
+
+import time
+from collections import deque
+from dataclasses import dataclass, field
+from enum import Enum, auto
+from typing import TYPE_CHECKING, Any, Protocol
+
+from pyphotonrealtime.protocol.packet.packet_stream import PhotonStreamParser
+from pyphotonrealtime.transport import TcpTransport
+
+if TYPE_CHECKING:
+    from pyphotonrealtime.protocol.packet.base import PhotonPacket
+    from pyphotonrealtime.protocol.param.base import ParameterBase
+    from pyphotonrealtime.transport import Transport
+
+type Parameters = dict[int, ParameterBase[Any]]
+
+
+class PeerState(Enum):
+    """Connection state of a :class:`PhotonPeer`."""
+
+    Disconnected = auto()
+    Connecting = auto()
+    Connected = auto()
+    Disconnecting = auto()
+
+
+class StatusCode(Enum):
+    """Peer status changes reported to :meth:`PeerListener.on_status_changed`."""
+
+    Connect = auto()
+    Disconnect = auto()
+    ExceptionOnConnect = auto()
+    Exception = auto()
+    TimeoutDisconnect = auto()
+    DisconnectByServer = auto()
+    EncryptionEstablished = auto()
+    EncryptionFailedToEstablish = auto()
+
+
+@dataclass(frozen=True, slots=True)
+class OperationResponse:
+    """The server's answer to an operation sent with ``send_operation``."""
+
+    operation_code: int
+    return_code: int
+    debug_message: str | None
+    parameters: Parameters = field(default_factory=dict)
+
+
+@dataclass(frozen=True, slots=True)
+class EventData:
+    """A server- or player-originated event."""
+
+    code: int
+    parameters: Parameters = field(default_factory=dict)
+
+
+class PeerListener(Protocol):
+    """Receives everything a peer dispatches (``IPhotonPeerListener``)."""
+
+    def on_status_changed(self, status: StatusCode) -> None:
+        """Handle a connection status change."""
+
+    def on_operation_response(self, response: OperationResponse) -> None:
+        """Handle the response to an operation."""
+
+    def on_event(self, event: EventData) -> None:
+        """Handle an incoming event."""
+
+
+class PhotonPeer:
+    """One connection to one Photon server, driven by :meth:`service`."""
+
+    def __init__(
+        self,
+        listener: PeerListener,
+        transport: Transport | None = None,
+        *,
+        disconnect_timeout: float = 10.0,
+        keep_alive_interval: float = 2.0,
+    ) -> None:
+        """Create a disconnected peer.
+
+        Args:
+            listener: Receives status changes, responses and events.
+            transport: Byte transport to use; defaults to TCP.
+            disconnect_timeout: Seconds without traffic before giving up.
+            keep_alive_interval: Seconds of idle sending before a ping.
+        """
+        self.listener = listener
+        self.transport = transport if transport is not None else TcpTransport()
+        self.disconnect_timeout = disconnect_timeout
+        self.keep_alive_interval = keep_alive_interval
+
+        self.state = PeerState.Disconnected
+        self.server_address: str | None = None
+        self.app_id: str | None = None
+
+        self._parser = PhotonStreamParser()
+        self._outgoing: deque[PhotonPacket] = deque()
+        self._incoming: deque[PhotonPacket] = deque()
+        self._aes_key: bytes | None = None
+        self._last_receive = 0.0
+        self._last_send = 0.0
+
+    # -- connection -------------------------------------------------------
+
+    def connect(self, server_address: str, app_id: str) -> bool:
+        """Start connecting to ``host:port``; the result arrives as a status.
+
+        Returns:
+            Whether the connection attempt was started.
+        """
+        # M1: send InitRequestPacket(app id, protocol version), move to
+        # Connected on InitResponse.
+        raise NotImplementedError
+
+    def disconnect(self) -> None:
+        """Send a disconnect message, then close the transport."""
+        raise NotImplementedError
+
+    def establish_encryption(self) -> bool:
+        """Start a Diffie-Hellman key exchange (``InitEncryptionRequest``).
+
+        Returns:
+            Whether the exchange was started.
+        """
+        raise NotImplementedError
+
+    @property
+    def is_encryption_available(self) -> bool:
+        """Whether a shared AES key has been negotiated."""
+        return self._aes_key is not None
+
+    # -- service loop -----------------------------------------------------
+
+    def service(self) -> None:
+        """Dispatch everything received, then send everything queued."""
+        while self.dispatch_incoming_commands():
+            pass
+        while self.send_outgoing_commands():
+            pass
+
+    def dispatch_incoming_commands(self) -> bool:
+        """Read from the transport and dispatch at most one command.
+
+        Returns:
+            Whether there may be more to dispatch.
+        """
+        # M1: map parsed packets to OperationResponse/EventData, answer
+        # keep-alives, detect timeouts (disconnect_timeout).
+        raise NotImplementedError
+
+    def send_outgoing_commands(self) -> bool:
+        """Flush queued commands to the transport.
+
+        Returns:
+            Whether more remain to be sent.
+        """
+        # M1: also emit a keep-alive when idle for keep_alive_interval.
+        raise NotImplementedError
+
+    # -- operations -------------------------------------------------------
+
+    def send_operation(
+        self, operation_code: int, parameters: Parameters, *, encrypt: bool = False
+    ) -> bool:
+        """Queue an operation; it goes out on the next ``send_outgoing_commands``.
+
+        Returns:
+            Whether the operation was queued.
+        """
+        # M1: build via PacketFactory.operation (encrypted when requested).
+        raise NotImplementedError
+
+    @staticmethod
+    def _now() -> float:
+        return time.monotonic()

pyphotonrealtime/protocol/__init__.py

@@ -0,0 +1 @@
+__all__ = []

pyphotonrealtime/protocol/command_code.py

@@ -0,0 +1,32 @@
+from enum import IntEnum
+
+
+class CommandCode(IntEnum):
+    Init = 0
+    InitResponse = 1
+
+    Operation = 2
+    OperationResponse = 3
+
+    Event = 4
+    DisconnectMessage = 5
+
+    KeyExchangeRequest = 6
+    KeyExchangeResponse = 7
+
+    Message = 8
+    RawMessage = 9
+
+    EncryptedOperation = 0x82
+    EncryptedOperationResponse = 0x83
+
+    EncryptedEvent = 0x84
+
+    Unknown = 0xFF
+
+
+ENCRYPTED_FLAG = 0x80
+
+
+def is_encrypted(command_code: CommandCode) -> bool:
+    return command_code.value > ENCRYPTED_FLAG

pyphotonrealtime/protocol/consts.py

@@ -0,0 +1,12 @@
+"""Wire-level constants of the Photon TCP protocol."""
+
+MSG_MAGIC = 0xF3
+
+# Diffie-Hellman parameters used by Photon's key exchange (Oakley group 1).
+OAKLEY_PRIME_768_HEX = (
+    "FFFFFFFFFFFFFFFFC90FDAA22168C234C4C6628B80DC1CD129024E088A67CC74020BBEA6"
+    "3B139B22514A08798E3404DDEF9519B3CD3A431B302B0A6DF25F14374FE1356D6D51C245"
+    "E485B576625E7EC6F44C42E9A63A3620FFFFFFFFFFFFFFFF"
+)
+OAKLEY_PRIME_768 = int(OAKLEY_PRIME_768_HEX, 16)
+DH_GENERATOR = 22

pyphotonrealtime/protocol/deserializer.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import struct
+from io import BytesIO
+from typing import TYPE_CHECKING, cast
+
+from pyphotonrealtime.protocol.command_code import CommandCode
+from pyphotonrealtime.protocol.operation_code import OperationCode
+from pyphotonrealtime.protocol.param.read_param import read_parameter
+
+if TYPE_CHECKING:
+    from typing import Any
+
+    from pyphotonrealtime.protocol.packet.header import PhotonDataPacketHeader
+    from pyphotonrealtime.protocol.param.base import ParameterBase
+    from pyphotonrealtime.protocol.param.parameter_key import ParameterKey
+
+
+def deserialize_photon_payload(
+    header: PhotonDataPacketHeader,
+    data: bytes,
+) -> tuple[
+    OperationCode,
+    dict[ParameterKey, ParameterBase[Any]],
+    tuple[int, ParameterBase[Any]] | None,
+]:
+    stream = BytesIO(data)
+
+    is_response = header.command in (
+        CommandCode.OperationResponse,
+        CommandCode.KeyExchangeResponse,
+        CommandCode.EncryptedOperationResponse,
+        CommandCode.DisconnectMessage,
+    )
+    skip_operation_code = header.command == CommandCode.DisconnectMessage
+
+    operation_code = OperationCode.DiffieHellmanRequest
+    if not skip_operation_code:
+        operation_code = cast("OperationCode", struct.unpack(">B", stream.read(1))[0])
+
+    response_debug_data = None
+    if is_response:
+        return_code = struct.unpack(">h", stream.read(2))[0]
+
+        debug_message_param = read_parameter(stream)
+
+        response_debug_data = (return_code, debug_message_param)
+
+    param_count = struct.unpack(">h", stream.read(2))[0]
+
+    params: dict[ParameterKey, ParameterBase[Any]] = {}
+    for _ in range(param_count):
+        key_bytes = stream.read(1)
+        if not key_bytes:
+            break
+        param_key = cast("ParameterKey", struct.unpack(">B", key_bytes)[0])
+
+        params[param_key] = read_parameter(stream)
+
+    return operation_code, params, response_debug_data

pyphotonrealtime/protocol/enum_lookups.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+from collections import defaultdict
+from typing import TYPE_CHECKING, Any
+
+from pyphotonrealtime.protocol.command_code import CommandCode
+from pyphotonrealtime.protocol.event_code import EventCode
+from pyphotonrealtime.protocol.operation_code import OperationCode
+from pyphotonrealtime.protocol.param.base import ParameterBase
+from pyphotonrealtime.protocol.param.parameter_key import ParameterKey
+from pyphotonrealtime.protocol.param.parameter_type import ParameterType
+from pyphotonrealtime.protocol.serialization_protocol import SerializationProtocol
+
+if TYPE_CHECKING:
+    from enum import IntEnum
+
+
+def build_value_lookup(enum_cls: type[IntEnum]) -> dict[int, list[str]]:
+    lookup: dict[int, list[str]] = defaultdict(list)
+
+    for name, member in enum_cls.__members__.items():
+        lookup[int(member.value)].append(name)
+
+    return dict(lookup)
+
+
+OPERATION_CODE_LOOKUP = build_value_lookup(OperationCode)
+EVENT_CODE_LOOKUP = build_value_lookup(EventCode)
+PARAMETER_KEY_LOOKUP = build_value_lookup(ParameterKey)
+PARAMETER_TYPE_LOOKUP = build_value_lookup(ParameterType)
+COMMAND_CODE_LOOKUP = build_value_lookup(CommandCode)
+SERIALIZATION_PROTOCOL_LOOKUP = build_value_lookup(SerializationProtocol)
+
+CommandParams = dict[ParameterKey, ParameterBase[Any]]
+
+
+def _get_x_name[XT](lookup_table: dict[XT, list[str]], v: XT) -> str:
+    n = lookup_table.get(v)
+    if n is None:
+        return f"UNKNOWN[{v!s}]"
+    if len(n) == 1:
+        return n[0]
+    return "/".join(n)
+
+
+def get_parameter_key_name(key: ParameterKey) -> str:
+    return _get_x_name(PARAMETER_KEY_LOOKUP, key)
+
+
+def get_parameter_type_name(param_type: ParameterType) -> str:
+    return _get_x_name(PARAMETER_TYPE_LOOKUP, param_type)
+
+
+def get_operation_name(operation_code: OperationCode) -> str:
+    return _get_x_name(OPERATION_CODE_LOOKUP, operation_code)
+
+
+def get_event_name(event_code: EventCode) -> str:
+    return _get_x_name(EVENT_CODE_LOOKUP, event_code)
+
+
+def get_command_name(command_code: CommandCode) -> str:
+    return _get_x_name(COMMAND_CODE_LOOKUP, command_code)
+
+
+def get_serialization_protocol_name(protocol: SerializationProtocol) -> str:
+    return _get_x_name(SERIALIZATION_PROTOCOL_LOOKUP, protocol)

pyphotonrealtime/protocol/event_code.py

@@ -0,0 +1,61 @@
+from enum import IntEnum
+
+
+def _as_code(value: object) -> int:
+    if not isinstance(value, int):
+        msg = f"Event codes are ints, got {type(value).__name__}"
+        raise TypeError(msg)
+    return value
+
+
+class PrisonArchitectEventCode(IntEnum):
+    """Reverse-engineered custom Photon event codes for Prison Architect.
+
+    Photon custom events are strictly in the 1-199 range.
+    """
+
+    PlayerJoin_Unknown = 2  # Suspected Player Join
+    PasswordAuthRequest = 5
+    KickPlayer = 6  # Soft kick, just asks the client to leave
+    WorldUpdate = 9
+    TickSpeedUpdate = 96
+
+    # Placeholders for identified but unmapped events
+    Unknown1 = 1
+    Unknown3 = 3
+    Unknown4 = 4
+    Unknown8 = 8
+    Unknown13 = 13
+    Unknown14 = 14
+    Unknown47 = 47
+    Unknown89 = 89
+    Unknown95 = 95
+    Unknown118 = 118
+
+    @classmethod
+    def _missing_(cls, value: object) -> int:
+        """Map unknown codes to plain ints so undocumented events don't crash."""
+        return _as_code(value)
+
+
+CUSTOM_EVENT_CODE_MAX = 200
+
+
+class EventCode(IntEnum):
+    GameList = 0xE6  # 230
+    GameListUpdate = 0xE5
+    QueueState = 0xE4
+    AppStats = 0xE2  # 226
+    GameServerOffline = 0xE1
+    LobbyStats = 0xE0
+    AuthEvent = 0xDF
+
+    Event = 0xFF
+
+    @classmethod
+    def _missing_(cls, value: object) -> int:
+        """Map unknown codes to plain ints so undocumented events don't crash."""
+        code = _as_code(value)
+        if 0 < code <= CUSTOM_EVENT_CODE_MAX:
+            return PrisonArchitectEventCode(code)
+        return code

pyphotonrealtime/protocol/operation_code.py

@@ -0,0 +1,35 @@
+from enum import IntEnum
+
+
+class OperationCode(IntEnum):
+    DiffieHellmanRequest = 0
+    DiffieHellmanResponse = 0x2A  # 42
+
+    GetGameList = 0xD9  # 217
+    Settings = 0xDA  # 218
+    Rpc = 0xDB  # 219
+    GetRegions = 0xDC  # 220
+    LobbyStats = 0xDD  # 221
+    FindFriends = 0xDE  # 222
+    DebugGame = 0xDF  # 223
+
+    JoinRandomGame = 0xE1  # 225
+    JoinGame = 0xE2  # 226
+    CreateGame = 0xE3  # 227
+    LeaveLobby = 0xE4  # 228
+    JoinLobby = 0xE5  # 229
+
+    GameList = 0xE6  # 230
+    Authenticate = 0xE6  # 230 (Alias for GameList)
+    AuthOnce = 0xE7  # 231
+
+    ChangeGroups = 0xF8  # 248
+    Ping = 0xF9  # 249
+
+    GetProperties = 0xFB  # 251
+    SetProperties = 0xFC  # 252
+    RaiseEvent = 0xFD  # 253
+    Leave = 0xFE  # 254
+    Join = 0xFF  # 255
+
+    Event = 0xFF  # 255

pyphotonrealtime/protocol/packet/__init__.py

@@ -0,0 +1,4 @@
+from .base import PhotonPacket
+from .factory import PacketFactory
+
+__all__ = ["PacketFactory", "PhotonPacket"]

pyphotonrealtime/protocol/packet/base.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+from abc import ABC
+from struct import pack
+from typing import TYPE_CHECKING, cast
+
+from pyphotonrealtime.protocol.packet.format import PacketFormat
+from pyphotonrealtime.protocol.packet.header import PhotonDataPacketHeader
+
+if TYPE_CHECKING:
+    from io import BytesIO
+
+
+class PhotonPacket(ABC):
+    _packet_format: PacketFormat
+
+    def __init__(self, packet_format: PacketFormat = PacketFormat.Data) -> None:
+        self._packet_format = packet_format
+
+    @classmethod
+    def from_bytes(cls, data: BytesIO) -> PhotonPacket:
+        packet_format = cast("PacketFormat", int.from_bytes(data.read(1)))
+        return cls(packet_format)
+
+    def serialize(self) -> bytes:
+        format_val = (
+            self._packet_format.value
+            if hasattr(self._packet_format, "value")
+            else self._packet_format
+        )
+        return pack(">B", format_val)
+
+    def get_format(self) -> PacketFormat:
+        return self._packet_format
+
+    def log(self) -> list[str]:
+        return [
+            f"Abstract Packet {self.get_format()}",
+        ]
+
+
+class PhotonDataPacket(PhotonPacket):
+    _header: PhotonDataPacketHeader
+    _data_length: int | None
+
+    def __init__(self, header: PhotonDataPacketHeader) -> None:
+        super().__init__(PacketFormat.Data)
+        self._header = header
+        self._data_length = None
+
+    @classmethod
+    def from_bytes(cls, data: BytesIO) -> PhotonDataPacket:
+        return cls(PhotonDataPacketHeader.from_bytes(data))
+
+    def get_header(self) -> PhotonDataPacketHeader:
+        return self._header
+
+    def resize(self, new_data_length: int) -> None:
+        self._data_length = new_data_length
+
+    def serialize(self) -> bytes:
+        return super().serialize() + self._header.serialize(self._data_length)
+
+    def log(self) -> list[str]:
+        length = (
+            self._data_length
+            if self._data_length is not None
+            else self.get_header().packet_length
+        )
+        return [f"{self.get_header().get_command_name()}, Length: {length}"]

pyphotonrealtime/protocol/packet/disconnect.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Self
+
+from pyphotonrealtime.protocol.packet.operation_packet import PhotonOperationPacket
+
+if TYPE_CHECKING:
+    from io import BytesIO
+
+    from pyphotonrealtime.protocol.packet.header import PhotonDataPacketHeader
+    from pyphotonrealtime.protocol.packet.operation_payload import PhotonPacketPayload
+
+
+class DisconnectMessagePacket(PhotonOperationPacket):
+    def __init__(
+        self,
+        header: PhotonDataPacketHeader,
+        payload: PhotonPacketPayload,
+        aes_key: bytes | None = None,
+    ) -> None:
+        super().__init__(header=header, payload=payload, aes_key=aes_key)
+
+    @classmethod
+    def from_bytes(
+        cls,
+        data: BytesIO,
+        *,
+        header: PhotonDataPacketHeader | None = None,
+        aes_key: bytes | None = None,
+    ) -> Self:
+        return super().from_bytes(data, header=header, aes_key=aes_key)
+
+    def log(self) -> list[str]:
+        return [
+            (
+                f"Command: {self.get_header().get_command_name()} "
+                f"{self.get_payload().get_operation_name()}"
+            ),
+            f"Reason: {self.get_payload().get_debug_message()}",
+        ]

pyphotonrealtime/protocol/packet/event_packet.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from pyphotonrealtime.protocol.command_code import CommandCode
+from pyphotonrealtime.protocol.packet.operation_packet import PhotonOperationPacket
+
+if TYPE_CHECKING:
+    from pyphotonrealtime.protocol.packet.header import PhotonDataPacketHeader
+    from pyphotonrealtime.protocol.packet.operation_payload import (
+        PhotonPacketPayload,
+    )
+
+
+class PhotonEventPacket(PhotonOperationPacket):
+    def __init__(
+        self,
+        header: PhotonDataPacketHeader,
+        payload: PhotonPacketPayload,
+        aes_key: bytes | None = None,
+    ) -> None:
+        super().__init__(header=header, payload=payload, aes_key=aes_key)
+        if header.get_command_code() not in (
+            CommandCode.Event,
+            CommandCode.EncryptedEvent,
+        ):
+            msg = "Packet is not an Event!"
+            raise TypeError(msg)
+        self._operation_payload = payload
+        self._aes_key = aes_key