JMP Protocol
DESCRIPTION
There are two methods of achieving a JMP protocol connection. Both provide
access to the full capabilities of the protocol.
WEBSOCKET
A WebSocket connection creates a full-duplex communications channel as would
be available by direct connection to a TCP port but using the HTTP or HTTPS
mechanism. This enables direct interaction between a website and JANOS.
By default a WebSocket channel supports the JMP protocol. This is how the
JNIOR WebUI performs tasks such as are available through the Folders, Console
and Syslog tabs.
Websocket has been standardized by the IETF
https://www.ietf.org/ as
RFC 6455
https://tools.ietf.org/html/rfc6455 . The JNIOR WebUI is installed
by the file /flash/www/config.zip and in particular the JavaScript file
comm.js in that library handles the Websocket communications. You are free
to use that source code as reference or to incorporate any part of it in your
custom website.
Note that the JMP protocol requires a login. This is critical as the protocol
is very powerful. When a website login to the JNIOR is successful (or if the
login is disabled) a Session Cookie is generated. This is passed when a
related HTTP connection is elevated to Websocket. It then is accepted as a
valid login credential providing seamless operation.
PROTOCOL PORT
By default a connection to TCP Port 9220 provides direct access to the JMP
protocol. In this case there is a special wrapper that must be used in
transporting the JSON messages.
One of the issues in using JSON in communications protocols stems from the
lack of message length information. In the absence of a length the
communications driver must count open '{' and close '}' curly braces in
order to ascertain when an entire structure has been read from the channel.
This is complicated by the fact that curly braces may appear in string data
and those must be ignored. The algorithm, while not complicated, is an
annoyance. The JMP connection uses a wrapper that conveys a message length.
Once a successful connection is made to the JMP Server port, messages may be
exchanged. With one exception all messages conform to the JSON format using
the ASCII printable character set. The high-level message format must be as
follows. This forms the message wrapper which is a 2-element JSON Array
construct.
[ length , object ]
Where length defines the exact size of the object in bytes excluding leading
and trailing white-space if any. Leading and trailing white-space, which can
include newline characters, may be present surrounding both the length value
and the object. Here object must be a fully formed and valid JSON Object
beginning with '{' and ending with '}' curly braces. Both these curly braces
and any characters in between are included in the length value. The leading
'[' opening square bracket, ',' comma, and trailing ']' closing square bracket
are required. The opening and closing JSON Object curly braces are also
verified. If there is any violation to this format the message will be simply
ignored. There is no response or indication of error. All bytes outside of
the square brackets are ignored as well.
A valid parsing strategy would be as follows:
* Read and ignore bytes up to a '[' opening square bracket
* Read and ignore white-space characters (space, tab, newline, etc.)
* Accumulate a decimal length (must be digits 0-9, the result must be >= 2)
* Read and ignore white-space
* Read and confirm the presence of the ',' comma
* Read and ignore white space
* Extract the JSON Object of precise length defined by the numeric value
* Read and ignore white-space
* Read and confirm the ']' closing square bracket (no other character
is acceptable)
* Confirm that the JSON object is properly enclosed by '{' and '}'
curly braces
* Process the JSON object and repeat
This wrapper is not used by the Websocket connection since Websocket already
includes message length information.
EXAMPLE
All TCP/IP Port 9220 communications utilize the 2-element JSON Array format
for conveying valid JSON Objects. This is not used in WebSocket communications.
In describing JMP protocol Messages the 2-element JSON Array format will be
assumed. We will only show the enclosed JSON Objects.
To initialize communications the client should send a blank or empty message.
The following is acceptable.
{
"Message":""
}
This message properly formatted for JMP Port 9220 would be transmitted as
follows.
[14, {"Message":""} ]
The connection will proceed depending on the authentication requirements
established by configuration and the client environment for the connection.
NOTES
It is important to note that the TCP/IP connection is a streaming channel
and one or more network packets may be required to convey an entire message.
Similarly a packet may include the final bytes of one message and those
beginning the next. A reliable implementation will buffer incoming data until
an entire message is received. Once the message is processed it is removed
from the buffer leaving any additional data which will be required to form
the message that follows.
JMP is not Master-Slave. Many requests do solicit a response but not all.
There are also unsolicited messages produced by the server. These alert the
client to I/O changes as well as many other events.
The protocol allows you to specify any amount of META data with your
request. That data is echoed in the associated response. This can be used
to maintain synchronization between request and response. It is a very
flexible means of synchronization and can be used to convey, for example,
detailed processing instructions for the response.
SEE ALSO
HELP Topics:
SECURITY,
JMP,
JSON
[/flash/manpages/protocol.hlp:24]