Confirmed users
1,927
edits
BMO/ChangeNotificationSystem: Difference between revisions
Jump to navigation
Jump to search
→Implementation
| Line 42: | Line 42: | ||
= Implementation = | = Implementation = | ||
Work on the prototype is | Work on the prototype is tracked in {{bug|923849}}. | ||
If you want to hack on the system, see the HACKING.md file in bugzfeed (https://github.com/mozilla/bugzfeed/blob/master/HACKING.md). | |||
== Bugzilla and Pulse == | |||
The changes are written by Bugzilla using the ZPushNotify extension (http://bzr.mozilla.org/bmo/4.2/files/head:/extensions/ZPushNotify/). | The changes are written by Bugzilla using the ZPushNotify extension (http://bzr.mozilla.org/bmo/4.2/files/head:/extensions/ZPushNotify/). | ||
| Line 48: | Line 52: | ||
The changes are picked up and delivered to Pulse by the Bugzilla Simple Shim (https://hg.mozilla.org/automation/pulseshims/ - relevant files are bugzilla_simple_shim.py, requirements_bugzilla_simple_shim.txt, and the bottom of config.ini.example). | The changes are picked up and delivered to Pulse by the Bugzilla Simple Shim (https://hg.mozilla.org/automation/pulseshims/ - relevant files are bugzilla_simple_shim.py, requirements_bugzilla_simple_shim.txt, and the bottom of config.ini.example). | ||
The Pulse messages are consumed by bugzfeed (https://github.com/mozilla/bugzfeed). | == bugzfeed == | ||
The Pulse messages are consumed by and served via WebSockets through bugzfeed (https://github.com/mozilla/bugzfeed). | |||
Bugzfeed takes a number of commands, sent in JSON format. Each command message is an object containing at least a <tt>command</tt> attribute. Most commands take other, command-specific attributes as well. The server responds to each command with a JSON message containing at least the attributes <tt>result</tt> and <tt>command</tt>. <tt>result</tt> is either the string <tt>ok</tt> or <tt>error</tt>; if the latter, the response object also has an <tt>error</tt> attribute containing a descriptive string. <tt>command</tt> is the name of the command this message is in response to. Most commands will include other attributes in the response object as well. | |||
=== Commands === | |||
The supported commands are | |||
'''<tt>subscribe</tt>''' | |||
Subscribe to one or more bugs. Attributes for this command are | |||
* <tt>bugs</tt>: Required. An array of one or more bug IDs. | |||
* <tt>since</tt>: Optional. A timestamp in UTC in the form <tt>YYYY-MM-DDTHH:MM:SS</tt>. If provided, any cached notifications (see below) matching those in the given <tt>bugs</tt> array are immediately sent after the command response. | |||
The response object also includes a <tt>bugs</tt> attribute, which is an array of all currently subscribed bugs after the command is executed. | |||
'''<tt>unsubscribe</tt>''' | |||
Unsubscribe to one or more bugs. Attributes are | |||
* <tt>bugs</tt>: Required. An array of one or more bug IDs. | |||
The response object also includes a <tt>bugs</tt> attribute, which is an array of all currently subscribed bugs after the command is executed. | |||
'''<tt>subscriptions</tt>''' | |||
List subscribed bugs. There are no extra attributes for this command. | |||
The response object also includes a <tt>bugs</tt> attribute, which is an array of all currently subscribed bugs. | |||
'''<tt>version</tt>''' | |||
Get the version of the bugzfeed server. There are no extra attributes for this command. | |||
The response object also includes a <tt>version</tt> attribute, which is a string representing the current version, e.g. <tt>0.3</tt>. | |||
=== Examples === | |||
To subscribe to bugs 1, 2, and 3, you would send the message <tt>{"command": "subscribe", "bugs": [1, 2, 3]}</tt>. If you were currently not subscribed to any others, the response would be <tt>{"command": "subscribe", "result": "ok", "bugs": [1, 2, 3]}</tt>. | |||
To later unsubscribe from bug 1, send <tt>{"command": "unsubscribe", "bugs": [1]}</tt>, to which the response would be (assuming no subscribe/unsubscribe commands were sent in between) <tt>{"command": "unsubscribe", "result": "ok", "bugs": [2, 3]}</tt>. | |||
=== Caching === | |||
The bugzfeed server caches the last 10 000 notifications it has received. This mechanism was put into place to account for brief client connections without maintaining per-connection state on the server. If the connection drops, after reconnecting a client can resubscribe to all its bugs and provide the time of the last known update to see if any updates have occurred while it was disconnected. It's suggested to use the exact time of the last update, not one second later, since technically multiple bugs can be updated in the same second. Just be aware that the last known update will be resent in this case, as all cached notifications with timestamps equal to or greater than the the value of the <tt>since</tt> are sent. | |||
Note that caching is implicitly performed on all other pieces of the notification system. If the pulse shim goes down, Bugzilla will continue to write updates to the database, which will be read when it is restarted. The bugzfeed production server is configured to use a durable pulse queue, so if it goes down, it will catch up on all queued messages when it restarts. | |||