Notifications

.github/workflows/tests.yml

@@ -47,4 +47,5 @@ jobs:
           coveralls
       - name: Linters
         run: |
-          black --check .
+          black --check .
+          ruff misago/notifications misago/apiv2

dev-docs/index.md

@@ -0,0 +1,12 @@
+# Misago Developer Reference
+
+This directory contains reference documents for Misago developers.
+
+> **Note:** This documentation is a temporary solution. In future I aim to generate Misago's dev documentation from it's codebase.
+
+
+## Notifications
+
+Misago's notifications feature is implemented in the `misago.notifications` package.
+
+- [Notifications guide](./notifications.md)

dev-docs/notifications.md

@@ -0,0 +1,187 @@
+# Notifications guide
+
+Misago's notifications feature is implemented in the `misago.notifications` package.
+
+
+## Notification model
+
+In Misago notifications are represented as instances of `misago.notifications.models.Notification` Django model.
+
+This model has following fields:
+
+- `id`: an `int` with primary key.
+- `user`: an foreign key to `misago.users.models.User`.
+- `verb`: a `str` with this notification's type. Max 32 characters.
+- `is_read`: a `bool` marking this notification as read or unread. Defaults to `False` (unread).
+- `actor`: an foreign key to `misago.users.models.User`, nullable.
+- `actor_name`: a `str` with actor username, nullable. Max 255 characters.
+- `category`: an foreign key to `misago.categories.models.Category`, nullable.
+- `thread`: an foreign key to `misago.threads.models.Thread`, nullable.
+- `thread_title`: a `str` with thread title, nullable. Max 255 characters.
+- `post`: an foreign key to `misago.threads.models.Post`, nullable.
+- `created_at`: `datetime` of notification's creation.
+
+
+## Notifying users
+
+To notify user about an event, use `notify_user` function from `misago.notifications.users`:
+
+```python
+def notify_user(
+    user: "User",
+    verb: str,
+    actor: Optional["User"] = None,
+    category: Optional[Category] = None,
+    thread: Optional[Thread] = None,
+    post: Optional[Post] = None,
+) -> Notification:
+    ...
+```
+
+This function performs two tasks:
+
+- It saves new `misago.notifications.models.Notification` instance to database.
+- It increases `user.unread_notifications` attribute in database.
+
+It takes two required arguments:
+
+- `user`: an instance of `misago.users.models.User` representing user to notify.
+- `verb`: a `str` with notification's "verb", eg. `REPLIED`, `FOLLOWED`.
+
+It optionally takes following arguments:
+
+- `actor`: an instance of `misago.users.models.User` representing user who caused the event.
+- `category`: an instance of `misago.categories.models.Categry` representing category in which the event has occurred.
+- `thread`: an instance of `misago.threads.models.Thread` representing thread in which the event has occurred.
+- `post`: an instance of `misago.threads.models.Post` representing post in which the event has occurred.
+
+Example `notify_user` call executed by Misago to notify an user watching a thread about new reply looks like this:
+
+```python
+notify_user(
+    watched_thread.user,
+    "REPLIED",
+    actor=reply.poster,
+    category=reply.category,
+    thread=reply.thread,
+    post=reply,
+) 
+```
+
+
+## Adding custom notification
+
+Misago supports adding custom notifications for new events.
+
+
+### Notification verb
+
+Each notification type is a "verb", a `str` representing the action (or event) that caused this notification.
+
+Standard verbs used by Misago are defined on `misago.notifications.verbs.NotificationVerb` enumerable.
+
+There's also special `TEST` verb thats not defined on `NotificationVerb` but is still supported for testing purposes.
+
+Custom verbs can be any Python string not longer than 32 characters. To reduce the risk of your custom verb conflicting with other plugin or future Misago release I recommend prefixing it with name of your plugin, eg. `USER_VOTES_VOTED`.
+
+Once you've decided on verb for your notification, you will be able to implement message and redirect url for it.
+
+
+### Notification registry
+
+Misago uses factory functions to retrieve notifications messages and redirect urls.
+
+Those factory functions are registered in special registry, importable as `registry` from `misago.notifications.registry` module.
+
+
+### Notification message
+
+Factory function for notification's message is called with single argument, `Notification` instance, and returns **escaped** `str` with HTML for notification message:
+
+```python
+def get_verb_notification_message(notification: Notification) -> str:
+    return html.escape(f"Test notification #{notification.id}")
+```
+
+> **Note:** For performance reasons foreign key fields on `Notification` model are not populated when notifications list is retrieved.
+> 
+> Use `notification.actor_name` field to retrieve actor's name and `notification.thread_title` field to retrieve thread's title.
+
+To register custom function as message factory for verb, use `registry`'s `message` method:
+
+```python
+import html
+
+from misago.notifications.registry import Notification, registry
+
+
+# `message` works as decorator
+@registry.message("CUSTOM")
+def get_custom_notification_message(notification: Notification) -> str:
+    return html.escape(f"Custom notification in {notification.thread_title}")
+
+
+# And as setter
+def get_custom_notification_message(notification: Notification) -> str:
+    return html.escape(f"Custom notification in {notification.thread_title}")
+
+
+registry.message("CUSTOM", get_custom_notification_message)
+```
+
+
+### Notification redirect url
+
+Factory function for notification's redirect url is called with two arguments, Django's `HttpRequest` instance and the `Notification` instance, and retuurns `str` with URL to which user should be redirected to see notification's source:
+
+```python
+def get_verb_notification_redirect_url(request: HttpRequest, notification: Notification) -> str:
+    return reverse(
+        "my-plugin:some-url",
+        kwargs={
+            "id": notification.thread.id,
+            "slug": notification.thread.slug,
+        },
+    )
+```
+
+> **Note:** Foreign key fields on `Notification` model are populated with related objects when notification redirect url is retrieved.
+
+
+To register custom function as redirect url factory for verb, use `registry`'s `redirect` method:
+
+```python
+from django.http import HttpRequest
+from django.urls import reverse
+from misago.notifications.registry import Notification, registry
+
+
+# `redirect` works as decorator
+@registry.redirect("CUSTOM")
+def get_custom_notification_redirect_url(
+    request: HttpRequest, notification: Notification
+) -> str:
+    return reverse(
+        "my-plugin:some-url",
+        kwargs={
+            "id": notification.thread.id,
+            "slug": notification.thread.slug,
+        },
+    )
+
+
+# And as setter
+def get_custom_notification_redirect_url(
+    request: HttpRequest, notification: Notification
+) -> str:
+    return reverse(
+        "my-plugin:some-url",
+        kwargs={
+            "id": notification.thread.id,
+            "slug": notification.thread.slug,
+        },
+    )
+
+
+registry.redirect("CUSTOM", get_custom_notification_redirect_url)
+```

