buglabs/bugswarm-connector — Issue #50: Changing the contract for announcing capabilities.
Author: barberdt
Created: 2011-12-08 22:11:00+00:00
State: open
Labels: content

This issue is opened to begin discussion of changing the workflow executed by the connector to announce its capabilities. Making this change would cause connector-dependent applications, such as the webUI, to change slightly. This issue is directed at @aturley, @santiago, @c4milo, and @jconnolly. Turley and I discussed this briefly and feel that this change makes sense, however, we would like everyone else's input as well.

**Current contract:**
There are two cases to consider:

**1.** The connector connects to a swarm with existing instance(s) of the webUI:

In this case, the connector sends a **public** capabilities message to the swarm. Any connected instances of the webUI then react to this message and **privately** request the announced feeds at a given frequency. The connector then responds, at that frequency, to those requests with **private** messages containing the feed data.

**2.** The connector is already connected and an instance of the webUI connects:

In this case, when the webUI connects, the connector recognizes that there is a new member in the swarm and sends a **private** capabilities message to that resource. The webUI then reacts to that message and responds **privately** with requests for the announced feeds at a given frequency. The connector then responds, at that frequency, to those requests with **private** messages containing the feed data.

**Proposed Contract:**
The same two cases as described above.

**1.**

In this case, the connector sends a **public** message to the swarm saying "Hello everyone, I am a connector". The format of this message would be decided after the decision regarding this change is made. Following this announcement, any applications that are interested in connectors, the webUI for instance, would send **private** messages to that connector saying "Hello connector, give me your capabilities message". Again, that message format would be decided. The connector would then respond by sending a **private** capabilities message to that resource and the workflow would continue as the current contract specifies it to.

**2.**

In this case, upon connection, the webUI (or other connector-interested resource) would send a **public** message to the swarm saying "Hello everyone, I am interested in connectors" (format to be decided). Any connectors in the room would then send **private** capabilities messages to that resource and the workflow would continue as the current contract specifies to.

**Reasons for Proposing this Change:**

In an effort to create a JScript-based connector using the BUGswarm JScript library, we stumbled across a situation where we were unable to determine whether we were receiving presence available messages because we had just connected or because a new member had joined the swarm. Because this connector was relying on presence notifications to know when to send the private capabilities messages as described in step **2** of the current contract, we were unable to determine which case we were in (step 1 or 2), and therefore unable to determine whether we should send one **public** capabilities message or several **private** capabilities messages to each resource we received presence from. The workaround was to do both, however, that resulted in any 'capabilities-sensitive' resources (the webUI specifically) to respond to capabilities (with feed requests) twice when they only needed to respond once.

**Advantages to Come from this Change:**

This change would alleviate the issue described above and create a more robust connector contract/specification, allowing for easier development of other connectors outside of the present implementation.

**SHARE YOUR THOUGHTS!!!**