chat: bring own database guide #2949
Conversation
|
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 ✨ Finishing touches🧪 Generate unit tests (beta)
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. Comment |
vladvelici
force-pushed
the
chat-bring-own-database-CHA-1145
branch
from
c4e4962 to
fc6ba27
Compare
AndyTWF
left a comment
AndyTWF
left a comment
There was a problem hiding this comment.
We need to update page data to make this visible on the nav.
|
|
||
| This article covers the following options: | ||
|
|
||
| 1. Using [outbound webhooks](/docs/platform/integrations/webhooks). This can be a [HTTP endpoint](/docs/platform/integrations/webhooks/generic), [AWS Lambda](/docs/platform/integrations/webhooks/lambda), [Azure Function](/docs/platform/integrations/webhooks/azure), [Google Function](/docs/platform/integrations/webhooks/gcp-function) and others. Messages will arrive to your own system as they are published to a room. |
There was a problem hiding this comment.
Rather than list 3 types of serverless function, perhaps call out one of them and maybe mention something like Kafka instead?
There was a problem hiding this comment.
kafka is part of the "outbound streaming". I've added examples to that list too. If you think it reads/looks better without the services list I can remove both lists from this?
There was a problem hiding this comment.
I think just one example per section, e.g. lambda and kafka is probably enough
| Use `channel.message` as the event type. | ||
|
|
||
| You need to consider: | ||
| - Redundancy. In case of failure, Ably will retry delivering the message to your webhook, but only for a short period of time. |
There was a problem hiding this comment.
We'd need to check this, I'm not sure we do?
There was a problem hiding this comment.
We do, I checked before writing this.
But it's just 2-3 retries for about 1 min max. Docs say 5 minutes for batched, you mentioned we kind of want to stay away from the batched format in webhooks so that doesn't matter. I had a paragraph suggesting it initially.
There was a problem hiding this comment.
If Ably is not able to eventually send the message to the webhook, how can the developer know that? Is there a way to retrieve webhook failed messages?
There was a problem hiding this comment.
It's logged on the log metachannel [meta]log
There was a problem hiding this comment.
I think the [meta]log channel is the place to find these errors. Mentioned it in another section, I could add a link here too.
| 3. If you want to store reaction summaries, always update the reactions field when receiving a reaction summary update (action `4` or `message.summary`). | ||
|
|
||
| <Code> | ||
| ```typescript |
There was a problem hiding this comment.
| ```typescript | |
| ```javascript |
There was a problem hiding this comment.
done, and removed the : Message type from example
There was a problem hiding this comment.
We could keep the : Message, its just for the language selector :)
|
|
||
| ## Decoding and storing messages | ||
|
|
||
| Regardless of the delivery mechanism, you will need to decode the received messages into Chat messages. Details of the mapping from Ably Pub/Sub messages to Chat messages are available in the [Integrations](/docs/chat/integrations) documentation. |
There was a problem hiding this comment.
This part is confusing for me. If I'm an Ably Chat user, using the Ably Chat SDK... why would I have to decode anything? I should be already managing Chat messages, right?
There was a problem hiding this comment.
This is where we are right now. Integrations (webhooks, outbound streaming, , etc) are a pub/sub features, so you need to do the encoding/decoding yourself.
In the future it would be nice if those were chat-specific to make it simpler but they're not right now.
There was a problem hiding this comment.
The future agreed direction is that the actual payloads will be the same across product, but that the SDKs (e.g. Chat) will have methods that convert these to their local representations
|
|
||
| 1. Save it to your own database. You can index by `serial`, this is the global unique identifier for a message, and is also used to sort messages in the canonical global order. | ||
| 2. If the message already exists by `serial`, it means you have received an update, delete, or reaction summary update. To check if you need to update the message, you can use the `version.serial` to compare the latest version of the message you have received with the version of the message you have in your database. Lexicographically higher means newer version. | ||
| 3. If you want to store reaction summaries, always update the reactions field when receiving a reaction summary update (action `4` or `message.summary`). |
There was a problem hiding this comment.
What is a "reaction summary update"? Is it an special message type, with different metadata? Is there a link to related documentation?
There was a problem hiding this comment.
It's a message with action message.summary. Over the wire it's a full regular message, but at the time of feature implementation in Chat this was a partial message that only had the summary (and identifying basics like timestamp and serial).
The chat SDK still exposes these via room.messages.reactions.subscribe() as a reactions summary event.
In Pub/Sub you get them via channel.subscribe().
Over integrations they look like messages with action message.summary.
Not sure what doc to point you to, probably https://ably.com/docs/chat/rooms/message-reactions, and maybe also annotations: https://ably.com/docs/messages/annotations#subscribe-to-annotation-summaries-.
| Use `channel.message` as the event type. | ||
|
|
||
| You need to consider: | ||
| - Redundancy. In case of failure, Ably will retry delivering the message to your webhook, but only for a short period of time. |
There was a problem hiding this comment.
If Ably is not able to eventually send the message to the webhook, how can the developer know that? Is there a way to retrieve webhook failed messages?
| Benefits of using an Ably queue: | ||
|
|
||
| - You can consume it from your servers, meaning overall this is fault-tolerant. Ably takes care of the complexity of maintaining a queue. | ||
| - You can use multiple queues and configure which channels go to which queue (use `.*::\$chat$` regex to match all chat rooms). |
There was a problem hiding this comment.
If we don't talk about directives, replace this with "use your own regular expression to match all your chat rooms" or something similar.
There was a problem hiding this comment.
I could just remove the parenthesis if we really want to avoid this. Or go with what @AndyTWF suggested: suggest prefixing the room names if they want to.
There was a problem hiding this comment.
The way we're trying to nudge users is to group chat rooms etc under a common namespace, e.g. chat:*
There was a problem hiding this comment.
I've removed all mentions of ::$chat suggesting a prefix if they need to filter.
| Benefits: | ||
| - Full control over publishing. | ||
| - Opportunity to add extra validation before publishing to Ably. | ||
| - You can publish messages directly via the Chat REST API, and avoid having to encode/decode Chat Messages to and from Ably Pub/Sub messages. You can bypass using an SDK entirely or you can use the Chat SDK for publishing. |
There was a problem hiding this comment.
I'd say just use the chat SDK, all the enocde/decode part for me (as an external developer) sounds confusing.
There was a problem hiding this comment.
Avoiding to have to do it is a benefit when you publish via your own servers or fetch via history.
But we don't have this benefit in the other methods of integrating right now.
I'd leave this paragraph in, perhaps mention this in the next section as well. WDYT?
There was a problem hiding this comment.
The main problem I see is that for me, as a developer that wants to use Ably Chat, is difficult to understand why should I care about PubSub... I want to use the chat, how is that implemented in Ably should be transparent for me. I see that I have to encode or decode from PubSub and that sounds complex and unnecessary. I just want to manage my messages.
There was a problem hiding this comment.
We have a progressive disclosure of complexity that we aim for - there will be some use-cases where we have to introduce Pub/Sub to the mix.
In this case, once we do the SDK changes to take integration payloads as they are and turn them directly into chat messages... people won't need to worry about Pub/Sub.
|
|
||
| You need to consider: | ||
| - You need to handle updates and deletes on your own. | ||
| - Storing message reactions can be difficult since you will not have access to the aggregate (summaries) Ably provides. |
There was a problem hiding this comment.
Do we offer an API for this in the SDK or REST APIs?
There was a problem hiding this comment.
You can:
- Fetch history (includes summaries)
- Fetch single message by serial (includes summaries)
- Fetch "own summary" but not really useful here
But in this context they're all a big annoyance since you need to actively fetch instead and you need to decide when to do it.
| - For each message, only the latest version of the message is returned. | ||
| - You will need to decide when and which rooms to import messages from. | ||
| - You can import the same room multiple times (deduplicate by `serial` and `version.serial`), but you will need to always fetch from the first message to make sure you don't miss any updates or deletes of older messages. | ||
|
|
There was a problem hiding this comment.
Also, every message retrieved via the history API is a billable history, so implementing this is not free.
There was a problem hiding this comment.
Should I add a note about this? I think perhaps this is better suited for the history page or pricing docs?
There was a problem hiding this comment.
Every message sent via an integration is too - so history isn't alone in this regard
vladvelici
force-pushed
the
chat-bring-own-database-CHA-1145
branch
from
215c729 to
7fb2c92
Compare
|
I've pushed the last round of changes. Added link in navigation. Changed title and file to "Export chat messages", sounds clearer to me than "bring your database". |
|
(I'll squash the commits before merge) |
| meta_keywords: "chat, data, export, stream, storage, Ably, chat SDK, realtime messaging, dependability, cost optimisation" | ||
| --- | ||
|
|
||
| Ably Chat is designed to be a simple and easy to use realtime chat solution that handles any scale from 1:1 and small group chats to large livestream chats with millions of users. |
There was a problem hiding this comment.
| Ably Chat is designed to be a simple and easy to use realtime chat solution that handles any scale from 1:1 and small group chats to large livestream chats with millions of users. | |
| Ably Chat is a simple and easy to use realtime chat solution that handles any scale from 1:1 and small group chats to large livestream chats with millions of users. |
|
|
||
| Ably Chat is designed to be a simple and easy to use realtime chat solution that handles any scale from 1:1 and small group chats to large livestream chats with millions of users. | ||
|
|
||
| Ably holds data for the purpose of providing realtime experiences. While Ably Chat provides flexible data retention for messages (30 days by default, up to a year on request), applications often need longer-term storage or additional control over their data. |
There was a problem hiding this comment.
| Ably holds data for the purpose of providing realtime experiences. While Ably Chat provides flexible data retention for messages (30 days by default, up to a year on request), applications often need longer-term storage or additional control over their data. | |
| Ably holds data for the purpose of providing realtime experiences. While Ably Chat provides flexible data retention for messages (30 days by default, up to a year on request), some applications may need longer-term storage or additional control over their data. |
More a nit pick, so feel free to ignore :)
|
|
||
| ## Different ways to export data from Ably Chat | ||
|
|
||
| We will explain each in detail, and provide code examples for each. This is an overview of the different ways to export data from Ably Chat. |
There was a problem hiding this comment.
I think this line isn't needed, Perhaps just the line, This article covers the following options?
|
|
||
| We will explain each in detail, and provide code examples for each. This is an overview of the different ways to export data from Ably Chat. | ||
|
|
||
| This article covers the following options: |
There was a problem hiding this comment.
| This article covers the following options: | |
| This guide covers the following options: |
|
|
||
| Regardless of the delivery mechanism, you will need to decode the received messages into Chat messages. Details of the mapping from Ably Pub/Sub messages to Chat messages are available in the [Integrations](/docs/chat/integrations) documentation. | ||
|
|
||
| After performing the decoding and you have a chat `Message` object, you can: |
There was a problem hiding this comment.
| After performing the decoding and you have a chat `Message` object, you can: | |
| After performing the decoding to get your chat `Message` object, you can: |
|
|
||
| 1. Save it to your own database. You can index by `serial`, this is the global unique identifier for a message, and is also used to sort messages in the canonical global order. | ||
| 2. If the message already exists by `serial`, it means you have received an update, delete, or reaction summary update. To check if you need to update the message, you can use the `version.serial` to compare the latest version of the message you have received with the version of the message you have in your database. Lexicographically higher means newer version. | ||
| 3. If you want to store reaction summaries, always update the reactions field when receiving a reaction summary update (action `4` or `message.summary`). |
There was a problem hiding this comment.
Perhaps we should add some links here to direct users to sections on message serials/versions?
Description
Add chat guide to save messages to your own database. https://ably.atlassian.net/browse/CHA-1145
Checklist