WIP checkpoint: Friends/follow/block models + Alembic migration

backend/alembic/env.py

@@ -8,7 +8,7 @@ from sqlalchemy.ext.asyncio import create_async_engine
 
 from app.config import settings
 from app.database import Base
-from app.models import user, session, world, asset  # noqa: F401
+from app.models import user, session, world, asset, friendship, follow, block  # noqa: F401
 
 # this is the Alembic Config object, which provides
 # access to the values within the .ini file in use.

backend/alembic/versions/0002_social_graph.py

@@ -0,0 +1,136 @@
+"""social graph: friendships, follows, blocks
+
+Revision ID: 0002_social_graph
+Revises: 0001_initial
+Create Date: 2026-08-18 00:00:00.000000
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+# revision identifiers, used by Alembic.
+revision: str = "0002_social_graph"
+down_revision: Union[str, None] = "0001_initial"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Create friendships, follows, and blocks tables."""
+    op.create_table(
+        "friendships",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("requester_id", sa.Integer(), nullable=False),
+        sa.Column("addressee_id", sa.Integer(), nullable=False),
+        sa.Column("status", sa.String(length=20), server_default="pending", nullable=False),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=True),
+        sa.CheckConstraint(
+            "status IN ('pending', 'accepted')",
+            name="ck_friendships_status",
+        ),
+        sa.CheckConstraint(
+            "requester_id <> addressee_id",
+            name="ck_friendships_no_self",
+        ),
+        sa.ForeignKeyConstraint(
+            ["addressee_id"],
+            ["users.id"],
+            ondelete="CASCADE",
+        ),
+        sa.ForeignKeyConstraint(
+            ["requester_id"],
+            ["users.id"],
+            ondelete="CASCADE",
+        ),
+        sa.PrimaryKeyConstraint("id"),
+        sa.UniqueConstraint(
+            "requester_id",
+            "addressee_id",
+            name="uq_friendships_requester_addressee",
+        ),
+    )
+    op.create_index(op.f("ix_friendships_id"), "friendships", ["id"], unique=False)
+    op.create_index(op.f("ix_friendships_addressee_id"), "friendships", ["addressee_id"], unique=False)
+    op.create_index(op.f("ix_friendships_requester_id"), "friendships", ["requester_id"], unique=False)
+
+    op.create_table(
+        "follows",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("follower_id", sa.Integer(), nullable=False),
+        sa.Column("followed_id", sa.Integer(), nullable=False),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.CheckConstraint(
+            "follower_id <> followed_id",
+            name="ck_follows_no_self",
+        ),
+        sa.ForeignKeyConstraint(
+            ["followed_id"],
+            ["users.id"],
+            ondelete="CASCADE",
+        ),
+        sa.ForeignKeyConstraint(
+            ["follower_id"],
+            ["users.id"],
+            ondelete="CASCADE",
+        ),
+        sa.PrimaryKeyConstraint("id"),
+        sa.UniqueConstraint(
+            "follower_id",
+            "followed_id",
+            name="uq_follows_follower_followed",
+        ),
+    )
+    op.create_index(op.f("ix_follows_id"), "follows", ["id"], unique=False)
+    op.create_index(op.f("ix_follows_followed_id"), "follows", ["followed_id"], unique=False)
+    op.create_index(op.f("ix_follows_follower_id"), "follows", ["follower_id"], unique=False)
+
+    op.create_table(
+        "blocks",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("blocker_id", sa.Integer(), nullable=False),
+        sa.Column("blocked_id", sa.Integer(), nullable=False),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.CheckConstraint(
+            "blocker_id <> blocked_id",
+            name="ck_blocks_no_self",
+        ),
+        sa.ForeignKeyConstraint(
+            ["blocked_id"],
+            ["users.id"],
+            ondelete="CASCADE",
+        ),
+        sa.ForeignKeyConstraint(
+            ["blocker_id"],
+            ["users.id"],
+            ondelete="CASCADE",
+        ),
+        sa.PrimaryKeyConstraint("id"),
+        sa.UniqueConstraint(
+            "blocker_id",
+            "blocked_id",
+            name="uq_blocks_blocker_blocked",
+        ),
+    )
+    op.create_index(op.f("ix_blocks_id"), "blocks", ["id"], unique=False)
+    op.create_index(op.f("ix_blocks_blocked_id"), "blocks", ["blocked_id"], unique=False)
+    op.create_index(op.f("ix_blocks_blocker_id"), "blocks", ["blocker_id"], unique=False)
+
+
+def downgrade() -> None:
+    """Drop friendships, follows, and blocks tables."""
+    op.drop_index(op.f("ix_blocks_blocker_id"), table_name="blocks")
+    op.drop_index(op.f("ix_blocks_blocked_id"), table_name="blocks")
+    op.drop_index(op.f("ix_blocks_id"), table_name="blocks")
+    op.drop_table("blocks")
+
+    op.drop_index(op.f("ix_follows_follower_id"), table_name="follows")
+    op.drop_index(op.f("ix_follows_followed_id"), table_name="follows")
+    op.drop_index(op.f("ix_follows_id"), table_name="follows")
+    op.drop_table("follows")
+
+    op.drop_index(op.f("ix_friendships_requester_id"), table_name="friendships")
+    op.drop_index(op.f("ix_friendships_addressee_id"), table_name="friendships")
+    op.drop_index(op.f("ix_friendships_id"), table_name="friendships")
+    op.drop_table("friendships")

