socket-netty 0.3.0__py3-none-any.whl

pynetty/handler/codec.py

@@ -0,0 +1,152 @@
+"""
+Common codecs, equivalent to io.netty.handler.codec.*
+
+- LengthFieldBasedFrameDecoder: reassembles TCP frames using a length
+  field at the start of each message (the classic "TCP doesn't respect
+  message boundaries" problem).
+- LengthFieldPrepender: prepends the length field before writing.
+
+Very useful for game protocols (Minecraft, Free Fire, etc.) where each
+packet is preceded by its size.
+"""
+
+from __future__ import annotations
+
+import struct
+from typing import Any
+
+from pynetty.buffer.bytebuf import ByteBuf
+from pynetty.exceptions import (
+    CorruptedFrameException,
+    DecoderException,
+    EncoderException,
+    TooLongFrameException,
+)
+from pynetty.handler.channel_handler import ChannelInboundHandler, ChannelOutboundHandler
+from pynetty.handler.channel_handler_context import ChannelHandlerContext
+
+# Netty's own default cap for LengthFieldBasedFrameDecoder-style decoders
+# is unbounded unless you specify max_frame_length; we mirror that but
+# make it configurable, matching real Netty usage patterns.
+_DEFAULT_MAX_FRAME_LENGTH = 8 * 1024 * 1024  # 8 MiB, a sane game-protocol default
+
+
+class LengthFieldBasedFrameDecoder(ChannelInboundHandler):
+    """
+    Accumulates bytes until a full frame is available, using a
+    fixed-size length field (1, 2, or 4 bytes) at the start of each
+    message.
+
+    length_field_length: how many bytes the length field occupies (1/2/4).
+    strip_length_field: if True, the message delivered to channel_read
+        does not include the length field, only the payload.
+    max_frame_length: frames whose declared length exceeds this raise
+        TooLongFrameException instead of buffering unbounded memory.
+    """
+
+    _FORMATS = {1: ">B", 2: ">H", 4: ">I"}
+
+    def __init__(
+        self,
+        length_field_length: int = 4,
+        strip_length_field: bool = True,
+        max_frame_length: int = _DEFAULT_MAX_FRAME_LENGTH,
+    ) -> None:
+        if length_field_length not in self._FORMATS:
+            raise ValueError("length_field_length must be 1, 2, or 4")
+        self._len_fmt = self._FORMATS[length_field_length]
+        self._len_size = length_field_length
+        self._strip = strip_length_field
+        self._max_frame_length = max_frame_length
+        self._buffer = bytearray()
+
+    async def channel_read(self, ctx: ChannelHandlerContext, msg: Any) -> None:
+        data = msg if isinstance(msg, (bytes, bytearray)) else bytes(msg)
+        self._buffer.extend(data)
+
+        try:
+            while True:
+                if len(self._buffer) < self._len_size:
+                    break
+                (frame_len,) = struct.unpack(self._len_fmt, self._buffer[: self._len_size])
+
+                if frame_len < 0:
+                    raise CorruptedFrameException(
+                        f"negative pre-adjustment length field: {frame_len}"
+                    )
+                if frame_len > self._max_frame_length:
+                    # Drop what we have; there's no reliable way to resync
+                    # mid-stream once a bogus length is trusted.
+                    self._buffer.clear()
+                    raise TooLongFrameException(
+                        f"frame length ({frame_len}) exceeds the configured maximum "
+                        f"({self._max_frame_length})"
+                    )
+
+                total = self._len_size + frame_len
+                if len(self._buffer) < total:
+                    break
+
+                if self._strip:
+                    frame = bytes(self._buffer[self._len_size : total])
+                else:
+                    frame = bytes(self._buffer[:total])
+
+                del self._buffer[:total]
+                await ctx.fire_channel_read(frame)
+        except (CorruptedFrameException, TooLongFrameException):
+            raise
+        except Exception as exc:
+            raise DecoderException("Failed to decode packet") from exc
+
+
+class LengthFieldPrepender(ChannelOutboundHandler):
+    """Prepends the payload size before writing it to the socket."""
+
+    _FORMATS = {1: ">B", 2: ">H", 4: ">I"}
+
+    def __init__(self, length_field_length: int = 4) -> None:
+        if length_field_length not in self._FORMATS:
+            raise ValueError("length_field_length must be 1, 2, or 4")
+        self._len_fmt = self._FORMATS[length_field_length]
+
+    async def write(self, ctx: ChannelHandlerContext, msg: Any) -> None:
+        try:
+            if isinstance(msg, ByteBuf):
+                payload = msg.to_bytes()
+            elif isinstance(msg, (bytes, bytearray)):
+                payload = bytes(msg)
+            else:
+                raise TypeError(
+                    f"LengthFieldPrepender expects bytes/ByteBuf, got {type(msg).__name__}"
+                )
+            header = struct.pack(self._len_fmt, len(payload))
+        except TypeError:
+            raise
+        except Exception as exc:
+            raise EncoderException("Failed to encode packet") from exc
+        await ctx.write(header + payload)
+
+
+class ByteToMessageCodec(ChannelInboundHandler):
+    """
+    Simple base for decoders that operate on an accumulated ByteBuf
+    instead of raw `bytes` fragments. Subclass and override `decode`.
+    """
+
+    def __init__(self) -> None:
+        self._cumulation = ByteBuf()
+
+    async def channel_read(self, ctx: ChannelHandlerContext, msg: Any) -> None:
+        data = msg if isinstance(msg, (bytes, bytearray)) else bytes(msg)
+        self._cumulation.write_bytes(data)
+        try:
+            await self.decode(ctx, self._cumulation)
+        except (CorruptedFrameException, TooLongFrameException):
+            raise
+        except Exception as exc:
+            raise DecoderException("Failed to decode packet") from exc
+
+    async def decode(self, ctx: ChannelHandlerContext, buf: ByteBuf) -> None:
+        """Override: read from `buf` while complete frames are available."""
+        raise NotImplementedError

