dndkit 0.4.0__py3-none-any.whl

dndkit/web/access.py

@@ -0,0 +1,136 @@
+"""Who opens what: each character's private link, and where phones find the server.
+
+A player's link carries a token derived from the campaign, the character and
+a secret kept in the data directory: links survive restarts, cannot be
+guessed, and all change if that file is deleted.
+"""
+
+import base64
+import functools
+import hashlib
+import hmac
+import ipaddress
+import os
+import re
+import secrets
+import socket
+from pathlib import Path
+from urllib.parse import urlsplit
+
+import segno
+
+from dndkit.config import WebSettings
+from dndkit.models import Campaign, Character
+from dndkit.views.everyone import Json
+
+KEY_FILE = "player-links.key"
+SECRET_BYTES = 32
+TOKEN_BYTES = 10  # 80 bits, 16 base32 characters
+TOKEN_PATTERN = re.compile(r"[a-z2-7]{16}")
+
+
+class PlayerLinks:
+    """The token in each character's link."""
+
+    def __init__(self, secret: bytes) -> None:
+        self._secret = secret
+
+    @classmethod
+    def open(cls, data_dir: Path) -> "PlayerLinks":
+        """Links signed with the data directory's secret, created on first use."""
+        return cls(_load_secret(data_dir / KEY_FILE))
+
+    def token(self, campaign: Campaign, character: Character) -> str:
+        """The token for *character* of *campaign*."""
+        message = f"{campaign.id}/{character.id}".encode()
+        digest = hmac.new(self._secret, message, hashlib.sha256).digest()
+        return base64.b32encode(digest[:TOKEN_BYTES]).decode().lower()
+
+    def character_for(self, campaign: Campaign, token: str) -> Character | None:
+        """The character of *campaign* whose link carries *token*, if any."""
+        if not TOKEN_PATTERN.fullmatch(token):
+            return None
+        for character in campaign.characters.values():
+            if hmac.compare_digest(self.token(campaign, character), token):
+                return character
+        return None
+
+
+def join(campaign: Campaign, links: PlayerLinks, base_url: str, reachable: bool) -> Json:
+    """Each character's link and its QR code, for the table screen."""
+    players = []
+    for character in sorted(campaign.characters.values(), key=lambda c: c.name):
+        url = f"{base_url}/p/{links.token(campaign, character)}/"
+        players.append(
+            {"name": character.name, "player": character.player_name, "url": url, "qr": _qr(url)}
+        )
+    return {"reachable": reachable, "players": players}
+
+
+@functools.lru_cache(maxsize=64)
+def _qr(url: str) -> str:
+    """A link's QR code as an image URI; the same links come back at every change."""
+    return segno.make(url, error="m").svg_data_uri(scale=4, dark="#1d1a22", light="#ffffff")
+
+
+def phone_base_url(settings: WebSettings, base_url: str) -> tuple[str, bool]:
+    """The address phones should use, and whether they can reach it at all.
+
+    *base_url* is the one the table screen used. A loopback one (the screen
+    runs on this machine) becomes the LAN address when the server listens on
+    every interface; otherwise phones cannot reach a loopback server.
+    """
+    if settings.public_url:
+        return settings.public_url, True
+    parts = urlsplit(base_url)
+    own = base_url.rstrip("/")
+    if not is_loopback(parts.hostname or ""):
+        return own, True
+    lan = lan_address() if _is_unspecified(settings.host) else None
+    if lan is None:
+        return own, False
+    port = f":{parts.port}" if parts.port else ""
+    return f"{parts.scheme}://{lan}{port}", True
+
+
+def lan_address() -> str | None:
+    """This machine's IPv4 address on the local network; nothing is sent."""
+    with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as probe:
+        try:
+            probe.connect(("192.0.2.1", 9))  # TEST-NET-1: only picks the outgoing interface
+            address: str = probe.getsockname()[0]
+        except OSError:
+            return None
+    return None if is_loopback(address) else address
+
+
+def is_loopback(host: str) -> bool:
+    """True for this machine's own addresses: a request from it, or a URL to it."""
+    if host == "localhost":
+        return True
+    try:
+        return ipaddress.ip_address(host).is_loopback
+    except ValueError:
+        return False
+
+
+def _is_unspecified(host: str) -> bool:
+    try:
+        return ipaddress.ip_address(host).is_unspecified
+    except ValueError:
+        return host == ""
+
+
+def _load_secret(path: Path) -> bytes:
+    try:
+        flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL
+        with os.fdopen(os.open(path, flags, 0o600), "wb") as file:
+            secret = secrets.token_bytes(SECRET_BYTES)
+            file.write(secret)
+            return secret
+    except FileExistsError:
+        secret = path.read_bytes()
+    if len(secret) < SECRET_BYTES:  # a write cut short: start again, links change
+        path.unlink()
+        return _load_secret(path)
+    return secret

