snapshot of https://github.com/zulip/zulip.git @ 48c69911c7dd4e03b20552eb3bd77ad8151c1357 (2026-09-15)

zerver/models/presence.py

@@ -0,0 +1,114 @@
+from django.db import models
+from django.db.models import CASCADE
+from django.utils.timezone import now as timezone_now
+
+from zerver.models.clients import Client
+from zerver.models.messages import AbstractEmoji
+from zerver.models.realms import Realm
+from zerver.models.users import UserProfile
+
+
+class UserPresence(models.Model):
+    """A record from the last time we heard from a given user on a given client.
+
+    This is the core table for Zulip's presence API, which consists of two components:
+    1) The update-presence endpoint, which is used for clients to update their presence
+       status and fetch latest presence data the whole realm:
+       https://zulip.com/api/update-presence
+    2) The events system is used to send limited immediate updates when
+       a user comes back online: https://zulip.com/api/get-events#presence
+
+    NOTE: Users can disable updates to this table (see UserProfile.presence_enabled),
+    so this cannot be used to determine if a user was recently active on Zulip.
+    The UserActivity table is recommended for that purpose.
+    """
+
+    user_profile = models.OneToOneField(UserProfile, on_delete=CASCADE, unique=True)
+
+    # Realm is just here as denormalization to optimize database
+    # queries to fetch all presence data for a given realm.
+    realm = models.ForeignKey(Realm, on_delete=CASCADE)
+
+    # The sequence ID within this realm for the last update to this user's presence;
+    # these IDs are generated by the PresenceSequence table and an important part
+    # of how we send incremental presence updates efficiently.
+    # To put it simply, every time we update a UserPresence row in a realm,
+    # the row gets last_update_id equal to 1 more than the previously updated
+    # row in that realm.
+    # This allows us to order UserPresence rows by when they were last updated.
+    # The API side of this functionality is documented at:
+    # https://zulip.com/api/update-presence#parameter-last_update_id
+    last_update_id = models.PositiveBigIntegerField(db_index=True, default=0)
+
+    # The last time the user had a client connected to Zulip,
+    # including idle clients where the user hasn't interacted with the
+    # system recently (and thus might be AFK).
+    last_connected_time = models.DateTimeField(default=timezone_now, db_index=True, null=True)
+    # The last time a client connected to Zulip reported that the user
+    # was actually present (E.g. via focusing a browser window or
+    # interacting with a computer running the desktop app)
+    last_active_time = models.DateTimeField(default=timezone_now, db_index=True, null=True)
+
+    # The following constants are used in the presence API for
+    # communicating whether a user is active (last_active_time recent)
+    # or idle (last_connected_time recent) or offline (neither
+    # recent).  They're no longer part of the data model.
+    LEGACY_STATUS_ACTIVE = "active"
+    LEGACY_STATUS_IDLE = "idle"
+    LEGACY_STATUS_ACTIVE_INT = 1
+    LEGACY_STATUS_IDLE_INT = 2
+
+    class Meta:
+        indexes = [
+            models.Index(
+                fields=["realm", "last_active_time"],
+                name="zerver_userpresence_realm_id_last_active_time_1c5aa9a2_idx",
+            ),
+            models.Index(
+                fields=["realm", "last_connected_time"],
+                name="zerver_userpresence_realm_id_last_connected_time_98d2fc9f_idx",
+            ),
+            models.Index(
+                fields=["realm", "last_update_id"],
+                name="zerver_userpresence_realm_last_update_id_idx",
+            ),
+        ]
+
+    @staticmethod
+    def status_from_string(status: str) -> int | None:
+        if status == "active":
+            return UserPresence.LEGACY_STATUS_ACTIVE_INT
+        elif status == "idle":
+            return UserPresence.LEGACY_STATUS_IDLE_INT
+
+        return None
+
+
+class PresenceSequence(models.Model):
+    """
+    This table is used to generate last_update_id values in the UserPresence table.
+
+    It serves as a per-realm sequence generator, while also facilitating
+    locking to avoid concurrency issues with setting last_update_id values.
+
+    Every realm has its unique row in this table, and when a UserPresence in the realm
+    is being updated, this row get locked against other UserPresence updates in the realm
+    to ensure sequential processing and set last_update_id values correctly.
+    """
+
+    realm = models.OneToOneField(Realm, on_delete=CASCADE)
+    last_update_id = models.PositiveBigIntegerField()
+
+
+class UserStatus(AbstractEmoji):
+    user_profile = models.OneToOneField(UserProfile, on_delete=CASCADE)
+
+    timestamp = models.DateTimeField()
+    client = models.ForeignKey(Client, on_delete=CASCADE)
+
+    # Override emoji_name and emoji_code field of (AbstractReaction model) to accept
+    # default value.
+    emoji_name = models.TextField(default="")
+    emoji_code = models.TextField(default="")
+
+    status_text = models.CharField(max_length=255, default="")