"""ProtocolHostRouter: Unified multiplexer for HTTP and WebSocket protocol suites.
Standard library and ws.py only. Multiplexes foreign and native protocol suites
(Nostr, ATProto, ActivityPub, Blossom CAS, Prometheus metrics) over a single
public edge port (e.g. 8000 or 443 with TLS).
"""
from __future__ import annotations
import collections
import dataclasses
import logging
import socket
import threading
import time
from typing import (
Any,
Callable,
Mapping,
Optional,
Sequence,
)
from fleetmesh_core.wire.interfaces import ProtocolHealth
from . import ws
log = logging.getLogger(__name__)
[docs]@dataclasses.dataclass(frozen=True)
class HttpRoute:
prefix: str
handler: Callable[[socket.socket, ws.PlainHTTP], Any]
methods: tuple[str, ...]
owner: str = ''
[docs]@dataclasses.dataclass(frozen=True)
class WebSocketRoute:
path: str
handler: Callable[[ws.WebSocket, str], Any]
owner: str = ''
[docs]class ProtocolHost:
"""Unified HTTP & WebSocket multiplexer mounted on the node's public port."""
[docs] def __init__(
self,
host: str = '127.0.0.1',
port: int = 0,
name: str = 'meshnode',
clock: Optional[Callable[[], int]] = None,
bind_wait: float = 10.0,
max_body_bytes: int = 16 * 1024 * 1024,
) -> None:
self.host: str = host
self.port: int = port
self.name: str = name
self.clock: Callable[[], int] = clock or (lambda: int(time.time()))
self.bind_wait: float = bind_wait
self.max_body_bytes: int = max_body_bytes
self._http_routes: list[HttpRoute] = []
self._ws_routes: list[WebSocketRoute] = []
self._lock: threading.RLock = threading.RLock()
self._server: Optional[ws.Server] = None
self._started: bool = False
self._active_connections: int = 0
self._requests_in: int = 0
self._requests_out: int = 0
self._errors: collections.deque[str] = collections.deque(maxlen=100)
@property
def url(self) -> str:
if self._server is not None:
return self._server.url
return 'ws://%s:%d' % (self.host, self.port)
@property
def http_url(self) -> str:
if self._server is not None:
return 'http://%s:%d' % (self._server.host, self._server.port)
return 'http://%s:%d' % (self.host, self.port)
# ---- Route Registration --------------------------------------------------
[docs] def mount_route(
self,
prefix: str,
handler: Callable[..., Any],
methods: Sequence[str] = ('GET',),
owner: str = '',
) -> None:
"""Mount an HTTP path prefix handler.
Longest prefix matches take precedence. Handler receives `(conn, req: ws.PlainHTTP)`
and returns True if handled, or False to fall through.
"""
clean_prefix = '/' + prefix.strip('/') if prefix != '/' else '/'
norm_methods = tuple(m.upper() for m in methods)
with self._lock:
# Replace existing identical prefix and owner if present
self._http_routes = [
r for r in self._http_routes
if not (r.prefix == clean_prefix and r.owner == owner and r.methods == norm_methods)
]
self._http_routes.append(HttpRoute(
prefix=clean_prefix,
handler=handler,
methods=norm_methods,
owner=owner,
))
# Sort by longest prefix first
self._http_routes.sort(key=lambda r: len(r.prefix), reverse=True)
[docs] def mount_websocket(
self,
path: str,
handler: Callable[[ws.WebSocket, str], Any],
owner: str = '',
) -> None:
"""Mount a WebSocket handler for an exact path or prefix."""
clean_path = '/' + path.strip('/') if path != '/' else '/'
with self._lock:
self._ws_routes = [
r for r in self._ws_routes
if not (r.path == clean_path and r.owner == owner)
]
self._ws_routes.append(WebSocketRoute(
path=clean_path,
handler=handler,
owner=owner,
))
self._ws_routes.sort(key=lambda r: len(r.path), reverse=True)
[docs] def unmount_all(self, owner: str) -> None:
"""Remove all HTTP and WebSocket routes registered by owner."""
if not owner:
return
with self._lock:
self._http_routes = [r for r in self._http_routes if r.owner != owner]
self._ws_routes = [r for r in self._ws_routes if r.owner != owner]
# Compatibility aliases conforming to ProtocolHostRouter interface
[docs] def register_route(self, method: str, prefix: str, handler: Callable[..., Any], owner: str = '') -> None:
"""Alias for mount_route for compatibility."""
self.mount_route(prefix=prefix, handler=handler, methods=(method,), owner=owner)
[docs] def register_websocket(self, path: str, handler: Callable[..., Any], owner: str = '') -> None:
"""Alias for mount_websocket for compatibility."""
self.mount_websocket(path=path, handler=handler, owner=owner)
[docs] def unregister_owner(self, owner: str) -> None:
"""Alias for unmount_all for compatibility."""
self.unmount_all(owner=owner)
# ---- Lifecycle -----------------------------------------------------------
[docs] def start(self) -> ProtocolHost:
with self._lock:
if self._started:
return self
self._server = ws.Server(
handler=self._dispatch_websocket,
host=self.host,
port=self.port,
http_handler=self._dispatch_http,
bind_wait=self.bind_wait,
)
self.host = self._server.host
self.port = self._server.port
self._server.start()
self._started = True
log.info("ProtocolHost serving on %s (%s)", self.url, self.http_url)
return self
@property
def server(self) -> Optional[Any]:
"""Underlying ws.Server instance, preserving socket address metadata even after stop."""
return self._server
[docs] def stop(self) -> None:
with self._lock:
if not self._started or self._server is None:
return
self._server.stop()
self._started = False
# ---- Multiplexing Dispatch -----------------------------------------------
def _dispatch_http(self, conn: socket.socket, req_or_path: Any, headers: Optional[dict[bytes, bytes]] = None) -> None:
self._requests_in += 1
if isinstance(req_or_path, ws.PlainHTTP) or hasattr(req_or_path, 'headers'):
req = req_or_path
else:
path = str(req_or_path)
hdrs = headers or {}
req = ws.PlainHTTP(path=path, headers=hdrs, method='GET', sock=conn)
clean_path = req.path.split('?', 1)[0]
method = req.method.upper()
# Enforce max body size from Content-Length header if present
cl_val = None
if hasattr(req, 'headers') and isinstance(req.headers, Mapping):
cl_val = req.headers.get(b'content-length') or req.headers.get('content-length') or req.headers.get('Content-Length')
if cl_val:
try:
cl_int = int(cl_val)
if cl_int > self.max_body_bytes:
ws.http_response(conn, '413 Payload Too Large',
f'{{"error":"payload_too_large","max_bytes":{self.max_body_bytes}}}'.encode('utf-8'),
'application/json')
self._requests_out += 1
return
if cl_int < 0:
ws.http_response(conn, '400 Bad Request',
b'{"error":"invalid_content_length"}',
'application/json')
self._requests_out += 1
return
except (ValueError, TypeError):
ws.http_response(conn, '400 Bad Request',
b'{"error":"invalid_content_length"}',
'application/json')
self._requests_out += 1
return
with self._lock:
routes = list(self._http_routes)
method_mismatch = False
allowed_methods: set[str] = set()
for route in routes:
prefix = route.prefix
# Match if path equals prefix or starts with prefix/
matched = False
if prefix == '/':
matched = True
elif clean_path == prefix or clean_path.startswith(prefix + '/') or clean_path.startswith(prefix + '?'):
matched = True
if matched:
if '*' in route.methods or method in route.methods:
try:
handled = route.handler(conn, req)
if handled is not False:
self._requests_out += 1
return
except Exception as e:
err = f"route {route.prefix} error: {type(e).__name__}: {e}"
self._errors.append(err)
log.exception("ProtocolHost HTTP error on %s %s: %s", method, clean_path, e)
try:
ws.http_response(conn, '500 Internal Server Error',
b'{"error":"internal_server_error"}',
'application/json')
except OSError:
pass
return
else:
method_mismatch = True
allowed_methods.update(route.methods)
# Handle CORS OPTIONS pre-flight if unhandled
if method == 'OPTIONS':
headers_map = {
'Allow': ', '.join(sorted(allowed_methods or {'GET', 'POST', 'OPTIONS'})),
}
ws.http_response(conn, '204 No Content', b'', 'text/plain', headers=headers_map)
self._requests_out += 1
return
if method_mismatch and allowed_methods:
headers_map = {'Allow': ', '.join(sorted(allowed_methods))}
ws.http_response(conn, '405 Method Not Allowed',
b'{"error":"method_not_allowed"}',
'application/json', headers=headers_map)
self._requests_out += 1
return
# 404 fallback
ws.http_response(conn, '404 Not Found',
f'{{"error":"not_found","path":"{clean_path}"}}'.encode('utf-8'),
'application/json')
self._requests_out += 1
def _dispatch_websocket(self, sock: ws.WebSocket, path: str) -> None:
self._active_connections += 1
clean_path = path.split('?', 1)[0]
with self._lock:
routes = list(self._ws_routes)
handler: Optional[Callable[[ws.WebSocket, str], Any]] = None
for r in routes:
if r.path == '/' or clean_path == r.path or clean_path.startswith(r.path + '/'):
handler = r.handler
break
if handler is None:
# No matching websocket route
try:
sock.close()
except Exception:
pass
self._active_connections = max(0, self._active_connections - 1)
return
try:
handler(sock, path)
except (ws.ConnectionClosed, ConnectionResetError, BrokenPipeError, OSError):
pass
except Exception as e:
err = f"ws {clean_path} error: {type(e).__name__}: {e}"
self._errors.append(err)
log.exception("ProtocolHost WebSocket error on %s: %s", clean_path, e)
finally:
self._active_connections = max(0, self._active_connections - 1)
# ---- Health & Telemetry --------------------------------------------------
[docs] def health(self) -> ProtocolHealth:
with self._lock:
errs = list(self._errors)
return ProtocolHealth(
healthy=self._started,
status="serving" if self._started else "stopped",
connections_active=self._active_connections,
messages_in=self._requests_in,
messages_out=self._requests_out,
errors=tuple(errs[-10:]),
)