Vumi Go event magic

gistfile1.md

Events

We add a new type of Vumi Go message, similar to a VumiApiCommand to handle events:

VumiApiEvent:
  account_key
  conversation_key
  conversation_type
  event_type
  event_data

A kind of event is uniquely identified by conversation_type and event_type, and event_data is a dict. All events go to an event dispatcher (either part of or similar to the command dispatcher) which looks up what needs to happen with each event and does the appropriate things.

Event sources

Event sources generate and publish events.

All application/conversation workers are potential event sources. We may want to have some additional non-conversation event sources as well at some point.

Event handlers

Event handlers are pieces of code (perhaps workers, perhaps part of the event dispatcher) that accept an event and then do something with it. Handlers would have to be specific to certain event types, but could also be event sources and fire their own events in response to things the're handling.

For example: A vxpolls conversation could fire a poll_complete event containing the poll results when someone finishes filling in a poll. The account has a create_contact handler listening for poll_complete events from that particular conversation, and configured to extract certain values from the poll data to create a contact with.

Configuration

Event handlers would have to be configured in the UI somewhere, probably in a manner similar to a conversation start. Perhaps this kind of flow:

1. Create new event handler
2. Select event source and type
3. Select event handler type
4. Configure handler-specific options
5. Profit!

We'd need to be able to chain handlers, so we could create a new contact and then send an SMS when a poll finishes.

Routing and tags

Not entirely event-related, but this might be a good place to set up account-level tag routing and such, perhaps with a default account-wide message handler that does something sane rather than just throwing all the messages on the floor.

Few questions:

• Why does this have to be separate to VumiApiCommand -- maybe the VumiApiCommand class just needs to be renamed? Conversation start is really just an event (i.e. it's not something one can reply to).
• Not quite sure who would catch the poll_complete event? There's nothing running on the Django side and the poll worker could just handle it.

• It can be a VumiApiCommand, I suppose, but I'm not really sold on the idea. I'm thinking of a command as a directed instruction (tell this conversation to start) and an event as a broadcast notification (this conversation has done something others might be interested in).
• The event dispatcher would catch all events for an account and then pass them to their configured handlers. The poll worker would fire the poll_complete event, the dispatcher would catch it, see that there's a "create contact" handler interested in that kind of event from that source, and feed the event to the handler.

I'm +1 on having this be a separate thing from a VumiApiCommand (maybe subclassed or perhaps the VumiApiCommand itself needs to be refined?) for the same reasons that @jerith mentions. I'd like to borrow some ideas from Django's signals stuff as it allows for fairly nice decoupling for events from bits of code acting on those events but then we'd want to do it asynchronously via queues - this would possibly prevent us from easily stopping events bubbling up the event handling chain unless we implement some fancy RPC thing somewhere.

A poll_complete event would be fantastic for one of my current projects as I need to hit a 3rd party payment gateway when a poll is completed.

More questions:

• How does the "create contact" handler get configured and hooked up?
• Where do contact handlers live in the system? Inside the event dispatcher? In their own workers? Somewhere in Django land?
• The "poll_complete" just doesn't seem like a great example of an event to me. It's specific to the poll worker and I don't really see a need for anything other than the poll worker to handle it (and an events system inside the same worker is something entirely different to what's being proposed here).

Event systems are useful for hits kind of many-to-many dispatch -- I'm just trying to make sure we have some sort of broad plan for how this is going to work in our case.

@hodgestar:

• That's something we need to decide. It'll probably be a bunch of yucky account-level UI work pushing a configuration into a datastore somewhere the event dispatcher can see it.
• Event handlers live in vumi-land, not Django-land. Probably either in the event dispatcher or in their own workers. I'm leaning slightly toward the former at the moment, but we need to figure out what will work best for us.
• The poll_complete event is actually the example that kicked this whole thing off. At an account level, we need certain actions outside the poll worker to be triggered when a poll completes. This could be contact creation, SMS sends, payment gateway notification, whatever. The point is that none of that behaviour belongs in the poll worker, and we want to be able to configure it for whatever the account owners need.