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)
There was a problem hiding this comment.
Fixed in 28d43f4
| 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
There was a problem hiding this comment.
That would be nice, @m-hulbert is there a way to do this?
There was a problem hiding this comment.
You can comma separate the languages in textile and it will render for each, but we didn't retain that functionality for the initial MDX implementation. Given that in 99% of cases the node sample is identical I'd rather handle this in a different way in the future -- either automate the creation centrally, or drop the node samples entirely because the JS is sufficient.
|
|
||
| <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
There was a problem hiding this comment.
Fixed in 66505d9
|
|
||
| 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
There was a problem hiding this comment.
Fixed in 8d7eb0c
mschristensen
force-pushed
the
feature/PUB-1676-message-annotations
branch
from
8d7eb0c to
ed9ed44
Compare
|
@m-hulbert for some reason the left nav menu gets squished when the content is too wide, despite the fact that it seems to wrap okay
|
Adds the error codes used for message annotations as defined in https://github.com/ably/ably-common/blob/main/protocol/errors.json
|
In 9582fcf I have added the error codes used by message annotations, which have been updated in ably/ably-common#307 And aligned in realtime in: https://github.com/ably/realtime/pull/7514 We need to decide on the name used for the channel rule in the website and can align the error codes, error messages used in realtime and the docs here accordingly. |
Updates the name used for the channel rule that enabled mutable messages functionality to "Advanced message features" per ADR-144. Marks the annotations feature as Experimental and adds the appropriate caveats to the channel rule documentation.
|
In 66a92ed I have renamed the "Mutable messages" channel rule to "Advanced message features" per ADR-144 (pending decision) and included the appropriate caveats for features that are not yet supported on mutable messages enabled channels. |
There was a problem hiding this comment.
Thanks Mike, this is comprehensive in terms of content - I just think shuffling the content around might help in understanding it a little quicker.
I know I've made various suggestions throughout, but in hindsight I wonder if the entire page should speak solely in terms of message summaries considering that is what we recommend. Then we have an independent section at the end that explains how/why you can subscribe to individual events. Otherwise it becomes quite complex to explain both instances everywhere. This would make some of my comments obsolete, but let me know what you think.
Also, the content squish is a regression in the MDX implementation which I've logged with the web team. It's related to codeblock scrolling/wrapping of long lines where we've added line numbering.
| *Resolution*: | ||
| * Ensure that @annotation_subscribe@ mode is specified in the client "channel options":/docs/channels/options before subscribing to individual annotations. | ||
|
|
||
| h2(#93002). 93002: Annotations are only supported on channels with the Mutable Messages feature enabled |
There was a problem hiding this comment.
This is currently out of sync with the 'advanced message features' rule naming - though appreciate that's still being debated.
| @@ -34,6 +34,10 @@ The following are the properties of a message: | |||
| - extras := A JSON object of arbitrary key-value pairs that may contain metadata, and/or ancillary payloads. Valid payloads include those related to "Push Notifications":/docs/push, "deltas":/docs/channels/options/deltas and headers. | |||
| - 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. | |||
|
|
|||
| <aside data-type='note'> | |||
| <p>Additional properties are included on a message when using message "annotations":/docs/messages/annotations .</p> | |||
There was a problem hiding this comment.
I think we should list the additional properties here.
| --- | ||
|
|
||
| <Aside data-type='experimental'> | ||
| Message Annotations is currently Experimental. Its features are still in development and subject to rapid change. |
There was a problem hiding this comment.
"The message annotations feature" or "Message annotations are"
| languages: | ||
| - javascript | ||
| - nodejs |
There was a problem hiding this comment.
This isn't required in MDX as an FYI.
| @@ -0,0 +1,529 @@ | |||
| --- | |||
| title: Message Annotations | |||
There was a problem hiding this comment.
I think this should be sentence case throughout for consistency.
| <Aside data-type="info"> | ||
| When using message annotations, normal messages delivered to the [`subscribe()`](/docs/pub-sub#subscribe) listener will have an `action` of `message.create`. | ||
| </Aside> |
There was a problem hiding this comment.
I wonder if this should be part of the intro section, but more importantly clearly state that annotation (summaries) use the same listener as regular messages on the channel. WDYT?
| <Aside data-type='note'> | ||
| Individual annotation events are useful for activity feeds or detailed logging, but for maintaining UI state, summary events are generally more reliable and efficient. | ||
| </Aside> |
There was a problem hiding this comment.
I'd pull this up into the intro of the section and out of the aside.
| </Aside> | ||
|
|
||
|
|
||
| ## Annotation types <a id="annotation-types"/> |
There was a problem hiding this comment.
Would this work better as part of publishing an annotation considering that's the point you need to set the type?
|
|
||
| Ably provides five summarization methods to support different use cases which are described below. | ||
|
|
||
| ### Total |
There was a problem hiding this comment.
I wonder if these should be listed before the payload example, as they're key to understanding what type of annotation you can publish.
|
|
||
| If the same client publishes an annotation of a given type to the same message twice, the `total` count is incremented twice. | ||
|
|
||
| ```javascript |
There was a problem hiding this comment.
Missing <Code> tags on the last few codeblocks of the page.
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