tyrtulia-tui 1.0.0__py3-none-any.whl

tyrtulia_tui/__init__.py

@@ -0,0 +1,3 @@
+"""Terminal client for Tyrtulia."""
+
+__version__ = "1.0.0"

tyrtulia_tui/__main__.py

@@ -0,0 +1,3 @@
+from tyrtulia_tui.main import main
+
+main()

tyrtulia_tui/app.py

@@ -0,0 +1,222 @@
+"""The Textual application."""
+
+import asyncio
+import json
+from functools import partial
+from pathlib import Path
+
+from textual import work
+from textual.app import App
+from textual.binding import Binding
+from textual.markup import escape
+
+from tyrtulia_tui.client import ssh
+from tyrtulia_tui.client.errors import ApiError, NotConnected
+from tyrtulia_tui.client.forum import Forum
+from tyrtulia_tui.client.hal import Resource
+from tyrtulia_tui.client.storage import ReadPositions, Tokens
+from tyrtulia_tui.screens.common import Prompt, describe, then
+from tyrtulia_tui.screens.notifications import NotificationsScreen
+from tyrtulia_tui.screens.profile import ProfileScreen
+from tyrtulia_tui.screens.search import SearchScreen
+from tyrtulia_tui.screens.thread import ThreadScreen
+from tyrtulia_tui.screens.threads import ThreadsScreen
+
+RECONNECT_SECONDS = 5.0
+
+
+class TyrtuliaApp(App[None]):
+    TITLE = "Tyrtulia"
+    BINDINGS = [
+        Binding("q", "quit", "Quit"),
+        Binding("i", "notifications", "Notifications"),
+        Binding("slash", "search", "Search"),
+        Binding("p", "profile", "Profile"),
+        Binding("l", "login", "Log in"),
+        Binding("o", "logout", "Log out"),
+    ]
+
+    def __init__(
+        self,
+        forum: Forum,
+        *,
+        instance: str,
+        positions: ReadPositions,
+        tokens: Tokens | None = None,
+        username: str | None = None,
+        key: Path | None = None,
+        live: bool = True,
+    ) -> None:
+        super().__init__()
+        self.forum = forum
+        self.instance = instance
+        self.positions = positions
+        self.tokens = tokens
+        self.username = username
+        self.key = key
+        self.live = live
+        self.root: Resource | None = None
+        self.unread: int | None = None
+
+    # Start
+
+    async def on_mount(self) -> None:
+        try:
+            await self.connect()
+        except (ApiError, NotConnected) as error:
+            self.exit(return_code=1, message=describe(error))
+            return
+        await self.push_screen(ThreadsScreen())
+
+    async def connect(self) -> None:
+        forum = self.forum
+        try:
+            self.root = await forum.root(refresh=True)
+        except ApiError as error:
+            if error.status != 401 or forum.via_socket:
+                raise
+            # The saved token expired or was revoked: continue without it.
+            self.forget_token()
+            self.root = await forum.root(refresh=True)
+        if not forum.via_socket and not forum.authenticated and self.username and self.key:
+            try:
+                await self.login(self.username, self.key)
+            except Exception as error:
+                self.notify(f"Login failed: {describe(error)}", severity="error", markup=False)
+        await self.after_identity_change()
+
+    async def after_identity_change(self) -> None:
+        self.root = await self.forum.root(refresh=True)
+        self.title = escape(str(self.root["name"]))
+        await self.update_unread()
+        self.refresh_bindings()
+        if self.live and self.forum.authenticated:
+            self.listen()
+
+    async def update_unread(self) -> None:
+        try:
+            me = await self.forum.me()
+        except ApiError, NotConnected:
+            return
+        if me is None:
+            self.sub_title = "reading as a guest · l to log in"
+            return
+        self.unread = me.get("unreadNotificationsCount")
+        unread = f" · {self.unread} unread" if self.unread else ""
+        self.sub_title = escape(f"{me['username']} ({me['role']}){unread}")
+
+    # Identity
+
+    async def login(self, username: str, key: Path) -> None:
+        token = await self.forum.login(username, lambda challenge: ssh.sign(challenge, key))
+        if self.tokens is not None:
+            self.tokens.set(self.instance, token)
+
+    def forget_token(self) -> None:
+        self.forum.token = None
+        if self.tokens is not None:
+            self.tokens.set(self.instance, None)
+
+    def check_action(self, action: str, parameters: tuple[object, ...]) -> bool | None:
+        authenticated = self.forum.authenticated
+        if action in ("notifications", "profile"):
+            return authenticated
+        if action == "login":
+            return not self.forum.via_socket and not authenticated
+        if action == "logout":
+            return not self.forum.via_socket and authenticated
+        return True
+
+    def action_login(self) -> None:
+        self.push_screen(Prompt("Username", self.username or ""), then(self.ask_key))
+
+    def ask_key(self, username: str | None) -> None:
+        if not username:
+            return
+        default = self.key or ssh.default_key() or Path.home() / ".ssh" / "id_ed25519"
+        self.push_screen(
+            Prompt("Private key (or its .pub, to sign with the agent)", str(default)),
+            then(partial(self.run_login, username)),
+        )
+
+    @work(exclusive=True, group="login")
+    async def run_login(self, username: str, key: str | None) -> None:
+        if not key:
+            return
+        try:
+            await self.login(username, Path(key).expanduser())
+        except Exception as error:
+            self.notify(f"Login failed: {describe(error)}", severity="error", markup=False)
+            return
+        self.username = username
+        self.notify(f"Logged in as {username}", markup=False)
+        await self.after_identity_change()
+        self.reload_screen()
+
+    @work(exclusive=True, group="login")
+    async def action_logout(self) -> None:
+        try:
+            await self.forum.logout()
+        except Exception as error:
+            self.notify(describe(error), severity="error", markup=False)
+        self.forget_token()
+        self.workers.cancel_group(self, "events")
+        await self.after_identity_change()
+        self.reload_screen()
+
+    # Navigation
+
+    def open_thread(self, href: str, post_number: int | None = None) -> None:
+        screen = self.screen
+        if isinstance(screen, ThreadScreen) and screen.href == href:
+            screen.focus_post = post_number
+            screen.load()
+            return
+        self.push_screen(ThreadScreen(href, post_number))
+
+    def action_notifications(self) -> None:
+        self.push_screen(NotificationsScreen())
+
+    def action_search(self) -> None:
+        self.push_screen(SearchScreen())
+
+    def action_profile(self) -> None:
+        self.push_screen(ProfileScreen())
+
+    def reload_screen(self) -> None:
+        screen = self.screen
+        load = getattr(screen, "load", None)
+        if callable(load):
+            load()
+        screen.refresh_bindings()
+
+    # Real time
+
+    @work(exclusive=True, group="events")
+    async def listen(self) -> None:
+        last_event_id: str | None = None
+        while self.forum.authenticated:
+            try:
+                async for event in self.forum.events(last_event_id):
+                    last_event_id = event.id or last_event_id
+                    await self.on_server_event(event.event, event.data)
+            except ApiError, NotConnected:
+                pass
+            await asyncio.sleep(RECONNECT_SECONDS)
+
+    async def on_server_event(self, name: str, data: str) -> None:
+        if name == "reset":
+            await self.update_unread()
+            self.reload_screen()
+            return
+        if name != "notification.created":
+            return
+        try:
+            kind = json.loads(data).get("kind", "notification")
+        except ValueError:
+            kind = "notification"
+        self.bell()
+        self.notify(f"New {kind} notification · i to open", title="Tyrtulia", markup=False)
+        await self.update_unread()
+        if isinstance(self.screen, (ThreadsScreen, ThreadScreen, NotificationsScreen)):
+            self.reload_screen()

