~certify-web-dev/twisted/certify-staging

"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml" lang="en"><head><title>Twisted Documentation: Banana Protocol Specifications</title><link href="../howto/stylesheet.css" type="text/css" rel="stylesheet" /></head><body bgcolor="white"><h1 class="title">Banana Protocol Specifications</h1><div class="toc"><ol><li><a href="#auto0">Introduction</a></li><li><a href="#auto1">Banana Encodings</a></li><li><a href="#auto2">Element Types</a></li><ul><li><a href="#auto3">Examples</a></li></ul><li><a href="#auto4">Profiles</a></li><ul><li><a href="#auto5">The "none" Profile</a></li><li><a href="#auto6">The "pb" Profile</a></li></ul><li><a href="#auto7">Protocol Handshake and Behaviour</a></li></ol></div><div class="content"><span></span><h2>Introduction<a name="auto0"></a></h2><p>

<?xml version="1.0" encoding="utf-8"?>

<!DOCTYPE html

PUBLIC '-//W3C//DTD XHTML 1.0 Transitional//EN'

'http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd'>

<head>

<title>Twisted Documentation: Banana Protocol Specifications</title>

</head>

<h1 class="title">Banana Protocol Specifications</h1>

<div class="toc"><ol><li><a href="#auto0">Introduction</a></li><li><a href="#auto1">Banana Encodings</a></li><li><a href="#auto2">Element Types</a></li><ul><li><a href="#auto3">Examples</a></li></ul><li><a href="#auto4">Profiles</a></li><ul><li><a href="#auto5">The "none" Profile</a></li><li><a href="#auto6">The "pb" Profile</a></li></ul><li><a href="#auto7">Protocol Handshake and Behaviour</a></li></ol></div>

<span/>

<h2>Introduction<a name="auto0"/></h2>

<p>

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.

</p><h2>Banana Encodings<a name="auto1"></a></h2><p>

</p>

<h2>Banana Encodings<a name="auto1"/></h2>

<p>

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 signficant

bit first. For example length 4674 will be sent as <code>0x42 0x24</code>. 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).

</p><p>

</p>

<p>

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).

</p><h2>Element Types<a name="auto2"></a></h2><p>

</p>

<h2>Element Types<a name="auto2"/></h2>

<p>

Given a series of bytes that gave us length N, these are the different delimiter bytes:

</p><dl><dt>List -- 0x80</dt><dd>The following bytes are a list of N elements. Lists may be nested,

</p>

<dl>

<dd>The following bytes are a list of N elements. Lists may be nested,

and a child list counts as only one element to its parent (regardless

of how many elements the child list contains). </dd><dt>Integer -- 0x81</dt><dd>The value of this element is the positive integer N. Following bytes are not part of this element. Integers can have values of 0 <= N <= 2147483647.</dd><dt>String -- 0x82</dt><dd>The following N bytes are a string element.</dd><dt>Negative Integer -- 0x83</dt><dd>The value of this element is the integer N * -1, i.e. -N. Following bytes are not part of this element. Negative integers can have values of 0 >= -N >= -2147483648.</dd><dt>Float - 0x84</dt><dd>The next 8 bytes are the float encoded in IEEE 754 floating-point <q>double format</q> bit layout.

of how many elements the child list contains). </dd>

<dt>Integer -- 0x81</dt>

<dd>The value of this element is the positive integer N. Following bytes are not part of this element. Integers can have values of 0 <= N <= 2147483647.</dd>

<dt>String -- 0x82</dt>

<dd>The following N bytes are a string element.</dd>

<dt>Negative Integer -- 0x83</dt>

<dd>The value of this element is the integer N * -1, i.e. -N. Following bytes are not part of this element. Negative integers can have values of 0 >= -N >= -2147483648.</dd>

<dt>Float - 0x84</dt>

<dd>The next 8 bytes are the float encoded in IEEE 754 floating-point <q>double format</q> bit layout.

No length bytes should have been defined.

</dd><dt>Large Integer -- 0x85</dt><dd>The value of this element is the positive large integer N. Following bytes are not part of this element. Large integers have no size limitation.</dd><dt>Large Negative Integer -- 0x86</dt><dd>The value of this element is the negative large integer -N. Following bytes are not part of this element. Large integers have no size limitation.</dd></dl><p>

</dd>

<dt>Large Integer -- 0x85</dt>

