wsbuilder 1.0.3__tar.gz → 1.2.0__tar.gz

{wsbuilder-1.0.3/src/wsbuilder.egg-info → wsbuilder-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wsbuilder
-Version: 1.0.3
+Version: 1.2.0
 Summary: Lightweight HTTP + WebSocket framework for Python.
 Author: wsbuilder Authors
 License-Expression: MIT

{wsbuilder-1.0.3 → wsbuilder-1.2.0}/docs/advanced.md

@@ -13,11 +13,15 @@ limites de transporte, instancia el servidor:
 from wsbuilder import App, HTTPServer
 
 app = App()
-server = HTTPServer("127.0.0.1", 8765, app)
-server.MAX_CONNECTION_WORKERS = 128
-server.MAX_REQUEST_HEADER_BYTES = 128 * 1024
-server.MAX_REQUEST_BODY_BYTES = 4 * 1024 * 1024
-server.REQUEST_READ_TIMEOUT_SECONDS = 15.0
+server = HTTPServer(
+    "127.0.0.1",
+    8765,
+    app,
+    max_connection_workers=128,
+    max_request_header_bytes=128 * 1024,
+    max_request_body_bytes=4 * 1024 * 1024,
+    request_read_timeout=15.0,
+)
 server.serve_forever()
 ```
 

{wsbuilder-1.0.3 → wsbuilder-1.2.0}/docs/app-http.md

@@ -250,19 +250,68 @@ Limites por defecto:
 | `MAX_REQUEST_HEADER_BYTES` | `64 KiB` |
 | `MAX_REQUEST_BODY_BYTES` | `2 MiB` |
 | `REQUEST_READ_TIMEOUT_SECONDS` | `10.0` segundos |
+| `KEEPALIVE_TIMEOUT_SECONDS` | `5.0` segundos entre peticiones |
+| `MAX_KEEPALIVE_REQUESTS` | `100` peticiones por conexion |
+| `MAX_CONCURRENT_STREAMS` | `100` streams HTTP/2 |
 | `ACCEPT_TIMEOUT_SECONDS` | `0.5` segundos |
+| `GRACEFUL_SHUTDOWN_TIMEOUT_SECONDS` | `10.0` segundos de espera al apagar |
+| `HANDLE_SIGTERM` | `True`: `SIGTERM` detiene el servidor de forma ordenada |
+| `MAX_WS_FRAME_BYTES` / `MAX_WS_MESSAGE_BYTES` | `None`: usa los `2 MiB` de `wsbuilder.ws` |
 
-Para cambiarlos, instancia `HTTPServer` manualmente y ajusta atributos antes de
-llamar `serve_forever()`.
+Se cambian con argumentos al crear el servidor, en `app.run()` o desde la CLI.
+Un valor invalido (cero workers, timeout `0`, tamano negativo) lanza
+`ValueError`; una clave desconocida, `TypeError`.
 
 ```python
 from wsbuilder import HTTPServer
 
-server = HTTPServer("127.0.0.1", 8765, app)
-server.MAX_REQUEST_BODY_BYTES = 4 * 1024 * 1024
+server = HTTPServer(
+    "127.0.0.1",
+    8765,
+    app,
+    max_connection_workers=128,
+    max_request_body_bytes=4 * 1024 * 1024,
+    keepalive_timeout=2.0,
+)
 server.serve_forever()
+
+# equivalente
+app.run("127.0.0.1", 8765, max_request_body_bytes=4 * 1024 * 1024)
+```
+
+| Argumento | Atributo | CLI |
+| --- | --- | --- |
+| `max_connection_workers` | `MAX_CONNECTION_WORKERS` | `--max-workers` |
+| `max_request_header_bytes` | `MAX_REQUEST_HEADER_BYTES` | `--max-header-bytes` |
+| `max_request_body_bytes` | `MAX_REQUEST_BODY_BYTES` | `--max-body-bytes` |
+| `request_read_timeout` | `REQUEST_READ_TIMEOUT_SECONDS` | `--request-timeout` |
+| `keepalive_timeout` | `KEEPALIVE_TIMEOUT_SECONDS` | `--keepalive-timeout` |
+| `max_keepalive_requests` | `MAX_KEEPALIVE_REQUESTS` | `--max-keepalive-requests` |
+| `max_concurrent_streams` | `MAX_CONCURRENT_STREAMS` | |
+| `graceful_shutdown_timeout` | `GRACEFUL_SHUTDOWN_TIMEOUT_SECONDS` | `--shutdown-timeout` |
+| `max_ws_frame_bytes` | `MAX_WS_FRAME_BYTES` | |
+| `max_ws_message_bytes` | `MAX_WS_MESSAGE_BYTES` | `--max-ws-message-bytes` |
+
+```bash
+python -m wsbuilder --max-workers 128 --max-body-bytes 4194304 --shutdown-timeout 5
 ```
 
+Asignar los atributos (`server.MAX_REQUEST_BODY_BYTES = ...`) sigue funcionando.
+
+### Apagado ordenado
+
+`server.stop()`, `Ctrl+C` y `SIGTERM` (el que envian Docker, systemd o
+Kubernetes) siguen el mismo camino:
+
+1. se deja de aceptar conexiones nuevas;
+2. las peticiones en curso terminan y se responden con `Connection: close`;
+3. el servidor espera a esas conexiones hasta `GRACEFUL_SHUTDOWN_TIMEOUT_SECONDS`;
+4. por ultimo se llama a `app.close()`.
+
+`SIGTERM` solo se captura cuando `serve_forever()` corre en el hilo principal;
+el manejador anterior se restaura al terminar. `server.active_connections()`
+devuelve cuantas conexiones siguen abiertas.
+
 ### Ciclo de vida
 
 Para levantar el servidor desde otro hilo (tests, embebido en otra app):

{wsbuilder-1.0.3 → wsbuilder-1.2.0}/docs/observability.md

@@ -65,6 +65,30 @@ logger.event("server_start", host="0.0.0.0", port=8765)
 
 `NDJSONLog` escribe un evento por linea y funciona bien para ingest para herramientas externas.
 
+### Mensajes del framework
+
+Los avisos y errores del propio framework (handlers que fallan, errores TLS,
+arranque y apagado del servidor) pasan por `wsbuilder.logs`:
+
+- sin `enable_logs()`, salen por **stderr** como `[evento] mensaje`; los errores
+  incluyen el traceback completo;
+- con `enable_logs()`, cada mensaje se guarda en el NDJSON con `ts`, `level`,
+  `event`, `message` y, si hubo excepcion, `error.type`, `error.message` y
+  `error.traceback`. Los de nivel `warning` o superior tambien se muestran por
+  stderr.
+
+```python
+logger = app.enable_logs(path="logs/wsbuilder.ndjson", console_level="error")
+logger.info("deploy", "version publicada", version="1.0.3")
+logger.exception("pagos", "fallo el cobro", exc)
+
+from wsbuilder.logs import console
+console.level = "warning"  # sin enable_logs: oculta los mensajes info
+```
+
+Niveles: `debug`, `info`, `warning`, `error`. `console_level=None` deja los
+mensajes solo en el archivo.
+
 ## Docs nativas
 
 `App.enable_docs()` publica una vista HTML y un endpoint JSON con `App.describe()`.

{wsbuilder-1.0.3 → wsbuilder-1.2.0}/docs/websocket.md

@@ -11,11 +11,25 @@ WSBuilder incluye handshake, framing y una clase `WebSocket` para manejar la con
     idle_timeout=15.0,
     keepalive_interval=5.0,
     pong_timeout=3.0,
+    max_message_bytes=256 * 1024,
 )
 def handler(ws, _request):
     ...
 ```
 
+### Limites de tamano
+
+| Opcion | Por defecto | Efecto |
+| --- | --- | --- |
+| `max_frame_bytes` | `2 MiB` | frame mas grande aceptado |
+| `max_message_bytes` | `2 MiB` | mensaje reensamblado mas grande; tambien limita cada frame |
+
+Si un cliente los supera, la conexion se cierra con el codigo `1009`
+(*Message Too Big*) y `recv_frame()` lanza `WebSocketMessageTooBigError`
+(subclase de `WebSocketProtocolError`). Para fijar el limite de todas las
+rutas usa `HTTPServer(..., max_ws_frame_bytes=..., max_ws_message_bytes=...)`;
+el valor de la ruta tiene prioridad sobre el del servidor.
+
 ## Handshake
 
 La funcion `handshake_websocket_with_options()` valida:

{wsbuilder-1.0.3 → wsbuilder-1.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "wsbuilder"
-version = "1.0.3"
+version = "1.2.0"
 description = "Lightweight HTTP + WebSocket framework for Python."
 readme = "README.md"
 requires-python = ">=3.11"

{wsbuilder-1.0.3 → wsbuilder-1.2.0}/src/wsbuilder/__init__.py

@@ -126,7 +126,7 @@ def __getattr__(name):
 def __dir__():
     return sorted(set(globals()) | _PKI_EXPORTS)
 
-__version__ = "1.0.3"
+__version__ = "1.2.0"
 
 __all__ = [
     "App",

{wsbuilder-1.0.3 → wsbuilder-1.2.0}/src/wsbuilder/__main__.py

@@ -184,16 +184,42 @@ def build_demo_app():
     return app
 
 
+#: CLI flag -> HTTPServer limit keyword, type and help.
+CLI_LIMITS = (
+    ("--max-workers", "max_connection_workers", int, "conexiones atendidas a la vez"),
+    ("--max-header-bytes", "max_request_header_bytes", int, "tamano maximo de cabeceras"),
+    ("--max-body-bytes", "max_request_body_bytes", int, "tamano maximo del body"),
+    ("--request-timeout", "request_read_timeout", float, "segundos para leer una peticion"),
+    ("--keepalive-timeout", "keepalive_timeout", float, "segundos de espera entre peticiones"),
+    ("--max-keepalive-requests", "max_keepalive_requests", int, "peticiones por conexion (0 = sin limite)"),
+    ("--shutdown-timeout", "graceful_shutdown_timeout", float, "segundos de espera al apagar"),
+    ("--max-ws-message-bytes", "max_ws_message_bytes", int, "tamano maximo de un mensaje WebSocket"),
+)
+
+
 def main():
     parser = argparse.ArgumentParser(
         description="Levanta un servidor demo HTTP + WebSocket de wsbuilder"
     )
     parser.add_argument("--host", default=DEFAULT_HOST, help="Host de escucha")
     parser.add_argument("--port", type=int, default=DEFAULT_PORT, help="Puerto de escucha")
+    limits = parser.add_argument_group("limites del servidor (por defecto los de HTTPServer)")
+    for flag, option, kind, help_text in CLI_LIMITS:
+        metavar = "SEG" if kind is float else "N"
+        limits.add_argument(
+            flag, dest=option, type=kind, default=None, metavar=metavar, help=help_text
+        )
     args = parser.parse_args()
 
+    server_options = {option: getattr(args, option) for _flag, option, _kind, _help in CLI_LIMITS}
     app = build_demo_app()
-    app.run(args.host, args.port)
+    try:
+        app.run(args.host, args.port, **server_options)
+    except ValueError as exc:
+        message = str(exc)
+        for flag, option, _kind, _help in CLI_LIMITS:
+            message = message.replace(option, flag)
+        parser.error(message)
 
 
 if __name__ == "__main__":

{wsbuilder-1.0.3 → wsbuilder-1.2.0}/src/wsbuilder/app.py

@@ -9,6 +9,7 @@ from html import escape as html_escape
 from .constants import DEFAULT_CORS_ALLOW_ORIGIN
 from .cookies import build_set_cookie, get_cookie
 from .http import Response
+from .logs import get_log
 from .tasks import TaskManager
 from .ws import _normalize_protocols
 
@@ -576,6 +577,8 @@ class App:
         on_timeout=None,
         io_poll_interval=1.0,
         ping_payload=b"",
+        max_frame_bytes=None,
+        max_message_bytes=None,
     ):
         normalized_path = str(path or "")
         if not normalized_path.startswith("/") or any(
@@ -592,6 +595,9 @@ class App:
         )
         if len(normalized_ping_payload) > 125:
             raise ValueError("WebSocket ping payload must be at most 125 bytes")
+        for name, limit in (("max_frame_bytes", max_frame_bytes), ("max_message_bytes", max_message_bytes)):
+            if limit is not None and int(limit) < 1:
+                raise ValueError(f"WebSocket {name} must be at least 1 byte")
 
         def decorator(func):
             self.ws_routes[normalized_path] = {
@@ -606,6 +612,8 @@ class App:
                 "on_timeout": on_timeout,
                 "io_poll_interval": float(io_poll_interval or 1.0),
                 "ping_payload": normalized_ping_payload,
+                "max_frame_bytes": None if max_frame_bytes is None else int(max_frame_bytes),
+                "max_message_bytes": None if max_message_bytes is None else int(max_message_bytes),
             }
             return func
 
@@ -711,7 +719,13 @@ class App:
             **kwargs,
         )
 
-    def enable_logs(self, path="logs/wsbuilder.ndjson", attr_name="logs", ensure_parent=True):
+    def enable_logs(
+        self,
+        path="logs/wsbuilder.ndjson",
+        attr_name="logs",
+        ensure_parent=True,
+        console_level="warning",
+    ):
         from .logs import install_logs
 
         return install_logs(
@@ -719,6 +733,7 @@ class App:
             path=path,
             attr_name=attr_name,
             ensure_parent=ensure_parent,
+            console_level=console_level,
         )
 
     def describe(self):
@@ -1302,7 +1317,9 @@ class App:
         except _RouteExecutionError as e:
             return Response.text(e.message, status=e.status)
         except Exception as e:
-            print(f"[http] handler error {request.method} {request.path}: {e}")
+            get_log(self).exception(
+                "http", f"handler error {request.method} {request.path}: {e}", e
+            )
             if route.kind == "api":
                 headers = {}
                 if cors_allow_origin:
@@ -1356,8 +1373,9 @@ class App:
 
         return resp
 
-    def run(self, host, port, ssl_context=None):
+    def run(self, host, port, ssl_context=None, **server_options):
+        """Serve the app; ``server_options`` are ``HTTPServer`` limit keywords."""
         from .server import HTTPServer
 
-        server = HTTPServer(host, port, self, ssl_context=ssl_context)
+        server = HTTPServer(host, port, self, ssl_context=ssl_context, **server_options)
         server.serve_forever()

{wsbuilder-1.0.3 → wsbuilder-1.2.0}/src/wsbuilder/db_replicas.py

@@ -6,6 +6,8 @@ import sqlite3
 import threading
 from dataclasses import dataclass
 
+from .logs import get_log
+
 
 @dataclass
 class SQLite3OptimizationConfig:
@@ -267,7 +269,7 @@ class OptimizedDatabase:
 
     def _log(self, *parts):
         if self.debug:
-            print("[DB]", *parts)
+            get_log().info("db", " ".join(str(part) for part in parts))
 
     def _get_tx_depth(self) -> int:
         return getattr(self._tx_depth, "value", 0)

{wsbuilder-1.0.3 → wsbuilder-1.2.0}/src/wsbuilder/framework.py

@@ -55,6 +55,7 @@ from .ws import (
     WebSocket,
     WebSocketConnectionClosedError,
     WebSocketFrame,
+    WebSocketMessageTooBigError,
     WebSocketProtocolError,
     WebSocketReadError,
     WebSocketReadTimeoutError,
@@ -134,6 +135,7 @@ __all__ = [
     "WebSocketReadTimeoutError",
     "WebSocketConnectionClosedError",
     "WebSocketProtocolError",
+    "WebSocketMessageTooBigError",
     "DEFAULT_CORS_ALLOW_ORIGIN",
     "MAGIC_WS",
     "STATUS_MESSAGES",

{wsbuilder-1.0.3 → wsbuilder-1.2.0}/src/wsbuilder/http.py

@@ -4,6 +4,7 @@ from urllib.parse import parse_qsl
 
 from .constants import STATUS_MESSAGES
 from .headers import validate_header_name, validate_header_value
+from .logs import get_log
 
 MAX_QUERY_FIELDS = 1024
 HTTP_0_9 = "HTTP/0.9"
@@ -231,7 +232,7 @@ def send_http_response(conn, response, *, send_body=True, keep_alive=False, vers
             else:
                 conn.sendall(response.body)
         except Exception as e:
-            print(f"[http] send error {status_code}: {e}")
+            get_log().warning("http", f"send error {status_code}: {e}")
         return
     reason = validate_header_value(
         response.reason or STATUS_MESSAGES.get(status_code, "Unknown")
@@ -290,7 +291,7 @@ def send_http_response(conn, response, *, send_body=True, keep_alive=False, vers
         else:
             conn.sendall(response.body)
     except Exception as e:
-        print(f"[http] send error {status_code}: {e}")
+        get_log().warning("http", f"send error {status_code}: {e}")
 
 
 def _iter_stream_chunks(source):

{wsbuilder-1.0.3 → wsbuilder-1.2.0}/src/wsbuilder/http2.py

@@ -14,6 +14,8 @@ it would desynchronise the decoder for every later stream.
 import struct
 
 from .hpack import Decoder, Encoder, HPACKError
+from .http import Response
+from .logs import get_log
 
 #: RFC 9113 section 3.4. A client opens with this exact octet sequence.
 CONNECTION_PREFACE = b"PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n"
@@ -239,6 +241,8 @@ class Stream:
         #: Body the peer's window has no room for yet.
         self.pending_output = bytearray()
         self.pending_end_stream = False
+        #: Set once the body outgrew the server limit and a 413 went out.
+        self.body_rejected = False
 
     @property
     def closed(self):
@@ -317,8 +321,12 @@ class Http2Connection:
     exercised in tests without a socket.
     """
 
-    def __init__(self, conn, app, *, tls=None, client_address=("", 0), max_streams=100):
+    def __init__(
+        self, conn, app, *, tls=None, client_address=("", 0), max_streams=100, max_body_bytes=None
+    ):
         self.conn = conn
+        #: Largest request body buffered per stream; None leaves it unbounded.
+        self.max_body_bytes = None if max_body_bytes is None else int(max_body_bytes)
         self.app = app
         self.tls = tls or {}
         self.client_address = client_address
@@ -577,6 +585,8 @@ class Http2Connection:
         stream.open_remote(end_stream)
         if end_stream:
             self._dispatch(stream)
+        elif self._declared_length_exceeds_limit(headers):
+            self._reject_body(stream)
 
     def _on_data(self, frame):
         self._require_stream_id(frame, False)
@@ -598,6 +608,15 @@ class Http2Connection:
             raise StreamError("DATA on a stream that is not open", frame.stream_id,
                               ERROR_STREAM_CLOSED)
         stream.inbound.consume(received)
+        if stream.body_rejected:
+            # The 413 is already on its way; the rest of the body is dropped
+            # and its window is not handed back.
+            if frame.has(FLAG_END_STREAM):
+                stream.end_remote()
+            return
+        if self.max_body_bytes is not None and len(stream.body) + len(payload) > self.max_body_bytes:
+            self._reject_body(stream)
+            return
         stream.body.extend(payload)
         if received:
             self._send(Frame(FRAME_WINDOW_UPDATE, 0, stream.id, struct.pack(">I", received)))
@@ -606,6 +625,31 @@ class Http2Connection:
             stream.end_remote()
             self._dispatch(stream)
 
+    def _declared_length_exceeds_limit(self, headers):
+        if self.max_body_bytes is None:
+            return False
+        for name, value in headers:
+            if name == "content-length":
+                try:
+                    return int(value) > self.max_body_bytes
+                except ValueError:
+                    return False
+        return False
+
+    def _reject_body(self, stream):
+        """Answer 413 before the body is complete, then stop the upload.
+
+        RFC 9113 section 8.1 lets a server respond early and reset the
+        request stream with NO_ERROR so the client stops sending.
+        """
+        stream.body_rejected = True
+        stream.body = bytearray()
+        self.send_response(stream, Response.text("Payload Too Large", status=413))
+        if not stream.pending_output:
+            stream.state = CLOSED
+            stream.reset_code = ERROR_NO_ERROR
+            self.send_rst_stream(stream.id, ERROR_NO_ERROR)
+
     # -- request handling ----------------------------------------------
 
     def _dispatch(self, stream):
@@ -632,7 +676,7 @@ class Http2Connection:
         try:
             response = self.app.dispatch(request)
         except Exception as exc:  # noqa: BLE001 - reported on the stream
-            print(f"[http2] handler error on stream {stream.id}: {exc}")
+            get_log(self.app).exception("http2", f"handler error on stream {stream.id}: {exc}", exc)
             raise StreamError("handler failed", stream.id, ERROR_INTERNAL_ERROR) from exc
         self.send_response(stream, response, send_body=request.method != "HEAD")
 

{wsbuilder-1.0.3 → wsbuilder-1.2.0}/src/wsbuilder/http3.py

@@ -43,6 +43,8 @@ SETTINGS_QPACK_BLOCKED_STREAMS = 0x07
 #: RFC 9220: lets a client send ``CONNECT`` with a ``:protocol`` pseudo-header,
 #: which is how WebSocket runs over HTTP/3.
 SETTINGS_ENABLE_CONNECT_PROTOCOL = 0x08
+#: Largest header block we accept, advertised in SETTINGS.
+MAX_FIELD_SECTION_SIZE = 65536
 
 H3_NO_ERROR = 0x0100
 H3_GENERAL_PROTOCOL_ERROR = 0x0101
@@ -171,10 +173,17 @@ def validate_request_headers(headers):
 
 
 class RequestStream:
-    """One request/response exchange on a bidirectional QUIC stream."""
+    """One request/response exchange on a bidirectional QUIC stream.
 
-    def __init__(self, stream_id):
+    With ``max_body_bytes`` set, a body (or a half-received frame) that
+    outgrows it is dropped and ``body_rejected`` is set so the server can
+    answer 413; the rest of the stream is then discarded.
+    """
+
+    def __init__(self, stream_id, max_body_bytes=None):
         self.id = int(stream_id)
+        self.max_body_bytes = None if max_body_bytes is None else int(max_body_bytes)
+        self.body_rejected = False
         self.buffer = bytearray()
         self.headers = None
         self.body = bytearray()
@@ -186,17 +195,37 @@ class RequestStream:
 
     def feed(self, data, fin=False):
         """Add stream bytes; returns True once the request is complete."""
+        if self.body_rejected:
+            self.finished = self.finished or bool(fin)
+            return False
         self.buffer.extend(data)
         frames, tail = parse_frames(self.buffer)
         self.buffer = bytearray(tail)
         for frame_type, payload in frames:
             self._on_frame(frame_type, payload)
+            if self.body_rejected:
+                return False
+        if self._buffer_limit() is not None and len(self.buffer) > self._buffer_limit():
+            # A frame that has not finished arriving can still outgrow memory.
+            self._reject_body()
+            return False
         if fin:
             self.finished = True
             if self.buffer:
                 raise H3Error("stream ended mid-frame", H3_FRAME_ERROR)
         return self.finished and self.headers is not None
 
+    def _buffer_limit(self):
+        if self.max_body_bytes is None:
+            return None
+        # Room for one whole field section or body, plus a frame header.
+        return max(self.max_body_bytes, MAX_FIELD_SECTION_SIZE) + 16
+
+    def _reject_body(self):
+        self.body_rejected = True
+        self.body = bytearray()
+        self.buffer = bytearray()
+
     def _on_frame(self, frame_type, payload):
         if frame_type == FRAME_HEADERS:
             try:
@@ -212,6 +241,13 @@ class RequestStream:
             if self.headers is None:
                 # Section 4.1: a request opens with HEADERS, always.
                 raise H3Error("DATA before HEADERS", H3_FRAME_UNEXPECTED)
+            if (
+                self.max_body_bytes is not None
+                and self.websocket is None
+                and len(self.body) + len(payload) > self.max_body_bytes
+            ):
+                self._reject_body()
+                return
             self.body.extend(payload)
             return
         if frame_type in (FRAME_SETTINGS, FRAME_GOAWAY, FRAME_MAX_PUSH_ID, FRAME_CANCEL_PUSH):
@@ -306,7 +342,7 @@ def build_control_stream(settings=None):
     values = {
         SETTINGS_QPACK_MAX_TABLE_CAPACITY: 0,
         SETTINGS_QPACK_BLOCKED_STREAMS: 0,
-        SETTINGS_MAX_FIELD_SECTION_SIZE: 65536,
+        SETTINGS_MAX_FIELD_SECTION_SIZE: MAX_FIELD_SECTION_SIZE,
         SETTINGS_ENABLE_CONNECT_PROTOCOL: 1,
     }
     if settings: