Establishing protocol version¶

Version is negotiated between experiment and experiment operator. Version is established from when experiment sends silf:protocol:version:set until experiment is finished.

Note

Currently experiment is finished when experiment sends silf:experiment:stop with type done. But precise moment may depend on protocol version.

Version values¶

We use semantic versioning v. 2.0.0 to version the protocol.

Experiment may specify that it supports version ranges that have following syntax: 1.1.1-2.0.0 which specifies versions from (including) 1.1.1 up to (excluding) 2.0.0.

Conversation¶

In this document we will define what stanzas are exchanged during the protocol negotiation. All communication is done inside labdata messages, :see:`proto-1.0-labdata`.

Happy path

Operator sends labdata: silf:protocol:version:get

Server responds with : silf:protocol:version:get that contains list of avilable versions.

Operetor sends: silf:protocol:version:set, this stanza contains selected version.
- Server responds with: silf:protocol:version:set with version selected by client.
  
  From now on version is set.

Other proper paths

Operator does not need to check avilable versions from the server, it can just send silf:protocol:version:set and hope for the best, if he sent version that can’t be handled by the experiment, experiment will send and error stanza.

Error conditions¶

Folowing error conditions are possible:

Client sends version that is not acceptable for the experiment (was not in avilable version list). In this case experiment sends silf:protocol:version:set with type: error.
Client can’t handle any version sent by the experiment. In this case client does not send silf:protocol:version:set and just disconects from the experiment room.
Client sends any other stanza not specified by the protocol. In this case experiment sends appropriate error stanza, or just ignores the message.

Joining experiment after version is established¶

If observer joins the room after session negotiation he is informed about protocol version by the athena bot before he joins the room.

If experiment operator joins the room after session negotiation has taken place Athena bot should send experiment version before operator is given voice in the room. If the operator is given voice in the room, and he didn’t get this information he can start version negotiation.

In both cases athena bot sends silf:protocol:version:set with type result and the same content that experiment sent earlier.

Stanza content¶

`silf:protocol:version:get`¶

Client sends empty labdata with type query.

Server responds with a message of type result, and list of protocol versions this experiment supports, in the following list:

{
    "versions": ["1.0", "1.0.2", "0.0.0-0.6.0"]
}

`silf:protocol:version:set`¶

Client sends labdata with type query and sends selected version:

{
    "version": "0.5.9"
}

Server responds with labdata with type result and the same content.

From now on up to the moment when experiment closes the experiment session protocol version siginified in before mentioned stanza is used.

If client sends improper version (one not present in list of versions), experiment responds with error.

Note

Server responds by confirming selected version just so all elements of the system can know version just by checking single stanza.

Example conversation¶

<message from='exp@muc.ilf/operator' to='exp@muc.ilf' type='groupchat'>
    <labdata xmlns="silf:protocol:version:get" type="query" id="q1"/>
</message>

<message from='exp@muc.ilf/experiment' to='exp@muc.ilf' type='groupchat'>
    <labdata xmlns="silf:protocol:version:get" type="result" id="q1">
    {
        "versions": ["1.0", "1.0.2", "0.5"]
    }
    </labdata>
</message>


<message from='exp@muc.ilf/operator' to='exp@muc.ilf' type='groupchat'>
    <labdata xmlns="silf:protocol:version:set" type="query" id="q2">
    {
        "version": "1.0"
    }
    </labdata>
</message>

<message from='exp@muc.ilf/experiment' to='exp@muc.ilf' type='groupchat'>
    <labdata xmlns="silf:protocol:version:set" type="result" id="q2">
        {
            "version": "1.0"
        }
    </labdata>
</message>