tyrtulia 1.0.0__py3-none-any.whl

tyrtulia/__init__.py

@@ -0,0 +1 @@
+"""Tyrtulia: a headless forum for small multi-user servers."""

tyrtulia/__main__.py

@@ -0,0 +1,5 @@
+"""``python -m tyrtulia``: the same as the ``tyrtulia`` console script."""
+
+from tyrtulia.entrypoint import main
+
+main()

tyrtulia/adapters/__init__.py

@@ -0,0 +1 @@
+"""Adapters: HTTP, storage and CLI."""

tyrtulia/adapters/background.py

@@ -0,0 +1,43 @@
+"""Work that runs inside the worker: periodic tasks (MiniHuey)."""
+
+import logging
+
+from flask import Flask
+from huey import crontab
+from huey.contrib.mini import MiniHuey
+
+from tyrtulia.adapters.http.context import SERVICES_KEY
+from tyrtulia.use_cases import maintenance
+from tyrtulia.use_cases.services import Services
+
+logger = logging.getLogger(__name__)
+
+START_KEY = "tyrtulia.start"
+
+
+def attach_background(app: Flask) -> None:
+    """Register the function that ``post_worker_init`` calls to start the background work."""
+    svc: Services = app.extensions[SERVICES_KEY]
+
+    def start() -> None:
+        huey = MiniHuey("tyrtulia")
+
+        @huey.periodic_task(crontab(minute="*/10"))
+        def purge_events() -> None:
+            removed = maintenance.purge_events(svc)
+            logger.info("Purged %d events", removed)
+
+        @huey.periodic_task(crontab(minute="5"))
+        def expire_sessions() -> None:
+            removed = maintenance.expire_sessions(svc)
+            logger.info("Expired %d sessions", removed)
+
+        @huey.periodic_task(crontab(minute="*/15"))
+        def deactivate_missing_unix_users() -> None:
+            for username in maintenance.deactivate_missing_unix_users(svc):
+                logger.info("Deactivated %s: the Unix user no longer exists", username)
+
+        huey.start()
+        app.extensions["tyrtulia.huey"] = huey
+
+    app.extensions[START_KEY] = start

tyrtulia/adapters/bbj_reader.py

@@ -0,0 +1,30 @@
+"""Read a BBJ SQLite database (tables ``users``, ``threads`` and ``messages``)."""
+
+import sqlite3
+from pathlib import Path
+
+from tyrtulia.domain.bbj import BbjDatabase, BbjMessage, BbjThread, BbjUser
+
+
+def read_bbj(path: Path) -> BbjDatabase:
+    connection = sqlite3.connect(f"file:{path}?mode=ro", uri=True)
+    try:
+        users = [
+            BbjUser(row[0], row[1], row[2] or "", float(row[3] or 0))
+            for row in connection.execute("SELECT user_id, user_name, bio, created FROM users")
+        ]
+        threads = [
+            BbjThread(row[0], row[1], row[2], float(row[3] or 0), bool(row[4]), row[5] or row[1])
+            for row in connection.execute(
+                "SELECT thread_id, author, title, created, pinned, last_author FROM threads"
+            )
+        ]
+        messages = [
+            BbjMessage(row[0], int(row[1]), row[2], float(row[3] or 0), row[4] or "", bool(row[5]))
+            for row in connection.execute(
+                "SELECT thread_id, post_id, author, created, body, send_raw FROM messages"
+            )
+        ]
+    finally:
+        connection.close()
+    return BbjDatabase(users, threads, messages)

tyrtulia/adapters/challenges.py

@@ -0,0 +1,21 @@
+"""SSH challenges live in memory: they last two minutes and there is one process."""
+
+from datetime import datetime
+
+from tyrtulia.use_cases.ports import PendingChallenge
+
+
+class MemoryChallengeStore:
+    def __init__(self) -> None:
+        self._pending: dict[str, PendingChallenge] = {}
+
+    def add(self, challenge: str, pending: PendingChallenge) -> None:
+        self._pending[challenge] = pending
+
+    def take(self, challenge: str) -> PendingChallenge | None:
+        return self._pending.pop(challenge, None)
+
+    def purge(self, moment: datetime) -> None:
+        expired = [key for key, value in self._pending.items() if value.expires_at <= moment]
+        for key in expired:
+            del self._pending[key]