devproject/settings.py

@@ -194,6 +194,7 @@
     "misago.themes",
     "misago.markup",
     "misago.legal",
+    "misago.notifications",
     "misago.categories",
     "misago.threads",
     "misago.readtracker",
@@ -204,6 +205,7 @@
     "misago.faker",
     "misago.menus",
     "misago.plugins",
+    "misago.apiv2",
 ]
 
 INTERNAL_IPS = ["127.0.0.1"]
@@ -305,6 +307,7 @@
                 "misago.markup.context_processors.preload_api_url",
                 "misago.threads.context_processors.preload_threads_urls",
                 "misago.users.context_processors.preload_user_json",
+                "misago.categories.context_processors.preload_categories_json",
                 "misago.socialauth.context_processors.preload_socialauth_json",
                 # Note: keep frontend_context processor last for previous processors
                 # to be able to expose data UI app via request.frontend_context

devproject/test_settings.py

@@ -3,16 +3,19 @@
 # Use in-memory cache
 CACHES = {"default": {"BACKEND": "django.core.cache.backends.dummy.DummyCache"}}
 
+# Disable Celery backend
+CELERY_BROKER_URL = None
+
 # Disable Debug Toolbar
 DEBUG_TOOLBAR_CONFIG = {}
 INTERNAL_IPS = []
 
