Changing the contract for announcing capabilities.

[barberdt]

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:

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. A connector-interested resource (the webUI for instance) connects to the swarm:

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.

Note: While these cases are described in the context of a relationship between the connector and the webUI, this contract and the announcements associated with it would hold

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!!!

[barberdt]

In speaking with @c4milo, it seems that the current majority is interested in changing it so that the connector simply sends private capabilities messages whenever it receives a swarm presence available message. This was @jconnolly's solution as well. I would wait for a comment here from @aturley, but I feel that this solution is a good one and makes things less confusing than the proposed solution in this issue. Also, in speaking with @c4milo, I learned that, as long as the connected is speaking through HTTP, the overhead of sending private messages to everyone in the room upon connection as a connector will be minimal since the server handles splitting up the message to go to everyone else, so the connector still is only sending one message.

[c4milo]

indeed @barberdt, the message will look like:

{ "message": {
       "to": [  {"swarm": "234", "resource": "222"}, 
                {"swarm": "234", "resource": "223"} ], 
        "payload": {"y":2}
  }
}

[barberdt]

@camilo, given that the trigger for sending private capabilities would be a presence available message (both for when the connector joins the swarm and when another resource joins the swarm), I'm not sure how you would be able to send just that one message with an array of {swarm: , resource: } objects as the 'to' value. I would imagine it would be one message for each swarm available received that would look like this:

{"message": {"to": [{"swarm": "234", "resource": "222"}], "payload": {"y":2}}}

Because of this, I'm still unsure about what the overhead would be like for sending this message to every resource in the swarm if the swarm had many many resources.

However, even with the overhead, this still seems to me to be the best solution right now.