Skip to content

Speakr is a personal, self-hosted web application designed for transcribing audio recordings

Python
4.5 KB
Raw Blame
"""In-app notifications.

Speakr already had a *delivery* channel in `push_subscription.py` (web push to
a browser) but nowhere to keep a notice, so nothing could be listed, counted,
or marked read. This is the store. Push stays a channel it can fan out to.

Three decisions are worth stating, because each one is cheap now and expensive
to retrofit.

**The text is not stored.** A `message_key` plus a JSON `params` blob is,
and the frontend renders it with the same `t()` every other string goes
through. Storing English sentences would make notifications the one part of
the interface that ignores the seven locales.

**Notices are deduplicated by `dedupe_key`.** The voice-embedding check runs
at startup, and startup happens on every restart and deploy, so an insert per
run would pile up identical rows. Unique per (user, key), so re-raising an
existing condition touches the existing row instead.

**A notice can be a condition, not only an event.** Most are events: something
happened, the user dismisses it. But "your embedding model changed" describes a
state that ends when the backend is restored, so it has to be resolvable by the
producer rather than only dismissable by the reader. `resolved_at` is what
separates the two.

Rows are one per recipient. The alternative, one row plus a read-state join
table, saves rows and costs a join on every unread count, every list and every
dismissal. Fan-out is what GitHub and Discourse do and it keeps per-user state
trivial.
"""

from datetime import datetime

from src.database import db


# Severity drives presentation only; nothing branches on it server-side.
NOTIFICATION_LEVELS = ('info', 'warning', 'error')

# Stable machine names. The value is written into rows, so renaming one orphans
# every existing notice of that kind; add a new name instead.
KIND_VOICE_EMBEDDING_CHANGED = 'voice_embedding.changed'


class Notification(db.Model):
    """One notice for one recipient."""

    __tablename__ = 'notification'

    id = db.Column(db.Integer, primary_key=True)
    user_id = db.Column(db.Integer, db.ForeignKey('user.id', ondelete='CASCADE'),
                        nullable=False, index=True)

    # What kind of thing this is, for filtering and for the producer to find
    # its own notices again.
    kind = db.Column(db.String(80), nullable=False, index=True)
    level = db.Column(db.String(20), nullable=False, default='info')

    # Localized at render time. `params` is interpolated into the string.
    message_key = db.Column(db.String(200), nullable=False)
    params = db.Column(db.JSON, nullable=True)

    # Optional in-app destination, e.g. '/admin'. Relative on purpose: an
    # absolute URL in a notification is a phishing shape.
    link = db.Column(db.String(500), nullable=True)

    # Idempotency. Unique per user so re-raising the same condition updates the
    # existing row rather than adding another.
    dedupe_key = db.Column(db.String(200), nullable=False, index=True)

    created_at = db.Column(db.DateTime, nullable=False, default=datetime.utcnow, index=True)
    updated_at = db.Column(db.DateTime, nullable=False, default=datetime.utcnow,
                           onupdate=datetime.utcnow)

    # Read: the user has seen it. Dismissed: the user cleared it away.
    # Resolved: the condition it described has ended, cleared by the producer
    # and not by the reader.
    read_at = db.Column(db.DateTime, nullable=True)
    dismissed_at = db.Column(db.DateTime, nullable=True)
    resolved_at = db.Column(db.DateTime, nullable=True, index=True)

    __table_args__ = (
        db.UniqueConstraint('user_id', 'dedupe_key', name='uq_notification_user_dedupe'),
    )

    user = db.relationship('User', backref=db.backref(
        'notifications', lazy='dynamic', cascade='all, delete-orphan'))

    @property
    def is_active(self):
        """Still worth showing: neither cleared by the user nor ended."""
        return self.dismissed_at is None and self.resolved_at is None

    def to_dict(self):
        return {
            'id': self.id,
            'kind': self.kind,
            'level': self.level,
            'message_key': self.message_key,
            'params': self.params or {},
            'link': self.link,
            'created_at': self.created_at.isoformat() if self.created_at else None,
            'read': self.read_at is not None,
            'resolved': self.resolved_at is not None,
        }

    def __repr__(self):  # pragma: no cover - debugging aid
        return f'<Notification {self.id} {self.kind} user={self.user_id}>'