-# Disable account validation via Stop Forum Spam
-MISAGO_NEW_REGISTRATIONS_VALIDATORS = ("misago.users.validators.validate_gmail_email",)
-
 # Store mails in memory
 EMAIL_BACKEND = "django.core.mail.backends.locmem.EmailBackend"
 
+# Disable account validation via Stop Forum Spam
+MISAGO_NEW_REGISTRATIONS_VALIDATORS = ("misago.users.validators.validate_gmail_email",)
+
 # Use MD5 password hashing to speed up test suite
 PASSWORD_HASHERS = ("django.contrib.auth.hashers.MD5PasswordHasher",)
 

frontend/src/components/Api/ApiFetch.jsx

@@ -0,0 +1,116 @@
+import React from "react"
+
+export default class ApiFetch extends React.Component {
+  constructor(props) {
+    super(props)
+
+    this.state = {
+      data: null,
+      loading: false,
+      error: null,
+    }
+
+    this.controller = new AbortController()
+    this.signal = this.controller.signal
+  }
+
+  componentDidMount() {
+    if (this.props.url && !this.props.disabled) {
+      this.request(this.props.url)
+    }
+  }
+
+  componentDidUpdate(prevProps) {
+    const url = this.props.url
+    const urlChanged = url && url !== prevProps.url
+    const disabledChanged = this.props.disabled != prevProps.disabled
+
+    if (urlChanged || disabledChanged) {
+      if (!this.props.disabled) {
+        if (this.hasCache(url)) {
+          this.getCache(url)
+        } else {
+          this.controller.abort()
+
+          this.controller = new AbortController()
+          this.signal = this.controller.signal
+          this.request(url)
+        }
+      } else {
+        this.controller.abort()
+      }
+    }
+  }
+
+  componentWillUnmount() {
+    this.controller.abort()
+  }
+
+  hasCache = (url) => {
+    return this.props.cache && this.props.cache[url]
+  }
+
+  getCache = async (url) => {
+    const data = this.props.cache[url]
+    this.setState({ loading: false, error: null, data })
+    if (this.props.onData) {
+      await this.props.onData(data)
+    }
+  }
+
+  setCache = (url, data) => {
+    if (this.props.cache) {
+      this.props.cache[url] = data
+    }
+  }
+
+  request = (url) => {
+    this.setState({ loading: true })
+
+    fetch(url, {
+      method: "GET",
+      credentials: "include",
+      signal: this.signal,
+    }).then(
+      async (response) => {
+        if (url === this.props.url) {
+          if (response.status == 200) {
+            const data = await response.json()
+            this.setState({ loading: false, error: null, data })
+            this.setCache(url, data)
+            if (this.props.onData) {
+              await this.props.onData(data)
+            }
+          } else {
+            const error = { status: response.status }
+            if (response.headers.get("Content-Type") === "application/json") {
+              error.data = await response.json()
+            }
+            this.setState({ loading: false, error })
+          }
+        }
+      },
+      (rejection) => {
+        if (url === this.props.url) {
+          this.setState({ loading: false, error: { status: 0, rejection } })
+        }
+      }
+    )
+  }
+
+  refetch = () => {
+    this.request(this.props.url)
+  }
+
+  update = (mutation) => {
+    this.setState((state) => {
+      return { data: mutation(state.data) }
+    })
+  }
+
+  render() {
+    return this.props.children(
+      Object.assign({ refetch: this.refetch, update: this.update }, this.state)
+    )
+  }
+}