socket-netty 0.3.0__py3-none-any.whl

pynetty/__init__.py

@@ -0,0 +1,137 @@
+"""
+pynetty: an event-driven asynchronous I/O library inspired by Netty
+(Java), built on top of asyncio.
+
+Typical usage (server):
+
+    from pynetty import ServerBootstrap, ChannelInboundHandler
+
+    class EchoHandler(ChannelInboundHandler):
+        async def channel_read(self, ctx, msg):
+            await ctx.write(msg)  # echo
+
+    async def main():
+        def init_channel(channel):
+            channel.pipeline.add_last("echo", EchoHandler())
+
+        server = await ServerBootstrap().child_handler(init_channel).bind("0.0.0.0", 9000)
+        await server.serve_forever()
+"""
+
+from pynetty.buffer import (
+    ByteBuf,
+    IndexOutOfBoundsError,
+    ByteBufAllocator,
+    UnpooledByteBufAllocator,
+    PooledByteBufAllocator,
+    DEFAULT_UNPOOLED,
+    DEFAULT_POOLED,
+)
+from pynetty.channel import (
+    Channel,
+    ChannelPipeline,
+    DuplicateHandlerNameError,
+    ChannelFuture,
+    ChannelPromise,
+    EventLoop,
+    EventLoopGroup,
+    ChannelOption,
+    apply_socket_options,
+    WriteBufferWaterMark,
+    ChannelExecutor,
+    FlowControlInboundHandler,
+    DatagramChannel,
+    DatagramBootstrap,
+)
+from pynetty.handler import (
+    ChannelHandler,
+    ChannelInboundHandler,
+    ChannelOutboundHandler,
+    ChannelInboundHandlerAdapter,
+    ChannelOutboundHandlerAdapter,
+    SimpleChannelInboundHandler,
+    ChannelHandlerContext,
+    LengthFieldBasedFrameDecoder,
+    LengthFieldPrepender,
+    ByteToMessageCodec,
+    ProtolibCodec,
+    SslContextBuilder,
+    IdleState,
+    IdleStateEvent,
+    IdleStateHandler,
+    ReadTimeoutHandler,
+    ReadTimeoutError,
+    WriteTimeoutHandler,
+    WriteTimeoutError,
+)
+from pynetty.bootstrap import ServerBootstrap, Bootstrap
+from pynetty.exceptions import (
+    NettyException,
+    ChannelException,
+    CodecException,
+    DecoderException,
+    EncoderException,
+    CorruptedFrameException,
+    TooLongFrameException,
+    TimeoutException,
+)
+
+__version__ = "0.3.0"
+
+__all__ = [
+    # exceptions
+    "NettyException",
+    "ChannelException",
+    "CodecException",
+    "DecoderException",
+    "EncoderException",
+    "CorruptedFrameException",
+    "TooLongFrameException",
+    "TimeoutException",
+    # buffer
+    "ByteBuf",
+    "IndexOutOfBoundsError",
+    "ByteBufAllocator",
+    "UnpooledByteBufAllocator",
+    "PooledByteBufAllocator",
+    "DEFAULT_UNPOOLED",
+    "DEFAULT_POOLED",
+    # channel
+    "Channel",
+    "ChannelPipeline",
+    "DuplicateHandlerNameError",
+    "ChannelFuture",
+    "ChannelPromise",
+    "EventLoop",
+    "EventLoopGroup",
+    "ChannelOption",
+    "apply_socket_options",
+    "WriteBufferWaterMark",
+    "ChannelExecutor",
+    "FlowControlInboundHandler",
+    "DatagramChannel",
+    "DatagramBootstrap",
+    # handler
+    "ChannelHandler",
+    "ChannelInboundHandler",
+    "ChannelOutboundHandler",
+    "ChannelInboundHandlerAdapter",
+    "ChannelOutboundHandlerAdapter",
+    "SimpleChannelInboundHandler",
+    "ChannelHandlerContext",
+    "LengthFieldBasedFrameDecoder",
+    "LengthFieldPrepender",
+    "ByteToMessageCodec",
+    "ProtolibCodec",
+    "SslContextBuilder",
+    "IdleState",
+    "IdleStateEvent",
+    "IdleStateHandler",
+    "ReadTimeoutHandler",
+    "ReadTimeoutError",
+    "WriteTimeoutHandler",
+    "WriteTimeoutError",
+    # bootstrap
+    "ServerBootstrap",
+    "Bootstrap",
+]