pynetty/handler/protolib_codec.py

@@ -0,0 +1,152 @@
+"""
+ProtolibCodec: bridges pynetty's ChannelPipeline with protolib's
+declarative binary-protocol engine (https://pypi.org/project/protolib/).
+
+protolib turns bytes into a dict (`{name, params}`) and back, based on
+a `.yml`/`.json` protocol description — instead of you hand-writing a
+parser for every packet type. This codec plugs that engine directly
+into the pipeline: `channel_read` delivers a dict, and `write` accepts
+a `(name, params)` tuple (or a dict with those two keys) and turns it
+into bytes.
+
+Two framing modes, controlled by `framed`:
+
+- `framed=True` (default): the codec owns framing itself via
+  protolib's own `PacketFramer` (varint length-prefix, Minecraft-style
+  wire format). Do NOT also add a LengthFieldBasedFrameDecoder in the
+  pipeline in this mode — ProtolibCodec already consumes raw,
+  unframed bytes straight from the socket.
+- `framed=False`: the codec assumes it's receiving an already-complete
+  frame (typically because a LengthFieldBasedFrameDecoder — or any
+  other decoder — sits earlier in the pipeline). Use this for
+  protocols with fixed-size or otherwise non-varint framing, such as
+  Minecraft Classic/ClassiCube. In this mode the codec calls
+  `Protocol.parse_packet`/`serialize_packet` directly and does no
+  buffering of its own.
+
+Any error protolib raises while parsing/serializing (ProtolibError and
+subclasses, including BufferUnderrun escaping in framed=False mode) is
+wrapped into pynetty's own DecoderException/EncoderException, so a
+broken packet looks the same everywhere in the pipeline:
+
+    io.netty.handler.codec.DecoderException: Failed to decode packet
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional, Tuple, Union
+
+from pynetty.exceptions import DecoderException, EncoderException
+from pynetty.handler.channel_handler import ChannelInboundHandler, ChannelOutboundHandler
+from pynetty.handler.channel_handler_context import ChannelHandlerContext
+
+try:
+    from protolib import Protocol, PacketFramer
+    from protolib.errors import ProtolibError
+    from protolib.io import BufferUnderrun
+except ImportError as _exc:  # pragma: no cover - exercised only when protolib is missing
+    Protocol = None  # type: ignore[assignment]
+    PacketFramer = None  # type: ignore[assignment]
+    ProtolibError = Exception  # type: ignore[assignment,misc]
+    BufferUnderrun = Exception  # type: ignore[assignment,misc]
+    _IMPORT_ERROR = _exc
+else:
+    _IMPORT_ERROR = None
+
+
+def _require_protolib() -> None:
+    if Protocol is None:
+        raise ImportError(
+            "ProtolibCodec requires the 'protolib' package. Install it with "
+            "'pip install protolib', or install pynetty with its declared "
+            "dependency (pip install pynetty) which pulls it in automatically."
+        ) from _IMPORT_ERROR
+
+
+class ProtolibCodec(ChannelInboundHandler, ChannelOutboundHandler):
+    """
+    Combined inbound+outbound handler: decodes incoming bytes into
+    `{name, params}` dicts using a protolib `Protocol`, and encodes
+    outgoing `(name, params)` tuples (or `{"name": ..., "params": ...}`
+    dicts) back into bytes.
+
+    protocol: a protolib `Protocol` instance, OR anything accepted by
+        `Protocol(...)` directly (a path to .yml/.json, an in-memory
+        string, or an already-parsed dict) — in which case this codec
+        builds the `Protocol` itself.
+    state / direction_in / direction_out: the state/direction keys
+        used to call `parse_packet`/`serialize_packet`. For stateless
+        protocols (e.g. Minecraft Bedrock), pass state=None — see
+        protolib's own docs on `packet_type_name`.
+    framed: True to have this codec do its own varint-length framing
+        via protolib's PacketFramer (raw socket bytes in); False to
+        assume a complete frame is already being delivered by an
+        earlier pipeline handler (e.g. LengthFieldBasedFrameDecoder).
+    """
+
+    def __init__(
+        self,
+        protocol: Any,
+        state: Optional[str] = "play",
+        direction_in: str = "toServer",
+        direction_out: str = "toClient",
+        framed: bool = True,
+    ) -> None:
+        _require_protolib()
+        self._protocol = protocol if isinstance(protocol, Protocol) else Protocol(protocol)
+        self._state = state
+        self._direction_in = direction_in
+        self._direction_out = direction_out
+        self._framed = framed
+        self._framer = PacketFramer() if framed else None
+
+    # ------------------------------------------------------------------
+    # Inbound: bytes -> {"name": ..., "params": ...}
+    # ------------------------------------------------------------------
+    async def channel_read(self, ctx: ChannelHandlerContext, msg: Any) -> None:
+        data = msg if isinstance(msg, (bytes, bytearray)) else bytes(msg)
+
+        try:
+            if self._framed:
+                frames = self._framer.feed(data)
+            else:
+                frames = [bytes(data)]
+
+            for frame in frames:
+                parsed = self._protocol.parse_packet(self._state, self._direction_in, frame)
+                await ctx.fire_channel_read({"name": parsed.name, "params": parsed.params})
+        except BufferUnderrun:
+            # Only reachable in framed=False mode: an earlier handler
+            # handed us an incomplete frame. In framed=True mode
+            # PacketFramer already guarantees complete frames.
+            raise DecoderException(
+                "Incomplete packet: an earlier handler must deliver a "
+                "complete frame when framed=False"
+            ) from None
+        except ProtolibError as exc:
+            raise DecoderException("Failed to decode packet") from exc
+
+    # ------------------------------------------------------------------
+    # Outbound: (name, params) or {"name": ..., "params": ...} -> bytes
+    # ------------------------------------------------------------------
+    async def write(self, ctx: ChannelHandlerContext, msg: Any) -> None:
+        name, params = self._unpack_outbound(msg)
+
+        try:
+            raw = self._protocol.serialize_packet(self._state, self._direction_out, name, params)
+            payload = PacketFramer.wrap(raw) if self._framed else raw
+        except ProtolibError as exc:
+            raise EncoderException("Failed to encode packet") from exc
+
+        await ctx.write(payload)
+
+    @staticmethod
+    def _unpack_outbound(msg: Any) -> Tuple[str, dict]:
+        if isinstance(msg, tuple) and len(msg) == 2:
+            return msg[0], msg[1]
+        if isinstance(msg, dict) and "name" in msg and "params" in msg:
+            return msg["name"], msg["params"]
+        raise EncoderException(
+            f"ProtolibCodec expects a (name, params) tuple or a "
+            f"{{'name': ..., 'params': ...}} dict, got {type(msg).__name__}"
+        )

pynetty/handler/ssl_context.py

@@ -0,0 +1,62 @@
+"""
+SslContext: equivalent to io.netty.handler.ssl.SslContextBuilder.
+
+asyncio already supports TLS natively via ssl.SSLContext passed to
+create_server()/create_connection(). Here we expose a builder with the
+same feel as Netty instead of making the user deal with the stdlib
+`ssl` module directly.
+"""
+
+from __future__ import annotations
+
+import ssl
+from typing import Optional
+
+
+class SslContextBuilder:
+    """Simplified equivalent to io.netty.handler.ssl.SslContextBuilder."""
+
+    def __init__(self) -> None:
+        self._cert_file: Optional[str] = None
+        self._key_file: Optional[str] = None
+        self._ca_file: Optional[str] = None
+        self._for_client = False
+        self._verify_peer = True
+
+    @classmethod
+    def for_server(cls, cert_file: str, key_file: str) -> "SslContextBuilder":
+        builder = cls()
+        builder._cert_file = cert_file
+        builder._key_file = key_file
+        builder._for_client = False
+        return builder
+
+    @classmethod
+    def for_client(cls) -> "SslContextBuilder":
+        builder = cls()
+        builder._for_client = True
+        return builder
+
+    def trust_manager(self, ca_file: str) -> "SslContextBuilder":
+        self._ca_file = ca_file
+        return self
+
+    def insecure_skip_verify(self) -> "SslContextBuilder":
+        """Equivalent to Netty's InsecureTrustManagerFactory — for development/testing ONLY."""
+        self._verify_peer = False
+        return self
+
+    def build(self) -> ssl.SSLContext:
+        if self._for_client:
+            ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
+            if self._ca_file:
+                ctx.load_verify_locations(cafile=self._ca_file)
+            if not self._verify_peer:
+                ctx.check_hostname = False
+                ctx.verify_mode = ssl.CERT_NONE
+        else:
+            ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
+            if not self._cert_file or not self._key_file:
+                raise ValueError("TLS server requires cert_file and key_file (use for_server(...))")
+            ctx.load_cert_chain(certfile=self._cert_file, keyfile=self._key_file)
+        return ctx

