Skip to content

armgit / mwmbl

Public Imported from GitHub
0

An open source, non-profit web search engine

Notify volunteers when they're granted a membership

Claude43ae0a40bb14
diff --git a/mwmbl/admin.py b/mwmbl/admin.py
index 9ec5eb5..5433273 100644
--- a/mwmbl/admin.py
+++ b/mwmbl/admin.py
@@ -13,9 +13,12 @@ from mwmbl.models import (
MwmblUser,
OldIndex,
UserBilling,
+ UserNotification,
VolunteerMembership,
generate_api_key,
)
+from mwmbl.utils import utc_today
+from mwmbl.volunteer_membership import notify_volunteer_membership_granted
class ApiKeyForm(forms.ModelForm):
@@ -103,9 +106,27 @@ class VolunteerMembershipAdmin(ModelAdmin):
readonly_fields = ("started",)
search_fields = ("user__username", "user__email")
+ def save_model(self, request, obj, form, change):
+ # Notify a gift, or the revival of a lapsed membership, but not an edit to a current one.
+ today = utc_today()
+ granted = obj.valid_until >= today and (not change or form.initial["valid_until"] < today)
+ super().save_model(request, obj, form, change)
+ if granted:
+ notify_volunteer_membership_granted(obj.user_id, obj.tier, obj.valid_until)
+
admin.site.register(VolunteerMembership, VolunteerMembershipAdmin)
+
+class UserNotificationAdmin(ModelAdmin):
+ list_display = ("user", "kind", "created", "dismissed_at")
+ list_filter = ("kind",)
+ readonly_fields = ("created",)
+ search_fields = ("user__username", "user__email")
+
+
+admin.site.register(UserNotification, UserNotificationAdmin)
+
# Adds the "Status" panel linking to the blacklist status page (mwmbl.admin_views) to the
# admin front page.
admin.site.index_template = "admin/mwmbl_index.html"
diff --git a/mwmbl/api.py b/mwmbl/api.py
index 1e3787e..815e4e1 100644
--- a/mwmbl/api.py
+++ b/mwmbl/api.py
@@ -14,6 +14,7 @@ Sub-routers (v2):
/api/v2/super-search/ — multi-source streaming search (SSE), authenticated
/api/v2/combined-search/ — Mwmbl + EUSP + Wikipedia in one ranked response, authenticated
/api/v2/membership/ — paid and volunteer memberships and Seed Search usage, authenticated
+ /api/v2/notifications/ — the user's undismissed notifications, authenticated
JWT token endpoints (from NinjaJWTDefaultController) are registered on v1,
typically at /api/v1/platform/token/pair, /api/v1/platform/token/refresh, etc.
@@ -175,6 +176,7 @@ v2_api = NinjaExtraAPI(
{"name": "Search"},
{"name": "Super Search"},
{"name": "Membership"},
+ {"name": "Notifications"},
]
},
)
@@ -204,6 +206,7 @@ def register_routers(ranker, combined_ranker, tiny_index):
import mwmbl.tinysearchengine.super_search as super_search_module
from mwmbl.platform.api import router as platform_router
from mwmbl.platform.membership_v2 import router as membership_v2_router
+ from mwmbl.platform.notifications import router as notifications_router
# Initialise routers that depend on runtime objects
search_module.init_router(ranker, tiny_index)
@@ -220,3 +223,4 @@ def register_routers(ranker, combined_ranker, tiny_index):
v2_api.add_router("/super-search/", super_search_module.router, tags=["Super Search"])
v2_api.add_router("/combined-search/", combined_search_module.router, tags=["Combined Search"])
v2_api.add_router("/membership/", membership_v2_router, tags=["Membership"])
+ v2_api.add_router("/notifications/", notifications_router, tags=["Notifications"])
diff --git a/mwmbl/migrations/0046_usernotification.py b/mwmbl/migrations/0046_usernotification.py
new file mode 100644
index 0000000..cb22756
--- /dev/null
+++ b/mwmbl/migrations/0046_usernotification.py
@@ -0,0 +1,38 @@
+import django.db.models.deletion
+from django.conf import settings
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+ dependencies = [
+ ("mwmbl", "0045_volunteermembership"),
+ ]
+
+ operations = [
+ migrations.CreateModel(
+ name="UserNotification",
+ fields=[
+ ("id", models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name="ID")),
+ (
+ "kind",
+ models.CharField(
+ choices=[("volunteer_membership_granted", "Volunteer membership granted")], max_length=40
+ ),
+ ),
+ ("data", models.JSONField(default=dict)),
+ ("created", models.DateTimeField(auto_now_add=True)),
+ ("dismissed_at", models.DateTimeField(blank=True, null=True)),
+ (
+ "user",
+ models.ForeignKey(
+ on_delete=django.db.models.deletion.CASCADE,
+ related_name="notifications",
+ to=settings.AUTH_USER_MODEL,
+ ),
+ ),
+ ],
+ options={
+ "indexes": [models.Index(fields=["user", "dismissed_at"], name="mwmbl_usern_user_id_980c84_idx")],
+ },
+ ),
+ ]
diff --git a/mwmbl/models.py b/mwmbl/models.py
index a1ea47c..8b90be1 100644
--- a/mwmbl/models.py
+++ b/mwmbl/models.py
@@ -286,6 +286,26 @@ class VolunteerMembership(models.Model):
unique_together = [("user", "tier")]
+class NotificationKind(models.TextChoices):
+ VOLUNTEER_MEMBERSHIP_GRANTED = "volunteer_membership_granted", "Volunteer membership granted"
+
+
+class UserNotification(models.Model):
+ """A message for a user that stays until they dismiss it, such as being granted a volunteer membership.
+
+ What a notification says is up to the front end: data holds the details it needs for each kind.
+ """
+
+ user = models.ForeignKey(MwmblUser, on_delete=models.CASCADE, related_name="notifications")
+ kind = models.CharField(max_length=40, choices=NotificationKind.choices)
+ data = models.JSONField(default=dict)
+ created = models.DateTimeField(auto_now_add=True)
+ dismissed_at = models.DateTimeField(null=True, blank=True)
+
+ class Meta:
+ indexes = [models.Index(fields=["user", "dismissed_at"])]
+
+
class AgreementType(models.TextChoices):
TERMS_OF_SERVICE_GUI = "TERMS_OF_SERVICE_GUI", "Terms of Service (GUI)"
TERMS_OF_SERVICE_API = "TERMS_OF_SERVICE_API", "Terms of Service (API)"
diff --git a/mwmbl/platform/notifications.py b/mwmbl/platform/notifications.py
new file mode 100644
index 0000000..a4d30d3
--- /dev/null
+++ b/mwmbl/platform/notifications.py
@@ -0,0 +1,38 @@
+"""v2 notification endpoints: messages a user sees until they dismiss them."""
+
+from django.utils import timezone
+from ninja import Router
+from ninja_jwt.authentication import JWTAuth
+
+from mwmbl.exceptions import InvalidRequest
+from mwmbl.models import UserNotification
+from mwmbl.platform.schemas import UserNotificationResponse
+
+router = Router(tags=["Notifications"])
+
+
+ "/",
+ auth=JWTAuth(),
+ response=list[UserNotificationResponse],
+ summary="List notifications",
+ description="Returns the user's notifications that they haven't dismissed, oldest first.",
+)
+def list_notifications(request):
+ return UserNotification.objects.filter(user=request.user, dismissed_at__isnull=True).order_by("created")
+
+
+ "/{notification_id}/dismiss",
+ auth=JWTAuth(),
+ response={204: None},
+ summary="Dismiss a notification",
+ description="Marks one of the user's notifications as dismissed, so it is no longer listed. Dismissing a "
+ "notification that is already dismissed does nothing.",
+)
+def dismiss_notification(request, notification_id: int):
+ notifications = UserNotification.objects.filter(user=request.user, id=notification_id)
+ if not notifications.exists():
+ raise InvalidRequest("Notification not found.", status=404)
+ notifications.filter(dismissed_at__isnull=True).update(dismissed_at=timezone.now())
+ return 204, None
diff --git a/mwmbl/platform/schemas.py b/mwmbl/platform/schemas.py
index 772dee6..575d05f 100644
--- a/mwmbl/platform/schemas.py
+++ b/mwmbl/platform/schemas.py
@@ -5,7 +5,7 @@ from ninja import Field, ModelSchema, Schema
from pydantic import model_validator
from mwmbl.membership import MembershipTier, VolunteerTier
-from mwmbl.models import AgreementType, DomainSubmission, MarketingSource
+from mwmbl.models import AgreementType, DomainSubmission, MarketingSource, NotificationKind
class UserProfileResponse(Schema):
@@ -99,6 +99,14 @@ class MembershipTiersV2Response(Schema):
volunteer: list[VolunteerTierResponse]
+class UserNotificationResponse(Schema):
+ id: int
+ kind: NotificationKind
+ # Depends on kind: volunteer_membership_granted has tier and valid_until.
+ data: dict
+ created: datetime
+
+
class CombinedSearchPreference(Schema):
enabled: bool
diff --git a/mwmbl/volunteer_membership.py b/mwmbl/volunteer_membership.py
index 8ccc53e..83e9d8a 100644
--- a/mwmbl/volunteer_membership.py
+++ b/mwmbl/volunteer_membership.py
@@ -4,7 +4,14 @@ import calendar
from datetime import date
from mwmbl.membership import VOLUNTEER_TIERS, combined_search_monthly_limit
-from mwmbl.models import Membership, MwmblUser, UserStats, VolunteerMembership
+from mwmbl.models import (
+ Membership,
+ MwmblUser,
+ NotificationKind,
+ UserNotification,
+ UserStats,
+ VolunteerMembership,
+)
from mwmbl.utils import utc_today
TIER_RANK = {info.tier.value: rank for rank, info in enumerate(VOLUNTEER_TIERS)}
@@ -21,7 +28,8 @@ def update_volunteer_memberships(user: MwmblUser, today: date) -> None:
Called after every batch of results, so a tier starts the moment the user reaches its
threshold, and a grant that failed is retried on their next batch. Once this month has earned
every tier, it costs one query. A grant never shortens a membership, so a longer one set by
- hand in the admin survives.
+ hand in the admin survives. The user is notified when a tier is granted afresh, not when it's
+ extended.
"""
valid_until = end_of_next_month(today)
extended = set(
@@ -43,10 +51,28 @@ def update_volunteer_memberships(user: MwmblUser, today: date) -> None:
_, created = VolunteerMembership.objects.get_or_create(
user=user, tier=info.tier, defaults={"valid_until": valid_until}
)
- if not created:
- VolunteerMembership.objects.filter(user=user, tier=info.tier, valid_until__lt=valid_until).update(
- valid_until=valid_until
- )
+ if created:
+ notify_volunteer_membership_granted(user.id, info.tier, valid_until)
+ continue
+ # Reviving a lapsed membership is a fresh grant, so it's notified; extending a current one isn't.
+ # Each update is a single statement, so concurrent batches can't both revive it.
+ revived = VolunteerMembership.objects.filter(user=user, tier=info.tier, valid_until__lt=today).update(
+ valid_until=valid_until
+ )
+ if revived:
+ notify_volunteer_membership_granted(user.id, info.tier, valid_until)
+ continue
+ VolunteerMembership.objects.filter(user=user, tier=info.tier, valid_until__lt=valid_until).update(
+ valid_until=valid_until
+ )
+
+
+def notify_volunteer_membership_granted(user_id: int, tier: str, valid_until: date) -> None:
+ UserNotification.objects.create(
+ user_id=user_id,
+ kind=NotificationKind.VOLUNTEER_MEMBERSHIP_GRANTED,
+ data={"tier": tier, "valid_until": valid_until.isoformat()},
+ )
def current_volunteer_memberships(user_ids) -> dict[int, VolunteerMembership]:
diff --git a/test/test_openapi.py b/test/test_openapi.py
index 216957e..8108b62 100644
--- a/test/test_openapi.py
+++ b/test/test_openapi.py
@@ -213,6 +213,8 @@ def test_v2_openapi_spec_generation():
"/api/v2/combined-search/seed-domains",
"/api/v2/membership/",
"/api/v2/membership/tiers",
+ "/api/v2/notifications/",
+ "/api/v2/notifications/{notification_id}/dismiss",
}
diff --git a/test/test_user_notifications.py b/test/test_user_notifications.py
new file mode 100644
index 0000000..f893776
--- /dev/null
+++ b/test/test_user_notifications.py
@@ -0,0 +1,159 @@
+"""Tests for notifying volunteers of membership grants, and for listing and dismissing notifications."""
+
+from datetime import date
+from types import SimpleNamespace
+from unittest.mock import patch
+
+import fakeredis
+import pytest
+from django.contrib.admin.sites import AdminSite
+from django.test import Client
+from ninja_jwt.tokens import RefreshToken
+
+from mwmbl.admin import VolunteerMembershipAdmin
+from mwmbl.crawler.stats import StatsManager
+from mwmbl.membership import VolunteerTier
+from mwmbl.models import MwmblUser, NotificationKind, UserNotification, VolunteerMembership
+
+TODAY = date(2026, 10, 17)
+POLLINATOR = VolunteerTier.POLLINATOR
+GRANTED = NotificationKind.VOLUNTEER_MEMBERSHIP_GRANTED
+
+
+def user(db):
+ return MwmblUser.objects.create_user(username="crawler", email="[email protected]", password="testpass123")
+
+
+def _crawl(user, day: date) -> None:
+ results = SimpleNamespace(results=[object()] * 100)
+ with patch("mwmbl.crawler.stats.utc_today", return_value=day):
+ StatsManager(fakeredis.FakeRedis()).record_results(results, user)
+
+
+def _crawl_three_days(user, year: int, month: int) -> None:
+ for day in (1, 2, 3):
+ _crawl(user, date(year, month, day))
+
+
+def _notification_data(user) -> list[dict]:
+ return list(UserNotification.objects.filter(user=user, kind=GRANTED).order_by("id").values_list("data", flat=True))
+
+
+def auth_headers(user):
+ return {"HTTP_AUTHORIZATION": f"Bearer {RefreshToken.for_user(user).access_token}"}
+
+
+def test_earning_a_tier_notifies_the_user(user):
+ _crawl_three_days(user, 2026, 10)
+
+ assert _notification_data(user) == [{"tier": "pollinator", "valid_until": "2026-11-30"}]
+
+
+def test_crawling_after_earning_a_tier_does_not_notify_again(user):
+ _crawl_three_days(user, 2026, 10)
+ _crawl(user, date(2026, 10, 4))
+
+ assert len(_notification_data(user)) == 1
+
+
+def test_extending_a_current_membership_does_not_notify(user):
+ _crawl_three_days(user, 2026, 10)
+ _crawl_three_days(user, 2026, 11)
+
+ assert len(_notification_data(user)) == 1
+
+
+def test_earning_a_lapsed_membership_again_notifies(user):
+ _crawl_three_days(user, 2026, 10)
+ _crawl_three_days(user, 2027, 1)
+
+ assert _notification_data(user)[1] == {"tier": "pollinator", "valid_until": "2027-02-28"}
+
+
+def _save_in_admin(volunteer_membership, change: bool, initial_valid_until: date | None = None) -> None:
+ form = SimpleNamespace(initial={"valid_until": initial_valid_until} if change else {})
+ with patch("mwmbl.admin.utc_today", return_value=TODAY):
+ VolunteerMembershipAdmin(VolunteerMembership, AdminSite()).save_model(None, volunteer_membership, form, change)
+
+
+def test_a_membership_gifted_in_the_admin_notifies(user):
+ _save_in_admin(VolunteerMembership(user=user, tier=POLLINATOR, valid_until=date(2027, 6, 30)), change=False)
+
+ assert _notification_data(user) == [{"tier": "pollinator", "valid_until": "2027-06-30"}]
+
+
+ "initial_valid_until, valid_until, notified",
+ [
+ (date(2026, 9, 30), date(2027, 6, 30), True),
+ (date(2026, 11, 30), date(2027, 6, 30), False),
+ (date(2026, 9, 30), date(2026, 10, 1), False),
+ ],
+ ids=["reviving a lapsed one", "extending a current one", "editing a lapsed one that stays lapsed"],
+)
+def test_editing_a_membership_in_the_admin(user, initial_valid_until, valid_until, notified):
+ volunteer_membership = VolunteerMembership.objects.create(
+ user=user, tier=POLLINATOR, valid_until=initial_valid_until
+ )
+ volunteer_membership.valid_until = valid_until
+
+ _save_in_admin(volunteer_membership, change=True, initial_valid_until=initial_valid_until)
+
+ assert bool(_notification_data(user)) == notified
+
+
+def test_list_notifications(user):
+ _crawl_three_days(user, 2026, 10)
+
+ response = Client().get("/api/v2/notifications/", **auth_headers(user))
+
+ assert response.status_code == 200
+ [notification] = response.json()
+ assert notification["kind"] == "volunteer_membership_granted"
+ assert notification["data"] == {"tier": "pollinator", "valid_until": "2026-11-30"}
+
+
+def test_dismissed_notifications_are_not_listed(user):
+ _crawl_three_days(user, 2026, 10)
+ notification = UserNotification.objects.get(user=user)
+
+ response = Client().post(f"/api/v2/notifications/{notification.id}/dismiss", **auth_headers(user))
+
+ assert response.status_code == 204
+ notification.refresh_from_db()
+ assert notification.dismissed_at is not None
+ assert Client().get("/api/v2/notifications/", **auth_headers(user)).json() == []
+
+
+def test_dismissing_twice_keeps_the_first_dismissal(user):
+ _crawl_three_days(user, 2026, 10)
+ notification = UserNotification.objects.get(user=user)
+ url = f"/api/v2/notifications/{notification.id}/dismiss"
+ Client().post(url, **auth_headers(user))
+ notification.refresh_from_db()
+ first_dismissed_at = notification.dismissed_at
+
+ response = Client().post(url, **auth_headers(user))
+
+ assert response.status_code == 204
+ notification.refresh_from_db()
+ assert notification.dismissed_at == first_dismissed_at
+
+
+def test_users_cannot_see_or_dismiss_each_others_notifications(user):
+ _crawl_three_days(user, 2026, 10)
+ notification = UserNotification.objects.get(user=user)
+ other = MwmblUser.objects.create_user(username="other", email="[email protected]", password="testpass123")
+
+ assert Client().get("/api/v2/notifications/", **auth_headers(other)).json() == []
+ response = Client().post(f"/api/v2/notifications/{notification.id}/dismiss", **auth_headers(other))
+
+ assert response.status_code == 404
+ notification.refresh_from_db()
+ assert notification.dismissed_at is None
+
+
+def test_notifications_require_login(db):
+ assert Client().get("/api/v2/notifications/").status_code == 401
+ assert Client().post("/api/v2/notifications/1/dismiss").status_code == 401