tyrtulia 1.0.0__py3-none-any.whl

tyrtulia/adapters/http/pagination.py

@@ -0,0 +1,86 @@
+"""Opaque cursors, ``perPage`` and collection documents."""
+
+import base64
+import binascii
+from collections.abc import Callable
+from typing import Any
+from urllib.parse import urlencode
+
+import msgspec
+from flask import request
+
+from tyrtulia.adapters.http.bodies import query_int
+from tyrtulia.domain.entities import Page
+from tyrtulia.domain.errors import validation_failed
+from tyrtulia.use_cases.ports import Cursor, CursorKey
+
+DEFAULT_PER_PAGE = 20
+MAX_PER_PAGE = 100
+
+
+class _CursorData(msgspec.Struct, forbid_unknown_fields=True):
+    k: list[str | int | float]
+    b: bool = False
+
+
+def per_page() -> int:
+    value = query_int("perPage", minimum=1, maximum=MAX_PER_PAGE)
+    return DEFAULT_PER_PAGE if value is None else value
+
+
+def encode_cursor(key: CursorKey, backwards: bool = False) -> str:
+    data = msgspec.json.encode({"k": key, "b": backwards} if backwards else {"k": key})
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode()
+
+
+def read_cursor(size: int) -> Cursor | None:
+    raw = request.args.get("cursor")
+    if raw is None:
+        return None
+    try:
+        padded = raw + "=" * (-len(raw) % 4)
+        data = msgspec.json.decode(base64.urlsafe_b64decode(padded), type=_CursorData)
+    except (binascii.Error, ValueError, msgspec.DecodeError) as error:
+        raise validation_failed("cursor is not valid") from error
+    if len(data.k) != size:
+        raise validation_failed("cursor is not valid")
+    return Cursor(list(data.k), data.b)
+
+
+def href(path: str, **params: Any) -> str:
+    query = {name: value for name, value in params.items() if value is not None}
+    return f"{path}?{urlencode(query)}" if query else path
+
+
+def get_link(target: str, **extra: Any) -> dict[str, Any]:
+    return {"href": target, "method": "GET", **extra}
+
+
+def collection[T](
+    name: str,
+    page: Page[T],
+    items: list[dict[str, Any]],
+    self_href: str,
+    *,
+    next_href: Callable[[T], str],
+    prev_href: Callable[[T], str],
+    links: dict[str, dict[str, Any]] | None = None,
+    meta: dict[str, Any] | None = None,
+    size: int,
+) -> dict[str, Any]:
+    all_links: dict[str, dict[str, Any]] = {"self": get_link(self_href)}
+    if page.has_next and page.items:
+        all_links["next"] = get_link(next_href(page.items[-1]))
+    if page.has_previous and page.items:
+        all_links["prev"] = get_link(prev_href(page.items[0]))
+    all_links.update(links or {})
+    return {
+        "_embedded": {name: items},
+        "meta": {
+            "perPage": size,
+            "hasNext": page.has_next,
+            "hasPrevious": page.has_previous,
+            **(meta or {}),
+        },
+        "_links": all_links,
+    }

tyrtulia/adapters/http/problems.py

