Navigation

Wiki Navigation

Banana is an efficient, extendable protocol for sending and receiving s-expressions.
A s-expression in this context is a list composed of bytes, integers, large integers, floats and/or s-expressions.
Unicode is not supported (but can be encoded to and decoded from bytes on the way into and out of Banana).
Unsupported types must be converted into a supported type before sending them with Banana.

The banana protocol is a stream of data composed of elements. Each element has the
following general structure - first, the length of element encoded in base-128, least significant
bit first. For example length 4674 will be sent as 0x420x24 . For certain element
types the length will be omitted (e.g. float) or have a different meaning (it is the actual
value of integer elements).

Following the length is a delimiter byte, which tells us what kind of element this
is. Depending on the element type, there will then follow the number of bytes specified
in the length. The byte’s high-bit will always be set, so that we can differentiate
between it and the length (since the length bytes use 128-base, their high bit will
never be set).

The Banana protocol is extendable. Therefore, it supports the concept of profiles. Profiles allow
developers to extend the banana protocol, adding new element types, while still keeping backwards
compatibility with implementations that don’t support the extensions. The profile used in each
session is determined at the handshake stage (see below.)

A profile is specified by a unique string. This specification defines two profiles
- "none" and "pb" . The "none" profile is the standard
profile that should be supported by all Banana implementations.
Additional profiles may be added in the future.

Extensions defined by a profile may only be used if that profile has been selected by client and server.

The "pb" profile is intended for use with the Perspective Broker protocol, that runs on top
of Banana. Basically, it converts commonly used PB strings into shorter versions, thus
minimizing bandwidth usage. It starts with a single byte, which tells us to which string element
to convert it, and ends with the delimiter byte, 0x87 , which should not be prefixed
by a length.

The initiating side of the connection will be referred to as “client” , and the other
side as “server” .

Upon connection, the server will send the client a list of string elements, signifying
the profiles it supports. It is recommended that "none" be included in this list. The client
then sends the server a string from this list, telling the server which profile it wants to
use. At this point the whole session will use this profile.

Once a profile has been established, the two sides may start exchanging elements. There is no
limitation on order or dependencies of messages. Any such limitation (e.g. “server can only send an element to client in response to a request from client” ) is application specific.

Upon receiving illegal messages, failed handshakes, etc., a Banana client or server should
close its connection.