pynetty/handler/timeout.py

@@ -0,0 +1,159 @@
+"""
+IdleStateHandler / ReadTimeoutHandler / WriteTimeoutHandler: equivalent
+to io.netty.handler.timeout.*
+
+- IdleStateHandler: fires an event once the channel has gone N seconds
+  without read activity, write activity, or both. It does not close
+  the connection by itself — typically combined with a handler that
+  reacts to the event (e.g. sending a ping, or closing if there's no
+  response).
+- ReadTimeoutHandler: closes the channel if too much time passes
+  without receiving data.
+- WriteTimeoutHandler: closes the channel if a write takes too long to
+  complete (approximated here, since asyncio doesn't easily expose
+  "pending write" at the socket level).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from enum import Enum, auto
+from typing import Optional
+
+from pynetty.exceptions import ReadTimeoutError, WriteTimeoutError
+from pynetty.handler.channel_handler import ChannelInboundHandler, ChannelOutboundHandler
+from pynetty.handler.channel_handler_context import ChannelHandlerContext
+
+
+class IdleState(Enum):
+    READER_IDLE = auto()
+    WRITER_IDLE = auto()
+    ALL_IDLE = auto()
+
+
+class IdleStateEvent:
+    def __init__(self, state: IdleState) -> None:
+        self.state = state
+
+    def __repr__(self) -> str:
+        return f"IdleStateEvent({self.state.name})"
+
+
+class IdleStateHandler(ChannelInboundHandler):
+    """
+    Fires a user_event_triggered-equivalent instead of overloading
+    channel_read: since pynetty doesn't (yet) have a separate channel
+    for user events, this handler calls a user-provided `on_idle`
+    callback directly.
+    """
+
+    def __init__(
+        self,
+        reader_idle_seconds: float = 0,
+        writer_idle_seconds: float = 0,
+        all_idle_seconds: float = 0,
+    ) -> None:
+        self._reader_idle = reader_idle_seconds
+        self._writer_idle = writer_idle_seconds
+        self._all_idle = all_idle_seconds
+        self._last_read = time.monotonic()
+        self._last_write = time.monotonic()
+        self._task: Optional[asyncio.Task] = None
+        self.on_idle = None  # optional async callback: async def on_idle(ctx, IdleStateEvent)
+
+    async def channel_active(self, ctx: ChannelHandlerContext) -> None:
+        self._last_read = time.monotonic()
+        self._last_write = time.monotonic()
+        self._task = asyncio.get_event_loop().create_task(self._watch(ctx))
+        await ctx.fire_channel_active()
+
+    async def channel_inactive(self, ctx: ChannelHandlerContext) -> None:
+        if self._task is not None:
+            self._task.cancel()
+        await ctx.fire_channel_inactive()
+
+    async def channel_read(self, ctx: ChannelHandlerContext, msg) -> None:
+        self._last_read = time.monotonic()
+        await ctx.fire_channel_read(msg)
+
+    def notify_write(self) -> None:
+        """Call manually after each write (there's no automatic outbound hook here)."""
+        self._last_write = time.monotonic()
+
+    async def _watch(self, ctx: ChannelHandlerContext) -> None:
+        try:
+            while True:
+                await asyncio.sleep(0.5)
+                now = time.monotonic()
+                if self._reader_idle and (now - self._last_read) >= self._reader_idle:
+                    await self._fire(ctx, IdleState.READER_IDLE)
+                    self._last_read = now
+                if self._writer_idle and (now - self._last_write) >= self._writer_idle:
+                    await self._fire(ctx, IdleState.WRITER_IDLE)
+                    self._last_write = now
+                if self._all_idle and (now - min(self._last_read, self._last_write)) >= self._all_idle:
+                    await self._fire(ctx, IdleState.ALL_IDLE)
+        except asyncio.CancelledError:
+            pass
+
+    async def _fire(self, ctx: ChannelHandlerContext, state: IdleState) -> None:
+        if self.on_idle is not None:
+            await self.on_idle(ctx, IdleStateEvent(state))
+
+
+class ReadTimeoutHandler(ChannelInboundHandler):
+    """Closes the channel if `timeout_seconds` pass without receiving any data."""
+
+    def __init__(self, timeout_seconds: float) -> None:
+        self._timeout = timeout_seconds
+        self._task: Optional[asyncio.Task] = None
+        self._last_read = time.monotonic()
+
+    async def channel_active(self, ctx: ChannelHandlerContext) -> None:
+        self._last_read = time.monotonic()
+        self._task = asyncio.get_event_loop().create_task(self._watch(ctx))
+        await ctx.fire_channel_active()
+
+    async def channel_inactive(self, ctx: ChannelHandlerContext) -> None:
+        if self._task is not None:
+            self._task.cancel()
+        await ctx.fire_channel_inactive()
+
+    async def channel_read(self, ctx: ChannelHandlerContext, msg) -> None:
+        self._last_read = time.monotonic()
+        await ctx.fire_channel_read(msg)
+
+    async def _watch(self, ctx: ChannelHandlerContext) -> None:
+        try:
+            while True:
+                await asyncio.sleep(0.25)
+                if (time.monotonic() - self._last_read) >= self._timeout:
+                    await ctx.fire_exception_caught(
+                        ReadTimeoutError(f"No data received in {self._timeout}s")
+                    )
+                    await ctx.close()
+                    return
+        except asyncio.CancelledError:
+            pass
+
+
+class WriteTimeoutHandler(ChannelOutboundHandler):
+    """
+    Closes the channel if a single write doesn't complete within the
+    time limit. Since asyncio.Transport.write() isn't awaitable (it
+    doesn't block, it queues internally), this watches that the
+    transport's drain() doesn't take too long when the outbound buffer
+    is full.
+    """
+
+    def __init__(self, timeout_seconds: float) -> None:
+        self._timeout = timeout_seconds
+
+    async def write(self, ctx: ChannelHandlerContext, msg) -> None:
+        try:
+            await asyncio.wait_for(ctx.write(msg), timeout=self._timeout)
+        except asyncio.TimeoutError:
+            exc = WriteTimeoutError(f"Write did not complete in {self._timeout}s")
+            await ctx.fire_exception_caught(exc)
+            await ctx.close()