backend/app/models/__init__.py

@@ -2,5 +2,17 @@ from app.models.user import User
 from app.models.session import Session
 from app.models.world import World
 from app.models.asset import Asset
+from app.models.friendship import Friendship, FriendshipStatus
+from app.models.follow import Follow
+from app.models.block import Block
 
-__all__ = ["User", "Session", "World", "Asset"]
+__all__ = [
+    "User",
+    "Session",
+    "World",
+    "Asset",
+    "Friendship",
+    "FriendshipStatus",
+    "Follow",
+    "Block",
+]

backend/app/models/block.py

@@ -0,0 +1,48 @@
+"""Block model: a hard deny that also hides content and prevents DMs."""
+
+from sqlalchemy import CheckConstraint, Column, DateTime, ForeignKey, Integer, UniqueConstraint
+from sqlalchemy.orm import relationship
+from sqlalchemy.sql import func
+
+from app.database import Base
+
+
+class Block(Base):
+    __tablename__ = "blocks"
+    __table_args__ = (
+        UniqueConstraint(
+            "blocker_id",
+            "blocked_id",
+            name="uq_blocks_pair",
+        ),
+        CheckConstraint(
+            "blocker_id <> blocked_id",
+            name="ck_blocks_no_self",
+        ),
+    )
+
+    id = Column(Integer, primary_key=True, index=True)
+    blocker_id = Column(
+        Integer,
+        ForeignKey("users.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True,
+    )
+    blocked_id = Column(
+        Integer,
+        ForeignKey("users.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True,
+    )
+    created_at = Column(DateTime(timezone=True), server_default=func.now())
+
+    blocker = relationship(
+        "User",
+        foreign_keys=[blocker_id],
+        back_populates="blocks_issued",
+    )
+    blocked = relationship(
+        "User",
+        foreign_keys=[blocked_id],
+        back_populates="blocks_received",
+    )

backend/app/models/follow.py

@@ -0,0 +1,48 @@
+"""Follow model: a one-way relationship requiring no approval."""
+
+from sqlalchemy import CheckConstraint, Column, DateTime, ForeignKey, Integer, UniqueConstraint
+from sqlalchemy.orm import relationship
+from sqlalchemy.sql import func
+
+from app.database import Base
+
+
+class Follow(Base):
+    __tablename__ = "follows"
+    __table_args__ = (
+        UniqueConstraint(
+            "follower_id",
+            "followed_id",
+            name="uq_follows_pair",
+        ),
+        CheckConstraint(
+            "follower_id <> followed_id",
+            name="ck_follows_no_self",
+        ),
+    )
+
+    id = Column(Integer, primary_key=True, index=True)
+    follower_id = Column(
+        Integer,
+        ForeignKey("users.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True,
+    )
+    followed_id = Column(
+        Integer,
+        ForeignKey("users.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True,
+    )
+    created_at = Column(DateTime(timezone=True), server_default=func.now())
+
+    follower = relationship(
+        "User",
+        foreign_keys=[follower_id],
+        back_populates="following",
+    )
+    followed = relationship(
+        "User",
+        foreign_keys=[followed_id],
+        back_populates="followers",
+    )

backend/app/models/friendship.py

@@ -0,0 +1,74 @@
+"""Friendship model: a one-directional request that becomes mutual on accept."""
+
+from sqlalchemy import (
+    CheckConstraint,
+    Column,
+    DateTime,
+    ForeignKey,
+    Integer,
+    String,
+    UniqueConstraint,
+)
+from sqlalchemy.orm import relationship
+from sqlalchemy.sql import func
+
+from app.database import Base
+
+
+class FriendshipStatus:
+    """String values for the friendship.status column."""
+
+    PENDING = "pending"
+    ACCEPTED = "accepted"
+
+
+class Friendship(Base):
+    __tablename__ = "friendships"
+    __table_args__ = (
+        UniqueConstraint(
+            "requester_id",
+            "addressee_id",
+            name="uq_friendships_pair",
+        ),
+        CheckConstraint(
+            "requester_id <> addressee_id",
+            name="ck_friendships_no_self",
+        ),
+        CheckConstraint(
+            "status IN ('pending', 'accepted')",
+            name="ck_friendships_status",
+        ),
+    )
+
+    id = Column(Integer, primary_key=True, index=True)
+    requester_id = Column(
+        Integer,
+        ForeignKey("users.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True,
+    )
+    addressee_id = Column(
+        Integer,
+        ForeignKey("users.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True,
+    )
+    status = Column(
+        String(20),
+        nullable=False,
+        default=FriendshipStatus.PENDING,
+        server_default=FriendshipStatus.PENDING,
+    )
+    created_at = Column(DateTime(timezone=True), server_default=func.now())
+    updated_at = Column(DateTime(timezone=True), onupdate=func.now())
+
+    requester = relationship(
+        "User",
+        foreign_keys=[requester_id],
+        back_populates="sent_friend_requests",
+    )
+    addressee = relationship(
+        "User",
+        foreign_keys=[addressee_id],
+        back_populates="received_friend_requests",
+    )

backend/app/models/user.py

@@ -19,3 +19,41 @@ class User(Base):
     sessions = relationship("Session", back_populates="user", cascade="all, delete-orphan")
     worlds = relationship("World", back_populates="owner")
     assets = relationship("Asset", back_populates="owner")
+
+    # Social graph
+    sent_friend_requests = relationship(
+        "Friendship",
+        foreign_keys="Friendship.requester_id",
+        back_populates="requester",
+        cascade="all, delete-orphan",
+    )
+    received_friend_requests = relationship(
+        "Friendship",
+        foreign_keys="Friendship.addressee_id",
+        back_populates="addressee",
+        cascade="all, delete-orphan",
+    )
+    following = relationship(
+        "Follow",
+        foreign_keys="Follow.follower_id",
+        back_populates="follower",
+        cascade="all, delete-orphan",
+    )
+    followers = relationship(
+        "Follow",
+        foreign_keys="Follow.followed_id",
+        back_populates="followed",
+        cascade="all, delete-orphan",
+    )
+    blocks_issued = relationship(
+        "Block",
+        foreign_keys="Block.blocker_id",
+        back_populates="blocker",
+        cascade="all, delete-orphan",
+    )
+    blocks_received = relationship(
+        "Block",
+        foreign_keys="Block.blocked_id",
+        back_populates="blocked",
+        cascade="all, delete-orphan",
+    )

backend/app/services/__init__.py

@@ -1 +0,0 @@
-"""Application services."""

backend/app/services/text_filter.py

@@ -1,340 +0,0 @@
-"""Pluggable server-side text filtering service.
-
-Provides a ``TextFilter`` protocol with a deterministic default
-implementation (profanity/term list with normalization) and a hook
-for third-party providers.
-
-Usage::
-
-    from app.services.text_filter import TextFilter, FilterResult, \
-        ProfanityTextFilter, get_text_filter
-
-    # Default factory reads config from the path below
-    filt = get_text_filter()
-    result = filt.check("Hello wor1d!")
-    # result.action == FilterAction.ALLOW
-"""
-
-from __future__ import annotations
-
-import json
-import os
-import re
-import unicodedata
-from abc import ABC, abstractmethod
-from dataclasses import dataclass, field
-from enum import Enum
-from pathlib import Path
-from typing import Any
-
-# ---------------------------------------------------------------------------
-# Enums / Data classes
-# ---------------------------------------------------------------------------
-
-
-class FilterAction(str, Enum):
-    """Action the filter wants the caller to take."""
-
-    ALLOW = "allow"
-    REDACT = "redact"
-    REJECT = "reject"
-
-
-@dataclass(frozen=True)
-class FilterResult:
-    """Immutable result of a single ``TextFilter.check()`` call.
-
-    Attributes:
-        action: What to do with the message.
-        filtered_text: The text after redaction (may equal *text* if
-            action is ``ALLOW``).
-        matched_terms: Sorted list of terms that triggered the filter.
-    """
-
-    action: FilterAction
-    filtered_text: str
-    matched_terms: list[str] = field(default_factory=list)
-
-    @property
-    def is_allowed(self) -> bool:
-        return self.action == FilterAction.ALLOW
-
-    @property
-    def is_rejected(self) -> bool:
-        return self.action == FilterAction.REJECT
-
-    @property
-    def is_redacted(self) -> bool:
-        return self.action == FilterAction.REDACT
-
-
-# ---------------------------------------------------------------------------
-# Protocol / abstract base
-# ---------------------------------------------------------------------------
-
-
-class TextFilter(ABC):
-    """Protocol for server-side text filters.
-
-    Every concrete filter must implement ``check()``.  The default
-    implementation (``ProfanityTextFilter``) is deterministic and
-    requires no external service.  A third-party provider can be
-    plugged in by subclassing ``TextFilter`` and overriding ``check``.
-    """
-
-    @abstractmethod
-    def check(self, text: str) -> FilterResult:
-        """Analyse *text* and return a ``FilterResult``.
-
-        Args:
-            text: Raw message text to filter.
-
-        Returns:
-            A ``FilterResult`` with the decision and any redacted text.
-        """
-
-
-# ---------------------------------------------------------------------------
-# Normalisation helpers
-# ---------------------------------------------------------------------------
-
-# Common leetspeak substitutions (char -> set of possible originals)
-_LEETSPEAK: dict[str, str] = {
-    "0": "o",
-    "1": "i",
-    "3": "e",
-    "4": "a",
-    "5": "s",
-    "7": "t",
-    "8": "b",
-    "9": "g",
-    "@": "a",
-}
-
-# Normalise separators that are often used to obfuscate words
-_SEPARATORS = re.compile(r"[\s_\-\.]+")
-
-
-def _normalize(text: str) -> str:
-    """Case-fold, strip diacritics, and replace leetspeak / separators.
-
-    This produces a canonical form for matching against the term list.
-    """
-    # Case-fold
-    text = text.casefold()
-    # Strip diacritics (e.g. é -> e)
-    text = unicodedata.normalize("NFKD", text)
-    text = "".join(c for c in text if not unicodedata.combining(c))
-    # Replace leetspeak
-    normalized = ""
-    for ch in text:
-        normalized += _LEETSPEAK.get(ch, ch)
-    # Collapse separators
-    normalized = _SEPARATORS.sub("", normalized)
-    return normalized
-
-
-# ---------------------------------------------------------------------------
-# Default implementation
-# ---------------------------------------------------------------------------
-
-# Default config path (relative to project root)
-_DEFAULT_CONFIG_PATH = Path(__file__).resolve().parent.parent.parent / "data" / "text_filter_config.json"
-
-
-@dataclass
-class _FilterPolicy:
-    """Filtering policy loaded from config."""
-
-    mode: str  # "redact" or "reject"
-    redaction_char: str = "*"
-    # Minimum term length to consider (avoids matching single chars)
-    min_term_length: int = 3
-    # If True, match terms case-insensitively after normalisation
-    case_insensitive: bool = True
-    # If True, match whole words only (after normalisation)
-    whole_word: bool = True
-
-
-class ProfanityTextFilter(TextFilter):
-    """Deterministic text filter backed by a JSON term list.
-
-    The config file is a JSON object with:
-
-    .. code-block:: json
-
-        {
-            "mode": "redact",
-            "redaction_char": "*",
-            "min_term_length": 3,
-            "case_insensitive": true,
-            "whole_word": true,
-            "terms": ["badword", "another", ...]
-        }
-
-    Terms are matched after normalisation (case-fold, leetspeak
-    substitution, separator removal, diacritic stripping).
-    """
-
-    def __init__(
-        self,
-        config_path: str | Path | None = None,
-        terms: list[str] | None = None,
-        policy: _FilterPolicy | None = None,
-    ) -> None:
-        """
-        Args:
-            config_path: Path to a JSON config file.  Ignored if *terms*
-                is provided.
-            terms: Inline list of terms (overrides config file).
-            policy: Filter policy.  Defaults to a redact policy.
-        """
-        if terms is not None:
-            self._terms: list[str] = [t.lower() for t in terms]
-        elif config_path is not None:
-            self._terms = self._load_terms(Path(config_path))
-        else:
-            # Try default path
-            if _DEFAULT_CONFIG_PATH.exists():
-                self._terms = self._load_terms(_DEFAULT_CONFIG_PATH)
-            else:
-                self._terms = []
-
-        self._policy = policy or _FilterPolicy(mode="redact")
-        # Pre-compile patterns for each term
-        self._patterns: list[tuple[re.Pattern[str], str]] = []
-        for term in self._terms:
-            if len(term) < self._policy.min_term_length:
-                continue
-            if self._policy.whole_word:
-                pattern = re.compile(
-                    r"(?<!\w)" + re.escape(term) + r"(?!\w)",
-                    re.IGNORECASE if self._policy.case_insensitive else 0,
-                )
-            else:
-                pattern = re.compile(
-                    re.escape(term),
-                    re.IGNORECASE if self._policy.case_insensitive else 0,
-                )
-            self._patterns.append((pattern, term))
-
-    # -- config loading --------------------------------------------------
-
-    @staticmethod
-    def _load_terms(config_path: Path) -> list[str]:
-        """Load terms from a JSON config file."""
-        with open(config_path, "r", encoding="utf-8") as f:
-            data: dict[str, Any] = json.load(f)
-
-        terms: list[str] = []
-        for raw in data.get("terms", []):
-            term = str(raw).strip()
-            if term:
-                terms.append(term.casefold())
-        return terms
-
-    # -- public API ------------------------------------------------------
-
-    def check(self, text: str) -> FilterResult:
-        """Check *text* against the loaded term list.
-
-        Returns a ``FilterResult`` with the appropriate action,
-        filtered text, and matched terms.
-        """
-        if not text:
-            return FilterResult(
-                action=FilterAction.ALLOW,
-                filtered_text=text,
-                matched_terms=[],
-            )
-
-        normalized = _normalize(text)
-        matched_terms: list[str] = []
-
-        # Collect all matches
-        for pattern, term in self._patterns:
-            if pattern.search(normalized):
-                if term not in matched_terms:
-                    matched_terms.append(term)
-
-        if not matched_terms:
-            return FilterResult(
-                action=FilterAction.ALLOW,
-                filtered_text=text,
-                matched_terms=[],
-            )
-
-        matched_terms.sort()
-
-        # Build filtered text by replacing matched terms
-        filtered = text
-        for term in matched_terms:
-            norm_term = _normalize(term)
-            # Find all occurrences in the normalised text and replace in original
-            # We need to map positions from normalised text back to original
-            filtered = self._replace_terms(filtered, term, norm_term)
-
-        action = FilterAction.REJECT if self._policy.mode == "reject" else FilterAction.REDACT
-
-        return FilterResult(
-            action=action,
-            filtered_text=filtered,
-            matched_terms=matched_terms,
-        )
-
-    def _replace_terms(
-        self, text: str, term: str, norm_term: str
-    ) -> str:
-        """Replace occurrences of *term* in *text* with redaction chars.
-
-        Uses normalised text for matching but preserves original casing
-        in the output.
-        """
-        norm_text = _normalize(text)
-        norm_term_len = len(norm_term)
-        result_chars = list(text)
-
-        start = 0
-        while start < len(norm_text):
-            idx = norm_text.find(norm_term, start)
-            if idx == -1:
-                break
-            # Replace characters in original text
-            for i in range(idx, min(idx + norm_term_len, len(result_chars))):
-                result_chars[i] = self._policy.redaction_char
-            start = idx + norm_term_len
-
-        return "".join(result_chars)
-
-    @property
-    def terms(self) -> list[str]:
-        """Read-only access to the loaded term list."""
-        return list(self._terms)
-
-    @property
-    def policy(self) -> _FilterPolicy:
-        """Read-only access to the filter policy."""
-        return self._policy
-
-
-# ---------------------------------------------------------------------------
-# Factory
-# ---------------------------------------------------------------------------
-
-
-def get_text_filter(
-    config_path: str | Path | None = None,
-    terms: list[str] | None = None,
-    policy: _FilterPolicy | None = None,
-) -> TextFilter:
-    """Return a ``TextFilter`` instance.
-
-    By default this creates a ``ProfanityTextFilter``.  To use a
-    third-party provider, subclass ``TextFilter`` and pass an
-    instance here instead.
-    """
-    return ProfanityTextFilter(
-        config_path=config_path,
-        terms=terms,
-        policy=policy,
-    )