tyrtulia/adapters/cli/__init__.py

@@ -0,0 +1 @@
+"""Administration CLI (Typer)."""

tyrtulia/adapters/cli/main.py

@@ -0,0 +1,195 @@
+"""``tyrtulia``: the administration CLI."""
+
+import logging
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from tyrtulia.config import Config, ConfigError, load_config, resolve_path
+from tyrtulia.domain.errors import DomainError
+from tyrtulia.use_cases.services import Services
+
+app = typer.Typer(help="Tyrtulia administration CLI.", no_args_is_help=True)
+account_app = typer.Typer(help="SSH key accounts.", no_args_is_help=True)
+identity_app = typer.Typer(help="Unix identity problems.", no_args_is_help=True)
+app.add_typer(account_app, name="account")
+app.add_typer(identity_app, name="identity")
+
+ConfigOption = Annotated[
+    str | None,
+    typer.Option(
+        "--config",
+        help="Configuration file (default: TYRTULIA_CONFIG or /etc/tyrtulia/config.toml).",
+    ),
+]
+KeyOption = Annotated[
+    Path, typer.Option("--key", help="Public key file (an authorized_keys line).", exists=True)
+]
+
+
+class State:
+    config_path: Path = Path("/etc/tyrtulia/config.toml")
+
+
+state = State()
+
+
+@app.callback()
+def main(config: ConfigOption = None) -> None:
+    state.config_path = resolve_path(config)
+
+
+def fail(message: str) -> typer.Exit:
+    typer.echo(message, err=True)
+    return typer.Exit(1)
+
+
+def read_config() -> Config:
+    try:
+        return load_config(state.config_path)
+    except ConfigError as error:
+        raise fail(str(error)) from error
+
+
+@contextmanager
+def open_services() -> Iterator[Services]:
+    """Services over the configured database, which must be migrated."""
+    from tyrtulia.adapters.storage.database import open_database
+    from tyrtulia.adapters.storage.migrations import pending_migrations
+    from tyrtulia.bootstrap import build_services
+
+    config = read_config()
+    database = open_database(config.storage.database)
+    with database.connection_context():
+        if pending_migrations(database):
+            raise fail("The database has pending migrations: run tyrtulia migrate")
+        try:
+            yield build_services(config, database)
+        except DomainError as error:
+            raise fail(error.detail) from error
+
+
+def read_key(path: Path) -> str:
+    lines = [line for line in path.read_text().splitlines() if line.strip()]
+    if not lines:
+        raise fail(f"{path} is empty")
+    return lines[0]
+
+
+@app.command()
+def serve(
+    pidfile: Annotated[
+        Path | None,
+        typer.Option("--pidfile", help="Write the PID of the server here (for rc.d scripts)."),
+    ] = None,
+) -> None:
+    """Start the server."""
+    from tyrtulia.adapters.http.server import TyrtuliaServer
+    from tyrtulia.adapters.peercred import UnsupportedPlatform
+
+    read_config()
+    logging.basicConfig(
+        level=logging.INFO, format="%(asctime)s %(levelname)s %(name)s: %(message)s"
+    )
+    try:
+        server = TyrtuliaServer(state.config_path, pidfile)
+    except UnsupportedPlatform as error:
+        raise fail(f"{error}. Disable [listen].socket or use Linux or a BSD system") from error
+    server.run()
+
+
+@app.command()
+def migrate() -> None:
+    """Apply database migrations."""
+    from tyrtulia.adapters.storage.database import open_database
+    from tyrtulia.adapters.storage.migrations import migrate as apply_migrations
+
+    database = open_database(read_config().storage.database)
+    with database.connection_context():
+        applied = apply_migrations(database)
+    if applied:
+        for migration in applied:
+            typer.echo(f"Applied {migration.name}")
+    else:
+        typer.echo("The database is up to date")
+
+
+@account_app.command("create")
+def account_create(name: str, key: KeyOption) -> None:
+    """Create an SSH key account. Rejects Unix user names and reserved names."""
+    from tyrtulia.use_cases import admin
+
+    with open_services() as svc:
+        admin.create_account(svc, name, read_key(key))
+    typer.echo(f"Created the account {name}")
+
+
+@account_app.command("rename")
+def account_rename(old: str, new: str) -> None:
+    """Rename an SSH key account. Same rules as create."""
+    from tyrtulia.use_cases import admin
+
+    with open_services() as svc:
+        admin.rename_account(svc, old, new)
+    typer.echo(f"Renamed {old} to {new}")
+
+
+@account_app.command("add-key")
+def account_add_key(name: str, key: KeyOption) -> None:
+    """Add an SSH key to an account."""
+    from tyrtulia.use_cases import admin
+
+    with open_services() as svc:
+        admin.add_key(svc, name, read_key(key))
+    typer.echo(f"Added the key to {name}")
+
+
+@identity_app.command("resolve")
+def identity_resolve(
+    name: str,
+    rename_to: Annotated[
+        str | None,
+        typer.Option("--rename-to", help="New name for an SSH key account in conflict."),
+    ] = None,
+) -> None:
+    """Resolve a unix-identity-mismatch or a username-conflict."""
+    from tyrtulia.use_cases import admin
+
+    with open_services() as svc:
+        typer.echo(admin.resolve_identity(svc, name, rename_to))
+
+
+@app.command("import-bbj")
+def import_bbj(
+    database: Annotated[Path, typer.Argument(help="BBJ SQLite database.", exists=True)],
+    trust_unix_names: Annotated[
+        bool,
+        typer.Option(
+            "--trust-unix-names", help="Send the posts of BBJ users to the matching Unix accounts."
+        ),
+    ] = False,
+) -> None:
+    """Import a BBJ database."""
+    from tyrtulia.adapters.bbj_reader import read_bbj
+    from tyrtulia.use_cases.bbj_import import ImportConflicts
+    from tyrtulia.use_cases.bbj_import import import_bbj as run_import
+
+    data = read_bbj(database)
+    with open_services() as svc:
+        try:
+            summary = run_import(svc, data, trust_unix_names=trust_unix_names)
+        except ImportConflicts as error:
+            typer.echo("The import stopped; nothing was imported. Conflicts:", err=True)
+            for conflict in error.conflicts:
+                typer.echo(f"  {conflict.username}: {conflict.reason}", err=True)
+            raise typer.Exit(1) from error
+    typer.echo(
+        f"Imported {summary.users} users, {summary.threads} threads and {summary.posts} posts"
+    )
+
+
+def run() -> None:
+    app()