dndkit/web/audiences.py

@@ -0,0 +1,111 @@
+"""The views each audience may stream: the table, one player, the game master.
+
+A feed asks for some views by name and gets only those its audience lists.
+"""
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+
+from dndkit.activity import ActivityLog
+from dndkit.config import WebSettings
+from dndkit.errors import GameError, NotFoundError
+from dndkit.game.dice import DiceLog
+from dndkit.models import Campaign
+from dndkit.storage import CampaignStore
+from dndkit.views import desk, everyone, public, widgets
+from dndkit.views.backstage import backstage
+from dndkit.views.everyone import Json
+from dndkit.views.world import world
+from dndkit.web import access
+from dndkit.web.access import PlayerLinks
+from dndkit.web.changes import ACTIVITY, Changes
+from dndkit.web.feed import Render, Renders, View
+
+Views = dict[str, View]
+GM_EVENTS = 40  # of the adventure log, on the backstage
+
+
+@dataclass(frozen=True)
+class Sources:
+    """What the web pages read, all shared with the MCP tools."""
+
+    store: CampaignStore
+    dice: DiceLog
+    changes: Changes
+    links: PlayerLinks
+    settings: WebSettings
+    activity: ActivityLog
+    renders: Renders = field(default_factory=Renders)
+
+    def reading(self, build: Callable[[Campaign], Json]) -> Render:
+        """A render of the active campaign through *build*."""
+
+        def render() -> Json:
+            with self.store.reading() as campaign:
+                return build(campaign)
+
+        return render
+
+    def player(self, token: str) -> str | None:
+        """The name of the character whose link carries *token*, if any."""
+        try:
+            with self.store.reading() as campaign:
+                character = self.links.character_for(campaign, token)
+        except GameError:  # no active campaign
+            return None
+        return character.name if character else None
+
+
+def table(sources: Sources, base_url: str) -> Views:
+    """The shared screen: what everyone at the table may see, and the join codes."""
+    phones, reachable = access.phone_base_url(sources.settings, base_url)
+    join = sources.reading(lambda c: access.join(c, sources.links, phones, reachable))
+    return {
+        **_shared(sources),
+        "join": View(join, f"join@{phones}"),  # the links follow the address asked
+    }
+
+
+def player(sources: Sources, token: str) -> Views:
+    """One player's phone: the shared screen's views and that character's sheet."""
+
+    def sheet(campaign: Campaign) -> Json:
+        character = sources.links.character_for(campaign, token)
+        if character is None:
+            raise NotFoundError("unknownLink")  # a word the page translates
+        return everyone.character(campaign, character.id)
+
+    return {**_shared(sources), "me": View(sources.reading(sheet), f"me@{token}")}
+
+
+def game_master(sources: Sources, base_url: str) -> Views:
+    """The backstage: exact numbers, plans, secrets, and what the model does."""
+    store = sources.store
+    renders: dict[str, Render] = {
+        "combat": sources.reading(widgets.combat),
+        "dice": lambda: everyone.dice(sources.dice, secrets=True),
+        "backstage": sources.reading(backstage),
+        "world": sources.reading(world),
+        "sheets": sources.reading(desk.sheets),
+        "notebook": sources.reading(
+            lambda c: desk.notebook(c, store.current_file, store.data_dir)
+        ),
+        "journal": sources.reading(lambda c: public.journal(c, limit=GM_EVENTS, full=True)),
+    }
+    return {
+        **table(sources, base_url),  # the join codes too
+        **{name: View(render, f"gm/{name}") for name, render in renders.items()},
+        "activity": View(lambda: desk.activity(sources.activity), "gm/activity", ACTIVITY),
+    }
+
+
+def _shared(sources: Sources) -> Views:
+    """What the table and every phone show alike: rendered once for all of them."""
+    renders: dict[str, Render] = {
+        "party": sources.reading(everyone.party),
+        "seating": sources.reading(everyone.seating_chart),
+        "journal": sources.reading(public.journal),
+        "dice": lambda: everyone.dice(sources.dice),
+        "combat": sources.reading(public.combat),
+    }
+    return {name: View(render, f"public/{name}") for name, render in renders.items()}

