[AIT-316] feat: annotations in summary

ttypic · ttypic · commit 42c0fd465083 · 2026-02-12T10:13:09.000Z
diff --git a/ably/realtime/annotations.py b/ably/realtime/annotations.py
@@ -6,8 +6,8 @@
 from ably.rest.annotations import RestAnnotations, construct_validate_annotation
 from ably.transport.websockettransport import ProtocolMessageAction
 from ably.types.annotation import Annotation, AnnotationAction
+from ably.types.channelmode import ChannelMode
 from ably.types.channelstate import ChannelState
-from ably.types.flags import Flag
 from ably.util.eventemitter import EventEmitter
 from ably.util.exceptions import AblyException
 from ably.util.helper import is_callable_or_coroutine
@@ -164,7 +164,7 @@ async def subscribe(self, *args):
 
         # Check if ANNOTATION_SUBSCRIBE mode is enabled
         if self.__channel.state == ChannelState.ATTACHED:
-            if Flag.ANNOTATION_SUBSCRIBE not in self.__channel.modes:
+            if ChannelMode.ANNOTATION_SUBSCRIBE not in self.__channel.modes:
                 if annotation_type is not None:
                     self.__subscriptions.off(annotation_type, listener)
                 else:
diff --git a/ably/rest/annotations.py b/ably/rest/annotations.py
@@ -41,7 +41,7 @@ def serial_from_msg_or_serial(msg_or_serial):
     if not message_serial or not isinstance(message_serial, str):
         raise AblyException(
             message='First argument of annotations.publish() must be either a Message '
-            '(or at least an object with a string `serial` property) or a message serial (string)',
+            'or a message serial (string)',
             status_code=400,
             code=40003,
         )