<dd>The value of this element is the positive large integer N. Following bytes are not part of this element. Large integers have no size limitation.</dd>

<dt>Large Negative Integer -- 0x86</dt>

<dd>The value of this element is the negative large integer -N. Following bytes are not part of this element. Large integers have no size limitation.</dd>

</dl>

<p>

Large integers are intended for arbitary length integers. Regular integers types (positive and negative) are limited to 32-bit values.

</p><h3>Examples<a name="auto3"></a></h3><p>

</p>

<h3>Examples<a name="auto3"/></h3>

<p>

Here are some examples of elements and their encodings - the type bytes are marked in bold:

</p><dl><dt><code>1</code></dt><dd><code>0x01 <strong>0x81</strong></code></dd><dt><code>-1</code></dt><dd><code>0x01 <strong>0x83</strong></code></dd><dt><code>1.5</code></dt><dd><code><strong>0x84</strong> 0x3f 0xf8 0x00 0x00 0x00 0x00 0x00 0x00</code></dd><dt><code>"hello"</code></dt><dd><code>0x05 <strong>0x82</strong> 0x68 0x65 0x6c 0x6c 0x6f</code></dd><dt><code>[]</code></dt><dd><code>0x00 <strong>0x80</strong></code></dd><dt><code>[1, 23]</code></dt><dd><code>0x02 <strong>0x80</strong> 0x01 <strong>0x81</strong> 0x17 <strong>0x81</strong></code></dd><dt><code>123456789123456789</code></dt><dd><code>0x15 0x3e 0x41 0x66 0x3a 0x69 0x26 0x5b 0x01 <strong>0x85</strong></code></dd><dt><code>[1, ["hello"]]</code></dt><dd><code>0x02 <strong>0x80</strong> 0x01 <strong>0x81</strong> 0x01 <strong>0x80</strong> 0x05 <strong>0x82</strong> 0x68 0x65 0x6c 0x6c 0x6f</code></dd></dl><h2>Profiles<a name="auto4"></a></h2><p>

</p>

<dl>

<dt><code>"hello"</code></dt>

100

101

102

<dt><code>[1, ["hello"]]</code></dt>

103

104

</dl>

105

106

<h2>Profiles<a name="auto4"/></h2>

107

108

<p>

109

The Banana protocol is extendable. Therefore, it supports the concept of profiles. Profiles allow

110

developers to extend the banana protocol, adding new element types, while still keeping backwards

111

compatability with implementations that don't support the extensions. The profile used in each

112

session is determined at the handshake stage (see below.)

</p><p>

113

</p>

114

115

<p>

116

A profile is specified by a unique string. This specification defines two profiles

117

- <code>"none"</code> and <code>"pb"</code>. The <code>"none"</code> profile is the standard

118

profile that should be supported by all Banana implementations.

119

Additional profiles may be added in the future.

</p><h3>The <code>"none"</code> Profile<a name="auto5"></a></h3><p>

120

</p>

121

122

<h3>The <code>"none"</code> Profile<a name="auto5"/></h3>

123

124

<p>

125

The <code>"none"</code> profile is identical to the delimiter types listed above. It is highly recommended

126

that all Banana clients and servers support the <code>"none"</code> profile.

</p><h3>The <code>"pb"</code> Profile<a name="auto6"></a></h3><p>

127

</p>

128

129

<h3>The <code>"pb"</code> Profile<a name="auto6"/></h3>

130

131

<p>

132

The <code>"pb"</code> profile is intended for use with the Perspective Broker protocol, that runs on top

133

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:

