Add NETfishing discovery service

netfishing_discovery/__init__.py

@@ -0,0 +1,3 @@
+"""NETfishing discovery service."""
+
+__version__ = "0.1.0"

netfishing_discovery/__main__.py

@@ -0,0 +1,5 @@
+from .server import main
+
+
+if __name__ == "__main__":
+    main()

netfishing_discovery/registry.py

@@ -0,0 +1,253 @@
+"""Thread-safe ephemeral room leases for the NETfishing directory."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import hmac
+import secrets
+import threading
+import time
+import unicodedata
+import uuid
+from collections.abc import Callable, Mapping
+from typing import Any
+
+
+ROOM_NAME_MAX_LENGTH = 48
+VERSION_MAX_LENGTH = 32
+MAX_ROOM_CAPACITY = 128
+DEFAULT_MAX_ROOMS = 4096
+DEFAULT_MAX_ROOMS_PER_ADDRESS = 32
+
+
+class RegistryError(Exception):
+    """Base class for errors safe to translate into API responses."""
+
+
+class ValidationError(RegistryError):
+    pass
+
+
+class RoomNotFoundError(RegistryError):
+    pass
+
+
+class LeaseAuthorizationError(RegistryError):
+    pass
+
+
+class RoomLimitError(RegistryError):
+    pass
+
+
+@dataclass(frozen=True, slots=True)
+class RoomAdvertisement:
+    room_id: str
+    room_name: str
+    address: str
+    port: int
+    current_players: int
+    max_players: int
+    game_version: str
+    protocol_version: int
+    created_at: float
+    updated_at: float
+    expires_at: float
+
+    def public_dict(self) -> dict[str, Any]:
+        return {
+            "room_id": self.room_id,
+            "room_name": self.room_name,
+            "address": self.address,
+            "port": self.port,
+            "current_players": self.current_players,
+            "max_players": self.max_players,
+            "game_version": self.game_version,
+            "protocol_version": self.protocol_version,
+            "created_at": _iso_utc(self.created_at),
+            "updated_at": _iso_utc(self.updated_at),
+            "expires_at": _iso_utc(self.expires_at),
+        }
+
+
+@dataclass(slots=True)
+class _RoomLease:
+    advertisement: RoomAdvertisement
+    token: str
+
+
+def _iso_utc(timestamp: float) -> str:
+    from datetime import datetime, timezone
+
+    return datetime.fromtimestamp(timestamp, timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def _clean_text(value: Any, field_name: str, max_length: int) -> str:
+    if not isinstance(value, str):
+        raise ValidationError(f"{field_name} must be a string")
+    normalized = unicodedata.normalize("NFC", value).strip()
+    if not normalized:
+        raise ValidationError(f"{field_name} cannot be empty")
+    if len(normalized) > max_length:
+        raise ValidationError(f"{field_name} cannot exceed {max_length} characters")
+    if any(unicodedata.category(character).startswith("C") for character in normalized):
+        raise ValidationError(f"{field_name} contains unsupported control characters")
+    return normalized
+
+
+def _clean_int(value: Any, field_name: str, minimum: int, maximum: int) -> int:
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise ValidationError(f"{field_name} must be an integer")
+    if value < minimum or value > maximum:
+        raise ValidationError(f"{field_name} must be between {minimum} and {maximum}")
+    return value
+
+
+class RoomRegistry:
+    """Stores short-lived room advertisements; no state survives a restart."""
+
+    def __init__(
+        self,
+        ttl_seconds: float = 45.0,
+        max_rooms: int = DEFAULT_MAX_ROOMS,
+        max_rooms_per_address: int = DEFAULT_MAX_ROOMS_PER_ADDRESS,
+        clock: Callable[[], float] = time.time,
+    ) -> None:
+        if ttl_seconds <= 0.0:
+            raise ValueError("ttl_seconds must be positive")
+        if max_rooms <= 0 or max_rooms_per_address <= 0:
+            raise ValueError("room limits must be positive")
+        self._ttl_seconds = float(ttl_seconds)
+        self._max_rooms = int(max_rooms)
+        self._max_rooms_per_address = int(max_rooms_per_address)
+        self._clock = clock
+        self._rooms: dict[str, _RoomLease] = {}
+        self._lock = threading.RLock()
+
+    @property
+    def ttl_seconds(self) -> float:
+        return self._ttl_seconds
+
+    def create(self, address: str, payload: Mapping[str, Any]) -> tuple[RoomAdvertisement, str]:
+        now = self._clock()
+        room_id = str(uuid.uuid4())
+        token = secrets.token_urlsafe(32)
+        advertisement = self._build_advertisement(room_id, address, payload, now, now)
+        with self._lock:
+            self._purge_locked(now)
+            if len(self._rooms) >= self._max_rooms:
+                raise RoomLimitError("the public room directory is at capacity")
+            address_room_count = sum(
+                1
+                for lease in self._rooms.values()
+                if lease.advertisement.address == address
+            )
+            if address_room_count >= self._max_rooms_per_address:
+                raise RoomLimitError("too many active rooms from this address")
+            self._rooms[room_id] = _RoomLease(advertisement, token)
+        return advertisement, token
+
+    def update(
+        self,
+        room_id: str,
+        token: str,
+        address: str,
+        payload: Mapping[str, Any],
+    ) -> RoomAdvertisement:
+        now = self._clock()
+        with self._lock:
+            self._purge_locked(now)
+            lease = self._authorized_lease_locked(room_id, token)
+            advertisement = self._build_advertisement(
+                room_id,
+                address,
+                payload,
+                lease.advertisement.created_at,
+                now,
+            )
+            lease.advertisement = advertisement
+            return advertisement
+
+    def delete(self, room_id: str, token: str) -> None:
+        now = self._clock()
+        with self._lock:
+            self._purge_locked(now)
+            self._authorized_lease_locked(room_id, token)
+            del self._rooms[room_id]
+
+    def list_rooms(
+        self,
+        *,
+        game_version: str | None = None,
+        protocol_version: int | None = None,
+    ) -> list[RoomAdvertisement]:
+        now = self._clock()
+        with self._lock:
+            self._purge_locked(now)
+            rooms = [lease.advertisement for lease in self._rooms.values()]
+        if game_version is not None:
+            rooms = [room for room in rooms if room.game_version == game_version]
+        if protocol_version is not None:
+            rooms = [room for room in rooms if room.protocol_version == protocol_version]
+        return sorted(rooms, key=lambda room: (-room.updated_at, room.room_name.casefold()))
+
+    def room_count(self) -> int:
+        now = self._clock()
+        with self._lock:
+            self._purge_locked(now)
+            return len(self._rooms)
+
+    def _build_advertisement(
+        self,
+        room_id: str,
+        address: str,
+        payload: Mapping[str, Any],
+        created_at: float,
+        now: float,
+    ) -> RoomAdvertisement:
+        room_name = _clean_text(payload.get("room_name"), "room_name", ROOM_NAME_MAX_LENGTH)
+        port = _clean_int(payload.get("port"), "port", 1, 65_535)
+        current_players = _clean_int(
+            payload.get("current_players"), "current_players", 1, MAX_ROOM_CAPACITY
+        )
+        max_players = _clean_int(
+            payload.get("max_players"), "max_players", 1, MAX_ROOM_CAPACITY
+        )
+        if current_players > max_players:
+            raise ValidationError("current_players cannot exceed max_players")
+        game_version = _clean_text(
+            payload.get("game_version"), "game_version", VERSION_MAX_LENGTH
+        )
+        protocol_version = _clean_int(
+            payload.get("protocol_version"), "protocol_version", 1, 2_147_483_647
+        )
+        return RoomAdvertisement(
+            room_id=room_id,
+            room_name=room_name,
+            address=address,
+            port=port,
+            current_players=current_players,
+            max_players=max_players,
+            game_version=game_version,
+            protocol_version=protocol_version,
+            created_at=created_at,
+            updated_at=now,
+            expires_at=now + self._ttl_seconds,
+        )
+
+    def _authorized_lease_locked(self, room_id: str, token: str) -> _RoomLease:
+        lease = self._rooms.get(room_id)
+        if lease is None:
+            raise RoomNotFoundError("room does not exist or its lease expired")
+        if not token or not hmac.compare_digest(lease.token, token):
+            raise LeaseAuthorizationError("invalid room lease token")
+        return lease
+
+    def _purge_locked(self, now: float) -> None:
+        expired = [
+            room_id
+            for room_id, lease in self._rooms.items()
+            if lease.advertisement.expires_at <= now
+        ]
+        for room_id in expired:
+            del self._rooms[room_id]

netfishing_discovery/server.py

@@ -0,0 +1,336 @@
+"""Small HTTP/JSON API for NETfishing public-room discovery."""
+
+from __future__ import annotations
+
+import argparse
+from dataclasses import dataclass
+import ipaddress
+import json
+import logging
+import os
+import signal
+import threading
+from http import HTTPStatus
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from socketserver import BaseServer
+from typing import Any
+from urllib.parse import parse_qs, urlsplit
+
+from . import __version__
+from .registry import (
+    DEFAULT_MAX_ROOMS,
+    DEFAULT_MAX_ROOMS_PER_ADDRESS,
+    LeaseAuthorizationError,
+    RoomLimitError,
+    RoomNotFoundError,
+    RoomRegistry,
+    ValidationError,
+)
+
+
+LOGGER = logging.getLogger("netfishing.discovery")
+DEFAULT_MAX_BODY_BYTES = 8 * 1024
+
+
+@dataclass(frozen=True, slots=True)
+class ServerConfig:
+    bind_host: str = "127.0.0.1"
+    bind_port: int = 7770
+    room_ttl_seconds: float = 45.0
+    max_rooms: int = DEFAULT_MAX_ROOMS
+    max_rooms_per_address: int = DEFAULT_MAX_ROOMS_PER_ADDRESS
+    max_body_bytes: int = DEFAULT_MAX_BODY_BYTES
+    trusted_proxy_cidrs: tuple[ipaddress.IPv4Network | ipaddress.IPv6Network, ...] = ()
+
+    @classmethod
+    def from_environment(cls) -> "ServerConfig":
+        proxy_cidrs: list[ipaddress.IPv4Network | ipaddress.IPv6Network] = []
+        raw_cidrs = os.getenv("NETFISHING_DISCOVERY_TRUSTED_PROXY_CIDRS", "")
+        for value in raw_cidrs.split(","):
+            value = value.strip()
+            if value:
+                proxy_cidrs.append(ipaddress.ip_network(value, strict=False))
+        return cls(
+            bind_host=os.getenv("NETFISHING_DISCOVERY_HOST", "127.0.0.1"),
+            bind_port=int(os.getenv("NETFISHING_DISCOVERY_PORT", "7770")),
+            room_ttl_seconds=float(os.getenv("NETFISHING_DISCOVERY_ROOM_TTL", "45")),
+            max_rooms=int(
+                os.getenv("NETFISHING_DISCOVERY_MAX_ROOMS", str(DEFAULT_MAX_ROOMS))
+            ),
+            max_rooms_per_address=int(
+                os.getenv(
+                    "NETFISHING_DISCOVERY_MAX_ROOMS_PER_ADDRESS",
+                    str(DEFAULT_MAX_ROOMS_PER_ADDRESS),
+                )
+            ),
+            max_body_bytes=int(
+                os.getenv("NETFISHING_DISCOVERY_MAX_BODY_BYTES", str(DEFAULT_MAX_BODY_BYTES))
+            ),
+            trusted_proxy_cidrs=tuple(proxy_cidrs),
+        )
+
+
+class DiscoveryHTTPServer(ThreadingHTTPServer):
+    daemon_threads = True
+    allow_reuse_address = True
+
+    def __init__(self, config: ServerConfig, registry: RoomRegistry | None = None) -> None:
+        self.config = config
+        self.registry = registry or RoomRegistry(
+            config.room_ttl_seconds,
+            config.max_rooms,
+            config.max_rooms_per_address,
+        )
+        super().__init__((config.bind_host, config.bind_port), DiscoveryRequestHandler)
+
+
+class DiscoveryRequestHandler(BaseHTTPRequestHandler):
+    server: DiscoveryHTTPServer
+    protocol_version = "HTTP/1.1"
+
+    def do_GET(self) -> None:
+        route = urlsplit(self.path)
+        if route.path == "/health":
+            self._send_json(
+                HTTPStatus.OK,
+                {
+                    "status": "ok",
+                    "service": "netfishing-discovery-server",
+                    "version": __version__,
+                    "active_rooms": self.server.registry.room_count(),
+                },
+            )
+            return
+        if route.path == "/v1/rooms":
+            try:
+                filters = parse_qs(route.query, keep_blank_values=False)
+                game_version = self._single_query_value(filters, "game_version")
+                raw_protocol = self._single_query_value(filters, "protocol_version")
+                protocol_version = int(raw_protocol) if raw_protocol is not None else None
+                if protocol_version is not None and protocol_version <= 0:
+                    raise ValueError
+            except ValueError:
+                self._send_error(HTTPStatus.BAD_REQUEST, "invalid_query", "invalid room filter")
+                return
+            rooms = self.server.registry.list_rooms(
+                game_version=game_version,
+                protocol_version=protocol_version,
+            )
+            self._send_json(
+                HTTPStatus.OK,
+                {
+                    "rooms": [room.public_dict() for room in rooms],
+                    "ttl_seconds": self.server.registry.ttl_seconds,
+                },
+            )
+            return
+        self._send_error(HTTPStatus.NOT_FOUND, "not_found", "route not found")
+
+    def do_POST(self) -> None:
+        if urlsplit(self.path).path != "/v1/rooms":
+            self._send_error(HTTPStatus.NOT_FOUND, "not_found", "route not found")
+            return
+        payload = self._read_json_object()
+        if payload is None:
+            return
+        try:
+            room, token = self.server.registry.create(self._client_address(), payload)
+        except ValidationError as error:
+            self._send_error(HTTPStatus.BAD_REQUEST, "invalid_room", str(error))
+            return
+        except RoomLimitError as error:
+            self._send_error(HTTPStatus.TOO_MANY_REQUESTS, "room_limit", str(error))
+            return
+        self._send_json(
+            HTTPStatus.CREATED,
+            {"room": room.public_dict(), "lease_token": token},
+        )
+
+    def do_PUT(self) -> None:
+        room_id = self._room_id_from_path()
+        if room_id is None:
+            self._send_error(HTTPStatus.NOT_FOUND, "not_found", "route not found")
+            return
+        payload = self._read_json_object()
+        if payload is None:
+            return
+        try:
+            room = self.server.registry.update(
+                room_id,
+                self._bearer_token(),
+                self._client_address(),
+                payload,
+            )
+        except ValidationError as error:
+            self._send_error(HTTPStatus.BAD_REQUEST, "invalid_room", str(error))
+            return
+        except LeaseAuthorizationError as error:
+            self._send_error(HTTPStatus.UNAUTHORIZED, "invalid_lease", str(error))
+            return
+        except RoomNotFoundError as error:
+            self._send_error(HTTPStatus.NOT_FOUND, "room_not_found", str(error))
+            return
+        self._send_json(HTTPStatus.OK, {"room": room.public_dict()})
+
+    def do_DELETE(self) -> None:
+        room_id = self._room_id_from_path()
+        if room_id is None:
+            self._send_error(HTTPStatus.NOT_FOUND, "not_found", "route not found")
+            return
+        try:
+            self.server.registry.delete(room_id, self._bearer_token())
+        except LeaseAuthorizationError as error:
+            self._send_error(HTTPStatus.UNAUTHORIZED, "invalid_lease", str(error))
+            return
+        except RoomNotFoundError as error:
+            self._send_error(HTTPStatus.NOT_FOUND, "room_not_found", str(error))
+            return
+        self.send_response(HTTPStatus.NO_CONTENT)
+        self.send_header("Content-Length", "0")
+        self.end_headers()
+
+    def log_message(self, format_string: str, *args: object) -> None:
+        LOGGER.info("%s - %s", self.client_address[0], format_string % args)
+
+    def _read_json_object(self) -> dict[str, Any] | None:
+        content_type = self.headers.get("Content-Type", "").split(";", 1)[0].strip().lower()
+        if content_type != "application/json":
+            self._send_error(
+                HTTPStatus.UNSUPPORTED_MEDIA_TYPE,
+                "unsupported_media_type",
+                "Content-Type must be application/json",
+            )
+            return None
+        try:
+            content_length = int(self.headers.get("Content-Length", ""))
+        except ValueError:
+            content_length = -1
+        if content_length < 0:
+            self._send_error(
+                HTTPStatus.LENGTH_REQUIRED,
+                "length_required",
+                "Content-Length required",
+            )
+            return None
+        if content_length > self.server.config.max_body_bytes:
+            self._send_error(
+                HTTPStatus.REQUEST_ENTITY_TOO_LARGE,
+                "body_too_large",
+                "request too large",
+            )
+            return None
+        try:
+            payload = json.loads(self.rfile.read(content_length))
+        except (json.JSONDecodeError, UnicodeDecodeError):
+            self._send_error(HTTPStatus.BAD_REQUEST, "invalid_json", "invalid JSON body")
+            return None
+        if not isinstance(payload, dict):
+            self._send_error(HTTPStatus.BAD_REQUEST, "invalid_json", "JSON body must be an object")
+            return None
+        return payload
+
+    def _client_address(self) -> str:
+        peer_text = self.client_address[0]
+        try:
+            peer = ipaddress.ip_address(peer_text)
+        except ValueError:
+            return peer_text
+        if not any(peer in network for network in self.server.config.trusted_proxy_cidrs):
+            return peer_text
+        forwarded = self.headers.get("X-Forwarded-For", "").split(",", 1)[0].strip()
+        try:
+            return str(ipaddress.ip_address(forwarded))
+        except ValueError:
+            return peer_text
+
+    def _room_id_from_path(self) -> str | None:
+        path = urlsplit(self.path).path
+        prefix = "/v1/rooms/"
+        room_id = path[len(prefix) :] if path.startswith(prefix) else ""
+        if not room_id or "/" in room_id:
+            return None
+        return room_id
+
+    def _bearer_token(self) -> str:
+        value = self.headers.get("Authorization", "")
+        scheme, separator, token = value.partition(" ")
+        if separator and scheme.lower() == "bearer":
+            return token.strip()
+        return ""
+
+    @staticmethod
+    def _single_query_value(filters: dict[str, list[str]], key: str) -> str | None:
+        values = filters.get(key)
+        if not values:
+            return None
+        if len(values) != 1:
+            raise ValueError
+        return values[0]
+
+    def _send_error(self, status: HTTPStatus, code: str, message: str) -> None:
+        self._send_json(status, {"error": {"code": code, "message": message}})
+
+    def _send_json(self, status: HTTPStatus, payload: dict[str, Any]) -> None:
+        body = json.dumps(payload, ensure_ascii=False, separators=(",", ":")).encode("utf-8")
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json; charset=utf-8")
+        self.send_header("Content-Length", str(len(body)))
+        self.send_header("Cache-Control", "no-store")
+        self.send_header("X-Content-Type-Options", "nosniff")
+        self.end_headers()
+        self.wfile.write(body)
+
+
+def _install_signal_handlers(server: BaseServer) -> None:
+    def stop_server(_signum: int, _frame: object) -> None:
+        LOGGER.info("shutdown requested")
+        # BaseServer.shutdown() must run on a different thread from serve_forever().
+        threading.Thread(target=server.shutdown, name="discovery-shutdown", daemon=True).start()
+
+    signal.signal(signal.SIGINT, stop_server)
+    signal.signal(signal.SIGTERM, stop_server)
+
+
+def _argument_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--host", help="bind address (overrides environment)")
+    parser.add_argument("--port", type=int, help="bind port (overrides environment)")
+    parser.add_argument("--log-level", default=os.getenv("NETFISHING_DISCOVERY_LOG_LEVEL", "INFO"))
+    return parser
+
+
+def main() -> None:
+    arguments = _argument_parser().parse_args()
+    config = ServerConfig.from_environment()
+    if arguments.host is not None or arguments.port is not None:
+        config = ServerConfig(
+            bind_host=arguments.host or config.bind_host,
+            bind_port=arguments.port or config.bind_port,
+            room_ttl_seconds=config.room_ttl_seconds,
+            max_rooms=config.max_rooms,
+            max_rooms_per_address=config.max_rooms_per_address,
+            max_body_bytes=config.max_body_bytes,
+            trusted_proxy_cidrs=config.trusted_proxy_cidrs,
+        )
+    logging.basicConfig(
+        level=getattr(logging, arguments.log_level.upper(), logging.INFO),
+        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+    )
+    server = DiscoveryHTTPServer(config)
+    _install_signal_handlers(server)
+    LOGGER.info(
+        "NETfishing discovery server %s listening on %s:%d (room TTL %.1fs)",
+        __version__,
+        config.bind_host,
+        server.server_address[1],
+        config.room_ttl_seconds,
+    )
+    try:
+        server.serve_forever(poll_interval=0.25)
+    finally:
+        server.server_close()
+        LOGGER.info("server stopped")
+
+
+if __name__ == "__main__":
+    main()