@@ -0,0 +1,71 @@
+"""RFC 9457 problem documents for the error catalog."""
+
+from typing import Any
+
+import msgspec
+from flask import Response, request
+
+PROBLEM_TYPE = "application/problem+json"
+
+CATALOG: dict[str, tuple[int, str]] = {
+    "validation-failed": (400, "The request does not match the rules"),
+    "invalid-query": (400, "Invalid search syntax"),
+    "unauthenticated": (401, "Authentication is required"),
+    "invalid-signature": (401, "The signature is not valid"),
+    "forbidden": (403, "You do not have permission for this action"),
+    "readonly": (403, "Your account is read-only"),
+    "banned": (403, "Your account is banned"),
+    "fields-not-allowed": (403, "A field is not allowed for you"),
+    "cannot-moderate-staff": (403, "Moderators and admins cannot be moderated"),
+    "not-found": (404, "Not found"),
+    "not-acceptable": (406, "Unsupported media type requested"),
+    "thread-closed": (409, "The thread is closed"),
+    "thread-has-replies": (409, "The thread has replies from other people"),
+    "key-already-registered": (409, "The SSH key is already registered"),
+    "username-conflict": (409, "An SSH key account already uses this name"),
+    "username-taken": (409, "The username is not available"),
+    "unix-identity-mismatch": (409, "The Unix identity does not match the account"),
+    "edit-conflict": (412, "The post was modified by someone else"),
+    "unsupported-media-type": (415, "Unsupported media type"),
+    "too-many-mentions": (422, "Too many mentions"),
+    "invalid-public-key": (422, "The public key is not valid"),
+    "invalid-target": (422, "The report target is not valid"),
+    "precondition-required": (428, "If-Match is required"),
+    "rate-limited": (429, "Too many requests"),
+    "too-many-connections": (429, "Too many open event streams"),
+}
+
+
+def problem(
+    code: str,
+    detail: str,
+    *,
+    links: dict[str, dict[str, Any]] | None = None,
+    headers: dict[str, str] | None = None,
+) -> Response:
+    status, title = CATALOG[code]
+    body: dict[str, Any] = {
+        "type": f"{request.host_url}errors/{code}",
+        "title": title,
+        "status": status,
+        "detail": detail,
+        "instance": request.path,
+    }
+    if links:
+        body["_links"] = links
+    return _response(body, status, headers)
+
+
+def generic_problem(status: int, title: str, detail: str | None = None) -> Response:
+    """Errors outside the catalog (405, 500): ``about:blank`` as RFC 9457 allows."""
+    body: dict[str, Any] = {"type": "about:blank", "title": title, "status": status}
+    if detail:
+        body["detail"] = detail
+    return _response(body, status, None)
+
+
+def _response(body: dict[str, Any], status: int, headers: dict[str, str] | None) -> Response:
+    response = Response(msgspec.json.encode(body), status=status, mimetype=PROBLEM_TYPE)
+    for name, value in (headers or {}).items():
+        response.headers[name] = value
+    return response

tyrtulia/adapters/http/ratelimit.py

