Moderation proof of concept implementation

h/db/mixins.py

@@ -5,13 +5,16 @@
 import sqlalchemy as sa
 
 
-class Timestamps:
+class CreatedMixin:
     created = sa.Column(
         sa.DateTime,
         default=datetime.datetime.utcnow,
         server_default=sa.func.now(),
         nullable=False,
     )
+
+
+class Timestamps(CreatedMixin):
     updated = sa.Column(
         sa.DateTime,
         server_default=sa.func.now(),

h/events.py

@@ -1,7 +1,12 @@
+from typing import Literal
+
+AnnotationAction = Literal["create", "update", "delete"]
+
+
 class AnnotationEvent:
     """An event representing an action on an annotation."""
 
-    def __init__(self, request, annotation_id, action):
+    def __init__(self, request, annotation_id, action: AnnotationAction):
         self.request = request
         self.annotation_id = annotation_id
         self.action = action

h/migrations/versions/96cde96b2fd7_backfill_denied_based_on_moderation.py

@@ -0,0 +1,41 @@
+"""Backfill DENIED based on moderation."""
+
+import sqlalchemy as sa
+from alembic import op
+
+revision = "96cde96b2fd7"
+down_revision = "c8f748cbfb8f"
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+
+    result = conn.execute(
+        sa.text(
+            """
+    UPDATE annotation
+        SET moderation_status = 'DENIED'
+    FROM annotation_moderation
+    WHERE annotation.id = annotation_moderation.annotation_id
+    AND annotation.moderation_status  is null
+    """
+        )
+    )
+    print("\tUpdated annotation rows as DENIED:", result.rowcount)  # noqa: T201
+
+    result = conn.execute(
+        sa.text(
+            """
+    UPDATE annotation_slim
+        SET moderation_status = 'DENIED'
+    FROM annotation_moderation
+    WHERE annotation_slim.pubid = annotation_moderation.annotation_id
+    AND annotation_slim.moderation_status is null
+    """
+        )
+    )
+    print("\tUpdated annotations as DENIED:", result.rowcount)  # noqa: T201
+
+
+def downgrade() -> None:
+    pass

h/migrations/versions/bd226cc1c359_create_moderation_log_table.py

@@ -0,0 +1,47 @@
+"""Create moderation log table."""
+
+import sqlalchemy as sa
+from alembic import op
+
+from h.db import types
+
+revision = "bd226cc1c359"
+down_revision = "96cde96b2fd7"
+
+
+def upgrade() -> None:
+    op.create_table(
+        "moderation_log",
+        sa.Column("id", sa.Integer(), autoincrement=True, nullable=False),
+        sa.Column("user_id", sa.Integer(), nullable=False),
+        sa.Column("annotation_id", types.URLSafeUUID(), nullable=False),
+        sa.Column("old_moderation_status", sa.String(), nullable=False),
+        sa.Column("new_moderation_status", sa.String(), nullable=False),
+        sa.Column(
+            "created", sa.DateTime(), server_default=sa.text("now()"), nullable=False
+        ),
+        sa.ForeignKeyConstraint(
+            ["annotation_id"],
+            ["annotation.id"],
+            name=op.f("fk__moderation_log__annotation_id__annotation"),
+            ondelete="CASCADE",
+        ),
+        sa.ForeignKeyConstraint(
+            ["user_id"],
+            ["user.id"],
+            name=op.f("fk__moderation_log__user_id__user"),
+            ondelete="CASCADE",
+        ),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk__moderation_log")),
+    )
+    op.create_index(
+        op.f("ix__moderation_log_annotation_id"),
+        "moderation_log",
+        ["annotation_id"],
+        unique=False,
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("moderation_log")
+    # ### end Alembic commands ###

h/migrations/versions/c8f748cbfb8f_create_the_moderation_status_column.py

@@ -0,0 +1,40 @@
+"""Create the moderation_status column."""
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy.dialects import postgresql
+
+revision = "c8f748cbfb8f"
+down_revision = "cf4eedee60f7"
+
+
+def upgrade() -> None:
+    moderation_status_type = postgresql.ENUM(
+        "APPROVED",
+        "DENIED",
+        "SPAM",
+        "PENDING",
+        name="moderationstatus",
+    )
+    moderation_status_type.create(op.get_bind(), checkfirst=True)
+    op.add_column(
+        "annotation",
+        sa.Column(
+            "moderation_status",
+            moderation_status_type,
+            nullable=True,
+        ),
+    )
+    op.add_column(
+        "annotation_slim",
+        sa.Column(
+            "moderation_status",
+            moderation_status_type,
+            nullable=True,
+        ),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("annotation_slim", "moderation_status")
+    op.drop_column("annotation", "moderation_status")

h/migrations/versions/cf4eedee60f7_add_group_pre_moderated.py

@@ -0,0 +1,15 @@
+"""Add Group.pre_moderated."""
+
+import sqlalchemy as sa
+from alembic import op
+
+revision = "cf4eedee60f7"
+down_revision = "9d97a3e4921e"
+
+
+def upgrade() -> None:
+    op.add_column("group", sa.Column("pre_moderated", sa.Boolean(), nullable=True))
+
+
+def downgrade() -> None:
+    op.drop_column("group", "pre_moderated")

h/models/annotation.py

@@ -1,20 +1,32 @@
 import datetime
+from enum import Enum
 from uuid import UUID
 
 import sqlalchemy as sa
 from sqlalchemy.dialects import postgresql as pg
 from sqlalchemy.ext.hybrid import hybrid_property
 from sqlalchemy.ext.mutable import MutableDict, MutableList
+from sqlalchemy.orm import Mapped, relationship
 
 from h.db import Base, types
 from h.models.group import Group
 from h.util import markdown_render, uri
 from h.util.user import split_user
 
 
+class ModerationStatus(Enum):
+    APPROVED = "APPROVED"
+    PENDING = "PENDING"
+    DENIED = "DENIED"
+    SPAM = "SPAM"
+
+
 class Annotation(Base):
     """Model class representing a single annotation."""
 
+    # Expose the ModerationStatus directly here
+    ModerationStatus = ModerationStatus
+
     __tablename__ = "annotation"
     __table_args__ = (
         # Tags are stored in an array-type column, and indexed using a
@@ -68,7 +80,7 @@ class Annotation(Base):
         index=True,
     )
 
-    group = sa.orm.relationship(
+    group = relationship(
         Group,
         primaryjoin=(Group.pubid == groupid),
         foreign_keys=[groupid],
@@ -138,11 +150,11 @@ class Annotation(Base):
         uselist=True,
     )
 
-    mentions = sa.orm.relationship("Mention", back_populates="annotation")
+    mentions = relationship("Mention", back_populates="annotation")
 
-    notifications = sa.orm.relationship(
-        "Notification", back_populates="source_annotation"
-    )
+    notifications = relationship("Notification", back_populates="source_annotation")
+
+    moderation_status: Mapped[ModerationStatus | None]
 
     @property
     def uuid(self):
@@ -258,8 +270,16 @@ def authority(self):
     @property
     def is_hidden(self):
         """Check if this annotation id is hidden."""
-
+        # TODO, move to the new column after migration and backfill migration
         return self.moderation is not None
 
+    @property
+    def moderated(self):
+        # This replaces is_hidden, adding a new property to give more visibility to the change in the PoC
+        return bool(
+            self.moderation_status
+            and self.moderation_status != ModerationStatus.APPROVED
+        )
+
     def __repr__(self):
         return f"<Annotation {self.id}>"

h/models/annotation_moderation.py

@@ -1,7 +1,31 @@
 import sqlalchemy as sa
+from sqlalchemy import ForeignKey
+from sqlalchemy.orm import (
+    Mapped,
+    MappedAsDataclass,
+    mapped_column,
+    relationship,
+)
 
 from h.db import Base, types
-from h.db.mixins import Timestamps
+from h.db.mixins import CreatedMixin, Timestamps
+from h.db.mixins_dataclasses import AutoincrementingIntegerID
+from h.models.annotation import ModerationStatus
+
+
+class ModerationLog(Base, AutoincrementingIntegerID, CreatedMixin, MappedAsDataclass):
+    __tablename__ = "moderation_log"
+
+    user_id: Mapped[int] = mapped_column(sa.ForeignKey("user.id", ondelete="CASCADE"))
+    user = relationship("User")
+
+    annotation_id: Mapped[types.URLSafeUUID] = mapped_column(
+        ForeignKey("annotation.id", ondelete="CASCADE"), index=True
+    )
+    annotation = relationship("Annotation")
+
+    old_moderation_status: Mapped[ModerationStatus | None] = mapped_column()
+    new_moderation_status: Mapped[ModerationStatus] = mapped_column()
 
 
 class AnnotationModeration(Base, Timestamps):

h/models/annotation_slim.py

@@ -1,9 +1,11 @@
 import datetime
 
 import sqlalchemy as sa
+from sqlalchemy.orm import Mapped, relationship
 
 from h.db import Base, types
 from h.models import helpers
+from h.models.annotation import Annotation
 
 
 class AnnotationSlim(Base):
@@ -31,7 +33,7 @@ class AnnotationSlim(Base):
     )
     """The value of annotation.id, named here pubid following the convention of group.pubid"""
 
-    annotation = sa.orm.relationship(
+    annotation = relationship(
         "Annotation", backref=sa.orm.backref("slim", uselist=False)
     )
 
@@ -64,6 +66,7 @@ class AnnotationSlim(Base):
         default=False,
         server_default=sa.sql.expression.false(),
     )
+    moderation_status: Mapped[Annotation.ModerationStatus | None]
 
     shared = sa.Column(
         sa.Boolean,
@@ -78,26 +81,26 @@ class AnnotationSlim(Base):
         nullable=False,
         index=True,
     )
-    document = sa.orm.relationship("Document")
+    document = relationship("Document")
 
     user_id = sa.Column(
         sa.Integer,
         sa.ForeignKey("user.id", ondelete="CASCADE"),
         nullable=False,
         index=True,
     )
-    user = sa.orm.relationship("User")
+    user = relationship("User")
 
     group_id = sa.Column(
         sa.Integer,
         sa.ForeignKey("group.id", ondelete="CASCADE"),
         nullable=False,
         index=True,
     )
-    group = sa.orm.relationship("Group")
+    group = relationship("Group")
 
     # Using `meta` as `metadata` is reserved by SQLAlchemy
-    meta = sa.orm.relationship("AnnotationMetadata", uselist=False)
+    meta = relationship("AnnotationMetadata", uselist=False)
 
     def __repr__(self):
         return helpers.repr_(self, ["id"])

h/models/group.py

@@ -6,7 +6,7 @@
 import slugify
 import sqlalchemy as sa
 from sqlalchemy.dialects.postgresql import JSONB
-from sqlalchemy.orm import relationship
+from sqlalchemy.orm import Mapped, mapped_column, relationship
 
 from h import pubid
 from h.db import Base, mixins
@@ -157,6 +157,8 @@ class Group(Base, mixins.Timestamps):
         sa.Enum(WriteableBy, name="group_writeable_by"), nullable=True
     )
 
+    pre_moderated: Mapped[bool | None] = mapped_column()
+
     @property
     def groupid(self):
         if self.authority_provided_id is None:

h/presenters/annotation_searchindex.py

@@ -47,7 +47,7 @@ def asdict(self):
     def _add_hidden(self, result):
         # Mark an annotation as hidden if it and all of it's children have been
         # moderated and hidden.
-        parents_and_replies = [self.annotation.id] + self.annotation.thread_ids  # noqa: RUF005
+        parents_and_replies = [self.annotation.id, *self.annotation.thread_ids]
 
         ann_mod_svc = self.request.find_service(name="annotation_moderation")
         is_hidden = len(ann_mod_svc.all_hidden(parents_and_replies)) == len(