dndkit/web/changes.py

@@ -0,0 +1,84 @@
+"""Change notices: tools change the game in worker threads, web feeds wait on a loop."""
+
+import asyncio
+import contextlib
+import threading
+
+Waiter = tuple[asyncio.AbstractEventLoop, asyncio.Event]
+
+GAME = "game"  # the campaign and the dice: what every page shows
+ACTIVITY = "activity"  # the model's calls, read ones included: the backstage's log only
+
+
+class Changes:
+    """Versions that go up at every change, one per topic, and wake whoever waits.
+
+    The campaign store and the dice log call ``notify`` from FastMCP's worker
+    threads, the activity log ``notify_activity``; web feeds ``await wait(...)``
+    on an event loop. A view follows one topic, so a read-only call refreshes
+    the backstage's log and nothing else. ``close`` wakes everyone for good, so
+    open feeds end when the server stops.
+    """
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._versions = {GAME: 0, ACTIVITY: 0}
+        self._closed = False
+        self._waiters: set[Waiter] = set()
+
+    @property
+    def version(self) -> int:
+        """How many changes so far, all topics."""
+        with self._lock:
+            return sum(self._versions.values())
+
+    def versions(self) -> dict[str, int]:
+        """How many changes so far, by topic."""
+        with self._lock:
+            return dict(self._versions)
+
+    @property
+    def closed(self) -> bool:
+        """True once the server stops: feeds should end."""
+        with self._lock:
+            return self._closed
+
+    def notify(self, topic: str = GAME) -> None:
+        """Something changed: wake every waiting feed. Safe from any thread."""
+        with self._lock:
+            self._versions[topic] += 1
+            waiters = list(self._waiters)
+        _wake(waiters)
+
+    def notify_activity(self) -> None:
+        """The model called something: only the activity log changed."""
+        self.notify(ACTIVITY)
+
+    def close(self) -> None:
+        """Wake every feed, which then ends."""
+        with self._lock:
+            self._closed = True
+            waiters = list(self._waiters)
+        _wake(waiters)
+
+    async def wait(self, seen: int, timeout: float) -> int:
+        """The version once it is no longer *seen*, or after *timeout* seconds anyway."""
+        waiter = (asyncio.get_running_loop(), asyncio.Event())
+        with self._lock:
+            if sum(self._versions.values()) != seen or self._closed:
+                return sum(self._versions.values())
+            self._waiters.add(waiter)
+        try:
+            with contextlib.suppress(TimeoutError):
+                await asyncio.wait_for(waiter[1].wait(), timeout)
+        finally:
+            with self._lock:
+                self._waiters.discard(waiter)
+        return self.version
+
+
+def _wake(waiters: list[Waiter]) -> None:
+    for loop, event in waiters:
+        # A loop already closed has nobody left to wake.
+        with contextlib.suppress(RuntimeError):
+            loop.call_soon_threadsafe(event.set)

dndkit/web/feed.py

