Add custom emoji support (#18)

Site-wide, any user can upload -- usable both as reactions and inline
in message text via :shortcode:, alongside the existing built-in
Unicode picker. A :shortcode: reference is stored/sent as literal
text (same as the built-in shortcode convention) and resolved to an
image at render time, so it degrades to plain text if the emoji is
later deleted.

Backend: new custom_emoji table (shortcode unique, sized to fit
MessageReaction.emoji's existing column alongside its colons), upload/
list/delete endpoints (delete restricted to uploader or site admin).

Frontend: a CustomEmojiProvider context feeds a new "Custom" category
in the emoji picker (inline upload + hover-to-remove), extends the
composer's shortcode autocomplete, and a shared EmojiGlyph resolver
renders custom emoji wherever a value can appear -- message text,
reaction pills, and the picker itself.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

backend/app/main.py

@@ -15,6 +15,7 @@ from app.routers import (
     admin,
     auth,
     bots,
+    custom_emoji,
     custom_themes,
     health,
     push,
@@ -93,6 +94,7 @@ def create_app() -> FastAPI:
     app.include_router(users.router)
     app.include_router(push.router)
     app.include_router(custom_themes.router)
+    app.include_router(custom_emoji.router)
     app.include_router(uploads.router)
     app.include_router(admin.router)
     app.include_router(bots.router)

backend/app/models/__init__.py

@@ -1,6 +1,7 @@
 from app.models.admin_audit_log import AdminAuditLog
 from app.models.api_token import ApiToken
 from app.models.base import Base
+from app.models.custom_emoji import CustomEmoji
 from app.models.custom_theme import CustomTheme
 from app.models.event_subscription import EventSubscription
 from app.models.invite import InviteStatus
@@ -46,5 +47,6 @@ __all__ = [
     "WebhookIncoming",
     "EventSubscription",
     "CustomTheme",
+    "CustomEmoji",
     "LinkPreview",
 ]

backend/app/models/custom_emoji.py

@@ -0,0 +1,28 @@
+import uuid
+from datetime import datetime
+
+from sqlalchemy import DateTime, ForeignKey, String, func
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from app.models.base import Base
+
+
+class CustomEmoji(Base):
+    __tablename__ = "custom_emoji"
+
+    id: Mapped[uuid.UUID] = mapped_column(primary_key=True, default=uuid.uuid4)
+    # #18: site-wide, not room-scoped -- kept globally unique so a bare
+    # `:shortcode:` in any message/reaction is unambiguous without also
+    # knowing which room it was posted in. 30 chars, not 32 -- the stored
+    # *reference* in MessageReaction.emoji (String(32)) is the shortcode
+    # wrapped in colons, so this is sized to leave room for both without
+    # widening that column.
+    shortcode: Mapped[str] = mapped_column(String(30), unique=True, index=True, nullable=False)
+    storage_filename: Mapped[str] = mapped_column(String(64), nullable=False)
+    content_type: Mapped[str] = mapped_column(String(50), nullable=False)
+    uploaded_by: Mapped[uuid.UUID] = mapped_column(ForeignKey("users.id"), nullable=False)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now(), nullable=False
+    )
+
+    uploader = relationship("User")

backend/app/routers/custom_emoji.py

@@ -0,0 +1,131 @@
+import uuid
+
+from fastapi import APIRouter, Depends, File, Form, HTTPException, UploadFile
+from fastapi.responses import FileResponse
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.database import get_db
+from app.dependencies import get_current_user
+from app.models import User
+from app.schemas.custom_emoji import CustomEmojiRead
+from app.services.custom_emoji_service import (
+    SHORTCODE_PATTERN,
+    CustomEmojiNotFoundError,
+    DuplicateShortcodeError,
+    InvalidShortcodeError,
+    NotEmojiOwnerError,
+    create_custom_emoji,
+    delete_custom_emoji,
+    get_custom_emoji_by_shortcode,
+    list_custom_emoji,
+)
+from app.services.upload_settings_service import format_mb, get_upload_settings
+from app.storage import (
+    ALLOWED_IMAGE_CONTENT_TYPES,
+    UPLOADS_DIR,
+    InvalidImageError,
+    UploadTooLargeError,
+    process_image,
+    read_capped,
+    save_file,
+)
+
+# Small and square -- these render inline in message text/reaction pills at
+# roughly text size, nowhere near message-image or avatar dimensions.
+CUSTOM_EMOJI_MAX_DIMENSION = 128
+
+router = APIRouter(prefix="/api/custom-emoji", tags=["custom-emoji"])
+
+
+@router.post("", response_model=CustomEmojiRead, status_code=201)
+async def upload_custom_emoji_endpoint(
+    shortcode: str = Form(...),
+    file: UploadFile = File(...),
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    shortcode = shortcode.strip().lower()
+    # Checked here, before any file processing/saving, so the common
+    # rejection cases (bad format, name taken) never leave an orphaned
+    # file on disk -- create_custom_emoji below still re-checks both
+    # (the actual source of truth, and the only thing that closes the
+    # TOCTOU race on the uniqueness check).
+    if not SHORTCODE_PATTERN.match(shortcode):
+        raise HTTPException(
+            status_code=400,
+            detail="Shortcode must be 2-30 characters: lowercase letters, numbers, hyphens, underscores",
+        )
+    if await get_custom_emoji_by_shortcode(db, shortcode) is not None:
+        raise HTTPException(status_code=409, detail="An emoji with that shortcode already exists")
+
+    if file.content_type not in ALLOWED_IMAGE_CONTENT_TYPES:
+        raise HTTPException(status_code=400, detail="Unsupported image type")
+
+    upload_settings = await get_upload_settings(db)
+    try:
+        data = await read_capped(file, cap=upload_settings.max_upload_bytes)
+    except UploadTooLargeError:
+        raise HTTPException(
+            status_code=413,
+            detail=f"Image exceeds {format_mb(upload_settings.max_upload_bytes)} limit",
+        )
+
+    try:
+        data, ext = process_image(
+            data, file.content_type, square=True, max_dimension=CUSTOM_EMOJI_MAX_DIMENSION
+        )
+    except InvalidImageError:
+        raise HTTPException(status_code=400, detail="File is not a valid image")
+
+    storage_filename = save_file(data, ext)
+    try:
+        return await create_custom_emoji(
+            db, current_user.id, shortcode, storage_filename, file.content_type
+        )
+    except (InvalidShortcodeError, DuplicateShortcodeError):
+        # Already checked above -- only reachable via the uniqueness
+        # check's TOCTOU race (two uploads of the same new shortcode at
+        # once), not the common case.
+        raise HTTPException(status_code=409, detail="An emoji with that shortcode already exists")
+
+
+@router.get("", response_model=list[CustomEmojiRead])
+async def list_custom_emoji_endpoint(
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    return await list_custom_emoji(db)
+
+
+@router.delete("/{emoji_id}", status_code=204)
+async def delete_custom_emoji_endpoint(
+    emoji_id: uuid.UUID,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    try:
+        await delete_custom_emoji(db, emoji_id, current_user)
+    except CustomEmojiNotFoundError:
+        raise HTTPException(status_code=404, detail="Custom emoji not found")
+    except NotEmojiOwnerError:
+        raise HTTPException(status_code=403, detail="Only the uploader or a site admin can remove this")
+
+
+@router.get("/{shortcode}/image")
+async def get_custom_emoji_image_endpoint(
+    shortcode: str,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    emoji = await get_custom_emoji_by_shortcode(db, shortcode)
+    if emoji is None:
+        raise HTTPException(status_code=404, detail="Custom emoji not found")
+    return FileResponse(
+        UPLOADS_DIR / emoji.storage_filename,
+        media_type=emoji.content_type,
+        # Site-wide and rarely changed, but a shortcode can be deleted and
+        # re-uploaded with different image data -- short-cache like the
+        # avatar endpoint, not `immutable` like content-addressed message
+        # images.
+        headers={"Cache-Control": "private, max-age=300"},
+    )

backend/app/schemas/custom_emoji.py

@@ -0,0 +1,13 @@
+import uuid
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict
+
+
+class CustomEmojiRead(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: uuid.UUID
+    shortcode: str
+    uploaded_by: uuid.UUID
+    created_at: datetime

backend/app/services/custom_emoji_service.py

@@ -0,0 +1,80 @@
+import re
+import uuid
+
+from sqlalchemy import select
+from sqlalchemy.exc import IntegrityError
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models import CustomEmoji, User
+from app.storage import delete_file
+
+# Deliberately stricter than the built-in Unicode shortcode set's charset
+# (see frontend/src/lib/emojiShortcodes.ts, which also allows '+') -- this
+# is validating a *new name being chosen*, not matching against an
+# existing fixed list, so there's no reason to allow anything a person
+# wouldn't naturally type. Max 30 chars matches CustomEmoji.shortcode's
+# column width exactly (see that model's comment for why).
+SHORTCODE_PATTERN = re.compile(r"^[a-z0-9_-]{2,30}$")
+
+
+class InvalidShortcodeError(Exception):
+    pass
+
+
+class DuplicateShortcodeError(Exception):
+    pass
+
+
+class CustomEmojiNotFoundError(Exception):
+    pass
+
+
+class NotEmojiOwnerError(Exception):
+    pass
+
+
+async def create_custom_emoji(
+    db: AsyncSession,
+    uploaded_by: uuid.UUID,
+    shortcode: str,
+    storage_filename: str,
+    content_type: str,
+) -> CustomEmoji:
+    if not SHORTCODE_PATTERN.match(shortcode):
+        raise InvalidShortcodeError()
+
+    emoji = CustomEmoji(
+        shortcode=shortcode,
+        storage_filename=storage_filename,
+        content_type=content_type,
+        uploaded_by=uploaded_by,
+    )
+    db.add(emoji)
+    try:
+        await db.commit()
+    except IntegrityError as exc:
+        await db.rollback()
+        raise DuplicateShortcodeError() from exc
+    await db.refresh(emoji)
+    return emoji
+
+
+async def list_custom_emoji(db: AsyncSession) -> list[CustomEmoji]:
+    result = await db.execute(select(CustomEmoji).order_by(CustomEmoji.shortcode))
+    return list(result.scalars().all())
+
+
+async def get_custom_emoji_by_shortcode(db: AsyncSession, shortcode: str) -> CustomEmoji | None:
+    result = await db.execute(select(CustomEmoji).where(CustomEmoji.shortcode == shortcode))
+    return result.scalar_one_or_none()
+
+
+async def delete_custom_emoji(db: AsyncSession, emoji_id: uuid.UUID, current_user: User) -> None:
+    emoji = await db.get(CustomEmoji, emoji_id)
+    if emoji is None:
+        raise CustomEmojiNotFoundError()
+    if emoji.uploaded_by != current_user.id and not current_user.is_site_admin:
+        raise NotEmojiOwnerError()
+    delete_file(emoji.storage_filename)
+    await db.delete(emoji)
+    await db.commit()

backend/app/ws/chat.py

@@ -311,7 +311,11 @@ async def chat_endpoint(websocket: WebSocket, db: AsyncSession = Depends(get_db)
                         envelope.room_id is None
                         or envelope.message_id is None
                         or not envelope.emoji
-                        or len(envelope.emoji) > 8
+                        # #18: a raw unicode glyph never gets close to this,
+                        # but a custom emoji reaction is stored as its
+                        # literal `:shortcode:` text (see MessageReaction.emoji's
+                        # String(32) column, which this matches exactly).
+                        or len(envelope.emoji) > 32
                     ):
                         await websocket.send_json(
                             {"type": "error", "detail": "room_id, message_id, and emoji required"}