pynetty/bootstrap/__init__.py

@@ -0,0 +1,3 @@
+from pynetty.bootstrap.bootstrap import ServerBootstrap, Bootstrap
+
+__all__ = ["ServerBootstrap", "Bootstrap"]

pynetty/bootstrap/bootstrap.py

@@ -0,0 +1,162 @@
+"""
+ServerBootstrap / Bootstrap: high-level entry points for standing up a
+server or client, Netty-style. They configure the ChannelInitializer
+and start the asyncio loop underneath. They support .option(...)
+(socket options), .ssl(...) (TLS), .group(...) (EventLoopGroup), and
+.water_mark(...) (backpressure).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import ssl as ssl_module
+from typing import Any, Callable, Dict, Optional
+
+from pynetty.channel.channel import Channel
+from pynetty.channel.protocol_adapter import _ChannelProtocol
+from pynetty.channel.channel_option import ChannelOption, apply_socket_options
+from pynetty.channel.flow_control import WriteBufferWaterMark
+from pynetty.channel.event_loop import EventLoopGroup
+from pynetty.exceptions import ChannelException
+
+
+ChannelInitializer = Callable[[Channel], "asyncio.Future | None"]
+
+
+class ServerBootstrap:
+    """Equivalent to io.netty.bootstrap.ServerBootstrap."""
+
+    def __init__(self) -> None:
+        self._child_initializer: Optional[ChannelInitializer] = None
+        self._server: Optional[asyncio.AbstractServer] = None
+        self._options: Dict[str, Any] = {}
+        self._ssl_context: Optional[ssl_module.SSLContext] = None
+        self._water_mark: Optional[WriteBufferWaterMark] = None
+        self._group: Optional[EventLoopGroup] = None
+
+    def child_handler(self, initializer: ChannelInitializer) -> "ServerBootstrap":
+        self._child_initializer = initializer
+        return self
+
+    def option(self, name: str, value: Any) -> "ServerBootstrap":
+        self._options[name] = value
+        return self
+
+    def ssl(self, context: ssl_module.SSLContext) -> "ServerBootstrap":
+        self._ssl_context = context
+        return self
+
+    def water_mark(self, mark: WriteBufferWaterMark) -> "ServerBootstrap":
+        self._water_mark = mark
+        return self
+
+    def group(self, event_loop_group: EventLoopGroup) -> "ServerBootstrap":
+        self._group = event_loop_group
+        return self
+
+    async def bind(self, host: str = "0.0.0.0", port: int = 0) -> "ServerBootstrap":
+        if self._child_initializer is None:
+            raise ChannelException("You must call child_handler(...) before bind()")
+
+        loop = asyncio.get_event_loop()
+
+        def factory() -> Channel:
+            channel = Channel()
+            result = self._child_initializer(channel)
+            if asyncio.iscoroutine(result):
+                loop.create_task(result)
+            return channel
+
+        backlog = self._options.get(ChannelOption.SO_BACKLOG, 100)
+
+        server = await loop.create_server(
+            lambda: _ChannelProtocol(factory, water_mark=self._water_mark),
+            host=host,
+            port=port,
+            backlog=backlog,
+            ssl=self._ssl_context,
+        )
+
+        remaining = {k: v for k, v in self._options.items() if k != ChannelOption.SO_BACKLOG}
+        if remaining:
+            for sock in server.sockets:
+                apply_socket_options(sock, remaining)
+
+        self._server = server
+        return self
+
+    def sockets_address(self) -> list:
+        if self._server is None:
+            return []
+        return [sock.getsockname() for sock in self._server.sockets]
+
+    async def close(self) -> None:
+        if self._server is not None:
+            self._server.close()
+            await self._server.wait_closed()
+
+    async def serve_forever(self) -> None:
+        if self._server is None:
+            raise ChannelException("Call bind() before serve_forever()")
+        async with self._server:
+            await self._server.serve_forever()
+
+
+class Bootstrap:
+    """Equivalent to io.netty.bootstrap.Bootstrap (client side)."""
+
+    def __init__(self) -> None:
+        self._handler_initializer: Optional[ChannelInitializer] = None
+        self._options: Dict[str, Any] = {}
+        self._ssl_context: Optional[ssl_module.SSLContext] = None
+        self._water_mark: Optional[WriteBufferWaterMark] = None
+        self._group: Optional[EventLoopGroup] = None
+
+    def handler(self, initializer: ChannelInitializer) -> "Bootstrap":
+        self._handler_initializer = initializer
+        return self
+
+    def option(self, name: str, value: Any) -> "Bootstrap":
+        self._options[name] = value
+        return self
+
+    def ssl(self, context: ssl_module.SSLContext) -> "Bootstrap":
+        self._ssl_context = context
+        return self
+
+    def water_mark(self, mark: WriteBufferWaterMark) -> "Bootstrap":
+        self._water_mark = mark
+        return self
+
+    def group(self, event_loop_group: EventLoopGroup) -> "Bootstrap":
+        self._group = event_loop_group
+        return self
+
+    async def connect(self, host: str, port: int) -> Channel:
+        if self._handler_initializer is None:
+            raise ChannelException("You must call handler(...) before connect()")
+
+        loop = asyncio.get_event_loop()
+        holder: dict = {}
+
+        def factory() -> Channel:
+            channel = Channel()
+            holder["channel"] = channel
+            result = self._handler_initializer(channel)
+            if asyncio.iscoroutine(result):
+                loop.create_task(result)
+            return channel
+
+        transport, protocol = await loop.create_connection(
+            lambda: _ChannelProtocol(factory, water_mark=self._water_mark),
+            host=host,
+            port=port,
+            ssl=self._ssl_context,
+        )
+
+        if self._options:
+            sock = transport.get_extra_info("socket")
+            if sock is not None:
+                apply_socket_options(sock, self._options)
+
+        return holder["channel"]

pynetty/buffer/__init__.py

@@ -0,0 +1,18 @@
+from pynetty.buffer.bytebuf import ByteBuf, IndexOutOfBoundsError
+from pynetty.buffer.allocator import (
+    ByteBufAllocator,
+    UnpooledByteBufAllocator,
+    PooledByteBufAllocator,
+    DEFAULT_UNPOOLED,
+    DEFAULT_POOLED,
+)
+
+__all__ = [
+    "ByteBuf",
+    "IndexOutOfBoundsError",
+    "ByteBufAllocator",
+    "UnpooledByteBufAllocator",
+    "PooledByteBufAllocator",
+    "DEFAULT_UNPOOLED",
+    "DEFAULT_POOLED",
+]

pynetty/buffer/allocator.py

@@ -0,0 +1,113 @@
+"""
+ByteBufAllocator: equivalent to io.netty.buffer.ByteBufAllocator.
+
+Netty uses this to avoid GC pressure on high-throughput hot paths
+(thousands of packets/sec) by recycling buffers instead of allocating a
+new one per message. Python's GC differs (refcounting + generational),
+but the pattern still pays off: it avoids constantly reallocating and
+resetting bytearrays in high-traffic game servers.
+
+Two implementations, mirroring Netty:
+  - UnpooledByteBufAllocator: allocates a fresh ByteBuf every time
+    (simple, safe default).
+  - PooledByteBufAllocator: keeps a pool of recycled ByteBuf objects per
+    size bucket; release() returns them to the pool instead of discarding.
+"""
+
+from __future__ import annotations
+
+import threading
+from collections import defaultdict
+from typing import Dict, List
+
+from pynetty.buffer.bytebuf import ByteBuf
+
+
+class ByteBufAllocator:
+    """Base interface — equivalent to Netty's ByteBufAllocator interface."""
+
+    def buffer(self, initial_capacity: int = 256) -> ByteBuf:
+        raise NotImplementedError
+
+    def release(self, buf: ByteBuf) -> None:
+        raise NotImplementedError
+
+
+class UnpooledByteBufAllocator(ByteBufAllocator):
+    """Simple allocator: every buffer() call creates a fresh ByteBuf; release() is a no-op beyond clearing."""
+
+    def buffer(self, initial_capacity: int = 256) -> ByteBuf:
+        return ByteBuf()
+
+    def release(self, buf: ByteBuf) -> None:
+        buf.clear()
+
+
+class PooledByteBufAllocator(ByteBufAllocator):
+    """
+    Allocator with a real pool bucketed by size (powers of 2, same
+    approach Netty uses). buffer() reuses a clean ByteBuf from the
+    matching bucket if one is available; otherwise it creates one.
+
+    release(buf) clears it and returns it to its bucket's pool, ready
+    for the next buffer(similar initial_capacity) call.
+    """
+
+    _MIN_BUCKET = 64  # minimum bucket capacity, in bytes
+
+    def __init__(self, max_pooled_per_bucket: int = 64) -> None:
+        self._pools: Dict[int, List[ByteBuf]] = defaultdict(list)
+        self._max_pooled_per_bucket = max_pooled_per_bucket
+        self._lock = threading.Lock()
+        # Simple metrics, useful for tuning game servers
+        self.stats_allocated = 0
+        self.stats_reused = 0
+        self.stats_released = 0
+
+    def _bucket_for(self, capacity: int) -> int:
+        bucket = self._MIN_BUCKET
+        while bucket < capacity:
+            bucket *= 2
+        return bucket
+
+    def buffer(self, initial_capacity: int = 256) -> ByteBuf:
+        bucket = self._bucket_for(initial_capacity)
+        with self._lock:
+            pool = self._pools[bucket]
+            if pool:
+                buf = pool.pop()
+                self.stats_reused += 1
+                buf._pool_bucket = bucket  # type: ignore[attr-defined]
+                return buf
+            self.stats_allocated += 1
+        buf = ByteBuf()
+        buf._pool_bucket = bucket  # type: ignore[attr-defined]
+        return buf
+
+    def release(self, buf: ByteBuf) -> None:
+        # Use the bucket it was handed out with by buffer(); if the
+        # ByteBuf didn't come from this allocator (unmarked), fall back
+        # to the minimum bucket as a safe default.
+        bucket = getattr(buf, "_pool_bucket", None) or self._MIN_BUCKET
+        buf.clear()
+        with self._lock:
+            pool = self._pools[bucket]
+            if len(pool) < self._max_pooled_per_bucket:
+                pool.append(buf)
+            self.stats_released += 1
+
+    def pooled_count(self) -> int:
+        with self._lock:
+            return sum(len(p) for p in self._pools.values())
+
+    def __repr__(self) -> str:
+        return (
+            f"PooledByteBufAllocator(allocated={self.stats_allocated}, "
+            f"reused={self.stats_reused}, released={self.stats_released}, "
+            f"pooled_now={self.pooled_count()})"
+        )
+
+
+# Default instances, equivalent to Netty's ByteBufAllocator.DEFAULT
+DEFAULT_UNPOOLED = UnpooledByteBufAllocator()
+DEFAULT_POOLED = PooledByteBufAllocator()

