socket-netty 0.3.0__py3-none-any.whl

pynetty/channel/event_loop.py

@@ -0,0 +1,157 @@
+"""
+EventLoop / EventLoopGroup: equivalent to io.netty.channel.EventLoop and
+EventLoopGroup.
+
+In Netty (Java), an EventLoopGroup is a thread pool, each with its own
+event loop, sharing out registered Channels (round-robin). In Python,
+asyncio runs on a single thread per loop, so we replicate the model as
+honestly as possible: each EventLoop in this module runs on its OWN
+operating-system thread, with its own asyncio.EventLoop inside. An
+EventLoopGroup shares Channels across several EventLoops that way —
+real concurrency, not just cooperative.
+
+For the simple single-thread case (99% of asyncio usage),
+EventLoopGroup(num_threads=1) behaves the same as using
+asyncio.get_event_loop() directly, but with Netty's API.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import concurrent.futures
+import itertools
+import threading
+from typing import Any, Callable, Coroutine, List, Optional, TypeVar
+
+T = TypeVar("T")
+
+
+class EventLoop:
+    """
+    Wraps an asyncio.AbstractEventLoop running on a dedicated thread.
+    Equivalent to io.netty.channel.EventLoop (a single-thread
+    execution "wheel").
+    """
+
+    def __init__(self, name: str = "pynetty-eventloop") -> None:
+        self.name = name
+        self._loop: Optional[asyncio.AbstractEventLoop] = None
+        self._thread: Optional[threading.Thread] = None
+        self._ready = threading.Event()
+        self._shutdown = False
+
+    def start(self) -> "EventLoop":
+        if self._thread is not None:
+            return self
+        self._thread = threading.Thread(target=self._run, name=self.name, daemon=True)
+        self._thread.start()
+        self._ready.wait()
+        return self
+
+    def _run(self) -> None:
+        self._loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(self._loop)
+        self._ready.set()
+        try:
+            self._loop.run_forever()
+        finally:
+            self._loop.close()
+
+    @property
+    def loop(self) -> asyncio.AbstractEventLoop:
+        if self._loop is None:
+            raise RuntimeError(f"EventLoop {self.name!r} has not been started (call start())")
+        return self._loop
+
+    def in_event_loop(self) -> bool:
+        """True if the calling code is already running inside this loop/thread."""
+        try:
+            return asyncio.get_running_loop() is self._loop
+        except RuntimeError:
+            return False
+
+    def submit(self, coro_factory: Callable[[], Coroutine[Any, Any, T]]) -> "concurrent.futures.Future[T]":
+        """
+        Schedules a coroutine to run on this EventLoop from ANY thread
+        (including its own). Returns a concurrent.futures.Future that
+        you can block on with .result(), or wrap in asyncio with
+        asyncio.wrap_future().
+        """
+        if self._loop is None:
+            raise RuntimeError(f"EventLoop {self.name!r} has not been started")
+        return asyncio.run_coroutine_threadsafe(coro_factory(), self._loop)
+
+    def call_soon(self, callback: Callable[..., None], *args: Any) -> None:
+        self.loop.call_soon_threadsafe(callback, *args)
+
+    def shutdown_gracefully(self, timeout: float = 5.0) -> None:
+        if self._loop is None or self._shutdown:
+            return
+        self._shutdown = True
+
+        async def _stop_all_tasks() -> None:
+            tasks = [t for t in asyncio.all_tasks(self._loop) if t is not asyncio.current_task()]
+            for t in tasks:
+                t.cancel()
+            if tasks:
+                await asyncio.gather(*tasks, return_exceptions=True)
+
+        fut = asyncio.run_coroutine_threadsafe(_stop_all_tasks(), self._loop)
+        try:
+            fut.result(timeout=timeout)
+        except Exception:
+            pass
+        self._loop.call_soon_threadsafe(self._loop.stop)
+        if self._thread is not None:
+            self._thread.join(timeout=timeout)
+
+    def __repr__(self) -> str:
+        return f"EventLoop(name={self.name!r}, running={self._loop is not None})"
+
+
+class EventLoopGroup:
+    """
+    Pool of EventLoop instances. Equivalent to Netty's NioEventLoopGroup.
+    Shares out EventLoops round-robin via next_loop().
+
+    Typical usage (as in Netty):
+        boss_group = EventLoopGroup(1)     # accepts connections
+        worker_group = EventLoopGroup(4)   # processes channel I/O
+    """
+
+    def __init__(self, num_threads: int = 1, name_prefix: str = "pynetty-worker") -> None:
+        if num_threads < 1:
+            raise ValueError("num_threads must be >= 1")
+        self._loops: List[EventLoop] = [
+            EventLoop(name=f"{name_prefix}-{i}") for i in range(num_threads)
+        ]
+        self._cycle = itertools.cycle(self._loops)
+        self._started = False
+
+    def start(self) -> "EventLoopGroup":
+        if self._started:
+            return self
+        for loop in self._loops:
+            loop.start()
+        self._started = True
+        return self
+
+    def next_loop(self) -> EventLoop:
+        """Returns the next EventLoop round-robin (equivalent to group.next() in Netty)."""
+        if not self._started:
+            self.start()
+        return next(self._cycle)
+
+    def all_loops(self) -> List[EventLoop]:
+        return list(self._loops)
+
+    def shutdown_gracefully(self, timeout: float = 5.0) -> None:
+        for loop in self._loops:
+            loop.shutdown_gracefully(timeout=timeout)
+        self._started = False
+
+    def __len__(self) -> int:
+        return len(self._loops)
+
+    def __repr__(self) -> str:
+        return f"EventLoopGroup(threads={len(self._loops)})"

pynetty/channel/flow_control.py

@@ -0,0 +1,99 @@
+"""
+Backpressure and Concurrency: equivalent to
+io.netty.channel.WriteBufferWaterMark and Netty's one-thread-per-loop
+model.
+
+- WriteBufferWaterMark: high/low thresholds to pause/resume writes
+  when the socket's outbound buffer fills up (asyncio already exposes
+  this via transport.set_write_buffer_limits +
+  pause_writing()/resume_writing() on the Protocol; here we integrate
+  it with the pipeline via channel_writability_changed).
+- ChannelExecutor: guarantees that a given Channel's code always runs
+  serialized (one message at a time), equivalent to Netty "pinning"
+  each Channel to a single EventLoop/thread.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+
+class WriteBufferWaterMark:
+    """
+    Write buffer thresholds. When the pending buffer exceeds `high`,
+    the channel is marked non-writable (backpressure); once it drops
+    below `low`, it's marked writable again.
+    """
+
+    def __init__(self, low: int = 32 * 1024, high: int = 64 * 1024) -> None:
+        if low > high:
+            raise ValueError("low cannot be greater than high")
+        self.low = low
+        self.high = high
+
+    def apply(self, transport: asyncio.Transport) -> None:
+        transport.set_write_buffer_limits(high=self.high, low=self.low)
+
+
+class ChannelExecutor:
+    """
+    Serializes a Channel's message processing using an internal queue +
+    a single worker task — equivalent to Netty's guarantee that all of
+    a Channel's events run on the same thread, one at a time, without
+    racing against each other.
+
+    Usage: instead of creating a task per channel_read, work is queued
+    here, guaranteeing order and avoiding concurrent re-entrancy over
+    the same handler/state.
+    """
+
+    def __init__(self) -> None:
+        self._queue: asyncio.Queue = asyncio.Queue()
+        self._worker: asyncio.Task | None = None
+        self._running = False
+
+    def start(self) -> None:
+        if self._worker is not None:
+            return
+        self._running = True
+        self._worker = asyncio.get_event_loop().create_task(self._run())
+
+    async def submit(self, coro) -> None:
+        await self._queue.put(coro)
+
+    async def _run(self) -> None:
+        while True:
+            coro = await self._queue.get()
+            if coro is None:
+                break
+            try:
+                await coro
+            except Exception:
+                # The pipeline itself already handles exceptions via
+                # exception_caught; this is a last-resort safety net.
+                pass
+            finally:
+                self._queue.task_done()
+
+    async def stop(self) -> None:
+        self._running = False
+        await self._queue.put(None)
+        if self._worker is not None:
+            await self._worker
+
+
+class FlowControlInboundHandler:
+    """
+    Optional mixin: adds channel_writability_changed handling to an
+    existing ChannelInboundHandler. Not a standalone handler — the
+    user is expected to combine it or check ctx.channel.is_writable()
+    before continuing to write aggressively (e.g. when streaming many
+    packets back to back).
+    """
+
+    @staticmethod
+    async def wait_writable(channel: Any, poll_interval: float = 0.01) -> None:
+        """Cooperatively waits until the channel becomes writable again."""
+        while not channel.is_writable():
+            await asyncio.sleep(poll_interval)