tyrtulia/adapters/http/__init__.py

@@ -0,0 +1 @@
+"""HTTP adapter: Flask app, authentication, negotiation and representers."""

tyrtulia/adapters/http/app.py

@@ -0,0 +1,111 @@
+"""Flask application factory."""
+
+import logging
+
+import peewee
+from flask import Flask, Response, g
+from werkzeug.exceptions import HTTPException
+
+from tyrtulia.adapters.http import auth, negotiation
+from tyrtulia.adapters.http.context import CONFIG_KEY, SERVICES_KEY
+from tyrtulia.adapters.http.problems import CATALOG, generic_problem, problem
+from tyrtulia.adapters.http.ratelimit import RateLimiter, SlidingWindowLimiter
+from tyrtulia.adapters.http.routes import register_routes
+from tyrtulia.adapters.http.routes.notifications import BROKER_KEY
+from tyrtulia.adapters.http.sse import Broker
+from tyrtulia.config import Config
+from tyrtulia.domain.errors import DomainError
+from tyrtulia.use_cases.common import EditConflict
+from tyrtulia.use_cases.services import Services
+
+logger = logging.getLogger(__name__)
+
+RATE_LIMITER_KEY = "tyrtulia.rate_limiter"
+
+
+def create_app(
+    config: Config,
+    svc: Services,
+    database: peewee.SqliteDatabase,
+    broker: Broker | None = None,
+) -> Flask:
+    app = Flask("tyrtulia")
+    app.json.sort_keys = False  # type: ignore[attr-defined]
+    broker = broker or Broker(config.rate_limit.max_sse_per_user)
+    svc.publisher = broker
+    app.extensions[SERVICES_KEY] = svc
+    app.extensions[CONFIG_KEY] = config
+    app.extensions[BROKER_KEY] = broker
+
+    @app.before_request
+    def open_connection() -> None:
+        database.connect(reuse_if_open=True)
+
+    @app.teardown_request
+    def close_connection(_error: BaseException | None) -> None:
+        if not database.is_closed():
+            database.close()
+
+    limiter = RateLimiter(SlidingWindowLimiter(lambda: svc.clock.now().timestamp()))
+    app.extensions[RATE_LIMITER_KEY] = limiter
+
+    @app.before_request
+    def prepare() -> None:
+        """Identify, count against the rate limits, then negotiate.
+
+        Requests that fail authentication still count (by IP), so failed
+        attempts are limited and carry the rate limit headers too.
+        """
+        try:
+            auth.authenticate()
+        except DomainError:
+            g.actor = None
+            limiter.check()
+            raise
+        limiter.check()
+        negotiation.check_accept()
+
+    app.after_request(limiter.add_headers)
+
+    @app.errorhandler(DomainError)
+    def domain_error(error: DomainError) -> Response:
+        links = dict(error.links)
+        if isinstance(error, EditConflict):
+            links["latest-version"] = {"href": f"/posts/{error.post_id}", "method": "GET"}
+            if error.theirs is not None:
+                links["diff"] = {
+                    "href": f"/posts/{error.post_id}/revisions/{error.current}"
+                    f"?format=diff&from={error.theirs}",
+                    "method": "GET",
+                    "type": "text/x-diff",
+                }
+        if error.code not in CATALOG:
+            logger.error("Unknown error code %s", error.code)
+            return generic_problem(500, "Internal server error")
+        return problem(error.code, error.detail, links=links, headers=error.headers)
+
+    @app.errorhandler(HTTPException)
+    def http_error(error: HTTPException) -> Response:
+        status = error.code or 500
+        if status == 404:
+            return problem("not-found", "The resource does not exist")
+        if status == 415:
+            return problem("unsupported-media-type", "Unsupported media type")
+        response = generic_problem(status, error.name, error.description)
+        if status == 405 and hasattr(error, "valid_methods") and error.valid_methods:
+            response.headers["Allow"] = ", ".join(error.valid_methods)
+        return response
+
+    @app.errorhandler(Exception)
+    def unexpected_error(error: Exception) -> Response:
+        logger.exception("Unexpected error", exc_info=error)
+        return generic_problem(500, "Internal server error")
+
+    @app.after_request
+    def empty_responses(response: Response) -> Response:
+        if response.status_code in (202, 204):
+            response.headers.pop("Content-Type", None)
+        return response
+
+    register_routes(app)
+    return app