@@ -0,0 +1,155 @@
+"""In-memory sliding window rate limiting, per user and per IP.
+
+``GET`` and ``HEAD`` are reads, everything else is a write; requesting an
+SSH challenge and logging in also count in the login limit, per IP.
+Through the socket only the per-user limits apply. Every response carries
+``RateLimit`` and ``RateLimit-Policy`` (IETF httpapi rate limit headers);
+a ``429`` also carries ``Retry-After``.
+"""
+
+import ipaddress
+import math
+from collections import defaultdict, deque
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+
+from flask import Response, g, request
+
+from tyrtulia.adapters.http.auth import READ_METHODS, via_socket
+from tyrtulia.adapters.http.context import actor, config
+from tyrtulia.domain.errors import DomainError
+
+LOGIN_ENDPOINTS = frozenset({"auth.request_challenge", "auth.login"})
+
+
+@dataclass(frozen=True, slots=True)
+class Policy:
+    name: str
+    quota: int
+    window: int
+
+
+@dataclass(frozen=True, slots=True)
+class Usage:
+    policy: Policy
+    remaining: int
+    reset: int
+
+
+class SlidingWindowLimiter:
+    def __init__(self, now: Callable[[], float]) -> None:
+        self._now = now
+        self._hits: dict[tuple[str, str], deque[float]] = defaultdict(deque)
+
+    def hit(self, policy: Policy, keys: Sequence[str]) -> list[Usage]:
+        """Count one request against every key; raise if any is over the quota."""
+        moment = self._now()
+        usages = []
+        for key in keys:
+            hits = self._hits[(policy.name, key)]
+            while hits and hits[0] <= moment - policy.window:
+                hits.popleft()
+            reset = math.ceil(hits[0] + policy.window - moment) if hits else policy.window
+            if len(hits) >= policy.quota:
+                raise RateLimited(Usage(policy, 0, max(reset, 1)))
+            usages.append((hits, reset))
+        result = []
+        for hits, reset in usages:
+            hits.append(moment)
+            remaining = policy.quota - len(hits)
+            result.append(Usage(policy, remaining, reset if len(hits) > 1 else policy.window))
+        return result
+
+
+class RateLimited(Exception):
+    def __init__(self, usage: Usage) -> None:
+        super().__init__(usage.policy.name)
+        self.usage = usage
+
+
+def _trusted(address: str, proxies: Sequence[str]) -> bool:
+    try:
+        ip = ipaddress.ip_address(address)
+    except ValueError:
+        return False
+    for proxy in proxies:
+        try:
+            if ip in ipaddress.ip_network(proxy, strict=False):
+                return True
+        except ValueError:
+            continue
+    return False
+
+
+def client_ip(remote_addr: str, forwarded_for: str | None, proxies: Sequence[str]) -> str:
+    """The real client IP: ``X-Forwarded-For`` is only believed from trusted proxies."""
+    if not forwarded_for or not _trusted(remote_addr, proxies):
+        return remote_addr
+    hops = [hop.strip() for hop in forwarded_for.split(",") if hop.strip()]
+    for hop in reversed(hops):
+        if not _trusted(hop, proxies):
+            return hop
+    return hops[0] if hops else remote_addr
+
+
+def _header_value(usages: Sequence[Usage]) -> tuple[str, str]:
+    policies: dict[str, Usage] = {}
+    for usage in usages:
+        current = policies.get(usage.policy.name)
+        if current is None or usage.remaining < current.remaining:
+            policies[usage.policy.name] = usage
+    policy = ", ".join(
+        f'"{u.policy.name}";q={u.policy.quota};w={u.policy.window}' for u in policies.values()
+    )
+    state = ", ".join(f'"{u.policy.name}";r={u.remaining};t={u.reset}' for u in policies.values())
+    return policy, state
+
+
+class RateLimiter:
+    def __init__(self, limiter: SlidingWindowLimiter) -> None:
+        self.limiter = limiter
+
+    def check(self) -> None:
+        limits = config().rate_limit
+        current = actor()
+        keys = []
+        if current is not None:
+            keys.append(f"user:{current.user.id}")
+        if not via_socket():
+            remote = request.remote_addr or "unknown"
+            ip = client_ip(
+                remote, request.headers.get("X-Forwarded-For"), config().listen.trusted_proxies
+            )
+            keys.append(f"ip:{ip}")
+        if request.method in READ_METHODS:
+            policies = [(Policy("read", limits.read_per_minute, 60), keys)]
+        else:
+            policies = [(Policy("write", limits.write_per_minute, 60), keys)]
+        if request.endpoint in LOGIN_ENDPOINTS and not via_socket():
+            ip_keys = [key for key in keys if key.startswith("ip:")]
+            policies.append((Policy("login", limits.login_per_15_minutes, 900), ip_keys))
+        usages: list[Usage] = []
+        try:
+            for policy, policy_keys in policies:
+                usages += self.limiter.hit(policy, policy_keys)
+        except RateLimited as error:
+            policy_header, state = _header_value([error.usage])
+            raise DomainError(
+                "rate-limited",
+                f"Too many requests; retry in {error.usage.reset} seconds",
+                headers={
+                    "Retry-After": str(error.usage.reset),
+                    "RateLimit-Policy": policy_header,
+                    "RateLimit": state,
+                },
+            ) from error
+        g.rate_limit_usages = usages
+
+    @staticmethod
+    def add_headers(response: Response) -> Response:
+        usages = g.get("rate_limit_usages")
+        if usages and "RateLimit" not in response.headers:
+            policy, state = _header_value(usages)
+            response.headers["RateLimit-Policy"] = policy
+            response.headers["RateLimit"] = state
+        return response

tyrtulia/adapters/http/representers.py

