Banana is an efficient, extendable protocol for sending and receiving s-expressions. A s-expression in this context is a list composed of byte strings, integers, large integers, floats and/or s-expressions.
The banana protocol is a stream of data composed of elements. Each element has the
following structure - first, the length of element encoded in base-128, least signficant
bit first. For example length 4674 will be sent as 0x42 0x24
.
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).
Given a series of bytes that gave us length N, these are the different delimiter bytes:
Large integers do not need to be supported - they are intended for arbitary length integers. Regular integers types (positive and negative) are limited to 32-bit values.
Here are some examples of elements and their encodings:
0x1 0x81
0x1 0x83
0x84 0x3f 0xf8 0x0 0x0 0x0 0x0 0x0 0x0
0x5 0x82 0x68 0x65 0x6c 0x6c 0x6f
0x0 0x80
0x2 0x80 0x1 0x81 0x17 0x81
0x15 0x3e 0x41 0x66 0x3a 0x69 0x26 0x5b 0x1 0x85
0x2 0x80 0x1 0x81 0x1 0x80 0x5 0x82 0x68 0x65 0x6c 0x6c 0x6f
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 compatability 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.
The "none" profile is identical to the delimiter types listed above. It is highly recommended that all Banana clients and servers support the "none" profile.
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 does this by adding an additional delimiter byte, 0x87. This byte should not be prefixed by a length. It should be followed by a single byte, which tells us to which string element to convert it:
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.