Wbs implementation

AGENTS.md

@@ -2,18 +2,46 @@
 
 Read README.md for the basic understanding of what this project is.
 
-picows - this is the main package
+picows - this is the main package.
+picows.websockets - reimplements popular websockets library interface on top of picows
+tests - Contains tests for picows
+examples - Various examples for users on how to use picows + perf_test that could be used to build call-graph with perf 
 
-aiofastnet - Contains optimized versions of asyncio create_connection, create_server
-I plan to make a separate python project for it, but I'm not there yet. It should be treated
-as a separate python project. It will have its own tests, eventually its own description and docs.
-The project contains very efficient repimplementation of SelectSocketTransport and SSLProtocol 
-using Cython and sometimes a pure C code. create_connection, create_server are defined in aiofastnet/api.py
-sslproto.pyx - hack python SSLContext to get raw SSL_CTX*, it works with openssl api directly after that.
-sslproto_stdlib.pyx - is just for reference, I will delete it soon, but now it's good for comparison between
-stdlib ssl and whatever is in sslproto.pyx.
-
-tests - Contains tests for both picows and aiofastnet. Tests for aiofastnet will become a part of a separate project.
+## Code style notes
+- Max line width is 120
+- Do not write `del transport` or similar `del <parameter>` statements inside callbacks just to mark arguments as unused.
+  Leave unused callback parameters as-is or rename them with a leading underscore if that is clearer.
+  Using `del` in this situation is confusing and suggests reference-counting or lifetime management concerns.
+- Prefer direct composition only when there is a real behavioral boundary.
+  Do not introduce adapter / holder / deferred-event plumbing just to preserve a conceptual separation.
+  If extra machinery exists only to work around the separation you introduced, the separation is probably wrong.
+- Do not model impossible or non-normal internal states in the mainline code path without a concrete reason.
+  If an invariant is guaranteed by control flow, write the code around that invariant instead of adding repeated defensive checks.
+  Every extra "just in case" branch teaches the reader that the state is part of normal behavior.
+  Add such checks only for real risks like external misuse, concurrency races, partial failure, or invariants that are genuinely hard to guarantee.
+  If the only reason for the check is uncertainty in the design, fix the design first.
+- When simplifying code, finish the simplification across all equivalent branches, not only at the first local site.
+  If the same conversion, check, or tiny code pattern appears in multiple sibling paths after a refactor, stop and normalize it before considering the work done.
+  Do not remove one layer of abstraction only to inline the same logic redundantly in several places.
+  After a refactor, scan for duplicated branch bodies and duplicated type-specific handling introduced by the change.
+- `picows.websockets` aims for import-level compatibility with the official `websockets` package on the client side.
+  We can skip complicated areas such as the full server interface, but simple surface-area compatibility matters.
+  Type definitions, exception definitions, and other lightweight importable names should exist when upstream exposes them.
+  People switching from `websockets` to `picows.websockets` should notice as little difference as possible.
+- In Cythonized Python modules, avoid `typing.cast(...)` in hot paths.
+  Cython may compile `cast(...)` into a real runtime global lookup and function call instead of erasing it like a type checker would.
+  Prefer control-flow narrowing, assertions, or narrowly scoped type-ignore comments when needed.
+- If `picows` core exposes an inconsistent runtime shape or behavior that looks like a bug, do not silently normalize around it in wrapper code.
+  Stop and ask first, or at least clearly call out that it appears to be a core bug instead of assuming it is an intentional quirk.
+  Wrapper-level workarounds for such inconsistencies should be treated as temporary and explicit, not as the default resolution.
+  Legitimate intentional quirks can be documented in this file separately once confirmed.
+- `WSUpgradeRequest` / `WSUpgradeResponse` expose a mixed bytes/str API and this is public API.
+  Request `method`, `path`, `version` and response `version` are low-level protocol bytes, while headers are decoded strings and response `status` is `HTTPStatus`.
+  Do not change this shape casually in core or silently normalize it away in wrappers; treat it as a stable compatibility constraint unless an intentional breaking change is agreed.
+- In `picows` core, once a CLOSE frame has been sent, later send-side API calls are effectively no-ops.
+  This applies to `send_close()` as well as the other send methods.
+  Also, `disconnect()` and `wait_disconnected()` are safe to call multiple times.
+  Wrapper code should rely on these idempotency guarantees instead of adding its own state-based suppression around shutdown operations.
 
 ## Testing instructions
 - Run lint after updating code with:

docs/source/reference.rst

@@ -146,8 +146,6 @@ Classes
     .. py:attribute:: payload_size
         :type: size_t
 
-        **Available only from Cython.**
-
         Size of the payload.
 
 .. autoclass:: WSUpgradeRequest

examples/echo_client_websockets.py

