Plugin Link Negotiation Protocol

This is a draft document.

= Introduction = The Plugin Link Negotiation Protocol (PLNP) is a low-level line-oriented protocol for enabling parties communicating over a network socket to arrive at joint agreement on a set of operating options.

It is purposely lightweight and minimalist to support options negotiation before more powerful structured or hierarchical mechanisms are in place on the link, in order that these mechanism can themselves be open to negotiation.

The protocol is bidirectional. When one party is the initiator of a negotiation over a specific option, the other party replies in its role as responder. By design, these roles are transient and concurrent: in principle, both parties can be engaged in both roles concurrently without conflict.

However, as an initial implementation constraint, the plugin will be the sole initiator and the viewer the sole responder, to simplify the implementation. This initial implementation constraint may become final if this restriction is found to be satisfactory in practice.

The above symmetry is broken only in the final command of a negotiation: the resolution command START can be invoked only by the plugin and not by the viewer, since the viewer is unaware of when the process of options negotiation has terminated.

The resolution command QUIT can be invoked by both parties to abort the negotiation and close the network link.

= Protocol commands, informal =


 * HELP
 * WANT   [] ...
 * OK   
 * NO   
 * START
 * QUIT
 * QUIT

= Protocol grammar, initiator =


 * ::=  ;


 *  ::=  ;


 *  ::= "START" | "QUIT";


 *  ::=  |  ;


 *  ::=  <line_terminator>;


 * <want_extended> ::= <want_command> | <help_command> | <comment_command>;


 * <want_command> ::= <want_noargs> | <want_command> ;


 * <want_noargs> ::= "WANT" ;


 * ::= "json" | "xml" | "debug";




 * <help_command> ::= "HELP";


 * ::= <whitespace_chars> | <whitespace_chars>;


 * <whitespace_chars> ::= ' ' | '\t';


 * <line_terminator> ::= '\r' '\n';


 * <comment_command> := "#" <sequence_of_characters_excluding_CRLF>;


 * ::= <sequence_of_characters_excluding_whitespace_or_CRLF>;

= Protocol grammar, responder =


 * ::= <responder_command> <line_terminator>;


 * <responder_command> ::= <negotiation_response> | <comment_command>;


 * <negotiation_response> ::= <accept_or_reject> ;


 * <accept_or_reject> ::= "OK" | "NO";

= Protocol semantics and implementation constraints =


 * 1) Each command appears on a separate CRLF-terminated line.
 * 2) Fields within each line are separated by whitespace consisting of ASCII spaces and/or tabs only.
 * 3) Each field consists of a string of one or more characters excluding whitespace or CRLF.
 * 4) Every command contains at the very least a commandName field.
 * 5) In some commands, the commandName field may be followed by an option field.
 * 6) If present, the option field is a keyword that names a particular option.
 * 7) An option field may be followed by zero or more argument fields.
 * 8) If present, argument fields supply additional information for the option.
 * 9) CommandNames are not case-sensitive, whereas options are.
 * 10) Lines have a maximum length of 255 characters including the CRLF.

= Examples of protocol negotiation =

Example: simplest use

 * START

Example: simplest use with some helpful information supplied by both parties

 * # Viewer: Imprudence v5.191.6-rc93 on 3rd Jan 2015
 * # Plugin: Nice to meet you Imprudence, I'm plugin WooHoo and I'll use your defaults
 * START

Example: negotiation of alternative link serializations

 * # Viewer: Imprudence v5.191.6-rc93 on 3rd Jan 2015
 * # Plugin: Nice to meet you Imprudence, I'm plugin WooHoo
 * WANT xml
 * NO xml
 * WANT json
 * OK json
 * START

Example: the start of a manual debug session

 * # Viewer: Imprudence v5.191.6-rc93 on 3rd Jan 2015
 * # Testing 1
 * WANT debug 5
 * # Viewer: debug level set to 5
 * OK debug
 * START
 * # Viewer: parsed cmd={START} option={}
 * # Viewer: dispatching {START} command
 * # Viewer: configuring link options
 * # Viewer: loading JSON serialization handler
 * # Viewer: plugin session is ready
 * <now we talk to the viewer using JSON>