Bugzilla Push Extension
-----------------------
This extension sends messages to a message broker via AMQP or STOMP
whenever an object (bug, keyword, component, etc) is created or modified.

For more information, read these blog posts:
* http://christian.legnitto.com/blog/2010/08/20/push-notifications-for-bugzilla/
* http://christian.legnitto.com/blog/2010/09/10/bugzilla-amqp-is-now-buzgilla-push-supports-the-stomp-protocol/

You can also view these demo videos. Warning, they are large (recorded off a
24 inch monitor) but the actual file size is small:
* http://people.mozilla.org/~clegnitto/broker/demo.theora.ogv (OGG Theora)
* http://people.mozilla.org/~clegnitto/broker/demo.webm (WebM)

Please note this has not been tested in production yet! This is a very early
release, and though it works please proceed with caution. On the plus side,
it doesn't modify any Bugzilla data--the worst that can happen is 
your Bugzilla installation fails until you deactivate the extension. I have
tested it locally against Bugzilla's trunk. If you find problems with older 
releases, let me know.

You can deactivate the extension by moving it out of the Bugzilla extension
directory or placing an empty file named "disabled" in the extension directory
and then restarting your webserver.

WARNING! WARNING! WARNING!

The message fields/formats *will likely change* in future revisions. Currently
the messages look like:

_meta:
    'routing_key' => 'The routing key'
    'time'        => 'Time the message was created'
payload:
    OBJECT_TYPE => {DUMP OF BUGZILLA OBJECT}
    'change' => {DUMP OF BUGZILLA CHANGE REPRESENTATION}
             (for changed messages)

Both the envelope format and the format of the raw data will likely change.
I am currently doing mapping for types, but the mapping may change until I
"officially" decide the interface is frozen. When possible, I tried to copy 
the WebServices. All times/dates are in iso8601 format.

Questions, comments, concerns: email Christian Legnitto <[email protected]>


Requirements
-----------------------
* You need to patch Bugzilla with the patch from 
  https://bugzilla.mozilla.org/show_bug.cgi?id=587793.
    (the patch is trivial and will be integrated in a later Bugzilla release)

* If you want comment messages, you need to patch Bugzilla with the patch from 
  https://bugzilla.mozilla.org/show_bug.cgi?id=590334. The extension should
  still work without the patch, but no messages will be sent for any events
  related to comments

* Perl module Net::RabbitFoot
    (if you want to use AMQP)

* You should probably patch Net::RabbitFoot with the patch from
  http://github.com/cooldaemon/RabbitFoot/commit/ec13602e3bb4d676f750a22e659bc8aedc09f16f
  until an updated version gets in cpan (or build from RabbitFoot's source)

* Perl module Net::Stomp
    (if you want to use STOMP)

* Perl module Scalar::Util
    (used to determine type of object we are messaging about, already required)

* Perl module JSON >= 2.07
    (used to serialize the message, already required)


Installation
-----------------------
1. Copy the Push directory to the Bugzilla "extensions" directory
2. (optional) sudo perl /path/to/bugzilla/install-module.pl [Requirements above]
3. Login to your Bugzilla installation as an administrator
4. Click "Administration"
5. Click "Parameters"
6. Click "Push Integration" in the left menu
7. Insert data specific to your broker setup


Known Issues / TODO
-----------------------
* Messages are always serialized with JSON. Support for other schemes will be
added in the future

* The exchanges are currently hardcoded as durable topic exchanges. I intend
to make this configurable via the admin interface

* I need to come up with stable object mappings so that consumers don't
break when Bugzilla changes the internal representations. I'm mostly there

* Comments only send comment.new messages. I want them also to send bug changed
messages as well (perhaps with configurable behavior)

* Custom fields are supported as simple strings rather than objects. I plan
to make this support more robust in the future

* Vhosts other than "/" have not been tested, though they probably work

* I want to make the message verbosity configurable. Currently it resolves and
includes most embedded objects, which may not be ideal for every use-case

* Due to the way Bugzilla extensions work, the message is sent during a
database transaction. If the transaction is rolled back the message will still
be sent. I'm thinking of ways to mitigate/fix this, but it should generally
be a non-issue for now

* Currently messages are sent for each change. In the future I want to make it
configrable between current behavior, current behavior + a changeset message,
and only a changeset message

* Related to the previous, I want to break additions (changes where the value 
before wasn't set) removals (changes where the value was set before and not 
after) and general changes (fields that had a value that changed) into seperate
messages so consumers don't have to know stuff like '---' means the field was
cleared, etc

* Be aware, if you choose to send messages about secure bugs and allow public
access to your broker you are esentially removing the bug security.
In the future I intend to allow publishing secure bug messages to a different
different exchange or server as well as disallowing any messages a public
bugzilla user couldn't see

* Bug closed messages are not sent. Currently, consumers will need to listen to
bug changed messages and look at 'is_open' in the status. I intend to make
this configurable so that you can send closed and reopened messages

* Object deletion messages are not sent. This is a future feature I want to add
if at all possible

* It would be nice in the future for the connection and channel to stay open
between Bugzilla and the broker (for simplicity and performance). I'm not sure
this is possible with the current extension system

* There has been no performance testing, but I will (hopefully) be testing
soon. Whenever I saw a chance to speed things up / return early I did though.

* The coding style doesn't match Bugzilla's coding guidelines

* I am not a Perl programmer, so I am sure there are better ways to write
portions of the extension. I'll be doing more general code cleanup and
solidifying as time goes on

* This file is pretty much the only documentation. I need to write more!