@@ -0,0 +1,355 @@
+"""One representer per resource. Permissions become links; nothing else."""
+
+from datetime import UTC, datetime
+from typing import Any
+
+from tyrtulia.domain import permissions
+from tyrtulia.domain.entities import (
+    Actor,
+    ModlogEntry,
+    Notification,
+    Post,
+    Revision,
+    SshKey,
+    SubscriptionLevel,
+    Thread,
+    User,
+    UserRef,
+    UserStats,
+)
+from tyrtulia.domain.roles import Role
+
+type Links = dict[str, dict[str, Any]]
+type Document = dict[str, Any]
+
+DIFF_TYPE = "text/x-diff"
+ATOM_TYPE = "application/atom+xml"
+EVENT_STREAM_TYPE = "text/event-stream"
+
+
+def iso(moment: datetime) -> str:
+    return moment.astimezone(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def link(href: str, method: str = "GET", **extra: Any) -> dict[str, Any]:
+    return {"href": href, "method": method, **extra}
+
+
+def schema_link(href: str, method: str, schema: str) -> dict[str, Any]:
+    return link(href, method, schema=f"/schemas/{schema}")
+
+
+def thread_path(thread_id: str) -> str:
+    return f"/threads/{thread_id}"
+
+
+def post_path(post_id: str) -> str:
+    return f"/posts/{post_id}"
+
+
+def user_path(username: str) -> str:
+    return f"/users/{username}"
+
+
+def notification_path(notification_id: str) -> str:
+    return f"/notifications/{notification_id}"
+
+
+def ssh_key_path(key_id: str) -> str:
+    return f"/users/me/ssh-keys/{key_id}"
+
+
+def single_page_meta(count: int) -> dict[str, Any]:
+    """``meta`` of a collection that always fits in one page."""
+    return {"perPage": max(count, 1), "hasNext": False, "hasPrevious": False}
+
+
+def report_link() -> dict[str, Any]:
+    return schema_link("/reports", "POST", "report")
+
+
+def root(name: str, actor: Actor | None) -> Document:
+    links: Links = {"self": link("/"), "latest": link("/threads")}
+    if actor is not None:
+        links["watching"] = link("/threads?filter=watching")
+    if permissions.can_write(actor):
+        links["createThread"] = schema_link("/threads", "POST", "thread")
+    links["search"] = link("/search{?q,author,in}", templated=True)
+    links["user"] = link("/users/{username}", templated=True)
+    if actor is not None:
+        links["me"] = link("/users/me")
+        links["notifications"] = link("/notifications")
+        links["events"] = link("/events", type=EVENT_STREAM_TYPE)
+    links["modlog"] = link("/modlog")
+    links["alternate"] = link("/threads.atom", type=ATOM_TYPE)
+    if actor is None:
+        links["sshChallenge"] = schema_link("/ssh-challenges", "POST", "ssh-challenge")
+        links["login"] = schema_link("/sessions", "POST", "session")
+    return {"name": name, "_links": links}
+
+
+def user_summary(user: UserRef) -> Document:
+    return {
+        "username": user.username,
+        "deactivated": user.deactivated,
+        "_links": {"self": link(user_path(user.username))},
+    }
+
+
+def _user_fields(
+    user: User, role: Role, stats: UserStats, *, email: bool, unread: int | None = None
+) -> Document:
+    document: Document = {
+        "username": user.username,
+        "about": user.about,
+        "aboutHtml": user.about_html,
+    }
+    if email and user.email is not None:
+        document["email"] = user.email
+    document.update(
+        role=role.value,
+        deactivated=user.deactivated,
+        postsCount=stats.posts_count,
+        threadsCount=stats.threads_count,
+    )
+    if unread is not None:
+        document["unreadNotificationsCount"] = unread
+    document["createdAt"] = iso(user.created_at)
+    return document
+
+
+def user(target: User, role: Role, stats: UserStats, actor: Actor | None) -> Document:
+    private = permissions.can_see_private_profile(actor, target)
+    document = _user_fields(target, role, stats, email=private)
+    path = user_path(target.username)
+    links: Links = {
+        "self": link(path),
+        "threads": link(f"/threads?author={target.username}"),
+    }
+    if permissions.can_report(actor, target.id):
+        links["report"] = report_link()
+    if permissions.can_moderate_user(actor, role):
+        if role is Role.BANNED:
+            links["unban"] = link(f"{path}/ban", "DELETE")
+        else:
+            links["ban"] = schema_link(f"{path}/ban", "PUT", "moderation")
+        # A banned user keeps the role it returns to, which can be read-only.
+        readonly = role is Role.READONLY or target.role_before_ban is Role.READONLY
+        if readonly:
+            links["unreadonly"] = link(f"{path}/readonly", "DELETE")
+        else:
+            links["readonly"] = schema_link(f"{path}/readonly", "PUT", "moderation")
+    document["_links"] = links
+    return document
+
+
+def current_user(actor: Actor, stats: UserStats, unread: int | None) -> Document:
+    target = actor.user
+    document = _user_fields(target, actor.role, stats, email=True, unread=unread)
+    links: Links = {
+        "self": link("/users/me"),
+        "threads": link(f"/threads?author={target.username}"),
+    }
+    if permissions.can_write(actor):
+        links["edit"] = schema_link("/users/me", "PATCH", "profile")
+    links["sshKeys"] = link("/users/me/ssh-keys")
+    links["notifications"] = link("/notifications")
+    links["events"] = link("/events", type=EVENT_STREAM_TYPE)
+    if actor.session_id is not None:
+        links["logout"] = link("/sessions/current", "DELETE")
+    document["_links"] = links
+    return document
+
+
+def ssh_key(key: SshKey, actor: Actor) -> Document:
+    document: Document = {
+        "id": key.id,
+        "title": key.title,
+        "fingerprint": key.fingerprint,
+        "createdAt": iso(key.created_at),
+    }
+    if key.last_used_at is not None:
+        document["lastUsedAt"] = iso(key.last_used_at)
+    links: Links = {}
+    if permissions.can_write(actor):
+        links["delete"] = link(ssh_key_path(key.id), "DELETE")
+    document["_links"] = links
+    return document
+
+
+def thread(
+    item: Thread,
+    actor: Actor | None,
+    subscription: SubscriptionLevel | None,
+    first_post: Document | None = None,
+) -> Document:
+    path = thread_path(item.id)
+    document: Document = {
+        "id": item.id,
+        "title": item.title,
+        "pinned": item.pinned,
+        "closed": item.closed,
+        "postsCount": item.posts_count,
+        "highestPostNumber": item.highest_post_number,
+    }
+    if subscription is not None:
+        document["subscription"] = subscription.value
+    document["createdAt"] = iso(item.created_at)
+    document["lastPostedAt"] = iso(item.last_posted_at)
+    if item.deleted_at is not None and permissions.is_moderator(actor):
+        document["deletedAt"] = iso(item.deleted_at)
+    embedded: Document = {
+        "author": user_summary(item.author),
+        "lastPoster": user_summary(item.last_poster),
+    }
+    if first_post is not None:
+        embedded["firstPost"] = first_post
+    document["_embedded"] = embedded
+    links: Links = {
+        "self": link(path),
+        "posts": link(f"{path}/posts"),
+    }
+    if permissions.can_reply(actor, item):
+        links["reply"] = schema_link(f"{path}/posts", "POST", "post")
+    if permissions.can_edit_thread(actor, item):
+        links["edit"] = schema_link(path, "PATCH", "thread-update")
+    if permissions.is_moderator(actor):
+        links["pin"] = schema_link(path, "PATCH", "thread-update")
+        links["close"] = schema_link(path, "PATCH", "thread-update")
+    if not item.deleted and permissions.can_delete_thread(actor, item, item.others_replied):
+        links["delete"] = link(path, "DELETE")
+    if permissions.can_write(actor):
+        links["subscribe"] = schema_link(f"{path}/subscription", "PUT", "subscription")
+    if permissions.can_report(actor, item.author.id):
+        links["report"] = report_link()
+    links["alternate"] = link(f"{path}.atom", type=ATOM_TYPE)
+    document["_links"] = links
+    return document
+
+
+def post(item: Post, actor: Actor | None, *, tree: bool = False) -> Document:
+    path = post_path(item.id)
+    up = link(thread_path(item.thread_id))
+    if item.deleted_at is not None:
+        tombstone: Document = {"author": user_summary(item.author)}
+        if tree:
+            tombstone["replies"] = _replies(item, actor)
+        return {
+            "id": item.id,
+            "postNumber": item.post_number,
+            "createdAt": iso(item.created_at),
+            "deletedAt": iso(item.deleted_at),
+            "_embedded": tombstone,
+            "_links": {"self": link(path), "up": up},
+        }
+    show_content = not item.hidden or permissions.can_see_hidden_content(actor, item)
+    document: Document = {"id": item.id, "postNumber": item.post_number}
+    if item.reply_to_post_number is not None:
+        document["replyToPostNumber"] = item.reply_to_post_number
+    if show_content:
+        document["body"] = item.body
+        document["bodyHtml"] = item.body_html
+    document["version"] = item.version
+    document["repliesCount"] = item.replies_count
+    document["hidden"] = item.hidden
+    if item.hidden and show_content and item.hidden_reason is not None:
+        document["hiddenReason"] = item.hidden_reason
+    document["createdAt"] = iso(item.created_at)
+    if item.edited_at is not None:
+        document["editedAt"] = iso(item.edited_at)
+    embedded: Document = {"author": user_summary(item.author)}
+    if tree:
+        embedded["replies"] = _replies(item, actor)
+    document["_embedded"] = embedded
+    links: Links = {"self": link(path), "up": up}
+    if item.reply_to_post_id is not None:
+        links["replyTo"] = link(post_path(item.reply_to_post_id))
+    links["replies"] = link(f"{path}/replies")
+    if permissions.can_see_history(actor, item):
+        links["version-history"] = link(f"{path}/revisions")
+    if permissions.can_edit_post(actor, item):
+        links["edit"] = schema_link(path, "PATCH", "post-update")
+        links["delete"] = link(path, "DELETE")
+    if permissions.is_moderator(actor):
+        rel = "unhide" if item.hidden else "hide"
+        links[rel] = schema_link(path, "PATCH", "post-update")
+    if permissions.can_report(actor, item.author.id):
+        links["report"] = report_link()
+    document["_links"] = links
+    return document
+
+
+def _replies(item: Post, actor: Actor | None) -> list[Document]:
+    return [post(reply, actor, tree=True) for reply in item.replies]
+
+
+def revision(
+    item: Revision, current: Post, actor: Actor | None, *, with_body: bool = True
+) -> Document:
+    path = f"{post_path(current.id)}/revisions/{item.version}"
+    document: Document = {"version": item.version}
+    if item.title is not None:
+        document["title"] = item.title
+    if with_body:
+        document["body"] = item.body
+    if item.reason is not None:
+        document["reason"] = item.reason
+    document["createdAt"] = iso(item.created_at)
+    document["_embedded"] = {"editor": user_summary(item.editor)}
+    links: Links = {
+        "self": link(path),
+        "latest-version": link(post_path(current.id)),
+        "diff": link(f"{path}?format=diff", type=DIFF_TYPE),
+    }
+    if item.version != current.version and permissions.can_edit_post(actor, current):
+        links["revert"] = link(f"{path}/revert", "POST")
+    document["_links"] = links
+    return document
+
+
+def notification(item: Notification, actor: Actor) -> Document:
+    readonly = actor.role is Role.READONLY
+    document: Document = {"id": item.id, "kind": item.kind.value}
+    if not readonly:
+        document["read"] = item.read
+    document["excerpt"] = item.excerpt
+    document["createdAt"] = iso(item.created_at)
+    embedded: Document = {"actor": user_summary(item.actor)}
+    if item.thread is not None:
+        embedded["thread"] = {
+            "id": item.thread.id,
+            "title": item.thread.title,
+            "_links": {"self": link(thread_path(item.thread.id))},
+        }
+    document["_embedded"] = embedded
+    path = notification_path(item.id)
+    links: Links = {"self": link(path), "target": link(notification_target(item))}
+    if not readonly and permissions.can_write(actor):
+        links["markRead"] = schema_link(path, "PATCH", "notification-update")
+    document["_links"] = links
+    return document
+
+
+def notification_target(item: Notification) -> str:
+    if item.post_id is not None:
+        return post_path(item.post_id)
+    if item.thread_id is not None:
+        return thread_path(item.thread_id)
+    assert item.target_user is not None
+    return user_path(item.target_user.username)
+
+
+def modlog_entry(entry: ModlogEntry) -> Document:
+    document: Document = {"id": entry.id, "action": entry.action}
+    if entry.reason is not None:
+        document["reason"] = entry.reason
+    document["createdAt"] = iso(entry.created_at)
+    document["_embedded"] = {"moderator": user_summary(entry.moderator)}
+    if entry.target_kind == "post":
+        target = post_path(entry.target_id)
+    elif entry.target_kind == "thread":
+        target = thread_path(entry.target_id)
+    else:
+        target = user_path(entry.target_username or entry.target_id)
+    document["_links"] = {"target": link(target)}
+    return document