@@ -67,7 +67,7 @@ def construct_validate_annotation(msg_or_serial, annotation: Annotation) -> Anno
 
     if not annotation or not isinstance(annotation, Annotation):
         raise AblyException(
-            message='Second argument of annotations.publish() must be a dict or Annotation '
+            message='Second argument of annotations.publish() must be an Annotation '
             '(the intended annotation to publish)',
             status_code=400,
             code=40003,
diff --git a/ably/types/channeloptions.py b/ably/types/channeloptions.py
@@ -43,7 +43,7 @@ def params(self) -> dict[str, str] | None:
 
     @property
     def modes(self) -> list[ChannelMode] | None:
-        """Get channel parameters"""
+        """Get channel modes"""
         return self.__modes
 
     def __eq__(self, other):
diff --git a/ably/types/message.py b/ably/types/message.py
@@ -11,6 +11,42 @@
 log = logging.getLogger(__name__)
 
 
+class MessageAnnotations:
+    """
+    Contains information about annotations associated with a particular message.
+    """
+
+    def __init__(self, summary=None):
+        """
+        Args:
+            summary: A dict mapping annotation types to their aggregated values.
+                    The keys are annotation types (e.g., "reaction:distinct.v1").
+                    The values depend on the aggregation method of the annotation type.
+        """
+        # TM8a: Ensure summary exists
+        self.__summary = summary if summary is not None else {}
+
+    @property
+    def summary(self):
+        """A dict of annotation type to aggregated annotation values."""
+        return self.__summary
+
+    def as_dict(self):
+        """Convert MessageAnnotations to dictionary format."""
+        return {
+            'summary': self.summary,
+        }
+
+    @staticmethod
+    def from_dict(obj):
+        """Create MessageAnnotations from dictionary."""
+        if obj is None:
+            return MessageAnnotations()
+        return MessageAnnotations(
+            summary=obj.get('summary'),
+        )
+
+
 class MessageVersion:
     """
     Contains the details regarding the current version of the message - including when it was updated and by whom.
@@ -111,6 +147,7 @@ def __init__(self,
                  serial=None, # TM2r
                  action=None, # TM2j
                  version=None, # TM2s
+                 annotations=None, # TM2t
                  ):
 
         super().__init__(encoding)
@@ -126,6 +163,7 @@ def __init__(self,
         self.__serial = serial
         self.__action = action
         self.__version = version
+        self.__annotations = annotations
 
     def __eq__(self, other):
         if isinstance(other, Message):
@@ -190,6 +228,10 @@ def serial(self):
     def action(self):
         return self.__action
 
+    @property
+    def annotations(self):
+        return self.__annotations
+
     def encrypt(self, channel_cipher):
         if isinstance(self.data, CipherData):
             return
@@ -234,6 +276,7 @@ def as_dict(self, binary=False):
             'version': self.version.as_dict() if self.version else None,
             'serial': self.serial,
             'action': int(self.action) if self.action is not None else None,
+            'annotations': self.annotations.as_dict() if self.annotations else None,
             **encode_data(self.data, self._encoding_array, binary),
         }
 
@@ -278,6 +321,31 @@ def from_encoded(obj, cipher=None, context=None):
             # TM2s
             version = MessageVersion(serial=serial, timestamp=timestamp)
 
+        # Parse annotations from the wire format
+        annotations_obj = obj.get('annotations')
+        if annotations_obj is None:
+            # TM2u: Always initialize annotations with empty summary
+            annotations = MessageAnnotations()
+        else:
+            annotations = MessageAnnotations.from_dict(annotations_obj)
+
+        # Process annotation summary entries to ensure clipped fields are set
+        if annotations and annotations.summary:
+            for annotation_type, summary_entry in annotations.summary.items():
+                # TM7c1c, TM7d1c: For distinct.v1, unique.v1, multiple.v1
+                if (annotation_type.endswith(':distinct.v1') or
+                    annotation_type.endswith(':unique.v1') or
+                    annotation_type.endswith(':multiple.v1')):
+                    # These types have entries that need clipped field
+                    if isinstance(summary_entry, dict):
+                        for _entry_key, entry_value in summary_entry.items():
+                            if isinstance(entry_value, dict) and 'clipped' not in entry_value:
+                                entry_value['clipped'] = False
+                # TM7c1c: For flag.v1
+                elif annotation_type.endswith(':flag.v1'):
+                    if isinstance(summary_entry, dict) and 'clipped' not in summary_entry:
+                        summary_entry['clipped'] = False
+
         return Message(
             id=id,
             name=name,
@@ -288,6 +356,7 @@ def from_encoded(obj, cipher=None, context=None):
             serial=serial,
             action=action,
             version=version,
+            annotations=annotations,
             **decoded_data
         )
 
diff --git a/test/ably/realtime/realtimeannotations_test.py b/test/ably/realtime/realtimeannotations_test.py
@@ -6,7 +6,7 @@
 import pytest
 
 from ably import AblyException
-from ably.types.annotation import AnnotationAction
+from ably.types.annotation import Annotation, AnnotationAction
 from ably.types.channelmode import ChannelMode
 from ably.types.channeloptions import ChannelOptions
 from ably.types.message import MessageAction
@@ -71,10 +71,10 @@ def on_message(msg):
         await channel.subscribe('message', on_message)
 
         # Publish annotation using realtime
-        await channel.annotations.publish(publish_result.serials[0], {
-            'type': 'reaction:distinct.v1',
-            'name': '👍'
-        })
+        await channel.annotations.publish(publish_result.serials[0], Annotation(
+            type='reaction:distinct.v1',
+            name='👍'
+        ))
 
         # Wait for annotation
         annotation = await annotation_future
@@ -88,6 +88,7 @@ def on_message(msg):
         summary = await message_summary
         assert summary.action == MessageAction.MESSAGE_SUMMARY
         assert summary.serial == publish_result.serials[0]
+        assert summary.annotations.summary['reaction:distinct.v1']['👍']['total'] == 1
 
         # Try again but with REST publish
         annotation_future2 = asyncio.Future()
@@ -98,10 +99,10 @@ async def on_annotation2(annotation):
 
         await channel.annotations.subscribe(on_annotation2)
 
-        await rest_channel.annotations.publish(publish_result.serials[0], {
-            'type': 'reaction:distinct.v1',
-            'name': '😕'
-        })
+        await rest_channel.annotations.publish(publish_result.serials[0], Annotation(
+            type='reaction:distinct.v1',
+            name='😕'
+        ))
 
         annotation = await annotation_future2
         assert annotation.action == AnnotationAction.ANNOTATION_CREATE
@@ -130,10 +131,10 @@ async def test_get_all_annotations_for_a_message(self):
         # Publish multiple annotations
         emojis = ['👍', '😕', '👎']
         for emoji in emojis:
-            await channel.annotations.publish(publish_result.serials[0], {
-                'type': 'reaction:distinct.v1',
-                'name': emoji
-            })
+            await channel.annotations.publish(publish_result.serials[0], Annotation(
+                type='reaction:distinct.v1',
+                name=emoji
+            ))
 
         # Wait for all annotations to appear
         annotations = []
@@ -191,10 +192,10 @@ async def on_reaction(annotation):
         # Publish message and annotation
         publish_result = await channel.publish('message', 'test')
 
-        await channel.annotations.publish(publish_result.serials[0], {
-            'type': 'reaction:distinct.v1',
-            'name': '👍'
-        })
+        await channel.annotations.publish(publish_result.serials[0], Annotation(
+            type='reaction:distinct.v1',
+            name='👍'
+        ))
 
         # Should receive the annotation
         annotation = await reaction_future
@@ -227,10 +228,10 @@ async def on_annotation(annotation):
         # Publish message and first annotation
         publish_result = await channel.publish('message', 'test')
 
-        await channel.annotations.publish(publish_result.serials[0], {
-            'type': 'reaction:distinct.v1',
-            'name': '👍'
-        })
+        await channel.annotations.publish(publish_result.serials[0], Annotation(
+            type='reaction:distinct.v1',
+            name='👍'
+        ))
 
         # Wait for the first annotation to appear
         await annotation_future.get()
@@ -242,10 +243,10 @@ async def on_annotation(annotation):
         await channel.annotations.subscribe(lambda annotation: annotation_future.set_result(annotation))
 
         # Publish another annotation
-        await channel.annotations.publish(publish_result.serials[0], {
-            'type': 'reaction:distinct.v1',
-            'name': '😕'
-        })
+        await channel.annotations.publish(publish_result.serials[0], Annotation(
+            type='reaction:distinct.v1',
+            name='😕'
+        ))
 
         # Wait for the second annotation to appear in another listener
         await annotation_future.get()
@@ -287,10 +288,10 @@ async def on_annotation(annotation):
         await channel.publish('message', 'test')
         message = await message_future
 
-        await channel.annotations.publish(message.serial, {
-            'type': 'reaction:distinct.v1',
-            'name': '👍'
-        })
+        await channel.annotations.publish(message.serial, Annotation(
+            type='reaction:distinct.v1',
+            name='👍'
+        ))
 
         await annotation_future.get()
 
@@ -299,10 +300,10 @@ async def on_annotation(annotation):
         assert annotations_received[0].action == AnnotationAction.ANNOTATION_CREATE
 
         # Delete the annotation
-        await channel.annotations.delete(message.serial, {
-            'type': 'reaction:distinct.v1',
-            'name': '👍'
-        })
+        await channel.annotations.delete(message.serial, Annotation(
+            type='reaction:distinct.v1',
+            name='👍'
+        ))
 
         # Wait for delete annotation
         await annotation_future.get()
diff --git a/test/ably/rest/restannotations_test.py b/test/ably/rest/restannotations_test.py
diff --git a/test/ably/utils.py b/test/ably/utils.py