pynetty/buffer/bytebuf.py

@@ -0,0 +1,256 @@
+"""
+ByteBuf: Netty-style byte buffer.
+
+Maintains independent reader/writer indices (unlike BytesIO), supports
+dynamic growth, and exposes helpers for big-endian primitives plus
+protobuf/Minecraft-style varints (heavily used in game protocols).
+"""
+
+from __future__ import annotations
+
+import struct
+from typing import Union
+
+from pynetty.exceptions import IndexOutOfBoundsError, CorruptedFrameException
+
+__all__ = ["ByteBuf", "IndexOutOfBoundsError"]
+
+
+class ByteBuf:
+    __slots__ = ("_data", "_reader_index", "_writer_index", "_mark", "_pool_bucket")
+
+    def __init__(self, initial: Union[bytes, bytearray, None] = None) -> None:
+        self._data = bytearray(initial) if initial is not None else bytearray()
+        self._reader_index = 0
+        self._writer_index = len(self._data)
+        self._mark = 0
+        self._pool_bucket = None
+
+    # ------------------------------------------------------------------
+    # Constructors
+    # ------------------------------------------------------------------
+    @classmethod
+    def buffer(cls, capacity: int = 256) -> "ByteBuf":
+        buf = cls()
+        buf._data = bytearray()
+        return buf
+
+    @classmethod
+    def wrapped(cls, data: Union[bytes, bytearray]) -> "ByteBuf":
+        """Wraps existing data; writer_index is left at the end (ready to read)."""
+        return cls(data)
+
+    # ------------------------------------------------------------------
+    # Indices
+    # ------------------------------------------------------------------
+    @property
+    def reader_index(self) -> int:
+        return self._reader_index
+
+    @property
+    def writer_index(self) -> int:
+        return self._writer_index
+
+    def readable_bytes(self) -> int:
+        return self._writer_index - self._reader_index
+
+    def is_readable(self, size: int = 1) -> bool:
+        return self.readable_bytes() >= size
+
+    def reset_reader_index(self) -> "ByteBuf":
+        self._reader_index = 0
+        return self
+
+    def mark_reader_index(self) -> "ByteBuf":
+        self._mark = self._reader_index
+        return self
+
+    def reset_to_mark(self) -> "ByteBuf":
+        self._reader_index = self._mark
+        return self
+
+    def skip_bytes(self, length: int) -> "ByteBuf":
+        self._check_readable(length)
+        self._reader_index += length
+        return self
+
+    def clear(self) -> "ByteBuf":
+        self._reader_index = 0
+        self._writer_index = 0
+        self._data = bytearray()
+        return self
+
+    # ------------------------------------------------------------------
+    # Internal
+    # ------------------------------------------------------------------
+    def _check_readable(self, length: int) -> None:
+        if self.readable_bytes() < length:
+            raise IndexOutOfBoundsError(
+                f"readerIndex({self._reader_index}) + length({length}) exceeds "
+                f"writerIndex({self._writer_index}): {self!r}"
+            )
+
+    def _ensure_writable(self, length: int) -> None:
+        needed = self._writer_index + length
+        if needed > len(self._data):
+            self._data.extend(b"\x00" * (needed - len(self._data)))
+
+    # ------------------------------------------------------------------
+    # Raw bytes
+    # ------------------------------------------------------------------
+    def write_bytes(self, data: Union[bytes, bytearray]) -> "ByteBuf":
+        self._ensure_writable(len(data))
+        self._data[self._writer_index : self._writer_index + len(data)] = data
+        self._writer_index += len(data)
+        return self
+
+    def read_bytes(self, length: int) -> bytes:
+        self._check_readable(length)
+        result = bytes(self._data[self._reader_index : self._reader_index + length])
+        self._reader_index += length
+        return result
+
+    def read_all(self) -> bytes:
+        return self.read_bytes(self.readable_bytes())
+
+    def to_bytes(self) -> bytes:
+        """Full copy of the written content (ignores indices)."""
+        return bytes(self._data[: self._writer_index])
+
+    # ------------------------------------------------------------------
+    # Integers (big-endian, Netty's default)
+    # ------------------------------------------------------------------
+    def write_byte(self, value: int) -> "ByteBuf":
+        return self.write_bytes(struct.pack(">b" if value < 0 else ">B", value & 0xFF if value >= 0 else value))
+
+    def read_byte(self) -> int:
+        return struct.unpack(">b", self.read_bytes(1))[0]
+
+    def read_unsigned_byte(self) -> int:
+        return struct.unpack(">B", self.read_bytes(1))[0]
+
+    def write_short(self, value: int) -> "ByteBuf":
+        return self.write_bytes(struct.pack(">h", value))
+
+    def read_short(self) -> int:
+        return struct.unpack(">h", self.read_bytes(2))[0]
+
+    def write_unsigned_short(self, value: int) -> "ByteBuf":
+        return self.write_bytes(struct.pack(">H", value))
+
+    def read_unsigned_short(self) -> int:
+        return struct.unpack(">H", self.read_bytes(2))[0]
+
+    def write_int(self, value: int) -> "ByteBuf":
+        return self.write_bytes(struct.pack(">i", value))
+
+    def read_int(self) -> int:
+        return struct.unpack(">i", self.read_bytes(4))[0]
+
+    def write_unsigned_int(self, value: int) -> "ByteBuf":
+        return self.write_bytes(struct.pack(">I", value))
+
+    def read_unsigned_int(self) -> int:
+        return struct.unpack(">I", self.read_bytes(4))[0]
+
+    def write_long(self, value: int) -> "ByteBuf":
+        return self.write_bytes(struct.pack(">q", value))
+
+    def read_long(self) -> int:
+        return struct.unpack(">q", self.read_bytes(8))[0]
+
+    def write_float(self, value: float) -> "ByteBuf":
+        return self.write_bytes(struct.pack(">f", value))
+
+    def read_float(self) -> float:
+        return struct.unpack(">f", self.read_bytes(4))[0]
+
+    def write_double(self, value: float) -> "ByteBuf":
+        return self.write_bytes(struct.pack(">d", value))
+
+    def read_double(self) -> float:
+        return struct.unpack(">d", self.read_bytes(8))[0]
+
+    def write_boolean(self, value: bool) -> "ByteBuf":
+        return self.write_byte(1 if value else 0)
+
+    def read_boolean(self) -> bool:
+        return self.read_byte() != 0
+
+    # ------------------------------------------------------------------
+    # VarInt / VarLong (Minecraft / protobuf style) — handy for wire protocols
+    # ------------------------------------------------------------------
+    def write_varint(self, value: int) -> "ByteBuf":
+        value &= 0xFFFFFFFF
+        while True:
+            byte = value & 0x7F
+            value >>= 7
+            if value:
+                self.write_byte(byte | 0x80)
+            else:
+                self.write_byte(byte)
+                break
+        return self
+
+    def read_varint(self) -> int:
+        result = 0
+        shift = 0
+        while True:
+            byte = self.read_unsigned_byte()
+            result |= (byte & 0x7F) << shift
+            if not (byte & 0x80):
+                break
+            shift += 7
+            if shift >= 35:
+                raise CorruptedFrameException("VarInt is too big")
+        if result & 0x80000000:
+            result -= 0x100000000
+        return result
+
+    def write_varlong(self, value: int) -> "ByteBuf":
+        value &= 0xFFFFFFFFFFFFFFFF
+        while True:
+            byte = value & 0x7F
+            value >>= 7
+            if value:
+                self.write_byte(byte | 0x80)
+            else:
+                self.write_byte(byte)
+                break
+        return self
+
+    def read_varlong(self) -> int:
+        result = 0
+        shift = 0
+        while True:
+            byte = self.read_unsigned_byte()
+            result |= (byte & 0x7F) << shift
+            if not (byte & 0x80):
+                break
+            shift += 7
+            if shift >= 70:
+                raise CorruptedFrameException("VarLong is too big")
+        if result & 0x8000000000000000:
+            result -= 0x10000000000000000
+        return result
+
+    # ------------------------------------------------------------------
+    # Strings
+    # ------------------------------------------------------------------
+    def write_string(self, value: str, encoding: str = "utf-8") -> "ByteBuf":
+        encoded = value.encode(encoding)
+        self.write_varint(len(encoded))
+        return self.write_bytes(encoded)
+
+    def read_string(self, encoding: str = "utf-8") -> str:
+        length = self.read_varint()
+        return self.read_bytes(length).decode(encoding)
+
+    def __len__(self) -> int:
+        return self.readable_bytes()
+
+    def __repr__(self) -> str:
+        return (
+            f"ByteBuf(readerIndex={self._reader_index}, "
+            f"writerIndex={self._writer_index}, capacity={len(self._data)})"
+        )