feat: Add scheduled task to sync RetroAchievements progress

Add a new scheduled task that syncs RetroAchievements progress for all
users with a RetroAchievements username.

Environment variables:
- `ENABLE_SCHEDULED_RETROACHIEVEMENTS_PROGRESS_SYNC`: Enable or disable
  the task (default: `false`)
- `SCHEDULED_RETROACHIEVEMENTS_PROGRESS_SYNC_CRON`: Cron string to
  schedule the task (default: "0 4 * * *" - daily at 4 AM)

backend/handler/database/users_handler.py

@@ -2,13 +2,40 @@ from collections.abc import Sequence
 
 from decorators.database import begin_session
 from models.user import Role, User
-from sqlalchemy import delete, func, select, update
+from sqlalchemy import and_, delete, func, not_, select, update
 from sqlalchemy.orm import Session
+from sqlalchemy.sql import Delete, Select, Update
 
 from .base_handler import DBBaseHandler
 
 
 class DBUsersHandler(DBBaseHandler):
+    def filter[QueryT: Select[tuple[User]] | Update | Delete](
+        self,
+        query: QueryT,
+        *,
+        usernames: Sequence[str] = (),
+        emails: Sequence[str] = (),
+        roles: Sequence[Role] = (),
+        has_ra_username: bool | None = None,
+    ) -> QueryT:
+        if usernames:
+            query = query.filter(
+                func.lower(User.username).in_([u.lower() for u in usernames])
+            )
+        if emails:
+            query = query.filter(
+                func.lower(User.email).in_([e.lower() for e in emails])
+            )
+        if roles:
+            query = query.filter(User.role.in_(roles))
+        if has_ra_username is not None:
+            predicate = and_(User.ra_username != "", User.ra_username.isnot(None))
+            if not has_ra_username:
+                predicate = not_(predicate)
+            query = query.filter(predicate)
+        return query
+
     @begin_session
     def add_user(self, user: User, session: Session = None) -> User:
         return session.merge(user)
@@ -17,15 +44,13 @@ class DBUsersHandler(DBBaseHandler):
     def get_user_by_username(
         self, username: str, session: Session = None
     ) -> User | None:
-        return session.scalar(
-            select(User).filter(func.lower(User.username) == username.lower()).limit(1)
-        )
+        query = self.filter(select(User), usernames=[username])
+        return session.scalar(query.limit(1))
 
     @begin_session
     def get_user_by_email(self, email: str, session: Session = None) -> User | None:
-        return session.scalar(
-            select(User).filter(func.lower(User.email) == email.lower()).limit(1)
-        )
+        query = self.filter(select(User), emails=[email])
+        return session.scalar(query.limit(1))
 
     @begin_session
     def get_user(self, id: int, session: Session = None) -> User | None:
@@ -42,8 +67,23 @@ class DBUsersHandler(DBBaseHandler):
         return session.query(User).filter_by(id=id).one()
 
     @begin_session
-    def get_users(self, session: Session = None) -> Sequence[User]:
-        return session.scalars(select(User)).all()
+    def get_users(
+        self,
+        *,
+        usernames: Sequence[str] = (),
+        emails: Sequence[str] = (),
+        roles: Sequence[Role] = (),
+        has_ra_username: bool | None = None,
+        session: Session = None,
+    ) -> Sequence[User]:
+        query = self.filter(
+            select(User),
+            usernames=usernames,
+            emails=emails,
+            roles=roles,
+            has_ra_username=has_ra_username,
+        )
+        return session.scalars(query).all()
 
     @begin_session
     def delete_user(self, id: int, session: Session = None):
@@ -55,4 +95,5 @@ class DBUsersHandler(DBBaseHandler):
 
     @begin_session
     def get_admin_users(self, session: Session = None) -> Sequence[User]:
-        return session.scalars(select(User).filter_by(role=Role.ADMIN)).all()
+        query = self.filter(select(User), roles=[Role.ADMIN])
+        return session.scalars(query).all()