</p><dl><dt>0x01</dt><dd>'None'</dd><dt>0x02</dt><dd>'class'</dd><dt>0x03</dt><dd>'dereference'</dd><dt>0x04</dt><dd>'reference'</dd><dt>0x05</dt><dd>'dictionary'</dd><dt>0x06</dt><dd>'function'</dd><dt>0x07</dt><dd>'instance'</dd><dt>0x08</dt><dd>'list'</dd><dt>0x09</dt><dd>'module'</dd><dt>0x0a</dt><dd>'persistent'</dd><dt>0x0b</dt><dd>'tuple'</dd><dt>0x0c</dt><dd>'unpersistable'</dd><dt>0x0d</dt><dd>'copy'</dd><dt>0x0e</dt><dd>'cache'</dd><dt>0x0f</dt><dd>'cached'</dd><dt>0x10</dt><dd>'remote'</dd><dt>0x11</dt><dd>'local'</dd><dt>0x12</dt><dd>'lcache'</dd><dt>0x13</dt><dd>'version'</dd><dt>0x14</dt><dd>'login'</dd><dt>0x15</dt><dd>'password'</dd><dt>0x16</dt><dd>'challenge'</dd><dt>0x17</dt><dd>'logged_in'</dd><dt>0x18</dt><dd>'not_logged_in'</dd><dt>0x19</dt><dd>'cachemessage'</dd><dt>0x1a</dt><dd>'message'</dd><dt>0x1b</dt><dd>'answer'</dd><dt>0x1c</dt><dd>'error'</dd><dt>0x1d</dt><dd>'decref'</dd><dt>0x1e</dt><dd>'decache'</dd><dt>0x1f</dt><dd>'uncache'</dd></dl><h2>Protocol Handshake and Behaviour<a name="auto7"></a></h2><p>

134

minimizing bandwidth usage. It starts with a single byte, which tells us to which string element

135

to convert it, and ends with the delimiter byte, <code>0x87</code>, which should not be prefixed

136

by a length.

137

</p>

138

139

<dl>

140

141

<dt>0x02</dt> <dd>'class'</dd>

142

<dt>0x03</dt> <dd>'dereference'</dd>

143

<dt>0x04</dt> <dd>'reference'</dd>

144

<dt>0x05</dt> <dd>'dictionary'</dd>

145

<dt>0x06</dt> <dd>'function'</dd>

146

<dt>0x07</dt> <dd>'instance'</dd>

147

148

<dt>0x09</dt> <dd>'module'</dd>

149

<dt>0x0a</dt> <dd>'persistent'</dd>

150

<dt>0x0b</dt> <dd>'tuple'</dd>

151

<dt>0x0c</dt> <dd>'unpersistable'</dd>

152

153

<dt>0x0e</dt> <dd>'cache'</dd>

154

<dt>0x0f</dt> <dd>'cached'</dd>

155

<dt>0x10</dt> <dd>'remote'</dd>

156

<dt>0x11</dt> <dd>'local'</dd>

157

<dt>0x12</dt> <dd>'lcache'</dd>

158

<dt>0x13</dt> <dd>'version'</dd>

159

<dt>0x14</dt> <dd>'login'</dd>

160

<dt>0x15</dt> <dd>'password'</dd>

161

<dt>0x16</dt> <dd>'challenge'</dd>

162

<dt>0x17</dt> <dd>'logged_in'</dd>

163

<dt>0x18</dt> <dd>'not_logged_in'</dd>

164

<dt>0x19</dt> <dd>'cachemessage'</dd>

165

<dt>0x1a</dt> <dd>'message'</dd>

166

<dt>0x1b</dt> <dd>'answer'</dd>

167

<dt>0x1c</dt> <dd>'error'</dd>

168

<dt>0x1d</dt> <dd>'decref'</dd>

169

<dt>0x1e</dt> <dd>'decache'</dd>

170

<dt>0x1f</dt> <dd>'uncache'</dd>

171

</dl>

172

173

<h2>Protocol Handshake and Behaviour<a name="auto7"/></h2>

174

175

<p>

176

The initiating side of the connection will be referred to as <q>client</q>, and the other

177

side as <q>server</q>.

</p><p>

178

</p>

179

180

<p>

181

Upon connection, the server will send the client a list of string elements, signifying

182

the profiles it supports. It is recommended that <code>"none"</code> be included in this list. The client

183

then sends the server a string from this list, telling the server which profile it wants to

184

use. At this point the whole session will use this profile.

</p><p>

185

</p>

186

187

<p>

188

Once a profile has been established, the two sides may start exchanging elements. There is no

189

limitation on order or dependencies of messages. Any such limitation (e.g. <q>server can only

190

send an element to client in response to a request from client</q>) is application specific.

</p><p>

191

</p>

192

193

<p>

194

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

195

close its connection.

</p></div><p><a href="../howto/index.html">Index</a></p><span class="version">Version: 8.2.0</span></body></html>

b'\\ No newline at end of file'

196

</p>

197

198

</div>

199

200

<p><a href="../howto/index.html">Index</a></p>

201

<span class="version">Version: 9.0.0</span>

202

</body>

203

</html>

b'\\ No newline at end of file'

Older »