pynetty/channel/protocol_adapter.py

@@ -0,0 +1,59 @@
+"""
+_ChannelProtocol: bridge between asyncio.Protocol and our Channel.
+
+asyncio calls these callbacks synchronously; here we convert them into
+coroutines scheduled on the loop so we can fire the pipeline (which is
+async end-to-end) without blocking.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Callable, Optional
+
+from pynetty.channel.channel import Channel
+from pynetty.channel.flow_control import WriteBufferWaterMark
+
+
+class _ChannelProtocol(asyncio.Protocol):
+    def __init__(
+        self,
+        channel_factory: Callable[[], Channel],
+        water_mark: Optional[WriteBufferWaterMark] = None,
+    ) -> None:
+        self.channel: Channel = channel_factory()
+        self._loop = asyncio.get_event_loop()
+        self._water_mark = water_mark
+
+    def connection_made(self, transport: asyncio.BaseTransport) -> None:
+        self.channel._attach_transport(transport)
+        if self._water_mark is not None:
+            self._water_mark.apply(transport)  # type: ignore[arg-type]
+        self._loop.create_task(self._safe(self.channel._mark_active()))
+
+    def data_received(self, data: bytes) -> None:
+        self._loop.create_task(self._safe(self.channel._fire_read(data)))
+
+    def pause_writing(self) -> None:
+        self.channel._set_writable(False)
+
+    def resume_writing(self) -> None:
+        self.channel._set_writable(True)
+
+    def connection_lost(self, exc: Optional[Exception]) -> None:
+        if exc is not None:
+            self._loop.create_task(self._safe(self.channel._fire_exception(exc)))
+        self._loop.create_task(self._safe(self.channel._mark_inactive()))
+
+    async def _safe(self, coro) -> None:
+        try:
+            await coro
+        except Exception as exc:  # noqa: BLE001 - last resort: the task must not die
+            try:
+                await self.channel._fire_exception(exc)
+            except Exception:
+                # If even the exception handling fails, there's nothing
+                # left to do but swallow it silently here; the user
+                # should have a robust exception_caught.
+                pass
+

pynetty/exceptions.py

@@ -0,0 +1,94 @@
+"""
+Exceptions mirroring Netty's own hierarchy under io.netty.*
+
+Every exception here carries a `netty_path` class attribute matching the
+fully-qualified Java class it corresponds to. __str__ prefixes messages
+with that path, so a caught exception prints exactly like it would coming
+out of a real Netty stack, e.g.:
+
+    io.netty.handler.codec.DecoderException: Failed to decode packet
+"""
+
+from __future__ import annotations
+
+
+class NettyException(Exception):
+    """Base class for all pynetty exceptions; mirrors io.netty.channel.ChannelException lineage."""
+
+    netty_path: str = "io.netty.channel.ChannelException"
+
+    def __str__(self) -> str:
+        msg = super().__str__()
+        return f"{self.netty_path}: {msg}" if msg else self.netty_path
+
+
+# ----------------------------------------------------------------------
+# io.netty.channel.*
+# ----------------------------------------------------------------------
+class ChannelException(NettyException):
+    netty_path = "io.netty.channel.ChannelException"
+
+
+class DuplicateHandlerNameError(NettyException):
+    netty_path = "io.netty.channel.ChannelPipelineException"
+
+
+# ----------------------------------------------------------------------
+# io.netty.handler.codec.*
+# ----------------------------------------------------------------------
+class CodecException(NettyException):
+    netty_path = "io.netty.handler.codec.CodecException"
+
+
+class DecoderException(CodecException):
+    netty_path = "io.netty.handler.codec.DecoderException"
+
+
+class EncoderException(CodecException):
+    netty_path = "io.netty.handler.codec.EncoderException"
+
+
+class CorruptedFrameException(DecoderException):
+    netty_path = "io.netty.handler.codec.CorruptedFrameException"
+
+
+class TooLongFrameException(DecoderException):
+    netty_path = "io.netty.handler.codec.TooLongFrameException"
+
+
+# ----------------------------------------------------------------------
+# io.netty.handler.timeout.*
+# ----------------------------------------------------------------------
+class TimeoutException(NettyException):
+    netty_path = "io.netty.handler.timeout.TimeoutException"
+
+
+class ReadTimeoutError(TimeoutException):
+    netty_path = "io.netty.handler.timeout.ReadTimeoutException"
+
+
+class WriteTimeoutError(TimeoutException):
+    netty_path = "io.netty.handler.timeout.WriteTimeoutException"
+
+
+# ----------------------------------------------------------------------
+# io.netty.buffer.*
+# ----------------------------------------------------------------------
+class IndexOutOfBoundsError(NettyException):
+    netty_path = "io.netty.buffer.IndexOutOfBoundsException"
+
+
+__all__ = [
+    "NettyException",
+    "ChannelException",
+    "DuplicateHandlerNameError",
+    "CodecException",
+    "DecoderException",
+    "EncoderException",
+    "CorruptedFrameException",
+    "TooLongFrameException",
+    "TimeoutException",
+    "ReadTimeoutError",
+    "WriteTimeoutError",
+    "IndexOutOfBoundsError",
+]

pynetty/handler/__init__.py

@@ -0,0 +1,47 @@
+from pynetty.handler.channel_handler import (
+    ChannelHandler,
+    ChannelInboundHandler,
+    ChannelOutboundHandler,
+    ChannelInboundHandlerAdapter,
+    ChannelOutboundHandlerAdapter,
+    SimpleChannelInboundHandler,
+)
+from pynetty.handler.channel_handler_context import ChannelHandlerContext
+from pynetty.handler.codec import (
+    LengthFieldBasedFrameDecoder,
+    LengthFieldPrepender,
+    ByteToMessageCodec,
+)
+from pynetty.handler.protolib_codec import ProtolibCodec
+from pynetty.handler.ssl_context import SslContextBuilder
+from pynetty.handler.timeout import (
+    IdleState,
+    IdleStateEvent,
+    IdleStateHandler,
+    ReadTimeoutHandler,
+    ReadTimeoutError,
+    WriteTimeoutHandler,
+    WriteTimeoutError,
+)
+
+__all__ = [
+    "ChannelHandler",
+    "ChannelInboundHandler",
+    "ChannelOutboundHandler",
+    "ChannelInboundHandlerAdapter",
+    "ChannelOutboundHandlerAdapter",
+    "SimpleChannelInboundHandler",
+    "ChannelHandlerContext",
+    "LengthFieldBasedFrameDecoder",
+    "LengthFieldPrepender",
+    "ByteToMessageCodec",
+    "ProtolibCodec",
+    "SslContextBuilder",
+    "IdleState",
+    "IdleStateEvent",
+    "IdleStateHandler",
+    "ReadTimeoutHandler",
+    "ReadTimeoutError",
+    "WriteTimeoutHandler",
+    "WriteTimeoutError",
+]

pynetty/handler/channel_handler.py

@@ -0,0 +1,83 @@
+"""
+ChannelHandler: basic unit of event processing in the pipeline.
+
+Follows Netty's model: handlers receive events (inbound) or intercept
+write operations (outbound) through a ChannelHandlerContext, and decide
+whether to propagate them to the next handler in the chain.
+"""
+
+from __future__ import annotations
+
+from typing import Any, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pynetty.handler.channel_handler_context import ChannelHandlerContext
+
+
+class ChannelHandler:
+    """Base class that all handlers inherit from."""
+
+    async def handler_added(self, ctx: "ChannelHandlerContext") -> None:
+        """Called when the handler is added to the pipeline."""
+
+    async def handler_removed(self, ctx: "ChannelHandlerContext") -> None:
+        """Called when the handler is removed from the pipeline."""
+
+    async def exception_caught(self, ctx: "ChannelHandlerContext", exc: Exception) -> None:
+        """Default exception handling: propagates to the next handler."""
+        await ctx.fire_exception_caught(exc)
+
+
+class ChannelInboundHandler(ChannelHandler):
+    """Handler for inbound events: connection, data read, close, etc."""
+
+    async def channel_registered(self, ctx: "ChannelHandlerContext") -> None:
+        await ctx.fire_channel_registered()
+
+    async def channel_active(self, ctx: "ChannelHandlerContext") -> None:
+        await ctx.fire_channel_active()
+
+    async def channel_inactive(self, ctx: "ChannelHandlerContext") -> None:
+        await ctx.fire_channel_inactive()
+
+    async def channel_read(self, ctx: "ChannelHandlerContext", msg: Any) -> None:
+        await ctx.fire_channel_read(msg)
+
+    async def channel_read_complete(self, ctx: "ChannelHandlerContext") -> None:
+        await ctx.fire_channel_read_complete()
+
+
+class ChannelOutboundHandler(ChannelHandler):
+    """Handler for outbound operations: write, close, etc."""
+
+    async def write(self, ctx: "ChannelHandlerContext", msg: Any) -> None:
+        await ctx.write(msg)
+
+    async def close(self, ctx: "ChannelHandlerContext") -> None:
+        await ctx.close()
+
+
+class ChannelInboundHandlerAdapter(ChannelInboundHandler):
+    """Alias for compatibility with Netty's naming (ChannelInboundHandlerAdapter)."""
+
+
+class ChannelOutboundHandlerAdapter(ChannelOutboundHandler):
+    """Alias for compatibility with Netty's naming (ChannelOutboundHandlerAdapter)."""
+
+
+class SimpleChannelInboundHandler(ChannelInboundHandler):
+    """
+    Equivalent to Netty's SimpleChannelInboundHandler: automatically
+    releases/discards the message after processing it. Python has no
+    manual refcounting like Netty's (pooled ByteBuf), so this mainly
+    serves as a semantic extension point.
+    """
+
+    async def channel_read(self, ctx: "ChannelHandlerContext", msg: Any) -> None:
+        try:
+            await self.channel_read0(ctx, msg)
+        finally:
+            pass
+
+    async def channel_read0(self, ctx: "ChannelHandlerContext", msg: Any) -> None:
+        raise NotImplementedError