@@ -0,0 +1,112 @@
+"""Server-sent events: each view's JSON at once, then again whenever it changes.
+
+Every open page streams its own views, but they render once per change for
+all of them (``Renders``): ten phones showing the party cost one render, in a
+small pool of threads of their own, so pages never keep the tools waiting.
+"""
+
+import json
+import logging
+import threading
+from collections.abc import AsyncIterator, Callable, Mapping
+from dataclasses import dataclass
+from typing import Any
+
+import anyio
+import anyio.to_thread
+
+from dndkit.errors import GameError, NoActiveCampaignError
+from dndkit.web.changes import GAME, Changes
+
+Render = Callable[[], Any]
+
+logger = logging.getLogger(__name__)
+
+HEARTBEAT_SECONDS = 15.0
+RETRY_MILLISECONDS = 2000
+RENDER_THREADS = 2  # the tools have FastMCP's pool; the pages share these
+
+
+@dataclass(frozen=True)
+class View:
+    """A view to stream: how to render it, the key every feed showing the same
+    thing shares (the table's party, one player's sheet), and the topic of
+    changes it follows (``changes.GAME`` or ``changes.ACTIVITY``)."""
+
+    render: Render
+    key: str
+    topic: str = GAME
+
+
+class Renders:
+    """Each view's latest text, rendered once per change for every feed."""
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._texts: dict[str, tuple[int, str]] = {}
+        self._key_locks: dict[str, threading.Lock] = {}
+        self._limiter: anyio.CapacityLimiter | None = None
+
+    async def all(self, views: Mapping[str, View], versions: Mapping[str, int]) -> dict[str, str]:
+        """The text of every view at *versions*, in the pages' own threads."""
+        if self._limiter is None:
+            self._limiter = anyio.CapacityLimiter(RENDER_THREADS)
+        return await anyio.to_thread.run_sync(self._all, views, versions, limiter=self._limiter)
+
+    def _all(self, views: Mapping[str, View], versions: Mapping[str, int]) -> dict[str, str]:
+        return {name: self.text(view, versions[view.topic]) for name, view in views.items()}
+
+    def text(self, view: View, version: int) -> str:
+        """*view*'s text at *version* of its topic: kept, or rendered now."""
+        with self._lock:
+            key_lock = self._key_locks.setdefault(view.key, threading.Lock())
+        with key_lock:  # a second feed asking at once waits for the first render
+            kept = self._texts.get(view.key)
+            if kept is not None and kept[0] == version:
+                return kept[1]
+            text = render(view)
+            self._texts[view.key] = (version, text)
+            return text
+
+
+async def stream(
+    changes: Changes, views: Mapping[str, View], renders: Renders
+) -> AsyncIterator[str]:
+    """SSE text for *views*: all of them, then those that changed after each change.
+
+    A heartbeat comment keeps idle connections open; the stream ends when the
+    server stops (``Changes.close``).
+    """
+    yield f"retry: {RETRY_MILLISECONDS}\n\n"
+    sent: dict[str, str] = {}
+    seen: dict[str, int] | None = None
+    while not changes.closed:
+        versions = changes.versions()
+        if versions == seen:
+            yield ": still here\n\n"
+        else:
+            seen = versions
+            for name, text in (await renders.all(views, versions)).items():
+                if sent.get(name) != text:
+                    sent[name] = text
+                    yield f"event: {name}\ndata: {text}\n\n"
+        await changes.wait(sum(versions.values()), HEARTBEAT_SECONDS)
+
+
+def render_once(views: Mapping[str, View]) -> dict[str, str]:
+    """Every view's text now, without keeping it (tests, a one-off look)."""
+    return {name: render(view) for name, view in views.items()}
+
+
+def render(view: View) -> str:
+    """One view's JSON; a view that fails sends its error alone, the others go on."""
+    try:
+        data = view.render()
+    except NoActiveCampaignError:
+        data = {"error": "noCampaign"}  # a word the pages translate
+    except GameError as exc:
+        data = {"error": str(exc)}
+    except Exception:
+        logger.exception("A web view failed")
+        data = {"error": "viewFailed"}
+    return json.dumps(data, ensure_ascii=False, separators=(",", ":"))

dndkit/web/routes.py

