From b2fb12ae41627cf250c07b5eaed6cbd6fb4c04d5 2013-07-24 18:20:29
From: MinRK <benjaminrk@gmail.com>
Date: 2013-07-24 18:20:29
Subject: [PATCH] document the wire protocol
---

diff --git a/docs/source/development/messaging.txt b/docs/source/development/messaging.txt
index f95a514..96bb47b 100644
--- a/docs/source/development/messaging.txt
+++ b/docs/source/development/messaging.txt
@@ -110,7 +110,69 @@ A message is defined by the following four-dictionary structure::
       'metadata' : dict,
     }
 
-   
+The Wire Protocol
+=================
+
+This message format exists at a high level,
+but does not describe the actual *implementation* at the wire level in zeromq.
+The canonical implementation of the message spec is our :class:`~IPython.kernel.zmq.session.Session` class.
+Every message is serialized to a sequence of at least six blobs of bytes:
+
+.. sourcecode:: python
+
+    [
+      b'u-u-i-d',         # zmq identity(ies)
+      b'<IDS|MSG>',       # delimiter
+      b'baddad42',        # HMAC signature
+      b'{header}',        # serialized header dict
+      b'{parent_header}', # serialized parent header dict
+      b'{metadata}',      # serialized metadata dict
+      b'{content},        # serialized content dict
+      b'blob',            # extra raw data buffer(s)
+      ...
+    ]
+
+The front of the message is the ZeroMQ routing prefix,
+which can be zero or more socket identities.
+This is every piece of the message prior to the delimiter key ``<IDS|MSG>``.
+In the case of IOPub, there should be just one prefix,
+which is the topic for IOPub subscribers, e.g. ``stdout``, ``stderr``, ``pyout``.
+
+.. note::
+
+    In most cases, the IOPub topics are irrelevant and completely ignored,
+    because frontends just subscribe to all topics.
+
+After the delimiter is the `HMAC`_ signature of the message, used for authentication.
+If authentication is disabled, this should be an empty string.
+By default, the hashing function used for computing these signatures is sha256.
+
+.. _HMAC: http://en.wikipedia.org/wiki/HMAC
+
+.. note::
+
+    To disable authentication and signature checking,
+    set the `key` field of a connection file to an empty string.
+
+The signature is generated by computing the HMAC digest of the concatenation of:
+
+- A shared key (from the ``key`` field of a connection file)
+- The serialized header dict
+- The serialized parent header dict
+- The serialized metadata dict
+- The serialized content dict
+
+After the signature is the actual message, always in four byte sequences.
+The four dictionaries that compose a message are serialized separately,
+in the order of header, parent header, metadata, and content.
+These can be serialized by any function that turns a dict into bytes.
+The default and most common serialization is JSON, but msgpack and pickle
+are common alternatives.
+
+After the serialized dicts are zero to many raw data buffers,
+which can be used by message types that support binary data (mainly apply and data_pub).
+
+
 Python functional API
 =====================