Feature/pub 1676 message annotations #2642
Conversation
Adds "annotations" to the list of documented channel rules.
Adds a page to the Messages section of the Pub/Sub product nav to document the message annotation feature.
Describes how to enable message annotations by configuring an annotations channel rule.
Add docs for publishing annotations, subscribing to annotation summaries and individual annotation events, and descriptions of annotation types and the available summarization methods and their semantics.
Documents the annotations.delete() method and describes how the are treated when producing summaries.
Link to the annotations docs that specify annotation message properties.
|
Important Review skippedAuto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the You can disable this status message by setting the Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
Documents the annotation modes ANNOTATION_SUBSCRIBE and ANNOTATION_PUBLISH and the associated capabilities annotation-subscribe and annotation-publish.
Specifies which summarization methods unidentified clients may use. Describes how to require that all clients are identified via the Identified channel rule.
| | -------- | ----------- | | ||
| | id | An Ably-generated ID used to uniquely identify the message. | | ||
| | action | The action specifies whether this is an annotation being added (`annotation.create`) or removed (`annotation.delete`). See [subscribing to annotation updates](#subscribe). | | ||
| | serial | This message's unique serial (lexicographically totally ordered). | |
There was a problem hiding this comment.
This message's unique serial
"This annotation's unique serial"
| | count | An optional count, only relevant to certain summarization methods. See [annotation summaries](#annotation-summaries) for more information. | | ||
| | data | An optional payload for the annotation. Available on an [individual annotation](#subscribe-individual-annotations) but not aggregated or included in [annotation summaries](#annotation-summaries). | | ||
| | encoding | This is typically empty, as all messages received from Ably are automatically decoded client-side using this value. However, if the message encoding cannot be processed, this attribute contains the remaining transformations not applied to the `data` payload. | | ||
| | timestamp | The timestamp of when the message was received by Ably, as milliseconds since the Unix epoch. | |
There was a problem hiding this comment.
the message
"the annotation"
(etc)
| name: 'delivered' | ||
| }); | ||
| ``` | ||
| </Code> |
There was a problem hiding this comment.
this is character-for-character identical to the javascript code sample. I'm pretty sure you don't need both, I think we have a fallback waterfall defined so that it'll show the most relevant code sample that exists, and ofc that'd be javascript for nodejs? Mark can confirm
|
|
||
| <Code> | ||
| ```javascript | ||
| await channel.annotations.subscribe((annotation) => { |
There was a problem hiding this comment.
The code example should include getting the channel with channeloptions that specify the annotation_subscribe mode
|
|
||
| A separate summary is produced for each distinct [annotation type](#annotation-types). | ||
|
|
||
| The summarization method specified in the [annotation type](#annotation-types) determines how annotations in the same namespace for a given message are aggregated into a summary. A summary is constructed from the set of `annotation.create` and `annotation.delete` messages that have been published for a message. |
There was a problem hiding this comment.
Might be useful to give an example summary in a code block? Just to show that it's an object whose keys are the annotation types, which is obvious once you know it but isn't necessarily clear from reading the docs
Description
Adds docs for the message annotations feature to the Messages section of the Pub/Sub product docs.
Includes:
typespecifiers the different summarization methods and their semanticsNot ready to merge yet until we are ready to make the release but opening as draft now for early review.
Checklist