@@ -0,0 +1,134 @@
+"""The web site: pages and their live feeds, for three audiences.
+
+    /table/       the shared screen: public views and the players' join codes
+    /p/<token>/   one player's phone: public views and that character's sheet
+    /gm/          the game master's backstage, only from this machine
+
+Each page is self-contained HTML (``ui.page``) that opens one event stream,
+``feed?views=a,b``, relative to its own address. Every page is read-only:
+the game changes only through the MCP tools, so the model always knows.
+"""
+
+from urllib.parse import urlsplit
+
+import anyio.to_thread
+from starlette.applications import Starlette
+from starlette.requests import Request
+from starlette.responses import (
+    HTMLResponse,
+    PlainTextResponse,
+    RedirectResponse,
+    Response,
+    StreamingResponse,
+)
+from starlette.routing import Route
+
+from dndkit import ui
+from dndkit.config import WebSettings
+from dndkit.web import audiences, feed
+from dndkit.web.access import is_loopback
+from dndkit.web.audiences import Sources, Views
+
+PAGE_HEADERS = {
+    "Cache-Control": "no-store",
+    "Referrer-Policy": "no-referrer",  # a player's address holds their token
+    "X-Content-Type-Options": "nosniff",
+    "Content-Security-Policy": (
+        "default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; "
+        "img-src data:; connect-src 'self'; base-uri 'none'; frame-ancestors 'none'"
+    ),
+}
+PROXY_HEADERS = ("forwarded", "x-forwarded-for", "x-forwarded-host", "via")
+FEED_HEADERS = {"Cache-Control": "no-cache", "X-Accel-Buffering": "no"}
+
+
+def create_app(sources: Sources) -> Starlette:
+    """The site over *sources*, shared with the running MCP server."""
+
+    async def table_feed(request: Request) -> Response:
+        return _feed(request, sources, audiences.table(sources, str(request.base_url)))
+
+    async def player_page(request: Request) -> Response:
+        name = await _player(sources, request)
+        return _page("player") if name else _refused(request, 404, "unknownLink")
+
+    async def player_feed(request: Request) -> Response:
+        token = request.path_params["token"]
+        if not await _player(sources, request):
+            return _refused(request, 404, "unknownLink")
+        return _feed(request, sources, audiences.player(sources, token))
+
+    async def gm_page(request: Request) -> Response:
+        if not _local(request, sources.settings):
+            return _refused(request, 403, "localOnly")
+        return _page("gm")
+
+    async def gm_feed(request: Request) -> Response:
+        if not _local(request, sources.settings):
+            return _refused(request, 403, "localOnly")
+        return _feed(request, sources, audiences.game_master(sources, str(request.base_url)))
+
+    return Starlette(
+        routes=[
+            Route("/", lambda _: RedirectResponse("/table/")),
+            Route("/table/", lambda _: _page("table")),
+            Route("/table/feed", table_feed),
+            Route("/p/{token}/", player_page),
+            Route("/p/{token}/feed", player_feed),
+            Route("/gm/", gm_page),
+            Route("/gm/feed", gm_feed),
+        ]
+    )
+
+
+def _page(name: str) -> Response:
+    return HTMLResponse(ui.page(name, web=True), headers=PAGE_HEADERS)
+
+
+def _feed(request: Request, sources: Sources, views: Views) -> Response:
+    wanted = [name for name in request.query_params.get("views", "").split(",") if name]
+    unknown = [name for name in wanted if name not in views]
+    if not wanted or unknown:
+        known = ", ".join(sorted(views))
+        return PlainTextResponse(f"Ask for views among: {known}.", status_code=400)
+    stream = feed.stream(sources.changes, {name: views[name] for name in wanted}, sources.renders)
+    return StreamingResponse(stream, media_type="text/event-stream", headers=FEED_HEADERS)
+
+
+async def _player(sources: Sources, request: Request) -> str | None:
+    token = request.path_params["token"]
+    return await anyio.to_thread.run_sync(sources.player, token)
+
+
+def _local(request: Request, settings: WebSettings) -> bool:
+    """A request from this machine, for this server.
+
+    The peer is a loopback address or our own. The Host must name this server
+    too: a hostile page whose domain resolves to 127.0.0.1 (DNS rebinding)
+    would send its own domain. Anything that went through a proxy is refused.
+    """
+    if request.client is None or any(h in request.headers for h in PROXY_HEADERS):
+        return False
+    server = (request.scope.get("server") or ("", 0))[0]
+    peer = request.client.host
+    host = urlsplit(f"//{request.headers.get('host', '')}").hostname or ""
+    ours = {server, urlsplit(settings.public_url or "").hostname}
+    return (is_loopback(peer) or peer == server) and (is_loopback(host) or host in ours)
+
+
+REFUSALS = {  # English, French
+    "unknownLink": (
+        "This link matches no character of the active campaign.",
+        "Ce lien ne correspond à aucun personnage de la campagne active.",
+    ),
+    "localOnly": (
+        "The backstage opens only on the computer running the game.",
+        "La régie ne s'ouvre que sur l'ordinateur qui fait tourner la partie.",
+    ),
+}
+
+
+def _refused(request: Request, status: int, reason: str) -> Response:
+    french = request.headers.get("accept-language", "").lower().startswith("fr")
+    text = REFUSALS[reason][1 if french else 0]
+    return PlainTextResponse(text, status_code=status, headers=PAGE_HEADERS)