From 1742ba3f088c827af645ed0f38b45fb4814e0317 Mon Sep 17 00:00:00 2001 From: Michael Emperador Date: Fri, 21 Aug 2026 23:17:33 -0500 Subject: [PATCH 01/14] feat: add timeout-bounded regex routing --- README.md | 58 +++++++- benchmarks/route_benchmark.py | 50 +++++++ pyproject.toml | 1 + smallserver/__init__.py | 4 + smallserver/app.py | 60 +++++--- smallserver/http.py | 44 +++++- smallserver/routing.py | 265 ++++++++++++++++++++++++++++++++++ smallserver/server.py | 33 ++++- tests/test_http.py | 26 ++++ tests/test_regex_routing.py | 231 +++++++++++++++++++++++++++++ tests/test_routing.py | 16 ++ tests/test_server.py | 18 +++ tests/test_server_runtime.py | 37 +++++ 13 files changed, 810 insertions(+), 33 deletions(-) create mode 100644 benchmarks/route_benchmark.py create mode 100644 smallserver/routing.py create mode 100644 tests/test_regex_routing.py diff --git a/README.md b/README.md index 37cbe90..0992a4e 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,17 @@ # SmallServer SmallServer is a SmallOS-native web framework in early development. It provides -a bounded HTTP/1.1 server, static async routing for GET, POST, PUT, PATCH, and -DELETE, and explicit escape hatches for blocking and asyncio-native libraries. +a bounded HTTP/1.1 server and async routing for GET, POST, PUT, PATCH, and +DELETE. Static routes are built in, timeout-bounded regular-expression routes +are available through an optional dependency, and explicit escape hatches +support blocking and asyncio-native libraries. ## Current scope The current package provides an HTTP/1.1 baseline over a SmallOS runtime. It can: -- register static async routes for GET, POST, PUT, PATCH, and DELETE; +- register static or optional regular-expression async routes for GET, POST, + PUT, PATCH, and DELETE; - dispatch an already-created `Request` to a handler; - return deterministic `Response` values, including HTTP/1.1 bytes; - return 404 for an unknown path and 405 with `Allow` for a known path using @@ -18,7 +21,8 @@ The current package provides an HTTP/1.1 baseline over a SmallOS runtime. It can - parse one `Content-Length` HTTP/1.1 request per connection and close after its response. -Keep-alive/pipelining, TLS, path parameters, and HTTP/2 are not implemented yet. +Keep-alive/pipelining, TLS, automatic path templates, and HTTP/2 are not +implemented yet. ## Install for development @@ -28,6 +32,14 @@ python3 -m pip install -e . python3 -m unittest discover -s tests -v ``` +Install the optional matching engine when an application uses raw regex routes: + +```bash +python3 -m pip install -e '.[regex-routes]' +``` + +Static routing neither imports nor requires that dependency. + SmallOS is installed from the canonical `master` branch in `requirements.txt`. It owns scheduling, socket readiness, and foreign execution adapters. @@ -101,8 +113,42 @@ async def delete_widgets(request: Request) -> Response: return Response(status=204) ``` -Route paths are static in this release. Path parameters and richer lifecycle -hooks are deferred; the current `ServerHandle` provides explicit shutdown. +Static route lookup is dictionary-based and always takes precedence over a +regex route for the same method and path. Richer lifecycle hooks are deferred; +the current `ServerHandle` provides explicit shutdown. + +## Define regular-expression routes + +Regex routes use full-path matching and run in registration order after static +lookup. Only named captures become immutable `request.path_params`; an optional +group that did not participate is omitted. + +```python +@app.get_regex(r"/users/(?P[0-9]+)") +async def get_user(request: Request) -> Response: + return Response.json({"user_id": request.path_params["user_id"]}) + +@app.route_regex( + r"/articles/(?P[a-z0-9]+(?:-[a-z0-9]+)*)", + methods=("GET", "PATCH"), +) +async def article(request: Request) -> Response: + return Response.json({"slug": request.path_params["slug"]}) +``` + +Patterns must begin with a literal `/` and do not need `^` or `$`. They are +trusted application configuration, but paths are hostile input: SmallServer +bounds pattern length, route count, named captures, path bytes, each match, and +the total matching time. Prefer unambiguous repetition and narrow character +classes even with these deadlines. A timeout raises `RouteMatchTimeout` with an +opaque route ID and becomes a sanitized 500 response on the network path. + +Requests retain the exact ASCII origin-form target in `request.raw_target`. +Routing uses `request.path`, which excludes the query string; +`request.query_string` contains the raw text after `?`. Neither paths nor named +captures are percent-decoded, so `/files/a%2Fb` remains distinct from +`/files/a/b`. `request.route_pattern` identifies the selected static path or +regex pattern. ## Dispatch a request diff --git a/benchmarks/route_benchmark.py b/benchmarks/route_benchmark.py new file mode 100644 index 0000000..29bb1b2 --- /dev/null +++ b/benchmarks/route_benchmark.py @@ -0,0 +1,50 @@ +"""Small routing microbenchmark; run with ``python benchmarks/route_benchmark.py``.""" + +from __future__ import annotations + +import asyncio +import importlib.util +from pathlib import Path +import sys +import time + +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) + +from smallserver import Headers, RegexRouteConfig, Request, Response, RouteMatchTimeout, SmallServer + + +async def benchmark() -> None: + app = SmallServer() + + @app.get("/health") + async def health(request): + return Response() + + request = Request("GET", "/health", Headers()) + iterations = 25_000 + started = time.perf_counter() + for _ in range(iterations): + await app.dispatch(request) + static_elapsed = time.perf_counter() - started + print("static: {:.0f} dispatches/second".format(iterations / static_elapsed)) + + if importlib.util.find_spec("regex") is None: + print("regex: skipped (install smallserver[regex-routes])") + return + + bounded = SmallServer(RegexRouteConfig(match_timeout=0.002, total_match_timeout=0.005)) + + @bounded.get_regex(r"/(a+)+$") + async def hostile(request): + return Response() + + started = time.perf_counter() + try: + await bounded.dispatch(Request("GET", "/" + "a" * 5000 + "!", Headers())) + except RouteMatchTimeout: + pass + print("worst-case regex timeout: {:.4f}s".format(time.perf_counter() - started)) + + +if __name__ == "__main__": + asyncio.run(benchmark()) diff --git a/pyproject.toml b/pyproject.toml index 337debe..d78894a 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -14,6 +14,7 @@ dependencies = [] [project.optional-dependencies] dev = ["build>=1.2"] +regex-routes = ["regex>=2023.10.3"] [tool.setuptools.packages.find] include = ["smallserver*"] diff --git a/smallserver/__init__.py b/smallserver/__init__.py index a421318..e470f75 100644 --- a/smallserver/__init__.py +++ b/smallserver/__init__.py @@ -4,6 +4,7 @@ from .adapters import AdapterRegistry, AdapterShutdownError, http_error_from_adapter from .errors import HTTPError from .http import Headers, Request, Response +from .routing import RegexRouteConfig, RegexRoutesUnavailable, RouteMatchTimeout from .server import ServerConfig, ServerHandle __all__ = [ @@ -11,8 +12,11 @@ "AdapterShutdownError", "Headers", "HTTPError", + "RegexRouteConfig", + "RegexRoutesUnavailable", "Request", "Response", + "RouteMatchTimeout", "ServerConfig", "ServerHandle", "SmallServer", diff --git a/smallserver/app.py b/smallserver/app.py index 416542f..aabb735 100644 --- a/smallserver/app.py +++ b/smallserver/app.py @@ -4,40 +4,35 @@ import inspect from collections.abc import Awaitable, Callable, Iterable +from dataclasses import replace import socket from typing import Any from .errors import HTTPError from .http import Request, Response +from .routing import RegexRouteConfig, Router from .server import HTTPParseError, HTTPRequestParser, ServerConfig, ServerHandle Handler = Callable[[Request], Awaitable[Response]] -_METHODS = frozenset({"GET", "POST", "PUT", "PATCH", "DELETE"}) class SmallServer: """Register static HTTP routes and dispatch requests to async handlers.""" - def __init__(self) -> None: - self._routes: dict[tuple[str, str], Handler] = {} + def __init__(self, regex_config: RegexRouteConfig | None = None) -> None: + self._router = Router(regex_config) def route(self, path: str, methods: Iterable[str]) -> Callable[[Handler], Handler]: if not isinstance(path, str) or not path.startswith("/"): raise ValueError("route path must start with '/'") - normalized = tuple(dict.fromkeys(method.upper() for method in methods)) - if not normalized or any(method not in _METHODS for method in normalized): - raise ValueError("routes must use one or more supported HTTP methods") + if "?" in path or "#" in path: + raise ValueError("route path must not contain a query string or fragment") + normalized = self._router.normalize_methods(methods) def register(handler: Handler) -> Handler: if not callable(handler): raise TypeError("route handler must be callable") - keys = [(method, path) for method in normalized] - for method, key_path in keys: - key = (method, key_path) - if key in self._routes: - raise ValueError("route already registered: {} {}".format(method, path)) - for key in keys: - self._routes[key] = handler + self._router.add_static(path, normalized, handler) return handler return register @@ -57,6 +52,33 @@ def patch(self, path: str) -> Callable[[Handler], Handler]: def delete(self, path: str) -> Callable[[Handler], Handler]: return self.route(path, ("DELETE",)) + def route_regex(self, pattern: str, methods: Iterable[str]) -> Callable[[Handler], Handler]: + """Register a timeout-bounded full-path regular-expression route.""" + normalized = self._router.normalize_methods(methods) + + def register(handler: Handler) -> Handler: + if not callable(handler): + raise TypeError("route handler must be callable") + self._router.add_regex(pattern, normalized, handler) + return handler + + return register + + def get_regex(self, pattern: str) -> Callable[[Handler], Handler]: + return self.route_regex(pattern, ("GET",)) + + def post_regex(self, pattern: str) -> Callable[[Handler], Handler]: + return self.route_regex(pattern, ("POST",)) + + def put_regex(self, pattern: str) -> Callable[[Handler], Handler]: + return self.route_regex(pattern, ("PUT",)) + + def patch_regex(self, pattern: str) -> Callable[[Handler], Handler]: + return self.route_regex(pattern, ("PATCH",)) + + def delete_regex(self, pattern: str) -> Callable[[Handler], Handler]: + return self.route_regex(pattern, ("DELETE",)) + def serve( self, runtime: Any, @@ -110,12 +132,13 @@ def serve( async def dispatch(self, request: Request) -> Response: """Run a registered handler or return a deterministic HTTP response.""" - handler = self._routes.get((request.method.upper(), request.path)) - if handler is None: - allowed = sorted(method for method, path in self._routes if path == request.path) - if allowed: - return Response.text("method not allowed", status=405, headers={"Allow": ", ".join(allowed)}) + match = self._router.resolve(request.method, request.path) + if match.handler is None: + if match.allowed_methods: + return Response.text("method not allowed", status=405, headers={"Allow": ", ".join(match.allowed_methods)}) return Response.text("not found", status=404) + handler = match.handler + request = replace(request, path_params=match.path_params, route_pattern=match.route_pattern) try: result = handler(request) if not inspect.isawaitable(result): @@ -169,6 +192,7 @@ async def _connection_loop(self, task: Any, handle: ServerHandle, client: socket handle._config.max_header_bytes, handle._config.max_header_count, handle._config.max_body_bytes, + handle._config.max_request_target_bytes, ) try: while not handle.closed: diff --git a/smallserver/http.py b/smallserver/http.py index 42b43c8..f90afbd 100644 --- a/smallserver/http.py +++ b/smallserver/http.py @@ -3,14 +3,25 @@ from __future__ import annotations from collections.abc import Iterable, Iterator, Mapping -from dataclasses import dataclass +from dataclasses import dataclass, field import json import re from types import MappingProxyType from typing import Any _TOKEN = re.compile(r"^[!#$%&'*+.^_`|~0-9A-Za-z-]+$") -_REASONS = {200: "OK", 201: "Created", 204: "No Content", 400: "Bad Request", 404: "Not Found", 405: "Method Not Allowed", 413: "Payload Too Large", 500: "Internal Server Error", 503: "Service Unavailable"} +_REASONS = { + 200: "OK", + 201: "Created", + 204: "No Content", + 400: "Bad Request", + 404: "Not Found", + 405: "Method Not Allowed", + 413: "Payload Too Large", + 414: "URI Too Long", + 500: "Internal Server Error", + 503: "Service Unavailable", +} class Headers(Mapping[str, str]): @@ -60,16 +71,45 @@ class Request: headers: Headers body: bytes = b"" version: str = "HTTP/1.1" + raw_target: str | None = None + query_string: str = "" + path_params: Mapping[str, str] = field(default_factory=dict) + route_pattern: str | None = None def __post_init__(self) -> None: if not _TOKEN.fullmatch(self.method): raise ValueError("invalid HTTP method") + if not isinstance(self.query_string, str): + raise TypeError("query_string must be a string") + if self.raw_target is None and "?" not in self.path and self.query_string: + raw_target = self.path + "?" + self.query_string + else: + raw_target = self.path if self.raw_target is None else self.raw_target + if not isinstance(raw_target, str) or not raw_target.startswith("/"): + raise ValueError("request path/target must start with '/'") + target_path, separator, target_query = raw_target.partition("?") + if self.raw_target is None: + if self.query_string and self.query_string != (target_query if separator else ""): + raise ValueError("request target fields are inconsistent") + object.__setattr__(self, "path", target_path) + object.__setattr__(self, "query_string", target_query if separator else "") + object.__setattr__(self, "raw_target", raw_target) + elif self.path != target_path or self.query_string != (target_query if separator else ""): + raise ValueError("request target fields are inconsistent") if not self.path.startswith("/"): raise ValueError("request path must start with '/'") if not isinstance(self.headers, Headers): object.__setattr__(self, "headers", Headers(self.headers)) if not isinstance(self.body, bytes): raise TypeError("request body must be bytes") + if not isinstance(self.path_params, Mapping): + raise TypeError("path_params must be a mapping") + params = dict(self.path_params) + if any(not isinstance(name, str) or not isinstance(value, str) for name, value in params.items()): + raise TypeError("path_params must map strings to strings") + object.__setattr__(self, "path_params", MappingProxyType(params)) + if self.route_pattern is not None and not isinstance(self.route_pattern, str): + raise TypeError("route_pattern must be a string or None") @dataclass(frozen=True) diff --git a/smallserver/routing.py b/smallserver/routing.py new file mode 100644 index 0000000..a6c9eff --- /dev/null +++ b/smallserver/routing.py @@ -0,0 +1,265 @@ +"""Deterministic static and timeout-bounded regular-expression routing.""" + +from __future__ import annotations + +from collections.abc import Awaitable, Callable, Iterable, Mapping +from dataclasses import dataclass +import importlib +import math +import time +from types import MappingProxyType +from typing import Any + +from .http import Request, Response + +Handler = Callable[[Request], Awaitable[Response]] +SUPPORTED_METHODS = frozenset({"GET", "POST", "PUT", "PATCH", "DELETE"}) + + +class RegexRoutesUnavailable(RuntimeError): + """Raised when regex routes are used without their optional dependency.""" + + +class RouteMatchTimeout(RuntimeError): + """Raised when a bounded regex route match exceeds its deadline.""" + + def __init__(self, route_id: str) -> None: + self.route_id = route_id + super().__init__("regular-expression route matching timed out ({})".format(route_id)) + + +@dataclass(frozen=True) +class RegexRouteConfig: + """Finite limits applied to regex registration and hostile request paths.""" + + max_path_bytes: int = 8 * 1024 + max_pattern_length: int = 1024 + max_routes: int = 100 + match_timeout: float = 0.01 + total_match_timeout: float = 0.05 + max_named_captures: int = 20 + + def __post_init__(self) -> None: + for name in ("max_path_bytes", "max_pattern_length", "max_routes", "max_named_captures"): + value = getattr(self, name) + if type(value) is not int or value <= 0: + raise ValueError("{} must be a positive integer".format(name)) + for name in ("match_timeout", "total_match_timeout"): + value = getattr(self, name) + if type(value) not in (int, float) or not math.isfinite(value) or value <= 0: + raise ValueError("{} must be a finite positive number".format(name)) + + +@dataclass(frozen=True) +class RouteMatch: + handler: Handler | None + path_params: Mapping[str, str] + route_pattern: str | None + allowed_methods: tuple[str, ...] = () + + +@dataclass(frozen=True) +class _RegexRoute: + route_id: str + pattern: str + compiled: Any + handlers: Mapping[str, Handler] + literal_prefix: str + + +class Router: + """Resolve static and ordered regex routes without slowing static lookup.""" + + def __init__(self, regex_config: RegexRouteConfig | None = None) -> None: + self._static: dict[tuple[str, str], Handler] = {} + self._regex: list[_RegexRoute] = [] + self._regex_by_pattern: dict[str, int] = {} + self.regex_config = regex_config or RegexRouteConfig() + + @staticmethod + def normalize_methods(methods: Iterable[str]) -> tuple[str, ...]: + try: + normalized = tuple(dict.fromkeys(method.upper() for method in methods)) + except AttributeError as exc: + raise ValueError("routes must use one or more supported HTTP methods") from exc + if not normalized or any(method not in SUPPORTED_METHODS for method in normalized): + raise ValueError("routes must use one or more supported HTTP methods") + return normalized + + def add_static(self, path: str, methods: tuple[str, ...], handler: Handler) -> None: + keys = [(method, path) for method in methods] + for key in keys: + if key in self._static: + raise ValueError("route already registered: {} {}".format(key[0], path)) + for key in keys: + self._static[key] = handler + + def add_regex(self, pattern: str, methods: tuple[str, ...], handler: Handler) -> None: + if not isinstance(pattern, str): + raise TypeError("regex route pattern must be a string") + existing_index = self._regex_by_pattern.get(pattern) + if existing_index is not None: + existing = self._regex[existing_index] + duplicate = next((method for method in methods if method in existing.handlers), None) + if duplicate is not None: + raise ValueError("regex route already registered: {}".format(duplicate)) + handlers = dict(existing.handlers) + handlers.update((method, handler) for method in methods) + self._regex[existing_index] = _RegexRoute( + existing.route_id, + existing.pattern, + existing.compiled, + MappingProxyType(handlers), + existing.literal_prefix, + ) + return + + if len(self._regex) >= self.regex_config.max_routes: + raise ValueError("maximum registered regex routes exceeded") + compiled = self._compile(pattern) + route = _RegexRoute( + "regex-route-{}".format(len(self._regex) + 1), + pattern, + compiled, + MappingProxyType({method: handler for method in methods}), + _literal_prefix(pattern), + ) + self._regex_by_pattern[pattern] = len(self._regex) + self._regex.append(route) + + def resolve(self, method: str, path: str) -> RouteMatch: + method = method.upper() + static = self._static.get((method, path)) + if static is not None: + return RouteMatch(static, MappingProxyType({}), path) + + if not self._regex: + allowed = tuple(sorted(method for method, registered_path in self._static if registered_path == path)) + return RouteMatch(None, MappingProxyType({}), None, allowed) + self._validate_path(path) + deadline = time.monotonic() + self.regex_config.total_match_timeout + cached: dict[int, Any] = {} + for index, route in enumerate(self._regex): + if method not in route.handlers: + continue + match = self._match(route, path, deadline) + cached[index] = match + if match is not None: + return RouteMatch( + route.handlers[method], + MappingProxyType(_captures(match)), + route.pattern, + ) + + allowed = {registered_method for registered_method, registered_path in self._static if registered_path == path} + for index, route in enumerate(self._regex): + match = cached.get(index) + if index not in cached: + match = self._match(route, path, deadline) + if match is not None: + allowed.update(route.handlers) + return RouteMatch(None, MappingProxyType({}), None, tuple(sorted(allowed))) + + def _compile(self, pattern: str) -> Any: + if not isinstance(pattern, str): + raise TypeError("regex route pattern must be a string") + if not pattern.startswith("/"): + raise ValueError("regex route pattern must start with a literal '/'") + if len(pattern) > self.regex_config.max_pattern_length: + raise ValueError("regex route pattern is too long") + names = _named_group_names(pattern) + if len(names) != len(set(names)): + raise ValueError("regex route pattern contains duplicate named groups") + if len(names) > self.regex_config.max_named_captures: + raise ValueError("regex route pattern has too many named captures") + try: + engine = importlib.import_module("regex") + except ImportError as exc: + raise RegexRoutesUnavailable( + "regular-expression routes require 'smallserver[regex-routes]'" + ) from exc + try: + compiled = engine.compile(pattern) + except Exception: + raise ValueError("invalid regex route pattern") from None + try: + empty_match = compiled.fullmatch("", timeout=self.regex_config.match_timeout) + except TimeoutError as exc: + raise ValueError("regex route pattern validation timed out") from exc + if empty_match is not None: + raise ValueError("regex route pattern must not match an empty path") + return compiled + + def _validate_path(self, path: str) -> None: + try: + size = len(path.encode("ascii")) + except UnicodeEncodeError as exc: + raise ValueError("request path must contain ASCII characters only") from exc + if size > self.regex_config.max_path_bytes: + raise ValueError("request path is too large for routing") + + def _match(self, route: _RegexRoute, path: str, deadline: float) -> Any: + remaining = deadline - time.monotonic() + if remaining <= 0: + raise RouteMatchTimeout(route.route_id) + if len(route.literal_prefix) > 1 and not path.startswith(route.literal_prefix): + return None + timeout = min(float(self.regex_config.match_timeout), remaining) + try: + return route.compiled.fullmatch(path, timeout=timeout) + except TimeoutError as exc: + raise RouteMatchTimeout(route.route_id) from exc + + +def _captures(match: Any) -> dict[str, str]: + return {name: value for name, value in match.groupdict().items() if value is not None} + + +def _literal_prefix(pattern: str) -> str: + """Return only the leading literals that are safe to use as a rejection index.""" + special = frozenset(".[](){}*+?|^$\\") + end = 0 + while end < len(pattern) and pattern[end] not in special: + end += 1 + return pattern[:end] + + +def _named_group_names(pattern: str) -> list[str]: + """Find named-group declarations while ignoring escapes and character classes.""" + names: list[str] = [] + escaped = False + in_class = False + index = 0 + while index < len(pattern): + character = pattern[index] + if escaped: + escaped = False + index += 1 + continue + if character == "\\": + escaped = True + index += 1 + continue + if character == "[": + in_class = True + index += 1 + continue + if character == "]" and in_class: + in_class = False + index += 1 + continue + marker_length = 0 + if not in_class and pattern.startswith("(?P<", index): + marker_length = 4 + elif not in_class and pattern.startswith("(?<", index): + next_character = pattern[index + 3 : index + 4] + if next_character not in ("=", "!"): + marker_length = 3 + if marker_length: + end = pattern.find(">", index + marker_length) + if end >= 0: + names.append(pattern[index + marker_length : end]) + index = end + 1 + continue + index += 1 + return names diff --git a/smallserver/server.py b/smallserver/server.py index 09701fe..a3510d6 100644 --- a/smallserver/server.py +++ b/smallserver/server.py @@ -21,10 +21,17 @@ def __init__(self, status: int, detail: str) -> None: class HTTPRequestParser: """Incrementally parse one bounded HTTP/1.1 request with Content-Length.""" - def __init__(self, max_header_bytes: int, max_header_count: int, max_body_bytes: int) -> None: + def __init__( + self, + max_header_bytes: int, + max_header_count: int, + max_body_bytes: int, + max_request_target_bytes: int = 8 * 1024, + ) -> None: self._max_header_bytes = max_header_bytes self._max_header_count = max_header_count self._max_body_bytes = max_body_bytes + self._max_request_target_bytes = max_request_target_bytes self._buffer = bytearray() self._request_head: tuple[str, str, Headers, int] | None = None @@ -42,13 +49,22 @@ def feed(self, data: bytes) -> Request | None: self._request_head = self._parse_head(bytes(self._buffer[:marker])) del self._buffer[:header_length] - method, path, headers, content_length = self._request_head + method, raw_target, headers, content_length = self._request_head if len(self._buffer) > content_length: raise HTTPParseError(400, "pipelined requests are not supported") if len(self._buffer) < content_length: return None try: - return Request(method, path, headers, bytes(self._buffer), "HTTP/1.1") + path, separator, query_string = raw_target.partition("?") + return Request( + method, + path, + headers, + bytes(self._buffer), + "HTTP/1.1", + raw_target=raw_target, + query_string=query_string if separator else "", + ) except ValueError as exc: raise HTTPParseError(400, str(exc)) from exc @@ -59,10 +75,12 @@ def _parse_head(self, raw: bytes) -> tuple[str, str, Headers, int]: raise HTTPParseError(400, "request headers are not valid bytes") from exc if not lines or len(lines[0].split(" ")) != 3: raise HTTPParseError(400, "malformed request line") - method, path, version = lines[0].split(" ") - if version != "HTTP/1.1" or not path.startswith("/"): + method, raw_target, version = lines[0].split(" ") + if version != "HTTP/1.1" or not raw_target.startswith("/"): raise HTTPParseError(400, "only origin-form HTTP/1.1 requests are supported") - if "#" in path or any(not 0x21 <= ord(character) <= 0x7E for character in path): + if len(raw_target.encode("iso-8859-1")) > self._max_request_target_bytes: + raise HTTPParseError(414, "request target is too large") + if "#" in raw_target or any(not 0x21 <= ord(character) <= 0x7E for character in raw_target): raise HTTPParseError(400, "request target is not valid origin-form") if len(lines) - 1 > self._max_header_count: raise HTTPParseError(413, "too many request headers") @@ -94,7 +112,7 @@ def _parse_head(self, raw: bytes) -> tuple[str, str, Headers, int]: raise HTTPParseError(413, "request body is too large") if not headers.get("host"): raise HTTPParseError(400, "HTTP/1.1 requests require a Host header") - return method, path, headers, length + return method, raw_target, headers, length @dataclass(frozen=True) @@ -105,6 +123,7 @@ class ServerConfig: max_header_bytes: int = 16 * 1024 max_header_count: int = 100 max_body_bytes: int = 1024 * 1024 + max_request_target_bytes: int = 8 * 1024 receive_chunk_bytes: int = 8 * 1024 listener_priority: int = 1 connection_priority: int = 2 diff --git a/tests/test_http.py b/tests/test_http.py index 841d1ee..95679a6 100644 --- a/tests/test_http.py +++ b/tests/test_http.py @@ -1,4 +1,5 @@ import unittest +from types import MappingProxyType from smallserver import Headers, Request, Response @@ -31,3 +32,28 @@ def test_header_values_match_the_wire_encoding(self) -> None: with self.subTest(invalid=invalid): with self.assertRaisesRegex(ValueError, "header value"): Headers({"X-Test": invalid}) + + def test_request_splits_raw_target_and_keeps_captures_immutable(self) -> None: + request = Request( + "GET", + "/items?tag=a%2Fb&empty=", + Headers(), + path_params={"item_id": "a%2Fb"}, + route_pattern=r"/items/(?P[^/]+)", + ) + self.assertEqual(request.raw_target, "/items?tag=a%2Fb&empty=") + self.assertEqual(request.path, "/items") + self.assertEqual(request.query_string, "tag=a%2Fb&empty=") + self.assertIsInstance(request.path_params, MappingProxyType) + with self.assertRaises(TypeError): + request.path_params["item_id"] = "changed" # type: ignore[index] + + def test_request_rejects_inconsistent_explicit_target_fields(self) -> None: + with self.assertRaisesRegex(ValueError, "inconsistent"): + Request("GET", "/one", Headers(), raw_target="/two") + + def test_request_can_be_built_from_separate_path_and_query(self) -> None: + request = Request("GET", "/items", Headers(), query_string="page=2") + self.assertEqual(request.raw_target, "/items?page=2") + self.assertEqual(request.path, "/items") + self.assertEqual(request.query_string, "page=2") diff --git a/tests/test_regex_routing.py b/tests/test_regex_routing.py new file mode 100644 index 0000000..fba24b4 --- /dev/null +++ b/tests/test_regex_routing.py @@ -0,0 +1,231 @@ +import importlib.util +import time +import unittest +from unittest.mock import patch + +from smallserver import ( + Headers, + RegexRouteConfig, + RegexRoutesUnavailable, + Request, + Response, + RouteMatchTimeout, + SmallServer, +) + + +HAS_REGEX = importlib.util.find_spec("regex") is not None + + +class OptionalRegexDependencyTests(unittest.TestCase): + def test_static_routes_do_not_import_optional_engine(self) -> None: + app = SmallServer() + + async def handler(request): + return Response() + + with patch("smallserver.routing.importlib.import_module", side_effect=AssertionError("imported")): + app.get("/health")(handler) + + def test_registration_explains_missing_extra(self) -> None: + app = SmallServer() + + async def handler(request): + return Response() + + with patch("smallserver.routing.importlib.import_module", side_effect=ImportError): + with self.assertRaisesRegex(RegexRoutesUnavailable, r"smallserver\[regex-routes\]"): + app.get_regex(r"/users/[0-9]+")(handler) + + +@unittest.skipUnless(HAS_REGEX, "regex-routes extra is not installed") +class RegexRoutingTests(unittest.IsolatedAsyncioTestCase): + async def test_named_captures_are_immutable_and_optional_groups_are_omitted(self) -> None: + app = SmallServer() + seen = [] + + @app.get_regex(r"/users/(?P[0-9]+)(?:/(?P
[a-z]+))?") + async def user(request): + seen.append(request) + return Response.json(dict(request.path_params)) + + response = await app.dispatch(Request("GET", "/users/42?debug=1", Headers())) + self.assertEqual(response.body, b'{"user_id":"42"}') + self.assertEqual(seen[0].raw_target, "/users/42?debug=1") + self.assertEqual(seen[0].query_string, "debug=1") + self.assertEqual(seen[0].route_pattern, r"/users/(?P[0-9]+)(?:/(?P
[a-z]+))?") + with self.assertRaises(TypeError): + seen[0].path_params["user_id"] = "1" # type: ignore[index] + await app.dispatch(Request("GET", "/users/43/profile", Headers())) + self.assertEqual(dict(seen[0].path_params), {"user_id": "42"}) + self.assertEqual(dict(seen[1].path_params), {"user_id": "43", "section": "profile"}) + + async def test_captures_preserve_percent_encoded_octets(self) -> None: + app = SmallServer() + + @app.get_regex(r"/files/(?P[^/]+)") + async def file(request): + return Response.text(request.path_params["name"]) + + response = await app.dispatch(Request("GET", "/files/a%2Fb", Headers())) + self.assertEqual(response.body, b"a%2Fb") + + async def test_static_precedence_and_regex_registration_order(self) -> None: + app = SmallServer() + + @app.get_regex(r"/items/(?P.+)") + async def broad(request): + return Response.text("broad") + + @app.get_regex(r"/items/(?P[0-9]+)") + async def narrow(request): + return Response.text("narrow") + + @app.get("/items/7") + async def exact(request): + return Response.text("static") + + self.assertEqual((await app.dispatch(Request("GET", "/items/7", Headers()))).body, b"static") + self.assertEqual((await app.dispatch(Request("GET", "/items/8", Headers()))).body, b"broad") + + async def test_method_first_matching_and_sorted_allow(self) -> None: + app = SmallServer() + + @app.post("/records/1") + async def static_post(request): + return Response.text("post") + + @app.delete_regex(r"/records/(?P[0-9]+)") + async def regex_delete(request): + return Response.text("delete") + + @app.get_regex(r"/records/(?P.+)") + async def regex_get(request): + return Response.text("get") + + self.assertEqual((await app.dispatch(Request("GET", "/records/1", Headers()))).body, b"get") + response = await app.dispatch(Request("PATCH", "/records/1", Headers())) + self.assertEqual(response.status, 405) + self.assertEqual(response.headers["allow"], "DELETE, GET, POST") + + async def test_all_regex_method_decorators_dispatch(self) -> None: + app = SmallServer() + for method in ("get", "post", "put", "patch", "delete"): + decorator = getattr(app, method + "_regex") + + @decorator("/" + method + r"/(?P[0-9]+)") + async def handler(request, expected=method): + return Response.text(expected + request.path_params["value"]) + + for method in ("get", "post", "put", "patch", "delete"): + response = await app.dispatch(Request(method.upper(), "/" + method + "/2", Headers())) + self.assertEqual(response.body, (method + "2").encode()) + + async def test_same_pattern_disjoint_methods_merge_and_duplicates_are_atomic(self) -> None: + app = SmallServer() + + async def first(request): + return Response.text("first") + + async def second(request): + return Response.text("second") + + app.get_regex(r"/merged/(?P[0-9]+)")(first) + app.post_regex(r"/merged/(?P[0-9]+)")(second) + with self.assertRaisesRegex(ValueError, "already registered"): + app.route_regex(r"/merged/(?P[0-9]+)", ("PATCH", "GET"))(second) + self.assertEqual((await app.dispatch(Request("PATCH", "/merged/1", Headers()))).status, 405) + self.assertEqual((await app.dispatch(Request("POST", "/merged/1", Headers()))).body, b"second") + + def test_registration_limits_and_invalid_patterns(self) -> None: + async def handler(request): + return Response() + + cases = ( + (r"items/[0-9]+", "literal '/'"), + (r"/[", "invalid"), + (r"/(?Px)(?Py)", "duplicate"), + ) + for pattern, message in cases: + with self.subTest(pattern=pattern): + with self.assertRaisesRegex((ValueError, TypeError), message): + SmallServer().get_regex(pattern)(handler) + + with self.assertRaisesRegex(ValueError, "too long"): + SmallServer(RegexRouteConfig(max_pattern_length=4)).get_regex("/long")(handler) + with self.assertRaisesRegex(ValueError, "too many"): + SmallServer(RegexRouteConfig(max_named_captures=1)).get_regex( + r"/(?Px)(?Py)" + )(handler) + limited = SmallServer(RegexRouteConfig(max_routes=1)) + limited.get_regex(r"/one")(handler) + with self.assertRaisesRegex(ValueError, "maximum"): + limited.get_regex(r"/two")(handler) + + async def test_catastrophic_backtracking_is_bounded_and_path_is_not_disclosed(self) -> None: + app = SmallServer(RegexRouteConfig(match_timeout=0.001, total_match_timeout=0.005)) + + @app.get_regex(r"/(a+)+$") + async def handler(request): + return Response() + + hostile_path = "/" + "a" * 5000 + "!" + started = time.monotonic() + with self.assertRaises(RouteMatchTimeout) as raised: + await app.dispatch(Request("GET", hostile_path, Headers())) + elapsed = time.monotonic() - started + self.assertLess(elapsed, 0.25) + self.assertNotIn(hostile_path, str(raised.exception)) + self.assertEqual(raised.exception.route_id, "regex-route-1") + + async def test_total_budget_bounds_many_individually_fast_misses(self) -> None: + class SlowPattern: + def fullmatch(self, value, timeout): + if not value: + return None + time.sleep(min(timeout / 2, 0.001)) + return None + + class Engine: + @staticmethod + def compile(pattern): + return SlowPattern() + + app = SmallServer( + RegexRouteConfig(max_routes=20, match_timeout=0.01, total_match_timeout=0.003) + ) + + async def handler(request): + return Response() + + with patch("smallserver.routing.importlib.import_module", return_value=Engine()): + for index in range(10): + app.get_regex("/(?:route-{}).*".format(index))(handler) + started = time.monotonic() + with self.assertRaises(RouteMatchTimeout): + await app.dispatch(Request("GET", "/route", Headers())) + self.assertLess(time.monotonic() - started, 0.05) + + async def test_manual_dispatch_path_limit_is_enforced_before_matching(self) -> None: + app = SmallServer(RegexRouteConfig(max_path_bytes=8)) + + @app.get_regex(r"/.*") + async def handler(request): + return Response() + + with self.assertRaisesRegex(ValueError, "too large"): + await app.dispatch(Request("GET", "/12345678", Headers())) + + +class RegexRouteConfigTests(unittest.TestCase): + def test_rejects_nonfinite_or_nonpositive_limits(self) -> None: + for kwargs in ( + {"max_routes": 0}, + {"max_routes": True}, + {"match_timeout": 0}, + {"match_timeout": float("inf")}, + {"total_match_timeout": float("nan")}, + ): + with self.subTest(kwargs=kwargs): + with self.assertRaises(ValueError): + RegexRouteConfig(**kwargs) diff --git a/tests/test_routing.py b/tests/test_routing.py index 19da695..d152500 100644 --- a/tests/test_routing.py +++ b/tests/test_routing.py @@ -30,6 +30,20 @@ async def items(request): self.assertEqual(response.status, 405) self.assertEqual(response.headers["allow"], "GET") + async def test_query_string_does_not_participate_in_static_matching(self) -> None: + app = SmallServer() + seen = [] + + @app.get("/items") + async def items(request): + seen.append(request) + return Response() + + response = await app.dispatch(Request("GET", "/items?tag=a%2Fb", Headers())) + self.assertEqual(response.status, 200) + self.assertEqual(seen[0].path, "/items") + self.assertEqual(seen[0].query_string, "tag=a%2Fb") + async def test_http_error_becomes_response(self) -> None: app = SmallServer() @@ -61,6 +75,8 @@ async def one(request): app.get("/one")(one) with self.assertRaisesRegex(ValueError, "supported HTTP methods"): app.route("/trace", ("TRACE",)) + with self.assertRaisesRegex(ValueError, "query string"): + app.get("/one?debug=1") async def test_failed_multi_method_registration_is_atomic(self) -> None: app = SmallServer() diff --git a/tests/test_server.py b/tests/test_server.py index bf6e193..27b1766 100644 --- a/tests/test_server.py +++ b/tests/test_server.py @@ -35,11 +35,29 @@ def test_requires_host_and_rejects_invalid_origin_form(self) -> None: with self.assertRaisesRegex(HTTPParseError, "origin-form"): self.parser().feed(b"GET /items#fragment HTTP/1.1\r\nHost: localhost\r\n\r\n") + def test_splits_query_without_decoding_or_normalizing_path(self) -> None: + request = self.parser().feed( + b"GET /items/a%2Fb?tag=x%20y HTTP/1.1\r\nHost: localhost\r\n\r\n" + ) + self.assertIsNotNone(request) + assert request is not None + self.assertEqual(request.raw_target, "/items/a%2Fb?tag=x%20y") + self.assertEqual(request.path, "/items/a%2Fb") + self.assertEqual(request.query_string, "tag=x%20y") + + def test_enforces_request_target_limit_independently(self) -> None: + parser = HTTPRequestParser(256, 2, 32, max_request_target_bytes=8) + with self.assertRaisesRegex(HTTPParseError, "request target") as raised: + parser.feed(b"GET /12345678 HTTP/1.1\r\nHost: x\r\n\r\n") + self.assertEqual(raised.exception.status, 414) + def test_config_rejects_unbounded_limits(self) -> None: with self.assertRaisesRegex(ValueError, "max_connections"): ServerConfig(max_connections=0) with self.assertRaisesRegex(ValueError, "max_connections"): ServerConfig(max_connections=True) + with self.assertRaisesRegex(ValueError, "max_request_target_bytes"): + ServerConfig(max_request_target_bytes=0) def test_serve_closes_bound_socket_when_runtime_fork_fails(self) -> None: class Listener: diff --git a/tests/test_server_runtime.py b/tests/test_server_runtime.py index 2bfa26b..9d80992 100644 --- a/tests/test_server_runtime.py +++ b/tests/test_server_runtime.py @@ -1,3 +1,4 @@ +import importlib.util import socket import threading import unittest @@ -8,6 +9,9 @@ from smallserver import AdapterRegistry, Response, SmallServer +HAS_REGEX = importlib.util.find_spec("regex") is not None + + class SmallOSServerIntegrationTests(unittest.TestCase): def _request(self, port: int, path: str) -> bytes: with socket.create_connection(("127.0.0.1", port), timeout=3) as connection: @@ -127,3 +131,36 @@ def fast_client() -> None: self.assertEqual(errors, []) self.assertIn(b"\r\n\r\nfast done", responses["fast"]) self.assertIn(b"\r\n\r\nslow done", responses["slow"]) + + @unittest.skipUnless(HAS_REGEX, "regex-routes extra is not installed") + def test_loopback_regex_route_uses_path_without_query(self) -> None: + runtime = SmallOS().setKernel(Unix()) + app = SmallServer() + + @app.get_regex(r"/files/(?P[^/]+)") + async def file(request): + return Response.text(request.path_params["name"] + "?" + request.query_string) + + try: + server = app.serve(runtime, host="127.0.0.1", port=0) + except PermissionError: + self.skipTest("the current sandbox does not permit loopback TCP binds") + + received = [] + errors = [] + + def client() -> None: + try: + received.append(self._request(server.port, "/files/a%2Fb?download=1")) + except BaseException as exc: + errors.append(exc) + finally: + server.close() + + worker = threading.Thread(target=client, daemon=True) + worker.start() + runtime.start() + worker.join(timeout=2) + self.assertFalse(worker.is_alive()) + self.assertEqual(errors, []) + self.assertIn(b"\r\n\r\na%2Fb?download=1", b"".join(received)) From 8625d569f734890a79a371e053f10867d0743e41 Mon Sep 17 00:00:00 2001 From: Michael Emperador Date: Fri, 21 Aug 2026 23:37:26 -0500 Subject: [PATCH 02/14] fix: harden regex routing after review --- README.md | 31 +++++++++- benchmarks/route_benchmark.py | 58 ++++++++++++++--- pyproject.toml | 2 +- smallserver/__init__.py | 3 +- smallserver/app.py | 30 ++++++++- smallserver/routing.py | 110 +++++++++++++++++++++------------ smallserver/server.py | 2 +- tests/installed_regex_smoke.py | 21 +++++++ tests/test_regex_routing.py | 89 ++++++++++++++++++++++++-- tests/test_server.py | 11 ++++ tests/test_server_runtime.py | 85 ++++++++++++++++++++++++- tests/typing/regex_routes.py | 20 ++++++ 12 files changed, 399 insertions(+), 63 deletions(-) create mode 100644 tests/installed_regex_smoke.py create mode 100644 tests/typing/regex_routes.py diff --git a/README.md b/README.md index 0992a4e..991183c 100644 --- a/README.md +++ b/README.md @@ -136,13 +136,30 @@ async def article(request: Request) -> Response: return Response.json({"slug": request.path_params["slug"]}) ``` -Patterns must begin with a literal `/` and do not need `^` or `$`. They are -trusted application configuration, but paths are hostile input: SmallServer +Patterns must begin with a literal `/` and do not need `^` or `$`. SmallServer +wraps the complete expression in a slash guard, so every top-level alternative +is constrained to an origin-form path. They are trusted application +configuration, but paths are hostile input: SmallServer bounds pattern length, route count, named captures, path bytes, each match, and the total matching time. Prefer unambiguous repetition and narrow character classes even with these deadlines. A timeout raises `RouteMatchTimeout` with an opaque route ID and becomes a sanitized 500 response on the network path. +Applications can observe that failure without receiving the hostile target: + +```python +from smallserver import RouteMatchTimeout + +def observe_route_error(error: RouteMatchTimeout) -> None: + logger.error("route matching failed: %s", error.route_id) + +app = SmallServer(route_error_observer=observe_route_error) +``` + +The synchronous observer runs once on the connection task and should return +quickly; observer failures are isolated from the response path. A path above +the configured regex-routing byte limit returns 414 before matching begins. + Requests retain the exact ASCII origin-form target in `request.raw_target`. Routing uses `request.path`, which excludes the query string; `request.query_string` contains the raw text after `?`. Neither paths nor named @@ -150,6 +167,16 @@ captures are percent-decoded, so `/files/a%2Fb` remains distinct from `/files/a/b`. `request.route_pattern` identifies the selected static path or regex pattern. +Run `python benchmarks/route_benchmark.py` for a same-process comparison of +the pre-router dictionary dispatch model and current router dispatch. Its JSON +also records configured versus observed hostile-pattern timeout when the extra +is installed; rates are machine-specific and should be compared on the same +host. + +Release validation can run `python tests/installed_regex_smoke.py` from an +environment where the built `smallserver[regex-routes]` wheel is installed. +The project requires Python 3.10 or newer. + ## Dispatch a request The listener creates requests and calls `dispatch()`. The same boundary is diff --git a/benchmarks/route_benchmark.py b/benchmarks/route_benchmark.py index 29bb1b2..a3b247e 100644 --- a/benchmarks/route_benchmark.py +++ b/benchmarks/route_benchmark.py @@ -1,9 +1,12 @@ -"""Small routing microbenchmark; run with ``python benchmarks/route_benchmark.py``.""" +"""Repeatable routing comparison; run with ``python benchmarks/route_benchmark.py``.""" from __future__ import annotations +import argparse import asyncio import importlib.util +import inspect +import json from pathlib import Path import sys import time @@ -13,7 +16,19 @@ from smallserver import Headers, RegexRouteConfig, Request, Response, RouteMatchTimeout, SmallServer -async def benchmark() -> None: +async def _legacy_dispatch(routes, request): + """Model the pre-router static dictionary dispatch for same-run comparison.""" + handler = routes[(request.method.upper(), request.path)] + result = handler(request) + if not inspect.isawaitable(result): + raise TypeError("benchmark handler must be awaitable") + response = await result + if not isinstance(response, Response): + raise TypeError("benchmark handler must return Response") + return response + + +async def benchmark(iterations: int) -> dict[str, float | int | str]: app = SmallServer() @app.get("/health") @@ -21,16 +36,30 @@ async def health(request): return Response() request = Request("GET", "/health", Headers()) - iterations = 25_000 + legacy_routes = {("GET", "/health"): health} + + started = time.perf_counter() + for _ in range(iterations): + await _legacy_dispatch(legacy_routes, request) + legacy_elapsed = time.perf_counter() - started + started = time.perf_counter() for _ in range(iterations): await app.dispatch(request) - static_elapsed = time.perf_counter() - started - print("static: {:.0f} dispatches/second".format(iterations / static_elapsed)) + router_elapsed = time.perf_counter() - started + + legacy_rate = iterations / legacy_elapsed + router_rate = iterations / router_elapsed + result: dict[str, float | int | str] = { + "iterations": iterations, + "legacy_static_dispatches_per_second": round(legacy_rate, 2), + "router_static_dispatches_per_second": round(router_rate, 2), + "router_to_legacy_ratio": round(router_rate / legacy_rate, 4), + } if importlib.util.find_spec("regex") is None: - print("regex: skipped (install smallserver[regex-routes])") - return + result["regex"] = "skipped; install smallserver[regex-routes]" + return result bounded = SmallServer(RegexRouteConfig(match_timeout=0.002, total_match_timeout=0.005)) @@ -43,8 +72,19 @@ async def hostile(request): await bounded.dispatch(Request("GET", "/" + "a" * 5000 + "!", Headers())) except RouteMatchTimeout: pass - print("worst-case regex timeout: {:.4f}s".format(time.perf_counter() - started)) + result["configured_regex_match_timeout_seconds"] = 0.002 + result["observed_worst_case_regex_seconds"] = round(time.perf_counter() - started, 6) + return result + + +def main() -> None: + parser = argparse.ArgumentParser() + parser.add_argument("--iterations", type=int, default=25_000) + arguments = parser.parse_args() + if arguments.iterations <= 0: + parser.error("--iterations must be positive") + print(json.dumps(asyncio.run(benchmark(arguments.iterations)), indent=2, sort_keys=True)) if __name__ == "__main__": - asyncio.run(benchmark()) + main() diff --git a/pyproject.toml b/pyproject.toml index d78894a..ced2d56 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -14,7 +14,7 @@ dependencies = [] [project.optional-dependencies] dev = ["build>=1.2"] -regex-routes = ["regex>=2023.10.3"] +regex-routes = ["regex>=2023.10.3,<2027"] [tool.setuptools.packages.find] include = ["smallserver*"] diff --git a/smallserver/__init__.py b/smallserver/__init__.py index e470f75..476d64e 100644 --- a/smallserver/__init__.py +++ b/smallserver/__init__.py @@ -4,7 +4,7 @@ from .adapters import AdapterRegistry, AdapterShutdownError, http_error_from_adapter from .errors import HTTPError from .http import Headers, Request, Response -from .routing import RegexRouteConfig, RegexRoutesUnavailable, RouteMatchTimeout +from .routing import RegexRouteConfig, RegexRoutesUnavailable, RouteMatchTimeout, RoutePathTooLarge from .server import ServerConfig, ServerHandle __all__ = [ @@ -17,6 +17,7 @@ "Request", "Response", "RouteMatchTimeout", + "RoutePathTooLarge", "ServerConfig", "ServerHandle", "SmallServer", diff --git a/smallserver/app.py b/smallserver/app.py index aabb735..a009025 100644 --- a/smallserver/app.py +++ b/smallserver/app.py @@ -10,17 +10,26 @@ from .errors import HTTPError from .http import Request, Response -from .routing import RegexRouteConfig, Router +from .routing import RegexRouteConfig, RouteMatchTimeout, RoutePathTooLarge, Router from .server import HTTPParseError, HTTPRequestParser, ServerConfig, ServerHandle Handler = Callable[[Request], Awaitable[Response]] +RouteErrorObserver = Callable[[RouteMatchTimeout], None] class SmallServer: """Register static HTTP routes and dispatch requests to async handlers.""" - def __init__(self, regex_config: RegexRouteConfig | None = None) -> None: + def __init__( + self, + regex_config: RegexRouteConfig | None = None, + *, + route_error_observer: RouteErrorObserver | None = None, + ) -> None: + if route_error_observer is not None and not callable(route_error_observer): + raise TypeError("route_error_observer must be callable or None") self._router = Router(regex_config) + self._route_error_observer = route_error_observer def route(self, path: str, methods: Iterable[str]) -> Callable[[Handler], Handler]: if not isinstance(path, str) or not path.startswith("/"): @@ -132,7 +141,10 @@ def serve( async def dispatch(self, request: Request) -> Response: """Run a registered handler or return a deterministic HTTP response.""" - match = self._router.resolve(request.method, request.path) + try: + match = self._router.resolve(request.method, request.path) + except RoutePathTooLarge: + return Response.text("request target is too large", status=414) if match.handler is None: if match.allowed_methods: return Response.text("method not allowed", status=405, headers={"Allow": ", ".join(match.allowed_methods)}) @@ -214,6 +226,9 @@ async def _connection_loop(self, task: Any, handle: ServerHandle, client: socket continue try: response = await self.dispatch(request) + except RouteMatchTimeout as exc: + self._observe_route_error(exc) + response = Response.text("internal server error", status=500) except Exception: response = Response.text("internal server error", status=500) await self._send_response(task, client, response) @@ -239,3 +254,12 @@ async def _send_response(self, task: Any, client: socket.socket, response: Respo if sent <= 0: return offset += sent + + def _observe_route_error(self, error: RouteMatchTimeout) -> None: + observer = self._route_error_observer + if observer is None: + return + try: + observer(error) + except Exception: + pass diff --git a/smallserver/routing.py b/smallserver/routing.py index a6c9eff..b53588d 100644 --- a/smallserver/routing.py +++ b/smallserver/routing.py @@ -6,6 +6,7 @@ from dataclasses import dataclass import importlib import math +import re import time from types import MappingProxyType from typing import Any @@ -28,6 +29,10 @@ def __init__(self, route_id: str) -> None: super().__init__("regular-expression route matching timed out ({})".format(route_id)) +class RoutePathTooLarge(RuntimeError): + """Raised before matching when a request path exceeds its routing bound.""" + + @dataclass(frozen=True) class RegexRouteConfig: """Finite limits applied to regex registration and hostile request paths.""" @@ -64,7 +69,6 @@ class _RegexRoute: pattern: str compiled: Any handlers: Mapping[str, Handler] - literal_prefix: str class Router: @@ -110,7 +114,6 @@ def add_regex(self, pattern: str, methods: tuple[str, ...], handler: Handler) -> existing.pattern, existing.compiled, MappingProxyType(handlers), - existing.literal_prefix, ) return @@ -122,7 +125,6 @@ def add_regex(self, pattern: str, methods: tuple[str, ...], handler: Handler) -> pattern, compiled, MappingProxyType({method: handler for method in methods}), - _literal_prefix(pattern), ) self._regex_by_pattern[pattern] = len(self._regex) self._regex.append(route) @@ -167,11 +169,6 @@ def _compile(self, pattern: str) -> Any: raise ValueError("regex route pattern must start with a literal '/'") if len(pattern) > self.regex_config.max_pattern_length: raise ValueError("regex route pattern is too long") - names = _named_group_names(pattern) - if len(names) != len(set(names)): - raise ValueError("regex route pattern contains duplicate named groups") - if len(names) > self.regex_config.max_named_captures: - raise ValueError("regex route pattern has too many named captures") try: engine = importlib.import_module("regex") except ImportError as exc: @@ -179,15 +176,17 @@ def _compile(self, pattern: str) -> Any: "regular-expression routes require 'smallserver[regex-routes]'" ) from exc try: - compiled = engine.compile(pattern) + compiled = engine.compile("(?=/)(?:{})".format(pattern)) except Exception: raise ValueError("invalid regex route pattern") from None - try: - empty_match = compiled.fullmatch("", timeout=self.regex_config.match_timeout) - except TimeoutError as exc: - raise ValueError("regex route pattern validation timed out") from exc - if empty_match is not None: - raise ValueError("regex route pattern must not match an empty path") + names = _named_group_names(pattern) + compiled_names = set(compiled.groupindex) + if set(names) != compiled_names: + raise ValueError("regex route named groups could not be validated") + if len(names) != len(compiled_names): + raise ValueError("regex route pattern contains duplicate named groups") + if len(compiled_names) > self.regex_config.max_named_captures: + raise ValueError("regex route pattern has too many named captures") return compiled def _validate_path(self, path: str) -> None: @@ -196,14 +195,12 @@ def _validate_path(self, path: str) -> None: except UnicodeEncodeError as exc: raise ValueError("request path must contain ASCII characters only") from exc if size > self.regex_config.max_path_bytes: - raise ValueError("request path is too large for routing") + raise RoutePathTooLarge("request path is too large for routing") def _match(self, route: _RegexRoute, path: str, deadline: float) -> Any: remaining = deadline - time.monotonic() if remaining <= 0: raise RouteMatchTimeout(route.route_id) - if len(route.literal_prefix) > 1 and not path.startswith(route.literal_prefix): - return None timeout = min(float(self.regex_config.match_timeout), remaining) try: return route.compiled.fullmatch(path, timeout=timeout) @@ -215,18 +212,10 @@ def _captures(match: Any) -> dict[str, str]: return {name: value for name, value in match.groupdict().items() if value is not None} -def _literal_prefix(pattern: str) -> str: - """Return only the leading literals that are safe to use as a rejection index.""" - special = frozenset(".[](){}*+?|^$\\") - end = 0 - while end < len(pattern) and pattern[end] not in special: - end += 1 - return pattern[:end] - - def _named_group_names(pattern: str) -> list[str]: - """Find named-group declarations while ignoring escapes and character classes.""" + """Find declarations while honoring regex comments and scoped verbose mode.""" names: list[str] = [] + verbose_stack = [False] escaped = False in_class = False index = 0 @@ -248,18 +237,59 @@ def _named_group_names(pattern: str) -> list[str]: in_class = False index += 1 continue - marker_length = 0 - if not in_class and pattern.startswith("(?P<", index): - marker_length = 4 - elif not in_class and pattern.startswith("(?<", index): - next_character = pattern[index + 3 : index + 4] - if next_character not in ("=", "!"): - marker_length = 3 - if marker_length: - end = pattern.find(">", index + marker_length) - if end >= 0: - names.append(pattern[index + marker_length : end]) - index = end + 1 + if not in_class and verbose_stack[-1] and character == "#": + newline = pattern.find("\n", index + 1) + index = len(pattern) if newline < 0 else newline + 1 + continue + if not in_class and pattern.startswith("(?#", index): + index = _comment_end(pattern, index + 3) + continue + if not in_class and character == "(": + flags = re.match(r"\(\?([A-Za-z]*)(?:-([A-Za-z]*))?([:)])", pattern[index:]) + if flags is not None: + enabled, disabled, delimiter = flags.groups() + verbose = (verbose_stack[-1] or "x" in enabled) and "x" not in (disabled or "") + index += flags.end() + if delimiter == ":": + verbose_stack.append(verbose) + else: + verbose_stack[-1] = verbose continue + marker_length = 0 + if pattern.startswith("(?P<", index): + marker_length = 4 + elif pattern.startswith("(?<", index): + next_character = pattern[index + 3 : index + 4] + if next_character not in ("=", "!"): + marker_length = 3 + if marker_length: + end = pattern.find(">", index + marker_length) + if end >= 0: + names.append(pattern[index + marker_length : end]) + verbose_stack.append(verbose_stack[-1]) + index = end + 1 + continue + verbose_stack.append(verbose_stack[-1]) + index += 1 + continue + if not in_class and character == ")": + if len(verbose_stack) > 1: + verbose_stack.pop() + index += 1 + continue index += 1 return names + + +def _comment_end(pattern: str, index: int) -> int: + escaped = False + while index < len(pattern): + character = pattern[index] + if escaped: + escaped = False + elif character == "\\": + escaped = True + elif character == ")": + return index + 1 + index += 1 + return index diff --git a/smallserver/server.py b/smallserver/server.py index a3510d6..9ef851d 100644 --- a/smallserver/server.py +++ b/smallserver/server.py @@ -123,10 +123,10 @@ class ServerConfig: max_header_bytes: int = 16 * 1024 max_header_count: int = 100 max_body_bytes: int = 1024 * 1024 - max_request_target_bytes: int = 8 * 1024 receive_chunk_bytes: int = 8 * 1024 listener_priority: int = 1 connection_priority: int = 2 + max_request_target_bytes: int = 8 * 1024 def __post_init__(self) -> None: for name, value in self.__dict__.items(): diff --git a/tests/installed_regex_smoke.py b/tests/installed_regex_smoke.py new file mode 100644 index 0000000..7689ff0 --- /dev/null +++ b/tests/installed_regex_smoke.py @@ -0,0 +1,21 @@ +"""Smoke an installed ``smallserver[regex-routes]`` package outside the source path.""" + +import asyncio + +from smallserver import Headers, Request, Response, SmallServer + + +async def main() -> None: + app = SmallServer() + + @app.get_regex(r"/users/(?P[0-9]+)") + async def user(request: Request) -> Response: + return Response.text(request.path_params["user_id"]) + + response = await app.dispatch(Request("GET", "/users/42?source=smoke", Headers())) + assert response.status == 200 + assert response.body == b"42" + + +if __name__ == "__main__": + asyncio.run(main()) diff --git a/tests/test_regex_routing.py b/tests/test_regex_routing.py index fba24b4..71c0b73 100644 --- a/tests/test_regex_routing.py +++ b/tests/test_regex_routing.py @@ -12,12 +12,17 @@ RouteMatchTimeout, SmallServer, ) +from smallserver.routing import Router HAS_REGEX = importlib.util.find_spec("regex") is not None class OptionalRegexDependencyTests(unittest.TestCase): + def test_error_observer_must_be_callable(self) -> None: + with self.assertRaisesRegex(TypeError, "route_error_observer"): + SmallServer(route_error_observer=object()) # type: ignore[arg-type] + def test_static_routes_do_not_import_optional_engine(self) -> None: app = SmallServer() @@ -88,6 +93,51 @@ async def exact(request): self.assertEqual((await app.dispatch(Request("GET", "/items/7", Headers()))).body, b"static") self.assertEqual((await app.dispatch(Request("GET", "/items/8", Headers()))).body, b"broad") + async def test_alternation_and_optional_literals_preserve_order_and_405(self) -> None: + app = SmallServer() + + @app.get_regex(r"/foo|/bar") + async def top_level(request): + return Response.text("top") + + @app.get_regex(r"/fo?bar") + async def optional(request): + return Response.text("optional") + + @app.get_regex(r"/(?:red|blue)") + async def nested(request): + return Response.text("nested") + + for path, expected in ( + ("/foo", b"top"), + ("/bar", b"top"), + ("/fbar", b"optional"), + ("/fobar", b"optional"), + ("/red", b"nested"), + ("/blue", b"nested"), + ): + with self.subTest(path=path): + self.assertEqual((await app.dispatch(Request("GET", path, Headers()))).body, expected) + response = await app.dispatch(Request("POST", "/bar", Headers())) + self.assertEqual(response.status, 405) + self.assertEqual(response.headers["allow"], "GET") + + def test_compiled_routes_are_structurally_guarded_to_slash_paths(self) -> None: + async def handler(request): + return Response() + + for pattern, slash_path, non_slash_path in ( + (r"/foo|bar", "/foo", "bar"), + (r"/?foo", "/foo", "foo"), + ): + with self.subTest(pattern=pattern): + router = Router() + router.add_regex(pattern, ("GET",), handler) + self.assertIs(router.resolve("GET", slash_path).handler, handler) + miss = router.resolve("GET", non_slash_path) + self.assertIsNone(miss.handler) + self.assertEqual(miss.allowed_methods, ()) + async def test_method_first_matching_and_sorted_allow(self) -> None: app = SmallServer() @@ -162,6 +212,19 @@ async def handler(request): with self.assertRaisesRegex(ValueError, "maximum"): limited.get_regex(r"/two")(handler) + async def test_verbose_comment_group_text_does_not_create_false_duplicate(self) -> None: + app = SmallServer() + + @app.get_regex( + "/(?x:items/ # (?Pthis is comment text)\n" + " (?P[0-9]+))" + ) + async def item(request): + return Response.text(request.path_params["item_id"]) + + response = await app.dispatch(Request("GET", "/items/42", Headers())) + self.assertEqual(response.body, b"42") + async def test_catastrophic_backtracking_is_bounded_and_path_is_not_disclosed(self) -> None: app = SmallServer(RegexRouteConfig(match_timeout=0.001, total_match_timeout=0.005)) @@ -180,9 +243,9 @@ async def handler(request): async def test_total_budget_bounds_many_individually_fast_misses(self) -> None: class SlowPattern: + groupindex = {} + def fullmatch(self, value, timeout): - if not value: - return None time.sleep(min(timeout / 2, 0.001)) return None @@ -207,14 +270,30 @@ async def handler(request): self.assertLess(time.monotonic() - started, 0.05) async def test_manual_dispatch_path_limit_is_enforced_before_matching(self) -> None: + calls = [] + + class Pattern: + groupindex = {} + + def fullmatch(self, value, timeout): + calls.append(value) + return None + + class Engine: + @staticmethod + def compile(pattern): + return Pattern() + app = SmallServer(RegexRouteConfig(max_path_bytes=8)) - @app.get_regex(r"/.*") async def handler(request): return Response() - with self.assertRaisesRegex(ValueError, "too large"): - await app.dispatch(Request("GET", "/12345678", Headers())) + with patch("smallserver.routing.importlib.import_module", return_value=Engine()): + app.get_regex(r"/.*")(handler) + response = await app.dispatch(Request("GET", "/12345678", Headers())) + self.assertEqual(response.status, 414) + self.assertEqual(calls, []) class RegexRouteConfigTests(unittest.TestCase): diff --git a/tests/test_server.py b/tests/test_server.py index 27b1766..86eef5c 100644 --- a/tests/test_server.py +++ b/tests/test_server.py @@ -59,6 +59,17 @@ def test_config_rejects_unbounded_limits(self) -> None: with self.assertRaisesRegex(ValueError, "max_request_target_bytes"): ServerConfig(max_request_target_bytes=0) + def test_config_preserves_legacy_positional_field_mapping(self) -> None: + config = ServerConfig(1, 2, 3, 4, 5, 6, 7) + self.assertEqual(config.max_connections, 1) + self.assertEqual(config.max_header_bytes, 2) + self.assertEqual(config.max_header_count, 3) + self.assertEqual(config.max_body_bytes, 4) + self.assertEqual(config.receive_chunk_bytes, 5) + self.assertEqual(config.listener_priority, 6) + self.assertEqual(config.connection_priority, 7) + self.assertEqual(config.max_request_target_bytes, 8 * 1024) + def test_serve_closes_bound_socket_when_runtime_fork_fails(self) -> None: class Listener: closed = False diff --git a/tests/test_server_runtime.py b/tests/test_server_runtime.py index 9d80992..1ada18c 100644 --- a/tests/test_server_runtime.py +++ b/tests/test_server_runtime.py @@ -6,7 +6,7 @@ from SmallPackage import SmallOS, Unix from SmallPackage.adapters.threads import ThreadAdapter -from smallserver import AdapterRegistry, Response, SmallServer +from smallserver import AdapterRegistry, RegexRouteConfig, Response, RouteMatchTimeout, SmallServer HAS_REGEX = importlib.util.find_spec("regex") is not None @@ -164,3 +164,86 @@ def client() -> None: self.assertFalse(worker.is_alive()) self.assertEqual(errors, []) self.assertIn(b"\r\n\r\na%2Fb?download=1", b"".join(received)) + + @unittest.skipUnless(HAS_REGEX, "regex-routes extra is not installed") + def test_regex_timeout_is_observed_once_and_does_not_stop_server(self) -> None: + runtime = SmallOS().setKernel(Unix()) + observed: list[RouteMatchTimeout] = [] + app = SmallServer( + RegexRouteConfig(match_timeout=0.001, total_match_timeout=0.005), + route_error_observer=observed.append, + ) + + @app.get_regex(r"/(a+)+$") + async def expensive(request): + return Response() + + @app.get("/health") + async def health(request): + return Response.text("healthy") + + try: + server = app.serve(runtime, host="127.0.0.1", port=0) + except PermissionError: + self.skipTest("the current sandbox does not permit loopback TCP binds") + + hostile_path = "/" + "a" * 5000 + "!" + received = [] + errors = [] + + def client() -> None: + try: + received.append(self._request(server.port, hostile_path)) + received.append(self._request(server.port, "/health")) + except BaseException as exc: + errors.append(exc) + finally: + server.close() + + worker = threading.Thread(target=client, daemon=True) + worker.start() + runtime.start() + worker.join(timeout=3) + self.assertFalse(worker.is_alive()) + self.assertEqual(errors, []) + self.assertEqual(len(observed), 1) + self.assertEqual(observed[0].route_id, "regex-route-1") + self.assertNotIn(hostile_path, str(observed[0])) + self.assertTrue(received[0].startswith(b"HTTP/1.1 500 Internal Server Error\r\n")) + self.assertNotIn(hostile_path.encode("ascii"), received[0]) + self.assertTrue(received[1].startswith(b"HTTP/1.1 200 OK\r\n")) + self.assertTrue(received[1].endswith(b"healthy")) + + @unittest.skipUnless(HAS_REGEX, "regex-routes extra is not installed") + def test_regex_path_limit_returns_414_before_matching(self) -> None: + runtime = SmallOS().setKernel(Unix()) + app = SmallServer(RegexRouteConfig(max_path_bytes=8)) + + @app.get_regex(r"/.*") + async def route(request): + return Response.text("must not run") + + try: + server = app.serve(runtime, host="127.0.0.1", port=0) + except PermissionError: + self.skipTest("the current sandbox does not permit loopback TCP binds") + + received = [] + errors = [] + + def client() -> None: + try: + received.append(self._request(server.port, "/12345678")) + except BaseException as exc: + errors.append(exc) + finally: + server.close() + + worker = threading.Thread(target=client, daemon=True) + worker.start() + runtime.start() + worker.join(timeout=2) + self.assertFalse(worker.is_alive()) + self.assertEqual(errors, []) + self.assertTrue(received[0].startswith(b"HTTP/1.1 414 URI Too Long\r\n")) + self.assertNotIn(b"must not run", received[0]) diff --git a/tests/typing/regex_routes.py b/tests/typing/regex_routes.py new file mode 100644 index 0000000..2239829 --- /dev/null +++ b/tests/typing/regex_routes.py @@ -0,0 +1,20 @@ +"""Public typing fixture for mypy/pyright and compile-only release checks.""" + +from smallserver import Request, Response, RouteMatchTimeout, SmallServer + + +def observe(error: RouteMatchTimeout) -> None: + route_id: str = error.route_id + assert route_id + + +def application() -> SmallServer: + app = SmallServer(route_error_observer=observe) + + @app.get_regex(r"/users/(?P[0-9]+)") + async def user(request: Request) -> Response: + user_id: str = request.path_params["user_id"] + pattern: str | None = request.route_pattern + return Response.json({"user_id": user_id, "pattern": pattern}) + + return app From 3aa94ea523e5d315d954d7c390649acc6f27fec6 Mon Sep 17 00:00:00 2001 From: Michael Emperador Date: Fri, 21 Aug 2026 23:47:09 -0500 Subject: [PATCH 03/14] fix: isolate route events and optimize static dispatch --- README.md | 21 +++++---- benchmarks/route_benchmark.py | 67 ++++++++++++++++++++-------- smallserver/__init__.py | 9 +++- smallserver/app.py | 35 +++++++++------ smallserver/routing.py | 12 ++++++ tests/installed_regex_smoke.py | 4 +- tests/test_routing.py | 16 +++++++ tests/test_server_runtime.py | 79 +++++++++++++++++++++++++++++----- tests/typing/regex_routes.py | 6 +-- 9 files changed, 195 insertions(+), 54 deletions(-) diff --git a/README.md b/README.md index 991183c..93ffe35 100644 --- a/README.md +++ b/README.md @@ -148,30 +148,35 @@ opaque route ID and becomes a sanitized 500 response on the network path. Applications can observe that failure without receiving the hostile target: ```python -from smallserver import RouteMatchTimeout +from smallserver import RouteErrorEvent -def observe_route_error(error: RouteMatchTimeout) -> None: - logger.error("route matching failed: %s", error.route_id) +def observe_route_error(event: RouteErrorEvent) -> None: + logger.error("route matching failed: %s (%s)", event.route_id, event.category) app = SmallServer(route_error_observer=observe_route_error) ``` -The synchronous observer runs once on the connection task and should return -quickly; observer failures are isolated from the response path. A path above -the configured regex-routing byte limit returns 414 before matching begins. +The synchronous observer receives a fresh, immutable, traceback-free event +containing only an opaque route ID and category. It runs once on the connection +task and should return quickly; observer failures are isolated from the +response path. A path above the configured regex-routing byte limit returns +414 before matching begins. Requests retain the exact ASCII origin-form target in `request.raw_target`. Routing uses `request.path`, which excludes the query string; `request.query_string` contains the raw text after `?`. Neither paths nor named captures are percent-decoded, so `/files/a%2Fb` remains distinct from -`/files/a/b`. `request.route_pattern` identifies the selected static path or -regex pattern. +`/files/a/b`. `request.route_pattern` identifies a selected regex pattern; +static dispatch passes the original request through without adding route +context. Run `python benchmarks/route_benchmark.py` for a same-process comparison of the pre-router dictionary dispatch model and current router dispatch. Its JSON also records configured versus observed hostile-pattern timeout when the extra is installed; rates are machine-specific and should be compared on the same host. +Use `python benchmarks/route_benchmark.py --release` to enforce the documented +static-dispatch floor of 80% of the legacy model across repeated rounds. Release validation can run `python tests/installed_regex_smoke.py` from an environment where the built `smallserver[regex-routes]` wheel is installed. diff --git a/benchmarks/route_benchmark.py b/benchmarks/route_benchmark.py index a3b247e..81ff591 100644 --- a/benchmarks/route_benchmark.py +++ b/benchmarks/route_benchmark.py @@ -8,6 +8,7 @@ import inspect import json from pathlib import Path +import statistics import sys import time @@ -15,6 +16,8 @@ from smallserver import Headers, RegexRouteConfig, Request, Response, RouteMatchTimeout, SmallServer +STATIC_DISPATCH_RATIO_FLOOR = 0.80 + async def _legacy_dispatch(routes, request): """Model the pre-router static dictionary dispatch for same-run comparison.""" @@ -28,7 +31,14 @@ async def _legacy_dispatch(routes, request): return response -async def benchmark(iterations: int) -> dict[str, float | int | str]: +async def _measure(operation, iterations: int) -> float: + started = time.perf_counter() + for _ in range(iterations): + await operation() + return iterations / (time.perf_counter() - started) + + +async def benchmark(iterations: int, rounds: int) -> dict[str, float | int | str | bool]: app = SmallServer() @app.get("/health") @@ -38,23 +48,37 @@ async def health(request): request = Request("GET", "/health", Headers()) legacy_routes = {("GET", "/health"): health} - started = time.perf_counter() - for _ in range(iterations): - await _legacy_dispatch(legacy_routes, request) - legacy_elapsed = time.perf_counter() - started - - started = time.perf_counter() - for _ in range(iterations): - await app.dispatch(request) - router_elapsed = time.perf_counter() - started - - legacy_rate = iterations / legacy_elapsed - router_rate = iterations / router_elapsed - result: dict[str, float | int | str] = { + async def legacy_operation(): + return await _legacy_dispatch(legacy_routes, request) + + async def router_operation(): + return await app.dispatch(request) + + await _measure(legacy_operation, min(iterations, 1_000)) + await _measure(router_operation, min(iterations, 1_000)) + legacy_rates = [] + router_rates = [] + ratios = [] + for round_number in range(rounds): + if round_number % 2: + router_rate = await _measure(router_operation, iterations) + legacy_rate = await _measure(legacy_operation, iterations) + else: + legacy_rate = await _measure(legacy_operation, iterations) + router_rate = await _measure(router_operation, iterations) + legacy_rates.append(legacy_rate) + router_rates.append(router_rate) + ratios.append(router_rate / legacy_rate) + + median_ratio = statistics.median(ratios) + result: dict[str, float | int | str | bool] = { "iterations": iterations, - "legacy_static_dispatches_per_second": round(legacy_rate, 2), - "router_static_dispatches_per_second": round(router_rate, 2), - "router_to_legacy_ratio": round(router_rate / legacy_rate, 4), + "rounds": rounds, + "legacy_static_dispatches_per_second": round(statistics.median(legacy_rates), 2), + "router_static_dispatches_per_second": round(statistics.median(router_rates), 2), + "router_to_legacy_ratio": round(median_ratio, 4), + "static_dispatch_ratio_floor": STATIC_DISPATCH_RATIO_FLOOR, + "static_dispatch_floor_passed": median_ratio >= STATIC_DISPATCH_RATIO_FLOOR, } if importlib.util.find_spec("regex") is None: @@ -80,10 +104,17 @@ async def hostile(request): def main() -> None: parser = argparse.ArgumentParser() parser.add_argument("--iterations", type=int, default=25_000) + parser.add_argument("--rounds", type=int, default=5) + parser.add_argument("--release", action="store_true") arguments = parser.parse_args() if arguments.iterations <= 0: parser.error("--iterations must be positive") - print(json.dumps(asyncio.run(benchmark(arguments.iterations)), indent=2, sort_keys=True)) + if arguments.rounds <= 0: + parser.error("--rounds must be positive") + result = asyncio.run(benchmark(arguments.iterations, arguments.rounds)) + print(json.dumps(result, indent=2, sort_keys=True)) + if arguments.release and not result["static_dispatch_floor_passed"]: + raise SystemExit(1) if __name__ == "__main__": diff --git a/smallserver/__init__.py b/smallserver/__init__.py index 476d64e..2fe0c87 100644 --- a/smallserver/__init__.py +++ b/smallserver/__init__.py @@ -4,7 +4,13 @@ from .adapters import AdapterRegistry, AdapterShutdownError, http_error_from_adapter from .errors import HTTPError from .http import Headers, Request, Response -from .routing import RegexRouteConfig, RegexRoutesUnavailable, RouteMatchTimeout, RoutePathTooLarge +from .routing import ( + RegexRouteConfig, + RegexRoutesUnavailable, + RouteErrorEvent, + RouteMatchTimeout, + RoutePathTooLarge, +) from .server import ServerConfig, ServerHandle __all__ = [ @@ -16,6 +22,7 @@ "RegexRoutesUnavailable", "Request", "Response", + "RouteErrorEvent", "RouteMatchTimeout", "RoutePathTooLarge", "ServerConfig", diff --git a/smallserver/app.py b/smallserver/app.py index a009025..eee2386 100644 --- a/smallserver/app.py +++ b/smallserver/app.py @@ -10,11 +10,17 @@ from .errors import HTTPError from .http import Request, Response -from .routing import RegexRouteConfig, RouteMatchTimeout, RoutePathTooLarge, Router +from .routing import ( + RegexRouteConfig, + RouteErrorEvent, + RouteMatchTimeout, + RoutePathTooLarge, + Router, +) from .server import HTTPParseError, HTTPRequestParser, ServerConfig, ServerHandle Handler = Callable[[Request], Awaitable[Response]] -RouteErrorObserver = Callable[[RouteMatchTimeout], None] +RouteErrorObserver = Callable[[RouteErrorEvent], None] class SmallServer: @@ -141,16 +147,18 @@ def serve( async def dispatch(self, request: Request) -> Response: """Run a registered handler or return a deterministic HTTP response.""" - try: - match = self._router.resolve(request.method, request.path) - except RoutePathTooLarge: - return Response.text("request target is too large", status=414) - if match.handler is None: - if match.allowed_methods: - return Response.text("method not allowed", status=405, headers={"Allow": ", ".join(match.allowed_methods)}) - return Response.text("not found", status=404) - handler = match.handler - request = replace(request, path_params=match.path_params, route_pattern=match.route_pattern) + handler = self._router.static_handler(request.method, request.path) + if handler is None: + try: + match = self._router.resolve(request.method, request.path) + except RoutePathTooLarge: + return Response.text("request target is too large", status=414) + if match.handler is None: + if match.allowed_methods: + return Response.text("method not allowed", status=405, headers={"Allow": ", ".join(match.allowed_methods)}) + return Response.text("not found", status=404) + handler = match.handler + request = replace(request, path_params=match.path_params, route_pattern=match.route_pattern) try: result = handler(request) if not inspect.isawaitable(result): @@ -259,7 +267,8 @@ def _observe_route_error(self, error: RouteMatchTimeout) -> None: observer = self._route_error_observer if observer is None: return + event = RouteErrorEvent(route_id=error.route_id, category="route_match_timeout") try: - observer(error) + observer(event) except Exception: pass diff --git a/smallserver/routing.py b/smallserver/routing.py index b53588d..f8db1ed 100644 --- a/smallserver/routing.py +++ b/smallserver/routing.py @@ -33,6 +33,14 @@ class RoutePathTooLarge(RuntimeError): """Raised before matching when a request path exceeds its routing bound.""" +@dataclass(frozen=True) +class RouteErrorEvent: + """Traceback-free, immutable routing failure data safe for observation.""" + + route_id: str + category: str + + @dataclass(frozen=True) class RegexRouteConfig: """Finite limits applied to regex registration and hostile request paths.""" @@ -98,6 +106,10 @@ def add_static(self, path: str, methods: tuple[str, ...], handler: Handler) -> N for key in keys: self._static[key] = handler + def static_handler(self, method: str, path: str) -> Handler | None: + """Return an exact static handler without allocating match context.""" + return self._static.get((method.upper(), path)) + def add_regex(self, pattern: str, methods: tuple[str, ...], handler: Handler) -> None: if not isinstance(pattern, str): raise TypeError("regex route pattern must be a string") diff --git a/tests/installed_regex_smoke.py b/tests/installed_regex_smoke.py index 7689ff0..e439c6d 100644 --- a/tests/installed_regex_smoke.py +++ b/tests/installed_regex_smoke.py @@ -2,10 +2,12 @@ import asyncio -from smallserver import Headers, Request, Response, SmallServer +from smallserver import Headers, Request, Response, RouteErrorEvent, SmallServer async def main() -> None: + event = RouteErrorEvent("regex-route-smoke", "route_match_timeout") + assert (event.route_id, event.category) == ("regex-route-smoke", "route_match_timeout") app = SmallServer() @app.get_regex(r"/users/(?P[0-9]+)") diff --git a/tests/test_routing.py b/tests/test_routing.py index d152500..72349f6 100644 --- a/tests/test_routing.py +++ b/tests/test_routing.py @@ -44,6 +44,22 @@ async def items(request): self.assertEqual(seen[0].path, "/items") self.assertEqual(seen[0].query_string, "tag=a%2Fb") + async def test_static_dispatch_passes_original_request_without_route_context_copy(self) -> None: + app = SmallServer() + seen = [] + + @app.get("/health") + async def health(request): + seen.append(request) + return Response() + + request = Request("GET", "/health", Headers()) + response = await app.dispatch(request) + self.assertEqual(response.status, 200) + self.assertIs(seen[0], request) + self.assertIsNone(seen[0].route_pattern) + self.assertEqual(dict(seen[0].path_params), {}) + async def test_http_error_becomes_response(self) -> None: app = SmallServer() diff --git a/tests/test_server_runtime.py b/tests/test_server_runtime.py index 1ada18c..c7bbb61 100644 --- a/tests/test_server_runtime.py +++ b/tests/test_server_runtime.py @@ -1,4 +1,5 @@ import importlib.util +from dataclasses import FrozenInstanceError import socket import threading import unittest @@ -6,18 +7,23 @@ from SmallPackage import SmallOS, Unix from SmallPackage.adapters.threads import ThreadAdapter -from smallserver import AdapterRegistry, RegexRouteConfig, Response, RouteMatchTimeout, SmallServer +from smallserver import ( + AdapterRegistry, + RegexRouteConfig, + Request, + Response, + RouteErrorEvent, + SmallServer, +) HAS_REGEX = importlib.util.find_spec("regex") is not None class SmallOSServerIntegrationTests(unittest.TestCase): - def _request(self, port: int, path: str) -> bytes: + def _exchange(self, port: int, payload: bytes) -> bytes: with socket.create_connection(("127.0.0.1", port), timeout=3) as connection: - connection.sendall( - "GET {} HTTP/1.1\r\nHost: localhost\r\n\r\n".format(path).encode("ascii") - ) + connection.sendall(payload) chunks = [] while True: chunk = connection.recv(4096) @@ -25,6 +31,12 @@ def _request(self, port: int, path: str) -> bytes: return b"".join(chunks) chunks.append(chunk) + def _request(self, port: int, path: str) -> bytes: + return self._exchange( + port, + "GET {} HTTP/1.1\r\nHost: localhost\r\n\r\n".format(path).encode("ascii"), + ) + def test_loopback_server_accepts_fragmented_request_and_shuts_down(self) -> None: runtime = SmallOS().setKernel(Unix()) app = SmallServer() @@ -168,13 +180,15 @@ def client() -> None: @unittest.skipUnless(HAS_REGEX, "regex-routes extra is not installed") def test_regex_timeout_is_observed_once_and_does_not_stop_server(self) -> None: runtime = SmallOS().setKernel(Unix()) - observed: list[RouteMatchTimeout] = [] + observed: list[RouteErrorEvent] = [] app = SmallServer( RegexRouteConfig(match_timeout=0.001, total_match_timeout=0.005), route_error_observer=observed.append, ) - @app.get_regex(r"/(a+)+$") + pattern_secret = "sensitive-pattern-marker" + + @app.post_regex(r"/(a+)+$(?#sensitive-pattern-marker)") async def expensive(request): return Response() @@ -188,12 +202,20 @@ async def health(request): self.skipTest("the current sandbox does not permit loopback TCP binds") hostile_path = "/" + "a" * 5000 + "!" + authorization_secret = "Bearer sensitive-authorization-marker" + body_secret = b"sensitive-body-marker" received = [] errors = [] def client() -> None: try: - received.append(self._request(server.port, hostile_path)) + request = ( + "POST {} HTTP/1.1\r\n" + "Host: localhost\r\n" + "Authorization: {}\r\n" + "Content-Length: {}\r\n\r\n" + ).format(hostile_path, authorization_secret, len(body_secret)).encode("ascii") + received.append(self._exchange(server.port, request + body_secret)) received.append(self._request(server.port, "/health")) except BaseException as exc: errors.append(exc) @@ -207,8 +229,24 @@ def client() -> None: self.assertFalse(worker.is_alive()) self.assertEqual(errors, []) self.assertEqual(len(observed), 1) - self.assertEqual(observed[0].route_id, "regex-route-1") - self.assertNotIn(hostile_path, str(observed[0])) + event = observed[0] + self.assertEqual(event.route_id, "regex-route-1") + self.assertEqual(event.category, "route_match_timeout") + with self.assertRaises(FrozenInstanceError): + event.route_id = "changed" # type: ignore[misc] + self.assertFalse(hasattr(event, "__traceback__")) + self.assertFalse(hasattr(event, "__cause__")) + self.assertFalse(hasattr(event, "__context__")) + + reachable = _reachable_objects(event) + reachable_strings = {value for value in reachable if isinstance(value, str)} + self.assertEqual( + reachable_strings, + {"route_id", "category", "regex-route-1", "route_match_timeout"}, + ) + self.assertFalse(any(isinstance(value, Request) for value in reachable)) + for secret in (hostile_path, authorization_secret, body_secret.decode("ascii"), pattern_secret): + self.assertNotIn(secret, reachable_strings) self.assertTrue(received[0].startswith(b"HTTP/1.1 500 Internal Server Error\r\n")) self.assertNotIn(hostile_path.encode("ascii"), received[0]) self.assertTrue(received[1].startswith(b"HTTP/1.1 200 OK\r\n")) @@ -247,3 +285,24 @@ def client() -> None: self.assertEqual(errors, []) self.assertTrue(received[0].startswith(b"HTTP/1.1 414 URI Too Long\r\n")) self.assertNotIn(b"must not run", received[0]) + + +def _reachable_objects(root): + pending = [root] + seen = set() + result = [] + while pending: + value = pending.pop() + identity = id(value) + if identity in seen: + continue + seen.add(identity) + result.append(value) + if isinstance(value, dict): + pending.extend(value.keys()) + pending.extend(value.values()) + elif isinstance(value, (tuple, list, set, frozenset)): + pending.extend(value) + elif hasattr(value, "__dict__"): + pending.append(vars(value)) + return result diff --git a/tests/typing/regex_routes.py b/tests/typing/regex_routes.py index 2239829..7f66494 100644 --- a/tests/typing/regex_routes.py +++ b/tests/typing/regex_routes.py @@ -1,10 +1,10 @@ """Public typing fixture for mypy/pyright and compile-only release checks.""" -from smallserver import Request, Response, RouteMatchTimeout, SmallServer +from smallserver import Request, Response, RouteErrorEvent, SmallServer -def observe(error: RouteMatchTimeout) -> None: - route_id: str = error.route_id +def observe(event: RouteErrorEvent) -> None: + route_id: str = event.route_id assert route_id From 4fed85273a2fcfadfee08d86a097763a480beac8 Mon Sep 17 00:00:00 2001 From: Michael Emperador Date: Fri, 21 Aug 2026 23:57:49 -0500 Subject: [PATCH 04/14] fix: isolate regex observer execution --- README.md | 13 +++-- benchmarks/route_benchmark.py | 4 ++ smallserver/app.py | 106 +++++++++++++++++++++++++++++----- smallserver/server.py | 19 +++++- tests/test_route_benchmark.py | 35 +++++++++++ tests/test_routing.py | 22 +++++++ tests/test_server_runtime.py | 47 +++++++++++++-- 7 files changed, 222 insertions(+), 24 deletions(-) create mode 100644 tests/test_route_benchmark.py diff --git a/README.md b/README.md index 93ffe35..87b894b 100644 --- a/README.md +++ b/README.md @@ -156,11 +156,14 @@ def observe_route_error(event: RouteErrorEvent) -> None: app = SmallServer(route_error_observer=observe_route_error) ``` -The synchronous observer receives a fresh, immutable, traceback-free event -containing only an opaque route ID and category. It runs once on the connection -task and should return quickly; observer failures are isolated from the -response path. A path above the configured regex-routing byte limit returns -414 before matching begins. +The observer receives a fresh, immutable, traceback-free event containing only +an opaque route ID and category. A bounded single-worker dispatcher invokes it +outside the SmallOS/request call stack and exits when its queue drains. The +observer should return quickly; failures are isolated from responses, reported +through `threading.excepthook`, and counted by +`server.route_observer_failures`. Capacity drops are counted by +`server.dropped_route_error_events`. A path above the configured regex-routing +byte limit returns 414 before matching begins. Requests retain the exact ASCII origin-form target in `request.raw_target`. Routing uses `request.path`, which excludes the query string; diff --git a/benchmarks/route_benchmark.py b/benchmarks/route_benchmark.py index 81ff591..1efab47 100644 --- a/benchmarks/route_benchmark.py +++ b/benchmarks/route_benchmark.py @@ -111,6 +111,10 @@ def main() -> None: parser.error("--iterations must be positive") if arguments.rounds <= 0: parser.error("--rounds must be positive") + if arguments.release and arguments.iterations < 10_000: + parser.error("--release requires at least 10000 iterations") + if arguments.release and arguments.rounds < 5: + parser.error("--release requires at least 5 rounds") result = asyncio.run(benchmark(arguments.iterations, arguments.rounds)) print(json.dumps(result, indent=2, sort_keys=True)) if arguments.release and not result["static_dispatch_floor_passed"]: diff --git a/smallserver/app.py b/smallserver/app.py index eee2386..53c5d51 100644 --- a/smallserver/app.py +++ b/smallserver/app.py @@ -3,9 +3,11 @@ from __future__ import annotations import inspect +from collections import deque from collections.abc import Awaitable, Callable, Iterable from dataclasses import replace import socket +import threading from typing import Any from .errors import HTTPError @@ -23,6 +25,77 @@ RouteErrorObserver = Callable[[RouteErrorEvent], None] +class _RouteObserverDispatcher: + """Run sanitized events on one bounded, short-lived observer thread.""" + + def __init__(self, observer: RouteErrorObserver) -> None: + self._observer = observer + self._events: deque[RouteErrorEvent] = deque() + self._lock = threading.Lock() + self._worker_active = False + self._pending = 0 + self._dropped = 0 + self._failures = 0 + + @property + def dropped(self) -> int: + with self._lock: + return self._dropped + + @property + def failures(self) -> int: + with self._lock: + return self._failures + + def schedule(self, event: RouteErrorEvent, max_pending: int) -> bool: + with self._lock: + if self._pending >= max_pending: + self._dropped += 1 + return False + self._events.append(event) + self._pending += 1 + if self._worker_active: + return True + self._worker_active = True + try: + threading.Thread( + target=self._run, + name="smallserver-route-observer", + daemon=True, + ).start() + except BaseException: + self._worker_active = False + self._events.pop() + self._pending -= 1 + self._dropped += 1 + return False + return True + + def _run(self) -> None: + while True: + with self._lock: + if not self._events: + self._worker_active = False + return + event = self._events.popleft() + try: + self._observer(event) + except BaseException as exc: + with self._lock: + self._failures += 1 + try: + threading.excepthook( + threading.ExceptHookArgs( + (type(exc), exc, exc.__traceback__, threading.current_thread()) + ) + ) + except BaseException: + pass + finally: + with self._lock: + self._pending -= 1 + + class SmallServer: """Register static HTTP routes and dispatch requests to async handlers.""" @@ -35,7 +108,11 @@ def __init__( if route_error_observer is not None and not callable(route_error_observer): raise TypeError("route_error_observer must be callable or None") self._router = Router(regex_config) - self._route_error_observer = route_error_observer + self._route_observer_dispatcher = ( + _RouteObserverDispatcher(route_error_observer) + if route_error_observer is not None + else None + ) def route(self, path: str, methods: Iterable[str]) -> Callable[[Handler], Handler]: if not isinstance(path, str) or not path.startswith("/"): @@ -123,7 +200,7 @@ def serve( except BaseException: listener.close() raise - handle = ServerHandle(runtime, listener, config) + handle = ServerHandle(runtime, listener, config, self._route_observer_dispatcher) listener_task = SmallTask( config.listener_priority, self._accept_loop, @@ -148,7 +225,10 @@ def serve( async def dispatch(self, request: Request) -> Response: """Run a registered handler or return a deterministic HTTP response.""" handler = self._router.static_handler(request.method, request.path) - if handler is None: + if handler is not None: + if request.path_params or request.route_pattern is not None: + request = replace(request, path_params={}, route_pattern=None) + else: try: match = self._router.resolve(request.method, request.path) except RoutePathTooLarge: @@ -235,7 +315,15 @@ async def _connection_loop(self, task: Any, handle: ServerHandle, client: socket try: response = await self.dispatch(request) except RouteMatchTimeout as exc: - self._observe_route_error(exc) + dispatcher = self._route_observer_dispatcher + if dispatcher is not None: + dispatcher.schedule( + RouteErrorEvent( + route_id=exc.route_id, + category="route_match_timeout", + ), + handle._config.max_connections, + ) response = Response.text("internal server error", status=500) except Exception: response = Response.text("internal server error", status=500) @@ -262,13 +350,3 @@ async def _send_response(self, task: Any, client: socket.socket, response: Respo if sent <= 0: return offset += sent - - def _observe_route_error(self, error: RouteMatchTimeout) -> None: - observer = self._route_error_observer - if observer is None: - return - event = RouteErrorEvent(route_id=error.route_id, category="route_match_timeout") - try: - observer(event) - except Exception: - pass diff --git a/smallserver/server.py b/smallserver/server.py index 9ef851d..39f1bfe 100644 --- a/smallserver/server.py +++ b/smallserver/server.py @@ -137,10 +137,17 @@ def __post_init__(self) -> None: class ServerHandle: """A bound listener and its cooperative shutdown signal.""" - def __init__(self, runtime: Any, listener: socket.socket, config: ServerConfig) -> None: + def __init__( + self, + runtime: Any, + listener: socket.socket, + config: ServerConfig, + route_observer_dispatcher: Any = None, + ) -> None: self._runtime = runtime self._listener = listener self._config = config + self._route_observer_dispatcher = route_observer_dispatcher self._wake_read, self._wake_write = socket.socketpair() self._wake_read.setblocking(False) self._wake_write.setblocking(False) @@ -161,6 +168,16 @@ def port(self) -> int: def closed(self) -> bool: return self._closed + @property + def dropped_route_error_events(self) -> int: + dispatcher = self._route_observer_dispatcher + return 0 if dispatcher is None else int(dispatcher.dropped) + + @property + def route_observer_failures(self) -> int: + dispatcher = self._route_observer_dispatcher + return 0 if dispatcher is None else int(dispatcher.failures) + def close(self) -> None: """Request shutdown safely from any thread without closing live FDs there.""" if self._closed: diff --git a/tests/test_route_benchmark.py b/tests/test_route_benchmark.py new file mode 100644 index 0000000..8b0abdd --- /dev/null +++ b/tests/test_route_benchmark.py @@ -0,0 +1,35 @@ +import contextlib +import io +import sys +import unittest +from unittest.mock import patch + +from benchmarks import route_benchmark + + +class RouteBenchmarkCLITests(unittest.TestCase): + def test_release_mode_rejects_undersized_samples(self) -> None: + cases = ( + ("9999", "5", "10000 iterations"), + ("10000", "4", "5 rounds"), + ) + for iterations, rounds, message in cases: + with self.subTest(iterations=iterations, rounds=rounds): + stderr = io.StringIO() + with patch.object( + sys, + "argv", + [ + "route_benchmark.py", + "--release", + "--iterations", + iterations, + "--rounds", + rounds, + ], + ): + with contextlib.redirect_stderr(stderr): + with self.assertRaises(SystemExit) as raised: + route_benchmark.main() + self.assertEqual(raised.exception.code, 2) + self.assertIn(message, stderr.getvalue()) diff --git a/tests/test_routing.py b/tests/test_routing.py index 72349f6..e6aaed4 100644 --- a/tests/test_routing.py +++ b/tests/test_routing.py @@ -60,6 +60,28 @@ async def health(request): self.assertIsNone(seen[0].route_pattern) self.assertEqual(dict(seen[0].path_params), {}) + async def test_static_dispatch_clears_spoofed_route_context(self) -> None: + app = SmallServer() + seen = [] + + @app.get("/health") + async def health(request): + seen.append(request) + return Response() + + dirty = Request( + "GET", + "/health", + Headers(), + path_params={"spoofed": "value"}, + route_pattern="sensitive-spoofed-pattern", + ) + response = await app.dispatch(dirty) + self.assertEqual(response.status, 200) + self.assertIsNot(seen[0], dirty) + self.assertIsNone(seen[0].route_pattern) + self.assertEqual(dict(seen[0].path_params), {}) + async def test_http_error_becomes_response(self) -> None: app = SmallServer() diff --git a/tests/test_server_runtime.py b/tests/test_server_runtime.py index c7bbb61..916e9c4 100644 --- a/tests/test_server_runtime.py +++ b/tests/test_server_runtime.py @@ -1,8 +1,10 @@ import importlib.util from dataclasses import FrozenInstanceError +import inspect import socket import threading import unittest +from unittest.mock import patch from SmallPackage import SmallOS, Unix from SmallPackage.adapters.threads import ThreadAdapter @@ -13,6 +15,7 @@ Request, Response, RouteErrorEvent, + RouteMatchTimeout, SmallServer, ) @@ -181,9 +184,29 @@ def client() -> None: def test_regex_timeout_is_observed_once_and_does_not_stop_server(self) -> None: runtime = SmallOS().setKernel(Unix()) observed: list[RouteErrorEvent] = [] + observer_graph = [] + observer_finished = threading.Event() + hook_finished = threading.Event() + hook_events = [] + + def observe(event: RouteErrorEvent) -> None: + observed.append(event) + caller_locals = [] + frame = inspect.currentframe() + while frame is not None: + caller_locals.append(dict(frame.f_locals)) + frame = frame.f_back + observer_graph.extend(_reachable_objects(caller_locals)) + observer_finished.set() + raise RuntimeError("intentional observer failure") + + def observe_thread_failure(arguments) -> None: + hook_events.append(arguments) + hook_finished.set() + app = SmallServer( RegexRouteConfig(match_timeout=0.001, total_match_timeout=0.005), - route_error_observer=observed.append, + route_error_observer=observe, ) pattern_secret = "sensitive-pattern-marker" @@ -217,15 +240,20 @@ def client() -> None: ).format(hostile_path, authorization_secret, len(body_secret)).encode("ascii") received.append(self._exchange(server.port, request + body_secret)) received.append(self._request(server.port, "/health")) + if not observer_finished.wait(2): + raise TimeoutError("route observer did not run") + if not hook_finished.wait(2): + raise TimeoutError("observer failure was not reported") except BaseException as exc: errors.append(exc) finally: server.close() worker = threading.Thread(target=client, daemon=True) - worker.start() - runtime.start() - worker.join(timeout=3) + with patch("threading.excepthook", side_effect=observe_thread_failure): + worker.start() + runtime.start() + worker.join(timeout=3) self.assertFalse(worker.is_alive()) self.assertEqual(errors, []) self.assertEqual(len(observed), 1) @@ -247,6 +275,17 @@ def client() -> None: self.assertFalse(any(isinstance(value, Request) for value in reachable)) for secret in (hostile_path, authorization_secret, body_secret.decode("ascii"), pattern_secret): self.assertNotIn(secret, reachable_strings) + + caller_strings = {value for value in observer_graph if isinstance(value, str)} + self.assertFalse(any(isinstance(value, Request) for value in observer_graph)) + self.assertFalse(any(isinstance(value, RouteMatchTimeout) for value in observer_graph)) + for secret in (hostile_path, authorization_secret, body_secret.decode("ascii"), pattern_secret): + self.assertNotIn(secret, caller_strings) + self.assertNotIn(body_secret, observer_graph) + self.assertEqual(server.route_observer_failures, 1) + self.assertEqual(server.dropped_route_error_events, 0) + self.assertEqual(len(hook_events), 1) + self.assertIsInstance(hook_events[0].exc_value, RuntimeError) self.assertTrue(received[0].startswith(b"HTTP/1.1 500 Internal Server Error\r\n")) self.assertNotIn(hostile_path.encode("ascii"), received[0]) self.assertTrue(received[1].startswith(b"HTTP/1.1 200 OK\r\n")) From 9639a4bdd5c8b04d907486d2aeacf3538e3ee76f Mon Sep 17 00:00:00 2001 From: Michael Emperador Date: Sat, 22 Aug 2026 00:12:10 -0500 Subject: [PATCH 05/14] fix: keep route observers on SmallOS --- README.md | 15 +++-- smallserver/app.py | 123 ++++++++++------------------------- smallserver/server.py | 80 +++++++++++++++++++++-- tests/test_server.py | 94 +++++++++++++++++++++++++- tests/test_server_runtime.py | 94 +++++++++++++++----------- 5 files changed, 262 insertions(+), 144 deletions(-) diff --git a/README.md b/README.md index 87b894b..8fe7a07 100644 --- a/README.md +++ b/README.md @@ -157,13 +157,14 @@ app = SmallServer(route_error_observer=observe_route_error) ``` The observer receives a fresh, immutable, traceback-free event containing only -an opaque route ID and category. A bounded single-worker dispatcher invokes it -outside the SmallOS/request call stack and exits when its queue drains. The -observer should return quickly; failures are isolated from responses, reported -through `threading.excepthook`, and counted by -`server.route_observer_failures`. Capacity drops are counted by -`server.dropped_route_error_events`. A path above the configured regex-routing -byte limit returns 414 before matching begins. +an opaque route ID and category. A bounded scheduler-local queue delivers it on +one dedicated SmallOS task, separate from the request task. The synchronous +observer must return quickly and must not block; blocking and async observers +remain an execution-adapter follow-up. Failures are isolated from responses +and counted by `server.route_observer_failures`. Capacity drops are counted by +`server.dropped_route_error_events`; tune the positive queue bound with +`ServerConfig(max_route_error_events=...)`. A path above the configured +regex-routing byte limit returns 414 before matching begins. Requests retain the exact ASCII origin-form target in `request.raw_target`. Routing uses `request.path`, which excludes the query string; diff --git a/smallserver/app.py b/smallserver/app.py index 53c5d51..952791f 100644 --- a/smallserver/app.py +++ b/smallserver/app.py @@ -3,11 +3,9 @@ from __future__ import annotations import inspect -from collections import deque from collections.abc import Awaitable, Callable, Iterable from dataclasses import replace import socket -import threading from typing import Any from .errors import HTTPError @@ -19,83 +17,19 @@ RoutePathTooLarge, Router, ) -from .server import HTTPParseError, HTTPRequestParser, ServerConfig, ServerHandle +from .server import ( + HTTPParseError, + HTTPRequestParser, + RouteObserverChannel, + ServerConfig, + ServerHandle, + run_route_observer, +) Handler = Callable[[Request], Awaitable[Response]] RouteErrorObserver = Callable[[RouteErrorEvent], None] -class _RouteObserverDispatcher: - """Run sanitized events on one bounded, short-lived observer thread.""" - - def __init__(self, observer: RouteErrorObserver) -> None: - self._observer = observer - self._events: deque[RouteErrorEvent] = deque() - self._lock = threading.Lock() - self._worker_active = False - self._pending = 0 - self._dropped = 0 - self._failures = 0 - - @property - def dropped(self) -> int: - with self._lock: - return self._dropped - - @property - def failures(self) -> int: - with self._lock: - return self._failures - - def schedule(self, event: RouteErrorEvent, max_pending: int) -> bool: - with self._lock: - if self._pending >= max_pending: - self._dropped += 1 - return False - self._events.append(event) - self._pending += 1 - if self._worker_active: - return True - self._worker_active = True - try: - threading.Thread( - target=self._run, - name="smallserver-route-observer", - daemon=True, - ).start() - except BaseException: - self._worker_active = False - self._events.pop() - self._pending -= 1 - self._dropped += 1 - return False - return True - - def _run(self) -> None: - while True: - with self._lock: - if not self._events: - self._worker_active = False - return - event = self._events.popleft() - try: - self._observer(event) - except BaseException as exc: - with self._lock: - self._failures += 1 - try: - threading.excepthook( - threading.ExceptHookArgs( - (type(exc), exc, exc.__traceback__, threading.current_thread()) - ) - ) - except BaseException: - pass - finally: - with self._lock: - self._pending -= 1 - - class SmallServer: """Register static HTTP routes and dispatch requests to async handlers.""" @@ -108,11 +42,7 @@ def __init__( if route_error_observer is not None and not callable(route_error_observer): raise TypeError("route_error_observer must be callable or None") self._router = Router(regex_config) - self._route_observer_dispatcher = ( - _RouteObserverDispatcher(route_error_observer) - if route_error_observer is not None - else None - ) + self._route_error_observer = route_error_observer def route(self, path: str, methods: Iterable[str]) -> Callable[[Handler], Handler]: if not isinstance(path, str) or not path.startswith("/"): @@ -200,7 +130,12 @@ def serve( except BaseException: listener.close() raise - handle = ServerHandle(runtime, listener, config, self._route_observer_dispatcher) + observer_channel = ( + RouteObserverChannel(self._route_error_observer, config.max_route_error_events) + if self._route_error_observer is not None + else None + ) + handle = ServerHandle(runtime, listener, config, observer_channel) listener_task = SmallTask( config.listener_priority, self._accept_loop, @@ -214,7 +149,16 @@ def serve( name="smallserver-close-watcher", ) handle._listener_task = listener_task - tasks = (listener_task, close_task) + tasks: tuple[Any, ...] = (listener_task, close_task) + if observer_channel is not None: + observer_task = SmallTask( + config.listener_priority, + run_route_observer, + args=(observer_channel,), + name="smallserver-route-observer", + ) + observer_channel.bind(observer_task) + tasks += (observer_task,) try: runtime.fork(list(tasks)) except BaseException: @@ -294,6 +238,7 @@ async def _connection_loop(self, task: Any, handle: ServerHandle, client: socket handle._config.max_body_bytes, handle._config.max_request_target_bytes, ) + route_error_event: RouteErrorEvent | None = None try: while not handle.closed: try: @@ -315,15 +260,10 @@ async def _connection_loop(self, task: Any, handle: ServerHandle, client: socket try: response = await self.dispatch(request) except RouteMatchTimeout as exc: - dispatcher = self._route_observer_dispatcher - if dispatcher is not None: - dispatcher.schedule( - RouteErrorEvent( - route_id=exc.route_id, - category="route_match_timeout", - ), - handle._config.max_connections, - ) + route_error_event = RouteErrorEvent( + route_id=exc.route_id, + category="route_match_timeout", + ) response = Response.text("internal server error", status=500) except Exception: response = Response.text("internal server error", status=500) @@ -335,6 +275,9 @@ async def _connection_loop(self, task: Any, handle: ServerHandle, client: socket client.close() except OSError: pass + observer_channel = handle._route_observer_channel + if route_error_event is not None and observer_channel is not None: + observer_channel.enqueue(route_error_event, task) async def _send_response(self, task: Any, client: socket.socket, response: Response) -> None: headers = {name: value for name, value in response.headers.items() if name.lower() != "connection"} diff --git a/smallserver/server.py b/smallserver/server.py index 39f1bfe..c9570af 100644 --- a/smallserver/server.py +++ b/smallserver/server.py @@ -2,11 +2,15 @@ from __future__ import annotations +from collections import deque from dataclasses import dataclass import socket from typing import Any from .http import Headers, Request, Response +from .routing import RouteErrorEvent + +_ROUTE_OBSERVER_SIGNAL = 31 class HTTPParseError(Exception): @@ -127,6 +131,7 @@ class ServerConfig: listener_priority: int = 1 connection_priority: int = 2 max_request_target_bytes: int = 8 * 1024 + max_route_error_events: int = 16 def __post_init__(self) -> None: for name, value in self.__dict__.items(): @@ -134,6 +139,58 @@ def __post_init__(self) -> None: raise ValueError("{} must be a positive integer".format(name)) +class RouteObserverChannel: + """Bounded scheduler-local delivery state for one server invocation.""" + + def __init__(self, observer: Any, max_events: int) -> None: + self.observer = observer + self.max_events = max_events + self.events: deque[RouteErrorEvent] = deque() + self.task: Any = None + self.accepting = True + self.dropped = 0 + self.failures = 0 + + def bind(self, task: Any) -> None: + self.task = task + + def enqueue(self, event: RouteErrorEvent, source_task: Any) -> bool: + if not self.accepting or len(self.events) >= self.max_events: + self.dropped += 1 + return False + self.events.append(event) + try: + signalled = ( + self.task is not None + and source_task.sendSignal(self.task.getID(), _ROUTE_OBSERVER_SIGNAL) == 0 + ) + except BaseException: + signalled = False + if not signalled: + self.events.pop() + self.dropped += 1 + return False + return True + + def stop(self) -> None: + self.accepting = False + self.dropped += len(self.events) + self.events.clear() + + +async def run_route_observer(task: Any, channel: RouteObserverChannel) -> None: + """Drain sanitized events on a dedicated SmallOS task.""" + while channel.accepting: + while channel.events: + event = channel.events.popleft() + try: + channel.observer(event) + except BaseException: + channel.failures += 1 + if channel.accepting: + await task.wait_signal(_ROUTE_OBSERVER_SIGNAL) + + class ServerHandle: """A bound listener and its cooperative shutdown signal.""" @@ -142,12 +199,12 @@ def __init__( runtime: Any, listener: socket.socket, config: ServerConfig, - route_observer_dispatcher: Any = None, + route_observer_channel: RouteObserverChannel | None = None, ) -> None: self._runtime = runtime self._listener = listener self._config = config - self._route_observer_dispatcher = route_observer_dispatcher + self._route_observer_channel = route_observer_channel self._wake_read, self._wake_write = socket.socketpair() self._wake_read.setblocking(False) self._wake_write.setblocking(False) @@ -170,13 +227,13 @@ def closed(self) -> bool: @property def dropped_route_error_events(self) -> int: - dispatcher = self._route_observer_dispatcher - return 0 if dispatcher is None else int(dispatcher.dropped) + channel = self._route_observer_channel + return 0 if channel is None else int(channel.dropped) @property def route_observer_failures(self) -> int: - dispatcher = self._route_observer_dispatcher - return 0 if dispatcher is None else int(dispatcher.failures) + channel = self._route_observer_channel + return 0 if channel is None else int(channel.failures) def close(self) -> None: """Request shutdown safely from any thread without closing live FDs there.""" @@ -194,6 +251,12 @@ def _finish_close(self) -> None: self._connections.clear() if self._listener_task is not None: self._runtime.resume_task(self._listener_task) + channel = self._route_observer_channel + if channel is not None: + channel.stop() + if channel.task is not None: + self._runtime.cancel_task(channel.task) + channel.task = None for sock in (self._listener, self._wake_read, self._wake_write): try: sock.close() @@ -203,6 +266,9 @@ def _finish_close(self) -> None: def _abort_startup(self, tasks: tuple[Any, ...]) -> None: """Release bound resources after task registration fails.""" self._closed = True + channel = self._route_observer_channel + if channel is not None: + channel.stop() cancel_task = getattr(self._runtime, "cancel_task", None) if callable(cancel_task): for task in tasks: @@ -210,6 +276,8 @@ def _abort_startup(self, tasks: tuple[Any, ...]) -> None: cancel_task(task) except BaseException: pass + if channel is not None: + channel.task = None for sock in (self._listener, self._wake_read, self._wake_write): try: sock.close() diff --git a/tests/test_server.py b/tests/test_server.py index 86eef5c..d386393 100644 --- a/tests/test_server.py +++ b/tests/test_server.py @@ -1,8 +1,8 @@ import unittest from unittest.mock import patch -from smallserver import SmallServer -from smallserver.server import HTTPParseError, HTTPRequestParser, ServerConfig +from smallserver import RouteErrorEvent, SmallServer +from smallserver.server import HTTPParseError, HTTPRequestParser, RouteObserverChannel, ServerConfig class HTTPRequestParserTests(unittest.TestCase): @@ -58,6 +58,8 @@ def test_config_rejects_unbounded_limits(self) -> None: ServerConfig(max_connections=True) with self.assertRaisesRegex(ValueError, "max_request_target_bytes"): ServerConfig(max_request_target_bytes=0) + with self.assertRaisesRegex(ValueError, "max_route_error_events"): + ServerConfig(max_route_error_events=0) def test_config_preserves_legacy_positional_field_mapping(self) -> None: config = ServerConfig(1, 2, 3, 4, 5, 6, 7) @@ -69,6 +71,46 @@ def test_config_preserves_legacy_positional_field_mapping(self) -> None: self.assertEqual(config.listener_priority, 6) self.assertEqual(config.connection_priority, 7) self.assertEqual(config.max_request_target_bytes, 8 * 1024) + self.assertEqual(config.max_route_error_events, 16) + + def test_route_observer_channel_has_deterministic_capacity_and_stop(self) -> None: + class ObserverTask: + @staticmethod + def getID() -> int: + return 9 + + class SourceTask: + signals = [] + + def sendSignal(self, pid, signal) -> int: + self.signals.append((pid, signal)) + return 0 + + channel = RouteObserverChannel(lambda event: None, max_events=1) + channel.bind(ObserverTask()) + source = SourceTask() + first = RouteErrorEvent("regex-route-1", "route_match_timeout") + second = RouteErrorEvent("regex-route-2", "route_match_timeout") + self.assertTrue(channel.enqueue(first, source)) + self.assertFalse(channel.enqueue(second, source)) + self.assertEqual(list(channel.events), [first]) + self.assertEqual(channel.dropped, 1) + self.assertEqual(source.signals, [(9, 31)]) + channel.stop() + self.assertFalse(channel.accepting) + self.assertEqual(list(channel.events), []) + self.assertEqual(channel.dropped, 2) + + failing_channel = RouteObserverChannel(lambda event: None, max_events=1) + failing_channel.bind(ObserverTask()) + + class FailingSourceTask: + def sendSignal(self, pid, signal) -> int: + raise RuntimeError("signal failed") + + self.assertFalse(failing_channel.enqueue(first, FailingSourceTask())) + self.assertEqual(list(failing_channel.events), []) + self.assertEqual(failing_channel.dropped, 1) def test_serve_closes_bound_socket_when_runtime_fork_fails(self) -> None: class Listener: @@ -105,3 +147,51 @@ def cancel_task(self, task) -> None: SmallServer().serve(runtime) self.assertTrue(listener.closed) self.assertEqual(runtime.cancelled, 2) + + def test_observer_task_is_included_in_startup_rollback(self) -> None: + class Listener: + closed = False + + def setsockopt(self, *args) -> None: + pass + + def bind(self, address) -> None: + pass + + def listen(self, backlog) -> None: + pass + + def setblocking(self, blocking) -> None: + pass + + def close(self) -> None: + self.closed = True + + class Runtime: + tasks = [] + cancelled = [] + + def fork(self, tasks) -> None: + self.tasks = list(tasks) + raise RuntimeError("no task capacity") + + def cancel_task(self, task) -> None: + self.cancelled.append(task) + + listener = Listener() + runtime = Runtime() + app = SmallServer(route_error_observer=lambda event: None) + with patch("smallserver.app.socket.socket", return_value=listener): + with self.assertRaisesRegex(RuntimeError, "capacity"): + app.serve(runtime) + self.assertTrue(listener.closed) + self.assertEqual(len(runtime.tasks), 3) + self.assertEqual(runtime.cancelled, runtime.tasks) + self.assertEqual( + [task.name for task in runtime.tasks], + [ + "smallserver-listener", + "smallserver-close-watcher", + "smallserver-route-observer", + ], + ) diff --git a/tests/test_server_runtime.py b/tests/test_server_runtime.py index 916e9c4..3937cf9 100644 --- a/tests/test_server_runtime.py +++ b/tests/test_server_runtime.py @@ -4,7 +4,6 @@ import socket import threading import unittest -from unittest.mock import patch from SmallPackage import SmallOS, Unix from SmallPackage.adapters.threads import ThreadAdapter @@ -18,6 +17,7 @@ RouteMatchTimeout, SmallServer, ) +from smallserver.server import run_route_observer HAS_REGEX = importlib.util.find_spec("regex") is not None @@ -186,24 +186,22 @@ def test_regex_timeout_is_observed_once_and_does_not_stop_server(self) -> None: observed: list[RouteErrorEvent] = [] observer_graph = [] observer_finished = threading.Event() - hook_finished = threading.Event() - hook_events = [] + observer_threads = [] def observe(event: RouteErrorEvent) -> None: observed.append(event) + observer_threads.append(threading.current_thread()) caller_locals = [] frame = inspect.currentframe() while frame is not None: caller_locals.append(dict(frame.f_locals)) + if frame.f_code is run_route_observer.__code__: + break frame = frame.f_back - observer_graph.extend(_reachable_objects(caller_locals)) + observer_graph.extend(_reachable_container_values(caller_locals)) observer_finished.set() raise RuntimeError("intentional observer failure") - def observe_thread_failure(arguments) -> None: - hook_events.append(arguments) - hook_finished.set() - app = SmallServer( RegexRouteConfig(match_timeout=0.001, total_match_timeout=0.005), route_error_observer=observe, @@ -227,35 +225,24 @@ async def health(request): hostile_path = "/" + "a" * 5000 + "!" authorization_secret = "Bearer sensitive-authorization-marker" body_secret = b"sensitive-body-marker" - received = [] - errors = [] - - def client() -> None: - try: - request = ( - "POST {} HTTP/1.1\r\n" - "Host: localhost\r\n" - "Authorization: {}\r\n" - "Content-Length: {}\r\n\r\n" - ).format(hostile_path, authorization_secret, len(body_secret)).encode("ascii") - received.append(self._exchange(server.port, request + body_secret)) - received.append(self._request(server.port, "/health")) - if not observer_finished.wait(2): - raise TimeoutError("route observer did not run") - if not hook_finished.wait(2): - raise TimeoutError("observer failure was not reported") - except BaseException as exc: - errors.append(exc) - finally: - server.close() - - worker = threading.Thread(target=client, daemon=True) - with patch("threading.excepthook", side_effect=observe_thread_failure): - worker.start() - runtime.start() - worker.join(timeout=3) - self.assertFalse(worker.is_alive()) - self.assertEqual(errors, []) + runtime_thread = threading.Thread( + target=runtime.start, + name="smallos-runtime-test", + daemon=True, + ) + runtime_thread.start() + request = ( + "POST {} HTTP/1.1\r\n" + "Host: localhost\r\n" + "Authorization: {}\r\n" + "Content-Length: {}\r\n\r\n" + ).format(hostile_path, authorization_secret, len(body_secret)).encode("ascii") + received = [self._exchange(server.port, request + body_secret)] + received.append(self._request(server.port, "/health")) + self.assertTrue(observer_finished.wait(2), "route observer did not run") + server.close() + runtime_thread.join(timeout=3) + self.assertFalse(runtime_thread.is_alive()) self.assertEqual(len(observed), 1) event = observed[0] self.assertEqual(event.route_id, "regex-route-1") @@ -284,8 +271,17 @@ def client() -> None: self.assertNotIn(body_secret, observer_graph) self.assertEqual(server.route_observer_failures, 1) self.assertEqual(server.dropped_route_error_events, 0) - self.assertEqual(len(hook_events), 1) - self.assertIsInstance(hook_events[0].exc_value, RuntimeError) + self.assertEqual(observer_threads, [runtime_thread]) + self.assertNotIn( + "smallserver-route-observer", + {thread.name for thread in threading.enumerate()}, + ) + channel = server._route_observer_channel + self.assertIsNotNone(channel) + assert channel is not None + self.assertFalse(channel.accepting) + self.assertEqual(list(channel.events), []) + self.assertIsNone(channel.task) self.assertTrue(received[0].startswith(b"HTTP/1.1 500 Internal Server Error\r\n")) self.assertNotIn(hostile_path.encode("ascii"), received[0]) self.assertTrue(received[1].startswith(b"HTTP/1.1 200 OK\r\n")) @@ -345,3 +341,23 @@ def _reachable_objects(root): elif hasattr(value, "__dict__"): pending.append(vars(value)) return result + + +def _reachable_container_values(root): + """Walk frame-local containers without traversing scheduler object graphs.""" + pending = [root] + seen = set() + result = [] + while pending: + value = pending.pop() + identity = id(value) + if identity in seen: + continue + seen.add(identity) + result.append(value) + if isinstance(value, dict): + pending.extend(value.keys()) + pending.extend(value.values()) + elif isinstance(value, (tuple, list, set, frozenset)): + pending.extend(value) + return result From 9c43f8908ad83327a14e1bbdc5b7a187b45be288 Mon Sep 17 00:00:00 2001 From: Michael Emperador Date: Sat, 22 Aug 2026 02:00:53 -0500 Subject: [PATCH 06/14] feat: add bounded WebSocket server --- pyproject.toml | 1 + smallserver/__init__.py | 16 + smallserver/app.py | 116 +++++ smallserver/http.py | 4 + smallserver/server.py | 54 +- smallserver/websocket.py | 843 +++++++++++++++++++++++++++++++ tests/test_websocket.py | 657 ++++++++++++++++++++++++ tests/typing/websocket_routes.py | 14 + 8 files changed, 1694 insertions(+), 11 deletions(-) create mode 100644 smallserver/websocket.py create mode 100644 tests/test_websocket.py create mode 100644 tests/typing/websocket_routes.py diff --git a/pyproject.toml b/pyproject.toml index ced2d56..af3cbe6 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -15,6 +15,7 @@ dependencies = [] [project.optional-dependencies] dev = ["build>=1.2"] regex-routes = ["regex>=2023.10.3,<2027"] +websocket = ["wsproto>=1.2,<2"] [tool.setuptools.packages.find] include = ["smallserver*"] diff --git a/smallserver/__init__.py b/smallserver/__init__.py index db879cb..a03bde9 100644 --- a/smallserver/__init__.py +++ b/smallserver/__init__.py @@ -18,6 +18,15 @@ RoutePathTooLarge, ) from .server import ServerConfig, ServerHandle +from .websocket import ( + WebSocket, + WebSocketCapacityError, + WebSocketConfig, + WebSocketDisconnect, + WebSocketMessage, + WebSocketStateError, + WebSocketUnavailable, +) if TYPE_CHECKING: from .adapters import AdapterRegistry, AdapterShutdownError, http_error_from_adapter @@ -51,5 +60,12 @@ def __getattr__(name: str) -> Any: "ServerHandle", "ServerStartupError", "SmallServer", + "WebSocket", + "WebSocketCapacityError", + "WebSocketConfig", + "WebSocketDisconnect", + "WebSocketMessage", + "WebSocketStateError", + "WebSocketUnavailable", "http_error_from_adapter", ] diff --git a/smallserver/app.py b/smallserver/app.py index 6c8f8a1..ea97f34 100644 --- a/smallserver/app.py +++ b/smallserver/app.py @@ -40,8 +40,19 @@ ServerHandle, run_route_observer, ) +from .websocket import ( + WebSocket, + WebSocketConfig, + WebSocketUnavailable, + _WebSocketRoute, + _WebSocketState, + _is_upgrade_attempt, + _validate_upgrade, + run_websocket_connection, +) Handler = Callable[[Request], Awaitable[Response]] +WebSocketHandler = Callable[[WebSocket], Awaitable[None]] RouteErrorObserver = Callable[[RouteErrorEvent], None] @@ -139,11 +150,18 @@ def __init__( regex_config: RegexRouteConfig | None = None, *, route_error_observer: RouteErrorObserver | None = None, + websocket_config: WebSocketConfig | None = None, ) -> None: if route_error_observer is not None and not callable(route_error_observer): raise TypeError("route_error_observer must be callable or None") self._router = Router(regex_config) self._route_error_observer = route_error_observer + if websocket_config is not None and not isinstance( + websocket_config, WebSocketConfig + ): + raise TypeError("websocket_config must be a WebSocketConfig or None") + self._websocket_config = websocket_config or WebSocketConfig() + self._websocket_routes: dict[str, _WebSocketRoute] = {} self._active_invocation: object | ServerHandle | None = None self._invocation_lock: Any = ( allocate_lock() if allocate_lock is not None else _NoThreadLock() @@ -200,6 +218,50 @@ def patch(self, path: str) -> Callable[[Handler], Handler]: def delete(self, path: str) -> Callable[[Handler], Handler]: return self.route(path, ("DELETE",)) + def websocket( + self, + path: str, + *, + origins: Iterable[str] | None = None, + subprotocols: Iterable[str] = (), + ) -> Callable[[WebSocketHandler], WebSocketHandler]: + """Register a static HTTP/1.1 WebSocket Upgrade route.""" + if not isinstance(path, str) or not path.startswith("/"): + raise ValueError("WebSocket route path must start with '/'") + if "?" in path or "#" in path: + raise ValueError("WebSocket route path must not contain query or fragment") + if path in self._websocket_routes: + raise ValueError("WebSocket route already registered: {}".format(path)) + origin_set: frozenset[str] | None = None + if origins is not None: + if isinstance(origins, str): + raise TypeError("WebSocket origins must be an iterable of strings") + origin_set = frozenset(origins) + if any(not isinstance(origin, str) or not origin for origin in origin_set): + raise ValueError("WebSocket origins must be non-empty strings") + if isinstance(subprotocols, str): + raise TypeError("WebSocket subprotocols must be an iterable of tokens") + protocols = tuple(dict.fromkeys(subprotocols)) + if any( + not isinstance(protocol, str) + or not protocol + or any(character in protocol for character in "()<>@,;:\\\"/[]?={} \t") + for protocol in protocols + ): + raise ValueError("WebSocket subprotocols must be valid HTTP tokens") + + def register(handler: WebSocketHandler) -> WebSocketHandler: + if not callable(handler): + raise TypeError("WebSocket handler must be callable") + if path in self._websocket_routes: + raise ValueError("WebSocket route already registered: {}".format(path)) + self._websocket_routes[path] = _WebSocketRoute( + handler, origin_set, protocols + ) + return handler + + return register + def route_regex(self, pattern: str, methods: Iterable[str]) -> Callable[[Handler], Handler]: """Register a timeout-bounded full-path regular-expression route.""" normalized = self._router.normalize_methods(methods) @@ -585,6 +647,7 @@ async def _connection_loop( handle._config.max_header_count, handle._config.max_body_bytes, handle._config.max_request_target_bytes, + preserve_trailing_data=True, ) primary_error: BaseException | None = None route_error_event: RouteErrorEvent | None = None @@ -607,6 +670,25 @@ async def _connection_loop( return if request is None: continue + if _is_upgrade_attempt(request): + response = await self._dispatch_websocket( + task, + handle, + client, + request, + parser.trailing_data, + ) + if response is not None: + await self._send_response(task, handle, client, response) + return + if parser.trailing_data: + await self._send_response( + task, + handle, + client, + Response.text("pipelined requests are not supported", status=400), + ) + return try: response = await self.dispatch(request) except RouteMatchTimeout as exc: @@ -628,6 +710,40 @@ async def _connection_loop( observer_channel.enqueue(route_error_event, task) handle._connection_finished(task, client, primary_error) + async def _dispatch_websocket( + self, + task: Any, + handle: ServerHandle, + client: TransportHandle, + request: Request, + trailing_data: bytes, + ) -> Response | None: + route = self._websocket_routes.get(request.path) + if route is None: + return Response.text("not found", status=404) + invalid = _validate_upgrade(request, route) + if invalid is not None: + return invalid + if len(handle._websocket_states) >= min( + self._websocket_config.max_connections, + handle._config.max_connections, + ): + return Response.text("WebSocket capacity reached", status=503) + try: + state = _WebSocketState( + handle._runtime, + handle._transport, + client, + request, + route, + self._websocket_config, + trailing_data, + ) + except WebSocketUnavailable as exc: + return Response.text(str(exc), status=503) + await run_websocket_connection(task, state, handle) + return None + async def _send_response( self, task: Any, diff --git a/smallserver/http.py b/smallserver/http.py index f90afbd..b1b2574 100644 --- a/smallserver/http.py +++ b/smallserver/http.py @@ -11,14 +11,18 @@ _TOKEN = re.compile(r"^[!#$%&'*+.^_`|~0-9A-Za-z-]+$") _REASONS = { + 101: "Switching Protocols", 200: "OK", 201: "Created", 204: "No Content", 400: "Bad Request", + 403: "Forbidden", 404: "Not Found", 405: "Method Not Allowed", 413: "Payload Too Large", 414: "URI Too Long", + 408: "Request Timeout", + 426: "Upgrade Required", 500: "Internal Server Error", 503: "Service Unavailable", } diff --git a/smallserver/server.py b/smallserver/server.py index d48d95b..d4f2135 100644 --- a/smallserver/server.py +++ b/smallserver/server.py @@ -31,13 +31,21 @@ def __init__( max_header_count: int, max_body_bytes: int, max_request_target_bytes: int = 8 * 1024, + preserve_trailing_data: bool = False, ) -> None: self._max_header_bytes = max_header_bytes self._max_header_count = max_header_count self._max_body_bytes = max_body_bytes self._max_request_target_bytes = max_request_target_bytes + self._preserve_trailing_data = preserve_trailing_data self._buffer = bytearray() self._request_head: tuple[str, str, Headers, int] | None = None + self._trailing_data = b"" + + @property + def trailing_data(self) -> bytes: + """Bytes received after the request body for an explicit protocol handoff.""" + return self._trailing_data def feed(self, data: bytes) -> Request | None: self._buffer.extend(data) @@ -54,17 +62,19 @@ def feed(self, data: bytes) -> Request | None: del self._buffer[:header_length] method, raw_target, headers, content_length = self._request_head - if len(self._buffer) > content_length: + if len(self._buffer) > content_length and not self._preserve_trailing_data: raise HTTPParseError(400, "pipelined requests are not supported") if len(self._buffer) < content_length: return None try: path, separator, query_string = raw_target.partition("?") + body = bytes(self._buffer[:content_length]) + self._trailing_data = bytes(self._buffer[content_length:]) return Request( method, path, headers, - bytes(self._buffer), + body, "HTTP/1.1", raw_target=raw_target, query_string=query_string if separator else "", @@ -177,19 +187,26 @@ def stop(self) -> None: self.accepting = False self.dropped += len(self.events) self.events.clear() + if self.task is not None: + accept_signal = getattr(self.task, "acceptSignal", None) + if callable(accept_signal): + accept_signal(_ROUTE_OBSERVER_SIGNAL) async def run_route_observer(task: Any, channel: RouteObserverChannel) -> None: """Drain sanitized events on a dedicated SmallOS task.""" - while channel.accepting: - while channel.events: - event = channel.events.popleft() - try: - channel.observer(event) - except BaseException: - channel.failures += 1 - if channel.accepting: - await task.wait_signal(_ROUTE_OBSERVER_SIGNAL) + try: + while channel.accepting: + while channel.events: + event = channel.events.popleft() + try: + channel.observer(event) + except BaseException: + channel.failures += 1 + if channel.accepting: + await task.wait_signal(_ROUTE_OBSERVER_SIGNAL) + finally: + channel.task = None class ServerHandle: @@ -229,6 +246,7 @@ def __init__( self._connections: dict[int, tuple[TransportHandle, Any]] = {} self._closing_connections: dict[int, TransportHandle] = {} self._pending_task_cancellations: dict[int, Any] = {} + self._websocket_states: dict[int, Any] = {} self._capacity_waiting = False @property @@ -335,6 +353,10 @@ async def close_from_task(self, task: Any) -> None: return self._close_requested = True self._finalization_attempted = True + for state in tuple(self._websocket_states.values()): + request_shutdown = getattr(state, "request_shutdown", None) + if callable(request_shutdown): + request_shutdown() self._finish_close(current_task=task) def _listener_failed(self, exc: BaseException, task: Any) -> None: @@ -369,6 +391,10 @@ def _finish_close( return self._close_requested = True self._finalization_attempted = True + for state in tuple(self._websocket_states.values()): + request_shutdown = getattr(state, "request_shutdown", None) + if callable(request_shutdown): + request_shutdown() channel = self._route_observer_channel if channel is not None and channel.accepting: channel.stop() @@ -402,6 +428,7 @@ def _finish_close( self._cancelled_task_ids.add(identity) for identity, (connection, task) in list(self._connections.items()): + websocket_owned = identity in self._websocket_states if owner_thread: if ( task is not current_task @@ -416,6 +443,10 @@ def _finish_close( self._runtime.resume_task(task) except BaseException: pass + if websocket_owned: + # The live coordinator owns its bounded Close handshake + # and releases the stream through _connection_finished(). + continue if task is not current_task: self._connections.pop(identity, None) self._close_or_retain(connection, current_task) @@ -546,6 +577,7 @@ def _update_finished(self) -> None: and not self._connections and not self._closing_connections and not self._pending_task_cancellations + and not self._websocket_states ) if self._finished: self._cleanup_errors.clear() diff --git a/smallserver/websocket.py b/smallserver/websocket.py new file mode 100644 index 0000000..48fd91a --- /dev/null +++ b/smallserver/websocket.py @@ -0,0 +1,843 @@ +"""Bounded RFC 6455 WebSocket support driven by SmallOS tasks.""" + +from __future__ import annotations + +import base64 +from collections import deque +from dataclasses import dataclass +import hashlib +import importlib +import inspect +import math +import time +from typing import Any, AsyncIterator, Callable, Mapping + +from .http import Headers, Request, Response + +_GUID = b"258EAFA5-E914-47DA-95CA-C5AB0DC85B11" +_DECISION_SIGNAL = 24 +_INBOX_SIGNAL = 25 +_OUTBOX_SIGNAL = 26 +_ACK_SIGNAL = 27 + + +class WebSocketUnavailable(RuntimeError): + """The optional WebSocket protocol dependency is unavailable.""" + + +class WebSocketStateError(RuntimeError): + """A WebSocket operation is invalid in the current lifecycle state.""" + + +class WebSocketCapacityError(RuntimeError): + """A bounded WebSocket mailbox cannot accept another item.""" + + +class WebSocketDisconnect(Exception): + """The peer or server closed a WebSocket connection.""" + + def __init__(self, code: int = 1006, reason: str = "") -> None: + self.code = code + self.reason = reason + super().__init__("WebSocket disconnected ({})".format(code)) + + +@dataclass(frozen=True) +class WebSocketMessage: + """One complete text or binary WebSocket message.""" + + data: str | bytes + + @property + def is_text(self) -> bool: + return isinstance(self.data, str) + + @property + def is_binary(self) -> bool: + return isinstance(self.data, bytes) + + @property + def text(self) -> str: + if not isinstance(self.data, str): + raise TypeError("WebSocket message is binary") + return self.data + + @property + def bytes(self) -> bytes: + if not isinstance(self.data, bytes): + raise TypeError("WebSocket message is text") + return self.data + + +@dataclass(frozen=True) +class WebSocketConfig: + """Finite resource and lifetime limits for WebSocket connections.""" + + max_frame_payload_bytes: int = 1024 * 1024 + max_message_bytes: int = 1024 * 1024 + max_inbound_messages: int = 16 + max_inbound_bytes: int = 2 * 1024 * 1024 + max_outbound_commands: int = 16 + max_outbound_bytes: int = 2 * 1024 * 1024 + receive_chunk_bytes: int = 16 * 1024 + write_chunk_bytes: int = 16 * 1024 + max_connections: int = 100 + handshake_timeout: float = 10.0 + idle_timeout: float = 300.0 + pong_timeout: float = 10.0 + close_timeout: float = 5.0 + deadline_resolution: float = 0.05 + + def __post_init__(self) -> None: + integer_fields = ( + "max_frame_payload_bytes", + "max_message_bytes", + "max_inbound_messages", + "max_inbound_bytes", + "max_outbound_commands", + "max_outbound_bytes", + "receive_chunk_bytes", + "write_chunk_bytes", + "max_connections", + ) + for name in integer_fields: + value = getattr(self, name) + if type(value) is not int or value <= 0: + raise ValueError("{} must be a positive integer".format(name)) + for name in ( + "handshake_timeout", + "idle_timeout", + "pong_timeout", + "close_timeout", + "deadline_resolution", + ): + value = getattr(self, name) + if type(value) not in (int, float) or not math.isfinite(value) or value <= 0: + raise ValueError("{} must be a finite positive number".format(name)) + if self.max_frame_payload_bytes > self.max_message_bytes: + raise ValueError("max_frame_payload_bytes must not exceed max_message_bytes") + + +@dataclass(frozen=True) +class _WebSocketRoute: + handler: Callable[[WebSocket], Any] + origins: frozenset[str] | None + subprotocols: tuple[str, ...] + + +@dataclass +class _OutboundCommand: + event: Any + size: int + waiter: Any = None + done: bool = False + error: BaseException | None = None + + +@dataclass(frozen=True) +class _WSProtoAPI: + Connection: Any + ConnectionType: Any + TextMessage: Any + BytesMessage: Any + Ping: Any + Pong: Any + CloseConnection: Any + + +def _load_wsproto() -> _WSProtoAPI: + """Import the optional protocol engine only when an upgrade is served.""" + try: + connection = importlib.import_module("wsproto.connection") + events = importlib.import_module("wsproto.events") + except ImportError as exc: + raise WebSocketUnavailable( + "WebSocket routes require the 'smallserver[websocket]' extra" + ) from exc + return _WSProtoAPI( + connection.Connection, + connection.ConnectionType, + events.TextMessage, + events.BytesMessage, + events.Ping, + events.Pong, + events.CloseConnection, + ) + + +class _FrameGuard: + """Validate declared client frame sizes before forwarding payload bytes.""" + + def __init__(self, max_payload_bytes: int) -> None: + self._max_payload_bytes = max_payload_bytes + self._header = bytearray() + self._header_length: int | None = None + self._payload_remaining = 0 + + def feed(self, data: bytes) -> tuple[bytes, ...]: + chunks: list[bytes] = [] + offset = 0 + while offset < len(data): + if self._payload_remaining: + length = min(self._payload_remaining, len(data) - offset) + chunks.append(data[offset : offset + length]) + offset += length + self._payload_remaining -= length + if self._payload_remaining == 0: + self._header_length = None + continue + + if self._header_length is None: + needed = 2 - len(self._header) + if needed: + length = min(needed, len(data) - offset) + self._header.extend(data[offset : offset + length]) + offset += length + if len(self._header) < 2: + continue + second = self._header[1] + marker = second & 0x7F + extension = 2 if marker == 126 else 8 if marker == 127 else 0 + self._header_length = 2 + extension + (4 if second & 0x80 else 0) + + needed = self._header_length - len(self._header) + if needed: + length = min(needed, len(data) - offset) + self._header.extend(data[offset : offset + length]) + offset += length + if len(self._header) < self._header_length: + continue + + first, second = self._header[:2] + if not second & 0x80: + raise ValueError("client WebSocket frames must be masked") + marker = second & 0x7F + index = 2 + if marker == 126: + payload_length = int.from_bytes(self._header[index : index + 2], "big") + index += 2 + if payload_length < 126: + raise ValueError("non-minimal WebSocket frame length") + elif marker == 127: + payload_length = int.from_bytes(self._header[index : index + 8], "big") + index += 8 + if payload_length < 65536 or payload_length >> 63: + raise ValueError("invalid WebSocket frame length") + else: + payload_length = marker + opcode = first & 0x0F + if opcode >= 8 and (not first & 0x80 or payload_length > 125): + raise ValueError("invalid WebSocket control frame") + if payload_length > self._max_payload_bytes: + raise WebSocketCapacityError("WebSocket frame payload is too large") + chunks.append(bytes(self._header)) + self._header.clear() + self._payload_remaining = payload_length + if payload_length == 0: + self._header_length = None + return tuple(chunks) + + +class WebSocket: + """Application-facing WebSocket connection.""" + + def __init__(self, state: _WebSocketState) -> None: + self._state = state + + @property + def request(self) -> Request: + return self._state.request + + @property + def subprotocol(self) -> str | None: + return self._state.subprotocol + + async def accept( + self, + subprotocol: str | None = None, + headers: Mapping[str, str] | None = None, + ) -> None: + await self._state.accept(subprotocol, headers) + + async def reject(self, response: Response) -> None: + await self._state.reject(response) + + async def receive(self) -> WebSocketMessage: + return await self._state.receive() + + async def receive_text(self) -> str: + return (await self.receive()).text + + async def receive_bytes(self) -> bytes: + return (await self.receive()).bytes + + async def send_text(self, value: str) -> None: + if not isinstance(value, str): + raise TypeError("WebSocket text payload must be a string") + await self._state.send_message(value) + + async def send_bytes(self, value: bytes) -> None: + if not isinstance(value, bytes): + raise TypeError("WebSocket binary payload must be bytes") + await self._state.send_message(value) + + async def ping(self, payload: bytes = b"") -> None: + if not isinstance(payload, bytes) or len(payload) > 125: + raise ValueError("WebSocket Ping payload must be at most 125 bytes") + await self._state.ping(payload) + + async def close(self, code: int = 1000, reason: str = "") -> None: + await self._state.close(code, reason) + + def __aiter__(self) -> AsyncIterator[WebSocketMessage]: + return self + + async def __anext__(self) -> WebSocketMessage: + try: + return await self.receive() + except WebSocketDisconnect as exc: + raise StopAsyncIteration from exc + + +class _WebSocketState: + """One coordinator-owned WebSocket protocol and mailbox state.""" + + def __init__( + self, + runtime: Any, + transport: Any, + client: Any, + request: Request, + route: _WebSocketRoute, + config: WebSocketConfig, + trailing_data: bytes, + ) -> None: + self.runtime = runtime + self.transport = transport + self.client = client + self.request = request + self.route = route + self.config = config + self.trailing_data = trailing_data + self.api = _load_wsproto() + self.protocol: Any = None + self.coordinator_task: Any = None + self.handler_task: Any = None + self.reader_task: Any = None + self.writer_task: Any = None + self.deadline_task: Any = None + self.accepted = False + self.rejected = False + self.shutdown = False + self.peer_closed = False + self.close_sent = False + self.subprotocol: str | None = None + self.disconnect: WebSocketDisconnect | None = None + self.handler_error: BaseException | None = None + self.inbox: deque[WebSocketMessage] = deque() + self.inbox_bytes = 0 + self.outbox: deque[_OutboundCommand] = deque() + self.outbox_bytes = 0 + self.writer_busy = False + self._message_kind: type | None = None + self._message_parts: list[str] | list[bytes] = [] + self._message_bytes = 0 + self._guard = _FrameGuard(config.max_frame_payload_bytes) + self.created_at = time.monotonic() + self.last_activity = self.created_at + self.pong_deadline: float | None = None + self.close_deadline: float | None = None + self._children: list[Any] = [] + + def _current_task(self) -> Any: + task = getattr(self.runtime, "cursor", None) + if task is None: + raise WebSocketStateError("WebSocket operations require a running SmallOS task") + return task + + @staticmethod + def _signal(task: Any, signal: int) -> None: + if task is not None: + accept = getattr(task, "acceptSignal", None) + if callable(accept): + accept(signal) + + async def _send_http(self, task: Any, response: Response) -> None: + headers = { + name: value + for name, value in response.headers.items() + if name.lower() != "connection" + } + headers["Connection"] = "close" + payload = Response(response.status, response.body, headers).to_http1() + await self.transport.send_all(task, self.client, payload) + + async def accept( + self, subprotocol: str | None, headers: Mapping[str, str] | None + ) -> None: + task = self._current_task() + if self.accepted or self.rejected: + raise WebSocketStateError("WebSocket handshake is already decided") + if subprotocol is not None: + if subprotocol not in self.route.subprotocols: + raise WebSocketStateError("selected subprotocol is not allowed by the route") + if subprotocol not in _token_list(self.request.headers.get("sec-websocket-protocol")): + raise WebSocketStateError("selected subprotocol was not offered by the client") + extra = Headers(headers or {}) + forbidden = { + "connection", + "upgrade", + "sec-websocket-accept", + "sec-websocket-protocol", + "content-length", + } + if any(name.lower() in forbidden for name in extra): + raise ValueError("handshake headers contain a reserved field") + key = self.request.headers["sec-websocket-key"].encode("ascii") + accept_value = base64.b64encode(hashlib.sha1(key + _GUID).digest()).decode("ascii") + lines = [ + "HTTP/1.1 101 Switching Protocols", + "Upgrade: websocket", + "Connection: Upgrade", + "Sec-WebSocket-Accept: {}".format(accept_value), + ] + if subprotocol is not None: + lines.append("Sec-WebSocket-Protocol: {}".format(subprotocol)) + lines.extend("{}: {}".format(name, value) for name, value in extra.items()) + payload = ("\r\n".join(lines) + "\r\n\r\n").encode("latin-1") + self.protocol = self.api.Connection(self.api.ConnectionType.SERVER) + await self.transport.send_all(task, self.client, payload) + self.subprotocol = subprotocol + self.accepted = True + self.last_activity = time.monotonic() + self._signal(self.coordinator_task, _DECISION_SIGNAL) + + async def reject(self, response: Response) -> None: + task = self._current_task() + if self.accepted or self.rejected: + raise WebSocketStateError("WebSocket handshake is already decided") + if not isinstance(response, Response): + raise TypeError("reject() requires a Response") + if response.status < 300: + raise ValueError("WebSocket rejection response must have status 300 or greater") + await self._send_http(task, response) + self.rejected = True + self._signal(self.coordinator_task, _DECISION_SIGNAL) + + def _require_open(self) -> None: + if not self.accepted: + raise WebSocketStateError("WebSocket must be accepted first") + if self.shutdown or self.disconnect is not None: + raise self.disconnect or WebSocketStateError("WebSocket is closed") + + async def receive(self) -> WebSocketMessage: + task = self._current_task() + if not self.accepted: + raise WebSocketStateError("WebSocket must be accepted first") + while not self.inbox: + if self.disconnect is not None: + raise self.disconnect + await task.wait_signal(_INBOX_SIGNAL) + message = self.inbox.popleft() + self.inbox_bytes -= _message_size(message.data) + return message + + async def send_message(self, value: str | bytes) -> None: + self._require_open() + size = _message_size(value) + if size > self.config.max_message_bytes: + raise WebSocketCapacityError("WebSocket message is too large") + event = ( + self.api.TextMessage(data=value) + if isinstance(value, str) + else self.api.BytesMessage(data=value) + ) + await self._enqueue(event, size, wait=True) + + async def ping(self, payload: bytes) -> None: + self._require_open() + await self._enqueue(self.api.Ping(payload=payload), len(payload), wait=True) + self.pong_deadline = time.monotonic() + self.config.pong_timeout + + async def close(self, code: int, reason: str) -> None: + self._require_open() + if not _valid_close_code(code): + raise ValueError("invalid WebSocket close code") + if not isinstance(reason, str) or len(reason.encode("utf-8")) > 123: + raise ValueError("WebSocket close reason must be at most 123 UTF-8 bytes") + await self._enqueue( + self.api.CloseConnection(code=code, reason=reason), + 2 + len(reason.encode("utf-8")), + wait=True, + ) + self.close_sent = True + self.close_deadline = time.monotonic() + self.config.close_timeout + task = self._current_task() + while not self.peer_closed and time.monotonic() < self.close_deadline: + await task.sleep(min(self.config.deadline_resolution, self.config.close_timeout)) + if self.disconnect is None: + self.disconnect = WebSocketDisconnect(code, reason) + + async def _enqueue(self, event: Any, size: int, *, wait: bool) -> None: + if ( + len(self.outbox) >= self.config.max_outbound_commands + or self.outbox_bytes + size > self.config.max_outbound_bytes + ): + raise WebSocketCapacityError("WebSocket outbound queue is full") + waiter = self._current_task() if wait else None + command = _OutboundCommand(event, size, waiter) + self.outbox.append(command) + self.outbox_bytes += size + self._signal(self.writer_task, _OUTBOX_SIGNAL) + if wait: + while not command.done: + await waiter.wait_signal(_ACK_SIGNAL) + if command.error is not None: + raise command.error + + def _enqueue_control(self, event: Any, size: int = 0) -> bool: + if ( + len(self.outbox) >= self.config.max_outbound_commands + or self.outbox_bytes + size > self.config.max_outbound_bytes + ): + return False + self.outbox.append(_OutboundCommand(event, size)) + self.outbox_bytes += size + self._signal(self.writer_task, _OUTBOX_SIGNAL) + return True + + def _deliver_message(self, value: str | bytes) -> bool: + size = _message_size(value) + if ( + len(self.inbox) >= self.config.max_inbound_messages + or self.inbox_bytes + size > self.config.max_inbound_bytes + ): + return False + self.inbox.append(WebSocketMessage(value)) + self.inbox_bytes += size + self._signal(self.handler_task, _INBOX_SIGNAL) + return True + + def _disconnect(self, code: int, reason: str = "") -> None: + if self.disconnect is None: + self.disconnect = WebSocketDisconnect(code, reason) + self._signal(self.handler_task, _INBOX_SIGNAL) + self._signal(self.coordinator_task, _DECISION_SIGNAL) + + def request_shutdown(self, code: int = 1001) -> None: + if self.shutdown: + return + self.shutdown = True + if self.accepted and not self.close_sent and self.protocol is not None: + self._enqueue_control( + self.api.CloseConnection(code=code, reason="server shutdown"), 17 + ) + self.close_sent = True + self._disconnect(code, "server shutdown") + self._signal(self.writer_task, _OUTBOX_SIGNAL) + + +def _token_list(value: str | None) -> tuple[str, ...]: + if value is None: + return () + return tuple(token.strip() for token in value.split(",") if token.strip()) + + +def _message_size(value: str | bytes) -> int: + return len(value.encode("utf-8")) if isinstance(value, str) else len(value) + + +def _valid_close_code(code: int) -> bool: + return type(code) is int and ( + 1000 <= code <= 1014 and code not in {1004, 1005, 1006} + or 3000 <= code <= 4999 + ) + + +def _valid_websocket_key(value: str | None) -> bool: + if value is None: + return False + try: + return len(base64.b64decode(value.encode("ascii"), validate=True)) == 16 + except (ValueError, UnicodeEncodeError): + return False + + +def _is_upgrade_attempt(request: Request) -> bool: + headers = request.headers + return bool( + headers.get("upgrade") + or headers.get("sec-websocket-key") + or headers.get("sec-websocket-version") + or any(token.lower() == "upgrade" for token in _token_list(headers.get("connection"))) + ) + + +def _validate_upgrade( + request: Request, route: _WebSocketRoute +) -> Response | None: + if request.method.upper() != "GET": + return Response.text("WebSocket upgrade requires GET", status=400) + if request.version != "HTTP/1.1": + return Response.text("WebSocket upgrade requires HTTP/1.1", status=400) + if request.body: + return Response.text("WebSocket upgrade must not include a body", status=400) + if request.headers.get("upgrade", "").lower() != "websocket": + return Response.text("invalid WebSocket Upgrade header", status=400) + connection_tokens = { + token.lower() for token in _token_list(request.headers.get("connection")) + } + if "upgrade" not in connection_tokens: + return Response.text("invalid WebSocket Connection header", status=400) + if request.headers.get("sec-websocket-version") != "13": + return Response.text( + "unsupported WebSocket version", + status=426, + headers={"Sec-WebSocket-Version": "13"}, + ) + if not _valid_websocket_key(request.headers.get("sec-websocket-key")): + return Response.text("invalid WebSocket key", status=400) + origin = request.headers.get("origin") + if route.origins is not None and origin not in route.origins: + return Response.text("WebSocket origin is not allowed", status=403) + return None + + +async def run_websocket_connection( + task: Any, state: _WebSocketState, server_handle: Any +) -> None: + """Coordinate one accepted HTTP connection through its WebSocket lifetime.""" + state.coordinator_task = task + server_handle._websocket_states[id(state.client)] = state + + def spawn(routine: Any, name: str) -> Any: + child = task.spawn( + routine, + priority=server_handle._config.connection_priority, + args=(state,), + name=name, + ) + state._children.append(child) + server_handle._owned_tasks.append(child) + return child + + try: + state.handler_task = spawn(_run_handler, "smallserver-websocket-handler") + state.deadline_task = spawn( + _run_deadlines, "smallserver-websocket-deadline" + ) + while not state.accepted and not state.rejected and state.disconnect is None: + await task.wait_signal(_DECISION_SIGNAL) + if not state.accepted: + return + state.writer_task = spawn(_run_writer, "smallserver-websocket-writer") + state.reader_task = spawn(_run_reader, "smallserver-websocket-reader") + try: + await task.join(state.handler_task) + except WebSocketDisconnect: + pass + except BaseException as exc: + state.handler_error = exc + + if state.handler_error is not None and not state.close_sent: + try: + await state._enqueue( + state.api.CloseConnection(code=1011, reason="handler failed"), + 16, + wait=True, + ) + state.close_sent = True + except BaseException: + pass + elif not state.close_sent and state.disconnect is None: + try: + await state._enqueue( + state.api.CloseConnection(code=1000, reason=""), 2, wait=True + ) + state.close_sent = True + except BaseException: + pass + + deadline = time.monotonic() + state.config.close_timeout + while ( + state.outbox or state.writer_busy or not state.peer_closed + ) and time.monotonic() < deadline: + await task.sleep( + min(state.config.deadline_resolution, state.config.close_timeout) + ) + finally: + state.request_shutdown() + for child in list(state._children): + if child is task: + continue + if ( + server_handle._cancel_or_retain_task(child) + and child in server_handle._owned_tasks + ): + server_handle._owned_tasks.remove(child) + state._children.clear() + server_handle._websocket_states.pop(id(state.client), None) + + +async def _run_handler(task: Any, state: _WebSocketState) -> None: + socket = WebSocket(state) + try: + result = state.route.handler(socket) + if not inspect.isawaitable(result): + raise TypeError("WebSocket handlers must return an awaitable") + await result + except WebSocketDisconnect: + pass + except BaseException as exc: + state.handler_error = exc + finally: + if not state.accepted and not state.rejected: + response = Response.text( + "internal server error" if state.handler_error is not None else "forbidden", + status=500 if state.handler_error is not None else 403, + ) + try: + await state.reject(response) + except BaseException: + state._disconnect(1006) + state._signal(state.coordinator_task, _DECISION_SIGNAL) + + +async def _run_writer(task: Any, state: _WebSocketState) -> None: + while not state.shutdown or state.outbox: + while state.outbox: + command = state.outbox.popleft() + state.outbox_bytes -= command.size + state.writer_busy = True + try: + payload = state.protocol.send(command.event) + for offset in range(0, len(payload), state.config.write_chunk_bytes): + await state.transport.send_all( + task, + state.client, + payload[offset : offset + state.config.write_chunk_bytes], + ) + state.last_activity = time.monotonic() + except BaseException as exc: + command.error = exc + state._disconnect(1006) + finally: + state.writer_busy = False + command.done = True + state._signal(command.waiter, _ACK_SIGNAL) + if not state.shutdown: + await task.wait_signal(_OUTBOX_SIGNAL) + + +async def _run_reader(task: Any, state: _WebSocketState) -> None: + try: + if state.trailing_data: + _receive_protocol_data(state, state.trailing_data) + state.trailing_data = b"" + if _drain_protocol_events(state): + return + while not state.shutdown: + chunk = await state.transport.recv( + task, state.client, state.config.receive_chunk_bytes + ) + if not chunk: + state.protocol.receive_data(None) + _drain_protocol_events(state) + state._disconnect(1006) + return + state.last_activity = time.monotonic() + _receive_protocol_data(state, chunk) + if _drain_protocol_events(state): + return + except WebSocketCapacityError: + if state.shutdown: + return + state._enqueue_control( + state.api.CloseConnection(code=1009, reason="message too large"), 19 + ) + state.close_sent = True + state._disconnect(1009, "message too large") + except BaseException: + if state.shutdown: + return + state._enqueue_control( + state.api.CloseConnection(code=1002, reason="protocol error"), 16 + ) + state.close_sent = True + state._disconnect(1002, "protocol error") + + +def _receive_protocol_data(state: _WebSocketState, data: bytes) -> None: + for chunk in state._guard.feed(data): + state.protocol.receive_data(chunk) + + +def _drain_protocol_events(state: _WebSocketState) -> bool: + for event in state.protocol.events(): + if isinstance(event, (state.api.TextMessage, state.api.BytesMessage)): + kind = str if isinstance(event, state.api.TextMessage) else bytes + if state._message_kind is None: + state._message_kind = kind + state._message_parts = [] + state._message_bytes = 0 + if state._message_kind is not kind: + raise ValueError("WebSocket message type changed during fragmentation") + state._message_bytes += _message_size(event.data) + if state._message_bytes > state.config.max_message_bytes: + raise WebSocketCapacityError("WebSocket message is too large") + state._message_parts.append(event.data) + if event.message_finished: + value = ( + "".join(state._message_parts) + if kind is str + else b"".join(state._message_parts) + ) + state._message_kind = None + state._message_parts = [] + state._message_bytes = 0 + if not state._deliver_message(value): + raise WebSocketCapacityError("WebSocket inbound queue is full") + elif isinstance(event, state.api.Ping): + if not state._enqueue_control(event.response(), len(event.payload)): + raise WebSocketCapacityError("WebSocket outbound queue is full") + elif isinstance(event, state.api.Pong): + state.pong_deadline = None + elif isinstance(event, state.api.CloseConnection): + state.peer_closed = True + if not state.close_sent: + if not state._enqueue_control(event.response(), 2): + raise WebSocketCapacityError("WebSocket outbound queue is full") + state.close_sent = True + state._disconnect(event.code, event.reason or "") + return True + return False + + +async def _run_deadlines(task: Any, state: _WebSocketState) -> None: + while not state.shutdown: + await task.sleep(state.config.deadline_resolution) + now = time.monotonic() + if not state.accepted and not state.rejected: + if now - state.created_at >= state.config.handshake_timeout: + try: + await state.reject( + Response.text("WebSocket handshake timed out", status=408) + ) + except BaseException: + state._disconnect(1006) + return + continue + if state.accepted and now - state.last_activity >= state.config.idle_timeout: + state._enqueue_control( + state.api.CloseConnection(code=1001, reason="idle timeout"), 14 + ) + state.close_sent = True + state._disconnect(1001, "idle timeout") + return + if state.pong_deadline is not None and now >= state.pong_deadline: + state._enqueue_control( + state.api.CloseConnection(code=1002, reason="Pong timeout"), 14 + ) + state.close_sent = True + state._disconnect(1002, "Pong timeout") + return diff --git a/tests/test_websocket.py b/tests/test_websocket.py new file mode 100644 index 0000000..40e37f6 --- /dev/null +++ b/tests/test_websocket.py @@ -0,0 +1,657 @@ +from __future__ import annotations + +import base64 +import importlib.util +import socket +import threading +import time +import unittest +from unittest.mock import patch + +from SmallPackage import SmallOS, SmallTask, SmallWebSocketClient, Unix + +from smallserver import ( + Headers, + Request, + Response, + SmallServer, + WebSocket, + WebSocketCapacityError, + WebSocketConfig, + WebSocketUnavailable, +) +from smallserver.websocket import ( + _FrameGuard, + _WebSocketState, + _WebSocketRoute, + _load_wsproto, + _validate_upgrade, +) + + +HAS_WSPROTO = importlib.util.find_spec("wsproto") is not None + + +def upgrade_request(**headers: str) -> Request: + values = { + "Host": "localhost", + "Upgrade": "websocket", + "Connection": "keep-alive, Upgrade", + "Sec-WebSocket-Version": "13", + "Sec-WebSocket-Key": "dGhlIHNhbXBsZSBub25jZQ==", + } + values.update(headers) + return Request("GET", "/ws", Headers(values)) + + +async def unused_handler(socket: WebSocket) -> None: + await socket.reject(Response(status=403)) + + +class WebSocketProtocolTests(unittest.TestCase): + def test_config_rejects_unbounded_or_inconsistent_limits(self) -> None: + with self.assertRaisesRegex(ValueError, "max_message_bytes"): + WebSocketConfig(max_message_bytes=0) + with self.assertRaisesRegex(ValueError, "must not exceed"): + WebSocketConfig(max_frame_payload_bytes=2, max_message_bytes=1) + with self.assertRaisesRegex(ValueError, "idle_timeout"): + WebSocketConfig(idle_timeout=float("inf")) + + def test_registration_is_lazy_and_coexists_with_get(self) -> None: + app = SmallServer() + + @app.get("/ws") + async def ordinary(request): + return Response.text("http") + + with patch("importlib.import_module") as importer: + + @app.websocket("/ws") + async def websocket(socket): + await socket.accept() + + importer.assert_not_called() + self.assertIsNotNone(app._router.static_handler("GET", "/ws")) + self.assertIn("/ws", app._websocket_routes) + + def test_missing_optional_engine_has_clear_error(self) -> None: + real_import = __import__("importlib").import_module + + def missing(name: str): + if name.startswith("wsproto"): + raise ImportError("missing") + return real_import(name) + + with patch("importlib.import_module", side_effect=missing): + with self.assertRaisesRegex(WebSocketUnavailable, "websocket.*extra"): + _load_wsproto() + + def test_upgrade_validation_and_rfc_example_accept_inputs(self) -> None: + route = _WebSocketRoute(unused_handler, None, ("chat.v1",)) + self.assertIsNone(_validate_upgrade(upgrade_request(), route)) + response = _validate_upgrade( + upgrade_request(**{"Sec-WebSocket-Version": "12"}), route + ) + self.assertIsNotNone(response) + assert response is not None + self.assertEqual(response.status, 426) + self.assertEqual(response.headers["sec-websocket-version"], "13") + for name, value in ( + ("Upgrade", "not-websocket"), + ("Connection", "keep-alive"), + ("Sec-WebSocket-Key", base64.b64encode(b"short").decode("ascii")), + ): + with self.subTest(name=name): + self.assertEqual( + _validate_upgrade(upgrade_request(**{name: value}), route).status, + 400, + ) + + def test_origin_policy_is_explicit(self) -> None: + route = _WebSocketRoute( + unused_handler, frozenset({"https://allowed.example"}), () + ) + denied = _validate_upgrade( + upgrade_request(Origin="https://denied.example"), route + ) + self.assertIsNotNone(denied) + assert denied is not None + self.assertEqual(denied.status, 403) + self.assertIsNone( + _validate_upgrade( + upgrade_request(Origin="https://allowed.example"), route + ) + ) + + @unittest.skipUnless(HAS_WSPROTO, "websocket extra is not installed") + def test_frame_guard_bounds_declared_length_before_payload(self) -> None: + guard = _FrameGuard(max_payload_bytes=1024) + declared = b"\x82\xff" + (65537).to_bytes(8, "big") + b"mask" + with self.assertRaises(WebSocketCapacityError): + for byte in declared: + guard.feed(bytes([byte])) + self.assertLessEqual(len(guard._header), 14) + + @unittest.skipUnless(HAS_WSPROTO, "websocket extra is not installed") + def test_partial_masked_fragmented_input_and_protocol_errors(self) -> None: + api = _load_wsproto() + client = api.Connection(api.ConnectionType.CLIENT) + server = api.Connection(api.ConnectionType.SERVER) + guard = _FrameGuard(1024) + payload = client.send( + api.TextMessage(data="hel", frame_finished=True, message_finished=False) + ) + client.send( + api.TextMessage(data="lo", frame_finished=True, message_finished=True) + ) + for byte in payload: + for chunk in guard.feed(bytes([byte])): + server.receive_data(chunk) + events = list(server.events()) + self.assertEqual("".join(event.data for event in events), "hello") + self.assertTrue(events[-1].message_finished) + with self.assertRaisesRegex(ValueError, "masked"): + _FrameGuard(1024).feed(b"\x81\x01x") + + @unittest.skipUnless(HAS_WSPROTO, "websocket extra is not installed") + def test_inbound_and_outbound_mailboxes_are_bounded(self) -> None: + config = WebSocketConfig( + max_frame_payload_bytes=8, + max_message_bytes=8, + max_inbound_messages=1, + max_inbound_bytes=3, + max_outbound_commands=1, + max_outbound_bytes=3, + ) + state = _WebSocketState( + object(), + object(), + object(), + upgrade_request(), + _WebSocketRoute(unused_handler, None, ()), + config, + b"", + ) + self.assertTrue(state._deliver_message("abc")) + self.assertFalse(state._deliver_message("x")) + self.assertTrue(state._enqueue_control(state.api.Ping(payload=b"abc"), 3)) + self.assertFalse(state._enqueue_control(state.api.Ping(payload=b"x"), 1)) + + +@unittest.skipUnless(HAS_WSPROTO, "websocket extra is not installed") +class WebSocketLoopbackTests(unittest.TestCase): + def _http_exchange(self, port: int, payload: bytes) -> bytes: + with socket.create_connection(("127.0.0.1", port), timeout=3) as stream: + stream.sendall(payload) + chunks = [] + while True: + chunk = stream.recv(4096) + if not chunk: + return b"".join(chunks) + chunks.append(chunk) + + def test_wsproto_client_interoperability_and_http_coexistence(self) -> None: + api = _load_wsproto() + runtime = SmallOS().setKernel(Unix()) + app = SmallServer( + websocket_config=WebSocketConfig( + max_frame_payload_bytes=4096, + max_message_bytes=4096, + idle_timeout=5, + handshake_timeout=2, + close_timeout=1, + ) + ) + + @app.get("/ws") + async def normal_get(request): + return Response.text("ordinary-http") + + @app.websocket( + "/ws", + origins={"https://allowed.example"}, + subprotocols=("chat.v1",), + ) + async def echo(websocket: WebSocket) -> None: + await websocket.accept(subprotocol="chat.v1") + async for message in websocket: + if message.is_text: + await websocket.send_text(message.text) + else: + await websocket.send_bytes(message.bytes) + + try: + server = app.serve(runtime, host="127.0.0.1", port=0) + except PermissionError: + self.skipTest("the current sandbox does not permit loopback TCP binds") + + outcomes: list[object] = [] + errors: list[BaseException] = [] + + def client_work() -> None: + try: + ordinary = self._http_exchange( + server.port, + b"GET /ws HTTP/1.1\r\nHost: localhost\r\n\r\n", + ) + outcomes.append(ordinary) + with socket.create_connection( + ("127.0.0.1", server.port), timeout=3 + ) as stream: + stream.sendall( + b"GET /ws?room=1 HTTP/1.1\r\n" + b"Host: localhost\r\n" + b"Upgrade: websocket\r\n" + b"Connection: keep-alive, Upgrade\r\n" + b"Sec-WebSocket-Version: 13\r\n" + b"Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==\r\n" + b"Sec-WebSocket-Protocol: chat.v1\r\n" + b"Origin: https://allowed.example\r\n\r\n" + ) + response = b"" + while b"\r\n\r\n" not in response: + response += stream.recv(4096) + outcomes.append(response) + client = api.Connection(api.ConnectionType.CLIENT) + stream.sendall( + client.send( + api.TextMessage( + data="hel", + frame_finished=True, + message_finished=False, + ) + ) + + client.send( + api.TextMessage( + data="lo", + frame_finished=True, + message_finished=True, + ) + ) + ) + outcomes.extend(_receive_events(stream, client, api.TextMessage)) + stream.sendall(client.send(api.BytesMessage(data=b"binary"))) + outcomes.extend(_receive_events(stream, client, api.BytesMessage)) + stream.sendall(client.send(api.Ping(payload=b"probe"))) + outcomes.extend(_receive_events(stream, client, api.Pong)) + stream.sendall( + client.send(api.CloseConnection(code=1000, reason="done")) + ) + outcomes.extend(_receive_events(stream, client, api.CloseConnection)) + except BaseException as exc: + errors.append(exc) + finally: + server.close() + + worker = threading.Thread(target=client_work, daemon=True) + worker.start() + runtime.start() + worker.join(timeout=5) + + self.assertFalse(worker.is_alive()) + self.assertEqual(errors, []) + self.assertIn(b"ordinary-http", outcomes[0]) + self.assertIn(b"HTTP/1.1 101 Switching Protocols", outcomes[1]) + self.assertIn(b"Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=", outcomes[1]) + self.assertIn(b"Sec-WebSocket-Protocol: chat.v1", outcomes[1]) + self.assertTrue(any(getattr(event, "data", None) == "hello" for event in outcomes)) + self.assertTrue(any(getattr(event, "data", None) == b"binary" for event in outcomes)) + self.assertTrue(any(getattr(event, "payload", None) == b"probe" for event in outcomes)) + self.assertTrue( + any(getattr(event, "code", None) == 1000 for event in outcomes), + outcomes, + ) + self.assertEqual(server._websocket_states, {}) + self.assertEqual(runtime.ioReadWaiters, {}) + self.assertEqual(runtime.ioWriteWaiters, {}) + + def test_smallos_websocket_client_interoperability(self) -> None: + runtime = SmallOS().setKernel(Unix()) + app = SmallServer( + websocket_config=WebSocketConfig( + max_frame_payload_bytes=4096, + max_message_bytes=4096, + idle_timeout=5, + close_timeout=1, + ) + ) + + @app.websocket("/native", subprotocols=("smallos.v1",)) + async def echo(websocket: WebSocket) -> None: + await websocket.accept(subprotocol="smallos.v1") + message = await websocket.receive() + await websocket.send_text(message.text) + + try: + server = app.serve(runtime, host="127.0.0.1", port=0) + except PermissionError: + self.skipTest("the current sandbox does not permit loopback TCP binds") + + outcome: dict[str, object] = {} + + async def client_job(task) -> None: + client = SmallWebSocketClient( + task, + host="127.0.0.1", + port=server.port, + client_key="dGhlIHNhbXBsZSBub25jZQ==", + ) + try: + await client.connect("/native", subprotocols=("smallos.v1",)) + outcome["subprotocol"] = client.negotiated_subprotocol + await client.send_text("native-client") + outcome["message"] = await client.receive() + finally: + await client.disconnect() + server.close() + + client_task = SmallTask(2, client_job, name="smallserver-ws-client") + runtime.fork(client_task) + runtime.start() + + self.assertIsNone(client_task.exception) + self.assertEqual(outcome["subprotocol"], "smallos.v1") + self.assertEqual( + outcome["message"], {"type": "text", "data": "native-client"} + ) + self.assertTrue(server.finished) + self.assertEqual(runtime.ioReadWaiters, {}) + self.assertEqual(runtime.ioWriteWaiters, {}) + + def test_waiting_websocket_does_not_delay_unrelated_http(self) -> None: + runtime = SmallOS().setKernel(Unix()) + app = SmallServer( + websocket_config=WebSocketConfig( + max_frame_payload_bytes=4096, + max_message_bytes=4096, + idle_timeout=5, + close_timeout=1, + ) + ) + + @app.get("/fast") + async def fast(request): + return Response.text("fast") + + @app.websocket("/waiting") + async def waiting(websocket: WebSocket) -> None: + await websocket.accept() + await websocket.receive() + + try: + server = app.serve(runtime, host="127.0.0.1", port=0) + except PermissionError: + self.skipTest("the current sandbox does not permit loopback TCP binds") + + api = _load_wsproto() + outcomes: list[bytes] = [] + errors: list[BaseException] = [] + + def client_work() -> None: + try: + with socket.create_connection( + ("127.0.0.1", server.port), timeout=3 + ) as websocket_stream: + websocket_stream.sendall( + b"GET /waiting HTTP/1.1\r\nHost: localhost\r\n" + b"Upgrade: websocket\r\nConnection: Upgrade\r\n" + b"Sec-WebSocket-Version: 13\r\n" + b"Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==\r\n\r\n" + ) + response = b"" + while b"\r\n\r\n" not in response: + response += websocket_stream.recv(4096) + outcomes.append(response) + outcomes.append( + self._http_exchange( + server.port, + b"GET /fast HTTP/1.1\r\nHost: localhost\r\n\r\n", + ) + ) + client = api.Connection(api.ConnectionType.CLIENT) + websocket_stream.sendall( + client.send(api.CloseConnection(code=1000, reason="done")) + ) + _receive_events( + websocket_stream, client, api.CloseConnection + ) + except BaseException as exc: + errors.append(exc) + finally: + server.close() + + worker = threading.Thread(target=client_work, daemon=True) + worker.start() + runtime.start() + worker.join(timeout=5) + + self.assertFalse(worker.is_alive()) + self.assertEqual(errors, []) + self.assertIn(b"HTTP/1.1 101 Switching Protocols", outcomes[0]) + self.assertIn(b"fast", outcomes[1]) + self.assertTrue(server.finished) + + def test_malformed_and_oversized_frames_close_with_safe_codes(self) -> None: + runtime = SmallOS().setKernel(Unix()) + app = SmallServer( + websocket_config=WebSocketConfig( + max_frame_payload_bytes=8, + max_message_bytes=8, + idle_timeout=5, + close_timeout=1, + ) + ) + + @app.websocket("/bounded") + async def bounded(websocket: WebSocket) -> None: + await websocket.accept() + await websocket.receive() + + try: + server = app.serve(runtime, host="127.0.0.1", port=0) + except PermissionError: + self.skipTest("the current sandbox does not permit loopback TCP binds") + + api = _load_wsproto() + close_codes: list[int | None] = [] + errors: list[BaseException] = [] + + def send_bad_frame(frame: bytes) -> None: + with socket.create_connection( + ("127.0.0.1", server.port), timeout=3 + ) as stream: + stream.sendall( + b"GET /bounded HTTP/1.1\r\nHost: localhost\r\n" + b"Upgrade: websocket\r\nConnection: Upgrade\r\n" + b"Sec-WebSocket-Version: 13\r\n" + b"Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==\r\n\r\n" + ) + response = b"" + while b"\r\n\r\n" not in response: + response += stream.recv(4096) + stream.sendall(frame) + client = api.Connection(api.ConnectionType.CLIENT) + events = _receive_events(stream, client, api.CloseConnection) + close = next( + event for event in events if isinstance(event, api.CloseConnection) + ) + close_codes.append(close.code) + stream.sendall(client.send(close.response())) + + def client_work() -> None: + try: + send_bad_frame(b"\x81\x01x") + send_bad_frame(b"\x82\xfe\x00\x7emask") + except BaseException as exc: + errors.append(exc) + finally: + server.close() + + worker = threading.Thread(target=client_work, daemon=True) + worker.start() + runtime.start() + worker.join(timeout=5) + + self.assertFalse(worker.is_alive()) + self.assertEqual(errors, []) + self.assertEqual(close_codes, [1002, 1009]) + self.assertTrue(server.finished) + + def test_server_shutdown_attempts_close_and_releases_children(self) -> None: + api = _load_wsproto() + runtime = SmallOS().setKernel(Unix()) + app = SmallServer( + websocket_config=WebSocketConfig( + max_frame_payload_bytes=4096, + max_message_bytes=4096, + close_timeout=1, + idle_timeout=5, + ) + ) + + @app.websocket("/live") + async def live(websocket: WebSocket) -> None: + await websocket.accept() + await websocket.receive() + + try: + server = app.serve(runtime, host="127.0.0.1", port=0) + except PermissionError: + self.skipTest("the current sandbox does not permit loopback TCP binds") + + close_events: list[object] = [] + states: list[object] = [] + errors: list[BaseException] = [] + + def client_work() -> None: + try: + with socket.create_connection( + ("127.0.0.1", server.port), timeout=3 + ) as stream: + stream.sendall( + b"GET /live HTTP/1.1\r\nHost: localhost\r\n" + b"Upgrade: websocket\r\nConnection: Upgrade\r\n" + b"Sec-WebSocket-Version: 13\r\n" + b"Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==\r\n\r\n" + ) + response = b"" + while b"\r\n\r\n" not in response: + response += stream.recv(4096) + client = api.Connection(api.ConnectionType.CLIENT) + states.extend(server._websocket_states.values()) + server.close() + events = _receive_events(stream, client, api.CloseConnection) + close_events.extend(events) + close_event = next( + event + for event in events + if isinstance(event, api.CloseConnection) + ) + stream.sendall(client.send(close_event.response())) + except BaseException as exc: + errors.append(exc) + + worker = threading.Thread(target=client_work, daemon=True) + worker.start() + runtime.start() + worker.join(timeout=5) + + self.assertFalse(worker.is_alive()) + self.assertEqual(errors, []) + self.assertTrue( + any(getattr(event, "code", None) == 1001 for event in close_events), + ( + close_events, + states[0].disconnect if states else None, + states[0].handler_error if states else None, + ), + ) + self.assertTrue(server.finished) + self.assertEqual(server._websocket_states, {}) + self.assertEqual(runtime.ioReadWaiters, {}) + self.assertEqual(runtime.ioWriteWaiters, {}) + + def test_handler_failure_sends_sanitized_1011_close(self) -> None: + api = _load_wsproto() + runtime = SmallOS().setKernel(Unix()) + app = SmallServer( + websocket_config=WebSocketConfig( + max_frame_payload_bytes=4096, + max_message_bytes=4096, + close_timeout=1, + idle_timeout=5, + ) + ) + + @app.websocket("/fail") + async def fail(websocket: WebSocket) -> None: + await websocket.accept() + raise RuntimeError("sensitive-handler-detail") + + try: + server = app.serve(runtime, host="127.0.0.1", port=0) + except PermissionError: + self.skipTest("the current sandbox does not permit loopback TCP binds") + + close_events: list[object] = [] + errors: list[BaseException] = [] + + def client_work() -> None: + try: + with socket.create_connection( + ("127.0.0.1", server.port), timeout=3 + ) as stream: + stream.sendall( + b"GET /fail HTTP/1.1\r\nHost: localhost\r\n" + b"Upgrade: websocket\r\nConnection: Upgrade\r\n" + b"Sec-WebSocket-Version: 13\r\n" + b"Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==\r\n\r\n" + ) + response = b"" + while b"\r\n\r\n" not in response: + response += stream.recv(4096) + client = api.Connection(api.ConnectionType.CLIENT) + events = _receive_events(stream, client, api.CloseConnection) + close_events.extend(events) + close_event = next( + event + for event in events + if isinstance(event, api.CloseConnection) + ) + stream.sendall(client.send(close_event.response())) + except BaseException as exc: + errors.append(exc) + finally: + server.close() + + worker = threading.Thread(target=client_work, daemon=True) + worker.start() + runtime.start() + worker.join(timeout=5) + + self.assertFalse(worker.is_alive()) + self.assertEqual(errors, []) + failure = next( + event for event in close_events if isinstance(event, api.CloseConnection) + ) + self.assertEqual(failure.code, 1011) + self.assertNotIn("sensitive", failure.reason) + self.assertTrue(server.finished) + + +def _receive_events(stream, connection, event_type): + deadline = time.monotonic() + 3 + received = [] + while time.monotonic() < deadline: + data = stream.recv(4096) + if not data: + return received + connection.receive_data(data) + events = list(connection.events()) + received.extend(events) + if any(isinstance(event, event_type) for event in events): + return received + raise TimeoutError("expected WebSocket event was not received") + + +if __name__ == "__main__": + unittest.main() diff --git a/tests/typing/websocket_routes.py b/tests/typing/websocket_routes.py new file mode 100644 index 0000000..910ecd5 --- /dev/null +++ b/tests/typing/websocket_routes.py @@ -0,0 +1,14 @@ +from smallserver import SmallServer, WebSocket, WebSocketMessage + + +app = SmallServer() + + +@app.websocket("/chat", subprotocols=("chat.v1",)) +async def chat(socket: WebSocket) -> None: + await socket.accept(subprotocol="chat.v1") + message: WebSocketMessage = await socket.receive() + if message.is_text: + await socket.send_text(message.text) + else: + await socket.send_bytes(message.bytes) From 71acd3993af40c90fa4bce5b514b999567711c00 Mon Sep 17 00:00:00 2001 From: Michael Emperador Date: Sat, 22 Aug 2026 02:01:07 -0500 Subject: [PATCH 07/14] docs: add WebSocket examples and guide --- README.md | 33 +++++++++++++++++++++++- demo.py | 12 ++++++++- examples/websocket_echo.py | 28 ++++++++++++++++++++ guide/websockets.md | 52 ++++++++++++++++++++++++++++++++++++++ 4 files changed, 123 insertions(+), 2 deletions(-) create mode 100644 examples/websocket_echo.py create mode 100644 guide/websockets.md diff --git a/README.md b/README.md index 04846b4..66dfe0b 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,9 @@ The current package provides an HTTP/1.1 baseline over a SmallOS runtime. It can - parse one `Content-Length` HTTP/1.1 request per connection and close after its response. -Keep-alive/pipelining, TLS, automatic path templates, and HTTP/2 are not +RFC 6455 WebSockets over HTTP/1.1 Upgrade are available through the optional +`websocket` extra. Keep-alive/pipelining, TLS, automatic path templates, +compression, RFC 8441 WebSockets over HTTP/2, and HTTP/2 itself are not implemented yet. ## Install for development @@ -40,6 +42,12 @@ python3 -m pip install -e '.[regex-routes]' Static routing neither imports nor requires that dependency. +Install the optional WebSocket protocol engine when serving WebSocket routes: + +```bash +python3 -m pip install -e '.[websocket]' +``` + SmallOS is installed from the canonical `master` branch in `requirements.txt`. It owns scheduling, socket readiness, and foreign execution adapters. @@ -206,6 +214,29 @@ Static route lookup is dictionary-based and always takes precedence over a regex route for the same method and path. Richer lifecycle hooks are deferred; the current `ServerHandle` provides explicit shutdown. +## WebSocket routes + +Register WebSockets independently from HTTP routes. The same path may also +have a normal GET handler because only an Upgrade candidate enters the +WebSocket route table. + +```python +from smallserver import WebSocket + +@app.websocket("/echo") +async def echo(socket: WebSocket) -> None: + await socket.accept() + async for message in socket: + if message.is_text: + await socket.send_text(message.text) + else: + await socket.send_bytes(message.bytes) +``` + +See [`guide/websockets.md`](guide/websockets.md) and the runnable +[`examples/websocket_echo.py`](examples/websocket_echo.py) for origin, +subprotocol, capacity, and lifecycle details. + ## Define regular-expression routes Regex routes use full-path matching and run in registration order after static diff --git a/demo.py b/demo.py index bfa2f07..1fc7613 100644 --- a/demo.py +++ b/demo.py @@ -4,7 +4,7 @@ import json -from smallserver import HTTPError, Request, Response, SmallServer +from smallserver import HTTPError, Request, Response, SmallServer, WebSocket app = SmallServer() @@ -81,6 +81,16 @@ async def delete_task(request: Request) -> Response: return Response(status=204) +@app.websocket("/ws") +async def websocket_echo(socket: WebSocket) -> None: + await socket.accept() + async for message in socket: + if message.is_text: + await socket.send_text(message.text) + else: + await socket.send_bytes(message.bytes) + + if __name__ == "__main__": print("Starting SmallServer on http://127.0.0.1:8000") app.listen(host="127.0.0.1", port=8000) diff --git a/examples/websocket_echo.py b/examples/websocket_echo.py new file mode 100644 index 0000000..01bf4d3 --- /dev/null +++ b/examples/websocket_echo.py @@ -0,0 +1,28 @@ +"""Run a bounded WebSocket echo endpoint on localhost:8000.""" + +from smallserver import SmallServer, WebSocket, WebSocketConfig + + +app = SmallServer( + websocket_config=WebSocketConfig( + max_frame_payload_bytes=64 * 1024, + max_message_bytes=256 * 1024, + max_inbound_messages=8, + max_outbound_commands=8, + ) +) + + +@app.websocket("/echo", subprotocols=("echo.v1",)) +async def echo(socket: WebSocket) -> None: + await socket.accept(subprotocol="echo.v1") + async for message in socket: + if message.is_text: + await socket.send_text(message.text) + else: + await socket.send_bytes(message.bytes) + + +if __name__ == "__main__": + print("Starting WebSocket echo server on ws://127.0.0.1:8000/echo") + app.listen(host="127.0.0.1", port=8000) diff --git a/guide/websockets.md b/guide/websockets.md new file mode 100644 index 0000000..4413e2d --- /dev/null +++ b/guide/websockets.md @@ -0,0 +1,52 @@ +# WebSockets + +Install the optional protocol engine before serving WebSocket routes: + +```bash +python3 -m pip install -e '.[websocket]' +``` + +WebSocket routes use HTTP/1.1 Upgrade while SmallOS continues to own task +scheduling and socket readiness. A normal `GET` route may use the same path; +requests without Upgrade headers remain ordinary HTTP requests. + +```python +from smallserver import SmallServer, WebSocket + +app = SmallServer() + +@app.websocket( + "/chat", + origins={"https://app.example.com"}, + subprotocols=("chat.v1",), +) +async def chat(socket: WebSocket) -> None: + await socket.accept(subprotocol="chat.v1") + async for message in socket: + if message.is_text: + await socket.send_text(message.text) + else: + await socket.send_bytes(message.bytes) + +app.listen() +``` + +The application must explicitly call `accept()` or `reject()` before using +message operations. Returning without either decision sends a sanitized 403. +Text, binary, fragmented messages, Ping/Pong, and Close are supported. Queue, +frame, message, connection, handshake, idle, Pong, and close limits are finite +and configurable through `WebSocketConfig`. + +An origin allowlist is strongly recommended when browser credentials or +cookies are involved. A selected subprotocol must have been offered by the +client and allowed by the route. Outbound saturation raises +`WebSocketCapacityError`; peer or server closure raises `WebSocketDisconnect` +from receive operations. + +Send calls complete after the serialized frame bytes have been flushed through +the connection writer. They do not mean the peer application has processed the +message. + +This release does not implement `wss://` termination, compression, custom +extensions, or RFC 8441 WebSockets over HTTP/2. Put TLS at a trusted reverse +proxy until SmallServer gains a native TLS boundary. From d28d41e155bb0c31ba67901847a345ec2e8b757c Mon Sep 17 00:00:00 2001 From: Michael Emperador Date: Sat, 22 Aug 2026 02:02:15 -0500 Subject: [PATCH 08/14] test: cover WebSocket deadlines and interoperability --- tests/test_websocket.py | 115 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 115 insertions(+) diff --git a/tests/test_websocket.py b/tests/test_websocket.py index 40e37f6..b2cc9bc 100644 --- a/tests/test_websocket.py +++ b/tests/test_websocket.py @@ -496,6 +496,121 @@ def client_work() -> None: self.assertEqual(close_codes, [1002, 1009]) self.assertTrue(server.finished) + def test_handshake_idle_and_pong_deadlines_are_bounded(self) -> None: + runtime = SmallOS().setKernel(Unix()) + app = SmallServer( + websocket_config=WebSocketConfig( + max_frame_payload_bytes=1024, + max_message_bytes=1024, + handshake_timeout=0.1, + idle_timeout=0.2, + pong_timeout=0.05, + close_timeout=0.2, + deadline_resolution=0.01, + ) + ) + + @app.websocket("/handshake-timeout") + async def handshake_timeout(websocket: WebSocket) -> None: + await runtime.cursor.sleep(1) + + @app.websocket("/idle-timeout") + async def idle_timeout(websocket: WebSocket) -> None: + await websocket.accept() + await websocket.receive() + + @app.websocket("/pong-timeout") + async def pong_timeout(websocket: WebSocket) -> None: + await websocket.accept() + await websocket.ping(b"deadline") + await websocket.receive() + + try: + server = app.serve(runtime, host="127.0.0.1", port=0) + except PermissionError: + self.skipTest("the current sandbox does not permit loopback TCP binds") + + api = _load_wsproto() + outcomes: dict[str, object] = {} + errors: list[BaseException] = [] + + def connect(path: str): + stream = socket.create_connection(("127.0.0.1", server.port), timeout=3) + stream.sendall( + "GET {} HTTP/1.1\r\nHost: localhost\r\n" + "Upgrade: websocket\r\nConnection: Upgrade\r\n" + "Sec-WebSocket-Version: 13\r\n" + "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==\r\n\r\n".format( + path + ).encode("ascii") + ) + response = b"" + while b"\r\n\r\n" not in response: + response += stream.recv(4096) + return stream, response + + def client_work() -> None: + try: + stream, response = connect("/handshake-timeout") + outcomes["handshake"] = response + stream.close() + + stream, response = connect("/idle-timeout") + outcomes["idle_handshake"] = response + idle_client = api.Connection(api.ConnectionType.CLIENT) + idle_events = _receive_events( + stream, idle_client, api.CloseConnection + ) + idle_close = next( + event + for event in idle_events + if isinstance(event, api.CloseConnection) + ) + outcomes["idle_code"] = idle_close.code + stream.sendall(idle_client.send(idle_close.response())) + stream.close() + + stream, response = connect("/pong-timeout") + outcomes["pong_handshake"] = response + pong_client = api.Connection(api.ConnectionType.CLIENT) + ping_events = _receive_events(stream, pong_client, api.Ping) + outcomes["ping_payload"] = next( + event.payload + for event in ping_events + if isinstance(event, api.Ping) + ) + close_events = _receive_events( + stream, pong_client, api.CloseConnection + ) + pong_close = next( + event + for event in close_events + if isinstance(event, api.CloseConnection) + ) + outcomes["pong_code"] = pong_close.code + stream.sendall(pong_client.send(pong_close.response())) + stream.close() + except BaseException as exc: + errors.append(exc) + finally: + server.close() + + worker = threading.Thread(target=client_work, daemon=True) + worker.start() + runtime.start() + worker.join(timeout=5) + + self.assertFalse(worker.is_alive()) + self.assertEqual(errors, []) + self.assertIn(b"HTTP/1.1 408 Request Timeout", outcomes["handshake"]) + self.assertIn( + b"HTTP/1.1 101 Switching Protocols", outcomes["idle_handshake"] + ) + self.assertEqual(outcomes["idle_code"], 1001) + self.assertEqual(outcomes["ping_payload"], b"deadline") + self.assertEqual(outcomes["pong_code"], 1002) + self.assertTrue(server.finished) + def test_server_shutdown_attempts_close_and_releases_children(self) -> None: api = _load_wsproto() runtime = SmallOS().setKernel(Unix()) From 155eb97b5743539300d28afe8ca8344ceac55ed9 Mon Sep 17 00:00:00 2001 From: Michael Emperador Date: Sat, 22 Aug 2026 02:19:41 -0500 Subject: [PATCH 09/14] docs: add comprehensive public guide --- README.md | 326 ++++---------------------------- guide/adapters.md | 49 +++++ guide/api-reference.md | 73 +++++++ guide/configuration.md | 44 +++++ guide/development.md | 52 +++++ guide/errors-observability.md | 51 +++++ guide/getting-started.md | 63 ++++++ guide/index.md | 27 +++ guide/platforms-kernels.md | 40 ++++ guide/protocol-roadmap.md | 36 ++++ guide/requests-and-responses.md | 65 +++++++ guide/routing.md | 45 +++++ guide/runtime-lifecycle.md | 78 ++++++++ tests/test_documentation.py | 77 ++++++++ 14 files changed, 741 insertions(+), 285 deletions(-) create mode 100644 guide/adapters.md create mode 100644 guide/api-reference.md create mode 100644 guide/configuration.md create mode 100644 guide/development.md create mode 100644 guide/errors-observability.md create mode 100644 guide/getting-started.md create mode 100644 guide/index.md create mode 100644 guide/platforms-kernels.md create mode 100644 guide/protocol-roadmap.md create mode 100644 guide/requests-and-responses.md create mode 100644 guide/routing.md create mode 100644 guide/runtime-lifecycle.md create mode 100644 tests/test_documentation.py diff --git a/README.md b/README.md index 3c7598b..5c66963 100644 --- a/README.md +++ b/README.md @@ -1,305 +1,61 @@ # SmallServer -SmallServer is a SmallOS-native web framework in early development. It provides -a bounded HTTP/1.1 server, static async routing for GET, POST, PUT, PATCH, and -DELETE, and explicit escape hatches for blocking and asyncio-native libraries. - -## Current scope - -The current package provides an HTTP/1.1 baseline over a SmallOS runtime. It can: - -- register static async routes for GET, POST, PUT, PATCH, and DELETE; -- dispatch an already-created `Request` to a handler; -- return deterministic `Response` values, including HTTP/1.1 bytes; -- return 404 for an unknown path and 405 with `Allow` for a known path using - the wrong method. -- bind a non-blocking TCP listener, accept bounded concurrent connections, and - wait for read/write readiness through SmallOS; -- parse one `Content-Length` HTTP/1.1 request per connection and close after - its response. - -Keep-alive/pipelining, TLS, path parameters, and HTTP/2 are not implemented yet. - -## Install for development - -```bash -python3 -m pip install -r requirements.txt -python3 -m pip install -e . -python3 -m unittest discover -s tests -v -``` - -SmallOS is installed from the canonical `master` branch in `requirements.txt`. -It owns scheduling, socket readiness, and foreign execution adapters. - -## Run the demo - -The included demo starts a task API at `http://127.0.0.1:8000`. Common -application code does not need to import or configure SmallOS. - -```bash -python3 -m pip install -r requirements.txt -python3 demo.py -``` - -Leave the process running and exercise GET, POST, PUT, PATCH, and DELETE from a -browser or HTTP client. Press Ctrl-C for deterministic cleanup without a -traceback. The static `/tasks` path is intentional: path parameters arrive -with a later milestone. - -## Bind a server - -Create the application and call blocking `listen()`. It lazily creates a -SmallOS runtime with the Unix kernel, while SmallOS remains the scheduler and -owner of socket readiness. `port=0` asks the operating system for an available -port, which is useful in tests and local tooling. +SmallServer is a small, SmallOS-native HTTP framework for Python 3.10+. The +current base serves bounded HTTP/1.1 requests, routes exact paths to async +handlers, and provides explicit lifecycle and third-party execution controls. ```python from smallserver import Response, SmallServer app = SmallServer() -@app.get("/health") -async def health(request): - return Response.json({"status": "ok"}) - -app.listen(host="127.0.0.1", port=8000) -``` - -Managed `listen()` blocks and catches Ctrl-C after closing its listener, wakeup -channel, connections, and server tasks. It returns the closed `ServerHandle`, -whose cached `address` and `port` remain available for diagnostics. Each -current connection accepts one request and sends a `Connection: close` -response. - -If the runtime exits normally but cleanup is incomplete, `listen()` raises -`ServerFinalizationError`; retain it and call `retry_cleanup()` until it -succeeds. If runtime startup raises while cleanup is incomplete, ordinary -failures are wrapped by `ServerStartupError`; `KeyboardInterrupt` and -`SystemExit` keep their identity and expose that cleanup owner as `__cause__`. -Until cleanup succeeds, the application rejects another listener invocation. - -## Advanced runtime control - -Supply a configured runtime when the application needs to coordinate other -SmallOS tasks. A supplied runtime is never reconfigured or destroyed, and -`start=False` schedules the server without starting it: - -```python -from SmallPackage import SmallOS, Unix -from smallserver import Response, SmallServer - -runtime = SmallOS().setKernel(Unix()) -app = SmallServer() @app.get("/health") async def health(request): return Response.json({"status": "ok"}) -server = app.listen(runtime=runtime, start=False) -try: - runtime.start() -finally: - server.finalize() -``` - -On a kernel with `supports_wakeup_channel() == True`, call `server.close()` -from another thread or client-control path to request scheduler-safe shutdown. -`Unix` provides this cross-thread wakeup capability. - -Constrained kernels may support TCP servers without supporting a thread-safe -wakeup channel. On those kernels, `server.close()` raises instead of mutating -runtime state from an unsafe context. A currently running SmallOS task can use -`await server.close_from_task(task)` to close on the scheduler thread. The -handle's `finished` property becomes true only after the listener, every -connection, and the wakeup channel have closed successfully; `cleanup_errors` -reports close failures that remain available for a later scheduler-side retry. - -If startup fails and the kernel also fails to release an acquired listener or -wakeup resource, `serve()` raises `ServerStartupError`. Its `primary_error` -preserves the startup failure and `cleanup_errors` reports the outstanding -cleanup attempts without exposing kernel handles. Keep the exception and call -`retry_cleanup()` (or `finalize()`) until it returns `True`; later calls remain -safe and return `True`. `KeyboardInterrupt` and `SystemExit` are always -re-raised as the identical exception; when rollback is incomplete, their -`__cause__` is the `ServerStartupError` cleanup owner. Abandoning an incomplete -startup error performs one best-effort cleanup retry and emits a -`ResourceWarning` if resources remain owned. - -`max_connections` bounds every connection stream still owned by the server, -including streams retained after a failed close. At capacity the listener -blocks on a SmallOS scheduler signal without polling or accepting another -connection; releasing capacity signals the listener. Any connection close -failure is fatal and stops further acceptance while retaining the stream for -an explicit shutdown-cleanup retry. - -Each current connection accepts one request and sends a `Connection: close` -response. - -`app.serve(runtime, ...)` remains the equivalent schedule-and-return -compatibility API. `listen(runtime=runtime, start=True)` starts the supplied -runtime exactly once and finalizes only server-owned resources when it exits; -the runtime itself still belongs to the caller. - -While the scheduler is running on a kernel with a wakeup channel, -`server.close()` is the thread-safe shutdown signal. Kernels without that -capability must call `await server.close_from_task(task)` from their currently -running SmallOS task. After a manually started scheduler has already exited or -failed, `server.finalize()` is the idempotent owner-thread cleanup operation on -either kind of kernel. - -Execution adapters are likewise application-owned. Construct and close them -around the runtime lifecycle rather than expecting managed `listen()` to -create or stop adapter threads or asyncio loops. See -[`examples/manual_runtime.py`](examples/manual_runtime.py) for the complete -manual shape. - -Only one listener invocation can be active on an application at a time. Once -its handle reports `finished`, all retained cleanup has completed and the same -application can listen again. A failed cleanup attempt keeps the invocation -reserved until a later successful retry. - -## Define routes - -Use one decorator for each supported method. Handlers receive an immutable -`Request` and must return a `Response`. - -```python -from smallserver import Request, Response, SmallServer - -app = SmallServer() - -@app.get("/health") -async def health(request: Request) -> Response: - return Response.json({"status": "ok"}) - -@app.post("/widgets") -async def create_widget(request: Request) -> Response: - # request.body is always bytes. - return Response.json({"created": True}, status=201) - -@app.put("/widgets") -async def replace_widgets(request: Request) -> Response: - return Response.text("replaced") - -@app.patch("/widgets") -async def patch_widgets(request: Request) -> Response: - return Response.text("updated") - -@app.delete("/widgets") -async def delete_widgets(request: Request) -> Response: - return Response(status=204) -``` - -Route paths are static in this release. Path parameters and richer lifecycle -hooks are deferred; the current `ServerHandle` provides explicit shutdown. - -## Dispatch a request -The listener creates requests and calls `dispatch()`. The same boundary is -useful in application tests: - -```python -request = Request( - method="GET", - path="/health", - headers={"Accept": "application/json"}, -) - -response = await app.dispatch(request) -assert response.status == 200 -assert response.body == b'{"status":"ok"}' -assert response.headers["content-type"] == "application/json" -``` - -For a path that is registered but does not accept the request method, -`dispatch()` returns a 405 response and an `Allow` header. An unknown path -returns 404. - -## Build responses - -`Response.text()` encodes UTF-8 text and supplies a text content type. -`Response.json()` emits compact UTF-8 JSON. The response serializer adds an -accurate `Content-Length` header when one was not supplied. - -```python -response = Response.text("hello", headers={"X-Request-ID": "abc123"}) -wire_bytes = response.to_http1() - -# b"HTTP/1.1 200 OK\\r\\nContent-Length: 5..." +if __name__ == "__main__": + app.listen(host="127.0.0.1", port=8000) ``` -Header names and values are validated: duplicate names (case-insensitively), -forbidden control characters, and values outside the HTTP/1.1 Latin-1 wire -range are rejected. - -## Expected application errors - -Raise `HTTPError` inside a handler when an expected client-facing response is -clearer than constructing it inline: +Install the canonical SmallOS master dependency and this package, then run the +example: -```python -from smallserver import HTTPError - -@app.delete("/widgets") -async def delete_widget(request: Request) -> Response: - raise HTTPError(413, "request is too large") -``` - -`dispatch()` turns this into a text response with status 413. Unexpected -exceptions are intentionally left visible for the future SmallOS server's -runtime error handling. - -## Third-party blocking and asyncio libraries - -SmallServer delegates foreign execution to SmallOS's bounded adapters. The -application creates those adapters explicitly and can group them in an -`AdapterRegistry` for naming and deterministic shutdown: - -```python -from SmallPackage.adapters.asyncio_loop import AsyncioAdapter -from SmallPackage.adapters.threads import ThreadAdapter -from smallserver import AdapterRegistry, Response - -async def fetch_records(rows): - # Construct loop-affine clients inside the adapter-owned event loop. - async with make_async_client() as client: - return await client.fetch(rows) - -with AdapterRegistry( - database=ThreadAdapter(max_workers=1, max_pending=8), - async_sdk=AsyncioAdapter(max_pending=32), -) as services: - - @app.get("/records") - async def records(request): - rows = await services.call("database", repository.list_records) - result = await services.call("async_sdk", fetch_records, rows) - return Response.json(result) - - server = app.serve(runtime, host="127.0.0.1", port=8000) - runtime.start() -``` - -Use one thread worker for thread-affine resources such as a single SQLite -connection. `AsyncioAdapter` owns one persistent event loop and must receive an -async callable, not a task or future created on another loop. - -Adapter errors remain visible to handlers. `http_error_from_adapter()` is an -opt-in, detail-sanitizing translation: capacity/unavailable failures become -503 and protocol/execution failures become 500. - -Run the standard-library adapter example with: - -```bash -python3 examples/adapters_demo.py -``` - -## Development relationship - -SmallOS's canonical upstream is [MikiEEE/SmallOS](https://github.com/MikiEEE/SmallOS). During initial development, install the canonical `master` branch: - -```bash +```console python3 -m pip install -r requirements.txt +python3 -m pip install -e . +python3 demo.py ``` -SmallOS's normalized distribution name is currently unavailable for public package installation; SmallServer must not claim a PyPI dependency until that is resolved. +Application code can use blocking `app.listen()` without importing SmallOS. +Advanced applications can supply their own runtime, schedule the server without +starting it, and own execution adapters for blocking or asyncio-native +libraries. + +Current boundaries are intentional: one request is served per HTTP/1.1 +connection; routes are exact static paths; keep-alive, pipelining, TLS, path +parameters, WebSockets, and HTTP/2 are not part of this base. + +## Documentation + +- [Guide index](guide/index.md) +- [Getting started](guide/getting-started.md) +- [Routing](guide/routing.md) +- [Requests and responses](guide/requests-and-responses.md) +- [Runtime and lifecycle](guide/runtime-lifecycle.md) +- [Configuration](guide/configuration.md) +- [Third-party adapters](guide/adapters.md) +- [Errors and observability](guide/errors-observability.md) +- [Platforms and kernels](guide/platforms-kernels.md) +- [API reference](guide/api-reference.md) +- [Protocol roadmap](guide/protocol-roadmap.md) +- [Development](guide/development.md) + +See [`demo.py`](demo.py) for all five supported HTTP methods, +[`examples/manual_runtime.py`](examples/manual_runtime.py) for caller-owned +SmallOS startup, and [`examples/adapters_demo.py`](examples/adapters_demo.py) +for blocking and asyncio escape hatches. + +SmallServer is early-stage software. Review the documented limits and lifecycle +contract before deploying it outside controlled environments. diff --git a/guide/adapters.md b/guide/adapters.md new file mode 100644 index 0000000..2bc91b1 --- /dev/null +++ b/guide/adapters.md @@ -0,0 +1,49 @@ +# Third-party adapters + +SmallServer handlers run on the SmallOS scheduler and must not call blocking +functions or drive a second event loop directly. SmallOS supplies explicit +escape hatches: + +- `ThreadAdapter` for blocking or thread-affine callables; +- `AsyncioAdapter` for coroutine-based libraries on a persistent asyncio loop. + +The application creates, bounds, and shuts down these adapters. SmallServer +does not create adapter workers as a side effect of `listen()`. + +```python +from SmallPackage.adapters.errors import AdapterError +from SmallPackage.adapters.threads import ThreadAdapter +from smallserver import AdapterRegistry, Response, http_error_from_adapter + +services = AdapterRegistry(blocking=ThreadAdapter(max_workers=2, max_pending=8)) + + +async def handler(request): + try: + result = await services.call("blocking", str.upper, "smallserver") + except AdapterError as exc: + raise http_error_from_adapter(exc) + return Response.text(result) + + +services.shutdown() +``` + +In a real application, keep the registry alive around the complete runtime +lifecycle; do not shut it down immediately after defining a handler. The +context manager calls `shutdown()` automatically and cancels pending adapter +work when its body exits with an exception. + +`AdapterRegistry` accepts named, user-created adapters that provide `call()` +and `shutdown()`. It rejects duplicate names and duplicate adapter objects, +delegates calls, exposes stable registration order through `names()` and +`items()`, and shuts adapters down in reverse registration order. + +`http_error_from_adapter()` intentionally sanitizes adapter failures: +capacity, unavailable, closed, and cancelled conditions become generic 503 +responses; other adapter failures become a generic 500. Log internal causes in +application-controlled telemetry if needed, but do not expose them to clients. + +See [`examples/adapters_demo.py`](../examples/adapters_demo.py) for a runnable +SQLite and asyncio example and [`examples/manual_runtime.py`](../examples/manual_runtime.py) +for the surrounding runtime lifecycle. diff --git a/guide/api-reference.md b/guide/api-reference.md new file mode 100644 index 0000000..1bea9fe --- /dev/null +++ b/guide/api-reference.md @@ -0,0 +1,73 @@ +# API reference + +This page summarizes the public names exported by `smallserver` on the +lifecycle base. Signatures omit overload detail where prose is clearer. + +## Application + +### `SmallServer()` + +- `get(path)`, `post(path)`, `put(path)`, `patch(path)`, `delete(path)` — route + decorators for one supported method. +- `route(path, methods)` — atomic multi-method route decorator. +- `async dispatch(request)` — dispatch an existing `Request`. +- `listen(host="127.0.0.1", port=8000, config=None, *, runtime=None, start=None)` + — managed blocking lifecycle or caller-owned scheduling/startup. +- `serve(runtime, host="127.0.0.1", port=8000, config=None)` — schedule against + a caller-owned runtime and return immediately. + +## HTTP values + +### `Headers(values=None)` + +Immutable, case-insensitive mapping with `items()` and `get()`. + +### `Request(method, path, headers, body=b"", version="HTTP/1.1")` + +Frozen request value with validated method, path, headers, and byte body. + +### `Response(status=200, body=b"", headers=Headers())` + +Frozen response value. `Response.text()`, `Response.json()`, and `to_http1()` +provide common construction and serialization paths. + +## Server lifecycle + +### `ServerConfig(...)` + +Frozen finite-limit configuration. See [Configuration](configuration.md). + +### `ServerHandle` + +Read-only properties: `address`, `port`, `closed`, `failure`, `finished`, +`cleanup_errors`, and `owned_connection_count`. + +Operations: `close()`, `async close_from_task(task)`, and `finalize()`. + +## Adapters + +### `AdapterRegistry(**adapters)` + +Methods: `register`, `get`, `call`, `names`, `items`, and `shutdown`. It also +implements a context manager and exposes `closed`. + +### `http_error_from_adapter(exc)` + +Convert a SmallOS `AdapterError` to a sanitized `HTTPError`. + +### `AdapterShutdownError` + +Raised after registry shutdown attempts every adapter but one or more fail. +Its `failures` tuple contains `(name, exception)` entries. + +## Errors + +- `HTTPError(status, detail="")` +- `ServerConfigurationError` +- `ServerStartupError` +- `ServerFinalizationError` + +Cleanup errors expose `cleanup_errors`, `cleanup_complete`, `retry_cleanup()`, +and `finalize()`. `ServerStartupError` additionally exposes `primary_error`. + +Public typing information is shipped through `smallserver/py.typed`. diff --git a/guide/configuration.md b/guide/configuration.md new file mode 100644 index 0000000..2d1693a --- /dev/null +++ b/guide/configuration.md @@ -0,0 +1,44 @@ +# Configuration + +Pass a `ServerConfig` to `listen()` or `serve()` to tune finite listener, +parser, and scheduling limits. + +```python +from smallserver import ServerConfig, SmallServer + +app = SmallServer() +config = ServerConfig( + max_connections=50, + max_header_bytes=16 * 1024, + max_header_count=64, + max_body_bytes=512 * 1024, + receive_chunk_bytes=8 * 1024, + listener_priority=1, + connection_priority=2, + accept_batch_size=16, +) +``` + +| Setting | Default | Purpose | +| --- | ---: | --- | +| `max_connections` | 100 | Maximum connection streams still owned by the server. | +| `max_header_bytes` | 16 KiB | Maximum HTTP/1.1 request-head bytes. | +| `max_header_count` | 100 | Maximum number of request header fields. | +| `max_body_bytes` | 1 MiB | Maximum `Content-Length` and buffered request body. | +| `receive_chunk_bytes` | 8 KiB | Bytes requested from the transport per read. | +| `listener_priority` | 1 | SmallOS listener and close-watcher task priority. | +| `connection_priority` | 2 | SmallOS connection-task priority. | +| `accept_batch_size` | 16 | Accepts before the listener explicitly yields. | + +Every field must be a positive integer; booleans are rejected. The public port +must be an integer from 0 through 65535. `port=0` delegates port selection to +the kernel. + +At connection capacity, the listener waits on a scheduler signal instead of +accepting and discarding more streams. Connections whose close failed still +count against the limit because the server continues to own them. A close +failure is fatal to further acceptance and remains visible for cleanup retry. + +Limits are per `ServerHandle`. They bound HTTP input and framework-owned +connections, but they do not limit memory allocated by your handlers, response +bodies, adapter queues, or downstream libraries; configure those separately. diff --git a/guide/development.md b/guide/development.md new file mode 100644 index 0000000..68689c3 --- /dev/null +++ b/guide/development.md @@ -0,0 +1,52 @@ +# Development + +## Set up + +Use Python 3.10 or newer and install the canonical SmallOS master checkout plus +SmallServer in editable mode: + +```console +python3 -m pip install -r requirements.txt +python3 -m pip install -e . +``` + +For reproducible validation, put the canonical SmallOS checkout at the front of +`PYTHONPATH` rather than relying on an unrelated installed package named +`SmallPackage`. + +## Validate + +```console +python3 -m unittest discover -s tests -v +python3 -m compileall -q smallserver demo.py examples tests +git diff --check +``` + +The suite covers routing, HTTP values and parsing, adapters, lifecycle failure +ownership, kernel transport behavior, and real loopback serving when the local +environment permits binds. Documentation tests verify the tracked guide set, +relative Markdown links, and Python code-block syntax. + +Run the examples when their platform requirements are available: + +```console +python3 demo.py +python3 examples/adapters_demo.py +python3 examples/manual_runtime.py +``` + +The two network examples block until shutdown. `adapters_demo.py` completes on +its own and demonstrates SQLite thread affinity and a persistent asyncio loop. + +## Contribution boundaries + +- Keep framework networking behind SmallOS kernel abstractions. +- Preserve finite parsing, connection, and adapter limits. +- Keep the HTTP core independent of `asyncio`. +- Add lifecycle tests for partial acquisition and cleanup failure paths. +- Update the README and focused guide page when a public API changes. +- Extend [Protocol roadmap](protocol-roadmap.md) docs on the feature branch that + implements a protocol; do not describe planned APIs as present. + +The ignored `docs/` and `skills/` trees support local agent workflows. Public, +versioned user documentation belongs in `README.md` and `guide/`. diff --git a/guide/errors-observability.md b/guide/errors-observability.md new file mode 100644 index 0000000..bfd51c7 --- /dev/null +++ b/guide/errors-observability.md @@ -0,0 +1,51 @@ +# Errors and observability + +SmallServer separates expected HTTP responses, configuration mistakes, +runtime failures, and incomplete cleanup ownership. + +## Handler-facing errors + +Raise `HTTPError(status, detail)` for an expected 4xx or 5xx response. Status +must be between 400 and 599. The detail becomes a plain-text response; do not +put secrets or raw downstream exceptions in it. + +The network server converts ordinary handler exceptions into a generic 500. +`app.dispatch()` only catches `HTTPError`, so direct dispatch in tests preserves +programming errors. + +## Configuration errors + +`ServerConfigurationError` reports a runtime or kernel capability that cannot +support the requested lifecycle. Type and value mistakes generally raise +`TypeError` or `ValueError` before binding. + +## Startup and finalization ownership + +`ServerStartupError` means startup failed and one or more acquired resources +could not yet be released. Its `primary_error` is the original failure; +`cleanup_errors` contains the current cleanup failures. Retain the exception +and call `retry_cleanup()` or `finalize()` until it returns `True`. + +`ServerFinalizationError` means a started runtime returned normally but server +cleanup remains incomplete. It exposes the same `cleanup_errors`, +`cleanup_complete`, `retry_cleanup()`, and `finalize()` contract. + +`KeyboardInterrupt` and `SystemExit` retain their identity. If rollback is +incomplete, their `__cause__` is the `ServerStartupError` cleanup owner. An +abandoned incomplete cleanup error makes one best-effort retry and emits a +`ResourceWarning` if ownership remains. + +## ServerHandle state + +Observe these stable properties: + +- `address` and `port`: cached bind result; +- `closed`: shutdown has been requested; +- `finished`: all server-owned cleanup is complete; +- `failure`: first fatal listener or connection-cleanup failure, if any; +- `cleanup_errors`: current failures for still-owned resources; +- `owned_connection_count`: active and retained connection streams. + +SmallServer does not provide a logging backend, metrics registry, or tracing +system in this base. Applications should report sanitized handle state and +their own handler/adapter telemetry without reaching into private attributes. diff --git a/guide/getting-started.md b/guide/getting-started.md new file mode 100644 index 0000000..1871378 --- /dev/null +++ b/guide/getting-started.md @@ -0,0 +1,63 @@ +# Getting started + +## Requirements + +SmallServer requires Python 3.10 or newer. During development, +`requirements.txt` installs SmallOS from the canonical GitHub `master` branch; +SmallServer itself declares no package-index runtime dependency yet. + +```console +python3 -m pip install -r requirements.txt +python3 -m pip install -e . +``` + +The first command needs Git and network access. Pin the SmallOS revision in +your own deployment lock or build process if reproducibility matters. + +## Create an application + +```python +from smallserver import Request, Response, SmallServer + +app = SmallServer() + + +@app.get("/health") +async def health(request: Request) -> Response: + return Response.json({"status": "ok"}) + + +if __name__ == "__main__": + app.listen(host="127.0.0.1", port=8000) +``` + +Run the file and request the exact path: + +```console +curl -i http://127.0.0.1:8000/health +``` + +`listen()` creates a SmallOS runtime with its Unix kernel, blocks while that +runtime runs, and handles Ctrl-C by cleaning up server-owned resources. Normal +application code does not need to import SmallOS. + +Use `port=0` when a test or tool needs the kernel to choose an available port. +Because managed `listen()` blocks, inspect the returned handle only after the +runtime has stopped. For access to the bound port while the server is running, +use [caller-owned runtime mode](runtime-lifecycle.md#caller-owned-runtime). + +## Try the task demo + +[`demo.py`](../demo.py) implements GET, POST, PUT, PATCH, and DELETE on the +static `/tasks` route: + +```console +python3 demo.py +curl -i http://127.0.0.1:8000/tasks +curl -i -X POST -H 'Content-Type: application/json' \ + --data '{"title":"read the guide"}' http://127.0.0.1:8000/tasks +``` + +Every current HTTP/1.1 connection serves one request and closes after the +response. See [Routing](routing.md) and [Configuration](configuration.md) before +building a larger application. diff --git a/guide/index.md b/guide/index.md new file mode 100644 index 0000000..457a1f5 --- /dev/null +++ b/guide/index.md @@ -0,0 +1,27 @@ +# SmallServer guide + +This guide documents the API available on the lifecycle base. Start with the +managed server path, then open the focused page for the part you are changing. + +## Learn SmallServer + +1. [Getting started](getting-started.md) — install, create an app, and run it. +2. [Routing](routing.md) — exact paths, methods, 404, and 405 behavior. +3. [Requests and responses](requests-and-responses.md) — immutable HTTP values. +4. [Runtime and lifecycle](runtime-lifecycle.md) — managed and caller-owned modes. +5. [Configuration](configuration.md) — finite parser and connection limits. + +## Integrate and operate + +- [Third-party adapters](adapters.md) +- [Errors and observability](errors-observability.md) +- [Platforms and kernels](platforms-kernels.md) +- [API reference](api-reference.md) + +## Project direction + +- [Protocol roadmap](protocol-roadmap.md) +- [Development](development.md) + +The base described here supports HTTP/1.1 only. Protocol feature branches add +their own documentation without changing what this base promises. diff --git a/guide/platforms-kernels.md b/guide/platforms-kernels.md new file mode 100644 index 0000000..e29f0df --- /dev/null +++ b/guide/platforms-kernels.md @@ -0,0 +1,40 @@ +# Platforms and kernels + +SmallServer delegates networking, readiness, task registration, and task +cancellation to SmallOS. Production framework modules do not import Python's +`socket` module directly; kernel-owned transport handles remain opaque to the +application. + +## Desktop default + +Managed `app.listen()` lazily imports `SmallOS` and the `Unix` kernel, configures +that runtime, and starts it. If the dependency or Unix kernel is unavailable, +it raises `ServerConfigurationError` and asks the caller to provide a suitable +runtime. + +The canonical SmallOS dependency is installed from GitHub `master` by +`requirements.txt`. Python package metadata intentionally has no runtime +dependency until SmallOS has an unambiguous published distribution contract. + +## Custom and constrained kernels + +A supplied runtime must expose a configured `kernel` plus callable `fork`, +`resume_task`, and `cancel_task` operations. Starting it through SmallServer +also requires `start`. + +The kernel must satisfy SmallOS's network capability contract for listeners, +streams, readiness, retry direction, addresses, and cleanup. Capability checks +occur before SmallServer binds a listener. + +A wakeup channel is optional: + +- with one, `ServerHandle.close()` can notify the scheduler from another thread; +- without one, external `close()` raises and a running task must call + `await handle.close_from_task(task)`; +- after a caller-owned scheduler exits, `handle.finalize()` is the owner-thread + cleanup path on either kind of kernel. + +Do not infer that a MicroPython-like platform supports managed Unix mode or a +thread-safe wakeup just because it can accept TCP connections. Supply the +platform runtime explicitly and test its real capability surface and cleanup +behavior. diff --git a/guide/protocol-roadmap.md b/guide/protocol-roadmap.md new file mode 100644 index 0000000..ebf6c7e --- /dev/null +++ b/guide/protocol-roadmap.md @@ -0,0 +1,36 @@ +# Protocol and feature roadmap + +This guide base documents the exact API at the server-lifecycle milestone: +bounded HTTP/1.1, exact static routes, shared HTTP values, explicit SmallOS +lifecycle control, and application-owned execution adapters. + +Feature branches extend this foundation independently. Until such a branch is +merged into the branch you install, its API is not available. + +## Routing extensions + +The regex-routing feature introduces an explicit timeout-bounded regex route +form and captured path parameters while preserving exact static-route +precedence. It is not part of this base. Base applications should continue to +register literal paths and should not assume automatic query parsing. + +## WebSocket server + +The WebSocket feature is planned as optional RFC 6455 server support over an +HTTP/1.1 Upgrade, using SmallOS-native transport ownership and bounded +protocol state. TLS, compression, and RFC 8441 WebSockets over HTTP/2 remain +separate concerns. No WebSocket API is exported by this base. + +## HTTP/2 server + +The HTTP/2 feature is planned as an optional cleartext prior-knowledge server +using the hyper-h2 4.x sans-I/O stack. Its branch is responsible for documenting +dependency installation, stream concurrency, flow control, protocol limits, +GOAWAY, and graceful shutdown. This base does not accept HTTP/2 connections and +does not export an HTTP/2 configuration type. + +## Existing HTTP/1.1 limits + +Keep-alive, pipelining, TLS termination, automatic protocol detection, h2c +upgrade, middleware/ASGI compatibility, and automatic request-data decoding are +not implemented here. Treat this page as direction, not a compatibility promise. diff --git a/guide/requests-and-responses.md b/guide/requests-and-responses.md new file mode 100644 index 0000000..4144a70 --- /dev/null +++ b/guide/requests-and-responses.md @@ -0,0 +1,65 @@ +# Requests and responses + +`Request`, `Response`, and `Headers` are immutable value objects shared by the +router and server. + +## Request + +A handler receives: + +- `method`: a valid HTTP token; +- `path`: the request target, beginning with `/`; +- `headers`: a case-insensitive `Headers` mapping; +- `body`: complete request bytes; +- `version`: `HTTP/1.1` for the current network server. + +The base parser accepts one origin-form HTTP/1.1 request framed by zero or one +`Content-Length` header. It rejects transfer encoding, multiple content lengths, +missing `Host`, invalid targets, oversized input, and pipelined bytes. It does +not decode JSON, forms, query parameters, or text for you. + +```python +import json + +from smallserver import HTTPError, Request, Response + + +async def create(request: Request) -> Response: + try: + value = json.loads(request.body.decode("utf-8")) + except (UnicodeDecodeError, json.JSONDecodeError) as exc: + raise HTTPError(400, "body must be valid JSON") from exc + return Response.json({"received": value}, status=201) +``` + +## Headers + +Header lookup is case-insensitive while iteration preserves the originally +provided spelling. Names must be HTTP tokens; values cannot contain control +characters other than horizontal tab or characters outside Latin-1. Duplicate +names are rejected after case folding. + +```python +from smallserver import Headers + +headers = Headers({"Content-Type": "application/json"}) +assert headers["content-type"] == "application/json" +``` + +## Response + +Construct `Response(status, body, headers)`, or use `Response.text()` and +`Response.json()`. Bodies must already be `bytes`. An explicit `Content-Length` +must exactly match the body; otherwise construction fails. The HTTP/1.1 server +adds a length when absent and sends `Connection: close`. + +```python +from smallserver import Response + +plain = Response.text("ready") +created = Response.json({"id": "1"}, status=201) +empty = Response(status=204) +``` + +`Response.to_http1()` is available for deterministic serialization and tests. +Applications normally return the value and let SmallServer write it. diff --git a/guide/routing.md b/guide/routing.md new file mode 100644 index 0000000..e262a57 --- /dev/null +++ b/guide/routing.md @@ -0,0 +1,45 @@ +# Routing + +SmallServer currently matches a request method and path exactly. Register +routes with `get`, `post`, `put`, `patch`, `delete`, or the multi-method +`route` decorator. + +```python +from smallserver import Response, SmallServer + +app = SmallServer() + + +@app.route("/status", methods=("GET", "POST")) +async def status(request): + return Response.text(request.method) +``` + +Methods passed to `route` are normalized to uppercase and duplicates are +removed. Registration rejects an empty method set, unsupported methods, +non-callable handlers, duplicate method/path pairs, and paths that do not start +with `/`. A failed multi-method registration does not partially add a route. + +## Dispatch behavior + +- An exact method/path match runs its async handler. +- A known path with the wrong method returns 405 and a sorted `Allow` header. +- An unknown path returns 404. +- A handler must return an awaitable whose result is a `Response`. +- Raising `HTTPError` produces the requested 4xx or 5xx response. + +An ordinary handler exception becomes a generic 500 when the network server +invokes it. A direct call to `await app.dispatch(request)` preserves ordinary +exceptions for tests and embedding code. + +## Static-path boundary + +This base does not parse path parameters or split query strings. The request +target is matched as received, so `/items` and `/items?limit=10` are different +route keys. Register stable static paths and parse only data whose format your +application explicitly controls. + +Timeout-bounded regex routes and captured parameters are being developed as an +optional route form; see the [protocol and feature roadmap](protocol-roadmap.md#routing-extensions). +Do not write base-compatible examples that assume `/items/{id}` or automatic +query parsing. diff --git a/guide/runtime-lifecycle.md b/guide/runtime-lifecycle.md new file mode 100644 index 0000000..d67611e --- /dev/null +++ b/guide/runtime-lifecycle.md @@ -0,0 +1,78 @@ +# Runtime and lifecycle + +SmallOS always owns scheduling and I/O readiness. SmallServer offers one +managed mode for normal applications and explicit modes for applications that +coordinate other SmallOS tasks. + +Only one listener invocation may be active on a `SmallServer` instance. The +instance can be reused after its handle is fully finished. + +## Managed runtime + +```python +from smallserver import Response, SmallServer + +app = SmallServer() + + +@app.get("/") +async def index(request): + return Response.text("hello") + + +app.listen(host="127.0.0.1", port=8000) +``` + +With no `runtime`, `listen()` lazily creates `SmallOS().setKernel(Unix())`, +starts it, blocks until shutdown, and finalizes server-owned resources. In this +managed mode, Ctrl-C is consumed after successful cleanup and the closed +`ServerHandle` is returned. + +## Caller-owned runtime + +Supply a configured runtime to schedule the listener without starting it: + +```python +from SmallPackage import SmallOS, Unix +from smallserver import Response, SmallServer + +runtime = SmallOS().setKernel(Unix()) +app = SmallServer() + + +@app.get("/health") +async def health(request): + return Response.json({"status": "ok"}) + + +handle = app.listen(runtime=runtime, start=False, port=0) +print(handle.address) +try: + runtime.start() +finally: + handle.finalize() +``` + +With a supplied runtime, `start=False` is the default. `app.serve(runtime, ...)` +is the equivalent schedule-and-return compatibility API. Passing `start=True` +starts the supplied runtime once; the caller still owns that runtime. + +## Shutdown operations + +- `handle.close()` requests shutdown from outside the scheduler when the kernel + provides a wakeup channel. Unix supports this path. +- `await handle.close_from_task(task)` shuts down from the currently running + SmallOS task and is required on kernels without a wakeup channel. +- `handle.finalize()` performs idempotent owner-thread cleanup after a manually + started scheduler has exited or failed. + +`closed` means shutdown was requested. `finished` is stronger: the listener, +wakeup channel, connections, and retained cleanup work have all completed. +Failed closes remain owned and appear in `cleanup_errors`; call the appropriate +cleanup operation again from a safe context. + +`address` and `port` are cached and remain readable after close. `failure` +reports the first fatal listener or connection-cleanup failure. + +See [Errors and observability](errors-observability.md) for incomplete startup +and finalization transactions. diff --git a/tests/test_documentation.py b/tests/test_documentation.py new file mode 100644 index 0000000..bfb33af --- /dev/null +++ b/tests/test_documentation.py @@ -0,0 +1,77 @@ +import re +import unittest +from pathlib import Path + + +ROOT = Path(__file__).resolve().parents[1] +GUIDE_FILES = { + "index.md", + "getting-started.md", + "routing.md", + "requests-and-responses.md", + "runtime-lifecycle.md", + "configuration.md", + "adapters.md", + "errors-observability.md", + "platforms-kernels.md", + "api-reference.md", + "protocol-roadmap.md", + "development.md", +} +MARKDOWN_LINK = re.compile(r"(? {}".format(document.relative_to(ROOT), target)) + continue + if separator: + headings = { + heading_slug(value) + for value in HEADING.findall(destination.read_text()) + } + if fragment not in headings: + failures.append( + "{} -> {} (missing heading)".format( + document.relative_to(ROOT), target + ) + ) + self.assertEqual(failures, []) + + def test_python_code_blocks_compile(self): + failures = [] + for document in self._documents(): + for position, source in enumerate(PYTHON_BLOCK.findall(document.read_text()), 1): + try: + compile(source, "{}:block{}".format(document, position), "exec") + except SyntaxError as exc: + failures.append(str(exc)) + self.assertEqual(failures, []) + + +if __name__ == "__main__": + unittest.main() From ec8602084a615a50ffff2a9b0ba417841722e0a9 Mon Sep 17 00:00:00 2001 From: Michael Emperador Date: Sat, 22 Aug 2026 02:26:32 -0500 Subject: [PATCH 10/14] fix: harden WebSocket protocol lifecycle --- smallserver/app.py | 5 +- smallserver/websocket.py | 330 +++++++++++++++++++++++++++++++++------ 2 files changed, 284 insertions(+), 51 deletions(-) diff --git a/smallserver/app.py b/smallserver/app.py index ea97f34..67eb03c 100644 --- a/smallserver/app.py +++ b/smallserver/app.py @@ -46,6 +46,7 @@ WebSocketUnavailable, _WebSocketRoute, _WebSocketState, + _is_http_token, _is_upgrade_attempt, _validate_upgrade, run_websocket_connection, @@ -243,9 +244,7 @@ def websocket( raise TypeError("WebSocket subprotocols must be an iterable of tokens") protocols = tuple(dict.fromkeys(subprotocols)) if any( - not isinstance(protocol, str) - or not protocol - or any(character in protocol for character in "()<>@,;:\\\"/[]?={} \t") + not isinstance(protocol, str) or not _is_http_token(protocol) for protocol in protocols ): raise ValueError("WebSocket subprotocols must be valid HTTP tokens") diff --git a/smallserver/websocket.py b/smallserver/websocket.py index 48fd91a..9e024e3 100644 --- a/smallserver/websocket.py +++ b/smallserver/websocket.py @@ -19,6 +19,9 @@ _INBOX_SIGNAL = 25 _OUTBOX_SIGNAL = 26 _ACK_SIGNAL = 27 +_HTTP_TOKEN_CHARACTERS = frozenset( + "!#$%&'*+-.^_`|~0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz" +) class WebSocketUnavailable(RuntimeError): @@ -85,6 +88,7 @@ class WebSocketConfig: handshake_timeout: float = 10.0 idle_timeout: float = 300.0 pong_timeout: float = 10.0 + write_timeout: float = 30.0 close_timeout: float = 5.0 deadline_resolution: float = 0.05 @@ -108,6 +112,7 @@ def __post_init__(self) -> None: "handshake_timeout", "idle_timeout", "pong_timeout", + "write_timeout", "close_timeout", "deadline_resolution", ): @@ -328,25 +333,33 @@ def __init__( self.deadline_task: Any = None self.accepted = False self.rejected = False + self.handshake_state = "pending" + self.handshake_error: BaseException | None = None self.shutdown = False self.peer_closed = False self.close_sent = False self.subprotocol: str | None = None self.disconnect: WebSocketDisconnect | None = None self.handler_error: BaseException | None = None + self.fatal_error: BaseException | None = None self.inbox: deque[WebSocketMessage] = deque() self.inbox_bytes = 0 self.outbox: deque[_OutboundCommand] = deque() self.outbox_bytes = 0 self.writer_busy = False + self.active_command: _OutboundCommand | None = None self._message_kind: type | None = None - self._message_parts: list[str] | list[bytes] = [] + self._message_buffer = bytearray() self._message_bytes = 0 self._guard = _FrameGuard(config.max_frame_payload_bytes) self.created_at = time.monotonic() self.last_activity = self.created_at self.pong_deadline: float | None = None + self._ping_generation = 0 + self._pending_ping_generation: int | None = None + self._pending_ping_payload: bytes | None = None self.close_deadline: float | None = None + self.write_deadline: float | None = None self._children: list[Any] = [] def _current_task(self) -> Any: @@ -376,7 +389,7 @@ async def accept( self, subprotocol: str | None, headers: Mapping[str, str] | None ) -> None: task = self._current_task() - if self.accepted or self.rejected: + if self.handshake_state != "pending": raise WebSocketStateError("WebSocket handshake is already decided") if subprotocol is not None: if subprotocol not in self.route.subprotocols: @@ -389,6 +402,7 @@ async def accept( "upgrade", "sec-websocket-accept", "sec-websocket-protocol", + "sec-websocket-extensions", "content-length", } if any(name.lower() in forbidden for name in extra): @@ -405,24 +419,55 @@ async def accept( lines.append("Sec-WebSocket-Protocol: {}".format(subprotocol)) lines.extend("{}: {}".format(name, value) for name, value in extra.items()) payload = ("\r\n".join(lines) + "\r\n\r\n").encode("latin-1") - self.protocol = self.api.Connection(self.api.ConnectionType.SERVER) - await self.transport.send_all(task, self.client, payload) - self.subprotocol = subprotocol - self.accepted = True - self.last_activity = time.monotonic() - self._signal(self.coordinator_task, _DECISION_SIGNAL) + protocol = self.api.Connection(self.api.ConnectionType.SERVER) + self.handshake_state = "accepting" + self.protocol = protocol + try: + await self.transport.send_all(task, self.client, payload) + except GeneratorExit: + raise + except BaseException as exc: + self._fail_handshake(exc) + raise + else: + self.subprotocol = subprotocol + self.accepted = True + self.handshake_state = "accepted" + self.last_activity = time.monotonic() + self._signal(self.coordinator_task, _DECISION_SIGNAL) async def reject(self, response: Response) -> None: task = self._current_task() - if self.accepted or self.rejected: + if self.handshake_state != "pending": raise WebSocketStateError("WebSocket handshake is already decided") if not isinstance(response, Response): raise TypeError("reject() requires a Response") if response.status < 300: raise ValueError("WebSocket rejection response must have status 300 or greater") - await self._send_http(task, response) - self.rejected = True - self._signal(self.coordinator_task, _DECISION_SIGNAL) + self.handshake_state = "rejecting" + try: + await self._send_http(task, response) + except GeneratorExit: + raise + except BaseException as exc: + self._fail_handshake(exc) + raise + else: + self.rejected = True + self.handshake_state = "rejected" + self._signal(self.coordinator_task, _DECISION_SIGNAL) + + def _fail_handshake(self, error: BaseException) -> None: + if self.handshake_state == "failed": + return + self.accepted = False + self.rejected = False + self.protocol = None + self.handshake_state = "failed" + self.handshake_error = error + if isinstance(error, (KeyboardInterrupt, SystemExit)): + self.fatal_error = error + self._disconnect(1006) def _require_open(self) -> None: if not self.accepted: @@ -456,8 +501,21 @@ async def send_message(self, value: str | bytes) -> None: async def ping(self, payload: bytes) -> None: self._require_open() - await self._enqueue(self.api.Ping(payload=payload), len(payload), wait=True) + if self._pending_ping_generation is not None: + raise WebSocketStateError("a WebSocket Ping is already awaiting Pong") + self._ping_generation += 1 + generation = self._ping_generation + self._pending_ping_generation = generation + self._pending_ping_payload = payload self.pong_deadline = time.monotonic() + self.config.pong_timeout + try: + await self._enqueue( + self.api.Ping(payload=payload), len(payload), wait=True + ) + except BaseException: + if self._pending_ping_generation == generation: + self._clear_pending_ping() + raise async def close(self, code: int, reason: str) -> None: self._require_open() @@ -465,13 +523,18 @@ async def close(self, code: int, reason: str) -> None: raise ValueError("invalid WebSocket close code") if not isinstance(reason, str) or len(reason.encode("utf-8")) > 123: raise ValueError("WebSocket close reason must be at most 123 UTF-8 bytes") - await self._enqueue( - self.api.CloseConnection(code=code, reason=reason), - 2 + len(reason.encode("utf-8")), - wait=True, - ) + reason_bytes = reason.encode("utf-8") self.close_sent = True self.close_deadline = time.monotonic() + self.config.close_timeout + try: + await self._enqueue( + self.api.CloseConnection(code=code, reason=reason), + 2 + len(reason_bytes), + wait=True, + ) + except BaseException: + self._disconnect(code, reason) + raise task = self._current_task() while not self.peer_closed and time.monotonic() < self.close_deadline: await task.sleep(min(self.config.deadline_resolution, self.config.close_timeout)) @@ -495,6 +558,45 @@ async def _enqueue(self, event: Any, size: int, *, wait: bool) -> None: if command.error is not None: raise command.error + def _clear_pending_ping(self) -> None: + self._pending_ping_generation = None + self._pending_ping_payload = None + self.pong_deadline = None + + def _fail_outbound(self, error: BaseException) -> None: + commands = list(self.outbox) + self.outbox.clear() + self.outbox_bytes = 0 + if self.active_command is not None: + commands.insert(0, self.active_command) + seen: set[int] = set() + for command in commands: + if id(command) in seen: + continue + seen.add(id(command)) + command.error = error + command.done = True + self._signal(command.waiter, _ACK_SIGNAL) + + def _cancel_task(self, target: Any) -> None: + if target is None or target is getattr(self.runtime, "cursor", None): + return + try: + self.runtime.cancel_task(target) + except (KeyboardInterrupt, SystemExit) as exc: + self.fatal_error = exc + raise + except BaseException: + # ServerHandle retains ownership and retries cancellation in finalization. + pass + + def _abort_writer(self, error: BaseException) -> None: + self._fail_outbound(error) + self._cancel_task(self.writer_task) + + def _cancel_handler(self) -> None: + self._cancel_task(self.handler_task) + def _enqueue_control(self, event: Any, size: int = 0) -> bool: if ( len(self.outbox) >= self.config.max_outbound_commands @@ -533,7 +635,11 @@ def request_shutdown(self, code: int = 1001) -> None: self.api.CloseConnection(code=code, reason="server shutdown"), 17 ) self.close_sent = True - self._disconnect(code, "server shutdown") + if self.handshake_state in {"pending", "accepting", "rejecting"}: + self._fail_handshake(WebSocketDisconnect(code, "server shutdown")) + else: + self._disconnect(code, "server shutdown") + self._cancel_handler() self._signal(self.writer_task, _OUTBOX_SIGNAL) @@ -543,6 +649,14 @@ def _token_list(value: str | None) -> tuple[str, ...]: return tuple(token.strip() for token in value.split(",") if token.strip()) +def _is_http_token(value: str) -> bool: + return ( + isinstance(value, str) + and bool(value) + and all(character in _HTTP_TOKEN_CHARACTERS for character in value) + ) + + def _message_size(value: str | bytes) -> int: return len(value.encode("utf-8")) if isinstance(value, str) else len(value) @@ -597,6 +711,15 @@ def _validate_upgrade( ) if not _valid_websocket_key(request.headers.get("sec-websocket-key")): return Response.text("invalid WebSocket key", status=400) + offered_subprotocols = _token_list( + request.headers.get("sec-websocket-protocol") + ) + offered_header = request.headers.get("sec-websocket-protocol") + if offered_header is not None and ( + not offered_subprotocols + or any(not _is_http_token(protocol) for protocol in offered_subprotocols) + ): + return Response.text("invalid WebSocket subprotocol", status=400) origin = request.headers.get("origin") if route.origins is not None and origin not in route.origins: return Response.text("WebSocket origin is not allowed", status=403) @@ -626,9 +749,11 @@ def spawn(routine: Any, name: str) -> Any: state.deadline_task = spawn( _run_deadlines, "smallserver-websocket-deadline" ) - while not state.accepted and not state.rejected and state.disconnect is None: + while state.handshake_state in {"pending", "accepting", "rejecting"}: await task.wait_signal(_DECISION_SIGNAL) if not state.accepted: + if state.fatal_error is not None: + raise state.fatal_error return state.writer_task = spawn(_run_writer, "smallserver-websocket-writer") state.reader_task = spawn(_run_reader, "smallserver-websocket-reader") @@ -639,22 +764,33 @@ def spawn(routine: Any, name: str) -> Any: except BaseException as exc: state.handler_error = exc + if isinstance(state.handler_error, (KeyboardInterrupt, SystemExit)): + raise state.handler_error + if state.fatal_error is not None: + raise state.fatal_error + if state.handler_error is not None and not state.close_sent: try: + state.close_deadline = time.monotonic() + state.config.close_timeout await state._enqueue( state.api.CloseConnection(code=1011, reason="handler failed"), 16, wait=True, ) state.close_sent = True + except (KeyboardInterrupt, SystemExit): + raise except BaseException: pass elif not state.close_sent and state.disconnect is None: try: + state.close_deadline = time.monotonic() + state.config.close_timeout await state._enqueue( state.api.CloseConnection(code=1000, reason=""), 2, wait=True ) state.close_sent = True + except (KeyboardInterrupt, SystemExit): + raise except BaseException: pass @@ -688,16 +824,27 @@ async def _run_handler(task: Any, state: _WebSocketState) -> None: await result except WebSocketDisconnect: pass + except GeneratorExit: + raise + except (KeyboardInterrupt, SystemExit) as exc: + state.handler_error = exc + if state.handshake_state in {"pending", "accepting", "rejecting"}: + state._fail_handshake(exc) + raise except BaseException as exc: state.handler_error = exc finally: - if not state.accepted and not state.rejected: + if state.handshake_state == "pending": response = Response.text( "internal server error" if state.handler_error is not None else "forbidden", status=500 if state.handler_error is not None else 403, ) try: await state.reject(response) + except (KeyboardInterrupt, SystemExit) as exc: + state.handler_error = exc + state.fatal_error = exc + raise except BaseException: state._disconnect(1006) state._signal(state.coordinator_task, _DECISION_SIGNAL) @@ -709,6 +856,8 @@ async def _run_writer(task: Any, state: _WebSocketState) -> None: command = state.outbox.popleft() state.outbox_bytes -= command.size state.writer_busy = True + state.active_command = command + state.write_deadline = time.monotonic() + state.config.write_timeout try: payload = state.protocol.send(command.event) for offset in range(0, len(payload), state.config.write_chunk_bytes): @@ -718,11 +867,23 @@ async def _run_writer(task: Any, state: _WebSocketState) -> None: payload[offset : offset + state.config.write_chunk_bytes], ) state.last_activity = time.monotonic() + except GeneratorExit: + raise + except (KeyboardInterrupt, SystemExit) as exc: + command.error = exc + state.fatal_error = exc + state._disconnect(1006) + state._cancel_handler() + raise except BaseException as exc: command.error = exc state._disconnect(1006) + state._cancel_handler() finally: state.writer_busy = False + if state.active_command is command: + state.active_command = None + state.write_deadline = None command.done = True state._signal(command.waiter, _ACK_SIGNAL) if not state.shutdown: @@ -744,11 +905,14 @@ async def _run_reader(task: Any, state: _WebSocketState) -> None: state.protocol.receive_data(None) _drain_protocol_events(state) state._disconnect(1006) + state._cancel_handler() return state.last_activity = time.monotonic() _receive_protocol_data(state, chunk) if _drain_protocol_events(state): return + except GeneratorExit: + raise except WebSocketCapacityError: if state.shutdown: return @@ -757,6 +921,12 @@ async def _run_reader(task: Any, state: _WebSocketState) -> None: ) state.close_sent = True state._disconnect(1009, "message too large") + state._cancel_handler() + except (KeyboardInterrupt, SystemExit) as exc: + state.fatal_error = exc + state._disconnect(1006) + state._cancel_handler() + raise except BaseException: if state.shutdown: return @@ -765,6 +935,7 @@ async def _run_reader(task: Any, state: _WebSocketState) -> None: ) state.close_sent = True state._disconnect(1002, "protocol error") + state._cancel_handler() def _receive_protocol_data(state: _WebSocketState, data: bytes) -> None: @@ -778,22 +949,27 @@ def _drain_protocol_events(state: _WebSocketState) -> bool: kind = str if isinstance(event, state.api.TextMessage) else bytes if state._message_kind is None: state._message_kind = kind - state._message_parts = [] + state._message_buffer.clear() state._message_bytes = 0 if state._message_kind is not kind: raise ValueError("WebSocket message type changed during fragmentation") state._message_bytes += _message_size(event.data) if state._message_bytes > state.config.max_message_bytes: raise WebSocketCapacityError("WebSocket message is too large") - state._message_parts.append(event.data) + encoded = ( + event.data.encode("utf-8") + if isinstance(event.data, str) + else event.data + ) + state._message_buffer.extend(encoded) if event.message_finished: value = ( - "".join(state._message_parts) + bytes(state._message_buffer).decode("utf-8") if kind is str - else b"".join(state._message_parts) + else bytes(state._message_buffer) ) state._message_kind = None - state._message_parts = [] + state._message_buffer.clear() state._message_bytes = 0 if not state._deliver_message(value): raise WebSocketCapacityError("WebSocket inbound queue is full") @@ -801,43 +977,101 @@ def _drain_protocol_events(state: _WebSocketState) -> bool: if not state._enqueue_control(event.response(), len(event.payload)): raise WebSocketCapacityError("WebSocket outbound queue is full") elif isinstance(event, state.api.Pong): - state.pong_deadline = None + _handle_pong(state, event.payload) elif isinstance(event, state.api.CloseConnection): state.peer_closed = True + close_code = int(event.code) + disconnect_reason = event.reason or "" if not state.close_sent: - if not state._enqueue_control(event.response(), 2): + if close_code == 1002: + response = state.api.CloseConnection( + code=1002, reason="protocol error" + ) + elif close_code == 1007: + response = state.api.CloseConnection( + code=1007, reason="invalid payload" + ) + else: + response = event.response() + if not state._enqueue_control( + response, _close_event_size(response) + ): raise WebSocketCapacityError("WebSocket outbound queue is full") state.close_sent = True - state._disconnect(event.code, event.reason or "") + if close_code == 1002: + disconnect_reason = "protocol error" + elif close_code == 1007: + disconnect_reason = "invalid payload" + state._disconnect(close_code, disconnect_reason) return True return False +def _handle_pong(state: _WebSocketState, payload: bytes) -> None: + if ( + state._pending_ping_generation is not None + and payload == state._pending_ping_payload + ): + state._clear_pending_ping() + + +def _close_event_size(event: Any) -> int: + if int(event.code) == 1005: + return 0 + return 2 + len((event.reason or "").encode("utf-8")) + + async def _run_deadlines(task: Any, state: _WebSocketState) -> None: while not state.shutdown: await task.sleep(state.config.deadline_resolution) now = time.monotonic() - if not state.accepted and not state.rejected: + if state.handshake_state in {"pending", "accepting", "rejecting"}: if now - state.created_at >= state.config.handshake_timeout: - try: - await state.reject( - Response.text("WebSocket handshake timed out", status=408) - ) - except BaseException: - state._disconnect(1006) + if state.handshake_state == "pending": + try: + await state.reject( + Response.text("WebSocket handshake timed out", status=408) + ) + except (KeyboardInterrupt, SystemExit) as exc: + state.fatal_error = exc + raise + except BaseException: + state._disconnect(1006) + else: + error = WebSocketDisconnect(1006, "handshake timed out") + state._fail_handshake(error) + state._cancel_handler() return continue - if state.accepted and now - state.last_activity >= state.config.idle_timeout: - state._enqueue_control( - state.api.CloseConnection(code=1001, reason="idle timeout"), 14 - ) - state.close_sent = True - state._disconnect(1001, "idle timeout") - return if state.pong_deadline is not None and now >= state.pong_deadline: - state._enqueue_control( - state.api.CloseConnection(code=1002, reason="Pong timeout"), 14 - ) - state.close_sent = True - state._disconnect(1002, "Pong timeout") + _begin_deadline_close(state, 1002, "Pong timeout") + elif state.accepted and now - state.last_activity >= state.config.idle_timeout: + _begin_deadline_close(state, 1001, "idle timeout") + if state.write_deadline is not None and now >= state.write_deadline: + error = WebSocketDisconnect(1006, "write timed out") + state._abort_writer(error) + state._cancel_handler() + state._disconnect(error.code, error.reason) + return + if state.close_deadline is not None and now >= state.close_deadline: + error = state.disconnect or WebSocketDisconnect(1006, "close timed out") + state._abort_writer(error) + state._cancel_handler() + state._disconnect(error.code, error.reason) return + + +def _begin_deadline_close( + state: _WebSocketState, code: int, reason: str +) -> None: + if not state.close_sent and state.protocol is not None: + reason_bytes = reason.encode("utf-8") + state._enqueue_control( + state.api.CloseConnection(code=code, reason=reason), + 2 + len(reason_bytes), + ) + state.close_sent = True + if state.close_deadline is None: + state.close_deadline = time.monotonic() + state.config.close_timeout + state._disconnect(code, reason) + state._cancel_handler() From 21d9396e0ded36b43e897bab80863a52059394eb Mon Sep 17 00:00:00 2001 From: Michael Emperador Date: Sat, 22 Aug 2026 02:26:40 -0500 Subject: [PATCH 11/14] test: cover WebSocket review regressions --- tests/test_websocket.py | 404 +++++++++++++++++++++++++++++++++++++++- 1 file changed, 403 insertions(+), 1 deletion(-) diff --git a/tests/test_websocket.py b/tests/test_websocket.py index b2cc9bc..9755560 100644 --- a/tests/test_websocket.py +++ b/tests/test_websocket.py @@ -9,8 +9,10 @@ from unittest.mock import patch from SmallPackage import SmallOS, SmallTask, SmallWebSocketClient, Unix +from SmallPackage.adapters.threads import ThreadAdapter from smallserver import ( + AdapterRegistry, Headers, Request, Response, @@ -18,13 +20,20 @@ WebSocket, WebSocketCapacityError, WebSocketConfig, + WebSocketDisconnect, WebSocketUnavailable, ) from smallserver.websocket import ( _FrameGuard, _WebSocketState, _WebSocketRoute, + _drain_protocol_events, + _handle_pong, _load_wsproto, + _receive_protocol_data, + _run_deadlines, + _run_handler, + _run_writer, _validate_upgrade, ) @@ -48,6 +57,55 @@ async def unused_handler(socket: WebSocket) -> None: await socket.reject(Response(status=403)) +class _RecordingTransport: + def __init__(self) -> None: + self.send_calls = 0 + self.payloads: list[bytes] = [] + + async def send_all(self, task, client, payload: bytes) -> None: + self.send_calls += 1 + self.payloads.append(payload) + + +class _BlockingTransport(_RecordingTransport): + async def send_all(self, task, client, payload: bytes) -> None: + self.send_calls += 1 + self.payloads.append(payload) + await task.wait_signal(28) + + +def _make_state( + runtime, + transport, + handler, + *, + config: WebSocketConfig | None = None, +) -> _WebSocketState: + return _WebSocketState( + runtime, + transport, + object(), + upgrade_request(), + _WebSocketRoute(handler, None, ()), + config or WebSocketConfig(), + b"", + ) + + +def _make_accepted_state( + runtime, + transport, + handler, + *, + config: WebSocketConfig | None = None, +) -> _WebSocketState: + state = _make_state(runtime, transport, handler, config=config) + state.protocol = state.api.Connection(state.api.ConnectionType.SERVER) + state.accepted = True + state.handshake_state = "accepted" + return state + + class WebSocketProtocolTests(unittest.TestCase): def test_config_rejects_unbounded_or_inconsistent_limits(self) -> None: with self.assertRaisesRegex(ValueError, "max_message_bytes"): @@ -56,6 +114,8 @@ def test_config_rejects_unbounded_or_inconsistent_limits(self) -> None: WebSocketConfig(max_frame_payload_bytes=2, max_message_bytes=1) with self.assertRaisesRegex(ValueError, "idle_timeout"): WebSocketConfig(idle_timeout=float("inf")) + with self.assertRaisesRegex(ValueError, "write_timeout"): + WebSocketConfig(write_timeout=0) def test_registration_is_lazy_and_coexists_with_get(self) -> None: app = SmallServer() @@ -123,6 +183,270 @@ def test_origin_policy_is_explicit(self) -> None: ) ) + def test_subprotocol_tokens_are_ascii(self) -> None: + app = SmallServer() + for invalid in ("chat:v1", "café", "chat v1", ""): + with self.subTest(invalid=invalid): + with self.assertRaisesRegex(ValueError, "HTTP tokens"): + app.websocket( + "/invalid-{}".format(len(app._websocket_routes)), + subprotocols=(invalid,), + ) + + route = _WebSocketRoute(unused_handler, None, ("chat.v1",)) + for offered in ("chat:v1", "café", ","): + with self.subTest(offered=offered): + invalid = _validate_upgrade( + upgrade_request(**{"Sec-WebSocket-Protocol": offered}), route + ) + self.assertIsNotNone(invalid) + assert invalid is not None + self.assertEqual(invalid.status, 400) + + @unittest.skipUnless(HAS_WSPROTO, "websocket extra is not installed") + def test_extensions_cannot_be_selected_in_accept_response(self) -> None: + runtime = SmallOS().setKernel(Unix()) + transport = _RecordingTransport() + state = _make_state(runtime, transport, unused_handler) + outcome: list[BaseException] = [] + + async def accept_with_extension(task) -> None: + try: + await WebSocket(state).accept( + headers={"Sec-WebSocket-Extensions": "permessage-deflate"} + ) + except BaseException as exc: + outcome.append(exc) + + attempt = SmallTask(2, accept_with_extension, name="extension-rejection") + runtime.fork(attempt) + runtime.start() + self.assertIsInstance(outcome[0], ValueError) + self.assertEqual(state.handshake_state, "pending") + self.assertEqual(transport.send_calls, 0) + + @unittest.skipUnless(HAS_WSPROTO, "websocket extra is not installed") + def test_atomic_handshake_timeout_is_terminal_while_send_is_blocked(self) -> None: + runtime = SmallOS().setKernel(Unix()) + transport = _BlockingTransport() + config = WebSocketConfig( + handshake_timeout=0.02, + idle_timeout=1, + close_timeout=0.02, + deadline_resolution=0.005, + ) + state = _make_state(runtime, transport, unused_handler, config=config) + outcomes: list[BaseException] = [] + + async def accept_job(task) -> None: + state.handler_task = task + try: + await WebSocket(state).accept() + except BaseException as exc: + outcomes.append(exc) + + accept_task = SmallTask(2, accept_job, name="blocked-handshake") + deadline_task = SmallTask( + 2, _run_deadlines, args=(state,), name="handshake-deadline" + ) + state.deadline_task = deadline_task + runtime.fork([accept_task, deadline_task]) + runtime.start() + + self.assertEqual(transport.send_calls, 1) + self.assertEqual(state.handshake_state, "failed") + self.assertFalse(state.accepted) + self.assertFalse(state.rejected) + self.assertIsNotNone(state.handshake_error) + + async def retry_job(task) -> None: + try: + await WebSocket(state).accept() + except BaseException as exc: + outcomes.append(exc) + + retry_task = SmallTask(2, retry_job, name="handshake-retry") + runtime.fork(retry_task) + runtime.start() + self.assertIsInstance(outcomes[-1], Exception) + self.assertIn("already decided", str(outcomes[-1])) + self.assertEqual(transport.send_calls, 1) + + pending = _make_state( + SmallOS().setKernel(Unix()), _RecordingTransport(), unused_handler + ) + pending.request_shutdown() + self.assertEqual(pending.handshake_state, "failed") + self.assertIsInstance(pending.handshake_error, WebSocketDisconnect) + + @unittest.skipUnless(HAS_WSPROTO, "websocket extra is not installed") + def test_ping_is_armed_before_send_and_only_matching_pong_clears(self) -> None: + runtime = SmallOS().setKernel(Unix()) + state = _make_accepted_state(runtime, _RecordingTransport(), unused_handler) + observations: list[tuple[object, ...]] = [] + _handle_pong(state, b"unsolicited") + self.assertIsNone(state._pending_ping_generation) + + async def immediate_pong(event, size, *, wait): + observations.append( + ( + state._pending_ping_generation, + state._pending_ping_payload, + state.pong_deadline is not None, + ) + ) + _handle_pong(state, b"wrong") + observations.append((state._pending_ping_generation,)) + _handle_pong(state, b"probe") + + state._enqueue = immediate_pong + + async def ping_job(task) -> None: + await WebSocket(state).ping(b"probe") + + ping_task = SmallTask(2, ping_job, name="fast-pong") + runtime.fork(ping_task) + runtime.start() + self.assertIsNone(ping_task.exception) + self.assertEqual(observations[0][1:], (b"probe", True)) + self.assertIsNotNone(observations[1][0]) + self.assertIsNone(state._pending_ping_generation) + self.assertIsNone(state.pong_deadline) + + @unittest.skipUnless(HAS_WSPROTO, "websocket extra is not installed") + def test_fragment_metadata_is_coalesced_and_close_reasons_are_sanitized(self) -> None: + api = _load_wsproto() + runtime = SmallOS().setKernel(Unix()) + state = _make_accepted_state(runtime, _RecordingTransport(), unused_handler) + client = api.Connection(api.ConnectionType.CLIENT) + + _receive_protocol_data( + state, + client.send( + api.TextMessage(data="a", message_finished=False) + ), + ) + _drain_protocol_events(state) + for _ in range(2048): + _receive_protocol_data( + state, + client.send(api.TextMessage(data="", message_finished=False)), + ) + _drain_protocol_events(state) + self.assertEqual(len(state._message_buffer), 1) + _receive_protocol_data( + state, + client.send(api.TextMessage(data="b", message_finished=True)), + ) + _drain_protocol_events(state) + self.assertEqual(state.inbox.popleft().text, "ab") + + peer_close_state = _make_accepted_state( + runtime, _RecordingTransport(), unused_handler + ) + peer = api.Connection(api.ConnectionType.CLIENT) + _receive_protocol_data( + peer_close_state, + peer.send(api.CloseConnection(code=1000, reason="peer detail")), + ) + self.assertTrue(_drain_protocol_events(peer_close_state)) + command = peer_close_state.outbox.popleft() + self.assertEqual(command.size, 2 + len(b"peer detail")) + self.assertEqual(command.event.reason, "peer detail") + + protocol_error_state = _make_accepted_state( + runtime, _RecordingTransport(), unused_handler + ) + _receive_protocol_data(protocol_error_state, b"\x83\x80mask") + self.assertTrue(_drain_protocol_events(protocol_error_state)) + generated = protocol_error_state.outbox.popleft() + self.assertEqual(int(generated.event.code), 1002) + self.assertEqual(generated.event.reason, "protocol error") + self.assertEqual(protocol_error_state.disconnect.reason, "protocol error") + + @unittest.skipUnless(HAS_WSPROTO, "websocket extra is not installed") + def test_slow_writer_is_interrupted_by_bounded_deadlines(self) -> None: + runtime = SmallOS().setKernel(Unix()) + config = WebSocketConfig( + idle_timeout=1, + write_timeout=0.02, + close_timeout=0.02, + pong_timeout=1, + deadline_resolution=0.005, + ) + state = _make_accepted_state( + runtime, _BlockingTransport(), unused_handler, config=config + ) + outcomes: list[str] = [] + + async def sender(task) -> None: + state.handler_task = task + try: + await WebSocket(state).send_text("blocked") + finally: + outcomes.append("sender-finished") + + sender_task = SmallTask(2, sender, name="blocked-sender") + writer_task = SmallTask(2, _run_writer, args=(state,), name="blocked-writer") + deadline_task = SmallTask(2, _run_deadlines, args=(state,), name="write-deadline") + state.writer_task = writer_task + state.deadline_task = deadline_task + started = time.monotonic() + runtime.fork([sender_task, writer_task, deadline_task]) + runtime.start() + + self.assertLess(time.monotonic() - started, 0.5) + self.assertEqual(outcomes, ["sender-finished"]) + self.assertIsNotNone(state.disconnect) + self.assertEqual(state.disconnect.code, 1006) + self.assertEqual(state.disconnect.reason, "write timed out") + self.assertEqual(state.outbox_bytes, 0) + self.assertEqual(len(state.outbox), 0) + + @unittest.skipUnless(HAS_WSPROTO, "websocket extra is not installed") + def test_critical_handler_failures_keep_identity_and_ordinary_errors_translate(self) -> None: + for critical in (KeyboardInterrupt("stop"), SystemExit(7)): + with self.subTest(critical=type(critical).__name__): + runtime = SmallOS().setKernel(Unix()) + + async def critical_handler(socket, error=critical) -> None: + raise error + + state = _make_state( + runtime, _RecordingTransport(), critical_handler + ) + handler_task = SmallTask( + 2, _run_handler, args=(state,), name="critical-handler" + ) + state.handler_task = handler_task + runtime.fork(handler_task) + try: + runtime.start() + except (KeyboardInterrupt, SystemExit) as caught: + self.assertIs(caught, critical) + else: + self.fail("critical handler exception did not escape unchanged") + self.assertIs(state.fatal_error, critical) + self.assertEqual(state.handshake_state, "failed") + + runtime = SmallOS().setKernel(Unix()) + + async def ordinary_handler(socket) -> None: + raise RuntimeError("private detail") + + transport = _RecordingTransport() + state = _make_state(runtime, transport, ordinary_handler) + handler_task = SmallTask( + 2, _run_handler, args=(state,), name="ordinary-handler" + ) + state.handler_task = handler_task + runtime.fork(handler_task) + runtime.start() + self.assertIsNone(handler_task.exception) + self.assertTrue(state.rejected) + self.assertIn(b"HTTP/1.1 500 Internal Server Error", transport.payloads[0]) + self.assertNotIn(b"private detail", transport.payloads[0]) + @unittest.skipUnless(HAS_WSPROTO, "websocket extra is not installed") def test_frame_guard_bounds_declared_length_before_payload(self) -> None: guard = _FrameGuard(max_payload_bytes=1024) @@ -517,7 +841,7 @@ async def handshake_timeout(websocket: WebSocket) -> None: @app.websocket("/idle-timeout") async def idle_timeout(websocket: WebSocket) -> None: await websocket.accept() - await websocket.receive() + await runtime.cursor.sleep(5) @app.websocket("/pong-timeout") async def pong_timeout(websocket: WebSocket) -> None: @@ -611,6 +935,84 @@ def client_work() -> None: self.assertEqual(outcomes["pong_code"], 1002) self.assertTrue(server.finished) + def test_idle_deadline_cancels_adapter_waiting_handler(self) -> None: + runtime = SmallOS().setKernel(Unix()) + release = threading.Event() + entered = threading.Event() + app = SmallServer( + websocket_config=WebSocketConfig( + idle_timeout=0.05, + close_timeout=0.1, + deadline_resolution=0.01, + ) + ) + errors: list[BaseException] = [] + + def blocking_work() -> None: + entered.set() + if not release.wait(2): + raise TimeoutError("adapter worker was not released") + + with AdapterRegistry( + blocking=ThreadAdapter(max_workers=1, max_pending=1) + ) as services: + + @app.websocket("/adapter-idle") + async def adapter_idle(websocket: WebSocket) -> None: + await websocket.accept() + await services.call("blocking", blocking_work) + + try: + server = app.serve(runtime, host="127.0.0.1", port=0) + except PermissionError: + self.skipTest("the current sandbox does not permit loopback TCP binds") + + close_codes: list[int | None] = [] + + def client_work() -> None: + try: + with socket.create_connection( + ("127.0.0.1", server.port), timeout=3 + ) as stream: + stream.sendall( + b"GET /adapter-idle HTTP/1.1\r\nHost: localhost\r\n" + b"Upgrade: websocket\r\nConnection: Upgrade\r\n" + b"Sec-WebSocket-Version: 13\r\n" + b"Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==\r\n\r\n" + ) + response = b"" + while b"\r\n\r\n" not in response: + response += stream.recv(4096) + if not entered.wait(1): + raise TimeoutError("adapter handler did not start") + api = _load_wsproto() + client = api.Connection(api.ConnectionType.CLIENT) + events = _receive_events( + stream, client, api.CloseConnection + ) + close = next( + event + for event in events + if isinstance(event, api.CloseConnection) + ) + close_codes.append(close.code) + stream.sendall(client.send(close.response())) + except BaseException as exc: + errors.append(exc) + finally: + release.set() + server.close() + + worker = threading.Thread(target=client_work, daemon=True) + worker.start() + runtime.start() + worker.join(timeout=5) + + self.assertFalse(worker.is_alive()) + self.assertEqual(errors, []) + self.assertEqual(close_codes, [1001]) + self.assertTrue(server.finished) + def test_server_shutdown_attempts_close_and_releases_children(self) -> None: api = _load_wsproto() runtime = SmallOS().setKernel(Unix()) From a291238795debcd4c62bad964d3c62e67c709729 Mon Sep 17 00:00:00 2001 From: Michael Emperador Date: Sat, 22 Aug 2026 02:26:46 -0500 Subject: [PATCH 12/14] docs: document WebSocket deadline semantics --- guide/websockets.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/guide/websockets.md b/guide/websockets.md index 4413e2d..342cc82 100644 --- a/guide/websockets.md +++ b/guide/websockets.md @@ -34,8 +34,14 @@ app.listen() The application must explicitly call `accept()` or `reject()` before using message operations. Returning without either decision sends a sanitized 403. Text, binary, fragmented messages, Ping/Pong, and Close are supported. Queue, -frame, message, connection, handshake, idle, Pong, and close limits are finite -and configurable through `WebSocketConfig`. +frame, message, connection, handshake, idle, Pong, write, and close limits are +finite and configurable through `WebSocketConfig`. + +Only one application Ping may await a Pong at a time. The timeout is armed +before the frame is written, and only a Pong with the matching payload clears +it. Handshake, idle, Pong, and close deadlines also bound cleanup when a peer +stops reading; expired connections cancel handler work owned by that +connection. An origin allowlist is strongly recommended when browser credentials or cookies are involved. A selected subprotocol must have been offered by the From 4bed08af074e17a8ca7f843a46bbe0eed40b5305 Mon Sep 17 00:00:00 2001 From: Michael Emperador Date: Sat, 22 Aug 2026 02:39:39 -0500 Subject: [PATCH 13/14] docs: clarify WebSocket example and closure semantics --- examples/websocket_echo.py | 4 ++-- guide/development.md | 5 +++-- guide/websockets.md | 16 ++++++++++++++-- 3 files changed, 19 insertions(+), 6 deletions(-) diff --git a/examples/websocket_echo.py b/examples/websocket_echo.py index 01bf4d3..4153dea 100644 --- a/examples/websocket_echo.py +++ b/examples/websocket_echo.py @@ -13,9 +13,9 @@ ) -@app.websocket("/echo", subprotocols=("echo.v1",)) +@app.websocket("/echo") async def echo(socket: WebSocket) -> None: - await socket.accept(subprotocol="echo.v1") + await socket.accept() async for message in socket: if message.is_text: await socket.send_text(message.text) diff --git a/guide/development.md b/guide/development.md index 12bde66..b51b5c0 100644 --- a/guide/development.md +++ b/guide/development.md @@ -41,8 +41,9 @@ python3 examples/manual_runtime.py python3 examples/websocket_echo.py ``` -The two network examples block until shutdown. `adapters_demo.py` completes on -its own and demonstrates SQLite thread affinity and a persistent asyncio loop. +The three network examples block until shutdown. `adapters_demo.py` completes +on its own and demonstrates SQLite thread affinity and a persistent asyncio +loop. ## Contribution boundaries diff --git a/guide/websockets.md b/guide/websockets.md index 342cc82..5fe7b48 100644 --- a/guide/websockets.md +++ b/guide/websockets.md @@ -46,8 +46,15 @@ connection. An origin allowlist is strongly recommended when browser credentials or cookies are involved. A selected subprotocol must have been offered by the client and allowed by the route. Outbound saturation raises -`WebSocketCapacityError`; peer or server closure raises `WebSocketDisconnect` -from receive operations. +`WebSocketCapacityError`. + +Direct calls to `receive()`, `receive_text()`, or `receive_bytes()` raise +`WebSocketDisconnect` after already queued messages have been delivered when +the peer or application closes the connection. `async for message in socket` +instead treats that disconnect as normal iteration completion. Server shutdown +and expired handshake, idle, Pong, write, or close deadlines may cancel the +connection handler to guarantee bounded cleanup, so application resource +cleanup belongs in the handler's `finally` block. Send calls complete after the serialized frame bytes have been flushed through the connection writer. They do not mean the peer application has processed the @@ -56,3 +63,8 @@ message. This release does not implement `wss://` termination, compression, custom extensions, or RFC 8441 WebSockets over HTTP/2. Put TLS at a trusted reverse proxy until SmallServer gains a native TLS boundary. + +The runnable [`websocket_echo.py`](../examples/websocket_echo.py) accepts +clients without requiring a subprotocol. The `/chat` example above separately +demonstrates explicit negotiation: a client must offer `chat.v1` before the +handler may select it. From e1de8a9756a957374d53cc31afda1eba24d7f343 Mon Sep 17 00:00:00 2001 From: Michael Emperador Date: Sun, 23 Aug 2026 16:13:34 -0500 Subject: [PATCH 14/14] chore: move public documentation out of WebSocket PR --- README.md | 120 +++++++++++++++----------------- guide/adapters.md | 49 ------------- guide/api-reference.md | 97 -------------------------- guide/configuration.md | 61 ---------------- guide/development.md | 59 ---------------- guide/errors-observability.md | 57 --------------- guide/getting-started.md | 66 ------------------ guide/index.md | 29 -------- guide/platforms-kernels.md | 40 ----------- guide/protocol-roadmap.md | 31 --------- guide/requests-and-responses.md | 68 ------------------ guide/routing.md | 66 ------------------ guide/runtime-lifecycle.md | 78 --------------------- guide/websockets.md | 70 ------------------- tests/test_documentation.py | 78 --------------------- 15 files changed, 56 insertions(+), 913 deletions(-) delete mode 100644 guide/adapters.md delete mode 100644 guide/api-reference.md delete mode 100644 guide/configuration.md delete mode 100644 guide/development.md delete mode 100644 guide/errors-observability.md delete mode 100644 guide/getting-started.md delete mode 100644 guide/index.md delete mode 100644 guide/platforms-kernels.md delete mode 100644 guide/protocol-roadmap.md delete mode 100644 guide/requests-and-responses.md delete mode 100644 guide/routing.md delete mode 100644 guide/runtime-lifecycle.md delete mode 100644 guide/websockets.md delete mode 100644 tests/test_documentation.py diff --git a/README.md b/README.md index 73b5744..3f9b5c3 100644 --- a/README.md +++ b/README.md @@ -1,64 +1,68 @@ # SmallServer -SmallServer is a SmallOS-native web framework for Python 3.10+. It serves -bounded HTTP/1.1 requests, exact and timeout-bounded regex routes, optional -RFC 6455 WebSockets, explicit runtime lifecycle control, and third-party -execution adapters. - -```python -from smallserver import Response, SmallServer - -app = SmallServer() +SmallServer is a SmallOS-native web framework in early development. It provides +a bounded HTTP/1.1 server, static async routing for GET, POST, PUT, PATCH, and +DELETE, and explicit escape hatches for blocking and asyncio-native libraries. +## Current scope -@app.get("/health") -async def health(request): - return Response.json({"status": "ok"}) +The current package provides an HTTP/1.1 baseline over a SmallOS runtime. It can: +- register static async routes for GET, POST, PUT, PATCH, and DELETE; +- dispatch an already-created `Request` to a handler; +- return deterministic `Response` values, including HTTP/1.1 bytes; +- return 404 for an unknown path and 405 with `Allow` for a known path using + the wrong method. +- bind a non-blocking TCP listener, accept bounded concurrent connections, and + wait for read/write readiness through SmallOS; +- parse one `Content-Length` HTTP/1.1 request per connection and close after + its response. -if __name__ == "__main__": - app.listen(host="127.0.0.1", port=8000) -``` +Keep-alive/pipelining, TLS, path parameters, and HTTP/2 are not implemented yet. -Install the canonical SmallOS master dependency and this package, then run the -demo: +## Install for development -```console +```bash python3 -m pip install -r requirements.txt python3 -m pip install -e . -python3 demo.py +python3 -m unittest discover -s tests -v ``` -Application code can use blocking `app.listen()` without importing SmallOS. -Advanced applications can supply their own runtime, schedule without starting -it, and own adapters for blocking or asyncio-native libraries. +SmallOS is installed from the canonical `master` branch in `requirements.txt`. +It owns scheduling, socket readiness, and foreign execution adapters. -## Optional features +## Run the demo -Static routing and HTTP-only imports need neither optional protocol package. -Install only the feature an application serves: +The included demo starts a task API at `http://127.0.0.1:8000`. Common +application code does not need to import or configure SmallOS. -```console -python3 -m pip install -e '.[regex-routes]' -python3 -m pip install -e '.[websocket]' +```bash +python3 -m pip install -r requirements.txt +python3 demo.py ``` -Regex routes use bounded full-path matching after exact static lookup. -WebSocket routes use a separate static route table, so an ordinary `GET` and a -WebSocket Upgrade may coexist at one path. +Leave the process running and exercise GET, POST, PUT, PATCH, and DELETE from a +browser or HTTP client. Press Ctrl-C for deterministic cleanup without a +traceback. The static `/tasks` path is intentional: path parameters arrive +with a later milestone. + +## Bind a server + +Create the application and call blocking `listen()`. It lazily creates a +SmallOS runtime with the Unix kernel, while SmallOS remains the scheduler and +owner of socket readiness. `port=0` asks the operating system for an available +port, which is useful in tests and local tooling. ```python -from smallserver import WebSocket +from smallserver import Response, SmallServer + +app = SmallServer() +@app.get("/health") +async def health(request): + return Response.json({"status": "ok"}) -@app.websocket("/echo", origins={"https://app.example.com"}) -async def echo(socket: WebSocket) -> None: - await socket.accept() - async for message in socket: - if message.is_text: - await socket.send_text(message.text) - else: - await socket.send_bytes(message.bytes) +app.listen(host="127.0.0.1", port=8000) ``` ### Configure the managed SmallOS runtime @@ -91,8 +95,6 @@ configure it directly with `SmallOS(config=...)`; SmallServer rejects `task_capacity` must reserve at least `max_connections + 2` task slots for the listener and shutdown-control tasks, and both server task priorities must be below `priority_levels`. -Configuring a regex route-error observer adds one dedicated SmallOS task, so -that mode requires at least `max_connections + 3` slots. Managed `listen()` blocks and catches Ctrl-C after closing its listener, wakeup channel, connections, and server tasks. It returns the closed `ServerHandle`, @@ -100,28 +102,18 @@ whose cached `address` and `port` remain available for diagnostics. Each current connection accepts one request and sends a `Connection: close` response. -## Documentation - -- [Guide index](guide/index.md) -- [Getting started](guide/getting-started.md) -- [Routing](guide/routing.md) -- [WebSockets](guide/websockets.md) -- [Requests and responses](guide/requests-and-responses.md) -- [Runtime and lifecycle](guide/runtime-lifecycle.md) -- [Configuration](guide/configuration.md) -- [Third-party adapters](guide/adapters.md) -- [Errors and observability](guide/errors-observability.md) -- [Platforms and kernels](guide/platforms-kernels.md) -- [API reference](guide/api-reference.md) -- [Protocol roadmap](guide/protocol-roadmap.md) -- [Development](guide/development.md) - -See [`demo.py`](demo.py) for all five HTTP methods and a WebSocket route, -[`examples/websocket_echo.py`](examples/websocket_echo.py) for a bounded echo -server, [`examples/manual_runtime.py`](examples/manual_runtime.py) for -caller-owned SmallOS startup, and -[`examples/adapters_demo.py`](examples/adapters_demo.py) for blocking and -asyncio escape hatches. +If the runtime exits normally but cleanup is incomplete, `listen()` raises +`ServerFinalizationError`; retain it and call `retry_cleanup()` until it +succeeds. If runtime startup raises while cleanup is incomplete, ordinary +failures are wrapped by `ServerStartupError`; `KeyboardInterrupt` and +`SystemExit` keep their identity and expose that cleanup owner as `__cause__`. +Until cleanup succeeds, the application rejects another listener invocation. + +## Advanced runtime control + +Supply a configured runtime when the application needs to coordinate other +SmallOS tasks. A supplied runtime is never reconfigured or destroyed, and +`start=False` schedules the server without starting it: ```python from SmallPackage import SmallOS, Unix diff --git a/guide/adapters.md b/guide/adapters.md deleted file mode 100644 index 2bc91b1..0000000 --- a/guide/adapters.md +++ /dev/null @@ -1,49 +0,0 @@ -# Third-party adapters - -SmallServer handlers run on the SmallOS scheduler and must not call blocking -functions or drive a second event loop directly. SmallOS supplies explicit -escape hatches: - -- `ThreadAdapter` for blocking or thread-affine callables; -- `AsyncioAdapter` for coroutine-based libraries on a persistent asyncio loop. - -The application creates, bounds, and shuts down these adapters. SmallServer -does not create adapter workers as a side effect of `listen()`. - -```python -from SmallPackage.adapters.errors import AdapterError -from SmallPackage.adapters.threads import ThreadAdapter -from smallserver import AdapterRegistry, Response, http_error_from_adapter - -services = AdapterRegistry(blocking=ThreadAdapter(max_workers=2, max_pending=8)) - - -async def handler(request): - try: - result = await services.call("blocking", str.upper, "smallserver") - except AdapterError as exc: - raise http_error_from_adapter(exc) - return Response.text(result) - - -services.shutdown() -``` - -In a real application, keep the registry alive around the complete runtime -lifecycle; do not shut it down immediately after defining a handler. The -context manager calls `shutdown()` automatically and cancels pending adapter -work when its body exits with an exception. - -`AdapterRegistry` accepts named, user-created adapters that provide `call()` -and `shutdown()`. It rejects duplicate names and duplicate adapter objects, -delegates calls, exposes stable registration order through `names()` and -`items()`, and shuts adapters down in reverse registration order. - -`http_error_from_adapter()` intentionally sanitizes adapter failures: -capacity, unavailable, closed, and cancelled conditions become generic 503 -responses; other adapter failures become a generic 500. Log internal causes in -application-controlled telemetry if needed, but do not expose them to clients. - -See [`examples/adapters_demo.py`](../examples/adapters_demo.py) for a runnable -SQLite and asyncio example and [`examples/manual_runtime.py`](../examples/manual_runtime.py) -for the surrounding runtime lifecycle. diff --git a/guide/api-reference.md b/guide/api-reference.md deleted file mode 100644 index 3dcabd2..0000000 --- a/guide/api-reference.md +++ /dev/null @@ -1,97 +0,0 @@ -# API reference - -This page summarizes the public names exported by `smallserver`. Signatures -omit overload detail where prose is clearer. - -## Application - -### `SmallServer(regex_config=None, *, route_error_observer=None, websocket_config=None)` - -- `get(path)`, `post(path)`, `put(path)`, `patch(path)`, `delete(path)` — route - decorators for one supported method. -- `route(path, methods)` — atomic multi-method route decorator. -- `get_regex`, `post_regex`, `put_regex`, `patch_regex`, `delete_regex`, and - `route_regex` — optional timeout-bounded full-path route decorators. -- `websocket(path, *, origins=None, subprotocols=())` — static WebSocket route. -- `async dispatch(request)` — dispatch an existing `Request`. -- `listen(host="127.0.0.1", port=8000, config=None, *, runtime=None, start=None)` - — managed blocking lifecycle or caller-owned scheduling/startup. -- `serve(runtime, host="127.0.0.1", port=8000, config=None)` — schedule against - a caller-owned runtime and return immediately. - -## HTTP values - -### `Headers(values=None)` - -Immutable, case-insensitive mapping with `items()` and `get()`. - -### `Request(method, path, headers, body=b"", version="HTTP/1.1", ...)` - -Frozen request value with validated method, routed path, headers, byte body, -raw target, query string, immutable path parameters, and route pattern. - -### `Response(status=200, body=b"", headers=Headers())` - -Frozen response value. `Response.text()`, `Response.json()`, and `to_http1()` -provide common construction and serialization paths. - -## Server lifecycle - -### `ServerConfig(...)` - -Frozen finite-limit configuration. See [Configuration](configuration.md). - -### `ServerHandle` - -Read-only properties: `address`, `port`, `closed`, `failure`, `finished`, -`cleanup_errors`, and `owned_connection_count`. - -Operations: `close()`, `async close_from_task(task)`, and `finalize()`. - -## Regex routing - -- `RegexRouteConfig` — finite route, pattern, capture, path, and timeout limits. -- `RegexRoutesUnavailable` — the optional matching engine is missing. -- `RouteMatchTimeout` and `RoutePathTooLarge` — bounded matching failures. -- `RouteErrorEvent` — sanitized event sent to the optional observer. - -## WebSockets - -- `WebSocketConfig` — finite frame, message, mailbox, connection, and deadline - limits. -- `WebSocket` — `accept`, `reject`, receive/send methods, `ping`, `close`, - iteration, `request`, and negotiated `subprotocol`. -- `WebSocketMessage` — complete typed text or binary message. -- `WebSocketDisconnect`, `WebSocketStateError`, and `WebSocketCapacityError` — - application-visible lifecycle and capacity outcomes. -- `WebSocketUnavailable` — the optional `wsproto` engine is missing. - -See [WebSockets](websockets.md) for handshake and completion semantics. - -## Adapters - -### `AdapterRegistry(**adapters)` - -Methods: `register`, `get`, `call`, `names`, `items`, and `shutdown`. It also -implements a context manager and exposes `closed`. - -### `http_error_from_adapter(exc)` - -Convert a SmallOS `AdapterError` to a sanitized `HTTPError`. - -### `AdapterShutdownError` - -Raised after registry shutdown attempts every adapter but one or more fail. -Its `failures` tuple contains `(name, exception)` entries. - -## Errors - -- `HTTPError(status, detail="")` -- `ServerConfigurationError` -- `ServerStartupError` -- `ServerFinalizationError` - -Cleanup errors expose `cleanup_errors`, `cleanup_complete`, `retry_cleanup()`, -and `finalize()`. `ServerStartupError` additionally exposes `primary_error`. - -Public typing information is shipped through `smallserver/py.typed`. diff --git a/guide/configuration.md b/guide/configuration.md deleted file mode 100644 index 7200540..0000000 --- a/guide/configuration.md +++ /dev/null @@ -1,61 +0,0 @@ -# Configuration - -Pass a `ServerConfig` to `listen()` or `serve()` to tune finite listener, -parser, and scheduling limits. - -```python -from smallserver import ServerConfig, SmallServer - -app = SmallServer() -config = ServerConfig( - max_connections=50, - max_header_bytes=16 * 1024, - max_header_count=64, - max_body_bytes=512 * 1024, - receive_chunk_bytes=8 * 1024, - listener_priority=1, - connection_priority=2, - accept_batch_size=16, -) -``` - -| Setting | Default | Purpose | -| --- | ---: | --- | -| `max_connections` | 100 | Maximum connection streams still owned by the server. | -| `max_header_bytes` | 16 KiB | Maximum HTTP/1.1 request-head bytes. | -| `max_header_count` | 100 | Maximum number of request header fields. | -| `max_body_bytes` | 1 MiB | Maximum `Content-Length` and buffered request body. | -| `receive_chunk_bytes` | 8 KiB | Bytes requested from the transport per read. | -| `listener_priority` | 1 | SmallOS listener and close-watcher task priority. | -| `connection_priority` | 2 | SmallOS connection-task priority. | -| `accept_batch_size` | 16 | Accepts before the listener explicitly yields. | -| `max_request_target_bytes` | 8 KiB | Maximum origin-form request-target bytes. | -| `max_route_error_events` | 16 | Bounded sanitized observer-event queue. | - -Every field must be a positive integer; booleans are rejected. The public port -must be an integer from 0 through 65535. `port=0` delegates port selection to -the kernel. - -At connection capacity, the listener waits on a scheduler signal instead of -accepting and discarding more streams. Connections whose close failed still -count against the limit because the server continues to own them. A close -failure is fatal to further acceptance and remains visible for cleanup retry. - -Limits are per `ServerHandle`. They bound HTTP input and framework-owned -connections, but they do not limit memory allocated by your handlers, response -bodies, adapter queues, or downstream libraries; configure those separately. - -## Regex routing limits - -Pass `RegexRouteConfig` to `SmallServer(regex_config=...)`. It bounds path -bytes, pattern length, route count, named captures, individual match time, and -total matching time. Regex configuration is validated without importing the -optional engine; registration imports it lazily. - -## WebSocket limits - -Pass `WebSocketConfig` to `SmallServer(websocket_config=...)`. Its positive, -finite settings bound frame and reassembled-message bytes, inbox/outbox counts -and bytes, read/write chunks, WebSocket connection count, and handshake, idle, -Pong, write, and close deadlines. `max_frame_payload_bytes` cannot exceed -`max_message_bytes`. See [WebSockets](websockets.md) for operational behavior. diff --git a/guide/development.md b/guide/development.md deleted file mode 100644 index b51b5c0..0000000 --- a/guide/development.md +++ /dev/null @@ -1,59 +0,0 @@ -# Development - -## Set up - -Use Python 3.10 or newer and install the canonical SmallOS master checkout plus -SmallServer in editable mode: - -```console -python3 -m pip install -r requirements.txt -python3 -m pip install -e . -``` - -Install both optional test surfaces with -`python3 -m pip install -e '.[regex-routes,websocket]'` when validating the -complete feature set. Also run the suite without extras to keep HTTP-only -imports lazy. - -For reproducible validation, put the canonical SmallOS checkout at the front of -`PYTHONPATH` rather than relying on an unrelated installed package named -`SmallPackage`. - -## Validate - -```console -python3 -m unittest discover -s tests -v -python3 -m compileall -q smallserver demo.py examples tests -git diff --check -``` - -The suite covers routing, HTTP values and parsing, WebSockets, adapters, -lifecycle failure ownership, kernel transport behavior, and real loopback -serving when the local environment permits binds. Documentation tests verify -the tracked guide set, relative Markdown links, and Python code-block syntax. - -Run the examples when their platform requirements are available: - -```console -python3 demo.py -python3 examples/adapters_demo.py -python3 examples/manual_runtime.py -python3 examples/websocket_echo.py -``` - -The three network examples block until shutdown. `adapters_demo.py` completes -on its own and demonstrates SQLite thread affinity and a persistent asyncio -loop. - -## Contribution boundaries - -- Keep framework networking behind SmallOS kernel abstractions. -- Preserve finite parsing, connection, and adapter limits. -- Keep the HTTP core independent of `asyncio`. -- Add lifecycle tests for partial acquisition and cleanup failure paths. -- Update the README and focused guide page when a public API changes. -- Extend [Protocol roadmap](protocol-roadmap.md) docs on the feature branch that - implements a protocol; do not describe planned APIs as present. - -The ignored `docs/` and `skills/` trees support local agent workflows. Public, -versioned user documentation belongs in `README.md` and `guide/`. diff --git a/guide/errors-observability.md b/guide/errors-observability.md deleted file mode 100644 index 9b1bb5d..0000000 --- a/guide/errors-observability.md +++ /dev/null @@ -1,57 +0,0 @@ -# Errors and observability - -SmallServer separates expected HTTP responses, configuration mistakes, -runtime failures, and incomplete cleanup ownership. - -## Handler-facing errors - -Raise `HTTPError(status, detail)` for an expected 4xx or 5xx response. Status -must be between 400 and 599. The detail becomes a plain-text response; do not -put secrets or raw downstream exceptions in it. - -The network server converts ordinary handler exceptions into a generic 500. -`app.dispatch()` only catches `HTTPError`, so direct dispatch in tests preserves -programming errors. - -## Configuration errors - -`ServerConfigurationError` reports a runtime or kernel capability that cannot -support the requested lifecycle. Type and value mistakes generally raise -`TypeError` or `ValueError` before binding. - -## Startup and finalization ownership - -`ServerStartupError` means startup failed and one or more acquired resources -could not yet be released. Its `primary_error` is the original failure; -`cleanup_errors` contains the current cleanup failures. Retain the exception -and call `retry_cleanup()` or `finalize()` until it returns `True`. - -`ServerFinalizationError` means a started runtime returned normally but server -cleanup remains incomplete. It exposes the same `cleanup_errors`, -`cleanup_complete`, `retry_cleanup()`, and `finalize()` contract. - -`KeyboardInterrupt` and `SystemExit` retain their identity. If rollback is -incomplete, their `__cause__` is the `ServerStartupError` cleanup owner. An -abandoned incomplete cleanup error makes one best-effort retry and emits a -`ResourceWarning` if ownership remains. - -## ServerHandle state - -Observe these stable properties: - -- `address` and `port`: cached bind result; -- `closed`: shutdown has been requested; -- `finished`: all server-owned cleanup is complete; -- `failure`: first fatal listener or connection-cleanup failure, if any; -- `cleanup_errors`: current failures for still-owned resources; -- `owned_connection_count`: active and retained connection streams. - -SmallServer does not provide a logging backend, metrics registry, or tracing -system. Applications should report sanitized handle state and -their own handler/adapter telemetry without reaching into private attributes. - -Regex matching timeouts may be reported through `route_error_observer`. Its -dedicated SmallOS task receives bounded, traceback-free `RouteErrorEvent` -values containing only an opaque route ID and category. Observer failures and -capacity drops are isolated and counted on `ServerHandle`; the observer must -return quickly and use an execution adapter for blocking work. diff --git a/guide/getting-started.md b/guide/getting-started.md deleted file mode 100644 index 1101ab5..0000000 --- a/guide/getting-started.md +++ /dev/null @@ -1,66 +0,0 @@ -# Getting started - -## Requirements - -SmallServer requires Python 3.10 or newer. During development, -`requirements.txt` installs SmallOS from the canonical GitHub `master` branch; -SmallServer itself declares no package-index runtime dependency yet. - -```console -python3 -m pip install -r requirements.txt -python3 -m pip install -e . -``` - -Install `.[regex-routes]` for regex routes or `.[websocket]` for WebSocket -routes. Static HTTP usage imports without either optional package. - -The first command needs Git and network access. Pin the SmallOS revision in -your own deployment lock or build process if reproducibility matters. - -## Create an application - -```python -from smallserver import Request, Response, SmallServer - -app = SmallServer() - - -@app.get("/health") -async def health(request: Request) -> Response: - return Response.json({"status": "ok"}) - - -if __name__ == "__main__": - app.listen(host="127.0.0.1", port=8000) -``` - -Run the file and request the exact path: - -```console -curl -i http://127.0.0.1:8000/health -``` - -`listen()` creates a SmallOS runtime with its Unix kernel, blocks while that -runtime runs, and handles Ctrl-C by cleaning up server-owned resources. Normal -application code does not need to import SmallOS. - -Use `port=0` when a test or tool needs the kernel to choose an available port. -Because managed `listen()` blocks, inspect the returned handle only after the -runtime has stopped. For access to the bound port while the server is running, -use [caller-owned runtime mode](runtime-lifecycle.md#caller-owned-runtime). - -## Try the task demo - -[`demo.py`](../demo.py) implements GET, POST, PUT, PATCH, and DELETE on the -static `/tasks` route plus a WebSocket echo route at `/ws`: - -```console -python3 demo.py -curl -i http://127.0.0.1:8000/tasks -curl -i -X POST -H 'Content-Type: application/json' \ - --data '{"title":"read the guide"}' http://127.0.0.1:8000/tasks -``` - -Every ordinary HTTP/1.1 connection serves one request and closes after the -response. See [Routing](routing.md), [WebSockets](websockets.md), and -[Configuration](configuration.md) before building a larger application. diff --git a/guide/index.md b/guide/index.md deleted file mode 100644 index 54bac06..0000000 --- a/guide/index.md +++ /dev/null @@ -1,29 +0,0 @@ -# SmallServer guide - -This guide documents the current SmallServer API: bounded HTTP/1.1, static and -regex routing, WebSockets, managed or caller-owned SmallOS lifecycle, and -execution adapters. - -## Learn SmallServer - -1. [Getting started](getting-started.md) — install, create an app, and run it. -2. [Routing](routing.md) — exact and bounded regex routes. -3. [WebSockets](websockets.md) — HTTP/1.1 Upgrade, messages, and deadlines. -4. [Requests and responses](requests-and-responses.md) — immutable HTTP values. -5. [Runtime and lifecycle](runtime-lifecycle.md) — managed and caller-owned modes. -6. [Configuration](configuration.md) — finite parser and protocol limits. - -## Integrate and operate - -- [Third-party adapters](adapters.md) -- [Errors and observability](errors-observability.md) -- [Platforms and kernels](platforms-kernels.md) -- [API reference](api-reference.md) - -## Project direction - -- [Protocol roadmap](protocol-roadmap.md) -- [Development](development.md) - -SmallServer currently supports HTTP/1.1 and RFC 6455 Upgrade only. See the -roadmap for deferred HTTP/2, TLS, compression, and keep-alive work. diff --git a/guide/platforms-kernels.md b/guide/platforms-kernels.md deleted file mode 100644 index e29f0df..0000000 --- a/guide/platforms-kernels.md +++ /dev/null @@ -1,40 +0,0 @@ -# Platforms and kernels - -SmallServer delegates networking, readiness, task registration, and task -cancellation to SmallOS. Production framework modules do not import Python's -`socket` module directly; kernel-owned transport handles remain opaque to the -application. - -## Desktop default - -Managed `app.listen()` lazily imports `SmallOS` and the `Unix` kernel, configures -that runtime, and starts it. If the dependency or Unix kernel is unavailable, -it raises `ServerConfigurationError` and asks the caller to provide a suitable -runtime. - -The canonical SmallOS dependency is installed from GitHub `master` by -`requirements.txt`. Python package metadata intentionally has no runtime -dependency until SmallOS has an unambiguous published distribution contract. - -## Custom and constrained kernels - -A supplied runtime must expose a configured `kernel` plus callable `fork`, -`resume_task`, and `cancel_task` operations. Starting it through SmallServer -also requires `start`. - -The kernel must satisfy SmallOS's network capability contract for listeners, -streams, readiness, retry direction, addresses, and cleanup. Capability checks -occur before SmallServer binds a listener. - -A wakeup channel is optional: - -- with one, `ServerHandle.close()` can notify the scheduler from another thread; -- without one, external `close()` raises and a running task must call - `await handle.close_from_task(task)`; -- after a caller-owned scheduler exits, `handle.finalize()` is the owner-thread - cleanup path on either kind of kernel. - -Do not infer that a MicroPython-like platform supports managed Unix mode or a -thread-safe wakeup just because it can accept TCP connections. Supply the -platform runtime explicitly and test its real capability surface and cleanup -behavior. diff --git a/guide/protocol-roadmap.md b/guide/protocol-roadmap.md deleted file mode 100644 index 9be0286..0000000 --- a/guide/protocol-roadmap.md +++ /dev/null @@ -1,31 +0,0 @@ -# Protocol and feature roadmap - -The current branch provides bounded HTTP/1.1, static and regex routes, shared -HTTP values, RFC 6455 Upgrade, explicit SmallOS lifecycle control, and -application-owned execution adapters. - -## Routing extensions - -Timeout-bounded regex routes and immutable named captures are implemented as -the optional `regex-routes` extra. Exact static routes retain precedence. - -## WebSocket server - -Optional RFC 6455 server support over HTTP/1.1 Upgrade is implemented through -the `websocket` extra with SmallOS-native transport ownership and bounded -protocol state. TLS, compression, custom extensions, and RFC 8441 WebSockets -over HTTP/2 remain separate concerns. - -## HTTP/2 server - -The HTTP/2 feature is planned as an optional cleartext prior-knowledge server -using the hyper-h2 4.x sans-I/O stack. Its branch is responsible for documenting -dependency installation, stream concurrency, flow control, protocol limits, -GOAWAY, and graceful shutdown. SmallServer does not yet accept HTTP/2 -connections or export an HTTP/2 configuration type. - -## Existing HTTP/1.1 limits - -Keep-alive, pipelining, TLS termination, automatic protocol detection, h2c -upgrade, middleware/ASGI compatibility, and automatic request-data decoding are -not implemented here. Treat this page as direction, not a compatibility promise. diff --git a/guide/requests-and-responses.md b/guide/requests-and-responses.md deleted file mode 100644 index b27c79f..0000000 --- a/guide/requests-and-responses.md +++ /dev/null @@ -1,68 +0,0 @@ -# Requests and responses - -`Request`, `Response`, and `Headers` are immutable value objects shared by the -router and server. - -## Request - -A handler receives: - -- `method`: a valid HTTP token; -- `path`: the request target, beginning with `/`; -- `headers`: a case-insensitive `Headers` mapping; -- `body`: complete request bytes; -- `version`: `HTTP/1.1` for the current network server; -- `raw_target`: the exact origin-form target; -- `query_string`: undecoded text after `?`; -- `path_params` and `route_pattern`: immutable regex-route context when used. - -The base parser accepts one origin-form HTTP/1.1 request framed by zero or one -`Content-Length` header. It rejects transfer encoding, multiple content lengths, -missing `Host`, invalid targets, oversized input, and pipelined bytes. It does -not decode JSON, forms, query parameters, percent escapes, or text for you. - -```python -import json - -from smallserver import HTTPError, Request, Response - - -async def create(request: Request) -> Response: - try: - value = json.loads(request.body.decode("utf-8")) - except (UnicodeDecodeError, json.JSONDecodeError) as exc: - raise HTTPError(400, "body must be valid JSON") from exc - return Response.json({"received": value}, status=201) -``` - -## Headers - -Header lookup is case-insensitive while iteration preserves the originally -provided spelling. Names must be HTTP tokens; values cannot contain control -characters other than horizontal tab or characters outside Latin-1. Duplicate -names are rejected after case folding. - -```python -from smallserver import Headers - -headers = Headers({"Content-Type": "application/json"}) -assert headers["content-type"] == "application/json" -``` - -## Response - -Construct `Response(status, body, headers)`, or use `Response.text()` and -`Response.json()`. Bodies must already be `bytes`. An explicit `Content-Length` -must exactly match the body; otherwise construction fails. The HTTP/1.1 server -adds a length when absent and sends `Connection: close`. - -```python -from smallserver import Response - -plain = Response.text("ready") -created = Response.json({"id": "1"}, status=201) -empty = Response(status=204) -``` - -`Response.to_http1()` is available for deterministic serialization and tests. -Applications normally return the value and let SmallServer write it. diff --git a/guide/routing.md b/guide/routing.md deleted file mode 100644 index 5fcd6b5..0000000 --- a/guide/routing.md +++ /dev/null @@ -1,66 +0,0 @@ -# Routing - -SmallServer checks exact static routes first, then optional timeout-bounded -regular-expression routes. Register static routes with `get`, `post`, `put`, -`patch`, `delete`, or the multi-method `route` decorator. - -```python -from smallserver import Response, SmallServer - -app = SmallServer() - - -@app.route("/status", methods=("GET", "POST")) -async def status(request): - return Response.text(request.method) -``` - -Methods passed to `route` are normalized to uppercase and duplicates are -removed. Registration rejects an empty method set, unsupported methods, -non-callable handlers, duplicate method/path pairs, and paths that do not start -with `/`. A failed multi-method registration does not partially add a route. - -## Dispatch behavior - -- An exact method/path match runs its async handler. -- A known path with the wrong method returns 405 and a sorted `Allow` header. -- An unknown path returns 404. -- A handler must return an awaitable whose result is a `Response`. -- Raising `HTTPError` produces the requested 4xx or 5xx response. - -An ordinary handler exception becomes a generic 500 when the network server -invokes it. A direct call to `await app.dispatch(request)` preserves ordinary -exceptions for tests and embedding code. - -## Request targets - -The parser preserves the exact ASCII origin-form target as -`request.raw_target`. Routing uses `request.path`, excluding the raw query -string stored in `request.query_string`. Neither field nor a regex capture is -percent-decoded, so `/files/a%2Fb` remains distinct from `/files/a/b`. - -## Regex routes - -Install the bounded matching engine only when needed: - -```console -python3 -m pip install -e '.[regex-routes]' -``` - -```python -@app.get_regex(r"/users/(?P[0-9]+)") -async def user(request): - return Response.json({"user_id": request.path_params["user_id"]}) -``` - -`route_regex(pattern, methods)` and the five method-specific regex decorators -use full-path matching in registration order after static lookup. Only named -captures are exposed through immutable `request.path_params`; an unmatched -optional group is omitted. `request.route_pattern` identifies the selected -pattern. - -Patterns must begin with a literal `/`. Registration and dispatch bound route -count, pattern length, capture count, path bytes, each match, and total matching -time. A timeout becomes a sanitized 500 on the network path and may be observed -through the bounded `route_error_observer` channel without disclosing the -hostile path. Oversized paths return 414 before matching. diff --git a/guide/runtime-lifecycle.md b/guide/runtime-lifecycle.md deleted file mode 100644 index d67611e..0000000 --- a/guide/runtime-lifecycle.md +++ /dev/null @@ -1,78 +0,0 @@ -# Runtime and lifecycle - -SmallOS always owns scheduling and I/O readiness. SmallServer offers one -managed mode for normal applications and explicit modes for applications that -coordinate other SmallOS tasks. - -Only one listener invocation may be active on a `SmallServer` instance. The -instance can be reused after its handle is fully finished. - -## Managed runtime - -```python -from smallserver import Response, SmallServer - -app = SmallServer() - - -@app.get("/") -async def index(request): - return Response.text("hello") - - -app.listen(host="127.0.0.1", port=8000) -``` - -With no `runtime`, `listen()` lazily creates `SmallOS().setKernel(Unix())`, -starts it, blocks until shutdown, and finalizes server-owned resources. In this -managed mode, Ctrl-C is consumed after successful cleanup and the closed -`ServerHandle` is returned. - -## Caller-owned runtime - -Supply a configured runtime to schedule the listener without starting it: - -```python -from SmallPackage import SmallOS, Unix -from smallserver import Response, SmallServer - -runtime = SmallOS().setKernel(Unix()) -app = SmallServer() - - -@app.get("/health") -async def health(request): - return Response.json({"status": "ok"}) - - -handle = app.listen(runtime=runtime, start=False, port=0) -print(handle.address) -try: - runtime.start() -finally: - handle.finalize() -``` - -With a supplied runtime, `start=False` is the default. `app.serve(runtime, ...)` -is the equivalent schedule-and-return compatibility API. Passing `start=True` -starts the supplied runtime once; the caller still owns that runtime. - -## Shutdown operations - -- `handle.close()` requests shutdown from outside the scheduler when the kernel - provides a wakeup channel. Unix supports this path. -- `await handle.close_from_task(task)` shuts down from the currently running - SmallOS task and is required on kernels without a wakeup channel. -- `handle.finalize()` performs idempotent owner-thread cleanup after a manually - started scheduler has exited or failed. - -`closed` means shutdown was requested. `finished` is stronger: the listener, -wakeup channel, connections, and retained cleanup work have all completed. -Failed closes remain owned and appear in `cleanup_errors`; call the appropriate -cleanup operation again from a safe context. - -`address` and `port` are cached and remain readable after close. `failure` -reports the first fatal listener or connection-cleanup failure. - -See [Errors and observability](errors-observability.md) for incomplete startup -and finalization transactions. diff --git a/guide/websockets.md b/guide/websockets.md deleted file mode 100644 index 5fe7b48..0000000 --- a/guide/websockets.md +++ /dev/null @@ -1,70 +0,0 @@ -# WebSockets - -Install the optional protocol engine before serving WebSocket routes: - -```bash -python3 -m pip install -e '.[websocket]' -``` - -WebSocket routes use HTTP/1.1 Upgrade while SmallOS continues to own task -scheduling and socket readiness. A normal `GET` route may use the same path; -requests without Upgrade headers remain ordinary HTTP requests. - -```python -from smallserver import SmallServer, WebSocket - -app = SmallServer() - -@app.websocket( - "/chat", - origins={"https://app.example.com"}, - subprotocols=("chat.v1",), -) -async def chat(socket: WebSocket) -> None: - await socket.accept(subprotocol="chat.v1") - async for message in socket: - if message.is_text: - await socket.send_text(message.text) - else: - await socket.send_bytes(message.bytes) - -app.listen() -``` - -The application must explicitly call `accept()` or `reject()` before using -message operations. Returning without either decision sends a sanitized 403. -Text, binary, fragmented messages, Ping/Pong, and Close are supported. Queue, -frame, message, connection, handshake, idle, Pong, write, and close limits are -finite and configurable through `WebSocketConfig`. - -Only one application Ping may await a Pong at a time. The timeout is armed -before the frame is written, and only a Pong with the matching payload clears -it. Handshake, idle, Pong, and close deadlines also bound cleanup when a peer -stops reading; expired connections cancel handler work owned by that -connection. - -An origin allowlist is strongly recommended when browser credentials or -cookies are involved. A selected subprotocol must have been offered by the -client and allowed by the route. Outbound saturation raises -`WebSocketCapacityError`. - -Direct calls to `receive()`, `receive_text()`, or `receive_bytes()` raise -`WebSocketDisconnect` after already queued messages have been delivered when -the peer or application closes the connection. `async for message in socket` -instead treats that disconnect as normal iteration completion. Server shutdown -and expired handshake, idle, Pong, write, or close deadlines may cancel the -connection handler to guarantee bounded cleanup, so application resource -cleanup belongs in the handler's `finally` block. - -Send calls complete after the serialized frame bytes have been flushed through -the connection writer. They do not mean the peer application has processed the -message. - -This release does not implement `wss://` termination, compression, custom -extensions, or RFC 8441 WebSockets over HTTP/2. Put TLS at a trusted reverse -proxy until SmallServer gains a native TLS boundary. - -The runnable [`websocket_echo.py`](../examples/websocket_echo.py) accepts -clients without requiring a subprotocol. The `/chat` example above separately -demonstrates explicit negotiation: a client must offer `chat.v1` before the -handler may select it. diff --git a/tests/test_documentation.py b/tests/test_documentation.py deleted file mode 100644 index 044afd5..0000000 --- a/tests/test_documentation.py +++ /dev/null @@ -1,78 +0,0 @@ -import re -import unittest -from pathlib import Path - - -ROOT = Path(__file__).resolve().parents[1] -GUIDE_FILES = { - "index.md", - "getting-started.md", - "routing.md", - "requests-and-responses.md", - "runtime-lifecycle.md", - "websockets.md", - "configuration.md", - "adapters.md", - "errors-observability.md", - "platforms-kernels.md", - "api-reference.md", - "protocol-roadmap.md", - "development.md", -} -MARKDOWN_LINK = re.compile(r"(? {}".format(document.relative_to(ROOT), target)) - continue - if separator: - headings = { - heading_slug(value) - for value in HEADING.findall(destination.read_text()) - } - if fragment not in headings: - failures.append( - "{} -> {} (missing heading)".format( - document.relative_to(ROOT), target - ) - ) - self.assertEqual(failures, []) - - def test_python_code_blocks_compile(self): - failures = [] - for document in self._documents(): - for position, source in enumerate(PYTHON_BLOCK.findall(document.read_text()), 1): - try: - compile(source, "{}:block{}".format(document, position), "exec") - except SyntaxError as exc: - failures.append(str(exc)) - self.assertEqual(failures, []) - - -if __name__ == "__main__": - unittest.main()