tyrtulia/adapters/http/atom.py

@@ -0,0 +1,64 @@
+"""Atom documents (RFC 4287)."""
+
+from datetime import datetime
+from xml.etree import ElementTree
+
+from tyrtulia.adapters.http.representers import iso
+
+ATOM_NAMESPACE = "http://www.w3.org/2005/Atom"
+
+ElementTree.register_namespace("", ATOM_NAMESPACE)
+
+
+def _tag(name: str) -> str:
+    return f"{{{ATOM_NAMESPACE}}}{name}"
+
+
+def _text(parent: ElementTree.Element, name: str, text: str, **attributes: str) -> None:
+    element = ElementTree.SubElement(parent, _tag(name), attributes)
+    element.text = text
+
+
+def _link(parent: ElementTree.Element, rel: str, href: str, media_type: str) -> None:
+    ElementTree.SubElement(parent, _tag("link"), {"rel": rel, "href": href, "type": media_type})
+
+
+class Feed:
+    def __init__(self, feed_id: str, title: str, self_href: str, alternate_href: str) -> None:
+        self.root = ElementTree.Element(_tag("feed"))
+        _text(self.root, "id", feed_id)
+        _text(self.root, "title", title)
+        self._updated = ElementTree.SubElement(self.root, _tag("updated"))
+        _link(self.root, "self", self_href, "application/atom+xml")
+        _link(self.root, "alternate", alternate_href, "application/vnd.tyrtulia.v1+json")
+        self.updated: datetime | None = None
+
+    def add_entry(
+        self,
+        entry_id: str,
+        title: str,
+        author: str,
+        href: str,
+        published: datetime,
+        updated: datetime,
+        html: str | None,
+    ) -> None:
+        entry = ElementTree.SubElement(self.root, _tag("entry"))
+        _text(entry, "id", f"urn:uuid:{entry_id}")
+        _text(entry, "title", title)
+        author_element = ElementTree.SubElement(entry, _tag("author"))
+        _text(author_element, "name", author)
+        _link(entry, "alternate", href, "application/vnd.tyrtulia.v1+json")
+        _text(entry, "published", iso(published))
+        _text(entry, "updated", iso(updated))
+        if html is not None:
+            _text(entry, "content", html, type="html")
+        if self.updated is None or updated > self.updated:
+            self.updated = updated
+
+    def render(self, fallback_updated: datetime) -> bytes:
+        self._updated.text = iso(self.updated or fallback_updated)
+        return (
+            b'<?xml version="1.0" encoding="utf-8"?>\n'
+            + ElementTree.tostring(self.root, encoding="unicode").encode()
+        )

