-
-
Notifications
You must be signed in to change notification settings - Fork 1.8k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
[RFC] Push Notifications API #469
Comments
A couple thoughts on the "Polling for notifications after being offline" section after some discussion in the Matrix server: The Example output from cURL:
Although this would need to run an expensive query against the DB depending on the number of topics, so calls using |
It's unclear how authentication ties in to all of this. |
In order for an instance to provide notifications for a channel, said channel needs to be tracked. To track a channel means the instance is subscribed to a channel's RSS feed and/or has a job running to pull all videos/update older videos from a channel. Tracking channels can be resource intensive so currently it is only done when at least one user has previously subscribed to a channel (it will still track after unsubscribing). To ensure that a channel is being tracked, a client should send a Authentication is needed so that a client can ensure it will receive notifications for a channel, while not allowing an easy vector for abuse. |
Additionally, supporting a |
Added Since each message contains the entire Important to note is that notifications will also be sent whenever a video is updated for example when a description or title is changed. It is recommended to use logic similar to here to provide consistent notifications for new videos. |
Added |
Added Although there isn't technically a limit on the size of a GET request, things can start to fail in weird ways after a certain limit. This provides a way to access the advertised 1000 topics per call by putting the topics field into the body. If you're using something like sse.js, you can do: notifications = new SSE(
'/api/v1/auth/notifications?fields=videoId,title,author,authorId,publishedText,published,authorThumbnails', {
withCredentials: true,
payload: 'topics=' + subscriptions.join(','),
headers: { 'Content-Type': 'application/x-www-form-urlencoded' }
});
notifications.onmessage = function (event) {
if (event.data === '') {
return;
}
var notification = JSON.parse(event.data);
// ...
} |
This issue has been automatically marked as stale and will be closed in 30 days because it has not had recent activity and is much likely outdated. If you think this issue is still relevant and applicable, you just have to post a comment and it will be unmarked. |
Related issues: #195, #427
Currently, in order for an application to receive updates from a channel, it needs to send a request to
/api/v1/channels/latest/:ucid
or similar endpoint. This is inefficient when the number of channels being requested reaches even moderate size. This propsal is for a/api/v1/notifications
that uses EventSource to push notifications in near real-time.The EventSource protocol pushes updates using a persistent connection to an HTTP server. It is supported in all major browsers with a polyfill available for IE. The EventSource API can automatically reconnect to the source on errors, and provides a simple API for handling events. There is also a wrapper reconnecting-eventsource for handling more challenging network conditions.
The EventSource protocol is quite simple and can be implemented easily in any language where it isn't already supported. It sends comments (lines prefixed with
:
), or events containing: one or moredata
fields, an optionalid
, and an optionaltype
. After each message is sent a trailing newline. Example from the spec:/api/v1/notifications
The endpoint
/api/v1/notifications
would support atopics
parameter containing a list of comma-separated resources. Each resource would be a UCID or any other supported ID./api/v1/notifications
would support a maximum of 1000 topics per call.Opening a connection to
/api/v1/notifications
creates a persistent connection between the server and the client, with:keepalive #{TIMESTAMP}
messages sent every 20-30 seconds to ensure the connection is not dropped.Each event would contain a
data
field with the updated resource as JSON. Schema would be the same as/api/v1/channels/latest/:ucid
.Example output from cURL:
Example handling in JavaScript:
Polling for notifications after being offline
In order for an application to receive notifications after being offline , a
?since=TIMESTAMP
should be added to/api/v1/channels/latest/:ucid
. Using?since=
would return up to 15 videos uploaded after the specified timestamp. If there are more than 15 videos that have been uploaded since the given date,/api/v1/channels/latest/:ucid
will return the 15 latest.It may also make sense to support an
?until=TIMESTAMP
to create a "window" where specific videos can be queried, although this would require authentication as mentioned below.Final thoughts
Notifications would only be supported for channels tracked by the instance, which means that one or more users on that instance are subscribed to them. Requesting that a new channel be tracked by an instance must be authenticated to prevent abuse. Authentication will be handled in a second RFC.
Important to note is that notifications will be sent when a channel changes a video's description or title, not just when it is uploaded.
In accordance with this spec, a
"protocols":["eventsource"]
field should be added to/api/v1/stats
, example. See also #356.I would like to discuss if there are any issues with this approach, or any other issues that haven't been considered to ensure this is provides as much utility as possible.
Thanks!
The text was updated successfully, but these errors were encountered: