Event Architecture

[james-rae]

(note this exists in HackMD but duplicating here to keep a this repo full)
Also see #344 afterwards for more things that were discovered and discussed after implementing the stuff below.

Challenges

We want to achieve a number of things that tend to conflict with each other.

• Fixture indepedence / decoupling
• Simple communication between fixtures
• Ability for non-standard fixtures to react to RAMP workflows
• Ability to customize or turn off standard RAMP fixtures & workflows
• Avoidance of race condition nonsense when multiple fixtures are reacting asynchronously to the same event

A few ideas have been batted around, but have either pointed towards anarchy (e.g. global events with random things reacting in random order) or authoritarianism (e.g. specific functions on specifically named fixtures expecting to be called at a specific point in time).

Idea: Opening up the Event Architecture

Of the many ideas considered, a common issue that keeps appearing is that we have no idea what a 3rd party fixture will want to do. Building an internal system that handles all eventualities is pretty much impossible.

So the idea is to allow a site author to make their own rules, and have an out-of-the-box rule set for vanilla R4MP. We leave it up to the author to work out whatever special logic is required for their specific needs.

Everything is presented as a concept for now. Names, parameter orderings, etc, are always up for debate.

Also, for simplicity, the examples are done assuming certain design choices. Further down there are options that may change how the examples would be coded.

Event Name Party

Fixtures will have named events. The event names for our out-of-box fixture should be well documented in our docsite.

The event handler registrations will also have names. The out-of-box handlers for vanilla configuration will have nice and documented names. 3rd party handlers can be author defined, or system generated if not.

The main reason for introducing names on the handlers is that we will have out-of-box handlers existing at startup. The name makes it easy for someone to remove it, rather than having to derive a function memory address somehow. A secondary benefit is it allows someone debugging to easily see what handlers are lurking, and can allow for simple programmatic checks for handler existence.

The registration of the out-of-box handlers must be designed so they are added before a 3rd party can start manipulating event handlers.

Adding Event Handlers

The fixture base class will have a public function .on(eventName, eventHandler, handlerName?) to register an event handler.

Non-existing event names or duplicate handler names will throw an error. Not providing the handler name will generate a name something like <FixtureName>_<eventName>CustomHandler<AutoNumber>.

Removing Event Handlers

The fixture base class will have a public function .off(eventName, handlerName) to de-register an event handler.

Non-existing event names or handler names will throw an error. Possible discussion: have it return a boolean indicating if it found and removed the event handler rather than an error bomb.

Inspecting Event Handlers

The fixture base class will have a public function .activeHandlers(eventName) that returns an array of the names of all handlers registered to the event.

We can also consider a function like .availableEvents() that returns an array of all the event names fixture exposes.

Examples

Example 1: Out of the Box: Legend Opens Grid

This would be part of our standard setup, so if the site author does not interfere, this code would be done as part of the startup.

rInstance.fixture.get('legend').on(
  'item-click',
  dataPayload => rInstance.fixture.get('grid').open(dataPayload),
  'ramp-legend-item-click-grid' // a constant, documented
);

Example 2: Extra Listener, Random

In this case, we want our grid to still open from the legend, but want a second graph fixture to open as well. The order in which the grid and chart fixture open may be random

// this is done by internal standard startup
rInstance.fixture.get('legend').on(
  'item-click',
  dataPayload => rInstance.fixture.get('grid').open(dataPayload),
  'ramp-legend-item-click-grid'
);

// this is provided by the 3rd party site author
rInstance.fixture.get('legend').on(
  'item-click',
  dataPayload => rInstance.fixture.get('fancyChart').open(dataPayload),
  'my-charty-chart-handler'
);

Example 3: Extra Listener, Specific Control

Like Example 2, we have the chart opening with the grid. However now we take over the default event handlers. Note that while we have shared variable declarations to keep the sample uncluttered, in the real case this would be implemented across two different files (the core startup and the host page script).

// get fixture references
const [legend, grid, fancyChart] = 
    rInstance.fixture.get(['legend', 'grid', 'fancyChart']);

// this is done by internal standard startup
legend.on('item-click', 
    dataPayload => grid.open(dataPayload), 
    'ramp-legend-item-click-grid');

// this is provided by the 3rd party site author
legend.off('item-click', 'ramp-legend-item-click-grid');
legend.on(
    'item-click',
    dataPayload => {
        grid.open(dataPayload);
        fancyChart.open(dataPayload);
    },
    'my-chart-grid-handler'
);

Example 4: Inspection Party

A power flex. Assuming the setup of Example 2, a chart and grid, not connected. Imagine a custom fixture button exists to toggle if the chart should appear. The custom fixture exposes an event called 'chart-toggle-button-click'

// this is provided by the 3rd party site author

const [legend, chartToggle] = rInstance.fixture.get(['legend', 'chartToggle']);

chartToggle.on(
  'chart-toggle-button-click',
  () => {
    if (legend.activeHandlers('item-click').indexOf('my-charty-chart-handler') > -1) {
      // the chart click handler exists, remove it
      legend.off('item-click', 'my-charty-chart-handler');
    } else {
      // the chart click handler does not exist, add it.
      legend.on('item-click', chartHandlerFunction, 'my-charty-chart-handler');
    }
  },
  'toggle-grid-chart-connection'
);

Benefits

• Offloads any complexity that is not part of out-of-the-box RAMP.
• Flexible enough to have multiple listeners, no listeners, etc.
• Can still support the notion of "special" fixtures. That is, if a different fixture is named the same as ours and implements the same interface, it can be swapped without needing to mess with the events
• Can be manipulated programatically as well as custom-coded

Downsides

• Custom configurations can require a heavy amount of code on the page. The page is essentially re-programming the event handlers. That said, customizations around strict rules or free-range events would also require heavy page interventions.
• We would need to provide documentation and boiler plate of the default set of events for people to understand all the things they need to accomodate for when tweaking
• Any changes to the default event handlers could cause instability in existing pages. However this risk also exists with our API so nothing new.
• Having handler manipulation in the page isn't the greatest for re-use. Would be nicer if, say, a fixture startup routine could have event modifications in it. But then we would be back in the same problem of not knowing what other fixtures could be sharing the runtime with that specific fixture.

Possible Enhancement - Disabling Events

A use case that might be useful to support is the concept of disabling an event handler. In Example 4, we add and remove the event handler to support a toggle button effect. Being able to disable or enable the event would be simpler.

We can imagine a suite of event management methods would be something like add event hander, remove event handler, enable event handler, disable event handler. Alternately the enable and disable could be replaced with a toggle event function that changes the enabled/disabled state.

Further, adding this would merit a .disabledEvents() method that returns the names of all the disabled event handlers.

Naming Fun Never Ends

Entertaining the abitlity to enable and disable events means our proposed functions on() and off() can be confusing. At a glance they could hint that they control the enable and disable instead of the add and remove.

If we come to it, we can figure out ideal method names for the suite. Potential fun pairs: on, off, enable, disable, add, remove, listen, unlisten. Some of these may want more explicit names. E.g. fixture.add() isn't clear that it would effect event handlers, so perhaps fixture.addListner() is more appropriate.

Possible Enhancement - Bulk Registration

A way to register a batch of events could be a niceity for initialization blocks.

The following is a basic example. It doesn't allow for providing event names. Once the guts of this event framework are solidified this concept can be revisited and optimal parameter signatures can be proposed.

rInstance.fixture.get('legend').on({
  'item-click': dataPayload => rInstance.fixture.get('grid').open(dataPayload),
  'item-remove': doStuff,
  'item-add': event => doOtherStuff()
});

Possible Enhancement - Replace Handler

Another use case that may be good to support is the idea of replacing a handler. Of course this can be done with a remove then add.

The original spec for on() above indicates an error is thrown if an event handler name is used twice. We could consider changing this behavior to do a replace. This idea is a risky one, as it opens up unintentional overwrites. An optional boolean force parameter could be added to the on() signature to help ensure the caller understands the consequences.

A different approach is to make a dedicated update() function for event handlers. This gets rid of any unintentional consequences. But it also removes the ability to easily support the use case of "I don't care what the current event handler is, nor if it exists at all, I decree the handler to now be this new handler". That usecase would need an if-exists check first.

If we decide to not have a replace mechanism and just use off() then on(), it would help if we chose the implementation of off() that does not error if removing a non-existing handler and just returns false

Event Bus of Madness

The above examples all act as if each fixture is handling its own event bus. The actual implementation is a bit more complex, and we have some options to consider.

Current Global Event Bus

We have a global event-bus and it can be accessed from the API instance:

rInstance.on('blah-event', callback);
rInstance.once('blah-event', callback);
rInstance.off('blah-event'?, callback?); // removes event handlers
rInstance.emit('blah-event', args);

Any code can use this including fixtures, panels, and the host page.

This event bus comes from the Vue core framework. This matters as creating multiple event busses mean spinning up a Vue() instance for each, which is more expensive than, say, a dirty fake event system that GeoAPI uses by wrapping an array of callbacks.

Update: Option 2 won by an overwhelming majority. 🎉

Option 1 - Fixture Has Own Bus

Give each fixture its own event bus to emit events on. This easily aligns with the proposed convention on setting event handlers on fixtures themselves:

rInstance.fixture.get('legend').on(
    'item-click',
    dataPayload => rInstance.fixture.get('grid').open(dataPayload),
    'ramp-legend-item-click-grid'
);

The default Vue event bus functions would need some wrapping to allow for handler name parameter.

Pros

• Straightforward setup where each fixture get its own event bus

Cons

• Each event bus is a empty Vue instance; each new event bus will consume additional memory
• If a fixture is removed and re-added, all handlers will need to be re-added, as the bus would have been destroyed
• Cannot register an event until the fixture exists, possibly creating timing trickery for when the core startup and the host page can register events

Option 2 - Leveraging the Global Bus

Reuse the global event bus for all fixture events. This will require some wrapping of the global even bus functions to help distinguish events from different fixture (since you can't trust people to name things correctly):

// some-fixture
this.emit('my-event');
this.on('your-event', callback)


// the above will transalte on the global bus by combining the event and fixture names
this._eventBus.$emit(`${fixture.name}/${event-name}`);
this._eventBus.$on(`${fixture.name}/${event-name}`, callback);


// host page will still subscribe to event through fixtures
rInstance.fixture.get('legend').on('item-click', callback);


// but it would be possible, although not advised, to subscribe though the global bus
rInstance.on('legend/item-click', callback);


// this "might" be useful if you don't know when a certain fixture will be loaded,
// and don't want to `setTimeout` it; although in this case,
// you should listen to `fixture-added` event (coming-soon) and subscribe then;
rInstance.on('fixture-added', ({id}) => { 
    if (id === 'legend') {
        rInstance.fixture.get('legend').on('item-click', callback);
    }
});

Pros

• Only a single event bus is needed, so less duplication and less memory consumption
• Easy for the core to react to setting/removing handlers if needed since all events go through a single bus
• Possible to set up events before the fixtures exist, making initial setup easier

Cons

• Somewhat more work
• It is possible to fake events belonging to other fixtures since everything goes through a single bus

Option 3 - Decoupled Fixture Bus

We keep the idea of a bus-per-fixture from Option 1, but the bus lives in a decoupled global area, like an EventSheriff. Each bus in the Sheriff is keyed by fixture key-name.

// Option 1, the on() method would be implemented like
on(...) {
    this.privateBus.on(...);
}

// Option 3, the on() method would be implemented like

on(...) {
  const myBus = this.iApi.eventSheriff.get(this.id);
  myBus.on(...)
}

Pros

• Can preserve event bindings if fixtures are removed and re-added
• Possible to set up events before the fixtures exist, making initial setup easier
• Not possible to fake an event from another fixture by emitting on the global bus

Cons

• Somewhat more work
• Each event bus is a empty Vue instance; each new event bus will consume additional memory

Discussion

• Can anyone think of a scenario where this breaks / won't work?
• Any suggestions for improvements?
• For later: best way to align things like Layer Status changing so similar things can be done.

[james-rae]

We ended up just keeping the basic Global bus. Fixtures all have access to the instance API, so they just emit/listen to it.