tyrtulia/adapters/http/auth.py

@@ -0,0 +1,38 @@
+"""Who is asking: the socket peer (``SO_PEERCRED``) or a session token."""
+
+from flask import g, request
+
+from tyrtulia.adapters.http.context import services
+from tyrtulia.domain.errors import DomainError, unauthenticated
+from tyrtulia.domain.roles import Role
+from tyrtulia.use_cases.accounts import identify_unix
+from tyrtulia.use_cases.sessions import authenticate_token
+
+PEER_UID_KEY = "tyrtulia.peer_uid"
+READ_METHODS = frozenset({"GET", "HEAD"})
+LOGOUT_ENDPOINT = "auth.logout"
+
+
+def authenticate() -> None:
+    g.actor = None
+    uid = request.environ.get(PEER_UID_KEY)
+    if uid is not None:
+        g.actor = identify_unix(services(), int(uid))
+    elif "Authorization" in request.headers:
+        scheme, _, token = request.headers["Authorization"].partition(" ")
+        if scheme.lower() != "bearer" or not token.strip():
+            raise unauthenticated("Use Authorization: Bearer with a session token")
+        g.actor = authenticate_token(services(), token.strip())
+    actor = g.actor
+    if actor is None:
+        return
+    if (
+        actor.role is Role.READONLY
+        and request.method not in READ_METHODS
+        and request.endpoint != LOGOUT_ENDPOINT
+    ):
+        raise DomainError("readonly", "Read-only accounts can only read")
+
+
+def via_socket() -> bool:
+    return request.environ.get(PEER_UID_KEY) is not None

tyrtulia/adapters/http/bodies.py

@@ -0,0 +1,43 @@
+"""Decoding request bodies and query parameters."""
+
+import msgspec
+from flask import request
+
+from tyrtulia.adapters.http.negotiation import JSON_TYPES
+from tyrtulia.domain.errors import DomainError, validation_failed
+
+MERGE_PATCH_TYPE = "application/merge-patch+json"
+
+
+def read_body[T](struct: type[T]) -> T:
+    """Decode a JSON body (``POST``, ``PUT``) or a merge patch (``PATCH``)."""
+    media_type = request.mimetype
+    if request.method == "PATCH":
+        if media_type != MERGE_PATCH_TYPE:
+            raise DomainError("unsupported-media-type", f"PATCH requires {MERGE_PATCH_TYPE}")
+    elif media_type not in JSON_TYPES:
+        raise DomainError("unsupported-media-type", "The body must be application/json")
+    try:
+        return msgspec.json.decode(request.get_data(), type=struct)
+    except msgspec.ValidationError as error:
+        raise validation_failed(str(error)) from error
+    except msgspec.DecodeError as error:
+        raise DomainError("unsupported-media-type", "The body is not valid JSON") from error
+
+
+def query_int(name: str, *, minimum: int, maximum: int | None = None) -> int | None:
+    raw = request.args.get(name)
+    if raw is None:
+        return None
+    if not raw.isdigit():
+        raise validation_failed(f"{name} must be an integer")
+    value = int(raw)
+    if value < minimum or (maximum is not None and value > maximum):
+        limit = f"between {minimum} and {maximum}" if maximum is not None else f">= {minimum}"
+        raise validation_failed(f"{name} must be {limit}")
+    return value
+
+
+def given[T](value: T | msgspec.UnsetType) -> T | None:
+    """The value of an optional field, or ``None`` when it was not sent."""
+    return None if isinstance(value, msgspec.UnsetType) else value