@@ -0,0 +1,14 @@
+import asyncio
+
+from picows import websockets
+
+
+async def main():
+    async with websockets.connect("ws://127.0.0.1:9001") as websocket:
+        await websocket.send("Hello world")
+        reply = await websocket.recv()
+        print(f"Echo reply: {reply}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

picows/picows.pxd

@@ -67,7 +67,7 @@ cdef class MemoryBuffer:
 cdef class WSFrame:
     cdef:
         char* payload_ptr
-        Py_ssize_t payload_size
+        readonly Py_ssize_t payload_size
         readonly Py_ssize_t tail_size
         readonly WSMsgType msg_type
         readonly uint8_t fin

picows/picows.pyx

@@ -47,7 +47,7 @@ class _NotImplemented(Exception):
     pass
 
 
-# "unlikely" works only gcc, but still nice to have
+# "unlikely" works only for gcc, but still nice to have
 # https://github.com/cython/cython/issues/7667
 cdef extern from *:
     cdef bint unlikely(bint val) noexcept
@@ -668,6 +668,8 @@ cdef class WSTransport:
 
             if self.close_handshake is None:
                 self.close_handshake = <WSCloseHandshake>WSCloseHandshake.__new__(WSCloseHandshake)
+                self.close_handshake.recv = None
+                self.close_handshake.sent = None
                 self.close_handshake.recv_then_sent = False
 
             self.close_handshake.sent = <WSCloseInfo>WSCloseInfo.__new__(WSCloseInfo)
@@ -1648,7 +1650,8 @@ cdef class WSProtocol(WSProtocolBase, asyncio.BufferedProtocol):
                 self._f_payload_start_pos = self._f_curr_state_start_pos
                 self._state = WSParserState.READ_PAYLOAD
 
-            if self._f_payload_length > self._max_frame_size:
+            if (self._f_payload_length > self._max_frame_size and
+                    self._f_msg_type not in (WSMsgType.PING, WSMsgType.PONG, WSMsgType.CLOSE)):
                 raise WSProtocolError(
                     WSCloseCode.MESSAGE_TOO_BIG,
                     f"Received frame with payload size exceeding max allowed size, "

picows/websockets/__init__.py

@@ -0,0 +1,100 @@
+from . import exceptions
+from .asyncio.client import connect
+from .asyncio.connection import ClientConnection, ServerConnection, process_exception
+from .asyncio.router import route
+from .asyncio.server import Server, ServerHandshakeConnection, basic_auth, broadcast, serve
+from .compat import CloseCode, Request, Response, State
+from .exceptions import (
+    ConcurrencyError,
+    ConnectionClosed,
+    ConnectionClosedError,
+    ConnectionClosedOK,
+    DuplicateParameter,
+    InvalidHandshake,
+    InvalidHeader,
+    InvalidHeaderFormat,
+    InvalidHeaderValue,
+    InvalidMessage,
+    InvalidOrigin,
+    InvalidParameterName,
+    InvalidParameterValue,
+    InvalidProxy,
+    InvalidProxyMessage,
+    InvalidProxyStatus,
+    InvalidState,
+    InvalidStatus,
+    InvalidUpgrade,
+    InvalidURI,
+    NegotiationError,
+    PayloadTooBig,
+    ProtocolError,
+    ProxyError,
+    SecurityError,
+    WebSocketException,
+)
+from .typing import (
+    BytesLike,
+    Data,
+    DataLike,
+    ExtensionName,
+    ExtensionParameter,
+    HeadersLike,
+    LoggerLike,
+    Origin,
+    StatusLike,
+    Subprotocol,
+)
+
+__all__ = [
+    "BytesLike",
+    "ClientConnection",
+    "CloseCode",
+    "Data",
+    "DataLike",
+    "Server",
+    "ServerHandshakeConnection",
+    "ServerConnection",
+    "ConcurrencyError",
+    "ConnectionClosed",
+    "ConnectionClosedError",
+    "ConnectionClosedOK",
+    "DuplicateParameter",
+    "ExtensionName",
+    "ExtensionParameter",
+    "HeadersLike",
+    "InvalidHandshake",
+    "InvalidHeader",
+    "InvalidHeaderFormat",
+    "InvalidHeaderValue",
+    "InvalidMessage",
+    "InvalidOrigin",
+    "InvalidParameterName",
+    "InvalidParameterValue",
+    "InvalidProxy",
+    "InvalidProxyMessage",
+    "InvalidProxyStatus",
+    "InvalidState",
+    "InvalidStatus",
+    "InvalidUpgrade",
+    "InvalidURI",
+    "LoggerLike",
+    "NegotiationError",
+    "Origin",
+    "PayloadTooBig",
+    "ProtocolError",
+    "ProxyError",
+    "Request",
+    "Response",
+    "SecurityError",
+    "State",
+    "StatusLike",
+    "Subprotocol",
+    "WebSocketException",
+    "basic_auth",
+    "broadcast",
+    "connect",
+    "exceptions",
+    "process_exception",
+    "route",
+    "serve",
+]

picows/websockets/asyncio/__init__.py

@@ -0,0 +1,18 @@
+from .client import connect
+from .connection import ClientConnection, ServerConnection, process_exception
+from .router import route
+from .server import Server, ServerHandshakeConnection, basic_auth, broadcast, serve
+from ..compat import State
+
+__all__ = [
+    "ClientConnection",
+    "Server",
+    "ServerHandshakeConnection",
+    "ServerConnection",
+    "basic_auth",
+    "broadcast",
+    "connect",
+    "process_exception",
+    "route",
+    "serve",
+]