bmo / pulse integration
=======================

notes to include in this document:

  - publishes each change in bmo to pulse
  - will support multiple connectors
    - initially just pulse
    - want to push bug metadata into an elastic-search cluster
  - comments require two new hook for bugzilla 4.0
  - comments are sent in a seperate message from bug meta changes
  - talk about objects vs data values
    - objects always contain 'id', and generally 'name'
    - if an object field is no set ==> undef (eg bug:milestone)
  - currently untested on bugzilla 4.2 or higher

message structure:

  - always contains an "event" hash
    - user: actor object
    - action: "create" or "modify"
    - target: name of the object the change was actioned on (eg "bug")
    - time: when
  - always contains an event.target hash

sample message:

{
   "bug" : {
      "alias" : "",
      "assigned_to" : {
         "id" : 13647,
         "login" : "glob@mozilla.com",
         "real_name" : "byron jones [:glob]"
      },
      "cf_blocking_191" : "",
      "cf_blocking_192" : "",
      "cf_blocking_20" : "",
      "cf_blocking_fennec" : "",
      "cf_blocking_fx" : "",
      "cf_crash_signature" : "",
      "cf_status_191" : "",
      "cf_status_192" : "",
      "cf_status_20" : "",
      "cf_status_firefox5" : "",
      "classification" : "Components",
      "component" : {
         "id" : 539,
         "name" : "General"
      },
      "creation_time" : "2011-12-06T09:18:00",
      "flags" : [],
      "id" : 648667,
      "keywords" : [
         "regression"
      ],
      "last_change_time" : "2011-12-06T09:44:23",
      "operating_system" : "Mac OS X",
      "platform" : "x86",
      "priority" : "",
      "product" : {
         "id" : 1,
         "name" : "Core"
      },
      "reporter" : {
         "id" : 13647,
         "login" : "glob@mozilla.com",
         "real_name" : "byron jones [:glob]"
      },
      "resolution" : "",
      "severity" : "normal",
      "status" : {
         "id" : 3,
         "name" : "ASSIGNED"
      },
      "summary" : "test",
      "target_milestone" : null,
      "url" : "",
      "version" : {
         "id" : 355,
         "name" : "unspecified"
      },
      "whiteboard" : ""
   },
   "event" : {
      "action" : "modify",
      "changes" : [
        {
            "added" : "glob@mozilla.com",
            "field" : "assigned_to",
            "removed" : "nobody@mozilla.org",
        }
      ],
      "target" : "bug",
      "time" : "2011-12-06T09:45:52",
      "user" : {
         "id" : 13647,
         "login" : "glob@mozilla.com",
         "real_name" : "byron jones [:glob]"
      }
   }
}

flow

- the bugzilla extension inserts messages into a 'push' table
- a daemon polls the table and calls on each connector to publish the message
- as order is important, we need to manage transient failures

poe daemon : polling 'push' table

    foreach connector (connectors)
        # check if a connector is backlogged
        if (count(table.push_backlog[connector]) > 0)
            connector.backlogged = true
        else
            connector.backlogged = false

    # process each pending message
    foreach message (table.push[oldest first])
        foreach connector (connectors)
            if (!connector.backlogged)
                result = connector.send(message)
                if (result == transient_failure)
                    log transient error
                    connector.backlogged = true
                else if (result == permanant_failure)
                    log failure
                else
                    log success
            if (connector.backlogged)
                insert into table.push_backlog[connector]
        delete message from table.push

    # process backlog
    foreach connector (connectors)
        foreach message (table.push_backlog[connector])
            result = connector.send(message)
            if (result == transient_failure)
                log transient error
                break out of foreach message loop
            else if (result == permanant_failure
                log failure
            else
                log success
            delete message from table.push_backlog