tyrtulia/adapters/http/context.py

@@ -0,0 +1,45 @@
+"""Per-request access to the services and the acting user."""
+
+from typing import Any
+
+import msgspec
+from flask import Response, current_app, g
+
+from tyrtulia.adapters.http.negotiation import API_TYPE
+from tyrtulia.config import Config
+from tyrtulia.domain.entities import Actor
+from tyrtulia.use_cases.services import Services
+
+SERVICES_KEY = "tyrtulia.services"
+CONFIG_KEY = "tyrtulia.config"
+
+
+def services() -> Services:
+    svc: Services = current_app.extensions[SERVICES_KEY]
+    return svc
+
+
+def config() -> Config:
+    cfg: Config = current_app.extensions[CONFIG_KEY]
+    return cfg
+
+
+def actor() -> Actor | None:
+    current: Actor | None = g.get("actor")
+    return current
+
+
+def hal(
+    body: dict[str, Any],
+    status: int = 200,
+    *,
+    headers: dict[str, str] | None = None,
+) -> Response:
+    response = Response(msgspec.json.encode(body), status=status, mimetype=API_TYPE)
+    for name, value in (headers or {}).items():
+        response.headers[name] = value
+    return response
+
+
+def no_content() -> Response:
+    return Response(status=204)

tyrtulia/adapters/http/negotiation.py

@@ -0,0 +1,58 @@
+"""Content negotiation for the versioned media type."""
+
+from collections.abc import Callable
+from typing import Any
+
+from flask import current_app, request
+
+from tyrtulia.domain.errors import DomainError
+
+API_TYPE = "application/vnd.tyrtulia.v1+json"
+JSON_TYPES = frozenset({API_TYPE, "application/json"})
+DEFAULT_ACCEPTED = frozenset({API_TYPE, "application/json", "application/*", "*/*"})
+
+type View = Callable[..., Any]
+
+
+def produces(*media_types: str) -> Callable[[View], View]:
+    """Declare the extra media types a view can answer with."""
+
+    def decorator(view: View) -> View:
+        view.produces = frozenset(media_types)  # type: ignore[attr-defined]
+        return view
+
+    return decorator
+
+
+def _accepted_types(header: str) -> list[str]:
+    accepted = []
+    for entry in header.split(","):
+        parts = [part.strip() for part in entry.split(";")]
+        media_type = parts[0].lower()
+        if not media_type:
+            continue
+        quality = 1.0
+        for parameter in parts[1:]:
+            name, _, value = parameter.partition("=")
+            if name.strip().lower() == "q":
+                try:
+                    quality = float(value)
+                except ValueError:
+                    quality = 0.0
+        if quality > 0:
+            accepted.append(media_type)
+    return accepted
+
+
+def check_accept() -> None:
+    header = request.headers.get("Accept")
+    if header is None or not header.strip():
+        return
+    allowed = set(DEFAULT_ACCEPTED)
+    view = current_app.view_functions.get(request.endpoint or "")
+    allowed |= getattr(view, "produces", frozenset())
+    if not any(media_type in allowed for media_type in _accepted_types(header)):
+        raise DomainError(
+            "not-acceptable",
+            f"Send Accept with {API_TYPE}, application/json or */*",
+        )