tyrtulia_tui/client/__init__.py

@@ -0,0 +1 @@
+"""A Tyrtulia API client that only knows ``GET /`` and follows links."""

tyrtulia_tui/client/errors.py

@@ -0,0 +1,17 @@
+"""Errors returned by the server as RFC 9457 problem documents."""
+
+from typing import Any
+
+
+class ApiError(Exception):
+    def __init__(self, status: int, problem: dict[str, Any]) -> None:
+        self.status = status
+        self.problem = problem
+        self.kind = str(problem.get("type", "about:blank")).rsplit("/", 1)[-1]
+        self.title = str(problem.get("title", "Error"))
+        self.detail = str(problem.get("detail") or self.title)
+        super().__init__(f"{status} {self.kind}: {self.detail}")
+
+
+class NotConnected(Exception):
+    """The configured socket or URL cannot be reached."""

tyrtulia_tui/client/forum.py

@@ -0,0 +1,324 @@
+"""The forum as seen by a client: every operation follows a link."""
+
+import json as jsonlib
+from collections.abc import AsyncIterator, Awaitable, Callable
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+from tyrtulia_tui.client.errors import ApiError, NotConnected
+from tyrtulia_tui.client.hal import Link, Page, Resource
+
+API_TYPE = "application/vnd.tyrtulia.v1+json"
+MERGE_PATCH = "application/merge-patch+json"
+EVENT_STREAM = "text/event-stream"
+
+type Signer = Callable[[str], Awaitable[str]]
+
+
+@dataclass(frozen=True, slots=True)
+class ServerEvent:
+    id: str | None
+    event: str
+    data: str
+
+
+class Forum:
+    """A connection to one Tyrtulia instance, through the socket or over HTTP."""
+
+    def __init__(
+        self, http: httpx.AsyncClient, *, via_socket: bool, token: str | None = None
+    ) -> None:
+        self.http = http
+        self.via_socket = via_socket
+        self.token = token
+        self._root: Resource | None = None
+
+    # Plumbing
+
+    def _headers(self, extra: dict[str, str] | None = None) -> dict[str, str]:
+        headers = {"Accept": API_TYPE}
+        if self.token and not self.via_socket:
+            headers["Authorization"] = f"Bearer {self.token}"
+        headers.update(extra or {})
+        return headers
+
+    async def request(
+        self,
+        target: Link | str,
+        *,
+        method: str | None = None,
+        json: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> httpx.Response:
+        href = target.href if isinstance(target, Link) else target
+        verb = method or (target.method if isinstance(target, Link) else "GET")
+        extra = dict(headers or {})
+        content = None
+        if json is not None:
+            content = jsonlib.dumps(json).encode()
+            extra.setdefault("Content-Type", MERGE_PATCH if verb == "PATCH" else "application/json")
+        try:
+            response = await self.http.request(
+                verb, href, content=content, headers=self._headers(extra)
+            )
+        except httpx.TransportError as error:
+            raise NotConnected(str(error) or type(error).__name__) from error
+        if response.status_code >= 400:
+            raise _problem(response)
+        return response
+
+    async def get(self, target: Link | str) -> Resource:
+        response = await self.request(target, method="GET")
+        return Resource.parse(response.json())
+
+    async def send(
+        self,
+        link: Link,
+        json: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> Resource | None:
+        response = await self.request(link, json=json, headers=headers)
+        if response.status_code in (202, 204) or not response.content:
+            return None
+        return Resource.parse(response.json())
+
+    async def page(self, target: Link | str) -> Page:
+        resource = await self.get(target)
+        embedded = resource.get("_embedded", {})
+        name = next(iter(embedded), None)
+        items = resource.embedded_list(name) if name else []
+        return Page(items, resource)
+
+    async def root(self, *, refresh: bool = False) -> Resource:
+        if self._root is None or refresh:
+            self._root = await self.get("/")
+        return self._root
+
+    async def aclose(self) -> None:
+        await self.http.aclose()
+
+    # Identity
+
+    @property
+    def authenticated(self) -> bool:
+        return self._root is not None and self._root.has("me")
+
+    async def me(self) -> Resource | None:
+        root = await self.root()
+        return await self.get(root.link("me")) if root.has("me") else None
+
+    async def login(self, username: str, sign: Signer) -> str:
+        """Request a challenge, sign it with the SSH key and keep the session token."""
+        root = await self.root()
+        challenge = await self.send(root.link("sshChallenge"), {"username": username})
+        assert challenge is not None
+        signature = await sign(str(challenge["challenge"]))
+        session = await self.send(
+            root.link("login"),
+            {"username": username, "challenge": challenge["challenge"], "signature": signature},
+        )
+        assert session is not None
+        self.token = str(session["token"])
+        await self.root(refresh=True)
+        return self.token
+
+    async def logout(self) -> None:
+        me = await self.me()
+        if me is not None and me.has("logout"):
+            await self.send(me.link("logout"))
+        self.token = None
+        await self.root(refresh=True)
+
+    # Threads and posts
+
+    async def threads(self, *, watching: bool = False) -> Page:
+        root = await self.root()
+        rel = "watching" if watching and root.has("watching") else "latest"
+        return await self.page(root.link(rel))
+
+    async def create_thread(self, title: str, body: str) -> Resource:
+        root = await self.root()
+        thread = await self.send(root.link("createThread"), {"title": title, "body": body})
+        assert thread is not None
+        return thread
+
+    async def posts(self, thread: Resource, *, after: int | None = None) -> Page:
+        href = thread.link("posts").href
+        if after is not None:
+            href += f"?after={after}"
+        return await self.page(href)
+
+    async def reply(self, thread: Resource, body: str, reply_to: int | None = None) -> Resource:
+        payload: dict[str, Any] = {"body": body}
+        if reply_to is not None:
+            payload["replyToPostNumber"] = reply_to
+        post = await self.send(thread.link("reply"), payload)
+        assert post is not None
+        return post
+
+    async def edit_post(self, post: Resource, body: str, reason: str | None = None) -> Resource:
+        payload: dict[str, Any] = {"body": body}
+        if reason:
+            payload["reason"] = reason
+        edited = await self.send(
+            post.link("edit"), payload, headers={"If-Match": f'"v{post["version"]}"'}
+        )
+        assert edited is not None
+        return edited
+
+    async def edit_thread(self, thread: Resource, rel: str, **fields: Any) -> Resource:
+        """``rel`` is ``edit``, ``pin`` or ``close``; titles need the first post version."""
+        headers = {}
+        if "title" in fields:
+            current = await self.request(thread.link("self"))
+            headers["If-Match"] = current.headers["ETag"]
+        changed = await self.send(thread.link(rel), fields, headers=headers)
+        assert changed is not None
+        return changed
+
+    async def hide(self, post: Resource, hidden: bool, reason: str | None = None) -> Resource:
+        rel = "hide" if hidden else "unhide"
+        payload: dict[str, Any] = {"hidden": hidden}
+        if hidden and reason:
+            payload["hiddenReason"] = reason
+        changed = await self.send(post.link(rel), payload)
+        assert changed is not None
+        return changed
+
+    async def delete(self, resource: Resource) -> None:
+        await self.send(resource.link("delete"))
+
+    async def subscribe(self, thread: Resource, level: str) -> str:
+        result = await self.send(thread.link("subscribe"), {"level": level})
+        assert result is not None
+        return str(result["level"])
+
+    async def report(self, resource: Resource, message: str) -> None:
+        target = resource.link("self").href
+        await self.send(resource.link("report"), {"target": target, "message": message})
+
+    async def thread_of(self, post: Resource) -> Resource:
+        return await self.get(post.link("up"))
+
+    # Search
+
+    async def search(self, query: str, *, author: str | None = None) -> Page:
+        root = await self.root()
+        return await self.page(root.link("search").expand(q=query, author=author))
+
+    # Notifications
+
+    async def notifications(self, *, unread: bool = False) -> Page:
+        root = await self.root()
+        href = root.link("notifications").href + ("?filter=unread" if unread else "")
+        return await self.page(href)
+
+    async def mark_read(self, notification: Resource) -> None:
+        if notification.has("markRead"):
+            await self.send(notification.link("markRead"), {"read": True})
+
+    async def mark_all_read(self, page: Page) -> None:
+        link = page.resource.links.get("markAllRead")
+        if link is not None and page.items:
+            await self.send(link, {"before": page.items[0]["id"]})
+
+    async def events(self, last_event_id: str | None = None) -> AsyncIterator[ServerEvent]:
+        """The user's event stream; heartbeats are skipped."""
+        root = await self.root()
+        link = root.link("events")
+        headers = self._headers({"Accept": EVENT_STREAM})
+        if last_event_id:
+            headers["Last-Event-ID"] = last_event_id
+        timeout = httpx.Timeout(10.0, read=None)
+        try:
+            async with self.http.stream(
+                "GET", link.href, headers=headers, timeout=timeout
+            ) as response:
+                if response.status_code >= 400:
+                    await response.aread()
+                    raise _problem(response)
+                async for event in parse_events(response.aiter_lines()):
+                    yield event
+        except httpx.TransportError as error:
+            raise NotConnected(str(error) or type(error).__name__) from error
+
+    # Profile and keys
+
+    async def edit_profile(self, **fields: Any) -> Resource:
+        me = await self.me()
+        assert me is not None
+        changed = await self.send(me.link("edit"), fields)
+        assert changed is not None
+        return changed
+
+    async def ssh_keys(self) -> Page:
+        me = await self.me()
+        assert me is not None
+        return await self.page(me.link("sshKeys"))
+
+    async def add_key(self, public_key: str, title: str | None = None) -> Resource:
+        keys = await self.ssh_keys()
+        payload: dict[str, Any] = {"publicKey": public_key.strip()}
+        if title:
+            payload["title"] = title
+        key = await self.send(keys.resource.link("create"), payload)
+        assert key is not None
+        return key
+
+
+def _problem(response: httpx.Response) -> ApiError:
+    try:
+        problem = response.json()
+    except ValueError:
+        problem = {"title": response.reason_phrase or "Error"}
+    if not isinstance(problem, dict):
+        problem = {"title": str(problem)}
+    return ApiError(response.status_code, problem)
+
+
+async def parse_events(lines: AsyncIterator[str]) -> AsyncIterator[ServerEvent]:
+    """Server-Sent Events framing: fields until a blank line; comments are ignored."""
+    event_id: str | None = None
+    name = "message"
+    data: list[str] = []
+    async for line in lines:
+        if line == "":
+            if data:
+                yield ServerEvent(event_id, name, "\n".join(data))
+            name, data = "message", []
+            continue
+        if line.startswith(":"):
+            continue
+        field, _, value = line.partition(":")
+        value = value.removeprefix(" ")
+        if field == "id":
+            event_id = value
+        elif field == "event":
+            name = value
+        elif field == "data":
+            data.append(value)
+
+
+def connect(
+    *,
+    socket: str | None = None,
+    url: str | None = None,
+    token: str | None = None,
+    transport: httpx.AsyncBaseTransport | None = None,
+) -> Forum:
+    """A forum through a Unix socket (no token needed) or over HTTP(S)."""
+    timeout = httpx.Timeout(15.0)
+    if transport is not None:
+        base = url or "http://localhost"
+        http = httpx.AsyncClient(base_url=base, transport=transport, timeout=timeout)
+        return Forum(http, via_socket=socket is not None, token=token)
+    if socket:
+        uds = httpx.AsyncHTTPTransport(uds=socket)
+        http = httpx.AsyncClient(base_url="http://localhost", transport=uds, timeout=timeout)
+        return Forum(http, via_socket=True)
+    if not url:
+        raise NotConnected("No socket and no URL configured")
+    http = httpx.AsyncClient(base_url=url.rstrip("/"), timeout=timeout)
+    return Forum(http, via_socket=False, token=token)

tyrtulia_tui/client/hal.py

@@ -0,0 +1,97 @@
+"""HAL documents: links, embedded resources and RFC 6570 templates."""
+
+import re
+from dataclasses import dataclass, field
+from typing import Any
+from urllib.parse import quote, urlencode
+
+_EXPRESSION = re.compile(r"\{([?&]?)([^}]+)\}")
+
+
+@dataclass(frozen=True, slots=True)
+class Link:
+    href: str
+    method: str = "GET"
+    templated: bool = False
+    type: str | None = None
+    schema: str | None = None
+
+    @classmethod
+    def parse(cls, data: dict[str, Any]) -> Link:
+        return cls(
+            href=str(data["href"]),
+            method=str(data.get("method", "GET")),
+            templated=bool(data.get("templated", False)),
+            type=data.get("type"),
+            schema=data.get("schema"),
+        )
+
+    def expand(self, **values: str | int | None) -> str:
+        """Expand simple (``{name}``) and form-style query (``{?a,b}``) expressions."""
+        if not self.templated:
+            return self.href
+
+        def replace(match: re.Match[str]) -> str:
+            operator, names = match.group(1), match.group(2).split(",")
+            if not operator:
+                return "".join(quote(str(values.get(n) or ""), safe="") for n in names)
+            pairs = [(n, str(values[n])) for n in names if values.get(n) not in (None, "")]
+            if not pairs:
+                return ""
+            return ("?" if operator == "?" else "&") + urlencode(pairs)
+
+        return _EXPRESSION.sub(replace, self.href)
+
+
+@dataclass(slots=True)
+class Resource:
+    """A HAL resource: its own fields, its links and its embedded resources."""
+
+    data: dict[str, Any]
+    links: dict[str, Link] = field(default_factory=dict)
+
+    @classmethod
+    def parse(cls, data: dict[str, Any]) -> Resource:
+        links = {rel: Link.parse(value) for rel, value in data.get("_links", {}).items()}
+        return cls(data=data, links=links)
+
+    def __getitem__(self, key: str) -> Any:
+        return self.data[key]
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return self.data.get(key, default)
+
+    def has(self, rel: str) -> bool:
+        return rel in self.links
+
+    def link(self, rel: str) -> Link:
+        return self.links[rel]
+
+    def embedded(self, name: str) -> Resource | None:
+        value = self.data.get("_embedded", {}).get(name)
+        return Resource.parse(value) if isinstance(value, dict) else None
+
+    def embedded_list(self, name: str) -> list[Resource]:
+        values = self.data.get("_embedded", {}).get(name) or []
+        return [Resource.parse(value) for value in values]
+
+
+@dataclass(slots=True)
+class Page:
+    """A page of a collection, with its navigation links."""
+
+    items: list[Resource]
+    resource: Resource
+
+    @property
+    def meta(self) -> dict[str, Any]:
+        meta: dict[str, Any] = self.resource.get("meta", {})
+        return meta
+
+    @property
+    def next(self) -> Link | None:
+        return self.resource.links.get("next")
+
+    @property
+    def prev(self) -> Link | None:
+        return self.resource.links.get("prev")