pynetty/handler/channel_handler_context.py

@@ -0,0 +1,104 @@
+"""
+ChannelHandlerContext: represents the association between a
+ChannelHandler and its position within the ChannelPipeline. Lets you
+propagate events forward (inbound) or backward (outbound) in the chain.
+"""
+
+from __future__ import annotations
+
+from typing import Any, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pynetty.channel.channel import Channel
+    from pynetty.handler.channel_handler import ChannelHandler
+    from pynetty.channel.channel_pipeline import ChannelPipeline
+
+
+class ChannelHandlerContext:
+    __slots__ = ("name", "handler", "pipeline", "_next", "_prev")
+
+    def __init__(self, name: str, handler: "ChannelHandler", pipeline: "ChannelPipeline") -> None:
+        self.name = name
+        self.handler = handler
+        self.pipeline = pipeline
+        self._next: "ChannelHandlerContext | None" = None
+        self._prev: "ChannelHandlerContext | None" = None
+
+    @property
+    def channel(self) -> "Channel":
+        return self.pipeline.channel
+
+    # ------------------------------------------------------------------
+    # Inbound propagation (toward the next handler in the chain)
+    # ------------------------------------------------------------------
+    async def fire_channel_registered(self) -> None:
+        nxt = self._find_next_inbound()
+        if nxt is not None:
+            await nxt.handler.channel_registered(nxt)
+
+    async def fire_channel_active(self) -> None:
+        nxt = self._find_next_inbound()
+        if nxt is not None:
+            await nxt.handler.channel_active(nxt)
+
+    async def fire_channel_inactive(self) -> None:
+        nxt = self._find_next_inbound()
+        if nxt is not None:
+            await nxt.handler.channel_inactive(nxt)
+
+    async def fire_channel_read(self, msg: Any) -> None:
+        nxt = self._find_next_inbound()
+        if nxt is not None:
+            await nxt.handler.channel_read(nxt, msg)
+
+    async def fire_channel_read_complete(self) -> None:
+        nxt = self._find_next_inbound()
+        if nxt is not None:
+            await nxt.handler.channel_read_complete(nxt)
+
+    async def fire_exception_caught(self, exc: Exception) -> None:
+        nxt = self._find_next_inbound()
+        if nxt is not None:
+            await nxt.handler.exception_caught(nxt, exc)
+        else:
+            # No one else is left in the chain: don't swallow it silently.
+            raise exc
+
+    # ------------------------------------------------------------------
+    # Outbound propagation (backward, toward the socket)
+    # ------------------------------------------------------------------
+    async def write(self, msg: Any) -> None:
+        prev = self._find_prev_outbound()
+        if prev is not None:
+            await prev.handler.write(prev, msg)
+        else:
+            await self.channel._do_write(msg)
+
+    async def close(self) -> None:
+        prev = self._find_prev_outbound()
+        if prev is not None:
+            await prev.handler.close(prev)
+        else:
+            await self.channel._do_close()
+
+    # ------------------------------------------------------------------
+    # Lookup of relevant handlers by type
+    # ------------------------------------------------------------------
+    def _find_next_inbound(self) -> "ChannelHandlerContext | None":
+        from pynetty.handler.channel_handler import ChannelInboundHandler
+
+        node = self._next
+        while node is not None and not isinstance(node.handler, ChannelInboundHandler):
+            node = node._next
+        return node
+
+    def _find_prev_outbound(self) -> "ChannelHandlerContext | None":
+        from pynetty.handler.channel_handler import ChannelOutboundHandler
+
+        node = self._prev
+        while node is not None and not isinstance(node.handler, ChannelOutboundHandler):
+            node = node._prev
+        return node
+
+    def __repr__(self) -> str:
+        return f"ChannelHandlerContext(name={self.name!r}, handler={self.handler.__class__.__name__})"