git.maemo.org Git - xmlrpc-c/blob - tools/binmode-rpc-kit/binmode-rpc-rfc.txt

   1 This is a draft, and subject to change. Please do not implement it
   2 yet. Thank you!
   3
   4 Examples can be found at the bottom of the file.
   5
   6 Thank you for your feedback!
   7
   8 Eric Kidd
   9 eric.kidd@pobox.com
  10 30 January 2001
  11
  12
  13 The Binmode RPC Protocol
  14 ========================
  15
  16 Binmode RPC is an ultra-lightweight RPC protocol designed for 100%
  17 compatibility with XML-RPC <http://www.xmlrpc.com/>. It emphasizes
  18 simplicity, dynamically-typed data, and extreme ease of implementation.
  19
  20 Two XML-RPC implementations that support 'binmode-rpc' may negotiate away
  21 the XML part of XML-RPC, and replace it with a simple binary protocol.
  22
  23 Design goals:
  24
  25   * The complete specification should fit in a 350-line text file. :-)
  26   * The protocol should be easy to implement.
  27   * The protocol should provide a high degree of compression.
  28   * The protocol should be very fast--faster than zlib compression.
  29   * The protocol must be implementable in portable ANSI C, with no
  30     './configure' checks.
  31   * The protocol must not contain any options, variant encodings
  32     or similar hair. If you want DCE/RPC, you know where to find it.
  33   * All protocol operations must be performed at the byte level
  34     (except for UTF-8 encoding and decoding).
  35   * The protocol must be semi-readable in a hex dump or Emacs buffer.
  36   * The protocol must efficiently encode boxcarred calls that are
  37     implemented using 'system.multicall'.
  38   * The protocol must support an efficient encoding for
  39     frequently-repeated string values.
  40
  41   * The protocol must never be sent to clients or servers which
  42     don't support it.
  43   * There must be a way for clients and servers to active the protocol
  44     if both ends of the connection support it.
  45
  46
  47 The X-XML-RPC-Extensions Header
  48 -------------------------------
  49
  50 (First, we'll need a mechanism for unobtrusively announcing the presence of
  51 non-standard capabilities.)
  52
  53 An XML-RPC implementation MAY advertise additional, non-standard
  54 capabilities using the 'X-XML-RPC-Extensions' header.
  55
  56 Rationale: The 'X-XML-RPC-Extensions' header should be available to CGI
  57 scripts in the environment variable HTTP_X_XML_RPC_EXTENSIONS.
  58
  59 If present, this header MUST contain a comma-separated list of
  60 keywords. Parameter information MAY be included, if desired, in the
  61 standard fashion used by HTTP 1.1 'Accept-Encoding' headers.
  62
  63   X-XML-RPC-Extensions: binmode-rpc
  64   X-XML-RPC-Extensions: binmode-rpc, x-telepathic-transport
  65   X-XML-RPC-Extensions: binmode-rpc,x-telepathic-transport
  66   X-XML-RPC-Extensions: binmode-rpc, x-telepathic-transport;speed=low
  67
  68 If a client sends the X-XML-RPC-Extensions header in a request, the server
  69 MAY use any of the specified extensions in its response.
  70
  71 Rationale: No client may be sent non-standard data without first having
  72 advertised the ability to accept it.
  73
  74 If the server includes the X-XML-RPC-Extensions header in a response, the
  75 client MAY use any of the specified extensions in further requests to that
  76 URL. The client MUST NOT assume that the same extensions are available for
  77 any other URL on the same server.
  78
  79 Rationale: No server may be sent non-standard data without first having
  80 advertised the ability to accept it. Furthermore, this permission is
  81 URL-specific, since different XML-RPC implementations may be located at
  82 different URLs on a single server.
  83
  84 The client SHOULD NOT cache extension information about a particular server
  85 for an excessive length of time (typically beyond a single program
  86 invocation). If the client does cache this information indefinitely, it
  87 SHOULD be able to cope if an extension is disabled.
  88
  89 Rationale: The XML-RPC implementation used on the server may be changed by
  90 the administrator.
  91
  92
  93 The 'binmode-rpc' Extension
  94 -----------------------
  95
  96 A client or server which sends the 'binmode-rpc' extension MUST accept
  97 message bodies of type 'application/x-binmode-rpc' in addition to the
  98 regular 'text/xml'.
  99
 100 All servers which accept the binmode-rpc extension MUST also support
 101 standard XML-RPC, as described by <http://www.xmlrpc.org/spec>.
 102
 103
 104 The 'application/x-binmode-rpc' Format
 105 --------------------------------------
 106
 107 All documents of the type 'application/x-binmode-rpc' MUST begin with the
 108 following byte sequence (represented here as a C string):
 109
 110   'binmode-rpc:'
 111
 112 This MUST be followed by a Call or a Response, encoded as described below:
 113
 114   Call := 'C' String Array
 115
 116 A Call consists of a single octet with the ASCII value 'C', followed by a
 117 String containing the method name and an Array containing the parameters.
 118
 119   Response := 'R' (Value|Fault)
 120
 121 A Response MUST contain either a Value or a Fault.
 122
 123   Fault := 'F' Struct
 124
 125 A Fault contains a regular Struct (with members as specified by the the
 126 XML-RPC specification).
 127
 128 Trailing data at the end of an 'application/x-binmode-rpc' document MUST be
 129 ignored.
 130
 131
 132 Byte-Order of Integers
 133 ----------------------
 134
 135 (The following integer types don't correspond directly to XML-RPC
 136 integers--instead, they'll be used to *build* more complicated types.)
 137
 138   SignedLSB := a four-octet, signed, twos'-complement integer,
 139                least-significant byte (LSB) first
 140   UnsignedLSB := a four-octet, unsigned integer, LSB first
 141
 142 Raw integer data is encoded in little-endian format.
 143
 144 Rationale: A fixed, mandatory byte ordering is easier to implement than
 145 approaches which allow multiple byte orderings, and little-endian CPUs
 146 outnumber big-endian CPUs at the time of writing.
 147
 148
 149 Values
 150 ------
 151
 152   Value := (Integer|Boolean|Double|DateTimeISO8601Binary|Array|Struct|
 153             String|Other)
 154
 155   Integer := 'I' SignedLSB
 156   Boolean := ('t'|'f')
 157
 158   Double := 'D' SizeOctet AsciiChar...
 159   DateTimeISO8601 := '8' SizeOctet AsciiChar...
 160
 161 These two types are encoded with an unsigned size octet followed by the
 162 specified number of ASCII characters. The values are encoded in the fashion
 163 described by the XML-RPC specification.
 164
 165 Rationale: In both these cases, we're punting. Binary floating point
 166 formats are highly non-portable, and cannot be easily manipulated by most
 167 programming languages. XML-RPC <dateTime.iso8601> values lack timezone
 168 information, and are therefore difficult to convert to a binary format.
 169
 170   Binary := 'B' UnsignedLSB Octet...
 171
 172 This corresponds to the XML-RPC <base64> type, but without any encoding.
 173 The UnsignedLSB specifies the number of octets of data.
 174
 175   Array := 'A' UnsignedLSB Value...
 176
 177 The UnsignedLSB specifies the number of values in the array.
 178
 179   Struct := 'S' UnsignedLSB (String,Value)...
 180
 181 The UnsignedLSB specifies the number of String,Value pairs in the struct.
 182 The strings are keys; the values may be of any type.
 183
 184   Other := 'O' String Binary
 185
 186 Future XML-RPC types (if any) may be sent a String containing the type name
 187 and a Binary block (as above) containing type-specific data.
 188 Implementations MUST NOT encode any of the standard types using this
 189 construct. Implementations MAY signal an error if data of type Other is
 190 encountered.
 191
 192 Rationale: This is allowed to cause an error because most applications
 193 won't understand the contents anyway. But if new types are added, dumb
 194 gateways will be able to manipulate them in encapsulated format (if they so
 195 desire).
 196
 197
 198 Strings
 199 -------
 200
 201   String := (RegularString|RecordedString|RecalledString)
 202
 203 We have three types of strings.
 204
 205   RegularString := 'U' StringData
 206   StringData := UnsignedLSB Utf8Octet...
 207
 208 Strings are encoded in UTF-8 format. The UnsignedLSB specifies the number
 209 of UTF-8 octets. Implementations SHOULD raise an error if they encounter
 210 invalid UTF-8 data (e.g., ISO Latin 1 characters).
 211
 212 Rationale: Technically speaking, XML-RPC is limited to plain ASCII
 213 characters, and may not contain 8-bit or 16-bit characters in any coding
 214 system. But since XML-RPC is based on XML, adding Unicode is a trivial
 215 enhancement to the basic protocol, and *somebody* will make it sooner or
 216 later. When that day arrives, we want to be able to encode Unicode
 217 characters.
 218
 219 Implements MUST encode UTF-8 characters using the minimum number of octets.
 220 Implementations SHOULD raise an error if they encounter any UTF-8
 221 characters encoded using more than the minimum number of octets.
 222
 223 Rationale: Overlong UTF-8 encodings are sometimes used to bypass string
 224 validation in security code. They serve no legitimate purpose, either. So
 225 to improve the overall security of the Universe, we work hard to discourage
 226 them.
 227
 228 UTF-8 & Unicode FAQ: http://www.cl.cam.ac.uk/~mgk25/unicode.html
 229
 230   RecordedString := '>' CodebookPosition StringData
 231   RecalledString := '<' CodebookPosition
 232   CodebookPosition := UnsignedOctet
 233
 234 The 'binmode' format supports a 256-entry "codebook" of strings. At the
 235 start of a data stream, the codebook is empty. When the decoder
 236 encounters a RecordedString, it MUST store it into the specified codebook
 237 position (and then proceed to decode it as a regular string).
 238
 239 When the decoder encounters a RecalledString, it MUST look it up in the
 240 specified codebook position. If that codebook position has been set, the
 241 implementation MUST use the string value found in the codebook. If the
 242 position has not been set, the implementation MUST stop decoding and raise
 243 an error. It is legal to change a codebook position once it has been set;
 244 the most recent value applies.
 245
 246 A RecordedString or a RecalledString may be used anywhere a RegularString
 247 may be used.
 248
 249 Rationale: XML-RPC data tends to contain large numbers of identical
 250 strings. (These are typically the names of <struct> members or the names of
 251 methods in a multicall.) To get any kind of reasonable data compression,
 252 it's necessary to have some way of compressing these values. The codebook
 253 mechanism is relatively simple and uncomplicated.
 254
 255 Implementations MAY choose not to use this feature when encoding data, but
 256 MUST understand it when decoding data.
 257
 258 Rationale: On the decoding end of things, this feature is trivial to
 259 implement, and must be present for the sake of interoperability. On the
 260 encoding end of things, however, making effective use of this feature is
 261 slightly trickier, so implementations are allowed (but not encouraged) to
 262 omit it.
 263
 264
 265 Compliance
 266 ----------
 267
 268 Implementations MUST implement all features of this protocol correctly,
 269 particularly on the decoding end. In the case of this protocol, a 95% correct
 270 implementation is 100% broken. Yes, this statement is redundant. ;-)
 271
 272
 273 Examples
 274 --------
 275
 276 Non-ASCII octets are specified as in C strings. Continued lines are
 277 indicated by a trailing '\'; these should be joined together as one
 278 sequence of bytes.
 279
 280 binmode-rpc:CU\003\0\0\0addA\002\0\0\0I\002\0\0\0I\002\0\0\0
 281
 282 binmode-rpc:RI\004\0\0\0
 283
 284 binmode-rpc:RFS\002\0\0\0 \
 285 U\011\0\0\0faultCodeI\001\0\0\0 \
 286 U\013\0\0\0faultStringU\021\0\0\0An error occurred
 287
 288 binmode-rpc:RA\006\0\0\0 \
 289 >\000\003\0\0\0foo \
 290 >\001\003\0\0\0bar \
 291 <\000 \
 292 >\000\003\0\0\0baz \
 293 <\000 \
 294 <\001
 295
 296 (This deserializes to ['foo', 'bar', 'foo', 'baz', 'baz', 'bar'].)
 297
 298 binmode-rpc:RU\042\0\0\0Copyright \302\251 1995 J. Random Hacker
 299
 300 (This is based on an example in the Unicode/UTF-8 FAQ (see above).)
 301
 302 binmode-rpc:RA\010\0\0\0 \
 303 I\006\0\0\0 \
 304 tf \
 305 D\0042.75 \
 306 8\02119980717T14:08:55 \
 307 U\003\0\0\0foo \
 308 B\003\0\0\0abc \
 309 S\002\0\0\0U\003\0\0\0runt
 310
 311 Counter-Examples
 312 ----------------
 313
 314 The following specimens are illegal, and SHOULD be rejected by a compliant
 315 implementation. Please test your code.
 316
 317 * A different format name:
 318
 319   binmode-rpc2:RI\004\0\0\0
 320
 321 * A built-in type incorrectly encoded using 'O':
 322
 323   binmode-rpc:ROU\006\0\0\0stringB\003\0\0\0xyz
 324
 325 * A recall of an unrecorded string:
 326
 327   binmode-rpc:R<\002
 328
 329 * ISO Latin 1 data in a string. (UTF-8 required!)
 330
 331   binmode-rpc:RU\041\0\0\0Copyright \251 1995 J. Random Hacker
 332
 333 * UTF-8 character encoded with too many octets (based on an example in the
 334   Unicode/UTF-8 FAQ):
 335
 336   binmode-rpc:RU\041\0\0\0Bad linefeed: \300\212 (too many bytes)
 337
 338 A compliant implementation MUST NOT send any of these sequences.